canicode 0.10.5 → 0.11.1

package/skills/canicode-roundtrip/helpers.js

@@ -78,8 +78,189 @@ ${footer}`;
     }
   }
 
+  // src/core/roundtrip/annotation-payload.ts
+  var CANICODE_JSON_FENCE = "```canicode-json";
+  function formatIntentValueForDisplay(value) {
+    if (value === void 0) return "undefined";
+    if (value === null) return "null";
+    if (typeof value === "object") {
+      try {
+        return `\`${JSON.stringify(value)}\``;
+      } catch {
+        return String(value);
+      }
+    }
+    return `\`${String(value)}\``;
+  }
+  function buildCodegenDirective(args) {
+    const { sceneNodeId, intent } = args;
+    const val = intent.value === void 0 ? "undefined" : JSON.stringify(intent.value);
+    return `When generating code for node ${sceneNodeId}, set ${intent.field} to ${val} (user intent, scope: ${intent.scope}). Prefer this over the current Figma scene value when they disagree.`;
+  }
+  function sceneOutcomeToAck(result, reason) {
+    return reason !== void 0 ? { result, reason } : { result };
+  }
+  function buildOutcomeHumanLine(args) {
+    if (args.skippedDefinitionDueToAdr012) {
+      const adrHint = " Canicode skipped writing the source component without `allowDefinitionWrite: true` (ADR-012 safer default). The instance-level change did not apply as intended in the scene.";
+      if (args.reason === "silent-ignore") {
+        return "**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore)." + adrHint;
+      }
+      return "**Scene write outcome:** Figma rejected an instance-level change" + (args.errorMessage ? `: ${args.errorMessage}` : "") + "." + adrHint;
+    }
+    if (args.reason === "silent-ignore") {
+      return "**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore). No source definition was available to escalate.";
+    }
+    if (args.reason === "override-error") {
+      return "**Scene write outcome:** Figma rejected an instance-level change" + (args.errorMessage ? `: ${args.errorMessage}` : "") + ". No source definition was available to escalate.";
+    }
+    return "**Scene write outcome:** Could not apply automatically" + (args.errorMessage ? `: ${args.errorMessage}` : "") + ".";
+  }
+  function buildAdr012PropagationParagraph(args) {
+    const { componentName, replicaCount } = args;
+    const fanOutHint = typeof replicaCount === "number" && replicaCount >= 2 ? ` This batched question covers ${replicaCount} instance scenes \u2014 changing **${componentName}** at the definition still affects every inheriting instance, not just one row in the batch.` : "";
+    return `Canicode's safer default (ADR-012) is to skip writing the source component **${componentName}** without explicit opt-in, because that write propagates to every non-overridden instance of **${componentName}** in the file.${fanOutHint} Prefer a manual override on **this** instance when you only need a local fix. Use \`allowDefinitionWrite: true\` only when you intend to change **${componentName}** for all inheriting instances \u2014 it is not a neutral shortcut for a single-instance tweak.`;
+  }
+  function buildDefinitionWriteSkippedBody(args) {
+    const {
+      ruleId,
+      sceneNodeId,
+      componentName,
+      reason,
+      errorMessage,
+      replicaCount,
+      intent
+    } = args;
+    const ackIntent = intent ? {
+      field: intent.field,
+      value: intent.value,
+      scope: intent.scope
+    } : void 0;
+    const sceneWriteOutcome = sceneOutcomeToAck("user-declined-propagation", "adr-012-opt-in-disabled");
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...ackIntent ? { intent: ackIntent } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = buildOutcomeHumanLine({
+      reason,
+      ...errorMessage !== void 0 ? { errorMessage } : {},
+      skippedDefinitionDueToAdr012: true
+    });
+    const adrBlock = buildAdr012PropagationParagraph({
+      componentName,
+      ...replicaCount !== void 0 ? { replicaCount } : {}
+    });
+    const proseParts = [userAnswerLine, outcomeLine, adrBlock].filter(
+      (p) => p !== null
+    );
+    const prose = proseParts.join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function buildNoDefinitionFallbackBody(args) {
+    const { ruleId, sceneNodeId, reason, errorMessage, intent } = args;
+    const ackIntent = intent ? { field: intent.field, value: intent.value, scope: intent.scope } : void 0;
+    const outcomeResult = reason === "silent-ignore" ? "silent-ignored" : reason === "override-error" ? "api-rejected" : "api-rejected";
+    const sceneWriteOutcome = sceneOutcomeToAck(
+      outcomeResult,
+      reason === "silent-ignore" ? "silent-ignore-no-definition" : "no-definition-escalation"
+    );
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...ackIntent ? { intent: ackIntent } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = buildOutcomeHumanLine({
+      reason,
+      ...errorMessage !== void 0 ? { errorMessage } : {},
+      skippedDefinitionDueToAdr012: false
+    });
+    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function buildDefinitionTierFailureBody(args) {
+    const { ruleId, sceneNodeId, intent, kind, errorMessage } = args;
+    const sceneWriteOutcome = sceneOutcomeToAck(
+      kind === "read-only-library" ? "api-rejected" : "api-rejected",
+      kind === "read-only-library" ? "definition-read-only" : "definition-write-failed"
+    );
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...intent ? {
+        intent: {
+          field: intent.field,
+          value: intent.value,
+          scope: intent.scope
+        }
+      } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const human = kind === "read-only-library" ? "source component lives in an external library and is read-only from this file \u2014 apply the fix in the library file itself." : `could not apply at source definition: ${errorMessage}`;
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = `**Scene write outcome:** ${human}`;
+    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function appendJsonFenceAndFooter(prose, jsonBlock, ruleId) {
+    const footer = `\u2014 *${ruleId}*`;
+    const hasIntent = jsonBlock.intent !== void 0;
+    if (!hasIntent) {
+      return `${prose}
+
+${footer}`;
+    }
+    const jsonText = JSON.stringify(jsonBlock, null, 0);
+    return `${prose}
+
+${CANICODE_JSON_FENCE}
+${jsonText}
+\`\`\`
+
+${footer}`;
+  }
+  var FENCED_JSON_RE = new RegExp(
+    `${CANICODE_JSON_FENCE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*([\\s\\S]*?)\\s*\`\`\``,
+    "m"
+  );
+  function parseCanicodeJsonPayloadFromMarkdown(text) {
+    const m = FENCED_JSON_RE.exec(text);
+    if (!m?.[1]) return void 0;
+    try {
+      const raw = JSON.parse(m[1].trim());
+      if (!raw || typeof raw !== "object") return void 0;
+      const o = raw;
+      if (o.v !== 1 || typeof o.ruleId !== "string") return void 0;
+      return raw;
+    } catch {
+      return void 0;
+    }
+  }
+
   // src/core/roundtrip/apply-with-instance-fallback.ts
   var DEFINITION_WRITE_SKIPPED_EVENT = "cic_roundtrip_definition_write_skipped";
+  function categoryIdForAnnotate(categories, kind, roundtripIntent) {
+    if (kind === "adr012-definition-skipped") {
+      return categories.fallback;
+    }
+    if (roundtripIntent !== void 0) {
+      return categories.gotcha;
+    }
+    return categories.flag;
+  }
   function resolveSourceComponentName(definition, question) {
     if (definition && typeof definition.name === "string" && definition.name) {
       return definition.name;
@@ -93,11 +274,24 @@ ${footer}`;
   async function routeToDefinitionOrAnnotate(definition, writeFn, ctx) {
     if (definition && !ctx.allowDefinitionWrite && ctx.reason !== "non-override-error") {
       const componentName = resolveSourceComponentName(definition, ctx.question);
+      const replicaCount = typeof ctx.question.replicas === "number" && Number.isInteger(ctx.question.replicas) ? ctx.question.replicas : void 0;
       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.`,
-          categoryId: ctx.categories.fallback
+          markdown: buildDefinitionWriteSkippedBody({
+            ruleId: ctx.question.ruleId,
+            sceneNodeId: ctx.scene.id,
+            componentName,
+            reason: ctx.reason,
+            ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},
+            ...replicaCount !== void 0 ? { replicaCount } : {},
+            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}
+          }),
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "adr012-definition-skipped",
+            ctx.roundtripIntent
+          )
         });
       }
       ctx.telemetry?.(DEFINITION_WRITE_SKIPPED_EVENT, {
@@ -111,11 +305,21 @@ ${footer}`;
     }
     if (!definition) {
       if (ctx.categories) {
-        const markdown = ctx.reason === "silent-ignore" ? "write accepted but value unchanged; no definition available" : ctx.reason === "override-error" ? `could not apply automatically: ${ctx.errorMessage ?? ""}` : `could not apply automatically: ${ctx.errorMessage ?? ""}`;
+        const markdown = buildNoDefinitionFallbackBody({
+          ruleId: ctx.question.ruleId,
+          sceneNodeId: ctx.scene.id,
+          reason: ctx.reason,
+          ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},
+          ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}
+        });
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
           markdown,
-          categoryId: ctx.categories.fallback
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "other-failure",
+            ctx.roundtripIntent
+          )
         });
       }
       return ctx.reason === "silent-ignore" ? { icon: "\u{1F4DD}", label: "silent-ignore, annotated" } : { icon: "\u{1F4DD}", label: `error: ${ctx.errorMessage ?? ""}` };
@@ -132,8 +336,18 @@ ${footer}`;
       if (ctx.categories) {
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
-          markdown: isRemoteReadOnly ? "source component lives in an external library and is read-only from this file \u2014 apply the fix in the library file itself." : `could not apply at source definition: ${defMsg}`,
-          categoryId: ctx.categories.fallback
+          markdown: buildDefinitionTierFailureBody({
+            ruleId: ctx.question.ruleId,
+            sceneNodeId: ctx.scene.id,
+            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {},
+            kind: isRemoteReadOnly ? "read-only-library" : "definition-error",
+            errorMessage: defMsg
+          }),
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "other-failure",
+            ctx.roundtripIntent
+          )
         });
       }
       return {
@@ -143,7 +357,7 @@ ${footer}`;
     }
   }
   async function applyWithInstanceFallback(question, writeFn, context = {}) {
-    const { categories, allowDefinitionWrite = false, telemetry } = context;
+    const { categories, allowDefinitionWrite = false, telemetry, roundtripIntent } = context;
     const scene = await figma.getNodeByIdAsync(question.nodeId);
     if (!scene) return { icon: "\u{1F4DD}", label: "missing node" };
     const definition = question.sourceChildId ? await figma.getNodeByIdAsync(question.sourceChildId) : null;
@@ -156,7 +370,8 @@ ${footer}`;
           categories,
           reason: "silent-ignore",
           allowDefinitionWrite,
-          telemetry
+          telemetry,
+          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
         });
       }
       return { icon: "\u2705", label: "instance/scene" };
