canicode 0.11.0 → 0.11.2

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';
@@ -1377,7 +1377,9 @@ var EVENTS = {
   // cannot import `core/monitoring` directly, so the event fires through a
   // caller-supplied callback. Define the typed name here so a future consumer
   // has a single place to wire it up.
-  ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`
+  ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`,
+  /** CLI `canicode roundtrip-tally` completed successfully. */
+  ROUNDTRIP_TALLY: `${EVENT_PREFIX}roundtrip_tally`
 };
 
 // src/core/monitoring/capture.ts
@@ -1529,6 +1531,14 @@ function printDocsSetup() {
   console.log(`
 CANICODE SETUP GUIDE
 
+  Skills at a glance: canicode-gotchas = survey answers saved locally (memo-only).
+  canicode-roundtrip = same flow plus writes to Figma via use_figma (canvas).
+
+  Token safety: Do NOT paste your Figma token into Claude, Cursor, or other
+  agent chats \u2014 transcripts can retain it. Use:
+    FIGMA_TOKEN=figd_\u2026 npx canicode init
+  or run \`npx canicode init\` and enter the token only at the CLI prompt.
+
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
  1. CLI (REST API)
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -1538,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"
@@ -1548,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
@@ -1556,6 +1571,8 @@ CANICODE SETUP GUIDE
  2. CLAUDE CODE SKILLS (requires FIGMA_TOKEN)
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 
+  (Same token safety as above \u2014 env var or interactive prompt, not chat.)
+
   Setup:
     canicode init --token figd_xxxxxxxxxxxxx
     (installs three skills into ./.claude/skills/ alongside the token)
@@ -1567,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):
@@ -1575,6 +1592,43 @@ CANICODE SETUP GUIDE
     /canicode-gotchas <url>      Run a gotcha survey
     /canicode-roundtrip <url>    Analyze, fix gotchas in Figma, re-analyze
 
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ 3. CURSOR SKILLS (requires FIGMA_TOKEN)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  (Same token safety as above \u2014 env var or interactive prompt, not chat.)
+
+  Setup:
+    canicode init --token figd_xxxxxxxxxxxxx --cursor-skills
+    (installs Cursor copies of the three skills into ./.cursor/skills/)
+
+  Installed skills:
+    canicode             Lightweight CLI wrapper
+    canicode-gotchas     Standalone gotcha survey
+    canicode-roundtrip   Full analyze -> gotcha -> apply roundtrip
+
+  Flags:
+    --cursor-skills   Install Cursor copies of all three skills into .cursor/skills/
+                      (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):
+    @canicode <figma-url>
+    @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).
+
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
  TOKEN PRIORITY
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -1590,6 +1644,7 @@ CANICODE SETUP GUIDE
   CI/CD, automation        -> CLI + FIGMA_TOKEN env var
   Claude Code (full)       -> canicode MCP server + FIGMA_TOKEN
   Claude Code (light)      -> /canicode skill + FIGMA_TOKEN
+  Cursor Agent             -> canicode init --cursor-skills + Figma MCP
   In Figma                 -> Figma Plugin
   Browser                  -> Web App (GitHub Pages)
   Quick trial, offline     -> CLI + JSON fixtures
@@ -3520,9 +3575,27 @@ defineRule({
   definition: missingPrototypeDef,
   check: missingPrototypeCheck
 });
+var AcknowledgmentIntentSchema = z.object({
+  field: z.string(),
+  value: z.unknown(),
+  scope: z.enum(["instance", "definition"])
+});
+var AcknowledgmentSceneWriteOutcomeSchema = z.object({
+  result: z.enum([
+    "succeeded",
+    "silent-ignored",
+    "api-rejected",
+    "user-declined-propagation",
+    "unknown"
+  ]),
+  reason: z.string().optional()
+});
 var AcknowledgmentSchema = z.object({
   nodeId: z.string(),
-  ruleId: z.string()
+  ruleId: z.string(),
+  intent: AcknowledgmentIntentSchema.optional(),
+  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
+  codegenDirective: z.string().optional()
 });
 var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
 function normalizeNodeId(id) {
@@ -4172,7 +4245,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.11.0";
+var version2 = "0.11.2";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -5651,6 +5724,7 @@ 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(),
@@ -5660,7 +5734,10 @@ var AnalyzeOptionsSchema = z.object({
   scope: z.enum(["page", "component"]).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) Path to a JSON file containing [{ nodeId, ruleId }] pairs harvested from canicode-authored Figma annotations. 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.").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");
@@ -5670,6 +5747,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);
@@ -5946,7 +6024,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) {
@@ -5987,20 +6071,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 = " > ";
@@ -6019,12 +6108,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),
     questions,
     groupedQuestions,
-    designKey: options.designKey ?? ""
+    designKey: options.designKey ?? "",
+    suggestedDefaultApply
   };
 }
 function deduplicateSiblingIssues(issues) {
@@ -6173,12 +6268,15 @@ 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()
 });
 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 };
@@ -6207,7 +6305,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)").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");
@@ -6260,6 +6361,239 @@ ${msg}`);
     }
   });
 }
