@sxl-studio/bridge 1.7.2 → 1.8.0

package/README.md

@@ -14,10 +14,47 @@ Official [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/) does n
 
 | Need | Use |
 |------|-----|
-| Native file operations where Figma’s MCP tools are enough (context, many canvas writes, variables in supported flows) | **Official Figma MCP** (often remote `https://mcp.figma.com/mcp`) |
+| Native file operations where Figma’s MCP tools are enough (context, many canvas writes, new files, FigJam/Slides, FigJam/Slides asset upload) | **Official Figma MCP** (often remote `https://mcp.figma.com/mcp`) |
 | Plugin-only workflows: compositions, plugin token/Git APIs, whitelisted node helpers, Dev Mode codegen parity | **SXL Studio Bridge** + plugin Remote Connect |
+| Cross-file/no-plugin reads for known files or teams (`whoami`, file/node metadata, screenshots/image URLs, published components/styles, variables REST endpoints), active-file design context, active-file metadata, variable/style definitions, Figma MCP-compatible library discovery/search, Figma Design image insertion, local Code Connect context/suggestions | **SXL Studio Bridge** (`get_design_context`, `get_metadata`, `get_variable_defs`, `get_libraries`, `search_design_system`, `figma_rest_*`, `get_screenshot`, `upload_assets`, `get_context_for_code_connect`, `get_code_connect_suggestions`) |
 
