date	2026-06-20
owner	chris
status	active
role-label	chris

energy-proxy

Home energy monitoring and ComEd-RTP-aware HVAC cost optimization running as a Docker Compose stack on Pi-lab. Single ComEd Hourly Pricing household; IECC climate zone 5A; Amana CTK04AE thermostat on a 2-stage AC + modulating furnace.

The controller

Two control approaches — retained for a 2027 cost-savings comparison:

• Arm A — the CTK04AE's internal programmed schedule runs autonomously.
• Arm B — Arm A plus price awareness (the rev 4.1 spike-only controller, live in production since 2026-07-06). At normal prices the thermostat runs its own program and the controller writes nothing. During ComEd RTP spikes it pushes timed warm holds anchored on a live read of the device's current program value (elevated = program + offset; scarcity = an absolute max-house temperature), and actively releases them once two consecutive price buckets confirm cheap. Warm-only; never cools below the device's program. Safety is device-owned: setpoint min/max limits are the hard cap, and the timed-hold TTL reverts the device to its own schedule if the controller dies — the safety net and the release path are independent mechanisms by design.

2026 status: built, validated, and running the season live. The Arm A vs Arm B cost-savings comparison is the 2027 experiment — deferred.

Controller design: docs/superpowers/specs/2026-06-20-commissioning-controller-design.md (rev 4.1, spike-only — live since 2026-07-06) Implementation plan: docs/superpowers/plans/2026-07-05-spike-only-controller-plan.md

What's in this repo

• Controller — hvac-scheduler service. Current spec/plan linked above.
• Arm apparatus — CTK04AE program (Arm A) and price-overlay controller (Arm B), retained for the 2027 comparison.
• Telemetry pipeline — Docker Compose stack of pollers + InfluxDB + Grafana + Loki, under deploy/energy-stack/. Per-service detail in docs/SERVICES.md.
• Analysis tooling — shadow-validation ops check under tools/analysis/ (run_shadow_validation.py + helpers).
• 5CP telemetry — PJM capacity-peak data collected and retained for later analysis; not a live control input.

Architecture

Diagram source: docs/diagrams/architecture.mmd (Mermaid). Re-render with npx -y @mermaid-js/mermaid-cli -i docs/diagrams/architecture.mmd -o docs/diagrams/architecture.png -t neutral -b white -w 1600 -H 1400 (SVG is also committed at the same path).

Stack runs as a single Docker Compose project. Deployment is automated: merging to main triggers a GitHub Actions workflow that joins the operator's tailnet as an ephemeral CI node and updates the stack in place. No public ingress.

Reading path

1. docs/PROJECT.md — project narrative, decisions, phase history, hardware inventory.
2. INDEX.md — canonical document map (every active doc, grouped by intent).
3. docs/superpowers/specs/2026-06-20-commissioning-controller-design.md — current controller spec.
4. deploy/energy-stack/README.md — stack ops, ports, secrets, restore.

For AI agents: AGENTS.md (local, gitignored — not in the committed repo) is the standing behavior contract for this repo. Legacy operator README archived at docs/archive/README-LEGACY.md.

License

MIT