canicode 0.11.0 → 0.11.1

package/dist/cli/index.js

@@ -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
@@ -1556,6 +1566,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)
@@ -1575,6 +1587,35 @@ 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/
+    --no-skills       Skip Claude Code skills (with --cursor-skills, still installs
+                      the Cursor bundle plus the shared gotchas answer file)
+    --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
+
+  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 +1631,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 +3562,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 +4232,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.11.0";
+var version2 = "0.11.1";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -5660,7 +5720,7 @@ 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", "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) => {
     const parseResult = AnalyzeOptionsSchema.safeParse(rawOptions);
     if (!parseResult.success) {
       const msg = parseResult.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
@@ -6260,6 +6320,221 @@ ${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(),
+  /**
+   * `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.
+   */
+  batchable: z.boolean(),
+  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()
+});
+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 +6651,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 +6683,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 +6727,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 +6737,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 +6749,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) {
@@ -6894,14 +7217,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 +7235,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 +7245,29 @@ 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`).
+  // 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 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("--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) => {
     try {
       const parseResult = InitOptionsSchema.safeParse(rawOptions);
       if (!parseResult.success) {
@@ -7044,6 +7379,10 @@ ${msg}`);
       }
       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
 `);
@@ -7151,6 +7490,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 +8926,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 +10786,7 @@ registerVisualCompare(cli);
 registerInit(cli);
 registerConfig(cli);
 registerListRules(cli);
+registerRoundtripTally(cli);
 registerCalibrateAnalyze(cli);
 registerCalibrateEvaluate(cli);
 registerCalibrateGapReport(cli);
@@ -10312,6 +10810,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",
@@ -10334,7 +10833,8 @@ cli.help((sections) => {
         `  $ 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")
     },
     {