@cueplusplus/ui 0.13.0 → 0.14.1

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.
@@ -170,7 +171,7 @@ function writePreferences(storageKey, preferences) {
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, asChild = false, className, style: styleProp, children }) {
+function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, nonce, asChild = false, className, style: styleProp, children }) {
 	const ambient = React.useContext(ThemeContext);
 	const isRoot = ambient === null;
 	const outerStyleSet = React.useContext(StyleSetContext);
@@ -510,10 +511,35 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		children
 	});
 	const densityLayer = overridesStyle === "" ? null : /* @__PURE__ */ jsx("style", {
+		...nonce === void 0 ? null : { nonce },
 		"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,
@@ -537,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
+  ]
 }

package/manifest/components/animated-number.json

@@ -55,10 +55,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/animated-number",
   "mdUrl": "/docs/components/animated-number.md",
   "jsonUrl": "/r/components/animated-number.json",
+  "whenToUse": [
+    "A value that is the same fact moving — a token count, a cost, a duration, a file tally."
+  ],
+  "whenNotToUse": [
+    "A value that is a new fact each time. A number that steps says 'this is different'; one that counts says 'this is the same thing, changed'."
+  ],
+  "commonMistakes": [
+    "Dropping the `tabular-nums`. A proportional `1` is narrower than a `0`, so a stepping counter nudges everything to its right on every update.",
+    "Tweening something that jumps for a real reason, which implies continuity that is not there."
+  ],
   "specimens": [
     {
       "title": "AnimatedNumber",
@@ -70,6 +80,5 @@
       "note": "A number that counts to its new value instead of jumping to it, in tabular numerals so the digits do not jitter on the way. Both halves are one teardown's: the reference eases its live token estimate from the previous value to the new one and paints it in font-variant-numeric tabular-nums, because a proportional 1 is narrower than a 0 and a stepping counter nudges everything to its right on every update. A value that steps reads as a new fact; a value that counts reads as the same fact moving, which is what a token, a cost and a duration actually are.",
       "interaction": "press the button and watch the digits rather than the box — nothing to the right of the number moves. Under prefers-reduced-motion the new value simply arrives: stillness for a counter has to mean landing on the number, because a readout that stopped where it was would be wrong rather than still. Mid-tween the digits are aria-hidden and the settled value is carried beside them, so a screen reader reads what the run reported and never a frame of the animation."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/app-window-frame.json

@@ -104,10 +104,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/app-window-frame",
   "mdUrl": "/docs/components/app-window-frame.md",
   "jsonUrl": "/r/components/app-window-frame.json",
+  "whenToUse": [
+    "A marketing hero or a docs illustration that should re-theme with the site and stay legible at any zoom.",
+    "Anywhere a real screenshot would go stale the week after a redesign."
+  ],
+  "whenNotToUse": [
+    "Application chrome. This is a depiction of a window, not one — use `TitleBar` and `StatusBar` directly."
+  ],
+  "commonMistakes": [
+    "Reaching for a PNG. Because the contents are components, the depiction and the real thing cannot drift — it is built from the real `TitleBar` and `StatusBar`.",
+    "Filling it with fake markup. The point is that it holds the components it is advertising."
+  ],
   "specimens": [
     {
       "title": "AppWindowFrame",
@@ -119,6 +130,5 @@
       "note": "The marketing device: a window with traffic lights, a toolbar slot and a status bar slot, so a screenshot of a product looks like a product.",
       "interaction": "none. The frame is scenery."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/approval-card.json

@@ -116,10 +116,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/approval-card",
   "mdUrl": "/docs/components/approval-card.md",
   "jsonUrl": "/r/components/approval-card.json",
+  "whenToUse": [
+    "A command with side effects that must not run until someone says so.",
+    "Carrying that request through its whole lifecycle, since one card covers request, running, done and denied."
+  ],
+  "whenNotToUse": [
+    "A decision with no command behind it. `command` is required and is shown in a mono field.",
+    "Reporting a command that failed. The four states are request, running, done and denied; a failure needs somewhere else to go."
+  ],
+  "commonMistakes": [
+    "Leaving `state=\"request\"` after the user has answered, so Allow and Deny stay pressable on a command that already ran.",
+    "Folding the explanation into `title`. `title` names the action that needs approval; `subtitle` is the supporting line that explains it."
+  ],
   "specimens": [
     {
       "title": "ApprovalCard",
@@ -131,6 +143,5 @@
       "note": "Human in the loop for one action: the command in mono exactly as it will run, and three answers. The four specimens are the four states of the union, and the first one is live: answer it and it moves.",
       "interaction": "Allow once and Always allow are separate answers, never one control with a modifier. Denying settles the card rather than hiding it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/artifact-card.json

@@ -73,10 +73,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/artifact-card",
   "mdUrl": "/docs/components/artifact-card.md",
   "jsonUrl": "/r/components/artifact-card.json",
+  "whenToUse": [
+    "A document the model produced, standing in the transcript as an object with its kind, version and recency.",
+    "The live phase of that writing, where `generating` pulses the icon and shows a word count with a shimmer."
+  ],
+  "whenNotToUse": [
+    "A file the person attached rather than one the model generated.",
+    "Showing the document's text. The card stands for the artifact; it does not render its body."
+  ],
+  "commonMistakes": [
+    "Passing `words` without `generating`. The live word count only replaces the meta line while generation is running.",
+    "Splitting the resting line across props. `meta` is one pre-formatted string — kind, version and recency together."
+  ],
   "specimens": [
     {
       "title": "ArtifactCard",
@@ -88,6 +100,5 @@
       "note": "The document the answer produced, as an object you can pick up. While it is being written the icon pulses, the label shimmers and the word count climbs; when it lands, the meta line blurs in with its size and version. It is the handle — the document itself opens in a canvas.",
       "interaction": "the whole card is the target and lifts a pixel under the pointer; the arrow only appears on hover, so a resting card is quiet."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/ask-box.json

@@ -268,10 +268,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/ask-box",
   "mdUrl": "/docs/components/ask-box.md",
   "jsonUrl": "/r/components/ask-box.json",
+  "whenToUse": [
+    "A run that cannot proceed without a person — a confirmation, a value, a choice between options.",
+    "Anywhere the answer must be recorded by the host, not by the UI."
+  ],
+  "whenNotToUse": [
+    "A form. This is a single question inside a transcript.",
+    "Something the agent can decide. An ask that did not need asking is an interruption."
+  ],
+  "commonMistakes": [
+    "Letting the component own whether it has been answered. It holds the *draft* only; the fact of having answered comes back as `answer` once the host has recorded it. Anything else makes local state the source of truth for a decision the run depends on — which survives exactly until the pane unmounts."
+  ],
   "specimens": [
     {
       "title": "AskBox",
@@ -283,6 +294,5 @@
       "note": "The HITL question widget: five kinds, three danger levels, and a collapsed `question · answer ✓` summary once it is answered. Controlled through `onAnswer`, because the host owns the run.",
       "interaction": "the danger chip is text as well as colour; an answered box collapses but stays expandable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/audience-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "An audience: a named group of people something is published to.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/audience-icon",
   "mdUrl": "/docs/components/audience-icon.md",
   "jsonUrl": "/r/components/audience-icon.json",
+  "whenToUse": [
+    "Choosing or showing who something is published to."
+  ],
+  "whenNotToUse": [
+    "A container of artefacts. Use `FolderIcon` or `CatalogueIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a diamond or a tag, which files it with the folders — exactly the mistake a reader makes when deciding where to publish something. It is people, not an abstract shape."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
       "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/autocomplete.json

@@ -242,10 +242,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/autocomplete",
   "mdUrl": "/docs/components/autocomplete.md",
   "jsonUrl": "/r/components/autocomplete.json",
+  "whenToUse": [
+    "A value the product cannot enumerate: a name, a search term, a hostname. The suggestions are a shortcut, not the set of legal answers.",
+    "Anywhere typing something unlisted must survive blur rather than being silently discarded."
+  ],
+  "whenNotToUse": [
+    "A value that must come from a known set. Use `Combobox`, whose text is a filter and whose value is always one of `items`.",
+    "Several values at once. Use `TagsInput` for free-form, `MultiSelect` for a known set."
+  ],
+  "commonMistakes": [
+    "Reaching for it because it looks like `Combobox`. Pick on the contract, not the shape: ask what happens downstream to a value nobody suggested.",
+    "Passing objects as `items`. Suggestions are plain strings, because an autocomplete has no identity to attach to a value it did not supply.",
+    "Validating only against the suggestions. The whole point is that the typed value wins, so the typed value is what needs checking."
+  ],
   "specimens": [
     {
       "title": "Autocomplete",
@@ -257,6 +270,5 @@
       "note": "Suggestions over free text: the field keeps whatever was typed, and the list only offers.",
       "interaction": "the list opens on input, not on focus; `autoHighlight` pre-selects the first match."
     }
-  ],
-  "todo": true
+  ]
 }