From a005acb93d1d788d2c73a72c4d6f94c7acb0453c Mon Sep 17 00:00:00 2001
From: lilleman <lilleman@larvit.se>
Date: Wed, 5 Aug 2026 23:41:12 +0200
Subject: [PATCH] Cut non-essential prose from docs and comments, and require
 the same of every future change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README loses the competitor comparison, the personas and the repeated philosophy; the
five near-identical E2E command blocks become a table plus one command, and the file
map a clause per entry. AGENTS.md keeps every decision but drops the narrative around
them. todo.md's completed items collapse to their task line — git holds the rest.

Comments lose restatement, README duplication and history ("used to", "originally",
dated notes). AGENTS.md gains a Prose discipline section making this a standing pass on
every change rather than a one-off cleanup.

src/compose.test.ts now expects 6 documented E2E run commands, not 10, since the README
states the command once instead of per suite.
---
 AGENTS.md                                   |  284 ++--
 README.md                                   | 1654 +++++++------------
 e2e-tests/devstack-login.spec.ts            |   21 +-
 e2e-tests/full-flow.spec.ts                 |    4 +-
 e2e-tests/visual.spec.ts                    |    5 +-
 examples/plugins/admin/README.md            |   40 +-
 examples/plugins/admin/admin-grants.test.ts |    6 +-
 examples/plugins/admin/admin-shared.ts      |   31 +-
 examples/plugins/admin/admin-users.ts       |    7 +-
 examples/plugins/admin/plugin.ts            |   10 +-
 src/auth/bootstrap.test.ts                  |    7 +-
 src/auth/bootstrap.ts                       |   19 +-
 src/auth/denylist.ts                        |   24 +-
 src/auth/guards.ts                          |    8 +-
 src/auth/routes.ts                          |    6 +-
 src/compose.test.ts                         |    2 +-
 src/config.ts                               |   12 +-
 src/http/app.test.ts                        |   28 +-
 src/http/app.ts                             |  139 +-
 src/http/safe-url.ts                        |   17 +-
 src/http/security-headers.ts                |   18 +-
 src/i18n/load.ts                            |   14 +-
 src/i18n/translate.ts                       |   15 +-
 src/logger.ts                               |   27 +-
 src/plugin-host/plugin.ts                   |   70 +-
 src/plugin-host/system.ts                   |    9 +-
 src/ui/chrome.ts                            |   20 +-
 src/ui/nav.ts                               |   11 +-
 todo.md                                     |  111 +-
 29 files changed, 980 insertions(+), 1639 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index bad976d..052e732 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,20 +3,27 @@
 Guidance for AI agents and contributors working in this repo. Read `README.md` for
 commands and layout.
 
-## Maintaining this file
+## Prose discipline
 
-Every agent session reads this file in full, so its length is a cost paid on every task.
-Keep it the shortest thing that still changes what someone does.
+Every word in this repo is read again on every future task, so prose is a recurring cost. On **any**
+change, sweep the prose you touched — this file, `README.md`, the example READMEs, and code
+comments — and cut it back to what a competent reader could not infer:
 
-- **Trim as you add.** After any edit, re-read the whole file and compress: merge overlapping
-  entries, cut prose that restates a rule, drop what the code or `README.md` already says.
-  Question each section — same information, fewer words.
-- **Record the decision and the reason it turns on, nothing else.** Not the investigation, not
-  what was tried first, not how it was verified — that belongs in the PR that made the change.
+- **Delete history.** Git holds it. No "this moved from X", "used to be Y", "was tried and
+  rejected", "(declined twice)", dated changelog entries, or the symptom that prompted a fix. Record
+  the decision and the reason it *currently* turns on, nothing else.
+- **Delete restatement.** A comment that says what the adjacent line says, a doc paragraph that
+  re-explains a table above it, a file-map entry that expands the filename. The fix is deletion,
+  not trimming.
+- **Delete the self-evident** and anything already stated once elsewhere. **One home per fact** —
+  link to it instead of repeating it; the same sentence in five files is five chances to drift.
 - **Give every accepted risk an expiry** ("valid while X"), and delete the entry once X stops
   holding.
-- **One home per fact.** Link to it rather than restating it — the same sentence in five files
-  is five things to update and five chances to drift.
+- **Keep** the surprising why, the footgun, the invariant, the external constraint, and the one-time
+  setup a reader cannot dig out of the code. Once a line has earned its place, make it short and
+  information-dense.
+
+Trimming is not a separate task to schedule — do it in the same change, every time.
 
 ## How to work with tasks
 
@@ -31,29 +38,23 @@ branch, create a PR and merge it when the CI/CD turns green.
 1. **Simplicity** — prefer the solution that is easiest to understand, smallest, and most readable.
 2. **Few dependencies** — runtime deps stay minimal (today `ejs`, `lucide-static`, `@larvit/log`).
    Prefer the Node standard library; justify any new dependency; do not add frameworks. The app is
-   **stateless — no database**. Auth/identity/OAuth are **Ory sidecar services** (Kratos/Keto/Hydra,
-   backed by Postgres), reached over their REST APIs with built-in `fetch` — no SDK. New
-   capabilities ship as **plugin folders** under `plugins/` that fetch their data from upstream
-   services, not as core code.
+   **stateless — no database**. Auth/identity/OAuth are **Ory sidecar services** reached over their
+   REST APIs with built-in `fetch` — no SDK. New capabilities ship as **plugin folders** under
+   `plugins/` that fetch their data from upstream services, not as core code.
 3. **Strict TypeScript** — `tsconfig.json` is strict (incl. `noUncheckedIndexedAccess`,
    `exactOptionalPropertyTypes`, `verbatimModuleSyntax`). Keep it that way. Prefer exact types;
    limit nullable and multi-option types.
-4. **Environment-agnostic** — the app never asks *which environment* it runs in; no `NODE_ENV`
-   branching. Every behaviour is an **explicit config toggle** (e.g. `CACHE_TEMPLATES`,
-   `REQUIRE_SECURE_SECRETS`), read once in `src/config.ts`. Compose files set them per deployment.
-5. **Semantic, accessible DOM** — use the right element for the job (landmarks, one `<h1>` per page
-   + sane heading order, lists, `<table>` with row/column headers, `<fieldset>`/`<legend>`,
-   `<button>` vs `<a>`); add ARIA only to fill real gaps (`aria-current`, `aria-sort`, labels).
-   Classes/ids name *meaning*, not looks. Prefer native semantics over `div` + ARIA. New views and
-   partials keep this bar.
-6. **Full, parallel E2E** — every user-facing flow (each page, form, guard, plugin route) has a
-   Playwright E2E test, shipped in the same change as the surface. Tests stay independent and
-   side-effect-free so the suite runs `fullyParallel` — never serialise on shared state.
-7. **Powerful, fail-loud plugins** — the plugin API is the product's main surface and the only way
-   to add domain features. It optimises for being **powerful, predictable, and overloadable** (a
-   plugin can take over as much of a page as it wants), and the host **fails loud at boot/discovery**
-   (bad manifest, version mismatch, conflict) rather than sandboxing at runtime. Runtime
-   crash-isolation is a deliberate **non-goal** — diagnose at deploy time, not in production.
+4. **Environment-agnostic** — no `NODE_ENV` branching. Every behaviour is an **explicit config
+   toggle** read once in `src/config.ts`; compose files set them per deployment.
+5. **Semantic, accessible DOM** — the right element for the job (landmarks, one `<h1>` per page +
+   sane heading order, lists, `<table>` with row/column headers, `<fieldset>`/`<legend>`, `<button>`
+   vs `<a>`); ARIA only to fill real gaps. Classes/ids name *meaning*, not looks.
+6. **Full, parallel E2E** — every user-facing flow has a Playwright test, shipped in the same change
+   as the surface. Tests stay independent and side-effect-free so the suite runs `fullyParallel`.
+7. **Powerful, fail-loud plugins** — the plugin API is the product's main surface and the only way to
+   add domain features. It optimises for being powerful, predictable and overloadable, and the host
+   **fails loud at boot/discovery** rather than sandboxing at runtime. Runtime crash-isolation is a
+   deliberate **non-goal**.
 
 ## Deliberate architectural deviations (don't re-flag)
 
@@ -62,36 +63,32 @@ Revisit only if the stated reason stops holding.
 
 ### Structure & contracts
 
-- **`src/` is grouped by concern**, not flat — `http/` (request pipeline), `auth/` (session-JWT hot
-  path, guards, Ory REST clients), `i18n/` (locale resolution + catalogs), `plugin-host/`
-  (discovery/router/hooks/view-resolver + the `plugin-api.ts` author barrel + `system.ts` behind
-  `ctx.system`), `ui/` (design-system view-models + menu/chrome). `server.ts`/`config.ts`/`logger.ts`
-  and the topology-guard `*.test.ts` stay at the root; tests are co-located. Add a new module to the
-  folder owning its concern; don't reintroduce a flat tree. The core ships **no domain screens** —
-  even the admin GUI is a drop-in plugin (`examples/plugins/admin/`).
+- **`src/` is grouped by concern**, not flat — `http/`, `auth/`, `i18n/`, `plugin-host/`, `ui/`,
+  with `server.ts`/`config.ts`/`logger.ts` and the topology-guard `*.test.ts` at the root; tests are
+  co-located. Add a new module to the folder owning its concern. The core ships **no domain
+  screens** — even the admin GUI is a drop-in plugin (`examples/plugins/admin/`).
 - **Plugins and config import the host only via package.json `imports`** — `#plugin-api` →
   `src/plugin-host/plugin-api.ts`, `#menu-config` → `src/ui/menu-config.ts`, never a relative
-  `../../src/*` path. These two barrels are the whole contract surface; the `src/*` behind them may
-  be refactored freely. Don't "fix" a `#`-import back to a relative path. Two consequences:
+  `../../src/*` path. These two barrels are the whole contract surface; don't "fix" a `#`-import
+  back to a relative path. Two consequences:
   - `#plugin-api` re-exports the Ory client types (`KratosAdmin`/`KetoClient`/`HydraAdmin` + their
     DTOs and error classes), so those shapes are **contract-visible** — changing them needs a major
     `apiVersion` bump, not a free refactor.
   - **A plugin/config folder must stay a plain folder — no `package.json` of its own**, which would
     become its own scope and stop `#`-specifiers resolving. A plugin kept in its own repo therefore
     typechecks against the barrel only when mounted under the host tree (or with a vendored stub).
-- **`examples/` mirrors the drop-in mount dirs** — `examples/plugins/<id>/` copies to `plugins/<id>/`,
-  `examples/config/menu.ts` to `config/menu.ts`. Both mirrors are in `tsconfig.include` and resolve
-  the host via `#`-imports, so each typechecks in place *and* copies across unchanged. Never commit
-  real plugins/config into the root mount dirs — they ship empty.
+- **`examples/` mirrors the drop-in mount dirs** — `examples/plugins/<id>/` copies to
+  `plugins/<id>/`, `examples/config/menu.ts` to `config/menu.ts`. Both mirrors are in
+  `tsconfig.include` and resolve the host via `#`-imports, so each typechecks in place *and* copies
+  across unchanged. Never commit real plugins/config into the root mount dirs — they ship empty.
 - **`ctx.chrome` is lazily memoized — do not make it unconditional** or move it into the base request
-  context. It protects the I/O-free hot path on the public, bot-hit landing (`/`). (Declined twice.)
+  context. It protects the I/O-free hot path on the public, bot-hit landing (`/`).
 - **A plugin-owned render always runs on that plugin's context.** The landing slots (`home`,
   `dashboard`) and an `onRequest` short-circuit build their context with `contextFor(pluginId)`
   exactly as a plugin route does — otherwise `ctx.t` is the core translator and the plugin's own keys
   render as bare keys on the pages it owns.
 - **Email is delegated to Kratos** (it renders + sends recovery/verification mail); `web` never
-  touches SMTP. Customization is Kratos' `courier.template_override_path`, not app code — keeping
-  `web` stateless and dependency-light.
+  touches SMTP. Customization is Kratos' `courier.template_override_path`, not app code.
 
 ### Authorization
 
@@ -100,10 +97,10 @@ Revisit only if the stated reason stops holding.
   a role is a *bundle*, which here is just a group with several grants (groups nest). Ory's own
   "permission" (the `Resource` `permits`: view/edit/delete) is the separate per-row tier.
 - **A permission name is always `<resource>:<action>`** — `scheduling:read`, `users:write`. A bare
-  word names *who someone is* (a role), and roles are groups here; the old catch-all `admin` was
-  exactly that mistake. **Enforced at discovery** (`isValidPermissionName` in `plugin-host/plugin.ts`,
-  checked by `shapeError` over every route/nav `permission` and every declared name), fail-loud like
-  any other manifest rule — not only in the admin GUI, which an operator removes by not copying it in.
+  word names *who someone is* (a role), and roles are groups here. **Enforced at discovery**
+  (`isValidPermissionName` in `plugin-host/plugin.ts`, checked by `shapeError` over every route/nav
+  `permission` and every declared name), fail-loud like any other manifest rule — not only in the
+  admin GUI, which an operator removes by not copying it in.
   - **Names are authored in plugin code; only grants live in Keto.** The host collects every installed
     plugin's declarations into one catalog (`declaredPermissions` → `ctx.declaredPermissions`), and
     that catalog *is* the list the admin screens offer. Hence **no Permissions admin screen**: nothing
@@ -116,16 +113,16 @@ Revisit only if the stated reason stops holding.
   - **Declaring a permission stays optional.** Mandatory declaration would let `findConflicts` see all
     overlaps, but would then warn on exactly that legitimate sharing case. Shape is enforced;
     declaration is not.
-  - `ADMIN_PERMISSIONS` **defaults to empty** (every permission is owned by the plugin gating on it),
-    and **an unusable value is dropped with a warning, never fatal** — fail-loud belongs at the
-    manifest boundary where a developer authored the mistake, whereas `bootstrap` gates `web`, so
-    refusing operator env takes the whole stack down. `e2e-tests/compose.auth.yml` seeds a bad value
-    so the container proves it survives one. The seed is a function of what `bootstrap` discovers, so
-    a plugin dropped in after first boot needs `docker compose up -d` (re-runs the one-shot), not
-    `restart web`. `bootstrap`'s matching `./plugins` mount belongs in `compose.override.yml` and
-    nowhere else: in the base file it would desynchronise prod and collide with the e2e stacks, which
-    bind individual plugins *inside* `/app/plugins` (a nested mount into a read-only parent is EROFS
-    and the container never starts). Valid while bootstrap is the only writer of grants.
+  - `ADMIN_PERMISSIONS` **defaults to empty**, and **an unusable value is dropped with a warning,
+    never fatal** — fail-loud belongs at the manifest boundary where a developer authored the
+    mistake, whereas `bootstrap` gates `web`, so refusing operator env takes the whole stack down
+    (`e2e-tests/compose.auth.yml` seeds a bad value to prove the container survives one). The seed is
+    a function of what `bootstrap` discovers, so a plugin dropped in after first boot needs
+    `docker compose up -d`, not `restart web`. `bootstrap`'s matching `./plugins` mount belongs in
+    `compose.override.yml` and nowhere else: in the base file it would desynchronise prod and collide
+    with the e2e stacks, which bind individual plugins *inside* `/app/plugins` (a nested mount into a
+    read-only parent is EROFS and the container never starts). Valid while bootstrap is the only
+    writer of grants.
   - **`actionForMethod` is plugin-local and must not migrate into `#plugin-api`.** Inside the admin
     example it keeps the route table and the in-handler guard deriving from one function, so 29 routes
     × 2 gate sites cannot drift. Generalised, it would make authorization a function of the transport
@@ -133,21 +130,20 @@ Revisit only if the stated reason stops holding.
 - **A `:read`-only holder must never be shown a write affordance.** The list/detail models carry
   `canWrite` and the views drop create/save/delete/add/remove; the permission picker still renders,
   disabled, because *seeing* who holds what is the point of `:read`. A **write-intent GET** (a create
-  form, a delete-confirm page) is the exception to `actionForMethod` and gates on `:write`, since a
-  page whose only purpose is to start a write should refuse a reader rather than render a form whose
-  submit 403s. Two grant-specific guards go with it: you cannot revoke your own **direct** grants
-  (self-lockout would need a `curl` against Keto to undo), and a permission held *through a group*
-  renders ticked-but-disabled, because unticked stated the opposite of the truth. **Known gap:** the
-  group paths are unguarded — unticking a permission on a group you belong to, leaving it, or deleting
-  it can still strip your own access. The robust "last effective holder" check needs a reverse Keto
+  form, a delete-confirm page) is the exception to `actionForMethod` and gates on `:write`. Two
+  grant-specific guards go with it: you cannot revoke your own **direct** grants (self-lockout would
+  need a `curl` against Keto to undo), and a permission held *through a group* renders
+  ticked-but-disabled, because unticked stated the opposite of the truth. **Known gap:** the group
+  paths are unguarded — unticking a permission on a group you belong to, leaving it, or deleting it
+  can still strip your own access. The robust "last effective holder" check needs a reverse Keto
   query and is deferred.
 - **`users:write` and `groups:write` are equivalent to full administrative access**: `groups:write`
   adds you to any group, including one holding every permission; `users:write` mints a recovery code
   for any account. The containment the split buys is real on the **read** half only (`users:read` is
   a safe helpdesk grant). Don't let the per-resource naming imply otherwise in docs.
-- **Plainpages says "user" everywhere; Ory's word is "identity".** Ory's own docs use the terms
-  interchangeably, so this is house style, not a renamed concept. The single exception is the
-  `Identity` DTO in `src/auth/kratos-admin.ts`, which mirrors Kratos' wire shape — don't rename it.
+- **Plainpages says "user" everywhere; Ory's word is "identity".** House style, not a renamed
+  concept. The single exception is the `Identity` DTO in `src/auth/kratos-admin.ts`, which mirrors
+  Kratos' wire shape — don't rename it.
 
 ### i18n
 
@@ -156,15 +152,14 @@ Revisit only if the stated reason stops holding.
   page's language invisible in its address and unshareable; the cost is that a plugin wraps its own
   hrefs. Matching is exact on a full tag (`sv-FI` ≠ `sv-SE`), except that a lone language from
   `Accept-Language` takes the first regional catalog for it.
-- **The core building blocks carry the locale; a plugin doesn't have to.** The shell (breadcrumbs),
-  `pagination`, `filter-bar`, `data-table`, `auth-card`, `flow-body`, `field` and `menu` wrap every
-  href in `localeHref`; nav and sign-in are wrapped in `chrome.ts`; the two GET forms carry it as a
-  hidden `locale` input, since a GET submit replaces the whole query string. **A form's `action`
-  counts as a link** — sign-out, consent and auth-card forms carry it too, or picking a language and
-  then saving anything drops back to `Accept-Language`. Putting the obligation on each call site was
-  tried and missed five of eight sites in one commit. `ctx.localeHref` remains for hrefs a plugin's
-  own markup emits. The one round-trip that cannot carry it is the Kratos sign-in POST (absolute
-  off-site URL).
+- **The core building blocks carry the locale; a plugin doesn't have to.** The shell, `pagination`,
+  `filter-bar`, `data-table`, `auth-card`, `flow-body`, `field` and `menu` wrap every href in
+  `localeHref`; nav and sign-in are wrapped in `chrome.ts`; the two GET forms carry it as a hidden
+  `locale` input, since a GET submit replaces the whole query string. **A form's `action` counts as a
+  link** — sign-out, consent and auth-card forms carry it too, or picking a language and then saving
+  anything drops back to `Accept-Language`. The obligation stays on the building block, never on each
+  call site. `ctx.localeHref` remains for hrefs a plugin's own markup emits. The one round-trip that
+  cannot carry it is the Kratos sign-in POST (absolute off-site URL).
 - **`locale` is a host-owned query param** — in `parseListQuery`'s reserved set, so a localized list
   page doesn't hand a plugin a phantom `locale` filter. The i18n view locals (`t`, `locale`, `locales`,
   `localeHref`, `localeParam`, `localeSwitch`, `dir`) are likewise reserved, merged after a handler's
@@ -192,30 +187,28 @@ Revisit only if the stated reason stops holding.
   escaping into `t()` — every other value in a view would become the odd one out.
 - **RTL is out of scope until there is a real use case.** `textDirection` sets `<html dir>` because
   that is free and correct, but the stylesheet keeps physical `left`/`right` properties; a genuine RTL
-  locale needs those moved to logical ones first. Don't convert the CSS or file findings about it on
-  spec. Valid while no deployment needs an RTL language.
+  locale needs those moved to logical ones first. Valid while no deployment needs an RTL language.
 
 ### UI
 
 - **A dropdown is a `<button popovertarget>` + `[popover]`, never a `<details>`.** The browser then
   owns open/close — the only zero-JS way to dismiss by clicking outside — and the panel sits in the
-  top layer, so a row kebab is no longer clipped by `.table-wrap`'s `overflow`. Four rules hold it
+  top layer, so a row kebab is not clipped by `.table-wrap`'s `overflow`. Four rules hold it
   together: the panel carries **`position-anchor: auto`** (a bare `anchor()` resolves to nothing in
   all three engines); it stays the trigger's **next sibling inside the `.menu` wrapper**, which the
-  open-state style and the old-browser fallback both read; the partial **requires a caller-named `id`**
-  and fails loud without one, since that is the `popovertarget` idref (generated ids were tried and
-  rejected — nondeterministic HTML forecloses the caching decision); and **neither `aria-expanded` nor
-  `aria-haspopup` is written**, because a zero-JS invoker cannot keep the first truthful and the second
-  would promise `role="menu"` semantics these panels don't implement. `<details>` stays where it means
-  disclosure rather than popup: the nav tree. `shell.ejs` hand-rolls the same block for the profile
-  menu (its trigger composes escaped user values and its one item is a CSRF POST form, neither of which
-  the partial's `Item` shapes cover) — keep the two in step.
-- **`ICON_NAMES` (`src/ui/icons.ts`) is a host-owned registry, not a frozen plugin contract.** It is
-  deliberately not re-exported from `#plugin-api`; README → Nav & permission gates tells an author that
-  a new icon means registering it there. So the palette may narrow when the last reference to an id
-  goes, and a plugin needing one gets it re-registered in the same change. Accepted cost: an unknown
-  sprite id renders blank instead of failing loud (the `every icon <use> resolves` e2e test catches
-  anything reaching the nav). Removing an id is a core edit — weigh it per icon rather than sweeping.
+  open-state style and the old-browser fallback both read; the partial **requires a caller-named
+  `id`** and fails loud without one, since that is the `popovertarget` idref (never generate one —
+  nondeterministic HTML forecloses the caching decision); and **neither `aria-expanded` nor
+  `aria-haspopup` is written**, because a zero-JS invoker cannot keep the first truthful and the
+  second would promise `role="menu"` semantics these panels don't implement. `<details>` stays where
+  it means disclosure rather than popup: the nav tree. `shell.ejs` hand-rolls the same block for the
+  profile menu (its trigger composes escaped user values and its one item is a CSRF POST form) — keep
+  the two in step.
+- **`ICON_NAMES` (`src/ui/icons.ts`) is a host-owned registry, not a frozen plugin contract**, so it
+  is deliberately not re-exported from `#plugin-api`. The palette may narrow when the last reference
+  to an id goes, and a plugin needing one gets it re-registered in the same change. Accepted cost: an
+  unknown sprite id renders blank instead of failing loud (the `every icon <use> resolves` e2e test
+  catches anything reaching the nav).
 
 ### Build, test & release
 
@@ -226,16 +219,14 @@ Revisit only if the stated reason stops holding.
   files, `.dockerignore` the image).
 - **A container whose output a human then edits or deletes runs as `--user "$(id -u):$(id -g)"`** —
   the E2E runner (artifacts) and a lockfile edit, or the output is root-owned and needs `sudo`, which
-  a dev box may not have at all. Not universal: `bootstrap` writes `jwks.json` as root when it is
-  absent on first boot — the committed dev key makes that rare, and when it happens the rotation
-  runbook's host-side `>` needs the file re-owned first. Valid while the dev key ships committed.
-  Three consequences.
-  `e2e-tests/artifacts/` is *tracked* (`.gitkeep`), since an absent bind-mount source is
-  daemon-created as root and that uid then cannot write it — which also makes a root-owned leftover
-  an upgrade hazard (README → Breaking changes). The runner image sets `HOME=/tmp`, since an
-  arbitrary uid has no passwd entry and would land on an unwritable `/`. And rootless Docker wants
-  the flag *dropped* — container root is already the invoking user there. Baking a `USER` in instead
-  does not work: the image's `pwuser` is 1001, and no fixed uid matches every host.
+  a dev box may not have. Not universal: `bootstrap` writes `jwks.json` as root when it is absent on
+  first boot; the committed dev key makes that rare, and when it happens the rotation runbook's
+  host-side `>` needs the file re-owned first (valid while the dev key ships committed). Three
+  consequences: `e2e-tests/artifacts/` is *tracked* (`.gitkeep`), since an absent bind-mount source is
+  daemon-created as root and that uid then cannot write it (README → Upgrading); the runner image sets
+  `HOME=/tmp`, since an arbitrary uid has no passwd entry and would land on an unwritable `/`; and
+  rootless Docker wants the flag *dropped*, container root already being the invoking user. Baking a
+  `USER` in instead does not work — the image's `pwuser` is 1001 and no fixed uid matches every host.
   `src/compose.test.ts` guards every documented command, `src/ci-gate.test.ts` the gate's own.
 - **Anything the browser logs fails the E2E test that provoked it.** Every spec takes its `test` from
   `e2e-tests/console-guard.ts`, which fails a test on a console error/warning or uncaught exception on
@@ -244,42 +235,38 @@ Revisit only if the stated reason stops holding.
   Chromium drops (the e2e stacks serve plain http over container hostnames), and `allowConsole(re)` for
   a test whose own page provokes a message on purpose. `src/e2e-console-guard.test.ts` locks the wiring
   in the *unit* gate, since a spec importing `test` straight from Playwright — or minting a page with
-  a raw `newPage()` instead of `watchedPage()` — would run unwatched and green. The buffer clears at
-  teardown so a `beforeAll` is watched too; accepted cost is that a page outliving its test can log
-  late and fail the next one.
+  a raw `newPage()` instead of `watchedPage()` — would run unwatched and green. Accepted cost: a page
+  outliving its test can log late and fail the next one.
 - **The Ory-free specs run in all three engines; the Ory-backed ones stay on Chromium.**
   `visual.spec.ts` + `language.spec.ts` are side-effect-free, so parallel runs don't collide, and a
   console message only appears in the engine that renders the page (`ORY_FREE` in
   `e2e-tests/playwright.config.ts`). The rest write users, groups and sessions to one shared backend,
-  so widening them means a stack per engine. Screenshots are written per project name.
-- **The docs-only CI skip is `*.md` anywhere in the tree, not just the root.** No test, build step or
-  workflow reads a markdown file, so a nested `examples/plugins/admin/README.md` edit is as safe to
-  skip as `README.md`. Both git channels in `ci.sh`'s `docs_only()` pass `--no-renames`: rename
-  detection names only the destination, so `git mv src/app.ts notes.md` otherwise read as docs and
-  skipped the gate over a source file that was gone. `src/ci-gate.test.ts` locks the flags as a *text*
-  guard — the test image ships neither `git` nor `bash`. Revisit if a `.md` ever becomes load-bearing.
+  so widening them means a stack per engine.
+- **The docs-only CI skip is `*.md` anywhere in the tree, not just the root** — no test, build step or
+  workflow reads a markdown file. Both git channels in `ci.sh`'s `docs_only()` pass `--no-renames`:
+  rename detection names only the destination, so `git mv src/app.ts notes.md` would otherwise read as
+  docs and skip the gate over a source file that was gone. `src/ci-gate.test.ts` locks the flags as a
+  *text* guard — the test image ships neither `git` nor `bash`. Revisit if a `.md` ever becomes
+  load-bearing.
 - **CI docker logins share the runner host's Docker config.** The act_runner is host-mode, so
   `docker login`/`logout` in the workflows mutate one shared `~/.docker/config.json`: concurrent jobs
   can race (one job's logout can 401 another's push — recover by re-running), and tokens sit in that
   file between login and logout. Same class: concurrent runs share the workspace dir, so ci.sh's
   web-image build races another run's container creation on the `<project>-web` tag. Accepted for a
   single-maintainer cadence; serialize with a workflow `concurrency` group if it ever bites.
-- **Plainpages is pre-announcement: no tags, no releases.** All tags and semver container tags were
-  deleted, and `auto-release` is gated behind the `AUTO_RELEASE` Actions variable (unset ⇒ skipped,
-  the fail-safe direction on every unknown-`vars` path). A version only communicates to consumers and
-  there are none — the same reasoning that freezes `HOST_API_VERSION`. Two couplings: `registry-cleanup`
-  keeps a hash image only while its commit is a branch head *or* release-tagged, so with zero tags a
-  hand-cut tag must sit on `main`'s tip; and `mirror.yml` pushes tags with `--prune` (so its
-  `fetch-tags: true` is load-bearing), meaning a tag or Release created on GitHub is swept away and
-  releases are cut on Gitea only. Valid until the
-  maintainer says Plainpages is ready to show people.
-- **A stricter manifest rule breaks already-copied plugins, and while `HOST_API_VERSION` is frozen the
-  failure names a symptom rather than the cause.** `plugins/` is an operator-owned drop-in mount, so an
-  operator's copy is whatever version they took. `checkApiVersion` is the right mechanism — a breaking
-  manifest change bumps the major and a stale plugin is refused by *version* — but that only works once
-  the freeze lifts. Until then a stricter rule ships with a README → Upgrading entry and a re-copy hint
-  in the discovery error. Fail-loud stays right either way: the alternative is a route gating on a name
-  nobody can be granted, i.e. a permanent silent 403. **Valid while `HOST_API_VERSION` stays frozen.**
+- **Plainpages is pre-announcement: no tags, no releases.** `auto-release` is gated behind the
+  `AUTO_RELEASE` Actions variable (unset ⇒ skipped, the fail-safe direction on every unknown-`vars`
+  path) — a version only communicates to consumers and there are none. Two couplings:
+  `registry-cleanup` keeps a hash image only while its commit is a branch head *or* release-tagged, so
+  with zero tags a hand-cut tag must sit on `main`'s tip; and `mirror.yml` pushes tags with `--prune`
+  (its `fetch-tags: true` is load-bearing), so a tag or Release created on GitHub is swept away and
+  releases are cut on Gitea only. Valid until the maintainer says Plainpages is ready to show people.
+- **A stricter manifest rule breaks already-copied plugins**, and while `HOST_API_VERSION` is frozen
+  the failure names a symptom rather than the cause — `checkApiVersion` would refuse a stale plugin by
+  *version*, but only once the freeze lifts. Until then a stricter rule ships with a README →
+  Upgrading entry and a re-copy hint in the discovery error. Fail-loud stays right either way: the
+  alternative is a route gating on a name nobody can be granted, i.e. a permanent silent 403.
+  **Valid while `HOST_API_VERSION` stays frozen.**
 
 ## Docker only — no host tooling
 
@@ -298,8 +285,8 @@ docker compose -f compose.yml up --build -d              # production
 `README.md` serves two readers, in this order — preserve it when editing:
 
 1. **First-time reader (top).** A one/two-sentence tagline, then a **Quick start** that gets the
-   stack up and a *minimal* plugin live. Nothing comes before Quick start — no philosophy, no
-   rationale. Keep its commands copy-pasteable; deeper detail lives in its own section, linked.
+   stack up and a *minimal* plugin live. Nothing comes before Quick start. Keep its commands
+   copy-pasteable; deeper detail lives in its own section, linked.
 2. **Returning developer (rest).** A **Contents** ToC right after Quick start, then sections ordered
    by **what an adopter reaches for first**, not by architectural layering: Overview → Users, groups
    & permissions → Building plugins → menu/blocks/interactivity → Configuration → Auth → Email →
@@ -308,29 +295,23 @@ docker compose -f compose.yml up --build -d              # production
    permissions precedes Building plugins** because a manifest's `permission:` gate is unreadable
    without the model, and it is the one home for that model.
 
-When editing: put content in the section it belongs to; keep the ToC in sync when you add/rename/
-remove an `H2`/`H3`; state each fact in one home and link to it.
-
-**Don't document internals here.** How a script reaches a decision, what a function guards — a
-developer can read that off the code in seconds, and it only makes the README longer for humans and
-machines alike. It belongs in the code, or nowhere. The README earns its length on what you cannot
-dig out: how to use and operate Plainpages, the external contracts, and one-time setup. Same test
-before adding a row to a table or the file map — a clause, not a paragraph.
+Keep the ToC in sync when you add/rename/remove an `H2`/`H3`. **Don't document internals** — how a
+script reaches a decision, what a function guards; a developer reads that off the code in seconds.
+The README earns its length on how to use and operate Plainpages, the external contracts, and
+one-time setup. A file-map or table row gets a clause, not a paragraph.
 
 ## Rules
 
 - Node 24 runs `.ts` directly (type stripping). Keep all TypeScript **erasable**
   (`erasableSyntaxOnly` is on): no `enum`, `namespace`, parameter properties, or decorators. Import
   local modules with their `.ts` extension.
-- **No `.mjs`.** Write modules as `.ts` — even standalone scripts run in bare `node:24` containers
-  (the e2e mock servers, `examples/shifts-upstream/server.ts`). If a file genuinely must be plain
-  JavaScript, use `.js`; `"type": "module"` is set in both `package.json`s, so `.js` is ESM.
+- **No `.mjs`.** Write modules as `.ts` — even standalone scripts run in bare `node:24` containers.
+  If a file genuinely must be plain JavaScript, use `.js`; `"type": "module"` is set in both
+  `package.json`s, so `.js` is ESM.
 - **No build step** and no compiled artifacts — do not add a bundler or `tsc` emit.
 - Before finishing a change, run the typecheck and tests above; both must pass.
 - Tests use the built-in `node --test` runner — no test framework dependency.
-- English everywhere. Keep code comments short and information-dense; self-explained code with no
-  comment at all is preferred.
-- Do not comment about history ("this moved from X"), or about the absence of things.
+- English everywhere.
 - Pin all dependencies and Docker images to exact, human-readable **semantic versions** — never
   ranges (`^`, `~`) and never digests. npm deps via `.npmrc` (`save-exact=true`) + `npm ci`; images
   by tag.
@@ -370,3 +351,10 @@ before adding a row to a table or the file map — a clause, not a paragraph.
 - Use well formed, standard compliant, rich URIs. Prefer state in the URL over POSTing it, for
   example on list pages with filters and pagination. Do `ids=x&ids=y`, not `ids[]=x&ids[]=y` and not
   `ids=x,y`.
