canicode 0.11.5 → 0.12.1

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync, readdirSync, renameSync, chmodSync, copyFileSync } from 'fs';
-import { join, resolve, dirname, basename, relative } from 'path';
+import { join, resolve, dirname, basename, isAbsolute, sep, relative } from 'path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 import { createRequire } from 'module';
@@ -10,6 +10,7 @@ import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 import { z } from 'zod';
 import { readFile, writeFile } from 'fs/promises';
+import * as readline from 'readline/promises';
 import { createInterface } from 'readline/promises';
 import { pathToFileURL, fileURLToPath } from 'url';
 
@@ -131,6 +132,32 @@ var init_figma_client = __esm({
         const buffer = await response.arrayBuffer();
         return Buffer.from(buffer).toString("base64");
       }
+      /**
+       * Get the components a file has published to a team library.
+       *
+       * `GET /v1/files/:file_key/components` returns only components that have
+       * been pushed via the Publish Library action — local-but-unpublished
+       * components are absent. This is the authoritative way to detect whether
+       * a Figma component is mappable via Code Connect (#532): `add_code_connect_map`
+       * requires a published component and otherwise fails with "Published
+       * component not found."
+       */
+      async getPublishedComponents(fileKey) {
+        const url = `${FIGMA_API_BASE}/files/${fileKey}/components`;
+        const response = await fetch(url, {
+          headers: { "X-Figma-Token": this.token }
+        });
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({}));
+          throw new FigmaClientError(
+            `Failed to fetch published components: ${response.status} ${response.statusText}`,
+            response.status,
+            error
+          );
+        }
+        const data = await response.json();
+        return data.meta?.components ?? [];
+      }
       async getFileNodes(fileKey, nodeIds) {
         const ids = nodeIds.join(",");
         const url = `${FIGMA_API_BASE}/files/${fileKey}/nodes?ids=${encodeURIComponent(ids)}`;
@@ -1371,6 +1398,8 @@ var EVENTS = {
   // CLI
   CLI_COMMAND: `${EVENT_PREFIX}cli_command`,
   CLI_INIT: `${EVENT_PREFIX}cli_init`,
+  CLI_CONFIG_SET_TOKEN: `${EVENT_PREFIX}cli_config_set_token`,
+  CLI_DOCTOR: `${EVENT_PREFIX}cli_doctor`,
   // Roundtrip (ADR-012)
   // Wiring point for the roundtrip helper's `telemetry` callback. No Node-side
   // orchestrator reads this yet — the helper ships in a sandbox-pure IIFE that
@@ -1547,12 +1576,14 @@ CANICODE SETUP GUIDE
     npm install -g canicode
 
   Setup:
-    canicode init --token figd_xxxxxxxxxxxxx
+    canicode init                              (interactive prompt; TTY)
+    canicode init --token figd_xxxxxxxxxxxxx   (non-TTY / CI)
+    FIGMA_TOKEN=figd_xxx canicode init         (env-driven)
     (saves token + installs Claude Code skills into ./.claude/skills/)
 
   Skills only (no token yet):
     canicode init --cursor-skills
-    (installs Claude skills + Cursor copies; run init --token \u2026 before live Figma REST URLs)
+    (installs Claude skills + Cursor copies; run init or init --token \u2026 before live Figma REST URLs)
 
   Use:
     canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
@@ -1562,7 +1593,7 @@ CANICODE SETUP GUIDE
     --preset strict|relaxed|dev-friendly|ai-ready
     --config ./my-config.json
     --no-open   Don't open report in browser
-    --api       No-op for Figma URLs (REST always); same flag as gotcha-survey (#461)
+    --api       No-op for Figma URLs (REST always); same flag as gotcha-survey
 
   Output:
     ~/.canicode/reports/report-YYYY-MM-DD-HH-mm-<filekey>.html
@@ -1574,7 +1605,8 @@ CANICODE SETUP GUIDE
   (Same token safety as above \u2014 env var or interactive prompt, not chat.)
 
   Setup:
-    canicode init --token figd_xxxxxxxxxxxxx
+    canicode init                              (interactive prompt; TTY)
+    canicode init --token figd_xxxxxxxxxxxxx   (non-TTY / CI)
     (installs three skills into ./.claude/skills/ alongside the token)
 
   Installed skills:
@@ -1599,7 +1631,8 @@ CANICODE SETUP GUIDE
   (Same token safety as above \u2014 env var or interactive prompt, not chat.)
 
   Setup:
-    canicode init --token figd_xxxxxxxxxxxxx --cursor-skills
+    canicode init --cursor-skills                              (interactive prompt; TTY)
+    canicode init --token figd_xxxxxxxxxxxxx --cursor-skills   (non-TTY / CI)
     (installs Cursor copies of the three skills into ./.cursor/skills/)
 
   Installed skills:
@@ -1629,6 +1662,14 @@ CANICODE SETUP GUIDE
   See also: docs/CUSTOMIZATION.md#cursor-mcp-canicode (Figma MCP required for roundtrip
   writes; analyze-only works without it).
 
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ MANAGE CONFIG
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  canicode config set-token   Rotate Figma token (no skill reinstall)
+  canicode config show        Print masked token + config + reports paths
+  canicode config path        Print absolute config path (script-friendly)
+
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
  TOKEN PRIORITY
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -1821,6 +1862,7 @@ var RULE_ID_CATEGORY = {
   "detached-instance": "code-quality",
   "variant-structure-mismatch": "code-quality",
   "deep-nesting": "code-quality",
+  "unmapped-component": "code-quality",
   // Token Management
   "raw-value": "token-management",
   "irregular-spacing": "token-management",
@@ -1851,6 +1893,12 @@ var RULE_PURPOSE = {
   "detached-instance": "violation",
   "variant-structure-mismatch": "violation",
   "deep-nesting": "violation",
+  // #520: unmapped-component is annotation-primary. Fires only when the
+  // user has Code Connect set up at all (figma.config.json present in cwd).
+  // The gotcha drives the user to /canicode-roundtrip for actual mapping
+  // registration via the Figma MCP tools — analyze itself does not parse
+  // mapping declarations (deferred to v1.5).
+  "unmapped-component": "info-collection",
   // Token Management
   "raw-value": "violation",
   "irregular-spacing": "violation",
@@ -1894,12 +1942,12 @@ var RULE_CONFIGS = {
     enabled: true
   },
   "missing-size-constraint": {
-    // #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,
+    // #403 → #519: info-collection rule. Score is 0 (severity `note`):
+    // its value is the gotcha annotation, not the grade impact. Survey-
+    // generator includes this rule via the `purpose === "info-collection"`
+    // branch so the gotcha keeps surfacing.
+    severity: "note",
+    score: 0,
     enabled: true
   },
   // ── Code Quality ──
@@ -1931,6 +1979,16 @@ var RULE_CONFIGS = {
       maxDepth: 5
     }
   },
+  "unmapped-component": {
+    // #520 / #519: zero-impact tier. Fires per main component when Code
+    // Connect is set up in the consuming repo (figma.config.json at cwd).
+    // Score is 0 because the rule's value is the gotcha + roundtrip handoff,
+    // not the grade signal — designers who deliberately do not map (e.g.
+    // marketing-only banners) are not punished.
+    severity: "note",
+    score: 0,
+    enabled: true
+  },
   // ── Token Management ──
   "raw-value": {
     severity: "missing-info",
@@ -1952,15 +2010,15 @@ var RULE_CONFIGS = {
   // is minimal. Score stays at -1 so re-enabling `missing-prototype` on
   // fixtures that lack `interactionDestinations` (#139) cannot swing grades.
   "missing-interaction-state": {
-    severity: "missing-info",
-    score: -1,
-    // uncalibrated: no metric to validate score (#210), kept at -1 to preserve category visibility
+    severity: "note",
+    // #519: info-collection rule, zero-score tier
+    score: 0,
     enabled: true
   },
   "missing-prototype": {
-    severity: "missing-info",
-    score: -1,
-    // #406: info-collection — annotation is primary output; score kept minimal so #139 fixtures don't skew calibration
+    severity: "note",
+    // #519: info-collection — annotation is primary output, no grade impact
+    score: 0,
     enabled: true
   },
   // ── Semantic ──
@@ -2165,7 +2223,14 @@ var SeveritySchema = z.enum([
   "blocking",
   "risk",
   "missing-info",
-  "suggestion"
+  "suggestion",
+  /**
+   * `note` is the zero-impact tier (#519): findings render in the report but
+   * never move the grade. Used for annotation-primary rules whose value is the
+   * nudge, not the score (e.g. unmapped Code Connect components, info-collection
+   * rules whose answers belong in figma-implement-design context, not in linting).
+   */
+  "note"
 ]);
 
 // src/core/contracts/rule.ts
@@ -2459,6 +2524,10 @@ var missingComponentMsg = {
     suggestion: `Create a new variant for this style combination`
   })
 };
+var unmappedComponentMsg = (componentName) => ({
+  message: `"${componentName}" has no Code Connect mapping`,
+  suggestion: `Run /canicode-roundtrip on this component to register a mapping so figma-implement-design reuses your code instead of regenerating markup. Skip if intentionally unmapped.`
+});
 var detachedInstanceMsg = (name, componentName) => ({
   message: `"${name}" may be a detached instance of component "${componentName}"`,
   suggestion: `Restore as an instance of "${componentName}" or create a new variant`
@@ -3010,6 +3079,174 @@ defineRule({
   definition: irregularSpacingDef,
   check: irregularSpacingCheck
 });
+var FIGMA_CONFIG_FILENAME = "figma.config.json";
+var FIGMA_CONNECT_FILE_GLOB = /\.figma\.(tsx?|jsx?)$/;
+var NODE_ID_QUERY_RE = /[?&]node-id=([0-9A-Za-z%:\-_]+)/;
+function parseCodeConnectMappings(cwd) {
+  const configPath = join(cwd, FIGMA_CONFIG_FILENAME);
+  if (!existsSync(configPath)) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "no-config",
+      skippedReason: `${FIGMA_CONFIG_FILENAME} not found at ${cwd}`
+    };
+  }
+  let config2;
+  try {
+    config2 = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "malformed-config",
+      skippedReason: `malformed ${FIGMA_CONFIG_FILENAME}: ${err.message}`
+    };
+  }
+  const includes = config2.codeConnect?.include ?? config2.include ?? [];
+  if (includes.length === 0) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "no-includes",
+      skippedReason: `${FIGMA_CONFIG_FILENAME} has no codeConnect.include paths`
+    };
+  }
+  const candidateFiles = /* @__PURE__ */ new Set();
+  for (const includePattern of includes) {
+    for (const file of resolveInclude(cwd, includePattern)) {
+      candidateFiles.add(file);
+    }
+  }
+  const mappedNodeIds = /* @__PURE__ */ new Set();
+  const scannedFiles = [];
+  for (const file of candidateFiles) {
+    scannedFiles.push(file);
+    let contents;
+    try {
+      contents = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const nodeId of extractNodeIdsFromSource(contents)) {
+      mappedNodeIds.add(nodeId);
+    }
+  }
+  return { mappedNodeIds, scannedFiles };
+}
+function resolveInclude(cwd, includePattern) {
+  const results = [];
+  const absolute = isAbsolute(includePattern) ? includePattern : resolve(cwd, includePattern);
+  const segments = absolute.split(sep);
+  let firstGlobIdx = segments.findIndex((s) => /[*?{[]/.test(s));
+  if (firstGlobIdx === -1) {
+    if (existsSync(absolute)) {
+      const stat = statSync(absolute);
+      if (stat.isFile() && FIGMA_CONNECT_FILE_GLOB.test(absolute)) {
+        results.push(absolute);
+      } else if (stat.isDirectory()) {
+        walkDir(absolute, results);
+      }
+    }
+    return results;
+  }
+  const rootSegments = segments.slice(0, firstGlobIdx);
+  const root = rootSegments.length === 0 ? sep : rootSegments.join(sep);
+  if (!existsSync(root)) return results;
+  const rootStat = statSync(root);
+  if (!rootStat.isDirectory()) return results;
+  walkDir(root, results);
+  const prefix = rootSegments.join(sep) + sep;
+  return results.filter((f) => f.startsWith(prefix) || rootSegments.length === 0);
+}
+function walkDir(dir, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry === "node_modules" || entry.startsWith(".")) continue;
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+    } else if (stat.isFile() && FIGMA_CONNECT_FILE_GLOB.test(full)) {
+      out.push(full);
+    }
+  }
+}
+function extractNodeIdsFromSource(source) {
+  const nodeIds = /* @__PURE__ */ new Set();
+  const re = new RegExp(NODE_ID_QUERY_RE, "g");
+  let match;
+  while ((match = re.exec(source)) !== null) {
+    const raw = match[1];
+    if (!raw) continue;
+    const decoded = safeDecode(raw);
+    nodeIds.add(decoded.replace(/-/g, ":"));
+  }
+  return nodeIds;
+}
+function safeDecode(raw) {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+var PropertyAcknowledgmentIntentSchema = z.object({
+  kind: z.literal("property").default("property"),
+  field: z.string(),
+  value: z.unknown(),
+  scope: z.enum(["instance", "definition"])
+});
+var RuleOptOutAcknowledgmentIntentSchema = z.object({
+  kind: z.literal("rule-opt-out"),
+  ruleId: z.string()
+}).strict();
+var AcknowledgmentIntentSchema = z.preprocess((raw) => {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw;
+    if (obj["kind"] === void 0) {
+      return { ...obj, kind: "property" };
+    }
+  }
+  return raw;
+}, z.discriminatedUnion("kind", [
+  PropertyAcknowledgmentIntentSchema,
+  RuleOptOutAcknowledgmentIntentSchema
+]));
+function isRuleOptOutIntent(intent) {
+  return intent !== void 0 && intent.kind === "rule-opt-out";
+}
+var AcknowledgmentSceneWriteOutcomeSchema = z.object({
+  result: z.enum([
+    "succeeded",
+    "silent-ignored",
+    "api-rejected",
+    "user-declined-propagation",
+    "unknown"
+  ]),
+  reason: z.string().optional()
+});
+var AcknowledgmentSchema = z.object({
+  nodeId: z.string(),
+  ruleId: z.string(),
+  intent: AcknowledgmentIntentSchema.optional(),
+  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
+  codegenDirective: z.string().optional()
+});
+var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
+function normalizeNodeId(id) {
+  return id.replace(/-/g, ":");
+}
 
 // src/core/rules/component/index.ts
 var STYLE_COMPARE_KEYS = ["fills", "strokes", "effects", "cornerRadius", "strokeWeight", "individualStrokeWeights"];
