canicode 0.9.1 → 0.10.1

package/dist/mcp/server.js

@@ -510,6 +510,44 @@ function getConfigsWithPreset(preset) {
   }
   return configs;
 }
+var RULE_ANNOTATION_PROPERTIES = {
+  "missing-size-constraint": {
+    default: [{ type: "width" }, { type: "height" }]
+  },
+  "irregular-spacing": {
+    bySubType: {
+      gap: [{ type: "itemSpacing" }],
+      padding: [{ type: "padding" }]
+    }
+  },
+  "fixed-size-in-auto-layout": {
+    default: [{ type: "width" }, { type: "height" }, { type: "layoutMode" }]
+  },
+  "raw-value": {
+    bySubType: {
+      color: [{ type: "fills" }],
+      font: [
+        { type: "fontSize" },
+        { type: "fontFamily" },
+        { type: "fontWeight" },
+        { type: "lineHeight" }
+      ],
+      spacing: [{ type: "itemSpacing" }, { type: "padding" }]
+    }
+  },
+  "absolute-position-in-auto-layout": {
+    default: [{ type: "layoutMode" }]
+  }
+};
+function getAnnotationProperties(ruleId, subType) {
+  const entry = RULE_ANNOTATION_PROPERTIES[ruleId];
+  if (!entry) return void 0;
+  if (subType !== void 0 && entry.bySubType) {
+    const match = entry.bySubType[subType];
+    if (match) return match;
+  }
+  return entry.default;
+}
 function getRuleOption(ruleId, optionKey, defaultValue) {
   const config2 = RULE_CONFIGS[ruleId];
   if (!config2.options) return defaultValue;
@@ -1625,8 +1663,97 @@ async function loadFromApi(fileKey, nodeId, token) {
   return { file, nodeId };
 }
 
+// src/core/adapters/instance-id-parser.ts
+function isInstanceChildNodeId(nodeId) {
+  return nodeId.startsWith("I") && nodeId.includes(";");
+}
+function parseInstanceChildNodeId(nodeId) {
+  if (!isInstanceChildNodeId(nodeId)) return null;
+  const segments = nodeId.split(";");
+  if (segments.length < 2) return null;
+  const parentInstanceId = segments[0].replace(/^I/, "");
+  const sourceNodeId = segments[segments.length - 1];
+  if (!parentInstanceId || !sourceNodeId) return null;
+  return { parentInstanceId, sourceNodeId };
+}
+
+// src/core/gotcha/apply-context.ts
+var STRATEGY_BY_RULE = {
+  // Strategy A — property modification
+  "no-auto-layout": "property-mod",
+  "fixed-size-in-auto-layout": "property-mod",
+  "missing-size-constraint": "property-mod",
+  "irregular-spacing": "property-mod",
+  "non-semantic-name": "property-mod",
+  // Strategy B — structural modification (needs user confirmation)
+  "non-layout-container": "structural-mod",
+  "deep-nesting": "structural-mod",
+  "missing-component": "structural-mod",
+  "detached-instance": "structural-mod",
+  // Strategy C — annotation only
+  "absolute-position-in-auto-layout": "annotation",
+  "variant-structure-mismatch": "annotation",
+  // Strategy D — auto-fix lower-severity issues from analyze output
+  "non-standard-naming": "auto-fix",
+  "inconsistent-naming-convention": "auto-fix",
+  "raw-value": "auto-fix",
+  "missing-interaction-state": "auto-fix",
+  "missing-prototype": "auto-fix"
+};
+function resolveTargetProperty(ruleId, subType) {
+  switch (ruleId) {
+    case "no-auto-layout":
+      return ["layoutMode", "itemSpacing"];
+    case "fixed-size-in-auto-layout":
+      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";
+      return ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft"];
+    case "non-semantic-name":
+      return "name";
+    case "non-layout-container":
+      return "layoutMode";
+    case "non-standard-naming":
+    case "inconsistent-naming-convention":
+      return "name";
+    case "deep-nesting":
+    case "missing-component":
+    case "detached-instance":
+    case "absolute-position-in-auto-layout":
+    case "variant-structure-mismatch":
+    case "raw-value":
+    case "missing-interaction-state":
+    case "missing-prototype":
+      return void 0;
+  }
+}
+function computeApplyContext(violation, instanceContext) {
+  const ruleId = violation.ruleId;
+  const applyStrategy = STRATEGY_BY_RULE[ruleId] ?? "annotation";
+  const targetProperty = resolveTargetProperty(ruleId, violation.subType);
+  const annotationProperties = getAnnotationProperties(
+    ruleId,
+    violation.subType
+  );
+  const parsed = parseInstanceChildNodeId(violation.nodeId);
+  const isInstanceChild = parsed !== null || isInstanceChildNodeId(violation.nodeId);
+  const sourceChildId = instanceContext?.sourceNodeId ?? parsed?.sourceNodeId;
+  return {
+    applyStrategy,
+    ...targetProperty !== void 0 ? { targetProperty } : {},
+    ...annotationProperties !== void 0 ? { annotationProperties } : {},
+    isInstanceChild,
+    ...sourceChildId !== void 0 ? { sourceChildId } : {}
+  };
+}
+
 // package.json
-var version = "0.9.1";
+var version = "0.10.1";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -1655,6 +1782,9 @@ function calculateGrade(percentage) {
   if (percentage >= 50) return "D";
   return "F";
 }
+function isReadyForCodeGen(grade) {
+  return grade === "S" || grade === "A+" || grade === "A";
+}
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
@@ -1802,14 +1932,24 @@ function buildResultJson(fileName, result, scores, options) {
     const id = issue.violation.ruleId;
     issuesByRule[id] = (issuesByRule[id] ?? 0) + 1;
   }
-  const issues = result.issues.map((issue) => ({
-    ruleId: issue.violation.ruleId,
-    ...issue.violation.subType && { subType: issue.violation.subType },
-    severity: issue.config.severity,
-    nodeId: issue.violation.nodeId,
-    nodePath: issue.violation.nodePath,
-    message: issue.violation.message
-  }));
+  const issues = result.issues.map((issue) => {
+    const applyContext = computeApplyContext(issue.violation);
+    const suggestedName = issue.violation.suggestedName;
+    return {
+      ruleId: issue.violation.ruleId,
+      ...issue.violation.subType && { subType: issue.violation.subType },
+      severity: issue.config.severity,
+      nodeId: issue.violation.nodeId,
+      nodePath: issue.violation.nodePath,
+      message: issue.violation.message,
+      applyStrategy: applyContext.applyStrategy,
+      ...applyContext.targetProperty !== void 0 ? { targetProperty: applyContext.targetProperty } : {},
+      ...applyContext.annotationProperties !== void 0 ? { annotationProperties: applyContext.annotationProperties } : {},
+      ...suggestedName !== void 0 ? { suggestedName } : {},
+      isInstanceChild: applyContext.isInstanceChild,
+      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
+    };
+  });
   const json = {
     version,
     analyzedAt: result.analyzedAt,
@@ -1818,6 +1958,8 @@ function buildResultJson(fileName, result, scores, options) {
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
     issueCount: result.issues.length,
+    isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
+    blockingIssueCount: scores.summary.blocking,
     scores: {
       overall: scores.overall,
       categories: scores.byCategory
@@ -1831,6 +1973,219 @@ function buildResultJson(fileName, result, scores, options) {
   }
   return json;
 }
+z.object({
+  ruleId: z.string(),
+  question: z.string(),
+  hint: z.string(),
+  example: z.string()
+});
+var GOTCHA_QUESTIONS = {
+  // ── Pixel Critical (blocking) ──
+  "no-auto-layout": {
+    ruleId: "no-auto-layout",
+    question: 'Frame "{nodeName}" has no Auto Layout. How should this area be laid out?',
+    hint: "Describe the flex direction, gap, and alignment",
+    example: "Vertical flex, gap 16px, items centered"
+  },
+  "absolute-position-in-auto-layout": {
+    ruleId: "absolute-position-in-auto-layout",
+    question: '"{nodeName}" uses absolute positioning inside an Auto Layout parent. Is this an intentional overlay, or should it flow with the layout?',
+    hint: "Specify if this is a badge/overlay, or should be part of the normal flow",
+    example: "This is a notification badge \u2014 position absolute, top-right corner"
+  },
+  "non-layout-container": {
+    ruleId: "non-layout-container",
+    question: '"{nodeName}" is a Group/Section used as a layout container. What layout structure should it have?',
+    hint: "Describe the intended layout: flex direction, wrap, gap",
+    example: "Horizontal flex, gap 12px, wrap on mobile"
+  },
+  // ── Responsive Critical (risk) ──
+  "fixed-size-in-auto-layout": {
+    ruleId: "fixed-size-in-auto-layout",
+    question: '"{nodeName}" has a fixed size inside Auto Layout. Should it be responsive?',
+    hint: "Specify which axis should be flexible (width, height, or both)",
+    example: "Width should FILL the parent, height can stay fixed"
+  },
+  "missing-size-constraint": {
+    ruleId: "missing-size-constraint",
+    question: '"{nodeName}" uses FILL sizing without min/max constraints. What are the size boundaries?',
+    hint: "Provide min-width, max-width, or both",
+    example: "min-width 320px, max-width 1200px"
+  },
+  // ── Code Quality (risk) ──
+  "missing-component": {
+    ruleId: "missing-component",
+    question: '"{nodeName}" appears to be a repeated structure. Should it be a reusable component?',
+    hint: "Describe if this should be extracted as a component and what props it needs",
+    example: "Yes, extract as ProductCard component with title, image, and price props"
+  },
+  "detached-instance": {
+    ruleId: "detached-instance",
+    question: '"{nodeName}" looks like a detached component instance. Should it use the original component or is it a new variant?',
+    hint: "Specify whether to restore the component link or create a new variant",
+    example: "This is a new variant \u2014 create a 'compact' variant of the original component"
+  },
+  "variant-structure-mismatch": {
+    ruleId: "variant-structure-mismatch",
+    question: '"{nodeName}" has variants with different child structures. Which structure is the canonical one?',
+    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"
+  },
+  "deep-nesting": {
+    ruleId: "deep-nesting",
+    question: '"{nodeName}" is deeply nested. Can some intermediate layers be flattened or extracted?',
+    hint: "Identify which wrapper layers are unnecessary or should become sub-components",
+    example: "The inner wrapper is just for spacing \u2014 flatten it and use padding instead"
+  },
+  // ── Token Management ──
+  "raw-value": {
+    ruleId: "raw-value",
+    question: '"{nodeName}" uses raw values without design tokens. What tokens should be used?',
+    hint: "Specify the token names or variable references for colors, fonts, spacing, etc.",
+    example: "Use $color-primary for the fill, $font-body for the text style"
+  },
+  "irregular-spacing": {
+    ruleId: "irregular-spacing",
+    question: '"{nodeName}" has spacing values that are off the design grid. What should the correct spacing be?',
+    hint: "Provide the intended spacing value aligned to the grid system",
+    example: "Gap should be 16px (4pt grid), not 15px"
+  },
+  // ── Interaction ──
+  "missing-interaction-state": {
+    ruleId: "missing-interaction-state",
+    question: '"{nodeName}" appears interactive but is missing state variants. What interaction states are needed?',
+    hint: "List the needed states: Hover, Active, Disabled, Focus",
+    example: "Needs Hover (darken 10%) and Disabled (opacity 50%, no pointer events)"
+  },
+  "missing-prototype": {
+    ruleId: "missing-prototype",
+    question: '"{nodeName}" looks interactive but has no prototype interaction. What should happen on click/interaction?',
+    hint: "Describe the interaction behavior: navigation, overlay, state change, etc.",
+    example: "On click, navigate to the product detail page"
+  },
+  // ── Semantic ──
+  "non-standard-naming": {
+    ruleId: "non-standard-naming",
+    question: '"{nodeName}" uses non-standard state names. What naming convention should be followed?',
+    hint: "Specify the expected state name format (e.g., Hover, Disabled, Active)",
+    example: 'Use "Hover" instead of "hover_v1", "Disabled" instead of "off"'
+  },
+  "non-semantic-name": {
+    ruleId: "non-semantic-name",
+    question: '"{nodeName}" has a non-semantic name. What is the purpose of this element?',
+    hint: "Provide a descriptive name that reflects the element's role in the UI",
+    example: 'Rename "Frame 12" to "HeroSection" or "ProductGrid"'
+  },
+  "inconsistent-naming-convention": {
+    ruleId: "inconsistent-naming-convention",
+    question: '"{nodeName}" uses a different naming convention than its siblings. Which convention should be used?',
+    hint: "Choose one: camelCase, kebab-case, PascalCase, or Title Case",
+    example: "Use PascalCase for all component layers (e.g., CardTitle, CardBody)"
+  }
+};
+
+// src/core/gotcha/survey-generator.ts
+var NODE_PATH_SEPARATOR = " > ";
+function generateGotchaSurvey(result, scores) {
+  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);
+  return {
+    designGrade: grade,
+    isReadyForCodeGen: isReadyForCodeGen(grade),
+    questions
+  };
+}
+function deduplicateSiblingIssues(issues) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const issue of issues) {
+    const parentPath = getParentPath(issue.violation.nodePath);
+    const key = `${parentPath}||${issue.violation.ruleId}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(issue);
+    }
+  }
+  return result;
+}
+function getParentPath(nodePath) {
+  const lastSep = nodePath.lastIndexOf(NODE_PATH_SEPARATOR);
+  if (lastSep === -1) return "";
+  return nodePath.slice(0, lastSep);
+}
+function getNodeName(nodePath) {
+  const lastSep = nodePath.lastIndexOf(NODE_PATH_SEPARATOR);
+  if (lastSep === -1) return nodePath;
+  return nodePath.slice(lastSep + NODE_PATH_SEPARATOR.length);
+}
+function stableSortBySeverity(issues) {
+  const blocking = [];
+  const risk = [];
+  for (const issue of issues) {
+    if (issue.config.severity === "blocking") {
+      blocking.push(issue);
+    } else {
+      risk.push(issue);
+    }
+  }
+  return [...blocking, ...risk];
+}
+function mapToQuestion(issue, file) {
+  const ruleId = issue.violation.ruleId;
+  const template = GOTCHA_QUESTIONS[ruleId];
+  if (!template) return null;
+  const nodeName = getNodeName(issue.violation.nodePath);
+  const instanceContext = buildInstanceContext(issue.violation.nodeId, file);
+  const applyContext = computeApplyContext(
+    issue.violation,
+    instanceContext ?? void 0
+  );
+  const suggestedName = issue.violation.suggestedName;
+  return {
+    nodeId: issue.violation.nodeId,
+    nodeName,
+    ruleId,
+    severity: issue.config.severity,
+    question: template.question.replace("{nodeName}", nodeName),
+    hint: template.hint,
+    example: template.example,
+    ...instanceContext ? { instanceContext } : {},
+    applyStrategy: applyContext.applyStrategy,
+    ...applyContext.targetProperty !== void 0 ? { targetProperty: applyContext.targetProperty } : {},
+    ...applyContext.annotationProperties !== void 0 ? { annotationProperties: applyContext.annotationProperties } : {},
+    ...suggestedName !== void 0 ? { suggestedName } : {},
+    isInstanceChild: applyContext.isInstanceChild,
+    ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
+  };
+}
+function buildInstanceContext(nodeId, file) {
+  const parts = parseInstanceChildNodeId(nodeId);
+  if (!parts) return null;
+  const parentInstance = findNodeById2(file.document, parts.parentInstanceId);
+  const componentId = parentInstance?.componentId;
+  const componentName = componentId ? file.components[componentId]?.name : void 0;
+  return {
+    parentInstanceNodeId: parts.parentInstanceId,
+    sourceNodeId: parts.sourceNodeId,
+    ...componentId ? { sourceComponentId: componentId } : {},
+    ...componentName ? { sourceComponentName: componentName } : {}
+  };
+}
+function findNodeById2(node, id) {
+  if (node.id === id) return node;
+  if (node.children) {
+    for (const child of node.children) {
+      const found = findNodeById2(child, id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
 
 // src/core/ui-constants.ts
 var GAUGE_R = 54;
@@ -2998,7 +3353,14 @@ var EVENTS = {
   MCP_TOOL_CALLED: `${EVENT_PREFIX}mcp_tool_called`,
   // CLI
   CLI_COMMAND: `${EVENT_PREFIX}cli_command`,
-  CLI_INIT: `${EVENT_PREFIX}cli_init`
+  CLI_INIT: `${EVENT_PREFIX}cli_init`,
+  // 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
+  // cannot import `core/monitoring` directly, so the event fires through a
+  // caller-supplied callback. Define the typed name here so a future consumer
+  // has a single place to wire it up.
+  ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`
 };
 
 // src/core/monitoring/capture.ts
@@ -4113,6 +4475,10 @@ defineRule({
 });
 
 // src/core/rules/naming/index.ts
+function capitalize(s) {
+  if (!s) return s;
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 function detectNamingConvention(name) {
   if (/^[a-z]+(-[a-z]+)*$/.test(name)) return "kebab-case";
   if (/^[a-z]+(_[a-z]+)*$/.test(name)) return "snake_case";
@@ -4238,6 +4604,7 @@ var inconsistentNamingConventionCheck = (node, context) => {
       ruleId: inconsistentNamingConventionDef.id,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
+      suggestedName: suggested,
       ...inconsistentNamingMsg(node.name, nodeConvention, dominantConvention, suggested)
     };
   }
@@ -4275,6 +4642,7 @@ var nonStandardNamingCheck = (node, context) => {
             subType: "state-name",
             nodeId: node.id,
             nodePath: context.path.join(" > "),
+            suggestedName: capitalize(suggestion),
             ...nonStandardNamingMsg.stateName(node.name, opt, suggestion)
           };
         }
@@ -4531,6 +4899,78 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     }
   }
 );
