canicode 0.11.1 → 0.11.3

package/README.md

@@ -152,7 +152,7 @@ Drops three skills into `./.claude/skills/`:
 
 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.
 
-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.
+Flags: `--global` installs into `~/.claude/skills/` instead. `--cursor-skills` also installs Cursor copies under `.cursor/skills/`. `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
 
 </details>
 
@@ -182,7 +182,7 @@ For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZA
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` saves the token (and installs the Claude Code skills as a bonus — pass `--no-skills` to skip).
+Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` saves the token and installs the Claude Code skills into `./.claude/skills/`.
 
 **Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
 

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync, copyFileSync, readdirSync, renameSync, chmodSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync, readdirSync, renameSync, chmodSync, copyFileSync } from 'fs';
 import { join, resolve, dirname, basename, relative } from 'path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
@@ -1548,7 +1548,11 @@ CANICODE SETUP GUIDE
 
   Setup:
     canicode init --token figd_xxxxxxxxxxxxx
-    (saves token + installs skills \u2014 see section 2 for --no-skills)
+    (saves token + installs Claude Code skills into ./.claude/skills/)
+
+  Skills only (no token yet):
+    canicode init --cursor-skills
+    (installs Claude skills + Cursor copies; run init --token \u2026 before live Figma REST URLs)
 
   Use:
     canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
@@ -1558,6 +1562,7 @@ CANICODE SETUP GUIDE
     --preset strict|relaxed|dev-friendly|ai-ready
     --config ./my-config.json
     --no-open   Don't open report in browser
+    --api       No-op for Figma URLs (REST always); same flag as gotcha-survey (#461)
 
   Output:
     ~/.canicode/reports/report-YYYY-MM-DD-HH-mm-<filekey>.html
@@ -1579,7 +1584,7 @@ CANICODE SETUP GUIDE
 
   Flags:
     --global      Install to ~/.claude/skills/ instead of ./.claude/skills/
-    --no-skills   Skip skill install (token only \u2014 legacy behavior)
+    --cursor-skills  Also install Cursor copies (see \xA73)
     --force       Overwrite existing skill files without prompting
 
   Use (in Claude Code):
@@ -1604,8 +1609,8 @@ CANICODE SETUP GUIDE
 
   Flags:
     --cursor-skills   Install Cursor copies of all three skills into .cursor/skills/
-    --no-skills       Skip Claude Code skills (with --cursor-skills, still installs
-                      the Cursor bundle plus the shared gotchas answer file)
+                      (with --token, runs after full Claude skill install; without token,
+                      installs Claude skills under .claude/skills/ first, then Cursor copies)
     --force           Overwrite existing skill files without prompting
 
   Use (in Cursor Agent chat):
@@ -1613,6 +1618,14 @@ CANICODE SETUP GUIDE
     @canicode-gotchas <figma-url>      Run a gotcha survey
     @canicode-roundtrip <figma-url>    Analyze, fix gotchas in Figma, re-analyze
 
+  Invocation: docs default to @-skills for Agent chat. If your team uses slash
+  commands or Cursor rules instead, use those \u2014 capability is the same once MCP
+  + skills load.
+
+  MCP files: Cursor reads .cursor/mcp.json (or ~/.cursor/mcp.json), not the
+  repo-root .mcp.json used by Claude Code \u2014 duplicate Figma + canicode entries
+  if you use both hosts (see docs/CUSTOMIZATION.md#cursor-mcp-canicode).
+
   See also: docs/CUSTOMIZATION.md#cursor-mcp-canicode (Figma MCP required for roundtrip
   writes; analyze-only works without it).
 
@@ -4232,9 +4245,11 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.11.1";
+var version2 = "0.11.3";
 
 // src/core/engine/scoring.ts
+var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
+var DEFAULT_CODEGEN_READY_MIN_GRADE = "A";
 function computeTotalScorePerCategory(configs) {
   const totals = Object.fromEntries(
     CATEGORIES.map((c) => [c, 0])
@@ -4261,8 +4276,9 @@ function calculateGrade(percentage) {
   if (percentage >= 50) return "D";
   return "F";
 }
-function isReadyForCodeGen(grade) {
-  return grade === "S" || grade === "A+" || grade === "A";
+function isReadyForCodeGen(grade, minGrade) {
+  const threshold = minGrade ?? DEFAULT_CODEGEN_READY_MIN_GRADE;
+  return GRADE_ORDER.indexOf(grade) <= GRADE_ORDER.indexOf(threshold);
 }
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -4455,7 +4471,7 @@ function buildResultJson(fileName, result, scores, options) {
     scope: result.scope,
     issueCount: result.issues.length,
     acknowledgedCount: scores.summary.acknowledgedCount,
-    isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
+    isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade, options?.codegenReadyMinGrade),
     blockingIssueCount: scores.summary.blocking,
     scores: {
       overall: scores.overall,
@@ -4492,6 +4508,7 @@ var ConfigFileSchema = z.object({
   excludeNodeTypes: z.array(z.string()).optional(),
   excludeNodeNames: z.array(z.string()).optional(),
   gridBase: z.number().int().positive().optional(),
+  codegenReadyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional(),
   rules: z.record(z.string(), RuleOverrideSchema).superRefine((rules, ctx) => {
     const unknown = Object.keys(rules).filter((id) => !VALID_RULE_IDS.has(id));
     if (unknown.length > 0) {
@@ -5711,16 +5728,21 @@ var AnalyzeOptionsSchema = z.object({
   preset: z.enum(["relaxed", "dev-friendly", "ai-ready", "strict"]).optional(),
   output: z.string().optional(),
   token: z.string().optional(),
+  /** Accepted for CLI parity; Figma URL loads always use the REST API today (#461). */
   api: z.boolean().optional(),
   screenshot: z.boolean().optional(),
   config: z.string().optional(),
   noOpen: z.boolean().optional(),
   json: z.boolean().optional(),
   acknowledgments: z.string().optional(),
-  scope: z.enum(["page", "component"]).optional()
+  scope: z.enum(["page", "component"]).optional(),
+  readyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional()
 });
 function registerAnalyze(cli2) {
-  cli2.command("analyze <input>", "Analyze a Figma file or JSON fixture").option("--preset <preset>", "Analysis preset (relaxed | dev-friendly | ai-ready | strict)").option("--output <path>", "HTML report output path").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--api", "Load via Figma REST API (requires FIGMA_TOKEN)").option("--screenshot", "Include screenshot comparison in report (requires ANTHROPIC_API_KEY)").option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--no-open", "Don't open report in browser after analysis").option("--json", "Output JSON results to stdout (same format as MCP)").option("--acknowledgments <path>", "(#371 / ADR-019) Path to JSON acknowledgments from canicode Figma annotations (nodeId, ruleId; optional intent / sceneWriteOutcome / codegenDirective per #444). Matching issues are flagged acknowledged and contribute half weight to density.").option("--scope <scope>", "(#404) Override analysis scope: `page` (screen/section \u2014 container bounds are required) or `component` (standalone reusable unit \u2014 root FILL is the design contract). Defaults to auto-detection from the root node type.").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign --api --token YOUR_TOKEN").example("  canicode analyze ./fixtures/my-design --output report.html").example("  canicode analyze ./fixtures/my-design --config ./my-config.json").action(async (input, rawOptions) => {
+  cli2.command("analyze <input>", "Analyze a Figma file or JSON fixture").option("--preset <preset>", "Analysis preset (relaxed | dev-friendly | ai-ready | strict)").option("--output <path>", "HTML report output path").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option(
+    "--api",
+    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `gotcha-survey` (#461)."
+  ).option("--screenshot", "Include screenshot comparison in report (requires ANTHROPIC_API_KEY)").option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--no-open", "Don't open report in browser after analysis").option("--json", "Output JSON results to stdout (same format as MCP)").option("--acknowledgments <path>", "(#371 / ADR-019) Path to JSON acknowledgments from canicode Figma annotations (nodeId, ruleId; optional intent / sceneWriteOutcome / codegenDirective per #444). Matching issues are flagged acknowledged and contribute half weight to density.").option("--scope <scope>", "(#404) Override analysis scope: `page` (screen/section \u2014 container bounds are required) or `component` (standalone reusable unit \u2014 root FILL is the design contract). Defaults to auto-detection from the root node type.").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign").example("  canicode analyze ./fixtures/my-design --output report.html").example("  canicode analyze ./fixtures/my-design --config ./my-config.json").action(async (input, rawOptions) => {
     const parseResult = AnalyzeOptionsSchema.safeParse(rawOptions);
     if (!parseResult.success) {
       const msg = parseResult.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
@@ -5730,6 +5752,7 @@ ${msg}`);
       process.exit(1);
     }
     const options = parseResult.data;
