infoscreen-dev/.github/copilot-instructions.md

Copilot Instructions - Infoscreen Client

Purpose

This file defines durable, high-signal instructions for AI assistants working in this repository.

Instruction File Design Rules

Treat this file as policy, not as project handbook.

• Scope rule: keep only durable constraints, architectural invariants, and high-value task pointers for assistants.
• Size rule: target 80-140 lines; hard cap 180 lines.
• Canonical-doc rule: link to specialist docs for operational depth instead of copying their content.
• Single-source rule: each topic has one canonical document; this file should only reference it.
• No shadow-README rule: do not add long setup guides, full command catalogs, troubleshooting playbooks, or large directory trees.

Allowed content:

• Critical do/don't rules.
• Short architecture snapshot.
• Runtime coordination file map.
• Minimal task pointers to key methods.
• Documentation policy for where detailed content belongs.

Disallowed content:

• Comprehensive installation/deployment tutorials.
• Large environment-variable reference sections.
• Extended troubleshooting matrices.
• Repeated feature deep-dives already documented elsewhere.
• Historical release notes (keep those in CHANGELOG.md).

Update checklist for contributors:

1. Is the new text a durable assistant rule or invariant?
2. If it is operational detail, did you place it in the specialist doc and only link it here?
3. Did you avoid duplicating existing docs?
4. Does this file remain below the hard cap?

Use specialist docs for deep operational details:

• README.md (landing page + docs map)
• TV_POWER_RUNBOOK.md (TV power rollout and canary)
• TV_POWER_INTENT_SERVER_CONTRACT_V1.md (frozen contract)
• IMPRESSIVE_INTEGRATION.md (presentation behavior)
• HDMI_CEC_SETUP.md (CEC setup/troubleshooting)
• SCREENSHOT_MQTT_FIX.md (screenshot race-condition fixes)
• src/README.md (developer-focused architecture/debugging)
• SERVER_TEAM_ACTIONS.md (server-side integration action items)

Critical Rules

• ALWAYS use Impressive for PDF presentations.
• NEVER suggest xdotool-based slideshow control.
• NEVER suggest converting presentations to video as a workaround.
• Virtual environment must include pygame and pillow for Impressive.
• Keep screenshot consent notice in docs when describing dashboard screenshots.
• Keep screenshot updates consistent between latest.jpg and meta.json.
• Event-trigger screenshots must preserve metadata and send quickly (send_immediately=true).
• Dashboard payload must stay grouped v2 (message/content/runtime/metadata, schema_version="2.0").
• Dashboard payload assembly is centralized in _build_dashboard_payload().
• Root README.md is a landing page; do not re-expand it into a full manual.
• TV power rollout guidance lives in TV_POWER_RUNBOOK.md.
• TV power contract truth lives in TV_POWER_INTENT_SERVER_CONTRACT_V1.md.
• MQTT_USER/MQTT_PASSWORD_BROKER are broker login credentials; MQTT_USERNAME/MQTT_PASSWORD are legacy identity fields. Never confuse the two.

Architecture Snapshot

Two-process design:

• src/simclient.py: MQTT communication, discovery, group assignment, event intake, heartbeat, dashboard publish, power intent ingestion, remote command intake.
• src/display_manager.py: content display lifecycle, HDMI-CEC, screenshot capture, runtime process health.

Runtime coordination files:

• src/current_event.json (active event)
• src/current_process_health.json (health bridge)
• src/power_intent_state.json (simclient -> display_manager)
• src/power_state.json (display_manager -> simclient -> MQTT)
• src/screenshots/meta.json and src/screenshots/latest.jpg

TV Power Coordination Rules

• POWER_CONTROL_MODE supports: local, hybrid, mqtt.
• Phase 1 intent topic is group-scoped: infoscreen/groups/{group_id}/power/intent.
• In hybrid mode, valid fresh MQTT intent is preferred with local fallback behavior.
• Retained clear is an empty payload and should be handled cleanly (not as broken JSON).
• Use scripts/test-power-intent.sh for ON/OFF, stale, malformed, retained-clear, and telemetry checks.

HDMI-CEC Rules

• In ENV=development, display manager automatically disables CEC.
• scripts/test-hdmi-cec.sh integration path respects development mode; manual CEC options still work.
• Keep delayed turn-off behavior safe across adjacent events.

Screenshot System Rules

• Capture is performed by display_manager.py; transmission by simclient.py.
• Keep event-trigger screenshot behavior intact (event_start / event_stop).
• Maintain one-second responsiveness for triggered send handling.
• Prefer latest.jpg for dashboard transmission, with safe fallback to newest timestamped file.

Common Task Pointers

• Add event type: src/display_manager.py -> start_display_for_event()
• Presentation behavior: src/display_manager.py -> start_presentation()
• Power intent validation: src/simclient.py -> validate_power_intent_payload()
• Power intent application: src/display_manager.py -> _apply_mqtt_power_intent()
• Screenshot capture logic: src/display_manager.py -> _capture_screenshot()
• Dashboard payload: src/simclient.py -> _build_dashboard_payload()
• Remote command intake: src/simclient.py -> on_command_message()
• Command validation: src/simclient.py -> validate_command_payload()
• File URL rewriting: src/simclient.py -> resolve_file_url()

Documentation Policy

When updating docs:

• Keep README.md concise and link-heavy.
• Put rollout/runbook content into specialist docs (for example TV_POWER_RUNBOOK.md).
• Keep implementation history in CHANGELOG.md.
• Prefer updating one canonical doc per topic instead of duplicating the same content in multiple files.

Assistant Workflow Expectations

• Prefer minimal, targeted changes.
• Preserve existing behavior unless explicitly changing it.
• Validate changes with relevant scripts/log checks where possible.
• Keep references and examples aligned with current files and topics.