docs: reorganize into project/ + reference/, expand Storybook Foundations

Move working docs (backlog, prd, roadmap) under docs/project/ and durable docs (architecture ADRs, guides, audits) under docs/reference/; add a docs/README.md index. Update every path reference in code comments, CLAUDE.md, READMEs, and the new-ssp skill. Expand the Storybook Foundations curriculum (Overview, BDD, i18n; rename Layers→Domain-Driven Design) and reorder the sidebar. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-20 20:33:32 +02:00
parent 55a0a2d166
commit d4e5a76873
40 changed files with 1699 additions and 1087 deletions
@@ -1,6 +1,6 @@
 # Showcase roadmap — superseded

-**This roadmap is superseded by [`docs/backlog/`](backlog/README.md)** (2026-07-02).
+**This roadmap is superseded by [`docs/project/backlog/`](backlog/README.md)** (2026-07-02).

 The backlog absorbs and corrects this document: its Storybook-as-curriculum track became
 WP-14/15 (+ per-invariant MDX pages in WP-05/07/08/13/17), its enforcement track became
@@ -5,7 +5,7 @@ design-system fidelity, DDD/FP consistency, Storybook as curriculum, and WCAG co
 with automated gates. Source: the architecture/CIBG/a11y audit of 2026-07-02 (plan:
 "Showcase hardening").

-This backlog **supersedes `docs/SHOWCASE-ROADMAP.md`**.
+This backlog **supersedes `docs/project/SHOWCASE-ROADMAP.md`**.

 ## Session protocol

@@ -55,7 +55,7 @@ build", so every story added or changed by later WPs is automatically covered.
 6. Run locally against a fresh `build-storybook`; triage violations: fix trivial ones
   (labels, roles, contrast via `--rhc-*` tokens); anything structural gets the escape
   hatch + comment + WP cross-ref.
-7. Update `docs/backlog/README.md`: GREEN now includes `npm run test-storybook:ci`.
+7. Update `docs/project/backlog/README.md`: GREEN now includes `npm run test-storybook:ci`.

 ## Acceptance criteria

@@ -11,7 +11,7 @@ Phase 0 — a pure move of wiring, no behavior change.

 ## Read first

- `CLAUDE.md` §1, `docs/ARCHITECTURE.md`
+- `CLAUDE.md` §1, `docs/reference/architecture/ARCHITECTURE.md`
 - `eslint.config.mjs`
 - `src/app/registratie/ui/registratie-wizard/registratie-wizard.component.ts` (lines
  ~18-19: `BrpAdapter`/`parseBrpAddress`, `DuoAdapter`/`parseDuoLookup`)
