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>`
Aggregate frontend checks	`./scripts/check_frontend_quality.sh`
Install git hooks	`~/.bun/bin/bun run hooks:install`

Always run check and build after making frontend changes. check must pass with no Biome warnings or errors before finishing.

Backend Python Checks

Backend Python checks run from the repo root using uv.

Task	Command
Aggregate backend checks	`./scripts/check_python_quality.sh`
Format check	`uv run --with "ruff>=0.15.0,<1.0.0" ruff format --check app.py`
Lint	`uv run --with "ruff>=0.15.0,<1.0.0" ruff check app.py`
Dependency check	`uv run --with "deptry>=0.24.0,<1.0.0" deptry . --requirements-files requirements.txt --known-first-party app,supertonic_gateway,voice_rtc,wisper --per-rule-ignores DEP002=uvicorn --extend-exclude "./frontend/." --extend-exclude "./\\.venv/." --extend-exclude "./__pycache__/."`
Dead code	`uv run --with "vulture>=2.15,<3.0.0" vulture app.py --min-confidence 80`

Always run ./scripts/check_python_quality.sh after making backend Python changes.

Git Hooks

Versioned hooks live in .githooks/
bun install in frontend/ auto-installs them via postinstall
Manual install is ~/.bun/bin/bun run hooks:install from frontend/ or ./scripts/install_git_hooks.sh from the repo root
The pre-commit hook runs ./scripts/check_python_quality.sh for staged backend changes and ./scripts/check_frontend_quality.sh for staged frontend changes

Linting rules

Linter: Biome (config at frontend/biome.json)
No biome-ignore suppressions — fix the code or disable the rule in biome.json
bun run check is warning-failing and should block commits on any Biome warning
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

3 KiB Raw Blame History