@@ -171,7 +386,8 @@ ${footer}`;
           reason: "non-override-error",
           errorMessage: msg,
           allowDefinitionWrite,
-          telemetry
+          telemetry,
+          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
         });
       }
       return routeToDefinitionOrAnnotate(definition, writeFn, {
@@ -181,7 +397,8 @@ ${footer}`;
         reason: "override-error",
         errorMessage: msg,
         allowDefinitionWrite,
-        telemetry
+        telemetry,
+        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
       });
     }
   }
@@ -220,6 +437,39 @@ ${footer}`;
     target.setBoundVariable(prop, variable);
     return true;
   }
+  function buildRoundtripIntentFromPropertyAnswer(question, answerValue) {
+    const raw = question.targetProperty;
+    if (raw === void 0) return void 0;
+    const props = Array.isArray(raw) ? raw : [raw];
+    if (props.length === 0) return void 0;
+    if (props.length === 1) {
+      const prop = props[0];
+      const perProp = answerValue && typeof answerValue === "object" && !("variable" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;
+      const parsed = parseValueForIntent(perProp);
+      if (parsed === void 0) return void 0;
+      return { field: prop, value: parsed, scope: "instance" };
+    }
+    const obj = answerValue && typeof answerValue === "object" && !("variable" in answerValue) && !Array.isArray(answerValue) ? answerValue : void 0;
+    const picked = {};
+    for (const p of props) {
+      if (obj && p in obj && obj[p] !== void 0) picked[p] = obj[p];
+    }
+    if (Object.keys(picked).length === 0) return void 0;
+    return {
+      field: props.join(", "),
+      value: picked,
+      scope: "instance"
+    };
+  }
+  function parseValueForIntent(raw) {
+    if (raw && typeof raw === "object" && "variable" in raw) {
+      return { variable: raw.variable };
+    }
+    if (raw && typeof raw === "object" && "fallback" in raw) {
+      return raw.fallback;
+    }
+    return raw;
+  }
   function applyPropertyScalar(target, prop, scalar) {
     const rec = target;
     const before = rec[prop];
@@ -228,6 +478,10 @@ ${footer}`;
     return true;
   }
   async function applyPropertyMod(question, answerValue, context = {}) {
+    const roundtripIntent = buildRoundtripIntentFromPropertyAnswer(
+      question,
+      answerValue
+    );
     const props = Array.isArray(question.targetProperty) ? question.targetProperty : question.targetProperty !== void 0 ? [question.targetProperty] : [];
     return applyWithInstanceFallback(
       question,
@@ -258,7 +512,10 @@ ${footer}`;
         }
         return changed;
       },
-      context
+      {
+        ...context,
+        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
+      }
     );
   }
 
@@ -334,7 +591,15 @@ ${footer}`;
       }
       const ruleId = extractRuleId(text);
       if (!ruleId) continue;
-      out.push({ nodeId: node.id, ruleId });
+      const payload = parseCanicodeJsonPayloadFromMarkdown(text);
+      const payloadAligned = payload && payload.ruleId === ruleId;
+      out.push({
+        nodeId: node.id,
+        ruleId,
+        ...payloadAligned && payload.intent ? { intent: payload.intent } : {},
+        ...payloadAligned && payload.sceneWriteOutcome ? { sceneWriteOutcome: payload.sceneWriteOutcome } : {},
+        ...payloadAligned && payload.codegenDirective ? { codegenDirective: payload.codegenDirective } : {}
+      });
     }
     return out;
   }
