@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/env-var-input.json

@@ -166,7 +166,7 @@
     "--cue-text-ui",
     "--cue-warn"
   ],
-  "summary": "A config value that may be a literal *or* a reference to an environment variable — and looks unmistakably different in each case.",
+  "summary": "A config value that may be a literal or an `env(NAME)` reference — and looks unmistakably different in each case.",
   "examples": [
     {
       "title": "Usage",
@@ -174,10 +174,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/env-var-input",
   "mdUrl": "/docs/components/env-var-input.md",
   "jsonUrl": "/r/components/env-var-input.json",
+  "whenToUse": [
+    "Any config screen where some values are secrets and some name where a secret comes from.",
+    "Anywhere the difference decides whether a value is safe to screenshot, commit or paste into a ticket."
+  ],
+  "whenNotToUse": [
+    "A secret typed directly with no indirection. Use `PasswordInput`.",
+    "Ordinary configuration with no environment indirection. Use `Input`."
+  ],
+  "commonMistakes": [
+    "Rendering references as ordinary text. The warn-toned pill is the entire point: a screen of identical text boxes gives no way to tell the key from the pointer to the key.",
+    "Treating `secret` as encryption. It masks a literal on screen; it does nothing to how the value is stored or sent."
+  ],
   "specimens": [
     {
       "title": "EnvVarInput",
@@ -189,6 +201,5 @@
       "note": "A literal value and an `env(NAME)` reference are different things, so they do not look the same: the reference swaps to an amber token pill.",
       "interaction": "the mode switch is a button; typing `env(` in the field is enough to flip it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/error-state.json

@@ -73,10 +73,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/error-state",
   "mdUrl": "/docs/components/error-state.md",
   "jsonUrl": "/r/components/error-state.json",
+  "whenToUse": [
+    "A failed request inside a surface, where the retry should sit with the failure rather than interrupt."
+  ],
+  "whenNotToUse": [
+    "A failure with nothing to try again. `onRetry` is required.",
+    "A decision that must block everything until it is answered. This is deliberately not a modal."
+  ],
+  "commonMistakes": [
+    "Rendering your own spinner while retrying. `retrying` swaps the banner to a spinning Retrying status instead of the error.",
+    "Putting the whole message in `title`. `detail` is the supporting line that explains what went wrong."
+  ],
   "specimens": [
     {
       "title": "ErrorState",
@@ -88,6 +99,5 @@
       "note": "A failure banner, not a modal: it sits in the flow where the answer would have been, says what broke and what to do, and leaves the rest of the page alone. Retrying is a different element entirely rather than a disabled button — `role='alert'` while it is a failure, `role='status'` while it is trying again, which is the difference between interrupting a screen reader and not.",
       "interaction": "Retry is a named button that tints on hover. The retrying state has no control at all, because there is nothing to press while it works."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/export-dialog.json

@@ -83,7 +83,8 @@
     "--cue-space-4",
     "--cue-sunken",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps"
   ],
   "summary": "The export dialog: CSS, DTCG tokens, a `createTheme()` call and a shadcn `registry:theme` item.",
   "examples": [
@@ -93,9 +94,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/export-dialog",
   "mdUrl": "/docs/components/export-dialog.md",
   "jsonUrl": "/r/components/export-dialog.json",
-  "todo": true
+  "whenToUse": [
+    "Handing a tuned theme to code, in whichever of the four shapes the consumer needs."
+  ],
+  "whenNotToUse": [
+    "Exporting anything but the configurator's overrides. All four outputs are generated from them."
+  ],
+  "commonMistakes": [
+    "Re-deriving a value before export. Nothing here re-derives: the CSS output is literally the stylesheet on the page, which is what makes it trustworthy."
+  ]
 }

package/manifest/components/eyebrow.json

@@ -29,9 +29,10 @@
     "--cue-accent",
     "--cue-font-mono",
     "--cue-space-2",
-    "--cue-text-label"
+    "--cue-text-label",
+    "--cue-tracking-caps-loose"
   ],
-  "summary": "The small accent kicker that sits above a title: `// PATCH`.",
+  "summary": "The small accent kicker above a title: `// PATCH`.",
   "examples": [
     {
       "title": "Usage",
@@ -39,10 +40,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/eyebrow",
   "mdUrl": "/docs/components/eyebrow.md",
   "jsonUrl": "/r/components/eyebrow.json",
+  "whenToUse": [
+    "Naming the category a title belongs to, where the title alone would not say it.",
+    "Anywhere the accent should carry pure typography — this is the one place the system spends it that way."
+  ],
+  "whenNotToUse": [
+    "A status. Use `Chip`, which carries the tone vocabulary.",
+    "A second heading. An eyebrow is a kicker, not a level in the outline."
+  ],
+  "commonMistakes": [
+    "Typing the slashes into the text. They are `aria-hidden` and `select-none` for a reason — a screen reader should read \"patch\", and a copy-paste of the page should not carry punctuation that was only ever decoration."
+  ],
   "specimens": [
     {
       "title": "Eyebrow",
@@ -54,6 +66,5 @@
       "note": "The `//` motif from the brand site, in mono micro.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/feedback-dialog.json

@@ -113,10 +113,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/feedback-dialog",
   "mdUrl": "/docs/components/feedback-dialog.md",
   "jsonUrl": "/r/components/feedback-dialog.json",
+  "whenToUse": [
+    "Collecting the reason behind a negative rating, with optional free text alongside it."
+  ],
+  "whenNotToUse": [
+    "A single-choice survey. More than one reason may be picked at once."
+  ],
+  "commonMistakes": [
+    "Writing long reason strings. Keep them short enough to scan in one line.",
+    "Rendering your own thank-you. `sent` replaces the whole form with an acknowledgement once the report is filed.",
+    "Requiring `note` before submit. The free-text detail is always optional."
+  ],
   "specimens": [
     {
       "title": "FeedbackDialog",
@@ -128,6 +139,5 @@
       "note": "A thumbs-down that asks why, so the signal arrives with a reason attached. The reasons are chips rather than a select because more than one is usually true, and the note is marked optional in the header — a feedback form that demands prose collects nothing. Sending replaces the whole form with an acknowledgement.",
       "interaction": "each chip is `aria-pressed`. The acknowledgement lives in a `status` live region mounted from the start and empty until it is not — a region created together with its text is the case a screen reader is free to miss."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/field-description.json

@@ -33,9 +33,10 @@
     "--cue-space-1",
     "--cue-space-2",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps-tight"
   ],
-  "summary": "Quiet helper text under a control, published to assistive tech as the control's `aria-describedby` target.",
+  "summary": "Quiet helper text under a control, published as the control's `aria-describedby` target.",
   "examples": [
     {
       "title": "Usage",
@@ -43,10 +44,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-description",
   "mdUrl": "/docs/components/field-description.md",
   "jsonUrl": "/r/components/field-description.json",
+  "whenToUse": [
+    "A constraint or a consequence the label cannot carry: the format expected, what the value affects.",
+    "Text that should be read out after the control's name rather than as part of it."
+  ],
+  "whenNotToUse": [
+    "An error. Use `FieldError` — a description is permanent and an error is a state.",
+    "A whole paragraph. If it needs that much, the field needs a different design."
+  ],
+  "commonMistakes": [
+    "Putting the requirement only here and not in validation, so a screen reader hears the rule but nothing enforces it.",
+    "Repeating the label in other words, which makes every field announce twice."
+  ],
   "specimens": [
     {
       "title": "Field / FieldLabel / FieldDescription / FieldError",
@@ -61,6 +74,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-error.json

@@ -54,9 +54,10 @@
     "--cue-space-1",
     "--cue-space-2",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps-tight"
   ],
-  "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 +65,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 +95,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

@@ -33,9 +33,10 @@
     "--cue-space-1",
     "--cue-space-2",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps-tight"
   ],
-  "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 +44,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 +74,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.json

@@ -33,7 +33,8 @@
     "--cue-space-1",
     "--cue-space-2",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-tracking-caps-tight"
   ],
   "summary": "The label, description and validation wrapper a form control belongs in.",
   "examples": [

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/footer.json

@@ -65,6 +65,7 @@
   "defaultVariants": {},
   "tokensUsed": [
     "--cue-band-rule",
+    "--cue-band-rule-color",
     "--cue-band-y",
     "--cue-border",
     "--cue-fg-subtle",

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

@@ -158,7 +158,8 @@
     "--cue-border",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-hair-strong",
+    "--cue-paint-screen",
+    "--cue-paint-screen-size",
     "--cue-radius-control",
     "--cue-radius-surface",
     "--cue-space-2",

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