@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/flow-graph.json

@@ -66,10 +66,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/flow-graph",
   "mdUrl": "/docs/components/flow-graph.md",
   "jsonUrl": "/r/components/flow-graph.json",
+  "whenToUse": [
+    "Work that branches and rejoins, where a list would lose the shape.",
+    "A graph drawn progressively, where an edge stays dim until both of its ends have been reached."
+  ],
+  "whenNotToUse": [
+    "A graph you want laid out for you. Layout is explicit and the element runs no solver."
+  ],
+  "commonMistakes": [
+    "Leaving grid positions off the nodes. Every node carries its own, because nothing solves the layout.",
+    "Wondering why an edge is dim. An edge dims until both of its ends are visible, which `visibleCount` controls."
+  ],
   "specimens": [
     {
       "title": "FlowGraph",
@@ -81,6 +92,5 @@
       "note": "Work as a graph rather than a list, for the runs that fan out and rejoin — here the two trusses are patched in parallel and the render waits for both. Layout is explicit: every node carries its own column and row and the element runs no solver, which is what keeps a re-render from rearranging a diagram somebody was reading.",
       "interaction": "none. `visibleCount` is what makes the graph arrive a node at a time, and an edge stays dim until both of its ends have been reached."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/folder-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "A folder somebody made: a shelf of bookmarks, filed by hand.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/folder-icon",
   "mdUrl": "/docs/components/folder-icon.md",
   "jsonUrl": "/r/components/folder-icon.json",
+  "whenToUse": [
+    "A collection a person curated deliberately."
+  ],
+  "whenNotToUse": [
+    "A result set a query returned. The tab is what says a person put these here on purpose.",
+    "An audience. Use `AudienceIcon` — its members are people, not artefacts."
+  ],
+  "commonMistakes": [
+    "Replacing it with a plain rounded box, which in this library is a panel, a card or a dialog — and which drops the one thing a folder has to say."
+  ],
   "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/frac.json

@@ -45,10 +45,19 @@
   ],
   "summary": "A fraction inside an expression — numerator, rule, denominator — set inline and aligned to the middle.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/frac",
   "mdUrl": "/docs/components/frac.md",
   "jsonUrl": "/r/components/frac.json",
+  "whenToUse": [
+    "A fraction set inside a line of an expression."
+  ],
+  "whenNotToUse": [
+    "A display-sized equation of its own. This sets inline and aligns to the middle of the line."
+  ],
+  "commonMistakes": [
+    "Writing the fraction as text with a slash instead of passing `over` and `under`, which loses the rule and the middle alignment."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -63,6 +72,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/frames.json

@@ -88,6 +88,20 @@
           "control": {
             "kind": "boolean"
           }
+        },
+        {
+          "name": "layout",
+          "type": "\"column\" | \"board\"",
+          "required": false,
+          "defaultValue": "board",
+          "description": "How the frames are arranged. Defaults to `\"board\"`.\n\n`\"board\"` is the original: a short, wide, sideways scroller a reader drags\nthrough — right where the frames are a set you *browse*, on a homepage wall\nor a design surface.\n\n`\"column\"` stacks them one under the next, each at the full width it is\ngiven, and the canvas grows to whatever it holds. It exists for the page\nthat *reads*: a documentation page scrolls vertically already, and asking a\nreader to pan a second axis to reach the fifth variant of a component —\nwith that fifth variant clipped at the board's edge until they do — hides\nthe examples behind an interaction. A column has no fixed height, so\n`height` is ignored, and nothing pans, so `pan` and `hint` are moot.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "column",
+              "board"
+            ]
+          }
         }
       ],
       "typeReferences": [

package/manifest/components/generation-loader.json

@@ -58,10 +58,21 @@
   ],
   "summary": "The wait before there is anything to show.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/generation-loader",
   "mdUrl": "/docs/components/generation-loader.md",
   "jsonUrl": "/r/components/generation-loader.json",
