canicode 0.10.4 → 0.11.0

package/docs/CUSTOMIZATION.md

@@ -104,7 +104,7 @@ Override score, severity, or enable/disable individual rules:
 | Rule ID | Default Score | Default Severity |
 |---------|--------------|-----------------|
 | `fixed-size-in-auto-layout` | -6 | risk |
-| `missing-size-constraint` | -8 | risk |
+| `missing-size-constraint` | -1 | missing-info |
 
 **Code Quality (4 rules)**
 
@@ -134,8 +134,8 @@ Override score, severity, or enable/disable individual rules:
 
 | Rule ID | Default Score | Default Severity |
 |---------|--------------|-----------------|
-| `missing-interaction-state` | -1 | suggestion |
-| `missing-prototype` *(disabled)* | -3 | missing-info |
+| `missing-interaction-state` | -1 | missing-info |
+| `missing-prototype` | -1 | missing-info |
 <!-- RULE_TABLE_END -->
 
 ### Example Configs
@@ -176,6 +176,42 @@ Override score, severity, or enable/disable individual rules:
 
 ---
 
+## Cursor MCP (canicode)
+
+Configure the canicode MCP server so Cursor exposes `analyze`, `gotcha-survey`, and other tools.
+
+### Project config (`.cursor/mcp.json`)
+
+Create or merge into `.cursor/mcp.json` in your repository root:
+
+```json
+{
+  "mcpServers": {
+    "canicode": {
+      "command": "npx",
+      "args": ["-y", "--package=canicode", "canicode-mcp"]
+    }
+  }
+}
+```
+
+Use long-form `--package` (short `-p` can confuse some parsers). Set your Figma token once with `npx canicode init --token figd_…` — the MCP server reads `~/.canicode/config.json`; you do not need `FIGMA_TOKEN` in the MCP block unless your team prefers env injection.
+
+### Gotcha survey in Cursor
+
+1. Add the MCP config above and restart Cursor (or reload MCP).
+2. Run `npx canicode init --token … --cursor-skills` to install **canicode**, **canicode-gotchas**, and **canicode-roundtrip** (with `helpers.js`) under `.cursor/skills/`, and ensure the shared answer file exists at `.claude/skills/canicode-gotchas/SKILL.md` when needed (or run full `canicode init` and add `--cursor-skills`). Authoring is single-source under `.claude/skills/` in the repo; the npm build writes `skills/cursor/` (gotchas strip `# Collected Gotchas`; other skills are full copies).
+3. In chat, @-mention **canicode**, **canicode-gotchas**, or **canicode-roundtrip** as needed. For roundtrip, the Figma MCP must expose **`use_figma`** in the session — same requirement as Claude Code.
+
+### Manual test checklist (#407)
+
+- [ ] MCP: Cursor shows `canicode` connected and the tools list includes `gotcha-survey` (and `analyze` if testing roundtrip Step 1).
+- [ ] Figma MCP: `use_figma` is available when testing **roundtrip** (install + restart host if tools are missing).
+- [ ] Calling `gotcha-survey` with a local fixture path returns JSON with `designGrade` and `questions` / `isReadyForCodeGen`.
+- [ ] After the Q&A loop, `npx canicode upsert-gotcha-section …` succeeds and updates `.claude/skills/canicode-gotchas/SKILL.md`.
+- [ ] Optional: @ **canicode-roundtrip** — Step 4 reads `helpers.js` from `.cursor/skills/canicode-roundtrip/helpers.js` after `canicode init --cursor-skills`.
+
+---
 
 ## Telemetry
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canicode",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "mcpName": "io.github.let-sunny/canicode",
   "description": "Lint Figma designs for AI code-gen and roundtrip the answers back into the file. CLI + MCP server.",
   "type": "module",

package/skills/canicode-gotchas/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: canicode-gotchas
-description: Gotcha survey workflow plus accumulating per-design answers — one Workflow region on top, numbered sections appended per Figma design
+description: Gotcha survey (Claude Code or Cursor) — Q&A workflow; answers accumulate in .claude/skills/canicode-gotchas/SKILL.md for figma-implement-design
 ---
 
-# CanICode Gotchas -- Design Gotcha Survey & Skill Writer
+# CanICode Gotchas — Design Gotcha Survey
 
-Run a gotcha survey on a Figma design to identify implementation pitfalls, collect developer answers, and upsert them into this skill file so code generation agents can reference them automatically. The file has two regions: the **Workflow** below (installed by `canicode init`, never overwritten) and the **Collected Gotchas** region at the bottom (one numbered section per design, replaced in place on re-runs).
+Run a gotcha survey on a Figma design to collect implementation context that Figma cannot encode natively, capture developer/designer answers, and upsert them into **`.claude/skills/canicode-gotchas/SKILL.md`** so downstream `figma-implement-design` runs have annotation-ready context. In this model, rules do rule-based best-practice detection, and gotcha is the annotation output from that detection. Some gotchas come from violation rules (what is wrong and how to resolve it); others come from info-collection rules (neutral context Figma cannot represent, like interaction intent/state).
+
+**Install location:** The workflow prose may live under `.claude/skills/canicode-gotchas/SKILL.md` (default `canicode init`) or be copied to `.cursor/skills/canicode-gotchas/SKILL.md` (`canicode init --cursor-skills`). The **authoritative gotcha store** is always **`.claude/skills/canicode-gotchas/SKILL.md`** — the CLI `upsert-gotcha-section` writes there only. In the `.claude` copy, this file has two regions: the **Workflow** below (installed by `canicode init`, never overwritten manually) and the **Collected Gotchas** region at the bottom (one numbered section per design, replaced in place on re-runs).
 
 ## Prerequisites
 
