canicode 0.10.3 → 0.10.4

package/README.md

@@ -72,7 +72,7 @@ npx canicode init --token figd_xxxxxxxxxxxxx
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 
 # MCP Server — works with Claude Code, Cursor, Claude Desktop
-claude mcp add canicode -- npx -y -p canicode canicode-mcp
+claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
 <details>
@@ -107,68 +107,73 @@ Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggest
 
 ---
 
-## Installation
+## Installation — pick one
+
+Each row below is a **complete** install. Don't run more than one — they cover overlapping use cases. (#367)
+
+| If you use… | Install |
+|-------------|---------|
+| **Claude Code** (recommended for the roundtrip workflow) | `npx canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND drops `/canicode`, `/canicode-gotchas`, `/canicode-roundtrip` skills into `./.claude/skills/`. The skills already know how to call canicode via `npx canicode …`, no MCP install needed. |
+| **Cursor / Claude Desktop / other MCP host** | `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — registers the MCP server. |
+| **Just the CLI** (CI, scripts) | Nothing. `npx canicode analyze "<figma-url>"` works directly. Run `canicode init --token …` once if you want the token persisted to `~/.canicode/config.json`. |
+
+> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+
+> **Roundtrip prerequisite:** the `/canicode-roundtrip` skill calls the Figma MCP server to read and write the design. Install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` and restart Claude Code so the new MCP tools load.
 
 <details>
-<summary><strong>CLI</strong></summary>
+<summary><strong>Claude Code Skills</strong> — install details</summary>
 
 ```bash
-npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+npx canicode init --token figd_xxxxxxxxxxxxx
 ```
 
-Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND installs the Claude Code skills (see below).
-
-> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+Drops three skills into `./.claude/skills/`:
 
-**Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
+- **canicode** — lightweight CLI wrapper (use `/canicode <figma-url>`)
+- **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
+- **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
 
-| Seat | File in Starter plan | File in Pro/Org/Enterprise |
-|------|---------------------|---------------------------|
-| View, Collab | 6 req/month | 6 req/month |
-| Dev, Full | 6 req/month | 10–20 req/min |
+The skills shell out to `npx canicode …` for analyze / gotcha-survey when the canicode MCP server is not installed — both paths produce the same JSON shape. The Figma MCP server is still required for the apply step (Step 4 in `/canicode-roundtrip`); see the prereq note above.
 
-Hitting 429 errors? Make sure the file is in a paid workspace. Or save a fixture once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
+Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips skill install (token only). `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
 
 </details>
 
 <details>
-<summary><strong>MCP Server</strong> (Claude Code / Cursor / Claude Desktop)</summary>
+<summary><strong>MCP Server</strong> — install details</summary>
 
 ```bash
-claude mcp add canicode -- npx -y -p canicode canicode-mcp
-claude mcp add -s project -t http figma https://mcp.figma.com/mcp
+claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
 Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
 
-canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls.
+canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls. The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` (set via `canicode init --token …`) or from the host's environment, so passing `-e FIGMA_TOKEN=…` to `claude mcp add` is **not** required and the current parser rejects it anyway (#364).
 
-With a Figma API token:
-```bash
-claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
-```
+If you genuinely need a per-server token without using `canicode init`, export it on the calling shell instead: `export FIGMA_TOKEN=figd_xxxxxxxxxxxxx`.
 
 For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md).
 
 </details>
 
-
 <details>
-<summary><strong>Claude Code Skills</strong> (lightweight, no MCP install)</summary>
+<summary><strong>CLI</strong> — install details</summary>
 
 ```bash
-npx canicode init --token figd_xxxxxxxxxxxxx
+npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Saves your Figma token AND installs three skills into `./.claude/skills/`:
+Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` saves the token (and installs the Claude Code skills as a bonus — pass `--no-skills` to skip).
 
-- **canicode** — lightweight CLI wrapper (use `/canicode <figma-url>`)
-- **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
-- **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
+**Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
 
-> **Next:** install the Figma MCP server (`claude mcp add -s project -t http figma https://mcp.figma.com/mcp`) and restart Claude Code so both the skills and the MCP tools load. See the **MCP Server** section above for context.
+| Seat | File in Starter plan | File in Pro/Org/Enterprise |
+|------|---------------------|---------------------------|
+| View, Collab | 6 req/month | 6 req/month |
+| Dev, Full | 6 req/month | 10–20 req/min |
 
-Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips skill install (token only). `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
+Hitting 429 errors? Make sure the file is in a paid workspace. Or save a fixture once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
 
 </details>
 

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,
@@ -3409,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) {
@@ -3459,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;
@@ -3466,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
@@ -3500,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,
@@ -3980,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";
@@ -4025,7 +4046,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.10.3";
+var version2 = "0.10.4";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -4081,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);
@@ -4128,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) {
@@ -4145,6 +4168,7 @@ function calculateScores(result, configs) {
         summary.suggestion++;
         break;
     }
+    if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
   return {
     overall: {
@@ -4195,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) {
@@ -4219,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: {
@@ -4245,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(),
@@ -5478,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");
@@ -5550,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;
         }
@@ -5731,9 +5792,72 @@ 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"
@@ -5742,16 +5866,23 @@ function generateGotchaSurvey(result, scores) {
   const sorted = stableSortBySeverity(deduped);
   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)) {
@@ -5900,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 = [
@@ -5968,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>",
@@ -7688,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() ?? "";
@@ -9191,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`);
             }
           }
@@ -9542,6 +9865,7 @@ process.on("beforeExit", () => {
 });
 registerAnalyze(cli);
 registerGotchaSurvey(cli);
+registerUpsertGotchaSection(cli);
 registerDesignTree(cli);
 registerVisualCompare(cli);
 registerInit(cli);
@@ -9599,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")
     }