+var DetectionSchema = z.literal("rule-based");
+var OutputChannelSchema = z.enum(["score", "annotation"]);
+var PersistenceIntentSchema = z.enum(["transient", "durable"]);
+var RulePurposeSchema = z.enum(["violation", "info-collection"]);
+
+// src/core/contracts/gotcha-survey.ts
+var GradeSchema = z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]);
+var InstanceContextSchema = z.object({
+  parentInstanceNodeId: z.string(),
+  sourceNodeId: z.string(),
+  sourceComponentId: z.string().optional(),
+  sourceComponentName: z.string().optional()
+});
+var RuleApplyStrategySchema = z.enum([
+  "property-mod",
+  "structural-mod",
+  "annotation",
+  "auto-fix"
+]);
+var TargetPropertySchema = z.union([z.string(), z.array(z.string())]);
+var AnnotationPropertySchema = z.object({ type: z.string() });
+var GotchaDetectionSchema = DetectionSchema;
+var GotchaOutputChannelSchema = OutputChannelSchema.extract([
+  "annotation"
+]);
+var GotchaPersistenceIntentSchema = PersistenceIntentSchema.extract([
+  "durable"
+]);
+var GotchaSurveyQuestionSchema = z.object({
+  nodeId: z.string(),
+  nodeName: z.string(),
+  ruleId: z.string(),
+  detection: GotchaDetectionSchema,
+  outputChannel: GotchaOutputChannelSchema,
+  persistenceIntent: GotchaPersistenceIntentSchema,
+  /**
+   * #406: Classifies the triggering rule as `violation` (score-primary,
+   * gotcha secondary) or `info-collection` (annotation-primary, score
+   * minimal). Consumers use this to prioritize answers that collect durable
+   * implementation context over answers that merely describe how to fix a
+   * violation the rule will stop firing for.
+   */
+  purpose: RulePurposeSchema,
+  severity: SeveritySchema,
+  question: z.string(),
+  hint: z.string(),
+  example: z.string(),
+  instanceContext: InstanceContextSchema.optional(),
+  applyStrategy: RuleApplyStrategySchema,
+  targetProperty: TargetPropertySchema.optional(),
+  annotationProperties: z.array(AnnotationPropertySchema).optional(),
+  suggestedName: z.string().optional(),
+  isInstanceChild: z.boolean(),
+  sourceChildId: z.string().optional(),
+  // #356: when this question collapses N instance-child issues that share the
+  // same `(sourceComponentId, sourceNodeId, ruleId)` tuple, `replicas` is the
+  // total instance count (>=2) and `replicaNodeIds` lists every instance scene
+  // node id OTHER than the kept `nodeId`. Apply step iterates
+  // `[nodeId, ...replicaNodeIds]` so the same answer lands on every replica.
+  // Single-instance questions omit both fields.
+  replicas: z.number().int().min(2).optional(),
+  replicaNodeIds: z.array(z.string()).optional()
+});
+var SurveyQuestionBatchSchema = z.object({
+  ruleId: z.string(),
+  /**
+   * 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.
+   */
+  batchMode: z.enum(["safe", "opt-in", "none"]),
+  questions: z.array(GotchaSurveyQuestionSchema),
+  /**
+   * Sum of `max(question.replicas, 1)` across `questions`. Counts the
+   * actual Figma scene fan-out so the SKILL can render `N instances`
+   * accurately even when one batch member already collapses multiple
+   * replicas via the #356 source-component dedupe.
+   */
+  totalScenes: z.number().int().min(1)
+});
+var SurveyQuestionGroupSchema = z.object({
+  /**
+   * Shared `instanceContext` for the group, or `null` for the trailing
+   * non-instance group. The SKILL emits the verbose "Instance note" header
+   * once per non-null group instead of once per question (#370).
+   */
+  instanceContext: InstanceContextSchema.nullable(),
+  batches: z.array(SurveyQuestionBatchSchema)
+});
+var GroupedSurveySchema = z.object({
+  groups: z.array(SurveyQuestionGroupSchema)
+});
+var GotchaSurveySchema = z.object({
+  designGrade: GradeSchema,
+  isReadyForCodeGen: z.boolean(),
+  questions: z.array(GotchaSurveyQuestionSchema),
+  groupedQuestions: GroupedSurveySchema,
+  /**
+   * #384 — canonical identifier for this design across canicode runs.
+   * Computed by `computeDesignKey(input)` (`<fileKey>#<nodeId>` for Figma
+   * URLs, absolute path for fixtures). The `canicode-gotchas` SKILL reads
+   * this directly when upserting the per-design section, so the SKILL.md
+   * prose no longer parses URLs (per ADR-016).
+   */
+  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(),
+  z.union([
+    z.object({ answer: z.string() }),
+    z.object({ skipped: z.literal(true) })
+  ])
+);
+var RenderGotchaSectionInputSchema = z.object({
+  questions: z.array(GotchaSurveyQuestionSchema),
+  answers: AnswersMapSchema,
+  designName: z.string(),
+  figmaUrl: z.string(),
+  designKey: z.string(),
+  designGrade: z.string(),
+  analyzedAt: z.string(),
+  /** Local date for the section header (`YYYY-MM-DD`). */
+  today: z.string()
+});
+function isSkippedAnswer(nodeId, answers) {
+  const v = answers[nodeId];
+  if (v === void 0) return true;
+  if ("skipped" in v && v.skipped === true) return true;
+  if ("answer" in v) return false;
+  return true;
+}
+function skippedCountsByRule(skippedQs) {
+  const m = /* @__PURE__ */ new Map();
+  for (const q of skippedQs) {
+    m.set(q.ruleId, (m.get(q.ruleId) ?? 0) + 1);
+  }
+  return m;
+}
+function renderSkippedCompact(skippedQs) {
+  const n = skippedQs.length;
+  const counts = skippedCountsByRule(skippedQs);
+  const lines = [`#### Skipped (${n})`, ""];
+  const sortedRules = [...counts.keys()].sort((a, b) => a.localeCompare(b));
+  for (const ruleId of sortedRules) {
+    const c = counts.get(ruleId) ?? 0;
+    lines.push(`- \`${ruleId}\` \xD7 ${c}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderInstanceContextBullet(q) {
+  const ic = q.instanceContext;
+  if (!ic) return null;
+  let componentPart = "";
+  if (ic.sourceComponentName !== void 0 && ic.sourceComponentId !== void 0) {
+    componentPart = `, component \`${ic.sourceComponentName}\` / \`${ic.sourceComponentId}\``;
+  } else if (ic.sourceComponentName !== void 0) {
+    componentPart = `, component \`${ic.sourceComponentName}\``;
+  } else if (ic.sourceComponentId !== void 0) {
+    componentPart = `, component \`${ic.sourceComponentId}\``;
+  }
+  return `- **Instance context**: parent instance \`${ic.parentInstanceNodeId}\`, source node \`${ic.sourceNodeId}\`${componentPart} \u2014 roundtrip apply uses this to write on the source definition when instance overrides fail.`;
+}
+function renderGotchaSection(raw) {
+  const input = RenderGotchaSectionInputSchema.parse(raw);
+  const header = [
+    `## #{{SECTION_NUMBER}} \u2014 ${input.designName} \u2014 ${input.today}`,
+    "",
+    `- **Figma URL**: ${input.figmaUrl}`,
+    `- **Design key**: ${input.designKey}`,
+    `- **Grade**: ${input.designGrade}`,
+    `- **Analyzed at**: ${input.analyzedAt}`,
+    "",
+    "### Gotchas",
+    ""
+  ].join("\n");
+  const answered = [];
+  const skippedList = [];
+  for (const q of input.questions) {
+    if (isSkippedAnswer(q.nodeId, input.answers)) skippedList.push(q);
+    else answered.push(q);
+  }
+  const blocks = [];
+  for (const q of answered) {
+    const v = input.answers[q.nodeId];
+    if (v === void 0 || !("answer" in v)) {
+      throw new Error(
+        `renderGotchaSection: expected answer for nodeId ${q.nodeId} (answered set)`
+      );
+    }
+    const answerLine = v.answer;
+    const lines = [
+      `#### ${q.ruleId} \u2014 ${q.nodeName}`,
+      "",
+      `- **Severity**: ${q.severity}`,
+      `- **Node ID**: ${q.nodeId}`
+    ];
+    const icBullet = renderInstanceContextBullet(q);
+    if (icBullet !== null) {
+      lines.push(icBullet);
+    }
+    lines.push(
+      `- **Question**: ${q.question}`,
+      `- **Answer**: ${answerLine}`,
+      ""
+    );
+    blocks.push(lines.join("\n"));
+  }
+  if (skippedList.length > 0) {
+    blocks.push(renderSkippedCompact(skippedList));
+  }
+  return `${header}${blocks.join("")}`.replace(/\s+$/, "") + "\n";
+}
 z.enum([
   "missing",
   "valid",
@@ -6376,10 +6710,26 @@ function ensureTrailingNewline(s) {
 }
 
 // src/cli/commands/upsert-gotcha-section.ts
+var AnswerSchema = z.union([
+  z.object({ answer: z.string() }),
+  z.object({ skipped: z.literal(true) })
+]);
+var UpsertJsonPayloadSchema = z.object({
+  survey: GotchaSurveySchema.pick({
+    designKey: true,
+    designGrade: true,
+    questions: true
+  }),
+  answers: z.record(z.string(), AnswerSchema),
+  designName: z.string(),
+  figmaUrl: z.string(),
+  analyzedAt: z.string(),
+  today: z.string()
+});
 var UpsertOptionsSchema = z.object({
   file: z.string().min(1, "--file is required"),
   designKey: z.string().min(1, "--design-key is required"),
-  section: z.string().min(1, "--section is required (use '-' to read stdin)")
+  input: z.string().min(1, "--input is required (use '--input=-' to read stdin)")
 });
 var USER_MESSAGES = {
   missing: "Gotchas SKILL.md not found at the given path. Run `canicode init` first, then re-invoke this skill.",
@@ -6392,8 +6742,38 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+function parseUpsertPayload(rawJson) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch {
+    throw new Error("Invalid JSON in --input");
+  }
+  const result = UpsertJsonPayloadSchema.safeParse(parsed);
+  if (!result.success) {
+    const msg = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(`Invalid upsert payload: ${msg}`);
+  }
+  return result.data;
+}
 async function runUpsertGotchaSection(options) {
-  const sectionMarkdown = options.section === "-" ? await readStdin() : options.section;
+  const rawJson = options.input === "-" ? await readStdin() : readFileSync(options.input, "utf-8");
+  const payload = parseUpsertPayload(rawJson);
+  if (payload.survey.designKey !== options.designKey) {
+    throw new Error(
+      `--design-key (${options.designKey}) does not match survey.designKey (${payload.survey.designKey})`
+    );
+  }
+  const sectionMarkdown = renderGotchaSection({
+    questions: payload.survey.questions,
+    answers: payload.answers,
+    designName: payload.designName,
+    figmaUrl: payload.figmaUrl,
+    designKey: payload.survey.designKey,
+    designGrade: payload.survey.designGrade,
+    analyzedAt: payload.analyzedAt,
+    today: payload.today
+  });
   const currentContent = existsSync(options.file) ? readFileSync(options.file, "utf-8") : null;
   const { state, newContent, plan } = renderUpsertedFile({
     currentContent,
@@ -6406,7 +6786,8 @@ async function runUpsertGotchaSection(options) {
       action: null,
       sectionNumber: null,
       wrote: false,
-      userMessage: USER_MESSAGES[state] ?? null
+      userMessage: USER_MESSAGES[state] ?? null,
+      designKey: payload.survey.designKey
     };
   }
   writeFileSync(options.file, newContent, "utf-8");
@@ -6415,7 +6796,8 @@ async function runUpsertGotchaSection(options) {
     action: plan?.action ?? null,
     sectionNumber: plan?.sectionNumber ?? null,
     wrote: true,
-    userMessage: null
+    userMessage: null,
+    designKey: payload.survey.designKey
   };
 }
 function registerUpsertGotchaSection(cli2) {
@@ -6426,8 +6808,8 @@ function registerUpsertGotchaSection(cli2) {
     "--design-key <key>",
     "Canonical design key from gotcha-survey's response"
   ).option(
-    "--section <markdown>",
-    "Already-rendered per-design section markdown. Use '-' to read from stdin."
+    "--input <path>",
+    "JSON payload path, or '--input=-' to read JSON from stdin (cac parses a bare '-' as a flag, so the '=' form is required)."
   ).action(async (rawOptions) => {
     const parseResult = UpsertOptionsSchema.safeParse(rawOptions);
     if (!parseResult.success) {
@@ -6585,52 +6967,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) {
@@ -6741,35 +7077,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(),
@@ -6894,14 +7201,16 @@ function formatNextSteps(opts) {
         "",
         "  Next:",
         "    1. Restart Cursor or reload MCP (so skills + MCP tools load in a fresh session)",
-        "    2. In Agent chat, @ canicode-roundtrip with your Figma URL (or @ canicode-gotchas for survey-only)"
+        "    2. In Agent chat, @ canicode-roundtrip with your Figma URL (or @ canicode-gotchas for survey-only)",
+        "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode (project `.cursor/mcp.json`), then reload MCP; otherwise skills keep using `npx canicode \u2026` (#433)."
       ].join("\n");
     }
     return [
       "",
       "  Next:",
       "    1. Restart Claude Code (the newly installed skills only load on a fresh session)",
-      "    2. Run /canicode-roundtrip <figma-url>"
+      "    2. Run /canicode-roundtrip <figma-url>",
+      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so `analyze` / `gotcha-survey` tools load \u2014 otherwise skills shell out to `npx canicode \u2026` (#433)."
     ].join("\n");
   }
   if (cursor) {
@@ -6910,7 +7219,8 @@ function formatNextSteps(opts) {
       "  Next:",
       "    1. Add Figma MCP to .cursor/mcp.json (see https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode and Figma MCP docs)",
       "    2. Restart Cursor so Figma tools (e.g. use_figma) load",
-      "    3. @ canicode-roundtrip with your Figma URL for full roundtrip"
+      "    3. @ canicode-roundtrip with your Figma URL for full roundtrip",
+      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per the Customization guide (`#cursor-mcp-canicode`), then reload MCP; otherwise skills keep using `npx canicode \u2026` (#433)."
     ].join("\n");
   }
   return [
@@ -6919,20 +7229,82 @@ function formatNextSteps(opts) {
     "    1. Install Figma MCP:",
     "         claude mcp add -s project -t http figma https://mcp.figma.com/mcp",
     "    2. Restart Claude Code (so the new skills + Figma MCP tools both load)",
-    "    3. Run /canicode-roundtrip <figma-url>"
+    "    3. Run /canicode-roundtrip <figma-url>",
+    "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so MCP tools load \u2014 otherwise skills shell out to `npx canicode \u2026` (#433)."
   ].join("\n");
 }
 var InitOptionsSchema = z.object({
   token: z.string().optional(),
   global: z.boolean().optional(),
-  // cac maps `--no-skills` to `skills: false` (mirrors `--no-telemetry`).
-  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", "Set up canicode with Figma API token").option("--token <token>", "Save Figma API token and install Claude Code skills to .claude/skills/").option("--global", "Install skills to ~/.claude/skills/ instead of ./.claude/skills/").option("--no-skills", "Skip skill installation (token only)").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) => {
+  cli2.command(
+    "init",
+    "Set up canicode with Figma API token (never paste a token into agent chat \u2014 use FIGMA_TOKEN=\u2026 or the interactive prompt)"
+  ).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("--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) {
@@ -6947,103 +7319,57 @@ ${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;
       }
       console.log(`CANICODE SETUP
 `);
+      console.log(
+        `  Never paste your token into Claude/Cursor chat \u2014 use FIGMA_TOKEN=\u2026 npx canicode init or this prompt only.
+`
+      );
       console.log(`  canicode init --token YOUR_FIGMA_TOKEN`);
       console.log(`  Get token: figma.com > Settings > Personal access tokens
 `);
@@ -7051,8 +7377,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:`);
@@ -7151,6 +7476,164 @@ function registerListRules(cli2) {
     }
   });
 }
+var StepFourReportSchema = z.object({
+  /** ✅ — Strategy A property write (or A's auto-fix branch) succeeded. */
+  resolved: z.number().int().min(0),
+  /** 📝 — Strategy C wrote a Figma annotation (or A/B fell back to one). */
+  annotated: z.number().int().min(0),
+  /**
+   * 🌐 — `applyWithInstanceFallback` propagated the write up to the
+   * source COMPONENT definition (only counted when
+   * `allowDefinitionWrite: true`).
+   */
+  definitionWritten: z.number().int().min(0),
+  /**
+   * ⏭️ — User said "skip", "n/a", or otherwise declined a per-question
+   * confirmation (Strategy B opt-out, etc.).
+   */
+  skipped: z.number().int().min(0)
+});
+var ReanalyzeForTallySchema = z.object({
+  /**
+   * Total remaining issues from the re-analyze. Maps to the existing
+   * `issueCount` (analyze JSON) / `questions.length` (gotcha-survey JSON)
+   * field — both downstream channels populate it.
+   */
+  issueCount: z.number().int().min(0),
+  /**
+   * Issues the re-analyze flagged with `acknowledged: true` because they
+   * matched a canicode-authored Figma annotation harvested in Step 5a.
+   * From the analyze response's top-level `acknowledgedCount` (#371).
+   */
+  acknowledgedCount: z.number().int().min(0)
+});
+z.object({
+  /** ✅ resolved (passthrough from `stepFourReport.resolved`). */
+  X: z.number().int().min(0),
+  /** 📝 annotated. */
+  Y: z.number().int().min(0),
+  /** 🌐 definition writes propagated. */
+  Z: z.number().int().min(0),
+  /** ⏭️ skipped. */
+  W: z.number().int().min(0),
+  /** `X + Y + Z + W` — questions the SKILL acted on in Step 4. */
+  N: z.number().int().min(0),
+  /** `reanalyzeResponse.issueCount` — total remaining after re-analyze. */
+  V: z.number().int().min(0),
+  /**
+   * `reanalyzeResponse.acknowledgedCount` — the slice of `V` that carries
+   * a canicode annotation (counted at half weight by the density score
+   * per #371, but still surfaced as remaining).
+   */
+  V_ack: z.number().int().min(0),
+  /** `V - V_ack` — issues with no annotation; the user's follow-up backlog. */
+  V_open: z.number().int().min(0)
+});
+
+// src/core/roundtrip/compute-roundtrip-tally.ts
+function computeRoundtripTally(args) {
+  const { stepFourReport, reanalyzeResponse } = args;
+  const { resolved, annotated, definitionWritten, skipped } = stepFourReport;
+  const { issueCount, acknowledgedCount } = reanalyzeResponse;
+  if (acknowledgedCount > issueCount) {
+    throw new Error(
+      `computeRoundtripTally: reanalyzeResponse.acknowledgedCount (${acknowledgedCount}) cannot exceed issueCount (${issueCount}). Acknowledged issues are a subset of remaining issues.`
+    );
+  }
+  return {
+    X: resolved,
+    Y: annotated,
+    Z: definitionWritten,
+    W: skipped,
+    N: resolved + annotated + definitionWritten + skipped,
+    V: issueCount,
+    V_ack: acknowledgedCount,
+    V_open: issueCount - acknowledgedCount
+  };
+}
+
+// src/cli/commands/roundtrip-tally.ts
+var RoundtripTallyCliOptionsSchema = z.object({
+  analyze: z.string().min(1),
+  step4: z.string().min(1)
+});
+function parseJsonFile(label, path, raw) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `roundtrip-tally: ${label} is not valid JSON (${path})`,
+      { cause: err }
+    );
+  }
+}
+async function readUtf8File(label, path) {
+  try {
+    return await readFile(path, "utf-8");
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`roundtrip-tally: cannot read ${label} (${path}): ${detail}`, {
+      cause: err
+    });
+  }
+}
+async function computeRoundtripTallyFromSavedFiles(args) {
+  const [analyzeRaw, step4Raw] = await Promise.all([
+    readUtf8File("--analyze", args.analyzePath),
+    readUtf8File("--step4", args.step4Path)
+  ]);
+  const analyzeParsed = parseJsonFile("--analyze", args.analyzePath, analyzeRaw);
+  const step4Parsed = parseJsonFile("--step4", args.step4Path, step4Raw);
+  const reanalyzeResult = ReanalyzeForTallySchema.safeParse(analyzeParsed);
+  if (!reanalyzeResult.success) {
+    const msg = reanalyzeResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(
+      `roundtrip-tally: --analyze must include issueCount and acknowledgedCount (${args.analyzePath}): ${msg}`
+    );
+  }
+  const stepFourResult = StepFourReportSchema.safeParse(step4Parsed);
+  if (!stepFourResult.success) {
+    const msg = stepFourResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(
+      `roundtrip-tally: --step4 must match StepFourReport (${args.step4Path}): ${msg}`
+    );
+  }
+  return computeRoundtripTally({
+    stepFourReport: stepFourResult.data,
+    reanalyzeResponse: reanalyzeResult.data
+  });
+}
+function registerRoundtripTally(cli2) {
+  cli2.command(
+    "roundtrip-tally",
+    "Print the Step 5 roundtrip tally from re-analyze JSON and Step 4 outcome counts"
+  ).option("--analyze <path>", "Path to re-analyze JSON (`canicode analyze --json` output)").option("--step4 <path>", "Path to Step 4 structured counts (resolved / annotated / definitionWritten / skipped)").example("  canicode roundtrip-tally --analyze ./reanalyze.json --step4 ./step4-report.json").action(async (rawOptions) => {
+    const parsed = RoundtripTallyCliOptionsSchema.safeParse(rawOptions);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
+      console.error(`
+roundtrip-tally requires --analyze and --step4:
+${msg}`);
+      process.exit(1);
+    }
+    try {
+      const tally = await computeRoundtripTallyFromSavedFiles({
+        analyzePath: parsed.data.analyze,
+        step4Path: parsed.data.step4
+      });
+      console.log(JSON.stringify(tally, null, 2));
+      trackEvent(EVENTS.ROUNDTRIP_TALLY);
+    } catch (err) {
+      if (err instanceof Error) {
+        trackError(err, { command: "roundtrip-tally" });
+        console.error(err.message);
+      } else {
+        console.error(err);
+      }
+      process.exit(1);
+    }
+  });
+}
 
 // src/cli/internal-commands.ts
 var INTERNAL_COMMANDS = [
@@ -8429,9 +8912,9 @@ function registerCalibrateEvaluate(cli2) {
       if (!existsSync(conversionPath)) {
         throw new Error(`Conversion file not found: ${conversionPath}`);
       }
-      const { readFile: readFile4 } = await import('fs/promises');
-      const analysisData = JSON.parse(await readFile4(analysisPath, "utf-8"));
-      const conversionData = JSON.parse(await readFile4(conversionPath, "utf-8"));
+      const { readFile: readFile5 } = await import('fs/promises');
+      const analysisData = JSON.parse(await readFile5(analysisPath, "utf-8"));
+      const conversionData = JSON.parse(await readFile5(conversionPath, "utf-8"));
       let fixtureName;
       if (options.runDir) {
         const dirName = resolve(options.runDir).split(/[/\\]/).pop() ?? "";
@@ -10289,6 +10772,7 @@ registerVisualCompare(cli);
 registerInit(cli);
 registerConfig(cli);
 registerListRules(cli);
+registerRoundtripTally(cli);
 registerCalibrateAnalyze(cli);
 registerCalibrateEvaluate(cli);
 registerCalibrateGapReport(cli);
@@ -10312,6 +10796,7 @@ cli.help((sections) => {
       section.body = section.body.split("\n").filter((line) => !INTERNAL_COMMANDS.some((cmd) => line.includes(cmd))).join("\n");
     }
   }
+  sections.splice(1, 0, { body: `  ${pkg2.description}` });
   sections.push(
     {
       title: "\nSetup",
@@ -10319,10 +10804,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",
@@ -10331,10 +10813,10 @@ 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`
+        `  $ canicode gotcha-survey "https://www.figma.com/design/..." --json`,
+        `  $ canicode roundtrip-tally --analyze ./reanalyze.json --step4 ./step4.json`
       ].join("\n")
     },
     {