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/plans/docs-restructure-ai-lookup.md

@@ -0,0 +1,499 @@
+---
+title: Docs-restructuur — geoptimaliseerd voor AI-lookup
+status: proposal
+audience: maintainer, ai-agent
+language: nl
+last_updated: 2026-05-02
+related:
+  - CLAUDE.md
+  - AGENTS.md
+  - README.md
+  - docs/agent-instruction-audit.md
+---
+
+# Plan — Docs-restructuur voor AI-lookup
+
+> Doel van dit plan: de huidige documentatie- en instructielaag van Scrum4Me omzetten naar een structuur die een AI-agent (Claude Code, Codex, een MCP-worker) in zo min mogelijk tokens en tool-calls het juiste document laat vinden, lezen en toepassen — zonder dat de mens-leesbaarheid eronder lijdt.
+
+Dit is een **proposal**, niet een afgerond ontwerp. Lees het, markeer wat je niet wil, en ik werk het uit naar een uitvoerbaar migratieplan met file-per-file diff.
+
+---
+
+## 1. Waarom dit plan
+
+Een AI-agent doet voor élke beslissing typisch dit:
+
+1. Leest `CLAUDE.md` (of `AGENTS.md`) volledig in context.
+2. Scant `docs/` met `ls`/`grep`/`glob` om relevante bestanden te kiezen.
+3. Leest één of meerdere docs volledig — vaak meer dan nodig, omdat doc-grenzen vaag zijn.
+4. Vindt cross-refs (`zie docs/X#Y`) en herhaalt stap 3.
+
+Elke stap kost tokens en latency. Als de bestandsboom, naamgeving of inhoud onduidelijk is, leest de agent te veel of het verkeerde — en maakt vervolgens beslissingen op verouderde of irrelevante informatie.
+
+**Concrete kosten in deze repo (gemeten 2026-05-02):**
+
+| Plek | Bestanden | Regels totaal | Grootste bestand |
+|---|---:|---:|---|
+| Root (CLAUDE.md, README.md, AGENTS.md, Brainstorm.md) | 4 | 679 | CLAUDE.md (340) |
+| `docs/` (root, exclusief subdirs) | 13 | 5.873 | scrum4me-architecture.md (1.247) |
+| `docs/patterns/` | 11 | 1.013 | dialog.md (387) |
+| `docs/plans/` | 8 | 2.121 | M10-qr-pairing-login.md (885) |
+| `.Plans/` (parallelle plan-historie) | 3 | ~600 | — |
+| **Totaal** | **39** | **~10.700** | — |
+
+Bij elke turn die met `CLAUDE.md` start, wordt minimaal 340 regels orientation in de context geladen — vóór er één regel code is gelezen. De agent kan vervolgens uit ~9.000 regels documentatie het juiste fragment moeten kiezen op basis van bestandsnamen alleen, want er is geen front-matter en geen index.
+
+---
+
+## 2. Wat ik aantrof — review per laag
+
+### 2.1 Root-niveau orientation
+
+| Bestand | Wat het doet vandaag | Probleem |
+|---|---|---|
+| `CLAUDE.md` (340 r) | Doel, doc-index, twee start-tracks, tech stack, UI-conventies, patroon-index, env vars, conventies, branch/commit-strategie, scrum-terminologie, MCP, deployment, DoD | Té breed: oriëntatie + harde regels + referentie-tabellen + procedures. Alles wordt elke turn geladen. |
+| `AGENTS.md` (38 r) | Codex-variant van CLAUDE.md | Duplicatie: 80% overlapt met CLAUDE.md (access-control, doc-sync, verificatie). Twee waarheden die uit elkaar kunnen lopen. |
+| `README.md` (285 r) | Portfolio-pitch, stack, setup, routes, dev-flow | Mensgericht (recruiters, GitHub-bezoekers). Goed dat het bestaat — niet aanraken. |
+| `Brainstorm.md` (16 r) | Stukjes Prisma-schema, JSON-snippet en HTML-DOM-dump zonder context | **Dood bestand**, weghalen of verplaatsen naar `docs/scratch/`. |
+
+### 2.2 `docs/` root
+
+| Bestand | Regels | Waar het thuishoort |
+|---|---:|---|
+| `scrum4me-architecture.md` | 1.247 | `docs/architecture/` — splitsen (zie §4) |
+| `scrum4me-functional-spec.md` | 650 | `docs/specs/functional.md` |
+| `scrum4me-backlog.md` | 751 | `docs/backlog/index.md` |
+| `scrum4me-product-backlog.md` | 454 | `docs/backlog/product-historical.md` (referentie, zie noot in CLAUDE.md) |
+| `scrum4me-personas.md` | 138 | `docs/specs/personas.md` |
+| `scrum4me-styling.md` | 670 | `docs/design/styling.md` |
+| `MD3_Color_Scheme_Documentation.md` | 941 | `docs/design/md3-color-scheme.md` (overlapt deels met `styling.md` — kandidaat voor merge) |
+| `scrum4me-test-plan.md` | 454 | `docs/qa/api-test-plan.md` |
+| `scrum4me-pbi-dialog.md` | 120 | `docs/specs/dialogs/pbi.md` |
+| `scrum4me-story-dialog.md` | 163 | `docs/specs/dialogs/story.md` |
+| `scrum4me-task-dialog.md` | 127 | `docs/specs/dialogs/task.md` |
+| `solo-paneel-spec.md` | 771 | `docs/specs/solo-panel.md` |
+| `API.md` | 520 | `docs/api/rest-contract.md` |
+| `agent-instruction-audit.md` | 173 | `docs/decisions/agent-instructions.md` (ADR-stijl) |
+| `erd.svg`, `icons.html` | — | `docs/assets/` |
+
+**Patroon dat opvalt:** alles met prefix `scrum4me-` — dat prefix is overbodig, je staat al in `docs/` van de Scrum4Me-repo. Verwijderen scheelt visuele ruis bij `ls`.
+
+**Inconsistente capitalization:** één bestand `MD3_Color_Scheme_Documentation.md` (snake + UpperCamel), de rest kebab. Eén bestand `API.md` (UPPER), de rest lowercase.
+
+### 2.3 `docs/patterns/`
+
+11 patronen, elk 25–390 regels. Goed als concept, maar:
+
+- `test.md` bevat letterlijk het woord "test" — junkfile, weghalen.
+- Geen front-matter; agent moet titel + intro lezen om te weten of het patroon van toepassing is.
+- Naamgeving inconsistent: `iron-session.md`, `qr-login.md`, `claude-question-channel.md` — sommige domeinspecifiek, andere generiek. Geen prefix die laat zien of het een **rule** (verplicht), **recipe** (voorbeeldcode) of **explainer** is.
+
+### 2.4 `docs/plans/`
+
+- 8 plans. Eén heeft een filename met spaties en em-dash: `Tweede Claude Agent — Planning Agent.md` — breekt grep/glob/git-workflows op sommige shells, en is moeilijk te linken. Omnoemen naar `tweede-claude-agent-planning.md`.
+- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` (ook nog typo "rioriteiten") — externe locatie die niet in de repo zit en die de agent niet kan lezen.
+- `MEMORY.md` wordt op meerdere plaatsen genoemd maar bestaat niet in de repo.
+
+### 2.5 `.Plans/` (root)
+
+3 historische planfiles uit april 2026, parallel aan `docs/plans/`. Twee waarheden voor "waar staan plannen". Voorstel: archiveren naar `docs/plans/archive/` of weghalen.
+
+### 2.6 Cross-referenties en dode links
+
+- CLAUDE.md verwijst naar `docs/scrum4me-architecture.md#demo-user-policy` — die anchor bestaat (regel 1068 `## Demo-user policy (ST-1110)`), dus dit is OK; maar er bestaat geen lint die garandeert dat dit zo blijft als de header verandert.
+- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` — externe locatie buiten de repo, plus typo "rioriteiten". Een agent kan die niet lezen.
+- README.md verwijst niet naar CLAUDE.md/AGENTS.md (mensbezoekers vinden de agent-instructie laag niet).
+- Geen enkel doc heeft een "Zie ook"-blok aan de onderkant. Cross-navigatie tussen patroon ↔ spec ↔ plan moet de agent zelf reconstrueren.
+
+### 2.7 Wat er níet is (en zou moeten)
+
+- **Geen index/manifest.** Een agent die `glob "docs/**/*.md"` doet, krijgt 30+ paden zonder context.
+- **Geen front-matter.** Geen status (draft/active/deprecated), audience, last-updated, related.
+- **Geen ADR-laag.** Beslissingen zoals "waarom geen Radix maar @base-ui/react", "waarom float sort_order", "waarom one-branch-per-milestone" zitten verstrooid in CLAUDE.md, README en losse plans. Een `docs/decisions/`-folder met ADR-format zou ze vindbaar maken.
+- **Geen glossary.** Domeintermen (PBI, Story, Sprint, Solo, Todo, demo-token) zijn alleen impliciet gedefinieerd in de functional spec.
+- **Geen "lookup-hints" in de doc-index.** CLAUDE.md zegt *waarvoor* je een doc gebruikt, niet *wanneer je het NIET hoeft te lezen*.
+
+---
+
+## 3. Doelen voor de nieuwe structuur
+
+In volgorde van belangrijkheid:
+
+1. **Eén goedkope orientation-laag.** Een agent moet ≤150 regels lezen om te weten waar hij verder moet kijken.
+2. **Voorspelbare paden.** `docs/<topic>/<entity-or-feature>.md` zonder uitzonderingen.
+3. **Machine-leesbare metadata.** YAML-front-matter op élk doc met minimaal `status`, `audience`, `last_updated`, `related`.
+4. **Per-doc lookup-hint.** Eén zin "Lees dit als …" bovenaan; één zin "Niet hiervoor lezen: …" om verkeerd ophalen te voorkomen.
+5. **Splitsing van regels (verplicht) en uitleg (referentie).** Regels in een korte rule-doc; voorbeeldcode en rationale in een aparte recipe/explainer.
+6. **Eén bron-van-waarheid per onderwerp.** Geen Codex-vs-Claude-duplicatie; AGENTS.md wordt een 10-regelige verwijzing naar CLAUDE.md.
+
+---
+
+## 4. Voorgestelde doelstructuur
+
+```
+/                                         (repo-root)
+├── README.md                             (mens, portfolio — ongewijzigd)
+├── CLAUDE.md                             (agent-orientation, ≤150 regels — zie §5)
+├── AGENTS.md                             (10 regels: "alles in CLAUDE.md geldt ook voor jou")
+├── docs/
+│   ├── INDEX.md                          (NIEUW — manifest met front-matter van alle docs)
+│   ├── glossary.md                       (NIEUW — PBI, Story, Sprint, demo-token, …)
+│   │
+│   ├── architecture/
+│   │   ├── overview.md                   (uit huidige architecture.md §1–§3)
+│   │   ├── data-model.md                 (uit §Datamodel + §Prisma Schema)
+│   │   ├── auth-and-sessions.md          (uit §Authenticatieflow)
+│   │   ├── qr-pairing.md                 (uit §QR-pairing flow)
+│   │   ├── claude-question-channel.md    (uit §Vraag-antwoord-kanaal)
+│   │   └── project-structure.md          (uit §Projectstructuur)
+│   │
+│   ├── specs/
+│   │   ├── functional.md                 (huidige scrum4me-functional-spec.md)
+│   │   ├── personas.md
+│   │   ├── solo-panel.md
+│   │   └── dialogs/
+│   │       ├── pbi.md
+│   │       ├── story.md
+│   │       └── task.md
+│   │
+│   ├── design/
+│   │   ├── styling.md                    (samengevoegd uit styling + MD3-color)
+│   │   └── color-tokens.md               (alleen het token-overzicht)
+│   │
+│   ├── api/
+│   │   ├── rest-contract.md              (huidige API.md)
+│   │   └── error-codes.md                (afgesplitst — vandaag verspreid)
+│   │
+│   ├── patterns/                         (RULES — kort en bindend)
+│   │   ├── 00-conventions.md             (server-action, prisma-client, route-handler — kort)
+│   │   ├── dialog.md
+│   │   ├── sort-order.md
+│   │   ├── zustand-optimistic.md
+│   │   ├── iron-session.md
+│   │   ├── proxy.md                      (was middleware.md — nieuwe naam)
+│   │   ├── qr-pairing.md
+│   │   └── claude-question-channel.md
+│   │
+│   ├── recipes/                          (NIEUW — uitgewerkte voorbeeldcode bij rules)
+│   │   └── …                             (één recipe per pattern dat code-snippets had)
+│   │
+│   ├── runbooks/                         (NIEUW — operationele procedures)
+│   │   ├── deploy-vercel.md              (uit CLAUDE.md §Deployment)
+│   │   ├── env-vars.md                   (uit CLAUDE.md §Env vars + .env.example)
+│   │   └── local-dev.md                  (huidige README §setup, geëxtraheerd)
+│   │
+│   ├── decisions/                        (NIEUW — ADR-stijl)
+│   │   ├── 0001-base-ui-over-radix.md
+│   │   ├── 0002-float-sort-order.md
+│   │   ├── 0003-one-branch-per-milestone.md
+│   │   ├── 0004-status-enum-mapping.md
+│   │   └── 0005-agent-instructions.md    (was agent-instruction-audit.md)
+│   │
+│   ├── backlog/
+│   │   ├── index.md                      (huidige scrum4me-backlog.md)
+│   │   └── product-historical.md         (huidige scrum4me-product-backlog.md)
+│   │
+│   ├── plans/
+│   │   ├── M9-active-product-backlog.md
+│   │   ├── M10-qr-pairing-login.md
+│   │   ├── M11-claude-questions.md
+│   │   ├── ST-1109-pbi-status.md
+│   │   ├── ST-1110-demo-readonly.md
+│   │   ├── ST-1111-claude-job-trigger.md
+│   │   ├── ST-1114-copilot-reviews.md
+│   │   ├── tweede-claude-agent-planning.md   (rename — geen spaties/em-dash)
+│   │   └── archive/                          (uit `.Plans/` aan repo-root)
+│   │       ├── 2026-04-27-claude-md-workflow-update.md
+│   │       ├── 2026-04-27-insert-milestone-tool.md
+│   │       └── 2026-04-27-m8-realtime-solo.md
+│   │
+│   ├── qa/
+│   │   └── api-test-plan.md
+│   │
+│   └── assets/
+│       ├── erd.svg
+│       └── icons.html
+│
+└── .Plans/                                (WEG — naar docs/plans/archive/)
+└── Brainstorm.md                          (WEG — junk, of naar docs/scratch/)
+└── docs/patterns/test.md                  (WEG — junk)
+```
+
+**Prefix `scrum4me-` overal weg.** Je staat in de Scrum4Me-repo.
+**Alle bestandsnamen kebab-case, lowercase.** Geen `API.md`, geen `MD3_…`.
+
+---
+
+## 5. CLAUDE.md herontwerp
+
+CLAUDE.md wordt strikt **router + harde regels** — geen referentie-tabellen, geen voorbeelden, geen rationale.
+
+Voorgestelde nieuwe inhoud (max ~150 regels):
+
+```markdown
+# CLAUDE.md — Scrum4Me
+
+## 1. Wat is Scrum4Me
+(2 zinnen — link naar README voor de pitch)
+
+## 2. Eerst lezen, altijd
+- docs/INDEX.md — manifest van alle docs
+- docs/glossary.md — bij twijfel over een term
+
+## 3. Hoe je werk vindt
+Twee tracks (A: MCP, B: manueel) — verkort tot 10 regels.
+Detail: docs/runbooks/sprint-flow.md
+
+## 4. Hardstop-regels (nooit overtreden)
+- demo-user heeft geen schrijfrechten (3-laagsdekking)
+- @base-ui/react, niet Radix
+- nooit bg-blue-500, altijd MD3-tokens
+- één commit = één verantwoordelijkheid
+- één branch per milestone, push pas na user-approval
+- denormalized FKs uit DB-parent, niet uit client-input
+(elk punt → 1 regel + link naar pattern/decision)
+
+## 6. Stack op één regel per laag
+(geen versie-uitleg, link naar docs/architecture/overview.md)
+
+## 7. Snelreferentie patronen
+| Wanneer | Lees |
+|---|---|
+| Server Action schrijven | docs/patterns/server-action.md |
+| Drag-and-drop reorder | docs/patterns/sort-order.md |
+| …(max 10 rijen)…|
+
+## 8. Verificatie vóór hand-off
+`npm run lint && npm test && npm run build`
+```
+
+Alles wat nu in CLAUDE.md §Conventies, §Branch & PR Strategy, §Commit Strategy, §MCP-integratie, §Deployment staat → verhuist naar:
+- `docs/runbooks/branch-and-commit.md` (regels + voorbeelden samen)
+- `docs/runbooks/deploy-vercel.md`
+- `docs/runbooks/mcp-integration.md`
+- `docs/decisions/0003-one-branch-per-milestone.md` (waarom)
+
+CLAUDE.md houdt in §4 alleen de éénregelige regel + link.
+
+**Effect:** elke turn 150 r in plaats van 340 r aan orientation-context. De agent leest aanvullende docs alleen wanneer de huidige taak ze raakt.
+
+---
+
+## 6. Front-matter spec
+
+Élk markdown-bestand in `docs/` (en `CLAUDE.md`, `AGENTS.md`) krijgt bovenaan:
+
+```yaml
+---
+title: <korte titel>
+status: draft | active | deprecated
+audience: ai-agent | maintainer | contributor | external
+language: nl | en
+last_updated: 2026-05-02
+applies_to: [feature-of-module-of-milestone-keys]   # optioneel
+related:
+  - docs/<andere>.md
+  - CLAUDE.md
+when_to_read: <één zin>
+do_not_read_for: <één zin — voorkomt mis-fetch>
+---
+```
+
+**Waarom dit voor AI-lookup helpt:**
+
+- `status: deprecated` → agent slaat het over zonder te lezen.
+- `applies_to: [M10, qr-login]` → grep op milestone-key → directe hit.
+- `when_to_read` / `do_not_read_for` → agent kan beslissen op de eerste 20 regels of dit doc nuttig is, zonder de hele 800-regelige spec in te lezen.
+- `related` → expliciete graaf in plaats van impliciete cross-refs.
+
+`docs/INDEX.md` wordt automatisch gegenereerd uit deze front-matter (klein script in `scripts/build-docs-index.ts` — onderdeel van het migratieplan).
+
+---
+
+## 7. AGENTS.md herontwerp
+
+```markdown
+# AGENTS.md
+
+This repo's source of truth for agent instructions is **CLAUDE.md**.
+Codex, Cursor, Continue, and any other coding agent: read CLAUDE.md first.
+The same product, security, and verification rules apply regardless of which agent runs.
+
+Repo-specific addendum (only if your agent does NOT speak markdown well):
+- The "This is NOT the Next.js you know" note also applies to you.
+- Run `npm run lint && npm test && npm run build` before handing work back.
+```
+
+Geen duplicatie van access-control of doc-sync — die regels staan exclusief in CLAUDE.md / `docs/patterns/` / `docs/decisions/`.
+
+---
+
+## 8. Migratie in fases
+
+Elke fase is een eigen branch + PR. Geen big-bang. Volgorde gekozen zodat agents tijdens de migratie nog steeds werken.
+
+### Fase 1 — Junk weg, front-matter erbij (laag risico)
+
+- `docs/patterns/test.md` weghalen.
+- `Brainstorm.md` weghalen of `docs/scratch/brainstorm-2026-05.md`.
+- `.Plans/` → `docs/plans/archive/`.
+- Front-matter toevoegen aan élk bestaand bestand (zonder verplaatsen). Status default = `active`.
+- `docs/INDEX.md` genereren via script.
+
+**Voor commit:** alle bestaande paden werken nog. Geen risico voor lopende sessies of CI.
+
+### Fase 2 — Naamgeving normaliseren
+
+- `scrum4me-` prefix overal weg via `git mv` (1 commit per groep — backlog/specs/personas/styling/dialogs).
+- `API.md` → `api/rest-contract.md`.
+- `MD3_Color_Scheme_Documentation.md` → `design/md3-color-scheme.md`.
+- `Tweede Claude Agent — Planning Agent.md` → `plans/tweede-claude-agent-planning.md`.
+- `middleware.md` → `proxy.md` (volgt Next.js 16 hernoeming).
+- Per `git mv`: in dezelfde commit zoek-en-vervang alle interne links + CLAUDE.md doc-index.
+
+### Fase 3 — Folder-taxonomie
+
+- Maak `docs/architecture/`, `docs/specs/`, `docs/design/`, `docs/api/`, `docs/runbooks/`, `docs/decisions/`, `docs/backlog/`, `docs/qa/`, `docs/assets/`.
+- Verplaats per groep met `git mv`. Eén commit per groep.
+- Update CLAUDE.md doc-index per stap.
+
+### Fase 4 — Splits monolithische docs
+
+- `scrum4me-architecture.md` (1.247 r) opdelen in 6 docs onder `docs/architecture/`.
+- Originele file wordt 20 regels: titel + "Dit document is opgesplitst — zie:" + lijst met nieuwe paden.
+- Idem voor `solo-paneel-spec.md` als dat onderdelen heeft die naar specs én patterns kunnen.
+
+### Fase 5 — CLAUDE.md verkorten + AGENTS.md verkorten
+
+- Knip CLAUDE.md naar het skelet uit §5.
+- Verplaats verwijderde secties naar `docs/runbooks/` en `docs/decisions/`.
+- AGENTS.md vervangen door de versie uit §7.
+
+### Fase 6 — ADR-backfill
+
+- Schrijf ADR's voor de impliciete beslissingen (5–8 stuks):
+  1. base-ui-over-radix
+  2. float-sort-order
+  3. one-branch-per-milestone
+  4. status-enum-mapping (db UPPER ↔ api lower)
+  5. iron-session-over-nextauth
+  6. demo-user-policy (3-laags)
+  7. claude-question-channel-design
+  8. agent-instructions-policy (was audit)
+
+### Fase 7 — Glossary + index-script
+
+- `docs/glossary.md` schrijven (PBI, Story, Sprint, Solo, Todo, demo-token, MCP-job, …).
+- `scripts/build-docs-index.ts` — genereert `docs/INDEX.md` uit alle front-matters.
+- Husky pre-commit hook: index regenereren bij wijziging van front-matter.
+
+### Fase 8 — Cross-link-check
+
+- Klein script dat alle `docs/...md` links volgt en rapporteert dode links én anchor-misses.
+- Toevoegen aan `npm run lint` of `npm test`.
+
+---
+
+## 9. Wat dit oplevert (meetbaar)
+
+| Metric | Vandaag | Doel |
+|---|---:|---:|
+| Regels die elke agent-turn standaard in context komen (CLAUDE.md) | 340 | ≤150 |
+| Doc-bestanden in `docs/` root | 13 | 2 (INDEX.md, glossary.md) |
+| Doc-bestanden zonder front-matter | 36 | 0 |
+| Junk-bestanden | 3 (test.md, Brainstorm.md, .Plans/) | 0 |
+| Bestandsnamen met spaties of niet-ASCII | 1 | 0 |
+| Filename-prefixen die geen informatie toevoegen (`scrum4me-`) | 8 | 0 |
+| Documenten >800 regels | 4 | 0 (na splitsing) |
+| Dode interne links | onbekend | 0 (na lint) |
+
+---
+
+## 10. Wat dit níet oplevert (eerlijk)
+
+- Codequaliteit verbetert niet automatisch.
+- Patronen die nu fout zijn worden niet gefixt — alleen vindbaar gemaakt.
+- ADR's invullen kost denkwerk dat ik niet uit jouw hoofd kan halen — fase 6 vereist jouw input.
+- AI-agents die geen front-matter parseren (oudere modellen, sommige codex-flavors) profiteren minder. Voor de `docs/INDEX.md` is het wel platte tekst — die helpt iedereen.
+
+---
+
+## 11. Open beslissingen — status
+
+| # | Vraag | Besluit (2026-05-02) |
+|---|---|---|
+| 1 | Taal van docs, front-matter, INDEX.md | **English** — alle nieuwe en herschreven docs in het Engels. Code comments blijven Engels (al zo). UI-strings blijven Nederlands. |
+| 2 | MD3-color + styling samenvoegen | **Eén doc** — `docs/design/styling.md`. |
+| 3 | `solo-paneel-spec.md` | **Samenvoegen** — opgaan in `docs/specs/functional.md` (eigen sectie). |
+| 4 | `.Plans/` archief | **Bewaren** — verplaatsen naar `docs/plans/archive/`. |
+| 5 | ADR-template (Nygard vs MADR) | **In discussie** — referentielink gedeeld, ik heb die niet kunnen openen (claude.ai share staat niet op de fetch-allowlist). Default voor fase 6: Nygard, klein en passend bij solo + kleine repo. Vervangbaar zodra besluit valt. |
+| 6 | Index-generator | **Node-script** in `scripts/build-docs-index.ts`. |
+
+## 12. Implicaties van besluit 1 — taalwissel
+
+De keuze "alle docs Engels" is groter dan hij lijkt. Drie scope-niveaus:
+
+**Niveau A — going-forward only (kleinste scope):**
+- Élk nieuw doc en élke nieuw aangemaakte front-matter in het Engels.
+- Dit plan, INDEX.md, glossary.md, runbooks/, decisions/ — allemaal Engels vanaf creatie.
+- Bestaande Nederlandse docs blijven staan tot ze om een andere reden geraakt worden.
+- **Risico:** mengvormen in docs/ — een agent vindt ene helft Engels, andere helft Nederlands. Grep op een Engels keyword mist Nederlandse hits.
+
+**Niveau B — opportunistic (middel):**
+- Niveau A + élke doc die we aanraken voor de restructuur (renames, splitsingen, front-matter toevoegen) wordt meteen vertaald.
+- Aan het eind van fase 5 zijn `architecture/`, `specs/`, `design/`, `api/`, `patterns/`, `runbooks/`, `decisions/` allemaal Engels.
+- Backlog, plans en QA blijven Nederlands tenzij ze ge-edit worden.
+
+**Niveau C — full sweep:**
+- Élke `.md` in de repo vertalen, ongeacht of de restructuur hem aanraakt.
+- Aanzienlijk werk: ~10.700 regels prose. Schatting: 1-2 dagen agent-tijd of een batch-translate-pass met review.
+
+**Voorstel: niveau B.** Sluit aan bij de migratiefases zonder een aparte translation-sprint te hoeven plannen. Niveau C kan later als één losse PR.
+
+## 13. ADR-template — voorlopige keuze
+
+Tot besluit valt op vraag 5: ik gebruik **Nygard-Light** als template voor fase 6. Eén ADR is één bestand met:
+
+```markdown
+---
+title: <decision title>
+adr_number: 0001
+status: proposed | accepted | superseded by 00xx
+date: 2026-05-02
+---
+
+# 0001. <decision title>
+
+## Context
+Why this decision matters now. What forces are in play.
+
+## Decision
+The choice we make. One paragraph, declarative.
+
+## Consequences
+What becomes easier, what becomes harder, what we accept.
+```
+
+Compact, grep-vriendelijk, en agent-leesbaar binnen ~30 regels. Als MADR de uitkomst wordt, swappen we het template voor fase 6 — alle eerdere fases zijn template-onafhankelijk.
+
+## 14. Volgende stap
+
+Met deze besluiten kan ik fase 1 omzetten naar een concrete uitvoeringslijst:
+
+- exacte `rm` / `git mv` / `mkdir` commando's
+- de front-matter-template in het Engels
+- één `npm run` of bash-snippet die de hele fase in één commit zet
+- bijbehorende update-diff voor CLAUDE.md (alleen de doc-index-tabel)
+
+Zeg het woord en ik produceer dat als `docs/plans/docs-restructure-phase-1.md`.
+
+---
+
+## Verificatie van dit plan
+
+- [x] Bestandsnamen en regelaantallen gecheckt tegen `find docs -type f` + `wc -l` op disk (2026-05-02).
+- [x] Cross-refs in CLAUDE.md gegrep't en op bestaan getoetst.
+- [x] Geen voorgestelde nieuwe paden conflicteren met bestaande.
+- [x] Open beslissingen (§11) afgehandeld door maintainer (2026-05-02) — vraag 5 voorlopig op default.
+- [ ] ADR-template definitief vastgesteld (vraag 5).
+- [ ] Migratie fase 1 omgezet naar uitvoerbaar PR-plan (`docs/plans/docs-restructure-phase-1.md`).