@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/composer-model-trigger.json

@@ -60,10 +60,21 @@
   ],
   "summary": "The model name in the toolbar, which opens the model menu.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-model-trigger",
   "mdUrl": "/docs/components/composer-model-trigger.md",
   "jsonUrl": "/r/components/composer-model-trigger.json",
+  "whenToUse": [
+    "The toolbar control that opens the model menu, labelled with the selected model.",
+    "A trigger that has to be announced correctly, since it carries `aria-expanded` from `open`."
+  ],
+  "whenNotToUse": [
+    "A control that opens nothing. It carries `aria-expanded` for the menu it opens."
+  ],
+  "commonMistakes": [
+    "Leaving `open` stale. It is announced as `aria-expanded`, so a wrong value lies to a screen reader.",
+    "Setting `aria-expanded` yourself. The trigger already carries it, from `open`."
+  ],
   "specimens": [
     {
       "title": "ComposerModelTrigger / ComposerModelItem",
@@ -76,6 +87,5 @@
       "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
       "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-person-item.json

@@ -61,10 +61,21 @@
   ],
   "summary": "A mentionable person in the menu: their initial, their name, and whether they are an agent or a human.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-person-item",
   "mdUrl": "/docs/components/composer-person-item.md",
   "jsonUrl": "/r/components/composer-person-item.json",
+  "whenToUse": [
+    "Each mentionable person or agent offered in the composer menu.",
+    "A mention list that mixes agents and humans, since the row says which one it is."
+  ],
+  "whenNotToUse": [
+    "An entry that is not a `ComposerPerson`."
+  ],
+  "commonMistakes": [
+    "Marking several rows `active`. It is the row Enter would pick, so only one has it.",
+    "Rendering your own initial beside the name. The row already draws one."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -81,6 +92,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-send.json

@@ -60,10 +60,21 @@
   ],
   "summary": "Send, which becomes stop while the model is streaming.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-send",
   "mdUrl": "/docs/components/composer-send.md",
   "jsonUrl": "/r/components/composer-send.json",
+  "whenToUse": [
+    "The send control of a composer, which doubles as stop while a reply streams.",
+    "An empty input, where `idle` dims the control because there is nothing to send."
+  ],
+  "whenNotToUse": [
+    "A second, separate stop button. The arrow and the square are the same control."
+  ],
+  "commonMistakes": [
+    "Swapping in your own stop button when streaming starts. The arrow and the square cross-fade rather than swap.",
+    "Leaving `idle` false on an empty input, which keeps the button bright when there is nothing to send."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -81,6 +92,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-toolbar.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The row under the input, which holds the two `ComposerActions` clusters.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-toolbar",
   "mdUrl": "/docs/components/composer-toolbar.md",
   "jsonUrl": "/r/components/composer-toolbar.json",
+  "whenToUse": [
+    "The control row beneath the composer input."
+  ],
+  "whenNotToUse": [
+    "Anything above the input, such as the attachment rail."
+  ],
+  "commonMistakes": [
+    "Putting controls straight into the toolbar. It holds two `ComposerActions` clusters, and the controls go inside them."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -60,6 +69,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-voice-button.json

@@ -50,10 +50,19 @@
   ],
   "summary": "The microphone, which becomes a filled stop while recording.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-voice-button",
   "mdUrl": "/docs/components/composer-voice-button.md",
   "jsonUrl": "/r/components/composer-voice-button.json",
+  "whenToUse": [
+    "The toolbar control that opens and closes the microphone."
+  ],
+  "whenNotToUse": [
+    "A separate stop control. The same button becomes a filled stop while `active`."
+  ],
+  "commonMistakes": [
+    "Swapping the icon yourself when recording starts. `active` already turns the microphone into a filled stop."
+  ],
   "specimens": [
     {
       "title": "ComposerVoice / ComposerVoiceButton",
@@ -66,6 +75,5 @@
       "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
       "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-voice.json

@@ -60,10 +60,21 @@
   ],
   "summary": "What replaces the input while the microphone is open: a level meter, a running clock while recording, and a shimmering `Transcribing` once it stops.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-voice",
   "mdUrl": "/docs/components/composer-voice.md",
   "jsonUrl": "/r/components/composer-voice.json",
+  "whenToUse": [
+    "The recording state of a voice composer, in place of the text input.",
+    "The transcribing state after recording stops, which is `recording={false}`."
+  ],
+  "whenNotToUse": [
+    "The resting composer. `recording={false}` is the transcribing state, not the resting one — unmount it instead."
+  ],
+  "commonMistakes": [
+    "Expecting it to keep its own time. `seconds` drives both the clock and the meter, so the caller owns the tick.",
+    "Reading `recording={false}` as idle, which leaves a shimmering Transcribing on screen with nothing to transcribe."
+  ],
   "specimens": [
     {
       "title": "ComposerVoice / ComposerVoiceButton",
@@ -76,6 +87,5 @@
       "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
       "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer.json

@@ -210,7 +210,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "The thing you type into: an auto-growing textarea, a send affordance, and slots for everything a host wants to hang off them.",
+  "summary": "The thing you type into: an auto-growing textarea, a send affordance, and slots to hang things off.",
   "examples": [
     {
       "title": "Usage",
@@ -218,10 +218,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer",
   "mdUrl": "/docs/components/composer.md",
   "jsonUrl": "/r/components/composer.json",
+  "whenToUse": [
+    "Any chat or prompt input.",
+    "Anywhere a running request must be interruptible: `busy` plus `onStop` turns send into stop."
+  ],
+  "whenNotToUse": [
+    "A form field. Use `Textarea` inside a `Field`."
+  ],
+  "commonMistakes": [
+    "Capping it to one line. It grows rather than scrolls on purpose — a box that hides the second half of what you wrote is the most-complained-about part of every chat UI.",
+    "Leaving `onStop` unwired while passing `busy`, which shows a stop affordance that does nothing."
+  ],
   "specimens": [
     {
       "title": "Composer",
@@ -233,6 +244,5 @@
       "note": "An auto-growing textarea at the large control height, with an attachment slot, a toolbar slot and a Stop that reports rather than decides.",
       "interaction": "Enter sends by default, mod+Enter when configured the other way; Shift+Enter always inserts a newline."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/computer-use.json

@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/computer-use",
   "mdUrl": "/docs/components/computer-use.md",
   "jsonUrl": "/r/components/computer-use.json",
+  "whenToUse": [
+    "A live session an agent is operating, wrapped around whatever you use for the viewport.",
+    "Showing the ordered actions taken, with the current one called out."
+  ],
+  "whenNotToUse": [
+    "A session with no viewport to show. `children` is required, and it is the thing being driven."
+  ],
+  "commonMistakes": [
+    "Trimming `steps` down to the current one. The two before `activeIndex` stay as a fading trail.",
+    "Expecting the element to supply the stream. You hand it the viewport yourself — a video stream, a screenshot, an iframe."
+  ],
   "specimens": [
     {
       "title": "ComputerUse",
@@ -93,6 +104,5 @@
       "note": "The screen the agent is driving, with a cursor trail behind it and the current action named underneath. The two steps before the live one stay as fading dots, which is what turns a jumping pointer into a path you can follow. The viewport is `children` — a screenshot, a video stream, a sandboxed iframe — so the element frames it and isolates nothing of its own.",
       "interaction": "none, and deliberately: this is a view of a session, not a remote control. The cursor and its trail are `aria-hidden`; the action row underneath is what a screen reader gets."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/confidence-marker.json

@@ -66,10 +66,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/confidence-marker",
   "mdUrl": "/docs/components/confidence-marker.md",
   "jsonUrl": "/r/components/confidence-marker.json",
+  "whenToUse": [
+    "Generated prose where the reader must know which sentences are grounded."
+  ],
+  "whenNotToUse": [
+    "Citations. Use `InlineCitation` — where a claim came from and how confident it is are different questions."
+  ],
+  "commonMistakes": [
+    "Marking only the guesses, which leaves the reader unable to tell an unmarked sourced claim from an unmarked unchecked one."
+  ],
   "specimens": [
     {
       "title": "ConfidenceMarker",
@@ -81,6 +90,5 @@
       "note": "Which clause came from a source, which was worked out, and which is a guess — drawn as three underlines rather than three colours of text, so the sentence still reads as a sentence. The basis appears under it on hover, in a row that is always reserved so nothing below moves.",
       "interaction": "each clause is a button that responds to hover *and* focus, so the basis is reachable from a keyboard. The chip carries role='status' and is referenced by `aria-describedby`."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/connection-state.json

@@ -83,10 +83,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/connection-state",
   "mdUrl": "/docs/components/connection-state.md",
   "jsonUrl": "/r/components/connection-state.json",
+  "whenToUse": [
+    "Any streamed run, so a dropped socket does not read as a dead run.",
+    "Anywhere the user should know work continued — `resumedTokens` is what proves it."
+  ],
+  "whenNotToUse": [
+    "A failed request with nothing to resume. That is an error, not a reconnection."
+  ],
+  "commonMistakes": [
+    "Showing a generic 'disconnected' state. The point is that the run did not stop; a message that implies it did makes people start over."
+  ],
   "specimens": [
     {
       "title": "ConnectionState",
@@ -98,6 +108,5 @@
       "note": "The socket drops; the run does not. Four phases, and the useful one is `online` — it renders nothing at all, so the element can stay mounted at the top of a transcript and simply have nothing to say most of the time. `dropped` offers a reconnect, `reconnecting` counts attempts, and `resumed` says how much of the stream was recovered.",
       "interaction": "Reconnect is a plain named button. Nothing here retries on its own — the phase is the caller's, so a page can back off however it likes."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/container.json

@@ -55,10 +55,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/container",
   "mdUrl": "/docs/components/container.md",
   "jsonUrl": "/r/components/container.json",
+  "whenToUse": [
+    "A page that already has its own heading — a route opening with a `TitleBar`, or a section inside a shell — where all you need is the measure."
+  ],
+  "whenNotToUse": [
+    "A page that needs a header too. Use `PageShell`, which is this plus one.",
+    "A full-bleed surface. The gutters are the point; wrapping and then cancelling them is a sign the shell is wrong."
+  ],
+  "commonMistakes": [
+    "Nesting one inside another, which applies the gutters twice and narrows the measure without anyone choosing to."
+  ],
   "specimens": [
     {
       "title": "Container",
@@ -70,6 +80,5 @@
       "note": "Three measures. The one place a max-width is allowed to be hardcoded, because a measure is typographic, not thematic.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/context-breakdown.json

@@ -44,7 +44,7 @@
     "--cue-text-body",
     "--cue-warn"
   ],
-  "summary": "Where the window actually went: prompt, tools, files, conversation, and what's left.",
+  "summary": "Where the window actually went: prompt, tools, files, conversation, and what is left.",
   "examples": [
     {
       "title": "Usage",
@@ -52,10 +52,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/context-breakdown",
   "mdUrl": "/docs/components/context-breakdown.md",
   "jsonUrl": "/r/components/context-breakdown.json",
+  "whenToUse": [
+    "Showing the shape of context use without the cost argument around it."
+  ],
+  "whenNotToUse": [
+    "A full accounting with cost. Use `ContextUsage`."
+  ],
+  "commonMistakes": [
+    "Omitting `limit`, which leaves the segments with nothing to be a share of."
+  ],
   "specimens": [
     {
       "title": "ContextBreakdown",
@@ -67,6 +76,5 @@
       "note": "Where the window actually went, which is the question a context limit never answers on its own. Headroom is derived rather than passed — it is whatever the segments left — and the header turns warn once they pass 85 per cent of the limit. The tint is the caller's: the same class paints the bar slice and its legend dot, so the two cannot drift apart.",
       "interaction": "none. The legend dots are `aria-hidden`; the label beside each one carries the meaning."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/context-menu.json

@@ -106,7 +106,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The menu a right click raises: row actions on a cue list, fixture actions on the patch grid, node actions on a canvas.",
+  "summary": "The menu a right click raises: row actions on a cue list, node actions on a canvas.",
   "examples": [
     {
       "title": "Usage",
@@ -114,10 +114,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/context-menu",
   "mdUrl": "/docs/components/context-menu.md",
   "jsonUrl": "/r/components/context-menu.json",
+  "whenToUse": [
+    "Actions that belong to the thing under the pointer.",
+    "Anywhere the same actions should also be reachable another way — a right click is not discoverable on its own."
+  ],
+  "whenNotToUse": [
+    "The only path to an action. Keyboard users never right-click.",
+    "Navigation. Use links."
+  ],
+  "commonMistakes": [
+    "Restyling the rows. They *are* `DropdownMenu`'s rows, re-exported rather than re-skinned — a user should never be able to tell from a row how they got to it."
+  ],
   "specimens": [
     {
       "title": "ContextMenu",
@@ -129,6 +140,5 @@
       "note": "The same menu surface, opened by a right-click on a region rather than by a button.",
       "interaction": "the Menu key and Shift+F10 open it from the keyboard, which is the part most implementations forget."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/context-usage.json

@@ -70,7 +70,7 @@
     "--cue-text-body",
     "--cue-warn"
   ],
-  "summary": "Where the window went, what share each part of it took, and what that cost.",
+  "summary": "Where the window went, what share each part took, and what that cost.",
   "examples": [
     {
       "title": "Usage",
@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/context-usage",
   "mdUrl": "/docs/components/context-usage.md",
   "jsonUrl": "/r/components/context-usage.json",
+  "whenToUse": [
+    "Answering 'why did it forget the thing I said an hour ago' with *the venue's documents are 38k of it* rather than a number going up.",
+    "Anywhere the cost belongs beside the shape — the bar, the table and the stat rows are three readings of one thing."
+  ],
+  "whenNotToUse": [
+    "A limit alone. A context limit tells a reader nothing they can act on.",
+    "The breakdown without the bill. Use `ContextBreakdown`."
+  ],
+  "commonMistakes": [
+    "Rebuilding the breakdown as a grid of divs. It is a real table with real column headers, because three columns of numbers whose meaning is carried by the header is exactly what a table is for."
+  ],
   "specimens": [
     {
       "title": "ContextUsage",
@@ -93,6 +104,5 @@
       "note": "Where the window went, what share each part took, and what that cost — Cursor's tray, opencode's labels and Claude Code's table, which between them are a complete spec. The breakdown is a real table with real column headers because three columns of numbers whose meaning lives in the heading above them is exactly what a table is for. A category that names no tone takes the next hue in the family's rotation, so five rows are legible without the caller choosing five colours that fight.",
       "interaction": "none. The bar is aria-hidden — every figure in it is written out in the table under it — and pressure is stated on the element as `data-pressure`, so a console can style the whole card from one attribute rather than from a threshold of its own."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/conversation-search.json

@@ -91,10 +91,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/conversation-search",
   "mdUrl": "/docs/components/conversation-search.md",
   "jsonUrl": "/r/components/conversation-search.json",
+  "whenToUse": [
+    "Searching a long transcript, where the hits should be visible on the scroll rail and not only in a list."
+  ],
+  "whenNotToUse": [
+    "Searching across threads rather than inside one."
+  ],
+  "commonMistakes": [
+    "Looking up surrounding text per hit. Each `SearchHit` carries its own, so nothing needs fetching to render the preview.",
+    "Expecting `onStep` to hand you a new index. It is called with -1 or 1 and you wrap the index yourself.",
+    "Re-clamping `activeIndex` when the results narrow. It is already clamped to the current hit set, so narrowing cannot strand it out of range."
+  ],
   "specimens": [
     {
       "title": "ConversationSearch",
@@ -106,6 +117,5 @@
       "note": "Find inside one long thread, with every hit marked down the scrollbar so the shape of the answer is visible before you walk it. Each hit carries its own surrounding text, so the preview needs no lookup back into the transcript — which is what lets a search box render before the thread it is searching has loaded.",
       "interaction": "the counter and the rail agree because `activeIndex` is clamped to the current hit set: narrowing the results cannot strand the marker out of range. Stepping is `-1` and `1`; wrapping is the caller's."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/copy-button.json

@@ -98,10 +98,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/copy-button",
   "mdUrl": "/docs/components/copy-button.md",
   "jsonUrl": "/r/components/copy-button.json",
+  "whenToUse": [
+    "Any value the reader is meant to take elsewhere: an id, a token, a command.",
+    "Anywhere the confirmation must be heard as well as seen — the label lives in an `aria-live` region."
+  ],
+  "whenNotToUse": [
+    "A whole document or a selection. That is the browser's copy, not a button."
+  ],
+  "commonMistakes": [
+    "Replacing the label swap with a toast. At console density a toast for 'copied an id' is heavier than the action itself.",
+    "Confirming on a colour change alone, which is never announced (WCAG 1.4.1).",
+    "Treating a failed copy as success. Both the async clipboard and the fallback can fail, and `onCopyError` is how you find out."
+  ],
   "specimens": [
     {
       "title": "CopyButton",
@@ -113,6 +125,5 @@
       "note": "Copies, then says so for a beat. The confirmation is text, not a colour change.",
       "interaction": "the label swaps to the copied state and reverts after the timeout; the accessible name swaps with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cost-meter.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cost-meter",
   "mdUrl": "/docs/components/cost-meter.md",
   "jsonUrl": "/r/components/cost-meter.json",
+  "whenToUse": [
+    "Any surface where spend is a fact the user acts on.",
+    "Multi-model runs, where the split is the interesting part."
+  ],
+  "whenNotToUse": [
+    "Context pressure. Use `ContextUsage` — tokens held and money spent are different questions."
+  ],
+  "commonMistakes": [
+    "Showing the run cost with no session total, which removes the only context that makes it mean anything."
+  ],
   "specimens": [
     {
       "title": "CostMeter",
@@ -79,6 +89,5 @@
       "note": "What the run spent, against what the session has spent — two numbers, then the arithmetic under them. Every figure arrives pre-formatted: the element does no currency maths and no rounding, so a bench and a billing page cannot disagree about what `$3.12` means.",
       "interaction": "none. `share` drives the bar and the lines are given largest-first, so the bar reads left to right in the same order as the rows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cue-portal-frame.json

@@ -49,7 +49,7 @@
     "--cue-font-sans",
     "--cue-font-scale"
   ],
-  "summary": "Inline version of the portal contract, for portals whose container cannot be chosen (a third-party overlay, or content already portaled by something else).",
+  "summary": "Inline version of the portal contract, for portals whose container you cannot choose.",
   "examples": [
     {
       "title": "Usage",
@@ -57,9 +57,18 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cue-portal-frame",
   "mdUrl": "/docs/components/cue-portal-frame.md",
   "jsonUrl": "/r/components/cue-portal-frame.json",
-  "todo": true
+  "whenToUse": [
+    "A third-party overlay, or content already portalled by something else, that must still carry the theme, density, font, mode and style stamps."
+  ],
+  "whenNotToUse": [
+    "A portal you control. Prefer the `useCuePortalProps` hook — this exists for the case where you cannot reach the container."
+  ],
+  "commonMistakes": [
+    "Reaching for it first. It is the fallback, not the default, and wrapping in `display: contents` where the hook would do is one more element for nothing.",
+    "Stamping only `data-theme`. The contract is the whole set — theme, density, font, mode, style, skin, fidelity, font scale and overrides — or a portal renders half-themed."
+  ]
 }

package/manifest/components/data-table-pagination.json

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/data-table-pagination",
   "mdUrl": "/docs/components/data-table-pagination.md",
   "jsonUrl": "/r/components/data-table-pagination.json",
+  "whenToUse": [
+    "Any paged table.",
+    "Tables that get sorted to put the interesting row at one end — first and last exist because stepping there one page at a time is not a navigation strategy."
+  ],
+  "whenNotToUse": [
+    "A table short enough to scroll.",
+    "A non-table list. Use `Pagination`."
+  ],
+  "commonMistakes": [
+    "Rebuilding the buttons as bare glyphs. Every one is an `IconButton` with a real accessible name — an arrow alone announces as nothing."
+  ],
   "specimens": [
     {
       "title": "DataTable recipe",
@@ -92,6 +103,5 @@
       "note": "Not a component: `useCueTable` wires four TanStack v9 features, `DataTableToolbar` and `DataTablePagination` supply the chrome, and the markup stays at the call site. Rendered through the same Table above.",
       "interaction": "the header cells are buttons that toggle sorting; the pager disables at the ends rather than hiding."
     }
-  ],
-  "todo": true
+  ]
 }