@noemuch/bridge-ds 2.3.0 → 2.5.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "bridge-ds",
+  "displayName": "Bridge Design System",
+  "version": "2.5.1",
+  "description": "AI-powered design generation in Figma — spec-first, DS-native, with a learning loop that improves over time. Extracts your real design system, writes validated specs, and generates production-ready Figma designs using actual DS components and tokens.",
+  "author": {
+    "name": "noemuch",
+    "url": "https://github.com/noemuch"
+  },
+  "homepage": "https://github.com/noemuch/bridge",
+  "repository": "https://github.com/noemuch/bridge",
+  "license": "MIT",
+  "keywords": [
+    "figma",
+    "design-system",
+    "design-tokens",
+    "mcp",
+    "ai-design",
+    "figma-plugin-api",
+    "spec-first",
+    "design-generation"
+  ],
+  "skills": {
+    "design-workflow": "./skills/design-workflow/SKILL.md"
+  },
+  "commands": {
+    "design-workflow": "./commands/design-workflow.md"
+  },
+  "instructions": "./CLAUDE.md",
+  "mcpServers": "./.mcp.json"
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "bridge-ds",
+  "displayName": "Bridge Design System",
+  "version": "2.5.1",
+  "description": "AI-powered design generation in Figma — spec-first, DS-native, with a learning loop.",
+  "author": "noemuch",
+  "homepage": "https://github.com/noemuch/bridge",
+  "repository": "https://github.com/noemuch/bridge",
+  "license": "MIT",
+  "keywords": ["figma", "design-system", "mcp", "ai-design"],
+  "skills": {
+    "design-workflow": "./skills/design-workflow/SKILL.md"
+  },
+  "commands": {
+    "design-workflow": "./commands/design-workflow.md"
+  },
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": ["-y", "figma-console-mcp@latest"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": ""
+      }
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": ["-y", "figma-console-mcp@latest"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": ""
+      },
+      "description": "Figma Console MCP — gives Claude native access to Figma Desktop via Plugin API. Required for design generation."
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to Bridge DS are documented here.
+
+## [2.5.1] — 2026-03-25
+
+### Added
+- **Rule 24**: Never screenshot a page or empty node — create a frame first
+- **Rule 25**: Input/Select components — swap to `state=filled` for real values
+- **Rule 26**: Validate registry keys before writing scripts — copy-paste from registries, never type manually
+- `quick.md`: References Rules 24-26 in generation steps
+
+## [2.5.0] — 2026-03-25
+
+### Added
+- **Dual MCP transport**: Support for both figma-console-mcp (preferred) and official Figma MCP server (fallback). Auto-detection picks the best available transport.
+- **Express mode**: `/design-workflow quick` skips formal spec, generates from brief description with 2 questions max. Same DS quality guarantees.
+- **Plugin packaging**: `.claude-plugin/plugin.json` and `.cursor-plugin/plugin.json` for marketplace distribution.
+- **Transport adapter**: `transport-adapter.md` — central reference for tool mapping, script adaptation, and composite DS extraction.
+- **Rule 23**: Transport-aware scripting in `figma-api-rules.md` (IIFE vs top-level await, official transport constraints).
+- **KB path resolution**: `./bridge-ds/` (plugin mode) or `.claude/skills/` (npm scaffold mode).
+- **`.mcp.json`**: MCP server dependency declaration for plugin installs.
+
+### Changed
+- `mcp-setup.js`: Returns `{ console, official }` instead of boolean.
+- `cli.js`: Reports both transports during init, offers dual setup instructions.
+- `onboarding.md`: Dual transport detection + composite DS extraction for official transport.
+- `quality-gates.md`: Quick mode section with relaxed gates (pattern matching best-effort, no formal spec/review).
+- 6 schema files updated with transport notes.
+- `package.json`: Bumped to v2.5.0, added plugin manifests to `files`.
+
+## [2.4.1] — 2026-03-20
+
+### Fixed
+- **review.md**: Sections F (Component API Quality) and G (Learning Opportunity) were in wrong order
+- **CLI help**: Added missing `drop`, `learn`, `sync`, `status` slash commands
+- **README.md**: Added missing `learn` and `sync` commands to table; updated workflow diagram with learning loop
+- **design.md**: Fixed incorrect absolute path to knowledge base (now relative `references/knowledge-base/`)
+- **done.md**: Added `Learnings: {n} persisted` to output template
+- **scaffold.js**: Added `learnings.json` to `.gitignore` entries; `update()` now preserves `learnings.json`
+
+### Added
+- **Templates**: "Known Preferences" section in both `screen-template.md` and `spec-template.md`
+- **CHANGELOG.md**: This file
+
+## [2.4.0] — 2026-03-19
+
+### Added
+- Learning loop: `learn` action diffs Figma corrections against generation snapshot, extracts reusable preferences
+- Incremental DS sync: `sync` action updates registries without full re-setup
+- `status` action shows current workflow state and suggests next step
+- `drop` action abandons work with preserved learnings
+- Snapshot capture after design generation for learn diffing
+
+## [2.3.0] — 2026-03-18
+
+### Added
+- Screen generation with reference inspection and clone-first strategy
+- Auto-enrichment of specs from knowledge base
+- Visual reference pattern matching (blocking gate)
+
+## [2.2.0] — 2026-03-17
+
+### Added
+- `update` command to preserve knowledge base on upgrades
+- Interactive MCP setup during `init`
+
+## [2.1.0] — 2026-03-16
+
+### Added
+- Registry schemas and validation for setup
+- Validation gate before design generation
+
+## [2.0.1] — 2026-03-15
+
+### Fixed
+- Strengthened pre-script audit
+- Added Rule 20 (setTextStyleIdAsync)
+
+## [2.0.0] — 2026-03-14
+
+### Changed
+- Complete rewrite: MCP-powered design workflow via figma-console-mcp
+- Spec-first architecture with atomic generation
+- Knowledge base system (registries, guides, patterns)
+- DS-native generation (zero hardcoded values)
+
+## [1.0.0] — 2026-03-12
+
+### Added
+- Initial release: Bridge for Claude Code
+- CLI with `init` command
+- Design workflow skill scaffold

