docs: write the README and map the build workflow

docs/logboek.md

@@ -2,7 +2,9 @@
 
 Bijgehouden tijdens de bouw. Per stap: wat ik deed, waarom, wat ik heb laten
 vallen.
+
 ## Dag 1 - korte sessie in de avond
+
 ### Opzet
 
 Wat ik deed:
@@ -35,6 +37,7 @@ Wat ik heb laten vallen of uitgesteld:
 - Geen apart beslisdocument. De motivering staat in de README en hier.
 
 ## Dag 2
+
 ### Spotify-koppeling
 
 Wat ik deed:
@@ -227,7 +230,7 @@ Waarom:
   main landt.
 - Styling is scoped CSS per component bovenop globale design tokens
   (custom properties). Scoped omdat machine-geconverteerde componenten
-  om style leakage te voorkomen, en  omdat het bouwpakket al gewone CSS 
+  om style leakage te voorkomen, en omdat het bouwpakket al gewone CSS
   per component leverde: een utility
   framework had een rewrite plus een extra dependency gekost. De
   tokens houden het thema op 1 plek, dus het bekende scoped-CSS risico
@@ -262,7 +265,7 @@ Wat ik deed:
   gefragmenteerde chunks, error-terminaliteit, de request-caps en
   abort-races vastlegt; draait mee in CI.
 - Alle user-facing tekst uit de componenten geextraheerd naar 1 getypeerde
-  messages-module (i18n-klaar zonder er nu een framework voor mee te nemen), 
+  messages-module (i18n-klaar zonder er nu een framework voor mee te nemen),
   alle magic numbers vervangen door
   benoemde constants met per waarde een reden (de request-caps verwijzen
   expliciet naar de backend schema-bounds), en dichtgeschreven TypeScript
@@ -275,6 +278,7 @@ Waarom:
   contractkritische randen vastzet, voordat het richting main gaat.
 
 ## Dag 3 - avond
+
 ### Live eval run
 
 Wat ik deed:
@@ -397,6 +401,8 @@ Wat ik heb laten vallen of uitgesteld:
 - Byte-snapshots per pipeline-stap; de checks hierboven en de cassettes
   zijn nu het bewijs.
 
+## Dag 3 - afronding
+
 ### Demo mode
 
 Wat ik deed:
@@ -438,3 +444,31 @@ Waarom:
 
 - Minder scopes vragen dan je gebruikt is netter richting de reviewer en
   richting Spotify.
+
+### Documentatie
+
+Wat ik deed:
+
+- De README geschreven: wat het is, drie manieren om het te draaien, hoe
+  de pipeline werkt, de keuzes, eerlijke performance-cijfers (eerste kaart
+  20 tot 30 s, gemeten via de UI en de eval), een stukje van de
+  vergelijking met kale search, en een "where to look" tabel per
+  beoordelingscriterium.
+- docs/workflow.md toegevoegd: hoe ik werk. De server, Forgejo met een
+  GitHub-mirror, Komodo en Caddy voor de gehoste instantie, en hoe ik
+  agents inzet: implementatie parallel en goedkoop, ontwerp, review en
+  verificatie serieel en bij mij.
+- De gehoste preview bouwt nu bij elke merge opnieuw vanaf main.
+
+Waarom:
+
+- De reviewer leest de README het eerst; die moet kort zijn en naar de
+  rest wijzen in plaats van alles zelf te vertellen. En de werkwijze
+  uitleggen is eerlijker dan hem laten raden waarom commits in bursts
+  binnenkomen.
+
+Wat ik heb laten vallen of uitgesteld:
+
+- Een sneller model op de intent call (zou de wachttijd flink verlagen;
+  de fabrication rate is de afweging om dan te meten) staat als vervolg
+  in de README, niet gebouwd.

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.