@hirobius/design-system 0.20.0 → 0.21.0

package/mcp/guide.mjs

@@ -0,0 +1,315 @@
+/**
+ * The consumer guide: which HDS component answers which screen need.
+ *
+ * One source for both agent surfaces: the `hds` MCP server (mcp/catalog.mjs)
+ * serves it, and scripts/generate-agents-md.mjs projects it into the packaged
+ * AGENTS.md. Component facts (props, descriptions, import paths) are NOT here;
+ * they come from the shipped manifest and component-api.json. This file holds
+ * only the choices the data leaves open, each one a place where agents built
+ * the same screen differently in the 2026-10-05 consistency baseline
+ * (eval/consistency/DIAGNOSIS-2026-10-05.md).
+ *
+ * Every name in `use` must exist in component-api.json or be a listed hook;
+ * scripts/__tests__/generate-agents-md.test.mjs enforces it.
+ */
+
+/** Hooks are not components, so component-api.json has no entry for them. */
+export const HOOKS = {
+  useToast: {
+    import: '@hirobius/design-system',
+    note: 'Inside a ToastProvider: `const { toast } = useToast(); toast({ title, description?, tone? })`.',
+  },
+};
+
+/**
+ * One row per screen need. `use` is the answer (in order of composition),
+ * `avoid` the alternatives agents reached for instead, `how` one line of usage.
+ * `keywords` feed search_components ranking. A component named in `avoid` is
+ * not wrong in general; it is the wrong answer for that one need, and the
+ * server tells an agent so (`insteadFor`). Every need has one answer: the four
+ * number components are the case that split the baseline, so a row of numbers
+ * is always MetricTiles.
+ */
+export const INTENTS = [
+  {
+    id: 'page-shell',
+    need: 'Outermost wrapper of a screen',
+    keywords: ['page', 'screen', 'shell', 'layout', 'wrapper', 'root'],
+    use: ['Page', 'Stack'],
+    avoid: ['Container', 'Box', 'a bare Stack as the root'],
+    how: '`<Page><Stack gap="spacious">…one child per section…</Stack></Page>`. `Container` is for a full-bleed surface that is not a page.',
+  },
+  {
+    id: 'page-header',
+    need: 'Screen title with breadcrumb, status and actions',
+    keywords: ['title', 'header', 'heading', 'breadcrumb', 'status', 'name'],
+    use: ['PageHeader', 'Breadcrumb', 'Badge'],
+    avoid: ['Text as the page title', 'a Stack row of Text and Badge'],
+    how: 'Exactly one per screen: `<PageHeader breadcrumb={<Breadcrumb items={[{ label, href }, { label }]} />} title="…" status={<Badge tone="success">Active</Badge>} />`.',
+  },
+  {
+    id: 'metrics',
+    need: 'Row of headline numbers (stats, KPIs, counts, totals)',
+    keywords: [
+      'metric',
+      'metrics',
+      'stat',
+      'stats',
+      'kpi',
+      'number',
+      'numbers',
+      'tile',
+      'tiles',
+      'headline',
+      'count',
+      'total',
+    ],
+    use: ['MetricTiles', 'MetricTile'],
+    avoid: ['Stat', 'StatusTile', 'CardMetric', 'Card with Text'],
+    how: '`<MetricTiles><MetricTile label="Open projects" value="5" />…</MetricTiles>`; one MetricTile per number. `Stat` is for a number inside prose or a dense list, `Card.Metric` for one inside an existing `Card`, `StatusTile` for a state with notes (never a number).',
+  },
+  {
+    id: 'table',
+    need: 'Table of records with row actions',
+    keywords: ['table', 'rows', 'records', 'list', 'data', 'grid', 'columns'],
+    use: ['DataTableSection', 'Badge', 'Button'],
+    avoid: ['Table on its own', 'Card around a Table'],
+    how: '`<DataTableSection title="Projects" columns={[{ key, label }]} rows={[{ key, cells: [...], actions: <Stack direction="row" gap="tight">…</Stack> }]} />`; leave the actions column out of `columns`.',
+  },
+  {
+    id: 'tabs',
+    need: 'Switch between panels of related content',
+    keywords: ['tabs', 'tab', 'panel', 'panels', 'sections', 'switch'],
+    use: ['Tabs', 'TabsList', 'TabsTrigger', 'TabsContent'],
+    avoid: ['SegmentedControl', 'Button rows'],
+    how: '`<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>`.',
+  },
+  {
+    id: 'status',
+    need: 'Status label in a header or table cell',
+    keywords: ['status', 'state', 'label', 'chip', 'pill', 'badge'],
+    use: ['Badge'],
+    avoid: ['Tag', 'Text'],
+    how: '`<Badge tone="success|info|warning|danger|neutral|inProgress">…</Badge>`; tone is the only styling input.',
+  },
+  {
+    id: 'form',
+    need: 'Form with fields and a submit button',
+    keywords: ['form', 'field', 'fields', 'input', 'textarea', 'notes', 'submit', 'save'],
+    use: ['Form', 'Textarea', 'Input', 'FormActions', 'Button'],
+    avoid: ['a raw `<form>`', 'a Stack of Buttons as the footer'],
+    how: '`<Form onSubmit={…}><Textarea label="Notes" … /><FormActions primary={<Button type="submit">Save note</Button>} /></Form>`; every field takes its own `label`.',
+  },
+  {
+    id: 'confirm',
+    need: 'Confirm a destructive or irreversible action (delete, archive, remove)',
+    keywords: [
+      'confirm',
+      'confirmation',
+      'destructive',
+      'delete',
+      'archive',
+      'remove',
+      'modal',
+      'dialog',
+    ],
+    use: ['AlertDialog', 'Button'],
+    avoid: ['Dialog', '`window.confirm`'],
+    how: 'Trigger, title, description, Cancel and Action parts: `<AlertDialog><AlertDialog.Trigger asChild><Button …>Archive</Button></AlertDialog.Trigger><AlertDialog.Content><AlertDialog.Header><AlertDialog.Title>…</AlertDialog.Title><AlertDialog.Description>…</AlertDialog.Description></AlertDialog.Header><AlertDialog.Footer><AlertDialog.Cancel asChild><Button variant="secondary">Cancel</Button></AlertDialog.Cancel><AlertDialog.Action asChild><Button tone="danger" onClick={…}>Archive</Button></AlertDialog.Action></AlertDialog.Footer></AlertDialog.Content></AlertDialog>`. Focus moves in and returns to the trigger for you.',
+  },
+  {
+    id: 'feedback',
+    need: 'Brief confirmation after an action (saved, archived, sent)',
+    keywords: [
+      'toast',
+      'confirmation',
+      'saved',
+      'success',
+      'notify',
+      'notification',
+      'feedback',
+      'message',
+    ],
+    use: ['ToastProvider', 'useToast'],
+    avoid: ['Badge', 'Alert', 'Text'],
+    how: 'Wrap the app root once in `<ToastProvider>`, then `toast({ title: "Note saved", tone: "success" })` from `useToast()`.',
+  },
+  {
+    id: 'message',
+    need: 'Message that stays next to its content (error, warning, info)',
+    keywords: ['alert', 'error', 'warning', 'info', 'banner', 'callout'],
+    use: ['Alert'],
+    avoid: ['Text in a coloured Surface'],
+    how: '`<Alert tone="warning">…</Alert>`.',
+  },
+  {
+    id: 'action',
+    need: 'Button or row action',
+    keywords: ['button', 'action', 'click', 'view', 'edit', 'cta'],
+    use: ['Button'],
+    avoid: ['a raw `<button>`', 'InlineLink for an action'],
+    how: 'Row actions: `<Button variant="tertiary" size="sm" aria-label="View Brand refresh">View</Button>`; the destructive one adds `tone="danger"`.',
+  },
+  {
+    id: 'spacing',
+    need: 'Space between sections or items',
+    keywords: ['spacing', 'gap', 'stack', 'row', 'column', 'layout', 'columns'],
+    use: ['Stack', 'Grid'],
+    avoid: ['margins on children', 'raw px gaps such as px8'],
+    how: 'Stack `gap`: `spacious` between page sections, `normal` inside a section, `tight` between buttons. `Grid` for two-dimensional layout.',
+  },
+  {
+    id: 'surface',
+    need: 'Padded background or a titled content object',
+    keywords: ['card', 'surface', 'panel', 'box', 'background', 'container'],
+    use: ['Surface', 'Card'],
+    avoid: ['a Box with background and padding'],
+    how: '`Surface` for a plain padded background; `Card` only when the content has a title or can be pressed.',
+  },
+  {
+    id: 'progress',
+    need: 'Progress bar or ring',
+    keywords: ['progress', 'bar', 'percent', 'loading', 'completion'],
+    use: ['Progress'],
+    avoid: ['a hand-built bar'],
+    how: '`<Progress value={60} label="Upload" />`; inside an existing `Card`, `CardProgress`.',
+  },
+  {
+    id: 'text',
+    need: 'Body copy',
+    keywords: ['text', 'copy', 'paragraph', 'body', 'typography'],
+    use: ['Text'],
+    avoid: ['Text as a section heading'],
+    how: 'Section headings come from the pattern that owns the section (`PageHeader` `title`, `DataTableSection` `title`), not from extra Text.',
+  },
+  {
+    id: 'empty',
+    need: 'Empty state for a list or section',
+    keywords: ['empty', 'none', 'nothing', 'placeholder', 'zero'],
+    use: ['EmptyState'],
+    avoid: ['Text saying "No items"'],
+    how: '`DataTableSection` shows its own through `emptyTitle`; use `EmptyState` elsewhere.',
+  },
+  {
+    id: 'danger-zone',
+    need: 'The one irreversible action of a screen (delete the client, close the account)',
+    keywords: ['danger', 'irreversible', 'delete', 'account', 'zone', 'destructive'],
+    use: ['DestructiveSection'],
+    avoid: ['a danger Button that acts without a confirm'],
+    how: 'Last on the screen: `<DestructiveSection title="Delete client" description="…" actionLabel="Delete" onConfirm={…} />`; it opens its own AlertDialog. A per-row destructive action uses AlertDialog directly.',
+  },
+  {
+    id: 'metadata',
+    need: 'Read-only details as label and value pairs',
+    keywords: ['metadata', 'details', 'properties', 'key', 'value', 'pairs', 'record'],
+    use: ['MetadataList', 'Field'],
+    avoid: ['a Table with two columns', 'Text pairs in a Stack'],
+    how: '`<MetadataList items={[{ term: "Owner", description: "Ada" }]} />` for a set; `Field` for one pair.',
+  },
+  {
+    id: 'people',
+    need: 'A person, or a group of people',
+    keywords: ['avatar', 'avatars', 'person', 'people', 'user', 'users', 'team', 'members'],
+    use: ['Avatar', 'AvatarGroup'],
+    avoid: ['an image in a rounded Box'],
+    how: '`<Avatar src alt initials />`; several in a row: `<AvatarGroup max={3}>…Avatars…</AvatarGroup>`.',
+  },
+  {
+    id: 'date',
+    need: 'A date or time',
+    keywords: ['date', 'time', 'timestamp', 'when', 'ago', 'due'],
+    use: ['Timestamp'],
+    avoid: ['a formatted string in Text'],
+    how: '`<Timestamp date="2026-10-14" />` renders a `<time dateTime>`; a date in a table cell may stay plain text.',
+  },
+  {
+    id: 'shortcut',
+    need: 'A keyboard key or shortcut hint',
+    keywords: ['keyboard', 'shortcut', 'key', 'kbd', 'hotkey'],
+    use: ['Kbd'],
+    avoid: ['InlineCode', 'Text in a Box'],
+    how: '`<Kbd>⌘K</Kbd>`.',
+  },
+  {
+    id: 'quote',
+    need: 'A quotation with attribution',
+    keywords: ['quote', 'quotation', 'testimonial', 'blockquote', 'citation'],
+    use: ['Blockquote'],
+    avoid: ['Callout for a quote', 'italic Text'],
+    how: '`<Blockquote attribution="Ada Lovelace">…</Blockquote>`.',
+  },
+  {
+    id: 'rail',
+    need: 'A fixed-width side rail beside fluid content, or a row that stacks when narrow',
+    keywords: ['sidebar', 'rail', 'aside', 'responsive', 'switcher', 'stack', 'narrow', 'columns'],
+    use: ['Sidebar', 'Switcher'],
+    avoid: ['a Grid with media queries'],
+    how: '`Sidebar` (`side`, `sideWidth`) for rail + content; `Switcher` (`threshold`) for a row that flips to a column. Neither needs a media query.',
+  },
+  {
+    id: 'sticky',
+    need: 'Keep an element stuck while its region scrolls',
+    keywords: ['sticky', 'pin', 'fixed', 'scroll'],
+    use: ['Pin'],
+    avoid: ['position: sticky in style'],
+    how: '`<Pin top="…">…</Pin>` inside the scrolling region.',
+  },
+];
+
+/**
+ * The ratified core set (scripts/lib/core-components.mjs, hds#254). Copied, not
+ * imported, because scripts/ does not ship; scripts/__tests__/generate-agents-md.test.mjs
+ * pins the two together.
+ */
+export const RATIFIED_CORE = [
+  'Alert',
+  'Avatar',
+  'Badge',
+  'Box',
+  'Breadcrumb',
+  'Button',
+  'Card',
+  'Checkbox',
+  'Combobox',
+  'Container',
+  'Dialog',
+  'Disclosure',
+  'Divider',
+  'EmptyState',
+  'Field',
+  'Grid',
+  'HdsRouterProvider',
+  'HdsThemeProvider',
+  'Icon',
+  'InlineLink',
+  'Input',
+  'Kbd',
+  'Menu',
+  'Pagination',
+  'Popover',
+  'Progress',
+  'Radio',
+  'SegmentedControl',
+  'Select',
+  'Skeleton',
+  'Slider',
+  'Spinner',
+  'Stack',
+  'Surface',
+  'Table',
+  'Tabs',
+  'Tag',
+  'Text',
+  'Textarea',
+  'ToastProvider',
+  'Toggle',
+  'Tooltip',
+  'VisuallyHidden',
+];
+
+/** The core set agents should prefer: the ratified core plus every `use` above, hooks excluded. */
+export function coreComponents() {
+  const names = new Set(RATIFIED_CORE);
+  for (const intent of INTENTS) for (const name of intent.use) if (!HOOKS[name]) names.add(name);
+  return [...names].sort();
+}

