smart-thermostat-with-vents

Recreate the Plenum (smart-thermostat-with-vents) development environment from scratch: prerequisites, backend pip install, frontend npm install/build, .env setup, VS Code launch configs, Docker image build, docker-compose test stack anatomy, and local E2E/Playwright setup. Load when setting up a fresh clone, when an install/build/test command fails with missing deps or wrong versions, when Vite/dev-server ports or proxies misbehave, or when you need to know where a build artifact or the SQLite DB lives. Do NOT load for actually running/operating the app (plenum-run-and-operate) or for CI workflow internals (plenum-ci-and-release).

Load this BEFORE making any change to the Plenum repo (smart-thermostat-with-vents) — adding a temperature field, config option, endpoint, dependency, UI change, or engine/safety-guard edit — or before opening/reviewing/merging a PR or cutting a release. Explains how changes are classified, which CI gates each class must clear, what evidence a reviewer expects, the non-negotiable rules with the historical incident behind each, and the release/branch-protection flow.

The CI/CD machine of Plenum (smart-thermostat-with-vents): every GitHub Actions workflow job-by-job, container-ci's three build modes (normal PR / release PR / fork PR) and the PLENUM_IMAGE handoff, the visual-regression golden-screenshot machinery (parallel F/C legs, update-then-verify, fan-in auto-commit bot), the tag→release-PR→publish release flow, branch protection, the failure-triage table for red checks, and the nightly ci-image cleanup. Load when a CI check fails, when a bot pushed "ci: update E2E golden screenshots" onto your branch, when cutting or validating a release, or when editing anything under .github/workflows/.

The chronicle of every settled battle in Plenum (smart-thermostat-with-vents) — major investigations, dead ends, rejected approaches, and reverts, each as symptom → root cause → evidence → fix → status. Load when you suspect a bug was seen before, when someone proposes re-fixing or weakening something (deadband in at-target, frontend toStorage on payloads, default-mapped MCP port, per-selector screenshot masks), when you need the incident behind a guard/test name, or before filing an issue that might duplicate #26–#369 history. NOT for live triage of a new symptom (use plenum-debugging-playbook) or for the invariant statements themselves (plenum-architecture-contract).

Executable, decision-gated campaign plan for Plenum issue #373 — adding authentication to the web UI (port 8099) and the MCP server (port 9099), which are BOTH unauthenticated today and rely entirely on Home Assistant ingress in front. Load when working on #373, when asked to design or implement auth/login/OAuth/bearer tokens/sessions for Plenum, when reasoning about ingress-vs-direct-port trust, MCP OAuth 2.1 authorization, or when someone proposes gating access by port number or trusting X-Ingress headers. This is a CANDIDATE plan, not decreed scope — the owner has not chosen an approach. NOT for general change-gating (load plenum-change-control) or the shipped MCP transport internals (plenum-architecture-contract).

