canicode 0.10.5 → 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
@@ -1777,6 +1819,41 @@ var RULE_ID_CATEGORY = {
   "non-semantic-name": "semantic",
   "inconsistent-naming-convention": "semantic"
 };
+var RULE_PURPOSE = {
+  // Pixel Critical
+  "no-auto-layout": "violation",
+  "absolute-position-in-auto-layout": "violation",
+  "non-layout-container": "violation",
+  // Responsive Critical
+  "fixed-size-in-auto-layout": "violation",
+  // #403: missing-size-constraint reframed as info-collection. The rule
+  // fires on width chains whose intent is structurally undecidable
+  // (FILL container with no chain-bound ancestor; FIXED component or
+  // instance root). The gotcha question is the primary signal; the
+  // -1 score is just enough to keep the rule visible in
+  // diversity scoring without driving grade swings on its own.
+  "missing-size-constraint": "info-collection",
+  // Code Quality
+  "missing-component": "violation",
+  "detached-instance": "violation",
+  "variant-structure-mismatch": "violation",
+  "deep-nesting": "violation",
+  // Token Management
+  "raw-value": "violation",
+  "irregular-spacing": "violation",
+  // Interaction — gotcha-primary: Figma cannot encode "what happens on
+  // click" or "which states exist" in a way downstream code generation can
+  // consume. Rules fire to trigger the annotation, not to flag a violation.
+  "missing-interaction-state": "info-collection",
+  "missing-prototype": "info-collection",
+  // Semantic
+  "non-standard-naming": "violation",
+  "non-semantic-name": "violation",
+  "inconsistent-naming-convention": "violation"
+};
+function getRulePurpose(ruleId) {
+  return RULE_PURPOSE[ruleId] ?? "violation";
+}
 var RULE_CONFIGS = {
   // ── Pixel Critical ──
   "no-auto-layout": {
@@ -1804,8 +1881,12 @@ var RULE_CONFIGS = {
     enabled: true
   },
   "missing-size-constraint": {
-    severity: "risk",
-    score: -8,
+    // #403: severity downgraded `risk → missing-info` and score from
+    // -8 → -1 to match the new info-collection purpose. Keeping the
+    // rule enabled (not disabled) so its gotchas still surface in the
+    // survey — see RULE_PURPOSE entry above for the full rationale.
+    severity: "missing-info",
+    score: -1,
     enabled: true
   },
   // ── Code Quality ──
@@ -1852,17 +1933,22 @@ var RULE_CONFIGS = {
     }
   },
   // ── Interaction ──
+  // #406: both rules are `info-collection` — primary output is the gotcha
+  // annotation, not the score. Severity is `missing-info` so they surface in
+  // the gotcha survey (see `generateGotchaSurvey`) even though the penalty
+  // is minimal. Score stays at -1 so re-enabling `missing-prototype` on
+  // fixtures that lack `interactionDestinations` (#139) cannot swing grades.
   "missing-interaction-state": {
-    severity: "suggestion",
+    severity: "missing-info",
     score: -1,
     // uncalibrated: no metric to validate score (#210), kept at -1 to preserve category visibility
     enabled: true
   },
   "missing-prototype": {
     severity: "missing-info",
-    score: -3,
-    enabled: false
-    // disabled: interactionDestinations data missing from fixtures (#139)
+    score: -1,
+    // #406: info-collection — annotation is primary output; score kept minimal so #139 fixtures don't skew calibration
+    enabled: true
   },
   // ── Semantic ──
   "non-standard-naming": {
@@ -1930,7 +2016,11 @@ function getConfigsWithPreset(preset) {
 }
 var RULE_ANNOTATION_PROPERTIES = {
   "missing-size-constraint": {
-    default: [{ type: "width" }, { type: "height" }]
+    // #403: width-only — the redesigned rule does not evaluate the
+    // height axis (deferred follow-up). Emitting a `height` annotation
+    // here would mark properties the rule never inspected and confuse
+    // downstream Dev Mode hints.
+    default: [{ type: "width" }]
   },
   "irregular-spacing": {
     bySubType: {
@@ -1982,6 +2072,14 @@ var RuleRegistry = class {
   register(rule) {
     this.rules.set(rule.definition.id, rule);
   }
+  /**
+   * Remove a rule by ID. Primarily used by tests that register a
+   * throwaway rule and need to restore the registry afterwards. Returns
+   * `true` if the rule was present.
+   */
+  unregister(id) {
+    return this.rules.delete(id);
+  }
   /**
    * Get a rule by ID
    */
@@ -2033,6 +2131,58 @@ function defineRule(rule) {
   ruleRegistry.register(rule);
   return rule;
 }
+var CategorySchema = z.enum([
+  "pixel-critical",
+  "responsive-critical",
+  "code-quality",
+  "token-management",
+  "semantic",
+  "interaction"
+]);
+var CATEGORIES = CategorySchema.options;
+var CATEGORY_LABELS = {
+  "pixel-critical": "Pixel Critical",
+  "responsive-critical": "Responsive Critical",
+  "code-quality": "Code Quality",
+  "token-management": "Token Management",
+  "semantic": "Semantic",
+  "interaction": "Interaction"
+};
+var SeveritySchema = z.enum([
+  "blocking",
+  "risk",
+  "missing-info",
+  "suggestion"
+]);
+
+// src/core/contracts/rule.ts
+z.object({
+  id: z.string(),
+  name: z.string(),
+  category: CategorySchema,
+  why: z.string(),
+  impact: z.string(),
+  fix: z.string()
+});
+z.object({
+  severity: SeveritySchema,
+  score: z.number().int().max(0),
+  depthWeight: z.number().min(1).max(2).optional(),
+  enabled: z.boolean().default(true),
+  options: z.record(z.string(), z.unknown()).optional()
+});
+function getAnalysisState(context, key, init) {
+  if (context.analysisState.has(key)) {
+    return context.analysisState.get(key);
+  }
+  const value = init();
+  context.analysisState.set(key, value);
+  return value;
+}
+var DEPTH_WEIGHT_CATEGORIES = ["pixel-critical", "responsive-critical"];
+function supportsDepthWeight(category) {
+  return DEPTH_WEIGHT_CATEGORIES.includes(category);
+}
 
 // src/core/rules/node-semantics.ts
 function isContainerNode(node) {
@@ -2041,9 +2191,6 @@ function isContainerNode(node) {
 function hasAutoLayout(node) {
   return node.layoutMode !== void 0 && node.layoutMode !== "NONE";
 }
-function hasTextContent(node) {
-  return node.type === "TEXT" || (node.children?.some((c) => c.type === "TEXT") ?? false);
-}
 function hasOverlappingBounds(a, b) {
   const boxA = a.absoluteBoundingBox;
   const boxB = b.absoluteBoundingBox;
@@ -2184,12 +2331,6 @@ function isAbsolutePositionExempt(node) {
   if (isExcludedName(node.name)) return true;
   return false;
 }
-function isSizeConstraintExempt(node, context) {
-  if (node.maxWidth !== void 0) return true;
-  if (context.parent?.maxWidth !== void 0) return true;
-  if (context.depth <= 1) return true;
-  return false;
-}
 function isFixedSizeExempt(node) {
   if (isVisualOnlyNode(node)) return true;
   if (isExcludedName(node.name)) return true;
@@ -2256,21 +2397,21 @@ var fixedSizeMsg = {
   })
 };
 var missingSizeConstraintMsg = {
-  maxWidth: (name, currentWidth) => ({
-    message: `"${name}" uses FILL width (currently ${currentWidth}) without max-width`,
-    suggestion: `Add maxWidth to prevent stretching on large screens`
+  pageContainerUnbound: (name, currentWidth) => ({
+    message: `Container "${name}" uses FILL width (currently ${currentWidth}) and no ancestor defines a width bound`,
+    suggestion: `Decide whether this area should stretch with the screen, or set min/max-width here so the responsive behavior is explicit`
   }),
-  minWidth: (name, currentWidth) => ({
-    message: `"${name}" uses FILL width (currently ${currentWidth}) without min-width`,
-    suggestion: `Add minWidth to prevent collapsing on small screens`
+  pageInstanceFixed: (name, currentWidth) => ({
+    message: `Instance "${name}" has fixed width (${currentWidth}) inside an Auto Layout parent`,
+    suggestion: `Confirm whether this fixed width is intentional \u2014 if not, set the instance to FILL so it follows the parent's layout`
   }),
-  wrap: (name) => ({
-    message: `"${name}" is in a wrap container without min-width`,
-    suggestion: `Add minWidth to control when wrapping occurs`
+  componentFixedByDesign: (name, currentWidth) => ({
+    message: `Component "${name}" has fixed width (${currentWidth}) at its root`,
+    suggestion: `Confirm whether this component is intentionally non-responsive \u2014 otherwise switch root sizing to FILL or set min/max bounds`
   }),
-  grid: (name) => ({
-    message: `"${name}" is in a grid layout without size constraints`,
-    suggestion: `Add min/max-width for proper column sizing`
+  componentFixedByOverride: (name, currentWidth) => ({
+    message: `Instance "${name}" overrides root width to fixed (${currentWidth}); the original component may be FILL`,
+    suggestion: `Confirm whether the fixed-width override is intentional \u2014 if not, restore root sizing to inherit from the component definition`
   })
 };
 var nonLayoutContainerMsg = {
@@ -2562,44 +2703,97 @@ var missingSizeConstraintDef = {
   id: "missing-size-constraint",
   name: "Missing Size Constraint",
   category: "responsive-critical",
-  why: "Without min/max-width, AI has no bounds \u2014 generated code may collapse or stretch indefinitely",
-  impact: "Content becomes unreadable or invisible at extreme screen sizes",
-  fix: "Set min-width and/or max-width so AI can generate proper size constraints"
+  why: "Width sizing without explicit bounds (FIXED root or FILL chained to a bounded ancestor) is structurally indistinguishable from missing information \u2014 AI cannot tell whether the designer intended responsive stretching, a fixed cap, or simply forgot to set min/max",
+  impact: "Generated code either guesses hard-coded widths or omits responsive constraints; either way the runtime layout drifts from the design intent at viewports the designer never explicitly considered",
+  fix: "Answer the gotcha to declare intent (responsive vs. fixed-by-design vs. instance override), then encode the answer in Figma sizing \u2014 FILL/HUG with min/max for responsive bounds, FIXED only when intentionally non-responsive"
 };
-var missingSizeConstraintCheck = (node, context) => {
-  if (!isContainerNode(node) && !hasTextContent(node)) return null;
-  if (!context.parent || !hasAutoLayout(context.parent)) return null;
-  const nodePath = context.path.join(" > ");
-  if (context.parent.layoutWrap === "WRAP" && node.layoutSizingHorizontal === "FILL" && node.minWidth === void 0) {
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "wrap",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.wrap(node.name)
-    };
-  }
-  if (context.parent.layoutMode === "GRID" && node.layoutSizingHorizontal === "FILL" && node.minWidth === void 0 && node.maxWidth === void 0) {
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "grid",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.grid(node.name)
-    };
+var CHAIN_BOUND_KEY = "missing-size-constraint:chain-bound";
+function getChainBoundCache(context) {
+  return getAnalysisState(context, CHAIN_BOUND_KEY, () => /* @__PURE__ */ new Map());
+}
+function establishesOwnWidthBound(node) {
+  if (node.layoutSizingHorizontal === "FIXED") return true;
+  if (node.minWidth !== void 0 || node.maxWidth !== void 0) return true;
+  return false;
+}
+function recordChainBound(context, node) {
+  const cache = getChainBoundCache(context);
+  const cached = cache.get(node.id);
+  if (cached !== void 0) return cached;
+  const own = establishesOwnWidthBound(node);
+  const parent = context.parent;
+  const inherited = parent ? cache.get(parent.id) ?? false : false;
+  const result = own || inherited;
+  cache.set(node.id, result);
+  return result;
+}
+function parentChainBound(context) {
+  if (!context.parent) return false;
+  return getChainBoundCache(context).get(context.parent.id) ?? false;
+}
+var PAGE_CONTAINER_FRAME_TYPES = /* @__PURE__ */ new Set(["FRAME", "SECTION"]);
+function formatWidth(node) {
+  return node.absoluteBoundingBox ? `${node.absoluteBoundingBox.width}px` : "unknown";
+}
+function buildViolation(subType, node, context, msg) {
+  return {
+    ruleId: missingSizeConstraintDef.id,
+    subType,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    ...msg
+  };
+}
+function checkComponentScopeRoot(node, context) {
+  if (context.depth !== 0) return null;
+  if (node.layoutSizingHorizontal !== "FIXED") return null;
+  const currentWidth = formatWidth(node);
+  if (context.rootNodeType === "INSTANCE") {
+    return buildViolation(
+      "component-fixed-by-override",
+      node,
+      context,
+      missingSizeConstraintMsg.componentFixedByOverride(node.name, currentWidth)
+    );
   }
-  if (node.layoutSizingHorizontal === "FILL") {
-    if (isSizeConstraintExempt(node, context)) return null;
-    const currentWidth = node.absoluteBoundingBox ? `${node.absoluteBoundingBox.width}px` : "unknown";
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "max-width",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.maxWidth(node.name, currentWidth)
-    };
+  return buildViolation(
+    "component-fixed-by-design",
+    node,
+    context,
+    missingSizeConstraintMsg.componentFixedByDesign(node.name, currentWidth)
+  );
+}
+function checkPageInstanceFixed(node, context) {
+  if (node.type !== "INSTANCE") return null;
+  if (node.layoutSizingHorizontal !== "FIXED") return null;
+  if (!context.parent || !hasAutoLayout(context.parent)) return null;
+  const currentWidth = formatWidth(node);
+  return buildViolation(
+    "page-instance-fixed",
+    node,
+    context,
+    missingSizeConstraintMsg.pageInstanceFixed(node.name, currentWidth)
+  );
+}
+function checkPageContainerUnbound(node, context) {
+  if (!PAGE_CONTAINER_FRAME_TYPES.has(node.type)) return null;
+  if (node.layoutSizingHorizontal !== "FILL") return null;
+  if (parentChainBound(context)) return null;
+  const currentWidth = formatWidth(node);
+  return buildViolation(
+    "page-container-unbound",
+    node,
+    context,
+    missingSizeConstraintMsg.pageContainerUnbound(node.name, currentWidth)
+  );
+}
+var missingSizeConstraintCheck = (node, context) => {
+  recordChainBound(context, node);
+  if (context.ancestorTypes.includes("INSTANCE")) return null;
+  if (context.scope === "component") {
+    return checkComponentScopeRoot(node, context);
   }
-  return null;
+  return checkPageInstanceFixed(node, context) ?? checkPageContainerUnbound(node, context);
 };
 defineRule({
   definition: missingSizeConstraintDef,
@@ -2803,58 +2997,6 @@ defineRule({
   definition: irregularSpacingDef,
   check: irregularSpacingCheck
 });
-var CategorySchema = z.enum([
-  "pixel-critical",
-  "responsive-critical",
-  "code-quality",
-  "token-management",
-  "semantic",
-  "interaction"
-]);
-var CATEGORIES = CategorySchema.options;
-var CATEGORY_LABELS = {
-  "pixel-critical": "Pixel Critical",
-  "responsive-critical": "Responsive Critical",
-  "code-quality": "Code Quality",
-  "token-management": "Token Management",
-  "semantic": "Semantic",
-  "interaction": "Interaction"
-};
-var SeveritySchema = z.enum([
-  "blocking",
-  "risk",
-  "missing-info",
-  "suggestion"
-]);
-
-// src/core/contracts/rule.ts
-z.object({
-  id: z.string(),
-  name: z.string(),
-  category: CategorySchema,
-  why: z.string(),
-  impact: z.string(),
-  fix: z.string()
-});
-z.object({
-  severity: SeveritySchema,
-  score: z.number().int().max(0),
-  depthWeight: z.number().min(1).max(2).optional(),
-  enabled: z.boolean().default(true),
-  options: z.record(z.string(), z.unknown()).optional()
-});
-function getAnalysisState(context, key, init) {
-  if (context.analysisState.has(key)) {
-    return context.analysisState.get(key);
-  }
-  const value = init();
-  context.analysisState.set(key, value);
-  return value;
-}
-var DEPTH_WEIGHT_CATEGORIES = ["pixel-critical", "responsive-critical"];
-function supportsDepthWeight(category) {
-  return DEPTH_WEIGHT_CATEGORIES.includes(category);
-}
 
 // src/core/rules/component/index.ts
 var STYLE_COMPARE_KEYS = ["fills", "strokes", "effects", "cornerRadius", "strokeWeight", "individualStrokeWeights"];
@@ -3420,14 +3562,37 @@ 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) {
   return id.replace(/-/g, ":");
 }
+var AnalysisScopeSchema = z.enum(["page", "component"]);
+var COMPONENT_SCOPE_ROOT_TYPES = /* @__PURE__ */ new Set(["COMPONENT", "COMPONENT_SET", "INSTANCE"]);
+function detectAnalysisScope(rootNode) {
+  return COMPONENT_SCOPE_ROOT_TYPES.has(rootNode.type) ? "component" : "page";
+}
 
 // src/core/engine/rule-engine.ts
 function calculateMaxDepth(node, currentDepth = 0) {
@@ -3479,6 +3644,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
     this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
@@ -3491,6 +3657,7 @@ var RuleEngine = class {
         (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
       )
     );
+    this.scopeOverride = options.scope;
   }
   /**
    * Analyze a Figma file and return issues
@@ -3507,6 +3674,8 @@ var RuleEngine = class {
     }
     const maxDepth = calculateMaxDepth(rootNode);
     const nodeCount = countNodes(rootNode);
+    const scope = this.scopeOverride ?? detectAnalysisScope(rootNode);
+    const rootNodeType = rootNode.type;
     const issues = [];
     const failedRules = [];
     const enabledRules = this.getEnabledRules();
@@ -3522,6 +3691,8 @@ var RuleEngine = class {
       [],
       0,
       analysisState,
+      scope,
+      rootNodeType,
       void 0,
       void 0
     );
@@ -3539,7 +3710,8 @@ var RuleEngine = class {
       failedRules,
       maxDepth,
       nodeCount,
-      analyzedAt: (/* @__PURE__ */ new Date()).toISOString()
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      scope
     };
   }
   /**
@@ -3557,7 +3729,7 @@ var RuleEngine = class {
   /**
    * Recursively traverse the tree and run rules
    */
-  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, parent, siblings) {
+  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, scope, rootNodeType, parent, siblings) {
     const nodePath = [...path, node.name];
     const isComponentBoundary = node.type === "COMPONENT" || node.type === "COMPONENT_SET" || node.type === "INSTANCE";
     const currentComponentDepth = isComponentBoundary ? 0 : componentDepth;
@@ -3576,7 +3748,9 @@ var RuleEngine = class {
       path: nodePath,
       ancestorTypes,
       siblings,
-      analysisState
+      analysisState,
+      scope,
+      rootNodeType
     };
     for (const rule of rules) {
       const ruleId = rule.definition.id;
@@ -3623,6 +3797,8 @@ var RuleEngine = class {
           childAncestorTypes,
           currentComponentDepth + 1,
           analysisState,
+          scope,
+          rootNodeType,
           node,
           node.children
         );
@@ -4056,7 +4232,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.10.5";
+var version2 = "0.11.1";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -4250,6 +4426,10 @@ function buildResultJson(fileName, result, scores, options) {
     const suggestedName = issue.violation.suggestedName;
     return {
       ruleId: issue.violation.ruleId,
+      detection: "rule-based",
+      outputChannel: "score",
+      persistenceIntent: "transient",
+      purpose: getRulePurpose(issue.violation.ruleId),
       ...issue.violation.subType && { subType: issue.violation.subType },
       severity: issue.config.severity,
       nodeId: issue.violation.nodeId,
@@ -4272,6 +4452,7 @@ function buildResultJson(fileName, result, scores, options) {
     fileName,
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
+    scope: result.scope,
     issueCount: result.issues.length,
     acknowledgedCount: scores.summary.acknowledgedCount,
     isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
@@ -5535,10 +5716,11 @@ var AnalyzeOptionsSchema = z.object({
   config: z.string().optional(),
   noOpen: z.boolean().optional(),
   json: z.boolean().optional(),
-  acknowledgments: z.string().optional()
+  acknowledgments: z.string().optional(),
+  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.").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");
@@ -5625,7 +5807,8 @@ Analyzing: ${file.name}`);
         ...effectiveNodeId && { targetNodeId: effectiveNodeId },
         ...excludeNodeNames && { excludeNodeNames },
         ...excludeNodeTypes && { excludeNodeTypes },
-        ...acknowledgments && { acknowledgments }
+        ...acknowledgments && { acknowledgments },
+        ...options.scope && { scope: options.scope }
       };
       const result = analyzeFile(file, analyzeOptions);
       log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
@@ -5693,11 +5876,14 @@ Report saved: ${outputPath}`);
 }
 z.object({
   ruleId: z.string(),
+  detection: z.literal("rule-based"),
+  outputChannel: z.literal("annotation"),
+  persistenceIntent: z.literal("durable"),
   question: z.string(),
   hint: z.string(),
   example: z.string()
 });
-var GOTCHA_QUESTIONS = {
+var GOTCHA_QUESTION_CONTENT = {
   // ── Pixel Critical (blocking) ──
   "no-auto-layout": {
     ruleId: "no-auto-layout",
@@ -5801,6 +5987,17 @@ var GOTCHA_QUESTIONS = {
     example: "Use PascalCase for all component layers (e.g., CardTitle, CardBody)"
   }
 };
+var GOTCHA_QUESTIONS = Object.fromEntries(
+  Object.entries(GOTCHA_QUESTION_CONTENT).map(([ruleId, content]) => [
+    ruleId,
+    {
+      ...content,
+      detection: "rule-based",
+      outputChannel: "annotation",
+      persistenceIntent: "durable"
+    }
+  ])
+);
 
 // src/core/gotcha/group-and-batch-questions.ts
 var BATCHABLE_RULE_IDS = [
@@ -5869,9 +6066,14 @@ function pushIntoBatch(group, question) {
 var NODE_PATH_SEPARATOR = " > ";
 function generateGotchaSurvey(result, scores, options = {}) {
   const grade = scores.overall.grade;
-  const relevantIssues = result.issues.filter(
-    (issue) => issue.config.severity === "blocking" || issue.config.severity === "risk"
-  );
+  const relevantIssues = result.issues.filter((issue) => {
+    const severity = issue.config.severity;
+    if (severity === "blocking" || severity === "risk") return true;
+    if (severity === "missing-info") {
+      return getRulePurpose(issue.violation.ruleId) === "info-collection";
+    }
+    return false;
+  });
   const deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
   const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
@@ -5915,14 +6117,17 @@ function getNodeName(nodePath) {
 function stableSortBySeverity(issues) {
   const blocking = [];
   const risk = [];
+  const missingInfo = [];
   for (const issue of issues) {
     if (issue.config.severity === "blocking") {
       blocking.push(issue);
+    } else if (issue.config.severity === "missing-info") {
+      missingInfo.push(issue);
     } else {
       risk.push(issue);
     }
   }
-  return [...blocking, ...risk];
+  return [...blocking, ...risk, ...missingInfo];
 }
 function mapToQuestion(issue, file) {
   const ruleId = issue.violation.ruleId;
@@ -5939,6 +6144,10 @@ function mapToQuestion(issue, file) {
     nodeId: issue.violation.nodeId,
     nodeName,
     ruleId,
+    detection: template.detection,
+    outputChannel: template.outputChannel,
+    persistenceIntent: template.persistenceIntent,
+    purpose: getRulePurpose(issue.violation.ruleId),
     severity: issue.config.severity,
     question: template.question.replace("{nodeName}", nodeName),
     hint: template.hint,
@@ -6026,7 +6235,8 @@ var GotchaSurveyOptionsSchema = z.object({
   token: z.string().optional(),
   config: z.string().optional(),
   targetNodeId: z.string().optional(),
-  json: z.boolean().optional()
+  json: z.boolean().optional(),
+  scope: z.enum(["page", "component"]).optional()
 });
 async function runGotchaSurvey(input, options) {
   const { file, nodeId } = await loadFile(input, options.token);
@@ -6038,7 +6248,8 @@ async function runGotchaSurvey(input, options) {
   }
   const result = analyzeFile(file, {
     configs,
-    ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
+    ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
+    ...options.scope ? { scope: options.scope } : {}
   });
   const scores = calculateScores(result, configs);
   return generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });
@@ -6056,7 +6267,7 @@ 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("--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("--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");
@@ -6109,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",
@@ -6225,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.",
@@ -6241,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,
@@ -6255,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");
@@ -6264,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) {
@@ -6275,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) {
@@ -6431,6 +6905,100 @@ var SKILL_NAMES = ["canicode", "canicode-gotchas", "canicode-roundtrip"];
 function defaultSourceDir() {
   return fileURLToPath(new URL("../../skills/", import.meta.url));
 }
+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) {
+    mkdirSync(destSkillDir, { recursive: true });
+    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 installSkills(rawOptions) {
   const options = InstallSkillsOptionsSchema.parse(rawOptions);
   const sourceDir = options.sourceDir ?? defaultSourceDir();
@@ -6496,6 +7064,76 @@ 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(),
+  /** Defaults to bundled `skills/cursor/` (build output). */
+  sourceRoot: z.string().optional(),
+  /**
+   * Parent of per-skill dirs (defaults to `<cwd>/.cursor/skills`).
+   * Tests may use a non-`.cursor` path when the runner blocks hidden directories.
+   */
+  targetSkillsRoot: z.string().optional()
+});
+async function installCursorBundledSkills(rawOptions) {
+  const options = InstallCursorBundledSchema.parse(rawOptions);
+  const sourceRoot = options.sourceRoot ?? defaultCursorBundleRoot();
+  const cwd = options.cwd ?? process.cwd();
+  const targetDir = options.targetSkillsRoot ?? join(cwd, ".cursor", "skills");
+  if (!existsSync(sourceRoot)) {
+    throw new Error(
+      `Bundled Cursor skills directory not found: ${sourceRoot}
+If you are developing canicode, run 'pnpm build' first (bundle populates skills/cursor/).
+If you installed canicode from npm, please file a bug report \u2014 the tarball is missing skills/cursor/.`
+    );
+  }
+  mkdirSync(targetDir, { recursive: true });
+  const skillNames = readdirSync(sourceRoot).filter((name) => statSync(join(sourceRoot, name)).isDirectory()).sort();
+  if (skillNames.length === 0) {
+    throw new Error(`No skill directories under: ${sourceRoot}`);
+  }
+  const entries = skillNames.map((skillName) => ({
+    skillName,
+    srcSkillDir: join(sourceRoot, skillName),
+    destSkillDir: join(targetDir, skillName)
+  }));
+  const part = await copyMultipleSkillTrees(entries, options.force);
+  return {
+    installed: part.installed,
+    overwritten: part.overwritten,
+    skipped: part.skipped,
+    targetDir
+  };
+}
 function listFilesRecursive(dir) {
   const out = [];
   const walk = (current) => {
@@ -6554,9 +7192,9 @@ async function promptOverwriteBatch(candidates) {
 }
 
 // src/cli/commands/init.ts
-function figmaMcpRegistered(cwd = process.cwd()) {
+function figmaEntryInMcpFile(filePath) {
   try {
-    const raw = readFileSync(join(cwd, ".mcp.json"), "utf-8");
+    const raw = readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(raw);
     const figma = parsed?.mcpServers?.["figma"];
     return typeof figma === "object" && figma !== null;
@@ -6564,17 +7202,41 @@ function figmaMcpRegistered(cwd = process.cwd()) {
     return false;
   }
 }
+function figmaMcpRegistered(cwd = process.cwd()) {
+  return figmaEntryInMcpFile(join(cwd, ".mcp.json")) || figmaEntryInMcpFile(join(cwd, ".cursor", "mcp.json"));
+}
 function formatNextSteps(opts) {
   if (!opts.skillsInstalled) {
     return `
   Next: canicode analyze "https://www.figma.com/design/..."`;
   }
+  const cursor = opts.cursorSkillsInstalled === true;
   if (opts.figmaMcpPresent) {
+    if (cursor) {
+      return [
+        "",
+        "  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)",
+        "    \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) {
+    return [
+      "",
+      "  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",
+      "    \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 [
@@ -6583,18 +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("--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) {
@@ -6638,9 +7311,56 @@ ${msg}`);
             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;
+          }
         }
         trackEvent(EVENTS.CLI_INIT, {
           skillsRequested: options.skills !== false,
+          cursorSkillsRequested: options.cursorSkills === true,
           skillStepOk,
           target: options.global ? "global" : "project",
           force: options.force ?? false,
@@ -6650,7 +7370,8 @@ ${msg}`);
           console.log(
             formatNextSteps({
               figmaMcpPresent: figmaMcpRegistered(),
-              skillsInstalled: options.skills !== false
+              skillsInstalled: options.skills !== false,
+              cursorSkillsInstalled: options.cursorSkills === true
             })
           );
         }
@@ -6658,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
 `);
@@ -6666,6 +7391,7 @@ ${msg}`);
       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(`  --force        Overwrite existing skill files without prompting
 `);
       console.log(`After setup:`);
@@ -6764,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 = [
@@ -6871,7 +7755,16 @@ var CalibrationConfigSchema = z.object({
   maxConversionNodes: z.number().int().positive().default(20),
   samplingStrategy: SamplingStrategySchema.default("top-issues"),
   outputPath: z.string().default("logs/calibration/calibration-report.md"),
-  runDir: z.string().optional()
+  runDir: z.string().optional(),
+  /**
+   * #404: Explicit analysis scope for the calibration run. When omitted,
+   * the orchestrator (`scripts/calibrate.ts`) injects `"page"` as the
+   * policy default — `fixtures/done/*` are conceptually pages even though
+   * they are stored as `COMPONENT` variants ("Platform=Desktop" etc.) and
+   * would otherwise auto-detect as component scope. A `.scope` file in
+   * the fixture directory overrides the default per-fixture.
+   */
+  scope: AnalysisScopeSchema.optional()
 });
 
 // src/agents/analysis-agent.ts
@@ -7832,7 +8725,10 @@ function buildRuleScoresMap() {
 async function runCalibrationAnalyze(config2) {
   const parsed = CalibrationConfigSchema.parse(config2);
   const { file, fileKey, nodeId } = await loadFile2(parsed.input, parsed.token);
-  const analyzeOptions = nodeId ? { targetNodeId: nodeId } : {};
+  const analyzeOptions = {
+    ...nodeId ? { targetNodeId: nodeId } : {},
+    ...parsed.scope ? { scope: parsed.scope } : {}
+  };
   const analysisResult = analyzeFile(file, analyzeOptions);
   const analysisOutput = runAnalysisAgent({ analysisResult });
   const ruleScores = {
@@ -7953,7 +8849,7 @@ function registerCalibrateAnalyze(cli2) {
   cli2.command(
     "calibrate-analyze <input>",
     "Run calibration analysis and output JSON for conversion step"
-  ).option("--output <path>", "Output JSON path", { default: "logs/calibration/calibration-analysis.json" }).option("--run-dir <path>", "Run directory (overrides --output, writes to <run-dir>/analysis.json)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--target-node-id <nodeId>", "Scope analysis to a specific node").action(async (input, options) => {
+  ).option("--output <path>", "Output JSON path", { default: "logs/calibration/calibration-analysis.json" }).option("--run-dir <path>", "Run directory (overrides --output, writes to <run-dir>/analysis.json)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--target-node-id <nodeId>", "Scope analysis to a specific node").option("--scope <scope>", "(#404) Override analysis scope (`page` | `component`). Pass-through to the rule engine; `scripts/calibrate.ts` normally sets this to `page` for fixtures/done/* because they are conceptually pages packaged as COMPONENT variants.").action(async (input, options) => {
     try {
       console.log("Running calibration analysis...");
       const calibConfig = {
@@ -7962,7 +8858,8 @@ function registerCalibrateAnalyze(cli2) {
         samplingStrategy: "top-issues",
         outputPath: "logs/calibration/calibration-report.md",
         ...options.token && { token: options.token },
-        ...options.targetNodeId && { targetNodeId: options.targetNodeId }
+        ...options.targetNodeId && { targetNodeId: options.targetNodeId },
+        ...options.scope && { scope: options.scope }
       };
       const { analysisOutput, ruleScores, fileKey } = await runCalibrationAnalyze(calibConfig);
       const filteredSummaries = filterConversionCandidates(
@@ -7977,6 +8874,14 @@ function registerCalibrateAnalyze(cli2) {
         analyzedAt: analysisOutput.analysisResult.analyzedAt,
         nodeCount: analysisOutput.analysisResult.nodeCount,
         issueCount: analysisOutput.analysisResult.issues.length,
+        /**
+         * #404: Resolved analysis scope for this calibration run —
+         * surfaced in analysis.json so downstream diff/tuning agents
+         * and post-hoc grade comparisons can see whether a run used
+         * page or component scope (critical once #403 introduces
+         * scope-dependent rule behavior).
+         */
+        scope: analysisOutput.analysisResult.scope,
         calibrationTier,
         scoreReport: analysisOutput.scoreReport,
         nodeIssueSummaries: filteredSummaries,
@@ -8021,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() ?? "";
@@ -9881,6 +10786,7 @@ registerVisualCompare(cli);
 registerInit(cli);
 registerConfig(cli);
 registerListRules(cli);
+registerRoundtripTally(cli);
 registerCalibrateAnalyze(cli);
 registerCalibrateEvaluate(cli);
 registerCalibrateGapReport(cli);
@@ -9904,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",
@@ -9926,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")
     },
     {