@cueplusplus/ui 0.14.0 → 0.14.1

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

@@ -60,10 +60,21 @@
   ],
   "summary": "A slash command in the menu: its icon, `/name`, what it does, and the return key on the active row.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-command-item",
   "mdUrl": "/docs/components/composer-command-item.md",
   "jsonUrl": "/r/components/composer-command-item.json",
+  "whenToUse": [
+    "Each slash command offered in the composer menu.",
+    "The row Enter would run, which is the one that carries the return key."
+  ],
+  "whenNotToUse": [
+    "An entry that is not a runnable command. `command` takes a `ComposerCommand`."
+  ],
+  "commonMistakes": [
+    "Marking more than one row `active`. It is the row Enter would run, so exactly one carries it.",
+    "Drawing the return key hint yourself. It already appears on the active row."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -80,6 +91,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-context.json

@@ -51,10 +51,21 @@
   ],
   "summary": "The context-window dial in the toolbar, with the breakdown on hover or focus.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-context",
   "mdUrl": "/docs/components/composer-context.md",
   "jsonUrl": "/r/components/composer-context.json",
+  "whenToUse": [
+    "Showing how much of the context window has gone, and where, from the composer toolbar.",
+    "A usage readout that has to stay reachable by keyboard, since the breakdown opens on hover or focus."
+  ],
+  "whenNotToUse": [
+    "A generic progress meter. It is shaped around a `ComposerUsage` breakdown."
+  ],
+  "commonMistakes": [
+    "Adding a warning threshold of your own. It turns danger-coloured past 85%, which is the point where the next long tool result starts costing the conversation its own history.",
+    "Treating the dial as decoration and putting the breakdown out of keyboard reach. It opens on hover or focus."
+  ],
   "specimens": [
     {
       "title": "ComposerContext",
@@ -66,6 +77,5 @@
       "note": "The context window as a dial small enough to leave in the toolbar, with the arithmetic behind it on hover or focus. It turns the danger hue past 85% — the point where the next long tool result starts costing the conversation its own history rather than its headroom. Everything is in thousands of tokens and nothing is rounded here: the element divides, the caller counts.",
       "interaction": "the dial is a labelled button (`Context usage`) and the breakdown opens on hover *or* focus-within, so it is reachable from the keyboard without a click target that does nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-input.json

@@ -51,10 +51,19 @@
   ],
   "summary": "The text field.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-input",
   "mdUrl": "/docs/components/composer-input.md",
   "jsonUrl": "/r/components/composer-input.json",
+  "whenToUse": [
+    "The message field of a composer, where Enter submits."
+  ],
+  "whenNotToUse": [
+    "A field inside a multi-step form. Enter here sends the message."
+  ],
+  "commonMistakes": [
+    "Adding your own Enter handler on top of it. Submission is already guarded against IME composition, so accepting a candidate does not send — a hand-rolled handler loses that."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -72,6 +81,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-menu-item.json

@@ -50,10 +50,20 @@
   ],
   "summary": "One row of a `ComposerMenu`, and the chassis the command, person and model rows are built on.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu-item",
   "mdUrl": "/docs/components/composer-menu-item.md",
   "jsonUrl": "/r/components/composer-menu-item.json",
+  "whenToUse": [
+    "A row in a `ComposerMenu` that none of the built rows already covers."
+  ],
+  "whenNotToUse": [
+    "A command, a person or a model row, which are already built on this chassis."
+  ],
+  "commonMistakes": [
+    "Using `active` for selection. It says where the keyboard is, not what has been chosen.",
+    "Rebuilding the command, person or model rows from scratch. They are already built on this chassis."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -70,6 +80,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-menu.json

@@ -64,10 +64,21 @@
   ],
   "summary": "The popover the slash and mention menus are drawn in, anchored above the bar.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu",
   "mdUrl": "/docs/components/composer-menu.md",
   "jsonUrl": "/r/components/composer-menu.json",
+  "whenToUse": [
+    "Drawing the slash or mention menu over the composer.",
+    "Hanging the menu from either edge, with `align`."
+  ],
+  "whenNotToUse": [
+    "A menu that must unmount when closed. Closed is animated out, not unmounted.",
+    "A menu that should hang below the input. It is anchored above the bar."
+  ],
+  "commonMistakes": [
+    "Conditionally rendering it instead of toggling `open`. It animates open rather than mounting, so the caret never moves under it."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -84,6 +95,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-model-item.json

@@ -61,10 +61,21 @@
   ],
   "summary": "One model in the menu, with its metadata and a tick on the chosen one.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-model-item",
   "mdUrl": "/docs/components/composer-model-item.md",
   "jsonUrl": "/r/components/composer-model-item.json",
+  "whenToUse": [
+    "Each model offered in the composer's model menu.",
+    "Showing each model's metadata beside its name, rather than in a second column."
+  ],
+  "whenNotToUse": [
+    "A row whose entry is not a `ComposerModel`."
+  ],
+  "commonMistakes": [
+    "Drawing your own tick beside the current model. `selected` draws it.",
+    "Using `selected` as the keyboard cursor. It marks the model in use."
+  ],
   "specimens": [
     {
       "title": "ComposerModelTrigger / ComposerModelItem",
@@ -77,6 +88,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-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
+  ]
 }