@@ -360,17 +625,22 @@ ${footer}`;
     walk(root, canicodeCategoryIds, out);
     return out;
   }
+  function safeChildren(node) {
+    try {
+      const c = node.children;
+      return Array.isArray(c) ? c : [];
+    } catch {
+      return [];
+    }
+  }
   function walk(node, canicodeCategoryIds, out) {
     try {
       const local = extractAcknowledgmentsFromNode(node, canicodeCategoryIds);
       for (const a of local) out.push(a);
     } catch {
     }
-    const children = node.children;
-    if (Array.isArray(children)) {
-      for (const child of children) {
-        if (child && typeof child === "object") walk(child, canicodeCategoryIds, out);
-      }
+    for (const child of safeChildren(node)) {
+      if (child && typeof child === "object") walk(child, canicodeCategoryIds, out);
     }
   }
 

package/skills/cursor/canicode/SKILL.md

@@ -0,0 +1,82 @@
+---
+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
+
+### Step 0: Verify canicode MCP tools are loaded (optional fast path)
+
+Before shelling out to `npx canicode analyze …`, check whether the **`analyze` MCP tool** is available in **this** session — not only whether `.mcp.json` lists `canicode`. New MCP registrations usually need a **restart or MCP reload** before tools appear.
+
+If you must use the CLI fallback, say so out loud: the user may have added `claude mcp add canicode …` but not restarted yet (#433). After restart/reload, `analyze` via MCP avoids the `npx` spawn. The fallback is valid — silence makes users think the MCP install failed.
+
+## 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,178 @@
+---
+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
+
+**Channel contrast:** **`canicode-gotchas`** (**this skill**) persists answers **only** in **local** `.claude/skills/canicode-gotchas/SKILL.md` — **memo-only**, no Plugin write to Figma. **`canicode-roundtrip`** writes to the **canvas**. Use gotchas when you want Q&A captured for code-gen context without mutating the file.
+
+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 0: Verify canicode MCP tools are loaded (optional fast path)
+
+Before Step 1, verify that `gotcha-survey` is callable in **this** session — not merely listed in `.mcp.json`. Newly registered MCP servers usually need a **host restart or MCP reload** before tools appear (same pattern as `/canicode-roundtrip` Step 0 for the Figma MCP).
+
+When you fall back to `npx canicode gotcha-survey … --json`, tell the user explicitly: the canicode MCP may not be loaded yet. They should register it (`claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, or the Cursor/`mcp.json` equivalent in the Customization guide) and **restart the IDE or reload MCP** — then the next session can use the MCP tool without spawning `npx`. The CLI fallback is correct behavior; silence makes users think registration failed (#433).
+
+### 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).
+
+Build **one JSON object** on stdin for `upsert-gotcha-section`. The CLI renders the section markdown from `survey` + `answers` via `renderGotchaSection` in TypeScript (#439) — severity, rule text, node ids, and instance context come **verbatim** from `gotcha-survey --json`; the skill must not paste LLM-authored section prose.
+
+Payload shape:
+
+```json
+{
+  "survey": {
+    "designKey": "<same as Step 4a>",
+    "designGrade": "<from gotcha-survey>",
+    "questions": "<full questions[] array from gotcha-survey — preserve order>"
+  },
+  "answers": {
+    "<nodeId>": { "answer": "…" }
+  },
+  "designName": "<Figma file name or fixture label>",
+  "figmaUrl": "<the user's input URL or path>",
+  "analyzedAt": "<ISO 8601 timestamp when you upsert>",
+  "today": "<YYYY-MM-DD local date for the section title>"
+}
+```
+
+For skipped / n/a: use `{ "skipped": true }` for that `nodeId`, or omit the key. Skipped questions do **not** get per-question rows; `renderGotchaSection` appends a compact **`#### Skipped (N)`** block listing each `ruleId` with a count (`ruleId` lines sorted lexically — see `src/core/gotcha/render-gotcha-section.ts`).
+
+Invoke (cac requires `--input=-`, not `--input -`, so the stdin sentinel survives parsing — #420):
+
+```bash
+npx canicode upsert-gotcha-section \
+  --file .claude/skills/canicode-gotchas/SKILL.md \
+  --design-key "<designKey from Step 4a>" \
+  --input=-
+```
+
+Pipe the JSON object on stdin. `--design-key` must equal `survey.designKey` (the CLI validates the match).
+
+The CLI prints JSON `{ state, action, sectionNumber, wrote, userMessage, designKey }`:
+
+- `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.
+
+## 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. Remaining questions count toward **`#### Skipped (N)`** (omit keys or `{ "skipped": true }`).
+- **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`).