@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/disclosure.json

@@ -104,9 +104,10 @@
     "--cue-space-4",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "The \"advanced\" idiom: a chromeless `▸ advanced` toggle over the fields most users never touch.",
+  "summary": "The 'advanced' idiom: a chromeless `▸ advanced` toggle over the fields most users never touch.",
   "examples": [
     {
       "title": "Usage",
@@ -114,10 +115,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/disclosure",
   "mdUrl": "/docs/components/disclosure.md",
   "jsonUrl": "/r/components/disclosure.json",
+  "whenToUse": [
+    "Optional fields inside a form — the ones that matter to a few people and would otherwise lengthen the page for everyone.",
+    "Anywhere the toggle should read as an annotation on the form rather than a division of it."
+  ],
+  "whenNotToUse": [
+    "A section that peers with the sections around it. Use `Collapsible`.",
+    "Content the user is expected to read. Progressive disclosure hides it; if it matters, show it."
+  ],
+  "commonMistakes": [
+    "Reaching for `Collapsible` instead. It is deliberately not one: giving these fields a summary row that looks like a section header is what makes forms read as twice as long as they are.",
+    "Dressing it up with a rim or a fill. It is drawn as quietly as the system can draw anything — one triangle and micro caption ink."
+  ],
   "specimens": [
     {
       "title": "Disclosure",
@@ -129,6 +142,5 @@
       "note": "The `advanced` idiom: a chromeless mono `▸ label` toggle for the settings most people never open.",
       "interaction": "the caret rotates; nothing else moves."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/dmx-bar.json

@@ -77,7 +77,8 @@
     "--cue-text-emphasis",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "The whole universe as one strip: 512 columns, black at 0, white at 255.",
   "examples": [
@@ -87,10 +88,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/dmx-bar",
   "mdUrl": "/docs/components/dmx-bar.md",
   "jsonUrl": "/r/components/dmx-bar.json",
+  "whenToUse": [
+    "A live universe readout that must stay cheap enough to leave running at wire rate.",
+    "Under a node in a routing graph, where the shape of the output is the reading."
+  ],
+  "whenNotToUse": [
+    "Per-channel inspection. Use `ChannelMatrix`."
+  ],
+  "commonMistakes": [
+    "Re-rendering it from React state per frame. The whole design is about what happens *between* frames."
+  ],
   "specimens": [
     {
       "title": "DmxBar",
@@ -102,6 +113,5 @@
       "note": "The whole universe as one 512×1 texture, scaled up with `image-rendering: pixelated` on a true-black ground. Interpolating between two channels would draw levels nobody sent.",
       "interaction": "hovering reports `CH n · v` through a portaled readout, positioned by percentage so it survives a scaled container; the number is written to a span through a ref rather than re-rendering at 40 Hz."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/dmx-strip.json

@@ -87,7 +87,8 @@
     "--cue-text-emphasis",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "`DmxBar`'s picture with no console behind it — a lighting rig, simulated.",
   "examples": [
@@ -97,10 +98,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/dmx-strip",
   "mdUrl": "/docs/components/dmx-strip.md",
   "jsonUrl": "/r/components/dmx-strip.json",
+  "whenToUse": [
+    "Marketing and docs, where the device should look alive without a wire behind it."
+  ],
+  "whenNotToUse": [
+    "Real output. Use `DmxBar`, which draws actual channel data."
+  ],
+  "commonMistakes": [
+    "Presenting it as live data. It is a model of a plausible rig — the same canvas the bridge uses, driven by a simulation."
+  ],
   "specimens": [
     {
       "title": "DmxStrip",
@@ -112,6 +122,5 @@
       "note": "A seeded fixture simulation: mulberry32 from the `seed` prop, so the same seed draws the same rig every time. Values ramp rather than jump.",
       "interaction": "the readout updates through a ref; under prefers-reduced-motion the strip paints one static frame instead of animating."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/document-reference.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/document-reference",
   "mdUrl": "/docs/components/document-reference.md",
   "jsonUrl": "/r/components/document-reference.json",
+  "whenToUse": [
+    "Showing which passages of a source the answer drew on, each pinned to a page.",
+    "Sending the reader to the page an anchor sits on, through `onJump`."
+  ],
+  "whenNotToUse": [
+    "A source with no page structure. `pages` and per-page anchors are the shape of the element."
+  ],
+  "commonMistakes": [
+    "Assuming every page highlights something. A page with no anchor highlights nothing.",
+    "Expecting `onJump` to move `activePage` for you. It reports the page to open; the state stays yours."
+  ],
   "specimens": [
     {
       "title": "DocumentReference",
@@ -103,6 +114,5 @@
       "note": "One document the answer leans on, with the passages it quoted and the page each is on. Several anchors can cite one page — two of these are both page 31 — so the current one is marked by `aria-current` rather than by matching the number, which is what stops the wrong row lighting up.",
       "interaction": "every quote is a button that reports its page to `onJump`; the active row takes the recessed field ground, the others only on hover."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/draft-restore.json

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/draft-restore",
   "mdUrl": "/docs/components/draft-restore.md",
   "jsonUrl": "/r/components/draft-restore.json",
+  "whenToUse": [
+    "Returning to a thread that has unsent composer text saved against it.",
+    "A one-line preview of that text with when it was last touched beside it."
+  ],
+  "whenNotToUse": [
+    "A long draft you want shown in full. `draft` is truncated to one line."
+  ],
+  "commonMistakes": [
+    "Passing a timestamp to `savedAt`. It is printed as given, so pre-format it.",
+    "Wiring only `onRestore`. Without `onDiscard` the prompt has no way to go away for good."
+  ],
   "specimens": [
     {
       "title": "DraftRestore",
@@ -91,6 +102,5 @@
       "note": "Come back to a thread and the sentence you never sent is still sitting there. One line of what it was, when it was saved, and the two answers anybody ever has for it. `savedAt` is pre-formatted like every other time in this family — the element does no date maths, so a server-rendered draft and a client-rendered one cannot disagree.",
       "interaction": "restore is a worded button and discard is a labelled icon (`Discard the draft`): the destructive one is the one that has to be aimed at."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/drawer.json

@@ -174,9 +174,10 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.",
+  "summary": "A swipe-dismissable edge panel — the touch-first cousin of `Sheet`.",
   "examples": [
     {
       "title": "Usage",
@@ -184,10 +185,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/drawer",
   "mdUrl": "/docs/components/drawer.md",
   "jsonUrl": "/r/components/drawer.json",
+  "whenToUse": [
+    "Touch surfaces, where dragging a panel away is the natural dismissal.",
+    "Stacked panels: nested-drawer stacking comes from the primitive."
+  ],
+  "whenNotToUse": [
+    "Pointer-first consoles. Use `Sheet`."
+  ],
+  "commonMistakes": [
+    "Setting the edge and the gesture separately. `swipeDirection` picks both together on purpose, so a drawer can never be dragged in a direction that does not dismiss it."
+  ],
   "specimens": [
     {
       "title": "Drawer",
@@ -199,6 +210,5 @@
       "note": "The touch-first sheet: a grab handle and a swipe direction.",
       "interaction": "drag the handle to dismiss; on a pointer device it behaves as an ordinary sheet."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/dropdown-menu.json

@@ -233,7 +233,8 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "A command list hung off a button.",
   "examples": [

package/manifest/components/edit-message.json

@@ -111,10 +111,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/edit-message",
   "mdUrl": "/docs/components/edit-message.md",
   "jsonUrl": "/r/components/edit-message.json",
+  "whenToUse": [
+    "Editing a message already in the transcript, where the cost — the replies after it — should be stated before sending.",
+    "A turn that reads as a plain bubble until it is clicked, with `onStartEdit` opening the composer."
+  ],
+  "whenNotToUse": [
+    "Composing a new message. This swaps between a resting bubble and an edit composer for a turn that already exists."
+  ],
+  "commonMistakes": [
+    "Expecting `onCancel` to put the old text back. Restore the original yourself.",
+    "Passing `discardedReplies={0}` while replies exist. The warning hides at zero, which silently removes the one thing the element is for."
+  ],
   "specimens": [
     {
       "title": "EditMessage",
@@ -126,6 +137,5 @@
       "note": "Rewriting a turn you already sent, told up front what it throws away. The count is the point: editing the third message of a thread discards everything after it, and a control that hid that would be a data-loss trap wearing a pencil icon.",
       "interaction": "resting, the whole bubble is the button that starts an edit. Editing, the textarea is labelled and takes cue's focus ring; Send leads and Cancel is a ghost."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-command-palette.json

@@ -102,10 +102,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-command-palette",
   "mdUrl": "/docs/components/elements-command-palette.md",
   "jsonUrl": "/r/components/elements-command-palette.json",
+  "whenToUse": [
+    "A keystroke-away list of every runnable command in the app.",
+    "A list where the arrow keys and Enter should already work, because the element owns the key handling."
+  ],
+  "whenNotToUse": [
+    "A menu whose grouping you want to control. Groups are derived from the entries and keep first-seen order."
+  ],
+  "commonMistakes": [
+    "Adding your own arrow-key and Enter handling. The element owns the key handling and reports where it landed through `onActiveChange`.",
+    "Treating `activeId` as the element's own state. It stays yours to hold; the element only reports the move."
+  ],
   "specimens": [
     {
       "title": "ElementsCommandPalette",
@@ -117,6 +128,5 @@
       "note": "Everything the console can do, one keystroke away and grouped by where it acts. The element owns the arrow keys and reports where they landed, so the highlighted row stays the caller's state — and `aria-activedescendant` moves the highlight without moving focus, which is what keeps typing and walking the list the same gesture. Groups are derived from the commands and keep first-seen order, so the palette cannot be re-ordered by accident.",
       "interaction": "the input is a combobox over a listbox; arrows walk, Enter runs, and a query that filters the active row out drops the descendant reference rather than pointing at nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-composer.json

@@ -45,10 +45,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-composer",
   "mdUrl": "/docs/components/elements-composer.md",
   "jsonUrl": "/r/components/elements-composer.json",
+  "whenToUse": [
+    "A full message input that needs attachments, slash commands, mentions, a model picker, voice and context usage together.",
+    "A composer that has to show how much of the context window is gone alongside the input itself."
+  ],
+  "whenNotToUse": [
+    "A screen that only needs the shape of a composer rather than a working one."
+  ],
+  "commonMistakes": [
+    "Putting `ComposerInput` outside `ComposerBar`. The bar is the surface the input, the attachments and the toolbar sit on.",
+    "Hanging controls straight off `ComposerToolbar`. They go in `ComposerActions` clusters, one at each end."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -66,6 +77,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-data-table.json

@@ -55,10 +55,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-data-table",
   "mdUrl": "/docs/components/elements-data-table.md",
   "jsonUrl": "/r/components/elements-data-table.json",
+  "whenToUse": [
+    "A short comparison the model produced as part of an answer — model name, context window and cost."
+  ],
+  "whenNotToUse": [
+    "A sortable, paginated dataset. `rows` is a small `ModelUsage[]` shaped for an answer."
+  ],
+  "commonMistakes": [
+    "Holding `cycle` constant and expecting the row entrance to replay. It is an identity key that remounts the body."
+  ],
   "specimens": [
     {
       "title": "ElementsDataTable",
@@ -70,6 +79,5 @@
       "note": "A small table the model can answer with directly — three columns, no sorting, no virtualisation, no header menu. It is `ElementsDataTable` because the package already sells a real one at `@cueplusplus/ui/instruments`: that one is a data grid, this one is a paragraph shaped like a grid, and the rename keeps a consumer from reaching for the wrong one.",
       "interaction": "none. `cycle` remounts the body, so a new answer's rows stagger in rather than mutating in place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-timeline.json

@@ -57,10 +57,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-timeline",
   "mdUrl": "/docs/components/elements-timeline.md",
   "jsonUrl": "/r/components/elements-timeline.json",
+  "whenToUse": [
+    "Past and scheduled events shown together on one axis.",
+    "A run where the scheduled events should be visible before they resolve, with `visibleCount` moving as they do."
+  ],
+  "whenNotToUse": [
+    "Work that branches and rejoins rather than running along a single axis."
+  ],
+  "commonMistakes": [
+    "Passing only the resolved events. `events` holds past and scheduled together, and `visibleCount` says how many have resolved.",
+    "Ordering by resolution rather than chronologically. The events are expected in chronological order."
+  ],
   "specimens": [
     {
       "title": "ElementsTimeline",
@@ -72,6 +83,5 @@
       "note": "Events on one axis, with what already happened and what is still coming in the same list — `past`, `now` and `future` are one union, so a schedule and a history are the same component. It publishes as `ElementsTimeline` because cue already sells a `Timeline`; the spec asked for `ToolTimeline`, which turned out to be the next bench's name.",
       "interaction": "none. The now marker is the only one that pulses, and it holds still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elicitation-form.json

@@ -110,10 +110,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elicitation-form",
   "mdUrl": "/docs/components/elicitation-form.md",
   "jsonUrl": "/r/components/elicitation-form.json",
+  "whenToUse": [
+    "A server that stopped part-way through a tool call and needs fields filled before it can continue."
+  ],
+  "whenNotToUse": [
+    "A form of your own design. `fields` is the schema the server sent, already resolved to display values.",
+    "A request for permission to run something rather than for data."
+  ],
+  "commonMistakes": [
+    "Leaving `state=\"request\"` after the user answered. Accepted and declined swap the action row for the outcome.",
+    "Rewriting `message` in your own voice. It is why the input is needed, in the server's words."
+  ],
   "specimens": [
     {
       "title": "ElicitationForm",
@@ -125,6 +136,5 @@
       "note": "A server pausing mid-tool-call to ask for the fields it still needs — MCP's elicitation, drawn. The fields arrive already resolved to display values, so the element renders a schema without ever having parsed one, and `state` swaps the two buttons for the outcome the moment the user answers. Declining is a first-class answer here, not a dismissal.",
       "interaction": "each field's control is chosen by its `kind` — a value chip, a row of options, or a switch — and the required ones are marked on the label rather than announced only on failure."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-composer.json

@@ -47,10 +47,19 @@
   ],
   "summary": "A composer-shaped invitation under the suggestions.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-composer",
   "mdUrl": "/docs/components/empty-state-composer.md",
   "jsonUrl": "/r/components/empty-state-composer.json",
+  "whenToUse": [
+    "The blank-thread screen whose real composer lives somewhere else."
+  ],
+  "whenNotToUse": [
+    "A working input. It is a display rather than one — `placeholder` is a string and send takes a handler."
+  ],
+  "commonMistakes": [
+    "Omitting `onSend` and expecting a live control. Without a handler the send control renders disabled."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -66,6 +75,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-greeting.json

@@ -25,10 +25,19 @@
   ],
   "summary": "The one line at the top of a blank thread.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-greeting",
   "mdUrl": "/docs/components/empty-state-greeting.md",
   "jsonUrl": "/r/components/empty-state-greeting.json",
+  "whenToUse": [
+    "The single opening line on an empty thread."
+  ],
+  "whenNotToUse": [
+    "A second line of copy beneath it. This is the one a screen reader lands on."
+  ],
+  "commonMistakes": [
+    "Wrapping it in a heading of your own, which nests a heading inside a heading."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -44,6 +53,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-suggestion.json

@@ -36,10 +36,19 @@
   ],
   "summary": "One thing worth asking, as a pill.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-suggestion",
   "mdUrl": "/docs/components/empty-state-suggestion.md",
   "jsonUrl": "/r/components/empty-state-suggestion.json",
+  "whenToUse": [
+    "Each starter prompt offered on a blank thread."
+  ],
+  "whenNotToUse": [
+    "A standing control. It is a suggestion pill for the blank-thread screen."
+  ],
+  "commonMistakes": [
+    "Omitting `index`. It staggers the entrance so the pills arrive left to right rather than all at once."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -55,6 +64,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-suggestions.json

@@ -25,10 +25,19 @@
   ],
   "summary": "The row the suggestion pills wrap in.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-suggestions",
   "mdUrl": "/docs/components/empty-state-suggestions.md",
   "jsonUrl": "/r/components/empty-state-suggestions.json",
+  "whenToUse": [
+    "Holding the suggestion pills so they wrap as one row."
+  ],
+  "whenNotToUse": [
+    "Anything other than the suggestion pills."
+  ],
+  "commonMistakes": [
+    "Laying the pills out with a flex row of your own, which drops the wrapping the element already provides."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -44,6 +53,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state.json

@@ -83,7 +83,7 @@
     "--cue-text-emphasis",
     "--cue-text-ui"
   ],
-  "summary": "The \"there is nothing here\" panel body.",
+  "summary": "The 'there is nothing here' panel body — a report, not an alarm.",
   "examples": [
     {
       "title": "Usage",
@@ -91,10 +91,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state",
   "mdUrl": "/docs/components/empty-state.md",
   "jsonUrl": "/r/components/empty-state.json",
+  "whenToUse": [
+    "A list, table or panel with no rows, where the reader needs to know why and what to do next.",
+    "Anywhere an action would help: `action` is the slot for the one thing that fills the emptiness."
+  ],
+  "whenNotToUse": [
+    "An error. Emptiness is a state; a failure needs its own tone and a way to retry.",
+    "Loading. Use `Skeleton` or `Spinner` — an empty state says nothing is coming."
+  ],
+  "commonMistakes": [
+    "Colouring it to draw attention. It uses the muted ramp throughout and takes its emphasis from position; an alarming empty state reports a problem that is not there.",
+    "Putting the meaning in the icon. The icon is decorative — the title carries it, so a screen reader hears one sentence instead of a shrug."
+  ],
   "specimens": [
     {
       "title": "EmptyState",
@@ -106,6 +118,5 @@
       "note": "The standard empty copy, from lib/samples.tsx. Same words everywhere in the app.",
       "interaction": "the action is an ordinary Button and behaves like one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/end-of-turn-summary.json

@@ -69,10 +69,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/end-of-turn-summary",
   "mdUrl": "/docs/components/end-of-turn-summary.md",
   "jsonUrl": "/r/components/end-of-turn-summary.json",
+  "whenToUse": [
+    "The closing line of a turn, saying what it came to.",
+    "A turn whose result is not a diff at all, using `label` to replace the built line: `2 cues written`, `Nothing to change`."
+  ],
+  "whenNotToUse": [
+    "Anywhere you want review, keep or reject buttons. It is a rollup, not a control — those belong to a bar above the composer that acts on the whole run.",
+    "A turn that read files and wrote nothing but which you want reported as two zeroes. It says `No files changed` and stops."
+  ],
+  "commonMistakes": [
+    "Adding per-turn action buttons beside it. A per-turn row with those buttons on it is a row that can be pressed after the next turn has already changed the same files.",
+    "Passing `additions={0}` and `deletions={0}` to force the counts out. The counts are drawn only when there are some."
+  ],
   "specimens": [
     {
       "title": "EndOfTurnSummary",
@@ -84,6 +96,5 @@
       "note": "What the turn came to, in one line. A rollup and not a control: review, keep and reject act on the whole run and belong above the composer, where they cannot be pressed after the next turn has already changed the same files. The + and − are CodeDiff's glyphs, so one transcript never shows two conventions for the same number, and a turn that changed nothing says so instead of saying it with two zeroes.",
       "interaction": "none. It is a sentence with two tinted numbers in it."
     }
-  ],
-  "todo": true
+  ]
 }