stable

AGENTS.md

@@ -0,0 +1,40 @@
+# Agent Instructions
+
+## Project layout
+
+- `app.py` — FastAPI server (writable)
+- `frontend/` — Preact + TypeScript UI built with Vite
+- `voice_rtc.py`, `supertonic_gateway.py`, `wisper.py` — read-only; do not modify
+- `start.sh` — read-only startup script
+- `.env.voice` — local env overrides (writable); sourced before `start.sh` defaults
+
+## Toolchain
+
+All frontend commands run from `frontend/` using `~/.bun/bin/bun`.
+
+| Task | Command |
+|---|---|
+| Lint + format check | `~/.bun/bin/bun run check` |
+| Build | `~/.bun/bin/bun run build` |
+| Dead code | `~/.bun/bin/bunx knip` |
+| Format a file | `~/.bun/bin/bun run biome format --write <file>` |
+
+Always run `check` and `build` after making frontend changes. Both must pass with no errors before finishing.
+
+## Linting rules
+
+- Linter: Biome (config at `frontend/biome.json`)
+- No `biome-ignore` suppressions — fix the code or disable the rule in `biome.json`
+- All font sizes in CSS must use `rem`, not `px`
+
+## Dead code
+
+Run `~/.bun/bin/bunx knip` from `frontend/` to find unused files, exports, and types. The only expected false positive is `dist/assets/` build output.
+
+## Backend
+
+- Card instances are file-backed in `NANOBOT_WORKSPACE/cards/instances/<card-id>/card.json`
+- Card HTML snapshots are stored beside metadata in `NANOBOT_WORKSPACE/cards/instances/<card-id>/render.html`
+- Templates live in `NANOBOT_WORKSPACE/cards/templates/<template-key>/template.html` with `manifest.json`
+- `GET /cards` returns all non-archived cards ordered by lane, state, priority, then update time
+- `DELETE /cards/{id}` removes a card on dismiss