+  "whenToUse": [
+    "The gap before the model has produced anything at all, under a shimmering status label.",
+    "A replay you can pause: the caller advances `tick`, so a paused replay pauses the loader too."
+  ],
+  "whenNotToUse": [
+    "Work with named stages and an estimate. This is the empty wait, not a progress bar."
+  ],
+  "commonMistakes": [
+    "Expecting it to animate on its own. `tick` drives both the pixel pattern and the elapsed seconds counter.",
+    "Leaving it on screen once content arrives. It is for the wait before there is anything to show."
+  ],
   "specimens": [
     {
       "title": "GenerationLoader",
@@ -73,6 +84,5 @@
       "note": "The wait before there is anything at all to show. Nine cells keep time under a shimmering label, driven by a tick the caller advances — so a paused replay pauses the loader too, which a CSS animation could never do. The three variants are three shapes for the same clock.",
       "interaction": "none. The matrix is aria-hidden; the label is the only thing a screen reader gets, which is the right amount."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/generative-ui.json

@@ -97,7 +97,7 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [],
-  "summary": "The vocabulary a model composes at runtime.",
+  "summary": "The vocabulary a model composes at runtime: a JSON tree of intrinsic names, turned into elements.",
   "examples": [
     {
       "title": "Usage",
@@ -105,10 +105,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/generative-ui",
   "mdUrl": "/docs/components/generative-ui.md",
   "jsonUrl": "/r/components/generative-ui.json",
+  "whenToUse": [
+    "Rendering a component tree a language model emitted as JSON, where there is no compile step between the two and there cannot be one.",
+    "A widget that has to draw inside somebody else's console: the stylesheet is plain `[data-aui]` CSS and the tree it draws carries no `class` attribute anywhere."
+  ],
+  "whenNotToUse": [
+    "A tree a programmer wrote. Every other component in the library is handed props at a call site, where a wrong one costs a type error.",
+    "Markdown you expect parsed. This subpath ships no parser and will not acquire one — pass `renderMarkdown`, which is shaped for `@cueplusplus/ui/elements/markdown`."
+  ],
+  "commonMistakes": [
+    "Casting the parsed tool result to `GenerativeNode` before passing it. `spec` is `unknown` on purpose, because a cast is a claim about the bytes that nobody is in a position to make.",
+    "Wrapping it in an error boundary and expecting throws. It never throws: an unknown `$type` draws an in-place notice and its siblings still render, a spec that is not a tree draws a legible error state rather than a blank box, and a tree past `GENERATIVE_MAX_DEPTH` stops and says so.",
+    "Passing `skin` and `fidelity` inside an `AgentSurface`, which has already stamped the subtree and whose values inherit through CSS with nothing threaded."
+  ],
   "specimens": [
     {
       "title": "GenerativeUI",
@@ -120,6 +133,5 @@
       "note": "The one component here nobody wrote props for. A model emits a tree of 27 intrinsic names as JSON and this draws it, with no compile step in between and none possible, so the specimens are the spec objects themselves: a dashboard the model composed out of facts, a chart and a table; a patch form whose confirm hands back every named field at once; and a chart on its own. The last two are wrong on purpose. A $type from a newer catalogue draws an in-place notice and its siblings still render; a spec that is not a tree at all draws a legible error rather than the blank box that reads as a message still streaming. Neither throws, which is the whole contract. It draws from plain [data-aui] CSS with no utilities and no icon or chart package behind it, because the console a model is talking to is usually somebody else's app.",
       "interaction": "every control is a real control and takes the house focus ring; text fires on blur rather than per keystroke, since $action is a message to the model. The form specimen is live: submit it and the model's own card gains a success alert with what the desk received."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/grid.json

@@ -112,10 +112,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/grid",
   "mdUrl": "/docs/components/grid.md",
   "jsonUrl": "/r/components/grid.json",
+  "whenToUse": [
+    "A card grid, a tile wall, any set of peers laid out in both directions.",
+    "Responsive column counts without media queries: give `minItemWidth` and let it fit as many as it can."
+  ],
+  "whenNotToUse": [
+    "A single row or column. Use `Stack`.",
+    "A table. Use the data-table instruments, which carry the semantics a grid of divs cannot."
+  ],
+  "commonMistakes": [
+    "Setting `cols` and `minItemWidth` together and expecting both to apply.",
+    "Hand-picking the gap. It is a rung of the density ladder for the same reason `Stack`'s is — a card grid should tighten with the rest of the console."
+  ],
   "specimens": [
     {
       "title": "Grid",
@@ -127,6 +139,5 @@
       "note": "Fixed columns, or auto-fit from a minimum item width.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/group-bar.json

@@ -102,10 +102,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/group-bar",
   "mdUrl": "/docs/components/group-bar.md",
   "jsonUrl": "/r/components/group-bar.json",
+  "whenToUse": [
+    "A breakdown where the proportions are the reading and exact numbers are not.",
+    "Anywhere a stacked bar should carry no axis — the shape is the answer."
+  ],
+  "whenNotToUse": [
+    "Values that must be compared precisely. Use a table or a labelled chart.",
+    "A single value against a maximum. Use `Progress`."
+  ],
+  "commonMistakes": [
+    "Rendering zero-valued groups. Empty groups get no cell: a minimum width is what makes a two-pixel sliver visible, and a minimum width on a zero draws a group that is not there."
+  ],
   "specimens": [
     {
       "title": "GroupBar",
@@ -117,6 +128,5 @@
       "note": "The distribution strip: one flex cell per item, coloured by tone, with a legend that names each share.",
       "interaction": "none. It is a picture of a breakdown, and the legend is the text version of it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/guardrail-notice.json

@@ -89,10 +89,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/guardrail-notice",
   "mdUrl": "/docs/components/guardrail-notice.md",
   "jsonUrl": "/r/components/guardrail-notice.json",
+  "whenToUse": [
+    "A refusal that should say where the line actually sits and offer the nearest things it can do."
+  ],
+  "whenNotToUse": [
+    "A failure the system could simply try again.",
+    "A refusal with no rule behind it. `policy` is a required short label for the rule that applied."
+  ],
+  "commonMistakes": [
+    "Writing an apology into `title`. It is the refusal in one line, stated plainly rather than apologetically.",
+    "Omitting `alternatives` to hide the section. Pass an empty array; it is a required prop."
+  ],
   "specimens": [
     {
       "title": "GuardrailNotice",
@@ -104,6 +115,5 @@
       "note": "A refusal in its own shape: what it will not do, why, the rule that applied, and the nearest things it *can* do. The alternatives are the whole point — a refusal that ends at 'no' hands the work back with nothing attached, and this one hands back three next moves.",
       "interaction": "each alternative is a button reporting its own text to `onPick`. With an empty list the section disappears rather than leaving an empty rule."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/hover-card.json

@@ -161,7 +161,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A richer preview than a tooltip, revealed by hovering a link or a name: the fixture behind a profile string, the operator behind an initial.",
+  "summary": "A richer preview than a tooltip, revealed by hovering a link or a name.",
   "examples": [
     {
       "title": "Usage",
@@ -169,10 +169,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/hover-card",
   "mdUrl": "/docs/components/hover-card.md",
   "jsonUrl": "/r/components/hover-card.json",
+  "whenToUse": [
+    "A preview the pointer can travel into — the fixture behind a profile string, the operator behind an initial.",
+    "Content with its own links or controls."
+  ],
+  "whenNotToUse": [
+    "A short description of a control. Use `Tooltip`, which is announced as the trigger's description.",
+    "Anything that must be reachable by keyboard alone. Hover is the trigger."
+  ],
+  "commonMistakes": [
+    "Using it as a big tooltip. It is deliberately not one: the card is reachable and its content is not announced as the trigger's description."
+  ],
   "specimens": [
     {
       "title": "HoverCard",
@@ -184,6 +195,5 @@
       "note": "A preview card: richer than a tooltip, and never the only way to reach the information.",
       "interaction": "opens on hover after a delay and on focus; the card itself is hoverable, so a link inside it is reachable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/icon-button.json

@@ -86,10 +86,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/icon-button",
   "mdUrl": "/docs/components/icon-button.md",
   "jsonUrl": "/r/components/icon-button.json",
+  "whenToUse": [
+    "A control whose meaning is carried by a familiar glyph in a place with no room for a label: a close, a copy, a kebab menu.",
+    "A dense toolbar where visible rims would be noise. The default `ghost` variant stays invisible until hovered."
+  ],
+  "whenNotToUse": [
+    "An action whose icon is not unambiguous on its own. Use `Button` with `icon` and real text.",
+    "A destructive action that deserves confirmation in place. Use `TwoStepButton`."
+  ],
+  "commonMistakes": [
+    "Treating `aria-label` as optional because the icon 'obviously' means close. It is required, and it is the only name the control has.",
+    "Putting a title or tooltip on the icon instead of labelling the button. The tooltip is a hint; the label is the accessible name.",
+    "Wrapping the icon in extra sizing markup. Pass the component to `icon` and it is rendered `aria-hidden` at the right rung."
+  ],
   "specimens": [
     {
       "title": "IconButton",
@@ -101,6 +114,5 @@
       "note": "A square button with a required accessible name. There is no unlabelled variant.",
       "interaction": "same ring as Button; the hit target stays at the control height even when the glyph shrinks."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/image-generation.json

@@ -53,10 +53,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/image-generation",
   "mdUrl": "/docs/components/image-generation.md",
   "jsonUrl": "/r/components/image-generation.json",
+  "whenToUse": [
+    "An image being generated, where the frame should hold its size before there is anything in it.",
+    "A result that should stay tied to its prompt, which is printed under the frame."
+  ],
+  "whenNotToUse": [
+    "An image that already exists and has no generating phase."
+  ],
+  "commonMistakes": [
+    "Leaving `generating` true after the image lands, which keeps a pulsing dot grid over a finished picture.",
+    "Dropping the prompt. It is shown under the frame, and it is what ties the result back to what was asked."
+  ],
   "specimens": [
     {
       "title": "ImageGeneration",
@@ -68,6 +79,5 @@
       "note": "A dot grid holds the square while the image resolves out of a blur — the frame is the right size from the first frame, so nothing below it moves when the picture lands. While generating, the prompt is replaced by a shimmering label; when it settles, the prompt is what is left under the image.",
       "interaction": "regenerate is a labelled icon button. The grid and the image are both `aria-hidden`: the prompt underneath is the description, and a decorative placeholder should not be announced as a picture."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/info-tip.json

@@ -104,7 +104,7 @@
     "--cue-font-mono",
     "--cue-text-micro"
   ],
-  "summary": "The 13px circular \"i\" badge: a footnote marker for a field, a column or a number whose definition is not obvious.",
+  "summary": "The 13px circular 'i' badge: a footnote marker for a field, a column or a number.",
   "examples": [
     {
       "title": "Usage",
@@ -112,10 +112,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/info-tip",
   "mdUrl": "/docs/components/info-tip.md",
   "jsonUrl": "/r/components/info-tip.json",
+  "whenToUse": [
+    "A definition that is not obvious and does not deserve permanent space.",
+    "Anywhere the explanation must be reachable from the keyboard — it is a real `<button>`."
+  ],
+  "whenNotToUse": [
+    "Text the reader needs. Use `FieldDescription`; a footnote most people never open is the wrong home for a requirement.",
+    "A control's name. Use a label."
+  ],
+  "commonMistakes": [
+    "Rebuilding it as a `<span>` with a hover handler, which puts the explanation out of keyboard reach.",
+    "Filling it with a paragraph. It is a footnote marker, not a panel."
+  ],
   "specimens": [
     {
       "title": "Tooltip / InfoTip",
@@ -128,6 +140,5 @@
       "note": "A tooltip names a control; an InfoTip is the 13px `i` badge that explains one.",
       "interaction": "tooltips open on hover and on keyboard focus, and never on touch; the InfoTip badge is a real button."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/inline-citation.json

@@ -70,10 +70,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/inline-citation",
   "mdUrl": "/docs/components/inline-citation.md",
   "jsonUrl": "/r/components/inline-citation.json",
+  "whenToUse": [
+    "Numbered markers set in a sentence, each previewing the source behind it.",
+    "A preview that carries the source's domain, title and snippet without leaving the sentence."
+  ],
+  "whenNotToUse": [
+    "A standalone source card outside a sentence. These markers live inline."
+  ],
+  "commonMistakes": [
+    "Using `-1` for closed. `openIndex` is `number | null`, and `null` is the closed value.",
+    "Leaving `onOpenIndexChange` off. It is required, because which preview is open is state you hold rather than state the element keeps."
+  ],
   "specimens": [
     {
       "title": "InlineCitation",
@@ -85,6 +96,5 @@
       "note": "The marker inside the sentence, rather than the list under it: a numbered chip the paragraph flows around, and behind each one the page it stands on. `Sources` is the bibliography; this is the footnote, and the two are meant to be read together — the chip says a claim is attributable without spending a clause saying so.",
       "interaction": "each marker is a button, so the preview is reachable from a keyboard as well as a pointer; the open one inverts to the accent fill. The card is the family's one portal, and it carries the island stamp — opened inside an `AgentSurface`, it paints in that island's values rather than the document's."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/input-group.json

@@ -84,7 +84,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A control and its adornments, drawn as a single field.",
+  "summary": "A control and its adornments, drawn as a single field — one rim, one fill, however many affordances.",
   "examples": [
     {
       "title": "Usage",
@@ -92,10 +92,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/input-group",
   "mdUrl": "/docs/components/input-group.md",
   "jsonUrl": "/r/components/input-group.json",
+  "whenToUse": [
+    "A prefix or suffix that belongs to the field: a unit, a currency, a copy button, a scheme.",
+    "Anywhere two controls must read as one: the group owns the chassis and publishes that through context."
+  ],
+  "whenNotToUse": [
+    "Two independent fields. Give them their own rims; a shared one says they are one value.",
+    "A label. Use `FieldLabel`; `leading` is part of the control, not its name."
+  ],
+  "commonMistakes": [
+    "Styling the `Input` inside. It strips its own border, background, height and padding by design and inherits the group's font size — restyling it puts the rim back and breaks the single-field illusion.",
+    "Assuming focus styling comes free. A `<div>` matches neither `:focus` nor `:focus-visible`, which is why the group handles it; do not reimplement it with `:focus-within`."
+  ],
   "specimens": [
     {
       "title": "InputGroup",
@@ -107,6 +119,5 @@
       "note": "One rim around a control and its adornments, so the group focuses as a unit.",
       "interaction": "any focus inside strengthens the whole rim; the ring waits for a keyboard-visible descendant, so a click on an adornment does not light the cluster up. The inner control never rings — the group owns the rim."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/item.json

@@ -135,7 +135,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control — the shape a settings entry, a search hit and a device row all want.",
+  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control.",
   "examples": [
     {
       "title": "Usage",
@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/item",
   "mdUrl": "/docs/components/item.md",
   "jsonUrl": "/r/components/item.json",
+  "whenToUse": [
+    "A settings entry, a search hit, a device row — a self-contained object that can stand alone, sit in a `Stack` or fill a `Grid` cell.",
+    "Anything clickable: it renders a real `<button>` when interactive, so keyboard users get it for free."
+  ],
+  "whenNotToUse": [
+    "A line of a hairline table. Use `Row` — that is a row of a grid, this is an object.",
+    "A whole summary surface. Use `Card`."
+  ],
+  "commonMistakes": [
+    "Wrapping a non-interactive `Item` in a `<div onClick>`. Pass `interactive` and let it be a button.",
+    "Putting the control inside `children` instead of `actions`, which loses the reserved slot and the alignment with every other row."
+  ],
   "specimens": [
     {
       "title": "Item",
@@ -158,6 +170,5 @@
       "note": "A media, title, description and actions row. Three variants, plus interactive and disabled.",
       "interaction": "the interactive variant takes a hover ground and a focus ring; it is a button, so Enter and Space activate it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/job-progress.json

@@ -96,10 +96,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/job-progress",
   "mdUrl": "/docs/components/job-progress.md",
   "jsonUrl": "/r/components/job-progress.json",
+  "whenToUse": [
+    "Long work with named stages, where a long install should not read the same as a fast clone.",
+    "Anything a person may need to abandon — `onCancel` is the way out, and it hides once the job finishes."
+  ],
+  "whenNotToUse": [
+    "A wait short enough that stages and an estimate are noise."
+  ],
+  "commonMistakes": [
+    "Giving every stage the same weight, which is exactly what the relative weights exist to avoid.",
+    "Special-casing the finished state. Passing `stages.length` as `stageIndex` marks the job finished, and the bar never runs past its track.",
+    "Passing a duration object to `eta`. It is a pre-formatted estimate, replaced by done once finished."
+  ],
   "specimens": [
     {
       "title": "JobProgress",
@@ -111,6 +123,5 @@
       "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
       "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/kbd.json

@@ -32,10 +32,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/kbd",
   "mdUrl": "/docs/components/kbd.md",
   "jsonUrl": "/r/components/kbd.json",
+  "whenToUse": [
+    "Naming a shortcut in prose, a menu row or an empty state — reference material the reader's eye can skip.",
+    "Anywhere a `Chip` sits on the same row. It is sized off the chip height so the two line up."
+  ],
+  "whenNotToUse": [
+    "A button. This is static markup that renders on the server and has no press behaviour.",
+    "A code fragment or a token name. Use inline code; a key cap says 'press this'."
+  ],
+  "commonMistakes": [
+    "Building a chord out of one `Kbd` containing `⌘ + K`. Emit one per key and put the separator between them, so each cap reads as a key.",
+    "Reaching for it as a small badge. It is set in the micro type step on purpose; `Chip` is the badge."
+  ],
   "specimens": [
     {
       "title": "Kbd",
@@ -47,6 +59,5 @@
       "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/launcher-bubble.json

@@ -110,10 +110,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/launcher-bubble",
   "mdUrl": "/docs/components/launcher-bubble.md",
   "jsonUrl": "/r/components/launcher-bubble.json",
+  "whenToUse": [
+    "An assistant that lives in the corner of a product rather than owning the page: a bubble that opens into a greeting and a few ways in.",
+    "A first run with nothing typed yet — `prompts` exists so the first message does not have to be invented."
+  ],
+  "whenNotToUse": [
+    "A launcher with no starters to offer. `prompts` is required, and an empty panel is the case the component is shaped against.",
+    "A panel whose open state lives inside it. `open` is required and the bubble only reports the press through `onToggle`."
+  ],
+  "commonMistakes": [
+    "Driving `unread` to zero and expecting a `0` badge. It is hidden at zero, and hidden again the whole time the panel is open.",
+    "Wiring the panel's Start a conversation action to `onPick`. That callback fires only for a starter prompt; the empty thread is `onStart`."
+  ],
   "specimens": [
     {
       "title": "LauncherBubble",
@@ -125,6 +137,5 @@
       "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
       "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
     }
-  ],
-  "todo": true
+  ]
 }