+server.tool(
+  "gotcha-survey",
+  `Generate a gotcha survey from a Figma design analysis.
+
+Analyzes the design and returns a GotchaSurvey JSON with designGrade, isReadyForCodeGen, and questions[].
+When isReadyForCodeGen is true, questions will be empty (no survey needed).
+
+Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKEN env var or the token parameter for live Figma URLs.`,
+  {
+    input: z.string().describe("Figma URL or local fixture path. Requires FIGMA_TOKEN for live URLs."),
+    token: z.string().optional().describe("Figma API token (falls back to FIGMA_TOKEN env var)"),
+    preset: z.enum(["relaxed", "dev-friendly", "ai-ready", "strict"]).optional().describe("Analysis preset"),
+    targetNodeId: z.string().optional().describe("Scope analysis to a specific node ID"),
+    configPath: z.string().optional().describe("Path to config JSON file for rule overrides")
+  },
+  {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+    title: "Gotcha Survey"
+  },
+  async ({ input, token, preset, targetNodeId, configPath }) => {
+    trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "gotcha-survey" });
+    try {
+      const { file, nodeId } = await loadFile(input, token);
+      const effectiveNodeId = targetNodeId ?? nodeId;
+      let configs = preset ? { ...getConfigsWithPreset(preset) } : { ...RULE_CONFIGS };
+      if (configPath) {
+        const configFile = await loadConfigFile(configPath);
+        configs = mergeConfigs(configs, configFile);
+      }
+      const result = analyzeFile(file, {
+        configs,
+        ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
+      });
+      const scores = calculateScores(result, configs);
+      const survey = generateGotchaSurvey(result, scores);
+      trackEvent(EVENTS.ANALYSIS_COMPLETED, {
+        nodeCount: result.nodeCount,
+        issueCount: result.issues.length,
+        grade: scores.overall.grade,
+        percentage: scores.overall.percentage,
+        source: isJsonFile(input) || isFixtureDir(input) ? "fixture" : "figma"
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(survey, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      trackError(
+        error instanceof Error ? error : new Error(String(error)),
+        { tool: "gotcha-survey" }
+      );
+      trackEvent(EVENTS.ANALYSIS_FAILED, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
 server.tool(
   "list-rules",
   "List all available analysis rules with their current configuration",
@@ -4584,6 +5024,7 @@ server.tool(
 
 Available topics:
 - setup: Installation and token configuration
+- scoring: Scoring model formula (density+diversity, severity weights, grades)
 - rules: All rule IDs with default scores and severity
 - config: Config overrides (scores, severity, node exclusions, thresholds)
 - visual-compare: Pixel-level comparison between Figma and AI-generated code
@@ -4592,7 +5033,7 @@ Available topics:
 
 Use this when the user asks about how to use canicode, configuration, rules, visual comparison, or any feature.`,
   {
-    topic: z.enum(["all", "setup", "rules", "config", "visual-compare", "design-tree"]).optional().describe("Topic to retrieve. Default: all")
+    topic: z.enum(["all", "setup", "scoring", "rules", "config", "visual-compare", "design-tree"]).optional().describe("Topic to retrieve. Default: all")
   },
   {
     readOnlyHint: true,
@@ -4618,7 +5059,18 @@ Get your token: Figma \u2192 Settings \u2192 Security \u2192 Personal access tok
 claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
 \`\`\`
 
-Requires FIGMA_TOKEN for live Figma URL analysis.`,
+Requires FIGMA_TOKEN for live Figma URL analysis.
+
+## CLI only (no MCP server)
+
+User-facing MCP tools have CLI equivalents with the same JSON shape, so skills and scripts can run without installing the canicode MCP server:
+
+\`\`\`bash
+npx canicode analyze <input>
+npx canicode gotcha-survey <input> --json
+\`\`\`
+
+The CLI spawns per call (slower than the long-running MCP server) but needs no extra setup beyond \`FIGMA_TOKEN\`.`,
       "visual-compare": `# Visual Compare
 
 Pixel-level comparison between Figma design and AI-generated code.
@@ -4664,6 +5116,36 @@ Viewport and device pixel ratio are auto-inferred from the Figma PNG dimensions
 ## Requirements
 - npx playwright install chromium
 - Figma API token with read access`,
+      "scoring": `# Scoring Model
+
+Score = density (70%) + diversity (30%), averaged across 6 categories.
+
+## Severity weights
+
+| Severity | Weight |
+|----------|--------|
+| blocking | 3.0x |
+| risk | 2.0x |
+| missing-info | 1.0x |
+| suggestion | 0.5x |
+
+## Grades
+
+| Grade | Min score |
+|-------|-----------|
+| S | 95 |
+| A+ | 90 |
+| A | 85 |
+| B+ | 80 |
+| B | 75 |
+| C+ | 70 |
+| C | 65 |
+| D | 50 |
+| F | <50 |
+
+Floor: 5% minimum.
+
+Full documentation: https://github.com/let-sunny/canicode/wiki/Scoring-Model`,
       "design-tree": `# Design Tree
 
 Generate a DOM-like design tree from a Figma fixture. Converts the node tree to a concise text format with inline CSS styles \u2014 50-100x smaller than raw JSON.