@cueplusplus/ui 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,188 @@
 # @cueplusplus/ui
 
+## 0.14.1
+
+### Patch Changes
+
+- 9857b93: Every chrome component now ships hand-written guidance in the manifest.
+
+  Fifteen of the twenty-three had extracted facts and nothing that said when to
+  reach for one. `chrome` joins `layout`, `forms` and `primitives` as a complete
+  group.
+
+  The guidance names the rules these components enforce and a hand-rolled
+  replacement always loses: `SegmentedControl` cannot be emptied and `ToggleGroup`
+  can, which is the whole difference between a view picker and a filter bar;
+  `NavigationMenu` must not take `role="menu"`, because that tells a screen reader
+  to expect commands and swallows the browser's own link affordances; `Toolbar` is
+  one tab stop with arrow keys inside, which is what a flex row of buttons throws
+  away; and `Tree` earns its hand-built implementation on three details together —
+  roving tabindex, a flat DOM carrying `aria-level`/`aria-posinset`/`aria-setsize`,
+  and the keyboard contract.
+
+  No API changed.
+
+- d11bcb7: The six domain groups ship hand-written guidance: date, color, flow, midi, dmx
+  and charts.
+
+  Twenty-eight components gained `whenToUse`, `whenNotToUse` and `commonMistakes`,
+  completing every one of the six. Coverage is 164 of 326, and only `elements` and
+  `icons` remain.
+
+  These are the components most often reached for wrongly, because the right
+  choice depends on the domain rather than the shape: a `DateField` beats a
+  `DatePicker` whenever the user already knows the date, and `TimeField` takes
+  `hourCycle={24}` because a control room does not read AM/PM. `MusicalTimeInput`
+  exists because a number field asks for 4.25 and means "bar 2, beat 1, one
+  sixteenth in". `UniverseGrid` is deliberately not a table: position _is_ the
+  address, which is what makes an overlap visible rather than inferred. And three
+  of them refuse a prop on purpose — `FlowBackground`'s `color` writes a property
+  that outranks the theme map, so passing one opts out of theming rather than
+  into it.
+
+  No API changed.
+
+- 2a5b3aa: Every component in the library now ships hand-written guidance.
+
+  The last 162 — all 152 of `elements` and all 10 of `icons` — gained `whenToUse`,
+  `whenNotToUse` and `commonMistakes`. Coverage is **326 of 326**: an agent reading
+  `manifest.json` now gets the judgement as well as the API for every component,
+  not for the thirty-eight that happened to have prose.
+
+  The guidance is derived from each component's own record, never invented, and
+  where a record had only a one-line summary the file is short rather than padded.
+  What that surfaces is the reasoning the source already carried:
+
+  - `GenerativeUI` takes `spec` as `unknown` on purpose, because a cast is a claim
+    about the bytes nobody is in a position to make — and it never throws, so an
+    error boundary around it is waiting for something that will not happen.
+  - `RevertDock` will not render without `This action cannot be undone.` on screen,
+    and picking a scope only arms it, because the old layout put the destructive
+    control _inside_ the scope control's box at 448px.
+  - `AnimatedNumber` is `tabular-nums` because a proportional `1` is narrower than
+    a `0`, so a stepping counter nudges everything to its right on every update.
+  - `Message` renders React nodes verbatim and will never parse markdown, which is
+    what keeps a consumer from being one prompt away from an injection.
+  - The ten icons each say what misreading their shape prevents: an audience drawn
+    as a tag files people with the folders, an empty beta ring reads as "nothing
+    here yet", and a bare chevron for a CLI tool promises a disclosure that
+    navigates instead.
+
+  No API changed.
+
+- 0b5ed2d: Every forms control now ships hand-written guidance in the manifest.
+
+  Twenty-three of the twenty-nine carried extracted facts — props, variants, types
+  — but nothing that said when to reach for one. They now carry `whenToUse`,
+  `whenNotToUse` and `commonMistakes` alongside the rest, so `forms` joins
+  `primitives` as a complete group.
+
+  The guidance is mostly about pairs that look alike and are not:
+  `Autocomplete` accepts what you typed and `Combobox` does not, which decides what
+  downstream code may assume about the value. `ToggleGroup` can be empty and
+  `SegmentedControl` cannot, which is the difference between a filter bar and a
+  view switcher. `Toggle` announces `aria-pressed` and `Switch` announces
+  `aria-checked`, which is why one belongs in a toolbar and the other in a settings
+  list. `MultiSelect` takes a known set and `TagsInput` takes anything.
+
+  No API changed.
+
+- 3e928f8: Every instrument now ships hand-written guidance in the manifest.
+
+  Fourteen of the twenty-one had extracted facts and nothing that said when to
+  reach for one. `instruments` joins `chrome`, `layout`, `forms` and `primitives`
+  as a complete group.
+
+  Several of these components exist because a hand-rolled version gets one rule
+  wrong, and the guidance names which: `Sparkline` and `UsageChart` fix their axis
+  at 0–100, because a trace scaled to its own range makes a flat 3% look identical
+  to a flat 95%; `Progress` transitions linearly, because a bar that eases is lying
+  about its rate; `GroupBar` gives no cell to an empty group, because a minimum
+  width on a zero draws a group that is not there; `LogViewer` fixes its row height
+  so the virtualiser never measures; and `TwoStepButton` is the right shape for a
+  _routine_ destructive action, where a modal would only teach people to dismiss
+  dialogs.
+
+  No API changed.
+
+- f2e5203: Every layout component now ships hand-written guidance in the manifest.
+
+  Seventeen of the twenty had extracted facts and nothing that said when to reach
+  for one. `layout` joins `forms` and `primitives` as a complete group.
+
+  The guidance is mostly about three disclosure components that look alike and are
+  not: `Accordion` coordinates several peer sections, `Collapsible` is one of them
+  alone, and `Disclosure` is neither — it is an annotation on the form it sits in,
+  which is why giving those fields a summary row makes a form read as twice as long
+  as it is. Also why `Stack` exists at all: `flex gap-2` written by hand pins
+  spacing to a pixel value and quietly opts out of the density ladder.
+
+  No API changed.
+
+- ba6d72e: `ThemeProvider`'s `nonce` now reaches Base UI's style element too, not just the
+  density layer.
+
+  `@base-ui/react` renders one `<style>` of its own — a hoisted
+  `<style precedence>` carrying `.base-ui-disable-scrollbar` — and `ScrollAreaRoot`
+  and `SelectPopup` give it a nonce they read from Base UI's `CSPContext`. Nothing
+  fills that context unless a `CSPProvider` is rendered above them, so under
+  `style-src-elem 'self' 'nonce-<per-request>'` that element shipped bare and the
+  browser refused it by content hash, on every page rendering a Select, a Popover
+  or a ScrollArea.
+
+  It was reported to us as a density-layer problem and it never was: the
+  application that hit it passes no `overrides`, so the density `<style>` did not
+  exist in its tree at all. The nonce prop added for that report was correct and
+  addressed a different element. This is the half that was actually biting.
+
+  Given a nonce, `ThemeProvider` now renders `CSPProvider` around its tree. Given
+  none, it renders none — deliberately, so an application that wraps itself in its
+  own `CSPProvider` keeps it. An unconditional inner provider would overwrite that
+  outer context with `undefined` and un-nonce every Base UI style element in the
+  tree, which is the bug this fixes, caused by its fix.
+
+  No API changed. A tree with no nonce renders exactly what it rendered before.
+
+- b12c65d: Four more groups ship hand-written guidance: overlays, system, chat and the
+  configurator.
+
+  Twenty-one components gained `whenToUse`, `whenNotToUse` and `commonMistakes`,
+  completing all four groups. Coverage is 136 of 326.
+
+  Two of these matter beyond the component they describe. `Message` renders React
+  nodes verbatim and will never parse markdown or HTML, because model output is
+  untrusted text and a component that quietly parsed it would make every consumer
+  of this library one prompt away from an injection — a caller that wants rich text
+  passes its own renderer and owns that decision. And `AskBox` holds only the
+  _draft_ answer: the fact of having answered comes back from the host, because
+  local state as the source of truth for a decision a run depends on survives
+  exactly until the pane unmounts.
+
+  The overlay family's distinctions are the rest: `AlertDialog` refuses
+  outside-press dismissal and `Dialog` does not; `Sheet` is a side channel and
+  `Drawer` is its swipe-dismissable cousin; `HoverCard` is reachable by the pointer
+  and a `Tooltip` is not; `ContextMenu` and `Menubar` re-export `DropdownMenu`'s
+  own rows, so a user can never tell from a row how they got to it.
+
+  No API changed.
+
+- f1fa7b6: Every primitive now ships hand-written guidance in the manifest.
+
+  `Avatar`, `AvatarGroup`, `IconButton`, `Kbd`, `Separator`, `Skeleton`, `Spinner`
+  and `StatusDot` carried extracted facts — props, variants, types — but nothing
+  that said when to reach for one. They now carry `whenToUse`, `whenNotToUse` and
+  `commonMistakes` alongside the rest, so the ten components in `primitives` are
+  complete. An agent reading `manifest.json` gets the judgement as well as the API:
+  that `StatusDot`'s wrapper is the containing block its `sr-only` label needs,
+  that `Skeleton` has no intrinsic size and collapses without one, that
+  `IconButton`'s `aria-label` is the only name the control has.
+
+  No API changed. These are fields the manifest schema already had and thirty-eight
+  other components already filled.
+
+- Updated dependencies [abd9a57]
+  - @cueplusplus/tokens@0.14.1
+
 ## 0.14.0
 
 ### Minor Changes

