@handamade/psi-mcp 0.7.1 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Kurkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @handamade/psi-mcp
 
-MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 15 React 19 components, 3 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 18 React 19 components, 4 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
 
 ## Connect
 

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.7.1",
+ "version": "0.8.0",
  "themes": [
   "light",
   "dark",
@@ -700,6 +700,121 @@
    ],
    "slots": [],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# AspectRatio\n\nFixed-aspect-ratio box that sizes its child media.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `ratio` | `number` | — | yes | Width/height ratio, e.g. 16/10 or 4/5. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the frame element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-aspect-ratio-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "Menu",
+   "description": "Action menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.",
+   "props": [
+    {
+     "name": "open",
+     "type": "boolean",
+     "required": true,
+     "default": null,
+     "description": "Controlled open state; syncs to showPopover()/hidePopover()."
+    },
+    {
+     "name": "onClose",
+     "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => void",
+     "required": true,
+     "default": null,
+     "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step."
+    },
+    {
+     "name": "trigger",
+     "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
+     "required": true,
+     "default": null,
+     "description": "The trigger element. Must be a single React element that spreads unknown\nprops onto a focusable node (a Psi `Button`, say): Menu clones it to add\n`aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates\nthe menu with the control users actually focus."
+    },
+    {
+     "name": "placement",
+     "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\"",
+     "required": false,
+     "default": "bottom-start",
+     "description": "Placement relative to the trigger."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name for the menu when there is no visible label."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the popover element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "trigger",
+     "accepts": {
+      "contracts": [
+       "interactive"
+      ]
+     },
+     "cardinality": "1..1",
+     "order": 1
+    },
+    {
+     "name": "body",
+     "accepts": {
+      "components": [
+       "MenuItem",
+       "MenuSeparator"
+      ]
+     },
+     "cardinality": "1..*",
+     "order": 2
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Menu\n\nAction menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showPopover()/hidePopover(). |\n| `onClose` | `(reason: \"item-select\" \\| \"esc\" \\| \"outside\") => void` | — | yes | Called when a dismissal is *requested*; the consumer flips `open`. Menu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays open until `open` becomes false (D50). `\"outside\"` is the one exception: light dismiss is performed by the browser before it tells us, so by the time that reason is reported the popover is already closed. Flipping `open` to false is still required, to keep React's state in step. |\n| `trigger` | `ReactElement<Record<string, unknown>, string \\| JSXElementConstructor<any>>` | — | yes | The trigger element. Must be a single React element that spreads unknown props onto a focusable node (a Psi `Button`, say): Menu clones it to add `aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates the menu with the control users actually focus. |\n| `placement` | `\"bottom-start\" \\| \"bottom-end\" \\| \"top-start\" \\| \"top-end\"` | bottom-start | no | Placement relative to the trigger. |\n| `aria-label` | `string` | — | no | Accessible name for the menu when there is no visible label. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the popover element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Down / Arrow Up | Moves between enabled items, wrapping at both ends. Disabled items are skipped. |\n| Home / End | Jumps to the first or last enabled item. |\n| Any single printable key | Typeahead — focuses the first enabled item whose label starts with the typed prefix; the prefix resets after 500ms. Keystrokes with Meta/Ctrl/Alt held are ignored. |\n| Esc | Suppresses the platform's own dismissal and reports onClose(\"esc\"); the menu stays open until the consumer flips `open` (D50). |\n| Enter / Space | Activates the focused item (native button behavior). |\n\nOpens on the native top layer via popover=\"auto\", which supplies light dismiss. Controlled-only: every dismissal path (esc, item-select, outside) only reports onClose(reason) — the consumer must flip `open` to actually close it; outside is the one path the platform has already acted on by the time it is reported. Opening moves focus to the first enabled item — Menu takes focus off the trigger as soon as `open` becomes true. Focus returns to the trigger when the menu actually closes, and only if focus is still inside the menu, so a light dismiss onto another control does not steal focus back. Requires an accessible name — pass aria-label. Placement uses CSS anchor positioning where supported and a JS fallback below that floor; below it there is no collision flip.\n\n## Theming\n\nOverride `--psi-menu-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "MenuItem",
+   "description": "One action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).",
+   "props": [
+    {
+     "name": "onSelect",
+     "type": "() => void",
+     "required": true,
+     "default": null,
+     "description": "Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50)."
+    },
+    {
+     "name": "variant",
+     "type": "\"neutral\" | \"danger\"",
+     "required": false,
+     "default": "neutral",
+     "description": "danger is for destructive actions only (house rule)."
+    },
+    {
+     "name": "disabled",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": ""
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# MenuItem\n\nOne action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `onSelect` | `() => void` | — | yes | Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50). |\n| `variant` | `\"neutral\" \\| \"danger\"` | neutral | no | danger is for destructive actions only (house rule). |\n| `disabled` | `boolean` | false | no |  |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates; Menu reports onClose(\"item-select\") but does not close itself. |\n\nRenders a real <button>. disabled sets aria-disabled (not the disabled attribute) so the item stays discoverable to assistive tech while being skipped by roving navigation. variant=\"danger\" is for destructive actions only.\n\n## Theming\n\nThis component has no `--psi-menu-item-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "MenuSeparator",
+   "description": "Hairline rule between Menu item groups. No props by design (D53).",
+   "props": [],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# MenuSeparator\n\nHairline rule between Menu item groups. No props by design (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n\n\nNon-interactive rule with role=\"separator\" — exposed to assistive tech as a separator, never focusable, and skipped by roving navigation.\n\n## Theming\n\nThis component has no `--psi-menu-separator-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   }
  ],
  "tokens": [
@@ -2251,14 +2366,14 @@
     }
    ],
    "content": {
-    "title": "<Delete the object?>",
-    "consequence": "<what is permanently lost>",
+    "title": "[Delete the object?]",
+    "consequence": "[what is permanently lost]",
     "cancel-label": "Cancel",
-    "confirm-label": "<verb the object>"
+    "confirm-label": "[verb the object]"
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Dialog\n  footer={<>\n    <Button size={32} variant=\"ghost\">Cancel</Button>\n    <Button size={32} variant=\"danger\"><verb the object></Button>\n  </>}\n  title=\"<Delete the object?>\"\n>\n  <what is permanently lost>\n</Dialog>\n"
+   "preset": "<Dialog\n  footer={<>\n    <Button size={32} variant=\"ghost\">Cancel</Button>\n    <Button size={32} variant=\"danger\">[verb the object]</Button>\n  </>}\n  title=\"[Delete the object?]\"\n>\n  [what is permanently lost]\n</Dialog>\n"
   },
   {
    "id": "filter-toolbar",
@@ -2288,11 +2403,80 @@
    },
    "parameters": [],
    "content": {
-    "example-filter": "<active filter>"
+    "example-filter": "[active filter]"
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Toolbar>\n  <Input />\n  <Select />\n  <Tag><active filter></Tag>\n</Toolbar>\n"
+   "preset": "<Toolbar>\n  <Input />\n  <Select />\n  <Tag>[active filter]</Tag>\n</Toolbar>\n"
+  },
+  {
+   "id": "row-actions",
+   "intent": "List or table row with a labelled actions menu, including a destructive item — hand the destructive item's confirmation off to the destructive-confirm pattern. The trigger is a text Button, not an icon-only kebab: IconButton cannot carry an accessible name through the manifest, so it is not composable in a pattern yet",
+   "match": [
+    "row actions",
+    "per-row actions",
+    "table row menu",
+    "actions menu",
+    "row action list"
+   ],
+   "compose": {
+    "component": "Menu",
+    "props": {
+     "placement": "{param:placement}",
+     "aria-label": "{content:trigger-label}"
+    },
+    "slots": {
+     "trigger": [
+      {
+       "component": "Button",
+       "props": {
+        "variant": "ghost"
+       },
+       "content": "trigger-label"
+      }
+     ],
+     "body": [
+      {
+       "component": "MenuItem",
+       "content": "edit-label"
+      },
+      {
+       "component": "MenuItem",
+       "content": "duplicate-label"
+      },
+      {
+       "component": "MenuSeparator"
+      },
+      {
+       "component": "MenuItem",
+       "props": {
+        "variant": "danger"
+       },
+       "content": "delete-label"
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "placement",
+     "ask": "Which side should the menu open on?",
+     "options": [
+      "bottom-start",
+      "bottom-end"
+     ],
+     "default": "bottom-end"
+    }
+   ],
+   "content": {
+    "trigger-label": "Actions",
+    "edit-label": "Edit",
+    "duplicate-label": "Duplicate",
+    "delete-label": "Delete"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Menu\n  aria-label=\"Actions\"\n  placement=\"bottom-end\"\n  trigger={<Button variant=\"ghost\">Actions</Button>}\n>\n  <MenuItem>Edit</MenuItem>\n  <MenuItem>Duplicate</MenuItem>\n  <MenuSeparator />\n  <MenuItem variant=\"danger\">Delete</MenuItem>\n</Menu>\n"
   },
   {
    "id": "settings-form-row",
@@ -2326,13 +2510,13 @@
    },
    "parameters": [],
    "content": {
-    "row-label": "<setting name>",
-    "control-label": "<what turning it on does>",
-    "row-description": "<one-line consequence of the setting>"
+    "row-label": "[setting name]",
+    "control-label": "[what turning it on does]",
+    "row-description": "[one-line consequence of the setting]"
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Field\n  description=\"<one-line consequence of the setting>\"\n  group={true}\n  label=\"<setting name>\"\n>\n  <Switch><what turning it on does></Switch>\n</Field>\n"
+   "preset": "<Field\n  description=\"[one-line consequence of the setting]\"\n  group={true}\n  label=\"[setting name]\"\n>\n  <Switch>[what turning it on does]</Switch>\n</Field>\n"
   }
  ],
  "scales": {
@@ -2534,6 +2718,64 @@
    },
    "tagApi": "On Tag, subtle is a boolean prop, not part of the variant union: accent-subtle is spelled variant=\"accent\" subtle (Tag variants: neutral | accent | success | warning | danger)."
   },
+  "geometry": {
+   "sizes": [
+    24,
+    32,
+    40,
+    48
+   ],
+   "label": {
+    "paddingInline": [
+     8,
+     12,
+     16,
+     20
+    ],
+    "paddingInlineIcon": [
+     6,
+     8,
+     12,
+     16
+    ],
+    "gap": [
+     4,
+     8,
+     8,
+     8
+    ],
+    "font": [
+     "12-16-medium",
+     "14-20-medium",
+     "16-24-medium",
+     "18-28-medium"
+    ]
+   },
+   "value": {
+    "paddingInline": [
+     8,
+     8,
+     12,
+     16
+    ],
+    "font": [
+     "12-16-regular",
+     "14-20-regular",
+     "16-24-regular",
+     "18-28-regular"
+    ]
+   },
+   "components": {
+    "Button": "label",
+    "IconButton": "height-only",
+    "Input": "value",
+    "Select": "value"
+   },
+   "note": "Per-size geometry is data, not CSS literals (D54). Arrays are indexed by sizes[]. Read a value as --psi-control-{size}-{prop} for the label ramp and --psi-control-value-{size}-{prop} for the value ramp; components alias these as --psi-{component}-{size}-{prop}, which is the layer to override. The value ramp is one step tighter than the label ramp because a left-aligned value wants less air than a centred label (D55).",
+   "iconInset": "A leading icon sits one step closer to the edge than text — an icon is a solid shape with no side bearing (D55). Applied by .size{n}:has(> svg:first-child) on Button. IconButton is height-only: it is square with padding 0, so no padding/gap/font token applies to it.",
+   "iconInsetLimits": "The selector matches on element order, and :first-child ignores text nodes. Two consequences. (1) An icon wrapped in a <span> never matches — fails safe, no inset; set --psi-button-{size}-padding-inline-icon yourself. (2) A TRAILING icon (<Button>Next<IconChevronRight /></Button>) makes the svg the first ELEMENT child, so the rule fires and narrows the start (text) side while the icon keeps full padding — the inverse of the intent. CSS cannot tell the two apart without a DOM signal. Put the icon first, or override --psi-button-{size}-padding-inline-icon to match --psi-button-{size}-padding-inline to disable the inset.",
+   "radius": "Control radius is size-invariant (D56) — it does NOT ride the size ramp, because border-radius sits on each component's base rule and all four sizes resolve to radius-8. One dial, --psi-control-radius, is the layer to override, aliased per component: --psi-button-radius (Button, and IconButton via the same token), --psi-input-radius, --psi-select-radius, --psi-checkbox-box-radius, and --psi-tooltip-radius. Checkbox and Tooltip cap themselves with min(var(--psi-control-radius), var(--psi-radius-4)) and min(…, var(--psi-radius-6)) respectively so neither over-rounds a small object — but the published radius scale's floor is radius-4, so Checkbox's cap is a no-op for every on-scale value a theme can set; it only bites at an off-scale value like 0px. Tooltip's higher ceiling does track a sharper theme, down to radius-4. Tag and Switch stay --psi-radius-full: pill-ness is component identity, not theme expression. A theme retunes every control's shape by setting --psi-control-radius once. Psi now has two radius dials, not one: --psi-control-radius (here, for interactive controls) and --psi-surface-radius (for elevated surfaces — Dialog, Panel, Menu). --psi-card-radius sits on neither dial, so a theme that retunes controls or surfaces leaves Card at its own default of radius-8."
+  },
   "getting-started": {
    "install": "npm install @handamade/psi-tokens @handamade/psi-react",
    "cssImports": [

package/dist/store.js

@@ -1,4 +1,26 @@
 const MAX_RESULTS = 20;
+/** Documented search-response budget: "serialized result <= 6000 characters
+ * (~1.5k tokens)" (docs/superpowers/plans/2026-07-18-agent-access-plan.md),
+ * asserted by __tests__/store.test.ts's "stays within the response budget". */
+const RESPONSE_BUDGET = 6000;
+/** Order the empty-query overview is filled in. Guidance first, catalog last,
+ * because the two grow and cost very differently:
+ *
+ *   topics   — a fixed, slow-growing set of terse briefs (~90 chars each).
+ *              Carries the rules an agent cannot guess, `getting-started`
+ *              (the five required CSS imports) above all.
+ *   patterns — a handful of composition recipes, moderately sized.
+ *   components — verbose (up to 220 chars each) and the only axis that grows
+ *              with every release. Also the axis a keyword query recovers
+ *              best: search("menu") finds Menu; no query re-derives a house
+ *              rule an agent doesn't know exists.
+ *
+ * Capping by item *count* (the previous scheme) evicted the tail, and since
+ * components were emitted first the tail was always topics — so registering
+ * D53's Menu components silently dropped eight topics including
+ * `getting-started`. Filling by serialized *length* in this order instead
+ * degrades only the component tail, which is the cheap thing to lose. */
+const OVERVIEW_KIND_ORDER = ["topic", "pattern", "component"];
 const TOPIC_SUMMARIES = {
     variants: "Variant intent and typical use for all 8 flat variants",
     rules: "House rules: accent budget, sizing, color binding",
@@ -79,8 +101,20 @@ export function createStore(index) {
     function search(query) {
         const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
         if (terms.length === 0) {
-            // Overview: all components, patterns, and topics (tokens are discoverable via query).
-            return briefs.filter((b) => b.kind !== "token").slice(0, MAX_RESULTS + 10);
+            // Overview: topics, then patterns, then as many components as the
+            // response budget still affords (tokens are discoverable via query).
+            // Filled by serialized length, not item count, so the thing that gets
+            // dropped is always the component tail — never the guidance surface.
+            const candidates = OVERVIEW_KIND_ORDER.flatMap((kind) => briefs.filter((b) => b.kind === kind));
+            const out = [];
+            for (const brief of candidates) {
+                out.push(brief);
+                if (JSON.stringify(out).length > RESPONSE_BUDGET) {
+                    out.pop();
+                    break;
+                }
+            }
+            return out;
         }
         return briefs
             .map((b) => ({ b, s: score(b, terms) }))

package/llms.txt

@@ -7,4 +7,4 @@ Ids: component:<Name>, token:<name>, topic:<key>, pattern:<id>; bare names resol
 
 Connect: https://psi.kurkin.de/mcp (Streamable HTTP) or `npx @handamade/psi-mcp` (stdio).
 Agent context: `npx @handamade/psi-mcp init [--claude]` writes a marker-delimited block into AGENTS.md/CLAUDE.md (D44).
-The index bakes packages/react/dist/{manifest.json,patterns.json} (patterns.json: 3 composition patterns with clarifying parameters, blocked/gaps flags, preset JSX) + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).
+The index bakes packages/react/dist/{manifest.json,patterns.json} (patterns.json: 4 composition patterns with clarifying parameters, blocked/gaps flags, preset JSX) + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.7.1",
+  "version": "0.8.0",
+  "license": "MIT",
   "description": "MCP server and agent-context generator for the Psi (Ψ) design system",
   "type": "module",
   "bin": {
@@ -32,8 +33,8 @@
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
-    "@handamade/psi-tokens": "0.7.1",
-    "@handamade/psi-react": "0.7.1"
+    "@handamade/psi-react": "0.8.0",
+    "@handamade/psi-tokens": "0.8.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"