feat(tv-power): implement server PR1 with tests and documentation

README.md

@@ -96,6 +96,40 @@ make pull-prod
 make up-prod
 ```
 
+## Scheduler Runtime Flags
+
+Scheduler runtime defaults can be tuned with environment variables:
+
+- `POLL_INTERVAL_SECONDS` (default: `30`)
+- `REFRESH_SECONDS` (default: `0`, disabled)
+
+TV power coordination (server Phase 1, group-level intent only):
+
+- `POWER_INTENT_PUBLISH_ENABLED` (default: `false`)
+- `POWER_INTENT_HEARTBEAT_ENABLED` (default: `true`)
+- `POWER_INTENT_EXPIRY_MULTIPLIER` (default: `3`)
+- `POWER_INTENT_MIN_EXPIRY_SECONDS` (default: `90`)
+
+Power intent topic contract for Phase 1:
+
+- Topic: `infoscreen/groups/{group_id}/power/intent`
+- QoS: `1`
+- Retained: `true`
+- Publish mode: transition publish + heartbeat republish each poll
+- Schema version: `v1`
+- Intent ID behavior: stable across unchanged heartbeat cycles; new UUID only on semantic transition (desired_state or reason change)
+- Expiry rule: max(3 × poll_interval, 90 seconds)
+
+Rollout strategy (Phase 1):
+
+1. Keep `POWER_INTENT_PUBLISH_ENABLED=false` by default (disabled).
+2. Enable in test environment first: set `POWER_INTENT_PUBLISH_ENABLED=true` on one canary group's scheduler instance.
+3. Verify no unintended OFF between adjacent/overlapping events over 1–2 days.
+4. Expand to 20% of production groups for 2 days (canary soak).
+5. Monitor power-intent publish metrics (success rate, error rate, transition frequency) in scheduler logs.
+6. Roll out to 100% once canary is stable (zero off-between-adjacent-events incidents).
+7. Phase 2 (future): per-client override intents and state acknowledgments.
+
 ## Documentation Map
 
 ### Deployment