@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/research-report.json

@@ -67,10 +67,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/research-report",
   "mdUrl": "/docs/components/research-report.md",
   "jsonUrl": "/r/components/research-report.json",
+  "whenToUse": [
+    "A long research answer where the shape should be legible before the prose lands."
+  ],
+  "whenNotToUse": [
+    "An answer with no outline to state first. The sections existing from the start is the point of the component."
+  ],
+  "commonMistakes": [
+    "Appending sections as they complete. Pass the whole outline up front and let it fill in.",
+    "Deriving `sourcesRead` from the sections. It is a running count of sources consumed, passed in."
+  ],
   "specimens": [
     {
       "title": "ResearchReport",
@@ -82,6 +92,5 @@
       "note": "An outline that fills in rather than a spinner that spins: every heading is present from the first frame, and each one carries the number of sources behind it. The section being written spins in the streaming hue, the finished ones take a check, the ones still queued are a dot — three states, one row.",
       "interaction": "none. The counter above is derived from the sections, so `2/4 sections` cannot disagree with what is drawn under it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/resizable.json

@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/resizable",
   "mdUrl": "/docs/components/resizable.md",
   "jsonUrl": "/r/components/resizable.json",
+  "whenToUse": [
+    "A two-or-more pane view whose balance is the user's to choose: a tree beside a canvas, a list beside a detail.",
+    "Anywhere the right split differs per user or per task."
+  ],
+  "whenNotToUse": [
+    "A layout with one correct proportion. Use `Grid` or `Stack` and decide it.",
+    "Panes that must not collapse. A draggable split invites dragging to zero."
+  ],
+  "commonMistakes": [
+    "Importing it from the core barrel. `react-resizable-panels` is an **optional peer** — import from `@cueplusplus/ui/layout/resizable` so an app with no split view never installs one."
+  ],
   "specimens": [
     {
       "title": "Resizable",
@@ -86,6 +97,5 @@
       "note": "react-resizable-panels with a 4px handle that goes accent on hover. Also an optional peer, from @cueplusplus/ui/layout/resizable.",
       "interaction": "the handle is a `separator` with a value: arrow keys resize, Home and End collapse either way."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/retrieval-chunks.json

@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/retrieval-chunks",
   "mdUrl": "/docs/components/retrieval-chunks.md",
   "jsonUrl": "/r/components/retrieval-chunks.json",
+  "whenToUse": [
+    "Showing what a retrieval answer is standing on while the index is still being queried — `searching` shimmers the status line."
+  ],
+  "whenNotToUse": [
+    "Raw index output. `chunks` are the passages already above the threshold and already sorted by score."
+  ],
+  "commonMistakes": [
+    "Sorting or thresholding in the render. Both happen before the prop.",
+    "Slicing `chunks` to what has landed. `visibleCount` is that number, and `chunks` is the whole result.",
+    "Leaving `searching` true once the passages have arrived, so a settled panel keeps shimmering."
+  ],
   "specimens": [
     {
       "title": "RetrievalChunks",
@@ -93,6 +104,5 @@
       "note": "What a retrieval actually returned, before the answer built on it: the passage, where it came from, and the score — with a bar under each so a 0.62 reads as weaker than a 0.91 without arithmetic. Scores at or above 0.8 go green; that threshold is the element's one opinion.",
       "interaction": "none, and that is right: these are evidence, not controls. While `searching` the header shimmers; when it settles it says how many passages cleared the threshold."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/revert-dock.json

@@ -177,10 +177,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/revert-dock",
   "mdUrl": "/docs/components/revert-dock.md",
   "jsonUrl": "/r/components/revert-dock.json",
+  "whenToUse": [
+    "A checkpoint a run can be restored to, where files and the conversation are separate axes and the copy says which is which.",
+    "A runtime with only one axis to put back: `scopes={[\"conversation\"]}` offers that alone."
+  ],
+  "whenNotToUse": [
+    "Anything that is not destructive. This is the family's only destructive control, and `This action cannot be undone.` is on screen the whole time the dock is open — the sentence it refuses to render without."
+  ],
+  "commonMistakes": [
+    "Treating a scope press as the restore. Picking a scope only arms the dock; `onRestore` fires from one control alone, the one that answers \"Discard all changes up to this checkpoint?\", and at most once per arm.",
+    "Moving or replacing the scope list when the dock arms. It stays exactly where it was, dimmed and disabled, with the question appended under it — because the old layout put `Discard and restore` (x13-170, y131-161) inside `Restore conversation` (x13-435, y121-175) at 448px, so a double click on a scope destroyed the work with its second press.",
+    "Owning `open` and `confirming` internally. Both are the caller's, which is what lets the armed state be benched, tested and replayed instead of existing only between two clicks."
+  ],
   "specimens": [
     {
       "title": "RevertDock",
@@ -192,6 +204,5 @@
       "note": "The one destructive control in this family, and the three things that make it one rather than a button called Restore. The axis: a run changes the files and the conversation about them, and putting one back is not putting the other back — Roo writes it as `Restore Files` against `Restore Files & Task`, Cline as `Reset Code` against `Reset Chat`. The gate: picking a scope only arms the dock, and `onRestore` fires from the second press alone. And the geometry, which is the half a gate cannot do on its own: the confirm is appended under the scope list rather than drawn over it, because a destructive control that inherits the coordinates of the control that armed it is one a double click reaches unread. `This action cannot be undone.` is on the screen the whole time the dock is open, above every step, because an irreversibility that lives in a props table is one somebody meets for the first time afterwards.",
       "interaction": "each scope names what it costs in a second line under its label; pressing one tints that scope, disables the whole list where it stands and appends Cursor's question beneath it, so nothing above the confirm moves a pixel. Focus lands on `Keep everything`, which also comes first in the DOM; Escape backs out, folding the dock disarms it, and the destructive half refuses presses for 400 ms after it arrives. Restoring here folds the dock and says which scope it was."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/reviewable-diff.json

@@ -93,10 +93,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/reviewable-diff",
   "mdUrl": "/docs/components/reviewable-diff.md",
   "jsonUrl": "/r/components/reviewable-diff.json",
+  "whenToUse": [
+    "A patch a person should be able to take in parts rather than all or nothing."
+  ],
+  "whenNotToUse": [
+    "A diff nobody is deciding about. Apply stays disabled until no hunk is pending, so a read-only view sits permanently unapplyable."
+  ],
+  "commonMistakes": [
+    "Writing every hunk on `onApply`. Only the kept ones should be written — the discards are the whole point of the review.",
+    "Removing a discarded hunk from `hunks`. Each hunk carries its own decision, and it is the pending ones that gate Apply."
+  ],
   "specimens": [
     {
       "title": "ReviewableDiff",
@@ -108,6 +118,5 @@
       "note": "The same diff, except every hunk is a decision. A discarded hunk stays visible at reduced opacity rather than vanishing, so what the reviewer turned down is still part of what they reviewed, and Apply stays disabled until nothing is pending.",
       "interaction": "Keep and Discard are per hunk and named by range for a screen reader. Apply here puts every hunk back to pending, so the bench can be run again."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/risk-badge.json

@@ -69,10 +69,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/risk-badge",
   "mdUrl": "/docs/components/risk-badge.md",
   "jsonUrl": "/r/components/risk-badge.json",
+  "whenToUse": [
+    "Beside a tool call from a runtime that scores its own actions, so a `curl` to an arbitrary host does not look like a `cat` of a local file.",
+    "A runtime with no scorer at all: `unknown` is a first-class value and the honest answer."
+  ],
+  "whenNotToUse": [
+    "As a silent stand-in for safety. Omitting the badge, or falling back to `low` when nothing scored the call, is how a UI ends up implying that unscored means safe."
+  ],
+  "commonMistakes": [
+    "Restyling the row from a prop. The badge stamps `data-risk` and `data-color` for exactly that.",
+    "Overriding `label` with a bare adjective like `HIGH`. It sits inline beside a duration and a diff stat, where a bare adjective reads as a number about something — hence the `High risk` default.",
+    "Leaning on the colour. Each risk carries its own glyph and its own words so the badge survives a colour-blind reader, a monochrome screenshot, and a theme whose danger hue is somebody's brand red."
+  ],
   "specimens": [
     {
       "title": "RiskBadge",
@@ -84,6 +96,5 @@
       "note": "How dangerous the runtime says this call is, said out loud instead of implied. Six of the seven open-source agent UIs in the study encode risk through which approval bucket a tool happens to fall into, so a fetch to an arbitrary host and a read of a local file look alike until you read them. One runtime scores the action itself, and one badge then renders it for every tool that will ever exist. `unknown` is a first-class value: a runtime with no scorer must not be made to look like one that scored everything safe.",
       "interaction": "none. The qualifier beside the label is the half the implicit products were right about — `High risk` on its own is a temperature, `High risk · arbitrary network access` is a fact — and it truncates before the label does."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/schedule-card.json

@@ -101,10 +101,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/schedule-card",
   "mdUrl": "/docs/components/schedule-card.md",
   "jsonUrl": "/r/components/schedule-card.json",
+  "whenToUse": [
+    "A recurring run whose recent history matters — `history` is there so a silently failing schedule is visible."
+  ],
+  "whenNotToUse": [
+    "A cron editor. `cadence` is human-readable recurrence, not a cron string."
+  ],
+  "commonMistakes": [
+    "Formatting `nextRun` for a paused schedule. When `enabled` is false it is replaced by paused.",
+    "Passing an empty `history`. It is required, and a schedule with no visible runs is precisely the failure this card exists to catch."
+  ],
   "specimens": [
     {
       "title": "ScheduleCard",
@@ -116,6 +126,5 @@
       "note": "A job that repeats on its own: what it is called, how often it goes, when it next goes, and how the last three went. Paused, the next-run row dims and says `paused` rather than showing a time that will not happen.",
       "interaction": "the toggle is a real switch — role, `aria-checked` and a label naming the schedule — so three of these on a page do not all read as 'Toggle'."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/score-breakdown.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/score-breakdown",
   "mdUrl": "/docs/components/score-breakdown.md",
   "jsonUrl": "/r/components/score-breakdown.json",
+  "whenToUse": [
+    "A judged result where the reader should be able to argue with the number, because the criteria that produced it are on screen."
+  ],
+  "whenNotToUse": [
+    "A bare score. Without criteria there is no arithmetic to show, which is the whole of this component."
+  ],
+  "commonMistakes": [
+    "Scaling each criterion to its own maximum. `outOf` is the maximum for the headline and for every criterion bar.",
+    "Tinting the verdict yourself. Its tint follows `total` over `outOf`.",
+    "Slicing `criteria` to those scored so far. `visibleCount` is that, and `criteria` is the full set."
+  ],
   "specimens": [
     {
       "title": "ScoreBreakdown",
@@ -103,6 +114,5 @@
       "note": "A verdict with its working shown. The number leads, the badge names it in words, and every criterion carries its weight and the note that explains a low mark — which is what makes a 7.8 arguable instead of oracular. The badge's three bands are the element's own thresholds at three quarters and a half.",
       "interaction": "none. The bars animate their width, and hold still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scroll-anchor.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scroll-anchor",
   "mdUrl": "/docs/components/scroll-anchor.md",
   "jsonUrl": "/r/components/scroll-anchor.json",
+  "whenToUse": [
+    "A transcript viewport where messages arrive while the reader may have scrolled up — it pins only when they are already at the bottom."
+  ],
+  "whenNotToUse": [
+    "A scene you need to rewind through a prop. Replay happens by remounting; `paused` only freezes it where it is."
+  ],
+  "commonMistakes": [
+    "Expecting `paused` to restart the scene. It freezes; the way back to the start is a remount.",
+    "Wiring `onSettled` as a per-message callback. It fires once every message has landed and the viewport is pinned."
+  ],
   "specimens": [
     {
       "title": "ScrollAnchor",
@@ -79,6 +89,5 @@
       "note": "The rule every transcript needs and few get: streaming may only move the viewport if you were already at the bottom of it. Scroll up to read something and the answer keeps arriving behind you; a pill counts what landed and takes you back down. It is the family's one element that runs a clock of its own — the turns append on a timer so the behaviour can be seen standing still.",
       "interaction": "the pill is a button. Both scrolls are CSS `scroll-smooth`, not `scrollTo({ behavior })`, because only the declarative one can be withdrawn: `motion-reduce:scroll-auto` makes them instant, and the timer stops outright, painting the finished transcript in one go."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scroll-area.json

@@ -94,10 +94,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scroll-area",
   "mdUrl": "/docs/components/scroll-area.md",
   "jsonUrl": "/r/components/scroll-area.json",
+  "whenToUse": [
+    "A pane whose scrollbar should match the console rather than the OS.",
+    "Anywhere native scrolling must be kept — it re-skins the bar only, so momentum, keyboard and trackpad behaviour stay the browser's."
+  ],
+  "whenNotToUse": [
+    "The document itself. The page's own scroller is not this component's job."
+  ],
+  "commonMistakes": [
+    "Forgetting to bound its height. The frame needs `h-full` inside a flex parent or an explicit height — without one there is nothing to scroll and the component looks broken.",
+    "Reimplementing scrolling with transforms, which throws away exactly the native behaviour this keeps."
+  ],
   "specimens": [
     {
       "title": "ScrollArea",
@@ -109,6 +120,5 @@
       "note": "A themed scroller in either axis, so an overflowing panel does not fall back to the platform bar.",
       "interaction": "the thumb fades in on hover over the area and stays while dragging."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scrollable-tabs-list.json

@@ -63,7 +63,7 @@
     "--cue-surface-2",
     "--cue-text-ui"
   ],
-  "summary": "A {@link TabsList} that scrolls when its tabs do not fit, and says so.",
+  "summary": "A tabs list that scrolls when its tabs do not fit, and says so.",
   "examples": [
     {
       "title": "Usage",
@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scrollable-tabs-list",
   "mdUrl": "/docs/components/scrollable-tabs-list.md",
   "jsonUrl": "/r/components/scrollable-tabs-list.json",
+  "whenToUse": [
+    "Any tab strip whose count can outgrow its container.",
+    "Anywhere clipping would read as a layout bug: a plain flex row renders \"SETTINGS\" as \"INGS\"."
+  ],
+  "whenNotToUse": [
+    "A fixed, small set of tabs that always fits. `Tabs.List` is simpler."
+  ],
+  "commonMistakes": [
+    "Keeping `Tabs.List` because it looks fine today. The failure only appears at the tab count or the viewport you did not test.",
+    "Dropping the chevrons and keeping only the mask. The affordance is both halves — the mask says there is more, the buttons are how a pointer user gets there."
+  ],
   "specimens": [
     {
       "title": "ScrollableTabsList",
@@ -86,6 +97,5 @@
       "note": "The same list when it does not fit: a mask fade at each overflowing edge, plus chevron buttons.",
       "interaction": "the chevrons appear only on the side that actually overflows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-cell.json

@@ -62,7 +62,7 @@
     "--cue-surface-2",
     "--cue-surface-3"
   ],
-  "summary": "One filled cell of a {@link SeamGrid} — or of the Phase 1 `SeamList`.",
+  "summary": "One filled cell of a `SeamGrid` — or of a `SeamList`.",
   "examples": [
     {
       "title": "Usage",
@@ -70,10 +70,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-cell",
   "mdUrl": "/docs/components/seam-cell.md",
   "jsonUrl": "/r/components/seam-cell.json",
+  "whenToUse": [
+    "Every child of a seam container.",
+    "Anywhere the cell needs its own ground, an interactive state, or to sit flush against the container edge."
+  ],
+  "whenNotToUse": [
+    "Outside a seam container, where the fill has no seam to protect."
+  ],
+  "commonMistakes": [
+    "Making the fill transparent. The fill is the load-bearing part: without it the container's border colour shows through everywhere and the seam stops being a hairline."
+  ],
   "specimens": [
     {
       "title": "SeamGrid / SeamCell",
@@ -86,6 +96,5 @@
       "note": "The 1px-gap hairline idiom as a two-dimensional component: the grid's own background shows through the gaps.",
       "interaction": "`interactive` cells take a hover ground and a focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-grid.json

@@ -63,10 +63,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-grid",
   "mdUrl": "/docs/components/seam-grid.md",
   "jsonUrl": "/r/components/seam-grid.json",
+  "whenToUse": [
+    "A grid of cells that must be divided by a perfect hairline at every corner.",
+    "Anywhere borders would double up or disagree — the gap is 1px over the border colour, so there is nothing to double."
+  ],
+  "whenNotToUse": [
+    "A plain grid with spacing. Use `Grid`.",
+    "A one-dimensional run. Use `SeamList`."
+  ],
+  "commonMistakes": [
+    "Using cells that do not paint their own ground. Pair with `SeamCell` — an unfilled cell lets the container's border colour through everywhere, not just at the gap, and the seam disappears into a solid block.",
+    "Inlining the idiom by hand. It was inlined at eighteen call sites before it was a component."
+  ],
   "specimens": [
     {
       "title": "SeamGrid / SeamCell",
@@ -79,6 +91,5 @@
       "note": "The 1px-gap hairline idiom as a two-dimensional component: the grid's own background shows through the gaps.",
       "interaction": "`interactive` cells take a hover ground and a focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-list.json

@@ -35,10 +35,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-list",
   "mdUrl": "/docs/components/seam-list.md",
   "jsonUrl": "/r/components/seam-list.json",
+  "whenToUse": [
+    "Rows that are cards in their own right, where a border would double up with the row's own.",
+    "Anywhere a hairline must stay exactly one pixel and must not disagree with a rounded corner."
+  ],
+  "whenNotToUse": [
+    "A plain list of text. A `Stack` with a `gap` is simpler and says the same thing."
+  ],
+  "commonMistakes": [
+    "Giving the children a transparent fill. Each child must paint its own opaque fill — that is what makes the 1px gap read as a hairline instead of showing the container's border colour through the row.",
+    "Pairing it with rows that draw their own borders. Use `<Row seam>`."
+  ],
   "specimens": [
     {
       "title": "Row / SeamList",
@@ -51,6 +62,5 @@
       "note": "Hairline rows, and the 1px-gap variant where the gaps themselves are the rule.",
       "interaction": "pass `interactive` for a hover ground and a focus ring; `disabled` dims and stops pointer events."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/search-input.json

@@ -167,7 +167,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A filter box: leading magnifier, Escape to clear, and a debounced change callback for whatever the query drives.",
+  "summary": "A filter box: leading magnifier, Escape to clear, and a debounced change callback.",
   "examples": [
     {
       "title": "Usage",
@@ -175,10 +175,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/search-input",
   "mdUrl": "/docs/components/search-input.md",
   "jsonUrl": "/r/components/search-input.json",
+  "whenToUse": [
+    "Any console filter. Escape-to-clear is the behaviour every one needs and every hand-rolled box forgets.",
+    "A query that drives expensive work — `debounce` and `onDebouncedChange` exist so it is not run per keystroke."
+  ],
+  "whenNotToUse": [
+    "A value that is submitted rather than applied as you type. That is an `Input` in a form.",
+    "Choosing from a known set. Use `Combobox`."
+  ],
+  "commonMistakes": [
+    "Rebuilding it from `Input` plus an icon, which loses Escape-to-clear and its stopPropagation — without that the key bubbles into the surrounding dialog and closes it underneath the user.",
+    "Wiring expensive work to `onValueChange` instead of `onDebouncedChange`."
+  ],
   "specimens": [
     {
       "title": "SearchInput",
@@ -190,6 +202,5 @@
       "note": "A magnifier, a clear button that appears once there is something to clear, and an optional debounce.",
       "interaction": "Escape clears; the clear button is a real button with a name, not an icon glued to the rim."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/section-header.json

@@ -120,10 +120,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/section-header",
   "mdUrl": "/docs/components/section-header.md",
   "jsonUrl": "/r/components/section-header.json",
+  "whenToUse": [
+    "Titling a group inside a panel, where the heading must not read as another object.",
+    "A group that can be folded away: `collapsible` puts the disclosure on the header itself."
+  ],
+  "whenNotToUse": [
+    "A page title. Use `PageShell`'s header.",
+    "A row. This names rows; it is not one of them."
+  ],
+  "commonMistakes": [
+    "Boxing it — giving the heading a rim and a fill. A heading that is itself a panel competes with the panels underneath it and reads as another object rather than as their title.",
+    "Sizing the rule by hand. It is a `flex-1` block so it always fills exactly what the label and the count leave."
+  ],
   "specimens": [
     {
       "title": "SectionHeader",
@@ -135,6 +147,5 @@
       "note": "A label, a rule, an optional count and an action slot. Collapsible when the section under it is.",
       "interaction": "the collapsible variant is a button: hover tints the label, Enter and Space toggle."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/segmented-control.json

@@ -158,10 +158,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/segmented-control",
   "mdUrl": "/docs/components/segmented-control.md",
   "jsonUrl": "/r/components/segmented-control.json",
+  "whenToUse": [
+    "A choice between a small number of views where the answer is always one of them.",
+    "Anywhere clicking the active option must be a no-op rather than a way to end up with nothing."
+  ],
+  "whenNotToUse": [
+    "A filter that may be cleared. Use `ToggleGroup`, which can be emptied — that difference is the whole distinction.",
+    "Actions. Use `ButtonGroup`.",
+    "More options than fit comfortably. Use `Select`."
+  ],
+  "commonMistakes": [
+    "Choosing between this and `ToggleGroup` on appearance. Ask whether 'none' is a legal answer.",
+    "Adding your own clear control, which reintroduces the empty state this refuses."
+  ],
   "specimens": [
     {
       "title": "SegmentedControl",
@@ -173,6 +186,5 @@
       "note": "Three sizes. The active segment is `accent-soft`, on the same ruling as the active tab. The last specimen is five segments in 15rem: the rim and the height hold, the segments scroll inside them — the same overflow behaviour Toolbar and AppBar have, from the same module.",
       "interaction": "arrow keys move the selection and reach the segments off-screen; the whole control is one tab stop. A chevron appears at whichever edge still hides one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/separator.json

@@ -36,10 +36,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/separator",
   "mdUrl": "/docs/components/separator.md",
   "jsonUrl": "/r/components/separator.json",
+  "whenToUse": [
+    "Dividing groups that are genuinely separate: a menu's sections, a toolbar's clusters, a panel's header from its body.",
+    "Anywhere the division needs to exist in the accessibility tree — it carries `role=\"separator\"` and `aria-orientation`."
+  ],
+  "whenNotToUse": [
+    "Spacing. If the groups only need air, give them `gap`; a rule adds meaning that may not be there.",
+    "The outline of a surface. That is the card's own border, not a separator."
+  ],
+  "commonMistakes": [
+    "Replacing it with `border-t` on the next element. The line here is a `h-px` block precisely because a bordered zero-height box collapses unpredictably inside flex rows.",
+    "Overriding the colour with a literal instead of letting the `border` token paint it, which breaks the moment a theme changes."
+  ],
   "specimens": [
     {
       "title": "Separator",
@@ -51,6 +63,5 @@
       "note": "A hairline in either orientation.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/settings-panel.json

@@ -132,10 +132,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/settings-panel",
   "mdUrl": "/docs/components/settings-panel.md",
   "jsonUrl": "/r/components/settings-panel.json",
+  "whenToUse": [
+    "A compact settings surface for one thread: a few models, the system prompt, temperature and a handful of capability switches."
+  ],
+  "whenNotToUse": [
+    "A long model list. `models` feeds a segmented control — keep it to a few; more wants the model picker."
+  ],
+  "commonMistakes": [
+    "Driving `temperature` outside 0 to 2, which is the range the slider is built for.",
+    "Giving toggles with no explanation. Each switch carries a line saying what it turns on, which is what makes a capability list readable.",
+    "Passing `toggles` without `onToggle` and expecting the switches to move — the callback reports the switched capability's key and the state stays yours."
+  ],
   "specimens": [
     {
       "title": "SettingsPanel",
@@ -147,6 +158,5 @@
       "note": "Model, system prompt, temperature, and what the assistant is allowed to do — the four settings a chat product actually has, on one card. The capability switches each carry a line saying what turning them on does, which is the difference between a settings page and a list of nouns. The panel holds none of it: every value here is the caller's.",
       "interaction": "the segmented model control is a row of `aria-pressed` buttons, and both the prompt textarea and the temperature slider carry their own labels, so nothing on the card depends on the mono caption above it being read."
     }
-  ],
-  "todo": true
+  ]
 }