-- **canicode MCP server** (preferred): `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; the short-form `-y -p` collides with `claude mcp add`'s parser (#366). The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the host environment, so do **not** pass `-e FIGMA_TOKEN=…` here (#364).
-- **Without canicode MCP** (fallback): the `canicode gotcha-survey --json` CLI produces the same response shape — no MCP installation required.
-- **FIGMA_TOKEN** configured for live Figma URLs
+- **canicode MCP** (recommended): Register the server with your host — **Claude Code:** `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; the short-form `-y -p` collides with `claude mcp add`'s parser (#366); do **not** pass `-e FIGMA_TOKEN=…` here (#364). **Cursor / other hosts:** add `canicode-mcp` to your MCP config — see [Customization guide](https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode) (`~/.cursor/mcp.json` or project `.cursor/mcp.json`). The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the environment.
+- **Without canicode MCP** (fallback): `npx canicode gotcha-survey "<input>" --json` — same JSON shape as the MCP tool.
+- **FIGMA_TOKEN** configured for live Figma URLs.
+- **Gotcha destination on disk:** `.claude/skills/canicode-gotchas/SKILL.md` must exist before upsert — run `npx canicode init --token …` (add `--cursor-skills` if you also want the workflow file under `.cursor/skills/`).
 
 ## Workflow
 
@@ -38,12 +41,12 @@ Either channel returns:
 
 If `isReadyForCodeGen` is `true` or `questions` is empty:
 - Tell the user: "This design scored **{designGrade}** and is ready for code generation — no gotchas to resolve."
-- Do NOT write to the skill file.
+- Do NOT write to `.claude/skills/canicode-gotchas/SKILL.md`.
 - Stop here.
 
 ### Step 3: Present questions to the user
 
-The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so the SKILL never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and batchable-rule list all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
+The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so this skill never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and batchable-rule list all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
 
 For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
 
@@ -90,19 +93,19 @@ When applying the batched answer, expand back to per-question records in Step 4
 
 ### Step 4: Upsert the gotcha section
 
-After collecting all answers, **upsert** this design's section into the `# Collected Gotchas` region at the bottom of this file:
+After collecting all answers, **upsert** this design's section into the `# Collected Gotchas` region at the bottom of:
 
 ```
 .claude/skills/canicode-gotchas/SKILL.md
 ```
 
-This file goes in the **user's project** (current working directory), NOT in the canicode repo. The Workflow region above **must never be modified** — only the `# Collected Gotchas` region below is touched.
+That path is in the **user's project** (current working directory), NOT in the canicode repo. If you are following this workflow from a copy under `.cursor/skills/`, still upsert into **`.claude/skills/...`** only — never write gotcha answers into the `.cursor` copy. The Workflow region in the `.claude` file **must never be modified manually** — only the `# Collected Gotchas` region is touched (via the CLI below).
 
 #### Step 4a: Use the `designKey` from the survey response
 
 `designKey` uniquely identifies the design so re-running on the same URL replaces the existing section in place. The survey response carries it on `survey.designKey` — read it directly. Do **not** parse the input URL in prose.
 
-The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every shape with vitest coverage so the SKILL stays ADR-016-compliant:
+The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every shape with vitest coverage so this workflow stays ADR-016-compliant:
 
 - **Figma URL** → `<fileKey>#<nodeId>` with `-` → `:` normalization on the nodeId. Example: `https://figma.com/design/abc123XYZ/My-File?node-id=42-100&t=ref` → `designKey = "abc123XYZ#42:100"`. Trailing query parameters (`?t=...`, `?mode=...`) are dropped.
 - **Figma URL without `node-id`** → just `<fileKey>` (file-level key).
@@ -110,7 +113,7 @@ The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every sha
 
 #### Step 4b: Upsert via the canicode CLI
 
-File-state detection (4-way: missing / valid / missing-heading / clobbered) and section walking (find existing `## #NNN — ...` by `Design key` substring, otherwise compute the next monotonic zero-padded NNN) are deterministic markdown operations and live in `core/gotcha/upsert-gotcha-section.ts` with vitest coverage — the SKILL never re-implements them in prose (per ADR-016).
+File-state detection (4-way: missing / valid / missing-heading / clobbered) and section walking (find existing `## #NNN — ...` by `Design key` substring, otherwise compute the next monotonic zero-padded NNN) are deterministic markdown operations and live in `core/gotcha/upsert-gotcha-section.ts` with vitest coverage — do not re-implement them in prose (per ADR-016).
 
 Render the per-design section markdown using the **Output Template** below with the literal string `{{SECTION_NUMBER}}` in the header (the CLI substitutes the right NNN for you — preserves it on replace, computes the next monotonic value on append). Then invoke:
 