package/mcp/hds-mcp.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * hds-mcp — the `hds` MCP server over stdio, shipped in @hirobius/design-system.
+ *
+ * Run from an app that has the package installed:  npx hds-mcp
+ * Without an install:  npx -y -p @hirobius/design-system hds-mcp
+ *
+ * Reads the data the package already ships (public/hds-manifest.json,
+ * src/app/data/component-api.json) from its own install directory; it never
+ * touches the network or the caller's files. Messages are newline-delimited
+ * JSON-RPC 2.0 (the MCP stdio transport); logs go to stderr only.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { loadCatalog } from './catalog.mjs';
+import { createServer } from './server.mjs';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { version } = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+
+let catalog;
+try {
+  catalog = loadCatalog(PKG_ROOT);
+} catch (err) {
+  console.error(
+    `hds-mcp: could not read the design-system data under ${PKG_ROOT} (${err.message}).\n` +
+      '  Reinstall @hirobius/design-system; in the hds repo run `node scripts/generate-component-api.mjs` first.',
+  );
+  process.exit(1);
+}
+
+const handle = createServer({ version, instructions: catalog.instructions, tools: catalog.tools });
+
+const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);
+
+createInterface({ input: process.stdin }).on('line', (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  const response = handle(message);
+  if (response) send(response);
+});

