From 90ee1226412beea56ce6da5d6f11b8d820a0b5ef Mon Sep 17 00:00:00 2001
From: Madhura68 <janpetervisser2@gmail.com>
Date: Sun, 3 May 2026 00:56:03 +0200
Subject: [PATCH] docs(taxonomy): move design/api/qa/backlog/assets into
 folders

---
 CLAUDE.md                                     | 18 ++++++------
 README.md                                     | 12 ++++----
 docs/INDEX.md                                 | 12 ++++----
 docs/agent-instruction-audit.md               | 22 +++++++--------
 docs/{api.md => api/rest-contract.md}         |  0
 docs/architecture.md                          |  2 +-
 docs/{ => assets}/erd.svg                     |  0
 docs/{ => assets}/icons.html                  |  0
 docs/{backlog.md => backlog/index.md}         | 14 +++++-----
 .../product-historical.md}                    |  0
 docs/{ => design}/md3-color-scheme.md         |  0
 docs/{ => design}/styling.md                  |  0
 docs/obsidian-authoring.md                    |  2 +-
 docs/patterns/claude-question-channel.md      |  2 +-
 docs/patterns/dialog.md                       |  4 +--
 docs/patterns/prisma-client.md                |  6 ++--
 docs/patterns/qr-login.md                     |  2 +-
 docs/plans/M10-qr-pairing-login.md            |  8 +++---
 docs/plans/M11-claude-questions.md            |  8 +++---
 .../2026-04-27-claude-md-workflow-update.md   |  8 +++---
 .../2026-04-27-insert-milestone-tool.md       |  6 ++--
 .../archive/2026-04-27-m8-realtime-solo.md    |  4 +--
 docs/plans/docs-restructure-pbi-spec.md       | 28 +++++++++----------
 docs/plans/tweede-claude-agent-planning.md    |  2 +-
 docs/{test-plan.md => qa/api-test-plan.md}    |  0
 docs/specs/dialogs/pbi.md                     |  2 +-
 docs/specs/dialogs/story.md                   |  2 +-
 docs/specs/dialogs/task.md                    |  2 +-
 28 files changed, 83 insertions(+), 83 deletions(-)
 rename docs/{api.md => api/rest-contract.md} (100%)
 rename docs/{ => assets}/erd.svg (100%)
 rename docs/{ => assets}/icons.html (100%)
 rename docs/{backlog.md => backlog/index.md} (98%)
 rename docs/{product-backlog.md => backlog/product-historical.md} (100%)
 rename docs/{ => design}/md3-color-scheme.md (100%)
 rename docs/{ => design}/styling.md (100%)
 rename docs/{test-plan.md => qa/api-test-plan.md} (100%)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6d36bd4..11e4d78 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,11 +26,11 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over
 |---|---|
 | `docs/specs/functional.md` | Acceptatiecriteria, randgevallen, user flows |
 | `docs/architecture.md` | Stack, datamodel, Prisma schema, Zustand stores |
-| `docs/backlog.md` | Welke task bouwen, volgorde, "done when"-criteria |
+| `docs/backlog/index.md` | Welke task bouwen, volgorde, "done when"-criteria |
 | `docs/specs/personas.md` | Lars (primair), Dina, Remi — gebruik bij UI-beslissingen |
-| `docs/product-backlog.md` | Historische domein-backlog (referentie); seed wordt sinds ST-004 gegenereerd uit `backlog.md` via `prisma/seed-data/parse-backlog.ts` |
-| `docs/api.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
-| `docs/styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
+| `docs/backlog/product-historical.md` | Historische domein-backlog (referentie); seed wordt sinds ST-004 gegenereerd uit `backlog.md` via `prisma/seed-data/parse-backlog.ts` |
+| `docs/api/rest-contract.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
+| `docs/design/styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
 | `docs/agent-instruction-audit.md` | Waarom de agent-instructies zijn aangescherpt; checklist voor toekomstige wijzigingen |
 | `docs/plans/<milestone-key>-*.md` | Implementatieplan per milestone — Bestanden, Stappen, Aandachtspunten, Verificatie. Lees vóór je aan een ST begint. Milestone-key matcht backlog-header (`M9`, `M3.5`, `PBI-9`, …). |
 | [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule |
@@ -61,7 +61,7 @@ Werken aan een task kan via twee tracks. Track A heeft de voorkeur als je in Cla
 
 1. Lees de task in `backlog.md`
 2. Zoek de bijbehorende feature-spec in `functional.md`
-3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/styling.md` als dat van toepassing is
+3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/design/styling.md` als dat van toepassing is
 4. Bouw — test — verifieer de "Done when"-criteria
 5. Vraag of de code correct is
 6. Commit (zie Commit Strategy hieronder)
@@ -152,7 +152,7 @@ Volledige Zod-schema in `lib/env.ts`. `.env.example` is de canonieke lijst voor
 - **Docs-sync:** elke gedrags-, dependency-, API- of deploymentwijziging werkt README, relevante docs en patterns bij in dezelfde change
 - **Entity codes:** gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
 - **Status-enums op API:** lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie uitsluitend via `lib/task-status.ts`-mappers — nooit ad-hoc `.toLowerCase()` elders
-- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/api.md`
+- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/api/rest-contract.md`
 - **Tests volgen contract:** bij een API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` mee — een test die rood gaat omdat de oude waarde wordt verwacht is een onvolledige wijziging, niet een "kapotte test"
 - **Dev port:** `npm run dev` draait altijd op **3000**. Een `predev`-hook killt vooraf elk proces op 3000 (stale Next.js dev-server, vorige sessie) zodat sessies, cookies en MCP-config consistent op één poort werken. Wijk hier niet van af — geen `-p 3001` o.i.d. tenzij je expliciet twee dev-servers naast elkaar wil draaien
 
@@ -328,7 +328,7 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh
 
 - **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
+- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/api/rest-contract.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)
 
@@ -336,11 +336,11 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh
 
 ## Definition of Done (MVP)
 
-M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog.md`.
+M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog/index.md`.
 
 - [ ] Alle 62 tasks (ST-001 t/m ST-612) afgerond
 - [ ] Volledige Lars-flow zonder fouten (ST-612)
-- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/api.md`)
+- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/api/rest-contract.md`)
 - [ ] Demo-gebruiker heeft geen schrijfrechten
 - [ ] App opzetbaar via README zonder extra hulp
 - [ ] CI/CD actief — falende build blokkeert merge
diff --git a/README.md b/README.md
index 0630527..4419132 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ npx prisma db push
 npm run db:erd
 ```
 
