# 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)

## 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`.

## Architecture Snapshot

Two-process design:

- `src/simclient.py`: MQTT communication, discovery, group assignment, event intake, heartbeat, dashboard publish, power intent ingestion.
- `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()`
- 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.