@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/markdown-text.json

@@ -98,7 +98,7 @@
     "--cue-text-title",
     "--cue-text-ui"
   ],
-  "summary": "Model output, rendered.",
+  "summary": "Model output, rendered — the one component in this library that turns a string into markup.",
   "examples": [
     {
       "title": "Usage",
@@ -106,10 +106,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/markdown-text",
   "mdUrl": "/docs/components/markdown-text.md",
   "jsonUrl": "/r/components/markdown-text.json",
+  "whenToUse": [
+    "An assistant turn that is genuinely markdown. The input is assumed hostile, and the element subset, the attributes and the URL schemes are all enumerated rather than filtered.",
+    "The tail of a stream: `streaming` hides the token being typed, so no asterisks flicker through a bold run and no fence opens a code block for one frame."
+  ],
+  "whenNotToUse": [
+    "Any other text in the library. `Message`, `AskBox` and every other element place a string in the DOM as characters, because a component that quietly parsed would put every consumer one prompt away from an injection.",
+    "A console that renders transcripts without markdown. This lives at `@cueplusplus/ui/elements/markdown` and is deliberately not re-exported from `@cueplusplus/ui/elements`, so neither optional peer has to be installed."
+  ],
+  "commonMistakes": [
+    "Expecting tables, task lists or footnotes. No GFM plugin is enabled — an explicit autolink still works, the rest do not.",
+    "Reaching for raw HTML, or for control over `rel`. Markup in the source has no parser to reach it, and every link carries `noopener noreferrer nofollow` whatever `target` says.",
+    "Dropping a highlighter into `renderCodeBlock` without thinking. It is a second parser over the same untrusted string, usually one that emits HTML, which is why the default is a bare `pre`/`code` and opting in is a line somebody wrote."
+  ],
   "specimens": [
     {
       "title": "MarkdownText",
@@ -121,6 +134,5 @@
       "note": "The one component in the library that turns a string into markup, and the only one that has to be argued for. No raw HTML reaches the DOM — not filtered out, but never parsed: the img tag on the last line of the settled specimen is a real injection shape and renders as nothing. Links are http/https/mailto only and always carry rel='noopener noreferrer nofollow'; code blocks are plain text until a highlighter is passed. It ships from @cueplusplus/ui/elements/markdown so its parser and sanitizer stay off the elements barrel.",
       "interaction": "none — it is a document, and it stays selectable, copyable text. Headings start at h2 by default so a turn never claims a page's title, and links are keyboard-reachable with the house focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/math-block.json

@@ -61,10 +61,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/math-block",
   "mdUrl": "/docs/components/math-block.md",
   "jsonUrl": "/r/components/math-block.json",
+  "whenToUse": [
+    "A derivation an agent produces step by step, where `visibleSteps` says how much has been shown.",
+    "Working that needs an eyebrow above it — that is `label`, and it is optional."
+  ],
+  "whenNotToUse": [
+    "A string of TeX or any other notation to be parsed. Each step is a node, composed from the exported `Frac`, `Sup` and `Sub` helpers."
+  ],
+  "commonMistakes": [
+    "Appending to `steps` as the derivation lands. `steps` is the whole working and `visibleSteps` is the caller's counter over it.",
+    "Building exponents and bounds out of raw markup instead of the exported `Sup` and `Sub` helpers the component is designed around."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -79,6 +90,5 @@
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/mcp-server-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "An MCP server in the registry: a thing an agent connects *to*.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mcp-server-icon",
   "mdUrl": "/docs/components/mcp-server-icon.md",
   "jsonUrl": "/r/components/mcp-server-icon.json",
+  "whenToUse": [
+    "A catalogue row that is a running process somewhere, with an address and a session."
+  ],
+  "whenNotToUse": [
+    "Something installed and run locally. Use `CliToolIcon`.",
+    "A capability. Use `SkillIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a document. It is hardware — two rack units with a status lamp — because a row that looked like a file would hide the only fact about it that matters operationally."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +51,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/mcp-server-panel.json

@@ -82,10 +82,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mcp-server-panel",
   "mdUrl": "/docs/components/mcp-server-panel.md",
   "jsonUrl": "/r/components/mcp-server-panel.json",
+  "whenToUse": [
+    "A status surface listing every configured MCP server, connected or not — the header counts how many are live.",
+    "A server stuck on authorisation: `onAuthorize` is what puts the Authorize button on that row, and it is shown only while a server needs auth."
+  ],
+  "whenNotToUse": [
+    "A layout where several servers must be open at once. Only one expands at a time — `expandedId` is a single id, not a set."
+  ],
+  "commonMistakes": [
+    "Filtering `servers` down to the connected ones. The list is every configured server, and the header's live count is derived from the whole of it.",
+    "Holding a set of expanded ids in state. `onToggle` reports one id, and omitting `expandedId` entirely gives an all-collapsed list."
+  ],
   "specimens": [
     {
       "title": "McpServerPanel",
@@ -97,6 +108,5 @@
       "note": "Which servers are connected, what each one brought, and which is still waiting on you. The header counts the live ones against the configured ones, and the status dot has a `sr-only` word beside it — a colour is not a status for everybody. Authorize only exists on a server that needs it, so the row that wants something from you is the only one offering an action.",
       "interaction": "each server row carries `aria-expanded`; one expands at a time, and `expandedId` undefined is a legitimate all-collapsed state rather than a missing value."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/memory-chips.json

@@ -53,10 +53,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/memory-chips",
   "mdUrl": "/docs/components/memory-chips.md",
   "jsonUrl": "/r/components/memory-chips.json",
+  "whenToUse": [
+    "Showing the facts a turn just wrote to memory, with the new ones tinted apart from what was already known."
+  ],
+  "whenNotToUse": [
+    "A settings screen for everything stored across all threads. These chips are what the turn wrote, marked new or existing."
+  ],
+  "commonMistakes": [
+    "Leaving the existing mark off chips that were already remembered. Anything not marked existing is counted as new this turn and tinted, so a restored list lights up entirely.",
+    "Offering removal only for old facts. Every chip is removable through `onForget`, including the ones it just learned."
+  ],
   "specimens": [
     {
       "title": "MemoryChips",
@@ -68,6 +78,5 @@
       "note": "What it now remembers about you, written during the turn it learned it. The header counts what is new rather than what is stored — `remembered 2` is the fact worth showing — and anything not marked `existing` takes the streaming hue so a new memory is visibly new. Every chip is removable, including the one it just learned, which is the only version of this control that is honest.",
       "interaction": "each chip's remove button is labelled with the fact it would forget — `Forget ESPRITEs run in mode 8` — so the control names its consequence rather than saying 'remove'."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/menubar.json

@@ -154,7 +154,8 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "The desktop-application menu bar: a row of words, each dropping a menu.",
   "examples": [
@@ -164,10 +165,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/menubar",
   "mdUrl": "/docs/components/menubar.md",
   "jsonUrl": "/r/components/menubar.json",
+  "whenToUse": [
+    "A desktop-shaped app with more commands than a toolbar can hold.",
+    "Anywhere the bar behaviour — hover to switch once one is open, arrow keys across, typeahead inside — should come from the primitive."
+  ],
+  "whenNotToUse": [
+    "Site navigation. Use `NavigationMenu`; its rows are links, not commands.",
+    "A handful of actions. Use `Toolbar`."
+  ],
+  "commonMistakes": [
+    "Building it from separate `DropdownMenu`s, which loses the bar-level behaviour that makes a menubar feel native."
+  ],
   "specimens": [
     {
       "title": "Menubar",
@@ -179,6 +191,5 @@
       "note": "The desktop bar: once one menu is open, hovering the next one opens it.",
       "interaction": "left and right arrows move between menus, up and down move inside one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-actions.json

@@ -97,7 +97,7 @@
     "--cue-ok",
     "--cue-surface-2"
   ],
-  "summary": "Copy, rate, and regenerate.",
+  "summary": "Copy, rate and regenerate, each confirming itself with a small state change.",
   "examples": [
     {
       "title": "Usage",
@@ -105,10 +105,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-actions",
   "mdUrl": "/docs/components/message-actions.md",
   "jsonUrl": "/r/components/message-actions.json",
+  "whenToUse": [
+    "The action row under an assistant turn in a product that has all four: copy, thumbs, regenerate and an overflow menu."
+  ],
+  "whenNotToUse": [
+    "A row where only some of the actions apply. Every callback here is required, so a product without rating or regeneration would still draw those controls."
+  ],
+  "commonMistakes": [
+    "Setting `copied` on the press and never clearing it. The green check is caller state, so it stays until you reset it.",
+    "Treating `reaction` as a boolean. It is the active thumbs reaction or `null`, and `onReactionChange` reports the toggle.",
+    "Driving `regenerating` from a timer rather than the run. The icon spins to show work in progress and knows nothing about when it ends."
+  ],
   "specimens": [
     {
       "title": "MessageActions",
@@ -120,6 +131,5 @@
       "note": "The row under an answer: copy, rate it, run it again, or ask for more. Every action confirms itself in place — copy swaps to a check and turns green, a rating latches, regenerate spins while it is out — so nothing needs a toast to say it worked.",
       "interaction": "all five are named icon buttons; the two ratings carry aria-pressed and toggle off when pressed again. The copy swap is a crossfade between two icons in one cell, not a re-mount."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-attachments.json

@@ -51,10 +51,20 @@
   ],
   "summary": "The files a turn carried, as received rather than as staged.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-attachments",
   "mdUrl": "/docs/components/message-attachments.md",
   "jsonUrl": "/r/components/message-attachments.json",
+  "whenToUse": [
+    "Attachments on a turn that has already been sent: images render as a thumbnail row, everything else as a chip."
+  ],
+  "whenNotToUse": [
+    "The staging area in a composer. These are files as received, not files being picked."
+  ],
+  "commonMistakes": [
+    "Expecting the size or a document's page count to be computed. The row draws what each attachment item carries.",
+    "Omitting `onOpen` and expecting a preview tile to open. Opening an attachment for preview is the caller's."
+  ],
   "specimens": [
     {
       "title": "MessageAttachments",
@@ -66,6 +76,5 @@
       "note": "Files as received, not as staged: an image gets a preview tile that opens, a document gets its page count, anything else gets its size. Upstream's uploader lives in the composer — this is the read-only other end of it.",
       "interaction": "every row is one button with its name as the label; the image tile grows very slightly under the pointer, and holds still under reduced motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-branches.json

@@ -63,10 +63,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-branches",
   "mdUrl": "/docs/components/message-branches.md",
   "jsonUrl": "/r/components/message-branches.json",
+  "whenToUse": [
+    "A turn that has been regenerated more than once, where the reader should be able to step back to the answer they preferred."
+  ],
+  "whenNotToUse": [
+    "Choosing what to re-run the turn with. This steps through answers that already exist; it produces nothing."
+  ],
+  "commonMistakes": [
+    "Keeping only the current answer in state. `variants` is the whole set of alternates — dropping the earlier ones is exactly the losing-your-place this row exists to prevent.",
+    "Letting `index` run past the end of `variants`. The component is controlled: `onIndexChange` only reports which control was pressed."
+  ],
   "specimens": [
     {
       "title": "MessageBranches",
@@ -78,6 +88,5 @@
       "note": "Two answers to the same question, and a way through them that does not lose your place. The counter is the whole affordance — `2 / 2` is what tells you a second version exists at all — and it wraps at both ends rather than dead-ending.",
       "interaction": "both arrows are named and go disabled when there is only one version, which is the honest state for a turn nobody has regenerated."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-list.json

@@ -101,10 +101,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-list",
   "mdUrl": "/docs/components/message-list.md",
   "jsonUrl": "/r/components/message-list.json",
+  "whenToUse": [
+    "Any streaming transcript.",
+    "Anywhere the reader must be able to scroll back mid-stream without being yanked forward."
+  ],
+  "whenNotToUse": [
+    "A static conversation. A `Stack` of `Message`s is enough."
+  ],
+  "commonMistakes": [
+    "Treating following as a scroll position rather than a mode. It is a mode: pinned to the bottom it follows, and scrolling up hands control back and offers a 'jump to latest' pill — because a stream that yanks the viewport mid-sentence is the single most common reason people stop reading a chat."
+  ],
   "specimens": [
     {
       "title": "MessageList",
@@ -116,6 +126,5 @@
       "note": "A stick-to-bottom scroller. Scroll away and it offers to jump back to the latest rather than yanking you there.",
       "interaction": "the jump control is a button, and it appears only once you have actually scrolled off the tail."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-pair.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-pair",
   "mdUrl": "/docs/components/message-pair.md",
   "jsonUrl": "/r/components/message-pair.json",
+  "whenToUse": [
+    "A single exchange rendered as one unit — a preview tile, a demo, a bench frame — where the reply arrives word by word."
+  ],
+  "whenNotToUse": [
+    "A transcript of many turns. This is one pair, and the assistant side is a `words` array with a `visibleWords` counter rather than children you compose."
+  ],
+  "commonMistakes": [
+    "Leaving `streaming` true once `visibleWords` reaches the end, so a settled reply keeps its newest words tinted blue.",
+    "Restyling the user bubble away with classes instead of `variant=\"flat\"`, which renders it as plain right-aligned text."
+  ],
   "specimens": [
     {
       "title": "MessagePair",
@@ -102,6 +112,5 @@
       "note": "A whole turn in one element: what was asked, and the answer streaming under it with its actions waiting on hover. The two variants are the two house styles for a user turn — a bubble, or right-aligned text with no chrome at all.",
       "interaction": "the action row is invisible until the turn is hovered *or* focused, which is what keeps a keyboard from losing it. Both buttons are named."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-queue.json

@@ -65,10 +65,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-queue",
   "mdUrl": "/docs/components/message-queue.md",
   "jsonUrl": "/r/components/message-queue.json",
+  "whenToUse": [
+    "Showing what will send once the current run finishes, with the in-flight turn above the queue."
+  ],
+  "whenNotToUse": [
+    "A queue with nothing running. `running` is required, and the component is built around a turn in flight.",
+    "A queue whose entries should be rewritten or jumped before they send. The only thing this offers is `onCancel`."
+  ],
+  "commonMistakes": [
+    "Re-sorting `queued` before passing it. The order is the order the turns will drain in.",
+    "Wiring `onCancel` to stop the run. It removes a queued turn before it ever sends; the turn shown above is not cancellable from here."
+  ],
   "specimens": [
     {
       "title": "MessageQueue",
@@ -80,6 +91,5 @@
       "note": "What you typed while the last run was still out. The turn in flight pings at the top; everything behind it is numbered, cancellable and explicitly told when it will go. A queue that did not say 'sends when this finishes' would look like a list of failures.",
       "interaction": "each row's × is a named button — the message text is in the label, so five rows do not all read as 'Remove'."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-timing.json

@@ -49,10 +49,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-timing",
   "mdUrl": "/docs/components/message-timing.md",
   "jsonUrl": "/r/components/message-timing.json",
+  "whenToUse": [
+    "Under a finished turn, where the reader should be able to see what it cost.",
+    "During a stream: show fewer stats and set `streaming`, which tints the values while they are still moving."
+  ],
+  "whenNotToUse": [
+    "Raw numbers. `stats` are label and value pairs, pre-formatted — there is no rounding, no unit and no currency here."
+  ],
+  "commonMistakes": [
+    "Passing the full set of stats while the turn is still streaming. The intended shape is fewer during, the full set once it settles.",
+    "Leaving `streaming` on after the turn lands, so settled values stay tinted as if they were still moving."
+  ],
   "specimens": [
     {
       "title": "MessageTiming",
@@ -64,6 +75,5 @@
       "note": "What the turn cost, in the footer where a reader can ignore it. The values are strings the caller already formatted; while the turn is still streaming they sit in the live hue and settle into ink when it lands, so the row doubles as a state.",
       "interaction": "none. It is four label/value pairs in mono, tabular so the numbers do not jitter as they update."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message.json

@@ -119,7 +119,8 @@
     "--cue-space-4",
     "--cue-surface-1",
     "--cue-text-body",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps"
   ],
   "summary": "One turn in a conversation.",
   "examples": [
@@ -129,10 +130,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message",
   "mdUrl": "/docs/components/message.md",
   "jsonUrl": "/r/components/message.json",
+  "whenToUse": [
+    "Any transcript turn — a user's, an agent's, a tool's.",
+    "Anywhere authorship, timestamp and pending state should be drawn consistently."
+  ],
+  "whenNotToUse": [
+    "A delegated sub-run. Use `DelegationCard`, which folds it."
+  ],
+  "commonMistakes": [
+    "Expecting it to render markdown. Content is React nodes, verbatim, on purpose: model output is untrusted text, and a component that quietly parsed it would make every consumer one prompt away from an injection. Pass your own renderer and own that decision."
+  ],
   "specimens": [
     {
       "title": "Message",
@@ -144,6 +155,5 @@
       "note": "Three roles. The bubble radii are asymmetric and mirrored by role, and the author line is mono micro. Nothing here parses markdown: model output is an untrusted string, and a component that rendered it as markup would make every consumer one prompt away from an injection.",
       "interaction": "none. A message is a record."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/mobile-composer.json

@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mobile-composer",
   "mdUrl": "/docs/components/mobile-composer.md",
   "jsonUrl": "/r/components/mobile-composer.json",
+  "whenToUse": [
+    "A composer on a phone — the field is 16px so iOS does not zoom on focus, and the quick actions scroll horizontally above it.",
+    "A run in flight: `running` swaps send for stop and suppresses Return-to-send."
+  ],
+  "whenNotToUse": [
+    "A desktop composer. The layout carries a home-indicator inset and collapses its quick actions when the keyboard is up."
+  ],
+  "commonMistakes": [
+    "Passing `actions` without `onAction`. The chips render disabled, because `actions` is required and the row would otherwise be inert — the same is true of `onAttach` and its control.",
+    "Guessing at the keyboard from the viewport instead of driving `keyboardOpen` from `onFocus`, which is the callback given for exactly that.",
+    "Leaving `running` false during a run, so Return still sends and the stop control never appears."
+  ],
   "specimens": [
     {
       "title": "MobileComposer",
@@ -158,6 +170,5 @@
       "note": "The same composer on a phone: a bottom sheet with thumb-sized targets, quick actions scrolling above the field, and a 16px input so iOS does not zoom when it takes focus. `keyboardOpen` is the whole layout switch — the quick actions and the home-indicator inset both belong to the state where the keyboard is down.",
       "interaction": "send becomes stop while a run is in flight, and Return stops sending — a second send during a stream is almost always a mistake, so the element refuses it rather than queueing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/model-picker.json

@@ -67,10 +67,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/model-picker",
   "mdUrl": "/docs/components/model-picker.md",
   "jsonUrl": "/r/components/model-picker.json",
+  "whenToUse": [
+    "A picker over every model on offer, where price and capability are part of the choice."
+  ],
+  "whenNotToUse": [
+    "Two or three models in a settings row. This is the full list, and a family of one is a heading over a single row."
+  ],
+  "commonMistakes": [
+    "Grouping or sorting `models` by family before passing them. Families are derived from the entries and keep their first-seen order, so the order you pass is the order you get.",
+    "Passing `selectedId` without `onSelect` on a picker meant to change the model — the id alone only marks which one is active."
+  ],
   "specimens": [
     {
       "title": "ModelPicker",
@@ -82,6 +92,5 @@
       "note": "The full list rather than the rail: grouped by family, priced, and carrying what each one can actually do. This is the screen `ComposerModelTrigger` is a shortcut to, and the split is the point — the toolbar menu is for switching between models you already chose between, and this is where that choosing happens.",
       "interaction": "each row is `aria-pressed`, which is the honest role for a control that stays chosen rather than performing an action once."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/multi-select.json

@@ -225,9 +225,10 @@
     "--cue-text-body",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "Several values out of a known set, each shown as a removable chip.",
+  "summary": "Several values out of a known set, each shown as a removable chip inside the field.",
   "examples": [
     {
       "title": "Usage",
@@ -235,10 +236,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/multi-select",
   "mdUrl": "/docs/components/multi-select.md",
   "jsonUrl": "/r/components/multi-select.json",
+  "whenToUse": [
+    "A selection the user needs to see in full: assignees, fixtures, channels.",
+    "Anywhere the size of the selection is information. Nine trusses render nine chips tall, so the field is honest about how much has been chosen."
+  ],
+  "whenNotToUse": [
+    "Values the product cannot enumerate. Use `TagsInput`, which commits whatever is typed.",
+    "Exactly one value. Use `Select` or `Combobox`.",
+    "A set small enough to show at once. A `CheckboxGroup` shows every option without an open-close cycle."
+  ],
+  "commonMistakes": [
+    "Giving the field a fixed height. It takes `min-h-control-*` on purpose; a fixed height reintroduces the hidden overflow the chips exist to avoid.",
+    "Collapsing the chips behind a `+6 more`. That hides the selection the user came to check."
+  ],
   "specimens": [
     {
       "title": "MultiSelect",
@@ -250,6 +264,5 @@
       "note": "Several values in one control, rendered as removable chips.",
       "interaction": "each chip's remove button has its own accessible name; Backspace removes the last one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/musical-time-input.json

@@ -121,10 +121,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/musical-time-input",
   "mdUrl": "/docs/components/musical-time-input.md",
   "jsonUrl": "/r/components/musical-time-input.json",
+  "whenToUse": [
+    "Any position or length in musical time."
+  ],
+  "whenNotToUse": [
+    "Wall-clock time. Use a time field."
+  ],
+  "commonMistakes": [
+    "Using a `NumberField` instead. That asks for 4.25 and means 'bar 2, beat 1, one sixteenth in' — a conversion the musician has to do in their head every time. Three segments, each stepping in its own musical unit, does it instead."
+  ],
   "specimens": [
     {
       "title": "MusicalTimeInput",
@@ -136,6 +145,5 @@
       "note": "`bars.beats.sixteenths` as three segments, time-signature aware, with the total-beats readout beside it.",
       "interaction": "arrow keys and the scroll wheel step the segment under the caret; Tab moves between segments and overflow carries into the next one."
     }
-  ],
-  "todo": true
+  ]
 }