# 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