Record the comprehension check: paired ruling better for PR #184

.gitea/workflows/registry-cleanup.yml

@@ -19,4 +19,4 @@ jobs:
         run: |
           docker run --rm -v "$PWD:/repo" -w /repo \
             -e REGISTRY_TOKEN -e REGISTRY_USER -e REPO_TOKEN -e REPOSITORY -e SERVER_URL \
-            node:26.13.0-alpine3.24 node registry-cleanup/cleanup.ts
+            node:24.22.2-alpine3.24 node registry-cleanup/cleanup.ts

.gitea/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
           GIT_TAG: ${{ github.ref_name }}
         run: |
           set -euo pipefail
-          docker run --rm -v "$PWD:/repo" -w /repo node:26.13.0-alpine3.24 \
+          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
             node release-tooling/contract-version.ts "$GIT_TAG" src/plugin-host/plugin.ts
       - name: Promote the commit-hash image to semver + latest
         env:
@@ -98,9 +98,9 @@ jobs:
           VERSION=${INPUT_VERSION:-${GIT_TAG#v}}
           VERSION=${VERSION#v}
           # An empty dispatch input falls back to the branch name, so gate this like a tag.
-          docker run --rm -v "$PWD:/repo" -w /repo node:26.13.0-alpine3.24 \
+          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
             node release-tooling/contract-version.ts "$VERSION" src/plugin-host/plugin.ts
           docker run --rm -v "$PWD:/repo" -w /repo \
             -e DOCKERHUB_REPO -e DOCKERHUB_TOKEN -e DOCKERHUB_USER \
-            node:26.13.0-alpine3.24 \
+            node:24.22.2-alpine3.24 \
             node release-tooling/dockerhub-overview.ts "$VERSION"

.gitea/workflows/renovate.yml

@@ -58,11 +58,11 @@ jobs:
           if [ -z "$BUMPS" ]; then
             echo "Renovate commits since ${LATEST}, but none carry Release-Bump — nothing reached a running Plainpages; skipping"; exit 0
           fi
-          NEXT=$(docker run --rm -v "$PWD:/repo" -w /repo node:26.13.0-alpine3.24 \
+          NEXT=$(docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
                  node release-tooling/next-version.ts "$LATEST" $BUMPS)
           # Read the constant off origin/main, not the checkout, which lags the merges this run made.
           git show origin/main:src/plugin-host/plugin.ts \
-            | docker run -i --rm -v "$PWD:/repo" -w /repo node:26.13.0-alpine3.24 \
+            | docker run -i --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
                      node release-tooling/contract-version.ts "$NEXT" -
           echo "Releasing $LATEST -> $NEXT"
           git tag "$NEXT" origin/main

AGENTS.md

@@ -370,7 +370,7 @@ docker compose -f compose.yml up --build -d              # production
    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: Goals → Audience → Overview → Users, groups
+   by **what an adopter reaches for first**, not by architectural layering: Goals → Audience → Overview → Glossary → Users, groups
    & permissions → Building plugins → menu/blocks/interactivity → Configuration → Auth → Email →
    Architecture → Testing → Production → Observability → JWT-rotation runbook → Project-layout file
    map → Extending. Place a new section by how early an adopter needs it. **Users, groups &

CHANGELOG.md

@@ -6,6 +6,12 @@ at boot. Entries start at 0.3.0.
 
 ## Unreleased
 
+### The README defines its terms and states its intended scale
+
+A new Glossary defines host, plugin, manifest, chrome, nav fragment, permission name, system plugin
+and denylist. Plugin dependencies also states the scale Plainpages is sized for: a handful of plugins
+per deployment.
+
 ### The mobile nav stays reachable on engines without `:has()`
 
 At 860px and narrower, an engine without `:has()` (Chromium below 105, such as webOS TV 22 and 23,

Dockerfile

@@ -1,5 +1,5 @@
 # Node 24 runs TypeScript directly (type stripping) — no build step. Pinned exact tag.
-FROM node:26.13.0-alpine3.24
+FROM node:24.22.2-alpine3.24
 
 # Above WORKDIR so dev's `.:/app` bind mount can't shadow them; a volume at /app/node_modules
 # instead leaves a root-owned dir in the checkout (the daemon creates mount destinations as root).

README.md

@@ -73,6 +73,7 @@ From here, render real pages against the app shell and fetch upstream data — s
 - [Goals](#goals)
 - [Audience](#audience)
 - [Overview](#overview)
+- [Glossary](#glossary)
 - [Users, groups & permissions](#users-groups--permissions)
   - [naming a permission](#naming-a-permission)
   - [a worked example](#a-worked-example)
@@ -210,6 +211,24 @@ feature removes the need for JS (theme switching, popovers, disclosure) we use i
 avoid is shipping a client-side runtime, not using the platform. Markup is semantic and accessible
 (see [AGENTS.md](AGENTS.md)).
 
+## Glossary
+
+- **Host** — the `web` container: the Node process that discovers plugins, serves every page and
+  owns no state of its own. Everything outside it (a plugin's upstream, Ory) is reached over the network.
+- **Plugin** — a folder under `plugins/` that adds domain features.
+- **Manifest** — the object a plugin's `plugin.ts` exports as its default: its routes, nav,
+  permissions and hooks. The host checks it at boot and refuses a bad one ([The manifest](#the-manifest)).
+- **Chrome** — everything on a page that isn't the page's own content: brand, menu, user, theme and
+  CSRF token. A handler gets it as `ctx.chrome` ([RequestContext](#requestcontext)).
+- **Nav fragment** — the `nav` entries one plugin contributes. The host merges every plugin's
+  fragment into the one global menu and filters it per user ([The menu system](#the-menu-system)).
+- **Permission name** — a `<resource>:<action>` string such as `scheduling:write`, granted in Keto and
+  carried in the session JWT's `permissions` claim ([Naming a permission](#naming-a-permission)).
+- **System plugin** — a plugin that administers Plainpages' own identity stack, through the
+  privileged `ctx.system` ([System capabilities](#system-capabilities-the-ctxsystem-surface)).
+- **Denylist** — the optional in-memory list, per instance, of subjects revoked just now, so a
+  deactivation or a user's own permission change lands before the JWT expires ([Instant revoke](#instant-revoke-the-optional-denylist)).
+
 ## Users, groups & permissions
 
 Authorization here is two hops: a **user** — directly, or through a **group** — is granted a
@@ -793,6 +812,9 @@ included, since the plugin folder *is* the repo. A baked image needs no extra st
   above every plugin, and a plugin resolves it from there — nothing to declare, just import it. A
   copy inside your plugin's own `node_modules` would shadow it with a *second* instance of the host's
   contract, turning a sign-in redirect into a 500, so discovery refuses one there at boot.
+- **Plainpages is sized for a handful of plugins per deployment, about ten.** Each plugin carries
+  its own dependency tree, so every one adds to disk use and to the memory of the `web` process;
+  hundreds of plugins is not a goal.
 - **The host never upgrades or dedupes your dependencies.** Two plugins depending on the same package
   each get their own copy at their own version, so neither can break the other by upgrading — and
   keeping yours current, and audited, is yours to own. Renovate here watches every manifest in this

compose.override.yml

@@ -49,7 +49,7 @@ services:
   # backs it (PLUGIN_SETTING_SCHEDULING_UPSTREAM above points here). Stand-in for the customer's real service —
   # stdlib-only, in-memory, no auth. Prod points PLUGIN_SETTING_SCHEDULING_UPSTREAM at the real backend instead.
   shifts-upstream:
-    image: node:26.13.0-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: node /srv/server.ts
     restart: unless-stopped
     volumes:

docs/comprehension-history.md

@@ -62,3 +62,24 @@ Inherited architect, decided by:
 
 - Self-sufficiency, Overall: `public/css/styles.css:5` `Architecture` header: the false `light-dark()` bullet is gone, so the header no longer contradicts the TOKENS comment
 - Locality, Self-sufficiency, Overall: `public/css/styles.css:687` `@supports selector(:has(a))` in `@media (max-width: 860px)`: the guard and its comment put the dependency of the open state on `:has()` where an editor would change it
+
+## 2026-10-31T01:19:49Z, PR #184 at af157c9, against bb8e6bc
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | better | same | same | better | better |
+| Inherited architect | better | better | same | better | better |
+
+Mid A, decided by:
+
+- Self-sufficiency, Navigation, Overall: `public/css/styles.css:12` `TOKENS` header comment: says all three theme rules need `:has()`, names the engines without it and points to the `@supports not selector(:has(a))` block, where the old text called the swaps "rock-solid"
+- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: defines host, plugin, manifest, chrome, nav fragment, permission name, system plugin and denylist and links each to its home section
+- Self-sufficiency: `README.md:815` `Plugin dependencies`: the scale bullet states the plugin count the per-plugin dependency design assumes
+
+Inherited architect, decided by:
+
+- Self-sufficiency, Locality, Overall: `public/css/styles.css:12` `1. TOKENS` comment: an editor of the theme mapping learns of the distant `:has()` fallback from the comment, where the old text said the swap could not fail
+- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: a cold reader reaches "chrome" or "denylist" and their home sections in one hop
+- Self-sufficiency: `README.md:815` `### Plugin dependencies`: the scale bullet gives the plugin count the dependency design assumes

docs/reading-cost.md

@@ -47,3 +47,15 @@ Read most (opens and searches):
 - `examples/plugins/scheduling/views/overview.ejs` 1
 - `examples/plugins/scheduling/views/shifts.ejs` 1
 - `src/http/app.test.ts` 1
+
+## Reading cost, chunk 91d11dbe63f9, finished 2026-10-31T01:13:44Z
+
+69010 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `todo.md` 7
+- `README.md` 4
+- `public/css/styles.css` 4
+- `CHANGELOG.md` 1
+- `src/ui/stylesheet-floor.test.ts` 1

e2e-tests/compose.full.yml

@@ -53,7 +53,7 @@ services:
 
   # The reference plugin's upstream (examples/shifts-upstream) so /scheduling/shifts shows real rows.
   shifts-upstream:
-    image: node:26.13.0-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/server.ts"]
     volumes:
       - ./examples/shifts-upstream/server.ts:/server.ts:ro
@@ -66,7 +66,7 @@ services:
   # Mock OIDC provider for the SSO login test — stdlib Node, auto-approves, signs an id_token Kratos
   # verifies via its jwks. Reachable as the same host (mock-oidc:9000) by both the browser and Kratos.
   mock-oidc:
-    image: node:26.13.0-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/mock-oidc.ts"]
     environment:
       ISSUER: http://mock-oidc:9000
@@ -81,7 +81,7 @@ services:
 
   # Same-origin gateway: Kratos-owned paths → kratos, everything else → web (e2e-tests/proxy.ts).
   proxy:
-    image: node:26.13.0-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/proxy.ts"]
     depends_on:
       web:

package-lock.json

@@ -13,7 +13,7 @@
       },
       "devDependencies": {
         "@types/ejs": "3.1.5",
-        "@types/node": "26.6.6",
+        "@types/node": "24.19.2",
         "typescript": "7.0.2"
       },
       "engines": {
@@ -37,13 +37,13 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "26.6.6",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz",
-      "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==",
+      "version": "24.19.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.2.tgz",
+      "integrity": "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "undici-types": "~8.9.0"
+        "undici-types": ">=7.24.0 <7.24.7"
       }
     },
     "node_modules/@typescript/typescript-aix-ppc64": {
@@ -453,9 +453,9 @@
       }
     },
     "node_modules/undici-types": {
-      "version": "8.9.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
-      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "version": "7.24.6",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
       "dev": true,
       "license": "MIT"
     }

package.json

@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@types/ejs": "3.1.5",
-    "@types/node": "26.6.6",
+    "@types/node": "24.19.2",
     "typescript": "7.0.2"
   }
 }

public/css/styles.css

@@ -9,14 +9,17 @@
 /* ---------- 1. TOKENS ----------------------------------------
    Two raw palettes (--l-* light, --d-* dark) are defined once.
    A small mapping (--bg: var(--l-bg) ...) picks the active set.
-   Theme resolution (no JS):
+   Theme resolution (no JS); all three rules below need :has():
      • default + @media(dark)  → follows the OS  (Auto)
      • html:has(#theme-light)  → force light
      • html:has(#theme-dark)   → force dark
+   Engines without :has() (Chromium below 105, Firefox below 121,
+   Safari below 15.4) ignore all three and stay light; see the @supports not
+   selector(:has(a)) block further down.
    We avoid light-dark()/color-scheme for app colors because their
-   resolution is unreliable across engines; :has() variable swaps
-   are rock-solid. color-scheme is still set as a hint for native
-   widgets (date picker, scrollbars, selects).
+   resolution is unreliable across engines. color-scheme is still
+   set as a hint for native widgets (date picker, scrollbars,
+   selects).
 ------------------------------------------------------------- */
 :root {
   /* Hex, never oklch: below Chromium 111 `var(--accent)` is invalid at computed-value time and the

todo.md

@@ -12,13 +12,11 @@
 
 | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
 |---|---|---|---|---|---|---|---|---|---|---|---|
-| 26 | 0.4.21 |  |  | **Add a domain glossary and the project's intended horizon to the README.** | 1 | 2 | 1 | 2 | 3 | 9 by 3, code health by 2 | 11.9 |
 | 8 | 0.4.21 |  |  | **Run the visual E2E specs at viewports from a large desktop down to a small phone.** | 2 | 1 | 1 | 2 | 4 | code health by 3 | 9.0 |
 | 9 | 0.4.21 |  |  | **Typecheck `e2e-tests/` in the gate.** | 1 | 1 | 1 | 1 | 3 | code health by 2 | 9.0 |
 | 24 | 0.4.21 |  |  | **Retire `src/ui/shell-context.ts` and render the dashboard from `ctx.chrome`.** | 2 | 1 | 2 | 3 | 4 | code health by 3 | 9.0 |
 | 17 | 0.4.21 |  |  | **Remove the icons no caller uses from `ICON_NAMES` and the sprite.** | 1 | 1 | 1 | 1 | 1 | 8 by 1, code health by 1 | 8.8 |
 | 21 | 0.4.21 |  |  | **Fail the gate on a function that exceeds a size or complexity limit.** | 3 | 1 | 1 | 3 | 5 | code health by 4 | 7.2 |
-| 38 | 0.4.21 |  |  | **Correct the TOKENS comment at the top of `public/css/styles.css` so it no longer claims `:has()` swaps are "rock-solid" or that the theme follows the OS on every engine.** | 1 | 2 | 1 | 2 | 1 | code health by 1 | 7.2 |
 | 32 | 0.4.21 |  |  | **Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.** | 3 | 1 | 1 | 3 | 4 | code health by 2 | 6.0 |
 | 20 | 0.4.21 |  |  | **Redirect an anonymous hit on a session-needing flow page to sign-in, instead of a 500.** | 2 | 2 | 2 | 4 | 3 | 2 by 4 | 4.2 |
 | 4 | 0.4.21 |  |  | **Refuse a permission save whose baseline no longer matches Keto, so concurrent edits are not silently lost.** | 2 | 2 | 2 | 4 | 4 | 2 by 4 | 2.8 |
@@ -39,12 +37,6 @@
 
 ## Details
 
-### 26. Add a domain glossary and the project's intended horizon to the README.
-
-Glossary: host, manifest, chrome, nav fragment, permission token, system plugin, denylist. Also the
-expected plugin count, since per-plugin dependency isolation prices N dependency trees on disk and
-in RSS.
-
 ### 24. Retire `src/ui/shell-context.ts` and render the dashboard from `ctx.chrome`.
 
 `ShellModel`/`buildShellContext` has one consumer, the dashboard, and duplicates `PageChrome` on
@@ -59,14 +51,6 @@ AGENTS.md → "`ICON_NAMES` is a host-owned registry" already makes this routine
 
 Only `tsc --strict` runs today. A new tool is a new dependency, so justify it.
 
-### 38. Correct the TOKENS comment at the top of `public/css/styles.css` so it no longer claims `:has()` swaps are "rock-solid" or that the theme follows the OS on every engine.
-
-Section 1's TOKENS comment says the theme follows the OS by default and that `:has()` variable swaps
-are "rock-solid". On an engine without `:has()` (Chromium below 105, Firefox below 121) every theme
-rule is inert, the OS-dark rule included, so those engines stay light, as the
-`@supports not selector(:has(a))` block further down says. A reader trusting the comment expects dark
-mode there.
-
 ### 32. Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.
 
 Nothing checks README → "Two browser floors", and no E2E engine is old enough to show a break.