From 5b6080b80ef5f395d5a76f57d1284bc32f97738e Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Mon, 3 Aug 2026 22:56:27 -0700
Subject: [PATCH 1/7] CMP-1 chore: add agent interface skills

---
 .agents/skills/ai-sdk/SKILL.md                |  78 ++++
 .agents/skills/better-accessibility/SKILL.md  | 148 +++++++
 .../better-accessibility/agents/openai.yaml   |   3 +
 .../focus-and-keyboard.md                     | 131 ++++++
 .agents/skills/better-accessibility/forms.md  |  86 ++++
 .../skills/better-accessibility/hit-areas.md  |  76 ++++
 .../better-accessibility/motion-and-zoom.md   |  79 ++++
 .../better-accessibility/screen-readers.md    | 101 +++++
 .../semantics-and-aria.md                     |  83 ++++
 .agents/skills/better-colors/SKILL.md         | 113 +++++
 .../better-colors/accessibility-contrast.md   |  87 ++++
 .../skills/better-colors/agents/openai.yaml   |   3 +
 .../skills/better-colors/color-conversion.md  |  53 +++
 .agents/skills/better-colors/color-usage.md   |  94 ++++
 .../better-colors/gamut-and-tailwind.md       | 103 +++++
 .../better-colors/palette-generation.md       |  93 ++++
 .agents/skills/better-interface/SKILL.md      | 138 ++++++
 .../better-interface/agents/openai.yaml       |   5 +
 .agents/skills/better-layout/SKILL.md         | 114 +++++
 .../skills/better-layout/agents/openai.yaml   |   3 +
 .../better-layout/grouping-and-alignment.md   | 123 ++++++
 .../better-layout/spacing-and-adaptivity.md   | 159 +++++++
 .agents/skills/better-typography/SKILL.md     | 171 ++++++++
 .../better-typography/agents/openai.yaml      |   3 +
 .../better-typography/choosing-fonts.md       |  64 +++
 .../better-typography/css-cheat-sheet.md      |  65 +++
 .../details-and-accessibility.md              | 109 +++++
 .../better-typography/spacing-and-sizing.md   | 126 ++++++
 .../variable-fonts-and-opentype.md            | 105 +++++
 .../wrapping-and-punctuation.md               |  58 +++
 .agents/skills/better-ui/SKILL.md             | 141 ++++++
 .agents/skills/better-ui/agents/openai.yaml   |   3 +
 .agents/skills/better-ui/animations.md        | 404 ++++++++++++++++++
 .agents/skills/better-ui/icons.md             | 110 +++++
 .agents/skills/better-ui/performance.md       |  88 ++++
 .agents/skills/better-ui/surfaces.md          | 219 ++++++++++
 .agents/skills/better-writing/SKILL.md        | 145 +++++++
 .../skills/better-writing/agents/openai.yaml  |   3 +
 .claude/skills/ai-sdk/SKILL.md                |  78 ++++
 .claude/skills/better-accessibility/SKILL.md  | 148 +++++++
 .../better-accessibility/agents/openai.yaml   |   3 +
 .../focus-and-keyboard.md                     | 131 ++++++
 .claude/skills/better-accessibility/forms.md  |  86 ++++
 .../skills/better-accessibility/hit-areas.md  |  76 ++++
 .../better-accessibility/motion-and-zoom.md   |  79 ++++
 .../better-accessibility/screen-readers.md    | 101 +++++
 .../semantics-and-aria.md                     |  83 ++++
 .claude/skills/better-colors/SKILL.md         | 113 +++++
 .../better-colors/accessibility-contrast.md   |  87 ++++
 .../skills/better-colors/agents/openai.yaml   |   3 +
 .../skills/better-colors/color-conversion.md  |  53 +++
 .claude/skills/better-colors/color-usage.md   |  94 ++++
 .../better-colors/gamut-and-tailwind.md       | 103 +++++
 .../better-colors/palette-generation.md       |  93 ++++
 .claude/skills/better-interface/SKILL.md      | 138 ++++++
 .../better-interface/agents/openai.yaml       |   5 +
 .claude/skills/better-layout/SKILL.md         | 114 +++++
 .../skills/better-layout/agents/openai.yaml   |   3 +
 .../better-layout/grouping-and-alignment.md   | 123 ++++++
 .../better-layout/spacing-and-adaptivity.md   | 159 +++++++
 .claude/skills/better-typography/SKILL.md     | 171 ++++++++
 .../better-typography/agents/openai.yaml      |   3 +
 .../better-typography/choosing-fonts.md       |  64 +++
 .../better-typography/css-cheat-sheet.md      |  65 +++
 .../details-and-accessibility.md              | 109 +++++
 .../better-typography/spacing-and-sizing.md   | 126 ++++++
 .../variable-fonts-and-opentype.md            | 105 +++++
 .../wrapping-and-punctuation.md               |  58 +++
 .claude/skills/better-ui/SKILL.md             | 141 ++++++
 .claude/skills/better-ui/agents/openai.yaml   |   3 +
 .claude/skills/better-ui/animations.md        | 404 ++++++++++++++++++
 .claude/skills/better-ui/icons.md             | 110 +++++
 .claude/skills/better-ui/performance.md       |  88 ++++
 .claude/skills/better-ui/surfaces.md          | 219 ++++++++++
 .claude/skills/better-writing/SKILL.md        | 145 +++++++
 .../skills/better-writing/agents/openai.yaml  |   3 +
 AGENTS.md                                     |  52 +++
 CLAUDE.md                                     |  52 +++
 skills-lock.json                              |  48 +++
 79 files changed, 7526 insertions(+)
 create mode 100644 .agents/skills/ai-sdk/SKILL.md
 create mode 100644 .agents/skills/better-accessibility/SKILL.md
 create mode 100644 .agents/skills/better-accessibility/agents/openai.yaml
 create mode 100644 .agents/skills/better-accessibility/focus-and-keyboard.md
 create mode 100644 .agents/skills/better-accessibility/forms.md
 create mode 100644 .agents/skills/better-accessibility/hit-areas.md
 create mode 100644 .agents/skills/better-accessibility/motion-and-zoom.md
 create mode 100644 .agents/skills/better-accessibility/screen-readers.md
 create mode 100644 .agents/skills/better-accessibility/semantics-and-aria.md
 create mode 100644 .agents/skills/better-colors/SKILL.md
 create mode 100644 .agents/skills/better-colors/accessibility-contrast.md
 create mode 100644 .agents/skills/better-colors/agents/openai.yaml
 create mode 100644 .agents/skills/better-colors/color-conversion.md
 create mode 100644 .agents/skills/better-colors/color-usage.md
 create mode 100644 .agents/skills/better-colors/gamut-and-tailwind.md
 create mode 100644 .agents/skills/better-colors/palette-generation.md
 create mode 100644 .agents/skills/better-interface/SKILL.md
 create mode 100644 .agents/skills/better-interface/agents/openai.yaml
 create mode 100644 .agents/skills/better-layout/SKILL.md
 create mode 100644 .agents/skills/better-layout/agents/openai.yaml
 create mode 100644 .agents/skills/better-layout/grouping-and-alignment.md
 create mode 100644 .agents/skills/better-layout/spacing-and-adaptivity.md
 create mode 100644 .agents/skills/better-typography/SKILL.md
 create mode 100644 .agents/skills/better-typography/agents/openai.yaml
 create mode 100644 .agents/skills/better-typography/choosing-fonts.md
 create mode 100644 .agents/skills/better-typography/css-cheat-sheet.md
 create mode 100644 .agents/skills/better-typography/details-and-accessibility.md
 create mode 100644 .agents/skills/better-typography/spacing-and-sizing.md
 create mode 100644 .agents/skills/better-typography/variable-fonts-and-opentype.md
 create mode 100644 .agents/skills/better-typography/wrapping-and-punctuation.md
 create mode 100644 .agents/skills/better-ui/SKILL.md
 create mode 100644 .agents/skills/better-ui/agents/openai.yaml
 create mode 100644 .agents/skills/better-ui/animations.md
 create mode 100644 .agents/skills/better-ui/icons.md
 create mode 100644 .agents/skills/better-ui/performance.md
 create mode 100644 .agents/skills/better-ui/surfaces.md
 create mode 100644 .agents/skills/better-writing/SKILL.md
 create mode 100644 .agents/skills/better-writing/agents/openai.yaml
 create mode 100644 .claude/skills/ai-sdk/SKILL.md
 create mode 100644 .claude/skills/better-accessibility/SKILL.md
 create mode 100644 .claude/skills/better-accessibility/agents/openai.yaml
 create mode 100644 .claude/skills/better-accessibility/focus-and-keyboard.md
 create mode 100644 .claude/skills/better-accessibility/forms.md
 create mode 100644 .claude/skills/better-accessibility/hit-areas.md
 create mode 100644 .claude/skills/better-accessibility/motion-and-zoom.md
 create mode 100644 .claude/skills/better-accessibility/screen-readers.md
 create mode 100644 .claude/skills/better-accessibility/semantics-and-aria.md
 create mode 100644 .claude/skills/better-colors/SKILL.md
 create mode 100644 .claude/skills/better-colors/accessibility-contrast.md
 create mode 100644 .claude/skills/better-colors/agents/openai.yaml
 create mode 100644 .claude/skills/better-colors/color-conversion.md
 create mode 100644 .claude/skills/better-colors/color-usage.md
 create mode 100644 .claude/skills/better-colors/gamut-and-tailwind.md
 create mode 100644 .claude/skills/better-colors/palette-generation.md
 create mode 100644 .claude/skills/better-interface/SKILL.md
 create mode 100644 .claude/skills/better-interface/agents/openai.yaml
 create mode 100644 .claude/skills/better-layout/SKILL.md
 create mode 100644 .claude/skills/better-layout/agents/openai.yaml
 create mode 100644 .claude/skills/better-layout/grouping-and-alignment.md
 create mode 100644 .claude/skills/better-layout/spacing-and-adaptivity.md
 create mode 100644 .claude/skills/better-typography/SKILL.md
 create mode 100644 .claude/skills/better-typography/agents/openai.yaml
 create mode 100644 .claude/skills/better-typography/choosing-fonts.md
 create mode 100644 .claude/skills/better-typography/css-cheat-sheet.md
 create mode 100644 .claude/skills/better-typography/details-and-accessibility.md
 create mode 100644 .claude/skills/better-typography/spacing-and-sizing.md
 create mode 100644 .claude/skills/better-typography/variable-fonts-and-opentype.md
 create mode 100644 .claude/skills/better-typography/wrapping-and-punctuation.md
 create mode 100644 .claude/skills/better-ui/SKILL.md
 create mode 100644 .claude/skills/better-ui/agents/openai.yaml
 create mode 100644 .claude/skills/better-ui/animations.md
 create mode 100644 .claude/skills/better-ui/icons.md
 create mode 100644 .claude/skills/better-ui/performance.md
 create mode 100644 .claude/skills/better-ui/surfaces.md
 create mode 100644 .claude/skills/better-writing/SKILL.md
 create mode 100644 .claude/skills/better-writing/agents/openai.yaml

diff --git a/.agents/skills/ai-sdk/SKILL.md b/.agents/skills/ai-sdk/SKILL.md
new file mode 100644
index 00000000..19eb3ee3
--- /dev/null
+++ b/.agents/skills/ai-sdk/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: ai-sdk
+description: 'Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".'
+---
+
+## What the AI SDK Is
+
+The AI SDK by Vercel (the `ai` package on npm) is a TypeScript toolkit for building AI applications. It provides a unified API across model providers for text generation, structured output, tool calling, agents, embeddings, and framework UI integrations.
+
+- Repository: https://github.com/vercel/ai
+- Documentation: https://ai-sdk.dev/docs
+
+## Critical: Do Not Trust Your Own Memory
+
+Whatever you remember about the AI SDK is likely outdated. The SDK changes frequently across versions - APIs are renamed, removed, and added. Your training data almost certainly contains obsolete APIs, deprecated patterns, and model IDs that no longer exist. UI hooks like `useChat` are among the most frequently changed APIs, so be especially careful with client code.
+
+**Never write AI SDK code from memory.** Always verify every API, option, and pattern against the documentation and source code for the version that is actually installed in the project.
+
+## Use the Bundled, Version-Matched Docs
+
+The `ai` package ships its full documentation and source code inside `node_modules`. These always match the installed version, so trust them over anything you remember.
+
+1. Ensure `ai` is installed. If `node_modules/ai/` does not exist, install **only** the `ai` package using the project's package manager (e.g. `pnpm add ai`). Install provider packages (e.g. `@ai-sdk/openai`) and framework packages (e.g. `@ai-sdk/react`) later, when the task requires them.
+2. Read and grep the bundled docs at `node_modules/ai/docs/` and the source at `node_modules/ai/src/`.
+3. Provider and framework packages bundle their own docs at `node_modules/@ai-sdk/<name>/docs/`.
+4. If something isn't in the bundled docs, search https://ai-sdk.dev/docs. You can append `.md` to any docs page URL to get its markdown, and search via `https://ai-sdk.dev/api/search-docs?q=your_query`.
+5. If you cannot find support for an answer in the docs or source, say so explicitly — do not guess.
+
+## AI Gateway: The Fastest Way to Start
+
+The Vercel AI Gateway is the fastest way to get started with the AI SDK. It provides access to models from OpenAI, Anthropic, Google, and other providers through a single API, without installing provider packages or managing multiple API keys.
+
+To set it up:
+
+1. Authenticate with OIDC (for Vercel deployments) or get an AI Gateway API key.
+2. Provide it to your app via the `AI_GATEWAY_API_KEY` environment variable.
+3. Reference models with `provider/model` strings.
+
+For exact setup, authentication, and usage, read the bundled guide and the AI Gateway docs.
+
+### Choosing a Model
+
+Never use model IDs from memory — models are released and retired frequently. Fetch the current list before writing code that references a model. Do not truncate the list (e.g. with `head`) so you can find the newest models:
+
+```bash
+# All available models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '.data[].id'
+
+# Filter by provider (e.g. anthropic, openai, google)
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("anthropic/")) | .id] | reverse | .[]'
+```
+
+When multiple versions of a model exist, prefer the one with the highest version number.
+
+## Building and Consuming Agents
+
+Use the SDK's built-in agent abstraction (such as `ToolLoopAgent`) rather than hand-rolling tool-calling loops. For end-to-end type safety, infer the UI message type from your agent definition when consuming it on the client (e.g. with `useChat`). Consuming an agent is framework-specific: check `package.json` to detect the stack, then follow the matching quickstart.
+
+Look up the current agent, tool, and type-safety APIs in the bundled docs (`node_modules/ai/docs/`, especially the agents section) or at https://ai-sdk.dev/docs.
+
+## DevTools
+
+AI SDK DevTools captures your AI SDK calls - requests, responses, tool calls, token usage, and multi-step runs - so you can inspect exactly what your agents do. Use it while developing to debug generations. It is a separate package and is intended for local development only.
+
+For setup instructions, read the bundled DevTools documentation.
+
+## Keep the SDK Current
+
+Outdated installs are the most common source of errors. Compare the installed version against the latest:
+
+- **Installed:** the `version` field in `node_modules/ai/package.json`.
+- **Latest:** run `npm view ai version`.
+
+If the installed version is a major version (or more) behind the latest, tell the user they are on an old release, and recommend upgrading before continuing. Migration guides are at https://ai-sdk.dev/docs/migration-guides.
+
+## After Making Changes
+
+Run the project's type checker. Be minimal — only set options that differ from the defaults, checking docs or source for the defaults rather than over-specifying. Most type errors come from remembered, now-changed APIs; re-check the current docs and source when they occur.
diff --git a/.agents/skills/better-accessibility/SKILL.md b/.agents/skills/better-accessibility/SKILL.md
new file mode 100644
index 00000000..d2790fdf
--- /dev/null
+++ b/.agents/skills/better-accessibility/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: better-accessibility
+description: Accessibility engineering for product interfaces, from focus states and keyboard support to ARIA, forms, and screen readers. Use when building or reviewing UI components, modals, menus, forms, custom widgets, or when the user says "make this accessible" or reports keyboard or screen-reader issues. Triggers on accessibility, a11y, WCAG, aria, focus ring, focus-visible, focus trap, keyboard navigation, tab order, tabindex, screen reader, sr-only, aria-live, alt text, hit area, touch target, prefers-reduced-motion, autoplay, toast duration, skip link, semantic HTML, aria-label, form errors, disabled buttons, "not keyboard accessible".
+---
+
+# Accessibility that comes with the craft
+
+Accessibility is not a compliance checkbox bolted on at the end; it is the floor for interface craft. Most of it is free if you use the platform: native elements ship with keyboard support, real labels announce themselves, and a visible focus ring is one CSS rule. Apply these principles when building or reviewing UI code, and match the project's existing styling system (Tailwind vs. plain CSS vs. CSS-in-JS) when applying fixes.
+
+When reviewing, walk the interface as a keyboard-only user first (every flow must complete without a mouse), then as a screen-reader user: does each control announce a name, a role, and its state? When unsure, prefer the platform default over a custom rebuild, and remove ARIA rather than add it.
+
+Rendered-pair contrast measurement and color remediation are covered by the `better-colors` skill; visual text sizing and iOS input zoom by `better-typography`; spatial RTL layout by `better-layout`.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Focus & Keyboard](focus-and-keyboard.md) | Focus rings, skip links, tabindex, focus trapping, APG keyboard patterns |
+| [Semantics & ARIA](semantics-and-aria.md) | Native elements first, button vs link, landmarks, accessible names, disabled states |
+| [Forms](forms.md) | Labels, autocomplete, error messaging, input types |
+| [Screen Readers](screen-readers.md) | Visually hidden content, live regions, toasts, alt text, SVG |
+| [Hit Areas](hit-areas.md) | Target sizes, expanding hit areas, collision rules |
+| [Motion & Zoom](motion-and-zoom.md) | `prefers-reduced-motion`, autoplay and timed UI, 200% zoom, reflow, rem vs px |
+
+## Core Principles
+
+### 1. Native Elements First
+
+The first rule of ARIA: don't use ARIA when a native element exists. `<button>` for actions, `<a href>` for navigation (it must support Cmd/Ctrl/middle-click), never `<div onClick>`. No ARIA is better than bad ARIA.
+
+### 2. Visible Focus Rings
+
+Style `:focus-visible`, not bare `:focus`, so keyboard users get a ring and mouse users usually don't. Prefer the browser's unmodified focus indicator. If the design needs a custom ring, use a project focus token or another explicit color and verify the complete indicator against every adjacent color it crosses; `currentColor` is acceptable only after the same check. Use at least a `2px` solid perimeter or an equivalent visible area. Never use `outline: none` without a verified replacement, and preserve system colors in forced-colors mode.
+
+### 3. Full Keyboard Support
+
+Every pointer interaction needs a keyboard path, following the ARIA APG patterns: Escape closes overlays, arrow keys move within composite widgets (tabs, menus, listboxes), Tab moves between widgets, Enter and Space activate. Only `tabindex="0"` (join the natural tab order) and `tabindex="-1"` (programmatic focus), never positive values, which break the natural order. Composite widgets use roving tabindex: the active item is `0`, all others `-1`.
+
+### 4. Trap and Restore Focus
+
+Modals set `inert` on the background content, move focus inside on open, and return focus to the trigger on close. Add `overscroll-behavior: contain` so background content doesn't scroll.
+
+### 5. Minimum Hit Area
+
+WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target or one of its defined spacing, equivalent-control, inline, user-agent, or essential exceptions. For easier activation, aim for 44×44px in touch contexts and 40×40px in desktop interfaces when density permits. Extend with a pseudo-element if the visible element should stay smaller. Never let extended hit areas overlap.
+
+### 6. Label and Type Every Control
+
+Every input gets a `<label for>` or wrapping `<label>`; a placeholder is never a label, and label and control share one hit target: no dead zones between a checkbox and its text. Add `autocomplete` with a meaningful `name`, and the correct `type` and `inputmode` for the keyboard. Never block paste; users paste passwords and one-time codes.
+
+### 7. Errors That Announce
+
+Keep submit enabled until the request starts, then disable with a spinner while keeping the original label. Validate on submit: mark failing fields with `aria-invalid="true"`, point `aria-describedby` at the inline error text, and focus the first invalid field. Use native `disabled` when a native control is genuinely unavailable. Use `aria-disabled="true"` only when retaining focusability or discoverability is intentional; then block pointer, keyboard, and form behavior in code and style the state explicitly.
+
+### 8. Accessible Names Everywhere
+
+Icon-only buttons need a descriptive `aria-label`. Visible label text must appear in the accessible name. Decorative elements get `aria-hidden="true"`, never on a focusable element.
+
+### 9. Don't Rely on Color Alone
+
+Status needs a redundant cue: icon, text, or underline alongside the color. Determine which WCAG contrast requirement applies from the content and state, then use `better-colors` to measure the rendered foreground/background pair. When contrast fails, report the pair and requirement it misses; do not change the project's colors unless asked.
+
+### 10. Honor prefers-reduced-motion
+
+Wrap motion in `@media (prefers-reduced-motion: no-preference)` so it is opt-in. Under reduced motion, replace slides and scales with opacity crossfades; kill parallax and autoplay entirely. Independent of the preference: autoplaying media needs a visible pause control, and toasts carrying actions or errors stay until dismissed.
+
+### 11. Announce Dynamic Content
+
+Use `aria-describedby` for field-specific validation, a polite live region (`role="status"`) for non-urgent updates not tied to a control such as toasts or result counts, and `role="alert"` only for urgent errors not tied to a control. For reliable repeated polite announcements, render a stable empty region before updating its text; dynamically inserted alerts have different support and must be tested with the target screen readers.
+
+### 12. Alt Text by Purpose
+
+Decorative images get `alt=""`, informative images describe the meaning, functional images describe the action: a search icon button is `alt="Search"`, not `alt="magnifying glass"`.
+
+### 13. Structure Is Navigation
+
+Use headings that describe their sections and form a coherent outline; one page-level `<h1>` and properly nested levels are the recommended default, not standalone WCAG pass/fail rules. Expose one visible primary `<main>` landmark. When repeated navigation or chrome precedes it, make a "Skip to content" link the first focusable element. Anchored headings get `scroll-margin-top`.
+
+### 14. Survive Zoom and Text Resize
+
+The page must work at 200% zoom and reflow at 320px width without horizontal scrolling. Use `min-height` instead of fixed `height` on text containers, prefer `rem` breakpoints where they fit the codebase's conventions, and never use `user-scalable=no` or `maximum-scale=1`.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `outline: none` to remove the focus ring | Style `:focus-visible` instead; mouse clicks won't show it |
+| Custom focus color assumed to work everywhere | Verify the full indicator against every adjacent color and in forced-colors mode |
+| `<div onClick>` for a button or link | `<button>` for actions, `<a href>` for navigation |
+| Placeholder used as the only label | Add a visible `<label for>`; placeholders disappear on input |
+| Positive `tabindex` to fix focus order | Fix the DOM order; only use `0` and `-1` |
+| Repeated polite update inconsistently announced | Keep a stable empty status region and update its text; test the target screen readers |
+| `assertive` live region for a routine toast | Use `polite`; reserve `assertive` for errors |
+| `aria-hidden="true"` on a focusable element | Remove it or make the element non-focusable |
+| Functional icon alt describes the picture | Describe the action: `alt="Search"`, not `alt="magnifying glass"` |
+| `maximum-scale=1` to stop iOS input zoom | 16px input font on mobile (see `better-typography`); never block zoom |
+| Submit disabled until the form is valid | Keep it enabled; validate on submit and focus the first error |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone accessibility review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` prevents a task, hides content from assistive technology, or creates a systemic accessibility failure; `MEDIUM` makes an interaction meaningfully harder; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current implementation and an actionable replacement.
+- **Why**: name the violated principle and its user impact.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Accessible names everywhere
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/Dialog.tsx:42` | `<button><XIcon /></button>` | Add `aria-label="Close"`; mark the icon `aria-hidden="true"` | The icon-only control has no accessible name |
+| HIGH | `src/Nav.tsx:18` | `<a href="/settings"><GearIcon /></a>` | Add `aria-label="Settings"` | The link destination is unavailable to screen readers |
+
+#### Visible focus rings
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/button.css:12` | `button:focus { outline: none; }` | `button:focus-visible { outline: 2px solid; outline-offset: 2px; }` | Keyboard users cannot see focus |
+| HIGH | `src/Menu.tsx:31` | `focus:outline-none` | `focus-visible:outline-2 focus-visible:outline-offset-2` | Menu navigation has no visible focus indicator |
+
+#### Errors that announce
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/EmailField.tsx:27` | Error shown only as `border-red-500` | Add `aria-invalid="true"` + `aria-describedby="email-error"` with inline error text | Color alone neither explains nor announces the error |
+| MEDIUM | `src/SignupForm.tsx:64` | Submit disabled until the form is valid | Keep submit enabled; on failure, focus the first invalid field | A disabled action hides what must be fixed |
+
+#### Minimum hit area
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Toolbar.tsx:22` | `size-4` icon-only button | Extend the hit area to 44×44px with `after:absolute after:size-11` | The target is too small for reliable touch input |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including keyboard traversal, accessible-name inspection, and screen-reader or automated checks when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable accessibility findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-accessibility/agents/openai.yaml b/.agents/skills/better-accessibility/agents/openai.yaml
new file mode 100644
index 00000000..4f20e8a5
--- /dev/null
+++ b/.agents/skills/better-accessibility/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Accessibility"
+  short_description: "Focus, keyboard, ARIA, forms and screen readers"
diff --git a/.agents/skills/better-accessibility/focus-and-keyboard.md b/.agents/skills/better-accessibility/focus-and-keyboard.md
new file mode 100644
index 00000000..6a2cc6da
--- /dev/null
+++ b/.agents/skills/better-accessibility/focus-and-keyboard.md
@@ -0,0 +1,131 @@
+# Focus and Keyboard
+
+Focus rings, skip links, tabindex, focus trapping, and the APG keyboard patterns.
+
+## Focus rings
+
+Style `:focus-visible`, not bare `:focus`. The browser shows `:focus-visible` for keyboard and assistive-tech focus but suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement; that removes keyboard navigation for sighted keyboard users.
+
+Prefer the browser's unmodified focus indicator: it adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` generally preserves that indicator. A custom `outline: 2px solid` with no color renders `currentColor`; that is not automatically accessible because the outline may cross colors different from the text's own background. So the preference order is:
+
+```css
+/* Best: keep the browser ring, just give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+
+```tsx
+// Tailwind: use the project's focus token or established focus-ring utility
+<button className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--focus-ring)]">
+  Save
+</button>
+```
+
+A custom focus indicator must meet the applicable project/WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses, including component fills, page surfaces, images, gradients, and hover/selected states. A token, brand color, or `currentColor` is acceptable only when that rendered check passes.
+
+In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or explicitly use a system color such as `Highlight`; never freeze the authored color with `forced-color-adjust: none` unless the control remains perceivable.
+
+Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
+
+## Skip link
+
+When repeated navigation or other repeated chrome precedes the primary content, the first focusable element is a "Skip to content" link targeting `<main id="main">`. Visually hide it until focused:
+
+```css
+.skip-link {
+  position: absolute;
+  inset-inline-start: -999px;
+}
+.skip-link:focus {
+  inset-inline-start: 16px;
+  top: 16px;
+}
+```
+
+```html
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header>…</header>
+  <main id="main">…</main>
+</body>
+```
+
+Give in-page anchor targets `scroll-margin-top` (e.g. `scroll-margin-top: 80px` under a sticky header) so the target isn't hidden when jumped to.
+
+## tabindex rules
+
+- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
+- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers, and roving-tabindex members.
+- Positive `tabindex`: never. It hijacks the tab order for the whole page; fix the DOM order instead.
+
+### Roving tabindex
+
+Composite widgets (tabs, menus, toolbars, radio groups) occupy a single Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
+
+```tsx
+<div role="tablist">
+  {tabs.map((tab, i) => (
+    <button
+      role="tab"
+      tabIndex={i === activeIndex ? 0 : -1}
+      aria-selected={i === activeIndex}
+      onKeyDown={handleArrowKeys} // ArrowLeft/ArrowRight move activeIndex, wrapping
+    >
+      {tab.label}
+    </button>
+  ))}
+</div>
+```
+
+## Focus trapping and restoration
+
+Modals must trap focus. The modern technique is the `inert` attribute on everything behind the dialog; it removes background content from the tab order and from assistive tech in one move:
+
+```tsx
+// On open
+document.getElementById("app-content").inert = true;
+const dialog = dialogRef.current;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+
+// On close
+document.getElementById("app-content").inert = false;
+triggerRef.current?.focus(); // always return focus to the element that opened it
+```
+
+Native `<dialog>` with `showModal()` gives you the trap, `inert` background, and Escape handling for free; prefer it. A custom overlay that can't use `<dialog>` needs `role="dialog"`, `aria-modal="true"`, and an accessible name (`aria-labelledby` pointing at its heading). Either way:
+
+- On open, focus the first focusable element; for destructive confirmations, focus the least destructive action instead.
+- On close, return focus to the trigger. If the trigger no longer exists, move focus to the nearest logical container.
+- Add `overscroll-behavior: contain` on the dialog so scrolling inside never scrolls the page behind it.
+
+## Keyboard patterns (ARIA APG)
+
+Native elements come with these behaviors; custom widgets must implement them. A role is a promise: if you give something `role="tab"`, users expect the full tab keyboard model.
+
+| Widget | Keys |
+| --- | --- |
+| Dialog | Tab/Shift+Tab cycle inside (wrap at ends); Escape closes |
+| Tabs | Arrow keys move between tabs (wrapping); Tab exits to the panel; Home/End jump to first/last |
+| Menu button | Enter/Space/ArrowDown opens and focuses first item; ArrowUp opens and focuses last; arrows navigate; Escape closes and refocuses the button |
+| Disclosure / accordion | Header is a `<button aria-expanded>`; Enter and Space toggle |
+| Combobox | ArrowDown opens/moves into the list; Enter accepts; Escape closes and returns to the input; typing filters |
+| Listbox / radio group | Arrow keys move selection; one Tab stop for the whole group |
+
+Universal rules:
+
+- Escape dismisses whatever opened last: tooltip, then menu, then dialog.
+- Arrow keys, not Tab, move within a composite widget; Tab moves between widgets.
+- Tabs choose activation mode: automatic (panel switches on arrow focus) when panels render instantly, manual (Enter/Space to activate) when switching is expensive.
+- Enter submits the focused input's form. In `<textarea>`, Enter inserts a newline and ⌘/Ctrl+Enter submits.
+
+## SPA route changes
+
+Client-side navigation doesn't reset focus or announce anything. On route change: update `document.title` to match the new context, then move focus to the new view's `<h1>` (given `tabindex="-1"`) or to `<main>`. Restore scroll position on back/forward navigation; scroll to top on forward navigation.
diff --git a/.agents/skills/better-accessibility/forms.md b/.agents/skills/better-accessibility/forms.md
new file mode 100644
index 00000000..4a89cb1b
--- /dev/null
+++ b/.agents/skills/better-accessibility/forms.md
@@ -0,0 +1,86 @@
+# Forms
+
+Labels, autocomplete, error messaging, input types, and submit behavior.
+
+## Labels
+
+Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label: it disappears the moment the user types and usually fails contrast.
+
+```html
+<!-- Good: explicit association -->
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email" />
+
+<!-- Good: wrapping label, so label and control share one hit target -->
+<label>
+  <input type="checkbox" /> Send me updates
+</label>
+```
+
+Label and control must share one hit target: clicking the text "Send me updates" toggles the checkbox, with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
+
+Placeholders, when used *in addition to* a label, show an example of the expected format: `placeholder="name@company.com"`.
+
+## Error messaging
+
+The complete pattern:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  autocomplete="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error">Enter a valid email address.</p>
+```
+
+- `aria-invalid="true"` on the failing field, removed once fixed.
+- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
+- Errors render inline next to their fields, with an icon or text, never a red border alone (color-only cues fail).
+- On submit, focus the first invalid field.
+- Allow incomplete submission so validation can surface; don't disable submit until valid (see below).
+- Accept free text and validate after; don't block typing or filter characters as the user types. Trim values before validating; autocomplete and text expansion add trailing spaces.
+
+## Autocomplete and input types
+
+`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
+
+| Field | `autocomplete` |
+| --- | --- |
+| Name | `name` (or `given-name` / `family-name`) |
+| Email | `email` |
+| Phone | `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+
+Prefix with a section where relevant: `autocomplete="shipping street-address"`.
+
+Correct `type` and `inputmode` pick the right mobile keyboard:
+
+| Input | Use |
+| --- | --- |
+| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
+| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
+| Money, decimals | `type="text" inputmode="decimal"` |
+| True numeric quantity | `type="number"` |
+
+Disable spellcheck on emails, codes, and usernames: `spellcheck="false"`.
+
+## Never fight the user's tools
+
+- Never block paste in `<input>` or `<textarea>`; users paste passwords and one-time codes.
+- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
+- Never use `user-scalable=no` or `maximum-scale=1` to stop iOS input zoom; keep mobile input text at `16px` instead (covered in `better-typography`).
+
+## Submit behavior
+
+- Keep submit enabled until the request starts, then disable it and show a spinner *while keeping the original label*: "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
+- Announce results: success goes through a polite live region. For submit failures, focus the first invalid field; the focus move is the announcement, and reserve `role="alert"` for form-level errors not tied to a field (see [screen-readers.md](screen-readers.md)).
+- Warn on unsaved changes before navigation, and never lose typed input to a re-render; hydration must preserve focus and value.
+- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.
diff --git a/.agents/skills/better-accessibility/hit-areas.md b/.agents/skills/better-accessibility/hit-areas.md
new file mode 100644
index 00000000..d1882745
--- /dev/null
+++ b/.agents/skills/better-accessibility/hit-areas.md
@@ -0,0 +1,76 @@
+# Hit Areas
+
+Target sizes, expanding hit areas without changing visual size, and collision rules.
+
+## Target sizes
+
+Separate the conformance baseline from larger usability targets:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its defined exceptions. Treat 44px as a recommended touch target for primary controls and 40px as a useful desktop target when the product's density permits. Smaller controls are not automatically failures: check the spacing, equivalent-control, inline, user-agent, and essential exceptions before reporting one.
+
+Under the spacing exception, an undersized target passes if a 24px circle centered on its bounding box does not intersect another target or another undersized target's circle; in the simple case, 20px targets need at least a 4px gap.
+
+The visible element can stay small; the hit area is what must be big. If it looks clickable, it must be clickable across its whole visual extent: no dead zones (a checkbox and its label share one hit target).
+
+## Expanding the hit area
+
+If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element. Put the pseudo-element on the wrapping `<label>` or `<button>`, not on the `<input>` itself; replaced elements don't render `::before`/`::after` reliably.
+
+### CSS Example
+
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Layout alternative
+
+When the element can afford real box size, skip the pseudo-element and let the box itself be the target; this also gives the browser the real geometry for scrolling and gestures:
+
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+
+## Collision Rule
+
+If the extended hit area overlaps another interactive element, shrink the pseudo-element, but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.
+
+## Touch behavior
+
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Prefer generous targets and clear affordances over finicky interactions (tiny drag handles, precise hover zones).
diff --git a/.agents/skills/better-accessibility/motion-and-zoom.md b/.agents/skills/better-accessibility/motion-and-zoom.md
new file mode 100644
index 00000000..87e4ef81
--- /dev/null
+++ b/.agents/skills/better-accessibility/motion-and-zoom.md
@@ -0,0 +1,79 @@
+# Motion and Zoom
+
+`prefers-reduced-motion`, zoom and reflow, and unit choices that respect user settings.
+
+## prefers-reduced-motion
+
+Make motion opt-in: wrap animations in `@media (prefers-reduced-motion: no-preference)` so users who asked for reduced motion get the static version by default, instead of you chasing every animation with an override.
+
+```css
+/* Good: motion is opt-in */
+.card {
+  /* static styles */
+}
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    transition: transform 200ms ease-out;
+  }
+}
+```
+
+```tsx
+// Tailwind: motion-safe / motion-reduce variants
+<div className="motion-safe:transition-transform motion-safe:hover:-translate-y-1" />
+```
+
+For an existing codebase where opt-in isn't feasible, the global kill switch is the fallback:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`0.01ms` rather than `none` so `animationend`/`transitionend` events still fire and JS that waits on them doesn't hang.
+
+### What to disable vs reduce
+
+Reduced motion means reduced, not eliminated: it targets vestibular triggers, not feedback.
+
+| Disable entirely | Replace | Keep |
+| --- | --- | --- |
+| Parallax scrolling | Slide/scale/zoom transitions → opacity crossfade | Loading spinners and progress |
+| Autoplaying video, GIFs, looping decoration | Smooth scrolling → instant jump | Instant state changes (hover color, focus ring) |
+| Spinning, large-scale movement across the screen | Auto-rotating carousels → start paused | Brief functional feedback (button press) |
+
+Animations must be interruptible and driven by user input; nothing should autoplay or refuse to stop. Under reduced motion, carousels start paused.
+
+## Autoplay and timed UI
+
+Motion the user didn't ask for, and UI that acts on its own schedule:
+
+- **No autoplaying media without visible controls** (WCAG 2.2.2): anything that moves, blinks or updates automatically for more than 5 seconds needs a visible pause/stop control. Muted looping hero videos included.
+- **Prefer explicit dismissal over timers.** Auto-dismissing toasts are acceptable only for low-stakes confirmations; anything containing an action, an error, or information the user may need to act on stays until dismissed. If a toast must time out, 5 seconds is the floor, and hovering or focusing it pauses the timer.
+- **Never put critical information only in a timed element.** A vanished toast with the only link to an undo action is data loss on a schedule.
+
+## Zoom and reflow
+
+- **200% zoom** (WCAG 1.4.4): all content and functionality must survive text scaled to 200%. Never block zoom: no `user-scalable=no`, no `maximum-scale=1`. Safari ignores the cap but every other browser enforces it.
+- **Reflow at 320px** (WCAG 1.4.10): at 400% zoom on a 1280px viewport (equivalent to a 320px viewport) the page must work with vertical scrolling only: no two-dimensional scrolling except for genuinely 2D content (tables, maps, code blocks), which scroll inside their own container.
+
+Fixed heights are what break under zoom: use `min-height` on anything containing text and let containers grow.
+
+### rem vs px
+
+Respect how the codebase is set up: if the project sizes in `px` (or an established Tailwind scale), stay consistent with it; don't introduce mixed units into someone else's system. Where you do have the choice (new code, or a codebase already on `rem`), `rem` respects the user's base font size and `px` ignores it:
+
+| Use `rem` | Use `px` |
+| --- | --- |
+| `font-size` | Borders and hairlines |
+| `max-width` of text containers | Focus outline width and offset |
+| Media-query breakpoints (`@media (min-width: 48rem)`) | `box-shadow` details |
+| Spacing that should scale with text | Fixed-size decorations |
+
+Breakpoints are where the choice matters most: at a larger base font size, an `em`/`rem` query switches to the mobile layout when the text needs it; a `px` query doesn't.
diff --git a/.agents/skills/better-accessibility/screen-readers.md b/.agents/skills/better-accessibility/screen-readers.md
new file mode 100644
index 00000000..a868eae6
--- /dev/null
+++ b/.agents/skills/better-accessibility/screen-readers.md
@@ -0,0 +1,101 @@
+# Screen Readers
+
+Visually hidden content, live regions, toasts, alt text, and SVG.
+
+## Visually hidden content
+
+The canonical `.sr-only` pattern hides content visually while keeping it in the accessibility tree:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+Use `1px` boxes, not `0`; some screen readers skip zero-sized elements. `white-space: nowrap` prevents words from being read as one run-together string. Never use `display: none` or `visibility: hidden` for this; both remove the content from assistive tech entirely.
+
+Tailwind ships this as `sr-only`. For skip links, add a focus variant that un-hides the element (`focus:not-sr-only`, or override the positioning on `:focus`).
+
+Use it for context that sighted users get visually: `<span class="sr-only">Opens in new tab</span>`, table caption text, or the label of an icon-only control when `aria-label` isn't an option.
+
+## Choosing how to announce a change
+
+Work down this list and stop at the first match:
+
+1. **Focus moves there anyway** (opened modal, first invalid field on submit): nothing extra needed; the focus move is the announcement.
+2. **Tied to a specific control** (field error, character count): `aria-describedby` on the control; it's announced with the field.
+3. **Non-urgent, not tied to a control** (toast, "Saved", result count, loading state): polite live region / `role="status"`.
+4. **Urgent and not tied to a control** (form-level failure, session expiring): `role="alert"`.
+
+## Live regions
+
+Live regions announce content that changes without a page load: toasts, validation, search-result counts, loading states.
+
+| Mechanism | Politeness | Use for |
+| --- | --- | --- |
+| `role="status"` (= `aria-live="polite"` + `aria-atomic="true"`) | Waits for a pause | Toasts, "Saved", result counts, loading updates |
+| `role="alert"` (= `aria-live="assertive"` + `aria-atomic="true"`) | Interrupts immediately | Errors and urgent problems only |
+
+Rules for reliable announcements:
+
+- For repeated polite updates, keep a stable empty region in the DOM before changing its text. Inserting a new polite region together with its content is inconsistently announced.
+- Dynamically inserted `role="alert"` content is commonly announced, but behavior varies; use it only for urgent errors not tied to a control and test the target browser/screen-reader combinations.
+- Default to polite. Overusing `assertive` is the most common live-region mistake; it interrupts whatever the user was reading.
+- Keep messages short and self-contained; `aria-atomic="true"` re-reads the whole region on change.
+- Don't move focus to a toast; announce it and leave focus where the user is working. Give toasts a generous timeout or a dismiss button, and never put the only path to an action inside an auto-dismissing toast.
+
+```tsx
+// Region rendered from the start, message injected later
+<div role="status" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+For loading states: set `aria-busy="true"` on the updating region, announce "Loading…" politely, then announce the outcome ("Loaded, 12 results").
+
+## aria-hidden
+
+`aria-hidden="true"` removes an element and its whole subtree from assistive tech. Use it for decorative icons and content duplicated for visual effect. Never put it on (or above) a focusable element; that creates stops you can Tab to that don't exist for a screen reader. If you hide something interactive, also remove it from the tab order.
+
+## Alt text
+
+Choose by purpose, not by what the image looks like:
+
+| Purpose | Alt | Example |
+| --- | --- | --- |
+| Decorative, or redundant with adjacent text | `alt=""` (empty, but present) | Logo next to the company name in text |
+| Informative | Describe the meaning it adds | `alt="Ticket QR code"` |
+| Functional (image is the link/button) | Describe the action or destination | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text | The exact text (better: use real text) | `alt="50% off everything"` |
+| Complex (chart, diagram) | Short summary in `alt`, full data as a table or text nearby | `alt="Revenue by quarter, described below"` |
+
+A missing `alt` attribute is worse than an empty one: screen readers fall back to reading the file name.
+
+## SVG
+
+- Decorative SVG: `aria-hidden="true"` and `focusable="false"` (the latter for legacy Edge/IE tabbing), no title needed.
+- Meaningful inline SVG: `role="img"` plus `aria-label="…"` (or a `<title>` as the first child referenced by `aria-labelledby`).
+- Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
+
+```tsx
+// Decorative icon inside a labeled button
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">…</svg>
+</button>
+
+// Standalone meaningful icon
+<svg role="img" aria-label="Verified account">…</svg>
+```
+
+## Video and audio
+
+Prerecorded video needs captions; provide transcripts for audio. Never autoplay with sound, and always render controls.
diff --git a/.agents/skills/better-accessibility/semantics-and-aria.md b/.agents/skills/better-accessibility/semantics-and-aria.md
new file mode 100644
index 00000000..0a9a612d
--- /dev/null
+++ b/.agents/skills/better-accessibility/semantics-and-aria.md
@@ -0,0 +1,83 @@
+# Semantics and ARIA
+
+Native elements first, landmarks, accessible names, and the ARIA rules that keep custom widgets honest.
+
+## The rules of ARIA
+
+1. If a native HTML element with the semantics and behavior you need exists, use it instead of repurposing another element with ARIA.
+2. Don't change native semantics unless you really have to.
+3. Every interactive ARIA control must be keyboard-operable; a role is a promise of the full keyboard model, states, and behavior.
+4. Never put `role="presentation"` or `aria-hidden="true"` on a focusable element.
+5. All interactive elements must have an accessible name.
+
+No ARIA is better than bad ARIA: a screen reader trusts your roles, so a wrong role is worse than none.
+
+## Button vs link vs div
+
+| Element | Use for | Why |
+| --- | --- | --- |
+| `<a href>` | Navigation: anything that goes somewhere or changes the URL | Free Cmd/Ctrl/middle-click, right-click → copy link, Enter activation |
+| `<button>` | Actions: submit, toggle, open, delete | Free focus, Enter *and* Space activation, form semantics |
+| `<div onClick>` | Nothing | No role, no focus, no keyboard; screen readers see plain text |
+
+```tsx
+// Bad: invisible to keyboard and screen readers
+<div onClick={openSettings}>Settings</div>
+
+// Good: focus, Enter/Space activation, and semantics for free
+<button onClick={openSettings}>Settings</button>
+```
+
+If it looks clickable it must be clickable, and the reverse: if it's clickable it must be a real interactive element. Rebuilding a link as a button (or vice versa) breaks user expectations; a "button" that navigates should be a styled `<a>`.
+
+If a native element is truly impossible, the full polyfill is `role="button"` + `tabindex="0"` + Enter and Space handlers, which is why the native element is always less code.
+
+## Landmarks and headings
+
+- Expose one visible primary `<main>` landmark. `<header>`, `<nav>`, `<aside>`, `<footer>` map to landmarks screen-reader users jump between.
+- Multiple landmarks of the same type need distinguishing labels: `<nav aria-label="Primary">`, `<nav aria-label="Breadcrumbs">`.
+- Headings describe their sections and form a coherent outline. One page-level `<h1>` and properly nested levels are the recommended default; do not report either convention as a standalone WCAG failure without a concrete navigation or comprehension impact. Headings are structure, not styling; style a heading level with CSS instead of picking the tag by size.
+- `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
+
+## Accessible names
+
+Name precedence: `aria-labelledby` > `aria-label` > native label (`<label>`, text content, `alt`) > `title` attribute.
+
+- Prefer visible text or `aria-labelledby` over `aria-label`: `aria-label` is invisible, drifts out of sync with the UI, and translation tools handle it inconsistently.
+- Icon-only buttons always need a name: `<button aria-label="Close">` with the icon `aria-hidden="true"`.
+- The visible label must appear inside the accessible name (WCAG 2.5.3 Label in Name). A button showing "Send" with `aria-label="Submit message"` breaks voice control users who say "click Send".
+- Accessible names must exist even when the design omits visible labels.
+
+```tsx
+// Good: name from visible text, icon hidden
+<button>
+  <TrashIcon aria-hidden="true" /> Delete
+</button>
+
+// Good: icon-only, explicit name
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+Add `translate="no"` to brand names, code tokens, and identifiers so auto-translation doesn't garble them.
+
+## Common ARIA mistakes
+
+| Mistake | Why it fails |
+| --- | --- |
+| `aria-label` on a plain `<div>` or `<span>` | Names on non-interactive, role-less elements are ignored by most screen readers |
+| `<button role="button">` | Redundant role; adds noise, no benefit |
+| `aria-hidden="true"` on or above a focusable element | Creates elements you can Tab to but that don't exist for screen readers |
+| `aria-labelledby`/`aria-describedby` pointing at a missing ID | Silently produces no name or description |
+| `role="menu"` on a nav list | `menu` promises app-style arrow-key behavior; site navigation is `<nav>` with a list |
+
+## Disabled states
+
+Native `disabled` supplies the platform's complete disabled behavior: it removes the control from the tab order, suppresses activation, applies `:disabled`, and excludes form controls from submission. Use it when a native control is genuinely unavailable. `aria-disabled="true"` only announces the state; it does not change focusability, suppress behavior, or add disabled styling.
+
+- Don't disable submit buttons at all: keep them enabled, validate on submit, and focus the first error (see [forms.md](forms.md)).
+- Use `aria-disabled="true"` when keeping a control discoverable in the tab order is an intentional requirement, or when a custom control cannot use native `disabled`.
+- With `aria-disabled="true"`, block pointer and keyboard activation in the handler, prevent form submission where applicable, add explicit styling (including forced-colors support), and explain why the action is unavailable nearby.
+- Never set both `disabled` and `aria-disabled` on the same element.
+- Disabled controls are exempt from contrast minimums, but keep them legible anyway.
diff --git a/.agents/skills/better-colors/SKILL.md b/.agents/skills/better-colors/SKILL.md
new file mode 100644
index 00000000..fdeff04e
--- /dev/null
+++ b/.agents/skills/better-colors/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: better-colors
+description: OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.
+---
+
+# OKLCH Colors
+
+OKLCH is a perceptually uniform color space where lightness, chroma, and hue are useful design controls. Use it when the project already uses OKLCH, when creating a new color system, or when the user asks for conversion or palette work. Otherwise preserve the project's established tokens and notation: a consistent hex or RGB token system is better than introducing a second color representation for an isolated fix. To explore interactively, visit [oklch.fyi](https://oklch.fyi).
+
+## Quick Reference
+
+| Category | When to use | Reference |
+| --- | --- | --- |
+| Conversion | Hex/rgb/hsl to oklch | [color-conversion.md](color-conversion.md) |
+| Palettes | Generate scales, multi-hue, dark mode | [palette-generation.md](palette-generation.md) |
+| Contrast | APCA/WCAG checks, reporting failures, fixing on request | [accessibility-contrast.md](accessibility-contrast.md) |
+| Gamut & Tailwind | P3 fallbacks, `@theme` scales, gamut clamping | [gamut-and-tailwind.md](gamut-and-tailwind.md) |
+| Usage | Semantic tokens, one meaning per color, primary-action emphasis, appearance variants | [color-usage.md](color-usage.md) |
+
+## Core Principles
+
+### 1. Use a Perceptual Color Space
+
+- **Respect the existing system.** Do not convert notation merely because this skill was loaded. Reuse the project's semantic tokens and authoring format unless the task includes a color-system migration.
+- **Perceptual uniformity.** Equal L steps = equal brightness. `oklch(0.5 ...)` is visually mid. HSL's `lightness: 50%` varies wildly by hue.
+- **Stable hue.** HSL blue shifts toward purple as lightness changes. OKLCH hue stays constant across the full lightness range.
+- **Independent chroma.** Chroma is an absolute measure of colorfulness that doesn't depend on lightness. HSL saturation does.
+- **Finite gamut.** Not every oklch value maps to a displayable sRGB color. High-chroma values at certain hues will clip; gamut awareness is required.
+
+### 2. Write and Format OKLCH Consistently
+
+```
+oklch(L C H)
+oklch(L C H / alpha)
+```
+
+| Channel | Range | Description |
+| --- | --- | --- |
+| L (Lightness) | 0–1 | 0 = black, 1 = white. Perceptually uniform. |
+| C (Chroma) | 0–~0.4 | Colorfulness. 0 = gray. Max depends on L and H. |
+| H (Hue) | 0–360 | Hue angle in degrees. |
+| alpha | 0–1 | Optional transparency. Slash syntax. |
+
+```css
+oklch(0.637 0.237 25.331)
+oklch(0.8 0.05 200 / 0.5)
+```
+
+Use three decimal places for L and C and up to three for H. Drop trailing zeros and format `-0` as `0`. OKLCH is Baseline 2023; when support requirements are unusually broad, check the target project's browser matrix instead of relying on a fixed global-coverage percentage.
+
+### 3. Measure Contrast, Gamut, and Palette Behavior
+
+| Rule | Value |
+| --- | --- |
+| Light/dark boundary | L > 0.73 = light background → dark text; below it, light text still scores higher |
+| Lightness gap (light bg) | Foreground L < 0.35 when background L > 0.9 |
+| Lightness gap (dark bg) | Foreground L > 0.9 when background L < 0.25 |
+| Hue drift threshold | > 10° spread across palette steps = visible drift |
+| APCA body text | \|Lc\| >= 75 minimum, >= 90 preferred |
+| APCA non-body text | \|Lc\| >= 60 minimum |
+| WCAG 2 normal text | 4.5:1 AA, 7:1 AAA |
+| Contrast fix (only when asked) | Adjust L first; preserve C and H when possible, then remeasure the rendered pair |
+
+## Common Mistakes
+
+| Issue | Fix |
+| --- | --- |
+| Raw color bypasses the project's semantic token system | Reuse or add the correct role token in the project's existing notation |
+| Isolated OKLCH value introduced into a hex/RGB codebase | Preserve the established notation unless the task includes a color-system migration |
+| HSL palette ramp with hue drift | Rebuild with constant oklch hue |
+| Failing contrast (check foreground vs its background using APCA) | Report the pair, its measured Lc and the threshold it misses; change colors only when asked (then adjust L, keep C and H) |
+| High chroma without gamut check | Clamp to max chroma for the L/H in sRGB |
+| Same absolute C across different hues | Use same C% (percentage of max) for consistent vividness |
+| P3 color without sRGB fallback | Add `@media (color-gamut: p3)` pattern |
+| Dark mode created by mechanically reversing the light palette | Use the light palette as a starting point, then tune chroma and lightness and recheck every foreground/background pair |
+| Hex in Tailwind v4 `@theme` | Convert to oklch values |
+| Alpha with comma syntax | Use slash: `oklch(L C H / alpha)` |
+| Same hue means two different things (link color reused decoratively) | One color, one meaning; give the second use a neutral |
+| Semantic token used outside its role (separator as text) | Add a token for the missing role; never borrow by value |
+| Several colored control backgrounds in one view | Fill only the single primary action; secondaries stay neutral |
+| Palette verified only in light mode | Recheck every foreground/background pair in both appearances |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone color review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes content unreadable or assigns a misleading semantic color; `MEDIUM` creates a noticeable theme, gamut, or consistency failure; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current value or token and the exact replacement.
+- **Why**: name the violated principle and include measured contrast or gamut evidence when relevant.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/theme.css:18` | `color: #3b82f6` | `color: oklch(0.623 0.188 259.815)` | New project colors use OKLCH tokens |
+| MEDIUM | `src/palette.ts:31` | Same absolute C across hues | Same C% of each hue's maximum chroma | Equal chroma values do not appear equally vivid across hues |
+| HIGH | `src/theme.css:52` | P3 color with no fallback | Add an sRGB fallback before `@media (color-gamut: p3)` | The color fails on non-P3 displays |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including contrast measurements, gamut checks, and both light and dark appearances when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the table, state "No actionable color findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-colors/accessibility-contrast.md b/.agents/skills/better-colors/accessibility-contrast.md
new file mode 100644
index 00000000..d88a3c7d
--- /dev/null
+++ b/.agents/skills/better-colors/accessibility-contrast.md
@@ -0,0 +1,87 @@
+# Accessibility & Contrast
+
+Contrast is always measured between a **foreground color** (text, icon, or UI element) and the **background color** it sits on. When checking contrast, identify the background the element will be rendered against, typically the nearest parent's background color.
+
+**Report, don't repaint.** When a check fails, report it (the failing foreground/background pair, its measured Lc or ratio, and the threshold it misses) and leave the colors unchanged. A project's colors are a design decision; only apply the fix below when the user asks for one.
+
+## APCA thresholds (recommended)
+
+APCA (Accessible Perceptual Contrast Algorithm) is more perceptually accurate than WCAG 2 and pairs naturally with oklch since both are grounded in perceptual lightness. Use APCA as the default.
+
+Lc (Lightness Contrast) measures the perceived contrast between foreground and background. These levels are simplified from APCA's full font-size/weight lookup table:
+
+| Content Type | Minimum | Preferred |
+| --- | --- | --- |
+| Body text (columns/blocks of text) | Lc 75 | Lc 90 |
+| Non-body text (labels, headlines) | Lc 60 | Lc 75 |
+| Large text (≥36px) | Lc 45 | Lc 60 |
+| UI components | Lc 30 | n/a |
+
+Lc 30 is also APCA's minimum for disabled and placeholder text; the absolute floor for non-text elements to be discernible at all is Lc 15.
+
+APCA's Lc value is signed: positive means dark text on a light background, negative means light text on a dark background. Use the absolute value for threshold comparison.
+
+## WCAG 2 thresholds (for legal compliance)
+
+WCAG 2 is still required when making formal WCAG 2.x conformance claims. It uses a luminance ratio that can be both too strict and too lenient depending on the color pair.
+
+| Content Type | AA | AAA |
+| --- | --- | --- |
+| Normal text (<24px / <18.5px bold) | 4.5:1 | 7:1 |
+| Large text (>=24px / >=18.5px bold) | 3:1 | 4.5:1 |
+| UI components & graphical objects | 3:1 | n/a |
+
+WCAG defines "large text" in points: 18pt ≈ `24px`, or 14pt bold ≈ `18.5px`.
+
+## Fixing contrast with oklch (on request)
+
+In hex/rgb, fixing contrast means trial and error across three channels. In oklch, lightness (L) is the clearest first lever: adjust the L distance between the foreground and its background while preserving C and H when possible:
+
+```css
+/* Failing: text too close in lightness to its background (Lc ≈ 50) */
+color: oklch(0.65 0.08 250);      /* foreground */
+background: oklch(0.95 0.02 250); /* background */
+
+/* Fix: darken the text, keep C and H unchanged (Lc ≈ 90) */
+color: oklch(0.3 0.08 250);       /* foreground: more L distance */
+background: oklch(0.95 0.02 250); /* background: unchanged */
+```
+
+Note that mid-lightness backgrounds cap the achievable contrast: on a background of L 0.75, even pure black text only reaches about Lc 60; body text needs a background near the light or dark extreme.
+
+Adjust L first, then remeasure the rendered foreground/background pair. Chroma and hue can still affect the converted color, gamut mapping, and measured contrast; reduce C when needed to keep the adjusted color in gamut.
+
+## Quick lightness gap guide
+
+For body text (targeting |Lc| >= 75):
+
+- **Light background (L > 0.9):** foreground L should be below 0.35
+- **Dark background (L < 0.25):** foreground L should be above 0.9
+
+The gap is asymmetric because APCA is polarity-aware: mirrored pairs don't score identically. These are approximations; always verify with an actual contrast calculation.
+
+## Light vs dark color detection
+
+A background counts as light when its oklch lightness exceeds 0.73, the APCA crossover on neutral backgrounds:
+
+```
+if L > 0.73 → use dark text on this background
+if L <= 0.73 → use light text on this background
+```
+
+The crossover is higher than intuition suggests: in the 0.6–0.73 band the background already looks light, but white text still scores meaningfully higher than black.
+
+## Hue drift detection
+
+To detect hue drift in an existing HSL palette:
+
+1. Convert each step to oklch
+2. Compare the H values across steps
+3. If the hue spread is greater than 10°, the palette has visible drift
+
+```css
+/* HSL blue ramp: hue shifts toward purple */
+hsl(240, 80%, 20%)  →  oklch H ≈ 269
+hsl(240, 80%, 50%)  →  oklch H ≈ 267
+hsl(240, 80%, 90%)  →  oklch H ≈ 285  /* shifted 18° */
+```
diff --git a/.agents/skills/better-colors/agents/openai.yaml b/.agents/skills/better-colors/agents/openai.yaml
new file mode 100644
index 00000000..ae19ceb2
--- /dev/null
+++ b/.agents/skills/better-colors/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Colors"
+  short_description: "OKLCH palettes, contrast and theming"
diff --git a/.agents/skills/better-colors/color-conversion.md b/.agents/skills/better-colors/color-conversion.md
new file mode 100644
index 00000000..fa660420
--- /dev/null
+++ b/.agents/skills/better-colors/color-conversion.md
@@ -0,0 +1,53 @@
+# Color Conversion
+
+Use this reference only when the user asks for conversion, the project is already standardizing on OKLCH, or an agreed color-system migration requires it. Do not convert an isolated value in a project that intentionally uses another notation. When conversion is in scope, convert the color values but leave everything else unchanged: don't change gradient interpolation or restructure the CSS.
+
+## Supported input formats
+
+| Format | Examples |
+| --- | --- |
+| Hex (3/6/8-digit) | `#f00`, `#ff0000`, `#ff000080` |
+| `rgb()` / `rgba()` | `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)` |
+| `hsl()` / `hsla()` | `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)` |
+
+## Conversion examples
+
+```css
+/* Before */
+color: #3b82f6;
+background: #1e293b;
+border-color: #e2e8f0;
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+background: oklch(0.279 0.037 260.031);
+border-color: oklch(0.929 0.013 255.508);
+```
+
+```css
+/* Before */
+color: rgb(59, 130, 246);
+border: 1px solid rgba(0, 0, 0, 0.1);
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+border: 1px solid oklch(0 0 0 / 0.1);
+```
+
+Alpha uses the forward-slash syntax. Omit alpha when it's 1.
+
+## What to leave alone
+
+- CSS keywords: `currentColor`, `inherit`, `initial`, `unset`, `transparent`
+- Gradient interpolation methods: only convert the color stops, not the function itself
+- Colors in third-party library configs that expect hex input
+
+## Bulk conversion
+
+Bulk conversion is a migration task, not routine cleanup. When an entire file is explicitly in scope:
+
+1. Replace all hex colors with their oklch equivalents
+2. Replace all `rgb()`, `rgba()`, `hsl()`, `hsla()` function calls
+3. Leave gradient functions unchanged; only convert the color stops within them
+4. Leave `currentColor`, `inherit`, `transparent`, and CSS keywords as-is
+5. Preserve comments and formatting
diff --git a/.agents/skills/better-colors/color-usage.md b/.agents/skills/better-colors/color-usage.md
new file mode 100644
index 00000000..6b2a1dd0
--- /dev/null
+++ b/.agents/skills/better-colors/color-usage.md
@@ -0,0 +1,94 @@
+# Color Usage
+
+How to deploy color in an interface: semantic tokens, meaning, emphasis, and appearance variants. For picking the values themselves, see [palette-generation.md](palette-generation.md); for checking pairs, see [accessibility-contrast.md](accessibility-contrast.md).
+
+## One color, one meaning
+
+Use a color consistently for one purpose (interactive, destructive, featured) across the interface. If the brand color signals that text is interactive, that hue (anywhere within ±15°) on non-interactive text tells users to click something that isn't clickable.
+
+```css
+/* Bad: brand blue means both "link" and "decorative heading" */
+a { color: oklch(0.623 0.188 259.815); }
+.section-title { color: oklch(0.65 0.17 259.815); }
+
+/* Good: interactive elements own the brand hue; headings stay neutral */
+a { color: oklch(0.623 0.188 259.815); }
+.section-title { color: oklch(0.279 0.041 260.031); }
+```
+
+## Semantic tokens over raw values
+
+Name colors by role, not by appearance, and apply them only in that role: `--color-text-secondary` is muted foreground text, and using it as a background breaks every future theme change that assumes the role.
+
+```css
+/* Good: tokens named by role, used in that role */
+:root {
+  --color-text-primary: oklch(0.21 0.006 285.885);
+  --color-text-secondary: oklch(0.552 0.016 285.938);
+  --color-separator: oklch(0.92 0.004 286.32);
+  --color-surface: oklch(1 0 0);
+}
+
+/* Bad: separator token repurposed as text color because it "looked right" */
+.caption { color: var(--color-separator); }
+
+/* Bad: secondary-text token repurposed as a background */
+.tag { background: var(--color-text-secondary); }
+```
+
+If a role has no token yet, add the token; don't borrow one that happens to have the right value today. In Tailwind projects, this is the `@theme` block; see [gamut-and-tailwind.md](gamut-and-tailwind.md).
+
+## One colored action per view
+
+When the product uses filled color to encode primary emphasis, give that treatment to one primary action in the current decision context and leave peer actions neutral. Preserve an established component hierarchy that communicates emphasis another way; do not recolor controls merely to impose this recipe. Multiple colored backgrounds are acceptable when they encode distinct states or categories and do not compete as peer actions.
+
+```html
+<!-- Good: one filled primary action, neutral secondaries -->
+<button class="bg-blue-600 text-white">Save</button>
+<button class="text-zinc-700">Cancel</button>
+
+<!-- Bad: every action colored, so nothing is primary -->
+<button class="bg-blue-600 text-white">Save</button>
+<button class="bg-blue-600 text-white">Duplicate</button>
+<button class="bg-blue-600 text-white">Export</button>
+```
+
+Put the color on the background, not the label: a filled `bg-blue-600 text-white` button reads as primary from across the room; blue label text on a neutral button reads as a link. Selected states (an active tab, a checked segment) may use the accent color on the glyph and label: that is state, not emphasis.
+
+## Color across cultures
+
+Color meaning is not universal. If a color is load-bearing (finance, status, alerts), verify the meaning holds in every locale you ship to.
+
+| Color | Common Western reading | Elsewhere |
+| --- | --- | --- |
+| Red | Danger, loss, errors | Luck, prosperity; **gains** in Chinese financial UIs |
+| Green | Success, gains, go | Losses in Chinese financial UIs |
+| White | Purity, cleanliness | Mourning in parts of East Asia |
+| Gold | Premium, luxury | Religious significance in some regions |
+
+The classic case: stock tickers show gains in green for English locales and in red for Chinese locales. If your product localizes into such markets, make the gain/loss colors a per-locale token, not a hardcoded value.
+
+## Light, dark, and increased contrast
+
+Every custom color needs a light and a dark variant; dark mode derivation is covered in [palette-generation.md](palette-generation.md). Beyond that, users who enable increased contrast expect visibly stronger differentiation; supply it with `prefers-contrast`:
+
+```css
+:root {
+  --color-accent: oklch(0.623 0.188 259.815);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root { --color-accent: oklch(0.707 0.165 254.624); }
+}
+
+@media (prefers-contrast: more) {
+  :root { --color-accent: oklch(0.488 0.243 264.376); }
+}
+```
+
+The increased-contrast variant widens the foreground/background lightness gap by at least `0.15` L over the default variant. Then re-verify the pair against APCA's preferred thresholds (Lc 90 body, Lc 75 non-body).
+
+Two testing rules:
+
+- **Recheck every foreground/background pair in both appearances.** A pair that passes in light mode can fail in dark mode; the palettes aren't mirror images.
+- **Account for translucency.** A color on a translucent surface (`backdrop-filter` header, overlay) shifts with whatever scrolls behind it. Test it over the lightest and darkest content it can sit on, or make the surface opaque enough that the shift can't break contrast.
diff --git a/.agents/skills/better-colors/gamut-and-tailwind.md b/.agents/skills/better-colors/gamut-and-tailwind.md
new file mode 100644
index 00000000..f3cd08e7
--- /dev/null
+++ b/.agents/skills/better-colors/gamut-and-tailwind.md
@@ -0,0 +1,103 @@
+# Gamut Awareness & Tailwind v4
+
+## sRGB vs Display P3
+
+Every sRGB color exists within Display P3, but not every P3 color exists within sRGB. Display P3 covers ~50% more colors.
+
+## Max chroma varies by lightness and hue
+
+The gamut boundary is irregular. At L=0.5 in sRGB:
+
+- Highest chroma: purple (H ≈ 285) at C ≈ 0.29
+- Red-orange (H ≈ 0-30): C ≈ 0.20
+- Lowest chroma: cyan (H ≈ 195) at C ≈ 0.09
+
+The peak hue shifts with lightness. At L=0.7 magenta peaks, at L=0.9 green peaks. Cyan consistently has the lowest max chroma.
+
+## Gamut checking
+
+If a color's chroma exceeds the maximum for its L/H/space, it clips. The fix: reduce chroma while keeping L and H constant.
+
+```css
+/* Out of sRGB gamut */
+oklch(0.7 0.35 150)
+
+/* Clamped to max chroma */
+oklch(0.7 0.22 150)
+```
+
+## CSS fallback patterns
+
+```css
+/* sRGB fallback for all browsers */
+.accent {
+  color: oklch(0.7 0.2 150);
+}
+
+/* P3 enhancement for wider gamut displays */
+@media (color-gamut: p3) {
+  .accent {
+    color: oklch(0.7 0.3 150);
+  }
+}
+```
+
+For browsers without oklch support:
+
+```css
+.accent {
+  color: #4ade80;
+}
+
+@supports (color: oklch(0 0 0)) {
+  .accent {
+    color: oklch(0.7 0.2 150);
+  }
+
+  @media (color-gamut: p3) {
+    .accent {
+      color: oklch(0.7 0.3 150);
+    }
+  }
+}
+```
+
+## Tailwind v4
+
+Tailwind CSS v4 defines its default palette in oklch. Custom themes should follow the same convention.
+
+### Custom color scale with @theme
+
+```css
+@theme {
+  --color-brand-50: oklch(0.971 0.012 250);
+  --color-brand-100: oklch(0.932 0.028 250);
+  --color-brand-200: oklch(0.882 0.048 250);
+  --color-brand-300: oklch(0.812 0.078 250);
+  --color-brand-400: oklch(0.722 0.148 250);
+  --color-brand-500: oklch(0.623 0.188 250);
+  --color-brand-600: oklch(0.535 0.168 250);
+  --color-brand-700: oklch(0.445 0.138 250);
+  --color-brand-800: oklch(0.362 0.108 250);
+  --color-brand-900: oklch(0.289 0.078 250);
+  --color-brand-950: oklch(0.215 0.048 250);
+}
+```
+
+This gives you `bg-brand-500`, `text-brand-200`, etc. automatically.
+
+### Opacity modifiers
+
+Tailwind's opacity modifier syntax works with oklch:
+
+```html
+<div class="bg-brand-500/50"></div>
+<!-- Compiles to: oklch(0.623 0.188 250 / 0.5) -->
+```
+
+### Migrating existing themes
+
+1. Convert all hex values in `@theme` to oklch
+2. Replace any `theme()` references that used hex
+3. Test dark mode: oklch values may look slightly different due to perceptual accuracy
+4. Check for hardcoded hex in component code and convert those too
diff --git a/.agents/skills/better-colors/palette-generation.md b/.agents/skills/better-colors/palette-generation.md
new file mode 100644
index 00000000..228988fb
--- /dev/null
+++ b/.agents/skills/better-colors/palette-generation.md
@@ -0,0 +1,93 @@
+# Palette Generation
+
+## The scale convention
+
+Design system palettes use a numeric scale from 50 (lightest) to 950 (darkest). The standard labels by palette size:
+
+| Size | Labels |
+| --- | --- |
+| 5 | 100, 300, 500, 700, 900 |
+| 9 | 50, 100, 200, 300, 500, 700, 800, 900, 950 |
+| 11 | 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950 |
+
+11 steps matches Tailwind's default scales; use 9 as a leaner default when the `400`/`600` in-betweens aren't needed.
+
+## Algorithm
+
+Given a base color with lightness (L), chroma percentage, and hue (H):
+
+**Step 1. Lightness bounds:**
+
+```
+delta = 0.4
+minL = max(0.05, baseL - delta)
+maxL = min(0.95, baseL + delta)
+```
+
+Lightness is clamped to [0.05, 0.95] to avoid pure black/white which have zero chroma.
+
+**Step 2. Distribute lightness** evenly from maxL (lightest, label 50) to minL (darkest, label 950).
+
+**Step 3. Clamp chroma per step.** Each lightness level has a different maximum chroma for a given hue and color space:
+
+```
+maxChroma = findMaxChroma(step[i].L, hue, colorSpace)
+step[i].C = (chromaPercentage / 100) * maxChroma
+```
+
+This ensures every step is within gamut. High-chroma base colors will have lower chroma at the lightest and darkest ends; this is correct and expected.
+
+## CSS variable output
+
+```css
+:root {
+  --color-50: oklch(0.971 0.012 250);
+  --color-100: oklch(0.932 0.028 250);
+  --color-200: oklch(0.882 0.048 250);
+  --color-300: oklch(0.812 0.078 250);
+  --color-500: oklch(0.623 0.188 250);
+  --color-700: oklch(0.445 0.138 250);
+  --color-800: oklch(0.362 0.108 250);
+  --color-900: oklch(0.289 0.078 250);
+  --color-950: oklch(0.215 0.048 250);
+}
+```
+
+## Multi-hue palettes
+
+When generating palettes for multiple hues, use the same **lightness** and **chroma percentage** for all. Same L guarantees equal perceived brightness. Same chroma percentage (not absolute chroma) guarantees equal vividness relative to each hue's maximum.
+
+```css
+:root {
+  /* Same L, same C% (80% of max): different absolute C per hue */
+  --blue-500: oklch(0.623 0.141 250);   /* 80% of max 0.176 */
+  --green-500: oklch(0.623 0.157 145);  /* 80% of max 0.196 */
+  --red-500: oklch(0.623 0.202 25);     /* 80% of max 0.253 */
+}
+```
+
+Different hues have different max chroma at the same lightness. Using the same absolute C value across hues would make some appear more vivid than others.
+
+## Dark mode
+
+Start by swapping the light and dark semantic roles, then tune the mapped values for the dark appearance:
+
+```css
+:root {
+  --color-bg: var(--color-50);
+  --color-text: var(--color-950);
+}
+
+.dark {
+  --color-bg: var(--color-950);
+  --color-text: var(--color-50);
+}
+```
+
+Do not mechanically reverse every palette step. Dark appearances often need different chroma and lightness spacing, and equal OKLCH steps do not guarantee that every foreground/background pair preserves its contrast. Recheck each pair and tune the dark tokens independently where needed.
+
+## Why not HSL palettes?
+
+**Hue drift:** `hsl(240, 80%, 20%)` and `hsl(240, 80%, 90%)` are not the same perceptual hue. The light variant shifts ~16° toward purple. OKLCH hue is stable.
+
+**Brightness inconsistency:** `hsl(60, 100%, 50%)` (yellow) and `hsl(240, 100%, 50%)` (blue) have the same HSL lightness but wildly different perceived brightness.
diff --git a/.agents/skills/better-interface/SKILL.md b/.agents/skills/better-interface/SKILL.md
new file mode 100644
index 00000000..cf0dea40
--- /dev/null
+++ b/.agents/skills/better-interface/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: better-interface
+description: >-
+  User-invoked, cross-discipline interface review that coordinates better-accessibility, better-layout, better-writing, better-typography, better-colors, and better-ui. Use when explicitly invoked for a holistic review of a screen, flow, feature, or product interface. Supports quick and full review modes. Triggers on better-interface, full interface review, holistic UI audit, cross-discipline design review, review the whole interface.
+---
+
+# Review the interface as one system
+
+A strong interface is not six independent audits stapled together. Review the whole experience, let each `better-*` skill own its domain rules, then consolidate the evidence into one prioritized verdict.
+
+This skill owns orchestration only. Accessibility rules belong to `better-accessibility`; structure to `better-layout`; copy to `better-writing`; type to `better-typography`; color to `better-colors`; visual polish and motion to `better-ui`. Never duplicate or override their rules here.
+
+## Core Principles
+
+### 1. Resolve Scope and Mode First
+
+Infer the screen, flow, feature, or repository scope from the request and current workspace. State the resolved scope in the output. Use `full` when no mode is supplied.
+
+| Mode | Coverage | Finding cap |
+| --- | --- | --- |
+| `quick` | Primary user path and highest-traffic states; report only `HIGH` and `MEDIUM` issues | 5 |
+| `full` | Entire requested scope across all six domain skills, including empty, loading, error, and narrow-width states when present | 15 |
+
+If the requested scope is too large to inspect credibly, narrow it to the highest-traffic complete flow and state the boundary. Never imply uninspected surfaces were reviewed.
+
+### 2. Recon Before Judgment
+
+Identify the framework, styling system, component library, design tokens, supported viewports, and available preview or test commands. Follow the project's established Tailwind, plain CSS, CSS-in-JS, token, and component conventions.
+
+### 3. Use Domain Skills as the Sources of Truth
+
+Before reviewing, confirm that all six owning skills below are available. Load and apply every available owner. In `quick` mode, inspect all six domains but spend depth only where the primary flow has evidence. In `full` mode, complete each available domain review before consolidation.
+
+Review in this order so foundational failures are not hidden by polish:
+
+1. `better-accessibility`
+2. `better-layout`
+3. `better-writing`
+4. `better-typography`
+5. `better-colors`
+6. `better-ui`
+
+This skill owns the final response. When a domain skill is loaded through `better-interface`, apply its principles and references but ignore its standalone **Review Output Format**. Use the consolidated format, shared severity, and finding cap in this file instead.
+
+If an owning skill is unavailable, mark that domain `Not reviewed`, name the missing skill, and continue with the remaining domains. Do not recreate its rules from memory, substitute a neighboring skill, or claim holistic coverage.
+
+When two skills appear to cover the same issue, assign it to the skill that owns the underlying rule and mention secondary effects in the **Why** cell. Report it once.
+
+### 4. Require Evidence
+
+Every finding cites `path/to/file:line` and shows the current implementation. If the review artifact has no source files, cite the exact screen and component. Do not report a code-level finding from visual appearance alone or a visual finding from source code alone when runtime behavior determines the result.
+
+### 5. Rank by User Impact
+
+Use one shared severity scale:
+
+- `HIGH`: blocks a task, misleads the user, hides content or controls, causes data-loss risk, or creates a repeated systemic failure.
+- `MEDIUM`: meaningfully harms comprehension, efficiency, adaptability, or consistency.
+- `LOW`: isolated polish with limited task impact. Include only in `full` mode.
+
+Within a severity, rank by reach and leverage. A token or shared-component fix outranks the same symptom in one leaf component.
+
+### 6. Consolidate Systemic Findings
+
+One root cause is one finding. List every confirmed location in the same row rather than producing a row per occurrence. Do not pad the report to reach the finding cap; a short review or no findings is a valid result.
+
+### 7. Make Restraint Visible
+
+Record candidates considered but deliberately rejected. A candidate is rejected when the owning skill permits the current implementation, evidence is insufficient, the project convention is intentional, or the proposed change would add complexity without user benefit.
+
+### 8. Verify What Can Be Verified
+
+Run safe, relevant checks available in the project. Inspect the rendered interface when runtime behavior or visual judgment matters. Report the exact command or interaction and observed result. If a check cannot be run, label it **Not verified** and state what remains; never convert a verification gap into a finding.
+
+### 9. Review Without Mutating by Default
+
+Treat a review request as read-only. Do not edit source code unless the user also asks to implement the findings. When implementation is requested, preserve the consolidated report as the change scope and re-run the relevant verification afterward.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Six disconnected domain reports | Consolidate into one ranked findings table |
+| Same issue reported by multiple skills | Assign it to the skill that owns the underlying rule |
+| Finding with no exact location | Cite `path/to/file:line` and the current implementation |
+| Visual claim inferred only from source | Inspect the rendered state or mark it not verified |
+| Unlimited low-impact polish | Respect the mode cap; omit `LOW` findings in `quick` |
+| Silent gaps in coverage | Show which domains and states were actually inspected |
+| Missing owning skill silently treated as covered | Mark the domain `Not reviewed` and name the unavailable skill |
+| No rejected candidates | Include the required considered-but-rejected table |
+| Review silently edits code | Stay read-only unless implementation was requested |
+| “Approve” with pending actionable findings | Use `Needs changes` or `Block` |
+
+## Review Output Format
+
+Always use the following sections.
+
+### Scope and Coverage
+
+State the mode, exact scope, stack and styling conventions, and any review boundary. Then show coverage:
+
+| Domain | Evidence inspected | Result |
+| --- | --- | --- |
+| Accessibility | Files, components, states, or checks | Findings count or `Clear` |
+
+Include all six domains. `Clear` means inspected with no actionable finding; `Not reviewed` must explain why.
+
+### Findings
+
+Use one table ordered by severity, then reach and leverage:
+
+| # | Severity | Domain | Location | Before | After | Why |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | HIGH | Accessibility | `src/Dialog.tsx:42` | `<button><XIcon /></button>` | Add `aria-label="Close"` and hide the icon from the accessibility tree | The icon-only control has no accessible name |
+
+Each row is one root cause. The **Domain** value is the owning skill without the `better-` prefix. Respect the mode's finding cap. If there are no findings, omit the table and state "No actionable interface findings."
+
+### Considered but Rejected
+
+Include 1–3 candidates in `quick` mode and 2–5 in `full` mode:
+
+| Location | Candidate | Rejected because |
+| --- | --- | --- |
+| `src/Card.tsx:28` | Increase the shadow | Existing depth matches the shared surface token; changing one card would reduce consistency |
+
+These are real candidates inspected during the review, not invented filler. If the scope genuinely contains fewer borderline candidates, include the ones that exist and say so.
+
+### Verification
+
+List each check or interaction, the exact command or steps, and the observed result. Separate checks that passed from checks marked **Not verified**.
+
+### Verdict
+
+End with exactly one:
+
+- `Block` — one or more `HIGH` findings remain.
+- `Needs changes` — only `MEDIUM` or `LOW` findings remain.
+- `Approve` — no actionable findings remain and the claimed coverage was verified.
diff --git a/.agents/skills/better-interface/agents/openai.yaml b/.agents/skills/better-interface/agents/openai.yaml
new file mode 100644
index 00000000..7f9a897b
--- /dev/null
+++ b/.agents/skills/better-interface/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Better Interface"
+  short_description: "Cross-discipline interface review"
+policy:
+  allow_implicit_invocation: false
diff --git a/.agents/skills/better-layout/SKILL.md b/.agents/skills/better-layout/SKILL.md
new file mode 100644
index 00000000..31b5b02b
--- /dev/null
+++ b/.agents/skills/better-layout/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: better-layout
+description: Layout structure for web interfaces, from grouping and alignment to reading order, progressive disclosure, and adaptive breakpoints. Use when structuring a page or component, spacing or aligning controls, deciding what collapses at small sizes, handling RTL layout direction, or reviewing frontend code for layout. Triggers on layout, spacing, alignment, grouping, negative space, whitespace, visual hierarchy, reading order, progressive disclosure, breakpoints, responsive layout, container queries, safe area, full-bleed, edge-to-edge, layout margins, RTL layout, logical properties.
+---
+
+# Layout that communicates structure
+
+Layout communicates before a single word is read: position, spacing, and alignment carry hierarchy on their own, and generous space beats decoration. A good layout also survives stress: resize it, translate it, mirror it for RTL, and it should still hold together. Apply these principles when building or reviewing UI code, and express every change in the project's existing styling system (Tailwind, plain CSS, CSS-in-JS); never introduce a second styling approach.
+
+Hit-area sizes and focus behavior are covered by the `better-accessibility` skill; visual polish (radius, shadows, animation) by the `better-ui` skill; line length and text spacing by the `better-typography` skill.
+
+Treat the numeric values below as starting points for interfaces without an established density or spacing system. Preserve deliberate platform chrome, compact professional tools, and project tokens when they remain usable under hit-area, zoom, localization, and viewport stress tests.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Grouping & Alignment](grouping-and-alignment.md) | Space vs separators, alignment edges, logical properties, importance ordering |
+| [Spacing & Adaptivity](spacing-and-adaptivity.md) | Spacing between targets, layout margins, progressive disclosure, full-bleed content, breakpoints, i18n growth |
+
+## Core Principles
+
+### 1. Group with Space, Not Lines
+
+Negative space is the primary grouping tool; background shapes second; separator lines last, only where space alone can't carry the structure. The gap between groups must be at least 2× the gap within a group (`8px` intra-group → `16px`+ inter-group), or the grouping reads as noise.
+
+### 2. Keep Controls Distinct from Content
+
+Interactive elements must look interactive: a background shape, a border, or a consistent placement zone. Never style a control identically to adjacent static text.
+
+### 3. Align to Shared Edges
+
+Pick alignment edges and stick to them; every stray edge reads as noise. Use one project spacing step for each level of subordination (`16px` is a useful default). Use logical properties (`padding-inline-start`, `margin-inline-end`) for direction-dependent layout; reserve physical left/right for genuinely physical geometry.
+
+### 4. Order by Importance
+
+The most important content sits near the top and the leading edge; reading order flows top-to-bottom, leading-to-trailing. Think in leading/trailing, not left/right.
+
+### 5. Hint at Hidden Content
+
+Progressive disclosure needs a visible affordance. Use the project's established cue; without one, let the next item peek `16–32px` past the scroll edge or show a disclosure control. Content hidden with zero cue may as well not exist.
+
+### 6. Breathing Room Between Targets
+
+Without an established density system, start with `12px` between adjacent bordered or filled controls and `24px` of clearance around borderless text- and icon-only controls. Compact layouts may use less when `better-accessibility` hit areas do not overlap and the controls remain visually distinct.
+
+### 7. Inset Buttons from the Edges
+
+In content layouts, keep full-width buttons inside the layout margins (start near `16px` inline on mobile) with a visible radius. Edge-to-edge actions are acceptable when they intentionally follow established platform or application chrome, account for safe areas, and remain distinguishable from system UI.
+
+### 8. Content Bleeds, Controls Float
+
+Backgrounds and media extend to the viewport edges; controls and text stay inside the layout margins and safe areas (`env(safe-area-inset-*)`). Sticky chrome floats above the content layer, it doesn't dam it.
+
+### 9. Hold Structure Until It Breaks
+
+Breakpoints come from the content, not device presets. Keep the expanded layout as long as it genuinely fits and collapse late; prefer container queries for component-level adaptation. Test the smallest and largest sizes first.
+
+### 10. Plan for Growth and Clipping
+
+Plan for substantial and language-dependent string growth rather than relying on a universal percentage: no fixed widths or heights on text containers, and let rows wrap. Never park critical actions where resizing or scrolling clips them; keep them reachable in the normal flow or stable chrome appropriate to the product.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Separator line where spacing would do | Remove the line, double the gap between groups |
+| `margin-left` / `padding-right` in a localizable layout | `margin-inline-start` / `padding-inline-end` |
+| Content-layout button accidentally touches the viewport | Inset within the project margins; preserve intentional platform chrome |
+| Carousel/scroller that looks complete | Let the next item peek `16–32px` past the edge |
+| Adjacent controls merge or expanded hit areas overlap | Increase the gap using the project scale; use `12px`/`24px` as starting points |
+| Breakpoints at 768/1024 because they're the defaults | Break where the content actually stops fitting |
+| Fixed-width text container sized to one language | `max-width` + wrapping; test pseudo-localization and representative locales |
+| Primary action at the clip-prone bottom of a pane | Sticky positioning or stable chrome with safe-area padding |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone layout review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` blocks content or an action at a supported viewport; `MEDIUM` harms hierarchy, reading order, or adaptability; `LOW` is isolated alignment or spacing polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current layout and an actionable replacement.
+- **Why**: name the violated principle and its effect on comprehension or adaptability.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Group with space, not lines
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Settings.tsx:41` | `border-b` on every settings row | Remove borders; use `space-y-2` within groups and `space-y-8` between groups | Spacing communicates grouping with less visual noise |
+| LOW | `src/ProfileForm.tsx:58` | `<hr>` between form sections | Replace with `mt-10` on each section heading | Section hierarchy should not depend on repeated rules |
+
+#### Align to shared edges
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Card.tsx:24` | Card text at `pl-4`, card icon at `pl-3` | Align both to the same `pl-4` edge | Shared edges create a legible structure |
+| MEDIUM | `src/Nav.css:19` | `margin-left: 16px` | `margin-inline-start: 16px` | Physical properties break direction-aware layouts |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results across the relevant viewport widths, reading order, zoom, and RTL state. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable layout findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-layout/agents/openai.yaml b/.agents/skills/better-layout/agents/openai.yaml
new file mode 100644
index 00000000..4a43b675
--- /dev/null
+++ b/.agents/skills/better-layout/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Layout"
+  short_description: "Structure, grouping, alignment and adaptive layout"
diff --git a/.agents/skills/better-layout/grouping-and-alignment.md b/.agents/skills/better-layout/grouping-and-alignment.md
new file mode 100644
index 00000000..ff84d0a6
--- /dev/null
+++ b/.agents/skills/better-layout/grouping-and-alignment.md
@@ -0,0 +1,123 @@
+# Grouping & Alignment
+
+How spacing, shapes, shared edges, and ordering communicate what belongs together and what matters most.
+
+## Group with Space, Not Lines
+
+Three tools create grouping, in order of preference:
+
+1. **Negative space**: the default. Related items sit close; unrelated items sit far apart.
+2. **Background shapes**: a card or filled container, when a group needs to read as one unit (a selectable row, a draggable card).
+3. **Separator lines**: last resort, for dense data where space would cost too much (tables, long settings lists).
+
+The structural rule: the gap between groups must be at least 2× the gap within a group. If items inside a group are `8px` apart, groups need `16px`+ between them, otherwise the eye can't tell where one group ends.
+
+```css
+/* Good: spacing alone communicates the grouping */
+.field-group { display: flex; flex-direction: column; gap: 8px; }
+.form { display: flex; flex-direction: column; gap: 24px; }
+
+/* Bad: uniform spacing plus lines to compensate */
+.form > * { margin-bottom: 12px; border-bottom: 1px solid var(--separator); }
+```
+
+```html
+<!-- Good: Tailwind -->
+<div class="space-y-6">
+  <div class="space-y-2">…field group…</div>
+  <div class="space-y-2">…field group…</div>
+</div>
+```
+
+When a separator is genuinely needed, keep it quiet: hairline width, low contrast, and never combined with a large gap (the gap already did the job).
+
+## Keep Controls Distinct from Content
+
+Interactive elements need a visual signal that they're interactive: a background, a border, an underline, or placement in a consistent control zone (toolbar, footer row). A control styled identically to static text is invisible.
+
+```html
+<!-- Bad: action looks exactly like the description text next to it -->
+<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
+
+<!-- Good: the action reads as an action -->
+<p class="text-zinc-600">Your trial ends soon.</p>
+<button class="font-medium text-blue-600">Upgrade now</button>
+```
+
+The inverse also holds: don't give static elements control styling. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
+
+## Align to Shared Edges
+
+Pick a small set of alignment edges and put everything on them; the eye tracks straight edges to scan content.
+
+- Every stray edge (an icon 2px off the text edge, a card padded differently from its neighbor) reads as noise even when nobody can name the problem.
+- Use one consistent project spacing step to express hierarchy; `16px` is a useful default when no scale exists, and deeper nesting repeats the same step.
+- Numbers in tables right-align to the trailing edge (see `better-typography` for tabular figures); text left-aligns to the leading edge.
+
+```css
+/* Good: one shared leading edge, one indent step */
+.section { padding-inline: 24px; }
+.section .child { margin-inline-start: 16px; }
+
+/* Bad: three unrelated leading edges in one column */
+.header { padding-inline-start: 20px; }
+.list-item { padding-inline-start: 14px; }
+.footer { padding-inline-start: 24px; }
+```
+
+## Logical Properties, Not Physical
+
+Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
+
+| Physical (avoid) | Logical (use) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `border-right` | `border-inline-end` |
+
+```html
+<!-- Good: Tailwind logical utilities -->
+<div class="ms-4 pe-6 text-start">…</div>
+
+<!-- Bad: breaks in RTL -->
+<div class="ml-4 pr-6 text-left">…</div>
+```
+
+Reserve physical properties for things that genuinely refer to physical screen sides regardless of language, e.g. positioning relative to a device notch, or an element that must match a physical gesture direction.
+
+When the arrangement of elements encodes progression (star ratings, step indicators, progress bars), the sequence mirrors in RTL: stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements don't. Digit order inside numbers never reverses; that and other bidi text rules live in the `better-typography` skill.
+
+## Order by Importance
+
+Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
+
+- The most important information sits near the top and the leading edge; the further down and trailing something sits, the less attention it gets.
+- Give essential information room. Don't bury the one number the user came for under rows of secondary detail; push secondary content into collapsed sections, tabs, or detail views.
+- Within a row, the identifying content (name, title) leads; metadata and actions trail.
+
+```html
+<!-- Good: primary fact first, detail demoted -->
+<div>
+  <p class="text-2xl font-semibold">$4,320.00</p>
+  <p class="text-sm text-zinc-500">Available balance</p>
+</div>
+
+<!-- Bad: the key fact is buried below the fold of the card -->
+<div>
+  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
+  <p class="text-sm">Last statement: June 30</p>
+  <p class="text-sm">Balance: $4,320.00</p>
+</div>
+```
+
+Think in **leading/trailing**, not left/right: combined with logical properties, the same hierarchy mirrors correctly in RTL locales.
+
+## Don't Overload the Entry Point
+
+The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
+
+- One primary action per view (see `better-colors` for how color enforces this).
+- Group secondary actions behind a menu once they exceed two or three.
+- Prefer a short view that links deeper over a long view that shows everything at level one.
diff --git a/.agents/skills/better-layout/spacing-and-adaptivity.md b/.agents/skills/better-layout/spacing-and-adaptivity.md
new file mode 100644
index 00000000..75c09126
--- /dev/null
+++ b/.agents/skills/better-layout/spacing-and-adaptivity.md
@@ -0,0 +1,159 @@
+# Spacing & Adaptivity
+
+Space between controls, margins against the viewport, hinting at off-screen content, and layouts that survive resizing and translation.
+
+## Breathing Room Between Targets
+
+Controls placed too close together get mis-tapped and read as one unit. When the project has no established density scale, use these starting points:
+
+| Between | Starting point |
+| --- | --- |
+| Adjacent bordered/filled controls (buttons, inputs) | `12px` |
+| Around borderless controls (text buttons, icon buttons) | `24px` |
+| Unrelated control groups | `24px`+ (2× the intra-group gap) |
+
+Borderless controls usually need more clearance because nothing marks where one target ends and the next begins; the space itself is the boundary. Compact professional tools may use less when the hit areas remain distinct and do not overlap. Preserve an established, usable density instead of expanding controls solely to match these values.
+
+```html
+<!-- Good: bordered buttons at 12px, icon buttons given room -->
+<div class="flex gap-3">
+  <button class="rounded-lg border px-4 py-2">Cancel</button>
+  <button class="rounded-lg bg-blue-600 px-4 py-2 text-white">Save</button>
+</div>
+
+<!-- Bad: three borderless icon buttons packed at 4px -->
+<div class="flex gap-1">
+  <button><TrashIcon /></button>
+  <button><ArchiveIcon /></button>
+  <button><ShareIcon /></button>
+</div>
+```
+
+WCAG target-size requirements, larger usability targets, and pseudo-element expansion are covered by the `better-accessibility` skill; these clearances are in addition, so expanded hit areas never overlap.
+
+## Inset Buttons from the Edges
+
+In content layouts, buttons pressed accidentally against the viewport can look like system chrome and clip against curved corners or gesture zones. Keep them inside the layout margins. Edge-to-edge actions remain valid when they intentionally are application/platform chrome and account for safe areas:
+
+```css
+/* Good: inset action bar */
+.action-bar {
+  padding-inline: 16px;
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+.action-bar button { width: 100%; border-radius: 12px; }
+
+/* Bad: button glued to all three edges */
+.action-bar button {
+  width: 100vw;
+  border-radius: 0;
+  position: fixed;
+  bottom: 0;
+}
+```
+
+Start near `16px` inline margin on mobile when the project has no layout token; the button can still span the full content width inside those margins.
+
+## Progressive Disclosure Needs an Affordance
+
+Hiding complexity is good; hiding it without a cue is a trap. Every piece of off-screen or collapsed content needs a visible hint that it exists. Preserve the product's established scroll indicator or disclosure pattern; use the recipes below when no clear cue exists:
+
+- **Peeking items.** In a horizontal scroller or carousel, size items so the next one peeks `16–32px` past the container edge. A row of cards that ends exactly at the edge looks complete, and nobody scrolls it.
+- **Disclosure controls.** Collapsed sections get a chevron or "Show more" control; the label states what's hidden ("Show 12 more results"), not just "More".
+- **Truncation cues.** Clamped text shows an ellipsis and a way to expand; see `better-typography` for truncation mechanics.
+
+The peeking-scroller recipe: the container's padding creates the peek, and snap points stay on the content edge.
+
+```css
+.scroller {
+  display: flex;
+  gap: 12px;
+  overflow-x: auto;
+  padding-inline: 24px;
+  scroll-padding-inline: 24px;
+  scroll-snap-type: x mandatory;
+}
+.scroller > * {
+  flex: 0 0 calc(100% - 48px - 24px); /* container minus margins minus peek */
+  scroll-snap-align: start;
+}
+```
+
+```html
+<!-- Tailwind: the 80% width keeps the next card's leading 16-32px visible -->
+<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+</div>
+```
+
+## Content Bleeds, Controls Float
+
+The two layers behave differently at the edges:
+
+- **Content layer**: backgrounds, hero media, and scrollable lists extend to the viewport edges.
+- **Control layer**: text and controls stay inside the layout margins and safe areas, floating above the content.
+
+```css
+/* Good: full-bleed media inside a constrained article */
+.article {
+  display: grid;
+  grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr;
+}
+.article > * { grid-column: 2; }
+.article > .full-bleed { grid-column: 1 / -1; }
+```
+
+Sticky headers and floating action buttons account for safe areas:
+
+```css
+.fab {
+  position: fixed;
+  inset-inline-end: calc(16px + env(safe-area-inset-right));
+  bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+## Hold Structure Until It Breaks
+
+Breakpoints belong to the content, not the device catalog:
+
+- Break where the layout actually stops fitting (when the sidebar squeezes the content below its minimum measure, when the card grid drops below a usable column width), not at `768px` because a preset says so.
+- Collapse late. A layout that keeps its expanded structure as long as it genuinely fits stays stable and familiar; premature collapsing throws away space users paid for.
+- Prefer **container queries** for components: a card should adapt to the column it's in, not to the viewport.
+
+```css
+/* Good: component adapts to its container */
+.card-list { container-type: inline-size; }
+@container (max-width: 400px) {
+  .card { grid-template-columns: 1fr; }
+}
+
+/* Bad: viewport media query breaks the card inside a narrow sidebar */
+@media (max-width: 768px) {
+  .card { grid-template-columns: 1fr; }
+}
+```
+
+Test order: the smallest supported size and the largest first (those break first), then the sizes in between.
+
+## Plan for Growth and Clipping
+
+Layouts fail in two directions: content grows, and viewports shrink.
+
+**String expansion varies substantially by language and source-string length.** Do not rely on one universal percentage. Rules:
+
+- No fixed widths sized to English labels; use `max-width` plus wrapping.
+- No fixed heights on text containers; use `min-height` if a floor is needed.
+- Buttons size themselves from their label (`padding-inline`), never a hardcoded width.
+- Test with pseudo-localization or a long-string locale before shipping.
+
+```css
+/* Good: label defines the size */
+.button { padding-inline: 16px; white-space: nowrap; }
+
+/* Bad: German will overflow or truncate */
+.button { width: 96px; overflow: hidden; }
+```
+
+**Clipping:** never park critical actions where they can be cut off: the bottom edge of a resizable pane, below the fold of a fixed-height modal, behind an expanding keyboard. Keep primary actions in stable chrome: a sticky footer with safe-area padding, or the top of the view. If a modal's content scrolls, its action row doesn't.
diff --git a/.agents/skills/better-typography/SKILL.md b/.agents/skills/better-typography/SKILL.md
new file mode 100644
index 00000000..ecfe1a26
--- /dev/null
+++ b/.agents/skills/better-typography/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: better-typography
+description: Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.
+---
+
+# Great typography
+
+Good typography is mostly restraint. A sensible scale, comfortable spacing and enough contrast beat any clever effect. A label, a table cell, a marketing headline and an article paragraph should not share one set of rules. Apply these principles when building or reviewing anything with text in it.
+
+When reviewing, read the page instead of scanning the code: squint to check the hierarchy holds, read one full paragraph for comfort, and resize the viewport to catch bad wrapping, widows and truncation at real content lengths.
+
+The words themselves (button labels, error messages, empty states) are covered by the `better-writing` skill; semantic heading structure by `better-accessibility`; spatial RTL layout and logical CSS properties by `better-layout`; rendered-pair contrast measurement and color remediation by `better-colors`. This skill owns how text renders, wraps, and behaves in mixed-direction content.
+
+**Match the project's styling system.** Before suggesting or writing any fix, check how the codebase styles things and express every change in that system: Tailwind utilities in a Tailwind project, plain declarations in CSS, CSS Modules, styled-components or StyleX. The [cheat sheet](css-cheat-sheet.md) maps each declaration to its Tailwind equivalent. Never introduce a second styling approach just to apply a typography fix.
+
+## Quick Reference
+
+| Category | When to use | Reference |
+| --- | --- | --- |
+| Choosing fonts | Font categories, pairing, formats, typeface anatomy | [choosing-fonts.md](choosing-fonts.md) |
+| Variable fonts & OpenType | Axes, weights, tabular numbers, stylistic sets | [variable-fonts-and-opentype.md](variable-fonts-and-opentype.md) |
+| Spacing & sizing | Type scale, heading hierarchy, line-height, letter-spacing, text trimming | [spacing-and-sizing.md](spacing-and-sizing.md) |
+| Wrapping & punctuation | Measure, wrapping, truncation, smart punctuation, RTL | [wrapping-and-punctuation.md](wrapping-and-punctuation.md) |
+| Details & accessibility | Underlines, selection, forms, decorative text, contrast | [details-and-accessibility.md](details-and-accessibility.md) |
+| CSS cheat sheet | Quick lookup of every property covered, with Tailwind equivalents | [css-cheat-sheet.md](css-cheat-sheet.md) |
+
+## Core Principles
+
+### 1. Serve the Right Format
+
+Use `.woff2` (Brotli compression, broadly supported) on the web. `.woff` is a fallback only for very old browsers; `.ttf` and `.otf` are raw desktop formats with no web compression. How the files are loaded is the project's own concern, this skill does not prescribe it.
+
+### 2. Properties Over Raw Tags
+
+When a CSS property exists, use it. `font-weight: 650` instead of `font-variation-settings: "wght" 650`, `font-optical-sizing: auto` instead of `"opsz"`, `font-variant-numeric: tabular-nums` instead of `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders. Reserve the raw-tag properties for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) that have no property of their own.
+
+### 3. Load Intended Weights and Styles
+
+Browsers may synthesize a requested weight or style that the active family does not provide. Prefer loading the faces the design actually uses. Set `font-synthesis: none` only after verifying that every required bold, italic, small-cap, superscript, and subscript form remains visually distinct across the complete fallback stack; disabling synthesis is not a diagnostic and must not erase emphasis.
+
+### 4. Fewer Fonts, Sizes and Weights
+
+Rarely use more than three fonts. Weight and size define hierarchy, but overusing them hurts readability quickly. Pair for contrast, not similarity: a serif headline with a sans body reads as deliberate, two near-identical sans-serifs read as a mistake. Below `18px`, stay at weight `400`+; weights under `300` are display-only (`28px`+), they disappear at text sizes.
+
+### 5. Use a Type Scale with Semantic Names
+
+Define a small set of sizes and deviate from it as little as possible. Hard-coded sizes without a system break down at scale. For solo projects, default names like `text-sm` work fine as long as the usage rules are clear. On a team, name sizes by use (`text-body-sm`), not by size, so the rules stay consistent.
+
+### 6. Heading Sizes Descend with Level
+
+Within a coherent page hierarchy, map heading levels to descending steps of the type scale: a visually subordinate heading should not accidentally overpower its parent. Adjacent levels may share a size toward the small end of the scale as long as weight or spacing keeps them distinct. Pick semantic heading elements according to `better-accessibility`; this skill controls only their visual treatment.
+
+### 7. Line-Height by Role
+
+Headings tighter, around `1.1`. Body copy `1.5` to `1.6`. Prefer unitless values so line-height scales with the font size; fixed values like `24px` do not. Tight line-height is for short text: anything that wraps to three or more lines needs at least `1.4`, even in height-constrained rows.
+
+### 8. Letter-Spacing by Size
+
+Large headings often look better with slightly negative letter-spacing. Small uppercase labels need a little positive letter-spacing so letters do not feel crowded. Body copy at reading sizes needs neither.
+
+### 9. Cap the Measure
+
+Long lines make it hard for the eye to find the next line. Cap long-form text around 60–75 characters per line. Any unit works: `65ch` measures characters directly, and a pixel or rem cap is just as good: at a `16px` body size the range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` or `max-w-2xl` fit. What matters is that a cap exists and the resulting line length sits in range.
+
+### 10. Wrap Deliberately
+
+`text-wrap: balance` distributes text evenly across lines: use it on headings. `text-wrap: pretty` avoids leaving a single short word on the final line: use it on descriptions. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read. `overflow-wrap: break-word` where long words, links or IDs could escape the container. `white-space: nowrap` on labels and badges where a line break looks broken.
+
+### 11. Tabular Numbers on Changing Values
+
+Digits have different widths by default, so timers, counters and prices shift layout as they update. Apply `font-variant-numeric: tabular-nums` to any value that changes.
+
+### 12. Truncate Without Losing Content
+
+Single line: `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap`. Multiple lines: `line-clamp`. Truncation hides content, so if the missing text matters, keep the full value reachable in a tooltip or expanded view.
+
+### 13. Write Copy Naturally, Style with CSS
+
+Store text in natural case and control presentation with `text-transform`, so redesigns never require rewriting copy. Use smart punctuation: curly quotes in prose (straight quotes in code), an en dash for ranges like `2010–2020`, an em dash to set off a thought, the single ellipsis character, `&nbsp;` to keep values like `16 px` together and `&shy;` to control where long words may break.
+
+### 14. Underlines from the Font
+
+Default underlines sit wherever the browser decides. Pull position and thickness from the font's own metrics with `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune manually with `text-decoration-thickness`, `text-underline-offset` and `text-decoration-skip-ink`. `text-decoration-style` draws the line dotted, dashed or wavy; a dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term. Unless the only thing animating is a color change, build the underline as a separate element instead of using `text-decoration`: color is the only part of a real underline that animates reliably.
+
+### 15. Inputs at 16px on Mobile
+
+iOS Safari zooms the whole page when an input's text is smaller than `16px`. Keep input text at `16px` on mobile viewports (`text-base sm:text-sm`). Avoid the `maximum-scale=1` viewport meta: Safari ignores it for pinch zoom, but every other browser honors it and blocks zooming, which fails WCAG.
+
+### 16. Size and Contrast Floors
+
+Start long-form body text near the browser default of `16px`, then judge it in the actual typeface, measure, platform, and product density. UI text can go smaller: `14px` is a useful starting point for inputs and menus (inputs still need `16px` on mobile, see principle 15), `13px` for captions, rarely below `12px`. When text appears low-contrast, use `better-colors` to measure the rendered pair and `better-accessibility` to classify the requirement; do not change colors unless asked.
+
+### 17. Font Smoothing on the Root
+
+On macOS text renders heavier than intended. Apply `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` (both covered by Tailwind's `antialiased`) once on the root layout so they cover all text.
+
+### 18. Language and Bidi Behavior
+
+Set `lang` so browsers and assistive technology choose the right pronunciation, quotes, and hyphenation. Set `dir` at the document or content boundary where direction changes, preserve digit order, and use `<bdi>` for isolated mixed-direction values when needed. Spatial mirroring and logical CSS properties belong to `better-layout`.
+
+### 19. Keep Useful Text Selectable
+
+`::selection` can carry brand into the reading experience when the selected combination stays legible. Keep text selectable by default. Use `user-select: none` only on a specific draggable or gesture-driven surface where accidental selection demonstrably interferes with the interaction; never disable selection across the interface or merely because a button label can be highlighted.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `.ttf`/`.otf` served on the web | Convert to `.woff2` |
+| `font-variation-settings: "wght"` for weight | `font-weight` (works with non-variable fallbacks) |
+| `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` |
+| Synthesized face differs from the intended design | Load the required face; disable only the verified synthesis mode without erasing emphasis |
+| Hard-coded one-off font sizes | Use the type scale |
+| Child heading visually overpowers its parent | Map that section's hierarchy to descending scale steps |
+| Heading element picked for its default size | Choose semantics with `better-accessibility`, then set the visual size in CSS |
+| `line-height: 24px` on scalable text | Unitless value (`1.5`) |
+| Full-width paragraphs | Cap around 60–75 characters per line |
+| Orphan on the last line of a paragraph | `text-wrap: pretty` |
+| Lopsided two-line heading | `text-wrap: balance` |
+| Numbers cause layout shift | `tabular-nums` |
+| Truncated text with no way to read it | Tooltip or expanded view for the full value |
+| `UPPERCASE` typed into copy | Natural case + `text-transform` |
+| Justified text in an interface | `text-align: start`; reserve justify for specific editorial layouts |
+| Underline cuts through descenders | `text-decoration-skip-ink: auto`, `from-font` metrics |
+| Inputs below `16px` zoom on iOS | `text-base sm:text-sm` |
+| Root layout omits font smoothing | Apply `antialiased` once at the root |
+| Mixed-direction value renders in the wrong order | Set the correct `lang`/`dir`; isolate the value with `<bdi>` when needed |
+| Selection disabled across application chrome | Restore selection; suppress it only on a specific interaction that conflicts with dragging or gestures |
+| Extra-info hint with no visual cue | Dotted underline via `text-decoration-style: dotted` |
+| Thin/Light weight on `14px` UI text | Weight `400`+ below `18px`; thin weights are display-only |
+| `leading-none` on a three-line card description | At least `1.4` on any text that wraps to 3+ lines |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone typography review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes text unreadable, unavailable, or structurally misleading; `MEDIUM` harms hierarchy, wrapping, or scanning; `LOW` is isolated typographic polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current typography and an actionable replacement.
+- **Why**: name the violated principle and its effect on readability or hierarchy.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Tabular numbers
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Price.tsx:17` | `<span>{price}</span>` on a live price | `<span className="tabular-nums">{price}</span>` | Proportional digits cause changing values to shift |
+| LOW | `src/numbers.css:8` | `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` | The high-level property preserves fallback behavior |
+
+#### Line-height and measure
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Article.tsx:33` | `leading-none` on a body paragraph | `leading-normal` (`1.5`–`1.6`) | Wrapped body text needs enough vertical separation |
+| MEDIUM | `src/article.css:12` | Full-width article column | `max-width` near 65 characters at `16px` | Long measures make lines hard to track |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including wrapping, hierarchy, text resizing, font loading, and dynamic-value stability when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable typography findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-typography/agents/openai.yaml b/.agents/skills/better-typography/agents/openai.yaml
new file mode 100644
index 00000000..ab3f8a08
--- /dev/null
+++ b/.agents/skills/better-typography/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Typography"
+  short_description: "Web typography from fonts to spacing and wrapping"
diff --git a/.agents/skills/better-typography/choosing-fonts.md b/.agents/skills/better-typography/choosing-fonts.md
new file mode 100644
index 00000000..fb34bb40
--- /dev/null
+++ b/.agents/skills/better-typography/choosing-fonts.md
@@ -0,0 +1,64 @@
+# Choosing fonts
+
+Choosing a typeface, the right file format and understanding why fonts look the way they do.
+
+## Choosing a typeface
+
+Font families set the tone before the specific font does.
+
+| Category | Traits | Use for |
+| --- | --- | --- |
+| Serif | Small strokes at the ends of letters guide the eye along a line | Long passages, editorial reading |
+| Sans-serif | Clean, even shapes that stay crisp at small sizes | Default for most interfaces (Helvetica, Inter, Geist) |
+| Monospace | Every glyph the same width so columns line up | Code, tables, tabular data |
+| Display | Drawn for large headlines | Marketing headlines, hero text |
+| Script | Mimics handwriting | Rare, decorative moments |
+
+CSS exposes `cursive` and `fantasy` keywords for the last two categories.
+
+"Display" in a font's name does not make it a display font. Fonts like SF Pro and Heldane ship a `Display` variant for large sizes and a `Text` variant for smaller sizes. Use the variant that matches the size you are setting.
+
+### Rules
+
+- Fewer fonts is usually better. Rarely use more than three. Marketing pages can be more expressive than apps.
+- The same applies to sizes and weights. They define hierarchy, but overusing them hurts readability quickly.
+- Pair for contrast, not similarity. A serif headline with a sans body looks like a deliberate display/reading split. Two near-identical sans-serifs look like a mistake.
+- Thin weights are display-only. Below `18px`, stay at weight `400`+; Ultralight/Thin/Light (`100`–`300`) strokes disappear at text sizes and on low-DPI screens. Reserve them for `28px`+ display text, and even there check they hold up against the background.
+
+## Font family scope
+
+Applying or reviewing typography never requires a new typeface. Use the product's existing type system unless the task explicitly asks for a type change, and do not introduce a paid or proprietary face just to satisfy a review checklist. Rendering details like font smoothing, text wrapping and tabular numbers do not override the project's chosen font family.
+
+When a type change is asked for: a system-native macOS/iOS feel comes from the system stack; a commercial face such as Helvetica Now is a brand decision and keeps a practical fallback stack.
+
+```css
+/* System-native macOS/iOS feel */
+html {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+/* Commercial brand face with safe fallbacks */
+html {
+  font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
+## Formats
+
+| Format | Notes |
+| --- | --- |
+| `.woff2` | Brotli compression, broadly supported. Use this on the web. |
+| `.woff` | Older compression. Fallback only for very old browsers. |
+| `.ttf` / `.otf` | Raw formats, no web compression, larger files. Desktop only unless there is no other option. |
+
+## Anatomy of a typeface
+
+| Term | Meaning |
+| --- | --- |
+| x-height | Height of a lowercase `x` |
+| Cap height | Height of uppercase letters |
+| Baseline | The invisible line letters sit on |
+| Ascender | Part of a letter rising above the x-height |
+| Descender | Part dropping below the baseline |
+
+These measurements are why two fonts at the same `font-size` can look like different sizes. A font with a large x-height looks bigger.
diff --git a/.agents/skills/better-typography/css-cheat-sheet.md b/.agents/skills/better-typography/css-cheat-sheet.md
new file mode 100644
index 00000000..f3d29419
--- /dev/null
+++ b/.agents/skills/better-typography/css-cheat-sheet.md
@@ -0,0 +1,65 @@
+# CSS cheat sheet
+
+One-line lookup for every typography CSS declaration covered by this skill, with the Tailwind 4 equivalent. Where no utility exists, the arbitrary-value form is shown. Pick the column that matches the project: the declaration in plain CSS, CSS Modules, styled-components or StyleX codebases, the utility in Tailwind codebases.
+
+## Font
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `font-family: sans-serif` | The sans family | `font-sans` |
+| `font-family: serif` | The serif family | `font-serif` |
+| `font-family: monospace` | The monospace family | `font-mono` |
+| `font-size` | Size from the type scale | `text-*` |
+| `font-weight` | Any value from 1 to 1000 | `font-*` |
+| `font-style: italic` | Switch to italic style | `italic` |
+| `-webkit-font-smoothing` + `-moz-osx-font-smoothing` | Smooth macOS font rendering; apply once at the root | `antialiased` |
+| `font-synthesis: none` | Disable all synthesized forms after verifying fallbacks and emphasis | `[font-synthesis:none]` |
+| `font-feature-settings` | Toggle OpenType features | `[font-feature-settings:"ss01"]` |
+| `font-variation-settings` | Tune variable font axes | `[font-variation-settings:"GRAD"_80]` |
+| `font-optical-sizing` | Adjust details per size | `[font-optical-sizing:auto]` |
+| `font-variant-caps` | Real small capitals | `[font-variant-caps:small-caps]` |
+| `font-variant-position` | Real super and subscripts | `[font-variant-position:super]` |
+| `font-variant-numeric: tabular-nums` | Equal-width digits | `tabular-nums` |
+| `font-variant-numeric: slashed-zero` | Tell 0 from O | `slashed-zero` |
+
+## Spacing and layout
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `letter-spacing` | Space between letters | `tracking-*` |
+| `line-height` | Space between lines | `leading-*` |
+| `font-kerning` | Kerning on or off | `[font-kerning:none]` |
+| `text-box: trim-both` | Trim space above and below | `[text-box:trim-both_cap_alphabetic]` |
+| `max-width` on text columns | Cap at ~60–75 characters per line | `max-w-xl` / `max-w-2xl` / `max-w-[65ch]` |
+| `text-align` | Where lines start and end | `text-start` / `text-center` |
+
+## Wrapping and overflow
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-wrap: balance` | Even out heading lines | `text-balance` |
+| `text-wrap: pretty` | Avoid orphaned words | `text-pretty` |
+| `text-overflow: ellipsis` | Ellipsis for clipped text | `truncate` |
+| `line-clamp` | Cut off after N lines | `line-clamp-*` |
+| `overflow-wrap: break-word` | Break long strings | `break-words` |
+| `white-space: nowrap` | Stop wrapping | `whitespace-nowrap` |
+| `text-transform` | Change the casing | `uppercase` / `capitalize` |
+
+## Decoration and interaction
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-decoration-line: underline` | Draw an underline | `underline` |
+| `text-decoration-color` | Underline color | `decoration-*` |
+| `text-decoration-thickness` | Underline thickness | `decoration-1` / `decoration-2` |
+| `text-underline-offset` | Push the line down | `underline-offset-*` |
+| `text-underline-position: from-font` | Underline position from the font | `[text-underline-position:from-font]` |
+| `text-decoration-style` | Dotted, dashed or wavy | `decoration-dotted` / `decoration-wavy` |
+| `text-decoration-thickness: from-font` | Underline set by the font | `decoration-from-font` |
+| `text-decoration-skip-ink` | Gaps around descenders | `[text-decoration-skip-ink:auto]` |
+| `caret-color` | Tint the text cursor | `caret-*` |
+| `user-select: none` | Suppress selection on a verified drag/gesture conflict only | `select-none` |
+| `text-shadow` | Shadow behind the letters | `text-shadow-*` |
+| `-webkit-text-stroke` | Outline the letters | `[-webkit-text-stroke:1px_black]` |
+| `background-clip: text` | Clip a background to the letters | `bg-clip-text` |
+| `initial-letter` | Size a drop cap | `[initial-letter:3]` |
diff --git a/.agents/skills/better-typography/details-and-accessibility.md b/.agents/skills/better-typography/details-and-accessibility.md
new file mode 100644
index 00000000..abe484b3
--- /dev/null
+++ b/.agents/skills/better-typography/details-and-accessibility.md
@@ -0,0 +1,109 @@
+# Details and accessibility
+
+Underlines, selection, forms, decorative text and the floors that keep everything readable.
+
+## Underlines
+
+Default underline position is browser-determined: sometimes too close, cutting through descenders or too thin. Pull position and thickness from the font's own metrics:
+
+```css
+a {
+  text-underline-position: from-font;
+  text-decoration-thickness: from-font;
+}
+```
+
+The line does not have to be solid. `text-decoration-style` can draw it dotted, dashed or wavy. A dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term:
+
+```css
+abbr {
+  text-decoration: underline dotted;
+}
+```
+
+Or tune manually:
+
+```css
+a {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+  text-decoration-color: var(--color-gray-1000);
+  transition: text-decoration-color 200ms ease-out;
+}
+
+a:hover {
+  text-decoration-color: var(--color-gray-1200);
+}
+```
+
+Unless the only thing animating is a color change, build the underline as a custom element instead of using `text-decoration`: color is the only part of a real underline that animates reliably. Animate the custom element however the effect requires.
+
+## Selection
+
+- `::selection` changes the background and color of selected text; a subtle way to embed brand. Keep the combination legible.
+- Keep text selectable by default, including application chrome; users copy labels, identifiers, errors, and values in ways the designer may not predict.
+- Use `user-select: none` only on a specific draggable or gesture-driven surface where accidental selection conflicts with the interaction. Do not apply it globally or solely to imitate native chrome.
+- `::target-text` styles the phrase a shared link scrolls to.
+- The Custom Highlight API styles ranges you pick yourself, like search matches, without extra markup.
+
+## Forms and editable text
+
+- `::placeholder` styles the hint in an empty field.
+- `caret-color` colors the blinking insertion bar. Color is about as far as caret styling goes: a fully custom caret is very difficult to build and usually not worth it unless a very specific effect calls for it.
+
+### iOS input zoom
+
+Focusing an input with text smaller than `16px` zooms the whole page (an accessibility feature: `16px` is the web default and Safari treats smaller as too hard to read while typing).
+
+```tsx
+// Good: 16px on mobile, smaller from the sm breakpoint up
+<input className="text-base sm:text-sm" type="email" />
+```
+
+Avoid the `maximum-scale=1` viewport meta as a fix: Safari ignores the cap for pinch zoom, but every other browser honors it and restricts pinch zoom, which fails WCAG 1.4.4. The responsive input size solves the zoom with no accessibility cost.
+
+## Decorative text
+
+| Property | Effect |
+| --- | --- |
+| `::first-letter` | Drop cap, widely supported |
+| `::first-line` | Styles only the first line |
+| `initial-letter` | Sizes the drop cap; limited support, no Firefox yet |
+| `background-clip: text` | Clips a background or gradient to the letter shapes |
+| `-webkit-text-stroke` | Outlines the letters; works across modern browsers despite the prefix |
+| `text-shadow` | Like `box-shadow` but follows the character shapes |
+
+If a text stroke draws lines inside the letters, that is the font: the stroke traces every contour and variable fonts usually keep overlapping shapes unmerged. Static fonts do not have this issue.
+
+## Sizes
+
+Typography must survive the reader changing it: zoom, a larger browser font size, overridden line height or letter spacing.
+
+| Text | Size |
+| --- | --- |
+| Long-form body starting point | Around `16px`, verified in the actual typeface and measure |
+| Inputs and menus starting point | Around `14px` |
+| Captions | `13px` |
+| Floor | Rarely below `12px` |
+
+When text appears low-contrast, use `better-colors` to measure the rendered foreground/background pair and `better-accessibility` to classify the applicable requirement. Changing the project's colors remains a design decision unless the user asks for remediation.
+
+## Font smoothing
+
+On macOS text renders heavier than intended. Apply font smoothing once on the root layout so it covers all text. Tailwind's `antialiased` sets both properties:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+```tsx
+<html lang="en">
+  <body class="font-sans antialiased">
+    <main>{children}</main>
+  </body>
+</html>
+```
diff --git a/.agents/skills/better-typography/spacing-and-sizing.md b/.agents/skills/better-typography/spacing-and-sizing.md
new file mode 100644
index 00000000..d270ddfb
--- /dev/null
+++ b/.agents/skills/better-typography/spacing-and-sizing.md
@@ -0,0 +1,126 @@
+# Spacing and sizing
+
+A sensible scale and comfortable spacing do more for typography than any effect.
+
+## Units
+
+| Unit | Behavior |
+| --- | --- |
+| `px` | Fixed |
+| `em` | Scales with the current font size |
+| `rem` | Scales with the root font size |
+| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
+
+## Type scale
+
+A small set of predefined sizes used across a product, deviated from as little as possible. Hard-coding sizes without a system breaks down at scale.
+
+```css
+:root {
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+}
+```
+
+There are many existing scales to pick from, or define a custom one. The Tailwind type scale (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
+
+For solo projects the default names work fine as long as there are clear rules for where each size is used. On a team, give sizes semantic names: `text-sm` tells you the size but not the use; `text-body-sm` keeps sizes consistent with clear usage rules.
+
+A role-based scale pairs each size with its line-height and weight, so a role is one decision instead of three. A solid starting point for a product interface:
+
+| Role | Size | Line-height | Weight |
+| --- | --- | --- | --- |
+| Display | `2.25rem` (36px) | `1.1` | `600` |
+| Title | `1.5rem` (24px) | `1.2` | `600` |
+| Heading | `1.125rem` (18px) | `1.3` | `600` |
+| Body | `1rem` (16px) | `1.5` | `400` |
+| Caption | `0.8125rem` (13px) | `1.4` | `400` |
+
+Emphasis within a role is one weight step up (`400` → `500`), not a size change.
+
+## Heading hierarchy
+
+Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
+
+```css
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+h3 { font-size: var(--text-lg); }
+```
+
+In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), typically centralized in a component or `@layer base` rather than repeated inline.
+
+When reviewing a page, compare the computed size of headings within each semantic section: a child that accidentally renders more prominently than its parent breaks the visual hierarchy. Deep levels may share a size when the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading should not be smaller than body text unless it is deliberately a label-style overline.
+
+Heading semantics and outline quality belong to `better-accessibility`. Pick the element from the document structure, then use this skill to make that structure visually legible; never pick a heading element for its browser-default size.
+
+## Kerning and letter-spacing
+
+- **Kerning** adjusts specific pairs like `AV` or `Ye`. It is built into the font and browsers apply it automatically. Only switch it off deliberately with `font-kerning: none`.
+- **`letter-spacing`** adds the same space between every character:
+  - Large headings often look better slightly negative.
+  - Small uppercase labels need a little positive spacing so letters do not feel crowded.
+  - Body copy needs neither.
+
+```css
+/* Good */
+.display-heading {
+  letter-spacing: -0.02em;
+}
+
+.uppercase-label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Line-height
+
+| Text | Value |
+| --- | --- |
+| Headings | ~`1.1` |
+| Body copy | `1.5`–`1.6` |
+
+Prefer unitless values: they scale with the font size, fixed values like `line-height: 24px` do not. Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding.
+
+Tight line-height is for short text. Anything that wraps to three or more lines needs at least `1.4`, even in height-constrained places like list rows and cards: a tightly-leaded paragraph is harder to read than a taller row is to fit.
+
+```css
+/* Bad: card description at heading leading */
+.card-description { line-height: 1.1; }
+
+/* Good: it wraps to 3 lines, so it reads as body text */
+.card-description { line-height: 1.4; }
+```
+
+## Text trimming with text-box
+
+Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
+
+| Keyword | Trims at |
+| --- | --- |
+| `cap` | The cap height (top) |
+| `alphabetic` | The baseline (bottom) |
+| `text` | The font's own text edge, keeping room for descenders |
+
+```css
+/* trim top and bottom */
+.badge {
+  text-box: trim-both cap alphabetic;
+}
+
+/* trim only the top */
+.heading {
+  text-box: trim-start cap;
+}
+
+/* trim only the bottom */
+.label {
+  text-box: trim-end alphabetic;
+}
+```
+
+Supported in Chromium (133+) and Safari (18.2+), not yet Firefox; treat it as progressive enhancement, where unsupported browsers keep the default leading.
diff --git a/.agents/skills/better-typography/variable-fonts-and-opentype.md b/.agents/skills/better-typography/variable-fonts-and-opentype.md
new file mode 100644
index 00000000..86d33c34
--- /dev/null
+++ b/.agents/skills/better-typography/variable-fonts-and-opentype.md
@@ -0,0 +1,105 @@
+# Variable fonts and OpenType
+
+What a font file can do beyond drawing letters, and how to reach those abilities from CSS.
+
+## Static vs variable
+
+- **Static font:** one weight and one style per file. Regular + medium + bold = three files.
+- **Variable font:** an entire range in one file. Any value in the range works, e.g. `font-weight: 589`.
+
+A variable font is not automatically better. One or two weights: static files can be smaller. Several weights, optical sizes or custom axes: a variable font usually makes more sense.
+
+## Load intended weights and styles
+
+When you use a weight or style the active family does not provide, the browser may synthesize it. Prefer loading the faces the design actually uses. Disable synthesis only after verifying the complete fallback stack and every semantic emphasis state; `none` disables weight, style, small-cap, superscript, and subscript synthesis together and can erase distinctions when the real face is unavailable.
+
+```css
+.brand-wordmark {
+  /* Safe only after this isolated treatment is verified */
+  font-synthesis: none;
+}
+```
+
+For body and interface text, keep synthesis enabled unless a verified font setup supplies every requested form. If only one mode is unwanted, use the specific longhand (`font-synthesis-weight`, `font-synthesis-style`, and related properties) instead of the blanket shorthand.
+
+## Axes
+
+Variable-font controls, each with a four-letter tag. A font only supports the axes its designer included.
+
+| Axis | Tag | Controls |
+| --- | --- | --- |
+| Weight | `wght` | Stroke thickness (like `font-weight`) |
+| Optical size | `opsz` | Details and spacing tuned for the display size |
+| Width | `wdth` | Glyph width |
+| Slant | `slnt` | Slant angle |
+| Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
+
+Inter's variable file exposes only `wght` and `opsz`.
+
+Optical sizes predate variable fonts and many fonts still ship them as separate files: Heldane Text is sturdier and more spaced for reading sizes, Heldane Display has finer details for large sizes.
+
+## Properties over axis tags
+
+When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders; `font-variation-settings` silently does nothing. Save the raw tags for custom axes with no property of their own:
+
+```css
+/* Good: common axes use the properties */
+.heading {
+  font-weight: 650;
+  font-optical-sizing: auto;
+}
+
+/* Good: custom axis with no property of its own */
+.heading-grade {
+  font-variation-settings: "GRAD" 80;
+}
+
+/* Bad: weight via raw tag breaks on fallback fonts */
+.heading {
+  font-variation-settings: "wght" 650;
+}
+```
+
+## OpenType features
+
+OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, they work the same on static and variable fonts. A font only ships the features its designer included.
+
+| Tag | Feature |
+| --- | --- |
+| `tnum` | Tabular numbers: every digit the same width |
+| `zero` | Slashed zero: `0` distinct from `O` |
+| `liga` | Ligatures: joins pairs like "fi" into one shape |
+| `ss01`–`ss20` | Stylistic sets (numbered slots) |
+| `cv01`–`cv99` | Character variants (numbered slots) |
+
+Same rule as axes: prefer the `font-variant-*` properties, reserve `font-feature-settings` for tags with no property:
+
+```css
+/* Good: common features use the properties */
+.price {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Good: slashed zero via the property too */
+.id {
+  font-variant-numeric: slashed-zero;
+}
+
+/* Good: niche feature with no property of its own */
+.logo {
+  font-feature-settings: "ss01" 1;
+}
+```
+
+Tabular numbers matter for changing values: without them each digit has a different width and the layout shifts as values update.
+
+## Small caps, superscripts, subscripts
+
+- **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
+- **Superscripts** sit above the normal line (the 2 in x²), **subscripts** below it (H₂O). Enable proper glyphs with `font-variant-position`.
+
+Both require the font to include the glyphs.
+
+## Stylistic sets and character variants
+
+`ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.
diff --git a/.agents/skills/better-typography/wrapping-and-punctuation.md b/.agents/skills/better-typography/wrapping-and-punctuation.md
new file mode 100644
index 00000000..62f634c8
--- /dev/null
+++ b/.agents/skills/better-typography/wrapping-and-punctuation.md
@@ -0,0 +1,58 @@
+# Wrapping and punctuation
+
+Where lines start, where they end, where they break and which characters they use.
+
+## Measure (line length)
+
+Long lines make it harder for the eye to find the start of the next line. For long-form text, aim for 60–75 characters per line.
+
+Any unit works. `65ch` measures characters directly (one `ch` is the width of the `0` in the current font), but a pixel or rem cap is just as good: at a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) or `max-w-2xl` (`672px`) fit. What matters is that a cap exists and the resulting line length sits in range; recheck it if the body font size changes.
+
+## Alignment
+
+`text-align` controls where each line starts and ends. `text-align: justify` stretches spaces until both edges line up; it can work in specific editorial layouts but avoid it in most interfaces.
+
+## Wrapping
+
+| Property | Use |
+| --- | --- |
+| `text-wrap: balance` | Distributes text evenly across multiple lines |
+| `text-wrap: pretty` | Avoids leaving a single short word on the final line |
+| `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
+| `white-space: nowrap` | Keeps labels and badges on one line where a break looks broken |
+
+Use `balance` on headings and `pretty` on descriptions; combined they give the best outcome. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
+
+## Truncation
+
+- Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
+- Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
+
+Truncation hides content. If the missing text matters, make the full value available elsewhere (tooltip or expanded view).
+
+## Case
+
+`text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so changing presentation never requires rewriting copy.
+
+## Smart punctuation
+
+Keyboard characters are not always the best characters:
+
+| Instead of | Use |
+| --- | --- |
+| Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
+| Hyphen in ranges | En dash: `2010–2020` |
+| Two hyphens for an aside | Em dash character |
+| Three periods `...` | The single ellipsis character `…` |
+| Regular space in `16 px` | `&nbsp;` so the value never breaks apart |
+| Uncontrolled word breaks | `&shy;` to mark where a word may break |
+
+## Internationalization
+
+- Set the `lang` attribute so browsers choose the right quotes, hyphenation and pronunciation.
+- Set `dir` at the document or content boundary where direction changes. Spatial mirroring and the logical-property table live in `better-layout`.
+
+Two refinements for mixed-direction text:
+
+- **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction, but a paragraph of three or more lines aligns to its own script's direction: an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang`/`dir` on the paragraph element handles this.
+- **Never reverse digits.** Numbers keep their digit order in every direction: a phone number or "541" reads identically in RTL. Browsers handle this via the Unicode bidi algorithm; don't fight it with manual reordering, and wrap mixed number/text values in `<bdi>` if adjacent RTL text disturbs them.
diff --git a/.agents/skills/better-ui/SKILL.md b/.agents/skills/better-ui/SKILL.md
new file mode 100644
index 00000000..fe49ed4d
--- /dev/null
+++ b/.agents/skills/better-ui/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: better-ui
+description: Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.
+---
+
+# Details that make interfaces feel better
+
+Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code.
+
+When reviewing, slow the interface down: replay motion at 10% speed in the browser's Animations panel and walk every state: hover, focus, active, loading, empty. What feels off at 10% speed is what's subtly wrong at full speed.
+
+Preserve the project's component library, tokens, and density. Match its established motion language except where a principle below prescribes an exact interaction pattern.
+
+Typography (text wrapping, font rendering, tabular numbers, spacing) is covered by the `better-typography` skill; use that for anything text-related. Accessibility (hit areas, focus states, keyboard support, ARIA, reduced motion) is covered by the `better-accessibility` skill. Layout structure (grouping, spacing between sections, breakpoints, spatial RTL) is covered by the `better-layout` skill.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Surfaces](surfaces.md) | Border radius, optical alignment, shadows, image outlines |
+| [Animations](animations.md) | Interruptible animations, enter/exit transitions, icon animations, scale on press, motion restraint |
+| [Icons](icons.md) | Icon stroke weight, states via `currentColor`, outline vs fill, sizing, RTL flipping |
+| [Performance](performance.md) | Transition specificity, `will-change` usage |
+
+## Core Principles
+
+### 1. Concentric Border Radius
+
+Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off.
+
+### 2. Optical Over Geometric Alignment
+
+When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment.
+
+### 3. Shadows for Elevation, Borders for Structure
+
+For buttons, cards, and containers whose border exists only to create depth, prefer layered transparent `box-shadow` values. Keep borders that communicate structure or state: dividers, layout separators, and selected or focus states.
+
+### 4. Interruptible Animations
+
+Use CSS transitions for interactive state changes: they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.
+
+### 5. Split and Stagger Enter Animations
+
+For an infrequent staged entrance where sequence helps communicate hierarchy, break content into semantic chunks and stagger them by ~100ms instead of animating one container. Do not stagger routine, high-frequency interactions.
+
+### 6. Subtle Exit Animations
+
+Use a small fixed `translateY` instead of full height. Exits should be softer than enters. Use `ease-out` for both enter and exit transitions.
+
+### 7. Contextual Icon Animations
+
+Animate icons with `opacity`, `scale`, and `blur` instead of toggling visibility. Use exactly these values: scale from `0.25` to `1`, opacity from `0` to `1`, blur from `4px` to `0px`. If the project has `motion` or `framer-motion` in `package.json`, match that package's import path (or the established nearby imports when both exist) and use `transition: { type: "spring", duration: 0.3, bounce: 0 }`; bounce must always be `0`. If no motion library is installed, keep both icons in the DOM (one absolute-positioned) and cross-fade with CSS transitions using `cubic-bezier(0.2, 0, 0, 1)`; this gives both enter and exit animations without any dependency.
+
+### 8. Image Outlines
+
+Add a subtle `1px` outline with low opacity to images for consistent depth. The color must be pure black in light mode (`oklch(0 0 0 / 0.1)`) and pure white in dark mode (`oklch(1 0 0 / 0.1)`), never a near-black like slate, zinc, or any tinted neutral. A tinted outline picks up the surface color underneath it and reads as dirt on the image edge.
+
+### 9. Scale on Press
+
+A subtle `scale(0.96)` on click gives buttons tactile feedback. Always use `0.96`. Never use a value smaller than `0.95`: anything below feels exaggerated. Add a `static` prop to disable it when motion would be distracting.
+
+### 10. Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations.
+
+### 11. Never Use `transition: all`
+
+Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.
+
+### 12. Use `will-change` Sparingly
+
+Only for `transform`, `opacity`, `filter`, the properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter.
+
+### 13. Match Icon Stroke to Text Weight
+
+An icon next to text carries the text's optical weight: `1.5px` stroke beside regular (400) text, `2px` beside semibold (600). One stroke weight per icon set; never mix libraries on one surface.
+
+### 14. One SVG, Recolored per State
+
+Icons use `currentColor` and get their states (hover, selected, disabled) from CSS color and opacity, never from separate assets. Outline variant is the default; fill variant marks the active state.
+
+### 15. Motion Restraint
+
+No custom animation on high-frequency interactions: the attention cost repeats on every trigger. Motion is never the only feedback channel; every animated state change also needs a static cue (color, icon, label).
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Same border radius on closely nested parent and child | Calculate `outerRadius = innerRadius + padding` |
+| Icons look off-center | Adjust optically with padding or fix SVG directly |
+| Border used only to fake elevation | Use layered `box-shadow` with transparency; keep structural and state borders |
+| Jarring staged entrance or contextual exit | Stagger infrequent entrances and keep context-preserving exits subtle |
+| Stateful icon or toggle animates its default state on page load | Add `initial={false}` to that `AnimatePresence`; preserve intentional page entrances |
+| `transition: all` on elements | Specify exact properties |
+| First-frame animation stutter | Add `will-change: transform` (sparingly) |
+| Hairline icon beside bold text | Match the stroke width to the text weight |
+| Separate icon assets per state | One `currentColor` SVG, states via CSS |
+| Filled icons everywhere | Outline as default, fill only for the active state |
+| Entrance animation on every hover or keystroke | Instant feedback or ≤150ms opacity/color transition |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone UI-polish review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes an interaction misleading, unresponsive, or repeatedly disruptive; `MEDIUM` creates a noticeable craft or consistency problem; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current implementation and an actionable replacement.
+- **Why**: name the violated principle and explain how it affects the interface.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Concentric border radius
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Card.tsx:28` | `rounded-xl` on card + `rounded-xl` on inner button (`p-2`) | `rounded-2xl` on card (`8 + 8 = 16`), `rounded-lg` on inner button | Nested corners should be concentric |
+| LOW | `src/card.css:11` | `border-radius: 16px` on both nested surfaces | Outer `24px`, inner `16px` with `8px` padding | Equal nested radii make the inner surface look pinched |
+
+#### Scale on press
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Button.tsx:19` | `<button className="...">` | Add `active:scale-[0.96] transition-transform` | Press feedback makes the control feel responsive |
+| MEDIUM | `src/button.css:24` | `scale(0.9)` on press | Raise to `scale(0.96)` | Anything below `0.95` feels exaggerated |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results. Walk every relevant state and inspect motion at 10% speed when animation is involved. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable UI-polish findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-ui/agents/openai.yaml b/.agents/skills/better-ui/agents/openai.yaml
new file mode 100644
index 00000000..59812d3c
--- /dev/null
+++ b/.agents/skills/better-ui/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better UI"
+  short_description: "Design engineering details for polished interfaces"
diff --git a/.agents/skills/better-ui/animations.md b/.agents/skills/better-ui/animations.md
new file mode 100644
index 00000000..59bb9a1b
--- /dev/null
+++ b/.agents/skills/better-ui/animations.md
@@ -0,0 +1,404 @@
+# Animations
+
+Interruptible animations, enter/exit transitions, contextual icon animations, and motion restraint.
+
+## Interruptible Animations
+
+Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
+
+### CSS Transitions vs. Keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes, retargets mid-animation | No, restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Fixed; retargets the value mid-flight, not the timeline | Fixed timeline, restarts from the beginning |
+
+```css
+/* Good: interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses, no jank */
+```
+
+```css
+/* Bad: keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts, feels broken */
+```
+
+**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Enter Animations: Split and Stagger
+
+Use this pattern for infrequent staged entrances where sequence helps communicate hierarchy, such as the first load of a page hero, success state, or empty state. Break a large container into semantic chunks and animate each individually. Do not stagger routine interactions such as row hovers, keystrokes, or repeated tab changes.
+
+### Step by Step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
+
+### Code Example
+
+```tsx
+// Motion (Framer Motion): staggered enter
+function PageHeader() {
+  return (
+    <motion.div
+      initial="hidden"
+      animate="visible"
+      variants={{
+        visible: { transition: { staggerChildren: 0.1 } },
+      }}
+    >
+      <motion.h1
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        Welcome
+      </motion.h1>
+
+      <motion.p
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        A description of the page.
+      </motion.p>
+
+      <motion.div
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        <Button>Get started</Button>
+      </motion.div>
+    </motion.div>
+  );
+}
+```
+
+### CSS-Only Stagger
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  filter: blur(4px);
+  animation: fadeInUp 400ms ease-out forwards;
+}
+
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 100ms; }
+.stagger-item:nth-child(3) { animation-delay: 200ms; }
+
+@keyframes fadeInUp {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+```
+
+## Exit Animations
+
+Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing; don't fight for attention.
+
+### Subtle Exit (Recommended)
+
+```tsx
+// Small fixed translateY: indicates direction without drama
+<motion.div
+  exit={{
+    opacity: 0,
+    y: -12,
+    filter: "blur(4px)",
+    transition: { duration: 0.15, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Full Exit (When Context Matters)
+
+```tsx
+// Slide fully out: use when spatial context is important
+// (e.g., a card returning to a list, a drawer closing)
+<motion.div
+  exit={{
+    opacity: 0,
+    x: "-100%",
+    transition: { duration: 0.2, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Good vs. Bad
+
+```css
+/* Good: subtle exit */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-12px);
+  transition: opacity 150ms ease-out, transform 150ms ease-out;
+}
+
+/* Bad: dramatic exit that steals focus */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-100%) scale(0.5);
+  transition: all 400ms ease-out;
+}
+
+/* Sometimes correct: remove immediately when motion adds no context */
+.item-exit {
+  display: none;
+}
+```
+
+**Key points:**
+- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
+- Keep some directional movement to indicate where the element went
+- Exit duration should be shorter than enter duration (150ms vs 300ms)
+- Use a subtle exit when it preserves spatial context. Remove immediately when motion adds no information, the interaction repeats frequently, or reduced motion is requested.
+
+## Contextual Icon Animations
+
+When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
+
+### Motion Example
+
+This example uses the `motion` package. If the project instead has `framer-motion`, import the same APIs from `"framer-motion"`; never mix an installed package with the other package's import path.
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS Transition Approach (No Motion)
+
+If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
+
+The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them: the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
+
+### Choosing Between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
+| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+
+**Rule:** Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or from `"framer-motion"` when `framer-motion` is installed. If both exist, follow the imports already used by the component or its nearest peers. If neither is present, use the CSS cross-fade pattern; don't add a dependency just for icon transitions.
+
+### When to Animate Icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+**Important:** Always use exactly these values for contextual icon animations; do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value
+
+## Scale on Press
+
+A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95`: anything below feels exaggerated. Use CSS transitions for interruptibility, so that if the user releases mid-press, it smoothly returns.
+
+Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
+
+### CSS Example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion Example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static Prop Pattern
+
+Extract the scale class into a variable and conditionally apply it based on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load, only on subsequent state changes.
+
+### When It Works
+
+```tsx
+// Good: icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for: icon swaps, toggles, tabs, segmented controls: anything that has a default state on page load.
+
+### When It Breaks
+
+Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
+
+```tsx
+// Bad: initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.
+
+## Motion Restraint
+
+Motion is a budget, not a garnish. Three rules decide whether an animation belongs at all:
+
+- **No custom animation on high-frequency interactions.** An animation on something users trigger constantly (every keystroke, every list-row hover, every tab switch in a work tool) charges its attention cost on every single trigger. Reserve expressive motion for infrequent moments (first load of a view, success states, empty states); high-frequency interactions get instant feedback or the subtlest possible transition (`opacity`/`background-color` at ≤150ms).
+- **Motion is never the only feedback channel.** Every state change an animation communicates must also be visible when the animation doesn't run: a color change, an icon swap, a label. Users with reduced motion enabled, and anyone who blinked, still need to see what happened.
+- **Brief and precise beats prominent.** If a shorter, smaller animation communicates the same thing, use it. When in doubt, cut the duration, not the clarity.
+
+```css
+/* Good: high-frequency hover gets a minimal transition */
+.row:hover {
+  background-color: var(--surface-hover);
+  transition: background-color 100ms ease-out;
+}
+
+/* Bad: every hover replays a full entrance */
+.row:hover .row-icon {
+  animation: bounceIn 500ms;
+}
+```
+
+Honoring `prefers-reduced-motion` is covered by the `better-accessibility` skill; apply it to every animation in this file.
diff --git a/.agents/skills/better-ui/icons.md b/.agents/skills/better-ui/icons.md
new file mode 100644
index 00000000..2c50e30b
--- /dev/null
+++ b/.agents/skills/better-ui/icons.md
@@ -0,0 +1,110 @@
+# Icons
+
+Icon weight, states, sizing, and direction: the details that make icons sit naturally in an interface.
+
+## Match Icon Stroke to Text Weight
+
+An icon next to text should carry the same optical weight as the text, or the pair looks mismatched: a hairline icon beside semibold text reads as broken, a heavy icon beside regular text shouts.
+
+| Adjacent text | Icon stroke width (24px grid) |
+| --- | --- |
+| Regular (400), 14–16px | `1.5px` |
+| Medium/Semibold (500–600) | `2px` |
+| Bold (700), or emphasized standalone | `2.5px` |
+
+```html
+<!-- Good: stroke tuned to the label weight -->
+<button class="flex items-center gap-2 font-semibold">
+  <PlusIcon stroke-width="2" class="size-4" />
+  New project
+</button>
+
+<!-- Bad: default 1.5px stroke against a bold label -->
+<button class="flex items-center gap-2 font-bold">
+  <PlusIcon stroke-width="1.5" class="size-4" />
+  New project
+</button>
+```
+
+Two related consistency rules:
+
+- **One optical strategy per surface.** Do not mix icon libraries with incompatible stroke conventions on one toolbar. If the chosen library intentionally supports stroke variants, match them to adjacent text as above; otherwise preserve the set's native stroke and use size or color for emphasis.
+- **Size icons relative to the text's cap height**, typically `1em`–`1.25em` when inline with text, so the pair scales together.
+
+## One SVG, Recolored per State
+
+Never ship separate icon assets for default/hover/selected/disabled states. Use a single SVG drawn with `currentColor` and let CSS state drive the color:
+
+```html
+<!-- Good: one asset, states are CSS -->
+<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
+```
+
+```css
+.icon-button { color: oklch(0.552 0.016 285.938); }
+.icon-button:hover { color: oklch(0.21 0.006 285.885); }
+.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
+.icon-button:disabled { opacity: 0.4; }
+```
+
+```html
+<!-- Tailwind -->
+<button class="text-zinc-500 hover:text-zinc-900 aria-pressed:text-blue-600 disabled:opacity-40">
+  <BookmarkIcon />
+</button>
+```
+
+Hardcoded fills inside the SVG (`fill="#666"`) break this; strip them to `currentColor` when importing icons.
+
+## Outline Default, Fill Active
+
+When an icon set offers outline and filled variants, use them as a state pair, not interchangeably:
+
+| Variant | Use for |
+| --- | --- |
+| Outline | Default state: toolbars, list rows, inline with text |
+| Fill | Selected/active state: the active tab, a toggled bookmark, a liked heart |
+
+```tsx
+// Good: variant communicates state
+<TabIcon variant={isActive ? "solid" : "outline"} />
+
+// Bad: filled icons everywhere, so the active tab has no state signal
+<TabIcon variant="solid" />
+```
+
+The swap between variants is a contextual icon animation; use the exact cross-fade values in [animations.md](animations.md).
+
+## Design at Render Size
+
+An icon that looks great at 48px can collapse into mush at 16px. Details that read at large sizes (thin interior lines, tight counters, fine texture) blur or alias when small.
+
+- Test every icon at the smallest size it will render (often `16px`); it must stay recognizable there.
+- Prefer simplified glyphs for small contexts over scaling down detailed artwork.
+- Keep icons on the pixel grid at their render size: a 16px icon drawn on a 24px grid with fractional scaling renders soft. Use the icon set's native grid sizes (`16`, `20`, `24`) rather than arbitrary scales.
+- Always SVG, never raster, so the same asset stays crisp at every density.
+
+## Icons in RTL
+
+Under `dir="rtl"`, flip icons whose meaning is tied to reading direction, and leave the rest alone:
+
+| Flip | Don't flip |
+| --- | --- |
+| Back/forward arrows, chevrons in navigation | Logos and brand marks |
+| Text-block glyphs (alignment, lists, indent) | Checkmarks |
+| Speaker/volume waves (emanate in reading direction) | Physical objects: clocks, cups, pencils |
+| "Send" style directional glyphs | Media playback (play/rewind refer to tape direction, convention keeps them LTR) |
+
+```css
+/* Good: mirror only direction-dependent icons */
+[dir="rtl"] .icon-directional {
+  scale: -1 1;
+}
+```
+
+```html
+<!-- Tailwind -->
+<ChevronRightIcon class="icon-directional rtl:-scale-x-100" />
+```
+
+Analyze composite icons part by part: a badge or slash overlay may keep its position even when the base glyph flips. Accessible names for icon-only buttons are covered by the `better-accessibility` skill.
diff --git a/.agents/skills/better-ui/performance.md b/.agents/skills/better-ui/performance.md
new file mode 100644
index 00000000..3c397616
--- /dev/null
+++ b/.agents/skills/better-ui/performance.md
@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition Only What Changes
+
+Never use `transition: all` or Tailwind's `transition-all`. Always specify the exact properties that change. (Tailwind's bare `transition` maps to a curated default list of colors, opacity, shadow and transforms, not to `all`; still prefer naming exactly what changes.)
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS Example
+
+```css
+/* Good: only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad: transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good: explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad: transition all
+<button className="transition-all duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` Note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate`, so it covers all transform-related properties, not just `transform`. Use this when you're only animating transforms. For multiple non-transform properties, use the bracket syntax: `transition-[scale,opacity,filter]`.
+
+## Use `will-change` Sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it, the browser promotes the element only when the animation starts; that one-time layer promotion can cause a micro-stutter on the first frame.
+
+This particularly helps when an element is changing `scale`, `rotation`, or moving around with `transform`. For other properties, it doesn't help much: the browser can't composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good: specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good: multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad: never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad: properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful Properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Newer Chromium only | Rarely; not reliable cross-browser |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to Skip
+
+Modern browsers are already good at optimizing on their own. Only add `will-change` when you notice first-frame stutter; Safari in particular benefits from it. Don't add it preemptively to every animated element; each extra compositing layer costs memory.
diff --git a/.agents/skills/better-ui/surfaces.md b/.agents/skills/better-ui/surfaces.md
new file mode 100644
index 00000000..04762eb0
--- /dev/null
+++ b/.agents/skills/better-ui/surfaces.md
@@ -0,0 +1,219 @@
+# Surfaces
+
+Border radius, optical alignment, shadows, and image outlines.
+
+## Concentric Border Radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
+
+### Example
+
+```css
+/* Good: concentric radii */
+.card {
+  border-radius: 20px; /* 12 + 8 */
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+
+/* Bad: same radius on both */
+.card {
+  border-radius: 12px;
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+// Good: outer radius accounts for padding
+<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
+  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad: same radius on both
+<div className="rounded-xl p-2">
+  <div className="rounded-xl">          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched border radii on closely nested surfaces is a common source of visual tension. Calculate concentrically when the layers share a visible, even inset; preserve an established component token when the layers are independent or the padding is intentionally asymmetric.
+
+## Optical Alignment
+
+When geometric centering looks off, align optically instead.
+
+### Buttons with Text + Icon
+
+When an icon makes otherwise symmetric padding look unbalanced, use slightly less padding on the icon side. A useful starting point is:
+`icon-side padding = text-side padding - 2px`.
+
+```css
+/* Good: less padding on icon side */
+.button-with-icon {
+  padding-inline-start: 16px;
+  padding-inline-end: 14px; /* trailing icon side = text side - 2px */
+}
+
+/* Bad: equal padding looks like icon is pushed too far right */
+.button-with-icon {
+  padding-inline: 16px;
+}
+```
+
+```tsx
+// Tailwind
+<button className="ps-4 pe-3.5 flex items-center gap-2">
+  <span>Continue</span>
+  <ArrowRightIcon />
+</button>
+```
+
+### Play Button Triangles
+
+Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
+
+```css
+/* Good: optically centered */
+.play-button svg {
+  transform: translateX(2px); /* physical correction to the glyph itself */
+}
+
+/* Bad: geometrically centered but looks off */
+.play-button svg {
+  /* no adjustment */
+}
+```
+
+### Asymmetric Icons (Stars, Arrows, Carets)
+
+Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
+
+```tsx
+// Best: fix in the SVG itself
+// Adjust the viewBox or path to visually center the icon
+
+// Fallback: adjust with margin
+<span className="translate-x-px">
+  <StarIcon />
+</span>
+```
+
+## Shadows Instead of Borders
+
+For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds: solid border colors don't work well on backgrounds other than the ones they were designed for.
+
+**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
+
+### Shadow as Border (Light Mode)
+
+The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0px 0px 0px 1px oklch(0 0 0 / 0.06),
+    0px 1px 2px -1px oklch(0 0 0 / 0.06),
+    0px 2px 4px 0px oklch(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0px 0px 0px 1px oklch(0 0 0 / 0.08),
+    0px 1px 2px -1px oklch(0 0 0 / 0.08),
+    0px 2px 4px 0px oklch(0 0 0 / 0.06);
+}
+```
+
+### Shadow as Border (Dark Mode)
+
+In dark mode, simplify to a single white ring, since layered depth shadows aren't visible on dark backgrounds:
+
+```css
+/* Dark mode: adapt to whatever setup the project uses
+   (prefers-color-scheme, class, data attribute, etc.) */
+--shadow-border: 0 0 0 1px oklch(1 0 0 / 0.08);
+--shadow-border-hover: 0 0 0 1px oklch(1 0 0 / 0.13);
+```
+
+### Usage with Hover Transition
+
+Apply the variable and add `transition-[box-shadow]` for a smooth hover:
+
+```css
+.card {
+  box-shadow: var(--shadow-border);
+  transition-property: box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-border-hover);
+}
+```
+
+### When to Use Shadows vs. Borders
+
+| Use shadows | Use borders |
+| --- | --- |
+| Cards, containers with depth | Dividers between list items |
+| Buttons with bordered styles | Table cell boundaries |
+| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
+| Elements on varied backgrounds | Hairline separators in dense UI |
+| Hover/focus states for lift effect | |
+
+## Image Outlines
+
+Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
+
+### Color rules (non-negotiable)
+
+- **Light mode**: pure black, `oklch(0 0 0 / 0.1)`.
+- **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`.
+- Never use a near-black or near-white from the project palette (e.g. slate-900, zinc-900, `#0a0a0a`, `#111827`, `#f5f5f7`). Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
+- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
+
+### Light Mode
+
+```css
+img {
+  outline: 1px solid oklch(0 0 0 / 0.1);
+  outline-offset: -1px; /* draw the ring just inside the image edge */
+}
+```
+
+### Dark Mode
+
+```css
+img {
+  outline: 1px solid oklch(1 0 0 / 0.1);
+  outline-offset: -1px;
+}
+```
+
+### Tailwind with Dark Mode
+
+```tsx
+<img
+  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+  src={src}
+  alt={alt}
+/>
+```
+
+Use `outline-black/10` and `outline-white/10` specifically, not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
+
+**Why outline instead of border?** `outline` never affects layout (no added width or height at any offset), and `outline-offset: -1px` draws the ring just inside the image edge so it hugs the corner radius instead of sitting outside it.
diff --git a/.agents/skills/better-writing/SKILL.md b/.agents/skills/better-writing/SKILL.md
new file mode 100644
index 00000000..eb8dea42
--- /dev/null
+++ b/.agents/skills/better-writing/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: better-writing
+description: >-
+  UX writing and interface copy, from voice and button labels to error messages and empty states. Use when writing or reviewing any user-facing text: button and link labels, form errors, placeholders, settings labels, onboarding flows, notifications, or empty states. Triggers on UX writing, microcopy, interface copy, product copy, copywriting, button labels, link text, error messages, empty states, placeholder text, settings labels, capitalization, title case, sentence case, voice and tone.
+---
+
+# Writing that disappears into the interface
+
+Clear and brief beats clever, consistency beats variety, and the best error message is the interaction redesigned so the error can't happen. Apply these principles when writing or reviewing any user-facing text.
+
+How copy renders (capitalization via `text-transform`, truncation, smart punctuation) is covered by the `better-typography` skill; error markup and announcements (`aria-invalid`, live regions) by the `better-accessibility` skill; room for translated strings by the `better-layout` skill.
+
+## Core Principles
+
+### 1. Recon the Existing Voice
+
+Before writing or reviewing, inspect nearby interface copy, the product's terminology, localization conventions, and any voice or content style guide. Preserve intentional brand character when it remains clear and appropriate to the stakes. Treat a difference from generic plain language as a finding only when it creates inconsistency, ambiguity, translation risk, or an inappropriate tone.
+
+### 2. One Voice, Flexible Tone
+
+The product has one voice, established by its existing system rather than invented during a local edit. Keep terms consistent: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
+
+| Context | Tone |
+| --- | --- |
+| Success, onboarding, empty states | Warm, can be light |
+| Routine actions, settings | Neutral, minimal |
+| Errors, destructive confirmations | Calm, plain, zero playfulness |
+| Data loss, security | Serious, explicit |
+
+### 3. Address the Reader Directly
+
+In instructional interface copy, address the reader directly as "you" rather than "the user." Avoid “we” in errors when it creates ambiguity or reads as deflection: prefer “Unable to load content” over “We're having trouble loading this content.” Preserve an established first-person brand voice in low-stakes contexts when it remains clear. Use possessives sparingly (“Favorites” over “Your Favorites”) and never switch perspective accidentally.
+
+### 4. Plain Words Over Clever Ones
+
+Choose easily understood words and delete every word that isn't needed. No idioms, colloquialisms, or humor that won't translate. Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible. Never build sentences by concatenating fragments around variables (`"You have " + n + " new messages"`); word order changes per language, so use full templated strings with proper pluralization.
+
+### 5. Verb-First Buttons
+
+Button labels start with a verb naming the specific action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or bare "Yes"/"No" on consequential actions. Confirmation buttons repeat the consequence so the dialog is answerable without reading the body: "Delete this project?" offers `Delete project` and `Cancel`, not `Yes` and `No`.
+
+### 6. Consistent Flow Vocabulary
+
+Multi-step flows use one vocabulary: "Get Started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms across steps makes users wonder if the buttons do different things.
+
+### 7. Links Describe Their Destination
+
+Link text makes sense out of context; screen-reader users navigate by a list of the page's links. "Read the billing docs", never "Click here" (which also fails the device-verb rule on touch), and never a bare "Learn more" when several appear on one page. Suffix each: "Learn more about exports".
+
+### 8. One Capitalization Policy
+
+Pick title case or sentence case per element type (all buttons, all headings) and apply it consistently; sentence case is the safer default: calmer, no per-word case rules, localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
+
+### 9. Settings Describe the ON State
+
+Label a toggle for what happens when it's on: "Send read receipts", and users infer the off state. Never label the negative ("Don't send read receipts"), which turns the toggle into a double negative. Link directly to a referenced setting instead of describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
+
+### 10. Errors Say How to Fix, Next to Where It Broke
+
+An error is an instruction, adjacent to the failing field:
+
+| Bad | Good |
+| --- | --- |
+| That password is too short | Choose a password with at least 8 characters |
+| Invalid name | Use only letters for your name |
+| Oops! Something went wrong. | Unable to save. Check your connection and try again. |
+
+No blame, no "oops", no exclamation marks. Phrase hints positively ("Use only letters", not "Don't use numbers or symbols") and show them before the mistake, not after. If the same error keeps firing for many users, redesign the interaction instead of rewording it.
+
+### 11. Empty States Point Forward
+
+An empty state says what this place is and how to fill it, with one clear next action:
+
+```html
+<!-- Bad: a shrug -->
+<p>No results.</p>
+
+<!-- Good: orientation plus a next step -->
+<p class="font-medium">No projects yet</p>
+<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
+<button class="mt-4">Create a project</button>
+```
+
+Search and filter empty states name the query and offer an exit: "No results for 'quarterly'. Clear filters". Never park crucial persistent information in an empty state; it disappears the moment content exists.
+
+### 12. Placeholders Are Examples, Not Labels
+
+Placeholders show the expected format (`name@example.com`, `DD/MM/YYYY`). A placeholder is never the field's only label: it vanishes on input, and every field keeps a visible label.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Local rewrite ignores the product's established terminology or voice | Inspect nearby copy and the style guide before proposing a change |
+| "The user" in instructional interface copy | Address the reader directly as "you" |
+| "We're having trouble…" obscures responsibility or recovery | Use a direct status and next step: "Unable to load content" |
+| `OK` / `Yes` confirming a destructive dialog | Repeat the consequence: "Delete project" |
+| "Continue" on step 2, "Next" on step 3 | One flow vocabulary throughout |
+| "Click here" or bare "Learn more" link | Describe the destination: "Read the billing docs" |
+| "Save Changes" beside "Discard changes" | One capitalization policy per element type |
+| "Don't send read receipts" toggle | Label the ON state: "Send read receipts" |
+| "Oops! Something went wrong." | Say what to do, next to the failing field |
+| "No results." as the whole empty state | Orient and point forward with a next action |
+| Placeholder doing the label's job | Visible label; placeholder shows the format |
+| `"You have " + n + " messages"` | Full templated strings with pluralization |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone writing review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` misleads users, obscures a consequence, or prevents recovery; `MEDIUM` makes a task harder to understand; `LOW` is isolated voice or consistency polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: quote the current copy and its complete replacement.
+- **Why**: name the violated principle and explain the comprehension or trust cost.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Errors say how to fix
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/PasswordField.tsx:36` | "Invalid password" | "Choose a password with at least 8 characters" | The error must say how to fix the problem |
+| HIGH | `src/Editor.tsx:81` | "We couldn't process your request" toast | Inline "Unable to save. Check your connection and try again." | The current message neither locates the failure nor offers recovery |
+
+#### Verb-first buttons
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/DeleteDialog.tsx:29` | "OK" on the delete confirmation | "Delete project" | A consequential action must repeat the consequence |
+| MEDIUM | `src/Signup.tsx:54` | "Let's go!" | "Create account" | The label must name the action |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including the complete flow, variable interpolation, pluralization, and narrow-width wrapping when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable writing findings", report verification, and end with `Approve`.
diff --git a/.agents/skills/better-writing/agents/openai.yaml b/.agents/skills/better-writing/agents/openai.yaml
new file mode 100644
index 00000000..89ab41ec
--- /dev/null
+++ b/.agents/skills/better-writing/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Writing"
+  short_description: "UX writing, interface copy and microcopy"
diff --git a/.claude/skills/ai-sdk/SKILL.md b/.claude/skills/ai-sdk/SKILL.md
new file mode 100644
index 00000000..19eb3ee3
--- /dev/null
+++ b/.claude/skills/ai-sdk/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: ai-sdk
+description: 'Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".'
+---
+
+## What the AI SDK Is
+
+The AI SDK by Vercel (the `ai` package on npm) is a TypeScript toolkit for building AI applications. It provides a unified API across model providers for text generation, structured output, tool calling, agents, embeddings, and framework UI integrations.
+
+- Repository: https://github.com/vercel/ai
+- Documentation: https://ai-sdk.dev/docs
+
+## Critical: Do Not Trust Your Own Memory
+
+Whatever you remember about the AI SDK is likely outdated. The SDK changes frequently across versions - APIs are renamed, removed, and added. Your training data almost certainly contains obsolete APIs, deprecated patterns, and model IDs that no longer exist. UI hooks like `useChat` are among the most frequently changed APIs, so be especially careful with client code.
+
+**Never write AI SDK code from memory.** Always verify every API, option, and pattern against the documentation and source code for the version that is actually installed in the project.
+
+## Use the Bundled, Version-Matched Docs
+
+The `ai` package ships its full documentation and source code inside `node_modules`. These always match the installed version, so trust them over anything you remember.
+
+1. Ensure `ai` is installed. If `node_modules/ai/` does not exist, install **only** the `ai` package using the project's package manager (e.g. `pnpm add ai`). Install provider packages (e.g. `@ai-sdk/openai`) and framework packages (e.g. `@ai-sdk/react`) later, when the task requires them.
+2. Read and grep the bundled docs at `node_modules/ai/docs/` and the source at `node_modules/ai/src/`.
+3. Provider and framework packages bundle their own docs at `node_modules/@ai-sdk/<name>/docs/`.
+4. If something isn't in the bundled docs, search https://ai-sdk.dev/docs. You can append `.md` to any docs page URL to get its markdown, and search via `https://ai-sdk.dev/api/search-docs?q=your_query`.
+5. If you cannot find support for an answer in the docs or source, say so explicitly — do not guess.
+
+## AI Gateway: The Fastest Way to Start
+
+The Vercel AI Gateway is the fastest way to get started with the AI SDK. It provides access to models from OpenAI, Anthropic, Google, and other providers through a single API, without installing provider packages or managing multiple API keys.
+
+To set it up:
+
+1. Authenticate with OIDC (for Vercel deployments) or get an AI Gateway API key.
+2. Provide it to your app via the `AI_GATEWAY_API_KEY` environment variable.
+3. Reference models with `provider/model` strings.
+
+For exact setup, authentication, and usage, read the bundled guide and the AI Gateway docs.
+
+### Choosing a Model
+
+Never use model IDs from memory — models are released and retired frequently. Fetch the current list before writing code that references a model. Do not truncate the list (e.g. with `head`) so you can find the newest models:
+
+```bash
+# All available models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '.data[].id'
+
+# Filter by provider (e.g. anthropic, openai, google)
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("anthropic/")) | .id] | reverse | .[]'
+```
+
+When multiple versions of a model exist, prefer the one with the highest version number.
+
+## Building and Consuming Agents
+
+Use the SDK's built-in agent abstraction (such as `ToolLoopAgent`) rather than hand-rolling tool-calling loops. For end-to-end type safety, infer the UI message type from your agent definition when consuming it on the client (e.g. with `useChat`). Consuming an agent is framework-specific: check `package.json` to detect the stack, then follow the matching quickstart.
+
+Look up the current agent, tool, and type-safety APIs in the bundled docs (`node_modules/ai/docs/`, especially the agents section) or at https://ai-sdk.dev/docs.
+
+## DevTools
+
+AI SDK DevTools captures your AI SDK calls - requests, responses, tool calls, token usage, and multi-step runs - so you can inspect exactly what your agents do. Use it while developing to debug generations. It is a separate package and is intended for local development only.
+
+For setup instructions, read the bundled DevTools documentation.
+
+## Keep the SDK Current
+
+Outdated installs are the most common source of errors. Compare the installed version against the latest:
+
+- **Installed:** the `version` field in `node_modules/ai/package.json`.
+- **Latest:** run `npm view ai version`.
+
+If the installed version is a major version (or more) behind the latest, tell the user they are on an old release, and recommend upgrading before continuing. Migration guides are at https://ai-sdk.dev/docs/migration-guides.
+
+## After Making Changes
+
+Run the project's type checker. Be minimal — only set options that differ from the defaults, checking docs or source for the defaults rather than over-specifying. Most type errors come from remembered, now-changed APIs; re-check the current docs and source when they occur.
diff --git a/.claude/skills/better-accessibility/SKILL.md b/.claude/skills/better-accessibility/SKILL.md
new file mode 100644
index 00000000..d2790fdf
--- /dev/null
+++ b/.claude/skills/better-accessibility/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: better-accessibility
+description: Accessibility engineering for product interfaces, from focus states and keyboard support to ARIA, forms, and screen readers. Use when building or reviewing UI components, modals, menus, forms, custom widgets, or when the user says "make this accessible" or reports keyboard or screen-reader issues. Triggers on accessibility, a11y, WCAG, aria, focus ring, focus-visible, focus trap, keyboard navigation, tab order, tabindex, screen reader, sr-only, aria-live, alt text, hit area, touch target, prefers-reduced-motion, autoplay, toast duration, skip link, semantic HTML, aria-label, form errors, disabled buttons, "not keyboard accessible".
+---
+
+# Accessibility that comes with the craft
+
+Accessibility is not a compliance checkbox bolted on at the end; it is the floor for interface craft. Most of it is free if you use the platform: native elements ship with keyboard support, real labels announce themselves, and a visible focus ring is one CSS rule. Apply these principles when building or reviewing UI code, and match the project's existing styling system (Tailwind vs. plain CSS vs. CSS-in-JS) when applying fixes.
+
+When reviewing, walk the interface as a keyboard-only user first (every flow must complete without a mouse), then as a screen-reader user: does each control announce a name, a role, and its state? When unsure, prefer the platform default over a custom rebuild, and remove ARIA rather than add it.
+
+Rendered-pair contrast measurement and color remediation are covered by the `better-colors` skill; visual text sizing and iOS input zoom by `better-typography`; spatial RTL layout by `better-layout`.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Focus & Keyboard](focus-and-keyboard.md) | Focus rings, skip links, tabindex, focus trapping, APG keyboard patterns |
+| [Semantics & ARIA](semantics-and-aria.md) | Native elements first, button vs link, landmarks, accessible names, disabled states |
+| [Forms](forms.md) | Labels, autocomplete, error messaging, input types |
+| [Screen Readers](screen-readers.md) | Visually hidden content, live regions, toasts, alt text, SVG |
+| [Hit Areas](hit-areas.md) | Target sizes, expanding hit areas, collision rules |
+| [Motion & Zoom](motion-and-zoom.md) | `prefers-reduced-motion`, autoplay and timed UI, 200% zoom, reflow, rem vs px |
+
+## Core Principles
+
+### 1. Native Elements First
+
+The first rule of ARIA: don't use ARIA when a native element exists. `<button>` for actions, `<a href>` for navigation (it must support Cmd/Ctrl/middle-click), never `<div onClick>`. No ARIA is better than bad ARIA.
+
+### 2. Visible Focus Rings
+
+Style `:focus-visible`, not bare `:focus`, so keyboard users get a ring and mouse users usually don't. Prefer the browser's unmodified focus indicator. If the design needs a custom ring, use a project focus token or another explicit color and verify the complete indicator against every adjacent color it crosses; `currentColor` is acceptable only after the same check. Use at least a `2px` solid perimeter or an equivalent visible area. Never use `outline: none` without a verified replacement, and preserve system colors in forced-colors mode.
+
+### 3. Full Keyboard Support
+
+Every pointer interaction needs a keyboard path, following the ARIA APG patterns: Escape closes overlays, arrow keys move within composite widgets (tabs, menus, listboxes), Tab moves between widgets, Enter and Space activate. Only `tabindex="0"` (join the natural tab order) and `tabindex="-1"` (programmatic focus), never positive values, which break the natural order. Composite widgets use roving tabindex: the active item is `0`, all others `-1`.
+
+### 4. Trap and Restore Focus
+
+Modals set `inert` on the background content, move focus inside on open, and return focus to the trigger on close. Add `overscroll-behavior: contain` so background content doesn't scroll.
+
+### 5. Minimum Hit Area
+
+WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target or one of its defined spacing, equivalent-control, inline, user-agent, or essential exceptions. For easier activation, aim for 44×44px in touch contexts and 40×40px in desktop interfaces when density permits. Extend with a pseudo-element if the visible element should stay smaller. Never let extended hit areas overlap.
+
+### 6. Label and Type Every Control
+
+Every input gets a `<label for>` or wrapping `<label>`; a placeholder is never a label, and label and control share one hit target: no dead zones between a checkbox and its text. Add `autocomplete` with a meaningful `name`, and the correct `type` and `inputmode` for the keyboard. Never block paste; users paste passwords and one-time codes.
+
+### 7. Errors That Announce
+
+Keep submit enabled until the request starts, then disable with a spinner while keeping the original label. Validate on submit: mark failing fields with `aria-invalid="true"`, point `aria-describedby` at the inline error text, and focus the first invalid field. Use native `disabled` when a native control is genuinely unavailable. Use `aria-disabled="true"` only when retaining focusability or discoverability is intentional; then block pointer, keyboard, and form behavior in code and style the state explicitly.
+
+### 8. Accessible Names Everywhere
+
+Icon-only buttons need a descriptive `aria-label`. Visible label text must appear in the accessible name. Decorative elements get `aria-hidden="true"`, never on a focusable element.
+
+### 9. Don't Rely on Color Alone
+
+Status needs a redundant cue: icon, text, or underline alongside the color. Determine which WCAG contrast requirement applies from the content and state, then use `better-colors` to measure the rendered foreground/background pair. When contrast fails, report the pair and requirement it misses; do not change the project's colors unless asked.
+
+### 10. Honor prefers-reduced-motion
+
+Wrap motion in `@media (prefers-reduced-motion: no-preference)` so it is opt-in. Under reduced motion, replace slides and scales with opacity crossfades; kill parallax and autoplay entirely. Independent of the preference: autoplaying media needs a visible pause control, and toasts carrying actions or errors stay until dismissed.
+
+### 11. Announce Dynamic Content
+
+Use `aria-describedby` for field-specific validation, a polite live region (`role="status"`) for non-urgent updates not tied to a control such as toasts or result counts, and `role="alert"` only for urgent errors not tied to a control. For reliable repeated polite announcements, render a stable empty region before updating its text; dynamically inserted alerts have different support and must be tested with the target screen readers.
+
+### 12. Alt Text by Purpose
+
+Decorative images get `alt=""`, informative images describe the meaning, functional images describe the action: a search icon button is `alt="Search"`, not `alt="magnifying glass"`.
+
+### 13. Structure Is Navigation
+
+Use headings that describe their sections and form a coherent outline; one page-level `<h1>` and properly nested levels are the recommended default, not standalone WCAG pass/fail rules. Expose one visible primary `<main>` landmark. When repeated navigation or chrome precedes it, make a "Skip to content" link the first focusable element. Anchored headings get `scroll-margin-top`.
+
+### 14. Survive Zoom and Text Resize
+
+The page must work at 200% zoom and reflow at 320px width without horizontal scrolling. Use `min-height` instead of fixed `height` on text containers, prefer `rem` breakpoints where they fit the codebase's conventions, and never use `user-scalable=no` or `maximum-scale=1`.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `outline: none` to remove the focus ring | Style `:focus-visible` instead; mouse clicks won't show it |
+| Custom focus color assumed to work everywhere | Verify the full indicator against every adjacent color and in forced-colors mode |
+| `<div onClick>` for a button or link | `<button>` for actions, `<a href>` for navigation |
+| Placeholder used as the only label | Add a visible `<label for>`; placeholders disappear on input |
+| Positive `tabindex` to fix focus order | Fix the DOM order; only use `0` and `-1` |
+| Repeated polite update inconsistently announced | Keep a stable empty status region and update its text; test the target screen readers |
+| `assertive` live region for a routine toast | Use `polite`; reserve `assertive` for errors |
+| `aria-hidden="true"` on a focusable element | Remove it or make the element non-focusable |
+| Functional icon alt describes the picture | Describe the action: `alt="Search"`, not `alt="magnifying glass"` |
+| `maximum-scale=1` to stop iOS input zoom | 16px input font on mobile (see `better-typography`); never block zoom |
+| Submit disabled until the form is valid | Keep it enabled; validate on submit and focus the first error |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone accessibility review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` prevents a task, hides content from assistive technology, or creates a systemic accessibility failure; `MEDIUM` makes an interaction meaningfully harder; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current implementation and an actionable replacement.
+- **Why**: name the violated principle and its user impact.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Accessible names everywhere
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/Dialog.tsx:42` | `<button><XIcon /></button>` | Add `aria-label="Close"`; mark the icon `aria-hidden="true"` | The icon-only control has no accessible name |
+| HIGH | `src/Nav.tsx:18` | `<a href="/settings"><GearIcon /></a>` | Add `aria-label="Settings"` | The link destination is unavailable to screen readers |
+
+#### Visible focus rings
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/button.css:12` | `button:focus { outline: none; }` | `button:focus-visible { outline: 2px solid; outline-offset: 2px; }` | Keyboard users cannot see focus |
+| HIGH | `src/Menu.tsx:31` | `focus:outline-none` | `focus-visible:outline-2 focus-visible:outline-offset-2` | Menu navigation has no visible focus indicator |
+
+#### Errors that announce
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/EmailField.tsx:27` | Error shown only as `border-red-500` | Add `aria-invalid="true"` + `aria-describedby="email-error"` with inline error text | Color alone neither explains nor announces the error |
+| MEDIUM | `src/SignupForm.tsx:64` | Submit disabled until the form is valid | Keep submit enabled; on failure, focus the first invalid field | A disabled action hides what must be fixed |
+
+#### Minimum hit area
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Toolbar.tsx:22` | `size-4` icon-only button | Extend the hit area to 44×44px with `after:absolute after:size-11` | The target is too small for reliable touch input |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including keyboard traversal, accessible-name inspection, and screen-reader or automated checks when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable accessibility findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-accessibility/agents/openai.yaml b/.claude/skills/better-accessibility/agents/openai.yaml
new file mode 100644
index 00000000..4f20e8a5
--- /dev/null
+++ b/.claude/skills/better-accessibility/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Accessibility"
+  short_description: "Focus, keyboard, ARIA, forms and screen readers"
diff --git a/.claude/skills/better-accessibility/focus-and-keyboard.md b/.claude/skills/better-accessibility/focus-and-keyboard.md
new file mode 100644
index 00000000..6a2cc6da
--- /dev/null
+++ b/.claude/skills/better-accessibility/focus-and-keyboard.md
@@ -0,0 +1,131 @@
+# Focus and Keyboard
+
+Focus rings, skip links, tabindex, focus trapping, and the APG keyboard patterns.
+
+## Focus rings
+
+Style `:focus-visible`, not bare `:focus`. The browser shows `:focus-visible` for keyboard and assistive-tech focus but suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement; that removes keyboard navigation for sighted keyboard users.
+
+Prefer the browser's unmodified focus indicator: it adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` generally preserves that indicator. A custom `outline: 2px solid` with no color renders `currentColor`; that is not automatically accessible because the outline may cross colors different from the text's own background. So the preference order is:
+
+```css
+/* Best: keep the browser ring, just give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+
+```tsx
+// Tailwind: use the project's focus token or established focus-ring utility
+<button className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--focus-ring)]">
+  Save
+</button>
+```
+
+A custom focus indicator must meet the applicable project/WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses, including component fills, page surfaces, images, gradients, and hover/selected states. A token, brand color, or `currentColor` is acceptable only when that rendered check passes.
+
+In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or explicitly use a system color such as `Highlight`; never freeze the authored color with `forced-color-adjust: none` unless the control remains perceivable.
+
+Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
+
+## Skip link
+
+When repeated navigation or other repeated chrome precedes the primary content, the first focusable element is a "Skip to content" link targeting `<main id="main">`. Visually hide it until focused:
+
+```css
+.skip-link {
+  position: absolute;
+  inset-inline-start: -999px;
+}
+.skip-link:focus {
+  inset-inline-start: 16px;
+  top: 16px;
+}
+```
+
+```html
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header>…</header>
+  <main id="main">…</main>
+</body>
+```
+
+Give in-page anchor targets `scroll-margin-top` (e.g. `scroll-margin-top: 80px` under a sticky header) so the target isn't hidden when jumped to.
+
+## tabindex rules
+
+- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
+- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers, and roving-tabindex members.
+- Positive `tabindex`: never. It hijacks the tab order for the whole page; fix the DOM order instead.
+
+### Roving tabindex
+
+Composite widgets (tabs, menus, toolbars, radio groups) occupy a single Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
+
+```tsx
+<div role="tablist">
+  {tabs.map((tab, i) => (
+    <button
+      role="tab"
+      tabIndex={i === activeIndex ? 0 : -1}
+      aria-selected={i === activeIndex}
+      onKeyDown={handleArrowKeys} // ArrowLeft/ArrowRight move activeIndex, wrapping
+    >
+      {tab.label}
+    </button>
+  ))}
+</div>
+```
+
+## Focus trapping and restoration
+
+Modals must trap focus. The modern technique is the `inert` attribute on everything behind the dialog; it removes background content from the tab order and from assistive tech in one move:
+
+```tsx
+// On open
+document.getElementById("app-content").inert = true;
+const dialog = dialogRef.current;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+
+// On close
+document.getElementById("app-content").inert = false;
+triggerRef.current?.focus(); // always return focus to the element that opened it
+```
+
+Native `<dialog>` with `showModal()` gives you the trap, `inert` background, and Escape handling for free; prefer it. A custom overlay that can't use `<dialog>` needs `role="dialog"`, `aria-modal="true"`, and an accessible name (`aria-labelledby` pointing at its heading). Either way:
+
+- On open, focus the first focusable element; for destructive confirmations, focus the least destructive action instead.
+- On close, return focus to the trigger. If the trigger no longer exists, move focus to the nearest logical container.
+- Add `overscroll-behavior: contain` on the dialog so scrolling inside never scrolls the page behind it.
+
+## Keyboard patterns (ARIA APG)
+
+Native elements come with these behaviors; custom widgets must implement them. A role is a promise: if you give something `role="tab"`, users expect the full tab keyboard model.
+
+| Widget | Keys |
+| --- | --- |
+| Dialog | Tab/Shift+Tab cycle inside (wrap at ends); Escape closes |
+| Tabs | Arrow keys move between tabs (wrapping); Tab exits to the panel; Home/End jump to first/last |
+| Menu button | Enter/Space/ArrowDown opens and focuses first item; ArrowUp opens and focuses last; arrows navigate; Escape closes and refocuses the button |
+| Disclosure / accordion | Header is a `<button aria-expanded>`; Enter and Space toggle |
+| Combobox | ArrowDown opens/moves into the list; Enter accepts; Escape closes and returns to the input; typing filters |
+| Listbox / radio group | Arrow keys move selection; one Tab stop for the whole group |
+
+Universal rules:
+
+- Escape dismisses whatever opened last: tooltip, then menu, then dialog.
+- Arrow keys, not Tab, move within a composite widget; Tab moves between widgets.
+- Tabs choose activation mode: automatic (panel switches on arrow focus) when panels render instantly, manual (Enter/Space to activate) when switching is expensive.
+- Enter submits the focused input's form. In `<textarea>`, Enter inserts a newline and ⌘/Ctrl+Enter submits.
+
+## SPA route changes
+
+Client-side navigation doesn't reset focus or announce anything. On route change: update `document.title` to match the new context, then move focus to the new view's `<h1>` (given `tabindex="-1"`) or to `<main>`. Restore scroll position on back/forward navigation; scroll to top on forward navigation.
diff --git a/.claude/skills/better-accessibility/forms.md b/.claude/skills/better-accessibility/forms.md
new file mode 100644
index 00000000..4a89cb1b
--- /dev/null
+++ b/.claude/skills/better-accessibility/forms.md
@@ -0,0 +1,86 @@
+# Forms
+
+Labels, autocomplete, error messaging, input types, and submit behavior.
+
+## Labels
+
+Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label: it disappears the moment the user types and usually fails contrast.
+
+```html
+<!-- Good: explicit association -->
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email" />
+
+<!-- Good: wrapping label, so label and control share one hit target -->
+<label>
+  <input type="checkbox" /> Send me updates
+</label>
+```
+
+Label and control must share one hit target: clicking the text "Send me updates" toggles the checkbox, with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
+
+Placeholders, when used *in addition to* a label, show an example of the expected format: `placeholder="name@company.com"`.
+
+## Error messaging
+
+The complete pattern:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  autocomplete="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error">Enter a valid email address.</p>
+```
+
+- `aria-invalid="true"` on the failing field, removed once fixed.
+- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
+- Errors render inline next to their fields, with an icon or text, never a red border alone (color-only cues fail).
+- On submit, focus the first invalid field.
+- Allow incomplete submission so validation can surface; don't disable submit until valid (see below).
+- Accept free text and validate after; don't block typing or filter characters as the user types. Trim values before validating; autocomplete and text expansion add trailing spaces.
+
+## Autocomplete and input types
+
+`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
+
+| Field | `autocomplete` |
+| --- | --- |
+| Name | `name` (or `given-name` / `family-name`) |
+| Email | `email` |
+| Phone | `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+
+Prefix with a section where relevant: `autocomplete="shipping street-address"`.
+
+Correct `type` and `inputmode` pick the right mobile keyboard:
+
+| Input | Use |
+| --- | --- |
+| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
+| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
+| Money, decimals | `type="text" inputmode="decimal"` |
+| True numeric quantity | `type="number"` |
+
+Disable spellcheck on emails, codes, and usernames: `spellcheck="false"`.
+
+## Never fight the user's tools
+
+- Never block paste in `<input>` or `<textarea>`; users paste passwords and one-time codes.
+- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
+- Never use `user-scalable=no` or `maximum-scale=1` to stop iOS input zoom; keep mobile input text at `16px` instead (covered in `better-typography`).
+
+## Submit behavior
+
+- Keep submit enabled until the request starts, then disable it and show a spinner *while keeping the original label*: "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
+- Announce results: success goes through a polite live region. For submit failures, focus the first invalid field; the focus move is the announcement, and reserve `role="alert"` for form-level errors not tied to a field (see [screen-readers.md](screen-readers.md)).
+- Warn on unsaved changes before navigation, and never lose typed input to a re-render; hydration must preserve focus and value.
+- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.
diff --git a/.claude/skills/better-accessibility/hit-areas.md b/.claude/skills/better-accessibility/hit-areas.md
new file mode 100644
index 00000000..d1882745
--- /dev/null
+++ b/.claude/skills/better-accessibility/hit-areas.md
@@ -0,0 +1,76 @@
+# Hit Areas
+
+Target sizes, expanding hit areas without changing visual size, and collision rules.
+
+## Target sizes
+
+Separate the conformance baseline from larger usability targets:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its defined exceptions. Treat 44px as a recommended touch target for primary controls and 40px as a useful desktop target when the product's density permits. Smaller controls are not automatically failures: check the spacing, equivalent-control, inline, user-agent, and essential exceptions before reporting one.
+
+Under the spacing exception, an undersized target passes if a 24px circle centered on its bounding box does not intersect another target or another undersized target's circle; in the simple case, 20px targets need at least a 4px gap.
+
+The visible element can stay small; the hit area is what must be big. If it looks clickable, it must be clickable across its whole visual extent: no dead zones (a checkbox and its label share one hit target).
+
+## Expanding the hit area
+
+If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element. Put the pseudo-element on the wrapping `<label>` or `<button>`, not on the `<input>` itself; replaced elements don't render `::before`/`::after` reliably.
+
+### CSS Example
+
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Layout alternative
+
+When the element can afford real box size, skip the pseudo-element and let the box itself be the target; this also gives the browser the real geometry for scrolling and gestures:
+
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+
+## Collision Rule
+
+If the extended hit area overlaps another interactive element, shrink the pseudo-element, but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.
+
+## Touch behavior
+
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Prefer generous targets and clear affordances over finicky interactions (tiny drag handles, precise hover zones).
diff --git a/.claude/skills/better-accessibility/motion-and-zoom.md b/.claude/skills/better-accessibility/motion-and-zoom.md
new file mode 100644
index 00000000..87e4ef81
--- /dev/null
+++ b/.claude/skills/better-accessibility/motion-and-zoom.md
@@ -0,0 +1,79 @@
+# Motion and Zoom
+
+`prefers-reduced-motion`, zoom and reflow, and unit choices that respect user settings.
+
+## prefers-reduced-motion
+
+Make motion opt-in: wrap animations in `@media (prefers-reduced-motion: no-preference)` so users who asked for reduced motion get the static version by default, instead of you chasing every animation with an override.
+
+```css
+/* Good: motion is opt-in */
+.card {
+  /* static styles */
+}
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    transition: transform 200ms ease-out;
+  }
+}
+```
+
+```tsx
+// Tailwind: motion-safe / motion-reduce variants
+<div className="motion-safe:transition-transform motion-safe:hover:-translate-y-1" />
+```
+
+For an existing codebase where opt-in isn't feasible, the global kill switch is the fallback:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`0.01ms` rather than `none` so `animationend`/`transitionend` events still fire and JS that waits on them doesn't hang.
+
+### What to disable vs reduce
+
+Reduced motion means reduced, not eliminated: it targets vestibular triggers, not feedback.
+
+| Disable entirely | Replace | Keep |
+| --- | --- | --- |
+| Parallax scrolling | Slide/scale/zoom transitions → opacity crossfade | Loading spinners and progress |
+| Autoplaying video, GIFs, looping decoration | Smooth scrolling → instant jump | Instant state changes (hover color, focus ring) |
+| Spinning, large-scale movement across the screen | Auto-rotating carousels → start paused | Brief functional feedback (button press) |
+
+Animations must be interruptible and driven by user input; nothing should autoplay or refuse to stop. Under reduced motion, carousels start paused.
+
+## Autoplay and timed UI
+
+Motion the user didn't ask for, and UI that acts on its own schedule:
+
+- **No autoplaying media without visible controls** (WCAG 2.2.2): anything that moves, blinks or updates automatically for more than 5 seconds needs a visible pause/stop control. Muted looping hero videos included.
+- **Prefer explicit dismissal over timers.** Auto-dismissing toasts are acceptable only for low-stakes confirmations; anything containing an action, an error, or information the user may need to act on stays until dismissed. If a toast must time out, 5 seconds is the floor, and hovering or focusing it pauses the timer.
+- **Never put critical information only in a timed element.** A vanished toast with the only link to an undo action is data loss on a schedule.
+
+## Zoom and reflow
+
+- **200% zoom** (WCAG 1.4.4): all content and functionality must survive text scaled to 200%. Never block zoom: no `user-scalable=no`, no `maximum-scale=1`. Safari ignores the cap but every other browser enforces it.
+- **Reflow at 320px** (WCAG 1.4.10): at 400% zoom on a 1280px viewport (equivalent to a 320px viewport) the page must work with vertical scrolling only: no two-dimensional scrolling except for genuinely 2D content (tables, maps, code blocks), which scroll inside their own container.
+
+Fixed heights are what break under zoom: use `min-height` on anything containing text and let containers grow.
+
+### rem vs px
+
+Respect how the codebase is set up: if the project sizes in `px` (or an established Tailwind scale), stay consistent with it; don't introduce mixed units into someone else's system. Where you do have the choice (new code, or a codebase already on `rem`), `rem` respects the user's base font size and `px` ignores it:
+
+| Use `rem` | Use `px` |
+| --- | --- |
+| `font-size` | Borders and hairlines |
+| `max-width` of text containers | Focus outline width and offset |
+| Media-query breakpoints (`@media (min-width: 48rem)`) | `box-shadow` details |
+| Spacing that should scale with text | Fixed-size decorations |
+
+Breakpoints are where the choice matters most: at a larger base font size, an `em`/`rem` query switches to the mobile layout when the text needs it; a `px` query doesn't.
diff --git a/.claude/skills/better-accessibility/screen-readers.md b/.claude/skills/better-accessibility/screen-readers.md
new file mode 100644
index 00000000..a868eae6
--- /dev/null
+++ b/.claude/skills/better-accessibility/screen-readers.md
@@ -0,0 +1,101 @@
+# Screen Readers
+
+Visually hidden content, live regions, toasts, alt text, and SVG.
+
+## Visually hidden content
+
+The canonical `.sr-only` pattern hides content visually while keeping it in the accessibility tree:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+Use `1px` boxes, not `0`; some screen readers skip zero-sized elements. `white-space: nowrap` prevents words from being read as one run-together string. Never use `display: none` or `visibility: hidden` for this; both remove the content from assistive tech entirely.
+
+Tailwind ships this as `sr-only`. For skip links, add a focus variant that un-hides the element (`focus:not-sr-only`, or override the positioning on `:focus`).
+
+Use it for context that sighted users get visually: `<span class="sr-only">Opens in new tab</span>`, table caption text, or the label of an icon-only control when `aria-label` isn't an option.
+
+## Choosing how to announce a change
+
+Work down this list and stop at the first match:
+
+1. **Focus moves there anyway** (opened modal, first invalid field on submit): nothing extra needed; the focus move is the announcement.
+2. **Tied to a specific control** (field error, character count): `aria-describedby` on the control; it's announced with the field.
+3. **Non-urgent, not tied to a control** (toast, "Saved", result count, loading state): polite live region / `role="status"`.
+4. **Urgent and not tied to a control** (form-level failure, session expiring): `role="alert"`.
+
+## Live regions
+
+Live regions announce content that changes without a page load: toasts, validation, search-result counts, loading states.
+
+| Mechanism | Politeness | Use for |
+| --- | --- | --- |
+| `role="status"` (= `aria-live="polite"` + `aria-atomic="true"`) | Waits for a pause | Toasts, "Saved", result counts, loading updates |
+| `role="alert"` (= `aria-live="assertive"` + `aria-atomic="true"`) | Interrupts immediately | Errors and urgent problems only |
+
+Rules for reliable announcements:
+
+- For repeated polite updates, keep a stable empty region in the DOM before changing its text. Inserting a new polite region together with its content is inconsistently announced.
+- Dynamically inserted `role="alert"` content is commonly announced, but behavior varies; use it only for urgent errors not tied to a control and test the target browser/screen-reader combinations.
+- Default to polite. Overusing `assertive` is the most common live-region mistake; it interrupts whatever the user was reading.
+- Keep messages short and self-contained; `aria-atomic="true"` re-reads the whole region on change.
+- Don't move focus to a toast; announce it and leave focus where the user is working. Give toasts a generous timeout or a dismiss button, and never put the only path to an action inside an auto-dismissing toast.
+
+```tsx
+// Region rendered from the start, message injected later
+<div role="status" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+For loading states: set `aria-busy="true"` on the updating region, announce "Loading…" politely, then announce the outcome ("Loaded, 12 results").
+
+## aria-hidden
+
+`aria-hidden="true"` removes an element and its whole subtree from assistive tech. Use it for decorative icons and content duplicated for visual effect. Never put it on (or above) a focusable element; that creates stops you can Tab to that don't exist for a screen reader. If you hide something interactive, also remove it from the tab order.
+
+## Alt text
+
+Choose by purpose, not by what the image looks like:
+
+| Purpose | Alt | Example |
+| --- | --- | --- |
+| Decorative, or redundant with adjacent text | `alt=""` (empty, but present) | Logo next to the company name in text |
+| Informative | Describe the meaning it adds | `alt="Ticket QR code"` |
+| Functional (image is the link/button) | Describe the action or destination | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text | The exact text (better: use real text) | `alt="50% off everything"` |
+| Complex (chart, diagram) | Short summary in `alt`, full data as a table or text nearby | `alt="Revenue by quarter, described below"` |
+
+A missing `alt` attribute is worse than an empty one: screen readers fall back to reading the file name.
+
+## SVG
+
+- Decorative SVG: `aria-hidden="true"` and `focusable="false"` (the latter for legacy Edge/IE tabbing), no title needed.
+- Meaningful inline SVG: `role="img"` plus `aria-label="…"` (or a `<title>` as the first child referenced by `aria-labelledby`).
+- Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
+
+```tsx
+// Decorative icon inside a labeled button
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">…</svg>
+</button>
+
+// Standalone meaningful icon
+<svg role="img" aria-label="Verified account">…</svg>
+```
+
+## Video and audio
+
+Prerecorded video needs captions; provide transcripts for audio. Never autoplay with sound, and always render controls.
diff --git a/.claude/skills/better-accessibility/semantics-and-aria.md b/.claude/skills/better-accessibility/semantics-and-aria.md
new file mode 100644
index 00000000..0a9a612d
--- /dev/null
+++ b/.claude/skills/better-accessibility/semantics-and-aria.md
@@ -0,0 +1,83 @@
+# Semantics and ARIA
+
+Native elements first, landmarks, accessible names, and the ARIA rules that keep custom widgets honest.
+
+## The rules of ARIA
+
+1. If a native HTML element with the semantics and behavior you need exists, use it instead of repurposing another element with ARIA.
+2. Don't change native semantics unless you really have to.
+3. Every interactive ARIA control must be keyboard-operable; a role is a promise of the full keyboard model, states, and behavior.
+4. Never put `role="presentation"` or `aria-hidden="true"` on a focusable element.
+5. All interactive elements must have an accessible name.
+
+No ARIA is better than bad ARIA: a screen reader trusts your roles, so a wrong role is worse than none.
+
+## Button vs link vs div
+
+| Element | Use for | Why |
+| --- | --- | --- |
+| `<a href>` | Navigation: anything that goes somewhere or changes the URL | Free Cmd/Ctrl/middle-click, right-click → copy link, Enter activation |
+| `<button>` | Actions: submit, toggle, open, delete | Free focus, Enter *and* Space activation, form semantics |
+| `<div onClick>` | Nothing | No role, no focus, no keyboard; screen readers see plain text |
+
+```tsx
+// Bad: invisible to keyboard and screen readers
+<div onClick={openSettings}>Settings</div>
+
+// Good: focus, Enter/Space activation, and semantics for free
+<button onClick={openSettings}>Settings</button>
+```
+
+If it looks clickable it must be clickable, and the reverse: if it's clickable it must be a real interactive element. Rebuilding a link as a button (or vice versa) breaks user expectations; a "button" that navigates should be a styled `<a>`.
+
+If a native element is truly impossible, the full polyfill is `role="button"` + `tabindex="0"` + Enter and Space handlers, which is why the native element is always less code.
+
+## Landmarks and headings
+
+- Expose one visible primary `<main>` landmark. `<header>`, `<nav>`, `<aside>`, `<footer>` map to landmarks screen-reader users jump between.
+- Multiple landmarks of the same type need distinguishing labels: `<nav aria-label="Primary">`, `<nav aria-label="Breadcrumbs">`.
+- Headings describe their sections and form a coherent outline. One page-level `<h1>` and properly nested levels are the recommended default; do not report either convention as a standalone WCAG failure without a concrete navigation or comprehension impact. Headings are structure, not styling; style a heading level with CSS instead of picking the tag by size.
+- `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
+
+## Accessible names
+
+Name precedence: `aria-labelledby` > `aria-label` > native label (`<label>`, text content, `alt`) > `title` attribute.
+
+- Prefer visible text or `aria-labelledby` over `aria-label`: `aria-label` is invisible, drifts out of sync with the UI, and translation tools handle it inconsistently.
+- Icon-only buttons always need a name: `<button aria-label="Close">` with the icon `aria-hidden="true"`.
+- The visible label must appear inside the accessible name (WCAG 2.5.3 Label in Name). A button showing "Send" with `aria-label="Submit message"` breaks voice control users who say "click Send".
+- Accessible names must exist even when the design omits visible labels.
+
+```tsx
+// Good: name from visible text, icon hidden
+<button>
+  <TrashIcon aria-hidden="true" /> Delete
+</button>
+
+// Good: icon-only, explicit name
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+Add `translate="no"` to brand names, code tokens, and identifiers so auto-translation doesn't garble them.
+
+## Common ARIA mistakes
+
+| Mistake | Why it fails |
+| --- | --- |
+| `aria-label` on a plain `<div>` or `<span>` | Names on non-interactive, role-less elements are ignored by most screen readers |
+| `<button role="button">` | Redundant role; adds noise, no benefit |
+| `aria-hidden="true"` on or above a focusable element | Creates elements you can Tab to but that don't exist for screen readers |
+| `aria-labelledby`/`aria-describedby` pointing at a missing ID | Silently produces no name or description |
+| `role="menu"` on a nav list | `menu` promises app-style arrow-key behavior; site navigation is `<nav>` with a list |
+
+## Disabled states
+
+Native `disabled` supplies the platform's complete disabled behavior: it removes the control from the tab order, suppresses activation, applies `:disabled`, and excludes form controls from submission. Use it when a native control is genuinely unavailable. `aria-disabled="true"` only announces the state; it does not change focusability, suppress behavior, or add disabled styling.
+
+- Don't disable submit buttons at all: keep them enabled, validate on submit, and focus the first error (see [forms.md](forms.md)).
+- Use `aria-disabled="true"` when keeping a control discoverable in the tab order is an intentional requirement, or when a custom control cannot use native `disabled`.
+- With `aria-disabled="true"`, block pointer and keyboard activation in the handler, prevent form submission where applicable, add explicit styling (including forced-colors support), and explain why the action is unavailable nearby.
+- Never set both `disabled` and `aria-disabled` on the same element.
+- Disabled controls are exempt from contrast minimums, but keep them legible anyway.
diff --git a/.claude/skills/better-colors/SKILL.md b/.claude/skills/better-colors/SKILL.md
new file mode 100644
index 00000000..fdeff04e
--- /dev/null
+++ b/.claude/skills/better-colors/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: better-colors
+description: OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.
+---
+
+# OKLCH Colors
+
+OKLCH is a perceptually uniform color space where lightness, chroma, and hue are useful design controls. Use it when the project already uses OKLCH, when creating a new color system, or when the user asks for conversion or palette work. Otherwise preserve the project's established tokens and notation: a consistent hex or RGB token system is better than introducing a second color representation for an isolated fix. To explore interactively, visit [oklch.fyi](https://oklch.fyi).
+
+## Quick Reference
+
+| Category | When to use | Reference |
+| --- | --- | --- |
+| Conversion | Hex/rgb/hsl to oklch | [color-conversion.md](color-conversion.md) |
+| Palettes | Generate scales, multi-hue, dark mode | [palette-generation.md](palette-generation.md) |
+| Contrast | APCA/WCAG checks, reporting failures, fixing on request | [accessibility-contrast.md](accessibility-contrast.md) |
+| Gamut & Tailwind | P3 fallbacks, `@theme` scales, gamut clamping | [gamut-and-tailwind.md](gamut-and-tailwind.md) |
+| Usage | Semantic tokens, one meaning per color, primary-action emphasis, appearance variants | [color-usage.md](color-usage.md) |
+
+## Core Principles
+
+### 1. Use a Perceptual Color Space
+
+- **Respect the existing system.** Do not convert notation merely because this skill was loaded. Reuse the project's semantic tokens and authoring format unless the task includes a color-system migration.
+- **Perceptual uniformity.** Equal L steps = equal brightness. `oklch(0.5 ...)` is visually mid. HSL's `lightness: 50%` varies wildly by hue.
+- **Stable hue.** HSL blue shifts toward purple as lightness changes. OKLCH hue stays constant across the full lightness range.
+- **Independent chroma.** Chroma is an absolute measure of colorfulness that doesn't depend on lightness. HSL saturation does.
+- **Finite gamut.** Not every oklch value maps to a displayable sRGB color. High-chroma values at certain hues will clip; gamut awareness is required.
+
+### 2. Write and Format OKLCH Consistently
+
+```
+oklch(L C H)
+oklch(L C H / alpha)
+```
+
+| Channel | Range | Description |
+| --- | --- | --- |
+| L (Lightness) | 0–1 | 0 = black, 1 = white. Perceptually uniform. |
+| C (Chroma) | 0–~0.4 | Colorfulness. 0 = gray. Max depends on L and H. |
+| H (Hue) | 0–360 | Hue angle in degrees. |
+| alpha | 0–1 | Optional transparency. Slash syntax. |
+
+```css
+oklch(0.637 0.237 25.331)
+oklch(0.8 0.05 200 / 0.5)
+```
+
+Use three decimal places for L and C and up to three for H. Drop trailing zeros and format `-0` as `0`. OKLCH is Baseline 2023; when support requirements are unusually broad, check the target project's browser matrix instead of relying on a fixed global-coverage percentage.
+
+### 3. Measure Contrast, Gamut, and Palette Behavior
+
+| Rule | Value |
+| --- | --- |
+| Light/dark boundary | L > 0.73 = light background → dark text; below it, light text still scores higher |
+| Lightness gap (light bg) | Foreground L < 0.35 when background L > 0.9 |
+| Lightness gap (dark bg) | Foreground L > 0.9 when background L < 0.25 |
+| Hue drift threshold | > 10° spread across palette steps = visible drift |
+| APCA body text | \|Lc\| >= 75 minimum, >= 90 preferred |
+| APCA non-body text | \|Lc\| >= 60 minimum |
+| WCAG 2 normal text | 4.5:1 AA, 7:1 AAA |
+| Contrast fix (only when asked) | Adjust L first; preserve C and H when possible, then remeasure the rendered pair |
+
+## Common Mistakes
+
+| Issue | Fix |
+| --- | --- |
+| Raw color bypasses the project's semantic token system | Reuse or add the correct role token in the project's existing notation |
+| Isolated OKLCH value introduced into a hex/RGB codebase | Preserve the established notation unless the task includes a color-system migration |
+| HSL palette ramp with hue drift | Rebuild with constant oklch hue |
+| Failing contrast (check foreground vs its background using APCA) | Report the pair, its measured Lc and the threshold it misses; change colors only when asked (then adjust L, keep C and H) |
+| High chroma without gamut check | Clamp to max chroma for the L/H in sRGB |
+| Same absolute C across different hues | Use same C% (percentage of max) for consistent vividness |
+| P3 color without sRGB fallback | Add `@media (color-gamut: p3)` pattern |
+| Dark mode created by mechanically reversing the light palette | Use the light palette as a starting point, then tune chroma and lightness and recheck every foreground/background pair |
+| Hex in Tailwind v4 `@theme` | Convert to oklch values |
+| Alpha with comma syntax | Use slash: `oklch(L C H / alpha)` |
+| Same hue means two different things (link color reused decoratively) | One color, one meaning; give the second use a neutral |
+| Semantic token used outside its role (separator as text) | Add a token for the missing role; never borrow by value |
+| Several colored control backgrounds in one view | Fill only the single primary action; secondaries stay neutral |
+| Palette verified only in light mode | Recheck every foreground/background pair in both appearances |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone color review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes content unreadable or assigns a misleading semantic color; `MEDIUM` creates a noticeable theme, gamut, or consistency failure; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current value or token and the exact replacement.
+- **Why**: name the violated principle and include measured contrast or gamut evidence when relevant.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/theme.css:18` | `color: #3b82f6` | `color: oklch(0.623 0.188 259.815)` | New project colors use OKLCH tokens |
+| MEDIUM | `src/palette.ts:31` | Same absolute C across hues | Same C% of each hue's maximum chroma | Equal chroma values do not appear equally vivid across hues |
+| HIGH | `src/theme.css:52` | P3 color with no fallback | Add an sRGB fallback before `@media (color-gamut: p3)` | The color fails on non-P3 displays |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including contrast measurements, gamut checks, and both light and dark appearances when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the table, state "No actionable color findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-colors/accessibility-contrast.md b/.claude/skills/better-colors/accessibility-contrast.md
new file mode 100644
index 00000000..d88a3c7d
--- /dev/null
+++ b/.claude/skills/better-colors/accessibility-contrast.md
@@ -0,0 +1,87 @@
+# Accessibility & Contrast
+
+Contrast is always measured between a **foreground color** (text, icon, or UI element) and the **background color** it sits on. When checking contrast, identify the background the element will be rendered against, typically the nearest parent's background color.
+
+**Report, don't repaint.** When a check fails, report it (the failing foreground/background pair, its measured Lc or ratio, and the threshold it misses) and leave the colors unchanged. A project's colors are a design decision; only apply the fix below when the user asks for one.
+
+## APCA thresholds (recommended)
+
+APCA (Accessible Perceptual Contrast Algorithm) is more perceptually accurate than WCAG 2 and pairs naturally with oklch since both are grounded in perceptual lightness. Use APCA as the default.
+
+Lc (Lightness Contrast) measures the perceived contrast between foreground and background. These levels are simplified from APCA's full font-size/weight lookup table:
+
+| Content Type | Minimum | Preferred |
+| --- | --- | --- |
+| Body text (columns/blocks of text) | Lc 75 | Lc 90 |
+| Non-body text (labels, headlines) | Lc 60 | Lc 75 |
+| Large text (≥36px) | Lc 45 | Lc 60 |
+| UI components | Lc 30 | n/a |
+
+Lc 30 is also APCA's minimum for disabled and placeholder text; the absolute floor for non-text elements to be discernible at all is Lc 15.
+
+APCA's Lc value is signed: positive means dark text on a light background, negative means light text on a dark background. Use the absolute value for threshold comparison.
+
+## WCAG 2 thresholds (for legal compliance)
+
+WCAG 2 is still required when making formal WCAG 2.x conformance claims. It uses a luminance ratio that can be both too strict and too lenient depending on the color pair.
+
+| Content Type | AA | AAA |
+| --- | --- | --- |
+| Normal text (<24px / <18.5px bold) | 4.5:1 | 7:1 |
+| Large text (>=24px / >=18.5px bold) | 3:1 | 4.5:1 |
+| UI components & graphical objects | 3:1 | n/a |
+
+WCAG defines "large text" in points: 18pt ≈ `24px`, or 14pt bold ≈ `18.5px`.
+
+## Fixing contrast with oklch (on request)
+
+In hex/rgb, fixing contrast means trial and error across three channels. In oklch, lightness (L) is the clearest first lever: adjust the L distance between the foreground and its background while preserving C and H when possible:
+
+```css
+/* Failing: text too close in lightness to its background (Lc ≈ 50) */
+color: oklch(0.65 0.08 250);      /* foreground */
+background: oklch(0.95 0.02 250); /* background */
+
+/* Fix: darken the text, keep C and H unchanged (Lc ≈ 90) */
+color: oklch(0.3 0.08 250);       /* foreground: more L distance */
+background: oklch(0.95 0.02 250); /* background: unchanged */
+```
+
+Note that mid-lightness backgrounds cap the achievable contrast: on a background of L 0.75, even pure black text only reaches about Lc 60; body text needs a background near the light or dark extreme.
+
+Adjust L first, then remeasure the rendered foreground/background pair. Chroma and hue can still affect the converted color, gamut mapping, and measured contrast; reduce C when needed to keep the adjusted color in gamut.
+
+## Quick lightness gap guide
+
+For body text (targeting |Lc| >= 75):
+
+- **Light background (L > 0.9):** foreground L should be below 0.35
+- **Dark background (L < 0.25):** foreground L should be above 0.9
+
+The gap is asymmetric because APCA is polarity-aware: mirrored pairs don't score identically. These are approximations; always verify with an actual contrast calculation.
+
+## Light vs dark color detection
+
+A background counts as light when its oklch lightness exceeds 0.73, the APCA crossover on neutral backgrounds:
+
+```
+if L > 0.73 → use dark text on this background
+if L <= 0.73 → use light text on this background
+```
+
+The crossover is higher than intuition suggests: in the 0.6–0.73 band the background already looks light, but white text still scores meaningfully higher than black.
+
+## Hue drift detection
+
+To detect hue drift in an existing HSL palette:
+
+1. Convert each step to oklch
+2. Compare the H values across steps
+3. If the hue spread is greater than 10°, the palette has visible drift
+
+```css
+/* HSL blue ramp: hue shifts toward purple */
+hsl(240, 80%, 20%)  →  oklch H ≈ 269
+hsl(240, 80%, 50%)  →  oklch H ≈ 267
+hsl(240, 80%, 90%)  →  oklch H ≈ 285  /* shifted 18° */
+```
diff --git a/.claude/skills/better-colors/agents/openai.yaml b/.claude/skills/better-colors/agents/openai.yaml
new file mode 100644
index 00000000..ae19ceb2
--- /dev/null
+++ b/.claude/skills/better-colors/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Colors"
+  short_description: "OKLCH palettes, contrast and theming"
diff --git a/.claude/skills/better-colors/color-conversion.md b/.claude/skills/better-colors/color-conversion.md
new file mode 100644
index 00000000..fa660420
--- /dev/null
+++ b/.claude/skills/better-colors/color-conversion.md
@@ -0,0 +1,53 @@
+# Color Conversion
+
+Use this reference only when the user asks for conversion, the project is already standardizing on OKLCH, or an agreed color-system migration requires it. Do not convert an isolated value in a project that intentionally uses another notation. When conversion is in scope, convert the color values but leave everything else unchanged: don't change gradient interpolation or restructure the CSS.
+
+## Supported input formats
+
+| Format | Examples |
+| --- | --- |
+| Hex (3/6/8-digit) | `#f00`, `#ff0000`, `#ff000080` |
+| `rgb()` / `rgba()` | `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)` |
+| `hsl()` / `hsla()` | `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)` |
+
+## Conversion examples
+
+```css
+/* Before */
+color: #3b82f6;
+background: #1e293b;
+border-color: #e2e8f0;
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+background: oklch(0.279 0.037 260.031);
+border-color: oklch(0.929 0.013 255.508);
+```
+
+```css
+/* Before */
+color: rgb(59, 130, 246);
+border: 1px solid rgba(0, 0, 0, 0.1);
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+border: 1px solid oklch(0 0 0 / 0.1);
+```
+
+Alpha uses the forward-slash syntax. Omit alpha when it's 1.
+
+## What to leave alone
+
+- CSS keywords: `currentColor`, `inherit`, `initial`, `unset`, `transparent`
+- Gradient interpolation methods: only convert the color stops, not the function itself
+- Colors in third-party library configs that expect hex input
+
+## Bulk conversion
+
+Bulk conversion is a migration task, not routine cleanup. When an entire file is explicitly in scope:
+
+1. Replace all hex colors with their oklch equivalents
+2. Replace all `rgb()`, `rgba()`, `hsl()`, `hsla()` function calls
+3. Leave gradient functions unchanged; only convert the color stops within them
+4. Leave `currentColor`, `inherit`, `transparent`, and CSS keywords as-is
+5. Preserve comments and formatting
diff --git a/.claude/skills/better-colors/color-usage.md b/.claude/skills/better-colors/color-usage.md
new file mode 100644
index 00000000..6b2a1dd0
--- /dev/null
+++ b/.claude/skills/better-colors/color-usage.md
@@ -0,0 +1,94 @@
+# Color Usage
+
+How to deploy color in an interface: semantic tokens, meaning, emphasis, and appearance variants. For picking the values themselves, see [palette-generation.md](palette-generation.md); for checking pairs, see [accessibility-contrast.md](accessibility-contrast.md).
+
+## One color, one meaning
+
+Use a color consistently for one purpose (interactive, destructive, featured) across the interface. If the brand color signals that text is interactive, that hue (anywhere within ±15°) on non-interactive text tells users to click something that isn't clickable.
+
+```css
+/* Bad: brand blue means both "link" and "decorative heading" */
+a { color: oklch(0.623 0.188 259.815); }
+.section-title { color: oklch(0.65 0.17 259.815); }
+
+/* Good: interactive elements own the brand hue; headings stay neutral */
+a { color: oklch(0.623 0.188 259.815); }
+.section-title { color: oklch(0.279 0.041 260.031); }
+```
+
+## Semantic tokens over raw values
+
+Name colors by role, not by appearance, and apply them only in that role: `--color-text-secondary` is muted foreground text, and using it as a background breaks every future theme change that assumes the role.
+
+```css
+/* Good: tokens named by role, used in that role */
+:root {
+  --color-text-primary: oklch(0.21 0.006 285.885);
+  --color-text-secondary: oklch(0.552 0.016 285.938);
+  --color-separator: oklch(0.92 0.004 286.32);
+  --color-surface: oklch(1 0 0);
+}
+
+/* Bad: separator token repurposed as text color because it "looked right" */
+.caption { color: var(--color-separator); }
+
+/* Bad: secondary-text token repurposed as a background */
+.tag { background: var(--color-text-secondary); }
+```
+
+If a role has no token yet, add the token; don't borrow one that happens to have the right value today. In Tailwind projects, this is the `@theme` block; see [gamut-and-tailwind.md](gamut-and-tailwind.md).
+
+## One colored action per view
+
+When the product uses filled color to encode primary emphasis, give that treatment to one primary action in the current decision context and leave peer actions neutral. Preserve an established component hierarchy that communicates emphasis another way; do not recolor controls merely to impose this recipe. Multiple colored backgrounds are acceptable when they encode distinct states or categories and do not compete as peer actions.
+
+```html
+<!-- Good: one filled primary action, neutral secondaries -->
+<button class="bg-blue-600 text-white">Save</button>
+<button class="text-zinc-700">Cancel</button>
+
+<!-- Bad: every action colored, so nothing is primary -->
+<button class="bg-blue-600 text-white">Save</button>
+<button class="bg-blue-600 text-white">Duplicate</button>
+<button class="bg-blue-600 text-white">Export</button>
+```
+
+Put the color on the background, not the label: a filled `bg-blue-600 text-white` button reads as primary from across the room; blue label text on a neutral button reads as a link. Selected states (an active tab, a checked segment) may use the accent color on the glyph and label: that is state, not emphasis.
+
+## Color across cultures
+
+Color meaning is not universal. If a color is load-bearing (finance, status, alerts), verify the meaning holds in every locale you ship to.
+
+| Color | Common Western reading | Elsewhere |
+| --- | --- | --- |
+| Red | Danger, loss, errors | Luck, prosperity; **gains** in Chinese financial UIs |
+| Green | Success, gains, go | Losses in Chinese financial UIs |
+| White | Purity, cleanliness | Mourning in parts of East Asia |
+| Gold | Premium, luxury | Religious significance in some regions |
+
+The classic case: stock tickers show gains in green for English locales and in red for Chinese locales. If your product localizes into such markets, make the gain/loss colors a per-locale token, not a hardcoded value.
+
+## Light, dark, and increased contrast
+
+Every custom color needs a light and a dark variant; dark mode derivation is covered in [palette-generation.md](palette-generation.md). Beyond that, users who enable increased contrast expect visibly stronger differentiation; supply it with `prefers-contrast`:
+
+```css
+:root {
+  --color-accent: oklch(0.623 0.188 259.815);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root { --color-accent: oklch(0.707 0.165 254.624); }
+}
+
+@media (prefers-contrast: more) {
+  :root { --color-accent: oklch(0.488 0.243 264.376); }
+}
+```
+
+The increased-contrast variant widens the foreground/background lightness gap by at least `0.15` L over the default variant. Then re-verify the pair against APCA's preferred thresholds (Lc 90 body, Lc 75 non-body).
+
+Two testing rules:
+
+- **Recheck every foreground/background pair in both appearances.** A pair that passes in light mode can fail in dark mode; the palettes aren't mirror images.
+- **Account for translucency.** A color on a translucent surface (`backdrop-filter` header, overlay) shifts with whatever scrolls behind it. Test it over the lightest and darkest content it can sit on, or make the surface opaque enough that the shift can't break contrast.
diff --git a/.claude/skills/better-colors/gamut-and-tailwind.md b/.claude/skills/better-colors/gamut-and-tailwind.md
new file mode 100644
index 00000000..f3cd08e7
--- /dev/null
+++ b/.claude/skills/better-colors/gamut-and-tailwind.md
@@ -0,0 +1,103 @@
+# Gamut Awareness & Tailwind v4
+
+## sRGB vs Display P3
+
+Every sRGB color exists within Display P3, but not every P3 color exists within sRGB. Display P3 covers ~50% more colors.
+
+## Max chroma varies by lightness and hue
+
+The gamut boundary is irregular. At L=0.5 in sRGB:
+
+- Highest chroma: purple (H ≈ 285) at C ≈ 0.29
+- Red-orange (H ≈ 0-30): C ≈ 0.20
+- Lowest chroma: cyan (H ≈ 195) at C ≈ 0.09
+
+The peak hue shifts with lightness. At L=0.7 magenta peaks, at L=0.9 green peaks. Cyan consistently has the lowest max chroma.
+
+## Gamut checking
+
+If a color's chroma exceeds the maximum for its L/H/space, it clips. The fix: reduce chroma while keeping L and H constant.
+
+```css
+/* Out of sRGB gamut */
+oklch(0.7 0.35 150)
+
+/* Clamped to max chroma */
+oklch(0.7 0.22 150)
+```
+
+## CSS fallback patterns
+
+```css
+/* sRGB fallback for all browsers */
+.accent {
+  color: oklch(0.7 0.2 150);
+}
+
+/* P3 enhancement for wider gamut displays */
+@media (color-gamut: p3) {
+  .accent {
+    color: oklch(0.7 0.3 150);
+  }
+}
+```
+
+For browsers without oklch support:
+
+```css
+.accent {
+  color: #4ade80;
+}
+
+@supports (color: oklch(0 0 0)) {
+  .accent {
+    color: oklch(0.7 0.2 150);
+  }
+
+  @media (color-gamut: p3) {
+    .accent {
+      color: oklch(0.7 0.3 150);
+    }
+  }
+}
+```
+
+## Tailwind v4
+
+Tailwind CSS v4 defines its default palette in oklch. Custom themes should follow the same convention.
+
+### Custom color scale with @theme
+
+```css
+@theme {
+  --color-brand-50: oklch(0.971 0.012 250);
+  --color-brand-100: oklch(0.932 0.028 250);
+  --color-brand-200: oklch(0.882 0.048 250);
+  --color-brand-300: oklch(0.812 0.078 250);
+  --color-brand-400: oklch(0.722 0.148 250);
+  --color-brand-500: oklch(0.623 0.188 250);
+  --color-brand-600: oklch(0.535 0.168 250);
+  --color-brand-700: oklch(0.445 0.138 250);
+  --color-brand-800: oklch(0.362 0.108 250);
+  --color-brand-900: oklch(0.289 0.078 250);
+  --color-brand-950: oklch(0.215 0.048 250);
+}
+```
+
+This gives you `bg-brand-500`, `text-brand-200`, etc. automatically.
+
+### Opacity modifiers
+
+Tailwind's opacity modifier syntax works with oklch:
+
+```html
+<div class="bg-brand-500/50"></div>
+<!-- Compiles to: oklch(0.623 0.188 250 / 0.5) -->
+```
+
+### Migrating existing themes
+
+1. Convert all hex values in `@theme` to oklch
+2. Replace any `theme()` references that used hex
+3. Test dark mode: oklch values may look slightly different due to perceptual accuracy
+4. Check for hardcoded hex in component code and convert those too
diff --git a/.claude/skills/better-colors/palette-generation.md b/.claude/skills/better-colors/palette-generation.md
new file mode 100644
index 00000000..228988fb
--- /dev/null
+++ b/.claude/skills/better-colors/palette-generation.md
@@ -0,0 +1,93 @@
+# Palette Generation
+
+## The scale convention
+
+Design system palettes use a numeric scale from 50 (lightest) to 950 (darkest). The standard labels by palette size:
+
+| Size | Labels |
+| --- | --- |
+| 5 | 100, 300, 500, 700, 900 |
+| 9 | 50, 100, 200, 300, 500, 700, 800, 900, 950 |
+| 11 | 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950 |
+
+11 steps matches Tailwind's default scales; use 9 as a leaner default when the `400`/`600` in-betweens aren't needed.
+
+## Algorithm
+
+Given a base color with lightness (L), chroma percentage, and hue (H):
+
+**Step 1. Lightness bounds:**
+
+```
+delta = 0.4
+minL = max(0.05, baseL - delta)
+maxL = min(0.95, baseL + delta)
+```
+
+Lightness is clamped to [0.05, 0.95] to avoid pure black/white which have zero chroma.
+
+**Step 2. Distribute lightness** evenly from maxL (lightest, label 50) to minL (darkest, label 950).
+
+**Step 3. Clamp chroma per step.** Each lightness level has a different maximum chroma for a given hue and color space:
+
+```
+maxChroma = findMaxChroma(step[i].L, hue, colorSpace)
+step[i].C = (chromaPercentage / 100) * maxChroma
+```
+
+This ensures every step is within gamut. High-chroma base colors will have lower chroma at the lightest and darkest ends; this is correct and expected.
+
+## CSS variable output
+
+```css
+:root {
+  --color-50: oklch(0.971 0.012 250);
+  --color-100: oklch(0.932 0.028 250);
+  --color-200: oklch(0.882 0.048 250);
+  --color-300: oklch(0.812 0.078 250);
+  --color-500: oklch(0.623 0.188 250);
+  --color-700: oklch(0.445 0.138 250);
+  --color-800: oklch(0.362 0.108 250);
+  --color-900: oklch(0.289 0.078 250);
+  --color-950: oklch(0.215 0.048 250);
+}
+```
+
+## Multi-hue palettes
+
+When generating palettes for multiple hues, use the same **lightness** and **chroma percentage** for all. Same L guarantees equal perceived brightness. Same chroma percentage (not absolute chroma) guarantees equal vividness relative to each hue's maximum.
+
+```css
+:root {
+  /* Same L, same C% (80% of max): different absolute C per hue */
+  --blue-500: oklch(0.623 0.141 250);   /* 80% of max 0.176 */
+  --green-500: oklch(0.623 0.157 145);  /* 80% of max 0.196 */
+  --red-500: oklch(0.623 0.202 25);     /* 80% of max 0.253 */
+}
+```
+
+Different hues have different max chroma at the same lightness. Using the same absolute C value across hues would make some appear more vivid than others.
+
+## Dark mode
+
+Start by swapping the light and dark semantic roles, then tune the mapped values for the dark appearance:
+
+```css
+:root {
+  --color-bg: var(--color-50);
+  --color-text: var(--color-950);
+}
+
+.dark {
+  --color-bg: var(--color-950);
+  --color-text: var(--color-50);
+}
+```
+
+Do not mechanically reverse every palette step. Dark appearances often need different chroma and lightness spacing, and equal OKLCH steps do not guarantee that every foreground/background pair preserves its contrast. Recheck each pair and tune the dark tokens independently where needed.
+
+## Why not HSL palettes?
+
+**Hue drift:** `hsl(240, 80%, 20%)` and `hsl(240, 80%, 90%)` are not the same perceptual hue. The light variant shifts ~16° toward purple. OKLCH hue is stable.
+
+**Brightness inconsistency:** `hsl(60, 100%, 50%)` (yellow) and `hsl(240, 100%, 50%)` (blue) have the same HSL lightness but wildly different perceived brightness.
diff --git a/.claude/skills/better-interface/SKILL.md b/.claude/skills/better-interface/SKILL.md
new file mode 100644
index 00000000..cf0dea40
--- /dev/null
+++ b/.claude/skills/better-interface/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: better-interface
+description: >-
+  User-invoked, cross-discipline interface review that coordinates better-accessibility, better-layout, better-writing, better-typography, better-colors, and better-ui. Use when explicitly invoked for a holistic review of a screen, flow, feature, or product interface. Supports quick and full review modes. Triggers on better-interface, full interface review, holistic UI audit, cross-discipline design review, review the whole interface.
+---
+
+# Review the interface as one system
+
+A strong interface is not six independent audits stapled together. Review the whole experience, let each `better-*` skill own its domain rules, then consolidate the evidence into one prioritized verdict.
+
+This skill owns orchestration only. Accessibility rules belong to `better-accessibility`; structure to `better-layout`; copy to `better-writing`; type to `better-typography`; color to `better-colors`; visual polish and motion to `better-ui`. Never duplicate or override their rules here.
+
+## Core Principles
+
+### 1. Resolve Scope and Mode First
+
+Infer the screen, flow, feature, or repository scope from the request and current workspace. State the resolved scope in the output. Use `full` when no mode is supplied.
+
+| Mode | Coverage | Finding cap |
+| --- | --- | --- |
+| `quick` | Primary user path and highest-traffic states; report only `HIGH` and `MEDIUM` issues | 5 |
+| `full` | Entire requested scope across all six domain skills, including empty, loading, error, and narrow-width states when present | 15 |
+
+If the requested scope is too large to inspect credibly, narrow it to the highest-traffic complete flow and state the boundary. Never imply uninspected surfaces were reviewed.
+
+### 2. Recon Before Judgment
+
+Identify the framework, styling system, component library, design tokens, supported viewports, and available preview or test commands. Follow the project's established Tailwind, plain CSS, CSS-in-JS, token, and component conventions.
+
+### 3. Use Domain Skills as the Sources of Truth
+
+Before reviewing, confirm that all six owning skills below are available. Load and apply every available owner. In `quick` mode, inspect all six domains but spend depth only where the primary flow has evidence. In `full` mode, complete each available domain review before consolidation.
+
+Review in this order so foundational failures are not hidden by polish:
+
+1. `better-accessibility`
+2. `better-layout`
+3. `better-writing`
+4. `better-typography`
+5. `better-colors`
+6. `better-ui`
+
+This skill owns the final response. When a domain skill is loaded through `better-interface`, apply its principles and references but ignore its standalone **Review Output Format**. Use the consolidated format, shared severity, and finding cap in this file instead.
+
+If an owning skill is unavailable, mark that domain `Not reviewed`, name the missing skill, and continue with the remaining domains. Do not recreate its rules from memory, substitute a neighboring skill, or claim holistic coverage.
+
+When two skills appear to cover the same issue, assign it to the skill that owns the underlying rule and mention secondary effects in the **Why** cell. Report it once.
+
+### 4. Require Evidence
+
+Every finding cites `path/to/file:line` and shows the current implementation. If the review artifact has no source files, cite the exact screen and component. Do not report a code-level finding from visual appearance alone or a visual finding from source code alone when runtime behavior determines the result.
+
+### 5. Rank by User Impact
+
+Use one shared severity scale:
+
+- `HIGH`: blocks a task, misleads the user, hides content or controls, causes data-loss risk, or creates a repeated systemic failure.
+- `MEDIUM`: meaningfully harms comprehension, efficiency, adaptability, or consistency.
+- `LOW`: isolated polish with limited task impact. Include only in `full` mode.
+
+Within a severity, rank by reach and leverage. A token or shared-component fix outranks the same symptom in one leaf component.
+
+### 6. Consolidate Systemic Findings
+
+One root cause is one finding. List every confirmed location in the same row rather than producing a row per occurrence. Do not pad the report to reach the finding cap; a short review or no findings is a valid result.
+
+### 7. Make Restraint Visible
+
+Record candidates considered but deliberately rejected. A candidate is rejected when the owning skill permits the current implementation, evidence is insufficient, the project convention is intentional, or the proposed change would add complexity without user benefit.
+
+### 8. Verify What Can Be Verified
+
+Run safe, relevant checks available in the project. Inspect the rendered interface when runtime behavior or visual judgment matters. Report the exact command or interaction and observed result. If a check cannot be run, label it **Not verified** and state what remains; never convert a verification gap into a finding.
+
+### 9. Review Without Mutating by Default
+
+Treat a review request as read-only. Do not edit source code unless the user also asks to implement the findings. When implementation is requested, preserve the consolidated report as the change scope and re-run the relevant verification afterward.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Six disconnected domain reports | Consolidate into one ranked findings table |
+| Same issue reported by multiple skills | Assign it to the skill that owns the underlying rule |
+| Finding with no exact location | Cite `path/to/file:line` and the current implementation |
+| Visual claim inferred only from source | Inspect the rendered state or mark it not verified |
+| Unlimited low-impact polish | Respect the mode cap; omit `LOW` findings in `quick` |
+| Silent gaps in coverage | Show which domains and states were actually inspected |
+| Missing owning skill silently treated as covered | Mark the domain `Not reviewed` and name the unavailable skill |
+| No rejected candidates | Include the required considered-but-rejected table |
+| Review silently edits code | Stay read-only unless implementation was requested |
+| “Approve” with pending actionable findings | Use `Needs changes` or `Block` |
+
+## Review Output Format
+
+Always use the following sections.
+
+### Scope and Coverage
+
+State the mode, exact scope, stack and styling conventions, and any review boundary. Then show coverage:
+
+| Domain | Evidence inspected | Result |
+| --- | --- | --- |
+| Accessibility | Files, components, states, or checks | Findings count or `Clear` |
+
+Include all six domains. `Clear` means inspected with no actionable finding; `Not reviewed` must explain why.
+
+### Findings
+
+Use one table ordered by severity, then reach and leverage:
+
+| # | Severity | Domain | Location | Before | After | Why |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | HIGH | Accessibility | `src/Dialog.tsx:42` | `<button><XIcon /></button>` | Add `aria-label="Close"` and hide the icon from the accessibility tree | The icon-only control has no accessible name |
+
+Each row is one root cause. The **Domain** value is the owning skill without the `better-` prefix. Respect the mode's finding cap. If there are no findings, omit the table and state "No actionable interface findings."
+
+### Considered but Rejected
+
+Include 1–3 candidates in `quick` mode and 2–5 in `full` mode:
+
+| Location | Candidate | Rejected because |
+| --- | --- | --- |
+| `src/Card.tsx:28` | Increase the shadow | Existing depth matches the shared surface token; changing one card would reduce consistency |
+
+These are real candidates inspected during the review, not invented filler. If the scope genuinely contains fewer borderline candidates, include the ones that exist and say so.
+
+### Verification
+
+List each check or interaction, the exact command or steps, and the observed result. Separate checks that passed from checks marked **Not verified**.
+
+### Verdict
+
+End with exactly one:
+
+- `Block` — one or more `HIGH` findings remain.
+- `Needs changes` — only `MEDIUM` or `LOW` findings remain.
+- `Approve` — no actionable findings remain and the claimed coverage was verified.
diff --git a/.claude/skills/better-interface/agents/openai.yaml b/.claude/skills/better-interface/agents/openai.yaml
new file mode 100644
index 00000000..7f9a897b
--- /dev/null
+++ b/.claude/skills/better-interface/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Better Interface"
+  short_description: "Cross-discipline interface review"
+policy:
+  allow_implicit_invocation: false
diff --git a/.claude/skills/better-layout/SKILL.md b/.claude/skills/better-layout/SKILL.md
new file mode 100644
index 00000000..31b5b02b
--- /dev/null
+++ b/.claude/skills/better-layout/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: better-layout
+description: Layout structure for web interfaces, from grouping and alignment to reading order, progressive disclosure, and adaptive breakpoints. Use when structuring a page or component, spacing or aligning controls, deciding what collapses at small sizes, handling RTL layout direction, or reviewing frontend code for layout. Triggers on layout, spacing, alignment, grouping, negative space, whitespace, visual hierarchy, reading order, progressive disclosure, breakpoints, responsive layout, container queries, safe area, full-bleed, edge-to-edge, layout margins, RTL layout, logical properties.
+---
+
+# Layout that communicates structure
+
+Layout communicates before a single word is read: position, spacing, and alignment carry hierarchy on their own, and generous space beats decoration. A good layout also survives stress: resize it, translate it, mirror it for RTL, and it should still hold together. Apply these principles when building or reviewing UI code, and express every change in the project's existing styling system (Tailwind, plain CSS, CSS-in-JS); never introduce a second styling approach.
+
+Hit-area sizes and focus behavior are covered by the `better-accessibility` skill; visual polish (radius, shadows, animation) by the `better-ui` skill; line length and text spacing by the `better-typography` skill.
+
+Treat the numeric values below as starting points for interfaces without an established density or spacing system. Preserve deliberate platform chrome, compact professional tools, and project tokens when they remain usable under hit-area, zoom, localization, and viewport stress tests.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Grouping & Alignment](grouping-and-alignment.md) | Space vs separators, alignment edges, logical properties, importance ordering |
+| [Spacing & Adaptivity](spacing-and-adaptivity.md) | Spacing between targets, layout margins, progressive disclosure, full-bleed content, breakpoints, i18n growth |
+
+## Core Principles
+
+### 1. Group with Space, Not Lines
+
+Negative space is the primary grouping tool; background shapes second; separator lines last, only where space alone can't carry the structure. The gap between groups must be at least 2× the gap within a group (`8px` intra-group → `16px`+ inter-group), or the grouping reads as noise.
+
+### 2. Keep Controls Distinct from Content
+
+Interactive elements must look interactive: a background shape, a border, or a consistent placement zone. Never style a control identically to adjacent static text.
+
+### 3. Align to Shared Edges
+
+Pick alignment edges and stick to them; every stray edge reads as noise. Use one project spacing step for each level of subordination (`16px` is a useful default). Use logical properties (`padding-inline-start`, `margin-inline-end`) for direction-dependent layout; reserve physical left/right for genuinely physical geometry.
+
+### 4. Order by Importance
+
+The most important content sits near the top and the leading edge; reading order flows top-to-bottom, leading-to-trailing. Think in leading/trailing, not left/right.
+
+### 5. Hint at Hidden Content
+
+Progressive disclosure needs a visible affordance. Use the project's established cue; without one, let the next item peek `16–32px` past the scroll edge or show a disclosure control. Content hidden with zero cue may as well not exist.
+
+### 6. Breathing Room Between Targets
+
+Without an established density system, start with `12px` between adjacent bordered or filled controls and `24px` of clearance around borderless text- and icon-only controls. Compact layouts may use less when `better-accessibility` hit areas do not overlap and the controls remain visually distinct.
+
+### 7. Inset Buttons from the Edges
+
+In content layouts, keep full-width buttons inside the layout margins (start near `16px` inline on mobile) with a visible radius. Edge-to-edge actions are acceptable when they intentionally follow established platform or application chrome, account for safe areas, and remain distinguishable from system UI.
+
+### 8. Content Bleeds, Controls Float
+
+Backgrounds and media extend to the viewport edges; controls and text stay inside the layout margins and safe areas (`env(safe-area-inset-*)`). Sticky chrome floats above the content layer, it doesn't dam it.
+
+### 9. Hold Structure Until It Breaks
+
+Breakpoints come from the content, not device presets. Keep the expanded layout as long as it genuinely fits and collapse late; prefer container queries for component-level adaptation. Test the smallest and largest sizes first.
+
+### 10. Plan for Growth and Clipping
+
+Plan for substantial and language-dependent string growth rather than relying on a universal percentage: no fixed widths or heights on text containers, and let rows wrap. Never park critical actions where resizing or scrolling clips them; keep them reachable in the normal flow or stable chrome appropriate to the product.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Separator line where spacing would do | Remove the line, double the gap between groups |
+| `margin-left` / `padding-right` in a localizable layout | `margin-inline-start` / `padding-inline-end` |
+| Content-layout button accidentally touches the viewport | Inset within the project margins; preserve intentional platform chrome |
+| Carousel/scroller that looks complete | Let the next item peek `16–32px` past the edge |
+| Adjacent controls merge or expanded hit areas overlap | Increase the gap using the project scale; use `12px`/`24px` as starting points |
+| Breakpoints at 768/1024 because they're the defaults | Break where the content actually stops fitting |
+| Fixed-width text container sized to one language | `max-width` + wrapping; test pseudo-localization and representative locales |
+| Primary action at the clip-prone bottom of a pane | Sticky positioning or stable chrome with safe-area padding |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone layout review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` blocks content or an action at a supported viewport; `MEDIUM` harms hierarchy, reading order, or adaptability; `LOW` is isolated alignment or spacing polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current layout and an actionable replacement.
+- **Why**: name the violated principle and its effect on comprehension or adaptability.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Group with space, not lines
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Settings.tsx:41` | `border-b` on every settings row | Remove borders; use `space-y-2` within groups and `space-y-8` between groups | Spacing communicates grouping with less visual noise |
+| LOW | `src/ProfileForm.tsx:58` | `<hr>` between form sections | Replace with `mt-10` on each section heading | Section hierarchy should not depend on repeated rules |
+
+#### Align to shared edges
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Card.tsx:24` | Card text at `pl-4`, card icon at `pl-3` | Align both to the same `pl-4` edge | Shared edges create a legible structure |
+| MEDIUM | `src/Nav.css:19` | `margin-left: 16px` | `margin-inline-start: 16px` | Physical properties break direction-aware layouts |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results across the relevant viewport widths, reading order, zoom, and RTL state. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable layout findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-layout/agents/openai.yaml b/.claude/skills/better-layout/agents/openai.yaml
new file mode 100644
index 00000000..4a43b675
--- /dev/null
+++ b/.claude/skills/better-layout/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Layout"
+  short_description: "Structure, grouping, alignment and adaptive layout"
diff --git a/.claude/skills/better-layout/grouping-and-alignment.md b/.claude/skills/better-layout/grouping-and-alignment.md
new file mode 100644
index 00000000..ff84d0a6
--- /dev/null
+++ b/.claude/skills/better-layout/grouping-and-alignment.md
@@ -0,0 +1,123 @@
+# Grouping & Alignment
+
+How spacing, shapes, shared edges, and ordering communicate what belongs together and what matters most.
+
+## Group with Space, Not Lines
+
+Three tools create grouping, in order of preference:
+
+1. **Negative space**: the default. Related items sit close; unrelated items sit far apart.
+2. **Background shapes**: a card or filled container, when a group needs to read as one unit (a selectable row, a draggable card).
+3. **Separator lines**: last resort, for dense data where space would cost too much (tables, long settings lists).
+
+The structural rule: the gap between groups must be at least 2× the gap within a group. If items inside a group are `8px` apart, groups need `16px`+ between them, otherwise the eye can't tell where one group ends.
+
+```css
+/* Good: spacing alone communicates the grouping */
+.field-group { display: flex; flex-direction: column; gap: 8px; }
+.form { display: flex; flex-direction: column; gap: 24px; }
+
+/* Bad: uniform spacing plus lines to compensate */
+.form > * { margin-bottom: 12px; border-bottom: 1px solid var(--separator); }
+```
+
+```html
+<!-- Good: Tailwind -->
+<div class="space-y-6">
+  <div class="space-y-2">…field group…</div>
+  <div class="space-y-2">…field group…</div>
+</div>
+```
+
+When a separator is genuinely needed, keep it quiet: hairline width, low contrast, and never combined with a large gap (the gap already did the job).
+
+## Keep Controls Distinct from Content
+
+Interactive elements need a visual signal that they're interactive: a background, a border, an underline, or placement in a consistent control zone (toolbar, footer row). A control styled identically to static text is invisible.
+
+```html
+<!-- Bad: action looks exactly like the description text next to it -->
+<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
+
+<!-- Good: the action reads as an action -->
+<p class="text-zinc-600">Your trial ends soon.</p>
+<button class="font-medium text-blue-600">Upgrade now</button>
+```
+
+The inverse also holds: don't give static elements control styling. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
+
+## Align to Shared Edges
+
+Pick a small set of alignment edges and put everything on them; the eye tracks straight edges to scan content.
+
+- Every stray edge (an icon 2px off the text edge, a card padded differently from its neighbor) reads as noise even when nobody can name the problem.
+- Use one consistent project spacing step to express hierarchy; `16px` is a useful default when no scale exists, and deeper nesting repeats the same step.
+- Numbers in tables right-align to the trailing edge (see `better-typography` for tabular figures); text left-aligns to the leading edge.
+
+```css
+/* Good: one shared leading edge, one indent step */
+.section { padding-inline: 24px; }
+.section .child { margin-inline-start: 16px; }
+
+/* Bad: three unrelated leading edges in one column */
+.header { padding-inline-start: 20px; }
+.list-item { padding-inline-start: 14px; }
+.footer { padding-inline-start: 24px; }
+```
+
+## Logical Properties, Not Physical
+
+Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
+
+| Physical (avoid) | Logical (use) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `border-right` | `border-inline-end` |
+
+```html
+<!-- Good: Tailwind logical utilities -->
+<div class="ms-4 pe-6 text-start">…</div>
+
+<!-- Bad: breaks in RTL -->
+<div class="ml-4 pr-6 text-left">…</div>
+```
+
+Reserve physical properties for things that genuinely refer to physical screen sides regardless of language, e.g. positioning relative to a device notch, or an element that must match a physical gesture direction.
+
+When the arrangement of elements encodes progression (star ratings, step indicators, progress bars), the sequence mirrors in RTL: stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements don't. Digit order inside numbers never reverses; that and other bidi text rules live in the `better-typography` skill.
+
+## Order by Importance
+
+Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
+
+- The most important information sits near the top and the leading edge; the further down and trailing something sits, the less attention it gets.
+- Give essential information room. Don't bury the one number the user came for under rows of secondary detail; push secondary content into collapsed sections, tabs, or detail views.
+- Within a row, the identifying content (name, title) leads; metadata and actions trail.
+
+```html
+<!-- Good: primary fact first, detail demoted -->
+<div>
+  <p class="text-2xl font-semibold">$4,320.00</p>
+  <p class="text-sm text-zinc-500">Available balance</p>
+</div>
+
+<!-- Bad: the key fact is buried below the fold of the card -->
+<div>
+  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
+  <p class="text-sm">Last statement: June 30</p>
+  <p class="text-sm">Balance: $4,320.00</p>
+</div>
+```
+
+Think in **leading/trailing**, not left/right: combined with logical properties, the same hierarchy mirrors correctly in RTL locales.
+
+## Don't Overload the Entry Point
+
+The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
+
+- One primary action per view (see `better-colors` for how color enforces this).
+- Group secondary actions behind a menu once they exceed two or three.
+- Prefer a short view that links deeper over a long view that shows everything at level one.
diff --git a/.claude/skills/better-layout/spacing-and-adaptivity.md b/.claude/skills/better-layout/spacing-and-adaptivity.md
new file mode 100644
index 00000000..75c09126
--- /dev/null
+++ b/.claude/skills/better-layout/spacing-and-adaptivity.md
@@ -0,0 +1,159 @@
+# Spacing & Adaptivity
+
+Space between controls, margins against the viewport, hinting at off-screen content, and layouts that survive resizing and translation.
+
+## Breathing Room Between Targets
+
+Controls placed too close together get mis-tapped and read as one unit. When the project has no established density scale, use these starting points:
+
+| Between | Starting point |
+| --- | --- |
+| Adjacent bordered/filled controls (buttons, inputs) | `12px` |
+| Around borderless controls (text buttons, icon buttons) | `24px` |
+| Unrelated control groups | `24px`+ (2× the intra-group gap) |
+
+Borderless controls usually need more clearance because nothing marks where one target ends and the next begins; the space itself is the boundary. Compact professional tools may use less when the hit areas remain distinct and do not overlap. Preserve an established, usable density instead of expanding controls solely to match these values.
+
+```html
+<!-- Good: bordered buttons at 12px, icon buttons given room -->
+<div class="flex gap-3">
+  <button class="rounded-lg border px-4 py-2">Cancel</button>
+  <button class="rounded-lg bg-blue-600 px-4 py-2 text-white">Save</button>
+</div>
+
+<!-- Bad: three borderless icon buttons packed at 4px -->
+<div class="flex gap-1">
+  <button><TrashIcon /></button>
+  <button><ArchiveIcon /></button>
+  <button><ShareIcon /></button>
+</div>
+```
+
+WCAG target-size requirements, larger usability targets, and pseudo-element expansion are covered by the `better-accessibility` skill; these clearances are in addition, so expanded hit areas never overlap.
+
+## Inset Buttons from the Edges
+
+In content layouts, buttons pressed accidentally against the viewport can look like system chrome and clip against curved corners or gesture zones. Keep them inside the layout margins. Edge-to-edge actions remain valid when they intentionally are application/platform chrome and account for safe areas:
+
+```css
+/* Good: inset action bar */
+.action-bar {
+  padding-inline: 16px;
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+.action-bar button { width: 100%; border-radius: 12px; }
+
+/* Bad: button glued to all three edges */
+.action-bar button {
+  width: 100vw;
+  border-radius: 0;
+  position: fixed;
+  bottom: 0;
+}
+```
+
+Start near `16px` inline margin on mobile when the project has no layout token; the button can still span the full content width inside those margins.
+
+## Progressive Disclosure Needs an Affordance
+
+Hiding complexity is good; hiding it without a cue is a trap. Every piece of off-screen or collapsed content needs a visible hint that it exists. Preserve the product's established scroll indicator or disclosure pattern; use the recipes below when no clear cue exists:
+
+- **Peeking items.** In a horizontal scroller or carousel, size items so the next one peeks `16–32px` past the container edge. A row of cards that ends exactly at the edge looks complete, and nobody scrolls it.
+- **Disclosure controls.** Collapsed sections get a chevron or "Show more" control; the label states what's hidden ("Show 12 more results"), not just "More".
+- **Truncation cues.** Clamped text shows an ellipsis and a way to expand; see `better-typography` for truncation mechanics.
+
+The peeking-scroller recipe: the container's padding creates the peek, and snap points stay on the content edge.
+
+```css
+.scroller {
+  display: flex;
+  gap: 12px;
+  overflow-x: auto;
+  padding-inline: 24px;
+  scroll-padding-inline: 24px;
+  scroll-snap-type: x mandatory;
+}
+.scroller > * {
+  flex: 0 0 calc(100% - 48px - 24px); /* container minus margins minus peek */
+  scroll-snap-align: start;
+}
+```
+
+```html
+<!-- Tailwind: the 80% width keeps the next card's leading 16-32px visible -->
+<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+</div>
+```
+
+## Content Bleeds, Controls Float
+
+The two layers behave differently at the edges:
+
+- **Content layer**: backgrounds, hero media, and scrollable lists extend to the viewport edges.
+- **Control layer**: text and controls stay inside the layout margins and safe areas, floating above the content.
+
+```css
+/* Good: full-bleed media inside a constrained article */
+.article {
+  display: grid;
+  grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr;
+}
+.article > * { grid-column: 2; }
+.article > .full-bleed { grid-column: 1 / -1; }
+```
+
+Sticky headers and floating action buttons account for safe areas:
+
+```css
+.fab {
+  position: fixed;
+  inset-inline-end: calc(16px + env(safe-area-inset-right));
+  bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+## Hold Structure Until It Breaks
+
+Breakpoints belong to the content, not the device catalog:
+
+- Break where the layout actually stops fitting (when the sidebar squeezes the content below its minimum measure, when the card grid drops below a usable column width), not at `768px` because a preset says so.
+- Collapse late. A layout that keeps its expanded structure as long as it genuinely fits stays stable and familiar; premature collapsing throws away space users paid for.
+- Prefer **container queries** for components: a card should adapt to the column it's in, not to the viewport.
+
+```css
+/* Good: component adapts to its container */
+.card-list { container-type: inline-size; }
+@container (max-width: 400px) {
+  .card { grid-template-columns: 1fr; }
+}
+
+/* Bad: viewport media query breaks the card inside a narrow sidebar */
+@media (max-width: 768px) {
+  .card { grid-template-columns: 1fr; }
+}
+```
+
+Test order: the smallest supported size and the largest first (those break first), then the sizes in between.
+
+## Plan for Growth and Clipping
+
+Layouts fail in two directions: content grows, and viewports shrink.
+
+**String expansion varies substantially by language and source-string length.** Do not rely on one universal percentage. Rules:
+
+- No fixed widths sized to English labels; use `max-width` plus wrapping.
+- No fixed heights on text containers; use `min-height` if a floor is needed.
+- Buttons size themselves from their label (`padding-inline`), never a hardcoded width.
+- Test with pseudo-localization or a long-string locale before shipping.
+
+```css
+/* Good: label defines the size */
+.button { padding-inline: 16px; white-space: nowrap; }
+
+/* Bad: German will overflow or truncate */
+.button { width: 96px; overflow: hidden; }
+```
+
+**Clipping:** never park critical actions where they can be cut off: the bottom edge of a resizable pane, below the fold of a fixed-height modal, behind an expanding keyboard. Keep primary actions in stable chrome: a sticky footer with safe-area padding, or the top of the view. If a modal's content scrolls, its action row doesn't.
diff --git a/.claude/skills/better-typography/SKILL.md b/.claude/skills/better-typography/SKILL.md
new file mode 100644
index 00000000..ecfe1a26
--- /dev/null
+++ b/.claude/skills/better-typography/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: better-typography
+description: Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.
+---
+
+# Great typography
+
+Good typography is mostly restraint. A sensible scale, comfortable spacing and enough contrast beat any clever effect. A label, a table cell, a marketing headline and an article paragraph should not share one set of rules. Apply these principles when building or reviewing anything with text in it.
+
+When reviewing, read the page instead of scanning the code: squint to check the hierarchy holds, read one full paragraph for comfort, and resize the viewport to catch bad wrapping, widows and truncation at real content lengths.
+
+The words themselves (button labels, error messages, empty states) are covered by the `better-writing` skill; semantic heading structure by `better-accessibility`; spatial RTL layout and logical CSS properties by `better-layout`; rendered-pair contrast measurement and color remediation by `better-colors`. This skill owns how text renders, wraps, and behaves in mixed-direction content.
+
+**Match the project's styling system.** Before suggesting or writing any fix, check how the codebase styles things and express every change in that system: Tailwind utilities in a Tailwind project, plain declarations in CSS, CSS Modules, styled-components or StyleX. The [cheat sheet](css-cheat-sheet.md) maps each declaration to its Tailwind equivalent. Never introduce a second styling approach just to apply a typography fix.
+
+## Quick Reference
+
+| Category | When to use | Reference |
+| --- | --- | --- |
+| Choosing fonts | Font categories, pairing, formats, typeface anatomy | [choosing-fonts.md](choosing-fonts.md) |
+| Variable fonts & OpenType | Axes, weights, tabular numbers, stylistic sets | [variable-fonts-and-opentype.md](variable-fonts-and-opentype.md) |
+| Spacing & sizing | Type scale, heading hierarchy, line-height, letter-spacing, text trimming | [spacing-and-sizing.md](spacing-and-sizing.md) |
+| Wrapping & punctuation | Measure, wrapping, truncation, smart punctuation, RTL | [wrapping-and-punctuation.md](wrapping-and-punctuation.md) |
+| Details & accessibility | Underlines, selection, forms, decorative text, contrast | [details-and-accessibility.md](details-and-accessibility.md) |
+| CSS cheat sheet | Quick lookup of every property covered, with Tailwind equivalents | [css-cheat-sheet.md](css-cheat-sheet.md) |
+
+## Core Principles
+
+### 1. Serve the Right Format
+
+Use `.woff2` (Brotli compression, broadly supported) on the web. `.woff` is a fallback only for very old browsers; `.ttf` and `.otf` are raw desktop formats with no web compression. How the files are loaded is the project's own concern, this skill does not prescribe it.
+
+### 2. Properties Over Raw Tags
+
+When a CSS property exists, use it. `font-weight: 650` instead of `font-variation-settings: "wght" 650`, `font-optical-sizing: auto` instead of `"opsz"`, `font-variant-numeric: tabular-nums` instead of `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders. Reserve the raw-tag properties for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) that have no property of their own.
+
+### 3. Load Intended Weights and Styles
+
+Browsers may synthesize a requested weight or style that the active family does not provide. Prefer loading the faces the design actually uses. Set `font-synthesis: none` only after verifying that every required bold, italic, small-cap, superscript, and subscript form remains visually distinct across the complete fallback stack; disabling synthesis is not a diagnostic and must not erase emphasis.
+
+### 4. Fewer Fonts, Sizes and Weights
+
+Rarely use more than three fonts. Weight and size define hierarchy, but overusing them hurts readability quickly. Pair for contrast, not similarity: a serif headline with a sans body reads as deliberate, two near-identical sans-serifs read as a mistake. Below `18px`, stay at weight `400`+; weights under `300` are display-only (`28px`+), they disappear at text sizes.
+
+### 5. Use a Type Scale with Semantic Names
+
+Define a small set of sizes and deviate from it as little as possible. Hard-coded sizes without a system break down at scale. For solo projects, default names like `text-sm` work fine as long as the usage rules are clear. On a team, name sizes by use (`text-body-sm`), not by size, so the rules stay consistent.
+
+### 6. Heading Sizes Descend with Level
+
+Within a coherent page hierarchy, map heading levels to descending steps of the type scale: a visually subordinate heading should not accidentally overpower its parent. Adjacent levels may share a size toward the small end of the scale as long as weight or spacing keeps them distinct. Pick semantic heading elements according to `better-accessibility`; this skill controls only their visual treatment.
+
+### 7. Line-Height by Role
+
+Headings tighter, around `1.1`. Body copy `1.5` to `1.6`. Prefer unitless values so line-height scales with the font size; fixed values like `24px` do not. Tight line-height is for short text: anything that wraps to three or more lines needs at least `1.4`, even in height-constrained rows.
+
+### 8. Letter-Spacing by Size
+
+Large headings often look better with slightly negative letter-spacing. Small uppercase labels need a little positive letter-spacing so letters do not feel crowded. Body copy at reading sizes needs neither.
+
+### 9. Cap the Measure
+
+Long lines make it hard for the eye to find the next line. Cap long-form text around 60–75 characters per line. Any unit works: `65ch` measures characters directly, and a pixel or rem cap is just as good: at a `16px` body size the range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` or `max-w-2xl` fit. What matters is that a cap exists and the resulting line length sits in range.
+
+### 10. Wrap Deliberately
+
+`text-wrap: balance` distributes text evenly across lines: use it on headings. `text-wrap: pretty` avoids leaving a single short word on the final line: use it on descriptions. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read. `overflow-wrap: break-word` where long words, links or IDs could escape the container. `white-space: nowrap` on labels and badges where a line break looks broken.
+
+### 11. Tabular Numbers on Changing Values
+
+Digits have different widths by default, so timers, counters and prices shift layout as they update. Apply `font-variant-numeric: tabular-nums` to any value that changes.
+
+### 12. Truncate Without Losing Content
+
+Single line: `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap`. Multiple lines: `line-clamp`. Truncation hides content, so if the missing text matters, keep the full value reachable in a tooltip or expanded view.
+
+### 13. Write Copy Naturally, Style with CSS
+
+Store text in natural case and control presentation with `text-transform`, so redesigns never require rewriting copy. Use smart punctuation: curly quotes in prose (straight quotes in code), an en dash for ranges like `2010–2020`, an em dash to set off a thought, the single ellipsis character, `&nbsp;` to keep values like `16 px` together and `&shy;` to control where long words may break.
+
+### 14. Underlines from the Font
+
+Default underlines sit wherever the browser decides. Pull position and thickness from the font's own metrics with `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune manually with `text-decoration-thickness`, `text-underline-offset` and `text-decoration-skip-ink`. `text-decoration-style` draws the line dotted, dashed or wavy; a dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term. Unless the only thing animating is a color change, build the underline as a separate element instead of using `text-decoration`: color is the only part of a real underline that animates reliably.
+
+### 15. Inputs at 16px on Mobile
+
+iOS Safari zooms the whole page when an input's text is smaller than `16px`. Keep input text at `16px` on mobile viewports (`text-base sm:text-sm`). Avoid the `maximum-scale=1` viewport meta: Safari ignores it for pinch zoom, but every other browser honors it and blocks zooming, which fails WCAG.
+
+### 16. Size and Contrast Floors
+
+Start long-form body text near the browser default of `16px`, then judge it in the actual typeface, measure, platform, and product density. UI text can go smaller: `14px` is a useful starting point for inputs and menus (inputs still need `16px` on mobile, see principle 15), `13px` for captions, rarely below `12px`. When text appears low-contrast, use `better-colors` to measure the rendered pair and `better-accessibility` to classify the requirement; do not change colors unless asked.
+
+### 17. Font Smoothing on the Root
+
+On macOS text renders heavier than intended. Apply `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` (both covered by Tailwind's `antialiased`) once on the root layout so they cover all text.
+
+### 18. Language and Bidi Behavior
+
+Set `lang` so browsers and assistive technology choose the right pronunciation, quotes, and hyphenation. Set `dir` at the document or content boundary where direction changes, preserve digit order, and use `<bdi>` for isolated mixed-direction values when needed. Spatial mirroring and logical CSS properties belong to `better-layout`.
+
+### 19. Keep Useful Text Selectable
+
+`::selection` can carry brand into the reading experience when the selected combination stays legible. Keep text selectable by default. Use `user-select: none` only on a specific draggable or gesture-driven surface where accidental selection demonstrably interferes with the interaction; never disable selection across the interface or merely because a button label can be highlighted.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `.ttf`/`.otf` served on the web | Convert to `.woff2` |
+| `font-variation-settings: "wght"` for weight | `font-weight` (works with non-variable fallbacks) |
+| `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` |
+| Synthesized face differs from the intended design | Load the required face; disable only the verified synthesis mode without erasing emphasis |
+| Hard-coded one-off font sizes | Use the type scale |
+| Child heading visually overpowers its parent | Map that section's hierarchy to descending scale steps |
+| Heading element picked for its default size | Choose semantics with `better-accessibility`, then set the visual size in CSS |
+| `line-height: 24px` on scalable text | Unitless value (`1.5`) |
+| Full-width paragraphs | Cap around 60–75 characters per line |
+| Orphan on the last line of a paragraph | `text-wrap: pretty` |
+| Lopsided two-line heading | `text-wrap: balance` |
+| Numbers cause layout shift | `tabular-nums` |
+| Truncated text with no way to read it | Tooltip or expanded view for the full value |
+| `UPPERCASE` typed into copy | Natural case + `text-transform` |
+| Justified text in an interface | `text-align: start`; reserve justify for specific editorial layouts |
+| Underline cuts through descenders | `text-decoration-skip-ink: auto`, `from-font` metrics |
+| Inputs below `16px` zoom on iOS | `text-base sm:text-sm` |
+| Root layout omits font smoothing | Apply `antialiased` once at the root |
+| Mixed-direction value renders in the wrong order | Set the correct `lang`/`dir`; isolate the value with `<bdi>` when needed |
+| Selection disabled across application chrome | Restore selection; suppress it only on a specific interaction that conflicts with dragging or gestures |
+| Extra-info hint with no visual cue | Dotted underline via `text-decoration-style: dotted` |
+| Thin/Light weight on `14px` UI text | Weight `400`+ below `18px`; thin weights are display-only |
+| `leading-none` on a three-line card description | At least `1.4` on any text that wraps to 3+ lines |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone typography review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes text unreadable, unavailable, or structurally misleading; `MEDIUM` harms hierarchy, wrapping, or scanning; `LOW` is isolated typographic polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current typography and an actionable replacement.
+- **Why**: name the violated principle and its effect on readability or hierarchy.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Tabular numbers
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Price.tsx:17` | `<span>{price}</span>` on a live price | `<span className="tabular-nums">{price}</span>` | Proportional digits cause changing values to shift |
+| LOW | `src/numbers.css:8` | `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` | The high-level property preserves fallback behavior |
+
+#### Line-height and measure
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Article.tsx:33` | `leading-none` on a body paragraph | `leading-normal` (`1.5`–`1.6`) | Wrapped body text needs enough vertical separation |
+| MEDIUM | `src/article.css:12` | Full-width article column | `max-width` near 65 characters at `16px` | Long measures make lines hard to track |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including wrapping, hierarchy, text resizing, font loading, and dynamic-value stability when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable typography findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-typography/agents/openai.yaml b/.claude/skills/better-typography/agents/openai.yaml
new file mode 100644
index 00000000..ab3f8a08
--- /dev/null
+++ b/.claude/skills/better-typography/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Typography"
+  short_description: "Web typography from fonts to spacing and wrapping"
diff --git a/.claude/skills/better-typography/choosing-fonts.md b/.claude/skills/better-typography/choosing-fonts.md
new file mode 100644
index 00000000..fb34bb40
--- /dev/null
+++ b/.claude/skills/better-typography/choosing-fonts.md
@@ -0,0 +1,64 @@
+# Choosing fonts
+
+Choosing a typeface, the right file format and understanding why fonts look the way they do.
+
+## Choosing a typeface
+
+Font families set the tone before the specific font does.
+
+| Category | Traits | Use for |
+| --- | --- | --- |
+| Serif | Small strokes at the ends of letters guide the eye along a line | Long passages, editorial reading |
+| Sans-serif | Clean, even shapes that stay crisp at small sizes | Default for most interfaces (Helvetica, Inter, Geist) |
+| Monospace | Every glyph the same width so columns line up | Code, tables, tabular data |
+| Display | Drawn for large headlines | Marketing headlines, hero text |
+| Script | Mimics handwriting | Rare, decorative moments |
+
+CSS exposes `cursive` and `fantasy` keywords for the last two categories.
+
+"Display" in a font's name does not make it a display font. Fonts like SF Pro and Heldane ship a `Display` variant for large sizes and a `Text` variant for smaller sizes. Use the variant that matches the size you are setting.
+
+### Rules
+
+- Fewer fonts is usually better. Rarely use more than three. Marketing pages can be more expressive than apps.
+- The same applies to sizes and weights. They define hierarchy, but overusing them hurts readability quickly.
+- Pair for contrast, not similarity. A serif headline with a sans body looks like a deliberate display/reading split. Two near-identical sans-serifs look like a mistake.
+- Thin weights are display-only. Below `18px`, stay at weight `400`+; Ultralight/Thin/Light (`100`–`300`) strokes disappear at text sizes and on low-DPI screens. Reserve them for `28px`+ display text, and even there check they hold up against the background.
+
+## Font family scope
+
+Applying or reviewing typography never requires a new typeface. Use the product's existing type system unless the task explicitly asks for a type change, and do not introduce a paid or proprietary face just to satisfy a review checklist. Rendering details like font smoothing, text wrapping and tabular numbers do not override the project's chosen font family.
+
+When a type change is asked for: a system-native macOS/iOS feel comes from the system stack; a commercial face such as Helvetica Now is a brand decision and keeps a practical fallback stack.
+
+```css
+/* System-native macOS/iOS feel */
+html {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+/* Commercial brand face with safe fallbacks */
+html {
+  font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
+## Formats
+
+| Format | Notes |
+| --- | --- |
+| `.woff2` | Brotli compression, broadly supported. Use this on the web. |
+| `.woff` | Older compression. Fallback only for very old browsers. |
+| `.ttf` / `.otf` | Raw formats, no web compression, larger files. Desktop only unless there is no other option. |
+
+## Anatomy of a typeface
+
+| Term | Meaning |
+| --- | --- |
+| x-height | Height of a lowercase `x` |
+| Cap height | Height of uppercase letters |
+| Baseline | The invisible line letters sit on |
+| Ascender | Part of a letter rising above the x-height |
+| Descender | Part dropping below the baseline |
+
+These measurements are why two fonts at the same `font-size` can look like different sizes. A font with a large x-height looks bigger.
diff --git a/.claude/skills/better-typography/css-cheat-sheet.md b/.claude/skills/better-typography/css-cheat-sheet.md
new file mode 100644
index 00000000..f3d29419
--- /dev/null
+++ b/.claude/skills/better-typography/css-cheat-sheet.md
@@ -0,0 +1,65 @@
+# CSS cheat sheet
+
+One-line lookup for every typography CSS declaration covered by this skill, with the Tailwind 4 equivalent. Where no utility exists, the arbitrary-value form is shown. Pick the column that matches the project: the declaration in plain CSS, CSS Modules, styled-components or StyleX codebases, the utility in Tailwind codebases.
+
+## Font
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `font-family: sans-serif` | The sans family | `font-sans` |
+| `font-family: serif` | The serif family | `font-serif` |
+| `font-family: monospace` | The monospace family | `font-mono` |
+| `font-size` | Size from the type scale | `text-*` |
+| `font-weight` | Any value from 1 to 1000 | `font-*` |
+| `font-style: italic` | Switch to italic style | `italic` |
+| `-webkit-font-smoothing` + `-moz-osx-font-smoothing` | Smooth macOS font rendering; apply once at the root | `antialiased` |
+| `font-synthesis: none` | Disable all synthesized forms after verifying fallbacks and emphasis | `[font-synthesis:none]` |
+| `font-feature-settings` | Toggle OpenType features | `[font-feature-settings:"ss01"]` |
+| `font-variation-settings` | Tune variable font axes | `[font-variation-settings:"GRAD"_80]` |
+| `font-optical-sizing` | Adjust details per size | `[font-optical-sizing:auto]` |
+| `font-variant-caps` | Real small capitals | `[font-variant-caps:small-caps]` |
+| `font-variant-position` | Real super and subscripts | `[font-variant-position:super]` |
+| `font-variant-numeric: tabular-nums` | Equal-width digits | `tabular-nums` |
+| `font-variant-numeric: slashed-zero` | Tell 0 from O | `slashed-zero` |
+
+## Spacing and layout
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `letter-spacing` | Space between letters | `tracking-*` |
+| `line-height` | Space between lines | `leading-*` |
+| `font-kerning` | Kerning on or off | `[font-kerning:none]` |
+| `text-box: trim-both` | Trim space above and below | `[text-box:trim-both_cap_alphabetic]` |
+| `max-width` on text columns | Cap at ~60–75 characters per line | `max-w-xl` / `max-w-2xl` / `max-w-[65ch]` |
+| `text-align` | Where lines start and end | `text-start` / `text-center` |
+
+## Wrapping and overflow
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-wrap: balance` | Even out heading lines | `text-balance` |
+| `text-wrap: pretty` | Avoid orphaned words | `text-pretty` |
+| `text-overflow: ellipsis` | Ellipsis for clipped text | `truncate` |
+| `line-clamp` | Cut off after N lines | `line-clamp-*` |
+| `overflow-wrap: break-word` | Break long strings | `break-words` |
+| `white-space: nowrap` | Stop wrapping | `whitespace-nowrap` |
+| `text-transform` | Change the casing | `uppercase` / `capitalize` |
+
+## Decoration and interaction
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-decoration-line: underline` | Draw an underline | `underline` |
+| `text-decoration-color` | Underline color | `decoration-*` |
+| `text-decoration-thickness` | Underline thickness | `decoration-1` / `decoration-2` |
+| `text-underline-offset` | Push the line down | `underline-offset-*` |
+| `text-underline-position: from-font` | Underline position from the font | `[text-underline-position:from-font]` |
+| `text-decoration-style` | Dotted, dashed or wavy | `decoration-dotted` / `decoration-wavy` |
+| `text-decoration-thickness: from-font` | Underline set by the font | `decoration-from-font` |
+| `text-decoration-skip-ink` | Gaps around descenders | `[text-decoration-skip-ink:auto]` |
+| `caret-color` | Tint the text cursor | `caret-*` |
+| `user-select: none` | Suppress selection on a verified drag/gesture conflict only | `select-none` |
+| `text-shadow` | Shadow behind the letters | `text-shadow-*` |
+| `-webkit-text-stroke` | Outline the letters | `[-webkit-text-stroke:1px_black]` |
+| `background-clip: text` | Clip a background to the letters | `bg-clip-text` |
+| `initial-letter` | Size a drop cap | `[initial-letter:3]` |
diff --git a/.claude/skills/better-typography/details-and-accessibility.md b/.claude/skills/better-typography/details-and-accessibility.md
new file mode 100644
index 00000000..abe484b3
--- /dev/null
+++ b/.claude/skills/better-typography/details-and-accessibility.md
@@ -0,0 +1,109 @@
+# Details and accessibility
+
+Underlines, selection, forms, decorative text and the floors that keep everything readable.
+
+## Underlines
+
+Default underline position is browser-determined: sometimes too close, cutting through descenders or too thin. Pull position and thickness from the font's own metrics:
+
+```css
+a {
+  text-underline-position: from-font;
+  text-decoration-thickness: from-font;
+}
+```
+
+The line does not have to be solid. `text-decoration-style` can draw it dotted, dashed or wavy. A dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term:
+
+```css
+abbr {
+  text-decoration: underline dotted;
+}
+```
+
+Or tune manually:
+
+```css
+a {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+  text-decoration-color: var(--color-gray-1000);
+  transition: text-decoration-color 200ms ease-out;
+}
+
+a:hover {
+  text-decoration-color: var(--color-gray-1200);
+}
+```
+
+Unless the only thing animating is a color change, build the underline as a custom element instead of using `text-decoration`: color is the only part of a real underline that animates reliably. Animate the custom element however the effect requires.
+
+## Selection
+
+- `::selection` changes the background and color of selected text; a subtle way to embed brand. Keep the combination legible.
+- Keep text selectable by default, including application chrome; users copy labels, identifiers, errors, and values in ways the designer may not predict.
+- Use `user-select: none` only on a specific draggable or gesture-driven surface where accidental selection conflicts with the interaction. Do not apply it globally or solely to imitate native chrome.
+- `::target-text` styles the phrase a shared link scrolls to.
+- The Custom Highlight API styles ranges you pick yourself, like search matches, without extra markup.
+
+## Forms and editable text
+
+- `::placeholder` styles the hint in an empty field.
+- `caret-color` colors the blinking insertion bar. Color is about as far as caret styling goes: a fully custom caret is very difficult to build and usually not worth it unless a very specific effect calls for it.
+
+### iOS input zoom
+
+Focusing an input with text smaller than `16px` zooms the whole page (an accessibility feature: `16px` is the web default and Safari treats smaller as too hard to read while typing).
+
+```tsx
+// Good: 16px on mobile, smaller from the sm breakpoint up
+<input className="text-base sm:text-sm" type="email" />
+```
+
+Avoid the `maximum-scale=1` viewport meta as a fix: Safari ignores the cap for pinch zoom, but every other browser honors it and restricts pinch zoom, which fails WCAG 1.4.4. The responsive input size solves the zoom with no accessibility cost.
+
+## Decorative text
+
+| Property | Effect |
+| --- | --- |
+| `::first-letter` | Drop cap, widely supported |
+| `::first-line` | Styles only the first line |
+| `initial-letter` | Sizes the drop cap; limited support, no Firefox yet |
+| `background-clip: text` | Clips a background or gradient to the letter shapes |
+| `-webkit-text-stroke` | Outlines the letters; works across modern browsers despite the prefix |
+| `text-shadow` | Like `box-shadow` but follows the character shapes |
+
+If a text stroke draws lines inside the letters, that is the font: the stroke traces every contour and variable fonts usually keep overlapping shapes unmerged. Static fonts do not have this issue.
+
+## Sizes
+
+Typography must survive the reader changing it: zoom, a larger browser font size, overridden line height or letter spacing.
+
+| Text | Size |
+| --- | --- |
+| Long-form body starting point | Around `16px`, verified in the actual typeface and measure |
+| Inputs and menus starting point | Around `14px` |
+| Captions | `13px` |
+| Floor | Rarely below `12px` |
+
+When text appears low-contrast, use `better-colors` to measure the rendered foreground/background pair and `better-accessibility` to classify the applicable requirement. Changing the project's colors remains a design decision unless the user asks for remediation.
+
+## Font smoothing
+
+On macOS text renders heavier than intended. Apply font smoothing once on the root layout so it covers all text. Tailwind's `antialiased` sets both properties:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+```tsx
+<html lang="en">
+  <body class="font-sans antialiased">
+    <main>{children}</main>
+  </body>
+</html>
+```
diff --git a/.claude/skills/better-typography/spacing-and-sizing.md b/.claude/skills/better-typography/spacing-and-sizing.md
new file mode 100644
index 00000000..d270ddfb
--- /dev/null
+++ b/.claude/skills/better-typography/spacing-and-sizing.md
@@ -0,0 +1,126 @@
+# Spacing and sizing
+
+A sensible scale and comfortable spacing do more for typography than any effect.
+
+## Units
+
+| Unit | Behavior |
+| --- | --- |
+| `px` | Fixed |
+| `em` | Scales with the current font size |
+| `rem` | Scales with the root font size |
+| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
+
+## Type scale
+
+A small set of predefined sizes used across a product, deviated from as little as possible. Hard-coding sizes without a system breaks down at scale.
+
+```css
+:root {
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+}
+```
+
+There are many existing scales to pick from, or define a custom one. The Tailwind type scale (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
+
+For solo projects the default names work fine as long as there are clear rules for where each size is used. On a team, give sizes semantic names: `text-sm` tells you the size but not the use; `text-body-sm` keeps sizes consistent with clear usage rules.
+
+A role-based scale pairs each size with its line-height and weight, so a role is one decision instead of three. A solid starting point for a product interface:
+
+| Role | Size | Line-height | Weight |
+| --- | --- | --- | --- |
+| Display | `2.25rem` (36px) | `1.1` | `600` |
+| Title | `1.5rem` (24px) | `1.2` | `600` |
+| Heading | `1.125rem` (18px) | `1.3` | `600` |
+| Body | `1rem` (16px) | `1.5` | `400` |
+| Caption | `0.8125rem` (13px) | `1.4` | `400` |
+
+Emphasis within a role is one weight step up (`400` → `500`), not a size change.
+
+## Heading hierarchy
+
+Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
+
+```css
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+h3 { font-size: var(--text-lg); }
+```
+
+In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), typically centralized in a component or `@layer base` rather than repeated inline.
+
+When reviewing a page, compare the computed size of headings within each semantic section: a child that accidentally renders more prominently than its parent breaks the visual hierarchy. Deep levels may share a size when the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading should not be smaller than body text unless it is deliberately a label-style overline.
+
+Heading semantics and outline quality belong to `better-accessibility`. Pick the element from the document structure, then use this skill to make that structure visually legible; never pick a heading element for its browser-default size.
+
+## Kerning and letter-spacing
+
+- **Kerning** adjusts specific pairs like `AV` or `Ye`. It is built into the font and browsers apply it automatically. Only switch it off deliberately with `font-kerning: none`.
+- **`letter-spacing`** adds the same space between every character:
+  - Large headings often look better slightly negative.
+  - Small uppercase labels need a little positive spacing so letters do not feel crowded.
+  - Body copy needs neither.
+
+```css
+/* Good */
+.display-heading {
+  letter-spacing: -0.02em;
+}
+
+.uppercase-label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Line-height
+
+| Text | Value |
+| --- | --- |
+| Headings | ~`1.1` |
+| Body copy | `1.5`–`1.6` |
+
+Prefer unitless values: they scale with the font size, fixed values like `line-height: 24px` do not. Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding.
+
+Tight line-height is for short text. Anything that wraps to three or more lines needs at least `1.4`, even in height-constrained places like list rows and cards: a tightly-leaded paragraph is harder to read than a taller row is to fit.
+
+```css
+/* Bad: card description at heading leading */
+.card-description { line-height: 1.1; }
+
+/* Good: it wraps to 3 lines, so it reads as body text */
+.card-description { line-height: 1.4; }
+```
+
+## Text trimming with text-box
+
+Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
+
+| Keyword | Trims at |
+| --- | --- |
+| `cap` | The cap height (top) |
+| `alphabetic` | The baseline (bottom) |
+| `text` | The font's own text edge, keeping room for descenders |
+
+```css
+/* trim top and bottom */
+.badge {
+  text-box: trim-both cap alphabetic;
+}
+
+/* trim only the top */
+.heading {
+  text-box: trim-start cap;
+}
+
+/* trim only the bottom */
+.label {
+  text-box: trim-end alphabetic;
+}
+```
+
+Supported in Chromium (133+) and Safari (18.2+), not yet Firefox; treat it as progressive enhancement, where unsupported browsers keep the default leading.
diff --git a/.claude/skills/better-typography/variable-fonts-and-opentype.md b/.claude/skills/better-typography/variable-fonts-and-opentype.md
new file mode 100644
index 00000000..86d33c34
--- /dev/null
+++ b/.claude/skills/better-typography/variable-fonts-and-opentype.md
@@ -0,0 +1,105 @@
+# Variable fonts and OpenType
+
+What a font file can do beyond drawing letters, and how to reach those abilities from CSS.
+
+## Static vs variable
+
+- **Static font:** one weight and one style per file. Regular + medium + bold = three files.
+- **Variable font:** an entire range in one file. Any value in the range works, e.g. `font-weight: 589`.
+
+A variable font is not automatically better. One or two weights: static files can be smaller. Several weights, optical sizes or custom axes: a variable font usually makes more sense.
+
+## Load intended weights and styles
+
+When you use a weight or style the active family does not provide, the browser may synthesize it. Prefer loading the faces the design actually uses. Disable synthesis only after verifying the complete fallback stack and every semantic emphasis state; `none` disables weight, style, small-cap, superscript, and subscript synthesis together and can erase distinctions when the real face is unavailable.
+
+```css
+.brand-wordmark {
+  /* Safe only after this isolated treatment is verified */
+  font-synthesis: none;
+}
+```
+
+For body and interface text, keep synthesis enabled unless a verified font setup supplies every requested form. If only one mode is unwanted, use the specific longhand (`font-synthesis-weight`, `font-synthesis-style`, and related properties) instead of the blanket shorthand.
+
+## Axes
+
+Variable-font controls, each with a four-letter tag. A font only supports the axes its designer included.
+
+| Axis | Tag | Controls |
+| --- | --- | --- |
+| Weight | `wght` | Stroke thickness (like `font-weight`) |
+| Optical size | `opsz` | Details and spacing tuned for the display size |
+| Width | `wdth` | Glyph width |
+| Slant | `slnt` | Slant angle |
+| Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
+
+Inter's variable file exposes only `wght` and `opsz`.
+
+Optical sizes predate variable fonts and many fonts still ship them as separate files: Heldane Text is sturdier and more spaced for reading sizes, Heldane Display has finer details for large sizes.
+
+## Properties over axis tags
+
+When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders; `font-variation-settings` silently does nothing. Save the raw tags for custom axes with no property of their own:
+
+```css
+/* Good: common axes use the properties */
+.heading {
+  font-weight: 650;
+  font-optical-sizing: auto;
+}
+
+/* Good: custom axis with no property of its own */
+.heading-grade {
+  font-variation-settings: "GRAD" 80;
+}
+
+/* Bad: weight via raw tag breaks on fallback fonts */
+.heading {
+  font-variation-settings: "wght" 650;
+}
+```
+
+## OpenType features
+
+OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, they work the same on static and variable fonts. A font only ships the features its designer included.
+
+| Tag | Feature |
+| --- | --- |
+| `tnum` | Tabular numbers: every digit the same width |
+| `zero` | Slashed zero: `0` distinct from `O` |
+| `liga` | Ligatures: joins pairs like "fi" into one shape |
+| `ss01`–`ss20` | Stylistic sets (numbered slots) |
+| `cv01`–`cv99` | Character variants (numbered slots) |
+
+Same rule as axes: prefer the `font-variant-*` properties, reserve `font-feature-settings` for tags with no property:
+
+```css
+/* Good: common features use the properties */
+.price {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Good: slashed zero via the property too */
+.id {
+  font-variant-numeric: slashed-zero;
+}
+
+/* Good: niche feature with no property of its own */
+.logo {
+  font-feature-settings: "ss01" 1;
+}
+```
+
+Tabular numbers matter for changing values: without them each digit has a different width and the layout shifts as values update.
+
+## Small caps, superscripts, subscripts
+
+- **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
+- **Superscripts** sit above the normal line (the 2 in x²), **subscripts** below it (H₂O). Enable proper glyphs with `font-variant-position`.
+
+Both require the font to include the glyphs.
+
+## Stylistic sets and character variants
+
+`ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.
diff --git a/.claude/skills/better-typography/wrapping-and-punctuation.md b/.claude/skills/better-typography/wrapping-and-punctuation.md
new file mode 100644
index 00000000..62f634c8
--- /dev/null
+++ b/.claude/skills/better-typography/wrapping-and-punctuation.md
@@ -0,0 +1,58 @@
+# Wrapping and punctuation
+
+Where lines start, where they end, where they break and which characters they use.
+
+## Measure (line length)
+
+Long lines make it harder for the eye to find the start of the next line. For long-form text, aim for 60–75 characters per line.
+
+Any unit works. `65ch` measures characters directly (one `ch` is the width of the `0` in the current font), but a pixel or rem cap is just as good: at a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) or `max-w-2xl` (`672px`) fit. What matters is that a cap exists and the resulting line length sits in range; recheck it if the body font size changes.
+
+## Alignment
+
+`text-align` controls where each line starts and ends. `text-align: justify` stretches spaces until both edges line up; it can work in specific editorial layouts but avoid it in most interfaces.
+
+## Wrapping
+
+| Property | Use |
+| --- | --- |
+| `text-wrap: balance` | Distributes text evenly across multiple lines |
+| `text-wrap: pretty` | Avoids leaving a single short word on the final line |
+| `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
+| `white-space: nowrap` | Keeps labels and badges on one line where a break looks broken |
+
+Use `balance` on headings and `pretty` on descriptions; combined they give the best outcome. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
+
+## Truncation
+
+- Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
+- Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
+
+Truncation hides content. If the missing text matters, make the full value available elsewhere (tooltip or expanded view).
+
+## Case
+
+`text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so changing presentation never requires rewriting copy.
+
+## Smart punctuation
+
+Keyboard characters are not always the best characters:
+
+| Instead of | Use |
+| --- | --- |
+| Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
+| Hyphen in ranges | En dash: `2010–2020` |
+| Two hyphens for an aside | Em dash character |
+| Three periods `...` | The single ellipsis character `…` |
+| Regular space in `16 px` | `&nbsp;` so the value never breaks apart |
+| Uncontrolled word breaks | `&shy;` to mark where a word may break |
+
+## Internationalization
+
+- Set the `lang` attribute so browsers choose the right quotes, hyphenation and pronunciation.
+- Set `dir` at the document or content boundary where direction changes. Spatial mirroring and the logical-property table live in `better-layout`.
+
+Two refinements for mixed-direction text:
+
+- **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction, but a paragraph of three or more lines aligns to its own script's direction: an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang`/`dir` on the paragraph element handles this.
+- **Never reverse digits.** Numbers keep their digit order in every direction: a phone number or "541" reads identically in RTL. Browsers handle this via the Unicode bidi algorithm; don't fight it with manual reordering, and wrap mixed number/text values in `<bdi>` if adjacent RTL text disturbs them.
diff --git a/.claude/skills/better-ui/SKILL.md b/.claude/skills/better-ui/SKILL.md
new file mode 100644
index 00000000..fe49ed4d
--- /dev/null
+++ b/.claude/skills/better-ui/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: better-ui
+description: Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.
+---
+
+# Details that make interfaces feel better
+
+Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code.
+
+When reviewing, slow the interface down: replay motion at 10% speed in the browser's Animations panel and walk every state: hover, focus, active, loading, empty. What feels off at 10% speed is what's subtly wrong at full speed.
+
+Preserve the project's component library, tokens, and density. Match its established motion language except where a principle below prescribes an exact interaction pattern.
+
+Typography (text wrapping, font rendering, tabular numbers, spacing) is covered by the `better-typography` skill; use that for anything text-related. Accessibility (hit areas, focus states, keyboard support, ARIA, reduced motion) is covered by the `better-accessibility` skill. Layout structure (grouping, spacing between sections, breakpoints, spatial RTL) is covered by the `better-layout` skill.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Surfaces](surfaces.md) | Border radius, optical alignment, shadows, image outlines |
+| [Animations](animations.md) | Interruptible animations, enter/exit transitions, icon animations, scale on press, motion restraint |
+| [Icons](icons.md) | Icon stroke weight, states via `currentColor`, outline vs fill, sizing, RTL flipping |
+| [Performance](performance.md) | Transition specificity, `will-change` usage |
+
+## Core Principles
+
+### 1. Concentric Border Radius
+
+Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off.
+
+### 2. Optical Over Geometric Alignment
+
+When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment.
+
+### 3. Shadows for Elevation, Borders for Structure
+
+For buttons, cards, and containers whose border exists only to create depth, prefer layered transparent `box-shadow` values. Keep borders that communicate structure or state: dividers, layout separators, and selected or focus states.
+
+### 4. Interruptible Animations
+
+Use CSS transitions for interactive state changes: they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.
+
+### 5. Split and Stagger Enter Animations
+
+For an infrequent staged entrance where sequence helps communicate hierarchy, break content into semantic chunks and stagger them by ~100ms instead of animating one container. Do not stagger routine, high-frequency interactions.
+
+### 6. Subtle Exit Animations
+
+Use a small fixed `translateY` instead of full height. Exits should be softer than enters. Use `ease-out` for both enter and exit transitions.
+
+### 7. Contextual Icon Animations
+
+Animate icons with `opacity`, `scale`, and `blur` instead of toggling visibility. Use exactly these values: scale from `0.25` to `1`, opacity from `0` to `1`, blur from `4px` to `0px`. If the project has `motion` or `framer-motion` in `package.json`, match that package's import path (or the established nearby imports when both exist) and use `transition: { type: "spring", duration: 0.3, bounce: 0 }`; bounce must always be `0`. If no motion library is installed, keep both icons in the DOM (one absolute-positioned) and cross-fade with CSS transitions using `cubic-bezier(0.2, 0, 0, 1)`; this gives both enter and exit animations without any dependency.
+
+### 8. Image Outlines
+
+Add a subtle `1px` outline with low opacity to images for consistent depth. The color must be pure black in light mode (`oklch(0 0 0 / 0.1)`) and pure white in dark mode (`oklch(1 0 0 / 0.1)`), never a near-black like slate, zinc, or any tinted neutral. A tinted outline picks up the surface color underneath it and reads as dirt on the image edge.
+
+### 9. Scale on Press
+
+A subtle `scale(0.96)` on click gives buttons tactile feedback. Always use `0.96`. Never use a value smaller than `0.95`: anything below feels exaggerated. Add a `static` prop to disable it when motion would be distracting.
+
+### 10. Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations.
+
+### 11. Never Use `transition: all`
+
+Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.
+
+### 12. Use `will-change` Sparingly
+
+Only for `transform`, `opacity`, `filter`, the properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter.
+
+### 13. Match Icon Stroke to Text Weight
+
+An icon next to text carries the text's optical weight: `1.5px` stroke beside regular (400) text, `2px` beside semibold (600). One stroke weight per icon set; never mix libraries on one surface.
+
+### 14. One SVG, Recolored per State
+
+Icons use `currentColor` and get their states (hover, selected, disabled) from CSS color and opacity, never from separate assets. Outline variant is the default; fill variant marks the active state.
+
+### 15. Motion Restraint
+
+No custom animation on high-frequency interactions: the attention cost repeats on every trigger. Motion is never the only feedback channel; every animated state change also needs a static cue (color, icon, label).
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Same border radius on closely nested parent and child | Calculate `outerRadius = innerRadius + padding` |
+| Icons look off-center | Adjust optically with padding or fix SVG directly |
+| Border used only to fake elevation | Use layered `box-shadow` with transparency; keep structural and state borders |
+| Jarring staged entrance or contextual exit | Stagger infrequent entrances and keep context-preserving exits subtle |
+| Stateful icon or toggle animates its default state on page load | Add `initial={false}` to that `AnimatePresence`; preserve intentional page entrances |
+| `transition: all` on elements | Specify exact properties |
+| First-frame animation stutter | Add `will-change: transform` (sparingly) |
+| Hairline icon beside bold text | Match the stroke width to the text weight |
+| Separate icon assets per state | One `currentColor` SVG, states via CSS |
+| Filled icons everywhere | Outline as default, fill only for the active state |
+| Entrance animation on every hover or keystroke | Instant feedback or ≤150ms opacity/color transition |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone UI-polish review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes an interaction misleading, unresponsive, or repeatedly disruptive; `MEDIUM` creates a noticeable craft or consistency problem; `LOW` is isolated polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current implementation and an actionable replacement.
+- **Why**: name the violated principle and explain how it affects the interface.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Concentric border radius
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Card.tsx:28` | `rounded-xl` on card + `rounded-xl` on inner button (`p-2`) | `rounded-2xl` on card (`8 + 8 = 16`), `rounded-lg` on inner button | Nested corners should be concentric |
+| LOW | `src/card.css:11` | `border-radius: 16px` on both nested surfaces | Outer `24px`, inner `16px` with `8px` padding | Equal nested radii make the inner surface look pinched |
+
+#### Scale on press
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Button.tsx:19` | `<button className="...">` | Add `active:scale-[0.96] transition-transform` | Press feedback makes the control feel responsive |
+| MEDIUM | `src/button.css:24` | `scale(0.9)` on press | Raise to `scale(0.96)` | Anything below `0.95` feels exaggerated |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results. Walk every relevant state and inspect motion at 10% speed when animation is involved. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable UI-polish findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-ui/agents/openai.yaml b/.claude/skills/better-ui/agents/openai.yaml
new file mode 100644
index 00000000..59812d3c
--- /dev/null
+++ b/.claude/skills/better-ui/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better UI"
+  short_description: "Design engineering details for polished interfaces"
diff --git a/.claude/skills/better-ui/animations.md b/.claude/skills/better-ui/animations.md
new file mode 100644
index 00000000..59bb9a1b
--- /dev/null
+++ b/.claude/skills/better-ui/animations.md
@@ -0,0 +1,404 @@
+# Animations
+
+Interruptible animations, enter/exit transitions, contextual icon animations, and motion restraint.
+
+## Interruptible Animations
+
+Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
+
+### CSS Transitions vs. Keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes, retargets mid-animation | No, restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Fixed; retargets the value mid-flight, not the timeline | Fixed timeline, restarts from the beginning |
+
+```css
+/* Good: interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses, no jank */
+```
+
+```css
+/* Bad: keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts, feels broken */
+```
+
+**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Enter Animations: Split and Stagger
+
+Use this pattern for infrequent staged entrances where sequence helps communicate hierarchy, such as the first load of a page hero, success state, or empty state. Break a large container into semantic chunks and animate each individually. Do not stagger routine interactions such as row hovers, keystrokes, or repeated tab changes.
+
+### Step by Step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
+
+### Code Example
+
+```tsx
+// Motion (Framer Motion): staggered enter
+function PageHeader() {
+  return (
+    <motion.div
+      initial="hidden"
+      animate="visible"
+      variants={{
+        visible: { transition: { staggerChildren: 0.1 } },
+      }}
+    >
+      <motion.h1
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        Welcome
+      </motion.h1>
+
+      <motion.p
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        A description of the page.
+      </motion.p>
+
+      <motion.div
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        <Button>Get started</Button>
+      </motion.div>
+    </motion.div>
+  );
+}
+```
+
+### CSS-Only Stagger
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  filter: blur(4px);
+  animation: fadeInUp 400ms ease-out forwards;
+}
+
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 100ms; }
+.stagger-item:nth-child(3) { animation-delay: 200ms; }
+
+@keyframes fadeInUp {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+```
+
+## Exit Animations
+
+Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing; don't fight for attention.
+
+### Subtle Exit (Recommended)
+
+```tsx
+// Small fixed translateY: indicates direction without drama
+<motion.div
+  exit={{
+    opacity: 0,
+    y: -12,
+    filter: "blur(4px)",
+    transition: { duration: 0.15, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Full Exit (When Context Matters)
+
+```tsx
+// Slide fully out: use when spatial context is important
+// (e.g., a card returning to a list, a drawer closing)
+<motion.div
+  exit={{
+    opacity: 0,
+    x: "-100%",
+    transition: { duration: 0.2, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Good vs. Bad
+
+```css
+/* Good: subtle exit */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-12px);
+  transition: opacity 150ms ease-out, transform 150ms ease-out;
+}
+
+/* Bad: dramatic exit that steals focus */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-100%) scale(0.5);
+  transition: all 400ms ease-out;
+}
+
+/* Sometimes correct: remove immediately when motion adds no context */
+.item-exit {
+  display: none;
+}
+```
+
+**Key points:**
+- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
+- Keep some directional movement to indicate where the element went
+- Exit duration should be shorter than enter duration (150ms vs 300ms)
+- Use a subtle exit when it preserves spatial context. Remove immediately when motion adds no information, the interaction repeats frequently, or reduced motion is requested.
+
+## Contextual Icon Animations
+
+When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
+
+### Motion Example
+
+This example uses the `motion` package. If the project instead has `framer-motion`, import the same APIs from `"framer-motion"`; never mix an installed package with the other package's import path.
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS Transition Approach (No Motion)
+
+If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
+
+The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them: the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
+
+### Choosing Between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
+| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+
+**Rule:** Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or from `"framer-motion"` when `framer-motion` is installed. If both exist, follow the imports already used by the component or its nearest peers. If neither is present, use the CSS cross-fade pattern; don't add a dependency just for icon transitions.
+
+### When to Animate Icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+**Important:** Always use exactly these values for contextual icon animations; do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value
+
+## Scale on Press
+
+A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95`: anything below feels exaggerated. Use CSS transitions for interruptibility, so that if the user releases mid-press, it smoothly returns.
+
+Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
+
+### CSS Example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion Example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static Prop Pattern
+
+Extract the scale class into a variable and conditionally apply it based on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load, only on subsequent state changes.
+
+### When It Works
+
+```tsx
+// Good: icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for: icon swaps, toggles, tabs, segmented controls: anything that has a default state on page load.
+
+### When It Breaks
+
+Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
+
+```tsx
+// Bad: initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.
+
+## Motion Restraint
+
+Motion is a budget, not a garnish. Three rules decide whether an animation belongs at all:
+
+- **No custom animation on high-frequency interactions.** An animation on something users trigger constantly (every keystroke, every list-row hover, every tab switch in a work tool) charges its attention cost on every single trigger. Reserve expressive motion for infrequent moments (first load of a view, success states, empty states); high-frequency interactions get instant feedback or the subtlest possible transition (`opacity`/`background-color` at ≤150ms).
+- **Motion is never the only feedback channel.** Every state change an animation communicates must also be visible when the animation doesn't run: a color change, an icon swap, a label. Users with reduced motion enabled, and anyone who blinked, still need to see what happened.
+- **Brief and precise beats prominent.** If a shorter, smaller animation communicates the same thing, use it. When in doubt, cut the duration, not the clarity.
+
+```css
+/* Good: high-frequency hover gets a minimal transition */
+.row:hover {
+  background-color: var(--surface-hover);
+  transition: background-color 100ms ease-out;
+}
+
+/* Bad: every hover replays a full entrance */
+.row:hover .row-icon {
+  animation: bounceIn 500ms;
+}
+```
+
+Honoring `prefers-reduced-motion` is covered by the `better-accessibility` skill; apply it to every animation in this file.
diff --git a/.claude/skills/better-ui/icons.md b/.claude/skills/better-ui/icons.md
new file mode 100644
index 00000000..2c50e30b
--- /dev/null
+++ b/.claude/skills/better-ui/icons.md
@@ -0,0 +1,110 @@
+# Icons
+
+Icon weight, states, sizing, and direction: the details that make icons sit naturally in an interface.
+
+## Match Icon Stroke to Text Weight
+
+An icon next to text should carry the same optical weight as the text, or the pair looks mismatched: a hairline icon beside semibold text reads as broken, a heavy icon beside regular text shouts.
+
+| Adjacent text | Icon stroke width (24px grid) |
+| --- | --- |
+| Regular (400), 14–16px | `1.5px` |
+| Medium/Semibold (500–600) | `2px` |
+| Bold (700), or emphasized standalone | `2.5px` |
+
+```html
+<!-- Good: stroke tuned to the label weight -->
+<button class="flex items-center gap-2 font-semibold">
+  <PlusIcon stroke-width="2" class="size-4" />
+  New project
+</button>
+
+<!-- Bad: default 1.5px stroke against a bold label -->
+<button class="flex items-center gap-2 font-bold">
+  <PlusIcon stroke-width="1.5" class="size-4" />
+  New project
+</button>
+```
+
+Two related consistency rules:
+
+- **One optical strategy per surface.** Do not mix icon libraries with incompatible stroke conventions on one toolbar. If the chosen library intentionally supports stroke variants, match them to adjacent text as above; otherwise preserve the set's native stroke and use size or color for emphasis.
+- **Size icons relative to the text's cap height**, typically `1em`–`1.25em` when inline with text, so the pair scales together.
+
+## One SVG, Recolored per State
+
+Never ship separate icon assets for default/hover/selected/disabled states. Use a single SVG drawn with `currentColor` and let CSS state drive the color:
+
+```html
+<!-- Good: one asset, states are CSS -->
+<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
+```
+
+```css
+.icon-button { color: oklch(0.552 0.016 285.938); }
+.icon-button:hover { color: oklch(0.21 0.006 285.885); }
+.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
+.icon-button:disabled { opacity: 0.4; }
+```
+
+```html
+<!-- Tailwind -->
+<button class="text-zinc-500 hover:text-zinc-900 aria-pressed:text-blue-600 disabled:opacity-40">
+  <BookmarkIcon />
+</button>
+```
+
+Hardcoded fills inside the SVG (`fill="#666"`) break this; strip them to `currentColor` when importing icons.
+
+## Outline Default, Fill Active
+
+When an icon set offers outline and filled variants, use them as a state pair, not interchangeably:
+
+| Variant | Use for |
+| --- | --- |
+| Outline | Default state: toolbars, list rows, inline with text |
+| Fill | Selected/active state: the active tab, a toggled bookmark, a liked heart |
+
+```tsx
+// Good: variant communicates state
+<TabIcon variant={isActive ? "solid" : "outline"} />
+
+// Bad: filled icons everywhere, so the active tab has no state signal
+<TabIcon variant="solid" />
+```
+
+The swap between variants is a contextual icon animation; use the exact cross-fade values in [animations.md](animations.md).
+
+## Design at Render Size
+
+An icon that looks great at 48px can collapse into mush at 16px. Details that read at large sizes (thin interior lines, tight counters, fine texture) blur or alias when small.
+
+- Test every icon at the smallest size it will render (often `16px`); it must stay recognizable there.
+- Prefer simplified glyphs for small contexts over scaling down detailed artwork.
+- Keep icons on the pixel grid at their render size: a 16px icon drawn on a 24px grid with fractional scaling renders soft. Use the icon set's native grid sizes (`16`, `20`, `24`) rather than arbitrary scales.
+- Always SVG, never raster, so the same asset stays crisp at every density.
+
+## Icons in RTL
+
+Under `dir="rtl"`, flip icons whose meaning is tied to reading direction, and leave the rest alone:
+
+| Flip | Don't flip |
+| --- | --- |
+| Back/forward arrows, chevrons in navigation | Logos and brand marks |
+| Text-block glyphs (alignment, lists, indent) | Checkmarks |
+| Speaker/volume waves (emanate in reading direction) | Physical objects: clocks, cups, pencils |
+| "Send" style directional glyphs | Media playback (play/rewind refer to tape direction, convention keeps them LTR) |
+
+```css
+/* Good: mirror only direction-dependent icons */
+[dir="rtl"] .icon-directional {
+  scale: -1 1;
+}
+```
+
+```html
+<!-- Tailwind -->
+<ChevronRightIcon class="icon-directional rtl:-scale-x-100" />
+```
+
+Analyze composite icons part by part: a badge or slash overlay may keep its position even when the base glyph flips. Accessible names for icon-only buttons are covered by the `better-accessibility` skill.
diff --git a/.claude/skills/better-ui/performance.md b/.claude/skills/better-ui/performance.md
new file mode 100644
index 00000000..3c397616
--- /dev/null
+++ b/.claude/skills/better-ui/performance.md
@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition Only What Changes
+
+Never use `transition: all` or Tailwind's `transition-all`. Always specify the exact properties that change. (Tailwind's bare `transition` maps to a curated default list of colors, opacity, shadow and transforms, not to `all`; still prefer naming exactly what changes.)
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS Example
+
+```css
+/* Good: only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad: transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good: explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad: transition all
+<button className="transition-all duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` Note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate`, so it covers all transform-related properties, not just `transform`. Use this when you're only animating transforms. For multiple non-transform properties, use the bracket syntax: `transition-[scale,opacity,filter]`.
+
+## Use `will-change` Sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it, the browser promotes the element only when the animation starts; that one-time layer promotion can cause a micro-stutter on the first frame.
+
+This particularly helps when an element is changing `scale`, `rotation`, or moving around with `transform`. For other properties, it doesn't help much: the browser can't composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good: specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good: multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad: never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad: properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful Properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Newer Chromium only | Rarely; not reliable cross-browser |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to Skip
+
+Modern browsers are already good at optimizing on their own. Only add `will-change` when you notice first-frame stutter; Safari in particular benefits from it. Don't add it preemptively to every animated element; each extra compositing layer costs memory.
diff --git a/.claude/skills/better-ui/surfaces.md b/.claude/skills/better-ui/surfaces.md
new file mode 100644
index 00000000..04762eb0
--- /dev/null
+++ b/.claude/skills/better-ui/surfaces.md
@@ -0,0 +1,219 @@
+# Surfaces
+
+Border radius, optical alignment, shadows, and image outlines.
+
+## Concentric Border Radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
+
+### Example
+
+```css
+/* Good: concentric radii */
+.card {
+  border-radius: 20px; /* 12 + 8 */
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+
+/* Bad: same radius on both */
+.card {
+  border-radius: 12px;
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+// Good: outer radius accounts for padding
+<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
+  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad: same radius on both
+<div className="rounded-xl p-2">
+  <div className="rounded-xl">          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched border radii on closely nested surfaces is a common source of visual tension. Calculate concentrically when the layers share a visible, even inset; preserve an established component token when the layers are independent or the padding is intentionally asymmetric.
+
+## Optical Alignment
+
+When geometric centering looks off, align optically instead.
+
+### Buttons with Text + Icon
+
+When an icon makes otherwise symmetric padding look unbalanced, use slightly less padding on the icon side. A useful starting point is:
+`icon-side padding = text-side padding - 2px`.
+
+```css
+/* Good: less padding on icon side */
+.button-with-icon {
+  padding-inline-start: 16px;
+  padding-inline-end: 14px; /* trailing icon side = text side - 2px */
+}
+
+/* Bad: equal padding looks like icon is pushed too far right */
+.button-with-icon {
+  padding-inline: 16px;
+}
+```
+
+```tsx
+// Tailwind
+<button className="ps-4 pe-3.5 flex items-center gap-2">
+  <span>Continue</span>
+  <ArrowRightIcon />
+</button>
+```
+
+### Play Button Triangles
+
+Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
+
+```css
+/* Good: optically centered */
+.play-button svg {
+  transform: translateX(2px); /* physical correction to the glyph itself */
+}
+
+/* Bad: geometrically centered but looks off */
+.play-button svg {
+  /* no adjustment */
+}
+```
+
+### Asymmetric Icons (Stars, Arrows, Carets)
+
+Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
+
+```tsx
+// Best: fix in the SVG itself
+// Adjust the viewBox or path to visually center the icon
+
+// Fallback: adjust with margin
+<span className="translate-x-px">
+  <StarIcon />
+</span>
+```
+
+## Shadows Instead of Borders
+
+For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds: solid border colors don't work well on backgrounds other than the ones they were designed for.
+
+**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
+
+### Shadow as Border (Light Mode)
+
+The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0px 0px 0px 1px oklch(0 0 0 / 0.06),
+    0px 1px 2px -1px oklch(0 0 0 / 0.06),
+    0px 2px 4px 0px oklch(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0px 0px 0px 1px oklch(0 0 0 / 0.08),
+    0px 1px 2px -1px oklch(0 0 0 / 0.08),
+    0px 2px 4px 0px oklch(0 0 0 / 0.06);
+}
+```
+
+### Shadow as Border (Dark Mode)
+
+In dark mode, simplify to a single white ring, since layered depth shadows aren't visible on dark backgrounds:
+
+```css
+/* Dark mode: adapt to whatever setup the project uses
+   (prefers-color-scheme, class, data attribute, etc.) */
+--shadow-border: 0 0 0 1px oklch(1 0 0 / 0.08);
+--shadow-border-hover: 0 0 0 1px oklch(1 0 0 / 0.13);
+```
+
+### Usage with Hover Transition
+
+Apply the variable and add `transition-[box-shadow]` for a smooth hover:
+
+```css
+.card {
+  box-shadow: var(--shadow-border);
+  transition-property: box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-border-hover);
+}
+```
+
+### When to Use Shadows vs. Borders
+
+| Use shadows | Use borders |
+| --- | --- |
+| Cards, containers with depth | Dividers between list items |
+| Buttons with bordered styles | Table cell boundaries |
+| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
+| Elements on varied backgrounds | Hairline separators in dense UI |
+| Hover/focus states for lift effect | |
+
+## Image Outlines
+
+Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
+
+### Color rules (non-negotiable)
+
+- **Light mode**: pure black, `oklch(0 0 0 / 0.1)`.
+- **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`.
+- Never use a near-black or near-white from the project palette (e.g. slate-900, zinc-900, `#0a0a0a`, `#111827`, `#f5f5f7`). Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
+- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
+
+### Light Mode
+
+```css
+img {
+  outline: 1px solid oklch(0 0 0 / 0.1);
+  outline-offset: -1px; /* draw the ring just inside the image edge */
+}
+```
+
+### Dark Mode
+
+```css
+img {
+  outline: 1px solid oklch(1 0 0 / 0.1);
+  outline-offset: -1px;
+}
+```
+
+### Tailwind with Dark Mode
+
+```tsx
+<img
+  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+  src={src}
+  alt={alt}
+/>
+```
+
+Use `outline-black/10` and `outline-white/10` specifically, not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
+
+**Why outline instead of border?** `outline` never affects layout (no added width or height at any offset), and `outline-offset: -1px` draws the ring just inside the image edge so it hugs the corner radius instead of sitting outside it.
diff --git a/.claude/skills/better-writing/SKILL.md b/.claude/skills/better-writing/SKILL.md
new file mode 100644
index 00000000..eb8dea42
--- /dev/null
+++ b/.claude/skills/better-writing/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: better-writing
+description: >-
+  UX writing and interface copy, from voice and button labels to error messages and empty states. Use when writing or reviewing any user-facing text: button and link labels, form errors, placeholders, settings labels, onboarding flows, notifications, or empty states. Triggers on UX writing, microcopy, interface copy, product copy, copywriting, button labels, link text, error messages, empty states, placeholder text, settings labels, capitalization, title case, sentence case, voice and tone.
+---
+
+# Writing that disappears into the interface
+
+Clear and brief beats clever, consistency beats variety, and the best error message is the interaction redesigned so the error can't happen. Apply these principles when writing or reviewing any user-facing text.
+
+How copy renders (capitalization via `text-transform`, truncation, smart punctuation) is covered by the `better-typography` skill; error markup and announcements (`aria-invalid`, live regions) by the `better-accessibility` skill; room for translated strings by the `better-layout` skill.
+
+## Core Principles
+
+### 1. Recon the Existing Voice
+
+Before writing or reviewing, inspect nearby interface copy, the product's terminology, localization conventions, and any voice or content style guide. Preserve intentional brand character when it remains clear and appropriate to the stakes. Treat a difference from generic plain language as a finding only when it creates inconsistency, ambiguity, translation risk, or an inappropriate tone.
+
+### 2. One Voice, Flexible Tone
+
+The product has one voice, established by its existing system rather than invented during a local edit. Keep terms consistent: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
+
+| Context | Tone |
+| --- | --- |
+| Success, onboarding, empty states | Warm, can be light |
+| Routine actions, settings | Neutral, minimal |
+| Errors, destructive confirmations | Calm, plain, zero playfulness |
+| Data loss, security | Serious, explicit |
+
+### 3. Address the Reader Directly
+
+In instructional interface copy, address the reader directly as "you" rather than "the user." Avoid “we” in errors when it creates ambiguity or reads as deflection: prefer “Unable to load content” over “We're having trouble loading this content.” Preserve an established first-person brand voice in low-stakes contexts when it remains clear. Use possessives sparingly (“Favorites” over “Your Favorites”) and never switch perspective accidentally.
+
+### 4. Plain Words Over Clever Ones
+
+Choose easily understood words and delete every word that isn't needed. No idioms, colloquialisms, or humor that won't translate. Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible. Never build sentences by concatenating fragments around variables (`"You have " + n + " new messages"`); word order changes per language, so use full templated strings with proper pluralization.
+
+### 5. Verb-First Buttons
+
+Button labels start with a verb naming the specific action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or bare "Yes"/"No" on consequential actions. Confirmation buttons repeat the consequence so the dialog is answerable without reading the body: "Delete this project?" offers `Delete project` and `Cancel`, not `Yes` and `No`.
+
+### 6. Consistent Flow Vocabulary
+
+Multi-step flows use one vocabulary: "Get Started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms across steps makes users wonder if the buttons do different things.
+
+### 7. Links Describe Their Destination
+
+Link text makes sense out of context; screen-reader users navigate by a list of the page's links. "Read the billing docs", never "Click here" (which also fails the device-verb rule on touch), and never a bare "Learn more" when several appear on one page. Suffix each: "Learn more about exports".
+
+### 8. One Capitalization Policy
+
+Pick title case or sentence case per element type (all buttons, all headings) and apply it consistently; sentence case is the safer default: calmer, no per-word case rules, localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
+
+### 9. Settings Describe the ON State
+
+Label a toggle for what happens when it's on: "Send read receipts", and users infer the off state. Never label the negative ("Don't send read receipts"), which turns the toggle into a double negative. Link directly to a referenced setting instead of describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
+
+### 10. Errors Say How to Fix, Next to Where It Broke
+
+An error is an instruction, adjacent to the failing field:
+
+| Bad | Good |
+| --- | --- |
+| That password is too short | Choose a password with at least 8 characters |
+| Invalid name | Use only letters for your name |
+| Oops! Something went wrong. | Unable to save. Check your connection and try again. |
+
+No blame, no "oops", no exclamation marks. Phrase hints positively ("Use only letters", not "Don't use numbers or symbols") and show them before the mistake, not after. If the same error keeps firing for many users, redesign the interaction instead of rewording it.
+
+### 11. Empty States Point Forward
+
+An empty state says what this place is and how to fill it, with one clear next action:
+
+```html
+<!-- Bad: a shrug -->
+<p>No results.</p>
+
+<!-- Good: orientation plus a next step -->
+<p class="font-medium">No projects yet</p>
+<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
+<button class="mt-4">Create a project</button>
+```
+
+Search and filter empty states name the query and offer an exit: "No results for 'quarterly'. Clear filters". Never park crucial persistent information in an empty state; it disappears the moment content exists.
+
+### 12. Placeholders Are Examples, Not Labels
+
+Placeholders show the expected format (`name@example.com`, `DD/MM/YYYY`). A placeholder is never the field's only label: it vanishes on input, and every field keeps a visible label.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Local rewrite ignores the product's established terminology or voice | Inspect nearby copy and the style guide before proposing a change |
+| "The user" in instructional interface copy | Address the reader directly as "you" |
+| "We're having trouble…" obscures responsibility or recovery | Use a direct status and next step: "Unable to load content" |
+| `OK` / `Yes` confirming a destructive dialog | Repeat the consequence: "Delete project" |
+| "Continue" on step 2, "Next" on step 3 | One flow vocabulary throughout |
+| "Click here" or bare "Learn more" link | Describe the destination: "Read the billing docs" |
+| "Save Changes" beside "Discard changes" | One capitalization policy per element type |
+| "Don't send read receipts" toggle | Label the ON state: "Send read receipts" |
+| "Oops! Something went wrong." | Say what to do, next to the failing field |
+| "No results." as the whole empty state | Orient and point forward with a next action |
+| Placeholder doing the label's job | Visible label; placeholder shows the format |
+| `"You have " + n + " messages"` | Full templated strings with pluralization |
+
+## Review Output Format
+
+Use this format only when the user asks for a standalone writing review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
+
+Present the standalone review in two parts.
+
+### Findings
+
+Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` misleads users, obscures a consequence, or prevents recovery; `MEDIUM` makes a task harder to understand; `LOW` is isolated voice or consistency polish.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: quote the current copy and its complete replacement.
+- **Why**: name the violated principle and explain the comprehension or trust cost.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
+
+### Example
+
+#### Errors say how to fix
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/PasswordField.tsx:36` | "Invalid password" | "Choose a password with at least 8 characters" | The error must say how to fix the problem |
+| HIGH | `src/Editor.tsx:81` | "We couldn't process your request" toast | Inline "Unable to save. Check your connection and try again." | The current message neither locates the failure nor offers recovery |
+
+#### Verb-first buttons
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| HIGH | `src/DeleteDialog.tsx:29` | "OK" on the delete confirmation | "Delete project" | A consequential action must repeat the consequence |
+| MEDIUM | `src/Signup.tsx:54` | "Let's go!" | "Create account" | The label must name the action |
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact checks run and their observed results, including the complete flow, variable interpolation, pluralization, and narrow-width wrapping when applicable. If a check was not run, state what still needs verification.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.
+
+When there are no findings, omit the tables, state "No actionable writing findings", report verification, and end with `Approve`.
diff --git a/.claude/skills/better-writing/agents/openai.yaml b/.claude/skills/better-writing/agents/openai.yaml
new file mode 100644
index 00000000..89ab41ec
--- /dev/null
+++ b/.claude/skills/better-writing/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Writing"
+  short_description: "UX writing, interface copy and microcopy"
diff --git a/AGENTS.md b/AGENTS.md
index 9d102bf6..31f587b4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,3 +34,55 @@ what it does — and if the API reads it, declare it in
 Anything a self-hoster might not have is optional, and the code must work
 without it: a missing key removes a capability, it never throws. See
 `apps/agent/agent/lib/capabilities.ts` for the pattern.
+
+
+## Median Tasks
+
+Median can use a project-local workspace binding. If this repository has
+`.median/config.json`, run `mdn` commands from inside this repository so the
+correct Median workspace profile is selected. The local config stores only a
+profile name; API keys stay in your user config.
+
+To bind this repository to a workspace:
+
+```
+mdn setup --local
+```
+
+Before starting work, check your assigned tasks:
+
+```
+mdn tasks --agent <your-agent-name>
+```
+
+When picking up a task:
+
+```
+mdn status <TASK-CODE> in_progress --agent <your-agent-name>
+```
+
+When completing a task:
+
+```
+mdn status <TASK-CODE> ready --agent <your-agent-name>
+```
+
+To create a new task:
+
+```
+mdn create --title "Description" --status todo --priority medium --agent <your-agent-name>
+```
+
+## Commit Messages & Pull Requests
+
+Always include the Median task ID in commit messages and PR titles so tasks get marked automatically.
+
+```
+git commit -m "MDN-42 fix: resolve auth token expiry"
+```
+
+For pull requests, include the task ID in the title:
+
+```
+MDN-42 fix: resolve auth token expiry
+```
diff --git a/CLAUDE.md b/CLAUDE.md
index 43c994c2..16f00e26 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,53 @@
 @AGENTS.md
+
+
+## Median Tasks
+
+Median can use a project-local workspace binding. If this repository has
+`.median/config.json`, run `mdn` commands from inside this repository so the
+correct Median workspace profile is selected. The local config stores only a
+profile name; API keys stay in your user config.
+
+To bind this repository to a workspace:
+
+```
+mdn setup --local
+```
+
+Before starting work, check your assigned tasks:
+
+```
+mdn tasks --agent <your-agent-name>
+```
+
+When picking up a task:
+
+```
+mdn status <TASK-CODE> in_progress --agent <your-agent-name>
+```
+
+When completing a task:
+
+```
+mdn status <TASK-CODE> ready --agent <your-agent-name>
+```
+
+To create a new task:
+
+```
+mdn create --title "Description" --status todo --priority medium --agent <your-agent-name>
+```
+
+## Commit Messages & Pull Requests
+
+Always include the Median task ID in commit messages and PR titles so tasks get marked automatically.
+
+```
+git commit -m "MDN-42 fix: resolve auth token expiry"
+```
+
+For pull requests, include the task ID in the title:
+
+```
+MDN-42 fix: resolve auth token expiry
+```
diff --git a/skills-lock.json b/skills-lock.json
index aed6bf51..280b310f 100644
--- a/skills-lock.json
+++ b/skills-lock.json
@@ -7,12 +7,60 @@
       "skillPath": "skills/ai-elements/SKILL.md",
       "computedHash": "6d7ccc65b98adb04d6c47632746dbfea55528903de9b027f6b39b80983d5aa55"
     },
+    "ai-sdk": {
+      "source": "vercel/ai",
+      "sourceType": "github",
+      "skillPath": "skills/use-ai-sdk/SKILL.md",
+      "computedHash": "dfce60b0f2749991e000123526e298d5ede1c8353d837e71886fb3c8e5f8b730"
+    },
+    "better-accessibility": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-accessibility/SKILL.md",
+      "computedHash": "a7b0b70403af4625052410d239a8683b35221efbf6b61b396110ce000da05e26"
+    },
     "better-auth-best-practices": {
       "source": "better-auth/skills",
       "sourceType": "github",
       "skillPath": "better-auth/best-practices/SKILL.md",
       "computedHash": "61ba0ef64ed2e7c424401cc848ca33dd6d790a720c44727717dc0c5cba5fc122"
     },
+    "better-colors": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-colors/SKILL.md",
+      "computedHash": "094fbf1d8e31d225179f5d3ca80246b08b3dd9154f4058d7ee86a95e1139e563"
+    },
+    "better-interface": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-interface/SKILL.md",
+      "computedHash": "90e23bcfdea67e937a17ce43d91467f67ab71120803161ba0c2dabeb47066cd7"
+    },
+    "better-layout": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-layout/SKILL.md",
+      "computedHash": "e4eda446af4127a9b0ea97f0cc1e7c77cc1120b91fce25e3947af5e0884b74e5"
+    },
+    "better-typography": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-typography/SKILL.md",
+      "computedHash": "bbe024b4a78a56cd08b6d2e90d53bf268b559262c20665a440931645ed1861d4"
+    },
+    "better-ui": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-ui/SKILL.md",
+      "computedHash": "3d745409bc2de890c04c110ea9d43a305b33abb500a5c664f26d44774a02c79f"
+    },
+    "better-writing": {
+      "source": "jakubkrehel/skills",
+      "sourceType": "github",
+      "skillPath": "skills/better-writing/SKILL.md",
+      "computedHash": "450dc38b88fc7207044bf918e52a29422ad7a3de71517119cfd12fb65c7b05ee"
+    },
     "eve": {
       "source": "vercel/eve",
       "sourceType": "github",

From 7cdd3153aab25083457eb79b7328a64ba76d696c Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 11:07:33 -0700
Subject: [PATCH 2/7] CMP-1 feat: build durable custom agents

---
 apps/agent/agent/channels/crm.ts              | 132 ++-
 apps/agent/agent/hooks/audit.ts               | 122 ++-
 apps/agent/agent/instructions.md              | 116 +-
 apps/agent/agent/instructions/task.ts         |  31 +-
 apps/agent/agent/lib/builder-runtime.ts       | 411 +++++++
 apps/agent/agent/lib/context-dev.ts           |  30 +-
 apps/agent/agent/lib/custom-agent-dispatch.ts | 413 ++++++++
 apps/agent/agent/lib/research-instructions.ts |  26 +
 apps/agent/agent/lib/run-runtime.ts           | 395 +++++++
 apps/agent/agent/lib/session-purpose.ts       |  42 +
 apps/agent/agent/schedules/dispatch.ts        |  45 +-
 .../agent/subagents/agent_builder/agent.ts    |  17 +
 .../subagents/agent_builder/instructions.md   |  29 +
 .../agent_builder/sandbox/sandbox.ts          |   9 +
 .../agent_builder/tools/ask_question.ts       |   3 +
 .../subagents/agent_builder/tools/bash.ts     |   3 +
 .../subagents/agent_builder/tools/glob.ts     |   3 +
 .../subagents/agent_builder/tools/grep.ts     |   3 +
 .../agent_builder/tools/inspect_context.ts    |  16 +
 .../agent_builder/tools/read_file.ts          |   3 +
 .../agent_builder/tools/save_agent_draft.ts   |  45 +
 .../subagents/agent_builder/tools/todo.ts     |   3 +
 .../agent_builder/tools/web_fetch.ts          |   3 +
 .../agent_builder/tools/web_search.ts         |   3 +
 .../agent_builder/tools/write_file.ts         |   3 +
 .../agent/subagents/agent_runner/agent.ts     |  29 +
 .../subagents/agent_runner/instructions.md    |  22 +
 .../subagents/agent_runner/sandbox/sandbox.ts |   9 +
 .../agent_runner/tools/ask_question.ts        |   3 +
 .../subagents/agent_runner/tools/bash.ts      |   3 +
 .../agent_runner/tools/create_crm_activity.ts |  20 +
 .../agent_runner/tools/finish_run.ts          |  16 +
 .../subagents/agent_runner/tools/glob.ts      |   3 +
 .../subagents/agent_runner/tools/grep.ts      |   3 +
 .../agent_runner/tools/inspect_run.ts         |  13 +
 .../subagents/agent_runner/tools/query_crm.ts |  17 +
 .../agent_runner/tools/read_crm_record.ts     |  16 +
 .../subagents/agent_runner/tools/read_file.ts |   3 +
 .../subagents/agent_runner/tools/todo.ts      |   3 +
 .../subagents/agent_runner/tools/web_fetch.ts |   3 +
 .../agent_runner/tools/web_search.ts          |   3 +
 .../agent_runner/tools/write_file.ts          |   3 +
 apps/agent/agent/tools/enrich_company.ts      |   4 +-
 apps/agent/agent/tools/fetch_contact_photo.ts |   4 +-
 apps/agent/agent/tools/identify_contact.ts    |   4 +-
 apps/agent/agent/tools/record_fact.ts         |   4 +-
 apps/agent/agent/tools/record_job_change.ts   |   4 +-
 apps/agent/agent/tools/schedule_recheck.ts    |   4 +-
 apps/agent/agent/tools/set_contact_socials.ts |   4 +-
 apps/agent/agent/tools/write_brief.ts         |   4 +-
 .../agent/tools/write_workspace_profile.ts    |   4 +-
 apps/agent/test/custom-agent-runtime.spec.ts  |  63 ++
 apps/agent/test/verify-key.spec.ts            |  14 +
 apps/api/src/agent/agent-access.service.ts    |  61 ++
 .../src/agent/agent-definitions.service.ts    | 349 ++++++
 apps/api/src/agent/agent-runs.service.ts      | 192 ++++
 apps/api/src/agent/agent-trigger.service.ts   |  14 +-
 apps/api/src/agent/agent.module.ts            |  16 +-
 apps/api/src/agent/agents.contracts.ts        |  27 +
 apps/api/src/agent/agents.router.ts           | 107 ++
 apps/api/src/app.module.ts                    |   2 +
 .../conversation-sharing.service.ts           | 165 +++
 .../conversations/conversations.contracts.ts  |  52 +-
 .../src/conversations/conversations.module.ts |  10 +-
 .../src/conversations/conversations.router.ts |  72 ++
 .../conversations/conversations.service.ts    | 507 ++++++++-
 apps/api/src/generated/server.ts              |  73 +-
 apps/api/test/conversations.spec.ts           |  32 +
 .../app/(app)/(agent-builder)/agent/page.tsx  |   5 +
 .../(agent-builder)/agents/[agentId]/page.tsx |  27 +
 .../app/(app)/(agent-builder)/agents/page.tsx |  21 +
 .../(agent-builder)/agents/team/page.tsx      |   8 +
 .../(agent-builder)/chat/[chatId]/page.tsx    |  21 +
 apps/app/app/(app)/(agent-builder)/layout.tsx |  21 +
 apps/app/app/eve/v1/[...path]/route.ts        |  32 +
 .../agent-builder/agent-builder-chat.tsx      | 999 ++++++++++++++++++
 .../agent-builder/agent-builder-home.tsx      |  95 ++
 .../agent-builder/agent-builder-shell.tsx     |  10 +
 .../agent-builder/agent-builder-sidebar.tsx   | 209 ++++
 .../agent-builder/agent-composer.tsx          | 416 ++++++++
 .../agent-builder/share-chat-dialog.tsx       | 225 ++++
 .../agent-builder/team-agent-detail.tsx       | 573 ++++++++++
 .../agent-builder/team-agents-index.tsx       |  83 ++
 apps/app/components/app-icon-rail.tsx         | 125 ++-
 .../components/crm/agent-conversations.tsx    |   2 +-
 apps/app/components/crm/agent-panel.tsx       |  34 +-
 apps/app/lib/agent-builder.ts                 |  15 +
 apps/app/lib/agent-transcript.ts              |  50 +
 apps/app/next.config.ts                       |  12 +
 apps/app/test/agent-builder.spec.ts           |  28 +
 apps/app/test/agent-transcript.spec.ts        |  53 +
 docs/environment.md                           |  12 +-
 .../migration.sql                             | 290 +++++
 .../migration.sql                             |   8 +
 packages/db/prisma/schema.prisma              | 396 ++++++-
 packages/ui/src/components/bubble.tsx         |   2 +-
 96 files changed, 7419 insertions(+), 220 deletions(-)
 create mode 100644 apps/agent/agent/lib/builder-runtime.ts
 create mode 100644 apps/agent/agent/lib/custom-agent-dispatch.ts
 create mode 100644 apps/agent/agent/lib/research-instructions.ts
 create mode 100644 apps/agent/agent/lib/run-runtime.ts
 create mode 100644 apps/agent/agent/lib/session-purpose.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/agent.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/instructions.md
 create mode 100644 apps/agent/agent/subagents/agent_builder/sandbox/sandbox.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/ask_question.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/bash.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/glob.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/grep.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/inspect_context.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/read_file.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/todo.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/web_fetch.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/web_search.ts
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/write_file.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/agent.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/instructions.md
 create mode 100644 apps/agent/agent/subagents/agent_runner/sandbox/sandbox.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/ask_question.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/bash.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/create_crm_activity.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/finish_run.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/glob.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/grep.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/inspect_run.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/query_crm.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/read_crm_record.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/read_file.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/todo.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/web_fetch.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/web_search.ts
 create mode 100644 apps/agent/agent/subagents/agent_runner/tools/write_file.ts
 create mode 100644 apps/agent/test/custom-agent-runtime.spec.ts
 create mode 100644 apps/api/src/agent/agent-access.service.ts
 create mode 100644 apps/api/src/agent/agent-definitions.service.ts
 create mode 100644 apps/api/src/agent/agent-runs.service.ts
 create mode 100644 apps/api/src/agent/agents.contracts.ts
 create mode 100644 apps/api/src/agent/agents.router.ts
 create mode 100644 apps/api/src/conversations/conversation-sharing.service.ts
 create mode 100644 apps/app/app/(app)/(agent-builder)/agent/page.tsx
 create mode 100644 apps/app/app/(app)/(agent-builder)/agents/[agentId]/page.tsx
 create mode 100644 apps/app/app/(app)/(agent-builder)/agents/page.tsx
 create mode 100644 apps/app/app/(app)/(agent-builder)/agents/team/page.tsx
 create mode 100644 apps/app/app/(app)/(agent-builder)/chat/[chatId]/page.tsx
 create mode 100644 apps/app/app/(app)/(agent-builder)/layout.tsx
 create mode 100644 apps/app/components/agent-builder/agent-builder-chat.tsx
 create mode 100644 apps/app/components/agent-builder/agent-builder-home.tsx
 create mode 100644 apps/app/components/agent-builder/agent-builder-shell.tsx
 create mode 100644 apps/app/components/agent-builder/agent-builder-sidebar.tsx
 create mode 100644 apps/app/components/agent-builder/agent-composer.tsx
 create mode 100644 apps/app/components/agent-builder/share-chat-dialog.tsx
 create mode 100644 apps/app/components/agent-builder/team-agent-detail.tsx
 create mode 100644 apps/app/components/agent-builder/team-agents-index.tsx
 create mode 100644 apps/app/lib/agent-builder.ts
 create mode 100644 apps/app/test/agent-builder.spec.ts
 create mode 100644 packages/db/prisma/migrations/20260803210000_agent_builder_foundation/migration.sql
 create mode 100644 packages/db/prisma/migrations/20260804160000_agent_conversation_command_type/migration.sql

diff --git a/apps/agent/agent/channels/crm.ts b/apps/agent/agent/channels/crm.ts
index 44d686ac..077c167b 100644
--- a/apps/agent/agent/channels/crm.ts
+++ b/apps/agent/agent/channels/crm.ts
@@ -1,8 +1,18 @@
 import { EnrichmentStatus } from "@crm/db";
 import { defineChannel, POST } from "eve/channels";
 import { verifyKey } from "../lib/context-dev";
+import {
+	builderIdFromToken,
+	dispatchAgentRun,
+	dispatchBuilderSubmission,
+	drainAgentRuns,
+	drainBuilder,
+	failRun,
+	runIdFromToken,
+} from "../lib/custom-agent-dispatch";
 import { brief, drainAll, taskAuth } from "../lib/dispatch";
 import { settle } from "../lib/enrichment";
+import { finishRun } from "../lib/run-runtime";
 import { completeTask, taskSubject } from "../lib/tasks";
 
 const TASK_MARKER = "task:";
@@ -47,6 +57,30 @@ export default defineChannel({
 			return new Response(null, { status: 202 });
 		}),
 
+		POST(
+			"/internal/crm/builder-dispatch",
+			async (request, { send, waitUntil }) => {
+				if (!authorised(request)) {
+					return new Response("Unauthorized", { status: 401 });
+				}
+
+				waitUntil(drainBuilder(send));
+				return new Response(null, { status: 202 });
+			},
+		),
+
+		POST(
+			"/internal/crm/agent-dispatch",
+			async (request, { send, waitUntil }) => {
+				if (!authorised(request)) {
+					return new Response("Unauthorized", { status: 401 });
+				}
+
+				waitUntil(drainAgentRuns(send));
+				return new Response(null, { status: 202 });
+			},
+		),
+
 		POST("/internal/crm/verify-key", async (request) => {
 			if (!authorised(request)) {
 				return new Response("Unauthorized", { status: 401 });
@@ -71,29 +105,107 @@ export default defineChannel({
 	],
 
 	events: {
+		async "message.completed"(data, channel) {
+			const conversationId = builderIdFromToken(channel.continuationToken);
+			if (!conversationId || !data.message?.trim()) return;
+
+			await import("@crm/db").then(({ db }) =>
+				db.agentConversation.updateMany({
+					where: { id: conversationId, kind: "BUILDER" },
+					data: {
+						lastAssistantAt: new Date(),
+						lastMessageAt: new Date(),
+						messageCount: { increment: 1 },
+					},
+				}),
+			);
+		},
+
 		async "session.waiting"(_data, channel) {
 			const taskId = taskFromToken(channel.continuationToken);
-			if (!taskId) return;
+			if (taskId) {
+				const subject = await completeTask(taskId, "ran");
+				if (subject) await settle(subject, EnrichmentStatus.COMPLETE);
+				return;
+			}
 
-			const subject = await completeTask(taskId, "ran");
-			if (subject) await settle(subject, EnrichmentStatus.COMPLETE);
+			const conversationId = builderIdFromToken(channel.continuationToken);
+			if (!conversationId) return;
+
+			await import("@crm/db").then(({ db }) =>
+				db.agentConversation.updateMany({
+					where: { id: conversationId, kind: "BUILDER" },
+					data: { continuationToken: channel.continuationToken },
+				}),
+			);
 		},
 
 		async "turn.failed"(data, channel) {
 			const taskId = taskFromToken(channel.continuationToken);
-			if (!taskId) return;
-
 			const reason =
-				typeof data === "object" && data && "error" in data
-					? String((data as { error: unknown }).error)
-					: "The research turn failed.";
+				typeof data === "object" && data && "message" in data
+					? String((data as { message: unknown }).message)
+					: "The agent turn failed.";
+
+			if (taskId) {
+				const subject = await taskSubject(taskId);
+				if (subject) await settle(subject, EnrichmentStatus.FAILED, reason);
+				return;
+			}
 
-			const subject = await taskSubject(taskId);
-			if (subject) await settle(subject, EnrichmentStatus.FAILED, reason);
+			const runId = runIdFromToken(channel.continuationToken);
+			if (runId) await failRun(runId, "TURN_FAILED", reason);
+		},
+
+		async "session.completed"(_data, channel) {
+			const runId = runIdFromToken(channel.continuationToken);
+			if (!runId) return;
+
+			const { db } = await import("@crm/db");
+			const run = await db.agentRun.findUnique({
+				where: { id: runId },
+				select: { status: true, summary: true },
+			});
+			if (run?.status === "RUNNING") {
+				await finishRun(runId, {
+					summary: run.summary ?? "The agent run completed.",
+				});
+			}
+		},
+
+		async "session.failed"(data, channel) {
+			const conversationId = builderIdFromToken(channel.continuationToken);
+			if (conversationId) {
+				const { db } = await import("@crm/db");
+				await db.agentConversation.updateMany({
+					where: { id: conversationId, kind: "BUILDER" },
+					data: {
+						continuationToken: channel.continuationToken,
+						lastAssistantAt: new Date(),
+						lastMessageAt: new Date(),
+					},
+				});
+				return;
+			}
+
+			const runId = runIdFromToken(channel.continuationToken);
+			if (runId) await failRun(runId, data.code, data.message);
 		},
 	},
 
 	async receive(input, { send }) {
+		const builderSubmissionId =
+			typeof input.target?.builderSubmissionId === "string"
+				? input.target.builderSubmissionId
+				: null;
+		if (builderSubmissionId) {
+			return dispatchBuilderSubmission(builderSubmissionId, send);
+		}
+
+		const runId =
+			typeof input.target?.runId === "string" ? input.target.runId : null;
+		if (runId) return dispatchAgentRun(runId, send);
+
 		const taskId =
 			typeof input.target?.taskId === "string" ? input.target.taskId : null;
 
diff --git a/apps/agent/agent/hooks/audit.ts b/apps/agent/agent/hooks/audit.ts
index a574b0aa..d4753870 100644
--- a/apps/agent/agent/hooks/audit.ts
+++ b/apps/agent/agent/hooks/audit.ts
@@ -1,6 +1,7 @@
-import { db } from "@crm/db";
+import { db, type Prisma } from "@crm/db";
 import { defineHook } from "eve/hooks";
 import { currentFocus } from "../lib/focus";
+import { attribute, purposeOf } from "../lib/session-purpose";
 
 export default defineHook({
 	events: {
@@ -10,6 +11,8 @@ export default defineHook({
 			if (!id) return;
 
 			try {
+				const data = ("data" in event ? (event.data ?? {}) : {}) as object;
+				const emittedAt = event.meta?.at ? new Date(event.meta.at) : new Date();
 				await db.agentEvent.createMany({
 					data: [
 						{
@@ -17,12 +20,20 @@ export default defineHook({
 							sessionId: ctx.session.id,
 							contactId: currentFocus().contactId,
 							type: event.type,
-							data: ("data" in event ? (event.data ?? {}) : {}) as object,
-							emittedAt: event.meta?.at ? new Date(event.meta.at) : new Date(),
+							data,
+							emittedAt,
 						},
 					],
 					skipDuplicates: true,
 				});
+
+				const purpose = purposeOf(ctx);
+				if (purpose === "builder") {
+					await persistBuilderLifecycle(event, ctx.session.id, ctx);
+				}
+				if (purpose === "team-agent") {
+					await persistRunEvent(id, event.type, data, emittedAt, ctx);
+				}
 			} catch (error) {
 				console.warn("[audit] could not record event", {
 					type: event.type,
@@ -32,3 +43,108 @@ export default defineHook({
 		},
 	},
 });
+
+async function persistBuilderLifecycle(
+	event: { type: string },
+	sessionId: string,
+	ctx: Parameters<typeof purposeOf>[0],
+) {
+	const conversationId = attribute(ctx, "conversationId");
+	if (!conversationId) return;
+
+	if (event.type === "session.started") {
+		await db.agentConversation.updateMany({
+			where: { id: conversationId, kind: "BUILDER" },
+			data: { sessionId, continuationToken: null },
+		});
+	}
+
+	if (event.type === "message.received") {
+		const submissionId = attribute(ctx, "submissionId");
+		if (submissionId) {
+			await db.agentConversationSubmission.updateMany({
+				where: { id: submissionId, conversationId },
+				data: { status: "ACCEPTED", acceptedAt: new Date() },
+			});
+		}
+	}
+}
+
+async function persistRunEvent(
+	eventId: string,
+	type: string,
+	data: object,
+	emittedAt: Date,
+	ctx: Parameters<typeof purposeOf>[0] & { session: { id: string } },
+) {
+	const runId = attribute(ctx, "runId");
+	if (!runId) return;
+
+	const run = await db.agentRun.update({
+		where: { id: runId },
+		data: {
+			nextEventSequence: { increment: 1 },
+			...(type === "session.started"
+				? {
+						sessionId: ctx.session.id,
+						status: "RUNNING",
+						startedAt: new Date(),
+					}
+				: {}),
+		},
+		select: { nextEventSequence: true },
+	});
+
+	await db.agentRunEvent.createMany({
+		data: [
+			{
+				id: eventId,
+				runId,
+				sequence: run.nextEventSequence,
+				type,
+				data: data as Prisma.InputJsonValue,
+				emittedAt,
+			},
+		],
+		skipDuplicates: true,
+	});
+
+	if (type === "step.completed") {
+		const usage = recordOf(data).usage;
+		const values = recordOf(usage);
+		await db.agentRun.update({
+			where: { id: runId },
+			data: {
+				...(numberOf(values.inputTokens) !== null
+					? { inputTokens: { increment: numberOf(values.inputTokens) ?? 0 } }
+					: {}),
+				...(numberOf(values.outputTokens) !== null
+					? { outputTokens: { increment: numberOf(values.outputTokens) ?? 0 } }
+					: {}),
+				...(numberOf(values.costUsd) !== null
+					? { costUsd: { increment: numberOf(values.costUsd) ?? 0 } }
+					: {}),
+			},
+		});
+	}
+
+	if (type === "message.completed") {
+		const message = recordOf(data).message;
+		if (typeof message === "string" && message.trim()) {
+			await db.agentRun.update({
+				where: { id: runId },
+				data: { summary: message.slice(0, 1000) },
+			});
+		}
+	}
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function numberOf(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
diff --git a/apps/agent/agent/instructions.md b/apps/agent/agent/instructions.md
index 4aa0ab64..90381f98 100644
--- a/apps/agent/agent/instructions.md
+++ b/apps/agent/agent/instructions.md
@@ -1,111 +1,9 @@
-# CRM research agent
+# Comp AI CRM agent runtime
 
-You work out who the people in our CRM are, what the companies are, and where
-the deals stand — so a rep opens a record already knowing what they are dealing
-with.
+You are the durable Eve runtime behind Comp AI CRM. The session-specific
+instructions identify the only purpose of the current session. Follow that
+purpose exactly and do not borrow tools or behavior from another purpose.
 
-## The one rule
-
-**Never write a fact you have not read from a source.**
-
-Most contacts here arrived as an email address and a guess.
-`pmarchetti@fernhill.com` became a contact called "Pmarchetti" because that is what the
-address looks like title-cased. Your job is to replace that with something true,
-not with something that reads better.
-
-A confidently wrong fact is worse than a missing one, because nobody can tell it
-is wrong. If you cannot confirm something, leave it. That is a successful
-outcome.
-
-## How this works
-
-You do not assert confidence — you report **evidence**, and the ledger scores
-it. `record_fact` takes what you *saw* ("their signature block says Head of
-Security"), decides what that is worth, and either writes the record or offers a
-rep a suggestion. Strong evidence writes. Weak evidence becomes a question for a
-human. Both are the system working.
-
-So there is nothing to argue with and no bar to clear by trying harder. Report
-what you found, accurately, and move on.
-
-## The record you were opened on
-
-Every session starts from one record, and your session instructions say which
-and give you its id. Read that record before anything else:
-
-| Opened on | Start with            |
-| --------- | --------------------- |
-| a person  | `read_crm_history`    |
-| a company | `read_company_history`|
-| a deal    | `read_deal_history`   |
-
-All three are free — our own database, no vendor, no budget — and they are the
-best evidence in the system besides.
-
-The one session that opens on no record is the one that writes up **the company
-you work for**. Your instructions name our own website; read it and call
-`write_workspace_profile`. Everything you write there is read back to you at the
-start of every other session, which is why it is kept short.
-
-## The three records are joined, and so are your tools
-
-A contact works somewhere. A company has people and deals. A deal has a company
-and the people on it. **You can always get from any one to the others**, and
-each read hands you the ids to do it:
-
-- `read_crm_history` returns the contact's **company id** and the deals they are
-  on.
-- `read_company_history` returns **every contact there, with their ids**, and
-  every deal.
-- `read_deal_history` returns the company and everyone attached, with ids.
-- `search_crm` finds any of the three by name, email address or domain.
-
-So two answers are always wrong:
-
-**"I don't have a tool that lists contacts by company."** You do. It is
-`read_company_history`, and the person asking is looking at that company.
-
-**"Could you paste the contact's name or email address?"** Never ask a rep for
-an id, and never ask them to search for you. Call `search_crm`. If it returns
-nothing, say so — that is a real answer. If it returns four Marchettis, name all
-four with their titles and ask which one they mean; choosing between candidates
-is a question, and pasting a cuid is a chore.
-
-## Where to look outside, in order
-
-1. **The CRM first, always.** A reply from their own address, a signature block,
-   a meeting they attended. No data vendor can sell us any of that.
-2. **LinkedIn** (`resolve_linkedin_profile` → `get_linkedin_profile`) for
-   identity: name, current title, employer, tenure. Self-reported, and
-   authoritative for who someone is.
-3. **The open web** (`web_search`, `web_fetch`, `research_person`,
-   `research_company`) for context: news, funding, what they have said publicly.
-   Sometimes wrong about job titles — where it disagrees with LinkedIn about
-   identity, LinkedIn wins.
-
-Search results are not evidence. A search for "Paula Marchetti" once returned
-Brightwater's CEO. A search tells you where to look.
-
-**Not every install has 2 and 3.** They each need an API key, and plenty of
-copies of this CRM run with none. Your session instructions list what this one
-has before you plan; a tool whose source is missing says so, costs nothing, and
-will say the same thing however many times you call it. This is normal, not
-broken. Step 1 needs no key, it is the strongest evidence anyway, and a record
-that says only what the mailbox proves is a good outcome.
-
-## Your budget
-
-Each session comes with a research budget, and **only vendor calls spend it**.
-Every read of our own CRM is free, however many you make. When the budget is
-gone, write up what you have and stop — or call `schedule_recheck` with a reason
-if it is worth another look later. Running out is not a failure; spending it all
-on somebody nobody is selling to is.
-
-## Skills
-
-Load these when the work calls for them, and before your first one of a session:
-
-- `identity-matching` — deciding whether a candidate really is this person.
-- `evidence` — which observation is which `kind`, and why it matters.
-- `writing-a-brief` — the Background panel a rep reads before a call.
-- `data-boundaries` — what you may read (everything) and what may leave.
+Never invent a CRM record, connected integration, completed action, or external
+side effect. Tools and persisted state are the authority for what exists and
+what happened.
diff --git a/apps/agent/agent/instructions/task.ts b/apps/agent/agent/instructions/task.ts
index 186ac5b3..d09a3622 100644
--- a/apps/agent/agent/instructions/task.ts
+++ b/apps/agent/agent/instructions/task.ts
@@ -1,10 +1,23 @@
 import { defineDynamic, defineInstructions } from "eve/instructions";
 import { focusOn, setBudget } from "../lib/focus";
 import { sessionPreamble } from "../lib/preamble";
+import { RESEARCH_INSTRUCTIONS } from "../lib/research-instructions";
+import { attribute, purposeOf } from "../lib/session-purpose";
 
 export default defineDynamic({
 	events: {
 		"session.started": async (_event, ctx) => {
+			const purpose = purposeOf(ctx);
+			if (purpose === "builder") {
+				return builderInstructions(ctx);
+			}
+
+			if (purpose === "team-agent") {
+				return defineInstructions({
+					markdown: `This is one background run of a deployed team agent. Call agent_runner exactly once and pass the run id from your user message. Do not call research tools or perform work yourself. Relay the specialist's factual completion summary. Never claim an external action that the specialist did not log.`,
+				});
+			}
+
 			const attributes = ctx.session.auth.current?.attributes ?? {};
 			const budget = asNumber(attributes.budget);
 			const kind = asString(attributes.taskKind);
@@ -27,11 +40,27 @@ export default defineDynamic({
 
 			focusOn({ ...focus, sessionId: ctx.session.id });
 
-			return defineInstructions({ markdown });
+			return defineInstructions({
+				markdown: `${RESEARCH_INSTRUCTIONS}\n\n${markdown}`,
+			});
 		},
+		"turn.started": (_event, ctx) =>
+			purposeOf(ctx) === "builder" ? builderInstructions(ctx) : null,
 	},
 });
 
+function builderInstructions(ctx: Parameters<typeof purposeOf>[0]) {
+	return defineInstructions({
+		markdown: builderTaskMarkdown(attribute(ctx, "commandType")),
+	});
+}
+
+export function builderTaskMarkdown(commandType: string | null): string {
+	return commandType === "CREATE_AGENT"
+		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If it asks for clarification, ask only that question. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
+		: `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. The user must explicitly run the Create agent slash command before agent creation begins. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`;
+}
+
 function asString(value: unknown): string | null {
 	return typeof value === "string" && value.trim() ? value.trim() : null;
 }
diff --git a/apps/agent/agent/lib/builder-runtime.ts b/apps/agent/agent/lib/builder-runtime.ts
new file mode 100644
index 00000000..dd436cb3
--- /dev/null
+++ b/apps/agent/agent/lib/builder-runtime.ts
@@ -0,0 +1,411 @@
+import { db, type Prisma } from "@crm/db";
+import { readAgentModel } from "@crm/db/settings";
+
+const GMAIL_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
+const CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar.readonly";
+
+export type BuilderResource = {
+	kind: "integration" | "company" | "contact" | "deal";
+	id: string;
+	label: string;
+};
+
+export type DraftTrigger = {
+	type: "MANUAL" | "SCHEDULE";
+	name: string;
+	summary: string;
+	nextRunAt?: string | null;
+	intervalMinutes?: number | null;
+};
+
+export type DraftAction = {
+	type: "crm.activity.create" | "run.summary";
+	provider: "crm";
+	summary: string;
+};
+
+export type DraftAgentInput = {
+	name: string;
+	description: string;
+	instructions: string;
+	trigger: DraftTrigger;
+	resources: BuilderResource[];
+	actions: DraftAction[];
+	access: string[];
+};
+
+export async function builderContext(conversationId: string, userId: string) {
+	const conversation = await db.agentConversation.findFirst({
+		where: { id: conversationId, userId, kind: "BUILDER" },
+		select: {
+			id: true,
+			title: true,
+			agent: {
+				select: {
+					id: true,
+					name: true,
+					description: true,
+					status: true,
+					versions: {
+						orderBy: { number: "desc" },
+						take: 1,
+						select: {
+							id: true,
+							number: true,
+							status: true,
+							manifest: true,
+							instructions: true,
+						},
+					},
+				},
+			},
+			submissions: {
+				orderBy: { createdAt: "asc" },
+				select: { id: true, message: true, createdAt: true },
+			},
+		},
+	});
+
+	if (!conversation)
+		throw new Error("This builder conversation is unavailable.");
+
+	const resources = uniqueResources(
+		conversation.submissions.flatMap((submission) =>
+			resourcesOf(submission.message),
+		),
+	);
+
+	return {
+		conversation: {
+			id: conversation.id,
+			title: conversation.title,
+		},
+		availableConnections: await connectionStatus(userId),
+		resources: await describeResources(resources),
+		existingDraft: conversation.agent,
+		now: new Date().toISOString(),
+	};
+}
+
+export async function saveBuilderDraft(
+	conversationId: string,
+	userId: string,
+	input: DraftAgentInput,
+) {
+	const conversation = await db.agentConversation.findFirst({
+		where: { id: conversationId, userId, kind: "BUILDER" },
+		select: { id: true, agentId: true },
+	});
+
+	if (!conversation)
+		throw new Error("This builder conversation is unavailable.");
+
+	const validation = await validateDraft(userId, input);
+	if (!validation.valid) {
+		return {
+			saved: false as const,
+			issues: validation.issues,
+			availableConnections: validation.connections,
+		};
+	}
+
+	const model = await readAgentModel(db);
+	const now = new Date();
+	const nextRunAt = scheduleDate(input.trigger, now);
+	const manifest = {
+		kind: "crm-team-agent",
+		trigger: {
+			type: input.trigger.type,
+			name: input.trigger.name,
+			summary: input.trigger.summary,
+			config:
+				input.trigger.type === "SCHEDULE"
+					? {
+							intervalMinutes: input.trigger.intervalMinutes,
+							nextRunAt: nextRunAt?.toISOString(),
+						}
+					: {},
+		},
+		dataScope: {
+			summary: scopeSummary(input.resources),
+			resources: input.resources,
+		},
+		actions: input.actions,
+		access: input.access,
+	};
+	const sandboxPolicy = {
+		backend: "vercel-sandbox",
+		networkPolicy: "deny-all",
+		credentials: "app-runtime-only",
+	};
+
+	return db.$transaction(async (tx) => {
+		let agentId = conversation.agentId;
+		let created = false;
+
+		if (!agentId) {
+			const agent = await tx.agentDefinition.create({
+				data: {
+					name: input.name,
+					description: input.description,
+					createdById: userId,
+				},
+				select: { id: true },
+			});
+			agentId = agent.id;
+			created = true;
+
+			await tx.agentConversation.update({
+				where: { id: conversationId },
+				data: { agentId, title: input.name },
+			});
+		} else {
+			await tx.agentDefinition.update({
+				where: { id: agentId },
+				data: { name: input.name, description: input.description },
+			});
+		}
+
+		const latest = await tx.agentVersion.findFirst({
+			where: { agentId },
+			orderBy: { number: "desc" },
+			select: { number: true },
+		});
+		const number = (latest?.number ?? 0) + 1;
+		const version = await tx.agentVersion.create({
+			data: {
+				agentId,
+				number,
+				status: "READY",
+				instructions: input.instructions,
+				manifest: manifest as Prisma.InputJsonValue,
+				modelId: model.id,
+				sandboxPolicy,
+				validation: {
+					status: "passed",
+					checkedAt: now.toISOString(),
+					capabilities: validation.capabilities,
+				},
+				sourceConversationId: conversationId,
+				createdById: userId,
+			},
+			select: { id: true, number: true, status: true },
+		});
+
+		await tx.agentTrigger.create({
+			data: {
+				agentId,
+				versionId: version.id,
+				type: input.trigger.type,
+				name: input.trigger.name,
+				config: manifest.trigger.config as Prisma.InputJsonValue,
+				createdById: userId,
+				nextRunAt,
+			},
+		});
+
+		if (created) {
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type: "agent.created",
+					summary: "Created a draft agent from a private builder chat",
+					requestId: `builder:${conversationId}`,
+				},
+			});
+		}
+
+		await tx.agentAuditEvent.create({
+			data: {
+				agentId,
+				versionId: version.id,
+				actorUserId: userId,
+				actorType: "USER",
+				actorId: userId,
+				type: "version.created",
+				summary: `Prepared version ${number} for review`,
+				requestId: version.id,
+				after: { status: "READY", validation: "passed" },
+			},
+		});
+
+		return {
+			saved: true as const,
+			agentId,
+			versionId: version.id,
+			versionNumber: version.number,
+			status: version.status,
+		};
+	});
+}
+
+async function validateDraft(userId: string, input: DraftAgentInput) {
+	const connections = await connectionStatus(userId);
+	const issues: string[] = [];
+	const capabilities = new Set(["crm.read", "crm.activity.create"]);
+
+	for (const resource of input.resources) {
+		if (resource.kind !== "integration") continue;
+		if (resource.id === "google:gmail" && !connections.gmail) {
+			issues.push("Gmail is not connected for the chat owner.");
+		}
+		if (resource.id === "google:calendar" && !connections.calendar) {
+			issues.push("Google Calendar is not connected for the chat owner.");
+		}
+		if (!resource.id.startsWith("google:")) {
+			issues.push(`${resource.label} is not an available integration.`);
+		}
+		capabilities.add(`${resource.id}.read`);
+	}
+
+	const missingRecords = await missingResourceIds(input.resources);
+	issues.push(
+		...missingRecords.map(
+			(resource) => `${resource.label} is no longer in the CRM.`,
+		),
+	);
+
+	if (input.trigger.type === "SCHEDULE") {
+		const next = Date.parse(input.trigger.nextRunAt ?? "");
+		if (!Number.isFinite(next) || next <= Date.now()) {
+			issues.push("A scheduled agent needs a future next run time.");
+		}
+		if (
+			!input.trigger.intervalMinutes ||
+			input.trigger.intervalMinutes < 1 ||
+			input.trigger.intervalMinutes > 525_600
+		) {
+			issues.push(
+				"A scheduled agent needs a recurrence from 1 minute to 1 year.",
+			);
+		}
+	}
+
+	return {
+		valid: issues.length === 0,
+		issues,
+		connections,
+		capabilities: [...capabilities],
+	};
+}
+
+async function connectionStatus(userId: string) {
+	const accounts = await db.account.findMany({
+		where: { userId, providerId: "google" },
+		select: { scope: true },
+	});
+	const scopes = new Set(
+		accounts.flatMap((account) => (account.scope ?? "").split(/[,\s]+/)),
+	);
+
+	return {
+		gmail: scopes.has(GMAIL_SCOPE),
+		calendar: scopes.has(CALENDAR_SCOPE),
+		crm: true,
+	};
+}
+
+async function describeResources(resources: BuilderResource[]) {
+	return Promise.all(
+		resources.map(async (resource) => {
+			if (resource.kind === "company") {
+				const row = await db.company.findUnique({
+					where: { id: resource.id },
+					select: { id: true, name: true, domain: true, industry: true },
+				});
+				return { ...resource, record: row };
+			}
+			if (resource.kind === "contact") {
+				const row = await db.contact.findUnique({
+					where: { id: resource.id },
+					select: {
+						id: true,
+						firstName: true,
+						lastName: true,
+						email: true,
+						title: true,
+						company: { select: { id: true, name: true } },
+					},
+				});
+				return { ...resource, record: row };
+			}
+			if (resource.kind === "deal") {
+				const row = await db.deal.findUnique({
+					where: { id: resource.id },
+					select: {
+						id: true,
+						name: true,
+						stage: true,
+						amount: true,
+						currency: true,
+						company: { select: { id: true, name: true } },
+					},
+				});
+				return {
+					...resource,
+					record: row
+						? {
+								...row,
+								amount: row.amount === null ? null : Number(row.amount),
+							}
+						: null,
+				};
+			}
+			return { ...resource, record: null };
+		}),
+	);
+}
+
+async function missingResourceIds(resources: BuilderResource[]) {
+	const described = await describeResources(
+		resources.filter((resource) => resource.kind !== "integration"),
+	);
+	return described.filter((resource) => !resource.record);
+}
+
+function resourcesOf(value: unknown): BuilderResource[] {
+	if (!value || typeof value !== "object" || !("resources" in value)) return [];
+	const resources = (value as { resources?: unknown }).resources;
+	if (!Array.isArray(resources)) return [];
+
+	return resources.flatMap((resource) => {
+		if (!resource || typeof resource !== "object") return [];
+		const row = resource as Record<string, unknown>;
+		if (
+			!["integration", "company", "contact", "deal"].includes(
+				String(row.kind),
+			) ||
+			typeof row.id !== "string" ||
+			typeof row.label !== "string"
+		) {
+			return [];
+		}
+		return [resource as BuilderResource];
+	});
+}
+
+function uniqueResources(resources: BuilderResource[]): BuilderResource[] {
+	return [
+		...new Map(
+			resources.map((resource) => [
+				`${resource.kind}:${resource.id}`,
+				resource,
+			]),
+		).values(),
+	];
+}
+
+function scheduleDate(trigger: DraftTrigger, now: Date): Date | null {
+	if (trigger.type !== "SCHEDULE") return null;
+	const parsed = new Date(trigger.nextRunAt ?? "");
+	return parsed > now ? parsed : null;
+}
+
+function scopeSummary(resources: BuilderResource[]): string {
+	if (resources.length === 0)
+		return "Workspace CRM records required by the run";
+	return resources.map((resource) => resource.label).join(" · ");
+}
diff --git a/apps/agent/agent/lib/context-dev.ts b/apps/agent/agent/lib/context-dev.ts
index 30341d47..6f093c43 100644
--- a/apps/agent/agent/lib/context-dev.ts
+++ b/apps/agent/agent/lib/context-dev.ts
@@ -99,29 +99,22 @@ export async function verifyKey(key: string): Promise<KeyCheck> {
 	}
 }
 
-/**
- * 401 is the only answer that means *this key is wrong*. Everything else that
- * came back from Context.dev — a 422 refusing the probe address, a 403 about
- * the plan, a 429, a 500 — was served *after* the key authenticated, so the
- * key is good and only the probe was refused. Anything that never reached them
- * says nothing about the key at all.
- */
 export function classifyKey(error: unknown): KeyCheck {
 	if (!(error instanceof APIError)) {
 		return { outcome: "unknown", reason: describe(error) };
 	}
 
-	if (error.status === 401) {
+	if (error.status === undefined) {
+		return { outcome: "unknown", reason: describe(error) };
+	}
+
+	if (error.status === 401 && !recognisedKeyFailure(error)) {
 		return {
 			outcome: "invalid",
 			reason: "Context did not recognise that API key.",
 		};
 	}
 
-	if (error.status === undefined) {
-		return { outcome: "unknown", reason: describe(error) };
-	}
-
 	return { outcome: "valid" };
 }
 
@@ -281,6 +274,19 @@ function errorCode(error: APIError): string | undefined {
 	return typeof body?.error_code === "string" ? body.error_code : undefined;
 }
 
+function recognisedKeyFailure(error: APIError): boolean {
+	const body = error.error as
+		| { error_code?: unknown; message?: unknown }
+		| undefined;
+	const detail = [body?.error_code, body?.message, error.message]
+		.filter((value): value is string => typeof value === "string")
+		.join(" ");
+
+	return /(usage|credit|quota|allowance|billing|rate.?limit|limit.?exceeded|insufficient.?permission)/i.test(
+		detail,
+	);
+}
+
 function describe(error: unknown): string {
 	if (error instanceof APIError) {
 		return `${error.status ?? "?"} ${errorCode(error) ?? error.message}`;
diff --git a/apps/agent/agent/lib/custom-agent-dispatch.ts b/apps/agent/agent/lib/custom-agent-dispatch.ts
new file mode 100644
index 00000000..d2c637fa
--- /dev/null
+++ b/apps/agent/agent/lib/custom-agent-dispatch.ts
@@ -0,0 +1,413 @@
+import { db } from "@crm/db";
+import type { SendFn } from "eve/channels";
+
+const BUILDER_BATCH = 20;
+const RUN_BATCH = 20;
+const MAX_BUILDER_ATTEMPTS = 3;
+const BUILDER_LEASE_MS = 5 * 60_000;
+
+export async function pendingBuilderSubmissionIds(): Promise<string[]> {
+	await recoverBuilderSubmissions();
+	const rows = await db.agentConversationSubmission.findMany({
+		where: {
+			status: "PENDING",
+			conversation: {
+				kind: "BUILDER",
+				OR: [{ sessionId: null }, { continuationToken: { not: null } }],
+			},
+		},
+		orderBy: { createdAt: "asc" },
+		take: BUILDER_BATCH * 3,
+		select: { id: true, conversationId: true },
+	});
+
+	const seen = new Set<string>();
+	return rows
+		.flatMap((row) => {
+			if (seen.has(row.conversationId)) return [];
+			seen.add(row.conversationId);
+			return [row.id];
+		})
+		.slice(0, BUILDER_BATCH);
+}
+
+export async function drainBuilder(send: SendFn): Promise<number> {
+	const ids = await pendingBuilderSubmissionIds();
+	await Promise.all(ids.map((id) => dispatchBuilderSubmission(id, send)));
+	return ids.length;
+}
+
+export async function dispatchBuilderSubmission(
+	submissionId: string,
+	send: SendFn,
+) {
+	const claimed = await db.agentConversationSubmission.updateMany({
+		where: { id: submissionId, status: "PENDING" },
+		data: {
+			status: "SENDING",
+			attemptCount: { increment: 1 },
+			sentAt: new Date(),
+			errorCode: null,
+			errorMessage: null,
+		},
+	});
+	if (claimed.count === 0)
+		throw new Error("Builder submission was already claimed.");
+
+	const submission = await db.agentConversationSubmission.findUnique({
+		where: { id: submissionId },
+		select: {
+			id: true,
+			commandType: true,
+			message: true,
+			attemptCount: true,
+			conversation: {
+				select: {
+					id: true,
+					title: true,
+					userId: true,
+					kind: true,
+				},
+			},
+		},
+	});
+	if (submission?.conversation.kind !== "BUILDER") {
+		throw new Error("Builder submission is unavailable.");
+	}
+
+	const conversationId = submission.conversation.id;
+	await db.agentConversation.update({
+		where: { id: conversationId },
+		data: { continuationToken: null },
+	});
+
+	try {
+		const session = await send(
+			builderMessage(submission.id, submission.message),
+			{
+				auth: {
+					authenticator: "crm-builder",
+					principalType: "user",
+					principalId: submission.conversation.userId,
+					attributes: {
+						purpose: "builder",
+						commandType: submission.commandType,
+						conversationId,
+						userId: submission.conversation.userId,
+						submissionId: submission.id,
+					},
+				},
+				continuationToken: builderToken(conversationId),
+				title: submission.conversation.title ?? "Agent builder",
+			},
+		);
+
+		await db.$transaction([
+			db.agentConversationSubmission.update({
+				where: { id: submission.id },
+				data: { status: "ACCEPTED", acceptedAt: new Date() },
+			}),
+			db.agentConversation.update({
+				where: { id: conversationId },
+				data: { sessionId: session.id, continuationToken: null },
+			}),
+		]);
+
+		return session;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const retry = submission.attemptCount < MAX_BUILDER_ATTEMPTS;
+		await db.$transaction([
+			db.agentConversationSubmission.update({
+				where: { id: submission.id },
+				data: {
+					status: retry ? "PENDING" : "FAILED",
+					errorCode: "DELIVERY_FAILED",
+					errorMessage: message,
+				},
+			}),
+			db.agentConversation.update({
+				where: { id: conversationId },
+				data: { continuationToken: builderToken(conversationId) },
+			}),
+		]);
+		throw error;
+	}
+}
+
+export async function queueDueAgentRuns(now = new Date()): Promise<number> {
+	const triggers = await db.agentTrigger.findMany({
+		where: {
+			enabled: true,
+			type: "SCHEDULE",
+			nextRunAt: { lte: now },
+			agent: { status: "LIVE" },
+		},
+		orderBy: { nextRunAt: "asc" },
+		take: RUN_BATCH,
+		select: {
+			id: true,
+			agentId: true,
+			versionId: true,
+			nextRunAt: true,
+			config: true,
+		},
+	});
+
+	let queued = 0;
+	for (const trigger of triggers) {
+		if (!trigger.nextRunAt) continue;
+		const intervalMinutes = intervalOf(trigger.config);
+		const nextRunAt = advance(trigger.nextRunAt, intervalMinutes, now);
+		const claimed = await db.agentTrigger.updateMany({
+			where: { id: trigger.id, nextRunAt: trigger.nextRunAt, enabled: true },
+			data: { nextRunAt, lastRunAt: trigger.nextRunAt },
+		});
+		if (claimed.count === 0) continue;
+
+		const idempotencyKey = `${trigger.id}:${trigger.nextRunAt.toISOString()}`;
+		await db.agentRun.upsert({
+			where: { idempotencyKey },
+			create: {
+				agentId: trigger.agentId,
+				versionId: trigger.versionId,
+				triggerId: trigger.id,
+				triggerType: "SCHEDULE",
+				idempotencyKey,
+				correlationId: crypto.randomUUID(),
+				input: { scheduledFor: trigger.nextRunAt.toISOString() },
+				events: { create: { sequence: 0, type: "run.queued", data: {} } },
+			},
+			update: {},
+		});
+		queued += 1;
+	}
+
+	return queued;
+}
+
+export async function pendingAgentRunIds(): Promise<string[]> {
+	const rows = await db.agentRun.findMany({
+		where: { status: "QUEUED", agent: { status: "LIVE" } },
+		orderBy: { createdAt: "asc" },
+		take: RUN_BATCH,
+		select: { id: true },
+	});
+	return rows.map((row) => row.id);
+}
+
+export async function drainAgentRuns(send: SendFn): Promise<number> {
+	await queueDueAgentRuns();
+	const ids = await pendingAgentRunIds();
+	await Promise.all(ids.map((id) => dispatchAgentRun(id, send)));
+	return ids.length;
+}
+
+export async function dispatchAgentRun(runId: string, send: SendFn) {
+	const run = await db.agentRun.findUnique({
+		where: { id: runId },
+		select: {
+			id: true,
+			status: true,
+			agentId: true,
+			versionId: true,
+			initiatedById: true,
+			agent: {
+				select: { name: true, createdById: true, status: true },
+			},
+			version: { select: { modelId: true } },
+		},
+	});
+	if (run?.status !== "QUEUED" || run.agent.status !== "LIVE") {
+		throw new Error("Agent run was already claimed or is not live.");
+	}
+
+	const claimed = await db.agentRun.updateMany({
+		where: { id: runId, status: "QUEUED" },
+		data: {
+			status: "RUNNING",
+			startedAt: new Date(),
+			modelId: run.version.modelId,
+		},
+	});
+	if (claimed.count === 0) throw new Error("Agent run was already claimed.");
+
+	const principalId = run.initiatedById ?? run.agent.createdById;
+	try {
+		const session = await send(`Execute deployed agent run ${run.id}.`, {
+			auth: {
+				authenticator: run.initiatedById ? "crm-user" : "crm-schedule",
+				principalType: run.initiatedById ? "user" : "runtime",
+				principalId,
+				attributes: {
+					purpose: "team-agent",
+					runId: run.id,
+					agentId: run.agentId,
+					versionId: run.versionId,
+					userId: principalId,
+				},
+			},
+			continuationToken: runToken(run.id),
+			title: `${run.agent.name} run`,
+			mode: "task",
+		});
+
+		await db.agentRun.update({
+			where: { id: run.id },
+			data: { sessionId: session.id },
+		});
+		return session;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		await failRun(run.id, "DELIVERY_FAILED", message);
+		throw error;
+	}
+}
+
+export async function failRun(runId: string, code: string, message: string) {
+	const run = await db.agentRun.update({
+		where: { id: runId },
+		data: {
+			status: "FAILED",
+			errorCode: code,
+			errorMessage: message,
+			finishedAt: new Date(),
+		},
+		select: { id: true, agentId: true, versionId: true },
+	});
+
+	await db.agentAuditEvent.upsert({
+		where: {
+			agentId_type_requestId: {
+				agentId: run.agentId,
+				type: "run.failed",
+				requestId: run.id,
+			},
+		},
+		create: {
+			agentId: run.agentId,
+			versionId: run.versionId,
+			actorType: "AGENT",
+			actorId: run.id,
+			type: "run.failed",
+			summary: message,
+			requestId: run.id,
+		},
+		update: { summary: message },
+	});
+}
+
+export function builderToken(conversationId: string): string {
+	return `builder:${conversationId}`;
+}
+
+export function builderIdFromToken(token: string | undefined): string | null {
+	return idFromToken(token, "builder:");
+}
+
+export function runToken(runId: string): string {
+	return `run:${runId}`;
+}
+
+export function runIdFromToken(token: string | undefined): string | null {
+	return idFromToken(token, "run:");
+}
+
+async function recoverBuilderSubmissions() {
+	const stale = new Date(Date.now() - BUILDER_LEASE_MS);
+	await db.agentConversationSubmission.updateMany({
+		where: {
+			status: "SENDING",
+			sentAt: { lt: stale },
+			attemptCount: { lt: MAX_BUILDER_ATTEMPTS },
+		},
+		data: { status: "PENDING" },
+	});
+	await db.agentConversationSubmission.updateMany({
+		where: {
+			status: "SENDING",
+			sentAt: { lt: stale },
+			attemptCount: { gte: MAX_BUILDER_ATTEMPTS },
+		},
+		data: {
+			status: "FAILED",
+			errorCode: "DELIVERY_EXHAUSTED",
+			errorMessage:
+				"The builder could not accept this message after three attempts.",
+		},
+	});
+}
+
+function builderMessage(
+	submissionId: string,
+	value: unknown,
+): Parameters<SendFn>[0] {
+	const message = recordOf(value);
+	const text = typeof message.text === "string" ? message.text : "";
+	const resources = Array.isArray(message.resources) ? message.resources : [];
+	const attachments = Array.isArray(message.attachments)
+		? message.attachments
+		: [];
+	const context = [
+		`Submission id: ${submissionId}`,
+		resources.length > 0
+			? `Tagged resources: ${resources.map(resourceLabel).filter(Boolean).join(", ")}`
+			: null,
+	]
+		.filter(Boolean)
+		.join("\n");
+	const parts: Array<Record<string, unknown>> = [
+		{ type: "text", text: `${context}\n\n${text}` },
+	];
+
+	for (const attachment of attachments) {
+		const row = recordOf(attachment);
+		if (typeof row.contentBase64 !== "string" || typeof row.type !== "string") {
+			continue;
+		}
+		parts.push({
+			type: "file",
+			data: Buffer.from(row.contentBase64, "base64"),
+			mediaType: row.type,
+		});
+	}
+
+	return parts as Parameters<SendFn>[0];
+}
+
+function resourceLabel(value: unknown): string | null {
+	const row = recordOf(value);
+	return typeof row.label === "string" ? row.label : null;
+}
+
+function intervalOf(value: unknown): number {
+	const interval = recordOf(value).intervalMinutes;
+	return typeof interval === "number" &&
+		Number.isFinite(interval) &&
+		interval >= 1
+		? Math.min(interval, 525_600)
+		: 1440;
+}
+
+function advance(from: Date, intervalMinutes: number, now: Date): Date {
+	const intervalMs = intervalMinutes * 60_000;
+	const missed = Math.max(
+		1,
+		Math.floor((now.getTime() - from.getTime()) / intervalMs) + 1,
+	);
+	return new Date(from.getTime() + missed * intervalMs);
+}
+
+function idFromToken(token: string | undefined, marker: string): string | null {
+	if (!token) return null;
+	const index = token.lastIndexOf(marker);
+	if (index === -1) return null;
+	const id = token.slice(index + marker.length);
+	return id || null;
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
diff --git a/apps/agent/agent/lib/research-instructions.ts b/apps/agent/agent/lib/research-instructions.ts
new file mode 100644
index 00000000..b29b5781
--- /dev/null
+++ b/apps/agent/agent/lib/research-instructions.ts
@@ -0,0 +1,26 @@
+export const RESEARCH_INSTRUCTIONS = `# CRM research agent
+
+Work out who the people in the CRM are, what the companies are, and where deals
+stand so a rep opens a record already knowing what they are dealing with.
+
+Never write a fact you have not read from a source. A confidently wrong fact is
+worse than a missing one. If you cannot confirm something, leave it missing.
+Report evidence through the evidence tools instead of asserting confidence.
+
+Read the record you were opened on before doing anything else. Use
+read_crm_history for a contact, read_company_history for a company, and
+read_deal_history for a deal. These CRM reads are free, authoritative, and join
+to related contacts, companies, and deals. Use search_crm when a request names a
+record without an id. Never ask a rep to find an id the CRM can resolve.
+
+Look outside the CRM only after reading internal history. Prefer LinkedIn for
+identity and the open web for context. Search results point to sources but are
+not themselves evidence. When an install lacks a vendor capability, continue
+with CRM evidence instead of treating that absence as a failure.
+
+Only vendor calls spend the session research budget. When it is gone, write up
+what you have and stop, or schedule a recheck when another look is justified.
+
+Load identity-matching before deciding whether a candidate is the same person,
+evidence before recording facts, writing-a-brief before a background brief, and
+data-boundaries before moving data outside the CRM.`;
diff --git a/apps/agent/agent/lib/run-runtime.ts b/apps/agent/agent/lib/run-runtime.ts
new file mode 100644
index 00000000..a86ead0e
--- /dev/null
+++ b/apps/agent/agent/lib/run-runtime.ts
@@ -0,0 +1,395 @@
+import { ActivityType, db, type Prisma } from "@crm/db";
+import { readCompanyHistory, readDealHistory } from "./accounts";
+import { readCrmHistory } from "./crm";
+import { searchCrm } from "./lookup";
+
+type RunResource = {
+	kind: "integration" | "company" | "contact" | "deal";
+	id: string;
+	label: string;
+};
+
+export async function runContext(runId: string) {
+	const run = await db.agentRun.findUnique({
+		where: { id: runId },
+		select: {
+			id: true,
+			status: true,
+			triggerType: true,
+			input: true,
+			agent: { select: { id: true, name: true, description: true } },
+			version: {
+				select: {
+					id: true,
+					number: true,
+					instructions: true,
+					manifest: true,
+					modelId: true,
+					sandboxPolicy: true,
+				},
+			},
+			trigger: { select: { id: true, name: true, type: true, config: true } },
+		},
+	});
+
+	if (!run) throw new Error("This agent run is unavailable.");
+
+	return {
+		...run,
+		allowedResources: manifestResources(run.version.manifest),
+		allowedActions: manifestActions(run.version.manifest),
+		now: new Date().toISOString(),
+	};
+}
+
+export async function queryRunCrm(
+	runId: string,
+	input: {
+		query: string;
+		kinds?: ("contact" | "company" | "deal")[];
+		limit: number;
+	},
+) {
+	const run = await runContext(runId);
+	const scoped = run.allowedResources.filter(
+		(resource) => resource.kind !== "integration",
+	);
+	const result = await searchCrm(input.query, input);
+	if (scoped.length === 0) return result;
+
+	const allowed = new Set(scoped.map((resource) => resource.id));
+	return {
+		...result,
+		contacts: result.contacts.filter((row) => allowed.has(row.id)),
+		companies: result.companies.filter((row) => allowed.has(row.id)),
+		deals: result.deals.filter((row) => allowed.has(row.id)),
+		total: [...result.contacts, ...result.companies, ...result.deals].filter(
+			(row) => allowed.has(row.id),
+		).length,
+	};
+}
+
+export async function readRunRecord(
+	runId: string,
+	input: {
+		kind: "contact" | "company" | "deal";
+		id: string;
+	},
+) {
+	const run = await runContext(runId);
+	assertResourceAllowed(run.allowedResources, input);
+
+	if (input.kind === "contact")
+		return readCrmHistory(input.id, { threads: 10 });
+	if (input.kind === "company") {
+		return readCompanyHistory(input.id, { threads: 10, people: 50 });
+	}
+	return readDealHistory(input.id, { threads: 10 });
+}
+
+export async function createRunActivity(
+	runId: string,
+	callId: string,
+	input: {
+		type: "NOTE" | "TASK";
+		targetKind: "company" | "contact" | "deal";
+		targetId: string;
+		subject?: string | null;
+		body?: string | null;
+		dueAt?: string | null;
+	},
+) {
+	const run = await db.agentRun.findUnique({
+		where: { id: runId },
+		select: {
+			id: true,
+			agentId: true,
+			initiatedById: true,
+			agent: { select: { createdById: true } },
+			version: { select: { manifest: true } },
+		},
+	});
+	if (!run) throw new Error("This agent run is unavailable.");
+
+	const target = await targetRecord(input.targetKind, input.targetId);
+	const idempotencyKey = `${runId}:${callId}`;
+	const existing = await db.agentAction.findUnique({
+		where: { idempotencyKey },
+		select: {
+			id: true,
+			status: true,
+			externalId: true,
+			errorMessage: true,
+		},
+	});
+	if (existing?.status === "SUCCEEDED") {
+		return {
+			actionId: existing.id,
+			activityId: existing.externalId,
+			replayed: true,
+		};
+	}
+
+	const action =
+		existing ??
+		(await db.agentAction.create({
+			data: {
+				agentId: run.agentId,
+				runId,
+				type: "crm.activity.create",
+				provider: "crm",
+				targetType: input.targetKind,
+				targetId: input.targetId,
+				targetLabel: target?.label ?? input.targetId,
+				summary:
+					input.subject?.trim() ||
+					`Create a ${input.type.toLowerCase()} on ${target?.label ?? input.targetId}`,
+				metadata: { activityType: input.type },
+				idempotencyKey,
+			},
+			select: {
+				id: true,
+				status: true,
+				externalId: true,
+				errorMessage: true,
+			},
+		}));
+
+	try {
+		assertActionAllowed(run.version.manifest, "crm.activity.create");
+		assertResourceAllowed(manifestResources(run.version.manifest), {
+			kind: input.targetKind,
+			id: input.targetId,
+		});
+		if (!target) throw new Error("The requested CRM target no longer exists.");
+		if (input.type === "TASK" && !input.subject?.trim()) {
+			throw new Error("A CRM task needs a subject.");
+		}
+
+		await db.agentAction.update({
+			where: { id: action.id },
+			data: {
+				status: "RUNNING",
+				startedAt: new Date(),
+				attemptCount: { increment: 1 },
+				errorCode: null,
+				errorMessage: null,
+			},
+		});
+
+		const activityId = `agent-action-${action.id}`;
+		const now = new Date();
+		const dueAt = input.dueAt ? new Date(input.dueAt) : null;
+		if (dueAt && Number.isNaN(dueAt.getTime()))
+			throw new Error("The due date is invalid.");
+
+		await db.$transaction(async (tx) => {
+			await tx.activity.upsert({
+				where: { id: activityId },
+				create: {
+					id: activityId,
+					type: input.type === "TASK" ? ActivityType.TASK : ActivityType.NOTE,
+					subject: input.subject?.trim() || null,
+					body: input.body?.trim() || null,
+					occurredAt: now,
+					dueAt: input.type === "TASK" ? dueAt : null,
+					companyId: target.companyId,
+					contactId: target.contactId,
+					dealId: target.dealId,
+					createdById: run.initiatedById ?? run.agent.createdById,
+					meta: {
+						source: "agent",
+						agentId: run.agentId,
+						runId,
+						actionId: action.id,
+					},
+				},
+				update: {},
+			});
+
+			if (target.companyId) {
+				await tx.company.update({
+					where: { id: target.companyId },
+					data: { lastActivityAt: now },
+				});
+			}
+			if (target.contactId) {
+				await tx.contact.update({
+					where: { id: target.contactId },
+					data: { lastActivityAt: now },
+				});
+			}
+			if (target.dealId) {
+				await tx.deal.update({
+					where: { id: target.dealId },
+					data: { lastActivityAt: now },
+				});
+			}
+
+			await tx.agentAction.update({
+				where: { id: action.id },
+				data: {
+					status: "SUCCEEDED",
+					externalId: activityId,
+					completedAt: now,
+				},
+			});
+		});
+
+		return { actionId: action.id, activityId, replayed: false };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		await db.agentAction.update({
+			where: { id: action.id },
+			data: {
+				status: "FAILED",
+				errorCode: "ACTION_REJECTED",
+				errorMessage: message,
+				completedAt: new Date(),
+			},
+		});
+		throw error;
+	}
+}
+
+export async function finishRun(
+	runId: string,
+	input: { summary: string; result?: Record<string, unknown> | null },
+) {
+	const run = await db.agentRun.update({
+		where: { id: runId },
+		data: {
+			status: "SUCCEEDED",
+			summary: input.summary,
+			result: (input.result ?? {}) as Prisma.InputJsonValue,
+			finishedAt: new Date(),
+		},
+		select: { id: true, agentId: true, versionId: true },
+	});
+
+	await db.agentAuditEvent.upsert({
+		where: {
+			agentId_type_requestId: {
+				agentId: run.agentId,
+				type: "run.completed",
+				requestId: run.id,
+			},
+		},
+		create: {
+			agentId: run.agentId,
+			versionId: run.versionId,
+			actorType: "AGENT",
+			actorId: run.id,
+			type: "run.completed",
+			summary: input.summary,
+			requestId: run.id,
+		},
+		update: { summary: input.summary },
+	});
+
+	return { id: run.id, status: "SUCCEEDED" as const };
+}
+
+function manifestResources(value: unknown): RunResource[] {
+	const manifest = recordOf(value);
+	const scope = recordOf(manifest.dataScope);
+	if (!Array.isArray(scope.resources)) return [];
+
+	return scope.resources.flatMap((resource) => {
+		if (!resource || typeof resource !== "object") return [];
+		const row = resource as Record<string, unknown>;
+		if (
+			!["integration", "company", "contact", "deal"].includes(
+				String(row.kind),
+			) ||
+			typeof row.id !== "string" ||
+			typeof row.label !== "string"
+		) {
+			return [];
+		}
+		return [resource as RunResource];
+	});
+}
+
+function manifestActions(value: unknown) {
+	const actions = recordOf(value).actions;
+	return Array.isArray(actions) ? actions.map(recordOf) : [];
+}
+
+function assertActionAllowed(manifest: unknown, type: string) {
+	if (!manifestActions(manifest).some((action) => action.type === type)) {
+		throw new Error(`Agent version does not allow ${type}.`);
+	}
+}
+
+function assertResourceAllowed(
+	resources: RunResource[],
+	input: { kind: "contact" | "company" | "deal"; id: string },
+) {
+	const records = resources.filter(
+		(resource) => resource.kind !== "integration",
+	);
+	if (records.length === 0) return;
+	if (
+		records.some(
+			(resource) => resource.kind === input.kind && resource.id === input.id,
+		)
+	) {
+		return;
+	}
+	throw new Error(
+		"That CRM record is outside this agent version's approved scope.",
+	);
+}
+
+async function targetRecord(kind: "company" | "contact" | "deal", id: string) {
+	if (kind === "company") {
+		const company = await db.company.findUnique({
+			where: { id },
+			select: { id: true, name: true },
+		});
+		return company
+			? {
+					label: company.name,
+					companyId: company.id,
+					contactId: null,
+					dealId: null,
+				}
+			: null;
+	}
+	if (kind === "contact") {
+		const contact = await db.contact.findUnique({
+			where: { id },
+			select: { id: true, firstName: true, lastName: true, companyId: true },
+		});
+		return contact
+			? {
+					label: [contact.firstName, contact.lastName]
+						.filter(Boolean)
+						.join(" "),
+					companyId: contact.companyId,
+					contactId: contact.id,
+					dealId: null,
+				}
+			: null;
+	}
+
+	const deal = await db.deal.findUnique({
+		where: { id },
+		select: { id: true, name: true, companyId: true },
+	});
+	return deal
+		? {
+				label: deal.name,
+				companyId: deal.companyId,
+				contactId: null,
+				dealId: deal.id,
+			}
+		: null;
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
diff --git a/apps/agent/agent/lib/session-purpose.ts b/apps/agent/agent/lib/session-purpose.ts
new file mode 100644
index 00000000..c39d3113
--- /dev/null
+++ b/apps/agent/agent/lib/session-purpose.ts
@@ -0,0 +1,42 @@
+export type SessionPurpose = "builder" | "team-agent" | "research";
+
+type PurposeContext = {
+	readonly session: {
+		readonly auth: {
+			readonly current: {
+				readonly attributes: Readonly<Record<string, unknown>>;
+			} | null;
+			readonly initiator: {
+				readonly attributes: Readonly<Record<string, unknown>>;
+			} | null;
+		};
+	};
+};
+
+export function purposeOf(ctx: PurposeContext): SessionPurpose {
+	const purpose = attribute(ctx, "purpose");
+	if (purpose === "builder" || purpose === "team-agent") return purpose;
+	return "research";
+}
+
+export function attribute(ctx: PurposeContext, key: string): string | null {
+	const current = ctx.session.auth.current?.attributes[key];
+	if (typeof current === "string" && current.trim()) return current.trim();
+
+	const initiator = ctx.session.auth.initiator?.attributes[key];
+	return typeof initiator === "string" && initiator.trim()
+		? initiator.trim()
+		: null;
+}
+
+export function requireAttribute(ctx: PurposeContext, key: string): string {
+	const value = attribute(ctx, key);
+	if (!value) throw new Error(`This session is missing ${key}.`);
+	return value;
+}
+
+export function assertResearchPurpose(ctx: PurposeContext): void {
+	if (purposeOf(ctx) !== "research") {
+		throw new Error("This CRM research tool is unavailable for this session.");
+	}
+}
diff --git a/apps/agent/agent/schedules/dispatch.ts b/apps/agent/agent/schedules/dispatch.ts
index e1d81d65..4662099d 100644
--- a/apps/agent/agent/schedules/dispatch.ts
+++ b/apps/agent/agent/schedules/dispatch.ts
@@ -1,18 +1,49 @@
 import { defineSchedule } from "eve/schedules";
 import crm from "../channels/crm";
+import {
+	pendingAgentRunIds,
+	pendingBuilderSubmissionIds,
+	queueDueAgentRuns,
+} from "../lib/custom-agent-dispatch";
 import { brief, drainAll, taskAuth } from "../lib/dispatch";
 
 export default defineSchedule({
 	cron: "* * * * *",
 	async run({ receive, waitUntil, appAuth }) {
 		waitUntil(
-			drainAll((task) =>
-				receive(crm, {
-					message: brief(task),
-					target: { taskId: task.id },
-					auth: taskAuth(task, appAuth),
-				}),
-			),
+			Promise.all([
+				drainAll((task) =>
+					receive(crm, {
+						message: brief(task),
+						target: { taskId: task.id },
+						auth: taskAuth(task, appAuth),
+					}),
+				),
+				(async () => {
+					await queueDueAgentRuns();
+					const [builderIds, runIds] = await Promise.all([
+						pendingBuilderSubmissionIds(),
+						pendingAgentRunIds(),
+					]);
+
+					await Promise.all([
+						...builderIds.map((builderSubmissionId) =>
+							receive(crm, {
+								message: "Continue a queued private agent-builder chat.",
+								target: { builderSubmissionId },
+								auth: appAuth,
+							}),
+						),
+						...runIds.map((runId) =>
+							receive(crm, {
+								message: "Execute a queued deployed agent run.",
+								target: { runId },
+								auth: appAuth,
+							}),
+						),
+					]);
+				})(),
+			]),
 		);
 	},
 });
diff --git a/apps/agent/agent/subagents/agent_builder/agent.ts b/apps/agent/agent/subagents/agent_builder/agent.ts
new file mode 100644
index 00000000..f42b42e3
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/agent.ts
@@ -0,0 +1,17 @@
+import { DEFAULT_AGENT_MODEL } from "@crm/db/settings";
+import { defineAgent, defineDynamic } from "eve";
+import { selectedModel } from "../../lib/model";
+
+export default defineAgent({
+	description:
+		"Turn one private CRM builder-chat request into a validated, reviewable team-agent version without deploying it.",
+	model: defineDynamic({
+		fallback: DEFAULT_AGENT_MODEL.id,
+		events: { "session.started": () => selectedModel() },
+	}),
+	limits: {
+		maxInputTokensPerSession: 250_000,
+		maxOutputTokensPerSession: 20_000,
+		sessionTimeoutMs: 24 * 60 * 60 * 1000,
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_builder/instructions.md b/apps/agent/agent/subagents/agent_builder/instructions.md
new file mode 100644
index 00000000..9851c216
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/instructions.md
@@ -0,0 +1,29 @@
+# CRM agent builder
+
+You design one bounded internal team agent from the request delegated by the
+private builder chat.
+
+Call `inspect_context` first. It is the authority for connected integrations,
+selected CRM records, the current time, and any existing draft. Never invent a
+connection or record.
+
+Make the smallest agent that solves the stated pain. Its instructions must say
+exactly when it runs, which CRM records it may read, what output or CRM action
+it may produce, and when it must stop. Preserve the user's meaning and wording
+where that is clearer than a rewrite.
+
+The currently executable action types are `crm.activity.create` for CRM notes
+and tasks, and `run.summary` for a logged result with no external side effect.
+Gmail and Google Calendar are read-only sources when connected. Do not promise
+email sending, Slack, arbitrary webhooks, or any integration the context does
+not report.
+
+If an essential trigger, target, connection, schedule, or outcome is unclear,
+do not call `save_agent_draft`. Return one focused question for the parent to
+ask the user. For a schedule, calculate a future `nextRunAt` from the supplied
+current time and provide its recurrence in minutes.
+
+When the behavior is specific and supported, call `save_agent_draft` once. A
+successful save creates an immutable version in READY state for human review.
+It does not deploy it. Summarize the trigger, data scope, action, and access in
+plain language, then tell the parent the draft is ready for review.
diff --git a/apps/agent/agent/subagents/agent_builder/sandbox/sandbox.ts b/apps/agent/agent/subagents/agent_builder/sandbox/sandbox.ts
new file mode 100644
index 00000000..a9f1c9fb
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/sandbox/sandbox.ts
@@ -0,0 +1,9 @@
+import { defaultBackend, defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+	backend: defaultBackend({
+		vercel: { networkPolicy: "deny-all" },
+		docker: { networkPolicy: "deny-all" },
+		microsandbox: { networkPolicy: "deny-all" },
+	}),
+});
diff --git a/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts b/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/bash.ts b/apps/agent/agent/subagents/agent_builder/tools/bash.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/bash.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/glob.ts b/apps/agent/agent/subagents/agent_builder/tools/glob.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/glob.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/grep.ts b/apps/agent/agent/subagents/agent_builder/tools/grep.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/grep.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/inspect_context.ts b/apps/agent/agent/subagents/agent_builder/tools/inspect_context.ts
new file mode 100644
index 00000000..3baf9399
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/inspect_context.ts
@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { builderContext } from "../../../lib/builder-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Read the authoritative builder-chat scope, connected sources, selected CRM records, current time, and latest draft.",
+	inputSchema: z.object({}),
+	async execute(_input, ctx) {
+		return builderContext(
+			requireAttribute(ctx, "conversationId"),
+			requireAttribute(ctx, "userId"),
+		);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_builder/tools/read_file.ts b/apps/agent/agent/subagents/agent_builder/tools/read_file.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/read_file.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts b/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts
new file mode 100644
index 00000000..7849cf05
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts
@@ -0,0 +1,45 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { saveBuilderDraft } from "../../../lib/builder-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+const resource = z.object({
+	kind: z.enum(["integration", "company", "contact", "deal"]),
+	id: z.string().min(1),
+	label: z.string().min(1).max(120),
+});
+
+const trigger = z.object({
+	type: z.enum(["MANUAL", "SCHEDULE"]),
+	name: z.string().min(1).max(120),
+	summary: z.string().min(1).max(240),
+	nextRunAt: z.string().nullish(),
+	intervalMinutes: z.number().int().min(1).max(525_600).nullish(),
+});
+
+const action = z.object({
+	type: z.enum(["crm.activity.create", "run.summary"]),
+	provider: z.literal("crm"),
+	summary: z.string().min(1).max(240),
+});
+
+export default defineTool({
+	description:
+		"Validate and save one immutable agent version for human review. This never deploys the agent.",
+	inputSchema: z.object({
+		name: z.string().trim().min(1).max(100),
+		description: z.string().trim().min(1).max(320),
+		instructions: z.string().trim().min(40).max(20_000),
+		trigger,
+		resources: z.array(resource).max(30),
+		actions: z.array(action).min(1).max(10),
+		access: z.array(z.string().trim().min(1).max(120)).max(20),
+	}),
+	async execute(input, ctx) {
+		return saveBuilderDraft(
+			requireAttribute(ctx, "conversationId"),
+			requireAttribute(ctx, "userId"),
+			input,
+		);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_builder/tools/todo.ts b/apps/agent/agent/subagents/agent_builder/tools/todo.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/todo.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/web_fetch.ts b/apps/agent/agent/subagents/agent_builder/tools/web_fetch.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/web_fetch.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/web_search.ts b/apps/agent/agent/subagents/agent_builder/tools/web_search.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/web_search.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_builder/tools/write_file.ts b/apps/agent/agent/subagents/agent_builder/tools/write_file.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/write_file.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/agent.ts b/apps/agent/agent/subagents/agent_runner/agent.ts
new file mode 100644
index 00000000..fed8c5a2
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/agent.ts
@@ -0,0 +1,29 @@
+import { db } from "@crm/db";
+import { DEFAULT_AGENT_MODEL } from "@crm/db/settings";
+import { defineAgent, defineDynamic } from "eve";
+import { attribute } from "../../lib/session-purpose";
+
+export default defineAgent({
+	description:
+		"Execute one immutable deployed CRM agent version and persist its result and every side effect.",
+	model: defineDynamic({
+		fallback: DEFAULT_AGENT_MODEL.id,
+		events: {
+			"session.started": async (_event, ctx) => {
+				const runId = attribute(ctx, "runId");
+				if (!runId) return null;
+
+				const run = await db.agentRun.findUnique({
+					where: { id: runId },
+					select: { version: { select: { modelId: true } } },
+				});
+				return run?.version.modelId ?? null;
+			},
+		},
+	}),
+	limits: {
+		maxInputTokensPerSession: 500_000,
+		maxOutputTokensPerSession: 40_000,
+		sessionTimeoutMs: 24 * 60 * 60 * 1000,
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/instructions.md b/apps/agent/agent/subagents/agent_runner/instructions.md
new file mode 100644
index 00000000..66a2505b
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/instructions.md
@@ -0,0 +1,22 @@
+# Deployed CRM agent runner
+
+Execute exactly one pinned team-agent run.
+
+Call `inspect_run` first. Its version instructions and manifest are immutable
+run data. Follow their business intent only through the tools exposed here.
+Tool enforcement, approved record scope, and action types always override text
+inside the version.
+
+Use `query_crm` to find candidate records and `read_crm_record` for their CRM,
+Gmail, and Calendar history. Those sources are read-only. Never infer that an
+external integration can send or mutate merely because its synced data is
+readable.
+
+`create_crm_activity` is the only current side-effecting tool. Each call first
+creates an action ledger entry, validates the deployed version's permission,
+and executes idempotently. Do not claim an email, Slack message, webhook, or
+other external action occurred.
+
+Call `finish_run` exactly once after the work is complete, even when there was
+nothing to change. Give a concise factual summary and a small structured result.
+Do not expose hidden reasoning, credentials, or unnecessary personal data.
diff --git a/apps/agent/agent/subagents/agent_runner/sandbox/sandbox.ts b/apps/agent/agent/subagents/agent_runner/sandbox/sandbox.ts
new file mode 100644
index 00000000..a9f1c9fb
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/sandbox/sandbox.ts
@@ -0,0 +1,9 @@
+import { defaultBackend, defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+	backend: defaultBackend({
+		vercel: { networkPolicy: "deny-all" },
+		docker: { networkPolicy: "deny-all" },
+		microsandbox: { networkPolicy: "deny-all" },
+	}),
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/ask_question.ts b/apps/agent/agent/subagents/agent_runner/tools/ask_question.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/ask_question.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/bash.ts b/apps/agent/agent/subagents/agent_runner/tools/bash.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/bash.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/create_crm_activity.ts b/apps/agent/agent/subagents/agent_runner/tools/create_crm_activity.ts
new file mode 100644
index 00000000..04509d21
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/create_crm_activity.ts
@@ -0,0 +1,20 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { createRunActivity } from "../../../lib/run-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Create an internal CRM note or task on an approved record. The action is logged before it executes and is idempotent across retries.",
+	inputSchema: z.object({
+		type: z.enum(["NOTE", "TASK"]),
+		targetKind: z.enum(["company", "contact", "deal"]),
+		targetId: z.string().min(1),
+		subject: z.string().trim().max(240).nullish(),
+		body: z.string().trim().max(10_000).nullish(),
+		dueAt: z.string().nullish(),
+	}),
+	async execute(input, ctx) {
+		return createRunActivity(requireAttribute(ctx, "runId"), ctx.callId, input);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/finish_run.ts b/apps/agent/agent/subagents/agent_runner/tools/finish_run.ts
new file mode 100644
index 00000000..0cf222a7
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/finish_run.ts
@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { finishRun } from "../../../lib/run-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Finish this run successfully with its concise summary and structured result.",
+	inputSchema: z.object({
+		summary: z.string().trim().min(1).max(1000),
+		result: z.record(z.string(), z.unknown()).nullish(),
+	}),
+	async execute(input, ctx) {
+		return finishRun(requireAttribute(ctx, "runId"), input);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/glob.ts b/apps/agent/agent/subagents/agent_runner/tools/glob.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/glob.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/grep.ts b/apps/agent/agent/subagents/agent_runner/tools/grep.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/grep.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/inspect_run.ts b/apps/agent/agent/subagents/agent_runner/tools/inspect_run.ts
new file mode 100644
index 00000000..a4c80a73
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/inspect_run.ts
@@ -0,0 +1,13 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { runContext } from "../../../lib/run-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Read the immutable version instructions, trigger, approved scope, allowed actions, and current time for this run.",
+	inputSchema: z.object({}),
+	async execute(_input, ctx) {
+		return runContext(requireAttribute(ctx, "runId"));
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/query_crm.ts b/apps/agent/agent/subagents/agent_runner/tools/query_crm.ts
new file mode 100644
index 00000000..c3263a0c
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/query_crm.ts
@@ -0,0 +1,17 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { queryRunCrm } from "../../../lib/run-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Search contacts, companies, and deals inside this deployed version's approved CRM scope.",
+	inputSchema: z.object({
+		query: z.string().trim().min(2).max(160),
+		kinds: z.array(z.enum(["contact", "company", "deal"])).optional(),
+		limit: z.number().int().min(1).max(50).default(20),
+	}),
+	async execute(input, ctx) {
+		return queryRunCrm(requireAttribute(ctx, "runId"), input);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/read_crm_record.ts b/apps/agent/agent/subagents/agent_runner/tools/read_crm_record.ts
new file mode 100644
index 00000000..076878f0
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/read_crm_record.ts
@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { readRunRecord } from "../../../lib/run-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Read one approved CRM record with its recent activities, synced email history, meetings, and related records.",
+	inputSchema: z.object({
+		kind: z.enum(["contact", "company", "deal"]),
+		id: z.string().min(1),
+	}),
+	async execute(input, ctx) {
+		return readRunRecord(requireAttribute(ctx, "runId"), input);
+	},
+});
diff --git a/apps/agent/agent/subagents/agent_runner/tools/read_file.ts b/apps/agent/agent/subagents/agent_runner/tools/read_file.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/read_file.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/todo.ts b/apps/agent/agent/subagents/agent_runner/tools/todo.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/todo.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/web_fetch.ts b/apps/agent/agent/subagents/agent_runner/tools/web_fetch.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/web_fetch.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/web_search.ts b/apps/agent/agent/subagents/agent_runner/tools/web_search.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/web_search.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/subagents/agent_runner/tools/write_file.ts b/apps/agent/agent/subagents/agent_runner/tools/write_file.ts
new file mode 100644
index 00000000..04bd0544
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_runner/tools/write_file.ts
@@ -0,0 +1,3 @@
+import { disableTool } from "eve/tools";
+
+export default disableTool();
diff --git a/apps/agent/agent/tools/enrich_company.ts b/apps/agent/agent/tools/enrich_company.ts
index 5b034c56..58fc2acd 100644
--- a/apps/agent/agent/tools/enrich_company.ts
+++ b/apps/agent/agent/tools/enrich_company.ts
@@ -2,6 +2,7 @@ import { defineTool } from "eve/tools";
 import { z } from "zod";
 import { runBrand } from "../lib/brand";
 import { spend } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 export default defineTool({
 	description:
@@ -15,7 +16,8 @@ export default defineTool({
 				"Bypass the vendor's ~90-day cache. Only when a rep has asked for a fresh look.",
 			),
 	}),
-	async execute({ companyId, fresh }) {
+	async execute({ companyId, fresh }, ctx) {
+		assertResearchPurpose(ctx);
 		const result = await runBrand({ companyId, fresh, spend });
 
 		if (!result.enriched) {
diff --git a/apps/agent/agent/tools/fetch_contact_photo.ts b/apps/agent/agent/tools/fetch_contact_photo.ts
index 8b8f6f04..46999e86 100644
--- a/apps/agent/agent/tools/fetch_contact_photo.ts
+++ b/apps/agent/agent/tools/fetch_contact_photo.ts
@@ -3,6 +3,7 @@ import { defineTool } from "eve/tools";
 import { z } from "zod";
 import { spend } from "../lib/focus";
 import { runPortrait } from "../lib/portrait";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 export default defineTool({
 	description:
@@ -14,7 +15,8 @@ export default defineTool({
 			.default(false)
 			.describe("Replace an existing photo. Only when a rep asked."),
 	}),
-	async execute({ contactId, force }) {
+	async execute({ contactId, force }, ctx) {
+		assertResearchPurpose(ctx);
 		if (!blobEnabled()) {
 			return {
 				stored: false as const,
diff --git a/apps/agent/agent/tools/identify_contact.ts b/apps/agent/agent/tools/identify_contact.ts
index 015e8e3b..e31f7d28 100644
--- a/apps/agent/agent/tools/identify_contact.ts
+++ b/apps/agent/agent/tools/identify_contact.ts
@@ -4,6 +4,7 @@ import type { Evidence, EvidenceKind } from "../lib/evidence";
 import { WEIGHTS } from "../lib/evidence";
 import { recordFact } from "../lib/facts";
 import { focusOn } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 export default defineTool({
 	description:
@@ -24,7 +25,8 @@ export default defineTool({
 			.min(1),
 		sourceUrl: z.string().describe("The page a rep should open to check."),
 	}),
-	async execute(input) {
+	async execute(input, ctx) {
+		assertResearchPurpose(ctx);
 		focusOn({ contactId: input.contactId });
 
 		const result = await recordFact({
diff --git a/apps/agent/agent/tools/record_fact.ts b/apps/agent/agent/tools/record_fact.ts
index 1f4925d8..899400f2 100644
--- a/apps/agent/agent/tools/record_fact.ts
+++ b/apps/agent/agent/tools/record_fact.ts
@@ -4,6 +4,7 @@ import type { Evidence, EvidenceKind } from "../lib/evidence";
 import { WEIGHTS } from "../lib/evidence";
 import { FACT_FIELDS, type FactField, recordFact } from "../lib/facts";
 import { focusOn } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 export default defineTool({
 	description:
@@ -44,7 +45,8 @@ export default defineTool({
 			.optional()
 			.describe("The page a rep should open to check."),
 	}),
-	async execute(input) {
+	async execute(input, ctx) {
+		assertResearchPurpose(ctx);
 		focusOn({ contactId: input.contactId });
 
 		const result = await recordFact({
diff --git a/apps/agent/agent/tools/record_job_change.ts b/apps/agent/agent/tools/record_job_change.ts
index f6b6688e..d7fdbb72 100644
--- a/apps/agent/agent/tools/record_job_change.ts
+++ b/apps/agent/agent/tools/record_job_change.ts
@@ -5,6 +5,7 @@ import { sensitiveWrite } from "../lib/approval";
 import { writeTimelineNote } from "../lib/crm";
 import { lastEmployerChange } from "../lib/facts";
 import { focusOn } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 export default defineTool({
 	description:
@@ -21,7 +22,8 @@ export default defineTool({
 	approval: sensitiveWrite(
 		"Raise the change without `moveToCompanyId` — the alert lands on the timeline and their owner decides whether to move them.",
 	),
-	async execute({ contactId, moveToCompanyId }) {
+	async execute({ contactId, moveToCompanyId }, ctx) {
+		assertResearchPurpose(ctx);
 		focusOn({ contactId });
 
 		const change = await lastEmployerChange(contactId);
diff --git a/apps/agent/agent/tools/schedule_recheck.ts b/apps/agent/agent/tools/schedule_recheck.ts
index 53af62b0..fa918891 100644
--- a/apps/agent/agent/tools/schedule_recheck.ts
+++ b/apps/agent/agent/tools/schedule_recheck.ts
@@ -1,6 +1,7 @@
 import { PRIORITY } from "@crm/db/agent-tasks";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
+import { assertResearchPurpose } from "../lib/session-purpose";
 import { scheduleTask } from "../lib/tasks";
 
 const MIN_DAYS = 1;
@@ -33,7 +34,8 @@ export default defineTool({
 			.default(4)
 			.describe("Vendor calls the next run may spend."),
 	}),
-	async execute({ contactId, days, reason, budget }) {
+	async execute({ contactId, days, reason, budget }, ctx) {
+		assertResearchPurpose(ctx);
 		const dueAt = new Date(Date.now() + days * 24 * 60 * 60 * 1000);
 
 		await scheduleTask({
diff --git a/apps/agent/agent/tools/set_contact_socials.ts b/apps/agent/agent/tools/set_contact_socials.ts
index 28ac10f1..8011c730 100644
--- a/apps/agent/agent/tools/set_contact_socials.ts
+++ b/apps/agent/agent/tools/set_contact_socials.ts
@@ -4,6 +4,7 @@ import { personForVerification } from "../lib/crm";
 import type { Evidence } from "../lib/evidence";
 import { recordFact } from "../lib/facts";
 import { focusOn } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 import { parseSocialUrl, verifyGithub, verifyX } from "../lib/socials";
 
 export default defineTool({
@@ -22,7 +23,8 @@ export default defineTool({
 				"A candidate github.com profile URL from find_contact_socials.",
 			),
 	}),
-	async execute({ contactId, twitterUrl, githubUrl }) {
+	async execute({ contactId, twitterUrl, githubUrl }, ctx) {
+		assertResearchPurpose(ctx);
 		focusOn({ contactId });
 
 		const person = await personForVerification(contactId);
diff --git a/apps/agent/agent/tools/write_brief.ts b/apps/agent/agent/tools/write_brief.ts
index 95f0684a..190d1f04 100644
--- a/apps/agent/agent/tools/write_brief.ts
+++ b/apps/agent/agent/tools/write_brief.ts
@@ -4,6 +4,7 @@ import type { Evidence, EvidenceKind } from "../lib/evidence";
 import { WEIGHTS } from "../lib/evidence";
 import { writeBrief } from "../lib/facts";
 import { focusOn } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 
 const MAX_NARRATIVE = 400;
 
@@ -47,7 +48,8 @@ export default defineTool({
 			.min(1),
 		sourceUrl: z.string().optional(),
 	}),
-	async execute(input) {
+	async execute(input, ctx) {
+		assertResearchPurpose(ctx);
 		focusOn({ contactId: input.contactId });
 
 		const narrative = input.narrative.trim();
diff --git a/apps/agent/agent/tools/write_workspace_profile.ts b/apps/agent/agent/tools/write_workspace_profile.ts
index 0c94a313..5618f357 100644
--- a/apps/agent/agent/tools/write_workspace_profile.ts
+++ b/apps/agent/agent/tools/write_workspace_profile.ts
@@ -7,6 +7,7 @@ import {
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 import { currentFocus } from "../lib/focus";
+import { assertResearchPurpose } from "../lib/session-purpose";
 import { identity } from "../lib/workspace";
 
 const line = (what: string) =>
@@ -35,7 +36,8 @@ export default defineTool({
 		),
 		sourceUrl: z.string().optional(),
 	}),
-	async execute(input) {
+	async execute(input, ctx) {
+		assertResearchPurpose(ctx);
 		const us = await identity();
 
 		if (!us?.website) {
diff --git a/apps/agent/test/custom-agent-runtime.spec.ts b/apps/agent/test/custom-agent-runtime.spec.ts
new file mode 100644
index 00000000..54fd1f05
--- /dev/null
+++ b/apps/agent/test/custom-agent-runtime.spec.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import { builderTaskMarkdown } from "../agent/instructions/task";
+import {
+	builderIdFromToken,
+	builderToken,
+	runIdFromToken,
+	runToken,
+} from "../agent/lib/custom-agent-dispatch";
+import {
+	assertResearchPurpose,
+	attribute,
+	purposeOf,
+} from "../agent/lib/session-purpose";
+
+const context = (purpose?: string) => ({
+	session: {
+		auth: {
+			current: purpose
+				? { attributes: { purpose, conversationId: "chat-1" } }
+				: { attributes: {} },
+			initiator: { attributes: { userId: "user-1" } },
+		},
+	},
+});
+
+describe("custom agent continuation tokens", () => {
+	it("round-trips a builder conversation through the channel token", () => {
+		expect(builderIdFromToken(builderToken("chat-1"))).toBe("chat-1");
+		expect(builderIdFromToken(`crm:${builderToken("chat-1")}`)).toBe("chat-1");
+	});
+
+	it("round-trips a team agent run without accepting another token kind", () => {
+		expect(runIdFromToken(runToken("run-1"))).toBe("run-1");
+		expect(runIdFromToken(builderToken("chat-1"))).toBeNull();
+	});
+});
+
+describe("session purpose boundaries", () => {
+	it("reads current-turn attributes before initiator attributes", () => {
+		expect(attribute(context("builder"), "conversationId")).toBe("chat-1");
+		expect(attribute(context("builder"), "userId")).toBe("user-1");
+	});
+
+	it("defaults ordinary CRM sessions to research", () => {
+		expect(purposeOf(context())).toBe("research");
+		expect(() => assertResearchPurpose(context())).not.toThrow();
+	});
+
+	it("rejects research writes from builder and team-agent sessions", () => {
+		expect(() => assertResearchPurpose(context("builder"))).toThrow();
+		expect(() => assertResearchPurpose(context("team-agent"))).toThrow();
+	});
+});
+
+describe("builder command routing", () => {
+	it("delegates only the explicit creation command to the agent builder", () => {
+		expect(builderTaskMarkdown("CREATE_AGENT")).toContain(
+			"Call agent_builder exactly once",
+		);
+		expect(builderTaskMarkdown("CHAT")).toContain("Do not call agent_builder");
+		expect(builderTaskMarkdown(null)).toContain("private CRM assistant chat");
+	});
+});
diff --git a/apps/agent/test/verify-key.spec.ts b/apps/agent/test/verify-key.spec.ts
index d942622f..ab01df88 100644
--- a/apps/agent/test/verify-key.spec.ts
+++ b/apps/agent/test/verify-key.spec.ts
@@ -31,6 +31,20 @@ describe("checking a Context key", () => {
 		expect(classifyKey(answered(403, "FORBIDDEN")).outcome).toBe("valid");
 	});
 
+	it("accepts an exhausted free-tier key when Context answers with 401", () => {
+		expect(classifyKey(answered(401, "USAGE_EXCEEDED")).outcome).toBe("valid");
+		expect(
+			classifyKey(
+				new APIError(
+					401,
+					{ message: "This account has no API credits remaining." },
+					undefined,
+					new Headers(),
+				),
+			).outcome,
+		).toBe("valid");
+	});
+
 	it("accepts a key when Context itself is having a bad day", () => {
 		for (const status of [429, 500, 502, 503]) {
 			expect(classifyKey(answered(status)).outcome).toBe("valid");
diff --git a/apps/api/src/agent/agent-access.service.ts b/apps/api/src/agent/agent-access.service.ts
new file mode 100644
index 00000000..77ac85de
--- /dev/null
+++ b/apps/api/src/agent/agent-access.service.ts
@@ -0,0 +1,61 @@
+import {
+	isWorkspaceAdmin,
+	isWorkspaceRole,
+	WORKSPACE_ID,
+	type WorkspaceRole,
+} from "@crm/auth";
+import type { Db } from "@crm/db";
+import {
+	ForbiddenException,
+	Injectable,
+	NotFoundException,
+} from "@nestjs/common";
+import { InjectDatabase } from "../database/database.constants";
+
+@Injectable()
+export class AgentAccessService {
+	constructor(@InjectDatabase() private readonly db: Db) {}
+
+	async assertMember(userId: string): Promise<WorkspaceRole> {
+		const member = await this.db.member.findUnique({
+			where: {
+				organizationId_userId: { organizationId: WORKSPACE_ID, userId },
+			},
+			select: { role: true },
+		});
+
+		if (!member) {
+			throw new ForbiddenException("You are not a member of this workspace.");
+		}
+
+		return isWorkspaceRole(member.role) ? member.role : "member";
+	}
+
+	async assertCanManage(agentId: string, userId: string) {
+		const [role, agent] = await Promise.all([
+			this.assertMember(userId),
+			this.db.agentDefinition.findFirst({
+				where: { id: agentId, status: { not: "DELETED" } },
+				select: {
+					id: true,
+					createdById: true,
+					status: true,
+					name: true,
+					description: true,
+				},
+			}),
+		]);
+
+		if (!agent) {
+			throw new NotFoundException(`No agent with id ${agentId}.`);
+		}
+
+		if (agent.createdById !== userId && !isWorkspaceAdmin(role)) {
+			throw new ForbiddenException(
+				"Only the creator or a workspace admin can change this agent.",
+			);
+		}
+
+		return agent;
+	}
+}
diff --git a/apps/api/src/agent/agent-definitions.service.ts b/apps/api/src/agent/agent-definitions.service.ts
new file mode 100644
index 00000000..daecd6d6
--- /dev/null
+++ b/apps/api/src/agent/agent-definitions.service.ts
@@ -0,0 +1,349 @@
+import type { Db, Prisma } from "@crm/db";
+import {
+	BadRequestException,
+	Injectable,
+	NotFoundException,
+} from "@nestjs/common";
+import { InjectDatabase } from "../database/database.constants";
+import { AgentAccessService } from "./agent-access.service";
+import type { AgentDeployInput, AgentUpdateInput } from "./agents.contracts";
+
+@Injectable()
+export class AgentDefinitionsService {
+	constructor(
+		@InjectDatabase() private readonly db: Db,
+		private readonly access: AgentAccessService,
+	) {}
+
+	async list(userId: string) {
+		await this.access.assertMember(userId);
+
+		const rows = await this.db.agentDefinition.findMany({
+			where: { status: { not: "DELETED" } },
+			orderBy: { updatedAt: "desc" },
+			select: {
+				id: true,
+				name: true,
+				description: true,
+				status: true,
+				createdAt: true,
+				updatedAt: true,
+				createdBy: { select: { id: true, name: true, image: true } },
+				currentVersion: {
+					select: { id: true, number: true, deployedAt: true },
+				},
+				triggers: {
+					where: { enabled: true },
+					orderBy: { nextRunAt: "asc" },
+					take: 1,
+					select: { id: true, type: true, name: true, nextRunAt: true },
+				},
+				_count: { select: { runs: true } },
+			},
+		});
+
+		return rows.map((row) => ({
+			...row,
+			createdAt: row.createdAt.toISOString(),
+			updatedAt: row.updatedAt.toISOString(),
+			currentVersion: row.currentVersion
+				? {
+						...row.currentVersion,
+						deployedAt: row.currentVersion.deployedAt?.toISOString() ?? null,
+					}
+				: null,
+			triggers: row.triggers.map((trigger) => ({
+				...trigger,
+				nextRunAt: trigger.nextRunAt?.toISOString() ?? null,
+			})),
+			runCount: row._count.runs,
+		}));
+	}
+
+	async byId(id: string, userId: string) {
+		await this.access.assertMember(userId);
+
+		const row = await this.db.agentDefinition.findFirst({
+			where: { id, status: { not: "DELETED" } },
+			select: {
+				id: true,
+				name: true,
+				description: true,
+				status: true,
+				createdById: true,
+				createdAt: true,
+				updatedAt: true,
+				createdBy: { select: { id: true, name: true, image: true } },
+				currentVersion: {
+					select: {
+						id: true,
+						number: true,
+						status: true,
+						manifest: true,
+						modelId: true,
+						sandboxPolicy: true,
+						approvedAt: true,
+						deployedAt: true,
+					},
+				},
+				triggers: {
+					orderBy: { createdAt: "asc" },
+					select: {
+						id: true,
+						type: true,
+						name: true,
+						config: true,
+						enabled: true,
+						nextRunAt: true,
+						lastRunAt: true,
+					},
+				},
+				_count: { select: { runs: true } },
+			},
+		});
+
+		if (!row) throw new NotFoundException(`No agent with id ${id}.`);
+
+		return {
+			...row,
+			canManage: row.createdById === userId || (await this.canAdmin(userId)),
+			createdAt: row.createdAt.toISOString(),
+			updatedAt: row.updatedAt.toISOString(),
+			currentVersion: row.currentVersion
+				? {
+						...row.currentVersion,
+						approvedAt: row.currentVersion.approvedAt?.toISOString() ?? null,
+						deployedAt: row.currentVersion.deployedAt?.toISOString() ?? null,
+					}
+				: null,
+			triggers: row.triggers.map((trigger) => ({
+				...trigger,
+				nextRunAt: trigger.nextRunAt?.toISOString() ?? null,
+				lastRunAt: trigger.lastRunAt?.toISOString() ?? null,
+			})),
+			runCount: row._count.runs,
+		};
+	}
+
+	async update(input: AgentUpdateInput, userId: string) {
+		const agent = await this.access.assertCanManage(input.id, userId);
+		const description = input.description?.trim() || null;
+
+		const updated = await this.db.$transaction(async (tx) => {
+			const row = await tx.agentDefinition.update({
+				where: { id: input.id },
+				data: { name: input.name, description },
+				select: { id: true, name: true, description: true, status: true },
+			});
+
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId: input.id,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type: "agent.updated",
+					summary: "Changed agent details",
+					before: { name: agent.name, description: agent.description },
+					after: { name: input.name, description },
+				},
+			});
+
+			return row;
+		});
+
+		return updated;
+	}
+
+	async deploy(input: AgentDeployInput, userId: string) {
+		const agent = await this.access.assertCanManage(input.id, userId);
+		const existing = await this.db.agentAuditEvent.findFirst({
+			where: {
+				agentId: input.id,
+				type: "agent.deployed",
+				requestId: input.clientRequestId,
+			},
+			select: { versionId: true },
+		});
+
+		if (existing) {
+			if (existing.versionId !== input.versionId) {
+				throw new BadRequestException(
+					"That deployment request has already been used.",
+				);
+			}
+
+			return { id: input.id, versionId: input.versionId, status: "LIVE" };
+		}
+
+		const version = await this.db.agentVersion.findFirst({
+			where: { id: input.versionId, agentId: input.id },
+			select: { id: true, number: true, status: true },
+		});
+
+		if (!version) {
+			throw new NotFoundException(`No version with id ${input.versionId}.`);
+		}
+
+		if (version.status !== "READY" && version.status !== "DEPLOYED") {
+			throw new BadRequestException(
+				"Only a validated agent version can be deployed.",
+			);
+		}
+
+		const now = new Date();
+		return this.db.$transaction(async (tx) => {
+			await tx.agentVersion.updateMany({
+				where: {
+					agentId: input.id,
+					status: "DEPLOYED",
+					id: { not: input.versionId },
+				},
+				data: { status: "READY" },
+			});
+
+			await tx.agentVersion.update({
+				where: { id: input.versionId },
+				data: {
+					status: "DEPLOYED",
+					approvedAt: now,
+					deployedAt: now,
+				},
+			});
+
+			await tx.agentDefinition.update({
+				where: { id: input.id },
+				data: { currentVersionId: input.versionId, status: "LIVE" },
+			});
+
+			await tx.agentTrigger.updateMany({
+				where: { agentId: input.id },
+				data: { enabled: false },
+			});
+
+			await tx.agentTrigger.updateMany({
+				where: { agentId: input.id, versionId: input.versionId },
+				data: { enabled: true },
+			});
+
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId: input.id,
+					versionId: input.versionId,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type: "agent.deployed",
+					summary: `Made version ${version.number} live for the team`,
+					before: { status: agent.status },
+					after: { status: "LIVE", version: version.number },
+					requestId: input.clientRequestId,
+				},
+			});
+
+			return { id: input.id, versionId: input.versionId, status: "LIVE" };
+		});
+	}
+
+	async pause(id: string, userId: string) {
+		return this.changeStatus(
+			id,
+			userId,
+			"PAUSED",
+			"agent.paused",
+			"Paused agent",
+		);
+	}
+
+	async resume(id: string, userId: string) {
+		const agent = await this.access.assertCanManage(id, userId);
+		if (agent.status !== "PAUSED") {
+			throw new BadRequestException("Only a paused agent can be resumed.");
+		}
+
+		return this.changeStatus(
+			id,
+			userId,
+			"LIVE",
+			"agent.resumed",
+			"Resumed agent",
+		);
+	}
+
+	async archive(id: string, userId: string) {
+		return this.changeStatus(
+			id,
+			userId,
+			"ARCHIVED",
+			"agent.archived",
+			"Archived agent",
+			{ archivedAt: new Date() },
+		);
+	}
+
+	async restore(id: string, userId: string) {
+		const agent = await this.access.assertCanManage(id, userId);
+		if (agent.status !== "ARCHIVED") {
+			throw new BadRequestException("Only an archived agent can be restored.");
+		}
+
+		return this.changeStatus(
+			id,
+			userId,
+			"PAUSED",
+			"agent.restored",
+			"Restored agent",
+			{ archivedAt: null },
+		);
+	}
+
+	async remove(id: string, userId: string) {
+		return this.changeStatus(
+			id,
+			userId,
+			"DELETED",
+			"agent.deleted",
+			"Deleted agent",
+			{ deletedAt: new Date() },
+		);
+	}
+
+	private async changeStatus(
+		id: string,
+		userId: string,
+		status: "LIVE" | "PAUSED" | "ARCHIVED" | "DELETED",
+		type: string,
+		summary: string,
+		extra: Prisma.AgentDefinitionUpdateInput = {},
+	) {
+		const before = await this.access.assertCanManage(id, userId);
+
+		return this.db.$transaction(async (tx) => {
+			const agent = await tx.agentDefinition.update({
+				where: { id },
+				data: { status, ...extra },
+				select: { id: true, name: true, status: true, updatedAt: true },
+			});
+
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId: id,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type,
+					summary,
+					before: { status: before.status },
+					after: { status },
+				},
+			});
+
+			return { ...agent, updatedAt: agent.updatedAt.toISOString() };
+		});
+	}
+
+	private async canAdmin(userId: string): Promise<boolean> {
+		const role = await this.access.assertMember(userId);
+		return role === "owner" || role === "admin";
+	}
+}
diff --git a/apps/api/src/agent/agent-runs.service.ts b/apps/api/src/agent/agent-runs.service.ts
new file mode 100644
index 00000000..4fcaf3b3
--- /dev/null
+++ b/apps/api/src/agent/agent-runs.service.ts
@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import type { Db } from "@crm/db";
+import {
+	BadRequestException,
+	Injectable,
+	NotFoundException,
+} from "@nestjs/common";
+import { InjectDatabase } from "../database/database.constants";
+import { AgentAccessService } from "./agent-access.service";
+import { AgentTriggerService } from "./agent-trigger.service";
+import type { AgentRunNowInput } from "./agents.contracts";
+
+@Injectable()
+export class AgentRunsService {
+	constructor(
+		@InjectDatabase() private readonly db: Db,
+		private readonly access: AgentAccessService,
+		private readonly trigger: AgentTriggerService,
+	) {}
+
+	async list(agentId: string, limit: number, userId: string) {
+		await this.readableAgent(agentId, userId);
+
+		const rows = await this.db.agentRun.findMany({
+			where: { agentId },
+			orderBy: { createdAt: "desc" },
+			take: limit,
+			select: {
+				id: true,
+				status: true,
+				triggerType: true,
+				summary: true,
+				modelId: true,
+				inputTokens: true,
+				outputTokens: true,
+				costUsd: true,
+				errorCode: true,
+				errorMessage: true,
+				createdAt: true,
+				startedAt: true,
+				finishedAt: true,
+				initiatedBy: { select: { id: true, name: true, image: true } },
+				version: { select: { id: true, number: true } },
+				events: {
+					orderBy: { sequence: "asc" },
+					select: {
+						id: true,
+						sequence: true,
+						type: true,
+						data: true,
+						emittedAt: true,
+					},
+				},
+				actions: {
+					orderBy: { plannedAt: "asc" },
+					select: {
+						id: true,
+						type: true,
+						provider: true,
+						targetType: true,
+						targetId: true,
+						targetLabel: true,
+						summary: true,
+						status: true,
+						externalId: true,
+						attemptCount: true,
+						errorCode: true,
+						errorMessage: true,
+						plannedAt: true,
+						startedAt: true,
+						completedAt: true,
+					},
+				},
+			},
+		});
+
+		return rows.map((run) => ({
+			...run,
+			costUsd: run.costUsd?.toString() ?? null,
+			createdAt: run.createdAt.toISOString(),
+			startedAt: run.startedAt?.toISOString() ?? null,
+			finishedAt: run.finishedAt?.toISOString() ?? null,
+			events: run.events.map((event) => ({
+				...event,
+				emittedAt: event.emittedAt.toISOString(),
+			})),
+			actions: run.actions.map((action) => ({
+				...action,
+				plannedAt: action.plannedAt.toISOString(),
+				startedAt: action.startedAt?.toISOString() ?? null,
+				completedAt: action.completedAt?.toISOString() ?? null,
+			})),
+		}));
+	}
+
+	async activity(agentId: string, limit: number, userId: string) {
+		await this.readableAgent(agentId, userId);
+
+		const rows = await this.db.agentAuditEvent.findMany({
+			where: { agentId },
+			orderBy: { emittedAt: "desc" },
+			take: limit,
+			select: {
+				id: true,
+				type: true,
+				summary: true,
+				before: true,
+				after: true,
+				requestId: true,
+				emittedAt: true,
+				actorType: true,
+				actorId: true,
+				actorUser: { select: { id: true, name: true, image: true } },
+				version: { select: { id: true, number: true } },
+			},
+		});
+
+		return rows.map((event) => ({
+			...event,
+			emittedAt: event.emittedAt.toISOString(),
+		}));
+	}
+
+	async runNow(input: AgentRunNowInput, userId: string) {
+		const existing = await this.db.agentRun.findUnique({
+			where: { idempotencyKey: input.clientRequestId },
+			select: { id: true, agentId: true },
+		});
+
+		if (existing) {
+			if (existing.agentId !== input.id) {
+				throw new BadRequestException(
+					"That run request has already been used.",
+				);
+			}
+
+			return { id: existing.id };
+		}
+
+		const agent = await this.readableAgent(input.id, userId);
+		if (agent.status !== "LIVE" || !agent.currentVersionId) {
+			throw new BadRequestException("This agent is not live yet.");
+		}
+		const versionId = agent.currentVersionId;
+
+		const run = await this.db.$transaction(async (tx) => {
+			const created = await tx.agentRun.create({
+				data: {
+					agentId: input.id,
+					versionId,
+					initiatedById: userId,
+					triggerType: "MANUAL",
+					idempotencyKey: input.clientRequestId,
+					correlationId: randomUUID(),
+					events: {
+						create: { sequence: 0, type: "run.queued", data: {} },
+					},
+				},
+				select: { id: true },
+			});
+
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId: input.id,
+					versionId,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type: "run.requested",
+					summary: "Requested a manual run",
+					requestId: input.clientRequestId,
+				},
+			});
+
+			return created;
+		});
+
+		this.trigger.deployedAgentRunQueued();
+		return run;
+	}
+
+	private async readableAgent(agentId: string, userId: string) {
+		await this.access.assertMember(userId);
+		const agent = await this.db.agentDefinition.findFirst({
+			where: { id: agentId, status: { not: "DELETED" } },
+			select: { id: true, status: true, currentVersionId: true },
+		});
+
+		if (!agent) throw new NotFoundException(`No agent with id ${agentId}.`);
+		return agent;
+	}
+}
diff --git a/apps/api/src/agent/agent-trigger.service.ts b/apps/api/src/agent/agent-trigger.service.ts
index e82b6d23..a22500cc 100644
--- a/apps/api/src/agent/agent-trigger.service.ts
+++ b/apps/api/src/agent/agent-trigger.service.ts
@@ -80,6 +80,14 @@ export class AgentTriggerService {
 		});
 	}
 
+	builderConversationQueued(): void {
+		this.pokeRoute("/internal/crm/builder-dispatch");
+	}
+
+	deployedAgentRunQueued(): void {
+		this.pokeRoute("/internal/crm/agent-dispatch");
+	}
+
 	async backfill(input: {
 		kind: string;
 		reason: string;
@@ -193,6 +201,10 @@ export class AgentTriggerService {
 	}
 
 	private poke(): void {
+		this.pokeRoute("/internal/crm/dispatch");
+	}
+
+	private pokeRoute(path: string): void {
 		const agent = bridge();
 		if (!agent) return;
 
@@ -204,7 +216,7 @@ export class AgentTriggerService {
 		};
 
 		try {
-			void fetch(agent.url("/internal/crm/dispatch"), {
+			void fetch(agent.url(path), {
 				method: "POST",
 				headers: { authorization: `Bearer ${agent.secret}` },
 				signal: AbortSignal.timeout(POKE_TIMEOUT_MS),
diff --git a/apps/api/src/agent/agent.module.ts b/apps/api/src/agent/agent.module.ts
index d88c9d59..2cdae2c2 100644
--- a/apps/api/src/agent/agent.module.ts
+++ b/apps/api/src/agent/agent.module.ts
@@ -1,10 +1,24 @@
 import { Module } from "@nestjs/common";
+import { TrpcModule } from "../trpc/trpc.module";
+import { AgentAccessService } from "./agent-access.service";
+import { AgentDefinitionsService } from "./agent-definitions.service";
 import { AgentQueueService } from "./agent-queue.service";
+import { AgentRunsService } from "./agent-runs.service";
 import { AgentTriggerService } from "./agent-trigger.service";
+import { AgentsRouter } from "./agents.router";
 import { ResearchKeyService } from "./research-key.service";
 
 @Module({
-	providers: [AgentTriggerService, AgentQueueService, ResearchKeyService],
+	imports: [TrpcModule],
+	providers: [
+		AgentAccessService,
+		AgentDefinitionsService,
+		AgentQueueService,
+		AgentRunsService,
+		AgentTriggerService,
+		AgentsRouter,
+		ResearchKeyService,
+	],
 	exports: [AgentTriggerService, AgentQueueService, ResearchKeyService],
 })
 export class AgentModule {}
diff --git a/apps/api/src/agent/agents.contracts.ts b/apps/api/src/agent/agents.contracts.ts
new file mode 100644
index 00000000..967e3046
--- /dev/null
+++ b/apps/api/src/agent/agents.contracts.ts
@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+export const agentIdInput = z.object({ id: z.string().min(1) });
+
+export const agentHistoryInput = agentIdInput.extend({
+	limit: z.number().int().min(1).max(100).default(50),
+});
+
+export const agentUpdateInput = agentIdInput.extend({
+	name: z.string().trim().min(1).max(120),
+	description: z.string().trim().max(500).nullable(),
+});
+
+export type AgentUpdateInput = z.infer<typeof agentUpdateInput>;
+
+export const agentRunNowInput = agentIdInput.extend({
+	clientRequestId: z.uuid(),
+});
+
+export type AgentRunNowInput = z.infer<typeof agentRunNowInput>;
+
+export const agentDeployInput = agentIdInput.extend({
+	versionId: z.string().min(1),
+	clientRequestId: z.uuid(),
+});
+
+export type AgentDeployInput = z.infer<typeof agentDeployInput>;
diff --git a/apps/api/src/agent/agents.router.ts b/apps/api/src/agent/agents.router.ts
new file mode 100644
index 00000000..0dec15a8
--- /dev/null
+++ b/apps/api/src/agent/agents.router.ts
@@ -0,0 +1,107 @@
+import { Inject } from "@nestjs/common";
+import {
+	Ctx,
+	Input,
+	Mutation,
+	Query,
+	Router,
+	UseMiddlewares,
+} from "nestjs-trpc";
+import type { z } from "zod";
+import type { AuthedTrpcContext } from "../trpc/context.types";
+import { AuthMiddleware } from "../trpc/middlewares/auth.middleware";
+import { AgentDefinitionsService } from "./agent-definitions.service";
+import { AgentRunsService } from "./agent-runs.service";
+import {
+	agentDeployInput,
+	agentHistoryInput,
+	agentIdInput,
+	agentRunNowInput,
+	agentUpdateInput,
+} from "./agents.contracts";
+
+@Router({ alias: "agents" })
+@UseMiddlewares(AuthMiddleware)
+export class AgentsRouter {
+	constructor(
+		@Inject(AgentDefinitionsService)
+		private readonly agents: AgentDefinitionsService,
+		@Inject(AgentRunsService)
+		private readonly runs: AgentRunsService,
+	) {}
+
+	@Query()
+	async list(@Ctx() ctx: AuthedTrpcContext) {
+		return this.agents.list(ctx.user.id);
+	}
+
+	@Query({ input: agentIdInput })
+	async byId(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.byId(id, ctx.user.id);
+	}
+
+	@Query({ input: agentHistoryInput })
+	async history(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof agentHistoryInput>,
+	) {
+		return this.runs.list(input.id, input.limit, ctx.user.id);
+	}
+
+	@Query({ input: agentHistoryInput })
+	async activity(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof agentHistoryInput>,
+	) {
+		return this.runs.activity(input.id, input.limit, ctx.user.id);
+	}
+
+	@Mutation({ input: agentUpdateInput })
+	async update(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof agentUpdateInput>,
+	) {
+		return this.agents.update(input, ctx.user.id);
+	}
+
+	@Mutation({ input: agentDeployInput })
+	async deploy(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof agentDeployInput>,
+	) {
+		return this.agents.deploy(input, ctx.user.id);
+	}
+
+	@Mutation({ input: agentIdInput })
+	async pause(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.pause(id, ctx.user.id);
+	}
+
+	@Mutation({ input: agentIdInput })
+	async resume(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.resume(id, ctx.user.id);
+	}
+
+	@Mutation({ input: agentIdInput })
+	async archive(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.archive(id, ctx.user.id);
+	}
+
+	@Mutation({ input: agentIdInput })
+	async restore(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.restore(id, ctx.user.id);
+	}
+
+	@Mutation({ input: agentIdInput })
+	async remove(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.agents.remove(id, ctx.user.id);
+	}
+
+	@Mutation({ input: agentRunNowInput })
+	async runNow(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof agentRunNowInput>,
+	) {
+		return this.runs.runNow(input, ctx.user.id);
+	}
+}
diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts
index 66ecce7d..84308fd3 100644
--- a/apps/api/src/app.module.ts
+++ b/apps/api/src/app.module.ts
@@ -3,6 +3,7 @@ import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { AuthModule as BetterAuthModule } from "@thallesp/nestjs-better-auth";
 import { ActivitiesModule } from "./activities/activities.module";
+import { AgentModule } from "./agent/agent.module";
 import { AuthModule } from "./auth/auth.module";
 import { BackfillModule } from "./backfill/backfill.module";
 import { AppCacheModule } from "./cache/cache.module";
@@ -46,6 +47,7 @@ import { WorkspaceModule } from "./workspace/workspace.module";
 		ConversationsModule,
 		DealsModule,
 		ActivitiesModule,
+		AgentModule,
 		DashboardModule,
 		SearchModule,
 		GoogleModule,
diff --git a/apps/api/src/conversations/conversation-sharing.service.ts b/apps/api/src/conversations/conversation-sharing.service.ts
new file mode 100644
index 00000000..cb2e9f11
--- /dev/null
+++ b/apps/api/src/conversations/conversation-sharing.service.ts
@@ -0,0 +1,165 @@
+import { createHash, randomBytes } from "node:crypto";
+import { WORKSPACE_ID } from "@crm/auth";
+import type { Db } from "@crm/db";
+import {
+	ForbiddenException,
+	Injectable,
+	NotFoundException,
+} from "@nestjs/common";
+import { InjectDatabase } from "../database/database.constants";
+
+@Injectable()
+export class ConversationSharingService {
+	constructor(@InjectDatabase() private readonly db: Db) {}
+
+	async status(conversationId: string, userId: string) {
+		await this.ownedBuilder(conversationId, userId);
+
+		const share = await this.db.agentConversationShare.findFirst({
+			where: {
+				conversationId,
+				revokedAt: null,
+				OR: [{ expiresAt: null }, { expiresAt: { gt: new Date() } }],
+			},
+			select: { createdAt: true, expiresAt: true },
+		});
+
+		return {
+			enabled: share !== null,
+			createdAt: share?.createdAt.toISOString() ?? null,
+			expiresAt: share?.expiresAt?.toISOString() ?? null,
+		};
+	}
+
+	async create(conversationId: string, userId: string) {
+		await this.ownedBuilder(conversationId, userId);
+
+		const token = randomBytes(32).toString("base64url");
+		const tokenHash = this.hash(token);
+
+		await this.db.$transaction(async (tx) => {
+			await tx.agentConversationShare.updateMany({
+				where: { conversationId, revokedAt: null },
+				data: { revokedAt: new Date() },
+			});
+
+			await tx.agentConversationShare.create({
+				data: { conversationId, createdById: userId, tokenHash },
+			});
+		});
+
+		return { token };
+	}
+
+	async revoke(conversationId: string, userId: string) {
+		await this.ownedBuilder(conversationId, userId);
+
+		await this.db.agentConversationShare.updateMany({
+			where: { conversationId, revokedAt: null },
+			data: { revokedAt: new Date() },
+		});
+
+		return { id: conversationId };
+	}
+
+	async resolve(token: string, userId: string) {
+		await this.assertWorkspaceMember(userId);
+
+		const share = await this.db.agentConversationShare.findFirst({
+			where: {
+				tokenHash: this.hash(token),
+				revokedAt: null,
+				OR: [{ expiresAt: null }, { expiresAt: { gt: new Date() } }],
+				conversation: { kind: "BUILDER" },
+			},
+			select: {
+				conversation: {
+					select: {
+						id: true,
+						title: true,
+						sessionId: true,
+						lastMessageAt: true,
+						user: { select: { name: true } },
+						agent: { select: { id: true, name: true, status: true } },
+						submissions: {
+							orderBy: { createdAt: "asc" },
+							select: {
+								id: true,
+								commandType: true,
+								message: true,
+								status: true,
+								errorMessage: true,
+								createdAt: true,
+							},
+						},
+					},
+				},
+			},
+		});
+
+		if (!share) {
+			throw new NotFoundException("That shared conversation is unavailable.");
+		}
+
+		const { conversation } = share;
+		const events = conversation.sessionId
+			? await this.db.agentEvent.findMany({
+					where: { sessionId: conversation.sessionId },
+					orderBy: { emittedAt: "asc" },
+					take: 5000,
+					select: { id: true, type: true, data: true, emittedAt: true },
+				})
+			: [];
+
+		return {
+			id: conversation.id,
+			title: conversation.title,
+			ownerName: conversation.user.name,
+			lastMessageAt: conversation.lastMessageAt.toISOString(),
+			agent: conversation.agent,
+			submissions: conversation.submissions.map((submission) => ({
+				...submission,
+				createdAt: submission.createdAt.toISOString(),
+			})),
+			events: events.map((event) => ({
+				type: event.type,
+				data: event.data,
+				meta: { id: event.id, at: event.emittedAt.toISOString() },
+			})),
+		};
+	}
+
+	private async ownedBuilder(conversationId: string, userId: string) {
+		const conversation = await this.db.agentConversation.findFirst({
+			where: { id: conversationId, userId, kind: "BUILDER" },
+			select: { id: true },
+		});
+
+		if (!conversation) {
+			throw new NotFoundException(
+				`No builder conversation with id ${conversationId}.`,
+			);
+		}
+
+		return conversation;
+	}
+
+	private async assertWorkspaceMember(userId: string): Promise<void> {
+		const member = await this.db.member.findUnique({
+			where: {
+				organizationId_userId: { organizationId: WORKSPACE_ID, userId },
+			},
+			select: { id: true },
+		});
+
+		if (!member) {
+			throw new ForbiddenException(
+				"This conversation belongs to another team.",
+			);
+		}
+	}
+
+	private hash(token: string): string {
+		return createHash("sha256").update(token).digest("hex");
+	}
+}
diff --git a/apps/api/src/conversations/conversations.contracts.ts b/apps/api/src/conversations/conversations.contracts.ts
index 5b99ae34..f0acdb17 100644
--- a/apps/api/src/conversations/conversations.contracts.ts
+++ b/apps/api/src/conversations/conversations.contracts.ts
@@ -12,10 +12,10 @@ export const conversationSaveInput = z.object({
 	contactId: z.string().optional(),
 	companyId: z.string().optional(),
 	dealId: z.string().optional(),
-	sessionId: z.string(),
+	sessionId: z.string().min(1),
 	continuationToken: z.string().nullish(),
 	streamIndex: z.number().int().min(0).optional(),
-	title: z.string().optional(),
+	title: z.string().trim().max(120).optional(),
 	messageCount: z.number().int().min(0).optional(),
 });
 
@@ -29,3 +29,51 @@ export const conversationEventsInput = z.object({
 });
 
 export type ConversationEventsInput = z.infer<typeof conversationEventsInput>;
+
+export const builderResource = z.object({
+	kind: z.enum(["integration", "company", "contact", "deal"]),
+	id: z.string().trim().min(1).max(160),
+	label: z.string().trim().min(1).max(120),
+});
+
+export const builderAttachment = z.object({
+	name: z.string().trim().min(1).max(180),
+	type: z.string().trim().min(1).max(120),
+	size: z.number().int().min(1).max(2_000_000),
+	contentBase64: z.string().min(1).max(2_800_000),
+});
+
+export const builderConversationCreateInput = z.object({
+	clientRequestId: z.uuid(),
+	commandType: z.enum(["CHAT", "CREATE_AGENT"]).default("CHAT"),
+	message: z.string().trim().min(1).max(20_000),
+	resources: z.array(builderResource).max(20).default([]),
+	attachments: z.array(builderAttachment).max(5).default([]),
+});
+
+export type BuilderConversationCreateInput = z.infer<
+	typeof builderConversationCreateInput
+>;
+
+export const builderConversationSubmitInput =
+	builderConversationCreateInput.extend({
+		id: z.string().min(1),
+	});
+
+export type BuilderConversationSubmitInput = z.infer<
+	typeof builderConversationSubmitInput
+>;
+
+export const sharedConversationInput = z.object({
+	token: z.string().trim().min(32).max(256),
+});
+
+export const builderResourceSearchInput = z.object({
+	q: z.string().trim().max(120).default(""),
+});
+
+export const builderResponseRatingInput = z.object({
+	id: z.string().min(1),
+	messageId: z.string().trim().min(1).max(240),
+	rating: z.enum(["UP", "DOWN"]).nullable(),
+});
diff --git a/apps/api/src/conversations/conversations.module.ts b/apps/api/src/conversations/conversations.module.ts
index 54df59fb..b39be8f1 100644
--- a/apps/api/src/conversations/conversations.module.ts
+++ b/apps/api/src/conversations/conversations.module.ts
@@ -1,11 +1,17 @@
 import { Module } from "@nestjs/common";
+import { AgentModule } from "../agent/agent.module";
 import { TrpcModule } from "../trpc/trpc.module";
+import { ConversationSharingService } from "./conversation-sharing.service";
 import { ConversationsRouter } from "./conversations.router";
 import { ConversationsService } from "./conversations.service";
 
 @Module({
-	imports: [TrpcModule],
-	providers: [ConversationsService, ConversationsRouter],
+	imports: [TrpcModule, AgentModule],
+	providers: [
+		ConversationsService,
+		ConversationSharingService,
+		ConversationsRouter,
+	],
 	exports: [ConversationsService],
 })
 export class ConversationsModule {}
diff --git a/apps/api/src/conversations/conversations.router.ts b/apps/api/src/conversations/conversations.router.ts
index ac66ba8b..87476f26 100644
--- a/apps/api/src/conversations/conversations.router.ts
+++ b/apps/api/src/conversations/conversations.router.ts
@@ -10,11 +10,17 @@ import {
 import type { z } from "zod";
 import type { AuthedTrpcContext } from "../trpc/context.types";
 import { AuthMiddleware } from "../trpc/middlewares/auth.middleware";
+import { ConversationSharingService } from "./conversation-sharing.service";
 import {
+	builderConversationCreateInput,
+	builderConversationSubmitInput,
+	builderResourceSearchInput,
+	builderResponseRatingInput,
 	conversationEventsInput,
 	conversationIdInput,
 	conversationListInput,
 	conversationSaveInput,
+	sharedConversationInput,
 } from "./conversations.contracts";
 import { ConversationsService } from "./conversations.service";
 
@@ -24,6 +30,8 @@ export class ConversationsRouter {
 	constructor(
 		@Inject(ConversationsService)
 		private readonly conversations: ConversationsService,
+		@Inject(ConversationSharingService)
+		private readonly sharing: ConversationSharingService,
 	) {}
 
 	@Query({ input: conversationListInput })
@@ -34,6 +42,21 @@ export class ConversationsRouter {
 		return this.conversations.list(input, ctx.user.id);
 	}
 
+	@Query()
+	async builderList(@Ctx() ctx: AuthedTrpcContext) {
+		return this.conversations.listBuilder(ctx.user.id);
+	}
+
+	@Query({ input: builderResourceSearchInput })
+	async builderResources(@Ctx() ctx: AuthedTrpcContext, @Input("q") q: string) {
+		return this.conversations.builderResources(q, ctx.user.id);
+	}
+
+	@Query({ input: conversationIdInput })
+	async builderById(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.conversations.builderById(id, ctx.user.id);
+	}
+
 	@Query({ input: conversationEventsInput })
 	async events(
 		@Ctx() ctx: AuthedTrpcContext,
@@ -50,6 +73,55 @@ export class ConversationsRouter {
 		return this.conversations.save(input, ctx.user.id);
 	}
 
+	@Mutation({ input: builderConversationCreateInput })
+	async createBuilder(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof builderConversationCreateInput>,
+	) {
+		return this.conversations.createBuilder(input, ctx.user.id);
+	}
+
+	@Mutation({ input: builderConversationSubmitInput })
+	async submitBuilder(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof builderConversationSubmitInput>,
+	) {
+		return this.conversations.submitBuilder(input, ctx.user.id);
+	}
+
+	@Mutation({ input: builderResponseRatingInput })
+	async rateBuilderResponse(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof builderResponseRatingInput>,
+	) {
+		return this.conversations.rateBuilderResponse(input, ctx.user.id);
+	}
+
+	@Mutation({ input: conversationIdInput })
+	async markRead(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.conversations.markRead(id, ctx.user.id);
+	}
+
+	@Query({ input: conversationIdInput })
+	async shareStatus(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.sharing.status(id, ctx.user.id);
+	}
+
+	@Mutation({ input: conversationIdInput })
+	async createShare(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.sharing.create(id, ctx.user.id);
+	}
+
+	@Mutation({ input: conversationIdInput })
+	async revokeShare(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
+		return this.sharing.revoke(id, ctx.user.id);
+	}
+
+	@Query({ input: sharedConversationInput })
+	async shared(@Ctx() ctx: AuthedTrpcContext, @Input("token") token: string) {
+		return this.sharing.resolve(token, ctx.user.id);
+	}
+
 	@Mutation({ input: conversationIdInput })
 	async remove(@Ctx() ctx: AuthedTrpcContext, @Input("id") id: string) {
 		return this.conversations.remove(id, ctx.user.id);
diff --git a/apps/api/src/conversations/conversations.service.ts b/apps/api/src/conversations/conversations.service.ts
index c28b7786..5f107476 100644
--- a/apps/api/src/conversations/conversations.service.ts
+++ b/apps/api/src/conversations/conversations.service.ts
@@ -1,4 +1,5 @@
-import type { Db } from "@crm/db";
+import { WORKSPACE_ID } from "@crm/auth";
+import type { Db, Prisma } from "@crm/db";
 import { CACHE_MANAGER } from "@nestjs/cache-manager";
 import {
 	BadRequestException,
@@ -6,10 +7,14 @@ import {
 	Injectable,
 	Logger,
 	NotFoundException,
+	Optional,
 } from "@nestjs/common";
 import type { Cache } from "cache-manager";
+import { AgentTriggerService } from "../agent/agent-trigger.service";
 import { InjectDatabase } from "../database/database.constants";
 import type {
+	BuilderConversationCreateInput,
+	BuilderConversationSubmitInput,
 	ConversationEventsInput,
 	ConversationListInput,
 	ConversationSaveInput,
@@ -25,6 +30,24 @@ export interface ConversationSummary {
 	lastMessageAt: string;
 }
 
+export interface BuilderConversationSummary {
+	id: string;
+	sessionId: string | null;
+	continuationToken: string | null;
+	streamIndex: number;
+	title: string | null;
+	messageCount: number;
+	lastMessageAt: string;
+	lastAssistantAt: string | null;
+	unread: boolean;
+	state: "working" | "unread" | "deployed" | "idle";
+	agent: {
+		id: string;
+		name: string;
+		status: string;
+	} | null;
+}
+
 const LIST_TTL_MS = 10 * 60_000;
 
 const listKey = (userId: string, recordId: string) =>
@@ -37,6 +60,7 @@ export class ConversationsService {
 	constructor(
 		@InjectDatabase() private readonly db: Db,
 		@Inject(CACHE_MANAGER) private readonly cache: Cache,
+		@Optional() private readonly agent?: AgentTriggerService,
 	) {}
 
 	async list(
@@ -71,16 +95,441 @@ export class ConversationsService {
 			},
 		});
 
-		const summaries = rows.map((row) => ({
-			...row,
-			lastMessageAt: row.lastMessageAt.toISOString(),
-		}));
+		const summaries = rows.flatMap((row) =>
+			row.sessionId
+				? [
+						{
+							...row,
+							sessionId: row.sessionId,
+							lastMessageAt: row.lastMessageAt.toISOString(),
+						},
+					]
+				: [],
+		);
 
 		await this.cache.set(key, summaries, LIST_TTL_MS);
 
 		return summaries;
 	}
 
+	async listBuilder(userId: string): Promise<BuilderConversationSummary[]> {
+		const rows = await this.db.agentConversation.findMany({
+			where: { userId, kind: "BUILDER" },
+			orderBy: { lastMessageAt: "desc" },
+			take: 50,
+			select: {
+				id: true,
+				sessionId: true,
+				continuationToken: true,
+				streamIndex: true,
+				title: true,
+				messageCount: true,
+				lastMessageAt: true,
+				lastAssistantAt: true,
+				lastReadAt: true,
+				agent: { select: { id: true, name: true, status: true } },
+				_count: {
+					select: {
+						submissions: { where: { commandType: "CREATE_AGENT" } },
+					},
+				},
+				submissions: {
+					where: { status: { in: ["PENDING", "SENDING"] } },
+					select: { id: true },
+					take: 1,
+				},
+			},
+		});
+
+		return rows.map((row) => {
+			const unread = Boolean(
+				row.lastAssistantAt &&
+					(!row.lastReadAt || row.lastAssistantAt > row.lastReadAt),
+			);
+			const working =
+				row.submissions.length > 0 ||
+				Boolean(row.sessionId && !row.continuationToken);
+
+			return {
+				id: row.id,
+				sessionId: row.sessionId,
+				continuationToken: row.continuationToken,
+				streamIndex: row.streamIndex,
+				title: row.title,
+				messageCount: row.messageCount,
+				lastMessageAt: row.lastMessageAt.toISOString(),
+				lastAssistantAt: row.lastAssistantAt?.toISOString() ?? null,
+				unread,
+				state:
+					row._count.submissions > 0 && row.agent?.status === "LIVE"
+						? "deployed"
+						: working
+							? "working"
+							: unread
+								? "unread"
+								: "idle",
+				agent: row.agent,
+			};
+		});
+	}
+
+	async builderResources(q: string, userId: string) {
+		const member = await this.db.member.findUnique({
+			where: {
+				organizationId_userId: { organizationId: WORKSPACE_ID, userId },
+			},
+			select: { id: true },
+		});
+
+		if (!member) {
+			throw new NotFoundException("No workspace membership was found.");
+		}
+
+		const search = q.trim();
+		const contains = search
+			? { contains: search, mode: "insensitive" as const }
+			: undefined;
+
+		const [companies, contacts, deals] = await Promise.all([
+			this.db.company.findMany({
+				where: contains ? { name: contains } : undefined,
+				orderBy: { lastActivityAt: { sort: "desc", nulls: "last" } },
+				take: 6,
+				select: { id: true, name: true, domain: true },
+			}),
+			this.db.contact.findMany({
+				where: contains
+					? {
+							OR: [
+								{ firstName: contains },
+								{ lastName: contains },
+								{ email: contains },
+							],
+						}
+					: undefined,
+				orderBy: { lastActivityAt: { sort: "desc", nulls: "last" } },
+				take: 6,
+				select: {
+					id: true,
+					firstName: true,
+					lastName: true,
+					email: true,
+					company: { select: { name: true } },
+				},
+			}),
+			this.db.deal.findMany({
+				where: contains ? { name: contains } : undefined,
+				orderBy: { lastActivityAt: { sort: "desc", nulls: "last" } },
+				take: 6,
+				select: {
+					id: true,
+					name: true,
+					company: { select: { name: true } },
+				},
+			}),
+		]);
+
+		return [
+			...companies.map((company) => ({
+				kind: "company" as const,
+				id: company.id,
+				label: company.name,
+				detail: company.domain,
+			})),
+			...contacts.map((contact) => ({
+				kind: "contact" as const,
+				id: contact.id,
+				label: [contact.firstName, contact.lastName].filter(Boolean).join(" "),
+				detail: contact.company?.name ?? contact.email,
+			})),
+			...deals.map((deal) => ({
+				kind: "deal" as const,
+				id: deal.id,
+				label: deal.name,
+				detail: deal.company.name,
+			})),
+		];
+	}
+
+	async builderById(id: string, userId: string) {
+		const row = await this.db.agentConversation.findFirst({
+			where: { id, userId, kind: "BUILDER" },
+			select: {
+				id: true,
+				sessionId: true,
+				continuationToken: true,
+				streamIndex: true,
+				title: true,
+				messageCount: true,
+				lastMessageAt: true,
+				lastAssistantAt: true,
+				lastReadAt: true,
+				agent: {
+					select: {
+						id: true,
+						name: true,
+						description: true,
+						status: true,
+						createdBy: { select: { id: true, name: true } },
+						currentVersion: {
+							select: {
+								id: true,
+								number: true,
+								status: true,
+								manifest: true,
+								modelId: true,
+								sandboxPolicy: true,
+								deployedAt: true,
+							},
+						},
+						triggers: {
+							orderBy: { createdAt: "asc" },
+							select: {
+								id: true,
+								type: true,
+								name: true,
+								config: true,
+								enabled: true,
+								nextRunAt: true,
+							},
+						},
+					},
+				},
+				createdVersions: {
+					orderBy: { number: "desc" },
+					take: 1,
+					select: {
+						id: true,
+						number: true,
+						status: true,
+						instructions: true,
+						manifest: true,
+						modelId: true,
+						sandboxPolicy: true,
+						validation: true,
+						createdAt: true,
+					},
+				},
+				feedback: {
+					where: { userId },
+					select: { messageId: true, rating: true },
+				},
+				submissions: {
+					orderBy: { createdAt: "asc" },
+					select: {
+						id: true,
+						clientRequestId: true,
+						commandType: true,
+						message: true,
+						status: true,
+						errorCode: true,
+						errorMessage: true,
+						createdAt: true,
+						sentAt: true,
+						acceptedAt: true,
+					},
+				},
+			},
+		});
+
+		if (!row) {
+			throw new NotFoundException(`No builder conversation with id ${id}.`);
+		}
+
+		return {
+			...row,
+			lastMessageAt: row.lastMessageAt.toISOString(),
+			lastAssistantAt: row.lastAssistantAt?.toISOString() ?? null,
+			lastReadAt: row.lastReadAt?.toISOString() ?? null,
+			agent: row.agent
+				? {
+						...row.agent,
+						currentVersion: row.agent.currentVersion
+							? {
+									...row.agent.currentVersion,
+									deployedAt:
+										row.agent.currentVersion.deployedAt?.toISOString() ?? null,
+								}
+							: null,
+						triggers: row.agent.triggers.map((trigger) => ({
+							...trigger,
+							nextRunAt: trigger.nextRunAt?.toISOString() ?? null,
+						})),
+					}
+				: null,
+			createdVersions: row.createdVersions.map((version) => ({
+				...version,
+				createdAt: version.createdAt.toISOString(),
+			})),
+			submissions: row.submissions.map((submission) => ({
+				...submission,
+				createdAt: submission.createdAt.toISOString(),
+				sentAt: submission.sentAt?.toISOString() ?? null,
+				acceptedAt: submission.acceptedAt?.toISOString() ?? null,
+			})),
+		};
+	}
+
+	async createBuilder(
+		input: BuilderConversationCreateInput,
+		userId: string,
+	): Promise<{ id: string }> {
+		const existing = await this.db.agentConversationSubmission.findUnique({
+			where: { clientRequestId: input.clientRequestId },
+			select: {
+				conversation: { select: { id: true, userId: true, kind: true } },
+			},
+		});
+
+		if (existing) {
+			if (
+				existing.conversation.userId !== userId ||
+				existing.conversation.kind !== "BUILDER"
+			) {
+				throw new BadRequestException("That request has already been used.");
+			}
+
+			return { id: existing.conversation.id };
+		}
+
+		const now = new Date();
+		const conversation = await this.db.agentConversation.create({
+			data: {
+				kind: "BUILDER",
+				userId,
+				title: this.titleFrom(input.message),
+				lastReadAt: now,
+				lastMessageAt: now,
+				submissions: {
+					create: {
+						submittedById: userId,
+						clientRequestId: input.clientRequestId,
+						commandType: input.commandType,
+						message: this.builderMessage(input),
+					},
+				},
+			},
+			select: { id: true },
+		});
+
+		this.agent?.builderConversationQueued();
+
+		return conversation;
+	}
+
+	async submitBuilder(
+		input: BuilderConversationSubmitInput,
+		userId: string,
+	): Promise<{ id: string }> {
+		const existing = await this.db.agentConversationSubmission.findUnique({
+			where: { clientRequestId: input.clientRequestId },
+			select: { id: true, conversationId: true, submittedById: true },
+		});
+
+		if (existing) {
+			if (
+				existing.conversationId !== input.id ||
+				existing.submittedById !== userId
+			) {
+				throw new BadRequestException("That request has already been used.");
+			}
+
+			return { id: existing.id };
+		}
+
+		const conversation = await this.db.agentConversation.findFirst({
+			where: { id: input.id, userId, kind: "BUILDER" },
+			select: { id: true },
+		});
+
+		if (!conversation) {
+			throw new NotFoundException(
+				`No builder conversation with id ${input.id}.`,
+			);
+		}
+
+		const submission = await this.db.$transaction(async (tx) => {
+			const created = await tx.agentConversationSubmission.create({
+				data: {
+					conversationId: input.id,
+					submittedById: userId,
+					clientRequestId: input.clientRequestId,
+					commandType: input.commandType,
+					message: this.builderMessage(input),
+				},
+				select: { id: true },
+			});
+
+			await tx.agentConversation.update({
+				where: { id: input.id },
+				data: { lastMessageAt: new Date(), lastReadAt: new Date() },
+			});
+
+			return created;
+		});
+
+		this.agent?.builderConversationQueued();
+
+		return submission;
+	}
+
+	async markRead(id: string, userId: string): Promise<{ id: string }> {
+		const updated = await this.db.agentConversation.updateMany({
+			where: { id, userId, kind: "BUILDER" },
+			data: { lastReadAt: new Date() },
+		});
+
+		if (updated.count === 0) {
+			throw new NotFoundException(`No builder conversation with id ${id}.`);
+		}
+
+		return { id };
+	}
+
+	async rateBuilderResponse(
+		input: { id: string; messageId: string; rating: "UP" | "DOWN" | null },
+		userId: string,
+	) {
+		const conversation = await this.db.agentConversation.findFirst({
+			where: { id: input.id, userId, kind: "BUILDER" },
+			select: { id: true },
+		});
+
+		if (!conversation) {
+			throw new NotFoundException(
+				`No builder conversation with id ${input.id}.`,
+			);
+		}
+
+		const key = {
+			conversationId_userId_messageId: {
+				conversationId: input.id,
+				userId,
+				messageId: input.messageId,
+			},
+		};
+
+		if (!input.rating) {
+			await this.db.agentConversationFeedback.deleteMany({
+				where: key.conversationId_userId_messageId,
+			});
+			return { id: input.messageId, rating: null };
+		}
+
+		await this.db.agentConversationFeedback.upsert({
+			where: key,
+			create: {
+				conversationId: input.id,
+				userId,
+				messageId: input.messageId,
+				rating: input.rating,
+			},
+			update: { rating: input.rating },
+		});
+
+		return { id: input.messageId, rating: input.rating };
+	}
+
 	async save(
 		input: ConversationSaveInput,
 		userId: string,
@@ -130,6 +579,8 @@ export class ConversationsService {
 			throw new NotFoundException(`No conversation with id ${input.id}.`);
 		}
 
+		if (!conversation.sessionId) return [];
+
 		const events = await this.db.agentEvent.findMany({
 			where: { sessionId: conversation.sessionId },
 			orderBy: { emittedAt: "asc" },
@@ -161,22 +612,19 @@ export class ConversationsService {
 			throw new NotFoundException(`No conversation with id ${id}.`);
 		}
 
-		await this.db.$transaction([
-			this.db.agentEvent.deleteMany({
-				where: { sessionId: conversation.sessionId },
-			}),
-			this.db.agentConversation.delete({ where: { id } }),
-		]);
+		await this.db.$transaction(async (tx) => {
+			if (conversation.sessionId) {
+				await tx.agentEvent.deleteMany({
+					where: { sessionId: conversation.sessionId },
+				});
+			}
 
-		await this.cache.del(
-			listKey(
-				userId,
-				conversation.contactId ??
-					conversation.companyId ??
-					conversation.dealId ??
-					"",
-			),
-		);
+			await tx.agentConversation.delete({ where: { id } });
+		});
+
+		const recordId =
+			conversation.contactId ?? conversation.companyId ?? conversation.dealId;
+		if (recordId) await this.cache.del(listKey(userId, recordId));
 
 		this.logger.log({ message: "Conversation removed", conversationId: id });
 
@@ -198,4 +646,23 @@ export class ConversationsService {
 
 		return recordId;
 	}
+
+	private builderMessage(input: {
+		message: string;
+		resources: BuilderConversationCreateInput["resources"];
+		attachments: BuilderConversationCreateInput["attachments"];
+	}): Prisma.InputJsonValue {
+		return {
+			text: input.message,
+			resources: input.resources,
+			attachments: input.attachments,
+		};
+	}
+
+	private titleFrom(message: string): string {
+		const normalized = message.replace(/\s+/g, " ").trim();
+		return normalized.length <= 80
+			? normalized
+			: `${normalized.slice(0, 77).trimEnd()}…`;
+	}
 }
diff --git a/apps/api/src/generated/server.ts b/apps/api/src/generated/server.ts
index 499b12df..ae32c91e 100644
--- a/apps/api/src/generated/server.ts
+++ b/apps/api/src/generated/server.ts
@@ -14,9 +14,10 @@ import { z } from "zod";
 const t = initTRPC.create();
 const publicProcedure = t.procedure;
 import { timelineInput, timelineCountsInput, myTasksInput, activityCreateInput, completeInput } from "../activities/activities.contracts";
+import { agentIdInput, agentHistoryInput, agentUpdateInput, agentDeployInput, agentRunNowInput } from "../agent/agents.contracts";
 import { companyListInput, companyIdInput, companyOptionsInput, companyCreateInput, companyUpdateArgs, setPrimaryContactInput } from "../companies/companies.contracts";
 import { contactListInput, contactIdInput, contactCreateInput, contactUpdateArgs, factDecisionInput } from "../contacts/contacts.contracts";
-import { conversationListInput, conversationEventsInput, conversationSaveInput, conversationIdInput } from "../conversations/conversations.contracts";
+import { conversationListInput, builderResourceSearchInput, conversationIdInput, conversationEventsInput, conversationSaveInput, builderConversationCreateInput, builderConversationSubmitInput, builderResponseRatingInput, sharedConversationInput } from "../conversations/conversations.contracts";
 import { dashboardSummaryInput } from "../dashboard/dashboard.contracts";
 import { dealListInput, dealIdInput, dealCreateInput, dealUpdateArgs, setStageInput } from "../deals/deals.contracts";
 import { setAutoCreateInput, suppressDomainInput, threadInput, calendarEventInput } from "../google/google.contracts";
@@ -24,6 +25,7 @@ import { setAgentModelInput, setResearchKeyInput } from "../settings/settings.co
 import { ssoProviderListInput, registerSsoProviderInput, deleteSsoProviderInput } from "../sso/sso.contracts";
 import { memberListInput, updateWorkspaceInput, setMemberRoleInput } from "../workspace/workspace.contracts";
 import type { ActivitiesRouter } from "../activities/activities.router";
+import type { AgentsRouter } from "../agent/agents.router";
 import type { CompaniesRouter } from "../companies/companies.router";
 import type { ContactsRouter } from "../contacts/contacts.router";
 import type { ConversationsRouter } from "../conversations/conversations.router";
@@ -54,6 +56,43 @@ const appRouter = t.router({
       .input(completeInput)
       .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ActivitiesRouter["complete"]>>)
     }),
+  agents: t.router({
+    list: publicProcedure
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["list"]>>),
+    byId: publicProcedure
+      .input(agentIdInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["byId"]>>),
+    history: publicProcedure
+      .input(agentHistoryInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["history"]>>),
+    activity: publicProcedure
+      .input(agentHistoryInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["activity"]>>),
+    update: publicProcedure
+      .input(agentUpdateInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["update"]>>),
+    deploy: publicProcedure
+      .input(agentDeployInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["deploy"]>>),
+    pause: publicProcedure
+      .input(agentIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["pause"]>>),
+    resume: publicProcedure
+      .input(agentIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["resume"]>>),
+    archive: publicProcedure
+      .input(agentIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["archive"]>>),
+    restore: publicProcedure
+      .input(agentIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["restore"]>>),
+    remove: publicProcedure
+      .input(agentIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["remove"]>>),
+    runNow: publicProcedure
+      .input(agentRunNowInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<AgentsRouter["runNow"]>>)
+    }),
   companies: t.router({
     list: publicProcedure
       .input(companyListInput)
@@ -110,12 +149,44 @@ const appRouter = t.router({
     list: publicProcedure
       .input(conversationListInput)
       .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["list"]>>),
+    builderList: publicProcedure
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["builderList"]>>),
+    builderResources: publicProcedure
+      .input(builderResourceSearchInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["builderResources"]>>),
+    builderById: publicProcedure
+      .input(conversationIdInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["builderById"]>>),
     events: publicProcedure
       .input(conversationEventsInput)
       .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["events"]>>),
     save: publicProcedure
       .input(conversationSaveInput)
       .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["save"]>>),
+    createBuilder: publicProcedure
+      .input(builderConversationCreateInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["createBuilder"]>>),
+    submitBuilder: publicProcedure
+      .input(builderConversationSubmitInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["submitBuilder"]>>),
+    rateBuilderResponse: publicProcedure
+      .input(builderResponseRatingInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["rateBuilderResponse"]>>),
+    markRead: publicProcedure
+      .input(conversationIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["markRead"]>>),
+    shareStatus: publicProcedure
+      .input(conversationIdInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["shareStatus"]>>),
+    createShare: publicProcedure
+      .input(conversationIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["createShare"]>>),
+    revokeShare: publicProcedure
+      .input(conversationIdInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["revokeShare"]>>),
+    shared: publicProcedure
+      .input(sharedConversationInput)
+      .query(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["shared"]>>),
     remove: publicProcedure
       .input(conversationIdInput)
       .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["remove"]>>)
diff --git a/apps/api/test/conversations.spec.ts b/apps/api/test/conversations.spec.ts
index 8bc5bbb5..51a40ba1 100644
--- a/apps/api/test/conversations.spec.ts
+++ b/apps/api/test/conversations.spec.ts
@@ -25,6 +25,7 @@ let service: ConversationsService;
 let cache: ReturnType<typeof memoryCache>;
 
 beforeAll(async () => {
+	await db.agentConversation.deleteMany({ where: { userId } });
 	await db.user.deleteMany({ where: { id: userId } });
 	await db.contact.deleteMany({ where: { email } });
 
@@ -46,6 +47,7 @@ beforeAll(async () => {
 
 afterAll(async () => {
 	await db.contact.deleteMany({ where: { email } });
+	await db.agentConversation.deleteMany({ where: { userId } });
 	await db.user.deleteMany({ where: { id: userId } });
 });
 
@@ -159,4 +161,34 @@ describe("ConversationsService", () => {
 
 		expect(service.remove(conversation.id, "somebody-else")).rejects.toThrow();
 	});
+
+	it("persists the command type that controls agent creation", async () => {
+		const chat = await service.createBuilder(
+			{
+				clientRequestId: crypto.randomUUID(),
+				commandType: "CHAT",
+				message: "Tell me about this customer",
+				resources: [],
+				attachments: [],
+			},
+			userId,
+		);
+		const creation = await service.createBuilder(
+			{
+				clientRequestId: crypto.randomUUID(),
+				commandType: "CREATE_AGENT",
+				message: "/Create agent Flag stalled deals",
+				resources: [],
+				attachments: [],
+			},
+			userId,
+		);
+
+		expect(
+			(await service.builderById(chat.id, userId)).submissions[0],
+		).toMatchObject({ commandType: "CHAT" });
+		expect(
+			(await service.builderById(creation.id, userId)).submissions[0],
+		).toMatchObject({ commandType: "CREATE_AGENT" });
+	});
 });
diff --git a/apps/app/app/(app)/(agent-builder)/agent/page.tsx b/apps/app/app/(app)/(agent-builder)/agent/page.tsx
new file mode 100644
index 00000000..8b10fb70
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/agent/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default async function AgentBuilderPage() {
+	redirect("/agents");
+}
diff --git a/apps/app/app/(app)/(agent-builder)/agents/[agentId]/page.tsx b/apps/app/app/(app)/(agent-builder)/agents/[agentId]/page.tsx
new file mode 100644
index 00000000..ea85f69f
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/agents/[agentId]/page.tsx
@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import { TeamAgentDetail } from "@/components/agent-builder/team-agent-detail";
+import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+
+export const metadata: Metadata = { title: "Team agent" };
+
+export default async function TeamAgentPage({
+	params,
+}: {
+	params: Promise<{ agentId: string }>;
+}) {
+	const { agentId } = await params;
+	const trpc = getServerTrpc();
+	const queryClient = getServerQueryClient();
+
+	await Promise.all([
+		queryClient.prefetchQuery(trpc.agents.byId.queryOptions({ id: agentId })),
+		queryClient.prefetchQuery(
+			trpc.agents.history.queryOptions({ id: agentId, limit: 50 }),
+		),
+		queryClient.prefetchQuery(
+			trpc.agents.activity.queryOptions({ id: agentId, limit: 100 }),
+		),
+	]);
+
+	return <TeamAgentDetail agentId={agentId} />;
+}
diff --git a/apps/app/app/(app)/(agent-builder)/agents/page.tsx b/apps/app/app/(app)/(agent-builder)/agents/page.tsx
new file mode 100644
index 00000000..f884d82f
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/agents/page.tsx
@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import { AgentBuilderHome } from "@/components/agent-builder/agent-builder-home";
+import { requireSession } from "@/lib/session";
+import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+
+export const metadata: Metadata = { title: "Agents" };
+
+export default async function AgentsPage() {
+	const session = await requireSession();
+	const trpc = getServerTrpc();
+	const queryClient = getServerQueryClient();
+
+	await Promise.all([
+		queryClient.prefetchQuery(
+			trpc.conversations.builderResources.queryOptions({ q: "" }),
+		),
+		queryClient.prefetchQuery(trpc.google.status.queryOptions()),
+	]);
+
+	return <AgentBuilderHome name={session.user.name} />;
+}
diff --git a/apps/app/app/(app)/(agent-builder)/agents/team/page.tsx b/apps/app/app/(app)/(agent-builder)/agents/team/page.tsx
new file mode 100644
index 00000000..de732046
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/agents/team/page.tsx
@@ -0,0 +1,8 @@
+import type { Metadata } from "next";
+import { TeamAgentsIndex } from "@/components/agent-builder/team-agents-index";
+
+export const metadata: Metadata = { title: "Team agents" };
+
+export default function TeamAgentsListPage() {
+	return <TeamAgentsIndex />;
+}
diff --git a/apps/app/app/(app)/(agent-builder)/chat/[chatId]/page.tsx b/apps/app/app/(app)/(agent-builder)/chat/[chatId]/page.tsx
new file mode 100644
index 00000000..ed82eb81
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/chat/[chatId]/page.tsx
@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import { AgentBuilderChat } from "@/components/agent-builder/agent-builder-chat";
+import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+
+export const metadata: Metadata = { title: "Agent chat" };
+
+export default async function AgentChatPage({
+	params,
+}: {
+	params: Promise<{ chatId: string }>;
+}) {
+	const { chatId } = await params;
+	const trpc = getServerTrpc();
+	const queryClient = getServerQueryClient();
+
+	void queryClient.prefetchQuery(
+		trpc.conversations.builderById.queryOptions({ id: chatId }),
+	);
+
+	return <AgentBuilderChat conversationId={chatId} />;
+}
diff --git a/apps/app/app/(app)/(agent-builder)/layout.tsx b/apps/app/app/(app)/(agent-builder)/layout.tsx
new file mode 100644
index 00000000..b4de3375
--- /dev/null
+++ b/apps/app/app/(app)/(agent-builder)/layout.tsx
@@ -0,0 +1,21 @@
+import { AgentBuilderShell } from "@/components/agent-builder/agent-builder-shell";
+import { HydrateClient } from "@/lib/trpc/hydrate";
+import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+
+export default async function AgentBuilderLayout({
+	children,
+}: Readonly<{ children: React.ReactNode }>) {
+	const trpc = getServerTrpc();
+	const queryClient = getServerQueryClient();
+
+	await Promise.all([
+		queryClient.prefetchQuery(trpc.conversations.builderList.queryOptions()),
+		queryClient.prefetchQuery(trpc.agents.list.queryOptions()),
+	]);
+
+	return (
+		<HydrateClient>
+			<AgentBuilderShell>{children}</AgentBuilderShell>
+		</HydrateClient>
+	);
+}
diff --git a/apps/app/app/eve/v1/[...path]/route.ts b/apps/app/app/eve/v1/[...path]/route.ts
index ed6d815f..deafca16 100644
--- a/apps/app/app/eve/v1/[...path]/route.ts
+++ b/apps/app/app/eve/v1/[...path]/route.ts
@@ -1,3 +1,4 @@
+import { db } from "@crm/db";
 import {
 	AGENT_URL,
 	bridgeConfigured,
@@ -44,9 +45,35 @@ async function handler(request: Request): Promise<Response> {
 	const contactId = request.headers.get("x-crm-contact");
 	const companyId = request.headers.get("x-crm-company");
 	const dealId = request.headers.get("x-crm-deal");
+	const builderConversationId = request.headers.get(
+		"x-crm-builder-conversation",
+	);
 	headers.delete("x-crm-contact");
 	headers.delete("x-crm-company");
 	headers.delete("x-crm-deal");
+	headers.delete("x-crm-builder-conversation");
+
+	if (builderConversationId) {
+		const conversation = await db.agentConversation.findFirst({
+			where: {
+				id: builderConversationId,
+				userId: session.user.id,
+				kind: "BUILDER",
+			},
+			select: { sessionId: true },
+		});
+		const requestedSession = sessionFromPath(url.pathname);
+
+		if (
+			!conversation ||
+			(requestedSession && conversation.sessionId !== requestedSession)
+		) {
+			return Response.json(
+				{ error: "Conversation not found." },
+				{ status: 404 },
+			);
+		}
+	}
 
 	headers.set(
 		"authorization",
@@ -119,3 +146,8 @@ export {
 function cuid(value: string | null): string | undefined {
 	return value && /^[a-z0-9]{20,32}$/.test(value) ? value : undefined;
 }
+
+function sessionFromPath(pathname: string): string | null {
+	const match = pathname.match(/\/eve\/v1\/session\/([^/]+)/);
+	return match?.[1] ? decodeURIComponent(match[1]) : null;
+}
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
new file mode 100644
index 00000000..bb6b4f8d
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -0,0 +1,999 @@
+"use client";
+
+import Add from "@carbon/icons-react/es/Add";
+import ArrowRight from "@carbon/icons-react/es/ArrowRight";
+import Checkmark from "@carbon/icons-react/es/Checkmark";
+import CheckmarkFilled from "@carbon/icons-react/es/CheckmarkFilled";
+import Copy from "@carbon/icons-react/es/Copy";
+import Play from "@carbon/icons-react/es/Play";
+import Renew from "@carbon/icons-react/es/Renew";
+import ThumbsDown from "@carbon/icons-react/es/ThumbsDown";
+import ThumbsUp from "@carbon/icons-react/es/ThumbsUp";
+import WarningAlt from "@carbon/icons-react/es/WarningAlt";
+import { Button } from "@crm/ui/components/button";
+import { Icon } from "@crm/ui/components/icon";
+import { Markdown } from "@crm/ui/components/markdown";
+import { cn } from "@crm/ui/lib/utils";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { MessageStreamEvent } from "eve/client";
+import { useEveAgent } from "eve/react";
+import Link from "next/link";
+import { useState } from "react";
+import { toast } from "sonner";
+import { hasCreateAgentCommand } from "@/lib/agent-builder";
+import {
+	type AgentTurnFailure,
+	latestTurnFailure,
+	toTranscript,
+} from "@/lib/agent-transcript";
+import { useTRPC } from "@/lib/trpc/client";
+import type { RouterOutputs } from "@/lib/trpc/types";
+import { AgentComposer, type BuilderPrompt } from "./agent-composer";
+import { ShareChatDialog } from "./share-chat-dialog";
+
+type Conversation = RouterOutputs["conversations"]["builderById"];
+type SharedConversation = RouterOutputs["conversations"]["shared"];
+
+type DraftVersion = {
+	id: string;
+	status: string;
+	manifest: unknown;
+};
+
+type BuilderSubmission = {
+	id: string;
+	commandType: "CHAT" | "CREATE_AGENT";
+	message: unknown;
+	status: string;
+	errorMessage: string | null;
+};
+
+export function AgentBuilderChat({
+	conversationId,
+}: {
+	conversationId: string;
+}) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const conversation = useQuery({
+		...trpc.conversations.builderById.queryOptions({ id: conversationId }),
+		refetchInterval: (query) => {
+			const data = query.state.data;
+			return data?.agent?.status === "LIVE" ? 10_000 : 2500;
+		},
+	});
+	const shared = useQuery({
+		...trpc.conversations.shared.queryOptions({ token: conversationId }),
+		enabled: conversation.isError,
+		refetchInterval: 10_000,
+	});
+	const events = useQuery({
+		...trpc.conversations.events.queryOptions({
+			id: conversationId,
+			limit: 5000,
+		}),
+		enabled: Boolean(conversation.data?.sessionId),
+		refetchInterval: 2500,
+	});
+	const submit = useMutation(
+		trpc.conversations.submitBuilder.mutationOptions({
+			onSuccess: async () => {
+				await Promise.all([
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderById.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderList.pathKey(),
+					}),
+				]);
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+	const markRead = useMutation(
+		trpc.conversations.markRead.mutationOptions({
+			onSuccess: () =>
+				queryClient.invalidateQueries({
+					queryKey: trpc.conversations.builderList.pathKey(),
+				}),
+		}),
+	);
+
+	if (conversation.isPending || (conversation.isError && shared.isPending)) {
+		return <ChatLoading />;
+	}
+
+	if (conversation.isError) {
+		if (shared.data) {
+			return <SharedAgentChat conversation={shared.data} />;
+		}
+
+		return (
+			<main className="flex flex-1 items-center justify-center p-8">
+				<div className="max-w-md text-center">
+					<h1 className="font-medium text-lg">Chat unavailable</h1>
+					<p className="mt-2 text-muted-foreground text-sm">
+						{conversation.error.message}
+					</p>
+					<Button asChild variant="outline" className="mt-5">
+						<Link href="/agents">Start a new chat</Link>
+					</Button>
+				</div>
+			</main>
+		);
+	}
+
+	const data = conversation.data;
+	const submissions = data.submissions as BuilderSubmission[];
+	const failure = latestTurnFailure(events.data ?? []);
+	const creatingAgent = hasCreateAgentCommand(submissions);
+	const working = isWorking(data, creatingAgent) && !failure;
+	const retryPrompt = retryPromptOf(submissions.at(-1));
+	const send = (prompt: BuilderPrompt) => {
+		submit.mutate({
+			id: conversationId,
+			clientRequestId: crypto.randomUUID(),
+			...prompt,
+		});
+	};
+
+	return (
+		<main
+			className="flex min-h-0 flex-1 flex-col"
+			onPointerEnter={() => {
+				if (
+					data.lastAssistantAt &&
+					(!data.lastReadAt ||
+						new Date(data.lastAssistantAt) > new Date(data.lastReadAt)) &&
+					!markRead.isPending
+				) {
+					markRead.mutate({ id: conversationId });
+				}
+			}}
+		>
+			<ChatHeader
+				conversation={data}
+				working={working}
+				creatingAgent={creatingAgent}
+			/>
+
+			<div className="min-h-0 flex-1 overflow-y-auto">
+				<div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 py-6 sm:gap-5 sm:px-5 sm:py-9">
+					{submissions.map((submission) => (
+						<UserSubmission
+							key={submission.id}
+							message={submissionText(submission.message)}
+							failed={submission.status === "FAILED"}
+							error={submission.errorMessage}
+						/>
+					))}
+
+					{events.data && events.data.length > 0 ? (
+						<AssistantTranscript
+							key={`${events.data.length}:${events.data.at(-1)?.meta.id}`}
+							conversation={data}
+							events={events.data as unknown as MessageStreamEvent[]}
+						/>
+					) : null}
+
+					{working && creatingAgent ? (
+						<BuildingAgentCard
+							conversationId={conversationId}
+							sessionId={data.sessionId}
+							eventCount={events.data?.length ?? 0}
+						/>
+					) : null}
+
+					{!working &&
+					failure &&
+					creatingAgent &&
+					!reviewable(data) &&
+					data.agent?.status !== "LIVE" ? (
+						<BuilderFailureCard
+							failure={failure}
+							creatingAgent
+							retrying={submit.isPending}
+							onRetry={retryPrompt ? () => send(retryPrompt) : null}
+						/>
+					) : null}
+
+					{!working && failure && !creatingAgent ? (
+						<BuilderFailureCard
+							failure={failure}
+							creatingAgent={false}
+							retrying={submit.isPending}
+							onRetry={retryPrompt ? () => send(retryPrompt) : null}
+						/>
+					) : null}
+
+					{creatingAgent && reviewable(data) ? (
+						<ReviewAgentCard conversation={data} />
+					) : null}
+
+					{creatingAgent && data.agent?.status === "LIVE" ? (
+						<DeployedAgentCard
+							conversation={data}
+							onFollowUp={(message) =>
+								send({
+									commandType: "CHAT",
+									message,
+									resources: [],
+									attachments: [],
+								})
+							}
+						/>
+					) : null}
+				</div>
+			</div>
+
+			<div className="shrink-0 border-t px-4 py-3 sm:px-5">
+				<div className="mx-auto w-full max-w-3xl">
+					<AgentComposer
+						mode="chat"
+						pending={submit.isPending}
+						disabled={working}
+						onSubmit={send}
+					/>
+				</div>
+			</div>
+		</main>
+	);
+}
+
+function SharedAgentChat({
+	conversation,
+}: {
+	conversation: SharedConversation;
+}) {
+	const submissions = conversation.submissions as BuilderSubmission[];
+	const events = conversation.events as unknown as MessageStreamEvent[];
+
+	return (
+		<main className="flex min-h-0 flex-1 flex-col">
+			<header className="flex h-12 shrink-0 items-center gap-3 border-b px-5">
+				<h1 className="min-w-0 flex-1 truncate font-medium text-sm">
+					{conversation.agent?.name ?? conversation.title ?? "Agent builder"}
+				</h1>
+				<span className="text-muted-foreground text-xs">Read-only</span>
+			</header>
+
+			<div className="min-h-0 flex-1 overflow-y-auto">
+				<div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 py-6 sm:gap-5 sm:px-5 sm:py-9">
+					<div className="rounded-lg border bg-card px-4 py-3 text-sm">
+						<p className="font-medium">Shared by {conversation.ownerName}</p>
+						<p className="mt-1 text-muted-foreground text-xs">
+							You can read this builder chat, but only its owner can continue or
+							change it.
+						</p>
+					</div>
+
+					{submissions.map((submission) => (
+						<UserSubmission
+							key={submission.id}
+							message={submissionText(submission.message)}
+							failed={submission.status === "FAILED"}
+							error={submission.errorMessage}
+						/>
+					))}
+
+					{events.length > 0 ? (
+						<SharedAssistantTranscript events={events} />
+					) : null}
+				</div>
+			</div>
+		</main>
+	);
+}
+
+function SharedAssistantTranscript({
+	events,
+}: {
+	events: MessageStreamEvent[];
+}) {
+	const agent = useEveAgent({ initialEvents: events });
+	const messages = toTranscript(agent.data.messages).filter(
+		(message) => !message.mine,
+	);
+
+	return messages.map((message) => {
+		const markdown = message.items
+			.filter((item) => item.kind === "said")
+			.map((item) => item.text)
+			.join("\n\n");
+
+		return markdown ? (
+			<div
+				key={message.id}
+				className="flex w-full min-w-0 max-w-[640px] flex-col gap-2"
+			>
+				<Markdown className="wrap-break-word text-sm leading-5">
+					{markdown}
+				</Markdown>
+				<Button
+					variant="ghost"
+					size="icon-xs"
+					aria-label="Copy response as Markdown"
+					onClick={() => {
+						void navigator.clipboard.writeText(markdown);
+						toast.success("Response copied as Markdown.");
+					}}
+				>
+					<Icon icon={Copy} />
+				</Button>
+			</div>
+		) : null;
+	});
+}
+
+function ChatHeader({
+	conversation,
+	working,
+	creatingAgent,
+}: {
+	conversation: Conversation;
+	working: boolean;
+	creatingAgent: boolean;
+}) {
+	const title =
+		(creatingAgent ? conversation.agent?.name : null) ??
+		conversation.title ??
+		"Agent chat";
+
+	return (
+		<header className="flex h-12 shrink-0 items-center gap-2 border-b px-4 sm:gap-2.5 sm:pr-4 sm:pl-5">
+			<div className="flex min-w-0 flex-1 items-center gap-2 sm:gap-3">
+				<h1 className="truncate font-medium text-sm">{title}</h1>
+				<span className="hidden shrink-0 text-muted-foreground text-xs sm:inline">
+					Private
+				</span>
+				{working ? (
+					<span className="flex shrink-0 items-center gap-2 text-muted-foreground text-xs">
+						<Icon
+							icon={Renew}
+							className="size-3.5 animate-spin text-ring"
+							motion="none"
+						/>
+						<span className="sr-only">Working in background</span>
+						<span aria-hidden="true" className="hidden sm:inline">
+							Working in background
+						</span>
+					</span>
+				) : null}
+			</div>
+			<Button asChild variant="ghost" size="icon-sm">
+				<Link href="/agents" aria-label="Start a new chat">
+					<Icon icon={Add} />
+				</Link>
+			</Button>
+			<ShareChatDialog conversationId={conversation.id} title={title} />
+		</header>
+	);
+}
+
+function UserSubmission({
+	message,
+	failed,
+	error,
+}: {
+	message: string;
+	failed: boolean;
+	error: string | null;
+}) {
+	return (
+		<div className="flex min-w-0 w-full justify-end">
+			<div className="w-fit min-w-0 max-w-full rounded-md bg-muted px-3 py-2.5 text-sm leading-5 sm:max-w-[620px] sm:px-3.5 sm:py-3">
+				<p className="wrap-break-word">{message}</p>
+				{failed ? (
+					<p className="mt-2 text-destructive text-xs">
+						{error ?? "This message could not be sent."}
+					</p>
+				) : null}
+			</div>
+		</div>
+	);
+}
+
+function AssistantTranscript({
+	conversation,
+	events,
+}: {
+	conversation: Conversation;
+	events: MessageStreamEvent[];
+}) {
+	const agent = useEveAgent({ initialEvents: events });
+	const messages = toTranscript(agent.data.messages).filter(
+		(message) => !message.mine,
+	);
+
+	return (
+		<>
+			{messages.map((message) => {
+				const markdown = message.items
+					.filter((item) => item.kind === "said")
+					.map((item) => item.text)
+					.join("\n\n");
+
+				return (
+					<div
+						key={message.id}
+						className="flex w-full min-w-0 max-w-[640px] flex-col gap-2"
+					>
+						{markdown ? (
+							<Markdown className="wrap-break-word text-sm leading-5">
+								{markdown}
+							</Markdown>
+						) : null}
+						{message.items
+							.filter((item) => item.kind === "did")
+							.map((item) => (
+								<div
+									key={item.id}
+									className="flex min-w-0 items-start gap-2 text-muted-foreground text-xs"
+								>
+									{item.pending ? (
+										<Icon
+											icon={Renew}
+											className="size-3.5 animate-spin"
+											motion="none"
+										/>
+									) : (
+										<Icon icon={Checkmark} className="size-3.5 text-ring" />
+									)}
+									<span className="min-w-0 wrap-break-word">{item.label}</span>
+								</div>
+							))}
+						{markdown ? (
+							<ResponseActions
+								conversation={conversation}
+								messageId={message.id}
+								markdown={markdown}
+							/>
+						) : null}
+					</div>
+				);
+			})}
+		</>
+	);
+}
+
+function ResponseActions({
+	conversation,
+	messageId,
+	markdown,
+}: {
+	conversation: Conversation;
+	messageId: string;
+	markdown: string;
+}) {
+	const trpc = useTRPC();
+	const initial = conversation.feedback.find(
+		(item) => item.messageId === messageId,
+	)?.rating;
+	const [rating, setRating] = useState<"UP" | "DOWN" | null>(initial ?? null);
+	const rate = useMutation(
+		trpc.conversations.rateBuilderResponse.mutationOptions({
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	const choose = (next: "UP" | "DOWN") => {
+		const value = rating === next ? null : next;
+		setRating(value);
+		rate.mutate({ id: conversation.id, messageId, rating: value });
+	};
+
+	return (
+		<div className="flex h-7 items-center gap-0.5">
+			<Button
+				variant="ghost"
+				size="icon-xs"
+				aria-label="Copy response as Markdown"
+				onClick={() => {
+					void navigator.clipboard.writeText(markdown);
+					toast.success("Response copied as Markdown.");
+				}}
+			>
+				<Icon icon={Copy} />
+			</Button>
+			<Button
+				variant="ghost"
+				size="icon-xs"
+				aria-label="Rate response helpful"
+				aria-pressed={rating === "UP"}
+				className={cn(rating === "UP" && "bg-muted text-foreground")}
+				onClick={() => choose("UP")}
+			>
+				<Icon icon={ThumbsUp} />
+			</Button>
+			<Button
+				variant="ghost"
+				size="icon-xs"
+				aria-label="Rate response not helpful"
+				aria-pressed={rating === "DOWN"}
+				className={cn(rating === "DOWN" && "bg-muted text-foreground")}
+				onClick={() => choose("DOWN")}
+			>
+				<Icon icon={ThumbsDown} />
+			</Button>
+		</div>
+	);
+}
+
+function BuildingAgentCard({
+	conversationId,
+	sessionId,
+	eventCount,
+}: {
+	conversationId: string;
+	sessionId: string | null;
+	eventCount: number;
+}) {
+	const [stopping, setStopping] = useState(false);
+	const completed = Math.min(
+		3,
+		sessionId ? Math.max(1, Math.floor(eventCount / 4)) : 0,
+	);
+	const steps = [
+		["Read the CRM data model", "Companies · contacts · deals"],
+		["Resolved the requested records", "Scoped to this workspace"],
+		["Checked connected integrations", "Only available connections"],
+		["Preparing the agent", "Isolated Vercel Sandbox"],
+	] as const;
+
+	return (
+		<div className="flex flex-col gap-4">
+			<p className="max-w-[640px] text-pretty text-sm leading-5">
+				I’m turning this into a team agent. I’ll inspect the CRM scope, verify
+				the requested connections, then prepare a safe deployment for review.
+			</p>
+			<div className="overflow-hidden rounded-lg border bg-card">
+				<div className="flex flex-wrap items-center gap-3 border-b px-4 py-3 sm:gap-4 sm:px-5 sm:py-4">
+					<Icon
+						icon={Renew}
+						className="size-3.5 animate-spin text-ring"
+						motion="none"
+					/>
+					<span className="min-w-0 flex-1 font-medium text-sm">
+						Building the agent
+					</span>
+					<span className="font-mono text-muted-foreground text-xs">
+						{completed} of 4
+					</span>
+					<Button
+						variant="outline"
+						size="sm"
+						disabled={!sessionId || stopping}
+						onClick={() => {
+							if (!sessionId) return;
+							setStopping(true);
+							void fetch(`/eve/v1/session/${sessionId}/cancel`, {
+								method: "POST",
+								headers: { "x-crm-builder-conversation": conversationId },
+							})
+								.then(async (response) => {
+									if (!response.ok) {
+										throw new Error(await response.text());
+									}
+									toast.success("Stop requested.");
+								})
+								.catch(() => {
+									setStopping(false);
+									toast.error("The agent could not be stopped. Try again.");
+								});
+						}}
+					>
+						{stopping ? "Stopping" : "Stop"}
+					</Button>
+				</div>
+				{steps.map(([label, detail], index) => (
+					<div
+						key={label}
+						className="flex min-h-10 items-start gap-3 border-t px-4 py-2.5 first:border-t-0 sm:h-8 sm:min-h-0 sm:items-center sm:gap-4 sm:px-5 sm:py-0"
+					>
+						<span className="flex size-5 shrink-0 items-center justify-center">
+							{index < completed ? (
+								<Icon icon={Checkmark} className="size-3.5 text-ring" />
+							) : index === completed ? (
+								<Icon
+									icon={Renew}
+									className="size-3.5 animate-spin text-muted-foreground"
+									motion="none"
+								/>
+							) : null}
+						</span>
+						<span className="min-w-0 flex-1 wrap-break-word text-sm">
+							{label}
+						</span>
+						<span className="min-w-0 max-w-[45%] text-right text-muted-foreground text-xs sm:w-60 sm:max-w-none sm:shrink-0">
+							{detail}
+						</span>
+					</div>
+				))}
+				<p className="border-t px-4 py-3 text-muted-foreground text-xs sm:px-5">
+					This chat keeps running if you leave. You’ll see a dot in the sidebar
+					when there’s a response.
+				</p>
+			</div>
+		</div>
+	);
+}
+
+function BuilderFailureCard({
+	failure,
+	creatingAgent,
+	retrying,
+	onRetry,
+}: {
+	failure: AgentTurnFailure;
+	creatingAgent: boolean;
+	retrying: boolean;
+	onRetry: (() => void) | null;
+}) {
+	const message =
+		failure.kind === "rate-limit"
+			? "Vercel AI Gateway rate-limited this model before it could start. Try again in a moment or add AI Gateway credits in Vercel."
+			: failure.kind === "restricted"
+				? "This model requires paid AI Gateway credits. Add credits in Vercel, then try again."
+				: failure.kind === "credits"
+					? "Vercel AI Gateway has no available credits. Add credits in Vercel, then try again."
+					: "The builder could not finish this request. Try again.";
+
+	return (
+		<div
+			role="alert"
+			className="flex flex-col items-stretch gap-3 rounded-lg border border-destructive/30 bg-card px-4 py-3 sm:flex-row sm:items-start"
+		>
+			<div className="flex min-w-0 flex-1 items-start gap-3">
+				<Icon icon={WarningAlt} className="mt-0.5 size-4 text-destructive" />
+				<div className="min-w-0 flex-1">
+					<p className="font-medium text-sm">
+						{creatingAgent ? "Agent creation stopped" : "Response stopped"}
+					</p>
+					<p className="mt-0.5 text-pretty text-muted-foreground text-xs leading-5">
+						{message}
+					</p>
+				</div>
+			</div>
+			{onRetry ? (
+				<Button
+					variant="outline"
+					size="sm"
+					disabled={retrying}
+					onClick={onRetry}
+				>
+					Try again
+				</Button>
+			) : null}
+		</div>
+	);
+}
+
+function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const version = conversation.createdVersions[0] as DraftVersion | undefined;
+	const agent = conversation.agent;
+	const manifest = manifestOf(version?.manifest);
+	const deploy = useMutation(
+		trpc.agents.deploy.mutationOptions({
+			onSuccess: async () => {
+				await Promise.all([
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderById.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderList.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.agents.list.pathKey(),
+					}),
+				]);
+				toast.success("Agent created for the team.");
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	if (!version || !agent) return null;
+
+	return (
+		<div className="flex flex-col gap-5">
+			<p className="max-w-[640px] text-pretty text-sm leading-5">
+				I’ve drafted the agent. Review its scope before I create and deploy it
+				for the team.
+			</p>
+			<div className="overflow-hidden rounded-lg border bg-card">
+				<div className="border-b px-4 py-3 sm:px-5 sm:py-4">
+					<h2 className="wrap-break-word font-medium text-sm">{agent.name}</h2>
+					<p className="mt-0.5 wrap-break-word text-pretty text-muted-foreground text-xs">
+						{agent.description ?? "A durable agent for your team."}
+					</p>
+				</div>
+				<ReviewRow label="Trigger" value={manifest.trigger} />
+				<ReviewRow label="Looks at" value={manifest.looksAt} />
+				<ReviewRow label="Action" value={manifest.action} />
+				<ReviewRow label="Access" value={manifest.access} />
+				<p className="border-t px-4 py-2 text-pretty text-muted-foreground text-xs sm:px-5">
+					Runs in an isolated Vercel Sandbox. Integration credentials are
+					brokered at runtime and never enter the workspace.
+				</p>
+				<div className="flex min-h-14 flex-col items-stretch gap-3 border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-4 sm:px-5">
+					<p className="text-pretty text-muted-foreground text-xs">
+						Creating this makes the agent available to everyone in Comp AI.
+					</p>
+					<div className="flex flex-wrap justify-end gap-1 sm:shrink-0">
+						<Button
+							variant="ghost"
+							onClick={() =>
+								document
+									.querySelector<HTMLTextAreaElement>(
+										'textarea[aria-label="Message the agent builder"]',
+									)
+									?.focus()
+							}
+						>
+							Change details
+						</Button>
+						<Button
+							disabled={deploy.isPending}
+							onClick={() =>
+								deploy.mutate({
+									id: agent.id,
+									versionId: version.id,
+									clientRequestId: crypto.randomUUID(),
+								})
+							}
+						>
+							{deploy.isPending ? "Creating…" : "Create agent"}
+						</Button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+function ReviewRow({ label, value }: { label: string; value: string }) {
+	return (
+		<div className="flex min-h-8 flex-col items-start gap-0.5 border-b px-4 py-2 last:border-b-0 sm:flex-row sm:items-center sm:gap-4 sm:px-5 sm:py-1.5">
+			<span className="text-muted-foreground text-xs sm:w-[104px] sm:shrink-0">
+				{label}
+			</span>
+			<span className="min-w-0 flex-1 wrap-break-word font-medium text-sm">
+				{value}
+			</span>
+		</div>
+	);
+}
+
+function DeployedAgentCard({
+	conversation,
+	onFollowUp,
+}: {
+	conversation: Conversation;
+	onFollowUp: (message: string) => void;
+}) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const agent = conversation.agent;
+	const run = useMutation(
+		trpc.agents.runNow.mutationOptions({
+			onSuccess: async () => {
+				await queryClient.invalidateQueries({
+					queryKey: trpc.agents.history.pathKey(),
+				});
+				toast.success("Agent run queued.");
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	if (!agent) return null;
+	const nextRun = agent.triggers.find((trigger) => trigger.enabled)?.nextRunAt;
+
+	return (
+		<div className="flex flex-col gap-[18px]">
+			<div className="space-y-1">
+				<p className="text-sm leading-5">{agent.name} is live.</p>
+				<p className="text-muted-foreground text-sm leading-5">
+					I created the Eve agent, applied its bounded CRM and integration
+					access, and scheduled its first run.
+				</p>
+			</div>
+			<div className="overflow-hidden rounded-lg border bg-card">
+				<div className="flex flex-col items-start gap-3 border-b px-4 py-3 sm:flex-row sm:items-center sm:gap-4 sm:px-5 sm:py-4">
+					<div className="flex min-w-0 flex-1 flex-col gap-0.5">
+						<div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+							<Icon icon={CheckmarkFilled} className="size-3.5 text-ring" />
+							<h2 className="min-w-0 wrap-break-word font-medium text-sm">
+								{agent.name}
+							</h2>
+							<span className="text-muted-foreground text-xs">Live</span>
+						</div>
+						<p className="wrap-break-word text-muted-foreground text-xs">
+							Team agent · created by {agent.createdBy.name}
+						</p>
+					</div>
+					<Button asChild variant="outline" size="sm">
+						<Link href={`/agents/${agent.id}`}>Open agent</Link>
+					</Button>
+				</div>
+				<div className="grid border-b sm:grid-cols-3">
+					<DeployedStat
+						label="Next run"
+						value={nextRun ? formatNextRun(nextRun) : "Manual only"}
+					/>
+					<DeployedStat label="Execution" value="Vercel · Eve · Sandbox" />
+					<DeployedStat label="Available to" value="Everyone in Comp AI" last />
+				</div>
+				<div className="flex min-h-12 flex-col items-start gap-3 px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-4 sm:px-5 sm:py-2">
+					<p className="text-pretty text-muted-foreground text-xs">
+						The chat remains private. The agent is now team-owned.
+					</p>
+					<Button
+						variant="outline"
+						size="sm"
+						disabled={run.isPending}
+						onClick={() =>
+							run.mutate({ id: agent.id, clientRequestId: crypto.randomUUID() })
+						}
+					>
+						<Icon icon={Play} data-icon="inline-start" />
+						Run now
+					</Button>
+				</div>
+			</div>
+
+			<div>
+				<p className="flex h-7 items-center text-muted-foreground text-sm">
+					Suggested follow-ups
+				</p>
+				{["Run it once now", "Add another teammate to the notification"].map(
+					(suggestion) => (
+						<button
+							key={suggestion}
+							type="button"
+							onClick={() => onFollowUp(suggestion)}
+							className="flex w-full items-center gap-3 border-t py-2.5 text-left outline-none hover:bg-muted/50 focus-visible:bg-muted/50"
+						>
+							<span className="min-w-0 flex-1 wrap-break-word text-sm">
+								{suggestion}
+							</span>
+							<Icon
+								icon={ArrowRight}
+								className="size-4 text-muted-foreground"
+							/>
+						</button>
+					),
+				)}
+			</div>
+		</div>
+	);
+}
+
+function DeployedStat({
+	label,
+	value,
+	last = false,
+}: {
+	label: string;
+	value: string;
+	last?: boolean;
+}) {
+	return (
+		<div
+			className={cn(
+				"flex min-w-0 flex-col justify-center gap-1 px-4 py-3 sm:px-5",
+				!last && "border-b sm:border-r sm:border-b-0",
+			)}
+		>
+			<span className="text-muted-foreground text-xs">{label}</span>
+			<span className="min-w-0 wrap-break-word font-medium text-sm sm:truncate">
+				{value}
+			</span>
+		</div>
+	);
+}
+
+function ChatLoading() {
+	return (
+		<main className="flex flex-1 items-center justify-center">
+			<Icon
+				icon={Renew}
+				className="size-4 animate-spin text-muted-foreground"
+				motion="none"
+			/>
+		</main>
+	);
+}
+
+function submissionText(message: unknown): string {
+	if (!message || typeof message !== "object" || !("text" in message)) {
+		return "Message unavailable";
+	}
+	return typeof message.text === "string"
+		? message.text
+		: "Message unavailable";
+}
+
+function retryPromptOf(
+	submission: BuilderSubmission | undefined,
+): BuilderPrompt | null {
+	if (!submission) return null;
+	const row = recordOf(submission.message);
+	if (typeof row.text !== "string" || !row.text.trim()) return null;
+
+	return {
+		commandType: submission.commandType,
+		message: row.text,
+		resources: Array.isArray(row.resources)
+			? (row.resources as BuilderPrompt["resources"])
+			: [],
+		attachments: Array.isArray(row.attachments)
+			? (row.attachments as BuilderPrompt["attachments"])
+			: [],
+	};
+}
+
+function isWorking(
+	conversation: Conversation,
+	creatingAgent: boolean,
+): boolean {
+	if (
+		(creatingAgent && conversation.agent?.status === "LIVE") ||
+		(creatingAgent && conversation.createdVersions[0]?.status === "READY")
+	) {
+		return false;
+	}
+
+	return (
+		conversation.submissions.some((submission) =>
+			["PENDING", "SENDING"].includes(submission.status),
+		) || Boolean(conversation.sessionId && !conversation.continuationToken)
+	);
+}
+
+function reviewable(conversation: Conversation): boolean {
+	return (
+		conversation.agent?.status !== "LIVE" &&
+		conversation.createdVersions[0]?.status === "READY"
+	);
+}
+
+function manifestOf(value: unknown) {
+	const manifest = recordOf(value);
+	const trigger = recordOf(manifest.trigger);
+	const dataScope = recordOf(manifest.dataScope);
+	const actions = Array.isArray(manifest.actions)
+		? manifest.actions.map(recordOf)
+		: [];
+	const access = Array.isArray(manifest.access)
+		? manifest.access.filter((item): item is string => typeof item === "string")
+		: [];
+
+	return {
+		trigger: textOf(trigger.summary, "Manual or configured schedule"),
+		looksAt: textOf(dataScope.summary, "CRM records in the approved scope"),
+		action: textOf(actions[0]?.summary, "Perform the requested team action"),
+		access: access.length > 0 ? access.join(" · ") : "Bounded CRM read access",
+	};
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function textOf(value: unknown, fallback: string): string {
+	return typeof value === "string" && value.trim() ? value : fallback;
+}
+
+function formatNextRun(value: string): string {
+	return new Intl.DateTimeFormat(undefined, {
+		weekday: "short",
+		hour: "numeric",
+		minute: "2-digit",
+		timeZoneName: "short",
+	}).format(new Date(value));
+}
diff --git a/apps/app/components/agent-builder/agent-builder-home.tsx b/apps/app/components/agent-builder/agent-builder-home.tsx
new file mode 100644
index 00000000..956802e8
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-builder-home.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import ArrowRight from "@carbon/icons-react/es/ArrowRight";
+import { Icon } from "@crm/ui/components/icon";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+import { toast } from "sonner";
+import { useTRPC } from "@/lib/trpc/client";
+import { AgentComposer, type BuilderPrompt } from "./agent-composer";
+
+const SUGGESTIONS = [
+	"Brief every deal owner before a renewal call",
+	"Flag deals with no activity for 14 days",
+	"Hand new customers from Sales to Onboarding",
+];
+
+export function AgentBuilderHome({ name }: { name: string }) {
+	const router = useRouter();
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const [initialPrompt, setInitialPrompt] = useState("");
+	const create = useMutation(
+		trpc.conversations.createBuilder.mutationOptions({
+			onSuccess: async ({ id }) => {
+				await queryClient.invalidateQueries({
+					queryKey: trpc.conversations.builderList.pathKey(),
+				});
+				router.push(`/chat/${id}`);
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	const submit = (prompt: BuilderPrompt) => {
+		create.mutate({
+			...prompt,
+			clientRequestId: crypto.randomUUID(),
+		});
+	};
+
+	return (
+		<main className="relative flex min-h-0 flex-1 flex-col items-center justify-center overflow-y-auto px-4 pt-14 pb-20 sm:px-6 sm:pt-12 sm:pb-28">
+			<div className="flex w-full max-w-3xl flex-col items-center gap-3 pb-6 text-center">
+				<h1 className="text-balance font-medium text-2xl tracking-tight sm:text-3xl">
+					What can I help with, {firstName(name)}?
+				</h1>
+				<p className="max-w-xl text-balance text-muted-foreground text-sm">
+					Ask about your CRM, tag a record or integration, or use /Create agent
+					to automate a task.
+				</p>
+			</div>
+
+			<div className="w-full max-w-3xl">
+				<AgentComposer
+					key={initialPrompt}
+					mode="home"
+					initialPrompt={initialPrompt}
+					pending={create.isPending}
+					onSubmit={submit}
+				/>
+				<p className="flex h-8 items-center px-px text-muted-foreground text-xs">
+					Chats stay private to you. Agents you create are available to the
+					whole team.
+				</p>
+
+				<div className="pt-1">
+					<p className="flex h-7 items-center text-muted-foreground text-xs">
+						Suggested agents
+					</p>
+					{SUGGESTIONS.map((suggestion) => (
+						<button
+							key={suggestion}
+							type="button"
+							onClick={() => setInitialPrompt(`/Create agent ${suggestion}`)}
+							className="flex h-[42px] w-full items-center border-t text-left outline-none transition-colors hover:bg-muted/50 focus-visible:bg-muted/50"
+						>
+							<span className="min-w-0 flex-1 font-medium text-sm">
+								{suggestion}
+							</span>
+							<Icon
+								icon={ArrowRight}
+								className="size-4 text-muted-foreground"
+							/>
+						</button>
+					))}
+				</div>
+			</div>
+		</main>
+	);
+}
+
+function firstName(name: string): string {
+	return name.trim().split(/\s+/)[0] || "there";
+}
diff --git a/apps/app/components/agent-builder/agent-builder-shell.tsx b/apps/app/components/agent-builder/agent-builder-shell.tsx
new file mode 100644
index 00000000..5be2d8fd
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-builder-shell.tsx
@@ -0,0 +1,10 @@
+import { AgentBuilderSidebar } from "./agent-builder-sidebar";
+
+export function AgentBuilderShell({ children }: { children: React.ReactNode }) {
+	return (
+		<div className="flex min-h-0 min-w-0 flex-1">
+			<AgentBuilderSidebar className="hidden w-[213px] flex-none border-r md:flex" />
+			<div className="flex min-w-0 flex-1 flex-col">{children}</div>
+		</div>
+	);
+}
diff --git a/apps/app/components/agent-builder/agent-builder-sidebar.tsx b/apps/app/components/agent-builder/agent-builder-sidebar.tsx
new file mode 100644
index 00000000..5fef3de6
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-builder-sidebar.tsx
@@ -0,0 +1,209 @@
+"use client";
+
+import Add from "@carbon/icons-react/es/Add";
+import Bot from "@carbon/icons-react/es/Bot";
+import CheckmarkFilled from "@carbon/icons-react/es/CheckmarkFilled";
+import CircleFilled from "@carbon/icons-react/es/CircleFilled";
+import Renew from "@carbon/icons-react/es/Renew";
+import { Button } from "@crm/ui/components/button";
+import { Icon } from "@crm/ui/components/icon";
+import { cn } from "@crm/ui/lib/utils";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useTRPC } from "@/lib/trpc/client";
+import type { RouterOutputs } from "@/lib/trpc/types";
+
+type Conversation = RouterOutputs["conversations"]["builderList"][number];
+type TeamAgent = RouterOutputs["agents"]["list"][number];
+
+export function AgentBuilderSidebar({
+	className,
+	onNavigate,
+}: {
+	className?: string;
+	onNavigate?: () => void;
+}) {
+	const pathname = usePathname();
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const conversations = useQuery({
+		...trpc.conversations.builderList.queryOptions(),
+		refetchInterval: 5000,
+	});
+	const agents = useQuery({
+		...trpc.agents.list.queryOptions(),
+		refetchInterval: 10_000,
+	});
+	const markRead = useMutation(
+		trpc.conversations.markRead.mutationOptions({
+			onSuccess: () =>
+				queryClient.invalidateQueries({
+					queryKey: trpc.conversations.builderList.pathKey(),
+				}),
+		}),
+	);
+
+	const groups = groupConversations(conversations.data ?? []);
+	const teamAgents = agents.data ?? [];
+
+	return (
+		<aside className={cn("min-h-0 min-w-0 flex-col p-4 font-sans", className)}>
+			<div className="flex h-7 shrink-0 items-center justify-between pl-2">
+				<span className="font-medium text-xs">Chats</span>
+				<Button asChild variant="ghost" size="icon-xs">
+					<Link href="/agents" aria-label="New agent chat" onClick={onNavigate}>
+						<Icon icon={Add} />
+					</Link>
+				</Button>
+			</div>
+
+			<nav aria-label="Agent chats" className="min-h-0 flex-1 overflow-y-auto">
+				{groups.map((group) => (
+					<div key={group.label}>
+						<div className="flex h-8 items-end pb-1 pl-2 font-medium text-[11px] text-muted-foreground uppercase tracking-[0.08em]">
+							{group.label}
+						</div>
+						{group.items.map((conversation) => {
+							const active = pathname === `/chat/${conversation.id}`;
+							return (
+								<Link
+									key={conversation.id}
+									href={`/chat/${conversation.id}`}
+									aria-current={active ? "page" : undefined}
+									onClick={() => {
+										if (conversation.unread) {
+											markRead.mutate({ id: conversation.id });
+										}
+										onNavigate?.();
+									}}
+									className={cn(
+										"flex h-7 items-center gap-3 rounded-sm px-2 text-xs outline-none transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/60",
+										active && "bg-muted font-medium",
+										!active &&
+											conversation.state === "idle" &&
+											"text-muted-foreground",
+									)}
+								>
+									<ConversationState state={conversation.state} />
+									<span className="min-w-0 flex-1 truncate">
+										{conversation.title ?? "Untitled chat"}
+									</span>
+								</Link>
+							);
+						})}
+					</div>
+				))}
+
+				{conversations.isSuccess && groups.length === 0 ? (
+					<p className="px-2 py-3 text-muted-foreground text-xs">
+						No chats in the last 7 days.
+					</p>
+				) : null}
+
+				<TeamAgents
+					agents={teamAgents}
+					pathname={pathname}
+					onNavigate={onNavigate}
+				/>
+			</nav>
+		</aside>
+	);
+}
+
+function TeamAgents({
+	agents,
+	pathname,
+	onNavigate,
+}: {
+	agents: TeamAgent[];
+	pathname: string;
+	onNavigate?: () => void;
+}) {
+	return (
+		<div className="mt-3 border-t pt-1">
+			<Link
+				href="/agents/team"
+				onClick={onNavigate}
+				className="flex h-8 items-end gap-2 rounded-sm px-2 pb-1 font-medium text-[11px] text-muted-foreground uppercase tracking-[0.08em] outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/60"
+			>
+				<span className="min-w-0 flex-1">Team agents</span>
+				<span className="shrink-0 font-mono">{agents.length}</span>
+			</Link>
+			{agents.map((agent) => {
+				const active = pathname === `/agents/${agent.id}`;
+				return (
+					<Link
+						key={agent.id}
+						href={`/agents/${agent.id}`}
+						aria-current={active ? "page" : undefined}
+						onClick={onNavigate}
+						className={cn(
+							"flex h-7 items-center gap-3 rounded-sm px-2 text-xs outline-none transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/60",
+							active ? "bg-muted font-medium" : "text-muted-foreground",
+						)}
+					>
+						<span className="flex size-5 shrink-0 items-center justify-center">
+							<Icon icon={Bot} className="size-3.5" />
+						</span>
+						<span className="min-w-0 flex-1 truncate">{agent.name}</span>
+					</Link>
+				);
+			})}
+		</div>
+	);
+}
+
+function ConversationState({ state }: { state: Conversation["state"] }) {
+	if (state === "working") {
+		return (
+			<span className="flex size-5 shrink-0 items-center justify-center text-muted-foreground">
+				<Icon icon={Renew} className="size-3.5 animate-spin" motion="none" />
+			</span>
+		);
+	}
+
+	if (state === "unread") {
+		return (
+			<span className="flex size-5 shrink-0 items-center justify-center text-ring">
+				<Icon icon={CircleFilled} className="size-3.5" motion="none" />
+			</span>
+		);
+	}
+
+	if (state === "deployed") {
+		return (
+			<span className="flex size-5 shrink-0 items-center justify-center text-ring">
+				<Icon icon={CheckmarkFilled} className="size-3.5" motion="none" />
+			</span>
+		);
+	}
+
+	return <span className="size-5 shrink-0" />;
+}
+
+function groupConversations(conversations: Conversation[]) {
+	const todayStart = new Date();
+	todayStart.setHours(0, 0, 0, 0);
+	const yesterdayStart = new Date(todayStart);
+	yesterdayStart.setDate(yesterdayStart.getDate() - 1);
+	const lastWeekStart = new Date(todayStart);
+	lastWeekStart.setDate(lastWeekStart.getDate() - 7);
+
+	const today = { label: "Today", items: [] as Conversation[] };
+	const yesterday = { label: "Yesterday", items: [] as Conversation[] };
+	const recent = { label: "Last 7 days", items: [] as Conversation[] };
+
+	for (const conversation of conversations) {
+		const lastMessageAt = new Date(conversation.lastMessageAt);
+		if (lastMessageAt >= todayStart) {
+			today.items.push(conversation);
+		} else if (lastMessageAt >= yesterdayStart) {
+			yesterday.items.push(conversation);
+		} else if (lastMessageAt >= lastWeekStart) {
+			recent.items.push(conversation);
+		}
+	}
+
+	return [today, yesterday, recent].filter((group) => group.items.length > 0);
+}
diff --git a/apps/app/components/agent-builder/agent-composer.tsx b/apps/app/components/agent-builder/agent-composer.tsx
new file mode 100644
index 00000000..74c70bc5
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-composer.tsx
@@ -0,0 +1,416 @@
+"use client";
+
+import Add from "@carbon/icons-react/es/Add";
+import Application from "@carbon/icons-react/es/Application";
+import ArrowUp from "@carbon/icons-react/es/ArrowUp";
+import AttachmentIcon from "@carbon/icons-react/es/Attachment";
+import Building from "@carbon/icons-react/es/Building";
+import Calendar from "@carbon/icons-react/es/Calendar";
+import Close from "@carbon/icons-react/es/Close";
+import Document from "@carbon/icons-react/es/Document";
+import Email from "@carbon/icons-react/es/Email";
+import Partnership from "@carbon/icons-react/es/Partnership";
+import Search from "@carbon/icons-react/es/Search";
+import User from "@carbon/icons-react/es/User";
+import { Button } from "@crm/ui/components/button";
+import { type CarbonIcon, Icon } from "@crm/ui/components/icon";
+import { Input } from "@crm/ui/components/input";
+import {
+	Popover,
+	PopoverContent,
+	PopoverTrigger,
+} from "@crm/ui/components/popover";
+import { cn } from "@crm/ui/lib/utils";
+import { useQuery } from "@tanstack/react-query";
+import { useRef, useState } from "react";
+import { toast } from "sonner";
+import {
+	type BuilderCommandType,
+	builderCommandType,
+} from "@/lib/agent-builder";
+import { useTRPC } from "@/lib/trpc/client";
+
+export type BuilderResource = {
+	kind: "integration" | "company" | "contact" | "deal";
+	id: string;
+	label: string;
+};
+
+export type BuilderAttachment = {
+	name: string;
+	type: string;
+	size: number;
+	contentBase64: string;
+};
+
+export type BuilderPrompt = {
+	commandType: BuilderCommandType;
+	message: string;
+	resources: BuilderResource[];
+	attachments: BuilderAttachment[];
+};
+
+export function AgentComposer({
+	mode,
+	disabled = false,
+	pending = false,
+	initialPrompt = "",
+	onSubmit,
+}: {
+	mode: "home" | "chat";
+	disabled?: boolean;
+	pending?: boolean;
+	initialPrompt?: string;
+	onSubmit: (prompt: BuilderPrompt) => void;
+}) {
+	const trpc = useTRPC();
+	const fileInput = useRef<HTMLInputElement>(null);
+	const [draft, setDraft] = useState(initialPrompt);
+	const [resourceQuery, setResourceQuery] = useState("");
+	const [resources, setResources] = useState<BuilderResource[]>([]);
+	const [attachments, setAttachments] = useState<BuilderAttachment[]>([]);
+	const resourceResults = useQuery(
+		trpc.conversations.builderResources.queryOptions({ q: resourceQuery }),
+	);
+	const google = useQuery(trpc.google.status.queryOptions());
+	const canSend = draft.trim().length > 0 && !disabled && !pending;
+
+	const submit = () => {
+		if (!canSend) return;
+		const message = draft.trim();
+		onSubmit({
+			commandType: builderCommandType(message),
+			message,
+			resources,
+			attachments,
+		});
+		setDraft("");
+		setResources([]);
+		setAttachments([]);
+	};
+
+	const addResource = (resource: BuilderResource) => {
+		setResources((current) =>
+			current.some(
+				(item) => item.kind === resource.kind && item.id === resource.id,
+			)
+				? current
+				: [...current, resource],
+		);
+	};
+
+	const connectedGoogle = (google.data?.sources ?? []).filter(
+		(source) => source.connected,
+	);
+
+	return (
+		<div
+			className={cn(
+				"flex w-full flex-col justify-between rounded-lg border bg-muted p-[11px] shadow-[inset_0_1px_1px_rgb(0_0_0/0.12)] transition-colors focus-within:border-muted-foreground/60 focus-within:ring-1 focus-within:ring-ring/40",
+				mode === "home" ? "min-h-24" : "min-h-[78px]",
+			)}
+		>
+			{resources.length > 0 || attachments.length > 0 ? (
+				<div className="flex flex-wrap gap-1 px-1 pb-1">
+					{resources.map((resource) => (
+						<ComposerChip
+							key={`${resource.kind}:${resource.id}`}
+							label={resource.label}
+							icon={RESOURCE_ICONS[resource.kind]}
+							onRemove={() =>
+								setResources((current) =>
+									current.filter(
+										(item) =>
+											item.kind !== resource.kind || item.id !== resource.id,
+									),
+								)
+							}
+						/>
+					))}
+					{attachments.map((attachment) => (
+						<ComposerChip
+							key={`${attachment.name}:${attachment.size}`}
+							label={attachment.name}
+							icon={Document}
+							onRemove={() =>
+								setAttachments((current) =>
+									current.filter((item) => item !== attachment),
+								)
+							}
+						/>
+					))}
+				</div>
+			) : null}
+
+			<textarea
+				value={draft}
+				onChange={(event) => setDraft(event.target.value)}
+				onKeyDown={(event) => {
+					if (event.key === "Enter" && !event.shiftKey) {
+						event.preventDefault();
+						submit();
+					}
+				}}
+				disabled={disabled}
+				rows={mode === "home" ? 2 : 1}
+				placeholder={
+					mode === "home"
+						? "Ask about your CRM or automate a task…"
+						: "Send a message"
+				}
+				aria-label="Message the agent builder"
+				className="max-h-40 min-h-6 w-full resize-none bg-transparent px-1 text-base leading-6 outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-60 sm:text-[15px]"
+			/>
+
+			<div className="flex h-7 items-center justify-between">
+				<div className="flex items-center gap-0.5">
+					<Popover>
+						<PopoverTrigger asChild>
+							<Button
+								variant="ghost"
+								size="icon-sm"
+								aria-label="Tag CRM records and integrations"
+							>
+								<Icon icon={Add} />
+							</Button>
+						</PopoverTrigger>
+						<PopoverContent
+							size="fit"
+							align="start"
+							side="top"
+							className="w-80"
+						>
+							<div className="border-b p-2">
+								<div className="relative">
+									<Icon
+										icon={Search}
+										className="absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-muted-foreground"
+									/>
+									<Input
+										value={resourceQuery}
+										onChange={(event) => setResourceQuery(event.target.value)}
+										placeholder="Search CRM records"
+										className="pl-8"
+									/>
+								</div>
+							</div>
+							<div className="max-h-72 overflow-y-auto p-1">
+								{connectedGoogle.map((source) => (
+									<ResourceButton
+										key={source.source}
+										icon={source.source === "calendar" ? Calendar : Email}
+										label={
+											source.source === "calendar" ? "Google Calendar" : "Gmail"
+										}
+										detail="Connected integration"
+										onSelect={() =>
+											addResource({
+												kind: "integration",
+												id: `google:${source.source}`,
+												label:
+													source.source === "calendar"
+														? "Google Calendar"
+														: "Gmail",
+											})
+										}
+									/>
+								))}
+								{(resourceResults.data ?? []).map((resource) => (
+									<ResourceButton
+										key={`${resource.kind}:${resource.id}`}
+										icon={RESOURCE_ICONS[resource.kind]}
+										label={resource.label}
+										detail={resource.detail ?? RESOURCE_LABELS[resource.kind]}
+										onSelect={() => addResource(resource)}
+									/>
+								))}
+								{resourceResults.isSuccess &&
+								connectedGoogle.length === 0 &&
+								resourceResults.data.length === 0 ? (
+									<p className="px-3 py-5 text-center text-muted-foreground text-xs">
+										No matching records.
+									</p>
+								) : null}
+							</div>
+						</PopoverContent>
+					</Popover>
+
+					<input
+						ref={fileInput}
+						type="file"
+						multiple
+						className="hidden"
+						onChange={(event) => {
+							void addFiles(event.currentTarget.files, setAttachments);
+							event.currentTarget.value = "";
+						}}
+					/>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						aria-label="Attach files"
+						onClick={() => fileInput.current?.click()}
+					>
+						<Icon icon={AttachmentIcon} />
+					</Button>
+
+					<Popover>
+						<PopoverTrigger asChild>
+							<Button
+								variant="ghost"
+								size="icon-sm"
+								aria-label="Open slash commands"
+								className="font-mono text-sm"
+							>
+								/
+							</Button>
+						</PopoverTrigger>
+						<PopoverContent
+							size="fit"
+							align="start"
+							side="top"
+							className="w-64 p-1"
+						>
+							<button
+								type="button"
+								onClick={() =>
+									setDraft((current) =>
+										current.startsWith("/Create agent")
+											? current
+											: `/Create agent ${current}`,
+									)
+								}
+								className="flex w-full items-center gap-3 rounded-sm px-3 py-2 text-left outline-none hover:bg-muted focus-visible:bg-muted"
+							>
+								<Icon
+									icon={Application}
+									className="size-4 text-muted-foreground"
+								/>
+								<span>
+									<span className="block font-medium text-xs">
+										/Create agent
+									</span>
+									<span className="block text-muted-foreground text-xs">
+										Build a durable team automation
+									</span>
+								</span>
+							</button>
+						</PopoverContent>
+					</Popover>
+				</div>
+
+				<Button
+					variant="default"
+					size="icon-sm"
+					disabled={!canSend}
+					aria-label="Send message"
+					onClick={submit}
+					className="rounded-full"
+				>
+					<Icon icon={ArrowUp} />
+				</Button>
+			</div>
+		</div>
+	);
+}
+
+const RESOURCE_ICONS: Record<BuilderResource["kind"], CarbonIcon> = {
+	integration: Application,
+	company: Building,
+	contact: User,
+	deal: Partnership,
+};
+
+const RESOURCE_LABELS: Record<BuilderResource["kind"], string> = {
+	integration: "Integration",
+	company: "Company",
+	contact: "Contact",
+	deal: "Deal",
+};
+
+function ComposerChip({
+	label,
+	icon,
+	onRemove,
+}: {
+	label: string;
+	icon: CarbonIcon;
+	onRemove: () => void;
+}) {
+	return (
+		<span className="flex h-6 max-w-full items-center gap-1 rounded-full bg-foreground px-2 text-background text-xs sm:max-w-56">
+			<Icon icon={icon} className="size-3.5 shrink-0" />
+			<span className="truncate font-medium">{label}</span>
+			<button
+				type="button"
+				aria-label={`Remove ${label}`}
+				onClick={onRemove}
+				className="-mr-1 flex size-4 items-center justify-center rounded-full outline-none hover:bg-background/15 focus-visible:ring-2 focus-visible:ring-background/60"
+			>
+				<Icon icon={Close} className="size-3" />
+			</button>
+		</span>
+	);
+}
+
+function ResourceButton({
+	icon,
+	label,
+	detail,
+	onSelect,
+}: {
+	icon: CarbonIcon;
+	label: string;
+	detail: string | null;
+	onSelect: () => void;
+}) {
+	return (
+		<button
+			type="button"
+			onClick={onSelect}
+			className="flex w-full items-center gap-3 rounded-sm px-3 py-2 text-left outline-none hover:bg-muted focus-visible:bg-muted"
+		>
+			<span className="flex size-6 shrink-0 items-center justify-center text-muted-foreground">
+				<Icon icon={icon} className="size-4" />
+			</span>
+			<span className="min-w-0 flex-1">
+				<span className="block truncate font-medium text-xs">{label}</span>
+				<span className="block truncate text-muted-foreground text-xs">
+					{detail}
+				</span>
+			</span>
+		</button>
+	);
+}
+
+async function addFiles(
+	files: FileList | null,
+	setAttachments: React.Dispatch<React.SetStateAction<BuilderAttachment[]>>,
+) {
+	if (!files) return;
+	const accepted: BuilderAttachment[] = [];
+
+	for (const file of Array.from(files).slice(0, 5)) {
+		if (file.size > 2_000_000) {
+			toast.error(`${file.name} is larger than 2 MB.`);
+			continue;
+		}
+
+		accepted.push({
+			name: file.name,
+			type: file.type || "application/octet-stream",
+			size: file.size,
+			contentBase64: bytesToBase64(new Uint8Array(await file.arrayBuffer())),
+		});
+	}
+
+	setAttachments((current) => [...current, ...accepted].slice(0, 5));
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+	let binary = "";
+	for (let index = 0; index < bytes.length; index += 8192) {
+		binary += String.fromCharCode(...bytes.subarray(index, index + 8192));
+	}
+	return btoa(binary);
+}
diff --git a/apps/app/components/agent-builder/share-chat-dialog.tsx b/apps/app/components/agent-builder/share-chat-dialog.tsx
new file mode 100644
index 00000000..24c74b33
--- /dev/null
+++ b/apps/app/components/agent-builder/share-chat-dialog.tsx
@@ -0,0 +1,225 @@
+"use client";
+
+import Close from "@carbon/icons-react/es/Close";
+import Copy from "@carbon/icons-react/es/Copy";
+import { Button } from "@crm/ui/components/button";
+import {
+	Dialog,
+	DialogClose,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogTrigger,
+} from "@crm/ui/components/dialog";
+import { Icon } from "@crm/ui/components/icon";
+import { cn } from "@crm/ui/lib/utils";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { toast } from "sonner";
+import { useTRPC } from "@/lib/trpc/client";
+
+export function ShareChatDialog({
+	conversationId,
+	title,
+}: {
+	conversationId: string;
+	title: string;
+}) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const [open, setOpen] = useState(false);
+	const [choice, setChoice] = useState<boolean | null>(null);
+	const [token, setToken] = useState<string | null>(null);
+	const status = useQuery({
+		...trpc.conversations.shareStatus.queryOptions({ id: conversationId }),
+		enabled: open,
+	});
+	const shared = choice ?? status.data?.enabled ?? false;
+
+	const invalidate = () =>
+		queryClient.invalidateQueries({
+			queryKey: trpc.conversations.shareStatus.pathKey(),
+		});
+
+	const create = useMutation(
+		trpc.conversations.createShare.mutationOptions({
+			onSuccess: async (result) => {
+				setToken(result.token);
+				setChoice(true);
+				await invalidate();
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+	const revoke = useMutation(
+		trpc.conversations.revokeShare.mutationOptions({
+			onSuccess: async () => {
+				setToken(null);
+				setChoice(false);
+				await invalidate();
+				toast.success("Chat link revoked.");
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	const copyLink = async () => {
+		if (!token) return;
+		await navigator.clipboard.writeText(
+			`${window.location.origin}/chat/${token}`,
+		);
+		toast.success("Chat link copied.");
+	};
+
+	return (
+		<Dialog
+			open={open}
+			onOpenChange={(next) => {
+				setOpen(next);
+				if (!next) setChoice(null);
+			}}
+		>
+			<DialogTrigger asChild>
+				<Button variant="outline" size="sm">
+					Share chat
+				</Button>
+			</DialogTrigger>
+			<DialogContent
+				showCloseButton={false}
+				className="w-[440px] max-w-[calc(100%-2rem)] gap-0 overflow-hidden p-0 sm:max-w-[440px]"
+			>
+				<DialogHeader className="relative gap-1 border-b p-5 pr-14">
+					<DialogTitle className="font-semibold text-sm">
+						Share chat
+					</DialogTitle>
+					<DialogDescription>{title}</DialogDescription>
+					<DialogClose asChild>
+						<Button
+							variant="ghost"
+							size="icon-sm"
+							className="absolute top-4 right-4"
+						>
+							<Icon icon={Close} />
+							<span className="sr-only">Close</span>
+						</Button>
+					</DialogClose>
+				</DialogHeader>
+
+				<div className="flex flex-col gap-2.5 p-5">
+					<ShareChoice
+						selected={!shared}
+						label="Only you"
+						onSelect={() => {
+							if (shared || status.data?.enabled) {
+								revoke.mutate({ id: conversationId });
+							} else {
+								setChoice(false);
+							}
+						}}
+					/>
+					<ShareChoice
+						selected={shared}
+						label="Anyone in Comp AI with the link"
+						detail="Read-only"
+						onSelect={() => {
+							if (!token) create.mutate({ id: conversationId });
+							setChoice(true);
+						}}
+					/>
+
+					{shared ? (
+						<div className="flex h-9 items-center gap-3 rounded-md border bg-background py-[3px] pr-[3px] pl-4">
+							<span className="min-w-0 flex-1 truncate font-mono text-xs">
+								{token
+									? `crm.trycomp.ai/chat/${token.slice(0, 12)}…`
+									: "An active read-only link exists"}
+							</span>
+							<Button
+								variant="outline"
+								size="sm"
+								onClick={() => {
+									if (token) {
+										void copyLink();
+									} else {
+										create.mutate({ id: conversationId });
+									}
+								}}
+								disabled={create.isPending}
+							>
+								{token ? <Icon icon={Copy} data-icon="inline-start" /> : null}
+								{token ? "Copy link" : "Replace link"}
+							</Button>
+						</div>
+					) : null}
+
+					<p className="text-muted-foreground text-xs">
+						Sharing this chat does not change who can edit or run the agent.
+					</p>
+				</div>
+
+				<DialogFooter className="flex-row items-center justify-between border-t p-4 px-5">
+					<Button
+						variant="ghost"
+						onClick={() => revoke.mutate({ id: conversationId })}
+						disabled={!shared || revoke.isPending}
+					>
+						Revoke link
+					</Button>
+					<div className="flex gap-3">
+						<DialogClose asChild>
+							<Button variant="outline">Cancel</Button>
+						</DialogClose>
+						<DialogClose asChild>
+							<Button>Done</Button>
+						</DialogClose>
+					</div>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
+
+function ShareChoice({
+	selected,
+	label,
+	detail,
+	onSelect,
+}: {
+	selected: boolean;
+	label: string;
+	detail?: string;
+	onSelect: () => void;
+}) {
+	return (
+		<label
+			className={cn(
+				"flex h-12 w-full cursor-pointer items-center gap-2.5 rounded-md border px-2.5 text-left outline-none focus-within:ring-2 focus-within:ring-ring/60",
+				selected && "border-muted-foreground/60 bg-muted",
+			)}
+		>
+			<input
+				type="radio"
+				name="chat-sharing"
+				checked={selected}
+				onChange={onSelect}
+				className="sr-only"
+			/>
+			<span
+				className={cn(
+					"flex size-3.5 shrink-0 items-center justify-center rounded-full border border-muted-foreground",
+					selected && "border-ring",
+				)}
+			>
+				{selected ? <span className="size-2 rounded-full bg-ring" /> : null}
+			</span>
+			<span className="min-w-0 flex-1">
+				<span className="block font-medium text-sm">{label}</span>
+				{detail ? (
+					<span className="block text-muted-foreground text-xs">{detail}</span>
+				) : null}
+			</span>
+		</label>
+	);
+}
diff --git a/apps/app/components/agent-builder/team-agent-detail.tsx b/apps/app/components/agent-builder/team-agent-detail.tsx
new file mode 100644
index 00000000..1df7e2b2
--- /dev/null
+++ b/apps/app/components/agent-builder/team-agent-detail.tsx
@@ -0,0 +1,573 @@
+"use client";
+
+import ChevronDown from "@carbon/icons-react/es/ChevronDown";
+import ChevronUp from "@carbon/icons-react/es/ChevronUp";
+import Download from "@carbon/icons-react/es/Download";
+import Pause from "@carbon/icons-react/es/Pause";
+import Play from "@carbon/icons-react/es/Play";
+import Renew from "@carbon/icons-react/es/Renew";
+import { Button } from "@crm/ui/components/button";
+import { Icon } from "@crm/ui/components/icon";
+import { cn } from "@crm/ui/lib/utils";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { toast } from "sonner";
+import { useTRPC } from "@/lib/trpc/client";
+import type { RouterOutputs } from "@/lib/trpc/types";
+
+type AgentTab = "overview" | "runs" | "activity";
+type AgentDetail = RouterOutputs["agents"]["byId"];
+type Runs = RouterOutputs["agents"]["history"];
+type Activity = RouterOutputs["agents"]["activity"];
+type RunRow = Omit<Runs[number], "events"> & {
+	events: Array<{
+		id: string;
+		type: string;
+		data: unknown;
+		emittedAt: string;
+	}>;
+};
+type ActivityRow = Omit<Activity[number], "before" | "after"> & {
+	before: unknown;
+	after: unknown;
+};
+
+export function TeamAgentDetail({ agentId }: { agentId: string }) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const [tab, setTab] = useState<AgentTab>("runs");
+	const agent = useQuery(trpc.agents.byId.queryOptions({ id: agentId }));
+	const runs = useQuery(
+		trpc.agents.history.queryOptions({ id: agentId, limit: 50 }),
+	);
+	const activity = useQuery(
+		trpc.agents.activity.queryOptions({ id: agentId, limit: 100 }),
+	);
+	const invalidate = () =>
+		Promise.all([
+			queryClient.invalidateQueries({ queryKey: trpc.agents.byId.pathKey() }),
+			queryClient.invalidateQueries({ queryKey: trpc.agents.list.pathKey() }),
+		]);
+	const runNow = useMutation(
+		trpc.agents.runNow.mutationOptions({
+			onSuccess: async () => {
+				await queryClient.invalidateQueries({
+					queryKey: trpc.agents.history.pathKey(),
+				});
+				setTab("runs");
+				toast.success("Agent run queued.");
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+	const pause = useMutation(
+		trpc.agents.pause.mutationOptions({
+			onSuccess: invalidate,
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+	const resume = useMutation(
+		trpc.agents.resume.mutationOptions({
+			onSuccess: invalidate,
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+
+	if (agent.isPending) {
+		return (
+			<main className="flex flex-1 items-center justify-center">
+				<Icon
+					icon={Renew}
+					className="size-4 animate-spin text-muted-foreground"
+					motion="none"
+				/>
+			</main>
+		);
+	}
+
+	if (agent.isError) {
+		return (
+			<main className="flex flex-1 items-center justify-center p-8 text-center">
+				<p className="text-muted-foreground text-sm">{agent.error.message}</p>
+			</main>
+		);
+	}
+
+	const data = agent.data;
+	const nextRun = data.triggers.find((trigger) => trigger.enabled)?.nextRunAt;
+
+	return (
+		<main className="min-h-0 min-w-0 flex-1 overflow-y-auto px-4 py-6 sm:px-6 sm:py-10">
+			<div className="mx-auto flex w-full min-w-0 max-w-[1040px] flex-col gap-6">
+				<div className="flex min-w-0 flex-col items-stretch gap-6 sm:flex-row sm:items-start sm:justify-between sm:gap-8">
+					<div className="min-w-0 max-w-[650px]">
+						<h1 className="wrap-break-word text-balance font-semibold text-2xl tracking-tight sm:text-3xl">
+							{data.name}
+						</h1>
+						<p className="mt-3 wrap-break-word text-pretty text-muted-foreground text-sm leading-6">
+							{data.description ?? "A durable team automation."}
+						</p>
+						<p className="mt-3 wrap-break-word text-muted-foreground text-xs">
+							Created by {data.createdBy.name} · Team agent · Version{" "}
+							{data.currentVersion?.number ?? "—"}
+						</p>
+					</div>
+					<div className="flex min-w-0 flex-col items-start gap-2 sm:shrink-0 sm:items-end">
+						<span className="text-muted-foreground text-xs">Next run</span>
+						<span className="font-mono text-sm">
+							{nextRun ? formatDate(nextRun) : "Manual only"}
+						</span>
+						<div className="mt-1 flex flex-wrap gap-2">
+							<Button
+								variant="outline"
+								disabled={data.status !== "LIVE" || runNow.isPending}
+								onClick={() =>
+									runNow.mutate({
+										id: data.id,
+										clientRequestId: crypto.randomUUID(),
+									})
+								}
+							>
+								<Icon icon={Play} data-icon="inline-start" />
+								Run now
+							</Button>
+							{data.canManage && data.status === "LIVE" ? (
+								<Button
+									variant="outline"
+									disabled={pause.isPending}
+									onClick={() => pause.mutate({ id: data.id })}
+								>
+									<Icon icon={Pause} data-icon="inline-start" />
+									Pause
+								</Button>
+							) : null}
+							{data.canManage && data.status === "PAUSED" ? (
+								<Button
+									variant="outline"
+									disabled={resume.isPending}
+									onClick={() => resume.mutate({ id: data.id })}
+								>
+									<Icon icon={Play} data-icon="inline-start" />
+									Resume
+								</Button>
+							) : null}
+						</div>
+					</div>
+				</div>
+
+				<div className="flex h-9 min-w-0 items-end gap-5 overflow-x-auto border-b sm:gap-6">
+					<TabButton
+						active={tab === "overview"}
+						onClick={() => setTab("overview")}
+					>
+						Overview
+					</TabButton>
+					<TabButton active={tab === "runs"} onClick={() => setTab("runs")}>
+						Runs{" "}
+						<span className="font-mono text-muted-foreground">
+							{data.runCount}
+						</span>
+					</TabButton>
+					<TabButton
+						active={tab === "activity"}
+						onClick={() => setTab("activity")}
+					>
+						Activity{" "}
+						<span className="font-mono text-muted-foreground">
+							{activity.data?.length ?? 0}
+						</span>
+					</TabButton>
+				</div>
+
+				{tab === "overview" ? <AgentOverview agent={data} /> : null}
+				{tab === "runs" ? <AgentRuns runs={runs.data ?? []} /> : null}
+				{tab === "activity" ? (
+					<AgentActivity activity={activity.data ?? []} />
+				) : null}
+			</div>
+		</main>
+	);
+}
+
+function TabButton({
+	active,
+	onClick,
+	children,
+}: {
+	active: boolean;
+	onClick: () => void;
+	children: React.ReactNode;
+}) {
+	return (
+		<button
+			type="button"
+			onClick={onClick}
+			className={cn(
+				"flex h-8 items-center gap-2 border-b-2 border-transparent text-muted-foreground text-sm outline-none hover:text-foreground focus-visible:text-foreground",
+				active && "border-ring font-medium text-foreground",
+			)}
+		>
+			{children}
+		</button>
+	);
+}
+
+function AgentOverview({ agent }: { agent: AgentDetail }) {
+	const version = agent.currentVersion as {
+		manifest: unknown;
+		sandboxPolicy: unknown;
+		modelId: string;
+	} | null;
+	const manifest = recordOf(version?.manifest);
+	const sandbox = recordOf(version?.sandboxPolicy);
+
+	return (
+		<div className="overflow-hidden rounded-lg border bg-card">
+			<DetailRow label="Status" value={agent.status} />
+			<DetailRow label="Model" value={version?.modelId ?? "—"} />
+			<DetailRow
+				label="Execution"
+				value={textOf(sandbox.summary, "Vercel Sandbox · deny-all network")}
+			/>
+			<DetailRow
+				label="Scope"
+				value={textOf(
+					recordOf(manifest.dataScope).summary,
+					"Bounded CRM access",
+				)}
+			/>
+			<DetailRow
+				label="Triggers"
+				value={
+					agent.triggers.map((trigger) => trigger.name).join(" · ") ||
+					"Manual only"
+				}
+			/>
+		</div>
+	);
+}
+
+function DetailRow({ label, value }: { label: string; value: string }) {
+	return (
+		<div className="flex min-h-11 flex-col items-start gap-1 border-t px-4 py-3 first:border-t-0 sm:flex-row sm:items-center sm:gap-5 sm:px-5 sm:py-2">
+			<span className="text-muted-foreground text-xs sm:w-36 sm:shrink-0">
+				{label}
+			</span>
+			<span className="min-w-0 max-w-full flex-1 wrap-break-word text-sm">
+				{value}
+			</span>
+		</div>
+	);
+}
+
+function AgentRuns({ runs }: { runs: Runs }) {
+	const [outcome, setOutcome] = useState("ALL");
+	const [expanded, setExpanded] = useState<string | null>(null);
+	const visible = runs.filter(
+		(run) => outcome === "ALL" || run.status === outcome,
+	);
+
+	return (
+		<div className="flex min-w-0 flex-col gap-4 sm:gap-6">
+			<div className="flex min-h-7 items-center justify-start sm:justify-end">
+				<select
+					value={outcome}
+					onChange={(event) => setOutcome(event.target.value)}
+					aria-label="Filter run outcomes"
+					className="h-7 rounded-md border bg-muted px-2.5 font-medium text-xs outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
+				>
+					<option value="ALL">All outcomes</option>
+					<option value="SUCCEEDED">Succeeded</option>
+					<option value="FAILED">Failed</option>
+					<option value="RUNNING">Running</option>
+					<option value="QUEUED">Queued</option>
+				</select>
+			</div>
+
+			{visible.map((run, index) => (
+				<div
+					key={run.id}
+					className="min-w-0 overflow-hidden rounded-lg border bg-card"
+				>
+					<button
+						type="button"
+						onClick={() =>
+							setExpanded((current) => (current === run.id ? null : run.id))
+						}
+						className="flex min-h-14 w-full min-w-0 flex-col items-stretch gap-3 px-4 py-3 text-left outline-none hover:bg-muted/40 focus-visible:bg-muted/40 sm:flex-row sm:items-center sm:justify-between sm:gap-5 sm:px-5 sm:py-2"
+					>
+						<span className="min-w-0 flex-1">
+							<span className="flex flex-wrap items-center gap-x-3 gap-y-1">
+								<span className="font-semibold text-sm">
+									Run #{String(runs.length - index).padStart(3, "0")}
+								</span>
+								<span
+									className={cn(
+										"text-muted-foreground text-xs",
+										run.status === "FAILED" && "text-destructive",
+									)}
+								>
+									{humanStatus(run.status)}
+								</span>
+							</span>
+							<span className="mt-1 block wrap-break-word font-mono text-muted-foreground text-xs leading-5 sm:mt-0">
+								{humanStatus(run.triggerType)} · {formatDate(run.createdAt)} ·
+								Version {run.version.number}
+							</span>
+						</span>
+						<span className="flex min-w-0 items-center justify-between gap-3 font-mono text-muted-foreground text-xs sm:shrink-0 sm:justify-start sm:gap-4">
+							<span>{duration(run.startedAt, run.finishedAt)}</span>
+							<span>
+								{run.actions.length} external{" "}
+								{run.actions.length === 1 ? "action" : "actions"}
+							</span>
+							<Icon
+								icon={expanded === run.id ? ChevronUp : ChevronDown}
+								className="size-3.5"
+							/>
+						</span>
+					</button>
+
+					{expanded === run.id ? (
+						<ExpandedRun run={run as unknown as RunRow} />
+					) : null}
+				</div>
+			))}
+
+			{visible.length === 0 ? (
+				<p className="py-12 text-center text-muted-foreground text-sm">
+					No runs match this outcome.
+				</p>
+			) : null}
+		</div>
+	);
+}
+
+function ExpandedRun({ run }: { run: RunRow }) {
+	const events = run.events.filter(
+		(event) => event.type !== "message.appended",
+	);
+	const condensedEvents = run.events.length - events.length;
+
+	return (
+		<div className="min-w-0 border-t">
+			<div className="grid grid-cols-2 gap-x-4 gap-y-3 border-b bg-background px-4 py-3 sm:min-h-[58px] sm:grid-cols-4 sm:items-center sm:gap-0 sm:px-5 sm:py-2">
+				<RunMeta label="Trigger" value={humanStatus(run.triggerType)} />
+				<RunMeta
+					label="Initiated by"
+					value={run.initiatedBy?.name ?? "Eve scheduler"}
+				/>
+				<RunMeta label="Model" value={run.modelId ?? "Gateway default"} />
+				<RunMeta label="Version" value={String(run.version.number)} last />
+			</div>
+
+			<div>
+				{events.map((event) => (
+					<div
+						key={event.id}
+						className="grid min-h-8 min-w-0 grid-cols-[68px_minmax(0,1fr)] items-start gap-x-3 border-t px-4 py-2 first:border-t-0 sm:flex sm:items-center sm:gap-5 sm:px-5 sm:py-1.5"
+					>
+						<span className="shrink-0 font-mono text-muted-foreground text-xs sm:w-[78px]">
+							{formatTime(event.emittedAt)}
+						</span>
+						<span className="min-w-0 flex-1 wrap-break-word text-sm">
+							{eventLabel(event.type, event.data)}
+						</span>
+						<span className="hidden shrink-0 font-mono text-muted-foreground text-xs sm:inline">
+							event
+						</span>
+					</div>
+				))}
+				{run.actions.map((action) => (
+					<div
+						key={action.id}
+						className="grid min-h-12 min-w-0 grid-cols-[68px_minmax(0,1fr)] items-start gap-x-3 gap-y-1 border-t px-4 py-3 sm:flex sm:gap-5 sm:px-5"
+					>
+						<span className="shrink-0 font-mono text-muted-foreground text-xs sm:w-[78px]">
+							{formatTime(
+								action.completedAt ?? action.startedAt ?? action.plannedAt,
+							)}
+						</span>
+						<span className="min-w-0 flex-1">
+							<span className="block wrap-break-word text-sm">
+								{action.summary}
+							</span>
+							<span className="block wrap-break-word text-muted-foreground text-xs">
+								{action.provider} · {humanStatus(action.status)}
+								{action.targetLabel ? ` · ${action.targetLabel}` : ""}
+							</span>
+						</span>
+						<span className="col-start-2 min-w-0 wrap-break-word font-mono text-muted-foreground text-xs sm:col-auto sm:shrink-0">
+							{action.externalId ?? action.id.slice(0, 12)}
+						</span>
+					</div>
+				))}
+				{condensedEvents > 0 ? (
+					<div className="flex min-h-9 items-center border-t px-4 py-2 text-muted-foreground text-xs sm:px-5">
+						{condensedEvents} streaming{" "}
+						{condensedEvents === 1 ? "update" : "updates"} condensed
+					</div>
+				) : null}
+			</div>
+		</div>
+	);
+}
+
+function RunMeta({
+	label,
+	value,
+	last = false,
+}: {
+	label: string;
+	value: string;
+	last?: boolean;
+}) {
+	return (
+		<span
+			className={cn(
+				"flex min-w-0 flex-col gap-0.5 sm:flex-1",
+				last && "sm:max-w-44",
+			)}
+		>
+			<span className="text-muted-foreground text-xs">{label}</span>
+			<span className="wrap-break-word text-sm sm:truncate">{value}</span>
+		</span>
+	);
+}
+
+function AgentActivity({ activity }: { activity: Activity }) {
+	const [kind, setKind] = useState("ALL");
+	const rows = activity as unknown as ActivityRow[];
+	const visible = rows.filter(
+		(event) => kind === "ALL" || event.type.startsWith(kind),
+	);
+
+	return (
+		<div className="flex min-w-0 flex-col gap-4 sm:gap-6">
+			<div className="flex min-h-7 flex-wrap items-center justify-start gap-2 sm:justify-end sm:gap-3">
+				<select
+					value={kind}
+					onChange={(event) => setKind(event.target.value)}
+					aria-label="Filter activity"
+					className="h-7 rounded-md border bg-muted px-2.5 font-medium text-xs outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
+				>
+					<option value="ALL">All changes</option>
+					<option value="agent.">Agent changes</option>
+					<option value="run.">Run requests</option>
+				</select>
+				<Button
+					variant="outline"
+					size="sm"
+					onClick={() => exportJson("agent-activity.json", visible)}
+				>
+					<Icon icon={Download} data-icon="inline-start" />
+					Export
+				</Button>
+			</div>
+
+			<div className="min-w-0 overflow-hidden rounded-lg border bg-card">
+				<div className="hidden h-9 items-center border-b bg-background px-5 text-muted-foreground text-xs sm:flex">
+					<span className="w-[166px] shrink-0">Time</span>
+					<span className="min-w-0 flex-1">Change</span>
+					<span className="w-[140px] shrink-0">Actor</span>
+					<span className="w-[118px] shrink-0 text-right">Request</span>
+				</div>
+				{visible.map((event) => (
+					<div
+						key={event.id}
+						className="flex min-h-11 min-w-0 flex-col items-start gap-2 border-t px-4 py-3 first:border-t-0 sm:flex-row sm:items-center sm:gap-0 sm:px-5"
+					>
+						<span className="shrink-0 font-mono text-muted-foreground text-xs sm:w-[166px]">
+							{formatDate(event.emittedAt)}
+						</span>
+						<span className="min-w-0 flex-1">
+							<span className="block wrap-break-word text-sm">
+								{event.summary}
+							</span>
+							{changeDetail(event.before, event.after) ? (
+								<span className="block max-w-full whitespace-pre-wrap wrap-break-word font-mono text-muted-foreground text-xs">
+									{changeDetail(event.before, event.after)}
+								</span>
+							) : null}
+						</span>
+						<span className="min-w-0 wrap-break-word text-xs sm:w-[140px] sm:shrink-0 sm:text-sm">
+							<span className="text-muted-foreground sm:hidden">Actor · </span>
+							{event.actorUser?.name ?? event.actorId ?? event.actorType}
+						</span>
+						<span className="min-w-0 wrap-break-word font-mono text-muted-foreground text-xs sm:w-[118px] sm:shrink-0 sm:text-right">
+							<span className="font-sans sm:hidden">Request · </span>
+							{event.requestId?.slice(0, 12) ?? "—"}
+						</span>
+					</div>
+				))}
+			</div>
+		</div>
+	);
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function textOf(value: unknown, fallback: string): string {
+	return typeof value === "string" && value.trim() ? value : fallback;
+}
+
+function humanStatus(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/_/g, " ")
+		.replace(/^./, (character) => character.toUpperCase());
+}
+
+function formatDate(value: string): string {
+	return new Intl.DateTimeFormat(undefined, {
+		month: "short",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		second: "2-digit",
+	}).format(new Date(value));
+}
+
+function formatTime(value: string): string {
+	return new Intl.DateTimeFormat(undefined, {
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hour12: false,
+	}).format(new Date(value));
+}
+
+function duration(startedAt: string | null, finishedAt: string | null): string {
+	if (!startedAt) return "—";
+	const milliseconds =
+		(finishedAt ? new Date(finishedAt) : new Date()).getTime() -
+		new Date(startedAt).getTime();
+	return `${Math.max(0, milliseconds / 1000).toFixed(1)}s`;
+}
+
+function eventLabel(type: string, data: unknown): string {
+	const payload = recordOf(data);
+	return textOf(payload.summary, humanStatus(type.replace(/\./g, " ")));
+}
+
+function changeDetail(before: unknown, after: unknown): string | null {
+	if (!before && !after) return null;
+	const previous = JSON.stringify(before);
+	const next = JSON.stringify(after);
+	return previous && next ? `${previous} → ${next}` : next || previous;
+}
+
+function exportJson(name: string, value: unknown) {
+	const url = URL.createObjectURL(
+		new Blob([JSON.stringify(value, null, 2)], { type: "application/json" }),
+	);
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = name;
+	anchor.click();
+	URL.revokeObjectURL(url);
+}
diff --git a/apps/app/components/agent-builder/team-agents-index.tsx b/apps/app/components/agent-builder/team-agents-index.tsx
new file mode 100644
index 00000000..e974f4de
--- /dev/null
+++ b/apps/app/components/agent-builder/team-agents-index.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import ArrowRight from "@carbon/icons-react/es/ArrowRight";
+import Bot from "@carbon/icons-react/es/Bot";
+import { Icon } from "@crm/ui/components/icon";
+import { useQuery } from "@tanstack/react-query";
+import Link from "next/link";
+import { useTRPC } from "@/lib/trpc/client";
+
+export function TeamAgentsIndex() {
+	const trpc = useTRPC();
+	const agents = useQuery(trpc.agents.list.queryOptions());
+
+	return (
+		<main className="min-h-0 min-w-0 flex-1 overflow-y-auto px-4 py-6 sm:px-6 sm:py-10">
+			<div className="mx-auto flex w-full min-w-0 max-w-[1040px] flex-col gap-6">
+				<div>
+					<h1 className="text-balance font-semibold text-2xl tracking-tight sm:text-3xl">
+						Team agents
+					</h1>
+					<p className="mt-2 text-pretty text-muted-foreground text-sm">
+						Durable automations created from private agent-builder chats.
+					</p>
+				</div>
+
+				{agents.data?.length ? (
+					<div className="overflow-hidden rounded-lg border bg-card">
+						{agents.data.map((agent) => (
+							<Link
+								key={agent.id}
+								href={`/agents/${agent.id}`}
+								transitionTypes={["nav-forward"]}
+								className="flex min-h-16 min-w-0 items-start gap-3 border-t px-4 py-4 outline-none first:border-t-0 hover:bg-muted/50 focus-visible:bg-muted/50 sm:items-center sm:gap-4 sm:px-5 sm:py-3"
+							>
+								<span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+									<Icon icon={Bot} />
+								</span>
+								<span className="min-w-0 flex-1">
+									<span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+										<span className="min-w-0 wrap-break-word font-medium text-sm sm:truncate">
+											{agent.name}
+										</span>
+										<span className="shrink-0 text-muted-foreground text-xs">
+											{agent.status.toLowerCase()}
+										</span>
+									</span>
+									<span className="mt-1 block wrap-break-word text-muted-foreground text-xs sm:mt-0 sm:truncate">
+										{agent.description ?? "No description"}
+									</span>
+									<span className="mt-2 block font-mono text-muted-foreground text-xs sm:hidden">
+										{agent.runCount} runs
+									</span>
+								</span>
+								<span className="hidden shrink-0 font-mono text-muted-foreground text-xs sm:inline">
+									{agent.runCount} runs
+								</span>
+								<Icon
+									icon={ArrowRight}
+									className="size-4 text-muted-foreground"
+								/>
+							</Link>
+						))}
+					</div>
+				) : (
+					<div className="flex min-h-64 flex-col items-center justify-center rounded-lg border border-dashed text-center">
+						<Icon icon={Bot} className="size-6 text-muted-foreground" />
+						<h2 className="mt-4 font-medium text-sm">No team agents yet</h2>
+						<p className="mt-1 text-muted-foreground text-xs">
+							Create one from a private chat, then review its access before
+							deploy.
+						</p>
+						<Link
+							href="/agents"
+							className="mt-4 text-primary text-xs hover:underline"
+						>
+							Open the agent builder
+						</Link>
+					</div>
+				)}
+			</div>
+		</main>
+	);
+}
diff --git a/apps/app/components/app-icon-rail.tsx b/apps/app/components/app-icon-rail.tsx
index 659ae1df..fccded8b 100644
--- a/apps/app/components/app-icon-rail.tsx
+++ b/apps/app/components/app-icon-rail.tsx
@@ -1,7 +1,9 @@
 "use client";
 
+import Bot from "@carbon/icons-react/es/Bot";
 import Building from "@carbon/icons-react/es/Building";
 import type { CarbonIconType } from "@carbon/icons-react/es/CarbonIcon";
+import Close from "@carbon/icons-react/es/Close";
 import Dashboard from "@carbon/icons-react/es/Dashboard";
 import Partnership from "@carbon/icons-react/es/Partnership";
 import Settings from "@carbon/icons-react/es/Settings";
@@ -22,6 +24,7 @@ import {
 import { cn } from "@crm/ui/lib/utils";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
+import { AgentBuilderSidebar } from "@/components/agent-builder/agent-builder-sidebar";
 import { useMobileNav } from "@/components/mobile-nav";
 
 type RailItem = {
@@ -29,6 +32,7 @@ type RailItem = {
 	href: string;
 	icon: CarbonIconType;
 	match: "exact" | "prefix";
+	related?: string[];
 };
 
 const ITEMS: RailItem[] = [
@@ -41,13 +45,21 @@ const ITEMS: RailItem[] = [
 		match: "prefix",
 	},
 	{ title: "Deals", href: "/deals", icon: Partnership, match: "prefix" },
+	{
+		title: "Agents",
+		href: "/agents",
+		icon: Bot,
+		match: "prefix",
+		related: ["/agent", "/chat"],
+	},
 	{ title: "Settings", href: "/settings", icon: Settings, match: "prefix" },
 ];
 
 function isActive(item: RailItem, pathname: string): boolean {
 	return (
 		pathname === item.href ||
-		(item.match === "prefix" && pathname.startsWith(item.href))
+		(item.match === "prefix" && pathname.startsWith(item.href)) ||
+		Boolean(item.related?.some((prefix) => pathname.startsWith(prefix)))
 	);
 }
 
@@ -103,6 +115,9 @@ function MobileRailLink({
 				href={item.href}
 				aria-current={active ? "page" : undefined}
 				onClick={onNavigate}
+				transitionTypes={[
+					item.title === "Agents" ? "nav-forward" : "nav-lateral",
+				]}
 			>
 				<Icon icon={item.icon} />
 				<span>{item.title}</span>
@@ -111,9 +126,46 @@ function MobileRailLink({
 	);
 }
 
+function MobileRailIconLink({
+	item,
+	active,
+	onNavigate,
+}: {
+	item: RailItem;
+	active: boolean;
+	onNavigate: () => void;
+}) {
+	return (
+		<Button
+			asChild
+			variant="ghost"
+			size="icon"
+			className={cn(
+				"text-muted-foreground",
+				active &&
+					"bg-muted text-foreground hover:bg-muted hover:text-foreground",
+			)}
+		>
+			<Link
+				href={item.href}
+				aria-current={active ? "page" : undefined}
+				onClick={onNavigate}
+			>
+				<Icon icon={item.icon} />
+				<span className="sr-only">{item.title}</span>
+			</Link>
+		</Button>
+	);
+}
+
 export function AppIconRail() {
 	const pathname = usePathname();
 	const { open, setOpen } = useMobileNav();
+	const inAgents =
+		pathname === "/agent" ||
+		pathname === "/agents" ||
+		pathname.startsWith("/agents/") ||
+		pathname.startsWith("/chat/");
 
 	return (
 		<>
@@ -131,21 +183,62 @@ export function AppIconRail() {
 			</nav>
 
 			<Sheet open={open} onOpenChange={setOpen}>
-				<SheetContent side="left" className="w-64 gap-0 p-0">
-					<SheetHeader>
-						<SheetTitle>Navigation</SheetTitle>
-					</SheetHeader>
-					<nav aria-label="Primary" className="flex flex-1 flex-col gap-1 p-2">
-						{ITEMS.map((item) => (
-							<MobileRailLink
-								key={item.href}
-								item={item}
-								active={isActive(item, pathname)}
-								onNavigate={() => setOpen(false)}
-							/>
-						))}
-					</nav>
-				</SheetContent>
+				{inAgents ? (
+					<SheetContent
+						side="left"
+						showCloseButton={false}
+						className="w-5/6 max-w-sm flex-row gap-0 p-0"
+					>
+						<SheetHeader className="sr-only">
+							<SheetTitle>Navigation and agent chats</SheetTitle>
+						</SheetHeader>
+						<nav
+							aria-label="Primary"
+							className="flex w-14 shrink-0 flex-col items-center gap-1 border-r py-3"
+						>
+							<Button
+								variant="ghost"
+								size="icon"
+								aria-label="Close navigation"
+								onClick={() => setOpen(false)}
+							>
+								<Icon icon={Close} />
+							</Button>
+							<div className="my-1 h-px w-5 bg-border" />
+							{ITEMS.map((item) => (
+								<MobileRailIconLink
+									key={item.href}
+									item={item}
+									active={isActive(item, pathname)}
+									onNavigate={() => setOpen(false)}
+								/>
+							))}
+						</nav>
+						<AgentBuilderSidebar
+							className="flex flex-1"
+							onNavigate={() => setOpen(false)}
+						/>
+					</SheetContent>
+				) : (
+					<SheetContent side="left" className="w-64 gap-0 p-0">
+						<SheetHeader>
+							<SheetTitle>Navigation</SheetTitle>
+						</SheetHeader>
+						<nav
+							aria-label="Primary"
+							className="flex flex-1 flex-col gap-1 p-2"
+						>
+							{ITEMS.map((item) => (
+								<MobileRailLink
+									key={item.href}
+									item={item}
+									active={isActive(item, pathname)}
+									onNavigate={() => setOpen(false)}
+								/>
+							))}
+						</nav>
+					</SheetContent>
+				)}
 			</Sheet>
 		</>
 	);
diff --git a/apps/app/components/crm/agent-conversations.tsx b/apps/app/components/crm/agent-conversations.tsx
index 94e778ff..5aa589f7 100644
--- a/apps/app/components/crm/agent-conversations.tsx
+++ b/apps/app/components/crm/agent-conversations.tsx
@@ -42,7 +42,7 @@ export function ConversationPicker({
 	const label = current?.title ?? "New conversation";
 
 	return (
-		<div className="flex items-center gap-2 border-b px-5 py-2">
+		<div className="flex min-w-0 items-center gap-2 border-b px-4 py-2 sm:px-5">
 			<DropdownMenu>
 				<DropdownMenuTrigger asChild>
 					<Button
diff --git a/apps/app/components/crm/agent-panel.tsx b/apps/app/components/crm/agent-panel.tsx
index 48edb238..69526906 100644
--- a/apps/app/components/crm/agent-panel.tsx
+++ b/apps/app/components/crm/agent-panel.tsx
@@ -221,7 +221,7 @@ function Thread({
 			<MessageScrollerProvider autoScroll defaultScrollPosition="end">
 				<MessageScroller className="flex-1">
 					<MessageScrollerViewport>
-						<MessageScrollerContent className="gap-3 px-5 py-4">
+						<MessageScrollerContent className="gap-3 px-4 py-4 sm:px-5">
 							{messages.length === 0 && !busy ? (
 								<Idle kind={record.kind} onAsk={ask} />
 							) : null}
@@ -251,15 +251,15 @@ function Thread({
 			{agent.error ? <Failure message={agent.error.message} /> : null}
 
 			{thread?.status === "working" && !busy ? (
-				<p className="border-t px-5 py-2 text-muted-foreground text-xs">
+				<p className="border-t px-4 py-2 text-pretty text-muted-foreground text-xs sm:px-5">
 					Still working on the last question. Your next one can go in when it
 					finishes.
 				</p>
 			) : null}
 
 			{ended ? (
-				<div className="flex items-center justify-between gap-3 border-t px-5 py-2">
-					<p className="text-muted-foreground text-xs">
+				<div className="flex flex-col items-start gap-3 border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:px-5 sm:py-2">
+					<p className="text-pretty text-muted-foreground text-xs">
 						This conversation has ended.
 					</p>
 					<Button variant="outline" size="sm" onClick={onNewThread}>
@@ -269,7 +269,7 @@ function Thread({
 			) : null}
 
 			<form
-				className="flex items-center gap-2 border-t px-5 py-3"
+				className="flex min-w-0 items-center gap-2 border-t px-4 py-3 sm:px-5"
 				onSubmit={(event) => {
 					event.preventDefault();
 					ask(draft);
@@ -340,9 +340,11 @@ function Failure({ message }: { message: string }) {
 			: null;
 
 	return (
-		<div className="border-t px-5 py-3 text-xs">
-			<p className="text-destructive">{message}</p>
-			{hint ? <p className="text-muted-foreground text-xs">{hint}</p> : null}
+		<div className="border-t px-4 py-3 text-xs sm:px-5">
+			<p className="wrap-break-word text-destructive">{message}</p>
+			{hint ? (
+				<p className="wrap-break-word text-muted-foreground text-xs">{hint}</p>
+			) : null}
 		</div>
 	);
 }
@@ -362,20 +364,20 @@ const SOURCE_ICONS: Record<Source["network"], CarbonIcon> = {
 function Item({ item }: { item: TranscriptItem }) {
 	if (item.kind === "said") {
 		return item.mine ? (
-			<Message align="end">
+			<Message align="end" className="min-w-0">
 				<MessageContent>
 					<Bubble variant="secondary" align="end">
-						<BubbleContent>{item.text}</BubbleContent>
+						<BubbleContent className="text-pretty">{item.text}</BubbleContent>
 					</Bubble>
 				</MessageContent>
 			</Message>
 		) : (
-			<Message>
+			<Message className="min-w-0">
 				<AgentAvatar />
 				<MessageContent>
 					<Bubble variant="ghost">
 						<BubbleContent>
-							<Markdown>{item.text}</Markdown>
+							<Markdown className="wrap-break-word">{item.text}</Markdown>
 						</BubbleContent>
 					</Bubble>
 				</MessageContent>
@@ -384,7 +386,7 @@ function Item({ item }: { item: TranscriptItem }) {
 	}
 
 	return (
-		<div className="space-y-1.5">
+		<div className="min-w-0 space-y-1.5">
 			<Marker>
 				<MarkerIcon>
 					{item.pending ? <Spinner /> : <Icon icon={TONE_ICONS[item.tone]} />}
@@ -438,11 +440,13 @@ function Question({
 	agent: ReturnType<typeof useEveAgent>;
 }) {
 	return (
-		<Message>
+		<Message className="min-w-0">
 			<AgentAvatar />
 			<MessageContent>
 				<Bubble variant="tinted">
-					<BubbleContent>{question.prompt}</BubbleContent>
+					<BubbleContent className="text-pretty">
+						{question.prompt}
+					</BubbleContent>
 				</Bubble>
 
 				<div className="flex flex-wrap gap-2">
diff --git a/apps/app/lib/agent-builder.ts b/apps/app/lib/agent-builder.ts
new file mode 100644
index 00000000..1e2977c8
--- /dev/null
+++ b/apps/app/lib/agent-builder.ts
@@ -0,0 +1,15 @@
+export type BuilderCommandType = "CHAT" | "CREATE_AGENT";
+
+export function builderCommandType(message: string): BuilderCommandType {
+	return /^\/create\s+agent(?:\s|$)/i.test(message.trimStart())
+		? "CREATE_AGENT"
+		: "CHAT";
+}
+
+export function hasCreateAgentCommand(
+	submissions: ReadonlyArray<{ commandType: BuilderCommandType }>,
+): boolean {
+	return submissions.some(
+		(submission) => submission.commandType === "CREATE_AGENT",
+	);
+}
diff --git a/apps/app/lib/agent-transcript.ts b/apps/app/lib/agent-transcript.ts
index 662a955f..b89293b7 100644
--- a/apps/app/lib/agent-transcript.ts
+++ b/apps/app/lib/agent-transcript.ts
@@ -19,6 +19,16 @@ export type Source = {
 	network: "linkedin" | "github" | "web";
 };
 
+export type AgentTurnFailure = {
+	code: string;
+	kind: "rate-limit" | "restricted" | "credits" | "unknown";
+};
+
+type AgentStreamEvent = {
+	type: string;
+	data?: unknown;
+};
+
 const VERBS: Record<string, string> = {
 	read_crm_history: "Read our emails and meetings with them",
 	read_company_history: "Read everything we have on the company",
@@ -183,12 +193,52 @@ export function pendingQuestion(messages: readonly EveMessage[]) {
 	return null;
 }
 
+export function latestTurnFailure(
+	events: readonly AgentStreamEvent[],
+): AgentTurnFailure | null {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (!event) continue;
+		if (event.type === "turn.completed") return null;
+		if (event.type !== "turn.failed" && event.type !== "session.failed") {
+			continue;
+		}
+
+		const data = recordOf(event.data);
+		const message = typeof data.message === "string" ? data.message : "";
+		const code = typeof data.code === "string" ? data.code : "AGENT_FAILED";
+
+		return {
+			code,
+			kind: /free tier users do not have access|RestrictedModelsError/i.test(
+				message,
+			)
+				? "restricted"
+				: /GatewayRateLimitError|free tier requests.*rate-?limited/i.test(
+							message,
+						)
+					? "rate-limit"
+					: /credits?|quota|billing|usage limit/i.test(message)
+						? "credits"
+						: "unknown",
+		};
+	}
+
+	return null;
+}
+
 function output(part: EveMessagePart): Record<string, unknown> | null {
 	return "output" in part && part.output && typeof part.output === "object"
 		? (part.output as Record<string, unknown>)
 		: null;
 }
 
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
 function hostOf(url: string): string {
 	try {
 		return new URL(url).hostname.replace(/^www\./, "");
diff --git a/apps/app/next.config.ts b/apps/app/next.config.ts
index 9c9bca2a..44763346 100644
--- a/apps/app/next.config.ts
+++ b/apps/app/next.config.ts
@@ -8,7 +8,19 @@ const apiUrl =
 	process.env.NEXT_PUBLIC_API_URL ??
 	"http://localhost:3001";
 
+const allowedDevOrigins = (process.env.APP_URL ?? "")
+	.split(",")
+	.flatMap((origin) => {
+		try {
+			return [new URL(origin.trim()).hostname];
+		} catch {
+			return [];
+		}
+	});
+
 const nextConfig: NextConfig = {
+	allowedDevOrigins,
+
 	env: {
 		NEXT_PUBLIC_API_URL: apiUrl,
 	},
diff --git a/apps/app/test/agent-builder.spec.ts b/apps/app/test/agent-builder.spec.ts
new file mode 100644
index 00000000..3e412e58
--- /dev/null
+++ b/apps/app/test/agent-builder.spec.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "bun:test";
+import {
+	builderCommandType,
+	hasCreateAgentCommand,
+} from "../lib/agent-builder";
+
+describe("agent builder commands", () => {
+	it("only enters agent creation for the explicit slash command", () => {
+		expect(builderCommandType("/Create agent Flag stalled deals")).toBe(
+			"CREATE_AGENT",
+		);
+		expect(builderCommandType("  /create agent summarize renewals")).toBe(
+			"CREATE_AGENT",
+		);
+		expect(builderCommandType("Tell me about this customer")).toBe("CHAT");
+		expect(builderCommandType("/Create agentic workflows")).toBe("CHAT");
+	});
+
+	it("shows creation surfaces only after a creation command", () => {
+		expect(hasCreateAgentCommand([{ commandType: "CHAT" }])).toBe(false);
+		expect(
+			hasCreateAgentCommand([
+				{ commandType: "CHAT" },
+				{ commandType: "CREATE_AGENT" },
+			]),
+		).toBe(true);
+	});
+});
diff --git a/apps/app/test/agent-transcript.spec.ts b/apps/app/test/agent-transcript.spec.ts
index d7cfb62d..be70e012 100644
--- a/apps/app/test/agent-transcript.spec.ts
+++ b/apps/app/test/agent-transcript.spec.ts
@@ -3,6 +3,7 @@ import { readdirSync } from "node:fs";
 import type { EveMessage } from "eve/react";
 import {
 	describe as describeStep,
+	latestTurnFailure,
 	NEW_THREAD,
 	outcomeTone,
 	pendingQuestion,
@@ -220,6 +221,58 @@ describe("pendingQuestion", () => {
 	});
 });
 
+describe("latestTurnFailure", () => {
+	it("recognizes the Vercel Gateway free-tier rate limit", () => {
+		expect(
+			latestTurnFailure([
+				{
+					type: "turn.failed",
+					data: {
+						code: "MODEL_CALL_FAILED",
+						message:
+							"GatewayRateLimitError: Free tier requests on this model are rate-limited.",
+					},
+				},
+			]),
+		).toEqual({ code: "MODEL_CALL_FAILED", kind: "rate-limit" });
+	});
+
+	it("does not keep an earlier failure after a later turn completes", () => {
+		expect(
+			latestTurnFailure([
+				{ type: "turn.failed", data: { message: "Provider unavailable" } },
+				{ type: "turn.completed", data: {} },
+				{ type: "session.waiting", data: {} },
+			]),
+		).toBeNull();
+	});
+
+	it("recognizes a model restricted to paid Gateway credits", () => {
+		expect(
+			latestTurnFailure([
+				{
+					type: "session.failed",
+					data: {
+						code: "MODEL_CALL_FAILED",
+						message: "Free tier users do not have access to this model.",
+					},
+				},
+			]),
+		).toEqual({ code: "MODEL_CALL_FAILED", kind: "restricted" });
+	});
+
+	it("keeps provider details out of the display contract", () => {
+		expect(
+			latestTurnFailure([
+				{
+					type: "session.failed",
+					data: { message: "Internal provider stack and request body" },
+				},
+			]),
+		).toEqual({ code: "AGENT_FAILED", kind: "unknown" });
+	});
+});
+
 describe("resolveThread", () => {
 	const rows = [
 		{ id: "c2", title: "Thursday" },
diff --git a/docs/environment.md b/docs/environment.md
index de37b77b..d3f50307 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -260,11 +260,13 @@ rather than leaving it to be discovered on a settings page nobody visits.
     brand, and a free-provider address is refused with a documented `422`
     before any resolution — so `key-check@gmail.com` reaches Context, proves
     the key authenticates, and is never billed. Measured at about half a second.
-  - **`401` is the only answer that means the key is wrong.** A `403` about the
-    plan, a `422` refusing the probe, a `429`, a `500` — all of those were
-    served *after* the key authenticated, so the key is good and only the probe
-    was refused. `classifyKey` in `lib/context-dev.ts` holds that rule and
-    `test/verify-key.spec.ts` pins every branch of it.
+  - **An authentication status does not necessarily mean the key is wrong.**
+    Context returns `401` for an exhausted free-tier allowance as well as for
+    an invalid key, and `401` or `403` can also represent insufficient credits
+    or permissions. `classifyKey` inspects the stable error code and response
+    message before rejecting a key; quota, plan, rate-limit and permission
+    responses prove the key was recognised and allow it to be saved.
+    `test/verify-key.spec.ts` pins those branches.
   - **A check that cannot be made is not a failed check.** No
     `AGENT_BRIDGE_SECRET`, an agent that is down, a timeout — all return
     `unknown`, and an unknown answer *saves the key* and logs that it went in
diff --git a/packages/db/prisma/migrations/20260803210000_agent_builder_foundation/migration.sql b/packages/db/prisma/migrations/20260803210000_agent_builder_foundation/migration.sql
new file mode 100644
index 00000000..02373332
--- /dev/null
+++ b/packages/db/prisma/migrations/20260803210000_agent_builder_foundation/migration.sql
@@ -0,0 +1,290 @@
+CREATE TYPE "AgentConversationKind" AS ENUM ('RECORD', 'BUILDER');
+CREATE TYPE "AgentDefinitionStatus" AS ENUM ('DRAFT', 'DEPLOYING', 'LIVE', 'PAUSED', 'ARCHIVED', 'DELETED');
+CREATE TYPE "AgentVersionStatus" AS ENUM ('DRAFT', 'VALIDATING', 'READY', 'DEPLOYED', 'REJECTED');
+CREATE TYPE "AgentTriggerType" AS ENUM ('MANUAL', 'SCHEDULE', 'EVENT', 'WEBHOOK');
+CREATE TYPE "AgentRunStatus" AS ENUM ('QUEUED', 'RUNNING', 'WAITING_FOR_APPROVAL', 'SUCCEEDED', 'FAILED', 'CANCELLED');
+CREATE TYPE "AgentActionStatus" AS ENUM ('PLANNED', 'RUNNING', 'SUCCEEDED', 'FAILED', 'CANCELLED');
+CREATE TYPE "AgentConversationShareScope" AS ENUM ('WORKSPACE_LINK');
+CREATE TYPE "AgentConversationSubmissionStatus" AS ENUM ('PENDING', 'SENDING', 'ACCEPTED', 'FAILED', 'CANCELLED');
+
+CREATE TYPE "AgentResponseRating" AS ENUM ('UP', 'DOWN');
+
+ALTER TABLE "agentConversation"
+ADD COLUMN "kind" "AgentConversationKind" NOT NULL DEFAULT 'RECORD',
+ADD COLUMN "agentId" TEXT,
+ADD COLUMN "updatedAt" TIMESTAMP(3),
+ADD COLUMN "lastAssistantAt" TIMESTAMP(3),
+ADD COLUMN "lastReadAt" TIMESTAMP(3);
+
+ALTER TABLE "agentConversation"
+ALTER COLUMN "sessionId" DROP NOT NULL;
+
+UPDATE "agentConversation"
+SET "updatedAt" = "lastMessageAt";
+
+ALTER TABLE "agentConversation"
+ALTER COLUMN "updatedAt" SET NOT NULL;
+
+CREATE TABLE "agentDefinition" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "status" "AgentDefinitionStatus" NOT NULL DEFAULT 'DRAFT',
+    "createdById" TEXT NOT NULL,
+    "currentVersionId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "archivedAt" TIMESTAMP(3),
+    "deletedAt" TIMESTAMP(3),
+
+    CONSTRAINT "agentDefinition_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentVersion" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "number" INTEGER NOT NULL,
+    "status" "AgentVersionStatus" NOT NULL DEFAULT 'DRAFT',
+    "instructions" TEXT NOT NULL,
+    "manifest" JSONB NOT NULL,
+    "modelId" TEXT NOT NULL,
+    "sandboxPolicy" JSONB NOT NULL,
+    "validation" JSONB,
+    "sourceConversationId" TEXT,
+    "createdById" TEXT NOT NULL,
+    "deploymentId" TEXT,
+    "approvedAt" TIMESTAMP(3),
+    "deployedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "agentVersion_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentTrigger" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "versionId" TEXT NOT NULL,
+    "type" "AgentTriggerType" NOT NULL,
+    "name" TEXT NOT NULL,
+    "config" JSONB NOT NULL,
+    "createdById" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT false,
+    "nextRunAt" TIMESTAMP(3),
+    "lastRunAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "agentTrigger_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentRun" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "versionId" TEXT NOT NULL,
+    "triggerId" TEXT,
+    "initiatedById" TEXT,
+    "triggerType" "AgentTriggerType" NOT NULL,
+    "status" "AgentRunStatus" NOT NULL DEFAULT 'QUEUED',
+    "principalId" TEXT,
+    "sessionId" TEXT,
+    "idempotencyKey" TEXT NOT NULL,
+    "correlationId" TEXT NOT NULL,
+    "input" JSONB,
+    "result" JSONB,
+    "summary" TEXT,
+    "modelId" TEXT,
+    "inputTokens" INTEGER,
+    "outputTokens" INTEGER,
+    "costUsd" DECIMAL(12,6),
+    "errorCode" TEXT,
+    "errorMessage" TEXT,
+    "nextEventSequence" INTEGER NOT NULL DEFAULT 0,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "startedAt" TIMESTAMP(3),
+    "finishedAt" TIMESTAMP(3),
+
+    CONSTRAINT "agentRun_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentRunEvent" (
+    "id" TEXT NOT NULL,
+    "runId" TEXT NOT NULL,
+    "sequence" INTEGER NOT NULL,
+    "type" TEXT NOT NULL,
+    "data" JSONB NOT NULL,
+    "emittedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "agentRunEvent_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentAction" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "runId" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "targetType" TEXT,
+    "targetId" TEXT,
+    "targetLabel" TEXT,
+    "summary" TEXT NOT NULL,
+    "metadata" JSONB,
+    "status" "AgentActionStatus" NOT NULL DEFAULT 'PLANNED',
+    "idempotencyKey" TEXT NOT NULL,
+    "requestHash" TEXT,
+    "externalId" TEXT,
+    "attemptCount" INTEGER NOT NULL DEFAULT 0,
+    "errorCode" TEXT,
+    "errorMessage" TEXT,
+    "plannedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "startedAt" TIMESTAMP(3),
+    "completedAt" TIMESTAMP(3),
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "agentAction_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentAuditEvent" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "versionId" TEXT,
+    "actorUserId" TEXT,
+    "type" TEXT NOT NULL,
+    "actorType" TEXT NOT NULL,
+    "actorId" TEXT,
+    "summary" TEXT NOT NULL,
+    "before" JSONB,
+    "after" JSONB,
+    "requestId" TEXT,
+    "emittedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "agentAuditEvent_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentConversationShare" (
+    "id" TEXT NOT NULL,
+    "conversationId" TEXT NOT NULL,
+    "createdById" TEXT NOT NULL,
+    "scope" "AgentConversationShareScope" NOT NULL DEFAULT 'WORKSPACE_LINK',
+    "tokenHash" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expiresAt" TIMESTAMP(3),
+    "revokedAt" TIMESTAMP(3),
+
+    CONSTRAINT "agentConversationShare_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentConversationSubmission" (
+    "id" TEXT NOT NULL,
+    "conversationId" TEXT NOT NULL,
+    "submittedById" TEXT NOT NULL,
+    "clientRequestId" TEXT NOT NULL,
+    "message" JSONB NOT NULL,
+    "status" "AgentConversationSubmissionStatus" NOT NULL DEFAULT 'PENDING',
+    "attemptCount" INTEGER NOT NULL DEFAULT 0,
+    "errorCode" TEXT,
+    "errorMessage" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "sentAt" TIMESTAMP(3),
+    "acceptedAt" TIMESTAMP(3),
+
+    CONSTRAINT "agentConversationSubmission_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "agentConversationFeedback" (
+    "id" TEXT NOT NULL,
+    "conversationId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "messageId" TEXT NOT NULL,
+    "rating" "AgentResponseRating" NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "agentConversationFeedback_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "agentDefinition_currentVersionId_key" ON "agentDefinition"("currentVersionId");
+CREATE INDEX "agentDefinition_status_updatedAt_idx" ON "agentDefinition"("status", "updatedAt");
+CREATE INDEX "agentDefinition_createdById_createdAt_idx" ON "agentDefinition"("createdById", "createdAt");
+
+CREATE UNIQUE INDEX "agentVersion_agentId_number_key" ON "agentVersion"("agentId", "number");
+CREATE INDEX "agentVersion_agentId_createdAt_idx" ON "agentVersion"("agentId", "createdAt");
+CREATE INDEX "agentVersion_status_createdAt_idx" ON "agentVersion"("status", "createdAt");
+
+CREATE INDEX "agentTrigger_agentId_enabled_idx" ON "agentTrigger"("agentId", "enabled");
+CREATE INDEX "agentTrigger_enabled_nextRunAt_idx" ON "agentTrigger"("enabled", "nextRunAt");
+CREATE INDEX "agentTrigger_versionId_idx" ON "agentTrigger"("versionId");
+
+CREATE UNIQUE INDEX "agentRun_sessionId_key" ON "agentRun"("sessionId");
+CREATE UNIQUE INDEX "agentRun_idempotencyKey_key" ON "agentRun"("idempotencyKey");
+CREATE UNIQUE INDEX "agentRun_correlationId_key" ON "agentRun"("correlationId");
+CREATE INDEX "agentRun_agentId_createdAt_idx" ON "agentRun"("agentId", "createdAt");
+CREATE INDEX "agentRun_versionId_createdAt_idx" ON "agentRun"("versionId", "createdAt");
+CREATE INDEX "agentRun_status_createdAt_idx" ON "agentRun"("status", "createdAt");
+CREATE INDEX "agentRun_triggerId_createdAt_idx" ON "agentRun"("triggerId", "createdAt");
+
+CREATE UNIQUE INDEX "agentRunEvent_runId_sequence_key" ON "agentRunEvent"("runId", "sequence");
+CREATE INDEX "agentRunEvent_runId_emittedAt_idx" ON "agentRunEvent"("runId", "emittedAt");
+
+CREATE UNIQUE INDEX "agentAction_idempotencyKey_key" ON "agentAction"("idempotencyKey");
+CREATE INDEX "agentAction_agentId_plannedAt_idx" ON "agentAction"("agentId", "plannedAt");
+CREATE INDEX "agentAction_runId_plannedAt_idx" ON "agentAction"("runId", "plannedAt");
+CREATE INDEX "agentAction_provider_externalId_idx" ON "agentAction"("provider", "externalId");
+CREATE INDEX "agentAction_status_plannedAt_idx" ON "agentAction"("status", "plannedAt");
+
+CREATE INDEX "agentAuditEvent_agentId_emittedAt_idx" ON "agentAuditEvent"("agentId", "emittedAt");
+CREATE INDEX "agentAuditEvent_versionId_emittedAt_idx" ON "agentAuditEvent"("versionId", "emittedAt");
+CREATE INDEX "agentAuditEvent_actorUserId_emittedAt_idx" ON "agentAuditEvent"("actorUserId", "emittedAt");
+CREATE INDEX "agentAuditEvent_type_emittedAt_idx" ON "agentAuditEvent"("type", "emittedAt");
+
+CREATE UNIQUE INDEX "agentAuditEvent_agentId_type_requestId_key" ON "agentAuditEvent"("agentId", "type", "requestId");
+
+CREATE UNIQUE INDEX "agentConversationShare_tokenHash_key" ON "agentConversationShare"("tokenHash");
+CREATE INDEX "agentConversationShare_conversationId_revokedAt_idx" ON "agentConversationShare"("conversationId", "revokedAt");
+
+CREATE UNIQUE INDEX "agentConversationSubmission_clientRequestId_key" ON "agentConversationSubmission"("clientRequestId");
+CREATE INDEX "agentConversationSubmission_conversationId_createdAt_idx" ON "agentConversationSubmission"("conversationId", "createdAt");
+CREATE INDEX "agentConversationSubmission_status_createdAt_idx" ON "agentConversationSubmission"("status", "createdAt");
+
+CREATE UNIQUE INDEX "agentConversationFeedback_conversationId_userId_messageId_key" ON "agentConversationFeedback"("conversationId", "userId", "messageId");
+
+CREATE INDEX "agentConversationFeedback_conversationId_createdAt_idx" ON "agentConversationFeedback"("conversationId", "createdAt");
+
+CREATE INDEX "agentConversation_userId_kind_lastMessageAt_idx" ON "agentConversation"("userId", "kind", "lastMessageAt");
+CREATE INDEX "agentConversation_agentId_lastMessageAt_idx" ON "agentConversation"("agentId", "lastMessageAt");
+
+ALTER TABLE "agentDefinition" ADD CONSTRAINT "agentDefinition_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "user"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentDefinition" ADD CONSTRAINT "agentDefinition_currentVersionId_fkey" FOREIGN KEY ("currentVersionId") REFERENCES "agentVersion"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "agentVersion" ADD CONSTRAINT "agentVersion_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentVersion" ADD CONSTRAINT "agentVersion_sourceConversationId_fkey" FOREIGN KEY ("sourceConversationId") REFERENCES "agentConversation"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+ALTER TABLE "agentVersion" ADD CONSTRAINT "agentVersion_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "user"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "agentConversation" ADD CONSTRAINT "agentConversation_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "agentTrigger" ADD CONSTRAINT "agentTrigger_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentTrigger" ADD CONSTRAINT "agentTrigger_versionId_fkey" FOREIGN KEY ("versionId") REFERENCES "agentVersion"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentTrigger" ADD CONSTRAINT "agentTrigger_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "user"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "agentRun" ADD CONSTRAINT "agentRun_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentRun" ADD CONSTRAINT "agentRun_versionId_fkey" FOREIGN KEY ("versionId") REFERENCES "agentVersion"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentRun" ADD CONSTRAINT "agentRun_triggerId_fkey" FOREIGN KEY ("triggerId") REFERENCES "agentTrigger"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentRun" ADD CONSTRAINT "agentRun_initiatedById_fkey" FOREIGN KEY ("initiatedById") REFERENCES "user"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "agentRunEvent" ADD CONSTRAINT "agentRunEvent_runId_fkey" FOREIGN KEY ("runId") REFERENCES "agentRun"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "agentAction" ADD CONSTRAINT "agentAction_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentAction" ADD CONSTRAINT "agentAction_runId_fkey" FOREIGN KEY ("runId") REFERENCES "agentRun"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "agentAuditEvent" ADD CONSTRAINT "agentAuditEvent_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "agentDefinition"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentAuditEvent" ADD CONSTRAINT "agentAuditEvent_versionId_fkey" FOREIGN KEY ("versionId") REFERENCES "agentVersion"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "agentAuditEvent" ADD CONSTRAINT "agentAuditEvent_actorUserId_fkey" FOREIGN KEY ("actorUserId") REFERENCES "user"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "agentConversationShare" ADD CONSTRAINT "agentConversationShare_conversationId_fkey" FOREIGN KEY ("conversationId") REFERENCES "agentConversation"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "agentConversationShare" ADD CONSTRAINT "agentConversationShare_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "user"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "agentConversationSubmission" ADD CONSTRAINT "agentConversationSubmission_conversationId_fkey" FOREIGN KEY ("conversationId") REFERENCES "agentConversation"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "agentConversationSubmission" ADD CONSTRAINT "agentConversationSubmission_submittedById_fkey" FOREIGN KEY ("submittedById") REFERENCES "user"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "agentConversationFeedback" ADD CONSTRAINT "agentConversationFeedback_conversationId_fkey" FOREIGN KEY ("conversationId") REFERENCES "agentConversation"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "agentConversationFeedback" ADD CONSTRAINT "agentConversationFeedback_userId_fkey" FOREIGN KEY ("userId") REFERENCES "user"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/packages/db/prisma/migrations/20260804160000_agent_conversation_command_type/migration.sql b/packages/db/prisma/migrations/20260804160000_agent_conversation_command_type/migration.sql
new file mode 100644
index 00000000..3d85d0a3
--- /dev/null
+++ b/packages/db/prisma/migrations/20260804160000_agent_conversation_command_type/migration.sql
@@ -0,0 +1,8 @@
+CREATE TYPE "AgentConversationCommandType" AS ENUM ('CHAT', 'CREATE_AGENT');
+
+ALTER TABLE "agentConversationSubmission"
+ADD COLUMN "commandType" "AgentConversationCommandType" NOT NULL DEFAULT 'CHAT';
+
+UPDATE "agentConversationSubmission"
+SET "commandType" = 'CREATE_AGENT'
+WHERE "message"->>'text' ~* '^\s*/create\s+agent(?:\s|$)';
diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma
index 99f028c3..39a2edff 100644
--- a/packages/db/prisma/schema.prisma
+++ b/packages/db/prisma/schema.prisma
@@ -1,4 +1,3 @@
-
 datasource db {
   provider = "postgresql"
 }
@@ -31,6 +30,15 @@ model User {
   factDecisions  ContactFact[]       @relation("FactDecider")
   conversations  AgentConversation[] @relation("ConversationOwner")
 
+  createdAgentDefinitions AgentDefinition[]             @relation("AgentDefinitionCreator")
+  createdAgentVersions    AgentVersion[]                @relation("AgentVersionCreator")
+  createdAgentTriggers    AgentTrigger[]                @relation("AgentTriggerCreator")
+  initiatedAgentRuns      AgentRun[]                    @relation("AgentRunInitiator")
+  agentAuditEvents        AgentAuditEvent[]             @relation("AgentAuditActor")
+  conversationShares      AgentConversationShare[]      @relation("ConversationShareCreator")
+  conversationSubmissions AgentConversationSubmission[] @relation("ConversationSubmissionAuthor")
+  conversationFeedback    AgentConversationFeedback[]   @relation("ConversationFeedbackAuthor")
+
   members     Member[]
   invitations Invitation[]
 
@@ -135,6 +143,74 @@ enum RecordSource {
   CALENDAR
 }
 
+enum AgentConversationKind {
+  RECORD
+  BUILDER
+}
+
+enum AgentDefinitionStatus {
+  DRAFT
+  DEPLOYING
+  LIVE
+  PAUSED
+  ARCHIVED
+  DELETED
+}
+
+enum AgentVersionStatus {
+  DRAFT
+  VALIDATING
+  READY
+  DEPLOYED
+  REJECTED
+}
+
+enum AgentTriggerType {
+  MANUAL
+  SCHEDULE
+  EVENT
+  WEBHOOK
+}
+
+enum AgentRunStatus {
+  QUEUED
+  RUNNING
+  WAITING_FOR_APPROVAL
+  SUCCEEDED
+  FAILED
+  CANCELLED
+}
+
+enum AgentActionStatus {
+  PLANNED
+  RUNNING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+}
+
+enum AgentConversationShareScope {
+  WORKSPACE_LINK
+}
+
+enum AgentConversationSubmissionStatus {
+  PENDING
+  SENDING
+  ACCEPTED
+  FAILED
+  CANCELLED
+}
+
+enum AgentConversationCommandType {
+  CHAT
+  CREATE_AGENT
+}
+
+enum AgentResponseRating {
+  UP
+  DOWN
+}
+
 model Company {
   id          String  @id @default(cuid())
   name        String
@@ -353,6 +429,8 @@ model AgentEvent {
 model AgentConversation {
   id String @id @default(cuid())
 
+  kind AgentConversationKind @default(RECORD)
+
   contactId String?
   contact   Contact? @relation(fields: [contactId], references: [id], onDelete: Cascade)
   companyId String?
@@ -363,22 +441,332 @@ model AgentConversation {
   userId String
   user   User   @relation("ConversationOwner", fields: [userId], references: [id], onDelete: Cascade)
 
-  sessionId         String  @unique
+  agentId String?
+  agent   AgentDefinition? @relation(fields: [agentId], references: [id], onDelete: SetNull)
+
+  sessionId         String? @unique
   continuationToken String?
   streamIndex       Int     @default(0)
 
   title        String?
   messageCount Int     @default(0)
 
-  createdAt     DateTime @default(now())
-  lastMessageAt DateTime @default(now())
+  createdAt       DateTime  @default(now())
+  updatedAt       DateTime  @updatedAt
+  lastMessageAt   DateTime  @default(now())
+  lastAssistantAt DateTime?
+  lastReadAt      DateTime?
+
+  shares          AgentConversationShare[]
+  submissions     AgentConversationSubmission[]
+  feedback        AgentConversationFeedback[]
+  createdVersions AgentVersion[]                @relation("AgentVersionSourceConversation")
 
   @@index([contactId, lastMessageAt])
   @@index([companyId, lastMessageAt])
   @@index([dealId, lastMessageAt])
+  @@index([userId, kind, lastMessageAt])
+  @@index([agentId, lastMessageAt])
   @@map("agentConversation")
 }
 
+model AgentConversationFeedback {
+  id String @id @default(cuid())
+
+  conversationId String
+  conversation   AgentConversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+
+  userId String
+  user   User   @relation("ConversationFeedbackAuthor", fields: [userId], references: [id], onDelete: Cascade)
+
+  messageId String
+  rating    AgentResponseRating
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([conversationId, userId, messageId])
+  @@index([conversationId, createdAt])
+  @@map("agentConversationFeedback")
+}
+
+model AgentConversationShare {
+  id String @id @default(cuid())
+
+  conversationId String
+  conversation   AgentConversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+
+  createdById String
+  createdBy   User   @relation("ConversationShareCreator", fields: [createdById], references: [id], onDelete: Cascade)
+
+  scope     AgentConversationShareScope @default(WORKSPACE_LINK)
+  tokenHash String                      @unique
+
+  createdAt DateTime  @default(now())
+  expiresAt DateTime?
+  revokedAt DateTime?
+
+  @@index([conversationId, revokedAt])
+  @@map("agentConversationShare")
+}
+
+model AgentConversationSubmission {
+  id String @id @default(cuid())
+
+  conversationId String
+  conversation   AgentConversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+
+  submittedById String
+  submittedBy   User   @relation("ConversationSubmissionAuthor", fields: [submittedById], references: [id], onDelete: Restrict)
+
+  clientRequestId String                            @unique
+  commandType     AgentConversationCommandType      @default(CHAT)
+  message         Json
+  status          AgentConversationSubmissionStatus @default(PENDING)
+  attemptCount    Int                               @default(0)
+
+  errorCode    String?
+  errorMessage String?
+
+  createdAt  DateTime  @default(now())
+  sentAt     DateTime?
+  acceptedAt DateTime?
+
+  @@index([conversationId, createdAt])
+  @@index([status, createdAt])
+  @@map("agentConversationSubmission")
+}
+
+model AgentDefinition {
+  id String @id @default(cuid())
+
+  name        String
+  description String?
+  status      AgentDefinitionStatus @default(DRAFT)
+
+  createdById String
+  createdBy   User   @relation("AgentDefinitionCreator", fields: [createdById], references: [id], onDelete: Restrict)
+
+  currentVersionId String?       @unique
+  currentVersion   AgentVersion? @relation("CurrentAgentVersion", fields: [currentVersionId], references: [id], onDelete: SetNull)
+
+  versions      AgentVersion[]      @relation("AgentVersions")
+  triggers      AgentTrigger[]
+  runs          AgentRun[]
+  actions       AgentAction[]
+  auditEvents   AgentAuditEvent[]
+  conversations AgentConversation[]
+
+  createdAt  DateTime  @default(now())
+  updatedAt  DateTime  @updatedAt
+  archivedAt DateTime?
+  deletedAt  DateTime?
+
+  @@index([status, updatedAt])
+  @@index([createdById, createdAt])
+  @@map("agentDefinition")
+}
+
+model AgentVersion {
+  id String @id @default(cuid())
+
+  agentId String
+  agent   AgentDefinition @relation("AgentVersions", fields: [agentId], references: [id], onDelete: Restrict)
+
+  number Int
+  status AgentVersionStatus @default(DRAFT)
+
+  instructions  String
+  manifest      Json
+  modelId       String
+  sandboxPolicy Json
+  validation    Json?
+
+  sourceConversationId String?
+  sourceConversation   AgentConversation? @relation("AgentVersionSourceConversation", fields: [sourceConversationId], references: [id], onDelete: SetNull)
+
+  createdById String
+  createdBy   User   @relation("AgentVersionCreator", fields: [createdById], references: [id], onDelete: Restrict)
+
+  deploymentId String?
+  approvedAt   DateTime?
+  deployedAt   DateTime?
+  createdAt    DateTime  @default(now())
+
+  currentFor  AgentDefinition?  @relation("CurrentAgentVersion")
+  triggers    AgentTrigger[]
+  runs        AgentRun[]
+  auditEvents AgentAuditEvent[]
+
+  @@unique([agentId, number])
+  @@index([agentId, createdAt])
+  @@index([status, createdAt])
+  @@map("agentVersion")
+}
+
+model AgentTrigger {
+  id String @id @default(cuid())
+
+  agentId String
+  agent   AgentDefinition @relation(fields: [agentId], references: [id], onDelete: Restrict)
+
+  versionId String
+  version   AgentVersion @relation(fields: [versionId], references: [id], onDelete: Restrict)
+
+  type   AgentTriggerType
+  name   String
+  config Json
+
+  createdById String
+  createdBy   User   @relation("AgentTriggerCreator", fields: [createdById], references: [id], onDelete: Restrict)
+
+  enabled   Boolean   @default(false)
+  nextRunAt DateTime?
+  lastRunAt DateTime?
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+
+  runs AgentRun[]
+
+  @@index([agentId, enabled])
+  @@index([enabled, nextRunAt])
+  @@index([versionId])
+  @@map("agentTrigger")
+}
+
+model AgentRun {
+  id String @id @default(cuid())
+
+  agentId String
+  agent   AgentDefinition @relation(fields: [agentId], references: [id], onDelete: Restrict)
+
+  versionId String
+  version   AgentVersion @relation(fields: [versionId], references: [id], onDelete: Restrict)
+
+  triggerId String?
+  trigger   AgentTrigger? @relation(fields: [triggerId], references: [id], onDelete: Restrict)
+
+  initiatedById String?
+  initiatedBy   User?   @relation("AgentRunInitiator", fields: [initiatedById], references: [id], onDelete: SetNull)
+
+  triggerType    AgentTriggerType
+  status         AgentRunStatus   @default(QUEUED)
+  principalId    String?
+  sessionId      String?          @unique
+  idempotencyKey String           @unique
+  correlationId  String           @unique
+
+  input   Json?
+  result  Json?
+  summary String?
+
+  modelId      String?
+  inputTokens  Int?
+  outputTokens Int?
+  costUsd      Decimal? @db.Decimal(12, 6)
+
+  errorCode    String?
+  errorMessage String?
+
+  nextEventSequence Int @default(0)
+
+  createdAt  DateTime  @default(now())
+  startedAt  DateTime?
+  finishedAt DateTime?
+
+  events  AgentRunEvent[]
+  actions AgentAction[]
+
+  @@index([agentId, createdAt])
+  @@index([versionId, createdAt])
+  @@index([status, createdAt])
+  @@index([triggerId, createdAt])
+  @@map("agentRun")
+}
+
+model AgentRunEvent {
+  id String @id @default(cuid())
+
+  runId String
+  run   AgentRun @relation(fields: [runId], references: [id], onDelete: Restrict)
+
+  sequence  Int
+  type      String
+  data      Json
+  emittedAt DateTime @default(now())
+
+  @@unique([runId, sequence])
+  @@index([runId, emittedAt])
+  @@map("agentRunEvent")
+}
+
+model AgentAction {
+  id String @id @default(cuid())
+
+  agentId String
+  agent   AgentDefinition @relation(fields: [agentId], references: [id], onDelete: Restrict)
+
+  runId String
+  run   AgentRun @relation(fields: [runId], references: [id], onDelete: Restrict)
+
+  type        String
+  provider    String
+  targetType  String?
+  targetId    String?
+  targetLabel String?
+  summary     String
+  metadata    Json?
+
+  status         AgentActionStatus @default(PLANNED)
+  idempotencyKey String            @unique
+  requestHash    String?
+  externalId     String?
+  attemptCount   Int               @default(0)
+
+  errorCode    String?
+  errorMessage String?
+
+  plannedAt   DateTime  @default(now())
+  startedAt   DateTime?
+  completedAt DateTime?
+  updatedAt   DateTime  @updatedAt
+
+  @@index([agentId, plannedAt])
+  @@index([runId, plannedAt])
+  @@index([provider, externalId])
+  @@index([status, plannedAt])
+  @@map("agentAction")
+}
+
+model AgentAuditEvent {
+  id String @id @default(cuid())
+
+  agentId String
+  agent   AgentDefinition @relation(fields: [agentId], references: [id], onDelete: Restrict)
+
+  versionId String?
+  version   AgentVersion? @relation(fields: [versionId], references: [id], onDelete: Restrict)
+
+  actorUserId String?
+  actorUser   User?   @relation("AgentAuditActor", fields: [actorUserId], references: [id], onDelete: SetNull)
+
+  type      String
+  actorType String
+  actorId   String?
+  summary   String
+  before    Json?
+  after     Json?
+  requestId String?
+  emittedAt DateTime @default(now())
+
+  @@unique([agentId, type, requestId])
+  @@index([agentId, emittedAt])
+  @@index([versionId, emittedAt])
+  @@index([actorUserId, emittedAt])
+  @@index([type, emittedAt])
+  @@map("agentAuditEvent")
+}
+
 model Deal {
   id            String              @id @default(cuid())
   conversations AgentConversation[]
diff --git a/packages/ui/src/components/bubble.tsx b/packages/ui/src/components/bubble.tsx
index 95d03dc9..a177e0e9 100644
--- a/packages/ui/src/components/bubble.tsx
+++ b/packages/ui/src/components/bubble.tsx
@@ -15,7 +15,7 @@ function BubbleGroup({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 const bubbleVariants = cva(
-  "group/bubble relative flex w-fit max-w-[80%] min-w-0 flex-col gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[variant=ghost]:max-w-full",
+  "group/bubble relative flex w-fit max-w-full min-w-0 flex-col gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[variant=ghost]:max-w-full sm:max-w-[80%]",
   {
     variants: {
       variant: {

From 46960a8aecdfa87e7ff2ac1b253c208dd45fac0c Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 14:41:18 -0700
Subject: [PATCH 3/7] CMP-1 feat: refine agent builder interactions

---
 THIRD_PARTY_NOTICES.md                        |  13 +
 apps/agent/package.json                       |   4 +-
 apps/agent/turbo.json                         |   1 +
 .../src/agent/agent-definitions.service.ts    |  93 ++++++-
 apps/api/src/agent/agent-runs.service.ts      |  31 ++-
 apps/api/test/agent-delete.spec.ts            | 240 ++++++++++++++++++
 .../agent-builder/agent-builder-chat.tsx      | 177 ++++++++-----
 .../agent-builder/agent-composer.tsx          |  67 +++--
 .../agent-builder/share-chat-dialog.tsx       |  54 +++-
 .../agent-builder/team-agent-detail.tsx       | 215 ++++++++++++++--
 bun.lock                                      |   9 +
 docs/agent.md                                 |  45 ++--
 packages/ui/package.json                      |   1 +
 packages/ui/src/components/async-action.tsx   | 199 +++++++++++++++
 packages/ui/src/components/button.tsx         |   2 +-
 packages/ui/src/components/progress.tsx       |  97 +++++++
 packages/ui/src/components/skeleton-swap.tsx  | 132 ++++++++++
 packages/ui/src/components/task-steps.tsx     | 144 +++++++++++
 18 files changed, 1366 insertions(+), 158 deletions(-)
 create mode 100644 THIRD_PARTY_NOTICES.md
 create mode 100644 apps/api/test/agent-delete.spec.ts
 create mode 100644 packages/ui/src/components/async-action.tsx
 create mode 100644 packages/ui/src/components/progress.tsx
 create mode 100644 packages/ui/src/components/skeleton-swap.tsx
 create mode 100644 packages/ui/src/components/task-steps.tsx

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
new file mode 100644
index 00000000..b07cc758
--- /dev/null
+++ b/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,13 @@
+# Third-party notices
+
+## Interior
+
+The async interaction primitives in `packages/ui` are derived from behavioral patterns in [Interior](https://github.com/ddoemonn/interior).
+
+Copyright (c) 2026 ozzy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/apps/agent/package.json b/apps/agent/package.json
index ab68a8a5..8bde0a7d 100644
--- a/apps/agent/package.json
+++ b/apps/agent/package.json
@@ -6,8 +6,8 @@
 	"license": "MIT",
 	"scripts": {
 		"backfill:images": "bun scripts/backfill-brand-images.ts",
-		"dev": "eve dev --no-ui",
-		"dev:tui": "eve dev",
+		"dev": "eve dev",
+		"dev:headless": "eve dev --no-ui",
 		"dispatch": "curl -fsS -X POST \"${AGENT_URL:-http://127.0.0.1:2000}/eve/v1/dev/schedules/dispatch\"",
 		"build": "eve build",
 		"start": "eve start",
diff --git a/apps/agent/turbo.json b/apps/agent/turbo.json
index 25049716..14b772d1 100644
--- a/apps/agent/turbo.json
+++ b/apps/agent/turbo.json
@@ -11,6 +11,7 @@
 		},
 		"dev": {
 			"cache": false,
+			"interactive": true,
 			"persistent": true,
 			"passThroughEnv": [
 				"AGENT_BRIDGE_SECRET",
diff --git a/apps/api/src/agent/agent-definitions.service.ts b/apps/api/src/agent/agent-definitions.service.ts
index daecd6d6..6611e5ec 100644
--- a/apps/api/src/agent/agent-definitions.service.ts
+++ b/apps/api/src/agent/agent-definitions.service.ts
@@ -298,14 +298,91 @@ export class AgentDefinitionsService {
 	}
 
 	async remove(id: string, userId: string) {
-		return this.changeStatus(
-			id,
-			userId,
-			"DELETED",
-			"agent.deleted",
-			"Deleted agent",
-			{ deletedAt: new Date() },
-		);
+		await this.access.assertCanManage(id, userId);
+		const now = new Date();
+
+		return this.db.$transaction(async (tx) => {
+			const [current] = await tx.$queryRaw<
+				Array<{ id: string; status: string }>
+			>`
+				SELECT id, status
+				FROM "agentDefinition"
+				WHERE id = ${id}
+				FOR UPDATE
+			`;
+
+			if (!current || current.status === "DELETED") {
+				throw new NotFoundException(`No agent with id ${id}.`);
+			}
+
+			const disabledTriggers = await tx.agentTrigger.updateMany({
+				where: { agentId: id, enabled: true },
+				data: { enabled: false, nextRunAt: null },
+			});
+
+			const cancellableRuns = await tx.$queryRaw<Array<{ id: string }>>`
+				SELECT id
+				FROM "agentRun"
+				WHERE "agentId" = ${id}
+					AND status IN ('QUEUED', 'WAITING_FOR_APPROVAL')
+				ORDER BY id
+				FOR UPDATE
+			`;
+
+			for (const run of cancellableRuns) {
+				const cancelled = await tx.agentRun.update({
+					where: { id: run.id },
+					data: {
+						status: "CANCELLED",
+						finishedAt: now,
+						errorCode: "AGENT_DELETED",
+						errorMessage: "The agent was deleted before this run completed.",
+						nextEventSequence: { increment: 1 },
+					},
+					select: { nextEventSequence: true },
+				});
+
+				await tx.agentRunEvent.create({
+					data: {
+						runId: run.id,
+						sequence: cancelled.nextEventSequence,
+						type: "run.cancelled",
+						data: { reason: "agent.deleted" },
+						emittedAt: now,
+					},
+				});
+			}
+
+			const agent = await tx.agentDefinition.update({
+				where: { id },
+				data: { status: "DELETED", deletedAt: now },
+				select: { id: true, name: true, status: true, updatedAt: true },
+			});
+
+			await tx.agentAuditEvent.create({
+				data: {
+					agentId: id,
+					actorUserId: userId,
+					actorType: "USER",
+					actorId: userId,
+					type: "agent.deleted",
+					summary: "Deleted agent",
+					before: { status: current.status },
+					after: {
+						status: "DELETED",
+						disabledTriggers: disabledTriggers.count,
+						cancelledRuns: cancellableRuns.length,
+					},
+				},
+			});
+
+			return {
+				...agent,
+				updatedAt: agent.updatedAt.toISOString(),
+				disabledTriggers: disabledTriggers.count,
+				cancelledRuns: cancellableRuns.length,
+			};
+		});
 	}
 
 	private async changeStatus(
diff --git a/apps/api/src/agent/agent-runs.service.ts b/apps/api/src/agent/agent-runs.service.ts
index 4fcaf3b3..24f6d2ef 100644
--- a/apps/api/src/agent/agent-runs.service.ts
+++ b/apps/api/src/agent/agent-runs.service.ts
@@ -137,17 +137,34 @@ export class AgentRunsService {
 			return { id: existing.id };
 		}
 
-		const agent = await this.readableAgent(input.id, userId);
-		if (agent.status !== "LIVE" || !agent.currentVersionId) {
-			throw new BadRequestException("This agent is not live yet.");
-		}
-		const versionId = agent.currentVersionId;
+		await this.access.assertMember(userId);
 
 		const run = await this.db.$transaction(async (tx) => {
+			const [agent] = await tx.$queryRaw<
+				Array<{
+					id: string;
+					status: string;
+					currentVersionId: string | null;
+				}>
+			>`
+				SELECT id, status, "currentVersionId"
+				FROM "agentDefinition"
+				WHERE id = ${input.id}
+				FOR UPDATE
+			`;
+
+			if (!agent || agent.status === "DELETED") {
+				throw new NotFoundException(`No agent with id ${input.id}.`);
+			}
+
+			if (agent.status !== "LIVE" || !agent.currentVersionId) {
+				throw new BadRequestException("This agent is not live yet.");
+			}
+
 			const created = await tx.agentRun.create({
 				data: {
 					agentId: input.id,
-					versionId,
+					versionId: agent.currentVersionId,
 					initiatedById: userId,
 					triggerType: "MANUAL",
 					idempotencyKey: input.clientRequestId,
@@ -162,7 +179,7 @@ export class AgentRunsService {
 			await tx.agentAuditEvent.create({
 				data: {
 					agentId: input.id,
-					versionId,
+					versionId: agent.currentVersionId,
 					actorUserId: userId,
 					actorType: "USER",
 					actorId: userId,
diff --git a/apps/api/test/agent-delete.spec.ts b/apps/api/test/agent-delete.spec.ts
new file mode 100644
index 00000000..d9ef43f9
--- /dev/null
+++ b/apps/api/test/agent-delete.spec.ts
@@ -0,0 +1,240 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import {
+	DEFAULT_WORKSPACE_NAME,
+	WORKSPACE_ID,
+	WORKSPACE_SLUG,
+} from "@crm/auth";
+import { db } from "@crm/db";
+import { AgentAccessService } from "../src/agent/agent-access.service";
+import { AgentDefinitionsService } from "../src/agent/agent-definitions.service";
+
+const suffix = crypto.randomUUID();
+const userId = `agent-delete-user-${suffix}`;
+const memberId = `agent-delete-member-${suffix}`;
+const idempotencyPrefix = `agent-delete-${suffix}`;
+
+const access = new AgentAccessService(db);
+const agents = new AgentDefinitionsService(db, access);
+
+let agentId: string;
+let versionId: string;
+let triggerId: string;
+let queuedRunId: string;
+let waitingRunId: string;
+let runningRunId: string;
+
+async function clean() {
+	if (agentId) {
+		await db.agentRunEvent.deleteMany({ where: { run: { agentId } } });
+		await db.agentAction.deleteMany({ where: { agentId } });
+		await db.agentAuditEvent.deleteMany({ where: { agentId } });
+		await db.agentRun.deleteMany({ where: { agentId } });
+		await db.agentTrigger.deleteMany({ where: { agentId } });
+		await db.agentDefinition.updateMany({
+			where: { id: agentId },
+			data: { currentVersionId: null },
+		});
+		await db.agentVersion.deleteMany({ where: { agentId } });
+		await db.agentDefinition.deleteMany({ where: { id: agentId } });
+	}
+
+	await db.member.deleteMany({ where: { id: memberId } });
+	await db.user.deleteMany({ where: { id: userId } });
+}
+
+beforeAll(async () => {
+	await db.organization.upsert({
+		where: { id: WORKSPACE_ID },
+		update: {},
+		create: {
+			id: WORKSPACE_ID,
+			name: DEFAULT_WORKSPACE_NAME,
+			slug: WORKSPACE_SLUG,
+			createdAt: new Date(),
+		},
+	});
+	await db.user.create({
+		data: {
+			id: userId,
+			name: "Agent Delete Test",
+			email: `${userId}@example.test`,
+		},
+	});
+	await db.member.create({
+		data: {
+			id: memberId,
+			organizationId: WORKSPACE_ID,
+			userId,
+			role: "member",
+			createdAt: new Date(),
+		},
+	});
+
+	const agent = await db.agentDefinition.create({
+		data: {
+			name: "Delete me",
+			status: "PAUSED",
+			createdById: userId,
+		},
+		select: { id: true },
+	});
+	agentId = agent.id;
+
+	const version = await db.agentVersion.create({
+		data: {
+			agentId,
+			number: 1,
+			status: "DEPLOYED",
+			instructions: "Test deletion behavior.",
+			manifest: {},
+			modelId: "test/model",
+			sandboxPolicy: {},
+			createdById: userId,
+			approvedAt: new Date(),
+			deployedAt: new Date(),
+		},
+		select: { id: true },
+	});
+	versionId = version.id;
+	await db.agentDefinition.update({
+		where: { id: agentId },
+		data: { currentVersionId: versionId },
+	});
+
+	const trigger = await db.agentTrigger.create({
+		data: {
+			agentId,
+			versionId,
+			type: "SCHEDULE",
+			name: "Every hour",
+			config: { intervalMinutes: 60 },
+			createdById: userId,
+			enabled: true,
+			nextRunAt: new Date(Date.now() + 60 * 60 * 1000),
+		},
+		select: { id: true },
+	});
+	triggerId = trigger.id;
+
+	const [queued, waiting, running] = await Promise.all([
+		db.agentRun.create({
+			data: {
+				agentId,
+				versionId,
+				triggerId,
+				triggerType: "SCHEDULE",
+				status: "QUEUED",
+				idempotencyKey: `${idempotencyPrefix}-queued`,
+				correlationId: `${idempotencyPrefix}-queued`,
+			},
+			select: { id: true },
+		}),
+		db.agentRun.create({
+			data: {
+				agentId,
+				versionId,
+				triggerType: "MANUAL",
+				status: "WAITING_FOR_APPROVAL",
+				idempotencyKey: `${idempotencyPrefix}-waiting`,
+				correlationId: `${idempotencyPrefix}-waiting`,
+			},
+			select: { id: true },
+		}),
+		db.agentRun.create({
+			data: {
+				agentId,
+				versionId,
+				triggerType: "MANUAL",
+				status: "RUNNING",
+				idempotencyKey: `${idempotencyPrefix}-running`,
+				correlationId: `${idempotencyPrefix}-running`,
+				startedAt: new Date(),
+			},
+			select: { id: true },
+		}),
+	]);
+	queuedRunId = queued.id;
+	waitingRunId = waiting.id;
+	runningRunId = running.id;
+});
+
+afterAll(async () => {
+	await clean();
+	await db.$disconnect();
+});
+
+describe("deleting an agent", () => {
+	it("stops future work while preserving its audit history", async () => {
+		const removed = await agents.remove(agentId, userId);
+
+		expect(removed.status).toBe("DELETED");
+		expect(removed.disabledTriggers).toBe(1);
+		expect(removed.cancelledRuns).toBe(2);
+
+		const [definition, trigger, runs, runEvents, auditEvent, listed] =
+			await Promise.all([
+				db.agentDefinition.findUnique({ where: { id: agentId } }),
+				db.agentTrigger.findUnique({ where: { id: triggerId } }),
+				db.agentRun.findMany({
+					where: { id: { in: [queuedRunId, waitingRunId, runningRunId] } },
+					select: {
+						id: true,
+						status: true,
+						errorCode: true,
+						finishedAt: true,
+					},
+				}),
+				db.agentRunEvent.findMany({
+					where: { runId: { in: [queuedRunId, waitingRunId] } },
+					select: { runId: true, type: true, data: true },
+				}),
+				db.agentAuditEvent.findFirst({
+					where: { agentId, type: "agent.deleted" },
+				}),
+				agents.list(userId),
+			]);
+
+		expect(definition?.deletedAt).not.toBeNull();
+		expect(trigger).toMatchObject({ enabled: false, nextRunAt: null });
+		expect(
+			runs.filter((run) => [queuedRunId, waitingRunId].includes(run.id)),
+		).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					status: "CANCELLED",
+					errorCode: "AGENT_DELETED",
+					finishedAt: expect.any(Date),
+				}),
+				expect.objectContaining({
+					status: "CANCELLED",
+					errorCode: "AGENT_DELETED",
+					finishedAt: expect.any(Date),
+				}),
+			]),
+		);
+		expect(runs.find((run) => run.id === runningRunId)?.status).toBe("RUNNING");
+		expect(runEvents).toHaveLength(2);
+		expect(runEvents).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					type: "run.cancelled",
+					data: { reason: "agent.deleted" },
+				}),
+			]),
+		);
+		expect(auditEvent?.after).toEqual({
+			status: "DELETED",
+			disabledTriggers: 1,
+			cancelledRuns: 2,
+		});
+		expect(listed.some((agent) => agent.id === agentId)).toBe(false);
+
+		let lookupError: unknown;
+		try {
+			await agents.byId(agentId, userId);
+		} catch (error) {
+			lookupError = error;
+		}
+		expect((lookupError as Error).message).toBe(`No agent with id ${agentId}.`);
+	});
+});
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
index bb6b4f8d..aff75970 100644
--- a/apps/app/components/agent-builder/agent-builder-chat.tsx
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -10,9 +10,15 @@ import Renew from "@carbon/icons-react/es/Renew";
 import ThumbsDown from "@carbon/icons-react/es/ThumbsDown";
 import ThumbsUp from "@carbon/icons-react/es/ThumbsUp";
 import WarningAlt from "@carbon/icons-react/es/WarningAlt";
+import {
+	AsyncButtonContent,
+	useAsyncAction,
+} from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
 import { Icon } from "@crm/ui/components/icon";
 import { Markdown } from "@crm/ui/components/markdown";
+import { Skeleton } from "@crm/ui/components/skeleton";
+import { TaskSteps } from "@crm/ui/components/task-steps";
 import { cn } from "@crm/ui/lib/utils";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { MessageStreamEvent } from "eve/client";
@@ -528,17 +534,44 @@ function BuildingAgentCard({
 	sessionId: string | null;
 	eventCount: number;
 }) {
-	const [stopping, setStopping] = useState(false);
 	const completed = Math.min(
 		3,
 		sessionId ? Math.max(1, Math.floor(eventCount / 4)) : 0,
 	);
 	const steps = [
-		["Read the CRM data model", "Companies · contacts · deals"],
-		["Resolved the requested records", "Scoped to this workspace"],
-		["Checked connected integrations", "Only available connections"],
-		["Preparing the agent", "Isolated Vercel Sandbox"],
+		{
+			id: "data-model",
+			label: "Read the CRM data model",
+			meta: "Companies · contacts · deals",
+		},
+		{
+			id: "records",
+			label: "Resolved the requested records",
+			meta: "Scoped to this workspace",
+		},
+		{
+			id: "integrations",
+			label: "Checked connected integrations",
+			meta: "Only available connections",
+		},
+		{
+			id: "sandbox",
+			label: "Preparing the agent",
+			meta: "Isolated Vercel Sandbox",
+		},
 	] as const;
+	const stop = useAsyncAction({
+		action: async () => {
+			if (!sessionId) return;
+			const response = await fetch(`/eve/v1/session/${sessionId}/cancel`, {
+				method: "POST",
+				headers: { "x-crm-builder-conversation": conversationId },
+			});
+			if (!response.ok) throw new Error(await response.text());
+		},
+		onSuccess: () => toast.success("Stop requested."),
+		onError: () => toast.error("The agent could not be stopped. Try again."),
+	});
 
 	return (
 		<div className="flex flex-col gap-4">
@@ -562,53 +595,25 @@ function BuildingAgentCard({
 					<Button
 						variant="outline"
 						size="sm"
-						disabled={!sessionId || stopping}
-						onClick={() => {
-							if (!sessionId) return;
-							setStopping(true);
-							void fetch(`/eve/v1/session/${sessionId}/cancel`, {
-								method: "POST",
-								headers: { "x-crm-builder-conversation": conversationId },
-							})
-								.then(async (response) => {
-									if (!response.ok) {
-										throw new Error(await response.text());
-									}
-									toast.success("Stop requested.");
-								})
-								.catch(() => {
-									setStopping(false);
-									toast.error("The agent could not be stopped. Try again.");
-								});
-						}}
+						disabled={!sessionId || stop.pending}
+						aria-busy={stop.pending}
+						onClick={() => stop.run()}
 					>
-						{stopping ? "Stopping" : "Stop"}
+						<AsyncButtonContent
+							status={stop.status}
+							pendingLabel="Stopping"
+							successLabel="Stopping"
+							errorLabel="Try again"
+						>
+							Stop
+						</AsyncButtonContent>
 					</Button>
 				</div>
-				{steps.map(([label, detail], index) => (
-					<div
-						key={label}
-						className="flex min-h-10 items-start gap-3 border-t px-4 py-2.5 first:border-t-0 sm:h-8 sm:min-h-0 sm:items-center sm:gap-4 sm:px-5 sm:py-0"
-					>
-						<span className="flex size-5 shrink-0 items-center justify-center">
-							{index < completed ? (
-								<Icon icon={Checkmark} className="size-3.5 text-ring" />
-							) : index === completed ? (
-								<Icon
-									icon={Renew}
-									className="size-3.5 animate-spin text-muted-foreground"
-									motion="none"
-								/>
-							) : null}
-						</span>
-						<span className="min-w-0 flex-1 wrap-break-word text-sm">
-							{label}
-						</span>
-						<span className="min-w-0 max-w-[45%] text-right text-muted-foreground text-xs sm:w-60 sm:max-w-none sm:shrink-0">
-							{detail}
-						</span>
-					</div>
-				))}
+				<TaskSteps
+					steps={[...steps]}
+					current={completed}
+					label="Agent creation"
+				/>
 				<p className="border-t px-4 py-3 text-muted-foreground text-xs sm:px-5">
 					This chat keeps running if you leave. You’ll see a dot in the sidebar
 					when there’s a response.
@@ -659,9 +664,15 @@ function BuilderFailureCard({
 					variant="outline"
 					size="sm"
 					disabled={retrying}
+					aria-busy={retrying}
 					onClick={onRetry}
 				>
-					Try again
+					<AsyncButtonContent
+						status={retrying ? "pending" : "idle"}
+						pendingLabel="Retrying"
+					>
+						Try again
+					</AsyncButtonContent>
 				</Button>
 			) : null}
 		</div>
@@ -736,6 +747,7 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 						</Button>
 						<Button
 							disabled={deploy.isPending}
+							aria-busy={deploy.isPending}
 							onClick={() =>
 								deploy.mutate({
 									id: agent.id,
@@ -744,7 +756,22 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 								})
 							}
 						>
-							{deploy.isPending ? "Creating…" : "Create agent"}
+							<AsyncButtonContent
+								status={
+									deploy.isPending
+										? "pending"
+										: deploy.isError
+											? "error"
+											: deploy.isSuccess
+												? "success"
+												: "idle"
+								}
+								pendingLabel="Creating"
+								successLabel="Created"
+								errorLabel="Try again"
+							>
+								Create agent
+							</AsyncButtonContent>
 						</Button>
 					</div>
 				</div>
@@ -787,6 +814,13 @@ function DeployedAgentCard({
 			onError: (error) => toast.error(error.message),
 		}),
 	);
+	const runAction = useAsyncAction({
+		action: () =>
+			run.mutateAsync({
+				id: agent?.id ?? "",
+				clientRequestId: crypto.randomUUID(),
+			}),
+	});
 
 	if (!agent) return null;
 	const nextRun = agent.triggers.find((trigger) => trigger.enabled)?.nextRunAt;
@@ -833,13 +867,19 @@ function DeployedAgentCard({
 					<Button
 						variant="outline"
 						size="sm"
-						disabled={run.isPending}
-						onClick={() =>
-							run.mutate({ id: agent.id, clientRequestId: crypto.randomUUID() })
-						}
+						disabled={runAction.pending}
+						aria-busy={runAction.pending}
+						onClick={() => runAction.run()}
 					>
-						<Icon icon={Play} data-icon="inline-start" />
-						Run now
+						<AsyncButtonContent
+							status={runAction.status}
+							pendingLabel="Queueing"
+							successLabel="Queued"
+							errorLabel="Try again"
+						>
+							<Icon icon={Play} data-icon="inline-start" />
+							Run now
+						</AsyncButtonContent>
 					</Button>
 				</div>
 			</div>
@@ -897,12 +937,23 @@ function DeployedStat({
 
 function ChatLoading() {
 	return (
-		<main className="flex flex-1 items-center justify-center">
-			<Icon
-				icon={Renew}
-				className="size-4 animate-spin text-muted-foreground"
-				motion="none"
-			/>
+		<main className="flex min-h-0 flex-1 flex-col" aria-busy="true">
+			<header className="flex h-12 shrink-0 items-center border-b px-5">
+				<Skeleton className="h-4 w-40" />
+			</header>
+			<div className="min-h-0 flex-1 overflow-hidden">
+				<div className="mx-auto flex w-full max-w-3xl flex-col gap-5 px-4 py-6 sm:px-5 sm:py-9">
+					<Skeleton className="ml-auto h-16 w-2/3 max-w-[520px]" />
+					<div className="flex max-w-[640px] flex-col gap-2">
+						<Skeleton className="h-4 w-full" />
+						<Skeleton className="h-4 w-11/12" />
+						<Skeleton className="h-4 w-8/12" />
+					</div>
+				</div>
+			</div>
+			<span role="status" className="sr-only">
+				Loading chat
+			</span>
 		</main>
 	);
 }
diff --git a/apps/app/components/agent-builder/agent-composer.tsx b/apps/app/components/agent-builder/agent-composer.tsx
index 74c70bc5..6b2ce01a 100644
--- a/apps/app/components/agent-builder/agent-composer.tsx
+++ b/apps/app/components/agent-builder/agent-composer.tsx
@@ -12,6 +12,7 @@ import Email from "@carbon/icons-react/es/Email";
 import Partnership from "@carbon/icons-react/es/Partnership";
 import Search from "@carbon/icons-react/es/Search";
 import User from "@carbon/icons-react/es/User";
+import { AsyncButtonContent } from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
 import { type CarbonIcon, Icon } from "@crm/ui/components/icon";
 import { Input } from "@crm/ui/components/input";
@@ -20,6 +21,8 @@ import {
 	PopoverContent,
 	PopoverTrigger,
 } from "@crm/ui/components/popover";
+import { Skeleton } from "@crm/ui/components/skeleton";
+import { SkeletonSwap } from "@crm/ui/components/skeleton-swap";
 import { cn } from "@crm/ui/lib/utils";
 import { useQuery } from "@tanstack/react-query";
 import { useRef, useState } from "react";
@@ -215,22 +218,28 @@ export function AgentComposer({
 										}
 									/>
 								))}
-								{(resourceResults.data ?? []).map((resource) => (
-									<ResourceButton
-										key={`${resource.kind}:${resource.id}`}
-										icon={RESOURCE_ICONS[resource.kind]}
-										label={resource.label}
-										detail={resource.detail ?? RESOURCE_LABELS[resource.kind]}
-										onSelect={() => addResource(resource)}
-									/>
-								))}
-								{resourceResults.isSuccess &&
-								connectedGoogle.length === 0 &&
-								resourceResults.data.length === 0 ? (
-									<p className="px-3 py-5 text-center text-muted-foreground text-xs">
-										No matching records.
-									</p>
-								) : null}
+								<SkeletonSwap
+									loading={resourceResults.isFetching}
+									label="CRM records"
+									skeleton={<ResourceResultsSkeleton />}
+								>
+									{(resourceResults.data ?? []).map((resource) => (
+										<ResourceButton
+											key={`${resource.kind}:${resource.id}`}
+											icon={RESOURCE_ICONS[resource.kind]}
+											label={resource.label}
+											detail={resource.detail ?? RESOURCE_LABELS[resource.kind]}
+											onSelect={() => addResource(resource)}
+										/>
+									))}
+									{resourceResults.isSuccess &&
+									connectedGoogle.length === 0 &&
+									resourceResults.data.length === 0 ? (
+										<p className="px-3 py-5 text-center text-muted-foreground text-xs">
+											No matching records.
+										</p>
+									) : null}
+								</SkeletonSwap>
 							</div>
 						</PopoverContent>
 					</Popover>
@@ -303,17 +312,41 @@ export function AgentComposer({
 					variant="default"
 					size="icon-sm"
 					disabled={!canSend}
+					aria-busy={pending}
 					aria-label="Send message"
 					onClick={submit}
 					className="rounded-full"
 				>
-					<Icon icon={ArrowUp} />
+					<AsyncButtonContent
+						status={pending ? "pending" : "idle"}
+						pendingLabel={<span className="sr-only">Sending</span>}
+						successLabel={<span className="sr-only">Sent</span>}
+						errorLabel={<span className="sr-only">Send failed</span>}
+					>
+						<Icon icon={ArrowUp} />
+					</AsyncButtonContent>
 				</Button>
 			</div>
 		</div>
 	);
 }
 
+function ResourceResultsSkeleton() {
+	return (
+		<div className="flex flex-col gap-1 px-3 py-2">
+			{["first", "second", "third"].map((item) => (
+				<div key={item} className="flex h-10 items-center gap-3">
+					<Skeleton className="size-6 shrink-0" />
+					<div className="flex min-w-0 flex-1 flex-col gap-1.5">
+						<Skeleton className="h-3 w-2/3" />
+						<Skeleton className="h-2.5 w-1/3" />
+					</div>
+				</div>
+			))}
+		</div>
+	);
+}
+
 const RESOURCE_ICONS: Record<BuilderResource["kind"], CarbonIcon> = {
 	integration: Application,
 	company: Building,
diff --git a/apps/app/components/agent-builder/share-chat-dialog.tsx b/apps/app/components/agent-builder/share-chat-dialog.tsx
index 24c74b33..0e36dc05 100644
--- a/apps/app/components/agent-builder/share-chat-dialog.tsx
+++ b/apps/app/components/agent-builder/share-chat-dialog.tsx
@@ -2,6 +2,10 @@
 
 import Close from "@carbon/icons-react/es/Close";
 import Copy from "@carbon/icons-react/es/Copy";
+import {
+	AsyncButtonContent,
+	useAsyncAction,
+} from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
 import {
 	Dialog,
@@ -72,6 +76,14 @@ export function ShareChatDialog({
 		);
 		toast.success("Chat link copied.");
 	};
+	const createAction = useAsyncAction({
+		action: () => create.mutateAsync({ id: conversationId }),
+		onError: () => setChoice(null),
+	});
+	const revokeAction = useAsyncAction({
+		action: () => revoke.mutateAsync({ id: conversationId }),
+	});
+	const copyAction = useAsyncAction({ action: copyLink });
 
 	return (
 		<Dialog
@@ -111,9 +123,10 @@ export function ShareChatDialog({
 					<ShareChoice
 						selected={!shared}
 						label="Only you"
+						disabled={createAction.pending || revokeAction.pending}
 						onSelect={() => {
 							if (shared || status.data?.enabled) {
-								revoke.mutate({ id: conversationId });
+								revokeAction.run();
 							} else {
 								setChoice(false);
 							}
@@ -123,8 +136,9 @@ export function ShareChatDialog({
 						selected={shared}
 						label="Anyone in Comp AI with the link"
 						detail="Read-only"
+						disabled={createAction.pending || revokeAction.pending}
 						onSelect={() => {
-							if (!token) create.mutate({ id: conversationId });
+							if (!token) createAction.run();
 							setChoice(true);
 						}}
 					/>
@@ -141,15 +155,23 @@ export function ShareChatDialog({
 								size="sm"
 								onClick={() => {
 									if (token) {
-										void copyLink();
+										copyAction.run();
 									} else {
-										create.mutate({ id: conversationId });
+										createAction.run();
 									}
 								}}
-								disabled={create.isPending}
+								disabled={createAction.pending || copyAction.pending}
+								aria-busy={createAction.pending || copyAction.pending}
 							>
-								{token ? <Icon icon={Copy} data-icon="inline-start" /> : null}
-								{token ? "Copy link" : "Replace link"}
+								<AsyncButtonContent
+									status={token ? copyAction.status : createAction.status}
+									pendingLabel={token ? "Copying" : "Creating link"}
+									successLabel={token ? "Copied" : "Link created"}
+									errorLabel="Try again"
+								>
+									{token ? <Icon icon={Copy} data-icon="inline-start" /> : null}
+									{token ? "Copy link" : "Replace link"}
+								</AsyncButtonContent>
 							</Button>
 						</div>
 					) : null}
@@ -162,10 +184,18 @@ export function ShareChatDialog({
 				<DialogFooter className="flex-row items-center justify-between border-t p-4 px-5">
 					<Button
 						variant="ghost"
-						onClick={() => revoke.mutate({ id: conversationId })}
-						disabled={!shared || revoke.isPending}
+						onClick={() => revokeAction.run()}
+						disabled={!shared || revokeAction.pending}
+						aria-busy={revokeAction.pending}
 					>
-						Revoke link
+						<AsyncButtonContent
+							status={revokeAction.status}
+							pendingLabel="Revoking"
+							successLabel="Revoked"
+							errorLabel="Try again"
+						>
+							Revoke link
+						</AsyncButtonContent>
 					</Button>
 					<div className="flex gap-3">
 						<DialogClose asChild>
@@ -185,11 +215,13 @@ function ShareChoice({
 	selected,
 	label,
 	detail,
+	disabled = false,
 	onSelect,
 }: {
 	selected: boolean;
 	label: string;
 	detail?: string;
+	disabled?: boolean;
 	onSelect: () => void;
 }) {
 	return (
@@ -197,12 +229,14 @@ function ShareChoice({
 			className={cn(
 				"flex h-12 w-full cursor-pointer items-center gap-2.5 rounded-md border px-2.5 text-left outline-none focus-within:ring-2 focus-within:ring-ring/60",
 				selected && "border-muted-foreground/60 bg-muted",
+				disabled && "cursor-not-allowed opacity-50",
 			)}
 		>
 			<input
 				type="radio"
 				name="chat-sharing"
 				checked={selected}
+				disabled={disabled}
 				onChange={onSelect}
 				className="sr-only"
 			/>
diff --git a/apps/app/components/agent-builder/team-agent-detail.tsx b/apps/app/components/agent-builder/team-agent-detail.tsx
index 1df7e2b2..bb3ec38c 100644
--- a/apps/app/components/agent-builder/team-agent-detail.tsx
+++ b/apps/app/components/agent-builder/team-agent-detail.tsx
@@ -3,13 +3,35 @@
 import ChevronDown from "@carbon/icons-react/es/ChevronDown";
 import ChevronUp from "@carbon/icons-react/es/ChevronUp";
 import Download from "@carbon/icons-react/es/Download";
+import OverflowMenuVertical from "@carbon/icons-react/es/OverflowMenuVertical";
 import Pause from "@carbon/icons-react/es/Pause";
 import Play from "@carbon/icons-react/es/Play";
-import Renew from "@carbon/icons-react/es/Renew";
+import TrashCan from "@carbon/icons-react/es/TrashCan";
+import {
+	AlertDialog,
+	AlertDialogCancel,
+	AlertDialogContent,
+	AlertDialogDescription,
+	AlertDialogFooter,
+	AlertDialogHeader,
+	AlertDialogTitle,
+} from "@crm/ui/components/alert-dialog";
+import {
+	AsyncButtonContent,
+	useAsyncAction,
+} from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from "@crm/ui/components/dropdown-menu";
 import { Icon } from "@crm/ui/components/icon";
+import { Skeleton } from "@crm/ui/components/skeleton";
 import { cn } from "@crm/ui/lib/utils";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useRouter } from "next/navigation";
 import { useState } from "react";
 import { toast } from "sonner";
 import { useTRPC } from "@/lib/trpc/client";
@@ -72,15 +94,38 @@ export function TeamAgentDetail({ agentId }: { agentId: string }) {
 			onError: (error) => toast.error(error.message),
 		}),
 	);
+	const runAction = useAsyncAction({
+		action: () =>
+			runNow.mutateAsync({
+				id: agentId,
+				clientRequestId: crypto.randomUUID(),
+			}),
+	});
+	const pauseAction = useAsyncAction({
+		action: () => pause.mutateAsync({ id: agentId }),
+	});
+	const resumeAction = useAsyncAction({
+		action: () => resume.mutateAsync({ id: agentId }),
+	});
 
 	if (agent.isPending) {
 		return (
-			<main className="flex flex-1 items-center justify-center">
-				<Icon
-					icon={Renew}
-					className="size-4 animate-spin text-muted-foreground"
-					motion="none"
-				/>
+			<main
+				className="min-h-0 min-w-0 flex-1 overflow-hidden px-4 py-6 sm:px-6 sm:py-10"
+				aria-busy="true"
+			>
+				<div className="mx-auto flex w-full max-w-[1040px] flex-col gap-6">
+					<div className="flex flex-col gap-3">
+						<Skeleton className="h-8 w-72 max-w-full" />
+						<Skeleton className="h-4 w-[520px] max-w-full" />
+						<Skeleton className="h-3 w-56 max-w-full" />
+					</div>
+					<Skeleton className="h-9 w-full" />
+					<Skeleton className="h-56 w-full" />
+				</div>
+				<span role="status" className="sr-only">
+					Loading agent
+				</span>
 			</main>
 		);
 	}
@@ -120,37 +165,59 @@ export function TeamAgentDetail({ agentId }: { agentId: string }) {
 						<div className="mt-1 flex flex-wrap gap-2">
 							<Button
 								variant="outline"
-								disabled={data.status !== "LIVE" || runNow.isPending}
-								onClick={() =>
-									runNow.mutate({
-										id: data.id,
-										clientRequestId: crypto.randomUUID(),
-									})
-								}
+								disabled={data.status !== "LIVE" || runAction.pending}
+								aria-busy={runAction.pending}
+								onClick={() => runAction.run()}
 							>
-								<Icon icon={Play} data-icon="inline-start" />
-								Run now
+								<AsyncButtonContent
+									status={runAction.status}
+									pendingLabel="Queueing"
+									successLabel="Queued"
+									errorLabel="Try again"
+								>
+									<Icon icon={Play} data-icon="inline-start" />
+									Run now
+								</AsyncButtonContent>
 							</Button>
 							{data.canManage && data.status === "LIVE" ? (
 								<Button
 									variant="outline"
-									disabled={pause.isPending}
-									onClick={() => pause.mutate({ id: data.id })}
+									disabled={pauseAction.pending}
+									aria-busy={pauseAction.pending}
+									onClick={() => pauseAction.run()}
 								>
-									<Icon icon={Pause} data-icon="inline-start" />
-									Pause
+									<AsyncButtonContent
+										status={pauseAction.status}
+										pendingLabel="Pausing"
+										successLabel="Paused"
+										errorLabel="Try again"
+									>
+										<Icon icon={Pause} data-icon="inline-start" />
+										Pause
+									</AsyncButtonContent>
 								</Button>
 							) : null}
 							{data.canManage && data.status === "PAUSED" ? (
 								<Button
 									variant="outline"
-									disabled={resume.isPending}
-									onClick={() => resume.mutate({ id: data.id })}
+									disabled={resumeAction.pending}
+									aria-busy={resumeAction.pending}
+									onClick={() => resumeAction.run()}
 								>
-									<Icon icon={Play} data-icon="inline-start" />
-									Resume
+									<AsyncButtonContent
+										status={resumeAction.status}
+										pendingLabel="Resuming"
+										successLabel="Resumed"
+										errorLabel="Try again"
+									>
+										<Icon icon={Play} data-icon="inline-start" />
+										Resume
+									</AsyncButtonContent>
 								</Button>
 							) : null}
+							{data.canManage ? (
+								<DeleteAgentAction agentId={data.id} name={data.name} />
+							) : null}
 						</div>
 					</div>
 				</div>
@@ -189,6 +256,106 @@ export function TeamAgentDetail({ agentId }: { agentId: string }) {
 	);
 }
 
+function DeleteAgentAction({
+	agentId,
+	name,
+}: {
+	agentId: string;
+	name: string;
+}) {
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const router = useRouter();
+	const [confirming, setConfirming] = useState(false);
+	const remove = useMutation(
+		trpc.agents.remove.mutationOptions({
+			onSuccess: async () => {
+				await Promise.all([
+					queryClient.invalidateQueries({
+						queryKey: trpc.agents.list.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.agents.byId.pathKey(),
+						refetchType: "none",
+					}),
+				]);
+				setConfirming(false);
+				toast.success(`${name} was deleted.`);
+				router.replace("/agents");
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
+	const removeAction = useAsyncAction({
+		action: () => remove.mutateAsync({ id: agentId }),
+	});
+
+	return (
+		<>
+			<DropdownMenu>
+				<DropdownMenuTrigger asChild>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						disabled={removeAction.pending}
+					>
+						<Icon icon={OverflowMenuVertical} />
+						<span className="sr-only">More agent actions</span>
+					</Button>
+				</DropdownMenuTrigger>
+				<DropdownMenuContent align="end">
+					<DropdownMenuItem
+						variant="destructive"
+						onSelect={() => setConfirming(true)}
+					>
+						<Icon icon={TrashCan} />
+						Delete agent
+					</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
+
+			<AlertDialog
+				open={confirming}
+				onOpenChange={(open) => {
+					if (!removeAction.pending) setConfirming(open);
+				}}
+			>
+				<AlertDialogContent>
+					<AlertDialogHeader>
+						<AlertDialogTitle>Delete {name}?</AlertDialogTitle>
+						<AlertDialogDescription>
+							This removes it from the team agent list, disables its triggers,
+							and cancels queued runs. Its run and action history stays in the
+							audit log. A run already in progress may finish.
+						</AlertDialogDescription>
+					</AlertDialogHeader>
+
+					<AlertDialogFooter>
+						<AlertDialogCancel disabled={removeAction.pending}>
+							Cancel
+						</AlertDialogCancel>
+						<Button
+							variant="destructive"
+							disabled={removeAction.pending}
+							aria-busy={removeAction.pending}
+							onClick={() => removeAction.run()}
+						>
+							<AsyncButtonContent
+								status={removeAction.status}
+								pendingLabel="Deleting"
+								successLabel="Deleted"
+								errorLabel="Try again"
+							>
+								Delete agent
+							</AsyncButtonContent>
+						</Button>
+					</AlertDialogFooter>
+				</AlertDialogContent>
+			</AlertDialog>
+		</>
+	);
+}
+
 function TabButton({
 	active,
 	onClick,
diff --git a/bun.lock b/bun.lock
index 9f7e1dcc..810b516e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -166,6 +166,7 @@
         "cmdk": "^1.1.1",
         "date-fns": "^4.4.0",
         "lucide-react": "^1.28.0",
+        "motion": "^12.42.2",
         "next-themes": "^0.4.6",
         "nuqs": "^2.8.9",
         "radix-ui": "^1.6.0",
@@ -1377,6 +1378,8 @@
 
     "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
 
+    "framer-motion": ["framer-motion@12.43.0", "", { "dependencies": { "motion-dom": "^12.43.0", "motion-utils": "^12.39.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-1eaL3RvR/kAlbG7UYcpMptEyzPoENO0c6w7ZnB3/hh2vSAz/6uGAFn6fdoqTBguNstf3MsFhJHsD/0DHiclG+g=="],
+
     "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
 
     "fs-constants": ["fs-constants@1.0.0", "", {}, "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow=="],
@@ -1759,6 +1762,12 @@
 
     "mkdirp-classic": ["mkdirp-classic@0.5.3", "", {}, "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A=="],
 
+    "motion": ["motion@12.43.0", "", { "dependencies": { "framer-motion": "^12.43.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-BQgQbSa9Hn3/mtbib0MK53y6JSANa+YKUKlaYnWzAVDH424RYQ5LVpV3pNiWH00BA2z4ojsSdMzqT7g2FQwjuQ=="],
+
+    "motion-dom": ["motion-dom@12.43.0", "", { "dependencies": { "motion-utils": "^12.39.0" } }, "sha512-azKON4d9S65PEoFUiQTMTgPheEmzf2QngdRc50AKfJp9Q9mmcBVw22c8eMq9k8kxOFHdL7+WZY7N/5F/lwiDag=="],
+
+    "motion-utils": ["motion-utils@12.39.0", "", {}, "sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ=="],
+
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
     "multer": ["multer@2.2.0", "", { "dependencies": { "append-field": "^1.0.0", "busboy": "^1.6.0", "concat-stream": "^2.0.0", "type-is": "^1.6.18" } }, "sha512-6rdyFg2kLrMh9Jee7/BMPuV9lEAd7lLW2YUpF9/YxR7njyoUwwQ0ZPh3TaIY50Sw6vlyD2HW3wGOkTS4P79xrQ=="],
diff --git a/docs/agent.md b/docs/agent.md
index 907e5132..a525b2d1 100644
--- a/docs/agent.md
+++ b/docs/agent.md
@@ -741,23 +741,17 @@ silently ignored.
 
 ## Watching it work
 
-`eve dev` shows every tool call, every result and every token — but only in its
-interactive TUI, and under `bun run dev` that TUI is unreadable. Turbo gives each
-task a pty, so eve believes it owns a terminal and paints a full-screen UI into a
-pane that turbo is also drawing; the two redraws interleave and what a rep of the
-agent's work actually looks like is `Building your agent compiling
-agent[agent] on  LinkedIn (RAPIDAPI_KEY)`. The prompt at the bottom is real and
-you cannot type at it usefully either.
-
-So **`dev` is `eve dev --no-ui`**, and `dev:tui` keeps the interactive one for
-when you run the agent on its own and want to talk to it. `--no-ui` changes
-nothing about the server — same port, same routes, same watcher — it only stops
-eve taking over the terminal, which is the whole of the problem.
-
-That leaves nothing narrating the session, and `hooks/activity.ts` is that
-narration: a line per tool call with its arguments, a line per result with how
-long it took, the finish reason and token spend of each step, and any failure
-with its code.
+`eve dev` shows every tool call, every result and every token in its interactive
+TUI, and it is the agent package's default `dev` command. The package's Turbo
+task is explicitly interactive, so select the agent pane and press Enter to hand
+stdin to eve. Type `/traces` to open the live trace viewer; Ctrl+Z returns input
+to Turbo.
+
+`dev:headless` keeps `eve dev --no-ui` available when a terminal cannot render
+the nested TUI. It starts the same server on the same port with the same routes
+and watcher. In that mode `hooks/activity.ts` narrates the session instead: a
+line per tool call with its arguments, a line per result with how long it took,
+the finish reason and token spend of each step, and any failure with its code.
 
 - **The lines go to stderr, not stdout.** The TUI's default log mode is `stderr`
   and it keeps stdout buffered and hidden, so a `console.log` here would be
@@ -782,17 +776,16 @@ with its code.
 record, so keep the turbo scrollback rather than going looking for a file that
 was never written.
 
-Two consequences of running headless, both worth recognising rather than
-debugging:
+Two consequences of opting into `dev:headless`, both worth recognising rather
+than debugging:
 
-- **A second `bun run dev` fails the whole turbo run.** An interactive `eve dev`
-  reconnects to a local server that is already up; a headless one rejects it and
-  exits non-zero, and turbo then tears down the other tasks in *that*
-  invocation — the first one keeps running untouched. `A dev server is already
-  running for this eve agent` means exactly what it says: you already have one.
-  Use the terminal it is in, or stop it before starting another.
+- **A headless dev process cannot reconnect.** An interactive `eve dev`
+  reconnects to a local server that is already up; `dev:headless` rejects it and
+  exits non-zero. `A dev server is already running for this eve agent` means
+  exactly what it says: use the terminal it is in, or stop it before starting
+  another.
 - **An orphaned agent holds the port.** If turbo dies without reaping its child,
-  nothing on screen says so and every later `bun run dev` fails the same way.
+  nothing on screen says so and every later `dev:headless` fails the same way.
   `lsof -nP -iTCP:2000 -sTCP:LISTEN` names the process to kill.
 
 ### Nothing is researching, and the queue only grows
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 3a65efce..f766ce65 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -25,6 +25,7 @@
 		"cmdk": "^1.1.1",
 		"date-fns": "^4.4.0",
 		"lucide-react": "^1.28.0",
+		"motion": "^12.42.2",
 		"next-themes": "^0.4.6",
 		"nuqs": "^2.8.9",
 		"radix-ui": "^1.6.0",
diff --git a/packages/ui/src/components/async-action.tsx b/packages/ui/src/components/async-action.tsx
new file mode 100644
index 00000000..35b49fa9
--- /dev/null
+++ b/packages/ui/src/components/async-action.tsx
@@ -0,0 +1,199 @@
+"use client";
+
+import { CircleAlertIcon, CheckIcon } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import {
+	type ReactNode,
+	useCallback,
+	useRef,
+	useState,
+} from "react";
+import { useMountEffect } from "@crm/ui/hooks/use-mount-effect";
+import { Spinner } from "@crm/ui/components/spinner";
+
+const TRANSITION = {
+	type: "spring",
+	stiffness: 520,
+	damping: 34,
+	mass: 0.45,
+} as const;
+
+const INSTANT = { duration: 0 } as const;
+
+export type AsyncActionStatus = "idle" | "pending" | "success" | "error";
+
+export type UseAsyncActionOptions<TArgs extends unknown[], TResult> = {
+	action: (...args: TArgs) => TResult | Promise<TResult>;
+	resetAfter?: number;
+	onSuccess?: (result: TResult) => void;
+	onError?: (error: unknown) => void;
+};
+
+export function useAsyncAction<TArgs extends unknown[], TResult>({
+	action,
+	resetAfter = 1400,
+	onSuccess,
+	onError,
+}: UseAsyncActionOptions<TArgs, TResult>) {
+	const [status, setStatus] = useState<AsyncActionStatus>("idle");
+	const phase = useRef<AsyncActionStatus>("idle");
+	const runId = useRef(0);
+	const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const alive = useRef(true);
+	const actionRef = useRef(action);
+	const successRef = useRef(onSuccess);
+	const errorRef = useRef(onError);
+
+	actionRef.current = action;
+	successRef.current = onSuccess;
+	errorRef.current = onError;
+
+	const clear = useCallback(() => {
+		if (timer.current) {
+			clearTimeout(timer.current);
+			timer.current = null;
+		}
+	}, []);
+
+	const reset = useCallback(() => {
+		runId.current += 1;
+		clear();
+		phase.current = "idle";
+		setStatus("idle");
+	}, [clear]);
+
+	const run = useCallback(
+		(...args: TArgs) => {
+			if (phase.current === "pending") return;
+
+			clear();
+			const id = ++runId.current;
+			phase.current = "pending";
+			setStatus("pending");
+
+			const settle = (next: "success" | "error") => {
+				if (!alive.current || id !== runId.current) return;
+				clear();
+				phase.current = next;
+				setStatus(next);
+				timer.current = setTimeout(() => {
+					if (!alive.current || id !== runId.current) return;
+					phase.current = "idle";
+					setStatus("idle");
+				}, resetAfter);
+			};
+
+			Promise.resolve()
+				.then(() => actionRef.current(...args))
+				.then(
+					(result) => {
+						settle("success");
+						successRef.current?.(result);
+					},
+					(error: unknown) => {
+						settle("error");
+						errorRef.current?.(error);
+					},
+				);
+		},
+		[clear, resetAfter],
+	);
+
+	useMountEffect(() => {
+		alive.current = true;
+		return () => {
+			alive.current = false;
+			clear();
+		};
+	});
+
+	return {
+		status,
+		run,
+		reset,
+		pending: status === "pending",
+	};
+}
+
+export type AsyncButtonContentProps = {
+	status: AsyncActionStatus;
+	children: ReactNode;
+	pendingLabel: ReactNode;
+	successLabel?: ReactNode;
+	errorLabel?: ReactNode;
+};
+
+export function AsyncButtonContent({
+	status,
+	children,
+	pendingLabel,
+	successLabel = "Done",
+	errorLabel = "Try again",
+}: AsyncButtonContentProps) {
+	const reduced = useReducedMotion() === true;
+	const states: Array<{ status: AsyncActionStatus; content: ReactNode }> = [
+		{ status: "idle", content: children },
+		{
+			status: "pending",
+			content: (
+				<>
+					<Spinner data-icon="inline-start" aria-hidden />
+					{pendingLabel}
+				</>
+			),
+		},
+		{
+			status: "success",
+			content: (
+				<>
+					<CheckIcon data-icon="inline-start" aria-hidden />
+					{successLabel}
+				</>
+			),
+		},
+		{
+			status: "error",
+			content: (
+				<>
+					<CircleAlertIcon data-icon="inline-start" aria-hidden />
+					{errorLabel}
+				</>
+			),
+		},
+	];
+
+	return (
+		<>
+			<span className="grid min-w-0 items-center justify-items-center">
+				{states.map((state) => {
+					const active = state.status === status;
+					return (
+						<motion.span
+							key={state.status}
+							aria-hidden={!active}
+							className="col-start-1 row-start-1 inline-flex items-center justify-center gap-1.5 whitespace-nowrap"
+							initial={false}
+							animate={{
+								opacity: active ? 1 : 0,
+								scale: reduced || active ? 1 : 0.92,
+								filter: reduced || active ? "blur(0px)" : "blur(2px)",
+							}}
+							transition={reduced ? INSTANT : TRANSITION}
+						>
+							{state.content}
+						</motion.span>
+					);
+				})}
+			</span>
+			<span role="status" aria-live="polite" className="sr-only">
+				{status === "pending"
+					? pendingLabel
+					: status === "success"
+						? successLabel
+						: status === "error"
+							? errorLabel
+							: ""}
+			</span>
+		</>
+	);
+}
diff --git a/packages/ui/src/components/button.tsx b/packages/ui/src/components/button.tsx
index 430d1bf6..6590d911 100644
--- a/packages/ui/src/components/button.tsx
+++ b/packages/ui/src/components/button.tsx
@@ -4,7 +4,7 @@ import { Slot } from "radix-ui";
 import type * as React from "react";
 
 const buttonVariants = cva(
-	"group/button inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent bg-clip-padding text-xs font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:ring-2 focus-visible:ring-ring/60 focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-2 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+	"group/button inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent bg-clip-padding text-xs font-medium whitespace-nowrap transition-[color,background-color,border-color,box-shadow,opacity,transform] outline-none select-none focus-visible:ring-2 focus-visible:ring-ring/60 focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-2 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 	{
 		variants: {
 			variant: {
diff --git a/packages/ui/src/components/progress.tsx b/packages/ui/src/components/progress.tsx
new file mode 100644
index 00000000..8d6b41eb
--- /dev/null
+++ b/packages/ui/src/components/progress.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import { cn } from "@crm/ui/lib/utils";
+import { motion, useReducedMotion } from "motion/react";
+import { useId } from "react";
+
+const FILL = {
+	type: "spring",
+	stiffness: 210,
+	damping: 34,
+	mass: 0.9,
+} as const;
+
+const INSTANT = { duration: 0 } as const;
+
+export type ProgressProps = {
+	value: number | null;
+	max?: number;
+	label?: string;
+	pendingLabel?: string;
+	completeLabel?: string;
+	className?: string;
+};
+
+export function Progress({
+	value,
+	max = 100,
+	label = "Progress",
+	pendingLabel = "Working",
+	completeLabel = "Complete",
+	className,
+}: ProgressProps) {
+	const reduced = useReducedMotion() === true;
+	const labelId = useId();
+	const indeterminate = value === null;
+	const fraction =
+		value === null || max <= 0 ? 0 : Math.min(1, Math.max(0, value / max));
+	const percent = Math.round(fraction * 100);
+	const complete = !indeterminate && fraction >= 1;
+
+	return (
+		<div className={cn("w-full", className)}>
+			<div className="flex items-baseline justify-between gap-3">
+				<span id={labelId} className="truncate font-medium text-xs">
+					{label}
+				</span>
+				<span
+					aria-hidden
+					className="grid shrink-0 justify-items-end font-mono text-muted-foreground text-xs tabular-nums"
+				>
+					<span className="col-start-1 row-start-1">
+						{indeterminate ? pendingLabel : `${percent}%`}
+					</span>
+				</span>
+			</div>
+			<div
+				role="progressbar"
+				aria-labelledby={labelId}
+				aria-valuemin={0}
+				aria-valuemax={max}
+				aria-valuenow={indeterminate ? undefined : fraction * max}
+				aria-valuetext={indeterminate ? pendingLabel : `${percent}%`}
+				className="mt-2 h-1.5 overflow-hidden rounded-full bg-muted"
+			>
+				<div className="relative h-full overflow-hidden rounded-full">
+					<motion.span
+						aria-hidden
+						className="absolute inset-0 block origin-left rounded-full bg-primary"
+						initial={false}
+						animate={{ scaleX: indeterminate ? 0 : fraction }}
+						transition={reduced ? INSTANT : FILL}
+					/>
+					{indeterminate ? (
+						<motion.span
+							aria-hidden
+							className="absolute inset-y-0 left-0 block w-2/5 rounded-full bg-primary"
+							initial={reduced ? { x: "75%" } : { x: "-100%" }}
+							animate={reduced ? { x: "75%" } : { x: "250%" }}
+							transition={
+								reduced
+									? INSTANT
+									: {
+											duration: 1.25,
+											ease: "easeInOut",
+											repeat: Number.POSITIVE_INFINITY,
+										}
+							}
+						/>
+					) : null}
+				</div>
+			</div>
+			<span role="status" aria-live="polite" className="sr-only">
+				{complete ? completeLabel : indeterminate ? pendingLabel : ""}
+			</span>
+		</div>
+	);
+}
diff --git a/packages/ui/src/components/skeleton-swap.tsx b/packages/ui/src/components/skeleton-swap.tsx
new file mode 100644
index 00000000..629a6ca1
--- /dev/null
+++ b/packages/ui/src/components/skeleton-swap.tsx
@@ -0,0 +1,132 @@
+"use client";
+
+import { Skeleton } from "@crm/ui/components/skeleton";
+import { useMountEffect } from "@crm/ui/hooks/use-mount-effect";
+import { cn } from "@crm/ui/lib/utils";
+import { motion, useReducedMotion } from "motion/react";
+import {
+	type ReactNode,
+	useCallback,
+	useRef,
+	useState,
+} from "react";
+
+const CROSSFADE = {
+	type: "spring",
+	stiffness: 260,
+	damping: 34,
+	mass: 0.8,
+} as const;
+
+const INSTANT = { duration: 0 } as const;
+
+export type SkeletonSwapProps = {
+	loading: boolean;
+	children: ReactNode;
+	skeleton?: ReactNode;
+	delay?: number;
+	minVisible?: number;
+	label?: string;
+	className?: string;
+};
+
+export function SkeletonSwap({
+	loading,
+	children,
+	skeleton,
+	delay = 120,
+	minVisible = 380,
+	label,
+	className,
+}: SkeletonSwapProps) {
+	const [showSkeleton, setShowSkeleton] = useState(false);
+	const shownAt = useRef(0);
+	const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const reduced = useReducedMotion() === true;
+
+	const clear = useCallback(() => {
+		if (timer.current) {
+			clearTimeout(timer.current);
+			timer.current = null;
+		}
+	}, []);
+
+	const bind = useCallback(
+		(node: HTMLDivElement | null) => {
+			if (!node) return;
+			clear();
+
+			if (loading && !showSkeleton) {
+				timer.current = setTimeout(() => {
+					shownAt.current = performance.now();
+					setShowSkeleton(true);
+				}, delay);
+				return;
+			}
+
+			if (!loading && showSkeleton) {
+				const remaining = Math.max(
+					0,
+					minVisible - (performance.now() - shownAt.current),
+				);
+				timer.current = setTimeout(() => setShowSkeleton(false), remaining);
+			}
+		},
+		[clear, delay, loading, minVisible, showSkeleton],
+	);
+
+	useMountEffect(() => clear);
+
+	return (
+		<div
+			ref={bind}
+			aria-busy={loading}
+			aria-label={label}
+			className={cn("relative grid min-w-0", className)}
+		>
+			<motion.div
+				className="col-start-1 row-start-1 min-w-0"
+				initial={false}
+				animate={{
+					opacity: showSkeleton ? 0 : 1,
+					scale: reduced || !showSkeleton ? 1 : 0.99,
+					filter: reduced || !showSkeleton ? "blur(0px)" : "blur(3px)",
+				}}
+				transition={reduced ? INSTANT : CROSSFADE}
+				style={{
+					transformOrigin: "top left",
+					pointerEvents: showSkeleton ? "none" : undefined,
+				}}
+			>
+				{children}
+			</motion.div>
+			<motion.div
+				aria-hidden
+				className="pointer-events-none col-start-1 row-start-1 min-w-0"
+				initial={false}
+				animate={{
+					opacity: showSkeleton ? 1 : 0,
+					filter: reduced || showSkeleton ? "blur(0px)" : "blur(3px)",
+				}}
+				transition={reduced ? INSTANT : CROSSFADE}
+			>
+				{skeleton ?? <DefaultSkeleton />}
+			</motion.div>
+			{label ? (
+				<span role="status" aria-live="polite" className="sr-only">
+					{loading ? "" : `${label} loaded`}
+				</span>
+			) : null}
+		</div>
+	);
+}
+
+function DefaultSkeleton() {
+	return (
+		<div className="flex flex-col gap-2">
+			<Skeleton className="h-4 w-full" />
+			<Skeleton className="h-4 w-11/12" />
+			<Skeleton className="h-4 w-8/12" />
+		</div>
+	);
+}
diff --git a/packages/ui/src/components/task-steps.tsx b/packages/ui/src/components/task-steps.tsx
new file mode 100644
index 00000000..d0308d58
--- /dev/null
+++ b/packages/ui/src/components/task-steps.tsx
@@ -0,0 +1,144 @@
+"use client";
+
+import { CheckIcon, XIcon } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import { Spinner } from "@crm/ui/components/spinner";
+import { cn } from "@crm/ui/lib/utils";
+
+const TRANSITION = {
+	type: "spring",
+	stiffness: 520,
+	damping: 34,
+	mass: 0.45,
+} as const;
+
+const INSTANT = { duration: 0 } as const;
+
+export type TaskStep = {
+	id: string;
+	label: string;
+	meta?: string;
+};
+
+export type TaskStepStatus = "pending" | "active" | "done" | "error";
+
+export type UseTaskStepsOptions = {
+	steps: TaskStep[];
+	current: number;
+	failed?: boolean;
+};
+
+export function useTaskSteps({
+	steps,
+	current,
+	failed = false,
+}: UseTaskStepsOptions) {
+	const complete = !failed && current >= steps.length;
+	const rows = steps.map((step, index) => ({
+		...step,
+		status: (index < current
+			? "done"
+			: index === current && failed
+				? "error"
+				: index === current && !complete
+					? "active"
+					: "pending") as TaskStepStatus,
+	}));
+	const active = rows.find((row) => row.status === "active");
+	const sentence = failed
+		? `Failed at ${steps[Math.min(current, steps.length - 1)]?.label ?? "step"}`
+		: complete
+			? `All ${steps.length} steps complete`
+			: active
+				? `${active.label}, step ${current + 1} of ${steps.length}`
+				: "";
+
+	return { rows, complete, sentence };
+}
+
+export type TaskStepsProps = UseTaskStepsOptions & {
+	label?: string;
+	className?: string;
+};
+
+export function TaskSteps({
+	steps,
+	current,
+	failed = false,
+	label = "Task progress",
+	className,
+}: TaskStepsProps) {
+	const { rows, complete, sentence } = useTaskSteps({
+		steps,
+		current,
+		failed,
+	});
+	const reduced = useReducedMotion() === true;
+
+	return (
+		<div className={cn("w-full", className)}>
+			<ol aria-label={label}>
+				{rows.map((row) => (
+					<li
+						key={row.id}
+						aria-current={row.status === "active" ? "step" : undefined}
+						className="flex min-h-10 items-start gap-3 border-t px-4 py-2.5 first:border-t-0 sm:h-8 sm:min-h-0 sm:items-center sm:gap-4 sm:px-5 sm:py-0"
+					>
+						<span className="relative grid size-5 shrink-0 place-items-center">
+							{(["pending", "active", "done", "error"] as const).map(
+								(status) => {
+									const active = row.status === status;
+									return (
+										<motion.span
+											key={status}
+											aria-hidden
+											className={cn(
+												"col-start-1 row-start-1 grid size-5 place-items-center",
+												status === "done" && "text-ring",
+												status === "error" && "text-destructive",
+												status === "active" && "text-muted-foreground",
+											)}
+											initial={false}
+											animate={{
+												opacity: active ? 1 : 0,
+												scale: reduced || active ? 1 : 0.6,
+											}}
+											transition={reduced ? INSTANT : TRANSITION}
+										>
+											{status === "done" ? <CheckIcon /> : null}
+											{status === "error" ? <XIcon /> : null}
+											{status === "active" ? (
+												<Spinner aria-hidden />
+											) : null}
+										</motion.span>
+									);
+								},
+							)}
+						</span>
+						<span
+							className={cn(
+								"min-w-0 flex-1 wrap-break-word text-sm transition-colors",
+								row.status === "active" && "font-medium",
+								row.status === "pending" && "text-muted-foreground",
+								row.status === "error" && "font-medium text-destructive",
+							)}
+						>
+							{row.label}
+						</span>
+						{row.meta ? (
+							<span className="min-w-0 max-w-[45%] text-right text-muted-foreground text-xs sm:w-60 sm:max-w-none sm:shrink-0">
+								{row.meta}
+							</span>
+						) : null}
+					</li>
+				))}
+			</ol>
+			<span role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+				{sentence}
+			</span>
+			<span className="sr-only" aria-live={complete || failed ? "polite" : "off"}>
+				{complete ? "Task complete" : failed ? "Task failed" : ""}
+			</span>
+		</div>
+	);
+}

From d1b39196aff6419b81d80b507530cb609ba9799e Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 21:50:10 -0700
Subject: [PATCH 4/7] CMP-34 feat: ship private durable agent creation
 workspace

---
 apps/agent/agent/lib/builder-runtime.ts       | 112 ++++++++++
 .../subagents/agent_builder/instructions.md   |  14 +-
 .../agent_builder/tools/write_agent_file.ts   |  24 +++
 apps/api/src/agent/agent-access.service.ts    |  24 +++
 .../src/agent/agent-definitions.service.ts    |   5 +-
 apps/api/src/agent/agent-runs.service.ts      |   9 +-
 apps/api/src/agent/agent-visibility.ts        |  15 ++
 .../conversation-sharing.service.ts           |  19 ++
 .../conversations/conversations.contracts.ts  |   2 +
 .../conversations/conversations.service.ts    |  27 ++-
 apps/api/src/workspace/workspace.contracts.ts |   8 +
 apps/api/src/workspace/workspace.service.ts   |   2 +-
 apps/api/test/agent-visibility.spec.ts        |  26 +++
 .../[slug]/(agent-builder)/agent/page.tsx     |   2 +-
 .../(agent-builder)/agents/[agentId]/page.tsx |  23 ++-
 .../[slug]/(agent-builder)/agents/page.tsx    |  19 +-
 .../(agent-builder)/agents/team/page.tsx      |  13 +-
 .../(agent-builder)/chat/[chatId]/page.tsx    |  25 ++-
 .../[slug]/(agent-builder)/chat/page.tsx      |  38 ++++
 .../(app)/[slug]/(agent-builder)/layout.tsx   |  27 ++-
 apps/app/app/(app)/[slug]/layout.tsx          |   2 +
 .../(landing)/onboarding/onboarding-form.tsx  |  41 +++-
 .../agent-builder/agent-builder-chat.tsx      | 157 ++++++++++----
 .../agent-builder/agent-builder-home.tsx      |   4 +-
 .../agent-builder/agent-builder-shell.tsx     |  21 +-
 .../agent-builder/agent-builder-sidebar.tsx   |  12 +-
 .../agent-builder/agent-code-workspace.tsx    | 194 ++++++++++++++++++
 .../agent-builder/agent-composer.tsx          | 142 +++++++------
 .../components/agent-builder/chat-chips.tsx   | 158 ++++++++++++++
 .../agent-builder/team-agents-index.tsx       |  36 +++-
 apps/app/components/app-icon-rail.tsx         |  14 +-
 apps/app/lib/agent-builder.ts                 |  19 +-
 apps/app/lib/use-hydrated.ts                  |  19 ++
 apps/app/package.json                         |   2 +
 apps/app/test/agent-builder.spec.ts           |   8 +
 bun.lock                                      |  50 +++++
 .../migration.sql                             |  23 +++
 packages/db/prisma/schema.prisma              |  30 +++
 packages/db/src/workspace.ts                  |   3 +
 39 files changed, 1196 insertions(+), 173 deletions(-)
 create mode 100644 apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts
 create mode 100644 apps/api/src/agent/agent-visibility.ts
 create mode 100644 apps/api/test/agent-visibility.spec.ts
 create mode 100644 apps/app/app/(app)/[slug]/(agent-builder)/chat/page.tsx
 create mode 100644 apps/app/components/agent-builder/agent-code-workspace.tsx
 create mode 100644 apps/app/components/agent-builder/chat-chips.tsx
 create mode 100644 apps/app/lib/use-hydrated.ts
 create mode 100644 packages/db/prisma/migrations/20260804210000_agent_builder_artifacts/migration.sql

diff --git a/apps/agent/agent/lib/builder-runtime.ts b/apps/agent/agent/lib/builder-runtime.ts
index dd436cb3..b7ed74ef 100644
--- a/apps/agent/agent/lib/builder-runtime.ts
+++ b/apps/agent/agent/lib/builder-runtime.ts
@@ -34,6 +34,64 @@ export type DraftAgentInput = {
 	access: string[];
 };
 
+export const BUILDER_ARTIFACT_PATHS = [
+	"agent/README.md",
+	"agent/instructions.md",
+	"agent/manifest.json",
+] as const;
+
+export type BuilderArtifactPath = (typeof BUILDER_ARTIFACT_PATHS)[number];
+
+const ARTIFACT_LANGUAGES: Record<BuilderArtifactPath, string> = {
+	"agent/README.md": "markdown",
+	"agent/instructions.md": "markdown",
+	"agent/manifest.json": "json",
+};
+
+export async function writeBuilderArtifact(
+	conversationId: string,
+	userId: string,
+	path: BuilderArtifactPath,
+	content: string,
+) {
+	assertSafeArtifact(content);
+
+	return db.$transaction(async (tx) => {
+		const conversation = await tx.agentConversation.findFirst({
+			where: { id: conversationId, userId, kind: "BUILDER" },
+			select: { id: true },
+		});
+		if (!conversation) {
+			throw new Error("This builder conversation is unavailable.");
+		}
+
+		const latest = await tx.agentBuilderArtifact.findFirst({
+			where: { conversationId, path },
+			orderBy: { revision: "desc" },
+			select: { id: true, revision: true, content: true, status: true },
+		});
+
+		if (latest?.content === content && latest.status === "WRITING") {
+			return { saved: true as const, id: latest.id, revision: latest.revision };
+		}
+
+		const artifact = await tx.agentBuilderArtifact.create({
+			data: {
+				conversationId,
+				path,
+				language: ARTIFACT_LANGUAGES[path],
+				content,
+				previousContent: latest?.content ?? null,
+				revision: (latest?.revision ?? 0) + 1,
+				status: "WRITING",
+			},
+			select: { id: true, revision: true },
+		});
+
+		return { saved: true as const, ...artifact };
+	});
+}
+
 export async function builderContext(conversationId: string, userId: string) {
 	const conversation = await db.agentConversation.findFirst({
 		where: { id: conversationId, userId, kind: "BUILDER" },
@@ -138,6 +196,8 @@ export async function saveBuilderDraft(
 		networkPolicy: "deny-all",
 		credentials: "app-runtime-only",
 	};
+	const files = artifactFiles(input, manifest);
+	for (const file of files) assertSafeArtifact(file.content);
 
 	return db.$transaction(async (tx) => {
 		let agentId = conversation.agentId;
@@ -192,6 +252,26 @@ export async function saveBuilderDraft(
 			select: { id: true, number: true, status: true },
 		});
 
+		for (const file of files) {
+			const latestArtifact = await tx.agentBuilderArtifact.findFirst({
+				where: { conversationId, path: file.path },
+				orderBy: { revision: "desc" },
+				select: { revision: true, content: true },
+			});
+			await tx.agentBuilderArtifact.create({
+				data: {
+					conversationId,
+					versionId: version.id,
+					path: file.path,
+					language: file.language,
+					content: file.content,
+					previousContent: latestArtifact?.content ?? null,
+					revision: (latestArtifact?.revision ?? 0) + 1,
+					status: "READY",
+				},
+			});
+		}
+
 		await tx.agentTrigger.create({
 			data: {
 				agentId,
@@ -404,6 +484,38 @@ function scheduleDate(trigger: DraftTrigger, now: Date): Date | null {
 	return parsed > now ? parsed : null;
 }
 
+function artifactFiles(input: DraftAgentInput, manifest: object) {
+	return [
+		{
+			path: "agent/README.md" as const,
+			language: ARTIFACT_LANGUAGES["agent/README.md"],
+			content: `# ${input.name}\n\n${input.description}\n\n## Trigger\n\n${input.trigger.summary}\n\n## Access\n\n${input.access.map((item) => `- ${item}`).join("\n") || "- CRM data in the approved scope"}\n`,
+		},
+		{
+			path: "agent/instructions.md" as const,
+			language: ARTIFACT_LANGUAGES["agent/instructions.md"],
+			content: `${input.instructions.trim()}\n`,
+		},
+		{
+			path: "agent/manifest.json" as const,
+			language: ARTIFACT_LANGUAGES["agent/manifest.json"],
+			content: `${JSON.stringify(manifest, null, 2)}\n`,
+		},
+	];
+}
+
+function assertSafeArtifact(content: string): void {
+	const secretPatterns = [
+		/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/i,
+		/\b(?:api[_-]?key|password|secret|access[_-]?token)\b\s*[:=]\s*["']?[a-z0-9_./+=-]{12,}/i,
+		/\b(?:sk|pk)_(?:live|test)_[a-z0-9]{16,}/i,
+	];
+
+	if (secretPatterns.some((pattern) => pattern.test(content))) {
+		throw new Error("Agent files cannot contain credentials or secret values.");
+	}
+}
+
 function scopeSummary(resources: BuilderResource[]): string {
 	if (resources.length === 0)
 		return "Workspace CRM records required by the run";
diff --git a/apps/agent/agent/subagents/agent_builder/instructions.md b/apps/agent/agent/subagents/agent_builder/instructions.md
index 9851c216..7dc65537 100644
--- a/apps/agent/agent/subagents/agent_builder/instructions.md
+++ b/apps/agent/agent/subagents/agent_builder/instructions.md
@@ -23,7 +23,13 @@ do not call `save_agent_draft`. Return one focused question for the parent to
 ask the user. For a schedule, calculate a future `nextRunAt` from the supplied
 current time and provide its recurrence in minutes.
 
-When the behavior is specific and supported, call `save_agent_draft` once. A
-successful save creates an immutable version in READY state for human review.
-It does not deploy it. Summarize the trigger, data scope, action, and access in
-plain language, then tell the parent the draft is ready for review.
+When the behavior is specific and supported, build the agent in front of the
+user. Call `write_agent_file` for `agent/instructions.md`, then
+`agent/manifest.json`, then `agent/README.md`. These are durable working
+revisions, so write complete useful contents and revise a file with another
+call when necessary. Never put credentials, tokens, or secret values in a
+file. After the three files agree, call `save_agent_draft` once with the exact
+same behavior. A successful save creates exact final file snapshots and an
+immutable version in READY state for human review. It does not deploy it.
+Summarize the trigger, data scope, action, and access in plain language, then
+tell the parent the draft is ready for review.
diff --git a/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts b/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts
new file mode 100644
index 00000000..7e0878b0
--- /dev/null
+++ b/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts
@@ -0,0 +1,24 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import {
+	BUILDER_ARTIFACT_PATHS,
+	writeBuilderArtifact,
+} from "../../../lib/builder-runtime";
+import { requireAttribute } from "../../../lib/session-purpose";
+
+export default defineTool({
+	description:
+		"Write one durable agent file revision so the user can follow the build live. Write instructions and the manifest before saving the final draft.",
+	inputSchema: z.object({
+		path: z.enum(BUILDER_ARTIFACT_PATHS),
+		content: z.string().min(1).max(40_000),
+	}),
+	async execute(input, ctx) {
+		return writeBuilderArtifact(
+			requireAttribute(ctx, "conversationId"),
+			requireAttribute(ctx, "userId"),
+			input.path,
+			input.content,
+		);
+	},
+});
diff --git a/apps/api/src/agent/agent-access.service.ts b/apps/api/src/agent/agent-access.service.ts
index 77ac85de..1c2c4284 100644
--- a/apps/api/src/agent/agent-access.service.ts
+++ b/apps/api/src/agent/agent-access.service.ts
@@ -11,6 +11,7 @@ import {
 	NotFoundException,
 } from "@nestjs/common";
 import { InjectDatabase } from "../database/database.constants";
+import { canReadAgent, isPrivateAgentDraft } from "./agent-visibility";
 
 @Injectable()
 export class AgentAccessService {
@@ -50,6 +51,10 @@ export class AgentAccessService {
 			throw new NotFoundException(`No agent with id ${agentId}.`);
 		}
 
+		if (isPrivateAgentDraft(agent.status) && agent.createdById !== userId) {
+			throw new NotFoundException(`No agent with id ${agentId}.`);
+		}
+
 		if (agent.createdById !== userId && !isWorkspaceAdmin(role)) {
 			throw new ForbiddenException(
 				"Only the creator or a workspace admin can change this agent.",
@@ -58,4 +63,23 @@ export class AgentAccessService {
 
 		return agent;
 	}
+
+	async assertCanRead(agentId: string, userId: string) {
+		await this.assertMember(userId);
+		const agent = await this.db.agentDefinition.findFirst({
+			where: { id: agentId, status: { not: "DELETED" } },
+			select: {
+				id: true,
+				createdById: true,
+				status: true,
+				currentVersionId: true,
+			},
+		});
+
+		if (!agent || !canReadAgent(agent.status, agent.createdById, userId)) {
+			throw new NotFoundException(`No agent with id ${agentId}.`);
+		}
+
+		return agent;
+	}
 }
diff --git a/apps/api/src/agent/agent-definitions.service.ts b/apps/api/src/agent/agent-definitions.service.ts
index 6611e5ec..32bd2aa8 100644
--- a/apps/api/src/agent/agent-definitions.service.ts
+++ b/apps/api/src/agent/agent-definitions.service.ts
@@ -6,6 +6,7 @@ import {
 } from "@nestjs/common";
 import { InjectDatabase } from "../database/database.constants";
 import { AgentAccessService } from "./agent-access.service";
+import { TEAM_AGENT_STATUSES } from "./agent-visibility";
 import type { AgentDeployInput, AgentUpdateInput } from "./agents.contracts";
 
 @Injectable()
@@ -19,7 +20,7 @@ export class AgentDefinitionsService {
 		await this.access.assertMember(userId);
 
 		const rows = await this.db.agentDefinition.findMany({
-			where: { status: { not: "DELETED" } },
+			where: { status: { in: [...TEAM_AGENT_STATUSES] } },
 			orderBy: { updatedAt: "desc" },
 			select: {
 				id: true,
@@ -61,7 +62,7 @@ export class AgentDefinitionsService {
 	}
 
 	async byId(id: string, userId: string) {
-		await this.access.assertMember(userId);
+		await this.access.assertCanRead(id, userId);
 
 		const row = await this.db.agentDefinition.findFirst({
 			where: { id, status: { not: "DELETED" } },
diff --git a/apps/api/src/agent/agent-runs.service.ts b/apps/api/src/agent/agent-runs.service.ts
index 24f6d2ef..dc3bddf6 100644
--- a/apps/api/src/agent/agent-runs.service.ts
+++ b/apps/api/src/agent/agent-runs.service.ts
@@ -197,13 +197,6 @@ export class AgentRunsService {
 	}
 
 	private async readableAgent(agentId: string, userId: string) {
-		await this.access.assertMember(userId);
-		const agent = await this.db.agentDefinition.findFirst({
-			where: { id: agentId, status: { not: "DELETED" } },
-			select: { id: true, status: true, currentVersionId: true },
-		});
-
-		if (!agent) throw new NotFoundException(`No agent with id ${agentId}.`);
-		return agent;
+		return this.access.assertCanRead(agentId, userId);
 	}
 }
diff --git a/apps/api/src/agent/agent-visibility.ts b/apps/api/src/agent/agent-visibility.ts
new file mode 100644
index 00000000..c74082c5
--- /dev/null
+++ b/apps/api/src/agent/agent-visibility.ts
@@ -0,0 +1,15 @@
+import type { AgentDefinitionStatus } from "@crm/db/enums";
+
+export const TEAM_AGENT_STATUSES = ["LIVE", "PAUSED", "ARCHIVED"] as const;
+
+export function isPrivateAgentDraft(status: AgentDefinitionStatus): boolean {
+	return status === "DRAFT" || status === "DEPLOYING";
+}
+
+export function canReadAgent(
+	status: AgentDefinitionStatus,
+	createdById: string,
+	userId: string,
+): boolean {
+	return !isPrivateAgentDraft(status) || createdById === userId;
+}
diff --git a/apps/api/src/conversations/conversation-sharing.service.ts b/apps/api/src/conversations/conversation-sharing.service.ts
index cb2e9f11..3cd3ccd3 100644
--- a/apps/api/src/conversations/conversation-sharing.service.ts
+++ b/apps/api/src/conversations/conversation-sharing.service.ts
@@ -81,6 +81,21 @@ export class ConversationSharingService {
 						lastMessageAt: true,
 						user: { select: { name: true } },
 						agent: { select: { id: true, name: true, status: true } },
+						builderArtifacts: {
+							orderBy: [{ createdAt: "desc" }, { revision: "desc" }],
+							take: 100,
+							select: {
+								id: true,
+								versionId: true,
+								path: true,
+								language: true,
+								content: true,
+								previousContent: true,
+								revision: true,
+								status: true,
+								createdAt: true,
+							},
+						},
 						submissions: {
 							orderBy: { createdAt: "asc" },
 							select: {
@@ -117,6 +132,10 @@ export class ConversationSharingService {
 			ownerName: conversation.user.name,
 			lastMessageAt: conversation.lastMessageAt.toISOString(),
 			agent: conversation.agent,
+			builderArtifacts: conversation.builderArtifacts.map((artifact) => ({
+				...artifact,
+				createdAt: artifact.createdAt.toISOString(),
+			})),
 			submissions: conversation.submissions.map((submission) => ({
 				...submission,
 				createdAt: submission.createdAt.toISOString(),
diff --git a/apps/api/src/conversations/conversations.contracts.ts b/apps/api/src/conversations/conversations.contracts.ts
index f0acdb17..30e2b0f4 100644
--- a/apps/api/src/conversations/conversations.contracts.ts
+++ b/apps/api/src/conversations/conversations.contracts.ts
@@ -34,6 +34,8 @@ export const builderResource = z.object({
 	kind: z.enum(["integration", "company", "contact", "deal"]),
 	id: z.string().trim().min(1).max(160),
 	label: z.string().trim().min(1).max(120),
+	detail: z.string().trim().max(160).nullable().optional(),
+	imageUrl: z.url().nullable().optional(),
 });
 
 export const builderAttachment = z.object({
diff --git a/apps/api/src/conversations/conversations.service.ts b/apps/api/src/conversations/conversations.service.ts
index 5f107476..56bb0391 100644
--- a/apps/api/src/conversations/conversations.service.ts
+++ b/apps/api/src/conversations/conversations.service.ts
@@ -195,7 +195,7 @@ export class ConversationsService {
 				where: contains ? { name: contains } : undefined,
 				orderBy: { lastActivityAt: { sort: "desc", nulls: "last" } },
 				take: 6,
-				select: { id: true, name: true, domain: true },
+				select: { id: true, name: true, domain: true, logoUrl: true },
 			}),
 			this.db.contact.findMany({
 				where: contains
@@ -214,6 +214,7 @@ export class ConversationsService {
 					firstName: true,
 					lastName: true,
 					email: true,
+					imageUrl: true,
 					company: { select: { name: true } },
 				},
 			}),
@@ -224,7 +225,7 @@ export class ConversationsService {
 				select: {
 					id: true,
 					name: true,
-					company: { select: { name: true } },
+					company: { select: { name: true, logoUrl: true } },
 				},
 			}),
 		]);
@@ -235,18 +236,21 @@ export class ConversationsService {
 				id: company.id,
 				label: company.name,
 				detail: company.domain,
+				imageUrl: company.logoUrl,
 			})),
 			...contacts.map((contact) => ({
 				kind: "contact" as const,
 				id: contact.id,
 				label: [contact.firstName, contact.lastName].filter(Boolean).join(" "),
 				detail: contact.company?.name ?? contact.email,
+				imageUrl: contact.imageUrl,
 			})),
 			...deals.map((deal) => ({
 				kind: "deal" as const,
 				id: deal.id,
 				label: deal.name,
 				detail: deal.company.name,
+				imageUrl: deal.company.logoUrl,
 			})),
 		];
 	}
@@ -310,6 +314,21 @@ export class ConversationsService {
 						createdAt: true,
 					},
 				},
+				builderArtifacts: {
+					orderBy: [{ createdAt: "desc" }, { revision: "desc" }],
+					take: 100,
+					select: {
+						id: true,
+						versionId: true,
+						path: true,
+						language: true,
+						content: true,
+						previousContent: true,
+						revision: true,
+						status: true,
+						createdAt: true,
+					},
+				},
 				feedback: {
 					where: { userId },
 					select: { messageId: true, rating: true },
@@ -361,6 +380,10 @@ export class ConversationsService {
 				...version,
 				createdAt: version.createdAt.toISOString(),
 			})),
+			builderArtifacts: row.builderArtifacts.map((artifact) => ({
+				...artifact,
+				createdAt: artifact.createdAt.toISOString(),
+			})),
 			submissions: row.submissions.map((submission) => ({
 				...submission,
 				createdAt: submission.createdAt.toISOString(),
diff --git a/apps/api/src/workspace/workspace.contracts.ts b/apps/api/src/workspace/workspace.contracts.ts
index a79a53da..55d57784 100644
--- a/apps/api/src/workspace/workspace.contracts.ts
+++ b/apps/api/src/workspace/workspace.contracts.ts
@@ -1,4 +1,5 @@
 import { WORKSPACE_ROLES } from "@crm/auth";
+import { MAX_SLUG } from "@crm/db/workspace";
 import { z } from "zod";
 import { listInput } from "../trpc/list-input";
 
@@ -11,6 +12,13 @@ export type MemberListInput = z.infer<typeof memberListInput>;
 export const updateWorkspaceInput = z.object({
 	name: z.string().trim().min(1).max(120),
 	website: z.string().trim().min(1).max(255),
+	slug: z
+		.string()
+		.trim()
+		.min(1)
+		.max(MAX_SLUG)
+		.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+		.optional(),
 });
 
 export const setMemberRoleInput = z.object({
diff --git a/apps/api/src/workspace/workspace.service.ts b/apps/api/src/workspace/workspace.service.ts
index bce1d687..505a0a10 100644
--- a/apps/api/src/workspace/workspace.service.ts
+++ b/apps/api/src/workspace/workspace.service.ts
@@ -144,7 +144,7 @@ export class WorkspaceService {
 			where: { id: WORKSPACE_ID },
 			data: {
 				name: input.name,
-				slug: workspaceSlug(input.name),
+				slug: workspaceSlug(input.slug ?? input.name),
 				website,
 				metadata: markOnboarded(before?.metadata ?? null, new Date()),
 			},
diff --git a/apps/api/test/agent-visibility.spec.ts b/apps/api/test/agent-visibility.spec.ts
new file mode 100644
index 00000000..8c012f78
--- /dev/null
+++ b/apps/api/test/agent-visibility.spec.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "bun:test";
+import {
+	canReadAgent,
+	isPrivateAgentDraft,
+	TEAM_AGENT_STATUSES,
+} from "../src/agent/agent-visibility";
+
+describe("agent visibility", () => {
+	it("keeps drafts private to their creator", () => {
+		expect(canReadAgent("DRAFT", "creator", "creator")).toBe(true);
+		expect(canReadAgent("DRAFT", "creator", "teammate")).toBe(false);
+		expect(canReadAgent("DEPLOYING", "creator", "teammate")).toBe(false);
+	});
+
+	it("makes deployed lifecycle states visible to the team", () => {
+		for (const status of TEAM_AGENT_STATUSES) {
+			expect(canReadAgent(status, "creator", "teammate")).toBe(true);
+		}
+	});
+
+	it("treats deployment as the ownership boundary", () => {
+		expect(isPrivateAgentDraft("DRAFT")).toBe(true);
+		expect(isPrivateAgentDraft("DEPLOYING")).toBe(true);
+		expect(isPrivateAgentDraft("LIVE")).toBe(false);
+	});
+});
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/agent/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/agent/page.tsx
index 4e2ac3b3..3bcdbe5c 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/agent/page.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/agent/page.tsx
@@ -7,5 +7,5 @@ export default async function AgentBuilderPage({
 	params: Promise<{ slug: string }>;
 }) {
 	const { slug } = await params;
-	redirect(workspaceUrl(slug, "/agents"));
+	redirect(workspaceUrl(slug, "/chat"));
 }
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/agents/[agentId]/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/agents/[agentId]/page.tsx
index ea85f69f..e68718ef 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/agents/[agentId]/page.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/agents/[agentId]/page.tsx
@@ -1,10 +1,23 @@
 import type { Metadata } from "next";
+import { Suspense } from "react";
 import { TeamAgentDetail } from "@/components/agent-builder/team-agent-detail";
 import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
 
 export const metadata: Metadata = { title: "Team agent" };
 
-export default async function TeamAgentPage({
+export default function TeamAgentPage({
+	params,
+}: {
+	params: Promise<{ agentId: string }>;
+}) {
+	return (
+		<Suspense fallback={<AgentDetailFallback />}>
+			<PrefetchedTeamAgent params={params} />
+		</Suspense>
+	);
+}
+
+async function PrefetchedTeamAgent({
 	params,
 }: {
 	params: Promise<{ agentId: string }>;
@@ -25,3 +38,11 @@ export default async function TeamAgentPage({
 
 	return <TeamAgentDetail agentId={agentId} />;
 }
+
+function AgentDetailFallback() {
+	return (
+		<main className="flex min-h-0 flex-1 items-center justify-center">
+			<span className="text-muted-foreground text-sm">Opening agent…</span>
+		</main>
+	);
+}
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/agents/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/agents/page.tsx
index f884d82f..c4a5b5f0 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/agents/page.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/agents/page.tsx
@@ -1,21 +1,8 @@
 import type { Metadata } from "next";
-import { AgentBuilderHome } from "@/components/agent-builder/agent-builder-home";
-import { requireSession } from "@/lib/session";
-import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+import { TeamAgentsIndex } from "@/components/agent-builder/team-agents-index";
 
 export const metadata: Metadata = { title: "Agents" };
 
-export default async function AgentsPage() {
-	const session = await requireSession();
-	const trpc = getServerTrpc();
-	const queryClient = getServerQueryClient();
-
-	await Promise.all([
-		queryClient.prefetchQuery(
-			trpc.conversations.builderResources.queryOptions({ q: "" }),
-		),
-		queryClient.prefetchQuery(trpc.google.status.queryOptions()),
-	]);
-
-	return <AgentBuilderHome name={session.user.name} />;
+export default function AgentsPage() {
+	return <TeamAgentsIndex />;
 }
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/agents/team/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/agents/team/page.tsx
index de732046..68330fd6 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/agents/team/page.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/agents/team/page.tsx
@@ -1,8 +1,9 @@
-import type { Metadata } from "next";
-import { TeamAgentsIndex } from "@/components/agent-builder/team-agents-index";
+import { redirect } from "next/navigation";
+import { workspaceUrl } from "@/lib/workspace-url";
 
-export const metadata: Metadata = { title: "Team agents" };
-
-export default function TeamAgentsListPage() {
-	return <TeamAgentsIndex />;
+export default async function TeamAgentsListPage({
+	params,
+}: PageProps<"/[slug]/agents/team">) {
+	const { slug } = await params;
+	redirect(workspaceUrl(slug, "/agents"));
 }
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/chat/[chatId]/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/chat/[chatId]/page.tsx
index ed82eb81..ef4e646f 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/chat/[chatId]/page.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/chat/[chatId]/page.tsx
@@ -1,10 +1,23 @@
 import type { Metadata } from "next";
+import { Suspense } from "react";
 import { AgentBuilderChat } from "@/components/agent-builder/agent-builder-chat";
 import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
 
 export const metadata: Metadata = { title: "Agent chat" };
 
-export default async function AgentChatPage({
+export default function AgentChatPage({
+	params,
+}: {
+	params: Promise<{ chatId: string }>;
+}) {
+	return (
+		<Suspense fallback={<ChatFallback />}>
+			<PrefetchedAgentChat params={params} />
+		</Suspense>
+	);
+}
+
+async function PrefetchedAgentChat({
 	params,
 }: {
 	params: Promise<{ chatId: string }>;
@@ -13,9 +26,17 @@ export default async function AgentChatPage({
 	const trpc = getServerTrpc();
 	const queryClient = getServerQueryClient();
 
-	void queryClient.prefetchQuery(
+	await queryClient.prefetchQuery(
 		trpc.conversations.builderById.queryOptions({ id: chatId }),
 	);
 
 	return <AgentBuilderChat conversationId={chatId} />;
 }
+
+function ChatFallback() {
+	return (
+		<main className="flex min-h-0 flex-1 items-center justify-center">
+			<span className="text-muted-foreground text-sm">Opening chat…</span>
+		</main>
+	);
+}
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/chat/page.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/chat/page.tsx
new file mode 100644
index 00000000..c65694ad
--- /dev/null
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/chat/page.tsx
@@ -0,0 +1,38 @@
+import type { Metadata } from "next";
+import { Suspense } from "react";
+import { AgentBuilderHome } from "@/components/agent-builder/agent-builder-home";
+import { requireSession } from "@/lib/session";
+import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
+
+export const metadata: Metadata = { title: "Chat" };
+
+export default function ChatPage() {
+	return (
+		<Suspense fallback={<ChatHomeFallback />}>
+			<ChatHome />
+		</Suspense>
+	);
+}
+
+async function ChatHome() {
+	const session = await requireSession();
+	const trpc = getServerTrpc();
+	const queryClient = getServerQueryClient();
+
+	await Promise.all([
+		queryClient.prefetchQuery(
+			trpc.conversations.builderResources.queryOptions({ q: "" }),
+		),
+		queryClient.prefetchQuery(trpc.google.status.queryOptions()),
+	]);
+
+	return <AgentBuilderHome name={session.user.name} />;
+}
+
+function ChatHomeFallback() {
+	return (
+		<main className="flex min-h-0 flex-1 items-center justify-center">
+			<span className="text-muted-foreground text-sm">Opening chat…</span>
+		</main>
+	);
+}
diff --git a/apps/app/app/(app)/[slug]/(agent-builder)/layout.tsx b/apps/app/app/(app)/[slug]/(agent-builder)/layout.tsx
index b4de3375..bba5b541 100644
--- a/apps/app/app/(app)/[slug]/(agent-builder)/layout.tsx
+++ b/apps/app/app/(app)/[slug]/(agent-builder)/layout.tsx
@@ -1,8 +1,33 @@
+import { Suspense } from "react";
 import { AgentBuilderShell } from "@/components/agent-builder/agent-builder-shell";
 import { HydrateClient } from "@/lib/trpc/hydrate";
 import { getServerQueryClient, getServerTrpc } from "@/lib/trpc/server";
 
-export default async function AgentBuilderLayout({
+export default function AgentBuilderLayout({
+	children,
+}: Readonly<{ children: React.ReactNode }>) {
+	return (
+		<Suspense
+			fallback={
+				<AgentBuilderShell>
+					<AgentBuilderContentFallback />
+				</AgentBuilderShell>
+			}
+		>
+			<PrefetchedAgentBuilderShell>{children}</PrefetchedAgentBuilderShell>
+		</Suspense>
+	);
+}
+
+function AgentBuilderContentFallback() {
+	return (
+		<main className="flex min-h-0 flex-1 items-center justify-center">
+			<span className="text-muted-foreground text-sm">Loading chat…</span>
+		</main>
+	);
+}
+
+async function PrefetchedAgentBuilderShell({
 	children,
 }: Readonly<{ children: React.ReactNode }>) {
 	const trpc = getServerTrpc();
diff --git a/apps/app/app/(app)/[slug]/layout.tsx b/apps/app/app/(app)/[slug]/layout.tsx
index aa7fcb95..19c4b050 100644
--- a/apps/app/app/(app)/[slug]/layout.tsx
+++ b/apps/app/app/(app)/[slug]/layout.tsx
@@ -1,4 +1,5 @@
 import { notFound, unstable_rethrow } from "next/navigation";
+import { connection } from "next/server";
 import { Suspense } from "react";
 import { AppHeader, AppHeaderFallback } from "@/components/app-header";
 import { AppIconRail, AppIconRailFallback } from "@/components/app-icon-rail";
@@ -42,6 +43,7 @@ export default function AppLayout({
 async function WorkspaceHeader({
 	params,
 }: Pick<LayoutProps<"/[slug]">, "params">) {
+	await connection();
 	const [{ user }, { slug }] = await Promise.all([
 		requireGoogleAccess(),
 		params,
diff --git a/apps/app/app/(landing)/onboarding/onboarding-form.tsx b/apps/app/app/(landing)/onboarding/onboarding-form.tsx
index 5801a375..50e12f8b 100644
--- a/apps/app/app/(landing)/onboarding/onboarding-form.tsx
+++ b/apps/app/app/(landing)/onboarding/onboarding-form.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import { workspaceSlug } from "@crm/db/workspace";
 import { Button } from "@crm/ui/components/button";
 import {
 	Field,
@@ -17,7 +18,7 @@ import {
 import { Spinner } from "@crm/ui/components/spinner";
 import { useMutation } from "@tanstack/react-query";
 import { useRouter } from "next/navigation";
-import { useId } from "react";
+import { useId, useState } from "react";
 import { toast } from "sonner";
 import { useTRPC } from "@/lib/trpc/client";
 
@@ -26,7 +27,11 @@ export function OnboardingForm({ placeholder }: { placeholder: string }) {
 	const router = useRouter();
 
 	const nameId = useId();
+	const slugId = useId();
 	const websiteId = useId();
+	const [name, setName] = useState("");
+	const [slug, setSlug] = useState("");
+	const [slugEdited, setSlugEdited] = useState(false);
 
 	const save = useMutation(
 		trpc.workspace.update.mutationOptions({
@@ -47,6 +52,7 @@ export function OnboardingForm({ placeholder }: { placeholder: string }) {
 
 				save.mutate({
 					name: String(form.get("name") ?? "").trim(),
+					slug: String(form.get("slug") ?? "").trim(),
 					website: String(form.get("website") ?? "").trim(),
 				});
 			}}
@@ -58,6 +64,12 @@ export function OnboardingForm({ placeholder }: { placeholder: string }) {
 					<Input
 						id={nameId}
 						name="name"
+						value={name}
+						onChange={(event) => {
+							const next = event.target.value;
+							setName(next);
+							if (!slugEdited) setSlug(workspaceSlug(next));
+						}}
 						placeholder={placeholder}
 						autoComplete="organization"
 						autoFocus
@@ -65,6 +77,33 @@ export function OnboardingForm({ placeholder }: { placeholder: string }) {
 					/>
 				</Field>
 
+				<Field>
+					<FieldLabel htmlFor={slugId}>Workspace URL</FieldLabel>
+					<InputGroup>
+						<InputGroupAddon>
+							<InputGroupText>/</InputGroupText>
+						</InputGroupAddon>
+						<InputGroupInput
+							id={slugId}
+							name="slug"
+							value={slug}
+							onChange={(event) => {
+								setSlugEdited(true);
+								setSlug(workspaceSlug(event.target.value));
+							}}
+							placeholder={workspaceSlug(placeholder)}
+							autoComplete="off"
+							autoCapitalize="off"
+							autoCorrect="off"
+							spellCheck={false}
+							required
+						/>
+					</InputGroup>
+					<FieldDescription>
+						Your team will use this address to open the CRM.
+					</FieldDescription>
+				</Field>
+
 				<Field>
 					<FieldLabel htmlFor={websiteId}>Website</FieldLabel>
 					<InputGroup>
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
index e495e759..967944d1 100644
--- a/apps/app/components/agent-builder/agent-builder-chat.tsx
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -1,14 +1,18 @@
 "use client";
 
 import Add from "@carbon/icons-react/es/Add";
+import Application from "@carbon/icons-react/es/Application";
 import ArrowRight from "@carbon/icons-react/es/ArrowRight";
+import Building from "@carbon/icons-react/es/Building";
 import Checkmark from "@carbon/icons-react/es/Checkmark";
 import CheckmarkFilled from "@carbon/icons-react/es/CheckmarkFilled";
 import Copy from "@carbon/icons-react/es/Copy";
+import Partnership from "@carbon/icons-react/es/Partnership";
 import Play from "@carbon/icons-react/es/Play";
 import Renew from "@carbon/icons-react/es/Renew";
 import ThumbsDown from "@carbon/icons-react/es/ThumbsDown";
 import ThumbsUp from "@carbon/icons-react/es/ThumbsUp";
+import User from "@carbon/icons-react/es/User";
 import WarningAlt from "@carbon/icons-react/es/WarningAlt";
 import {
 	AsyncButtonContent,
@@ -26,7 +30,10 @@ import { useEveAgent } from "eve/react";
 import Link from "next/link";
 import { useState } from "react";
 import { toast } from "sonner";
-import { hasCreateAgentCommand } from "@/lib/agent-builder";
+import {
+	consumeBuilderCommand,
+	hasCreateAgentCommand,
+} from "@/lib/agent-builder";
 import {
 	type AgentTurnFailure,
 	latestTurnFailure,
@@ -35,7 +42,13 @@ import {
 import { useTRPC } from "@/lib/trpc/client";
 import type { RouterOutputs } from "@/lib/trpc/types";
 import { useWorkspaceUrl } from "@/lib/use-workspace-url";
+import { AgentCodeWorkspace } from "./agent-code-workspace";
 import { AgentComposer, type BuilderPrompt } from "./agent-composer";
+import {
+	ChatAttachmentChip,
+	ChatCommandChip,
+	ChatReferenceChip,
+} from "./chat-chips";
 import { ShareChatDialog } from "./share-chat-dialog";
 
 type Conversation = RouterOutputs["conversations"]["builderById"];
@@ -124,7 +137,7 @@ export function AgentBuilderChat({
 						{conversation.error.message}
 					</p>
 					<Button asChild variant="outline" className="mt-5">
-						<Link href={workspaceUrl("/agents")}>Start a new chat</Link>
+						<Link href={workspaceUrl("/chat")}>Start a new chat</Link>
 					</Button>
 				</div>
 			</main>
@@ -170,7 +183,7 @@ export function AgentBuilderChat({
 					{submissions.map((submission) => (
 						<UserSubmission
 							key={submission.id}
-							message={submissionText(submission.message)}
+							submission={submission}
 							failed={submission.status === "FAILED"}
 							error={submission.errorMessage}
 						/>
@@ -188,7 +201,14 @@ export function AgentBuilderChat({
 						<BuildingAgentCard
 							conversationId={conversationId}
 							sessionId={data.sessionId}
-							eventCount={events.data?.length ?? 0}
+							artifacts={data.builderArtifacts}
+						/>
+					) : null}
+
+					{creatingAgent && data.builderArtifacts.length > 0 ? (
+						<AgentCodeWorkspace
+							artifacts={data.builderArtifacts}
+							working={working}
 						/>
 					) : null}
 
@@ -278,7 +298,7 @@ function SharedAgentChat({
 					{submissions.map((submission) => (
 						<UserSubmission
 							key={submission.id}
-							message={submissionText(submission.message)}
+							submission={submission}
 							failed={submission.status === "FAILED"}
 							error={submission.errorMessage}
 						/>
@@ -287,6 +307,13 @@ function SharedAgentChat({
 					{events.length > 0 ? (
 						<SharedAssistantTranscript events={events} />
 					) : null}
+
+					{conversation.builderArtifacts.length > 0 ? (
+						<AgentCodeWorkspace
+							artifacts={conversation.builderArtifacts}
+							working={false}
+						/>
+					) : null}
 				</div>
 			</div>
 		</main>
@@ -370,7 +397,7 @@ function ChatHeader({
 				) : null}
 			</div>
 			<Button asChild variant="ghost" size="icon-sm">
-				<Link href={workspaceUrl("/agents")} aria-label="Start a new chat">
+				<Link href={workspaceUrl("/chat")} aria-label="Start a new chat">
 					<Icon icon={Add} />
 				</Link>
 			</Button>
@@ -380,18 +407,47 @@ function ChatHeader({
 }
 
 function UserSubmission({
-	message,
+	submission,
 	failed,
 	error,
 }: {
-	message: string;
+	submission: BuilderSubmission;
 	failed: boolean;
 	error: string | null;
 }) {
+	const message = builderMessageOf(submission.message);
+	const command =
+		submission.commandType === "CREATE_AGENT"
+			? consumeBuilderCommand(message.text)
+			: null;
+	const text = command?.body ?? message.text;
+
 	return (
 		<div className="flex min-w-0 w-full justify-end">
-			<div className="w-fit min-w-0 max-w-full rounded-md bg-muted px-3 py-2.5 text-sm leading-5 sm:max-w-[620px] sm:px-3.5 sm:py-3">
-				<p className="wrap-break-word">{message}</p>
+			<div className="flex w-fit min-w-0 max-w-full flex-col gap-2 rounded-md bg-muted px-3 py-2.5 text-sm leading-5 sm:max-w-[620px] sm:px-3.5 sm:py-3">
+				{submission.commandType === "CREATE_AGENT" ? (
+					<div className="flex flex-wrap gap-1">
+						<ChatCommandChip label="Create agent" icon={Application} />
+					</div>
+				) : null}
+				<p className="wrap-break-word">{text}</p>
+				{message.resources.length > 0 || message.attachments.length > 0 ? (
+					<div className="flex flex-wrap gap-1 pt-1">
+						{message.resources.map((resource) => (
+							<ChatReferenceChip
+								key={`${resource.kind}:${resource.id}`}
+								resource={resource}
+								icon={RESOURCE_ICONS[resource.kind]}
+							/>
+						))}
+						{message.attachments.map((attachment) => (
+							<ChatAttachmentChip
+								key={`${attachment.name}:${attachment.size}`}
+								attachment={attachment}
+							/>
+						))}
+					</div>
+				) : null}
 				{failed ? (
 					<p className="mt-2 text-destructive text-xs">
 						{error ?? "This message could not be sent."}
@@ -531,36 +587,42 @@ function ResponseActions({
 function BuildingAgentCard({
 	conversationId,
 	sessionId,
-	eventCount,
+	artifacts,
 }: {
 	conversationId: string;
 	sessionId: string | null;
-	eventCount: number;
+	artifacts: Conversation["builderArtifacts"];
 }) {
-	const completed = Math.min(
-		3,
-		sessionId ? Math.max(1, Math.floor(eventCount / 4)) : 0,
-	);
+	const paths = new Set(artifacts.map((artifact) => artifact.path));
+	const completed = paths.has("agent/README.md")
+		? 4
+		: paths.has("agent/manifest.json")
+			? 3
+			: paths.has("agent/instructions.md")
+				? 2
+				: sessionId
+					? 1
+					: 0;
 	const steps = [
 		{
-			id: "data-model",
-			label: "Read the CRM data model",
-			meta: "Companies · contacts · deals",
+			id: "context",
+			label: "Inspect the requested scope",
+			meta: "CRM records and connected sources",
 		},
 		{
-			id: "records",
-			label: "Resolved the requested records",
-			meta: "Scoped to this workspace",
+			id: "instructions",
+			label: "Write the agent instructions",
+			meta: "Trigger, boundaries, and stopping rules",
 		},
 		{
-			id: "integrations",
-			label: "Checked connected integrations",
-			meta: "Only available connections",
+			id: "manifest",
+			label: "Define the agent manifest",
+			meta: "Data scope and allowed actions",
 		},
 		{
-			id: "sandbox",
-			label: "Preparing the agent",
-			meta: "Isolated Vercel Sandbox",
+			id: "review",
+			label: "Prepare the private draft",
+			meta: "Saved for your review",
 		},
 	] as const;
 	const stop = useAsyncAction({
@@ -702,7 +764,7 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 						queryKey: trpc.agents.list.pathKey(),
 					}),
 				]);
-				toast.success("Agent created for the team.");
+				toast.success("Agent deployed to the team.");
 			},
 			onError: (error) => toast.error(error.message),
 		}),
@@ -713,8 +775,8 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 	return (
 		<div className="flex flex-col gap-5">
 			<p className="max-w-[640px] text-pretty text-sm leading-5">
-				I’ve drafted the agent. Review its scope before I create and deploy it
-				for the team.
+				I’ve drafted the agent. Its files and configuration stay private to you
+				until you deploy it.
 			</p>
 			<div className="overflow-hidden rounded-lg border bg-card">
 				<div className="border-b px-4 py-3 sm:px-5 sm:py-4">
@@ -733,7 +795,7 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 				</p>
 				<div className="flex min-h-14 flex-col items-stretch gap-3 border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-4 sm:px-5">
 					<p className="text-pretty text-muted-foreground text-xs">
-						Creating this makes the agent available to everyone in Comp AI.
+						Deploying makes this agent available to the whole team.
 					</p>
 					<div className="flex flex-wrap justify-end gap-1 sm:shrink-0">
 						<Button
@@ -769,11 +831,11 @@ function ReviewAgentCard({ conversation }: { conversation: Conversation }) {
 												? "success"
 												: "idle"
 								}
-								pendingLabel="Creating"
-								successLabel="Created"
+								pendingLabel="Deploying"
+								successLabel="Deployed"
 								errorLabel="Try again"
 							>
-								Create agent
+								Deploy agent
 							</AsyncButtonContent>
 						</Button>
 					</div>
@@ -962,13 +1024,24 @@ function ChatLoading() {
 	);
 }
 
-function submissionText(message: unknown): string {
-	if (!message || typeof message !== "object" || !("text" in message)) {
-		return "Message unavailable";
-	}
-	return typeof message.text === "string"
-		? message.text
-		: "Message unavailable";
+const RESOURCE_ICONS = {
+	integration: Application,
+	company: Building,
+	contact: User,
+	deal: Partnership,
+} as const;
+
+function builderMessageOf(message: unknown) {
+	const row = recordOf(message);
+	return {
+		text: typeof row.text === "string" ? row.text : "Message unavailable",
+		resources: Array.isArray(row.resources)
+			? (row.resources as BuilderPrompt["resources"])
+			: [],
+		attachments: Array.isArray(row.attachments)
+			? (row.attachments as BuilderPrompt["attachments"])
+			: [],
+	};
 }
 
 function retryPromptOf(
diff --git a/apps/app/components/agent-builder/agent-builder-home.tsx b/apps/app/components/agent-builder/agent-builder-home.tsx
index bcaaddda..beaa8d84 100644
--- a/apps/app/components/agent-builder/agent-builder-home.tsx
+++ b/apps/app/components/agent-builder/agent-builder-home.tsx
@@ -62,8 +62,8 @@ export function AgentBuilderHome({ name }: { name: string }) {
 					onSubmit={submit}
 				/>
 				<p className="flex h-8 items-center px-px text-muted-foreground text-xs">
-					Chats stay private to you. Agents you create are available to the
-					whole team.
+					Chats and agent drafts stay private to you. Deploying an agent makes
+					it available to the whole team.
 				</p>
 
 				<div className="pt-1">
diff --git a/apps/app/components/agent-builder/agent-builder-shell.tsx b/apps/app/components/agent-builder/agent-builder-shell.tsx
index 5be2d8fd..280c0119 100644
--- a/apps/app/components/agent-builder/agent-builder-shell.tsx
+++ b/apps/app/components/agent-builder/agent-builder-shell.tsx
@@ -1,10 +1,29 @@
+import { Skeleton } from "@crm/ui/components/skeleton";
+import { Suspense } from "react";
 import { AgentBuilderSidebar } from "./agent-builder-sidebar";
 
 export function AgentBuilderShell({ children }: { children: React.ReactNode }) {
 	return (
 		<div className="flex min-h-0 min-w-0 flex-1">
-			<AgentBuilderSidebar className="hidden w-[213px] flex-none border-r md:flex" />
+			<Suspense fallback={<AgentBuilderSidebarFallback />}>
+				<AgentBuilderSidebar className="hidden w-[213px] flex-none border-r md:flex" />
+			</Suspense>
 			<div className="flex min-w-0 flex-1 flex-col">{children}</div>
 		</div>
 	);
 }
+
+function AgentBuilderSidebarFallback() {
+	return (
+		<aside className="hidden w-[213px] flex-none flex-col border-r p-4 md:flex">
+			<div className="flex h-7 items-center pl-2 font-medium text-xs">
+				Chats
+			</div>
+			<div className="mt-3 space-y-2 px-2" aria-hidden="true">
+				<Skeleton className="h-2.5 w-16" />
+				<Skeleton className="h-7 w-full" />
+				<Skeleton className="h-7 w-full" />
+			</div>
+		</aside>
+	);
+}
diff --git a/apps/app/components/agent-builder/agent-builder-sidebar.tsx b/apps/app/components/agent-builder/agent-builder-sidebar.tsx
index 585bdc14..51637c90 100644
--- a/apps/app/components/agent-builder/agent-builder-sidebar.tsx
+++ b/apps/app/components/agent-builder/agent-builder-sidebar.tsx
@@ -13,6 +13,7 @@ import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { useTRPC } from "@/lib/trpc/client";
 import type { RouterOutputs } from "@/lib/trpc/types";
+import { useHydrated } from "@/lib/use-hydrated";
 import { useWorkspaceUrl } from "@/lib/use-workspace-url";
 
 type Conversation = RouterOutputs["conversations"]["builderList"][number];
@@ -29,6 +30,7 @@ export function AgentBuilderSidebar({
 	const workspaceUrl = useWorkspaceUrl();
 	const trpc = useTRPC();
 	const queryClient = useQueryClient();
+	const hydrated = useHydrated();
 	const conversations = useQuery({
 		...trpc.conversations.builderList.queryOptions(),
 		refetchInterval: 5000,
@@ -46,8 +48,8 @@ export function AgentBuilderSidebar({
 		}),
 	);
 
-	const groups = groupConversations(conversations.data ?? []);
-	const teamAgents = agents.data ?? [];
+	const groups = groupConversations(hydrated ? (conversations.data ?? []) : []);
+	const teamAgents = hydrated ? (agents.data ?? []) : [];
 
 	return (
 		<aside className={cn("min-h-0 min-w-0 flex-col p-4 font-sans", className)}>
@@ -55,7 +57,7 @@ export function AgentBuilderSidebar({
 				<span className="font-medium text-xs">Chats</span>
 				<Button asChild variant="ghost" size="icon-xs">
 					<Link
-						href={workspaceUrl("/agents")}
+						href={workspaceUrl("/chat")}
 						aria-label="New agent chat"
 						onClick={onNavigate}
 					>
@@ -102,7 +104,7 @@ export function AgentBuilderSidebar({
 					</div>
 				))}
 
-				{conversations.isSuccess && groups.length === 0 ? (
+				{groups.length === 0 ? (
 					<p className="px-2 py-3 text-muted-foreground text-xs">
 						No chats in the last 7 days.
 					</p>
@@ -132,7 +134,7 @@ function TeamAgents({
 	return (
 		<div className="mt-3 border-t pt-1">
 			<Link
-				href={workspaceUrl("/agents/team")}
+				href={workspaceUrl("/agents")}
 				onClick={onNavigate}
 				className="flex h-8 items-end gap-2 rounded-sm px-2 pb-1 font-medium text-[11px] text-muted-foreground uppercase tracking-[0.08em] outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/60"
 			>
diff --git a/apps/app/components/agent-builder/agent-code-workspace.tsx b/apps/app/components/agent-builder/agent-code-workspace.tsx
new file mode 100644
index 00000000..23273ffa
--- /dev/null
+++ b/apps/app/components/agent-builder/agent-code-workspace.tsx
@@ -0,0 +1,194 @@
+"use client";
+
+import Checkmark from "@carbon/icons-react/es/Checkmark";
+import Renew from "@carbon/icons-react/es/Renew";
+import { Button } from "@crm/ui/components/button";
+import { Icon } from "@crm/ui/components/icon";
+import { File, MultiFileDiff } from "@pierre/diffs/react";
+import {
+	FileTree,
+	useFileTree,
+	useFileTreeSelection,
+} from "@pierre/trees/react";
+import { useState } from "react";
+
+export type AgentCodeArtifact = {
+	id: string;
+	versionId: string | null;
+	path: string;
+	language: string;
+	content: string;
+	previousContent: string | null;
+	revision: number;
+	status: "WRITING" | "READY";
+	createdAt: string;
+};
+
+export function AgentCodeWorkspace({
+	artifacts,
+	working,
+}: {
+	artifacts: AgentCodeArtifact[];
+	working: boolean;
+}) {
+	const latest = latestArtifacts(artifacts);
+	const paths = [...latest.keys()].sort();
+
+	return (
+		<AgentCodeWorkspaceSurface
+			key={paths.join("|")}
+			artifacts={artifacts}
+			latest={latest}
+			paths={paths}
+			working={working}
+		/>
+	);
+}
+
+function AgentCodeWorkspaceSurface({
+	artifacts,
+	latest,
+	paths,
+	working,
+}: {
+	artifacts: AgentCodeArtifact[];
+	latest: Map<string, AgentCodeArtifact>;
+	paths: string[];
+	working: boolean;
+}) {
+	const [mode, setMode] = useState<"code" | "changes">("code");
+	const { model } = useFileTree({
+		paths,
+		initialExpansion: "open",
+		initialSelectedPaths: paths[0] ? [paths[0]] : [],
+		gitStatus: paths.map((path) => ({
+			path,
+			status: latest.get(path)?.status === "READY" ? "added" : "modified",
+		})),
+	});
+	const selection = useFileTreeSelection(model);
+	const selectedPath =
+		selection.find((path) => latest.has(path)) ?? paths[0] ?? null;
+	const artifact = selectedPath ? latest.get(selectedPath) : null;
+	const revisions = artifact
+		? artifacts.filter((item) => item.path === artifact.path)
+		: [];
+	const previous = artifact?.previousContent ?? null;
+	const showChanges = mode === "changes" && previous !== null;
+
+	if (!artifact) return null;
+
+	const file = {
+		name: artifact.path,
+		contents: artifact.content,
+		lang: artifact.language,
+		cacheKey: artifact.id,
+	};
+
+	return (
+		<section
+			aria-label="Generated agent files"
+			className="overflow-hidden rounded-lg border bg-card"
+		>
+			<header className="flex min-h-11 flex-wrap items-center gap-2 border-b px-3 py-2 sm:px-4">
+				<span className="flex min-w-0 flex-1 items-center gap-2">
+					<Icon
+						icon={working ? Renew : Checkmark}
+						className={
+							working ? "size-3.5 animate-spin text-ring" : "size-3.5 text-ring"
+						}
+						motion="none"
+					/>
+					<span className="truncate font-medium text-sm">
+						{working ? "Writing agent files" : "Agent files"}
+					</span>
+					<span className="shrink-0 font-mono text-muted-foreground text-xs">
+						{paths.length}/3
+					</span>
+				</span>
+				<fieldset
+					className="flex min-w-0 items-center gap-1 border-0 p-0"
+					aria-label="Code view"
+				>
+					<Button
+						variant={mode === "code" ? "secondary" : "ghost"}
+						size="xs"
+						onClick={() => setMode("code")}
+					>
+						Code
+					</Button>
+					<Button
+						variant={mode === "changes" ? "secondary" : "ghost"}
+						size="xs"
+						disabled={previous === null}
+						onClick={() => setMode("changes")}
+					>
+						Changes
+					</Button>
+				</fieldset>
+			</header>
+
+			<div className="grid min-h-0 md:grid-cols-[190px_minmax(0,1fr)]">
+				<div className="h-40 min-w-0 border-b bg-muted/20 p-2 md:h-[360px] md:border-r md:border-b-0">
+					<FileTree
+						model={model}
+						aria-label="Agent files"
+						style={{ height: "100%", width: "100%" }}
+					/>
+				</div>
+				<div className="min-w-0 overflow-auto bg-background md:h-[360px]">
+					<div className="flex h-8 items-center gap-2 border-b px-3 text-xs">
+						<span className="min-w-0 flex-1 truncate font-mono">
+							{artifact.path}
+						</span>
+						<span className="shrink-0 text-muted-foreground">
+							revision {artifact.revision}
+						</span>
+						<span className="sr-only" aria-live="polite">
+							{artifact.status === "READY" ? "Ready" : "Writing"}
+						</span>
+					</div>
+					{showChanges ? (
+						<MultiFileDiff
+							oldFile={{
+								name: artifact.path,
+								contents: previous,
+								lang: artifact.language,
+								cacheKey: `${artifact.id}:previous`,
+							}}
+							newFile={file}
+							options={{
+								diffStyle: "unified",
+								overflow: "wrap",
+								themeType: "system",
+							}}
+							disableWorkerPool
+						/>
+					) : (
+						<File
+							file={file}
+							options={{ overflow: "wrap", themeType: "system" }}
+							disableWorkerPool
+						/>
+					)}
+				</div>
+			</div>
+			<footer className="border-t px-3 py-2 text-muted-foreground text-xs sm:px-4">
+				{working
+					? "Files are saved as the builder works. You can leave and come back without losing progress."
+					: `${revisions.length} saved ${revisions.length === 1 ? "revision" : "revisions"} for this file.`}
+			</footer>
+		</section>
+	);
+}
+
+function latestArtifacts(artifacts: AgentCodeArtifact[]) {
+	const latest = new Map<string, AgentCodeArtifact>();
+	for (const artifact of artifacts) {
+		const current = latest.get(artifact.path);
+		if (!current || artifact.revision > current.revision) {
+			latest.set(artifact.path, artifact);
+		}
+	}
+	return latest;
+}
diff --git a/apps/app/components/agent-builder/agent-composer.tsx b/apps/app/components/agent-builder/agent-composer.tsx
index 6b2ce01a..d79aa4bd 100644
--- a/apps/app/components/agent-builder/agent-composer.tsx
+++ b/apps/app/components/agent-builder/agent-composer.tsx
@@ -6,8 +6,6 @@ import ArrowUp from "@carbon/icons-react/es/ArrowUp";
 import AttachmentIcon from "@carbon/icons-react/es/Attachment";
 import Building from "@carbon/icons-react/es/Building";
 import Calendar from "@carbon/icons-react/es/Calendar";
-import Close from "@carbon/icons-react/es/Close";
-import Document from "@carbon/icons-react/es/Document";
 import Email from "@carbon/icons-react/es/Email";
 import Partnership from "@carbon/icons-react/es/Partnership";
 import Search from "@carbon/icons-react/es/Search";
@@ -30,19 +28,21 @@ import { toast } from "sonner";
 import {
 	type BuilderCommandType,
 	builderCommandType,
+	consumeBuilderCommand,
 } from "@/lib/agent-builder";
 import { useTRPC } from "@/lib/trpc/client";
+import {
+	ChatAttachmentChip,
+	type ChatChipAttachment,
+	type ChatChipResource,
+	ChatCommandChip,
+	ChatReferenceChip,
+	ChatReferenceIdentity,
+} from "./chat-chips";
 
-export type BuilderResource = {
-	kind: "integration" | "company" | "contact" | "deal";
-	id: string;
-	label: string;
-};
+export type BuilderResource = ChatChipResource;
 
-export type BuilderAttachment = {
-	name: string;
-	type: string;
-	size: number;
+export type BuilderAttachment = ChatChipAttachment & {
 	contentBase64: string;
 };
 
@@ -53,6 +53,13 @@ export type BuilderPrompt = {
 	attachments: BuilderAttachment[];
 };
 
+const CREATE_AGENT_COMMAND = {
+	commandType: "CREATE_AGENT" as const,
+	invocation: "/Create agent",
+	label: "Create agent",
+	description: "Build a durable team automation",
+};
+
 export function AgentComposer({
 	mode,
 	disabled = false,
@@ -68,7 +75,12 @@ export function AgentComposer({
 }) {
 	const trpc = useTRPC();
 	const fileInput = useRef<HTMLInputElement>(null);
-	const [draft, setDraft] = useState(initialPrompt);
+	const initialCommand = consumeBuilderCommand(initialPrompt);
+	const [draft, setDraft] = useState(initialCommand?.body ?? initialPrompt);
+	const [command, setCommand] = useState<typeof CREATE_AGENT_COMMAND | null>(
+		initialCommand ? CREATE_AGENT_COMMAND : null,
+	);
+	const [commandOpen, setCommandOpen] = useState(false);
 	const [resourceQuery, setResourceQuery] = useState("");
 	const [resources, setResources] = useState<BuilderResource[]>([]);
 	const [attachments, setAttachments] = useState<BuilderAttachment[]>([]);
@@ -80,14 +92,17 @@ export function AgentComposer({
 
 	const submit = () => {
 		if (!canSend) return;
-		const message = draft.trim();
+		const body = draft.trim();
+		const message = command ? `${command.invocation} ${body}` : body;
 		onSubmit({
-			commandType: builderCommandType(message),
+			commandType: command?.commandType ?? builderCommandType(message),
 			message,
 			resources,
 			attachments,
 		});
 		setDraft("");
+		setCommand(null);
+		setCommandOpen(false);
 		setResources([]);
 		setAttachments([]);
 	};
@@ -105,6 +120,18 @@ export function AgentComposer({
 	const connectedGoogle = (google.data?.sources ?? []).filter(
 		(source) => source.connected,
 	);
+	const updateDraft = (value: string) => {
+		const parsed = consumeBuilderCommand(value);
+		if (parsed) {
+			setCommand(CREATE_AGENT_COMMAND);
+			setDraft(parsed.body);
+			setCommandOpen(false);
+			return;
+		}
+
+		setDraft(value);
+		setCommandOpen(!command && value.trimStart().startsWith("/"));
+	};
 
 	return (
 		<div
@@ -113,12 +140,19 @@ export function AgentComposer({
 				mode === "home" ? "min-h-24" : "min-h-[78px]",
 			)}
 		>
-			{resources.length > 0 || attachments.length > 0 ? (
+			{command || resources.length > 0 || attachments.length > 0 ? (
 				<div className="flex flex-wrap gap-1 px-1 pb-1">
+					{command ? (
+						<ChatCommandChip
+							label={command.label}
+							icon={Application}
+							onRemove={() => setCommand(null)}
+						/>
+					) : null}
 					{resources.map((resource) => (
-						<ComposerChip
+						<ChatReferenceChip
 							key={`${resource.kind}:${resource.id}`}
-							label={resource.label}
+							resource={resource}
 							icon={RESOURCE_ICONS[resource.kind]}
 							onRemove={() =>
 								setResources((current) =>
@@ -131,10 +165,9 @@ export function AgentComposer({
 						/>
 					))}
 					{attachments.map((attachment) => (
-						<ComposerChip
+						<ChatAttachmentChip
 							key={`${attachment.name}:${attachment.size}`}
-							label={attachment.name}
-							icon={Document}
+							attachment={attachment}
 							onRemove={() =>
 								setAttachments((current) =>
 									current.filter((item) => item !== attachment),
@@ -147,7 +180,7 @@ export function AgentComposer({
 
 			<textarea
 				value={draft}
-				onChange={(event) => setDraft(event.target.value)}
+				onChange={(event) => updateDraft(event.target.value)}
 				onKeyDown={(event) => {
 					if (event.key === "Enter" && !event.shiftKey) {
 						event.preventDefault();
@@ -214,6 +247,8 @@ export function AgentComposer({
 													source.source === "calendar"
 														? "Google Calendar"
 														: "Gmail",
+												detail: "Connected integration",
+												imageUrl: null,
 											})
 										}
 									/>
@@ -229,6 +264,7 @@ export function AgentComposer({
 											icon={RESOURCE_ICONS[resource.kind]}
 											label={resource.label}
 											detail={resource.detail ?? RESOURCE_LABELS[resource.kind]}
+											imageUrl={resource.imageUrl}
 											onSelect={() => addResource(resource)}
 										/>
 									))}
@@ -263,7 +299,7 @@ export function AgentComposer({
 						<Icon icon={AttachmentIcon} />
 					</Button>
 
-					<Popover>
+					<Popover open={commandOpen} onOpenChange={setCommandOpen}>
 						<PopoverTrigger asChild>
 							<Button
 								variant="ghost"
@@ -282,13 +318,13 @@ export function AgentComposer({
 						>
 							<button
 								type="button"
-								onClick={() =>
+								onClick={() => {
+									setCommand(CREATE_AGENT_COMMAND);
 									setDraft((current) =>
-										current.startsWith("/Create agent")
-											? current
-											: `/Create agent ${current}`,
-									)
-								}
+										current.trimStart().startsWith("/") ? "" : current,
+									);
+									setCommandOpen(false);
+								}}
 								className="flex w-full items-center gap-3 rounded-sm px-3 py-2 text-left outline-none hover:bg-muted focus-visible:bg-muted"
 							>
 								<Icon
@@ -297,10 +333,10 @@ export function AgentComposer({
 								/>
 								<span>
 									<span className="block font-medium text-xs">
-										/Create agent
+										/{CREATE_AGENT_COMMAND.label}
 									</span>
 									<span className="block text-muted-foreground text-xs">
-										Build a durable team automation
+										{CREATE_AGENT_COMMAND.description}
 									</span>
 								</span>
 							</button>
@@ -361,40 +397,17 @@ const RESOURCE_LABELS: Record<BuilderResource["kind"], string> = {
 	deal: "Deal",
 };
 
-function ComposerChip({
-	label,
-	icon,
-	onRemove,
-}: {
-	label: string;
-	icon: CarbonIcon;
-	onRemove: () => void;
-}) {
-	return (
-		<span className="flex h-6 max-w-full items-center gap-1 rounded-full bg-foreground px-2 text-background text-xs sm:max-w-56">
-			<Icon icon={icon} className="size-3.5 shrink-0" />
-			<span className="truncate font-medium">{label}</span>
-			<button
-				type="button"
-				aria-label={`Remove ${label}`}
-				onClick={onRemove}
-				className="-mr-1 flex size-4 items-center justify-center rounded-full outline-none hover:bg-background/15 focus-visible:ring-2 focus-visible:ring-background/60"
-			>
-				<Icon icon={Close} className="size-3" />
-			</button>
-		</span>
-	);
-}
-
 function ResourceButton({
 	icon,
 	label,
 	detail,
+	imageUrl,
 	onSelect,
 }: {
 	icon: CarbonIcon;
 	label: string;
 	detail: string | null;
+	imageUrl?: string | null;
 	onSelect: () => void;
 }) {
 	return (
@@ -403,15 +416,16 @@ function ResourceButton({
 			onClick={onSelect}
 			className="flex w-full items-center gap-3 rounded-sm px-3 py-2 text-left outline-none hover:bg-muted focus-visible:bg-muted"
 		>
-			<span className="flex size-6 shrink-0 items-center justify-center text-muted-foreground">
-				<Icon icon={icon} className="size-4" />
-			</span>
-			<span className="min-w-0 flex-1">
-				<span className="block truncate font-medium text-xs">{label}</span>
-				<span className="block truncate text-muted-foreground text-xs">
-					{detail}
-				</span>
-			</span>
+			<ChatReferenceIdentity
+				resource={{
+					kind: "integration",
+					id: label,
+					label,
+					detail,
+					imageUrl,
+				}}
+				icon={icon}
+			/>
 		</button>
 	);
 }
diff --git a/apps/app/components/agent-builder/chat-chips.tsx b/apps/app/components/agent-builder/chat-chips.tsx
new file mode 100644
index 00000000..8e4f8be7
--- /dev/null
+++ b/apps/app/components/agent-builder/chat-chips.tsx
@@ -0,0 +1,158 @@
+import Close from "@carbon/icons-react/es/Close";
+import Document from "@carbon/icons-react/es/Document";
+import { Avatar, AvatarFallback, AvatarImage } from "@crm/ui/components/avatar";
+import { type CarbonIcon, Icon } from "@crm/ui/components/icon";
+import Image from "next/image";
+
+export type ChatChipResource = {
+	kind: "integration" | "company" | "contact" | "deal";
+	id: string;
+	label: string;
+	detail?: string | null;
+	imageUrl?: string | null;
+};
+
+export type ChatChipAttachment = {
+	name: string;
+	type: string;
+	size: number;
+	contentBase64?: string;
+};
+
+export function ChatReferenceChip({
+	resource,
+	icon,
+	onRemove,
+}: {
+	resource: ChatChipResource;
+	icon: CarbonIcon;
+	onRemove?: () => void;
+}) {
+	return (
+		<span className="flex min-w-0 max-w-full items-center gap-2 rounded-md border bg-background py-1 pr-2 pl-1 text-left shadow-xs">
+			<ChatReferenceIdentity resource={resource} icon={icon} />
+			{onRemove ? (
+				<button
+					type="button"
+					aria-label={`Remove ${resource.label}`}
+					onClick={onRemove}
+					className="flex size-6 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/60"
+				>
+					<Icon icon={Close} className="size-3" />
+				</button>
+			) : null}
+		</span>
+	);
+}
+
+export function ChatReferenceIdentity({
+	resource,
+	icon,
+}: {
+	resource: ChatChipResource;
+	icon: CarbonIcon;
+}) {
+	return (
+		<>
+			<Avatar size="sm">
+				{resource.imageUrl ? (
+					<AvatarImage src={resource.imageUrl} alt="" />
+				) : null}
+				<AvatarFallback>
+					<Icon icon={icon} className="size-3" />
+				</AvatarFallback>
+			</Avatar>
+			<span className="min-w-0 max-w-48">
+				<span className="block truncate font-medium text-xs">
+					{resource.label}
+				</span>
+				{resource.detail ? (
+					<span className="block truncate text-[11px] text-muted-foreground">
+						{resource.detail}
+					</span>
+				) : null}
+			</span>
+		</>
+	);
+}
+
+export function ChatAttachmentChip({
+	attachment,
+	onRemove,
+}: {
+	attachment: ChatChipAttachment;
+	onRemove?: () => void;
+}) {
+	const image =
+		attachment.type.startsWith("image/") && attachment.contentBase64;
+
+	return (
+		<span className="flex min-w-0 max-w-full items-center gap-2 rounded-md border bg-background py-1 pr-2 pl-1 text-left shadow-xs">
+			<span className="flex size-6 shrink-0 items-center justify-center overflow-hidden rounded-sm bg-muted text-muted-foreground">
+				{image ? (
+					<Image
+						src={`data:${attachment.type};base64,${attachment.contentBase64}`}
+						alt=""
+						width={24}
+						height={24}
+						unoptimized
+						className="size-full object-cover"
+					/>
+				) : (
+					<Icon icon={Document} className="size-3.5" />
+				)}
+			</span>
+			<span className="min-w-0 max-w-48">
+				<span className="block truncate font-medium text-xs">
+					{attachment.name}
+				</span>
+				<span className="block text-[11px] text-muted-foreground">
+					{formatBytes(attachment.size)}
+				</span>
+			</span>
+			{onRemove ? (
+				<button
+					type="button"
+					aria-label={`Remove ${attachment.name}`}
+					onClick={onRemove}
+					className="flex size-6 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/60"
+				>
+					<Icon icon={Close} className="size-3" />
+				</button>
+			) : null}
+		</span>
+	);
+}
+
+export function ChatCommandChip({
+	label,
+	icon,
+	onRemove,
+}: {
+	label: string;
+	icon: CarbonIcon;
+	onRemove?: () => void;
+}) {
+	return (
+		<span className="flex h-7 items-center gap-1.5 rounded-md bg-primary px-2 text-primary-foreground text-xs">
+			<Icon icon={icon} className="size-3.5" />
+			<span className="font-medium">{label}</span>
+			{onRemove ? (
+				<button
+					type="button"
+					aria-label={`Remove ${label}`}
+					onClick={onRemove}
+					className="-mr-1 flex size-5 items-center justify-center rounded-sm outline-none hover:bg-primary-foreground/15 focus-visible:ring-2 focus-visible:ring-primary-foreground/60"
+				>
+					<Icon icon={Close} className="size-3" />
+				</button>
+			) : null}
+		</span>
+	);
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
diff --git a/apps/app/components/agent-builder/team-agents-index.tsx b/apps/app/components/agent-builder/team-agents-index.tsx
index c4c50e48..ae4b767b 100644
--- a/apps/app/components/agent-builder/team-agents-index.tsx
+++ b/apps/app/components/agent-builder/team-agents-index.tsx
@@ -3,15 +3,19 @@
 import ArrowRight from "@carbon/icons-react/es/ArrowRight";
 import Bot from "@carbon/icons-react/es/Bot";
 import { Icon } from "@crm/ui/components/icon";
+import { Skeleton } from "@crm/ui/components/skeleton";
 import { useQuery } from "@tanstack/react-query";
 import Link from "next/link";
 import { useTRPC } from "@/lib/trpc/client";
+import { useHydrated } from "@/lib/use-hydrated";
 import { useWorkspaceUrl } from "@/lib/use-workspace-url";
 
 export function TeamAgentsIndex() {
 	const trpc = useTRPC();
 	const workspaceUrl = useWorkspaceUrl();
 	const agents = useQuery(trpc.agents.list.queryOptions());
+	const hydrated = useHydrated();
+	const rows = hydrated ? agents.data : undefined;
 
 	return (
 		<main className="min-h-0 min-w-0 flex-1 overflow-y-auto px-4 py-6 sm:px-6 sm:py-10">
@@ -25,9 +29,11 @@ export function TeamAgentsIndex() {
 					</p>
 				</div>
 
-				{agents.data?.length ? (
+				{rows === undefined ? (
+					<AgentListFallback />
+				) : rows.length ? (
 					<div className="overflow-hidden rounded-lg border bg-card">
-						{agents.data.map((agent) => (
+						{rows.map((agent) => (
 							<Link
 								key={agent.id}
 								href={workspaceUrl(`/agents/${agent.id}`)}
@@ -72,10 +78,10 @@ export function TeamAgentsIndex() {
 							deploy.
 						</p>
 						<Link
-							href={workspaceUrl("/agents")}
+							href={workspaceUrl("/chat")}
 							className="mt-4 text-primary text-xs hover:underline"
 						>
-							Open the agent builder
+							Open chat
 						</Link>
 					</div>
 				)}
@@ -83,3 +89,25 @@ export function TeamAgentsIndex() {
 		</main>
 	);
 }
+
+function AgentListFallback() {
+	return (
+		<div
+			className="overflow-hidden rounded-lg border bg-card"
+			aria-hidden="true"
+		>
+			{[0, 1].map((row) => (
+				<div
+					key={row}
+					className="flex min-h-16 items-center gap-4 border-t px-5 py-3 first:border-t-0"
+				>
+					<Skeleton className="size-8 shrink-0 rounded-md" />
+					<span className="min-w-0 flex-1 space-y-2">
+						<Skeleton className="h-3 w-32" />
+						<Skeleton className="h-2.5 w-full max-w-96" />
+					</span>
+				</div>
+			))}
+		</div>
+	);
+}
diff --git a/apps/app/components/app-icon-rail.tsx b/apps/app/components/app-icon-rail.tsx
index 2f507ca4..e56ee8f0 100644
--- a/apps/app/components/app-icon-rail.tsx
+++ b/apps/app/components/app-icon-rail.tsx
@@ -49,11 +49,11 @@ const ITEMS: RailItem[] = [
 	},
 	{ title: "Deals", href: "/deals", icon: Partnership, match: "prefix" },
 	{
-		title: "Agents",
-		href: "/agents",
+		title: "Chat",
+		href: "/chat",
 		icon: Bot,
 		match: "prefix",
-		related: ["/agent", "/chat"],
+		related: ["/agent", "/agents"],
 	},
 	{ title: "Settings", href: "/settings", icon: Settings, match: "prefix" },
 ];
@@ -135,7 +135,7 @@ function MobileRailLink({
 				aria-current={active ? "page" : undefined}
 				onClick={onNavigate}
 				transitionTypes={[
-					item.title === "Agents" ? "nav-forward" : "nav-lateral",
+					item.title === "Chat" ? "nav-forward" : "nav-lateral",
 				]}
 			>
 				<Icon icon={item.icon} />
@@ -221,8 +221,8 @@ export function AppIconRail() {
 			})),
 		[workspaceUrl],
 	);
-	const inAgents = items.some(
-		(item) => item.title === "Agents" && isActive(item, pathname),
+	const inChat = items.some(
+		(item) => item.title === "Chat" && isActive(item, pathname),
 	);
 
 	return (
@@ -242,7 +242,7 @@ export function AppIconRail() {
 			</nav>
 
 			<Sheet open={open} onOpenChange={setOpen}>
-				{inAgents ? (
+				{inChat ? (
 					<SheetContent
 						side="left"
 						showCloseButton={false}
diff --git a/apps/app/lib/agent-builder.ts b/apps/app/lib/agent-builder.ts
index 1e2977c8..00fe5120 100644
--- a/apps/app/lib/agent-builder.ts
+++ b/apps/app/lib/agent-builder.ts
@@ -1,9 +1,22 @@
 export type BuilderCommandType = "CHAT" | "CREATE_AGENT";
 
+const CREATE_AGENT = /^\/create(?:\s+agent|-agent)(?:\s|$)/i;
+
 export function builderCommandType(message: string): BuilderCommandType {
-	return /^\/create\s+agent(?:\s|$)/i.test(message.trimStart())
-		? "CREATE_AGENT"
-		: "CHAT";
+	return CREATE_AGENT.test(message.trimStart()) ? "CREATE_AGENT" : "CHAT";
+}
+
+export function consumeBuilderCommand(
+	message: string,
+): { commandType: BuilderCommandType; body: string } | null {
+	const trimmed = message.trimStart();
+	const match = CREATE_AGENT.exec(trimmed);
+	if (!match) return null;
+
+	return {
+		commandType: "CREATE_AGENT",
+		body: trimmed.slice(match[0].length).trimStart(),
+	};
 }
 
 export function hasCreateAgentCommand(
diff --git a/apps/app/lib/use-hydrated.ts b/apps/app/lib/use-hydrated.ts
new file mode 100644
index 00000000..06392591
--- /dev/null
+++ b/apps/app/lib/use-hydrated.ts
@@ -0,0 +1,19 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+export function useHydrated() {
+	return useSyncExternalStore(subscribe, clientSnapshot, serverSnapshot);
+}
+
+function subscribe() {
+	return () => undefined;
+}
+
+function clientSnapshot() {
+	return true;
+}
+
+function serverSnapshot() {
+	return false;
+}
diff --git a/apps/app/package.json b/apps/app/package.json
index 8ddaa67f..d29480ac 100644
--- a/apps/app/package.json
+++ b/apps/app/package.json
@@ -17,6 +17,8 @@
 		"@crm/db": "workspace:*",
 		"@crm/env": "workspace:*",
 		"@crm/ui": "workspace:*",
+		"@pierre/diffs": "^1.2.12",
+		"@pierre/trees": "^1.0.0-beta.5",
 		"@tanstack/react-query": "^5.101.2",
 		"@trpc/client": "^11.18.0",
 		"@trpc/server": "^11.18.0",
diff --git a/apps/app/test/agent-builder.spec.ts b/apps/app/test/agent-builder.spec.ts
index 3e412e58..36455a8f 100644
--- a/apps/app/test/agent-builder.spec.ts
+++ b/apps/app/test/agent-builder.spec.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import {
 	builderCommandType,
+	consumeBuilderCommand,
 	hasCreateAgentCommand,
 } from "../lib/agent-builder";
 
@@ -14,6 +15,13 @@ describe("agent builder commands", () => {
 		);
 		expect(builderCommandType("Tell me about this customer")).toBe("CHAT");
 		expect(builderCommandType("/Create agentic workflows")).toBe("CHAT");
+		expect(builderCommandType("/create-agent Flag stalled deals")).toBe(
+			"CREATE_AGENT",
+		);
+		expect(consumeBuilderCommand("/Create agent Flag stalled deals")).toEqual({
+			commandType: "CREATE_AGENT",
+			body: "Flag stalled deals",
+		});
 	});
 
 	it("shows creation surfaces only after a creation command", () => {
diff --git a/bun.lock b/bun.lock
index a5777efb..20737668 100644
--- a/bun.lock
+++ b/bun.lock
@@ -75,6 +75,8 @@
         "@crm/db": "workspace:*",
         "@crm/env": "workspace:*",
         "@crm/ui": "workspace:*",
+        "@pierre/diffs": "^1.2.12",
+        "@pierre/trees": "^1.0.0-beta.5",
         "@tanstack/react-query": "^5.101.2",
         "@trpc/client": "^11.18.0",
         "@trpc/server": "^11.18.0",
@@ -512,6 +514,14 @@
 
     "@paralleldrive/cuid2": ["@paralleldrive/cuid2@2.3.1", "", { "dependencies": { "@noble/hashes": "^1.1.5" } }, "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw=="],
 
+    "@pierre/diffs": ["@pierre/diffs@1.3.3", "", { "dependencies": { "@pierre/theme": "2.0.0", "@pierre/theming": "1.0.0", "@shikijs/transformers": "^3.0.0 || ^4.0.0", "diff": "9.0.0", "hast-util-to-html": "9.0.5", "lru_map": "0.4.1", "shiki": "^3.0.0 || ^4.0.0" }, "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0" } }, "sha512-LPoRv3vkfhrZbdRe/aPhJFjD1XK2JD9ALAdvral6ThG3qAcMDSytGbAXk3WQlt5+AZDOQXflHQwBWhw+89Ttzg=="],
+
+    "@pierre/theme": ["@pierre/theme@2.0.0", "", {}, "sha512-yNDd9GYLQl1mEUJR8AneJ5e4ohLIHQd/wZLWr4fagt78vS2RwwZNW530vVgHqXFAyFVcFlRmGUD5ramXH46OXw=="],
+
+    "@pierre/theming": ["@pierre/theming@1.0.0", "", { "peerDependencies": { "@pierre/theme": "^1.1.0", "@shikijs/themes": "^3.0.0 || ^4.0.0", "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0", "shiki": "^3.0.0 || ^4.0.0" }, "optionalPeers": ["@pierre/theme", "@shikijs/themes", "react", "react-dom", "shiki"] }, "sha512-WsdrnhKfjeyXGDikZmN9pkpeZ5S/cl6EE72feiSc0tlynT1tMYqXqouhuv/foK+PY9OEnebOAVRQn3+rAstR8g=="],
+
+    "@pierre/trees": ["@pierre/trees@1.0.0-beta.6", "", { "dependencies": { "@pierre/theming": "1.0.0", "preact": "11.0.0-beta.0", "preact-render-to-string": "6.6.5" }, "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0" } }, "sha512-zxeuSFM9TveM7b5XofweJALCtm/tGYV9HZzdbf7Uf+kBxIlUyz24/EHaGRjB0dsmmfDQl2ETz7AWwJ15lhSnpw=="],
+
     "@prisma/adapter-pg": ["@prisma/adapter-pg@7.9.1", "", { "dependencies": { "@prisma/driver-adapter-utils": "7.9.1", "@types/pg": "^8.16.0", "pg": "^8.16.3", "postgres-array": "3.0.4" } }, "sha512-Ho2RK1KanQxLNSC0sR5bpiiVep10sWPLXCcxK+KXfI/Q69TMRbiafSvLPv3V9snimX72rMCqGlyJ4sBO4lKTAw=="],
 
     "@prisma/client": ["@prisma/client@7.9.1", "", { "dependencies": { "@prisma/client-runtime-utils": "7.9.1" }, "peerDependencies": { "prisma": "*", "typescript": ">=5.4.0" }, "optionalPeers": ["prisma", "typescript"] }, "sha512-+xgrh2EhJVF79wC0yX5G4PI1Rdcm7Qn/nekNQ+t/O153wtNggruHal+fXHSa0QE+Tp/Cw5wvxeCEhZZ59xGm8Q=="],
@@ -700,6 +710,24 @@
 
     "@shadcn/react": ["@shadcn/react@0.2.1", "", { "peerDependencies": { "@types/react": ">=19", "react": ">=19" }, "optionalPeers": ["@types/react", "react"] }, "sha512-5krgi3dRMKb5jH6a+qPzVJUy/54s0kKE4Rw4LjDfLqOdVQTWKUgxWf1kW8r912I0jX/Lzxqc+pgjkjWxUIK5BQ=="],
 
+    "@shikijs/core": ["@shikijs/core@4.4.2", "", { "dependencies": { "@shikijs/primitive": "4.4.2", "@shikijs/types": "4.4.2", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5", "hast-util-to-html": "^9.0.5" } }, "sha512-StyzbAyxg2/tBGf78gwbBkGyeQ73lf8UiJArFaQhTQIDqQOCKPCQFanvrs4/Yv3Yfyc+ONInJM6K+FMIf+P+kA=="],
+
+    "@shikijs/engine-javascript": ["@shikijs/engine-javascript@4.4.2", "", { "dependencies": { "@shikijs/types": "4.4.2", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.6" } }, "sha512-MnIkeqWdVPUWsxlx8gKLVCJFTsqrQJgpTPBPpQwaFeJ56lOnJxj5aN2LUFnfxUEcvOQuNocmbaMnVrCEln6rkw=="],
+
+    "@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@4.4.2", "", { "dependencies": { "@shikijs/types": "4.4.2", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-GLhowz1+jixjz+wiZ3wMnOn1jTxiFCGl2PkXufivbnwPHKuyw1AYqu5/hbWhZZ2oAb0NP05WUJhYeigY14drnw=="],
+
+    "@shikijs/langs": ["@shikijs/langs@4.4.2", "", { "dependencies": { "@shikijs/types": "4.4.2" } }, "sha512-8DfeusD+Zdv/eYIDdXyJTUnSMHt+aAWjAOCXV20HNGAHRlInXpG8wh421v6B91WOm9TFwRLN+b/LG5F2NAIojg=="],
+
+    "@shikijs/primitive": ["@shikijs/primitive@4.4.2", "", { "dependencies": { "@shikijs/types": "4.4.2", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-l6fQQKsOMlz72n38fztmSgZ76MO6KSWuw8o+GJ+FhmqrpC9pIOJNQNXGgbb5yX2AwpzlEHwsaLPnk/8o4Fm+rA=="],
+
+    "@shikijs/themes": ["@shikijs/themes@4.4.2", "", { "dependencies": { "@shikijs/types": "4.4.2" } }, "sha512-H0CFoL07ddDC2Dd6EdrPYNkRhUR6YCkJlnuYFceYYUJJA5TIm2b5B33qqiDYryBExgbKMndFJPb2u1gTuqO37g=="],
+
+    "@shikijs/transformers": ["@shikijs/transformers@4.4.2", "", { "dependencies": { "@shikijs/core": "4.4.2", "@shikijs/types": "4.4.2" } }, "sha512-d81PJ9KkR1tVP95FH/9296HTtDo0mh76wv10u9T1YmsZq/UcXgt0OLdBszfUQ1i+umkRMCjDnFbFZU7/tCODTQ=="],
+
+    "@shikijs/types": ["@shikijs/types@4.4.2", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-PFYitV4vpDr/iPCIhnHp+Q4ftic5N5VeNJ3KQ1O8gn3h2ar8qgwMAXF7tq4m1CWaMS60fV4VqF6vfnWH4F7vqQ=="],
+
+    "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
+
     "@sindresorhus/merge-streams": ["@sindresorhus/merge-streams@4.0.0", "", {}, "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ=="],
 
     "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
@@ -1450,6 +1478,8 @@
 
     "hast-util-sanitize": ["hast-util-sanitize@5.0.2", "", { "dependencies": { "@types/hast": "^3.0.0", "@ungap/structured-clone": "^1.0.0", "unist-util-position": "^5.0.0" } }, "sha512-3yTWghByc50aGS7JlGhk61SPenfE/p1oaFeNwkOOyrscaOkMGrcW9+Cy/QAIOBpZxP1yqDIzFMR0+Np0i0+usg=="],
 
+    "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
+
     "hast-util-to-jsx-runtime": ["hast-util-to-jsx-runtime@2.3.6", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "hast-util-whitespace": "^3.0.0", "mdast-util-mdx-expression": "^2.0.0", "mdast-util-mdx-jsx": "^3.0.0", "mdast-util-mdxjs-esm": "^2.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "style-to-js": "^1.0.0", "unist-util-position": "^5.0.0", "vfile-message": "^4.0.0" } }, "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg=="],
 
     "hast-util-to-parse5": ["hast-util-to-parse5@8.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "web-namespaces": "^2.0.0", "zwitch": "^2.0.0" } }, "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA=="],
@@ -1636,6 +1666,8 @@
 
     "lru.min": ["lru.min@1.1.4", "", {}, "sha512-DqC6n3QQ77zdFpCMASA1a3Jlb64Hv2N2DciFGkO/4L9+q/IpIAuRlKOvCXabtRW6cQf8usbmM6BE/TOPysCdIA=="],
 
+    "lru_map": ["lru_map@0.4.1", "", {}, "sha512-I+lBvqMMFfqaV8CJCISjI3wbjmwVu/VyOoU7+qtu9d7ioW5klMgsTTiUOUp+DJvfTTzKXoPbyC6YfgkNcyPSOg=="],
+
     "lucide-react": ["lucide-react@1.28.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-fARAFJULsGuDDydjp6+6blekG/sBIM29TerzLjc9bQUKAcEfrSc4ZQKb25KRz4OMKd87cZTb5dgq0w/T6KufVg=="],
 
     "magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ=="],
@@ -1826,6 +1858,10 @@
 
     "onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
 
+    "oniguruma-parser": ["oniguruma-parser@0.12.2", "", {}, "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw=="],
+
+    "oniguruma-to-es": ["oniguruma-to-es@4.3.6", "", { "dependencies": { "oniguruma-parser": "^0.12.2", "regex": "^6.1.0", "regex-recursion": "^6.0.2" } }, "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA=="],
+
     "open": ["open@10.2.0", "", { "dependencies": { "default-browser": "^5.2.1", "define-lazy-prop": "^3.0.0", "is-inside-container": "^1.0.0", "wsl-utils": "^0.1.0" } }, "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA=="],
 
     "ora": ["ora@8.2.0", "", { "dependencies": { "chalk": "^5.3.0", "cli-cursor": "^5.0.0", "cli-spinners": "^2.9.2", "is-interactive": "^2.0.0", "is-unicode-supported": "^2.0.0", "log-symbols": "^6.0.0", "stdin-discarder": "^0.2.2", "string-width": "^7.2.0", "strip-ansi": "^7.1.0" } }, "sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw=="],
@@ -1914,6 +1950,10 @@
 
     "powershell-utils": ["powershell-utils@0.1.0", "", {}, "sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A=="],
 
+    "preact": ["preact@11.0.0-beta.0", "", {}, "sha512-IcODoASASYwJ9kxz7+MJeiJhvLriwSb4y4mHIyxdgaRZp6kPUud7xytrk/6GZw8U3y6EFJaRb5wi9SrEK+8+lg=="],
+
+    "preact-render-to-string": ["preact-render-to-string@6.6.5", "", { "peerDependencies": { "preact": ">=10 || >= 11.0.0-0" } }, "sha512-O6MHzYNIKYaiSX3bOw0gGZfEbOmlIDtDfWwN1JJdc/T3ihzRT6tGGSEWE088dWrEDGa1u7101q+6fzQnO9XCPA=="],
+
     "prebuild-install": ["prebuild-install@7.1.3", "", { "dependencies": { "detect-libc": "^2.0.0", "expand-template": "^2.0.3", "github-from-package": "0.0.0", "minimist": "^1.2.3", "mkdirp-classic": "^0.5.3", "napi-build-utils": "^2.0.0", "node-abi": "^3.3.0", "pump": "^3.0.0", "rc": "^1.2.7", "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" }, "bin": { "prebuild-install": "bin.js" } }, "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug=="],
 
     "prettier": ["prettier@3.9.6", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-OpN0zzVdiaiAhxpuuj5efpIS4sY9j7bY6uR5mnj5yPzGkdkjNKSJeUThPb60Jw29QuAZgA4o+/iB49kFiaBX6g=="],
@@ -1980,6 +2020,12 @@
 
     "reflect-metadata": ["reflect-metadata@0.2.2", "", {}, "sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q=="],
 
+    "regex": ["regex@6.1.0", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg=="],
+
+    "regex-recursion": ["regex-recursion@6.0.2", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg=="],
+
+    "regex-utilities": ["regex-utilities@2.3.0", "", {}, "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng=="],
+
     "regexp-to-ast": ["regexp-to-ast@0.5.0", "", {}, "sha512-tlbJqcMHnPKI9zSrystikWKwHkBqu2a/Sgw01h3zFjvYrMxEDYHzzoMZnUrbIfpTFEsoRnnviOXNCzFiSc54Qw=="],
 
     "rehype-harden": ["rehype-harden@1.1.8", "", { "dependencies": { "unist-util-visit": "^5.0.0" } }, "sha512-Qn7vR1xrf6fZCrkm9TDWi/AB4ylrHy+jqsNm1EHOAmbARYA6gsnVJBq/sdBh6kmT4NEZxH5vgIjrscefJAOXcw=="],
@@ -2066,6 +2112,8 @@
 
     "shell-quote": ["shell-quote@1.9.0", "", {}, "sha512-Iov+JwFv/2HcTpcwNMKd8+IWNb8tboQJNQTkAY/LLVK7gGH9jy+LGkVqPxfekHl+yMmiqXszdGWXgkfml7hjqA=="],
 
+    "shiki": ["shiki@4.4.2", "", { "dependencies": { "@shikijs/core": "4.4.2", "@shikijs/engine-javascript": "4.4.2", "@shikijs/engine-oniguruma": "4.4.2", "@shikijs/langs": "4.4.2", "@shikijs/themes": "4.4.2", "@shikijs/types": "4.4.2", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-P8F/dFhRevaw2uSdeIYlq/5SXZNY85DPtmXQ947gD1Zj2JqO5AkNvVVBar0Me9JkFx3uzVud/qOtP5ek9NEQGA=="],
+
     "side-channel": ["side-channel@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.4", "side-channel-list": "^1.0.1", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ=="],
 
     "side-channel-list": ["side-channel-list@1.0.1", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.4" } }, "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w=="],
@@ -2374,6 +2422,8 @@
 
     "@paralleldrive/cuid2/@noble/hashes": ["@noble/hashes@1.8.0", "", {}, "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A=="],
 
+    "@pierre/diffs/diff": ["diff@9.0.0", "", {}, "sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw=="],
+
     "@prisma/engines/@prisma/get-platform": ["@prisma/get-platform@7.9.1", "", { "dependencies": { "@prisma/debug": "7.9.1" } }, "sha512-PK8R60YZRQvYxBrGG9i7l2/rFyzy+2MuI1dKtmtrCqPH8YpiJx/MfiC7LRzX5786rZDEv7BngcjfIJW4/9ADuw=="],
 
     "@prisma/fetch-engine/@prisma/get-platform": ["@prisma/get-platform@7.9.1", "", { "dependencies": { "@prisma/debug": "7.9.1" } }, "sha512-PK8R60YZRQvYxBrGG9i7l2/rFyzy+2MuI1dKtmtrCqPH8YpiJx/MfiC7LRzX5786rZDEv7BngcjfIJW4/9ADuw=="],
diff --git a/packages/db/prisma/migrations/20260804210000_agent_builder_artifacts/migration.sql b/packages/db/prisma/migrations/20260804210000_agent_builder_artifacts/migration.sql
new file mode 100644
index 00000000..e30d05f5
--- /dev/null
+++ b/packages/db/prisma/migrations/20260804210000_agent_builder_artifacts/migration.sql
@@ -0,0 +1,23 @@
+CREATE TYPE "AgentBuilderArtifactStatus" AS ENUM ('WRITING', 'READY');
+
+CREATE TABLE "agentBuilderArtifact" (
+    "id" TEXT NOT NULL,
+    "conversationId" TEXT,
+    "versionId" TEXT,
+    "path" TEXT NOT NULL,
+    "language" TEXT NOT NULL,
+    "content" TEXT NOT NULL,
+    "previousContent" TEXT,
+    "revision" INTEGER NOT NULL,
+    "status" "AgentBuilderArtifactStatus" NOT NULL DEFAULT 'WRITING',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "agentBuilderArtifact_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "agentBuilderArtifact_conversationId_path_revision_key" ON "agentBuilderArtifact"("conversationId", "path", "revision");
+CREATE INDEX "agentBuilderArtifact_conversationId_createdAt_idx" ON "agentBuilderArtifact"("conversationId", "createdAt");
+CREATE INDEX "agentBuilderArtifact_versionId_path_idx" ON "agentBuilderArtifact"("versionId", "path");
+
+ALTER TABLE "agentBuilderArtifact" ADD CONSTRAINT "agentBuilderArtifact_conversationId_fkey" FOREIGN KEY ("conversationId") REFERENCES "agentConversation"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+ALTER TABLE "agentBuilderArtifact" ADD CONSTRAINT "agentBuilderArtifact_versionId_fkey" FOREIGN KEY ("versionId") REFERENCES "agentVersion"("id") ON DELETE SET NULL ON UPDATE CASCADE;
diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma
index 39a2edff..0e7b36f8 100644
--- a/packages/db/prisma/schema.prisma
+++ b/packages/db/prisma/schema.prisma
@@ -165,6 +165,11 @@ enum AgentVersionStatus {
   REJECTED
 }
 
+enum AgentBuilderArtifactStatus {
+  WRITING
+  READY
+}
+
 enum AgentTriggerType {
   MANUAL
   SCHEDULE
@@ -461,6 +466,7 @@ model AgentConversation {
   submissions     AgentConversationSubmission[]
   feedback        AgentConversationFeedback[]
   createdVersions AgentVersion[]                @relation("AgentVersionSourceConversation")
+  builderArtifacts AgentBuilderArtifact[]
 
   @@index([contactId, lastMessageAt])
   @@index([companyId, lastMessageAt])
@@ -597,6 +603,7 @@ model AgentVersion {
   triggers    AgentTrigger[]
   runs        AgentRun[]
   auditEvents AgentAuditEvent[]
+  builderArtifacts AgentBuilderArtifact[]
 
   @@unique([agentId, number])
   @@index([agentId, createdAt])
@@ -604,6 +611,29 @@ model AgentVersion {
   @@map("agentVersion")
 }
 
+model AgentBuilderArtifact {
+  id String @id @default(cuid())
+
+  conversationId String?
+  conversation   AgentConversation? @relation(fields: [conversationId], references: [id], onDelete: SetNull)
+
+  versionId String?
+  version   AgentVersion? @relation(fields: [versionId], references: [id], onDelete: SetNull)
+
+  path            String
+  language        String
+  content         String
+  previousContent String?
+  revision        Int
+  status          AgentBuilderArtifactStatus @default(WRITING)
+  createdAt       DateTime                   @default(now())
+
+  @@unique([conversationId, path, revision])
+  @@index([conversationId, createdAt])
+  @@index([versionId, path])
+  @@map("agentBuilderArtifact")
+}
+
 model AgentTrigger {
   id String @id @default(cuid())
 
diff --git a/packages/db/src/workspace.ts b/packages/db/src/workspace.ts
index c7053329..c3a7ffc7 100644
--- a/packages/db/src/workspace.ts
+++ b/packages/db/src/workspace.ts
@@ -10,6 +10,9 @@ export const MAX_SLUG = 48;
 export const RESERVED_SLUGS: readonly string[] = [
 	"_next",
 	"api",
+	"agent",
+	"agents",
+	"chat",
 	"companies",
 	"contacts",
 	"deals",

From ef760727cf7a5a8cf1823a688a39d3495295e020 Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:10:54 -0700
Subject: [PATCH 5/7] CMP-46 feat: refine agent builder interactions

---
 apps/agent/agent/instructions/task.ts         |   2 +-
 .../subagents/agent_builder/instructions.md   |  12 +-
 apps/agent/test/custom-agent-runtime.spec.ts  |   7 +-
 .../agent-builder/agent-builder-chat.tsx      | 249 +++++++++++++++---
 .../agent-builder/agent-code-workspace.tsx    |  34 +--
 apps/app/lib/agent-transcript.ts              |  10 +-
 apps/app/test/agent-transcript.spec.ts        |  18 ++
 7 files changed, 256 insertions(+), 76 deletions(-)

diff --git a/apps/agent/agent/instructions/task.ts b/apps/agent/agent/instructions/task.ts
index d09a3622..780f9f39 100644
--- a/apps/agent/agent/instructions/task.ts
+++ b/apps/agent/agent/instructions/task.ts
@@ -57,7 +57,7 @@ function builderInstructions(ctx: Parameters<typeof purposeOf>[0]) {
 
 export function builderTaskMarkdown(commandType: string | null): string {
 	return commandType === "CREATE_AGENT"
-		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If it asks for clarification, ask only that question. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
+		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If the specialist says an essential decision is unclear, call ask_question instead of replying with a plain-text question. Ask one focused question, offer two to four mutually exclusive options when they clarify a real choice, and allow a freeform answer when a custom response is valid. Ask only when the answer materially changes the trigger, records, integrations, schedule, outcome, or side effect. Do not interrupt a sufficiently specific request or ask about optional polish. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
 		: `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. The user must explicitly run the Create agent slash command before agent creation begins. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`;
 }
 
diff --git a/apps/agent/agent/subagents/agent_builder/instructions.md b/apps/agent/agent/subagents/agent_builder/instructions.md
index 7dc65537..7f307fd8 100644
--- a/apps/agent/agent/subagents/agent_builder/instructions.md
+++ b/apps/agent/agent/subagents/agent_builder/instructions.md
@@ -18,10 +18,14 @@ Gmail and Google Calendar are read-only sources when connected. Do not promise
 email sending, Slack, arbitrary webhooks, or any integration the context does
 not report.
 
-If an essential trigger, target, connection, schedule, or outcome is unclear,
-do not call `save_agent_draft`. Return one focused question for the parent to
-ask the user. For a schedule, calculate a future `nextRunAt` from the supplied
-current time and provide its recurrence in minutes.
+If an essential trigger, target, connection, schedule, outcome, or side effect
+is unclear, do not call `save_agent_draft`. Return one focused question for the
+parent to ask the user. Include two to four mutually exclusive options when
+they clarify a real choice, and say whether a custom answer is valid. Ask only
+when the answer materially changes the bounded behavior. Do not interrupt a
+sufficiently specific request or ask about optional polish. For a schedule,
+calculate a future `nextRunAt` from the supplied current time and provide its
+recurrence in minutes.
 
 When the behavior is specific and supported, build the agent in front of the
 user. Call `write_agent_file` for `agent/instructions.md`, then
diff --git a/apps/agent/test/custom-agent-runtime.spec.ts b/apps/agent/test/custom-agent-runtime.spec.ts
index 54fd1f05..5a5f95a5 100644
--- a/apps/agent/test/custom-agent-runtime.spec.ts
+++ b/apps/agent/test/custom-agent-runtime.spec.ts
@@ -54,8 +54,11 @@ describe("session purpose boundaries", () => {
 
 describe("builder command routing", () => {
 	it("delegates only the explicit creation command to the agent builder", () => {
-		expect(builderTaskMarkdown("CREATE_AGENT")).toContain(
-			"Call agent_builder exactly once",
+		const creation = builderTaskMarkdown("CREATE_AGENT");
+		expect(creation).toContain("Call agent_builder exactly once");
+		expect(creation).toContain("call ask_question");
+		expect(creation).toContain(
+			"Do not interrupt a sufficiently specific request",
 		);
 		expect(builderTaskMarkdown("CHAT")).toContain("Do not call agent_builder");
 		expect(builderTaskMarkdown(null)).toContain("private CRM assistant chat");
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
index 967944d1..027122ce 100644
--- a/apps/app/components/agent-builder/agent-builder-chat.tsx
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -20,9 +20,9 @@ import {
 } from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
 import { Icon } from "@crm/ui/components/icon";
+import { Input } from "@crm/ui/components/input";
 import { Markdown } from "@crm/ui/components/markdown";
 import { Skeleton } from "@crm/ui/components/skeleton";
-import { TaskSteps } from "@crm/ui/components/task-steps";
 import { cn } from "@crm/ui/lib/utils";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { MessageStreamEvent } from "eve/client";
@@ -37,6 +37,7 @@ import {
 import {
 	type AgentTurnFailure,
 	latestTurnFailure,
+	pendingQuestion,
 	toTranscript,
 } from "@/lib/agent-transcript";
 import { useTRPC } from "@/lib/trpc/client";
@@ -68,6 +69,12 @@ type BuilderSubmission = {
 	errorMessage: string | null;
 };
 
+type ClarificationResponse = {
+	requestId: string;
+	optionId?: string;
+	text?: string;
+};
+
 export function AgentBuilderChat({
 	conversationId,
 }: {
@@ -149,6 +156,7 @@ export function AgentBuilderChat({
 	const failure = latestTurnFailure(events.data ?? []);
 	const creatingAgent = hasCreateAgentCommand(submissions);
 	const working = isWorking(data, creatingAgent) && !failure;
+	const awaitingInput = events.data?.at(-1)?.type === "session.waiting";
 	const retryPrompt = retryPromptOf(submissions.at(-1));
 	const send = (prompt: BuilderPrompt) => {
 		submit.mutate({
@@ -259,7 +267,7 @@ export function AgentBuilderChat({
 					<AgentComposer
 						mode="chat"
 						pending={submit.isPending}
-						disabled={working}
+						disabled={working || awaitingInput}
 						onSubmit={send}
 					/>
 				</div>
@@ -465,10 +473,43 @@ function AssistantTranscript({
 	conversation: Conversation;
 	events: MessageStreamEvent[];
 }) {
-	const agent = useEveAgent({ initialEvents: events });
+	const trpc = useTRPC();
+	const queryClient = useQueryClient();
+	const agent = useEveAgent({
+		headers: { "x-crm-builder-conversation": conversation.id },
+		initialEvents: events,
+		...(conversation.sessionId
+			? {
+					initialSession: {
+						sessionId: conversation.sessionId,
+						streamIndex: conversation.streamIndex,
+						...(conversation.continuationToken
+							? { continuationToken: conversation.continuationToken }
+							: {}),
+					},
+				}
+			: {}),
+		onError: (error) => toast.error(error.message),
+	});
 	const messages = toTranscript(agent.data.messages).filter(
 		(message) => !message.mine,
 	);
+	const question = pendingQuestion(agent.data.messages);
+	const latestMessageId = messages.at(-1)?.id;
+	const answerQuestion = async (response: ClarificationResponse) => {
+		await agent.send({ inputResponses: [response] });
+		await Promise.all([
+			queryClient.invalidateQueries({
+				queryKey: trpc.conversations.builderById.pathKey(),
+			}),
+			queryClient.invalidateQueries({
+				queryKey: trpc.conversations.builderList.pathKey(),
+			}),
+			queryClient.invalidateQueries({
+				queryKey: trpc.conversations.events.pathKey(),
+			}),
+		]);
+	};
 
 	return (
 		<>
@@ -514,6 +555,16 @@ function AssistantTranscript({
 								markdown={markdown}
 							/>
 						) : null}
+						{question && message.id === latestMessageId ? (
+							<ClarificationCard
+								key={question.requestId}
+								question={question}
+								pending={
+									agent.status === "submitted" || agent.status === "streaming"
+								}
+								onAnswer={answerQuestion}
+							/>
+						) : null}
 					</div>
 				);
 			})}
@@ -521,6 +572,105 @@ function AssistantTranscript({
 	);
 }
 
+function ClarificationCard({
+	question,
+	pending,
+	onAnswer,
+}: {
+	question: NonNullable<ReturnType<typeof pendingQuestion>>;
+	pending: boolean;
+	onAnswer: (response: ClarificationResponse) => Promise<void>;
+}) {
+	const [answer, setAnswer] = useState("");
+	const options = question.options ?? [];
+	const showFreeform =
+		question.display === "text" ||
+		question.allowFreeform === true ||
+		options.length === 0;
+
+	const submitAnswer = () => {
+		const text = answer.trim();
+		if (!text || pending) return;
+		void onAnswer({ requestId: question.requestId, text });
+	};
+
+	return (
+		<div className="ml-3 border-ring/50 border-l-2 pl-3">
+			<div className="rounded-r-lg bg-muted/50 px-3 py-3 sm:px-4">
+				<p className="font-medium text-xs">Before I continue</p>
+				<Markdown className="mt-1 text-pretty text-sm leading-5">
+					{question.prompt}
+				</Markdown>
+
+				{options.length > 0 ? (
+					<div className="mt-3 flex flex-wrap gap-2">
+						{options.map((option) => (
+							<Button
+								key={option.id}
+								type="button"
+								variant={
+									option.style === "danger"
+										? "destructive"
+										: option.style === "primary"
+											? "default"
+											: "outline"
+								}
+								size="sm"
+								className="h-auto min-h-8 max-w-full flex-col items-start whitespace-normal text-left"
+								disabled={pending}
+								onClick={() =>
+									void onAnswer({
+										requestId: question.requestId,
+										optionId: option.id,
+									})
+								}
+							>
+								<span>{option.label}</span>
+								{option.description ? (
+									<span className="font-normal text-current/70 text-xs">
+										{option.description}
+									</span>
+								) : null}
+							</Button>
+						))}
+					</div>
+				) : null}
+
+				{showFreeform ? (
+					<form
+						className="mt-3 flex min-w-0 gap-2"
+						onSubmit={(event) => {
+							event.preventDefault();
+							submitAnswer();
+						}}
+					>
+						<Input
+							value={answer}
+							onChange={(event) => setAnswer(event.target.value)}
+							placeholder="Type another answer"
+							aria-label="Answer the agent's question"
+							disabled={pending}
+						/>
+						<Button
+							type="submit"
+							size="sm"
+							disabled={!answer.trim() || pending}
+						>
+							{pending ? "Sending" : "Send"}
+						</Button>
+					</form>
+				) : null}
+
+				{pending ? (
+					<span className="sr-only" role="status">
+						Sending your answer
+					</span>
+				) : null}
+			</div>
+		</div>
+	);
+}
+
 function ResponseActions({
 	conversation,
 	messageId,
@@ -603,28 +753,7 @@ function BuildingAgentCard({
 				: sessionId
 					? 1
 					: 0;
-	const steps = [
-		{
-			id: "context",
-			label: "Inspect the requested scope",
-			meta: "CRM records and connected sources",
-		},
-		{
-			id: "instructions",
-			label: "Write the agent instructions",
-			meta: "Trigger, boundaries, and stopping rules",
-		},
-		{
-			id: "manifest",
-			label: "Define the agent manifest",
-			meta: "Data scope and allowed actions",
-		},
-		{
-			id: "review",
-			label: "Prepare the private draft",
-			meta: "Saved for your review",
-		},
-	] as const;
+	const steps = ["Scope", "Instructions", "Manifest", "Review"] as const;
 	const stop = useAsyncAction({
 		action: async () => {
 			if (!sessionId) return;
@@ -644,8 +773,8 @@ function BuildingAgentCard({
 				I’m turning this into a team agent. I’ll inspect the CRM scope, verify
 				the requested connections, then prepare a safe deployment for review.
 			</p>
-			<div className="overflow-hidden rounded-lg border bg-card">
-				<div className="flex flex-wrap items-center gap-3 border-b px-4 py-3 sm:gap-4 sm:px-5 sm:py-4">
+			<div className="overflow-hidden rounded-lg bg-muted/40">
+				<div className="flex flex-wrap items-center gap-3 px-4 pt-4 pb-2">
 					<Icon
 						icon={Renew}
 						className="size-3.5 animate-spin text-ring"
@@ -657,8 +786,61 @@ function BuildingAgentCard({
 					<span className="font-mono text-muted-foreground text-xs">
 						{completed} of 4
 					</span>
+				</div>
+				<ol
+					className="grid grid-cols-4 gap-2 px-3 py-4 sm:px-4"
+					aria-label="Agent creation"
+				>
+					{steps.map((label, index) => {
+						const done = index < completed;
+						const active = index === completed && completed < steps.length;
+
+						return (
+							<li
+								key={label}
+								className="flex min-w-0 flex-col items-center gap-2 text-center"
+								aria-current={active ? "step" : undefined}
+							>
+								<span
+									className={cn(
+										"flex size-6 items-center justify-center rounded-full text-[11px]",
+										done && "bg-ring text-background",
+										active && "bg-background text-ring",
+										!done &&
+											!active &&
+											"bg-background/60 text-muted-foreground",
+									)}
+								>
+									{done ? (
+										<Icon icon={Checkmark} className="size-3.5" />
+									) : active ? (
+										<Icon
+											icon={Renew}
+											className="size-3.5 animate-spin"
+											motion="none"
+										/>
+									) : (
+										index + 1
+									)}
+								</span>
+								<span
+									className={cn(
+										"min-w-0 wrap-break-word text-[11px] leading-4 sm:text-xs",
+										!done && !active && "text-muted-foreground",
+									)}
+								>
+									{label}
+								</span>
+							</li>
+						);
+					})}
+				</ol>
+				<footer className="flex min-h-12 flex-wrap items-center gap-3 bg-background/55 px-4 py-2.5">
+					<p className="min-w-0 flex-1 text-pretty text-muted-foreground text-xs">
+						You can leave this chat. I’ll keep working in the background.
+					</p>
 					<Button
-						variant="outline"
+						variant="ghost"
 						size="sm"
 						disabled={!sessionId || stop.pending}
 						aria-busy={stop.pending}
@@ -673,16 +855,7 @@ function BuildingAgentCard({
 							Stop
 						</AsyncButtonContent>
 					</Button>
-				</div>
-				<TaskSteps
-					steps={[...steps]}
-					current={completed}
-					label="Agent creation"
-				/>
-				<p className="border-t px-4 py-3 text-muted-foreground text-xs sm:px-5">
-					This chat keeps running if you leave. You’ll see a dot in the sidebar
-					when there’s a response.
-				</p>
+				</footer>
 			</div>
 		</div>
 	);
diff --git a/apps/app/components/agent-builder/agent-code-workspace.tsx b/apps/app/components/agent-builder/agent-code-workspace.tsx
index 23273ffa..aad4d572 100644
--- a/apps/app/components/agent-builder/agent-code-workspace.tsx
+++ b/apps/app/components/agent-builder/agent-code-workspace.tsx
@@ -37,7 +37,6 @@ export function AgentCodeWorkspace({
 	return (
 		<AgentCodeWorkspaceSurface
 			key={paths.join("|")}
-			artifacts={artifacts}
 			latest={latest}
 			paths={paths}
 			working={working}
@@ -46,12 +45,10 @@ export function AgentCodeWorkspace({
 }
 
 function AgentCodeWorkspaceSurface({
-	artifacts,
 	latest,
 	paths,
 	working,
 }: {
-	artifacts: AgentCodeArtifact[];
 	latest: Map<string, AgentCodeArtifact>;
 	paths: string[];
 	working: boolean;
@@ -70,9 +67,6 @@ function AgentCodeWorkspaceSurface({
 	const selectedPath =
 		selection.find((path) => latest.has(path)) ?? paths[0] ?? null;
 	const artifact = selectedPath ? latest.get(selectedPath) : null;
-	const revisions = artifact
-		? artifacts.filter((item) => item.path === artifact.path)
-		: [];
 	const previous = artifact?.previousContent ?? null;
 	const showChanges = mode === "changes" && previous !== null;
 
@@ -88,9 +82,9 @@ function AgentCodeWorkspaceSurface({
 	return (
 		<section
 			aria-label="Generated agent files"
-			className="overflow-hidden rounded-lg border bg-card"
+			className="overflow-hidden rounded-lg bg-muted/40"
 		>
-			<header className="flex min-h-11 flex-wrap items-center gap-2 border-b px-3 py-2 sm:px-4">
+			<header className="flex min-h-11 flex-wrap items-center gap-2 px-3 py-2">
 				<span className="flex min-w-0 flex-1 items-center gap-2">
 					<Icon
 						icon={working ? Renew : Checkmark}
@@ -102,8 +96,8 @@ function AgentCodeWorkspaceSurface({
 					<span className="truncate font-medium text-sm">
 						{working ? "Writing agent files" : "Agent files"}
 					</span>
-					<span className="shrink-0 font-mono text-muted-foreground text-xs">
-						{paths.length}/3
+					<span className="shrink-0 text-muted-foreground text-xs">
+						{paths.length} {paths.length === 1 ? "file" : "files"}
 					</span>
 				</span>
 				<fieldset
@@ -128,8 +122,8 @@ function AgentCodeWorkspaceSurface({
 				</fieldset>
 			</header>
 
-			<div className="grid min-h-0 md:grid-cols-[190px_minmax(0,1fr)]">
-				<div className="h-40 min-w-0 border-b bg-muted/20 p-2 md:h-[360px] md:border-r md:border-b-0">
+			<div className="mx-2 mb-2 grid min-h-0 overflow-hidden rounded-md bg-background md:grid-cols-[190px_minmax(0,1fr)]">
+				<div className="h-36 min-w-0 border-b border-border/60 bg-muted/15 p-2 md:h-[360px] md:border-r md:border-b-0">
 					<FileTree
 						model={model}
 						aria-label="Agent files"
@@ -137,17 +131,6 @@ function AgentCodeWorkspaceSurface({
 					/>
 				</div>
 				<div className="min-w-0 overflow-auto bg-background md:h-[360px]">
-					<div className="flex h-8 items-center gap-2 border-b px-3 text-xs">
-						<span className="min-w-0 flex-1 truncate font-mono">
-							{artifact.path}
-						</span>
-						<span className="shrink-0 text-muted-foreground">
-							revision {artifact.revision}
-						</span>
-						<span className="sr-only" aria-live="polite">
-							{artifact.status === "READY" ? "Ready" : "Writing"}
-						</span>
-					</div>
 					{showChanges ? (
 						<MultiFileDiff
 							oldFile={{
@@ -173,11 +156,6 @@ function AgentCodeWorkspaceSurface({
 					)}
 				</div>
 			</div>
-			<footer className="border-t px-3 py-2 text-muted-foreground text-xs sm:px-4">
-				{working
-					? "Files are saved as the builder works. You can leave and come back without losing progress."
-					: `${revisions.length} saved ${revisions.length === 1 ? "revision" : "revisions"} for this file.`}
-			</footer>
 		</section>
 	);
 }
diff --git a/apps/app/lib/agent-transcript.ts b/apps/app/lib/agent-transcript.ts
index b89293b7..7b11f7fe 100644
--- a/apps/app/lib/agent-transcript.ts
+++ b/apps/app/lib/agent-transcript.ts
@@ -102,7 +102,9 @@ export function toTranscript(
 							label: describe(part),
 							tone: outcomeTone(part),
 							pending:
-								state === "input-streaming" || state === "input-available",
+								state === "input-streaming" ||
+								state === "input-available" ||
+								state === "approval-requested",
 							sources: sourcesOf(part),
 						},
 					];
@@ -184,10 +186,12 @@ export function sourcesOf(part: EveMessagePart): Source[] {
 
 export function pendingQuestion(messages: readonly EveMessage[]) {
 	for (const part of messages.at(-1)?.parts ?? []) {
-		if (part.type !== "dynamic-tool") continue;
+		if (part.type !== "dynamic-tool" || part.state !== "approval-requested") {
+			continue;
+		}
 
 		const request = part.toolMetadata?.eve?.inputRequest;
-		if (request) return request;
+		if (request?.kind === "question") return request;
 	}
 
 	return null;
diff --git a/apps/app/test/agent-transcript.spec.ts b/apps/app/test/agent-transcript.spec.ts
index be70e012..6c0ac015 100644
--- a/apps/app/test/agent-transcript.spec.ts
+++ b/apps/app/test/agent-transcript.spec.ts
@@ -185,6 +185,7 @@ describe("sourcesOf", () => {
 describe("pendingQuestion", () => {
 	const request = {
 		requestId: "req_1",
+		kind: "question",
 		prompt: "Which one?",
 		options: [{ id: "a", label: "The first" }],
 	};
@@ -195,6 +196,7 @@ describe("pendingQuestion", () => {
 				{
 					type: "dynamic-tool",
 					toolName: "ask_question",
+					state: "approval-requested",
 					toolMetadata: { eve: { inputRequest: request } },
 				},
 			]),
@@ -208,6 +210,7 @@ describe("pendingQuestion", () => {
 			{
 				type: "dynamic-tool",
 				toolName: "ask_question",
+				state: "approval-requested",
 				toolMetadata: { eve: { inputRequest: request } },
 			},
 		]);
@@ -216,6 +219,21 @@ describe("pendingQuestion", () => {
 		expect(pendingQuestion([asked, answered])).toBeNull();
 	});
 
+	it("ignores a question that already has a response", () => {
+		expect(
+			pendingQuestion([
+				message([
+					{
+						type: "dynamic-tool",
+						toolName: "ask_question",
+						state: "approval-responded",
+						toolMetadata: { eve: { inputRequest: request } },
+					},
+				]),
+			]),
+		).toBeNull();
+	});
+
 	it("finds nothing in an empty transcript", () => {
 		expect(pendingQuestion([])).toBeNull();
 	});

From 7a94b196737d63f6e4880e53dbca688ad584331b Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 23:04:04 -0700
Subject: [PATCH 6/7] CMP-46 fix: anchor builder questions to the composer

---
 apps/agent/agent/instructions/task.ts         |   2 +-
 apps/agent/agent/lib/custom-agent-dispatch.ts |  12 +-
 .../subagents/agent_builder/instructions.md   |  10 +-
 apps/agent/test/custom-agent-runtime.spec.ts  |  16 +
 .../conversations/conversations.contracts.ts  |  16 +
 .../src/conversations/conversations.router.ts |   9 +
 .../conversations/conversations.service.ts    | 141 +++++++++
 apps/api/src/generated/server.ts              |   5 +-
 apps/api/test/conversations.spec.ts           |  72 +++++
 .../agent-builder/agent-builder-chat.tsx      | 274 ++++++------------
 .../agent-builder/agent-composer.tsx          |   9 +-
 .../agent-clarification-composer.tsx          | 160 ++++++++++
 apps/app/components/agent-composer-frame.ts   |   2 +
 apps/app/components/crm/agent-panel.tsx       | 104 +++----
 apps/app/lib/agent-transcript.ts              |  18 +-
 packages/ui/src/components/textarea.tsx       |  16 +-
 packages/ui/src/components/toggle-group.tsx   |   2 +-
 packages/ui/src/components/toggle.tsx         |   5 +-
 18 files changed, 604 insertions(+), 269 deletions(-)
 create mode 100644 apps/app/components/agent-clarification-composer.tsx
 create mode 100644 apps/app/components/agent-composer-frame.ts

diff --git a/apps/agent/agent/instructions/task.ts b/apps/agent/agent/instructions/task.ts
index 780f9f39..de9a2abc 100644
--- a/apps/agent/agent/instructions/task.ts
+++ b/apps/agent/agent/instructions/task.ts
@@ -57,7 +57,7 @@ function builderInstructions(ctx: Parameters<typeof purposeOf>[0]) {
 
 export function builderTaskMarkdown(commandType: string | null): string {
 	return commandType === "CREATE_AGENT"
-		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If the specialist says an essential decision is unclear, call ask_question instead of replying with a plain-text question. Ask one focused question, offer two to four mutually exclusive options when they clarify a real choice, and allow a freeform answer when a custom response is valid. Ask only when the answer materially changes the trigger, records, integrations, schedule, outcome, or side effect. Do not interrupt a sufficiently specific request or ask about optional polish. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
+		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If the specialist says an essential decision is unclear, call ask_question instead of replying with a plain-text question. Ask exactly one decision at a time and never bundle several missing details into one prompt. Offer two to four mutually exclusive options when they clarify a real choice, and allow a freeform answer when a custom response is valid. After the answer, ask another question only if the build remains materially blocked. Ask only when the answer materially changes the trigger, records, integrations, schedule, outcome, or side effect. Do not interrupt a sufficiently specific request or ask about optional polish. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
 		: `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. The user must explicitly run the Create agent slash command before agent creation begins. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`;
 }
 
diff --git a/apps/agent/agent/lib/custom-agent-dispatch.ts b/apps/agent/agent/lib/custom-agent-dispatch.ts
index d2c637fa..49b5940a 100644
--- a/apps/agent/agent/lib/custom-agent-dispatch.ts
+++ b/apps/agent/agent/lib/custom-agent-dispatch.ts
@@ -83,7 +83,7 @@ export async function dispatchBuilderSubmission(
 
 	try {
 		const session = await send(
-			builderMessage(submission.id, submission.message),
+			builderDeliveryMessage(submission.id, submission.message),
 			{
 				auth: {
 					authenticator: "crm-builder",
@@ -338,11 +338,19 @@ async function recoverBuilderSubmissions() {
 	});
 }
 
-function builderMessage(
+export function builderDeliveryMessage(
 	submissionId: string,
 	value: unknown,
 ): Parameters<SendFn>[0] {
 	const message = recordOf(value);
+	const inputResponse = recordOf(message.inputResponse);
+	const response =
+		typeof inputResponse.requestId === "string" &&
+		typeof inputResponse.answer === "string"
+			? inputResponse.answer.trim()
+			: "";
+	if (response) return response;
+
 	const text = typeof message.text === "string" ? message.text : "";
 	const resources = Array.isArray(message.resources) ? message.resources : [];
 	const attachments = Array.isArray(message.attachments)
diff --git a/apps/agent/agent/subagents/agent_builder/instructions.md b/apps/agent/agent/subagents/agent_builder/instructions.md
index 7f307fd8..2c858c56 100644
--- a/apps/agent/agent/subagents/agent_builder/instructions.md
+++ b/apps/agent/agent/subagents/agent_builder/instructions.md
@@ -22,10 +22,12 @@ If an essential trigger, target, connection, schedule, outcome, or side effect
 is unclear, do not call `save_agent_draft`. Return one focused question for the
 parent to ask the user. Include two to four mutually exclusive options when
 they clarify a real choice, and say whether a custom answer is valid. Ask only
-when the answer materially changes the bounded behavior. Do not interrupt a
-sufficiently specific request or ask about optional polish. For a schedule,
-calculate a future `nextRunAt` from the supplied current time and provide its
-recurrence in minutes.
+when the answer materially changes the bounded behavior. Return exactly one
+decision per pause; never bundle several missing details into one question.
+After the answer, ask the next question only if the build is still materially
+blocked. Do not interrupt a sufficiently specific request or ask about optional
+polish. For a schedule, calculate a future `nextRunAt` from the supplied current
+time and provide its recurrence in minutes.
 
 When the behavior is specific and supported, build the agent in front of the
 user. Call `write_agent_file` for `agent/instructions.md`, then
diff --git a/apps/agent/test/custom-agent-runtime.spec.ts b/apps/agent/test/custom-agent-runtime.spec.ts
index 5a5f95a5..2d14c965 100644
--- a/apps/agent/test/custom-agent-runtime.spec.ts
+++ b/apps/agent/test/custom-agent-runtime.spec.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { builderTaskMarkdown } from "../agent/instructions/task";
 import {
+	builderDeliveryMessage,
 	builderIdFromToken,
 	builderToken,
 	runIdFromToken,
@@ -35,6 +36,20 @@ describe("custom agent continuation tokens", () => {
 	});
 });
 
+describe("builder delivery messages", () => {
+	it("delivers a question response without submission wrapper text", () => {
+		expect(
+			builderDeliveryMessage("submission-1", {
+				text: "Use a CRM task instead",
+				inputResponse: {
+					requestId: "question-1",
+					answer: "crm-task",
+				},
+			}),
+		).toBe("crm-task");
+	});
+});
+
 describe("session purpose boundaries", () => {
 	it("reads current-turn attributes before initiator attributes", () => {
 		expect(attribute(context("builder"), "conversationId")).toBe("chat-1");
@@ -57,6 +72,7 @@ describe("builder command routing", () => {
 		const creation = builderTaskMarkdown("CREATE_AGENT");
 		expect(creation).toContain("Call agent_builder exactly once");
 		expect(creation).toContain("call ask_question");
+		expect(creation).toContain("exactly one decision at a time");
 		expect(creation).toContain(
 			"Do not interrupt a sufficiently specific request",
 		);
diff --git a/apps/api/src/conversations/conversations.contracts.ts b/apps/api/src/conversations/conversations.contracts.ts
index 30e2b0f4..14d2c891 100644
--- a/apps/api/src/conversations/conversations.contracts.ts
+++ b/apps/api/src/conversations/conversations.contracts.ts
@@ -66,6 +66,22 @@ export type BuilderConversationSubmitInput = z.infer<
 	typeof builderConversationSubmitInput
 >;
 
+export const builderQuestionResponseInput = z
+	.object({
+		id: z.string().min(1),
+		clientRequestId: z.uuid(),
+		requestId: z.string().trim().min(1).max(240),
+		optionId: z.string().trim().min(1).max(160).optional(),
+		text: z.string().trim().min(1).max(20_000).optional(),
+	})
+	.refine((input) => Boolean(input.optionId) !== Boolean(input.text), {
+		message: "Choose one option or enter a written answer.",
+	});
+
+export type BuilderQuestionResponseInput = z.infer<
+	typeof builderQuestionResponseInput
+>;
+
 export const sharedConversationInput = z.object({
 	token: z.string().trim().min(32).max(256),
 });
diff --git a/apps/api/src/conversations/conversations.router.ts b/apps/api/src/conversations/conversations.router.ts
index 87476f26..e65987ee 100644
--- a/apps/api/src/conversations/conversations.router.ts
+++ b/apps/api/src/conversations/conversations.router.ts
@@ -14,6 +14,7 @@ import { ConversationSharingService } from "./conversation-sharing.service";
 import {
 	builderConversationCreateInput,
 	builderConversationSubmitInput,
+	builderQuestionResponseInput,
 	builderResourceSearchInput,
 	builderResponseRatingInput,
 	conversationEventsInput,
@@ -89,6 +90,14 @@ export class ConversationsRouter {
 		return this.conversations.submitBuilder(input, ctx.user.id);
 	}
 
+	@Mutation({ input: builderQuestionResponseInput })
+	async answerBuilderQuestion(
+		@Ctx() ctx: AuthedTrpcContext,
+		@Input() input: z.infer<typeof builderQuestionResponseInput>,
+	) {
+		return this.conversations.answerBuilderQuestion(input, ctx.user.id);
+	}
+
 	@Mutation({ input: builderResponseRatingInput })
 	async rateBuilderResponse(
 		@Ctx() ctx: AuthedTrpcContext,
diff --git a/apps/api/src/conversations/conversations.service.ts b/apps/api/src/conversations/conversations.service.ts
index 56bb0391..19ac1e4a 100644
--- a/apps/api/src/conversations/conversations.service.ts
+++ b/apps/api/src/conversations/conversations.service.ts
@@ -15,6 +15,7 @@ import { InjectDatabase } from "../database/database.constants";
 import type {
 	BuilderConversationCreateInput,
 	BuilderConversationSubmitInput,
+	BuilderQuestionResponseInput,
 	ConversationEventsInput,
 	ConversationListInput,
 	ConversationSaveInput,
@@ -496,6 +497,136 @@ export class ConversationsService {
 		return submission;
 	}
 
+	async answerBuilderQuestion(
+		input: BuilderQuestionResponseInput,
+		userId: string,
+	): Promise<{ id: string }> {
+		const existing = await this.db.agentConversationSubmission.findUnique({
+			where: { clientRequestId: input.clientRequestId },
+			select: { id: true, conversationId: true, submittedById: true },
+		});
+
+		if (existing) {
+			if (
+				existing.conversationId !== input.id ||
+				existing.submittedById !== userId
+			) {
+				throw new BadRequestException("That request has already been used.");
+			}
+
+			return { id: existing.id };
+		}
+
+		const conversation = await this.db.agentConversation.findFirst({
+			where: { id: input.id, userId, kind: "BUILDER" },
+			select: { id: true, sessionId: true, continuationToken: true },
+		});
+
+		if (!conversation) {
+			throw new NotFoundException(
+				`No builder conversation with id ${input.id}.`,
+			);
+		}
+
+		if (!conversation.sessionId || !conversation.continuationToken) {
+			throw new BadRequestException(
+				"The agent is no longer waiting for that answer.",
+			);
+		}
+
+		const boundary = await this.db.agentEvent.findFirst({
+			where: {
+				sessionId: conversation.sessionId,
+				type: {
+					in: [
+						"input.requested",
+						"message.received",
+						"turn.cancelled",
+						"session.completed",
+						"session.failed",
+					],
+				},
+			},
+			orderBy: [{ emittedAt: "desc" }, { id: "desc" }],
+			select: { type: true, data: true },
+		});
+
+		if (boundary?.type !== "input.requested") {
+			throw new BadRequestException(
+				"The agent is no longer waiting for that answer.",
+			);
+		}
+
+		const requests = arrayOf(recordOf(boundary.data).requests).map(recordOf);
+		const question = requests.find(
+			(request) =>
+				request.kind === "question" && request.requestId === input.requestId,
+		);
+
+		if (!question) {
+			throw new BadRequestException(
+				"That follow-up question is no longer active.",
+			);
+		}
+
+		const options = arrayOf(question.options).map(recordOf);
+		const selected = input.optionId
+			? options.find((option) => option.id === input.optionId)
+			: null;
+
+		if (input.optionId && !selected) {
+			throw new BadRequestException(
+				"That answer is not available for this question.",
+			);
+		}
+
+		const acceptsText =
+			question.allowFreeform === true ||
+			question.display === "text" ||
+			options.length === 0;
+		if (input.text && !acceptsText) {
+			throw new BadRequestException(
+				"Choose one of the available answers for this question.",
+			);
+		}
+
+		const answer = input.optionId ?? input.text;
+		if (!answer) {
+			throw new BadRequestException("Choose an answer before submitting.");
+		}
+
+		const displayText =
+			typeof selected?.label === "string" ? selected.label : answer;
+		const submission = await this.db.$transaction(async (tx) => {
+			const created = await tx.agentConversationSubmission.create({
+				data: {
+					conversationId: input.id,
+					submittedById: userId,
+					clientRequestId: input.clientRequestId,
+					commandType: "CHAT",
+					message: {
+						text: displayText,
+						resources: [],
+						attachments: [],
+						inputResponse: { requestId: input.requestId, answer },
+					},
+				},
+				select: { id: true },
+			});
+
+			await tx.agentConversation.update({
+				where: { id: input.id },
+				data: { lastMessageAt: new Date(), lastReadAt: new Date() },
+			});
+
+			return created;
+		});
+
+		this.agent?.builderConversationQueued();
+
+		return submission;
+	}
+
 	async markRead(id: string, userId: string): Promise<{ id: string }> {
 		const updated = await this.db.agentConversation.updateMany({
 			where: { id, userId, kind: "BUILDER" },
@@ -689,3 +820,13 @@ export class ConversationsService {
 			: `${normalized.slice(0, 77).trimEnd()}…`;
 	}
 }
+
+function recordOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function arrayOf(value: unknown): unknown[] {
+	return Array.isArray(value) ? value : [];
+}
diff --git a/apps/api/src/generated/server.ts b/apps/api/src/generated/server.ts
index ae32c91e..6705efd3 100644
--- a/apps/api/src/generated/server.ts
+++ b/apps/api/src/generated/server.ts
@@ -17,7 +17,7 @@ import { timelineInput, timelineCountsInput, myTasksInput, activityCreateInput,
 import { agentIdInput, agentHistoryInput, agentUpdateInput, agentDeployInput, agentRunNowInput } from "../agent/agents.contracts";
 import { companyListInput, companyIdInput, companyOptionsInput, companyCreateInput, companyUpdateArgs, setPrimaryContactInput } from "../companies/companies.contracts";
 import { contactListInput, contactIdInput, contactCreateInput, contactUpdateArgs, factDecisionInput } from "../contacts/contacts.contracts";
-import { conversationListInput, builderResourceSearchInput, conversationIdInput, conversationEventsInput, conversationSaveInput, builderConversationCreateInput, builderConversationSubmitInput, builderResponseRatingInput, sharedConversationInput } from "../conversations/conversations.contracts";
+import { conversationListInput, builderResourceSearchInput, conversationIdInput, conversationEventsInput, conversationSaveInput, builderConversationCreateInput, builderConversationSubmitInput, builderQuestionResponseInput, builderResponseRatingInput, sharedConversationInput } from "../conversations/conversations.contracts";
 import { dashboardSummaryInput } from "../dashboard/dashboard.contracts";
 import { dealListInput, dealIdInput, dealCreateInput, dealUpdateArgs, setStageInput } from "../deals/deals.contracts";
 import { setAutoCreateInput, suppressDomainInput, threadInput, calendarEventInput } from "../google/google.contracts";
@@ -169,6 +169,9 @@ const appRouter = t.router({
     submitBuilder: publicProcedure
       .input(builderConversationSubmitInput)
       .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["submitBuilder"]>>),
+    answerBuilderQuestion: publicProcedure
+      .input(builderQuestionResponseInput)
+      .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["answerBuilderQuestion"]>>),
     rateBuilderResponse: publicProcedure
       .input(builderResponseRatingInput)
       .mutation(async () => "PLACEHOLDER_DO_NOT_REMOVE" as unknown as Awaited<ReturnType<ConversationsRouter["rateBuilderResponse"]>>),
diff --git a/apps/api/test/conversations.spec.ts b/apps/api/test/conversations.spec.ts
index 51a40ba1..514c6279 100644
--- a/apps/api/test/conversations.spec.ts
+++ b/apps/api/test/conversations.spec.ts
@@ -25,6 +25,9 @@ let service: ConversationsService;
 let cache: ReturnType<typeof memoryCache>;
 
 beforeAll(async () => {
+	await db.agentEvent.deleteMany({
+		where: { sessionId: { startsWith: `builder-question-${suffix}` } },
+	});
 	await db.agentConversation.deleteMany({ where: { userId } });
 	await db.user.deleteMany({ where: { id: userId } });
 	await db.contact.deleteMany({ where: { email } });
@@ -46,6 +49,9 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
+	await db.agentEvent.deleteMany({
+		where: { sessionId: { startsWith: `builder-question-${suffix}` } },
+	});
 	await db.contact.deleteMany({ where: { email } });
 	await db.agentConversation.deleteMany({ where: { userId } });
 	await db.user.deleteMany({ where: { id: userId } });
@@ -191,4 +197,70 @@ describe("ConversationsService", () => {
 			(await service.builderById(creation.id, userId)).submissions[0],
 		).toMatchObject({ commandType: "CREATE_AGENT" });
 	});
+
+	it("queues a pending builder answer for the CRM-owned Eve channel", async () => {
+		const conversation = await service.createBuilder(
+			{
+				clientRequestId: crypto.randomUUID(),
+				commandType: "CREATE_AGENT",
+				message: "/Create agent Flag overdue invoices",
+				resources: [],
+				attachments: [],
+			},
+			userId,
+		);
+		const sessionId = `builder-question-${suffix}-1`;
+		await db.agentConversation.update({
+			where: { id: conversation.id },
+			data: {
+				sessionId,
+				continuationToken: `crm:builder:${conversation.id}`,
+			},
+		});
+		await db.agentEvent.create({
+			data: {
+				id: `evt_${suffix}_question`,
+				sessionId,
+				type: "input.requested",
+				data: {
+					requests: [
+						{
+							kind: "question",
+							requestId: "question-1",
+							prompt: "Where should this go?",
+							display: "select",
+							options: [{ id: "crm-task", label: "Create a CRM task" }],
+						},
+					],
+				},
+				emittedAt: new Date(),
+			},
+		});
+
+		const response = await service.answerBuilderQuestion(
+			{
+				id: conversation.id,
+				clientRequestId: crypto.randomUUID(),
+				requestId: "question-1",
+				optionId: "crm-task",
+			},
+			userId,
+		);
+		const submission = await db.agentConversationSubmission.findUnique({
+			where: { id: response.id },
+			select: { commandType: true, message: true, status: true },
+		});
+
+		expect(submission).toMatchObject({
+			commandType: "CHAT",
+			status: "PENDING",
+			message: {
+				text: "Create a CRM task",
+				inputResponse: {
+					requestId: "question-1",
+					answer: "crm-task",
+				},
+			},
+		});
+	});
 });
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
index 027122ce..e015c60b 100644
--- a/apps/app/components/agent-builder/agent-builder-chat.tsx
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -20,16 +20,18 @@ import {
 } from "@crm/ui/components/async-action";
 import { Button } from "@crm/ui/components/button";
 import { Icon } from "@crm/ui/components/icon";
-import { Input } from "@crm/ui/components/input";
 import { Markdown } from "@crm/ui/components/markdown";
 import { Skeleton } from "@crm/ui/components/skeleton";
 import { cn } from "@crm/ui/lib/utils";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { MessageStreamEvent } from "eve/client";
-import { useEveAgent } from "eve/react";
 import Link from "next/link";
 import { useState } from "react";
 import { toast } from "sonner";
+import {
+	AgentClarificationComposer,
+	type ClarificationResponse,
+} from "@/components/agent-clarification-composer";
 import {
 	consumeBuilderCommand,
 	hasCreateAgentCommand,
@@ -37,6 +39,7 @@ import {
 import {
 	type AgentTurnFailure,
 	latestTurnFailure,
+	messagesFromEvents,
 	pendingQuestion,
 	toTranscript,
 } from "@/lib/agent-transcript";
@@ -69,12 +72,6 @@ type BuilderSubmission = {
 	errorMessage: string | null;
 };
 
-type ClarificationResponse = {
-	requestId: string;
-	optionId?: string;
-	text?: string;
-};
-
 export function AgentBuilderChat({
 	conversationId,
 }: {
@@ -118,6 +115,24 @@ export function AgentBuilderChat({
 			onError: (error) => toast.error(error.message),
 		}),
 	);
+	const answerQuestion = useMutation(
+		trpc.conversations.answerBuilderQuestion.mutationOptions({
+			onSuccess: async () => {
+				await Promise.all([
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderById.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.builderList.pathKey(),
+					}),
+					queryClient.invalidateQueries({
+						queryKey: trpc.conversations.events.pathKey(),
+					}),
+				]);
+			},
+			onError: (error) => toast.error(error.message),
+		}),
+	);
 	const markRead = useMutation(
 		trpc.conversations.markRead.mutationOptions({
 			onSuccess: () =>
@@ -153,7 +168,16 @@ export function AgentBuilderChat({
 
 	const data = conversation.data;
 	const submissions = data.submissions as BuilderSubmission[];
-	const failure = latestTurnFailure(events.data ?? []);
+	const persistedEvents = (events.data ??
+		[]) as unknown as MessageStreamEvent[];
+	const agentMessages = messagesFromEvents(persistedEvents);
+	const waitingQuestion = pendingQuestion(agentMessages);
+	const question =
+		waitingQuestion &&
+		!hasQueuedQuestionResponse(submissions, waitingQuestion.requestId)
+			? waitingQuestion
+			: null;
+	const failure = latestTurnFailure(persistedEvents);
 	const creatingAgent = hasCreateAgentCommand(submissions);
 	const working = isWorking(data, creatingAgent) && !failure;
 	const awaitingInput = events.data?.at(-1)?.type === "session.waiting";
@@ -197,11 +221,10 @@ export function AgentBuilderChat({
 						/>
 					))}
 
-					{events.data && events.data.length > 0 ? (
+					{agentMessages.length > 0 ? (
 						<AssistantTranscript
-							key={`${events.data.length}:${events.data.at(-1)?.meta.id}`}
 							conversation={data}
-							events={events.data as unknown as MessageStreamEvent[]}
+							agentMessages={agentMessages}
 						/>
 					) : null}
 
@@ -264,12 +287,27 @@ export function AgentBuilderChat({
 
 			<div className="shrink-0 border-t px-4 py-3 sm:px-5">
 				<div className="mx-auto w-full max-w-3xl">
-					<AgentComposer
-						mode="chat"
-						pending={submit.isPending}
-						disabled={working || awaitingInput}
-						onSubmit={send}
-					/>
+					{question ? (
+						<AgentClarificationComposer
+							key={question.requestId}
+							question={question}
+							pending={answerQuestion.isPending}
+							onSubmit={async (response: ClarificationResponse) => {
+								await answerQuestion.mutateAsync({
+									id: conversationId,
+									clientRequestId: crypto.randomUUID(),
+									...response,
+								});
+							}}
+						/>
+					) : (
+						<AgentComposer
+							mode="chat"
+							pending={submit.isPending}
+							disabled={working || awaitingInput}
+							onSubmit={send}
+						/>
+					)}
 				</div>
 			</div>
 		</main>
@@ -333,8 +371,7 @@ function SharedAssistantTranscript({
 }: {
 	events: MessageStreamEvent[];
 }) {
-	const agent = useEveAgent({ initialEvents: events });
-	const messages = toTranscript(agent.data.messages).filter(
+	const messages = toTranscript(messagesFromEvents(events)).filter(
 		(message) => !message.mine,
 	);
 
@@ -468,48 +505,14 @@ function UserSubmission({
 
 function AssistantTranscript({
 	conversation,
-	events,
+	agentMessages,
 }: {
 	conversation: Conversation;
-	events: MessageStreamEvent[];
+	agentMessages: ReturnType<typeof messagesFromEvents>;
 }) {
-	const trpc = useTRPC();
-	const queryClient = useQueryClient();
-	const agent = useEveAgent({
-		headers: { "x-crm-builder-conversation": conversation.id },
-		initialEvents: events,
-		...(conversation.sessionId
-			? {
-					initialSession: {
-						sessionId: conversation.sessionId,
-						streamIndex: conversation.streamIndex,
-						...(conversation.continuationToken
-							? { continuationToken: conversation.continuationToken }
-							: {}),
-					},
-				}
-			: {}),
-		onError: (error) => toast.error(error.message),
-	});
-	const messages = toTranscript(agent.data.messages).filter(
+	const messages = toTranscript(agentMessages).filter(
 		(message) => !message.mine,
 	);
-	const question = pendingQuestion(agent.data.messages);
-	const latestMessageId = messages.at(-1)?.id;
-	const answerQuestion = async (response: ClarificationResponse) => {
-		await agent.send({ inputResponses: [response] });
-		await Promise.all([
-			queryClient.invalidateQueries({
-				queryKey: trpc.conversations.builderById.pathKey(),
-			}),
-			queryClient.invalidateQueries({
-				queryKey: trpc.conversations.builderList.pathKey(),
-			}),
-			queryClient.invalidateQueries({
-				queryKey: trpc.conversations.events.pathKey(),
-			}),
-		]);
-	};
 
 	return (
 		<>
@@ -555,16 +558,6 @@ function AssistantTranscript({
 								markdown={markdown}
 							/>
 						) : null}
-						{question && message.id === latestMessageId ? (
-							<ClarificationCard
-								key={question.requestId}
-								question={question}
-								pending={
-									agent.status === "submitted" || agent.status === "streaming"
-								}
-								onAnswer={answerQuestion}
-							/>
-						) : null}
 					</div>
 				);
 			})}
@@ -572,105 +565,6 @@ function AssistantTranscript({
 	);
 }
 
-function ClarificationCard({
-	question,
-	pending,
-	onAnswer,
-}: {
-	question: NonNullable<ReturnType<typeof pendingQuestion>>;
-	pending: boolean;
-	onAnswer: (response: ClarificationResponse) => Promise<void>;
-}) {
-	const [answer, setAnswer] = useState("");
-	const options = question.options ?? [];
-	const showFreeform =
-		question.display === "text" ||
-		question.allowFreeform === true ||
-		options.length === 0;
-
-	const submitAnswer = () => {
-		const text = answer.trim();
-		if (!text || pending) return;
-		void onAnswer({ requestId: question.requestId, text });
-	};
-
-	return (
-		<div className="ml-3 border-ring/50 border-l-2 pl-3">
-			<div className="rounded-r-lg bg-muted/50 px-3 py-3 sm:px-4">
-				<p className="font-medium text-xs">Before I continue</p>
-				<Markdown className="mt-1 text-pretty text-sm leading-5">
-					{question.prompt}
-				</Markdown>
-
-				{options.length > 0 ? (
-					<div className="mt-3 flex flex-wrap gap-2">
-						{options.map((option) => (
-							<Button
-								key={option.id}
-								type="button"
-								variant={
-									option.style === "danger"
-										? "destructive"
-										: option.style === "primary"
-											? "default"
-											: "outline"
-								}
-								size="sm"
-								className="h-auto min-h-8 max-w-full flex-col items-start whitespace-normal text-left"
-								disabled={pending}
-								onClick={() =>
-									void onAnswer({
-										requestId: question.requestId,
-										optionId: option.id,
-									})
-								}
-							>
-								<span>{option.label}</span>
-								{option.description ? (
-									<span className="font-normal text-current/70 text-xs">
-										{option.description}
-									</span>
-								) : null}
-							</Button>
-						))}
-					</div>
-				) : null}
-
-				{showFreeform ? (
-					<form
-						className="mt-3 flex min-w-0 gap-2"
-						onSubmit={(event) => {
-							event.preventDefault();
-							submitAnswer();
-						}}
-					>
-						<Input
-							value={answer}
-							onChange={(event) => setAnswer(event.target.value)}
-							placeholder="Type another answer"
-							aria-label="Answer the agent's question"
-							disabled={pending}
-						/>
-						<Button
-							type="submit"
-							size="sm"
-							disabled={!answer.trim() || pending}
-						>
-							{pending ? "Sending" : "Send"}
-						</Button>
-					</form>
-				) : null}
-
-				{pending ? (
-					<span className="sr-only" role="status">
-						Sending your answer
-					</span>
-				) : null}
-			</div>
-		</div>
-	);
-}
-
 function ResponseActions({
 	conversation,
 	messageId,
@@ -768,13 +662,9 @@ function BuildingAgentCard({
 	});
 
 	return (
-		<div className="flex flex-col gap-4">
-			<p className="max-w-[640px] text-pretty text-sm leading-5">
-				I’m turning this into a team agent. I’ll inspect the CRM scope, verify
-				the requested connections, then prepare a safe deployment for review.
-			</p>
+		<div className="w-full max-w-sm">
 			<div className="overflow-hidden rounded-lg bg-muted/40">
-				<div className="flex flex-wrap items-center gap-3 px-4 pt-4 pb-2">
+				<div className="flex items-center gap-3 px-4 pt-4 pb-2">
 					<Icon
 						icon={Renew}
 						className="size-3.5 animate-spin text-ring"
@@ -788,7 +678,7 @@ function BuildingAgentCard({
 					</span>
 				</div>
 				<ol
-					className="grid grid-cols-4 gap-2 px-3 py-4 sm:px-4"
+					className="flex flex-col gap-1 px-3 py-3"
 					aria-label="Agent creation"
 				>
 					{steps.map((label, index) => {
@@ -798,17 +688,17 @@ function BuildingAgentCard({
 						return (
 							<li
 								key={label}
-								className="flex min-w-0 flex-col items-center gap-2 text-center"
+								className={cn(
+									"flex min-h-9 min-w-0 items-center gap-3 rounded-md px-2.5 py-2",
+									active && "bg-background",
+								)}
 								aria-current={active ? "step" : undefined}
 							>
 								<span
 									className={cn(
-										"flex size-6 items-center justify-center rounded-full text-[11px]",
-										done && "bg-ring text-background",
-										active && "bg-background text-ring",
-										!done &&
-											!active &&
-											"bg-background/60 text-muted-foreground",
+										"flex size-5 shrink-0 items-center justify-center text-[11px]",
+										(done || active) && "text-ring",
+										!done && !active && "text-muted-foreground",
 									)}
 								>
 									{done ? (
@@ -825,19 +715,22 @@ function BuildingAgentCard({
 								</span>
 								<span
 									className={cn(
-										"min-w-0 wrap-break-word text-[11px] leading-4 sm:text-xs",
+										"min-w-0 flex-1 wrap-break-word text-xs",
 										!done && !active && "text-muted-foreground",
 									)}
 								>
 									{label}
 								</span>
+								<span className="shrink-0 text-muted-foreground text-[11px]">
+									{done ? "Done" : active ? "Working" : "Queued"}
+								</span>
 							</li>
 						);
 					})}
 				</ol>
-				<footer className="flex min-h-12 flex-wrap items-center gap-3 bg-background/55 px-4 py-2.5">
+				<footer className="flex min-h-12 items-center gap-3 bg-background/55 px-4 py-2.5">
 					<p className="min-w-0 flex-1 text-pretty text-muted-foreground text-xs">
-						You can leave this chat. I’ll keep working in the background.
+						Runs in the background
 					</p>
 					<Button
 						variant="ghost"
@@ -1217,11 +1110,26 @@ function builderMessageOf(message: unknown) {
 	};
 }
 
+function hasQueuedQuestionResponse(
+	submissions: BuilderSubmission[],
+	requestId: string,
+): boolean {
+	return submissions.some((submission) => {
+		if (submission.status === "FAILED" || submission.status === "CANCELLED") {
+			return false;
+		}
+
+		const response = recordOf(recordOf(submission.message).inputResponse);
+		return response.requestId === requestId;
+	});
+}
+
 function retryPromptOf(
 	submission: BuilderSubmission | undefined,
 ): BuilderPrompt | null {
 	if (!submission) return null;
 	const row = recordOf(submission.message);
+	if (Object.keys(recordOf(row.inputResponse)).length > 0) return null;
 	if (typeof row.text !== "string" || !row.text.trim()) return null;
 
 	return {
diff --git a/apps/app/components/agent-builder/agent-composer.tsx b/apps/app/components/agent-builder/agent-composer.tsx
index d79aa4bd..4a7f2d73 100644
--- a/apps/app/components/agent-builder/agent-composer.tsx
+++ b/apps/app/components/agent-builder/agent-composer.tsx
@@ -21,6 +21,7 @@ import {
 } from "@crm/ui/components/popover";
 import { Skeleton } from "@crm/ui/components/skeleton";
 import { SkeletonSwap } from "@crm/ui/components/skeleton-swap";
+import { Textarea } from "@crm/ui/components/textarea";
 import { cn } from "@crm/ui/lib/utils";
 import { useQuery } from "@tanstack/react-query";
 import { useRef, useState } from "react";
@@ -31,6 +32,7 @@ import {
 	consumeBuilderCommand,
 } from "@/lib/agent-builder";
 import { useTRPC } from "@/lib/trpc/client";
+import { AGENT_COMPOSER_CLASS_NAME } from "../agent-composer-frame";
 import {
 	ChatAttachmentChip,
 	type ChatChipAttachment,
@@ -136,7 +138,7 @@ export function AgentComposer({
 	return (
 		<div
 			className={cn(
-				"flex w-full flex-col justify-between rounded-lg border bg-muted p-[11px] shadow-[inset_0_1px_1px_rgb(0_0_0/0.12)] transition-colors focus-within:border-muted-foreground/60 focus-within:ring-1 focus-within:ring-ring/40",
+				AGENT_COMPOSER_CLASS_NAME,
 				mode === "home" ? "min-h-24" : "min-h-[78px]",
 			)}
 		>
@@ -178,7 +180,7 @@ export function AgentComposer({
 				</div>
 			) : null}
 
-			<textarea
+			<Textarea
 				value={draft}
 				onChange={(event) => updateDraft(event.target.value)}
 				onKeyDown={(event) => {
@@ -189,13 +191,14 @@ export function AgentComposer({
 				}}
 				disabled={disabled}
 				rows={mode === "home" ? 2 : 1}
+				variant="composer"
+				size="composer"
 				placeholder={
 					mode === "home"
 						? "Ask about your CRM or automate a task…"
 						: "Send a message"
 				}
 				aria-label="Message the agent builder"
-				className="max-h-40 min-h-6 w-full resize-none bg-transparent px-1 text-base leading-6 outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-60 sm:text-[15px]"
 			/>
 
 			<div className="flex h-7 items-center justify-between">
diff --git a/apps/app/components/agent-clarification-composer.tsx b/apps/app/components/agent-clarification-composer.tsx
new file mode 100644
index 00000000..8f0ccb5e
--- /dev/null
+++ b/apps/app/components/agent-clarification-composer.tsx
@@ -0,0 +1,160 @@
+"use client";
+
+import { AsyncButtonContent } from "@crm/ui/components/async-action";
+import { Button } from "@crm/ui/components/button";
+import { Markdown } from "@crm/ui/components/markdown";
+import { Textarea } from "@crm/ui/components/textarea";
+import { ToggleGroup, ToggleGroupItem } from "@crm/ui/components/toggle-group";
+import type { EveMessageInputRequest } from "eve/react";
+import { useId, useState } from "react";
+import { AGENT_COMPOSER_CLASS_NAME } from "./agent-composer-frame";
+
+export type ClarificationResponse = {
+	requestId: string;
+	optionId?: string;
+	text?: string;
+};
+
+export function AgentClarificationComposer({
+	question,
+	pending,
+	onSubmit,
+}: {
+	question: EveMessageInputRequest;
+	pending: boolean;
+	onSubmit: (response: ClarificationResponse) => Promise<void>;
+}) {
+	const answerId = useId();
+	const errorId = `${answerId}-error`;
+	const [selectedOptionId, setSelectedOptionId] = useState("");
+	const [answer, setAnswer] = useState("");
+	const [error, setError] = useState<string | null>(null);
+	const options = question.options ?? [];
+	const showFreeform =
+		question.display === "text" ||
+		question.allowFreeform === true ||
+		options.length === 0;
+	const selectedOption = options.find(
+		(option) => option.id === selectedOptionId,
+	);
+
+	const submit = async () => {
+		if (pending) return;
+		const text = answer.trim();
+		if (!selectedOptionId && !text) {
+			setError(
+				options.length > 0
+					? "Choose an answer before submitting."
+					: "Write an answer before submitting.",
+			);
+			return;
+		}
+
+		setError(null);
+		try {
+			await onSubmit(
+				selectedOptionId
+					? { requestId: question.requestId, optionId: selectedOptionId }
+					: { requestId: question.requestId, text },
+			);
+		} catch {
+			setError("Unable to submit. Check your connection and try again.");
+		}
+	};
+
+	return (
+		<form
+			className={AGENT_COMPOSER_CLASS_NAME}
+			onSubmit={(event) => {
+				event.preventDefault();
+				void submit();
+			}}
+		>
+			<div className="px-1 pt-0.5">
+				<p className="font-medium text-xs">Quick follow-up</p>
+				<Markdown className="mt-1 max-h-48 overflow-y-auto text-pretty text-sm leading-5">
+					{question.prompt}
+				</Markdown>
+			</div>
+
+			{options.length > 0 ? (
+				<div className="mt-3">
+					<ToggleGroup
+						type="single"
+						orientation="vertical"
+						variant="outline"
+						size="choice"
+						value={selectedOptionId}
+						disabled={pending}
+						onValueChange={(value) => {
+							setSelectedOptionId(value);
+							if (value) setAnswer("");
+							setError(null);
+						}}
+					>
+						{options.map((option) => (
+							<ToggleGroupItem key={option.id} value={option.id}>
+								<span className="w-full wrap-break-word font-medium">
+									{option.label}
+								</span>
+								{option.description ? (
+									<span className="w-full wrap-break-word font-normal text-muted-foreground text-xs">
+										{option.description}
+									</span>
+								) : null}
+							</ToggleGroupItem>
+						))}
+					</ToggleGroup>
+				</div>
+			) : null}
+
+			{showFreeform ? (
+				<div className="mt-3 px-1">
+					<label
+						htmlFor={answerId}
+						className="font-medium text-muted-foreground text-xs"
+					>
+						{options.length > 0 ? "Or write an answer" : "Your answer"}
+						<Textarea
+							id={answerId}
+							value={answer}
+							onChange={(event) => {
+								setAnswer(event.target.value);
+								if (event.target.value) setSelectedOptionId("");
+								setError(null);
+							}}
+							placeholder="Add the detail the agent needs"
+							variant="composer"
+							rows={2}
+							disabled={pending}
+							aria-invalid={Boolean(error)}
+							aria-describedby={error ? errorId : undefined}
+						/>
+					</label>
+				</div>
+			) : null}
+
+			<div className="mt-3 flex min-h-7 items-center justify-between gap-3 px-1">
+				{error ? (
+					<p id={errorId} role="alert" className="text-destructive text-xs">
+						{error}
+					</p>
+				) : (
+					<p className="min-w-0 truncate text-muted-foreground text-xs">
+						{selectedOption
+							? `Selected: ${selectedOption.label}`
+							: "Choose an answer, then submit."}
+					</p>
+				)}
+				<Button type="submit" size="sm" disabled={pending} aria-busy={pending}>
+					<AsyncButtonContent
+						status={pending ? "pending" : "idle"}
+						pendingLabel="Submitting"
+					>
+						Submit answer
+					</AsyncButtonContent>
+				</Button>
+			</div>
+		</form>
+	);
+}
diff --git a/apps/app/components/agent-composer-frame.ts b/apps/app/components/agent-composer-frame.ts
new file mode 100644
index 00000000..d7edc8d4
--- /dev/null
+++ b/apps/app/components/agent-composer-frame.ts
@@ -0,0 +1,2 @@
+export const AGENT_COMPOSER_CLASS_NAME =
+	"flex w-full flex-col justify-between rounded-lg border bg-muted p-[11px] shadow-[inset_0_1px_1px_rgb(0_0_0/0.12)] transition-colors focus-within:border-muted-foreground/60 focus-within:ring-1 focus-within:ring-ring/40";
diff --git a/apps/app/components/crm/agent-panel.tsx b/apps/app/components/crm/agent-panel.tsx
index 69526906..a900a65a 100644
--- a/apps/app/components/crm/agent-panel.tsx
+++ b/apps/app/components/crm/agent-panel.tsx
@@ -47,6 +47,7 @@ import { Spinner } from "@crm/ui/components/spinner";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useEveAgent } from "eve/react";
 import { useEffect, useRef, useState } from "react";
+import { AgentClarificationComposer } from "@/components/agent-clarification-composer";
 import {
 	type Conversation,
 	ConversationPicker,
@@ -235,12 +236,6 @@ function Thread({
 									</div>
 								</MessageScrollerItem>
 							))}
-
-							{question ? (
-								<MessageScrollerItem messageId={question.requestId}>
-									<Question question={question} agent={agent} />
-								</MessageScrollerItem>
-							) : null}
 						</MessageScrollerContent>
 					</MessageScrollerViewport>
 
@@ -268,29 +263,40 @@ function Thread({
 				</div>
 			) : null}
 
-			<form
-				className="flex min-w-0 items-center gap-2 border-t px-4 py-3 sm:px-5"
-				onSubmit={(event) => {
-					event.preventDefault();
-					ask(draft);
-				}}
-			>
-				<Input
-					value={draft}
-					onChange={(event) => setDraft(event.target.value)}
-					placeholder={copy.placeholder}
-					disabled={locked}
-				/>
-				<Button
-					type="submit"
-					size="icon-sm"
-					variant="outline"
-					disabled={locked}
-				>
-					{busy ? <Spinner /> : <Icon icon={Send} />}
-					<span className="sr-only">Ask</span>
-				</Button>
-			</form>
+			<div className="border-t px-4 py-3 sm:px-5">
+				{question ? (
+					<AgentClarificationComposer
+						key={question.requestId}
+						question={question}
+						pending={busy}
+						onSubmit={(response) => agent.send({ inputResponses: [response] })}
+					/>
+				) : (
+					<form
+						className="flex min-w-0 items-center gap-2"
+						onSubmit={(event) => {
+							event.preventDefault();
+							ask(draft);
+						}}
+					>
+						<Input
+							value={draft}
+							onChange={(event) => setDraft(event.target.value)}
+							placeholder={copy.placeholder}
+							disabled={locked}
+						/>
+						<Button
+							type="submit"
+							size="icon-sm"
+							variant="outline"
+							disabled={locked}
+						>
+							{busy ? <Spinner /> : <Icon icon={Send} />}
+							<span className="sr-only">Ask</span>
+						</Button>
+					</form>
+				)}
+			</div>
 		</div>
 	);
 }
@@ -432,46 +438,6 @@ function AgentAvatar() {
 	);
 }
 
-function Question({
-	question,
-	agent,
-}: {
-	question: NonNullable<ReturnType<typeof pendingQuestion>>;
-	agent: ReturnType<typeof useEveAgent>;
-}) {
-	return (
-		<Message className="min-w-0">
-			<AgentAvatar />
-			<MessageContent>
-				<Bubble variant="tinted">
-					<BubbleContent className="text-pretty">
-						{question.prompt}
-					</BubbleContent>
-				</Bubble>
-
-				<div className="flex flex-wrap gap-2">
-					{(question.options ?? []).map((option) => (
-						<Button
-							key={option.id}
-							variant="outline"
-							size="sm"
-							onClick={() =>
-								void agent.send({
-									inputResponses: [
-										{ requestId: question.requestId, optionId: option.id },
-									],
-								})
-							}
-						>
-							{option.label}
-						</Button>
-					))}
-				</div>
-			</MessageContent>
-		</Message>
-	);
-}
-
 function useSavedConversation({
 	record,
 	conversation,
diff --git a/apps/app/lib/agent-transcript.ts b/apps/app/lib/agent-transcript.ts
index 7b11f7fe..cba963bf 100644
--- a/apps/app/lib/agent-transcript.ts
+++ b/apps/app/lib/agent-transcript.ts
@@ -1,4 +1,9 @@
-import type { EveMessage, EveMessagePart } from "eve/react";
+import type { MessageStreamEvent } from "eve/client";
+import {
+	defaultMessageReducer,
+	type EveMessage,
+	type EveMessagePart,
+} from "eve/react";
 
 export type TranscriptItem =
 	| { kind: "said"; id: string; mine: boolean; text: string }
@@ -76,6 +81,17 @@ export type TranscriptMessage = {
 	items: TranscriptItem[];
 };
 
+export function messagesFromEvents(
+	events: readonly MessageStreamEvent[],
+): readonly EveMessage[] {
+	const reducer = defaultMessageReducer();
+	let data = reducer.initial();
+
+	for (const event of events) data = reducer.reduce(data, event);
+
+	return data.messages;
+}
+
 export function toTranscript(
 	messages: readonly EveMessage[],
 ): TranscriptMessage[] {
diff --git a/packages/ui/src/components/textarea.tsx b/packages/ui/src/components/textarea.tsx
index 74e4801a..27cc72ac 100644
--- a/packages/ui/src/components/textarea.tsx
+++ b/packages/ui/src/components/textarea.tsx
@@ -6,14 +6,24 @@ const textareaVariants = cva(
 	"flex field-sizing-content w-full rounded-md border border-input bg-background px-2.5 py-2 text-xs transition-colors outline-none placeholder:text-muted-foreground hover:border-ring/40 focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/40 disabled:cursor-not-allowed disabled:bg-muted disabled:opacity-60 aria-invalid:border-destructive aria-invalid:ring-2 aria-invalid:ring-destructive/25 md:text-xs dark:bg-muted dark:shadow-[inset_0_1px_1px_rgb(0_0_0/0.30)] dark:disabled:bg-muted",
 	{
 		variants: {
-			size: { default: "min-h-16", sm: "min-h-8" },
+			variant: {
+				default: "",
+				composer:
+					"resize-none rounded-none border-transparent bg-transparent px-1 py-0 text-base leading-6 shadow-none ring-0 hover:border-transparent focus-visible:border-transparent focus-visible:ring-0 disabled:bg-transparent sm:text-[15px] dark:bg-transparent dark:shadow-none dark:disabled:bg-transparent",
+			},
+			size: {
+				default: "min-h-16",
+				sm: "min-h-8",
+				composer: "max-h-40 min-h-6",
+			},
 		},
-		defaultVariants: { size: "default" },
+		defaultVariants: { variant: "default", size: "default" },
 	},
 );
 
 function Textarea({
 	className,
+	variant,
 	size,
 	...props
 }: Omit<React.ComponentProps<"textarea">, "size"> &
@@ -21,7 +31,7 @@ function Textarea({
 	return (
 		<textarea
 			data-slot="textarea"
-			className={cn(textareaVariants({ size }), className)}
+			className={cn(textareaVariants({ variant, size }), className)}
 			{...props}
 		/>
 	);
diff --git a/packages/ui/src/components/toggle-group.tsx b/packages/ui/src/components/toggle-group.tsx
index a21fac66..86a125eb 100644
--- a/packages/ui/src/components/toggle-group.tsx
+++ b/packages/ui/src/components/toggle-group.tsx
@@ -40,7 +40,7 @@ function ToggleGroup({
 			data-orientation={orientation}
 			style={{ "--gap": spacing } as React.CSSProperties}
 			className={cn(
-				"group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-md data-[size=sm]:rounded-md data-vertical:flex-col data-vertical:items-stretch",
+				"group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-md data-[size=sm]:rounded-md data-vertical:w-full data-vertical:flex-col data-vertical:items-stretch",
 				className,
 			)}
 			{...props}
diff --git a/packages/ui/src/components/toggle.tsx b/packages/ui/src/components/toggle.tsx
index b9822f14..4ef67527 100644
--- a/packages/ui/src/components/toggle.tsx
+++ b/packages/ui/src/components/toggle.tsx
@@ -11,13 +11,16 @@ const toggleVariants = cva(
 		variants: {
 			variant: {
 				default: "bg-transparent",
-				outline: "border border-input bg-transparent hover:bg-muted",
+				outline:
+					"border border-input bg-transparent hover:bg-muted data-[state=on]:border-ring data-[state=on]:bg-background data-[state=on]:ring-1 data-[state=on]:ring-ring/30",
 			},
 			size: {
 				default:
 					"h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
 				sm: "h-7 min-w-7 rounded-md px-2.5 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5",
 				lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+				choice:
+					"h-auto min-h-10 w-full flex-col items-start gap-0.5 px-3 py-2 text-left whitespace-normal",
 			},
 		},
 		defaultVariants: {

From f923dfd38ef4efdd138fdb12af7ccfc30278938e Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Tue, 4 Aug 2026 23:43:40 -0700
Subject: [PATCH 7/7] CMP-46 fix: interleave follow-up answers in chat

---
 apps/agent/agent/instructions/task.ts         |   2 +-
 apps/agent/test/custom-agent-runtime.spec.ts  |   5 +-
 .../agent-builder/agent-builder-chat.tsx      | 303 +++++++++++-------
 .../agent-clarification-composer.tsx          |  16 +-
 apps/app/components/crm/agent-panel.tsx       |  11 +
 apps/app/lib/agent-transcript.ts              |  83 +++++
 apps/app/test/agent-transcript.spec.ts        |  84 ++++-
 packages/ui/src/components/toggle.tsx         |   2 +-
 8 files changed, 374 insertions(+), 132 deletions(-)

diff --git a/apps/agent/agent/instructions/task.ts b/apps/agent/agent/instructions/task.ts
index de9a2abc..e1b05ccd 100644
--- a/apps/agent/agent/instructions/task.ts
+++ b/apps/agent/agent/instructions/task.ts
@@ -58,7 +58,7 @@ function builderInstructions(ctx: Parameters<typeof purposeOf>[0]) {
 export function builderTaskMarkdown(commandType: string | null): string {
 	return commandType === "CREATE_AGENT"
 		? `This private CRM chat turn used the Create agent command. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. Relay the specialist's result in concise product language. If the specialist says an essential decision is unclear, call ask_question instead of replying with a plain-text question. Ask exactly one decision at a time and never bundle several missing details into one prompt. Offer two to four mutually exclusive options when they clarify a real choice, and allow a freeform answer when a custom response is valid. After the answer, ask another question only if the build remains materially blocked. Ask only when the answer materially changes the trigger, records, integrations, schedule, outcome, or side effect. Do not interrupt a sufficiently specific request or ask about optional polish. If it saved a draft, explain that it is ready for human review and is not deployed yet.`
-		: `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. The user must explicitly run the Create agent slash command before agent creation begins. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`;
+		: `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. If one materially necessary decision is missing, call ask_question with one focused follow-up instead of guessing; do not interrupt for optional detail. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. The user must explicitly run the Create agent slash command before agent creation begins. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`;
 }
 
 function asString(value: unknown): string | null {
diff --git a/apps/agent/test/custom-agent-runtime.spec.ts b/apps/agent/test/custom-agent-runtime.spec.ts
index 2d14c965..fd5a726e 100644
--- a/apps/agent/test/custom-agent-runtime.spec.ts
+++ b/apps/agent/test/custom-agent-runtime.spec.ts
@@ -76,7 +76,10 @@ describe("builder command routing", () => {
 		expect(creation).toContain(
 			"Do not interrupt a sufficiently specific request",
 		);
-		expect(builderTaskMarkdown("CHAT")).toContain("Do not call agent_builder");
+		const chat = builderTaskMarkdown("CHAT");
+		expect(chat).toContain("Do not call agent_builder");
+		expect(chat).toContain("call ask_question");
+		expect(chat).toContain("one focused follow-up");
 		expect(builderTaskMarkdown(null)).toContain("private CRM assistant chat");
 	});
 });
diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx
index e015c60b..cefb91ca 100644
--- a/apps/app/components/agent-builder/agent-builder-chat.tsx
+++ b/apps/app/components/agent-builder/agent-builder-chat.tsx
@@ -10,6 +10,7 @@ import Copy from "@carbon/icons-react/es/Copy";
 import Partnership from "@carbon/icons-react/es/Partnership";
 import Play from "@carbon/icons-react/es/Play";
 import Renew from "@carbon/icons-react/es/Renew";
+import Reply from "@carbon/icons-react/es/Reply";
 import ThumbsDown from "@carbon/icons-react/es/ThumbsDown";
 import ThumbsUp from "@carbon/icons-react/es/ThumbsUp";
 import User from "@carbon/icons-react/es/User";
@@ -25,6 +26,7 @@ import { Skeleton } from "@crm/ui/components/skeleton";
 import { cn } from "@crm/ui/lib/utils";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { MessageStreamEvent } from "eve/client";
+import type { EveMessage, EveMessageInputRequest } from "eve/react";
 import Link from "next/link";
 import { useState } from "react";
 import { toast } from "sonner";
@@ -38,6 +40,7 @@ import {
 } from "@/lib/agent-builder";
 import {
 	type AgentTurnFailure,
+	conversationTimeline,
 	latestTurnFailure,
 	messagesFromEvents,
 	pendingQuestion,
@@ -66,6 +69,7 @@ type DraftVersion = {
 
 type BuilderSubmission = {
 	id: string;
+	createdAt: string;
 	commandType: "CHAT" | "CREATE_AGENT";
 	message: unknown;
 	status: string;
@@ -171,6 +175,12 @@ export function AgentBuilderChat({
 	const persistedEvents = (events.data ??
 		[]) as unknown as MessageStreamEvent[];
 	const agentMessages = messagesFromEvents(persistedEvents);
+	const timeline = conversationTimeline(
+		submissions,
+		persistedEvents,
+		agentMessages,
+	);
+	const answeredQuestionIds = questionResponseIds(submissions);
 	const waitingQuestion = pendingQuestion(agentMessages);
 	const question =
 		waitingQuestion &&
@@ -212,21 +222,23 @@ export function AgentBuilderChat({
 
 			<div className="min-h-0 flex-1 overflow-y-auto">
 				<div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 py-6 sm:gap-5 sm:px-5 sm:py-9">
-					{submissions.map((submission) => (
-						<UserSubmission
-							key={submission.id}
-							submission={submission}
-							failed={submission.status === "FAILED"}
-							error={submission.errorMessage}
-						/>
-					))}
-
-					{agentMessages.length > 0 ? (
-						<AssistantTranscript
-							conversation={data}
-							agentMessages={agentMessages}
-						/>
-					) : null}
+					{timeline.map((item) =>
+						item.kind === "submission" ? (
+							<UserSubmission
+								key={item.id}
+								submission={item.submission}
+								failed={item.submission.status === "FAILED"}
+								error={item.submission.errorMessage}
+							/>
+						) : (
+							<AssistantMessage
+								key={item.id}
+								conversation={data}
+								message={item.message}
+								answeredQuestionIds={answeredQuestionIds}
+							/>
+						),
+					)}
 
 					{working && creatingAgent ? (
 						<BuildingAgentCard
@@ -319,8 +331,12 @@ function SharedAgentChat({
 }: {
 	conversation: SharedConversation;
 }) {
-	const submissions = conversation.submissions as BuilderSubmission[];
+	const submissions =
+		conversation.submissions as unknown as BuilderSubmission[];
 	const events = conversation.events as unknown as MessageStreamEvent[];
+	const messages = messagesFromEvents(events);
+	const timeline = conversationTimeline(submissions, events, messages);
+	const answeredQuestionIds = questionResponseIds(submissions);
 
 	return (
 		<main className="flex min-h-0 flex-1 flex-col">
@@ -341,18 +357,23 @@ function SharedAgentChat({
 						</p>
 					</div>
 
-					{submissions.map((submission) => (
-						<UserSubmission
-							key={submission.id}
-							submission={submission}
-							failed={submission.status === "FAILED"}
-							error={submission.errorMessage}
-						/>
-					))}
-
-					{events.length > 0 ? (
-						<SharedAssistantTranscript events={events} />
-					) : null}
+					{timeline.map((item) =>
+						item.kind === "submission" ? (
+							<UserSubmission
+								key={item.id}
+								submission={item.submission}
+								failed={item.submission.status === "FAILED"}
+								error={item.submission.errorMessage}
+							/>
+						) : (
+							<AssistantMessage
+								key={item.id}
+								conversation={null}
+								message={item.message}
+								answeredQuestionIds={answeredQuestionIds}
+							/>
+						),
+					)}
 
 					{conversation.builderArtifacts.length > 0 ? (
 						<AgentCodeWorkspace
@@ -366,45 +387,6 @@ function SharedAgentChat({
 	);
 }
 
-function SharedAssistantTranscript({
-	events,
-}: {
-	events: MessageStreamEvent[];
-}) {
-	const messages = toTranscript(messagesFromEvents(events)).filter(
-		(message) => !message.mine,
-	);
-
-	return messages.map((message) => {
-		const markdown = message.items
-			.filter((item) => item.kind === "said")
-			.map((item) => item.text)
-			.join("\n\n");
-
-		return markdown ? (
-			<div
-				key={message.id}
-				className="flex w-full min-w-0 max-w-[640px] flex-col gap-2"
-			>
-				<Markdown className="wrap-break-word text-sm leading-5">
-					{markdown}
-				</Markdown>
-				<Button
-					variant="ghost"
-					size="icon-xs"
-					aria-label="Copy response as Markdown"
-					onClick={() => {
-						void navigator.clipboard.writeText(markdown);
-						toast.success("Response copied as Markdown.");
-					}}
-				>
-					<Icon icon={Copy} />
-				</Button>
-			</div>
-		) : null;
-	});
-}
-
 function ChatHeader({
 	conversation,
 	working,
@@ -466,10 +448,23 @@ function UserSubmission({
 			? consumeBuilderCommand(message.text)
 			: null;
 	const text = command?.body ?? message.text;
+	const response = inputResponseOf(submission.message);
 
 	return (
 		<div className="flex min-w-0 w-full justify-end">
-			<div className="flex w-fit min-w-0 max-w-full flex-col gap-2 rounded-md bg-muted px-3 py-2.5 text-sm leading-5 sm:max-w-[620px] sm:px-3.5 sm:py-3">
+			<div
+				className={cn(
+					"flex w-fit min-w-0 max-w-full flex-col gap-2 rounded-md bg-muted px-3 py-2.5 text-sm leading-5 sm:max-w-[620px] sm:px-3.5 sm:py-3",
+					response &&
+						"max-w-sm gap-1.5 border-ring border-r-2 bg-muted/70 py-2 sm:max-w-sm sm:py-2.5",
+				)}
+			>
+				{response ? (
+					<div className="flex items-center gap-1.5 text-muted-foreground text-xs">
+						<Icon icon={Reply} className="size-3.5" />
+						<span>Answer to follow-up</span>
+					</div>
+				) : null}
 				{submission.commandType === "CREATE_AGENT" ? (
 					<div className="flex flex-wrap gap-1">
 						<ChatCommandChip label="Create agent" icon={Application} />
@@ -503,65 +498,112 @@ function UserSubmission({
 	);
 }
 
-function AssistantTranscript({
+function AssistantMessage({
 	conversation,
-	agentMessages,
+	message,
+	answeredQuestionIds,
 }: {
-	conversation: Conversation;
-	agentMessages: ReturnType<typeof messagesFromEvents>;
+	conversation: Conversation | null;
+	message: EveMessage;
+	answeredQuestionIds: ReadonlySet<string>;
 }) {
-	const messages = toTranscript(agentMessages).filter(
-		(message) => !message.mine,
-	);
+	const [transcript] = toTranscript([message]);
+	if (!transcript || transcript.mine) return null;
+
+	const markdown = transcript.items
+		.filter((item) => item.kind === "said")
+		.map((item) => item.text)
+		.join("\n\n");
 
 	return (
-		<>
-			{messages.map((message) => {
-				const markdown = message.items
-					.filter((item) => item.kind === "said")
-					.map((item) => item.text)
-					.join("\n\n");
-
-				return (
+		<div className="flex w-full min-w-0 max-w-[640px] flex-col gap-2">
+			{markdown ? (
+				<Markdown className="wrap-break-word text-sm leading-5">
+					{markdown}
+				</Markdown>
+			) : null}
+			{transcript.items.map((item) =>
+				item.kind === "asked" &&
+				(conversation === null ||
+					answeredQuestionIds.has(item.question.requestId)) ? (
+					<FollowUpTranscriptItem
+						key={item.id}
+						question={item.question}
+						answered={answeredQuestionIds.has(item.question.requestId)}
+					/>
+				) : null,
+			)}
+			{transcript.items
+				.filter((item) => item.kind === "did")
+				.map((item) => (
 					<div
-						key={message.id}
-						className="flex w-full min-w-0 max-w-[640px] flex-col gap-2"
+						key={item.id}
+						className="flex min-w-0 items-start gap-2 text-muted-foreground text-xs"
 					>
-						{markdown ? (
-							<Markdown className="wrap-break-word text-sm leading-5">
-								{markdown}
-							</Markdown>
-						) : null}
-						{message.items
-							.filter((item) => item.kind === "did")
-							.map((item) => (
-								<div
-									key={item.id}
-									className="flex min-w-0 items-start gap-2 text-muted-foreground text-xs"
-								>
-									{item.pending ? (
-										<Icon
-											icon={Renew}
-											className="size-3.5 animate-spin"
-											motion="none"
-										/>
-									) : (
-										<Icon icon={Checkmark} className="size-3.5 text-ring" />
-									)}
-									<span className="min-w-0 wrap-break-word">{item.label}</span>
-								</div>
-							))}
-						{markdown ? (
-							<ResponseActions
-								conversation={conversation}
-								messageId={message.id}
-								markdown={markdown}
+						{item.pending ? (
+							<Icon
+								icon={Renew}
+								className="size-3.5 animate-spin"
+								motion="none"
 							/>
-						) : null}
+						) : (
+							<Icon icon={Checkmark} className="size-3.5 text-ring" />
+						)}
+						<span className="min-w-0 wrap-break-word">{item.label}</span>
 					</div>
-				);
-			})}
-		</>
+				))}
+			{markdown ? (
+				conversation ? (
+					<ResponseActions
+						conversation={conversation}
+						messageId={transcript.id}
+						markdown={markdown}
+					/>
+				) : (
+					<CopyResponseAction markdown={markdown} />
+				)
+			) : null}
+		</div>
+	);
+}
+
+function FollowUpTranscriptItem({
+	question,
+	answered,
+}: {
+	question: EveMessageInputRequest;
+	answered: boolean;
+}) {
+	return (
+		<div className="w-full max-w-sm border-ring/50 border-l-2 bg-muted/40 px-3 py-2.5">
+			<div className="flex items-center justify-between gap-3 text-xs">
+				<span className="font-medium">Follow-up</span>
+				<span className="text-muted-foreground">
+					{answered ? "Answered" : "Waiting for your answer"}
+				</span>
+			</div>
+			<Markdown className="mt-1.5 max-h-24 overflow-y-auto wrap-break-word text-sm leading-5">
+				{question.prompt}
+			</Markdown>
+		</div>
+	);
+}
+
+function CopyResponseAction({ markdown }: { markdown: string }) {
+	return (
+		<div className="flex h-7 items-center">
+			<Button
+				variant="ghost"
+				size="icon-xs"
+				aria-label="Copy response as Markdown"
+				onClick={() => {
+					void navigator.clipboard.writeText(markdown);
+					toast.success("Response copied as Markdown.");
+				}}
+			>
+				<Icon icon={Copy} />
+			</Button>
+		</div>
 	);
 }
 
@@ -1119,11 +1161,32 @@ function hasQueuedQuestionResponse(
 			return false;
 		}
 
-		const response = recordOf(recordOf(submission.message).inputResponse);
-		return response.requestId === requestId;
+		return inputResponseOf(submission.message)?.requestId === requestId;
 	});
 }
 
+function questionResponseIds(
+	submissions: readonly BuilderSubmission[],
+): ReadonlySet<string> {
+	return new Set(
+		submissions.flatMap((submission) => {
+			if (submission.status === "FAILED" || submission.status === "CANCELLED") {
+				return [];
+			}
+
+			const response = inputResponseOf(submission.message);
+			return response ? [response.requestId] : [];
+		}),
+	);
+}
+
+function inputResponseOf(message: unknown): { requestId: string } | null {
+	const response = recordOf(recordOf(message).inputResponse);
+	return typeof response.requestId === "string" && response.requestId
+		? { requestId: response.requestId }
+		: null;
+}
+
 function retryPromptOf(
 	submission: BuilderSubmission | undefined,
 ): BuilderPrompt | null {
diff --git a/apps/app/components/agent-clarification-composer.tsx b/apps/app/components/agent-clarification-composer.tsx
index 8f0ccb5e..c3d1a3c8 100644
--- a/apps/app/components/agent-clarification-composer.tsx
+++ b/apps/app/components/agent-clarification-composer.tsx
@@ -72,18 +72,19 @@ export function AgentClarificationComposer({
 		>
 			<div className="px-1 pt-0.5">
 				<p className="font-medium text-xs">Quick follow-up</p>
-				<Markdown className="mt-1 max-h-48 overflow-y-auto text-pretty text-sm leading-5">
+				<Markdown className="mt-1 max-h-32 overflow-y-auto text-pretty text-sm leading-5">
 					{question.prompt}
 				</Markdown>
 			</div>
 
 			{options.length > 0 ? (
-				<div className="mt-3">
+				<div className="mt-2">
 					<ToggleGroup
 						type="single"
 						orientation="vertical"
 						variant="outline"
 						size="choice"
+						spacing={1}
 						value={selectedOptionId}
 						disabled={pending}
 						onValueChange={(value) => {
@@ -94,11 +95,11 @@ export function AgentClarificationComposer({
 					>
 						{options.map((option) => (
 							<ToggleGroupItem key={option.id} value={option.id}>
-								<span className="w-full wrap-break-word font-medium">
+								<span className="w-full wrap-break-word font-medium leading-4">
 									{option.label}
 								</span>
 								{option.description ? (
-									<span className="w-full wrap-break-word font-normal text-muted-foreground text-xs">
+									<span className="w-full wrap-break-word font-normal text-[11px] text-muted-foreground leading-4">
 										{option.description}
 									</span>
 								) : null}
@@ -109,7 +110,7 @@ export function AgentClarificationComposer({
 			) : null}
 
 			{showFreeform ? (
-				<div className="mt-3 px-1">
+				<div className="mt-2 px-1">
 					<label
 						htmlFor={answerId}
 						className="font-medium text-muted-foreground text-xs"
@@ -125,7 +126,8 @@ export function AgentClarificationComposer({
 							}}
 							placeholder="Add the detail the agent needs"
 							variant="composer"
-							rows={2}
+							size="composer"
+							rows={1}
 							disabled={pending}
 							aria-invalid={Boolean(error)}
 							aria-describedby={error ? errorId : undefined}
@@ -134,7 +136,7 @@ export function AgentClarificationComposer({
 				</div>
 			) : null}
 
-			<div className="mt-3 flex min-h-7 items-center justify-between gap-3 px-1">
+			<div className="mt-2 flex min-h-7 items-center justify-between gap-3 px-1">
 				{error ? (
 					<p id={errorId} role="alert" className="text-destructive text-xs">
 						{error}
diff --git a/apps/app/components/crm/agent-panel.tsx b/apps/app/components/crm/agent-panel.tsx
index a900a65a..11c1594b 100644
--- a/apps/app/components/crm/agent-panel.tsx
+++ b/apps/app/components/crm/agent-panel.tsx
@@ -391,6 +391,17 @@ function Item({ item }: { item: TranscriptItem }) {
 		);
 	}
 
+	if (item.kind === "asked") {
+		return (
+			<div className="w-full max-w-sm border-ring/50 border-l-2 bg-muted/40 px-3 py-2.5">
+				<p className="font-medium text-xs">Follow-up</p>
+				<Markdown className="mt-1.5 max-h-24 overflow-y-auto wrap-break-word text-sm leading-5">
+					{item.question.prompt}
+				</Markdown>
+			</div>
+		);
+	}
+
 	return (
 		<div className="min-w-0 space-y-1.5">
 			<Marker>
diff --git a/apps/app/lib/agent-transcript.ts b/apps/app/lib/agent-transcript.ts
index cba963bf..eccabfd0 100644
--- a/apps/app/lib/agent-transcript.ts
+++ b/apps/app/lib/agent-transcript.ts
@@ -2,11 +2,17 @@ import type { MessageStreamEvent } from "eve/client";
 import {
 	defaultMessageReducer,
 	type EveMessage,
+	type EveMessageInputRequest,
 	type EveMessagePart,
 } from "eve/react";
 
 export type TranscriptItem =
 	| { kind: "said"; id: string; mine: boolean; text: string }
+	| {
+			kind: "asked";
+			id: string;
+			question: EveMessageInputRequest;
+	  }
 	| {
 			kind: "did";
 			id: string;
@@ -81,6 +87,12 @@ export type TranscriptMessage = {
 	items: TranscriptItem[];
 };
 
+export type ConversationTimelineItem<
+	TSubmission extends { id: string; createdAt: string },
+> =
+	| { kind: "submission"; id: string; submission: TSubmission }
+	| { kind: "assistant"; id: string; message: EveMessage };
+
 export function messagesFromEvents(
 	events: readonly MessageStreamEvent[],
 ): readonly EveMessage[] {
@@ -92,6 +104,61 @@ export function messagesFromEvents(
 	return data.messages;
 }
 
+export function conversationTimeline<
+	TSubmission extends { id: string; createdAt: string },
+>(
+	submissions: readonly TSubmission[],
+	events: readonly MessageStreamEvent[],
+	messages: readonly EveMessage[],
+): ConversationTimelineItem<TSubmission>[] {
+	const turnTimes = new Map<string, number>();
+
+	for (const event of events) {
+		const turnId = stringOf(
+			recordOf("data" in event ? event.data : undefined).turnId,
+		);
+		if (!turnId || turnTimes.has(turnId)) continue;
+		turnTimes.set(turnId, timestampOf(event.meta.at));
+	}
+
+	const rows = [
+		...submissions.map((submission, index) => ({
+			kind: "submission" as const,
+			id: `submission:${submission.id}`,
+			submission,
+			at: timestampOf(submission.createdAt),
+			index,
+		})),
+		...messages
+			.filter((message) => message.role === "assistant")
+			.map((message, index) => ({
+				kind: "assistant" as const,
+				id: `assistant:${message.id}`,
+				message,
+				at:
+					turnTimes.get(stringOf(recordOf(message.metadata).turnId) ?? "") ??
+					Number.POSITIVE_INFINITY,
+				index,
+			})),
+	];
+
+	rows.sort((a, b) =>
+		a.at !== b.at
+			? a.at - b.at
+			: a.kind === b.kind
+				? a.index - b.index
+				: a.kind === "submission"
+					? -1
+					: 1,
+	);
+
+	return rows.map((row) =>
+		row.kind === "submission"
+			? { kind: row.kind, id: row.id, submission: row.submission }
+			: { kind: row.kind, id: row.id, message: row.message },
+	);
+}
+
 export function toTranscript(
 	messages: readonly EveMessage[],
 ): TranscriptMessage[] {
@@ -108,6 +175,13 @@ export function toTranscript(
 					return [{ kind: "said", id, mine: message.role === "user", text }];
 				}
 
+				if (part.type === "dynamic-tool") {
+					const request = part.toolMetadata?.eve?.inputRequest;
+					if (request?.kind === "question") {
+						return [{ kind: "asked", id, question: request }];
+					}
+				}
+
 				if (part.type.startsWith("tool-") || part.type === "dynamic-tool") {
 					const state = "state" in part ? part.state : undefined;
 
@@ -259,6 +333,15 @@ function recordOf(value: unknown): Record<string, unknown> {
 		: {};
 }
 
+function stringOf(value: unknown): string | null {
+	return typeof value === "string" && value ? value : null;
+}
+
+function timestampOf(value: string): number {
+	const timestamp = Date.parse(value);
+	return Number.isFinite(timestamp) ? timestamp : Number.POSITIVE_INFINITY;
+}
+
 function hostOf(url: string): string {
 	try {
 		return new URL(url).hostname.replace(/^www\./, "");
diff --git a/apps/app/test/agent-transcript.spec.ts b/apps/app/test/agent-transcript.spec.ts
index 6c0ac015..0e87520f 100644
--- a/apps/app/test/agent-transcript.spec.ts
+++ b/apps/app/test/agent-transcript.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import { readdirSync } from "node:fs";
 import type { EveMessage } from "eve/react";
 import {
+	conversationTimeline,
 	describe as describeStep,
 	latestTurnFailure,
 	NEW_THREAD,
@@ -13,8 +14,18 @@ import {
 	toTranscript,
 } from "../lib/agent-transcript";
 
-const message = (parts: unknown[], role: "user" | "assistant" = "assistant") =>
-	({ id: "m1", role, parts }) as unknown as EveMessage;
+const message = (
+	parts: unknown[],
+	role: "user" | "assistant" = "assistant",
+	id = "m1",
+	turnId?: string,
+) =>
+	({
+		id,
+		role,
+		parts,
+		metadata: turnId ? { turnId } : undefined,
+	}) as unknown as EveMessage;
 
 const tool = (
 	toolName: string,
@@ -87,6 +98,75 @@ describe("toTranscript", () => {
 
 		expect(grouped[0]?.items[0]).toMatchObject({ kind: "did", pending: true });
 	});
+
+	it("keeps an ask_question tool as a first-class follow-up", () => {
+		const request = {
+			requestId: "req_1",
+			kind: "question",
+			prompt: "Which account should I use?",
+			options: [{ id: "primary", label: "Primary account" }],
+		};
+		const grouped = toTranscript([
+			message([
+				{
+					type: "dynamic-tool",
+					toolName: "ask_question",
+					state: "approval-requested",
+					toolMetadata: { eve: { inputRequest: request } },
+				},
+			]),
+		]);
+
+		expect(grouped[0]?.items[0]).toMatchObject({
+			kind: "asked",
+			question: { requestId: "req_1", prompt: "Which account should I use?" },
+		});
+	});
+});
+
+describe("conversationTimeline", () => {
+	it("renders each follow-up before the answer submitted for it", () => {
+		const submissions = [
+			{ id: "opening", createdAt: "2026-08-05T10:00:00.000Z" },
+			{ id: "answer", createdAt: "2026-08-05T10:02:00.000Z" },
+		];
+		const messages = [
+			message(
+				[{ type: "text", text: "Which one?" }],
+				"assistant",
+				"a1",
+				"turn-1",
+			),
+			message([{ type: "text", text: "Got it." }], "assistant", "a2", "turn-2"),
+		];
+		const events = [
+			{
+				type: "turn.started",
+				data: { turnId: "turn-1" },
+				meta: { id: "event-1", at: "2026-08-05T10:01:00.000Z" },
+			},
+			{
+				type: "turn.started",
+				data: { turnId: "turn-2" },
+				meta: { id: "event-2", at: "2026-08-05T10:03:00.000Z" },
+			},
+		] as never;
+
+		const timeline = conversationTimeline(submissions, events, messages);
+
+		expect(timeline.map((item) => item.kind)).toEqual([
+			"submission",
+			"assistant",
+			"submission",
+			"assistant",
+		]);
+		expect(timeline.map((item) => item.id)).toEqual([
+			"submission:opening",
+			"assistant:a1",
+			"submission:answer",
+			"assistant:a2",
+		]);
+	});
 });
 
 describe("describe", () => {
diff --git a/packages/ui/src/components/toggle.tsx b/packages/ui/src/components/toggle.tsx
index 4ef67527..e4d5190e 100644
--- a/packages/ui/src/components/toggle.tsx
+++ b/packages/ui/src/components/toggle.tsx
@@ -20,7 +20,7 @@ const toggleVariants = cva(
 				sm: "h-7 min-w-7 rounded-md px-2.5 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5",
 				lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
 				choice:
-					"h-auto min-h-10 w-full flex-col items-start gap-0.5 px-3 py-2 text-left whitespace-normal",
+					"h-auto min-h-8 w-full flex-col items-start gap-0 px-2.5 py-1 text-left whitespace-normal",
 			},
 		},
 		defaultVariants: {