@@ -3219,6 +3456,49 @@ defineRule({
   definition: variantStructureMismatchDef,
   check: variantStructureMismatchCheck
 });
+var CODE_CONNECT_SETUP_KEY = "unmapped-component:setup-detected";
+var CODE_CONNECT_MAPPINGS_KEY = "unmapped-component:mappings";
+function codeConnectIsSetUp(context) {
+  return getAnalysisState(context, CODE_CONNECT_SETUP_KEY, () => {
+    return existsSync(join(process.cwd(), "figma.config.json"));
+  });
+}
+function codeConnectMappings(context) {
+  return getAnalysisState(
+    context,
+    CODE_CONNECT_MAPPINGS_KEY,
+    () => parseCodeConnectMappings(process.cwd())
+  );
+}
+var unmappedComponentDef = {
+  id: "unmapped-component",
+  name: "Unmapped Component",
+  category: "code-quality",
+  why: "Without a Code Connect mapping, figma-implement-design regenerates the same markup every time this component appears in a screen \u2014 wasting tokens and risking drift.",
+  impact: "Future roundtrips on screens containing this component cannot reuse your existing code; they regenerate markup that may not match the canonical implementation.",
+  fix: "Run /canicode-roundtrip on this component to register a mapping. Figma's get_code_connect_map will skip if a mapping already exists."
+};
+var unmappedComponentCheck = (node, context) => {
+  if (node.type !== "COMPONENT" && node.type !== "COMPONENT_SET") return null;
+  if (isInsideInstance(context)) return null;
+  if (!codeConnectIsSetUp(context)) return null;
+  const mappings = codeConnectMappings(context);
+  if (mappings.mappedNodeIds.has(node.id)) return null;
+  const ack = context.findAcknowledgment(node.id, unmappedComponentDef.id);
+  if (ack && isRuleOptOutIntent(ack.intent) && ack.intent.ruleId === unmappedComponentDef.id) {
+    return null;
+  }
+  return {
+    ruleId: unmappedComponentDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    ...unmappedComponentMsg(node.name)
+  };
+};
+defineRule({
+  definition: unmappedComponentDef,
+  check: unmappedComponentCheck
+});
 
 // src/core/rules/naming/index.ts
 function capitalize(s) {
@@ -3575,32 +3855,6 @@ defineRule({
   definition: missingPrototypeDef,
   check: missingPrototypeCheck
 });
-var AcknowledgmentIntentSchema = z.object({
-  field: z.string(),
-  value: z.unknown(),
-  scope: z.enum(["instance", "definition"])
-});
-var AcknowledgmentSceneWriteOutcomeSchema = z.object({
-  result: z.enum([
-    "succeeded",
-    "silent-ignored",
-    "api-rejected",
-    "user-declined-propagation",
-    "unknown"
-  ]),
-  reason: z.string().optional()
-});
-var AcknowledgmentSchema = z.object({
-  nodeId: z.string(),
-  ruleId: z.string(),
-  intent: AcknowledgmentIntentSchema.optional(),
-  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
-  codegenDirective: z.string().optional()
-});
-var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
-function normalizeNodeId(id) {
-  return id.replace(/-/g, ":");
-}
 var AnalysisScopeSchema = z.enum(["page", "component"]);
 var COMPONENT_SCOPE_ROOT_TYPES = /* @__PURE__ */ new Set(["COMPONENT", "COMPONENT_SET", "INSTANCE"]);
 function detectAnalysisScope(rootNode) {
@@ -3657,6 +3911,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  acknowledgmentsByKey;
   scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
@@ -3665,10 +3920,15 @@ 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;
+    const ackList = options.acknowledgments ?? [];
     this.acknowledgments = new Set(
-      (options.acknowledgments ?? []).map(
-        (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
-      )
+      ackList.map((a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`)
+    );
+    this.acknowledgmentsByKey = new Map(
+      ackList.map((a) => [
+        `${normalizeNodeId(a.nodeId)}::${a.ruleId}`,
+        a
+      ])
     );
     this.scopeOverride = options.scope;
   }
@@ -3752,6 +4012,7 @@ var RuleEngine = class {
     if (this.excludeNamePattern && this.excludeNamePattern.test(node.name)) {
       return;
     }
+    const acknowledgmentsByKey = this.acknowledgmentsByKey;
     const context = {
       file,
       parent,
@@ -3763,7 +4024,8 @@ var RuleEngine = class {
       siblings,
       analysisState,
       scope,
-      rootNodeType
+      rootNodeType,
+      findAcknowledgment: (nodeId, ruleId) => acknowledgmentsByKey.get(`${normalizeNodeId(nodeId)}::${ruleId}`)
     };
     for (const rule of rules) {
       const ruleId = rule.definition.id;
@@ -4187,6 +4449,7 @@ var STRATEGY_BY_RULE = {
   // Strategy C — annotation only
   "absolute-position-in-auto-layout": "annotation",
   "variant-structure-mismatch": "annotation",
+  "unmapped-component": "annotation",
   // Strategy D — auto-fix lower-severity issues from analyze output
   "non-standard-naming": "auto-fix",
   "inconsistent-naming-convention": "auto-fix",
@@ -4221,6 +4484,7 @@ function resolveTargetProperty(ruleId, subType) {
     case "raw-value":
     case "missing-interaction-state":
     case "missing-prototype":
+    case "unmapped-component":
       return void 0;
   }
 }
@@ -4245,7 +4509,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.11.5";
+var version2 = "0.12.1";
 
 // src/core/engine/scoring.ts
 var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
@@ -4352,6 +4616,7 @@ function calculateScores(result, configs) {
     risk: 0,
     missingInfo: 0,
     suggestion: 0,
+    note: 0,
     nodeCount,
     acknowledgedCount: 0
   };
@@ -4369,6 +4634,9 @@ function calculateScores(result, configs) {
       case "suggestion":
         summary.suggestion++;
         break;
+      case "note":
+        summary.note++;
+        break;
     }
     if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
@@ -4400,7 +4668,8 @@ function initializeCategoryScores() {
         blocking: 0,
         risk: 0,
         "missing-info": 0,
-        suggestion: 0
+        suggestion: 0,
+        note: 0
       }
     };
   }
@@ -4421,6 +4690,7 @@ function formatScoreSummary(report) {
   lines.push(`  Risk: ${report.summary.risk}`);
   lines.push(`  Missing Info: ${report.summary.missingInfo}`);
   lines.push(`  Suggestion: ${report.summary.suggestion}`);
+  lines.push(`  Note: ${report.summary.note}`);
   if (report.summary.acknowledgedCount > 0) {
     const unaddressed = report.summary.totalIssues - report.summary.acknowledgedCount;
     lines.push(
@@ -4431,6 +4701,19 @@ function formatScoreSummary(report) {
   }
   return lines.join("\n");
 }
+function formatCodeConnectCoverageLine(coverage) {
+  const { mapped, total } = coverage;
+  const pct = total === 0 ? 0 : Math.round(mapped / total * 100);
+  return `Code Connect coverage: ${mapped}/${total} components (${pct}%) mapped`;
+}
+var ROUNDTRIP_OPT_OUT_HINT = "Some components may carry roundtrip-recorded opt-outs that this standalone analyze cannot see (Figma REST annotations field is in private beta). Run /canicode-roundtrip to apply opt-outs.";
+function formatRoundtripOptOutHintLine(issues, acknowledgmentsProvided) {
+  const hasUnmapped = issues.some(
+    (issue) => issue.violation.ruleId === "unmapped-component"
+  );
+  if (!hasUnmapped) return null;
+  return ROUNDTRIP_OPT_OUT_HINT;
+}
 function buildResultJson(fileName, result, scores, options) {
   const issuesByRule = {};
   for (const issue of result.issues) {
@@ -4460,6 +4743,14 @@ function buildResultJson(fileName, result, scores, options) {
       ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
+  const optOutHint = options?.roundtripOptOutHintEligible ? formatRoundtripOptOutHintLine(result.issues) : null;
+  const summaryParts = [formatScoreSummary(scores)];
+  if (options?.codeConnectCoverage) {
+    summaryParts.push(formatCodeConnectCoverageLine(options.codeConnectCoverage));
+  }
+  if (optOutHint) {
+    summaryParts.push(optOutHint);
+  }
   const json = {
     version: version2,
     analyzedAt: result.analyzedAt,
@@ -4479,13 +4770,31 @@ function buildResultJson(fileName, result, scores, options) {
     },
     issuesByRule,
     issues,
-    summary: formatScoreSummary(scores)
+    summary: summaryParts.join("\n\n")
   };
+  if (options?.codeConnectCoverage) {
+    json["codeConnectCoverage"] = options.codeConnectCoverage;
+  }
+  if (optOutHint) {
+    json["roundtripOptOutHint"] = optOutHint;
+  }
   if (result.failedRules.length > 0) {
     json["failedRules"] = result.failedRules;
   }
   return json;
 }
+
+// src/core/rules/component/code-connect-coverage.ts
+function computeCodeConnectCoverage(components, cwd = process.cwd()) {
+  const result = parseCodeConnectMappings(cwd);
+  if (result.skipReason === "no-config") return void 0;
+  const componentNodeIds = Object.keys(components);
+  let mapped = 0;
+  for (const nodeId of componentNodeIds) {
+    if (result.mappedNodeIds.has(nodeId)) mapped++;
+  }
+  return { mapped, total: componentNodeIds.length };
+}
 function isFigmaUrl2(input) {
   return input.includes("figma.com/");
 }
@@ -4571,7 +4880,8 @@ function severityDot(sev) {
     blocking: "sev-blocking",
     risk: "sev-risk",
     "missing-info": "sev-missing",
-    suggestion: "sev-suggestion"
+    suggestion: "sev-suggestion",
+    note: "sev-note"
   };
   return map[sev];
 }
@@ -4580,7 +4890,8 @@ function severityBadge(sev) {
     blocking: "sev-blocking",
     risk: "sev-risk",
     "missing-info": "sev-missing",
-    suggestion: "sev-suggestion"
+    suggestion: "sev-suggestion",
+    note: "sev-note"
   };
   return map[sev];
 }
@@ -4638,6 +4949,7 @@ ${CATEGORIES.map((cat) => {
         ${renderSummaryDot("sev-risk", scores.summary.risk, "Risk")}
         ${renderSummaryDot("sev-missing", scores.summary.missingInfo, "Missing Info")}
         ${renderSummaryDot("sev-suggestion", scores.summary.suggestion, "Suggestion")}
+        ${renderSummaryDot("sev-note", scores.summary.note, "Note")}
         <div class="rpt-summary-total">
           <span class="rpt-summary-count">${scores.summary.totalIssues}</span>
           <span class="rpt-summary-label">Total</span>
@@ -4852,7 +5164,7 @@ function groupIssuesByRule(issues) {
     group.issues.push(issue);
     group.totalScore += issue.calculatedScore;
   }
-  const SEVERITY_RANK = { blocking: 0, risk: 1, "missing-info": 2, suggestion: 3 };
+  const SEVERITY_RANK = { blocking: 0, risk: 1, "missing-info": 2, suggestion: 3, note: 4 };
   return [...byRule.values()].sort((a, b) => {
     const sevDiff = (SEVERITY_RANK[a.severity] ?? 4) - (SEVERITY_RANK[b.severity] ?? 4);
     return sevDiff !== 0 ? sevDiff : a.totalScore - b.totalScore;
@@ -4920,6 +5232,7 @@ body {
 .sev-risk { background: var(--amber); }
 .sev-missing { background: #a1a1aa; }
 .sev-suggestion { background: var(--green); }
+.sev-note { background: #d4d4d8; }
 
 /* ---- Print ---- */
 @media print {
@@ -5316,6 +5629,7 @@ body {
 .rpt-issue-score.sev-risk     { background: var(--amber-bg); color: #d97706; border-color: rgba(245,158,11,0.2); }
 .rpt-issue-score.sev-missing  { background: #f4f4f5; color: #71717a; border-color: rgba(113,113,122,0.2); }
 .rpt-issue-score.sev-suggestion { background: var(--green-bg); color: #16a34a; border-color: rgba(34,197,94,0.2); }
+.rpt-issue-score.sev-note     { background: #f4f4f5; color: #71717a; border-color: rgba(113,113,122,0.2); }
 
 .rpt-issue-body {
   padding: 12px;
@@ -5741,8 +6055,8 @@ var AnalyzeOptionsSchema = z.object({
 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",
-    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `gotcha-survey` (#461)."
-  ).option("--screenshot", "Include screenshot comparison in report (requires ANTHROPIC_API_KEY)").option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--no-open", "Don't open report in browser after analysis").option("--json", "Output JSON results to stdout (same format as MCP)").option("--acknowledgments <path>", "(#371 / ADR-019) Path to JSON acknowledgments from canicode Figma annotations (nodeId, ruleId; optional intent / sceneWriteOutcome / codegenDirective per #444). Matching issues are flagged acknowledged and contribute half weight to density.").option("--scope <scope>", "(#404) Override analysis scope: `page` (screen/section \u2014 container bounds are required) or `component` (standalone reusable unit \u2014 root FILL is the design contract). Defaults to auto-detection from the root node type.").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign").example("  canicode analyze ./fixtures/my-design --output report.html").example("  canicode analyze ./fixtures/my-design --config ./my-config.json").action(async (input, rawOptions) => {
+    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `gotcha-survey`."
+  ).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>", "Path to JSON acknowledgments from canicode Figma annotations (nodeId, ruleId; optional intent / sceneWriteOutcome / codegenDirective). Matching issues are flagged acknowledged and contribute half weight to density.").option("--scope <scope>", "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.").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign").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");
@@ -5839,8 +6153,17 @@ Analyzing: ${file.name}`);
       const result = analyzeFile(file, analyzeOptions);
       log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
       const scores = calculateScores(result, configs);
+      const coverage = computeCodeConnectCoverage(file.components);
+      const optOutHintEligible = acknowledgments === void 0;
+      const optOutHint = optOutHintEligible ? formatRoundtripOptOutHintLine(result.issues, false) : null;
       if (options.json) {
-        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input), ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {} }), null, 2));
+        console.log(JSON.stringify(buildResultJson(file.name, result, scores, {
+          fileKey: file.fileKey,
+          designKey: computeDesignKey(input),
+          ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {},
+          ...coverage ? { codeConnectCoverage: coverage } : {},
+          roundtripOptOutHintEligible: optOutHintEligible
+        }), null, 2));
         if (scores.overall.grade === "F") {
           process.exitCode = 1;
         }
@@ -5848,6 +6171,14 @@ Analyzing: ${file.name}`);
       }
       console.log("\n" + "=".repeat(50));
       console.log(formatScoreSummary(scores));
+      if (coverage) {
+        console.log("");
+        console.log(formatCodeConnectCoverageLine(coverage));
+      }
+      if (optOutHint) {
+        console.log("");
+        console.log(optOutHint);
+      }
       console.log("=".repeat(50));
       const now = /* @__PURE__ */ new Date();
       const ts = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}-${String(now.getHours()).padStart(2, "0")}-${String(now.getMinutes()).padStart(2, "0")}`;
@@ -5961,6 +6292,12 @@ var GOTCHA_QUESTION_CONTENT = {
     hint: "Describe which variant has the correct structure, or if they should all match",
     example: "Default variant is canonical \u2014 other variants should toggle child visibility instead of adding/removing elements"
   },
+  "unmapped-component": {
+    ruleId: "unmapped-component",
+    question: '"{nodeName}" has no Code Connect mapping yet. Should we register one so figma-implement-design reuses your code?',
+    hint: "Skip if this component is intentionally unmapped (e.g. marketing-only banner). Otherwise run /canicode-roundtrip on the component to walk through registration.",
+    example: "Yes \u2014 map to src/components/Button.tsx so future screens reuse the existing implementation"
+  },
   "deep-nesting": {
     ruleId: "deep-nesting",
     question: '"{nodeName}" is deeply nested. Can some intermediate layers be flattened or extracted?',
@@ -6106,10 +6443,7 @@ function generateGotchaSurvey(result, scores, options = {}) {
   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;
+    return getRulePurpose(issue.violation.ruleId) === "info-collection";
   });
   const deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
@@ -6322,8 +6656,8 @@ function formatHumanSummary(survey) {
 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(
     "--api",
-    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `analyze` (#461)."
-  ).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)").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").example("  canicode gotcha-survey https://www.figma.com/design/ABC123/MyDesign --json").example("  canicode gotcha-survey ./fixtures/my-design --json").action(async (input, rawOptions) => {
+    "No-op for Figma URL inputs (file data is always fetched via REST). Accepted for CLI parity with `analyze`."
+  ).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>", "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)").option("--ready-min-grade <grade>", "Minimum grade for code-gen readiness (S | A+ | A | B+ | B | C+ | C | D | F). Overrides configPath codegenReadyMinGrade. Default: A").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");
@@ -6699,8 +7033,8 @@ function renderUpsertedFile(args) {
   }
   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 sep2 = working.endsWith("\n\n") ? "" : working.endsWith("\n") ? "\n" : "\n\n";
