docs: clean up CLAUDE.md — restructure scrambled sections + sync stale facts (#14)

Het bestand was structureel gebroken: prompt_scaffold-instructies uit /insights
("Add as a new ## X section ...\\n\\n## X") waren als platte tekst in de Branch &
PR Strategy-sectie beland, met drie nieuwe secties (UI Library Conventions,
Deployment, Plan Mode) onleesbaar verstopt daarbinnen.

Wijzigingen:

Restructurering
- Branch & PR Strategy: scaffold-residue weg, oorspronkelijke 'core rule' +
  do/don't/exceptions hersteld
- UI Library Conventions: eigen sectie, na Tech stack — base-ui/react render-prop
  pattern (niet Radix asChild) expliciet beschreven
- Deployment (Vercel): eigen sectie, vóór DoD — Sharp Linux-binaries, image
  remotePatterns, Hobby cron-limieten, CRON_SECRET, preflight
- Plan Mode: eigen sectie, achter Branch & PR — wanneer wel/niet, plus regel
  dat plannen in docs/plans/ landen

Nuance op Git Workflow-regel
- Auto-commit-verbod uit /insights was te strict: botst met Track A
  commit-per-laag dat we de afgelopen sprints (M9/M10/M11) consequent doen
- Verfijnd: tijdens directed sprint-flow is commit-per-laag impliciet
  geautoriseerd; ad-hoc/out-of-band werk vereist 'commit it'-bevestiging
- git push blijft altijd expliciet (de hele kostenbeheersings-policy gaat
  daarover)

Stale content gesynced
- MCP-tools-lijst 9 → 13 (M11 question-tools toegevoegd: ask_user_question,
  get_question_answer, list_open_questions, cancel_question), gegroepeerd
  per categorie
- DoD: 'Alle 7 API-endpoints' → 'Alle gedocumenteerde API-endpoints (zie
  docs/API.md)' (we hebben er nu 13+)
- Env vars: CRON_SECRET toegevoegd; SESSION_SECRET min-32-chars eis
  vermeld; verwijzing naar lib/env.ts en .env.example

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -85,6 +85,17 @@ Vercel Analytics (@vercel/analytics/next)
 
 ---
 
+## UI Library Conventions
+
+- Dit project gebruikt **`@base-ui/react`**, *niet* Radix UI — ondanks dat shadcn-componenten visueel-identiek zijn
+- Composition gebeurt via de **`render`-prop**, niet via Radix's `asChild`:
+  - ✅ `<TooltipTrigger render={<button />}>...</TooltipTrigger>`
+  - ❌ `<TooltipTrigger asChild><button>...</button></TooltipTrigger>` — geeft TS-errors
+- Vóór je een nieuwe shadcn-/UI-primitive gebruikt: grep eerst de codebase voor bestaand gebruik en volg dat patroon (`grep -rn "PrimitiveTrigger" components/`)
+- shadcn-componenten in `components/ui/` zijn dunne wrappers rond `@base-ui/react`-primitives; lees die voor de exacte prop-API
+
+---
+
 ## Implementatiepatronen
 
 Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
@@ -108,11 +119,14 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 ## Env vars
 
 ```bash
-DATABASE_URL=""        # postgresql://...
-DIRECT_URL=""          # alleen bij Neon/cloud
-SESSION_SECRET=""      # openssl rand -base64 32
+DATABASE_URL=""        # postgresql://... (verplicht)
+DIRECT_URL=""          # postgresql://... — pooler-bypass voor LISTEN/NOTIFY (Neon/cloud)
+SESSION_SECRET=""      # min 32 chars; openssl rand -base64 32
+CRON_SECRET=""         # M11 — Bearer-secret voor /api/cron/*; verplicht in productie, optioneel lokaal (genereer met openssl rand -base64 32)
 ```
 
+Volledige Zod-schema in `lib/env.ts`. `.env.example` is de canonieke lijst voor nieuwe checkouts.
+
 ---
 
 ## Conventies
@@ -154,11 +168,18 @@ Elke `git push` naar een feature-branch triggert een Vercel preview-deployment.
 - Een PR per story openen tijdens de implementatie
 - "Just-in-case" pushen om backup te hebben — gebruik `git stash`, een lokale tag, of meerdere lokale branches
 - `--force-push` om eerdere preview-builds "weg te toveren" (kost dezelfde build opnieuw bij hercreatie)
+- **Direct pushen naar `main`** — die branch heeft protection rules; gebruik altijd een PR
 