-Bridge forwards `commandType` + `payload` over WebSocket; **execution is always in the plugin** (whitelist + handlers). Adding an MCP tool in Bridge without the matching plugin handler will return `not_whitelisted`.
+Bridge catalogue entries expose explicit execution metadata:
+
+- `execution: "plugin"` — the MCP tool sends one Remote Connect command to the plugin.
+- `execution: "bridge-orchestration"` — Bridge parses/aggregates input and sends one or more plugin commands.
+- `execution: "bridge-local"` — Bridge answers locally and does not require a plugin command.
+
+Plugin-routed tools list their exact `pluginCommandTypes`; each one must exist in the plugin Remote Connect whitelist and handlers. Adding a plugin-routed MCP tool in Bridge without the matching plugin contract will return `not_whitelisted`.
+
+### AI agent operating contract
+
+When this README is used as context for an AI agent, the agent should treat Bridge as the controlled SXL Studio automation layer, not as a generic canvas scripting surface.
+
+1. Start with `get_bridge_runtime_summary` or `GET /api/runtime-summary`.
+2. If the task needs the open Figma file and Remote Connect is not connected, stop and ask the operator to open SXL Studio in Figma and enable Remote Connect. Do not fake live Figma results.
+3. For natural-language tasks, call `route_intent`, then `plan_workflow`, then `preview_workflow` before write tools.
+4. For screen generation, call `inspect_design_system`, then `validate_screen_spec`, then `build_screen` / `update_screen` with `dryRun: true`, then apply.
+5. For variable/style export, call `preview_export_variables` before `export_variables`; destructive options require top-level `confirmDestructive: true`.
+6. For Figma documentation, prefer `apply_doc_spec`, `build_component_doc`, `build_doc_flow`, `bind_variable_palette`, and `build_scenario_from_md` over ad hoc scripts.
+7. For large scans, request summaries first and use paginated detail tools only for the exact subset you need.
+8. After writes, re-run the relevant read/audit command and report changed/skipped items plus any visual review that remains.
+
+Bridge covers active-file Figma Design + SXL Studio workflows. Official Figma MCP remains the companion for remote-only/new-file work, FigJam/Slides-specific editing, generated diagrams, and hosted-only Code Connect context. Official references:
+
+- [Figma MCP server documentation](https://developers.figma.com/docs/figma-mcp-server/)
+- [Figma MCP tools and prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
+- [Figma skills for MCP](https://help.figma.com/hc/en-us/articles/39166810751895-Figma-skills-for-MCP)
+
+| User intent | Start with | Then use |
+|---|---|---|
+| Build or update a Figma screen | `route_intent`, `inspect_design_system` | `validate_screen_spec`, `build_screen` / `update_screen` dry-run, then apply |
+| Render documentation in Figma | `route_intent`, `sxl://agent/recipes/sxl-doc-builder` | `apply_doc_spec`, `build_component_doc`, `build_doc_flow`, `build_scenario_from_md` |
+| Export variables/styles | `preview_export_variables` | `export_variables` with explicit options |
+| Audit raw values or missing bindings | `audit_variable_coverage`, `audit_style_coverage` | paginated `find_*`, dry-run apply suggestions |
+| Analyze component usage/props | `analyze_component_usage`, `analyze_component_prop_usage` | `find_component_usages`, `find_component_prop_usages` |
+| Generate/apply compositions | `compose_from_url`, `list_composition_files` | `bulk_generate_compositions`, `audit_composition_drift` |
+| Connect Figma components to code | `get_context_for_code_connect` | `get_code_connect_suggestions`, `generate_code_connect_template`, `codeconnect_save_binding` |
+| Use repository-backed local storage | Git Sync Local Storage settings | `/api/workspace-blob`, `git_pull`, `git_push` |
 
 ### Version compatibility (npm Bridge ⟷ plugin)
 
@@ -30,28 +67,58 @@ Bridge forwards `commandType` + `payload` over WebSocket; **execution is always
 | **`1.4.x`** | **`2.1.0+`** (plugin with `apply_token_doc_spec`) | **Doc Spec v1** + `build_token_documentation` / `apply_token_doc_spec`, **MCP resources** `sxl://agent/recipes/doc-tokens` (+ doc-component, doc-composition, doc-flow), expanded MCP instructions for documentation recipes. |
 | **`1.5.x`** | **`2.2.0+`** | **Doc Builder v2**: `apply_doc_spec` (generic sections), `bind_variable_palette`, `build_component_doc`, `build_doc_flow`. Intent-router resource `sxl://agent/recipes/index` plus `template-discovery`, `doc-spec-v2`. Reinforced anti-patterns in `sxl-mcp-instructions.ts` (`/tmp` payloads, base64 loaders, `use_figma` scripts). |
 | **`1.6.x`** | **`2.3.0+`** | **Audit & Usage (Phase A)** + **Variables orchestration (Phase B)** + **Styles orchestration (Phase C)** + **Mockup-from-DesignSystem (Phase D)** + **Compositions orchestration (Phase E)**. Phase A: `audit` category — `analyze_variable_usage`, `find_variable_usages`, `render_variable_usage_page`, `audit_variable_coverage`, `find_variable_coverage_misses`, `audit_style_coverage`, `find_style_coverage_misses`, `find_unused_variables`, `find_unused_styles`. Chunked traversal with transitive-alias resolution. Token-economy: summary by default, paginated `find_*` for details. Phase B: new `variables-orchestration` category — `import_variable_spec` (idempotent bulk create / update with aliases), `analyze_variable_order` (read-only ordering diff), `dedupe_variables` (merge duplicates, dry-run by default), `rebind_variable_aliases` (bulk alias rewrite), `apply_coverage_suggestions` (audit suggestions → real bindings, dry-run by default). Phase C: new `styles-orchestration` category — `import_style_spec` (idempotent bulk create / update of Paint / Text / Effect styles), `dedupe_styles` (merge duplicates `byName | bySignature`), `rebind_style_consumers` (bulk styleId rewrite on consumer nodes), `audit_style_drift` (read-only drift between local Paint styles and Variables / `expectations[]`), `apply_style_coverage_suggestions` (Phase A `find_style_coverage_misses` → real `setStyleId*` writes). Phase D: new `mockup` category — `find_components` (read-only paginated catalogue of local + library-instantiated components with `componentPropertyDefinitions`, Dev-Mode compatible), `build_mockup` (declarative auto-layout assembly from an `instance | section | spacer | text` item tree with property / text / fill-binding overrides; `dryRun`-aware), `apply_mockup_dataset` (clone a template per dataset row with row-specific overrides; `dryRun`-aware). Phase E: new `compositions-orchestration` category — `bulk_generate_compositions` (bulk `generate` / `apply` of composition files with `fileIds | names | prefix` filters, `operation: auto | generate | apply`, per-item error isolation, `dryRun`-aware), `audit_composition_drift` (read-only drift detection between workspace composition files and tracked Figma components: `linked | unlinked | drift | missing`, Dev-Mode safe). All write commands accept `dryRun` / `apply` so Dev Mode can be used as a preview surface. Recipes: `sxl://agent/recipes/{variable-usage,audit-coverage,find-unused,bulk-variables,auto-bind-from-audit,bulk-styles,style-drift,mockup-builder,bulk-compositions,composition-drift}`. |
-| **`1.7.x`** | **`2.3.0+`** (plugin with Git Sync Local Storage) | **Workspace blobs API** (`GET|POST|DELETE /api/workspace-blob`): disk-backed cache for large Git Sync payloads so token/dataset bodies stay out of Figma `clientStorage`. Uses OS cache dir (`env-paths`, product id `sxl-studio-bridge`) under `workspace-blobs/` unless overridden by `SXL_BRIDGE_WORKSPACE_BLOB_ROOT`. Same `BRIDGE_AUTH_TOKEN` rules as other `/api/*`. Does **not** require an active Remote Connect WebSocket session. |
+| **`1.7.x`** | **`2.3.0+`** (plugin with Git Sync Local Storage) | **Workspace blobs API** (`GET|POST|DELETE /api/workspace-blob`): disk-backed cache for large Git Sync payloads so token/dataset bodies stay out of Figma `clientStorage`. Uses OS cache dir (`env-paths`, product id `sxl-studio-bridge`) under `workspace-blobs/` unless overridden by `SXL_BRIDGE_WORKSPACE_BLOB_ROOT`. Same `BRIDGE_AUTH_TOKEN` rules as other `/api/*`; if auth is enabled, enter the same token in the plugin Sync connection's **Bridge Auth Token** field. Does **not** require an active Remote Connect WebSocket session. Contract stabilization: MCP version follows `package.json`, `route_intent` maps RU/EN natural language to SXL recipes/tools/schema hints, `plan_workflow`/`preview_workflow` add dry-run/approval gates for multi-step chains, `list_tools`/`/api/tools` expose aliases, natural-language intents, dry-run and large-data flags, `get_capability_matrix` returns a machine-readable tool matrix, `get_contract_audit` verifies required meta tools/schema entrypoints/workflow gates, `get_bridge_audit_log` reads memory or persisted JSONL audit, MCP tools return normalized envelopes, `export_variables` uses plugin-safe defaults, Code Connect accepts full binding metadata, exposes schema resources, suggests local bindings through `get_context_for_code_connect` / `get_code_connect_suggestions`, and generates dry-run-first `.figma.ts` templates through `generate_code_connect_template`, enabled libraries can be searched through `search_enabled_library_assets` and inspected through `inspect_enabled_libraries` / `list_enabled_library_variables`, `get_metadata` reads active-file plugin metadata or hosted REST metadata, `get_screenshot` renders active-file SVGs or REST image URLs, Design DSL wrappers (`inspect_design_system`, `validate_screen_spec`, `build_screen`, `update_screen`) plus component usage/prop analytics and database CRUD/portable payload tools are catalogued, `build_doc_flow` renders both node pages and workspace composition pages (`compositionFileId`) through the existing composition pipeline, and optional `figma_rest_*` tools cover Figma REST reads without a plugin session. |
 
 Treat feature alignment by changelog or release tag, not npm name alone.
 
 ## Ports
 
-**One TCP port** (`BRIDGE_PORT`, default **`37830`**): plugin **WebSocket**, **HTTP REST** (`/api/*`), and **MCP Streamable HTTP** (`/mcp`) share it. Override with `BRIDGE_PORT=3100 npm start` if needed (update plugin build + `mcp.json` to match).
+**One TCP port** (`BRIDGE_PORT`, default **`37830`**): plugin **WebSocket**, **HTTP REST** (`/api/*`), and **MCP Streamable HTTP** (`/mcp`) share it. Override with `BRIDGE_PORT=3100 npm start` if needed, then use the same port in your MCP client and in the plugin **Remote Connect** overlay.
 
 | On port `BRIDGE_PORT` | URL (default) |
 |----------------------|---------------|
 | Plugin UI | `ws://127.0.0.1:37830` |
-| REST | `http://127.0.0.1:37830/api/{status,session,tools,log,command,disconnect,workspace-blob}` |
+| REST | `http://127.0.0.1:37830/api/{status,session,queue,events,tools,capabilities,contract-audit,figma-mcp-parity,figma-mcp-skills-parity,figma-rest-diagnostics,performance-profile,runtime-summary,operator-runbook,ultimate-readiness,log,command,disconnect,workspace-blob}` |
 | Cursor MCP | `http://127.0.0.1:37830/mcp` |
 
 ### Optional: shared-secret auth
 
-Set `BRIDGE_AUTH_TOKEN` in the environment and every `/api/*` and `/mcp` request must send `Authorization: Bearer <token>`. Requests without the header return `401 BRIDGE_UNAUTHORIZED`. Useful when running Bridge on a shared machine, or behind a local proxy.
+Set `BRIDGE_AUTH_TOKEN` in the environment and every `/api/*`, `/mcp`, and plugin WebSocket connection must authenticate. HTTP/MCP clients send `Authorization: Bearer <token>`; the SXL Studio plugin sends the token from the **Remote Connect** overlay. Requests without the token return `401 BRIDGE_UNAUTHORIZED` or a rejected WebSocket handshake. Useful when running Bridge on a shared machine, or behind a local proxy.
 
 ```bash
 BRIDGE_AUTH_TOKEN=s3cret npm start
 ```
 
+For live Remote Connect, enter the same token in the plugin **Remote Connect** overlay. For Git Sync **Local Storage**, enter the same token in the plugin Sync connection form under **Bridge Auth Token**. Zero-config mode remains unchanged: leave `BRIDGE_AUTH_TOKEN` unset and leave the plugin fields empty.
+
+### Optional: Figma REST companion
+
+Bridge can also call the Figma REST API directly for read-only hosted context that does not require the plugin to be open:
+
+```bash
+FIGMA_TOKEN=figd_xxx npm start
+# or OAuth/plan token with bearer auth:
+FIGMA_ACCESS_TOKEN=xxx FIGMA_AUTH_MODE=bearer npm start
+```
+
+Available MCP tools are `figma_rest_diagnose`, `figma_rest_whoami`, `figma_rest_get_file_metadata`, `figma_rest_get_file`, `figma_rest_get_file_nodes`, `figma_rest_get_images`, `figma_rest_get_image_fills`, `figma_rest_get_file_components`, `figma_rest_get_file_component_sets`, `figma_rest_get_file_styles`, `figma_rest_get_team_components`, `figma_rest_get_team_component_sets`, `figma_rest_get_team_styles`, `figma_rest_get_variables_local`, `figma_rest_get_variables_published`, and `figma_rest_search_design_system`.
+
+Call `figma_rest_diagnose` first for token/auth/scopes/permission preflight. HTTP clients can use `GET /api/figma-rest-diagnostics?checks=whoami,fileMetadata&fileKey=...`. Use the REST tools for known file/team reads, authenticated `whoami`, REST variables, and known-library search. For Figma MCP-style library discovery, prefer Bridge `get_libraries` and `search_design_system`; they combine active-file enabled libraries through Remote Connect with known file/team REST sources when configured. They do not replace official Figma MCP for creating new files or FigJam/Slides asset upload.
+
+For libraries already enabled in the open Figma file, `get_libraries` and `search_design_system` are the primary agent-facing tools. Use `search_enabled_library_assets` for lower-level enabled-library search, `inspect_enabled_libraries` for raw enabled descriptors, and `list_enabled_library_variables` for variables in a specific enabled collection. Figma Plugin API cannot enable libraries from code; Bridge reports that limitation in the compatibility tool responses.
+
+For screenshots or rendered node images, use `get_screenshot`. `mode: "plugin-svg"` returns inline SVG from active-file nodes or current selection through Remote Connect. `mode: "rest-image"` returns Figma-hosted PNG/JPG/SVG/PDF URLs for known `fileKey/url + nodeIds` using the REST Images endpoint.
+
+For metadata, use `get_metadata`. `mode: "plugin"` returns active-file selection/page structure or node tree metadata through Remote Connect. `mode: "rest"` returns hosted file metadata or node metadata for known `fileKey/url` and optional `nodeIds`.
+
+For active-file design context, use `get_design_context`. It bundles SXL codegen/composition JSON, sparse metadata, native variable/style definitions, optional SVG screenshot, and optional local Code Connect suggestions for the current selection or provided node ids. This mirrors the official MCP `get_design_context` intent as a structured starting point for the agent; it does not claim to be final production code.
+
+For Code Connect template/binding context, use `get_context_for_code_connect`. It bundles SXL registry/settings, selection status, existing bindings, SXL codegen/composition context, component discovery with props, and local source-file suggestions. It covers the active-file/local-codebase side of the official MCP `get_context_for_code_connect` workflow; hosted remote-only context remains official Figma MCP companion scope.
+
+For `.figma.ts` Code Connect template generation, use `generate_code_connect_template`. It accepts a full SXL `CodeConnectBinding` or local targets/component names, returns dry-run content/path by default, and writes only when `writeFile: true` is explicitly passed. Keep `includePropertyAttrs` off unless you have verified that Figma property names match the code component props.
+
+For variable/style definitions, use `get_variable_defs`. `mode: "selection"` is the official-MCP-style route for variables/styles used in the current Figma Design selection; it reads native `boundVariables`, text segment bindings, style ids, and resolved variable/style definitions through Remote Connect, then adds SXL applied-token metadata as compatibility context. `mode: "local"` reads active-file local variables/styles; `mode: "enabled-libraries"` reads variables from libraries already enabled in the open file; `mode: "rest"` reads known-file REST variable endpoints.
+
 ### Cursor MCP (recommended)
 
 Add `http://127.0.0.1:37830/mcp` to `.cursor/mcp.json`. Start Bridge **first** (`cd Utils/bridge && npm run build && npm start`). Then enable Remote Connect in the SXL Studio plugin.
@@ -67,12 +134,105 @@ npm run build
 node dist/index.js
 ```
 
-If you see `EADDRINUSE`, pick a free port: `BRIDGE_PORT=39999 npm start`, then use `http://127.0.0.1:39999/mcp` in Cursor and rebuild the plugin so `remoteBridge.ts` default matches.
+If you see `EADDRINUSE`, pick a free port: `BRIDGE_PORT=39999 npm start`, then use `http://127.0.0.1:39999/mcp` in Cursor and set `39999` in the plugin **Remote Connect** overlay. The plugin remembers the last port locally; the default remains `37830`.
 
 The repo `.cursor/mcp.json` points Cursor at `http://127.0.0.1:37830/mcp`. Bridge must run **before** opening Agent chat.
 
 **MCP + stdout:** the Model Context Protocol uses **stdout** for JSON-RPC. Do not use `console.log` in this process (it corrupts the stream). Use `console.error` for diagnostics.
 
+## Health checks
+
+Local health does not require a running Bridge server or Figma plugin. It verifies the local contract audit, local agent workflow routing/planning, and the Ultimate Bridge readiness audit. A healthy build reports `PASS`; `WARN` should be reviewed before release, while explicit Figma MCP companion/future scope is listed separately by `readiness`.
+
+```bash
+npm run build
+npm run health:local
+npm run readiness
+# installed package alternatives:
+sxl-bridge health
+sxl-bridge-health
+sxl-bridge readiness
+sxl-bridge-readiness
+```
+
+Local readiness proves the code/tool surface. It does **not** prove a live Figma session. To combine local readiness with running HTTP/MCP proof, use:
+
+```bash
+sxl-bridge-readiness --runtime --url http://127.0.0.1:37830
+# package script equivalent:
+npm run readiness:runtime
+```
+
+To make the gate fail unless the SXL Studio plugin is connected and live validation passes:
+
+```bash
+sxl-bridge-readiness --runtime --require-live --suite all
+sxl-bridge-readiness --runtime --require-live --suite all --write-canary --cleanup
+# non-destructive package script equivalent:
+npm run readiness:live
+```
+
+Use `--write-canary --cleanup` only with explicit approval; it creates a tiny validation frame, verifies the returned `rootNodeId`, then deletes that same frame.
+
+Runtime smoke checks the running HTTP/MCP surface (`/mcp` initialize/session/tools-list/tools-call `get_libraries` + `search_design_system` zero-config envelopes, `get_operator_runbook`, `list_tools`, `validate_screen_spec`, `preview_export_variables`, `get_figma_mcp_skills_parity`, and `plan_workflow` for Figma Design library discovery routing, resources-list/resources-read for `runtime-summary` + `operator-runbook` + `figma-mcp-skills-parity`, prompts-list/prompts-get for `sxl-operator` + `sxl-generate-design`, plus REST `status`, `tools`, `capabilities`, `contract-audit`, `figma-mcp-parity`, `figma-mcp-skills-parity`, `performance-profile`, `runtime-summary`, `operator-runbook`, `figma-rest-diagnostics`, `ultimate-readiness`, `queue`, `events`, `log?source=disk`):
+
+```bash
+sxl-bridge-health --runtime --url http://127.0.0.1:37830
+```
+
+Use `--require-plugin` when the check must prove an active SXL Studio Remote Connect session:
+
+```bash
+sxl-bridge-health --runtime --require-plugin --auth-token "$BRIDGE_AUTH_TOKEN"
+```
+
+`npm run check` includes the local health gate after build. `release:check` remains the publish dry-run gate and is intentionally separate from the normal local check.
+
+## Live workflow smoke
+
+When Figma is open and the SXL Studio plugin has an active **Remote Connect** session, run the non-destructive workflow smoke:
+
+```bash
+cd Utils/bridge
+npm run workflow:smoke
+# installed package alternatives:
+sxl-bridge smoke
+sxl-bridge-smoke
+```
+
+The workflow is intentionally small but real: `GET /api/status` → `get_plugin_status` → `find_components` → `build_mockup { dryRun: true }`. It proves that the plugin command path, queue, Remote Connect session, design-system discovery, and Design DSL dry-run are working together.
+
+To write an actual smoke frame into the active Figma file, opt in explicitly:
+
+```bash
+sxl-bridge-smoke --apply
+sxl-bridge-smoke --apply --cleanup
+```
+
+`--apply` requires `writesAllowed=true`; in Dev Mode/read-only contexts it fails before touching the canvas. `--cleanup` is only valid with `--apply`; it deletes the `rootNodeId` returned by the smoke frame creation step, so the canary can prove create/delete write access without leaving a frame in the file.
+
+For local agent routing/workflow validation without a running Bridge or Figma session, use:
+
+```bash
+npm run workflow:agent
+# installed package alternative:
+sxl-bridge-agent
+```
+
+`workflow:agent` validates representative RU/EN requests through `route_intent`, `plan_workflow`, and `preview_workflow`. It catches stale routing, missing preflight dependencies, unsafe generated plans, and read-only intents that accidentally plan write tools. `readiness` prints the Ultimate Bridge requirement audit locally, and `health:local` includes both the agent workflow gate and readiness gate.
+
+For a broader non-destructive live validation suite, use:
+
+```bash
+npm run workflow:validate
+# installed package alternatives:
+sxl-bridge validate
+sxl-bridge-live
+sxl-bridge-live --suite all --write-canary --cleanup
+```
+
+`workflow:validate` checks the running Bridge REST + MCP surface plus the connected plugin command path. The default `baseline` suite covers status, `/mcp` initialize/session/tools-list/tools-call `get_libraries` + `search_design_system` zero-config envelopes, `get_operator_runbook`, `list_tools`, `validate_screen_spec`, `preview_export_variables`, `get_figma_mcp_skills_parity`, and `plan_workflow` for Figma Design library discovery routing, resources-list/resources-read for `runtime-summary` + `operator-runbook` + `figma-mcp-skills-parity`, prompts-list/prompts-get for `sxl-operator` + `sxl-generate-design`, ultimate readiness, performance profile, operator runbook, tool catalogue, token/config reads, variable/style reads, component discovery, and a Design DSL dry-run. Readiness/performance endpoints are status-aware: `fail` fails the suite, while `warn` is surfaced without changing the non-destructive behavior. `--suite all` also verifies Code Connect registry/settings/selection status, selection variable definitions, dry-run `.figma.ts` template generation, database list commands, database payload export + import dry-run, variable/style spec dry-runs, dedupe dry-runs, variable/style coverage summary + paginated detail, variable/style coverage dry-run apply previews, unused variable/style scans, composition list + bulk dry-run + drift audit, component usage summary/detail pagination, component prop usage summary/detail pagination, and Doc Builder `build_doc_flow` dry-run. `--write-canary --cleanup` is the explicit write-path proof: it creates a tiny validation frame, verifies the returned `rootNodeId`, then deletes that same node. It requires an active Remote Connect session and exits non-zero when the plugin is not connected.
+
 ## MCP configuration (Cursor)
 
 Example `.cursor/mcp.json`:
@@ -111,7 +271,10 @@ Requires the plugin open in Figma, Remote Connect enabled, and Bridge running.
 curl -s http://127.0.0.1:37830/api/status
 ```
 
-Returns `ports`, `mcpStreamableHttp`, `session`, `queueLength`, `currentCommand`, `authEnabled`.
+Returns `ports`, `mcpStreamableHttp`, `session`, `queueLength`, `currentCommand`, `queue`,
+`runtime`, `telemetry`, and `authEnabled`. `runtime.health` is one of `ready`, `busy`,
+`degraded`, or `disconnected`; `runtime.issues` names the actionable condition. `telemetry`
+is sanitized and exposes counts/last failure metadata without payload values.
 
 ### Workspace blobs (Git Sync Local Storage)
 
@@ -147,13 +310,144 @@ curl -s 'http://127.0.0.1:37830/api/tools?devModeReadableOnly=true'
 
 Returns entries `{ name, category, description, requiresDesignMode, requiresComposition }`. MCP clients can call the equivalent `list_tools` meta-tool.
 
+Current entries also include routing metadata where available: `commandType`, `execution`, `pluginCommandTypes`, `aliases`, `naturalLanguageIntents`, `dryRunSupported`, `returnsLargeData`, `preferredBefore`, `preferredAfter`, and `timeoutMs`.
+
+### Workflow routing
+
+For broad natural-language requests, call `route_intent` first. For multi-step work, call `plan_workflow`, then validate the proposed sequence with `preview_workflow` before executing write tools. The preview checks unknown tools, missing or misordered `get_plugin_status`, missing or misordered design-system discovery, missing or misordered dry-run gates, and missing/misordered preflight tools declared by `preferredAfter`.
+
+For token export, this means `preview_export_variables` should precede `export_variables`. For Figma Design library discovery/search, use Bridge `get_libraries` / `search_design_system`. For official Figma MCP companion scope such as new-file creation, FigJam/Slides, diagrams, or hosted Code Connect repository context, the planner adds an explicit handoff step; avoid Bridge write tools unless the user narrows the task back to SXL/active-file Figma Design work.
+
+### Capability matrix
+
+MCP clients should call the `get_capability_matrix` tool. It returns the catalogue-derived matrix for agent routing and contract audits: execution mode, plugin command mapping, mode requirements, dry-run/large-data flags, and effective Bridge timeout. HTTP clients should use `GET /api/capabilities`, which is sourced from the same catalogue as `GET /api/tools`.
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/capabilities?category=mockup'
+```
+
+### Contract audit
+
+MCP clients should call `get_contract_audit` before release checks or when connecting a new agent/client. It verifies the current Bridge surface: required meta tools, recipe references, schema entrypoints, workflow gates, tool execution mapping, plugin command declarations, Remote Connect whitelist coverage and handler-path coverage when the plugin source is available, and timeouts. HTTP clients can use:
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/contract-audit'
+```
+
+The response is `{ ok, status, summary, requiredSurface, findings }`; release checks should treat `status: "fail"` as blocking. The CLI health gate uses the same contract audit locally, so `npm run check` catches stale catalogue/schema/recipe/Remote Connect whitelist/handler regressions before publish.
+
+### Figma MCP parity
+
+Bridge exposes a machine-readable parity map between official Figma MCP tools and SXL Bridge/SXL Studio capabilities:
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/figma-mcp-parity'
+```
+
+MCP clients can call `get_figma_mcp_parity` or attach `sxl://agent/figma-mcp-parity`. The matrix is intentionally explicit about companion requirements: Bridge plugin tools cover enabled-library search and active-file metadata in the open file, Bridge REST tools cover authenticated `whoami` and known file/team library reads when a Figma REST token is configured, `get_libraries` / `search_design_system` provide Figma MCP-compatible Figma Design library discovery/search over active-file and known REST sources, `get_design_context` covers active-file SXL-native design context, `get_metadata` covers hosted file/node metadata, `get_variable_defs` covers selection/local/enabled-library/known-file variable definitions, `get_screenshot` covers active-file SVG and known-node REST image rendering, Bridge `upload_assets` covers Figma Design image insertion, `get_context_for_code_connect` bundles active-file SXL Code Connect context, `generate_code_connect_template` generates dry-run-first local `.figma.ts` templates, and `get_code_connect_suggestions` ranks local source-file candidates before `codeconnect_save_binding`. Remote-only hosted Figma MCP capabilities such as new-file creation, hosted Code Connect repository context, and FigJam/Slides asset upload cannot be honestly implemented by a local Figma Design plugin Bridge.
+
+Bridge also exposes skill-level parity for the current official Figma MCP skills:
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/figma-mcp-skills-parity'
+```
+
+MCP clients can call `get_figma_mcp_skills_parity` or attach `sxl://agent/figma-mcp-skills-parity`. It maps the current official Figma MCP skills `figma-use`, `figma-use-figjam`, `figma-use-slides`, `figma-swiftui`, `figma-code-connect`, `figma-create-new-file`, `figma-generate-diagram`, `figma-generate-library`, and `figma-generate-design` to SXL recipes/resources/tools. The matrix keeps companion scope and agent-side codebase work explicit instead of pretending every official skill is a single Bridge plugin command.
+
+`route_intent` and `plan_workflow` are skill-aware. Current official FigJam, Slides, new-file, and diagram skills route to the official Figma MCP companion. `figma-swiftui` uses Bridge for active-file design context and Code Connect hints, then agent-side Swift edits. Older client aliases remain supported: `figma-implement-design` routes to `sxl-implement-design`, `figma-create-design-system-rules` routes to `sxl-generate-library`, and `figma-code-connect-components` routes to `sxl-code-connect`.
+
+For Figma Design image insertion, Bridge exposes `upload_assets`. It accepts PNG, JPG/JPEG, GIF, and WebP URLs or base64 payloads, enforces Figma MCP's 10MB-per-asset limit, supports `dryRun`, and applies images through the plugin's `set_image_fill` handler. It fills an existing `nodeId` when provided; otherwise it creates image rectangles. FigJam/Slides asset upload remains official Figma MCP companion scope.
+
+### Performance profile
+
+MCP clients should call `get_performance_profile` before broad audits, screen generation, bulk export/apply flows, or when optimizing agent behavior. It classifies every catalogued tool as `local`, `standard`, `summary`, `paginated-detail`, `write-preview`, or `long-running`, then exposes target budgets, large-data rules, dry-run-first rules, destructive-write warnings, and recent audit timings.
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/performance-profile?auditLimit=50'
+```
+
+Resource clients can attach `sxl://agent/performance-profile`. Treat `find_*` / large-data tools as paginated detail, use `analyze_*` / `audit_*` summaries before details, and call dry-run-capable write tools in preview mode before committing.
+
+### Runtime summary
+
+MCP clients should call `get_operator_runbook` as the start-here workflow chooser, then `get_bridge_runtime_summary` before heavy workflows. HTTP clients can use:
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/operator-runbook'
+curl -s 'http://127.0.0.1:37830/api/runtime-summary'
+```
+
+The runbook chooses the workflow, tools, dry-run gates, and companion handoff. The runtime summary reports plugin connection, current/queued commands, recent event/audit failures, auth state, MCP URL, and actionable recommendations. It is intentionally compact so agents can decide whether to proceed, wait, inspect logs, or ask the operator to open Remote Connect.
+
+### Ultimate readiness audit
+
+MCP clients can call `get_ultimate_readiness` before release or before claiming Bridge is complete. HTTP clients can use:
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/ultimate-readiness'
+```
+
+Local operators can run the same audit without a running Bridge server:
+
+```bash
+npm run readiness
+sxl-bridge readiness
+sxl-bridge-readiness --json
+npm run readiness:runtime
+npm run readiness:live
+```
+
+The audit maps the original Ultimate Bridge plan to concrete requirement rows: contract surface, SXL skills, Design DSL, component analytics, database tools, variables/styles, compositions, documentation, Code Connect, production safety, official Figma MCP tool parity, and official Figma MCP skill parity. The contract row includes Remote Connect whitelist and handler-path evidence when the plugin source is available. It deliberately keeps companion/future Figma MCP scope explicit instead of pretending the plugin API can create new files or handle FigJam/Slides. Add `--runtime` to report running Bridge HTTP/MCP proof next to local readiness; add `--require-live` when release sign-off must fail unless an active Remote Connect plugin session passes live validation.
+
+### Large-data response mode
+
+MCP tools marked `returnsLargeData` accept Bridge response controls:
+
+- `bridgeResponseMode: "auto"` (default) returns the full payload while it fits the MCP response budget, otherwise returns a compact envelope.
+- `bridgeResponseMode: "summary"` always returns `{ bridgeLargeData, summary, preview }` with counts, scalar fields, pagination hints, and a small item preview.
+- `bridgeResponseMode: "full"` explicitly returns the full payload. Use it only when the user needs exact data.
+
+Bridge strips these control fields before forwarding the command to the plugin. Raw HTTP `/api/command` remains an escape hatch for clients that intentionally want the exact plugin result.
+
+### Destructive confirmation gate
+
+Bridge blocks destructive plugin commands unless the caller passes `confirmDestructive: true` in the top-level payload. This applies to `delete_*`, `remove_*`, `reset_*`, `git_hard_pull`, `detach_instance`, `flatten_nodes`, `boolean_operation`, and `export_variables` when `deleteOrphans` or `allowDestructiveReorder` is enabled. Use `preview_export_variables` before token export; it reports the exact payload, effective plugin defaults, risk flags, and whether confirmation is required without touching Figma.
+
+```bash
+curl -s http://127.0.0.1:37830/api/command \
+  -H 'Content-Type: application/json' \
+  -d '{"commandType":"delete_nodes","payload":{"nodeIds":["1:2"],"confirmDestructive":true}}'
+```
+
+MCP tools expose the same `confirmDestructive` field where their schema is strict. Bridge strips `confirmDestructive` and `destructiveReason` before sending the payload to the plugin, so Remote Connect handlers do not need to accept those fields. Prefer dry-run/preview tools first when they exist.
+
 ### Audit trail
 
 ```bash
 curl -s 'http://127.0.0.1:37830/api/log?limit=50'
+curl -s 'http://127.0.0.1:37830/api/log?source=disk&limit=50'
+```
+
+`source=memory` (default) returns the in-process ring buffer. `source=disk` reads persisted JSONL entries from the OS cache directory (`env-paths`, product id `sxl-studio-bridge`, subdir `audit`) unless `SXL_BRIDGE_AUDIT_ROOT` is set. Entries contain only sanitized command metadata: `commandType`, `status`, `durationMs`, `payloadKeys`, `idempotencyKey`, and timestamp fields. Payload values are never stored.
+
+MCP clients can call `get_bridge_audit_log` with `{ source: "memory" | "disk", limit }`.
+
+### Queue snapshot
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/queue'
 ```
 
-Ring buffer of executed commands: `commandType`, `status`, `durationMs`, `payloadKeys`, `idempotencyKey`, `timestamp`.
+Live command queue snapshot: `current`, `queued`, and `immediate` commands with `commandId`, `commandType`, `status`, timings, and `payloadKeys`. Payload values are never exposed.
+
+### Command events
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/events?limit=100'
+curl -s 'http://127.0.0.1:37830/api/events?commandId=<command-id>'
+```
+
+Sanitized lifecycle/progress timeline: `queued`, `started`, `completed`/`failed`, timeout/cancel events, and plugin progress events when the plugin emits them. Events include ids, status, timings, `payloadKeys`, and `detailKeys`; payload/detail values are never exposed.
 
 ### Read token file (after `list_token_files`)
 
@@ -201,24 +495,27 @@ Failures return a structured envelope:
 }
 ```
 
-Known codes: `EDITOR_MODE_READONLY`, `BRIDGE_TIMEOUT`, `BRIDGE_CANCELLED`, `BRIDGE_UNAUTHORIZED`, `BRIDGE_ERROR`. MCP tools decode the envelope before returning to the agent.
+Known codes: `EDITOR_MODE_READONLY`, `DESTRUCTIVE_CONFIRMATION_REQUIRED`, `BRIDGE_TIMEOUT`, `BRIDGE_CANCELLED`, `BRIDGE_UNAUTHORIZED`, `BRIDGE_ERROR`. MCP tools decode the envelope before returning to the agent.
 
 ## MCP tools (summary)
 
 Registered in `src/mcp-factory.ts` via `tools/*.ts`:
 
-- **Diagnostics / meta:** `get_plugin_status`, `is_dev_mode`, `get_selection_summary`, `get_drift_status`, `list_tools`.
-- **Tokens / workspace:** `list_token_files`, `get_token_file_content`, `save_token_file` (upsert), `create_token_file`, `delete_token_file`, `move_token_file`, `rename_token_file`, `get_tokens_config`, `save_tokens_config`, `export_variables`, `reset_diff*`, `reapply_token_bindings`, `cross_file_sync_*`, `get_applied_tokens`.
+- **Diagnostics / meta:** `get_plugin_status`, `is_dev_mode`, `get_selection_summary`, `get_drift_status`, `get_operator_runbook`, `route_intent`, `plan_workflow`, `preview_workflow`, `list_tools`, `get_capability_matrix`, `get_contract_audit`, `get_figma_mcp_parity`, `get_performance_profile`, `get_bridge_audit_log`, `get_ultimate_readiness`.
+- **Tokens / workspace:** `list_token_files`, `get_token_file_content`, `save_token_file` (upsert), `create_token_file`, `delete_token_file`, `move_token_file`, `rename_token_file`, `get_tokens_config`, `save_tokens_config`, `preview_export_variables` (read-only export preflight), `export_variables`, `reset_diff*`, `reapply_token_bindings`, `cross_file_sync_*`, `get_applied_tokens`.
 - **Composition:** `export_composition_json`, `get_codegen`, `list_compositions`, `generate_composition`, `apply_composition`, `preview_composition`, `check_composition_linked`, `inspect_selection`.
 - **Variables:** `get_variables`, `create_variable_collection`, `create_variable`, `bind_variable`, `rename_variable`, `delete_variable`, `rename_variable_collection`, `delete_variable_collection`, `add_variable_mode`, `remove_variable_mode`, `rename_variable_mode`, `set_variable_mode_value`, `set_variable_scopes`, `set_variable_code_syntax`, plus batch ops `batch_create_variables` / `batch_set_variable_values` / `batch_delete_variables` / `batch_bind_variables`.
 - **Variables orchestration (Phase B, Bridge `1.6.0`+):** `import_variable_spec` (idempotent bulk create / update with aliases, `dryRun`), `analyze_variable_order` (read-only ordering diff), `dedupe_variables` (merge duplicates, dry-run by default; canvas write only with `apply: true`), `rebind_variable_aliases` (bulk alias rewrite, `dryRun`), `apply_coverage_suggestions` (audit suggestions → real bindings, dry-run by default).
 - **Styles:** `get_local_styles`, `create_paint_style`, `create_text_style`, `create_effect_style`, `set_text_style`, `set_effect_style`, `set_stroke_style`, `set_fill_style`, `import_style_by_key`.
 - **Styles orchestration (Phase C, Bridge `1.6.0`+):** `import_style_spec` (idempotent bulk create / update of Paint / Text / Effect styles, `dryRun`), `dedupe_styles` (merge duplicates `byName | bySignature`, dry-run by default; canvas write only with `apply: true`), `rebind_style_consumers` (bulk styleId rewrite on consumer nodes, `dryRun`), `audit_style_drift` (READ-ONLY drift between local Paint styles and Variables / `expectations[]`), `apply_style_coverage_suggestions` (Phase A `find_style_coverage_misses` → real `setStyleId*` writes, dry-run by default).
-- **Mockup-from-DesignSystem (Phase D, Bridge `1.6.0`+):** `find_components` (READ-ONLY paginated catalogue of local + library-instantiated components with `componentPropertyDefinitions`; Dev-Mode compatible), `build_mockup` (assemble one auto-layout mockup from a declarative `instance | section | spacer | text` item tree with property / text / fill-binding overrides; `dryRun`-aware), `apply_mockup_dataset` (clone a template per dataset row with row-specific overrides; `dryRun`-aware). Replaces hand-rolled `use_figma { figma.createInstance(...).setProperties(...) }` loops.
+- **Mockup-from-DesignSystem / Design DSL (Phase D):** `inspect_design_system` (READ-ONLY aggregate: components/props, variables, styles, token config, composition index), `validate_screen_spec`, `build_screen`, `update_screen`, `find_components`, `build_mockup`, `apply_mockup_dataset`. Prefer `inspect_design_system → validate_screen_spec/build_screen dryRun → build_screen/update_screen` for full screens; keep `build_mockup` as the low-level compatible DSL. Payload contract is exposed at `sxl://agent/schemas/design-dsl-v1`. Replaces hand-rolled `use_figma { figma.createInstance(...).setProperties(...) }` loops.
+- **Figma REST companion:** `figma_rest_diagnose`, `figma_rest_whoami`, `figma_rest_get_file_metadata`, `figma_rest_get_file`, `figma_rest_get_file_nodes`, `figma_rest_get_images`, `figma_rest_get_image_fills`, `figma_rest_get_file_components`, `figma_rest_get_file_component_sets`, `figma_rest_get_file_styles`, `figma_rest_get_team_components`, `figma_rest_get_team_component_sets`, `figma_rest_get_team_styles`, `figma_rest_get_variables_local`, `figma_rest_get_variables_published`, `figma_rest_search_design_system`. Bridge-local, read-only, no Remote Connect session required; use `FIGMA_TOKEN` / `FIGMA_ACCESS_TOKEN`. The Figma MCP-compatible `get_libraries` / `search_design_system` tools can orchestrate these REST reads together with active-file plugin sources.
 - **Compositions orchestration (Phase E, Bridge `1.6.0`+):** `bulk_generate_compositions` (bulk `generate` / `apply` of composition files in one MCP call; filters `fileIds | names | prefix`; `operation: auto | generate | apply`; per-item error isolation; `dryRun`-aware), `audit_composition_drift` (READ-ONLY drift detector between workspace composition files and tracked Figma components; statuses `linked | unlinked | drift | missing`; Dev-Mode safe). Replaces hand-rolled `for-of` loops over `generate_composition` / `apply_composition` and per-file `check_composition_linked` polling.
-- **Data / nodes:** `apply_mapping`, `apply_all_mappings`, `count_apply_targets`, `generate_instances`, `apply_image`, plus direct node helpers in `data.ts` / `figma-nodes.ts` (`set_node_fill_variable`, `create_rectangle`, `set_auto_layout`, `duplicate_subtree`, `create_component_instance`, `apply_documentation_payload`, extended `create_frame` / `create_text`).
+- **Data / nodes:** database CRUD (`list_datasets`, `get_dataset`, `save_dataset`, `delete_dataset`, `list_assets`, `get_asset`, `save_asset`, `delete_asset`, `list_mappings`, `get_mapping`, `save_mapping`, `delete_mapping`; save/delete support `dryRun` preview), portable database backup/restore (`export_database_payload`, `import_database_payload`; import defaults to `dryRun` and requires overwrite confirmation for existing IDs), mapping apply/generate preflights (`apply_mapping`, `apply_all_mappings`, `generate_instances`; all support `dryRun` preview before writing, and apply/count/generate workflows accept explicit `targetNodeIds` as deterministic selection roots), design-context orchestration (`get_design_context`), variable/style definition orchestration (`get_variable_defs`), Figma MCP-compatible library tools (`get_libraries`, `search_design_system`), enabled-library search/read tools (`search_enabled_library_assets`, `inspect_enabled_libraries`, `list_enabled_library_variables`), `get_metadata`, `get_screenshot`, `count_apply_targets`, `apply_image`, `upload_assets` (dry-run image URL/base64 upload into Figma Design), `get_code_connect_suggestions` (local binding candidates), plus direct node helpers in `data.ts` / `figma-nodes.ts` (`set_node_fill_variable`, `create_rectangle`, `set_auto_layout`, `duplicate_subtree`, `create_component_instance`, `apply_documentation_payload`, extended `create_frame` / `create_text`).
 - **Git:** `git_pull`, `git_hard_pull`, `git_push`.
-- **Orchestration:** `generate_code_from_url`, `compose_from_url`, `document_component`, `index_icons_for_export` (read-only icon index: COMPONENT + COMPONENT_SET variants with page/section metadata).
+- **Audit analytics:** variable/style usage and coverage tools plus component analytics (`analyze_component_usage`, `find_component_usages`, `analyze_component_prop_usage`, `find_component_prop_usages`).
+- **Audit remediation:** coverage audits are read-only; use `apply_coverage_suggestions` / `apply_style_coverage_suggestions` in preview mode before committing fixes.
+- **Orchestration:** `generate_code_from_url`, `compose_from_url`, `document_component`, `index_icons_for_export` (read-only icon index: COMPONENT + COMPONENT_SET variants with page/section metadata), `build_scenario_from_md`, `build_doc_flow` (node pages or `compositionFileId` pages rendered through the composition pipeline).
 
 ### MCP Resources
 
@@ -230,11 +527,34 @@ Registered in `src/mcp-factory.ts` via `tools/*.ts`:
 | `sxl://tokens/files` | Token file index |
 | `sxl://tokens/files/{fileId}` | Raw token file body |
 | `sxl://compositions/index` | Composition JSON index |
+| `sxl://agent/operator-runbook` | Start-here workflow chooser: preflight, safety rules, common SXL/Figma routes, dry-run gates, and live-readiness checks |
 | `sxl://agent/recipes/index` | Intent router (start here) |
-| `sxl://agent/recipes/{doc-tokens,doc-component,doc-composition,doc-flow,doc-spec-v2,template-discovery,variable-palette,compose-with-variables,scenario-from-markdown,variable-usage,audit-coverage,find-unused,bulk-variables,auto-bind-from-audit,bulk-styles,style-drift,mockup-builder,bulk-compositions,composition-drift}` | Doc Builder + audit + Phase B + Phase C + Phase D + Phase E orchestration recipes |
+| `sxl://agent/recipes/{sxl-use,sxl-implement-design,sxl-generate-design,sxl-generate-library,sxl-code-connect,sxl-audit,sxl-doc-builder,sxl-data-apply-mapping,sxl-data-apply-all,sxl-data-generate-instances,sxl-database-transfer,figma-mcp-companion,doc-tokens,doc-component,doc-composition,doc-flow,doc-spec-v2,template-discovery,variable-palette,compose-with-variables,scenario-from-markdown,variable-usage,audit-coverage,find-unused,bulk-variables,auto-bind-from-audit,bulk-styles,style-drift,mockup-builder,bulk-compositions,composition-drift}` | SXL skills + SXL database/data workflows + official Figma MCP companion routing + Doc Builder + audit + Phase B + Phase C + Phase D + Phase E orchestration recipes |
+| `sxl://agent/figma-mcp-parity` | Official Figma MCP tool → SXL Bridge/SXL Studio equivalent / companion / future scope map |
+| `sxl://agent/figma-mcp-skills-parity` | Official Figma MCP skill → SXL Bridge recipes/resources/tools / companion / agent-codebase-work map |
+| `sxl://agent/performance-profile` | Command budgets, large-data/dry-run policy, destructive-write warnings, and recent audit timings |
+| `sxl://agent/runtime-summary` | Plugin connection, queue pressure, recent failures, MCP URL, auth flag, and recommendations |
+| `sxl://agent/ultimate-readiness` | Requirement-by-requirement Ultimate Bridge Toolkit readiness audit |
 
 Cursor / Claude can attach these as context without calling tools.
 
+### MCP Prompts
+
+Bridge also registers prompt templates for MCP clients that support `prompts/list` / `prompts/get`:
+
+- `sxl-router`
+- `sxl-operator`
+- `sxl-use`
+- `sxl-implement-design`
+- `sxl-generate-design`
+- `sxl-generate-library`
+- `sxl-code-connect`
+- `sxl-audit`
+- `sxl-doc-builder`
+- `figma-mcp-companion`
+
+Each prompt returns a concise workflow instruction with the relevant `sxl://agent/recipes/*` resource, preferred tools, forbidden anti-patterns, dry-run gates, and done criteria. `figma-mcp-companion` is the explicit handoff prompt for official Figma MCP remote-only scopes such as new-file creation, FigJam/Slides, and diagrams; Figma Design library discovery should use Bridge `get_libraries` / `search_design_system`. Use prompts when the MCP client can inject prompt templates directly; use resources when the client prefers attachable context.
+
 ## Dev Mode support
 
 | Context | Reads | Canvas writes | Token/config/git writes |
@@ -251,6 +571,12 @@ Cursor / Claude can attach these as context without calling tools.
 npm run test    # Vitest
 npm run build   # tsc → dist/
 npm run lint    # tsc --noEmit
+npm run check   # lint + build + test
+npm run readiness # local Ultimate Bridge requirement audit
+npm run readiness:runtime # local readiness + running Bridge HTTP/MCP proof
+npm run readiness:live # strict live Figma E2E proof; requires Remote Connect
+npm run release:check # check + npm publish --dry-run
+npm run release:check:live # check + strict live readiness gate
 ```
 
 ## Publishing to npm