package/CLAUDE.md

@@ -0,0 +1,84 @@
+# Bridge DS — Claude Code Instructions
+
+Bridge DS is an AI-powered design workflow that generates Figma designs using your real design system. It supports two MCP transports: [figma-console-mcp](https://github.com/southleft/figma-console-mcp) (preferred) and the official Figma MCP server (fallback).
+
+## Architecture
+
+```
+Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop  (local, preferred)
+Claude Code  ──MCP──>  Figma MCP Server   ──Cloud──>      Figma Cloud    (official, fallback)
+```
+
+All Figma operations use MCP tools — no custom server, no HTTP calls, no curl. See `skills/design-workflow/references/transport-adapter.md` for transport detection and tool mapping.
+
+## Key MCP Tools
+
+Tools vary by transport. See `references/transport-adapter.md` for the full mapping.
+
+| Operation | Console transport | Official transport |
+|-----------|------------------|--------------------|
+| Execute Plugin API code | `figma_execute` | `use_figma` |
+| Take screenshot | `figma_take_screenshot` | `get_screenshot` |
+| Full DS extraction | `figma_get_design_system_kit` | Composite (see transport-adapter.md) |
+| Get variables | `figma_get_variables` | `get_variable_defs` |
+| Get styles | `figma_get_styles` | `search_design_system` |
+| Search components | `figma_search_components` | `search_design_system` |
+| Connection check | `figma_get_status` | `whoami` |
+
+## Script Structure
+
+Script format depends on the active transport. See `references/transport-adapter.md` Section C for full rules.
+
+**Console transport (figma_execute) — IIFE wrapper mandatory:**
+
+```javascript
+return (async function() {
+  await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+  // ... Plugin API code ...
+  return { success: true };
+})();
+```
+
+**Official transport (use_figma) — top-level await, no IIFE:**
+
+```javascript
+await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+// ... Plugin API code ...
+return { success: true };
+```
+
+Called as: `use_figma({ fileKey: "...", description: "...", code: "..." })`
+
+## Critical Figma API Rules
+
+Full rules: `skills/design-workflow/references/figma-api-rules.md`
+
+**Top 5 (most common bugs):**
+
+1. **FILL after appendChild** — Set `layoutSizingHorizontal = "FILL"` AFTER `parent.appendChild(child)`, never before
+2. **resize() overrides sizing** — Call `resize()` FIRST, then set `primaryAxisSizingMode`
+3. **Colors via setBoundVariableForPaint** — Not `setBoundVariable` (different API for fills/strokes)
+4. **textAutoResize after width** — Set characters → append → FILL → then `textAutoResize = "HEIGHT"`
+5. **DS component reuse** — NEVER recreate existing components as raw frames. Always import via `importComponentByKeyAsync`
+
+## Helpers
+
+Helpers (`mf`, `appendFill`, `bindPadding`, `bindRadius`) and the standard script boilerplate are defined in `skills/design-workflow/references/figma-api-rules.md` (Standard Script Boilerplate section). Always copy them from there.
+
+## Design Workflow
+
+The `/design-workflow` skill handles everything:
+
+```
+/design-workflow setup    → Extract DS + build knowledge base
+/design-workflow spec     → Write component or screen specification
+/design-workflow design   → Generate in Figma (atomic, verified)
+/design-workflow review   → Validate against spec + tokens
+/design-workflow done     → Archive and ship
+/design-workflow drop     → Abandon with preserved learnings
+/design-workflow learn    → Diff design vs corrections, extract learnings
+/design-workflow sync     → Incremental DS sync (no full re-setup)
+/design-workflow status   → Show current state, suggest next
+```
+
+Read `skills/design-workflow/SKILL.md` for the full workflow definition.

package/README.md

@@ -8,8 +8,9 @@ Bridge turns [Claude Code](https://claude.ai/download) into a designer that know
 You describe what you want
   → Claude consults the knowledge base (your DS, documented)
   → Claude writes the spec (exact components, tokens, layout)
-  → Claude generates in Figma via figma_execute (real DS components, bound variables)
+  → Claude generates in Figma (real DS components, bound variables)
   → You review in Figma
+  → Claude learns from your corrections (and improves next time)
 ```
 
 ## How it works
@@ -19,21 +20,23 @@ Bridge is two things:
 1. **A CLI** (`bridge-ds init`) that scaffolds your project with the design workflow skill
 2. **A Claude Code skill** (`/design-workflow`) that handles the intelligence — spec writing, DS knowledge, Figma generation
 
-The transport layer is [figma-console-mcp](https://github.com/southleft/figma-console-mcp), an MCP server that gives Claude native access to Figma (57+ tools).
+Bridge supports two MCP transports:
 
 ```
-Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop
-                                                            (your DS library,
-                                                             real components,
-                                                             bound variables)
+Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop  (preferred)
+Claude Code  ──MCP──>  Figma MCP Server   ──Cloud──>      Figma Cloud    (official, fallback)
 ```
 
+Auto-detection picks the best available transport. See [transport-adapter.md](skills/design-workflow/references/transport-adapter.md) for details.
+
 ## Prerequisites
 
 - [Claude Code](https://claude.ai/download) installed
 - [Node.js 18+](https://nodejs.org)
-- [Figma Desktop](https://www.figma.com/downloads/) (not the web app)
 - A Figma file with a published design system library
+- One of:
+  - [figma-console-mcp](https://github.com/southleft/figma-console-mcp) + [Figma Desktop](https://www.figma.com/downloads/) (recommended, full capabilities)
+  - Official Figma MCP server (simpler setup, cloud-based)
 
 ## Quick Start
 
@@ -97,11 +100,16 @@ Claude consults the knowledge base, identifies the right pattern, components, an
 ## The Workflow
 
 ```
-setup (once)  →  spec  →  design  →  review  →  done
-                   ↑                    |
-                   └── iterate ─────────┘
+setup (once)  →  spec  →  design  →  review  ──→  done
+                   ↑                    |             |
+                   └── iterate ─────────┘       learn ←┘
+                                           (diff corrections,
+                                            extract preferences)
 ```
 
+### Express mode
+For quick iterations, skip the formal spec: `/design-workflow quick "a settings page"`. 2 questions max, inline mini-spec, same DS quality guarantees.
+
 ### Spec-first
 No design without a validated specification. Claude knows exactly which components, tokens, and layout patterns to use because it has your DS documented.
 
@@ -137,11 +145,18 @@ knowledge-base/
 | `/design-workflow setup` | Extract DS + build knowledge base |
 | `/design-workflow spec {name}` | Write a component or screen spec |
 | `/design-workflow design` | Generate in Figma from active spec |
+| `/design-workflow quick {description}` | Express generation — skip spec, generate directly |
 | `/design-workflow review` | Validate design against spec + tokens |
 | `/design-workflow done` | Archive spec and ship |
 | `/design-workflow drop` | Abandon with preserved learnings |
+| `/design-workflow learn` | Diff corrections, extract learnings |
+| `/design-workflow sync` | Incremental DS sync (no full re-setup) |
 | `/design-workflow status` | Show current state, suggest next action |
 
+## Author
+
+Built by [Noé Chagué](https://www.linkedin.com/in/noechague/) — Design System @ [Finary](https://finary.com)
+
 ## License
 
 MIT

package/lib/cli.js

@@ -1,8 +1,10 @@
 const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
 const { scaffold, update } = require('./scaffold');
-const { checkMcp, setupMcp } = require('./mcp-setup');
+const { checkMcp } = require('./mcp-setup');
 
-// ── Branding ──────────────────────────────────────────────
+// ── Formatting ───────────────────────────────────────────
 const C = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
@@ -12,162 +14,145 @@ const C = {
   red: '\x1b[38;2;244;67;54m',
   yellow: '\x1b[38;2;255;193;7m',
   gray: '\x1b[38;2;158;158;158m',
-  white: '\x1b[38;2;255;255;255m',
 };
 
 function print(msg = '') { process.stdout.write(msg + '\n'); }
-function header(msg) { print(`\n${C.orange}${C.bold}🧱 ${msg}${C.reset}\n`); }
-function success(msg) { print(`${C.green}  ✓ ${msg}${C.reset}`); }
-function info(msg) { print(`${C.white}  ℹ ${msg}${C.reset}`); }
-function warn(msg) { print(`${C.yellow}  ⚠ ${msg}${C.reset}`); }
-function error(msg) { print(`${C.red}  ✗ ${msg}${C.reset}`); }
-function muted(msg) { print(`${C.gray}    ${msg}${C.reset}`); }
-function step(n, total, msg) { print(`${C.orange}  [${n}/${total}]${C.reset} ${C.bold}${msg}${C.reset}`); }
-
-// ── Spinner ───────────────────────────────────────────────
-const FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
-class Spinner {
-  constructor(msg) { this.msg = msg; this.i = 0; this.id = null; }
-  start() {
-    this.id = setInterval(() => {
-      process.stdout.write(`\r${C.orange}  ${FRAMES[this.i++ % FRAMES.length]}${C.reset} ${this.msg}`);
-    }, 80);
-    return this;
-  }
-  stop(result) {
-    clearInterval(this.id);
-    process.stdout.write('\r' + ' '.repeat(this.msg.length + 10) + '\r');
-    if (result) success(result);
-  }
+function ok(msg) { print(`  ${C.green}✓${C.reset} ${msg}`); }
+function fail(msg) { print(`  ${C.red}✗${C.reset} ${msg}`); }
+function warn(msg) { print(`  ${C.yellow}!${C.reset} ${msg}`); }
+function dim(msg) { print(`  ${C.dim}${msg}${C.reset}`); }
+
+function brand() {
+  const pkg = require('../package.json');
+  print(`\n  ${C.orange}${C.bold}Bridge DS${C.reset} ${C.dim}v${pkg.version}${C.reset}\n`);
 }
 
-// ── ASCII Art ─────────────────────────────────────────────
-function banner() {
-  print('');
-  print(`${C.orange}${C.bold}  ┌──────────────────────────────────────┐${C.reset}`);
-  print(`${C.orange}${C.bold}  │  🧱  Bridge DS                       │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  AI-powered design in Figma           │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  100% design system compliant         │${C.reset}`);
-  print(`${C.orange}${C.bold}  └──────────────────────────────────────┘${C.reset}`);
-  print('');
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
 }
 
-// ── Commands ──────────────────────────────────────────────
+// ── Commands ─────────────────────────────────────────────
 
 async function cmdInit() {
-  banner();
-  header('Initializing Bridge DS');
+  brand();
 
   const cwd = process.cwd();
-  const totalSteps = 4;
 
-  // Step 1: Check prerequisites
-  step(1, totalSteps, 'Checking prerequisites');
+  // 1. Prerequisites
   const nodeVersion = process.version.replace('v', '').split('.').map(Number);
   if (nodeVersion[0] < 18) {
-    error(`Node.js 18+ required (found ${process.version})`);
+    fail(`Node.js 18+ required (found ${process.version})`);
     process.exit(1);
   }
-  success(`Node.js ${process.version}`);
+  ok(`Node.js ${process.version}`);
 
-  // Step 2: Configure figma-console-mcp
-  step(2, totalSteps, 'Checking figma-console-mcp');
-  const mcpConfigured = checkMcp();
-  if (mcpConfigured) {
-    success('figma-console-mcp is configured');
-  } else {
-    warn('figma-console-mcp not found in Claude Code settings');
-    info('Run this command to add it:');
+  // 2. Figma MCP transport
+  const mcp = checkMcp();
+  let mcpReady = mcp.console || mcp.official;
+
+  if (mcp.console) {
+    ok('figma-console-mcp detected (preferred transport)');
+  }
+  if (mcp.official) {
+    ok('Official Figma MCP detected' + (mcp.console ? ' (fallback)' : ''));
+    if (!mcp.console) {
+      dim('figma-console-mcp is recommended for full capabilities but official MCP works too');
+    }
+  }
+
+  if (!mcpReady) {
+    warn('No Figma MCP transport configured');
+    print('');
+    dim('Bridge supports two transports:');
+    dim('  A) figma-console-mcp (recommended, full Plugin API access)');
+    dim('  B) Official Figma MCP (cloud-based, cross-library search)');
     print('');
-    print(`${C.dim}    claude mcp add figma-console -s user \\${C.reset}`);
-    print(`${C.dim}      -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN \\${C.reset}`);
-    print(`${C.dim}      -- npx -y figma-console-mcp@latest${C.reset}`);
+    dim('For option A, you need a Personal Access Token from Figma:');
+    dim('https://www.figma.com/developers/api#access-tokens');
     print('');
-    info('Then re-run: bridge-ds init');
-    info('Continuing with file setup...');
+
+    const token = await ask(`${C.bold}Figma token${C.reset} (figd_...) for figma-console-mcp, or Enter to skip:`);
+
+    if (token && token.startsWith('figd_')) {
+      try {
+        execSync(
+          `claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=${token} -- npx -y figma-console-mcp@latest`,
+          { stdio: 'pipe' }
+        );
+        ok('figma-console-mcp configured');
+        mcpReady = true;
+      } catch (e) {
+        fail('Could not configure MCP automatically');
+        dim('Run manually:');
+        dim(`claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=${token} -- npx -y figma-console-mcp@latest`);
+      }
+    } else if (token) {
+      warn('Token should start with figd_ — skipping MCP setup');
+      dim('You can configure it later:');
+      dim('claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=<token> -- npx -y figma-console-mcp@latest');
+    } else {
+      dim('Skipped. You can configure either transport later.');
+      dim('Console: claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=<token> -- npx -y figma-console-mcp@latest');
+      dim('Official: Configure via Claude settings or Figma MCP integration.');
+    }
   }
 
-  // Step 3: Scaffold project files
-  step(3, totalSteps, 'Scaffolding project files');
-  const spinner = new Spinner('Copying skills, commands, templates...').start();
-  const result = scaffold(cwd);
-  spinner.stop('Project files created');
+  print('');
 
-  for (const f of result.created) {
-    muted(f);
-  }
+  // 3. Scaffold
+  const result = scaffold(cwd);
+  ok(`${result.created.length} files scaffolded`);
 
-  // Step 4: Summary
-  step(4, totalSteps, 'Done!');
+  // 4. Summary
   print('');
-  print(`${C.orange}${C.bold}  ┌──────────────────────────────────────┐${C.reset}`);
-  print(`${C.orange}${C.bold}  │  Setup complete!                      │${C.reset}`);
-  print(`${C.orange}${C.bold}  │                                       │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  Next steps:                          │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  1. Open Claude Code in this project  │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  2. Run: /design-workflow setup       │${C.reset}`);
-  print(`${C.orange}${C.bold}  │     → Extracts & documents your DS    │${C.reset}`);
-  print(`${C.orange}${C.bold}  │  3. Run: /design-workflow spec ...    │${C.reset}`);
-  print(`${C.orange}${C.bold}  │     → Start designing!                │${C.reset}`);
-  print(`${C.orange}${C.bold}  └──────────────────────────────────────┘${C.reset}`);
+  if (mcpReady) {
+    ok(`${C.bold}Ready!${C.reset} Open Claude Code and run: ${C.orange}/design-workflow setup${C.reset}`);
+  } else {
+    warn(`${C.bold}Almost ready.${C.reset} Configure figma-console-mcp, then run: ${C.orange}/design-workflow setup${C.reset}`);
+  }
   print('');
 }
 
 async function cmdUpdate() {
-  banner();
-  header('Updating Bridge DS skill files');
+  brand();
 
   const cwd = process.cwd();
-
-  step(1, 2, 'Updating skill files');
-  const spinner = new Spinner('Updating SKILL.md, actions, rules, schemas, templates...').start();
   const result = update(cwd);
 
   if (result.error) {
-    spinner.stop();
-    error(result.error);
+    fail(result.error);
     process.exit(1);
   }
 
-  spinner.stop(`${result.updated.length} files updated`);
-
-  for (const f of result.updated) {
-    muted(f);
-  }
-
-  step(2, 2, 'Done!');
-  print('');
-  success('Skill files updated. Your knowledge base (registries, guides) was preserved.');
-  info('No need to re-run /design-workflow setup.');
+  ok(`${result.updated.length} files updated`);
+  dim('Knowledge base preserved (registries, guides, screenshots)');
   print('');
 }
 
 function cmdHelp() {
-  banner();
-  print(`${C.bold}  Commands:${C.reset}`);
-  print('');
-  print(`    ${C.orange}init${C.reset}       Initialize Bridge DS in current project`);
-  print(`               Scaffolds skills, commands, and specs directories`);
-  print('');
-  print(`    ${C.orange}update${C.reset}     Update skill files to latest version`);
-  print(`               Preserves your knowledge base (registries, guides)`);
-  print('');
-  print(`    ${C.orange}help${C.reset}       Show this help message`);
+  brand();
+  print(`  ${C.bold}Commands${C.reset}`);
+  print(`    ${C.orange}init${C.reset}       Set up Bridge DS in the current project`);
+  print(`    ${C.orange}update${C.reset}     Update skill files (preserves knowledge base)`);
+  print(`    ${C.orange}help${C.reset}       Show this help`);
   print(`    ${C.orange}version${C.reset}    Show version`);
   print('');
-  print(`${C.bold}  Usage:${C.reset}`);
-  print('');
-  print(`    ${C.dim}npx @noemuch/bridge-ds init${C.reset}     # Initialize in current project`);
-  print(`    ${C.dim}npx @noemuch/bridge-ds update${C.reset}   # Update skill files only`);
-  print(`    ${C.dim}bridge-ds help${C.reset}                  # Show help`);
-  print('');
-  print(`${C.bold}  After init:${C.reset}`);
-  print('');
-  print(`    ${C.dim}/design-workflow setup${C.reset}  # Extract & document your DS (in Claude Code)`);
-  print(`    ${C.dim}/design-workflow spec${C.reset}   # Spec a component or screen`);
-  print(`    ${C.dim}/design-workflow design${C.reset} # Generate in Figma`);
-  print(`    ${C.dim}/design-workflow review${C.reset} # Validate against spec`);
-  print(`    ${C.dim}/design-workflow done${C.reset}   # Archive & ship`);
+  print(`  ${C.bold}After init${C.reset}`);
+  print(`    ${C.dim}/design-workflow setup${C.reset}    Extract your design system`);
+  print(`    ${C.dim}/design-workflow spec${C.reset}     Spec a component or screen`);
+  print(`    ${C.dim}/design-workflow design${C.reset}   Generate in Figma`);
+  print(`    ${C.dim}/design-workflow review${C.reset}   Validate against spec`);
+  print(`    ${C.dim}/design-workflow done${C.reset}     Archive & ship`);
+  print(`    ${C.dim}/design-workflow drop${C.reset}    Abandon with preserved learnings`);
+  print(`    ${C.dim}/design-workflow learn${C.reset}   Diff corrections, extract learnings`);
+  print(`    ${C.dim}/design-workflow sync${C.reset}    Incremental DS sync`);
+  print(`    ${C.dim}/design-workflow status${C.reset}  Show current state, suggest next`);
   print('');
 }
 
@@ -176,30 +161,18 @@ function cmdVersion() {
   print(`bridge-ds v${pkg.version}`);
 }
 
-// ── Router ────────────────────────────────────────────────
+// ── Router ───────────────────────────────────────────────
 
 async function run(args) {
   const cmd = args[0] || 'help';
 
   switch (cmd) {
-    case 'init':
-      await cmdInit();
-      break;
-    case 'update':
-      await cmdUpdate();
-      break;
-    case 'help':
-    case '--help':
-    case '-h':
-      cmdHelp();
-      break;
-    case 'version':
-    case '--version':
-    case '-v':
-      cmdVersion();
-      break;
+    case 'init': return cmdInit();
+    case 'update': return cmdUpdate();
+    case 'help': case '--help': case '-h': return cmdHelp();
+    case 'version': case '--version': case '-v': return cmdVersion();
     default:
-      error(`Unknown command: ${cmd}`);
+      fail(`Unknown command: ${cmd}`);
       cmdHelp();
       process.exit(1);
   }