docs(storybook): render MDX tables + add i18n & testing-strategy docs/skill

- fix: wire remark-gfm into addon-docs so GFM pipe tables in *.mdx render
  (previously raw text in cibg-gaps/layers/atomic-design docs)
- add src/docs/i18n.mdx (Foundations/Internationalization): the $localize
  locale seam + how to test languages without coupling to copy
- add src/docs/testing.mdx (Foundations/Testing strategy): per-layer spec
  matrix, house style, Storybook a11y gate, GREEN gate
- add .claude/skills/test-strategy skill

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/skills/test-strategy/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: test-strategy
+description: Place tests the house way — Vitest specs co-located by layer (pure domain, no TestBed; parse* trust boundaries; thin UI via Storybook a11y). Use whenever adding a spec or deciding what to test.
+---
+
+# Test strategy (test where it's pure)
+
+Push logic down to where it's pure, test it there directly, keep the layers above thin.
+No `TestBed` for domain. Never assert on user-facing copy.
+
+## Rules
+
+- **`domain/` + any pure logic → required spec.** Reducers, combinators, `visibleSteps`,
+  policies, parsers. Import the function and call it — no Angular, no `TestBed`.
+- **Value-object parser → happy path + normalisation + each rejection.** Assert on the
+  `Result` discriminant (`.ok`) and the parsed value, **not** the error message.
+- **`infrastructure/` `parse*` (trust boundary) → required spec.** Accept a valid DTO;
+  reject `null`, `{}`, and malformed shapes. Name it `describe('… (trust boundary)')`.
+- **`application/` stores/commands → spec** the pure reduce + optimistic
+  begin→confirm/rollback + the command `Result`.
+- **`ui/` → Storybook story, not a component test.** Axe runs on every story; add a `play`
+  only for wiring axe can't see.
+- **Never assert on `$localize` copy.** It changes per locale/edit — assert on the
+  `Result`, the value object, or the message id.
+
+## Skeleton
+
+Co-locate `*.spec.ts` next to the unit, in the same layer folder:
+
+```
+<context>/domain/<thing>.spec.ts            # pure — no TestBed
+<context>/domain/value-objects/<vo>.spec.ts # parser: ok + normalise + each reject
+<context>/infrastructure/<x>.adapter.spec.ts# parse* trust boundary
+<context>/application/<store|command>.spec.ts
+```
+
+Minimal parser spec:
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { parseThing } from './thing';
+
+describe('parseThing', () => {
+  it('accepts + normalises', () => {
+    const r = parseThing(' raw ');
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toBe('RAW');
+  });
+  it('rejects malformed', () => {
+    expect(parseThing('').ok).toBe(false); // asserts the tag, not the copy
+  });
+});
+```
+
+## Worked examples
+
+- `src/app/registratie/domain/value-objects/postcode.spec.ts` — parser style.
+- `src/app/registratie/infrastructure/brp.adapter.spec.ts` — trust boundary (`null`/`{}`).
+- `src/app/registratie/domain/registratie-wizard.machine.spec.ts` — pure reducer.
+
+## Verify
+
+```bash
+npm test                     # Vitest (ng test — no vitest.config)
+npm run test-storybook       # axe over every story (UI a11y gate)
+cd backend && dotnet test    # backend rule + endpoint + golden tests
+```

.storybook/main.ts

@@ -1,8 +1,18 @@
 import type { StorybookConfig } from '@storybook/angular';
+import remarkGfm from 'remark-gfm';
 
 const config: StorybookConfig = {
   stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
-  addons: ['@storybook/addon-a11y', '@storybook/addon-docs', '@storybook/addon-onboarding'],
+  addons: [
+    '@storybook/addon-a11y',
+    // remark-gfm so GFM pipe tables in *.mdx docs actually render (addon-docs
+    // doesn't parse them without it).
+    {
+      name: '@storybook/addon-docs',
+      options: { mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [remarkGfm] } } },
+    },
+    '@storybook/addon-onboarding',
+  ],
   framework: '@storybook/angular',
   // Serve the vendored CIBG package so preview-head.html can <link> its CSS (and its
   // relative font/icon/image url()s resolve) — mirrors index.html for the real app.

package.json

@@ -55,6 +55,7 @@
     "jsdom": "^29.0.0",
     "nswag": "^14.7.1",
     "prettier": "^3.8.1",
+    "remark-gfm": "^4.0.1",
     "storybook": "^10.4.6",
     "typescript": "~6.0.2",
     "typescript-eslint": "^8.62.0",

src/docs/i18n.mdx

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Foundations/Internationalization" />
+
+# Internationalization (the locale seam)
+
+Every user-visible string goes through Angular's first-party **`$localize`** — no
+third-party i18n library. The source locale is **`nl`**; a second locale is a
+**translation file, not a code change**. That's the seam: adding English touched
+`src/locale/messages.en.xlf`, not the components.
+
+## How it's wired
+
+| Piece | Where | What |
+| --- | --- | --- |
+| Source locale | `angular.json` → `i18n.sourceLocale` | `nl` — the language the code is written in |
+| Locales | `angular.json` → `i18n.locales.en` | points at `src/locale/messages.en.xlf` |
+| Missing-translation policy | `angular.json` → `i18nMissingTranslation` | `error` — a missing `<target>` fails the build |
+| Runtime global | `angular.json` → `polyfills` | `@angular/localize/init` provides `$localize` |
+| English build/serve | `angular.json` → `configurations.en` | `ng build --configuration=en`, `ng serve --configuration=en` |
+
+Locale switching is **build-time**, not runtime: each locale is its own bundle. There is
+no in-app language picker (out of scope for the POC).
+
+## Authoring copy
+
+Two forms, same custom-id rule. The id is **stable** and shaped `@@<context>.<key>`, so
+translations survive copy edits.
+
+**In TS logic / value objects — tagged template:**
+
+```ts
+// src/app/registratie/domain/value-objects/postcode.ts
+return err($localize`:@@validation.postcode:Voer een geldige postcode in, bijv. 1234 AB.`);
+```
+
+With placeholders (named, so translators can reorder):
+
+```ts
+$localize`:@@aanvraag.row.ingediend:ingediend op ${formatDatumNl(a.submittedAt)}:datum:`;
+```
+
+**In inline component templates — the `i18n` attribute:**
+
+```html
+<!-- src/app/auth/ui/login-form/login-form.component.ts -->
+<app-button type="submit" i18n="@@login.submit">Inloggen met DigiD</app-button>
+```
+
+**Shared/English components never hardcode Dutch.** They expose copy as `input()`s with
+localizable defaults; the domain caller may override. See
+`shared/ui/async/async.component.ts`:
+
+```ts
+errorText = input($localize`:@@async.error:Er ging iets mis bij het laden van de gegevens.`);
+```
+
+## Extract & translate loop
+
+```bash
+npm run extract-i18n   # ng extract-i18n → src/locale/messages.xlf (source, nl)
+```
+
+Then a translator fills `<target>`s in `src/locale/messages.en.xlf`. Both files carry the
+same trans-units (currently 690 = 690, no drift); the `.en.xlf` header is
+`source-language="nl" target-language="en"`. Because `i18nMissingTranslation: error`, a
+forgotten target breaks the `en` build rather than silently shipping Dutch.
+
+## Testing languages without coupling to the strings
+
+**Rule: never assert on rendered copy.** Copy is the thing that changes per locale and per
+edit — a test that reads `"Voer een geldige postcode in"` breaks the moment a translator or
+a product owner touches the wording, in every locale. Assert on what's *invariant* instead:
+
+- **Parsers / value objects** — assert on the `Result` discriminant and the parsed value,
+  not the error message. This is the existing house pattern
+  (`registratie/domain/value-objects/postcode.spec.ts`):
+
+  ```ts
+  expect(parsePostcode('0234AB').ok).toBe(false); // rejects — never inspects the $localize string
+  ```
+
+- **The seam itself** — if you must verify that translation works, check that a known
+  **id flips**, not that a specific phrase appears. Build/serve the `en` configuration and
+  confirm the target for a stable id renders, e.g. `login.submit`: `nl` "Inloggen met
+  DigiD" → `en` "Log in with DigiD". You're testing the wiring, not the wording.
+
+  ```bash
+  ng serve --configuration=en   # then eyeball, or point an e2e at the en bundle
+  ```
+
+See [Testing strategy](?path=/docs/foundations-testing-strategy--docs) for how this fits the
+rest of the test pyramid.

src/docs/testing.mdx

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Foundations/Testing strategy" />
+
+# Testing strategy
+
+Tests follow the same grain as the architecture: **push the logic down to where it's pure,
+test it there directly, and keep the layers above thin.** No single tool covers everything,
+so each layer gets the cheapest test that catches its class of bug.
+
+## What gets tested where
+
+| Layer | Test kind | Tool | Rule |
+| --- | --- | --- | --- |
+| `domain/` | pure-function unit spec | Vitest | **Required.** Call the function directly — **no `TestBed`**. Reducers, combinators, `visibleSteps`, parsers, policies. |
+| `domain/value-objects/` | parser spec | Vitest | Happy path + normalisation + **each** rejection. Assert on the `Result`, never the message. |
+| `infrastructure/` `parse*` | trust-boundary spec | Vitest | Accept a valid DTO; **reject `null` / `{}` / malformed**. Name it `describe('… (trust boundary)')`. |
+| `application/` | store / command spec | Vitest | Reducer purity, optimistic begin→confirm/rollback, command `Result`. |
+| `ui/` | Storybook story | Storybook + a11y | Kept thin. Axe runs on every story; add a `play` only for wiring axe can't see. |
+| flows | e2e smoke | Playwright | One happy path + one error state per critical journey. |
+| backend | rule + endpoint + golden | xUnit | Mirror of the FE domain rules, plus `WebApplicationFactory` integration. |
+
+## Tooling
+
+Vitest runs through Angular's built-in `@angular/build:unit-test` builder — **there is no
+`vitest.config.ts`**; config is implicit via `tsconfig.spec.json`.
+
+```bash
+npm test           # ng test → Vitest, all *.spec.ts co-located next to their unit
+```
+
+Specs import `{ describe, it, expect }` from `vitest` and are co-located with the unit
+they cover.
+
+## The house style
+
+Pure and direct. A value-object parser spec
+(`registratie/domain/value-objects/postcode.spec.ts`):
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { parsePostcode } from './postcode';
+
+describe('parsePostcode', () => {
+  it('normalises to "1234 AB"', () => {
+    const r = parsePostcode(' 1234ab ');
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toBe('1234 AB');
+  });
+  it('rejects malformed input', () => {
+    expect(parsePostcode('0234AB').ok).toBe(false); // asserts the tag, not the copy
+  });
+});
+```
+
+A trust-boundary adapter (`registratie/infrastructure/brp.adapter.spec.ts`) additionally
+proves the untrusted shape is rejected:
+
+```ts
+expect(parseBrpAddress(null).ok).toBe(false);
+expect(parseBrpAddress({}).ok).toBe(false); // missing required field
+```
+
+Elm-style machines test the pure `reduce` with inline state fixtures — no Angular
+(`registratie/domain/registratie-wizard.machine.spec.ts`).
+
+## UI = Storybook, not heavy component tests
+
+`@storybook/addon-a11y` runs the `wcag2a/2aa/21a/21aa` rule sets on **every** story;
+`@storybook/test-runner` + `axe-playwright` turn that into a CI gate:
+
+```bash
+npm run test-storybook       # axe over every story against a running Storybook
+npm run test-storybook:ci    # builds storybook-static, serves :6006, runs the gate
+```
+
+Disabling a11y on a story needs an inline justification + a WP cross-reference (see
+[Accessibility](?path=/docs/foundations-accessibility--docs)).
+
+## Don't assert on copy
+
+Localized strings change per locale and per edit. Tests assert on the `Result`
+discriminant, the value object, or the message **id** — never the rendered Dutch/English
+text. Full detail in [Internationalization](?path=/docs/foundations-internationalization--docs).
+
+## The GREEN gate
+
+```bash
+npm run lint && npm run check:tokens && npm test && npm run build && npm run build-storybook
+cd backend && dotnet test
+```
+
+Everything above must pass before a work package is done.