-Deze command voert lokaal `prisma generate` uit. Daardoor worden zowel de Prisma Client als `docs/erd.svg` opnieuw opgebouwd.
+Deze command voert lokaal `prisma generate` uit. Daardoor worden zowel de Prisma Client als `docs/assets/erd.svg` opnieuw opgebouwd.
 
 In CI en deployment wordt bewust alleen de Prisma Client gegenereerd met `prisma generate --generator client`. Het ERD-diagram gebruikt Mermaid/Puppeteer en wordt daarom niet in GitHub Actions of Vercel gegenereerd.
 
@@ -155,11 +155,11 @@ Verwacht: alle 69 tests slagen, 0 failures.
 bash scripts/test-api.sh
 ```
 
-De curl-tests dekken alle 7 API-endpoints: auth (401), demo-blokkering (403), inputvalidatie (400) en happy paths. Zie `docs/test-plan.md` voor het volledige testplan.
+De curl-tests dekken alle 7 API-endpoints: auth (401), demo-blokkering (403), inputvalidatie (400) en happy paths. Zie `docs/qa/api-test-plan.md` voor het volledige testplan.
 
 ## Database
 
-![ERD](./docs/erd.svg)
+![ERD](./docs/assets/erd.svg)
 
 De databasevisualisatie wordt lokaal gegenereerd uit `prisma/schema.prisma` via `prisma-erd-generator`.
 
@@ -169,7 +169,7 @@ Handmatige generatie:
 npm run db:erd
 ```
 
-Tijdens lokale development draait `npm run dev` naast Next.js ook `npm run db:erd:watch`. Bij wijzigingen in `prisma/schema.prisma` wordt `docs/erd.svg` automatisch opnieuw gegenereerd.
+Tijdens lokale development draait `npm run dev` naast Next.js ook `npm run db:erd:watch`. Bij wijzigingen in `prisma/schema.prisma` wordt `docs/assets/erd.svg` automatisch opnieuw gegenereerd.
 
 Gebruik `npx prisma db push` alleen om het schema naar de database te synchroniseren. Gebruik `npm run db:erd` om lokaal Prisma Client en de ERD te genereren. Gebruik in CI uitsluitend `npx prisma generate --generator client`.
 
@@ -182,7 +182,7 @@ npm run dev      # lokale development server
 npm run lint     # ESLint
 npm test         # Vitest test suite
 npm run build    # productiebuild zoals Vercel die verwacht
-npm run db:erd   # Prisma Client + docs/erd.svg genereren
+npm run db:erd   # Prisma Client + docs/assets/erd.svg genereren
 ```
 
 ### Environment variables
@@ -281,5 +281,5 @@ De productieomgeving is gericht op Vercel + Neon.
 
 - [Functionele specificatie](docs/specs/functional.md)
 - [Technische architectuur](docs/architecture.md)
-- [Backlog](docs/backlog.md)
+- [Backlog](docs/backlog/index.md)
 - [Agent-instructie audit](docs/agent-instruction-audit.md)
diff --git a/docs/INDEX.md b/docs/INDEX.md
index 1c636a5..2aabc98 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -63,12 +63,12 @@ Auto-generated on 2026-05-02 from front-matter and headings.
 | Title | Path | Status | Updated |
 |---|---|---|---|
 | [Agent Instruction Audit](./agent-instruction-audit.md) | `agent-instruction-audit.md` | active | 2026-05-03 |
-| [Scrum4Me REST API](./api.md) | `api.md` | active | 2026-05-03 |
+| [Scrum4Me REST API](./api/rest-contract.md) | `api/rest-contract.md` | active | 2026-05-03 |
 | [Scrum4Me — Technische Architectuur](./architecture.md) | `architecture.md` | active | 2026-05-03 |
-| [Scrum4Me — Implementatie Backlog](./backlog.md) | `backlog.md` | active | 2026-05-03 |
-| [Material Design 3 Color Scheme Documentation](./md3-color-scheme.md) | `md3-color-scheme.md` | active | 2026-05-03 |
+| [Scrum4Me — Implementatie Backlog](./backlog/index.md) | `backlog/index.md` | active | 2026-05-03 |
+| [DevPlanner — Product Backlog](./backlog/product-historical.md) | `backlog/product-historical.md` | active | 2026-05-03 |
+| [Material Design 3 Color Scheme Documentation](./design/md3-color-scheme.md) | `design/md3-color-scheme.md` | active | 2026-05-03 |
+| [Scrum4Me — Styling & Design System](./design/styling.md) | `design/styling.md` | active | 2026-05-03 |
 | [Obsidian as Personal Authoring Layer](./obsidian-authoring.md) | `obsidian-authoring.md` | active | 2026-05-02 |
-| [DevPlanner — Product Backlog](./product-backlog.md) | `product-backlog.md` | active | 2026-05-03 |
+| [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 |
 | [Solo Paneel — Implementatie-specificatie](./solo-paneel-spec.md) | `solo-paneel-spec.md` | active | 2026-05-03 |
-| [Scrum4Me — Styling & Design System](./styling.md) | `styling.md` | active | 2026-05-03 |
-| [Scrum4Me — API Test Plan](./test-plan.md) | `test-plan.md` | active | 2026-05-03 |
diff --git a/docs/agent-instruction-audit.md b/docs/agent-instruction-audit.md
index 72c62e0..6552693 100644
--- a/docs/agent-instruction-audit.md
+++ b/docs/agent-instruction-audit.md
@@ -26,7 +26,7 @@ Dit document legt vast welke wijzigingen zijn gecontroleerd, welke documentatie
 | Reorder-acties valideren alle IDs binnen de juiste parent-scope | `actions/stories.ts`, `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `docs/patterns/sort-order.md`, `CLAUDE.md`, `AGENTS.md` |
 | Sprint afronden accepteert alleen stories uit de actieve sprint | `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `AGENTS.md` |
 | Todo-promotie gebruikt scoped todo lookup en `pbi.product_id` als bron van waarheid | `actions/todos.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `CLAUDE.md`, `AGENTS.md` |
-| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/specs/functional.md`, `docs/backlog.md`, `docs/patterns/route-handler.md` |
+| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/specs/functional.md`, `docs/backlog/index.md`, `docs/patterns/route-handler.md` |
 | `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
 | Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
 | `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/architecture.md` |
@@ -54,7 +54,7 @@ Een codewijziging is niet klaar als de documentatie een oud contract beschrijft.
 - `README.md`: setup, scripts, dependencies, deployment, API-overzicht.
 - `docs/specs/functional.md`: functionele eisen en API-contracten.
 - `docs/architecture.md`: stack, datamodel, securitymodel, env vars, deployment.
-- `docs/backlog.md`: "done when"-criteria en scope van backlog-items.
+- `docs/backlog/index.md`: "done when"-criteria en scope van backlog-items.
 - `docs/patterns/`: herbruikbare implementatiepatronen.
 - `CLAUDE.md` en `AGENTS.md`: agent-regels die de fout in de toekomst voorkomen.
 
@@ -108,7 +108,7 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow
 - **ST-509** Todo description (max 2000)
 - **ST-511** Entity codes voor Product/PBI/Story (auto-default + manual override + retry op race condition)
 - **ST-512** REST API uitgebreid met `code`, `description`, `implementation_plan` in alle endpoints
-- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/api.md`
+- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/api/rest-contract.md`
 - **PR #2 Codex-review-saga** — 8 testbestanden faalden bij de contract-flip; tests werden niet meebijgewerkt. Twee P2-issues van Codex: malformed JSON moet `400` blijven (P2.1), en `status: review` werd geaccepteerd terwijl de sprint-UI er niet mee om kan gaan (P2.2)
 - **M7: mcp** — aparte MCP-server repo (`madhura68/scrum4me-mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule
 - **lib/code.ts vs lib/code-server.ts** — gesplitst om client-bundle vrij te houden van `pg` (gaf eerst `Module not found: 'dns'` build-error)
@@ -118,13 +118,13 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow
 
 | Wijziging | Code-locatie | Documentatie bijgewerkt |
 |---|---|---|
-| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/api.md`, `CLAUDE.md` |
-| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/api.md`, `CLAUDE.md` |
-| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/api.md` |
-| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/backlog.md` (ST-511) |
-| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/api.md` |
-| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/api.md`, `CLAUDE.md` |
-| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog.md` (M7) |
+| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/api/rest-contract.md`, `CLAUDE.md` |
+| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/api/rest-contract.md`, `CLAUDE.md` |
+| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/api/rest-contract.md` |
+| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/backlog/index.md` (ST-511) |
+| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/api/rest-contract.md` |
+| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/api/rest-contract.md`, `CLAUDE.md` |
+| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog/index.md` (M7) |
 
 ## Nieuwe preventieve regels
 
