@hirobius/design-system 0.20.0 → 0.22.0

package/llms.txt

@@ -1,8 +1,67 @@
 # Hirobius Design System
 
-Generated: 2026-10-01T13:20:49.686Z
+Generated: 2026-10-07T16:09:09.631Z
 Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
 
+## Agents Using The Package: Start Here
+
+- Read `AGENTS.md` (package root, `node_modules/@hirobius/design-system/AGENTS.md`) first: which component to use for each screen need, the imports, and the rules.
+- MCP server `hds` ships in the package: run `npx hds-mcp` (stdio). Tools: `list_core`, `search_components`, `get_component`, `search_tokens`; each answer is under 2 KB.
+- Lint before you finish: `import hds from '@hirobius/design-system/eslint-plugin'` and spread `hds.configs.recommended` into `eslint.config.mjs`.
+
+## Pick By Need
+
+One answer per need. Use the components after the arrow; what follows "Not:" is what agents reached for instead, which is the wrong answer for that need even where it has a purpose of its own. Generated from `mcp/guide.mjs`, the same list as `AGENTS.md`.
+
+- **Outermost wrapper of a screen** → `Page`, `Stack`. Not: `Container`, `Box`, a bare Stack as the root.
+  `<Page><Stack gap="spacious">…one child per section…</Stack></Page>`. `Container` is for a full-bleed surface that is not a page.
+- **Screen title with breadcrumb, status and actions** → `PageHeader`, `Breadcrumb`, `Badge`. Not: Text as the page title, a Stack row of Text and Badge.
+  Exactly one per screen: `<PageHeader breadcrumb={<Breadcrumb items={[{ label, href }, { label }]} />} title="…" status={<Badge tone="success">Active</Badge>} />`.
+- **Row of headline numbers (stats, KPIs, counts, totals)** → `MetricTiles`, `MetricTile`. Not: `Stat`, `StatusTile`, `CardMetric`, Card with Text.
+  `<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).
+- **Table of records with row actions** → `DataTableSection`, `Badge`, `Button`. Not: Table on its own, Card around a Table.
+  `<DataTableSection title="Projects" columns={[{ key, label }]} rows={[{ key, cells: [...], actions: <Stack direction="row" gap="tight">…</Stack> }]} />`; leave the actions column out of `columns`.
+- **Switch between panels of related content** → `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Not: `SegmentedControl`, Button rows.
+  `<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>`.
+- **Status label in a header or table cell** → `Badge`. Not: `Tag`, `Text`.
+  `<Badge tone="success|info|warning|danger|neutral|inProgress">…</Badge>`; tone is the only styling input.
+- **Form with fields and a submit button** → `Form`, `Textarea`, `Input`, `FormActions`, `Button`. Not: a raw `<form>`, a Stack of Buttons as the footer.
+  `<Form onSubmit={…}><Textarea label="Notes" … /><FormActions primary={<Button type="submit">Save note</Button>} /></Form>`; every field takes its own `label`.
+- **Confirm a destructive or irreversible action (delete, archive, remove)** → `AlertDialog`, `Button`. Not: `Dialog`, `window.confirm`.
+  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.
+- **Brief confirmation after an action (saved, archived, sent)** → `ToastProvider`, `useToast`. Not: `Badge`, `Alert`, `Text`.
+  Wrap the app root once in `<ToastProvider>`, then `toast({ title: "Note saved", tone: "success" })` from `useToast()`.
+- **Message that stays next to its content (error, warning, info)** → `Alert`. Not: Text in a coloured Surface.
+  `<Alert tone="warning">…</Alert>`.
+- **Button or row action** → `Button`. Not: a raw `<button>`, InlineLink for an action.
+  Row actions: `<Button variant="tertiary" size="sm" aria-label="View Brand refresh">View</Button>`; the destructive one adds `tone="danger"`.
+- **Space between sections or items** → `Stack`, `Grid`. Not: margins on children, raw px gaps such as px8.
+  Stack `gap`: `spacious` between page sections, `normal` inside a section, `tight` between buttons. `Grid` for two-dimensional layout.
+- **Padded background or a titled content object** → `Surface`, `Card`. Not: a Box with background and padding.
+  `Surface` for a plain padded background; `Card` only when the content has a title or can be pressed.
+- **Progress bar or ring** → `Progress`. Not: a hand-built bar.
+  `<Progress value={60} label="Upload" />`; inside an existing `Card`, `CardProgress`.
+- **Body copy** → `Text`. Not: Text as a section heading.
+  Section headings come from the pattern that owns the section (`PageHeader` `title`, `DataTableSection` `title`), not from extra Text.
+- **Empty state for a list or section** → `EmptyState`. Not: Text saying "No items".
+  `DataTableSection` shows its own through `emptyTitle`; use `EmptyState` elsewhere.
+- **The one irreversible action of a screen (delete the client, close the account)** → `DestructiveSection`. Not: a danger Button that acts without a confirm.
+  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.
+- **Read-only details as label and value pairs** → `MetadataList`, `Field`. Not: a Table with two columns, Text pairs in a Stack.
+  `<MetadataList items={[{ term: "Owner", description: "Ada" }]} />` for a set; `Field` for one pair.
+- **A person, or a group of people** → `Avatar`, `AvatarGroup`. Not: an image in a rounded Box.
+  `<Avatar src alt initials />`; several in a row: `<AvatarGroup max={3}>…Avatars…</AvatarGroup>`.
+- **A date or time** → `Timestamp`. Not: a formatted string in Text.
+  `<Timestamp date="2026-10-14" />` renders a `<time dateTime>`; a date in a table cell may stay plain text.
+- **A keyboard key or shortcut hint** → `Kbd`. Not: `InlineCode`, Text in a Box.
+  `<Kbd>⌘K</Kbd>`.
+- **A quotation with attribution** → `Blockquote`. Not: Callout for a quote, italic Text.
+  `<Blockquote attribution="Ada Lovelace">…</Blockquote>`.
+- **A fixed-width side rail beside fluid content, or a row that stacks when narrow** → `Sidebar`, `Switcher`. Not: a Grid with media queries.
+  `Sidebar` (`side`, `sideWidth`) for rail + content; `Switcher` (`threshold`) for a row that flips to a column. Neither needs a media query.
+- **Keep an element stuck while its region scrolls** → `Pin`. Not: position: sticky in style.
+  `<Pin top="…">…</Pin>` inside the scrolling region.
+
 ## System Architecture
 
 - Engine: React + TypeScript
