@cobwds/mcp-server 1.19.3 → 1.23.1

package/dist/resources/frameworks.js

@@ -0,0 +1,104 @@
+/**
+ * Framework Resources
+ *
+ * MCP resources for COBWDS framework packages (@cobwds/react, @cobwds/vue,
+ * @cobwds/angular).
+ *
+ * Resources:
+ * - cobwds://frameworks - Index of framework packages with version and guide URI
+ * - cobwds://frameworks/react - @cobwds/react guide (synced from its README)
+ * - cobwds://frameworks/vue - @cobwds/vue guide (synced from its README)
+ * - cobwds://frameworks/angular - @cobwds/angular guide (synced from its README)
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getFrameworksIndex } from "../lib/frameworks-data.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const GUIDES_DIR = join(__dirname, "../../data/guides/frameworks");
+function loadFrameworkGuide(framework) {
+    try {
+        return readFileSync(join(GUIDES_DIR, `${framework}.md`), "utf-8");
+    }
+    catch {
+        return `Framework guide not found: ${framework}. Run "npm run sync:guides -w @cobwds/mcp-server".`;
+    }
+}
+export function registerFrameworkResources(server) {
+    // cobwds://frameworks - Index of framework packages
+    server.resource("frameworks", "cobwds://frameworks", {
+        description: "Index of COBWDS framework packages (@cobwds/react, @cobwds/vue, @cobwds/angular) with their published version and guide resource URI",
+        mimeType: "application/json",
+    }, async () => {
+        const index = getFrameworksIndex();
+        const list = [
+            {
+                id: "react",
+                packageName: index.react.packageName,
+                version: index.react.version,
+                guideUri: "cobwds://frameworks/react",
+            },
+            {
+                id: "vue",
+                packageName: index.vue.packageName,
+                version: index.vue.version,
+                guideUri: "cobwds://frameworks/vue",
+            },
+            {
+                id: "angular",
+                packageName: index.angular.packageName,
+                version: index.angular.version,
+                guideUri: "cobwds://frameworks/angular",
+            },
+        ];
+        return {
+            contents: [
+                {
+                    uri: "cobwds://frameworks",
+                    mimeType: "application/json",
+                    text: JSON.stringify(list, null, 2),
+                },
+            ],
+        };
+    });
+    // cobwds://frameworks/react - @cobwds/react guide
+    server.resource("frameworks-react", "cobwds://frameworks/react", {
+        description: "@cobwds/react install, usage, forms, SSR, and troubleshooting guide",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "cobwds://frameworks/react",
+                mimeType: "text/markdown",
+                text: loadFrameworkGuide("react"),
+            },
+        ],
+    }));
+    // cobwds://frameworks/vue - @cobwds/vue guide
+    server.resource("frameworks-vue", "cobwds://frameworks/vue", {
+        description: "@cobwds/vue install, usage, v-model forms, SSR, and troubleshooting guide",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "cobwds://frameworks/vue",
+                mimeType: "text/markdown",
+                text: loadFrameworkGuide("vue"),
+            },
+        ],
+    }));
+    // cobwds://frameworks/angular - @cobwds/angular guide
+    server.resource("frameworks-angular", "cobwds://frameworks/angular", {
+        description: "@cobwds/angular install, usage, forms, SSR, and troubleshooting guide",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "cobwds://frameworks/angular",
+                mimeType: "text/markdown",
+                text: loadFrameworkGuide("angular"),
+            },
+        ],
+    }));
+}

package/dist/resources/guides.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guides.d.ts","sourceRoot":"","sources":["../../src/resources/guides.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAyE9D"}
+{"version":3,"file":"guides.d.ts","sourceRoot":"","sources":["../../src/resources/guides.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoF9D"}

package/dist/resources/guides.js

@@ -56,7 +56,18 @@ Then use them in HTML:
 
 ## Framework Integration
 
-For framework-specific setup, use the \`get_guide\` tool with \`topic: "framework"\` and a \`framework\` parameter (angular, react, dotnet, drupal, or vanilla).
+For framework-specific setup, use the \`get_guide\` tool with a \`topic\` and a \`framework\` parameter (angular, react, vue, dotnet, drupal, or vanilla).
+
+React, Vue, and Angular are first-class packages, not wrapper snippets:
+\`@cobwds/react\` (\`npm install @cobwds/react\`), \`@cobwds/vue\`
+(\`npm install @cobwds/vue\`), and \`@cobwds/angular\`
+(\`npm install @cobwds/angular @cobwds/components\`) generate typed
+components, props, and events directly from this design system's
+manifest. See the \`cobwds://frameworks\` resource for their current
+published versions, \`cobwds://frameworks/react\`, \`cobwds://frameworks/vue\`, and
+\`cobwds://frameworks/angular\` for their full guides, and pass
+\`framework: "react"\` or \`"angular"\` to \`get_component\` for
+per-component import lines and framework-specific code examples.
 
 ## Resources
 

package/dist/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAIzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAKzD"}

package/dist/resources/index.js

@@ -6,8 +6,10 @@
 import { registerComponentResources } from "./components.js";
 import { registerTokenResources } from "./tokens.js";
 import { registerGuideResources } from "./guides.js";
+import { registerFrameworkResources } from "./frameworks.js";
 export function registerResources(server) {
     registerComponentResources(server);
     registerTokenResources(server);
     registerGuideResources(server);
+    registerFrameworkResources(server);
 }

package/dist/tools/component-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-tools.d.ts","sourceRoot":"","sources":["../../src/tools/component-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+G9D"}
+{"version":3,"file":"component-tools.d.ts","sourceRoot":"","sources":["../../src/tools/component-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2I9D"}

package/dist/tools/component-tools.js

@@ -10,6 +10,8 @@
 import { z } from "zod";
 import { getComponent, getAllComponents } from "../lib/cem-parser.js";
 import { searchComponents } from "../lib/search.js";
+import { buildExampleSnippets, } from "../lib/framework-snippets.js";
+import { buildAngularUsageNotes, buildReactUsageNotes, } from "../lib/framework-usage.js";
 export function registerComponentTools(server) {
     // find_components - Search or list all components
     server.tool("find_components", "Search for COBWDS components by name or description. Omit query to list all components.", {
@@ -51,15 +53,19 @@ export function registerComponentTools(server) {
         };
     });
     // get_component - Full documentation for a specific component
-    server.tool("get_component", "Get full documentation for a specific COBWDS component including properties, events, slots, and CSS custom properties", {
+    server.tool("get_component", "Get full documentation for a specific COBWDS component including properties, events, slots, and CSS custom properties. Set framework to 'react' or 'angular' to get that framework's import line, event-prop naming, and forms guidance alongside HTML/React/Angular code examples.", {
         tagName: z
             .string()
             .describe("The tag name of the component (e.g., 'cob-button')"),
         includeExamples: z
             .boolean()
             .default(false)
-            .describe("Include HTML code examples from component JSDoc. Set to true when you need usage patterns."),
-    }, async ({ tagName, includeExamples }) => {
+            .describe("Include code examples from component JSDoc. Set to true when you need usage patterns. Each example carries html, react, and angular snippets."),
+        framework: z
+            .enum(["html", "react", "angular"])
+            .default("html")
+            .describe("Which framework to optimize the response for. 'html' (default) returns plain custom-element usage. 'react' and 'angular' add framework-specific usage notes (import line, event-prop naming, forms binding) and, for a form-control component, transform that framework's example snippets into its idiomatic controlled/reactive-forms pattern."),
+    }, async ({ tagName, includeExamples, framework }) => {
         const component = getComponent(tagName);
         if (!component) {
             return {
@@ -76,16 +82,25 @@ export function registerComponentTools(server) {
         // Attributes contains the HTML API, members duplicates this plus private methods
         const { 
         // members: _members,
-        examples, ...componentWithoutMembers } = component;
+        examples, formControl, ...componentWithoutMembers } = component;
+        const usage = {};
+        if (framework === "react") {
+            usage.react = buildReactUsageNotes(tagName, component.name, formControl);
+        }
+        else if (framework === "angular") {
+            usage.angular = buildAngularUsageNotes(tagName, component.name, formControl);
+        }
         return {
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
                         ...componentWithoutMembers,
+                        formControl,
                         examples: includeExamples && examples && examples.length > 0
-                            ? examples
+                            ? buildExampleSnippets(examples, framework, formControl)
                             : undefined,
+                        usage: Object.keys(usage).length > 0 ? usage : undefined,
                         resourceUri: `cobwds://component/${tagName}`,
                     }, null, 2),
                 },

package/dist/tools/guide-tools.js

@@ -56,7 +56,7 @@ export function registerGuideTools(server) {
         ])
             .describe("The guide topic to retrieve"),
         framework: z
-            .enum(["angular", "react", "dotnet", "drupal", "vanilla"])
+            .enum(["angular", "react", "vue", "dotnet", "drupal", "vanilla"])
             .optional()
             .describe("When provided, returns framework-specific setup guide instead of the topic guide. Use with topic 'installation' to get framework install instructions."),
     }, async ({ topic, framework }) => {

package/dist/tools/utility-tools.d.ts

@@ -2,7 +2,55 @@
  * Utility Tools
  *
  * MCP tools for COBWDS utility classes.
+ *
+ * The class lists this tool returns are RENDERED from the scale constants
+ * below. Those constants mirror the Sass sources that actually generate the
+ * stylesheet:
+ *
+ *   - packages/styles/src/utilities/_config.scss     ($spacing, $opacity-values,
+ *                                                     $zindex-values, $display-values,
+ *                                                     $breakpoints, $flex-columns)
+ *   - packages/styles/src/utilities/_layout-grid.scss ($responsive-gap-suffixes)
+ *   - packages/styles/src/core/typography.scss        ($body-sizes, $ui-sizes,
+ *                                                     $ui-underline-styles, $display-sizes)
+ *
+ * Do not hand-write a class name into the markdown. Add it to a scale and let
+ * the renderer emit it, so a name can never appear here without a scale entry
+ * behind it.
+ *
+ * `npm run verify:utility-docs` compiles the stylesheet and asserts that every
+ * class this tool names exists in it. Run it after touching any scale.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const UTILITY_DOCS: {
+    grid: string;
+    flex: string;
+    spacing: string;
+    display: string;
+    opacity: string;
+    zindex: string;
+    typography: string;
+    responsive: string;
+    componentSpacing: string;
+};
+/**
+ * Classes the reference deliberately names in order to say they do NOT exist.
+ *
+ * These are the names people reach for out of habit from other frameworks.
+ * Saying so explicitly is more useful than silence, but it means the docs
+ * mention class names the stylesheet does not define, which would otherwise
+ * trip the verifier.
+ *
+ * `verify-utility-docs.mjs` asserts each of these is genuinely absent, so if
+ * COBWDS ever adds one, the stale warning fails the check instead of quietly
+ * misinforming people.
+ */
+declare const KNOWN_ABSENT: readonly string[];
+/**
+ * Exported so `src/scripts/verify-utility-docs.mjs` can assert that every class
+ * named in this reference exists in the compiled stylesheet — and that every
+ * class named in KNOWN_ABSENT still does not.
+ */
+export { UTILITY_DOCS, KNOWN_ABSENT };
 export declare function registerUtilityTools(server: McpServer): void;
 //# sourceMappingURL=utility-tools.d.ts.map

