82f43f75ba
shrink root README into a landing page with a docs map and focused contributor guidance add TV_POWER_RUNBOOK as the canonical TV power rollout and canary runbook add CHANGELOG and move project history out of README-style docs refactor src README into a developer-focused guide (architecture, runtime files, MQTT, debugging) prune redundant older HDMI docs and keep a canonical HDMI_CEC_SETUP path update copilot instructions to a high-signal policy format with strict anti-shadow-README design rules align references across docs to current files, scripts, and TV power behavior
125 lines
5.5 KiB
Markdown
125 lines
5.5 KiB
Markdown
# 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.
|