# WP-28 — Brief v2 demo polish (scenarios, e2e, docs)

Status: done (pending commit; `npm run e2e` unverified in this dev sandbox — see Deviations)
Phase: 6 — Brief v2 (edit-on-the-letter, org templates, server-rendered preview)

## Why

Phase 6 ships across five WPs; this one makes it demonstrable and closes the loop:
a demo script that maps every kept PRD §12 scenario to a URL + click path, an e2e
spec covering the new flows end-to-end, story gap-fill, and the docs/README updates
that keep CLAUDE.md and the backlog truthful.

## Read first

- PRD Brief v2 §6 (demo choreography), §12 (scenario list); WP-23..27 as built
- `e2e/` (WP-19 conventions); `src/app/shared/infrastructure/scenario.ts`

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

- **No preset registry.** The PRD's 18 scenarios collapse onto the existing toggles:
  `?role=drafter|approver|admin`, `?scenario=slow|loading|error` (the interceptor
  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/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.
  Preview assertion is content-type-level (text/html), not pixel.
- CLAUDE.md gets the new role value + route only — keep it rules, not narrative.

## Files

- `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/project/backlog/README.md` (statuses), `CLAUDE.md` (roles/routes touch-up)

## Steps

1. Demo script: table scenario → URL + clicks, covering every kept §12 entry.
2. e2e spec (backend + FE running, WP-19 pattern).
3. Story sweep for the new components/states.
4. Docs updates.

## Acceptance criteria

- [x] Every kept PRD §12 scenario has a working URL + click path in the script
      (walked manually once).
- [ ] `npm run e2e` green, including the new spec — **not verified in this dev
      sandbox**; see Deviations.
- [x] Full GREEN; backlog README statuses correct; CLAUDE.md mentions
      `?role=admin` and `/brief/huisstijl`.

## Deviations / notes (as built)

- **No Brief v2 PRD was ever committed.** WP-23..27 cite "PRD Brief v2 §N" throughout,
  but `docs/project/prd/` never held such a file — it only ever existed as chat
  context. The demo script (`docs/project/prd/0003-brief-v2-demo-script.md`) is
  written directly against the shipped code instead of translating an external §12
  scenario list, and says so up top.
- **`?scenario=` does not reach every endpoint.** `/brief/preview`,
  `/admin/org-template/{id}/preview` and `/brief/reveal-bignummer` are hand-written
  `fetch` calls (same seam as uploads, deliberately `.ExcludeFromDescription()`'d) and
  bypass `scenarioInterceptor`. The demo script and CLAUDE.md now say so explicitly.
- **Canvas authoring moved.** The original "drafter composes on the canvas" framing
  predates commit `ba32e3d` ("brief v3 — besluit-driven guided drafting"):
  `LetterCanvasComponent.editableRegions` no longer has a `'content'` mode. The
  drafter now works through `BehandelSchermComponent` (case header + stepper +
  `app-besluit-panel` + `app-letter-editor`), with the canvas as a read-only preview
  in a modal. The demo script and e2e spec follow that path.
- **`passage-picker` is dead code** — superseded by `besluit-panel`'s guided
  drafting, no consumer left besides its own story. Flagged with a comment on the
  component rather than deleted in this WP (out of scope for a demo-polish pass).
- **Story gaps were state gaps, not component gaps** — every component already had a
  co-located story. Added: `letter-composer` `RejectionDiff` + `AlleenLezen` (WP-27's
  diff view and the pure-viewer notice had no story), `letter-canvas` +
  `org-template-editor` `MetLogo` (WP-26's logo letterhead had no story), and
  `org-template-editor` `LogoUploadFout` (the upload-rejection branch had no story).
- **Org templates have no reset endpoint** — the e2e spec's admin section restores
  the org-template draft it edits (rollback + republish) instead of relying on a
  reset, so repeated runs don't drift the seeded "BIG-register" template.
- **`npm run e2e` could not be verified green in this dev sandbox** — both the new
  `brief-v2.spec.ts` and the pre-existing, untouched `smoke.spec.ts` fail here at
  the same kind of step (clicking a CIBG-styled radio's `<label for>`; e.g.
  `label[for="correspondentie-post"]` in `smoke.spec.ts`), with Playwright
  reporting the element "detached from the DOM, retrying" or a native input whose
  rendered box collapses to 1×1px. Reproduced with `--workers=1` and running
  `smoke.spec.ts` alone, so it isn't cross-test contention. Since `smoke.spec.ts`
  predates this WP and is unrelated to any file it touches, this reads as a
  sandbox-specific rendering/CSS-loading issue (fonts 404 here; a stylesheet may
  not be fully served), not a regression from this WP's changes. **Needs
  confirming green on a normal dev machine / CI** before this box can be ticked.

## Verification

Walk the demo script top to bottom against `docker compose up`; GREEN one-liner;
`npm run e2e`.

## Out of scope

New scenario interceptor cases; a scenario-switcher UI; screenshots/video.

## Risks

The demo script rots when flows change — it lists URLs + clicks only (no prose
walkthroughs), so churn stays cheap.