canicode 0.10.5 → 0.11.0

package/dist/cli/index.js

@@ -1777,6 +1777,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 +1839,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 +1891,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 +1974,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 +2030,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 +2089,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 +2149,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 +2289,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 +2355,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 +2661,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 +2955,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"];
@@ -3428,6 +3528,11 @@ 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 +3584,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 +3597,7 @@ var RuleEngine = class {
         (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
       )
     );
+    this.scopeOverride = options.scope;
   }
   /**
    * Analyze a Figma file and return issues
@@ -3507,6 +3614,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 +3631,8 @@ var RuleEngine = class {
       [],
       0,
       analysisState,
+      scope,
+      rootNodeType,
       void 0,
       void 0
     );
@@ -3539,7 +3650,8 @@ var RuleEngine = class {
       failedRules,
       maxDepth,
       nodeCount,
-      analyzedAt: (/* @__PURE__ */ new Date()).toISOString()
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      scope
     };
   }
   /**
@@ -3557,7 +3669,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 +3688,9 @@ var RuleEngine = class {
       path: nodePath,
       ancestorTypes,
       siblings,
-      analysisState
+      analysisState,
+      scope,
+      rootNodeType
     };
     for (const rule of rules) {
       const ruleId = rule.definition.id;
@@ -3623,6 +3737,8 @@ var RuleEngine = class {
           childAncestorTypes,
           currentComponentDepth + 1,
           analysisState,
+          scope,
+          rootNodeType,
           node,
           node.children
         );
@@ -4056,7 +4172,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.10.5";
+var version2 = "0.11.0";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -4250,6 +4366,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 +4392,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 +5656,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) 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) => {
     const parseResult = AnalyzeOptionsSchema.safeParse(rawOptions);
     if (!parseResult.success) {
       const msg = parseResult.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
@@ -5625,7 +5747,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 +5816,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 +5927,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 +6006,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 +6057,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 +6084,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 +6175,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 +6188,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 +6207,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");
@@ -6431,6 +6582,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 +6741,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 +6869,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,12 +6879,24 @@ 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)"
+      ].join("\n");
+    }
     return [
       "",
       "  Next:",
@@ -6577,6 +6904,15 @@ function formatNextSteps(opts) {
       "    2. Run /canicode-roundtrip <figma-url>"
     ].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"
+    ].join("\n");
+  }
   return [
     "",
     "  Next:",
@@ -6591,10 +6927,12 @@ var InitOptionsSchema = z.object({
   global: z.boolean().optional(),
   // cac maps `--no-skills` to `skills: false` (mirrors `--no-telemetry`).
   skills: z.boolean().optional(),
+  /** Install `skills/cursor/*` into `.cursor/skills/` (canicode, gotchas, roundtrip — issue #407). */
+  cursorSkills: z.boolean().optional(),
   force: z.boolean().optional()
 });
 function 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").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) => {
     try {
       const parseResult = InitOptionsSchema.safeParse(rawOptions);
       if (!parseResult.success) {
@@ -6638,9 +6976,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 +7035,8 @@ ${msg}`);
           console.log(
             formatNextSteps({
               figmaMcpPresent: figmaMcpRegistered(),
-              skillsInstalled: options.skills !== false
+              skillsInstalled: options.skills !== false,
+              cursorSkillsInstalled: options.cursorSkills === true
             })
           );
         }
@@ -6666,6 +7052,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:`);
@@ -6871,7 +7258,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 +8228,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 +8352,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 +8361,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 +8377,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,