@bongos/core 1.19.396 → 1.19.398

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.396",
-  "core_contract": "1.19.396",
-  "source_commit": "b4632d6e8d92e8096e958762a36e810fc24c9c35",
+  "core_version": "1.19.398",
+  "core_contract": "1.19.398",
+  "source_commit": "d2fe79ca3d995c8416584bc06575b73afeaec45c",
   "source_ref": "HEAD",
-  "built_at": "2026-08-28T16:08:46.136Z",
+  "built_at": "2026-08-28T18:29:17.996Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 345,
+    "docs_redacted": 348,
     "agent_docs_stubbed": 23,
-    "functional_verbatim": 1635,
+    "functional_verbatim": 1658,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2003,
-  "tree_sha256": "950c8c43ac98c0e161e25a1c17cd699ad9582392105dcd0abadc8efc090a95c8",
+  "file_count": 2029,
+  "tree_sha256": "034d29b37b3208023040c5ded6d355c32bba38f3e57ced2a770e893f8d1928ff",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -127,7 +127,7 @@
     {
       "path": ".claude/skills/design/SKILL.md",
       "mode": "0000644",
-      "sha256": "83f2d423421bc08e7f460847616bc0cfba636cb24563566724776b2c7c1a1662"
+      "sha256": "a16c7a31109db8e4e798e419fedd80bb6d258aa1f8b2680ccfd2925fd204e26f"
     },
     {
       "path": ".claude/skills/dev/SKILL.md",
@@ -1489,10 +1489,15 @@
       "mode": "0000644",
       "sha256": "901dcd1ca9748e999ea0db27e213f76c7e38caf620fb6b17fc8d1cf9dbee5e9d"
     },
+    {
+      "path": "docs/adr/0198-third-party-skill-vendoring-policy.md",
+      "mode": "0000644",
+      "sha256": "f56d8dfb794186e5a4424d87d40b3ad72cc0fd9872b58c5952aa7313c4f5285a"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "34f327bac4b238f5af2c47e2eb5298f20c9aac35c336dcab29c11396be992e48"
+      "sha256": "ca23e96e590686514d2021c0d0c410121333029204e3e3db9e9c177d000c731f"
     },
     {
       "path": "docs/api-reference.md",
@@ -1822,7 +1827,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "3789594e075f2501de76ac637a3adcb383e3bc611f84f985ed9e385e5d5c8169"
+      "sha256": "af39b836538ca2a2fbdb002be8b9dcc7b899b23e48cfe2cfe60325b5cb73bd45"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2054,6 +2059,11 @@
       "mode": "0000644",
       "sha256": "02ae31810440b86f7c896b7014c75549497cab47345079986d54c9785cf5cc4a"
     },
+    {
+      "path": "docs/recipes/ui-look-before-you-ship.md",
+      "mode": "0000644",
+      "sha256": "cd8272b75c5fe26f165cf95a45656109266c8ef1942a47705ab10f5f5affcdd5"
+    },
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
@@ -3999,6 +4009,11 @@
       "mode": "0000644",
       "sha256": "99f9338383c4940f199f8ad66d2140779b0262b628c135646c00778973a5b292"
     },