package/dist/tools/utility-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utility-tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmPzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}
+{"version":3,"file":"utility-tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiLzE,QAAA,MAAM,YAAY;;;;;;;;;;CAyOjB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,YAAY,EAAE,SAAS,MAAM,EAUlC,CAAC;AAEF;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAEtC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}

package/dist/tools/utility-tools.js

@@ -2,8 +2,150 @@
  * Utility Tools
  *
  * MCP tools for COBWDS utility classes.
+ *
+ * The class lists this tool returns are RENDERED from the scale constants
+ * below. Those constants mirror the Sass sources that actually generate the
+ * stylesheet:
+ *
+ *   - packages/styles/src/utilities/_config.scss     ($spacing, $opacity-values,
+ *                                                     $zindex-values, $display-values,
+ *                                                     $breakpoints, $flex-columns)
+ *   - packages/styles/src/utilities/_layout-grid.scss ($responsive-gap-suffixes)
+ *   - packages/styles/src/core/typography.scss        ($body-sizes, $ui-sizes,
+ *                                                     $ui-underline-styles, $display-sizes)
+ *
+ * Do not hand-write a class name into the markdown. Add it to a scale and let
+ * the renderer emit it, so a name can never appear here without a scale entry
+ * behind it.
+ *
+ * `npm run verify:utility-docs` compiles the stylesheet and asserts that every
+ * class this tool names exists in it. Run it after touching any scale.
  */
 import { z } from "zod";
+/**
+ * `$spacing` in _config.scss. The utilities emit literal pixel values, not
+ * `var(--cob-space-*)` references, so the rendered docs quote pixels.
+ *
+ * There is deliberately no `0` key: `cob-margin-0` and `cob-padding-0` are
+ * not generated.
+ */
+const SPACING = [
+    ["1px", "1px"],
+    ["2px", "2px"],
+    ["50", "4px", "0.25rem"],
+    ["100", "8px", "0.5rem"],
+    ["150", "12px", "0.75rem"],
+    ["200", "16px", "1rem"],
+    ["250", "20px", "1.25rem"],
+    ["300", "24px", "1.5rem"],
+    ["400", "32px", "2rem"],
+    ["500", "40px", "2.5rem"],
+    ["600", "48px", "3rem"],
+    ["700", "56px", "3.5rem"],
+    ["800", "64px", "4rem"],
+    ["1200", "96px", "6rem"],
+];
+/** `$responsive-gap-suffixes` in _layout-grid.scss. */
+const RESPONSIVE_GAP_KEYS = [
+    "400",
+    "500",
+    "600",
+    "700",
+    "800",
+    "1200",
+];
+/** `$opacity-values` in _config.scss. */
+const OPACITY = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+/** `$zindex-values` in _config.scss. */
+const ZINDEX = [
+    ["0", "0"],
+    ["100", "100"],
+    ["200", "200"],
+    ["300", "300"],
+    ["400", "400"],
+    ["500", "500"],
+    ["auto", "auto"],
+    ["bottom", "-100"],
+    ["top", "99999"],
+];
+/** `$display-values` in _config.scss. */
+const DISPLAY = [
+    "none",
+    "block",
+    "inline",
+    "inline-block",
+    "flex",
+    "inline-flex",
+    "table",
+    "table-cell",
+    "table-row",
+];
+/** `$breakpoints` in _config.scss. */
+const BREAKPOINTS = [
+    ["mobile-lg", "30em", "480px"],
+    ["tablet", "40em", "640px"],
+    ["desktop", "64em", "1024px"],
+    ["widescreen", "87.5em", "1400px"],
+];
+/** Typography scales in core/typography.scss. */
+const HEADING_LEVELS = [1, 2, 3, 4, 5, 6];
+const BODY_SIZES = ["xs", "sm", "md"];
+const UI_SIZES = ["xs", "sm", "md", "lg", "xl"];
+const DISPLAY_SIZES = ["sm", "md", "lg", "xl"];
+/** `$ui-underline-styles` — only these size/weight pairs are generated. */
+const UI_UNDERLINE = [
+    ["sm", "semibold"],
+    ["md", "semibold"],
+    ["md", "regular"],
+    ["lg", "semibold"],
+];
+const FLEX_ALIGN = [
+    "start",
+    "center",
+    "end",
+    "baseline",
+    "stretch",
+];
+const FLEX_JUSTIFY = [
+    "start",
+    "center",
+    "end",
+    "space-between",
+    "space-around",
+    "space-evenly",
+];
+/* ------------------------------------------------------------------ *
+ * Renderers
+ * ------------------------------------------------------------------ */
+const spacingKeys = SPACING.map(([key]) => key);
+const bullets = (lines) => lines.join("\n");
+const inlineList = (items) => items.map((i) => `\`${i}\``).join(", ");
+const spacingValueRows = bullets(SPACING.map(([key, px, rem]) => `- \`${key}\` - ${px}${rem ? ` (${rem})` : ""}`));
+const gapValueRows = bullets(SPACING.map(([key, px, rem]) => {
+    const size = `${px}${rem ? ` (${rem})` : ""}`;
+    // Gaps in the responsive set are capped at 2rem below 64em. For 400 the
+    // cap equals the full value, so only note it where it actually differs.
+    const capped = RESPONSIVE_GAP_KEYS.includes(key) && Number.parseInt(px, 10) > 32;
+    return capped
+        ? `- \`cob-grid-gap-${key}\` - ${size} at 64em and up, capped at 32px (2rem) below that`
+        : `- \`cob-grid-gap-${key}\` - ${size}`;
+}));
+const opacityRows = bullets(OPACITY.map((v) => {
+    const label = v === 0
+        ? "Fully transparent"
+        : v === 100
+            ? "Fully opaque"
+            : `${v}% opaque`;
+    return `- \`cob-opacity-${v}\` - opacity: ${v / 100} (${label})`;
+}));
+const zindexRows = bullets(ZINDEX.map(([name, value]) => `- \`cob-z-${name}\` - z-index: ${value}`));
+const displayRows = bullets(DISPLAY.map((v) => `- \`cob-display-${v}\` - display: ${v}`));
+const breakpointRows = bullets(BREAKPOINTS.map(([name, em, px]) => `- \`cob-${name}:\` - ${em} (${px}) and up`));
+const headingRows = bullets(HEADING_LEVELS.map((n) => `- \`cob-font-h${n}\` - Heading level ${n} type style`));
+const underlineRows = bullets(UI_UNDERLINE.flatMap(([size, weight]) => [
+    `- \`cob-font-ui-${size}-${weight}-underline\` - UI ${size} ${weight}, 7% underline`,
+    `- \`cob-font-ui-${size}-${weight}-underline-strong\` - UI ${size} ${weight}, 14% underline`,
+]));
 const UTILITY_DOCS = {
     grid: `## Grid System
 
@@ -26,20 +168,11 @@ COBWDS provides a 12-column responsive grid system.
 - \`cob-grid-col-fill\` - Column fills remaining space
 
 ### Gap Classes
-- \`cob-grid-gap-0\` - No gap
-- \`cob-grid-gap-2px\` - 2px gap
-- \`cob-grid-gap-50\` - 4px gap (0.25rem)
-- \`cob-grid-gap-100\` - 8px gap (0.5rem)
-- \`cob-grid-gap-150\` - 12px gap (0.75rem)
-- \`cob-grid-gap-200\` - 16px gap (1rem)
-- \`cob-grid-gap-250\` - 20px gap (1.25rem)
-- \`cob-grid-gap-300\` - 24px gap (1.5rem)
-- \`cob-grid-gap-400\` - 32px gap (2rem)
-- \`cob-grid-gap-500\` - 40px gap (2.5rem)
-- \`cob-grid-gap-600\` - 48px gap (3rem)
-- \`cob-grid-gap-700\` - 56px gap (3.5rem)
-- \`cob-grid-gap-800\` - 64px gap (4rem)
-- \`cob-grid-gap-1200\` - 96px gap (6rem)
+Gap classes apply to \`cob-grid-row\`. Use \`cob-grid-gap-x-*\` or
+\`cob-grid-gap-y-*\` for a single axis. There is no \`cob-grid-gap-0\`; omit
+the gap class instead.
+
+${gapValueRows}
 
 ### Offset Classes
 - \`cob-grid-offset-[1-12]\` - Offset column by 1-12 columns
@@ -61,6 +194,7 @@ COBWDS provides a 12-column responsive grid system.
 
 ### Display
 - \`cob-display-flex\` - Sets display: flex
+- \`cob-display-inline-flex\` - Sets display: inline-flex
 
 ### Direction
 - \`cob-flex-row\` - Row direction (default)
@@ -71,21 +205,26 @@ COBWDS provides a 12-column responsive grid system.
 - \`cob-flex-no-wrap\` - Prevent wrapping
 
 ### Alignment (Cross Axis)
-- \`cob-flex-align-start\` - Align items to start
-- \`cob-flex-align-center\` - Align items to center
-- \`cob-flex-align-end\` - Align items to end
-- \`cob-flex-align-stretch\` - Stretch items to fill
+${bullets(FLEX_ALIGN.map((v) => `- \`cob-flex-align-${v}\` - align-items: ${v}`))}
+
+### Self Alignment
+${bullets(FLEX_ALIGN.map((v) => `- \`cob-flex-align-self-${v}\` - align-self: ${v}`))}
 
 ### Justification (Main Axis)
