AGENTS.md

1# Open-FDD agent workspace — orientation
2 
3Plain Markdown on disk is the source of truth for **Cursor**, **Codex CLI**, and
4similar agents. Product code lives in `services/`, `sql_rules/`, `frontend/`,
5`mcp/`, `edge/`, `os/`. PyPI libraries live in `open_fdd/`. Orchestration lives in
6**`openfdd_agent_spec/`**.
7 
8**Primary agent prompt (paste into new sessions):** [`../AGENTS.md`](../AGENTS.md)
9 
10**Software-engineering mission:** [`MILESTONE_A.md`](MILESTONE_A.md)
11 
12**Ops / edge soak prompts:** [`../docs/agent/`](../docs/agent/) — GHCR bench, nightly
13retest. Do not confuse those with this engineering OS.
14 
15---
16 
17## Product vs libraries
18 
19| Layer | Owns |
20| --- | --- |
21| `services/` + `sql_rules/` + `frontend/web` | **Product:** central DataFusion SQL FDD + analytics, React SPA (`openfdd-web`), fieldbus, mqtt |
22| `open_fdd/` | **PyPI libraries** for third-party tooling: ECM + pandas oracle (`rules` / `analytics` / `reporting`) — not the product runtime |
23| `mcp/` | Optional read-first MCP → central |
24| `edge/`, `os/` | Future concepts — **never delete** |
25| `docs/rules/cookbook/` | Dual expression cookbooks (SQL + pandas) + parity matrix |
26| `tools/open-fdd-vibe21-production/` | Active recovery + Vibe 21 twin program |
27| `docs/migration/react-rust/capabilities.yaml` | Machine-readable capability ledger |
28| `openfdd_agent_spec/` | Agent law, Milestone A, skills, session log |
29| Playground vibe19/20 | External demos; consumers of PyPI |
30 
31**Naming (code truth):**
32 
33| Concept | Module / extra |
34| --- | --- |
35| Pandas oracle (PyPI) | `open_fdd.rules` (+ `open_fdd.analytics`) |
36| Pip extras | `oracle`, `analytics`, `reporting` (`vibe19` deprecated alias through 4.3) |
37| ECM math | `open_fdd.ecm_engineering` |
38| Shared contracts | `open_fdd.contracts` — Phase 2 target (not shipped) |
39 
40---
41 
42## AI agent quick rules (read first)
43 
441. Product FDD + Overview analytics = **DataFusion SQL** on GHCR. Never silent pandas fallback in central.
452. Pandas oracle stays forever on **PyPI** + cookbooks + vibe19 — never delete the pandas cookbook because production uses SQL.
463. Never delete the SQL cookbook because pandas remains the oracle.
474. **Product UI:** React SPA (`frontend/web` → `openfdd-web`, `compose.react.yml`) only. Overview = central `/api/analytics/*` (DataFusion) + client Plotly. Browser → central Rust `/api` only — **no Python in the product request path**.
485. **Internet-facing auth/UI hygiene:** Never put bench/dev secrets, credential file paths, default passwords, or JWT dumps on login or other product surfaces. Generic login errors only.
496. Test containers on **`OPENFDD_IMAGE_TAG=nightly`**, but **pin/run `sha-*`** per [`CONTAINER_AGENT.md`](CONTAINER_AGENT.md).
507. Playground images: `ghcr.io/bbartling/vibe19:develop`, `vibe20:develop` (external).
518. `edge/` and `os/` are future concepts — never delete.
529. Bounded PRs only — see [`PR_PROTOCOL.md`](PR_PROTOCOL.md).
5310. Prefer exact wheel install tests over editable-only validation for packaging PRs.
5411. Never trust a moving GHCR tag alone — resolve/pull immutable `sha-*`, recreate containers, then record the digest.
5512. Append [`SESSION_LOG.md`](SESSION_LOG.md) after non-trivial work.
5613. Update [`BUILD_CHECKPOINTS.md`](BUILD_CHECKPOINTS.md) when Milestone A or product capability status changes.
5714. CodeRabbit: fix actionable defects; reject suggestions that violate architecture.
5815. vibe21 = separate plan — not Milestone A.
5916. When blocked (secrets, permissions), finish non-blocked work and record the exact error.
6017. Bound each PR to its declared scope.
6118. **Active program:** [`tools/open-fdd-vibe21-production/`](../tools/open-fdd-vibe21-production/README.md) Master Loop. Keep [`capabilities.yaml`](../docs/migration/react-rust/capabilities.yaml) honest.
6219. For `frontend/web` work: follow [`openfdd-react-spa`](skills/openfdd-react-spa/SKILL.md).
6320. Central product image is **debian + Rust binaries only** — no Python. WattLab AFDD zip export is optional offline tooling (`OPENFDD_WATTLAB_PYTHON_EXPORT=1`).
6421. **Site lock:** Overview + sidebar Active site are the only editors of `?site=`. `SectionTabs` (and sidebar App pages) must `navigate` with `hrefWithSession` so `site` + `eq` survive. FDD / RCx / Results / WattLab show a locked `zip:BUILDING_*` caption — no Building `<Select>`.
6522. **FDD Plots = vibe19 `rule_result_chart`:** auto-load series; last y-axis title is `fault`; `confirmed_fault` is the last trace on the bottom domain (`domain[0] < 0.4`). A successful rule run with an empty overlay is a bug (fail the test), not a soft banner.
6623. **RCx catalog freeze:** every `REQUIRED_RCX_PRESET_IDS` id must stay listed. Family picker order is `RCX_FAMILY_ORDER` (Zones first) plus empty Heat pump / Weather placeholders. Auto-run the selected preset when site+preset are set.
6724. **Actions housekeeping:** default `GET /api/actions?limit=10`; `DELETE /api/actions/:id` and `DELETE /api/actions`; JSONL prune cap 50.
6825. **Section radios:** left, horizontal, **after** hero + Equipment on Overview (never inside `.oracle-hero`, never centered in the logo column). Other pages: same left radio row at the top of the page body.
6926. **Overview plot Expanders** default **open** — do not hide motor / mech / econ / BAS plot sections behind carets (`Expander` unmounts children when closed).
7027. **FDD Plots series overlay** honors Lab/`session_config` `confirm_min` (and typed rule params); source may be `sql_detail_session`. After Update-this-rule, listen for `RULES_UPDATED` and refetch results + series.
7128. **SCHED-1 portable occupancy:** numeric/boolean falsey (`0`, `0.0`, `false`) **and** string `unoccupied` (plus related tokens) — keep SQL (`sched1_unoccupied_runtime.sql`) and pandas `sched1` aligned.
7229. **Low-RAM / bensbench:** never local stack `docker build`; prune old images before pull; wait for GHCR publish then pull `sha-*` / `nightly`. Synthetic-59 soaks use `scripts/synthetic_59_*.py`; B100 dump-parity stays paused; never edit goldens to hide misses.
7330. **Plot PNG downloads:** `PlotlyHost` must pass `toImageButtonOptions.filename` (Overview/Reports). Default Plotly `newplot.png` is a regression.
7431. **Full-width UI:** `.app-content` / `.overview-populated` stretch (`max-width: none`) like Streamlit — do not reintroduce a rem content cap on Overview plots.
7532. **Rule Lab menu:** `RuleTuningPanel` sorts visible rules A–Z by `rule_id` (registry YAML order is engine priority only).
7633. **FDD Plots series roles:** `series_response` SELECT = `required_roles ∪ optional_roles` (SV-*/PID-HUNT keep required empty). Soft-empty when none present on equipment.
7734. **Mech cooling OAT bins:** status/cmd proof **before** amps (never OR amps when status exists); prefer web/`dry_bulb_f`/weather OAT over site-averaged AHU BAS `oa_t`. Version `mechanical-cooling-oat-bins-v2`.
7835. **Synthetic analytics soak:** `scripts/synthetic_59_overview_analytics_soak.py` asserts runtime + mech bin envelopes (separate from FDD pair scores).
7936. **Metric CSVs:** store as-uploaded; convert temperature roles C→F at run-rules/historian query. Do not duplicate 59 SQL files. Sliders display user units.
8037. **Package append:** `POST /api/csv/import/package/append` is the IoT hourly path (JWT + confirm). Vendor pullers are out-of-repo.
81 
82---
83 
84## Authority order
85 
861. Root [`AGENTS.md`](../AGENTS.md)
872. Machine manifests: [`ownership.yaml`](ownership.yaml), [`capabilities.yaml`](../docs/migration/react-rust/capabilities.yaml)
883. Current phase docs under [`tools/open-fdd-vibe21-production/`](../tools/open-fdd-vibe21-production/)
894. Generated OpenAPI / MCP / rule catalogs
905. Workflow guides and examples
91 
92Nested instructions may specialize but never contradict a higher authority.
93 
94## Bootstrap reading order
95 
961. [`../AGENTS.md`](../AGENTS.md)
972. This file
983. [`ARCHITECTURE.md`](ARCHITECTURE.md) + [`ownership.yaml`](ownership.yaml)
994. [`BUILD_CHECKPOINTS.md`](BUILD_CHECKPOINTS.md)
1005. [`tools/open-fdd-vibe21-production/prompts/MASTER_PRODUCTION_LOOP.md`](../tools/open-fdd-vibe21-production/prompts/MASTER_PRODUCTION_LOOP.md)
1016. [`MILESTONE_A.md`](MILESTONE_A.md) if executing Milestone A
1027. [`PR_PROTOCOL.md`](PR_PROTOCOL.md) before opening a PR
1038. Matching skill
1049. Cookbooks under `docs/rules/cookbook/`
105 
106---
107 
108## Skills
109 
110| Skill | Use when |
111| --- | --- |
112| [`openfdd-architecture`](skills/openfdd-architecture/SKILL.md) | Ownership / engine boundaries |
113| [`openfdd-react-spa`](skills/openfdd-react-spa/SKILL.md) | Product SPA (`frontend/web`) |
114| [`openfdd-sql-fdd`](skills/openfdd-sql-fdd/SKILL.md) | DataFusion SQL rules |
115| [`openfdd-pypi-oracle`](skills/openfdd-pypi-oracle/SKILL.md) | PyPI pandas oracle packaging |
116| [`openfdd-cookbook-parity`](skills/openfdd-cookbook-parity/SKILL.md) | Dual cookbook honesty |
117| [`openfdd-stack-ghcr`](skills/openfdd-stack-ghcr/SKILL.md) | GHCR pull / recreate |
118| [`openfdd-ecm-engineering`](skills/openfdd-ecm-engineering/SKILL.md) | ECM math library |
119| [`openfdd-milestone-a-pr`](skills/openfdd-milestone-a-pr/SKILL.md) | Milestone A PR loop |
120