@@ -148,7 +148,7 @@ API exposeert lowercase, DB houdt UPPER_SNAKE. Conversie uitsluitend via `lib/ta
 - `400`: parse-fout op `request.json()` — wikkel altijd in `try/catch`
 - `422`: zod-validatie of well-formed-maar-niet-acceptabel (bv. `task_id` van andere story)
 - `403`: demo-token op write
-- Documenteer per endpoint in `docs/api.md`
+- Documenteer per endpoint in `docs/api/rest-contract.md`
 
 ### Client/server module-boundary
 
diff --git a/docs/api.md b/docs/api/rest-contract.md
similarity index 100%
rename from docs/api.md
rename to docs/api/rest-contract.md
diff --git a/docs/architecture.md b/docs/architecture.md
index 338bbbd..504a009 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1226,7 +1226,7 @@ NODE_ENV="development"
 **CI/CD:** GitHub Actions → lint + typecheck + `prisma validate` op elke PR; Vercel deploy automatisch bij merge naar `main`
 **Database (cloud):** Neon — migraties via `prisma migrate deploy` in de Vercel build-stap
 **Database (lokaal):** Neon (gratis tier) — `npx prisma db push` synchroniseert schema
-**Prisma generatie:** CI/deployment gebruikt `prisma generate --generator client`; `npm run db:erd` is alleen lokaal en bouwt ook `docs/erd.svg`
+**Prisma generatie:** CI/deployment gebruikt `prisma generate --generator client`; `npm run db:erd` is alleen lokaal en bouwt ook `docs/assets/erd.svg`
 **Seeding:** `npx prisma db seed` laadt de testdata uit het Product Backlog document
 
 ### Deployment checklist (pre-launch)
diff --git a/docs/erd.svg b/docs/assets/erd.svg
similarity index 100%
rename from docs/erd.svg
rename to docs/assets/erd.svg
diff --git a/docs/icons.html b/docs/assets/icons.html
similarity index 100%
rename from docs/icons.html
rename to docs/assets/icons.html
diff --git a/docs/backlog.md b/docs/backlog/index.md
similarity index 98%
rename from docs/backlog.md
rename to docs/backlog/index.md
index 08ad818..3c536ce 100644
--- a/docs/backlog.md
+++ b/docs/backlog/index.md
@@ -417,8 +417,8 @@ De MVP is klaar wanneer Lars — de primaire persona — de volledige cyclus kan
   - **`PATCH /api/tasks/:id`:** accepteert lowercase `status` via mapper; retourneert lowercase
   - **Story-log metadata:** nieuwe optionele `metadata Json?` kolom op `StoryLog`; `POST /api/stories/:id/log` accepteert per type een optioneel `metadata`-veld (bv. `{ branch: 'feat/x' }`); bestaande velden ongewijzigd → backwards-compatible
   - **Foutcodes:** Zod-validatie geeft `422` (was `400`); `400` blijft voor malformed body; `401`/`403`/`404`/`500` ongewijzigd
-  - **API-documentatie:** nieuwe `docs/api.md` met endpoints, request/response, foutcodes, status-enums en curl-voorbeelden; `CLAUDE.md` verwijst ernaar
-  - Done when: `curl /api/health` werkt zonder auth; `curl /api/products/:id/claude-context` retourneert bundled JSON; PATCH/PUT routes accepteren lowercase status en geven 422 bij ongeldige body; story-log POST bewaart `metadata`; `docs/api.md` is gepubliceerd
+  - **API-documentatie:** nieuwe `docs/api/rest-contract.md` met endpoints, request/response, foutcodes, status-enums en curl-voorbeelden; `CLAUDE.md` verwijst ernaar
+  - Done when: `curl /api/health` werkt zonder auth; `curl /api/products/:id/claude-context` retourneert bundled JSON; PATCH/PUT routes accepteren lowercase status en geven 422 bij ongeldige body; story-log POST bewaart `metadata`; `docs/api/rest-contract.md` is gepubliceerd
   - **`GET /api/products`:** voeg `code` toe (naast `id`, `name`, `repo_url`); optioneel `description` en `definition_of_done`
   - **`GET /api/products/:id/next-story`:** voeg `code` toe op story; voeg per task `code` (derived `${story.code}.${index_in_story}`) en `implementation_plan` toe
   - **`GET /api/sprints/:id/tasks`:** voeg `description`, `implementation_plan` en `story_code` toe per task; voeg een derived `code`-veld per task toe (`${story.code}.${index_in_story}`)
@@ -555,7 +555,7 @@ Filtering server-side: alleen events binnen de actieve sprint van een product wa
   - Done when: twee tabs van Solo Paneel — mutatie in tab A komt binnen 1–2s in tab B zonder refresh
 
 - [x] **ST-806** Documentatie + acceptatietest
-  - Sectie "Realtime updates" in `docs/architecture.md` met diagram en filtering-regels; vermelding in `CLAUDE.md`; korte note over `/api/realtime/solo` in `docs/api.md`; handmatig E2E-scenario's gedraaid (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap)
+  - Sectie "Realtime updates" in `docs/architecture.md` met diagram en filtering-regels; vermelding in `CLAUDE.md`; korte note over `/api/realtime/solo` in `docs/api/rest-contract.md`; handmatig E2E-scenario's gedraaid (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap)
   - Done when: alle scenario's lopen door zonder onverwachte gedragingen
 
 Volledig plan in `.Plans/2026-04-27-m8-realtime-solo.md` (lokaal, niet gecommit).
@@ -649,12 +649,12 @@ Volledige flow + threat-model: `docs/patterns/qr-login.md` (op te leveren in ST-
 - [ ] **ST-1007** Desktop UI: QR-render + SSE-listener op `/login`
   - **Dependency:** `qrcode.react` (client SVG; mobileSecret blijft op desktop in JS-geheugen)
   - **`app/login/qr-login-button.tsx`:** Client Component; klik → POST `pair/start` (`credentials: 'same-origin'` zodat `s4m_pair`-cookie wordt geaccepteerd) → render QR met `qrUrl` (fragment-URL) → open `EventSource('/api/auth/pair/stream/<pairingId>', { withCredentials: true })` → bij `approved` event POST `pair/claim` (cookie-only) → bij succes `router.push('/dashboard')`; aftellende timer (2 min); bij timeout "Vernieuwen"-knop; cleanup bij unmount/redirect
-  - **`app/login/page.tsx`:** knop "Inloggen via mobiel" naast bestaande wachtwoord-form (MD3-tokens uit `docs/styling.md`)
+  - **`app/login/page.tsx`:** knop "Inloggen via mobiel" naast bestaande wachtwoord-form (MD3-tokens uit `docs/design/styling.md`)
   - A11y: QR heeft alt-tekst met de URL voor screenreaders/copy-paste (de hash-suffix is onderdeel van die alt-tekst, niet van de page-URL die in browsergeschiedenis komt)
   - Done when: end-to-end happy path werkt op localhost (twee browsers): A toont QR → B scant + bevestigt → A redirect naar `/dashboard` met `session.paired === true`; QR vernieuwt na expiry; geen secret zichtbaar in DevTools Network-tab onder URL-kolommen
 
 - [ ] **ST-1008** Documentatie + acceptatietest
-  - **`docs/api.md`:** drie nieuwe endpoints (start/stream/claim) met request/response, cookie-mechaniek, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`
+  - **`docs/api/rest-contract.md`:** drie nieuwe endpoints (start/stream/claim) met request/response, cookie-mechaniek, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`
   - **`docs/architecture.md`:** sectie "QR-pairing flow" met sequence-diagram + threat-model; expliciete subsectie *"Waarom geen secret in URL"* — fragments worden niet naar server gestuurd; SSE/claim authenticeren via HttpOnly cookie zodat secret-materiaal niet in access logs / reverse-proxy logs / observability-tools / browsergeschiedenis kan belanden
   - **`docs/patterns/qr-login.md`:** nieuw pattern-doc voor toekomstige features die hetzelfde unauth-SSE-via-pre-auth-cookie-patroon willen hergebruiken
   - **`CLAUDE.md`:** verwijzing naar het nieuwe pattern-doc in de patterns-tabel
@@ -702,7 +702,7 @@ Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scru
   - **`stores/notifications-store.ts`** — Zustand store volgens `solo-store.ts`-patroon: `init`, `add`, `update`, `remove`, `optimisticAnswer`, `rollbackAnswer`; selectors `openCount`, `forYouCount`
   - **`lib/realtime/use-notifications-realtime.ts`** — analoog aan `useSoloRealtime`; EventSource op `/api/realtime/notifications` met reconnect-backoff
   - **`components/notifications/notifications-bridge.tsx`** — Server Component die initial-data fetcht en aan store geeft; mount in `app/(app)/layout.tsx` naast `<SoloRealtimeBridge />`
-  - **`components/shared/notifications-bell.tsx`** — Bell-icon (Lucide) met badge in NavBar (links van avatar); MD3-tokens uit `docs/styling.md`
+  - **`components/shared/notifications-bell.tsx`** — Bell-icon (Lucide) met badge in NavBar (links van avatar); MD3-tokens uit `docs/design/styling.md`
   - **`components/notifications/notifications-sheet.tsx`** — shadcn Sheet van rechts; lijst gegroepeerd per product; story-assignee krijgt visuele *"wacht op jou"*-emphase
   - **`components/notifications/answer-modal.tsx`** — shadcn Dialog; story-context-link, vraag-tekst, RadioGroup (als options) of Textarea (free-text), submit via `useTransition` + Server Action; demo-blok met tooltip
   - Done when: bell + badge zichtbaar; klik opent Sheet met items; submit verwijdert item optimistisch; tweede tab van zelfde user ziet nieuwe vraag binnen 1-2s; demo-modus rendert maar Verstuur disabled
@@ -721,7 +721,7 @@ Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scru
   - Done when: handmatige `curl -X POST` met secret expireert oude rijen; Vercel-dashboard toont cron-config na deploy; onbevoegde call → 401
 
 - [ ] **ST-1108** Documentatie + acceptatietest
-  - **`docs/api.md`:** secties "SSE — Notifications" + "Cron — Expire questions" met curl-voorbeelden
+  - **`docs/api/rest-contract.md`:** secties "SSE — Notifications" + "Cron — Expire questions" met curl-voorbeelden
   - **`docs/architecture.md`:** sectie "Vraag-antwoord-kanaal Claude ↔ user" met Mermaid sequence-diagram + threat-model + "Waarom hergebruik scrum4me_changes-kanaal"
   - **`docs/patterns/claude-question-channel.md`:** nieuw herbruikbaar pattern-doc voor toekomstige bidirectionele async-communicatie tussen MCP-agents en interactieve users
   - **`CLAUDE.md`:** rij in Implementatiepatronen-tabel voor het nieuwe pattern
diff --git a/docs/product-backlog.md b/docs/backlog/product-historical.md
similarity index 100%
rename from docs/product-backlog.md
rename to docs/backlog/product-historical.md
diff --git a/docs/md3-color-scheme.md b/docs/design/md3-color-scheme.md
similarity index 100%
rename from docs/md3-color-scheme.md
rename to docs/design/md3-color-scheme.md
diff --git a/docs/styling.md b/docs/design/styling.md
similarity index 100%
rename from docs/styling.md
rename to docs/design/styling.md
diff --git a/docs/obsidian-authoring.md b/docs/obsidian-authoring.md
index 0ebf44f..4d7f017 100644
--- a/docs/obsidian-authoring.md
+++ b/docs/obsidian-authoring.md
@@ -163,7 +163,7 @@ Use with care:
 Avoid as canonical source:
 
 - **Canvas**, **Excalidraw** — not diff-able, not agent-readable. Keep
-  diagrams as committed SVG (`docs/erd.svg`) or as Mermaid blocks inside
+  diagrams as committed SVG (`docs/assets/erd.svg`) or as Mermaid blocks inside
   Markdown.
 
 ## Index generator interaction
diff --git a/docs/patterns/claude-question-channel.md b/docs/patterns/claude-question-channel.md
index 63f97ea..fed9fc4 100644
--- a/docs/patterns/claude-question-channel.md
+++ b/docs/patterns/claude-question-channel.md
@@ -148,7 +148,7 @@ Specifiek voor M11. Kopieer en pas aan:
 
 - Volledige flow + threat-model: `docs/architecture.md` § Vraag-
   antwoord-kanaal Claude ↔ user
-- Endpoint-contract: `docs/api.md` § Notifications + Cron
+- Endpoint-contract: `docs/api/rest-contract.md` § Notifications + Cron
 - LISTEN/NOTIFY-pattern: `app/api/realtime/solo/route.ts` (M8 ST-802) — zelfde
   ReadableStream + heartbeat + hard-close + abort-cleanup
 - M10 vs M11 keuze tussen eigen/gedeeld kanaal: zie threat-model-tabel
diff --git a/docs/patterns/dialog.md b/docs/patterns/dialog.md
index 8c71ace..751dfaf 100644
--- a/docs/patterns/dialog.md
+++ b/docs/patterns/dialog.md
@@ -28,7 +28,7 @@ Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per
 | 1.5 | **Drielaagse demo-policy** (verplicht — zie § 6) op elke write-actie. | `CLAUDE.md` "Demo-check" + `docs/architecture.md#demo-user-policy` |
 | 1.6 | Validatie via één gedeeld zod-schema (`lib/schemas/<entity>.ts`) — gebruikt door zowel form als server action. | `CLAUDE.md` "Validatie" |
 | 1.7 | Foutcodes volgen de project-conventie (§ 5). | `CLAUDE.md` "Foutcodes API" |
