docs: AI-optimized docs restructure (Phases 1–8) (#61)

* docs(dialog-pattern): add generic entity-dialog spec Introduceert docs/patterns/dialog.md als bron-of-truth voor elke create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende dataobject. Bevat 14 secties: uitgangspunten, stack, component- architectuur, layout, validatie, drielaagse demo-policy, submission, dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit profile-template, out-of-scope, en een verificatie-checklist. Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel zodat Claude (en mensen) de spec verplicht raadplegen voor elke nieuwe dialog. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(dialog-pattern): convert task spec + add pbi/story entity-profiles Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document bevat nu alleen Task-specifieke velden, URL-pattern, status-veld, server actions, triggers en bewuste out-of-scope-keuzes. Voegt twee nieuwe entity-profielen toe voor bestaande dialogen: - docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij, PbiStatusSelect, geen delete in v1) - docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met status/priority badges, inline activity-log, demo-readonly-fallback, inline-delete-confirm i.p.v. AlertDialog) Beide profielen documenteren expliciet de "Bekende gaps t.o.v. generieke spec" zodat opvolgende PR's de afwijkingen kunnen rechtzetten of bewust kunnen accorderen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Added pdevelopment docs * docs(plans): add docs-restructure plan for AI-optimized lookup Audit of existing 39 doc files (~10.700 lines) and a phased restructure proposal aimed at minimising the tokens an AI agent has to read to find the right reference. Captures resolved decisions on language (English), ADR template (Nygard default with MADR escape-hatch), index generator (node script), and folder taxonomy. Proposal status — fase 1 to follow. * docs(adr): add ADR scaffolding (templates, README, meta-ADR) Set up docs/adr/ as the canonical home for architecture decisions: - templates/nygard.md — default four-section format (Status, Context, Decision, Consequences) for one-way-door decisions. - templates/madr.md — MADR v4 with YAML front-matter and explicit Considered Options for decisions where rejected alternatives matter. - README.md — naming convention (NNNN-kebab-case), template-selection guidance (Nygard default; MADR for auth, queue mechanics, agent integration), status lifecycle, and ADR roster. - 0000-record-architecture-decisions.md — meta-ADR establishing the practice itself, in Nygard format. Backfilling existing implicit decisions (base-ui-over-radix, float sort_order, demo-user three-layer policy, etc.) is fase 6 of the docs-restructure plan. * feat(docs): add docs index generator + initial INDEX.md scripts/generate-docs-index.mjs walks docs/**/*.md, parses YAML front-matter (or first H1 fallback) and a Nygard-style ## Status section, then writes docs/INDEX.md with grouped tables for ADRs, Specs, Plans (with archive subsection), Patterns, and Other. Pure Node 20 (no external deps); idempotent — running it twice produces byte-identical output. Excludes adr/templates/, the ADR README, INDEX.md itself, and any *_*.md sidecar file. Wire-up: - package.json: docs:index → node scripts/generate-docs-index.mjs Initial run indexed 35 docs across the existing structure; the generated INDEX.md is committed so the table is reviewable in the PR before hooking generation into a pre-commit step. * chore: ignore Obsidian vault and personal sidecar files Add .obsidian/ (Obsidian vault config) and _*.md (personal sidecar notes) to .gitignore so the docs/ tree can serve as canonical source of truth while still being usable as an Obsidian vault for personal authoring. The docs index generator already excludes the same _*.md pattern from INDEX.md. * docs(plans): add PBI bulk-create spec for docs-restructure Machine-parseable spec for an executor that calls the scrum4me MCP (create_pbi → create_story → create_task) to seed the docs-restructure work into the DB. - Section 1 (Context) is the PBI description; serves as task-context via mcp__scrum4me__get_claude_context. - Section 2 lists the 6 resolved decisions (English, MD3+styling merged, solo-paneel merged, .Plans archived, Nygard ADR default, node index script). - Section 3 records what already shipped on this branch so the executor doesn't duplicate the ADR scaffolding or index generator. - Section 4 carries the structured YAML graph: 1 PBI, 8 stories (one per phase), 39 tasks. product_id is REPLACE_ME — fill before running. - YAML validated with PyYAML; field schema sanity-checked. * docs(junk-cleanup): remove stub patterns/test.md * docs(junk-cleanup): archive .Plans/ to docs/plans/archive/ * docs(front-matter): add YAML front-matter to docs/ root * docs(front-matter): add YAML front-matter to patterns/ * docs(front-matter): add YAML front-matter to plans + agent files * docs(index): regenerate INDEX.md after front-matter pass * docs(naming): drop scrum4me- prefix from doc filenames * docs(naming): lowercase API.md and MD3 filenames * docs(naming): rename plan file to kebab-case ASCII * docs(naming): rename middleware.md to proxy.md (next 16) * docs(naming): polish CLAUDE.md doc-index after renames * docs(taxonomy): scaffold topical folders under docs/ * docs(taxonomy): move spec files into docs/specs/ * docs(taxonomy): move design/api/qa/backlog/assets into folders * docs(taxonomy): move agent-instruction-audit into decisions/ * docs(split): break architecture.md into 6 topical files * docs(split): merge solo-paneel-spec into specs/functional.md * docs(split): merge md3-color-scheme into design/styling * docs(trim): extract branch/commit rules into runbook * docs(trim): extract MCP integration into runbook * docs(adr): add 0001-base-ui-over-radix * docs(adr): add 0002-float-sort-order * docs(adr): add 0003-one-branch-per-milestone * docs(adr): add 0004-status-enum-mapping * docs(adr): add 0005-iron-session-over-nextauth * docs(adr): add 0006-demo-user-three-layer-policy * docs(adr): add 0007-claude-question-channel-design * docs(adr): add 0008-agent-instructions-in-claude-md + update README index * docs(index): regenerate after ADR 0001-0008 * docs(glossary): add docs/glossary.md * chore(docs): regenerate INDEX.md in pre-commit hook * docs(readme): link INDEX + glossary + agent instructions * feat(docs): add doc-link checker script * chore(docs): wire docs:check-links and docs npm scripts * ci(docs): block merge on broken doc links * docs(links): fix broken cross-references after restructure --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 03:21:59 +02:00 · 2026-05-03 03:21:59 +02:00 · 7e45bbdbc0
commit 7e45bbdbc0
parent 289bcf9bf0
81 changed files with 12364 additions and 3154 deletions
--- a/docs/api/rest-contract.md
+++ b/docs/api/rest-contract.md
@ -0,0 +1,528 @@
+---
+title: "Scrum4Me REST API"
+status: active
+audience: [ai-agent, contributor]
+language: en
+last_updated: 2026-05-03
+---
+
+# Scrum4Me REST API
+
+REST-API contract voor Claude Code en andere clients.
+
+## Authenticatie
+
+Alle endpoints behalve `GET /api/health` vereisen een Bearer-token:
+
+```
+Authorization: Bearer <token>
+```
+
+Tokens beheer je via Instellingen → Tokens (`/settings/tokens`). Een token is gekoppeld aan één gebruiker; een demo-account-token kan lezen maar niet schrijven (`403`).
+
+## Status-enums
+
+De API gebruikt **lowercase** statussen. De database gebruikt UPPER_SNAKE; de vertaling gebeurt op de boundary.
+
+| Entiteit | Waarden |
+|---|---|
+| Task status | `todo`, `in_progress`, `review`, `done` |
+| Story status | `open`, `in_sprint`, `done` |
+
+## Foutcodes
+
+| Code | Betekenis |
+|---|---|
+| `200` | OK |
+| `201` | Created |
+| `400` | Malformed body (bv. ongeldige JSON) |
+| `401` | Token ontbreekt of ongeldig |
+| `403` | Token heeft geen toegang (demo-account, geen lid van product) |
+| `404` | Resource niet gevonden |
+| `422` | Validatiefout — body is wel-gevormd maar niet acceptabel |
+| `500` | Onverwachte serverfout |
+
+---
+
+## Endpoints
+
+### `GET /api/health`
+
+Health-probe. Geen authenticatie vereist.
+
+**Query params:** `?db=1` voegt een DB-ping toe.
+
+**Response (200):**
+```json
+{ "status": "ok", "version": "0.3.x", "time": "2026-04-26T20:00:00Z" }
+```
+
+Met `?db=1`:
+```json
+{ "status": "ok", "version": "0.3.x", "time": "...", "database": "ok" }
+```
+
+`database` is `"ok"` of `"down"`. De endpoint zelf retourneert altijd `200`.
+
+```bash
+curl https://scrum4me.app/api/health?db=1
+```
+
+---
+
+### `GET /api/products`
+
+Lijst van actieve producten waar de tokengebruiker eigenaar of lid van is.
+
+**Response (200):**
+```json
+[
+  {
+    "id": "cmofu...",
+    "code": "SCRUM4ME",
+    "name": "Scrum4Me",
+    "description": "...",
+    "repo_url": "https://github.com/...",
+    "definition_of_done": "..."
+  }
+]
+```
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" https://scrum4me.app/api/products
+```
+
+---
+
+### `GET /api/products/:id/claude-context`
+
+Bundled context voor Claude Code: product, actieve sprint, volgende story (met tasks) en open todos van de tokengebruiker — in één call.
+
+**Response (200):**
+```json
+{
+  "product": { "id", "code", "name", "description", "repo_url", "definition_of_done" },
+  "active_sprint": { "id": "...", "sprint_goal": "...", "status": "ACTIVE" } | null,
+  "next_story": {
+    "id", "code", "title", "description", "acceptance_criteria",
+    "priority", "status",
+    "tasks": [
+      { "id", "code", "title", "description", "implementation_plan",
+        "priority", "sort_order", "status" }
+    ]
+  } | null,
+  "open_todos": [
+    { "id", "title", "description", "created_at" }
+  ]
+}
+```
+
+`open_todos` is gelimiteerd op 50 items, gesorteerd op `created_at` asc. Demo-tokens kunnen dit endpoint lezen.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  https://scrum4me.app/api/products/$PRODUCT_ID/claude-context
+```
+
+---
+
+### `GET /api/products/:id/next-story`
+
+Hoogst geprioriteerde open story in de actieve sprint.
+
+**Response (200):**
+```json
+{
+  "id": "...",
+  "code": "ST-356",
+  "title": "Solo Kanban-bord met DnD en Zustand",
+  "description": "...",
+  "acceptance_criteria": "...",
+  "status": "in_sprint",
+  "tasks": [
+    {
+      "id": "...",
+      "code": "ST-356.1",
+      "title": "Store stores/solo-store.ts",
+      "description": "...",
+      "implementation_plan": null,
+      "priority": 2,
+      "sort_order": 1,
+      "status": "todo"
+    }
+  ]
+}
+```
+
+**Foutcodes:** `404` als geen actieve sprint of geen open stories.
+
+---
+
+### `GET /api/sprints/:id/tasks`
+
+Lijst taken van de sprint, geordend op `(story.sort_order, task.priority, task.sort_order)`.
+
+**Query params:** `?limit=N` (default 10, max 50)
+
+**Response (200):**
+```json
+[
+  {
+    "id": "...",
+    "code": "ST-356.1",
+    "title": "...",
+    "description": "...",
+    "implementation_plan": null,
+    "story_id": "...",
+    "story_code": "ST-356",
+    "priority": 2,
+    "sort_order": 1,
+    "status": "todo"
+  }
+]
+```
+
+---
+
+### `PATCH /api/stories/:id/tasks/reorder`
+
+Volgorde van taken binnen een story aanpassen.
+
+**Body:**
+```json
+{ "task_ids": ["task-id-a", "task-id-b", "task-id-c"] }
+```
+
+Alle IDs moeten bij de story horen. **Foutcodes:** `422` bij Zod-fouten of als een task_id niet tot de story behoort.
+
+---
+
+### `PATCH /api/tasks/:id`
+
+Status of implementation_plan bijwerken. Minstens één van beide is verplicht.
+Toegestane status-waarden zijn `todo`, `in_progress` en `done`. `review`
+wordt door deze endpoint geweigerd zolang de sprint-UI die state niet
+rendert — gebruik de Kanban-board voor REVIEW-overgangen.
+
+**Body:**
+```json
+{ "status": "in_progress", "implementation_plan": "..." }
+```
+
+**Response (200):**
+```json
+{
+  "id": "...",
+  "status": "in_progress",
+  "implementation_plan": "..."
+}
+```
+
+**Foutcodes:** `422` bij ongeldige body of onbekende status. `403` bij demo-token.
+
+---
+
+### `POST /api/stories/:id/log`
+
+Activiteit vastleggen op een story.
+
+**Body — IMPLEMENTATION_PLAN:**
+```json
+{
+  "type": "IMPLEMENTATION_PLAN",
+  "content": "Plan: ...",
+  "metadata": { "branch": "feat/x" }
+}
+```
+
+**Body — TEST_RESULT:**
+```json
+{
+  "type": "TEST_RESULT",
+  "content": "Alle tests groen",
+  "status": "PASSED",
+  "metadata": { "ci_run": "..." }
+}
+```
+
+**Body — COMMIT:**
+```json
+{
+  "type": "COMMIT",
+  "content": "Werk afgerond",
+  "commit_hash": "abc123",
+  "commit_message": "feat(ST-XXX): ...",
+  "metadata": { "branch": "feat/x" }
+}
+```
+
+`metadata` is optioneel, vrij JSON-object. **Response (201):**
+```json
+{ "id": "...", "created_at": "..." }
+```
+
+---
+
+### `POST /api/todos`
+
+Nieuwe todo voor de tokengebruiker.
+
+**Body:**
+```json
+{
+  "title": "Een ding doen",
+  "description": "Optionele uitleg, max 2000 tekens",
+  "product_id": "cmof..."
+}
+```
+
+**Response (201):**
+```json
+{ "id": "...", "title": "...", "description": "...", "created_at": "..." }
+```
+
+---
+
+### `GET /api/realtime/solo?product_id=...`
+
+Server-Sent Events stream voor het Solo Paneel. Wordt gebruikt door de browser-UI (`useSoloRealtime`); voor Claude Code zelden relevant, maar gedocumenteerd voor volledigheid.
+
+**Auth:** iron-session cookie of Bearer-token. Demo-tokens mogen lezen.
+**Query params:** `product_id` (verplicht).
+**Response:** `text/event-stream`. Stream blijft open tot de client sluit of de server na 240s een hard-close doet (client herconnect dan transparant).
+
+**Events:**
+- `event: ready` — eenmalig direct na connect, met `{ product_id, sprint_id }` als payload.
+- `event: error` — bij interne fouten (pg connect mislukt e.d.).
+- `data: {...}` — task/story mutaties die binnen scope vallen (zie hieronder). Payload-shape:
+
+  ```json
+  {
+    "op": "I" | "U" | "D",
+    "entity": "task" | "story",
+    "id": "cmof...",
+    "story_id": "cmof...",
+    "product_id": "cmof...",
+    "sprint_id": "cmog..." ,
+    "assignee_id": "cmof..." ,
+    "task_status": "TO_DO" | "IN_PROGRESS" | "REVIEW" | "DONE",
+    "task_title": "...",
+    "task_sort_order": 1,
+    "changed_fields": ["status", "updated_at"]
+  }
+  ```
+
+  Niet alle velden zijn altijd aanwezig — `task_*` alleen voor `entity: "task"`, idem `story_*`. `task_status` gebruikt de **DB-enum** (UPPER_SNAKE), niet de lowercase API-vorm.
+
+- `: heartbeat` — SSE-comment elke 25s, om proxies keep-alive te houden. Kan genegeerd worden.
+
+**Server-side filter:**
+- `product_id` matcht de query-param
+- `sprint_id` matcht de actieve sprint van het product
+- `assignee_id` is gelijk aan de ingelogde user (of `null` voor unassigned-story claims)
+
+Niet-matchende events worden gedropt — clients ontvangen geen irrelevante data.
+
+**Voorbeeld (browser):**
+```js
+const source = new EventSource('/api/realtime/solo?product_id=cmof...')
+source.onmessage = (e) => console.log(JSON.parse(e.data))
+```
+
+---
+
+## Auth — QR-pairing (M10)
+
+Drie anonieme/cookie-geauthenticeerde endpoints voor de password-loze inlog
+via QR-pairing. Worden door de browser gebruikt (niet door Claude Code) —
+gedocumenteerd voor volledigheid en voor handmatige curl-tests.
+
+**Cookie-mechaniek:** `pair/start` zet een korte `s4m_pair`-HttpOnly-cookie
+(`Path=/api/auth/pair`, `Max-Age=300`, `SameSite=Lax`, `Secure` in productie).
+`pair/stream` en `pair/claim` authenticeren tegen die cookie. Geheim materiaal
+zit nooit in URL-paden of querystrings — `mobileSecret` reist alleen via QR-
+fragment (`#s=…`) en POST-body, `desktopToken` alleen via cookie.
+
+### `POST /api/auth/pair/start`
+
+Anon. Maakt een nieuwe `LoginPairing` aan en zet de pre-auth cookie.
+
+**Auth:** geen.
+**Body:** geen.
+**Rate-limit:** 10 per IP per minuut (zelfde patroon als `/login`).
+
+**Response 200:**
+```json
+{
+  "pairingId": "cmoh...",
+  "mobileSecret": "<43-char base64url>",
+  "expiresAt": "2026-04-27T20:30:00.000Z",
+  "qrUrl": "https://.../m/pair#id=cmoh...&s=<mobileSecret>"
+}
+```
+Plus `Set-Cookie: s4m_pair=<desktopToken>; HttpOnly; Path=/api/auth/pair; Max-Age=300; SameSite=Lax`.
+
+**Foutcodes:** `429` bij rate-limit overschreden.
+
+**Voorbeeld:**
+```bash
+curl -i -X POST -c /tmp/jar http://localhost:3000/api/auth/pair/start
+```
+
+---
+
+### `GET /api/auth/pair/stream/:pairingId`
+
+Server-Sent Events stream die de desktop opent direct na `pair/start` om op
+de approve-bevestiging van de mobiel te wachten.
+
+**Auth:** `s4m_pair`-cookie. Werkt vanuit `EventSource` met `withCredentials: true`.
+**Path:** `pairingId` is niet vertrouwelijk; cookie is het bewijs.
+**Stream-duur:** maximaal 240s (Vercel-buffer onder de 300s `maxDuration`); sluit
+zodra status `consumed` of `cancelled` doorkomt.
+
+**Events:**
+- `event: state` — eenmalig direct na connect, met `{ pairing_id, status }` (status van pairing op moment van connecten — voorkomt race wanneer approve net vóór SSE-open landt).
+- `data: {...}` — bij elke status-overgang. Payload:
+  ```json
+  { "op": "I" | "U", "pairing_id": "cmoh...", "status": "pending" | "approved" | "consumed" | "cancelled" }
+  ```
+- `: heartbeat` — SSE-comment elke 25s.
+
+**Foutcodes:** `401` zonder/foute cookie, `404` als pairing onbekend, `410` als pairing verlopen.
+
+**Voorbeeld:**
+```bash
+curl -N -i -b /tmp/jar http://localhost:3000/api/auth/pair/stream/<pairingId>
+```
+
+---
+
+### `POST /api/auth/pair/claim`
+
+Cookie-auth. Atomisch consume van een approved pairing → schrijft de echte
+`session` cookie zodat de desktop is ingelogd.
+
+**Auth:** `s4m_pair`-cookie.
+**Body:** `{ "pairingId": "cmoh..." }`.
+
+**Response 200:** `{ "ok": true }` plus
+- `Set-Cookie: session=...; HttpOnly; SameSite=Lax` — paired-sessie met `paired: true` en `pairedExpiresAt = now + 8h` payload-velden.
+- `Set-Cookie: s4m_pair=...; Max-Age=0` — pre-auth cookie wordt gewist.
+
+**Foutcodes:**
+- `400` bij ontbrekende of malformed body
+- `401` zonder cookie of bij hash-mismatch (cookie matcht geen pairing)
+- `410` als pairing al consumed/cancelled is (replay) of verlopen
+
+**Voorbeeld:**
+```bash
+curl -i -X POST -b /tmp/jar -c /tmp/jar \
+  -H "Content-Type: application/json" \
+  -d '{"pairingId":"<pairingId>"}' \
+  http://localhost:3000/api/auth/pair/claim
+```
+
+---
+
+## Notifications — Vraag-antwoord-kanaal (M11)
+
+Endpoints voor de Claude vraag-antwoord-flow. De **MCP-tools** in de mcp-repo (`ask_user_question`, `get_question_answer`, `list_open_questions`, `cancel_question`) zijn de primaire schrijf-interface; de endpoints hieronder zijn voor de browser-UI en cron.
+
+### `GET /api/realtime/notifications`
+
+Server-Sent Events stream voor de notifications-bell in de NavBar. **User-scoped** — geen `product_id`-param; filtert server-side op alle producten waar de gebruiker eigenaar of teamlid is.
+
+**Auth:** iron-session cookie. Demo-gebruikers mogen lezen.
+**Response:** `text/event-stream`. Stream blijft open tot client sluit of server na 240s een hard-close doet (client herconnect).
+
+**Events:**
+- `event: state` — eenmalig direct na connect, met `{ questions: [...] }` als payload (zelfde shape als de live updates).
+- `data: {...}` — bij elke status-overgang in `claude_questions`. Payload-shape:
+  ```json
+  {
+    "op": "I" | "U",
+    "entity": "question",
+    "id": "cmoh...",
+    "product_id": "cmoh...",
+    "story_id": "cmoh...",
+    "task_id": "cmoh..." | null,
+    "assignee_id": "cmoh..." | null,
+    "status": "open" | "answered" | "cancelled" | "expired"
+  }
+  ```
+  Het is een delta — voor de volledige vraag-tekst en options reconnect de client (initial-state-event levert ze opnieuw).
+- `: heartbeat` — SSE-comment elke 25s.
+
+**Server-side filter:**
+- `payload.entity === 'question'` (`task` en `story` events horen op `/api/realtime/solo`)
+- `payload.product_id` zit in de set producten met user-access (productAccessFilter)
+
+**Voorbeeld:**
+```js
+const source = new EventSource('/api/realtime/notifications', { withCredentials: true })
+```
+
+---
+
+## Cron — Expire questions
+
+### `POST /api/cron/expire-questions`
+
+Vercel cron handler die dagelijks draait. Markeert verlopen open vragen als `expired` en verlopen pending login_pairings als `cancelled`.
+
+**Auth:** `Authorization: Bearer ${CRON_SECRET}` — header die Vercel automatisch injecteert wanneer de env-var op de project-omgeving staat. Zonder secret of bij mismatch: 401.
+
+**Schedule:** `0 4 * * *` (dagelijks om 04:00 UTC; Vercel Hobby-plan staat alleen daily crons toe — Pro ondersteunt fijnmazigere schedules).
+
+**Response 200:**
+```json
+{
+  "expired_questions": 0,
+  "expired_pairings": 0,
+  "ran_at": "2026-04-28T00:00:00.000Z"
+}
+```
+
+**Voorbeeld (handmatige trigger):**
+```bash
+curl -X POST -H "Authorization: Bearer $CRON_SECRET" \
+  https://your-app.vercel.app/api/cron/expire-questions
+```
+
+---
+
+## Cron — Cleanup agent artifacts
+
+### `POST /api/cron/cleanup-agent-artifacts`
+
+Vercel cron handler die dagelijks draait. Verwijdert `FAILED` en `CANCELLED` claude_jobs waarvan `finished_at` ouder is dan 7 dagen. Hard-delete — geen historische waarde; audit-trail zit in git-commits.
+
+**Auth:** `Authorization: Bearer ${CRON_SECRET}` — zelfde mechanisme als `/api/cron/expire-questions`. Zonder secret of bij mismatch: 401.
+
+**Schedule:** `0 3 * * *` (dagelijks om 03:00 UTC).
+
+**Response 200:**
+```json
+{
+  "deleted": 3,
+  "ran_at": "2026-05-01T03:00:00.000Z"
+}
+```
+
+**Voorbeeld (handmatige trigger):**
+```bash
+curl -X POST -H "Authorization: Bearer $CRON_SECRET" \
+  https://your-app.vercel.app/api/cron/cleanup-agent-artifacts
+```
+
+---
+
+## Voorbeeldworkflow voor Claude Code
+
+1. **Probe:** `GET /api/health?db=1` — bevestig dat de service en DB bereikbaar zijn.
+2. **Context:** `GET /api/products/$ID/claude-context` — haal product, sprint, volgende story en todos op in één call.
+3. **Plan vastleggen:** `POST /api/stories/$STORY_ID/log` met `type: IMPLEMENTATION_PLAN`.
+4. **Per task:** `PATCH /api/tasks/$TASK_ID` met `status: "in_progress"`, daarna met `status: "done"` plus eventueel `implementation_plan`.
+5. **Test:** `POST /api/stories/$STORY_ID/log` met `type: TEST_RESULT` en `status: PASSED|FAILED`.
+6. **Commit:** `POST /api/stories/$STORY_ID/log` met `type: COMMIT`, `commit_hash`, `commit_message`, optioneel `metadata: { branch }`.