+    working = `${working}${sep2}${COLLECTED_GOTCHAS_HEADING}
 `;
   }
   const plan = findOrAppendSection(working, designKey);
@@ -6748,7 +7082,7 @@ var UpsertOptionsSchema = z.object({
 });
 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."
+  clobbered: "Your gotchas SKILL.md is missing the canicode YAML frontmatter. Run `canicode init --force` to restore the workflow, then re-run this survey."
 };
 async function readStdin() {
   const chunks = [];
@@ -7189,6 +7523,47 @@ async function promptOverwriteBatch(candidates) {
   }
   return decisions;
 }
+var NonInteractiveError = class extends Error {
+  constructor(message = "Interactive prompt requires a TTY") {
+    super(message);
+    this.name = "NonInteractiveError";
+  }
+};
+async function promptForFigmaToken(opts = {}) {
+  const isTTY = opts.isTTY ?? process.stdin.isTTY ?? false;
+  if (!isTTY) {
+    throw new NonInteractiveError();
+  }
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const maxAttempts = opts.maxAttempts ?? 3;
+  const rl = readline.createInterface({ input, output });
+  try {
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const answer = (await rl.question("Figma token: ")).trim();
+      if (answer.length > 0) {
+        return answer;
+      }
+      if (attempt < maxAttempts) {
+        output.write("Token cannot be empty. Try again.\n");
+      }
+    }
+    throw new Error(`No token provided after ${maxAttempts} attempts`);
+  } finally {
+    rl.close();
+  }
+}
+function maskFigmaToken(token) {
+  if (!token) return "(empty)";
+  const BULLETS = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+  if (token.startsWith("figd_") && token.length > 9) {
+    return `figd_${BULLETS}${token.slice(-4)}`;
+  }
+  if (token.length >= 4) {
+    return `${BULLETS}${token.slice(-4)}`;
+  }
+  return "\u2022".repeat(token.length);
+}
 
 // src/cli/commands/init.ts
 function figmaEntryInMcpFile(filePath) {
@@ -7217,7 +7592,7 @@ function formatNextSteps(opts) {
         "  Next:",
         "    1. Restart Cursor or reload MCP (so skills + MCP tools load in a fresh session)",
         "    2. In Agent chat, @ canicode-roundtrip with your Figma URL (or @ canicode-gotchas for survey-only)",
-        "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode (project `.cursor/mcp.json`), then reload MCP; otherwise skills keep using `npx canicode \u2026` (#433)."
+        "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode (project `.cursor/mcp.json`), then reload MCP; otherwise skills keep using `npx canicode \u2026`."
       ].join("\n");
     }
     return [
@@ -7225,7 +7600,7 @@ function formatNextSteps(opts) {
       "  Next:",
       "    1. Restart Claude Code (the newly installed skills only load on a fresh session)",
       "    2. Run /canicode-roundtrip <figma-url>",
-      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so `analyze` / `gotcha-survey` tools load \u2014 otherwise skills shell out to `npx canicode \u2026` (#433)."
+      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so `analyze` / `gotcha-survey` tools load \u2014 otherwise skills shell out to `npx canicode \u2026`."
     ].join("\n");
   }
   if (cursor) {
@@ -7235,7 +7610,7 @@ function formatNextSteps(opts) {
       "    1. Add Figma MCP to .cursor/mcp.json (see https://github.com/let-sunny/canicode/blob/main/docs/CUSTOMIZATION.md#cursor-mcp-canicode and Figma MCP docs)",
       "    2. Restart Cursor so Figma tools (e.g. use_figma) load",
       "    3. @ canicode-roundtrip with your Figma URL for full roundtrip",
-      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per the Customization guide (`#cursor-mcp-canicode`), then reload MCP; otherwise skills keep using `npx canicode \u2026` (#433)."
+      "    \u2022 Optional \u2014 faster canicode MCP than `npx`: add `canicode-mcp` per the Customization guide (`#cursor-mcp-canicode`), then reload MCP; otherwise skills keep using `npx canicode \u2026`."
     ].join("\n");
   }
   return [
@@ -7245,7 +7620,7 @@ function formatNextSteps(opts) {
     "         claude mcp add -s project -t http figma https://mcp.figma.com/mcp",
     "    2. Restart Claude Code (so the new skills + Figma MCP tools both load)",
     "    3. Run /canicode-roundtrip <figma-url>",
-    "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so MCP tools load \u2014 otherwise skills shell out to `npx canicode \u2026` (#433)."
+    "    \u2022 Optional \u2014 faster canicode MCP than `npx`: `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, then restart Claude Code so MCP tools load \u2014 otherwise skills shell out to `npx canicode \u2026`."
   ].join("\n");
 }
 var InitOptionsSchema = z.object({
@@ -7258,6 +7633,56 @@ var InitOptionsSchema = z.object({
 function wantsSkillInstallWithoutToken(options) {
   return options.cursorSkills === true;
 }
+async function runFullInit(token, options, interactive) {
+  initAiready(token);
+  console.log(`  Config saved: ${getConfigPath()}`);
+  console.log(`  Reports will be saved to: ${getReportsDir()}/`);
+  const { skillStepOk, skillSummary } = await runInitSkillInstallSteps(options);
+  trackEvent(EVENTS.CLI_INIT, {
+    skillsRequested: true,
+    cursorSkillsRequested: options.cursorSkills === true,
+    skillStepOk,
+    target: options.global ? "global" : "project",
+    force: options.force ?? false,
+    interactive,
+    ...skillSummary ?? {}
+  });
+  if (skillStepOk) {
+    console.log(
+      formatNextSteps({
+        figmaMcpPresent: figmaMcpRegistered(),
+        skillsInstalled: true,
+        cursorSkillsInstalled: options.cursorSkills === true
+      })
+    );
+  }
+}
+function printSetupGuide() {
+  console.log(`CANICODE SETUP
+`);
+  console.log(
+    `  Never paste your token into Claude/Cursor chat \u2014 use FIGMA_TOKEN=\u2026 npx canicode init or this prompt only.
+`
+  );
+  console.log(`  canicode init                    (interactive prompt; TTY only)`);
+  console.log(`  canicode init --token YOUR_FIGMA_TOKEN   (CI / non-TTY)`);
+  console.log(`  Get token: figma.com > Settings > Personal access tokens
+`);
+  console.log(`Skills:`);
+  console.log(`  --token (or the interactive prompt) also installs three Claude Code skills`);
+  console.log(`  into ./.claude/skills/ (canicode, canicode-gotchas, canicode-roundtrip).`);
+  console.log(`  --global       Install to ~/.claude/skills/ instead`);
+  console.log(`  --cursor-skills Install Claude skills under .claude/skills/ plus Cursor copies under .cursor/skills/ (no --token yet \u2014 add --token when ready for REST analyze)`);
+  console.log(`  --force        Overwrite existing skill files without prompting
+`);
+  console.log(`Manage saved config (no skill reinstall):`);
+  console.log(`  canicode config set-token   Rotate saved Figma token`);
+  console.log(`  canicode config show        Print masked token + paths`);
+  console.log(`  canicode config path        Print absolute config path
+`);
+  console.log(`After setup:`);
+  console.log(`  canicode analyze "https://www.figma.com/design/..."`);
+}
 async function runInitSkillInstallSteps(options) {
   let skillStepOk = true;
   let skillSummary;
@@ -7331,27 +7756,7 @@ ${msg}`);
       }
       const options = parseResult.data;
       if (options.token) {
-        initAiready(options.token);
-        console.log(`  Config saved: ${getConfigPath()}`);
-        console.log(`  Reports will be saved to: ${getReportsDir()}/`);
-        const { skillStepOk, skillSummary } = await runInitSkillInstallSteps(options);
-        trackEvent(EVENTS.CLI_INIT, {
-          skillsRequested: true,
-          cursorSkillsRequested: options.cursorSkills === true,
-          skillStepOk,
-          target: options.global ? "global" : "project",
-          force: options.force ?? false,
-          ...skillSummary ?? {}
-        });
-        if (skillStepOk) {
-          console.log(
-            formatNextSteps({
-              figmaMcpPresent: figmaMcpRegistered(),
-              skillsInstalled: true,
-              cursorSkillsInstalled: options.cursorSkills === true
-            })
-          );
-        }
+        await runFullInit(options.token, options, false);
         return;
       }
       if (wantsSkillInstallWithoutToken(options)) {
@@ -7379,24 +7784,16 @@ ${msg}`);
         }
         return;
       }
-      console.log(`CANICODE SETUP
-`);
-      console.log(
-        `  Never paste your token into Claude/Cursor chat \u2014 use FIGMA_TOKEN=\u2026 npx canicode init or this prompt only.
-`
-      );
-      console.log(`  canicode init --token YOUR_FIGMA_TOKEN`);
-      console.log(`  Get token: figma.com > Settings > Personal access tokens
-`);
-      console.log(`Skills:`);
-      console.log(`  --token also installs three Claude Code skills into ./.claude/skills/`);
-      console.log(`  (canicode, canicode-gotchas, canicode-roundtrip).`);
-      console.log(`  --global       Install to ~/.claude/skills/ instead`);
-      console.log(`  --cursor-skills Install Claude skills under .claude/skills/ plus Cursor copies under .cursor/skills/ (no --token yet \u2014 add --token when ready for REST analyze)`);
-      console.log(`  --force        Overwrite existing skill files without prompting
-`);
-      console.log(`After setup:`);
-      console.log(`  canicode analyze "https://www.figma.com/design/..."`);
+      try {
+        const token = await promptForFigmaToken();
+        await runFullInit(token, options, true);
+        return;
+      } catch (promptError) {
+        if (!(promptError instanceof NonInteractiveError)) {
+          throw promptError;
+        }
+      }
+      printSetupGuide();
     } catch (error) {
       console.error(
         "\nError:",
@@ -7408,28 +7805,85 @@ ${msg}`);
 }
 
 // src/cli/commands/config.ts
+var VALID_ACTIONS = ["set-token", "show", "path"];
+function isConfigAction(value) {
+  return value !== void 0 && VALID_ACTIONS.includes(value);
+}
+function printConfigShow() {
+  const cfg = readConfig();
+  const envToken = process.env["FIGMA_TOKEN"];
+  const effectiveToken = getFigmaToken();
+  const tokenSource = envToken ? " (env: FIGMA_TOKEN)" : "";
+  console.log("CANICODE CONFIG\n");
+  console.log(`  Config path: ${getConfigPath()}`);
+  console.log(`  Reports dir: ${getReportsDir()}`);
+  console.log(`  Figma token: ${maskFigmaToken(effectiveToken)}${tokenSource}`);
+  console.log(`  Telemetry:   ${cfg.telemetry !== false ? "enabled" : "disabled"}`);
+  console.log(`
+Options:`);
+  console.log(`  canicode config set-token         Update saved Figma token (no skill reinstall)`);
+  console.log(`  canicode config show              Show current configuration`);
+  console.log(`  canicode config path              Print absolute config path`);
+  console.log(`  canicode config --no-telemetry    Opt out of anonymous telemetry`);
+  console.log(`  canicode config --telemetry       Opt back in`);
+}
+async function handleSetToken(options) {
+  let token = options.token;
+  const usedFlag = Boolean(token);
+  if (!token) {
+    try {
+      token = await promptForFigmaToken();
+    } catch (err) {
+      if (err instanceof NonInteractiveError) {
+        console.error(
+          "Run with --token <token> or set FIGMA_TOKEN=\u2026 (interactive prompt requires a TTY)."
+        );
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+  }
+  setFigmaToken(token);
+  console.log(`Token saved: ${getConfigPath()}`);
+  trackEvent(EVENTS.CLI_CONFIG_SET_TOKEN, { interactive: !usedFlag });
+}
 function registerConfig(cli2) {
-  cli2.command("config", "Manage canicode configuration").option("--telemetry", "Enable anonymous telemetry").option("--no-telemetry", "Disable anonymous telemetry").action((options) => {
+  cli2.command("config [action]", "Manage canicode configuration (actions: set-token, show, path)").option("--telemetry", "Enable anonymous telemetry").option("--no-telemetry", "Disable anonymous telemetry").option("--token <token>", "For `config set-token`: set token non-interactively (CI / non-TTY)").action(async (action, options) => {
     try {
-      if (options.telemetry === false) {
+      if (action !== void 0 && !isConfigAction(action)) {
+        console.error(
+          `Unknown config action: ${action}. Available: ${VALID_ACTIONS.join(", ")}`
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (action === "set-token") {
+        await handleSetToken(options);
+        return;
+      }
+      if (action === "path") {
+        console.log(getConfigPath());
+        return;
+      }
+      if (action === "show") {
+        printConfigShow();
+        return;
+      }
+      const argv = process.argv.slice(2);
+      const flippedOff = argv.includes("--no-telemetry");
+      const flippedOn = argv.includes("--telemetry");
+      if (flippedOff) {
         setTelemetryEnabled(false);
         console.log("Telemetry disabled. No analytics data will be sent.");
         return;
       }
-      if (options.telemetry === true) {
+      if (flippedOn) {
         setTelemetryEnabled(true);
         console.log("Telemetry enabled. Only anonymous usage events are tracked \u2014 no design data.");
         return;
       }
-      const cfg = readConfig();
-      console.log("CANICODE CONFIG\n");
-      console.log(`  Config path: ${getConfigPath()}`);
-      console.log(`  Figma token: ${cfg.figmaToken ? "set" : "not set"}`);
-      console.log(`  Telemetry:   ${cfg.telemetry !== false ? "enabled" : "disabled"}`);
-      console.log(`
-Options:`);
-      console.log(`  canicode config --no-telemetry    Opt out of anonymous telemetry`);
-      console.log(`  canicode config --telemetry       Opt back in`);
+      printConfigShow();
     } catch (error) {
       console.error(
         "\nError:",
@@ -7440,6 +7894,189 @@ Options:`);
   });
 }
 
+// src/cli/commands/doctor.ts
+init_figma_client();
+var CODE_CONNECT_PKG = "@figma/code-connect";
+var CODE_CONNECT_DOCS = "https://www.figma.com/code-connect-docs/";
+function readPackageJson(cwd) {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return void 0;
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function findCodeConnectVersion(pkg3) {
+  if (!pkg3) return void 0;
+  return pkg3.dependencies?.[CODE_CONNECT_PKG] ?? pkg3.devDependencies?.[CODE_CONNECT_PKG];
+}
+function runCodeConnectChecks(cwd) {
+  const pkg3 = readPackageJson(cwd);
+  const ccVersion = findCodeConnectVersion(pkg3);
+  const figmaConfigExists = existsSync(join(cwd, "figma.config.json"));
+  const results = [];
+  if (ccVersion) {
+    results.push({
+      name: `${CODE_CONNECT_PKG} installed`,
+      pass: true,
+      detail: ccVersion
+    });
+  } else {
+    results.push({
+      name: `${CODE_CONNECT_PKG} not installed`,
+      pass: false,
+      remediation: pkg3 ? `pnpm add -D ${CODE_CONNECT_PKG}  (or npm/yarn equivalent)` : `No package.json found at ${cwd} \u2014 run from your project root, or initialise one first.`
+    });
+  }
+  if (figmaConfigExists) {
+    results.push({
+      name: "figma.config.json found at repo root",
+      pass: true
+    });
+  } else {
+    results.push({
+      name: "figma.config.json not found at repo root",
+      pass: false,
+      remediation: `see ${CODE_CONNECT_DOCS}`
+    });
+  }
+  return results;
+}
+var PUBLISH_CHECK_NAME = "Figma component published in a library";
+async function runFigmaPublishCheck(input) {
+  const { figmaUrl, token, fetchPublishedComponents } = input;
+  let parsed;
+  try {
+    parsed = parseFigmaUrl(figmaUrl);
+  } catch (err) {
+    const message = err instanceof FigmaUrlParseError ? err.message : String(err);
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: `could not parse URL: ${message}`,
+      remediation: "Pass a valid Figma design URL (figma.com/design/<file>?node-id=<id>)."
+    };
+  }
+  if (!parsed.nodeId) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "URL is missing a node-id",
+      remediation: "Code Connect mapping is per-component \u2014 invoke with a URL that targets a specific node (?node-id=\u2026)."
+    };
+  }
+  if (!token) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "FIGMA_TOKEN not configured \u2014 skipping publish-status check",
+      remediation: "Set FIGMA_TOKEN (env var) or run `canicode config set-token` so doctor can verify this prereq inline."
+    };
+  }
+  if (!fetchPublishedComponents) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "no fetcher wired",
+      remediation: "internal: doctor was called without a Figma client"
+    };
+  }
+  let components;
+  try {
+    components = await fetchPublishedComponents(parsed.fileKey);
+  } catch (err) {
+    const status = err instanceof FigmaClientError ? err.statusCode : void 0;
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: `Figma API call failed${status ? ` (HTTP ${status})` : ""}: ${message}`,
+      remediation: "Step 7d will rely on the API as the authority; if your token / network is OK, the canicode-roundtrip step itself will surface the publish error inline."
+    };
+  }
+  const canonicalNodeId = parsed.nodeId.replace(/-/g, ":");
+  const match = components.find(
+    (c) => c.node_id === canonicalNodeId || c.node_id === parsed.nodeId
+  );
+  if (match) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: true,
+      detail: `${match.name} (${match.node_id})`
+    };
+  }
+  return {
+    name: PUBLISH_CHECK_NAME,
+    pass: false,
+    detail: `node ${canonicalNodeId} is not in the published-components list for file ${parsed.fileKey}`,
+    remediation: "Open the file in Figma \u2192 Assets panel \u2192 Publish library and include this component. Without publishing, `add_code_connect_map` fails with 'Published component not found.'"
+  };
+}
+function formatDoctorReport(results) {
+  const lines = ["Code Connect"];
+  for (const result of results) {
+    const icon = result.pass ? "\u2705" : result.inconclusive ? "\u26A0\uFE0F" : "\u274C";
+    const detail = result.detail ? ` (${result.detail})` : "";
+    lines.push(`  ${icon} ${result.name}${detail}`);
+    if (!result.pass && result.remediation) {
+      lines.push(`     \u2192 ${result.remediation}`);
+    }
+  }
+  lines.push("");
+  const blocking = results.filter((r) => !r.pass && !r.inconclusive).length;
+  const inconclusive = results.filter((r) => !r.pass && r.inconclusive).length;
+  if (blocking === 0 && inconclusive === 0) {
+    lines.push("All checks passed.");
+  } else if (blocking === 0) {
+    lines.push(
+      "Blocking checks passed; some checks were skipped (\u26A0\uFE0F) and could not be verified."
+    );
+  } else {
+    lines.push("Some checks failed. Fix the items above before running the Code Connect flow.");
+  }
+  return lines.join("\n");
+}
+function registerDoctor(cli2) {
+  cli2.command(
+    "doctor",
+    "Diagnose Code Connect prerequisites (`@figma/code-connect`, `figma.config.json`)"
+  ).option(
+    "--figma-url <url>",
+    "Optionally check that the target Figma component is published in a library (requires FIGMA_TOKEN)"
+  ).action(async (options) => {
+    const cwd = process.cwd();
+    const results = runCodeConnectChecks(cwd);
+    if (options.figmaUrl) {
+      const token = getFigmaToken();
+      const client = token ? new FigmaClient({ token }) : void 0;
+      const publishCheck = await runFigmaPublishCheck({
+        figmaUrl: options.figmaUrl,
+        token,
+        fetchPublishedComponents: client ? (fileKey) => client.getPublishedComponents(fileKey) : void 0
+      });
+      results.push(publishCheck);
+    }
+    console.log(formatDoctorReport(results));
+    const passed = results.filter((r) => r.pass).length;
+    const inconclusive = results.filter((r) => !r.pass && r.inconclusive).length;
+    const failed = results.length - passed - inconclusive;
+    trackEvent(EVENTS.CLI_DOCTOR, {
+      passed,
+      failed,
+      total: results.length
+    });
+    if (failed > 0) {
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/cli/commands/list-rules.ts
 function registerListRules(cli2) {
   cli2.command("list-rules", "List all analysis rules with scores and severity").option("--config <path>", "Apply config overrides to show effective scores").option("--json", "Output as JSON").action(async (options) => {
@@ -10566,8 +11203,8 @@ ${msg}`);
       if (vectorDir && existsSync(vectorDir)) {
         const vecOutputDir = resolve(outputDir, "vectors");
         mkdirSync(vecOutputDir, { recursive: true });
-        const { readdirSync: readdirSync4, copyFileSync: copyFileSync3 } = await import('fs');
-        const vecFiles = readdirSync4(vectorDir).filter((f) => f.endsWith(".svg") || f === "mapping.json");
+        const { readdirSync: readdirSync5, copyFileSync: copyFileSync3 } = await import('fs');
+        const vecFiles = readdirSync5(vectorDir).filter((f) => f.endsWith(".svg") || f === "mapping.json");
         for (const f of vecFiles) {
           copyFileSync3(resolve(vectorDir, f), resolve(vecOutputDir, f));
         }
@@ -10577,8 +11214,8 @@ ${msg}`);
       if (imageDir && existsSync(imageDir)) {
         const imgOutputDir = resolve(outputDir, "images");
         mkdirSync(imgOutputDir, { recursive: true });
-        const { readdirSync: readdirSync4, copyFileSync: copyFileSync3 } = await import('fs');
-        const imgFiles = readdirSync4(imageDir).filter((f) => f.endsWith(".png") || f.endsWith(".jpg") || f.endsWith(".json"));
+        const { readdirSync: readdirSync5, copyFileSync: copyFileSync3 } = await import('fs');
+        const imgFiles = readdirSync5(imageDir).filter((f) => f.endsWith(".png") || f.endsWith(".jpg") || f.endsWith(".json"));
         for (const f of imgFiles) {
           copyFileSync3(resolve(imageDir, f), resolve(imgOutputDir, f));
         }
@@ -10786,6 +11423,7 @@ registerDesignTree(cli);
 registerVisualCompare(cli);
 registerInit(cli);
 registerConfig(cli);
+registerDoctor(cli);
 registerListRules(cli);
 registerRoundtripTally(cli);
 registerCalibrateAnalyze(cli);
@@ -10815,7 +11453,11 @@ cli.help((sections) => {
   sections.push(
     {
       title: "\nSetup",
-      body: `  canicode init --token <token>   Save Figma token to ~/.canicode/`
+      body: [
+        `  canicode init                   Interactive setup (prompts for token)`,
+        `  canicode init --token <token>   Non-interactive setup (CI / non-TTY)`,
+        `  canicode config set-token       Rotate token without reinstalling skills`
+      ].join("\n")
     },
     {
       title: "\nData source",