@bongos/core 1.19.393 → 1.19.395

package/docs/file-map.md

@@ -129,6 +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).
 │   ├── 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.
@@ -373,6 +374,7 @@ tests/
 ├── builder-start/SKILL.md         ← /builder-start — list claimable tasks (parallel-safe vs active claims)
 ├── builder-sync/SKILL.md          ← /builder-sync — 'sync now': re-run the box source-fetch on demand so a freshly-claimed task's code lands within seconds, re-scoped to the active claim (BV1.R96, ADR 0148)
 ├── close-box/SKILL.md             ← /close-box — tear down the dev box you're working on, from inside the box terminal (POST /box/close)
+├── design/SKILL.md                ← /design — the UI design session: the operating playbook for ui-discipline work on ANY instance (load the instance's pack + DESIGN.md first, look before you ship, build inside the platform floors, ship the tests with the UI); routed from a `ui` claim via discipline-modes.json; shipped by the ui-design module (task 1003324, ADR 0197)
 ├── design-sync/SKILL.md           ← /design-sync — export repo design tokens + surfaces into Claude Design (token-preview bundle) and land generated UI code back as a GDS task (ADR 0081)
 ├── dev/SKILL.md                   ← /dev — engineering-session playbook for engineer-discipline tasks; the default understand→scoped-change→verify→ship loop made explicit ([#1272](https://example.com/builders#/task/1272))
 ├── feedback/SKILL.md              ← /feedback — pull the latest Bongos feedback bundle (prompt.md + screenshot file paths) into a Claude Code session; backed by scripts/gds/feedback-latest.js (BV1.R13, ADR 0087)

package/docs/modules-contract.md

@@ -246,6 +246,7 @@ Rules (enforced by the `BV1.R45` fitness check):
 | **`hall-ui`** *(core-domain web surface, default-on; R85)* | webSurfaces: `{ host: "builders.", dir: "public" }` (the authenticated builders' hall) | — (registers NO port; keeps a DEDICATED serving block in `serve-internal.js`, unlike `status-ui`) | `^1.11.0` |
 | **`lifecycle`** *(core-domain, default-on; R86)* | routes: `tasks`, `claims`, `versions`, `done-when`, `goals`, `dependencies`, `gate-approvals`, `analytics` | provides `lifecycle` (createTask, classifyTaskKind, tallyPeerVotes, work-tracking reads); resolves `reward`, `onboarding` | `^1.12.0` |
 | **`provisioning`** *(default-off; [ADR 0111](adr/<redacted>.md))* | routes: `provisioning` (own+Archon rank-gated) | provides `provisioning.instanceState` | `^1.14.0` |
+| **`ui-design`** *(core-domain, default-on; [ADR 0197](adr/<redacted>.md))* | skills: `design`, `design-sync`, `figma-design-sync` (the /design playbook + the two tool round-trips); the ADR 0081 adapters, sync CLIs and validator live in the module dir | — (registers NO port, NO routes; declaration-only — disabling it withdraws the skills and touches no served surface) | `^1.19.0` |
 
 Each module's `modules/<key>/CLAUDE.md` is the authoritative per-module reference (files, seams, tests, what is NOT in the module).
 

package/docs/onboarding/slash-commands.md

@@ -66,7 +66,7 @@ Every one of these talks to the build system. They're grouped by when you'd reac
 
 ### Design and art pipeline
 
-`/design-sync` and `/figma-design-sync` round-trip the UI design system. The `/otb-*` family — `otb-tile-generate`, `otb-design-review`, `otb-character-review`, `otb-feedback-capture`, `otb-figma-sync` — is the reference instance's pixel-art pipeline; it's only meaningful on an instance that runs that pipeline.
+`/design` is the ui-discipline playbook (world-first, show-first — shipped by the `ui-design` module, ADR 0197); `/design-sync` and `/figma-design-sync` round-trip the UI design system. The `/otb-*` family — `otb-tile-generate`, `otb-design-review`, `otb-character-review`, `otb-feedback-capture`, `otb-figma-sync` — is the reference instance's pixel-art pipeline; it's only meaningful on an instance that runs that pipeline.
 
 ### Session and meta
 

package/docs/recipes/claude-design-loop.md

@@ -2,8 +2,8 @@
 
 > End-to-end guide for the repo ↔ Claude Design sync cycle.
 > ADR: [ADR 0081](../adr/<redacted>.md).
-> Adapter: `src/ui/adapters/claude-design/index.js`.
-> CLI: `scripts/gds/design-sync.js`.
+> Adapter: `modules/ui-design/adapters/claude-design/index.js` (the `ui-design` module — ADR 0197).
+> CLI: `modules/ui-design/scripts/design-sync.js` (`scripts/gds/design-sync.js` is a thin shim over it).
 > Skill: `.claude/skills/design-sync/SKILL.md`.
 
 ---
@@ -93,7 +93,7 @@ When Claude Design's output is ready:
 **b. Run the export step** — either via the skill or directly:
 
 ```js
-const adapter = require('./src/ui/adapters/claude-design/index.js');
+const adapter = require('./modules/ui-design/adapters/claude-design/index.js');
 const result = await adapter.export({
   repoRoot: process.cwd(),
   surfaceId: 'hall-ui',

package/docs/recipes/figma-design-loop.md

@@ -2,8 +2,8 @@
 
 > End-to-end guide for the repo ↔ Figma sync cycle — the human escape hatch in ADR 0081.
 > ADR: [ADR 0081](../adr/<redacted>.md).
-> Adapter: `src/ui/adapters/figma/index.js`.
-> CLI: `scripts/gds/figma-design-sync.js`.
+> Adapter: `modules/ui-design/adapters/figma/index.js` (the `ui-design` module — ADR 0197).
+> CLI: `modules/ui-design/scripts/figma-design-sync.js` (`scripts/gds/figma-design-sync.js` is a thin shim over it).
 > Skill: `.claude/skills/figma-design-sync/SKILL.md`.
 >
 > Not to be confused with `otb-figma-sync` (pixel-art tile review, a separate Figma file, a separate concern).
@@ -72,7 +72,7 @@ The designer opens the pushed frames (or an existing component) and makes a manu
 
 **Code Connect output (ready code):**
 ```js
-const adapter = require('./src/ui/adapters/figma/index.js');
+const adapter = require('./modules/ui-design/adapters/figma/index.js');
 const result = await adapter.export({
   repoRoot: process.cwd(),
   surfaceId: 'hall-ui',
@@ -113,7 +113,7 @@ node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 
 ## Code-canonical vs. Figma-canonical
 
-Code-canonical is the default: the repo is authoritative, the Figma file is a synced view. A surface may be flagged `"figmaCanonical": true` in its `config/design-sources.json` entry (docs/design-contract.md §3.4) as an explicit exception for a design-system foundation a dedicated designer actively iterates on in Figma. All other surfaces stay code-canonical.
+Code-canonical is the default: the repo is authoritative, the Figma file is a synced view. A surface may be flagged `"figmaCanonical": true` in its `config/design-sources.json` entry (modules/ui-design/docs/design-contract.md §3.4) as an explicit exception for a design-system foundation a dedicated designer actively iterates on in Figma. All other surfaces stay code-canonical.
 
 ---
 

package/modules/ui-design/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/{src/ui → modules/ui-design}/adapters/claude-design/index.js

@@ -1,7 +1,7 @@
 'use strict';
 // Claude Design adapter — wires the repo design system to Claude Design.
 //
-// Conforms to the adapter interface in docs/design-contract.md §4.
+// Conforms to the adapter interface in modules/ui-design/docs/design-contract.md §4.
 //
 // import(opts): repo → Claude Design
 //   Resolves design tokens, scans src/ui/ surfaces, and writes a token-preview

package/{src/ui → modules/ui-design}/adapters/figma/index.js

@@ -1,7 +1,7 @@
 'use strict';
 // Figma adapter — the human escape hatch in ADR 0081's tool-agnostic design layer.
 //
-// Conforms to the adapter interface in docs/design-contract.md §4.
+// Conforms to the adapter interface in modules/ui-design/docs/design-contract.md §4.
 //
 // import(opts): repo → Figma
 //   Resolves design tokens + surfaces and builds a "push plan" (frames to
@@ -26,7 +26,7 @@ const os = require('node:os');
 const ID = 'figma';
 
 // Figma node types that carry no code-representable content — the round-trip
-// is honestly lossy here (docs/design-contract.md §2.3 / ADR 0081).
+// is honestly lossy here (modules/ui-design/docs/design-contract.md §2.3 / ADR 0081).
 const ASSET_ONLY_NODE_TYPES = new Set(['VECTOR', 'BOOLEAN_OPERATION', 'STAR', 'ELLIPSE', 'LINE']);
 
 // ── token helpers ─────────────────────────────────────────────────────────────
@@ -170,7 +170,7 @@ function componentNameFor(node) {
 // Walks a Figma node snapshot and produces { files, warnings } — files are
 // only emitted for nodes whose content is genuinely code-representable
 // (frames, text, solid-fill rectangles). Image/vector content is skipped with
-// a warning, matching the asset-not-code rule (docs/design-contract.md §2.3).
+// a warning, matching the asset-not-code rule (modules/ui-design/docs/design-contract.md §2.3).
 function snapshotToFiles(surfaceId, snapshot, colorTokenIndex) {
   const files = [];
   const warnings = [];

package/{docs → modules/ui-design/docs}/design-contract.md

@@ -1,8 +1,8 @@
 # Design contract — neutral adapter interface
 
-**Status:** Accepted · authored by [task 1377](https://example.com/builders#/task/1377) · governed by [ADR 0081](adr/<redacted>.md)
+**Status:** Accepted · authored by [task 1377](https://example.com/builders#/task/1377) · governed by [ADR 0081](../../../docs/adr/<redacted>.md) · lives in the `ui-design` module since [task 1003324](https://cloudbongos.com/builders#/task/1003324) ([ADR 0197](../../../docs/adr/<redacted>.md)) — the token files it names stay in `config/` as the host boundary
 
-The repo is the single source of truth for design. Every design tool is a swappable adapter that reads from and writes to this contract — it does not own the source. This file is the contract every adapter must conform to. The minimal validator (`scripts/gds/validate-design.js`) enforces the machine-checkable parts.
+The repo is the single source of truth for design. Every design tool is a swappable adapter that reads from and writes to this contract — it does not own the source. This file is the contract every adapter must conform to. The minimal validator (`modules/ui-design/scripts/validate-design.js`; `node scripts/gds/validate-design.js` is a thin shim over it) enforces the machine-checkable parts.
 
 ---
 
@@ -96,7 +96,7 @@ Rules:
 | Freeform canvas art | — | `assets/ui/<surface>/` | Asset |
 | Pixel-art game tiles | see `art/` pipeline | — | Art pipeline (not this contract) |
 
-Pixel-art game tiles (world tiles, characters, objects) are out of scope for this contract — they are governed by the `art/` pipeline and [ADR 0088](adr/<redacted>.md).
+Pixel-art game tiles (world tiles, characters, objects) are out of scope for this contract — they are governed by the `art/` pipeline and [ADR 0088](../../../docs/adr/<redacted>.md).
 
 ---
 
@@ -152,7 +152,7 @@ Figma-canonical is appropriate for design-system foundations that a dedicated de
 Each design tool that integrates with this contract must provide an adapter module. An adapter lives at:
 
 ```
-src/ui/adapters/<id>/index.js   (e.g. claude-design, figma)
+modules/ui-design/adapters/<id>/index.js   (e.g. claude-design, figma)
 ```
 
 ### 4.1 Required exports
@@ -235,7 +235,7 @@ module.exports = {
 
 ### 4.6 Adapter registration
 
-Adapters are discovered by the design subsystem at runtime. No static registry — the loader walks `src/ui/adapters/*/index.js` and requires each, verifying the `id` field is present. A missing or broken adapter is a non-fatal warning; the unaffected adapters continue loading.
+Adapters are discovered by the design subsystem at runtime. No static registry — the loader walks `modules/ui-design/adapters/*/index.js` and requires each, verifying the `id` field is present. A missing or broken adapter is a non-fatal warning; the unaffected adapters continue loading.
 
 ### 4.7 Adapter error contract
 
@@ -280,7 +280,7 @@ The `--dt-` prefix is reserved for this design system. Adapters must not emit CS
 
 ## 6. Validator
 
-`scripts/gds/validate-design.js` is the minimal validator for this contract. It checks:
+`modules/ui-design/scripts/validate-design.js` is the minimal validator for this contract (`node scripts/gds/validate-design.js` is a thin shim over it). It checks:
 
 1. `config/design-tokens.neutral.json` exists and validates against the schema.
 2. If `config/design-tokens.json` exists, it validates against the schema.
@@ -288,19 +288,19 @@ The `--dt-` prefix is reserved for this design system. Adapters must not emit CS
 4. `config/design-sources.json` is valid JSON and every surface entry has a `tool` field from the allowed enum.
 5. Every `sourceUrl` in `design-sources.json` is a valid URI string.
 6. Every `surfaceId` key in `design-sources.json` has a matching directory under `src/ui/` or `assets/ui/` (if any such directory exists — the file may precede the directories for a new instance).
-7. If `src/ui/adapters/` exists, each adapter directory has an `index.js` that exports `id`, `import`, and `export`.
+7. If `modules/ui-design/adapters/` exists, each adapter directory has an `index.js` that exports `id`, `import`, and `export`.
 
 The neutral-pair lockstep (§1.3) is deliberately not a validator check — it lives in `tests/design_tokens_sync.mjs`, so an instance running only `validate-design.js` is not forced to mirror its own pack.
 
 Usage:
 
 ```
-node scripts/gds/validate-design.js           # exits 0 on pass, 1 on failure
-node scripts/gds/validate-design.js --json    # machine-readable report
-node scripts/gds/validate-design.js --strict  # fail on warnings too
+node modules/ui-design/scripts/validate-design.js           # exits 0 on pass, 1 on failure
+node modules/ui-design/scripts/validate-design.js --json    # machine-readable report
+node modules/ui-design/scripts/validate-design.js --strict  # fail on warnings too
 ```
 
-The validator is hooked into `scripts/gds/fitness.js` as an opt-in check (enabled once the first adapter is committed — task 1378 or 1379).
+The validator is wired into `scripts/gds/fitness.js` (`checkDesignContract` in `fitness-checks-identity.js`) and hard-fails while any adapter is present.
 
 ---
 
@@ -316,7 +316,7 @@ The validator is hooked into `scripts/gds/fitness.js` as an opt-in check (enable
 
 ## 8. Adding a new adapter
 
-1. Create `src/ui/adapters/<id>/index.js` exporting `{ id, import, export }`.
+1. Create `modules/ui-design/adapters/<id>/index.js` exporting `{ id, import, export }`.
 2. Add a `<surface-id>` entry to `config/design-sources.json` with `"tool": "<id>"`.
 3. Write a task for the adapter (it unblocks from [task 1377](https://example.com/builders#/task/1377)) and ship it under a claimed Bongos task.
 4. The validator discovers the adapter automatically on the next run.

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

@@ -0,0 +1,3 @@
+# `modules/ui-design/kit/` — reserved home for the look-before-you-ship kit
+
+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)).

package/modules/ui-design/module.json

@@ -0,0 +1,11 @@
+{
+  "key": "ui-design",
+  "title": "UI design (the design contract, its adapters and sync, the /design playbook, the kit, the skills, the styles)",
+  "description": "The platform capability that lets any builder on any instance create and design good-looking, functional UIs in line with that instance's world (scoped with the owner 2026-08-28; task 1003324, ADR 0197). It ships METHOD and never a world: the neutral design contract of ADR 0081 with its tool adapters (Claude Design, Figma), their sync CLIs and the validator; the /design playbook for ui-discipline work; and the reserved homes for the look-before-you-ship kit (kit/), the vetted UI skills (skills/) and the style library (styles/) the sibling tasks land. The instance's world — its branding pack, config/design-tokens.*, config/design-sources.json and its DESIGN.md — stays in config/ and at the repo root as the host boundary this module reads and never owns (ADR 0062 §7). Cloud Bongos's own front door is this module's first customer, not its owner. default-on because every instance has a face. No routes, no migrations, no port: declaration-only like character-anim, so disabling it withdraws only the skills it contributes and touches no served surface.",
+  "coreVersion": "^1.19.0",
+  "default": true,
+  "maintenance": { "status": "core-maintained" },
+  "contributes": { "skills": ["design", "design-sync", "figma-design-sync"] },
+  "provides": [],
+  "consumes": []
+}

package/modules/ui-design/scripts/design-sync.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Build a Claude Design token-preview bundle from the repo's design system.
+//
+// Usage:
+//   node modules/ui-design/scripts/design-sync.js                 — build bundle, print manifest JSON
+//   node modules/ui-design/scripts/design-sync.js --surface <id>  — limit to one surface
+//   (node scripts/gds/design-sync.js is a thin shim over this file — the form the skills use)
+//
+// Output (stdout, JSON):
+//   { bundlePath, files, surfaceIds, summary }
+//
+// The /design-sync skill calls this, then uses the DesignSync MCP tool
+// to push the bundle to a Claude Design project.
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+// The design system (src/ui/, config/design-tokens.json) is HOST content (ADR 0108
+// §1), and this CLI lives in a module, which may not reach src/instance-config.js
+// (the one-way rule, ADR 0083). The instance root IS the repo root this module sits
+// in today, so the walk-up is byte-identical to the resolveInstanceRoot() the
+// core-side entry used to call; when the core installs as a package the root
+// arrives through the doorway (task 1003324, ADR 0197).
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function arg(flag, args) {
+  const i = args.indexOf(flag);
+  return i !== -1 ? args[i + 1] : null;
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+  const targetSurface = arg('--surface', args) || undefined;
+
+  const adapter = require('../adapters/claude-design/index.js');
+
+  const result = await adapter.import({
+    repoRoot: REPO_ROOT,
+    ...(targetSurface ? { surfaces: [{ id: targetSurface, path: path.join(REPO_ROOT, 'src', 'ui', targetSurface) }] } : {}),
+  });
+
+  // Build the file list from the bundle dir for the skill to pass to finalize_plan
+  const { bundlePath, surfaceIds, summary } = result;
+  const files = collectFiles(bundlePath, bundlePath);
+
+  const manifest = { bundlePath, files, surfaceIds, summary };
+  process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+})().catch(err => {
+  process.stderr.write(`design-sync: ${err.message}\n`);
+  process.exit(1);
+});
+
+function collectFiles(dir, root) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...collectFiles(full, root));
+    } else {
+      out.push(path.relative(root, full));
+    }
+  }
+  return out;
+}

package/modules/ui-design/scripts/figma-design-sync.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Build a Figma push plan from the repo's design system (task 2048, redo of 1379).
+//
+// Usage:
+//   node modules/ui-design/scripts/figma-design-sync.js                 — build plan, print manifest JSON
+//   node modules/ui-design/scripts/figma-design-sync.js --surface <id>  — limit to one surface
+//   (node scripts/gds/figma-design-sync.js is a thin shim over this file — the form the skills use)
+//
+// Output (stdout, JSON):
+//   { planPath, files, surfaceIds, summary }
+//
+// The figma-design-sync skill calls this, then executes the plan's frames
+// against the live Figma MCP tool.
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+// The design system (src/ui/, config/design-tokens.json) is HOST content (ADR 0108
+// §1), and this CLI lives in a module, which may not reach src/instance-config.js
+// (the one-way rule, ADR 0083). The instance root IS the repo root this module sits
+// in today, so the walk-up is byte-identical to the resolveInstanceRoot() the
+// core-side entry used to call; when the core installs as a package the root
+// arrives through the doorway (task 1003324, ADR 0197).
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function arg(flag, args) {
+  const i = args.indexOf(flag);
+  return i !== -1 ? args[i + 1] : null;
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+  const targetSurface = arg('--surface', args) || undefined;
+
+  const adapter = require('../adapters/figma/index.js');
+
+  const result = await adapter.import({
+    repoRoot: REPO_ROOT,
+    ...(targetSurface ? { surfaces: [{ id: targetSurface, path: path.join(REPO_ROOT, 'src', 'ui', targetSurface) }] } : {}),
+  });
+
+  const { planPath, surfaceIds, summary } = result;
+  const files = collectFiles(planPath, planPath);
+
+  const manifest = { planPath, files, surfaceIds, summary };
+  process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+})().catch(err => {
+  process.stderr.write(`figma-design-sync: ${err.message}\n`);
+  process.exit(1);
+});
+
+function collectFiles(dir, root) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...collectFiles(full, root));
+    } else {
+      out.push(path.relative(root, full));
+    }
+  }
+  return out;
+}

package/modules/ui-design/scripts/validate-design.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+'use strict';
+// validate-design.js — minimal validator for the neutral design contract (task 1377).
+// See modules/ui-design/docs/design-contract.md §6 for the full spec. Lives in the
+// ui-design module since task 1003324 (ADR 0197); node scripts/gds/validate-design.js
+// is a thin shim over this file.
+//
+// Usage:
+//   node modules/ui-design/scripts/validate-design.js           # exits 0 on pass, 1 on failure
+//   node modules/ui-design/scripts/validate-design.js --json    # machine-readable { ok, errors, warnings }
+//   node modules/ui-design/scripts/validate-design.js --strict  # treat warnings as errors
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The instance root is the repo root this module sits in (ADR 0108 §1); a module
+// may not reach src/instance-config.js for it (ADR 0083).
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_MODE = ARGS.has('--json');
+const STRICT = ARGS.has('--strict');
+
+const NEUTRAL_TOKENS  = path.join(REPO_ROOT, 'config', 'design-tokens.neutral.json');
+const INSTANCE_TOKENS = path.join(REPO_ROOT, 'config', 'design-tokens.json');
+const TOKENS_SCHEMA   = path.join(REPO_ROOT, 'config', 'design-tokens.schema.json');
+const DESIGN_SOURCES  = path.join(REPO_ROOT, 'config', 'design-sources.json');
+const UI_SRC          = path.join(REPO_ROOT, 'src', 'ui');
+const UI_ASSETS       = path.join(REPO_ROOT, 'assets', 'ui');
+const ADAPTERS_DIR    = path.join(__dirname, '..', 'adapters'); // the module's own adapters
+
+const TOOL_ENUM = new Set(['claude-design', 'figma', 'hand', 'asset']);
+const REQUIRED_COLORS = ['bg', 'bgCard', 'ink', 'accent'];
+const REQUIRED_FONTS  = ['display', 'body'];
+
+const errors   = [];
+const warnings = [];
+
+function err(msg)  { errors.push(msg); }
+function warn(msg) { warnings.push(msg); }
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    err(`${label}: cannot read/parse — ${e.message}`);
+    return null;
+  }
+}
+
+function deepMerge(base, override) {
+  if (!override) return base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(override)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && typeof out[k] === 'object') {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function isUri(s) {
+  try { new URL(s); return true; } catch { return false; }
+}
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function listDirs(p) {
+  if (!dirExists(p)) return [];
+  return fs.readdirSync(p, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+}
+
+// ── Check 1: neutral tokens file exists + parses ─────────────────────────────
+
+const schema   = readJson(TOKENS_SCHEMA, 'config/design-tokens.schema.json');
+const neutral  = readJson(NEUTRAL_TOKENS, 'config/design-tokens.neutral.json');
+
+if (!neutral) {
+  err('config/design-tokens.neutral.json is missing — this is the required baseline');
+}
+
+// ── Check 2: instance tokens file, if present, parses ────────────────────────
+
+let instance = null;
+if (fileExists(INSTANCE_TOKENS)) {
+  instance = readJson(INSTANCE_TOKENS, 'config/design-tokens.json');
+}
+
+// ── Check 3: merged tokens satisfy required fields ───────────────────────────
+
+const merged = neutral ? deepMerge(neutral, instance) : null;
+
+if (merged) {
+  if (!merged.colors || typeof merged.colors !== 'object') {
+    err('merged tokens: "colors" group is missing');
+  } else {
+    for (const key of REQUIRED_COLORS) {
+      if (!merged.colors[key]) err(`merged tokens: colors.${key} is required but missing`);
+      else if (typeof merged.colors[key] !== 'string') err(`merged tokens: colors.${key} must be a string`);
+    }
+    for (const [key, val] of Object.entries(merged.colors)) {
+      if (typeof val !== 'string') err(`merged tokens: colors.${key} must be a string`);
+    }
+  }
+
+  if (!merged.fonts || typeof merged.fonts !== 'object') {
+    err('merged tokens: "fonts" group is missing');
+  } else {
+    for (const key of REQUIRED_FONTS) {
+      if (!merged.fonts[key]) err(`merged tokens: fonts.${key} is required but missing`);
+      else if (typeof merged.fonts[key] !== 'string') err(`merged tokens: fonts.${key} must be a string`);
+    }
+    if (merged.fonts.links !== undefined) {
+      if (!Array.isArray(merged.fonts.links)) {
+        err('merged tokens: fonts.links must be an array');
+      } else {
+        for (const link of merged.fonts.links) {
+          if (typeof link !== 'string' || !isUri(link)) {
+            err(`merged tokens: fonts.links entry is not a valid URI: ${link}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Optional groups: check value types if present
+  if (merged.scale) {
+    for (const [k, v] of Object.entries(merged.scale)) {
+      if (typeof v !== 'string') err(`merged tokens: scale.${k} must be a string`);
+    }
+  }
+  if (merged.radius) {
+    for (const [k, v] of Object.entries(merged.radius)) {
+      if (typeof v !== 'string') err(`merged tokens: radius.${k} must be a string`);
+    }
+  }
+  if (merged.motion) {
+    for (const [k, v] of Object.entries(merged.motion)) {
+      if (typeof v !== 'string') err(`merged tokens: motion.${k} must be a string`);
+    }
+  }
+}
+
+// ── Check 4: design-sources.json is valid + entries have required fields ─────
+
+let sources = null;
+if (fileExists(DESIGN_SOURCES)) {
+  sources = readJson(DESIGN_SOURCES, 'config/design-sources.json');
+  if (sources) {
+    if (!sources.surfaces || typeof sources.surfaces !== 'object') {
+      err('config/design-sources.json: "surfaces" key must be an object');
+    } else {
+      for (const [surfaceId, entry] of Object.entries(sources.surfaces)) {
+        if (!entry || typeof entry !== 'object') {
+          err(`design-sources: surface "${surfaceId}" entry must be an object`);
+          continue;
+        }
+        if (!entry.tool) {
+          err(`design-sources: surface "${surfaceId}" is missing "tool" field`);
+        } else if (!TOOL_ENUM.has(entry.tool)) {
+          err(`design-sources: surface "${surfaceId}" tool "${entry.tool}" is not in allowed enum (${[...TOOL_ENUM].join(', ')})`);
+        }
+        if (entry.sourceUrl !== undefined) {
+          if (typeof entry.sourceUrl !== 'string' || !isUri(entry.sourceUrl)) {
+            err(`design-sources: surface "${surfaceId}" sourceUrl is not a valid URI`);
+          }
+        } else if (entry.tool && !['hand', 'asset'].includes(entry.tool)) {
+          warn(`design-sources: surface "${surfaceId}" tool "${entry.tool}" has no sourceUrl`);
+        }
+        if (entry.lastSyncedAt !== undefined) {
+          if (typeof entry.lastSyncedAt !== 'string' || isNaN(Date.parse(entry.lastSyncedAt))) {
+            err(`design-sources: surface "${surfaceId}" lastSyncedAt is not a valid ISO 8601 date`);
+          }
+        }
+      }
+    }
+  }
+} else {
+  warn('config/design-sources.json not found — this is optional until adapters are in use');
+}
+
+// ── Check 5: design-sources surface ids match directories (if dirs exist) ─────
+
+const hasUiSrc    = dirExists(UI_SRC);
+const hasUiAssets = dirExists(UI_ASSETS);
+
+if (sources && sources.surfaces) {
+  const uiSrcDirs    = hasUiSrc    ? new Set(listDirs(UI_SRC)) : new Set();
+  const uiAssetsDirs = hasUiAssets ? new Set(listDirs(UI_ASSETS)) : new Set();
+
+  for (const surfaceId of Object.keys(sources.surfaces)) {
+    const inSrc    = uiSrcDirs.has(surfaceId);
+    const inAssets = uiAssetsDirs.has(surfaceId);
+    if (!inSrc && !inAssets && (hasUiSrc || hasUiAssets)) {
+      warn(`design-sources: surface "${surfaceId}" has no matching directory in src/ui/ or assets/ui/`);
+    }
+  }
+}
+
+// ── Check 6: adapter directories have valid index.js ─────────────────────────
+
+if (dirExists(ADAPTERS_DIR)) {
+  for (const adapterName of listDirs(ADAPTERS_DIR)) {
+    const indexPath = path.join(ADAPTERS_DIR, adapterName, 'index.js');
+    if (!fileExists(indexPath)) {
+      err(`adapter "${adapterName}": missing index.js at modules/ui-design/adapters/${adapterName}/index.js`);
+      continue;
+    }
+    let mod;
+    try {
+      mod = require(indexPath);
+    } catch (e) {
+      err(`adapter "${adapterName}": index.js threw on require — ${e.message}`);
+      continue;
+    }
+    if (typeof mod.id !== 'string' || !mod.id) {
+      err(`adapter "${adapterName}": index.js must export a non-empty string "id"`);
+    } else if (mod.id !== adapterName) {
+      warn(`adapter "${adapterName}": exported id "${mod.id}" does not match directory name`);
+    }
+    if (typeof mod.import !== 'function') {
+      err(`adapter "${adapterName}": index.js must export an "import" function`);
+    }
+    if (typeof mod.export !== 'function') {
+      err(`adapter "${adapterName}": index.js must export an "export" function`);
+    }
+  }
+}
+
+// ── Report ────────────────────────────────────────────────────────────────────
+
+const effectiveErrors = STRICT ? [...errors, ...warnings] : errors;
+const ok = effectiveErrors.length === 0;
+
+if (JSON_MODE) {
+  process.stdout.write(JSON.stringify({ ok, errors, warnings }, null, 2) + '\n');
+} else {
+  const label = ok ? '✓ design contract valid' : '✗ design contract invalid';
+  process.stdout.write(`${label}\n`);
+  for (const e of errors)   process.stdout.write(`  ERROR   ${e}\n`);
+  for (const w of warnings) process.stdout.write(`  WARNING ${w}\n`);
+  if (ok && !STRICT && warnings.length) {
+    process.stdout.write(`  (${warnings.length} warning(s); use --strict to fail on warnings)\n`);
+  }
+}
+
+process.exit(ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+# `modules/ui-design/skills/` — reserved home for the vetted UI skills
+
+Lands with [task 1003321](https://cloudbongos.com/builders#/task/1003321): the vendored design skills (impeccable, the style/taste skills, image-to-code, imagegen, brandkit), each scanned with `/scan-before-install`, carrying a PROVENANCE sidecar and a licence on the allowlist, and prefixed with the PLATFORM PREAMBLE that reads the instance's branding pack and `DESIGN.md` before any taste rule applies. The vendoring policy is that task's ADR; [ADR 0197](../../../docs/adr/<redacted>.md) only points at it.

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

@@ -0,0 +1,3 @@
+# `modules/ui-design/styles/` — reserved home for the style library
+
+Lands with [task 1003323](https://cloudbongos.com/builders#/task/1003323): looks shipped as branding packs (the fifteen host-overridable tokens plus a `DESIGN.md` per look), with two alternates beside the chrome world, so an instance picks a world instead of inheriting Cloud Bongos's. A look is a pack; it is never a page's private palette.