@@ -36,56 +95,105 @@ This file intentionally does not embed prop tables or long-form API docs.
 - Detailed prop types, unions, defaults, and descriptions: read `src/app/data/component-api.json`.
 - Runtime behavior: read the actual component source under `src/app/components/` (and associated styles).
 
+## Core set
+
+The 43 components of the ratified core set (hds#254, ADR-031): brand-neutral, composable, imported from the package root. Build a screen from these first. Each has `core: true` in `public/hds-manifest.json` and is marked `[core]` under "Which one when". Composed pattern modules (page shells, forms, code blocks, page sections) are imported from `@hirobius/design-system/patterns`.
+
+- Button (Actions)
+- Avatar (Display)
+- Card (Display)
+- EmptyState (Display)
+- Field (Display)
+- Icon (Display)
+- Kbd (Display)
+- Table (Display)
+- Alert (Feedback)
+- Badge (Feedback)
+- Progress (Feedback)
+- Skeleton (Feedback)
+- Spinner (Feedback)
+- ToastProvider (Feedback)
+- Checkbox (Inputs)
+- Combobox (Inputs)
+- Input (Inputs)
+- Radio (Inputs)
+- SegmentedControl (Inputs)
+- Select (Inputs)
+- Slider (Inputs)
+- Tag (Inputs)
+- Textarea (Inputs)
+- Toggle (Inputs)
+- Box (Layout)
+- Container (Layout)
+- Disclosure (Layout)
+- Divider (Layout)
+- Grid (Layout)
+- Stack (Layout)
+- Surface (Layout)
+- Breadcrumb (Navigation)
+- InlineLink (Navigation)
+- Pagination (Navigation)
+- Tabs (Navigation)
+- Dialog (Overlays)
+- Menu (Overlays)
+- Popover (Overlays)
+- Tooltip (Overlays)
+- HdsRouterProvider (Theming)
+- HdsThemeProvider (Theming)
+- Text (Typography)
+- VisuallyHidden (Utility)
+
 ## Which one when
 
-One line per component that declares when to use it (`@usage` / `@useInstead` in its JSDoc). Full detail, including `usage.whenNot`, `keyboard` and `aiRules`, is in `public/hds-manifest.json` and `src/app/data/component-api.json`.
-
-Alert: Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
-Avatar: Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
-Badge: Label a status, state or count with a compact neutral or semantic chip, or a dot. Use instead: Tag, Alert
-Box: Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
-Breadcrumb: Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
-Button: Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
-Card: Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option. Use instead: Surface, Card.Metric
-CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card.
-Checkbox: Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
-Combobox: Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
-Container: Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
-Dialog: Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: Tooltip, Alert, ToastProvider
-Disclosure: Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
-Divider: Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
-EmptyState: Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
-Field: Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
-Grid: Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
-HdsRouterProvider: Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors.
-HdsThemeProvider: Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
-Icon: Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
-InlineLink: Link to a route or external URL from inside body copy. Use instead: Button, Text
-Input: Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots. Use instead: Textarea, Select, Combobox
-Kbd: Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
-Menu: Offer a list of actions from a trigger, closed until opened. Use instead: Select
-Pagination: Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
-Popover: Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open. Use instead: Tooltip, Menu, Dialog
-Progress: Show how far a task has got, as a bar or ring that is determinate or indeterminate. Use instead: Spinner, Skeleton
-Radio: Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
-SegmentedControl: Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
-Select: Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
-Skeleton: Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
-Slider: Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
-Spinner: Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
-Stack: Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
-Stat: Show one standalone headline figure with its label and an optional sub-line. Use instead: Card.Metric, StatusTile
-StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: Card.Metric, StatusListItem
-Surface: Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
-Table: Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
-Tabs: Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
-Tag: Show an interactive filter or category chip that people can toggle. Use instead: Badge
-Text: Set any text on the type ramp, with the element chosen by `as`. Use instead: InlineLink, Kbd
-Textarea: Collect multi-line free text such as a message, note or description. Use instead: Input
-ToastProvider: Confirm an action with a brief message that appears and dismisses itself, through useToast. Use instead: Alert, Dialog
-Toggle: Switch one setting on or off, with the effect applying immediately. Use instead: Checkbox, Radio
-Tooltip: Name an icon-only control, or add a short hint that appears on hover and keyboard focus. Use instead: Popover, Text
-VisuallyHidden: Give assistive technology a label or description that sighted people do not need to see. Use instead: Text
+One line per component that declares when to use it (`@usage` / `@useInstead` in its JSDoc); `[core]` marks the core set. Full detail, including `usage.whenNot`, `keyboard` and `aiRules`, is in `public/hds-manifest.json` and `src/app/data/component-api.json`.
+
+Alert: [core] Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
+AlertDialog: Confirm a destructive or irreversible action (delete, archive, remove) before it runs, with Cancel and Action buttons. Use instead: Dialog, ToastProvider
+Avatar: [core] Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
+Badge: [core] Label a status, state or count with a compact neutral or semantic chip, or a dot. Use instead: Tag, Alert
+Box: [core] Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
+Breadcrumb: [core] Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
+Button: [core] Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
+Card: [core] Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option. Use instead: Surface, Card.Metric
+CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card. Use instead: MetricTiles
+Checkbox: [core] Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
+Combobox: [core] Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
+Container: [core] Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
+Dialog: [core] Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: Tooltip, Alert, ToastProvider, AlertDialog
+Disclosure: [core] Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
+Divider: [core] Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
+EmptyState: [core] Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
+Field: [core] Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
+Grid: [core] Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
+HdsRouterProvider: [core] Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors.
+HdsThemeProvider: [core] Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
+Icon: [core] Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
+InlineLink: [core] Link to a route or external URL from inside body copy. Use instead: Button, Text
+Input: [core] Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots. Use instead: Textarea, Select, Combobox
+Kbd: [core] Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
+Menu: [core] Offer a list of actions from a trigger, closed until opened. Use instead: Select
+Pagination: [core] Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
+Popover: [core] Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open. Use instead: Tooltip, Menu, Dialog
+Progress: [core] Show how far a task has got, as a bar or ring that is determinate or indeterminate. Use instead: Spinner, Skeleton
+Radio: [core] Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
+SegmentedControl: [core] Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
+Select: [core] Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
+Skeleton: [core] Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
+Slider: [core] Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
+Spinner: [core] Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
+Stack: [core] Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
+Stat: Show one headline figure inline, inside prose or a dense list, with its label and an optional sub-line. Use instead: MetricTiles, Card.Metric, StatusTile
+StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: MetricTiles, Card.Metric, StatusListItem
+Surface: [core] Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
+Table: [core] Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
+Tabs: [core] Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
+Tag: [core] Show an interactive filter or category chip that people can toggle. Use instead: Badge
+Text: [core] Set any text on the type ramp, with the element chosen by `as`. Use instead: InlineLink, Kbd
+Textarea: [core] Collect multi-line free text such as a message, note or description. Use instead: Input
+ToastProvider: [core] Confirm an action with a brief message that appears and dismisses itself, through useToast. Use instead: Alert, Dialog
+Toggle: [core] Switch one setting on or off, with the effect applying immediately. Use instead: Checkbox, Radio
+Tooltip: [core] Name an icon-only control, or add a short hint that appears on hover and keyboard focus. Use instead: Popover, Text
+VisuallyHidden: [core] Give assistive technology a label or description that sighted people do not need to see. Use instead: Text
 
 ## Tokens (Primary Source Of Truth)
 
@@ -114,7 +222,7 @@ Canonical skeleton, outermost to innermost:
 2. `Stack` (vertical rhythm between sections) or `Grid` (two-dimensional/column layout) for the structural skeleton. One section = one Section/Stack — never add a second wrapper to fake a section boundary.
 3. Reach for a named layout primitive before hand-rolling flex/grid math for a common intent: `Stack direction="row" wrap="wrap"` (wrapping row of same-ish things), `Sidebar` (fixed-width rail + fluid content, no media query), `Switcher` (row that flips to a column below a threshold, no media query). A full-height shell with a centered main region, an aspect-ratio-locked media box or a negative margin that escapes a parent padding is a `Box` with `style` (not `sx`, which applies on the client only).
 4. `Surface` for any background-bearing, padded wrapper (card, panel, inset). Never a raw element with backgroundColor + padding hand-rolled inline.
-5. Use the screen patterns (`@hirobius/design-system/patterns`) for the parts every screen repeats: `PageHeader` once at the top (breadcrumb, `heading2` title, status, actions), `MetricTiles` for any row of headline numbers, `FormActions` for a form footer (primary right-most and last in DOM order, destructive on the far left), `DataTableSection` for a titled table (toolbar slot, consumer row actions, empty state, scrolls on narrow widths without a caller `minWidth`), and `DestructiveSection` last for an irreversible action (danger button, then an `AlertDialog` confirm). Pick between `MetricTiles`, `Stat`, `Card.Metric` and `StatusTile`, and between `Card` and `Surface`, with the "Which one, when" table in `DESIGN.md`.
+5. Use the screen patterns (`@hirobius/design-system/patterns`) for the parts every screen repeats: `PageHeader` once at the top (breadcrumb, `heading2` title, status, actions), `MetricTiles` for any row of headline numbers, `FormActions` for a form footer (primary right-most and last in DOM order, destructive on the far left), `DataTableSection` for a titled table (toolbar slot, consumer row actions, empty state, scrolls on narrow widths without a caller `minWidth`), and `DestructiveSection` last for an irreversible action (danger button, then an `AlertDialog` confirm). A row of headline numbers is always `MetricTiles`; `Stat`, `Card.Metric` and `StatusTile` answer other needs (see "Pick By Need" in `llms.txt`). Pick between `Card` and `Surface` with the "Which one, when" table in `DESIGN.md`.
 6. `Box` `sx` LAST — only for genuinely one-off layout that no named primitive covers. `sx` spacing/color keys MUST be HDS token keys, never raw hex/px.
 
 Negative rules (apply everywhere, checked by `scripts/audit-tokens.mjs --full`, `check-hardcoded-spacing.mjs`, `check-hardcoded-colors.mjs`):

package/mcp/catalog.mjs

@@ -0,0 +1,369 @@
+/**
+ * The `hds` MCP server's tools, built from the data the package already ships.
+ *
+ * Interface: `loadCatalog(packageRoot)` returns `{ instructions, tools }`, where
+ * each tool is `{ name, description, inputSchema, run(args) }` and `run` returns
+ * a plain object the server serialises. Every result is kept under RESULT_BUDGET
+ * bytes as it travels (the JSON text, escaped again inside the JSON-RPC
+ * response line): an agent asks a narrow question and gets a narrow answer, never
+ * the 400 KB manifest.
+ *
+ * Sources, all inside the installed package:
+ *   src/app/data/component-api.json      props, descriptions, usage contracts
+ *   public/hds-manifest.json             compound parts, keyboard, tokens (cssVar, light/dark values)
+ *   codemods/patterns-subpath.names.json which names import from /patterns
+ *   mcp/guide.mjs                        which component answers which need
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CORE_COMPONENTS } from './core-set.mjs';
+import { HOOKS, INTENTS, recommendedComponents } from './guide.mjs';
+
+export const RESULT_BUDGET = 1900;
+
+/** Bytes a result costs inside a tools/call response: its JSON, escaped as a string. */
+const bytes = (value) => Buffer.byteLength(JSON.stringify(JSON.stringify(value)));
+
+const ROOT_IMPORT = '@hirobius/design-system';
+
+const STOPWORDS = new Set(
+  'a an and as at by for from in into is it of on or the to with without show use'.split(' '),
+);
+
+const readJson = (root, rel) => JSON.parse(readFileSync(join(root, rel), 'utf8'));
+
+const words = (text) =>
+  String(text ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9.]+/)
+    .filter((w) => w && !STOPWORDS.has(w));
+
+function firstSentence(text = '', max = 160) {
+  const flat = String(text).replace(/\s+/g, ' ').trim();
+  const m = /^(.+?[.!?])(?=\s|$)/.exec(flat);
+  const s = m ? m[1] : flat;
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+/** Levenshtein distance, for "did you mean" on a misspelt component name. */
+function editDistance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** Drops the entries of `list` from the end until `make(list)` fits the budget. */
+function fitList(list, make) {
+  let n = list.length;
+  let out = make(list, 0);
+  while (n > 0 && bytes(out) > RESULT_BUDGET) {
+    n -= 1;
+    out = make(list.slice(0, n), list.length - n);
+  }
+  return out;
+}
+
+export function loadCatalog(root) {
+  const api = readJson(root, 'src/app/data/component-api.json').components;
+  const manifest = readJson(root, 'public/hds-manifest.json');
+  const patternNames = new Set(readJson(root, 'codemods/patterns-subpath.names.json').names);
+
+  /**
+   * The flags both search_components and get_component put on a component:
+   * `core` for the ratified core set, `recommended` for the rest of what the guide prefers, `insteadFor` for each need it is the
+   * wrong answer to (the guide names `use` instead).
+   */
+  const steer = (name) => {
+    const insteadFor = INTENTS.filter((i) => i.avoid.includes(name)).map((i) => ({
+      need: i.need,
+      use: i.use[0],
+    }));
+    return {
+      ...(ratified.has(name) ? { core: true } : recommended.has(name) ? { recommended: true } : {}),
+      ...(insteadFor.length ? { insteadFor } : {}),
+    };
+  };
+  const ratified = new Set(CORE_COMPONENTS);
+  const recommended = new Set(recommendedComponents());
+  const components = Object.keys(api)
+    .filter((name) => !api[name].hidden)
+    .sort();
+  const byLower = new Map(components.map((n) => [n.toLowerCase(), n]));
+  const importOf = (name) => (patternNames.has(name) ? `${ROOT_IMPORT}/patterns` : ROOT_IMPORT);
+
+  const tokens = Object.values(manifest.tokens ?? {}).flat();
+
+  // Flat aliases of compound parts (DialogContent for Dialog.Content): searchable by
+  // exact name only, so a purpose search returns the root component, not its parts.
+  const partAliases = new Set();
+  for (const [name, spec] of Object.entries(manifest.componentSpecs ?? {})) {
+    for (const m of spec.compoundMembers ?? [])
+      partAliases.add(`${name}${typeof m === 'string' ? m : m.name}`);
+  }
+
+  // ── search_components ───────────────────────────────────────────────────
+  function rankComponents(query) {
+    const q = String(query ?? '').trim();
+    const qWords = words(q);
+    const compact = q.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const scores = new Map(components.map((n) => [n, 0]));
+    const add = (name, n) => scores.has(name) && scores.set(name, scores.get(name) + n);
+
+    const matchedIntents = [];
+    for (const intent of INTENTS) {
+      const hits =
+        q.toLowerCase() === intent.id
+          ? 3
+          : qWords.filter((w) => intent.keywords.includes(w)).length;
+      if (!hits) continue;
+      matchedIntents.push({ intent, hits });
+      intent.use.forEach((name, i) => add(name, 10 * hits + (i === 0 ? 5 : 0)));
+    }
+    for (const name of components) {
+      const lower = name.toLowerCase();
+      if (lower === compact) add(name, 100);
+      else if (partAliases.has(name) && !recommended.has(name)) continue;
+      else if (qWords.some((w) => w.length > 2 && (lower.includes(w) || w.includes(lower))))
+        add(name, 20);
+      const entry = api[name];
+      const text = words(`${entry.description} ${entry.usage?.when ?? ''}`);
+      add(name, 2 * qWords.filter((w) => text.includes(w)).length);
+      if (scores.get(name) > 0) {
+        if (recommended.has(name)) add(name, 1);
+      }
+    }
+    const ranked = components
+      .filter((n) => scores.get(n) > 0)
+      .sort((a, b) => scores.get(b) - scores.get(a) || (a < b ? -1 : 1));
+    matchedIntents.sort((a, b) => b.hits - a.hits);
+    return { ranked, intents: matchedIntents.map((m) => m.intent) };
+  }
+
+  function searchComponents({ query, limit = 8 }) {
+    if (!String(query ?? '').trim()) throw new Error('query is required, e.g. "confirm delete"');
+    const { ranked, intents } = rankComponents(query);
+    const top = ranked.slice(0, Math.min(Math.max(1, limit), 8)).map((name) => ({
+      name,
+      import: importOf(name),
+      summary: firstSentence(api[name].usage?.when || api[name].description, 120),
+      ...steer(name),
+    }));
+    return fitList(top, (results) => ({
+      results,
+      needs: intents.slice(0, 2).map((i) => ({ need: i.need, use: i.use })),
+    }));
+  }
+
+  // ── get_component ───────────────────────────────────────────────────────
+  function getComponent({ name }) {
+    const base = String(name ?? '')
+      .trim()
+      .split('.')[0];
+    const canonical = byLower.get(base.toLowerCase()) ?? (HOOKS[base] ? base : null);
+    if (!canonical) {
+      const target = base.toLowerCase();
+      const close = components
+        .map((n) => ({ n, d: editDistance(n.toLowerCase(), target) }))
+        .filter((c) => c.d <= Math.max(2, Math.floor(target.length / 3)))
+        .sort((a, b) => a.d - b.d || (a.n < b.n ? -1 : 1))
+        .slice(0, 3)
+        .map((c) => c.n);
+      throw new Error(
+        `No component named "${name}".${close.length ? ` Did you mean: ${close.join(', ')}?` : ''} Use search_components to find one.`,
+      );
+    }
+    if (HOOKS[canonical]) return { name: canonical, kind: 'hook', ...HOOKS[canonical] };
+
+    const entry = api[canonical];
+    const spec = manifest.componentSpecs?.[canonical] ?? {};
+    const guide = INTENTS.filter((i) => i.use.includes(canonical)).map((i) => ({
+      need: i.need,
+      how: i.how,
+    }));
+    const propLine = (p, withDesc, typeMax) => {
+      const type = p.type.length > typeMax ? `${p.type.slice(0, typeMax - 1)}…` : p.type;
+      const def = p.default !== undefined ? ` = ${p.default}` : '';
+      const desc = withDesc && p.description ? ` — ${firstSentence(p.description, 90)}` : '';
+      return `${p.name}${p.required ? '' : '?'}: ${type}${def}${desc}`;
+    };
+    const build = (withDesc, typeMax, withHow) => ({
+      name: canonical,
+      import: importOf(canonical),
+      category: entry.category,
+      summary: firstSentence(entry.description, 200),
+      ...steer(canonical),
+      ...(entry.usage?.when ? { when: entry.usage.when } : {}),
+      ...(entry.usage?.whenNot ? { whenNot: entry.usage.whenNot } : {}),
+      ...(entry.usage?.useInstead?.length
+        ? { useInstead: entry.usage.useInstead.map((u) => `${u.component}: ${u.reason}`) }
+        : {}),
+      ...(spec.compoundMembers?.length
+        ? {
+            parts: spec.compoundMembers.map(
+              (m) => `${canonical}.${typeof m === 'string' ? m : m.name}`,
+            ),
+          }
+        : {}),
+      props: (entry.props ?? []).map((p) => propLine(p, withDesc, typeMax)),
+      ...(guide.length ? { guide: withHow ? guide : guide.map((g) => ({ need: g.need })) } : {}),
+    });
+    for (const [withDesc, typeMax, withHow] of [
+      [true, 80, true],
+      [false, 80, true],
+      [false, 48, true],
+      [false, 48, false],
+    ]) {
+      const out = build(withDesc, typeMax, withHow);
+      if (bytes(out) <= RESULT_BUDGET) return out;
+    }
+    const out = build(false, 32, false);
+    return fitList(out.props, (props, dropped) => ({
+      ...out,
+      props,
+      ...(dropped ? { propsOmitted: dropped, propsSource: 'src/app/data/component-api.json' } : {}),
+    }));
+  }
+
+  // ── search_tokens ───────────────────────────────────────────────────────
+  const tokenRow = (t) => ({
+    path: t.path,
+    cssVar: t.cssVar,
+    value: t.resolvedValue ?? t.value ?? t.composite ?? null,
+    ...(t.dark ? { dark: t.dark.resolvedValue ?? t.dark.value } : {}),
+  });
+
+  function searchTokens({ query, limit = 25 }) {
+    const q = String(query ?? '')
+      .trim()
+      .toLowerCase()
+      .replace(/^--/, '')
+      .replace(/^var\(--|\)$/g, '');
+    if (!q)
+      throw new Error(
+        'query is required: a path, a prefix ("semantic.space") or a word ("surface")',
+      );
+    const exact = tokens.find(
+      (t) => t.path.toLowerCase() === q || t.cssVar?.toLowerCase() === `--${q}`,
+    );
+    if (exact) {
+      return {
+        token: {
+          ...tokenRow(exact),
+          type: exact.type,
+          ...(exact.alias ? { alias: exact.alias } : {}),
+          description: firstSentence(exact.description, 300),
+        },
+      };
+    }
+    const tierRank = { semantic: 0, role: 1, component: 2, primitive: 3 };
+    const qWords = q.split(/[\s,]+/).filter(Boolean);
+    const matches = tokens
+      .map((t) => {
+        const path = t.path.toLowerCase();
+        let score = 0;
+        if (path.startsWith(`${q}.`) || path.startsWith(q)) score = 3;
+        else if (qWords.every((w) => path.includes(w))) score = 2;
+        else if (qWords.every((w) => `${path} ${t.description ?? ''}`.toLowerCase().includes(w)))
+          score = 1;
+        return { t, score };
+      })
+      .filter((m) => m.score > 0)
+      .sort(
+        (a, b) =>
+          b.score - a.score ||
+          (tierRank[a.t.path.split('.')[0]] ?? 9) - (tierRank[b.t.path.split('.')[0]] ?? 9) ||
+          (a.t.path < b.t.path ? -1 : 1),
+      );
+    const cap = Math.min(Math.max(1, limit), 40);
+    const rows = matches.slice(0, cap).map((m) => tokenRow(m.t));
+    return fitList(rows, (results) => ({
+      total: matches.length,
+      results,
+      ...(matches.length > results.length ? { more: matches.length - results.length } : {}),
+    }));
+  }
+
+  // ── list_core ───────────────────────────────────────────────────────────
+  function listCore() {
+    const names = [...recommended].filter((n) => api[n]);
+    // `id → use`: short enough that every need fits; search_components takes the id.
+    const needs = INTENTS.map((i) => `${i.id} → ${i.use.join(', ')}`);
+    // Needs are ordered most common first; what does not fit is one search_components away.
+    return fitList(needs, (shown, dropped) => ({
+      set: 'recommended: the ratified core plus what the needs name',
+      root: names.filter((n) => !patternNames.has(n)),
+      patterns: names.filter((n) => patternNames.has(n)),
+      hooks: Object.keys(HOOKS),
+      needs: shown,
+      ...(dropped ? { moreNeeds: dropped, forMore: 'search_components with the need' } : {}),
+    }));
+  }
+
+  const tools = [
+    {
+      name: 'search_components',
+      description:
+        'Find HDS components by name or by what you need ("row of headline numbers", "confirm delete"). Returns up to 8 matches with their import path, and the guide entry for the need.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'A component name or a plain-language need.' },
+          limit: { type: 'integer', minimum: 1, maximum: 8 },
+        },
+        required: ['query'],
+      },
+      run: searchComponents,
+    },
+    {
+      name: 'get_component',
+      description:
+        "One component's import path, usage contract (when, when not, use instead), props and compound parts, plus how the guide says to use it. Call before using a component.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'Component name, e.g. "MetricTiles" or "AlertDialog".',
+          },
+        },
+        required: ['name'],
+      },
+      run: getComponent,
+    },
+    {
+      name: 'search_tokens',
+      description:
+        'Look up design tokens. An exact path or CSS variable returns that token with its description; a prefix ("semantic.space") or words ("surface page") return matching tokens, semantic tier first, with CSS variable and light/dark values.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Token path, prefix, CSS variable or words.' },
+          limit: { type: 'integer', minimum: 1, maximum: 40 },
+        },
+        required: ['query'],
+      },
+      run: searchTokens,
+    },
+    {
+      name: 'list_core',
+      description:
+        'The core components to prefer, split by import path, the hooks, and one line per screen need (`id → components`; pass an id to search_components for its usage line). Call this first.',
+      inputSchema: { type: 'object', properties: {} },
+      run: listCore,
+    },
+  ];
+
+  const instructions = [
+    'Lookups for @hirobius/design-system (HDS). Call list_core first, then get_component for each component before you use it.',
+    'Import pattern-tier components (Page, PageHeader, MetricTiles, DataTableSection, Form, FormActions) from @hirobius/design-system/patterns, everything else from @hirobius/design-system.',
+    'Style with component props and semantic tokens only (search_tokens); no raw hex, px or Tailwind classes. The package AGENTS.md has the full rules.',
+  ].join(' ');
+
+  return { instructions, tools };
+}