docs: index orphaned reference docs + add scaffolding guide

- Index roles-and-access, dependencies, and dependency-graph (were on disk
  but missing from the docs README index).
- New reference/scaffolding.md: plop generators, gen:api (NSwag), gen:snippets,
  and the skill recipes — the one consolidated "how generation works" page.
- Fix stale backlog range (WP-01…WP-28 -> WP-48) and de-link the dead WP-32 row
  (undo folded into WP-31, no separate file).

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

docs/reference/scaffolding.md

@@ -0,0 +1,86 @@
+# Scaffolding & code generation — how it works
+
+How new code and boilerplate get generated in this repo. Three mechanisms, by design:
+**runnable plop generators** for the pure-TS leaf patterns, **standalone node generators**
+for the two committed-but-generated artifacts (`gen:api`, `gen:snippets`), and
+**skill-driven recipes** (`.claude/skills/`) for the patterns too awkward to templatize.
+The split is deliberate — [WP-43](../project/backlog/WP-43-scaffold-generators.md)
+shipped only the two leaf generators and kept the harder patterns as skills.
+
+## The rule: generate the boilerplate, not the judgement
+
+Anything mechanical and shape-stable gets a generator (value objects, form machines — each
+ships with its co-located spec so the "pure logic must have a spec" rule holds by default).
+Anything that spans a template `{{ }}` clash, the C# backend, or a design decision stays a
+**skill recipe** — a generator there adds little over the prose.
+
+## Plop generators (runnable)
+
+Config: `plopfile.mjs`; templates: `plop-templates/*.hbs` (Handlebars, prettier-ignored).
+
+- **`npm run gen:value-object`** — branded value object + `parseX` parser + spec
+  ("parse, don't validate"). Prompts for `context` + PascalCase `name`; emits
+  `src/app/{context}/domain/value-objects/{name}.ts` and its `.spec.ts`.
+- **`npm run gen:form-machine`** — Elm-style Model/Msg/pure-`reduce` state machine + spec.
+  Prompts for `context` + `name`; emits `src/app/{context}/domain/{name}.machine.ts` + spec.
+- **`npm run gen`** — interactive menu (pick a generator).
+- Positional args skip the prompts: `npx plop value-object registratie KvkNummer`.
+
+> ⚠ Each generated `$localize` id needs an English `<target>` in
+> `src/locale/messages.en.xlf` before `npm run ci` — the localize gate fails otherwise.
+
+## Typed API client — `npm run gen:api`
+
+Regenerates the FE⇄BE seam from the backend's OpenAPI doc (config: `nswag.json`).
+The script builds `BigRegister.Api`, emits `backend/swagger.json` via `dotnet swagger`, then
+NSwag regenerates the Fetch-based client into
+`src/app/shared/infrastructure/api-client.ts`. Both `swagger.json` and `api-client.ts` are
+**committed and never hand-edited** — a CI drift gate fails if they're stale. Run it after
+any backend contract change (see the `bff-endpoint` skill).
+
+## Showcase snippets — `npm run gen:snippets`
+
+`scripts/gen-snippets.mjs` extracts `// #region showcase:<name>` … `// #endregion` blocks
+from real source files into `src/app/showcase/snippets.generated.ts`, so the teaching
+showcase shows code identical to what ships. Committed, prettier-ignored, and drift-gated in
+CI (`gen:snippets && git diff --exit-code`).
+
+## Skill recipes (`.claude/skills/`)
+
+Patterns kept as recipes rather than generators — invoke by name (`/<skill>`):
+
+- **`new-feature`** — the house pipeline: domain → infrastructure → application → UI last.
+- **`new-context`** — scaffold a new bounded context (folders, alias, boundary rule, route).
+- **`value-object`** / **`form-machine`** — the two above; each points at its `gen:*` command.
+- **`bff-endpoint`** — screen-shaped read: C# endpoint + DTO + `gen:api` + adapter + store +
+  `<app-async>`. Skill, not generator (spans backend + regen).
+- **`mutation-command`** — a write op: adapter method + `submit-*` command returning `Result`.
+- **`ui-component`** — shared atom/molecule/organism + Storybook story. Skill because the
+  Angular template `{{ }}` collides with Handlebars.
+- **`new-ssp`** — bootstrap a whole new portal from this template (keep/strip/rename/re-seed).
+- **`document-feature`** — ship docs in the same diff (this doc came from it).
+- **`test-strategy`** — where specs live by layer.
+
+## Bootstrapping a whole new SSP
+
+Today the `new-ssp` skill is a **manual** fork-and-strip recipe (keep `shared/` + tooling,
+strip the business contexts, re-seed the backend, re-run `gen:api`). See the skill for the
+step-by-step and its GREEN-at-every-step verify gate.
+
+## Not yet built
+
+- **`gen:context`** ([WP-44](../project/backlog/WP-44-context-generator.md)) — a runnable
+  version of the `new-context` skill. Planned, not shipped.
+- **`create-ssp`** ([WP-45](../project/backlog/WP-45-create-ssp-generator.md)) —
+  mechanised `new-ssp`. Planned, not shipped.
+
+Don't assume either command exists — use the corresponding skill until they land.
+
+## See also
+
+- `plopfile.mjs` + `plop-templates/` — the leaf generators.
+- `.claude/skills/` — the recipe library.
+- `nswag.json` — the typed-client generation config.
+- `scripts/gen-snippets.mjs` — the showcase snippet extractor.
+- [ARCHITECTURE.md](architecture/ARCHITECTURE.md) — the NSwag client seam in context.
+- [WP-43](../project/backlog/WP-43-scaffold-generators.md) — why only leaves got generators.