package/dist/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "info" | "warn" | "danger" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
+  tone?: "info" | "warn" | "danger" | "busy" | "accent" | "ok" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/system/theme-provider.d.ts

@@ -237,7 +237,8 @@ interface ThemeProviderProps {
   /** Restore and write root preferences in localStorage. Defaults to `true`. */
   persistPreferences?: boolean;
   /**
-   * The Content-Security-Policy nonce for the density override layer.
+   * The Content-Security-Policy nonce for every `<style>` element this tree
+   * renders — this library's and Base UI's.
    *
    * When `overrides.densities` is set this provider emits one `<style>`
    * element (see {@link ThemeProviderProps.overrides}). Under a policy of
@@ -246,10 +247,31 @@ interface ThemeProviderProps {
    * cannot pick up a server nonce by itself. Pass the request's nonce here and
    * it is set on the element.
    *
-   * Nothing else in this library emits a `<style>` element, and
+   * It also reaches **Base UI**. Given a nonce, this provider renders
+   * `@base-ui/react`'s own `CSPProvider` around the tree, so the hoisted
+   * `<style>` that `ScrollAreaRoot` and `SelectPopup` emit carries it too.
+   * Without that, a strict policy refuses it by content hash on every page
+   * rendering a Select, a Popover or a ScrollArea — and a consumer has no way
+   * to guess the remedy lives in a peer dependency's provider. An outer
+   * `CSPProvider` a consumer renders itself is left alone: no nonce here means
+   * no provider here, rather than one that overwrites theirs with `undefined`.
+   *
    * `prepaintScript()` returns a *string* the application renders in a
    * `<script>` of its own — so the application already controls that element's
-   * nonce, and this prop is the whole of what a strict policy needs from here.
+   * nonce, and between it and this prop a strict policy needs nothing else
+   * from here.
+   *
+   * **Pass this OR render your own `CSPProvider` — not both.** Base UI's
+   * context carries a second value beside the nonce, `disableStyleElements`,
+   * and its provider is the only public way to set either: the package exports
+   * `CSPProvider` and no hook, so a provider rendered here *replaces* an outer
+   * one rather than extending it. Given a nonce this provider therefore sets
+   * `disableStyleElements` back to its default, and a consumer who had turned
+   * it on outside loses it silently — Base UI resumes emitting the very style
+   * element they suppressed. An application already rendering its own
+   * `CSPProvider` needs nothing from this prop: leave it unset and the outer
+   * context survives untouched, which is the case
+   * `base-ui-nonce-outer-provider.test.tsx` pins.
    *
    * **A nonce cannot rescue a style ATTRIBUTE**, and this provider always sets
    * one on its root: `color-scheme` and `--cue-font-scale`, plus the font

package/dist/system/theme-provider.js

@@ -9,6 +9,7 @@ import { ThemeRegistryContext } from "./theme-registry.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { MODES, THEME_NAME_PATTERN, validateManifest } from "@cueplusplus/theme-base";
+import { CSPProvider } from "@base-ui/react/csp-provider";
 //#region src/system/theme-provider.tsx
 /**
 * The empty registry, at module scope so the default is referentially stable.
@@ -514,7 +515,31 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		"data-cue-overrides": "",
 		children: overridesStyle
 	});
-	return /* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
+	/**
+	* Base UI's own style elements, which this provider's nonce also has to reach.
+	*
+	* `@base-ui/react` renders one style element — a hoisted
+	* `<style precedence>` carrying `.base-ui-disable-scrollbar` — from
+	* `utils/styles.mjs`. `ScrollAreaRoot` and `SelectPopup` pass it a nonce they
+	* read from Base UI's own `CSPContext`, and nothing fills that context unless
+	* a `CSPProvider` is rendered above them. Without one it ships bare and a
+	* `style-src-elem` policy refuses it by content hash, on every page that
+	* renders a Select, a Popover or a ScrollArea — which is most authenticated
+	* pages of a real application, and no page of its sign-in screen. A consumer
+	* cannot reasonably guess that the fix lives in a peer dependency's provider,
+	* and this library already takes the nonce and already sits at the root.
+	*
+	* Rendered **only when a nonce was given**, and that is not tidiness. A
+	* consumer that wraps its own application in `CSPProvider` is the case this
+	* must not break: an unconditional inner provider would overwrite that outer
+	* context with `undefined` and un-nonce every Base UI style element in the
+	* tree — turning this into the bug it exists to fix.
+	*/
+	const withCspContext = (tree) => nonce === void 0 ? tree : /* @__PURE__ */ jsx(CSPProvider, {
+		nonce,
+		children: tree
+	});
+	return withCspContext(/* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
 		value: registry,
 		children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
 			value: contextValue,
@@ -538,7 +563,7 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 				})
 			})
 		})
-	});
+	}));
 }
 //#endregion
 export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };

package/manifest/components/accordion.json

@@ -145,7 +145,7 @@
     "--cue-space-4",
     "--cue-text-ui"
   ],
-  "summary": "A stack of sections, one (or several) open at a time.",
+  "summary": "A stack of sections, one or several open at a time.",
   "examples": [
     {
       "title": "Usage",
@@ -153,10 +153,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/accordion",
   "mdUrl": "/docs/components/accordion.md",
   "jsonUrl": "/r/components/accordion.json",
+  "whenToUse": [
+    "Several peer sections where the reader only needs one at a time: a settings page, a long form split by topic.",
+    "Anywhere the closed titles are themselves a useful table of contents."
+  ],
+  "whenNotToUse": [
+    "Exactly one section. Use `Collapsible` — it wears the same skin, so a lone section and a stack of them look alike by design.",
+    "Optional detail inside a form. Use `Disclosure`; a summary row that looks like a section header makes a form read as twice as long as it is.",
+    "Content the reader must compare side by side. Hiding one to see the other defeats the task."
+  ],
+  "commonMistakes": [
+    "Opening every section by default, which is a page with extra clicks in it.",
+    "Reimplementing the open-state bookkeeping. The disclosure ARIA and keyboard handling are Base UI's; this layer only adds the console skin."
+  ],
   "specimens": [
     {
       "title": "Accordion",
@@ -168,6 +181,5 @@
       "note": "Hairline-separated items with mono summary rows. Several can be open at once.",
       "interaction": "the whole header row is the trigger; the panel animates its height and stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/activity-graph.json

@@ -84,10 +84,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/activity-graph",
   "mdUrl": "/docs/components/activity-graph.md",
   "jsonUrl": "/r/components/activity-graph.json",
+  "whenToUse": [
+    "Run volume over a date window, where the question is which days were busy rather than the exact number on any one of them.",
+    "A header that needs what is being counted on one side and a pre-formatted total opposite it."
+  ],
+  "whenNotToUse": [
+    "A window you need to fit a fixed width. Cells are fixed-size, so a long range scrolls horizontally rather than shrinking.",
+    "Anything that is not a date-and-count series: `data` is date and count pairs, and every gap in the window is filled as an empty cell."
+  ],
+  "commonMistakes": [
+    "Leaving `start` and `end` unset. heat-graph then draws a full year ending today, which will not match your data.",
+    "Bucketing the counts into levels yourself. Levels are classified for you from `data`.",
+    "Passing a raw number to `total`. It is printed as given, so format it first."
+  ],
   "specimens": [
     {
       "title": "ActivityGraph",
@@ -99,6 +112,5 @@
       "note": "Half a year of runs as a calendar of cells, dense where the work was. It is the one element in the family with a runtime dependency of its own — `heat-graph`, an optional peer — which does the calendar arithmetic and the levelling; everything you can see here is cue's, from the five-step ramp in the streaming hue down to the legend. Cells are a fixed size, so a long window scrolls sideways rather than shrinking into a smudge.",
       "interaction": "none. The five legend swatches are `aria-hidden` and sit between the words less and more, which is what carries the scale."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-card.json

@@ -130,10 +130,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-card",
   "mdUrl": "/docs/components/agent-card.md",
   "jsonUrl": "/r/components/agent-card.json",
+  "whenToUse": [
+    "A directory or picker where someone chooses an agent before the conversation starts.",
+    "Advertising named capabilities alongside the provider, version, model and endpoint behind them."
+  ],
+  "whenNotToUse": [
+    "Reporting what an agent is doing right now. The card is a standing description of the agent, not a live state.",
+    "An endpoint that has to be read in full. `endpoint` truncates rather than wraps."
+  ],
+  "commonMistakes": [
+    "Rendering your own Connected label beside the action. `connected` already swaps the action for a settled Connected state and disables it.",
+    "Writing a paragraph into `description`. It is sized for one or two sentences.",
+    "Leaving `onConnect` off while `connected` is false, which shows an action with nowhere to go."
+  ],
   "specimens": [
     {
       "title": "AgentCard",
@@ -145,6 +158,5 @@
       "note": "Who you are about to talk to, before you talk to it: the name and who publishes it, one paragraph on what it is for, the skills it advertises, and — in mono along the bottom — the model and the endpoint actually behind it. Those last two are the line that separates a card from a marketing tile.",
       "interaction": "the action is the only control. Connected disables it and swaps the ink button for a settled field row with a tick, rather than greying out a button that still looks pressable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-handoff.json

@@ -84,10 +84,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-handoff",
   "mdUrl": "/docs/components/agent-handoff.md",
   "jsonUrl": "/r/components/agent-handoff.json",
+  "whenToUse": [
+    "The moment one agent gives the baton to another in a transcript that would otherwise jump.",
+    "Showing which pieces of context travelled across with it."
+  ],
+  "whenNotToUse": [
+    "A handoff you cannot explain. `reason` is required because without it a handoff reads as an unexplained jump.",
+    "A step inside a single agent's own work — this element is about the boundary between two of them."
+  ],
+  "commonMistakes": [
+    "Omitting `carried` to hide the context section. Pass an empty array instead; it is a required prop.",
+    "Leaving `settled` false once the receiving agent is underway, so the arrow and the receiving badge keep signalling a transition that already finished."
+  ],
   "specimens": [
     {
       "title": "AgentHandoff",
@@ -99,6 +111,5 @@
       "note": "The baton moving, with the reason attached. Two badges and an arrow: while the handoff is live the receiving agent and the arrow take the streaming hue, and `settled` cools both once the new agent is actually underway. What travelled across is listed under it against a rule — a handoff with no carried context is a handoff you cannot audit.",
       "interaction": "none. It is a record of something that happened, not a control; the only thing that moves is the colour, over half a second."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-mode-badge.json

@@ -82,10 +82,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-mode-badge",
   "mdUrl": "/docs/components/agent-mode-badge.md",
   "jsonUrl": "/r/components/agent-mode-badge.json",
+  "whenToUse": [
+    "Anywhere a person needs the run's authority from the corner of their eye — the fact every catalogue leaves to prose.",
+    "As the source for mode-aware styling elsewhere: put the same `data-agent-mode` on a composer and its focus ring, send button and rail tint from one place."
+  ],
+  "whenNotToUse": [
+    "A status. Use `AgentStatus` — authority and activity are different questions."
+  ],
+  "commonMistakes": [
+    "Threading a mode prop through components instead of reusing the attribute. `elements.css` declares four custom properties under `data-agent-mode`, so a console adds a mode-aware surface by reading a property rather than by branching."
+  ],
   "specimens": [
     {
       "title": "AgentModeBadge",
@@ -97,6 +107,5 @@
       "note": "How much authority the run is holding, which is the fact a person most needs from the corner of their eye and the one every catalogue leaves to prose. The ladder is four rungs — will it ask me, is it writing, is it only planning, are the guardrails off — because that is how many accents every product in the study paints, whatever it calls its six or seven or nine modes. The chip is the readout; `data-agent-mode` is the part that travels.",
       "interaction": "press the chip to cycle the rung. The second specimen is the whole point: one attribute on the box, and the rail, the border and the send button all re-derive from `var(--cue-elements-mode-icon)` with no prop threading and no branch in any component. Colour is never alone — each rung has its own glyph and its own word, so the ladder survives a monochrome screenshot."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-pile.json

@@ -127,10 +127,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-pile",
   "mdUrl": "/docs/components/agent-pile.md",
   "jsonUrl": "/r/components/agent-pile.json",
+  "whenToUse": [
+    "A multi-agent run where who is involved matters more than what each is doing right now.",
+    "Anywhere the states must be legible without colour — crown, spinning arc and `?` badge each also go into the accessible name."
+  ],
+  "whenNotToUse": [
+    "One agent. An `Avatar` says it with less.",
+    "A list the reader must act on. A pile is a summary."
+  ],
+  "commonMistakes": [
+    "Adding a colour-only state of your own, which breaks the rule the three built-in states follow."
+  ],
   "specimens": [
     {
       "title": "AgentPile",
@@ -142,6 +153,5 @@
       "note": "Faces at −12px overlap, fanning to +4px on hover. The crown marks the orchestrator, an arc marks work in flight and a `?` marks an agent waiting on an answer.",
       "interaction": "every face is a button with the agent's name; the pile is one tab stop and arrow keys move inside it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-plan.json

@@ -54,10 +54,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-plan",
   "mdUrl": "/docs/components/agent-plan.md",
   "jsonUrl": "/r/components/agent-plan.json",
+  "whenToUse": [
+    "An ordered set of steps the agent walks front to back, with one of them currently running."
+  ],
+  "whenNotToUse": [
+    "Work that fans out and rejoins. `steps` is a flat array worked through in order.",
+    "A checklist a person ticks. Progress is driven entirely by `activeIndex`, not by input."
+  ],
+  "commonMistakes": [
+    "Clamping `activeIndex` before passing it. Values past the end already mark every step done, and values before the start mark none.",
+    "Passing rich nodes as steps. `steps` is `readonly string[]`."
+  ],
   "specimens": [
     {
       "title": "AgentPlan",
@@ -69,6 +80,5 @@
       "note": "The checklist the agent published before it started, with one index driving the whole thing: steps before it are done, the step at it is running, steps after it are waiting. An index past the end marks every step done.",
       "interaction": "none. A plan is a readout; the agent moves it, not the reader."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-status.json

@@ -67,10 +67,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-status",
   "mdUrl": "/docs/components/agent-status.md",
   "jsonUrl": "/r/components/agent-status.json",
+  "whenToUse": [
+    "A standing status pill beside a run: working, waiting, or done with a check.",
+    "Showing how long it has been going, which renders in mono when `elapsed` is provided."
+  ],
+  "whenNotToUse": [
+    "A failure. The three states are working, waiting and done — there is no error mode.",
+    "A multi-line explanation. `label` is a short status line."
+  ],
+  "commonMistakes": [
+    "Formatting the clock into `label`. `elapsed` is its own prop and gets the mono treatment.",
+    "Leaving `state=\"working\"` on a finished run, which keeps the pill signalling activity after there is nothing left to do."
+  ],
   "specimens": [
     {
       "title": "AgentStatus",
@@ -82,6 +94,5 @@
       "note": "One pill that always answers the two questions a run raises: what is it doing, and for how long. Working shimmers, waiting is still and marked, done carries a check and the elapsed total.",
       "interaction": "the trailing control is a labelled icon button that pauses a run and offers to run it again once it is done."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-surface.json

@@ -73,10 +73,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-surface",
   "mdUrl": "/docs/components/agent-surface.md",
   "jsonUrl": "/r/components/agent-surface.json",
+  "whenToUse": [
+    "A region of the elements family that must repaint wholesale — a different skin or fidelity — with no prop threading and no branch in any component."
+  ],
+  "whenNotToUse": [
+    "One component's appearance. Use that component's own props.",
+    "Density. Use `Density`."
+  ],
+  "commonMistakes": [
+    "Reading the React context to style something. The attributes do the work — `elements.css` re-declares the `--cue-*` tokens under them and custom properties inherit. The context exists for the one place that cannot see the DOM: an overlay portalled to `<body>` from inside the island."
+  ],
   "specimens": [
     {
       "title": "AgentSurface",
@@ -88,6 +98,5 @@
       "note": "One DOM, three paint jobs. The same three tool calls sit in all three specimens; the only difference is the pair of attributes on the box around them. skin='aui' re-points the colour set to assistant-ui's own inks and grounds, and fidelity='upstream' re-points the metrics too, which is what stops cue's density ladder at the island edge. Without @cueplusplus/ui/elements.css imported, all three would look alike.",
       "interaction": "none of its own. The island is a values-set, not a control: everything inside keeps the behaviour it has outside."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/alert-dialog.json

@@ -195,10 +195,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/alert-dialog",
   "mdUrl": "/docs/components/alert-dialog.md",
   "jsonUrl": "/r/components/alert-dialog.json",
+  "whenToUse": [
+    "A rare, expensive, irreversible action — dropping a database, discarding unsaved work.",
+    "Anywhere an accidental outside click must not dismiss the question."
+  ],
+  "whenNotToUse": [
+    "A routine destructive action. Use `TwoStepButton`: a dialog in front of something people do twenty times an hour only teaches them to dismiss dialogs.",
+    "Anything with more than two answers. Use `Dialog`."
+  ],
+  "commonMistakes": [
+    "Reaching for `Dialog` instead. The difference is not cosmetic — this takes `role=\"alertdialog\"` and refuses outside-press dismissal, which is the whole point.",
+    "Labelling the buttons 'OK' and 'Cancel'. Name the action: 'Delete patch' says what OK does."
+  ],
   "specimens": [
     {
       "title": "AlertDialog",
@@ -210,6 +222,5 @@
       "note": "The destructive twin: no scrim dismissal, no close button, and an explicit pair of Cancel and Action.",
       "interaction": "Escape is deliberately not enough on its own; the action has to be chosen."
     }
-  ],
-  "todo": true
+  ]
 }