The load-bearing design decisions of Plenum (smart-thermostat-with-vents), the invariants that must hold, WHY each exists, and the known-weak points. Load when you need the canonical temperature-unit contract (°F storage, single write boundary, #231), the component map with real file paths, the cycle-engine invariants (mode lock, in-place trigger updates, 60s tick), the MCP loopback design, or a "before you change X, understand Y" dependency check. Also load when CLAUDE.md prose seems to disagree with the repo — this skill flags the known drift.

Symptom-to-triage playbook for Plenum (smart-thermostat-with-vents). Load when something is behaving wrong at runtime and you need to find the cause fast — temperatures off by ~×1.8 or ~30°, cycles that never end or end early, vents thrashing or stuck open/closed, a zone the engine silently stopped controlling, timestamps shifted by hours, duplicated/zombie live-feed rows, HA entity or cover-service failures, wrong heat/cool mode or oscillation, or one of the three classic CI failures (golden-screenshot diff, TEMPERATURE_FIELDS parity, coverage gate). Gives ranked causes, the exact discriminating command/query/log line, and the issue precedent for each.

How to maintain Plenum's documents of record (README.md, DESIGN.md, CLAUDE.md, docs/*.md, CHANGELOG.md, RELEASE.md, screenshots/), the house prose style, and the external-claims discipline (test counts, coverage numbers, heat-pump non-support). Load when writing or editing any doc, refreshing the README "Tested" stats block, adding a docs/ feature page with a feature PR, amending CLAUDE.md after a hard-won lesson, or checking whether a documented number/path still matches the repo. Do NOT load for CI/release mechanics (plenum-ci-and-release) or PR gating rules (plenum-change-control).

How to run and add tests in Plenum (pytest/vitest/Playwright run commands, the --no-cov trap), what counts as evidence in the repo (smart-thermostat-with-vents), and how to add tests CI will accept. Load when running, writing, or debugging tests, when a coverage gate or parity/enforcement test fails (test_temperature_field_parity, test_addon_config, test_api_spec_enforcement), when you need the Celsius-mode test patterns, when adding an E2E round-trip with @covers tags, or when regenerating golden screenshots.

Catalog of every configuration axis in Plenum — config.yaml add-on options, run.sh/backend environment variables, system_settings DB keys, ThermostatConfig fields, per-room settings, schedule/override fields — with defaults, units, validation guards, and UI location. Load when you need to know where a setting lives, what its default/bounds are, whether a value is stored in °F or as a delta, or when adding a new knob (config option, temperature field, or system flag) and need the parity checklist.

How to MEASURE Plenum's runtime behavior instead of eyeballing it — the SQLite app.db schema with copy-pasteable diagnostic queries, the Logs page (Live Feed / Cycle History) and event-logger categories, what every Metrics chart actually computes (duty cycle, degree-minutes, overshoot histogram, time-to-target), the live-state endpoints and /ws stream, and ready-to-run scripts (cycle_report, overshoot_stats, event_tail, hvac_quality, ws_watch) for cycle reports and HVAC-quality analysis (short-cycling, oscillation, chronic overshoot, drifting rooms). Load when you need numbers, history, or evidence about what the system did.

First-principles analysis recipes for PROVING a Plenum change is correct before shipping it — unit-conversion algebra (round-trip identity, absolute-vs-delta typing), state-machine exhaustiveness tables, boundary/off-by-one inequality proofs, oscillation/hysteresis analysis, naive-vs-aware timezone audits, asyncio task-retention and reconnect-liveness proofs, and DB-invariant checks (migration idempotence, upsert column preservation). Load when a review comment says "prove it", when touching conversion/engine/trim/reconnect/migration code, or when a bug smells like an off-by-one, a missing state×event cell, or a double conversion. Each recipe has a worked example from a real closed issue with real numbers.

Open, SOTA-advancing research problems for Plenum — learned per-room thermal models, weather-aware predictive cycle planning, adaptive overshoot/deadband tuning, heat-pump shadow studies, and LLM/MCP self-explanation — each with the verified data asset behind it, the first three concrete in-repo steps, and a falsifiable numeric milestone. Load when asked "what could Plenum do that Flair/ecobee/research MPC can't", when starting an experiment on cycle-history data, or when scoping a learning/optimization feature. NOT a runbook for measuring today's behavior (plenum-diagnostics-and-tooling) or for how to run an experiment properly (plenum-research-methodology).

The discipline that turns a hunch into an accepted result in the Plenum repo — the evidence bar (one mechanism must explain every observation, hypotheses must predict numbers before you measure, adversarial refutation), the hunch→issue→sandbox-experiment→PR→docs lifecycle, how to run a systematic audit like the #280–#305 wave, experiment hygiene (both-directions tests, timezone matrix, restart-mid-state, simulated-vs-real HVAC), and a result-acceptance checklist. Load when you have a theory about a bug or a design idea and need to know what proof this project demands before it ships.

How to run and operate Plenum (smart-thermostat-with-vents) in its three modes — HA add-on, standalone Docker, local dev — and where its data lives. Load when installing/starting/restarting the add-on, wiring the docker run command, hunting for app.db on HAOS, doing backup/restore, attaching an MCP client to port 9099 (or hitting its 503), setting up a fresh instance (first-time setup order, System On/Off), or checking what happens across a restart/upgrade (migrations, unit-change banner, cycle restore, safety defaults). NOT for building from source (plenum-build-and-env) or for measuring/diagnosing a running system (plenum-diagnostics-and-tooling).

Domain theory for Plenum: HVAC physics for programmers (compressor, plenum, short-cycling, dead-heading, coil icing), zoning control theory (setpoint, deadband, overshoot, hysteresis, opposite-cycle prevention tiers), absolute vs delta °F/°C math, and the Home Assistant entity model (climate hvac_action vs hvac_mode, cover control methods, sensor unit normalization, binary_sensor presence, ingress). Load when you need to understand WHY a guard/field exists, what a domain term means, why a conversion subtracts 32 (or must not), or how Plenum reads/commands HA entities. Do NOT load for project invariants or write-boundary contracts — that is plenum-architecture-contract.