@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/field-error.json

@@ -56,7 +56,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "The error line under a control.",
+  "summary": "The error line under a control. Driven by Standard Schema issues, or by native validity.",
   "examples": [
     {
       "title": "Usage",
@@ -64,10 +64,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-error",
   "mdUrl": "/docs/components/field-error.md",
   "jsonUrl": "/r/components/field-error.json",
+  "whenToUse": [
+    "Showing a parse failure: pass `issues` from `schema.safeParse(x).issues` and the component owns visibility.",
+    "Keying off the browser's own `ValidityState`: pass `match` plus `children`."
+  ],
+  "whenNotToUse": [
+    "A permanent constraint. That is `FieldDescription`; an error should appear only when something is wrong.",
+    "A form-level failure. This belongs to one control."
+  ],
+  "commonMistakes": [
+    "Passing both `issues` and `match`. They are mutually exclusive by design — pick the source of truth.",
+    "Rendering it conditionally yourself when using `issues`. The component already decides when to show; wrapping it in your own guard fights it."
+  ],
   "specimens": [
     {
       "title": "Field / FieldLabel / FieldDescription / FieldError",
@@ -82,6 +94,5 @@
       "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
       "interaction": "clicking the label focuses the control; the error line is announced when it appears."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/field-label.json

@@ -35,7 +35,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "The name of a field: mono, uppercase, tracked out, one rung below body text.",
+  "summary": "The name of a field: a real `<label>`, wired to its control.",
   "examples": [
     {
       "title": "Usage",
@@ -43,10 +43,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-label",
   "mdUrl": "/docs/components/field-label.md",
   "jsonUrl": "/r/components/field-label.json",
+  "whenToUse": [
+    "Every control inside a `Field`. Clicking the label focuses — or toggles — the control it names.",
+    "Anywhere a visible name is wanted instead of an `aria-label`, which is the better default because sighted users need the name too."
+  ],
+  "whenNotToUse": [
+    "Helper text. Use `FieldDescription`, which becomes the `aria-describedby` target.",
+    "An error. Use `FieldError`."
+  ],
+  "commonMistakes": [
+    "Using a `<div>` styled to look like a label, which breaks click-to-focus and leaves the control unnamed.",
+    "Labelling a group of controls with one of these. A `RadioGroup` or `CheckboxGroup` needs a group name, not a label pointing at one member."
+  ],
   "specimens": [
     {
       "title": "Field / FieldLabel / FieldDescription / FieldError",
@@ -61,6 +73,5 @@
       "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
       "interaction": "clicking the label focuses the control; the error line is announced when it appears."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/file-tree.json

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/file-tree",
   "mdUrl": "/docs/components/file-tree.md",
   "jsonUrl": "/r/components/file-tree.json",
+  "whenToUse": [
+    "The full set of files a run changed, with per-file churn and a total across them.",
+    "A live run where files land one at a time, by raising `visibleCount`."
+  ],
+  "whenNotToUse": [
+    "One file's line-by-line change."
+  ],
+  "commonMistakes": [
+    "Passing nested `children` arrays. `nodes` is a flat list in display order and nesting comes from each node's depth.",
+    "Rendering the whole tree at once during a live run. `visibleCount` is what you raise as the run touches more files."
+  ],
   "specimens": [
     {
       "title": "FileTree",
@@ -91,6 +102,5 @@
       "note": "Everything a run touched, with the churn per file. The list is flat and the nesting is `depth`, which is what lets a row appear the moment the agent reports it rather than after its folder is complete.",
       "interaction": "rows highlight on hover to keep the eye on one line; nothing here is clickable, because the tree reports rather than navigates."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/file-upload.json

@@ -176,7 +176,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A drop zone with a file list under it.",
+  "summary": "A drop zone with a file list under it — and the zone is a real button.",
   "examples": [
     {
       "title": "Usage",
@@ -184,10 +184,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/file-upload",
   "mdUrl": "/docs/components/file-upload.md",
   "jsonUrl": "/r/components/file-upload.json",
+  "whenToUse": [
+    "Any upload. Dropping is the mouse affordance; pressing Enter on the focused zone opens the file dialog.",
+    "Uploads with rules: `accept`, `maxSize` and `maxFiles` are enforced before `onFilesAccepted`."
+  ],
+  "whenNotToUse": [
+    "A single file chosen rarely, where a plain button reads better than a target."
+  ],
+  "commonMistakes": [
+    "Rebuilding it as a `<div>` with a drop handler. A zone that only accepts drops is unusable without a pointer (WCAG 2.1.1), and it is the single most common defect in hand-rolled uploaders.",
+    "Handling only `onFilesAccepted`. Rejections are where the user learns the rule — `onFilesRejected` is not optional in practice."
+  ],
   "specimens": [
     {
       "title": "FileUpload",
@@ -199,6 +210,5 @@
       "note": "A drop zone that is also a button, so a keyboard can reach it. Rejections say which rule they broke.",
       "interaction": "the zone lights on drag-over; Enter or Space opens the file dialog."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/flow-background.json

@@ -28,10 +28,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/flow-background",
   "mdUrl": "/docs/components/flow-background.md",
   "jsonUrl": "/r/components/flow-background.json",
+  "whenToUse": [
+    "Behind any flow canvas."
+  ],
+  "whenNotToUse": [
+    "Outside React Flow."
+  ],
+  "commonMistakes": [
+    "Passing `color`. Leave it unset — it writes `--xy-background-pattern-color-props`, which outranks the theme map, so passing a colour is how you opt *out* of theming rather than how you theme it."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -45,6 +54,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/flow-controls.json

@@ -28,10 +28,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/flow-controls",
   "mdUrl": "/docs/components/flow-controls.md",
   "jsonUrl": "/r/components/flow-controls.json",
+  "whenToUse": [
+    "On any flow canvas the user pans and zooms."
+  ],
+  "whenNotToUse": [
+    "As a general toolbar. Use `Toolbar`."
+  ],
+  "commonMistakes": [
+    "Moving the shape rules into a class. `border-radius` and `overflow` have no `--xy-*` hook, so the library's own rule would win — and `overflow: hidden` is what makes the first and last buttons take the capsule's corners instead of squaring them off."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -45,6 +54,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

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/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
+  ]
 }