-- \`cob-flex-justify-start\` - Justify to start
-- \`cob-flex-justify-center\` - Justify to center
-- \`cob-flex-justify-end\` - Justify to end
+${bullets(FLEX_JUSTIFY.map((v) => `- \`cob-flex-justify-${v}\` - justify-content: ${v}`))}
 
 ### Flex Sizing
 - \`cob-flex-[1-12]\` - Flex grow/shrink values
 - \`cob-flex-auto\` - flex: auto (grow and shrink)
 - \`cob-flex-fill\` - Fill available space
 
+### Gaps
+Available on the spacing scale: ${inlineList(spacingKeys)}
+
+- \`cob-flex-gap-{value}\` - gap on both axes
+- \`cob-flex-row-gap-{value}\` - row-gap only
+- \`cob-flex-column-gap-{value}\` - column-gap only
+
 ### Example: Button Group
 \`\`\`html
 <div class="cob-display-flex cob-flex-justify-end cob-flex-gap-200">
@@ -111,21 +250,11 @@ Pattern: \`cob-{property}-{direction}-{value}\`
 - (none) - All sides
 
 ### Values
-- \`0\` - 0
-- \`1px\` - 1px
-- \`2px\` - 2px
-- \`50\` - var(--cob-space-50) = 0.125rem (2px)
-- \`100\` - var(--cob-space-100) = 0.25rem (4px)
-- \`150\` - var(--cob-space-150) = 0.375rem (6px)
-- \`200\` - var(--cob-space-200) = 0.5rem (8px)
-- \`250\` - var(--cob-space-250) = 0.625rem (10px)
-- \`300\` - var(--cob-space-300) = 0.75rem (12px)
-- \`400\` - var(--cob-space-400) = 1rem (16px)
-- \`500\` - var(--cob-space-500) = 1.25rem (20px)
-- \`600\` - var(--cob-space-600) = 1.5rem (24px)
-- \`700\` - var(--cob-space-700) = 2rem (32px)
-- \`800\` - var(--cob-space-800) = 2.5rem (40px)
-- \`1200\` - var(--cob-space-1200) = 4rem (64px)
+The utilities emit literal pixel values. There is no zero and no \`auto\`
+value — \`cob-margin-0\` and \`cob-padding-0\` are not generated. Omit the
+class instead.
+
+${spacingValueRows}
 
 ### Examples
 \`\`\`html
@@ -140,11 +269,7 @@ Pattern: \`cob-{property}-{direction}-{value}\`
 \`\`\``,
     display: `## Display Utilities
 
-- \`cob-display-none\` - Hide element
-- \`cob-display-block\` - Block display
-- \`cob-display-inline\` - Inline display
-- \`cob-display-inline-block\` - Inline-block display
-- \`cob-display-flex\` - Flex display
+${displayRows}
 
 ### Example: Hide on Mobile
 \`\`\`html
@@ -154,46 +279,57 @@ Pattern: \`cob-{property}-{direction}-{value}\`
 \`\`\``,
     opacity: `## Opacity Utilities
 
-- \`cob-opacity-0\` - Fully transparent
-- \`cob-opacity-25\` - 25% opacity
-- \`cob-opacity-50\` - 50% opacity
-- \`cob-opacity-75\` - 75% opacity
-- \`cob-opacity-100\` - Fully opaque`,
+The scale steps by 10 — there is no \`cob-opacity-25\` or \`cob-opacity-75\`.
+
+${opacityRows}`,
     zindex: `## Z-Index Utilities
 
-- \`cob-z-0\` - z-index: 0
-- \`cob-z-10\` - z-index: 10
-- \`cob-z-20\` - z-index: 20
-- \`cob-z-30\` - z-index: 30
-- \`cob-z-40\` - z-index: 40
-- \`cob-z-50\` - z-index: 50
-- \`cob-z-auto\` - z-index: auto`,
+The scale steps by 100, not by 10. \`cob-z-10\` through \`cob-z-50\` do not
+exist — the comparable values are \`cob-z-100\` through \`cob-z-500\`.
+
+${zindexRows}`,
     typography: `## Typography Utilities
 
-### Text Alignment
-- \`cob-text-left\` - Left align text
-- \`cob-text-center\` - Center align text
-- \`cob-text-right\` - Right align text
-
-### Font Weight
-- \`cob-font-normal\` - Normal weight
-- \`cob-font-medium\` - Medium weight
-- \`cob-font-semibold\` - Semibold weight
-- \`cob-font-bold\` - Bold weight
-
-### Text Transform
-- \`cob-text-uppercase\` - Uppercase text
-- \`cob-text-lowercase\` - Lowercase text
-- \`cob-text-capitalize\` - Capitalize text`,
+COBWDS ships a role-based type scale, not atomic text modifiers. Each class
+sets font-family, size, and line-height together, matching the text styles in
+the COBWDS Foundations Figma file.
+
+There are NO text-alignment, text-transform, or font-weight utilities
+(no \`cob-text-center\`, no \`cob-font-bold\`). Use CSS for those.
+
+### Headings
+${headingRows}
+
+### Body
+${bullets(BODY_SIZES.map((s) => `- \`cob-font-body-${s}\` - Body text, ${s}`))}
+
+### UI
+${bullets(UI_SIZES.map((s) => `- \`cob-font-ui-${s}\` - UI text, ${s}`))}
+
+### UI Underline
+${underlineRows}
+
+### Display
+${bullets(DISPLAY_SIZES.map((s) => `- \`cob-font-display-${s}\` - Display text, ${s}`))}
+
+### Agency
+- \`cob-font-agency\` - Agency / application title
+
+### Font family hooks
+These are attribute selectors, not standalone classes. They set only
+font-family on any element whose class list contains the substring, so pair
+them with a size class:
+
+- \`[class*="cob-font-mono-"]\` - monospace family
+- \`[class*="cob-font-sans-"]\` - sans-serif family
+- \`[class*="cob-font-serif-"]\` - serif family`,
     responsive: `## Responsive Breakpoints
 
 COBWDS utility classes support responsive prefixes.
 
 ### Breakpoints
 - (no prefix) - All screen sizes (mobile-first)
-- \`cob-mobile-lg:\` - 30em (480px) and up
-- \`cob-tablet:\` - 40em (640px) and up
-- \`cob-desktop:\` - 64em (1024px) and up
+${breakpointRows}
 
 ### Pattern
 \`cob-{breakpoint}:cob-{class}\`
@@ -236,6 +372,35 @@ When adding spacing around COBWDS components, use utility classes rather than wr
 <cob-button label="Submit"></cob-button>
 \`\`\``,
 };
