Lucy Doupalů be9f14ce34 Helpdesk - operator console + patched GrapheneOS Dialer for call handling

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.

2026-07-27 18:50:32 +02:00

2.6 KiB

Raw Blame History

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.