package/mcp/server.mjs

@@ -0,0 +1,94 @@
+/**
+ * The `hds` MCP server's protocol layer: JSON-RPC 2.0 messages in, responses out.
+ *
+ * Interface: `createServer({ version, instructions, tools })` returns
+ * `handle(message)`, which takes one parsed JSON value and returns the response
+ * object, or `null` for a notification. It never throws: a message that is not a
+ * request object gets -32600, and anything unexpected inside gets -32603, so one
+ * bad line cannot stop the process. Transport (stdio framing) lives in hds-mcp.mjs, the
+ * tool behaviour in catalog.mjs; this module only speaks MCP.
+ *
+ * No dependency on @modelcontextprotocol/sdk: the server needs four methods
+ * (initialize, ping, tools/list, tools/call), and a zero-dependency module keeps
+ * the published package's install graph unchanged.
+ */
+
+export const SERVER_NAME = 'hds';
+
+/** Protocol versions this server can speak; it echoes the client's when it is one of these. */
+const SUPPORTED_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+
+/**
+ * @param {{ version: string, instructions: string, tools: { name: string, description: string, inputSchema: object, run: (args: object) => unknown }[] }} options
+ */
+export function createServer({ version, instructions, tools }) {
+  const byName = new Map(tools.map((t) => [t.name, t]));
+
+  function dispatch(message) {
+    // MCP has no batches (removed in 2025-06-18), so an array is invalid like any non-object.
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      return rpcError(null, -32600, 'Invalid Request: expected one JSON-RPC request object');
+    }
+    const hasId = Object.prototype.hasOwnProperty.call(message, 'id');
+    const id = hasId ? message.id : null;
+    if (typeof message.method !== 'string') {
+      return hasId ? rpcError(id, -32600, 'Invalid Request: method must be a string') : null;
+    }
+    // A message without an `id` member is a notification; `id: null` is still a request.
+    if (!hasId) return null;
+    const { method } = message;
+    const params = message.params && typeof message.params === 'object' ? message.params : {};
+
+    switch (method) {
+      case 'initialize': {
+        const asked = params.protocolVersion;
+        return rpcResult(id, {
+          protocolVersion: SUPPORTED_VERSIONS.includes(asked) ? asked : SUPPORTED_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: SERVER_NAME, version },
+          instructions,
+        });
+      }
+      case 'ping':
+        return rpcResult(id, {});
+      case 'tools/list':
+        return rpcResult(id, {
+          tools: tools.map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+          })),
+        });
+      case 'tools/call': {
+        const tool = typeof params.name === 'string' ? byName.get(params.name) : undefined;
+        if (!tool) return rpcError(id, -32602, `Unknown tool: ${params.name}`);
+        try {
+          const args =
+            params.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+          const data = tool.run(args);
+          return rpcResult(id, { content: [{ type: 'text', text: JSON.stringify(data) }] });
+        } catch (err) {
+          // A tool-level failure is a result with isError, so the agent can read and recover.
+          return rpcResult(id, {
+            content: [{ type: 'text', text: JSON.stringify({ error: String(err.message) }) }],
+            isError: true,
+          });
+        }
+      }
+      default:
+        return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  return function handle(message) {
+    try {
+      return dispatch(message);
+    } catch (err) {
+      const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+      return rpcError(id ?? null, -32603, `Internal error: ${err?.message ?? err}`);
+    }
+  };
+}

