canicode 0.10.2 → 0.10.4

package/dist/cli/index.js

@@ -9,7 +9,7 @@ import cac from 'cac';
 import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 import { z } from 'zod';
-import { writeFile, readFile } from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
 import { createInterface } from 'readline/promises';
 import { pathToFileURL, fileURLToPath } from 'url';
 
@@ -3191,6 +3191,7 @@ var inconsistentNamingConventionCheck = (node, context) => {
   if (nodeConvention && nodeConvention !== dominantConvention && maxCount >= 2) {
     if (isCompatible(nodeConvention, dominantConvention, node.name)) return null;
     const suggested = convertName(node.name, dominantConvention);
+    if (suggested === node.name) return null;
     return {
       ruleId: inconsistentNamingConventionDef.id,
       nodeId: node.id,
@@ -3286,6 +3287,15 @@ function hasStateInComponentMaster(node, context, statePattern) {
   if (!master) return false;
   return hasStateInVariantProps(master, statePattern);
 }
+function canDetermineVariants(node, context) {
+  if (node.type === "COMPONENT") return true;
+  if (node.componentPropertyDefinitions !== void 0) return true;
+  if (node.componentId !== void 0) {
+    const defs = context.file.componentDefinitions;
+    if (defs && defs[node.componentId] !== void 0) return true;
+  }
+  return false;
+}
 var missingInteractionStateDef = {
   id: "missing-interaction-state",
   name: "Missing Interaction State",
@@ -3300,6 +3310,7 @@ var missingInteractionStateCheck = (node, context) => {
   if (!interactiveType) return null;
   const expectedStates = EXPECTED_STATES[interactiveType];
   if (!expectedStates) return null;
+  if (!canDetermineVariants(node, context)) return null;
   const seen = getSeen(context);
   const nodePath = context.path.join(" > ");
   for (const state of expectedStates) {
@@ -3399,6 +3410,14 @@ defineRule({
   definition: missingPrototypeDef,
   check: missingPrototypeCheck
 });
+var AcknowledgmentSchema = z.object({
+  nodeId: z.string(),
+  ruleId: z.string()
+});
+var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
+function normalizeNodeId(id) {
+  return id.replace(/-/g, ":");
+}
 
 // src/core/engine/rule-engine.ts
 function calculateMaxDepth(node, currentDepth = 0) {
@@ -3449,6 +3468,7 @@ var RuleEngine = class {
   targetNodeId;
   excludeNamePattern;
   excludeNodeTypes;
+  acknowledgments;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
     this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
@@ -3456,6 +3476,11 @@ var RuleEngine = class {
     this.targetNodeId = options.targetNodeId;
     this.excludeNamePattern = options.excludeNodeNames && options.excludeNodeNames.length > 0 ? new RegExp(`\\b(${options.excludeNodeNames.join("|")})\\b`, "i") : null;
     this.excludeNodeTypes = options.excludeNodeTypes && options.excludeNodeTypes.length > 0 ? new Set(options.excludeNodeTypes) : null;
+    this.acknowledgments = new Set(
+      (options.acknowledgments ?? []).map(
+        (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
+      )
+    );
   }
   /**
    * Analyze a Figma file and return issues
@@ -3490,6 +3515,14 @@ var RuleEngine = class {
       void 0,
       void 0
     );
+    if (this.acknowledgments.size > 0) {
+      for (const issue of issues) {
+        const key = `${normalizeNodeId(issue.violation.nodeId)}::${issue.violation.ruleId}`;
+        if (this.acknowledgments.has(key)) {
+          issue.acknowledged = true;
+        }
+      }
+    }
     return {
       file,
       issues,
@@ -3970,8 +4003,6 @@ function resolveTargetProperty(ruleId, subType) {
       if (subType === "horizontal") return "layoutSizingHorizontal";
       return ["layoutSizingHorizontal", "layoutSizingVertical"];
     case "missing-size-constraint":
-      if (subType === "wrap") return "minWidth";
-      if (subType === "max-width") return "maxWidth";
       return ["minWidth", "maxWidth"];
     case "irregular-spacing":
       if (subType === "gap") return "itemSpacing";
@@ -4015,7 +4046,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.10.2";
+var version2 = "0.10.4";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -4071,7 +4102,8 @@ function calculateScores(result, configs) {
     uniqueRulesPerCategory.get(category).add(ruleId);
     ruleScorePerCategory.get(category).set(ruleId, Math.abs(issue.config.score));
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
-    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + 1);
+    const weight = issue.acknowledged === true ? 0.5 : 1;
+    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + weight);
   }
   for (const category of CATEGORIES) {
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
@@ -4118,7 +4150,8 @@ function calculateScores(result, configs) {
     risk: 0,
     missingInfo: 0,
     suggestion: 0,
-    nodeCount
+    nodeCount,
+    acknowledgedCount: 0
   };
   for (const issue of result.issues) {
     switch (issue.config.severity) {
@@ -4135,6 +4168,7 @@ function calculateScores(result, configs) {
         summary.suggestion++;
         break;
     }
+    if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
   return {
     overall: {
@@ -4185,7 +4219,14 @@ function formatScoreSummary(report) {
   lines.push(`  Risk: ${report.summary.risk}`);
   lines.push(`  Missing Info: ${report.summary.missingInfo}`);
   lines.push(`  Suggestion: ${report.summary.suggestion}`);
-  lines.push(`  Total: ${report.summary.totalIssues}`);
+  if (report.summary.acknowledgedCount > 0) {
+    const unaddressed = report.summary.totalIssues - report.summary.acknowledgedCount;
+    lines.push(
+      `  Total: ${report.summary.totalIssues} (${report.summary.acknowledgedCount} acknowledged via canicode annotations / ${unaddressed} unaddressed)`
+    );
+  } else {
+    lines.push(`  Total: ${report.summary.totalIssues}`);
+  }
   return lines.join("\n");
 }
 function buildResultJson(fileName, result, scores, options) {
@@ -4209,17 +4250,20 @@ function buildResultJson(fileName, result, scores, options) {
       ...applyContext.annotationProperties !== void 0 ? { annotationProperties: applyContext.annotationProperties } : {},
       ...suggestedName !== void 0 ? { suggestedName } : {},
       isInstanceChild: applyContext.isInstanceChild,
-      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
+      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {},
+      ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
   const json = {
     version: version2,
     analyzedAt: result.analyzedAt,
     ...options?.fileKey && { fileKey: options.fileKey },
+    ...options?.designKey && { designKey: options.designKey },
     fileName,
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
     issueCount: result.issues.length,
+    acknowledgedCount: scores.summary.acknowledgedCount,
     isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
     blockingIssueCount: scores.summary.blocking,
     scores: {
@@ -4235,6 +4279,18 @@ function buildResultJson(fileName, result, scores, options) {
   }
   return json;
 }
+function isFigmaUrl2(input) {
+  return input.includes("figma.com/");
+}
+z.string();
+function computeDesignKey(input) {
+  if (isFigmaUrl2(input)) {
+    const { fileKey, nodeId } = parseFigmaUrl(input);
+    if (!nodeId) return fileKey;
+    return `${fileKey}#${nodeId.replace(/-/g, ":")}`;
+  }
+  return resolve(input);
+}
 var VALID_RULE_IDS = new Set(Object.keys(RULE_CONFIGS));
 var RuleOverrideSchema = z.object({
   score: z.number().int().max(0).optional(),
@@ -5468,10 +5524,11 @@ var AnalyzeOptionsSchema = z.object({
   screenshot: z.boolean().optional(),
   config: z.string().optional(),
   noOpen: z.boolean().optional(),
-  json: z.boolean().optional()
+  json: z.boolean().optional(),
+  acknowledgments: z.string().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)").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.").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");
@@ -5540,17 +5597,31 @@ Analyzing: ${file.name}`);
         excludeNodeTypes = configFile.excludeNodeTypes;
         log(`Config loaded: ${options.config}`);
       }
+      let acknowledgments;
+      if (options.acknowledgments) {
+        const ackPath = resolve(options.acknowledgments);
+        const raw = await readFile(ackPath, "utf-8");
+        const parsed = AcknowledgmentListSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+          throw new Error(
+            `Invalid --acknowledgments file at ${ackPath}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+          );
+        }
+        acknowledgments = parsed.data;
+        log(`Acknowledgments loaded: ${acknowledgments.length} entries from ${ackPath}`);
+      }
       const analyzeOptions = {
         configs,
         ...effectiveNodeId && { targetNodeId: effectiveNodeId },
         ...excludeNodeNames && { excludeNodeNames },
-        ...excludeNodeTypes && { excludeNodeTypes }
+        ...excludeNodeTypes && { excludeNodeTypes },
+        ...acknowledgments && { acknowledgments }
       };
       const result = analyzeFile(file, analyzeOptions);
       log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
       const scores = calculateScores(result, configs);
       if (options.json) {
-        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey }), null, 2));
+        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input) }), null, 2));
         if (scores.overall.grade === "F") {
           process.exitCode = 1;
         }
@@ -5721,26 +5792,97 @@ var GOTCHA_QUESTIONS = {
   }
 };
 
+// src/core/gotcha/group-and-batch-questions.ts
+var BATCHABLE_RULE_IDS = [
+  "missing-size-constraint",
+  "irregular-spacing",
+  "no-auto-layout",
+  "fixed-size-in-auto-layout"
+];
+var BATCHABLE_SET = new Set(BATCHABLE_RULE_IDS);
+var NO_SOURCE_SENTINEL = "_no-source";
+function groupAndBatchSurveyQuestions(questions) {
+  if (questions.length === 0) {
+    return { groups: [] };
+  }
+  const sorted = [...questions].sort(compareQuestions);
+  const groups = [];
+  let currentGroup = null;
+  let lastGroupKey = null;
+  for (const question of sorted) {
+    const groupKey = sourceComponentKey(question);
+    if (currentGroup === null || groupKey !== lastGroupKey) {
+      currentGroup = {
+        instanceContext: question.instanceContext ?? null,
+        batches: []
+      };
+      groups.push(currentGroup);
+      lastGroupKey = groupKey;
+    }
+    pushIntoBatch(currentGroup, question);
+  }
+  return { groups };
+}
+function compareQuestions(a, b) {
+  const aKey = sourceComponentKey(a);
+  const bKey = sourceComponentKey(b);
+  if (aKey !== bKey) {
+    if (aKey === NO_SOURCE_SENTINEL) return 1;
+    if (bKey === NO_SOURCE_SENTINEL) return -1;
+    return aKey.localeCompare(bKey);
+  }
+  if (a.ruleId !== b.ruleId) return a.ruleId.localeCompare(b.ruleId);
+  if (a.nodeName !== b.nodeName) return a.nodeName.localeCompare(b.nodeName);
+  return a.nodeId.localeCompare(b.nodeId);
+}
+function sourceComponentKey(question) {
+  return question.instanceContext?.sourceComponentId ?? NO_SOURCE_SENTINEL;
+}
+function pushIntoBatch(group, question) {
+  const sceneWeight = Math.max(question.replicas ?? 1, 1);
+  const isBatchable = BATCHABLE_SET.has(question.ruleId);
+  const last = group.batches.at(-1);
+  if (last !== void 0 && last.ruleId === question.ruleId && isBatchable && last.batchable) {
+    last.questions.push(question);
+    last.totalScenes += sceneWeight;
+    return;
+  }
+  group.batches.push({
+    ruleId: question.ruleId,
+    batchable: isBatchable,
+    questions: [question],
+    totalScenes: sceneWeight
+  });
+}
+
 // src/core/gotcha/survey-generator.ts
 var NODE_PATH_SEPARATOR = " > ";
-function generateGotchaSurvey(result, scores) {
+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 deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
-  const questions = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
+  const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
+  const questions = deduplicateBySourceComponent(mapped);
+  const groupedQuestions = groupAndBatchSurveyQuestions(questions);
   return {
     designGrade: grade,
     isReadyForCodeGen: isReadyForCodeGen(grade),
-    questions
+    questions,
+    groupedQuestions,
+    designKey: options.designKey ?? ""
   };
 }
 function deduplicateSiblingIssues(issues) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (const issue of issues) {
+    if (isInstanceChildNodeId(issue.violation.nodeId)) {
+      result.push(issue);
+      continue;
+    }
     const parentPath = getParentPath(issue.violation.nodePath);
     const key = `${parentPath}||${issue.violation.ruleId}`;
     if (!seen.has(key)) {
@@ -5800,6 +5942,50 @@ function mapToQuestion(issue, file) {
     ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
   };
 }
+function deduplicateBySourceComponent(questions) {
+  const groups = /* @__PURE__ */ new Map();
+  const order = [];
+  let uniqueCounter = 0;
+  for (const q of questions) {
+    const ic = q.instanceContext;
+    let key;
+    if (ic && ic.sourceComponentId && ic.sourceNodeId) {
+      key = `${ic.sourceComponentId}::${ic.sourceNodeId}::${q.ruleId}`;
+    } else {
+      key = `__unique__${uniqueCounter++}`;
+    }
+    const bucket = groups.get(key);
+    if (bucket) {
+      bucket.push(q);
+    } else {
+      groups.set(key, [q]);
+      order.push(key);
+    }
+  }
+  return order.map((key) => {
+    const group = groups.get(key);
+    const first = group[0];
+    if (group.length === 1) return first;
+    const otherIds = group.slice(1).map((q) => q.nodeId);
+    const sourceComponentName = first.instanceContext?.sourceComponentName;
+    const template = GOTCHA_QUESTIONS[first.ruleId];
+    const renamed = {
+      ...first,
+      replicas: group.length,
+      replicaNodeIds: otherIds
+    };
+    if (sourceComponentName) {
+      renamed.nodeName = sourceComponentName;
+      if (template) {
+        renamed.question = template.question.replace(
+          "{nodeName}",
+          sourceComponentName
+        );
+      }
+    }
+    return renamed;
+  });
+}
 function buildInstanceContext(nodeId, file) {
   const parts = parseInstanceChildNodeId(nodeId);
   if (!parts) return null;
@@ -5845,7 +6031,7 @@ async function runGotchaSurvey(input, options) {
     ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
   });
   const scores = calculateScores(result, configs);
-  return generateGotchaSurvey(result, scores);
+  return generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });
 }
 function formatHumanSummary(survey) {
   const lines = [
@@ -5913,6 +6099,198 @@ ${msg}`);
     }
   });
 }
+z.enum([
+  "missing",
+  "valid",
+  "missing-heading",
+  "clobbered"
+]);
+var COLLECTED_GOTCHAS_HEADING = "# Collected Gotchas";
+var SECTION_HEADER_RE = /^## #(\d{3,}) — /gm;
+function detectGotchasFileState(content) {
+  if (content === null) return "missing";
+  if (!hasFrontmatter(content)) return "clobbered";
+  if (!hasCollectedGotchasHeading(content)) return "missing-heading";
+  return "valid";
+}
+function hasFrontmatter(content) {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    return false;
+  }
+  const rest = content.slice(4);
+  return /^---\s*$/m.test(rest);
+}
+function hasCollectedGotchasHeading(content) {
+  return /^# Collected Gotchas\s*$/m.test(content);
+}
+function findOrAppendSection(content, designKey) {
+  const regionStart = locateCollectedGotchasRegion(content);
+  const region = content.slice(regionStart);
+  const sections = parseSections(region);
+  let maxNumber = 0;
+  for (const section of sections) {
+    if (section.numericValue > maxNumber) maxNumber = section.numericValue;
+    if (sectionMatchesDesignKey(section.body, designKey)) {
+      return {
+        action: "replace",
+        sectionNumber: section.padded,
+        replaceRange: [
+          regionStart + section.start,
+          regionStart + section.end
+        ]
+      };
+    }
+  }
+  const next = maxNumber + 1;
+  return {
+    action: "append",
+    sectionNumber: padNumber(next)
+  };
+}
+function parseSections(region) {
+  const sections = [];
+  const matches = [...region.matchAll(SECTION_HEADER_RE)];
+  for (let i = 0; i < matches.length; i += 1) {
+    const match = matches[i];
+    const start = match.index;
+    const next = matches[i + 1];
+    const end = next?.index ?? region.length;
+    const captured = match[1];
+    sections.push({
+      padded: captured,
+      numericValue: parseInt(captured, 10),
+      start,
+      end,
+      body: region.slice(start, end)
+    });
+  }
+  return sections;
+}
+function locateCollectedGotchasRegion(content) {
+  const re = /^# Collected Gotchas\s*$/m;
+  const match = re.exec(content);
+  if (!match) return content.length;
+  return match.index + match[0].length;
+}
+function sectionMatchesDesignKey(body, designKey) {
+  const re = /^-\s+\*\*Design key\*\*:\s+(.+?)\s*$/m;
+  const m = body.match(re);
+  if (!m) return false;
+  return m[1].includes(designKey);
+}
+function padNumber(n) {
+  return n.toString().padStart(3, "0");
+}
+function renderUpsertedFile(args) {
+  const { currentContent, designKey, sectionMarkdown } = args;
+  const state = detectGotchasFileState(currentContent);
+  if (state === "missing" || state === "clobbered") {
+    return { state, newContent: null };
+  }
+  let working = currentContent;
+  if (state === "missing-heading") {
+    const sep = working.endsWith("\n\n") ? "" : working.endsWith("\n") ? "\n" : "\n\n";
+    working = `${working}${sep}${COLLECTED_GOTCHAS_HEADING}
+`;
+  }
+  const plan = findOrAppendSection(working, designKey);
+  const sectionWithNumber = sectionMarkdown.includes("{{SECTION_NUMBER}}") ? sectionMarkdown.replace(/\{\{SECTION_NUMBER\}\}/g, plan.sectionNumber) : sectionMarkdown;
+  let newContent;
+  if (plan.action === "replace") {
+    const [start, end] = plan.replaceRange;
+    const before = working.slice(0, start);
+    const after = working.slice(end);
+    newContent = `${before}${ensureTrailingNewline(sectionWithNumber)}${after}`;
+  } else {
+    const trimmed = working.replace(/\s+$/, "");
+    newContent = `${trimmed}
+
+${ensureTrailingNewline(sectionWithNumber)}`;
+  }
+  return { state, newContent, plan };
+}
+function ensureTrailingNewline(s) {
+  return s.endsWith("\n") ? s : `${s}
+`;
+}
+
+// src/cli/commands/upsert-gotcha-section.ts
+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)")
+});
+var USER_MESSAGES = {
+  missing: "Gotchas SKILL.md not found at the given path. Run `canicode init` first, then re-invoke this skill.",
+  clobbered: "Your gotchas SKILL.md is missing the canicode YAML frontmatter (pre-#340 single-design clobber). Run `canicode init --force` to restore the workflow, then re-run this survey."
+};
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function runUpsertGotchaSection(options) {
+  const sectionMarkdown = options.section === "-" ? await readStdin() : options.section;
+  const currentContent = existsSync(options.file) ? readFileSync(options.file, "utf-8") : null;
+  const { state, newContent, plan } = renderUpsertedFile({
+    currentContent,
+    designKey: options.designKey,
+    sectionMarkdown
+  });
+  if (newContent === null) {
+    return {
+      state,
+      action: null,
+      sectionNumber: null,
+      wrote: false,
+      userMessage: USER_MESSAGES[state] ?? null
+    };
+  }
+  writeFileSync(options.file, newContent, "utf-8");
+  return {
+    state,
+    action: plan?.action ?? null,
+    sectionNumber: plan?.sectionNumber ?? null,
+    wrote: true,
+    userMessage: null
+  };
+}
+function registerUpsertGotchaSection(cli2) {
+  cli2.command(
+    "upsert-gotcha-section",
+    "Upsert a per-design section into the canicode-gotchas SKILL.md (used by the canicode-gotchas skill \u2014 Step 4b)"
+  ).option("--file <path>", "Path to the canicode-gotchas SKILL.md").option(
+    "--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."
+  ).action(async (rawOptions) => {
+    const parseResult = UpsertOptionsSchema.safeParse(rawOptions);
+    if (!parseResult.success) {
+      const msg = parseResult.error.issues.map((i) => `--${i.path.join(".")}: ${i.message}`).join("\n");
+      console.error(`
+Invalid options:
+${msg}`);
+      process.exit(1);
+    }
+    try {
+      const result = await runUpsertGotchaSection(parseResult.data);
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.wrote && result.userMessage) {
+        process.exitCode = 2;
+      }
+    } catch (error) {
+      console.error(
+        "\nError:",
+        error instanceof Error ? error.message : String(error)
+      );
+      process.exitCode = 1;
+    }
+  });
+}
 function registerDesignTree(cli2) {
   cli2.command(
     "design-tree <input>",
@@ -7633,9 +8011,9 @@ function registerCalibrateEvaluate(cli2) {
       if (!existsSync(conversionPath)) {
         throw new Error(`Conversion file not found: ${conversionPath}`);
       }
-      const { readFile: readFile3 } = await import('fs/promises');
-      const analysisData = JSON.parse(await readFile3(analysisPath, "utf-8"));
-      const conversionData = JSON.parse(await readFile3(conversionPath, "utf-8"));
+      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"));
       let fixtureName;
       if (options.runDir) {
         const dirName = resolve(options.runDir).split(/[/\\]/).pop() ?? "";
@@ -9136,8 +9514,8 @@ ${msg}`);
             const resp = await fetch(url);
             if (resp.ok) {
               const buffer = Buffer.from(await resp.arrayBuffer());
-              const { writeFile: writeFileSync6 } = await import('fs/promises');
-              await writeFileSync6(resolve(fixtureDir, "screenshot.png"), buffer);
+              const { writeFile: writeFileSync7 } = await import('fs/promises');
+              await writeFileSync7(resolve(fixtureDir, "screenshot.png"), buffer);
               console.log(`  screenshot.png: saved`);
             }
           }
@@ -9487,6 +9865,7 @@ process.on("beforeExit", () => {
 });
 registerAnalyze(cli);
 registerGotchaSurvey(cli);
+registerUpsertGotchaSection(cli);
 registerDesignTree(cli);
 registerVisualCompare(cli);
 registerInit(cli);
@@ -9544,7 +9923,7 @@ cli.help((sections) => {
       title: "\nInstallation",
       body: [
         `  CLI:     npm install -g canicode`,
-        `  MCP:     claude mcp add canicode -- npx -y -p canicode canicode-mcp`,
+        `  MCP:     claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`,
         `  Skills:  github.com/let-sunny/canicode`
       ].join("\n")
     }