canicode 0.10.2 → 0.10.4

package/README.md

@@ -44,7 +44,7 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
    - ✅ **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 grade improved. Repeat step 2 if new gotchas surface.
+4. **Re-analyze** — verify the gotchas were addressed (grade movement is a side-effect). 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.
 
 ---
@@ -72,7 +72,7 @@ npx canicode init --token figd_xxxxxxxxxxxxx
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 
 # MCP Server — works with Claude Code, Cursor, Claude Desktop
-claude mcp add canicode -- npx -y -p canicode canicode-mcp
+claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
 <details>
@@ -107,68 +107,73 @@ Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggest
 
 ---
 
-## Installation
+## Installation — pick one
+
+Each row below is a **complete** install. Don't run more than one — they cover overlapping use cases. (#367)
+
+| If you use… | Install |
+|-------------|---------|
+| **Claude Code** (recommended for the roundtrip workflow) | `npx canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND drops `/canicode`, `/canicode-gotchas`, `/canicode-roundtrip` skills into `./.claude/skills/`. The skills already know how to call canicode via `npx canicode …`, no MCP install needed. |
+| **Cursor / Claude Desktop / other MCP host** | `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — registers the MCP server. |
+| **Just the CLI** (CI, scripts) | Nothing. `npx canicode analyze "<figma-url>"` works directly. Run `canicode init --token …` once if you want the token persisted to `~/.canicode/config.json`. |
+
+> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+
+> **Roundtrip prerequisite:** the `/canicode-roundtrip` skill calls the Figma MCP server to read and write the design. Install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` and restart Claude Code so the new MCP tools load.
 
 <details>
-<summary><strong>CLI</strong></summary>
+<summary><strong>Claude Code Skills</strong> — install details</summary>
 
 ```bash
-npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+npx canicode init --token figd_xxxxxxxxxxxxx
 ```
 
-Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND installs the Claude Code skills (see below).
-
-> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+Drops three skills into `./.claude/skills/`:
 
-**Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
+- **canicode** — lightweight CLI wrapper (use `/canicode <figma-url>`)
+- **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
+- **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
 
-| Seat | File in Starter plan | File in Pro/Org/Enterprise |
-|------|---------------------|---------------------------|
-| View, Collab | 6 req/month | 6 req/month |
-| Dev, Full | 6 req/month | 10–20 req/min |
+The skills shell out to `npx canicode …` for analyze / gotcha-survey when the canicode MCP server is not installed — both paths produce the same JSON shape. The Figma MCP server is still required for the apply step (Step 4 in `/canicode-roundtrip`); see the prereq note above.
 
-Hitting 429 errors? Make sure the file is in a paid workspace. Or save a fixture once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
+Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips skill install (token only). `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
 
 </details>
 
 <details>
-<summary><strong>MCP Server</strong> (Claude Code / Cursor / Claude Desktop)</summary>
+<summary><strong>MCP Server</strong> — install details</summary>
 
 ```bash
-claude mcp add canicode -- npx -y -p canicode canicode-mcp
-claude mcp add -s project -t http figma https://mcp.figma.com/mcp
+claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
 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.
+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).
 
-With a Figma API token:
-```bash
-claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
-```
+If you genuinely need a per-server token without using `canicode init`, export it on the calling shell instead: `export FIGMA_TOKEN=figd_xxxxxxxxxxxxx`.
 
 For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md).
 
 </details>
 
-
 <details>
-<summary><strong>Claude Code Skills</strong> (lightweight, no MCP install)</summary>
+<summary><strong>CLI</strong> — install details</summary>
 
 ```bash
-npx canicode init --token figd_xxxxxxxxxxxxx
+npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Saves your Figma token AND installs three skills into `./.claude/skills/`:
+Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` saves the token (and installs the Claude Code skills as a bonus — pass `--no-skills` to skip).
 
-- **canicode** — lightweight CLI wrapper (use `/canicode <figma-url>`)
-- **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
-- **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
+**Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
 
-> **Next:** install the Figma MCP server (`claude mcp add -s project -t http figma https://mcp.figma.com/mcp`) and restart Claude Code so both the skills and the MCP tools load. See the **MCP Server** section above for context.
+| Seat | File in Starter plan | File in Pro/Org/Enterprise |
+|------|---------------------|---------------------------|
+| View, Collab | 6 req/month | 6 req/month |
+| Dev, Full | 6 req/month | 10–20 req/min |
 
-Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips skill install (token only). `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
+Hitting 429 errors? Make sure the file is in a paid workspace. Or save a fixture once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
 
 </details>