canicode 0.10.5 → 0.11.1

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,65 @@ 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.
+
+### 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:
+
+```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.
+
+### 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.
+
+### 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 --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`.
+
+---
 
 ## Telemetry
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canicode",
-  "version": "0.10.5",
+  "version": "0.11.1",
   "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/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

@@ -1,20 +1,31 @@
 ---
 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).
+**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 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
 
+### 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:
@@ -38,12 +49,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 +101,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,89 +121,60 @@ 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).
+
+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`).
 
-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:
+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) |
-| `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
 
-- **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.
 - **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