AGENTS.md

1# Agent Guide (container stack + external agents)
2 
3Open-FDD ships as a **container stack**: `openfdd-central`, `openfdd-web` (React),
4`openfdd-fieldbus`, `openfdd-mqtt`, plus optional `openfdd-mcp`. It does **not**
5ship an embedded AI chatbot. External orchestrators — Codex CLI, Cursor,
6OpenClaw, Claude Desktop, or any MCP host — connect via **JWT REST** and optional
7**`openfdd-mcp` stdio**.
8 
9| Layer | Responsibility |
10| --- | --- |
11| **central** | MQTTS ingest, Feather/Parquet historian, DataFusion SQL FDD + `/api/analytics/*`, REST + JWT (Rust image — no Python) |
12| **web** | React product UI (`frontend/web`) — sole product UI ([ADR-001](docs/architecture/adr-001-react-rust-modernization.md)) |
13| **fieldbus** | BACnet / Modbus / Haystack OT drivers |
14| **mqtt** | Mosquitto MQTTS broker |
15| **mcp** | Optional read-first stdio tools → central (`OPENFDD_API_BASE`) |
16 
17**Docs:** [Build recipes](docs/operations/build-recipes.md) · [External agents](docs/examples/external-agents.md) · [MCP README](mcp/README.md) · [ECM engineering (PyPI)](docs/ecm/README.md)
18 
19**Software-engineering agent OS:** [`openfdd_agent_spec/`](openfdd_agent_spec/) — architecture locks, skills, Milestone A.
20 
21**Active recovery / Vibe 21 twin program:** [`tools/open-fdd-vibe21-production/`](tools/open-fdd-vibe21-production/README.md) · capability ledger [`docs/migration/react-rust/capabilities.yaml`](docs/migration/react-rust/capabilities.yaml).
22 
23**PyPI (`open-fdd`):** ECM engineering + pandas oracle (`open_fdd.rules` / `analytics` / `reporting`) for **third-party tooling** outside the product app. Product FDD is DataFusion on GHCR.
24 
25Dual expression cookbooks (permanent): `docs/rules/cookbook/` (SQL + pandas).
26 
27## Start session
28 
29Unmerged UI is **not** on GHCR. Resolve newest published images by OCI
30`created` (`./scripts/ghcr_newest_by_created.py`), and never paste a Caddy
31URL until `./scripts/openfdd_demo_gate.sh` exits 0. See
32[`CONTAINER_AGENT.md`](openfdd_agent_spec/CONTAINER_AGENT.md).
33 
34```bash
35./scripts/openfdd_stack_up.sh react-ot     # React SPA + mqtt + central + fieldbus
36# or: react (no fieldbus) / csv
37TOKEN="$(curl -s -X POST http://127.0.0.1:8080/api/auth/login \
38  -H 'Content-Type: application/json' \
39  -d '{"username":"admin","password":"'"$OPENFDD_ADMIN_PASSWORD"'"}' \
40  | jq -r '.token // .access_token')"
41```
42 
43Discover routes: `curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/agent/tools | jq '.tools | length'`
44 
45## Safe scripts
46 
47```bash
48./scripts/openfdd_stack_pull.sh react-ot
49./scripts/openfdd_stack_up.sh react-ot
50./scripts/nightly-ot-bench/run_all.sh      # pull sha-* + OT/API gates
51./scripts/openfdd_stack_up.sh csv
52```
53 
54## External agent workflow
55 
561. Stack healthy on LAN/VPN only — never expose on public internet.
572. JWT for admin/operator/viewer (see central auth env).
583. `openfdd-mcp` stdio outside the web UI, or REST `/api/agent/tools`.
594. Read-first; writes need `OPENFDD_MCP_ALLOW_WRITES=1` and `confirm:true`.
605. Never print secrets. BACnet writes need explicit human approval.
61 
62## Product UI / FDD agent notes
63 
64- **Overview plots:** plot Expanders default **open** so charts are not hidden behind carets (`OverviewPopulated`).
65- **Lab → FDD Plots:** `session_config` `confirm_min` (and rule params) apply to the series overlay (`sql_detail_session`). After **Update this rule**, Reports/FDD Plots must refetch on `RULES_UPDATED`.
66- **SCHED-1 occupancy:** treat numeric `0` / `0.0` / `false` **and** string `unoccupied` (and related tokens) as unoccupied — SQL + pandas cookbook stay aligned.
67- **Synthetic-59:** soak via `scripts/synthetic_59_*.py` under `reports/wattlab-parity/fixtures/synthetic_59/`. Do not greenwash `expected_faults.csv`. B100 dump-parity remains **paused**.
68- **Units:** FDD SQL is °F canonical. Metric CSVs convert at query (`unit_system=metric|si`). Lab sliders show °C when metric is selected; Run all rules after switching.
69- **Hourly append:** seed with `POST /api/csv/import/package`, then `POST /api/csv/import/package/append` (JWT, `confirm:true`). Custom appenders stay outside the repo.
70- **Overview layout:** full width beside sidebar (Streamlit-like); named Plotly PNG stems via `downloadFilename`; Lab rule menu A–Z; FDD series = required∪optional roles.
71- **Mech OAT bins:** status/cmd before amps; prefer web/weather OAT. Analytics envelopes: `scripts/synthetic_59_overview_analytics_soak.py`.
72 
73## Low-RAM hosts (bensbench)
74 
75- **Never** local `docker build` / heavy Rust compile for stack images. Ship via PR → GH Actions → GHCR `nightly` / `sha-*`.
76- Before pulling new images: prune unused/old digests first, then `./scripts/openfdd_stack_pull.sh …` and `./scripts/openfdd_stack_up.sh … --no-pull`.
77- Details: [`openfdd_agent_spec/CONTAINER_AGENT.md`](openfdd_agent_spec/CONTAINER_AGENT.md).
78 
79## Never
80 
81- delete `workspace/`
82- run `docker compose down -v`
83- run `docker volume prune`
84- print secrets or tokens
85- expose API on public internet
86- write BACnet without explicit human approval
87- embed vendor chat relays or model API keys in the stack
88- add Python to the product central/web request path
89- local stack image builds on low-RAM hosts (use GHCR)
90 
91See [docs/agent/index.md](docs/agent/index.md) for external-agent architecture.
92 
93For library/migration/PR missions (Milestone A), start at [openfdd_agent_spec/AGENTS.md](openfdd_agent_spec/AGENTS.md).
94