Cut non-essential prose from docs and comments, and require the same of every future change

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.

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"] });

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(","));

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

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";

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" });