+    {
+      "path": "modules/hall-ui/public/ranks.states.json",
+      "mode": "0000644",
+      "sha256": "3a2e1d649c217473b3706f9295b796c50a20327b78b2856daf85bf01a1e34b27"
+    },
     {
       "path": "modules/hall-ui/public/roadmap.css",
       "mode": "0000644",
@@ -5177,7 +5192,77 @@
     {
       "path": "modules/ui-design/kit/README.md",
       "mode": "0000644",
-      "sha256": "70f65052951335b63def03590ee971e2f482d6db08365484b532e4bc3c676495"
+      "sha256": "850e72f762d80951ed0ad6ca392a5c0619f26c10a58edd0a1d467038b74bbcfa"
+    },
+    {
+      "path": "modules/ui-design/kit/check-mock.js",
+      "mode": "0000644",
+      "sha256": "9f38941d23b498feeac12f6f32a64d5f3c7749e1b6e01db7bf83dedd3cc2e549"
+    },
+    {
+      "path": "modules/ui-design/kit/contrast.js",
+      "mode": "0000644",
+      "sha256": "239cc33a7896dbbe0bab25098904b2be8298ff5c440b7e2a44594e131d21ed9c"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/cost-summary.json",
+      "mode": "0000644",
+      "sha256": "057391fcbba1985a234cf1d4f56db36a89a79d1ee44a80b5cd30f51ed7175cdb"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/featured.json",
+      "mode": "0000644",
+      "sha256": "a5e075d343bc7d29e69896ba90de2fc96e2aeb5765f09e193cb26926b4ae697d"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/leaderboard.json",
+      "mode": "0000644",
+      "sha256": "53f4fbe364bee2295133ea55082b79069451b0deaf3e99e42d0963c63ee1da87"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/me.json",
+      "mode": "0000644",
+      "sha256": "71e560cd3ffcc86287f0ec9c0e527de5ce568a1a9c5c8a6cefea7efe2459d070"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/my-projects.json",
+      "mode": "0000644",
+      "sha256": "ff0195be4b19616f30fccde0dc980a47329587124bfac08158b1e8741386fc1b"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/progress.json",
+      "mode": "0000644",
+      "sha256": "bbc16593ef50e966647f54559834a956778ac59937ef3fc27794d98d1e12a67e"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/recent-shipped.json",
+      "mode": "0000644",
+      "sha256": "5c50e901d4e2e123b2c94f17b42e68cdb5dd9702edff840802777f0796e8f976"
+    },
+    {
+      "path": "modules/ui-design/kit/lib.js",
+      "mode": "0000644",
+      "sha256": "9b0b5eb21711fd7f5c0857a89066270ac8c0911cec19d0b8f21ed369a1dde8e5"
+    },
+    {
+      "path": "modules/ui-design/kit/png.js",
+      "mode": "0000644",
+      "sha256": "d4a7f9c791dec3857452642a1f87dac716c2f098a36d6f7b5a0655da9a110b4e"
+    },
+    {
+      "path": "modules/ui-design/kit/probe.js",
+      "mode": "0000644",
+      "sha256": "d38d6168c3bd701a368726fbf53bfb9209711bd2cb68b7df79a3d2505edf2efe"
+    },
+    {
+      "path": "modules/ui-design/kit/render.js",
+      "mode": "0000644",
+      "sha256": "15931b862ff62824b9916172d75df677bea186e1be23eefb99bbd4541932acfd"
+    },
+    {
+      "path": "modules/ui-design/kit/serve.js",
+      "mode": "0000644",
+      "sha256": "f1d349f681525b78abb47df98bf26a1f7470a72b00b8d5696d5453bb936647c8"
     },
     {
       "path": "modules/ui-design/module.json",
@@ -5199,10 +5284,20 @@
       "mode": "0000644",
       "sha256": "c9d90b5ffb6e3895c8e98cefbdc89ff4fdd52a22a1073d8fe956a487c4b7816d"
     },
+    {
+      "path": "modules/ui-design/skills/PREAMBLE.md",
+      "mode": "0000644",
+      "sha256": "aa96d856793c1e804a90f40c498cff6143f2b5fee80dd5f840422cc6f1230644"
+    },
     {
       "path": "modules/ui-design/skills/README.md",
       "mode": "0000644",
-      "sha256": "709a99b3879eec15552c7ce18291fad5a4922d477955982eb51b718577ee7948"
+      "sha256": "0f7045426ad746ec98f6cf16ba0e2bf5c8ee573de9907dbc93676eac7d43d7b6"
+    },
+    {
+      "path": "modules/ui-design/skills/policy.json",
+      "mode": "0000644",
+      "sha256": "f73cb4ce230ffbd940a4aa00742f5d09e736a8f70402c155d1933618e70392d7"
     },
     {
       "path": "modules/ui-design/styles/README.md",
@@ -5212,12 +5307,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7dd6552859e62daf201d9fdd1c17f95ea4a97bac3e5dc95d175ed0c8bbac88c7"
+      "sha256": "13f7c20f7d01157842d006764090fabd60536d20e4dee048243f04851ece16c8"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "292bfaf5419d894c03339b6363173872ba73e896a9dceec60ff625568fe9ed60"
+      "sha256": "f45044af3ba97b0e1b923e179ea75e8186280f21bb0168cefd7489a133a137c0"
     },
     {
       "path": "public-docs/index.html",
@@ -5549,6 +5644,16 @@
       "mode": "0000644",
       "sha256": "1e7ceb571c899be95c7a945a8bd4337bb000af2b90d6f8de5b4dfcef3a5e8891"
     },
+    {
+      "path": "public-landing/index.probes.json",
+      "mode": "0000644",
+      "sha256": "eb90141b2ef676e06b3140d2e8caa61481991a748b36491502592987ed9c0880"
+    },
+    {
+      "path": "public-landing/index.states.json",
+      "mode": "0000644",
+      "sha256": "8d5955085ab5059a15195d5c475262d114061d616dd9c82335a91a5992cc5602"
+    },
     {
       "path": "public-landing/privacy.html",
       "mode": "0000644",
@@ -5559,6 +5664,16 @@
       "mode": "0000644",
       "sha256": "1e1867918ec2a8fe489d9d21aa2e50fada9950b220c865c57f23c703a6c29f24"
     },
+    {
+      "path": "public-landing/projects.probes.json",
+      "mode": "0000644",
+      "sha256": "e5594cda5b6c30569aaca6181dc39eb28d20e716cdebbca7ad618748bbb8ccb5"
+    },
+    {
+      "path": "public-landing/projects.states.json",
+      "mode": "0000644",
+      "sha256": "26a1473a42005d89b4a15b3538b3e9fe9d1982633f1ec556524d83e114df5240"
+    },
     {
       "path": "public-landing/terms.html",
       "mode": "0000644",
@@ -5807,7 +5922,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "a044b7ea705a87e569f903eb4fb19c941a1fbfd11b069563a2bc767be339d184"
+      "sha256": "4cfe40c72c326ac80a467c56ad24fea60e1b2f1a8a1399c21208eb333b9980fa"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -6789,6 +6904,11 @@
       "mode": "0000644",
       "sha256": "cc6e8640376ada7ceff6a896007b3257c8ea4d943a900eae28433cd41bdd139d"
     },
+    {
+      "path": "scripts/gds/ui-kit-transform.js",
+      "mode": "0000644",
+      "sha256": "8735394cfc5bcdd85b7addb78c3de302f4ba0fee37c25a595f5dcb46240ec529"
+    },
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
@@ -7032,7 +7152,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "77dd62d640862624066bfcd2845c6ed2801091ce49ed676a809da3cce5077761"
+      "sha256": "9705e8a5176cfd1136c1b432b1d4ff71351d9f4654c636345597a4d96763e500"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -7207,7 +7327,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "711a3add8803459721523364c9c993e30908475bebdf65eb83789f5520e91104"
+      "sha256": "ecd70bbc85834d5014b2062dd73436d56124aa399c12f9f4f0fc0f5e5f25a594"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7692,7 +7812,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "5ca8997f238d8395663992c9ce9ccef08ea2b09fbee6735c44f119050ef9455b"
+      "sha256": "37b2632142b2b2855a3c2b4b5dff6ab84536ee7b4a73fc24078851b6fc289f91"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -9954,6 +10074,16 @@
       "mode": "0000644",
       "sha256": "74798ce81280d4fcfa5844b575c3c64db582308f7a0726fc420317fe83eadd96"
     },
