be9f14ce34
A small helpdesk system: an office Pixel running a patched GrapheneOS Dialer answers technician calls, records both call legs as separate channels, and a Ruby backend transcribes them through Whisper and files an AI summary against the caller. Squashed to a single commit for sharing. No credentials are included; secrets live outside the repo in /etc/helpdesk/env on the server or a gitignored .claude/env.local locally. See .claude/env.local.example for the shape. Start at README.md, then docs/architecture.md.
45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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.
|