canicode 0.11.0 → 0.11.2

package/docs/CUSTOMIZATION.md

@@ -180,6 +180,22 @@ Override score, severity, or enable/disable individual rules:
 
 Configure the canicode MCP server so Cursor exposes `analyze`, `gotcha-survey`, and other tools.
 
+### Which MCP file affects which host?
+
+Two different JSON locations are easy to confuse because both can live in a git repo and both use an `mcpServers` object. (See GitHub #436.)
+
+| Path | Read by | Purpose |
+| --- | --- | --- |
+| **`.mcp.json`** at the **repository root** | **Claude Code** — `claude mcp add …` (project or user scope) persists entries here. | Shared with teammates when committed; this is the file skills and onboarding mean when they say “check `.mcp.json`” in a **Claude Code** context. |
+| **`.cursor/mcp.json`** | **Cursor** — project-scoped MCP list ([Cursor MCP docs — configuration locations](https://cursor.com/docs/context/mcp)). | Team-shared MCP for Cursor Agent in that workspace. |
+| **`~/.cursor/mcp.json`** | **Cursor** — global MCP list (same doc). | Personal MCP available across all projects; merged with project config (project wins if the same server name appears twice). |
+
+**Cursor does not use the repo-root `.mcp.json` for MCP.** If you only edit `.mcp.json` because you copied a Claude Code snippet, Cursor will not load those servers until you add the same `mcpServers` entries under **`.cursor/mcp.json`** or **`~/.cursor/mcp.json`**, then reload MCP or restart Cursor.
+
+**Claude Code does not read `.cursor/mcp.json`.** Register servers with `claude mcp add …` (or maintain the root `.mcp.json` format Claude Code expects for your install).
+
+**Canicode CLI (`canicode init`):** When suggesting Figma MCP setup for Cursor-heavy flows, the init command treats **either** repo-root `.mcp.json` **or** `.cursor/mcp.json` as evidence that Figma MCP is configured — so mixed-host repos still get accurate “already configured” detection. That does **not** mean Cursor loads `.mcp.json`; it only avoids false negatives when both files exist.
+
 ### Project config (`.cursor/mcp.json`)
 
 Create or merge into `.cursor/mcp.json` in your repository root:
@@ -197,20 +213,63 @@ Create or merge into `.cursor/mcp.json` in your repository root:
 
 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.
 
+### Figma MCP server id and tool names in Cursor (#437)
+
+Cursor may show an MCP **server id** in the UI that is **not** literally the key you typed in `mcpServers` (for example a workspace or project prefix). Skills and docs often say “the `figma` MCP” or “call `use_figma`” as shorthand — **your session’s truth is the live tool list** after MCP reload (Cursor: MCP / Tools panel), not the string `figma` or `use_figma` read from a config file alone.
+
+- If roundtrip fails with “cannot find `use_figma`” but Figma MCP shows as connected, open the tool list and note the **exact** tool identifier Cursor exposes (it may be namespaced).
+- Keep the Figma MCP entry in `.cursor/mcp.json` (or `~/.cursor/mcp.json`) per [Figma’s MCP docs](https://developers.figma.com/docs/figma-mcp-server/) — then rely on the host-reported tool name when wiring skills or debugging.
+
+### Post-install checklist (MCP + skills + Figma) (#461)
+
+After editing MCP JSON or running `canicode init`:
+
+1. **Restart the host** (Cursor or Claude Code) or use the product’s **reload MCP** action — on-disk config is not live until the next session.
+2. **Confirm the live tool list** (Cursor: Settings → MCP; Claude: tool picker) — the JSON file is not proof; the model can only call tools the host exposes.
+3. **Figma** — for MCP-driven canvas access, complete any **Connect / file access** steps your Figma account requires so `use_figma` can run against the target file.
+4. **Community / read-only files** — roundtrip Step 4 writes to the file. If the design is read-only, duplicate it into a workspace you own before running `/canicode-roundtrip` or `@canicode-roundtrip`.
+
 ### 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.
+2. Install skills: **`canicode init --token … --cursor-skills`** saves the Figma token and installs everything; or **`canicode init --cursor-skills`** without `--token` installs Claude skills plus Cursor copies — you still need **`canicode init --token …`** (or `FIGMA_TOKEN`) before REST **`analyze`** / **`gotcha-survey`** against a live URL. The shared gotchas answer file lives under `.claude/skills/canicode-gotchas/` when the gotchas skill is installed. 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** when your Cursor setup uses Agent-attached skills. Some teams prefer **slash commands** or rules instead of `@` — use whichever your workspace enables; roundtrip still needs **`use_figma`** from the Figma MCP in that session.
 
 ### 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`.
+- [ ] After the Q&A loop, `npx canicode upsert-gotcha-section --file … --design-key … --input=-` (JSON payload on stdin per `canicode-gotchas` Step 4b) 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`.
 
+### Troubleshooting: MCP not available or roundtrip Step 4 fails
+
+Work through these checks in order before concluding that an MCP server is broken.
+
+1. **Cursor host — ensure the server is enabled and the tools appear in the live session.**
+   MCP servers are not always active immediately after install. Open **Settings → MCP** and verify the server shows a connected status. If the entry is present but the tools are missing from the active tool list, use the reload MCP action (or restart Cursor). The live tool list — not the on-disk JSON — is what the model can actually call.
+
+2. **Two separate servers — identify which step failed before attributing blame.**
+   canicode (provides `analyze` and `gotcha-survey`) and Figma (provides `use_figma`) are independent MCP servers. Step 1 (analyze) and Step 3 (gotcha-survey) use the canicode server. Step 4 (canvas write) uses the Figma server. A failure in Step 4 is a Figma MCP issue, not a canicode issue — and vice versa. Check which server exposes the missing tool before editing config.
+
+3. **Step 4 (canvas write) — `helpers.js` must be prepended to every `use_figma` `code` string.**
+   `CanICodeRoundtrip` is not a Figma built-in. It is the global registered by the bundled IIFE in `helpers.js` (at `.claude/skills/canicode-roundtrip/helpers.js` for Claude Code, or `.cursor/skills/canicode-roundtrip/helpers.js` after `canicode init --cursor-skills`). If the bundle is missing from the string, the first Plugin API call throws `ReferenceError: CanICodeRoundtrip is not defined`. This is **not** the same as "canicode MCP is missing" — the canicode server may be healthy; only the Step 4 `use_figma` script is incomplete. Smoke-check with:
+   ```javascript
+   // <contents of helpers.js prepended here>
+   return { ok: typeof CanICodeRoundtrip !== 'undefined' };
+   ```
+   See the Step 4 preflight block in [`docs/roundtrip-protocol.md`](https://github.com/let-sunny/canicode/blob/main/docs/roundtrip-protocol.md) and the corresponding preflight check in the `canicode-roundtrip` SKILL.md for the full prepend procedure.
+
+4. **Size / delivery — measure the code string before assuming a server bug.**
+   If the `use_figma` call silently fails, truncates, or the host reports the tool payload is too large, the `helpers.js` bundle combined with the apply script may exceed the host's per-message or per-tool-call limit. Measure with `Buffer.byteLength(code, "utf8")` (Node) or `wc -c` (shell). If the string is too large for the chat/tool input, write it to a file and paste it into the MCP `use_figma` UI directly instead of relying on the model to pass the full string inline. See also the delivery notes in [#462](https://github.com/let-sunny/canicode/issues/462) and [`docs/roundtrip-protocol.md`](https://github.com/let-sunny/canicode/blob/main/docs/roundtrip-protocol.md).
+
+5. **Common symptom → likely cause mapping:**
+   - `ReferenceError: CanICodeRoundtrip is not defined` → `helpers.js` was not prepended (check 3 above).
+   - Truncated response or no server round-trip returned → delivery size issue (check 4 above).
+   - Permission error or "cannot edit" → Figma file seat or edit access; a Viewer seat cannot write via Plugin API.
+   - Tools missing from live tool list despite on-disk config → MCP server not enabled or not restarted (check 1 above).
+
 ---
 
 ## Telemetry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canicode",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "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",
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "tsup --config tsup.config.ts && pnpm build:roundtrip && pnpm bundle:skills",
     "build:web": "bash scripts/build-web.sh",
-    "build:roundtrip": "tsup --config tsup.roundtrip.config.ts",
+    "build:roundtrip": "tsup --config tsup.roundtrip.config.ts && tsx scripts/bundle-roundtrip-cache.ts",
     "bundle:skills": "bash scripts/bundle-skills.sh",
     "dev": "tsup --watch",
     "test": "vitest",

package/skills/canicode/SKILL.md

@@ -13,6 +13,12 @@ This skill works with either channel — the CLI or the canicode MCP server. Bot
 - 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

package/skills/canicode-gotchas/SKILL.md

@@ -5,6 +5,8 @@ description: Gotcha survey (Claude Code or Cursor) — Q&A workflow; answers acc
 
 # 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).
@@ -18,6 +20,12 @@ Run a gotcha survey on a Figma design to collect implementation context that Fig
 
 ## 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:
@@ -44,13 +52,40 @@ If `isReadyForCodeGen` is `true` or `questions` is empty:
 - Do NOT write to `.claude/skills/canicode-gotchas/SKILL.md`.
 - Stop here.
 
+### Step 3 — preamble: match the user's language
+
+Before rendering any question, detect the user's conversation language from their recent messages in **this** session. Korean vs. English vs. other is usually unambiguous; when ambiguous, default to English and ask the user once which language they prefer.
+
+When the user's language is non-English, localize only the **human-readable** strings rendered in the prompt templates below: the `question` text, the `why` line (if shown), the `Hint:` body, the `Example:` body, and the batch shared-prompt wording — including the "Reply with one answer to apply to all …, or **split** to answer each individually" sentence and the `skip` / `n/a` affordance sentence that follows it. Translate at render time only; the rule templates in `core/rules/*` stay English-only per CLAUDE.md and the issue's "Out of scope" list — do not rewrite source.
+
+Keep the following English even when localizing, because they are identifiers or structural markers that downstream tools grep for: `ruleId`, `nodeId`, `nodeName`, the severity label in brackets (`[blocking]`, `[risk]`, `[missing-info]`, `[suggestion]`), and the entire markdown scaffolding of the Step 4 upsert section (`## #NNN — …` headings, `Design key`, `#### Skipped (N)`, the per-record field labels). `renderGotchaSection` is the source of truth for that on-disk markdown (ADR-016) and its output stays English.
+
+In Step 4, pass the user's answer through **verbatim** into the `answers[<nodeId>].answer` field — do **not** back-translate answers to English. `figma-implement-design` is cross-language by design (see #461), and a round-trip to English introduces translation loss and defeats the "shared language for designer/PM" framing.
+
 ### 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:
+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 both batchable-rule lists (`BATCHABLE_RULE_IDS` for `safe` mode, `OPT_IN_BATCHABLE_RULE_IDS` for `opt-in` mode) all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
+
+**Before presenting the first batch**, display this shortcut notice once so the user knows they can exit early at any point:
+
+```
+Survey: {totalBatchCount} question(s) to answer.
+Tip: reply `skip remaining` at any point to bypass the rest with a default no-op annotation and finish immediately.
+```
+
+Where `totalBatchCount` is `groupedQuestions.groups.flatMap((g) => g.batches).length`.
+
+**After every 3rd batch** (i.e. after batches 3, 6, 9, …), re-surface the shortcut as a brief reminder before presenting the next batch:
 
-For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
+```
+(You can still reply `skip remaining` to bypass the remaining questions.)
+```
 
-- **Single-question batch (`batch.questions.length === 1`)** — render the standard prompt for `batch.questions[0]`:
+When the user replies `skip remaining` at any point during Step 3, immediately treat all unanswered batches as skipped (`{ "skipped": true }` for each unanswered `nodeId`) and proceed directly to Step 4 without asking further questions.
+
+For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`, branch on `batch.batchMode`:
+
+- **`batch.batchMode === "none"`** — single-question batch; the helper guarantees `batch.questions.length === 1`. Render the standard prompt for `batch.questions[0]`:
 
   ```
   **[{severity}] {ruleId}** — node: {nodeName}
@@ -61,7 +96,7 @@ For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
   > Example: {example}
   ```
 
-- **Batch of N ≥ 2 with `batch.batchable === true`** (#369) — render one shared prompt covering every member:
+- **`batch.batchMode === "safe"` with `batch.questions.length >= 2`** (#369) — rule in `BATCHABLE_RULE_IDS`; one answer is uniformly applicable. Render one shared prompt:
 
   ```
   **[{severity}] {ruleId}** — {batch.questions.length} instances:
@@ -79,13 +114,32 @@ For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
 
   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).
+- **`batch.batchMode === "opt-in"` with `batch.questions.length >= 2`** (#426) — rule in `OPT_IN_BATCHABLE_RULE_IDS` (currently `missing-prototype`). The same answer is usually shareable across siblings but may legitimately differ per node — signal that explicitly so the user can opt out of the shared answer with `split`:
+
+  ```
+  **[{severity}] {batch.ruleId}** — {batch.questions.length} instances of the same rule:
+    - {nodeName₁}
+    - {nodeName₂}
+    - …
+
+  {sharedQuestionPrompt}
+
+  Apply this answer to all {batch.questions.length} occurrences of `{batch.ruleId}`, or reply **split** to answer each individually.
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+  Unlike `safe` batches, the prompt frames the answer as a suggested default, not a uniform truth — reuse the rule's existing `example` (e.g. `missing-prototype`'s "navigates to `/product/{id}` detail page") so the user knows the answer can be a pattern, not a literal string shared character-for-character.
+
+- **Single-member `safe` or `opt-in` batch (`batch.questions.length === 1`)** — render the single-question template above; the shared-prompt framing collapses to the rule's own wording when there is only one node.
 
 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
+- Answer the question / batch directly (single value or pattern covers all batch members)
+- Say **split** (batch only) to fall back to per-question prompting for that batch — works the same for both `safe` and `opt-in` batches
 - Say **skip** to skip the question / the entire batch
 - Say **n/a** if the question / the entire batch is not applicable
+- Say **skip remaining** to immediately skip all remaining unanswered batches and proceed to Step 4
 
 When applying the batched answer, expand back to per-question records in Step 4 — the gotcha section format stores one record per `nodeId`.
 
@@ -115,77 +169,48 @@ The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every sha
 
 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:
+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>" \
-  --section -   # then pipe the rendered section markdown through stdin
+  --input=-
 ```
 
-The CLI prints a JSON result `{ state, action, sectionNumber, wrote, userMessage }`:
+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. 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.
+The Workflow region above must never be touched.
 
 ## Edge Cases
 
@@ -195,7 +220,7 @@ This ensures the code generation agent knows the gotcha exists even if no answer
 - **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)_.
+- **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`).
 
 # Collected Gotchas