@@ -38,7 +38,7 @@ Phase 0 — a pure move of wiring, no behavior change.
  lookups move behind a registratie `application/` facade (command or store methods)
 - `src/app/herregistratie/ui/intake-wizard/intake-wizard.component.ts` — policy resource
  moves behind **new** `src/app/herregistratie/application/` (folder doesn't exist yet)
- `docs/ARCHITECTURE.md` — fix "three contexts, four layers" → six contexts
+- `docs/reference/architecture/ARCHITECTURE.md` — fix "three contexts, four layers" → six contexts
  (shared, auth, registratie, herregistratie, brief, showcase), five layers (+ contracts);
  add the showcase sanction
 - `CLAUDE.md` §1 — add `brief` to the context list; note the showcase sanction
@@ -10,7 +10,7 @@ principle (every response through a hand-written `parse*` returning `Result`).

 ## Read first

- `CLAUDE.md` §3 + §4; `docs/architecture/0001-bff-lite-decision-dtos.md`
+- `CLAUDE.md` §3 + §4; `docs/reference/architecture/0001-bff-lite-decision-dtos.md`
 - `src/app/registratie/infrastructure/applications.adapter.ts` (+ its spec — the pattern
  to copy)
 - The three offenders below
@@ -5,7 +5,7 @@ Phase: 1 — FP/DDD core

 ## Why

-Docs (`docs/fp-tea-atomic-design.md`, ARCHITECTURE §2c) teach `createStore` as THE
+Docs (`docs/reference/fp-tea-atomic-design.md`, ARCHITECTURE §2c) teach `createStore` as THE
 wiring, but the wizard pages hand-wire `signal(model)` + local `dispatch()` — juniors see
 two idioms and copy the wrong one. Machine naming also drifts:
 `change-request.machine.ts` exports bare `State`/`Msg`; `upload.machine.ts` exports
@@ -14,7 +14,7 @@ two idioms and copy the wrong one. Machine naming also drifts:
 ## Read first

 - `src/app/shared/application/store.ts` (`createStore`) + its spec
- `docs/fp-tea-atomic-design.md` Part on TEA-in-Angular
+- `docs/reference/fp-tea-atomic-design.md` Part on TEA-in-Angular
 - All `*.machine.ts` files (6) and their UI wiring sites (wizard components/pages)

 ## Decisions (pre-made, don't relitigate)
@@ -59,7 +59,7 @@ no spec despite "domain and pure logic must have a spec" (CLAUDE.md §5).
      (`draft-sync.spec.ts`, `submit-change-request.spec.ts`).
 - [x] `map3` removed (found in `shared/application/remote-data.ts`, not
      `shared/kernel/fp.ts` as the WP text guessed — updated the three docs that
-      mentioned it: CLAUDE.md, `docs/ARCHITECTURE.md`, `remote-data.mdx`). The
+      mentioned it: CLAUDE.md, `docs/reference/architecture/ARCHITECTURE.md`, `remote-data.mdx`). The
      `variant` input on `confirmation.component.ts` no longer exists — already
      cleaned up before this WP ran; nothing to do.
 - [x] CLAUDE.md rule added (`Conventions` — DatePipe in templates, `formatDatumNl` in
@@ -35,7 +35,7 @@ the list-family rationale to document.

 ## Read first

- `docs/architecture/0003-*.md` (ADR-0003 — the token-bridge rationale this extends)
+- `docs/reference/architecture/0003-*.md` (ADR-0003 — the token-bridge rationale this extends)
 - The audit's gap list (below)

 ## Decisions (pre-made, don't relitigate)
@@ -41,7 +41,7 @@ Three app-level gaps close the WCAG story:
 - `src/app/app.config.ts` + a new small `shared/` focus-on-navigation service
 - `eslint.config.mjs`, `package.json` (angular-eslint)
 - Any template the new lint rules flag
- New `docs/wcag-checklist.md`
+- New `docs/reference/wcag-checklist.md`
 - New `src/docs/a11y.mdx` — title `Foundations/Accessibility`

 ## Steps
@@ -50,7 +50,7 @@ Three app-level gaps close the WCAG story:
   focus lands on the new page's heading).
 2. Add angular-eslint; enable the template rules on inline templates; plant a bad
   pattern, see it fail, remove it; fix real hits.
-3. `docs/wcag-checklist.md`: manual checks per page (dashboard, wizards, brief, login) —
+3. `docs/reference/wcag-checklist.md`: manual checks per page (dashboard, wizards, brief, login) —
   keyboard walk & focus order, no traps, 200% zoom/reflow, NVDA or VoiceOver pass,
   visible focus, error announcement; status columns (page × check).
 4. `src/docs/a11y.mdx`: the layered approach — axe gate (WP-01) + template lint + play
@@ -75,7 +75,7 @@ Three app-level gaps close the WCAG story:
  setup. Less code to hand-maintain, same coverage plus more.
 - The dashboard's checklist pass surfaced a **real bug**: `aanvraag-block`'s warning
  `app-alert` (two `app-button` actions) overflows the viewport at 320px — its
-  `.feedback` flex row doesn't wrap. Documented in `docs/wcag-checklist.md` with the
+  `.feedback` flex row doesn't wrap. Documented in `docs/reference/wcag-checklist.md` with the
  root cause, **not fixed** — fixing live component CSS found via the checklist is the
  "full manual audit" scope this WP's Out-of-scope section explicitly defers, not this
  WP's own deliverable. Flagged here so it isn't lost.
@@ -30,9 +30,9 @@ a real foundation to extend.

 ## Read first

- `docs/architecture/0002-user-groups-and-bounded-contexts.md` (the `Principal`
+- `docs/reference/architecture/0002-user-groups-and-bounded-contexts.md` (the `Principal`
  union, identity-vs-authorization split — see the deviation noted below)
- `docs/prd/0002-attribute-based-access-control.md` §5a, §6, §7, §9-P1
+- `docs/project/prd/0002-attribute-based-access-control.md` §5a, §6, §7, §9-P1
 - `backend/src/BigRegister.Api/Domain/Authorization/Authz.cs` (new — the single
  authorization helper)
 - `backend/src/BigRegister.Api/Data/BriefStore.cs` (`Review` — now delegates its
@@ -31,7 +31,7 @@ speculatively.
  `static Dictionary` + `lock`
 - `backend/src/BigRegister.Api/Data/SeedData.cs` (current in-memory seed — becomes
  a first-run DB seed)
- `docs/architecture/0001-bff-lite-decision-dtos.md` (confirm this WP doesn't touch
+- `docs/reference/architecture/0001-bff-lite-decision-dtos.md` (confirm this WP doesn't touch
  the decision-DTO contracts — persistence is purely behind the existing store
  interfaces)

@@ -14,11 +14,11 @@ WP-25, editor WP-26) reads what this WP serves.

 ## Read first

- `docs/prd` — the Brief v2 PRD §2a/§3 (two axes, OrgTemplate model, invariants)
+- `docs/project/prd` — the Brief v2 PRD §2a/§3 (two axes, OrgTemplate model, invariants)
 - `backend/src/BigRegister.Api/Data/BriefStore.cs` (store idiom + `BriefSeed`)
 - `backend/src/BigRegister.Api/Domain/Authorization/Authz.cs` (emit+enforce single source)
 - `backend/src/BigRegister.Api/Data/AppDbContext.cs` (JSON-column precedent, WP-22)
- `docs/backlog/WP-18-abac-capability-spine.md` (how the capability spine works)
+- `docs/project/backlog/WP-18-abac-capability-spine.md` (how the capability spine works)

 ## Decisions (pre-made, don't relitigate)

@@ -15,7 +15,7 @@ domain model, `brief.machine.ts`, and every `BriefMsg` stay byte-identical.
 - PRD Brief v2 §2b (fidelity note), §4, §10; the sample `voorbeeldbrief-inschrijving.pdf`
 - `src/app/brief/ui/letter-composer/letter-composer.component.ts` (the `canEdit` pivot)
 - `src/app/brief/ui/letter-preview/letter-preview.component.ts` (rendering that migrates in)
- `docs/backlog/WP-23-org-template-backend.md` (the `orgTemplate` on `BriefViewDto`)
+- `docs/project/backlog/WP-23-org-template-backend.md` (the `orgTemplate` on `BriefViewDto`)

 ## Decisions (pre-made, don't relitigate)

@@ -12,7 +12,7 @@ same composition is archived with the brief, making sent letters immutable.

 ## Read first

- PRD Brief v2 §2b, §8; `docs/backlog/WP-24-letter-canvas.md` (the `letter.css` contract)
+- PRD Brief v2 §2b, §8; `docs/project/backlog/WP-24-letter-canvas.md` (the `letter.css` contract)
 - `backend/src/BigRegister.Api/Program.cs` — upload `content` endpoint (binary house
  pattern: `.ExcludeFromDescription()` + hand-written FE fetch)
 - `src/app/shared/upload/upload.adapter.ts` (hand-written transport precedent)
@@ -12,7 +12,7 @@ content a read-only sample). PRD Brief v2 §5, §7h.

 ## Read first

- PRD Brief v2 §5, §7h; `docs/backlog/WP-23/24/25` (endpoints, canvas, proefbrief)
+- PRD Brief v2 §5, §7h; `docs/project/backlog/WP-23/24/25` (endpoints, canvas, proefbrief)
 - `src/app/shared/application/access.store.ts` (`can('orgtemplate:edit')`)
 - `.claude/skills/form-machine` — the house form idiom this editor follows
 - `src/app/shared/ui/upload/single-upload` (logo upload reuse)
@@ -22,7 +22,7 @@ that keep CLAUDE.md and the backlog truthful.
  already covers all `/api/` calls, the new endpoints included), and
  `POST /brief/reset`. The demo script documents the mapping; no new interceptor
  cases, no scenario code.
- Demo script lives at `docs/prd/0003-brief-v2-demo-script.md` and follows the §6
+- Demo script lives at `docs/project/prd/0003-brief-v2-demo-script.md` and follows the §6
  choreography (compose → preview → switch sub-org seed → "two axes, one render").
 - One e2e spec, not a suite: drafter composes on canvas → submit → approve → send
  pins the org-template version; admin publishes → drafter canvas reflects it.
@@ -31,10 +31,10 @@ that keep CLAUDE.md and the backlog truthful.

 ## Files

- `docs/prd/0003-brief-v2-demo-script.md` (new)
+- `docs/project/prd/0003-brief-v2-demo-script.md` (new)
 - `e2e/brief-v2.spec.ts` (new)
 - story gap-fill where WP-24..27 left holes
- `docs/backlog/README.md` (statuses), `CLAUDE.md` (roles/routes touch-up)
+- `docs/project/backlog/README.md` (statuses), `CLAUDE.md` (roles/routes touch-up)

 ## Steps