@calibrate-ds/cli 0.1.66 → 0.1.67

package/README.md

@@ -154,32 +154,57 @@ PTB exposes 22 tools over a stdio MCP server. Your AI IDE can query component de
 
 ### Available tools
 
+**Inspection**
+
 | Tool | What it does |
 |---|---|
 | `list_components` | List all components with kind, category, variant axes, and Figma node ID |
 | `get_component` | Full design context: variant axes, token bindings, state/interaction contracts, render tree |
-| `get_component_slots` | Instance-swap slots only — what child components (e.g. icons) a component accepts, and which are valid |
-| `find_component_by_figma_node` | Resolve a Figma node ID to its component and Symbol Bridge entry |
-| `is_stale` | Check if a component's implementation is behind the latest design |
-| `what_uses` | Which components reference a given token or component |
-| `coverage_summary` | Stamped vs. stale vs. unimplemented counts across the whole design system |
+| `find_component_by_figma_node` | Resolve a Figma node ID to its component |
+| `get_status` | Compare `stampedHash` vs `designHash` — what is ready, stale, or unimplemented |
+| `what_uses` | Which components depend on a given component |
 | `token_impact` | Which components are affected by a token change |
-| `list_themes` | List all token themes/collections in the design system |
-| `get_token` | Resolve a token name to its value and which components use it |
-| `get_verify_report` | Latest pixel-diff verify report for a component |
-| `run_scan` | Scan Figma and refresh the local snapshot — no terminal required |
-| `generate_components` | Scaffold typed React shells from the snapshot — no terminal required |
-| `generate_tokens` | Regenerate CSS token files — no terminal required |
-| `export_context` | Export `.ptb/context/` and update `ptb.lock` — no terminal required |
-| `stamp_component` | Mark a component as implemented — no terminal required |
-| `assign_component` | Assign a component to a developer — no terminal required |
-| `start_work` | Claim a component and get the full implementation brief (context, deps, acceptance criteria) in one call |
-| `submit_work` | Submit completed work — reads the actual `.ptb/verify/<slug>/report.json` (never trusts self-reported scores), hard-blocks on missing or scaffold reports, enforces a regression gate (score must meet or exceed the prior stamp), then stamps and transitions lifecycle status |
-| `implement_component` | Get full design context + dependency build plan for a component. Instructs the AI to build dependencies first, write files, ensure Storybook is running, run `run_verify`, then stamp with the verify result |
-| `setup_mcp` | Configure PTB MCP for additional AI IDEs (Cursor, Windsurf, Antigravity, VS Code) — no terminal required |
-| `get_changelog` | Show what changed in recent PTB versions |
-| `get_upgrade_checklist` | Steps to run after upgrading PTB |
-| `get_setup_checklist` | Check current project setup state (config, token, snapshot, context, tokens, components) and return a live guide — the AI runs auto-executable steps immediately and only pauses for manual ones |
+| `list_themes` | List all token collections and their modes |
+| `get_token` | Resolve a token name to its value and which components reference it |
+
+**Pipeline**
+
+| Tool | What it does |
+|---|---|
+| `run` | Run a PTB pipeline stage: `scan`, `generate`, `tokens`, `context`, `prune` |
+
+**Work lifecycle**
+
+| Tool | What it does |
+|---|---|
+| `assign_component` | Assign a component to a developer |
+| `start_work` | Claim a component and get the full implementation brief (context, deps, acceptance criteria) |
+| `implement_component` | Get design context + dependency plan — AI writes code, runs verify, and stamps |
+| `submit_work` | Stamp work done — reads `report.json`, hard-blocks on scaffold/missing report, enforces regression gate |
+| `document_component` | Generate MDX documentation and/or Storybook stories |
+
+**Governance**
+
+| Tool | What it does |
+|---|---|
+| `run_diff` | What changed in Figma since the last stamp — variant axes, tokens, layout |
+| `diff_clear` | Clear diff history for a component after reviewing changes |
+| `my_queue` | Components assigned to the current developer, sorted by status |
+
+**Verification**
+
+| Tool | What it does |
+|---|---|
+| `run_verify` | Pixel-diff the implementation against Figma thumbnails — requires Storybook running locally |
+| `get_verify_report` | Last verification report for a component without re-running |
+
+**Setup & info**
+
+| Tool | What it does |
+|---|---|
+| `setup_mcp` | Configure PTB MCP for additional AI IDEs (Cursor, Windsurf, Antigravity, VS Code) |
+| `get_checklist` | Live setup or upgrade checklist with state detection (`kind: "setup"` or `"upgrade"`) |
+| `whats_new` | Per-version upgrade changelog — what to re-run after updating PTB |
 
 ### Setup: Claude Code (zero config)
 