+    {
+      "path": "tests/ui_design_kit.mjs",
+      "mode": "0000644",
+      "sha256": "2d3c4f767a3de04beddf22d6d0acf8ca57b7a85dc0f132930466eb4f33aa8c13"
+    },
+    {
+      "path": "tests/ui_design_skills.mjs",
+      "mode": "0000644",
+      "sha256": "d43f67840668875a9829d741f661e344a27675704834cd6a5e6b9e3247164068"
+    },
     {
       "path": "tests/update_channel.mjs",
       "mode": "0000644",

package/.claude/skills/design/SKILL.md

@@ -25,7 +25,7 @@ Read, in this order, and quote nothing from memory:
 
 Render the real surface before and after — never reason about layout from source alone:
 
-- Stage it (`/builder-stage` on a box; a local stub + Playwright on a laptop — the kit under `modules/ui-design/kit/` ports the apex probes once [task 1003320](https://cloudbongos.com/builders#/task/1003320) lands) and screenshot **three widths (≥1280 / ~900 / ≤480) × two modes (light / dark)** at minimum.
+- Run the kit — `node modules/ui-design/kit/render.js --page <path>` renders every state of the page's states file at **1440 / 390 / 320 × dark / light** through a stub that serves the surface the way the instance does, audits each render against the floors below, and writes the shots; `node modules/ui-design/kit/probe.js --page <path>` runs the page's interaction contract as PASS/FAIL lines. The loop, the file shapes and the failure table: [`docs/recipes/ui-look-before-you-ship.md`](../../../docs/recipes/ui-look-before-you-ship.md). A page with no states file yet gets one first (copy the hub's). `/builder-stage` on a box shows the same change on a live preview.
 - Show the screens, then caption them in one line. The person you're working with judges the picture.
 - Grep the receiving page for class collisions before porting a component across pages (the landing's content sections are `.band`; the menu is `.menuBand`).
 
@@ -55,6 +55,14 @@ Generated code uses the `--dt-*` variables; adapters write only `src/ui/<surface
 - **Figma** (`/figma-design-sync`): push the current state so a designer never opens a stale file; land their edit back as committed code. Canvas art that won't translate becomes an asset, never forced into code.
 - Both are adapters against `modules/ui-design/docs/design-contract.md`; a third tool is a third adapter, not a new integration.
 
+## The vetted skills (the ui-design module's `skills/`)
+
+Third-party design skills reach a builder only through the module's vendoring policy ([`modules/ui-design/skills/README.md`](../../../modules/ui-design/skills/README.md), ADR 0198): scanned with `/scan-before-install` and reduced to `clean` or `caution`, a licence on the allowlist, a `PROVENANCE.md` sidecar, and the PLATFORM PREAMBLE that reads the instance's world before any taste rule. A vendored skill is listed here by name, one line each; a name that is not listed is not vendored, whatever a builder's own `~/.claude/skills` carries.
+
+- *None vendored (2026-08-28).* Both origins scanned for the scoped set — `pbakaus/impeccable`, and the eleven `Leonxlnx/taste-skill` skills (`design-taste-frontend`, `design-taste-frontend-v1`, `high-end-visual-design`, `minimalist-ui`, `industrial-brutalist-ui`, `redesign-existing-projects`, `gpt-taste`, `stitch-design-taste`, `image-to-code`, `imagegen-frontend-web`, `imagegen-frontend-mobile`, `brandkit`) — reduced to `dangerous` at the scanner's deterministic floor and landed as rebuild specs (GDS tasks). The roster, the verdicts and the way to land one are in the README; vendoring one anyway is an owner override recorded in an ADR, not a session's call.
+
+**Prerequisite, not vendored:** the **playwright plugin** (`claude plugin install playwright@claude-plugins-official`) is the LIVE browser-driving loop, where the kit in Step 2 is the headless one. Install it on the machine that runs a design session; the module never installs anything.
+
 ## Stay clear of
 
 - The pack's neutral values and `DESIGN.md`'s named rules — changing the world is the owner's decision and an ADR, not a session's taste.

package/docs/adr/0198-third-party-skill-vendoring-policy.md

@@ -0,0 +1,43 @@
+# ADR 0198 — Third-party skill vendoring: a scan verdict the session cannot override, a licence allowlist, a provenance sidecar, one preamble block, and no auto-update
+
+- **Status:** Accepted (2026-08-28)
+- **Task:** [task 1003321](https://cloudbongos.com/builders#/task/1003321) (goal 1000080 — the second of the five ui-design tasks scoped with the owner on 2026-08-28; [ADR 0197](<redacted>.md) §7 pointed the vendoring policy at this ADR)
+- **Owner intent (2026-08-28):** every builder, on every instance, can produce good-looking, functional UIs in line with that instance's world and build on it. The skills that produced Cloud Bongos's world lived in one builder's `~/.agents/skills`; they were to become part of the `ui-design` module, materialised for every builder where the module is on.
+
+## Context
+
+Twelve design skills were installed on the founding builder's machine and used through the whole-frontend pass: `impeccable` (the operating skill the hub round ran under, 148 files, Apache-2.0) and eleven single-file "taste" skills from one repository (`Leonxlnx/taste-skill`, MIT). The task: vendor them under `modules/ui-design/skills/`, each scanned with `/scan-before-install` on its origin, with a provenance sidecar, a licence allowlist, and a platform preamble that reads the instance's world before any taste rule, so `claude-materialize` installs them for every builder on every instance with the module on.
+
+Three facts shaped what happened:
+
+1. **The platform already owns a scanner with a deterministic floor and a fixed arithmetic** (`modules/security/artifact-scan/`, the `/scan-before-install` skill). Its rules are owner decisions written down: the floor's findings are untouchable by any model; the verdict is `reduceVerdict()`'s max over floor, panel, lens health, tier clamp and coverage; on `dangerous` no install command is printed and no sanitised copy is offered — the honest landing left is a rebuild spec derived from the artifact's documentation, or walking away.
+2. **Both origins reduced to `dangerous`.** `Leonxlnx/taste-skill` @ `ccbc1563…` (64 files, `default` tier, five lenses + one refuter, 21 panel findings upheld, 0 refuted): floor `dangerous` on one critical — an injection-phrase hit at `skills/taste-skill/SKILL.md:892` that the prompt-injection lens identifies as a filename-template placeholder (`<name>--<system>.md`); panel `caution` (one medium: the only documented install path runs an unpinned third-party `npx` CLI; twenty-one low: mandated invocation of any available image-generation tool, unbounded image counts, remote assets and an unpinned CDN script in generated pages, an auto-loaded cross-agent instruction file). `pbakaus/impeccable` @ `ea360025…` (3323 files, 63.7 MB — 16 harness-specific copies of one skill plus a CLI, a browser extension, a plugin and tests; `default` tier): floor `dangerous` on three criticals (a `bypassPermissions` marker in the skill's own live copy-edit agent; an instruction-override phrase in a test fixture that the lens confirms is injection-resistance test data; a same-file credential-store + http-client co-occurrence in a test) with 19 high, 107 medium, 147 low; the panel's upheld findings include PostToolUse and Stop hooks shipped in `.claude/settings.json` and written by the installer into five harness configs (under `$HOME` on a global install, so they fire in every project), a child agent spawned with `--permission-mode bypassPermissions` / `--dangerously-bypass-approvals-and-sandbox` from a loopback HTTP route with the parent environment forwarded, a setup directive that tells the model to disregard its harness system prompt's autonomy statement, a live-server token embedded in page source, an unverified remote bundle download on `install`/`update`, default-on telemetry, and a browser extension requesting `<all_urls>`.
+3. **The materialiser only knew `.claude/skills/`.** `claude-materialize.js` copied the core's `.claude/skills/` tree and skipped a disabled module's declared names; it never looked inside `modules/<key>/`. A skill living in a module's own tree had no path to a builder's harness.
+
+The taste skills' one critical is a false positive in the human sense and a true positive in the scanner's. That is exactly the case the scanner's rules were written for: if a session may decide which floor findings "don't really count", the floor is decoration and the next injection is one plausible sentence away from a clean verdict. The eleven taste skills are also, on the panel's reading, not benign as instructions: they mandate spending the builder's image-generation credits whenever a tool is present, with the cost brake removed — on a platform where the owner's rule confines image generation to hero plates and hero objects.
+
+## Decision
+
+1. **A scan verdict is the gate, and a session cannot override it.** A third-party skill lands under `modules/ui-design/skills/vendor/<name>/` only from a commit that `/scan-before-install` reduced to `clean` or `caution` at the `default` tier or higher. `dangerous` lands a rebuild spec (a GDS task holding the engine's script-framed `REBUILD-SPEC.md`), never a copy — not for a skill already installed on a builder's machine, not for one that ran the last round. Vendoring a `dangerous`-scanned skill is an **owner decision recorded in its own ADR**, with the scan report cited, and the test that enforces this policy (`tests/ui_design_skills.mjs`) is amended in the same change so the exception is visible in code, not just prose.
+2. **A licence allowlist:** `Apache-2.0`, `MIT`, `BSD-2-Clause`, `BSD-3-Clause`, `CC-BY-4.0`. Anything else, or unlicensed, is a rebuild spec. The upstream `LICENSE` text travels with every copy.
+3. **A provenance sidecar** — `PROVENANCE.md` beside every vendored `SKILL.md`, YAML frontmatter with `name`, `origin`, `sourcePath`, `commit` (the full sha; never a branch or tag), `licence`, `scanVerdict`, `scanTier`, `scanReport`, `scannedOn`, `vendoredOn`, then prose. The policy is data, not a README: [`modules/ui-design/skills/policy.json`](../../modules/ui-design/skills/policy.json) holds the allowlist, the landable verdicts, the sidecar's required fields and the preamble markers; the test reads it.
+4. **One preamble block, byte-identical everywhere.** [`modules/ui-design/skills/PREAMBLE.md`](../../modules/ui-design/skills/PREAMBLE.md) is inserted as the first thing after a vendored `SKILL.md`'s frontmatter, fenced by two HTML-comment markers, so an upstream refresh is a three-way merge around one block and the test can pin every copy against the source. It says, in order: load the instance's world (its pack, its tokens, its `DESIGN.md`; the neutral pack and the floors where it has none) before any taste rule; the fifteen-token contract is the only colour source; a style skill produces variants inside that world, never a second world; images are for hero plates and hero objects only; the instance's taste bans apply and win; the platform floors and the Kill Switch hold on every instance; look before you ship through the kit.
+5. **`vendor/` is the home, and it is exempt from the first-party budgets on purpose.** `scripts/gds/fitness-ratchets.js` already excludes any `vendor/` path segment from the line, oversize and duplication ratchets; a 150-file upstream tree is third-party code, not our debt. A skill the module *authors* lives at `skills/<name>/` and is counted.
+6. **The manifest stays the single declaration.** `module.json` `contributes.skills` names every skill the module ships, whether it lives in `.claude/skills/` or under the module; an undeclared dir is not a skill. `claude-materialize.js` gains step 1b: for every enabled module, each declared name that resolves to `modules/<key>/skills/<name>/` or `modules/<key>/skills/vendor/<name>/` (a dir with a `SKILL.md`) is copied — sidecar and licence included, the same `bongosify` + rebrand transforms — into the instance's `.claude/skills/<name>/`; a disabled module's are excluded by the rule that already existed; a name the core's own `.claude/skills/` carries keeps the core copy. `moduleSkillRoster` is the one place the enabled-or-not rule lives, shared by the old skip and the new copy, and it is walked once per materialise. **The gate holds at copy time, not only in CI:** a declared name is a path segment the materialiser writes under, so it must match `SKILL_NAME_RE` (a lowercase slug — `../x` names nothing) before any path is built; and a vendored dir lands only when `vendoredSkillGate` reads a `PROVENANCE.md` whose `licence` is on the allowlist and whose `scanVerdict` may land (the module's own `skills/policy.json` when present, the same five licences and two verdicts otherwise). A refusal is logged and reported in the summary, never a silent skip — a manual materialise outside CI cannot land an unvetted copy.
+7. **No auto-update.** A refresh is a task: re-scan the new commit, re-apply the preamble, update the sidecar. An instance may disable the module (which withdraws every vendored skill) or add its own skills under its own `.claude/skills/`; it never edits a vendored copy.
+8. **The playwright plugin is a documented prerequisite, never vendored** — an MCP plugin is the LIVE browser-driving loop, where the kit is the headless one; the module installs nothing.
+
+## Consequences
+
+- **The roster is empty on the day the policy ships, and that is the policy working.** Both origins were scanned at the standard tier with the strongest model on every lens and refuter; the reports live in the scanning builder's `~/.config/otb/scan-reports/`, the rows in `security_scans`, and two rebuild-spec tasks hold the documented functionality for an in-house build. The module CLAUDE.md, the skills README and `/design` say so in the same words; `/design` names the twelve by name so a builder knows what was scoped and why it is not there.
+- **A builder's materialised `.claude/skills` carries a vendored skill with its provenance and licence the moment one lands** — proven by fixture in `tests/ui_design_skills.mjs` and `tests/claude_materialize.mjs`, not by the roster.
+- **The core checkout itself does not see module-owned skills** (the materialiser's self-copy guard is a no-op when instance == core). A core developer uses their own `~/.claude/skills`; an instance gets the module's on `init`/`upgrade`. Filed as an idea for a dev-checkout materialise step.
+- **What the owner can decide next, and where:** vendor a subset anyway (an override ADR citing the report, plus the test amendment); or accept the rebuild-spec tasks and build the taste layer in-house on the style library (task 1003323) and the kit; or re-scan a later upstream commit when the flagged behaviours change. None of those is a session's call.
+
+## Rejected
+
+- **Treating the floor's filename-placeholder hit as a false positive and vendoring the eleven taste skills.** It is one, in the human sense — and the scanner's rule 6 exists so that a model never gets to say so. The value of the gate is that its arithmetic is not negotiable inside a task.
+- **Scanning a fork or a subtree to get a cleaner verdict.** The pinned SHA of the origin is the only install source; a narrower artifact chosen to pass the scan is evasion of our own gate.
+- **Vendoring `impeccable` with the hooks and the live loop stripped.** The scanner's sanitise landing is refused on any critical by design (a malice indicator makes whole-file removal unsafe to reason about), and a hand-pruned copy would be exactly the unscanned bytes the policy forbids.
+- **Putting vendored skills in `.claude/skills/` like the core's own.** They would count against the first-party ratchets, show in the file-map's generated skills section as ours, and lose the `vendor/` signal that says "not our code, see the sidecar".
+- **A second declaration surface** (a `vendored.json` roster the materialiser reads). The manifest is already the declaration; the roster is the README, the enforcement is the test.

package/docs/adr/README.md

@@ -285,5 +285,6 @@ This keeps the decision history honest and traceable.
 | 0195 | [**ADR numbers are checked like migration numbers, and the twenty existing collisions are grandfathered by name** ([task 1003164](https://cloudbongos.com/builders#/task/1003164)). Two ADRs could share a number and nothing flagged it — git sees no path collision, the index auto-merges into two rows, and every gate passes; it was found by a human reading `ls docs/adr/`, after a task note had already cited a number the collision made point at an unrelated document. Migrations had this guard already (`stemCollisions()` hard-fails CI, because a re-used migration number silently skips a migration); ADRs had only a best-effort allocator at claim time and nothing afterwards. `scripts/gds/adr-namespace.js` is the sibling module, wired into fitness as Check 31 and so into the required `unit` gate. Building it found twenty live collisions, not one, plus fourteen index defects of the same merge class — two ADRs listed twice and twelve with no row at all, ten of them the second file of a colliding pair, which is how a collision hides. The twenty pairs are grandfathered by EXACT FILENAME rather than renumbered: renumbering breaks every citation to them, which is the harm the check exists to prevent, and set-equality keeps the exemption as narrow as the history that earned it — a third file on a legacy number, or a rename of either half, still fails, and the list may only shrink. The index half is keyed on LINK TARGET, not number (a number rule cannot express a grandfathered pair): every file has exactly one row, every row points at a file that exists. Row ordering warns and never blocks — ten legacy rows are out of order and no PR author caused that (the ADR 0189 split). Rejected: renumbering; grandfathering by number; a numeric cutoff like LEGACY_BARE_CORE_MAX (a new ADR takes a number above the max, so it would catch nothing); fixing it in the claim-time allocator (which already tries, against a stale tree — that is how the collision happened).](<redacted>.md) | docs / numbering discipline |
 | 0196 | [**The chrome world becomes the token contract; the landing gets its own world sheet beside the hub's** ([task 1003298](https://cloudbongos.com/builders#/task/1003298), goal 1000080). The owner picked the chrome-blobs world (1003296) and the v3 composition with light rebuilt to the dark standard (1003297); this build makes it the platform's token contract. Decisions: (1) the neutral pack moves to the world's LIGHT values (pale grey paper, black ink, salmon accent, Manrope + JetBrains Mono) and design-tokens mirrors it; --accent-deep is #a3481a rather than the mock's #d96a35 because the hub and the gate pages paint TEXT with it and #a3481a is the lightest burnt orange clearing 4.5:1 on all three light grounds; the rgba hairlines are flattened to hex so hex-maths consumers survive. (2) theme.ui.backdrop becomes var(--bg): a literal there paints the light ground under the dark page in both modes, since the body rule outranks every sheet. (3) The landing gets its own world sheet public-landing/assets/world.css (contract tier = pack, derived tier both modes, root-absolute plate token PAIRS, the kill switch; NO composition switches) and cosmos.css stays the hub's component sheet until A4 — folding the two tiers would have collided (--line is a width in the world and a colour in the hub; the world's warm --ok/--warn/--err would repaint the hub's fixed green/amber/red chips). cosmos.css's dark tier moves to the world's black and its derived tier is retuned for the salmon accent (dark ink on the fill, never white). (4) Plates ship under public-landing/assets/world/ with provenance embedded: black plates verbatim JPEG, cutouts as WebP with alpha at 1600px (85–170 KB vs 1.1–2.4 MB PNG), sidecars; plate URLs in custom properties escape the ?v= stamp (edge cache 4h), accepted. (5) Live figures are BAKED inside apex-only sentinels (real, dated; a child renders empty until its own feed answers) and refreshed at render time from the five public feeds with fixed definitions: tasks shipped = the sum over every version row, builders = leaderboard entries holding credits, the ledger line = the first building version; live titles have em dashes normalised to a comma and a trailing parenthetical dropped. Every pack-reading fallback site (the claude-design adapter, the status explore page, provisioning onboarding, dev-box brand artifacts + tray icons, the two gate pages) is moved in the same task so no page keeps a private palette. Rejected: one merged token tier; a landing-private palette; PNG cutouts; a script-only ledger; #d96a35 as accent-deep.](<redacted>.md) | apex / design system |
 | 0197 | [**The ui-design module: design is a platform capability; the instance owns its world** ([task 1003324](https://cloudbongos.com/builders#/task/1003324), goal 1000080 — the first of the five ui-design tasks scoped with the owner 2026-08-28). ADR 0081 put the tool-agnostic design layer in core as Cloud Bongos's machinery; the whole-frontend pass then built the chrome world on it and left the three things a builder needs — the contract and its tooling, a way to look before shipping, the taste and the looks — scattered across core, scratchpads and personal skill installs. The owner's reframing: this is NOT the front door, it is a PLATFORM capability every builder on every instance gets, and Cloud Bongos's front door is its first customer, not its owner. Decisions: (1) `modules/ui-design/` is a default-on core-domain module beside grading/economy/memory — it ships METHOD, never a world; (2) ADR 0081's layer moves in (`src/ui/adapters/` → `adapters/`, the three `scripts/gds/` CLIs → `scripts/`, `docs/design-contract.md` → `docs/`) while `config/design-tokens.*`, `design-sources.json` and `DESIGN.md` STAY out as the host boundary — the ADR 0062 §7 split written for design; (3) declaration-only: three contributed skills, no routes/port/migrations, so `GET /modules` lists it and disabling it withdraws the skills and touches no served surface — and NO `ui` discipline yet, because the hall settings page and newcomer-restock don't know it; (4) the `/design` playbook is finally written — `discipline-modes.json` had routed `ui` tasks to a skill that did not exist since task 1267; (5) the module CLAUDE.md draws the platform FLOORS (the Fifteen Rule, the dark twins, no page `:root`, the 24px floor, AA in both modes, the Kill Switch) against the instance's WORLD (its packs + DESIGN.md), tightenable and never loosenable; (6) the CLIs keep thin `scripts/gds/` shims — the form `claude-materialize` rewrites to `bongos exec` on a packaged core, the form `doc-cli-guard` resolves, and the carve precedent — while inside the module they walk up from `__dirname` instead of the computed `require()` into `src/instance-config.js` the static boundary scanner could not see; (7) three reserved homes, each README'd for the task that fills it, the vendoring policy pointed at the skills task's ADR; (8) `public-landing` keeps its own key. Rejected: leaving the layer in core; moving the token files in; the module owning the front door; module-hosted CLIs with no shims; contributing the `ui` discipline now.](<redacted>.md) | modules / design system |
+| 0198 | [**Third-party skill vendoring: a scan verdict the session cannot override, a licence allowlist, a provenance sidecar, one preamble block, and no auto-update** ([task 1003321](https://cloudbongos.com/builders#/task/1003321), goal 1000080 — the second of the five ui-design tasks). Twelve design skills installed on one builder's machine were to become the `ui-design` module's vendored set. Both origins reduced to DANGEROUS under `/scan-before-install` at the default tier: `Leonxlnx/taste-skill` on one floor critical (an injection-phrase hit the panel identifies as a filename placeholder) with a caution panel; `pbakaus/impeccable` on three floor criticals and a panel that upheld shipped PostToolUse/Stop hooks written into five harness configs, a child agent spawned with permissions bypassed from a loopback HTTP route, a directive telling the model to disregard its harness system prompt, a page-embedded live-server token and an unverified remote bundle download. DECISION: the scan verdict is the gate and a session cannot override it — `dangerous` lands a rebuild spec (a GDS task), never a copy, and vendoring one anyway is an owner ADR plus a test amendment; a licence allowlist (Apache-2.0, MIT, BSD-2/3, CC-BY-4.0); a `PROVENANCE.md` sidecar with the full pinned sha; ONE preamble block (`skills/PREAMBLE.md`, byte-identical, fenced by two markers so an upstream refresh is a three-way merge) that reads the instance's world before any taste rule; `skills/vendor/<name>/` as the home because `fitness-ratchets.js` already exempts `vendor/` from the first-party budgets; the manifest stays the single declaration and `claude-materialize.js` step 1b lands a declared module skill — sidecar included — in every instance's `.claude/skills/` and withdraws it with the module; no auto-update; the playwright plugin a documented prerequisite. The roster ships EMPTY and that is the policy working: the machinery is proven by fixture (`tests/ui_design_skills.mjs`), the twelve are named in `/design` with their verdicts, two rebuild-spec tasks hold the documented functionality. Rejected: treating the placeholder hit as a false positive; scanning a fork or subtree; vendoring impeccable with the hooks stripped; `.claude/skills/` as the home; a second roster file.](<redacted>.md) | modules / design system / security |
 
 > ⚠️ **Numbering collisions are now machine-enforced, not narrated.** Twenty numbers are shared by two ADRs each — assigned in parallel sessions before anything checked. The files keep their filenames (renumbering would break every existing citation, and a number once assigned is never reused), and this table disambiguates each pair as `NNNN-a` / `NNNN-b`. The authoritative list is `LEGACY_DUPLICATE_ADRS` in [`scripts/gds/adr-namespace.js`](../../scripts/gds/adr-namespace.js), frozen by exact filename: a **new** collision — or a third file joining a legacy number, or a rename of either half — hard-fails the `unit` CI gate, as does an index row that points at no file or an ADR with no row. The list may only shrink. This paragraph used to narrate the collisions one by one and had fallen eight behind reality; see [ADR 0195](<redacted>.md) for why the check exists and why the pairs are grandfathered rather than renumbered.

package/docs/file-map.md

@@ -129,7 +129,7 @@
 │   ├── hall-ui/                ← CORE-DOMAIN WEB-SURFACE carve (BV1.R85, default-on): the authenticated builders' hall at builders.<apex>, moved from public-builders/ (~13k LOC, the largest). NO routes/db/port — declares contributes.webSurfaces:[{host:"builders.",dir:"public"}] for discovery, but UNLIKE status-ui keeps its DEDICATED serving block in serve-internal (the /builders shim + canonical redirects + citizen/Archon page gates + asset-stamping + hall-widget injection), partitioned out of the generic web-surface loop and served from BUILDERS_DIR. CLAUDE.md, module.json, public/{index.html,builders.js,style.css,work,watch,harbor,gate,pair,settings,ranks,sessions,primer,diagrams,atlas,...}.{html,js},cursors/,chime.wav.
 │   ├── lifecycle/               ← CORE-DOMAIN carve (BV1.R86, default-on): the build state machine — tasks · claims · versions · done-when · goals · dependencies · claim→ship→grade→credit · github-push + merge-lock + conflict-resolve + publish-reconciler. The LAST, most-coupled carve; registers the `lifecycle` kernel port (createTask, classifyTaskKind, tallyPeerVotes, work-tracking reads). CLAUDE.md, module.json, routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js, lifecycle.js, github-push.js, merge-lock.js, conflict-resolve.js, publish-reconciler.js, task-visuals.js + task-visual-db.js + routes/visuals.js (the optional ship-time visual, task 1003109 — the route file is NOT named task-*.js on purpose; see the module CLAUDE.md).
 │   ├── copy-desk/               ← CORE-DOMAIN module (task 1003113 / R02 of goal 1000074, default-on): the COPY half of the design contract — ADR 0081 gave design TOKENS a repo-owned source of truth, text had none. Owns the FLAG (anyone in any role marks a string or a whole surface as needing an artist's attention, with a reason required in BOTH the route and a CHECK constraint) and the QUEUE an artist reads it from. READS R01's committed registry (docs/copy-registry.json, generated by scripts/gds/copy-inventory.js) and never writes it. NO LIVE CMS is the hard non-goal: no column here could hold replacement text, and copy_no_cms.mjs pins that. Key is `copy-desk`, not `copy` — the branding contract already owns a `copy` block, so the bare word reds the "core carries no module code" fitness check. CLAUDE.md, module.json, registry.js, flags.js, routes/copy-desk.js, migrations/copy_desk_001_flags.sql, tests/{copy_flags,copy_queue,copy_no_cms}.mjs. Its hall surface lives with hall-ui (public/copy-desk.{html,js,css}), per the one-key-per-web-surface precedent.
-│   ├── ui-design/               ← CORE-DOMAIN module (task 1003324 / ADR 0197, default-on): the design capability every builder on every instance gets — ships METHOD, never a world. Absorbs ADR 0081's layer: adapters/{claude-design,figma}/index.js (moved from src/ui/adapters/), scripts/{design-sync,figma-design-sync,validate-design}.js (moved from scripts/gds/, which keeps thin shims), docs/design-contract.md (moved from docs/). Declaration-only: contributes.skills design (the /design playbook, new) + design-sync + figma-design-sync; no routes/port/migrations, so disabling it touches no served surface. CLAUDE.md separates the platform FLOORS (the Fifteen Rule, the dark twins, no page :root, the 24px floor, AA in both modes, the kill switch) from the instance's WORLD (its packs + DESIGN.md). Reserved homes kit/ (task 1003320), skills/ (1003321), styles/ (1003323), each with a README. config/design-tokens.* + design-sources.json STAY in config/ as the host boundary; public-landing keeps its own key (first customer, not owner).
+│   ├── ui-design/               ← CORE-DOMAIN module (task 1003324 / ADR 0197, default-on): the design capability every builder on every instance gets — ships METHOD, never a world. Absorbs ADR 0081's layer: adapters/{claude-design,figma}/index.js (moved from src/ui/adapters/), scripts/{design-sync,figma-design-sync,validate-design}.js (moved from scripts/gds/, which keeps thin shims), docs/design-contract.md (moved from docs/). Declaration-only: contributes.skills design (the /design playbook, new) + design-sync + figma-design-sync; no routes/port/migrations, so disabling it touches no served surface. CLAUDE.md separates the platform FLOORS (the Fifteen Rule, the dark twins, no page :root, the 24px floor, AA in both modes, the kill switch) from the instance's WORLD (its packs + DESIGN.md). kit/ (task 1003320) is the look-before-you-ship kit: lib.js (the floors, the states/probes contracts, the action + expectation vocabularies, the WCAG maths, the stub spawner), serve.js (any surface through the doorway's real transforms + fixtures/), render.js (states × 1440/390/320 × dark/light, audited), probe.js (PASS/FAIL contracts), check-mock.js (platform rules + the instance's DESIGN.md taste bans), contrast.js + png.js; a page's <page>.states.json / <page>.probes.json sit BESIDE the surface (public-landing/, modules/hall-ui/public/). Recipe: docs/recipes/ui-look-before-you-ship.md. skills/ (task 1003321 / ADR 0198) is the vendoring policy: policy.json (licence allowlist, verdicts that may land, sidecar fields, preamble markers), PREAMBLE.md (the platform preamble every vendored SKILL.md opens with), README.md (the roster — both origins scanned dangerous on 2026-08-28, landed as rebuild specs; nothing vendored — and the landing recipe); a landable copy goes under skills/vendor/<name>/ with PROVENANCE.md + LICENSE and is materialised into an instance's .claude/skills/ by claude-materialize.js step 1b. Reserved home styles/ (1003323) with a README. config/design-tokens.* + design-sources.json STAY in config/ as the host boundary; public-landing keeps its own key (first customer, not owner).
 │   ├── character-anim/          ← consistent-character generative animation (ADR 0088) — graded painterly frame sets + manifest, the otb-character-review skill. CLAUDE.md, module.json.
 │   ├── provisioning/            ← stands up + operates a Cloud Bongos instance's own infra (server/DB/domain/DNS/TLS) via the API (ADR 0111); web-tier request+state only, no cloud tokens — a separate control-plane runner drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute workloads. CLAUDE.md, module.json.
 │   └── demo/                    ← BV1.R52 acceptance-proof module: one rank-gated write route + one namespaced migration proving the loader mounts a scaffolded module with zero core edits. CLAUDE.md, module.json.

package/docs/recipes/ui-look-before-you-ship.md

@@ -0,0 +1,113 @@
+# Look before you ship — the ui-design kit
+
+> The `ui-design` module's kit (`modules/ui-design/kit/`, [task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../adr/<redacted>.md)): a stub, a renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance. Plain Node; the browser is the system Edge or Chrome (nothing is downloaded). The `/design` playbook sends you here.
+
+The loop is five commands and one habit: **stub → render → probe → read the shots → fix in one batch → re-run once.** A surface describes itself in two small JSON files beside it; the kit never hardcodes a page.
+
+## 0. Once per machine
+
+```
+npm install                       # playwright-core is a devDependency; no browser download
+```
+
+Edge or Chrome must be installed. If neither launches, every kit command prints one line saying so and exits 3.
+
+## 1. Stub — serve the surface the way the instance would
+
+```
+node modules/ui-design/kit/serve.js                          # public-landing at http://127.0.0.1:3412/
+AUTH=1 STUB_PORT=3413 node modules/ui-design/kit/serve.js    # the same, signed in (/me answers { builder })
+SURFACE=hall-ui PREFIX=/builders/ node modules/ui-design/kit/serve.js
+CHILD=1 node modules/ui-design/kit/serve.js                  # the child-instance shape (apex-only regions stripped)
+LIVE=1 node modules/ui-design/kit/serve.js                   # public feeds proxied to the pack's public origin
+FAIL=featured,progress node modules/ui-design/kit/serve.js   # those feeds answer 500
+```
+
+The stub runs the page through the **instance's real transforms** — the apex-only strip, the brand-token stamp, the pack's theme injection, run by the core-side command `scripts/gds/ui-kit-transform.js` (a module may not require core, so the stub spawns the command and memoises the page) — then the content-hash `?v=` stamp, with the instance's own branding pack, and answers the public feeds from `kit/fixtures/`. It also serves `docs/` raw, so a mock under `docs/design/mocks/` renders with its relative links: `http://127.0.0.1:3412/docs/design/mocks/hub/v2.html`.
+
+`SURFACE` is a checkout directory (`public-landing`, `modules/hall-ui/public`) or a module key whose manifest declares a `webSurfaces` dir. `PREFIX` is the URL prefix the surface's pages and assets live under (the hall's is `/builders/`).
+
+## 2. Render — every state, every width, both modes, audited
+
+```
+node modules/ui-design/kit/render.js --page /projects
+node modules/ui-design/kit/render.js --page /                       # MSYS_NO_PATHCONV=1 in Git Bash, or the kit reads the mangled root back
+node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui
+node modules/ui-design/kit/render.js --page /projects --only in-map,card --modes dark --sizes 390
+```
+
+`render.js` starts its own two stubs (signed out, signed in), renders each state of the page's **states file** in dark + light at 1440×900 / 390×844 / 320×700, drives the state's actions, and audits every render against the **platform floors**:
+
+| Floor | What fails it |
+|---|---|
+| `console-errors` | a `console.error` or an uncaught page error (the file's `ignoreConsole` regexes excepted) |
+| `failed-requests` | a 4xx/5xx response the file did not declare in `ignoreRequests` |
+| `horizontal-overflow` | `scrollWidth` wider than the viewport |
+| `one-header-main-h1` | not exactly one *rendered* `<header>`, `<main>` and `<h1>` |
+| `controls-24px` | a visible control under 24px on either side (`ignoreControls` for the skip link and the like) |
+| `top-bar-80px` | a `<header>` taller than 80px |
+| `reduced-motion` | under `prefers-reduced-motion` an animation still runs or a `requestAnimationFrame` loop ticks |
+
+Then a state's own `expect` (a band open, a dialog present, a field's value, a class, a query param). Shots and `report.json` land in `%TMP%/ui-design-kit/<surface>/<page>/` (or `--out`). Exit 0 is `ALL CLEAN`; 1 lists the problems; 2 is a broken states file, named line by line.
+
+### The states file — `<surface>/<page>.states.json`
+
+```json
+{
+  "page": "/projects",
+  "surface": "public-landing",
+  "modeQuery": "mode",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/my-projects"],
+  "ignoreConsole": ["\\b401\\b"],
+  "ignoreControls": [".skip", ".vh"],
+  "states": {
+    "out-map": { "auth": false, "expect": { "expanded": false } },
+    "in-map-projects": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProjects" } },
+    "card": { "auth": true, "actions": [["dispatchClick", "#orbField a.worldOrb:not(#selfOrb)"], ["wait", 600]], "expect": { "dialog": true } }
+  },
+  "reducedMotion": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 100]] }
+}
+```
+
+Actions: `click`, `focus`, `press`, `fill`, `wait`, `clickAt x y`, `clickIfVisible`, `dispatchClick`, `check`, `back`, `forward`. Expectations: `expanded`, `dialog`, `visible[]`, `hidden[]`, `open`, `closed`, `activeId`, `activeText`, `expandedIds[]`, `param{}`, `attr[[sel,name,value]]`, `text[[sel,value]]`, `href[[sel,value]]`, `count[[sel,n]]`, `value[[sel,v]]`, `hasClass[[sel,class,bool]]`, `checked`, `noOverflow`. The kit validates the file before it opens a browser and names every problem.
+
+The worked examples: `public-landing/projects.states.json` (the hub's thirteen), `public-landing/index.states.json` (the landing's four), `modules/hall-ui/public/ranks.states.json` (a second surface under its own prefix — it renders **red**, deliberately: the hall predates the 24px floor and Ranks has no `<h1>`, and the states file declares the shell's un-fixtured feeds rather than hiding the findings; idea 1000863 carries them).
+
+## 3. Probe — the interaction contract, as PASS/FAIL lines
+
+```
+node modules/ui-design/kit/probe.js --page /projects
+node modules/ui-design/kit/probe.js --page / --only "Escape"
+```
+
+A **probes file** (`<surface>/<page>.probes.json`) is a sequence: each probe opens the page (or continues the previous probe's page with `"continue": true`), drives steps from the same action vocabulary, and states what must be true with the same expectations. An uncaught page error during a probe fails it. The disclosure contract ships first — `public-landing/projects.probes.json` (24 probes: Enter opens on the first item, arrows cycle and skip hidden cells, Escape returns focus, Tab out closes, a click outside closes, one band closes the other, the views, the card yields Escape, the fold under 480, signed out nothing throws) and `index.probes.json` (10, the landing).
+
+## 4. Read the shots, fix in one batch, re-run once
+
+Open the shots directory. Look at the 390 and 320 renders first (the fold, the bar, the bands), then dark, then the states you touched. Fix everything you see in **one** batch — a render pass costs a minute, a change-render-change loop costs the afternoon — then re-run `render.js` and `probe.js` once. Ship the tests with the change: a new interactive behaviour gets a pin in the page's own test file in the same diff.
+
+## 5. Two more probes, for a mock and for colour
+
+```
+node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html [--states out-map,card] [--keys THESIS,BAR]
+node modules/ui-design/kit/contrast.js --pack
+node modules/ui-design/kit/contrast.js --url http://127.0.0.1:3412/projects --glyphs "#projTrig,.foot a"
+```
+
+`check-mock.js` runs the mechanical rules over a self-contained mock before anyone looks at it: the **platform's** (no page-local `:root`, page tokens on `body`, every dark rule written twice byte-identical, no literal colour beyond black/white with alpha, no pack colour pinned, the `?state=` contract, a head comment after `<body>`, one header/main/h1 + a skip link, apex-only sentinels balanced, no `innerHTML`, no motion in JavaScript, transitions ≤ 400ms) and the **instance's taste bans**, read from its `DESIGN.md` "Don't" section (an em/en dash, emoji, gradient text, a coloured glow, a box shadow). The em dash ban is Cloud Bongos's, not the platform's: an instance whose `DESIGN.md` never mentions it is not held to it.
+
+`contrast.js --pack` measures the instance's own pack — every ink on every ground, light values — with no browser. `--url`/`--file` walks every visible text element in both modes and computes the real WCAG ratio against its *composited* background; `--glyphs` screenshots named elements and reads the glyph pixels against the local ground's median, for text over a moving or textured ground where the stylesheet cannot say what is under it.
+
+## When it goes wrong
+
+| Symptom | Cause | Do |
+|---|---|---|
+| `no states file beside the surface: …/Git.states.json` | Git Bash turned `--page /` into the MSYS root | the kit reads it back as `/`; or `MSYS_NO_PATHCONV=1 node …` |
+| `no system browser` (exit 3) | neither Edge nor Chrome is installed | install one; the kit never downloads a browser |
+| `failed-requests: 404 …/api/bongos/goals` on a hall page | the shell polls feeds the stub does not fixture | declare them in the states file's `ignoreRequests` (the hall's does) — or add a fixture under `kit/fixtures/` and the route in `serve.js` |
+| `controls-24px: button.trig "builder" 13x44` | the chip sized itself by a missing avatar | the fixture builder's avatar is served by the stub (`/__kit/avatar.svg`); a page that rejects non-http avatars gets it absolutised |
+| a probe times out on `click` | an earlier probe in the chain left the page in another state | fix the earlier FAIL first; chains are sequences |
+
+## What the kit is not
+
+Not CI: `tests/ui_design_kit.mjs` pins the contract (the floors, the file shapes, the audit, the mock rules, the pack, the exit codes, the stub) without a browser; the renders are yours to run and look at. Not a screenshot-diff tool: it audits against floors and expectations, not against a golden image. Not an instance's taste: everything <redacted> lives in the states/probes files beside Cloud Bongos's pages and in its `DESIGN.md`.

package/modules/hall-ui/public/ranks.states.json

@@ -0,0 +1,15 @@
+{
+  "_": "The hall's Ranks page as the SECOND surface through modules/ui-design/kit/render.js (task 1003320): the hall serves under /builders/, signed out and in.",
+  "page": "/builders/ranks",
+  "surface": "hall-ui",
+  "stub": { "prefix": "/builders/" },
+  "modeQuery": false,
+  "_feeds": "The hall's shell polls goals + inbox + profile feeds on every page; the stub fixtures only the public feeds, so those 404s are declared here, not hidden by the kit. The 24px-floor and h1 findings the render reports are REAL (the hall predates the floor) and are deliberately not ignored.",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox/", "/api/(gds|bongos)/me/"],
+  "ignoreConsole": ["/api/(gds|bongos)/me", "\\b401\\b", "Unauthorized", "404 \\(Not Found\\)", "goals load failed"],
+  "states": {
+    "out": { "auth": false },
+    "in": { "auth": true }
+  },
+  "reducedMotion": { "auth": true }
+}

package/modules/ui-design/kit/README.md

@@ -1,3 +1,13 @@
-# `modules/ui-design/kit/` — reserved home for the look-before-you-ship kit
+# `modules/ui-design/kit/` — look before you ship
 
-Lands with [task 1003320](https://cloudbongos.com/builders#/task/1003320): an instance-agnostic stub server, a renderer/auditor (every state × width × mode, with the contrast audit), the interaction probes and the mock checker any builder points at any surface. Until it lands, the apex probes live in session scratchpads (see the [module CLAUDE.md](../CLAUDE.md)).
+The stub, the renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance ([task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../../../docs/adr/<redacted>.md)). Plain Node; the browser is the system Edge or Chrome via `playwright-core` (a devDependency — nothing is downloaded).
+
+```
+node modules/ui-design/kit/serve.js                     # the stub (SURFACE, PREFIX, AUTH=1, CHILD=1, LIVE=…, FAIL=…, STUB_PORT)
+node modules/ui-design/kit/render.js --page /projects   # every state × 1440/390/320 × dark/light, audited against the floors
+node modules/ui-design/kit/probe.js  --page /projects   # the interaction contract as PASS/FAIL lines
+node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html
+node modules/ui-design/kit/contrast.js --pack | --url <url> [--glyphs sel,sel]
+```
+
+A surface describes itself in two JSON files beside it — `<page>.states.json` and `<page>.probes.json` — in the vocabularies `lib.js` defines and validates. The full loop, the file shapes and the failure table: [`docs/recipes/ui-look-before-you-ship.md`](../../../docs/recipes/ui-look-before-you-ship.md). Exit codes everywhere: 0 clean · 1 problems · 2 a broken file or usage · 3 no browser.