@cueplusplus/ui 0.13.0

package/manifest/components/activity-graph.json

@@ -0,0 +1,104 @@
+{
+  "name": "ActivityGraph",
+  "slug": "activity-graph",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "heat-graph"
+  ],
+  "clientOnly": true,
+  "description": "A half-year of runs as a calendar of cells, dense where the work was.",
+  "props": [
+    {
+      "name": "data",
+      "type": "readonly DataPoint[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Date and count pairs from the heat-graph package. Levels are classified for you;\ngaps are filled as empty cells.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.run-days"
+      }
+    },
+    {
+      "name": "start",
+      "type": "string | Date",
+      "required": true,
+      "defaultValue": null,
+      "description": "First day of the window. Pass it explicitly: left unset, heat-graph draws a full\nyear ending today, which will not match your data.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "end",
+      "type": "string | Date",
+      "required": true,
+      "defaultValue": null,
+      "description": "Last day of the window. Cells are fixed-size, so a long window scrolls\nhorizontally rather than shrinking.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is being counted.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "total",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted summary shown opposite the title.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"data\" | \"start\" | \"end\" | \"title\" | \"total\"\n> & {\n  /**\n   * Date and count pairs from the heat-graph package. Levels are classified for you;\n   * gaps are filled as empty cells.\n   */\n  data: readonly HeatGraph.DataPoint[];\n  /**\n   * First day of the window. Pass it explicitly: left unset, heat-graph draws a full\n   * year ending today, which will not match your data.\n   */\n  start: string | Date;\n  /**\n   * Last day of the window. Cells are fixed-size, so a long window scrolls\n   * horizontally rather than shrinking.\n   */\n  end: string | Date;\n  /** What is being counted. */\n  title: string;\n  /** Pre-formatted summary shown opposite the title. */\n  total: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "A half-year of runs as a calendar of cells, dense where the work was.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ActivityGraph } from \"@cueplusplus/ui/elements\";\n\n<ActivityGraph\n  data={data}\n  start={start}\n  end={end}\n  title=\"Agent runs\"\n  total=\"1,204 in 6 months\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/activity-graph",
+  "mdUrl": "/docs/components/activity-graph.md",
+  "jsonUrl": "/r/components/activity-graph.json",
+  "specimens": [
+    {
+      "title": "ActivityGraph",
+      "group": "elements-agents",
+      "components": [
+        "ActivityGraph"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"six months\" wide>\n    <ActivityGraph\n      data={RUN_DAYS}\n      start=\"2026-02-01\"\n      end=\"2026-08-21\"\n      title=\"Agent runs\"\n      total=\"1,204 in 6 months\"\n    />\n  </Specimen>\n  <Specimen label=\"a fortnight\" wide>\n    <ActivityGraph\n      data={RECENT_DAYS}\n      start={RECENT_DAYS[0]!.date}\n      end={RECENT_DAYS[RECENT_DAYS.length - 1]!.date}\n      title=\"Agent runs\"\n      total=\"63 in 14 days\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Half a year of runs as a calendar of cells, dense where the work was. It is the one element in the family with a runtime dependency of its own — `heat-graph`, an optional peer — which does the calendar arithmetic and the levelling; everything you can see here is cue's, from the five-step ramp in the streaming hue down to the legend. Cells are a fixed size, so a long window scrolls sideways rather than shrinking into a smudge.",
+      "interaction": "none. The five legend swatches are `aria-hidden` and sit between the words less and more, which is what carries the scale."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-card.json

@@ -0,0 +1,150 @@
+{
+  "name": "AgentCard",
+  "slug": "agent-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Who you are about to talk to: its skills, its model, and the endpoint behind it.",
+  "props": [
+    {
+      "name": "name",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Display name of the agent.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What it does, in one or two sentences.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "provider",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Who publishes it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "version",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Card version, printed next to the name.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "model",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Model the agent runs on.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "endpoint",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Where it is reached. Truncates rather than wraps.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "skills",
+      "type": "readonly AgentSkill[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Named capabilities the card advertises.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.skills"
+      }
+    },
+    {
+      "name": "connected",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the action for a settled Connected state and disables it.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onConnect",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the agent is added.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"name\"\n  | \"description\"\n  | \"provider\"\n  | \"version\"\n  | \"model\"\n  | \"endpoint\"\n  | \"skills\"\n  | \"connected\"\n  | \"onConnect\"\n> & {\n  /** Display name of the agent. */\n  name: string;\n  /** What it does, in one or two sentences. */\n  description: string;\n  /** Who publishes it. */\n  provider: string;\n  /** Card version, printed next to the name. */\n  version: string;\n  /** Model the agent runs on. */\n  model: string;\n  /** Where it is reached. Truncates rather than wraps. */\n  endpoint: string;\n  /** Named capabilities the card advertises. */\n  skills: readonly AgentSkill[];\n  /** Swaps the action for a settled Connected state and disables it. */\n  connected: boolean;\n  /** Called when the agent is added. */\n  onConnect?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Who you are about to talk to: its skills, its model, and the endpoint behind it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentCard } from \"@cueplusplus/ui/elements\";\n\n<AgentCard\n  name=\"Maintainer\"\n  description=\"Reproduces the report, writes the fix, opens the PR.\"\n  provider=\"assistant-ui\"\n  version=\"1.4.0\"\n  model=\"opus\"\n  endpoint=\"https://agents.example.com/a2a\"\n  skills={skills}\n  connected={false}\n  onConnect={connect}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-card",
+  "mdUrl": "/docs/components/agent-card.md",
+  "jsonUrl": "/r/components/agent-card.json",
+  "specimens": [
+    {
+      "title": "AgentCard",
+      "group": "elements-agents",
+      "components": [
+        "AgentCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"not connected\">\n    <AgentCard\n      name=\"Patch\"\n      description=\"Assigns fixtures to universes and addresses, then redraws the plot to match. It will not touch a live desk.\"\n      provider=\"cue++ internal\"\n      version=\"2.4\"\n      model=\"Opus 5\"\n      endpoint=\"agents.cue.internal/patch\"\n      skills={SKILLS}\n      connected={connected}\n      onConnect={() => setConnected(true)}\n    />\n  </Specimen>\n  <Specimen label=\"connected\">\n    <AgentCard\n      name=\"Patch\"\n      description=\"Assigns fixtures to universes and addresses, then redraws the plot to match.\"\n      provider=\"cue++ internal\"\n      version=\"2.4\"\n      model=\"Opus 5\"\n      endpoint=\"agents.cue.internal/patch\"\n      skills={SKILLS.slice(0, 2)}\n      connected\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Who you are about to talk to, before you talk to it: the name and who publishes it, one paragraph on what it is for, the skills it advertises, and — in mono along the bottom — the model and the endpoint actually behind it. Those last two are the line that separates a card from a marketing tile.",
+      "interaction": "the action is the only control. Connected disables it and swaps the ink button for a settled field row with a tick, rather than greying out a button that still looks pressable."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-handoff.json

@@ -0,0 +1,104 @@
+{
+  "name": "AgentHandoff",
+  "slug": "agent-handoff",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Control passing between agents, with the reason and what came along.",
+  "props": [
+    {
+      "name": "from",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent giving up control.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "to",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent taking it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "reason",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why the baton moved. Without it a handoff reads as an unexplained jump.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "carried",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Context that travelled across. Pass an empty array to hide the section.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "settled",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Cools the arrow and the receiving badge once the new agent is underway.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"from\" | \"to\" | \"reason\" | \"carried\" | \"settled\"\n> & {\n  /** Agent giving up control. */\n  from: string;\n  /** Agent taking it. */\n  to: string;\n  /** Why the baton moved. Without it a handoff reads as an unexplained jump. */\n  reason: string;\n  /** Context that travelled across. Pass an empty array to hide the section. */\n  carried: readonly string[];\n  /** Cools the arrow and the receiving badge once the new agent is underway. */\n  settled: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-stream",
+    "--cue-text-ui"
+  ],
+  "summary": "Control passing between agents, with the reason and what came along.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentHandoff } from \"@cueplusplus/ui/elements\";\n\n<AgentHandoff from=\"Triage\" to=\"Maintainer\" reason={reason} carried={carried} settled />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-handoff",
+  "mdUrl": "/docs/components/agent-handoff.md",
+  "jsonUrl": "/r/components/agent-handoff.json",
+  "specimens": [
+    {
+      "title": "AgentHandoff",
+      "group": "elements-agents",
+      "components": [
+        "AgentHandoff"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"live\" wide>\n    <AgentHandoff\n      from=\"Patch\"\n      to=\"Plot\"\n      reason=\"Addresses are assigned; redrawing the hanging plot needs the drawing agent.\"\n      carried={[\n        \"Universe 3, channels 1–48\",\n        \"Six ESPRITEs on 3.2 m centres\",\n        \"Front truss at 8.4 m trim\",\n      ]}\n      settled={false}\n    />\n  </Specimen>\n  <Specimen label=\"settled, nothing carried\" wide>\n    <AgentHandoff\n      from=\"Plot\"\n      to=\"Check\"\n      reason=\"Plot is redrawn. The walk-the-rig pass starts from the file, not from this thread.\"\n      carried={[]}\n      settled\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The baton moving, with the reason attached. Two badges and an arrow: while the handoff is live the receiving agent and the arrow take the streaming hue, and `settled` cools both once the new agent is actually underway. What travelled across is listed under it against a rule — a handoff with no carried context is a handoff you cannot audit.",
+      "interaction": "none. It is a record of something that happened, not a control; the only thing that moves is the colour, over half a second."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-mode-badge.json

@@ -0,0 +1,102 @@
+{
+  "name": "AgentModeBadge",
+  "slug": "agent-mode-badge",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What the run is allowed to do, said in one chip and one attribute.\n\nAgent authority is the fact a person most needs from the corner of their eye\nand the one every catalogue leaves to prose. This is the readout: a glyph, a\nword, and `data-agent-mode` on the element. The attribute is the part that\ntravels — `@cueplusplus/ui/elements.css` declares four custom properties\nunder it, so putting the same attribute on a composer tints its focus ring,\nits send button and its rail from one place, and a console adds a\nmode-aware surface by reading a property rather than by threading a prop:\n\n```css\n.composer:focus-within { border-color: var(--cue-elements-mode-icon); }\n.send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }\n.turn-rail { background: var(--cue-elements-mode-border); }\n```\n\nThe ladder is four rungs and the mode set is open. Every product in the study\npaints six, seven or nine modes in exactly four accents — will it ask me, is\nit writing, is it only planning, are the guardrails off — so the rung is what\n`mode` carries and the product's own word is what `label` carries.\n\nThe properties resolve against the *element that carries the attribute*, not\nagainst the page: a badge inside an `<AgentSurface skin=\"aui\">` takes the\nisland's palette, because the quadruple is declared on `[data-agent-mode]`\nrather than at `:root` where a `var()` would have been substituted before it\never reached the island.",
+  "props": [
+    {
+      "name": "mode",
+      "type": "\"manual\" | \"auto-edit\" | \"plan\" | \"unsafe\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "How much authority the run is holding: `manual`, `auto-edit`, `plan` or\n`unsafe`. Stamped as `data-agent-mode`, which is what the quadruple in\n`@cueplusplus/ui/elements.css` is keyed on.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "manual",
+          "auto-edit",
+          "plan",
+          "unsafe"
+        ]
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The product's own word for it — `Agent`, `Build`, `YOLO`, `Bypass\npermissions`. Defaults to `AGENT_MODE_LABELS[mode]`, and it is the reason\na nine-mode product needs no more than these four rungs.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the mode actually does, as the badge's `title`. Defaults to\n`AGENT_MODE_DESCRIPTIONS[mode]`. Pass `\"\"` for no tooltip at all.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop) — `render={<button\ntype=\"button\" onClick={cycle} />}` for a picker that cycles, which is what\nevery product with more than two modes ships.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-elements-mode-background",
+    "--cue-elements-mode-border",
+    "--cue-elements-mode-icon",
+    "--cue-elements-mode-text",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "What the run is allowed to do, said in one chip and one attribute.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentModeBadge } from \"@cueplusplus/ui/elements\";\n\n<AgentModeBadge mode=\"plan\" />\n// A product's own word on cue's rung, and a chip that cycles.\n<AgentModeBadge\n  mode=\"unsafe\"\n  label=\"YOLO\"\n  render={<button type=\"button\" onClick={cycle} />}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-mode-badge",
+  "mdUrl": "/docs/components/agent-mode-badge.md",
+  "jsonUrl": "/r/components/agent-mode-badge.json",
+  "specimens": [
+    {
+      "title": "AgentModeBadge",
+      "group": "elements",
+      "components": [
+        "AgentModeBadge"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the four rungs\">\n    <span className=\"flex flex-wrap items-center gap-(--cue-space-2)\">\n      {AGENT_MODES.map((rung) => (\n        <AgentModeBadge key={rung} mode={rung} />\n      ))}\n    </span>\n  </Specimen>\n  <Specimen label={`one attribute, four surfaces · ${AGENT_MODE_LABELS[mode]}`} wide>\n    <div\n      data-agent-mode={mode}\n      className=\"flex w-full max-w-md items-center gap-(--cue-space-3) rounded-(--radius-surface) border bg-surface-1 p-(--cue-space-3)\"\n      style={{ borderColor: \"var(--cue-elements-mode-border)\" }}\n    >\n      <span\n        aria-hidden\n        className=\"h-9 w-0.5 shrink-0 rounded-full\"\n        style={{ background: \"var(--cue-elements-mode-icon)\" }}\n      />\n      <span className=\"flex min-w-0 flex-1 flex-col gap-(--cue-space-1)\">\n        <AgentModeBadge\n          mode={mode}\n          className=\"self-start\"\n          render={\n            <button\n              type=\"button\"\n              onClick={() =>\n                setMode(\n                  AGENT_MODES[\n                    (AGENT_MODES.indexOf(mode) + 1) % AGENT_MODES.length\n                  ] as AgentMode,\n                )\n              }\n            />\n          }\n        />\n        <span className=\"text-fg-muted truncate text-(length:--cue-text-ui)\">\n          Patch the front truss and write cue 1\n        </span>\n      </span>\n      <button\n        type=\"button\"\n        className=\"shrink-0 rounded-full px-(--cue-space-3) py-(--cue-space-1) text-(length:--cue-text-label) font-medium\"\n        style={{\n          background: \"var(--cue-elements-mode-icon)\",\n          color: \"var(--cue-bg)\",\n        }}\n      >\n        Send\n      </button>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "How much authority the run is holding, which is the fact a person most needs from the corner of their eye and the one every catalogue leaves to prose. The ladder is four rungs — will it ask me, is it writing, is it only planning, are the guardrails off — because that is how many accents every product in the study paints, whatever it calls its six or seven or nine modes. The chip is the readout; `data-agent-mode` is the part that travels.",
+      "interaction": "press the chip to cycle the rung. The second specimen is the whole point: one attribute on the box, and the rail, the border and the send button all re-derive from `var(--cue-elements-mode-icon)` with no prop threading and no branch in any component. Colour is never alone — each rung has its own glyph and its own word, so the ladder survives a monochrome screenshot."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-pile.json

@@ -0,0 +1,147 @@
+{
+  "name": "AgentPile",
+  "slug": "agent-pile",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The roster of agents working on a thread, stacked into one object.\n\nThree states ride on each avatar, and none of them is colour-only: the\norchestrator wears a crown, a working agent gets a spinning arc, and an agent\nwaiting on the user gets a `?` badge — each of them also spelled into the\navatar's accessible name, so a screen reader hears \"Researcher · working\"\nrather than nothing at all.\n\nAvatars are outlined in the agent's colour rather than filled with it. A fill\nwould put arbitrary-hue ink on an arbitrary-hue ground at 20px; the outline\ntreatment is the same tinted-chip recipe the rest of the system uses and\nstays legible on every theme.",
+  "props": [
+    {
+      "name": "agents",
+      "type": "readonly AgentPileEntry[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roster, in the order it should read. Renders nothing when empty.",
+      "control": {
+        "kind": "array",
+        "fixture": "chat.agents"
+      }
+    },
+    {
+      "name": "root",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator: takes the theme accent and wears the crown.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "selected",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the lane currently open — that avatar gets a ring.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((slug: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with a slug when an avatar is pressed. Omit for a read-only pile.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Show at most this many; the rest collapse into a `+N` chip.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "fanned",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Force the fan open or shut. Omit to let hover and focus decide.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the group. Required in practice — name the roster.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The roster of agents working on a thread, stacked into one object.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AgentPile aria-label=\"Agents\" agents={roster} root=\"chief\" onSelect={openLane} />\n<AgentPile aria-label=\"Agents\" agents={roster} max={5} fanned />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-pile",
+  "mdUrl": "/docs/components/agent-pile.md",
+  "jsonUrl": "/r/components/agent-pile.json",
+  "specimens": [
+    {
+      "title": "AgentPile",
+      "group": "chat",
+      "components": [
+        "AgentPile"
+      ],
+      "code": "<Specimens>\n  {([\"sm\", \"md\", \"lg\"] as const).map((size) => (\n    <Specimen key={size} label={size}>\n      <AgentPile agents={AGENTS} root=\"orchestrator\" size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"max 4\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" max={4} />\n  </Specimen>\n  <Specimen label=\"not fanned\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" fanned={false} />\n  </Specimen>\n  <Specimen label=\"selected\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" selected=\"patcher\" />\n  </Specimen>\n</Specimens>",
+      "note": "Faces at −12px overlap, fanning to +4px on hover. The crown marks the orchestrator, an arc marks work in flight and a `?` marks an agent waiting on an answer.",
+      "interaction": "every face is a button with the agent's name; the pile is one tab stop and arrow keys move inside it."
+    }
+  ],
+  "todo": true
+}