+
+## Comments
+
+Default to **no comment**. Delete one that restates the adjacent code, repeats a convention used
+elsewhere, justifies self-evident code, or records history. Write one only for what a competent
+reader of *this* codebase could not infer: a surprising why, a footgun, an invariant, an external
+constraint. See [Prose discipline](#prose-discipline).
diff --git a/README.md b/README.md
index df31551..002ee93 100644
--- a/README.md
+++ b/README.md
@@ -36,10 +36,9 @@ docker compose up -d
 ```
 
 The bootstrap grants the seeded admin every permission the installed plugins declare, so the
-**Admin** section now shows in the menu. Use `up -d`, not `restart web`: the seed runs in the
-one-shot `bootstrap` service, and only `up` re-runs it to pick up the new plugin's permissions
-(it is idempotent, so re-running costs nothing).
-See [`examples/plugins/admin/`](examples/plugins/admin/).
+**Admin** section now shows in the menu. Use `up -d`, not `restart web` — the seed runs in the
+one-shot `bootstrap` service, and only `up` re-runs it. See
+[`examples/plugins/admin/`](examples/plugins/admin/).
 
 **4. Add your first plugin.** The clone is bind-mounted into the container, so a new
 folder under `plugins/` goes live after a restart. Create `plugins/hello/plugin.ts`:
@@ -72,7 +71,6 @@ From here, render real pages against the app shell and fetch upstream data — s
 ## Contents
 
 - [Overview](#overview)
-  - [how it compares](#how-it-compares)
 - [Users, groups & permissions](#users-groups--permissions)
   - [naming a permission](#naming-a-permission)
   - [a worked example](#a-worked-example)
@@ -112,6 +110,7 @@ From here, render real pages against the app shell and fetch upstream data — s
   - [end-to-end](#end-to-end-playwright)
   - [the full gate](#the-full-gate-one-command)
 - [CI/CD](#cicd)
+  - [one-time setup](#one-time-ci-setup)
 - [Production & deployment](#production--deployment)
 - [Upgrading](#upgrading)
 - [Observability](#observability)
@@ -123,119 +122,38 @@ From here, render real pages against the app shell and fetch upstream data — s
 
 Plainpages gives you the boring-but-hard parts of a web app — a design system, a menu,
 sessions, and access control — and stays out of your domain logic. **Any page can be public
-or gated**, so the same foundation serves a purely public site, a fully locked-down internal
-tool, or the common middle: a public front with an authenticated area behind it. Its **sweet
-spot** is the **back-office and operational tooling** you'd otherwise hand-roll for the tenth
-time, but nothing ties it to internal-only use. The core itself ships **no domain screens at
-all** — even the screens for running the system (**users, groups, OAuth2 clients**) are a **drop-in
-plugin** you opt into ([`examples/plugins/admin/`](examples/plugins/admin/)). Everything is a plugin.
-
-**Who it's for.** Experienced developers building server-rendered web products — back-office
-and operational tools, dashboards, portals, or public sites with a gated area — for their own
-use or for a client. You know HTTP, Docker, and identity
-providers, and you'd rather assemble pages from building blocks than fight a framework or
-hand-roll auth for the tenth time. It's not a no-code tool and doesn't hide its moving
-parts: if "Ory is down ⇒ no logins" (see [Auth](#auth-sessions--access)) reads as
-obvious rather than surprising, you're the audience.
-
-**Who *they* build for.** The people who end up in front of a Plainpages app are not the
-audience above, and three of them shape the design more than any feature request does:
-
-- **The end user** — anyone using the product you assemble from Plainpages + your plugins.
-  They never hear the word "plugin": to them the menu, the screens and the sign-in are one app,
-  which is why the shell, the auth pages and every plugin share one design system, one menu and
-  one language.
-- **The power user** — lives in the app all day. Ctrl-clicks a row to open it in a new tab,
-  bookmarks a filtered-and-sorted list to come back to on Monday, sends that URL to a colleague,
-  and edits the query string by hand when it's faster. This is why list state and the chosen
-  language live **in the URL** and why every navigation is a real `<a href>`: middle-click, "open
-  in new tab", back, and bookmark all have to work without a second thought.
-- **The non-technical user** — clicks a button twice when nothing happens fast enough, never
-  touches the tab key, doesn't distinguish a link from a button, and won't recognise an error
-  code. This is why destructive actions go through a confirm page instead of an inline
-  `?confirm=1`, why a form's labels are clickable and its errors sit next to the field they
-  belong to, and why a page must never depend on keyboard-only affordances. A double-clicked
-  submit is a real event, not a misuse.
-
-**Included vs. what you add.**
+or gated**, so the same foundation serves a public site, a locked-down internal tool, or a
+public front with an authenticated area behind it.
 
 - **Included in the core:** themed sign-in / register / reset (Kratos-backed), the design
   system + app shell, the config-driven menu, sessions, and access control. No domain screens.
-- **Opt-in admin plugin:** the **users, groups, and OAuth2-clients** screens (users via
-  Kratos, the relationship graph via Keto, OAuth2 clients via Hydra) ship as
-  [`examples/plugins/admin/`](examples/plugins/admin/) — copy it into `plugins/` to get a GUI for
-  user & group admin. It's an ordinary plugin, using the privileged
-  [`ctx.system`](#system-capabilities-the-ctxsystem-surface) surface to reach Ory.
-- **You add:** everything else domain-specific, as **plugins** — a list page, a form, a
-  scheduler, a register, a dashboard — built from the same building blocks the admin plugin uses.
+- **Opt-in admin plugin:** the **users, groups, and OAuth2-clients** screens ship as
+  [`examples/plugins/admin/`](examples/plugins/admin/) — an ordinary plugin, reaching Ory through
+  the privileged [`ctx.system`](#system-capabilities-the-ctxsystem-surface) surface.
+- **You add:** everything else domain-specific, as **plugins** — built from the same building
+  blocks the admin plugin uses.
 
-**Priorities (unchanged from day one):** **simplicity, few dependencies, strict
-TypeScript, no build step, Docker-only, environment-agnostic** (no `NODE_ENV` — every
-behaviour is an explicit config toggle). Heavy lifting that *isn't* simple to do well —
-identity, sessions, SSO, OAuth2, permission checks — is delegated to **Ory** sidecar
-services rather than reinvented. "Simple" is about the *whole architecture* staying simple
-— not just at the start, but after you've dropped in 240 plugins and run it hard in
-production. The shape doesn't change as it grows: every plugin is the same self-contained
-folder, the hot path is the same I/O-free JWT check, and there's no app database to scale
-or migrate.
+**Priorities:** simplicity, few dependencies, strict TypeScript, no build step, Docker-only,
+environment-agnostic (no `NODE_ENV` — every behaviour is an explicit config toggle). Identity,
+sessions, SSO, OAuth2 and permission checks are delegated to **Ory** sidecar services. The shape
+doesn't change as it grows: every plugin is the same self-contained folder, the hot path is the
+same I/O-free JWT check, and there is no app database.
 
-**Plugins are the extension model — powerful, predictable, fail-loud.** Everything
-domain-specific is a plugin, and the plugin API is the product's main surface, written for
-experienced developers. It optimises for being **powerful, predictable, and overloadable** —
-a plugin can take over as much of a page as it wants. The host **fails loud at boot/discovery**
-rather than sandboxing at runtime: a malformed manifest, a version mismatch, or a conflict
-stops startup with a clear message. Runtime crash-isolation (one bad plugin can't take the
-host down) is a deliberate **non-goal** — diagnose at deploy time, not in production. See
-[Building plugins](#building-plugins).
+**Plugins are the extension model.** The plugin API is the product's main surface: powerful,
+predictable, and overloadable — a plugin can take over as much of a page as it wants. The host
+**fails loud at boot/discovery** (bad manifest, version mismatch, conflict) rather than sandboxing
+at runtime; crash-isolation is a deliberate non-goal. See [Building plugins](#building-plugins).
 
-**Low-end by design.** Plainpages deliberately targets **low-end systems, odd hardware,
-and low-bandwidth environments** — a tablet on a factory floor, an old thin client at a
-reception desk, a remote site on a flaky link. That's *why* the baseline is boring,
-standards-compliant **HTML + CSS with zero JavaScript**: it loads fast, degrades
-gracefully, and works on whatever browser is already there. Where a modern **CSS** feature
-removes the need for JavaScript (theme switching, popovers, disclosure) we use it — the
-trade we avoid is shipping a client-side runtime, not using the platform. That
-standards-first stance also makes **semantic, accessible markup** a priority: real
-landmarks, one `<h1>` per page, lists and tables with proper headers, a skip link, and
-ARIA (`aria-current`/`aria-sort`) only where the platform leaves a gap (see
-[AGENTS.md](AGENTS.md)).
-
-### How it compares
-
-The space around Plainpages is crowded, but it splits into families that each share **one**
-of its traits and miss the rest. Here's the map — established names per family, and where
-Plainpages sits relative to them:
-
-| Family · examples | What it is | Where Plainpages differs |
-| --- | --- | --- |
-| **Modular app frameworks** — Odoo · Frappe · OrchardCore · ABP | extend by dropping a **module folder** in; server-rendered | Closest in *shape* to the plugin model, but each is **metadata/model-driven with its own ORM/DB** and a large framework. Plainpages keeps the folder model while staying **stateless, framework-light, and component-not-generator**. |
-| **Developer portals / IDPs** — Backstage · Port · Cortex · Roadie · OpsLevel · Compass | plugin-based internal platforms with a service catalog | Closest on the **plugin** axis, but heavy **React SPAs** with a build step, built to catalog services. Plainpages is **zero-JS, few-deps, no-build** and renders general pages, not a catalog. |
-| **Model-driven auto-admin** — Django Admin · AdminJS · Filament · ActiveAdmin · EasyAdmin · Sonata · sqladmin · Starlette-admin | generate a CRUD UI **from your ORM/DB models** | Plainpages is a **component library, not a generator** — there is **no app DB** to model against; handlers fetch from upstream and you assemble the page. |
-| **Schema-driven content platforms** — KeystoneJS · Payload · Directus · Strapi · Wagtail | define a content schema, get an admin **+ API**; they own the data | Plainpages owns **no data** and isn't schema-first; it renders pages over services you already run, rather than being the system of record. |
-| **Naked-objects / runtime UI** — Apache Causeway · OpenXava · JHipster | the UI is **auto-projected from domain objects** (the generator extreme) | The opposite stance: Plainpages hands you **building blocks to assemble**, with no domain model driving the screen. |
-| **Low-code builders** — Retool · Appsmith · ToolJet · Budibase · NocoBase · ILLA | drag-and-drop GUI builders, **client-JS-heavy**, runtime state | Plainpages is **code-first and zero-JS** — server-rendered HTML versioned in your repo, no visual editor or runtime app state. |
-| **Code-first internal-tool platforms** — Windmill · Lowdefy · Superblocks | turn **scripts/config into auto-generated UIs** | Closest in *spirit* (for developers, self-hosted), but script/workflow-runner-centric. Plainpages gives you **full pages you control**, not a UI inferred from a function signature. |
-| **Hypermedia / zero-JS movement** — htmx · Hotwire/Turbo · Unpoly · Datastar | the **server-rendered-HTML philosophy** Plainpages is built on | These are *techniques*, not a foundation — no auth, menu, or plugins. Plainpages is what you **assemble with** the approach (and plugins may opt into htmx). *(Phoenix LiveView shares it but trades in a stateful socket.)* |
-| **CSS-only admin shells** — AdminLTE · Tabler · Bootstrap themes | a **visual shell** — markup + styles only | No backend, auth, routing, or extension model. Plainpages **includes the shell** and adds the hard-every-time parts. |
-| **Themed auth UI on Ory** — Kratos self-service UIs (`ory/kratos-selfservice-ui-node`, `kratos-admin-ui`) | the **login / registration screens** over Ory | The one *slice* with a direct off-the-shelf alternative: Plainpages reimplements it inside its own shell, so you could swap it out to avoid maintaining that part. |
-
-No family combines the whole set: **[drop-in plugin folders](#building-plugins)**, a **zero-JS
-server-rendered** design system, **[optional auth](#auth-sessions--access)** (any page
-public or gated), **no app database**, and a **framework-light TypeScript** core with no build
-step. Each neighbour shares one trait and trades away the rest — Plainpages is the intersection.
+**Zero JavaScript**, so pages stay fast on low-end hardware and flaky links. Where a modern CSS
+feature removes the need for JS (theme switching, popovers, disclosure) we use it — the trade we
+avoid is shipping a client-side runtime, not using the platform. Markup is semantic and accessible
+(see [AGENTS.md](AGENTS.md)).
 
 ## Users, groups & permissions
 
 Authorization here is two hops: a **user** — directly, or through a **group** — is granted a
-**permission**, and that permission's *name* is exactly the string a plugin gates on.
-
-- **Group** answers *who* — a reusable set of people. Optional: a permission can be granted
-  straight to a user.
-- **Permission** answers *what* — its **name is the string** you write in a manifest's
-  `permission:` gate.
-- **A relation tuple** is the grant: `Permission:<name>#granted@user:<id>`, or
-  `@Group:<name>#members`.
-- **Resource** answers *which row* — a live check, run only where a plugin explicitly asks for it.
+**permission**, and that permission's *name* is exactly the string a plugin gates on. Grants are
+Keto relation tuples: `Permission:<name>#granted@user:<id>`, or `@Group:<name>#members`.
 
 | Entity | Lives in | Answers | Example |
 | --- | --- | --- | --- |
@@ -244,57 +162,42 @@ Authorization here is two hops: a **user** — directly, or through a **group**
 | **Permission** | Keto | what you may do | `Permission:scheduling:read` |
 | **Resource** | Keto | which specific row | `Resource:shift-4471` |
 
-Users live in Kratos; every authorization edge is a Keto relation tuple. The app itself
-stores none of it — it is [stateless](#stateless).
+Keto's whole model is one primitive — `namespace:object#relation@subject` — so those four
+namespaces are *ours*, declared in `ory/keto/namespaces.keto.ts`; Keto resolves them, transitively
+through nested groups. The app stores none of it — it is [stateless](#stateless).
 
-**Keto ships no entities of its own.** Its entire model is one primitive —
-`namespace:object#relation@subject` — so the four namespaces above are *ours*, declared in
-`ory/keto/namespaces.keto.ts`; Keto only supplies the machinery that resolves them (including
-transitively, through nested groups).
-
-> **Ory calls a user an "identity".** Kratos owns that record and names it so: its API is
-> `/admin/identities`, and a session carries `session.identity`. Plainpages says **user**
-> everywhere, because that is the word readers already know — and Ory's own documentation states
-> it uses "identity" interchangeably with "users" and "accounts". You will meet Ory's spelling in
-> exactly two places: the Kratos API itself, and the `Identity` type in `src/auth/kratos-admin.ts`
-> that mirrors it.
-
-> **There is no `Role`.** In RBAC a permission is a single operation ("read shifts") and a role is
-> a *bundle* of them ("IT Support staff"). A route gates on one operation, so it gates on a
-> **permission**. When you want the bundle, make a group and grant it several — groups nest, so a
-> group of groups works too.
+> **There is no `Role`.** A route gates on a single operation, so it gates on a **permission**. For
+> a bundle ("IT Support staff"), make a group and grant it several — groups nest.
+>
+> **Ory calls a user an "identity"** (its own docs use the terms interchangeably). Plainpages says
+> **user** everywhere; you meet Ory's spelling only in the Kratos API and the `Identity` type in
+> `src/auth/kratos-admin.ts` that mirrors it.
 
 ### Naming a permission
 
-**Every permission name is `<resource>:<action>`.** `scheduling:read`, `users:write`,
-`oauth2-clients:read`. Both halves are lowercase letters, digits, dashes and underscores, and the
-host refuses a plugin that breaks the rule at discovery — so it holds for every installed plugin,
-not just the ones you wrote.
+**Every permission name is `<resource>:<action>`** — `scheduling:read`, `users:write`,
+`oauth2-clients:read`. Both halves are lowercase letters, digits, dashes and underscores; discovery
+refuses a plugin that breaks the rule, so it holds for every installed plugin.
 
-- **`<resource>`** names the thing acted on, not the plugin that happens to own it — permission
-  names are one **global namespace**, so an operator grants `scheduling:read` once and every plugin
-  referencing it is gated consistently. Pick a name no other plugin would claim for something else:
-  `oauth2-clients`, not `clients`.
-- **`<action>`** names the operation. `read` and `write` cover most screens; use a more specific
-  verb when the operation really is distinct (`invoices:approve`).
+- **`<resource>`** names the thing acted on, not the plugin that owns it — names are one **global
+  namespace**, so an operator grants `scheduling:read` once and every plugin referencing it is gated
+  consistently. Pick one no other plugin would claim: `oauth2-clients`, not `clients`.
+- **`<action>`** names the operation. `read`/`write` cover most screens; use a specific verb when the
+  operation really is distinct (`invoices:approve`).
 
-A bare word is the mistake this rule exists to stop. `admin` says *who someone is*, not *what they
-may do* — that is a role, and roles are **groups** here. Split it by resource and action, then
-bundle it back up with a group if you want one grant to hand out several:
+A bare word like `admin` says *who someone is*, not *what they may do* — that is a role, and roles
+are **groups** here. Split by resource and action, then bundle with a group:
 
 ```
 Group:it-support ──> Permission:users:read, Permission:users:write, Permission:groups:read, …
 ```
 
-The host checks the shape at **discovery**: a plugin gating on — or declaring — a name that isn't
-`<resource>:<action>` stops the boot, like any other bad manifest. Declaring is still optional, so
-two plugins may deliberately share a name.
+Declaring a permission stays optional, so two plugins may deliberately share a name.
 
-> **A `:write` is not a small grant.** Splitting by resource contains the **read** half — `users:read`
-> alone is a safe helpdesk grant. It contains the write half much less than the naming suggests:
-> `groups:write` lets someone add themselves to a group that holds every permission, and `users:write`
-> lets them mint a recovery code for any account and sign in as it. Treat `users:write` and
-> `groups:write` as full administrative access.
+> **A `:write` is not a small grant.** The split contains the **read** half — `users:read` alone is a
+> safe helpdesk grant — but `groups:write` lets someone add themselves to a group holding every
+> permission, and `users:write` lets them mint a recovery code for any account. Treat both as full
+> administrative access.
 
 ### A worked example
 
@@ -314,19 +217,11 @@ Alice works support and leads scheduling; Bob works support; Carol administers t
                                          └──>  Permission:users:write
 ```
 
-At login the host asks Keto which permissions the user holds, walking those arrows
-transitively, and bakes the answer into the session JWT (see [Login and the session
-JWT](#login-and-the-session-jwt)):
-
-```
-alice → permissions: ["scheduling:read", "scheduling:write"]
-bob   → permissions: ["scheduling:read"]
-carol → permissions: ["users:read", "users:write"]
-```
-
-Note what Carol does *not* have. **Permissions do not nest, and there is no superuser** — running
-the Users screen grants nothing on Groups, and nothing at all on `/scheduling`. `it-support` is the
-bundle; it is a **group**, not a permission.
+At login the host asks Keto which permissions the user holds, walking those arrows transitively,
+and bakes the answer into the session JWT (see [Login and the session
+JWT](#login-and-the-session-jwt)) — alice gets `scheduling:read` + `scheduling:write`, bob
+`scheduling:read`, carol `users:read` + `users:write`. **Permissions do not nest and there is no
+superuser**: carol's Users grant buys nothing on Groups or `/scheduling`.
 
 Against the reference plugins' actual routes:
 
@@ -340,15 +235,11 @@ Against the reference plugins' actual routes:
 | `POST /admin/users` | `users:write` | 403 | 403 | ✅ | → `/login` |
 | `GET /admin/groups` | `groups:read` | 403 | 403 | 403 | → `/login` |
 
-Bob reaches the shifts list with no direct grant: he is in `support`, support's members are
-`staff`, and staff holds `scheduling:read` — two hops, resolved by Keto at his login. He is
-refused the new-shift form because `scheduling:write` hangs off `sched-leads`, which he is not in.
-Carol reads *and* writes users because `it-support` holds both halves, but the Groups screen is a
-different resource and she was never granted it.
-An anonymous visitor gets a **redirect**, not a 403, carrying `return_to` so signing in lands them
-on the page they asked for; a signed-in user who merely lacks the permission gets the 403 page,
-because there is nothing to sign in *as* that would help. The menu is filtered by the same
-permissions, so nobody is shown a door they cannot open.
+Bob reaches the shifts list with no direct grant — `support` → `staff` → `scheduling:read`, two hops
+resolved by Keto at his login. An anonymous visitor gets a **redirect** carrying `return_to`, not a
+403; a signed-in user who merely lacks the permission gets the 403 page, since there is nothing to
+sign in *as* that would help. The menu is filtered by the same permissions, so nobody is shown a
+door they cannot open.
 
 ### Granting a permission
 
@@ -364,11 +255,10 @@ curl -X PUT http://keto:4467/admin/relation-tuples -H 'content-type: application
 ```
 
 **A permission's name is authored in plugin code; only its *grants* live in Keto.** A plugin
-declares the permissions it gates on (`permissions:` in the manifest), and the host collects them
-into one catalog — `ctx.declaredPermissions` — which is exactly the fixed list the admin screens
-offer. Nothing in the GUI invents a name: granting is ticking a box against that list, and a tuple
-in Keto naming something no installed plugin declares gates nothing. Name yours
-[`<resource>:<action>`](#naming-a-permission).
+declares the permissions it gates on (`permissions:` in the manifest) and the host collects them
+into one catalog — `ctx.declaredPermissions` — which is the fixed list the admin screens offer.
+Nothing in a GUI invents a name, and a tuple naming something no installed plugin declares gates
+nothing.
 
 A change takes effect on the user's **next login or JWT re-mint** (~10 min) — see [Instant
 revoke](#instant-revoke-the-optional-denylist) when you need it sooner.
@@ -376,12 +266,11 @@ revoke](#instant-revoke-the-optional-denylist) when you need it sooner.
 ### Fine-grained, per-row access
 
 The `Resource` namespace covers what a coarse permission cannot express: *this* row, shared with
-*this* person. It is a separate mechanism — a `Resource` carries Keto `permits` (`view`, `edit`,
-`delete`, which nest as `owner` ⊇ `editor` ⊇ `viewer`) and never appears in the JWT.
+*this* person. A `Resource` carries Keto `permits` (`view`, `edit`, `delete`, nesting as `owner` ⊇
+`editor` ⊇ `viewer`) and never appears in the JWT.
 
-**A per-row grant never widens a coarse gate.** The route's `permission` is checked *before* the
-handler runs, so a user rejected there never reaches the check. Gate the route on something they
-hold, then narrow inside the handler:
+**A per-row grant never widens a coarse gate** — the route's `permission` is checked before the
+handler runs. Gate the route on something they hold, then narrow inside the handler:
 
 ```ts
 { method: "POST", path: "/shifts/:id", permission: READ, handler: editShift }
@@ -402,17 +291,13 @@ I?"](#three-tiers-of-may-i).
 A plugin is a self-contained folder under `plugins/` that the host discovers at boot — no
 registration step, no central wiring. Each plugin carries its own nav, routes, views, and CSS.
 
-This is the **authoritative reference** for the plugin API — the product's main surface. The
-contract is **TypeScript** (`src/plugin-host/plugin.ts`), so the types there are the single
-source of truth; the sections below explain them, the guarantees around them, and the rules
-the host enforces. A complete, runnable example lives in
-**[`examples/plugins/scheduling/`](examples/plugins/scheduling/)** — a public overview page, a
-permission-gated list page fetching upstream data (it points `SCHEDULING_UPSTREAM` at its backend;
-the dev compose ships a tiny mock, `examples/shifts-upstream/`), a CSRF-guarded form forwarding
-writes upstream, and a mix of public + permission-gated nav. It is **not** pre-installed — `plugins/`
-ships empty so you mount your own. To run it in dev, copy it in
-(`cp -r examples/plugins/scheduling plugins/scheduling`, then restart) — the dev compose already
-points `SCHEDULING_UPSTREAM` at its mock backend. Copy it to `plugins/<id>/` and adapt.
+The contract is **TypeScript** (`src/plugin-host/plugin.ts`); the types there are the source of
+truth and the sections below explain them and the rules the host enforces. A runnable example lives
+in **[`examples/plugins/scheduling/`](examples/plugins/scheduling/)** — a public overview page, a
+permission-gated list page over an upstream service, a CSRF-guarded form, and a mix of public +
+gated nav. `plugins/` ships empty, so copy it in to run it
+(`cp -r examples/plugins/scheduling plugins/scheduling`, then restart); the dev compose already
+points `SCHEDULING_UPSTREAM` at its mock backend (`examples/shifts-upstream/`).
 
 ### Anatomy of a plugin
 
@@ -429,43 +314,30 @@ plugins/things/          # the plugin folder — its name is the id AND the moun
   service.ts             #   e.g. route handlers, upstream calls, domain helpers — design as you wish
 ```
 
-**Only `plugin.ts` is required.** The host looks for exactly that filename and its
-default-exported manifest. `views/`, `public/` and `i18n/` are the fixed folder *names* it resolves
-against — used only if the plugin renders views, serves assets or ships translations — but the files
-inside are yours to name (a catalog is named for its locale). Everything else (handlers, upstream clients, their filenames and folder layout)
-the host never sees; `plugin.ts` simply imports it. The `handlers.ts`/`service.ts` split above is
-just an example — name and arrange your modules however you like, or keep a routes-only plugin to a
-single `plugin.ts`.
+**Only `plugin.ts` is required.** `views/`, `public/` and `i18n/` are fixed folder *names* the host
+resolves against, but the files inside are yours to name. Everything else — handlers, upstream
+clients, their layout — the host never sees; `plugin.ts` simply imports it.
 
-**Identity comes from the folder.** The folder name *is* the plugin `id`, and the mount path is
-`/<id>` — neither is written in the manifest, so they can't drift or be claimed twice. The id
-must be **URL/path-safe** (`isValidPluginId`: lowercase `a–z`, digits, and dashes — dashes
-anywhere; no uppercase, underscores, dots, or slashes); the host rejects a malformed folder name
-at discovery. The id also namespaces the plugin's `views/`, its `/public/<id>/` assets, and (by
-convention) its nav/permission names.
+**Identity comes from the folder.** The folder name *is* the plugin `id` and the mount path is
+`/<id>`; neither is in the manifest, so they can't drift or be claimed twice. The id must be
+URL/path-safe (`isValidPluginId`: lowercase `a–z`, digits, dashes) and also namespaces the plugin's
+`views/`, its `/public/<id>/` assets, and by convention its nav/permission names.
 
-A handful of ids are **reserved** for the host's own first-party mounts — the gated `dashboard`, the
-Kratos auth flows (`auth`, `login`, `logout`, `recovery`, `registration`, `settings`, `verification`),
-the `oauth2` provider routes, and `public` (static). Since plugin routes resolve first, a folder
-claiming one would silently shadow a built-in route, so discovery refuses it loud
-(`RESERVED_PLUGIN_IDS`). (`/` is owned by the `home` field, not a route, so it needs no reservation;
-`admin` is **not** reserved — the admin screens are themselves a drop-in plugin mounted at `/admin`.)
+`RESERVED_PLUGIN_IDS` are refused at discovery — the gated `dashboard`, the Kratos auth flows
+(`auth`, `login`, `logout`, `recovery`, `registration`, `settings`, `verification`), the `oauth2`
+provider routes, and `public` — since plugin routes resolve first and a folder claiming one would
+silently shadow a built-in. `admin` is **not** reserved: the admin screens are themselves a plugin.
 
-Installing a plugin is "drop the folder, restart." Removing one is "delete the folder, restart."
-Nothing else references it; the operator stays in control through the central menu override
-(`config/menu.ts`).
+Installing a plugin is "drop the folder, restart"; removing one is "delete the folder, restart".
 
 ### The manifest
 
-A plugin imports its host surface from one module — **`#plugin-api`** (a Node [subpath
+A plugin imports its host surface from one module — **`#plugin-api`**, a Node [subpath
 import](https://nodejs.org/api/packages.html#subpath-imports) mapped to `src/plugin-host/plugin-api.ts`
-in the root `package.json`), the **stable author barrel** (`definePlugin`, the manifest/handler types,
-`RequestContext`, the guards, and the body/CSRF/list-query helpers). Using `#plugin-api` (not a relative
-`../../src/...` path) means the same import works at any folder depth and survives host refactors — it
-resolves against the app's `package.json` wherever your plugin folder sits under it. That barrel *is* the
-contract boundary; don't reach into deeper `src/*` modules — the host may refactor those freely as long as
-the barrel holds. (Keep your plugin a plain folder — no `package.json` of its own — so `#plugin-api`
-resolves against the host's.)
+in the root `package.json` (`definePlugin`, the manifest/handler types, `RequestContext`, the guards,
+and the body/CSRF/list-query helpers). That barrel **is** the contract boundary — never a relative
+`../../src/...` path; the host refactors everything behind it freely. Keep your plugin a plain folder
+with no `package.json` of its own, or `#plugin-api` resolves against that instead.
 
 ```ts
 import { definePlugin } from "#plugin-api";
@@ -492,11 +364,9 @@ export default definePlugin({
 });
 ```
 
-`definePlugin()` only types the object and returns it unchanged — a manifest may equally be a
-plain typed object. It types the authored shape (`PluginManifest`); the host attaches the
-folder-derived `id` to produce the loaded `Plugin`. All validation happens at discovery. Note
-there is **no `id` or `basePath`** in the manifest — both come from the folder
-([Anatomy](#anatomy-of-a-plugin)).
+`definePlugin()` only types the object (`PluginManifest`) and returns it unchanged — a manifest may
+equally be a plain typed object. All validation happens at discovery, and the host attaches the
+folder-derived `id` to produce the loaded `Plugin`.
 
 | Field | Required | Notes |
 | --- | --- | --- |
@@ -513,15 +383,12 @@ A plugin may be routes-only, nav-only, or hooks-only — every collection field
 ### Routes & handlers
 
 A route is `{ method, path, permission?, public?, handler }`. `path` is **relative to the plugin's
-mount path `/<id>`** (so `path: "/:id"` in the `things` plugin serves `/things/:id`); the host
-matches `method` + the resolved full path, extracts `:name` segments into `ctx.params.name`,
-runs the `permission` gate (a coarse JWT-claim check — see [Nav & permission gates](#nav--permission-gates)),
-and only then calls the handler with the [request context](#requestcontext). When the gate fails, an
-**anonymous** visitor is redirected to `/login` to sign in; the
-requested page is preserved as `return_to`, so after signing in they land **back on the page they
-asked for**, not the dashboard. A **signed-in** user who simply lacks the permission gets the **403** page.
-A route marked **`public: true`** has no gate at all — anyone reaches it (see [Public pages & menu
-items](#public-pages--menu-items)).
+mount path `/<id>`** (so `path: "/:id"` in the `things` plugin serves `/things/:id`); the host matches
+`method` + the resolved full path, extracts `:name` segments into `ctx.params.name`, runs the
+`permission` gate ([a coarse JWT-claim check](#nav--permission-gates)), then calls the handler with
+the [request context](#requestcontext). A failed gate redirects an **anonymous** visitor to `/login`
+with the page as `return_to`; a **signed-in** user lacking the permission gets the **403** page.
+`public: true` means no gate at all (see [Public pages](#public-pages--menu-items)).
 
 `method` is one of `GET HEAD POST PUT PATCH DELETE`. A `GET` route also answers `HEAD`.
 
@@ -554,36 +421,29 @@ export async function listThings(ctx: RequestContext) {
 }
 ```
 
-- **`view`** resolves against the plugin's own `views/` (`src/plugin-host/view-resolver.ts`) — nested names
-  like `"things/edit"` work, and an out-of-bounds name is refused. The template may `include()`
-  the core building-block partials (app shell, nav tree, data table, …) and its own
-  partials/subfolders to render a full page — exactly as the admin plugin's screens do. To load the
-  plugin's own CSS, pass its `/public/<id>/x.css` href in the shell's `styles` slot (an array of
-  extra stylesheet hrefs) — see the reference's `views/shifts.ejs`.
+- **`view`** resolves against the plugin's own `views/` (`src/plugin-host/view-resolver.ts`) —
+  nested names like `"things/edit"` work, out-of-bounds names are refused. The template may
+  `include()` the core building-block partials and its own. To load the plugin's own CSS, pass its
+  `/public/<id>/x.css` href in the shell's `styles` slot — see the reference's `views/shifts.ejs`.
 - **Finer authorization than the route `permission`** uses the guards from `#plugin-api`:
-  `requireSession(ctx)` (assert a session — throws a `GuardError` the host turns into a redirect
-  to sign in), `can(ctx, permission)` (a coarse JWT-claim check, zero I/O), and `check(keto, ctx,
-  {namespace, object, relation})` (a live Keto check for relationship rules — the subject is the
-  signed-in user, anonymous ⇒ denied). Throw `new GuardError(403, …)` after a failed `can`/`check`
-  to render the 403 page.
-- The handler **fetches its own data** from upstream and renders it; plugins hold no state
-  (see [Stateless](#stateless)). The partials only need rows.
-- `default` status: `200` for `view`/`html`/`json`, `303` for `redirect`.
+  `requireSession(ctx)`, `can(ctx, permission)` (coarse JWT-claim check, zero I/O), and
+  `check(keto, ctx, {namespace, object, relation})` (a live Keto check; anonymous ⇒ denied). Throw
+  `new GuardError(403, …)` after a failed `can`/`check` to render the 403 page.
+- The handler **fetches its own data** from upstream; plugins hold no state (see
+  [Stateless](#stateless)).
+- Default status: `200` for `view`/`html`/`json`, `303` for `redirect`.
 
 #### Escaping & the trust boundary
 
-The host does not sandbox plugin output (crash-isolation is a non-goal), so a handler **owns the
-safety of the data it renders**:
+The host does not sandbox plugin output, so a handler **owns the safety of the data it renders**:
 
 - **Raw HTML is raw.** An `{ html }` result and the `*.html` partial fields (`cell.html`,
-  `error.html`, a menu `trigger.html`) are emitted **unescaped** — that's their purpose (slot
-  composition). Escape any untrusted content yourself before putting it there.
-- **Text is auto-escaped; URLs are not scheme-checked.** Partials escape text fields (labels,
-  names), so those are injection-safe. But a URL field — nav `href`, a table cell link, a menu
-  item, a breadcrumb, `brand.logo` — is emitted as-is inside the attribute: a `javascript:` or
-  `data:` URL from upstream/user data becomes live XSS. When a URL comes from data you don't
-  control, pass it through **`safeUrl()`** from `#plugin-api` first — it returns the URL when
-  it's relative or `http(s):` and collapses anything else to `"#"`:
+  `error.html`, a menu `trigger.html`) are emitted **unescaped** — that's their purpose. Escape
+  untrusted content before putting it there.
+- **Text is auto-escaped; URLs are not scheme-checked.** A URL field — nav `href`, a table cell
+  link, a menu item, a breadcrumb, `brand.logo` — is emitted as-is inside the attribute, so a
+  `javascript:` or `data:` URL from upstream data becomes live XSS. Pass any URL you don't control
+  through **`safeUrl()`** from `#plugin-api`; it collapses anything but relative/`http(s):` to `"#"`:
   ```ts
   import { safeUrl } from "#plugin-api";
   return { view: "list", data: { rows: rows.map((r) => ({ ...r, href: safeUrl(r.href) })) } };
@@ -610,22 +470,15 @@ export default definePlugin({
 ```
 
 Each is a `RouteHandler` like any route's — it receives the [`RequestContext`](#requestcontext) and
-returns a `RouteResult`, typically a `view` from the plugin's own `views/`. A `dashboard` handler
-renders against the native app shell via `ctx.chrome` exactly as a route handler does; a `home`
-handler is a **public** page, so `ctx.user` may be `null` (use it to show a "go to dashboard" link to
-a signed-in visitor, or sign-in / register to an anonymous one). After login the user lands on
-`/dashboard` (or the `return_to` they were headed to), and the global menu's **Dashboard** link
-points there.
+returns a `RouteResult`, typically a `view` from the plugin's own `views/`, rendered against the
+native app shell via `ctx.chrome`. On `home` (public) `ctx.user` may be `null`; on `dashboard` the
+host enforces the session gate first, so it is non-null — branch on `ctx.permissions` *inside*
+rather than gating `dashboard` on a permission, since there is no second dashboard to fall back to.
+Both slots answer `GET` and `HEAD`.
 
-For the gated `dashboard`, the host enforces the session gate first, so `ctx.user` is non-null;
-branch on `ctx.permissions` *inside* to tailor the page per permission. Don't gate `dashboard` itself behind a
-single permission — there's no second dashboard to fall back to, so a user lacking it would land on a
-403. (Both slots answer `GET` and `HEAD`.)
-
-Only **one** plugin may own each slot: two declaring `home` (or two declaring `dashboard`) is a
-boot-stopping conflict ([below](#conflict-rules)), never last-write-wins. Neither needs a `routes`
-entry — the host mounts them above the `/<id>` route namespace, and `/` can't be shadowed by a plugin
-route at all (route paths always carry the `/<id>` prefix).
+Only **one** plugin may own each slot — two claiming either is a boot-stopping
+[conflict](#conflict-rules). Neither needs a `routes` entry; the host mounts them above the `/<id>`
+route namespace.
 
 ### RequestContext
 
@@ -653,53 +506,38 @@ interface RequestContext {
 }
 ```
 
-**`ctx.chrome`** is the page chrome the host builds per request — `{ brand, csrfToken, nav, signInHref,
-theme, user }`. Hand it to `partials/shell` so a `view` result renders the **native app shell** (the same
-sidebar, branding, theme switch and signed-in profile every page uses); `chrome.nav` is the
-global menu — your plugin's nav fragment plus every other installed plugin's (the admin section among
-them, when that plugin is present) — already composed, permission-filtered, and current-marked for this
-request (the gated **Dashboard** link is omitted for an
-anonymous visitor). `chrome.signInHref` is where the shell's anonymous **Sign in** link points — the
-current page baked in as `return_to`. Map each `chrome.*` to the matching `partials/shell` local —
-`brand`, `csrfToken`, `nav` (the rendered nav-tree), `signInHref`, `theme`, `user` — exactly as the
-reference `examples/plugins/scheduling/views/overview.ejs` does; a value you forget simply falls back to its
-shell default (e.g. a bare `/login`), it does not error. **`ctx.verifyCsrf(submitted)`** guards a
-state-changing form: render `chrome.csrfToken` in a hidden `_csrf` field, then on POST read your own
-body and `if (!ctx.verifyCsrf(form.get("_csrf"))) throw new GuardError(403, …)`. The host owns the
-secret and sets the cookie; the plugin never touches it. It is **opt-in per handler** — a route
-that never calls it has no CSRF guard at all. (See the reference: `examples/plugins/scheduling/`.)
+**`ctx.chrome`** — `{ brand, csrfToken, nav, signInHref, theme, user }`. Hand each field to the
+matching `partials/shell` local and a `view` result renders the **native app shell**, exactly as
+`examples/plugins/scheduling/views/overview.ejs` does; a field you omit falls back to its shell
+default rather than erroring. `chrome.nav` is the whole global menu — every installed plugin's
+fragment, already composed, permission-filtered and current-marked for this request.
+`chrome.signInHref` carries the current page as `return_to`. The same shell renders **every** page,
+so the menu looks identical signed in or out; `menu: false` drops the sidebar for a focused layout.
 
-The same shell renders **every** page (the dashboard, your plugin pages — the admin plugin's included, and the
-login/registration/front pages), so the menu looks identical signed in or out — it just permission-filters.
-A page that wants a focused, chrome-free layout passes **`menu: false`** to `partials/shell` (drops the
-sidebar, single column); everything else still renders.
+**`ctx.verifyCsrf(submitted)`** guards a state-changing form: render `chrome.csrfToken` in a hidden
+`_csrf` field, then on POST `if (!ctx.verifyCsrf(form.get("_csrf"))) throw new GuardError(403, …)`.
+The host owns the secret and sets the cookie. It is **opt-in per handler** — a route that never
+calls it has no CSRF guard at all.
 
-**`ctx.t`** translates in the request's language, and the same block (`t`, `locale`, `locales`,
+**`ctx.t`** translates in the request's language; the same block (`t`, `locale`, `locales`,
 `localeHref`, `dir`) is merged into every view's data — see [Languages](#languages-i18n).
 
-**`ctx.log`** is a structured, request-scoped logger ([`@larvit/log`](https://www.npmjs.com/package/@larvit/log))
-already in this request's trace: `ctx.log.info("…", { key: "value" })` (also `warn`/`error`/`debug`,
-metadata values are string/number/boolean), and **`ctx.log.fetch(url, init?)`** — a drop-in `fetch`
-for upstream calls that adds a client span and propagates the trace (W3C `traceparent`) downstream.
-The barrel also exports a standalone **`tracedFetch`** (same behaviour, reads the ambient request log)
-to default an upstream client's `fetch` to — the reference plugin's `createUpstream` does exactly this,
-so its calls are traced with no per-handler wiring. Lines are correlated by a `requestId` and carry
-`service.name`; output/level/OTLP export are the host's config (it logs to console always, and to an
-OpenTelemetry Collector when `OTLP_ENDPOINT` is set).
+**`ctx.log`** is a request-scoped [`@larvit/log`](https://www.npmjs.com/package/@larvit/log) logger
+already in this request's trace: `ctx.log.info("…", { key: "value" })`, and
+**`ctx.log.fetch(url, init?)`** — a drop-in `fetch` that adds a client span and propagates
+`traceparent` downstream. The barrel also exports a standalone **`tracedFetch`** (reads the ambient
+request log) to default an upstream client's `fetch` to, as the reference plugin's `createUpstream`
+does. Output, level and OTLP export are the host's config.
 
-**Stability guarantee.** The fields above are the stable contract — present and non-breaking
-across a major `apiVersion`. New fields may be **added** within a major version (additive, never
-breaking). `req`/`res` are the raw Node objects and the full escape hatch; reading them is fine,
-but prefer the typed fields so a handler keeps working as the host evolves. `user`/`permissions` come
-from the JWT middleware and are `null`/`[]` until a session exists.
+**Stability guarantee.** These fields are present and non-breaking across a major `apiVersion`; new
+ones may be added within it. `req`/`res` are the raw Node escape hatch — prefer the typed fields.
 
 ### System capabilities (the `ctx.system` surface)
 
-Most plugins fetch their own data from an upstream service they configure ([the scheduling
-reference](examples/plugins/scheduling/) points `SCHEDULING_UPSTREAM` at its backend). A **system
-plugin** — one that administers *Plainpages' own* identity stack rather than a domain service —
-needs the host's Ory admin clients and the instant-revoke hook instead. The host exposes those on
-**`ctx.system`**, and re-exports the client types + their error classes from `#plugin-api`:
+Most plugins fetch their own data from an upstream service they configure. A **system plugin** — one
+that administers *Plainpages' own* identity stack — needs the host's Ory admin clients and the
+instant-revoke hook instead. The host exposes those on **`ctx.system`**, and re-exports the client
+types + their error classes from `#plugin-api`:
 
 ```ts
 interface SystemCapabilities {          // every field optional — present only when the host wired it
@@ -710,65 +548,51 @@ interface SystemCapabilities {          // every field optional — present only
 }
 ```
 
-`ctx.system` is **`undefined` unless the host wired at least one** of these (Kratos/Keto configured,
-Hydra configured, the [revocation denylist](#instant-revoke-the-optional-denylist) enabled). A system
-plugin treats every field as optional and **degrades when absent** — the host never fails a request
-over it. The built-in **admin plugin** ([`examples/plugins/admin/`](examples/plugins/admin/)) is the
-reference consumer: its Users screen uses `ctx.system.kratosAdmin`, Groups and the permission pickers use `ctx.system.keto`,
-OAuth2 clients use `ctx.system.hydra`, and a deactivate/delete or user permission-change calls
-`ctx.system.revoke` so the change lands now instead of after the JWT TTL; where a capability is missing
-the screen renders a themed 503.
+`ctx.system` is **`undefined` unless the host wired at least one** of these. A system plugin treats
+every field as optional and **degrades when absent** — the host never fails a request over it. The
+**admin plugin** ([`examples/plugins/admin/`](examples/plugins/admin/)) is the reference consumer:
+Users uses `kratosAdmin`, Groups and the permission pickers `keto`, OAuth2 clients `hydra`, and a
+deactivate/delete or user permission-change calls `revoke` so the change lands before the JWT TTL;
+a missing capability renders a themed 503.
 
-This is a **privileged** surface — it hands a plugin the keys to identity and authorization. It's meant
-for first-party system plugins you author or vendor, the same trust level as any plugin (the host
-doesn't sandbox — [crash-isolation is a non-goal](#overview)). An ordinary domain plugin ignores it.
+This is a **privileged** surface — the keys to identity and authorization — meant for first-party
+system plugins you author or vendor. An ordinary domain plugin ignores it.
 
 ### Nav & permission gates
 
 A plugin's `nav` fragment is merged into the global menu by `composeNav` (`src/ui/nav.ts`), which
-applies the central override and then **filters per user** by the permissions in the session JWT — a
-node shows iff it is `public`, declares no `permission`, or the user's permissions include that name. Use
-arbitrary depth, counts, and icons; see `composeNav` for the node shape. A node's `icon` is a
-**Lucide icon**, referenced by its sprite id (e.g. `i-cal` → lucide `calendar`); the available ids
-are `ICON_NAMES` in `src/ui/icons.ts`, and adding one means registering its lucide name there.
+applies the central override and then **filters per user** by the permissions in the session JWT: a
+node shows iff it is `public`, declares no `permission`, or the user holds that name. A node's `icon`
+is a **Lucide icon** by sprite id (e.g. `i-cal` → lucide `calendar`); the available ids are
+`ICON_NAMES` in `src/ui/icons.ts`, and adding one means registering its lucide name there.
 
-**Gating a section header.** Putting the `permission` on the header is the simple form — the whole
-subtree disappears with it. When the children need *different* permissions, leave the header ungated
-and gate each child: `composeNav` drops a header whose children all filtered out. That second form
-only works while the header carries **no `href`** — give it one and it survives the filter as an
-ungated leaf, visible to everyone. The admin example uses it (three screens, six permissions).
+**Gating a section header.** A `permission` on the header takes the whole subtree with it. When the
+children need *different* permissions, leave the header ungated and gate each child — `composeNav`
+drops a header whose children all filtered out. That only works while the header carries **no
+`href`**: give it one and it survives as an ungated leaf, visible to everyone.
 
 #### Public pages & menu items
 
-A route or nav node may be marked **`public: true`** — reachable by **anyone, signed in or not**,
-and the menu item shows for everyone. This is the same as omitting `permission` (an ungated
-route/node is already open) but stated outright, so "public" is a **deliberate choice, not the
-accident of a forgotten gate**. `public` and `permission` are **mutually exclusive** — declaring
-both is contradictory and discovery refuses the plugin at boot.
+A route or nav node marked **`public: true`** is reachable by anyone and shows in everyone's menu.
+That is the same as omitting `permission`, but stated outright so public is a deliberate choice
+rather than a forgotten gate. The two are **mutually exclusive** — declaring both is refused at boot.
 
-A public page still renders in the native shell via `ctx.chrome`; for an anonymous visitor
-`ctx.user` is `null`, the shell shows a **Sign in** link (`chrome.signInHref`, returning to this page)
-in place of the profile/sign-out block, the gated **Dashboard** link is hidden, and `ctx.permissions` is
-empty (read a permission with `can(ctx, …)` to branch). The reference plugin's `/scheduling`
-**Overview** is a worked example: it's `public`, so the "Scheduling" menu header shows for everyone,
-while the actual shifts list stays behind `scheduling:read`.
+A public page still renders in the native shell; for an anonymous visitor `ctx.user` is `null`, the
+shell shows a **Sign in** link in place of the profile block, the gated **Dashboard** link is hidden,
+and `ctx.permissions` is empty (branch with `can(ctx, …)`). The reference plugin's `/scheduling`
+Overview is public while its shifts list stays behind `scheduling:read`.
 
-The gate passes iff the user's JWT `permissions` include that name. How permissions are granted, why their
-names are a shared global namespace, and the fine-grained per-row tier are all covered in
-[Users, groups & permissions](#users-groups--permissions).
-
-Declaring the ones you gate on in `permissions` is **optional but recommended**: it documents them,
-feeds conflict detection, and lets the one-command bootstrap seed them — the demo admin is
-granted every discovered plugin's declared permissions, so a dropped-in plugin works out of the box
-without editing host config.
+Declaring the permissions you gate on is **optional but recommended**: it documents them, feeds
+conflict detection, and lets the bootstrap seed them onto the demo admin, so a dropped-in plugin
+works without editing host config.
 
 ### Contract versioning
 
 Each manifest declares `apiVersion` — a **semver** string naming the host contract it was built
-against — and the host exposes the current `HOST_API_VERSION` (e.g. `"1.0.0"`). The host bumps
-**major** on a breaking manifest/handler change and **minor** on an additive one. At discovery
-the host parses both with `parseSemver` (the official semver core regex — strict: no ranges,
-`v` prefixes, or leading zeros) and applies provider/consumer semantics in `checkApiVersion`:
+against — against the host's `HOST_API_VERSION`. The host bumps **major** on a breaking
+manifest/handler change and **minor** on an additive one. At discovery it parses both with
+`parseSemver` (strict: no ranges, `v` prefixes, or leading zeros) and applies provider/consumer
+semantics in `checkApiVersion`:
 
 | Plugin `apiVersion` vs host | Result | Host action |
 | --- | --- | --- |
@@ -778,16 +602,13 @@ the host parses both with `parseSemver` (the official semver core regex — stri
 | different major | `refuse` | **abort boot** — incompatible contract |
 | missing / not a valid semver | `refuse` | **abort boot** — must be declared |
 
-The plugin pins one exact version (no ranges — in keeping with the project's pinning rules); the
-*host* supplies the caret-style compatibility. `parseSemver`/`checkApiVersion` are tight,
-dependency-free functions (the `semver` package's ranges/coercion/prerelease-precedence are more
-than the contract needs).
+The plugin pins one exact version (no ranges, per the project's pinning rules); the *host* supplies
+the caret-style compatibility.
 
 ### Conflict rules
 
-Plugins are independent folders, so the host detects collisions across all discovered plugins
-with `findConflicts` and resolves them **loudly — never last-write-wins**. `error` aborts boot;
-`warn` logs and continues.
+The host detects collisions across all discovered plugins with `findConflicts` and resolves them
+**loudly — never last-write-wins**. `error` aborts boot; `warn` logs and continues.
 
 | Kind | Level | Rule |
 | --- | --- | --- |
@@ -797,13 +618,10 @@ with `findConflicts` and resolves them **loudly — never last-write-wins**. `er
 | `home` / `dashboard` | error | More than one plugin declares `home` (or `dashboard`). Each landing page is a single slot, so only one may own it ([The landing pages](#the-landing-pages-home--dashboard)). |
 | `permission` | warn | A permission name is declared by more than one plugin. Sharing is legitimate; pick a more specific [`<resource>`](#naming-a-permission) if unintended. |
 
-There is **no separate `basePath` rule**: the mount path is the derived `/<id>`, so its
-uniqueness follows from the id check. `permission` is the one intentional overlap, so it warns
-rather than aborts; everything else is an error an author fixes before the host will start.
-
-Beyond cross-plugin conflicts, discovery also rejects **per-manifest shape errors** at boot: a
-non-array `nav`/`routes`/`permissions`, a non-function `home`/`dashboard`, or a route/nav node that
-sets both `public` and `permission` (mutually exclusive — [Public pages](#public-pages--menu-items)).
+Mount-path uniqueness needs no rule of its own — it follows from the id check. Discovery also
+rejects **per-manifest shape errors**: a non-array `nav`/`routes`/`permissions`, a non-function
+`home`/`dashboard`, a permission name that isn't [`<resource>:<action>`](#naming-a-permission), or a
+route/nav node setting both `public` and `permission`.
 
 ### Hooks
 
@@ -816,24 +634,20 @@ Optional, for reacting to system actions. A plugin's `hooks` may implement:
 | `onResponse(ctx, result)` | after the handler | observe/log; cannot change the response |
 
 Hooks run in **discovery order** (plugins sorted by id). `onRequest` fires on every request that
-reaches routing (static assets bypass it); the **first** hook to return a `RouteResult` wins and
-short-circuits — later `onRequest` hooks and the route handler are skipped, and that result renders
-against its own plugin's views. `onResponse` runs for a matched route after its handler, with the
-handler's result; its return value is ignored. Hooks run with no sandbox — a throwing hook fails
-loud (boot for `onBoot`, the request for the others). Keep them cheap; `onRequest` is on the hot
-path (the host skips the pipeline entirely when no plugin declares a hook). This surface is
-intentionally small and may grow additively within the major version.
+reaches routing (static assets bypass it); the **first** hook to return a `RouteResult` short-circuits
+— later hooks and the route handler are skipped, and that result renders against its own plugin's
+views. `onResponse` runs after a matched route's handler; its return value is ignored. Hooks are not
+sandboxed — a throwing hook fails loud (boot for `onBoot`, the request for the others). Keep them
+cheap: `onRequest` is on the hot path, though the host skips the pipeline entirely when no plugin
+declares a hook.
 
 ### Where plugins live (and how to mount them)
 
-The host scans **`/app/plugins/`** inside the `web` container — so "installing a plugin"
-means getting its folder there. There are two ways, depending on where the plugin's source
-lives:
+The host scans **`/app/plugins/`** inside the `web` container, so "installing a plugin" means
+getting its folder there.
 
-**1. In your clone (the default dev loop).** Create `plugins/<id>/` in the working tree.
-`docker compose up` already bind-mounts the whole tree (`compose.override.yml`:
-`.:/app`), so the folder is live in the container — restart to pick it up. This is the
-[Quick-start](#quick-start) path.
+**1. In your clone (the default dev loop).** Create `plugins/<id>/`; `docker compose up`
+bind-mounts the whole tree (`compose.override.yml`: `.:/app`), so a restart picks it up.
 
 **2. A plugin kept in its own repo, or added to a prebuilt image.** Bind-mount the plugin
 folder onto `/app/plugins/<id>` with a small compose override. Plugins are stateless, so
@@ -854,58 +668,34 @@ docker compose -f compose.yml -f compose.override.yml -f compose.plugins.yml up
 docker compose -f compose.yml -f compose.plugins.yml up -d
 ```
 
-A named volume or volume container works the same way (target `/app/plugins/<id>`), but a
-bind mount matches the edit-and-reload loop. For a **baked** production image, just keep
-the plugin in the build context and it's `COPY`'d in at build time — pinned and
-reproducible; mount a volume only to add plugins to an already-built image.
+A named volume works the same way (target `/app/plugins/<id>`). For a **baked** production image,
+keep the plugin in the build context and it is `COPY`'d in at build time.
 
-`#plugin-api` resolves against the *nearest* `package.json`, which at runtime must be the host's
-at `/app` — so the mounted `plugins/<id>/` folder must **not** contain a `package.json` of its own
-(one there becomes the plugin's scope, lacks the `#plugin-api` mapping, and boot fails loud). A
-plugin kept in its own repo therefore mounts as just its subfolder, with the repo's `package.json`
-kept outside the mount. To typecheck it against the barrel there, typecheck it mounted under the
-host tree, or vendor a type stub of the barrel and map `#plugin-api` to that (an `imports` target
-can't escape its own package scope, so it can't point at the host's file directly).
-
-> Discovery — scanning `plugins/`, importing each `plugin.ts` default export, and
-> validating it (id, `apiVersion`, conflicts) — runs at boot (`src/plugin-host/discovery.ts`); a bad
-> plugin stops startup with a precise message. The router (`src/plugin-host/router.ts`) then mounts
-> each route at `/<id>`, resolves `:name` params, runs the permission gate, and turns the
-> handler's `RouteResult` into the response; a `view` result renders
-> `plugins/<id>/views/<view>.ejs` (`src/plugin-host/view-resolver.ts`), which may `include()` the core
-> building-block partials. A plugin's `public/` assets are served at `/public/<id>/`
-> (`src/http/static.ts`). The mount mechanics above are how the files get into the container
-> either way.
+`#plugin-api` resolves against the *nearest* `package.json`, which at runtime must be the host's at
+`/app` — so a mounted `plugins/<id>/` must **not** contain a `package.json` of its own, or boot fails
+loud. A plugin kept in its own repo therefore mounts as just its subfolder, its `package.json` left
+outside the mount. To typecheck it there, typecheck it mounted under the host tree, or vendor a type
+stub of the barrel and map `#plugin-api` to that.
 
 ### Local dev & test story
 
-A plugin is a normal folder of TypeScript, so an author tests it the same way the core is tested
-— everything in Docker, no host tooling. The reference example (`examples/plugins/scheduling/`) is the
-worked example: thin handlers bound to an injectable upstream client, unit-tested in
-`shifts.test.ts` with a mocked `fetch` and a hand-built `ctx` (no host).
+A plugin is a normal folder of TypeScript, tested the same way the core is — everything in Docker.
+`examples/plugins/scheduling/` is the worked example: thin handlers bound to an injectable upstream
+client, unit-tested in `shifts.test.ts` with a mocked `fetch` and a hand-built `ctx`.
 
-1. **Unit-test handlers as pure functions.** Keep a handler thin: parse `ctx`, fetch upstream,
-   return a `RouteResult`. Test the data-shaping in isolation (mock `fetch`/upstream) with
-   `node --test`, exactly like `src/ui/dashboard.test.ts` tests the dashboard model. No host needed.
+1. **Unit-test handlers as pure functions** with `node --test` — no host needed.
 
    ```bash
    docker compose run --rm web npm test
    ```
 
-2. **Run one plugin against the host.** Get the folder into the container's `/app/plugins/<id>`
-   — either in your clone (the dev compose bind-mounts the tree) or by bind-mounting an external
-   folder ([Where plugins live](#where-plugins-live-and-how-to-mount-them)) — and `docker compose up`;
-   the host discovers it. For an isolated harness, the host exposes plugin injection
-   (`createApp({ plugins: [myPlugin] })`) so a test can mount a single manifest and assert its
-   routes, nav, and gating without the rest of the stack.
+2. **Run one plugin against the host.** Get the folder into `/app/plugins/<id>` and
+   `docker compose up`. For an isolated harness, `createApp({ plugins: [myPlugin] })` mounts a
+   single manifest so a test can assert its routes, nav and gating without the rest of the stack.
 
 3. **E2E the user-facing flow.** Per AGENTS.md §6, ship a side-effect-free Playwright test in
-   `e2e-tests/` for each plugin page/form so the suite stays `fullyParallel`, run against the live `web`
-   service with the plugin mounted. The reference's permission-gating is covered in `visual.spec.ts`;
-   its authenticated list/form happy-path is the full-E2E item (needs cross-host login infra).
-
-The validation an author hits is the same the host runs: bad `apiVersion` or a conflict
-([Conflict rules](#conflict-rules)) stops boot with a precise message naming the plugin(s) involved.
+   `e2e-tests/` for each plugin page/form, run against the live `web` service with the plugin
+   mounted.
 
 ## The menu system
 
@@ -929,58 +719,43 @@ The menu is **driven entirely by config** and assembled from two sources:
    export default defineMenu({ branding: { name: "Acme Ops" }, override: { hide: ["teams"] } });
    ```
 
-Every nav item may carry a `permission`; the rendered tree is **filtered per user** by
-reading the permissions in the session JWT (no per-request authz call — see
-[Auth, sessions & access](#auth-sessions--access)), so the menu only ever shows
-what that person can reach. An item (or a whole page) may instead be marked **`public:
-true`** to show it to **everyone, signed in or not** — the blessed, explicit way to expose
-a public page and its menu entry (an ungated item is already public; `public` just
-says so on purpose, and is mutually exclusive with `permission`). The markup is the
-recursive, zero-JS nav tree from the design foundation (header/leaf × clickable/static,
-counts, arbitrary depth). Branding (name, logo, default theme) renders in the app shell —
-the sidebar brand shows the configured logo (else a default mark), and the theme sets the
-theme-switch default.
+Every nav item may carry a `permission`; the rendered tree is **filtered per user** from the session
+JWT (no per-request authz call), so the menu only shows what that person can reach. An item may
+instead be **`public: true`** to show it to everyone — mutually exclusive with `permission`.
+Branding (name, logo, default theme) renders in the app shell.
 
-**One menu, one shell, everywhere.** There is a single menu (`src/ui/chrome.ts`
-`buildPluginChrome`), rendered by the same app shell on **every** page — the dashboard, plugin
-pages (the admin plugin's screens included), and the login / registration / recovery / front (`/`) pages.
-So it looks identical signed in or out; it just shows fewer items to an anonymous visitor
-(only `public` ones, plus a Sign-in link), filtered by the same per-user rule. The sidebar
-collapses to a burger on a narrow screen. A page that wants a focused, chrome-free layout
-(e.g. a print view) opts out with the shell's `menu: false`.
+**One menu, one shell, everywhere.** A single menu (`src/ui/chrome.ts` `buildPluginChrome`) renders
+in the same app shell on **every** page — dashboard, plugin pages, and the login / registration /
+recovery / front pages — so it looks identical signed in or out and just shows fewer items to an
+anonymous visitor. The sidebar collapses to a burger on a narrow screen; a page wanting a
+chrome-free layout opts out with the shell's `menu: false`.
 
 ## Building blocks
 
-Plainpages is a **component library, not a page generator** — you assemble pages from
-partials and helpers rather than declaring a schema and getting magic. The vocabulary is a
-set of reusable EJS partials + TS helpers, fully styled and zero-JS:
+Plainpages is a **component library, not a page generator** — reusable EJS partials + TS helpers,
+fully styled and zero-JS:
 
 - **Partials:** app shell, nav tree, filter bar, data table (sort / select / row actions),
   pagination, form fields, badges, menus, auth cards.
 - **Helpers:** `composeNav` (menu from config), `parseListQuery`
   (`?q=…&status=…&sort=…&page=…` → filter/sort/pagination), `paginate` (page math), and the
-  auth guards a handler calls to authorize (`src/auth/guards.ts`): `requireSession` (assert a
-  session — a `GuardError` the host turns into a redirect to sign in), `can(permission)` (a coarse
-  JWT-claim check, zero I/O), `check(relation, object)` (the one live Keto call, for
-  relationship rules).
+  auth guards (`src/auth/guards.ts`): `requireSession`, `can(permission)` (coarse JWT-claim check,
+  zero I/O), `check(relation, object)` (the one live Keto call).
 
 ## Interactivity: zero-JS spine
 
-The core and all building blocks **work with zero JavaScript** — theme switching and filtering
-are pure CSS + GET forms, and menus are the platform's own [popover
-API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API): a `<button popovertarget>`
-opens the panel and the browser dismisses it on a click outside or `Esc`; CSS anchor positioning
-places it. On a browser too old for the popover API the trigger is inert, so each panel falls back to
-flowing inline underneath it — cramped inside a table cell, but nothing is unreachable. That path
-is deliberately untested: no browser that supports popovers can render it. On the [low-end, low-bandwidth targets](#overview)
-we care about this is usually *faster*: a round-trip returning a small, pre-rendered HTML
-page beats a client-side runtime that must boot, fetch JSON, and re-render before anything
-shows. List state (`?q=…&status=…&sort=…&page=…`) lives **in the URL**, so a view is
-bookmarkable, shareable, and reproducible — the URL is the only state the UI keeps.
+The core and all building blocks **work with zero JavaScript** — theme switching and filtering are
+pure CSS + GET forms, and menus are the platform's own [popover
+API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API): a `<button popovertarget>` opens
+the panel, the browser dismisses it on an outside click or `Esc`, CSS anchor positioning places it.
+On a browser too old for popovers the trigger is inert and each panel falls back to flowing inline
+underneath it — cramped, but nothing is unreachable. List state
+(`?q=…&status=…&sort=…&page=…`) lives **in the URL**, so a view is bookmarkable and shareable; the
+URL is the only state the UI keeps.
 
-Plugins that genuinely need it — live dashboards, bulk actions, client-side validation —
-may **opt into progressive enhancement** (htmx, Alpine, or vanilla JS) on top of working
-server-rendered HTML. The baseline never depends on it.
+Plugins that genuinely need it — live dashboards, bulk actions, client-side validation — may **opt
+into progressive enhancement** (htmx, Alpine, vanilla JS) on top of working server-rendered HTML.
+The baseline never depends on it.
 
 ## Languages (i18n)
 
@@ -998,11 +773,10 @@ plugins/<id>/i18n/sv-SE.ts
 ```
 
 `locales/` is the operator's, mounted like `plugins/` and `config/` — a file there for a new tag
-**adds** a language, one for a tag the image already ships **replaces** that catalog wholesale (and
-is held to the same parity check, so a partial replacement fails the boot instead of leaving half
-the app in English). `locales/plugins/<id>/<tag>.ts` does the same for an installed plugin's words,
-checked against *that plugin's* `en-US` — so translating a vendored plugin, or fixing its wording,
-never means forking its folder:
+**adds** a language, one for a tag the image already ships **replaces** that catalog wholesale (held
+to the same parity check, so a partial replacement fails the boot). `locales/plugins/<id>/<tag>.ts`
+does the same for an installed plugin's words, checked against *that plugin's* `en-US`, so
+translating a vendored plugin never means forking its folder:
 
 ```yaml
 # compose.override.yml
@@ -1016,17 +790,13 @@ services:
 Matching is exact on a full tag — `?locale=sv-FI` with only `sv-SE` installed matches nothing and
 falls through to `Accept-Language` (and from there to `en-US`), rather than being served a
 neighbouring region — but a lone language (`sv`, as browsers send) resolves to the first regional
-catalog for it. There is **no locale cookie**: the URL is the only place a choice
-is stored, so a link is shareable and a page is what its address says it is. When the URL asked
-for a language, the host carries `?locale=` onto every link *it* renders (menu, sign-in, its own
-redirects) and `ctx.localeHref(href)` does the same for a plugin's links. The picker in the
-sidebar footer (and on the auth pages) lists every installed locale, each a plain link to the
-same page in that language; it renders whenever more than one locale is installed — **on every
-page**. After a POST the current URL may answer no GET at all (`POST /admin/users/:id/recovery`
-renders a page and has no GET sibling), so the host points the picker at the nearest page that does:
-this path when it answers GET, else the page the form was submitted from, else `/`. Switching
-language there therefore leaves the POST's own result behind — a re-rendered form's input, or a
-one-time code — which is the accepted cost of having the picker everywhere.
+catalog for it. There is **no locale cookie**: the URL is the only place a choice is stored, so a
+link is shareable and a page is what its address says it is. When the URL asked for a language, the
+host carries `?locale=` onto every link *it* renders and `ctx.localeHref(href)` does the same for a
+plugin's. The picker lists every installed locale and renders **on every page**. After a POST the
+current URL may answer no GET (`POST /admin/users/:id/recovery` has no GET sibling), so the host
+points the picker at this path when it answers GET, else the page the form was submitted from, else
+`/` — switching language there leaves that POST's own result behind.
 
 **Writing a catalog.** `en-US.ts` exports the object and its type; every other locale is written
 against that type, so a missing or misspelled key is a type error before the app ever boots. For a
@@ -1054,14 +824,12 @@ export default messages;
 ```
 
 At boot every catalog is checked against its set's `en-US`; a missing key, an unknown key, or a
-plural message that doesn't cover the categories its locale actually selects (`Intl.PluralRules`)
-**stops startup** with the full list — a half-translated deploy never reaches a visitor. A plugin
-may translate *fewer* locales than the host (its strings then render in `en-US` on that page), but
-never one the host doesn't have.
+plural message that doesn't cover the categories its locale selects (`Intl.PluralRules`) **stops
+startup** with the full list. A plugin may translate *fewer* locales than the host (its strings then
+render in `en-US`), never one the host doesn't have.
 
 **Using it.** `ctx.t(key, vars)` in a handler; in a view `t(...)` is already there, along with
-`locale`, `locales`, `localeHref()` and `dir` — the host merges them into every render, at any
-include depth:
+`locale`, `locales`, `localeHref()` and `dir` — merged into every render, at any include depth:
 
 ```ts
 // handler
@@ -1079,45 +847,41 @@ const EN: Translate = englishTranslator(enUS); // your catalog, then the host's
 <a href="<%= localeHref("/shop/new") %>"><%= t("shop.new") %></a>
 ```
 
-Three rules worth knowing:
+Rules worth knowing:
 
 - **An unknown key renders as itself.** That is what lets a nav label be either a catalog key or
-  plain text — `nav: [{ label: "shop.title" }]` is translated, `label: "Shop"` is not, and neither
-  breaks. The same holds for `config/menu.ts` branding and its `rename` overrides.
+  plain text — `label: "shop.title"` is translated, `label: "Shop"` is not, and neither breaks. Same
+  for `config/menu.ts` branding and its `rename` overrides.
 - **`t()` returns raw text; the view escapes it.** Use `<%= %>` as for any other value. A message
-  that deliberately carries markup is rendered with `<%- %>` — and its `{{vars}}` must then be
-  escaped at the call site, since nothing escapes them there (`pagination.ejs` is the worked example).
+  that deliberately carries markup uses `<%- %>` — and its `{{vars}}` must then be escaped at the
+  call site (`pagination.ejs` is the worked example).
 - **Dates and numbers are `Intl`'s job**, not the catalog's: `new Intl.DateTimeFormat(ctx.locale)`.
-- **The core building blocks carry the locale for you** — every href they render (menu, breadcrumbs,
-  pagination, sort headers, row actions, the auth card's links) goes through `localeHref`, and their
-  GET forms carry it as a hidden field, since a GET submit replaces the whole query string.
-  `ctx.localeHref` is for hrefs and form actions your own markup emits (a POST replaces the URL just
-  as a GET submit does), and `localeParam` (a view local: the tag, or null) for your own GET forms.
-  `locale` is reserved: `parseListQuery` never returns it as a filter. Responses carry
-  `Vary: Accept-Language`, so a cache in front of the app keys on the language too.
+- **The core building blocks carry the locale for you** — every href they render goes through
+  `localeHref`, and their GET forms carry it as a hidden field, since a GET submit replaces the whole
+  query string. `ctx.localeHref` is for hrefs and form actions your own markup emits (a POST replaces
+  the URL just as a GET submit does), and `localeParam` (a view local) for your own GET forms.
+  Responses carry `Vary: Accept-Language`.
 - **Reuse the core words.** Generic UI verbs live in the core catalog — `common.add/cancel/delete/
   edit/new/remove/save`, `filter.*`, `pagination.*`, `table.*` — and a plugin's lookup falls through
-  to them. Keep your catalog for your domain words, so N plugins don't re-translate "Cancel" N times.
-- **These view locals are reserved:** `t`, `locale`, `locales`, `localeHref`, `localeParam`,
-  `localeSwitch`, `dir`. They are merged after your `data`, so a key of yours with one of those names
-  is ignored rather than breaking the shell.
+  to them. Keep your catalog for your domain words.
+- **Reserved view locals:** `t`, `locale`, `locales`, `localeHref`, `localeParam`, `localeSwitch`,
+  `dir`. They are merged after your `data`, so a colliding key of yours is ignored rather than
+  breaking the shell. `locale` is likewise reserved in `parseListQuery`, never returned as a filter.
 
-**Kratos writes the auth flow's own text** (field labels, validation errors) and tags each string
-with a stable numeric id; a `kratos.<id>` key replaces it, and anything unmapped renders Kratos'
-English as-is. Field labels are keyed on the input name instead (`auth.field.password`), because
-Kratos' trait-label id is generic — the same id says "Email" on the login form and "First name" on
-a registration form. Operator- and developer-facing text (boot errors, logs) stays English.
+**Kratos writes the auth flow's own text** (field labels, validation errors), tagging each string
+with a stable numeric id; a `kratos.<id>` key replaces it and anything unmapped renders Kratos'
+English. Field labels are keyed on the input name instead (`auth.field.password`), because Kratos'
+trait-label id is generic — the same id says "Email" on login and "First name" on registration.
+Operator- and developer-facing text (boot errors, logs) stays English.
 
 ## Configuration
 
-Read from the environment once at boot (`src/config.ts`) and validated there — a bad URL,
-an out-of-range `PORT`, a non-boolean toggle, or a missing/throwaway enforced secret fails
-loud before the server starts. A clean clone needs **none** of these; every value defaults
-to the dev stack.
+Read from the environment once at boot (`src/config.ts`) and validated there — a bad URL, an
+out-of-range `PORT`, a non-boolean toggle, or a missing/throwaway enforced secret fails loud before
+the server starts. A clean clone needs **none** of these; every value defaults to the dev stack.
 
-The app is **environment-agnostic**: there is no `NODE_ENV`. Behaviour that used to flip on
-"production" is now its own explicit toggle, so a deployment turns on exactly what it wants.
-`compose.yml` (base) sets the hardened toggles; `compose.override.yml` (dev, auto-merged by
+The app is **environment-agnostic**: no `NODE_ENV`, every behaviour its own explicit toggle.
+`compose.yml` (base) sets the hardened ones; `compose.override.yml` (dev, auto-merged by
 `docker compose up`) turns them back off for live editing.
 
 | Var | Default | Notes |
@@ -1146,28 +910,22 @@ The app is **environment-agnostic**: there is no `NODE_ENV`. Behaviour that used
 ### Canonical host (one public URL)
 
 A site is often reachable at several URLs that resolve to the same place — `localhost` vs
-`127.0.0.1`, an apex vs `www.`, an IP vs a domain. That matters here because **cookies are
-host-scoped**: the themed login form POSTs to Kratos, and Kratos' CSRF cookie is set on the
-host the browser is on. Reach the app on one host but let the form post from another and
-that cookie is lost — Kratos rejects the flow and bounces to its error page. (The original
-symptom: open the banner's `http://localhost:3000`, sign in, land on
-`http://127.0.0.1:3000/error` "Page not found".)
+`127.0.0.1`, an apex vs `www.`. That matters because **cookies are host-scoped**: the themed login
+form POSTs to Kratos, and Kratos' CSRF cookie is set on the host the browser is on. Reach the app on
+one host but let the form post from another and that cookie is lost — Kratos rejects the flow and
+bounces to its error page.
 
-`APP_URL` is the **single source of truth** for the public host. Set it and the web app
-**redirects any off-host GET/HEAD visitor to it** (308, path + query preserved) *before* a
-flow starts, so the browser, the themed forms, and the cross-origin Kratos POST all share
-one cookie host. Static assets under `/public/` are served on any host (so health checks
-don't bounce). Everything else derives from the same `APP_URL`: the first-run banner, and —
-via compose — Kratos' browser-facing URLs (`compose.override.yml` maps `${APP_URL}` onto
-every `ui_url`, return URL, and `allowed_return_urls`). Set `APP_URL` and the whole stack
-follows; there is no second place to edit. A genuine Kratos flow error now renders a themed
-**`/error`** page (a path back to sign-in), not the catch-all 404.
+`APP_URL` is the **single source of truth** for the public host. Set it and the web app **redirects
+any off-host GET/HEAD visitor to it** (308, path + query preserved) *before* a flow starts, so the
+browser, the themed forms, and the cross-origin Kratos POST share one cookie host. Static assets
+under `/public/` are served on any host, so health checks don't bounce. Everything else derives from
+the same value: the first-run banner, and — via compose — Kratos' browser-facing URLs
+(`compose.override.yml` maps `${APP_URL}` onto every `ui_url`, return URL and
+`allowed_return_urls`). A genuine Kratos flow error renders the themed **`/error`** page.
 
-The redirect is an **explicit opt-in** (per the no-`NODE_ENV` rule): **unset ⇒ no
-redirect**, so a deploy that forgets `APP_URL` never bounces real users to a stale default.
-The clean clone still works with zero config because the bundled Kratos and the dev stack
-both default to `localhost` (the dev override sets `APP_URL=http://localhost:3000`); browse
-`localhost:3000` and login just works, and `127.0.0.1` is canonicalised onto it.
+The redirect is an **explicit opt-in**: **unset ⇒ no redirect**, so a deploy that forgets `APP_URL`
+never bounces real users to a stale default. A clean clone still works with zero config — the dev
+override sets `APP_URL=http://localhost:3000`, and `127.0.0.1` is canonicalised onto it.
 
 > **Behind a reverse proxy:** the proxy must pass the public `Host` through (or rewrite
 > Kratos' `base_url`/`ui_url`s to match what the browser sees). If it rewrites `Host` to an
@@ -1182,15 +940,12 @@ both default to `localhost` (the dev override sets `APP_URL=http://localhost:300
 
 ### What you must supply (the only manual prep)
 
-A clean clone needs **none** of the above — `docker compose up` brings up the whole stack
-with dev-throwaway secrets, an auto-generated signing key, and a seeded admin (see
-[Quick start](#quick-start)). What can't be auto-generated is **production-only** — none of it
-blocks a clean clone:
+A clean clone needs **none** of the above. What can't be auto-generated is **production-only**:
 
-1. **Production secrets** — every value below ships as a committed dev throwaway that works
-   out of the box and **must** be replaced before a deploy faces the internet. Only the first
-   is enforced: `REQUIRE_SECURE_SECRETS=true` refuses to boot on a missing or throwaway
-   `CSRF_SECRET` and **nothing else** — the rest fail silently, so treat this as a checklist.
+1. **Production secrets** — every value below ships as a committed dev throwaway and **must** be
+   replaced before a deploy faces the internet. Only the first is enforced:
+   `REQUIRE_SECURE_SECRETS=true` refuses to boot on a missing or throwaway `CSRF_SECRET` and
+   **nothing else** — the rest fail silently, so treat this as a checklist.
 
    | Secret | Where | Protects |
    | --- | --- | --- |
@@ -1207,40 +962,33 @@ blocks a clean clone:
    `kratos`/`hydra`, so add them to those services' `environment:` (or an `env_file:`) or they
    silently stay on the throwaways.
 
-2. **SSO provider client id/secret** — **optional**; password login works without them.
-   Supplying a provider's creds via env activates it; no creds ⇒ no SSO button (see
+2. **SSO provider client id/secret** — **optional**; password login works without them (see
    [Social sign-in (SSO)](#social-sign-in-sso)).
 
-Everything else is generated or seeded on first boot — Ory migrations, the dev signing key,
-the demo admin identity and its Keto permissions, the Keto OPL model — so there is nothing else to
-hand-configure.
+Everything else is generated or seeded on first boot — Ory migrations, the dev signing key, the demo
+admin identity and its Keto permissions, the Keto OPL model.
 
 ### Social sign-in (SSO)
 
-Off by default — a clean clone is password-only. Kratos activates a provider purely from
-the environment (no code, no rebuild): set `SELFSERVICE_METHODS_OIDC_ENABLED=true` and
-`SELFSERVICE_METHODS_OIDC_CONFIG_PROVIDERS` to a JSON array of providers (`google`,
-`microsoft`, …), each carrying its `client_id`/`client_secret` and referencing the committed
-claims mapper `ory/kratos/oidc/claims.jsonnet`. The themed sign-in/register pages derive one
-button per provider from the live flow's `oidc` nodes, so no creds ⇒ no provider ⇒ no
-button, and the whole SSO section disappears when none are configured — no code change to
-add or remove one. Open-source Kratos has **no native SAML** — front it with an OIDC bridge
-(Ory Polis) and register that bridge as a generic OIDC provider the same way.
+Off by default — a clean clone is password-only. Kratos activates a provider purely from the
+environment (no code, no rebuild): set `SELFSERVICE_METHODS_OIDC_ENABLED=true` and
+`SELFSERVICE_METHODS_OIDC_CONFIG_PROVIDERS` to a JSON array of providers, each carrying its
+`client_id`/`client_secret` and referencing the committed claims mapper
+`ory/kratos/oidc/claims.jsonnet`. The themed sign-in/register pages derive one button per provider
+from the live flow's `oidc` nodes, so no creds ⇒ no button, and the SSO section disappears entirely
+when none are configured. Open-source Kratos has **no native SAML** — front it with an OIDC bridge
+(Ory Polis) and register that bridge as a generic OIDC provider.
 
 ## Auth, sessions & access
 
-Identity comes from **Kratos**; the hot path stays I/O-free by carrying coarse authorization
-in a **locally-validated JWT**, and **Keto** is reserved for the rare fine-grained,
-must-be-fresh check.
+Identity comes from **Kratos**; the hot path stays I/O-free by carrying coarse authorization in a
+**locally-validated JWT**, and **Keto** is reserved for the rare fine-grained, must-be-fresh check.
 
 ### Login and the session JWT
 
-The themed sign-in / register / reset / SSO screens drive Kratos self-service flows. **SSO
-is optional and self-configuring:** each provider's button renders only when its credentials
-are present, and the whole SSO section disappears when none are configured — leaving plain
-password login. A developer never has to touch SSO to get started. On success, rather than
-keeping the opaque Kratos cookie and calling `whoami` on every request, the app **exchanges
-the session for a signed JWT once** via the Kratos **session tokenizer** (`whoami` with a
+The themed sign-in / register / reset / SSO screens drive Kratos self-service flows. On success,
+rather than keeping the opaque Kratos cookie and calling `whoami` on every request, the app
+**exchanges the session for a signed JWT once** via the Kratos **session tokenizer** (`whoami` with a
 `tokenize_as` template) and stores it as the session cookie.
 
 ```
@@ -1258,66 +1006,46 @@ the session for a signed JWT once** via the Kratos **session tokenizer** (`whoam
                                 filter menu · gate routes
 ```
 
-**Keto is the single source of truth for permissions.** Coarse permissions are Keto relations (e.g.
-`Permission:admin#granted@user:alice`); the admin screens write them *only* to Keto. But the
-tokenizer's claims mapper can read only the **identity**, not call Keto — so at login the
-app reads the permissions from Keto and refreshes a **derived projection**: a read-only copy
-written onto the identity's `metadata_public` for the tokenizer to see, which the template
-maps into the JWT `permissions` claim. (It must be `metadata_public`, not `metadata_admin`: the
-session Kratos hands the tokenizer carries only *public* metadata — and the user can already
-read these coarse permissions in their own JWT, so nothing is leaked.) That projection is a
-per-login cache, authoritative nowhere; nothing edits it by hand, and a stale one self-heals
-on the next login.
+**Keto is the single source of truth for permissions**, and the admin screens write them *only*
+there. But the tokenizer's claims mapper can read only the **identity**, not call Keto — so at login
+the app reads the permissions from Keto and refreshes a **derived projection**: a read-only copy on
+the identity's `metadata_public`, which the template maps into the JWT `permissions` claim. It must
+be `metadata_public`, not `metadata_admin` — the session Kratos hands the tokenizer carries only
+public metadata, and the user can already read these permissions in their own JWT. The projection is
+a per-login cache, authoritative nowhere; a stale one self-heals on the next login.
 
-A permission can be granted to a user directly or to a **group** the user belongs to; login
-resolves both (enumerate the defined permissions, ask Keto to resolve each membership), so the JWT
-`permissions` match what the admin **Effective access** view shows.
-
-Cost: **a handful of Keto reads + one identity refresh per login** — never per request. JWKS
-is cached, so even signature verification hits the network only on key rotation. The app
-stays stateless; "stay signed in" = re-mint the JWT on a short TTL, the one moment authz is
-recomputed from Keto.
+Login resolves both direct grants and group membership, so the JWT `permissions` match what the
+admin **Effective access** view shows. Cost: **a handful of Keto reads + one identity refresh per
+login**, never per request. JWKS is cached, so signature verification hits the network only on key
+rotation.
 
 #### Two trade-offs — both deliberate
 
-This design buys an I/O-free hot path that scales to **tens of thousands of concurrent
-users** on modest hardware. In return:
-
-- **Permission changes lag by up to one TTL (~10m).** Gating reads the JWT, not Keto, so a granted
-  or revoked permission only takes effect when the token is next minted (re-login or TTL refresh).
-  For an admin tool this is intentional — the alternative is a Keto call per request, which
-  we traded away. For instant revoke, turn on the optional
-  [revocation denylist](#instant-revoke-the-optional-denylist) — it closes the gap for
-  security-critical cases without putting Keto back on the hot path.
-- **Ory is on the critical path for sign-in.** If Kratos is down no one can log in; if it
-  stays down past the TTL, existing sessions can't refresh and the UI goes dark. That's the
-  direct consequence of being stateless and delegating identity — no local fallback, by
-  design. Run Ory with the availability you'd give any auth provider.
+- **Permission changes lag by up to one TTL (~10m).** Gating reads the JWT, not Keto, so a change
+  takes effect when the token is next minted. For instant revoke, turn on the optional
+  [revocation denylist](#instant-revoke-the-optional-denylist).
+- **Ory is on the critical path for sign-in.** If Kratos is down no one can log in; if it stays down
+  past the TTL, existing sessions can't refresh and the UI goes dark. Run Ory with the availability
+  you would give any auth provider.
 
 ### Instant revoke: the optional denylist
 
-Off by default; turn it on with `REVOCATION_DENYLIST=true` (`src/auth/denylist.ts`). For
-security-critical revoke (offboarding, a compromised account) the ~10m permission/session lag
-above is too long. When enabled, an admin **deactivating** or **deleting** a user, or
-**granting/revoking** a permission to a *user*, records that subject as revoked-now; the hot path
-then rejects every token for it minted **before** the revoke and forces a re-mint — which
-re-reads permissions from Keto, or clears a now-dead session. A fresh re-login (its JWT issued
-*after* the revoke) passes, so a permission downgrade lands immediately without locking the
-account.
+Off by default; turn it on with `REVOCATION_DENYLIST=true` (`src/auth/denylist.ts`). When enabled,
+an admin **deactivating** or **deleting** a user, or **granting/revoking** a permission to a *user*,
+records that subject as revoked-now; the hot path then rejects every token for it minted **before**
+the revoke and forces a re-mint — which re-reads permissions from Keto, or clears a dead session. A
+fresh re-login passes, so a downgrade lands immediately without locking the account.
 
-It's an in-memory, auto-evicting map — no database, like the JWKS cache, so it stays inside
-the stateless model. Entries self-evict after `REVOCATION_TTL_SEC` (default 900s ≥ the 10m
-token TTL + skew), by which point any pre-revoke token has expired anyway. The check is pure
-CPU — **Keto stays off the hot path**. Two deliberate bounds: it's instant on the **single
-instance** that handled the revoke (across replicas/restarts the guarantee falls back to the
-token TTL — back the denylist with a shared store for hard multi-instance instant-revoke),
-and a **group** membership change is transitive across many users, so it's left to lag —
-deactivate the user, or use a direct user-permission change, for an instant effect.
+It is an in-memory, auto-evicting map — no database, so it stays inside the stateless model — and
+the check is pure CPU, keeping Keto off the hot path. Entries self-evict after `REVOCATION_TTL_SEC`
+(default 900s ≥ the 10m token TTL + skew). Two bounds: it is instant only on the **single instance**
+that handled the revoke (elsewhere the guarantee falls back to the token TTL — back it with a shared
+store for hard multi-instance revoke), and a **group** membership change is transitive across many
+users, so it is left to lag.
 
 ### Three tiers of "may I?"
 
-[Users, groups & permissions](#users-groups--permissions) covers *what* the entities are; this is where each
-**kind** of rule belongs.
+Where each **kind** of rule belongs:
 
 ```
   coarse  (menu / route / feature)        → JWT claim     · in-process, zero I/O
@@ -1326,88 +1054,65 @@ deactivate the user, or use a direct user-permission change, for an instant effe
 ```
 
 - **Coarse** gates the menu and routes — read straight from the JWT.
-- **Attribute-based row rules** (ownership, tenant, status) live in the **upstream service**
-  that holds the data: it's the source of truth and the check is free.
-- **Relationship-based rules** (sharing, delegation, inherited/transitive access, or authz
-  that must mean the same thing across several services) go to **Keto** — that's what ReBAC
-  is for. Reserve it for those; don't pay its tuple-sync cost for rules a service can already
-  answer from its own data.
-
-The admin plugin's users / groups screens write authorization **only to Keto** — coarse
-permissions and fine-grained relationships alike.
+- **Attribute-based row rules** (ownership, tenant, status) live in the **upstream service** that
+  holds the data: it is the source of truth and the check is free.
+- **Relationship-based rules** (sharing, delegation, inherited access, or authz that must mean the
+  same thing across several services) go to **Keto**. Don't pay its tuple-sync cost for rules a
+  service can already answer from its own data.
 
 ### OAuth2 provider (Hydra)
 
-Only relevant when **other apps** authenticate *through* plainpages. The app implements
-Hydra's login & consent steps — authenticating the user via their Kratos session — and Hydra
-issues the access / refresh / id tokens those apps use. Nothing in the menu or first-party
-pages needs Hydra.
+Only relevant when **other apps** authenticate *through* plainpages: the app implements Hydra's
+login & consent steps against the user's Kratos session, and Hydra issues the tokens those apps use.
+Nothing in the menu or first-party pages needs Hydra.
 
-The **login challenge** is wired (`src/auth/oauth-login.ts` at `/oauth2/login`): Hydra hands the
-browser here, the app resolves it against the Kratos session and accepts (or bounces an
-unauthenticated user to the themed login, returning here once signed in). The **consent
-challenge** is wired too (`src/auth/oauth-consent.ts` at `/oauth2/consent`): a first-party client
-(its Hydra `metadata.first_party: true`) — or one Hydra already skipped — is auto-granted the
-requested scopes; any other client gets a themed consent screen (naming the signed-in
-account, with a sign-out escape) whose CSRF-guarded Allow/Deny accepts or rejects. id_token
-claims (email, name) come from the Kratos identity. RP-initiated **logout** is wired too
-(`/oauth2/logout`): Hydra hands the browser here, the app accepts the `logout_challenge` and
-resumes to Hydra's post-logout redirect — the first-party `POST /logout` still owns ending
-the Kratos session + our JWT cookie.
+- **`/oauth2/login`** (`src/auth/oauth-login.ts`) — resolve the challenge against the Kratos session
+  and accept, or bounce an unauthenticated user to the themed login and return here once signed in.
+- **`/oauth2/consent`** (`src/auth/oauth-consent.ts`) — a first-party client (Hydra
+  `metadata.first_party: true`), or one Hydra already skipped, is auto-granted its scopes; any other
+  gets a themed consent screen whose CSRF-guarded Allow/Deny accepts or rejects. id_token claims
+  come from the Kratos identity.
+- **`/oauth2/logout`** — accept the RP-initiated `logout_challenge` and resume to Hydra's
+  post-logout redirect. The first-party `POST /logout` still owns ending the Kratos session and our
+  JWT cookie.
 
-Those clients are registered from the admin plugin's **OAuth2 clients** screen (`/admin/clients`,
-`examples/plugins/admin/admin-clients.ts`, when that plugin is installed): register (Hydra shows the
-generated `client_secret` **once**, on the confirmation page — confidential clients), list, and
-delete. Confidential vs public (PKCE) and the first-party auto-consent flag are set at registration;
-writes go only to Hydra.
+Clients are registered from the admin plugin's **OAuth2 clients** screen (`/admin/clients`): Hydra
+shows the generated `client_secret` **once**, on the confirmation page. Confidential vs public
+(PKCE) and the first-party auto-consent flag are set at registration; writes go only to Hydra.
 
 ### Security model
 
-Everything above is *how* auth works. These are the few things the code won't tell you quickly,
-and that get a deployment wrong if you don't know them.
+**The private container network is the *only* thing guarding the Ory APIs.** Kratos admin (`4434`),
+Hydra admin (`4445`) and Keto write (`4467`) authenticate no one — reaching them *is* full identity
+and authorization control. Keto **read** (`4466`) cannot write but discloses the entire
+authorization graph, so treat it the same. `compose.yml` publishes none of the six Ory ports
+(guarded by `src/compose.test.ts`); dev publishes only the two a browser must reach.
 
-**The private container network is the *only* thing guarding the Ory APIs.** Kratos admin
-(`4434`), Hydra admin (`4445`) and Keto write (`4467`) authenticate no one — reaching them *is*
-full identity and authorization control. Keto **read** (`4466`) cannot write, but discloses the
-entire authorization graph, so treat it the same. `compose.yml` publishes none of the six Ory
-ports (guarded by `src/compose.test.ts`); dev publishes only the two a browser must reach. Never
-expose one, and never front one with a proxy that lacks its own auth.
-
-**The JWT is signed, not encrypted.** Claims are base64: a signed-in user can read their own
-`sub`, `email` and `permissions`. `HttpOnly` keeps page JavaScript out of the cookie, not the user.
-Never put anything in a claim you wouldn't show them.
+**The JWT is signed, not encrypted.** Claims are base64: a signed-in user can read their own `sub`,
+`email` and `permissions`. `HttpOnly` keeps page JavaScript out of the cookie, not the user.
 
 **The JWT's ~10m TTL is not the session lifetime.** The browser also holds Kratos'
-`plainpages_session` cookie (30 days, sliding), and *that* is what silently re-mints a lapsed
-JWT. So a stolen cookie jar is worth 30 days of re-mintable access, not ten minutes. Only our
-two cookies obey `SECURE_COOKIES`; the Kratos one takes its flags from Kratos' own config.
+`plainpages_session` cookie (30 days, sliding), and *that* is what silently re-mints a lapsed JWT —
+so a stolen cookie jar is worth 30 days of re-mintable access, not ten minutes. Only our two cookies
+obey `SECURE_COOKIES`; the Kratos one takes its flags from Kratos' own config.
 
-**Offboarding is not instant by default.** An expired JWT re-mints off that live Kratos session,
-re-reading permissions from Keto — so a revoked permission, or a deactivated identity, lands within one
-token TTL rather than immediately. With the
-[denylist](#instant-revoke-the-optional-denylist) on (it is off by default), both take effect at
-once, on the instance that handled the change.
+**Offboarding is not instant by default** — a revoked permission or deactivated identity lands
+within one token TTL, unless the [denylist](#instant-revoke-the-optional-denylist) is on.
 
-**Not guaranteed** — accepted, and stated where each mechanism is: permission changes
-[lag up to one token TTL and sign-in needs Ory up](#two-trade-offs--both-deliberate), and the
-denylist is [single-instance and skips group changes](#instant-revoke-the-optional-denylist).
 Hardening a real deploy is `REQUIRE_SECURE_SECRETS=true`, `SECURE_COOKIES=true`, and replacing
-**every** committed dev secret — see
-[what you must supply](#what-you-must-supply-the-only-manual-prep). `REQUIRE_SECURE_SECRETS`
-guards only `CSRF_SECRET`; nothing fails loud if you ship Ory's, Postgres' or the demo admin's
-throwaways.
+**every** committed dev secret ([what you must supply](#what-you-must-supply-the-only-manual-prep)).
+`REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`; nothing fails loud if you ship Ory's, Postgres'
+or the demo admin's throwaways.
 
 ## Email
 
-The only emails are the **recovery** and **verification** codes from Kratos' self-service
-flows, and **Kratos renders and sends them** (delegated, like the rest of identity — `web`
-never touches SMTP). Dev catches them in **mailpit** (<http://localhost:8025>); prod points
-Kratos at a real server via `COURIER_SMTP_CONNECTION_URI` (`courier.smtp` in
-`ory/kratos/kratos.yml`).
+The only emails are the **recovery** and **verification** codes from Kratos' self-service flows, and
+**Kratos renders and sends them** — `web` never touches SMTP. Dev catches them in **mailpit**
+(<http://localhost:8025>); prod points Kratos at a real server via `COURIER_SMTP_CONNECTION_URI`
+(`courier.smtp` in `ory/kratos/kratos.yml`).
 
 **Customizing the email content** is a built-in Kratos feature — no code here. Set
-`courier.template_override_path` to a mounted directory and drop Go templates in it, keyed by
-type:
+`courier.template_override_path` to a mounted directory and drop Go templates in it, keyed by type:
 
 ```
 <override-path>/recovery_code/valid/email.subject.gotmpl
@@ -1425,51 +1130,40 @@ docs for the full template-type list and the data each template receives.
 
 Plainpages runs as a small set of containers, orchestrated by Docker Compose:
 
-| Container      | Permission |
+| Container      | Does |
 | -------------- | ---- |
-| `web`          | The Node 24 + TypeScript app: server-rendered EJS, the plugin host, the building-block partials. Stays tiny. |
+| `web`          | The Node 24 + TypeScript app: server-rendered EJS, the plugin host, the building-block partials. |
 | `kratos`       | **Ory Kratos** — identity: login, registration, password reset, SSO, sessions. |
-| `keto`         | **Ory Keto** — permissions: the authorization decisions (`can user X do Y on Z?`). |
+| `keto`         | **Ory Keto** — the authorization decisions (`can user X do Y on Z?`). |
 | `hydra`        | **Ory Hydra** — OAuth2/OIDC provider, so other apps can log in *through* plainpages. |
 | `postgres`     | **Ory's** storage (Kratos/Keto/Hydra). |
 
-The `web` app is an Ory **relying party**: it never stores passwords. At login it turns
-the Kratos session into a short-lived, **locally-validated JWT** (the Kratos session
-tokenizer) carrying the user's coarse permissions — so every later request gates the menu and
-pages by **verifying the JWT in-process, with no per-request call to Ory**. Keto answers
-the rarer fine-grained checks; Hydra is used only when the app acts as an OAuth2 **login &
-consent provider** for other apps. It reaches the Ory services over their **REST APIs
-using Node's built-in `fetch`** — no SDK dependency. See
-[Auth, sessions & access](#auth-sessions--access).
+The `web` app is an Ory **relying party**: it never stores passwords. At login it turns the Kratos
+session into a short-lived, **locally-validated JWT** carrying the user's coarse permissions, so
+every later request gates the menu and pages **in-process, with no call to Ory**. Keto answers the
+rarer fine-grained checks; Hydra only when the app acts as an OAuth2 login & consent provider. All
+of it over their **REST APIs using Node's built-in `fetch`** — no SDK dependency.
 
-In **dev** the host-facing Ory ports are published — Kratos public `4433` (where the browser
-POSTs self-service flows) and Hydra public `4444`; **prod** (`docker compose -f compose.yml
-up`) keeps them internal.
+In **dev** the host-facing Ory ports are published — Kratos public `4433` and Hydra public `4444`;
+prod keeps them internal.
 
-So the `web` app is **stateless** and its npm footprint stays tiny — a small, pinned set
-of runtime deps (today **`ejs`** for templating, **`lucide-static`** for icons, and
-**`@larvit/log`** — itself zero-dependency — for structured/OTLP logging), grown only with
-justification and never a framework. Auth, sessions, SSO, and OAuth2 add *services*, not
-npm packages; data lives upstream.
+Runtime deps stay tiny and pinned: **`ejs`**, **`lucide-static`**, and **`@larvit/log`**. Auth,
+sessions, SSO and OAuth2 add *services*, not npm packages.
 
 ### Stateless
 
-Plainpages hold **no state of its own**. The only database in the stack
-is **Postgres** and is used by Ory (Kratos/Keto/Hydra); the `web` app never connects
-to it.
+Plainpages holds **no state of its own**. The only database in the stack is **Postgres**, used by
+Ory; the `web` app never connects to it.
 
-Plugins are encouraged to save state by **calling an upstream service** from its route handler
-— a REST API, an ERP, a plant historian, the customer's own backend — and renders the response with
-the building blocks; writes are forwarded the same way. The partials only need rows to
-render and don't care where they came from.
-
-This keeps `web` trivially scalable and crash-safe: any instance can serve any request,
-because the session lives in Kratos and the data lives upstream.
+A plugin reads and writes state by **calling an upstream service** from its route handler — a REST
+API, an ERP, a plant historian, the customer's own backend — and renders the response with the
+building blocks. That keeps `web` trivially scalable and crash-safe: any instance can serve any
+request, because the session lives in Kratos and the data lives upstream.
 
 ## Testing
 
-Type check and unit tests run off the Ory stack — units need no Postgres/Kratos/Keto, and
-`--no-deps` keeps `web` from dragging up its `depends_on` services:
+Type check and unit tests run off the Ory stack — `--no-deps` keeps `web` from dragging up its
+`depends_on` services:
 
 ```bash
 docker compose run --rm --no-deps web npm run typecheck   # strict tsc --noEmit
@@ -1478,89 +1172,37 @@ docker compose run --rm --no-deps web npm test            # node --test (units)
 
 ### End-to-end (Playwright)
 
-E2E runs in the official Playwright image (browsers preinstalled) against the live `web`
-service — no Node/browsers on the host. There are five suites:
+E2E runs in the official Playwright image (browsers preinstalled) against the live `web` service —
+no Node/browsers on the host. Five suites, each on its own stack:
 
-**Visual + design system** (`visual.spec.ts`, `language.spec.ts`) — Ory-free, so it stays fast. It
-screenshots the live pages and asserts the rendered design system — the app shell, theme switch,
-mobile off-canvas layout, icon sprite, CSRF-guarded sign-out, the public landing, the 404 page, and
-plugin permission-gating — the last exercised by bind-mounting the reference example
-(`examples/plugins/scheduling/`) onto `/app/plugins/scheduling`. `language.spec.ts` drives
-[language switching](#languages-i18n) in the browser: the picker, the choice surviving a click into
-the plugin's own pages, an `Accept-Language`-only visitor, and the fallback for an uninstalled locale.
+| Suite | Compose overlay | Covers |
+| --- | --- | --- |
+| `visual.spec.ts` + `language.spec.ts` | `e2e-tests/compose.visual.yml` | Ory-free: the rendered design system (app shell, theme switch, mobile off-canvas, icon sprite, CSRF-guarded sign-out, landing, 404), plugin permission-gating, and [language switching](#languages-i18n) |
+| `auth-refresh.spec.ts` | `e2e-tests/compose.auth.yml` | The real Ory stack with the session→JWT TTL cut to 8s: a lapsed JWT is silently re-minted from the live Kratos session, and once revoked the stale cookie is cleared |
+| `oauth-login.spec.ts` | `e2e-tests/compose.oauth.yml` | Another app logging in through us — register a client, start an authorization flow, `/oauth2/login` accept, `/oauth2/consent` Allow → authorization code |
+| `full-flow.spec.ts` | `e2e-tests/compose.full.yml` | The browser UI: password + mocked-SSO login, menu filtering by permission, admin users/groups/permissions CRUD, OAuth2-clients register → one-time secret → delete, a gated plugin page, logout |
+| `devstack-login.spec.ts` | `compose.override.yml` + `e2e-tests/compose.devstack.yml` | The plain `docker compose up` topology on the **host network**: sign-in works both from the banner's `localhost:3000` and from `127.0.0.1:3000` via the [canonical-host redirect](#canonical-host-one-public-url) |
 
 ```bash
-docker compose -f compose.yml -f e2e-tests/compose.visual.yml run --user "$(id -u):$(id -g)" --build --rm e2e   # run the suite
-docker compose -f compose.yml -f e2e-tests/compose.visual.yml down -v                 # tear down after
+docker compose -f compose.yml -f e2e-tests/compose.visual.yml run --user "$(id -u):$(id -g)" --build --rm e2e
+docker compose -f compose.yml -f e2e-tests/compose.visual.yml down -v
 ```
 
-**Auth — token timeout + refresh** (`auth-refresh.spec.ts`) — the full-stack counterpart: it
-boots the real Ory stack (Postgres + Kratos + Keto + bootstrap), shortens the session→JWT TTL
-to 8s (`ory/kratos/e2e.yml`) and sets `JWT_CLOCK_SKEW_SEC=0`, then logs in the seeded admin
-and proves the "stay signed in" hot path: the lapsed JWT is silently **re-minted** from the
-live Kratos session (permissions re-read from Keto), and once that session is revoked the stale
-cookie is **cleared**.
+Swap the overlay for another suite; `devstack` also needs `-f compose.override.yml`, host networking
+and the host ports `3000`/`4433` free. `--build` rebuilds the runner so spec edits are picked up (the
+image bakes in `e2e-tests/`). `full-flow` fronts web + Kratos on one origin through
+`e2e-tests/proxy.ts`, since the themed form posts straight to Kratos and cookies are host-scoped.
 
-```bash
-docker compose -f compose.yml -f e2e-tests/compose.auth.yml run --user "$(id -u):$(id -g)" --build --rm e2e   # run the suite
-docker compose -f compose.yml -f e2e-tests/compose.auth.yml down -v                 # tear down after
-```
-
-**OAuth2 login + consent** (`oauth-login.spec.ts`) — another app logs in *through* us: it
-boots the real stack (incl. Hydra), registers an OAuth2 client, starts an authorization flow,
-and drives the handlers end-to-end — `/oauth2/login` bounces an unauthenticated user to the
-themed login and **accepts** the challenge once a Kratos session exists; `/oauth2/consent`
-then shows the consent screen for the third-party client and **Allow** drives Hydra to issue
-the authorization code.
-
-```bash
-docker compose -f compose.yml -f e2e-tests/compose.oauth.yml run --user "$(id -u):$(id -g)" --build --rm e2e   # run the suite
-docker compose -f compose.yml -f e2e-tests/compose.oauth.yml down -v                 # tear down after
-```
-
-**Full browser flow** (`full-flow.spec.ts`) — the real Playwright UI against the live stack:
-the themed **password login** and a **mocked-SSO** login (an in-network mock OIDC provider,
-`e2e-tests/mock-oidc.ts`), **menu filtering by permission**, the **users/groups/permissions** admin CRUD, the
-**OAuth2-clients** admin screen (register → one-time secret → delete; Hydra is part of this stack
-for it), a permission-gated **plugin page**, and **logout**. Because the themed form posts straight to
-Kratos and cookies are host-scoped, a tiny same-origin gateway (`e2e-tests/proxy.ts`) fronts web +
-Kratos on one host (`ory/kratos/e2e-proxy.yml` points Kratos at it) — exactly as a production
-reverse proxy would.
-
-```bash
-docker compose -f compose.yml -f e2e-tests/compose.full.yml run --user "$(id -u):$(id -g)" --build --rm e2e   # run the suite
-docker compose -f compose.yml -f e2e-tests/compose.full.yml down -v                 # tear down after
-```
-
-`--build` rebuilds the runner so spec edits are always picked up (the image bakes in `e2e-tests/`).
-
-**Dev-stack login regression** (`devstack-login.spec.ts`) — drives the *plain* `docker
-compose up` topology (not the same-origin gateway above) with the runner on the **host
-network**, so the browser sees `http://localhost:3000` (web) and `http://127.0.0.1:4433`
-(Kratos public) exactly as a host browser does. It signs in the seeded admin from the URL the
-first-run banner advertises (`http://localhost:3000`) **and** from the wrong host
-(`http://127.0.0.1:3000`), asserting both reach the dashboard signed in — the latter via the
-[canonical-host redirect](#canonical-host-one-public-url). It guards against the regression
-where the advertised login URL dumps the user on the `/error` "Page not found" page; the
-proxied full-flow suite can't catch this (it fronts web + Kratos on one origin). Part of
-`ci.sh` — it needs host networking and the host ports `3000`/`4433` free (Linux).
-
-```bash
-docker compose -f compose.yml -f compose.override.yml -f e2e-tests/compose.devstack.yml run --user "$(id -u):$(id -g)" --build --rm e2e   # run it
-docker compose -f compose.yml -f compose.override.yml -f e2e-tests/compose.devstack.yml down -v                # tear down
-```
-
-Screenshots + an HTML report land in `e2e-tests/artifacts/` (git-ignored; `--user` above is what
-keeps them yours to delete — the runner writes them into your checkout). On **rootless** Docker drop
-that flag: container root is already you there, and a mapped uid cannot write. Every user-facing flow
-is covered end-to-end; tests are independent and run **fully in parallel** for speed
-([AGENTS.md](AGENTS.md)) — keep new tests side-effect-free so the suite stays fast.
+Screenshots + an HTML report land in `e2e-tests/artifacts/` (git-ignored). `--user` is what keeps
+them yours to delete — the runner writes into your checkout. On **rootless** Docker drop that flag:
+container root is already you there, and a mapped uid cannot write. Keep new tests
+side-effect-free so the suite stays `fullyParallel`.
 
 **Anything the browser logs fails the test.** Specs import `test` from
 `e2e-tests/console-guard.ts`, which watches every page a test opens — a console error or warning, or
-an uncaught exception, fails that test; a page that provokes one on purpose allows it explicitly with
-`allowConsole(/…/)`. The Ory-free suites run in **Chromium, Firefox and WebKit**, so each engine's
-console is read; the Ory-backed suites share one backend and stay on Chromium.
+an uncaught exception, fails that test; a page that provokes one on purpose allows it explicitly
+with `allowConsole(/…/)`. The Ory-free suites run in **Chromium, Firefox and WebKit**; the
+Ory-backed ones share one backend and stay on Chromium.
 
 ### The full gate (one command)
 
@@ -1599,109 +1241,72 @@ no repo files involved): direct pushes are blocked, changes land via PR only, th
 **fast-forward-only** — history stays linear and `main`'s head is the exact commit hash of
 the merged branch, which is why the branch's push-triggered status carries over.
 
-**Container images** — after a green gate, `ci.yml` builds the app image and pushes it to the
-Gitea container registry as `gitea.larvit.se/larvit/plainpages:<full commit hash>`. Because
-merges are fast-forward-only, the image for any `main` commit already exists — it was built
-and pushed by that exact commit's branch gate; nothing is rebuilt after merge (build once,
-promote by re-tagging). One-time setup: on an account with package write in the `larvit` org,
-create a Gitea access token with `read:package` + `write:package`, and store the account name
-as the Actions **variable** `DOCKER_REGISTRY_USER` and the token as the Actions **secret**
-`DOCKER_REGISTRY_TOKEN` (a `GITEA_` prefix is rejected — reserved, like `GITHUB_`). The
-package is **org-owned** (the image path starts with `larvit/`), so it lists under
-`larvit/-/packages`, not the repo — link it once to the repo's Packages tab:
-`POST /api/v1/packages/larvit/container/plainpages/-/link/plainpages`. Because
-this step runs
-inside the required gate, a missing/expired token (or registry outage) fails every branch's
-gate and blocks **all** merges until restored — set the secrets before this lands, and use a
-non-expiring token or track its expiry. Retention: hash tags accumulate one image per gated
-push, so the nightly `registry-cleanup.yml` prunes them
-([`registry-cleanup/cleanup.ts`](registry-cleanup/cleanup.ts) defines what survives).
-It reuses `DOCKER_REGISTRY_USER`/`DOCKER_REGISTRY_TOKEN` — no extra setup. Don't
-add a pattern-based org cleanup rule for this package (and remove it if one exists): its
-age/count heuristics can't see branch heads or release tags and would delete images the
-workflow protects.
+**Container images** — after a green gate, `ci.yml` builds the app image and pushes it as
+`gitea.larvit.se/larvit/plainpages:<full commit hash>`. Because merges are fast-forward-only, the
+image for any `main` commit already exists from that commit's branch gate — build once, promote by
+re-tagging. The build runs inside the required gate, so a missing/expired token or a registry outage
+blocks **all** merges until restored; use a non-expiring token or track its expiry. Hash tags
+accumulate one image per gated push, so nightly `registry-cleanup.yml` prunes them
+([`registry-cleanup/cleanup.ts`](registry-cleanup/cleanup.ts) defines what survives). Don't add a
+pattern-based org cleanup rule for this package — its age/count heuristics can't see branch heads or
+release tags and would delete images the workflow protects.
 
 **Releases** — pushing a semver git tag (`git tag v1.2.3 && git push origin v1.2.3`) runs
-`release.yml`, which pulls that commit's hash image from the registry and re-tags it as
-`1.2.3`, `1.2`, `1`, and `latest` — nothing is rebuilt, the released image is byte-identical
-to the gated one. It fails loud if no hash image exists: release tags must point at a commit
-that went through the gate (in practice, any `main` commit). The same four tags are then
-synced to [Docker Hub](https://hub.docker.com/r/larvit/plainpages) (`larvit/plainpages`) —
-releases only, no hash tags. One-time setup: create the public `larvit/plainpages`
-repository on Docker Hub, generate a read/write access token **scoped to that repository**
-(an organization access token, or a token on a dedicated single-purpose account — an
-account-wide PAT can push to every repo under the account), and store the account name as
-the Actions **variable** `DOCKERHUB_USER` and the token as the Actions **secret**
-`DOCKERHUB_TOKEN`. Until they exist, a release run fails at the Docker Hub step — after the
-Gitea re-tag has succeeded — so set them, then re-run the workflow. The Docker Hub
-repository **description** is maintained by hand: its source is
-[`README-dockerhub.md`](README-dockerhub.md) — paste it into the repository overview on
-Docker Hub when it changes.
+`release.yml`, which pulls that commit's hash image and re-tags it `1.2.3`, `1.2`, `1`, `latest`;
+nothing is rebuilt, so the released image is byte-identical to the gated one. It fails loud if no
+hash image exists — release tags must point at a commit that went through the gate. The same four
+tags sync to [Docker Hub](https://hub.docker.com/r/larvit/plainpages), releases only. The Docker Hub
+repository **description** is maintained by hand from [`README-dockerhub.md`](README-dockerhub.md).
 
-**GitHub mirror** — [github.com/larvit/plainpages](https://github.com/larvit/plainpages) is a
-read-only mirror; after every merge, `mirror.yml` force-pushes `main` and all tags there,
-overwriting any drift. Tags are pushed with `--prune`, so deleting one here deletes it there on
-the next mirror run — ref deletions don't trigger the workflow themselves — and the mirror can't
-go on advertising a version the source dropped; branches other than `main` are matched by no
-refspec and are left alone. The same sweep removes a tag *created* on GitHub, so cut releases on
-Gitea, never on the mirror — a GitHub Release made there loses its tag and does not come back.
-One-time setup: a dedicated
-GitHub machine account with write access to the GitHub repo (whose `main` must not block
-force-pushes, and which must carry no tag protection — that would reject the prune and fail every
-run), and a fine-grained PAT scoped to that repo (Contents: read & write), stored
-as the Gitea Actions secret `MIRROR_GITHUB_TOKEN` (repo Settings → Actions → Secrets; Gitea
-rejects secret names starting with `GITHUB_`/`GITEA_`). Trigger the workflow manually for
-the first sync — until the secret exists, the mirror job fails loud on each merge.
+**GitHub mirror** — [github.com/larvit/plainpages](https://github.com/larvit/plainpages) is
+read-only; after every merge `mirror.yml` force-pushes `main` and all tags, overwriting any drift.
+Tags go with `--prune`, so deleting one here deletes it there on the next run, and a tag *created* on
+GitHub is swept away — cut releases on Gitea, never on the mirror. Branches other than `main` match
+no refspec and are left alone.
 
-**Dependency updates** — `renovate.yml` runs [Renovate](https://docs.renovatebot.com)
-nightly (self-hosted, this repo only) against [`renovate.json`](renovate.json), opening PRs
-that bump npm deps (both `package.json`s), Docker base images (both Dockerfiles +
-`compose*.yml`), Gitea action versions, and the image tags pinned inside workflow `run:`
-steps (a custom regex manager, so nothing pinned drifts unmanaged). Version-locked sets move
-together in one PR — the Ory images (kratos/keto/hydra) and the Playwright runner + its
-browser image — and every bump keeps the existing **exact semver pin** exact, never widening
-to a range or adding a digest. Each PR
-runs through the normal gate on its `renovate/*` branch and, with `"automerge": true`,
-Renovate merges it once `CI / full-gate (push)` is green (rebasing stale branches so the
-fast-forward-only merge still holds) — routine bumps land untouched; only a red gate needs a
-human. One-time setup: reuse the shared `renovate@larvit.se` bot — give it write access to
-this repo and store its Gitea PAT as the Actions **secret** `RENOVATE_TOKEN`. Until it
-exists, the nightly job fails loud (and, like the other secrets, a `GITEA_`/`GITHUB_`
-prefix is rejected). Also store a **scopeless** (read-only) github.com PAT as the secret
-`RENOVATE_GITHUB_TOKEN` — the workflow hands it to Renovate as `GITHUB_COM_TOKEN`, so
-lookups of github.com-hosted deps (actions, Playwright, changelogs) run authenticated
-instead of tripping the anonymous 60-requests/hour limit.
+**Dependency updates** — `renovate.yml` runs [Renovate](https://docs.renovatebot.com) nightly
+(self-hosted, this repo only) against [`renovate.json`](renovate.json), bumping npm deps, Docker base
+images, Gitea action versions, and the image tags pinned inside workflow `run:` steps (a custom regex
+manager, so nothing pinned drifts unmanaged). Version-locked sets move together in one PR — the Ory
+images, and the Playwright runner + its browser image — and every bump keeps the **exact semver pin**
+exact. Each PR runs the normal gate on its `renovate/*` branch and automerges once
+`CI / full-gate (push)` is green; only a red gate needs a human.
 
-**Releases are paused.** Plainpages is pre-announcement: the repository carries **no tags**, and
+**Releases are paused.** Plainpages is pre-announcement: the repository carries **no tags**, so
 neither `release.yml` nor Docker Hub has a version to promote. Turn releasing back on by setting the
-Actions **variable** `AUTO_RELEASE` to `true` (that alone re-enables the job below), or cut a
-`vX.Y.Z` tag by hand **on `main`'s tip** — with nothing tagged, the nightly registry cleanup keeps
-only branch-head images, so an older commit's image is already gone and `release.yml` would fail
-loud with nothing to promote.
+Actions variable `AUTO_RELEASE` to `true`, or cut a `vX.Y.Z` tag by hand **on `main`'s tip** — with
+nothing tagged the nightly cleanup keeps only branch-head images, so an older commit's image is
+already gone and `release.yml` would fail loud.
 
-**Auto-release on dependency updates** — a second job in `renovate.yml` (`auto-release`, `needs:
-renovate`, gated on `AUTO_RELEASE` above) cuts **one** `vX.Y.Z` tag per run covering the
-renovate-bot commits merged to `main` since the last tag (it targets `origin/main`, and
-**skips** when the tip isn't a Renovate commit —
-a human owns that release — or when nothing new merged). Renovate stamps every commit with a
-`Release-Bump: <updateType>` trailer (`commitBody` in `renovate.json`), and
-[`auto-release/next-version.ts`](auto-release/next-version.ts) (unit-tested) turns the highest
-trailer on those commits into the next version — pre-1.0 it never auto-crosses into `1.0.0`,
-which stays a deliberate hand-cut tag. It's
-**tag-only** (no source commits): the tag hands off to `release.yml`, which promotes the
-already-built image, and is pushed with renovate-bot's PAT so `release.yml` actually fires (a tag
-pushed by the built-in Actions token wouldn't trigger it). The plugin-contract version
-(`HOST_API_VERSION`) is deliberately **not** touched here — it moves only when the plugin API
-itself changes, by hand.
+**Auto-release on dependency updates** — a second job in `renovate.yml` (`auto-release`, gated on
+`AUTO_RELEASE`) cuts **one** `vX.Y.Z` tag per run covering the renovate-bot commits merged to `main`
+since the last tag, and **skips** when the tip isn't a Renovate commit or nothing new merged.
+Renovate stamps each commit with a `Release-Bump: <updateType>` trailer and
+[`auto-release/next-version.ts`](auto-release/next-version.ts) turns the highest one into the next
+version — pre-1.0 it never auto-crosses into `1.0.0`. It is **tag-only**: the tag hands off to
+`release.yml`, and is pushed with renovate-bot's PAT so that workflow actually fires (a tag pushed by
+the built-in Actions token wouldn't trigger it). `HOST_API_VERSION` is never touched here.
 
-**One-time server setup** — register an
-[act_runner](https://docs.gitea.com/usage/actions/act-runner) in host mode with the label
-`docker-host` (config: `labels: ["docker-host:host"]`) on a machine with Docker Engine +
-Compose, git, and Node + github.com access (for `actions/checkout`). Runs must **never
-overlap** — the e2e stacks use fixed compose project names and the devstack suite uses host
-networking, and the workflows share the Docker daemon's registry login (`ci.yml` and
-`release.yml` each log in and log out) — so register exactly **one** `docker-host` runner,
-keep its capacity at 1, and keep host ports 3000/4433 free.
+### One-time CI setup
+
+| Actions var / secret | Value |
+| --- | --- |
+| `DOCKER_REGISTRY_USER` (var) + `DOCKER_REGISTRY_TOKEN` (secret) | A Gitea account with package write in the `larvit` org, and its access token with `read:package` + `write:package`. Reused by `registry-cleanup.yml`. |
+| `DOCKERHUB_USER` (var) + `DOCKERHUB_TOKEN` (secret) | The public `larvit/plainpages` Docker Hub repo, and a read/write token **scoped to that repository** (an org access token, or one on a dedicated account — an account-wide PAT can push to every repo under it). |
+| `MIRROR_GITHUB_TOKEN` (secret) | A fine-grained PAT (Contents: read & write) for a GitHub machine account with write access to the mirror. Its `main` must not block force-pushes and must carry no tag protection, which would reject the prune. |
+| `RENOVATE_TOKEN` (secret) | The shared `renovate@larvit.se` bot's Gitea PAT, with write access to this repo. |
+| `RENOVATE_GITHUB_TOKEN` (secret) | A **scopeless** (read-only) github.com PAT, so Renovate's lookups of github.com-hosted deps run authenticated instead of tripping the anonymous 60-req/hour limit. |
+
+Gitea rejects secret names prefixed `GITEA_`/`GITHUB_`. Each job fails loud until its secret exists.
+The container package is **org-owned**, so it lists under `larvit/-/packages` — link it to the repo's
+Packages tab once: `POST /api/v1/packages/larvit/container/plainpages/-/link/plainpages`.
+
+**The runner** — register one
+[act_runner](https://docs.gitea.com/usage/actions/act-runner) in host mode labelled `docker-host`
+(`labels: ["docker-host:host"]`) on a machine with Docker Engine + Compose, git, and Node +
+github.com access. Runs must **never overlap** — the e2e stacks use fixed compose project names, the
+devstack suite uses host networking, and the workflows share the Docker daemon's registry login — so
+keep exactly one runner at capacity 1, with host ports 3000/4433 free.
 
 ## Production & deployment
 
@@ -1709,46 +1314,37 @@ keep its capacity at 1, and keep host ports 3000/4433 free.
 docker compose -f compose.yml up --build -d   # base config only, no source mount
 ```
 
-`compose.yml` is the full prod stack — web + Postgres + the three Ory services
-(Kratos/Keto/Hydra, with migrations + the one-shot bootstrap) — and mounts no source. Secrets
-come from the environment (`CSRF_SECRET`, `POSTGRES_USER`/`POSTGRES_PASSWORD`); the base
-already sets `REQUIRE_SECURE_SECRETS=true`, so a missing or dev-throwaway `CSRF_SECRET` fails
-the boot rather than running insecure.
+`compose.yml` is the full prod stack — web + Postgres + the three Ory services (with migrations and
+the one-shot bootstrap) — and mounts no source. Secrets come from the environment; the base sets
+`REQUIRE_SECURE_SECRETS=true`, so a missing or dev-throwaway `CSRF_SECRET` fails the boot rather than
+running insecure. Before going live, supply the production secrets and any SSO credentials — the
+**only** manual prep ([What you must supply](#what-you-must-supply-the-only-manual-prep)).
 
-Before going live, supply the production secrets and any SSO credentials — the **only**
-manual prep ([What you must supply](#what-you-must-supply-the-only-manual-prep)); the rest is
-auto-generated.
+Every response carries security headers (`src/http/security-headers.ts`): a strict
+`Content-Security-Policy` (the core is zero-JS — `script-src 'self'`, no inline scripts),
+`X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY` + `frame-ancestors 'none'`,
+`Referrer-Policy`, and HSTS when `SECURE_COOKIES=true`. The CSP allows **same-origin** assets only,
+so a branding logo must live under `/public/` or be a `data:` URI; a plugin route can override any
+header per-response via `RouteResult.headers`.
 
-Every response carries security headers (`src/http/security-headers.ts`, set once per request): a
-strict `Content-Security-Policy` (the core is **zero-JS** — `script-src 'self'`, no inline
-scripts, so an injected `<script>` can't run), `X-Content-Type-Options: nosniff`,
-`X-Frame-Options: DENY` + `frame-ancestors 'none'`, `Referrer-Policy`, and — when
-`SECURE_COOKIES=true` (https) — HSTS. The CSP allows **same-origin** assets only, so a
-branding logo must live under `/public/` (or be a `data:` URI); a plugin route can override
-any header per-response via `RouteResult.headers` (e.g. to ship its own JS).
+A deep link reached while signed out — or after the session JWT lapses mid-task — bounces to the
+themed sign-in and returns to the **page that was requested** (`return_to`, validated host-relative
+by `localPath` in `src/http/safe-url.ts`, so a crafted value can't turn login completion into an open
+redirect). If Ory is unreachable on the sign-in path itself the user gets an honest **503**, distinct
+from the catch-all 500. The server drains in-flight requests on `SIGTERM`/`SIGINT`.
 
-A deep link reached while signed out — or after the ~10m session JWT lapses mid-task —
-bounces to the themed sign-in and, once authenticated, returns to the **page that was
-requested** (`return_to`, validated **host-relative** by `localPath` in `src/http/safe-url.ts`, so
-a crafted `?return_to=` can't turn login completion into an open redirect). If Ory is
-unreachable on the sign-in path itself, the user gets an honest **503** ("sign-in is
-temporarily unavailable"), distinct from the catch-all 500.
-
-The server drains in-flight requests on `SIGTERM`/`SIGINT` rather than cutting them
-mid-response, so container restarts are clean.
-
-The first-boot **bootstrap** is idempotent and runs on every `up` — it generates the JWT
-signing key if absent, creates the demo admin in Kratos, and grants it every discovered plugin's
-declared permission names in Keto (plus any `ADMIN_PERMISSIONS`), so permission checks (and any
-dropped-in plugin) resolve out of the box. The web app waits for Kratos + Keto to be healthy
-*and* the bootstrap to finish before starting. **Change the demo admin before production.**
+The first-boot **bootstrap** is idempotent and runs on every `up`: it generates the JWT signing key
+if absent, creates the demo admin in Kratos, and grants it every discovered plugin's declared
+permission names in Keto (plus any `ADMIN_PERMISSIONS`), so a dropped-in plugin resolves out of the
+box. The web app waits for Kratos + Keto healthy *and* the bootstrap to finish before starting.
+**Change the demo admin before production.**
 
 ## Upgrading
 
 **Re-copy your drop-in plugins.** Anything under `plugins/` is *your* copy — the host never updates
-it. When you pull a newer Plainpages, a plugin you copied from `examples/` is still the old one, and
-the host may have tightened a manifest rule since. Discovery fails loud at boot rather than running a
-plugin it can't honour, naming the plugin and the rule:
+it. A plugin copied from `examples/` is still the old one after you pull, and the host may have
+tightened a manifest rule since. Discovery fails loud at boot rather than running a plugin it can't
+honour, naming the plugin and the rule:
 
 ```bash
 rm -rf plugins/admin && cp -r examples/plugins/admin plugins/admin
@@ -1756,77 +1352,48 @@ docker compose up -d --build
 ```
 
 Do the same for any other folder you copied out of `examples/`. A plugin you wrote yourself needs the
-manifest change the error names — the same rules the shipped examples follow.
+manifest change the error names. Once [`HOST_API_VERSION`](#contract-versioning) starts moving a
+stale plugin will be refused by **version** instead; it is frozen at `1.0.0` until the first external
+plugin exists, so for now the error names the rule it tripped.
 
-Once [`HOST_API_VERSION`](#contract-versioning) starts moving, you won't have to read the rule to know
-why: a breaking manifest change bumps the major, and a plugin built against an older host is refused
-by **version**, naming both. The version is frozen at `1.0.0` until the first external plugin exists,
-so for now the error names the rule it tripped instead.
+Two paths in the checkout are load-bearing and must stay clear of root-owned leftovers:
+`node_modules/` must not exist (deps live at `/node_modules`, and anything at `/app/node_modules`
+silently shadows them), and `e2e-tests/artifacts/` must be writable by you or every E2E suite fails
+`EACCES`. Clearing the latter needs what `sudo` would do, which a dev box may lack:
 
-### Breaking changes
-
-- **Permission names must be `<resource>:<action>`** (2026-08-05). A manifest gating on — or
-  declaring — a bare word like `admin` now stops the boot. The bundled admin plugin was split into
-  `users:`/`groups:`/`oauth2-clients:` × `read`/`write`, so a copy taken before this needs re-copying.
-  `ADMIN_PERMISSIONS` is held to the same rule, but an unusable value there is dropped with a warning
-  rather than failing the boot. See [Naming a permission](#naming-a-permission).
-- **Deps moved to `/node_modules`, above `/app`** (2026-08-05). Run `rmdir node_modules` after
-  pulling (it is empty — no `sudo`) and `docker volume prune`. Keep that path clear: anything there
-  silently shadows the image's deps.
-- **`e2e-tests/artifacts/` is tracked, and the E2E runner writes as you** (2026-08-05). A root-owned
-  leftover from an earlier run blocks the checkout of its `.gitkeep` — git reports the failure but
-  still exits 0, leaving the file deleted in your working tree, where a later `git commit -a` would
-  commit that deletion — and every E2E suite then fails `EACCES`. Clear it before pulling; a root
-  container does what `sudo` would, which this needs and a dev box may lack:
-
-  ```bash
-  docker run --rm -v "$PWD/e2e-tests:/x" node:24.19.0-alpine3.24 rm -rf /x/artifacts
-  git checkout -- e2e-tests/artifacts/.gitkeep   # only if a pull already deleted it
-  ```
+```bash
+docker run --rm -v "$PWD/e2e-tests:/x" node:24.19.0-alpine3.24 rm -rf /x/artifacts
+git checkout -- e2e-tests/artifacts/.gitkeep   # only if a pull already deleted it
+```
 
 ## Observability
 
 Logging is **structured** and **OTLP-native**, on
-[`@larvit/log`](https://www.npmjs.com/package/@larvit/log) (zero-dependency). One app logger
-tags every line with `service.name` (`SERVICE_NAME`, default `plainpages` — brand your own
-deployment); each request is cloned into a short-lived **trace span**, made ambient for the
-whole handler (an `AsyncLocalStorage`), so logs and traces correlate. Three explicit toggles
-(no `NODE_ENV`):
+[`@larvit/log`](https://www.npmjs.com/package/@larvit/log). One app logger tags every line with
+`service.name`; each request is cloned into a short-lived **trace span**, made ambient for the whole
+handler (an `AsyncLocalStorage`), so logs and traces correlate. Three explicit toggles:
+`LOG_LEVEL`, `LOG_FORMAT` (`text` dev / `json` prod) and `SERVICE_NAME`.
 
-- `LOG_LEVEL` (default `info`) — `error` · `warn` · `info` · `verbose` · `debug` · `silly` ·
-  `none`.
-- `LOG_FORMAT` — `text` in dev (human-readable), `json` in prod (the base compose sets it)
-  for a log pipeline.
-- `SERVICE_NAME` — the `service.name` on every log and span.
+Every request emits one access line (`method`, `path` — the query is dropped, it can carry tokens —
+`status`, `ms`, `requestId`); login/logout, admin writes and missing-permission/CSRF rejections log
+at `info`/`warn`, the catch-all 500 and Ory-unreachable re-mint at `error`/`warn`. An inbound W3C
+`traceparent` is **adopted**, continuing a trace started upstream.
 
-Every request emits one access line (`method`, `path` — the query is dropped, it can carry
-tokens — `status`, `ms`, `requestId`); login/logout, admin writes (who-did-what), and
-missing-permission/CSRF rejections log at `info`/`warn`, and the catch-all 500 + the
-Ory-unreachable re-mint at `error`/`warn`. An inbound W3C `traceparent` is **adopted**, so a
-request continues a trace started by an upstream proxy/gateway.
+**Distributed tracing covers every outbound call.** Because the request logger is ambient, all
+outbound HTTP — the Ory clients and the JWKS fetch — runs through `tracedFetch`, becoming a client
+span under the request and carrying `traceparent` downstream. A plugin gets the same from
+`ctx.log.fetch(url)`, or by defaulting an upstream client to the exported `tracedFetch`.
 
-**Distributed tracing — every outbound call.** Because the request logger is ambient, **all**
-outbound HTTP — the Kratos/Keto/Hydra clients and the JWKS fetch — runs through it
-(`tracedFetch`), so each becomes a **client span** under the request and carries the
-`traceparent` downstream (Ory continues the same trace). A **plugin** does the same:
-`ctx.log` is its request logger and `ctx.log.fetch(url)` (or defaulting an upstream client to
-the exported `tracedFetch`, as the reference plugin does) traces its upstream calls too. The
-result is one trace per request spanning web → Ory/upstream.
-
-**OTLP export (off by default).** Point `OTLP_ENDPOINT` at an OpenTelemetry Collector's HTTP
-base URI (e.g. `http://otel-collector:4318`) and logs **and** spans also export there — feed
-Grafana Loki (logs) + Tempo (traces), or any OTLP backend. `OTLP_PROTOCOL` selects the wire
-format (`http/json` default, or `http/protobuf` for collectors that only accept protobuf).
-Export is fire-and-forget — it never blocks or fails a served request, and nothing exports
-when the endpoint is unset (zero cost). A collector outage is survivable but noisy: each
-request's failed export writes a line to stderr (it's retried per request, not queued), so
-run a local collector/agent you trust.
+**OTLP export (off by default).** Point `OTLP_ENDPOINT` at an OpenTelemetry Collector's HTTP base URI
+and logs **and** spans export there; `OTLP_PROTOCOL` selects `http/json` or `http/protobuf`. Export
+is fire-and-forget — it never blocks or fails a served request, and nothing exports when the endpoint
+is unset. A collector outage is survivable but noisy: each request's failed export writes a line to
+stderr, so run a local collector you trust.
 
 ## JWT signing key & rotation
 
 The session tokenizer signs each session→JWT with an **ES256** key at
-`ory/kratos/tokenizer/jwks.json`. The committed one is a **dev throwaway** (like the
-cookie/cipher secrets in `kratos.yml`) — a clean clone works; **never run it in
+`ory/kratos/tokenizer/jwks.json`. The committed one is a **dev throwaway** — **never run it in
 production**. Mint a fresh key with the bundled generator:
 
 ```bash
@@ -1842,15 +1409,14 @@ docker compose run --rm -T --no-deps web node src/auth/gen-jwks.ts > ory/kratos/
   is immutable and rotates only on a web redeploy. **For rotation, use `file://` on the web
   side** so it picks up new keys without a restart.
 
-**Why rotation is zero-downtime.** Kratos signs with the **first** key in the set and stamps
-its `kid` in each JWT header; web selects the verify key by that `kid`. So a set can hold the
-new key *and* the old one at once — tokens minted before and after the swap both verify.
+**Rotation is zero-downtime** because Kratos signs with the **first** key in the set and stamps its
+`kid` in each JWT header, while web selects the verify key by that `kid` — so a set can hold the new
+key *and* the old one at once, and tokens minted before and after the swap both verify.
 
 ### Scheduled rotation
 
-The token TTL is **10 min** (`kratos.yml` → `whoami.tokenizer.…ttl`); the wait window below
-is one TTL + clock skew, round up to **~12 min**. Run from the repo root (paths are
-container-relative; with the dev bind-mount they edit the real file).
+The token TTL is **10 min** (`kratos.yml` → `whoami.tokenizer.…ttl`); the wait window below is one
+TTL + clock skew, rounded up to **~12 min**. Run from the repo root.
 
 1. **Prepend a fresh key** (new key first, old key kept) — write via a temp file so the
    shell's `>` can't truncate the input before it's read:
@@ -1859,28 +1425,25 @@ container-relative; with the dev bind-mount they edit the real file).
      'node src/auth/gen-jwks.ts --prepend ory/kratos/tokenizer/jwks.json' > /tmp/jwks.json \
      && mv /tmp/jwks.json ory/kratos/tokenizer/jwks.json
    ```
-2. **Restart Kratos** so it signs with the new first key: `docker compose restart kratos`.
-   (web needs no restart — it hot-reloads the file. The hot path verifies JWTs locally, so a
-   brief Kratos blip only touches login/re-mint.)
-3. **Verify** new logins mint the new `kid` — decode the `plainpages_jwt` cookie's JWT
-   header, or watch web's logs for a `jwks reload on kid miss` debug line as old clients
-   present the new key.
+2. **Restart Kratos** so it signs with the new first key: `docker compose restart kratos`. web needs
+   no restart — it hot-reloads the file.
+3. **Verify** new logins mint the new `kid` — decode the `plainpages_jwt` cookie's JWT header, or
+   watch web's logs for a `jwks reload on kid miss` debug line.
 4. **Wait ~12 min**, then **prune** the superseded key:
    ```bash
    docker compose run --rm -T --no-deps web sh -c \
      'node src/auth/gen-jwks.ts --prune ory/kratos/tokenizer/jwks.json' > /tmp/jwks.json \
      && mv /tmp/jwks.json ory/kratos/tokenizer/jwks.json
    ```
-   No Kratos restart needed — it already signs with that key; this only drops a now-unused
-   verify key.
+   No Kratos restart needed — it already signs with that key; this only drops an unused verify key.
 
 **Rollback** (before the prune): the old key is still in the set, so revert step 1's file and
-`restart kratos` — in-flight tokens never broke.
+`restart kratos`.
 
 ### Emergency rotation (key compromise)
 
-Skip the overlap — you want every token signed with the leaked key to die now. **Replace**
-the set with a single fresh key (no `--prepend`):
+Skip the overlap — every token signed with the leaked key must die now. **Replace** the set with a
+single fresh key (no `--prepend`):
 
 ```bash
 docker compose run --rm -T --no-deps web node src/auth/gen-jwks.ts > ory/kratos/tokenizer/jwks.json
@@ -1895,83 +1458,39 @@ unnecessary here — the signature itself is already invalid.
 ## Project layout
 
 ```
-src/                  Node 24 + TypeScript app — strict tsc, no build step. *.test.ts sit beside their module.
-  server.ts           Entry point — starts the HTTP server (reads PORT, default 3000)
-  config.ts           Env loader — Ory endpoints, cookie/CSRF secrets, JWKS, port; validated at boot
-  logger.ts           createLogger()/requestLogger() + the ambient request log (runWithLog/currentLog) and tracedFetch: structured logger (service.name) + per-request trace span on @larvit/log; every outbound fetch joins the trace; OTLP export when OTLP_ENDPOINT set
-  *.test.ts (compose/kratos/keto/hydra/postgres)  Topology guards with no source counterpart — assert the compose dev/prod split + ordering and each Ory service's config (they validate ory/ + the compose files)
+src/                 The app — strict tsc, no build step. *.test.ts sit beside their module.
+  server.ts          Entry point; config.ts env loader; logger.ts structured log + trace span + tracedFetch
+  *.test.ts          Topology guards with no source counterpart (compose/kratos/keto/hydra/postgres/ci-gate)
+  http/              Request pipeline: app.ts (createApp), builtin-routes, context, body, cookie,
+                     static, safe-url (safeUrl + localPath), security-headers
+  auth/              Identity + the session-JWT hot path: jwt · jwt-middleware · jwks · gen-jwks (CLI) ·
+                     login · guards · csrf · denylist · flow-view · oauth-login · oauth-consent ·
+                     routes · bootstrap, and the Ory REST clients (kratos-public/admin, keto, hydra,
+                     fetch-timeout)
+  i18n/              catalog (parity rules) · locale (resolution) · translate · load · runtime ·
+                     english · view-locals · locales/ (the core en-US + sv-SE catalogs)
+  plugin-host/       plugin.ts (the contract) · plugin-api.ts (the `#plugin-api` barrel) · system.ts
+                     (ctx.system) · discovery · router · hooks · view-resolver
+  ui/                chrome (the one global menu) · shell-context · dashboard · nav (composeNav) ·
+                     menu-config (`#menu-config`) · icons (lucide sprite builder) · list-query · paginate
 
-  http/               Request pipeline + HTTP primitives
-    app.ts            createApp(): the request pipeline — security headers, static, canonical host, session verify/re-mint, CSRF, hooks, plugin routes, then the internal route table → RouteResult rendering
-    builtin-routes.ts The internal route table's contract: BuiltinRoute + the request's CSRF mint + matchBuiltinRoute() (exact path, GET answers HEAD)
-    context.ts        RequestContext handed to handlers + buildContext()
-    body.ts           readFormBody(): read + size-cap an x-www-form-urlencoded request body (CSRF gate + forms)
-    cookie.ts         Cookie parse + secure Set-Cookie build (session/CSRF cookies)
-    static.ts         Static file serving (path-traversal protection) + routePublic(): /public/<id>/ → a plugin's public/
-    safe-url.ts       safeUrl() (sanitise an untrusted href/src to relative-or-http(s), exposed to plugins) + localPath() (host-relative redirect-allowlist guard for return_to)
-    security-headers.ts  Response security headers set on every reply: strict CSP (zero-JS), nosniff, X-Frame-Options/frame-ancestors, Referrer-Policy, HSTS over https
-
-  auth/               Identity, the session-JWT hot path, guards, and the Ory REST clients
-    jwt.ts            JWS signature verify via node:crypto, no jose (decode + verify a compact JWS against one JWK)
-    jwt-middleware.ts resolveSession()/authenticate(): per-request session-JWT verify — key by kid → signature → exp/nbf/iss/aud (clock skew) → ctx.user/permissions; flags a lapsed token for re-mint
-    jwks.ts           JwksProvider — resolve the verify key by kid; createJwksProvider() picks by scheme: staticJwks (base64) or cachingJwks (file/http: TTL cache + rotation-on-miss reload)
-    gen-jwks.ts       generateJwks()/rotateJwks() + CLI (mint · --prepend · --prune): the ES256 session-tokenizer signing JWKS; see JWT signing key & rotation
-    login.ts          completeLogin()/remintSession(): login completion + TTL re-mint — permissions from Keto → metadata_public projection → tokenize → session JWT cookie
-    guards.ts         requireSession()/can()/check(): in-handler authorization — the imperative counterpart to the route permission gate; GuardError → 303 /login or 403; check() is the one live Keto "may I?" call
-    csrf.ts           CSRF for our own POST forms: signed double-submit token — issue/verify, cookie, request gate
-    denylist.ts       Optional instant-revoke denylist: in-memory, auto-evicting; hot path rejects a revoked subject's pre-revoke tokens (REVOCATION_DENYLIST)
-    flow-view.ts      buildFlowView(): Kratos self-service Flow → themed view model (fields, hidden csrf, buttons, tone-mapped messages) for views/auth.ejs
-    oauth-login.ts    resolveLoginChallenge(): authenticate a Hydra login challenge via the Kratos session → accept, or bounce to /login
-    oauth-consent.ts  resolveConsentChallenge()/acceptConsent()/rejectConsent(): auto-accept first-party, else show the consent screen → grant scopes
-    routes.ts         buildAuthRoutes(): the built-in auth/OAuth2 endpoints as named handlers on the internal route table — themed flow pages, /oauth2/* challenges, /auth/complete, POST /logout, /error; only what the wired clients support is registered
-    bootstrap.ts      One-command bootstrap: idempotent first-boot seed — JWKS-if-absent, demo admin in Kratos, admin permission in Keto
-    kratos-public.ts  createKratosPublic(): Kratos public-API fetch client — self-service flow init/get/submit, browser logout, whoami, session→JWT tokenize
-    kratos-admin.ts   createKratosAdmin(): Kratos admin-API fetch client — identity CRUD + surgical metadata_public update (login permission projection)
-    keto-client.ts    createKetoClient(): Keto fetch client — check / list / expand relations (read API) + write / delete tuples (write API)
-    hydra-admin.ts    createHydraAdmin(): Hydra admin-API fetch client — OAuth2 login + consent challenge get/accept/reject + OAuth2 client CRUD
-    fetch-timeout.ts  withTimeout(): bound every outbound Ory call — wrap the injected fetch so each request aborts after a deadline unless the caller passed its own signal; server.ts wires it into the Kratos/Keto/Hydra clients
-
-  i18n/               Translation: which language a request gets, and the words for it
-    catalog.ts        Catalog/Message types + checkCatalog(): the boot-time parity rules a locale is held to (keys, kinds, plural categories)
-    locale.ts         resolveLocale()/matchLocale()/parseAcceptLanguage() (?locale → Accept-Language → en-US) + localeHref(), textDirection(), localeLabel()
-    translate.ts      createTranslator(): key + vars → text — the catalog chain, {{var}} interpolation, Intl.PluralRules selection; an unknown key renders as itself
-    load.ts           loadI18n(): import src/i18n/locales/*.ts + plugins/<id>/i18n/*.ts and check every catalog against its en-US baseline — one boot-stopping error listing every problem
-    runtime.ts        createI18n(): the loaded catalogs per request — resolve the locale, hand out a memoised translator per locale+plugin
-    english.ts        The shipped en-US catalog as a ready translator + I18n, for paths the loaded catalogs aren't wired into (tests, ad-hoc contexts)
-    view-locals.ts    i18nLocals(): the t/locale/dir/localeSwitch block merged into every render (EJS passes it down into includes)
-    locales/          The core catalogs — en-US.ts (the baseline + its type) and sv-SE.ts
-
-  plugin-host/        Plugin discovery, routing, hooks, view resolution + the stable author barrel
-    plugin.ts         Plugin contract: manifest types, definePlugin(), version + conflict rules + fullPath()
-    plugin-api.ts     Stable plugin author barrel — the one module a plugin imports, as `#plugin-api` (definePlugin, ctx/result types, guards, body/CSRF/list-query/paginate helpers, and the ctx.system Ory client types)
-    system.ts         SystemCapabilities: the privileged ctx.system surface (Ory admin clients + instant-revoke) a system plugin uses; the host populates it from the wired clients, the admin plugin consumes it
-    discovery.ts      discoverPlugins(): scan plugins/, import + validate each plugin.ts default export, fail loud at boot
-    router.ts         matchRoute()/allowedMethods()/isAuthorized(): map method+path → plugin route, params, permission gate
-    hooks.ts          runBootHooks()/runRequestHooks()/runResponseHooks(): invoke a plugin's optional lifecycle hooks in discovery order; no sandbox (a throwing hook fails loud), skipped when no plugin declares one
-    view-resolver.ts  renderPluginView(): render plugins/<id>/views/<view>.ejs; plugin views can include() core partials
-
-  ui/                 Design-system view-models + menu/chrome — the building blocks pages render from
-    chrome.ts         buildPluginChrome(): the one global menu + brand/user/theme/csrf every page renders the shell from (unified across all pages) — exposed on ctx.chrome
-    shell-context.ts  buildShellContext(): brand/theme/user view-model for the dashboard shell (real signed-in user, no demo profile)
-    dashboard.ts      buildDashboardModel(): the gated "/dashboard" app home — a short instructional starter (replace it with a plugin `dashboard` handler); "/" is the public landing (a plugin `home` handler). Both render the one unified menu (ctx.chrome)
-    nav.ts            composeNav(): merge plugin nav fragments + central override, permission-filter → nav-tree model
-    menu-config.ts    loadMenuConfig()/defineMenu(): read config/menu.ts (central override + branding, imported as `#menu-config`), validated at boot
-    icons.ts          Used-icon registry + sprite builder from lucide-static (regenerates partials/icons.ejs)
-    list-query.ts     parseListQuery(): read a list URL → { q, filters, sort, page, pageSize }
-    paginate.ts       paginate(total,page,pageSize): page model (counts, row window, ellipsis sequence) for pagination.ejs
-
-views/               Core EJS templates, all in the one app shell: home (public "/" landing), index (instructional /dashboard), auth (themed Kratos flows), oauth-consent (OAuth2 consent), error (flow-error sink → /error), 403/404/500/503 (503 = Ory-unreachable on sign-in), partials/ (shell, nav tree, filter bar, data table, pagination, field, auth card, alert, landing/flow/consent bodies, menu/popover, theme switch, language picker, icon sprite). Domain screens live in plugins, not here — the admin plugin ships its own views/ (incl. its Users/Groups/Clients + permission-picker + confirm bodies)
-public/              Static assets under /public/ (css/styles.css + auth.css, favicon, robots.txt)
-config/              Drop-in mount point for the central menu override + branding (config/menu.ts). Ships empty (.gitkeep, git-ignored otherwise) — mount your own or copy the template from examples/config/; defaults apply when absent
-locales/             Drop-in mount point for extra (or replacement) language catalogs — a <locale>.ts here adds a language for the core, or replaces the shipped catalog for that tag wholesale; plugins/<id>/<locale>.ts does the same for an installed plugin. Ships empty (.gitkeep, git-ignored otherwise); see Languages
-ory/                 Ory service config (kratos/: identity schema, kratos.yml, oidc/ SSO claims mapper, tokenizer/ session→JWT claims mapper + dev signing JWKS; keto/: keto.yml + namespaces.keto.ts OPL — permission/group/resource; hydra/hydra.yml: OAuth2 issuer + login/consent URLs → /oauth2/*) + storage init (postgres/init/init.sql: one DB per service)
-plugins/             Drop-in plugin folders (scanned at /app/plugins; bind-mount or bake in). Ships empty (.gitkeep, git-ignored otherwise) — mount your own; the E2E suites bind-mount the example plugins onto /app/plugins/scheduling and /app/plugins/admin
-examples/            Copy-in reference material, mirroring the mount dirs: plugins/scheduling/ (the reference plugin — list/form over an upstream + permission-gated nav), plugins/admin/ (the system-admin plugin — Users/Groups/OAuth2-clients over Ory via ctx.system, permissions granted from the host's declared catalog), both copied into plugins/; and config/menu.ts (the menu/branding template copied into config/); shifts-upstream/ is the dev mock backend the scheduling plugin reads/writes (stand-in for your real service)
-e2e-tests/           Playwright E2E: visual.spec (design system, Ory-free) + auth-refresh.spec (token timeout/re-mint) + oauth-login.spec (OAuth2 login + consent) + full-flow.spec (browser UI: password/SSO login, menu-by-permission, admin CRUD, plugin page, logout) + devstack-login.spec (regression: login works from the banner's localhost URL and 127.0.0.1 is canonicalised, on the plain `docker compose up` topology); proxy.ts (same-origin gateway) + mock-oidc.ts (mock SSO provider) back full-flow. e2e-tests/Dockerfile + e2e-tests/compose.{visual,auth,oauth,full,devstack}.yml run them
-ci.sh                The full CI gate: typecheck → unit tests → every E2E suite, each on a fresh, always-torn-down stack (`bash ci.sh`)
-.gitea/workflows/    Gitea Actions: ci.yml — the full gate (ci.sh) on every branch push except main;
-                     mirror.yml — force-sync main + tags to the GitHub mirror; see CI/CD
-README-dockerhub.md  The Docker Hub repository description (docker.io/larvit/plainpages) — pasted into the Docker Hub overview by hand when it changes; see CI/CD
+views/               Core EJS in the one app shell: home, index, auth, oauth-consent, error, 403/404/500/503,
+                     and partials/ (shell, nav tree, filter bar, data table, pagination, field, auth card,
+                     alert, menu/popover, theme switch, language picker, icon sprite). Domain screens live
+                     in plugins.
+public/              Static assets served at /public/
+config/              Drop-in mount: the menu override + branding (config/menu.ts). Ships empty.
+locales/             Drop-in mount: extra or replacement catalogs. Ships empty. See Languages.
+plugins/             Drop-in mount: plugin folders, scanned at /app/plugins. Ships empty.
+ory/                 Ory config — kratos/ (identity schema, oidc claims mapper, tokenizer + dev JWKS),
+                     keto/ (namespaces.keto.ts OPL), hydra/, postgres/init/
+examples/            Copy-in reference mirroring the mount dirs: plugins/scheduling/, plugins/admin/,
+                     config/menu.ts, and shifts-upstream/ (the dev mock backend)
+e2e-tests/           Playwright specs + their Dockerfile and compose.{visual,auth,oauth,full,devstack}.yml;
+                     proxy.ts (same-origin gateway) and mock-oidc.ts back full-flow
+ci.sh                The full gate: typecheck → unit tests → every E2E suite on a fresh stack
+.gitea/workflows/    Gitea Actions — see CI/CD
+README-dockerhub.md  The Docker Hub repository description, pasted over by hand when it changes
 ```
 
 ## Extending the core
@@ -1988,13 +1507,10 @@ README-dockerhub.md  The Docker Hub repository description (docker.io/larvit/pla
   docker compose build
   ```
 
-All versions are pinned to **exact, human-readable semantic versions** (no ranges, no
-digests): npm deps via `.npmrc` (`save-exact=true`) + the committed lockfile (`npm ci`), and
-container images by tag in the `Dockerfile` / compose files (e.g. `node:24.16.0-alpine3.24`,
-pinned Ory and Postgres tags).
+All versions are pinned to **exact, human-readable semantic versions** (no ranges, no digests): npm
+deps via `.npmrc` (`save-exact=true`) + the committed lockfile (`npm ci`), and container images by
+tag in the `Dockerfile` / compose files.
 
-A plugin's `apiVersion` follows the same pin-it-by-hand spirit: write a **literal** semver — the
-host version the plugin was built against — and bump it by hand on rebuild. Never set it from the
-host's `HOST_API_VERSION` constant: that would make the plugin always equal the host, so the
-compatibility check ([Contract versioning](#contract-versioning)) could never fire and a breaking
-change would slip through silently.
+A plugin's `apiVersion` follows the same spirit: a **literal** semver, bumped by hand on rebuild.
+Never set it from the host's `HOST_API_VERSION` constant — the plugin would then always equal the
+host, so the [compatibility check](#contract-versioning) could never fire.
diff --git a/e2e-tests/devstack-login.spec.ts b/e2e-tests/devstack-login.spec.ts
index 820165c..f904024 100644
--- a/e2e-tests/devstack-login.spec.ts
+++ b/e2e-tests/devstack-login.spec.ts
@@ -1,20 +1,13 @@
 import { expect, test } from "./console-guard.ts";
 
-// Regression: the from-scratch dev experience the README/banner advertises must work. `docker compose
-// up`, open the printed login URL (http://localhost:3000), sign in as the seeded admin → you land on
-// the dashboard, signed in. Originally this dumped the user on http://127.0.0.1:3000/error?id=…
-// ("Page not found"): the banner printed `localhost` but kratos.yml hard-coded `127.0.0.1`, and a
-// host-scoped Kratos CSRF cookie can't cross `localhost`↔`127.0.0.1`, so the cross-host login POST
-// lost it and Kratos redirected to its error sink.
+// The from-scratch dev experience the banner advertises: `docker compose up`, open the printed
+// login URL, sign in as the seeded admin, land on the dashboard. A host-scoped Kratos CSRF cookie
+// cannot cross `localhost`↔`127.0.0.1`, so a cross-host login POST loses it and Kratos redirects to
+// its error sink; APP_URL canonicalises every off-host visitor onto one cookie host instead.
 //
-// The fix makes APP_URL the single source for the public host: the web app canonicalises every
-// off-host visitor onto it (so localhost / 127.0.0.1 / any alias funnel to one cookie host), Kratos'
-// browser URLs derive from it, and a real /error page replaces the 404.
-//
-// This is faithful to the user's environment: the runner uses the host network
-// (e2e-tests/compose.devstack.yml) against the plain `docker compose up` topology, so it sees
-// http://localhost:3000 (web) and http://127.0.0.1:4433 (Kratos public) exactly as a host browser
-// does. The proxied full-flow suite can't catch this regression — it fronts web + Kratos on one origin.
+// The runner is on the host network against the plain `docker compose up` topology, so it sees
+// http://localhost:3000 and http://127.0.0.1:4433 exactly as a host browser does. The proxied
+// full-flow suite cannot catch this — it fronts web + Kratos on one origin.
 const ADMIN_EMAIL = "admin@plainpages.local"; // seeded by bootstrap
 const ADMIN_PASSWORD = "admin";
 
diff --git a/e2e-tests/full-flow.spec.ts b/e2e-tests/full-flow.spec.ts
index d9b6d95..39db0c7 100644
--- a/e2e-tests/full-flow.spec.ts
+++ b/e2e-tests/full-flow.spec.ts
@@ -50,8 +50,8 @@ test.describe.serial("authenticated admin journey", () => {
   });
   test.afterAll(async () => { await page.context().close(); });
 
-  // The list screens rebuild their query from the list state (sort/page/filter), so they are where
-  // a chosen language used to get dropped — the core building blocks carry it now.
+  // The list screens rebuild their query from the list state (sort/page/filter), so they are where a
+  // chosen language is most easily dropped; the core building blocks carry it through.
   test("a sorted, paged admin list keeps the visitor's language", async () => {
     await page.goto("/admin/users?locale=sv-SE");
     await expect(page.locator("html")).toHaveAttribute("lang", "sv-SE");
diff --git a/e2e-tests/visual.spec.ts b/e2e-tests/visual.spec.ts
index 1048cae..bed2c0d 100644
--- a/e2e-tests/visual.spec.ts
+++ b/e2e-tests/visual.spec.ts
@@ -56,9 +56,8 @@ test("every icon <use> resolves to a defined <symbol> (no broken graphics)", asy
   expect(missing).toEqual([]);
 });
 
-// (The zero-JS URL-driven list — sortable headers, ?q search — is unit-tested per component
-// (list-query/data-table/filter-bar) and exercised live with real data by the full-flow E2E's admin
-// Users list. The mock-data dashboard that used to host it in this Ory-free suite is gone.)
+// The zero-JS URL-driven list — sortable headers, ?q search — is unit-tested per component and
+// exercised live by the full-flow E2E's admin Users list, so it has no Ory-free counterpart here.
 
 test("theme switch flips the palette with no JavaScript", async ({ page }) => {
   await page.goto("/dashboard");
diff --git a/examples/plugins/admin/README.md b/examples/plugins/admin/README.md
index c1fdf82..8266801 100644
--- a/examples/plugins/admin/README.md
+++ b/examples/plugins/admin/README.md
@@ -1,27 +1,22 @@
 # Admin — the system-administration plugin
 
-The Users / Groups / OAuth2-clients screens for running Plainpages itself. These used to be
-built into the core; they now ship as a **drop-in example plugin** so a fresh clone has no admin GUI
-until you opt in. Copy this folder into `plugins/` (it keeps the id and mount path `admin`, so the
-screens live at `/admin/*`) and restart:
+The Users / Groups / OAuth2-clients screens for running Plainpages itself, shipped as a **drop-in
+example plugin** so a fresh clone has no admin GUI until you opt in. Copy this folder into `plugins/`
+(it keeps the id and mount path `admin`, so the screens live at `/admin/*`) and restart:
 
 ```bash
 cp -r examples/plugins/admin plugins/admin
 docker compose up -d
 ```
 
-The bootstrap grants the seeded `admin@plainpages.local` every permission this plugin declares, so the
-section appears in the menu and the screens work immediately.
+The bootstrap grants the seeded `admin@plainpages.local` every permission this plugin declares, so
+the section appears in the menu and the screens work immediately. An older copy already in
+`plugins/` is yours — the host never updates it — so re-copy after a pull; a stale one stops the boot
+with a message naming it ([README → Upgrading](../../../README.md#upgrading)).
 
-> **Already have `plugins/admin` from an earlier version?** Re-copy it. Your copy is yours — the host
-> never updates it — and this plugin's permissions changed on 2026-08-05 (`admin` → `users:`/`groups:`/
-> `oauth2-clients:` × `read`/`write`). A stale copy stops the boot with a message naming it; see
-> [README → Upgrading](../../../README.md#upgrading).
-
-Every string it renders comes from its own catalogs (`i18n/en-US.ts`, `i18n/sv-SE.ts`) — the nav
-labels included, which are catalog keys in `admin-shared.ts`. Each pure view-model builder takes an
-optional `t`; the handlers pass `ctx.t`, and the default is the plugin's own English so a unit test
-reads in words rather than keys. (README → [Languages](../../../README.md#languages-i18n).)
+Every string it renders comes from its own catalogs (`i18n/en-US.ts`, `i18n/sv-SE.ts`), the nav
+labels included. Each pure view-model builder takes an optional `t` defaulting to the plugin's own
+English, so a unit test reads in words rather than keys.
 
 ## What it demonstrates — a *system* plugin
 
@@ -35,15 +30,14 @@ stack**, so they use the privileged **`ctx.system`** surface the host exposes to
 - **`ctx.system.revoke(sub)`** — the optional instant-revoke hook: a deactivate/delete or a
   user's permission change kills that subject's live tokens at once instead of waiting out the JWT TTL.
 
-`ctx.system` is populated only when the host wired those services (the dev stack wires Kratos + Keto,
-and Hydra when configured). Where a capability is absent the screen degrades to a themed 503 rather
-than crashing — see `admin-shared.ts`. Everything else is an ordinary plugin: folder-discovered,
-gated per route by its screen's `<resource>:<action>` permission, rendering the core building blocks
-in `views/`.
+`ctx.system` is populated only when the host wired those services. Where a capability is absent the
+screen degrades to a themed 503 rather than crashing. Everything else is an ordinary plugin:
+folder-discovered, gated per route by its screen's `<resource>:<action>` permission, rendering the
+core building blocks in `views/`.
 
-Each screen is its own resource — `users`, `groups`, `oauth2-clients` — and each splits into `:read`
-and `:write`, so a helpdesk account can be given `users:read` alone. The nav is filtered by the same
-permissions: holding none of the three hides the Admin section entirely.
+Each screen is its own resource — `users`, `groups`, `oauth2-clients` — split into `:read` and
+`:write`, so a helpdesk account can be given `users:read` alone. Holding none of the six hides the
+Admin section entirely.
 
 There is **no Permissions screen**. Permission names are declared in plugin code, not created in a
 GUI, so the host's catalog (`ctx.declaredPermissions`) is the fixed list — and holding one is a
diff --git a/examples/plugins/admin/admin-grants.test.ts b/examples/plugins/admin/admin-grants.test.ts
index 4965ef9..71cb978 100644
--- a/examples/plugins/admin/admin-grants.test.ts
+++ b/examples/plugins/admin/admin-grants.test.ts
@@ -46,9 +46,9 @@ test("buildPermissionPicker ticks what is held and carries each declaration's de
   assert.equal(picker.inheritedNote, undefined); // nothing is group-held here
 });
 
-// The failure this prevents: a permission held through a group used to render unticked, so the page
-// said "not held" about a grant that reaches the JWT — and unticking it wrote nothing, which read as
-// a successful revoke. Inherited rows are ticked, disabled, and never posted.
+// An inherited permission rendered unticked would say "not held" about a grant that reaches the JWT,
+// and unticking it writes nothing, reading as a successful revoke. So inherited rows are ticked,
+// disabled, and never posted.
 test("buildPermissionPicker distinguishes a direct grant from one inherited through a group", () => {
   const picker = buildPermissionPicker({ action: "/x", declared, direct: ["users:write"], effective: ["users:read", "users:write"] });
   assert.deepEqual(picker.choices.map((c) => [c.name, c.checked, c.inherited]), [
diff --git a/examples/plugins/admin/admin-shared.ts b/examples/plugins/admin/admin-shared.ts
index aeed4e1..839651e 100644
--- a/examples/plugins/admin/admin-shared.ts
+++ b/examples/plugins/admin/admin-shared.ts
@@ -1,14 +1,12 @@
-// Shared plumbing for the admin example plugin: the section nav fragment, the admin-only gate, the
-// CSRF-guarded form reader, the destructive-confirm model builder, and small RouteResult helpers
-// (themed not-found / capability-unavailable). Ported from the former built-in admin screens;
-// everything imports the host only through the #plugin-api barrel.
+// Shared plumbing for the admin example plugin: the section nav fragment, the screen gate, the
+// CSRF-guarded form reader, the destructive-confirm model builder, and small RouteResult helpers.
+// Everything imports the host only through the #plugin-api barrel.
 
 import { can, CSRF_FIELD, englishTranslator, GuardError, type NavNode, readFormBody, type RequestContext, requireSession, type RouteResult, type Translate, type User } from "#plugin-api";
 import enUS from "./i18n/en-US.ts";
 
-// This plugin's English (its catalog, then the host's — the screens reuse core words like Cancel and
-// Search), for a view model built outside a request: its unit tests. At runtime the handlers pass
-// ctx.t, which reads this catalog in the visitor's locale first, then the host's.
+// This plugin's English — its catalog, then the host's — for a view model built outside a request,
+// i.e. its unit tests. At runtime the handlers pass ctx.t instead.
 export const ADMIN_EN: Translate = englishTranslator(enUS);
 
 export const ADMIN_USERS_BASE = "/admin/users";
@@ -28,11 +26,9 @@ export function permissionName(resource: AdminResource, action: AdminAction): st
   return `${resource}:${action}`;
 }
 
-// This plugin's mapping from method to action: every screen reads on GET/HEAD and mutates on POST.
-// The manifest's route table and the in-handler guard both go through it rather than each spelling
-// the permission out, so they cannot drift into gating on different names. Deliberately local — as
-// a general mechanism it would make authorization a function of the transport verb, and a route
-// table should answer "what does this need?" on its own (AGENTS.md).
+// Every screen reads on GET/HEAD and mutates on POST. The route table and the in-handler guard both
+// go through this rather than each spelling the permission out, so they cannot drift. Deliberately
+// local: generalised, it would make authorization a function of the transport verb (AGENTS.md).
 export function actionForMethod(method: string): AdminAction {
   const verb = method.toUpperCase();
   return verb === "GET" || verb === "HEAD" ? "read" : "write";
@@ -54,13 +50,10 @@ export const ADMIN_NAV: NavNode = {
 };
 
 // The screen gate: a signed-in user holding this request's `<resource>:<action>`. Each route already
-// declares the same permission, so the host enforces it before the handler runs; this is
-// defence-in-depth and what a direct unit test relies on. Returns the (non-null) user for the
-// handler to thread on. GuardError → /login or 403.
-// `action` defaults to the method's, and is passed explicitly by a *write-intent GET* — a create form
-// or a delete-confirm page, whose only purpose is to start a write. Those refuse a reader honestly
-// instead of rendering a form whose submit would 403; the route table declares the same override, so
-// the two still cannot disagree.
+// declares the same permission, so this is defence-in-depth and what a direct unit test relies on.
+// `action` defaults to the method's, and is passed explicitly by a *write-intent GET* — a create
+// form or a delete-confirm page — which refuses a reader rather than rendering a form whose submit
+// would 403. The route table declares the same override, so the two cannot disagree.
 export function requirePermission(ctx: RequestContext, resource: AdminResource, action?: AdminAction): User {
   const user = requireSession(ctx); // anonymous → GuardError → /login (return_to kept)
   const permission = permissionName(resource, action ?? actionForMethod(ctx.req.method ?? "GET"));
diff --git a/examples/plugins/admin/admin-users.ts b/examples/plugins/admin/admin-users.ts
index 14982b5..d101759 100644
--- a/examples/plugins/admin/admin-users.ts
+++ b/examples/plugins/admin/admin-users.ts
@@ -1,8 +1,7 @@
 // Users admin screen: list Kratos identities (filter/sort/paginate) +
-// create/edit/deactivate/delete/trigger-recovery. Writes go only to Kratos via the admin client
-// (README "stateless"). Pure builders turn identities + the request URL into building-block view
-// models; below them are thin per-route handlers (keyed on ctx.params) over a shared `withUser` gate
-// — admin-only, CSRF-guarded, each returning a RouteResult (a view, or a redirect after a write — PRG).
+// create/edit/deactivate/delete/trigger-recovery. Pure builders turn identities + the request URL
+// into building-block view models; below them are thin per-route handlers keyed on ctx.params, over
+// a shared `withUser` gate.
 
 import { can, type Identity, type KetoClient, type KratosAdmin, KratosError, paginate, parseListQuery, type RecoveryCode, type RequestContext, type RouteHandler, type RouteResult, type Translate, type User } from "#plugin-api";
 import { applyGrants, buildPermissionPicker, effectivePermissions, grantDiff, heldPermissions, type PermissionPicker, PERMISSIONS_FIELD, userSubject } from "./admin-grants.ts";
diff --git a/examples/plugins/admin/plugin.ts b/examples/plugins/admin/plugin.ts
index c50120b..d73abd3 100644
--- a/examples/plugins/admin/plugin.ts
+++ b/examples/plugins/admin/plugin.ts
@@ -1,10 +1,8 @@
-// Admin example plugin: the Users / Groups / OAuth2-clients screens for running the system.
-// These used to ship inside the core; they were extracted here so a fresh clone has no built-in admin
-// GUI. Copy this folder to plugins/admin (then restart) to enable it — see README → Quick start.
+// Admin example plugin: the Users / Groups / OAuth2-clients screens for running the system. Copy
+// this folder to plugins/admin (then restart) to enable it — see README → Quick start.
 //
-// It is a *system* plugin: its handlers reach the host's Ory admin clients (Kratos/Keto/Hydra) and the
-// instant-revoke hook via ctx.system, which the host populates when those services are wired (the dev
-// stack wires all of them). Where a capability is absent the screen degrades to a themed 503.
+// It is a *system* plugin: its handlers reach the host's Ory admin clients and the instant-revoke
+// hook via ctx.system. Where a capability is absent the screen degrades to a themed 503.
 
 import { definePlugin, type HttpMethod, type Route, type RouteHandler } from "#plugin-api";
 import { clientsCreate, clientsDeleteConfirm, clientsDelete, clientsDetail, clientsList, clientsNewForm } from "./admin-clients.ts";
diff --git a/src/auth/bootstrap.test.ts b/src/auth/bootstrap.test.ts
index f9cd395..194c207 100644
--- a/src/auth/bootstrap.test.ts
+++ b/src/auth/bootstrap.test.ts
@@ -42,10 +42,9 @@ test("seedPermissions unions ADMIN_PERMISSIONS (empty by default) with the disco
   assert.deepEqual(names(",, ", [" scheduling:read ", ""]), ["scheduling:read"]); // blanks dropped, names trimmed (both sides)
 });
 
-// The regression this pins: an earlier revision *threw* here, so `ADMIN_PERMISSIONS=admin` — this
-// setting's own default until 2026-08-05 — exited bootstrap 1, and bootstrap gates `web`, so a
-// leftover variable bricked the whole stack on upgrade. Bootstrap must never refuse to start over
-// operator env: drop what it can't use, report it, seed the rest.
+// Bootstrap gates `web`, so it must never refuse to start over operator env — a leftover
+// ADMIN_PERMISSIONS would otherwise brick the whole stack. Drop what it can't use, report it, seed
+// the rest.
 test("seedPermissions drops an ADMIN_PERMISSIONS name that isn't <resource>:<action>, and never throws", () => {
   const legacy = seedPermissions("admin", ["users:read"]);
   assert.deepEqual(legacy, { ignored: ["admin"], permissions: ["users:read"] });
diff --git a/src/auth/bootstrap.ts b/src/auth/bootstrap.ts
index 95e850f..c7088bd 100644
--- a/src/auth/bootstrap.ts
+++ b/src/auth/bootstrap.ts
@@ -29,19 +29,14 @@ export function permissionTuple(userId: string, permission: string) {
   return { namespace: "Permission", object: permission, relation: "granted", subject_id: `user:${userId}` };
 }
 
-// The permissions to grant the demo admin = the configured base (ADMIN_PERMISSIONS, empty by default)
-// unioned with every discovered plugin's declared permission names (a route/nav `permission` is a
-// coarse permission — granted as a Keto `Permission:<name>#granted` tuple). So the host names no plugin, yet a
-// dropped-in plugin's permissions are seeded out of the box. Deduped, order-stable, blanks dropped.
-// The base is empty because permissions are `<resource>:<action>` and every one of them is owned by
-// the plugin that gates on it — a host-invented default would gate nothing.
+// ADMIN_PERMISSIONS (empty by default) unioned with every discovered plugin's declared names, so
+// the host names no plugin yet a dropped-in one is seeded out of the box.
+//
 // ADMIN_PERMISSIONS is the one place an operator names a permission by hand, so it is held to the
-// same `<resource>:<action>` rule discovery applies to a manifest — but *dropped with a warning*,
-// never fatal. Fail-loud belongs at the manifest boundary, where a developer authored the mistake
-// and can fix it; this is operator env, bootstrap gates `web`, and the whole stack must not refuse
-// to start over a stale variable. `admin` was this setting's own default before 2026-08-05, so a
-// value that bricks the boot is the *expected* leftover on any upgrade. The name it would have
-// written gates nothing anyway. Declared names already passed the check at discovery.
+// same `<resource>:<action>` rule as a manifest — but *dropped with a warning*, never fatal:
+// fail-loud belongs at the manifest boundary where a developer authored the mistake, whereas this
+// is operator env and bootstrap gates `web`, so the whole stack must not refuse to start over a
+// stale variable. The name it would have written gates nothing anyway.
 export function seedPermissions(adminPermissionsEnv: string | undefined, declaredNames: string[]): { ignored: string[]; permissions: string[] } {
   const clean = (xs: string[]): string[] => xs.map((r) => r.trim()).filter(Boolean);
   const configured = clean((adminPermissionsEnv ?? "").split(","));
diff --git a/src/auth/denylist.ts b/src/auth/denylist.ts
index b1accf7..dc43de5 100644
--- a/src/auth/denylist.ts
+++ b/src/auth/denylist.ts
@@ -1,20 +1,12 @@
-// Optional revocation denylist: instant permission/session revoke without putting Keto
-// back on the hot path. Off by default — enable with REVOCATION_DENYLIST=true.
+// Optional revocation denylist: instant permission/session revoke without putting Keto back on the
+// hot path. Off by default — enable with REVOCATION_DENYLIST=true. An admin action records the
+// subject as revoked-now; the hot path then rejects that subject's pre-revoke tokens at once,
+// forcing a re-mint (which re-reads permissions from Keto, or clears a now-dead session).
 //
-// The hot path verifies a short-lived (~10m) session JWT in-process, so a revoked permission or a
-// killed session only takes effect when the token is next minted (re-login / TTL refresh) —
-// up to one token TTL of lag. For security-critical revoke (offboarding, a compromised
-// account) that lag is too long. An admin action records the subject as revoked-now and the
-// hot path then rejects that subject's pre-revoke tokens at once, forcing a re-mint (which
-// re-reads permissions from Keto, or clears a now-dead session).
-//
-// Cost & scope: an in-memory, auto-evicting Map — no database, like the JWKS cache, so it
-// stays inside the stateless model. A token carries `iat`, so a *fresh* re-login (iat after
-// the revoke) passes while every token minted before the revoke is rejected. Entries self-evict
-// after one token TTL, by which point any pre-revoke token has expired anyway. Single-process:
-// instant on the instance that handled the revoke; across replicas/restarts the guarantee
-// falls back to the token TTL (the gap is just no longer closed early). Back it with a shared
-// store for hard multi-instance instant-revoke.
+// An in-memory, auto-evicting Map — no database, so it stays inside the stateless model. Entries
+// self-evict after one token TTL, by which point any pre-revoke token has expired anyway.
+// Single-process: instant on the instance that handled the revoke, elsewhere the guarantee falls
+// back to the token TTL. Back it with a shared store for hard multi-instance instant-revoke.
 
 export interface Denylist {
   // Hot-path check: is a token for `sub`, issued at `iat` (unix sec), revoked? A token minted
diff --git a/src/auth/guards.ts b/src/auth/guards.ts
index a631551..5012ee4 100644
--- a/src/auth/guards.ts
+++ b/src/auth/guards.ts
@@ -1,8 +1,6 @@
-// Auth guards: in-handler authorization, the imperative counterpart to the
-// declarative route `permission` gate. The middleware already verified the session JWT and put
-// the User on ctx; these read it. `requireSession` asserts (throws GuardError, which app.ts maps
-// to a response); `can`/`check` are predicates a handler branches on. `check` is the one live
-// Keto call — the fine-grained "may I?" tier (README), reserved for relationship rules.
+// In-handler authorization, the imperative counterpart to the declarative route `permission` gate.
+// `requireSession` asserts (throws GuardError, which app.ts maps to a response); `can`/`check` are
+// predicates a handler branches on. `check` is the one live Keto call, for relationship rules.
 import type { RequestContext, User } from "../http/context.ts";
 import type { KetoClient } from "./keto-client.ts";
 import { localPath } from "../http/safe-url.ts";
diff --git a/src/auth/routes.ts b/src/auth/routes.ts
index 5f98592..da64706 100644
--- a/src/auth/routes.ts
+++ b/src/auth/routes.ts
@@ -231,10 +231,8 @@ function logout(kratos: KratosPublic, secureCookies: boolean): BuiltinRoute["han
 }
 
 // Kratos' self-service error sink (kratos.yml flows.error.ui_url → /error). A flow that fails a
-// security/expiry check redirects the browser here with ?id=<uuid>. Render a themed page with a
-// path back into sign-in instead of the catch-all 404 ("Page not found") it used to hit. The
-// canonical-host redirect prevents the common cause (a lost cross-host CSRF cookie); this is the
-// honest fallback for any genuine flow error. The id is shown only for support reference.
+// security/expiry check redirects the browser here with ?id=<uuid>; render a themed page with a
+// path back into sign-in rather than the catch-all 404. The id is shown for support reference only.
 const errorSink = (ctx: RequestContext): RouteResult =>
   ({ data: { id: ctx.url.searchParams.get("id") }, view: "error" });
 
diff --git a/src/compose.test.ts b/src/compose.test.ts
index 1a96ba7..1a355c1 100644
--- a/src/compose.test.ts
+++ b/src/compose.test.ts
@@ -113,7 +113,7 @@ test("the E2E runner writes its artifacts as the invoking user, never as root",
   // filter would otherwise leave that command silently unguarded.
   const documented = [read("README.md"), ...composeFiles("e2e-tests/").map(read)]
     .join("\n").split("\n").filter((l) => /docker compose .*\brun\b.*\be2e\b/.test(l));
-  assert.equal(documented.length, 10, "5 compose headers + 5 README blocks");
+  assert.equal(documented.length, 6, "5 compose headers + 1 README block");
   for (const l of documented)
     assert.match(l, /--user "\$\(id -u\):\$\(id -g\)"/, `passes the uid: ${l.trim()}`);
   // An absent mount source is daemon-created as root, and then that uid can't write it at all.
diff --git a/src/config.ts b/src/config.ts
index 682cd00..137fff7 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,12 +1,6 @@
-// Config loaded once from the environment at boot: Ory endpoints, cookie/CSRF
-// secrets, JWKS location, listen port, behaviour toggles. Fail-loud — a bad value, a
-// missing enforced secret, a bad URL, or an out-of-range port throws here, never at
-// request time.
-//
-// Environment-agnostic (AGENTS.md): the app never asks "which environment am I?". Every
-// behaviour that used to ride on NODE_ENV is its own explicit toggle — `CACHE_TEMPLATES`,
-// `REQUIRE_SECURE_SECRETS`. Clean-clone (README): every value has a working dev default,
-// so `docker compose up` runs with zero config; a hardened deploy sets the toggles it wants.
+// Config loaded once from the environment at boot. Fail-loud — a bad value, a missing enforced
+// secret, a bad URL or an out-of-range port throws here, never at request time. Every value has a
+// working dev default, so `docker compose up` runs with zero config.
 
 // Log verbosity, most→least severe; "none" silences everything (matches @larvit/log's levels).
 export const LOG_LEVELS = ["error", "warn", "info", "verbose", "debug", "silly", "none"] as const;
diff --git a/src/http/app.test.ts b/src/http/app.test.ts
index dd07608..b4041f6 100644
--- a/src/http/app.test.ts
+++ b/src/http/app.test.ts
@@ -27,15 +27,12 @@ import type { MenuConfig } from "../ui/menu-config.ts";
 import { loadI18n } from "../i18n/load.ts";
 
 const viewsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "views");
-// The admin screens ship as a drop-in example plugin; the HTTP-level admin tests mount it via
-// createApp (with stub Ory clients on ctx.system + views from examples/plugins) exactly as an
-// operator would after copying it into plugins/.
+// The HTTP-level admin tests mount the example plugin via createApp — stub Ory clients on
+// ctx.system, views from examples/plugins — exactly as an operator would after copying it in.
 const examplesPluginsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "examples", "plugins");
 const adminPlugin: Plugin = { ...adminManifest, id: "admin" };
 
-// A session JWT signed with a throwaway test key — the verify path. Wired into the shared
-// `server` (and the per-test apps) so a request can present a valid session; the dashboard and the
-// gated routes need one. `staticJwks([ecJwk])` is the matching verify side.
+// A session JWT signed with a throwaway test key; `staticJwks([ecJwk])` is the matching verify side.
 const ec = generateKeyPairSync("ec", { namedCurve: "P-256" });
 const ecJwk: JsonWebKey = { ...(ec.publicKey.export({ format: "jwk" }) as JsonWebKey), alg: "ES256", kid: "test-kid" };
 const b64url = (i: Buffer | string): string => Buffer.from(i).toString("base64url");
@@ -101,8 +98,7 @@ test("plugins replace either landing: `home` owns the public /, `dashboard` owns
   const dir = mkdtempSync(join(tmpdir(), "pp-home-"));
   mkdirSync(join(dir, "portal", "views"), { recursive: true });
   writeFileSync(join(dir, "portal", "views", "welcome.ejs"), `<h1>Welcome to <%= brand %></h1><a href="/login">Sign in</a>`);
-  // The dashboard view renders the native app shell from ctx.chrome — the blessed plugin ergonomics:
-  // its own title/body, the global menu (chrome.nav), the signed-in user, the Sign-out CSRF token.
+  // The dashboard view renders the native app shell from ctx.chrome.
   writeFileSync(join(dir, "portal", "views", "board.ejs"),
     `<%- include("partials/shell", { body: "<p>Hi " + user.email + "</p>", brand: chrome.brand, csrfToken: chrome.csrfToken, nav: include("partials/nav-tree", { nodes: chrome.nav }), theme: chrome.theme, title: "My Portal", user: chrome.user }) %>`);
   t.after(() => rmSync(dir, { force: true, recursive: true }));
@@ -326,9 +322,8 @@ function rawGet(port: number, path: string, host: string, method = "GET"): Promi
 }
 
 test("APP_URL canonical-host redirect: an off-host visitor is 308'd to the configured origin (path+query kept)", async (t) => {
-  // The fix for the localhost-vs-127.0.0.1 / multi-domain trap: reach the app on any host and it
-  // sends you to APP_URL's host, so the browser, the themed form, and the cross-origin Kratos POST
-  // all share ONE cookie host. Off-canonical only — same-host requests pass straight through.
+  // Reach the app on any host and it sends you to APP_URL's, so the browser, the themed form and the
+  // cross-origin Kratos POST share ONE cookie host. Same-host requests pass straight through.
   const app = createApp({ jwks: staticJwks([ecJwk]), appUrl: "http://canonical.example:3000" });
   await new Promise<void>((r) => app.listen(0, r));
   t.after(() => app.close());
@@ -359,8 +354,8 @@ test("no APP_URL configured ⇒ no canonical redirect (unit-test apps and host-a
 });
 
 test("/error renders a themed sign-in error page (Kratos' flow error sink), not the 404", async () => {
-  // Kratos' flows.error.ui_url points here; a flow error redirects to /error?id=<uuid>. Without a
-  // handler it 404'd as "Page not found" (confusing). It must be a real, themed page now.
+  // Kratos' flows.error.ui_url points here; a flow error redirects to /error?id=<uuid>, which must
+  // land on a real themed page rather than the catch-all 404.
   const res = await fetch(base + `/error?id=${randomUUID()}`, { redirect: "manual" });
   assert.equal(res.status, 200);
   assert.match(res.headers.get("content-type") ?? "", /text\/html/);
@@ -1257,9 +1252,8 @@ test("admin Groups screen: gate, list, create, detail/membership, delete (CSRF-g
   assert.equal((await get("/admin/groups/%ZZ")).status, 404);
 });
 
-// Granting permissions over HTTP, on the two screens that replaced the deleted Permissions screen.
-// The offered set is the host's catalog (ctx.declaredPermissions, from what the installed plugins
-// declare), so the checkboxes are a fixed list and the POST is the desired state.
+// Granting permissions over HTTP. The offered set is the host's catalog (ctx.declaredPermissions),
+// so the checkboxes are a fixed list and the POST is the desired state.
 test("admin permission grants: the picker offers the declared catalog, and a save is the desired set", async (t) => {
   const ada = randomUUID();
   const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
@@ -1348,7 +1342,7 @@ test("admin screens render no write affordance for a read-only holder", async (t
   assert.doesNotMatch(group, /Delete group/);
   assert.doesNotMatch(group, /Save permissions/);
 
-  // The OAuth2-clients screen is held to the same rule (it was the one this test was written to catch).
+  // The OAuth2-clients screen is held to the same rule.
   const clientsRes = await get("/admin/clients", ["oauth2-clients:read"]);
   assert.equal(clientsRes.status, 200); // a real render, not the capability-missing 503
   const clients = await clientsRes.text();
diff --git a/src/http/app.ts b/src/http/app.ts
index 57a5cef..0314f04 100644
--- a/src/http/app.ts
+++ b/src/http/app.ts
@@ -39,15 +39,11 @@ const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 export interface AppOptions {
   appUrl?: string; // canonical public URL (config.appUrl); off-host GET/HEAD visitors are 308'd here. Omitted ⇒ no redirect
   auth?: VerifyOptions; // expected JWT issuer/audience + clock skew (config); used with jwks
-  // Cache compiled templates; caller decides (server passes config.cacheTemplates).
-  // Off by default so edits show live; the app itself never inspects the environment.
-  cache?: boolean;
+  cache?: boolean; // cache compiled EJS templates (config.cacheTemplates); off ⇒ edits show live
   csrfSecret?: string; // HMAC key for the double-submit CSRF token (config.csrfSecret); random if omitted
   denylist?: Denylist; // optional instant-revoke; the hot path rejects revoked subjects, admin writes record revokes
   hydra?: HydraAdmin; // Hydra admin client; with kratos enables the OAuth2 login challenge
-  // Loaded translation catalogs (server.ts passes the discovered ones). Omitted ⇒ the built-in
-  // en-US catalog only, so an unwired app still renders real English.
-  i18n?: I18n;
+  i18n?: I18n; // discovered catalogs; omitted ⇒ the built-in en-US only, so an unwired app still renders English
   jwks?: JwksProvider; // verify the session JWT → ctx.user/permissions; absent ⇒ always anonymous
   keto?: KetoClient; // Keto client; with kratos+kratosAdmin enables login completion
   kratos?: KratosPublic; // Kratos public client; enables the themed self-service routes
@@ -62,15 +58,12 @@ export interface AppOptions {
 }
 
 export function createApp(options: AppOptions = {}): Server {
-  // The denylist (when enabled) rides in the verify options so resolveSession rejects a revoked
-  // subject on the hot path; the bound `revoke` is handed to the admin handlers that should
-  // revoke instantly. Both absent ⇒ the feature is fully off (no cost, no behaviour change).
+  // The denylist rides in the verify options so resolveSession rejects a revoked subject on the hot
+  // path; the bound `revoke` goes to the admin handlers. Both absent ⇒ the feature is fully off.
   const denylist = options.denylist;
   const authOptions: VerifyOptions = denylist ? { ...(options.auth ?? {}), denylist } : (options.auth ?? {});
   const revoke = denylist ? (sub: string): void => denylist.revoke(sub) : undefined;
   const cache = options.cache ?? false;
-  // Canonical public host (APP_URL): when set, an off-host GET/HEAD visitor is redirected here so
-  // every cookie (esp. Kratos' cross-origin CSRF cookie) shares one host. Omitted ⇒ feature off.
   const canonical = options.appUrl ? new URL(options.appUrl) : undefined;
   const canonicalHost = canonical?.host; // host[:port], default ports omitted — matches the Host header
   const canonicalOrigin = canonical?.origin; // scheme + host[:port], no trailing slash
@@ -82,9 +75,7 @@ export function createApp(options: AppOptions = {}): Server {
   const keto = options.keto;
   const kratos = options.kratos;
   const kratosAdmin = options.kratosAdmin;
-  // Privileged host services handed to a system plugin via ctx.system — the Ory admin clients and
-  // the instant-revoke hook. Only the wired capabilities are present; with none wired ctx.system
-  // stays undefined, so an ordinary deployment (no Ory, hence no system plugin) pays nothing.
+  // Only the wired capabilities are present; with none wired ctx.system stays undefined.
   const system: SystemCapabilities | undefined = kratosAdmin || keto || hydra || revoke
     ? { ...(hydra ? { hydra } : {}), ...(keto ? { keto } : {}), ...(kratosAdmin ? { kratosAdmin } : {}), ...(revoke ? { revoke } : {}) }
     : undefined;
@@ -93,15 +84,11 @@ export function createApp(options: AppOptions = {}): Server {
   const menu = options.menu ?? DEFAULT_MENU;
   const plugins = options.plugins ?? [];
   const pluginIds = new Set(plugins.map((p) => p.id));
-  // A plugin may fully replace the public landing "/" (`home`) or the gated dashboard "/dashboard"
-  // (`dashboard`) — Discovery's findConflicts guarantees at most one of each, so `find` is
-  // unambiguous; the predicates narrow the slot to defined.
+  // `find` is unambiguous: findConflicts guarantees at most one owner of each landing slot.
   const homePlugin = plugins.find((p): p is Plugin & { home: RouteHandler } => typeof p.home === "function");
   const dashboardPlugin = plugins.find((p): p is Plugin & { dashboard: RouteHandler } => typeof p.dashboard === "function");
-  // Skip the hook pipeline entirely unless a plugin declares the hook (keeps the hot path free).
-  // The permission catalog is a property of the installed plugin set, so it is computed once at
-  // wiring rather than per request.
   const permissionCatalog = declaredPermissions(plugins);
+  // Skip the hook pipeline entirely unless a plugin declares the hook (keeps the hot path free).
   const anyRequestHooks = plugins.some((p) => p.hooks?.onRequest);
   const anyResponseHooks = plugins.some((p) => p.hooks?.onResponse);
   const pluginsDir = options.pluginsDir ?? PLUGINS_DIR;
@@ -115,19 +102,11 @@ export function createApp(options: AppOptions = {}): Server {
   const render = (view: string, data: Record<string, unknown>): Promise<string> =>
     ejs.renderFile(join(viewsDir, `${view}.ejs`), data, { cache, views: [viewsDir] });
 
-  // A `view` RouteResult renders plugins/<id>/views/<view>.ejs; such views may include() the core
-  // building-block partials (resolved from viewsDir) and their own partials/subfolders.
   const renderView = renderPluginView({ cache, coreViewsDir: viewsDir, pluginsDir });
 
-  // Every view renders with its context's i18n locals (t/locale/dir/localeSwitch/localeParam) merged
-  // in, so a view — core or plugin, at any include depth — calls `t(...)` without its handler passing
-  // it. A plugin's context carries that plugin's translator, so its own catalog wins in its own views.
-  // They are merged LAST: these names are reserved (README → Building plugins), and a handler that
-  // happens to use one loses that key rather than breaking the shell that renders around it.
-  // Where the language picker on this page should point. Normally the page itself; after a POST
-  // that URL may answer no GET (POST /admin/users/:id/delete has no GET sibling), so fall back to
-  // the page the form was submitted from, then to the front page — the picker is on every page, so
-  // every one of its links has to land somewhere real.
+  // Where the language picker points. Normally the page itself; after a POST that URL may answer no
+  // GET (POST /admin/users/:id/delete has no GET sibling), so fall back to the page the form was
+  // submitted from, then to the front page — the picker is on every page, so every link must land.
   const switchBase = (req: IncomingMessage, url: URL): string => {
     const method = (req.method ?? "GET").toUpperCase();
     if (method === "GET" || method === "HEAD") return `${url.pathname}${url.search}`;
@@ -147,6 +126,8 @@ export function createApp(options: AppOptions = {}): Server {
     t: ctx.t,
     url: ctx.url,
   });
+  // i18n locals go last: their names are reserved, so a handler's colliding key loses instead of
+  // breaking the shell around it.
   const viewsFor = (ctx: RequestContext): ViewRenderer => (view, data) => render(view, { ...data, ...i18nLocals(localsOf(ctx)) });
   const pluginViewsFor = (ctx: RequestContext, id: string): ViewRenderer => (view, data) => renderView(id, view, { ...data, ...i18nLocals(localsOf(ctx)) });
 
@@ -155,10 +136,7 @@ export function createApp(options: AppOptions = {}): Server {
     res.end(html);
   };
 
-  // The public landing "/": ungated — anyone may see it. A plugin may fully own it via `home`
-  // (rendered against its own views, native shell via ctx.chrome, with a fresh CSRF cookie for
-  // any form it ships). Else the built-in intro page with prominent sign-in / register links
-  // (`user` picks "go to dashboard" vs sign-in; the shell's Sign-out form needs the CSRF cookie).
+  // The public landing "/", ungated. A plugin may own it via `home`; else the built-in intro page.
   const serveHome = async (ctx: RequestContext, csrf: RequestCsrf, contextFor: PluginContextFactory): Promise<RouteResult | null> => {
     csrf.setCookie();
     if (homePlugin) {
@@ -172,10 +150,8 @@ export function createApp(options: AppOptions = {}): Server {
     return { data: { chrome: ctx.chrome, user: ctx.user }, view: "home" };
   };
 
-  // The post-login app home "/dashboard", gated to a signed-in user: anonymous bounces to sign
-  // in, remembering /dashboard as return_to. A plugin may fully own it via `dashboard` — its
-  // handler renders against its own views, same path as a plugin route. Else the built-in
-  // mock-data People list with the one global menu (ctx.chrome.nav) + branding from config/menu.ts.
+  // "/dashboard", gated to a signed-in user. A plugin may own it via `dashboard`; else the built-in
+  // starter page.
   const serveDashboard = async (ctx: RequestContext, csrf: RequestCsrf, contextFor: PluginContextFactory): Promise<RouteResult | null> => {
     if (!ctx.user) return { redirect: loginRedirect(ctx), status: 303 };
     // The page carries the Sign-out form, so Set-Cookie a fresh CSRF token here when absent.
@@ -214,26 +190,21 @@ export function createApp(options: AppOptions = {}): Server {
       // (writeHead merges these with its own headers; a plugin's RouteResult.headers can override).
       for (const [name, value] of secHeaderEntries) res.setHeader(name, value);
 
+      // Before auth: assets don't need a verified user, and the JWT cookie rides every request.
       if (pathname.startsWith("/public/") && (method === "GET" || method === "HEAD")) {
-        // /public/<id>/… serves a plugin's public/; everything else the core public/.
-        // Before auth: assets don't need a verified user, and the JWT cookie rides every request.
         const { dir, subPath } = routePublic(pathname.slice("/public/".length), publicDir, pluginsDir, pluginIds);
         await serveStatic(dir, subPath, res, method === "HEAD", (err) => reqLog.error("static stream error", { error: String(err) }));
         return;
       }
 
-      // Rendered pages content-negotiate on Accept-Language, so a cache in front of us must key on
-      // it — otherwise the first visitor's language is served to everyone. Set after the static
-      // branch above: an asset is the same bytes in every language, and a Vary there would fragment
-      // its cache entry per raw header string.
+      // A cache in front of us must key on the language. Set after the static branch: an asset is
+      // the same bytes in every language, and a Vary there fragments its entry per raw header.
       res.setHeader("vary", "accept-language");
 
-      // Canonical host (APP_URL): a visitor who reached us on a different host (localhost vs
-      // 127.0.0.1, a secondary domain) is sent to the configured origin, path + query preserved, so
-      // the browser, the themed forms, and the cross-origin Kratos POST all share one cookie host —
-      // otherwise the host-scoped Kratos CSRF cookie is lost and login dumps onto /error. Static
-      // assets above are served on any host (health checks). GET/HEAD only — a 308 must not replay a
-      // cross-host POST; first-party forms are always served from a canonical page anyway.
+      // Canonical host (APP_URL): send an off-host visitor to the configured origin so the browser,
+      // the themed forms and the cross-origin Kratos POST share one cookie host — otherwise the
+      // host-scoped Kratos CSRF cookie is lost and login dumps onto /error. GET/HEAD only: a 308
+      // must not replay a cross-host POST.
       if (canonicalHost && (method === "GET" || method === "HEAD")) {
         const host = req.headers.host;
         if (host !== undefined && host !== canonicalHost) {
@@ -242,18 +213,14 @@ export function createApp(options: AppOptions = {}): Server {
         }
       }
 
-      // Which language this request is served in: ?locale wins, else Accept-Language, else en-US.
-      // `explicit` (the URL asked) is what makes the choice travel: the chrome, this request's
-      // redirects and ctx.localeHref then carry ?locale onto the links they emit.
+      // `explicit` (the URL asked for a locale) is what makes the choice travel: the chrome, this
+      // request's redirects and ctx.localeHref then carry ?locale onto the links they emit.
       const { explicit, locale } = i18n.resolve({ acceptLanguage: req.headers["accept-language"], param: url.searchParams.get("locale") });
       const carryLocale = (href: string): string => localeHref(href, explicit ? locale : null);
       const t = i18n.translator(locale);
 
-      // Verify the session JWT once (cached JWKS) → ctx.user/permissions; none/invalid ⇒ anonymous.
-      // If the token has lapsed but a live Kratos session still backs it (and we have the Ory
-      // clients), silently re-mint it — "stay signed in": re-read permissions from Keto, re-tokenize,
-      // and set the fresh cookie via setHeader so it rides whatever response this request produces
-      // (a dead session clears the stale cookie). This is the only place the hot path touches Ory.
+      // A lapsed token still backed by a live Kratos session is silently re-minted — "stay signed
+      // in". The only place the hot path touches Ory.
       let user: User | null = null;
       if (jwks) {
         const auth = await resolveSession(req.headers.cookie, jwks, authOptions);
@@ -264,32 +231,25 @@ export function createApp(options: AppOptions = {}): Server {
             user = reminted.user;
             res.appendHeader("set-cookie", reminted.setCookie);
           } catch (err) {
-            // Ory unreachable (Kratos/Keto 5xx, refused, timeout) — degrade to anonymous instead of
-            // 500ing every lapsed request. Leave the cookie alone: it can re-mint once Ory recovers.
+            // Ory unreachable — degrade to anonymous instead of 500ing every lapsed request. Leave
+            // the cookie alone: it can re-mint once Ory recovers.
             reqLog.warn("session re-mint failed (Ory unreachable?)", { error: String(err) });
           }
         }
       }
-      // CSRF token for this request's first-party forms: reuse a genuine cookie token, else mint
-      // one (a page-emitting handler Set-Cookies it via csrfMint). Verified on our own
-      // state-changing routes.
       const csrf = ensureCsrfToken(req.headers.cookie, csrfSecret);
       const csrfMint: RequestCsrf = {
         setCookie: (): void => { if (csrf.fresh) res.appendHeader("set-cookie", csrfCookie(csrf.token, { secure: secureCookies })); },
         token: csrf.token,
       };
-      // Bound CSRF verifier handed to plugins via ctx.verifyCsrf (the host owns the secret).
       const verifyCsrf = (submitted: string | null | undefined): boolean =>
         verifyCsrfRequest({ cookieHeader: req.headers.cookie, secret: csrfSecret, submitted });
-      // Chrome (brand/global-nav/user/theme/csrf) composes the whole menu, so it's resolved lazily and
-      // at most once per request: this app-level memo shares it across the contexts below, and each
-      // ctx.chrome getter only triggers it when a handler actually reads it (a json/redirect handler,
-      // or the public "/" with a standalone home, never composes the menu).
+      // Chrome composes the whole menu, so it is memoized and resolved lazily — a json/redirect
+      // handler, or the public "/" with a standalone home, never pays for it.
       let chromeMemo: PageChrome | undefined;
       const chrome = (): PageChrome => (chromeMemo ??= buildPluginChrome({ csrfToken: csrf.token, currentPath: pathname, localeHref: carryLocale, menu, plugins, t, translatorFor: (id) => i18n.translator(locale, id), user }));
 
-      // The i18n half of every context: the locale, its translator, and the link carrier. A plugin
-      // route swaps in the plugin's own translator (its catalog first, then core).
+      // A plugin's context gets the plugin's own translator — its catalog first, then core.
       const i18nFor = (pluginId?: string) => ({
         locale,
         localeHref: carryLocale,
@@ -297,9 +257,8 @@ export function createApp(options: AppOptions = {}): Server {
         t: pluginId === undefined ? t : i18n.translator(locale, pluginId),
       });
 
-      // base context (no route params yet); reused for the built-in routes. A plugin-owned render
-      // (a landing slot, a hook short-circuit, a plugin route) gets `contextFor(id)` instead, so its
-      // own catalog is what `ctx.t` reads.
+      // Base context (no route params), for the built-in routes. Every plugin-owned render — a
+      // landing slot, a hook short-circuit, a plugin route — gets `contextFor(id)` instead.
       const ctx = buildContext(req, res, { chrome, declaredPermissions: permissionCatalog, user, ...i18nFor(), log: reqLog, verifyCsrf, ...(system ? { system } : {}) });
       const contextFor = (pluginId: string, params?: Record<string, string>): RequestContext =>
         buildContext(req, res, { chrome, declaredPermissions: permissionCatalog, user, ...i18nFor(pluginId), log: reqLog, ...(params ? { params } : {}), verifyCsrf, ...(system ? { system } : {}) });
@@ -309,23 +268,19 @@ export function createApp(options: AppOptions = {}): Server {
       if (anyRequestHooks) {
         const short = await runRequestHooks(plugins, contextFor);
         if (short) {
-          // Set the fresh CSRF cookie like every other page-emitting path, so a form the hook
-          // renders (its token is in ctx.chrome.csrfToken) has the matching double-submit cookie.
+          // Like every other page-emitting path, so a form the hook renders has its matching cookie.
           csrfMint.setCookie();
           await sendResult(res, short.result, pluginViewsFor(short.ctx, short.plugin.id), carryLocale);
           return;
         }
       }
 
-      // Plugin routes (any method): gate on the route's permission, then run the handler. The
-      // handler gets ctx.chrome (native app shell) + ctx.verifyCsrf (guard its own forms); a fresh
-      // CSRF cookie is set so those forms have a valid double-submit token.
       const match = matchRoute(plugins, method, pathname);
       if (match) {
         const routeCtx = contextFor(match.plugin.id, match.params);
         if (!isAuthorized(match.route, routeCtx.permissions)) {
-          // Anonymous → sign in (like the built-in screens' requireSession), remembering the page as
-          // return_to; a signed-in user who simply lacks the permission gets the 403 page.
+          // Anonymous → sign in, remembering the page as return_to; a signed-in user who simply
+          // lacks the permission gets the 403 page.
           if (!routeCtx.user) { res.writeHead(303, { location: loginRedirect(routeCtx) }).end(); return; }
           reqLog.warn("forbidden: missing permission", { path: pathname, required: match.route.permission ?? "", sub: routeCtx.user.id });
           sendHtml(res, 403, await renderPage("403", {}));
@@ -340,9 +295,6 @@ export function createApp(options: AppOptions = {}): Server {
         return;
       }
 
-      // Built-in endpoints (the auth/OAuth2 group, the landing slots, /error) from the internal
-      // route table — same handler shape as plugin routes; a `view` result renders the core views,
-      // null means the handler wrote to ctx.res itself.
       const builtin = matchBuiltinRoute(builtinRoutes, method, pathname);
       if (builtin) {
         await sendResult(res, await builtin.handler(ctx, csrfMint, contextFor), viewsFor(ctx), carryLocale);
@@ -385,20 +337,16 @@ export function createApp(options: AppOptions = {}): Server {
   };
 
   return createServer((req, res) => {
-    // Per-request log + trace span: a "request" span, continuing an upstream W3C traceparent
-    // when present (distributed tracing across a proxy). "close" (not "finish") fires on both a
-    // completed response and a premature disconnect/abort, so an aborted/truncated request is still
-    // logged and its span flushed.
+    // "close" (not "finish") fires on both a completed response and a premature disconnect, so an
+    // aborted request is still logged and its span flushed.
     const startMs = Date.now();
     const reqLog = requestLogger(log, {
       requestId: randomUUID(),
       ...(typeof req.headers.traceparent === "string" ? { traceparent: req.headers.traceparent } : {}),
     });
-    // end() must run exactly once, after BOTH the handler has fully unwound (settled) AND the
-    // response has closed (the access line is then emitted with the final status). Ending earlier
-    // would throw "already ended" from a still-running handler's ctx.log/tracedFetch on a client
-    // abort, or drop the access line on the happy path (handler settles before close). Coordinating
-    // the two signals avoids both. Logging must never crash a served request, so it's all guarded.
+    // end() must run exactly once, after BOTH the handler has unwound AND the response has closed.
+    // Earlier would throw "already ended" from a still-running handler's ctx.log on a client abort,
+    // or drop the access line on the happy path (the handler settles before close).
     let settled = false;
     let closed = false;
     const finalize = (): void => { if (settled && closed) void reqLog.end().catch(() => {}); };
@@ -410,9 +358,8 @@ export function createApp(options: AppOptions = {}): Server {
       } catch { /* never let logging crash a served request */ }
       finalize();
     });
-    // Make reqLog ambient for the whole handler (sync body + every await) so all outbound fetch is
-    // traced. handleRequest owns its own try/catch; the .catch logs a pathological escape via the
-    // app logger (not reqLog, which may be the thing that broke), never crashing the request.
+    // Make reqLog ambient for the whole handler so all outbound fetch is traced. The .catch logs a
+    // pathological escape via the app logger — not reqLog, which may be the thing that broke.
     void runWithLog(reqLog, () => handleRequest(req, res, reqLog))
       .catch((err) => log.error("request handler escaped its try/catch", { error: err instanceof Error ? (err.stack ?? err.message) : String(err) }))
       .finally(() => { settled = true; finalize(); });
diff --git a/src/http/safe-url.ts b/src/http/safe-url.ts
index 52dd2c5..2b52c9e 100644
--- a/src/http/safe-url.ts
+++ b/src/http/safe-url.ts
@@ -1,15 +1,8 @@
-// URL safety helpers. Two pure, dependency-free guards:
-//
-//   safeUrl(value)  — sanitise an untrusted URL before rendering it in an href/src attribute.
-//                     Partials escape *text*, but a URL field is emitted verbatim, so a
-//                     `javascript:`/`data:` URL from upstream/user data would be live XSS. The
-//                     contract (README.md → Routes & handlers) is: a relative or http(s) URL is allowed,
-//                     anything else collapses to "#". Exported to plugins via plugin-api.ts.
-//
-//   localPath(value) — validate a redirect target is a *same-origin* path (the redirect-URI
-//                     allowlist). Used for `return_to`: a host-relative "/a/b?x=1" passes, an
-//                     absolute or protocol-relative ("//evil.com", "https://evil.com") is rejected
-//                     so a crafted ?return_to= can't turn login completion into an open redirect.
+//   safeUrl(value)   — a URL field is emitted verbatim into an href/src, so a `javascript:`/`data:`
+//                      URL from untrusted data would be live XSS. Relative or http(s) passes,
+//                      anything else collapses to "#". Exported to plugins via plugin-api.ts.
+//   localPath(value) — the redirect-URI allowlist for `return_to`: host-relative passes, absolute
+//                      or protocol-relative is rejected, so a crafted value can't open-redirect.
 
 // ASCII control chars + space that browsers strip/ignore when resolving a URL — strip them before
 // the scheme check so "java\tscript:" / a leading space can't masquerade as relative.
diff --git a/src/http/security-headers.ts b/src/http/security-headers.ts
index 1772723..f042160 100644
--- a/src/http/security-headers.ts
+++ b/src/http/security-headers.ts
@@ -1,15 +1,11 @@
-// Response security headers: set once per request in app.ts so every response — page,
-// JSON, redirect, static, or error — carries them (writeHead merges with setHeader). A plugin route
-// may override any of them per-response via RouteResult.headers (e.g. relax the CSP to ship its own JS).
+// Set once per request in app.ts, so every response carries them (writeHead merges with setHeader).
+// A plugin route may override any per-response via RouteResult.headers.
 
-// Strict default CSP for the zero-JS, server-rendered core:
-//  - script-src 'self'  : the core ships no JS; a plugin may still serve its own /public/<id>/*.js for
-//                         opt-in progressive enhancement. No 'unsafe-inline' ⇒ an injected <script>
-//                         can't run (the main XSS sink).
-//  - style-src adds 'unsafe-inline' : a few partials carry inline style= attributes.
-//  - img-src adds data:             : favicon + inline data URIs.
-//  - no form-action     : the themed login form posts to Kratos' (often cross-origin) action URL.
-//  - frame-ancestors 'none' : clickjacking guard (the modern X-Frame-Options).
+// The non-obvious parts of the CSP:
+//  - script-src 'self' with no 'unsafe-inline' ⇒ an injected <script> can't run. A plugin may still
+//    serve its own /public/<id>/*.js for opt-in progressive enhancement.
+//  - style-src adds 'unsafe-inline': a few partials carry inline style= attributes.
+//  - no form-action: the themed login form posts to Kratos' (often cross-origin) action URL.
 const CSP = [
   "base-uri 'self'",
   "default-src 'self'",
diff --git a/src/i18n/load.ts b/src/i18n/load.ts
index b7ed0eb..71d9b41 100644
--- a/src/i18n/load.ts
+++ b/src/i18n/load.ts
@@ -1,12 +1,10 @@
-// Catalog discovery: import src/i18n/locales/<tag>.ts and plugins/<id>/i18n/<tag>.ts, then
-// check every one against its set's en-US baseline. The imperative shell over catalog.ts's pure
-// rules — the same contract as plugin discovery: one boot-stopping Error listing every problem,
-// so a half-translated deploy is caught at startup rather than as a stray English word in production.
+// Catalog discovery: import src/i18n/locales/<tag>.ts and plugins/<id>/i18n/<tag>.ts, then check
+// every one against its set's en-US baseline. The imperative shell over catalog.ts's pure rules,
+// with plugin discovery's contract: one boot-stopping Error listing every problem, so a
+// half-translated deploy is caught at startup rather than as a stray English word in production.
 //
-// Installed locales are whatever the core folder holds; a plugin may translate fewer of them (its
-// strings then render in en-US on that page) but never one the host does not have. The operator's
-// `locales/` mount extends both sides — `locales/<tag>.ts` for the core, `locales/plugins/<id>/<tag>.ts`
-// for a plugin — so adding a language never means forking the image or a vendored plugin.
+// A plugin may translate fewer locales than the core holds (its strings then render in en-US) but
+// never one the host lacks. The operator's `locales/` mount extends both sides.
 
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
diff --git a/src/i18n/translate.ts b/src/i18n/translate.ts
index 717899f..dd03cd1 100644
--- a/src/i18n/translate.ts
+++ b/src/i18n/translate.ts
@@ -1,12 +1,9 @@
-// The translator: a key + vars → the string to render. Pure and synchronous — views call it
-// as `t("shell.signOut")` and handlers as `ctx.t(...)`.
-//
-// Two rules the rest of the app leans on:
-//   · the lookup walks a catalog chain (plugin locale → plugin en-US → core locale → core en-US) and,
-//     when nothing has the key, returns the key itself. That is what makes a plain nav label like
-//     "Shifts" its own fallback — a manifest needs no catalog to keep working.
-//   · the result is raw text. Views escape with <%= %> exactly as they do for any other value, so a
-//     translation is never double-escaped, and a message that carries markup is rendered with <%- %>.
+// The translator: a key + vars → the string to render. Two rules the rest of the app leans on:
+//   · the lookup walks a catalog chain (plugin locale → plugin en-US → core locale → core en-US)
+//     and returns the key itself when nothing has it — so a plain nav label like "Shifts" is its
+//     own fallback and a manifest needs no catalog to keep working.
+//   · the result is raw text, escaped by the view with <%= %> like any other value, so a
+//     translation is never double-escaped and one carrying markup is rendered with <%- %>.
 
 import { isPluralMessage, type Catalog, type PluralMessage } from "./catalog.ts";
 
diff --git a/src/logger.ts b/src/logger.ts
index 38dcf9f..9cd81a5 100644
--- a/src/logger.ts
+++ b/src/logger.ts
@@ -21,11 +21,9 @@ export interface LoggerOptions {
   stdout?: (msg: string) => void;
 }
 
-// The app-level logger: a Log tagged service.name so every console line, OTLP log record and span is
-// attributed to the service. Level + format + name are explicit toggles (LOG_LEVEL/LOG_FORMAT/
-// SERVICE_NAME — environment-agnostic, AGENTS.md §4). With otlpEndpoint set, logs + spans also export
-// to that OTLP/HTTP collector (e.g. an OpenTelemetry Collector fronting Tempo/Loki); unset ⇒ console
-// only, at zero export cost. Conditional spreads keep exactOptionalPropertyTypes happy (no `key: undefined`).
+// The app-level logger, tagged service.name. With otlpEndpoint set, logs + spans also export to that
+// OTLP/HTTP collector; unset ⇒ console only, at zero export cost. The conditional spreads keep
+// exactOptionalPropertyTypes happy (no `key: undefined`).
 export function createLogger(opts: LoggerOptions = {}): Log {
   return new Log({
     context: { "service.name": opts.serviceName || SERVICE_NAME },
@@ -49,13 +47,10 @@ export function currentLog(): Log | undefined {
   return requestStore.getStore();
 }
 
-// A drop-in `fetch` that traces through the active request log — a client span nested under the
-// request span, with a W3C `traceparent` injected so the downstream service continues the same
-// trace. Outside a request (no ambient log) or for a non-string/URL input it's a plain `fetch`.
-// server.ts wires this (under the Ory timeout) into every Kratos/Keto/Hydra/JWKS call; a plugin
-// uses it for its upstream calls (exported via plugin-api.ts). The trace-setup adds no throw of its
-// own, but log.fetch throws synchronously if the request log has already ended (app.ts ends it only
-// after the handler unwinds, so a live handler never hits that).
+// A drop-in `fetch` that traces through the active request log — a client span under the request
+// span, with a W3C `traceparent` injected so the downstream service continues the same trace.
+// Outside a request, or for a non-string/URL input, it is a plain `fetch`. Note log.fetch throws
+// synchronously once the request log has ended; app.ts ends it only after the handler unwinds.
 export const tracedFetch: typeof fetch = (input, init) => {
   const log = currentLog();
   if (log && (typeof input === "string" || input instanceof URL)) return log.fetch(input, init);
@@ -63,11 +58,9 @@ export const tracedFetch: typeof fetch = (input, init) => {
 };
 
 // A per-request child logger holding a "request" trace span. `clone` (not parentLog) gives the
-// request its own root trace — so requests aren't all nested under one app-lifetime span — while
-// inheriting the parent's level/format/streams/OTLP. A valid upstream W3C `traceparent` is adopted
-// (the span continues that distributed trace across a reverse proxy/gateway; malformed ⇒ ignored, a
-// fresh trace starts). `requestId` tags every line + the span for log↔trace correlation. Flush with
-// `end()` on response finish to export the span — a no-op when OTLP is off.
+// request its own root trace, so requests aren't all nested under one app-lifetime span, while
+// inheriting the parent's level/format/streams/OTLP. A valid upstream `traceparent` is adopted;
+// malformed ⇒ ignored, a fresh trace starts. `end()` on response finish exports the span.
 export function requestLogger(appLog: Log, opts: { requestId: string; traceparent?: string | undefined }): Log {
   return appLog.clone({
     context: { ...appLog.context, requestId: opts.requestId },
diff --git a/src/plugin-host/plugin.ts b/src/plugin-host/plugin.ts
index 65b4b23..9b3d9de 100644
--- a/src/plugin-host/plugin.ts
+++ b/src/plugin-host/plugin.ts
@@ -1,6 +1,5 @@
-// The plugin contract — the product's main API surface: the machine-readable types +
-// pure rules; README.md (Building plugins) is the prose reference, discovery/router wire it to FS+HTTP.
-// Powerful, predictable, fails loud at boot/discovery rather than sandboxing at runtime.
+// The plugin contract — the product's main API surface: the machine-readable types + pure rules.
+// README → Building plugins is the prose reference; discovery/router wire this to FS + HTTP.
 //
 // A plugin's identity is its folder under plugins/: folder name = `id` (isValidPluginId), mount =
 // `/<id>`. Neither is in the manifest — the host derives them, so they can't drift or be claimed twice.
@@ -8,9 +7,7 @@
 import type { RequestContext } from "../http/context.ts";
 import type { NavNode } from "../ui/nav.ts";
 
-// Host contract version (semver). Bump major on a breaking manifest/handler change, minor on an
-// additive one. A plugin pins the version it targets via `apiVersion`; the host applies
-// provider/consumer semver semantics in checkApiVersion (refuse/warn on mismatch).
+// Bump major on a breaking manifest/handler change, minor on an additive one.
 export const HOST_API_VERSION = "1.0.0";
 
 export type HttpMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
@@ -30,24 +27,21 @@ export interface Route {
   method: HttpMethod;
   path: string; // relative to the plugin's mount path `/<id>`; ":name" segments → ctx.params.name
   permission?: string; // coarse gate — the Keto Permission the caller must hold; checked before the handler runs
-  // Mark the page reachable by anyone, signed in or not. The same as omitting `permission`
-  // — an ungated route is already open — but stated outright, so "public" is a deliberate
-  // choice, not an accident. Mutually exclusive with `permission` (discovery refuses both).
+  // Same as omitting `permission`, but stated outright so public is a deliberate choice rather than
+  // a forgotten gate. Mutually exclusive with `permission` (discovery refuses both).
   public?: boolean;
 }
 
-// A Keto Permission this plugin gates on — declared for docs/seeding. Permission names are a shared
-// global namespace (so an operator grants them once in Keto) and are always `<resource>:<action>` —
-// `scheduling:read`, `users:write`. A bare word names who someone is rather than what they may do,
-// which is a role, and roles are groups here (README → Users, groups & permissions).
+// A Keto Permission this plugin gates on — declared for docs/seeding. Names are a shared global
+// namespace, so an operator grants them once in Keto. See README → Users, groups & permissions.
 export interface PermissionDecl {
   description?: string;
   name: string;
 }
 
-// `<resource>:<action>`, each half lowercase alphanumeric with dashes/underscores inside. The 64-char
-// cap keeps a name usable as a Keto object and a URL path segment. Enforced at discovery like every
-// other manifest rule, so the convention holds for plugins the admin GUI never touches.
+// `<resource>:<action>`. The 64-char cap keeps a name usable as a Keto object and a URL path
+// segment. Enforced at discovery like every other manifest rule, so the convention holds for
+// plugins the admin GUI never touches.
 const PERMISSION_NAME = /^[a-z0-9][a-z0-9_-]*:[a-z0-9][a-z0-9_-]*$/;
 
 export function isValidPermissionName(name: string): boolean {
@@ -77,12 +71,10 @@ export interface PluginHooks {
 // host derives them from the folder name at discovery (see Plugin).
 export interface PluginManifest {
   apiVersion: string; // semver of the host contract this targets — write a literal, NOT HOST_API_VERSION (see docs)
-  // Take over the gated dashboard "/dashboard" — the post-login app home. A handler like any
-  // route's; the host gates it to a signed-in session (anonymous → /login), then renders its own view
-  // via ctx.chrome. At most one plugin may declare it (findConflicts → error, never last-write-wins).
+  // Take over "/dashboard"; the host gates it to a signed-in session first. At most one plugin may
+  // declare it (findConflicts → error, never last-write-wins).
   dashboard?: RouteHandler;
-  // Take over the public landing "/" — the ungated front page. A handler like any route's,
-  // anyone may reach it. At most one plugin may declare it (findConflicts → error).
+  // Take over the ungated public landing "/". At most one plugin may declare it.
   home?: RouteHandler;
   hooks?: PluginHooks;
   nav?: NavNode[]; // fragment merged into the menu (composeNav); node `icon` is a Lucide sprite id (src/ui/icons.ts), node ids must be globally unique
@@ -96,27 +88,23 @@ export interface Plugin extends PluginManifest {
   id: string;
 }
 
-// Identity helper: types the manifest, returns it unchanged. Validation happens at discovery
-//, so a plugin may equally be a plain typed object. Mirrors Vite's `defineConfig`.
+// Types the manifest and returns it unchanged; validation happens at discovery, so a plugin may
+// equally be a plain typed object.
 export function definePlugin(manifest: PluginManifest): PluginManifest {
   return manifest;
 }
 
-// A plugin id (its folder name) — lowercase a–z, digits, and dashes, dashes allowed anywhere.
-// Rejects uppercase, underscores, dots, slashes, spaces: the id forms the mount path `/<id>`,
-// the view/static namespace, and the central-override target, so it must stay URL/path-safe.
+// The id forms the mount path `/<id>`, the view/static namespace and the central-override target,
+// so it must stay URL/path-safe: no uppercase, underscores, dots, slashes or spaces.
 const PLUGIN_ID = /^[a-z0-9-]+$/;
 
 export function isValidPluginId(id: string): boolean {
   return PLUGIN_ID.test(id);
 }
 
-// Ids the host reserves for its own first-party mount segments (the gated /dashboard, the auth flows,
-// /auth/complete, /logout, the /oauth2 provider routes, the /public/ static). Plugin routes resolve
-// before these, so a folder named one of them would silently shadow a built-in route — discovery
-// refuses it, loud like any conflict. ("/" is owned by the `home` field, not a route, so it can't be
-// shadowed and needs no reservation.) Note `admin` is NOT reserved: the admin screens ship as a
-// drop-in plugin (examples/plugins/admin, mounted at /admin), not a built-in route.
+// Plugin routes resolve before the built-ins, so a folder named one of these would silently shadow
+// one — discovery refuses it. "/" is owned by the `home` field, not a route, so it needs no
+// reservation; `admin` is deliberately absent, the admin screens being a drop-in plugin.
 export const RESERVED_PLUGIN_IDS: ReadonlySet<string> = new Set([
   "auth", "dashboard", "login", "logout", "oauth2", "public", "recovery", "registration", "settings", "verification",
 ]);
@@ -127,14 +115,12 @@ export interface Semver {
   patch: number;
 }
 
-// The official semver.org 2.0.0 core regex (major.minor.patch, optional prerelease/build) — a
-// standardized parse with no dependency. We compare only major/minor for compatibility, so the
-// prerelease/build groups are matched (to accept valid input) but otherwise ignored.
+// The official semver.org 2.0.0 core regex. Only major/minor drive compatibility, so the
+// prerelease/build groups are matched to accept valid input but otherwise ignored.
 const SEMVER =
   /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
 
-// Parse a strict semver string → {major, minor, patch}, or null. Rejects ranges/prefixes
-// (`^1.2.3`, `v1`), leading zeros, whitespace and missing parts — fail loud over coerce.
+// Rejects ranges/prefixes (`^1.2.3`, `v1`), leading zeros and missing parts — fail loud over coerce.
 export function parseSemver(version: unknown): Semver | null {
   if (typeof version !== "string") return null;
   const m = SEMVER.exec(version);
@@ -147,9 +133,8 @@ export interface VersionCheck {
   message: string;
 }
 
-// Provider/consumer semver check (full table in README.md → Contract versioning): same major+minor → ok,
-// plugin minor < host → warn, else (newer minor, major mismatch, malformed) → refuse. Patch is
-// ignored. Discovery maps refuse→throw, warn→log.
+// Provider/consumer semver check (full table in README → Contract versioning). Discovery maps
+// refuse→throw, warn→log.
 export function checkApiVersion(pluginVersion: unknown, hostVersion: string = HOST_API_VERSION): VersionCheck {
   const plugin = parseSemver(pluginVersion);
   const host = parseSemver(hostVersion);
@@ -176,9 +161,8 @@ export interface PluginConflict {
   plugins: string[]; // unique ids involved
 }
 
-// The conflict rules: defined, loud resolution — never last-write-wins. Pure over the discovered
-// plugins; discovery throws on any "error" and logs every "warn". Mount-path (`/<id>`) uniqueness
-// is structural — it follows from the id check, so it needs no rule of its own. Shared permission
+// Loud resolution, never last-write-wins: discovery throws on any "error" and logs every "warn".
+// Mount-path uniqueness needs no rule of its own — it follows from the id check. Shared permission
 // names are the one intentional overlap, so they warn rather than error.
 export function findConflicts(plugins: Plugin[]): PluginConflict[] {
   const out: PluginConflict[] = [];
diff --git a/src/plugin-host/system.ts b/src/plugin-host/system.ts
index 4ffaf3c..34d5a18 100644
--- a/src/plugin-host/system.ts
+++ b/src/plugin-host/system.ts
@@ -10,11 +10,10 @@ import type { HydraAdmin } from "../auth/hydra-admin.ts";
 import type { KetoClient } from "../auth/keto-client.ts";
 import type { KratosAdmin } from "../auth/kratos-admin.ts";
 
-// Grouping criterion (keep this cohesive — it's a contract, so the "no catch-all bucket" rule that
-// governs folders governs this bag too): every field is a *privileged, host-owned, wire-dependent*
-// capability for administering Plainpages' own identity/permission stack. Add a field only when it
-// meets all three; if unrelated privileged concerns accrete (mailer, metrics, flags), sub-group
-// rather than pile them in flat.
+// Keep this cohesive — it is a contract, so the "no catch-all bucket" rule applies: every field is a
+// *privileged, host-owned, wire-dependent* capability for administering Plainpages' own
+// identity/permission stack. Add one only when it meets all three; sub-group rather than pile in
+// unrelated privileged concerns (mailer, metrics, flags).
 export interface SystemCapabilities {
   hydra?: HydraAdmin; // OAuth2 client admin (Hydra); present when the Hydra admin client is wired
   keto?: KetoClient; // relationship read/write (Keto); present when Keto is wired
diff --git a/src/ui/chrome.ts b/src/ui/chrome.ts
index f8f8ae5..24e1b04 100644
--- a/src/ui/chrome.ts
+++ b/src/ui/chrome.ts
@@ -1,9 +1,6 @@
-// Page chrome for plugin pages: the brand / global-nav / user / theme / csrf block a
-// plugin view hands to partials/shell so its page looks native — the same shell the dashboard and
-// every plugin renders. Pure; the host builds it per plugin request and exposes it on ctx.chrome.
-// nav is the global menu — Dashboard + every plugin's fragment (admin screens included, when the
-// admin plugin is installed) — run through composeNav (override + per-user filter) and
-// current-marked for the request path.
+// The brand / global-nav / user / theme / csrf block a view hands to partials/shell, exposed on
+// ctx.chrome. `nav` is the global menu — Dashboard plus every plugin's fragment — run through
+// composeNav (override + per-user filter) and current-marked for the request path.
 
 import type { User } from "../http/context.ts";
 import { ENGLISH } from "../i18n/english.ts";
@@ -13,9 +10,6 @@ import { composeNav, type NavNode } from "./nav.ts";
 import type { Plugin } from "../plugin-host/plugin.ts";
 import { branding, shellUser, type ShellUser } from "./shell-context.ts";
 
-// The "Dashboard" link to the gated app home (/dashboard). It targets a gated route, so it's shown
-// only to a signed-in user (an anonymous click would only dead-end at /login). Its label is a
-// catalog key — composeNav translates every label, and an unknown one renders as written.
 const DASHBOARD_NAV: NavNode = { href: "/dashboard", icon: "i-grid", id: "dashboard", label: "nav.dashboard" };
 
 export interface PageChrome {
@@ -41,13 +35,11 @@ export interface ChromeOptions {
 export function buildPluginChrome(opts: ChromeOptions): PageChrome {
   const t = opts.t ?? ENGLISH;
   const carryLocale = opts.localeHref ?? ((href: string) => href);
-  // The Dashboard link targets the gated /dashboard, so show it only to a signed-in user — to an
-  // anonymous visitor (a public page in the shell) it would only dead-end at /login. The admin
-  // section, when present, is just another plugin's nav fragment (examples/plugins/admin).
+  // Dashboard is gated, so an anonymous click would only dead-end at /login.
   const fragments: NavNode[][] = opts.user ? [[DASHBOARD_NAV]] : [];
   // A plugin's nav labels are keys in *its* catalog, so translate each fragment with that plugin's
-  // translator before they are merged. composeNav then runs the core one over the result for the
-  // built-in nodes and the central override's labels; already-translated text passes through it.
+  // translator before merging. composeNav then runs the core one over the result; already-translated
+  // text passes through it.
   for (const p of opts.plugins ?? []) {
     if (p.nav?.length) fragments.push(translateNav(p.nav, opts.translatorFor?.(p.id) ?? t));
   }
diff --git a/src/ui/nav.ts b/src/ui/nav.ts
index c39d9bc..9cf72f8 100644
--- a/src/ui/nav.ts
+++ b/src/ui/nav.ts
@@ -1,10 +1,7 @@
-// composeNav: merge each plugin's nav fragment into one tree, apply the central
-// override, then permission-filter per user. Pure and I/O-free — menu gating reads the JWT
-// `permissions` claim (README "The menu system"), never Keto. A node is visible iff it is `public`, or
-// declares no `permission`, or `permissions` includes that permission name; a gated header hides its whole
-// subtree, and a pure header left with no children is dropped. The config/menu.ts supplies
-// the override (+ branding); this helper only transforms data, so its result is per-deployment
-// up to the final permission filter and emits clean nodes ready for nav-tree.ejs (no id/permission).
+// composeNav: merge each plugin's nav fragment into one tree, apply the central override, then
+// permission-filter per user. Pure and I/O-free — menu gating reads the JWT `permissions` claim,
+// never Keto. A node is visible iff it is `public`, declares no `permission`, or the user holds that
+// name; a gated header hides its whole subtree, and a pure header left with no children is dropped.
 
 import { ENGLISH } from "../i18n/english.ts";
 import type { Translate } from "../i18n/translate.ts";
diff --git a/todo.md b/todo.md
index c3ae4db..735f9af 100644
--- a/todo.md
+++ b/todo.md
@@ -4,71 +4,66 @@
 
 - [ ] Add a way to configure plugins directly when installing. Most reasonable is an .env file in the plugin folder, I think, but I am open to suggestions.
 - [ ] Rename the plugin "admin" to something less generic, like "auth-admin" or "users-groups-admin".
-- [ ] Guard the group paths to self-lockout, or accept them explicitly. The self-revoke guard covers only your own *direct* grants on the Users screen; unticking a permission on a group you belong to, removing yourself from that group, or deleting it can all still strip your own effective access with no warning. Same scope the deleted Permissions screen had, and recorded in AGENTS.md as a known gap — the robust fix is a "last effective holder" check, which needs a reverse Keto query. Raised by the stability review 2026-08-05.
-- [ ] The permission picker has no concurrency baseline, so two operators editing the same user/group silently discard each other's change (standard lost-update on a set-based form — and the natural "two of us are onboarding the new hire" workflow produces exactly it). Sketch: post the rendered set as a hidden baseline; if it no longer matches Keto, re-render with "this changed while you had the page open" rather than applying. Fits the existing "the form is the whole truth" model instead of fighting it. Raised by the product review 2026-08-05.
-- [ ] A grant whose plugin was uninstalled is invisible and unremovable in the GUI. `grantDiff` deliberately never revokes an undeclared name (so an unrelated save can't drop it), but nothing *shows* it either — so it can't be audited or cleaned, and reinstalling that plugin silently reactivates access nobody remembers granting. Sketch: a read-only "held, but no installed plugin offers this" list with a remove action. Raised by the product review 2026-08-05.
-- [ ] A plugin may gate a route on a permission it never declares — declaring stays optional on purpose (mandatory declaration would warn on the legitimate cross-plugin sharing case). The cost is a dead end: the picker is built from declarations only, so that route is ungrantable from the GUI with no boot error, no warning, and a permanent 403 as the operator's only clue. Sketch: a discovery *warning* (not an error) naming the gated-but-undeclared permission. Raised by the product review 2026-08-05.
-- [ ] Saving permissions gives no confirmation, and a partial failure is silent. `applyGrants` loops writes then deletes with no transaction, so a Keto error midway leaves a half-applied set behind the generic error page; and a *successful* save is indistinguishable from "nothing changed" (PRG back to the same page, checkboxes as the only feedback). The `alert alert-pos` pattern the recovery-code banner uses is already available. Raised by the product review 2026-08-05.
-- [ ] Add the read-only operator to README → Overview's personas. `users:read` now makes a support/helpdesk account possible for the first time, and it is a distinct persona from the three listed (end user, non-technical user, plugin author) — the one whose screens must render without write affordances. Writing it down makes read-only rendering a stated requirement rather than something the next reviewer rediscovers. Raised by the product review 2026-08-05.
-- [ ] The seeded admin@plainpages.local are assigned twice to the permission "admin", should only be one, right? (the "admin" permission name can be switched after previous todos have been done)
+- [ ] Guard the group paths against self-lockout, or accept them explicitly. The self-revoke guard covers only your own *direct* grants on the Users screen; unticking a permission on a group you belong to, removing yourself from that group, or deleting it can all still strip your own effective access with no warning. Recorded in AGENTS.md as a known gap — the robust fix is a "last effective holder" check, which needs a reverse Keto query.
+- [ ] The permission picker has no concurrency baseline, so two operators editing the same user/group silently discard each other's change. Sketch: post the rendered set as a hidden baseline; if it no longer matches Keto, re-render with "this changed while you had the page open" rather than applying.
+- [ ] A grant whose plugin was uninstalled is invisible and unremovable in the GUI. `grantDiff` deliberately never revokes an undeclared name, but nothing *shows* it either — so it can't be audited or cleaned, and reinstalling that plugin silently reactivates access nobody remembers granting. Sketch: a read-only "held, but no installed plugin offers this" list with a remove action.
+- [ ] A plugin may gate a route on a permission it never declares — declaring stays optional on purpose. The cost is a dead end: the picker is built from declarations only, so that route is ungrantable from the GUI with no boot error and a permanent 403 as the operator's only clue. Sketch: a discovery *warning* (not an error) naming the gated-but-undeclared permission.
+- [ ] Saving permissions gives no confirmation, and a partial failure is silent. `applyGrants` loops writes then deletes with no transaction, so a Keto error midway leaves a half-applied set behind the generic error page; and a successful save is indistinguishable from "nothing changed". The `alert alert-pos` pattern the recovery-code banner uses is already available.
+- [ ] The seeded admin@plainpages.local is assigned twice to the same permission; should only be once.
 - [ ] In Playwright tests, try different resolutions and sizes, from BIG desktop down to tiny phone.
-- [ ] Decide whether `e2e-tests/` should be typechecked. It is outside `tsconfig.include`, so the gate never checks the most logic-bearing file in it (`console-guard.ts`) — Playwright strips its types without checking them. Including it needs the DOM lib and `@playwright/test` present wherever `npm run typecheck` runs, which today is the `web` image that installs neither. Raised by review 2026-08-05.
-- [ ] Decide whether Playwright's `workers` should be pinned. It is unset, so Playwright sizes the pool from `os.cpus()`, which reports the host's cores regardless of a container CPU quota — and with `retries: 0` a starved runner turns a slow test straight into a red gate rather than a retry. Fine on the current act_runner; revisit if CI ever runs constrained. Raised by review 2026-08-05.
-- [ ] Record the browser floor Plainpages actually requires, and whether the fallback is the contract or a courtesy. The stylesheet already needs `:has()` (Dec 2023); the menus now need the popover API (Safari 17, Sep 2023) and CSS anchor positioning for placement (newer still, and unguarded — the `@supports` test covers popover only). An iPadOS 16 tablet — capped at Safari 16, and exactly the "tablet on a factory floor, old thin client at a reception desk" README → Overview sells the zero-JS stance on — therefore gets panels flowing inline rather than working menus. Either state a supported floor in the README or accept the fallback as the answer for those devices; nobody has rendered that path on real hardware. Raised by the architecture review 2026-08-05.
-- [ ] Decide whether the profile dropdown still earns a dropdown. With the dead Profile link gone it holds one item, Sign out, behind a click — and its "Signed in as X" head only repeats the name and email the trigger already shows. Either put Sign out in the footer directly, or give the menu a second reason to exist. Overlaps the outside-click item above. Raised by review 2026-08-05.
-- [ ] When copy+paste the verification code from the email, it doesn't work because it does not trim whitechars around the code in the form. It should trim automatically.
-- [ ] Guard against the double-clicked submit, without client-side JavaScript. The README's non-technical persona double-clicks a button that doesn't respond instantly, so a second identical POST is an expected event, not misuse — today it creates two users, mints two recovery codes, or registers two OAuth2 clients. Constraints: HTML/CSS only (no client JS — priority: zero-JS spine), and it must not break an action that is *legitimately* repeatable (an increase-by-one button is not a duplicate, it is two increments). Sketch to evaluate: a CSS-only affordance so the second click has nothing to hit (`:active`/`:focus` state, or the submit visually and semantically settling), paired with the host recognising a duplicate on the server — same session, same route, same payload, within a short window — and then logging it and dropping the second rather than replaying it. Open questions: what identifies "the same submission" (a one-time token minted into each rendered form is stronger than hashing the payload, and the CSRF plumbing already mints per-request tokens), how long the window is, where the record lives given the app is stateless (in-memory like the revoke denylist, or push it to the upstream the plugin already writes to), and how a plugin declares a route as repeatable — an opt-out on the route, or opt-in per form. Raised 2026-08-04 with the personas.
-- [ ] Decide the caching contract for rendered pages. Responses now carry `Vary: Accept-Language` (they content-negotiate), but nothing sets `Cache-Control` — so a shared cache in front of the app has no instruction, and a signed-in page is not marked `private`. Pre-existing, surfaced by the i18n review 2026-08-03: either set the headers deliberately (public pages cacheable, gated pages `private, no-store`) or record in AGENTS.md that the reverse proxy owns this.
-- [ ] Decide whether the single generic Keto `Resource` namespace should become per-domain namespaces (`Shift`, `Document`, …), as Ory's own examples model it. One global `Resource` bucket is the project's own "no catch-all names" rule (`utils`, `helpers`, `misc`) applied to namespaces. Raised 2026-08-03; a design question, not a naming one.
-- [ ] Decide what `ICON_NAMES` (`src/ui/icons.ts`) actually is. Its comment says "the icons the UI actually references", but `i-chart`, `i-copy`, `i-download` and `i-sliders` have no caller anywhere — so either they go the way `i-gear` just did, or the comment should say the palette is curated and may carry an id ahead of its first use. Not cosmetic: the sprite is inlined into every page, and the rule decides whether a future removal is routine cleanup or a plugin-facing regression (see AGENTS.md → the `ICON_NAMES` deviation). Pre-existing, surfaced by the review 2026-08-05.
-- [ ] Decide (once) whether the CSRF token staying unbound to `sub`/session is accepted. `src/auth/csrf.ts` signs `<nonce>.<HMAC(secret, nonce)>` with no session binding, so any validly-signed token passes for any user — an attacker who can write cookies on the origin (a sibling subdomain, or a plaintext hop with `SECURE_COOKIES=false`) can fix a token they know. Standard for unbound signed double-submit and plausibly fine behind `SameSite=Lax` + HSTS. Accepted ⇒ record it in AGENTS.md → "Deliberate architectural deviations" and in README → Security model under "Not guaranteed"; not accepted ⇒ bind the nonce to `sub` (small change). Raised by review 2026-08-02; left undecided because it is a maintainer call, and an undocumented exception reads as a bug to the next reviewer.
-- [ ] Verify the documented Docker commands on macOS and fix whatever misbehaves — **macOS is a supported dev host** (maintainer, 2026-08-05), but nothing here has been run on one. Two known suspects, both from the `--user "$(id -u):$(id -g)"` idiom the E2E runner and the lockfile edit share: a macOS `id -g` is `20`, which is `dialout` inside the noble image rather than a user group, and Docker Desktop remaps bind-mount ownership in its own VM layer, so "the file belongs to you afterwards" may hold for a different reason or not at all. The same question covers rootless Docker, where README already says to *drop* the flag. Raised by the stability review 2026-08-05.
+- [ ] Decide whether `e2e-tests/` should be typechecked. It is outside `tsconfig.include`, so the gate never checks its most logic-bearing file (`console-guard.ts`). Including it needs the DOM lib and `@playwright/test` present wherever `npm run typecheck` runs, which today is the `web` image that installs neither.
+- [ ] Decide whether Playwright's `workers` should be pinned. Unset, it sizes the pool from `os.cpus()`, which reports the host's cores regardless of a container CPU quota — and with `retries: 0` a starved runner turns a slow test straight into a red gate. Fine on the current act_runner; revisit if CI ever runs constrained.
+- [ ] Record the browser floor Plainpages requires, and whether the fallback is the contract or a courtesy. The stylesheet needs `:has()` (Dec 2023); the menus need the popover API (Safari 17) and CSS anchor positioning for placement (newer still, and unguarded — the `@supports` test covers popover only). An iPadOS 16 tablet, capped at Safari 16, therefore gets panels flowing inline rather than working menus. Either state a supported floor or accept the fallback for those devices; nobody has rendered that path on real hardware.
+- [ ] Decide whether the profile dropdown still earns a dropdown. It holds one item, Sign out, behind a click, and its "Signed in as X" head repeats what the trigger already shows.
+- [ ] Trim whitespace around the verification code in the form — a copy+pasted code from the email currently fails.
+- [ ] Guard against the double-clicked submit, without client-side JavaScript. The non-technical persona double-clicks a button that doesn't respond instantly, so a second identical POST is an expected event, not misuse — today it creates two users, mints two recovery codes, or registers two OAuth2 clients. Constraints: HTML/CSS only, and it must not break an action that is *legitimately* repeatable. Sketch: a CSS-only affordance so the second click has nothing to hit, paired with the host recognising a duplicate on the server — same session, route and payload within a short window — then logging and dropping it. Open questions: what identifies "the same submission" (a one-time token minted into each rendered form beats hashing the payload, and the CSRF plumbing already mints per-request tokens), the window length, where the record lives given the app is stateless, and how a plugin declares a route repeatable.
+- [ ] Decide the caching contract for rendered pages. Responses carry `Vary: Accept-Language` but nothing sets `Cache-Control`, so a shared cache has no instruction and a signed-in page is not marked `private`. Either set the headers deliberately (public cacheable, gated `private, no-store`) or record in AGENTS.md that the reverse proxy owns this.
+- [ ] Decide whether the single generic Keto `Resource` namespace should become per-domain namespaces (`Shift`, `Document`, …), as Ory's own examples model it. One global `Resource` bucket is the project's own "no catch-all names" rule applied to namespaces. A design question, not a naming one.
+- [ ] Decide what `ICON_NAMES` (`src/ui/icons.ts`) actually is. `i-chart`, `i-copy`, `i-download` and `i-sliders` have no caller anywhere — so either they go, or the comment should say the palette is curated and may carry an id ahead of its first use. Not cosmetic: the sprite is inlined into every page, and the rule decides whether a future removal is routine cleanup or a plugin-facing regression.
+- [ ] Decide (once) whether the CSRF token staying unbound to `sub`/session is accepted. `src/auth/csrf.ts` signs `<nonce>.<HMAC(secret, nonce)>` with no session binding, so any validly-signed token passes for any user — an attacker who can write cookies on the origin can fix a token they know. Standard for unbound signed double-submit and plausibly fine behind `SameSite=Lax` + HSTS. Accepted ⇒ record it in AGENTS.md and README → Security model; not accepted ⇒ bind the nonce to `sub`.
+- [ ] Verify the documented Docker commands on macOS and fix whatever misbehaves — **macOS is a supported dev host**, but nothing here has been run on one. Two suspects, both from the `--user "$(id -u):$(id -g)"` idiom: a macOS `id -g` is `20`, which is `dialout` inside the noble image rather than a user group, and Docker Desktop remaps bind-mount ownership in its own VM layer. The same question covers rootless Docker, where README already says to *drop* the flag.
 
 ### Architectural review findings (2026-07-02)
 
-Prioritized. Overall verdict: architecture is sound (contract-first plugin API, functional core/imperative shell, strong test seams); these are refinements.
+Prioritized. Overall verdict: architecture is sound; these are refinements.
 
-- [ ] **MEDIUM — Add complexity/method-size static analysis to the CI gate.** Only `tsc --strict` today; a size/complexity rule would have caught the `app.ts` growth. Also when wiring CI/CD: keep the merge gate fast (typecheck + units + Ory-free `visual` suite; heavy e2e suites required-but-separate) and make the pipeline the only path to a published image (build once at tag, promote).
-- [ ] **LOW — The users list offers a pencil "Edit" row action to a `users:read` holder.** The link is harmless (it opens the read-only detail page), but the label contradicts what the reader can do. Needs `canWrite` threaded into `listTable` plus a `common.view` core catalog key and an `i-eye` entry in `ICON_NAMES` — a core registry change for a cosmetic fix, so it was left out of the permission-naming branch. Raised by the stability review 2026-08-05.
-- [ ] **MEDIUM→LOW — Add a list-page view-model helper in `src/ui/`.** Every list screen (users, groups, clients, shifts) hand-rewrites the same ~40 lines bridging `parseListQuery`/`paginate` to the EJS partials; at minimum a `buildPaginationModel(page, hrefFor)` block.
-- [ ] **LOW→MEDIUM — Retire `src/ui/shell-context.ts`.** `ShellModel`/`buildShellContext` has one consumer left (dashboard) and duplicates `PageChrome` on almost every field, incl. identical brand-assembly in `chrome.ts` and `shell-context.ts`. Fold the dashboard onto `ctx.chrome` + title/breadcrumbs; keep `shellUser` as the shared primitive.
+- [ ] **MEDIUM — Add complexity/method-size static analysis to the CI gate.** Only `tsc --strict` today; a size/complexity rule would have caught the `app.ts` growth.
+- [ ] **LOW — The users list offers a pencil "Edit" row action to a `users:read` holder.** The link is harmless (it opens the read-only detail page), but the label contradicts what the reader can do. Needs `canWrite` threaded into `listTable` plus a `common.view` core catalog key and an `i-eye` entry in `ICON_NAMES`.
+- [ ] **MEDIUM→LOW — Add a list-page view-model helper in `src/ui/`.** Every list screen hand-rewrites the same ~40 lines bridging `parseListQuery`/`paginate` to the EJS partials; at minimum a `buildPaginationModel(page, hrefFor)` block.
+- [ ] **LOW→MEDIUM — Retire `src/ui/shell-context.ts`.** `ShellModel`/`buildShellContext` has one consumer left (dashboard) and duplicates `PageChrome` on almost every field. Fold the dashboard onto `ctx.chrome` + title/breadcrumbs; keep `shellUser` as the shared primitive.
 - [ ] **LOW — Fix stale doc references to removed `docs/plugin-contract.md`** in `views/index.ejs` (user-visible dashboard text; also links /scheduling as if pre-installed) and `examples/plugins/scheduling/views/shifts.ejs`.
-- [ ] **LOW — Decide (once) on a `ctx.system` facade.** `#plugin-api` exposes raw Ory client shapes, so an Ory client refactor is a major `apiVersion` bump. AGENTS.md accepts this; revisit only if external plugin authors appear. Record the decision.
-- [ ] **LOW — README/AGENTS.md gaps:** state the intended lifetime/horizon explicitly, add a short domain glossary (host, manifest, chrome, nav fragment, permission token, system plugin, denylist…), and note the expected plugin-author population (first-party vs external) to justify the versioning machinery.
+- [ ] **LOW — Decide (once) on a `ctx.system` facade.** `#plugin-api` exposes raw Ory client shapes, so an Ory client refactor is a major `apiVersion` bump. AGENTS.md accepts this; revisit only if external plugin authors appear.
+- [ ] **LOW — README/AGENTS.md gaps:** state the intended lifetime/horizon explicitly, add a short domain glossary (host, manifest, chrome, nav fragment, permission token, system plugin, denylist…), and note the expected plugin-author population.
 
 ## Finnished work
 
-- [x] `e2e-tests/artifacts/` is written `root:root` into the checkout and needs `sudo` to delete — the Playwright container runs as root. Unlike the node_modules mountpoint, a container `user:` would fix it, but compose has no `$UID` of its own (needs an `.env` or `id -u` via `ci.sh`) and CI's artifact upload reads that dir. Found 2026-08-05. (Fixed with the idiom README already uses for a lockfile edit — every documented invocation passes `--user "$(id -u):$(id -g)"`: the five compose headers, the five README blocks and `ci.sh`'s two runs — so the runner writes as whoever started it, on a dev box and on a CI runner alike, and compose never needs a `$UID` of its own. Two things had to come with it. `e2e-tests/artifacts/` is now *tracked* (`.gitkeep`), because an absent bind-mount source is created by the daemon as root and an unprivileged runner then cannot write into it at all — the same trap the node_modules mountpoint hit, one layer up. And the runner image sets `HOME=/tmp` + `npm_config_cache=/tmp/.npm`, since an arbitrary uid has no home in the Playwright image. Baking a `USER` into the image was tried first and dropped: `pwuser` is **1001** in the noble image (uid 1000 is `ubuntu`), so it `EACCES`'d on a 1000-owned checkout, and no fixed uid can match every host. One premise turned out stale — no workflow uploads artifacts, so nothing in CI reads that dir. Verified by running the visual suite as uid 1000: 36 tests green across Chromium, Firefox and WebKit, every file written `lilleman:lilleman` and deletable without `sudo`, which this box does not even have. `src/compose.test.ts` guards every documented command plus the tracked mount point; `src/ci-gate.test.ts` guards the gate's own two.)
-- [x] node_modules gets installed straight to the root folder with root permissions, it should at the very least be same owner as the one running the docker process, or built inside the docker image. (It *was* built in the image; the checkout got an empty root-owned dir — the mountpoint for `compose.override.yml`'s `- /app/node_modules` volume. Re-owning it is impossible (the daemon creates mount destinations as root whatever `--user` says), so deps moved to `/node_modules` above `WORKDIR /app` and the volume is gone. See AGENTS.md.)
-- [x] Document permissions format so it is folled going forward: <resource>:<action>, for example scheduling:read. Permission "admin" does not match this, and needs to be users:read, users:write, groups:read, groups:write. (README → [Naming a permission](README.md#naming-a-permission) is the one home for the rule, and the host *enforces* it at discovery — `isValidPermissionName` in `src/plugin-host/plugin.ts`, checked by `shapeError` over every route/nav `permission` and every declared name — so a badly-named permission stops the boot like any other bad manifest, for every plugin rather than only ones the admin GUI touches. `admin` is gone, split per screen into `users:`, `groups:` and `oauth2-clients:` × `read`/`write`. The read/write split is real, not cosmetic: `users:read` opens the list and is refused on every POST, and the Admin nav header lost its own gate so each screen is filtered by its own `:read` — hold none of the three and `composeNav` drops the emptied header (which needs the header to carry no `href`, now asserted). Two things had to be fixed to get here. The permission path validator was the *group* regex with no colon, so `/admin/permissions/scheduling:read` already 404'd. And `ADMIN_PERMISSIONS` defaulting to empty exposed that `bootstrap` never bind-mounted `plugins/` at all — it discovered only the image's empty copy, so a dropped-in plugin's permissions were never seeded; the mount lives in `compose.override.yml` (dev-only, mirroring `web`'s `.:/app`) because the base file gives both services the same baked copy and a base-file mount would collide with the e2e stacks that bind plugins *inside* that path. Quick start now says `docker compose up -d`, which re-runs the one-shot. Verified end to end on a live stack.)
-- [x] Permissions should be a list in code. Since no permissions exists in the database out of the box, but there are a fixed number of permissions in the plugins that the end consumer and user of plain pages can use, these permissions must surface to the UI somehow. The effects is that the permissions page should be deleted completely, and the users and groups pages should gain the functionality to add permissions to their things instead, provided the user have the right permissiosn to do so, of course. Run the product reviewer agent on this todo also. (The host collects every installed plugin's declarations into one catalog — `declaredPermissions()` → `ctx.declaredPermissions`, deduped and sorted, computed once at wiring — and that catalog *is* the fixed list. The Permissions screen is deleted outright: its module, tests, three views, two partials and 29 catalog keys per locale. Users and Groups each gained a checkbox list of the catalog, ticked where held; the whole set posts back, so what is submitted is the desired state and `grantDiff` turns it into grants + revokes. Two properties earn their tests: a crafted POST cannot grant a name no plugin declares, and a held-but-undeclared name — left over from an uninstalled plugin — is never silently revoked by an unrelated save, since the picker only speaks for what it showed. A user's own change revokes their live tokens; a group's reaches members at their next re-mint, the documented transitive lag. Keto stays optional on the Users screen: without it the page still lists and edits, minus the picker. Maintainer's call 2026-08-05 to keep the OAuth2-clients screen and gate it `oauth2-clients:read/write` — permissions and OAuth2 are orthogonal, scopes say what an *app* may see and permissions what a *user* may do, so the screen only ever needed *a* gate.)
-- [x] In Playwright tests, check for warnings and errors in all browsers on all the steps. If they exist, that is a failure we need to fix. (Every spec takes its `test` from `e2e-tests/console-guard.ts`, which watches every page a test opens — `console.error`, `console.warning`, and uncaught page errors — and fails the test that provoked one, at whatever step. The bar is zero rather than a curated tolerance list: the app ships no client JavaScript, so a message means a broken sub-resource, a rejected attribute, or an engine refusing a feature. Two narrow escapes, both explicit: the COOP header Chromium drops because the e2e stacks serve plain http over container hostnames (a deployment serves https, where it applies), and per-test `allowConsole(/…/)` — used once, by the 404 spec, whose own navigation Chromium and WebKit log. **All browsers** is now literal for the Ory-free suites: `visual.spec.ts` + `language.spec.ts` run in Chromium, Firefox *and* WebKit — the per-test `@engines` tag is gone, and screenshots are written per project so the three don't fight over one file — which is what makes an engine-specific message visible at all. The Ory-backed suites write users, groups and sessions to one shared backend, so they stay on Chromium; widening them needs a stack per engine. Nothing in the app had to be fixed: the sweep found only the two above. Verified by negative control — an injected `console.warn` failed the test in all three engines and an injected `console.error` failed on full-flow's shared serial page — which also caught the guard registering that page twice. `src/e2e-console-guard.test.ts` locks the wiring in the *unit* gate, since a spec importing `test` straight from Playwright would run unwatched and green.)
-- [x] Don't run tests when only markdown files in the root have changed. (Already shipped for *any* `*.md`, anywhere in the tree — `ci.sh`'s `docs_only()` no-ops the gate when every path changed since `main` ends in `.md`, and the workflow still pushes the commit-hash image so a merged docs commit stays releasable. Kept wider than "in the root" deliberately: no test reads a markdown file, so a nested `examples/plugins/admin/README.md` edit is as safe to skip as `README.md`, and narrowing it would spend the full gate on one. What was actually broken was rename detection — `git mv src/app.ts notes.md` names only the destination under `git diff --name-only`, and collapses to a single `R src/app.ts -> notes.md` line under `git status --porcelain`, so **moving code onto a `.md` path skipped the gate over a source file that was gone**. Both channels now pass `--no-renames`; verified against a scratch repo across ten scenarios — docs-only, mixed, empty diff, dirty tree, untracked code, deleted doc, and the rename staged *and* committed — the last two failing before the fix and passing after. `src/ci-gate.test.ts` locks both flags; it stays a text guard because the test image is `node:alpine` with neither `git` nor `bash`.)
-- [x] The little menues, like when choosing language or clicking my username, they do not dissapear when clicking outside them, I must click the original trigger or choose something. See if there are more modern ways of handling this with HTML and CSS. I think there is a modal-thing or something? (The modern thing is the **Popover API**. All three popup menus — language picker, profile, row kebab — are now a `<button popovertarget>` plus a `[popover]` panel instead of `<details>`/`<summary>`, so the browser owns open/close: clicking anywhere outside dismisses one, `Esc` dismisses it and returns focus to the trigger, opening one closes the others, and the panel sits in the top layer where `.table-wrap`'s `overflow` can no longer clip a row kebab. Placement is CSS anchor positioning; the panel needs `position-anchor: auto` to bind to the button that opened it — a bare `anchor()` resolves to nothing in Chromium, Firefox and WebKit alike, measured in all three before picking the approach. `data-table.ejs` stopped hand-rolling its kebab and calls the `menu` partial, so the pattern lives in one file. Each panel is named by its caller (`locale-menu`, `profile-menu`, `row-actions-1`) and the partial fails loud without an `id`, since `popovertarget` is an idref — generated ids were tried first and dropped for being unreadable and nondeterministic. `<details>` stays in the nav tree, where it means disclosure rather than popup. A browser older than the popover API flows each panel inline under its trigger, so Sign out is never stranded behind an inert button. `e2e-tests/visual.spec.ts` drives the whole behaviour — opens, anchored to its trigger, outside-click, Esc — and runs in Firefox and WebKit as well as Chromium, because CSS anchor positioning is the newest thing in the app and every popup rests on it. Decisions recorded in AGENTS.md.)
-- [x] Organize the files in src in to folders so it is easier to understand the structure of the code.
+- [x] Run the E2E runner as the invoking user so its artifacts aren't root-owned.
+- [x] Install node_modules above `WORKDIR /app` so no mount leaves a root-owned dir in the checkout.
+- [x] Enforce `<resource>:<action>` permission names at discovery; split `admin` per screen.
+- [x] Make the declared-permission catalog the fixed list; delete the Permissions screen, move granting onto Users and Groups.
+- [x] Fail a Playwright test on any browser console warning, error or uncaught exception, in every engine.
+- [x] Skip the CI gate when only markdown changed.
+- [x] Replace the `<details>` popup menus with the Popover API so an outside click dismisses them.
+- [x] Organize the files in src into folders.
 - [x] Move docs/plugin-contract.md into README.md and remove the docs folder.
-- [x] The plugins/scheduling is an example and shouldn't be committed to the plugins directory since that should be empty to be able to be mounted in via docker or other means for the users/develoeprs using this application/framework. Put it in the examples folder instead.
-- [x] The config folder should be empty and the current settings in the menu.ts should be the fallback default. IF a menu.ts where to appear in that folder, it should override the default settings with whatever is in it. The idea is the folder should be empty by default and you mount it in your docker container with your config.
-- [x] Make the internal admin pages for users groups etc into a plugin instead in the examples folder and remove them from the internal source. Add a part in the quick start about copying this plugin into the plugins folder to enable GUI user- and group admining.
-- [x] CI/CD - Test on push to any branch except main. (`.gitea/workflows/ci.yml` runs `bash ci.sh`; the one-time act_runner setup it needs is documented in README → CI/CD.)
-- [x] CI/CD - Require PR to main and don't allow merge if tests does not pass. Only allow linear history and history that leaves the last commit hash on main the exact same as on the branch we just merged in. (Gitea branch protection on main + fast-forward-only merge style, set via API; documented in README → CI/CD.)
-- [x] CI/CD - Sync up to github after every successful merge to main, URL: git@github.com:larvit/plainpages.git - also note the true home top of the README. Force push to github, it should only ever be a mirror of the gitea.larvit.se repository. (`.gitea/workflows/mirror.yml` force-pushes main + tags over HTTPS with a dedicated account's PAT in the `MIRROR_GITHUB_TOKEN` secret; setup documented in README → CI/CD.)
-- [x] CI/CD - Build docker images as part of the requirements to be able to merge to main. Push them with the git commit hash as docker tag. Push to container registry at Gitea. (`ci.yml` builds + pushes `gitea.larvit.se/larvit/plainpages:<commit hash>` after a green gate — with ff-only merges that is the main commit's image; auth via the `DOCKER_REGISTRY_USER` variable + `DOCKER_REGISTRY_TOKEN` secret, retention via an org cleanup rule; documented in README → CI/CD.)
-- [x] CI/CD - Re-tag docker images from git hash to semver when a semver git tag is pushed. (`release.yml` on a `vX.Y.Z` tag pulls the commit-hash image and re-tags it `X.Y.Z`/`X.Y`/`X`/`latest`, failing loud if the gated image is missing; tag pushes also trigger the GitHub mirror; documented in README → CI/CD.)
-- [x] CI/CD - Sync docker images to docker hub after each re-tag to git tags. (`release.yml` pushes the same `X.Y.Z`/`X.Y`/`X`/`latest` tags to `docker.io/larvit/plainpages` after the Gitea re-tag — releases only, no hash tags; auth via the `DOCKERHUB_USER` variable + `DOCKERHUB_TOKEN` secret; documented in README → CI/CD.)
-- [x] Write a short text on how to use this docker image to publish on docker hub and save it to README-dockerhub.md (tagline, tags, clone-free quick start — the image ships the Ory config, extracted via `docker run … tar` + a self-contained compose.yml — env table, first plugin; pasted into the Docker Hub overview by hand — noted in README → CI/CD.)
-- [x] CI/CD - Setup renovate bot. Check how other repos on this Gitea is setup you can get access to, there should be a number of renovate bot activated ones. (`renovate.yml` runs the self-hosted `renovate/renovate` image nightly against `renovate.json` — this repo only, via the shared `renovate@larvit.se` bot + `RENOVATE_TOKEN` secret, mirroring the `pwrpln/core` pattern; standard managers cover npm/Dockerfiles/compose/gitea-action pins, two custom regex managers cover the image tags embedded in workflow `run:` steps, the Ory + Playwright lockstep sets are grouped, every bump stays an exact pin, and each PR automerges once the gate is green; documented in README → CI/CD.)
-- [x] CI/CD - Renovate: set a read-only `GITHUB_COM_TOKEN` env in `renovate.yml` so Renovate stops hitting github.com rate limits when resolving github-hosted deps (Playwright, lucide, `actions/checkout`) and can fetch changelogs. Non-blocking refinement; needs a read-only GitHub PAT stored as an Actions secret. (The renovate job forwards the `RENOVATE_GITHUB_TOKEN` secret — a scopeless read-only github.com PAT; Gitea rejects `GITHUB_`-prefixed secret names — into the container as `GITHUB_COM_TOKEN`; documented in README → CI/CD.)
-- [x] CI/CD - When renovate updates a dependency - also release a new version of plainpages based on what got updated with Renovate. Major typescript? New apiVersion + new major. A tiny patch to ejs? Only patch release etc. Before implementing, explain in detail how you will solve this. (`renovate.yml` gains an `auto-release` job (`needs: renovate`) that cuts one `vX.Y.Z` tag per run for what Renovate merged; level = highest `Release-Bump:` trailer Renovate stamps via `commitBody`, any dep's major/minor/patch mapped straight through (default patch). Decoupled from `apiVersion` (tag-only, `HOST_API_VERSION` untouched — a "major" is just a bigger image tag, never a plugin break); pre-1.0 shifts down so nothing auto-crosses into 1.0.0. Pure `auto-release/next-version.ts` + unit tests; tag pushed with renovate-bot's PAT so `release.yml` fires; documented in README → CI/CD.)
-- [x] Add an e2e test for the admin plugin's OAuth2-clients (Hydra) screen. The full-flow e2e suite runs without Hydra (compose.full.yml), so /admin/clients register/detail/delete is only unit-covered (src/http/app.test.ts); wire Hydra into an e2e stack and drive the screen in the browser. (compose.full.yml now includes Hydra (`serve all --dev`) and full-flow.spec.ts drives /admin/clients register → one-time secret → list → detail → delete in the browser; documented in README → Testing.)
-- [x] Build and publish docker image as CI/CD. (Duplicate of the CI/CD items above: `ci.yml` builds and pushes `gitea.larvit.se/larvit/plainpages:<commit hash>` behind the green gate, `release.yml` re-tags it to semver and syncs those tags to Docker Hub.)
-- [x] The human developer understands the security model in the auth in this project. (Two README sections. [Users, groups & permissions](README.md#users-groups--permissions) carries the weight: the entity model, a worked graph, a per-route can/cannot walkthrough, and the trap that a per-row grant never widens a coarse gate — placed before Building plugins because a manifest's `permission:` gate is unreadable without it. [Security model](README.md#security-model) is deliberately short, only the facts a deployment gets wrong without them: the private network as the *only* guard on the Ory APIs, signed-not-encrypted claims, the 30-day Kratos session behind the ~10m JWT, and non-instant offboarding. The first attempt answered the *threat* model instead — a 12-row attack/defense table — which was the wrong question and mostly restated code readable at its source; cut. Also corrected the hardening checklist: `REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`, so the committed Kratos/Hydra/Postgres/demo-admin secrets are now listed in "What you must supply". The mandatory-`exp` guard gained a test in `src/auth/jwt-middleware.test.ts`.)
-- [x] Add i18n support. (Catalogs are TS modules per locale — `src/i18n/locales/<tag>.ts` for the host, `plugins/<id>/i18n/<tag>.ts` for a plugin, looked up plugin-first then core; en-US + sv-SE ship. A request is served by `?locale=sv-SE` → `Accept-Language` → `en-US`, exact on a full tag but a lone language takes the first regional catalog; no cookie — when the URL asked, the host carries `?locale` onto the links it renders and `ctx.localeHref()` does it for a plugin's. `ctx.t(key, vars)` plus `t`/`locale`/`locales`/`localeHref`/`dir` merged into every view (any include depth); `{{var}}` interpolation, plurals via `Intl.PluralRules`, an unknown key renders as itself — which is what makes a nav label either a key or plain text. Every catalog is checked against its set's en-US at boot (keys, kind, plural categories) and a mismatch stops startup. Kratos' own flow text is mapped by its numeric id (only ids verified against the live stack; its generic trait-label id is deliberately unmapped, field labels key on the input name instead). Zero-JS language picker in the shell + the auth/consent pages, `<html lang dir>` from the locale. Core, both example plugins and their views translated; unit tests + `e2e-tests/language.spec.ts` in the visual gate; documented in README → Languages, decisions in AGENTS.md.)
-- [x] Settle the identity-vs-user vocabulary. (Plainpages says **user** everywhere — Keto namespace `User`, subjects `user:<kratos-id>`, `ctx.user`. Ory calls the record an "identity", but its own docs say it uses that term interchangeably with "users"/"accounts", so this is house style rather than a renamed concept, and "user" is the word readers know (Nielsen heuristic #2). README → Auth carries one note recording the mapping; the only place Ory's spelling survives is the `Identity` DTO in `src/auth/kratos-admin.ts`, which mirrors the Kratos wire shape. Recorded in AGENTS.md.)
-- [x] On the first page there is a button saying "Log in" and in the bottom left corner another button says "Sign in". Use a uniform language. (English now says **sign in / sign out / create account** everywhere; Swedish was already uniform. Three outliers went: the landing's `landing.signIn` "Log in", the registration submit `kratos.1040001` "Sign up" — under a "Create account" heading, and sv-SE already said "Skapa konto" — and `oauth.logoutExpired`'s "This logout request", whose sign-in twin said "sign-in request". The first-run banner says "sign in at" too, and the admin example's email hint says "the sign-in identifier". The rule is recorded in AGENTS.md → Rules and held by the author: a unit test asserting the verb shipped first and was dropped on the maintainer's call, since a build that fails on a word removes the judgment a growing UI needs. The two e2e specs that clicked "Log in" now scope to `#main-content`, since the anonymous sidebar carries a "Sign in" link of its own.)
-- [x] When logged in, there is a "profile" link in the little box when I've clicked my username in the bottom left corner. There is no profile, so the link is dead. Remove it. (The `<button type="button">` in the sidebar's profile menu had no handler and — zero-JS spine — could never get one; gone from `views/partials/shell.ejs` along with the `shell.profile` key in both locales. Sign out is now the menu's only item; the profile block itself (avatar, name, email) is the summary and stays. `src/ui/shell.test.ts` asserts the menu holds no dead `type="button"`, and `e2e-tests/full-flow.spec.ts` asserts Sign out is the only item once the dropdown is open.)
-- [x] There is a "Settings" in the bottom left (a little cog) showing a "Preferences" in a little menu when clicked. That is not in any spec, it exists when not even logged in and erh. Just remove. (Dropped from the sidebar footer in `views/partials/shell.ejs`, which now carries the profile menu — or Sign in when anonymous — plus the language picker. The `shell.settings`/`shell.preferences` catalog keys went with it in both locales, as did the then-unreferenced `i-gear` icon: `ICON_NAMES` is by definition the icons the UI references, so `views/partials/icons.ejs` was regenerated from it. Kratos' own `/settings` account flow is a different thing and is untouched. Covered by `src/ui/shell.test.ts` signed-in and anonymous, plus the public-landing case in `e2e-tests/visual.spec.ts`.)
-
-### Architectural review findings (2026-07-02)
-
-- [x] **HIGH — Split `handleRequest` in `src/http/app.ts` (~380 lines).** It mixes the request pipeline with inline implementations of ~10 built-in endpoints (Kratos flows, /oauth2/*, /auth/complete, /logout, /, /dashboard, 404/405). Extract each endpoint into a named handler (auth/OAuth2 group → `src/auth/` route module) with the same `(req, res, ctx)` shape plugin routes use; reduce `handleRequest` to pipeline → internal route table → `sendResult`.
+- [x] Move the scheduling example out of `plugins/` into `examples/`.
+- [x] Make `config/` an empty drop-in mount with the defaults as fallback.
+- [x] Turn the built-in admin pages into a drop-in example plugin.
+- [x] CI/CD — test on push to any branch except main.
+- [x] CI/CD — require a PR to main, gated on a green build, fast-forward-only.
+- [x] CI/CD — force-push mirror to GitHub after every merge to main.
+- [x] CI/CD — build and push the app image, tagged with the commit hash, as part of the gate.
+- [x] CI/CD — re-tag the hash image to semver on a `vX.Y.Z` tag.
+- [x] CI/CD — sync released tags to Docker Hub.
+- [x] Write README-dockerhub.md for the Docker Hub overview.
+- [x] CI/CD — set up the Renovate bot.
+- [x] CI/CD — give Renovate a read-only `GITHUB_COM_TOKEN` so github.com lookups aren't rate-limited.
+- [x] CI/CD — auto-release on Renovate updates, versioned from the `Release-Bump:` trailer.
+- [x] Add an e2e test for the admin plugin's OAuth2-clients (Hydra) screen.
+- [x] Document the auth security model in the README.
+- [x] Add i18n support.
+- [x] Settle the identity-vs-user vocabulary.
+- [x] Use one uniform verb per action in the English UI (sign in / sign out / create account).
+- [x] Remove the dead "Profile" link from the sidebar profile menu.
+- [x] Remove the unspecified "Settings"/"Preferences" cog from the sidebar footer.
+- [x] **HIGH — Split `handleRequest` in `src/http/app.ts`** — extract the built-in endpoints into named handlers on an internal route table.