@bongos/core 1.19.394 → 1.19.396

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.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.394",
+  "version": "1.19.396",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.394",
+      "version": "1.19.396",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.394",
+  "version": "1.19.396",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/copy-inventory.js

@@ -16,10 +16,12 @@
 // machine-readable registry and one human report. Same posture as gen-repo-map /
 // gen-api-docs: a command you run and commit.
 //
-// THE SURFACE MISMATCH, RECORDED RATHER THAN ASSUMED AWAY. docs/design-contract.md
-// says UI components live under `src/ui/<surface>/`, and that a surface directory is
-// the unit a design adapter targets. On this tree `src/ui/` contains only
-// `adapters/` — the real UI is modules/hall-ui/public and modules/status-ui/public.
+// THE SURFACE MISMATCH, RECORDED RATHER THAN ASSUMED AWAY. The design contract
+// (modules/ui-design/docs/design-contract.md) says UI components live under
+// `src/ui/<surface>/`, and that a surface directory is the unit a design adapter
+// targets. This tree has no `src/ui/` at all (the adapters moved to
+// modules/ui-design/adapters/ in task 1003324) — the real UI is modules/hall-ui/public
+// and modules/status-ui/public.
 // So this tool maps REAL paths onto contract-shaped surface ids and reports the
 // mismatch in its own output. Do not "fix" that by pretending the contract layout
 // exists.
@@ -76,7 +78,7 @@ const BLIND_SPOTS = [
   'Template literals containing a nested backtick: the literal scanner stops at the first closing backtick, so a nested template inside `${...}` truncates that one literal. Rare in this tree and cheap to spot (a row that ends mid-sentence); a real JS parser is the fix if it ever matters.',
   'Runtime-composed strings: anything assembled from fragments or interpolated at render time is captured only as its literal parts. A sentence that exists only once the browser runs cannot be inventoried by reading the tree.',
   'Generated pages: `docs/api-reference.md` and the OpenAPI surface are generated from route prose; that copy belongs to its generator, not to a designer.',
-  'The design-contract surface layout: `docs/design-contract.md` expects `src/ui/<surface>/`, which this tree does not use (`src/ui` holds only `adapters/`). Surface ids here are a MAPPING onto real paths, not evidence the contract layout exists.',
+  'The design-contract surface layout: `modules/ui-design/docs/design-contract.md` expects `src/ui/<surface>/`, which this tree does not use (there is no `src/ui/`; the adapters live in `modules/ui-design/adapters/`). Surface ids here are a MAPPING onto real paths, not evidence the contract layout exists.',
 ];
 
 // A stable id survives the string MOVING: it hashes surface + normalized text,

package/scripts/gds/design-sync.js

@@ -1,62 +1,12 @@
 #!/usr/bin/env node
-// Build a Claude Design token-preview bundle from the repo's design system.
+'use strict';
+// design-sync.js — thin shim: the Claude Design sync CLI lives in the ui-design
+// module at modules/ui-design/scripts/design-sync.js (task 1003324, ADR 0197).
 //
-// Usage:
-//   node scripts/gds/design-sync.js           — build bundle, print manifest JSON
+// WHY a shim rather than re-pointing every caller: `node scripts/gds/<x>.js` is
+// the form the skills and recipes use, and the form claude-materialize rewrites to
+// `bongos exec scripts/gds/<x>.js` when the core installs as a package — so this
+// path stays the stable, documented entry point. Flags pass straight through:
+//   node scripts/gds/design-sync.js                 — build the token-preview bundle, print the manifest
 //   node scripts/gds/design-sync.js --surface <id>  — limit to one surface
-//
-// 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');
-const { resolveInstanceRoot } = require(path.resolve(__dirname, '..', '..', 'src', 'instance-config'));
-
-// ADR 0108 §1: the design system (src/ui/, config/design-tokens.json) is host
-// content. resolveInstanceRoot() returns the repo root today, so this is
-// byte-identical for the live instance.
-const REPO_ROOT = resolveInstanceRoot();
-
-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(path.join(REPO_ROOT, 'src', 'ui', '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;
-}
+require('../../modules/ui-design/scripts/design-sync.js');