-### Uitzonderingen
+### Wanneer wel commit-zonder-vragen, wanneer niet
+
+- **Tijdens een directed sprint-flow** (Track A: `mcp__scrum4me__implement_next_story` of een expliciete *"implementeer M{N}"*-opdracht): commit-per-laag conform de Commit Strategy hieronder is impliciet geautoriseerd — niet per commit vragen
+- **Bij ad-hoc / out-of-band werk** (bug-fix tussendoor, refactor, kleine wijziging op verzoek): toon de diff + voorgestelde commit-message en wacht op `"commit it"` voordat je `git commit` draait
+- **`git push` is altijd expliciet** — de scope van de policy gaat over preview-builds, dus push gebeurt alleen na gebruiker-test, ongeacht commit-context
+
+### Uitzonderingen op de push-regel
 
 - Een **planning-PR** zonder code-wijzigingen (alleen docs in `docs/plans/` of `docs/`) mag direct gepusht worden — die triggert geen functional regressie en is goedkoop te bouwen
-- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden
+- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden (via een PR — zie boven)
 
 ### Wanneer aanpassen
 
@@ -166,6 +187,14 @@ Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) g
 
 ---
 
+## Plan Mode
+
+- Voor simpele, goed-afgebakende file-edits: **niet** in plan mode gaan — gewoon de wijziging maken
+- Reserveer plan mode voor multi-step refactors, ambigue verzoeken, of milestone-planning waarbij design-keuzes vooraf bevestigd moeten worden
+- Plannen die uit plan mode komen: opslaan als `docs/plans/M{N}-{slug}.md` (zie memory `feedback_plan_location`), niet als ephemeral systeem-bestand
+
+---
+
 ## Commit Strategy (STRICT)
 
 > **Core rule: één commit = één verantwoordelijkheid**
@@ -216,6 +245,8 @@ docs(ST-XXX): document profile feature
 
 ---
 
+
+
 ## Scrum-terminologie
 
 | Correct | Niet gebruiken |
@@ -231,15 +262,24 @@ docs(ST-XXX): document profile feature
 
 Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd.
 
-### Tools beschikbaar in Claude Code
+### Tools beschikbaar in Claude Code (13)
 
+**Read / context:**
 - `mcp__scrum4me__health` — service + DB ping
 - `mcp__scrum4me__list_products` — producten waar de tokengebruiker toegang tot heeft
 - `mcp__scrum4me__get_claude_context` — bundled product / actieve sprint / next story (met tasks) / open todos
+
+**Task / story writes:**
 - `mcp__scrum4me__update_task_status`, `mcp__scrum4me__update_task_plan`
 - `mcp__scrum4me__log_implementation`, `mcp__scrum4me__log_test_result`, `mcp__scrum4me__log_commit`
 - `mcp__scrum4me__create_todo`
 
+**Vraag-antwoord-kanaal (M11):**
+- `mcp__scrum4me__ask_user_question` — post een vraag over een story; optionele `wait_seconds` (max 600) polt voor het antwoord
+- `mcp__scrum4me__get_question_answer` — huidige status + antwoord (voor latere session-pickup)
+- `mcp__scrum4me__list_open_questions` — eigen vragen, max 50, recente eerst
+- `mcp__scrum4me__cancel_question` — asker-only annulering van een eigen open vraag
+
 ### Prompt
 
 - `implement_next_story` (arg: `product_id`) — end-to-end workflow
@@ -250,13 +290,23 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh
 
 ---
 
+## Deployment (Vercel)
+
+- **Sharp** moet Linux-binaries hebben voor de Vercel-runtime: `npm i --include=optional sharp` of platform-specifieke deps configureren in `package.json`
+- **Externe image hostnames** in `next.config.js` `images.remotePatterns` configureren *vóór* `next/image` op die hosts wijst — anders 500 in productie
+- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/API.md` + relevante pattern-docs updaten
+- **`CRON_SECRET`** moet als env-var op de Vercel-project-omgeving staan vóór de eerste cron-run, anders 401 op `/api/cron/*`-endpoints
+- **Preflight** vóór deploy: `npm run lint && npm test && npm run build` — falende build laat een PR niet door (CI blokkeert merge per ST-610)
+
+---
+
 ## Definition of Done (MVP)
 
 M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/scrum4me-backlog.md`.
 
 - [ ] Alle 62 tasks (ST-001 t/m ST-612) afgerond
 - [ ] Volledige Lars-flow zonder fouten (ST-612)
-- [ ] Alle 7 API-endpoints werken via curl
+- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/API.md`)
 - [ ] Demo-gebruiker heeft geen schrijfrechten
 - [ ] App opzetbaar via README zonder extra hulp
 - [ ] CI/CD actief — falende build blokkeert merge