@@ -236,7 +261,7 @@ Most AI IDEs spawn the MCP server from their own install directory, not your pro
 
 ### Figma token and the MCP server
 
-The MCP server is a **separate process** from your terminal — it does not inherit your shell exports. If `run_scan` tells you `FIGMA_ACCESS_TOKEN is not set in the MCP server environment`, that is why.
+The MCP server is a **separate process** from your terminal — it does not inherit your shell exports. If `run({ stage: "scan" })` tells you `FIGMA_ACCESS_TOKEN is not set in the MCP server environment`, that is why.
 
 **Never put your token directly in the MCP config file.** That file can end up in a dotfiles repo, get synced, or be shared — treat it like a `.env` file.
 
@@ -282,8 +307,8 @@ Then add the block to your MCP config — but prefer options 1 or 2 to keep cred
 
 1. Update the CLI: `npm install -g @calibrate-ds/cli`
 2. Restart your IDE's MCP server (the IDE needs to re-spawn the process)
-3. Ask your AI IDE: `"get_upgrade_checklist"` to see what to re-run
-4. Run `ptb scan` (or ask your IDE to `run_scan`) to pick up any scanner changes
+3. Ask your AI IDE: `"whats_new"` to see what to re-run
+4. Run `ptb scan` (or ask your IDE to `run({ stage: "scan" })`) to pick up any scanner changes
 
 ---
 
@@ -400,7 +425,7 @@ Weaker models will produce code that compiles but misses design intent — wrong
 PTB extracts everything from Figma into structured JSON. Your AI IDE doesn't need a live Figma connection — `.ptb/context/` files contain variant axes, token bindings, state contracts, layout, render trees, and interaction contracts.
 
 **Workflow:**
-1. Run `ptb export context` after each scan (or use the `export_context` MCP tool)
+1. Run `ptb export context` after each scan (or use `run({ stage: "context" })` via MCP)
 2. `ptb scan` auto-generates `AI.md` at your package root — most AI IDEs pick this up automatically
 3. Connect the MCP server — then ask your IDE: `"get_component Button"` for full design context
 4. Let the AI write the component — it has full design intent without needing Figma access
@@ -452,7 +477,7 @@ ptb stamp component Button -m "implemented with new focus ring per design v2"
 ptb stamp component .              # stamp all
 ```
 
-Or ask your AI IDE: `"stamp_component Button"` — no terminal needed.
+Or ask your AI IDE: `"submit_work Button"` — no terminal needed.
 
 ### Viewing history
 
@@ -707,7 +732,14 @@ All frameworks support the full governance workflow (scan, diff, status, stamp,
 
 ## Roadmap
 
-See [docs/PTB_ROADMAP.md](./docs/PTB_ROADMAP.md) for the full milestone breakdown: visual verification, MCP server, playground, visual governance, and bidirectional sync.
+| Milestone | What shipped |
+|---|---|
+| M1 | Scan → generate → governance → team workflow |
+| M2 | `ptb verify` — visual diff + AI feedback |
+| M3 | `ptb mcp` — live MCP server + Symbol Bridge |
+| M4 | `ptb dev` playground + three-column `ptb status` |
+| M5 | Verify-gated implement loop, story index resolution, playground overlay |
+| M5.5–M5.6 | 44-gap audit — CSS emission, naming, lifecycle integrity, scaffold guard, real verify gate (0.1.55 → 0.1.66) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/cli",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,10 +24,10 @@
     "commander": "^14.0.3",
     "openai": "^6.34.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/core": "^0.1.66",
-    "@calibrate-ds/shared-types": "^0.1.66",
-    "@calibrate-ds/generator-react": "^0.1.66",
-    "@calibrate-ds/figma-client": "^0.1.66"
+    "@calibrate-ds/core": "^0.1.67",
+    "@calibrate-ds/shared-types": "^0.1.67",
+    "@calibrate-ds/figma-client": "^0.1.67",
+    "@calibrate-ds/generator-react": "^0.1.67"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",