@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/password-input.json

@@ -143,7 +143,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A masked text field with a reveal control.",
+  "summary": "A masked text field with a reveal control that says what it does and which way it is.",
   "examples": [
     {
       "title": "Usage",
@@ -151,10 +151,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/password-input",
   "mdUrl": "/docs/components/password-input.md",
   "jsonUrl": "/r/components/password-input.json",
+  "whenToUse": [
+    "Any secret the user types and may need to check: a password, a token, a passphrase.",
+    "Anywhere a reveal is a genuine kindness — long generated secrets typed by hand."
+  ],
+  "whenNotToUse": [
+    "A secret that should never be shown. Pass `showReveal={false}`, or do not render one at all.",
+    "A config value that may reference an environment variable. Use `EnvVarInput`."
+  ],
+  "commonMistakes": [
+    "Replacing the reveal with a bare icon or a checkbox. It is a toggle button carrying `aria-pressed`, which is the one attribute that announces both what it does and its current state.",
+    "Painting the characters out with CSS instead of switching `type`. A password manager and the browser both key off the real type."
+  ],
   "specimens": [
     {
       "title": "PasswordInput",
@@ -166,6 +178,5 @@
       "note": "Input plus a reveal toggle carrying `aria-pressed`, so the state is spoken rather than implied by an icon swap.",
       "interaction": "the toggle is in the tab order after the field."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/permission-grant.json

@@ -95,10 +95,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/permission-grant",
   "mdUrl": "/docs/components/permission-grant.md",
   "jsonUrl": "/r/components/permission-grant.json",
+  "whenToUse": [
+    "A capability request from a named requester — filesystem access, network reach — where the answer outlives this one call.",
+    "The settled outcome: `scope` takes `session`, `always` or `denied` and the card shows what was decided rather than disappearing."
+  ],
+  "whenNotToUse": [
+    "A grant whose limits you cannot state. `reach` is required, and it is meant to carry what the grant does not cover as well as what it does."
+  ],
+  "commonMistakes": [
+    "Writing `reach` as a list of what is allowed only. Write the limits in too — that is what makes it a reach rather than a feature list.",
+    "Naming `capability` after the action rather than the capability. The point of this card, against a per-call approval, is that it grants a capability."
+  ],
   "specimens": [
     {
       "title": "PermissionGrant",
@@ -110,6 +121,5 @@
       "note": "The other half of the loop: granting a capability rather than approving one action. The reach is a list the caller writes, and the limits belong in it, because a grant a reader cannot bound is a grant they cannot give.",
       "interaction": "the three answers are Deny, this session and Always. Answer any card and it settles into the scope you chose."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/permission-scopes.json

@@ -164,10 +164,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/permission-scopes",
   "mdUrl": "/docs/components/permission-scopes.md",
   "jsonUrl": "/r/components/permission-scopes.json",
+  "whenToUse": [
+    "The approval card for one tool call, where a standing grant would write a rule and the reader deserves to be told which file it lands in.",
+    "A product with nowhere to persist a grant: omit `scopes` and the card asks, offering only once and no."
+  ],
+  "whenNotToUse": [
+    "As an overlay. There is no settled state — an answered permission is not a card any more, and every product that modelled approval as an overlay got the bug where the next message hides the answer."
+  ],
+  "commonMistakes": [
+    "Passing `onAlwaysAllow` without `scopes`. No scopes means no always-allow answer: a permanent grant that cannot say where it is saved is not one this element will offer.",
+    "Shortening or eliding a long rule before passing it. The label wraps instead, because a cut lands on the part that says how much is being granted — and `and 3 more` is a count, not an account.",
+    "Expecting `1`, `2` and `3` to answer from anywhere. The handler is the card's own `onKeyDown`, nothing is bound to the document, and the card never takes focus itself — a card that arrives mid-sentence and starts answering keystrokes is the bug the reference's 500ms delay exists to prevent."
+  ],
   "specimens": [
     {
       "title": "PermissionScopes",
@@ -179,6 +191,5 @@
       "note": "The one control in an agent UI whose label has to be computed, because what it grants is different every time it appears. `Yes, allow Bash(cue patch:*) for this project (just you)` is written from the rules it would add and the reach it would add them to, and the sentence under it names the file — permanently, not on hover. Nothing is shortened: the reference elides a long rule and strips the `:*` off a prefix rule, and both cuts land on the part that says how far the grant reaches, so this one wraps instead. When there are more rules than the sentence can name, every one of them is listed underneath, because `and 3 more` is a count and a count is not an account. The last card is what that costs: one directory of seventy-seven characters that a line breaker reads as a single word — it would take a hyphen if the name had one, and an underscored path has none — so the sentence breaks mid-path rather than running out of the card. It is also the card where the sentence is the whole account, since a grant naming one directory draws no rule list under it. The card after it moves the long word to the other two caller strings that can carry one — the subject beside the question, and the destination naming the file the grant is written into — and draws the destination both ways: the top card cycles it, so it is a button sized to its own text, and the bottom card has one destination and draws a span. Cycle the top one onto the project and the sentence breaks mid-path instead of leaving the card, which is the whole point of drawing where a permission is saved rather than hiding it behind a hover.",
       "interaction": "tab into the card and the numbers work — 1, 2, 3 fire whichever answers are rendered, built from the same list that drew them, and Escape denies. They are the card's own keys, not the document's: nothing here answers a digit typed into a composer somewhere above it, and a console that wants them to answer from anywhere routes them there itself. Press the dotted line to move the grant to another destination and watch the answer above it change with it: there is one resolved scope behind the label, the sentence and the callback, so they cannot disagree about what is being granted."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/piano-keyboard.json

@@ -129,10 +129,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/piano-keyboard",
   "mdUrl": "/docs/components/piano-keyboard.md",
   "jsonUrl": "/r/components/piano-keyboard.json",
+  "whenToUse": [
+    "Choosing a note range, where the keyboard itself is the clearest scale."
+  ],
+  "whenNotToUse": [
+    "A numeric range with no musical meaning. Use `Slider`."
+  ],
+  "commonMistakes": [
+    "Treating it as a display. It is a range control — the markers are draggable and the edges are arrow-key operable."
+  ],
   "specimens": [
     {
       "title": "PianoKeyboard",
@@ -144,6 +153,5 @@
       "note": "Exact key geometry from the shared layout module, in-range tinting, and draggable start and end markers.",
       "interaction": "each marker is a `role=slider` that announces the note it sits on, so the drag is a fast path rather than the only path."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/preset-section.json

@@ -64,7 +64,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "Section 1 — the four choices that are not token edits at all.",
+  "summary": "Section 1 of the configurator — the four choices that are not token edits at all.",
   "examples": [
     {
       "title": "Usage",
@@ -72,9 +72,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/preset-section",
   "mdUrl": "/docs/components/preset-section.md",
   "jsonUrl": "/r/components/preset-section.json",
-  "todo": true
+  "whenToUse": [
+    "Inside `ThemeConfigurator`. Preset, mode and density are *provider* state: picking one restamps the document and every portal under it."
+  ],
+  "whenNotToUse": [
+    "On its own. It edits the configurator's model, not yours."
+  ],
+  "commonMistakes": [
+    "Filing these with the colours. They are not token edits, which is why they live in their own section."
+  ]
 }

package/manifest/components/progress.json

@@ -94,10 +94,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/progress",
   "mdUrl": "/docs/components/progress.md",
   "jsonUrl": "/r/components/progress.json",
+  "whenToUse": [
+    "Work whose completion you can actually measure.",
+    "Work whose length you cannot: pass `value={null}` and the fill collapses to an indeterminate state."
+  ],
+  "whenNotToUse": [
+    "A short wait with no structure. Use `Spinner`.",
+    "Content arriving whose shape you know. Use `Skeleton`, which holds the layout too."
+  ],
+  "commonMistakes": [
+    "Easing the width transition. It is 120ms linear on purpose — a progress bar that eases is lying about its rate.",
+    "Faking determinate progress by animating to 90% and waiting. That is an indeterminate state wearing a number."
+  ],
   "specimens": [
     {
       "title": "Progress",
@@ -109,6 +121,5 @@
       "note": "Determinate and indeterminate, with an optional printed value.",
       "interaction": "the indeterminate track stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/prompt-library.json

@@ -102,10 +102,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/prompt-library",
   "mdUrl": "/docs/components/prompt-library.md",
   "jsonUrl": "/r/components/prompt-library.json",
+  "whenToUse": [
+    "A saved-prompt drawer where the reader should see a prompt's variables before it lands in the composer."
+  ],
+  "whenNotToUse": [
+    "A picker that inserts on a single click. Insertion is `onInsert`, called on double click; a single click only highlights."
+  ],
+  "commonMistakes": [
+    "Filtering `prompts` yourself against `query`. Filtering happens inside, against the name — pass everything saved.",
+    "Wiring `onSelect` to insert. Selecting previews the prompt below the list; inserting is the separate callback."
+  ],
   "specimens": [
     {
       "title": "PromptLibrary",
@@ -117,6 +127,5 @@
       "note": "Prompts somebody saved, searchable, with the holes in them counted before you insert one — `3 vars` is the difference between a prompt you can send and a template you still have to fill. The preview underneath is the whole body, because a prompt library that hides the prompt is a list of file names.",
       "interaction": "arrows walk the list and Enter inserts; a row also inserts on double-click, so the mouse has the same two gestures the keyboard does. An empty result says what it found nothing for rather than showing an empty box."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/queue-dock.json

@@ -119,10 +119,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/queue-dock",
   "mdUrl": "/docs/components/queue-dock.md",
   "jsonUrl": "/r/components/queue-dock.json",
+  "whenToUse": [
+    "A dock over the composer where a queued turn can still be rewritten, jumped to the front, or dropped before it sends — a queue you can only watch is one you will let send something you no longer mean.",
+    "A shared transcript, read-only: pass `messages` and `open` with no handlers and the dock draws the entries with nothing to press."
+  ],
+  "whenNotToUse": [
+    "An empty queue. It draws nothing — no line, no empty state, no rule — because a dock that announces it has nothing in it is a permanent strip of chrome apologising for itself."
+  ],
+  "commonMistakes": [
+    "Sorting `messages` into the order you think they should drain. Ordering is the caller's, because a component that sorted the array it was given could not be dragged.",
+    "Expecting edit, send-now and remove to be there by default. Each control exists only when its handler is given.",
+    "Owning `open` internally. It is a prop, so a scripted replay of the dock is arithmetic rather than a component with a mind of its own."
+  ],
   "specimens": [
     {
       "title": "QueueDock",
@@ -134,6 +146,5 @@
       "note": "What you typed while it was still working — and the three things you can still do about it. Cursor, opencode, Cline, Roo and Zed all ship this dock and assistant-ui's catalogue has nothing like it; the vendored MessageQueue two files along is the strip without the verbs. It folds to one line, because four queued turns above a composer is a wall, and an empty queue draws nothing at all rather than a strip of chrome apologising for itself.",
       "interaction": "the summary line is the trigger and carries its own aria-expanded; each entry's three controls are named after the turn they belong to (`Send now: Then export the whole show to the desk`), so a screen reader hears which one it is about to jump. Press any of them here and the entry drains — the bench refills when the last one goes."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/quota-banner.json

@@ -93,10 +93,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/quota-banner",
   "mdUrl": "/docs/components/quota-banner.md",
   "jsonUrl": "/r/components/quota-banner.json",
+  "whenToUse": [
+    "An allowance the reader is close to spending — the banner turns amber at 90 per cent of `limit`."
+  ],
+  "whenNotToUse": [
+    "A window whose reset you cannot state. `resetsIn` is required and pre-formatted; this does no time arithmetic."
+  ],
+  "commonMistakes": [
+    "Passing a percentage as `used`. `used` and `limit` are both counts in `unit`, and the amber threshold is derived from them.",
+    "Passing a Date or a duration to `resetsIn`. It is pre-formatted text — `3h 12m`."
+  ],
   "specimens": [
     {
       "title": "QuotaBanner",
@@ -108,6 +118,5 @@
       "note": "How much is left, when it comes back, and the way to get more — in that order, which is the order the question is actually asked in. It turns warn at nine tenths rather than at the wall, so the warning arrives while there is still something to do about it.",
       "interaction": "the upgrade action is an ink button with the label the caller passes; nothing here is a link, so the destination is entirely the host app's business."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/quote-reply.json

@@ -109,10 +109,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/quote-reply",
   "mdUrl": "/docs/components/quote-reply.md",
   "jsonUrl": "/r/components/quote-reply.json",
+  "whenToUse": [
+    "Acting on part of an answer rather than the whole turn, with the chosen run carried into the composer."
+  ],
+  "whenNotToUse": [
+    "A toolbar with an open-ended action set. Each entry in `actions` names one of the three built-in icons."
+  ],
+  "commonMistakes": [
+    "Expecting the component to detect the selection. `before`, `selection` and `after` are three strings you split, and `toolbarVisible` comes from your own selection handler.",
+    "Confusing `quoted` with `selection`. `quoted` is the text carried into the composer after the quote action, shown under a rule."
+  ],
   "specimens": [
     {
       "title": "QuoteReply",
@@ -124,6 +134,5 @@
       "note": "Select a phrase in an answer and act on that phrase rather than the whole turn. The selection stays lit in the streaming hue while the toolbar is up, and what you quoted is repeated under the composer so the next turn's subject is never in doubt.",
       "interaction": "the toolbar's row is reserved whether or not it is showing, so nothing below it jumps when a selection appears. Each action is a labelled button."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/radio-group.json

@@ -54,7 +54,7 @@
     "--cue-sunken",
     "--cue-text-ui"
   ],
-  "summary": "One-of-many selection: a roving-tabindex group of {@link Radio}s sharing a single value.",
+  "summary": "One-of-many selection: a roving-tabindex group of radios sharing a single value.",
   "examples": [
     {
       "title": "Usage",
@@ -62,10 +62,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/radio-group",
   "mdUrl": "/docs/components/radio-group.md",
   "jsonUrl": "/r/components/radio-group.json",
+  "whenToUse": [
+    "Two to about seven mutually exclusive options that should all be visible.",
+    "Dense settings panels — the whole group is one tab stop, which is what keeps them navigable."
+  ],
+  "whenNotToUse": [
+    "Several answers. Use `CheckboxGroup`.",
+    "A long list. Use `Select` or `Combobox` once the options stop fitting."
+  ],
+  "commonMistakes": [
+    "Leaving the group unnamed. Give it an `aria-label`, or a `FieldLabel` inside a `Field`; without one a screen reader hears unrelated options.",
+    "Expecting arrow keys only to move focus. Per the WAI-ARIA pattern Base UI implements, they move *and* select."
+  ],
   "specimens": [
     {
       "title": "RadioGroup",
@@ -78,6 +90,5 @@
       "note": "One choice out of a short set, in either orientation.",
       "interaction": "arrow keys move the selection, and the group is one tab stop."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/radio.json

@@ -65,7 +65,7 @@
     "--cue-sunken",
     "--cue-text-ui"
   ],
-  "summary": "One option inside a {@link RadioGroup}.",
+  "summary": "One option inside a `RadioGroup`. Round, to say 'exactly one'.",
   "examples": [
     {
       "title": "Usage",
@@ -73,10 +73,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/radio",
   "mdUrl": "/docs/components/radio.md",
   "jsonUrl": "/r/components/radio.json",
+  "whenToUse": [
+    "An option in a set where precisely one answer is legal.",
+    "Anywhere the options should all stay visible — a `Select` hides them behind a click."
+  ],
+  "whenNotToUse": [
+    "Any number of answers, including none. Use `Checkbox`, whose square says so.",
+    "On its own. A lone radio cannot be unselected and has no group to belong to."
+  ],
+  "commonMistakes": [
+    "Rendering one outside a `RadioGroup`, which leaves it with no shared value and no roving focus.",
+    "Overriding the checked fill. It draws an accent rim with an accent core rather than a solid fill so the selected option stays legible on the sunken field colour in every theme."
+  ],
   "specimens": [
     {
       "title": "RadioGroup",
@@ -89,6 +101,5 @@
       "note": "One choice out of a short set, in either orientation.",
       "interaction": "arrow keys move the selection, and the group is one tab stop."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/rating.json

@@ -160,7 +160,7 @@
     "--cue-icon-sm",
     "--cue-space-1"
   ],
-  "summary": "A 0–N rating, drawn as marks.",
+  "summary": "A 0–N rating, drawn as marks and built as a radio group.",
   "examples": [
     {
       "title": "Usage",
@@ -168,10 +168,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/rating",
   "mdUrl": "/docs/components/rating.md",
   "jsonUrl": "/r/components/rating.json",
+  "whenToUse": [
+    "A single score out of a small fixed count.",
+    "Read-only display of a score: it renders as one `img` with the value in its name."
+  ],
+  "whenNotToUse": [
+    "A continuous value. Use `Slider`.",
+    "Several independent flags. Marks imply one ordered scale."
+  ],
+  "commonMistakes": [
+    "Rebuilding it from toggle buttons, which puts five stops in the tab order and announces five unrelated controls where one covers the widget.",
+    "Using `disabled` to show a score. Use `readOnly` — an un-interactive control that still takes focus is a trap, and five disabled radios announce five things where one sentence will do."
+  ],
   "specimens": [
     {
       "title": "Rating",
@@ -183,6 +195,5 @@
       "note": "A radio group of marks, with the value spoken rather than implied by how many glyphs are filled.",
       "interaction": "arrow keys move; clicking the current mark clears it when `allowClear` is on."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/read-aloud.json

@@ -119,10 +119,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/read-aloud",
   "mdUrl": "/docs/components/read-aloud.md",
   "jsonUrl": "/r/components/read-aloud.json",
+  "whenToUse": [
+    "Playback of a finished answer where the reader should be able to follow along word by word."
+  ],
+  "whenNotToUse": [
+    "Text still arriving. The whole answer is split into `words` up front so the spoken one can be lit without re-parsing the text."
+  ],
+  "commonMistakes": [
+    "Expecting `onRateChange` to change the rate. It reports the tap on the rate control; cycling `rate` is yours.",
+    "Computing elapsed and duration inside. Both are pre-formatted strings — `0:04`, `0:11`.",
+    "Guarding `spokenIndex` against the ends. An index outside the text simply speaks none of it."
+  ],
   "specimens": [
     {
       "title": "ReadAloud",
@@ -134,6 +145,5 @@
       "note": "An answer played back with the spoken word lit as it goes. Position is a word index the caller advances, not an audio element, so the same component drives a real voice, a replay, or this bench. Speed is one tap away because that is the control people actually reach for.",
       "interaction": "play/pause and the speed chip are both named buttons, and the label says the current rate rather than just the glyph. The progress bar animates linearly, and not at all under reduced motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/reasoning-effort.json

@@ -75,10 +75,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/reasoning-effort",
   "mdUrl": "/docs/components/reasoning-effort.md",
   "jsonUrl": "/r/components/reasoning-effort.json",
+  "whenToUse": [
+    "A tier control where the choice has a price: each level carries its own token budget, and the selected one becomes the denominator of the bar."
+  ],
+  "whenNotToUse": [
+    "Spend with no tier to measure it against. `selectedKey` picks the budget `spent` fills."
+  ],
+  "commonMistakes": [
+    "Passing a percentage or a fraction as `spent`. It is thinking tokens used so far, filled against the selected level's budget.",
+    "Changing tier and leaving `spent` alone. The denominator moves with the tier, so the same number reads as a different fraction."
+  ],
   "specimens": [
     {
       "title": "ReasoningEffort",
@@ -90,6 +100,5 @@
       "note": "How hard to think, and how much of that budget the run actually spent. The segmented control is the choice; the hairline under it is the consequence, and it moves when you change rungs because a bigger budget makes the same spend a smaller fraction.",
       "interaction": "each segment is a button carrying aria-pressed. The meter animates its width rather than jumping, and holds still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/reasoning-panel.json

@@ -115,10 +115,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/reasoning-panel",
   "mdUrl": "/docs/components/reasoning-panel.md",
   "jsonUrl": "/r/components/reasoning-panel.json",
+  "whenToUse": [
+    "Extended thinking that should be available without being in the way: a trigger that shimmers while it runs, expanding into the steps."
+  ],
+  "whenNotToUse": [
+    "A trace with no settled state to fall back to. `restingLabel` is required — it is what the trigger says once streaming finishes."
+  ],
+  "commonMistakes": [
+    "Appending to `steps` as they land. `steps` is the full list available to reveal and `visibleSteps` is how many of them are shown.",
+    "Leaving `streaming` true after the run, so the trigger keeps its shimmering Thinking label and the active step keeps pulsing.",
+    "Passing `elapsed` on a settled panel. It is the timer beside Thinking while streaming, and omitting it hides it."
+  ],
   "specimens": [
     {
       "title": "ReasoningPanel",
@@ -130,6 +141,5 @@
       "note": "The model's own account of how it got there, revealed a beat at a time and then folded away. While it streams, the trigger shimmers and carries a running clock; when it settles, the label swaps for a summary and the timer goes. `visibleSteps` is what makes it a replay — the caller advances it, the panel never counts.",
       "interaction": "the whole trigger row is the toggle and it takes focus; the chevron turns with the panel. The newest step's dot pulses while streaming and stops when it does."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/recommendation-card.json

@@ -113,10 +113,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/recommendation-card",
   "mdUrl": "/docs/components/recommendation-card.md",
   "jsonUrl": "/r/components/recommendation-card.json",
+  "whenToUse": [
+    "A proposal the agent wants accepted, with the supporting reasoning as `children` and the confidence beside the bar meter."
+  ],
+  "whenNotToUse": [
+    "A decision with more than two outcomes. `state` is `idle` or `accepted`; there is no declined state, and `onAlternatives` is the other way out."
+  ],
+  "commonMistakes": [
+    "Passing a number as `confidenceLabel`. It is copy — `high confidence` — shown next to the meter while idle.",
+    "Forgetting `acceptedLabel`. It is required, and it is the whole of what the card says once `state` flips to `accepted`."
+  ],
   "specimens": [
     {
       "title": "RecommendationCard",
@@ -128,6 +138,5 @@
       "note": "The proposal itself, with how sure the agent is and a yes waiting on it. Accepting swaps the entire action row for a settled line rather than disabling the buttons, because a greyed-out Accept beside a green tick reads as an error state.",
       "interaction": "Accept leads in ink and Alternatives is a ghost. The confidence bars are decorative and hidden from assistive tech — the label beside them carries the meaning."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/regenerate-menu.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/regenerate-menu",
   "mdUrl": "/docs/components/regenerate-menu.md",
   "jsonUrl": "/r/components/regenerate-menu.json",
+  "whenToUse": [
+    "Re-running a turn where the interesting choice is what to run it with."
+  ],
+  "whenNotToUse": [
+    "A plain retry on the same model. The menu exists for the alternatives."
+  ],
+  "commonMistakes": [
+    "Removing the current model from `options`. Pass it and name it in `currentId` — the menu labels it current instead of showing its detail.",
+    "Owning `open` inside. It is a required prop, with `onOpenChange` reporting the trigger."
+  ],
   "specimens": [
     {
       "title": "RegenerateMenu",
@@ -102,6 +112,5 @@
       "note": "Fork the same turn to a different model instead of rolling the same dice again. The row matching `currentId` says `current` where the others say what distinguishes them, which is what keeps the menu from offering you what you already have.",
       "interaction": "the trigger carries aria-expanded and latches while the menu is up. The menu itself is a plain popover in flow — the elements family draws its own, so nothing here portals."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/replay-player.json

@@ -103,10 +103,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/replay-player",
   "mdUrl": "/docs/components/replay-player.md",
   "jsonUrl": "/r/components/replay-player.json",
+  "whenToUse": [
+    "Playing an authored run back — a demo, a docs tile, a screenshot harness — where frame 12 must be the same DOM however the reader got there.",
+    "Deep-linking into a run: `startAt` is the seat, and `data-replay-frame`, `data-replay-state` and `data-replay-playing` let a stylesheet or a test find a frame without reaching into React."
+  ],
+  "whenNotToUse": [
+    "A live run. Every frame of a `ReplayScript` carries the whole scene, so this is a controller over a filmstrip rather than an animation of its own."
+  ],
+  "commonMistakes": [
+    "Accumulating state between frames. The entire rendering rule is `frames[index].scene`, which is what makes scrubbing and watching agree.",
+    "Assuming reduced motion switches the component off. It opens on the resting frame and schedules nothing, but step and scrub keep working — play and rate are the only two affordances that go away.",
+    "Restyling the transport to match the scene. The chrome belongs to the console showing the run, not to the run, which is why it is assembled from shipped cue components."
+  ],
   "specimens": [
     {
       "title": "ReplayPlayer",
@@ -119,6 +131,5 @@
       "note": "The run above, playing. The player is a controller over a filmstrip rather than an animation: every frame carries the whole scene, so frame 5 reached by scrubbing is the same DOM as frame 5 reached by watching. One monotonic clock underneath it means pause keeps the unspent part of a hold instead of starting it again, and the rate control is exact rather than approximate. The root publishes data-replay-state, data-replay-playing and data-replay-frame, the way TerminalFrame publishes data-simulating. Under prefers-reduced-motion nothing is ever scheduled: the player opens on the resting frame and every control except play and rate keeps working, so a reader who asked for stillness can still step through all seven states.",
       "interaction": "the transport is five controls and a scrubber, all keyboard-reachable: the slider steps a frame per arrow key. Stepping stops the clock, because a step is a position rather than a speed. The scenes stay live while they are on screen — open the tool call's disclosure, answer the approval — and what a reader touched outlives the frame it was touched on for exactly as long as the row does: a scene keeps its state while the element in a position holds its type, and starts over when the run puts something else there. The player accumulates nothing either way, which is why a deep link, which is a fresh mount, always draws the frame it names."
     }
-  ],
-  "todo": true
+  ]
 }