+/**
+ * Classes the reference deliberately names in order to say they do NOT exist.
+ *
+ * These are the names people reach for out of habit from other frameworks.
+ * Saying so explicitly is more useful than silence, but it means the docs
+ * mention class names the stylesheet does not define, which would otherwise
+ * trip the verifier.
+ *
+ * `verify-utility-docs.mjs` asserts each of these is genuinely absent, so if
+ * COBWDS ever adds one, the stale warning fails the check instead of quietly
+ * misinforming people.
+ */
+const KNOWN_ABSENT = [
+    "cob-text-center",
+    "cob-font-bold",
+    "cob-z-10",
+    "cob-z-50",
+    "cob-opacity-25",
+    "cob-opacity-75",
+    "cob-margin-0",
+    "cob-padding-0",
+    "cob-grid-gap-0",
+];
+/**
+ * Exported so `src/scripts/verify-utility-docs.mjs` can assert that every class
+ * named in this reference exists in the compiled stylesheet — and that every
+ * class named in KNOWN_ABSENT still does not.
+ */
+export { UTILITY_DOCS, KNOWN_ABSENT };
 export function registerUtilityTools(server) {
     // get_utility_classes - Comprehensive utility class reference
     server.tool("get_utility_classes", "Get COBWDS utility class reference for layout, spacing, and styling", {