canicode 0.11.0 → 0.11.1

package/README.md

@@ -26,6 +26,8 @@
 
 AI can turn Figma designs into code — but the quality depends heavily on **how the design is structured**. CanICode runs a **roundtrip** over your Figma file: analyze the design, surface the gotchas it can't answer on its own, apply fixes back to Figma, re-analyze until the design is clean, then hand off to Figma's `figma-implement-design` skill for code generation. canicode does the design augmentation; code generation lives downstream (see [ADR-013](.claude/docs/ADR.md) for the scope boundary).
 
+![Role diagram: gotchas (memo) vs roundtrip (canvas) vs code-gen](docs/images/roles.svg)
+
 ### How the analyzer knows what to fix
 
 - **16 rules** across 6 categories: Pixel Critical, Responsive Critical, Code Quality, Token Management, Interaction, Semantic
@@ -38,25 +40,30 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
 
 ## The Roundtrip Workflow
 
-1. **Analyze** — run the 16 rules against the Figma design and grade it.
+**Skills:** **`canicode-gotchas`** = survey answers saved **locally** in SKILL.md only (memo). **`canicode-roundtrip`** = same analysis path plus **writes to Figma** (annotations / properties). Pick gotchas for capture-only; pick roundtrip when the design file should change.
+
+1. **Analyze** — run the 16 rules against the Figma design (report includes grade).
 2. **Surface gotchas** — the analyzer emits questions for design information it can't infer (missing states, unclear variants, responsive intent).
 3. **Apply fixes to Figma** — the `/canicode-roundtrip` skill writes answers back via `use_figma`. Each write shows up in the summary with one of three outcome markers:
    - ✅ **scene write succeeded** — the property was written directly to the scene node or instance override.
    - 📝 **annotated the scene node** — the skill left a structured annotation instead of writing the property. This is the [ADR-012](.claude/docs/ADR.md) default for instance-child layout writes, because propagating a property to the component definition (and therefore every instance of it) is almost never what the user wants. **A summary full of 📝 markers is correct behavior, not failure.**
    - 🌐 **definition write propagated** — the property was written to the component definition and every instance inherited it. Only happens when the user opted in up front with `allowDefinitionWrite`.
-4. **Re-analyze** — verify the gotchas were addressed (grade movement is a side-effect). Repeat step 2 if new gotchas surface.
+4. **Re-analyze** — verify gotchas were captured (annotations / acks); repeat step 2 if new gotchas surface.
 5. **Hand off** to `figma-implement-design` — canicode's scope ends here ([ADR-013](.claude/docs/ADR.md)). Figma's official code-generation skill takes the now-clean design and produces code.
 
 ---
 
 ## Getting Started
 
+> **Token safety:** Do **not** paste your Figma token into Claude, Cursor, or other agent chats — session logs can retain it. Use `FIGMA_TOKEN=figd_… npx canicode init`, or run `npx canicode init` and enter the token **only** at the CLI prompt.
+
 **Quickest way:** **[Open the web app](https://let-sunny.github.io/canicode/)** — paste a Figma URL, get a report.
 
 **Design-to-code in Claude Code (recommended):**
 
 ```bash
 # 1. Save your Figma token AND install the /canicode-roundtrip skill
+#    (never paste the token into chat — env var or CLI prompt only)
 npx canicode init --token figd_xxxxxxxxxxxxx
 
 # 2. Run the roundtrip on a Figma URL
@@ -67,8 +74,8 @@ npx canicode init --token figd_xxxxxxxxxxxxx
 
 **CanICode in Cursor (no Claude Code required):**
 
-1. Add **canicode** and **Figma** MCPs — [Cursor MCP](docs/CUSTOMIZATION.md#cursor-mcp-canicode) for `npx` → `canicode-mcp`; Figma MCP is required for **`use_figma`** if you run **roundtrip** (design writes), not for analyze-only.
-2. `npx canicode init --token figd_xxxxxxxxxxxxx --cursor-skills` — installs the same three skills as Claude under `.cursor/skills/` (`canicode`, `canicode-gotchas`, `canicode-roundtrip` + `helpers.js`) plus the shared `.claude/skills/canicode-gotchas/SKILL.md` answer file when needed.
+1. Add **canicode** and **Figma** MCPs — [Cursor MCP](docs/CUSTOMIZATION.md#cursor-mcp-canicode) for `npx` → `canicode-mcp` (use **`.cursor/mcp.json`** or **`~/.cursor/mcp.json`** in Cursor, not repo-root `.mcp.json`; [why](docs/CUSTOMIZATION.md#which-mcp-file-affects-which-host)); Figma MCP is required for **`use_figma`** if you run **roundtrip** (design writes), not for analyze-only.
+2. `npx canicode init --token figd_xxxxxxxxxxxxx --cursor-skills` (use `FIGMA_TOKEN=…` or the CLI prompt — not chat) — installs the same three skills as Claude under `.cursor/skills/` (`canicode`, `canicode-gotchas`, `canicode-roundtrip` + `helpers.js`) plus the shared `.claude/skills/canicode-gotchas/SKILL.md` answer file when needed.
 3. In Agent chat, @-mention **canicode-gotchas** (survey) or **canicode-roundtrip** (full roundtrip) and pass a Figma URL — same tool names and JSON as Claude Code (`gotcha-survey`, `analyze`, etc.).
 
 **If you only want analysis (no writes back to Figma):**
@@ -81,6 +88,8 @@ npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
 claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
+Restart Claude Code or reload MCP (Cursor) so canicode tools (`analyze`, `gotcha-survey`, …) load — same cold-session requirement as the Figma MCP (#433).
+
 <details>
 <summary><strong>All channels</strong></summary>
 
@@ -131,6 +140,7 @@ Each row below is a **complete** install. Don't run more than one — they cover
 <summary><strong>Claude Code Skills</strong> — install details</summary>
 
 ```bash
+# Token: env or CLI prompt only — do not paste into agent chat
 npx canicode init --token figd_xxxxxxxxxxxxx
 ```
 
@@ -153,6 +163,8 @@ Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips
 claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
+Restart Claude Code or reload MCP (Cursor) so canicode MCP tools appear in a fresh session (#433).
+
 Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
 
 canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls. The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` (set via `canicode init --token …`) or from the host's environment, so passing `-e FIGMA_TOKEN=…` to `claude mcp add` is **not** required and the current parser rejects it anyway (#364).