docs: write the README and map the build workflow

docs/workflow.md

@@ -0,0 +1,62 @@
+# How I work
+
+A short map of the setup behind this repo, because the process says as much
+as the code.
+
+## The environment
+
+Everything was built over SSH from a laptop (I was house-sitting for most
+of it) against my home server, a Debian box that runs my self-hosted
+infrastructure. The server carries the whole toolchain: uv and node for
+fast local feedback, Docker for the deliverable, and the deployment stack
+below. No cloud dev environment involved.
+
+## Source control and CI
+
+- Origin is my self-hosted Forgejo instance, with a push mirror to GitHub;
+  the repo you are reading is the mirror and shows the same history and
+  the same green CI.
+- CI runs on every push: ruff, mypy and pytest for the backend; typecheck,
+  lint, build and vitest for the frontend. It has been green since the
+  first commit.
+
+## Deployment
+
+- The hosted instance is a single container on the same server, built from
+  this repo's Dockerfile and managed with Komodo (a self-hosted container
+  control plane). It is rebuilt from main as the build advances.
+- Routing and TLS come from caddy-docker-proxy: the container carries its
+  route as labels, Caddy picks them up. The streaming endpoint needed one
+  deliberate setting there (no response buffering), verified through the
+  public URL.
+- HTTP basic auth sits at the edge because the instance runs against my
+  personal Spotify account.
+
+## AI-assisted building
+
+I work with coding agents, and this project was built that way end to end:
+
+- One orchestrating session (Claude Code harness) holds the plan and the
+  state. It briefs implementation agents (codex CLI, Opus 5 subagents) that
+  build scoped tracks in their own git worktrees, in parallel.
+- Contracts come first: the API schemas and the event protocol were frozen
+  before frontend and backend lanes ran in parallel against them.
+- Parallel lanes buy time where it matters. While I was working on the
+  backend, a separate lane generated a ready-to-implement UI (design
+  tokens, component structure, copy) against the frozen event protocol, so
+  frontend implementation started from a settled design instead of a blank
+  page.
+- Everything that lands is reviewed by me, commit by commit, in my editor
+  before it goes in. Voice-carrying text (this file, the README, the
+  logboek) I write or rewrite myself.
+- Verification against the real APIs is deliberate and budgeted: the
+  Spotify development quota is a daily account-level budget, so live test
+  runs are planned, sequential and measured rather than sprayed.
+- Review also runs as a tool: adversarial review passes over the diffs
+  produced findings that became fix batches; the useful findings and the
+  rejected ones are both traceable in the logboek.
+
+The result is that implementation is cheap and parallel, while design,
+review and verification stay serial and human. The logboek
+([logboek.md](logboek.md)) records that rhythm as it happened, including
+what was dropped under time pressure.