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.
2.6 KiB
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/envvariable 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.rband 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
helpdeskrole, neverpostgres. Parameterized queries only.