# Working on this repo (instructions for Claude)

## Keep the docs in sync with the code. Every change. No exceptions.

Any edit that changes behaviour, structure, config, commands, endpoints, env vars, or a default (a model
id, a port, a path) makes some doc wrong. Fix that doc in the SAME change. Before you finish, ask: "does a
doc now say something false?" If yes, you are not done.

Where things are documented — update the one your change touches:

- Top-of-file summary + grep anchors in each substantial code file. Update when you change what the file
  does or move key logic.
- `README.md` — what this is, how to run locally, the file map.
- `docs/architecture.md` — the pieces, the call flow, the two auth planes, storage, the AI subsystem.
- `docs/operations.md` — the server: deploy, rollback, the `/etc/helpdesk/env` variable table, backups, CI.
- `docs/device-api.md` — the phone-to-backend wire contract: endpoints, the HMAC recipe, the event state
  machine, reconciliation timings.
- `docs/phone-connectivity.md` — how the patched Dialer finds, authenticates to, and talks to the backend,
  plus the troubleshooting table.
- `docs/onboarding.md`, `docs/runbooks/*` — accounts/certs/SSH, and the device build + flash.
- Each component's own `README.md`.

Concrete: add an endpoint → `docs/device-api.md`. Add/rename an env var → the table in
`docs/operations.md`. Change a model default or the wiki-grounding behaviour → `docs/architecture.md` (AI
subsystem). Change how the phone connects or a config property → `docs/phone-connectivity.md`.

## Docs philosophy (why they're few)

Few durable standalone docs (what it is, what it does, where things live). Everything detailed lives IN the
code with grep anchors, so a reader jumps straight there. Do not add pages that only restate code — every
extra page is more surface to rot. No historical/status/planning docs in the repo (those are git-excluded
scratch like `todo-phased.md`).

## Style

Plain language. No buzzwords (no leverage / robust / seamless / caveat / delve / vibrant …). Run the
humanizer skill over prose you write or touch. **No em dashes or en dashes — use a plain hyphen `-`.**
Verify every claim against the code as it runs now before writing it.

## Don't break

- Local dev must keep booting with `ruby components/backend/server.rb` and no env (JSON store, no DB).
- Secrets never enter the repo — names and paths only. Values live in `/etc/helpdesk/env` (server) or
  `.claude/env.local` (local, gitignored).
- The app connects to PostgreSQL as the `helpdesk` role, never `postgres`. Parameterized queries only.