@@ -168,7 +171,7 @@ Each per-design section in the `# Collected Gotchas` region has this exact shape
 | `analyzedAt` | Current timestamp (ISO 8601) |
 | `ruleId` | `ruleId` from each question |
 | `nodeName` | `nodeName` from each question |
-| `severity` | `severity` from each question (blocking / risk) |
+| `severity` | `severity` from each question (blocking / risk / missing-info — the last surfaces only for info-collection rules per #406) |
 | `nodeId` | `nodeId` from each question |
 | `instanceContext` | When present on the question, copy `parentInstanceNodeId`, `sourceNodeId`, `sourceComponentId`, `sourceComponentName` into the bullet above (roundtrip / Plugin apply) |
 | `question` | `question` from each question |
@@ -186,7 +189,7 @@ This ensures the code generation agent knows the gotcha exists even if no answer
 
 ## Edge Cases
 
-- **No questions returned**: The design is ready for code generation. Inform the user and stop (Step 2). Do not touch the file.
+- **No questions returned**: The design is ready for code generation. Inform the user and stop (Step 2). Do not touch `.claude/skills/canicode-gotchas/SKILL.md`.
 - **Re-run on the same design**: Replace that design's section in place (matched by `Design key`) — preserve the original `#NNN` number. Do NOT append a duplicate.
 - **Re-run on a different design**: Append a new section with the next `#NNN`. Prior designs' sections are untouched.
 - **Workflow region**: Never modified. If you notice the Workflow region has been edited by the user, leave their edits alone — only the `# Collected Gotchas` region is under skill control.

package/skills/canicode-roundtrip/SKILL.md

@@ -10,8 +10,8 @@ Orchestrate the full design-to-code roundtrip: analyze a Figma design for readin
 
 ## Prerequisites
 
-- **Figma MCP server** installed (provides `get_design_context`, `get_screenshot`, `use_figma`, and other Figma tools) — REQUIRED, there is no CLI fallback for `use_figma`
-- **canicode MCP server** (preferred): `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; the short-form `-y -p` collides with `claude mcp add`'s parser (#366). The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the host environment, so do **not** pass `-e FIGMA_TOKEN=…` here (#364).
+- **Figma MCP server** installed (provides `get_design_context`, `get_screenshot`, `use_figma`, and other Figma tools) — REQUIRED, there is no CLI fallback for `use_figma`. Register it with your host (e.g. Claude Code: `claude mcp add -s project -t http figma https://mcp.figma.com/mcp`; Cursor: add the Figma MCP entry per host docs / project `.mcp.json`).
+- **canicode MCP** (preferred): **Claude Code:** `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; short `-y -p` collides with `claude mcp add`'s parser (#366); do **not** pass `-e FIGMA_TOKEN=…` here (#364). **Cursor / other hosts:** add `canicode-mcp` to MCP config — see [Customization guide](https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode). The server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the environment.
 - **Without canicode MCP** (fallback): Steps 1 (analyze) and 3 (gotcha-survey) shell out to `npx canicode <command> --json` — same JSON shape as the MCP tools. Step 4 (apply to Figma) still requires Figma MCP `use_figma`.
 - **FIGMA_TOKEN** configured for live Figma URLs
 - **Figma Full seat + file edit permission** (required for `use_figma` to modify the design)
@@ -20,13 +20,13 @@ Orchestrate the full design-to-code roundtrip: analyze a Figma design for readin
 
 ### Step 0: Verify Figma MCP tools are loaded
 
-Before Step 1, verify that `use_figma` is callable in **this** session — not merely listed in `.mcp.json`. Newly registered MCP servers (e.g. via `claude mcp add -s project -t http figma https://mcp.figma.com/mcp`) require a Claude Code restart to load their tools; reading `.mcp.json` is not a substitute for checking the live tool list you have access to right now.
+Before Step 1, verify that `use_figma` is callable in **this** session — not merely listed in `.mcp.json`. Newly registered MCP servers require a **host restart or MCP reload** so tools appear (e.g. Claude Code: restart after `claude mcp add …`; Cursor: restart Cursor or reload MCP after editing `.cursor/mcp.json`). Reading `.mcp.json` is not a substitute for checking the live tool list you have access to right now.
 
 If `use_figma` is unavailable in the current session, **Do NOT proceed to Step 1**. Steps 1 (analyze) and 3 (gotcha-survey) spend real Figma API calls and 5–15 minutes of human survey time before Step 4 would otherwise discover `use_figma` is missing. Halt immediately and tell the user:
 
-1. Confirm `.mcp.json` registers the Figma MCP entry (e.g. `figma` under `mcpServers`).
-2. Restart Claude Code so the newly registered tools load.
-3. Re-invoke `/canicode-roundtrip <url>`.
+1. Confirm `.mcp.json` (project or user) registers the Figma MCP entry (e.g. `figma` under `mcpServers`).
+2. Restart the IDE / agent host (or reload MCP) so the newly registered tools load.
+3. Re-invoke the roundtrip (Claude Code slash command `/canicode-roundtrip`, or Cursor: @ **canicode-roundtrip** with the Figma URL).
 
 See the Edge Case **No Figma MCP server** below for the one-way fallback when Figma MCP genuinely cannot be installed — the precheck above is for the common "installed but not restarted" case, not a replacement for that fallback.
 
@@ -227,7 +227,7 @@ The helper walks the tiers in order; variable binding is an alternative writeFn
 
 1. **Scene (instance) node** — `await figma.getNodeByIdAsync(question.nodeId)` and apply the write inside `try/catch`. If the answer names a design-system token (`{ variable: "name" }`), the helper calls `setBoundVariable` / `setBoundVariableForPaint` first and that binding bypasses the override gate — otherwise it performs a raw-value write. Success → done (local change only). Mark result with ✅.
 2. **Definition (source) node — opt-in only** — Runs only when the orchestrator passes `allowDefinitionWrite: true` on the helper context (after a batch-level confirmation naming the source component AND the propagation set). When the flag is off (the ADR-012 default), a recognized instance-override failure (override-error or silent-ignore) short-circuits here and routes directly to tier 3 — the definition node is never touched. When the flag is on, the helper loads `question.sourceChildId` (or walks `getMainComponentAsync()` if needed) and writes using the same bind-if-token-else-raw shape as tier 1; changes propagate to **every non-overridden instance** in the file (Experiment 10). Mark result with 🌐.
-3. **Annotation fallback — default path** — Under the ADR-012 default this is where override-errors and silent-ignores land: the helper annotates the **scene** node with markdown that names the source component as the recommended write target and notes that the instance kept its current value to avoid unintended fan-out. When `allowDefinitionWrite` is on, this tier also catches any definition-tier throw (e.g. Experiment 10 external-library read-only case, `mainComponent.remote === true` / *"Cannot write to internal and read-only node"*, and the `mainComponent === null` branch where `getMainComponentAsync()` resolves with no definition to name — see Experiment 11 / ADR-011). Either way, mark result with 📝.
+3. **Annotation fallback — default path** — Under the ADR-012 default this is where override-errors and silent-ignores land: the helper annotates the **scene** node with markdown that names the actual no-op (the property silently ignored the write or the override was rejected) and points to the source component as the correct write target. When `allowDefinitionWrite` is on, this tier also catches any definition-tier throw (e.g. Experiment 10 external-library read-only case, `mainComponent.remote === true` / *"Cannot write to internal and read-only node"*, and the `mainComponent === null` branch where `getMainComponentAsync()` resolves with no definition to name — see Experiment 11 / ADR-011). Either way, mark result with 📝.
 
 **Confirmation is a batch-level concern — and only needed when opting in.** A `use_figma` call runs one JavaScript batch and cannot pause mid-batch for user input. Under the ADR-012 default (`allowDefinitionWrite: false`), no propagation happens, so no confirmation is required — override-errors annotate and move on. The orchestrator sets `allowDefinitionWrite: true` only after enumerating the likely propagation set to the user up-front and collecting **one confirmation for the whole batch** that names the source component(s) and the affected instance set. When describing impact, note that the write reaches every **non-overridden** instance — any instance with a local override for the same property keeps its override. The helper below never prompts — it assumes that if the flag is on, confirmation already happened.
 
@@ -276,11 +276,11 @@ Branches on `probe`:
 
 The probe is read-only and idempotent; running it before the picker adds one round-trip but saves the user a confusing "I opted in, why did I get annotations?" moment that #342 surfaced live on Simple Design System (Community).
 
-**Shared helpers (bundled)** — the deterministic helpers live in TypeScript at `src/core/roundtrip/*.ts` and are bundled to a single IIFE at `.claude/skills/canicode-roundtrip/helpers.js`. `use_figma` only accepts a self-contained JS string, so the source of truth is TypeScript (with vitest coverage) and the bundle is the delivery artifact.
+**Shared helpers (bundled)** — the deterministic helpers live in TypeScript at `src/core/roundtrip/*.ts` and are bundled to a single IIFE shipped next to this skill as `helpers.js`. `use_figma` only accepts a self-contained JS string, so the source of truth is TypeScript (with vitest coverage) and the bundle is the delivery artifact.
 
 **Usage in a roundtrip session:**
 
-1. Read `.claude/skills/canicode-roundtrip/helpers.js` once at the start of Step 4.
+1. Read `helpers.js` from the same directory as this skill once at the start of Step 4 — typically `.claude/skills/canicode-roundtrip/helpers.js` (Claude Code / default `canicode init`) or `.cursor/skills/canicode-roundtrip/helpers.js` (Cursor with `canicode init --cursor-skills`).
 2. Prepend its contents verbatim at the top of every `use_figma` batch body — it registers a single global `CanICodeRoundtrip`.
 3. Reference exposed globals as `CanICodeRoundtrip.*`:
    - `stripAnnotations(annotations)` — normalizes the D1 label/labelMarkdown mutex on readback.
@@ -402,7 +402,7 @@ Notes:
 
 #### Strategy D: Auto-fix lower-severity issues from analysis
 
-The gotcha survey covers only blocking/risk severity. Lower-severity rules appear in `analyzeResult.issues[]` without a survey question. Each issue carries the same pre-computed fields (`applyStrategy`, `targetProperty`, `annotationProperties`, `suggestedName`, `isInstanceChild`, `sourceChildId`). The bundled helper handles the loop, the filter (`applyStrategy === "auto-fix"`), the naming-vs-annotation branch, and the per-issue outcome accumulator in one call:
+The gotcha survey covers blocking/risk severity plus `missing-info` severity from info-collection rules (#406 — currently `missing-prototype`, `missing-interaction-state`). All other lower-severity rules appear in `analyzeResult.issues[]` without a survey question. Each issue carries the same pre-computed fields (`applyStrategy`, `targetProperty`, `annotationProperties`, `suggestedName`, `isInstanceChild`, `sourceChildId`). The bundled helper handles the loop, the filter (`applyStrategy === "auto-fix"`), the naming-vs-annotation branch, and the per-issue outcome accumulator in one call:
 
 ```javascript
 const outcomes = await CanICodeRoundtrip.applyAutoFixes(analyzeResult.issues, { categories });
@@ -577,6 +577,7 @@ Follow the **figma-implement-design** skill workflow to generate code from the F
 
 - Gotchas with severity **blocking** MUST be addressed — the design cannot be implemented correctly without this information
 - Gotchas with severity **risk** SHOULD be addressed — they indicate potential issues that will surface later
+- Gotchas with severity **missing-info** from info-collection rules (`purpose === "info-collection"`, e.g. `missing-prototype`, `missing-interaction-state`) are annotation-primary (#406): the answer describes implementation context Figma cannot encode (click target, state variants). Treat them as code-generation context rather than violations to fix — the rule's score impact is minimal by design
 - Reference the specific node IDs from gotcha answers to locate the affected elements in the design
 - Pass the Figma URL or `survey.designKey` to `figma-implement-design` so it can grep the matching `## #NNN — …` section in `.claude/skills/canicode-gotchas/SKILL.md` instead of reading the whole accumulated file
 
@@ -613,5 +614,5 @@ Code: <files generated / next-step pointer from figma-implement-design>
 - **Partial gotcha answers**: Apply only the answered questions. Skipped/n/a questions are neither applied nor annotated.
 - **use_figma call fails for a node**: Report the error for that specific node, continue with other nodes. Failed property modifications become annotations so the context is not lost.
 - **Re-analyze shows new issues**: Only address issues from the original gotcha survey. New issues may appear due to structural changes — report them but do not re-enter the gotcha loop.
-- **Very large design (many gotchas)**: The gotcha survey already deduplicates sibling nodes and filters to blocking/risk severity only. If there are still many questions, ask the user if they want to focus on blocking issues only.
+- **Very large design (many gotchas)**: The gotcha survey already deduplicates sibling nodes and filters to blocking/risk plus `missing-info` from info-collection rules (#406). If there are still many questions, ask the user if they want to focus on blocking issues only.
 - **External library components**: Applies only when the orchestrator has set `allowDefinitionWrite: true`. Experiment 10's observed case is `getMainComponentAsync()` resolving with `mainComponent.remote === true` — writes then throw *"Cannot write to internal and read-only node"*. The `mainComponent === null` case is documented in the Plugin API but was not reproduced live in Experiment 10; Experiment 11 (#309) unit-test-covers the helper's routing for that branch (override-error + no `sourceChildId` → annotate with `could not apply automatically:` markdown — see ADR-011 Verification), so the code path is regression-locked while live Figma reproduction remains a manual fixture-seeding follow-up. Under the default (`allowDefinitionWrite: false`), the definition write never fires and this throw cannot surface. **The pre-flight `probeDefinitionWritability` (#357) detects both branches up-front** so the Definition write picker can drop the opt-in option entirely when every candidate is unwritable, saving the user a wasted decision before the runtime fallback kicks in.

package/skills/canicode-roundtrip/helpers.js

@@ -96,7 +96,7 @@ ${footer}`;
       if (ctx.categories) {
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
-          markdown: `Apply this fix on the source component **${componentName}** to share across all instances. This instance kept its current value to avoid unintended fan-out. Re-run with \`allowDefinitionWrite: true\` to propagate.`,
+          markdown: `The fix below could not be applied on this instance child \u2014 the property silently ignored the write or the override was rejected. Apply it on the source component **${componentName}** so every instance picks it up. Re-run with \`allowDefinitionWrite: true\` to let canicode propagate automatically.`,
           categoryId: ctx.categories.fallback
         });
       }

package/skills/cursor/canicode/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: canicode
+description: Analyze Figma designs for development-friendliness and AI-friendliness scores
+---
+
+# CanICode -- Figma Design Analysis
+
+Analyze Figma design files to score how development-friendly and AI-friendly they are. Produces actionable reports with specific issues and fix suggestions.
+
+## Prerequisites
+
+This skill works with either channel — the CLI or the canicode MCP server. Both return the same analysis; pick whichever is already set up. Requires either:
+- A **saved fixture** (from `canicode calibrate-save-fixture`)
+- A **FIGMA_TOKEN** for live Figma URLs
+
+## How to Analyze
+
+### From a Figma URL
+
+```bash
+npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234" --token YOUR_TOKEN
+```
+
+Or if FIGMA_TOKEN is set in environment:
+```bash
+npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+```
+
+### From a saved fixture
+
+```bash
+npx canicode analyze fixtures/my-design
+```
+
+### Save a fixture for offline analysis
+
+```bash
+npx canicode calibrate-save-fixture "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234" --output fixtures/my-design
+```
+
+## Analysis Options
+
+### Presets
+- `--preset relaxed` — Downgrades blocking to risk, reduces scores by 50%
+- `--preset dev-friendly` — Enables only pixel-critical and responsive-critical rules, disables the rest
+- `--preset ai-ready` — Sets pixel-critical and token-management rule scores to 150% of defaults
+- `--preset strict` — Increases all scores by 150%
+
+### Config overrides
+```bash
+npx canicode analyze <input> --config ./my-config.json
+```
+
+### JSON output
+```bash
+npx canicode analyze <input> --json
+```
+
+### Via MCP (when `canicode-mcp` is installed)
+
+If the user has the canicode MCP server installed, prefer the MCP tool — it avoids the `npx` spawn overhead and reuses a warm Figma client:
+
+```
+analyze({ input: "<figma-url-or-fixture-path>" })
+```
+
+Options mirror the CLI: `preset`, `token`, `config`, `targetNodeId`, `json`. The `json` response field matches `npx canicode analyze --json` byte-for-byte, so downstream code can parse either source.
+
+## What It Reports
+
+16 rules across 6 categories: Pixel Critical, Responsive Critical, Code Quality, Token Management, Interaction, Semantic.
+
+Each issue includes:
+- Rule ID and severity (blocking / risk / missing-info / suggestion)
+- Affected node with Figma deep link
+- Why it matters, impact, and how to fix

package/skills/cursor/canicode-gotchas/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: canicode-gotchas
+description: Gotcha survey (Claude Code or Cursor) — Q&A workflow; answers accumulate in .claude/skills/canicode-gotchas/SKILL.md for figma-implement-design
+---
+
+# CanICode Gotchas — Design Gotcha Survey
+
+Run a gotcha survey on a Figma design to collect implementation context that Figma cannot encode natively, capture developer/designer answers, and upsert them into **`.claude/skills/canicode-gotchas/SKILL.md`** so downstream `figma-implement-design` runs have annotation-ready context. In this model, rules do rule-based best-practice detection, and gotcha is the annotation output from that detection. Some gotchas come from violation rules (what is wrong and how to resolve it); others come from info-collection rules (neutral context Figma cannot represent, like interaction intent/state).
+
+**Install location:** The workflow prose may live under `.claude/skills/canicode-gotchas/SKILL.md` (default `canicode init`) or be copied to `.cursor/skills/canicode-gotchas/SKILL.md` (`canicode init --cursor-skills`). The **authoritative gotcha store** is always **`.claude/skills/canicode-gotchas/SKILL.md`** — the CLI `upsert-gotcha-section` writes there only. In the `.claude` copy, this file has two regions: the **Workflow** below (installed by `canicode init`, never overwritten manually) and the **Collected Gotchas** region at the bottom (one numbered section per design, replaced in place on re-runs).
+
+## Prerequisites
+
+- **canicode MCP** (recommended): Register the server with your host — **Claude Code:** `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; the short-form `-y -p` collides with `claude mcp add`'s parser (#366); do **not** pass `-e FIGMA_TOKEN=…` here (#364). **Cursor / other hosts:** add `canicode-mcp` to your MCP config — see [Customization guide](https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode) (`~/.cursor/mcp.json` or project `.cursor/mcp.json`). The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the environment.
+- **Without canicode MCP** (fallback): `npx canicode gotcha-survey "<input>" --json` — same JSON shape as the MCP tool.
+- **FIGMA_TOKEN** configured for live Figma URLs.
+- **Gotcha destination on disk:** `.claude/skills/canicode-gotchas/SKILL.md` must exist before upsert — run `npx canicode init --token …` (add `--cursor-skills` if you also want the workflow file under `.cursor/skills/`).
+
+## Workflow
+
+### Step 1: Run the gotcha survey
+
+If the `gotcha-survey` MCP tool is available, call it with the user's Figma URL:
+
+```
+gotcha-survey({ input: "<figma-url-or-fixture-path>" })
+```
+
+**Without canicode MCP** — shell out to the CLI. The `--json` output parses identically:
+
+```bash
+npx canicode gotcha-survey "<figma-url-or-fixture-path>" --json
+```
+
+Either channel returns:
+- `designGrade`: overall grade (S, A+, A, B+, B, C+, C, D, F)
+- `isReadyForCodeGen`: whether the design can be implemented without gotchas
+- `questions`: array of gotcha questions (may be empty)
+
+### Step 2: Check if survey is needed
+
+If `isReadyForCodeGen` is `true` or `questions` is empty:
+- Tell the user: "This design scored **{designGrade}** and is ready for code generation — no gotchas to resolve."
+- Do NOT write to `.claude/skills/canicode-gotchas/SKILL.md`.
+- Stop here.
+
+### Step 3: Present questions to the user
+
+The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so this skill never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and batchable-rule list all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
+
+For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
+
+- **Single-question batch (`batch.questions.length === 1`)** — render the standard prompt for `batch.questions[0]`:
+
+  ```
+  **[{severity}] {ruleId}** — node: {nodeName}
+
+  {question}
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+- **Batch of N ≥ 2 with `batch.batchable === true`** (#369) — render one shared prompt covering every member:
+
+  ```
+  **[{severity}] {ruleId}** — {batch.questions.length} instances:
+    - {nodeName₁}
+    - {nodeName₂}
+    - …
+
+  {sharedQuestionPrompt}
+
+  Reply with one answer to apply to all {batch.questions.length}, or **split** to answer each individually.
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+  Where `sharedQuestionPrompt` reuses the rule's `question` text with the per-node noun replaced by the rule's plural noun (e.g. "These layers all use FILL sizing without min/max constraints. What size boundaries should they share?" instead of repeating the singular phrasing N times).
+
+- **Any batch with `batch.batchable === false`** is always rendered as a single-question prompt — the helper guarantees `questions.length === 1` for those (identity-typed answers like `non-semantic-name`, structural-mod rules).
+
+Wait for the user's answer before moving to the next batch. The user may:
+- Answer the question / batch directly
+- Say **split** (batch only) to fall back to per-question prompting for that batch
+- Say **skip** to skip the question / the entire batch
+- Say **n/a** if the question / the entire batch is not applicable
+
+When applying the batched answer, expand back to per-question records in Step 4 — the gotcha section format stores one record per `nodeId`.
+
+> The `groupedQuestions.groups[].instanceContext` field exists for the `canicode-roundtrip` SKILL's "Instance note" hoist (#370). This skill ignores it — every record gets its own `Instance context` bullet in Step 4 anyway.
+
+### Step 4: Upsert the gotcha section
+
+After collecting all answers, **upsert** this design's section into the `# Collected Gotchas` region at the bottom of:
+
+```
+.claude/skills/canicode-gotchas/SKILL.md
+```
+
+That path is in the **user's project** (current working directory), NOT in the canicode repo. If you are following this workflow from a copy under `.cursor/skills/`, still upsert into **`.claude/skills/...`** only — never write gotcha answers into the `.cursor` copy. The Workflow region in the `.claude` file **must never be modified manually** — only the `# Collected Gotchas` region is touched (via the CLI below).
+
+#### Step 4a: Use the `designKey` from the survey response
+
+`designKey` uniquely identifies the design so re-running on the same URL replaces the existing section in place. The survey response carries it on `survey.designKey` — read it directly. Do **not** parse the input URL in prose.
+
+The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every shape with vitest coverage so this workflow stays ADR-016-compliant:
+
+- **Figma URL** → `<fileKey>#<nodeId>` with `-` → `:` normalization on the nodeId. Example: `https://figma.com/design/abc123XYZ/My-File?node-id=42-100&t=ref` → `designKey = "abc123XYZ#42:100"`. Trailing query parameters (`?t=...`, `?mode=...`) are dropped.
+- **Figma URL without `node-id`** → just `<fileKey>` (file-level key).
+- **Fixture path / JSON file** → absolute path.
+
+#### Step 4b: Upsert via the canicode CLI
+
+File-state detection (4-way: missing / valid / missing-heading / clobbered) and section walking (find existing `## #NNN — ...` by `Design key` substring, otherwise compute the next monotonic zero-padded NNN) are deterministic markdown operations and live in `core/gotcha/upsert-gotcha-section.ts` with vitest coverage — do not re-implement them in prose (per ADR-016).
+
+Render the per-design section markdown using the **Output Template** below with the literal string `{{SECTION_NUMBER}}` in the header (the CLI substitutes the right NNN for you — preserves it on replace, computes the next monotonic value on append). Then invoke:
+
+```bash
+npx canicode upsert-gotcha-section \
+  --file .claude/skills/canicode-gotchas/SKILL.md \
+  --design-key "<designKey from Step 4a>" \
+  --section -   # then pipe the rendered section markdown through stdin
+```
+
+The CLI prints a JSON result `{ state, action, sectionNumber, wrote, userMessage }`:
+
+- `wrote: true` → success. `action` is `"replace"` (preserved `sectionNumber`) or `"append"` (next monotonic `sectionNumber`).
+- `wrote: false` with `state: "missing"` → tell the user: *"Your gotchas SKILL.md is not installed yet. Run `canicode init` first, then re-invoke this skill."* Stop here.
+- `wrote: false` with `state: "clobbered"` → tell the user: *"Your gotchas SKILL.md is missing the canicode YAML frontmatter (pre-#340 single-design clobber). Run `canicode init --force` to restore the workflow, then re-run this survey — your answers will land in a clean numbered section."* Stop here.
+- `wrote: true` with `state: "missing-heading"` → silent recovery. The CLI injected the `# Collected Gotchas` heading and appended the section; the workflow region above is untouched.
+
+The Workflow region above must never be touched. Do NOT copy Workflow prose into the per-design section; the section only carries metadata + gotcha answers.
+
+## Output Template
+
+Each per-design section in the `# Collected Gotchas` region has this exact shape:
+
+````markdown
+## #NNN — {designName} — {YYYY-MM-DD}
+
+- **Figma URL**: {figmaUrl}
+- **Design key**: {designKey}
+- **Grade**: {designGrade}
+- **Analyzed at**: {analyzedAt}
+
+### Gotchas
+
+#### {ruleId} — {nodeName}
+
+- **Severity**: {severity}
+- **Node ID**: {nodeId}
+- **Instance context** (omit this bullet if `instanceContext` was not in the survey question): parent instance `parentInstanceNodeId`, source node `sourceNodeId`, component `sourceComponentName` / `sourceComponentId` when present — roundtrip apply uses this to write on the source definition when instance overrides fail.
+- **Question**: {question}
+- **Answer**: {userAnswer}
+
+(repeat for each question)
+````
+
+### Field mapping
+
+| Field | Source |
+|-------|--------|
+| `NNN` | `sectionNumber` — zero-padded three-digit index. Preserved on re-run, incremented on append. |
+| `designName` | Figma file name or fixture name from the input |
+| `YYYY-MM-DD` | Today's date (the day you are running the survey) |
+| `figmaUrl` | The input URL or fixture path provided by the user |
+| `designKey` | `survey.designKey` from the gotcha-survey response (see Step 4a) |
+| `designGrade` | `designGrade` from gotcha-survey response |
+| `analyzedAt` | Current timestamp (ISO 8601) |
+| `ruleId` | `ruleId` from each question |
+| `nodeName` | `nodeName` from each question |
+| `severity` | `severity` from each question (blocking / risk / missing-info — the last surfaces only for info-collection rules per #406) |
+| `nodeId` | `nodeId` from each question |
+| `instanceContext` | When present on the question, copy `parentInstanceNodeId`, `sourceNodeId`, `sourceComponentId`, `sourceComponentName` into the bullet above (roundtrip / Plugin apply) |
+| `question` | `question` from each question |
+| `userAnswer` | The answer collected from the user in Step 3 |
+
+### Skipped questions
+
+If the user skipped a question or said "n/a", still include it in the section with:
+
+```markdown
+- **Answer**: _(skipped)_
+```
+
+This ensures the code generation agent knows the gotcha exists even if no answer was provided.
+
+## Edge Cases
+
+- **No questions returned**: The design is ready for code generation. Inform the user and stop (Step 2). Do not touch `.claude/skills/canicode-gotchas/SKILL.md`.
+- **Re-run on the same design**: Replace that design's section in place (matched by `Design key`) — preserve the original `#NNN` number. Do NOT append a duplicate.
+- **Re-run on a different design**: Append a new section with the next `#NNN`. Prior designs' sections are untouched.
+- **Workflow region**: Never modified. If you notice the Workflow region has been edited by the user, leave their edits alone — only the `# Collected Gotchas` region is under skill control.
+- **Pre-#340 clobbered file** (the YAML frontmatter was rewritten to a per-design variant, so the canonical `canicode-gotchas` frontmatter is missing): tell the user to run `canicode init --force` to restore the workflow, then re-run the survey. The prior single-design content cannot be automatically migrated into a `## #001` section — the user re-runs and gets a clean section.
+- **MCP tool not available**: Fall back to `npx canicode gotcha-survey <input> --json` — the CLI returns the same `GotchaSurvey` shape. If the CLI is also unavailable (e.g. no node runtime), tell the user to install the canicode MCP server or the `canicode` npm package (see Prerequisites).
+- **Partial answers**: If the user stops mid-survey, upsert the section with answers collected so far. Mark remaining questions as _(skipped)_.
+- **Manual section deletion**: If the user deletes a middle section by hand, do not renumber existing sections. The next new section still gets `(highest existing number) + 1`; numeric gaps are acceptable (same pattern as `.claude/docs/ADR.md`).