@logicplanes/kaeso-ui 0.4.3 → 0.4.5

package/ai/component-registry.json

@@ -1,6 +1,6 @@
 {
   "package": "@logicplanes/kaeso-ui",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "components": [
     {
       "entry": "agent-avatar",
@@ -9,7 +9,7 @@
       "components": [
         {
           "name": "AgentAttribution",
-          "description": "A person's avatar with the agent that acted for them as a small badge on its corner, for audit rows and activity; it reads as one picture named after both. The badge stays inside the avatar's square, so a table cell never cuts it off.",
+          "description": "A person's avatar with the agent that acted for them as a small round ink badge on its corner, for audit rows and activity; it reads as one picture named after both, and a tooltip says the same to the pointer. The badge is about 40% of the avatar and a 2px gap cut out of the face separates it on any surface; it stays inside the avatar's square, so a table cell never cuts it off.",
           "props": [
             {
               "name": "agent",
@@ -37,7 +37,7 @@
               "type": "24 | 20 | 28 | 32 | 40",
               "required": false,
               "default": "24",
-              "description": "The diameter of the person's avatar in pixels; the agent badge is half of it."
+              "description": "The diameter of the person's avatar in pixels; the agent badge is about 40% of it (8 to 16px)."
             },
             {
               "name": "src",
@@ -51,7 +51,7 @@
         },
         {
           "name": "AgentAvatar",
-          "description": "An agent acting for a person: one bot face on an ink square, the same for every agent; write its model family beside it with useModelName where it matters.",
+          "description": "An agent acting for a person: one bot face on a `fill-3` square, the same for every agent (people are round, agents square); write its model family beside it with useModelName where it matters.",
           "props": [
             {
               "name": "name",
@@ -89,11 +89,11 @@
         "AGENT_ATTRIBUTION": {
           "axes": {
             "size": {
-              "20": "20px person, 10px agent badge",
-              "24": "24px person, 12px agent badge (default)",
-              "28": "28px person, 14px agent badge",
-              "32": "32px person, 16px agent badge",
-              "40": "40px person, 20px agent badge"
+              "20": "20px person, 8px agent badge",
+              "24": "24px person, 10px agent badge (default)",
+              "28": "28px person, 12px agent badge",
+              "32": "32px person, 12px agent badge",
+              "40": "40px person, 16px agent badge"
             }
           },
           "defaults": {
@@ -214,7 +214,7 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Slides the sheet in a little, to hint that it can be opened."
+              "description": "Shows the sheet as a preview that doesn't trap focus or dim the page, and closes when the pointer leaves it."
             },
             {
               "name": "returnFocus",
@@ -260,7 +260,7 @@
       "components": [
         {
           "name": "Avatar",
-          "description": "The first letters of the first and last word; `max` 1 keeps only the first.",
+          "description": "The first letters of the first and last word; `max` 1 keeps only the first. A photo gets a hairline so a light picture keeps its edge.",
           "props": [
             {
               "name": "name",
@@ -309,7 +309,7 @@
         },
         {
           "name": "AvatarGroup",
-          "description": "Overlapping avatars with a 2px panel ring and a \"+3\".",
+          "description": "Overlapping avatars, each separated from the one under it by a 2px gap cut out of that avatar, so the gap shows whatever surface the group sits on (a hovered row, a card); then a \"+3\".",
           "props": [
             {
               "name": "people",
@@ -337,7 +337,7 @@
               "type": "number",
               "required": false,
               "default": "4",
-              "description": "Show at most this many; the rest become \"+3\"."
+              "description": "Show at most this many; the rest become \"+3\", which names them in a tooltip."
             },
             {
               "name": "size",
@@ -379,7 +379,7 @@
       "components": [
         {
           "name": "Badge",
-          "description": "A small pill label: 22px, 12/500. Words carry meaning; color supports them.",
+          "description": "A small read-only pill label: 22px, 12/500, smaller than a Tag (24 or 28px) so a mark never looks like a control. Words carry meaning; color supports them. A label longer than its room ends in an ellipsis and shows in full in a tooltip. `ink` is for at most one badge on a view.",
           "props": [
             {
               "name": "children",
@@ -403,13 +403,13 @@
         "BADGE": {
           "axes": {
             "tone": {
-              "neutral": "Neutral (default)",
+              "neutral": "Neutral (default): fill-2, or the control fill on a hovered or selected row",
               "success": "Success",
               "warning": "Warning",
               "danger": "Danger",
               "info": "Information",
               "outline": "A ring only",
-              "ink": "Inverted, for the one thing that must stand out"
+              "ink": "Inverted: at most one on a view, for the one thing that must stand out"
             }
           },
           "defaults": {
@@ -425,7 +425,7 @@
       "components": [
         {
           "name": "Banner",
-          "description": "An inline notice: a tint, an icon, an optional title, the text, actions at the end. The banner is its own size container. From 480px inside its padding (the `banner` container size, `@banner:`) the actions sit on the right, centered on the title and text together, and the icon stays on the first line. Narrower (a phone) the actions go under the text, starting where the text starts: their 24px inset is the icon's 16px column and its 8px gap, which in the row is the gap before them.",
+          "description": "An inline notice: a tint, an icon (none for a neutral notice, so it never looks like information), an optional title, the text, actions at the end. Inline, the icon sits 12px in and the banner is at least 56px tall, so banners with and without actions stack evenly; full width, the icon sits on the 24px gutter and the text 24px further in. The banner is its own size container. From 480px inside its padding (the `banner` container size, `@banner:`) the actions sit on the right, centered on the title and text together, and the icon stays on the first line. Narrower (a phone) the actions go under the text, starting where the text starts: their 24px inset is the icon's 16px column and its 8px gap, which in the row is the gap before them.",
           "props": [
             {
               "name": "actions",
@@ -453,7 +453,7 @@
               "type": "IconSvgElement",
               "required": false,
               "default": null,
-              "description": "An icon in place of the tone's own."
+              "description": "An icon in place of the tone's own; a neutral banner has none unless you pass one."
             },
             {
               "name": "layout",
@@ -467,7 +467,7 @@
               "type": "(() => void)",
               "required": false,
               "default": null,
-              "description": "Only informational banners can be dismissed."
+              "description": "Shows a dismiss button on `neutral` and `info` banners. Success, warning and danger banners stay until their cause changes, so they ignore it and warn in development."
             },
             {
               "name": "title",
@@ -498,8 +498,8 @@
               "danger": "Something failed or will fail"
             },
             "layout": {
-              "inline": "Inside content: radius 14 (default)",
-              "full": "Across the top of the panel for global notices"
+              "inline": "Inside content: radius 14, its icon 12px in, at least 56px tall with or without actions (default)",
+              "full": "Across the top of the panel for global notices: its icon on the 24px gutter"
             }
           },
           "defaults": {
@@ -530,7 +530,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The button's label: a verb first, in sentence case."
+              "description": "The button's label: a verb first, in sentence case. A label wider than its container is cut with an ellipsis and shown whole in a tooltip."
             },
             {
               "name": "count",
@@ -551,7 +551,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Why the button is disabled, shown as a tooltip. The button stays focusable so people can read it."
+              "description": "Why the button is disabled, shown as a tooltip and read out as the button's description. The button stays focusable so people can reach it."
             },
             {
               "name": "fullWidth",
@@ -614,7 +614,7 @@
               "type": "\"md\" | \"xs\" | \"sm\" | \"lg\" | \"xl\"",
               "required": false,
               "default": null,
-              "description": "The height, from `xs` (24px) to `xl` (44px)."
+              "description": "The height, from `xs` (24px) to `xl` (48px)."
             },
             {
               "name": "target",
@@ -681,7 +681,7 @@
       "components": [
         {
           "name": "ButtonGroup",
-          "description": "Related actions side by side: connected pills, or spaced with `attached={false}`.",
+          "description": "Related actions side by side: connected pills, or spaced with `attached={false}`. An item with `pressed` is a toggle; pass `false` while it is off, and the selected item turns ink.",
           "props": [
             {
               "name": "children",
@@ -840,7 +840,7 @@
       "components": [
         {
           "name": "BarChart",
-          "description": "Bars for comparing values across categories: grouped, stacked, or horizontal for rankings. The category under the pointer, or reached with the arrow keys, shows its tooltip.",
+          "description": "Bars for comparing values across categories: grouped, stacked, or horizontal for rankings. The category under the pointer, or reached with the arrow keys, shows its tooltip; the legend pills show and hide series.",
           "props": [
             {
               "name": "aria-label",
@@ -861,7 +861,7 @@
               "type": "BarSeries[]",
               "required": true,
               "default": null,
-              "description": "The bars' series, each with an `id`, a `label`, one value per category and an optional `color`. Colors otherwise come from the series order by `id`."
+              "description": "The bars' series, each with an `id`, a `label`, one value per category and an optional `color`. Colors otherwise come from the series order by `id`; one series takes series 1. Negative values grow down from the zero line. With two or more, the legend shows and hides them."
             },
             {
               "name": "axisLabels",
@@ -889,7 +889,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows the empty state (`emptyText`) in place of the data. Pass it when the period has no data."
+              "description": "Shows the empty state (`emptyText`) in place of the data, over the baseline and the category axis. By default it shows when there is no value at all; zeros are data."
             },
             {
               "name": "emptyText",
@@ -903,14 +903,14 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails."
             },
             {
               "name": "formatValue",
               "type": "((v: number) => string)",
               "required": false,
-              "default": "(v) => formatNumber(v)",
-              "description": "Formats values on the axis and in the tooltip."
+              "default": null,
+              "description": "Formats values in the tooltip, the table and beside horizontal bars. Without it, values are written in full and the axis in short form (1.2M); the axis takes the room its widest label needs, and long category names in a ranking end in an ellipsis with the full name on hover."
             },
             {
               "name": "height",
@@ -938,7 +938,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The data is loading: the chart keeps its height and shows a quiet loading bar."
+              "description": "The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton."
             },
             {
               "name": "onRetry",
@@ -952,7 +952,7 @@
               "type": "{ first?: boolean; last?: boolean; ongoing?: boolean | undefined; } | undefined",
               "required": false,
               "default": null,
-              "description": "Marks the `first` or `last` category as covering only part of its span: its bars are drawn lighter and its tooltip says \"partial\". `ongoing` marks the last one as still counting, such as today, and says \"so far\"."
+              "description": "Marks the `first` or `last` category as covering only part of its span: its bars are drawn faint with a dashed edge, like a partial line, and its tooltip says \"partial\". `ongoing` marks the last one as still counting, such as today, and says \"so far\"."
             },
             {
               "name": "shares",
@@ -966,7 +966,7 @@
         },
         {
           "name": "ChartFrame",
-          "description": "The frame every chart draws in: a hidden data table for assistive technology, a \"View as table\" toggle, and the empty, loading and error states. The toggle sits at the right end of the last line of the legend; when the frame is narrower than 480px (the `chart-legend` container size, a phone), it moves to its own line under the legend, so it never reads as one of the series. Use it to build a chart of your own that behaves like the others.",
+          "description": "The frame every chart draws in: a hidden data table for assistive technology, a \"View as table\" toggle that shows the table at the chart's height, scrolling inside, and the empty, loading and error states. The toggle sits at the right end of the last line of the legend; when the frame is narrower than 480px (the `chart-legend` container size, a phone), it moves to its own line under the legend, so it never reads as one of the series. Use it to build a chart of your own that behaves like the others.",
           "props": [
             {
               "name": "children",
@@ -1113,7 +1113,7 @@
               "type": "Slice[]",
               "required": true,
               "default": null,
-              "description": "The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more."
+              "description": "The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more, and past the eighth slice the rest are grouped too, so no two slices share a color."
             },
             {
               "name": "className",
@@ -1127,7 +1127,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0."
+              "description": "Shows the empty state (`emptyText`) in place of the ring and legend. By default it shows when every value is 0, since a ring of nothing has no shares."
             },
             {
               "name": "emptyText",
@@ -1141,7 +1141,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails."
             },
             {
               "name": "formatValue",
@@ -1155,7 +1155,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The data is loading: the chart keeps its height and shows a quiet loading bar."
+              "description": "The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton."
             },
             {
               "name": "onRetry",
@@ -1176,7 +1176,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`."
+              "description": "Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. A long total steps down a size to fit the ring."
             },
             {
               "name": "totalLabel",
@@ -1190,7 +1190,7 @@
         },
         {
           "name": "Gauge",
-          "description": "A semicircle meter for one share of a limit, such as \"budget used\". It turns to warning at the first threshold and to danger at 100%.",
+          "description": "A semicircle meter for one share of a limit, such as \"budget used\". At the first threshold it says \"Near the limit\" and turns to warning; at 100% it says \"Over the limit\" and turns to danger.",
           "props": [
             {
               "name": "aria-label",
@@ -1204,7 +1204,7 @@
               "type": "number",
               "required": true,
               "default": null,
-              "description": "The share used, from 0 to 1. Values above 1 fill the arc and turn it to danger."
+              "description": "The share used, from 0 to 1. Values above 1 fill the arc and turn it to danger; a missing value (NaN) shows a dash and no arc."
             },
             {
               "name": "className",
@@ -1218,7 +1218,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "A caption under the value (\"of $500.00 budget\")."
+              "description": "A caption under the arc (\"of $500.00 budget\"); it wraps when long."
             },
             {
               "name": "thresholds",
@@ -1232,14 +1232,14 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Replaces the value in the center, which is otherwise the percentage."
+              "description": "Replaces the value in the center, which is otherwise the percentage. Pass a string so screen readers hear it with the unit."
             }
           ],
           "file": "src/components/charts/gauge.tsx"
         },
         {
           "name": "Heatmap",
-          "description": "A grid of cells shaded on a five-step ramp, for one value across two dimensions such as hour by weekday.",
+          "description": "A grid of cells shaded on a five-step ramp, for one value across two dimensions such as hour by weekday. One tab stop: the arrow keys move between cells and show each value, the table toggle lists them all, and a grid wider than its column scrolls with a fade at the edge.",
           "props": [
             {
               "name": "aria-label",
@@ -1260,7 +1260,7 @@
               "type": "string[]",
               "required": true,
               "default": null,
-              "description": "The row labels, top to bottom (weekdays)."
+              "description": "The row labels, top to bottom (weekdays). With no rows or columns the chart shows its empty state."
             },
             {
               "name": "values",
@@ -1288,7 +1288,7 @@
               "type": "((v: number) => string)",
               "required": false,
               "default": "(v) => formatNumber(v)",
-              "description": "Formats a cell's value for its tooltip and screen readers. Defaults to `formatNumber`."
+              "description": "Formats a cell's value for its tooltip, the table and screen readers. Defaults to `formatNumber`."
             }
           ],
           "file": "src/components/charts/heatmap.tsx"
@@ -1351,7 +1351,7 @@
               "type": "Slice[]",
               "required": true,
               "default": null,
-              "description": "The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more."
+              "description": "The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more, and past the eighth slice the rest are grouped too, so no two slices share a color."
             },
             {
               "name": "className",
@@ -1365,7 +1365,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0."
+              "description": "Shows the empty state (`emptyText`) in place of the ring and legend. By default it shows when every value is 0, since a ring of nothing has no shares."
             },
             {
               "name": "emptyText",
@@ -1379,7 +1379,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails."
             },
             {
               "name": "formatValue",
@@ -1393,7 +1393,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The data is loading: the chart keeps its height and shows a quiet loading bar."
+              "description": "The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton."
             },
             {
               "name": "onRetry",
@@ -1414,7 +1414,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`."
+              "description": "Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. A long total steps down a size to fit the ring."
             },
             {
               "name": "totalLabel",
@@ -1428,7 +1428,7 @@
         },
         {
           "name": "Sankey",
-          "description": "A flow diagram, such as requests from keys to models to providers, with ribbons as wide as each flow. Hovering a node highlights its paths.",
+          "description": "A flow diagram, such as requests from keys to models to providers, with ribbons as wide as each flow. Hovering a node, or reaching it with the arrow keys, highlights its paths. Each column keeps room for its labels; when narrow, the values go first, then long names end in an ellipsis.",
           "props": [
             {
               "name": "aria-label",
@@ -1463,7 +1463,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows the empty state (`emptyText`) in place of the data. Pass it when the period has no data."
+              "description": "Shows the empty state (`emptyText`) in place of the data. By default it shows when no link carries a value."
             },
             {
               "name": "emptyText",
@@ -1477,7 +1477,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails."
             },
             {
               "name": "formatValue",
@@ -1498,7 +1498,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The data is loading: the chart keeps its height and shows a quiet loading bar."
+              "description": "The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton."
             },
             {
               "name": "onRetry",
@@ -1540,7 +1540,7 @@
               "type": "((v: number) => string)",
               "required": false,
               "default": "(v) => formatNumber(v)",
-              "description": "Formats a segment's value in its tooltip. Defaults to `formatNumber`."
+              "description": "Formats each segment's value for screen readers, beside its share. Defaults to `formatNumber`."
             },
             {
               "name": "legend",
@@ -1568,7 +1568,7 @@
               "type": "number[]",
               "required": true,
               "default": null,
-              "description": "The values in order, oldest first."
+              "description": "The values in order, oldest first. One value is a dot at the newest end; none is a quiet flat line."
             },
             {
               "name": "className",
@@ -1610,7 +1610,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Draws the swatch as off, for a hidden series."
+              "description": "Draws the swatch as an outline in the series color, for a hidden series."
             },
             {
               "name": "shape",
@@ -1652,7 +1652,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0."
+              "description": "Shows the empty state (`emptyText`) in place of the data, over the baseline and the time axis. By default it shows when there are no points; zeros are data and draw a flat line on the baseline."
             },
             {
               "name": "emptyText",
@@ -1666,7 +1666,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails."
             },
             {
               "name": "formatTick",
@@ -1686,8 +1686,8 @@
               "name": "formatValue",
               "type": "((v: number) => string)",
               "required": false,
-              "default": "(v) => formatNumber(v)",
-              "description": "Formats values on the axis and in the tooltip."
+              "default": null,
+              "description": "Formats values in the tooltip, the table and on the axis. Without it, values are written in full and the axis in short form (1.2M), and the axis takes the room its widest label needs."
             },
             {
               "name": "height",
@@ -1722,7 +1722,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The data is loading: the chart keeps its height and shows a quiet loading bar."
+              "description": "The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton."
             },
             {
               "name": "onRetry",
@@ -1961,7 +1961,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows it as invalid; pair it with a message that says what to fix."
+              "description": "Shows it as invalid; inside a `Field` with `error`, it is invalid on its own and reads the message with it."
             },
             {
               "name": "label",
@@ -2094,7 +2094,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows it as invalid; pair it with a message that says what to fix."
+              "description": "Shows it as invalid; inside a `Field` with `error`, it is invalid on its own and reads the message with it."
             },
             {
               "name": "label",
@@ -2250,14 +2250,14 @@
               "type": "\"cell\" | \"text\" | \"box\"",
               "required": false,
               "default": "box",
-              "description": "`text` for long code in running text, so it breaks with the sentence instead of jumping to its own line as one box; `cell` for the same in a table cell."
+              "description": "`text` for long code in running text, so it breaks with the sentence instead of jumping to its own line as one box; `cell` for the same in a table cell. The default box wraps inside itself when it is wider than its line."
             },
             {
               "name": "shape",
               "type": "\"auto\" | \"pill\" | \"rounded\"",
               "required": false,
               "default": "auto",
-              "description": "A pill on one line, rounded corners when it wraps, or `auto` to choose by length."
+              "description": "`auto` (default) and `rounded` keep radius 6, so code in a sentence never mixes shapes; pass `pill` for one word standing alone, such as a model name in a table cell."
             }
           ],
           "file": "src/components/code/code.tsx"
@@ -2267,7 +2267,7 @@
         "CODE": {
           "axes": {
             "shape": {
-              "auto": "Pill for a single word, radius 6 for anything longer (default)",
+              "auto": "Radius 6, like every inline code in running text (default)",
               "pill": "Always a pill",
               "rounded": "Always radius 6"
             },
@@ -2291,7 +2291,7 @@
       "components": [
         {
           "name": "CodeBlock",
-          "description": "Highlighted code on a well: Kaeso's monochrome theme, copy on hover, tabs, line numbers, collapse. Long lines scroll sideways inside 16px of padding at both ends, and the code fades out at an edge with more to scroll to.",
+          "description": "Highlighted code on a well: Kaeso's monochrome theme, copy in the header with a title or tabs and on hover without, tabs, line numbers, collapse with a fade at the cut. Long lines scroll sideways inside 16px of padding at both ends, and the code fades out at an edge with more to scroll to.",
           "props": [
             {
               "name": "className",
@@ -2485,9 +2485,86 @@
           ],
           "file": "src/components/code-block/code-block.tsx"
         },
+        {
+          "name": "DiffView",
+          "description": "Two versions of a text side by side in one column: removed lines on red, added lines on green, the changed words inside them marked, syntax highlighted, and long unchanged runs folded away.",
+          "props": [
+            {
+              "name": "after",
+              "type": "string",
+              "required": true,
+              "default": null,
+              "description": "The new version."
+            },
+            {
+              "name": "before",
+              "type": "string",
+              "required": true,
+              "default": null,
+              "description": "The old version."
+            },
+            {
+              "name": "className",
+              "type": "string",
+              "required": false,
+              "default": null,
+              "description": "Classes for the layout of the outer element: margin, width and placement, never its look."
+            },
+            {
+              "name": "context",
+              "type": "number",
+              "required": false,
+              "default": "3",
+              "description": "Unchanged lines kept around each change before the rest folds (3 by default)."
+            },
+            {
+              "name": "copy",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Hide the copy circle, which copies the diff with + and - markers."
+            },
+            {
+              "name": "lang",
+              "type": "CodeLang",
+              "required": false,
+              "default": "text",
+              "description": "The language of both versions, for highlighting (`text` by default)."
+            },
+            {
+              "name": "lineNumbers",
+              "type": "boolean",
+              "required": false,
+              "default": null,
+              "description": "Shows the old and the new line numbers."
+            },
+            {
+              "name": "surface",
+              "type": "\"well\" | \"plain\"",
+              "required": false,
+              "default": "well",
+              "description": "On a filled well (`well`) or on the panel itself (`plain`)."
+            },
+            {
+              "name": "title",
+              "type": "ReactNode",
+              "required": false,
+              "default": null,
+              "description": "A name in the title bar, beside the count of added and removed lines."
+            },
+            {
+              "name": "wrap",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Long lines wrap instead of scrolling sideways, keeping their indent: values in a narrow column such as a sheet."
+            }
+          ],
+          "file": "src/components/code-block/diff-view.tsx"
+        },
         {
           "name": "JsonView",
-          "description": "A folding JSON tree: copy any path, highlight a search. For request and response bodies.",
+          "description": "A folding JSON tree: copy any path, highlight a search. For request and response bodies. It is one tab stop: the arrow keys move between rows and open and close them, and ⌘C or Ctrl C copies the row's path.",
           "props": [
             {
               "name": "value",
@@ -2540,6 +2617,17 @@
             "surface": "well"
           }
         },
+        "DIFF_VIEW": {
+          "axes": {
+            "surface": {
+              "well": "A well: radius 14, fill, no ring (default)",
+              "plain": "No surface, inside another well"
+            }
+          },
+          "defaults": {
+            "surface": "well"
+          }
+        },
         "JSON_VIEW": {
           "axes": {
             "surface": {
@@ -2560,7 +2648,7 @@
       "components": [
         {
           "name": "Accordion",
-          "description": "Collapsible rows separated by hairlines.",
+          "description": "Collapsible rows separated by hairlines, each the same pill row as Collapsible.",
           "props": [
             {
               "name": "items",
@@ -2595,7 +2683,7 @@
         },
         {
           "name": "Collapsible",
-          "description": "A disclosure row: a chevron that rotates in 180ms, a measured height animation.",
+          "description": "A disclosure row: a pill with the title 12px in and a chevron at its end that turns in 200ms, the content on the title's line, a measured height animation.",
           "props": [
             {
               "name": "children",
@@ -2654,8 +2742,8 @@
         "COLLAPSIBLE": {
           "axes": {
             "state": {
-              "closed": "Closed: the chevron points to the row (default)",
-              "open": "Open: the chevron turns down and the content shows"
+              "closed": "Closed: a pill row with the title 12px in and a chevron at its end pointing right (default)",
+              "open": "Open: the chevron turns down in 200ms and the content shows under the title"
             }
           },
           "defaults": {
@@ -2874,7 +2962,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "What the empty list says: \"No models match\". Defaults to \"No results\" in the provider's language."
+              "description": "What the empty list says: \"No models match\". Defaults to \"No matches for\" and the typed text, in the provider's language."
             },
             {
               "name": "error",
@@ -2916,7 +3004,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows a quiet progress line at the top of the list (async results)."
+              "description": "Shows a quiet progress line at the top of the list (async results) once loading takes 300ms; with reduced motion, only the words."
             },
             {
               "name": "multiple",
@@ -3070,7 +3158,7 @@
               "type": "CommandListGroup[]",
               "required": true,
               "default": null,
-              "description": "The rows, in groups; a group with a label gets a sticky caption with its mark and count, and a loading group keeps its caption while it has no rows yet."
+              "description": "The rows, in groups; a group with a label gets a sticky caption with its mark and count, and a loading group keeps its caption, without a count, over a Loading… row while it has no rows yet."
             },
             {
               "name": "autoFocus",
@@ -3112,7 +3200,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "What the list says when nothing matches: \"No models match\"."
+              "description": "What the list says when nothing matches: \"No models match\". Defaults to \"No results for “claude”\", naming the query, in the provider's language."
             },
             {
               "name": "escapeClears",
@@ -3147,7 +3235,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows a quiet progress line at the top while more rows load."
+              "description": "Shows a quiet progress line at the top while more rows load; with reduced motion it breathes instead of moving."
             },
             {
               "name": "match",
@@ -3395,7 +3483,7 @@
       "components": [
         {
           "name": "CommandPalette",
-          "description": "⌘K: search every page and action; nested pages; async groups with a quiet progress line.",
+          "description": "⌘K: search every page and action; nested pages with a chip that goes back; async groups with a quiet progress line. Escape closes; on a nested page it clears the search, then goes back a page. ⌘K does nothing while another dialog is open.",
           "props": [
             {
               "name": "groups",
@@ -3423,7 +3511,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Defaults to \"No results\" in the provider's language."
+              "description": "Defaults to \"No results for “claude”\" (naming the query) in the provider's language."
             },
             {
               "name": "hotkey",
@@ -3678,7 +3766,7 @@
       "components": [
         {
           "name": "DataTable",
-          "description": "A table for many rows: sorting, selection, loading and empty states, more rows on demand, and virtual scrolling for long lists.",
+          "description": "A table for many rows: sorting, selection, loading and empty states, more rows on demand, and virtual scrolling for long lists. One tab stop: the arrows move between rows and header buttons, Right reaches a row's controls, Shift with Left or Right resizes a column from its header, and a header's context menu widens, narrows or resets it.",
           "props": [
             {
               "name": "aria-label",
@@ -3706,7 +3794,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "The id of a row to show as active (open in a sheet)."
+              "description": "The id of the row whose detail is open, in a sheet beside the table: it keeps the selected fill and is marked aria-current."
             },
             {
               "name": "canSelectRow",
@@ -3722,6 +3810,13 @@
               "default": null,
               "description": "Classes for the layout of the outer element: margin, width and placement, never its look."
             },
+            {
+              "name": "data-force-row",
+              "type": "string",
+              "required": false,
+              "default": null,
+              "description": "Force a state on the first row for state matrices: hover, pressed, focus."
+            },
             {
               "name": "density",
               "type": "\"default\" | \"compact\" | \"comfortable\"",
@@ -3734,14 +3829,14 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "What to show when there are no rows, usually an `Empty`."
+              "description": "What to show when there are no rows: an `Empty` with the page's own sentence, such as \"No requests yet\" or, behind filters, \"No requests match\". Without it the table says \"No rows\"."
             },
             {
               "name": "error",
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The rows failed to load: the table says so where its rows would be and offers Try again (`onRetry`). Errors are toasts, so the value isn't shown; toast the message where the request fails."
+              "description": "The rows failed to load: the table says so where its rows would be and offers Try again (`onRetry`), or, without it, says to reload the page. Errors are toasts, so the value isn't shown; toast the message where the request fails."
             },
             {
               "name": "freshRowIds",
@@ -3846,7 +3941,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Adds a checkbox to every row."
+              "description": "Adds a checkbox to every row, named after the row's first text column; Space, Shift with the arrows and ⌘A select from the keyboard."
             },
             {
               "name": "selection",
@@ -3884,8 +3979,8 @@
         "DATA_TABLE": {
           "axes": {
             "density": {
-              "compact": "36px rows",
-              "default": "40px rows (default)",
+              "compact": "36px rows; 44px with a coarse pointer",
+              "default": "40px rows (default); 44px with a coarse pointer",
               "comfortable": "48px rows"
             }
           },
@@ -4007,7 +4102,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Shown without a date. Defaults to \"Pick a date\" (\"Pick a range\" for a range) in the provider's language."
+              "description": "Shown without a date. Defaults to \"Choose a date\" (\"Choose a date range\" for a range) in the provider's language."
             },
             {
               "name": "required",
@@ -4147,7 +4242,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Shown without a date. Defaults to \"Pick a date\" (\"Pick a range\" for a range) in the provider's language."
+              "description": "Shown without a date. Defaults to \"Choose a date\" (\"Choose a date range\" for a range) in the provider's language."
             },
             {
               "name": "preset",
@@ -4349,7 +4444,7 @@
       "components": [
         {
           "name": "DeleteResource",
-          "description": "Confirms deleting a resource: names the object and the consequence, asks for its name typed, and ends with a danger button.",
+          "description": "Confirms deleting a resource for good: the title names it, the body says the consequence, the person types its name, and a danger button names the action. A reversible action needs no confirmation: act at once and offer Undo in a toast.",
           "props": [
             {
               "name": "consequence",
@@ -4363,14 +4458,14 @@
               "type": "string",
               "required": true,
               "default": null,
-              "description": "\"project\", \"key\", \"organization\""
+              "description": "The kind of resource in the provider's language, as it reads after the verb on the button: \"project\", \"key\"; in German \"Projekt\"."
             },
             {
               "name": "name",
               "type": "string",
               "required": true,
               "default": null,
-              "description": "The resource's name; typed to confirm."
+              "description": "The resource's name: the title names it, and the person types it to confirm."
             },
             {
               "name": "onConfirm",
@@ -4419,7 +4514,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "\"Delete\", \"Archive\". Defaults to \"Delete\" in the provider's language."
+              "description": "The action in the provider's language, in the form it takes on the button and in the title: \"Archive\" (\"Archive project\", \"Archive “Checkout”?\"); in German the infinitive, \"archivieren\" (\"Projekt archivieren\"). Defaults to \"Delete\" in the provider's language."
             }
           ],
           "file": "src/blocks/delete-resource/delete-resource.tsx"
@@ -4429,8 +4524,8 @@
         "DELETE_RESOURCE": {
           "axes": {
             "confirm": {
-              "typed": "The person types the resource's name (default)",
-              "simple": "A confirm button only, for reversible archives"
+              "typed": "The person types the resource's name, for one that holds a lot: a project, an organization (default)",
+              "simple": "A confirm button only, for a resource that holds little: a key, an alias"
             }
           },
           "defaults": {
@@ -4474,7 +4569,7 @@
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "Names the action: \"Delete this key?\""
+              "description": "Names the action and the object: \"Delete “checkout-web”?\""
             },
             {
               "name": "cancelLabel",
@@ -4530,7 +4625,7 @@
               "type": "\"warning\" | \"danger\" | \"info\"",
               "required": false,
               "default": null,
-              "description": "How serious the confirmation is; `danger` for actions that can't be undone."
+              "description": "How serious the confirmation is: `danger` for an action that can't be undone (a danger confirm, the focus on Cancel), `warning` for a risky one that can (a primary confirm, the focus still on Cancel), `info` for a neutral one (the focus on the confirm)."
             },
             {
               "name": "trigger",
@@ -4551,13 +4646,13 @@
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "The dialog's heading, also its accessible name."
+              "description": "The dialog's heading, also its accessible name; a long one, or an id, wraps."
             },
             {
               "name": "anchor",
               "type": "\"center\" | \"top\"",
               "required": false,
-              "default": null,
+              "default": "top",
               "description": "Where it sits: centered, or with a fixed top edge for content that changes height, so the title never moves."
             },
             {
@@ -4656,7 +4751,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "A press outside doesn't close it, for forms that would lose what was typed; Escape and the close circle still do. Every StepDialog is persistent."
+              "description": "A press outside doesn't close it or move the focus, for forms that would lose what was typed; Escape and the close circle still close it. Every StepDialog is persistent."
             },
             {
               "name": "size",
@@ -4705,7 +4800,7 @@
         },
         {
           "name": "LayerDialog",
-          "description": "A stacked dialog: a second layer slides over the first (add model → review values); back returns. The layers below stay as they were. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. Enter in a single-line field and ⌘/Ctrl+Enter call onSubmit on every layer.",
+          "description": "A stacked dialog: a second layer slides over the first (add model → review values); Back returns, and Escape closes the dialog from any layer. The layers below stay as they were. The close circle sits in a bar above the title, with Back at its start from the second layer, so the title keeps its place on every layer. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. Enter in a single-line field and ⌘/Ctrl+Enter call onSubmit on every layer.",
           "props": [
             {
               "name": "layers",
@@ -4718,8 +4813,8 @@
               "name": "anchor",
               "type": "\"center\" | \"top\"",
               "required": false,
-              "default": null,
-              "description": "Where it sits: centered, or with a fixed top edge for layers of different heights."
+              "default": "top",
+              "description": "Where it sits: with a fixed top edge (default), so the title stays put on layers of different heights, or centered."
             },
             {
               "name": "busy",
@@ -4831,7 +4926,7 @@
               "type": "DialogStep[]",
               "required": true,
               "default": null,
-              "description": "The steps, each with its title, content and whether it can be continued; `onContinue` checks a step before the next opens, such as asking a server, and `continueLabel` names that check: \"Detect settings\"."
+              "description": "The steps, each with its title, content and whether it can be continued: with `blockedReason`, Continue waits, and Enter shows and announces the reason under the step; `onContinue` checks a step before the next opens, such as asking a server, and `continueLabel` names that check: \"Detect settings\"."
             },
             {
               "name": "submitLabel",
@@ -4911,9 +5006,9 @@
         "ALERT_DIALOG": {
           "axes": {
             "tone": {
-              "danger": "Destructive (default)",
-              "warning": "Risky but reversible",
-              "info": "Neutral confirmation"
+              "danger": "Destructive: a danger confirm, with the focus on Cancel (default)",
+              "warning": "Risky but reversible: a primary confirm, with the focus on Cancel",
+              "info": "A neutral confirmation: a primary confirm, with the focus on it"
             }
           },
           "defaults": {
@@ -4955,7 +5050,7 @@
           },
           "defaults": {
             "size": "md",
-            "anchor": "center"
+            "anchor": "top"
           }
         },
         "STEP_DIALOG": {
@@ -5060,7 +5155,7 @@
       "components": [
         {
           "name": "Empty",
-          "description": "An empty state: a title, one sentence, one or two actions. No icon, no illustration.",
+          "description": "An empty state: a title, one sentence, one action. No icon, no illustration. The `lg` title is a heading (h2) for a page that is empty; `md` and `compact` titles are text, so an empty table, list or section adds no heading to the page's outline.",
           "props": [
             {
               "name": "title",
@@ -5074,7 +5169,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "One primary and at most one secondary action."
+              "description": "The one action that makes something appear; put a link to read more in the description."
             },
             {
               "name": "children",
@@ -5102,7 +5197,7 @@
               "type": "\"md\" | \"lg\" | \"compact\"",
               "required": false,
               "default": "lg",
-              "description": "How much room it takes: a whole page (`lg`), a section (`md`) or a row (`compact`)."
+              "description": "How much room it takes: a whole page (`lg`, with a heading), a section (`md`) or a row (`compact`)."
             }
           ],
           "file": "src/components/empty/empty.tsx"
@@ -5144,7 +5239,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "The error message, shown under the control in the danger color: it marks the field invalid and is read out with the description."
+              "description": "The error message, shown under the control in the danger color: it marks the field invalid and is read out with the description. After a failed submit, move focus to the first invalid field so its error is heard."
             },
             {
               "name": "id",
@@ -5179,21 +5274,21 @@
         },
         {
           "name": "Fieldset",
-          "description": "A group of fields under one legend.",
+          "description": "A group of fields under one legend, which names the group for screen readers.",
           "props": [
             {
               "name": "legend",
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "The heading of the group of fields."
+              "description": "The heading of the group of fields, read out as the group's name."
             },
             {
               "name": "description",
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "One sentence of help under the heading."
+              "description": "One sentence of help under the heading; it also describes the group."
             }
           ],
           "file": "src/components/field/field.tsx"
@@ -5234,7 +5329,7 @@
               "type": "string",
               "required": true,
               "default": null,
-              "description": "The name of the figure's scrolling region, read by screen readers."
+              "description": "The name of the figure's scrolling region, read by screen readers; give each figure on a page its own."
             },
             {
               "name": "caption",
@@ -5441,7 +5536,7 @@
       "components": [
         {
           "name": "FilterRow",
-          "description": "The row between a page's header and its list or table: pill tabs at the start, filters at the end. It grows with its content instead of keeping a toolbar's 48px, and on a narrow screen the filters wrap under the tabs, at the start. The tabs keep their own arrow keys; Left and Right move across the filters only, which form their own toolbar.",
+          "description": "The row between a page's header and its list or table: pill tabs at the start, filters at the end. It grows with its content instead of keeping a toolbar's 48px, and on a narrow screen the filters wrap under the tabs, at the start. The tabs keep their own arrow keys; Left and Right move from filter to filter, which form their own toolbar.",
           "props": [
             {
               "name": "children",
@@ -5496,7 +5591,7 @@
       "components": [
         {
           "name": "Flow",
-          "description": "A node-and-connector diagram: the route \"app → Kaeso → provider / model\".",
+          "description": "A node-and-connector diagram: the route \"app → Kaeso → provider / model\". A diagram wider than its column scrolls sideways with a fade at the edge and takes focus.",
           "props": [
             {
               "name": "columns",
@@ -5517,7 +5612,7 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "Dots that travel along the connectors. Off by default; never on loaded pages that need calm."
+              "description": "When the route changes, a dot runs once along each connector, to show where requests now go. Never on first render and never with reduced motion."
             },
             {
               "name": "aria-label",
@@ -5548,7 +5643,7 @@
         "FLOW": {
           "axes": {
             "node": {
-              "pill": "A raised pill (default)",
+              "pill": "A pill with a hairline (default)",
               "box": "A rounded-14 box with a description line"
             }
           },
@@ -5944,7 +6039,7 @@
         },
         {
           "name": "NumberInput",
-          "description": "Numbers that stay exact: right-aligned tabular digits, a unit, stepper circles on hover, thousands separators on blur, and a decimal string value.",
+          "description": "Numbers that stay exact: end-aligned tabular digits, a unit, quiet stepper circles, thousands separators on blur, and a decimal string value.",
           "props": [
             {
               "name": "align",
@@ -5993,7 +6088,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Hide the stepper circles."
+              "description": "Hide the stepper circles, where a value is typed rather than nudged, such as an id or a year."
             },
             {
               "name": "integer",
@@ -6638,8 +6733,8 @@
         "NUMBER_INPUT": {
           "axes": {
             "align": {
-              "end": "Right-aligned tabular digits (default)",
-              "start": "Left-aligned"
+              "end": "End-aligned tabular digits (default)",
+              "start": "Start-aligned"
             }
           },
           "defaults": {
@@ -6649,7 +6744,7 @@
         "OTP_INPUT": {
           "axes": {
             "size": {
-              "md": "48px cells (default)",
+              "md": "48px cells (default); they shrink, square, when the row is narrower",
               "sm": "40px cells"
             }
           },
@@ -6732,7 +6827,7 @@
         },
         {
           "name": "ClientButton",
-          "description": "An agent client's mark, such as Claude, Cursor or GitHub Copilot, on a raised tile, as a button that opens how to connect it.",
+          "description": "An agent client's mark, such as Claude, Cursor or GitHub Copilot, in a raised circle beside the other header buttons, as a button that opens how to connect it.",
           "props": [
             {
               "name": "aria-label",
@@ -6755,6 +6850,13 @@
               "default": null,
               "description": "Classes for the layout of the outer element: margin, width and placement, never its look."
             },
+            {
+              "name": "data-force",
+              "type": "string",
+              "required": false,
+              "default": null,
+              "description": "Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`."
+            },
             {
               "name": "onClick",
               "type": "(() => void)",
@@ -6809,7 +6911,7 @@
         },
         {
           "name": "EffectiveAccess",
-          "description": "What someone can do, at a glance: a row per group with the granted rights in words (\"Every right\", \"None\", or their names) and how many of the group's rights that is, under the roles it comes from. The detail, with a source per right, is RightsMatrix in read-only mode.",
+          "description": "What someone can do, at a glance: a row per group with the granted rights in words (\"Every right\", \"None\", or their names) and how many of the group's rights that is, under the roles it comes from; groups with nothing granted share one \"No rights\" row. A role chip with more to say has a dotted underline and says it in a tooltip. The detail, with a source per right, is RightsMatrix in read-only mode.",
           "props": [
             {
               "name": "groups",
@@ -6886,7 +6988,7 @@
         },
         {
           "name": "GrantSummary",
-          "description": "What an agent or a key may do, one short line each after a check mark, on a group surface.",
+          "description": "What an agent or a key may do, one short line each after a check mark, on a group surface with 20px inside, like a settings group.",
           "props": [
             {
               "name": "aria-label",
@@ -6907,7 +7009,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "A small button after the note, such as Customize."
+              "description": "A small button after the note (or alone, at the end), such as Customize."
             },
             {
               "name": "className",
@@ -6921,14 +7023,14 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "A quiet note under the lines, such as how long it lasts."
+              "description": "A note under the lines in secondary text, such as how long it lasts."
             }
           ],
           "file": "src/components/kaeso/grant-summary.tsx"
         },
         {
           "name": "KeyDisplay",
-          "description": "A redacted key: mono 13 with its state dot, copy of the redacted form, and its access.",
+          "description": "A redacted key: mono 13, a word badge for any state but active, a copy of the redacted form, and its access in an outline badge.",
           "props": [
             {
               "name": "redacted",
@@ -6977,7 +7079,7 @@
         },
         {
           "name": "LimitMeter",
-          "description": "A limit: its kind, scope and window, hard or soft, the meter with alert ticks, and when it resets.",
+          "description": "A limit: its kind, scope and window, hard or soft, the meter with alert ticks, and when it resets. Over the limit it says so, and what happens to requests.",
           "props": [
             {
               "name": "kind",
@@ -6998,7 +7100,7 @@
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "\"Project\", \"Key ci-runner\", \"Member Ada\"."
+              "description": "\"Project\", \"Key ci-runner\", \"Member Ada\". A text scope also names the meter for screen readers, and shows whole on hover when it doesn't fit."
             },
             {
               "name": "used",
@@ -7391,7 +7493,7 @@
         },
         {
           "name": "RightsMatrix",
-          "description": "Rights by group, for a role, a member or a key. Edit mode: a checkbox per right and per group (mixed when some are granted), requirements kept (granting \"edit\" grants \"view\"; withdrawing \"view\" withdraws \"edit\"), each right's needs said under it, and arrow keys moving between checkboxes. Read-only mode: a mark per right and the roles that grant it. Rows keep their size whatever their state. Fits a sheet and a phone.",
+          "description": "Rights by group, for a role, a member or a key. Edit mode: a checkbox per right and per group (checked only when every right in it is granted, mixed when some are), requirements kept (granting \"edit\" grants \"view\"; withdrawing \"view\" withdraws \"edit\"), each right's needs said under it, and a right that can't change saying why under it. The matrix is one tab stop: the arrow keys move between checkboxes, and the right arrow reaches a right's sensitive mark. A group's name toggles the group, as a right's row toggles the right. Read-only mode: a mark per right and the roles that grant it. Rows keep their size whatever their state. Fits a sheet and a phone.",
           "props": [
             {
               "name": "groups",
@@ -7454,7 +7556,7 @@
         },
         {
           "name": "RolePicker",
-          "description": "Choosing a role: built-in roles first, then custom ones under their own caption, each with its one-sentence description. A role the person can't give stays in the list, disabled, with the reason under it and in its tooltip, so nobody wonders where it went.",
+          "description": "Choosing a role: built-in roles first, then custom ones under their own caption, each with its one-sentence description. A role the person can't give stays in the list, disabled, with the reason under it, so nobody wonders where it went.",
           "props": [
             {
               "name": "roles",
@@ -7538,14 +7640,14 @@
         },
         {
           "name": "SecretReveal",
-          "description": "The one-time secret: calm, centered, certain. The secret on a well (selected on click), a large \"Copy key\" that becomes \"Copied\" without changing size, a plain warning, and snippets that use it.",
+          "description": "The one-time secret: calm, centered, certain. The secret on a well (selected on click), a plain warning, a large \"Copy key\" that becomes \"Key copied\" without changing size, and a `.env` tab with the gateway's URL and the key beside SDK snippets that read the key from the environment.",
           "props": [
             {
               "name": "baseUrl",
               "type": "string",
               "required": true,
               "default": null,
-              "description": "The gateway's address, for the code snippet that uses the key."
+              "description": "The gateway's address, for the `.env` tab and the code snippets."
             },
             {
               "name": "secret",
@@ -7629,7 +7731,7 @@
         },
         {
           "name": "UsageBreakdown",
-          "description": "A stacked bar of token kinds with the numbers under it, in the fixed series mapping.",
+          "description": "A stacked bar of token kinds with the numbers under it, in the fixed series mapping; cache read is a soft blue edged in input's blue. Each rounded count shows the exact one on hover and focus.",
           "props": [
             {
               "name": "tokens",
@@ -7833,7 +7935,7 @@
       "components": [
         {
           "name": "KeyValue",
-          "description": "Label and value pairs (13 secondary label, 14 value), copyable values. Side by side for sheets; label above value in columns (`grid`) where a sheet is wide enough for two or more to a row. A text value that doesn't fit ends in an ellipsis and shows whole in a tooltip.",
+          "description": "Label and value pairs (13 secondary label, 14 value), copyable values. Side by side for sheets; label above value in columns (`grid`) where a sheet is wide enough for two or more to a row. A value or grid label that doesn't fit ends in an ellipsis, takes focus and shows whole in a tooltip. Side by side, the label column grows to its longest label up to 240px, and longer labels wrap. Ids and keys (`mono`) are 13px, like ids everywhere in the library.",
           "props": [
             {
               "name": "items",
@@ -7895,7 +7997,7 @@
       "components": [
         {
           "name": "Label",
-          "description": "The label of a form control.",
+          "description": "The label of a form control. Pass `data-disabled` beside a disabled control and it dims with it.",
           "props": [
             {
               "name": "children",
@@ -7968,7 +8070,7 @@
             },
             {
               "name": "gap",
-              "type": "0 | 2 | 24 | 20 | 32 | 40 | 4 | 6 | 8 | 12 | 16 | 48 | 64",
+              "type": "0 | 2 | 24 | 8 | 12 | 16 | 20 | 32 | 40 | 4 | 6 | 48 | 64",
               "required": false,
               "default": "16",
               "description": "The space between items, in pixels on the spacing scale."
@@ -7996,7 +8098,7 @@
             },
             {
               "name": "gap",
-              "type": "0 | 2 | 24 | 20 | 32 | 40 | 4 | 6 | 8 | 12 | 16 | 48 | 64",
+              "type": "0 | 2 | 24 | 8 | 12 | 16 | 20 | 32 | 40 | 4 | 6 | 48 | 64",
               "required": false,
               "default": "16",
               "description": "The space between items, in pixels on the spacing scale."
@@ -8038,7 +8140,7 @@
             },
             {
               "name": "gap",
-              "type": "0 | 2 | 24 | 20 | 32 | 40 | 4 | 6 | 8 | 12 | 16 | 48 | 64",
+              "type": "0 | 2 | 24 | 8 | 12 | 16 | 20 | 32 | 40 | 4 | 6 | 48 | 64",
               "required": false,
               "default": "16",
               "description": "The space between items, in pixels on the spacing scale."
@@ -8075,7 +8177,7 @@
               "2": "Two columns from 768px",
               "3": "Three columns from 768px",
               "4": "Two, then four from 1024px",
-              "6": "Three, then six from 1024px"
+              "6": "Two, three from 768px, six from 1024px"
             }
           },
           "defaults": {
@@ -8131,7 +8233,7 @@
         "LINK": {
           "axes": {
             "variant": {
-              "inline": "Inside prose: text color with a quiet underline that turns solid on hover",
+              "inline": "Inside prose: text color with a grey underline that turns to the text color on hover",
               "quiet": "Navigation-style links in footers and metadata; no underline until hover",
               "standalone": "A link on its own line (“Team overview ›”)",
               "heading": "A heading's link to itself: the heading's own look, with a # beside it on hover and keyboard focus",
@@ -8151,7 +8253,7 @@
       "components": [
         {
           "name": "GroupHeader",
-          "description": "A quiet caption row above its group: title, count and a disclosure chevron, set in from the edges like the rows. No band: space separates the groups, and the + circle appears with hover or focus.",
+          "description": "A quiet caption row above its group: title, count and a disclosure chevron, set in from the edges like the rows. On the panel there is no band: 16px of space separates the groups. In a card the header is a `fill-1` band with a hairline, the card's way of separating groups. The + circle appears with hover or focus.",
           "props": [
             {
               "name": "title",
@@ -8193,7 +8295,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "The list's first row (no hairline above it in a card)."
+              "description": "The list's first row: no space above it on the panel, no hairline above it in a card."
             },
             {
               "name": "glyph",
@@ -8207,7 +8309,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "In a selectable list, line the title up with the row titles after the checkbox column."
+              "description": "In a selectable list, line the title up with the row titles after the checkbox column; the hover fill still starts on the gutter."
             },
             {
               "name": "index",
@@ -8242,7 +8344,7 @@
         },
         {
           "name": "List",
-          "description": "The console list: 44px rows on the panel, no lines, metadata on the right, keyboard-first. An ARIA grid of one-cell rows with one tab stop: arrows move between rows, Space selects, Enter opens, and the right arrow reaches a row's actions.",
+          "description": "The console list: 44px rows on the panel (48px in a card, 56px with a second line), no lines, metadata on the right, keyboard-first. An ARIA grid of one-cell rows with one tab stop: arrows move between rows, Space selects, Enter opens, the right arrow reaches a row's actions and Escape comes back. A row's text can be selected and copied; a click that selects text doesn't open the row.",
           "props": [
             {
               "name": "aria-label",
@@ -8263,7 +8365,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Force a state on the first row for state matrices: hover, focus, selected."
+              "description": "Force a state on the first row for state matrices: hover, pressed, focus."
             },
             {
               "name": "density",
@@ -8305,7 +8407,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Loading rows shaped like items, while the rows aren't known yet."
+              "description": "Loading rows shaped like items, under a group header's shape when the list has groups, while the rows aren't known yet."
             },
             {
               "name": "onOpen",
@@ -8347,7 +8449,7 @@
               "type": "boolean",
               "required": false,
               "default": "true",
-              "description": "The floating selection bar; off where the host shows the count itself, as in a dialog."
+              "description": "The floating selection bar; off where the host shows the count itself, as in a dialog. Rows reached with the arrow keys scroll clear of it."
             },
             {
               "name": "virtualizeAbove",
@@ -8431,7 +8533,7 @@
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "The list is narrow (a phone): the title, the subtitle and the metadata with the date are lines of their own."
+              "description": "The list is narrow (a phone): the title and the subtitle are lines of their own, and the metadata, the date, the avatar and the actions share one line under them, so titles keep the row's width."
             },
             {
               "name": "onFocus",
@@ -8554,7 +8656,7 @@
           "axes": {
             "density": {
               "default": "44px rows (default)",
-              "compact": "36px rows"
+              "compact": "36px rows; 44px with a coarse pointer"
             }
           },
           "defaults": {
@@ -8570,14 +8672,14 @@
       "components": [
         {
           "name": "Loader",
-          "description": "A status region with the spinner and a label: \"Saving provider…\", or a page or region that is loading. Its place is kept while it waits out `delay`, so nothing moves when it shows.",
+          "description": "A status region with the spinner and a label: \"Saving provider…\", or a page or region that is loading. Its place is kept while it waits out `delay`, so nothing moves when it shows; the status region is there, empty, from the start, and its words arrive when the spinner shows, so screen readers announce them.",
           "props": [
             {
               "name": "delay",
               "type": "number | boolean",
               "required": false,
               "default": null,
-              "description": "Waits before the spinner and its label show, so quick work shows nothing: `true` for the library's 300ms (`useDelayedLoading`), or milliseconds. None by default."
+              "description": "Waits before the spinner and its label show, so quick work shows nothing: the library's 300ms by default (`useDelayedLoading`), a number of milliseconds, or `false` to show at once."
             },
             {
               "name": "hideLabel",
@@ -8605,7 +8707,7 @@
               "type": "number",
               "required": false,
               "default": null,
-              "description": "Once shown, they stay at least this many milliseconds: 400 with a delay, 0 without."
+              "description": "Once shown, they stay at least this many milliseconds: 400 by default, 0 with `delay={false}`."
             },
             {
               "name": "size",
@@ -8746,7 +8848,7 @@
       "components": [
         {
           "name": "Markdown",
-          "description": "Markdown, safely: headings, paragraphs, lists, tasks, code fences (CodeBlock), inline code, emphasis, links, quotes, rules and tables. Raw HTML stays text, links open only for http, https and mailto in a new tab, images are links. Long texts show their start until \"Show all\".",
+          "description": "Markdown, safely: headings, paragraphs, lists, tasks, code fences (CodeBlock), inline code, emphasis, links, quotes, rules and tables. Raw HTML stays text, links open only for http, https and mailto in a new tab, images are links. Long texts show their start until \"Show all\". A table wider than its column scrolls sideways with a fade and takes focus.",
           "props": [
             {
               "name": "text",
@@ -8849,7 +8951,7 @@
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "The area that opens the menu on a right click or long press."
+              "description": "The area that opens the menu on a right click or long press. When it holds nothing focusable, it becomes a focus stop, so Shift F10 and the context-menu key reach it; the focus returns to it when the menu closes."
             },
             {
               "name": "onOpenChange",
@@ -8863,7 +8965,7 @@
         },
         {
           "name": "Menu",
-          "description": "A dropdown menu: 16px radius, 34px rows, typeahead, Home/End, loops.",
+          "description": "A dropdown menu: 16px radius, 34px rows that grow when a label wraps, typeahead, Home/End, loops. An item's shortcut and hint describe it rather than name it. Checkbox and radio items show a check when chosen; the group's label says whether it takes one or several.",
           "props": [
             {
               "name": "children",
@@ -8971,7 +9073,7 @@
       "components": [
         {
           "name": "Meter",
-          "description": "A limit or quota: label and value, a 6px pill track, threshold ticks, a caption.",
+          "description": "A limit or quota: label and value, a 6px pill track, threshold ticks cut out of the bar, a caption. Past the first threshold the bar turns amber and the value and caption turn the warning color, at the limit red, and screen readers hear \"near the limit\" or \"over the limit\" after the value; in light the bar's end keeps 3:1 against the track.",
           "props": [
             {
               "name": "value",
@@ -8992,7 +9094,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "\"Resets in 12 days\""
+              "description": "\"Resets in 12 days\"; near or over the limit, say what happens, such as \"Over the limit: requests are refused\"."
             },
             {
               "name": "className",
@@ -9048,7 +9150,7 @@
         },
         {
           "name": "Progress",
-          "description": "Progress for work over a second: a determinate pill, or an indeterminate 2px line.",
+          "description": "Progress for work over a second: a determinate pill, or an indeterminate 2px line. With reduced motion the indeterminate line spans the width and pulses instead of sliding, so it never reads as a third done.",
           "props": [
             {
               "name": "aria-label",
@@ -9079,7 +9181,7 @@
         "METER": {
           "axes": {
             "tone": {
-              "auto": "Series 1 until the first alert threshold, warning after, danger at 100% (default)",
+              "auto": "Series 1 until the first alert threshold, amber (series 2) after, danger at 100%; the value and the caption take the warning or danger color too (default)",
               "neutral": "A plain share"
             }
           },
@@ -9159,7 +9261,7 @@
         "PAGE_HEADER": {
           "axes": {
             "size": {
-              "md": "52px, no bottom line (default); on a phone the tabs take a second row"
+              "md": "52px, no bottom line (default); on a phone the title and actions keep the first row and the tabs take a second"
             }
           },
           "defaults": {
@@ -9394,7 +9496,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Whether there is a next page."
+              "description": "Whether there is a next page; with Load more, turning it off after the last load shows “All rows shown” where focus was."
             },
             {
               "name": "hasPrevious",
@@ -9443,7 +9545,7 @@
               "type": "number",
               "required": false,
               "default": "1",
-              "description": "pages:"
+              "description": "The current page, for numbered pages; previous and next stay in place and only announce themselves unavailable at the ends."
             },
             {
               "name": "pageCount",
@@ -9467,9 +9569,9 @@
         "PAGINATION": {
           "axes": {
             "variant": {
-              "load-more": "A “Load more” pill while more rows exist, nothing once all are shown (cursor APIs, default)",
+              "load-more": "A “Load more” pill while more rows exist; once all are shown, nothing, or “All rows shown” where the button had focus (cursor APIs, default)",
               "cursor": "Previous and next circles, without a count",
-              "pages": "Page numbers, for lists with a known number of pages"
+              "pages": "Page numbers in seven fixed slots, so Next stays under the pointer, for lists with a known number of pages"
             }
           },
           "defaults": {
@@ -9485,7 +9587,7 @@
       "components": [
         {
           "name": "CompareGrid",
-          "description": "Columns side by side to compare models: equal widths, a header, a body that scrolls on its own and a footer each.",
+          "description": "Columns side by side to compare models: equal widths of at least 320px, a header, a body that scrolls on its own and a footer each. When the columns don't fit, Previous column and Next column reach the hidden ones. Removing a column is instant, so offer Undo in a toast.",
           "props": [
             {
               "name": "aria-label",
@@ -9548,21 +9650,21 @@
               "type": "(() => void)",
               "required": false,
               "default": null,
-              "description": "Adds a column: a circle at the end of the last column's header (and in the phone's switcher)."
+              "description": "Adds a column: a circle in a narrow rail after the columns (on a phone, in the switcher, or in the header of a single column). Focus moves to the new column's header."
             }
           ],
           "file": "src/components/playground/compare-grid.tsx"
         },
         {
           "name": "Composer",
-          "description": "The prompt box: a text box that grows with what is written up to `maxRows`, then scrolls; Send, which becomes Stop while a response streams. Enter sends and Shift Enter adds a line (`submitOn`); ⌘ Enter or Ctrl Enter also sends. On a touch screen Enter adds a line and the button sends.",
+          "description": "The prompt box: a text box that grows with what is written up to `maxRows`, then scrolls, its edge fading where more lines wait; Send, which becomes Stop while a response streams. Enter sends and Shift Enter adds a line (`submitOn`); ⌘ Enter or Ctrl Enter also sends. On a touch screen Enter adds a line and the button sends. A click anywhere in the box, the button row included, puts the cursor in the text.",
           "props": [
             {
               "name": "actions",
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Controls at the start of the button row: parameters, clear."
+              "description": "Controls at the start of the button row: parameters, clear. Ghost and secondary buttons there take tones made for the composer's surface."
             },
             {
               "name": "aria-label",
@@ -9674,21 +9776,21 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "The stop button's accessible name, shown while a reply streams."
+              "description": "The Stop button's label, shown while a response streams (\"Stop\" by default)."
             },
             {
               "name": "streaming",
               "type": "boolean",
               "required": false,
               "default": "false",
-              "description": "A response is arriving: Send becomes Stop. The text box stays editable for the next prompt."
+              "description": "A response is arriving: Send becomes Stop. The text box stays editable for the next prompt; Enter waits, and the text box's description says to stop the response to send."
             },
             {
               "name": "submitLabel",
               "type": "string",
               "required": false,
               "default": null,
-              "description": "The send button's accessible name."
+              "description": "The Send button's label (\"Send\" by default)."
             },
             {
               "name": "submitOn",
@@ -9899,7 +10001,7 @@
         },
         {
           "name": "ParameterPanel",
-          "description": "A request's parameters: system instructions, temperature, top P, most output tokens, and, for a model that reasons, reasoning effort and summary. Unset values are the model's defaults; Reset returns to them (instructions stay).",
+          "description": "A request's parameters: system instructions, temperature, top P, maximum output tokens, and, for a model that reasons, reasoning effort and summary. Unset values are the model's defaults; Reset returns to them (instructions stay).",
           "props": [
             {
               "name": "onValueChange",
@@ -9955,7 +10057,7 @@
               "type": "number",
               "required": false,
               "default": null,
-              "description": "The model's most output tokens: the field's maximum."
+              "description": "The model's maximum output tokens: the field's maximum, named in a hint under it."
             },
             {
               "name": "reasoning",
@@ -9976,7 +10078,7 @@
         },
         {
           "name": "ParameterPopover",
-          "description": "ParameterPanel in a 320px popover from a sliders circle (or any trigger).",
+          "description": "ParameterPanel in a 320px popover from a sliders circle (or any trigger), with a Close button beside its title. Focus stays inside until it closes.",
           "props": [
             {
               "name": "onValueChange",
@@ -10032,7 +10134,7 @@
               "type": "number",
               "required": false,
               "default": null,
-              "description": "The model's most output tokens: the field's maximum."
+              "description": "The model's maximum output tokens: the field's maximum, named in a hint under it."
             },
             {
               "name": "onOpenChange",
@@ -10088,14 +10190,14 @@
         },
         {
           "name": "PromptSuggestions",
-          "description": "Example prompts before a thread starts: up to three lines of plain secondary text that take a quiet fill on hover. No outlines, no icons; leave them out once a prompt is sent.",
+          "description": "Example prompts before a thread starts: up to three pill rows of secondary text that take a quiet fill on hover. No outlines, no icons; a prompt too long for its row shows in full in a tooltip. Leave them out once a prompt is sent.",
           "props": [
             {
               "name": "onSelect",
               "type": "(prompt: string) => void",
               "required": true,
               "default": null,
-              "description": "Puts the prompt in the composer (or sends it)."
+              "description": "Puts the prompt in the composer (or sends it). The list usually goes away then, so move focus to the composer."
             },
             {
               "name": "suggestions",
@@ -10124,13 +10226,20 @@
               "required": false,
               "default": null,
               "description": "Classes for the layout of the outer element: margin, width and placement, never its look."
+            },
+            {
+              "name": "data-force",
+              "type": "string",
+              "required": false,
+              "default": null,
+              "description": "Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`."
             }
           ],
           "file": "src/components/playground/prompt-suggestions.tsx"
         },
         {
           "name": "Reasoning",
-          "description": "A model's reasoning behind a quiet disclosure, closed by default: “Thought for 4.2 s” when it is done, “Thinking” with the latest line beside it while it streams. Opened, the reasoning reads in small secondary text beside a line. The Playground and the request log show reasoning with it.",
+          "description": "A model's reasoning behind a quiet disclosure, closed by default: a chevron, then “Thought for 4.2 s” when it is done, or “Thinking” with the latest line beside it while it streams. Opened, the reasoning reads in small secondary text under the title, beside a line under the chevron. The Playground and the request log (ConversationView) show reasoning with it.",
           "props": [
             {
               "name": "children",
@@ -10146,6 +10255,13 @@
               "default": null,
               "description": "Classes for the layout of the outer element: margin, width and placement, never its look."
             },
+            {
+              "name": "data-force",
+              "type": "string",
+              "required": false,
+              "default": null,
+              "description": "Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`."
+            },
             {
               "name": "defaultOpen",
               "type": "boolean",
@@ -10207,7 +10323,7 @@
         },
         {
           "name": "ResponseMetrics",
-          "description": "A response's numbers on one line: time to first token, total time, tokens (\"412 in · 168 out\", and reasoning), cost to the millionth of a dollar, as request logs show it. Tabular figures, labels in tertiary text. While `live`, values not known yet show \"—\" in the room they will take; before any response the line is empty, its height kept.",
+          "description": "A response's numbers on one line: time to first token, total time, tokens (\"412 in · 168 out\", and reasoning), cost with the decimals it was given, as request logs show it. Tabular figures, labels in tertiary text. Every value keeps the room a typical value takes, so nothing moves when values arrive; while `live`, values not known yet show \"—\"; before any response the line is empty, its height kept.",
           "props": [
             {
               "name": "className",
@@ -10221,7 +10337,7 @@
               "type": "string | null",
               "required": false,
               "default": null,
-              "description": "USD as a decimal string: \"0.004213\" reads \"$0.004213\", and zero reads \"$0\"."
+              "description": "USD as a decimal string, shown with its own decimals (two at least, six at most): \"0.004213\" reads \"$0.004213\", \"1.2311\" reads \"$1.2311\", zero reads \"$0\" and less than a millionth reads \"< $0.000001\"."
             },
             {
               "name": "duration",
@@ -10263,7 +10379,7 @@
               "type": "number | null",
               "required": false,
               "default": null,
-              "description": "Of the output tokens, those spent reasoning. Shown when given, or when `reasoning` is set."
+              "description": "Of the output tokens, those spent reasoning. Shown when given, or when `reasoning` is set (\"—\" when the provider didn't report them)."
             },
             {
               "name": "size",
@@ -10277,7 +10393,7 @@
               "type": "number",
               "required": false,
               "default": null,
-              "description": "When the request was sent (Date.now()): while live, Total counts up quietly until `duration` arrives."
+              "description": "When the request was sent (Date.now()): while live, Total counts up quietly, in tenths of a second and in whole seconds past ten, until `duration` arrives."
             },
             {
               "name": "timeToFirstToken",
@@ -10291,7 +10407,7 @@
         },
         {
           "name": "ResponseView",
-          "description": "A model's response as it arrives: Markdown text for reading (15/22), the reasoning summary in a \"Thinking\" disclosure (closed by default, live while it streams), and calm states for a stop, a cut-off reply or a failure, which shows its error in place.",
+          "description": "A model's response as it arrives: a quiet caret where the text will start until the first token, then Markdown text for reading (15/22) with the caret at its end while it streams; the reasoning summary in a \"Thinking\" disclosure (closed by default, live while it streams); and calm states for a stop, a cut-off reply or a failure, which shows its error in place. Text sits 12px in, code and tables on the edge; screen readers hear when a response finishes or stops.",
           "props": [
             {
               "name": "aria-label",
@@ -10326,7 +10442,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Under the response: its metrics, actions."
+              "description": "Under the response, on its text line: its metrics, actions."
             },
             {
               "name": "incompleteReason",
@@ -10347,7 +10463,7 @@
               "type": "(() => void)",
               "required": false,
               "default": null,
-              "description": "Sends the turn again; shown with an error, a stop or a cut-off reply."
+              "description": "Sends the turn again: a Retry button after a stop, a cut-off reply or an error."
             },
             {
               "name": "reasoning",
@@ -10410,7 +10526,7 @@
         },
         {
           "name": "UserMessage",
-          "description": "A person's turn: their prompt as quiet text that opens the turn, no bubble. A long prompt shows its first lines until \"Show all\".",
+          "description": "A person's turn: their prompt as quiet text that opens the turn, no bubble. A long prompt shows its first lines until \"Show all\", a disclosure button under them.",
           "props": [
             {
               "name": "children",
@@ -10581,7 +10697,7 @@
         },
         {
           "name": "Popover",
-          "description": "A floating panel next to its trigger: radius 16, raised; collision-aware.",
+          "description": "A floating panel next to its trigger: radius 16, raised; collision-aware and never wider than the screen. Its content takes a title, or an aria-label, which names it.",
           "props": [
             {
               "name": "children",
@@ -11155,7 +11271,7 @@
       "components": [
         {
           "name": "ResourceList",
-          "description": "A console list of resources: search, group headers, row actions and a selection bar.",
+          "description": "A console list of resources: search, group headers, row actions and a selection bar. A search announces how many rows it leaves, and its no-match state offers Clear search.",
           "props": [
             {
               "name": "aria-label",
@@ -11197,7 +11313,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Defaults to \"Nothing here yet\" in the provider's language."
+              "description": "What will appear, such as \"No keys yet\". Pass it: the default names the collection by its `aria-label` (\"No keys yet\", in the provider's language), which only reads well for a plural noun."
             },
             {
               "name": "onOpen",
@@ -11238,7 +11354,7 @@
       "components": [
         {
           "name": "ScrollArea",
-          "description": "A scroll container with thin scrollbars in the strong line color that show on hover (5.1), its content fading at an edge with more to scroll to.",
+          "description": "A scroll container with thin scrollbars that show on hover and darken while held, its content fading at every edge with more to scroll to; its focus ring sits above the fade.",
           "props": [
             {
               "name": "children",
@@ -11285,7 +11401,7 @@
             "orientation": {
               "vertical": "Scrolls up and down; the content fades at an edge with more to scroll to (default)",
               "horizontal": "Scrolls sideways",
-              "both": "Both directions"
+              "both": "Both directions; the content fades at every edge with more to scroll to"
             }
           },
           "defaults": {
@@ -11691,7 +11807,7 @@
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "Defaults to \"Select\" in the provider's language."
+              "description": "Defaults to \"Not set\" in the provider's language."
             },
             {
               "name": "required",
@@ -11992,7 +12108,7 @@
               "type": "ReactNode",
               "required": true,
               "default": null,
-              "description": "The sheet's heading, also its accessible name."
+              "description": "The sheet's heading, also its accessible name; a long one wraps."
             },
             {
               "name": "actions",
@@ -12027,7 +12143,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Keep the page behind interactive (non-modal)."
+              "description": "`false` keeps the page behind interactive, for an inspector: a press on the page leaves the sheet open, so the next row can fill it; Escape and the close circle close it."
             },
             {
               "name": "onOpenChange",
@@ -12055,14 +12171,14 @@
               "type": "\"md\" | \"sm\" | \"lg\"",
               "required": false,
               "default": null,
-              "description": "The sheet's width, or its height from the bottom."
+              "description": "The sheet's width from the side; a sheet from the bottom takes its content's height and ignores it."
             },
             {
               "name": "subtitle",
               "type": "ReactNode",
               "required": false,
               "default": null,
-              "description": "A mono subtitle for ids: `req_01J…`."
+              "description": "A mono subtitle for ids, shown whole: `req_01J…`."
             },
             {
               "name": "trigger",
@@ -12181,7 +12297,7 @@
       "components": [
         {
           "name": "Skeleton",
-          "description": "A placeholder in the shape of the content that is loading.",
+          "description": "A placeholder in the shape of the content that is loading. It is hidden from screen readers, so the region it stands in for sets `aria-busy` while it loads (List, DataTable and StatTile do). In forced colours it keeps an outline.",
           "props": [
             {
               "name": "shape",
@@ -12346,7 +12462,7 @@
         "SLIDER": {
           "axes": {
             "size": {
-              "md": "A 4px track in a 20px hit area (default)"
+              "md": "A 4px track in a 32px hit area (default)"
             }
           },
           "defaults": {
@@ -12425,7 +12541,7 @@
         },
         {
           "name": "StatGrid",
-          "description": "`StatTile`s in one raised group, divided by hairlines: two to a row, then as many as there are tiles (up to four) from 1024px. The last tile of a short row widens to fill it (the third of three spans both columns below 1024px), so the group never shows an empty cell. Where a number doesn't fit its tile (a phone, a long amount), every tile's number steps down a size, and the tiles take a row each when even the smallest doesn't fit: a value is never cut short.",
+          "description": "`StatTile`s in one raised group, divided by hairlines: two to a row, then as many as there are tiles (up to four) from 1024px. The last tile of a short row widens to fill it (the third of three spans both columns below 1024px), so the group never shows an empty cell. Where a number doesn't fit its tile (a phone, a long amount), every tile's number steps down a size, and the tiles take a row each when even the smallest doesn't fit. At the same width, live numbers only step the size down, never back up, so a digit that comes and goes doesn't make the tiles jump; a value that still can't fit ends in an ellipsis and shows in full in a tooltip.",
           "props": [
             {
               "name": "children",
@@ -12474,7 +12590,7 @@
               "type": "{ value: number; better?: \"up\" | \"down\"; }",
               "required": false,
               "default": null,
-              "description": "The change against the previous period, as a fraction (0.12 is +12%). `better` says which direction is good: errors are better down."
+              "description": "The change against the previous period, as a fraction (0.12 is +12%). `better` says which direction is good: errors are better down. The badge is green or red and says \"better\" or \"worse\" to screen readers."
             },
             {
               "name": "className",
@@ -12564,7 +12680,7 @@
               "type": "\"md\" | \"sm\"",
               "required": false,
               "default": "md",
-              "description": "The text size."
+              "description": "The text size: 14px, or 13px (`sm`) with a 14px icon."
             },
             {
               "name": "tone",
@@ -12606,14 +12722,14 @@
               "type": "\"md\" | \"sm\"",
               "required": false,
               "default": "md",
-              "description": "The dot's size."
+              "description": "The text size: 14px, or 13px (`sm`) with a 14px icon."
             },
             {
               "name": "tone",
               "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\" | \"info\"",
               "required": false,
               "default": "neutral",
-              "description": "The status the dot marks; keep it next to words that say the same."
+              "description": "The status the word marks; keep it next to words that say the same."
             }
           ],
           "file": "src/components/status-dot/status-dot.tsx"
@@ -12794,7 +12910,7 @@
               "type": "string",
               "required": false,
               "default": null,
-              "description": "Why it is disabled, shown as a tooltip; it stays focusable so people can read it."
+              "description": "Why it is disabled: shown under the label when there is one, and as a tooltip; it stays focusable so people can read it."
             },
             {
               "name": "id",
@@ -12815,7 +12931,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows that the change is being saved and ignores clicks until it is."
+              "description": "Shows that the change is being saved: it ignores clicks at once, and a spinner shows in the track once saving takes 300ms."
             },
             {
               "name": "name",
@@ -12871,7 +12987,7 @@
       "components": [
         {
           "name": "Table",
-          "description": "A plain table for small amounts of data; use `DataTable` for sorting, selection and many rows.",
+          "description": "A plain table for small amounts of data; use `DataTable` for sorting, selection and many rows. It has no row boxes, so its text sits on the gutter, not 12px in; its rows are 40px like DataTable's and grow when a cell wraps. Wider than its room, it scrolls sideways inside its own box under an edge fade, and the box takes focus as a group named \"Table, scrolls sideways\". Keep ids and model names on one line with `className=\"whitespace-nowrap\"` on their cells.",
           "props": [
             {
               "name": "density",
@@ -13011,8 +13127,8 @@
         "PILL_TABS": {
           "axes": {
             "variant": {
-              "underline": "Underline tabs for detail pages: 40px, a 2px ink indicator that slides",
-              "pill": "Header tabs: separate 32px pills, the active one filled"
+              "underline": "Underline tabs for detail pages: 40px, labels 12px in like every box, a 2px ink indicator under the label that slides",
+              "pill": "Header tabs: separate 32px pills, the active one filled; the first pill's edge on the gutter"
             }
           },
           "defaults": {
@@ -13022,8 +13138,8 @@
         "TABS": {
           "axes": {
             "variant": {
-              "underline": "Underline tabs for detail pages: 40px, a 2px ink indicator that slides",
-              "pill": "Header tabs: separate 32px pills, the active one filled"
+              "underline": "Underline tabs for detail pages: 40px, labels 12px in like every box, a 2px ink indicator under the label that slides",
+              "pill": "Header tabs: separate 32px pills, the active one filled; the first pill's edge on the gutter"
             }
           },
           "defaults": {
@@ -13067,14 +13183,14 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Marks a value that isn't accepted."
+              "description": "Marks a value that isn't accepted: a red ring, red text and an error icon named \"Not accepted\", so it doesn't rest on color."
             },
             {
               "name": "onClick",
               "type": "((e: MouseEvent<HTMLElement, MouseEvent>) => void)",
               "required": false,
               "default": null,
-              "description": "Renders a button with a hover fill."
+              "description": "Renders a button with the control's hover, press and focus: raised tags take the secondary button's material, outline tags the ghost's."
             },
             {
               "name": "onRemove",
@@ -13088,7 +13204,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "For toggle pills (DisplayOptions)."
+              "description": "For toggle pills (DisplayOptions): sets aria-pressed, and `true` draws the selected soft fill whatever the variant, so a toggle needs no variant swap."
             },
             {
               "name": "removeLabel",
@@ -13144,14 +13260,14 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Marks a value that isn't accepted."
+              "description": "Marks a value that isn't accepted: a red ring, red text and an error icon named \"Not accepted\", so it doesn't rest on color."
             },
             {
               "name": "onClick",
               "type": "((e: MouseEvent<HTMLElement, MouseEvent>) => void)",
               "required": false,
               "default": null,
-              "description": "Renders a button with a hover fill."
+              "description": "Renders a button with the control's hover, press and focus: raised tags take the secondary button's material, outline tags the ghost's."
             },
             {
               "name": "onRemove",
@@ -13165,7 +13281,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "For toggle pills (DisplayOptions)."
+              "description": "For toggle pills (DisplayOptions): sets aria-pressed, and `true` draws the selected soft fill whatever the variant, so a toggle needs no variant swap."
             },
             {
               "name": "removeLabel",
@@ -13261,7 +13377,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "One line with an ellipsis; the full text appears in a tooltip when it is cut."
+              "description": "One line with an ellipsis; when it is cut, plain text becomes a focus stop whose tooltip shows all of it."
             },
             {
               "name": "variant",
@@ -13368,7 +13484,7 @@
               "type": "number",
               "required": false,
               "default": null,
-              "description": "The image's own height in pixels, so the page keeps its place before it loads."
+              "description": "The image's own height in pixels. Pass it with `width` so the page keeps the image's place before it loads; without both, the content below moves when it arrives."
             },
             {
               "name": "width",
@@ -13585,7 +13701,7 @@
       "components": [
         {
           "name": "Timeline",
-          "description": "Events down a 1px line (the audit log): each event marks the line with a short 3px bar in its tone, no dots; titles, and times on the right.",
+          "description": "Events down a 1px line (the audit log): each event marks the line with a short 3px bar in its tone, no dots; titles, and times on the right. A toned event's title starts with its tone in words for screen readers (\"Critical: Key revoked\"), and a time with `datetime` shows the exact date and time in a tooltip.",
           "props": [
             {
               "name": "events",
@@ -13643,7 +13759,7 @@
               "type": "number",
               "required": false,
               "default": "5000",
-              "description": "How long a toast stays, in milliseconds."
+              "description": "How long a toast stays, in milliseconds; errors and toasts with an action stay until dismissed, unless `toast()` gets a timeout of its own."
             }
           ],
           "file": "src/components/toast/toast.tsx"
@@ -13671,7 +13787,7 @@
               "type": "boolean",
               "required": false,
               "default": null,
-              "description": "Shows a close button."
+              "description": "Shows the close button at its end, as a toast that stays until dismissed has."
             },
             {
               "name": "data-force",
@@ -13699,7 +13815,7 @@
         },
         {
           "name": "Toaster",
-          "description": "Mount once near the root. Three visible at most; 5s, paused on hover and focus; swipe or Escape to dismiss. With a client router that replaces <body> on navigation (Astro's ClientRouter), mount it in a persisted element inside a `PortalContainer`, so the toasts are not swapped away with the page.",
+          "description": "Mount once near the root. Three visible at most; 5s, paused on hover and focus; an error, or a toast with an action such as Undo, stays until it is dismissed; the close button, a swipe or Escape dismisses, and F6 moves the focus to the toasts. With a client router that replaces <body> on navigation (Astro's ClientRouter), mount it in a persisted element inside a `PortalContainer`, so the toasts are not swapped away with the page.",
           "props": [
             {
               "name": "limit",
@@ -13713,7 +13829,7 @@
               "type": "number",
               "required": false,
               "default": "5000",
-              "description": "How long a toast stays, in milliseconds."
+              "description": "How long a toast stays, in milliseconds; errors and toasts with an action stay until dismissed, unless `toast()` gets a timeout of its own."
             }
           ],
           "file": "src/components/toast/toast.tsx"
@@ -13744,7 +13860,7 @@
       "components": [
         {
           "name": "TableOfContents",
-          "description": "\"On this page\": the heading in view in text color with a 2px ink bar.",
+          "description": "\"On this page\": the heading in view in text color with a 2px ink bar on the rail.",
           "props": [
             {
               "name": "items",
@@ -13783,7 +13899,7 @@
           "axes": {
             "state": {
               "default": "A heading",
-              "active": "The heading in view, with a 2px ink bar"
+              "active": "The heading in view, with a 2px ink bar on the rail (a solid line in forced colours)"
             }
           },
           "defaults": {
@@ -13799,7 +13915,7 @@
       "components": [
         {
           "name": "Toolbar",
-          "description": "A row of controls above a list or a chart.",
+          "description": "A row of controls above a list or a chart: one tab stop, with the arrow keys moving between its controls.",
           "props": [
             {
               "name": "aria-label",
@@ -13823,7 +13939,7 @@
         "TOOLBAR": {
           "axes": {
             "size": {
-              "md": "48px, 24px side padding, under the page header (default)",
+              "md": "48px, 24px side padding, under the page header (default); one tab stop, arrows move between controls",
               "inset": "48px without side padding, inside padded content"
             }
           },
@@ -13840,7 +13956,7 @@
       "components": [
         {
           "name": "Tooltip",
-          "description": "A short label for a control, shown on hover and focus. Never on disabled elements without a reason.",
+          "description": "A short label for a control, shown on hover and focus. When it says more than the control's name, it is also the control's accessible description. Never on disabled elements without a reason.",
           "props": [
             {
               "name": "children",
@@ -13896,7 +14012,7 @@
               "type": "\"pill\" | \"multiline\"",
               "required": false,
               "default": "pill",
-              "description": "A pill for a short label, or a box for several lines."
+              "description": "A pill for a short label, or a box for several lines; a pill too long for the screen wraps into the box."
             },
             {
               "name": "shortcut",
@@ -13924,7 +14040,7 @@
         },
         {
           "name": "TooltipProvider",
-          "description": "Tooltips open after 500ms, and instantly when moving between tooltipped siblings.",
+          "description": "Tooltips open once the pointer has rested on a control for 500ms, and instantly when moving between tooltipped siblings.",
           "props": [
             {
               "name": "children",