-| 1.8 | Geen willekeurige Tailwind-kleuren (`bg-blue-500` etc.). Alleen MD3-tokens uit `app/styles/theme.css`. | `docs/styling.md` |
+| 1.8 | Geen willekeurige Tailwind-kleuren (`bg-blue-500` etc.). Alleen MD3-tokens uit `app/styles/theme.css`. | `docs/design/styling.md` |
 
 ---
 
@@ -389,7 +389,7 @@ Reviewer en bouwer lopen deze door vóór merge:
 ## 15 — Referenties
 
 - `CLAUDE.md` — UI Library Conventions, Demo-check, Foutcodes API, Validatie
-- `docs/styling.md` — MD3-tokens, kleurklassen
+- `docs/design/styling.md` — MD3-tokens, kleurklassen
 - `docs/architecture.md` — Demo user policy, scope-helpers
 - `docs/patterns/server-action.md` — Server Action template (auth + Zod)
 - `docs/patterns/zustand-optimistic.md` — voor lijst-views die de dialog aanroepen
diff --git a/docs/patterns/prisma-client.md b/docs/patterns/prisma-client.md
index 084cbc2..bbc98a4 100644
--- a/docs/patterns/prisma-client.md
+++ b/docs/patterns/prisma-client.md
@@ -60,14 +60,14 @@ generator client {
 
 generator erd {
   provider = "prisma-erd-generator"
-  output   = "../docs/erd.svg"
+  output   = "../docs/assets/erd.svg"
 }
 ```
 
 `prisma generate` bouwt dus twee artifacts:
 
 - Prisma Client in `node_modules/@prisma/client`
-- het ERD-diagram in `docs/erd.svg`
+- het ERD-diagram in `docs/assets/erd.svg`
 
 Gebruik volledige `prisma generate` alleen lokaal. De ERD-generator gebruikt Mermaid/Puppeteer en mag niet in CI of Vercel draaien.
 
@@ -78,7 +78,7 @@ Gebruik volledige `prisma generate` alleen lokaal. De ERD-generator gebruikt Mer
 | `npx prisma db push` | Schema synchroniseren naar de database |
 | `npx prisma db seed` | Seeddata laden |
 | `npx prisma generate --generator client` | Alleen Prisma Client genereren; gebruiken in CI/deployment |
-| `npm run db:erd` | `prisma generate`: Prisma Client en `docs/erd.svg` genereren |
+| `npm run db:erd` | `prisma generate`: Prisma Client en `docs/assets/erd.svg` genereren |
 | `npm run db:erd:watch` | `prisma/schema.prisma` watchen en ERD opnieuw genereren |
 | `npm run dev` | Next.js dev server plus ERD watcher starten |
 
diff --git a/docs/patterns/qr-login.md b/docs/patterns/qr-login.md
index 2fb91f4..1a6160a 100644
--- a/docs/patterns/qr-login.md
+++ b/docs/patterns/qr-login.md
@@ -99,6 +99,6 @@ Drie tijden in escalerende volgorde, alle korter dan de reguliere sessie:
 ## Referenties
 
 - Volledige flow + threat-model: `docs/architecture.md` § QR-pairing flow
-- Endpoint-contract: `docs/api.md` § Auth — QR-pairing
+- Endpoint-contract: `docs/api/rest-contract.md` § Auth — QR-pairing
 - LISTEN/NOTIFY-pattern: `app/api/realtime/solo/route.ts` (M8 ST-802) — zelfde
   ReadableStream + heartbeat + hard-close + abort-cleanup, alleen ander channel
diff --git a/docs/plans/M10-qr-pairing-login.md b/docs/plans/M10-qr-pairing-login.md
index 13e70d3..a88b7ec 100644
--- a/docs/plans/M10-qr-pairing-login.md
+++ b/docs/plans/M10-qr-pairing-login.md
@@ -776,7 +776,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
     <QrLoginButton />
     ```
 
-    MD3-tokens uit `docs/styling.md`; geen willekeurige Tailwind-kleuren.
+    MD3-tokens uit `docs/design/styling.md`; geen willekeurige Tailwind-kleuren.
 
 4. **A11y**: QR-component krijgt `aria-label="QR-code voor mobiel inloggen"` en de URL wordt visueel als kopieer-bare tekst onder de QR getoond zodat screenreaders en gebruikers met cameraproblemen de URL handmatig kunnen openen.
 
@@ -797,7 +797,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
 ## ST-1008 — Documentatie + acceptatietest
 
 **Bestanden**
-- `docs/api.md` — drie nieuwe endpoints
+- `docs/api/rest-contract.md` — drie nieuwe endpoints
 - `docs/architecture.md` — sectie "QR-pairing flow" + threat-model
 - `docs/patterns/qr-login.md` — nieuw pattern-doc
 - `CLAUDE.md` — verwijzing naar het pattern-doc in de patterns-tabel
@@ -805,7 +805,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
 
 **Stappen**
 
-1. **`docs/api.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
+1. **`docs/api/rest-contract.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
 
 2. **`docs/architecture.md`** — sectie *"QR-pairing flow"* met:
     - Sequence-diagram (mermaid of ASCII analoog aan M8)
@@ -835,7 +835,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
     7. **Secret niet in access logs** — controleer Vercel runtime-logs (via `mcp__a1fa0fcf-…__get_runtime_logs`) en lokale dev-logs; zoek op de secret-string en op `s=`-substrings; verwacht: 0 hits
 
 **Aandachtspunten**
-- Zorg dat de runtime-logs MCP-controle in `docs/test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
+- Zorg dat de runtime-logs MCP-controle in `docs/qa/api-test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
 - `docs/patterns/qr-login.md` mag refereren naar bestaande pattern-docs (iron-session, route-handler) zonder ze te dupliceren.
 
 **Verificatie**
diff --git a/docs/plans/M11-claude-questions.md b/docs/plans/M11-claude-questions.md
index 72c54ce..2de6f28 100644
--- a/docs/plans/M11-claude-questions.md
+++ b/docs/plans/M11-claude-questions.md
@@ -288,7 +288,7 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
 
 **Aandachtspunten**
 - Bell-icon en avatar moeten visueel balanceren — hoogte/padding gelijktrekken
-- MD3-tokens uit `docs/styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
+- MD3-tokens uit `docs/design/styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
 - Optimistic-answer in store: voor het Server Action-resultaat zet item op pending; bij error rollback met sonner-error-toast
 - Sheet-content blijft open zodat de user meerdere vragen achter elkaar kan beantwoorden (zelfde patroon als ST-358 openstaande-stories-sheet)
 - ARIA: bell-icon heeft `aria-label="Notificaties — N open vragen"`, badge `role="status"`
@@ -378,16 +378,16 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
 ## ST-1108 — Documentatie + acceptatietest
 
 **Bestanden**
-- `docs/api.md` — secties "SSE — Notifications" + "Cron — Expire questions"
+- `docs/api/rest-contract.md` — secties "SSE — Notifications" + "Cron — Expire questions"
 - `docs/architecture.md` — sectie "Vraag-antwoord-kanaal" met sequence-diagram
 - `docs/patterns/claude-question-channel.md` — herbruikbaar pattern-doc
-- `docs/backlog.md` — M11-tabel-rij + M11-sectie
+- `docs/backlog/index.md` — M11-tabel-rij + M11-sectie
 - `prisma/seed-data/parse-backlog.ts` — `M11: 'ACTIVE'`, `M10: 'COMPLETED'`, `M3.5: 'COMPLETED'`
 - `CLAUDE.md` — pattern-doc verwijzing in Implementatiepatronen-tabel
 
 **Stappen**
 
-1. Backlog-tabel-rij + M11-sectie in `docs/backlog.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
+1. Backlog-tabel-rij + M11-sectie in `docs/backlog/index.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
 
 2. `docs/architecture.md` § "Vraag-antwoord-kanaal":
    - Mermaid sequence-diagram: Claude → MCP → DB → trigger → SSE → user → Server Action → DB → trigger → polling-tool
diff --git a/docs/plans/archive/2026-04-27-claude-md-workflow-update.md b/docs/plans/archive/2026-04-27-claude-md-workflow-update.md
index fc160a3..32af0f8 100644
--- a/docs/plans/archive/2026-04-27-claude-md-workflow-update.md
+++ b/docs/plans/archive/2026-04-27-claude-md-workflow-update.md
@@ -47,7 +47,7 @@ Voeg toe onder de bestaande tabel:
 |---|---|
 | `https://github.com/madhura68/scrum4me-mcp` | MCP-server repo: tools, prompts, schema-sync workflow |
 
-(`docs/api.md` staat er al — laten staan.)
+(`docs/api/rest-contract.md` staat er al — laten staan.)
 
 ### 2. Sectie "Waar te beginnen" — herschrijven
 
@@ -65,7 +65,7 @@ Vervang de 7-stap manual loop door een dual-track:
 ```
 
 **Track B — manueel (Codex of zonder MCP)**:
-- Lees task in `docs/backlog.md`
+- Lees task in `docs/backlog/index.md`
 - Volg verder de bestaande 7-stappen-loop
 
 ### 3. Sectie "Implementatiepatronen" — uitbreiden
@@ -83,7 +83,7 @@ Voeg toe aan de bestaande lijst:
 
 - **Entity codes**: gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
 - **Status-enums op API**: lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie via `lib/task-status.ts`-mappers — nooit ad-hoc lowercase elders
-- **Foutcodes API**: `400` alleen voor malformed JSON-body (parse-fout); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteren in `docs/api.md`
+- **Foutcodes API**: `400` alleen voor malformed JSON-body (parse-fout); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteren in `docs/api/rest-contract.md`
 - **Tests volgen contract**: bij API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` bijgewerkt worden — een falende test op review betekent niet dat de tests "stuk zijn" maar dat de wijziging onvolledig is
 
 ### 5. Nieuwe sectie "MCP-integratie" — toevoegen vóór "Definition of Done"
@@ -118,7 +118,7 @@ stilletjes breekt op runtime.
 
 ### 6. Sectie "Definition of Done" — kop verduidelijken
 
-Wijzig `## Definition of Done` → `## Definition of Done (MVP)` en voeg eronder een korte zin toe: *"M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog.md`."*
+Wijzig `## Definition of Done` → `## Definition of Done (MVP)` en voeg eronder een korte zin toe: *"M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog/index.md`."*
 
 ## Bijwerken van auditdoc
 
diff --git a/docs/plans/archive/2026-04-27-insert-milestone-tool.md b/docs/plans/archive/2026-04-27-insert-milestone-tool.md
index 3a45f1b..cf3eb65 100644
--- a/docs/plans/archive/2026-04-27-insert-milestone-tool.md
+++ b/docs/plans/archive/2026-04-27-insert-milestone-tool.md
@@ -17,12 +17,12 @@ Eén commando dat een specifieke milestone (PBI + stories + tasks) uit de backlo
 
 Twee bronnen denkbaar:
 - **`.Plans/<datum>-<slug>.md`** — freeform plan-tekst, niet gestructureerd, niet gecommit
-- **`docs/backlog.md`** — al strict gestructureerd, gecommit, single source of truth voor alle bestaande seed-pipelines
+- **`docs/backlog/index.md`** — al strict gestructureerd, gecommit, single source of truth voor alle bestaande seed-pipelines
 
 Voorstel: het script leest de **backlog**. Workflow blijft natuurlijk:
 
 1. Plan schrijven naar `.Plans/<naam>.md` (lokaal, draft)
-2. Milestone-sectie + stories formaliseren in `docs/backlog.md` (PR)
+2. Milestone-sectie + stories formaliseren in `docs/backlog/index.md` (PR)
 3. Na merge: `npm run db:insert-milestone -- M8 [--product SCRUM4ME]`
 
 Eén canonical bron, geen ambiguïteit, en de bestaande parser doet 90% van het werk al.
@@ -49,7 +49,7 @@ Default product code: SCRUM4ME
 Logica:
 1. Parse args; valideer dat milestone-key matcht `^M[\d.]+$`
 2. `loadBacklog(repoRoot, { strict: false })`
-3. Zoek milestone op `key`; faal helder met "milestone <key> not found in docs/backlog.md" als ie er niet in staat
+3. Zoek milestone op `key`; faal helder met "milestone <key> not found in docs/backlog/index.md" als ie er niet in staat
 4. Lookup product via `code` (default `SCRUM4ME`); faal als niet gevonden
 5. Upsert PBI:
    - `where: { product_id_code: { product_id, code: milestone.key } }`
diff --git a/docs/plans/archive/2026-04-27-m8-realtime-solo.md b/docs/plans/archive/2026-04-27-m8-realtime-solo.md
index a104099..042c084 100644
--- a/docs/plans/archive/2026-04-27-m8-realtime-solo.md
+++ b/docs/plans/archive/2026-04-27-m8-realtime-solo.md
@@ -134,13 +134,13 @@ Strategie: combineer (a) trigger zet `product_id` en `assignee_id` in de payload
 ### ST-806 Documentatie + acceptatietest
 - Update `docs/architecture.md`: nieuwe sectie "Realtime updates" met diagram en filtering-regels
 - Update `CLAUDE.md`: vermelding dat Solo Paneel realtime is + dat MCP-writes vanzelf doorkomen
-- Update `docs/api.md`: korte note over `/api/realtime/solo` (Bearer auth, SSE format)
+- Update `docs/api/rest-contract.md`: korte note over `/api/realtime/solo` (Bearer auth, SSE format)
 - E2E-acceptatie: lijst van scenario's (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap) handmatig getest
 - Done when: scenario's lopen door zonder onverwachte gedragingen
 
 ## Backlog-edits
 
-In `docs/backlog.md`:
+In `docs/backlog/index.md`:
 
 1. **Milestone-overzicht** — rij toevoegen onder M7:
    ```
diff --git a/docs/plans/docs-restructure-pbi-spec.md b/docs/plans/docs-restructure-pbi-spec.md
index e25b4a5..333ffc9 100644
--- a/docs/plans/docs-restructure-pbi-spec.md
+++ b/docs/plans/docs-restructure-pbi-spec.md
@@ -267,15 +267,15 @@ pbi:
           description: "8 spec/backlog/styling files at docs/ root."
           implementation_plan: |
             git mv docs/architecture.md     docs/architecture.md
-            git mv docs/backlog.md          docs/backlog.md
+            git mv docs/backlog/index.md          docs/backlog/index.md
             git mv docs/specs/functional.md  docs/specs/functional.md
             git mv docs/specs/dialogs/pbi.md       docs/specs/dialogs/pbi.md
             git mv docs/specs/personas.md         docs/specs/personas.md
-            git mv docs/product-backlog.md  docs/product-backlog.md
+            git mv docs/backlog/product-historical.md  docs/backlog/product-historical.md
             git mv docs/specs/dialogs/story.md     docs/specs/dialogs/story.md
-            git mv docs/styling.md          docs/styling.md
+            git mv docs/design/styling.md          docs/design/styling.md
             git mv docs/specs/dialogs/task.md      docs/specs/dialogs/task.md
-            git mv docs/test-plan.md        docs/test-plan.md
+            git mv docs/qa/api-test-plan.md        docs/qa/api-test-plan.md
             # update every internal link
             grep -rln "" docs/ CLAUDE.md AGENTS.md README.md \
               | xargs sed -i '' 's|||g'
@@ -286,8 +286,8 @@ pbi:
         - title: "Lowercase api.md and MD3 file"
           description: "Two files use non-kebab capitalization."
           implementation_plan: |
-            git mv docs/api.md docs/api.md
-            git mv docs/md3-color-scheme.md docs/md3-color-scheme.md
+            git mv docs/api/rest-contract.md docs/api/rest-contract.md
+            git mv docs/design/md3-color-scheme.md docs/design/md3-color-scheme.md
             grep -rln "API\.md\|MD3_Color_Scheme" docs/ CLAUDE.md AGENTS.md README.md \
               | xargs sed -i '' 's|API\.md|api.md|g; s|md3-color-scheme|md3-color-scheme|g'
             npm run docs:index
@@ -371,14 +371,14 @@ pbi:
         - title: "Move design + api + qa + backlog + assets"
           description: "Bulk move per topic."
           implementation_plan: |
-            git mv docs/styling.md          docs/design/styling.md
-            git mv docs/md3-color-scheme.md docs/design/md3-color-scheme.md
-            git mv docs/api.md              docs/api/rest-contract.md
-            git mv docs/test-plan.md        docs/qa/api-test-plan.md
-            git mv docs/backlog.md          docs/backlog/index.md
-            git mv docs/product-backlog.md  docs/backlog/product-historical.md
-            git mv docs/erd.svg             docs/assets/erd.svg
-            git mv docs/icons.html          docs/assets/icons.html
+            git mv docs/design/styling.md          docs/design/styling.md
+            git mv docs/design/md3-color-scheme.md docs/design/md3-color-scheme.md
+            git mv docs/api/rest-contract.md              docs/api/rest-contract.md
+            git mv docs/qa/api-test-plan.md        docs/qa/api-test-plan.md
+            git mv docs/backlog/index.md          docs/backlog/index.md
+            git mv docs/backlog/product-historical.md  docs/backlog/product-historical.md
+            git mv docs/assets/erd.svg             docs/assets/erd.svg
+            git mv docs/assets/icons.html          docs/assets/icons.html
             # update links — sed sweep
             commit: docs(taxonomy): move design/api/qa/backlog/assets into folders
           priority: 2
diff --git a/docs/plans/tweede-claude-agent-planning.md b/docs/plans/tweede-claude-agent-planning.md
index a2995bc..3481519 100644
--- a/docs/plans/tweede-claude-agent-planning.md
+++ b/docs/plans/tweede-claude-agent-planning.md
@@ -214,7 +214,7 @@ Korte prompt-flow:
    - `docs/specs/functional.md` (functioneel kader)
    - `docs/architecture.md` (technisch kader)
    - `docs/patterns/*.md` (relevante patterns op basis van target-titel/-beschrijving)
-   - `docs/styling.md` als target UI-werk betreft
+   - `docs/design/styling.md` als target UI-werk betreft
 4. Bedenk children:
    - Voor `STORY`-target: 3-7 taken met titel, korte beschrijving, `implementation_plan` (verwijst naar relevante patterns + bestanden), priority
    - Voor `PBI`-target: 2-5 stories met titel, beschrijving in user-story-format, acceptance_criteria, priority
diff --git a/docs/test-plan.md b/docs/qa/api-test-plan.md
similarity index 100%
rename from docs/test-plan.md
rename to docs/qa/api-test-plan.md
diff --git a/docs/specs/dialogs/pbi.md b/docs/specs/dialogs/pbi.md
index 2f453c5..bd04ce3 100644
--- a/docs/specs/dialogs/pbi.md
+++ b/docs/specs/dialogs/pbi.md
@@ -125,4 +125,4 @@ Specifiek voor PbiDialog (boven op de algemene out-of-scope-lijst in `docs/patte
 - `lib/task-status.ts` — `PbiStatusApi`-mapper
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
 - `docs/architecture.md` — datamodel `Pbi`
-- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/specs/dialogs/story.md b/docs/specs/dialogs/story.md
index 69e957b..137f935 100644
--- a/docs/specs/dialogs/story.md
+++ b/docs/specs/dialogs/story.md
@@ -168,4 +168,4 @@ Specifiek voor StoryDialog (boven op de algemene out-of-scope-lijst in `docs/pat
 - `lib/task-status.ts` — status-enum-mapper
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
 - `docs/architecture.md` — datamodel `Story`
-- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/specs/dialogs/task.md b/docs/specs/dialogs/task.md
index 7c4a636..5eb64aa 100644
--- a/docs/specs/dialogs/task.md
+++ b/docs/specs/dialogs/task.md
@@ -131,5 +131,5 @@ Specifiek voor TaskDialog (boven op de algemene out-of-scope-lijst in `docs/patt
 
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth voor alles wat hier niet beschreven is)
 - `docs/architecture.md` — datamodel `Task`
-- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren
 - `lib/task-status.ts` — enum-mapper DB ↔ API