+    void options.api;
     const analysisStart = Date.now();
     trackEvent(EVENTS.ANALYSIS_STARTED, { source: isJsonFile(input) || isFixtureDir(input) ? "fixture" : "figma" });
     const log = options.json ? console.error.bind(console) : console.log.bind(console);
@@ -5782,13 +5805,16 @@ Analyzing: ${file.name}`);
       let configs = options.preset ? { ...getConfigsWithPreset(options.preset) } : { ...RULE_CONFIGS };
       let excludeNodeNames;
       let excludeNodeTypes;
+      let codegenReadyMinGrade;
       if (options.config) {
         const configFile = await loadConfigFile(options.config);
         configs = mergeConfigs(configs, configFile);
         excludeNodeNames = configFile.excludeNodeNames;
         excludeNodeTypes = configFile.excludeNodeTypes;
+        codegenReadyMinGrade = configFile.codegenReadyMinGrade;
         log(`Config loaded: ${options.config}`);
       }
+      const effectiveMinGrade = options.readyMinGrade ?? codegenReadyMinGrade;
       let acknowledgments;
       if (options.acknowledgments) {
         const ackPath = resolve(options.acknowledgments);
@@ -5814,7 +5840,7 @@ Analyzing: ${file.name}`);
       log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
       const scores = calculateScores(result, configs);
       if (options.json) {
-        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input) }), null, 2));
+        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input), ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {} }), null, 2));
         if (scores.overall.grade === "F") {
           process.exitCode = 1;
         }