package/package.json

@@ -20,7 +20,7 @@
   "author": "Adrian Milsap",
   "license": "SEE LICENSE IN NOTICE.md",
   "private": false,
-  "version": "0.20.0",
+  "version": "0.21.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
@@ -39,6 +39,7 @@
     },
     "./tokens.css": "./dist/tokens.css",
     "./styles.css": "./dist/styles.css",
+    "./fonts.css": "./dist/fonts.css",
     "./variables.css": "./dist/variables.css",
     "./static.css": "./dist/static.css",
     "./tokens": {
@@ -91,6 +92,10 @@
       "import": "./dist/icons.js",
       "default": "./dist/icons.js"
     },
+    "./eslint-plugin": {
+      "types": "./scripts/eslint-plugin-hds/index.d.mts",
+      "default": "./scripts/eslint-plugin-hds/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -113,7 +118,13 @@
     "codemods/unrewritable.mjs",
     "codemods/jsx-fold.mjs",
     "codemods/not-found-pattern.mjs",
-    "codemods/tile-grid.mjs"
+    "codemods/tile-grid.mjs",
+    "AGENTS.md",
+    "mcp/",
+    "scripts/eslint-plugin-hds/index.mjs",
+    "scripts/eslint-plugin-hds/index.d.mts",
+    "scripts/eslint-plugin-hds/package.json",
+    "scripts/eslint-plugin-hds/rules/"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -242,7 +253,8 @@
     "hds-patterns-subpath": "codemods/patterns-subpath.mjs",
     "hds-prefix": "codemods/hds-prefix.mjs",
     "hds-not-found-pattern": "codemods/not-found-pattern.mjs",
-    "hds-tile-grid": "codemods/tile-grid.mjs"
+    "hds-tile-grid": "codemods/tile-grid.mjs",
+    "hds-mcp": "mcp/hds-mcp.mjs"
   },
   "scripts": {
     "_comment:a11y-high-value": "The following check:* validators are high-value accessibility checks that catch real violations (check:focus found 1 missing focus class). Kept dormant/manual-only to avoid pre-commit performance regression. Candidates to wire into pretest after CI stability review.",
@@ -258,7 +270,7 @@
     "audit:sidecar": "node scripts/generate-security-posture.mjs",
     "audit:style-dictionary": "bash scripts/poc/style-dictionary-poc/run.sh",
     "build-storybook": "storybook build",
-    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/embed-fonts.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs",
+    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/build-fonts-css.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs",
     "build:types": "tsc -p tsconfig.dts.json && node scripts/strip-dts-side-effects.mjs && node scripts/add-dts-extensions.mjs",
     "catalog": "node scripts/generate-visual-catalog.mjs",
     "changelog:generate": "node scripts/generate-changelog.mjs",
@@ -279,11 +291,13 @@
     "check:dimensions": "node scripts/check-dimensions.mjs",
     "check:doc-refs": "node scripts/check-link-integrity.mjs --doc-refs-only",
     "check:docs": "node scripts/audit-component-integrity.mjs --docs && node scripts/check-token-descriptions.mjs --no-missing --quality",
+    "check:docs-guardrails": "node scripts/check-docs.mjs",
     "check:exemptions": "node scripts/check-exemptions.mjs",
     "check:fast": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/build-tokens.mjs && node scripts/verify-tokens.mjs && node scripts/audit-tokens.mjs --full && pnpm typecheck && node scripts/check-css-integrity.mjs && node scripts/audit-component-integrity.mjs --tokens && pnpm check:docs && node scripts/check-ref-forwarding.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-dimensions.mjs && node scripts/check-hardcoded-breakpoints.mjs && node scripts/check-typography-discipline.mjs && pnpm check:mojibake && node scripts/check-style-discipline.mjs --style-props-only && node scripts/check-tier-bypass.mjs && node scripts/check-link-integrity.mjs --doc-refs-only && node scripts/check-brand.mjs && node scripts/check-registry.mjs && node scripts/check-template-source-of-truth.mjs",
     "check:figma-coverage": "node scripts/check-figma-coverage.mjs",
     "check:figma-drift": "node scripts/check-figma-drift.mjs",
     "check:figma-mapping": "node scripts/check-figma-mapping.mjs",
+    "check:figma-staging-urls": "node scripts/check-figma-staging-urls.mjs",
     "check:focus": "node scripts/check-focus-states.mjs",
     "check:font-files": "node scripts/check-typography-discipline.mjs --font-files-only",
     "check:fonts": "node scripts/check-typography-discipline.mjs --fonts-only",
@@ -317,6 +331,8 @@
     "check:spacing": "node scripts/check-hardcoded-spacing.mjs",
     "check:spacing-vocabulary": "node scripts/check-spacing-vocabulary.mjs",
     "check:story-coverage": "node scripts/check-story-coverage.mjs",
+    "check:layout-contract": "node scripts/check-layout-contract.mjs",
+    "check:spacing-scale": "node scripts/check-tailwind-spacing-scale.mjs",
     "check:storybook-axe": "node scripts/check-storybook-axe.mjs",
     "check:style-props": "node scripts/check-style-discipline.mjs --style-props-only",
     "check:sync-map": "node scripts/check-sync-map.mjs",
@@ -338,8 +354,12 @@
     "closure:plan:check": "node scripts/generate-closure-plan.mjs --check",
     "docs:api": "node scripts/generate-component-api.mjs",
     "docs:changelogs": "node scripts/generate-component-changelogs.mjs",
+    "docs:build": "pnpm docs:prepare && pnpm --dir docs-site build",
+    "docs:components": "node scripts/generate-docs-components.mjs",
     "docs:component": "node scripts/generate-component-page.mjs",
+    "docs:dev": "pnpm docs:prepare && pnpm --dir docs-site dev",
     "docs:llms": "node scripts/generate-llms-txt.mjs",
+    "docs:prepare": "pnpm build:lib && pnpm docs:api && pnpm docs:components && pnpm --dir docs-site install --frozen-lockfile",
     "docs:site": "node scripts/generate-component-page.mjs --all --clean",
     "docs:site:inline": "node scripts/generate-component-page.mjs --all --clean --inline",
     "docs:site:shots": "node scripts/generate-component-page.mjs --all --clean --shots",
@@ -363,8 +383,8 @@
     "health-commit": "pnpm check:semantic-report && node scripts/print-health-commit.mjs",
     "icons:sync": "node scripts/sync-icons.mjs",
     "knip": "knip",
-    "lint": "eslint src scripts validators tests --max-warnings=0",
-    "lint:fix": "eslint src scripts validators tests --fix",
+    "lint": "eslint src scripts validators tests mcp --max-warnings=0",
+    "lint:fix": "eslint src scripts validators tests mcp --fix",
     "llms:generate": "node scripts/generate-llms-txt.mjs",
     "skill:generate": "node scripts/generate-consumer-skill.mjs",
     "check:consumer-skill": "node scripts/generate-consumer-skill.mjs --check",
@@ -373,7 +393,7 @@
     "prebuild-storybook": "node scripts/generate-component-api.mjs",
     "prebuild:lib": "node scripts/generate-component-api.mjs",
     "prestorybook": "node scripts/generate-component-api.mjs",
-    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/audit-component-integrity.mjs --api && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-staging-inventory.mjs --check && node scripts/generate-consumer-skill.mjs --check && node scripts/check-deprecations.mjs",
+    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/audit-component-integrity.mjs --api && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-staging-inventory.mjs --check && node scripts/generate-consumer-skill.mjs --check && node scripts/generate-agents-md.mjs --check && node scripts/check-deprecations.mjs && node scripts/upgrade/schema.mjs --check && node scripts/check-docs.mjs && node --test scripts/check-docs.selftest.mjs",
     "pretypecheck": "node scripts/audit-tokens.mjs --report-only",
     "preview:build": "vite build --config preview/vite.config.mjs",
     "promote": "node scripts/promote.mjs",
@@ -382,6 +402,9 @@
     "scaffold:component": "node scripts/scaffold-component.mjs",
     "scaffold:tenant": "node scripts/scaffold-tenant.mjs",
     "size-limit": "size-limit --config .size-limit.cjs",
+    "layout-contract:generate": "node scripts/generate-layout-contract.mjs",
+    "status:touch": "node scripts/status-touch.mjs",
+    "status:fold": "node scripts/status-fold.mjs",
     "smoke:consumer": "node scripts/smoke-consumer.mjs && node scripts/check-published-types.mjs && node scripts/check-rsc-directives.mjs && node scripts/check-pack-contents.mjs",
     "storybook": "storybook dev -p 6006",
     "storybook:deploy": "node scripts/deploy-storybook.mjs",
@@ -394,7 +417,7 @@
     "test:figma": "npx tsx scripts/figma-sync.ts",
     "test:phase1": "node scripts/test-phase1.mjs",
     "test:watch": "vitest",
-    "tokens": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/check-typography-discipline.mjs --overrides-only && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/generate-llms-txt.mjs && node scripts/generate-consumer-skill.mjs && node scripts/build-readme-counts.mjs",
+    "tokens": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/check-typography-discipline.mjs --overrides-only && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/generate-llms-txt.mjs && node scripts/generate-consumer-skill.mjs && node scripts/generate-agents-md.mjs && node scripts/build-readme-counts.mjs",
     "tokens:audit": "node scripts/audit-component-integrity.mjs --tokens",
     "tokens:build": "node scripts/build-hds-tokens.mjs",
     "tokens:index": "node scripts/build-token-index.mjs",
@@ -406,6 +429,9 @@
     "watch:guardrails": "nodemon --watch CLAUDE.md --watch .cursorrules --watch eslint.config.js --watch .github/workflows -e md,json,js,yml,yaml --exec \"node scripts/audit-guardrails.js\"",
     "watch:metrics": "nodemon --watch src/app/components --watch src/app/pages --watch src/app/design-system --watch src/app/styles -e tsx,ts,css --exec \"node scripts/audit-tokens.mjs --full && node scripts/generate-manifest.mjs\"",
     "consumer:usage": "node scripts/count-consumer-usage.mjs",
-    "codemod:names": "node scripts/build-codemod-pattern-names.mjs"
+    "upgrade:consumers": "node scripts/upgrade/consumers.mjs",
+    "codemod:names": "node scripts/build-codemod-pattern-names.mjs",
+    "agents:generate": "node scripts/generate-agents-md.mjs",
+    "check:agents-md": "node scripts/generate-agents-md.mjs --check"
   }
 }