docs: roles & ABAC quick reference

Add docs/reference/roles-and-access.md — a short, scannable reference for the
three dev roles (drafter/approver/admin), that login is faked and role is a
separate dev-only stand-in, how to switch (dev switcher / ?role=), a per-role
capability table, and the one ABAC principle (server emits + enforces; UI
renders). Points to PRD-0002 + the code. Adds a pointer from CLAUDE.md.

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

CLAUDE.md

@@ -184,6 +184,8 @@ atomic layer it is (a context organism doesn't get its own `Organisms/` bucket).
   components keep referencing tokens). System-font stack (licensed RO/Rijks fonts not shipped). See ADR-0003.
 - Scenario toggle (**dev-only**, not wired in prod builds): `?scenario=slow|loading|empty|error`
   on data pages (`scenario.interceptor.ts`) to see every async state.
+- Dev role stand-in (**dev-only**): `?role=drafter|approver|admin` (or the `⚙ state` dev panel).
+  Roles, how to switch, and what each unlocks: `docs/reference/roles-and-access.md`.
 - Prettier; `.editorconfig`. tsconfig: `noImplicitReturns`,
   `noPropertyAccessFromIndexSignature`, `noFallthroughCasesInSwitch`, `isolatedModules`.
 - **Enforced, not just hoped-for:** `npm run lint` (`eslint.config.mjs`) fails the build

docs/reference/roles-and-access.md

@@ -0,0 +1,64 @@
+# Roles & access (ABAC) — quick reference
+
+A short, practical reference for **which roles exist, how to switch between them, and what each
+unlocks**. For the full design and rationale see
+[PRD-0002 — Attribute-Based Access Control](../project/prd/0002-attribute-based-access-control.md).
+
+## Login vs. role — they are separate
+
+**Login is faked.** This POC has one hardcoded, stubbed DigiD user (a 9-digit BSN); there is no
+real identity provider and you do **not** pick a role when you log in.
+
+The **acting role** is a separate, **dev-only** stand-in for the coarse role a real AD/OIDC identity
+would carry. It is orthogonal to the login user — you log in as the one faked user, then choose an
+acting role to exercise the drafter/approver/admin flows.
+
+## The three roles
+
+`drafter` (default) · `approver` · `admin` — defined by the `Role` type in
+`src/app/shared/domain/role.ts`.
+
+## How to switch role (dev only)
+
+Both are wired only under `isDevMode()` — they do not exist in a production build.
+
+- **Dev switcher (easiest):** open the `⚙ state` panel (bottom-right in a dev build) and pick a
+  role from the **role** dropdown. The page reloads with the new role.
+- **`?role=` query param:** append `?role=drafter`, `?role=approver`, or `?role=admin` to any URL.
+  The value is **sticky for the browser tab** (`sessionStorage`), so it survives navigation that
+  drops the query param. An unknown value falls back to `drafter`; open a fresh tab or set
+  `?role=drafter` to reset.
+
+Mechanism: `src/app/shared/infrastructure/role.ts` reads the role and the HTTP interceptor stamps it
+as an `X-Role` header on role-aware requests; the backend resolves it into a `Principal`.
+
+## What each role unlocks
+
+Capabilities are resolved server-side (`backend/src/BigRegister.Api/Domain/Authorization/Authz.cs`,
+`RoleCapabilities`) and returned by `GET /me`.
+
+| Role       | Capabilities (`/me`)                                | Reaches                                                                              |
+| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `drafter`  | _(none of the admin capabilities)_                  | Composes letters; the only role that may reveal a BSN                                |
+| `approver` | `brief:approve`, `brief:reject`, `brief:send`       | Reviews/approves letters (four-eyes: approver ≠ drafter)                             |
+| `admin`    | `orgtemplate:edit`, `stamdata:edit`, `cases:manage` | Huisstijl `/brief/huisstijl`, Stamdata `/beheer/stamdata`, Aanvragen `/beheer/zaken` |
+
+The admin pages appear in the header nav and in the dashboard **"Beheer"** section whenever the
+matching capability is present — otherwise they are reachable only by URL (and the route guard
+redirects a user who lacks the capability back to `/dashboard`).
+
+## The one principle
+
+Identity (AD/OIDC, faked here) supplies **coarse roles**; the app owns a **fine-grained capability**
+model on top. The **same `Authz` check both emits a capability** (on `GET /me`, consumed by
+`AccessStore` in `src/app/shared/application/access.store.ts`) **and enforces the endpoint** — one
+source of truth, so the two can't drift. **The UI only renders decisions; it never derives access
+from a role.** Anything tied to a specific resource's live state (e.g. may-I-edit _this_ letter,
+reveal _this_ BSN) rides that screen's decision DTO rather than `/me`.
+
+## See also
+
+- [PRD-0002 — ABAC](../project/prd/0002-attribute-based-access-control.md) — full design.
+- `backend/src/BigRegister.Api/Domain/Authorization/Authz.cs` — role → capability, and the enforce twin.
+- `src/app/shared/infrastructure/role.ts` — the dev `?role=` reader + `X-Role`.
+- `src/app/shared/application/access.store.ts` — how the FE mirrors `/me` capabilities (deny-by-default).