@@ -6006,7 +6032,13 @@ var BATCHABLE_RULE_IDS = [
   "no-auto-layout",
   "fixed-size-in-auto-layout"
 ];
+var OPT_IN_BATCHABLE_RULE_IDS = [
+  "missing-prototype"
+];
 var BATCHABLE_SET = new Set(BATCHABLE_RULE_IDS);
+var OPT_IN_BATCHABLE_SET = new Set(
+  OPT_IN_BATCHABLE_RULE_IDS
+);
 var NO_SOURCE_SENTINEL = "_no-source";
 function groupAndBatchSurveyQuestions(questions) {
   if (questions.length === 0) {
@@ -6047,20 +6079,25 @@ function sourceComponentKey(question) {
 }
 function pushIntoBatch(group, question) {
   const sceneWeight = Math.max(question.replicas ?? 1, 1);
-  const isBatchable = BATCHABLE_SET.has(question.ruleId);
+  const batchMode = resolveBatchMode(question.ruleId);
   const last = group.batches.at(-1);
-  if (last !== void 0 && last.ruleId === question.ruleId && isBatchable && last.batchable) {
+  if (last !== void 0 && last.ruleId === question.ruleId && batchMode !== "none" && last.batchMode === batchMode) {
     last.questions.push(question);
     last.totalScenes += sceneWeight;
     return;
   }
   group.batches.push({
     ruleId: question.ruleId,
-    batchable: isBatchable,
+    batchMode,
     questions: [question],
     totalScenes: sceneWeight
   });
 }
+function resolveBatchMode(ruleId) {
+  if (BATCHABLE_SET.has(ruleId)) return "safe";
+  if (OPT_IN_BATCHABLE_SET.has(ruleId)) return "opt-in";
+  return "none";
+}
 
 // src/core/gotcha/survey-generator.ts
 var NODE_PATH_SEPARATOR = " > ";
@@ -6079,12 +6116,18 @@ function generateGotchaSurvey(result, scores, options = {}) {
   const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
   const questions = deduplicateBySourceComponent(mapped);
   const groupedQuestions = groupAndBatchSurveyQuestions(questions);
+  const PROPAGATION_CANDIDATE_THRESHOLD = 3;
+  const propagationCandidates = questions.filter(
+    (q) => q.isInstanceChild
+  ).length;
+  const suggestedDefaultApply = propagationCandidates >= PROPAGATION_CANDIDATE_THRESHOLD;
   return {
     designGrade: grade,
-    isReadyForCodeGen: isReadyForCodeGen(grade),
+    isReadyForCodeGen: isReadyForCodeGen(grade, options.codegenReadyMinGrade),
     questions,
     groupedQuestions,
-    designKey: options.designKey ?? ""
+    designKey: options.designKey ?? "",
+    suggestedDefaultApply
   };
 }
 function deduplicateSiblingIssues(issues) {
@@ -6233,26 +6276,36 @@ function findNodeById2(node, id) {
 var GotchaSurveyOptionsSchema = z.object({
   preset: z.enum(["relaxed", "dev-friendly", "ai-ready", "strict"]).optional(),
   token: z.string().optional(),
+  /** Accepted for CLI parity with `analyze`; Figma URL loads always use REST (#461). */
+  api: z.boolean().optional(),
   config: z.string().optional(),
   targetNodeId: z.string().optional(),
   json: z.boolean().optional(),
-  scope: z.enum(["page", "component"]).optional()
+  scope: z.enum(["page", "component"]).optional(),
+  readyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional()
 });
 async function runGotchaSurvey(input, options) {
+  void options.api;
   const { file, nodeId } = await loadFile(input, options.token);
   const effectiveNodeId = options.targetNodeId ?? nodeId;
   let configs = options.preset ? { ...getConfigsWithPreset(options.preset) } : { ...RULE_CONFIGS };
+  let codegenReadyMinGrade;
   if (options.config) {
     const configFile = await loadConfigFile(options.config);
     configs = mergeConfigs(configs, configFile);
+    codegenReadyMinGrade = configFile.codegenReadyMinGrade;
   }
+  const effectiveMinGrade = options.readyMinGrade ?? codegenReadyMinGrade;
   const result = analyzeFile(file, {
     configs,
     ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
     ...options.scope ? { scope: options.scope } : {}
   });
   const scores = calculateScores(result, configs);
-  return generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });
+  return generateGotchaSurvey(result, scores, {
+    designKey: computeDesignKey(input),
+    ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {}
+  });
 }
 function formatHumanSummary(survey) {
   const lines = [
@@ -6267,7 +6320,10 @@ function formatHumanSummary(survey) {
   return lines.join("\n");
 }
 function registerGotchaSurvey(cli2) {
-  cli2.command("gotcha-survey <input>", "Generate a gotcha survey from a Figma design analysis").option("--preset <preset>", "Analysis preset (relaxed | dev-friendly | ai-ready | strict)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--target-node-id <id>", "Scope analysis to a specific node ID").option("--scope <scope>", "(#404) Override analysis scope: `page` or `component`. Defaults to auto-detection from the root node type.").option("--json", "Output GotchaSurvey JSON to stdout (same format as MCP)").example("  canicode gotcha-survey https://www.figma.com/design/ABC123/MyDesign --json").example("  canicode gotcha-survey ./fixtures/my-design --json").action(async (input, rawOptions) => {
+  cli2.command("gotcha-survey <input>", "Generate a gotcha survey from a Figma design analysis").option("--preset <preset>", "Analysis preset (relaxed | dev-friendly | ai-ready | strict)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option(
+    "--api",
+    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `analyze` (#461)."
+  ).option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--target-node-id <id>", "Scope analysis to a specific node ID").option("--scope <scope>", "(#404) Override analysis scope: `page` or `component`. Defaults to auto-detection from the root node type.").option("--json", "Output GotchaSurvey JSON to stdout (same format as MCP)").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").example("  canicode gotcha-survey https://www.figma.com/design/ABC123/MyDesign --json").example("  canicode gotcha-survey ./fixtures/my-design --json").action(async (input, rawOptions) => {
     const parseResult = GotchaSurveyOptionsSchema.safeParse(rawOptions);
     if (!parseResult.success) {
       const msg = parseResult.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
@@ -6386,13 +6442,17 @@ var GotchaSurveyQuestionSchema = z.object({
 var SurveyQuestionBatchSchema = z.object({
   ruleId: z.string(),
   /**
-   * `true` when every member shares an answer-shape uniformly applicable to
-   * all of them (e.g. one `min-width` value covers all FILL children).
-   * The SKILL renders one shared prompt for `batchable: true` batches with
-   * `questions.length >= 2`; everything else falls through to the
-   * single-question template.
+   * Rendering mode for this batch (see `BatchMode` in
+   * `src/core/gotcha/group-and-batch-questions.ts` — the authoritative
+   * whitelists `BATCHABLE_RULE_IDS` and `OPT_IN_BATCHABLE_RULE_IDS` live
+   * there):
+   * - `"safe"` — one answer uniformly applies to every member (#369).
+   * - `"opt-in"` — one shared answer is a suggested default; the user may
+   *   reply `split` for per-node override (#426).
+   * - `"none"` — single-member batch, renders the standard per-question
+   *   template.
    */
-  batchable: z.boolean(),
+  batchMode: z.enum(["safe", "opt-in", "none"]),
   questions: z.array(GotchaSurveyQuestionSchema),
   /**
    * Sum of `max(question.replicas, 1)` across `questions`. Counts the
@@ -6426,7 +6486,21 @@ var GotchaSurveySchema = z.object({
    * this directly when upserting the per-design section, so the SKILL.md
    * prose no longer parses URLs (per ADR-016).
    */
-  designKey: z.string()
+  designKey: z.string(),
+  /**
+   * #428 — threshold hint for the `allowDefinitionWrite` picker in the
+   * `canicode-roundtrip` skill. `true` when `propagationCandidates >= 3`
+   * (i.e. three or more questions target instance children that could
+   * benefit from definition-level writes). When `false`, the skill silently
+   * uses the annotation default (ADR-012) without surfacing the picker —
+   * the opt-in flow is over-engineered for tiny surveys.
+   *
+   * Computed server-side from `questions` so the skill doesn't have to
+   * count `isInstanceChild` manually; the skill may still override this
+   * hint when it has additional context (e.g. all candidates are
+   * read-only per probe result).
+   */
+  suggestedDefaultApply: z.boolean()
 });
 var AnswersMapSchema = z.record(
   z.string(),
@@ -6908,52 +6982,6 @@ function defaultSourceDir() {
 function defaultCursorBundleRoot() {
   return fileURLToPath(new URL("../../skills/cursor", import.meta.url));
 }
-async function copySkillTree(skillName, srcSkillDir, destSkillDir, force) {
-  if (!existsSync(srcSkillDir)) {
-    throw new Error(`Bundled skill directory missing: ${srcSkillDir}`);
-  }
-  mkdirSync(destSkillDir, { recursive: true });
-  const ops = [];
-  const files = listFilesRecursive(srcSkillDir);
-  for (const relPath of files) {
-    const src = join(srcSkillDir, relPath);
-    const dest = join(destSkillDir, relPath);
-    mkdirSync(dirname(dest), { recursive: true });
-    const label = join(skillName, relPath);
-    let action;
-    if (!existsSync(dest)) {
-      action = "install";
-    } else if (force) {
-      action = "force-overwrite";
-    } else {
-      action = "needs-decision";
-    }
-    ops.push({ src, dest, label, action });
-  }
-  const candidates = ops.filter((op) => op.action === "needs-decision");
-  const decisions = candidates.length > 0 ? await promptOverwriteBatch(candidates.map((op) => ({ label: op.label, dest: op.dest }))) : /* @__PURE__ */ new Map();
-  const installed = [];
-  const overwritten = [];
-  const skipped = [];
-  for (const op of ops) {
-    if (op.action === "install") {
-      copyFileSync(op.src, op.dest);
-      installed.push(op.label);
-    } else if (op.action === "force-overwrite") {
-      copyFileSync(op.src, op.dest);
-      overwritten.push(op.label);
-    } else {
-      const decision = decisions.get(op.label) ?? "skip";
-      if (decision === "overwrite") {
-        copyFileSync(op.src, op.dest);
-        overwritten.push(op.label);
-      } else {
-        skipped.push(op.label);
-      }
-    }
-  }
-  return { installed, overwritten, skipped };
-}
 async function copyMultipleSkillTrees(entries, force) {
   const ops = [];
   for (const { skillName, srcSkillDir, destSkillDir } of entries) {
@@ -7064,35 +7092,6 @@ If you installed canicode from npm, please file a bug report \u2014 the tarball
   }
   return summary;
 }
-var InstallClaudeGotchasOnlySchema = z.object({
-  force: z.boolean(),
-  cwd: z.string().optional(),
-  sourceDir: z.string().optional()
-});
-async function installClaudeGotchasSkillOnly(rawOptions) {
-  const options = InstallClaudeGotchasOnlySchema.parse(rawOptions);
-  const sourceDir = options.sourceDir ?? defaultSourceDir();
-  const skillName = "canicode-gotchas";
-  const srcSkillDir = join(sourceDir, skillName);
-  const cwd = options.cwd ?? process.cwd();
-  const targetDir = join(cwd, ".claude", "skills");
-  const destSkillDir = join(targetDir, skillName);
-  if (!existsSync(sourceDir)) {
-    throw new Error(
-      `Bundled skills directory not found: ${sourceDir}
-If you are developing canicode, run 'pnpm build' first.
-If you installed canicode from npm, please file a bug report \u2014 the tarball is missing skills/.`
-    );
-  }
-  mkdirSync(targetDir, { recursive: true });
-  const part = await copySkillTree(skillName, srcSkillDir, destSkillDir, options.force);
-  return {
-    installed: part.installed,
-    overwritten: part.overwritten,
-    skipped: part.skipped,
-    targetDir
-  };
-}
 var InstallCursorBundledSchema = z.object({
   force: z.boolean(),
   cwd: z.string().optional(),
@@ -7252,14 +7251,67 @@ function formatNextSteps(opts) {
 var InitOptionsSchema = z.object({
   token: z.string().optional(),
   global: z.boolean().optional(),
-  // Declared positively as `--skills`; mri's built-in `--no-` prefix handling
-  // still maps `--no-skills` to `skills: false`. Declaring the option
-  // positively avoids cac's `(default: true)` artifact on negated flags.
-  skills: z.boolean().optional(),
   /** Install `skills/cursor/*` into `.cursor/skills/` (canicode, gotchas, roundtrip — issue #407). */
   cursorSkills: z.boolean().optional(),
   force: z.boolean().optional()
 });
+function wantsSkillInstallWithoutToken(options) {
+  return options.cursorSkills === true;
+}
+async function runInitSkillInstallSteps(options) {
+  let skillStepOk = true;
+  let skillSummary;
+  try {
+    const summary = await installSkills({
+      target: options.global ? "global" : "project",
+      force: options.force ?? false
+    });
+    console.log(`
+  Skills installed to: ${summary.targetDir}/`);
+    console.log(`    installed:   ${summary.installed.length}`);
+    console.log(`    overwritten: ${summary.overwritten.length}`);
+    console.log(`    skipped:     ${summary.skipped.length}`);
+    if (summary.skipped.length > 0) {
+      console.log(`  (Re-run with --force to overwrite skipped files.)`);
+    }
+    skillSummary = {
+      installed: summary.installed.length,
+      overwritten: summary.overwritten.length,
+      skipped: summary.skipped.length
+    };
+  } catch (skillError) {
+    console.error(
+      `
+  Skill install failed: ${skillError instanceof Error ? skillError.message : String(skillError)}`
+    );
+    process.exitCode = 1;
+    skillStepOk = false;
+  }
+  if (options.cursorSkills && skillStepOk) {
+    try {
+      const cSummary = await installCursorBundledSkills({
+        force: options.force ?? false
+      });
+      console.log(`
+  Cursor skills installed to: ${cSummary.targetDir}/`);
+      console.log(`    installed:   ${cSummary.installed.length}`);
+      console.log(`    overwritten: ${cSummary.overwritten.length}`);
+      console.log(`    skipped:     ${cSummary.skipped.length}`);
+      if (cSummary.skipped.length > 0) {
+        console.log(`  (Re-run with --force to overwrite skipped files.)`);
+      }
+      console.log(`  Open a new chat and @-mention canicode, canicode-gotchas, or canicode-roundtrip if skills do not appear immediately.`);
+    } catch (cursorError) {
+      console.error(
+        `
+  Cursor skill install failed: ${cursorError instanceof Error ? cursorError.message : String(cursorError)}`
+      );
+      process.exitCode = 1;
+      skillStepOk = false;
+    }
+  }
+  return skillSummary !== void 0 ? { skillStepOk, skillSummary } : { skillStepOk };
+}
 function registerInit(cli2) {
   cli2.command(
     "init",
@@ -7267,7 +7319,7 @@ function registerInit(cli2) {
   ).option(
     "--token <token>",
     "Save Figma API token (use env/CLI only \u2014 not agent chat) and install Claude Code skills to .claude/skills/"
-  ).option("--global", "Install skills to ~/.claude/skills/ instead of ./.claude/skills/").option("--skills", "Install Claude Code skills into .claude/skills/ (default: on \u2014 pass --no-skills to opt out)").option("--cursor-skills", "Also install Cursor copies of canicode / canicode-gotchas / canicode-roundtrip under .cursor/skills/").option("--force", "Overwrite existing skill files without prompting (also for non-TTY/CI)").action(async (rawOptions) => {
+  ).option("--global", "Install skills to ~/.claude/skills/ instead of ./.claude/skills/").option("--cursor-skills", "Also install Cursor copies of canicode / canicode-gotchas / canicode-roundtrip under .cursor/skills/ (with `--token`, runs after Claude skills; without token, installs Claude skills + Cursor bundle)").option("--force", "Overwrite existing skill files without prompting (also for non-TTY/CI)").action(async (rawOptions) => {
     try {
       const parseResult = InitOptionsSchema.safeParse(rawOptions);
       if (!parseResult.success) {
@@ -7282,98 +7334,48 @@ ${msg}`);
         initAiready(options.token);
         console.log(`  Config saved: ${getConfigPath()}`);
         console.log(`  Reports will be saved to: ${getReportsDir()}/`);
-        let skillStepOk = true;
-        let skillSummary;
-        if (options.skills !== false) {
-          try {
-            const summary = await installSkills({
-              target: options.global ? "global" : "project",
-              force: options.force ?? false
-            });
-            console.log(`
-  Skills installed to: ${summary.targetDir}/`);
-            console.log(`    installed:   ${summary.installed.length}`);
-            console.log(`    overwritten: ${summary.overwritten.length}`);
-            console.log(`    skipped:     ${summary.skipped.length}`);
-            if (summary.skipped.length > 0) {
-              console.log(`  (Re-run with --force to overwrite skipped files.)`);
-            }
-            skillSummary = {
-              installed: summary.installed.length,
-              overwritten: summary.overwritten.length,
-              skipped: summary.skipped.length
-            };
-          } catch (skillError) {
-            console.error(
-              `
-  Skill install failed: ${skillError instanceof Error ? skillError.message : String(skillError)}`
-            );
-            process.exitCode = 1;
-            skillStepOk = false;
-          }
-        } else if (options.cursorSkills) {
-          try {
-            const summary = await installClaudeGotchasSkillOnly({
-              force: options.force ?? false
-            });
-            console.log(`
-  Gotchas store (Claude Code skills path) installed to: ${summary.targetDir}/`);
-            console.log(`    installed:   ${summary.installed.length}`);
-            console.log(`    overwritten: ${summary.overwritten.length}`);
-            console.log(`    skipped:     ${summary.skipped.length}`);
-            skillSummary = {
-              installed: summary.installed.length,
-              overwritten: summary.overwritten.length,
-              skipped: summary.skipped.length
-            };
-          } catch (skillError) {
-            console.error(
-              `
-  Gotchas skill install failed: ${skillError instanceof Error ? skillError.message : String(skillError)}`
-            );
-            process.exitCode = 1;
-            skillStepOk = false;
-          }
-        }
-        if (options.cursorSkills && skillStepOk) {
-          try {
-            const cSummary = await installCursorBundledSkills({
-              force: options.force ?? false
-            });
-            console.log(`
-  Cursor skills installed to: ${cSummary.targetDir}/`);
-            console.log(`    installed:   ${cSummary.installed.length}`);
-            console.log(`    overwritten: ${cSummary.overwritten.length}`);
-            console.log(`    skipped:     ${cSummary.skipped.length}`);
-            if (cSummary.skipped.length > 0) {
-              console.log(`  (Re-run with --force to overwrite skipped files.)`);
-            }
-            console.log(`  Open a new chat and @-mention canicode, canicode-gotchas, or canicode-roundtrip if skills do not appear immediately.`);
-          } catch (cursorError) {
-            console.error(
-              `
-  Cursor skill install failed: ${cursorError instanceof Error ? cursorError.message : String(cursorError)}`
-            );
-            process.exitCode = 1;
-            skillStepOk = false;
-          }
+        const { skillStepOk, skillSummary } = await runInitSkillInstallSteps(options);
+        trackEvent(EVENTS.CLI_INIT, {
+          skillsRequested: true,
+          cursorSkillsRequested: options.cursorSkills === true,
+          skillStepOk,
+          target: options.global ? "global" : "project",
+          force: options.force ?? false,
+          ...skillSummary ?? {}
+        });
+        if (skillStepOk) {
+          console.log(
+            formatNextSteps({
+              figmaMcpPresent: figmaMcpRegistered(),
+              skillsInstalled: true,
+              cursorSkillsInstalled: options.cursorSkills === true
+            })
+          );
         }
+        return;
+      }
+      if (wantsSkillInstallWithoutToken(options)) {
+        const { skillStepOk, skillSummary } = await runInitSkillInstallSteps(options);
         trackEvent(EVENTS.CLI_INIT, {
-          skillsRequested: options.skills !== false,
+          skillsRequested: true,
           cursorSkillsRequested: options.cursorSkills === true,
           skillStepOk,
           target: options.global ? "global" : "project",
           force: options.force ?? false,
+          skillOnlyInit: true,
           ...skillSummary ?? {}
         });
         if (skillStepOk) {
           console.log(
             formatNextSteps({
               figmaMcpPresent: figmaMcpRegistered(),
-              skillsInstalled: options.skills !== false,
+              skillsInstalled: true,
               cursorSkillsInstalled: options.cursorSkills === true
             })
           );
+          console.log(
+            "\n  Figma token not saved \u2014 run `canicode init --token \u2026` when you need REST analyze or MCP against live files."
+          );
         }
         return;
       }
@@ -7390,8 +7392,7 @@ ${msg}`);
       console.log(`  --token also installs three Claude Code skills into ./.claude/skills/`);
       console.log(`  (canicode, canicode-gotchas, canicode-roundtrip).`);
       console.log(`  --global       Install to ~/.claude/skills/ instead`);
-      console.log(`  --no-skills    Skip skill install (token only)`);
-      console.log(`  --cursor-skills Also install Cursor copies of all three skills (.cursor/skills/); with --no-skills, still installs .claude gotcha store + Cursor bundle`);
+      console.log(`  --cursor-skills Install Claude skills under .claude/skills/ plus Cursor copies under .cursor/skills/ (no --token yet \u2014 add --token when ready for REST analyze)`);
       console.log(`  --force        Overwrite existing skill files without prompting
 `);
       console.log(`After setup:`);
@@ -10818,10 +10819,7 @@ cli.help((sections) => {
     },
     {
       title: "\nData source",
-      body: [
-        `  --api                   Load via Figma REST API (needs FIGMA_TOKEN)`,
-        `  --token <token>         Figma API token (or use FIGMA_TOKEN env var)`
-      ].join("\n")
+      body: `  --token <token>         Figma API token (or use FIGMA_TOKEN env var)`
     },
     {
       title: "\nCustomization",
@@ -10830,7 +10828,6 @@ cli.help((sections) => {
     {
       title: "\nExamples",
       body: [
-        `  $ canicode analyze "https://www.figma.com/design/..." --api`,
         `  $ canicode analyze "https://www.figma.com/design/..." --preset strict`,
         `  $ canicode analyze "https://www.figma.com/design/..." --config ./my-config.json`,
         `  $ canicode gotcha-survey "https://www.figma.com/design/..." --json`,