@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/skeleton.json

@@ -18,7 +18,7 @@
     "--cue-radius-control",
     "--cue-surface-2"
   ],
-  "summary": "A loading placeholder block.",
+  "summary": "A loading placeholder block. It carries no intrinsic size — give it the shape of what is arriving.",
   "examples": [
     {
       "title": "Usage",
@@ -26,10 +26,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/skeleton",
   "mdUrl": "/docs/components/skeleton.md",
   "jsonUrl": "/r/components/skeleton.json",
+  "whenToUse": [
+    "Content whose layout you already know, so the page does not jump when it lands: a row of cells, an avatar and two lines of text.",
+    "Waits long enough to notice but short enough that a spinner would feel heavier than the content itself."
+  ],
+  "whenNotToUse": [
+    "An indeterminate wait with no known shape. Use `Spinner`.",
+    "An empty result. Nothing is arriving, so say so — a skeleton promises content that never comes."
+  ],
+  "commonMistakes": [
+    "Rendering one with no `className`. It has no size of its own and collapses to nothing.",
+    "Sizing it differently from the real content, which turns the skeleton into the layout shift it exists to prevent.",
+    "Adding your own `aria-label`. It is `aria-hidden` on purpose — the surrounding live region should say 'loading', not a fleet of empty boxes."
+  ],
   "specimens": [
     {
       "title": "Skeleton",
@@ -41,6 +54,5 @@
       "note": "The shape of content that has not arrived. Sized by the caller, because only the caller knows the shape.",
       "interaction": "the shimmer stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/skill-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "A skill: the thing every other container in this set holds.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/skill-icon",
   "mdUrl": "/docs/components/skill-icon.md",
   "jsonUrl": "/r/components/skill-icon.json",
+  "whenToUse": [
+    "Marking a capability an agent gains — in a catalogue row, a stack, a search result."
+  ],
+  "whenNotToUse": [
+    "The file a skill travels in. That is an implementation detail, not the thing.",
+    "A container of skills. Use `FolderIcon`, `StackIcon` or `CatalogueIcon`."
+  ],
+  "commonMistakes": [
+    "Substituting a page or document glyph, which makes the catalogue look like a folder of documents rather than a list of things an agent can now do."
+  ],
   "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/slider.json

@@ -86,10 +86,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/slider",
   "mdUrl": "/docs/components/slider.md",
   "jsonUrl": "/r/components/slider.json",
+  "whenToUse": [
+    "A value judged by feel against its range — intensity, a fade time, a threshold.",
+    "Anywhere the shape of the range matters as much as the number."
+  ],
+  "whenNotToUse": [
+    "A number that must be exact. Use `NumberField`; a 2px rail is a readout first and a grab target second.",
+    "A value with no meaningful minimum or maximum."
+  ],
+  "commonMistakes": [
+    "Writing every `onValueChange` into undo history. `onCommit` is the important half of this API — it is what lets a whole drag coalesce into one undo entry instead of hundreds.",
+    "Adding a separate number readout instead of `showValue`."
+  ],
   "specimens": [
     {
       "title": "Slider / RangeSlider",
@@ -101,6 +113,5 @@
       "note": "One thumb or two. `onCommit` fires once at the end of a drag, which is the undo-coalescing contract the consoles need.",
       "interaction": "the thumb grows while dragging; arrow keys step, Page Up and Page Down jump."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sources.json

@@ -77,10 +77,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sources",
   "mdUrl": "/docs/components/sources.md",
   "jsonUrl": "/r/components/sources.json",
+  "whenToUse": [
+    "Citations under an answer, out of the way until the reader wants them."
+  ],
+  "whenNotToUse": [
+    "A component expected to own its own disclosure. `open` and `onOpenChange` are both required."
+  ],
+  "commonMistakes": [
+    "Passing `open` and no `onOpenChange`, or the reverse. Both are required and the pill does not toggle itself.",
+    "Rendering the source cards separately and using this only for the pill. The cards are the expanded state of the same component."
+  ],
   "specimens": [
     {
       "title": "Sources",
@@ -92,6 +102,5 @@
       "note": "Citations folded into a pill until somebody wants them. Collapsed it is a count — four sources, no argument; open it is a scannable grid of cards, one per site, each lifting a pixel under the pointer. The count is the whole affordance: it says provenance exists without spending a paragraph on it.",
       "interaction": "the pill is the trigger and takes cue's focus ring; the chevron turns with the panel, which animates its own height through Base UI rather than a max-height guess."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sparkline.json

@@ -61,7 +61,7 @@
     "--cue-danger",
     "--cue-warn"
   ],
-  "summary": "A tiny unlabelled trace: \"is this climbing, or did it just reset?\".",
+  "summary": "A tiny unlabelled trace: 'is this climbing, or did it just reset?'",
   "examples": [
     {
       "title": "Usage",
@@ -69,10 +69,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sparkline",
   "mdUrl": "/docs/components/sparkline.md",
   "jsonUrl": "/r/components/sparkline.json",
+  "whenToUse": [
+    "Direction and shape beside a number that already carries the magnitude.",
+    "A dense row or tile where a real chart would not fit and would not be read."
+  ],
+  "whenNotToUse": [
+    "A value the reader must quantify. It answers nothing but shape — the numbers belong to the `Stat` or the row above it.",
+    "A series with a meaningful ceiling other than 100."
+  ],
+  "commonMistakes": [
+    "Auto-scaling it to its own range. The scale is always 0–100 on purpose: a trace scaled to itself makes a flat 3% look identical to a flat 95%, which is the exact misreading a sparkline exists to prevent."
+  ],
   "specimens": [
     {
       "title": "Sparkline",
@@ -84,6 +95,5 @@
       "note": "A trend at row height, drawn as one path with no axes and no tooltip. When it needs either, reach for UsageChart.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/speaker-identity.json

@@ -46,10 +46,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/speaker-identity",
   "mdUrl": "/docs/components/speaker-identity.md",
   "jsonUrl": "/r/components/speaker-identity.json",
+  "whenToUse": [
+    "A transcript with more than two participants — several models, several agents — where each turn has to name who produced it."
+  ],
+  "whenNotToUse": [
+    "A plain user-and-assistant exchange, where naming every turn is noise."
+  ],
+  "commonMistakes": [
+    "Passing turns out of order. The prop is turns in order, each naming its own speaker, and the component derives nothing else."
+  ],
   "specimens": [
     {
       "title": "SpeakerIdentity",
@@ -61,6 +70,5 @@
       "note": "Who is talking, once a thread holds more than a user and one model. Four kinds — you, the agent, a subagent it delegated to, and a tool that answered — with the subagent's badge rounded so a delegated turn reads as delegated at a glance. `detail` is the second fact the name needs: which model spoke, or how long the tool took.",
       "interaction": "none. It is a transcript, not a control; the badges are the only thing distinguishing four voices that would otherwise be four paragraphs."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spec-sheet.json

@@ -65,7 +65,7 @@
     "--cue-text-body",
     "--cue-text-ui"
   ],
-  "summary": "The most common structured answer after a table: one object, labeled.",
+  "summary": "The most common structured answer after a table: one object, labelled.",
   "examples": [
     {
       "title": "Usage",
@@ -73,10 +73,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spec-sheet",
   "mdUrl": "/docs/components/spec-sheet.md",
   "jsonUrl": "/r/components/spec-sheet.json",
+  "whenToUse": [
+    "One object's attributes as an answer — a model, a SKU, a version — with `subtitle` carrying the identifier."
+  ],
+  "whenNotToUse": [
+    "Several objects compared side by side. This is one object, as label and value pairs."
+  ],
+  "commonMistakes": [
+    "Passing raw numbers and expecting formatting. Values are pre-formatted and right-aligned on tabular figures.",
+    "Slicing `rows` to what has landed. `visibleCount` is that, and `rows` is the whole sheet."
+  ],
   "specimens": [
     {
       "title": "SpecSheet",
@@ -88,6 +98,5 @@
       "note": "One object, labelled — the commonest structured answer after a table. Labels sit in mono on the leading edge and values in tabular figures on the trailing one, so a column of numbers lines up even though nothing here is a table. `emphasis` promotes the one row that answers the question.",
       "interaction": "none. `visibleCount` is what makes it arrive a row at a time instead of appearing whole."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spectrum-visualizer.json

@@ -127,10 +127,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spectrum-visualizer",
   "mdUrl": "/docs/components/spectrum-visualizer.md",
   "jsonUrl": "/r/components/spectrum-visualizer.json",
+  "whenToUse": [
+    "Any live audio analyser."
+  ],
+  "whenNotToUse": [
+    "A waveform or a level meter — a spectrum answers frequency, not amplitude over time."
+  ],
+  "commonMistakes": [
+    "Passing a colour per band. Colours are deliberately off the caller's hands: the original API asked for one and defaulted to `#00FF00` when it did not get one, which is how an audio tool ends up with two different greens for the same band in two different panels."
+  ],
   "specimens": [
     {
       "title": "SpectrumVisualizer",
@@ -142,6 +151,5 @@
       "note": "Bars or line, with band colours taken from the /charts ramps. Those are literals on purpose: a listener who has learnt `bass is red` must not relearn it because the console switched accent.",
       "interaction": "a selection dims the bands outside it rather than hiding them; thresholds are dashed rules per band."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spinner.json

@@ -43,7 +43,7 @@
     "--cue-icon-md",
     "--cue-icon-sm"
   ],
-  "summary": "An indeterminate progress ring, drawn in CSS only — no SVG, no animation library, one element.",
+  "summary": "An indeterminate progress ring, drawn in CSS only — one element, no SVG, no animation library.",
   "examples": [
     {
       "title": "Usage",
@@ -51,10 +51,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spinner",
   "mdUrl": "/docs/components/spinner.md",
   "jsonUrl": "/r/components/spinner.json",
+  "whenToUse": [
+    "A wait whose length and shape you cannot predict: a request in flight, a job whose progress is not reported.",
+    "Inside another control. It inks with `currentColor`, so a spinner in a `danger` button is red without being told."
+  ],
+  "whenNotToUse": [
+    "A wait with known structure. Use `Skeleton`, which holds the layout as well as the attention.",
+    "Progress you can actually measure. A ring that spins forever tells a reader less than a bar that moves."
+  ],
+  "commonMistakes": [
+    "Colouring it directly instead of letting it inherit. `currentColor` is the whole reason it works in every context.",
+    "Overriding `label` with something the surrounding live region already says, which announces the wait twice.",
+    "Assuming reduced motion hides it. The rotation stops and the ring stays as a static arc — the wait is still visible."
+  ],
   "specimens": [
     {
       "title": "Spinner",
@@ -66,6 +79,5 @@
       "note": "Two sizes. Carries a visually hidden label so a screen reader is told the wait, not left with a spinning div.",
       "interaction": "stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stack-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "One person's stack: the set of things they have actually installed.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stack-icon",
   "mdUrl": "/docs/components/stack-icon.md",
   "jsonUrl": "/r/components/stack-icon.json",
+  "whenToUse": [
+    "An accumulation — where the order things went in is part of what it is."
+  ],
+  "whenNotToUse": [
+    "A container things are filed into. Use `FolderIcon`.",
+    "Every stack at once. Use `StacksMatrixIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a box. The plates seen edge-on are the layers idiom, and a stack is an accumulation rather than a container."
+  ],
   "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/stack.json

@@ -123,10 +123,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stack",
   "mdUrl": "/docs/components/stack.md",
   "jsonUrl": "/r/components/stack.json",
+  "whenToUse": [
+    "Any run of siblings that needs consistent spacing — which is almost every layout in the system.",
+    "Anywhere spacing should track density: `gap={4}` is 8px at normal and 6px at ultra-compact without touching the markup."
+  ],
+  "whenNotToUse": [
+    "Two-dimensional layout. Use `Grid`.",
+    "A single child. The wrapper buys nothing."
+  ],
+  "commonMistakes": [
+    "Writing `flex gap-2` by hand instead. That is the exact opt-out this exists to prevent — it pins the spacing to a pixel value and stops tracking the density ladder.",
+    "Reaching for `gap` values outside the ladder, which reintroduces the per-call-site guess."
+  ],
   "specimens": [
     {
       "title": "Stack",
@@ -138,6 +150,5 @@
       "note": "Flex with the gap taken from a rung of the density ladder, never a length. That is what makes a layout tighten with the rest of the console.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stacks-matrix-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "Every stack at once, one column each: who has what, read across.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stacks-matrix-icon",
   "mdUrl": "/docs/components/stacks-matrix-icon.md",
   "jsonUrl": "/r/components/stacks-matrix-icon.json",
+  "whenToUse": [
+    "A two-axis question — 'which of these does that person not have'."
+  ],
+  "whenNotToUse": [
+    "One stack. Use `StackIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing more plates instead. The head rule and the name column are what make it a matrix rather than a grid, and the question it answers has two axes."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
       "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stat.json

@@ -91,10 +91,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stat",
   "mdUrl": "/docs/components/stat.md",
   "jsonUrl": "/r/components/stat.json",
+  "whenToUse": [
+    "A reading that deserves its own tile, in a row that scans as a list of captions with values underneath.",
+    "Numbers that change in place — the value is `tabular-nums` mono, so a ticking figure does not shuffle the layout."
+  ],
+  "whenNotToUse": [
+    "A table of numbers. Use a data table; a wall of tiles is harder to compare than a column.",
+    "A trend. Pair it with `Sparkline`, which answers direction, not magnitude."
+  ],
+  "commonMistakes": [
+    "Tinting the caption as well as the value. Only the value takes the tone — tinting both turns a red tile into an alarm rather than a reading.",
+    "Leading with the number. It reads label-first on purpose."
+  ],
   "specimens": [
     {
       "title": "Stat",
@@ -106,6 +118,5 @@
       "note": "A label, a figure and a detail line. Figures are mono `tabular-nums`, so a changing digit never shifts the column.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/status-dot.json

@@ -69,7 +69,7 @@
     "--cue-ok",
     "--cue-warn"
   ],
-  "summary": "A 6px state dot — the densest possible status indicator.",
+  "summary": "A 6px state dot — the densest possible status indicator, announced as well as shown.",
   "examples": [
     {
       "title": "Usage",
@@ -77,10 +77,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/status-dot",
   "mdUrl": "/docs/components/status-dot.md",
   "jsonUrl": "/r/components/status-dot.json",
+  "whenToUse": [
+    "State on a row where a `Chip` would not fit: a table of connections, a device list, a queue.",
+    "Live activity. `pulse` signals it, and stills itself under `prefers-reduced-motion`."
+  ],
+  "whenNotToUse": [
+    "State that needs a word to be understood. Use `Chip`, which shows the same tone vocabulary with its label visible.",
+    "A decorative bullet. Every dot emits an `sr-only` label inside a `role=\"status\"` wrapper, so a decorative one is noise in the accessibility tree."
+  ],
+  "commonMistakes": [
+    "Relying on the colour and adding a visible label beside it too, which announces the state twice. Pass `label` instead, or use a `Chip`.",
+    "Stripping the `relative` wrapper as redundant. It is the containing block for the `sr-only` label; without it that absolutely-positioned text escapes to `<html>`, and two thousand rows make the document thousands of pixels taller than anything on screen.",
+    "Passing a tone outside the shared vocabulary. `tone` is required and `idle` is the hollow ring, not a missing value."
+  ],
   "specimens": [
     {
       "title": "StatusDot",
@@ -92,6 +105,5 @@
       "note": "Five states, and the pulse that means work is in flight. The label is the accessible name, not decoration.",
       "interaction": "none. A dot is a readout."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stepper.json

@@ -79,7 +79,7 @@
     "--cue-space-3",
     "--cue-text-label"
   ],
-  "summary": "The step trail: `1 target · 2 preview · 3 apply`.",
+  "summary": "The step trail: `1 target · 2 preview · 3 apply`, as one line of mono text.",
   "examples": [
     {
       "title": "Usage",
@@ -87,10 +87,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stepper",
   "mdUrl": "/docs/components/stepper.md",
   "jsonUrl": "/r/components/stepper.json",
+  "whenToUse": [
+    "A wizard where the user needs to know how far along they are and what is left.",
+    "Anywhere vertical space belongs to the thing being configured rather than the chrome around it."
+  ],
+  "whenNotToUse": [
+    "Navigation. Use `Breadcrumb` — a stepper is progress through a task, not a location in a tree.",
+    "Two steps. A trail of two is a heading with extra parts."
+  ],
+  "commonMistakes": [
+    "Replacing it with numbered discs joined by rules. That is 60px tall and says exactly as much as one line of 9px type.",
+    "Accenting the whole trail. Only the numbers carry the accent, so it reads as one sentence with the position marked."
+  ],
   "specimens": [
     {
       "title": "Stepper",
@@ -102,6 +114,5 @@
       "note": "The step trail: `1 target · 2 preview · 3 apply`, with reached steps tinted rather than filled.",
       "interaction": "a reached step is a button; an upcoming one is not."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stopped-run.json

@@ -69,7 +69,7 @@
     "--cue-text-body",
     "--cue-text-ui"
   ],
-  "summary": "You pressed stop.",
+  "summary": "You pressed stop: the half-written answer stays, and continuing is one tap away.",
   "examples": [
     {
       "title": "Usage",
@@ -77,10 +77,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stopped-run",
   "mdUrl": "/docs/components/stopped-run.md",
   "jsonUrl": "/r/components/stopped-run.json",
+  "whenToUse": [
+    "Any early end to a run — stopped by you, the token limit, a timeout — with `reason` saying which."
+  ],
+  "whenNotToUse": [
+    "A run that finished. The component is built around a partial answer that stays on screen."
+  ],
+  "commonMistakes": [
+    "Clearing the words when the run stops. The partial answer staying is what makes continuing possible.",
+    "Wiring `onContinue` to restart the turn. It resumes from where the answer left off."
+  ],
   "specimens": [
     {
       "title": "StoppedRun",
@@ -92,6 +102,5 @@
       "note": "You pressed stop. The half-written answer stays exactly where it stopped, with a caret to say so, and the run gives its reason on a chip. Continuing is one tap; discarding is the quieter of the two, which is the right ranking.",
       "interaction": "Continue leads and carries the arrow; Discard is a ghost. Both are ordinary buttons — nothing here is a destructive-action dialog."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/streaming-text.json

@@ -62,10 +62,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/streaming-text",
   "mdUrl": "/docs/components/streaming-text.md",
   "jsonUrl": "/r/components/streaming-text.json",
+  "whenToUse": [
+    "An assistant turn arriving word by word, with inline code chips marked mono on their segment."
+  ],
+  "whenNotToUse": [
+    "Markdown. Segments are text chunks with an optional mono flag; nothing here parses."
+  ],
+  "commonMistakes": [
+    "Counting characters. `count` is how many words from the flattened segments are visible.",
+    "Leaving `streaming` true once the turn lands, so the newest words stay blue and the caret keeps blinking at the end."
+  ],
   "specimens": [
     {
       "title": "StreamingText",
@@ -77,6 +87,5 @@
       "note": "Tokens landing a word at a time: the newest two are lit in the streaming hue and cool into ink behind them, and a caret sits at the end while more is coming. A segment marked mono becomes a chip, which is how a path or a channel range survives being read aloud in prose.",
       "interaction": "none, and deliberately: it is a paragraph, and it stays selectable, copyable text at every count."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sub.json

@@ -22,10 +22,19 @@
   ],
   "summary": "A subscript inside an expression: a bound or a label, set upright inside the italic.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sub",
   "mdUrl": "/docs/components/sub.md",
   "jsonUrl": "/r/components/sub.json",
+  "whenToUse": [
+    "A bound or a label under a variable inside a rendered expression."
+  ],
+  "whenNotToUse": [
+    "Body prose that happens to need a subscript. This one is shaped to sit upright inside an expression's italic."
+  ],
+  "commonMistakes": [
+    "Reaching for it outside an expression, where the upright-inside-the-italic setting has nothing to sit inside."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -40,6 +49,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/subagent-list.json

@@ -86,10 +86,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/subagent-list",
   "mdUrl": "/docs/components/subagent-list.md",
   "jsonUrl": "/r/components/subagent-list.json",
+  "whenToUse": [
+    "A fan-out of parallel workers, each card naming its agent and model, with a summariser underneath."
+  ],
+  "whenNotToUse": [
+    "One agent's steps over time. This draws a card per worker and a progress width per worker."
+  ],
+  "commonMistakes": [
+    "Letting `progress` and `agents` fall out of step. The array is positional, per agent, and used while a worker is still running.",
+    "Marking individual agents complete. `completedCount` is how many from the start are complete, so completion is prefix-shaped.",
+    "Passing `summaryAgent` and expecting it to appear. It shows only when `showSummary` is true."
+  ],
   "specimens": [
     {
       "title": "SubagentList",
@@ -101,6 +112,5 @@
       "note": "Parallel workers, each with its own model and its own progress. `completedCount` marks the finished ones from the start of the list, and the summary card appears under them when the agent that folds their answers together starts work.",
       "interaction": "none. Delegation is something to watch, not something to steer from here."
     }
-  ],
-  "todo": true
+  ]
 }