diff --git a/.claude/skills/ui-components/SKILL.md b/.claude/skills/ui-components/SKILL.md
index 0f0ea19c55..ebedcf8f48 100644
--- a/.claude/skills/ui-components/SKILL.md
+++ b/.claude/skills/ui-components/SKILL.md
@@ -60,6 +60,115 @@ skeleton rules but lives next to its feature.
 - **No hardcoded user-facing strings** — even in stories/tests. Route through the i18n hook (`useT`);
   wording conventions are the [`translation`](../translation/SKILL.md) skill.
 
+## Composing pages — use the set, don't hand-roll
+
+The rules above build primitives; this builds _pages_ from them. **Feature pages and routes
+(`services/platform/app/**`) compose design-system components — they do not emit raw layout HTML.** A
+raw `<div className="flex flex-col gap-4">` on a page is the defect this prevents.
+
+- **Layout primitives** ([`@tale/ui/layout`](../../../packages/ui/src/components/layout/layout.tsx)):
+  vertical → `Stack`, horizontal → `Row`, responsive grid → `Grid`. They share one `gap` scale and take
+  `align`/`justify`/`wrap`, plus an `as` prop for semantic elements (`<Stack as="ul">`,
+  `<Stack as="form">`, `<Row as="nav">`) and `asChild` to merge onto a single child. `HStack`/`VStack`
+  are **deprecated aliases** of `Row`/`Stack`. A cluster of action buttons is the semantic `ActionRow`;
+  a titled section is `PageSection` (or `SettingsSection`). There is **no `Box`** — a neutral wrapper is
+  `<Stack gap={0}>`.
+- **One spacing scale** — `gapScale` in
+  [`layout.tsx`](../../../packages/ui/src/components/layout/layout.tsx). Recommended steps: **`2`** field
+  group (label → control → hint), **`4`** within a section (the default), **`6`** loose grouping, **`8`**
+  between sections (the settings rhythm). Never a raw `gap-[…]` or `space-y-*` for layout.
+- **Button size by context**
+  ([`button.tsx`](../../../packages/ui/src/components/primitives/button.tsx)): one height fits all —
+  **`default`** (`h-9`) for nearly everything (page/dialog/form/CTA actions) · **`sm`** (`h-8`) ONLY
+  for dense bars/toolbars (page-header action bars, table/card-header toolbars, the chat composer,
+  filter bars). There is **no `lg`**. Icon-only buttons are the same two heights, square —
+  **`icon`** (`size-9`) / **`icon-sm`** (`size-8`); prefer
+  [`IconButton`](../../../packages/ui/src/components/primitives/icon-button.tsx) (forces `aria-label`,
+  takes the same `size` axis) over a bare `<Button size="icon">`. A `size="icon"` button must hold a
+  **single icon** — the square clips text, so an icon+label control uses `default`/`sm` instead.
+- **Escape hatch.** Genuinely bespoke layout — chat/canvas, virtualization, geometry-measured
+  containers, responsive direction flips (`flex-col sm:flex-row`) — may stay raw with a one-line
+  `// raw layout: <reason>` so it reads as deliberate, not an oversight.
+
+## Concept → component catalog
+
+One concept, one component. Find it here before writing layout markup; import via `@tale/ui/<subpath>`
+unless noted.
+
+| Concept                 | Component                           | Concept                     | Component                  |
+| ----------------------- | ----------------------------------- | --------------------------- | -------------------------- |
+| Vertical group          | `Stack`                             | Horizontal group            | `Row`                      |
+| Responsive grid         | `Grid`                              | Action-button cluster       | `ActionRow`                |
+| Center content          | `Center`                            | Flex spacer                 | `Spacer`                   |
+| Page-width wrapper      | `Container` / `NarrowContainer`     | Titled section              | `PageSection`              |
+| Settings page / section | `SettingsPage` / `SettingsSection`¹ | Section header              | `SectionHeader`            |
+| Card                    | `Card`                              | Bordered subsection         | `BorderedSection`          |
+| Heading (h1–h6)         | `Heading`                           | Body / muted / label text   | `Text`                     |
+| Button / link-button    | `Button` / `LinkButton`             | Icon-only button            | `IconButton`               |
+| Text / multiline input  | `Input` / `Textarea`                | Field (label+control+error) | `Field`                    |
+| Select / searchable     | `Select` / `SearchableSelect`²      | Toggle                      | `Switch`²                  |
+| Checkbox                | `Checkbox`                          | Slider                      | `Slider`                   |
+| List / table            | `DataTable` (+ `useListPage`)¹      | Empty state                 | `EmptyState`               |
+| Badge / status dot      | `Badge` / `StatusIndicator`         | Alert / callout             | `Alert`                    |
+| Dialog / sheet          | `ResponsiveDialog`                  | Popover / menu              | `Popover` / `DropdownMenu` |
+| Tooltip                 | `Tooltip`                           | Tabs                        | `Tabs`                     |
+| Stat / stat group       | `StatItem` / `StatGrid`             | Code (inline / block)       | `InlineCode` / `CodeBlock` |
+| Image                   | `Image`                             | Loading                     | `Skeletonize` / `Spinner`  |
+
+¹ App-level (not `@tale/ui`): `SettingsPage`/`SettingsSection`, `DataTable`, `useListPage` live under
+`services/platform/app/components/` — import from `@/app/...`. ² `Select`, `SearchableSelect`, `Switch`,
+`RadioGroup` live in `app/components/ui/forms/` (app-level canonical — no `@tale/ui` rival); promote to
+`@tale/ui` only when a non-platform workspace (`web`/`docs`) needs them.
+
+Missing a concept? Extend the closest primitive or add a new one in `packages/ui` (story + a11y +
+skeleton-aware) — never a one-off in a feature folder.
+
+## One implementation per concept — the `@tale/ui` ↔ app layering
+
+There are two component layers, and **the same concept must never be implemented twice.** The split:
+
+- **`@tale/ui` owns the bare, shared primitive** (the control + its styling, once). It is consumed by
+  every workspace — `web` and `docs` included — and those **cannot import** `services/platform` code.
+  So any primitive a non-platform surface needs lives in `@tale/ui`, never in the app.
+- **The platform app composes that primitive; it never re-implements its styling.** The app layer adds
+  platform-only UX (label/description/error, password toggle, skeleton, i18n) _around_ the `@tale/ui`
+  control. Reference pattern:
+  [`app/.../data-display/image.tsx`](../../../services/platform/app/components/ui/data-display/image.tsx)
+  wraps `@tale/ui/image` and only adds the `BASE_PATH` fallback.
+
+**Rule:** before building a control under `app/components/ui/`, find the `@tale/ui` primitive and
+**compose it**. A second, divergent implementation (its own CVA/styling for an input, checkbox,
+tooltip, …) is a defect — it drifts. One canonical per concept.
+
+**Canonical per cross-layer concept** (use these; never fork a rival):
+
+| Concept                          | Canonical (use this)                          | Composes                                                  |
+| -------------------------------- | --------------------------------------------- | --------------------------------------------------------- |
+| Text input / textarea / checkbox | app `forms/{input,textarea,checkbox}`         | `@tale/ui/{input,textarea,checkbox}` (bare control)       |
+| Label                            | app `forms/label` (required/info/error)       | `@tale/ui/label`                                          |
+| Tooltip (simple)                 | app `overlays/tooltip` (`content`+`children`) | `@tale/ui/tooltip` (`TooltipContent`; raw parts for adv.) |
+| Settings section                 | app `SettingsSection`                         | `@tale/ui/page-section`                                   |
+| Image                            | app `data-display/image`                      | `@tale/ui/image`                                          |
+| Pagination                       | `data-table/data-table-pagination`            | — (standalone `navigation/pagination` was dead, removed)  |
+
+**Genuinely distinct — do NOT merge** (similar names, different concepts): `StatCard`/`StatCardGrid`
+(bordered headline-metric strip) vs `StatItem`/`StatGrid` (borderless `<dl>` key/value); `EmptyState`
+(full-height) vs `EmptyPlaceholder` (inline dashed); `@tale/ui/Field` (form wrapper) vs app `Field`
+(read-only display); the `Dialog → ConfirmDialog → DeleteDialog` / `FormDialog` / `ViewDialog`
+composition ladder; `InlineCode` vs `CodeBlock`; `Popover` (interactive) vs `Tooltip` (passive).
+
+**Known styling drift to reconcile** (the app control re-implements the primitive's look instead of
+composing it — route it through the `@tale/ui` primitive, reconcile to one token set, verify visually):
+`forms/input`, `forms/textarea`, `forms/checkbox` (border/focus tokens), `overlays/tooltip` (content
+background). Until reconciled, use the canonical above — don't add a third.
+
+## When to create a new primitive
+
+Reuse → extend (add a `variant`/prop) → compose → only then create. A new shared primitive lives in
+`packages/ui/src/components/<category>/`, ships a `*.stories.tsx` (all variants) and a
+`checkAccessibility()` block, is skeleton-aware if it's a leaf, and gets a `@tale/ui/<name>` subpath
+export.
+
 ## Patterns (show, don't tell)
 
 CVA base + named `variant`, then `cn(...)` so `className` overrides
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index a0ceb25468..b2d22eb1e6 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -39,32 +39,34 @@ concurrency:
 
 jobs:
   e2e:
-    name: Playwright (platform ${{ matrix.shard }}/8)
+    name: Playwright (platform ${{ matrix.shard }}/16)
     if: github.event_name != 'pull_request' || github.event.pull_request.draft != true
     runs-on: ubuntu-latest
-    timeout-minutes: 25
-    # The suite outgrew a single serial 30-min run (workers:1 against one
-    # backend). Shard the specs across parallel runners so each shard finishes
-    # well inside the timeout instead of being cancelled mid-run. Each shard is
-    # an independent job: it boots its own hermetic stack and runs the `setup`
-    # auth project before its slice. fail-fast:false so one shard's failure
-    # doesn't cancel the others — we want every shard's result.
+    timeout-minutes: 30
+    # The suite outgrew a single serial run (workers:1 against one backend).
+    # Shard the specs across parallel runners so each shard finishes well inside
+    # the timeout instead of being cancelled mid-run. Each shard is an
+    # independent job: it boots its own hermetic stack and runs the `setup` auth
+    # project before its slice. fail-fast:false so one shard's failure doesn't
+    # cancel the others — we want every shard's result, and a re-run of just the
+    # red shards (`gh run rerun --failed`) converges to green.
     #
-    # Shard count: 8. Each shard's cost is the FIXED per-shard boot (Chromium +
+    # Shard count: 16. Each shard's cost is the FIXED per-shard boot (Chromium +
     # Convex + Vite preview + @tale/mocks) plus its serial test slice; a single
     # worker per shard is mandatory (two starve the local Convex backend on the
     # 4-vCPU runner — see the run step). Parallelism therefore comes only from
-    # shards, so the lever for wall-clock is the test slice: 8 shards puts ~9 of
-    # the ~74 tests per job (vs ~18 at 4) and halves the serial test time. We stop
-    # at 8 rather than going higher because the boot floor dominates below ~9
-    # tests — more shards would multiply CI minutes for a negligible wall-clock
-    # gain. The prod build that used to sit on every shard's critical path is now
-    # cached across shards/re-runs (see the dist cache step), so test-only e2e PRs
-    # skip it entirely.
+    # shards, so the lever for wall-clock is the test slice: 16 shards puts ~5 of
+    # the ~74 tests per job. The boot floor dominates at this slice size, so this
+    # trades extra CI minutes for the shortest serial test time per shard —
+    # chosen deliberately so a shard is far less likely to hit the 30-min timeout
+    # when the local Convex backend runs slow under runner CPU contention. The
+    # prod build that used to sit on every shard's critical path is now cached
+    # across shards/re-runs (see the dist cache step), so test-only e2e PRs skip
+    # it entirely.
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2, 3, 4, 5, 6, 7, 8]
+        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
     permissions:
       contents: read
 
@@ -130,14 +132,14 @@ jobs:
         working-directory: services/platform
         run: bun run build
 
-      - name: Run E2E suite (shard ${{ matrix.shard }}/8)
+      - name: Run E2E suite (shard ${{ matrix.shard }}/16)
         working-directory: services/platform
         # One worker per shard. Two workers over-subscribed the 4-vCPU runner
         # (Vite + Convex + mock + the browser workers all share it): the local
         # Convex backend starved and queries blew its hard 1s function-execution
         # timeout in floods (100s+ per shard), stranding the WS unauthenticated
-        # and failing tests non-deterministically. Parallelism comes from the 4
-        # shards; each single-worker shard still finishes well inside the 25-min
+        # and failing tests non-deterministically. Parallelism comes from the 16
+        # shards; each single-worker shard still finishes well inside the 30-min
         # budget. Tune via E2E_WORKERS.
         env:
           E2E_WORKERS: '1'
@@ -149,7 +151,7 @@ jobs:
           # starve interactive queries past the backend's hard 1s timeout
           # mid-test. Passed through to the deployment env by sync-convex-env.
           TALE_E2E: '1'
-        run: bunx playwright test --shard=${{ matrix.shard }}/8
+        run: bunx playwright test --shard=${{ matrix.shard }}/16
 
       - name: Upload Playwright report
         if: failure()
diff --git a/.github/workflows/update-models.yml b/.github/workflows/update-models.yml
index d42574e52c..08a9cd3f09 100644
--- a/.github/workflows/update-models.yml
+++ b/.github/workflows/update-models.yml
@@ -48,7 +48,7 @@ jobs:
       - name: Detect changes
         id: diff
         run: |
-          if [ -n "$(git status --porcelain builtin-configs/providers)" ]; then
+          if [ -n "$(git status --porcelain builtin-configs/providers docs/en/platform/models.md docs/de/platform/models.md docs/fr/platform/models.md)" ]; then
             echo "changed=true" >> "$GITHUB_OUTPUT"
           else
             echo "changed=false" >> "$GITHUB_OUTPUT"
@@ -69,7 +69,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git checkout -B "$BRANCH"
-          git add builtin-configs/providers
+          git add builtin-configs/providers docs/en/platform/models.md docs/de/platform/models.md docs/fr/platform/models.md
           # --no-verify: skip any husky hooks `bun install` may have registered.
           git commit --no-verify -m "$TITLE"
           # Bot-owned branch, recreated from HEAD each run → a plain force push is
diff --git a/AGENTS.md b/AGENTS.md
index 9da70a0e5d..c4052a06b6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,11 +5,7 @@ Cursor, Codex, Copilot, Gemini CLI). Read it in full before your first change. D
 on-demand guides under [`.claude/skills/`](.claude/skills/) — this file is the contract; the skills
 are the how-to. The index is at the bottom.
 
-Tale is a monorepo on Bun workspaces. Every workspace script runs through the filter:
-
-```bash
-bun run --filter @tale/<workspace> <script>
-```
+Tale is a monorepo on Bun workspaces; every workspace script runs through `bun run --filter @tale/<workspace> <script>`.
 
 ## How to work
 
@@ -87,20 +83,21 @@ If you didn't verify it, it isn't done — say so rather than claiming it. Paste
 
 A change is rarely one file. Expand a local edit into its blast radius:
 
-| You changed…                                             | You must also…                                                                                  |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| A user-visible string                                    | `en/de/fr.json` (+`de-CH` if differs) · glossary · docs(3) · manual guide · e2e                 |
-| A translation key (add/rename/remove)                    | all base locales same commit · remove dead keys everywhere                                      |
-| A new interactive UI element                             | i18n label · a11y (HTML/keyboard/aria/contrast/24px) · docs · manual guide · e2e                |
-| A new `components/ui/` primitive                         | Storybook story (all variants) · a11y block · Skeletonize support                               |
-| A Convex field/table (rename/retype/split/drop/backfill) | migration + up/down + `migration.test.ts` + registry + `migrations:check`                       |
-| A knowledge-DB schema                                    | dbmate migration under `migrations/knowledge-db/<schema>/` · verify a fresh `compose up`        |
-| Env var / CLI flag / config key / API field              | docs(3) · `.env.example` · `README{,.de,.fr}.md` · setup                                        |
-| Error wording / validation / rate limit                  | docs(3) · tests · i18n                                                                          |
-| A date display                                           | `useFormatDate()` — never `toLocale*`                                                           |
-| A new query/mutation                                     | `queryWithRLS`/`mutationWithRLS` · validators · no `.collect()` · preload in the loader         |
-| A path/command/pattern a skill or `AGENTS.md` documents  | update that guide + the skill index · run `bun .claude/check-skill-links.mjs`                   |
-| A skill added/renamed/rescoped                           | set globs in `.claude/skill-globs.json` · `bun .claude/gen-skill-adapters.mjs` (Cursor/Copilot) |
+| You changed…                                             | You must also…                                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| A user-visible string                                    | `en/de/fr.json` (+`de-CH` if differs) · glossary · docs(3) · manual guide · e2e                  |
+| A translation key (add/rename/remove)                    | all base locales same commit · remove dead keys everywhere                                       |
+| A new interactive UI element                             | i18n label · a11y (HTML/keyboard/aria/contrast/24px) · docs · manual guide · e2e                 |
+| A new `components/ui/` primitive                         | Storybook story (all variants) · a11y block · Skeletonize support                                |
+| A feature page / route                                   | compose `@tale/ui` + layout primitives (no raw layout HTML) · button-size policy · one gap scale |
+| A Convex field/table (rename/retype/split/drop/backfill) | migration + up/down + `migration.test.ts` + registry + `migrations:check`                        |
+| A knowledge-DB schema                                    | dbmate migration under `migrations/knowledge-db/<schema>/` · verify a fresh `compose up`         |
+| Env var / CLI flag / config key / API field              | docs(3) · `.env.example` · `README{,.de,.fr}.md` · setup                                         |
+| Error wording / validation / rate limit                  | docs(3) · tests · i18n                                                                           |
+| A date display                                           | `useFormatDate()` — never `toLocale*`                                                            |
+| A new query/mutation                                     | `queryWithRLS`/`mutationWithRLS` · validators · no `.collect()` · preload in the loader          |
+| A path/command/pattern a skill or `AGENTS.md` documents  | update that guide + the skill index · run `bun .claude/check-skill-links.mjs`                    |
+| A skill added/renamed/rescoped                           | set globs in `.claude/skill-globs.json` · `bun .claude/gen-skill-adapters.mjs` (Cursor/Copilot)  |
 
 → Full guide: [`definition-of-done`](.claude/skills/definition-of-done/SKILL.md), [`ship`](.claude/skills/ship/SKILL.md)
 
@@ -164,8 +161,9 @@ knip · strict typecheck. **When you add a rule, add the guard.**
 
 - **Filenames:** dash-case everywhere except Convex, which uses snake_case.
 - **No status comments** (`// REFACTORED`, `// TODO: see #123`) and no comments narrating removed code. Git is the record. Comments explain _why_, rarely _what_.
+- **Comments address the next reader of the code, never the chat or a follow-up.** No verification-status notes, handoff messages, or references to the conversation/plan (e.g. `// ⚠️ UNVERIFIED … require a live stack to validate (see plan)`). That belongs in the PR description, an issue, or your reply — not the source. If something is genuinely unproven, say so in the PR, not in a comment that ships forever.
 - **No empty catch blocks.** Log (`console.warn`/`console.error`) or re-throw. Silent catches hide bugs.
-- **No locale-aware date methods.** `toLocaleDateString`/`toLocaleTimeString`/`toLocaleString` are banned. Use `useFormatDate()` in React or `formatDate()` from [`lib/utils/date/format`](services/platform/lib/utils/date/format.ts).
+- **No locale-aware date methods.** `toLocaleDateString`/`toLocaleTimeString`/`toLocaleString` are banned. Use `useFormatDate()` in React or `formatDate()` from `lib/utils/date/format`.
 - **No `\uXXXX` escapes in JSON.** Write non-ASCII literally as UTF-8 (`ät`, `é`, `—`, `«»`). JSON's required escapes (`\n`, `\t`, `\"`, `\\`) stay.
 
 → Full guide: [`clean-code`](.claude/skills/clean-code/SKILL.md)
@@ -214,11 +212,36 @@ run locally with `bun run lint:sast`. Suppress a genuine false-positive narrowly
 - **Navigation** uses TanStack Router (`useNavigate()`, `<Link>`). No `window.location`.
 - **Images** go through the `Image` component (`@/components/ui/image`); never bare `<img>`.
 - **No hardcoded user-facing strings** — always the `useT()` hook. A stray English literal in JSX is a bug.
-- **Loading is centralized** — split into presentational + container, wrap the plain part in `<Skeletonize loading>` ([`@tale/ui/skeleton-context`](packages/ui/src/components/feedback/skeleton-context.tsx)); skeleton-aware leaves mask to their own size. Never the bare `<Skeleton>` or a magic `h-[…]`.
+- **Loading is centralized** — split into presentational + container, wrap the plain part in `<Skeletonize loading>` (`@tale/ui/skeleton-context`); skeleton-aware leaves mask to their own size. Never the bare `<Skeleton>` or a magic `h-[…]`.
 - **CVA for named variants** (`variant`/`size`/`tone`); a conditional `cn()` for boolean states. Reach for `useMemo`/`memo` only when the profile justifies it, and avoid the `useEffect` reflex.
 
 → Full guide: [`react`](.claude/skills/react/SKILL.md), [`ui-components`](.claude/skills/ui-components/SKILL.md)
 
+## Design system & UI composition
+
+Tale has **one** design system — `@tale/ui` primitives, composed by feature pages. One concept, one
+component. **Build pages by composing components; never hand-roll layout HTML.**
+
+- **Compose, don't hand-roll.** Feature pages/routes (`services/platform/app/**`) use design-system
+  components + layout primitives — no raw `<div className="flex/grid …">`, `<section>`, `<h1|2|3>`, or
+  `<button>` for layout. Vertical → `Stack`, horizontal → `Row`, grid → `Grid` (`@tale/ui/layout`);
+  titled section → `PageSection`/`SettingsSection`; action cluster → `ActionRow`; a semantic element →
+  the primitive's `as` prop (`<Stack as="ul">`). Bespoke layout (chat/canvas, virtualization, measured
+  nodes) may stay raw with a one-line `// raw layout: <reason>`.
+- **One spacing scale** — named `gap` steps (`2` field group · `4` within a section / default · `6`
+  loose · `8` between sections); never a raw `gap-[…]` or `space-y-*` for layout.
+- **Button size by context** — `default` (page/dialog actions) · `sm` (dense/toolbar/table/inline) ·
+  `lg` (marketing CTAs) · icon-only → `IconButton` (never a bare `size="icon"`).
+- **One way per surface** — lists/tables → `useListPage` + `DataTable` (one add-item affordance, one
+  empty path); forms → `useFormEditor` + `Form`/`Field`; settings → `SettingsPage` + `SettingsSection`
+  (no page title — the rail names it).
+- **One implementation per concept across layers** — `@tale/ui` owns the bare shared primitive (also
+  used by `web`/`docs`, which can't import platform code); the platform app **composes** it and adds
+  UX (label/error/skeleton) — it never re-implements a primitive's styling. A second divergent
+  control (its own input/checkbox/tooltip) is a defect; find the `@tale/ui` primitive and wrap it.
+
+→ Full catalog + how-to: [`ui-components`](.claude/skills/ui-components/SKILL.md)
+
 ## Convex
 
 - **No `.collect()`** — iterate with `for await` or `.paginate()`. **Use `queryWithRLS`/`mutationWithRLS`**, not raw `query`/`mutation`. **Backend returns raw data;** the client filters/sorts/paginates.
@@ -245,8 +268,7 @@ Every user-facing string goes through the translation layer; never compare again
 in code, tests, or stories. **`en.json` is the schema** — every key exists in `de.json` and `fr.json`
 on the same commit; `de-CH` carries only differing values (fallback `de-CH → de → en`). Remove dead
 keys everywhere (orphan-key test). Sentence case; **informal form** (`du`, `tu` — never `Sie`/`vous`);
-ICU placeholders copy exactly; brand names don't translate. `useT(namespace)` from
-[`lib/i18n/client`](services/platform/lib/i18n/client.tsx).
+ICU placeholders copy exactly; brand names don't translate. `useT(namespace)` from `lib/i18n/client`.
 → Full guide: [`translation`](.claude/skills/translation/SKILL.md)
 
 ## Documentation
@@ -270,22 +292,25 @@ respect `prefers-reduced-motion`. Every component has an `accessibility` describ
 
 ## Anti-patterns — you'll be tempted to X; don't
 
-| Tempted to…                                                    | Instead                                            | Caught by                      |
-| -------------------------------------------------------------- | -------------------------------------------------- | ------------------------------ |
-| Update `en.json` only                                          | all base locales + variants, same commit           | i18n parity test · Ripple Map  |
-| Add a Convex field, skip the migration                         | versioned reversible migration + test              | `migrations:check` · DoD       |
-| Hand-roll a skeleton (`h-[200px]`)                             | `<Skeletonize>` + skeleton-aware leaves            | `skeleton-conventions.test.ts` |
-| Build a new Button/Input/Badge                                 | reuse/extend the `packages/ui` primitive           | reuse discipline · review      |
-| Build a 2nd catalog/list/page like an existing one             | extract the shared concept; both render through it | reuse discipline · review      |
-| Two surfaces (agents vs workflows) doing one thing differently | one concept, one implementation both call          | reuse discipline · review      |
-| `as any` to silence TS                                         | type guard / generic / discriminated union         | oxlint `no-explicit-any`       |
-| Bare `<img>`                                                   | the `Image` component                              | oxlint jsx-a11y `alt-text`     |
-| `toLocaleDateString`                                           | `useFormatDate()`                                  | code style · review            |
-| `.collect()` on a large set                                    | `for await` / `.paginate()`                        | `convex` guide · review        |
-| `window.location` for nav                                      | `useNavigate`/`<Link>`                             | `react` guide                  |
-| `useEffect` for derived state                                  | derive in render / event handler                   | `react` guide                  |
-| Empty catch                                                    | log or re-throw                                    | code style                     |
-| Declare "done" unrun                                           | observe the outcome, show evidence                 | verification doctrine          |
+| Tempted to…                                                    | Instead                                             | Caught by                      |
+| -------------------------------------------------------------- | --------------------------------------------------- | ------------------------------ |
+| Update `en.json` only                                          | all base locales + variants, same commit            | i18n parity test · Ripple Map  |
+| Add a Convex field, skip the migration                         | versioned reversible migration + test               | `migrations:check` · DoD       |
+| Hand-roll a skeleton (`h-[200px]`)                             | `<Skeletonize>` + skeleton-aware leaves             | `skeleton-conventions.test.ts` |
+| Build a new Button/Input/Badge                                 | reuse/extend the `packages/ui` primitive            | reuse discipline · review      |
+| Build a 2nd catalog/list/page like an existing one             | extract the shared concept; both render through it  | reuse discipline · review      |
+| Two surfaces (agents vs workflows) doing one thing differently | one concept, one implementation both call           | reuse discipline · review      |
+| Hand-roll page layout (`<div className="flex/grid…">`)         | compose `Stack`/`Row`/`Grid` (`@tale/ui/layout`)    | `ui-components` · review       |
+| Raw `gap-[…]` / arbitrary spacing                              | the named gap scale (`2`/`4`/`6`/`8`)               | `ui-components` · review       |
+| `<Button size>` picked by feel                                 | the size policy (default/sm/lg · icon→`IconButton`) | `ui-components` · review       |
+| `as any` to silence TS                                         | type guard / generic / discriminated union          | oxlint `no-explicit-any`       |
+| Bare `<img>`                                                   | the `Image` component                               | oxlint jsx-a11y `alt-text`     |
+| `toLocaleDateString`                                           | `useFormatDate()`                                   | code style · review            |
+| `.collect()` on a large set                                    | `for await` / `.paginate()`                         | `convex` guide · review        |
+| `window.location` for nav                                      | `useNavigate`/`<Link>`                              | `react` guide                  |
+| `useEffect` for derived state                                  | derive in render / event handler                    | `react` guide                  |
+| Empty catch                                                    | log or re-throw                                     | code style                     |
+| Declare "done" unrun                                           | observe the outcome, show evidence                  | verification doctrine          |
 
 ## Skills and guides index
 
diff --git a/README.md b/README.md
index b8f8ffded4..feab2bdeee 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ tale init [directory]              # Create a new project with example configs (
 tale start                         # Start all services locally
 tale start --detach                # Start in background
 tale start --port 8443             # Use a custom HTTPS port
-tale upgrade                       # Upgrade CLI and sync project files
+tale update                        # Update the CLI + sync project files (then `tale deploy`; CLI self-aligns automatically)
 tale convex admin                  # Generate Convex dashboard admin key
 tale config                        # Manage CLI configuration
 ```
diff --git a/builtin-configs/agents/chat/assistant.json b/builtin-configs/agents/chat/assistant.json
index b1420e201f..616d5f80dc 100644
--- a/builtin-configs/agents/chat/assistant.json
+++ b/builtin-configs/agents/chat/assistant.json
@@ -28,8 +28,8 @@
   "supportedModels": [
     "openrouter:anthropic/claude-haiku-4.5",
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6",
-    "openrouter:openai/gpt-5.2",
+    "openrouter:anthropic/claude-opus-4.8",
+    "openrouter:openai/gpt-5.5",
     "openrouter:google/gemini-3.1-pro-preview"
   ],
   "knowledgeMode": "tool",
diff --git a/builtin-configs/agents/chat/coder.json b/builtin-configs/agents/chat/coder.json
index 8554ba00fd..394f0aba4f 100644
--- a/builtin-configs/agents/chat/coder.json
+++ b/builtin-configs/agents/chat/coder.json
@@ -21,8 +21,8 @@
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
     "openrouter:anthropic/claude-haiku-4.5",
-    "openrouter:anthropic/claude-opus-4.6",
-    "openrouter:openai/gpt-5.2"
+    "openrouter:anthropic/claude-opus-4.8",
+    "openrouter:openai/gpt-5.5"
   ],
   "knowledgeMode": "tool",
   "includeOrgKnowledge": true,
diff --git a/builtin-configs/agents/chat/integration-assistant.json b/builtin-configs/agents/chat/integration-assistant.json
index db542b91d8..3457ce7f4e 100644
--- a/builtin-configs/agents/chat/integration-assistant.json
+++ b/builtin-configs/agents/chat/integration-assistant.json
@@ -10,8 +10,8 @@
   "outputReserve": 2048,
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6",
-    "openrouter:openai/gpt-5.2"
+    "openrouter:anthropic/claude-opus-4.8",
+    "openrouter:openai/gpt-5.5"
   ],
   "roleRestriction": "admin_developer",
   "visibleInChat": true,
diff --git a/builtin-configs/agents/chat/researcher.json b/builtin-configs/agents/chat/researcher.json
index 3dc42734fb..f56f359d48 100644
--- a/builtin-configs/agents/chat/researcher.json
+++ b/builtin-configs/agents/chat/researcher.json
@@ -8,8 +8,8 @@
   "integrationBindings": ["tavily"],
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6",
-    "openrouter:openai/gpt-5.2",
+    "openrouter:anthropic/claude-opus-4.8",
+    "openrouter:openai/gpt-5.5",
     "openrouter:google/gemini-3.1-pro-preview"
   ],
   "maxSteps": 40,
diff --git a/builtin-configs/agents/chat/workflow-assistant.json b/builtin-configs/agents/chat/workflow-assistant.json
index 3640237f64..55b0e73167 100644
--- a/builtin-configs/agents/chat/workflow-assistant.json
+++ b/builtin-configs/agents/chat/workflow-assistant.json
@@ -16,8 +16,8 @@
   ],
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6",
-    "openrouter:openai/gpt-5.2"
+    "openrouter:anthropic/claude-opus-4.8",
+    "openrouter:openai/gpt-5.5"
   ],
   "maxSteps": 30,
   "timeoutMs": 240000,
diff --git a/builtin-configs/agents/github/pull-request-reviewer.json b/builtin-configs/agents/github/pull-request-reviewer.json
index 1cb4ca7e16..3917c853cc 100644
--- a/builtin-configs/agents/github/pull-request-reviewer.json
+++ b/builtin-configs/agents/github/pull-request-reviewer.json
@@ -19,7 +19,7 @@
   ],
   "integrationBindings": ["github"],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/router.json b/builtin-configs/agents/router.json
index fade97dd6e..1e90a88708 100644
--- a/builtin-configs/agents/router.json
+++ b/builtin-configs/agents/router.json
@@ -20,6 +20,6 @@
   "supportedModels": [
     "openrouter:anthropic/claude-haiku-4.5",
     "openrouter:google/gemini-3.1-pro-preview",
-    "openrouter:openai/gpt-5.2"
+    "openrouter:openai/gpt-5.5"
   ]
 }
diff --git a/builtin-configs/agents/workforce/chief-executive-officer.json b/builtin-configs/agents/workforce/chief-executive-officer.json
index 0a6d947e82..72e09ec4db 100644
--- a/builtin-configs/agents/workforce/chief-executive-officer.json
+++ b/builtin-configs/agents/workforce/chief-executive-officer.json
@@ -17,7 +17,7 @@
     "request_human_input"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/workforce/chief-marketing-officer.json b/builtin-configs/agents/workforce/chief-marketing-officer.json
index a3eff41d36..7c1ef44686 100644
--- a/builtin-configs/agents/workforce/chief-marketing-officer.json
+++ b/builtin-configs/agents/workforce/chief-marketing-officer.json
@@ -17,7 +17,7 @@
   ],
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6"
+    "openrouter:anthropic/claude-opus-4.8"
   ],
   "personalizationMode": "off",
   "maxSteps": 30,
diff --git a/builtin-configs/agents/workforce/chief-operating-officer.json b/builtin-configs/agents/workforce/chief-operating-officer.json
index 1a1644a514..34ac75b003 100644
--- a/builtin-configs/agents/workforce/chief-operating-officer.json
+++ b/builtin-configs/agents/workforce/chief-operating-officer.json
@@ -16,7 +16,7 @@
     "request_human_input"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/workforce/chief-technology-officer.json b/builtin-configs/agents/workforce/chief-technology-officer.json
index 82ca320642..86e9bd313d 100644
--- a/builtin-configs/agents/workforce/chief-technology-officer.json
+++ b/builtin-configs/agents/workforce/chief-technology-officer.json
@@ -16,7 +16,7 @@
     "request_human_input"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/workforce/legal-counsel.json b/builtin-configs/agents/workforce/legal-counsel.json
index 5daf9ecfd0..667895813b 100644
--- a/builtin-configs/agents/workforce/legal-counsel.json
+++ b/builtin-configs/agents/workforce/legal-counsel.json
@@ -15,7 +15,7 @@
     "request_human_input"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/workforce/security-engineer.json b/builtin-configs/agents/workforce/security-engineer.json
index a28795904f..2f6f47c8da 100644
--- a/builtin-configs/agents/workforce/security-engineer.json
+++ b/builtin-configs/agents/workforce/security-engineer.json
@@ -14,7 +14,7 @@
     "document_write"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "off",
diff --git a/builtin-configs/agents/workforce/software-architect.json b/builtin-configs/agents/workforce/software-architect.json
index a52d2d782c..15df1a89b6 100644
--- a/builtin-configs/agents/workforce/software-architect.json
+++ b/builtin-configs/agents/workforce/software-architect.json
@@ -14,7 +14,7 @@
     "run_code"
   ],
   "supportedModels": [
-    "openrouter:anthropic/claude-opus-4.6",
+    "openrouter:anthropic/claude-opus-4.8",
     "openrouter:anthropic/claude-sonnet-4.6"
   ],
   "personalizationMode": "on",
diff --git a/builtin-configs/agents/workforce/software-developer.json b/builtin-configs/agents/workforce/software-developer.json
index 9ff5b586e4..fb23431dd7 100644
--- a/builtin-configs/agents/workforce/software-developer.json
+++ b/builtin-configs/agents/workforce/software-developer.json
@@ -10,7 +10,7 @@
   "integrationBindings": ["github"],
   "supportedModels": [
     "openrouter:anthropic/claude-sonnet-4.6",
-    "openrouter:anthropic/claude-opus-4.6"
+    "openrouter:anthropic/claude-opus-4.8"
   ],
   "timeoutMs": 1800000,
   "personalizationMode": "on",
diff --git a/builtin-configs/integrations/confluence/icon.svg b/builtin-configs/integrations/confluence/icon.svg
index 4cef831c1b..64d068b16c 100644
--- a/builtin-configs/integrations/confluence/icon.svg
+++ b/builtin-configs/integrations/confluence/icon.svg
@@ -1,7 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path fill="#1868DB" d="M.87 18.26c-.25.38-.53.87-.76 1.24a.76.76 0 0 0 .25 1.04l4.97 3.06a.76.76 0 0 0 1.06-.26c.2-.33.45-.77.73-1.22 1.97-3.25 3.95-2.85 7.51-1.15l4.96 2.34a.76.76 0 0 0 1.03-.38l2.36-5.35a.76.76 0 0 0-.38-1c-1.05-.49-3.13-1.47-5-2.36C9.54 9.76 4.83 9.99.87 18.26z" />
-  <path fill="#388BFF" d="M23.13 5.74c.25-.38.53-.87.76-1.24a.76.76 0 0 0-.25-1.04L18.67.4a.76.76 0 0 0-1.06.26c-.2.33-.45.77-.73 1.22-1.97 3.25-3.95 2.85-7.51 1.15L4.42.69a.76.76 0 0 0-1.03.38L1.03 6.42a.76.76 0 0 0 .38 1c1.05.49 3.13 1.47 5 2.36 7.39 3.55 12.1 3.33 16.06-4.94z" />
+  <g transform="translate(4.5 4.793) scale(0.0586)">
+    <defs><linearGradient id="SVGvnhR7dox" x1="99.14%" x2="33.859%" y1="112.708%" y2="37.755%"><stop offset="18%" stop-color="#0052cc"/><stop offset="100%" stop-color="#2684ff"/></linearGradient><linearGradient id="SVGgker3cTp" x1=".926%" x2="66.18%" y1="-12.582%" y2="62.306%"><stop offset="18%" stop-color="#0052cc"/><stop offset="100%" stop-color="#2684ff"/></linearGradient></defs><path fill="url(#SVGvnhR7dox)" d="M9.26 187.33c-2.64 4.307-5.607 9.305-8.126 13.287a8.127 8.127 0 0 0 2.722 11.052l52.823 32.507a8.127 8.127 0 0 0 11.256-2.763c2.113-3.536 4.835-8.127 7.801-13.044c20.926-34.538 41.974-30.312 79.925-12.19l52.376 24.908a8.127 8.127 0 0 0 10.93-4.063l25.152-56.886a8.127 8.127 0 0 0-4.063-10.646c-11.052-5.201-33.034-15.562-52.823-25.111c-71.189-34.579-131.691-32.344-177.972 42.949"/><path fill="url(#SVGgker3cTp)" d="M246.115 58.232c2.641-4.307 5.607-9.305 8.127-13.287a8.127 8.127 0 0 0-2.723-11.052L198.696 1.386a8.127 8.127 0 0 0-11.58 2.682c-2.113 3.535-4.835 8.127-7.802 13.043c-20.926 34.538-41.974 30.313-79.925 12.19L47.176 4.515a8.127 8.127 0 0 0-10.93 4.063L11.093 65.465a8.127 8.127 0 0 0 4.063 10.645c11.052 5.202 33.035 15.563 52.823 25.112c71.351 34.538 131.854 32.222 178.135-42.99"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/discord/icon.svg b/builtin-configs/integrations/discord/icon.svg
index 421c9bf05c..0b5d861806 100644
--- a/builtin-configs/integrations/discord/icon.svg
+++ b/builtin-configs/integrations/discord/icon.svg
@@ -1,6 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03ZM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418Zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418Z" fill="#5865F2" />
+  <g transform="translate(4.5 6.1699) scale(0.0586)">
+    <path fill="#5865f2" d="M216.856 16.597A208.5 208.5 0 0 0 164.042 0c-2.275 4.113-4.933 9.645-6.766 14.046q-29.538-4.442-58.533 0c-1.832-4.4-4.55-9.933-6.846-14.046a207.8 207.8 0 0 0-52.855 16.638C5.618 67.147-3.443 116.4 1.087 164.956c22.169 16.555 43.653 26.612 64.775 33.193A161 161 0 0 0 79.735 175.3a136.4 136.4 0 0 1-21.846-10.632a109 109 0 0 0 5.356-4.237c42.122 19.702 87.89 19.702 129.51 0a132 132 0 0 0 5.355 4.237a136 136 0 0 1-21.886 10.653c4.006 8.02 8.638 15.67 13.873 22.848c21.142-6.58 42.646-16.637 64.815-33.213c5.316-56.288-9.08-105.09-38.056-148.36M85.474 135.095c-12.645 0-23.015-11.805-23.015-26.18s10.149-26.2 23.015-26.2s23.236 11.804 23.015 26.2c.02 14.375-10.148 26.18-23.015 26.18m85.051 0c-12.645 0-23.014-11.805-23.014-26.18s10.148-26.2 23.014-26.2c12.867 0 23.236 11.804 23.015 26.2c0 14.375-10.148 26.18-23.015 26.18"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/github/icon.svg b/builtin-configs/integrations/github/icon.svg
index bb9f23fec8..6912e40bae 100644
--- a/builtin-configs/integrations/github/icon.svg
+++ b/builtin-configs/integrations/github/icon.svg
@@ -1,6 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path fill-rule="evenodd" clip-rule="evenodd" d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12Z" fill="#181717" />
+  <g transform="translate(4.5 4.6758) scale(0.0586)">
+    <path fill="#161614" d="M128.001 0C57.317 0 0 57.307 0 128.001c0 56.554 36.676 104.535 87.535 121.46c6.397 1.185 8.746-2.777 8.746-6.158c0-3.052-.12-13.135-.174-23.83c-35.61 7.742-43.124-15.103-43.124-15.103c-5.823-14.795-14.213-18.73-14.213-18.73c-11.613-7.944.876-7.78.876-7.78c12.853.902 19.621 13.19 19.621 13.19c11.417 19.568 29.945 13.911 37.249 10.64c1.149-8.272 4.466-13.92 8.127-17.116c-28.431-3.236-58.318-14.212-58.318-63.258c0-13.975 5-25.394 13.188-34.358c-1.329-3.224-5.71-16.242 1.24-33.874c0 0 10.749-3.44 35.21 13.121c10.21-2.836 21.16-4.258 32.038-4.307c10.878.049 21.837 1.47 32.066 4.307c24.431-16.56 35.165-13.12 35.165-13.12c6.967 17.63 2.584 30.65 1.255 33.873c8.207 8.964 13.173 20.383 13.173 34.358c0 49.163-29.944 59.988-58.447 63.157c4.591 3.972 8.682 11.762 8.682 23.704c0 17.126-.148 30.91-.148 35.126c0 3.407 2.304 7.398 8.792 6.14C219.37 232.5 256 184.537 256 128.002C256 57.307 198.691 0 128.001 0m-80.06 182.34c-.282.636-1.283.827-2.194.39c-.929-.417-1.45-1.284-1.15-1.922c.276-.655 1.279-.838 2.205-.399c.93.418 1.46 1.293 1.139 1.931m6.296 5.618c-.61.566-1.804.303-2.614-.591c-.837-.892-.994-2.086-.375-2.66c.63-.566 1.787-.301 2.626.591c.838.903 1 2.088.363 2.66m4.32 7.188c-.785.545-2.067.034-2.86-1.104c-.784-1.138-.784-2.503.017-3.05c.795-.547 2.058-.055 2.861 1.075c.782 1.157.782 2.522-.019 3.08m7.304 8.325c-.701.774-2.196.566-3.29-.49c-1.119-1.032-1.43-2.496-.726-3.27c.71-.776 2.213-.558 3.315.49c1.11 1.03 1.45 2.505.701 3.27m9.442 2.81c-.31 1.003-1.75 1.459-3.199 1.033c-1.448-.439-2.395-1.613-2.103-2.626c.301-1.01 1.747-1.484 3.207-1.028c1.446.436 2.396 1.602 2.095 2.622m10.744 1.193c.036 1.055-1.193 1.93-2.715 1.95c-1.53.034-2.769-.82-2.786-1.86c0-1.065 1.202-1.932 2.733-1.958c1.522-.03 2.768.818 2.768 1.868m10.555-.405c.182 1.03-.875 2.088-2.387 2.37c-1.485.271-2.861-.365-3.05-1.386c-.184-1.056.893-2.114 2.376-2.387c1.514-.263 2.868.356 3.061 1.403"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/gmail/icon.svg b/builtin-configs/integrations/gmail/icon.svg
index 409ae4da1c..8349042539 100644
--- a/builtin-configs/integrations/gmail/icon.svg
+++ b/builtin-configs/integrations/gmail/icon.svg
@@ -1,9 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path d="M24 5.457v13.909c0 .904-.732 1.636-1.636 1.636h-3.819V11.73L12 16.64l-6.545-4.91v9.272H1.636A1.636 1.636 0 0 1 0 19.366V5.457c0-.489.22-.952.6-1.26l.436-.328L12 12.184l10.964-8.315.436.328c.38.308.6.771.6 1.26Z" fill="#4285F4" />
-  <path d="M1.636 21.002h3.819V11.73L0 7.637v11.73c0 .903.732 1.635 1.636 1.635Z" fill="#34A853" />
-  <path d="M18.545 21.002h3.819A1.636 1.636 0 0 0 24 19.366V7.637l-5.455 4.093v9.272Z" fill="#FBBC04" />
-  <path d="M1.636 5.457v2.18L12 16.64l10.964-8.227V5.457L12 12.184 1.036 3.87l.6-.448Z" fill="#EA4335" />
+  <g transform="translate(4.5 6.3457) scale(0.0586)">
+    <path fill="#4285f4" d="M58.182 192.05V93.14L27.507 65.077L0 49.504v125.091c0 9.658 7.825 17.455 17.455 17.455z"/><path fill="#34a853" d="M197.818 192.05h40.727c9.659 0 17.455-7.826 17.455-17.455V49.505l-31.156 17.837l-27.026 25.798z"/><path fill="#ea4335" d="m58.182 93.14l-4.174-38.647l4.174-36.989L128 69.868l69.818-52.364l4.669 34.992l-4.669 40.644L128 145.504z"/><path fill="#fbbc04" d="M197.818 17.504V93.14L256 49.504V26.231c0-21.585-24.64-33.89-41.89-20.945z"/><path fill="#c5221f" d="m0 49.504l26.759 20.07L58.182 93.14V17.504L41.89 5.286C24.61-7.66 0 4.646 0 26.23z"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/google_drive/icon.svg b/builtin-configs/integrations/google_drive/icon.svg
index 7769f9b2f0..4e7a56ab6c 100644
--- a/builtin-configs/integrations/google_drive/icon.svg
+++ b/builtin-configs/integrations/google_drive/icon.svg
@@ -1,11 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path d="M7.71 3.5L1.15 14.85h6.56L14.27 3.5H7.71z" fill="#0066DA" />
-  <path d="M16.29 14.85l-3.27-5.67-3.32 5.67h6.59z" fill="#00AC47" />
-  <path d="M22.85 14.85L17.65 5.85 14.27 11.52l3.27 5.67h5.31z" fill="#EA4335" />
-  <path d="M11.7 14.85l-3.32 5.65h11.43l3.27-5.65H11.7z" fill="#00832D" />
-  <path d="M1.15 14.85l3.27 5.65h7.28l-3.27-5.65H1.15z" fill="#2684FC" />
-  <path d="M14.27 11.52l-3.27-5.67-3.29 5.67h6.56z" fill="#FFBA00" />
+  <g transform="translate(4.5 5.291) scale(0.0586)">
+    <path fill="#0066da" d="m19.354 196.034l11.29 19.5c2.346 4.106 5.718 7.332 9.677 9.678q17.009-21.591 23.68-33.137q6.77-11.717 16.641-36.655q-26.604-3.502-40.32-3.502q-13.165 0-40.322 3.502c0 4.545 1.173 9.09 3.519 13.196z"/><path fill="#ea4335" d="M215.681 225.212c3.96-2.346 7.332-5.572 9.677-9.677l4.692-8.064l22.434-38.855a26.57 26.57 0 0 0 3.518-13.196q-27.315-3.502-40.247-3.502q-13.899 0-40.248 3.502q9.754 25.075 16.422 36.655q6.724 11.683 23.752 33.137"/><path fill="#00832d" d="M128.001 73.311q19.68-23.768 27.125-36.655q5.996-10.377 13.196-33.137C164.363 1.173 159.818 0 155.126 0h-54.25C96.184 0 91.64 1.32 87.68 3.519q9.16 26.103 15.544 37.154q7.056 12.213 24.777 32.638"/><path fill="#2684fc" d="M175.36 155.42H80.642l-40.32 69.792c3.958 2.346 8.503 3.519 13.195 3.519h148.968c4.692 0 9.238-1.32 13.196-3.52z"/><path fill="#00ac47" d="M128.001 73.311L87.681 3.52c-3.96 2.346-7.332 5.571-9.678 9.677L3.519 142.224A26.57 26.57 0 0 0 0 155.42h80.642z"/><path fill="#ffba00" d="m215.242 77.71l-37.243-64.514c-2.345-4.106-5.718-7.331-9.677-9.677l-40.32 69.792l47.358 82.109h80.496c0-4.546-1.173-9.09-3.519-13.196z"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/shopify/icon.svg b/builtin-configs/integrations/shopify/icon.svg
index 2289145cf9..5ed9a94199 100644
--- a/builtin-configs/integrations/shopify/icon.svg
+++ b/builtin-configs/integrations/shopify/icon.svg
@@ -1,11 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path
-    fill-rule="evenodd"
-    clip-rule="evenodd"
-    d="M13.2094 3.669C13.2094 3.58725 13.2101 3.507 13.2101 3.41925C13.2101 2.65425 13.1042 2.03775 12.9347 1.5495C13.6161 1.635 14.0698 2.41425 14.3616 3.3105C14.0199 3.417 13.6311 3.53775 13.2094 3.669ZM11.7049 11.2965C11.7049 11.2965 10.9078 10.869 9.93094 10.869C8.49806 10.869 8.42569 11.7727 8.42569 12C8.42569 13.2427 11.6483 13.719 11.6483 16.629C11.6483 18.918 10.2034 20.3925 8.25488 20.3925C5.91675 20.3925 4.72125 18.93 4.72125 18.93L5.34731 16.8517C5.34731 16.8517 6.57637 17.9122 7.61381 17.9122C8.29069 17.9122 8.56687 17.376 8.56687 16.9845C8.56687 15.3637 5.92275 15.291 5.92275 12.6277C5.92275 10.3867 7.52363 8.21775 10.755 8.21775C11.9998 8.21775 12.6156 8.57625 12.6156 8.57625L11.7049 11.2965ZM11.1743 0.83025C11.3078 0.83025 11.4414 0.876 11.5699 0.9645C10.5825 1.431 9.525 2.607 9.078 4.9545C8.42494 5.15775 7.78687 5.3565 7.19662 5.54025C7.71956 3.74925 8.96213 0.83025 11.1743 0.83025ZM12.4026 3.786C12.4026 3.83325 12.4018 3.87675 12.4018 3.92025C11.6518 4.1535 10.8375 4.407 10.0211 4.66125C10.4794 2.88375 11.3385 2.025 12.09 1.701C12.2788 2.178 12.4026 2.86275 12.4026 3.786ZM15.9484 2.83069C15.8996 2.83706 15.8574 2.84662 15.828 2.85525C15.8123 2.85975 15.5496 2.9415 15.1146 3.0765C14.6886 1.845 13.9371 0.71325 12.6154 0.71325C12.5788 0.71325 12.5407 0.71475 12.5034 0.717C12.1273 0.2175 11.6616 0 11.2594 0C8.17931 0 6.70762 3.87 6.24637 5.83575C5.04937 6.2085 4.19925 6.47325 4.09106 6.50775C3.42244 6.7185 3.40144 6.7395 3.31425 7.37175C3.24788 7.851 1.5 21.4357 1.5 21.4357L15.1198 24L15.1343 23.9968L15.9484 2.83069ZM16.9236 3.49725C17.3168 3.88969 17.7626 4.33425 17.7626 4.33425C17.7626 4.33425 19.5977 4.47075 19.6843 4.47825C19.7717 4.48575 19.8769 4.5525 19.8932 4.67325C19.9097 4.794 22.5 22.3958 22.5 22.3958L16.1436 23.7774L16.9236 3.49725Z"
-    fill="#81BF37"
-  />
+  <g transform="translate(5.4247 4.5) scale(0.0514)">
+    <path fill="#95bf46" d="M223.774 57.34c-.201-1.46-1.48-2.268-2.537-2.357a19614 19614 0 0 0-23.383-1.743s-15.507-15.395-17.209-17.099c-1.703-1.703-5.029-1.185-6.32-.805c-.19.056-3.388 1.043-8.678 2.68c-5.18-14.906-14.322-28.604-30.405-28.604c-.444 0-.901.018-1.358.044C129.31 3.407 123.644.779 118.75.779c-37.465 0-55.364 46.835-60.976 70.635c-14.558 4.511-24.9 7.718-26.221 8.133c-8.126 2.549-8.383 2.805-9.45 10.462C21.3 95.806.038 260.235.038 260.235l165.678 31.042l89.77-19.42S223.973 58.8 223.775 57.34M156.49 40.848l-14.019 4.339c.005-.988.01-1.96.01-3.023c0-9.264-1.286-16.723-3.349-22.636c8.287 1.04 13.806 10.469 17.358 21.32m-27.638-19.483c2.304 5.773 3.802 14.058 3.802 25.238c0 .572-.005 1.095-.01 1.624c-9.117 2.824-19.024 5.89-28.953 8.966c5.575-21.516 16.025-31.908 25.161-35.828m-11.131-10.537c1.617 0 3.246.549 4.805 1.622c-12.007 5.65-24.877 19.88-30.312 48.297l-22.886 7.088C75.694 46.16 90.81 10.828 117.72 10.828"/><path fill="#5e8e3e" d="M221.237 54.983a19614 19614 0 0 0-23.383-1.743s-15.507-15.395-17.209-17.099c-.637-.634-1.496-.959-2.394-1.099l-12.527 256.233l89.762-19.418S223.972 58.8 223.774 57.34c-.201-1.46-1.48-2.268-2.537-2.357"/><path fill="#fff" d="m135.242 104.585l-11.069 32.926s-9.698-5.176-21.586-5.176c-17.428 0-18.305 10.937-18.305 13.693c0 15.038 39.2 20.8 39.2 56.024c0 27.713-17.577 45.558-41.277 45.558c-28.44 0-42.984-17.7-42.984-17.7l7.615-25.16s14.95 12.835 27.565 12.835c8.243 0 11.596-6.49 11.596-11.232c0-19.616-32.16-20.491-32.16-52.724c0-27.129 19.472-53.382 58.778-53.382c15.145 0 22.627 4.338 22.627 4.338"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/slack/icon.svg b/builtin-configs/integrations/slack/icon.svg
index 7eb898d22a..91a284ce26 100644
--- a/builtin-configs/integrations/slack/icon.svg
+++ b/builtin-configs/integrations/slack/icon.svg
@@ -1,9 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path d="M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52ZM6.313 15.165a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313Z" fill="#E01E5A" />
-  <path d="M8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834ZM8.834 6.313a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312Z" fill="#36C5F0" />
-  <path d="M18.956 8.834a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834ZM17.688 8.834a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312Z" fill="#2EB67D" />
-  <path d="M15.165 18.956a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52ZM15.165 17.688a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.528 2.528 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313Z" fill="#ECB22E" />
+  <g transform="translate(4.5 4.5) scale(0.0586)">
+    <path fill="#e01e5a" d="M53.841 161.32c0 14.832-11.987 26.82-26.819 26.82S.203 176.152.203 161.32c0-14.831 11.987-26.818 26.82-26.818H53.84zm13.41 0c0-14.831 11.987-26.818 26.819-26.818s26.819 11.987 26.819 26.819v67.047c0 14.832-11.987 26.82-26.82 26.82c-14.83 0-26.818-11.988-26.818-26.82z"/><path fill="#36c5f0" d="M94.07 53.638c-14.832 0-26.82-11.987-26.82-26.819S79.239 0 94.07 0s26.819 11.987 26.819 26.819v26.82zm0 13.613c14.832 0 26.819 11.987 26.819 26.819s-11.987 26.819-26.82 26.819H26.82C11.987 120.889 0 108.902 0 94.069c0-14.83 11.987-26.818 26.819-26.818z"/><path fill="#2eb67d" d="M201.55 94.07c0-14.832 11.987-26.82 26.818-26.82s26.82 11.988 26.82 26.82s-11.988 26.819-26.82 26.819H201.55zm-13.41 0c0 14.832-11.988 26.819-26.82 26.819c-14.831 0-26.818-11.987-26.818-26.82V26.82C134.502 11.987 146.489 0 161.32 0s26.819 11.987 26.819 26.819z"/><path fill="#ecb22e" d="M161.32 201.55c14.832 0 26.82 11.987 26.82 26.818s-11.988 26.82-26.82 26.82c-14.831 0-26.818-11.988-26.818-26.82V201.55zm0-13.41c-14.831 0-26.818-11.988-26.818-26.82c0-14.831 11.987-26.818 26.819-26.818h67.25c14.832 0 26.82 11.987 26.82 26.819s-11.988 26.819-26.82 26.819z"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/tavily/icon.svg b/builtin-configs/integrations/tavily/icon.svg
index 839e1570fa..80d651a3df 100644
--- a/builtin-configs/integrations/tavily/icon.svg
+++ b/builtin-configs/integrations/tavily/icon.svg
@@ -1,4 +1,4 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <path fill-rule="evenodd" clip-rule="evenodd" d="M10.5 4.25a6.25 6.25 0 1 0 3.83 11.19l3.49 3.49a1.1 1.1 0 0 0 1.56-1.56l-3.49-3.49A6.25 6.25 0 0 0 10.5 4.25Zm0 2.2a4.05 4.05 0 1 1 0 8.1 4.05 4.05 0 0 1 0-8.1Z" fill="#1F1E1E"/>
+  <path d="M12 12V5M12 12H19M12 12L5 19M9.5 7.5L12 5L14.5 7.5M16.5 9.5L19 12L16.5 14.5M8 19L5 19L5 16" stroke="#1F1E1E" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
 </svg>
diff --git a/builtin-configs/integrations/teams/icon.svg b/builtin-configs/integrations/teams/icon.svg
index 99a73bbede..783daa43b3 100644
--- a/builtin-configs/integrations/teams/icon.svg
+++ b/builtin-configs/integrations/teams/icon.svg
@@ -1,10 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path d="M20.625 10.5h-5.25a.375.375 0 0 0-.375.375v6a2.625 2.625 0 0 0 2.625 2.625h.75A2.625 2.625 0 0 0 21 16.875v-6a.375.375 0 0 0-.375-.375Z" fill="#5059C9" />
-  <circle cx="18" cy="7.5" r="2.25" fill="#5059C9" />
-  <path d="M14.25 10.5H7.125a.375.375 0 0 0-.375.375v7.5A3.375 3.375 0 0 0 10.125 21.75h.75a3.375 3.375 0 0 0 3.375-3.375v-7.5a.375.375 0 0 0 0-.375Z" fill="#7B83EB" />
-  <circle cx="10.5" cy="6" r="3" fill="#7B83EB" />
-  <path opacity="0.1" d="M10.875 10.5H6.75v8.25a3.37 3.37 0 0 0 2.503 3.254A3.375 3.375 0 0 0 14.25 18.75v-4.125A4.125 4.125 0 0 0 10.875 10.5Z" fill="black" />
+  <g transform="translate(4.5 4.998) scale(0.0586)">
+    <defs><linearGradient id="SVGCo9xpmZW" x1="17.372%" x2="82.628%" y1="-6.51%" y2="106.51%"><stop offset="0%" stop-color="#5a62c3"/><stop offset="50%" stop-color="#4d55bd"/><stop offset="100%" stop-color="#3940ab"/></linearGradient><path id="SVGhJCUgeMn" d="M136.93 64.476v12.8a32.7 32.7 0 0 1-5.953-.952a38.7 38.7 0 0 1-26.79-22.742h21.848c6.008.022 10.872 4.887 10.895 10.894"/></defs><path fill="#5059c9" d="M178.563 89.302h66.125c6.248 0 11.312 5.065 11.312 11.312v60.231c0 22.96-18.613 41.574-41.573 41.574h-.197c-22.96.003-41.576-18.607-41.579-41.568V95.215a5.91 5.91 0 0 1 5.912-5.913"/><circle cx="223.256" cy="50.605" r="26.791" fill="#5059c9"/><circle cx="139.907" cy="38.698" r="38.698" fill="#7b83eb"/><path fill="#7b83eb" d="M191.506 89.302H82.355c-6.173.153-11.056 5.276-10.913 11.449v68.697c-.862 37.044 28.445 67.785 65.488 68.692c37.043-.907 66.35-31.648 65.489-68.692v-68.697c.143-6.173-4.74-11.296-10.913-11.449"/><path d="M142.884 89.302v96.268a10.96 10.96 0 0 1-6.787 10.062c-1.3.55-2.697.833-4.108.833H76.68c-.774-1.965-1.488-3.93-2.084-5.953a72.5 72.5 0 0 1-3.155-21.076v-68.703c-.143-6.163 4.732-11.278 10.895-11.43z" opacity=".1"/><path d="M136.93 89.302v102.222c0 1.411-.283 2.808-.833 4.108a10.96 10.96 0 0 1-10.062 6.787H79.48c-1.012-1.965-1.965-3.93-2.798-5.954a59 59 0 0 1-2.084-5.953a72.5 72.5 0 0 1-3.155-21.076v-68.703c-.143-6.163 4.732-11.278 10.895-11.43z" opacity=".2"/><path d="M136.93 89.302v90.315c-.045 5.998-4.896 10.85-10.895 10.895H74.597a72.5 72.5 0 0 1-3.155-21.076v-68.703c-.143-6.163 4.732-11.278 10.895-11.43z" opacity=".2"/><path d="M130.977 89.302v90.315c-.046 5.998-4.897 10.85-10.895 10.895H74.597a72.5 72.5 0 0 1-3.155-21.076v-68.703c-.143-6.163 4.732-11.278 10.895-11.43z" opacity=".2"/><path d="M142.884 58.523v18.753c-1.012.06-1.965.12-2.977.12s-1.965-.06-2.977-.12a32.7 32.7 0 0 1-5.953-.952a38.7 38.7 0 0 1-26.791-22.742a33 33 0 0 1-1.905-5.954h29.708c6.007.023 10.872 4.887 10.895 10.895" opacity=".1"/><use href="#SVGhJCUgeMn" opacity=".2"/><use href="#SVGhJCUgeMn" opacity=".2"/><path d="M130.977 64.476v11.848a38.7 38.7 0 0 1-26.791-22.743h15.896c6.008.023 10.872 4.888 10.895 10.895" opacity=".2"/><path fill="url(#SVGCo9xpmZW)" d="M10.913 53.581h109.15c6.028 0 10.914 4.886 10.914 10.913v109.151c0 6.027-4.886 10.913-10.913 10.913H10.913C4.886 184.558 0 179.672 0 173.645V64.495C0 58.466 4.886 53.58 10.913 53.58"/><path fill="#fff" d="M94.208 95.125h-21.82v59.416H58.487V95.125H36.769V83.599h57.439z"/>
   </g>
 </svg>
diff --git a/builtin-configs/integrations/twilio/icon.svg b/builtin-configs/integrations/twilio/icon.svg
index 93d8562af3..7bbea0f3b7 100644
--- a/builtin-configs/integrations/twilio/icon.svg
+++ b/builtin-configs/integrations/twilio/icon.svg
@@ -1,6 +1,6 @@
 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="24" height="24" rx="6" fill="#FFFFFF"/>
-  <g transform="translate(4.500 4.500) scale(0.62500)">
-    <path fill-rule="evenodd" clip-rule="evenodd" d="M12 0C5.373 0 0 5.373 0 12s5.373 12 12 12 12-5.373 12-12S18.627 0 12 0Zm0 20.571a8.571 8.571 0 1 1 0-17.142 8.571 8.571 0 0 1 0 17.142Zm4.285-11.142a2.571 2.571 0 1 1-5.142 0 2.571 2.571 0 0 1 5.142 0Zm0 5.142a2.571 2.571 0 1 1-5.142 0 2.571 2.571 0 0 1 5.142 0Zm-5.142-5.142a2.571 2.571 0 1 1-5.143 0 2.571 2.571 0 0 1 5.143 0Zm0 5.142a2.571 2.571 0 1 1-5.143 0 2.571 2.571 0 0 1 5.143 0Z" fill="#F22F46" />
+  <g transform="translate(4.5 4.5) scale(0.0586)">
+    <path fill="#f12e45" d="M128 0c70.656 0 128 57.344 128 128s-57.344 128-128 128S0 198.656 0 128S57.344 0 128 0m0 33.792c-52.224 0-94.208 41.984-94.208 94.208S75.776 222.208 128 222.208s94.208-41.984 94.208-94.208S180.224 33.792 128 33.792m31.744 99.328c14.704 0 26.624 11.92 26.624 26.624s-11.92 26.624-26.624 26.624s-26.624-11.92-26.624-26.624s11.92-26.624 26.624-26.624m-63.488 0c14.704 0 26.624 11.92 26.624 26.624s-11.92 26.624-26.624 26.624s-26.624-11.92-26.624-26.624s11.92-26.624 26.624-26.624m63.488-63.488c14.704 0 26.624 11.92 26.624 26.624s-11.92 26.624-26.624 26.624s-26.624-11.92-26.624-26.624s11.92-26.624 26.624-26.624m-63.488 0c14.704 0 26.624 11.92 26.624 26.624s-11.92 26.624-26.624 26.624s-26.624-11.92-26.624-26.624s11.92-26.624 26.624-26.624"/>
   </g>
 </svg>
diff --git a/builtin-configs/providers/openrouter.json b/builtin-configs/providers/openrouter.json
index f64086478b..954c859cc3 100644
--- a/builtin-configs/providers/openrouter.json
+++ b/builtin-configs/providers/openrouter.json
@@ -13,28 +13,6 @@
     "text-to-speech": "openai/gpt-4o-mini-tts-2025-12-15"
   },
   "models": [
-    {
-      "id": "anthropic/claude-opus-4.6",
-      "displayName": "Claude Opus 4.6",
-      "description": "Anthropic's flagship — best for complex reasoning and coding",
-      "tags": ["chat", "vision"],
-      "reasoning": {
-        "knob": "budgetTokens",
-        "minBudgetTokens": 1024
-      },
-      "promptCaching": {
-        "mode": "explicit-breakpoints",
-        "maxBreakpoints": 4
-      },
-      "qualityScore": 0.98,
-      "contextWindow": 1000000,
-      "cost": {
-        "inputCentsPerMillion": 500.00000000000006,
-        "outputCentsPerMillion": 2500
-      },
-      "maxOutputTokens": 128000,
-      "hidden": true
-    },
     {
       "id": "anthropic/claude-sonnet-4.6",
       "displayName": "Claude Sonnet 4.6",
@@ -77,63 +55,6 @@
       },
       "maxOutputTokens": 64000
     },
-    {
-      "id": "openai/gpt-5.2-pro",
-      "displayName": "GPT-5.2 Pro",
-      "description": "OpenAI's most advanced model for the hardest reasoning tasks",
-      "tags": ["chat", "vision"],
-      "reasoning": {
-        "knob": "effort"
-      },
-      "promptCaching": {
-        "mode": "auto-server"
-      },
-      "qualityScore": 0.97,
-      "contextWindow": 400000,
-      "cost": {
-        "inputCentsPerMillion": 2100,
-        "outputCentsPerMillion": 16800
-      },
-      "maxOutputTokens": 128000,
-      "hidden": true
-    },
-    {
-      "id": "openai/gpt-5.2",
-      "displayName": "GPT-5.2",
-      "description": "OpenAI's flagship general-purpose model",
-      "tags": ["chat", "vision"],
-      "reasoning": {
-        "knob": "effort"
-      },
-      "promptCaching": {
-        "mode": "auto-server"
-      },
-      "qualityScore": 0.95,
-      "contextWindow": 400000,
-      "cost": {
-        "inputCentsPerMillion": 175,
-        "outputCentsPerMillion": 1400
-      },
-      "maxOutputTokens": 128000,
-      "hidden": true
-    },
-    {
-      "id": "openai/gpt-5.2-chat",
-      "displayName": "GPT-5.2 Instant",
-      "description": "Low-latency GPT-5.2 variant tuned for chat",
-      "tags": ["chat"],
-      "promptCaching": {
-        "mode": "auto-server"
-      },
-      "qualityScore": 0.85,
-      "contextWindow": 128000,
-      "cost": {
-        "inputCentsPerMillion": 175,
-        "outputCentsPerMillion": 1400
-      },
-      "maxOutputTokens": 16384,
-      "hidden": true
-    },
     {
       "id": "openai/gpt-oss-120b",
       "displayName": "GPT-OSS 120B",
@@ -313,45 +234,25 @@
       }
     },
     {
-      "id": "moonshotai/kimi-k2.5",
-      "displayName": "Kimi K2.5",
-      "description": "High-performance Moonshot general-purpose model",
-      "tags": ["chat"],
-      "qualityScore": 0.8,
-      "contextWindow": 262144,
-      "cost": {
-        "inputCentsPerMillion": 37.5,
-        "outputCentsPerMillion": 202.5
-      },
-      "reasoning": {
-        "knob": "effort"
-      }
-    },
-    {
-      "id": "minimax/minimax-m2.7",
-      "displayName": "MiniMax M2.7",
-      "description": "MiniMax flagship MoE for agentic coding and reasoning",
-      "tags": ["chat"],
+      "id": "moonshotai/kimi-k2.7-code",
+      "displayName": "Kimi K2.7 Code",
+      "description": "Moonshot's coding-specialized Kimi K2.7 — agentic coding, multimodal, 262K context",
+      "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
       },
-      "qualityScore": 0.78,
-      "contextWindow": 204800,
+      "qualityScore": 0.84,
+      "routingTags": ["code"],
+      "contextWindow": 262144,
       "cost": {
-        "inputCentsPerMillion": 25,
-        "outputCentsPerMillion": 100
-      },
-      "providerOptions": {
-        "provider": {
-          "quantizations": ["fp8", "fp4"]
-        }
+        "inputCentsPerMillion": 61.2,
+        "outputCentsPerMillion": 306.9
       },
-      "maxOutputTokens": 131072,
-      "hidden": true
+      "maxOutputTokens": 262144
     },
     {
       "id": "nvidia/nemotron-3-super-120b-a12b",
-      "displayName": "NVIDIA Nemotron 3 Super",
+      "displayName": "Nemotron 3 Super",
       "description": "NVIDIA frontier open-weight reasoning model",
       "tags": ["chat"],
       "reasoning": {
@@ -364,6 +265,22 @@
         "outputCentsPerMillion": 45
       }
     },
+    {
+      "id": "nvidia/nemotron-3-ultra-550b-a55b",
+      "displayName": "Nemotron 3 Ultra",
+      "description": "NVIDIA's flagship open-weight reasoning model (550B / 55B active), 1M context",
+      "tags": ["chat"],
+      "reasoning": {
+        "knob": "effort"
+      },
+      "qualityScore": 0.82,
+      "contextWindow": 1000000,
+      "cost": {
+        "inputCentsPerMillion": 50,
+        "outputCentsPerMillion": 220
+      },
+      "maxOutputTokens": 16384
+    },
     {
       "id": "qwen/qwen3.6-max-preview",
       "displayName": "Qwen3.6 Max Preview",
@@ -380,23 +297,6 @@
       },
       "maxOutputTokens": 65536
     },
-    {
-      "id": "qwen/qwen3.6-plus",
-      "displayName": "Qwen3.6 Plus",
-      "description": "Multimodal Qwen with 1M context",
-      "tags": ["chat", "vision"],
-      "qualityScore": 0.82,
-      "contextWindow": 1000000,
-      "cost": {
-        "inputCentsPerMillion": 32.5,
-        "outputCentsPerMillion": 195
-      },
-      "maxOutputTokens": 65536,
-      "reasoning": {
-        "knob": "effort"
-      },
-      "hidden": true
-    },
     {
       "id": "qwen/qwen3.6-flash",
       "displayName": "Qwen3.6 Flash",
@@ -413,43 +313,6 @@
         "knob": "effort"
       }
     },
-    {
-      "id": "qwen/qwen3.6-35b-a3b",
-      "displayName": "Qwen3.6 35B A3B",
-      "description": "Compact Qwen3.6 MoE, multimodal",
-      "tags": ["chat", "vision"],
-      "qualityScore": 0.72,
-      "contextWindow": 262144,
-      "cost": {
-        "inputCentsPerMillion": 15,
-        "outputCentsPerMillion": 100
-      },
-      "maxOutputTokens": 262144,
-      "reasoning": {
-        "knob": "effort"
-      }
-    },
-    {
-      "id": "qwen/qwen3.5-397b-a17b",
-      "displayName": "Qwen3.5 397B A17B",
-      "description": "Qwen3.5 large open-weight MoE (397B / 17B active)",
-      "tags": ["chat"],
-      "reasoning": {
-        "knob": "effort"
-      },
-      "qualityScore": 0.84,
-      "contextWindow": 262144,
-      "cost": {
-        "inputCentsPerMillion": 39,
-        "outputCentsPerMillion": 234
-      },
-      "providerOptions": {
-        "provider": {
-          "quantizations": ["fp8", "fp4"]
-        }
-      },
-      "maxOutputTokens": 65536
-    },
     {
       "id": "qwen/qwen3-coder",
       "displayName": "Qwen3 Coder 480B",
@@ -464,22 +327,6 @@
       },
       "maxOutputTokens": 65536
     },
-    {
-      "id": "qwen/qwen3-235b-a22b-2507",
-      "displayName": "Qwen3 235B A22B",
-      "description": "Qwen3 open-weight MoE (235B / 22B active), 262K context",
-      "tags": ["chat"],
-      "reasoning": {
-        "knob": "effort"
-      },
-      "qualityScore": 0.78,
-      "contextWindow": 262144,
-      "cost": {
-        "inputCentsPerMillion": 9,
-        "outputCentsPerMillion": 10
-      },
-      "maxOutputTokens": 16384
-    },
     {
       "id": "qwen/qwen3-vl-32b-instruct",
       "displayName": "Qwen3 VL 32B",
@@ -565,20 +412,6 @@
         "outputCentsPerMillion": 150
       }
     },
-    {
-      "id": "mistralai/mistral-medium-3",
-      "displayName": "Mistral Medium 3",
-      "description": "Mid-tier Mistral for general tasks",
-      "tags": ["chat"],
-      "maxOutputTokens": 8192,
-      "qualityScore": 0.74,
-      "contextWindow": 131072,
-      "cost": {
-        "inputCentsPerMillion": 40,
-        "outputCentsPerMillion": 200
-      },
-      "hidden": true
-    },
     {
       "id": "xiaomi/mimo-v2.5-pro",
       "displayName": "MiMo V2.5 Pro",
@@ -692,7 +525,8 @@
     },
     {
       "id": "qwen/qwen3.7-plus",
-      "displayName": "Qwen: Qwen3.7 Plus",
+      "displayName": "Qwen3.7 Plus",
+      "description": "Alibaba Qwen3.7 flagship — multimodal, 1M context",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
@@ -706,7 +540,8 @@
     },
     {
       "id": "minimax/minimax-m3",
-      "displayName": "MiniMax: MiniMax M3",
+      "displayName": "MiniMax M3",
+      "description": "MiniMax flagship MoE — multimodal, 1M context",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
@@ -720,7 +555,8 @@
     },
     {
       "id": "anthropic/claude-opus-4.8",
-      "displayName": "Anthropic: Claude Opus 4.8",
+      "displayName": "Claude Opus 4.8",
+      "description": "Anthropic's flagship — best for complex reasoning and coding",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "budgetTokens",
@@ -739,7 +575,8 @@
     },
     {
       "id": "mistralai/mistral-medium-3-5",
-      "displayName": "Mistral: Mistral Medium 3.5",
+      "displayName": "Mistral Medium 3.5",
+      "description": "Mistral's balanced multimodal mid-tier model",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
@@ -752,7 +589,8 @@
     },
     {
       "id": "openai/gpt-5.5-pro",
-      "displayName": "OpenAI: GPT-5.5 Pro",
+      "displayName": "GPT-5.5 Pro",
+      "description": "OpenAI's most advanced model for the hardest reasoning tasks",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
@@ -769,7 +607,8 @@
     },
     {
       "id": "openai/gpt-5.5",
-      "displayName": "OpenAI: GPT-5.5",
+      "displayName": "GPT-5.5",
+      "description": "OpenAI's flagship general-purpose model",
       "tags": ["chat", "vision"],
       "reasoning": {
         "knob": "effort"
@@ -786,7 +625,8 @@
     },
     {
       "id": "openai/gpt-5.3-chat",
-      "displayName": "OpenAI: GPT-5.3 Chat",
+      "displayName": "GPT-5.3 Chat",
+      "description": "Low-latency GPT-5 variant tuned for chat",
       "tags": ["chat", "vision"],
       "promptCaching": {
         "mode": "auto-server"
@@ -797,30 +637,170 @@
         "inputCentsPerMillion": 175,
         "outputCentsPerMillion": 1400
       }
+    },
+    {
+      "id": "x-ai/grok-4.20",
+      "displayName": "Grok 4.20",
+      "description": "xAI's flagship Grok — 2M-context multimodal reasoning with agentic tool use",
+      "tags": ["chat", "vision"],
+      "reasoning": {
+        "knob": "effort"
+      },
+      "promptCaching": {
+        "mode": "auto-server"
+      },
+      "qualityScore": 0.93,
+      "contextWindow": 2000000,
+      "cost": {
+        "inputCentsPerMillion": 125,
+        "outputCentsPerMillion": 250
+      }
+    },
+    {
+      "id": "cohere/command-a",
+      "displayName": "Command A",
+      "description": "Cohere's flagship — enterprise RAG and tool use, 256K context",
+      "tags": ["chat"],
+      "qualityScore": 0.8,
+      "contextWindow": 256000,
+      "cost": {
+        "inputCentsPerMillion": 250,
+        "outputCentsPerMillion": 1000
+      },
+      "maxOutputTokens": 8192
+    },
+    {
+      "id": "cohere/command-r-08-2024",
+      "displayName": "Command R",
+      "description": "Fast, low-cost Cohere model for RAG and retrieval",
+      "tags": ["chat"],
+      "qualityScore": 0.68,
+      "contextWindow": 128000,
+      "cost": {
+        "inputCentsPerMillion": 15,
+        "outputCentsPerMillion": 60
+      },
+      "maxOutputTokens": 4000
+    },
+    {
+      "id": "microsoft/phi-4",
+      "displayName": "Phi-4",
+      "description": "Microsoft's compact open-weight model for efficient reasoning",
+      "tags": ["chat"],
+      "qualityScore": 0.62,
+      "contextWindow": 16384,
+      "cost": {
+        "inputCentsPerMillion": 6.5,
+        "outputCentsPerMillion": 14
+      },
+      "maxOutputTokens": 16384
+    },
+    {
+      "id": "amazon/nova-premier-v1",
+      "displayName": "Nova Premier",
+      "description": "Amazon's most capable Nova model — multimodal, 1M context",
+      "tags": ["chat", "vision"],
+      "qualityScore": 0.8,
+      "contextWindow": 1000000,
+      "cost": {
+        "inputCentsPerMillion": 250,
+        "outputCentsPerMillion": 1250
+      },
+      "maxOutputTokens": 32000
+    },
+    {
+      "id": "amazon/nova-2-lite-v1",
+      "displayName": "Nova 2 Lite",
+      "description": "Fast, low-cost multimodal Nova with reasoning, 1M context",
+      "tags": ["chat", "vision"],
+      "reasoning": {
+        "knob": "effort"
+      },
+      "qualityScore": 0.72,
+      "contextWindow": 1000000,
+      "cost": {
+        "inputCentsPerMillion": 30,
+        "outputCentsPerMillion": 250
+      },
+      "maxOutputTokens": 65535
+    },
+    {
+      "id": "perplexity/sonar-pro",
+      "displayName": "Sonar Pro",
+      "description": "Perplexity's flagship answer engine with real-time web search and citations",
+      "tags": ["chat", "vision"],
+      "qualityScore": 0.78,
+      "contextWindow": 200000,
+      "cost": {
+        "inputCentsPerMillion": 300,
+        "outputCentsPerMillion": 1500
+      },
+      "maxOutputTokens": 8000
+    },
+    {
+      "id": "perplexity/sonar",
+      "displayName": "Sonar",
+      "description": "Low-cost Perplexity model with real-time web search",
+      "tags": ["chat", "vision"],
+      "qualityScore": 0.7,
+      "contextWindow": 127072,
+      "cost": {
+        "inputCentsPerMillion": 100,
+        "outputCentsPerMillion": 100
+      }
+    },
+    {
+      "id": "ai21/jamba-large-1.7",
+      "displayName": "Jamba Large 1.7",
+      "description": "AI21's hybrid SSM-Transformer with very long context",
+      "tags": ["chat"],
+      "qualityScore": 0.72,
+      "contextWindow": 256000,
+      "cost": {
+        "inputCentsPerMillion": 200,
+        "outputCentsPerMillion": 800
+      },
+      "maxOutputTokens": 4096
+    },
+    {
+      "id": "rekaai/reka-flash-3",
+      "displayName": "Reka Flash 3",
+      "description": "Reka's fast, efficient reasoning model",
+      "tags": ["chat"],
+      "reasoning": {
+        "knob": "effort"
+      },
+      "qualityScore": 0.66,
+      "contextWindow": 65536,
+      "cost": {
+        "inputCentsPerMillion": 10,
+        "outputCentsPerMillion": 20
+      },
+      "maxOutputTokens": 65536
+    },
+    {
+      "id": "liquid/lfm-2-24b-a2b",
+      "displayName": "LFM2 24B",
+      "description": "Liquid's efficient LFM2 MoE for fast, low-cost inference",
+      "tags": ["chat"],
+      "qualityScore": 0.6,
+      "contextWindow": 128000,
+      "cost": {
+        "inputCentsPerMillion": 3,
+        "outputCentsPerMillion": 12
+      }
     }
   ],
   "i18n": {
     "de": {
       "description": "Multi-Modell-KI-Gateway mit Zugang zu führenden LLM-Anbietern",
       "models": {
-        "anthropic/claude-opus-4.6": {
-          "description": "Leistungsstärkstes Modell für komplexe Aufgaben und Programmierung"
-        },
         "anthropic/claude-sonnet-4.6": {
           "description": "Ausgewogenes Anthropic-Modell für alltägliche Aufgaben"
         },
         "anthropic/claude-haiku-4.5": {
           "description": "Schnelles, schlankes Anthropic-Modell"
         },
-        "openai/gpt-5.2-pro": {
-          "description": "OpenAIs fortschrittlichstes Modell für anspruchsvollste Denkaufgaben"
-        },
-        "openai/gpt-5.2": {
-          "description": "OpenAIs Flaggschiff-Allzweckmodell"
-        },
-        "openai/gpt-5.2-chat": {
-          "description": "GPT-5.2-Variante mit niedriger Latenz, optimiert für Chat"
-        },
         "openai/gpt-oss-120b": {
           "description": "OpenAI open-weight MoE (117B / 5,1B aktiv), Apache 2.0, 131K Kontext"
         },
@@ -848,36 +828,18 @@
         "moonshotai/kimi-k2.6": {
           "description": "Moonshot K2.6 — multimodal, 262K Kontext"
         },
-        "moonshotai/kimi-k2.5": {
-          "description": "Hochleistungs-Allzweckmodell von Moonshot"
-        },
-        "minimax/minimax-m2.7": {
-          "description": "MiniMax-Flaggschiff-MoE für agentische Programmierung und Reasoning"
-        },
         "nvidia/nemotron-3-super-120b-a12b": {
           "description": "NVIDIAs open-weight-Reasoning-Modell der Spitzenklasse"
         },
         "qwen/qwen3.6-max-preview": {
           "description": "Alibaba-Qwen-Flaggschiff-Vorschau, 262K Kontext"
         },
-        "qwen/qwen3.6-plus": {
-          "description": "Multimodales Qwen mit 1M Kontext"
-        },
         "qwen/qwen3.6-flash": {
           "description": "Schnellste Qwen-Variante mit 1M Kontext, multimodal"
         },
-        "qwen/qwen3.6-35b-a3b": {
-          "description": "Kompaktes Qwen3.6-MoE, multimodal"
-        },
-        "qwen/qwen3.5-397b-a17b": {
-          "description": "Großes open-weight Qwen3.5-MoE (397B / 17B aktiv)"
-        },
         "qwen/qwen3-coder": {
           "description": "Qwen3-Coder-MoE (480B / 35B aktiv), abgestimmt auf agentische Programmierung, 262K Kontext"
         },
-        "qwen/qwen3-235b-a22b-2507": {
-          "description": "Qwen3 open-weight MoE (235B / 22B aktiv), 262K Kontext"
-        },
         "qwen/qwen3-vl-32b-instruct": {
           "description": "Qwen-Vision-Language-Modell zum Bildverständnis"
         },
@@ -896,9 +858,6 @@
         "mistralai/mistral-large-2512": {
           "description": "Mistrals Flaggschiff-Großmodell"
         },
-        "mistralai/mistral-medium-3": {
-          "description": "Mittelklasse-Mistral für allgemeine Aufgaben"
-        },
         "xiaomi/mimo-v2.5-pro": {
           "description": "Xiaomis Flaggschiff-Reasoning-Modell MiMo"
         },
@@ -922,30 +881,78 @@
         },
         "openai/gpt-4o-mini-tts-2025-12-15": {
           "description": "Günstige Sprachsynthese für den Voice-Modus, locale-zugeordnete Stimmen. Aktuelle Modell-id unter openrouter.ai/models (Text-to-Speech) prüfen — TTS-Versionen sind datiert und rotieren; id + defaults.text-to-speech gemeinsam aktualisieren. HINWEIS: Der cost-Wert ist eine Zeichen-Näherung nur für Tales Budget/Ledger; der Upstream rechnet pro Token ab — gegen den realen Nutzungs-Mix kalibrieren."
+        },
+        "x-ai/grok-4.20": {
+          "description": "xAIs Flaggschiff Grok — multimodales Reasoning mit 2M Kontext und agentischer Tool-Nutzung"
+        },
+        "cohere/command-a": {
+          "description": "Coheres Flaggschiff — Unternehmens-RAG und Tool-Nutzung, 256K Kontext"
+        },
+        "cohere/command-r-08-2024": {
+          "description": "Schnelles, günstiges Cohere-Modell für RAG und Retrieval"
+        },
+        "microsoft/phi-4": {
+          "description": "Microsofts kompaktes open-weight-Modell für effizientes Reasoning"
+        },
+        "amazon/nova-premier-v1": {
+          "description": "Amazons leistungsfähigstes Nova-Modell — multimodal, 1M Kontext"
+        },
+        "amazon/nova-2-lite-v1": {
+          "description": "Schnelles, günstiges multimodales Nova mit Reasoning, 1M Kontext"
+        },
+        "perplexity/sonar-pro": {
+          "description": "Perplexitys Flaggschiff-Antwortmaschine mit Echtzeit-Websuche und Quellenangaben"
+        },
+        "perplexity/sonar": {
+          "description": "Günstiges Perplexity-Modell mit Echtzeit-Websuche"
+        },
+        "ai21/jamba-large-1.7": {
+          "description": "AI21s hybrides SSM-Transformer-Modell mit sehr langem Kontext"
+        },
+        "rekaai/reka-flash-3": {
+          "description": "Rekas schnelles, effizientes Reasoning-Modell"
+        },
+        "liquid/lfm-2-24b-a2b": {
+          "description": "Liquids effizientes LFM2-MoE für schnelle, günstige Inferenz"
+        },
+        "nvidia/nemotron-3-ultra-550b-a55b": {
+          "description": "NVIDIAs Flaggschiff-open-weight-Reasoning-Modell (550B / 55B aktiv), 1M Kontext"
+        },
+        "moonshotai/kimi-k2.7-code": {
+          "description": "Moonshot Kimi K2.7, spezialisiert auf agentisches Programmieren, multimodal, 262K Kontext"
+        },
+        "qwen/qwen3.7-plus": {
+          "description": "Alibaba-Qwen3.7-Flaggschiff — multimodal, 1M Kontext"
+        },
+        "minimax/minimax-m3": {
+          "description": "MiniMax-Flaggschiff-MoE — multimodal, 1M Kontext"
+        },
+        "anthropic/claude-opus-4.8": {
+          "description": "Anthropics Flaggschiff — am besten für komplexes Reasoning und Programmierung"
+        },
+        "mistralai/mistral-medium-3-5": {
+          "description": "Ausgewogenes multimodales Mittelklasse-Modell von Mistral"
+        },
+        "openai/gpt-5.5-pro": {
+          "description": "OpenAIs fortschrittlichstes Modell für anspruchsvollste Denkaufgaben"
+        },
+        "openai/gpt-5.5": {
+          "description": "OpenAIs Flaggschiff-Allzweckmodell"
+        },
+        "openai/gpt-5.3-chat": {
+          "description": "GPT-5-Variante mit niedriger Latenz, optimiert für Chat"
         }
       }
     },
     "fr": {
       "description": "Passerelle IA multi-modèles avec accès aux principaux fournisseurs de LLM",
       "models": {
-        "anthropic/claude-opus-4.6": {
-          "description": "Le modèle phare d'Anthropic — idéal pour le raisonnement complexe et le code"
-        },
         "anthropic/claude-sonnet-4.6": {
           "description": "Modèle Anthropic équilibré pour les tâches courantes"
         },
         "anthropic/claude-haiku-4.5": {
           "description": "Modèle Anthropic rapide et léger"
         },
-        "openai/gpt-5.2-pro": {
-          "description": "Le modèle le plus avancé d'OpenAI pour les tâches de raisonnement les plus exigeantes"
-        },
-        "openai/gpt-5.2": {
-          "description": "Modèle généraliste phare d'OpenAI"
-        },
-        "openai/gpt-5.2-chat": {
-          "description": "Variante GPT-5.2 à faible latence optimisée pour le chat"
-        },
         "openai/gpt-oss-120b": {
           "description": "MoE open-weight d'OpenAI (117B / 5,1B actifs), Apache 2.0, contexte 131K"
         },
@@ -973,36 +980,18 @@
         "moonshotai/kimi-k2.6": {
           "description": "Moonshot K2.6 — multimodal, contexte 262K"
         },
-        "moonshotai/kimi-k2.5": {
-          "description": "Modèle généraliste haute performance de Moonshot"
-        },
-        "minimax/minimax-m2.7": {
-          "description": "MoE phare de MiniMax pour le code agentique et le raisonnement"
-        },
         "nvidia/nemotron-3-super-120b-a12b": {
           "description": "Modèle de raisonnement open-weight de pointe de NVIDIA"
         },
         "qwen/qwen3.6-max-preview": {
           "description": "Aperçu phare d'Alibaba Qwen, contexte 262K"
         },
-        "qwen/qwen3.6-plus": {
-          "description": "Qwen multimodal avec contexte 1M"
-        },
         "qwen/qwen3.6-flash": {
           "description": "La variante Qwen la plus rapide à contexte 1M, multimodale"
         },
-        "qwen/qwen3.6-35b-a3b": {
-          "description": "MoE Qwen3.6 compact, multimodal"
-        },
-        "qwen/qwen3.5-397b-a17b": {
-          "description": "Grand MoE open-weight Qwen3.5 (397B / 17B actifs)"
-        },
         "qwen/qwen3-coder": {
           "description": "MoE Qwen3-Coder (480B / 35B actifs) optimisé pour le code agentique, contexte 262K"
         },
-        "qwen/qwen3-235b-a22b-2507": {
-          "description": "MoE Qwen3 open-weight (235B / 22B actifs), contexte 262K"
-        },
         "qwen/qwen3-vl-32b-instruct": {
           "description": "Modèle vision-langage Qwen pour la compréhension d'images"
         },
@@ -1021,9 +1010,6 @@
         "mistralai/mistral-large-2512": {
           "description": "Grand modèle phare de Mistral"
         },
-        "mistralai/mistral-medium-3": {
-          "description": "Mistral milieu de gamme pour les tâches générales"
-        },
         "xiaomi/mimo-v2.5-pro": {
           "description": "Modèle de raisonnement phare MiMo de Xiaomi"
         },
@@ -1047,6 +1033,66 @@
         },
         "openai/gpt-4o-mini-tts-2025-12-15": {
           "description": "Synthèse vocale économique pour le mode vocal, voix mappées par locale. Vérifie l'id du modèle actuel sur openrouter.ai/models (Text-to-Speech) — les versions TTS sont datées et changent ; mets à jour l'id + defaults.text-to-speech ensemble. NOTE : le coût ci-dessous est une approximation par caractère utilisée uniquement par le budget/ledger de Tale ; l'upstream facture au token — recalibre selon ton usage réel."
+        },
+        "x-ai/grok-4.20": {
+          "description": "Le modèle phare Grok de xAI — raisonnement multimodal avec contexte 2M et usage agentique d'outils"
+        },
+        "cohere/command-a": {
+          "description": "Le modèle phare de Cohere — RAG d'entreprise et usage d'outils, contexte 256K"
+        },
+        "cohere/command-r-08-2024": {
+          "description": "Modèle Cohere rapide et économique pour le RAG et la recherche"
+        },
+        "microsoft/phi-4": {
+          "description": "Modèle open-weight compact de Microsoft pour un raisonnement efficace"
+        },
+        "amazon/nova-premier-v1": {
+          "description": "Le modèle Nova le plus performant d'Amazon — multimodal, contexte 1M"
+        },
+        "amazon/nova-2-lite-v1": {
+          "description": "Nova multimodal rapide et économique avec raisonnement, contexte 1M"
+        },
+        "perplexity/sonar-pro": {
+          "description": "Le moteur de réponse phare de Perplexity avec recherche web en temps réel et citations"
+        },
+        "perplexity/sonar": {
+          "description": "Modèle Perplexity économique avec recherche web en temps réel"
+        },
+        "ai21/jamba-large-1.7": {
+          "description": "Modèle hybride SSM-Transformer d'AI21 à très long contexte"
+        },
+        "rekaai/reka-flash-3": {
+          "description": "Modèle de raisonnement rapide et efficace de Reka"
+        },
+        "liquid/lfm-2-24b-a2b": {
+          "description": "MoE LFM2 efficace de Liquid pour une inférence rapide et économique"
+        },
+        "nvidia/nemotron-3-ultra-550b-a55b": {
+          "description": "Le modèle de raisonnement open-weight phare de NVIDIA (550B / 55B actifs), contexte 1M"
+        },
+        "moonshotai/kimi-k2.7-code": {
+          "description": "Kimi K2.7 de Moonshot, spécialisé dans le code agentique, multimodal, contexte 262K"
+        },
+        "qwen/qwen3.7-plus": {
+          "description": "Modèle phare Alibaba Qwen3.7 — multimodal, contexte 1M"
+        },
+        "minimax/minimax-m3": {
+          "description": "MoE phare de MiniMax — multimodal, contexte 1M"
+        },
+        "anthropic/claude-opus-4.8": {
+          "description": "Le modèle phare d'Anthropic — idéal pour le raisonnement complexe et le code"
+        },
+        "mistralai/mistral-medium-3-5": {
+          "description": "Modèle Mistral milieu de gamme, multimodal et équilibré"
+        },
+        "openai/gpt-5.5-pro": {
+          "description": "Le modèle le plus avancé d'OpenAI pour les tâches de raisonnement les plus exigeantes"
+        },
+        "openai/gpt-5.5": {
+          "description": "Modèle généraliste phare d'OpenAI"
+        },
+        "openai/gpt-5.3-chat": {
+          "description": "Variante GPT-5 à faible latence optimisée pour le chat"
         }
       }
     }
diff --git a/bun.lock b/bun.lock
index 441746ac88..788e7bc9a5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -23,6 +23,8 @@
       "devDependencies": {
         "@commitlint/cli": "20.5.0",
         "@commitlint/config-conventional": "20.5.0",
+        "@iconify-json/logos": "1.2.11",
+        "@iconify/utils": "3.1.3",
         "@storybook/addon-a11y": "10.3.5",
         "@storybook/addon-docs": "10.3.5",
         "@storybook/addon-themes": "10.3.5",
@@ -980,9 +982,11 @@
 
     "@hookform/resolvers": ["@hookform/resolvers@5.2.2", "", { "dependencies": { "@standard-schema/utils": "^0.3.0" }, "peerDependencies": { "react-hook-form": "^7.55.0" } }, "sha512-A/IxlMLShx3KjV/HeTcTfaMxdwy690+L/ZADoeaTltLx+CVuzkeVIPuybK3jrRfw7YZnmdKsVVHAlEPIAEUNlA=="],
 
+    "@iconify-json/logos": ["@iconify-json/logos@1.2.11", "", { "dependencies": { "@iconify/types": "*" } }, "sha512-fOo4pGEatuyuCFNL+cwquYMa2Im0oJHRHV7lt/Qqs5Ode/lPImHCQcfTtPzZj7qYMPb/h8YHN3TG54uEowrjNQ=="],
+
     "@iconify/types": ["@iconify/types@2.0.0", "", {}, "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg=="],
 
-    "@iconify/utils": ["@iconify/utils@3.1.0", "", { "dependencies": { "@antfu/install-pkg": "^1.1.0", "@iconify/types": "^2.0.0", "mlly": "^1.8.0" } }, "sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw=="],
+    "@iconify/utils": ["@iconify/utils@3.1.3", "", { "dependencies": { "@antfu/install-pkg": "^1.1.0", "@iconify/types": "^2.0.0", "import-meta-resolve": "^4.2.0" } }, "sha512-LPKOXPn/zV+zis1oOfGWogaXVpqUybF3ZS6SCZIsz8vg0ivVp9+fVqyYB7xq0aiST/VhUQYGO1qo6uoYSiEJqw=="],
 
     "@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.33.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.0.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ=="],
 
@@ -4880,6 +4884,8 @@
 
     "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
 
+    "mermaid/@iconify/utils": ["@iconify/utils@3.1.0", "", { "dependencies": { "@antfu/install-pkg": "^1.1.0", "@iconify/types": "^2.0.0", "mlly": "^1.8.0" } }, "sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw=="],
+
     "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],
 
     "mkdirp/minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
diff --git a/designs/platform/design-system.md b/designs/platform/design-system.md
index ac726a95b1..049dab1632 100644
--- a/designs/platform/design-system.md
+++ b/designs/platform/design-system.md
@@ -3,6 +3,14 @@
 > Dev handoff reference for the Tale Dashboard design file (`tale-dashboard`).
 > All component IDs reference nodes in the `.pen` design file.
 
+> **Implementation.** This document is the design _intent_; the design system that actually ships is
+> the `@tale/ui` library ([`packages/ui/src/components/`](../../packages/ui/src/components/)), composed
+> by feature pages. `@tale/ui` is the source of truth for code. Build pages by composing those
+> components — never hand-roll layout HTML. The concept→component catalog, the one `gap` spacing scale,
+> and the button-size policy live in the
+> [`ui-components` skill](../../.claude/skills/ui-components/SKILL.md); the working contract is in
+> [`AGENTS.md`](../../AGENTS.md).
+
 ---
 
 ## Table of Contents
diff --git a/docs-inter-font.png b/docs-inter-font.png
new file mode 100644
index 0000000000..5651f1a491
Binary files /dev/null and b/docs-inter-font.png differ
diff --git a/docs/de/cloud/onboarding.md b/docs/de/cloud/onboarding.md
index c4c0540dc2..37440c9d50 100644
--- a/docs/de/cloud/onboarding.md
+++ b/docs/de/cloud/onboarding.md
@@ -41,7 +41,7 @@ Für einen tieferen Spaziergang dazu, was einen Agent gut macht, siehe [Einen Ag
 
 ## Schritt 5 — Chat öffnen
 
-Öffne **Chat** in der Sidebar und klick **Neuer Chat**. Wähl den Agent im Picker, tipp eine Frage, die die Domäne des Agents abdeckt, sende. Die Antwort streamt zurück; landet sie so, wie du die Instructions geschrieben hast, ist die Org mit dem Onboarding fertig.
+Klick in der Sidebar auf **Neuer Chat**. Wähl den Agent im Picker, tipp eine Frage, die die Domäne des Agents abdeckt, sende. Die Antwort streamt zurück; landet sie so, wie du die Instructions geschrieben hast, ist die Org mit dem Onboarding fertig.
 
 Drei Folgeaufgaben, die sich jetzt lohnen, solange alles frisch ist:
 
diff --git a/docs/de/develop/ai-assisted-development.md b/docs/de/develop/ai-assisted-development.md
index b0bda80e92..226723f30a 100644
--- a/docs/de/develop/ai-assisted-development.md
+++ b/docs/de/develop/ai-assisted-development.md
@@ -27,14 +27,14 @@ Die Direktive zählt, weil jeder Editor unter Last Schema-Reads überspringt, so
 
 ## Was wo liegt
 
-| Pfad                               | Was es ist                                                                           |
-| ---------------------------------- | ------------------------------------------------------------------------------------ |
-| `agents/`                          | Eine JSON-Datei pro Agent — Anweisungen, Wissen, Tools, Modell.                      |
-| `workflows/`                       | Workflow-JSON-Configs, gruppiert nach Kategorie-Unterverzeichnis.                    |
-| `integrations/<slug>/config.json`  | Integration-Manifest — Operations, Auth-Methode, erlaubte Hosts.                     |
-| `integrations/<slug>/connector.ts` | Optionaler TypeScript-Connector für REST-Formen, die das Manifest nicht abdeckt.     |
-| `branding/branding.json`           | Org-Branding — Farben, Logos, E-Mail-Absender.                                       |
-| `.tale/reference/`                 | Schreibgeschützter Schema-Spiegel; neu erzeugt durch `tale init` und `tale upgrade`. |
+| Pfad                               | Was es ist                                                                          |
+| ---------------------------------- | ----------------------------------------------------------------------------------- |
+| `agents/`                          | Eine JSON-Datei pro Agent — Anweisungen, Wissen, Tools, Modell.                     |
+| `workflows/`                       | Workflow-JSON-Configs, gruppiert nach Kategorie-Unterverzeichnis.                   |
+| `integrations/<slug>/config.json`  | Integration-Manifest — Operations, Auth-Methode, erlaubte Hosts.                    |
+| `integrations/<slug>/connector.ts` | Optionaler TypeScript-Connector für REST-Formen, die das Manifest nicht abdeckt.    |
+| `branding/branding.json`           | Org-Branding — Farben, Logos, E-Mail-Absender.                                      |
+| `.tale/reference/`                 | Schreibgeschützter Schema-Spiegel; neu erzeugt durch `tale init` und `tale update`. |
 
 Der Reference-Baum ist byte-identisch zu den Schemas, gegen die die Plattform beim Deploy validiert. Behandle ihn als kanonisch: wenn ein Feldname in einer handgeschriebenen Config dem Reference widerspricht, gewinnt das Reference.
 
@@ -46,7 +46,7 @@ Die Rules-Datei nennt drei Regeln, die jeder Editor beim Bearbeiten durchsetzt:
 - **Workflows nutzen Integration-Operations.** Ein Workflow-Schritt referenziert Integration-Operations, die in `integrations/<slug>/config.json` deklariert sind. Ein Schritt gegen eine nicht-existente Operation zu bearbeiten, lässt die Validierung scheitern.
 - **Benennung ist erzwungen.** Agent-Dateinamen matchen `[a-z0-9][a-z0-9_-]*\.json`. Workflow-Step-Slugs matchen `[a-z0-9][a-z0-9_-]*`. Integration-Verzeichnisse sind kleingeschrieben alphanumerisch mit Bindestrichen oder Unterstrichen.
 
-Wenn der Editor eine Änderung vorschlägt, frag ihn, welche Datei in `.tale/reference/` er zugrunde gelegt hat. Wenn er das nicht kann, erzeug den Spiegel mit `tale upgrade` neu und versuch es nochmal.
+Wenn der Editor eine Änderung vorschlägt, frag ihn, welche Datei in `.tale/reference/` er zugrunde gelegt hat. Wenn er das nicht kann, erzeug den Spiegel mit `tale update` neu und versuch es nochmal.
 
 ## Wo das hingehört
 
diff --git a/docs/de/platform/agents/external-agent.md b/docs/de/platform/agents/external-agent.md
index 425ddf1ee7..f9fdd85d66 100644
--- a/docs/de/platform/agents/external-agent.md
+++ b/docs/de/platform/agents/external-agent.md
@@ -29,7 +29,7 @@ Wie der Agent sein Modell erreicht, ist eine Entscheidung pro Agent, die du im *
 
 **Verwaltet (Plattform-Gateway)** ist die Voreinstellung und das, was alle obigen Abschnitte beschreiben. Die Plattform prägt für die Runde einen kurzlebigen virtuellen Schlüssel, leitet den Agenten über ihr Gateway, erzwingt die erlaubten Modelle des Agenten, erfasst die Nutzung und wendet die Ausgabengrenzen der Organisation an. Die Sandbox hält nie einen echten Provider-Schlüssel.
 
-**Eigene Anmeldedaten (BYO)** nimmt die Plattform aus dem Anfragepfad heraus. Es wird kein virtueller Schlüssel geprägt; der Agent authentifiziert sich mit Anmeldedaten, die du unter [Umgebung & Geheimnisse](/de/platform/member/environment) hinterlegst, und erreicht den Provider direkt. Das Modell wird zu einer rohen Provider-ID, die du wortwörtlich eintippst, statt zu einem Katalogeintrag, und die native Websuche und das native Abrufen des Agenten bleiben aktiviert, statt deaktiviert zu werden. Weil das Gateway umgangen wird, gelten die Modell-Erlaubnisliste, die Ausgabengrenzen und die Nutzungserfassung der Organisation nicht für BYO-Runden — Abrechnung und Limits wandern in dein eigenes Provider-Konto. Wechselst du einen Agenten von verwaltet auf BYO, werden seine gespeicherten Plattform-Modelle gelöscht, da Katalogverweise für eine rohe Durchleitung bedeutungslos sind; du gibst die rohen IDs neu ein.
+**Eigene Anmeldedaten (BYO)** nimmt die Plattform aus dem Anfragepfad heraus. Es wird kein virtueller Schlüssel geprägt; der Agent authentifiziert sich mit Anmeldedaten, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst, und erreicht den Provider direkt. Das Modell wird zu einer rohen Provider-ID, die du wortwörtlich eintippst, statt zu einem Katalogeintrag, und die native Websuche und das native Abrufen des Agenten bleiben aktiviert, statt deaktiviert zu werden. Weil das Gateway umgangen wird, gelten die Modell-Erlaubnisliste, die Ausgabengrenzen und die Nutzungserfassung der Organisation nicht für BYO-Runden — Abrechnung und Limits wandern in dein eigenes Provider-Konto. Wechselst du einen Agenten von verwaltet auf BYO, werden seine gespeicherten Plattform-Modelle gelöscht, da Katalogverweise für eine rohe Durchleitung bedeutungslos sind; du gibst die rohen IDs neu ein.
 
 Das verschiebt auch die Vertrauensgrenze. Im verwalteten Modus hält die Sandbox nur einen budgetbegrenzten Gateway-Schlüssel; im BYO-Modus wird deine echte Provider-Anmeldedaten in die Sandbox-Umgebung eingespeist — dieselbe Lage wie beim GitHub-Token in der Sandbox —, sodass jeder Code, den der Agent in der Box ausführt, sie lesen kann. Das ist Absicht: Es ist deine Box und deine Anmeldedaten. Einen Agenten zu konfigurieren ist ohnehin eine privilegierte Aktion, daher ist der Schalter pro Agent die einzige Stellschraube; es gibt keinen separaten Schalter auf Organisationsebene.
 
@@ -47,4 +47,4 @@ Diese Abrechnung ist eine Eigenschaft des Gateways und gilt daher nur für verwa
 
 ## Wo das hineinpasst
 
-Ein externer Agent verwandelt einen Chat-Thread in eine Live-Sitzung mit einem Coding-Werkzeug in einer Sandbox — du steuerst ihn in normaler Sprache, er arbeitet in einem isolierten Arbeitsbereich, und die Sitzung bleibt für Folgefragen bestehen, bis du den Thread schließt. Die Anmeldedaten sind die Achse, die entscheidet, wie viel davon unter der Kontrolle der Organisation läuft: Ein verwalteter Agent bleibt am Plattform-Gateway unter den Grenzen und der Erfassung der Organisation, während ein Agent mit eigenen Anmeldedaten mit den Schlüsseln läuft, die du unter [Umgebung & Geheimnisse](/de/platform/member/environment) hinterlegst, und deinem eigenen Provider-Konto gegenüber rechenschaftspflichtig ist. Die Drift-Kandidaten hier sind die Agenten- und Modellnamen; kombiniere diese Seite mit der laufenden [Provider-Liste](/de/platform/admin/providers), statt dir bestimmte Modellzeichenketten zu merken, und mit [Integrationen](/de/platform/integrations/overview) für die verbundenen Integrationen, die der Agent erreichen kann — von GitHub für einen echten Pull-Request-Workflow bis zu einer Such- oder Datenintegration, die externe Fakten in die Arbeit holt.
+Ein externer Agent verwandelt einen Chat-Thread in eine Live-Sitzung mit einem Coding-Werkzeug in einer Sandbox — du steuerst ihn in normaler Sprache, er arbeitet in einem isolierten Arbeitsbereich, und die Sitzung bleibt für Folgefragen bestehen, bis du den Thread schließt. Die Anmeldedaten sind die Achse, die entscheidet, wie viel davon unter der Kontrolle der Organisation läuft: Ein verwalteter Agent bleibt am Plattform-Gateway unter den Grenzen und der Erfassung der Organisation, während ein Agent mit eigenen Anmeldedaten mit den Schlüsseln läuft, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst, und deinem eigenen Provider-Konto gegenüber rechenschaftspflichtig ist. Die Drift-Kandidaten hier sind die Agenten- und Modellnamen; kombiniere diese Seite mit der laufenden [Provider-Liste](/de/platform/admin/providers), statt dir bestimmte Modellzeichenketten zu merken, und mit [Integrationen](/de/platform/integrations/overview) für die verbundenen Integrationen, die der Agent erreichen kann — von GitHub für einen echten Pull-Request-Workflow bis zu einer Such- oder Datenintegration, die externe Fakten in die Arbeit holt.
diff --git a/docs/de/platform/member/environment.md b/docs/de/platform/member/environment.md
index 36512f5100..8d70d151db 100644
--- a/docs/de/platform/member/environment.md
+++ b/docs/de/platform/member/environment.md
@@ -1,15 +1,15 @@
 ---
-title: Umgebung & Geheimnisse
+title: Umgebungsvariablen & Geheimnisse
 description: Deine persönlichen Umgebungsvariablen und Geheimnisse, die Tale in jede Agent-Sandbox einspeist, die du in einer Organisation startest — meist die Provider-Anmeldedaten, mit denen sich ein BYO-Agent authentifiziert.
 ---
 
-Umgebung & Geheimnisse ist dein persönlicher Speicher für Variablen, die Tale in jede Agent-Sandbox einspeist, die du in dieser Organisation startest. Startet ein externer Agent seine Sandbox, setzt Tale jeden hier gespeicherten Eintrag in die Umgebung des Containers, bevor der Agent läuft — ein Befehl, den der Agent absetzt, oder der Agent selbst kann ihn dann lesen. Der Hauptzweck sind Anmeldedaten: ein [externer BYO-Agent](/de/platform/agents/external-agent) authentifiziert sich mit dem API-Schlüssel oder Token, den du hier hältst, statt über das Plattform-Gateway. Es ist eine Seite auf Mitglieds-Ebene, die jede Rolle erreicht, und die Einträge sind auf dich und die aktuelle Organisation begrenzt — sie lecken nie zu Teamkolleginnen durch und folgen dir nie in eine andere Organisation.
+Umgebungsvariablen & Geheimnisse ist dein persönlicher Speicher für Variablen, die Tale in jede Agent-Sandbox einspeist, die du in dieser Organisation startest. Startet ein externer Agent seine Sandbox, setzt Tale jeden hier gespeicherten Eintrag in die Umgebung des Containers, bevor der Agent läuft — ein Befehl, den der Agent absetzt, oder der Agent selbst kann ihn dann lesen. Der Hauptzweck sind Anmeldedaten: ein [externer BYO-Agent](/de/platform/agents/external-agent) authentifiziert sich mit dem API-Schlüssel oder Token, den du hier hältst, statt über das Plattform-Gateway. Es ist eine Seite auf Mitglieds-Ebene, die jede Rolle erreicht, und die Einträge sind auf dich und die aktuelle Organisation begrenzt — sie lecken nie zu Teamkolleginnen durch und folgen dir nie in eine andere Organisation.
 
 Diese Seite zeigt die zwei Arten von Eintrag, wie Geheimnisse geschützt werden, welche Regeln Name und Wert erfüllen müssen, und wo die Werte landen.
 
 ## Variablen und Geheimnisse
 
-Öffne **Einstellungen > Umgebung**. Die Seite ist ein Hinzufügen-Formular oben und darunter die Liste dessen, was du gespeichert hast. Jeder Eintrag hat einen **Name** und einen **Wert**, dazu einen **Geheimnis**-Schalter, der entscheidet, wie der Wert gespeichert und angezeigt wird.
+Öffne **Einstellungen > Umgebung**. **Variable hinzufügen** öffnet einen Dialog für einen neuen Eintrag, darunter steht die Liste dessen, was du gespeichert hast. Jeder Eintrag hat einen **Name** und einen **Wert**, dazu einen **Geheimnis**-Schalter, der entscheidet, wie der Wert gespeichert und angezeigt wird.
 
 Eine einfache Variable wird unverändert gespeichert und in der Liste in voller Länge zurückgezeigt — nimm sie für unkritische Konfiguration, die der Agent erwartet, einen Regionsnamen oder einen Endpunkt. Ein **Geheimnis** wird im Moment des Speicherns verschlüsselt und ist von da an schreibgeschützt: Die Liste zeigt `••••••••` statt des Werts, und es gibt keinen Weg, ihn zurückzulesen. Schalt den Schalter für alles Sensible ein — einen API-Schlüssel, einen OAuth-Token, ein Passwort. Der Preis dafür ist, dass du den Wert eines Geheimnisses später nicht mehr prüfen kannst: Bist du dir unsicher, ob er stimmt, lösch ihn und füg ihn neu hinzu, statt nach einem Anzeigen-Knopf zu suchen, den es nicht gibt.
 
@@ -29,4 +29,4 @@ Dieser letzte Schritt ist die Grenze, die es zu verstehen lohnt: Die Werte lande
 
 ## Wo das hingehört
 
-Umgebung & Geheimnisse ist die eine Seite auf Mitglieds-Ebene, die in die Sandbox reicht statt in den Chat — so kommen deine eigenen Schlüssel und deine Konfiguration zu den Agents, die du startest, ohne dass ein Redakteur oder Admin sie für dich setzt. Der Eintrag, den du am häufigsten hinzufügen wirst, sind die Provider-Anmeldedaten für einen [externen BYO-Agenten](/de/platform/agents/external-agent); lies diese Seite neben jener, um beide Hälften zu sehen — wo die Anmeldedaten liegen und wie einem Agenten gesagt wird, sie statt des Plattform-Gateways zu nutzen. Für den Rest deiner persönlichen Einstellungen — Anzeigename, Passwort, eigene Anweisungen — siehe [Einstellungen](/de/platform/member/preferences).
+Umgebungsvariablen & Geheimnisse ist die eine Seite auf Mitglieds-Ebene, die in die Sandbox reicht statt in den Chat — so kommen deine eigenen Schlüssel und deine Konfiguration zu den Agents, die du startest, ohne dass ein Redakteur oder Admin sie für dich setzt. Der Eintrag, den du am häufigsten hinzufügen wirst, sind die Provider-Anmeldedaten für einen [externen BYO-Agenten](/de/platform/agents/external-agent); lies diese Seite neben jener, um beide Hälften zu sehen — wo die Anmeldedaten liegen und wie einem Agenten gesagt wird, sie statt des Plattform-Gateways zu nutzen. Für den Rest deiner persönlichen Einstellungen — Anzeigename, Passwort, eigene Anweisungen — siehe [Einstellungen](/de/platform/member/preferences).
diff --git a/docs/de/platform/member/overview.md b/docs/de/platform/member/overview.md
index 677b009bf9..11d56b0946 100644
--- a/docs/de/platform/member/overview.md
+++ b/docs/de/platform/member/overview.md
@@ -16,7 +16,7 @@ Die Mitglieder-Oberfläche ist bewusst eng. Die vier Kübel sind:
 - **Konversationen** — die Inbox-Threads lesen, die dir zugewiesen sind. Mitglieder antworten, wenn ein Agent eine Konversation zurückgibt; sie können Threads, die anderen gehören, nicht neu zuweisen oder schliessen.
 - **Genehmigungen** — die Genehmigungs-Karten lesen, die zu dir geroutet wurden. Klick auf Genehmigen, Ablehnen oder Änderungen anfordern; hinterlass einen Kommentar, wenn die Regel danach fragt.
 
-Die Org-Konfigurationseinstellungen — Anbieter, Integrationen, Agents, Governance — sind für Mitglieder ausgeblendet; was bleibt, ist zum Grossteil die Arbeits-Oberfläche. Die Ausnahme ist eine kleine persönliche Einstellungs-Gruppe, die jede Rolle trägt: Konto, Personalisierung und [Umgebung & Geheimnisse](/de/platform/member/environment), die Schlüssel und Variablen, die in die Sandboxes injiziert werden, die du fährst.
+Die Org-Konfigurationseinstellungen — Anbieter, Integrationen, Agents, Governance — sind für Mitglieder ausgeblendet; was bleibt, ist zum Grossteil die Arbeits-Oberfläche. Die Ausnahme ist eine kleine persönliche Einstellungs-Gruppe, die jede Rolle trägt: Konto, Personalisierung und [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment), die Schlüssel und Variablen, die in die Sandboxes injiziert werden, die du fährst.
 
 ## Seiten in diesem Bereich
 
diff --git a/docs/de/platform/member/preferences.md b/docs/de/platform/member/preferences.md
index ab34c77874..f2a4e6c248 100644
--- a/docs/de/platform/member/preferences.md
+++ b/docs/de/platform/member/preferences.md
@@ -37,4 +37,4 @@ Die Zeile **Abmelden** unten im Profilmenü bestätigt mit einem Dialog, bevor s
 
 ## Wo das hingehört
 
-Einstellungen sind die Linie zwischen dir und dem Rest der Organisation. Der Org-Admin setzt Standardwerte — inklusive ob Personalisierung für neue Mitglieder an ist, was die Passwort-Richtlinie ist, welche Modelle erlaubt sind — und deine Einstellungen überschreiben die Standardwerte dort, wo Tale es zulässt. Eine persönliche Seite steht abseits dieses Sets: [Umgebung & Geheimnisse](/de/platform/member/environment) hält Variablen und Anmeldedaten, die innerhalb einer einzelnen Organisation auf dich begrenzt sind, statt dir über Organisationen hinweg zu folgen — der Ort für den Provider-Schlüssel, den ein BYO-Agent benutzt. Die nächste Lektüre, die sich lohnt, ist [Mitglieds-Übersicht](/de/platform/member/overview) für die Karte des restlichen Mitglieder-Bereichs, oder [Als App installieren](/de/platform/member/install-as-app), wenn du willst, dass Tale in deinem Dock statt in deinen Browser-Tabs lebt.
+Einstellungen sind die Linie zwischen dir und dem Rest der Organisation. Der Org-Admin setzt Standardwerte — inklusive ob Personalisierung für neue Mitglieder an ist, was die Passwort-Richtlinie ist, welche Modelle erlaubt sind — und deine Einstellungen überschreiben die Standardwerte dort, wo Tale es zulässt. Eine persönliche Seite steht abseits dieses Sets: [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hält Variablen und Anmeldedaten, die innerhalb einer einzelnen Organisation auf dich begrenzt sind, statt dir über Organisationen hinweg zu folgen — der Ort für den Provider-Schlüssel, den ein BYO-Agent benutzt. Die nächste Lektüre, die sich lohnt, ist [Mitglieds-Übersicht](/de/platform/member/overview) für die Karte des restlichen Mitglieder-Bereichs, oder [Als App installieren](/de/platform/member/install-as-app), wenn du willst, dass Tale in deinem Dock statt in deinen Browser-Tabs lebt.
diff --git a/docs/de/platform/models.md b/docs/de/platform/models.md
index e1fe104659..a25220cbbb 100644
--- a/docs/de/platform/models.md
+++ b/docs/de/platform/models.md
@@ -17,21 +17,65 @@ OpenRouter ist ein OpenAI-kompatibler Endpunkt, den Tale per HTTPS mit Bearer-To
 
 ## OpenRouter — Chat, Vision, Embeddings
 
-OpenRouter ist ein Multi-Modell-Gateway. Die ausgelieferte Konfiguration wählt `deepseek-v4-flash` als Default-Chat-Modell, `qwen3-vl-32b-instruct` für Vision und `qwen3-embedding-8b` für Embeddings — alle wegen des Geschwindigkeits-zu-Qualität-Verhältnisses zum Zeitpunkt des Schreibens. Die volle Lieferliste:
-
-- **Anthropic** — Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5.
-- **OpenAI** — GPT-5.2 Pro, GPT-5.2, GPT-5.2 Instant, GPT-OSS 120B (das Open-Weight-Release).
-- **Google** — Gemini 3 Pro, Gemini 3 Flash, Gemma 4 31B IT, Gemma 4 26B A4B IT, Nano Banana (Gemini 2.5 Flash Image).
-- **DeepSeek** — DeepSeek V4 Pro, DeepSeek V4 Flash.
-- **Moonshot AI** — Kimi K2.6, Kimi K2.5.
-- **MiniMax** — MiniMax M2.7.
-- **NVIDIA** — Nemotron 3 Super 120B.
-- **Qwen** — Qwen3.6 Max Preview, Qwen3.6 Plus, Qwen3.6 Flash, Qwen3.6 35B A3B, Qwen3.5 397B A17B, Qwen3 Coder 480B, Qwen3 235B A22B, Qwen3 VL 32B, Qwen3 Embedding 8B.
-- **Z.AI** — GLM 5.1, GLM 5 Turbo, GLM 5V Turbo.
-- **Mistral** — Mistral Large 3, Mistral Medium 3.
-- **Xiaomi** — MiMo V2.5 Pro.
-- **Meta** — LLaMA 4 Maverick, LLaMA 4 Scout.
-- **Black Forest Labs** — FLUX.2 [max], FLUX.2 [pro], FLUX.2 [flex].
+OpenRouter ist ein Multi-Modell-Gateway. Die ausgelieferte Konfiguration wählt `deepseek-v4-flash` als Default-Chat-Modell, `qwen3-vl-32b-instruct` für Vision und `qwen3-embedding-8b` für Embeddings — alle wegen des Geschwindigkeits-zu-Qualität-Verhältnisses zum Zeitpunkt des Schreibens. Die volle Lieferliste unten umfasst jedes sichtbare Modell der ausgelieferten `openrouter.json` und wird vom wöchentlichen Katalog-Job neu generiert, damit sie nie von der Konfiguration abweicht:
+
+<!-- MODELS_TABLE:START -->
+
+<!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. -->
+
+| Anbieter          | Modell                               | Fähigkeiten                  | Kontext | Eingabe ($/M) | Ausgabe ($/M) |
+| ----------------- | ------------------------------------ | ---------------------------- | ------- | ------------- | ------------- |
+| AI21              | Jamba Large 1.7                      | chat                         | 256K    | 2.00          | 8.00          |
+| Amazon            | Nova Premier                         | chat, vision                 | 1M      | 2.50          | 12.50         |
+| Amazon            | Nova 2 Lite                          | chat, vision                 | 1M      | 0.30          | 2.50          |
+| Anthropic         | Claude Sonnet 4.6                    | chat, vision                 | 1M      | 3.00          | 15.00         |
+| Anthropic         | Claude Haiku 4.5                     | chat                         | 200K    | 1.00          | 5.00          |
+| Anthropic         | Claude Opus 4.8                      | chat, vision                 | 1M      | 5.00          | 25.00         |
+| Black Forest Labs | FLUX.2 [flex]                        | image-generation, image-edit | —       | —             | —             |
+| Black Forest Labs | FLUX.2 [max]                         | image-generation, image-edit | —       | —             | —             |
+| Black Forest Labs | FLUX.2 [pro]                         | image-generation, image-edit | —       | —             | —             |
+| Cohere            | Command A                            | chat                         | 256K    | 2.50          | 10.00         |
+| Cohere            | Command R                            | chat                         | 128K    | 0.15          | 0.60          |
+| DeepSeek          | DeepSeek V4 Pro                      | chat                         | 1M      | 0.43          | 0.87          |
+| DeepSeek          | DeepSeek V4 Flash                    | chat                         | 1M      | 0.09          | 0.18          |
+| Google            | Gemini 3 Pro                         | chat, vision                 | 1M      | 2.00          | 12.00         |
+| Google            | Gemini 3 Flash                       | chat, vision                 | 1M      | 0.50          | 3.00          |
+| Google            | Gemma 4 31B IT                       | chat, vision                 | 262K    | 0.12          | 0.35          |
+| Google            | Gemma 4 26B A4B IT                   | chat, vision                 | 262K    | 0.06          | 0.33          |
+| Google            | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K     | 0.30          | 2.50          |
+| Liquid            | LFM2 24B                             | chat                         | 128K    | 0.03          | 0.12          |
+| Meta              | LLaMA 4 Maverick                     | chat                         | 1M      | 0.15          | 0.60          |
+| Meta              | LLaMA 4 Scout                        | chat                         | 10M     | 0.10          | 0.30          |
+| Microsoft         | Phi-4                                | chat                         | 16K     | 0.07          | 0.14          |
+| MiniMax           | MiniMax M3                           | chat, vision                 | 1M      | 0.30          | 1.20          |
+| Mistral           | Mistral Large 3                      | chat                         | 262K    | 0.50          | 1.50          |
+| Mistral           | Mistral Medium 3.5                   | chat, vision                 | 262K    | 1.50          | 7.50          |
+| Moonshot AI       | Kimi K2.6                            | chat, vision                 | 262K    | 0.68          | 3.41          |
+| Moonshot AI       | Kimi K2.7 Code                       | chat, vision                 | 262K    | 0.61          | 3.07          |
+| NVIDIA            | Nemotron 3 Ultra                     | chat                         | 1M      | 0.50          | 2.20          |
+| NVIDIA            | Nemotron 3 Super                     | chat                         | 1M      | 0.09          | 0.45          |
+| OpenAI            | GPT-OSS 120B                         | chat                         | 131K    | 0.04          | 0.18          |
+| OpenAI            | GPT-4o mini TTS                      | text-to-speech               | —       | —             | —             |
+| OpenAI            | GPT-5.3 Chat                         | chat, vision                 | 128K    | 1.75          | 14.00         |
+| OpenAI            | GPT-5.5                              | chat, vision                 | 1M      | 5.00          | 30.00         |
+| OpenAI            | GPT-5.5 Pro                          | chat, vision                 | 1M      | 30.00         | 180.00        |
+| OpenAI            | Whisper v1                           | transcription                | —       | —             | —             |
+| Perplexity        | Sonar Pro                            | chat, vision                 | 200K    | 3.00          | 15.00         |
+| Perplexity        | Sonar                                | chat, vision                 | 127K    | 1.00          | 1.00          |
+| Qwen              | Qwen3.6 Max Preview                  | chat                         | 262K    | 1.04          | 6.24          |
+| Qwen              | Qwen3 Coder 480B                     | chat                         | 1M      | 0.22          | 1.80          |
+| Qwen              | Qwen3 VL 32B                         | chat, vision                 | 262K    | 0.10          | 0.42          |
+| Qwen              | Qwen3.6 Flash                        | chat, vision                 | 1M      | 0.19          | 1.13          |
+| Qwen              | Qwen3 Embedding 8B                   | embedding                    | —       | 0.01          | 0.00          |
+| Qwen              | Qwen3.7 Plus                         | chat, vision                 | 1M      | 0.32          | 1.28          |
+| Reka              | Reka Flash 3                         | chat                         | 66K     | 0.10          | 0.20          |
+| Xiaomi            | MiMo V2.5 Pro                        | chat                         | 1M      | 0.43          | 0.87          |
+| Z.AI              | GLM 5.1                              | chat                         | 203K    | 0.98          | 3.08          |
+| Z.AI              | GLM 5 Turbo                          | chat                         | 262K    | 1.20          | 4.00          |
+| Z.AI              | GLM 5V Turbo                         | chat, vision                 | 131K    | 1.20          | 4.00          |
+| xAI               | Grok 4.20                            | chat, vision                 | 2M      | 1.25          | 2.50          |
+
+<!-- MODELS_TABLE:END -->
 
 Der volle und aktuelle Katalog lebt auf [openrouter.ai/models](https://openrouter.ai/models). Jedes Modell, das OpenRouter exponiert, kannst du auf deiner Instanz hinzufügen, indem du das `models`-Array in `<orgSlug>/providers/openrouter.json` unter `TALE_CONFIG_DIR` bearbeitest (pro Org unter dem org-first Layout).
 
diff --git a/docs/de/self-hosted/configuration/providers.md b/docs/de/self-hosted/configuration/providers.md
index 26c0cc82d5..d333135ff6 100644
--- a/docs/de/self-hosted/configuration/providers.md
+++ b/docs/de/self-hosted/configuration/providers.md
@@ -33,7 +33,7 @@ Die Referenz ist das Dateiformat auf Platte und die Reihenfolge der Operationen,
 }
 ```
 
-Die vollständige Menge der Felder lebt in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Der ausgelieferte Default ist eine einzige `openrouter.json`, die Chat, Vision, Embeddings, Transkription, Text-to-Speech und Bildgenerierung abdeckt — ein Key für alles. Um einen Anbieter direkt statt über OpenRouter aufzurufen, füg eine weitere Datei hinzu (z. B. eine `openai.json`, die auf `https://api.openai.com/v1` zeigt); siehe [Modelle out of the box](/de/platform/models) für den vollen Default-Katalog.
+Die vollständige Menge der Felder lebt in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Der ausgelieferte Default ist eine einzige `openrouter.json`, die Chat, Vision, Embeddings, Transkription, Text-to-Speech und Bildgenerierung abdeckt — ein Key für alles — mit kuratierten Presets für die gängigen Anbieter (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity und mehr). Um einen Anbieter direkt statt über OpenRouter aufzurufen, füg eine weitere Datei hinzu (z. B. eine `openai.json`, die auf `https://api.openai.com/v1` zeigt); siehe [Modelle out of the box](/de/platform/models) für den vollen Default-Katalog.
 
 `transcriptionMode` wählt, wie der Request-Body eines `transcription`-Modells geformt wird: `json-base64` (OpenRouters `input_audio`-Envelope) oder, wenn weggelassen, `multipart` — der OpenAI/Whisper-`multipart/form-data`-Upload, den auch vLLM, LocalAI und ein direkter OpenAI-Key erwarten. Setz es passend zum Transkriptions-Endpunkt, auf den du zeigst.
 
diff --git a/docs/de/self-hosted/configuration/retention.md b/docs/de/self-hosted/configuration/retention.md
index 5553f2c1ff..473893dd24 100644
--- a/docs/de/self-hosted/configuration/retention.md
+++ b/docs/de/self-hosted/configuration/retention.md
@@ -37,6 +37,8 @@ Unter dem Org-first-Layout sind Retention-Grenzen **pro Org**: editiere `retenti
 
 Der Plattform-Container beobachtet die Datei; Änderungen schlagen ein Grenzen-Update für jede bestehende Org vor. Admins sehen den Vorschlag in ihrem **Retention-Policy**-Bildschirm und wenden ihn selbst an. Der Vorschlagen-dann-anwenden-Schritt ist Absicht: Eine Untergrenze anzuziehen kürzt Historie, was eine destruktive Aktion ist, die kein Operator stillschweigend bei jeder Mandantin landen sollte.
 
+Die vom Admin gewählten Aufbewahrungsfenster liegen in einer separaten Datei, `retention-policy.json`, neben den Grenzen im selben `governance/`-Ordner. Sie enthält flache Felder `<Kategorie>Enabled` / `<Kategorie>RetentionDays` (z. B. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), nicht die `min`/`max`-Grenzen. Diese Datei schreibt **Einstellungen > Governance > Retention-Policy** in der App, Admins bearbeiten sie also normalerweise nie von Hand — halte sie getrennt von der vom Operator verwalteten Grenzen-Datei.
+
 ## Der Retention-Sweep
 
 Ein geplanter Cron in `tale-convex` läuft die tatsächliche Löschung. Jede Kategorie wird unabhängig gesweept — ein langsamer Lauf einer blockiert die anderen nicht. Löschungen sind audited (jede Kategorie hat ihr eigenes `*.retention_deleted`-Event), und eine Entität in ihrem Gnaden-Fenster wiederherzustellen ist von **Papierkorb** möglich, bevor der finale Sweep läuft.
diff --git a/docs/de/self-hosted/install/cli-install.md b/docs/de/self-hosted/install/cli-install.md
index 0f236eefd8..78d72695a4 100644
--- a/docs/de/self-hosted/install/cli-install.md
+++ b/docs/de/self-hosted/install/cli-install.md
@@ -133,14 +133,16 @@ Befehle beenden mit `0` bei Erfolg, `2` bei einem Nutzungsfehler, `3` bei einer
 - `--stop` — laufende Projekt-Container vor dem Wiederherstellen stoppen.
 - `-y, --yes` — die Bestätigungsabfrage überspringen.
 
-`tale rollback` — auf die vorherige Patch-Version zurückrollen (nur Patch-Ebene). Keine Argumente.
+`tale rollback` — auf die vorherige Patch-Version zurückrollen (nur Patch-Ebene). Fragt vorher nach Bestätigung.
+
+- `-y, --yes` — die Bestätigungsabfrage überspringen (im nicht-interaktiven Betrieb erforderlich).
 
 ### Wartung
 
-`tale upgrade` (Alias `tale update`) — die CLI auf die neueste Version aktualisieren und Projektdateien synchronisieren.
+`tale update` — diese Tale-Instanz auf eine neue Version bewegen: zuerst das CLI-Binary aktualisieren, dann die Projektdateien synchronisieren; danach `tale deploy` ausführen, um die Container zu rollen. Die CLI gleicht sich bei jedem Befehl ohnehin an die Instanz-Version an, also brauchst du das nur, um die Version bewusst zu wechseln.
 
-- `-v, --version <version>` — genau diese Version installieren (z. B. `0.9.0`) statt der neuesten; erlaubt Downgrades.
-- `-f, --force` — Neudownload erzwingen und lokal geänderte Dateien überschreiben.
+- `-v, --version <version>` — auf genau diese Version aktualisieren (z. B. `0.9.0`) statt der neuesten; erlaubt Downgrades.
+- `-f, --force` — Re-Sync erzwingen und lokal geänderte Projektdateien überschreiben.
 - `--dry-run` — anzeigen, was sich ändern würde, ohne etwas zu ändern.
 
 `tale cleanup` — inaktive (nicht-aktuelle) Container entfernen. Keine Argumente.
@@ -151,6 +153,12 @@ Befehle beenden mit `0` bei Erfolg, `2` bei einem Nutzungsfehler, `3` bei einer
 - `-a, --all` — auch die zustandsbehafteten Infrastruktur-Container entfernen.
 - `--dry-run` — den Reset vorab anzeigen, ohne Änderungen.
 
+`tale uninstall` — das `tale`-CLI-Binary von diesem System entfernen. Fragt nach, bevor etwas gelöscht wird, und _bietet an_, zusätzlich die benutzereigene Konfiguration (`~/.tale-daemon`) zu entfernen und die Docker-Ressourcen und Dateien eines Projekts abzubauen. Ohne `--purge` bleiben ein Projekt und seine Container unangetastet — führ darin `tale reset --all` aus, um sie zu entfernen.
+
+- `-f, --force` — die Bestätigungsabfrage überspringen (entfernt nur das Binary; die optionalen Aufräumschritte brauchen weiterhin `--purge`).
+- `--purge` — zusätzlich `~/.tale-daemon` entfernen und, für ein vom aktuellen Verzeichnis aus gefundenes Projekt, dessen Docker-Ressourcen abbauen und seine Dateien löschen. Nicht umkehrbar.
+- `--dry-run` — anzeigen, was entfernt würde, ohne etwas zu entfernen.
+
 `tale config` — CLI-Konfiguration verwalten. Mit dem Unterbefehl `show` die aufgelöste Konfiguration ausgeben.
 
 ### Erweitert
diff --git a/docs/de/self-hosted/operate/backups-and-restore.md b/docs/de/self-hosted/operate/backups-and-restore.md
index d695bb8134..aecdc1de92 100644
--- a/docs/de/self-hosted/operate/backups-and-restore.md
+++ b/docs/de/self-hosted/operate/backups-and-restore.md
@@ -58,8 +58,8 @@ tale restore
 tale restore 20260611-142530-deploy --stop
 
 # Den Stack auf der Version zurückbringen, die zu den Daten passt
-tale upgrade --version 0.9.6
-tale deploy --all
+tale update --version 0.9.6
+tale deploy --stop
 ```
 
 Das Redeploy der passenden Version ist Teil des Restores, kein optionales Extra: Der Snapshot hat die Daten exakt so erfasst, wie diese Plattform-Version sie hinterlassen hat, und ein neueres Binary würde sofort wieder seine Migrationen darauf laufen lassen. Die Restore-Ausgabe druckt die exakte Version aus dem Manifest des Snapshots.
diff --git a/docs/de/self-hosted/operate/release-notes/format.md b/docs/de/self-hosted/operate/release-notes/format.md
index 0dd1a38f35..b0b36605e9 100644
--- a/docs/de/self-hosted/operate/release-notes/format.md
+++ b/docs/de/self-hosted/operate/release-notes/format.md
@@ -5,7 +5,7 @@ description: Die Form, der Tales Release-Notes folgen — das semver-Versprechen
 
 Tale liefert ein Release pro Minor-Version und Patches als Bugfix-Tags dazwischen aus. Die Release-Notes für jeden Tag folgen derselben Form, damit du eine in einer Minute scannen kannst und weißt, ob das Upgrade ein Fünf-Minuten-Bump oder ein Wartungsfenster ist. Diese Seite deckt das Format ab: das semver-Versprechen, was jeder Abschnitt garantiert, und wo du tiefer liest, wenn eine Zeile auf eine Migration zeigt.
 
-Die Notes selbst leben auf der GitHub-Release-Seite zu jedem Tag. Das CLI bringt sie ebenfalls hoch — `tale upgrade --notes` druckt die Notes für die Version, die es gerade installieren will.
+Die Notes selbst leben auf der GitHub-Release-Seite zu jedem Tag. Das CLI bringt sie ebenfalls hoch — `tale update --notes` druckt die Notes für die Version, die es gerade installieren will.
 
 ## Das semver-Versprechen
 
@@ -30,7 +30,7 @@ Jede Release-Seite ist dieselbe geordnete Abschnitts-Liste. Leere Abschnitte wer
 
 ## Wie du ein Release scannst
 
-Lies die Versionszeile, die Highlights und den Breaking-Changes-Abschnitt. Ist Breaking Changes leer und nennt der Security-Abschnitt keinen Fix, der dein Install berührt, ist das Upgrade die Zwei-Kommando-Sequenz aus [Upgrades](/de/self-hosted/operate/upgrades). Hat einer der beiden Abschnitte Zeilen, gehst du sie durch, bevor du `tale deploy` läufst.
+Lies die Versionszeile, die Highlights und den Breaking-Changes-Abschnitt. Ist Breaking Changes leer und nennt der Security-Abschnitt keinen Fix, der dein Install berührt, ist das Upgrade die `tale update` + `tale deploy`-Sequenz aus [Upgrades](/de/self-hosted/operate/upgrades). Hat einer der beiden Abschnitte Zeilen, gehst du sie durch, bevor du `tale deploy` läufst.
 
 ```text
 0.12.0 (minor) — 14.05.2026
@@ -49,7 +49,7 @@ Security
   Siehe: Advisory TAL-2026-007.
 ```
 
-Die Form oben ist das, was `tale upgrade --notes` druckt. Die Web-Version desselben Releases fügt auf jeder Advisory- und Migrations-Zeile Links hinzu.
+Die Form oben ist das, was `tale update --notes` druckt. Die Web-Version desselben Releases fügt auf jeder Advisory- und Migrations-Zeile Links hinzu.
 
 ## Wo das hingehört
 
diff --git a/docs/de/self-hosted/operate/upgrades.md b/docs/de/self-hosted/operate/upgrades.md
index 0ec5c51a4a..ff31fbd459 100644
--- a/docs/de/self-hosted/operate/upgrades.md
+++ b/docs/de/self-hosted/operate/upgrades.md
@@ -1,41 +1,59 @@
 ---
 title: Upgrades
-description: Wie `tale upgrade` und `tale deploy` eine Tale-Instanz vorwärtsbewegen — das Rolling-Restart-Pattern, was vor einem Upgrade zu tun ist und die Versions-Kompatibilitäts-Story.
+description: Wie `tale update` eine Tale-Instanz vorwärtsbewegt — die automatische CLI-/Instanz-Versions-Angleichung, das Rolling-Restart-Pattern, was vor einem Upgrade zu tun ist und die Versions-Kompatibilitäts-Story.
 ---
 
-Upgrades auf einer self-hosted Tale-Instanz laufen durch das `tale`-CLI in zwei Schritten: `tale upgrade`, um das Binary selbst auf die neue Version zu bewegen, dann `tale deploy`, um die Plattform-Container passend zu rollen. Der Deploy nutzt ein Blue-Green-Pattern — die neue Farbe startet neben der alten, Healthchecks bestehen, der Traffic kippt, die alte Farbe drainet. Zero-Downtime ist der Default; macht ein Patch-Release Ärger, bringt `tale rollback` den vorherigen Patch in einem Kommando zurück, und alles Größere recovert aus dem Pre-Upgrade-Snapshot.
+Upgrades auf einer self-hosted Tale-Instanz laufen durch zwei Kommandos: `tale update` bewegt das CLI-Binary auf die neue Version und synct deine Projektdateien passend dazu, dann rollt `tale deploy` die Plattform-Container. Der Deploy nutzt ein Blue-Green-Pattern — die neue Farbe startet neben der alten, Healthchecks bestehen, der Traffic kippt, die alte Farbe drainet. Zero-Downtime ist der Default; macht ein Patch-Release Ärger, bringt `tale rollback` den vorherigen Patch in einem Kommando zurück, und alles Größere recovert aus dem Pre-Upgrade-Snapshot.
 
-Die CLI-Installation lebt in [Tale-CLI installieren](/de/self-hosted/install/cli-install). Diese Seite deckt ab, was jedes Subkommando tut und in welcher Reihenfolge sie zu laufen sind.
+Was du nicht mehr tust, ist das CLI von Hand im Gleichschritt zu halten: Das CLI gleicht sich automatisch an die Instanz an (siehe unten), sodass der einzige bewusste Schritt die Wahl ist, wann du mit `tale update` die Version wechselst.
+
+Die CLI-Installation lebt in [Tale-CLI installieren](/de/self-hosted/install/cli-install). Diese Seite deckt ab, was jedes Kommando tut und wie das Versions-Modell funktioniert.
+
+## Das CLI verfolgt die Instanz automatisch
+
+Das CLI-Binary hat immer dieselbe Version wie die Instanz, die es verwaltet. Der Workspace zeichnet diese Version in `tale.json` auf; bei jedem Kommando vergleicht das CLI seine eigene Version dagegen und aktualisiert sich selbst — auf- oder abwärts —, falls sie sich unterscheiden, bevor es läuft. Stimmen sie schon überein — der ganz überwiegend häufige Fall —, ist das ein No-op ohne Netzwerk-Aufruf, sodass du nie etwas davon merkst.
+
+Das heißt, du läufst `tale update` selten, außer wenn du bewusst auf eine neue Version willst. Ein Teamkollege, der ein neueres CLI als deine Instanz installiert hat, oder einen älteren Snapshot wiederhergestellt hat, bekommt beim nächsten Kommando automatisch die richtige CLI-Version. Es gibt kein Flag, das abzuschalten — Tool und Instanz im Gleichschritt zu halten ist das, was Deploys sicher macht.
 
 ## Bevor du upgradest
 
 Zwei Dinge sind es wert, zuerst zu bestätigen:
 
-- Deine Off-Host-Kopie des `backups`-Volumes ist aktuell — siehe [Backups und Restore](/de/self-hosted/operate/backups-and-restore). `tale deploy` snapshotet die Daten-Volumes automatisch vor jedem Schritt, der Daten migrieren kann, aber der Snapshot lebt auf demselben Host; die Off-Host-Kopie ist das, was eine tote Platte überlebt.
+- Deine Off-Host-Kopie des `backups`-Volumes ist aktuell — siehe [Backups und Restore](/de/self-hosted/operate/backups-and-restore). `tale update` snapshotet die Daten-Volumes automatisch vor jedem Schritt, der Daten migrieren kann, aber der Snapshot lebt auf demselben Host; die Off-Host-Kopie ist das, was eine tote Platte überlebt.
 - Die Release-Notes für die Zielversion nennen keinen breaking Change. Die Notes sind von der GitHub-Release-Seite verlinkt; breaking Changes sind oben als solche markiert.
 
 Überschreitet das Upgrade eine Major-Version (1.x → 2.x), lies die Migrations-Notes End-to-End, bevor du anfängst. Major-Versionen sind, wo Schema-Migrationen und Config-Datei-Format-Änderungen landen.
 
 ## Die zwei Kommandos
 
-`tale upgrade` aktualisiert das CLI-Binary selbst. Die deployte Plattform-Version stimmt mit der Version des CLI überein — diese Kopplung ist Absicht, damit das CLI, das du ausführst, nicht eine Version deployen kann, die es nicht kennt.
+`tale update` aktualisiert das CLI-Binary und synct dann deine Projektdateien auf die Templates dieser Version. Es fasst die laufenden Container **nicht** an — das ist der Job von `tale deploy`. Scheitert der Datei-Sync, rollt das CLI sein eigenes Binary auf die Version zurück, auf der dein Workspace war, sodass Binary und `tale.json` nie auseinanderdriften.
 
 ```bash
-# Bewege das CLI auf das letzte Release
-tale upgrade
+# Bewege das CLI und die Projektdateien auf das letzte Release
+tale update
 
-# Dann rolle die Plattform passend
-tale deploy
+# Eine bestimmte Version festnageln (erlaubt Downgrades — siehe Zurückrollen)
+tale update --version 0.10.2
+
+# Versions-Wechsel und Datei-Sync vorab ansehen, ohne etwas anzufassen
+tale update --dry-run
 ```
 
-`tale deploy` macht den eigentlichen Rolling-Restart: Es zieht neue Images, startet die neue Blue- oder Green-Farbe neben der laufenden, wartet auf Healthchecks, kippt den Proxy, drainet und entfernt die alte Farbe. Der Default zielt auf die rotierbaren Services (`platform`, `rag`, `crawler`); stateful Services (`db`, `proxy`) brauchen `--all`, um in-place aktualisiert zu werden.
+`tale deploy` macht den eigentlichen Rolling-Restart und deployt immer die eigene Version des CLI — die dank der Angleichung die Version ist, die dein Workspace aufzeichnet. Es sortiert die Services in drei Tiers:
+
+- **App-/Compute-Tier** — `platform`, `sandbox`, `sandbox-egress` — rollt bei **jedem** Deploy ohne Downtime (Blue-Green: die neue Farbe startet neben der alten, Healthchecks bestehen, der Traffic kippt, die alte Farbe drainet).
+- **Backend** — `convex` — rollt ebenfalls bei jedem Deploy, sodass es nie gegenüber `platform` versions-skewt; in-place neu erstellt wird es nur, wenn sich sein Image tatsächlich geändert hat.
+- **Stop-gegateter Tier** — `db`, `proxy` — bleibt standardmäßig **laufend und unangetastet** (Postgres oder den Proxy neu zu erstellen ist eine kurze Ausfallzeit, die du bei einem Routine-Roll nicht willst). Mit `--stop` aktualisierst du sie; der Deploy warnt und nennt sie, wenn er sie überspringt.
 
 ```bash
-# Schliess die stateful Services ein
-tale deploy --all
+# Nach tale update die Container passend rollen (App-Tier + convex)
+tale deploy
+
+# Auch db/proxy aktualisieren (kurze Downtime, während sie neu erstellt werden)
+tale deploy --stop
 
-# Rolle nur bestimmte Services
-tale deploy --services platform,rag
+# Nur bestimmte Services rollen
+tale deploy --services platform
 
 # Vorschau ohne Änderungen
 tale deploy --dry-run
@@ -45,7 +63,7 @@ tale deploy --dry-run
 
 ## Das Blue-Green-Pattern
 
-Eine laufende Instanz ist zu jeder Zeit eine der zwei Farben (Blue oder Green). `tale deploy` bringt die andere Farbe hoch, wartet, bis sie Healthchecks besteht, und kippt dann Caddys Upstream auf die neue Farbe. Die alte Farbe drainet ihre in-flight-Anfragen (Default 30 s), dann beendet sie sich.
+Eine laufende Instanz ist zu jeder Zeit eine der zwei Farben (Blue oder Green). Die Deploy-Phase bringt die andere Farbe hoch, wartet, bis sie Healthchecks besteht, und kippt dann Caddys Upstream auf die neue Farbe. Die alte Farbe drainet ihre in-flight-Anfragen (Default 30 s), dann beendet sie sich.
 
 Drei Garantien, die das Pattern dir gibt:
 
@@ -53,16 +71,21 @@ Drei Garantien, die das Pattern dir gibt:
 - **Patch-Rollback ist ein Kommando.** `tale rollback` deployt das vorherige Patch-Release auf der inaktiven Farbe neu und kippt den Traffic zurück. Minor- und Major-Downgrades verweigert es — die können die Datenbank vor dem Binary zurücklassen, und ihr Recovery-Pfad ist ein Snapshot-Restore.
 - **Gescheiterte Healthchecks blockieren den Kipp.** Besteht die neue Farbe nicht innerhalb des Timeouts, bricht der Deploy ab und die alte Farbe serviert weiter.
 
-Die vollständige Deploy-Prozedur inklusive der Cleanup-Phase lebt in `tale --help`; das operatorseitige Rezept ist `tale deploy && tale status` und visuelle Bestätigung im Browser.
+Die vollständige Deploy-Prozedur inklusive der Cleanup-Phase lebt in `tale --help`; das operatorseitige Rezept ist `tale update && tale deploy && tale status` und visuelle Bestätigung im Browser.
 
 ## Zurückrollen
 
 ```bash
-# Zurück zur vorherigen Patch-Version
+# Zurück zur vorherigen Patch-Version (fragt nach Bestätigung)
 tale rollback
+
+# Die Abfrage im nicht-interaktiven Betrieb überspringen
+tale rollback --yes
 ```
 
-`tale rollback` ist auf Patch-Schritte begrenzt: Es zielt nur auf die aufgezeichnete vorherige Version und verweigert, wenn diese Version nicht `major.minor` mit der laufenden Plattform teilt. Patch-Releases tragen nie Migrationen, also ist das Redeploy des vorherigen Patches immer sicher. Alles Größere kann Daten vorwärts migriert haben — ein älteres Binary auf migrierten Daten zu deployen korrumpiert die Instanz, statt sie zu retten. Für diese Fälle ist der Recovery-Pfad, den Pre-Upgrade-Snapshot wiederherzustellen und die passende Version neu zu deployen; die Verweigerungs-Meldung druckt die exakten Kommandos, und der volle Walk lebt in [Backups und Restore](/de/self-hosted/operate/backups-and-restore).
+`tale rollback` ist auf Patch-Schritte begrenzt: Es zielt nur auf die aufgezeichnete vorherige Version und verweigert, wenn diese Version nicht `major.minor` mit der laufenden Plattform teilt. Patch-Releases tragen nie Migrationen, also ist das Redeploy des vorherigen Patches immer sicher. Alles Größere kann Daten vorwärts migriert haben — ein älteres Binary auf migrierten Daten zu deployen korrumpiert die Instanz, statt sie zu retten. Für diese Fälle ist der Recovery-Pfad, den Pre-Upgrade-Snapshot wiederherzustellen und mit `tale update --version <version>` gefolgt von `tale deploy --stop` (sodass `db`/`proxy` ebenfalls zurückrollen) auf die passende Version zurückzugehen; die Verweigerungs-Meldung druckt die exakten Kommandos, und der volle Walk lebt in [Backups und Restore](/de/self-hosted/operate/backups-and-restore).
+
+Weil das Zurückrollen die laufenden Container abräumt, warnt das Kommando, was es vorhat, und fragt nach Bestätigung, bevor es auch nur ein Image zieht; mit `--yes` überspringst du diese Abfrage in Skripten oder CI.
 
 ## Versions-Kompatibilität
 
@@ -74,6 +97,8 @@ Tale-Versionen sind semver. Die Kompatibilitäts-Regeln:
 
 Minor-Versionen zu überspringen (von 0.9 auf 0.11 zu gehen) ist unterstützt, solange die Zwischen-Migrationen noch im Binary sind; die Release-Notes nennen es, wenn das nicht der Fall ist.
 
+Um bewusst eine Version _runter_ zu gehen — etwa wenn ein Minor-Release Ärger macht und du seine Migrationen schon zurückgenommen hast —, nagle das Ziel mit `tale update --version <version>` fest. Das Kommando warnt, wenn das Ziel älter als die laufende Version ist, und erinnert dich, zuerst die Daten-Migrationen zurückzunehmen.
+
 ## Wo das hingehört
 
 Der Upgrade-Flow knüpft jede andere Operate-Seite an — Backups sind das, was ein gescheitertes Upgrade wiederherstellbar macht, Observability ist das, was dir sagt, dass die neue Farbe healthy ist, Hardening ist das, was du nach einer Major-Version neu durchgehst. Setzt du das CLI zum ersten Mal auf, deckt [Tale-CLI installieren](/de/self-hosted/install/cli-install) das workstationseitige Setup ab; nimmst du den Pager mitten im Rollout auf, nennt [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting) die Symptome.
diff --git a/docs/en/cloud/onboarding.md b/docs/en/cloud/onboarding.md
index 03d71b45d9..0088fde910 100644
--- a/docs/en/cloud/onboarding.md
+++ b/docs/en/cloud/onboarding.md
@@ -41,7 +41,7 @@ For a deeper walk on what makes an agent good, see [Create an agent](/platform/a
 
 ## Step 5 — Open chat
 
-Open **Chat** in the sidebar and click **New chat**. Pick the agent from the picker, type a question the agent's domain covers, send. The reply streams back; if it lands the way you wrote the instructions to land, the org is done with onboarding.
+Click **New chat** in the sidebar. Pick the agent from the picker, type a question the agent's domain covers, send. The reply streams back; if it lands the way you wrote the instructions to land, the org is done with onboarding.
 
 Three follow-ups worth doing now while everything is fresh:
 
diff --git a/docs/en/develop/ai-assisted-development.md b/docs/en/develop/ai-assisted-development.md
index 956b9d0a7c..00ffdbe3f2 100644
--- a/docs/en/develop/ai-assisted-development.md
+++ b/docs/en/develop/ai-assisted-development.md
@@ -34,7 +34,7 @@ The directive matters because every editor under load skips schema reads unless
 | `integrations/<slug>/config.json`  | Integration manifest — operations, auth method, allowed hosts.          |
 | `integrations/<slug>/connector.ts` | Optional TypeScript connector for REST shapes the manifest can't cover. |
 | `branding/branding.json`           | Org branding — colours, logos, email senders.                           |
-| `.tale/reference/`                 | Read-only schema mirror; regenerated by `tale init` and `tale upgrade`. |
+| `.tale/reference/`                 | Read-only schema mirror; regenerated by `tale init` and `tale update`.  |
 
 The reference tree is bytes-identical to the schemas the platform validates against at deploy time. Treat it as canonical: when a field name in a hand-written config disagrees with the reference, the reference wins.
 
@@ -46,7 +46,7 @@ The rules file names three rules each editor enforces while editing:
 - **Workflows use integration operations.** A workflow step references integration operations declared in `integrations/<slug>/config.json`. Editing a step against an operation that does not exist will fail validation.
 - **Naming is enforced.** Agent filenames match `[a-z0-9][a-z0-9_-]*\.json`. Workflow step slugs match `[a-z0-9][a-z0-9_-]*`. Integration directories are lowercase alphanumeric with hyphens or underscores.
 
-When the editor proposes a change, ask it to cite the file in `.tale/reference/` it relied on. If it cannot, regenerate the mirror with `tale upgrade` and try again.
+When the editor proposes a change, ask it to cite the file in `.tale/reference/` it relied on. If it cannot, regenerate the mirror with `tale update` and try again.
 
 ## Where this fits
 
diff --git a/docs/en/platform/agents/external-agent.md b/docs/en/platform/agents/external-agent.md
index a03c471a5a..df9aaabb11 100644
--- a/docs/en/platform/agents/external-agent.md
+++ b/docs/en/platform/agents/external-agent.md
@@ -29,7 +29,7 @@ How the agent reaches its model is a per-agent choice, set on the agent's **Inst
 
 **Managed (platform gateway)** is the default and what every section above describes. The platform mints a short-lived virtual key for the turn, routes the agent through its gateway, enforces the agent's allowed models, meters usage, and applies the org's spend caps. The sandbox never holds a real provider key.
 
-**Bring your own credentials (BYO)** takes the platform out of the request path. No virtual key is minted; the agent authenticates with credentials you store under [Environment & secrets](/platform/member/environment) and reaches the provider directly. The model becomes a raw provider id you type verbatim rather than a catalogue entry, and the agent's native web search and fetch are left enabled rather than disabled. Because the gateway is bypassed, the org's model allowlist, spend caps, and usage metering do not apply to BYO turns — billing and limits move to your own provider account. Switching an agent from managed to BYO clears its saved platform models, since catalogue references mean nothing to a raw passthrough; you re-enter the raw ids.
+**Bring your own credentials (BYO)** takes the platform out of the request path. No virtual key is minted; the agent authenticates with credentials you store under [Environment variables & secrets](/platform/member/environment) and reaches the provider directly. The model becomes a raw provider id you type verbatim rather than a catalogue entry, and the agent's native web search and fetch are left enabled rather than disabled. Because the gateway is bypassed, the org's model allowlist, spend caps, and usage metering do not apply to BYO turns — billing and limits move to your own provider account. Switching an agent from managed to BYO clears its saved platform models, since catalogue references mean nothing to a raw passthrough; you re-enter the raw ids.
 
 That is also a shift in the trust boundary. In managed mode the sandbox holds only a budget-scoped gateway key; in BYO mode your real provider credential is injected into the sandbox environment — the same posture as the in-sandbox GitHub token — so any code the agent runs in the box can read it. That is by design: it is your box and your credential. Configuring an agent is already a privileged action, so the per-agent toggle is the only control; there is no separate org-level switch.
 
@@ -47,4 +47,4 @@ This accounting is a property of the gateway, so it covers managed turns only. A
 
 ## Where this fits
 
-An external agent turns a chat thread into a live session with a coding tool in a sandbox — you drive it in plain language, it works in an isolated workspace, and the session persists for follow-ups until you close the thread. Credentials are the axis that decides how much of that runs under the org's control: a managed agent stays on the platform gateway under the org's caps and metering, while a bring-your-own agent runs on the keys you keep under [Environment & secrets](/platform/member/environment) and answers to your own provider account. The drift candidates here are the agent and model names; pair this page with the running [Providers](/platform/admin/providers) list rather than memorising specific model strings, and with [Integrations](/platform/integrations/overview) for the connected integrations the agent can reach — from GitHub for a real pull-request workflow to a search or data integration that pulls outside facts into the work.
+An external agent turns a chat thread into a live session with a coding tool in a sandbox — you drive it in plain language, it works in an isolated workspace, and the session persists for follow-ups until you close the thread. Credentials are the axis that decides how much of that runs under the org's control: a managed agent stays on the platform gateway under the org's caps and metering, while a bring-your-own agent runs on the keys you keep under [Environment variables & secrets](/platform/member/environment) and answers to your own provider account. The drift candidates here are the agent and model names; pair this page with the running [Providers](/platform/admin/providers) list rather than memorising specific model strings, and with [Integrations](/platform/integrations/overview) for the connected integrations the agent can reach — from GitHub for a real pull-request workflow to a search or data integration that pulls outside facts into the work.
diff --git a/docs/en/platform/member/environment.md b/docs/en/platform/member/environment.md
index b3fa1df81b..2a28b413f8 100644
--- a/docs/en/platform/member/environment.md
+++ b/docs/en/platform/member/environment.md
@@ -1,15 +1,15 @@
 ---
-title: Environment & secrets
+title: Environment variables & secrets
 description: Your personal environment variables and secrets, injected into every agent sandbox you run in an organisation — most often the provider credential a bring-your-own agent authenticates with.
 ---
 
-Environment & secrets is your personal store of variables that Tale injects into every agent sandbox you run in this organisation. When an external agent starts its sandbox, each entry you have saved here is set in the container's environment before the agent runs, so a command the agent issues — or the agent itself — can read it. The headline use is credentials: a [bring-your-own external agent](/platform/agents/external-agent) authenticates with the API key or token you keep here instead of the platform gateway. It is a member-level page that every role can reach, and the entries are scoped to you and to the current organisation, so they never leak to teammates and never follow you into another org.
+Environment variables & secrets is your personal store of variables that Tale injects into every agent sandbox you run in this organisation. When an external agent starts its sandbox, each entry you have saved here is set in the container's environment before the agent runs, so a command the agent issues — or the agent itself — can read it. The headline use is credentials: a [bring-your-own external agent](/platform/agents/external-agent) authenticates with the API key or token you keep here instead of the platform gateway. It is a member-level page that every role can reach, and the entries are scoped to you and to the current organisation, so they never leak to teammates and never follow you into another org.
 
 This page covers the two kinds of entry, how secrets are protected, the rules a name and value have to satisfy, and where the values end up.
 
 ## Variables and secrets
 
-Open **Settings > Environment**. The page is an add form at the top and the list of what you have saved below. Each entry is a **Name** and a **Value**, plus a **Secret** switch that decides how the value is stored and shown.
+Open **Settings > Environment**. **Add variable** opens a dialog for a new entry, with the list of what you have saved below. Each entry is a **Name** and a **Value**, plus a **Secret** switch that decides how the value is stored and shown.
 
 A plain variable is stored as-is and shown back in full in the list — use it for non-sensitive configuration the agent expects, a region name or an endpoint. A **secret** is encrypted the moment you save it and is write-only from then on: the list shows `••••••••` in place of the value, and there is no way to read it back. Turn the switch on for anything sensitive — an API key, an OAuth token, a password. The trade-off is that you cannot review a secret's value later, so if you are unsure it is right, delete it and add it again rather than hunting for a reveal button that does not exist.
 
@@ -29,4 +29,4 @@ That last step is the boundary worth understanding: the values land inside your
 
 ## Where this fits
 
-Environment & secrets is the one member-level page that reaches into the sandbox rather than the chat — it is how your own keys and configuration get to the agents you run, without an Editor or Admin setting them for you. The entry you will add most often is the provider credential for a [bring-your-own external agent](/platform/agents/external-agent); read this page alongside that one to see both halves — where the credential is stored and how an agent is told to use it instead of the platform gateway. For the rest of your personal settings — display name, password, custom instructions — see [Preferences](/platform/member/preferences).
+Environment variables & secrets is the one member-level page that reaches into the sandbox rather than the chat — it is how your own keys and configuration get to the agents you run, without an Editor or Admin setting them for you. The entry you will add most often is the provider credential for a [bring-your-own external agent](/platform/agents/external-agent); read this page alongside that one to see both halves — where the credential is stored and how an agent is told to use it instead of the platform gateway. For the rest of your personal settings — display name, password, custom instructions — see [Preferences](/platform/member/preferences).
diff --git a/docs/en/platform/member/overview.md b/docs/en/platform/member/overview.md
index 104372fb47..19392fa91b 100644
--- a/docs/en/platform/member/overview.md
+++ b/docs/en/platform/member/overview.md
@@ -16,7 +16,7 @@ The Member surface is intentionally narrow. The four buckets are:
 - **Conversations** — read the inbox threads assigned to you. Members reply when an agent hands a conversation back; they cannot reassign or close threads other people own.
 - **Approvals** — read the approval cards routed to you. Click Approve, Reject, or Request changes; leave a comment if the rule asks for one.
 
-The org configuration settings — providers, integrations, agents, governance — are hidden for Members; the work surface is the bulk of what is left. The exception is a small personal settings group every role carries: Account, Personalization, and [Environment & secrets](/platform/member/environment), the keys and variables injected into the sandboxes you run.
+The org configuration settings — providers, integrations, agents, governance — are hidden for Members; the work surface is the bulk of what is left. The exception is a small personal settings group every role carries: Account, Personalization, and [Environment variables & secrets](/platform/member/environment), the keys and variables injected into the sandboxes you run.
 
 ## Pages in this section
 
diff --git a/docs/en/platform/member/preferences.md b/docs/en/platform/member/preferences.md
index 5e79275b20..1362a9c417 100644
--- a/docs/en/platform/member/preferences.md
+++ b/docs/en/platform/member/preferences.md
@@ -37,4 +37,4 @@ The **Log out** row at the bottom of the profile menu confirms with a dialog bef
 
 ## Where this fits
 
-Preferences are the line between you and the rest of the org. The org Admin sets defaults — including whether personalization is on for new members, what the password policy is, which models are allowed — and your preferences override the defaults where Tale lets them. One personal page sits apart from this set: [Environment & secrets](/platform/member/environment) holds variables and credentials scoped to you within a single organisation rather than following you across them — the place to keep the provider key a bring-your-own agent uses. The next read worth queuing is [Member overview](/platform/member/overview) for the map of the rest of the Member surface, or [Install as app](/platform/member/install-as-app) if you want Tale to live in your dock rather than your browser tabs.
+Preferences are the line between you and the rest of the org. The org Admin sets defaults — including whether personalization is on for new members, what the password policy is, which models are allowed — and your preferences override the defaults where Tale lets them. One personal page sits apart from this set: [Environment variables & secrets](/platform/member/environment) holds variables and credentials scoped to you within a single organisation rather than following you across them — the place to keep the provider key a bring-your-own agent uses. The next read worth queuing is [Member overview](/platform/member/overview) for the map of the rest of the Member surface, or [Install as app](/platform/member/install-as-app) if you want Tale to live in your dock rather than your browser tabs.
diff --git a/docs/en/platform/models.md b/docs/en/platform/models.md
index 829f800bd7..e3fc03ccd8 100644
--- a/docs/en/platform/models.md
+++ b/docs/en/platform/models.md
@@ -17,21 +17,65 @@ OpenRouter is an OpenAI-compatible endpoint Tale calls over HTTPS with a bearer
 
 ## OpenRouter — chat, vision, embeddings
 
-OpenRouter is a multi-model gateway. The shipped config picks `deepseek-v4-flash` as the default chat model, `qwen3-vl-32b-instruct` for vision, and `qwen3-embedding-8b` for embeddings — all picked for the speed-to-quality ratio at the moment of writing. The full ship list:
-
-- **Anthropic** — Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5.
-- **OpenAI** — GPT-5.2 Pro, GPT-5.2, GPT-5.2 Instant, GPT-OSS 120B (the open-weight release).
-- **Google** — Gemini 3 Pro, Gemini 3 Flash, Gemma 4 31B IT, Gemma 4 26B A4B IT, Nano Banana (Gemini 2.5 Flash Image).
-- **DeepSeek** — DeepSeek V4 Pro, DeepSeek V4 Flash.
-- **Moonshot AI** — Kimi K2.6, Kimi K2.5.
-- **MiniMax** — MiniMax M2.7.
-- **NVIDIA** — Nemotron 3 Super 120B.
-- **Qwen** — Qwen3.6 Max Preview, Qwen3.6 Plus, Qwen3.6 Flash, Qwen3.6 35B A3B, Qwen3.5 397B A17B, Qwen3 Coder 480B, Qwen3 235B A22B, Qwen3 VL 32B, Qwen3 Embedding 8B.
-- **Z.AI** — GLM 5.1, GLM 5 Turbo, GLM 5V Turbo.
-- **Mistral** — Mistral Large 3, Mistral Medium 3.
-- **Xiaomi** — MiMo V2.5 Pro.
-- **Meta** — LLaMA 4 Maverick, LLaMA 4 Scout.
-- **Black Forest Labs** — FLUX.2 [max], FLUX.2 [pro], FLUX.2 [flex].
+OpenRouter is a multi-model gateway. The shipped config picks `deepseek-v4-flash` as the default chat model, `qwen3-vl-32b-instruct` for vision, and `qwen3-embedding-8b` for embeddings — all picked for the speed-to-quality ratio at the moment of writing. The full ship list below is every visible model in the shipped `openrouter.json`, regenerated by the weekly catalog job so it never drifts from the config:
+
+<!-- MODELS_TABLE:START -->
+
+<!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. -->
+
+| Provider          | Model                                | Capabilities                 | Context | Input ($/M) | Output ($/M) |
+| ----------------- | ------------------------------------ | ---------------------------- | ------- | ----------- | ------------ |
+| AI21              | Jamba Large 1.7                      | chat                         | 256K    | 2.00        | 8.00         |
+| Amazon            | Nova Premier                         | chat, vision                 | 1M      | 2.50        | 12.50        |
+| Amazon            | Nova 2 Lite                          | chat, vision                 | 1M      | 0.30        | 2.50         |
+| Anthropic         | Claude Sonnet 4.6                    | chat, vision                 | 1M      | 3.00        | 15.00        |
+| Anthropic         | Claude Haiku 4.5                     | chat                         | 200K    | 1.00        | 5.00         |
+| Anthropic         | Claude Opus 4.8                      | chat, vision                 | 1M      | 5.00        | 25.00        |
+| Black Forest Labs | FLUX.2 [flex]                        | image-generation, image-edit | —       | —           | —            |
+| Black Forest Labs | FLUX.2 [max]                         | image-generation, image-edit | —       | —           | —            |
+| Black Forest Labs | FLUX.2 [pro]                         | image-generation, image-edit | —       | —           | —            |
+| Cohere            | Command A                            | chat                         | 256K    | 2.50        | 10.00        |
+| Cohere            | Command R                            | chat                         | 128K    | 0.15        | 0.60         |
+| DeepSeek          | DeepSeek V4 Pro                      | chat                         | 1M      | 0.43        | 0.87         |
+| DeepSeek          | DeepSeek V4 Flash                    | chat                         | 1M      | 0.09        | 0.18         |
+| Google            | Gemini 3 Pro                         | chat, vision                 | 1M      | 2.00        | 12.00        |
+| Google            | Gemini 3 Flash                       | chat, vision                 | 1M      | 0.50        | 3.00         |
+| Google            | Gemma 4 31B IT                       | chat, vision                 | 262K    | 0.12        | 0.35         |
+| Google            | Gemma 4 26B A4B IT                   | chat, vision                 | 262K    | 0.06        | 0.33         |
+| Google            | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K     | 0.30        | 2.50         |
+| Liquid            | LFM2 24B                             | chat                         | 128K    | 0.03        | 0.12         |
+| Meta              | LLaMA 4 Maverick                     | chat                         | 1M      | 0.15        | 0.60         |
+| Meta              | LLaMA 4 Scout                        | chat                         | 10M     | 0.10        | 0.30         |
+| Microsoft         | Phi-4                                | chat                         | 16K     | 0.07        | 0.14         |
+| MiniMax           | MiniMax M3                           | chat, vision                 | 1M      | 0.30        | 1.20         |
+| Mistral           | Mistral Large 3                      | chat                         | 262K    | 0.50        | 1.50         |
+| Mistral           | Mistral Medium 3.5                   | chat, vision                 | 262K    | 1.50        | 7.50         |
+| Moonshot AI       | Kimi K2.6                            | chat, vision                 | 262K    | 0.68        | 3.41         |
+| Moonshot AI       | Kimi K2.7 Code                       | chat, vision                 | 262K    | 0.61        | 3.07         |
+| NVIDIA            | Nemotron 3 Ultra                     | chat                         | 1M      | 0.50        | 2.20         |
+| NVIDIA            | Nemotron 3 Super                     | chat                         | 1M      | 0.09        | 0.45         |
+| OpenAI            | GPT-OSS 120B                         | chat                         | 131K    | 0.04        | 0.18         |
+| OpenAI            | GPT-4o mini TTS                      | text-to-speech               | —       | —           | —            |
+| OpenAI            | GPT-5.3 Chat                         | chat, vision                 | 128K    | 1.75        | 14.00        |
+| OpenAI            | GPT-5.5                              | chat, vision                 | 1M      | 5.00        | 30.00        |
+| OpenAI            | GPT-5.5 Pro                          | chat, vision                 | 1M      | 30.00       | 180.00       |
+| OpenAI            | Whisper v1                           | transcription                | —       | —           | —            |
+| Perplexity        | Sonar Pro                            | chat, vision                 | 200K    | 3.00        | 15.00        |
+| Perplexity        | Sonar                                | chat, vision                 | 127K    | 1.00        | 1.00         |
+| Qwen              | Qwen3.6 Max Preview                  | chat                         | 262K    | 1.04        | 6.24         |
+| Qwen              | Qwen3 Coder 480B                     | chat                         | 1M      | 0.22        | 1.80         |
+| Qwen              | Qwen3 VL 32B                         | chat, vision                 | 262K    | 0.10        | 0.42         |
+| Qwen              | Qwen3.6 Flash                        | chat, vision                 | 1M      | 0.19        | 1.13         |
+| Qwen              | Qwen3 Embedding 8B                   | embedding                    | —       | 0.01        | 0.00         |
+| Qwen              | Qwen3.7 Plus                         | chat, vision                 | 1M      | 0.32        | 1.28         |
+| Reka              | Reka Flash 3                         | chat                         | 66K     | 0.10        | 0.20         |
+| Xiaomi            | MiMo V2.5 Pro                        | chat                         | 1M      | 0.43        | 0.87         |
+| Z.AI              | GLM 5.1                              | chat                         | 203K    | 0.98        | 3.08         |
+| Z.AI              | GLM 5 Turbo                          | chat                         | 262K    | 1.20        | 4.00         |
+| Z.AI              | GLM 5V Turbo                         | chat, vision                 | 131K    | 1.20        | 4.00         |
+| xAI               | Grok 4.20                            | chat, vision                 | 2M      | 1.25        | 2.50         |
+
+<!-- MODELS_TABLE:END -->
 
 The full and live catalogue lives at [openrouter.ai/models](https://openrouter.ai/models). Any model OpenRouter exposes can be added to your instance by editing the `models` array in `<orgSlug>/providers/openrouter.json` under `TALE_CONFIG_DIR` (per-org under the org-first layout).
 
diff --git a/docs/en/self-hosted/configuration/providers.md b/docs/en/self-hosted/configuration/providers.md
index a7c7ad4ba6..528222c80d 100644
--- a/docs/en/self-hosted/configuration/providers.md
+++ b/docs/en/self-hosted/configuration/providers.md
@@ -33,7 +33,7 @@ The reference is the file format on disk and the order operations follow when ad
 }
 ```
 
-The full set of fields lives in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). The shipped default is a single `openrouter.json` that covers chat, vision, embeddings, transcription, text-to-speech, and image generation — one key for everything. To call a vendor directly instead of through OpenRouter, add another file (for example an `openai.json` pointed at `https://api.openai.com/v1`); see [Models out of the box](/platform/models) for the full default catalogue.
+The full set of fields lives in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). The shipped default is a single `openrouter.json` that covers chat, vision, embeddings, transcription, text-to-speech, and image generation — one key for everything — with curated presets across the common providers (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity, and more). To call a vendor directly instead of through OpenRouter, add another file (for example an `openai.json` pointed at `https://api.openai.com/v1`); see [Models out of the box](/platform/models) for the full default catalogue.
 
 `transcriptionMode` selects how a `transcription` model's request body is shaped: `json-base64` (OpenRouter's `input_audio` envelope) or, when omitted, `multipart` — the OpenAI/Whisper `multipart/form-data` upload that vLLM, LocalAI, and a direct OpenAI key also expect. Set it to match whichever transcription endpoint you point at.
 
diff --git a/docs/en/self-hosted/configuration/retention.md b/docs/en/self-hosted/configuration/retention.md
index 0e36299cce..9959472750 100644
--- a/docs/en/self-hosted/configuration/retention.md
+++ b/docs/en/self-hosted/configuration/retention.md
@@ -37,6 +37,8 @@ Under the org-first layout, retention bounds are **per-org**: edit `retention.js
 
 The platform container watches the file; changes propose a bounds update for every existing org. Admins see the proposal in their **Retention policy** screen and apply it themselves. The propose-then-apply step is deliberate: tightening a floor shortens history, which is a destructive action no operator should land silently on every tenant.
 
+The admin-chosen retention windows live in a separate file, `retention-policy.json`, alongside the bounds in the same `governance/` folder. It holds flat `<category>Enabled` / `<category>RetentionDays` fields (e.g. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), not the `min`/`max` bounds. That file is written by **Settings > Governance > Retention policy** in the app, so admins normally never edit it by hand — keep it distinct from the operator-owned bounds file.
+
 ## The retention sweep
 
 A scheduled cron inside `tale-convex` runs the actual deletion. Each category is swept independently — a slow run on one does not block the others. Deletions are audited (every category has its own `*.retention_deleted` event), and restoring an entity inside its grace window is possible from **Trash** before the final sweep.
diff --git a/docs/en/self-hosted/install/cli-install.md b/docs/en/self-hosted/install/cli-install.md
index 837212b763..3c51ef946a 100644
--- a/docs/en/self-hosted/install/cli-install.md
+++ b/docs/en/self-hosted/install/cli-install.md
@@ -133,14 +133,16 @@ Commands exit `0` on success, `2` on a usage error, `3` on an unmet precondition
 - `--stop` — stop running project containers before restoring.
 - `-y, --yes` — skip the confirmation prompt.
 
-`tale rollback` — roll back to the previous patch version (patch-level only). No arguments.
+`tale rollback` — roll back to the previous patch version (patch-level only). Prompts for confirmation before it touches anything.
+
+- `-y, --yes` — skip the confirmation prompt (required when running non-interactively).
 
 ### Maintain
 
-`tale upgrade` (alias `tale update`) — upgrade the CLI to the latest release and sync project files.
+`tale update` — move this Tale instance to a new version: update the CLI binary, then sync project files to that version's templates. Run `tale deploy` afterwards to roll the containers. The CLI also self-aligns to the instance version on every command, so this is only needed to deliberately change versions.
 
-- `-v, --version <version>` — install this exact version (e.g. `0.9.0`) instead of the latest; allows downgrades.
-- `-f, --force` — force re-download and overwrite locally modified files.
+- `-v, --version <version>` — update to this exact version (e.g. `0.9.0`) instead of the latest; allows downgrades.
+- `-f, --force` — force re-sync and overwrite locally modified project files.
 - `--dry-run` — show what would change without modifying anything.
 
 `tale cleanup` — remove inactive (non-current colour) containers. No arguments.
@@ -151,6 +153,12 @@ Commands exit `0` on success, `2` on a usage error, `3` on an unmet precondition
 - `-a, --all` — also remove the stateful infrastructure containers.
 - `--dry-run` — preview the reset without making changes.
 
+`tale uninstall` — remove the `tale` CLI binary from this system. It prompts before deleting anything and _offers_ to also remove the per-user config (`~/.tale-daemon`) and tear down a project's Docker resources and files. Without `--purge`, a project and its containers are left intact — run `tale reset --all` inside one to remove those.
+
+- `-f, --force` — skip the confirmation prompt (removes the binary only; the optional cleanups still need `--purge`).
+- `--purge` — also remove `~/.tale-daemon` and, for a project found from the current directory, tear down its Docker resources and delete its files. Irreversible.
+- `--dry-run` — show what would be removed without removing anything.
+
 `tale config` — manage CLI configuration. Use the `show` subcommand to print the resolved config.
 
 ### Advanced
diff --git a/docs/en/self-hosted/operate/backups-and-restore.md b/docs/en/self-hosted/operate/backups-and-restore.md
index 3f56af486c..59af5e724c 100644
--- a/docs/en/self-hosted/operate/backups-and-restore.md
+++ b/docs/en/self-hosted/operate/backups-and-restore.md
@@ -58,8 +58,8 @@ tale restore
 tale restore 20260611-142530-deploy --stop
 
 # Bring the stack back on the version that matches the data
-tale upgrade --version 0.9.6
-tale deploy --all
+tale update --version 0.9.6
+tale deploy --stop
 ```
 
 The redeploy of the matching version is part of the restore, not an optional extra: the snapshot captured the data exactly as that platform version left it, and a newer binary would immediately re-run its migrations against it. The restore output prints the exact version recorded in the snapshot's manifest.
diff --git a/docs/en/self-hosted/operate/release-notes/format.md b/docs/en/self-hosted/operate/release-notes/format.md
index e024125fea..05543e8c17 100644
--- a/docs/en/self-hosted/operate/release-notes/format.md
+++ b/docs/en/self-hosted/operate/release-notes/format.md
@@ -5,7 +5,7 @@ description: The shape Tale's release notes follow — the semver promise, where
 
 Tale ships a release per minor version and patches as bug-fix tags between them. The release notes for every tag follow the same shape so you can scan one in a minute and know whether the upgrade is a five-minute bump or a maintenance window. This page covers the format: the semver promise, what each section guarantees, and where to read deeper when a row points at a migration.
 
-The notes themselves live on the GitHub release page for each tag. The CLI also surfaces them — `tale upgrade --notes` prints the notes for the version it is about to install.
+The notes themselves live on the GitHub release page for each tag. The CLI also surfaces them — `tale update --notes` prints the notes for the version it is about to install.
 
 ## The semver promise
 
@@ -30,7 +30,7 @@ Each release page is the same ordered list of sections. Empty sections are omitt
 
 ## How to scan a release
 
-Read the version line, the highlights, and the breaking-changes section. If breaking changes is empty and the security section does not name a fix that touches your install, the upgrade is the two-command sequence from [Upgrades](/self-hosted/operate/upgrades). If either section has rows, walk them before running `tale deploy`.
+Read the version line, the highlights, and the breaking-changes section. If breaking changes is empty and the security section does not name a fix that touches your install, the upgrade is the `tale update` + `tale deploy` sequence from [Upgrades](/self-hosted/operate/upgrades). If either section has rows, walk them before running `tale deploy`.
 
 ```text
 0.12.0 (minor) — 2026-05-14
@@ -49,7 +49,7 @@ Security
   See: advisory TAL-2026-007.
 ```
 
-The shape above is what `tale upgrade --notes` prints. The web version of the same release adds links on every advisory and migration row.
+The shape above is what `tale update --notes` prints. The web version of the same release adds links on every advisory and migration row.
 
 ## Where this fits
 
diff --git a/docs/en/self-hosted/operate/upgrades.md b/docs/en/self-hosted/operate/upgrades.md
index 59eed76320..a342255fff 100644
--- a/docs/en/self-hosted/operate/upgrades.md
+++ b/docs/en/self-hosted/operate/upgrades.md
@@ -1,41 +1,59 @@
 ---
 title: Upgrades
-description: How `tale upgrade` and `tale deploy` move a Tale instance forward — the rolling restart pattern, what to do before an upgrade, and the version compatibility story.
+description: How `tale update` moves a Tale instance forward — automatic CLI/instance version alignment, the rolling restart pattern, what to do before an upgrade, and the version compatibility story.
 ---
 
-Upgrades on a self-hosted Tale instance run through the `tale` CLI in two steps: `tale upgrade` to move the binary itself to the new version, then `tale deploy` to roll the platform containers to match. The deploy uses a blue-green pattern — the new colour starts alongside the old, healthchecks pass, traffic flips, the old colour drains. Zero downtime is the default; if a patch release misbehaves, `tale rollback` returns to the previous patch in one command, and anything bigger recovers from the pre-upgrade snapshot.
+Upgrades on a self-hosted Tale instance run through two commands: `tale update` moves the CLI binary to the new version and syncs your project files to match, then `tale deploy` rolls the platform containers. The deploy uses a blue-green pattern — the new colour starts alongside the old, healthchecks pass, traffic flips, the old colour drains. Zero downtime is the default; if a patch release misbehaves, `tale rollback` returns to the previous patch in one command, and anything bigger recovers from the pre-upgrade snapshot.
 
-The CLI install lives in [Install the tale CLI](/self-hosted/install/cli-install). This page covers what each subcommand does and the order to run them in.
+What you no longer do is keep the CLI in sync by hand: the CLI aligns itself to the instance automatically (see below), so the only deliberate step is choosing when to move versions with `tale update`.
+
+The CLI install lives in [Install the tale CLI](/self-hosted/install/cli-install). This page covers what each command does and how the version model works.
+
+## The CLI tracks the instance automatically
+
+The CLI binary is always the same version as the instance it manages. The workspace records that version in `tale.json`; on every command the CLI compares its own version against it and, if they differ, self-updates the binary to match (up or down) before running. When they already match — the overwhelmingly common case — this is a no-op with no network call, so you never notice it.
+
+That means you rarely run `tale update` except when you deliberately want to move to a new version. A teammate who installed a newer CLI than your instance, or restored an older snapshot, gets the right CLI version automatically on their next command. There is no flag to turn this off — keeping the tool and the instance in lockstep is what makes deploys safe.
 
 ## Before you upgrade
 
 Two things are worth confirming first:
 
-- Your off-host copy of the `backups` volume is current — see [Backups and restore](/self-hosted/operate/backups-and-restore). `tale deploy` snapshots the data volumes automatically before any step that can migrate data, but the snapshot lives on the same host; the off-host copy is what survives a dead disk.
+- Your off-host copy of the `backups` volume is current — see [Backups and restore](/self-hosted/operate/backups-and-restore). `tale update` snapshots the data volumes automatically before any step that can migrate data, but the snapshot lives on the same host; the off-host copy is what survives a dead disk.
 - The release notes for the target version do not name a breaking change. The notes are linked from the GitHub release page; breaking changes are flagged as such at the top.
 
 If the upgrade crosses a major version (1.x → 2.x), read the migration notes end-to-end before starting. Major versions are where schema migrations and config-file format changes land.
 
 ## The two commands
 
-`tale upgrade` updates the CLI binary itself. The deployed platform version matches the CLI's version — that coupling is intentional, so the CLI you run cannot deploy a version it does not know about.
+`tale update` updates the CLI binary and then syncs your project files to that version's templates. It does **not** touch the running containers — that is `tale deploy`'s job. If the file sync fails, the CLI rolls its own binary back to the version your workspace was on, so the binary and `tale.json` never drift apart.
 
 ```bash
-# Move the CLI to the latest release
-tale upgrade
+# Move the CLI + project files to the latest release
+tale update
 
-# Then roll the platform to match
-tale deploy
+# Pin a specific version (allows downgrades — see Rolling back)
+tale update --version 0.10.2
+
+# Preview the version change and file sync without touching anything
+tale update --dry-run
 ```
 
-`tale deploy` does the actual rolling restart: it pulls new images, starts the new blue or green colour alongside the running one, waits for healthchecks, flips the proxy, drains and removes the old colour. The default targets the rotatable services (`platform`, `rag`, `crawler`); stateful services (`db`, `proxy`) need `--all` to update in place.
+`tale deploy` does the actual rolling restart, and it always deploys the CLI's own version — which, thanks to alignment, is the version your workspace records. It sorts the services into three tiers:
+
+- **App/compute tier** — `platform`, `sandbox`, `sandbox-egress` — rolls on **every** deploy with zero downtime (blue-green: the new colour starts alongside the old, healthchecks pass, traffic flips, the old colour drains).
+- **Backend** — `convex` — rolls on every deploy too, so it never version-skews from `platform`; it recreates in place only when its image actually changed.
+- **Stop-gated tier** — `db`, `proxy` — left **running and untouched** by default (recreating Postgres or the proxy is a brief outage you don't want on a routine roll). Pass `--stop` to update them; the deploy warns and names them when it skips.
 
 ```bash
-# Include the stateful services
-tale deploy --all
+# After tale update, roll the containers to match (app tier + convex)
+tale deploy
+
+# Also update db/proxy (brief downtime while they recreate)
+tale deploy --stop
 
 # Roll only specific services
-tale deploy --services platform,rag
+tale deploy --services platform
 
 # Preview without changes
 tale deploy --dry-run
@@ -45,7 +63,7 @@ tale deploy --dry-run
 
 ## The blue-green pattern
 
-A running instance is one of the two colours (blue or green) at any given time. `tale deploy` brings up the other colour, waits for it to pass healthchecks, then flips Caddy's upstream to the new colour. The old colour drains its in-flight requests (default 30 s), then exits.
+A running instance is one of the two colours (blue or green) at any given time. The deploy phase brings up the other colour, waits for it to pass healthchecks, then flips Caddy's upstream to the new colour. The old colour drains its in-flight requests (default 30 s), then exits.
 
 Three guarantees the pattern gives you:
 
@@ -53,16 +71,21 @@ Three guarantees the pattern gives you:
 - **Patch rollback is one command.** `tale rollback` redeploys the previous patch release on the idle colour and flips traffic back. It refuses minor and major downgrades — those can leave the database ahead of the binary, and their recovery path is a snapshot restore.
 - **Failed healthchecks block the flip.** If the new colour does not pass within the timeout, the deploy aborts and the old colour continues serving.
 
-The full deploy procedure including the cleanup phase lives in `tale --help`; the operator-facing recipe is `tale deploy && tale status` and visual confirmation in the browser.
+The full deploy procedure including the cleanup phase lives in `tale --help`; the operator-facing recipe is `tale update && tale deploy && tale status` and visual confirmation in the browser.
 
 ## Rolling back
 
 ```bash
-# Back to the previous patch version
+# Back to the previous patch version (prompts for confirmation)
 tale rollback
+
+# Skip the prompt when running non-interactively
+tale rollback --yes
 ```
 
-`tale rollback` is gated to patch-level steps: it only targets the recorded previous version, and refuses unless that version shares `major.minor` with the running platform. Patch releases never carry migrations, so redeploying the previous patch is always safe. Anything bigger may have migrated data forward — redeploying an older binary on top of migrated data corrupts the instance instead of recovering it. For those, the recovery path is restoring the pre-upgrade snapshot and redeploying the version that matches it; the refusal message prints the exact commands, and the full walk lives in [Backups and restore](/self-hosted/operate/backups-and-restore).
+`tale rollback` is gated to patch-level steps: it only targets the recorded previous version, and refuses unless that version shares `major.minor` with the running platform. Patch releases never carry migrations, so redeploying the previous patch is always safe. Anything bigger may have migrated data forward — redeploying an older binary on top of migrated data corrupts the instance instead of recovering it. For those, the recovery path is restoring the pre-upgrade snapshot and moving back to the version that matches it with `tale update --version <version>` followed by `tale deploy --stop` (so `db`/`proxy` roll back too); the refusal message prints the exact commands, and the full walk lives in [Backups and restore](/self-hosted/operate/backups-and-restore).
+
+Because the rollback tears down the running containers, the command warns what it is about to do and asks for confirmation before it pulls a single image; pass `--yes` to skip that prompt in scripts or CI.
 
 ## Version compatibility
 
@@ -74,6 +97,8 @@ Tale versions are semver. The compatibility rules:
 
 Skipping minor versions (going from 0.9 to 0.11) is supported as long as the intermediate migrations are still in the binary; the release notes call it out when this is not the case.
 
+To move _down_ a version deliberately — say a minor release misbehaves and you have already reversed its migrations — pin the target with `tale update --version <version>`. The command warns when the target is older than the running version and reminds you to reverse data migrations first.
+
 ## Where this fits
 
 The upgrade flow ties together every other operate page — backups are what makes a failed upgrade recoverable, observability is what tells you the new colour is healthy, hardening is what you re-walk after a major version. If you are setting up the CLI for the first time, [Install the tale CLI](/self-hosted/install/cli-install) covers the workstation-side setup; if you are picking up the pager mid-rollout, [Troubleshooting](/self-hosted/operate/observability/troubleshooting) names the symptoms.
diff --git a/docs/fr/cloud/onboarding.md b/docs/fr/cloud/onboarding.md
index 0b888ab986..dd4f15d007 100644
--- a/docs/fr/cloud/onboarding.md
+++ b/docs/fr/cloud/onboarding.md
@@ -41,7 +41,7 @@ Pour une marche plus profonde sur ce qui fait un bon agent, voir [Créer un agen
 
 ## Étape 5 — Ouvrir le chat
 
-Ouvre **Chat** dans la sidebar et clique **Nouveau chat**. Choisis l'agent dans le sélecteur, tape une question que le domaine de l'agent couvre, envoie. La réponse arrive en streaming ; si elle atterrit comme tu l'as écrite dans les instructions, l'organisation a fini son onboarding.
+Clique sur **Nouveau chat** dans la sidebar. Choisis l'agent dans le sélecteur, tape une question que le domaine de l'agent couvre, envoie. La réponse arrive en streaming ; si elle atterrit comme tu l'as écrite dans les instructions, l'organisation a fini son onboarding.
 
 Trois suites utiles à faire maintenant pendant que tout est frais :
 
diff --git a/docs/fr/develop/ai-assisted-development.md b/docs/fr/develop/ai-assisted-development.md
index a92aea8268..391c6c7d88 100644
--- a/docs/fr/develop/ai-assisted-development.md
+++ b/docs/fr/develop/ai-assisted-development.md
@@ -34,7 +34,7 @@ La directive compte parce que tout éditeur sous charge saute les lectures de sc
 | `integrations/<slug>/config.json`  | Manifeste d'intégration — operations, méthode d'auth, hôtes autorisés.               |
 | `integrations/<slug>/connector.ts` | Connecteur TypeScript optionnel pour les formes REST que le manifeste ne couvre pas. |
 | `branding/branding.json`           | Branding de l'org — couleurs, logos, expéditeurs courriel.                           |
-| `.tale/reference/`                 | Miroir de schéma en lecture seule ; régénéré par `tale init` et `tale upgrade`.      |
+| `.tale/reference/`                 | Miroir de schéma en lecture seule ; régénéré par `tale init` et `tale update`.       |
 
 L'arbre de référence est byte-à-byte identique aux schémas contre lesquels la plateforme valide au déploiement. Traite-le comme canonique : quand un nom de champ dans une config écrite à la main désaccorde avec la référence, la référence gagne.
 
@@ -46,7 +46,7 @@ Le fichier de règles nomme trois règles que chaque éditeur applique pendant l
 - **Les workflows utilisent les operations d'intégration.** Une étape de workflow référence une operation d'intégration déclarée dans `integrations/<slug>/config.json`. Éditer une étape contre une operation qui n'existe pas fait échouer la validation.
 - **Le nommage est imposé.** Les noms de fichier d'agent correspondent à `[a-z0-9][a-z0-9_-]*\.json`. Les slugs d'étape de workflow correspondent à `[a-z0-9][a-z0-9_-]*`. Les répertoires d'intégration sont en minuscules alphanumériques avec tirets ou soulignés.
 
-Quand l'éditeur propose un changement, demande-lui de citer le fichier dans `.tale/reference/` sur lequel il s'est appuyé. S'il ne peut pas, régénère le miroir avec `tale upgrade` et réessaie.
+Quand l'éditeur propose un changement, demande-lui de citer le fichier dans `.tale/reference/` sur lequel il s'est appuyé. S'il ne peut pas, régénère le miroir avec `tale update` et réessaie.
 
 ## Où cela s'inscrit
 
diff --git a/docs/fr/platform/agents/external-agent.md b/docs/fr/platform/agents/external-agent.md
index c26fe28490..52aa9be36f 100644
--- a/docs/fr/platform/agents/external-agent.md
+++ b/docs/fr/platform/agents/external-agent.md
@@ -29,7 +29,7 @@ La façon dont l'agent atteint son modèle est un choix propre à chaque agent,
 
 **Géré (passerelle de la plateforme)** est le mode par défaut, celui que décrivent toutes les sections ci-dessus. La plateforme forge une clé virtuelle éphémère pour le tour, achemine l'agent par sa passerelle, applique les modèles autorisés de l'agent, mesure l'utilisation et applique les plafonds de dépense de l'organisation. Le bac à sable ne détient jamais de vraie clé de fournisseur.
 
-**Apporte tes propres identifiants (BYO)** retire la plateforme du chemin de la requête. Aucune clé virtuelle n'est forgée ; l'agent s'authentifie avec les identifiants que tu stockes sous [Environnement et secrets](/fr/platform/member/environment) et atteint directement le fournisseur. Le modèle devient un identifiant de fournisseur brut que tu saisis tel quel plutôt qu'une entrée de catalogue, et la recherche et la récupération web natives de l'agent restent activées au lieu d'être désactivées. Comme la passerelle est contournée, la liste de modèles autorisés, les plafonds de dépense et la mesure d'utilisation de l'organisation ne s'appliquent pas aux tours BYO — la facturation et les limites passent à ton propre compte de fournisseur. Faire passer un agent du mode géré au mode BYO efface ses modèles de plateforme enregistrés, puisque les références de catalogue ne signifient rien pour un passage direct brut ; tu ressaisis les identifiants bruts.
+**Apporte tes propres identifiants (BYO)** retire la plateforme du chemin de la requête. Aucune clé virtuelle n'est forgée ; l'agent s'authentifie avec les identifiants que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) et atteint directement le fournisseur. Le modèle devient un identifiant de fournisseur brut que tu saisis tel quel plutôt qu'une entrée de catalogue, et la recherche et la récupération web natives de l'agent restent activées au lieu d'être désactivées. Comme la passerelle est contournée, la liste de modèles autorisés, les plafonds de dépense et la mesure d'utilisation de l'organisation ne s'appliquent pas aux tours BYO — la facturation et les limites passent à ton propre compte de fournisseur. Faire passer un agent du mode géré au mode BYO efface ses modèles de plateforme enregistrés, puisque les références de catalogue ne signifient rien pour un passage direct brut ; tu ressaisis les identifiants bruts.
 
 C'est aussi un déplacement de la frontière de confiance. En mode géré, le bac à sable ne détient qu'une clé de passerelle limitée par un budget ; en mode BYO, ton véritable identifiant de fournisseur est injecté dans l'environnement du bac à sable — la même posture que le jeton GitHub dans le bac à sable — de sorte que tout code que l'agent exécute dans la boîte peut le lire. C'est intentionnel : c'est ta boîte et ton identifiant. Configurer un agent est déjà une action privilégiée, si bien que le commutateur par agent est le seul contrôle ; il n'y a pas de bascule distincte au niveau de l'organisation.
 
@@ -47,4 +47,4 @@ Cette comptabilité est une propriété de la passerelle ; elle ne couvre donc q
 
 ## Où cela s'inscrit
 
-Un agent externe transforme un fil de discussion en une session en direct avec un outil de code dans un bac à sable — tu le pilotes en langage clair, il travaille dans un espace de travail isolé, et la session persiste pour les suivis jusqu'à ce que tu fermes le fil. Les identifiants sont l'axe qui décide quelle part de tout cela s'exécute sous le contrôle de l'organisation : un agent géré reste sur la passerelle de la plateforme, sous les plafonds et la mesure de l'organisation, tandis qu'un agent qui apporte ses propres identifiants s'exécute sur les clés que tu conserves sous [Environnement et secrets](/fr/platform/member/environment) et répond à ton propre compte de fournisseur. Les candidats à la dérive ici sont les noms d'agent et de modèle ; associe cette page à la liste des [Fournisseurs](/fr/platform/admin/providers) en cours plutôt que de mémoriser des chaînes de modèle spécifiques, et à [Intégrations](/fr/platform/integrations/overview) pour les intégrations connectées que l'agent peut atteindre — de GitHub pour un véritable flux de pull request à une intégration de recherche ou de données qui amène des faits externes dans le travail.
+Un agent externe transforme un fil de discussion en une session en direct avec un outil de code dans un bac à sable — tu le pilotes en langage clair, il travaille dans un espace de travail isolé, et la session persiste pour les suivis jusqu'à ce que tu fermes le fil. Les identifiants sont l'axe qui décide quelle part de tout cela s'exécute sous le contrôle de l'organisation : un agent géré reste sur la passerelle de la plateforme, sous les plafonds et la mesure de l'organisation, tandis qu'un agent qui apporte ses propres identifiants s'exécute sur les clés que tu conserves sous [Variables d'environnement et secrets](/fr/platform/member/environment) et répond à ton propre compte de fournisseur. Les candidats à la dérive ici sont les noms d'agent et de modèle ; associe cette page à la liste des [Fournisseurs](/fr/platform/admin/providers) en cours plutôt que de mémoriser des chaînes de modèle spécifiques, et à [Intégrations](/fr/platform/integrations/overview) pour les intégrations connectées que l'agent peut atteindre — de GitHub pour un véritable flux de pull request à une intégration de recherche ou de données qui amène des faits externes dans le travail.
diff --git a/docs/fr/platform/member/environment.md b/docs/fr/platform/member/environment.md
index 88f72869de..9bd01bdcea 100644
--- a/docs/fr/platform/member/environment.md
+++ b/docs/fr/platform/member/environment.md
@@ -1,15 +1,15 @@
 ---
-title: Environnement et secrets
+title: Variables d'environnement et secrets
 description: Tes variables d'environnement et secrets personnels, injectés dans chaque sandbox d'agent que tu lances dans une organisation — le plus souvent l'identifiant fournisseur avec lequel un agent BYO s'authentifie.
 ---
 
-Environnement et secrets est ton magasin personnel de variables que Tale injecte dans chaque sandbox d'agent que tu lances dans cette organisation. Quand un agent externe démarre sa sandbox, chaque entrée que tu as enregistrée ici est posée dans l'environnement du conteneur avant que l'agent tourne, pour qu'une commande lancée par l'agent — ou l'agent lui-même — puisse la lire. L'usage phare, ce sont les identifiants : un [agent externe en mode BYO](/fr/platform/agents/external-agent) s'authentifie avec la clé API ou le jeton que tu gardes ici plutôt qu'avec la passerelle de la plateforme. C'est une page de niveau membre que chaque rôle peut atteindre, et les entrées sont cantonnées à toi et à l'organisation actuelle, donc elles ne fuient jamais vers tes coéquipiers et ne te suivent jamais dans une autre org.
+Variables d'environnement et secrets est ton magasin personnel de variables que Tale injecte dans chaque sandbox d'agent que tu lances dans cette organisation. Quand un agent externe démarre sa sandbox, chaque entrée que tu as enregistrée ici est posée dans l'environnement du conteneur avant que l'agent tourne, pour qu'une commande lancée par l'agent — ou l'agent lui-même — puisse la lire. L'usage phare, ce sont les identifiants : un [agent externe en mode BYO](/fr/platform/agents/external-agent) s'authentifie avec la clé API ou le jeton que tu gardes ici plutôt qu'avec la passerelle de la plateforme. C'est une page de niveau membre que chaque rôle peut atteindre, et les entrées sont cantonnées à toi et à l'organisation actuelle, donc elles ne fuient jamais vers tes coéquipiers et ne te suivent jamais dans une autre org.
 
 Cette page couvre les deux types d'entrée, comment les secrets sont protégés, les règles qu'un nom et une valeur doivent respecter, et où les valeurs finissent.
 
 ## Variables et secrets
 
-Ouvre **Paramètres > Environnement**. La page est un formulaire d'ajout en haut et la liste de ce que tu as enregistré en dessous. Chaque entrée est un **Nom** et une **Valeur**, plus une bascule **Secret** qui décide comment la valeur est stockée et affichée.
+Ouvre **Paramètres > Environnement**. **Ajouter une variable** ouvre une boîte de dialogue pour une nouvelle entrée, avec la liste de ce que tu as enregistré en dessous. Chaque entrée est un **Nom** et une **Valeur**, plus une bascule **Secret** qui décide comment la valeur est stockée et affichée.
 
 Une variable simple est stockée telle quelle et réaffichée en entier dans la liste — utilise-la pour la configuration non sensible que l'agent attend, un nom de région ou un endpoint. Un **secret** est chiffré dès l'instant où tu l'enregistres et devient en écriture seule à partir de là : la liste montre `••••••••` à la place de la valeur, et il n'y a aucun moyen de la relire. Active la bascule pour tout ce qui est sensible — une clé API, un jeton OAuth, un mot de passe. Le compromis, c'est que tu ne peux pas revoir la valeur d'un secret plus tard, donc si tu n'es pas sûr qu'elle soit bonne, supprime-le et ajoute-le à nouveau plutôt que de chercher un bouton d'affichage qui n'existe pas.
 
@@ -29,4 +29,4 @@ Cette dernière étape est la frontière à comprendre : les valeurs atterrissen
 
 ## Où cela s'inscrit
 
-Environnement et secrets est l'unique page de niveau membre qui atteint la sandbox plutôt que le chat — c'est par elle que tes propres clés et ta configuration parviennent aux agents que tu lances, sans qu'un Éditeur ou un Admin ne les pose à ta place. L'entrée que tu ajouteras le plus souvent est l'identifiant fournisseur d'un [agent externe en mode BYO](/fr/platform/agents/external-agent) ; lis cette page en parallèle de celle-là pour voir les deux moitiés — où l'identifiant est stocké et comment on dit à un agent de l'utiliser au lieu de la passerelle de la plateforme. Pour le reste de tes réglages personnels — nom d'affichage, mot de passe, instructions personnalisées — vois [Préférences](/fr/platform/member/preferences).
+Variables d'environnement et secrets est l'unique page de niveau membre qui atteint la sandbox plutôt que le chat — c'est par elle que tes propres clés et ta configuration parviennent aux agents que tu lances, sans qu'un Éditeur ou un Admin ne les pose à ta place. L'entrée que tu ajouteras le plus souvent est l'identifiant fournisseur d'un [agent externe en mode BYO](/fr/platform/agents/external-agent) ; lis cette page en parallèle de celle-là pour voir les deux moitiés — où l'identifiant est stocké et comment on dit à un agent de l'utiliser au lieu de la passerelle de la plateforme. Pour le reste de tes réglages personnels — nom d'affichage, mot de passe, instructions personnalisées — vois [Préférences](/fr/platform/member/preferences).
diff --git a/docs/fr/platform/member/overview.md b/docs/fr/platform/member/overview.md
index 49cded6043..d31063676d 100644
--- a/docs/fr/platform/member/overview.md
+++ b/docs/fr/platform/member/overview.md
@@ -16,7 +16,7 @@ La surface Membre est volontairement étroite. Les quatre seaux sont :
 - **Conversations** — lire les threads d'inbox qui te sont assignés. Les Membres répondent quand un agent rend une conversation ; ils ne peuvent pas réassigner ou fermer des threads que d'autres possèdent.
 - **Approbations** — lire les cartes d'approbation routées vers toi. Clique sur Approuver, Rejeter, ou Demander des changements ; laisse un commentaire si la règle le demande.
 
-Les réglages de configuration de l'org — Fournisseurs, Intégrations, Agents, Gouvernance — sont cachés pour les Membres ; la surface travail est l'essentiel de ce qui reste. L'exception est un petit groupe de réglages personnels que porte chaque rôle : Compte, Personnalisation et [Environnement et secrets](/fr/platform/member/environment), les clés et variables injectées dans les sandboxes que tu fais tourner.
+Les réglages de configuration de l'org — Fournisseurs, Intégrations, Agents, Gouvernance — sont cachés pour les Membres ; la surface travail est l'essentiel de ce qui reste. L'exception est un petit groupe de réglages personnels que porte chaque rôle : Compte, Personnalisation et [Variables d'environnement et secrets](/fr/platform/member/environment), les clés et variables injectées dans les sandboxes que tu fais tourner.
 
 ## Pages dans cette section
 
diff --git a/docs/fr/platform/member/preferences.md b/docs/fr/platform/member/preferences.md
index aa2c77ab28..03cb11ba06 100644
--- a/docs/fr/platform/member/preferences.md
+++ b/docs/fr/platform/member/preferences.md
@@ -37,4 +37,4 @@ La ligne **Se déconnecter** en bas du menu de profil confirme via une boîte de
 
 ## Où cela s'inscrit
 
-Les préférences sont la ligne entre toi et le reste de l'org. L'Administrateur de l'org pose les valeurs par défaut — y compris si la personnalisation est active pour les nouveaux membres, quelle est la politique de mot de passe, quels modèles sont autorisés — et tes préférences remplacent les valeurs par défaut là où Tale le permet. Une page personnelle se tient à l'écart de cet ensemble : [Environnement et secrets](/fr/platform/member/environment) porte des variables et des identifiants cantonnés à toi au sein d'une seule organisation plutôt qu'ils ne te suivent d'une org à l'autre — l'endroit où garder la clé de fournisseur qu'utilise un agent BYO. La lecture suivante à mettre en file est [Vue d'ensemble Membre](/fr/platform/member/overview) pour la carte du reste de la surface Membre, ou [Installer en tant qu'app](/fr/platform/member/install-as-app) si tu veux que Tale vive dans ton dock plutôt que dans tes onglets de navigateur.
+Les préférences sont la ligne entre toi et le reste de l'org. L'Administrateur de l'org pose les valeurs par défaut — y compris si la personnalisation est active pour les nouveaux membres, quelle est la politique de mot de passe, quels modèles sont autorisés — et tes préférences remplacent les valeurs par défaut là où Tale le permet. Une page personnelle se tient à l'écart de cet ensemble : [Variables d'environnement et secrets](/fr/platform/member/environment) porte des variables et des identifiants cantonnés à toi au sein d'une seule organisation plutôt qu'ils ne te suivent d'une org à l'autre — l'endroit où garder la clé de fournisseur qu'utilise un agent BYO. La lecture suivante à mettre en file est [Vue d'ensemble Membre](/fr/platform/member/overview) pour la carte du reste de la surface Membre, ou [Installer en tant qu'app](/fr/platform/member/install-as-app) si tu veux que Tale vive dans ton dock plutôt que dans tes onglets de navigateur.
diff --git a/docs/fr/platform/models.md b/docs/fr/platform/models.md
index 9c2fcb4b1f..ce1ebcb6eb 100644
--- a/docs/fr/platform/models.md
+++ b/docs/fr/platform/models.md
@@ -17,21 +17,65 @@ OpenRouter est un endpoint compatible OpenAI que Tale appelle en HTTPS avec un b
 
 ## OpenRouter — chat, vision, embeddings
 
-OpenRouter est une passerelle multi-modèles. La configuration livrée choisit `deepseek-v4-flash` comme modèle de chat par défaut, `qwen3-vl-32b-instruct` pour la vision et `qwen3-embedding-8b` pour les embeddings — tous choisis pour le rapport vitesse/qualité au moment de l'écriture. La liste complète livrée :
-
-- **Anthropic** — Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5.
-- **OpenAI** — GPT-5.2 Pro, GPT-5.2, GPT-5.2 Instant, GPT-OSS 120B (la version open-weight).
-- **Google** — Gemini 3 Pro, Gemini 3 Flash, Gemma 4 31B IT, Gemma 4 26B A4B IT, Nano Banana (Gemini 2.5 Flash Image).
-- **DeepSeek** — DeepSeek V4 Pro, DeepSeek V4 Flash.
-- **Moonshot AI** — Kimi K2.6, Kimi K2.5.
-- **MiniMax** — MiniMax M2.7.
-- **NVIDIA** — Nemotron 3 Super 120B.
-- **Qwen** — Qwen3.6 Max Preview, Qwen3.6 Plus, Qwen3.6 Flash, Qwen3.6 35B A3B, Qwen3.5 397B A17B, Qwen3 Coder 480B, Qwen3 235B A22B, Qwen3 VL 32B, Qwen3 Embedding 8B.
-- **Z.AI** — GLM 5.1, GLM 5 Turbo, GLM 5V Turbo.
-- **Mistral** — Mistral Large 3, Mistral Medium 3.
-- **Xiaomi** — MiMo V2.5 Pro.
-- **Meta** — LLaMA 4 Maverick, LLaMA 4 Scout.
-- **Black Forest Labs** — FLUX.2 [max], FLUX.2 [pro], FLUX.2 [flex].
+OpenRouter est une passerelle multi-modèles. La configuration livrée choisit `deepseek-v4-flash` comme modèle de chat par défaut, `qwen3-vl-32b-instruct` pour la vision et `qwen3-embedding-8b` pour les embeddings — tous choisis pour le rapport vitesse/qualité au moment de l'écriture. La liste complète ci-dessous reprend chaque modèle visible de la `openrouter.json` livrée, régénérée par le job de catalogue hebdomadaire pour qu'elle ne dérive jamais de la configuration :
+
+<!-- MODELS_TABLE:START -->
+
+<!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. -->
+
+| Fournisseur       | Modèle                               | Capacités                    | Contexte | Entrée ($/M) | Sortie ($/M) |
+| ----------------- | ------------------------------------ | ---------------------------- | -------- | ------------ | ------------ |
+| AI21              | Jamba Large 1.7                      | chat                         | 256K     | 2.00         | 8.00         |
+| Amazon            | Nova Premier                         | chat, vision                 | 1M       | 2.50         | 12.50        |
+| Amazon            | Nova 2 Lite                          | chat, vision                 | 1M       | 0.30         | 2.50         |
+| Anthropic         | Claude Sonnet 4.6                    | chat, vision                 | 1M       | 3.00         | 15.00        |
+| Anthropic         | Claude Haiku 4.5                     | chat                         | 200K     | 1.00         | 5.00         |
+| Anthropic         | Claude Opus 4.8                      | chat, vision                 | 1M       | 5.00         | 25.00        |
+| Black Forest Labs | FLUX.2 [flex]                        | image-generation, image-edit | —        | —            | —            |
+| Black Forest Labs | FLUX.2 [max]                         | image-generation, image-edit | —        | —            | —            |
+| Black Forest Labs | FLUX.2 [pro]                         | image-generation, image-edit | —        | —            | —            |
+| Cohere            | Command A                            | chat                         | 256K     | 2.50         | 10.00        |
+| Cohere            | Command R                            | chat                         | 128K     | 0.15         | 0.60         |
+| DeepSeek          | DeepSeek V4 Pro                      | chat                         | 1M       | 0.43         | 0.87         |
+| DeepSeek          | DeepSeek V4 Flash                    | chat                         | 1M       | 0.09         | 0.18         |
+| Google            | Gemini 3 Pro                         | chat, vision                 | 1M       | 2.00         | 12.00        |
+| Google            | Gemini 3 Flash                       | chat, vision                 | 1M       | 0.50         | 3.00         |
+| Google            | Gemma 4 31B IT                       | chat, vision                 | 262K     | 0.12         | 0.35         |
+| Google            | Gemma 4 26B A4B IT                   | chat, vision                 | 262K     | 0.06         | 0.33         |
+| Google            | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K      | 0.30         | 2.50         |
+| Liquid            | LFM2 24B                             | chat                         | 128K     | 0.03         | 0.12         |
+| Meta              | LLaMA 4 Maverick                     | chat                         | 1M       | 0.15         | 0.60         |
+| Meta              | LLaMA 4 Scout                        | chat                         | 10M      | 0.10         | 0.30         |
+| Microsoft         | Phi-4                                | chat                         | 16K      | 0.07         | 0.14         |
+| MiniMax           | MiniMax M3                           | chat, vision                 | 1M       | 0.30         | 1.20         |
+| Mistral           | Mistral Large 3                      | chat                         | 262K     | 0.50         | 1.50         |
+| Mistral           | Mistral Medium 3.5                   | chat, vision                 | 262K     | 1.50         | 7.50         |
+| Moonshot AI       | Kimi K2.6                            | chat, vision                 | 262K     | 0.68         | 3.41         |
+| Moonshot AI       | Kimi K2.7 Code                       | chat, vision                 | 262K     | 0.61         | 3.07         |
+| NVIDIA            | Nemotron 3 Ultra                     | chat                         | 1M       | 0.50         | 2.20         |
+| NVIDIA            | Nemotron 3 Super                     | chat                         | 1M       | 0.09         | 0.45         |
+| OpenAI            | GPT-OSS 120B                         | chat                         | 131K     | 0.04         | 0.18         |
+| OpenAI            | GPT-4o mini TTS                      | text-to-speech               | —        | —            | —            |
+| OpenAI            | GPT-5.3 Chat                         | chat, vision                 | 128K     | 1.75         | 14.00        |
+| OpenAI            | GPT-5.5                              | chat, vision                 | 1M       | 5.00         | 30.00        |
+| OpenAI            | GPT-5.5 Pro                          | chat, vision                 | 1M       | 30.00        | 180.00       |
+| OpenAI            | Whisper v1                           | transcription                | —        | —            | —            |
+| Perplexity        | Sonar Pro                            | chat, vision                 | 200K     | 3.00         | 15.00        |
+| Perplexity        | Sonar                                | chat, vision                 | 127K     | 1.00         | 1.00         |
+| Qwen              | Qwen3.6 Max Preview                  | chat                         | 262K     | 1.04         | 6.24         |
+| Qwen              | Qwen3 Coder 480B                     | chat                         | 1M       | 0.22         | 1.80         |
+| Qwen              | Qwen3 VL 32B                         | chat, vision                 | 262K     | 0.10         | 0.42         |
+| Qwen              | Qwen3.6 Flash                        | chat, vision                 | 1M       | 0.19         | 1.13         |
+| Qwen              | Qwen3 Embedding 8B                   | embedding                    | —        | 0.01         | 0.00         |
+| Qwen              | Qwen3.7 Plus                         | chat, vision                 | 1M       | 0.32         | 1.28         |
+| Reka              | Reka Flash 3                         | chat                         | 66K      | 0.10         | 0.20         |
+| Xiaomi            | MiMo V2.5 Pro                        | chat                         | 1M       | 0.43         | 0.87         |
+| Z.AI              | GLM 5.1                              | chat                         | 203K     | 0.98         | 3.08         |
+| Z.AI              | GLM 5 Turbo                          | chat                         | 262K     | 1.20         | 4.00         |
+| Z.AI              | GLM 5V Turbo                         | chat, vision                 | 131K     | 1.20         | 4.00         |
+| xAI               | Grok 4.20                            | chat, vision                 | 2M       | 1.25         | 2.50         |
+
+<!-- MODELS_TABLE:END -->
 
 Le catalogue complet et à jour vit sur [openrouter.ai/models](https://openrouter.ai/models). Tout modèle exposé par OpenRouter peut être ajouté à ton instance en éditant le tableau `models` dans `<orgSlug>/providers/openrouter.json` sous `TALE_CONFIG_DIR` (par-org sous le layout org-first).
 
diff --git a/docs/fr/self-hosted/configuration/providers.md b/docs/fr/self-hosted/configuration/providers.md
index 35057de084..6f9db01d58 100644
--- a/docs/fr/self-hosted/configuration/providers.md
+++ b/docs/fr/self-hosted/configuration/providers.md
@@ -33,7 +33,7 @@ La référence est le format de fichier sur disque et l'ordre des opérations à
 }
 ```
 
-L'ensemble complet des champs vit dans [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Le défaut livré est un seul `openrouter.json` qui couvre le chat, la vision, les embeddings, la transcription, la synthèse vocale et la génération d'images — une clé pour tout. Pour appeler un fournisseur directement plutôt que via OpenRouter, ajoute un autre fichier (par exemple un `openai.json` pointant vers `https://api.openai.com/v1`) ; voir [Modèles livrés en standard](/fr/platform/models) pour le catalogue complet par défaut.
+L'ensemble complet des champs vit dans [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Le défaut livré est un seul `openrouter.json` qui couvre le chat, la vision, les embeddings, la transcription, la synthèse vocale et la génération d'images — une clé pour tout — avec des presets curés pour les fournisseurs courants (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity et plus). Pour appeler un fournisseur directement plutôt que via OpenRouter, ajoute un autre fichier (par exemple un `openai.json` pointant vers `https://api.openai.com/v1`) ; voir [Modèles livrés en standard](/fr/platform/models) pour le catalogue complet par défaut.
 
 `transcriptionMode` sélectionne la forme du corps de requête d'un modèle `transcription` : `json-base64` (l'enveloppe `input_audio` d'OpenRouter) ou, s'il est omis, `multipart` — l'upload `multipart/form-data` OpenAI/Whisper qu'attendent aussi vLLM, LocalAI et une clé OpenAI directe. Définis-le selon l'endpoint de transcription que tu vises.
 
diff --git a/docs/fr/self-hosted/configuration/retention.md b/docs/fr/self-hosted/configuration/retention.md
index a1851e1e3f..9ac5f86b6b 100644
--- a/docs/fr/self-hosted/configuration/retention.md
+++ b/docs/fr/self-hosted/configuration/retention.md
@@ -37,6 +37,8 @@ Sous la disposition org-first, les bornes de rétention sont **par org** : édit
 
 Le conteneur plateforme surveille le fichier ; les changements proposent une mise à jour de bornes pour chaque org existante. Les admins voient la proposition dans leur écran **Politique de rétention** et l'appliquent eux-mêmes. L'étape propose-puis-applique est délibérée : resserrer un plancher raccourcit l'historique, ce qui est une action destructive qu'aucun opérateur ne devrait poser silencieusement sur chaque tenant.
 
+Les fenêtres de rétention choisies par l'admin vivent dans un fichier distinct, `retention-policy.json`, à côté des bornes dans le même dossier `governance/`. Il contient des champs plats `<catégorie>Enabled` / `<catégorie>RetentionDays` (p. ex. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), pas les bornes `min`/`max`. Ce fichier est écrit par **Paramètres > Gouvernance > Politique de rétention** dans l'app, donc les admins ne l'éditent normalement jamais à la main — garde-le distinct du fichier de bornes géré par l'opérateur.
+
 ## Le sweep de rétention
 
 Un cron planifié dans `tale-convex` fait la suppression réelle. Chaque catégorie est sweepée indépendamment — un run lent sur une ne bloque pas les autres. Les suppressions sont auditées (chaque catégorie a son propre événement `*.retention_deleted`), et restaurer une entité dans sa fenêtre de grâce est possible depuis **Corbeille** avant le sweep final.
diff --git a/docs/fr/self-hosted/install/cli-install.md b/docs/fr/self-hosted/install/cli-install.md
index 6d39aeea3e..d08ed1aa5c 100644
--- a/docs/fr/self-hosted/install/cli-install.md
+++ b/docs/fr/self-hosted/install/cli-install.md
@@ -133,14 +133,16 @@ Les commandes se terminent avec `0` en cas de succès, `2` pour une erreur d'uti
 - `--stop` — arrêter les conteneurs du projet avant la restauration.
 - `-y, --yes` — ignorer l'invite de confirmation.
 
-`tale rollback` — revenir à la version patch précédente (niveau patch uniquement). Aucun argument.
+`tale rollback` — revenir à la version patch précédente (niveau patch uniquement). Demande confirmation au préalable.
+
+- `-y, --yes` — ignorer l'invite de confirmation (requis en mode non-interactif).
 
 ### Maintenance
 
-`tale upgrade` (alias `tale update`) — mettre à jour le CLI vers la dernière version et synchroniser les fichiers projet.
+`tale update` — bouger cette instance Tale vers une nouvelle version : mettre à jour le binaire CLI, puis synchroniser les fichiers projet sur les templates de cette version. Lance `tale deploy` ensuite pour rouler les conteneurs. La CLI s'aligne aussi d'elle-même sur la version de l'instance à chaque commande, donc ceci n'est nécessaire que pour changer délibérément de version.
 
-- `-v, --version <version>` — installer exactement cette version (p. ex. `0.9.0`) au lieu de la dernière ; autorise les rétrogradations.
-- `-f, --force` — forcer le re-téléchargement et écraser les fichiers modifiés localement.
+- `-v, --version <version>` — mettre à jour vers exactement cette version (p. ex. `0.9.0`) au lieu de la dernière ; autorise les rétrogradations.
+- `-f, --force` — forcer la re-synchronisation et écraser les fichiers projet modifiés localement.
 - `--dry-run` — montrer ce qui changerait sans rien modifier.
 
 `tale cleanup` — supprimer les conteneurs inactifs (couleur non courante). Aucun argument.
@@ -151,6 +153,12 @@ Les commandes se terminent avec `0` en cas de succès, `2` pour une erreur d'uti
 - `-a, --all` — supprimer aussi les conteneurs d'infrastructure avec état.
 - `--dry-run` — prévisualiser la réinitialisation sans rien modifier.
 
+`tale uninstall` — supprimer le binaire CLI `tale` de ce système. Il demande confirmation avant de supprimer quoi que ce soit et _propose_ de retirer aussi la configuration propre à l'utilisateur (`~/.tale-daemon`) et de démanteler les ressources Docker et les fichiers d'un projet. Sans `--purge`, un projet et ses conteneurs restent intacts — lance `tale reset --all` à l'intérieur pour les supprimer.
+
+- `-f, --force` — ignorer l'invite de confirmation (supprime uniquement le binaire ; les nettoyages optionnels nécessitent toujours `--purge`).
+- `--purge` — retirer aussi `~/.tale-daemon` et, pour un projet trouvé depuis le répertoire courant, démanteler ses ressources Docker et supprimer ses fichiers. Irréversible.
+- `--dry-run` — montrer ce qui serait supprimé sans rien supprimer.
+
 `tale config` — gérer la configuration du CLI. Utilise le sous-commande `show` pour afficher la configuration résolue.
 
 ### Avancé
diff --git a/docs/fr/self-hosted/operate/backups-and-restore.md b/docs/fr/self-hosted/operate/backups-and-restore.md
index 028ae41886..cb2aac76f3 100644
--- a/docs/fr/self-hosted/operate/backups-and-restore.md
+++ b/docs/fr/self-hosted/operate/backups-and-restore.md
@@ -58,8 +58,8 @@ tale restore
 tale restore 20260611-142530-deploy --stop
 
 # Remonter le stack sur la version qui correspond aux données
-tale upgrade --version 0.9.6
-tale deploy --all
+tale update --version 0.9.6
+tale deploy --stop
 ```
 
 Le redéploiement de la version correspondante fait partie de la restauration, ce n'est pas un extra optionnel : le snapshot a capturé les données exactement comme cette version de la plateforme les a laissées, et un binaire plus récent relancerait immédiatement ses migrations dessus. La sortie de la restauration imprime la version exacte enregistrée dans le manifest du snapshot.
diff --git a/docs/fr/self-hosted/operate/release-notes/format.md b/docs/fr/self-hosted/operate/release-notes/format.md
index de2d44d4f1..760b61c0fc 100644
--- a/docs/fr/self-hosted/operate/release-notes/format.md
+++ b/docs/fr/self-hosted/operate/release-notes/format.md
@@ -5,7 +5,7 @@ description: La forme que suivent les notes de version de Tale — la promesse s
 
 Tale publie une version par minor et des patches comme tags correctifs entre elles. Les notes de version pour chaque tag suivent la même forme afin que tu puisses en scanner une en une minute et savoir si la montée de version est un bump de cinq minutes ou une fenêtre de maintenance. Cette page couvre le format : la promesse semver, ce que chaque section garantit, et où lire plus en profondeur quand une ligne pointe vers une migration.
 
-Les notes elles-mêmes vivent sur la page de release GitHub de chaque tag. La CLI les fait aussi remonter — `tale upgrade --notes` imprime les notes de la version qu'elle est sur le point d'installer.
+Les notes elles-mêmes vivent sur la page de release GitHub de chaque tag. La CLI les fait aussi remonter — `tale update --notes` imprime les notes de la version qu'elle est sur le point d'installer.
 
 ## La promesse semver
 
@@ -30,7 +30,7 @@ Chaque page de release est la même liste ordonnée de sections. Les sections vi
 
 ## Comment scanner une release
 
-Lis la ligne de version, les highlights et la section des changements breaking. Si la section breaking est vide et que la section sécurité ne nomme pas un fix qui touche ton install, la montée de version est la séquence à deux commandes de [Montées de version](/fr/self-hosted/operate/upgrades). Si l'une ou l'autre des sections a des lignes, parcours-les avant de lancer `tale deploy`.
+Lis la ligne de version, les highlights et la section des changements breaking. Si la section breaking est vide et que la section sécurité ne nomme pas un fix qui touche ton install, la montée de version est la séquence `tale update` + `tale deploy` depuis [Montées de version](/fr/self-hosted/operate/upgrades). Si l'une ou l'autre des sections a des lignes, parcours-les avant de lancer `tale deploy`.
 
 ```text
 0.12.0 (minor) — 14/05/2026
@@ -49,7 +49,7 @@ Sécurité
   Voir : avis TAL-2026-007.
 ```
 
-La forme ci-dessus est ce qu'imprime `tale upgrade --notes`. La version web de la même release ajoute des liens sur chaque ligne d'avis et de migration.
+La forme ci-dessus est ce qu'imprime `tale update --notes`. La version web de la même release ajoute des liens sur chaque ligne d'avis et de migration.
 
 ## Où cela s'inscrit
 
diff --git a/docs/fr/self-hosted/operate/upgrades.md b/docs/fr/self-hosted/operate/upgrades.md
index 58dd05d182..3151203994 100644
--- a/docs/fr/self-hosted/operate/upgrades.md
+++ b/docs/fr/self-hosted/operate/upgrades.md
@@ -1,43 +1,61 @@
 ---
 title: Montées de version
-description: Comment `tale upgrade` et `tale deploy` font avancer une instance Tale — le pattern de redémarrage rolling, quoi faire avant une montée de version et l'histoire de la compatibilité de versions.
+description: Comment `tale update` fait avancer une instance Tale — l'alignement automatique de version entre la CLI et l'instance, le pattern de redémarrage rolling, quoi faire avant une montée de version et l'histoire de la compatibilité de versions.
 ---
 
-Les montées de version sur une instance Tale auto-hébergée passent par la CLI `tale` en deux étapes : `tale upgrade` pour bouger le binaire lui-même à la nouvelle version, puis `tale deploy` pour rouler les conteneurs plateforme pour correspondre. Le déploiement utilise un pattern blue-green — la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine. Zéro downtime est le défaut ; si une release patch se comporte mal, `tale rollback` ramène le patch précédent en une commande, et tout ce qui est plus gros se récupère depuis le snapshot pré-upgrade.
+Les montées de version sur une instance Tale auto-hébergée passent par deux commandes : `tale update` bouge le binaire CLI à la nouvelle version et synchronise tes fichiers projet pour correspondre, puis `tale deploy` roule les conteneurs plateforme. Le déploiement utilise un pattern blue-green — la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine. Zéro downtime est le défaut ; si une release patch se comporte mal, `tale rollback` ramène le patch précédent en une commande, et tout ce qui est plus gros se récupère depuis le snapshot pré-upgrade.
 
-L'installation de la CLI vit dans [Installer la CLI tale](/fr/self-hosted/install/cli-install). Cette page couvre ce que fait chaque sous-commande et l'ordre dans lequel les exécuter.
+Ce que tu ne fais plus, c'est garder la CLI synchronisée à la main : la CLI s'aligne elle-même sur l'instance automatiquement (voir plus bas), donc le seul pas délibéré est de choisir quand bouger de version avec `tale update`.
+
+L'installation de la CLI vit dans [Installer la CLI tale](/fr/self-hosted/install/cli-install). Cette page couvre ce que fait chaque commande et comment le modèle de versions fonctionne.
+
+## La CLI suit l'instance automatiquement
+
+Le binaire CLI est toujours à la même version que l'instance qu'il gère. Le workspace enregistre cette version dans `tale.json` ; à chaque commande, la CLI compare sa propre version à celle-là et, si elles diffèrent, se met à jour pour correspondre (en montant ou en descendant) avant de tourner. Quand elles correspondent déjà — le cas largement le plus fréquent — c'est un no-op sans appel réseau, donc tu ne le remarques jamais.
+
+Cela veut dire que tu lances rarement `tale update`, sauf quand tu veux délibérément bouger vers une nouvelle version. Un coéquipier qui a installé une CLI plus récente que ton instance, ou restauré un snapshot plus ancien, obtient la bonne version de CLI automatiquement à sa prochaine commande. Il n'y a aucun flag pour désactiver ça — garder l'outil et l'instance au pas l'un de l'autre est ce qui rend les déploiements sûrs.
 
 ## Avant de monter de version
 
 Deux choses valent la peine d'être confirmées d'abord :
 
-- Ta copie hors-hôte du volume `backups` est à jour — voir [Backups et restauration](/fr/self-hosted/operate/backups-and-restore). `tale deploy` snapshotte automatiquement les volumes de données avant toute étape qui peut migrer des données, mais le snapshot vit sur le même hôte ; la copie hors-hôte est ce qui survit à un disque mort.
+- Ta copie hors-hôte du volume `backups` est à jour — voir [Backups et restauration](/fr/self-hosted/operate/backups-and-restore). `tale update` snapshotte automatiquement les volumes de données avant toute étape qui peut migrer des données, mais le snapshot vit sur le même hôte ; la copie hors-hôte est ce qui survit à un disque mort.
 - Les notes de version pour la version cible ne nomment pas un changement breaking. Les notes sont liées depuis la page de release GitHub ; les changements breaking sont flaggés comme tels en haut.
 
 Si la montée de version traverse une version majeure (1.x → 2.x), lis les notes de migration de bout en bout avant de commencer. Les versions majeures sont où atterrissent les migrations de schéma et les changements de format de fichier de config.
 
 ## Les deux commandes
 
-`tale upgrade` met à jour le binaire CLI lui-même. La version plateforme déployée correspond à la version de la CLI — ce couplage est intentionnel, pour que la CLI que tu lances ne puisse pas déployer une version qu'elle ne connaît pas.
+`tale update` met à jour le binaire CLI, puis synchronise tes fichiers projet sur les templates de cette version. Il ne **touche pas** aux conteneurs en marche — c'est le boulot de `tale deploy`. Si la synchro des fichiers échoue, la CLI fait reculer son propre binaire à la version sur laquelle ton workspace était, pour que le binaire et `tale.json` ne dérivent jamais l'un de l'autre.
 
 ```bash
-# Bouge la CLI à la dernière release
-tale upgrade
+# Bouge la CLI et les fichiers projet à la dernière release
+tale update
 
-# Puis roule la plateforme pour correspondre
-tale deploy
+# Fixe une version précise (autorise les downgrades — voir Rollback)
+tale update --version 0.10.2
+
+# Aperçu du changement de version et de la synchro des fichiers sans rien toucher
+tale update --dry-run
 ```
 
-`tale deploy` fait le redémarrage rolling réel : il pull les nouvelles images, démarre la nouvelle couleur blue ou green à côté de celle qui tourne, attend les healthchecks, bascule le proxy, draine et retire l'ancienne couleur. Le défaut cible les services rotables (`platform`, `rag`, `crawler`) ; les services stateful (`db`, `proxy`) ont besoin de `--all` pour être mis à jour en place.
+`tale deploy` fait le vrai redémarrage rolling, et il déploie toujours la version propre à la CLI — qui, grâce à l'alignement, est la version qu'enregistre ton workspace. Il trie les services en trois étages :
+
+- **Étage app/compute** — `platform`, `sandbox`, `sandbox-egress` — roule à **chaque** déploiement, sans downtime (blue-green : la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine).
+- **Backend** — `convex` — roule à chaque déploiement lui aussi, pour ne jamais dériver en version d'avec `platform` ; il ne se recrée en place que quand son image a réellement changé.
+- **Étage à arrêt requis** — `db`, `proxy` — laissés **en marche et intacts** par défaut (recréer Postgres ou le proxy est une brève coupure que tu ne veux pas sur un roll de routine). Passe `--stop` pour les mettre à jour ; le déploiement prévient et les nomme quand il les saute.
 
 ```bash
-# Inclus les services stateful
-tale deploy --all
+# Après tale update, roule les conteneurs pour correspondre (étage app + convex)
+tale deploy
+
+# Mets aussi à jour db/proxy (brève coupure pendant qu'ils se recréent)
+tale deploy --stop
 
 # Roule seulement des services spécifiques
-tale deploy --services platform,rag
+tale deploy --services platform
 
-# Aperçu sans changements
+# Aperçu sans changement
 tale deploy --dry-run
 ```
 
@@ -45,7 +63,7 @@ tale deploy --dry-run
 
 ## Le pattern blue-green
 
-Une instance en marche est l'une des deux couleurs (blue ou green) à un instant donné. `tale deploy` monte l'autre couleur, attend qu'elle passe les healthchecks, puis bascule l'upstream de Caddy sur la nouvelle couleur. L'ancienne couleur draine ses requêtes en vol (défaut 30 s), puis sort.
+Une instance en marche est l'une des deux couleurs (blue ou green) à un instant donné. La phase de déploiement monte l'autre couleur, attend qu'elle passe les healthchecks, puis bascule l'upstream de Caddy sur la nouvelle couleur. L'ancienne couleur draine ses requêtes en vol (défaut 30 s), puis sort.
 
 Trois garanties que le pattern te donne :
 
@@ -53,16 +71,21 @@ Trois garanties que le pattern te donne :
 - **Le rollback de patch est une commande.** `tale rollback` redéploie la release patch précédente sur la couleur inactive et rebascule le trafic. Il refuse les downgrades minor et major — ceux-là peuvent laisser la base en avance sur le binaire, et leur chemin de récupération est une restauration de snapshot.
 - **Les healthchecks échoués bloquent la bascule.** Si la nouvelle couleur ne passe pas dans le timeout, le déploiement abandonne et l'ancienne couleur continue à servir.
 
-La procédure complète de déploiement, y compris la phase de cleanup, vit dans `tale --help` ; la recette côté opérateur est `tale deploy && tale status` et confirmation visuelle dans le navigateur.
+La procédure complète de déploiement, y compris la phase de cleanup, vit dans `tale --help` ; la recette côté opérateur est `tale update && tale deploy && tale status` et confirmation visuelle dans le navigateur.
 
 ## Rollback
 
 ```bash
-# Retour à la version patch précédente
+# Retour à la version patch précédente (demande confirmation)
 tale rollback
+
+# Ignorer l'invite en mode non-interactif
+tale rollback --yes
 ```
 
-`tale rollback` est limité aux pas de patch : il ne cible que la version précédente enregistrée, et refuse si cette version ne partage pas `major.minor` avec la plateforme qui tourne. Les releases patch ne portent jamais de migrations, donc redéployer le patch précédent est toujours sûr. Tout ce qui est plus gros peut avoir migré les données vers l'avant — déployer un binaire plus vieux sur des données migrées corrompt l'instance au lieu de la sauver. Pour ces cas, le chemin de récupération est de restaurer le snapshot pré-upgrade et de redéployer la version qui correspond ; le message de refus imprime les commandes exactes, et le walk complet vit dans [Backups et restauration](/fr/self-hosted/operate/backups-and-restore).
+`tale rollback` est limité aux pas de patch : il ne cible que la version précédente enregistrée, et refuse si cette version ne partage pas `major.minor` avec la plateforme qui tourne. Les releases patch ne portent jamais de migrations, donc redéployer le patch précédent est toujours sûr. Tout ce qui est plus gros peut avoir migré les données vers l'avant — déployer un binaire plus vieux sur des données migrées corrompt l'instance au lieu de la sauver. Pour ces cas, le chemin de récupération est de restaurer le snapshot pré-upgrade et de revenir à la version qui lui correspond avec `tale update --version <version>` suivi de `tale deploy --stop` (pour que `db`/`proxy` reculent aussi) ; le message de refus imprime les commandes exactes, et le walk complet vit dans [Backups et restauration](/fr/self-hosted/operate/backups-and-restore).
+
+Comme le rollback démolit les conteneurs en cours d'exécution, la commande prévient de ce qu'elle s'apprête à faire et demande confirmation avant de tirer la moindre image ; passe `--yes` pour ignorer cette invite dans les scripts ou en CI.
 
 ## Compatibilité de versions
 
@@ -74,6 +97,8 @@ Les versions Tale sont en semver. Les règles de compatibilité :
 
 Sauter des versions mineures (passer de 0.9 à 0.11) est supporté tant que les migrations intermédiaires sont encore dans le binaire ; les notes de version le mentionnent quand ce n'est pas le cas.
 
+Pour descendre _délibérément_ d'une version — disons qu'une release minor se comporte mal et que tu as déjà inversé ses migrations — fixe la cible avec `tale update --version <version>`. La commande prévient quand la cible est plus ancienne que la version qui tourne et te rappelle d'inverser d'abord les migrations de données.
+
 ## Où cela s'inscrit
 
 Le flow de montée de version noue chaque autre page d'exploitation — les backups sont ce qui rend une montée de version échouée récupérable, l'observabilité est ce qui te dit que la nouvelle couleur est saine, le durcissement est ce que tu reparcours après une version majeure. Si tu mets en place la CLI pour la première fois, [Installer la CLI tale](/fr/self-hosted/install/cli-install) couvre le setup côté workstation ; si tu prends le pager en plein rollout, [Dépannage](/fr/self-hosted/operate/observability/troubleshooting) nomme les symptômes.
diff --git a/package.json b/package.json
index 9eb82db8d1..b339fdd63b 100644
--- a/package.json
+++ b/package.json
@@ -53,6 +53,7 @@
     "gen:typescript-package": "bun run gen typescript-package",
     "gen:docker-service": "bun run gen docker-service",
     "gen:tool": "bun run gen tool",
+    "generate:icons": "bun scripts/generate-integration-icons.ts",
     "prepare": "bunx husky"
   },
   "dependencies": {
@@ -74,6 +75,8 @@
   "devDependencies": {
     "@commitlint/cli": "20.5.0",
     "@commitlint/config-conventional": "20.5.0",
+    "@iconify-json/logos": "1.2.11",
+    "@iconify/utils": "3.1.3",
     "@storybook/addon-a11y": "10.3.5",
     "@storybook/addon-docs": "10.3.5",
     "@storybook/addon-themes": "10.3.5",
diff --git a/packages/shared/src/classify/combinators.test.ts b/packages/shared/src/classify/combinators.test.ts
index abf19d9a5c..ca35db277e 100644
--- a/packages/shared/src/classify/combinators.test.ts
+++ b/packages/shared/src/classify/combinators.test.ts
@@ -65,6 +65,21 @@ describe('createStreamClassifier (sticky multi-line errors)', () => {
     expect(s('    at handler (chat.ts:42)').kind).toBe('error');
   });
 
+  it('keeps a Convex push error body surfaced even when left-aligned (block error)', () => {
+    const s = createStreamClassifier(classifyConvex);
+    // The header flags a block error; the server message underneath is plain,
+    // left-aligned prose that does NOT look like a stack continuation — it must
+    // still be surfaced (the regression: this body was being dropped as noise).
+    expect(s('✖ Hit an error while pushing:').kind).toBe('error');
+    expect(s('InternalServerError: function timed out').kind).toBe('error');
+    expect(s('Some additional server detail on its own line').kind).toBe(
+      'error',
+    );
+    // A genuine milestone (a retry's progress / functions-ready) ends the block.
+    expect(s('Preparing Convex functions...').kind).toBe('progress');
+    expect(s('Watching for file changes...').kind).toBe('noise');
+  });
+
   it('treats a blank line inside a trace as a continuation (stays sticky)', () => {
     const s = createStreamClassifier(classifyVite);
     s('X [ERROR] boom');
diff --git a/packages/shared/src/classify/combinators.ts b/packages/shared/src/classify/combinators.ts
index 2149796fcc..4f180d17bb 100644
--- a/packages/shared/src/classify/combinators.ts
+++ b/packages/shared/src/classify/combinators.ts
@@ -44,12 +44,28 @@ function looksLikeContinuation(raw: string): boolean {
  */
 export function createStreamClassifier(base: Classifier): Classifier {
   let inError = false;
+  // A "block" error (e.g. a Convex push failure) whose body is left-aligned
+  // prose, not an indented stack: stay surfaced through ANY line until a real
+  // milestone, since the body won't satisfy `looksLikeContinuation`.
+  let inBlock = false;
   return (line) => {
     const result = base(line);
     if (result.kind === 'error') {
       inError = true;
+      if (result.errorBlock) inBlock = true;
       return result;
     }
+    if (inBlock) {
+      // Only a genuine new milestone (a push retry's progress, "N functions
+      // ready", a schema/index line) ends the block; everything else is the
+      // error body and must stay visible.
+      if (result.kind === 'info' || result.kind === 'progress') {
+        inError = false;
+        inBlock = false;
+        return result;
+      }
+      return { ...result, kind: 'error', text: result.text ?? result.raw };
+    }
     if (inError) {
       if (looksLikeContinuation(result.raw)) {
         return { ...result, kind: 'error', text: result.text ?? result.raw };
diff --git a/packages/shared/src/classify/kinds.ts b/packages/shared/src/classify/kinds.ts
index 1239be6fa6..8c79d13506 100644
--- a/packages/shared/src/classify/kinds.ts
+++ b/packages/shared/src/classify/kinds.ts
@@ -27,6 +27,16 @@ export interface ProgressStatus {
 
 export interface ClassifiedLine {
   kind: LineKind;
+  /**
+   * Set on an `error` line whose body is NOT an indented stack trace — a
+   * multi-line tool error printed as left-aligned prose (e.g. a Convex "Hit an
+   * error while pushing:" server message). The stream classifier keeps every
+   * following line surfaced as error until the next real milestone
+   * (`info`/`progress`), instead of dropping the body as noise on the first
+   * non-indented line. Without it those detail lines — the actual cause — are
+   * silently swallowed.
+   */
+  errorBlock?: boolean;
   /** Cleaned display text; omit to hide the line entirely. */
   text?: string;
   status?: ProgressStatus;
diff --git a/packages/shared/src/classify/sources/convex.test.ts b/packages/shared/src/classify/sources/convex.test.ts
index e3d2698855..3b59c4d4ed 100644
--- a/packages/shared/src/classify/sources/convex.test.ts
+++ b/packages/shared/src/classify/sources/convex.test.ts
@@ -22,6 +22,20 @@ describe('classifyConvex', () => {
     expect(c('Error: nope').kind).toBe('error');
   });
 
+  it('flags a push-failure header as a block error (with or without the glyph)', () => {
+    const withGlyph = c('✖ Hit an error while pushing:');
+    expect(withGlyph.kind).toBe('error');
+    expect(withGlyph.errorBlock).toBe(true);
+    expect(withGlyph.text).toBe('Hit an error while pushing:');
+    // Non-TTY CI may strip the leading glyph — still recognised by text.
+    const noGlyph = c('Hit an error while pushing to local deployment');
+    expect(noGlyph.kind).toBe('error');
+    expect(noGlyph.errorBlock).toBe(true);
+    expect(c('Hit an error while running local deployment.').errorBlock).toBe(
+      true,
+    );
+  });
+
   it('surfaces schema/index/provision milestones as info', () => {
     expect(c('✔ Schema validation complete').text).toBe(
       'Schema validation complete',
diff --git a/packages/shared/src/classify/sources/convex.ts b/packages/shared/src/classify/sources/convex.ts
index 7f1e64d9bc..b342b87da4 100644
--- a/packages/shared/src/classify/sources/convex.ts
+++ b/packages/shared/src/classify/sources/convex.ts
@@ -12,6 +12,20 @@ import { noise } from '../kinds';
 
 export const classifyConvex: Classifier = (line) => {
   const body = stripAnsi(line);
+  // Push/deploy failure header. Convex prints the server error on the FOLLOWING
+  // lines as left-aligned prose (not an indented stack), so flag it as a block
+  // error — the stream classifier then keeps that body surfaced until the next
+  // milestone instead of dropping it as noise. Matched by text (not just the ✖
+  // glyph) so a non-TTY CI run, where the glyph may be absent, still surfaces it.
+  if (/Hit an error while (pushing|running)|while pushing to/i.test(body)) {
+    return {
+      kind: 'error',
+      errorBlock: true,
+      text: body.replace(/^[✖✗✘]\s*/, ''),
+      raw: line,
+      source: 'convex',
+    };
+  }
   if (/^[✖✗]|^\s*✘|Uncaught|Error:|error:/.test(body)) {
     return {
       kind: 'error',
diff --git a/packages/shared/src/tux/lines.test.ts b/packages/shared/src/tux/lines.test.ts
index 9ae8097d63..aa277d9ab5 100644
--- a/packages/shared/src/tux/lines.test.ts
+++ b/packages/shared/src/tux/lines.test.ts
@@ -16,6 +16,7 @@ import {
   questionLine,
   rule,
   sourceLine,
+  stepStartLine,
   table,
   warnLine,
 } from './lines.ts';
@@ -61,20 +62,27 @@ afterEach(() => {
 });
 
 describe('line emitters (plain ASCII profile)', () => {
-  it('render bracketed ASCII markers with no escape codes', () => {
+  it('render ASCII markers (info is markerless) with no escape codes', () => {
     doneLine('done');
     infoLine('info');
     questionLine('a question');
     warnLine('warn');
     errorLine('err');
     expect(stdout()).toContain('[ + ] done');
-    expect(stdout()).toContain('[ - ] info');
+    // info is neutral narration — emitted as plain text, with no marker.
+    expect(stdout()).toContain('info');
+    expect(stdout()).not.toContain('[ - ]');
     expect(stdout()).toContain('[ ? ] a question');
     expect(stdout()).toContain('[ ! ] warn');
     expect(stderr()).toContain('[ x ] err');
     expect(stdout() + stderr()).not.toContain('\x1b');
   });
 
+  it('stepStartLine keeps the [ - ] marker (a step start pairs with its terminal)', () => {
+    stepStartLine('Starting X');
+    expect(stdout()).toContain('[ - ] Starting X');
+  });
+
   it('routes errors (and error source lines) to stderr, the rest to stdout', () => {
     doneLine('ok');
     errorLine('boom');
diff --git a/packages/shared/src/tux/lines.ts b/packages/shared/src/tux/lines.ts
index b42009c705..2474d2c324 100644
--- a/packages/shared/src/tux/lines.ts
+++ b/packages/shared/src/tux/lines.ts
@@ -36,8 +36,22 @@ export function doneLine(message: string): void {
   writeLine(`${marker('done')} ${message}`);
 }
 
-/** Neutral information, rendered gray. Suppressed by `--quiet`. */
+/** Neutral information, rendered gray. Suppressed by `--quiet`. Markerless on
+ *  purpose: neutral narration reads as prose, visually distinct from the marked
+ *  `[ ✓ ]`/`[ ! ]`/`[ x ]` events around it. For a step's in-progress line, use
+ *  {@link stepStartLine} — that one keeps a marker. */
 export function infoLine(message: string): void {
+  if (quiet()) return;
+  const p = getPalette();
+  writeLine(`${p.dim}${message}${p.reset}`);
+}
+
+/** A step's in-progress line for non-interactive `runStep` (append-only mode):
+ *  the dim `[ - ]` pending marker that pairs with the step's
+ *  `[ ✓ ]`/`[ ! ]`/`[ x ]` terminal. Unlike {@link infoLine}, a step start is
+ *  half of a pair — not standalone narration — so it keeps the marker.
+ *  Suppressed by `--quiet`. */
+export function stepStartLine(message: string): void {
   if (quiet()) return;
   const p = getPalette();
   writeLine(`${p.dim}${getMarkers().info} ${message}${p.reset}`);
diff --git a/packages/shared/src/tux/step.ts b/packages/shared/src/tux/step.ts
index 9675d8ae98..3d1c17b75c 100644
--- a/packages/shared/src/tux/step.ts
+++ b/packages/shared/src/tux/step.ts
@@ -19,7 +19,7 @@ import {
   getReporterLevel,
   setActiveRegion,
 } from './context';
-import { doneLine, errorLine, infoLine, warnLine } from './lines';
+import { doneLine, errorLine, stepStartLine, warnLine } from './lines';
 
 /**
  * Throw from a `runStep` task to end the step as `[ ! ]` warn (degraded but
@@ -54,7 +54,7 @@ export async function runStep<T>(
 
   // ── Non-interactive: append-only start + result lines, no cursor escapes. ──
   if (!caps.interactive) {
-    infoLine(`${active}...`);
+    stepStartLine(`${active}...`);
     try {
       const result = await task();
       doneLine(`${done} (${elapsed()})`);
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1c02dc6fbf..5240996c67 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -84,6 +84,12 @@
     "./inline-code": "./src/components/data-display/inline-code.tsx",
     "./stat-grid": "./src/components/data-display/stat-grid.tsx",
     "./stat-item": "./src/components/data-display/stat-item.tsx",
+    "./stat-card-grid": "./src/components/data-display/stat-card-grid.tsx",
+    "./trend-indicator": "./src/components/data-display/trend-indicator.tsx",
+    "./sparkline": "./src/components/data-display/sparkline.tsx",
+    "./chart-card": "./src/components/data-display/chart-card.tsx",
+    "./chart-legend": "./src/components/data-display/chart-legend.tsx",
+    "./chart-theme": "./src/lib/chart-theme.ts",
     "./selectable-row": "./src/components/data-display/selectable-row.tsx",
     "./table": "./src/components/data-display/table.tsx",
     "./code-block": "./src/components/data-display/code-block.tsx",
diff --git a/packages/ui/src/components/data-display/chart-card.stories.tsx b/packages/ui/src/components/data-display/chart-card.stories.tsx
new file mode 100644
index 0000000000..730fb701eb
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-card.stories.tsx
@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { BarChart3 } from 'lucide-react';
+
+import { ChartCard } from './chart-card';
+import { ChartLegend } from './chart-legend';
+
+const ChartPlaceholder = () => (
+  <div className="bg-muted/60 text-muted-foreground flex size-full items-center justify-center rounded-md text-xs">
+    chart goes here
+  </div>
+);
+
+const meta: Meta<typeof ChartCard> = {
+  title: 'DataDisplay/ChartCard',
+  component: ChartCard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+The unified chart container: a bordered card with a title + optional info
+tooltip, an optional toolbar (period/metric controls), a fixed-height body that
+swaps between a loading placeholder, an empty state, and the chart, plus an
+optional legend. Replaces the per-feature \`ChartCard\` / \`ChartCardHeader\`
+copies.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ChartCard>;
+
+export const Default: Story = {
+  render: () => (
+    <ChartCard title="Execution trend">
+      <ChartPlaceholder />
+    </ChartCard>
+  ),
+};
+
+export const WithTooltipToolbarAndLegend: Story = {
+  render: () => (
+    <ChartCard
+      title="Usage over time"
+      tooltip="Requests and tokens per day for the selected period."
+      toolbar={
+        <select className="border-border rounded-md border px-2 py-1 text-xs">
+          <option>Last 7 days</option>
+          <option>Last 30 days</option>
+        </select>
+      }
+      legend={
+        <ChartLegend
+          items={[
+            { label: 'Completed', color: 'var(--color-chart-success)' },
+            { label: 'Failed', color: 'var(--color-chart-failure)' },
+          ]}
+        />
+      }
+    >
+      <ChartPlaceholder />
+    </ChartCard>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <ChartCard title="Execution trend" loading>
+      <ChartPlaceholder />
+    </ChartCard>
+  ),
+};
+
+export const Empty: Story = {
+  render: () => (
+    <ChartCard
+      title="Execution trend"
+      isEmpty
+      emptyIcon={BarChart3}
+      emptyTitle="No executions yet"
+      emptyDescription="Runs will appear here once your automations start."
+    >
+      <ChartPlaceholder />
+    </ChartCard>
+  ),
+};
diff --git a/packages/ui/src/components/data-display/chart-card.test.tsx b/packages/ui/src/components/data-display/chart-card.test.tsx
new file mode 100644
index 0000000000..541d152db9
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-card.test.tsx
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
+
+import { ChartCard } from './chart-card';
+
+describe('ChartCard', () => {
+  describe('rendering', () => {
+    it('renders the title and children', () => {
+      render(
+        <ChartCard title="Execution trend">
+          <div>chart body</div>
+        </ChartCard>,
+      );
+      expect(screen.getByText('Execution trend')).toBeInTheDocument();
+      expect(screen.getByText('chart body')).toBeInTheDocument();
+    });
+
+    it('shows a busy placeholder and hides the chart while loading', () => {
+      render(
+        <ChartCard title="Trend" loading>
+          <div>chart body</div>
+        </ChartCard>,
+      );
+      expect(screen.getByRole('status')).toBeInTheDocument();
+      expect(screen.queryByText('chart body')).not.toBeInTheDocument();
+    });
+
+    it('shows the empty state and hides the chart when empty', () => {
+      render(
+        <ChartCard title="Trend" isEmpty emptyTitle="No data yet">
+          <div>chart body</div>
+        </ChartCard>,
+      );
+      expect(screen.getByText('No data yet')).toBeInTheDocument();
+      expect(screen.queryByText('chart body')).not.toBeInTheDocument();
+    });
+
+    it('renders an info tooltip trigger when given a tooltip', () => {
+      render(
+        <ChartCard title="Trend" tooltip="What this shows">
+          <div>chart body</div>
+        </ChartCard>,
+      );
+      expect(
+        screen.getByRole('button', { name: 'What this shows' }),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <ChartCard title="Execution trend" tooltip="Runs per day">
+          <div>chart body</div>
+        </ChartCard>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/data-display/chart-card.tsx b/packages/ui/src/components/data-display/chart-card.tsx
new file mode 100644
index 0000000000..f488490742
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-card.tsx
@@ -0,0 +1,110 @@
+'use client';
+
+import { Info } from 'lucide-react';
+import { type ComponentType, type ReactNode } from 'react';
+
+import { cn } from '../../lib/cn';
+import { EmptyState } from '../feedback/empty-state';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '../overlays/tooltip';
+
+interface ChartCardProps {
+  /** Chart title. */
+  title: string;
+  /** Optional explainer shown via an info tooltip next to the title. */
+  tooltip?: string;
+  /** Right-aligned header controls, e.g. a period or metric selector. */
+  toolbar?: ReactNode;
+  /** Legend rendered below the chart body — typically a `<ChartLegend>`. */
+  legend?: ReactNode;
+  /** When true, show a placeholder block instead of the chart body. */
+  loading?: boolean;
+  /** When true (and not loading), show the empty state instead of children. */
+  isEmpty?: boolean;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  emptyIcon?: ComponentType<{ className?: string }>;
+  /** The chart itself (e.g. a recharts `ResponsiveContainer`). */
+  children: ReactNode;
+  /** Classes for the chart body wrapper — set the height here (e.g. `h-60`). */
+  bodyClassName?: string;
+  className?: string;
+}
+
+/**
+ * The unified chart container: a bordered card with a title + optional info
+ * tooltip, an optional toolbar (period/metric controls), a fixed-height body
+ * that swaps between a loading placeholder, an empty state, and the chart, and
+ * an optional legend below. Replaces the per-feature `ChartCard` /
+ * `ChartCardHeader` reimplementations.
+ */
+export function ChartCard({
+  title,
+  tooltip,
+  toolbar,
+  legend,
+  loading = false,
+  isEmpty = false,
+  emptyTitle,
+  emptyDescription,
+  emptyIcon,
+  children,
+  bodyClassName = 'h-60',
+  className,
+}: ChartCardProps) {
+  return (
+    <div
+      className={cn(
+        'border-border bg-card flex h-full flex-col gap-4 rounded-lg border p-5',
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex min-w-0 items-center gap-1.5">
+          <h3 className="text-foreground truncate text-sm font-semibold">
+            {title}
+          </h3>
+          {tooltip ? (
+            <TooltipProvider>
+              <Tooltip>
+                <TooltipTrigger
+                  type="button"
+                  aria-label={tooltip}
+                  className="text-muted-foreground hover:text-foreground focus-visible:ring-ring inline-flex size-6 shrink-0 items-center justify-center rounded focus-visible:ring-2 focus-visible:outline-none"
+                >
+                  <Info className="size-4" aria-hidden />
+                </TooltipTrigger>
+                <TooltipContent side="top">{tooltip}</TooltipContent>
+              </Tooltip>
+            </TooltipProvider>
+          ) : null}
+        </div>
+        {toolbar ? <div className="shrink-0">{toolbar}</div> : null}
+      </div>
+
+      <div className={cn('w-full', bodyClassName)}>
+        {loading ? (
+          <div
+            className="bg-muted size-full animate-pulse rounded-md motion-reduce:animate-none"
+            role="status"
+            aria-busy
+          />
+        ) : isEmpty ? (
+          <EmptyState
+            icon={emptyIcon}
+            title={emptyTitle ?? title}
+            description={emptyDescription}
+          />
+        ) : (
+          children
+        )}
+      </div>
+
+      {legend && !loading && !isEmpty ? legend : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/data-display/chart-legend.stories.tsx b/packages/ui/src/components/data-display/chart-legend.stories.tsx
new file mode 100644
index 0000000000..dcbf86bfe1
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-legend.stories.tsx
@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ChartLegend } from './chart-legend';
+
+const meta: Meta<typeof ChartLegend> = {
+  title: 'DataDisplay/ChartLegend',
+  component: ChartLegend,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+The shared chart legend row — a swatch + label (+ optional value) per series.
+Colors should come from chart-theme tokens (\`var(--color-chart-*)\`) so the
+legend matches the chart in both themes.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ChartLegend>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Completed', color: 'var(--color-chart-success)' },
+      { label: 'Failed', color: 'var(--color-chart-failure)' },
+    ],
+  },
+};
+
+export const WithValues: Story = {
+  args: {
+    items: [
+      {
+        label: 'Completed',
+        color: 'var(--color-chart-success)',
+        value: '1,284',
+      },
+      { label: 'Failed', color: 'var(--color-chart-failure)', value: '36' },
+      { label: 'Running', color: 'var(--color-chart-neutral)', value: '12' },
+    ],
+  },
+};
+
+export const StartAligned: Story = {
+  args: {
+    align: 'start',
+    items: [
+      { label: 'Requests', color: 'var(--color-chart-1)' },
+      { label: 'Input tokens', color: 'var(--color-chart-2)' },
+      { label: 'Output tokens', color: 'var(--color-chart-3)' },
+    ],
+  },
+};
diff --git a/packages/ui/src/components/data-display/chart-legend.test.tsx b/packages/ui/src/components/data-display/chart-legend.test.tsx
new file mode 100644
index 0000000000..50a15c58ac
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-legend.test.tsx
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
+
+import { ChartLegend } from './chart-legend';
+
+describe('ChartLegend', () => {
+  describe('rendering', () => {
+    it('renders a row per item with its label', () => {
+      render(
+        <ChartLegend
+          items={[
+            { label: 'Completed', color: 'var(--color-chart-success)' },
+            { label: 'Failed', color: 'var(--color-chart-failure)' },
+          ]}
+        />,
+      );
+      expect(screen.getByText('Completed')).toBeInTheDocument();
+      expect(screen.getByText('Failed')).toBeInTheDocument();
+      expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    });
+
+    it('renders optional trailing values', () => {
+      render(
+        <ChartLegend
+          items={[
+            {
+              label: 'Completed',
+              color: 'var(--color-chart-success)',
+              value: '1,284',
+            },
+          ]}
+        />,
+      );
+      expect(screen.getByText('1,284')).toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <ChartLegend
+          items={[
+            { label: 'Completed', color: 'var(--color-chart-success)' },
+            { label: 'Failed', color: 'var(--color-chart-failure)' },
+          ]}
+        />,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/data-display/chart-legend.tsx b/packages/ui/src/components/data-display/chart-legend.tsx
new file mode 100644
index 0000000000..dfa4cb14e4
--- /dev/null
+++ b/packages/ui/src/components/data-display/chart-legend.tsx
@@ -0,0 +1,58 @@
+'use client';
+
+import { type ReactNode } from 'react';
+
+import { cn } from '../../lib/cn';
+
+export interface ChartLegendItem {
+  /** Series name. */
+  label: string;
+  /** Swatch color — a `var(--color-chart-*)` token from chart-theme. */
+  color: string;
+  /** Optional trailing value, e.g. a count. */
+  value?: ReactNode;
+}
+
+interface ChartLegendProps {
+  items: ChartLegendItem[];
+  /** Alignment of the legend row. */
+  align?: 'center' | 'start';
+  className?: string;
+}
+
+/**
+ * The shared chart legend row — a swatch + label (+ optional value) per series.
+ * Previously re-implemented inline in every chart; centralized here so swatch
+ * shape, spacing, and muted-label treatment stay consistent.
+ */
+export function ChartLegend({
+  items,
+  align = 'center',
+  className,
+}: ChartLegendProps) {
+  return (
+    <ul
+      className={cn(
+        'flex flex-wrap gap-x-4 gap-y-1',
+        align === 'center' ? 'justify-center' : 'justify-start',
+        className,
+      )}
+    >
+      {items.map((item) => (
+        <li key={item.label} className="flex items-center gap-2 text-xs">
+          <span
+            className="size-3 shrink-0 rounded-[2px]"
+            style={{ background: item.color }}
+            aria-hidden
+          />
+          <span className="text-muted-foreground">{item.label}</span>
+          {item.value !== undefined ? (
+            <span className="text-foreground font-medium tabular-nums">
+              {item.value}
+            </span>
+          ) : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/packages/ui/src/components/data-display/sparkline.stories.tsx b/packages/ui/src/components/data-display/sparkline.stories.tsx
new file mode 100644
index 0000000000..98e7d0afe8
--- /dev/null
+++ b/packages/ui/src/components/data-display/sparkline.stories.tsx
@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Sparkline } from './sparkline';
+
+const sample = [4, 6, 5, 8, 7, 10, 9, 12, 11, 15];
+
+const meta: Meta<typeof Sparkline> = {
+  title: 'DataDisplay/Sparkline',
+  component: Sparkline,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+A tiny inline trend line — pure SVG, no charting dependency. Normalizes its
+series to its own min/max. Decorative by default (\`aria-hidden\`); pair it with
+a visible value, or pass \`aria-label\` to expose it as an image.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Sparkline>;
+
+export const Default: Story = {
+  args: { data: sample },
+};
+
+export const Filled: Story = {
+  args: { data: sample, filled: true, color: 'var(--color-chart-success)' },
+};
+
+export const Downward: Story = {
+  args: { data: sample.toReversed(), color: 'var(--color-chart-failure)' },
+};
+
+/** A flat series draws a centered horizontal line rather than dividing by zero. */
+export const Flat: Story = {
+  args: { data: [5, 5, 5, 5, 5] },
+};
+
+export const Larger: Story = {
+  args: { data: sample, width: 160, height: 48, filled: true },
+};
diff --git a/packages/ui/src/components/data-display/sparkline.test.tsx b/packages/ui/src/components/data-display/sparkline.test.tsx
new file mode 100644
index 0000000000..0d6d66132e
--- /dev/null
+++ b/packages/ui/src/components/data-display/sparkline.test.tsx
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Sparkline } from './sparkline';
+
+describe('Sparkline', () => {
+  describe('rendering', () => {
+    it('renders a polyline for a multi-point series', () => {
+      const { container } = render(<Sparkline data={[1, 4, 2, 6]} />);
+      const polyline = container.querySelector('polyline');
+      expect(polyline).toBeInTheDocument();
+      // 4 points → 4 coordinate pairs.
+      expect(
+        polyline?.getAttribute('points')?.trim().split(/\s+/),
+      ).toHaveLength(4);
+    });
+
+    it('is decorative (aria-hidden) by default', () => {
+      const { container } = render(<Sparkline data={[1, 2, 3]} />);
+      const svg = container.querySelector('svg');
+      expect(svg).toHaveAttribute('aria-hidden', 'true');
+      expect(svg).not.toHaveAttribute('role', 'img');
+    });
+
+    it('exposes itself as an image when given an aria-label', () => {
+      const { container } = render(
+        <Sparkline data={[1, 2, 3]} aria-label="Runs trend" />,
+      );
+      const svg = container.querySelector('svg');
+      expect(svg).toHaveAttribute('role', 'img');
+      expect(svg).toHaveAttribute('aria-label', 'Runs trend');
+    });
+
+    it('renders an area polygon when filled', () => {
+      const { container } = render(<Sparkline data={[1, 2, 3]} filled />);
+      expect(container.querySelector('polygon')).toBeInTheDocument();
+    });
+
+    it('renders nothing drawable for an empty series', () => {
+      const { container } = render(<Sparkline data={[]} />);
+      expect(container.querySelector('polyline')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit (decorative)', async () => {
+      const { container } = render(<Sparkline data={[1, 4, 2, 6]} />);
+      await checkAccessibility(container);
+    });
+
+    it('passes axe audit (labelled image)', async () => {
+      const { container } = render(
+        <Sparkline data={[1, 4, 2, 6]} aria-label="Runs trend" />,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/data-display/sparkline.tsx b/packages/ui/src/components/data-display/sparkline.tsx
new file mode 100644
index 0000000000..2ed6e2d766
--- /dev/null
+++ b/packages/ui/src/components/data-display/sparkline.tsx
@@ -0,0 +1,96 @@
+'use client';
+
+import { cn } from '../../lib/cn';
+
+interface SparklineProps {
+  /** Series of values, oldest → newest. */
+  data: number[];
+  width?: number;
+  height?: number;
+  /** Stroke color — defaults to the categorical chart-1 token. */
+  color?: string;
+  /** Fill the area under the line with a faint tint of the stroke color. */
+  filled?: boolean;
+  /**
+   * Accessible label. When provided the SVG is exposed to screen readers as an
+   * image; otherwise it is decorative (`aria-hidden`) — pair it with a visible
+   * value (e.g. inside a `MetricCard`).
+   */
+  'aria-label'?: string;
+  className?: string;
+}
+
+/**
+ * A tiny inline trend line — pure SVG, no charting dependency, so it stays
+ * cheap and embeddable (e.g. in a `MetricCard`). Normalizes the series to its
+ * own min/max and draws a single polyline; with `filled` it adds a soft area.
+ */
+export function Sparkline({
+  data,
+  width = 72,
+  height = 22,
+  color = 'var(--color-chart-1)',
+  filled = false,
+  'aria-label': ariaLabel,
+  className,
+}: SparklineProps) {
+  const pad = 1.5; // keep the stroke off the edges
+  const usableW = width - pad * 2;
+  const usableH = height - pad * 2;
+
+  // Need at least two points to draw a line.
+  const points =
+    data.length >= 2 ? data : data.length === 1 ? [data[0], data[0]] : [];
+  const min = points.length ? Math.min(...points) : 0;
+  const max = points.length ? Math.max(...points) : 0;
+  const range = max - min || 1; // avoid /0 on a flat series
+
+  const coords = points.map((v, i) => {
+    const x =
+      pad + (points.length === 1 ? 0 : (i / (points.length - 1)) * usableW);
+    // Invert Y so larger values sit higher.
+    const y = pad + (1 - (v - min) / range) * usableH;
+    return `${x.toFixed(2)},${y.toFixed(2)}`;
+  });
+
+  const linePath = coords.join(' ');
+  const areaPath = coords.length
+    ? `${pad},${height - pad} ${linePath} ${width - pad},${height - pad}`
+    : '';
+
+  const decorative = !ariaLabel;
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      className={cn('overflow-visible', className)}
+      role={decorative ? undefined : 'img'}
+      aria-label={ariaLabel}
+      aria-hidden={decorative || undefined}
+      preserveAspectRatio="none"
+    >
+      {coords.length > 0 && (
+        <>
+          {filled && (
+            <polygon
+              points={areaPath}
+              fill={color}
+              fillOpacity={0.12}
+              stroke="none"
+            />
+          )}
+          <polyline
+            points={linePath}
+            fill="none"
+            stroke={color}
+            strokeWidth={1.5}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </>
+      )}
+    </svg>
+  );
+}
diff --git a/packages/ui/src/components/data-display/stat-card-grid.stories.tsx b/packages/ui/src/components/data-display/stat-card-grid.stories.tsx
new file mode 100644
index 0000000000..115055d559
--- /dev/null
+++ b/packages/ui/src/components/data-display/stat-card-grid.stories.tsx
@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Info } from 'lucide-react';
+
+import { Skeletonize } from '../feedback/skeleton-context';
+import { StatCard, StatCardGrid } from './stat-card-grid';
+
+const meta: Meta<typeof StatCardGrid> = {
+  title: 'DataDisplay/StatCardGrid',
+  component: StatCardGrid,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+A bordered, divided strip of headline metrics. Pass already formatted/translated
+strings; each \`StatCard\` masks its value while a surrounding \`<Skeletonize loading>\`
+is active so the strip height never shifts.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof StatCardGrid>;
+
+/** The default 4-column summary strip. */
+export const FourColumn: Story = {
+  render: () => (
+    <StatCardGrid>
+      <StatCard label="Total requests" value="12,480" />
+      <StatCard label="Total tokens" value="3.2M" />
+      <StatCard label="Total cost" value="$184.20" />
+      <StatCard
+        label="Active users"
+        value="312"
+        tooltip={
+          <Info className="ml-1 inline-block size-3 align-text-bottom" />
+        }
+      />
+    </StatCardGrid>
+  ),
+};
+
+/** Two metrics. */
+export const TwoColumn: Story = {
+  render: () => (
+    <StatCardGrid cols={2}>
+      <StatCard label="Success rate" value="98.6%" />
+      <StatCard label="Avg duration" value="1.4s" />
+    </StatCardGrid>
+  ),
+};
+
+/** A wide `colSpan={2}` cell with extra content under the value (e.g. a bar). */
+export const WithColSpan: Story = {
+  render: () => (
+    <StatCardGrid>
+      <StatCard label="Sentiment" value="Positive" colSpan={2}>
+        <div className="bg-bg-muted mt-2 h-2 w-full overflow-hidden rounded-full">
+          <div className="bg-success h-full w-3/4" />
+        </div>
+      </StatCard>
+      <StatCard label="Helpful" value="248" />
+      <StatCard label="Not helpful" value="36" />
+    </StatCardGrid>
+  ),
+};
+
+/** While loading, every value masks to its line box — no layout shift. */
+export const Loading: Story = {
+  render: () => (
+    <Skeletonize loading>
+      <StatCardGrid>
+        <StatCard label="Total requests" value="12,480" />
+        <StatCard label="Total tokens" value="3.2M" loadingWidth="w-20" />
+        <StatCard label="Total cost" value="$184.20" />
+        <StatCard label="Active users" value="312" />
+      </StatCardGrid>
+    </Skeletonize>
+  ),
+};
diff --git a/packages/ui/src/components/data-display/stat-card-grid.test.tsx b/packages/ui/src/components/data-display/stat-card-grid.test.tsx
new file mode 100644
index 0000000000..db7800df14
--- /dev/null
+++ b/packages/ui/src/components/data-display/stat-card-grid.test.tsx
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
+
+import { Skeletonize } from '../feedback/skeleton-context';
+import { StatCard, StatCardGrid } from './stat-card-grid';
+
+describe('StatCardGrid', () => {
+  describe('rendering', () => {
+    it('renders label and value', () => {
+      render(
+        <StatCardGrid>
+          <StatCard label="Requests" value="42" />
+        </StatCardGrid>,
+      );
+      expect(screen.getByText('Requests')).toBeInTheDocument();
+      expect(screen.getByText('42')).toBeInTheDocument();
+    });
+
+    it('defaults to a 4-column strip and applies className', () => {
+      const { container } = render(
+        <StatCardGrid className="custom-class">
+          <StatCard label="A" value="1" />
+        </StatCardGrid>,
+      );
+      expect(container.firstChild).toHaveClass(
+        'md:grid-cols-4',
+        'custom-class',
+      );
+    });
+
+    it('applies cols=2', () => {
+      const { container } = render(
+        <StatCardGrid cols={2}>
+          <StatCard label="A" value="1" />
+        </StatCardGrid>,
+      );
+      expect(container.firstChild).toHaveClass('md:grid-cols-2');
+    });
+
+    it('spans both columns for colSpan=2', () => {
+      const { container } = render(
+        <StatCardGrid>
+          <StatCard label="Wide" value="x" colSpan={2} />
+        </StatCardGrid>,
+      );
+      expect(container.querySelector('.col-span-2')).toBeInTheDocument();
+    });
+
+    it('masks the value while loading', () => {
+      render(
+        <Skeletonize loading>
+          <StatCardGrid>
+            <StatCard label="Requests" value="42" />
+          </StatCardGrid>
+        </Skeletonize>,
+      );
+      // Label still renders; the numeric value is masked by the skeleton box.
+      expect(screen.getByText('Requests')).toBeInTheDocument();
+      expect(screen.queryByText('42')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <StatCardGrid>
+          <StatCard label="Revenue" value="$12,400" />
+          <StatCard label="Orders" value="342" />
+        </StatCardGrid>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/data-display/stat-card-grid.tsx b/packages/ui/src/components/data-display/stat-card-grid.tsx
new file mode 100644
index 0000000000..424236b4bf
--- /dev/null
+++ b/packages/ui/src/components/data-display/stat-card-grid.tsx
@@ -0,0 +1,109 @@
+'use client';
+
+import { cva, type VariantProps } from 'class-variance-authority';
+import { type ReactNode } from 'react';
+
+import { cn } from '../../lib/cn';
+import { SkeletonBox } from '../feedback/skeleton';
+import { useSkeleton } from '../feedback/skeleton-context';
+import { Text } from '../typography/text';
+
+/**
+ * StatCardGrid / StatCard — the bordered, divided strip of headline metrics used
+ * across analytics and audit summaries (total requests, success rate, …). One
+ * presentational primitive replacing four hand-rolled copies; pass already
+ * formatted/translated `label`/`value` strings (no i18n inside).
+ *
+ * Distinct from `@tale/ui/stat-grid` (a borderless `<dl>` of label/value pairs).
+ * Each `StatCard` masks its value to its own line box while a surrounding
+ * `<Skeletonize loading>` is active, so the strip's height is identical loading
+ * vs loaded.
+ */
+const statCardGridVariants = cva(
+  'border-border-base divide-border-base grid grid-cols-2 divide-y rounded-lg border md:divide-x md:divide-y-0',
+  {
+    variants: {
+      cols: {
+        2: 'md:grid-cols-2',
+        4: 'md:grid-cols-4',
+      },
+    },
+    defaultVariants: { cols: 4 },
+  },
+);
+
+export interface StatCardGridProps extends VariantProps<
+  typeof statCardGridVariants
+> {
+  children: ReactNode;
+  className?: string;
+}
+
+export function StatCardGrid({ cols, children, className }: StatCardGridProps) {
+  return (
+    <div className={cn(statCardGridVariants({ cols }), className)}>
+      {children}
+    </div>
+  );
+}
+
+export interface StatCardProps {
+  label: ReactNode;
+  value: ReactNode;
+  /**
+   * Optional node rendered inline after the label (e.g. an info glyph wrapped in
+   * a tooltip). Kept as a node so the caller owns tooltip + i18n.
+   */
+  tooltip?: ReactNode;
+  /** Span both columns (e.g. a wider sentiment cell). */
+  colSpan?: 1 | 2;
+  /** Width of the skeleton placeholder while loading (default `w-16`). */
+  loadingWidth?: string;
+  /** Extra classes on the value (accent colors, larger size). */
+  valueClassName?: string;
+  /** Extra content rendered under the value (e.g. a sentiment bar). */
+  children?: ReactNode;
+  className?: string;
+}
+
+export function StatCard({
+  label,
+  value,
+  tooltip,
+  colSpan,
+  loadingWidth = 'w-16',
+  valueClassName,
+  children,
+  className,
+}: StatCardProps) {
+  const loading = useSkeleton();
+  return (
+    <div
+      className={cn(
+        'flex flex-1 flex-col gap-1 p-5',
+        colSpan === 2 && 'col-span-2',
+        className,
+      )}
+    >
+      <Text className="text-fg-muted text-sm">
+        {label}
+        {tooltip}
+      </Text>
+      <Text
+        className={cn(
+          'text-fg-base font-mono text-2xl font-semibold',
+          valueClassName,
+        )}
+      >
+        {loading ? (
+          <SkeletonBox>
+            <span className={cn('my-0.5 inline-block h-7', loadingWidth)} />
+          </SkeletonBox>
+        ) : (
+          value
+        )}
+      </Text>
+      {children}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/data-display/trend-indicator.stories.tsx b/packages/ui/src/components/data-display/trend-indicator.stories.tsx
new file mode 100644
index 0000000000..68c6d54914
--- /dev/null
+++ b/packages/ui/src/components/data-display/trend-indicator.stories.tsx
@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { StatCard, StatCardGrid } from './stat-card-grid';
+import { TrendIndicator } from './trend-indicator';
+
+const meta: Meta<typeof TrendIndicator> = {
+  title: 'DataDisplay/TrendIndicator',
+  component: TrendIndicator,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+A compact period-over-period delta: a direction arrow + signed percentage,
+sentiment-colored (green = good, red = bad). Pass the current \`value\` and the
+\`previous\` value — the percentage and the "no prior data → neutral" rule are
+computed inside (see \`computeTrend\`). Use \`inverted\` for metrics where a
+decrease is good (cost, failures, latency).
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TrendIndicator>;
+
+/** An increase on a normal metric reads as positive (green up). */
+export const Up: Story = {
+  args: { value: 1284, previous: 1100, comparisonLabel: 'vs last period' },
+};
+
+/** A decrease on a normal metric reads as negative (red down). */
+export const Down: Story = {
+  args: { value: 920, previous: 1100, comparisonLabel: 'vs last period' },
+};
+
+/** With `inverted`, a decrease is good — e.g. cost or failures going down. */
+export const InvertedGood: Story = {
+  args: {
+    value: 42,
+    previous: 60,
+    inverted: true,
+    comparisonLabel: 'vs last period',
+  },
+};
+
+/** No prior period (new org / first window) renders a neutral dash, never ±100%. */
+export const NoPriorData: Story = {
+  args: { value: 12, previous: 0, comparisonLabel: 'vs last period' },
+};
+
+/** In context: deltas sit under the value inside a `StatCard`. */
+export const InStatCard: Story = {
+  render: () => (
+    <div className="w-[40rem]">
+      <StatCardGrid cols={2}>
+        <StatCard label="Total runs" value="1,284">
+          <TrendIndicator
+            value={1284}
+            previous={1100}
+            comparisonLabel="vs last period"
+          />
+        </StatCard>
+        <StatCard label="Failed runs" value="36">
+          <TrendIndicator
+            value={36}
+            previous={58}
+            inverted
+            comparisonLabel="vs last period"
+          />
+        </StatCard>
+      </StatCardGrid>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/data-display/trend-indicator.test.tsx b/packages/ui/src/components/data-display/trend-indicator.test.tsx
new file mode 100644
index 0000000000..a190a7e799
--- /dev/null
+++ b/packages/ui/src/components/data-display/trend-indicator.test.tsx
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
+
+import { computeTrend, TrendIndicator } from './trend-indicator';
+
+describe('computeTrend', () => {
+  it('computes a positive percentage for an increase', () => {
+    expect(computeTrend(120, 100)).toEqual({
+      deltaPct: 20,
+      direction: 'up',
+      isComputable: true,
+    });
+  });
+
+  it('computes a negative percentage for a decrease', () => {
+    expect(computeTrend(80, 100)).toEqual({
+      deltaPct: -20,
+      direction: 'down',
+      isComputable: true,
+    });
+  });
+
+  it('reports a flat, computable trend for an unchanged value', () => {
+    expect(computeTrend(100, 100)).toEqual({
+      deltaPct: 0,
+      direction: 'flat',
+      isComputable: true,
+    });
+  });
+
+  it('treats 0 → 0 as flat and computable', () => {
+    expect(computeTrend(0, 0)).toEqual({
+      deltaPct: 0,
+      direction: 'flat',
+      isComputable: true,
+    });
+  });
+
+  it('treats 0 → n as upward but NOT computable (no finite percentage)', () => {
+    expect(computeTrend(5, 0)).toEqual({
+      deltaPct: null,
+      direction: 'up',
+      isComputable: false,
+    });
+  });
+
+  it('treats a missing previous value as not computable', () => {
+    expect(computeTrend(5, undefined)).toEqual({
+      deltaPct: null,
+      direction: 'flat',
+      isComputable: false,
+    });
+    expect(computeTrend(5, null)).toEqual({
+      deltaPct: null,
+      direction: 'flat',
+      isComputable: false,
+    });
+  });
+});
+
+describe('TrendIndicator', () => {
+  describe('rendering', () => {
+    it('renders the percentage and comparison label', () => {
+      render(
+        <TrendIndicator
+          value={120}
+          previous={100}
+          comparisonLabel="vs prior"
+        />,
+      );
+      expect(screen.getByText('+20%')).toBeInTheDocument();
+      expect(screen.getByText('vs prior')).toBeInTheDocument();
+    });
+
+    it('colors a normal increase as positive (success)', () => {
+      const { container } = render(
+        <TrendIndicator value={120} previous={100} />,
+      );
+      expect(
+        container.querySelector('.text-chart-success'),
+      ).toBeInTheDocument();
+    });
+
+    it('flips sentiment color when inverted (an increase is bad)', () => {
+      const { container } = render(
+        <TrendIndicator value={120} previous={100} inverted />,
+      );
+      expect(
+        container.querySelector('.text-chart-failure'),
+      ).toBeInTheDocument();
+    });
+
+    it('renders a neutral dash when there is no prior data', () => {
+      const { container } = render(<TrendIndicator value={12} previous={0} />);
+      expect(screen.getByText('—')).toBeInTheDocument();
+      expect(
+        container.querySelector('.text-muted-foreground'),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <TrendIndicator
+          value={120}
+          previous={100}
+          comparisonLabel="vs prior"
+        />,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/data-display/trend-indicator.tsx b/packages/ui/src/components/data-display/trend-indicator.tsx
new file mode 100644
index 0000000000..75938a61d3
--- /dev/null
+++ b/packages/ui/src/components/data-display/trend-indicator.tsx
@@ -0,0 +1,131 @@
+'use client';
+
+import { ArrowDown, ArrowUp, Minus } from 'lucide-react';
+
+import { cn } from '../../lib/cn';
+import { SkeletonBox } from '../feedback/skeleton';
+
+export type TrendDirection = 'up' | 'down' | 'flat';
+
+export interface TrendResult {
+  /** Signed percentage change, or `null` when it can't be computed. */
+  deltaPct: number | null;
+  /** Direction of the change relative to the previous value. */
+  direction: TrendDirection;
+  /**
+   * Whether a meaningful percentage is available. False when there is no prior
+   * period to compare against (new org / first period) — the indicator renders
+   * a neutral dash rather than a misleading "+100%" / "−100%".
+   */
+  isComputable: boolean;
+}
+
+/**
+ * Pure period-over-period delta. The single place this math lives, so the
+ * "no prior data → neutral, not ±100%" rule is enforced once and unit-tested.
+ *
+ * - `previous` undefined/null → not computable (no comparison exists yet).
+ * - `previous === 0`: a 0→0 move is flat; a 0→n move is real growth but has no
+ *   finite percentage, so it's reported as `up` + not computable.
+ */
+export function computeTrend(
+  value: number,
+  previous: number | null | undefined,
+): TrendResult {
+  if (previous === null || previous === undefined) {
+    return { deltaPct: null, direction: 'flat', isComputable: false };
+  }
+  if (previous === 0) {
+    if (value === 0)
+      return { deltaPct: 0, direction: 'flat', isComputable: true };
+    return { deltaPct: null, direction: 'up', isComputable: false };
+  }
+  const deltaPct = ((value - previous) / previous) * 100;
+  const direction: TrendDirection =
+    deltaPct > 0 ? 'up' : deltaPct < 0 ? 'down' : 'flat';
+  return { deltaPct, direction, isComputable: true };
+}
+
+/** Format a signed percentage: whole numbers ≥10, one decimal below. */
+function formatDeltaPct(pct: number): string {
+  const sign = pct > 0 ? '+' : pct < 0 ? '−' : '';
+  const abs = Math.abs(pct);
+  const rounded = abs >= 10 ? Math.round(abs) : Math.round(abs * 10) / 10;
+  return `${sign}${rounded}%`;
+}
+
+interface TrendIndicatorProps {
+  /** Current-period value. */
+  value: number;
+  /** Previous-period value to compare against. */
+  previous: number | null | undefined;
+  /**
+   * When true, a DECREASE is good (cost, failures, latency, intervention rate):
+   * down → success color, up → failure color. The arrow still points with the
+   * raw direction; only the sentiment color flips.
+   */
+  inverted?: boolean;
+  /** Trailing context, e.g. "vs last period". Rendered muted. */
+  comparisonLabel?: string;
+  className?: string;
+}
+
+const DIRECTION_ICON = {
+  up: ArrowUp,
+  down: ArrowDown,
+  flat: Minus,
+} as const;
+
+/**
+ * A compact period-over-period delta badge: a direction arrow + signed
+ * percentage, sentiment-colored (green = good, red = bad) with `inverted` for
+ * metrics where down is good. Skeleton-aware — masks itself inside a
+ * `<Skeletonize loading>`.
+ */
+export function TrendIndicator({
+  value,
+  previous,
+  inverted = false,
+  comparisonLabel,
+  className,
+}: TrendIndicatorProps) {
+  const { deltaPct, direction, isComputable } = computeTrend(value, previous);
+
+  // Sentiment: up is good unless inverted; flat/indeterminate is neutral.
+  const sentiment: 'good' | 'bad' | 'neutral' =
+    direction === 'flat' || !isComputable
+      ? 'neutral'
+      : (direction === 'up') !== inverted
+        ? 'good'
+        : 'bad';
+
+  const Icon = DIRECTION_ICON[isComputable ? direction : 'flat'];
+
+  const colorClass =
+    sentiment === 'good'
+      ? 'text-chart-success'
+      : sentiment === 'bad'
+        ? 'text-chart-failure'
+        : 'text-muted-foreground';
+
+  return (
+    <SkeletonBox>
+      <span
+        className={cn(
+          'inline-flex items-center gap-1 text-xs font-medium tabular-nums',
+          className,
+        )}
+      >
+        <span className={cn('inline-flex items-center gap-0.5', colorClass)}>
+          <Icon className="size-3" aria-hidden />
+          {isComputable && deltaPct !== null ? formatDeltaPct(deltaPct) : '—'}
+        </span>
+        {comparisonLabel ? (
+          <span className="text-muted-foreground font-normal">
+            {comparisonLabel}
+          </span>
+        ) : null}
+      </span>
+    </SkeletonBox>
+  );
+}
diff --git a/packages/ui/src/components/feedback/accordion.stories.tsx b/packages/ui/src/components/feedback/accordion.stories.tsx
new file mode 100644
index 0000000000..815eab64eb
--- /dev/null
+++ b/packages/ui/src/components/feedback/accordion.stories.tsx
@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Accordion, AccordionItem } from './accordion';
+
+const meta: Meta<typeof Accordion> = {
+  title: 'Feedback/Accordion',
+  component: Accordion,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Accordion>;
+
+const items = [
+  {
+    id: 'what',
+    q: 'What is Tale?',
+    a: 'An AI workforce platform for your company.',
+  },
+  {
+    id: 'who',
+    q: 'Who is it for?',
+    a: 'Teams who want to delegate work to agents.',
+  },
+  {
+    id: 'how',
+    q: 'How do I start?',
+    a: 'Run the setup wizard and connect a provider.',
+  },
+];
+
+/** `single` (default) — opening one item closes the others. */
+export const Single: Story = {
+  render: () => (
+    <div className="max-w-xl">
+      <Accordion type="single" defaultOpen="what">
+        {items.map((it) => (
+          <AccordionItem key={it.id} id={it.id} question={it.q}>
+            {it.a}
+          </AccordionItem>
+        ))}
+      </Accordion>
+    </div>
+  ),
+};
+
+/** `multiple` — items open and close independently. */
+export const Multiple: Story = {
+  render: () => (
+    <div className="max-w-xl">
+      <Accordion type="multiple" defaultOpen={['what', 'how']}>
+        {items.map((it) => (
+          <AccordionItem key={it.id} id={it.id} question={it.q}>
+            {it.a}
+          </AccordionItem>
+        ))}
+      </Accordion>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/feedback/accordion.test.tsx b/packages/ui/src/components/feedback/accordion.test.tsx
new file mode 100644
index 0000000000..ebe0498312
--- /dev/null
+++ b/packages/ui/src/components/feedback/accordion.test.tsx
@@ -0,0 +1,24 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Accordion, AccordionItem } from './accordion';
+
+describe('Accordion', () => {
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <Accordion type="single" defaultOpen="a">
+          <AccordionItem id="a" question="First question">
+            First answer.
+          </AccordionItem>
+          <AccordionItem id="b" question="Second question">
+            Second answer.
+          </AccordionItem>
+        </Accordion>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/feedback/empty-state.tsx b/packages/ui/src/components/feedback/empty-state.tsx
index 624515d245..7c1d27a89b 100644
--- a/packages/ui/src/components/feedback/empty-state.tsx
+++ b/packages/ui/src/components/feedback/empty-state.tsx
@@ -9,7 +9,8 @@ import { cn } from '../../lib/cn';
 interface EmptyStateProps {
   icon?: ComponentType<{ className?: string }>;
   title: string;
-  description?: string;
+  /** Plain text or rich content (links, doc CTAs). Rendered in a `<div>`. */
+  description?: ReactNode;
   action?: ReactNode;
   className?: string;
 }
@@ -35,7 +36,9 @@ export function EmptyState({
         {title}
       </Heading>
       {description && (
-        <Text variant="muted" className="mt-1 max-w-[20rem]">
+        // `as="div"` (not the default `<p>`): descriptions may carry rich block
+        // content (links, doc CTAs), and a `<div>` inside a `<p>` is invalid.
+        <Text as="div" variant="muted" className="mt-1 max-w-80">
           {description}
         </Text>
       )}
diff --git a/packages/ui/src/components/forms/checkbox.stories.tsx b/packages/ui/src/components/forms/checkbox.stories.tsx
new file mode 100644
index 0000000000..2d77b11ea9
--- /dev/null
+++ b/packages/ui/src/components/forms/checkbox.stories.tsx
@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Skeletonize } from '../feedback/skeleton-context';
+import { Checkbox } from './checkbox';
+import { Label } from './label';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Forms/Checkbox',
+  component: Checkbox,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Unchecked: Story = {
+  render: () => <Checkbox aria-label="Accept terms" />,
+};
+
+export const Checked: Story = {
+  render: () => <Checkbox defaultChecked aria-label="Accept terms" />,
+};
+
+export const Indeterminate: Story = {
+  render: () => <Checkbox checked="indeterminate" aria-label="Select all" />,
+};
+
+export const Disabled: Story = {
+  render: () => <Checkbox disabled aria-label="Disabled" />,
+};
+
+export const WithLabel: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="terms" />
+      <Label htmlFor="terms">Accept terms and conditions</Label>
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <Skeletonize loading>
+      <Checkbox aria-label="Loading" />
+    </Skeletonize>
+  ),
+};
diff --git a/packages/ui/src/components/forms/checkbox.test.tsx b/packages/ui/src/components/forms/checkbox.test.tsx
new file mode 100644
index 0000000000..0a14d9cc15
--- /dev/null
+++ b/packages/ui/src/components/forms/checkbox.test.tsx
@@ -0,0 +1,26 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Checkbox } from './checkbox';
+import { Label } from './label';
+
+describe('Checkbox', () => {
+  describe('accessibility', () => {
+    it('passes axe audit with an aria-label', async () => {
+      const { container } = render(<Checkbox aria-label="Accept terms" />);
+      await checkAccessibility(container);
+    });
+
+    it('passes axe audit when paired with a Label', async () => {
+      const { container } = render(
+        <div className="flex items-center gap-2">
+          <Checkbox id="terms" />
+          <Label htmlFor="terms">Accept terms</Label>
+        </div>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/forms/field.stories.tsx b/packages/ui/src/components/forms/field.stories.tsx
new file mode 100644
index 0000000000..f7fb693575
--- /dev/null
+++ b/packages/ui/src/components/forms/field.stories.tsx
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Field } from './field';
+import { Input } from './input';
+
+const meta: Meta<typeof Field> = {
+  title: 'Forms/Field',
+  component: Field,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Field>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Field label="Workspace name" htmlFor="ws">
+        <Input id="ws" placeholder="Acme Inc." />
+      </Field>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Field
+        label="Email"
+        htmlFor="email"
+        description="We'll only use this to send sign-in links."
+      >
+        <Input id="email" type="email" placeholder="you@example.com" />
+      </Field>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Field label="API key" htmlFor="key" required>
+        <Input id="key" placeholder="sk-…" />
+      </Field>
+    </div>
+  ),
+};
+
+/** The error message is wired via `aria-describedby` + `aria-invalid` and `role="alert"`. */
+export const WithError: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Field label="Email" htmlFor="email-err" error="Enter a valid email.">
+        <Input id="email-err" defaultValue="not-an-email" />
+      </Field>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/forms/field.test.tsx b/packages/ui/src/components/forms/field.test.tsx
new file mode 100644
index 0000000000..32f4178c14
--- /dev/null
+++ b/packages/ui/src/components/forms/field.test.tsx
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Field } from './field';
+import { Input } from './input';
+
+describe('Field', () => {
+  it('wires the description to the control via aria-describedby', () => {
+    const { getByRole } = render(
+      <Field label="Email" htmlFor="email" description="No spam.">
+        <Input id="email" />
+      </Field>,
+    );
+    const input = getByRole('textbox');
+    const describedBy = input.getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+  });
+
+  it('sets aria-invalid and role=alert when an error is present', () => {
+    const { getByRole } = render(
+      <Field label="Email" htmlFor="email" error="Required">
+        <Input id="email" />
+      </Field>,
+    );
+    expect(getByRole('textbox')).toHaveAttribute('aria-invalid', 'true');
+    expect(getByRole('alert')).toHaveTextContent('Required');
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit with label + description', async () => {
+      const { container } = render(
+        <Field label="Email" htmlFor="email" description="No spam.">
+          <Input id="email" />
+        </Field>,
+      );
+      await checkAccessibility(container);
+    });
+
+    it('passes axe audit in the error state', async () => {
+      const { container } = render(
+        <Field label="Email" htmlFor="email" error="Enter a valid email.">
+          <Input id="email" defaultValue="x" />
+        </Field>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/forms/input.stories.tsx b/packages/ui/src/components/forms/input.stories.tsx
new file mode 100644
index 0000000000..7dffd6f2a9
--- /dev/null
+++ b/packages/ui/src/components/forms/input.stories.tsx
@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Skeletonize } from '../feedback/skeleton-context';
+import { Input } from './input';
+
+const meta: Meta<typeof Input> = {
+  title: 'Forms/Input',
+  component: Input,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Input>;
+
+export const Default: Story = {
+  args: { placeholder: 'you@example.com' },
+  render: (args) => (
+    <div className="max-w-sm">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const WithValue: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Input defaultValue="Acme Inc." />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Input placeholder="Disabled" disabled />
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Input defaultValue="not-an-email" aria-invalid aria-label="Email" />
+    </div>
+  ),
+};
+
+/** Inside a `<Skeletonize loading>` the field masks itself at its exact size. */
+export const Loading: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Skeletonize loading>
+        <Input placeholder="Loading" />
+      </Skeletonize>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/forms/input.tsx b/packages/ui/src/components/forms/input.tsx
index 2a7e6b8ed9..7e31049941 100644
--- a/packages/ui/src/components/forms/input.tsx
+++ b/packages/ui/src/components/forms/input.tsx
@@ -17,7 +17,7 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(
         ref={ref}
         type={type}
         className={cn(
-          'h-10 w-full rounded-lg border px-3 py-2 text-base md:text-sm',
+          'h-9 w-full rounded-lg border px-3 py-2 text-base md:text-sm',
           'border-[color:var(--color-border-input)] bg-[color:var(--color-bg-base)] text-[color:var(--color-fg-base)] placeholder:text-[color:var(--color-fg-subtle)] shadow-sm transition-colors',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--color-accent-base)]/30 focus-visible:border-[color:var(--color-accent-base)]',
           'disabled:cursor-not-allowed disabled:opacity-50',
diff --git a/packages/ui/src/components/forms/label.stories.tsx b/packages/ui/src/components/forms/label.stories.tsx
new file mode 100644
index 0000000000..69198663a6
--- /dev/null
+++ b/packages/ui/src/components/forms/label.stories.tsx
@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Input } from './input';
+import { Label } from './label';
+
+const meta: Meta<typeof Label> = {
+  title: 'Forms/Label',
+  component: Label,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Label>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="flex max-w-sm flex-col gap-2">
+      <Label htmlFor="name">Name</Label>
+      <Input id="name" placeholder="Acme Inc." />
+    </div>
+  ),
+};
+
+/** A label associates with its control via `htmlFor`, so clicking it focuses the input. */
+export const WithRequiredMarker: Story = {
+  render: () => (
+    <div className="flex max-w-sm flex-col gap-2">
+      <Label htmlFor="email">
+        Email
+        <span className="ml-0.5 text-[color:var(--color-danger)]" aria-hidden>
+          *
+        </span>
+      </Label>
+      <Input id="email" type="email" placeholder="you@example.com" />
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/forms/label.test.tsx b/packages/ui/src/components/forms/label.test.tsx
new file mode 100644
index 0000000000..04b5ba1e52
--- /dev/null
+++ b/packages/ui/src/components/forms/label.test.tsx
@@ -0,0 +1,21 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Input } from './input';
+import { Label } from './label';
+
+describe('Label', () => {
+  describe('accessibility', () => {
+    it('passes axe audit when associated with a control', async () => {
+      const { container } = render(
+        <>
+          <Label htmlFor="name">Name</Label>
+          <Input id="name" />
+        </>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/forms/slider.stories.tsx b/packages/ui/src/components/forms/slider.stories.tsx
new file mode 100644
index 0000000000..f32210f7ca
--- /dev/null
+++ b/packages/ui/src/components/forms/slider.stories.tsx
@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { Slider } from './slider';
+
+const meta: Meta<typeof Slider> = {
+  title: 'Forms/Slider',
+  component: Slider,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Slider>;
+
+function SliderDemo({
+  ticks,
+  withValueLabel,
+}: {
+  ticks?: readonly number[];
+  withValueLabel?: boolean;
+}) {
+  const [value, setValue] = useState(40);
+  return (
+    <div className="max-w-sm pt-10">
+      <Slider
+        aria-label="Temperature"
+        value={value}
+        min={0}
+        max={100}
+        ticks={ticks}
+        valueLabel={withValueLabel ? value : undefined}
+        onChange={(e) => setValue(e.currentTarget.valueAsNumber)}
+      />
+    </div>
+  );
+}
+
+export const Default: Story = { render: () => <SliderDemo /> };
+
+export const WithTicks: Story = {
+  render: () => <SliderDemo ticks={[0, 25, 50, 75, 100]} />,
+};
+
+export const WithValueLabel: Story = {
+  render: () => <SliderDemo withValueLabel />,
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Slider
+        aria-label="Disabled"
+        value={30}
+        min={0}
+        max={100}
+        disabled
+        onChange={() => {}}
+      />
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/forms/slider.test.tsx b/packages/ui/src/components/forms/slider.test.tsx
new file mode 100644
index 0000000000..c30bb9a05e
--- /dev/null
+++ b/packages/ui/src/components/forms/slider.test.tsx
@@ -0,0 +1,23 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Slider } from './slider';
+
+describe('Slider', () => {
+  describe('accessibility', () => {
+    it('passes axe audit with an accessible name', async () => {
+      const { container } = render(
+        <Slider
+          aria-label="Temperature"
+          value={40}
+          min={0}
+          max={100}
+          onChange={() => {}}
+        />,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/forms/textarea.stories.tsx b/packages/ui/src/components/forms/textarea.stories.tsx
new file mode 100644
index 0000000000..b1a8ade4e5
--- /dev/null
+++ b/packages/ui/src/components/forms/textarea.stories.tsx
@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Skeletonize } from '../feedback/skeleton-context';
+import { Textarea } from './textarea';
+
+const meta: Meta<typeof Textarea> = {
+  title: 'Forms/Textarea',
+  component: Textarea,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Textarea>;
+
+export const Default: Story = {
+  args: { placeholder: 'Write a description…' },
+  render: (args) => (
+    <div className="max-w-sm">
+      <Textarea {...args} />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Textarea placeholder="Disabled" disabled />
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Textarea defaultValue="Too short" aria-invalid aria-label="Notes" />
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Skeletonize loading>
+        <Textarea rows={4} />
+      </Skeletonize>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/layout/action-row.tsx b/packages/ui/src/components/layout/action-row.tsx
index f3996ef16b..5b030666f1 100644
--- a/packages/ui/src/components/layout/action-row.tsx
+++ b/packages/ui/src/components/layout/action-row.tsx
@@ -4,6 +4,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { forwardRef, type HTMLAttributes } from 'react';
 
 import { cn } from '../../lib/cn';
+import { gapScale } from './layout';
 
 const actionRowVariants = cva('flex items-center', {
   variants: {
@@ -12,10 +13,12 @@ const actionRowVariants = cva('flex items-center', {
       end: 'justify-end',
       between: 'justify-between',
     },
+    // Subset of the shared `gapScale` so action clusters never drift from the
+    // one spacing scale. Surface stays 1|2|3 (default 2) for back-compat.
     gap: {
-      1: 'gap-1',
-      2: 'gap-2',
-      3: 'gap-3',
+      1: gapScale[1],
+      2: gapScale[2],
+      3: gapScale[3],
     },
   },
   defaultVariants: {
diff --git a/packages/ui/src/components/layout/card.stories.tsx b/packages/ui/src/components/layout/card.stories.tsx
index 3c3b5b282b..ae1a964497 100644
--- a/packages/ui/src/components/layout/card.stories.tsx
+++ b/packages/ui/src/components/layout/card.stories.tsx
@@ -1,7 +1,18 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
+import { ArrowUpRight, Boxes, Plug } from 'lucide-react';
 
-import { Card } from './card';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardGrid,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+} from './card';
 
 const meta: Meta<typeof Card> = {
   title: 'Layout/Card',
@@ -12,14 +23,19 @@ const meta: Meta<typeof Card> = {
     docs: {
       description: {
         component: `
-A single-piece card component for grouping related content.
+The one bordered surface primitive. Compose it with the \`Card*\` subcomponents and
+drive its look with \`padding\` / \`radius\` / \`shadow\` / \`interactive\`. Use \`asChild\`
+to turn the card into a \`<button>\`, \`<a>\`, or router \`<Link>\`.
 
-## Usage
 \`\`\`tsx
-import { Card } from '@/app/components/ui/layout/card';
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@tale/ui/card';
 
-<Card title="Card Title" description="Card description">
-  Content goes here
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>Body</CardContent>
 </Card>
 \`\`\`
         `,
@@ -38,84 +54,152 @@ import { Card } from '@/app/components/ui/layout/card';
 export default meta;
 type Story = StoryObj<typeof Card>;
 
-export const Default: Story = {
-  args: {
-    title: 'Card title',
-    description: 'This is a description of the card content.',
-    children: <p>Card content goes here. This can be any content you want.</p>,
-  },
-};
-
-export const WithFooter: Story = {
-  args: {
-    title: 'Create project',
-    description: 'Deploy your new project in one-click.',
-    footer: (
-      <div className="flex gap-2">
+/** The classic composed card: header (title + description), content, footer. */
+export const Basic: Story = {
+  render: () => (
+    <Card>
+      <CardHeader>
+        <CardTitle>Create project</CardTitle>
+        <CardDescription>Deploy your new project in one click.</CardDescription>
+      </CardHeader>
+      <CardContent className="text-fg-muted mt-4 text-sm">
+        Your project will be deployed to our cloud infrastructure.
+      </CardContent>
+      <CardFooter className="mt-6 justify-end">
         <Button variant="secondary">Cancel</Button>
         <Button>Deploy</Button>
-      </div>
-    ),
-    children: (
-      <p className="text-muted-foreground text-sm">
-        Your project will be deployed to our cloud infrastructure.
-      </p>
-    ),
-  },
+      </CardFooter>
+    </Card>
+  ),
 };
 
-export const SimpleCard: Story = {
-  args: {
-    children: <p>A simple card with only content.</p>,
-  },
+/** Every padding step crossed with both radii. */
+export const PaddingAndRadius: Story = {
+  decorators: [],
+  render: () => (
+    <div className="grid w-full max-w-3xl grid-cols-2 gap-4">
+      {(['sm', 'md', 'lg', 'xl'] as const).map((padding) =>
+        (['lg', 'xl'] as const).map((radius) => (
+          <Card key={`${padding}-${radius}`} padding={padding} radius={radius}>
+            <span className="text-fg-muted text-sm">
+              padding=&quot;{padding}&quot; radius=&quot;{radius}&quot;
+            </span>
+          </Card>
+        )),
+      )}
+    </div>
+  ),
 };
 
-export const TitleOnly: Story = {
-  args: {
-    title: 'Notifications',
-    children: (
-      <p className="text-muted-foreground text-sm">
-        You have 3 unread messages.
-      </p>
-    ),
-  },
+/** `asChild` + `interactive` turns the whole card into a focusable button. */
+export const Interactive: Story = {
+  render: () => (
+    <Card asChild interactive padding="md">
+      <button type="button" className="w-full text-left">
+        <CardHeader>
+          <CardTitle>Clickable card</CardTitle>
+          <CardDescription>The whole surface is the button.</CardDescription>
+        </CardHeader>
+      </button>
+    </Card>
+  ),
 };
 
-export const Interactive: Story = {
-  args: {
-    title: 'Clickable Card',
-    description: 'Hover to see the effect',
-    className: 'cursor-pointer transition-shadow hover:shadow-md',
-    children: <p className="text-sm">Click this card to navigate somewhere.</p>,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Cards can be styled to appear interactive.',
-      },
-    },
-  },
+/** `asChild` around an anchor — a card that navigates. */
+export const AsLink: Story = {
+  render: () => (
+    <Card asChild interactive padding="md" className="group">
+      <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+        <CardHeader>
+          <div className="flex items-center justify-between gap-2">
+            <CardTitle>Documentation</CardTitle>
+            <ArrowUpRight className="text-fg-muted size-4 transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+          </div>
+          <CardDescription>Opens in a new tab.</CardDescription>
+        </CardHeader>
+      </a>
+    </Card>
+  ),
 };
 
-export const CardGrid: Story = {
+/** A leading 40px `CardMedia` tile + title + description. */
+export const WithMedia: Story = {
   render: () => (
-    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-2">
-      <Card title="Revenue" headerClassName="pb-2">
-        <p className="text-2xl font-bold">$45,231.89</p>
-        <p className="text-muted-foreground text-xs">+20.1% from last month</p>
-      </Card>
-      <Card title="Users" headerClassName="pb-2">
-        <p className="text-2xl font-bold">+2,350</p>
-        <p className="text-muted-foreground text-xs">+180.1% from last month</p>
-      </Card>
-    </div>
+    <Card padding="md">
+      <div className="flex items-start gap-3">
+        <CardMedia>
+          <Boxes className="text-fg-base size-5" />
+        </CardMedia>
+        <CardHeader>
+          <CardTitle>Inventory</CardTitle>
+          <CardDescription>Track products and stock levels.</CardDescription>
+        </CardHeader>
+      </div>
+    </Card>
+  ),
+};
+
+/** The browse-and-act catalog layout (media + title + badge + description + meta + actions). */
+export const Catalog: Story = {
+  render: () => (
+    <Card padding="md" className="flex h-full flex-col">
+      <div className="flex items-start gap-3">
+        <CardMedia>
+          <Plug className="text-fg-base size-5" />
+        </CardMedia>
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <div className="flex items-start justify-between gap-2">
+            <CardTitle className="line-clamp-1 text-sm">Slack</CardTitle>
+            <Badge variant="green" dot className="shrink-0">
+              Connected
+            </Badge>
+          </div>
+          <CardDescription className="line-clamp-2 leading-snug">
+            Send and receive messages from your workspace.
+          </CardDescription>
+        </div>
+      </div>
+      <CardFooter className="mt-auto pt-4">
+        <Button variant="secondary" size="sm">
+          Manage
+        </Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+/** The chat approval frame: `padding="md"` + `radius="xl"`. */
+export const ApprovalFrame: Story = {
+  render: () => (
+    <Card padding="md" radius="xl" className="overflow-hidden">
+      <CardHeader>
+        <CardTitle className="text-sm">Save 2 documents?</CardTitle>
+        <CardDescription>report.md, summary.md</CardDescription>
+      </CardHeader>
+      <CardFooter className="mt-4 justify-end">
+        <Button variant="secondary" size="sm">
+          Reject
+        </Button>
+        <Button size="sm">Approve</Button>
+      </CardFooter>
+    </Card>
   ),
+};
+
+/** `CardGrid` lays out cards 1 → 2 → 3 columns responsively. */
+export const CardGridStory: Story = {
+  name: 'Card grid',
   decorators: [],
-  parameters: {
-    docs: {
-      description: {
-        story: 'Cards in a grid layout for dashboards.',
-      },
-    },
-  },
+  render: () => (
+    <CardGrid className="w-full max-w-4xl">
+      {['Agents', 'Workflows', 'Integrations'].map((label) => (
+        <Card key={label} padding="md">
+          <CardTitle className="text-sm">{label}</CardTitle>
+          <CardDescription className="mt-1">
+            Browse and install from the catalog.
+          </CardDescription>
+        </Card>
+      ))}
+    </CardGrid>
+  ),
 };
diff --git a/packages/ui/src/components/layout/card.test.tsx b/packages/ui/src/components/layout/card.test.tsx
index 61528d8b29..c054b6b166 100644
--- a/packages/ui/src/components/layout/card.test.tsx
+++ b/packages/ui/src/components/layout/card.test.tsx
@@ -1,34 +1,138 @@
-import { describe, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
-import { checkAccessibility } from '@/tests/utils/a11y';
-import { render } from '@/tests/utils/render';
+import { checkAccessibility, expectFocusable } from '@/tests/utils/a11y';
+import { render, screen } from '@/tests/utils/render';
 
-import { Card } from './card';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardGrid,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+  cardVariants,
+} from './card';
 
 describe('Card', () => {
-  describe('accessibility', () => {
-    it('passes axe audit', async () => {
-      const { container } = render(
-        <Card title="Card Title" description="Card description">
-          <p>Card content</p>
+  describe('rendering', () => {
+    it('renders children', () => {
+      render(<Card>Body</Card>);
+      expect(screen.getByText('Body')).toBeInTheDocument();
+    });
+
+    it('composes header/title/description/content/footer', () => {
+      render(
+        <Card>
+          <CardHeader>
+            <CardTitle>Title</CardTitle>
+            <CardDescription>Description</CardDescription>
+          </CardHeader>
+          <CardContent>Content</CardContent>
+          <CardFooter>
+            <button type="button">Action</button>
+          </CardFooter>
         </Card>,
       );
-      await checkAccessibility(container);
+      expect(
+        screen.getByRole('heading', { level: 3, name: 'Title' }),
+      ).toBeInTheDocument();
+      expect(screen.getByText('Description')).toBeInTheDocument();
+      expect(screen.getByText('Content')).toBeInTheDocument();
+      expect(
+        screen.getByRole('button', { name: 'Action' }),
+      ).toBeInTheDocument();
+    });
+
+    it('applies the caller className over variant classes', () => {
+      const { container } = render(<Card className="custom-class">x</Card>);
+      expect(container.firstChild).toHaveClass('custom-class');
     });
+  });
 
-    it('passes axe audit with footer', async () => {
+  describe('variants', () => {
+    it.each(['none', 'sm', 'md', 'lg', 'xl'] as const)(
+      'maps padding=%s',
+      (padding) => {
+        const cls = cardVariants({ padding });
+        const expected = {
+          none: null,
+          sm: 'p-3',
+          md: 'p-4',
+          lg: 'p-5',
+          xl: 'p-6',
+        }[padding];
+        if (expected) expect(cls).toContain(expected);
+      },
+    );
+
+    it('maps radius=xl', () => {
+      expect(cardVariants({ radius: 'xl' })).toContain('rounded-xl');
+    });
+
+    it('adds hover/focus affordances when interactive', () => {
+      expect(cardVariants({ interactive: true })).toContain(
+        'hover:border-border-strong',
+      );
+    });
+  });
+
+  describe('asChild', () => {
+    it('renders as the child element and stays focusable', () => {
+      render(
+        <Card asChild interactive padding="none">
+          <button type="button">Open</button>
+        </Card>,
+      );
+      const button = screen.getByRole('button', { name: 'Open' });
+      expectFocusable(button);
+    });
+  });
+
+  describe('CardMedia', () => {
+    it('renders its child glyph', () => {
+      render(
+        <CardMedia>
+          <span data-testid="glyph" />
+        </CardMedia>,
+      );
+      expect(screen.getByTestId('glyph')).toBeInTheDocument();
+    });
+  });
+
+  describe('CardGrid', () => {
+    it('renders a responsive grid of children', () => {
       const { container } = render(
-        <Card title="Card Title" footer={<button type="button">Save</button>}>
-          <p>Card content</p>
+        <CardGrid>
+          <Card>a</Card>
+          <Card>b</Card>
+        </CardGrid>,
+      );
+      expect(container.firstChild).toHaveClass('grid');
+    });
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit (composed card)', async () => {
+      const { container } = render(
+        <Card>
+          <CardHeader>
+            <CardTitle>Title</CardTitle>
+            <CardDescription>Description</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <p>Card content</p>
+          </CardContent>
         </Card>,
       );
       await checkAccessibility(container);
     });
 
-    it('passes axe audit without header', async () => {
+    it('passes axe audit (interactive button card)', async () => {
       const { container } = render(
-        <Card>
-          <p>Card content only</p>
+        <Card asChild interactive padding="none">
+          <button type="button">Open project</button>
         </Card>,
       );
       await checkAccessibility(container);
diff --git a/packages/ui/src/components/layout/card.tsx b/packages/ui/src/components/layout/card.tsx
index ba3b2b5957..cf18271daa 100644
--- a/packages/ui/src/components/layout/card.tsx
+++ b/packages/ui/src/components/layout/card.tsx
@@ -1,62 +1,189 @@
-import { Text } from '@tale/ui/text';
-import { type ReactNode } from 'react';
+'use client';
+
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { type ComponentProps, forwardRef, type HTMLAttributes } from 'react';
 
 import { cn } from '../../lib/cn';
+import { Grid } from './layout';
+
+/**
+ * Card — the one bordered surface primitive for the whole app. Compose it with
+ * the `Card*` subcomponents (header/title/description/content/footer/media) or
+ * use it as a bare frame. Every "card-like" surface (catalogs, settings panels,
+ * chat approvals, kanban tasks, dashboards) is one of these with a different
+ * `padding`/`radius`/`interactive` combination — never a hand-rolled
+ * `rounded-* border bg-* p-*` div.
+ *
+ * Surfaces use the canonical design tokens (`bg-bg-base`/`border-border-base`/
+ * `text-fg-*`), matching Button/Badge and the markdown Card.
+ */
+export const cardVariants = cva(
+  'bg-bg-base text-fg-base border border-border-base transition-[colors,box-shadow]',
+  {
+    variants: {
+      /**
+       * Inner padding. `none` lets the caller own padding (e.g. a full-bleed
+       * inner button or a list of self-padded rows). Steps map to the real
+       * surfaces: `sm` kanban task, `md` chat approval, `lg` mcp/stat cell,
+       * `xl` classic card.
+       */
+      padding: { none: '', sm: 'p-3', md: 'p-4', lg: 'p-5', xl: 'p-6' },
+      radius: { lg: 'rounded-lg', xl: 'rounded-xl' },
+      shadow: { none: '', sm: 'shadow-sm', md: 'shadow-md' },
+      /**
+       * Adds a hover border lift + a focus ring. The focus ring only renders on
+       * the focused element, so it's meaningful when the card IS the
+       * interactive node (`asChild` around a `<button>`/`<a>`) and inert (but
+       * harmless) on a plain `<div>` card.
+       */
+      interactive: {
+        true: 'hover:border-border-strong focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none',
+        false: '',
+      },
+    },
+    defaultVariants: {
+      padding: 'xl',
+      radius: 'lg',
+      shadow: 'none',
+      interactive: false,
+    },
+  },
+);
 
-interface CardProps {
-  title?: ReactNode;
-  description?: ReactNode;
-  children?: ReactNode;
-  footer?: ReactNode;
-  className?: string;
-  contentClassName?: string;
-  headerClassName?: string;
-  footerClassName?: string;
+export interface CardProps
+  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardVariants> {
+  /**
+   * Render as a Radix `Slot` so the card's styling merges onto its single child
+   * — use it to turn the card into a `<button>`, `<a>`, or router `<Link>`.
+   */
+  asChild?: boolean;
 }
 
-export function Card({
-  title,
-  description,
-  children,
-  footer,
-  className,
-  contentClassName,
-  headerClassName,
-  footerClassName,
-}: CardProps) {
-  const hasHeader = !!(title || description);
+export const Card = forwardRef<HTMLDivElement, CardProps>(
+  (
+    { asChild, padding, radius, shadow, interactive, className, ...props },
+    ref,
+  ) => {
+    const Comp = asChild ? Slot : 'div';
+    return (
+      <Comp
+        ref={ref}
+        className={cn(
+          cardVariants({ padding, radius, shadow, interactive }),
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+Card.displayName = 'Card';
+
+/** Vertical header stack (title + description). Padding is owned by `Card`. */
+export const CardHeader = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex flex-col gap-1.5', className)}
+    {...props}
+  />
+));
+CardHeader.displayName = 'CardHeader';
 
+/**
+ * Card title — an `<h3>` by default (keeps heading order sane). Clamping is
+ * per-surface, so it's intentionally NOT baked in here; add `line-clamp-*` via
+ * `className` where a surface needs it.
+ */
+export const CardTitle = forwardRef<
+  HTMLHeadingElement,
+  HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => {
+  // Render through a tag variable (like `Heading`) so the content — passed as
+  // `children` via `...props` — isn't flagged as an empty heading.
+  const Tag = 'h3';
   return (
-    <div
+    <Tag
+      ref={ref}
       className={cn(
-        'rounded-lg border bg-card text-card-foreground shadow-sm',
+        'text-fg-base font-semibold leading-none tracking-tight',
         className,
       )}
-    >
-      {hasHeader && (
-        <div className={cn('flex flex-col space-y-1.5 p-6', headerClassName)}>
-          {title && (
-            <div className="text-xl leading-none font-semibold tracking-tight">
-              {title}
-            </div>
-          )}
-          {description && (
-            <Text as="div" variant="muted">
-              {description}
-            </Text>
-          )}
-        </div>
-      )}
-      {children && (
-        <div className={cn(hasHeader ? 'p-6 pt-0' : 'p-6', contentClassName)}>
-          {children}
-        </div>
-      )}
-      {footer && (
-        <div className={cn('flex items-center p-6 pt-0', footerClassName)}>
-          {footer}
-        </div>
-      )}
-    </div>
+      {...props}
+    />
   );
+});
+CardTitle.displayName = 'CardTitle';
+
+export const CardDescription = forwardRef<
+  HTMLParagraphElement,
+  HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p ref={ref} className={cn('text-fg-muted text-sm', className)} {...props} />
+));
+CardDescription.displayName = 'CardDescription';
+
+/** Body slot. Carries no styling of its own — pure structure. */
+export const CardContent = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn(className)} {...props} />
+));
+CardContent.displayName = 'CardContent';
+
+/** Footer row — actions sit here. */
+export const CardFooter = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex items-center gap-2', className)}
+    {...props}
+  />
+));
+CardFooter.displayName = 'CardFooter';
+
+/**
+ * A 40px bordered media tile for a card (brand glyph, icon, or avatar) so icon
+ * sizing is identical everywhere. Render an `<Image>`/`<Icon>` (≈24px) inside.
+ */
+export const CardMedia = forwardRef<
+  HTMLSpanElement,
+  HTMLAttributes<HTMLSpanElement>
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    className={cn(
+      'border-border-base bg-bg-base flex size-10 shrink-0 items-center justify-center rounded-lg border',
+      className,
+    )}
+    {...props}
+  />
+));
+CardMedia.displayName = 'CardMedia';
+
+export interface CardGridProps extends Omit<
+  ComponentProps<typeof Grid>,
+  'cols' | 'sm' | 'lg'
+> {
+  cols?: ComponentProps<typeof Grid>['cols'];
+  sm?: ComponentProps<typeof Grid>['sm'];
+  lg?: ComponentProps<typeof Grid>['lg'];
 }
+
+/**
+ * Responsive card grid: 1 → 2 (sm) → 3 (lg) columns, gap-4 — the browse-and-act
+ * default. A thin wrapper over `Grid`; override `cols`/`sm`/`md`/`lg`/`gap` for
+ * other shapes.
+ */
+export const CardGrid = forwardRef<HTMLDivElement, CardGridProps>(
+  ({ cols = 1, sm = 2, lg = 3, gap = 4, ...props }, ref) => (
+    <Grid ref={ref} cols={cols} sm={sm} lg={lg} gap={gap} {...props} />
+  ),
+);
+CardGrid.displayName = 'CardGrid';
diff --git a/packages/ui/src/components/layout/container.stories.tsx b/packages/ui/src/components/layout/container.stories.tsx
new file mode 100644
index 0000000000..e3e17893c6
--- /dev/null
+++ b/packages/ui/src/components/layout/container.stories.tsx
@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Container } from './container';
+
+const meta: Meta<typeof Container> = {
+  title: 'Layout/Container',
+  component: Container,
+  tags: ['autodocs'],
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Container>;
+
+const Band = ({ children }: { children: React.ReactNode }) => (
+  <div className="bg-primary/10 border-primary/20 rounded-md border p-4 text-center text-sm">
+    {children}
+  </div>
+);
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 py-6">
+      {(['md', 'lg', 'xl', 'full'] as const).map((size) => (
+        <Container key={size} size={size}>
+          <Band>size=&quot;{size}&quot;</Band>
+        </Container>
+      ))}
+    </div>
+  ),
+};
+
+export const Default: Story = {
+  render: () => (
+    <div className="py-6">
+      <Container>
+        <Band>Default container (xl, centered, responsive padding)</Band>
+      </Container>
+    </div>
+  ),
+};
diff --git a/packages/ui/src/components/layout/container.test.tsx b/packages/ui/src/components/layout/container.test.tsx
new file mode 100644
index 0000000000..5bbc07476b
--- /dev/null
+++ b/packages/ui/src/components/layout/container.test.tsx
@@ -0,0 +1,19 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Container } from './container';
+
+describe('Container', () => {
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <Container>
+          <p>Content</p>
+        </Container>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/layout/layout.stories.tsx b/packages/ui/src/components/layout/layout.stories.tsx
index 08e63300a7..86ec7c267c 100644
--- a/packages/ui/src/components/layout/layout.stories.tsx
+++ b/packages/ui/src/components/layout/layout.stories.tsx
@@ -1,14 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
-import {
-  Center,
-  Grid,
-  HStack,
-  NarrowContainer,
-  Spacer,
-  Stack,
-  VStack,
-} from './layout';
+import { Center, Grid, NarrowContainer, Row, Spacer, Stack } from './layout';
 
 const meta: Meta = {
   title: 'Layout/Primitives',
@@ -18,7 +10,10 @@ const meta: Meta = {
     docs: {
       description: {
         component:
-          'Layout primitive components for building consistent layouts.',
+          'Layout primitives for composing pages without raw layout `<div>`s. ' +
+          '`Stack` (vertical) and `Row` (horizontal) share one `gap` scale; ' +
+          '`Grid` is responsive. `HStack`/`VStack` are deprecated aliases of ' +
+          '`Row`/`Stack`.',
       },
     },
   },
@@ -39,7 +34,7 @@ const Box = ({
   </div>
 );
 
-export const StackComponent: StoryObj = {
+export const StackVertical: StoryObj = {
   render: () => (
     <div className="max-w-xs">
       <Stack gap={4}>
@@ -51,25 +46,49 @@ export const StackComponent: StoryObj = {
   ),
 };
 
-export const HStackComponent: StoryObj = {
+/** The recommended spacing rhythm: 2 (field groups), 4 (within a section), 6, 8 (between sections). */
+export const StackGapRhythm: StoryObj = {
   render: () => (
-    <HStack gap={4}>
+    <Row gap={6} align="start" wrap>
+      {([2, 4, 6, 8] as const).map((gap) => (
+        <Stack key={gap} gap={1} className="max-w-48">
+          <span className="text-muted-foreground text-xs">gap={gap}</span>
+          <Stack gap={gap}>
+            <Box>A</Box>
+            <Box>B</Box>
+            <Box>C</Box>
+          </Stack>
+        </Stack>
+      ))}
+    </Row>
+  ),
+};
+
+export const RowHorizontal: StoryObj = {
+  render: () => (
+    <Row gap={4}>
       <Box>Item 1</Box>
       <Box>Item 2</Box>
       <Box>Item 3</Box>
-    </HStack>
+    </Row>
   ),
 };
 
-export const VStackComponent: StoryObj = {
+export const RowJustify: StoryObj = {
   render: () => (
-    <div className="max-w-xs">
-      <VStack gap={4}>
-        <Box>Item 1</Box>
-        <Box>Item 2</Box>
-        <Box>Item 3</Box>
-      </VStack>
-    </div>
+    <Stack gap={3} className="w-full">
+      {(['start', 'center', 'end', 'between'] as const).map((justify) => (
+        <Row
+          key={justify}
+          gap={2}
+          justify={justify}
+          className="bg-muted/30 w-full rounded-md p-2"
+        >
+          <Box>A</Box>
+          <Box>B</Box>
+        </Row>
+      ))}
+    </Stack>
   ),
 };
 
@@ -83,6 +102,22 @@ export const GridResponsive: StoryObj = {
   ),
 };
 
+/** Use `as` to render a semantic element (here a `<ul>`) instead of a raw list tag on the page. */
+export const PolymorphicAs: StoryObj = {
+  render: () => (
+    <Stack as="ul" gap={2} className="max-w-xs">
+      {['First', 'Second', 'Third'].map((label) => (
+        <li
+          key={label}
+          className="bg-primary/10 border-primary/20 rounded-md border p-3 text-sm"
+        >
+          {label}
+        </li>
+      ))}
+    </Stack>
+  ),
+};
+
 export const CenterComponent: StoryObj = {
   render: () => (
     <Center className="bg-muted/30 h-40 rounded-lg">
@@ -93,11 +128,11 @@ export const CenterComponent: StoryObj = {
 
 export const SpacerComponent: StoryObj = {
   render: () => (
-    <HStack gap={4} className="w-full">
+    <Row gap={4} className="w-full">
       <Box>Left</Box>
       <Spacer />
       <Box>Right</Box>
-    </HStack>
+    </Row>
   ),
 };
 
diff --git a/packages/ui/src/components/layout/layout.test.tsx b/packages/ui/src/components/layout/layout.test.tsx
index 223fb307dd..7a27d95a7b 100644
--- a/packages/ui/src/components/layout/layout.test.tsx
+++ b/packages/ui/src/components/layout/layout.test.tsx
@@ -1,4 +1,4 @@
-import { describe, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
 import { checkAccessibility } from '@/tests/utils/a11y';
 import { render } from '@/tests/utils/render';
@@ -8,12 +8,62 @@ import {
   Grid,
   HStack,
   NarrowContainer,
+  Row,
   Spacer,
   Stack,
   VStack,
 } from './layout';
 
 describe('Stack', () => {
+  it('renders a vertical flex container with the default gap', () => {
+    const { container } = render(
+      <Stack>
+        <p>Item 1</p>
+        <p>Item 2</p>
+      </Stack>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.tagName).toBe('DIV');
+    expect(el).toHaveClass('flex', 'flex-col', 'gap-4', 'items-stretch');
+  });
+
+  it('applies gap, align, justify and wrap from the shared scale', () => {
+    const { container } = render(
+      <Stack gap={2} align="center" justify="between" wrap>
+        <p>Item</p>
+      </Stack>,
+    );
+    expect(container.firstElementChild).toHaveClass(
+      'gap-2',
+      'items-center',
+      'justify-between',
+      'flex-wrap',
+    );
+  });
+
+  it('renders a semantic element via `as`', () => {
+    const { container } = render(
+      <Stack as="ul">
+        <li>One</li>
+        <li>Two</li>
+      </Stack>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.tagName).toBe('UL');
+    expect(el).toHaveClass('flex', 'flex-col');
+  });
+
+  it('merges layout classes onto the child via `asChild`', () => {
+    const { getByTestId } = render(
+      <Stack gap={2} asChild>
+        <section data-testid="merged">content</section>
+      </Stack>,
+    );
+    const el = getByTestId('merged');
+    expect(el.tagName).toBe('SECTION');
+    expect(el).toHaveClass('flex', 'flex-col', 'gap-2');
+  });
+
   describe('accessibility', () => {
     it('passes axe audit', async () => {
       const { container } = render(
@@ -27,7 +77,49 @@ describe('Stack', () => {
   });
 });
 
-describe('HStack', () => {
+describe('Row', () => {
+  it('renders a horizontal flex container centered by default', () => {
+    const { container } = render(
+      <Row>
+        <p>Left</p>
+        <p>Right</p>
+      </Row>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.tagName).toBe('DIV');
+    expect(el).toHaveClass('flex', 'flex-row', 'gap-4', 'items-center');
+  });
+
+  it('applies justify and wrap', () => {
+    const { container } = render(
+      <Row justify="between" wrap>
+        <p>A</p>
+      </Row>,
+    );
+    expect(container.firstElementChild).toHaveClass(
+      'justify-between',
+      'flex-wrap',
+    );
+  });
+
+  describe('accessibility', () => {
+    it('passes axe audit', async () => {
+      const { container } = render(
+        <Row>
+          <p>Left</p>
+          <p>Right</p>
+        </Row>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
+
+describe('HStack (deprecated alias of Row)', () => {
+  it('is the Row component', () => {
+    expect(HStack).toBe(Row);
+  });
+
   describe('accessibility', () => {
     it('passes axe audit', async () => {
       const { container } = render(
@@ -41,7 +133,11 @@ describe('HStack', () => {
   });
 });
 
-describe('VStack', () => {
+describe('VStack (deprecated alias of Stack)', () => {
+  it('is the Stack component', () => {
+    expect(VStack).toBe(Stack);
+  });
+
   describe('accessibility', () => {
     it('passes axe audit', async () => {
       const { container } = render(
@@ -56,6 +152,20 @@ describe('VStack', () => {
 });
 
 describe('Grid', () => {
+  it('applies columns and gap', () => {
+    const { container } = render(
+      <Grid cols={2} gap={6}>
+        <p>Cell 1</p>
+        <p>Cell 2</p>
+      </Grid>,
+    );
+    expect(container.firstElementChild).toHaveClass(
+      'grid',
+      'grid-cols-2',
+      'gap-6',
+    );
+  });
+
   describe('accessibility', () => {
     it('passes axe audit', async () => {
       const { container } = render(
@@ -86,11 +196,11 @@ describe('Spacer', () => {
   describe('accessibility', () => {
     it('passes axe audit', async () => {
       const { container } = render(
-        <HStack>
+        <Row>
           <p>Left</p>
           <Spacer />
           <p>Right</p>
-        </HStack>,
+        </Row>,
       );
       await checkAccessibility(container);
     });
diff --git a/packages/ui/src/components/layout/layout.tsx b/packages/ui/src/components/layout/layout.tsx
index c8e8031e3b..81ac844c67 100644
--- a/packages/ui/src/components/layout/layout.tsx
+++ b/packages/ui/src/components/layout/layout.tsx
@@ -1,59 +1,69 @@
 'use client';
 
+import { Slot } from '@radix-ui/react-slot';
 import { cva, type VariantProps } from 'class-variance-authority';
-import { forwardRef, HTMLAttributes } from 'react';
+import { type ElementType, forwardRef, type HTMLAttributes } from 'react';
 
 import { cn } from '../../lib/cn';
 
-const stackVariants = cva('', {
+/**
+ * The single spacing scale shared by every layout primitive (`Stack`, `Row`,
+ * `Grid`) and re-used by `ActionRow` and `PageSection`. One scale, one source of
+ * truth — pick a named step, never a raw `gap-[…]`.
+ *
+ * Recommended steps for app layout: `2` (field groups: label → control → hint),
+ * `4` (within a section — the default), `6` (loose grouping inside a wide
+ * section), `8` (between sections / the settings rhythm). `5`, `10` and `12`
+ * remain for legacy callers; avoid them in new code.
+ */
+export const gapScale = {
+  0: 'gap-0',
+  1: 'gap-1',
+  2: 'gap-2',
+  3: 'gap-3',
+  4: 'gap-4',
+  5: 'gap-5',
+  6: 'gap-6',
+  8: 'gap-8',
+  10: 'gap-10',
+  12: 'gap-12',
+} as const;
+
+const alignVariants = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+  baseline: 'items-baseline',
+} as const;
+
+const justifyVariants = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  between: 'justify-between',
+  around: 'justify-around',
+  evenly: 'justify-evenly',
+} as const;
+
+const stackVariants = cva('flex flex-col', {
   variants: {
-    gap: {
-      0: 'space-y-0',
-      1: 'space-y-1',
-      2: 'space-y-2',
-      3: 'space-y-3',
-      4: 'space-y-4',
-      5: 'space-y-5',
-      6: 'space-y-6',
-      8: 'space-y-8',
-      10: 'space-y-10',
-      12: 'space-y-12',
-    },
+    gap: gapScale,
+    align: alignVariants,
+    justify: justifyVariants,
   },
   defaultVariants: {
     gap: 4,
+    align: 'stretch',
+    justify: 'start',
   },
 });
 
-const flexVariants = cva('flex', {
+const rowVariants = cva('flex flex-row', {
   variants: {
-    gap: {
-      0: 'gap-0',
-      1: 'gap-1',
-      2: 'gap-2',
-      3: 'gap-3',
-      4: 'gap-4',
-      5: 'gap-5',
-      6: 'gap-6',
-      8: 'gap-8',
-      10: 'gap-10',
-      12: 'gap-12',
-    },
-    align: {
-      start: 'items-start',
-      center: 'items-center',
-      end: 'items-end',
-      stretch: 'items-stretch',
-      baseline: 'items-baseline',
-    },
-    justify: {
-      start: 'justify-start',
-      center: 'justify-center',
-      end: 'justify-end',
-      between: 'justify-between',
-      around: 'justify-around',
-      evenly: 'justify-evenly',
-    },
+    gap: gapScale,
+    align: alignVariants,
+    justify: justifyVariants,
   },
   defaultVariants: {
     gap: 4,
@@ -64,18 +74,7 @@ const flexVariants = cva('flex', {
 
 const gridVariants = cva('grid', {
   variants: {
-    gap: {
-      0: 'gap-0',
-      1: 'gap-1',
-      2: 'gap-2',
-      3: 'gap-3',
-      4: 'gap-4',
-      5: 'gap-5',
-      6: 'gap-6',
-      8: 'gap-8',
-      10: 'gap-10',
-      12: 'gap-12',
-    },
+    gap: gapScale,
     cols: {
       1: 'grid-cols-1',
       2: 'grid-cols-2',
@@ -123,88 +122,174 @@ const gridVariants = cva('grid', {
   },
 });
 
+/** Semantic elements a layout primitive may render as (`<Stack as="ul">`). */
+type LayoutElement =
+  | 'div'
+  | 'section'
+  | 'article'
+  | 'aside'
+  | 'header'
+  | 'footer'
+  | 'main'
+  | 'nav'
+  | 'ul'
+  | 'ol'
+  | 'li'
+  | 'form'
+  | 'fieldset';
+
+interface PolymorphicProps {
+  /**
+   * Render a semantic element instead of the default `div` — use this to keep
+   * pages composing primitives rather than dropping to raw HTML (`as="ul"` for a
+   * list, `as="form"` for a form, `as="section"` for a landmark).
+   */
+  as?: LayoutElement;
+  /**
+   * Merge layout classes onto the single child element instead of rendering a
+   * wrapper. Mutually exclusive with `as`.
+   */
+  asChild?: boolean;
+}
+
 interface StackProps
-  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof stackVariants> {}
+  extends
+    HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof stackVariants>,
+    PolymorphicProps {
+  /** Allow items to wrap onto multiple lines. */
+  wrap?: boolean;
+}
 
 /**
- * Stack — vertical layout with configurable spacing (`space-y-*`). Default
- * gap is `4` (16px).
+ * Stack — the canonical **vertical** layout primitive: `flex-col` with a named
+ * `gap`. Defaults to `gap={4}` (16px) and `align="stretch"` so children fill the
+ * width. Use for stacked sections, fields, and cards instead of a raw
+ * `<div className="flex flex-col gap-…">`.
  */
 export const Stack = forwardRef<HTMLDivElement, StackProps>(
-  ({ gap, className, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(stackVariants({ gap }), className)}
-      {...props}
-    />
-  ),
+  (
+    {
+      gap,
+      align,
+      justify,
+      wrap = false,
+      as = 'div',
+      asChild = false,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp: ElementType = asChild ? Slot : as;
+    return (
+      <Comp
+        ref={ref}
+        className={cn(
+          stackVariants({ gap, align, justify }),
+          wrap && 'flex-wrap',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
 );
 Stack.displayName = 'Stack';
 
-interface HStackProps
-  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof flexVariants> {
+interface RowProps
+  extends
+    HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof rowVariants>,
+    PolymorphicProps {
+  /** Allow items to wrap onto multiple lines. */
   wrap?: boolean;
 }
 
 /**
- * HStack — horizontal flex layout with configurable spacing and alignment.
- * Default gap is `4` (16px), items centered vertically.
+ * Row — the canonical **horizontal** layout primitive: `flex-row` with a named
+ * `gap`. Defaults to `gap={4}` (16px) and `align="center"`. Use for inline
+ * groups (icon + label, control clusters) instead of a raw
+ * `<div className="flex items-center gap-…">`. For a cluster of action buttons,
+ * prefer the semantic `ActionRow`.
  */
-export const HStack = forwardRef<HTMLDivElement, HStackProps>(
-  ({ gap, align, justify, wrap = false, className, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(
-        flexVariants({ gap, align, justify }),
-        wrap && 'flex-wrap',
-        className,
-      )}
-      {...props}
-    />
-  ),
+export const Row = forwardRef<HTMLDivElement, RowProps>(
+  (
+    {
+      gap,
+      align,
+      justify,
+      wrap = false,
+      as = 'div',
+      asChild = false,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp: ElementType = asChild ? Slot : as;
+    return (
+      <Comp
+        ref={ref}
+        className={cn(
+          rowVariants({ gap, align, justify }),
+          wrap && 'flex-wrap',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
 );
-HStack.displayName = 'HStack';
+Row.displayName = 'Row';
 
-interface VStackProps
-  extends
-    HTMLAttributes<HTMLDivElement>,
-    Omit<VariantProps<typeof flexVariants>, 'align'> {
-  align?: 'start' | 'center' | 'end' | 'stretch';
-}
+/**
+ * @deprecated Use `Row` — the canonical horizontal layout primitive. Kept as an
+ * alias so existing call sites keep working; new code should import `Row`.
+ */
+export const HStack = Row;
 
 /**
- * VStack — vertical flex layout (alias for `flex-col` with gap).
+ * @deprecated Use `Stack` — the canonical vertical layout primitive. Kept as an
+ * alias so existing call sites keep working; new code should import `Stack`.
  */
-export const VStack = forwardRef<HTMLDivElement, VStackProps>(
-  ({ gap, align = 'stretch', justify, className, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(
-        flexVariants({ gap, align, justify }),
-        'flex-col',
-        className,
-      )}
-      {...props}
-    />
-  ),
-);
-VStack.displayName = 'VStack';
+export const VStack = Stack;
 
 interface GridProps
-  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof gridVariants> {}
+  extends
+    HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof gridVariants>,
+    PolymorphicProps {}
 
 /**
- * Grid — responsive grid layout. `cols` controls the column count at each
- * breakpoint (`sm`, `md`, `lg`, `xl` props).
+ * Grid — responsive grid layout. `cols` controls the column count, with
+ * per-breakpoint overrides (`sm`, `md`, `lg`, `xl`). Shares the one `gap` scale.
  */
 export const Grid = forwardRef<HTMLDivElement, GridProps>(
-  ({ cols, sm, md, lg, xl, gap, className, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(gridVariants({ cols, sm, md, lg, xl, gap }), className)}
-      {...props}
-    />
-  ),
+  (
+    {
+      cols,
+      sm,
+      md,
+      lg,
+      xl,
+      gap,
+      as = 'div',
+      asChild = false,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp: ElementType = asChild ? Slot : as;
+    return (
+      <Comp
+        ref={ref}
+        className={cn(gridVariants({ cols, sm, md, lg, xl, gap }), className)}
+        {...props}
+      />
+    );
+  },
 );
 Grid.displayName = 'Grid';
 
@@ -240,7 +325,7 @@ export const NarrowContainer = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('mx-auto w-full max-w-[544px] px-4', className)}
+    className={cn('mx-auto w-full max-w-136 px-4', className)}
     {...props}
   />
 ));
diff --git a/packages/ui/src/components/layout/page-section.tsx b/packages/ui/src/components/layout/page-section.tsx
index 9188118cac..9279ab8536 100644
--- a/packages/ui/src/components/layout/page-section.tsx
+++ b/packages/ui/src/components/layout/page-section.tsx
@@ -4,15 +4,18 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
 
 import { cn } from '../../lib/cn';
+import { gapScale } from './layout';
 import { SectionHeader } from './section-header';
 
 const sectionVariants = cva('flex flex-col', {
   variants: {
+    // Subset of the shared `gapScale` so titled sections never drift from the
+    // one spacing scale. Surface stays 3|4|5|6 (default 4) for back-compat.
     gap: {
-      3: 'gap-3',
-      4: 'gap-4',
-      5: 'gap-5',
-      6: 'gap-6',
+      3: gapScale[3],
+      4: gapScale[4],
+      5: gapScale[5],
+      6: gapScale[6],
     },
   },
   defaultVariants: {
diff --git a/packages/ui/src/components/layout/section.stories.tsx b/packages/ui/src/components/layout/section.stories.tsx
new file mode 100644
index 0000000000..5bdf89d7f3
--- /dev/null
+++ b/packages/ui/src/components/layout/section.stories.tsx
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Container } from './container';
+import { Section } from './section';
+
+const meta: Meta<typeof Section> = {
+  title: 'Layout/Section',
+  component: Section,
+  tags: ['autodocs'],
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Section>;
+
+export const Tones: Story = {
+  render: () => (
+    <>
+      {(['default', 'muted', 'inverse'] as const).map((tone) => (
+        <Section key={tone} tone={tone} spacing="sm">
+          <Container>
+            <p className="text-center text-sm">tone=&quot;{tone}&quot;</p>
+          </Container>
+        </Section>
+      ))}
+    </>
+  ),
+};
+
+export const Spacing: Story = {
+  render: () => (
+    <>
+      {(['sm', 'md', 'lg'] as const).map((spacing) => (
+        <Section
+          key={spacing}
+          spacing={spacing}
+          tone={spacing === 'md' ? 'muted' : 'default'}
+        >
+          <Container>
+            <p className="text-center text-sm">spacing=&quot;{spacing}&quot;</p>
+          </Container>
+        </Section>
+      ))}
+    </>
+  ),
+};
diff --git a/packages/ui/src/components/layout/section.test.tsx b/packages/ui/src/components/layout/section.test.tsx
new file mode 100644
index 0000000000..8c202f88cb
--- /dev/null
+++ b/packages/ui/src/components/layout/section.test.tsx
@@ -0,0 +1,30 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Section } from './section';
+
+describe('Section', () => {
+  describe('accessibility', () => {
+    it('passes axe audit (default tone)', async () => {
+      const { container } = render(
+        <Section>
+          <p>Default section content</p>
+        </Section>,
+      );
+      await checkAccessibility(container);
+    });
+
+    // The inverse tone paints accent-fg on accent-base; verify the pairing
+    // carries no contrast violation.
+    it('passes axe audit (inverse tone)', async () => {
+      const { container } = render(
+        <Section tone="inverse">
+          <p>Inverse section content</p>
+        </Section>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/overlays/tooltip.stories.tsx b/packages/ui/src/components/overlays/tooltip.stories.tsx
new file mode 100644
index 0000000000..1f540f6592
--- /dev/null
+++ b/packages/ui/src/components/overlays/tooltip.stories.tsx
@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Button } from '../primitives/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from './tooltip';
+
+const meta: Meta = {
+  title: 'Overlays/Tooltip',
+  tags: ['autodocs'],
+  parameters: { layout: 'centered' },
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="secondary">Hover me</Button>
+        </TooltipTrigger>
+        <TooltipContent>Helpful hint</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  ),
+};
+
+export const Sides: Story = {
+  render: () => (
+    <TooltipProvider>
+      <div className="flex gap-6">
+        {(['top', 'right', 'bottom', 'left'] as const).map((side) => (
+          <Tooltip key={side}>
+            <TooltipTrigger asChild>
+              <Button variant="secondary">{side}</Button>
+            </TooltipTrigger>
+            <TooltipContent side={side}>On {side}</TooltipContent>
+          </Tooltip>
+        ))}
+      </div>
+    </TooltipProvider>
+  ),
+};
diff --git a/packages/ui/src/components/overlays/tooltip.test.tsx b/packages/ui/src/components/overlays/tooltip.test.tsx
new file mode 100644
index 0000000000..ada99fa574
--- /dev/null
+++ b/packages/ui/src/components/overlays/tooltip.test.tsx
@@ -0,0 +1,27 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from './tooltip';
+
+describe('Tooltip', () => {
+  describe('accessibility', () => {
+    it('passes axe audit (trigger)', async () => {
+      const { container } = render(
+        <TooltipProvider>
+          <Tooltip>
+            <TooltipTrigger>Hover me</TooltipTrigger>
+            <TooltipContent>Helpful hint</TooltipContent>
+          </Tooltip>
+        </TooltipProvider>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/components/primitives/button.stories.tsx b/packages/ui/src/components/primitives/button.stories.tsx
index 96445377df..e6f80fa90c 100644
--- a/packages/ui/src/components/primitives/button.stories.tsx
+++ b/packages/ui/src/components/primitives/button.stories.tsx
@@ -1,5 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { Mail, Trash2, Check, ArrowRight, Plus } from 'lucide-react';
+import {
+  Mail,
+  Trash2,
+  Check,
+  ArrowRight,
+  Plus,
+  Pencil,
+  Copy,
+} from 'lucide-react';
 import { fn } from 'storybook/test';
 
 import { Button, LinkButton } from './button';
@@ -51,7 +59,7 @@ import { Button } from '@/app/components/ui/primitives';
     },
     size: {
       control: 'select',
-      options: ['default', 'sm', 'lg', 'icon'],
+      options: ['default', 'sm', 'icon', 'icon-sm'],
       description: 'Size variant',
       table: {
         type: { summary: 'string' },
@@ -105,14 +113,24 @@ export const AllVariants: Story = {
 export const AllSizes: Story = {
   render: () => (
     <div className="flex items-center gap-4">
-      <Button size="sm">Small</Button>
       <Button size="default">Default</Button>
-      <Button size="lg">Large</Button>
-      <Button size="icon">
+      <Button size="sm">Small</Button>
+      <Button size="icon" title="Add">
+        <Plus className="size-4" />
+      </Button>
+      <Button size="icon-sm" title="Add (small)">
         <Plus className="size-4" />
       </Button>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The full size set: `default` (h-9) and `sm` (h-8, for dense bars) for text buttons, plus the square `icon` (size-9) and `icon-sm` (size-8) for icon-only buttons. There is no `lg` size — page CTAs use the default height.',
+      },
+    },
+  },
 };
 
 export const WithIcon: Story = {
@@ -190,8 +208,38 @@ export const CollapseLabel: Story = {
   },
 };
 
+export const IconWithTooltip: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Button size="icon" variant="ghost" title="Edit">
+        <Pencil className="size-4" />
+      </Button>
+      <Button size="icon" variant="ghost" title="Copy" tooltipSide="bottom">
+        <Copy className="size-4" />
+      </Button>
+      <Button
+        size="icon"
+        variant="ghost"
+        title="Delete"
+        tooltip="Delete permanently"
+        tooltipSide="right"
+      >
+        <Trash2 className="size-4" />
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A plain-string `title` names an icon-only button (it has no visible text) AND shows it as a hover/focus tooltip — one prop for both. Pass `tooltip` for richer tip content that differs from the accessible name, and `tooltipSide` to change where it opens. Focus or hover an icon to see the tip.',
+      },
+    },
+  },
+};
+
 export const PressAnimation: Story = {
-  args: { variant: 'primary', size: 'lg', children: 'Press me' },
+  args: { variant: 'primary', size: 'default', children: 'Press me' },
   render: (args) => (
     <div className="flex flex-col items-center gap-4">
       <p className="text-muted-foreground text-sm">
diff --git a/packages/ui/src/components/primitives/button.test.tsx b/packages/ui/src/components/primitives/button.test.tsx
index 5e5df31c45..a3d3efb718 100644
--- a/packages/ui/src/components/primitives/button.test.tsx
+++ b/packages/ui/src/components/primitives/button.test.tsx
@@ -64,15 +64,104 @@ describe('Button', () => {
   });
 
   describe('sizes', () => {
-    it.each(['default', 'sm', 'lg', 'icon'] as const)(
+    it.each(['default', 'sm', 'icon', 'icon-sm'] as const)(
       'renders %s size',
       (size) => {
-        render(<Button size={size}>Button</Button>);
+        // `title` names the icon size (the type requires icon buttons to be
+        // labeled) and is harmless on the others.
+        render(
+          <Button size={size} title="Button">
+            Button
+          </Button>,
+        );
         expect(screen.getByRole('button')).toBeInTheDocument();
       },
     );
   });
 
+  describe('title (icon-button label + tooltip)', () => {
+    it('uses `title` as the accessible name and drops the native title', () => {
+      render(
+        <Button size="icon" title="Zoom in">
+          <Mail className="size-4" />
+        </Button>,
+      );
+      const button = screen.getByRole('button', { name: 'Zoom in' });
+      expect(button).toBeInTheDocument();
+      // No duplicate native browser tooltip.
+      expect(button).not.toHaveAttribute('title');
+    });
+
+    it('lets an explicit aria-label override the title for the name', () => {
+      render(
+        <Button size="icon" title="tooltip text" aria-label="real label">
+          <Mail className="size-4" />
+        </Button>,
+      );
+      expect(
+        screen.getByRole('button', { name: 'real label' }),
+      ).toBeInTheDocument();
+    });
+
+    it('does not let `title` override a text button’s name from children', () => {
+      // For non-icon buttons the accessible name comes from the children; the
+      // `title` only drives the tooltip, never the name.
+      render(<Button title="tooltip text">Save</Button>);
+      expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: 'tooltip text' })).toBeNull();
+    });
+
+    it('shows a tooltip on focus, sourced from `title`', async () => {
+      const { user } = render(
+        <Button size="icon" title="Zoom in">
+          <Mail className="size-4" />
+        </Button>,
+      );
+      await user.tab();
+      // Radix opens the tooltip on trigger focus; content carries role=tooltip.
+      const tooltip = await screen.findByRole('tooltip');
+      expect(tooltip).toHaveTextContent('Zoom in');
+    });
+
+    it('prefers explicit `tooltip` content over `title` for the visible tip', async () => {
+      const { user } = render(
+        <Button size="icon" title="aria name" tooltip="Rich tip">
+          <Mail className="size-4" />
+        </Button>,
+      );
+      // The accessible name still comes from `title`.
+      expect(
+        screen.getByRole('button', { name: 'aria name' }),
+      ).toBeInTheDocument();
+      await user.tab();
+      const tooltip = await screen.findByRole('tooltip');
+      expect(tooltip).toHaveTextContent('Rich tip');
+    });
+
+    it('renders no tooltip trigger when used as a Slot (asChild)', () => {
+      // A Slot is typically another overlay's trigger; wrapping it in a tooltip
+      // trigger would break that composition, so the tooltip is suppressed.
+      render(
+        <Button asChild title="tooltip text">
+          <a href="/test">Link</a>
+        </Button>,
+      );
+      const link = screen.getByRole('link', { name: 'Link' });
+      // The Slot collapses onto the anchor; no extra tooltip-trigger button.
+      expect(link).toBeInTheDocument();
+      expect(screen.queryByRole('button')).toBeNull();
+    });
+
+    it('passes axe audit for an icon button named via `title`', async () => {
+      const { container } = render(
+        <Button size="icon" title="Zoom in">
+          <Mail className="size-4" />
+        </Button>,
+      );
+      await checkAccessibility(container);
+    });
+  });
+
   describe('interactions', () => {
     it('calls onClick when clicked', async () => {
       const handleClick = vi.fn();
diff --git a/packages/ui/src/components/primitives/button.tsx b/packages/ui/src/components/primitives/button.tsx
index fe304b6fd6..6cba4e6017 100644
--- a/packages/ui/src/components/primitives/button.tsx
+++ b/packages/ui/src/components/primitives/button.tsx
@@ -1,4 +1,5 @@
 import { Slot } from '@radix-ui/react-slot';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { Link } from '@tanstack/react-router';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { Loader2, type LucideIcon } from 'lucide-react';
@@ -6,16 +7,20 @@ import * as React from 'react';
 
 import { cn } from '../../lib/cn';
 import { SkeletonBox } from '../feedback/skeleton';
+import { TooltipContent } from '../overlays/tooltip';
 
 export const buttonVariants = cva(
   'inline-flex items-center justify-center whitespace-nowrap rounded-lg text-sm font-medium transition-all duration-150 active:scale-[0.97] active:duration-75 motion-reduce:active:scale-100 motion-reduce:transition-none focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 disabled:active:scale-100 disabled:hover:opacity-50 leading-none ring-offset-background cursor-pointer',
   {
     variants: {
+      // One height fits all (`h-9`), with a single smaller variant (`h-8`) for
+      // dense bars/toolbars. Icon-only buttons are the same two heights, square.
+      // There is deliberately no `lg` — page CTAs use the default height too.
       size: {
-        default: 'px-4 py-3 grow-0',
-        sm: 'rounded-md px-3 py-2 text-xs grow-0',
-        lg: 'px-8 py-3.5',
-        icon: 'p-2',
+        default: 'h-9 px-4 grow-0',
+        sm: 'h-8 rounded-md px-3 text-xs grow-0',
+        icon: 'size-9',
+        'icon-sm': 'size-8 rounded-md',
       },
       variant: {
         primary:
@@ -27,7 +32,9 @@ export const buttonVariants = cva(
         secondary:
           'bg-bg-base text-fg-base ring-1 ring-border-strong ring-inset shadow-sm hover:bg-bg-elevated',
         ghost: 'text-fg-base hover:bg-bg-elevated',
-        link: 'text-fg-base px-0 py-1 relative after:content-[""] after:block after:w-full after:h-[1px] after:transition-all after:duration-300 after:ease-in-out after:absolute after:bottom-0 after:left-0 hover:after:bg-fg-base',
+        // `h-auto` resets the size axis's fixed height so a link button stays
+        // inline-sized (it's text, not a control box).
+        link: 'text-fg-base h-auto px-0 py-1 relative after:content-[""] after:block after:w-full after:h-[1px] after:transition-all after:duration-300 after:ease-in-out after:absolute after:bottom-0 after:left-0 hover:after:bg-fg-base',
       },
     },
     defaultVariants: {
@@ -37,10 +44,10 @@ export const buttonVariants = cva(
   },
 );
 
-export interface ButtonProps
+interface ButtonOwnProps
   extends
     React.ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {
+    Omit<VariantProps<typeof buttonVariants>, 'size'> {
   asChild?: boolean;
   isLoading?: boolean;
   /** Icon to display before the button text */
@@ -57,10 +64,51 @@ export interface ButtonProps
    * and action rows where labels would otherwise overlap on mobile.
    */
   collapseLabel?: boolean;
+  /**
+   * One-stop label for icon buttons: a plain-string `title` populates BOTH the
+   * `aria-label` (accessibility) AND a hover/focus tooltip, so callers set a
+   * single prop instead of repeating themselves. The native `title` attribute
+   * is suppressed so there's no duplicate browser tooltip. An explicit
+   * `aria-label` or `tooltip` overrides the respective half.
+   */
+  title?: string;
+  /**
+   * Rich tooltip content (overrides `title` for the visible tooltip only).
+   * Use when the tooltip needs more than the plain accessible name — e.g. a
+   * keyboard-shortcut badge. Rendered with the shared Tooltip primitive, and
+   * NEVER when `asChild` is set (the button is then a Radix `Slot`, usually
+   * another overlay's trigger, and wrapping a Slot in a tooltip trigger breaks
+   * that composition).
+   */
+  tooltip?: React.ReactNode;
+  /** Side the tooltip opens on (default `top`). */
+  tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
 }
 
-// Plain control — the real button. No skeleton logic of its own.
-const ButtonBase = React.forwardRef<HTMLButtonElement, ButtonProps>(
+type ButtonSize = NonNullable<VariantProps<typeof buttonVariants>['size']>;
+
+/**
+ * Icon-only buttons (`size="icon"` / `"icon-sm"`) MUST be named — there's no
+ * visible text. Enforced at the type level: a button must carry a `title`
+ * (which becomes both the label and a tooltip), OR an explicit `aria-label`, OR
+ * be a non-icon size. Phrasing it as "labeled OR non-icon" (rather than
+ * discriminating on `size`) keeps dynamic `size={cond ? 'sm' : 'icon'}` buttons
+ * valid as long as they're labeled — a plain `size`-discriminated union would
+ * reject those outright.
+ */
+export type ButtonProps = ButtonOwnProps &
+  (
+    | ({ size?: ButtonSize | null } & { 'aria-label': string })
+    | ({ size?: ButtonSize | null } & { title: string })
+    | { size?: Exclude<ButtonSize, 'icon' | 'icon-sm'> | null }
+  );
+
+// Loose internal props — the wrapper has already resolved title → aria-label
+// and stripped the tooltip props, so the base never sees them.
+type ButtonBaseProps = ButtonOwnProps & { size?: ButtonSize | null };
+
+// Plain control — the real button. No skeleton/tooltip logic of its own.
+const ButtonBase = React.forwardRef<HTMLButtonElement, ButtonBaseProps>(
   (
     {
       className,
@@ -137,11 +185,41 @@ ButtonBase.displayName = 'ButtonBase';
  * with an overlay at its exact size.
  */
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  (props, ref) => (
-    <SkeletonBox fullWidth={props.fullWidth}>
-      <ButtonBase {...props} ref={ref} />
-    </SkeletonBox>
-  ),
+  ({ tooltip, tooltipSide, title, 'aria-label': ariaLabel, ...props }, ref) => {
+    // `title` shows a tooltip for any button, and ALSO names icon-only buttons
+    // (they have no visible text). Text buttons keep their accessible name from
+    // their children — `title` must NOT override it there — so the name only
+    // falls back to `title` for `size="icon"`. The native `title` attribute is
+    // dropped either way so the browser doesn't pop a duplicate tooltip.
+    const accessibleName =
+      ariaLabel ??
+      (props.size === 'icon' || props.size === 'icon-sm' ? title : undefined);
+    const tip = tooltip ?? title;
+    const base = (
+      <ButtonBase {...props} aria-label={accessibleName} ref={ref} />
+    );
+    // The tooltip Trigger must wrap the REAL button (`ButtonBase` forwards its
+    // ref + props), never the `SkeletonBox` span — a plain span drops the
+    // Trigger's injected handlers/ref, leaving the tooltip permanently shut.
+    // So the Trigger goes inside and `SkeletonBox` wraps the whole thing.
+    // No tooltip when `asChild` — the button is then a Radix `Slot` (typically
+    // another overlay's trigger), and wrapping a Slot in a tooltip trigger
+    // breaks that composition.
+    const withTooltip =
+      tip == null || props.asChild ? (
+        base
+      ) : (
+        <TooltipPrimitive.Provider delayDuration={300}>
+          <TooltipPrimitive.Root>
+            <TooltipPrimitive.Trigger asChild>{base}</TooltipPrimitive.Trigger>
+            <TooltipPrimitive.Portal>
+              <TooltipContent side={tooltipSide}>{tip}</TooltipContent>
+            </TooltipPrimitive.Portal>
+          </TooltipPrimitive.Root>
+        </TooltipPrimitive.Provider>
+      );
+    return <SkeletonBox fullWidth={props.fullWidth}>{withTooltip}</SkeletonBox>;
+  },
 );
 Button.displayName = 'Button';
 
diff --git a/packages/ui/src/components/primitives/icon-button.stories.tsx b/packages/ui/src/components/primitives/icon-button.stories.tsx
index 3ce921603b..e9105ecd5f 100644
--- a/packages/ui/src/components/primitives/icon-button.stories.tsx
+++ b/packages/ui/src/components/primitives/icon-button.stories.tsx
@@ -116,6 +116,23 @@ export const AllSizes: Story = {
   ),
 };
 
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <IconButton icon={Edit} aria-label="Default height" size="default" />
+      <IconButton icon={Edit} aria-label="Small height" size="sm" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The button height axis: `default` is the standard h-9 square; `sm` is the h-8 square for dense bars and toolbars. (This is the button box size — use `iconSize` to change the glyph size within it.)',
+      },
+    },
+  },
+};
+
 export const CommonActions: Story = {
   render: () => (
     <div className="flex items-center gap-2 rounded-lg border p-4">
diff --git a/packages/ui/src/components/primitives/icon-button.tsx b/packages/ui/src/components/primitives/icon-button.tsx
index b705b6885c..0cc6b45080 100644
--- a/packages/ui/src/components/primitives/icon-button.tsx
+++ b/packages/ui/src/components/primitives/icon-button.tsx
@@ -35,6 +35,11 @@ interface IconButtonProps
   icon: LucideIcon;
   /** Additional className for the icon element */
   iconClassName?: string;
+  /**
+   * Control height: `'default'` is the standard h-9 square button; `'sm'` is
+   * the h-8 square for dense bars/toolbars. Mirrors the Button size axis.
+   */
+  size?: 'default' | 'sm';
   /** Accessible label for the button (required for accessibility) */
   'aria-label': string;
   /**
@@ -58,14 +63,22 @@ export const IconButton = forwardRef<
       iconSize,
       iconClassName,
       variant = 'ghost',
+      size = 'default',
       className,
       'aria-label': ariaLabel,
+      tooltip,
       asChild,
       slotChild,
       ...props
     },
     ref,
   ) => {
+    // Map the IconButton's two heights onto the Button's square icon sizes.
+    const buttonSize = size === 'sm' ? 'icon-sm' : 'icon';
+    // An icon button always has an accessible name (`aria-label`), so show it
+    // as a tooltip for free unless the caller supplies richer `tooltip`
+    // content. Skipped for the `asChild` (Slot) path below.
+    const resolvedTooltip = tooltip ?? ariaLabel;
     const iconNode = (
       <Icon
         className={cn(
@@ -92,7 +105,7 @@ export const IconButton = forwardRef<
           ref={ref}
           asChild
           variant={variant}
-          size="icon"
+          size={buttonSize}
           aria-label={ariaLabel}
           className={cn(focusOverride, className)}
           {...props}
@@ -106,8 +119,9 @@ export const IconButton = forwardRef<
       <Button
         ref={ref}
         variant={variant}
-        size="icon"
+        size={buttonSize}
         aria-label={ariaLabel}
+        tooltip={resolvedTooltip}
         className={cn(focusOverride, className)}
         {...props}
       >
diff --git a/packages/ui/src/components/primitives/image.stories.tsx b/packages/ui/src/components/primitives/image.stories.tsx
new file mode 100644
index 0000000000..f56b33e940
--- /dev/null
+++ b/packages/ui/src/components/primitives/image.stories.tsx
@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Image } from './image';
+
+const SAMPLE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='100'%3E%3Crect width='160' height='100' fill='%237c9cf5'/%3E%3C/svg%3E";
+const FALLBACK =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='100'%3E%3Crect width='160' height='100' fill='%23e2e8f0'/%3E%3C/svg%3E";
+
+const meta: Meta<typeof Image> = {
+  title: 'Primitives/Image',
+  component: Image,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Image>;
+
+export const Default: Story = {
+  render: () => (
+    <Image
+      src={SAMPLE}
+      alt="A sample banner"
+      className="rounded-md"
+      width={160}
+      height={100}
+    />
+  ),
+};
+
+/** On load error the component swaps in `fallbackSrc`. */
+export const ErrorFallback: Story = {
+  render: () => (
+    <Image
+      src="https://invalid.example/missing.png"
+      fallbackSrc={FALLBACK}
+      alt="Falls back when the source is unreachable"
+      className="rounded-md"
+      width={160}
+      height={100}
+    />
+  ),
+};
+
+/** A decorative image takes an empty `alt` so screen readers skip it. */
+export const Decorative: Story = {
+  render: () => (
+    <Image
+      src={SAMPLE}
+      alt=""
+      className="rounded-md"
+      width={160}
+      height={100}
+    />
+  ),
+};
diff --git a/packages/ui/src/components/primitives/image.test.tsx b/packages/ui/src/components/primitives/image.test.tsx
new file mode 100644
index 0000000000..b61bee067d
--- /dev/null
+++ b/packages/ui/src/components/primitives/image.test.tsx
@@ -0,0 +1,23 @@
+import { describe, it } from 'vitest';
+
+import { checkAccessibility } from '@/tests/utils/a11y';
+import { render } from '@/tests/utils/render';
+
+import { Image } from './image';
+
+const SAMPLE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='40' height='40'%3E%3Crect width='40' height='40' fill='%23ccc'/%3E%3C/svg%3E";
+
+describe('Image', () => {
+  describe('accessibility', () => {
+    it('passes axe audit with descriptive alt text', async () => {
+      const { container } = render(<Image src={SAMPLE} alt="Company logo" />);
+      await checkAccessibility(container);
+    });
+
+    it('passes axe audit for a decorative image (empty alt)', async () => {
+      const { container } = render(<Image src={SAMPLE} alt="" />);
+      await checkAccessibility(container);
+    });
+  });
+});
diff --git a/packages/ui/src/globals.css b/packages/ui/src/globals.css
index d3108d402f..81d7aba34a 100644
--- a/packages/ui/src/globals.css
+++ b/packages/ui/src/globals.css
@@ -45,6 +45,16 @@
  */
 
 @theme {
+  /* Brand font tokens. Without these, Tailwind v4's `font-sans`/`font-mono`
+     utilities resolve to its built-in *system* stacks instead of Inter, so any
+     element carrying `font-sans` (e.g. the platform `<body>`) overrides the
+     `@layer base` Inter rule with the system font. Defining them here makes the
+     utilities — and the Preflight `--default-font-family` derived from
+     `--font-sans` — resolve to the bundled Inter stack everywhere. The `--font-mono`
+     value matches the json-diff-viewer stack below. */
+  --font-sans: 'Inter', 'Inter Fallback', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+
   --color-bg-base: #ffffff;
   --color-bg-elevated: #f9fafb;
   --color-bg-muted: #f3f4f6;
@@ -131,6 +141,16 @@
   --color-chart-4: hsl(var(--chart-4));
   --color-chart-5: hsl(var(--chart-5));
 
+  /* Semantic chart fills — theme-aware via the raw `--chart-*` tokens defined
+     in `:root` / `.dark`. Charts must read these (e.g. `var(--color-chart-success)`
+     or the `bg-chart-success` utility) rather than hardcoding hex, so dark mode
+     resolves correctly. See packages/ui/src/lib/chart-theme.ts. */
+  --color-chart-success: hsl(var(--chart-success));
+  --color-chart-failure: hsl(var(--chart-failure));
+  --color-chart-warning: hsl(var(--chart-warning));
+  --color-chart-neutral: hsl(var(--chart-neutral));
+  --color-chart-primary: hsl(var(--chart-primary));
+
   --radius-sm: 0.375rem;
   --radius-md: 0.5rem;
   --radius-lg: var(--radius, 0.5rem);
@@ -206,6 +226,13 @@
   --chart-3: 197 37% 24%;
   --chart-4: 43 74% 66%;
   --chart-5: 27 87% 67%;
+  /* Semantic chart fills (light). Tuned for legibility on light surfaces;
+     dark equivalents live in `.dark` below. */
+  --chart-success: 158 64% 39%;
+  --chart-failure: 0 72% 51%;
+  --chart-warning: 38 92% 50%;
+  --chart-neutral: 240 4% 60%;
+  --chart-primary: 217 91% 60%;
   --radius: 0.5rem;
   --chat-max-width: 48rem;
 }
@@ -281,6 +308,13 @@
   --chart-3: 30 80% 55%;
   --chart-4: 280 65% 60%;
   --chart-5: 340 75% 55%;
+  /* Semantic chart fills (dark) — lifted lightness/saturation for contrast on
+     the near-black dark surface. */
+  --chart-success: 158 58% 52%;
+  --chart-failure: 0 84% 68%;
+  --chart-warning: 43 96% 56%;
+  --chart-neutral: 0 0% 55%;
+  --chart-primary: 213 94% 68%;
 }
 
 @media (prefers-reduced-motion: reduce) {
diff --git a/packages/ui/src/i18n/tests/glossary/glossary.json b/packages/ui/src/i18n/tests/glossary/glossary.json
index 6ed2d83892..e5311d8bfe 100644
--- a/packages/ui/src/i18n/tests/glossary/glossary.json
+++ b/packages/ui/src/i18n/tests/glossary/glossary.json
@@ -417,7 +417,7 @@
       "en": "Chat with AI",
       "de": "Chat mit KI",
       "fr": "Discuter avec l'IA",
-      "_note": "Matches UI label `navigation.chatWithAI`."
+      "_note": "Chat-module feature phrasing (e.g. the chat page meta description). The side-nav entry is the action label `navigation.newChat`."
     },
     {
       "key": "feature_conversations",
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index c12426a4fd..4c36cf1900 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -39,6 +39,25 @@ export {
 
 export { Container, type ContainerProps } from './components/layout/container';
 export { Section, type SectionProps } from './components/layout/section';
+export {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardGrid,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+  cardVariants,
+  type CardGridProps,
+  type CardProps,
+} from './components/layout/card';
+export {
+  StatCard,
+  StatCardGrid,
+  type StatCardGridProps,
+  type StatCardProps,
+} from './components/data-display/stat-card-grid';
 
 export {
   Tooltip,
diff --git a/packages/ui/src/lib/chart-theme.ts b/packages/ui/src/lib/chart-theme.ts
new file mode 100644
index 0000000000..bf4ba5fd3d
--- /dev/null
+++ b/packages/ui/src/lib/chart-theme.ts
@@ -0,0 +1,67 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * The single source of truth for chart styling across the platform.
+ *
+ * Every color is a `var(--color-chart-*)` reference (defined in
+ * `packages/ui/src/globals.css` for both `:root` and `.dark`) — never a
+ * hardcoded hex. This is what makes charts theme-aware: the same token resolves
+ * to a light- or dark-tuned value depending on the surrounding `.dark` scope.
+ * Consumers (recharts wrappers, the SVG Sparkline, legend swatches) pull from
+ * here so all charts share one palette.
+ */
+
+/** Semantic chart fills — outcome-coded (success/failure) + supporting hues. */
+export const CHART_COLORS = {
+  success: 'var(--color-chart-success)',
+  failure: 'var(--color-chart-failure)',
+  warning: 'var(--color-chart-warning)',
+  neutral: 'var(--color-chart-neutral)',
+  primary: 'var(--color-chart-primary)',
+} as const;
+
+export type ChartColorName = keyof typeof CHART_COLORS;
+
+/** Categorical palette for multi-series charts without an inherent meaning. */
+export const CHART_SERIES = [
+  'var(--color-chart-1)',
+  'var(--color-chart-2)',
+  'var(--color-chart-3)',
+  'var(--color-chart-4)',
+  'var(--color-chart-5)',
+] as const;
+
+/** Pick a categorical series color by index, wrapping around the palette. */
+export function getChartSeriesColor(index: number): string {
+  return CHART_SERIES[
+    ((index % CHART_SERIES.length) + CHART_SERIES.length) % CHART_SERIES.length
+  ];
+}
+
+/**
+ * Shared recharts `<Tooltip contentStyle>` so every chart tooltip looks the
+ * same. Uses the hsl-wrapped `--color-*` tokens (NOT the raw `--popover` HSL
+ * triple, which is not a valid standalone color value).
+ */
+export const CHART_TOOLTIP_CONTENT_STYLE: CSSProperties = {
+  fontSize: 12,
+  borderRadius: 6,
+  border: '1px solid var(--color-border)',
+  background: 'var(--color-popover)',
+  color: 'var(--color-popover-foreground)',
+};
+
+/** Shared `<CartesianGrid>` props — dashed horizontal lines only. */
+export const CHART_GRID_PROPS = {
+  strokeDasharray: '3 3',
+  vertical: false,
+  className: 'stroke-border',
+} as const;
+
+/** Shared `<XAxis>` / `<YAxis>` props — small muted ticks, no axis/tick lines. */
+export const CHART_AXIS_PROPS = {
+  tickLine: false,
+  axisLine: false,
+  tick: { fontSize: 11 },
+  className: 'text-muted-foreground',
+} as const;
diff --git a/scripts/generate-integration-icons.ts b/scripts/generate-integration-icons.ts
new file mode 100644
index 0000000000..37ee258658
--- /dev/null
+++ b/scripts/generate-integration-icons.ts
@@ -0,0 +1,90 @@
+/**
+ * Generates the integration catalog icons from a single canonical source:
+ * Iconify's `logos` collection (full-color brand marks).
+ *
+ * Each integration renders a 24x24 SVG with a baked white rounded tile so dark
+ * marks stay visible on both themes; the brand mark is scaled into a ~15px box
+ * centered in the tile (matching the existing ~62.5% mark-to-tile ratio). The
+ * backend serves these files as `data:image/svg+xml;base64,...` URIs, so they
+ * must stay self-contained static SVGs — this script is a build-time tool, not
+ * a runtime dependency.
+ *
+ * Brands absent from the `logos` set (outlook, tavily, ai-image) are authored by
+ * hand and intentionally left untouched here.
+ *
+ * Run: bun scripts/generate-integration-icons.ts
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { icons } from '@iconify-json/logos';
+import { getIconData } from '@iconify/utils';
+
+const REPO_ROOT = resolve(import.meta.dir, '..');
+const INTEGRATIONS_DIR = join(REPO_ROOT, 'builtin-configs', 'integrations');
+
+/** Tile geometry shared by every integration icon. */
+const TILE = 24;
+/** Edge of the centered content box; 15/24 ≈ the existing 62.5% ratio. */
+const MARK_BOX = 15;
+
+/**
+ * Integration slug → Iconify `logos` icon name. Only brands that exist in the
+ * set live here; adding a new logos-backed integration is one line + a re-run.
+ */
+const SLUG_TO_ICON: Record<string, string> = {
+  github: 'github-icon',
+  slack: 'slack-icon',
+  discord: 'discord-icon',
+  gmail: 'google-gmail',
+  google_drive: 'google-drive',
+  shopify: 'shopify',
+  confluence: 'confluence',
+  twilio: 'twilio-icon',
+  teams: 'microsoft-teams',
+};
+
+/** Format a number for SVG output: fixed precision with trailing zeros trimmed. */
+function num(value: number): string {
+  return Number(value.toFixed(4)).toString();
+}
+
+/** Wrap an Iconify icon body in the standard 24x24 white-tile frame. */
+function frame(body: string, width: number, height: number): string {
+  const scale = MARK_BOX / Math.max(width, height);
+  const tx = (TILE - width * scale) / 2;
+  const ty = (TILE - height * scale) / 2;
+  const transform = `translate(${num(tx)} ${num(ty)}) scale(${num(scale)})`;
+  return [
+    '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">',
+    '  <rect width="24" height="24" rx="6" fill="#FFFFFF"/>',
+    `  <g transform="${transform}">`,
+    `    ${body}`,
+    '  </g>',
+    '</svg>',
+    '',
+  ].join('\n');
+}
+
+async function main(): Promise<void> {
+  const slugs = Object.keys(SLUG_TO_ICON).sort();
+  for (const slug of slugs) {
+    const iconName = SLUG_TO_ICON[slug];
+    const data = getIconData(icons, iconName);
+    if (!data) {
+      throw new Error(
+        `Iconify logos set has no icon "${iconName}" (slug ${slug})`,
+      );
+    }
+    const width = data.width ?? icons.width ?? TILE;
+    const height = data.height ?? icons.height ?? TILE;
+    const svg = frame(data.body, width, height);
+    const outPath = join(INTEGRATIONS_DIR, slug, 'icon.svg');
+    await writeFile(outPath, svg, 'utf-8');
+    console.log(`✓ ${slug} ← logos:${iconName}`);
+  }
+  console.log(`\nGenerated ${slugs.length} integration icons.`);
+}
+
+main();
diff --git a/services/docs/app/content/frontmatter.json b/services/docs/app/content/frontmatter.json
index 8ec8277df1..d5adb54037 100644
--- a/services/docs/app/content/frontmatter.json
+++ b/services/docs/app/content/frontmatter.json
@@ -236,7 +236,7 @@
     "slug": "platform/member/environment",
     "locale": "de",
     "frontmatter": {
-      "title": "Umgebung & Geheimnisse",
+      "title": "Umgebungsvariablen & Geheimnisse",
       "description": "Deine persönlichen Umgebungsvariablen und Geheimnisse, die Tale in jede Agent-Sandbox einspeist, die du in einer Organisation startest — meist die Provider-Anmeldedaten, mit denen sich ein BYO-Agent authentifiziert."
     }
   },
@@ -1041,7 +1041,7 @@
     "locale": "de",
     "frontmatter": {
       "title": "Upgrades",
-      "description": "Wie `tale upgrade` und `tale deploy` eine Tale-Instanz vorwärtsbewegen — das Rolling-Restart-Pattern, was vor einem Upgrade zu tun ist und die Versions-Kompatibilitäts-Story."
+      "description": "Wie `tale update` eine Tale-Instanz vorwärtsbewegt — die automatische CLI-/Instanz-Versions-Angleichung, das Rolling-Restart-Pattern, was vor einem Upgrade zu tun ist und die Versions-Kompatibilitäts-Story."
     }
   },
   "de:self-hosted/operate/observability/operations": {
@@ -1356,7 +1356,7 @@
     "slug": "platform/member/environment",
     "locale": "fr",
     "frontmatter": {
-      "title": "Environnement et secrets",
+      "title": "Variables d'environnement et secrets",
       "description": "Tes variables d'environnement et secrets personnels, injectés dans chaque sandbox d'agent que tu lances dans une organisation — le plus souvent l'identifiant fournisseur avec lequel un agent BYO s'authentifie."
     }
   },
@@ -2161,7 +2161,7 @@
     "locale": "fr",
     "frontmatter": {
       "title": "Montées de version",
-      "description": "Comment `tale upgrade` et `tale deploy` font avancer une instance Tale — le pattern de redémarrage rolling, quoi faire avant une montée de version et l'histoire de la compatibilité de versions."
+      "description": "Comment `tale update` fait avancer une instance Tale — l'alignement automatique de version entre la CLI et l'instance, le pattern de redémarrage rolling, quoi faire avant une montée de version et l'histoire de la compatibilité de versions."
     }
   },
   "fr:self-hosted/operate/observability/operations": {
@@ -2476,7 +2476,7 @@
     "slug": "platform/member/environment",
     "locale": "en",
     "frontmatter": {
-      "title": "Environment & secrets",
+      "title": "Environment variables & secrets",
       "description": "Your personal environment variables and secrets, injected into every agent sandbox you run in an organisation — most often the provider credential a bring-your-own agent authenticates with."
     }
   },
@@ -3281,7 +3281,7 @@
     "locale": "en",
     "frontmatter": {
       "title": "Upgrades",
-      "description": "How `tale upgrade` and `tale deploy` move a Tale instance forward — the rolling restart pattern, what to do before an upgrade, and the version compatibility story."
+      "description": "How `tale update` moves a Tale instance forward — automatic CLI/instance version alignment, the rolling restart pattern, what to do before an upgrade, and the version compatibility story."
     }
   },
   "en:self-hosted/operate/observability/operations": {
diff --git a/services/docs/index.html b/services/docs/index.html
index 2e5cec8b40..c032bb836b 100644
--- a/services/docs/index.html
+++ b/services/docs/index.html
@@ -64,7 +64,7 @@
       title="llms-full.txt"
     />
   </head>
-  <body>
+  <body class="font-sans antialiased">
     <script>
       // Apply theme synchronously before React hydrates to avoid FOUC.
       // Mirrors logic in @tale/ui ThemeProvider (storage key, system fallback).
diff --git a/services/docs/tests/lib/markdown.ts b/services/docs/tests/lib/markdown.ts
index 5850e8b4de..23cd4a5d89 100644
--- a/services/docs/tests/lib/markdown.ts
+++ b/services/docs/tests/lib/markdown.ts
@@ -105,6 +105,18 @@ function stripFences(text: string): string {
   return out.join('\n');
 }
 
+/**
+ * Strip every HTML comment (`<!-- … -->`, single- or multi-line) from `text`,
+ * replacing each non-newline character with a space so line numbers and line
+ * count stay stable. HTML comments are invisible structural markers (e.g. the
+ * `<!-- MODELS_TABLE:START -->` fences a generator writes between), never prose,
+ * so prose mechanics must not scan them — the `<!--` opener alone would trip the
+ * no-exclamation rule.
+ */
+function stripHtmlComments(text: string): string {
+  return text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
+}
+
 /**
  * Mask every inline-code span (` `…` `) in a single line, replacing the entire
  * span (including the backticks) with spaces of equal length. Keeps the line
@@ -143,7 +155,7 @@ function maskUrls(line: string): string {
 export function* iterProseLines(
   body: string,
 ): Iterable<{ line: number; text: string }> {
-  const stripped = stripFences(body);
+  const stripped = stripHtmlComments(stripFences(body));
   const lines = stripped.split('\n');
   for (let i = 0; i < lines.length; i++) {
     const masked = maskUrls(maskInlineCode(lines[i]));
diff --git a/services/platform/.storybook/main.ts b/services/platform/.storybook/main.ts
index 381c945a1b..d14d8ce51d 100644
--- a/services/platform/.storybook/main.ts
+++ b/services/platform/.storybook/main.ts
@@ -9,6 +9,7 @@ export default defineStorybookMain({
     '../app/components/ui/**/*.stories.@(ts|tsx)',
     '../app/components/icons/**/*.stories.@(ts|tsx)',
     '../app/components/theme/**/*.stories.@(ts|tsx)',
+    '../app/components/metrics/**/*.stories.@(ts|tsx)',
   ],
   staticDirs: ['../public'],
   async viteFinal(viteConfig) {
diff --git a/services/platform/app/components/catalog/catalog-grid.tsx b/services/platform/app/components/catalog/catalog-grid.tsx
index 95ab350a3e..1efb91ec79 100644
--- a/services/platform/app/components/catalog/catalog-grid.tsx
+++ b/services/platform/app/components/catalog/catalog-grid.tsx
@@ -1,7 +1,6 @@
 'use client';
 
-import { Card } from '@tale/ui/card';
-import { Grid } from '@tale/ui/layout';
+import { Card, CardGrid, CardMedia } from '@tale/ui/card';
 import { type ReactNode } from 'react';
 
 import { cn } from '@/lib/utils/cn';
@@ -11,12 +10,11 @@ import { cn } from '@/lib/utils/cn';
  * that lays them out. Used by every "browse and act" surface (the integrations,
  * agents, and automations catalogs) so they stay visually identical.
  *
- * Why a dedicated card instead of `<Card>` directly: the `Card` primitive wraps
- * its children in a `p-6` content box, so callers that ALSO padded the outer
- * frame (the old agent catalog did `<Card className="p-4">`) double-padded and
- * the cards ballooned. `CatalogCard` owns a single `p-4` content box and slots
- * (media, title, badge, description, meta, actions), keeping every catalog card
- * sized to its content.
+ * `CatalogCard` is the catalog-specific composition of the `@tale/ui/card`
+ * primitive: a single `padding="md"` box with the catalog slots (media, title,
+ * badge, description, meta, actions). The grid and media tile delegate straight
+ * to the shared `CardGrid` / `CardMedia` so every catalog stays aligned with the
+ * rest of the app's cards.
  */
 
 /** Responsive catalog grid: 1 → 2 (sm) → 3 (lg) columns. */
@@ -27,24 +25,16 @@ export function CatalogGrid({
   children: ReactNode;
   className?: string;
 }) {
-  return (
-    <Grid cols={1} sm={2} lg={3} gap={4} className={className}>
-      {children}
-    </Grid>
-  );
+  return <CardGrid className={className}>{children}</CardGrid>;
 }
 
 /**
  * A 40px bordered media tile for a catalog card (brand glyph, icon, or avatar),
  * so icon sizing is identical across catalogs. Render an `<img>`/`<Icon>` (≈24px)
- * inside it.
+ * inside it. Thin alias over the shared `CardMedia`.
  */
 export function CatalogCardIcon({ children }: { children: ReactNode }) {
-  return (
-    <span className="border-border bg-background flex size-10 shrink-0 items-center justify-center rounded-lg border">
-      {children}
-    </span>
-  );
+  return <CardMedia>{children}</CardMedia>;
 }
 
 interface CatalogCardProps {
@@ -112,22 +102,20 @@ export function CatalogCard({
     </>
   );
 
-  const frameClass = cn(
-    'h-full',
-    interactive && 'hover:border-primary/50 transition-colors',
-    active && 'border-primary/50',
-    className,
-  );
-
   if (interactive) {
     return (
-      <Card className={frameClass} contentClassName="h-full p-0">
+      <Card
+        asChild
+        interactive
+        padding="md"
+        className={cn('h-full', active && 'border-border-strong', className)}
+      >
         <button
           type="button"
           onClick={onClick}
           disabled={disabled}
           aria-label={ariaLabel}
-          className="focus-visible:ring-ring flex h-full w-full flex-col p-4 text-left outline-none focus-visible:ring-2 disabled:opacity-50"
+          className="flex h-full w-full flex-col text-left disabled:opacity-50"
         >
           {inner}
         </button>
@@ -136,7 +124,14 @@ export function CatalogCard({
   }
 
   return (
-    <Card className={frameClass} contentClassName="flex h-full flex-col p-4">
+    <Card
+      padding="md"
+      className={cn(
+        'flex h-full flex-col',
+        active && 'border-border-strong',
+        className,
+      )}
+    >
       {inner}
     </Card>
   );
diff --git a/services/platform/app/components/env/env-var-list-editor.tsx b/services/platform/app/components/env/env-var-list-editor.tsx
index 6b951413c4..d28b7f31e3 100644
--- a/services/platform/app/components/env/env-var-list-editor.tsx
+++ b/services/platform/app/components/env/env-var-list-editor.tsx
@@ -267,7 +267,6 @@ export function EnvVarListEditor({
       ))}
       <HStack gap={2} className="justify-between">
         <Button
-          size="sm"
           variant="ghost"
           disabled={busy}
           className="self-start"
@@ -276,7 +275,7 @@ export function EnvVarListEditor({
           <Plus className="size-4" />
           {t('add')}
         </Button>
-        <Button size="sm" onClick={() => void onSave()} disabled={busy}>
+        <Button onClick={() => void onSave()} disabled={busy}>
           {saving ? t('saving') : t('save')}
         </Button>
       </HStack>
diff --git a/services/platform/app/components/error-boundaries/displays/global-error-display.tsx b/services/platform/app/components/error-boundaries/displays/global-error-display.tsx
index 82835ed21c..6bcd24c5e1 100644
--- a/services/platform/app/components/error-boundaries/displays/global-error-display.tsx
+++ b/services/platform/app/components/error-boundaries/displays/global-error-display.tsx
@@ -125,7 +125,6 @@ export function GlobalErrorDisplay({ error, reset }: GlobalErrorDisplayProps) {
           <Button
             type="button"
             variant="ghost"
-            size="sm"
             icon={showError ? ChevronUp : ChevronDown}
             iconClassName="size-3.5"
             onClick={() => setShowError((v) => !v)}
diff --git a/services/platform/app/components/flow/flow-canvas.tsx b/services/platform/app/components/flow/flow-canvas.tsx
index ad8a4c50e9..a4689c394f 100644
--- a/services/platform/app/components/flow/flow-canvas.tsx
+++ b/services/platform/app/components/flow/flow-canvas.tsx
@@ -53,8 +53,8 @@ function FlowCornerControls() {
       <Button
         size="icon"
         variant="secondary"
-        aria-label={t('flow.zoomIn')}
         title={t('flow.zoomIn')}
+        tooltipSide="right"
         onClick={() => void zoomIn({ duration: 150 })}
       >
         <Plus className="size-4" />
@@ -62,8 +62,8 @@ function FlowCornerControls() {
       <Button
         size="icon"
         variant="secondary"
-        aria-label={t('flow.zoomOut')}
         title={t('flow.zoomOut')}
+        tooltipSide="right"
         onClick={() => void zoomOut({ duration: 150 })}
       >
         <Minus className="size-4" />
@@ -71,8 +71,8 @@ function FlowCornerControls() {
       <Button
         size="icon"
         variant="secondary"
-        aria-label={t('flow.resetView')}
         title={t('flow.resetView')}
+        tooltipSide="right"
         onClick={() => void fitView({ padding: 0.2, duration: 300 })}
       >
         <Maximize className="size-4" />
@@ -101,7 +101,6 @@ function FlowCenterToolbar({
         {onOpenAi && (
           <Button
             size="icon"
-            aria-label={t('flow.aiEditor')}
             title={t('flow.aiEditor')}
             onClick={onOpenAi}
             className="bg-purple-600 text-white hover:bg-purple-700 dark:bg-purple-700 dark:hover:bg-purple-800"
diff --git a/services/platform/app/components/layout/mobile-bottom-nav.tsx b/services/platform/app/components/layout/mobile-bottom-nav.tsx
index cd74dc5ba3..96d2688dab 100644
--- a/services/platform/app/components/layout/mobile-bottom-nav.tsx
+++ b/services/platform/app/components/layout/mobile-bottom-nav.tsx
@@ -93,7 +93,7 @@ export function MobileBottomNav({ organizationId }: MobileBottomNavProps) {
       },
       {
         key: 'chat',
-        label: tNav('chatWithAI'),
+        label: tNav('chat'),
         icon: MessageCircle,
         to: `/dashboard/${organizationId}/chat`,
         activePrefix: `/dashboard/${organizationId}/chat`,
diff --git a/services/platform/app/components/metrics/charts/charts.stories.tsx b/services/platform/app/components/metrics/charts/charts.stories.tsx
new file mode 100644
index 0000000000..4d376a2d57
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/charts.stories.tsx
@@ -0,0 +1,157 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
+
+import { DonutChart } from './donut-chart';
+import { TrendAreaChart } from './trend-area-chart';
+import { TrendBarChart } from './trend-bar-chart';
+import { TrendLineChart } from './trend-line-chart';
+import { seriesToLegend, segmentsToLegend, type ChartSeries } from './types';
+
+/**
+ * The generic chart family — thin recharts wrappers on shared chart-theme
+ * tokens, designed to live inside a `<ChartCard>`. These render the chart BODY
+ * only; the card supplies the title/legend/loading/empty chrome.
+ */
+const meta: Meta = {
+  title: 'Metrics/Charts',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const shortDay = (key: string) => key.slice(5); // 2026-06-12 → 06-12
+
+const trendData = [
+  { day: '2026-06-10', completed: 24, failed: 2 },
+  { day: '2026-06-11', completed: 31, failed: 1 },
+  { day: '2026-06-12', completed: 18, failed: 4 },
+  { day: '2026-06-13', completed: 40, failed: 3 },
+  { day: '2026-06-14', completed: 36, failed: 0 },
+];
+
+const runSeries: ChartSeries[] = [
+  {
+    key: 'completed',
+    label: 'Completed',
+    color: CHART_COLORS.success,
+    stackId: 'runs',
+  },
+  {
+    key: 'failed',
+    label: 'Failed',
+    color: CHART_COLORS.failure,
+    stackId: 'runs',
+  },
+];
+
+export const StackedBar: Story = {
+  render: () => (
+    <div className="max-w-2xl">
+      <ChartCard
+        title="Execution trend"
+        tooltip="Completed vs failed runs per day."
+        legend={<ChartLegend items={seriesToLegend(runSeries)} />}
+      >
+        <TrendBarChart
+          data={trendData}
+          series={runSeries}
+          xKey="day"
+          xTickFormatter={shortDay}
+        />
+      </ChartCard>
+    </div>
+  ),
+};
+
+export const Line: Story = {
+  render: () => (
+    <div className="max-w-2xl">
+      <ChartCard title="Cycle time">
+        <TrendLineChart
+          data={trendData.map((d) => ({ day: d.day, hours: d.completed / 4 }))}
+          series={[
+            { key: 'hours', label: 'Avg hours', color: CHART_COLORS.primary },
+          ]}
+          xKey="day"
+          xTickFormatter={shortDay}
+          valueFormatter={(v) => `${v.toFixed(1)}h`}
+        />
+      </ChartCard>
+    </div>
+  ),
+};
+
+export const StackedArea: Story = {
+  render: () => {
+    const flow: ChartSeries[] = [
+      { key: 'backlog', label: 'Backlog', color: CHART_COLORS.neutral },
+      { key: 'inProgress', label: 'In progress', color: CHART_COLORS.primary },
+      { key: 'done', label: 'Done', color: CHART_COLORS.success },
+    ];
+    const data = trendData.map((d, i) => ({
+      day: d.day,
+      backlog: 20 - i * 2,
+      inProgress: 5 + i,
+      done: d.completed,
+    }));
+    return (
+      <div className="max-w-2xl">
+        <ChartCard
+          title="Cumulative flow"
+          legend={<ChartLegend items={seriesToLegend(flow)} />}
+        >
+          <TrendAreaChart
+            data={data}
+            series={flow}
+            xKey="day"
+            xTickFormatter={shortDay}
+          />
+        </ChartCard>
+      </div>
+    );
+  },
+};
+
+export const Donut: Story = {
+  render: () => {
+    const segments = [
+      {
+        key: 'completed',
+        label: 'Completed',
+        value: 149,
+        color: CHART_COLORS.success,
+      },
+      {
+        key: 'failed',
+        label: 'Failed',
+        value: 10,
+        color: CHART_COLORS.failure,
+      },
+      {
+        key: 'running',
+        label: 'Running',
+        value: 6,
+        color: CHART_COLORS.neutral,
+      },
+    ];
+    const total = segments.reduce((sum, s) => sum + s.value, 0);
+    return (
+      <div className="max-w-md">
+        <ChartCard
+          title="Status breakdown"
+          bodyClassName="h-52"
+          legend={<ChartLegend items={segmentsToLegend(segments)} />}
+        >
+          <DonutChart
+            segments={segments}
+            centerValue={total}
+            centerLabel="Total"
+          />
+        </ChartCard>
+      </div>
+    );
+  },
+};
diff --git a/services/platform/app/components/metrics/charts/donut-chart.tsx b/services/platform/app/components/metrics/charts/donut-chart.tsx
new file mode 100644
index 0000000000..d8b05be15f
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/donut-chart.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import { CHART_TOOLTIP_CONTENT_STYLE } from '@tale/ui/chart-theme';
+import { type ReactNode } from 'react';
+import { Cell, Pie, PieChart, ResponsiveContainer, Tooltip } from 'recharts';
+
+import type { DonutSegment } from './types';
+
+interface DonutChartProps {
+  segments: readonly DonutSegment[];
+  /** Big number shown in the ring center (e.g. the total). */
+  centerValue?: ReactNode;
+  /** Caption under the center value. */
+  centerLabel?: string;
+  /** Format segment values in the tooltip. */
+  valueFormatter?: (value: number) => string;
+}
+
+/**
+ * Generic donut/ring chart with an optional center total. Chart BODY only —
+ * wrap in `<ChartCard>` for the title/legend chrome (build the legend from the
+ * same segments via `segmentsToLegend`). Zero-value segments are dropped from
+ * the ring. Fills its parent.
+ */
+export function DonutChart({
+  segments,
+  centerValue,
+  centerLabel,
+  valueFormatter,
+}: DonutChartProps) {
+  const slices = segments.filter((s) => s.value > 0);
+
+  return (
+    <div className="relative flex size-full items-center justify-center">
+      <ResponsiveContainer width="100%" height="100%">
+        <PieChart>
+          <Tooltip
+            contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
+            formatter={(value) =>
+              typeof value === 'number' && valueFormatter
+                ? valueFormatter(value)
+                : String(value)
+            }
+          />
+          <Pie
+            data={slices}
+            dataKey="value"
+            nameKey="label"
+            innerRadius="62%"
+            outerRadius="92%"
+            paddingAngle={2}
+            stroke="none"
+          >
+            {slices.map((s) => (
+              <Cell key={s.key} fill={s.color} />
+            ))}
+          </Pie>
+        </PieChart>
+      </ResponsiveContainer>
+      {centerValue !== undefined || centerLabel ? (
+        <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center">
+          {centerValue !== undefined ? (
+            <span className="text-2xl font-semibold tabular-nums">
+              {centerValue}
+            </span>
+          ) : null}
+          {centerLabel ? (
+            <span className="text-muted-foreground text-xs">{centerLabel}</span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/services/platform/app/components/metrics/charts/index.ts b/services/platform/app/components/metrics/charts/index.ts
new file mode 100644
index 0000000000..f6385e1b47
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/index.ts
@@ -0,0 +1,11 @@
+export { TrendBarChart } from './trend-bar-chart';
+export { TrendLineChart } from './trend-line-chart';
+export { TrendAreaChart } from './trend-area-chart';
+export { DonutChart } from './donut-chart';
+export {
+  seriesToLegend,
+  segmentsToLegend,
+  type ChartSeries,
+  type ChartRow,
+  type DonutSegment,
+} from './types';
diff --git a/services/platform/app/components/metrics/charts/trend-area-chart.tsx b/services/platform/app/components/metrics/charts/trend-area-chart.tsx
new file mode 100644
index 0000000000..36cad2fabb
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/trend-area-chart.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import {
+  CHART_AXIS_PROPS,
+  CHART_GRID_PROPS,
+  CHART_TOOLTIP_CONTENT_STYLE,
+} from '@tale/ui/chart-theme';
+import {
+  Area,
+  AreaChart,
+  CartesianGrid,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+
+import type { ChartRow, ChartSeries } from './types';
+
+interface TrendAreaChartProps {
+  data: ChartRow[];
+  series: readonly ChartSeries[];
+  xKey: string;
+  xTickFormatter?: (value: string) => string;
+  yTickFormatter?: (value: number) => string;
+  valueFormatter?: (value: number) => string;
+  allowDecimals?: boolean;
+}
+
+/**
+ * Generic stacked area trend (e.g. cumulative flow). Chart BODY only — wrap in
+ * `<ChartCard>` for chrome. Series with the same `stackId` (default `'stack'`)
+ * stack into bands. Fills its parent.
+ */
+export function TrendAreaChart({
+  data,
+  series,
+  xKey,
+  xTickFormatter,
+  yTickFormatter,
+  valueFormatter,
+  allowDecimals = false,
+}: TrendAreaChartProps) {
+  return (
+    <ResponsiveContainer width="100%" height="100%">
+      <AreaChart data={data} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <CartesianGrid {...CHART_GRID_PROPS} />
+        <XAxis
+          dataKey={xKey}
+          tickMargin={8}
+          tickFormatter={xTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <YAxis
+          width={36}
+          allowDecimals={allowDecimals}
+          tickFormatter={yTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <Tooltip
+          contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
+          formatter={(value) =>
+            typeof value === 'number' && valueFormatter
+              ? valueFormatter(value)
+              : String(value)
+          }
+        />
+        {series.map((s) => (
+          <Area
+            key={s.key}
+            type="monotone"
+            dataKey={s.key}
+            name={s.label}
+            stackId={s.stackId ?? 'stack'}
+            stroke={s.color}
+            fill={s.color}
+            fillOpacity={0.18}
+            strokeWidth={1.5}
+          />
+        ))}
+      </AreaChart>
+    </ResponsiveContainer>
+  );
+}
diff --git a/services/platform/app/components/metrics/charts/trend-bar-chart.tsx b/services/platform/app/components/metrics/charts/trend-bar-chart.tsx
new file mode 100644
index 0000000000..8b23777d16
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/trend-bar-chart.tsx
@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  CHART_AXIS_PROPS,
+  CHART_GRID_PROPS,
+  CHART_TOOLTIP_CONTENT_STYLE,
+} from '@tale/ui/chart-theme';
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+
+import type { ChartRow, ChartSeries } from './types';
+
+interface TrendBarChartProps {
+  data: ChartRow[];
+  series: readonly ChartSeries[];
+  /** Data key for the X axis (e.g. a full date key). */
+  xKey: string;
+  /** Shorten the X tick label (the tooltip still shows the raw `xKey` value). */
+  xTickFormatter?: (value: string) => string;
+  yTickFormatter?: (value: number) => string;
+  /** Format series values in the tooltip. */
+  valueFormatter?: (value: number) => string;
+  allowDecimals?: boolean;
+}
+
+/**
+ * Generic single/stacked bar trend. The chart BODY only — wrap it in a
+ * `<ChartCard>` for the title/legend/loading/empty chrome. Series sharing a
+ * `stackId` stack together; the topmost stacked segment gets rounded corners.
+ * Fills its parent, so set the height on the `ChartCard` body.
+ */
+export function TrendBarChart({
+  data,
+  series,
+  xKey,
+  xTickFormatter,
+  yTickFormatter,
+  valueFormatter,
+  allowDecimals = false,
+}: TrendBarChartProps) {
+  return (
+    <ResponsiveContainer width="100%" height="100%">
+      <BarChart data={data} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <CartesianGrid {...CHART_GRID_PROPS} />
+        <XAxis
+          dataKey={xKey}
+          tickMargin={8}
+          tickFormatter={xTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <YAxis
+          width={36}
+          allowDecimals={allowDecimals}
+          tickFormatter={yTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <Tooltip
+          contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
+          formatter={(value) =>
+            typeof value === 'number' && valueFormatter
+              ? valueFormatter(value)
+              : String(value)
+          }
+        />
+        {series.map((s, i) => {
+          const isLast = i === series.length - 1;
+          const rounded = s.stackId ? isLast : true;
+          return (
+            <Bar
+              key={s.key}
+              dataKey={s.key}
+              name={s.label}
+              fill={s.color}
+              stackId={s.stackId}
+              radius={rounded ? [4, 4, 0, 0] : [0, 0, 0, 0]}
+            />
+          );
+        })}
+      </BarChart>
+    </ResponsiveContainer>
+  );
+}
diff --git a/services/platform/app/components/metrics/charts/trend-line-chart.tsx b/services/platform/app/components/metrics/charts/trend-line-chart.tsx
new file mode 100644
index 0000000000..36923c60ac
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/trend-line-chart.tsx
@@ -0,0 +1,83 @@
+'use client';
+
+import {
+  CHART_AXIS_PROPS,
+  CHART_GRID_PROPS,
+  CHART_TOOLTIP_CONTENT_STYLE,
+} from '@tale/ui/chart-theme';
+import {
+  CartesianGrid,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+
+import type { ChartRow, ChartSeries } from './types';
+
+interface TrendLineChartProps {
+  data: ChartRow[];
+  series: readonly ChartSeries[];
+  xKey: string;
+  xTickFormatter?: (value: string) => string;
+  yTickFormatter?: (value: number) => string;
+  valueFormatter?: (value: number) => string;
+  allowDecimals?: boolean;
+}
+
+/**
+ * Generic multi-series line trend (e.g. cycle time). Chart BODY only — wrap in
+ * `<ChartCard>` for chrome. Fills its parent.
+ */
+export function TrendLineChart({
+  data,
+  series,
+  xKey,
+  xTickFormatter,
+  yTickFormatter,
+  valueFormatter,
+  allowDecimals = true,
+}: TrendLineChartProps) {
+  return (
+    <ResponsiveContainer width="100%" height="100%">
+      <LineChart data={data} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <CartesianGrid {...CHART_GRID_PROPS} />
+        <XAxis
+          dataKey={xKey}
+          tickMargin={8}
+          tickFormatter={xTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <YAxis
+          width={36}
+          allowDecimals={allowDecimals}
+          tickFormatter={yTickFormatter}
+          {...CHART_AXIS_PROPS}
+        />
+        <Tooltip
+          contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
+          formatter={(value) =>
+            typeof value === 'number' && valueFormatter
+              ? valueFormatter(value)
+              : String(value)
+          }
+        />
+        {series.map((s) => (
+          <Line
+            key={s.key}
+            type="monotone"
+            dataKey={s.key}
+            name={s.label}
+            stroke={s.color}
+            strokeWidth={2}
+            dot={false}
+            activeDot={{ r: 3 }}
+            connectNulls
+          />
+        ))}
+      </LineChart>
+    </ResponsiveContainer>
+  );
+}
diff --git a/services/platform/app/components/metrics/charts/types.ts b/services/platform/app/components/metrics/charts/types.ts
new file mode 100644
index 0000000000..8b84dec925
--- /dev/null
+++ b/services/platform/app/components/metrics/charts/types.ts
@@ -0,0 +1,49 @@
+import type { ChartLegendItem } from '@tale/ui/chart-legend';
+
+/**
+ * One plotted series in a trend chart. `color` should be a chart-theme token
+ * (`var(--color-chart-*)` from `@tale/ui/chart-theme`) so the series matches
+ * its legend swatch and resolves correctly in dark mode. `stackId` groups
+ * series into a stack (bars/areas); omit it for grouped/overlaid series.
+ */
+export interface ChartSeries {
+  /** Key into each data row. */
+  key: string;
+  /** Already-translated display name (legend + tooltip). */
+  label: string;
+  /** Fill/stroke color — a chart-theme token. */
+  color: string;
+  /** Stack grouping id; series sharing one id stack together. */
+  stackId?: string;
+}
+
+/** A single donut segment. */
+export interface DonutSegment {
+  key: string;
+  label: string;
+  value: number;
+  color: string;
+}
+
+/** Build `ChartLegend` items from a series list (labels + swatch colors). */
+export function seriesToLegend(
+  series: readonly ChartSeries[],
+): ChartLegendItem[] {
+  return series.map((s) => ({ label: s.label, color: s.color }));
+}
+
+/** Build `ChartLegend` items (with counts) from donut segments. */
+export function segmentsToLegend(
+  segments: readonly DonutSegment[],
+  valueFormatter?: (value: number) => string,
+): ChartLegendItem[] {
+  return segments.map((s) => ({
+    label: s.label,
+    color: s.color,
+    value: valueFormatter ? valueFormatter(s.value) : s.value,
+  }));
+}
+
+/** Generic row shape accepted by the trend charts. `null` leaves a gap (e.g. a
+ *  day with no cycle-time samples). */
+export type ChartRow = Record<string, string | number | null>;
diff --git a/services/platform/app/components/metrics/metric-select.tsx b/services/platform/app/components/metrics/metric-select.tsx
new file mode 100644
index 0000000000..343f24bfce
--- /dev/null
+++ b/services/platform/app/components/metrics/metric-select.tsx
@@ -0,0 +1,42 @@
+'use client';
+
+import { Select } from '@/app/components/ui/forms/select';
+import { cn } from '@/lib/utils/cn';
+
+interface MetricSelectOption {
+  value: string;
+  label: string;
+}
+
+interface MetricSelectProps {
+  options: MetricSelectOption[];
+  value: string;
+  onValueChange: (value: string) => void;
+  'aria-label': string;
+  /** Trigger width — defaults to `w-36`; widen for long labels. */
+  widthClassName?: string;
+}
+
+/**
+ * The standard toolbar dropdown for metrics pages — a small (`size="sm"`),
+ * fixed-width `Select`. Centralizes the width + size so every period /
+ * granularity / metric selector across the metrics surfaces matches.
+ */
+export function MetricSelect({
+  options,
+  value,
+  onValueChange,
+  'aria-label': ariaLabel,
+  widthClassName = 'w-36',
+}: MetricSelectProps) {
+  return (
+    <div className={cn(widthClassName)}>
+      <Select
+        options={options}
+        value={value}
+        onValueChange={onValueChange}
+        aria-label={ariaLabel}
+      />
+    </div>
+  );
+}
diff --git a/services/platform/app/components/metrics/metrics-filter-chips.tsx b/services/platform/app/components/metrics/metrics-filter-chips.tsx
new file mode 100644
index 0000000000..e1a9c31b4f
--- /dev/null
+++ b/services/platform/app/components/metrics/metrics-filter-chips.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+import { Badge } from '@tale/ui/badge';
+import { Button } from '@tale/ui/button';
+import { HStack } from '@tale/ui/layout';
+import { X } from 'lucide-react';
+
+export interface MetricsFilterChip {
+  /** Stable key for React. */
+  key: string;
+  /** Already-translated chip label, e.g. "Agent: support-bot". */
+  label: string;
+  /** Clears just this filter. */
+  onClear: () => void;
+}
+
+interface MetricsFilterChipsProps {
+  chips: MetricsFilterChip[];
+  onClearAll: () => void;
+  /** Already-translated "Clear all" label. */
+  clearAllLabel: string;
+}
+
+/**
+ * The shared active-filter row used across metrics surfaces (usage, feedback).
+ * Renders nothing when there are no active filters. Caller supplies already-
+ * translated labels so this stays i18n-agnostic and reusable anywhere.
+ */
+export function MetricsFilterChips({
+  chips,
+  onClearAll,
+  clearAllLabel,
+}: MetricsFilterChipsProps) {
+  if (chips.length === 0) return null;
+
+  return (
+    <HStack gap={2} className="flex-wrap items-center">
+      {chips.map((chip) => (
+        <Badge
+          key={chip.key}
+          variant="outline"
+          className="cursor-pointer"
+          onClick={chip.onClear}
+        >
+          {chip.label}
+          <X className="ml-1 size-3" />
+        </Badge>
+      ))}
+      <Button variant="ghost" size="sm" onClick={onClearAll}>
+        {clearAllLabel}
+      </Button>
+    </HStack>
+  );
+}
diff --git a/services/platform/app/components/metrics/metrics-layout.stories.tsx b/services/platform/app/components/metrics/metrics-layout.stories.tsx
new file mode 100644
index 0000000000..c47b7f809e
--- /dev/null
+++ b/services/platform/app/components/metrics/metrics-layout.stories.tsx
@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Alert } from '@tale/ui/alert';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
+import { AlertTriangle } from 'lucide-react';
+
+import { TrendBarChart } from './charts';
+import { MetricSelect } from './metric-select';
+import { MetricsFilterChips } from './metrics-filter-chips';
+import { MetricsLayout } from './metrics-layout';
+
+/**
+ * The canonical metrics-page anatomy: header (title + description + toolbar) →
+ * filter chips → notices → KPI row → chart(s) → tables. Every metrics surface
+ * renders this same shell.
+ */
+const meta: Meta<typeof MetricsLayout> = {
+  title: 'Metrics/MetricsLayout',
+  component: MetricsLayout,
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof MetricsLayout>;
+
+const trend = [
+  { day: '2026-06-10', completed: 24, failed: 2 },
+  { day: '2026-06-11', completed: 31, failed: 1 },
+  { day: '2026-06-12', completed: 18, failed: 4 },
+  { day: '2026-06-13', completed: 40, failed: 3 },
+  { day: '2026-06-14', completed: 36, failed: 0 },
+];
+const series = [
+  {
+    key: 'completed',
+    label: 'Completed',
+    color: CHART_COLORS.success,
+    stackId: 'r',
+  },
+  { key: 'failed', label: 'Failed', color: CHART_COLORS.failure, stackId: 'r' },
+];
+
+export const FullAnatomy: Story = {
+  render: () => (
+    <MetricsLayout
+      title="Automation metrics"
+      description="Workflow execution health for the selected period."
+      toolbar={
+        <MetricSelect
+          aria-label="Period"
+          value="30"
+          onValueChange={() => {}}
+          options={[
+            { value: '7', label: 'Last 7 days' },
+            { value: '30', label: 'Last 30 days' },
+            { value: '90', label: 'Last 90 days' },
+          ]}
+        />
+      }
+      notice={
+        <Alert
+          variant="warning"
+          icon={AlertTriangle}
+          title="Showing a partial sample"
+          description="Results are capped; counts are lower bounds."
+        />
+      }
+    >
+      <StatCardGrid>
+        <StatCard label="Total runs" value="1,284">
+          <div className="mt-0.5">
+            <TrendIndicator value={1284} previous={1100} />
+          </div>
+        </StatCard>
+        <StatCard label="Success rate" value="98.6%">
+          <div className="mt-0.5">
+            <TrendIndicator value={98.6} previous={97.1} />
+          </div>
+        </StatCard>
+        <StatCard label="Avg duration" value="1.4s">
+          <div className="mt-0.5">
+            <TrendIndicator value={1.4} previous={1.9} inverted />
+          </div>
+        </StatCard>
+        <StatCard label="Failed runs" value="36">
+          <div className="mt-0.5">
+            <TrendIndicator value={36} previous={58} inverted />
+          </div>
+        </StatCard>
+      </StatCardGrid>
+
+      <ChartCard
+        title="Execution trend"
+        legend={
+          <ChartLegend
+            items={series.map((s) => ({ label: s.label, color: s.color }))}
+          />
+        }
+      >
+        <TrendBarChart
+          data={trend}
+          series={series}
+          xKey="day"
+          xTickFormatter={(d) => d.slice(5)}
+        />
+      </ChartCard>
+    </MetricsLayout>
+  ),
+};
+
+export const WithFilters: Story = {
+  render: () => (
+    <MetricsLayout
+      title="Usage"
+      description="LLM requests, tokens, and cost."
+      as="h3"
+      toolbar={
+        <MetricSelect
+          aria-label="Period"
+          value="30"
+          onValueChange={() => {}}
+          options={[{ value: '30', label: 'Last 30 days' }]}
+        />
+      }
+      filters={
+        <MetricsFilterChips
+          clearAllLabel="Clear all"
+          onClearAll={() => {}}
+          chips={[
+            { key: 'agent', label: 'Agent: support-bot', onClear: () => {} },
+            {
+              key: 'model',
+              label: 'Model: claude-opus-4-8',
+              onClear: () => {},
+            },
+          ]}
+        />
+      }
+    >
+      <StatCardGrid>
+        <StatCard label="Requests" value="12,480" />
+        <StatCard label="Tokens" value="3.2M" />
+        <StatCard label="Cost" value="$184.20" />
+        <StatCard label="Active users" value="312" />
+      </StatCardGrid>
+    </MetricsLayout>
+  ),
+};
diff --git a/services/platform/app/components/metrics/metrics-layout.tsx b/services/platform/app/components/metrics/metrics-layout.tsx
new file mode 100644
index 0000000000..534f92b0bd
--- /dev/null
+++ b/services/platform/app/components/metrics/metrics-layout.tsx
@@ -0,0 +1,69 @@
+'use client';
+
+import { HStack, Stack } from '@tale/ui/layout';
+import { Text } from '@tale/ui/text';
+import { type ReactNode } from 'react';
+
+import { cn } from '@/lib/utils/cn';
+
+interface MetricsLayoutProps {
+  /** Page/section title. */
+  title: string;
+  /** One-line description under the title. */
+  description?: string;
+  /** Heading element — `h2` for standalone routes, `h3` when embedded in a
+   *  settings tab that already owns the page heading. */
+  as?: 'h2' | 'h3';
+  /** Right-aligned header controls (period/granularity/metric selects). Stacks
+   *  below the title on mobile. */
+  toolbar?: ReactNode;
+  /** Active-filter chips row, shown directly under the header. */
+  filters?: ReactNode;
+  /** Notices (capped sample / empty / filtered) — pass `<Alert>`s. */
+  notice?: ReactNode;
+  /** Body: KPI row, charts, tables — in the canonical order. */
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * The shared shell for every metrics surface (automations, usage, feedback,
+ * project, agent scorecard, workforce). Gives them ONE structure — a responsive
+ * header (title + description + toolbar), a filter-chips row, a notices slot,
+ * then the body at the standard `gap-6` rhythm — so the pages stop looking
+ * hand-rolled and different. Padding-agnostic: the host (a route's
+ * `ContentArea` or a settings tab) owns the outer container.
+ */
+export function MetricsLayout({
+  title,
+  description,
+  as: Tag = 'h2',
+  toolbar,
+  filters,
+  notice,
+  children,
+  className,
+}: MetricsLayoutProps) {
+  return (
+    <Stack gap={6} className={className}>
+      <div className="flex flex-col gap-3 md:flex-row md:items-start md:justify-between">
+        <div className="flex flex-col gap-1">
+          <Tag className="text-foreground text-base font-semibold">{title}</Tag>
+          {description ? <Text variant="caption">{description}</Text> : null}
+        </div>
+        {toolbar ? (
+          <HStack gap={2} className="flex-wrap">
+            {toolbar}
+          </HStack>
+        ) : null}
+      </div>
+
+      {filters}
+      {notice ? (
+        <div className={cn('flex flex-col gap-3')}>{notice}</div>
+      ) : null}
+
+      {children}
+    </Stack>
+  );
+}
diff --git a/services/platform/app/components/ui/data-display/json-viewer.tsx b/services/platform/app/components/ui/data-display/json-viewer.tsx
index 99f68842fa..91000f4679 100644
--- a/services/platform/app/components/ui/data-display/json-viewer.tsx
+++ b/services/platform/app/components/ui/data-display/json-viewer.tsx
@@ -4,6 +4,7 @@ import { Button } from '@tale/ui/button';
 import { CheckIcon, CopyIcon } from 'lucide-react';
 import { useMemo, useState } from 'react';
 
+import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 import { lazyComponent } from '@/lib/utils/lazy-component';
 
@@ -36,6 +37,7 @@ export function JsonViewer({
   indentWidth?: number;
   className?: string;
 }) {
+  const { t } = useT('common');
   const [copied, setCopied] = useState(false);
   const json = useMemo(() => {
     try {
@@ -78,6 +80,7 @@ export function JsonViewer({
           <Button
             variant="ghost"
             size="icon"
+            title={t('actions.copy')}
             className="p-1"
             onClick={handleCopy}
           >
diff --git a/services/platform/app/components/ui/data-display/zoom-pan-viewer.test.tsx b/services/platform/app/components/ui/data-display/zoom-pan-viewer.test.tsx
index dd280c5674..6a62a7b4d0 100644
--- a/services/platform/app/components/ui/data-display/zoom-pan-viewer.test.tsx
+++ b/services/platform/app/components/ui/data-display/zoom-pan-viewer.test.tsx
@@ -9,9 +9,13 @@ vi.mock('@/lib/i18n/client', () => ({
   useT: () => ({
     t: (key: string) => {
       const translations: Record<string, string> = {
-        'imagePreview.zoomIn': 'Zoom in',
-        'imagePreview.zoomOut': 'Zoom out',
-        'imagePreview.resetZoom': 'Reset zoom',
+        // Controls reuse the automation editor's `common.flow.*` labels (and
+        // `common.aria.close`), which fixed the old missing-`imagePreview.*`
+        // fallthrough.
+        'flow.zoomIn': 'Zoom in',
+        'flow.zoomOut': 'Zoom out',
+        'flow.resetView': 'Reset view',
+        'aria.close': 'Close',
       };
       return translations[key] ?? key;
     },
@@ -43,7 +47,7 @@ describe('ZoomPanViewer', () => {
         screen.getByRole('button', { name: 'Zoom out' }),
       ).toBeInTheDocument();
       expect(
-        screen.getByRole('button', { name: 'Reset zoom' }),
+        screen.getByRole('button', { name: 'Reset view' }),
       ).toBeInTheDocument();
     });
 
@@ -131,22 +135,25 @@ describe('ZoomPanViewer', () => {
       fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }));
       expect(screen.getByText('150%')).toBeInTheDocument();
 
-      fireEvent.click(screen.getByRole('button', { name: 'Reset zoom' }));
+      fireEvent.click(screen.getByRole('button', { name: 'Reset view' }));
       expect(screen.getByText('100%')).toBeInTheDocument();
     });
 
-    it('disables reset button when not zoomed', () => {
+    it('keeps the fit/reset button enabled even when not zoomed', () => {
       render(<ZoomPanViewer {...defaultProps} />);
 
-      expect(screen.getByRole('button', { name: 'Reset zoom' })).toBeDisabled();
+      // The fit-to-screen control is always actionable (re-fits at any zoom).
+      expect(
+        screen.getByRole('button', { name: 'Reset view' }),
+      ).not.toBeDisabled();
     });
 
-    it('enables reset button when zoomed', () => {
+    it('keeps the reset button enabled when zoomed', () => {
       render(<ZoomPanViewer {...defaultProps} />);
 
       fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }));
       expect(
-        screen.getByRole('button', { name: 'Reset zoom' }),
+        screen.getByRole('button', { name: 'Reset view' }),
       ).not.toBeDisabled();
     });
   });
diff --git a/services/platform/app/components/ui/data-display/zoom-pan-viewer.tsx b/services/platform/app/components/ui/data-display/zoom-pan-viewer.tsx
index dc918a1bce..f78aabd55c 100644
--- a/services/platform/app/components/ui/data-display/zoom-pan-viewer.tsx
+++ b/services/platform/app/components/ui/data-display/zoom-pan-viewer.tsx
@@ -1,7 +1,8 @@
 'use client';
 
+import { Button } from '@tale/ui/button';
 import { Text } from '@tale/ui/text';
-import { RotateCcw, X, ZoomIn, ZoomOut } from 'lucide-react';
+import { Maximize, Minus, Plus, X } from 'lucide-react';
 import { memo, useCallback } from 'react';
 
 import { useZoomPan } from '@/app/hooks/use-zoom-pan';
@@ -85,95 +86,75 @@ export const ZoomPanViewer = memo(function ZoomPanViewer({
     [isDragging, toggleZoom],
   );
 
-  const isBottom = toolbarPosition === 'bottom';
-
-  const buttonClass = isBottom
-    ? 'grid size-8 place-items-center rounded-full transition hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-35'
-    : 'text-foreground size-8 disabled:cursor-not-allowed disabled:opacity-50';
-
-  const toolbar = (
-    <div
-      className={cn(
-        isBottom
-          ? 'bg-background text-foreground flex items-center gap-2 rounded-full px-4 py-2 shadow-xl ring-1 ring-white/10'
-          : 'bg-muted flex items-center gap-1 rounded-lg p-1',
-        toolbarClassName,
-      )}
-    >
-      <button
-        type="button"
+  // Zoom cluster modelled on the automation editor's corner controls
+  // (`flow-canvas.tsx`): shared `Button` primitives, `Minus` / `Plus` to step
+  // zoom and `Maximize` to fit, with a zoom-percentage readout between them.
+  const controls = (
+    <div className={cn('flex items-center gap-1.5', toolbarClassName)}>
+      <Button
+        variant="secondary"
+        size="icon"
+        title={t('flow.zoomOut')}
+        tooltipSide="top"
         onClick={zoomOut}
         disabled={!canZoomOut}
-        className={buttonClass}
-        aria-label={t('imagePreview.zoomOut')}
       >
-        <ZoomOut className="size-4" />
-      </button>
+        <Minus className="size-4" />
+      </Button>
       <Text
         as="span"
         align="center"
-        className="min-w-[3rem] text-sm tabular-nums"
+        className="bg-background ring-border text-foreground min-w-[3.25rem] rounded-md px-2 py-1.5 text-sm tabular-nums shadow-sm ring-1"
       >
         {Math.round(zoom * 100)}%
       </Text>
-      <button
-        type="button"
+      <Button
+        variant="secondary"
+        size="icon"
+        title={t('flow.zoomIn')}
+        tooltipSide="top"
         onClick={zoomIn}
         disabled={!canZoomIn}
-        className={buttonClass}
-        aria-label={t('imagePreview.zoomIn')}
       >
-        <ZoomIn className="size-4" />
-      </button>
-      <button
-        type="button"
+        <Plus className="size-4" />
+      </Button>
+      {/* Fit-to-screen — always enabled (re-fits even at 100%). */}
+      <Button
+        variant="secondary"
+        size="icon"
+        title={t('flow.resetView')}
+        tooltipSide="top"
         onClick={reset}
-        disabled={!isZoomed}
-        className={buttonClass}
-        aria-label={t('imagePreview.resetZoom')}
       >
-        <RotateCcw className="size-4" />
-      </button>
+        <Maximize className="size-4" />
+      </Button>
     </div>
   );
 
-  const renderToolbar = () => {
-    switch (toolbarPosition) {
-      case 'overlay':
-        return (
-          <div className="absolute top-4 right-4 left-4 z-10 flex items-center justify-between gap-2">
-            {headerContent ?? <span />}
-            <div className="flex items-center gap-2">
-              {toolbar}
-              {onClose && (
-                <button
-                  type="button"
-                  onClick={onClose}
-                  className="bg-muted text-foreground hover:bg-muted/80 grid size-8 place-items-center rounded-lg transition"
-                  // `common.imagePreview.*` is a missing group — the sibling
-                  // zoom buttons fall through to literal keys (pre-existing
-                  // bug). Use the canonical `common.aria.close` until the
-                  // group is filled in.
-                  aria-label={t('aria.close')}
-                >
-                  <X className="size-4" />
-                </button>
-              )}
-            </div>
-          </div>
-        );
-      case 'bottom':
-        return null;
-      case 'inline':
-        return <div className="mb-2 flex justify-end">{toolbar}</div>;
-      default:
-        return undefined;
-    }
-  };
-
   return (
-    <div className={cn('relative flex flex-1 flex-col min-h-0', className)}>
-      {renderToolbar()}
+    <div className={cn('relative flex min-h-0 flex-1 flex-col', className)}>
+      {toolbarPosition === 'overlay' && (
+        <div className="absolute top-4 right-4 left-4 z-20 flex items-start justify-between gap-2">
+          {headerContent ?? <span />}
+          {onClose && (
+            <Button
+              variant="secondary"
+              size="icon"
+              onClick={onClose}
+              // `common.imagePreview.*` was never added; the canonical close
+              // label lives at `common.aria.close`.
+              title={t('aria.close')}
+              tooltipSide="bottom"
+            >
+              <X className="size-4" />
+            </Button>
+          )}
+        </div>
+      )}
+
+      {toolbarPosition === 'inline' && (
+        <div className="mb-2 flex justify-end">{controls}</div>
+      )}
 
       <div
         ref={containerRef}
@@ -204,9 +185,12 @@ export const ZoomPanViewer = memo(function ZoomPanViewer({
         />
       </div>
 
-      {isBottom && (
-        <div className="sticky bottom-4 z-50 flex w-full justify-center">
-          {toolbar}
+      {/* Floating bottom-center cluster for the dialog (`overlay`) and document
+          preview (`bottom`) layouts. `pointer-events-none` on the wrapper keeps
+          drag-to-pan working everywhere except on the controls themselves. */}
+      {(toolbarPosition === 'overlay' || toolbarPosition === 'bottom') && (
+        <div className="pointer-events-none absolute inset-x-0 bottom-4 z-20 flex justify-center">
+          <div className="pointer-events-auto">{controls}</div>
         </div>
       )}
     </div>
diff --git a/services/platform/app/components/ui/data-table/data-table-action-menu.tsx b/services/platform/app/components/ui/data-table/data-table-action-menu.tsx
index 71db2a5116..de1744bea4 100644
--- a/services/platform/app/components/ui/data-table/data-table-action-menu.tsx
+++ b/services/platform/app/components/ui/data-table/data-table-action-menu.tsx
@@ -34,6 +34,15 @@ export interface DataTableActionMenuProps {
   href?: string;
   /** Button variant */
   variant?: 'primary' | 'destructive' | 'secondary' | 'ghost' | 'link';
+  /**
+   * Button size. Defaults to `default` (h-9) — the create/add action is a
+   * primary action that aligns with the h-9 search/filter controls beside it in
+   * the table toolbar, and matches the empty-state CTA so a list's add button is
+   * the same size in both places. `sm` stays available for genuinely dense bars.
+   */
+  size?: 'default' | 'sm';
+  /** Disable the action. */
+  disabled?: boolean;
   /** Menu items for dropdown (renders dropdown menu instead of simple button) */
   menuItems?: DataTableActionMenuItem[];
   /** Dropdown menu alignment */
@@ -58,6 +67,8 @@ export function DataTableActionMenu({
   onClick,
   href,
   variant,
+  size = 'default',
+  disabled,
   menuItems,
   align = 'end',
   className,
@@ -81,7 +92,12 @@ export function DataTableActionMenu({
     return (
       <DropdownMenu
         trigger={
-          <Button variant={variant} className={cn('gap-2', className)}>
+          <Button
+            variant={variant}
+            size={size}
+            disabled={disabled}
+            className={cn('gap-2', className)}
+          >
             {Icon && <Icon className="size-4" />}
             {label}
             <ChevronDown className="size-4" />
@@ -93,12 +109,13 @@ export function DataTableActionMenu({
     );
   }
 
-  // Render link button if href provided
-  if (href) {
+  // Render link button if href provided (a disabled link falls back to a
+  // disabled button — anchors have no native disabled state).
+  if (href && !disabled) {
     return (
       <Link
         to={href}
-        className={cn(buttonVariants({ variant }), 'gap-2', className)}
+        className={cn(buttonVariants({ variant, size }), 'gap-2', className)}
       >
         {Icon && <Icon className="size-4" />}
         {label}
@@ -111,6 +128,8 @@ export function DataTableActionMenu({
     <Button
       onClick={onClick}
       variant={variant}
+      size={size}
+      disabled={disabled}
       className={cn('gap-2', className)}
     >
       {Icon && <Icon className="size-4" />}
diff --git a/services/platform/app/components/ui/data-table/data-table-empty-state.stories.tsx b/services/platform/app/components/ui/data-table/data-table-empty-state.stories.tsx
index cecbd37d0e..8774b911ac 100644
--- a/services/platform/app/components/ui/data-table/data-table-empty-state.stories.tsx
+++ b/services/platform/app/components/ui/data-table/data-table-empty-state.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { Package, Users, FileText, Plus } from 'lucide-react';
+import { Package, Users, FileText } from 'lucide-react';
 
 import { DataTableEmptyState } from './data-table-empty-state';
 
@@ -114,32 +114,3 @@ export const TitleOnly: Story = {
     },
   },
 };
-
-export const WithAction: Story = {
-  args: {
-    icon: Users,
-    title: 'No agents yet',
-    description: 'Create your first agent to start automating work.',
-    action: {
-      label: 'Create agent',
-      icon: Plus,
-      onClick: () => {},
-    },
-  },
-  decorators: [
-    (Story) => (
-      <div className="h-[300px]">
-        <Story />
-      </div>
-    ),
-  ],
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'An empty list should point at one obvious next step. The optional ' +
-          '`action` renders a single primary CTA below the copy.',
-      },
-    },
-  },
-};
diff --git a/services/platform/app/components/ui/data-table/data-table-empty-state.test.tsx b/services/platform/app/components/ui/data-table/data-table-empty-state.test.tsx
index 495f5d13bf..7bf652b431 100644
--- a/services/platform/app/components/ui/data-table/data-table-empty-state.test.tsx
+++ b/services/platform/app/components/ui/data-table/data-table-empty-state.test.tsx
@@ -1,5 +1,5 @@
-import { Inbox, Plus } from 'lucide-react';
-import { describe, expect, it, vi } from 'vitest';
+import { Inbox } from 'lucide-react';
+import { describe, expect, it } from 'vitest';
 
 import { checkAccessibility } from '@/tests/utils/a11y';
 import { render, screen } from '@/tests/utils/render';
@@ -27,24 +27,15 @@ describe('DataTableEmptyState', () => {
     });
   });
 
-  describe('action CTA', () => {
-    it('renders the action button and fires onClick', async () => {
-      const onClick = vi.fn();
-      const { user } = render(
+  describe('button-less', () => {
+    it('never renders a button — table empty states carry no CTA', () => {
+      render(
         <DataTableEmptyState
           icon={Inbox}
           title="No agents yet"
           description="Create your first agent."
-          action={{ label: 'Create agent', icon: Plus, onClick }}
         />,
       );
-      const button = screen.getByRole('button', { name: 'Create agent' });
-      await user.click(button);
-      expect(onClick).toHaveBeenCalledTimes(1);
-    });
-
-    it('renders no button when no action is provided', () => {
-      render(<DataTableEmptyState title="No items" />);
       expect(screen.queryByRole('button')).not.toBeInTheDocument();
     });
   });
diff --git a/services/platform/app/components/ui/data-table/data-table-empty-state.tsx b/services/platform/app/components/ui/data-table/data-table-empty-state.tsx
index 862f16bac2..5531ad8d32 100644
--- a/services/platform/app/components/ui/data-table/data-table-empty-state.tsx
+++ b/services/platform/app/components/ui/data-table/data-table-empty-state.tsx
@@ -1,17 +1,6 @@
-import { Button } from '@tale/ui/button';
-import { VStack, Center } from '@tale/ui/layout';
-import { Text } from '@tale/ui/text';
-import type { LucideIcon } from 'lucide-react';
+import { EmptyState } from '@tale/ui/empty-state';
 import type { ComponentType, ReactNode } from 'react';
 
-/** A single primary call-to-action shown under the empty-state copy. */
-export interface DataTableEmptyStateAction {
-  label: string;
-  onClick: () => void;
-  // Matches Button's `icon` prop; the empty-state CTA renders a Button.
-  icon?: LucideIcon;
-}
-
 export interface DataTableEmptyStateProps {
   /** Icon to display */
   icon?: ComponentType<{ className?: string }>;
@@ -19,53 +8,22 @@ export interface DataTableEmptyStateProps {
   title: string;
   /** Description text or rich content */
   description?: ReactNode;
-  /**
-   * Optional primary action (e.g. "Create your first agent"). Keep it to a
-   * single obvious next step — an empty list should point at one clear thing.
-   */
-  action?: DataTableEmptyStateAction;
 }
 
 /**
- * Empty state component rendered inside DataTable.
- * Shows when there's no data at all (highest priority — displayed regardless of active filters).
+ * Empty state rendered inside DataTable. A thin adapter over the shared
+ * [`EmptyState`](../../../../../../packages/ui/src/components/feedback/empty-state.tsx)
+ * primitive so every table's empty state looks exactly like the empty states
+ * used everywhere else.
+ *
+ * Deliberately button-less: a table's empty state shows only icon + title +
+ * description. The create/add affordance lives in the table header, not in the
+ * empty body — so the empty state never competes with (or duplicates) it.
  */
 export function DataTableEmptyState({
-  icon: Icon,
+  icon,
   title,
   description,
-  action,
 }: DataTableEmptyStateProps) {
-  return (
-    <Center className="flex-[1_1_0] py-12">
-      <VStack align="center" className="max-w-[24rem] gap-2 text-center">
-        {Icon && (
-          <Icon
-            className="text-muted-foreground/60 mb-3 size-6"
-            aria-hidden="true"
-          />
-        )}
-        <Text variant="label">{title}</Text>
-        {/* `as="div"` (not the default <p>): empty-state descriptions can carry
-            rich content — links, buttons, doc CTAs wrapped in their own block
-            elements — and a <div> inside a <p> is invalid HTML (hydration error). */}
-        {description && (
-          <Text as="div" variant="muted">
-            {description}
-          </Text>
-        )}
-        {action && (
-          <Button
-            variant="primary"
-            size="sm"
-            icon={action.icon}
-            onClick={action.onClick}
-            className="mt-3"
-          >
-            {action.label}
-          </Button>
-        )}
-      </VStack>
-    </Center>
-  );
+  return <EmptyState icon={icon} title={title} description={description} />;
 }
diff --git a/services/platform/app/components/ui/data-table/data-table-pagination.tsx b/services/platform/app/components/ui/data-table/data-table-pagination.tsx
index f914af14b6..73e8aa5b5f 100644
--- a/services/platform/app/components/ui/data-table/data-table-pagination.tsx
+++ b/services/platform/app/components/ui/data-table/data-table-pagination.tsx
@@ -123,7 +123,7 @@ export function DataTablePagination({
         onClick={handlePrevious}
         disabled={isPrevDisabled}
         className="p-1.5"
-        aria-label={t('aria.previousPage')}
+        title={t('aria.previousPage')}
       >
         {isLoading ? (
           <Loader2 className="size-4 animate-spin" />
@@ -151,7 +151,7 @@ export function DataTablePagination({
         onClick={handleNext}
         disabled={isNextDisabled}
         className="p-1.5"
-        aria-label={t('aria.nextPage')}
+        title={t('aria.nextPage')}
       >
         {isLoading ? (
           <Loader2 className="size-4 animate-spin" />
diff --git a/services/platform/app/components/ui/data-table/data-table.test.tsx b/services/platform/app/components/ui/data-table/data-table.test.tsx
index 7596420e5e..bc32298ae2 100644
--- a/services/platform/app/components/ui/data-table/data-table.test.tsx
+++ b/services/platform/app/components/ui/data-table/data-table.test.tsx
@@ -308,3 +308,58 @@ describe('DataTable loading states', () => {
     });
   });
 });
+
+describe('DataTable addAction contract', () => {
+  it('renders the add button in the header at the default (h-9) size', () => {
+    render(
+      <DataTable
+        columns={columns}
+        data={sampleRows}
+        approxRowCount={3}
+        addAction={{ label: 'New customer', onClick: vi.fn() }}
+      />,
+    );
+
+    const btn = screen.getByRole('button', { name: 'New customer' });
+    expect(btn).toBeInTheDocument();
+    // Default (h-9) size: the create action aligns with the h-9 search/filter
+    // controls in the toolbar and matches the empty-state CTA — never `sm`.
+    expect(btn).toHaveClass('h-9');
+    expect(btn).not.toHaveClass('text-xs');
+  });
+
+  it('keeps the empty state button-less — only the header create button renders', () => {
+    render(
+      <DataTable
+        columns={columns}
+        data={[]}
+        approxRowCount={0}
+        emptyState={{ title: 'No customers' }}
+        addAction={{ label: 'New customer', onClick: vi.fn() }}
+      />,
+    );
+
+    // The create affordance lives ONLY in the header; the empty body has no CTA.
+    expect(
+      screen.getAllByRole('button', { name: 'New customer' }),
+    ).toHaveLength(1);
+    expect(screen.getByText('No customers')).toBeInTheDocument();
+  });
+
+  it('prefers an explicit actionMenu over addAction', () => {
+    render(
+      <DataTable
+        columns={columns}
+        data={sampleRows}
+        approxRowCount={3}
+        actionMenu={<button>Bespoke</button>}
+        addAction={{ label: 'New customer', onClick: vi.fn() }}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Bespoke' })).toBeInTheDocument();
+    expect(
+      screen.queryByRole('button', { name: 'New customer' }),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/services/platform/app/components/ui/data-table/data-table.tsx b/services/platform/app/components/ui/data-table/data-table.tsx
index 1dd1d46f96..53333d1518 100644
--- a/services/platform/app/components/ui/data-table/data-table.tsx
+++ b/services/platform/app/components/ui/data-table/data-table.tsx
@@ -28,7 +28,7 @@ import {
   type RowSelectionState,
   type OnChangeFn,
 } from '@tanstack/react-table';
-import { ChevronRight } from 'lucide-react';
+import { ChevronRight, type LucideIcon } from 'lucide-react';
 import {
   Fragment,
   useState,
@@ -53,6 +53,10 @@ import { useOrganizationId } from '@/app/hooks/use-organization-id';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 
+import {
+  DataTableActionMenu,
+  type DataTableActionMenuItem,
+} from './data-table-action-menu';
 import {
   DataTableEmptyState,
   type DataTableEmptyStateProps,
@@ -104,6 +108,29 @@ interface ColumnMeta {
   className?: string;
 }
 
+/**
+ * The single primary "create" affordance for a collection. Rendered in the
+ * header at a fixed size + placement AND synthesized into the empty-state CTA,
+ * so the add-item button is declared once and never drifts between the toolbar
+ * and the empty state. Prefer this over the raw `actionMenu` slot.
+ */
+export interface DataTableAddAction {
+  /** Button label, e.g. "New customer". */
+  label: string;
+  /** Optional leading icon. */
+  icon?: LucideIcon;
+  /** Click handler (e.g. open a create dialog). Required for the empty-state CTA. */
+  onClick?: () => void;
+  /** Navigate instead of handling a click (renders a link). */
+  href?: string;
+  /** Render a dropdown of create options instead of a single button. */
+  menuItems?: DataTableActionMenuItem[];
+  /** Disable the action (e.g. lacking write permission). */
+  disabled?: boolean;
+  /** Button variant (default `primary`). */
+  variant?: 'primary' | 'secondary' | 'ghost';
+}
+
 export interface DataTableProps<TData, TValue = unknown> {
   /** Column definitions */
   columns: ColumnDef<TData, TValue>[];
@@ -197,7 +224,16 @@ export interface DataTableProps<TData, TValue = unknown> {
   isFiltersLoading?: boolean;
   /** Callback to clear all filters */
   onClearFilters?: () => void;
-  /** Header action menu element (use DataTableActionMenu component) */
+  /**
+   * The primary create affordance. DataTable renders it in the header at a
+   * fixed size + placement and reuses it as the empty-state CTA. Preferred over
+   * the raw `actionMenu` slot, which exists only for bespoke header content.
+   */
+  addAction?: DataTableAddAction;
+  /**
+   * Escape hatch for bespoke header content. For the standard "Add X" button,
+   * use `addAction` instead so size/placement stay consistent across lists.
+   */
   actionMenu?: ReactNode;
   /**
    * Extra content rendered inside the filter bar (left side, alongside the
@@ -254,6 +290,7 @@ export function DataTable<TData, TValue = unknown>({
   dateRange,
   isFiltersLoading = false,
   onClearFilters,
+  addAction,
   actionMenu,
   filtersContent,
   footer,
@@ -457,12 +494,33 @@ export function DataTable<TData, TValue = unknown>({
     );
   }
 
+  // The primary "Add X" affordance. The explicit `actionMenu` slot wins (bespoke
+  // header content); otherwise `addAction` renders at the default (h-9) size and
+  // the standard right-aligned placement so every list's add button looks the
+  // same — and lines up with the h-9 search/filter controls in the same toolbar.
+  const primaryAction =
+    actionMenu ??
+    (addAction ? (
+      <DataTableActionMenu
+        label={addAction.label}
+        icon={addAction.icon}
+        onClick={addAction.onClick}
+        href={addAction.href}
+        menuItems={addAction.menuItems}
+        disabled={addAction.disabled}
+        variant={addAction.variant ?? 'primary'}
+      />
+    ) : null);
+
+  // Empty states are intentionally button-less (icon + title + description only):
+  // the create affordance lives in the table header, not the empty body.
+
   // Determine if we should render header
   const hasHeader =
     search ||
     (filters && filters.length > 0) ||
     dateRange ||
-    actionMenu ||
+    primaryAction ||
     filtersContent;
 
   // Build the header content
@@ -480,7 +538,7 @@ export function DataTable<TData, TValue = unknown>({
       >
         {filtersContent}
       </DataTableFilters>
-      {actionMenu}
+      {primaryAction}
     </div>
   ) : null;
 
@@ -847,7 +905,6 @@ export function DataTable<TData, TValue = unknown>({
                     icon={emptyState?.icon}
                     title={emptyState?.title ?? ''}
                     description={emptyState?.description}
-                    action={emptyState?.action}
                   />
                 </div>
               </TableCell>
diff --git a/services/platform/app/components/ui/dialog/confirm-dialog.tsx b/services/platform/app/components/ui/dialog/confirm-dialog.tsx
index 31551b8149..e97bb380bb 100644
--- a/services/platform/app/components/ui/dialog/confirm-dialog.tsx
+++ b/services/platform/app/components/ui/dialog/confirm-dialog.tsx
@@ -154,7 +154,6 @@ export function ConfirmDialog({
             onChange={(e) => setPhraseInput(e.target.value)}
             autoComplete="off"
             spellCheck={false}
-            size="sm"
           />
         </div>
       )}
diff --git a/services/platform/app/components/ui/editor/editor-actions.test.tsx b/services/platform/app/components/ui/editor/editor-actions.test.tsx
new file mode 100644
index 0000000000..e24378a039
--- /dev/null
+++ b/services/platform/app/components/ui/editor/editor-actions.test.tsx
@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { EditorActions } from './editor-actions';
+import type { EditorController } from './types';
+
+const toastMock = vi.fn();
+
+vi.mock('@/app/hooks/use-toast', () => ({
+  toast: (...args: unknown[]) => toastMock(...args),
+}));
+
+vi.mock('@/lib/i18n/client', () => ({
+  useT: () => ({ t: (key: string) => key }),
+}));
+
+function makeController(
+  overrides: Partial<EditorController> = {},
+): EditorController {
+  return {
+    isDirty: true,
+    isSaving: false,
+    isValid: true,
+    isLoading: false,
+    dirtyKeys: new Set<string>(['field']),
+    save: vi.fn().mockResolvedValue(undefined),
+    reset: vi.fn(),
+    ...overrides,
+  };
+}
+
+function clickSave() {
+  fireEvent.click(screen.getByRole('button', { name: 'actions.save' }));
+}
+
+beforeEach(() => {
+  toastMock.mockReset();
+});
+
+describe('EditorActions — suppressServerErrorToast', () => {
+  it('toasts a server error by default', async () => {
+    const controller = makeController({
+      save: vi.fn().mockRejectedValue(new Error('Server boom')),
+    });
+    render(<EditorActions controller={controller} />);
+    clickSave();
+    await waitFor(() => expect(toastMock).toHaveBeenCalledTimes(1));
+    expect(toastMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        description: 'Server boom',
+        variant: 'destructive',
+      }),
+    );
+  });
+
+  it('suppresses the generic server-error toast when set (caller toasts its own)', async () => {
+    const controller = makeController({
+      save: vi.fn().mockRejectedValue(new Error('Server boom')),
+    });
+    render(<EditorActions controller={controller} suppressServerErrorToast />);
+    clickSave();
+    await waitFor(() => expect(controller.save).toHaveBeenCalled());
+    expect(toastMock).not.toHaveBeenCalled();
+  });
+
+  it('still toasts validation failures even when suppressed', async () => {
+    const controller = makeController({
+      save: vi.fn().mockRejectedValue(new Error('VALIDATION_FAILED')),
+    });
+    render(<EditorActions controller={controller} suppressServerErrorToast />);
+    clickSave();
+    await waitFor(() => expect(toastMock).toHaveBeenCalledTimes(1));
+    expect(toastMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        description: 'editor.fixHighlightedFields',
+        variant: 'destructive',
+      }),
+    );
+  });
+});
diff --git a/services/platform/app/components/ui/editor/editor-actions.tsx b/services/platform/app/components/ui/editor/editor-actions.tsx
index 69edd99428..cc4cb62a55 100644
--- a/services/platform/app/components/ui/editor/editor-actions.tsx
+++ b/services/platform/app/components/ui/editor/editor-actions.tsx
@@ -36,6 +36,14 @@ interface EditorActionsProps {
   onEvent?: (event: EditorTelemetryEvent) => void;
   /** Tag for telemetry (e.g. `'agent'`, `'org_settings'`). */
   entityKind?: string;
+  /**
+   * Opt out of the generic server-error toast when the controller's own
+   * `save()` already surfaces a (typically localized) failure message itself —
+   * otherwise the user sees two destructive toasts for one failure. Validation
+   * failures are still toasted here, since callers don't handle those. Default
+   * `false` (EditorActions owns all error toasting).
+   */
+  suppressServerErrorToast?: boolean;
   className?: string;
 }
 
@@ -48,6 +56,7 @@ export function EditorActions({
   formId,
   onEvent,
   entityKind = 'unknown',
+  suppressServerErrorToast = false,
   className,
 }: EditorActionsProps) {
   const { t } = useT('common');
@@ -89,7 +98,7 @@ export function EditorActions({
           description: t('editor.fixHighlightedFields'),
           variant: 'destructive',
         });
-      } else {
+      } else if (!suppressServerErrorToast) {
         toast({
           title: t('actions.save'),
           description: err instanceof Error ? err.message : String(err),
@@ -97,7 +106,7 @@ export function EditorActions({
         });
       }
     }
-  }, [controller, entityKind, onEvent, t]);
+  }, [controller, entityKind, onEvent, suppressServerErrorToast, t]);
 
   const handleDiscard = useCallback(() => {
     if (!controller.isDirty || controller.isSaving) return;
@@ -152,9 +161,9 @@ export function EditorActions({
       {history}
       <Button
         type="button"
+        size="sm"
         onClick={handleDiscard}
         variant="secondary"
-        size="sm"
         icon={Undo2}
         iconClassName="size-3.5"
         collapseLabel
@@ -165,10 +174,10 @@ export function EditorActions({
       </Button>
       <Button
         type={formId ? 'submit' : 'button'}
+        size="sm"
         form={formId}
         onClick={formId ? undefined : () => void runSave()}
         disabled={saveDisabled}
-        size="sm"
         aria-busy={controller.isSaving ? 'true' : undefined}
       >
         {controller.isSaving ? (
diff --git a/services/platform/app/components/ui/feedback/banner.stories.tsx b/services/platform/app/components/ui/feedback/banner.stories.tsx
deleted file mode 100644
index 989e08bbf9..0000000000
--- a/services/platform/app/components/ui/feedback/banner.stories.tsx
+++ /dev/null
@@ -1,181 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import {
-  Info as InfoIcon,
-  AlertTriangle,
-  CheckCircle,
-  XCircle,
-} from 'lucide-react';
-import { useState } from 'react';
-
-import { Banner } from './banner';
-
-const meta: Meta<typeof Banner> = {
-  title: 'Feedback/Banner',
-  component: Banner,
-  tags: ['autodocs'],
-  parameters: {
-    layout: 'padded',
-    docs: {
-      description: {
-        component: `
-A banner component for displaying important messages with various severity levels.
-
-## Usage
-\`\`\`tsx
-import { Banner } from '@/app/components/ui/feedback/banner';
-import { Info } from 'lucide-react';
-
-<Banner
-  variant="info"
-  message="This is an informational message."
-  icon={InfoIcon}
-  dismissible
-  onClose={() => {}}
-/>
-\`\`\`
-
-## Accessibility
-- Uses role="alert" for announcements
-- Dismiss button has proper aria-label
-- Icons are decorative (aria-hidden)
-        `,
-      },
-    },
-  },
-  argTypes: {
-    variant: {
-      control: 'select',
-      options: ['info', 'warning', 'success', 'error'],
-    },
-    dismissible: {
-      control: 'boolean',
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Banner>;
-
-export const Info: Story = {
-  args: {
-    variant: 'info',
-    message: 'A new version of the application is available.',
-    icon: InfoIcon,
-    dismissible: true,
-  },
-};
-
-export const Warning: Story = {
-  args: {
-    variant: 'warning',
-    message: 'Your subscription will expire in 3 days.',
-    icon: AlertTriangle,
-    dismissible: true,
-  },
-};
-
-export const Success: Story = {
-  args: {
-    variant: 'success',
-    message: 'Your changes have been saved successfully.',
-    icon: CheckCircle,
-    dismissible: true,
-  },
-};
-
-export const Error: Story = {
-  args: {
-    variant: 'error',
-    message: 'Failed to connect to the server. Please try again.',
-    icon: XCircle,
-    dismissible: true,
-  },
-};
-
-export const AllVariants: Story = {
-  render: () => (
-    <div className="space-y-4">
-      <Banner
-        variant="info"
-        message="This is an informational banner."
-        icon={InfoIcon}
-      />
-      <Banner
-        variant="warning"
-        message="This is a warning banner."
-        icon={AlertTriangle}
-      />
-      <Banner
-        variant="success"
-        message="This is a success banner."
-        icon={CheckCircle}
-      />
-      <Banner
-        variant="error"
-        message="This is an error banner."
-        icon={XCircle}
-      />
-    </div>
-  ),
-};
-
-export const WithoutIcon: Story = {
-  args: {
-    variant: 'info',
-    message: 'This banner has no icon.',
-    dismissible: true,
-  },
-};
-
-export const NonDismissible: Story = {
-  args: {
-    variant: 'warning',
-    message: 'This banner cannot be dismissed.',
-    icon: AlertTriangle,
-    dismissible: false,
-  },
-};
-
-export const Dismissible: Story = {
-  render: function Render() {
-    const [hidden, setHidden] = useState(false);
-
-    return (
-      <div className="space-y-4">
-        <Banner
-          variant="info"
-          message="Click the X button to dismiss this banner."
-          icon={InfoIcon}
-          dismissible
-          isHidden={hidden}
-          onClose={() => setHidden(true)}
-        />
-        {hidden && (
-          <button
-            onClick={() => setHidden(false)}
-            className="text-primary text-sm hover:underline"
-          >
-            Show banner again
-          </button>
-        )}
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Banners can be dismissed by clicking the close button.',
-      },
-    },
-  },
-};
-
-export const LongMessage: Story = {
-  args: {
-    variant: 'warning',
-    message:
-      'This is a longer message that demonstrates how the banner handles multiple lines of text. The banner will expand to accommodate the content while maintaining proper alignment of the icon and dismiss button.',
-    icon: AlertTriangle,
-    dismissible: true,
-  },
-};
diff --git a/services/platform/app/components/ui/feedback/banner.test.tsx b/services/platform/app/components/ui/feedback/banner.test.tsx
deleted file mode 100644
index 29e592dfce..0000000000
--- a/services/platform/app/components/ui/feedback/banner.test.tsx
+++ /dev/null
@@ -1,41 +0,0 @@
-import { describe, it, expect } from 'vitest';
-
-import { checkAccessibility } from '@/tests/utils/a11y';
-import { render, screen } from '@/tests/utils/render';
-
-import { Banner } from './banner';
-
-describe('Banner', () => {
-  describe('accessibility', () => {
-    it('passes axe audit', async () => {
-      const { container } = render(<Banner message="Information message" />);
-      await checkAccessibility(container);
-    });
-
-    it('passes axe audit for each variant', async () => {
-      for (const variant of ['info', 'warning', 'success', 'error'] as const) {
-        const { container } = render(
-          <Banner variant={variant} message={`${variant} message`} />,
-        );
-        await checkAccessibility(container);
-      }
-    });
-
-    it('has alert role', () => {
-      render(<Banner message="Alert message" />);
-      expect(screen.getByRole('alert')).toBeInTheDocument();
-    });
-
-    it('dismiss button has aria-label', () => {
-      render(<Banner message="Dismissible" dismissible />);
-      expect(screen.getByRole('button')).toHaveAttribute('aria-label');
-    });
-
-    it('passes axe audit when not dismissible', async () => {
-      const { container } = render(
-        <Banner message="Non-dismissible" dismissible={false} />,
-      );
-      await checkAccessibility(container);
-    });
-  });
-});
diff --git a/services/platform/app/components/ui/feedback/banner.tsx b/services/platform/app/components/ui/feedback/banner.tsx
deleted file mode 100644
index 2aed9335de..0000000000
--- a/services/platform/app/components/ui/feedback/banner.tsx
+++ /dev/null
@@ -1,122 +0,0 @@
-'use client';
-
-import { Button } from '@tale/ui/button';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { X } from 'lucide-react';
-import type { ComponentPropsWithoutRef, FC } from 'react';
-
-import { useT } from '@/lib/i18n/client';
-import { cn } from '@/lib/utils/cn';
-
-const bannerVariants = cva(
-  'flex items-center gap-2 rounded-lg border p-3 transition-all',
-  {
-    variants: {
-      variant: {
-        info: 'bg-info border-info-foreground/30',
-        warning: 'bg-warning/10 border-warning/30',
-        success: 'bg-success/10 border-success/30',
-        error: 'bg-destructive/10 border-destructive/30',
-      },
-    },
-    defaultVariants: {
-      variant: 'info',
-    },
-  },
-);
-
-const bannerTextVariants = cva('grow text-sm leading-normal', {
-  variants: {
-    variant: {
-      info: 'text-info-foreground',
-      warning: 'text-warning',
-      success: 'text-success',
-      error: 'text-destructive',
-    },
-  },
-  defaultVariants: {
-    variant: 'info',
-  },
-});
-
-const bannerIconVariants = cva('shrink-0 size-5', {
-  variants: {
-    variant: {
-      info: 'text-info-foreground',
-      warning: 'text-warning',
-      success: 'text-success',
-      error: 'text-destructive',
-    },
-  },
-  defaultVariants: {
-    variant: 'info',
-  },
-});
-
-const bannerCloseVariants = cva(
-  'shrink-0 size-6 cursor-pointer transition-opacity hover:opacity-70',
-  {
-    variants: {
-      variant: {
-        info: 'text-info-foreground',
-        warning: 'text-warning',
-        success: 'text-success',
-        error: 'text-destructive',
-      },
-    },
-    defaultVariants: {
-      variant: 'info',
-    },
-  },
-);
-
-export interface BannerProps
-  extends
-    Omit<ComponentPropsWithoutRef<'div'>, 'children'>,
-    VariantProps<typeof bannerVariants> {
-  readonly variant?: 'info' | 'warning' | 'success' | 'error';
-  readonly message: string;
-  readonly icon?: FC<{ className?: string }>;
-  readonly dismissible?: boolean;
-  readonly onClose?: () => void;
-  readonly isHidden?: boolean;
-}
-
-export function Banner({
-  variant = 'info',
-  message,
-  icon: Icon,
-  dismissible = true,
-  onClose,
-  isHidden = false,
-  className,
-  ...restProps
-}: BannerProps) {
-  const { t } = useT('common');
-
-  if (isHidden) {
-    return null;
-  }
-
-  return (
-    <div
-      className={cn(bannerVariants({ variant }), className)}
-      role="alert"
-      {...restProps}
-    >
-      {Icon && <Icon className={bannerIconVariants({ variant })} />}
-      <p className={bannerTextVariants({ variant })}>{message}</p>
-      {dismissible && (
-        <Button
-          variant="ghost"
-          size="icon"
-          onClick={onClose}
-          className={bannerCloseVariants({ variant })}
-          aria-label={t('aria.dismiss')}
-        >
-          <X className="size-full" />
-        </Button>
-      )}
-    </div>
-  );
-}
diff --git a/services/platform/app/components/ui/filters/filter-button.tsx b/services/platform/app/components/ui/filters/filter-button.tsx
index 8d1d3d7a32..4e7eb7c985 100644
--- a/services/platform/app/components/ui/filters/filter-button.tsx
+++ b/services/platform/app/components/ui/filters/filter-button.tsx
@@ -6,10 +6,13 @@ import { ComponentProps } from 'react';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 
-interface FilterButtonProps extends ComponentProps<typeof Button> {
+// Intersection (not `interface extends`) because Button's props are a
+// discriminated union (icon size requires aria-label) — an interface can't
+// extend a union, but an intersection distributes over it cleanly.
+type FilterButtonProps = ComponentProps<typeof Button> & {
   hasActiveFilters: boolean;
   isLoading?: boolean;
-}
+};
 
 export function FilterButton({
   hasActiveFilters,
diff --git a/services/platform/app/components/ui/forms/date-picker.tsx b/services/platform/app/components/ui/forms/date-picker.tsx
index 8aba2da06c..2b18c6b57c 100644
--- a/services/platform/app/components/ui/forms/date-picker.tsx
+++ b/services/platform/app/components/ui/forms/date-picker.tsx
@@ -83,7 +83,6 @@ const DateTrigger = forwardRef<HTMLButtonElement, TriggerProps>(
         ref={ref}
         type="button"
         variant="ghost"
-        size="sm"
         disabled={disabled}
         onClick={onClick}
         className={cn(
diff --git a/services/platform/app/components/ui/forms/date-range-picker.tsx b/services/platform/app/components/ui/forms/date-range-picker.tsx
index 03fd6eaa93..c16edd8bd1 100644
--- a/services/platform/app/components/ui/forms/date-range-picker.tsx
+++ b/services/platform/app/components/ui/forms/date-range-picker.tsx
@@ -409,7 +409,6 @@ function DatePickerWithRangeBase({
             <Button
               type="button"
               variant="ghost"
-              size="sm"
               onClick={handleClear}
               disabled={disabled || isLoading}
               className="relative top-1 ml-auto block h-min px-2 py-1 text-xs"
diff --git a/services/platform/app/components/ui/forms/input.stories.tsx b/services/platform/app/components/ui/forms/input.stories.tsx
index 326ce4b291..c9bba0b424 100644
--- a/services/platform/app/components/ui/forms/input.stories.tsx
+++ b/services/platform/app/components/ui/forms/input.stories.tsx
@@ -32,10 +32,11 @@ import { Input } from './input';
     },
   },
   argTypes: {
-    size: {
+    variant: {
       control: 'select',
-      options: ['default', 'sm', 'lg'],
-      description: 'Input size variant',
+      options: ['default', 'unstyled'],
+      description:
+        'Visual variant: `default` (bordered field) or `unstyled` (no chrome, inherits surrounding styles)',
     },
     type: {
       control: 'select',
@@ -187,14 +188,25 @@ export const PasswordWithError: Story = {
   },
 };
 
-export const AllSizes: Story = {
+export const Variants: Story = {
   render: () => (
     <div className="flex flex-col gap-4">
-      <Input size="sm" label="Small" placeholder="Small input" />
-      <Input size="default" label="Default" placeholder="Default input" />
-      <Input size="lg" label="Large" placeholder="Large input" />
+      <Input variant="default" label="Default" placeholder="Bordered field" />
+      <Input
+        variant="unstyled"
+        label="Unstyled"
+        placeholder="No chrome — inherits surrounding styles"
+      />
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The input renders at a single height (h-9). The only style axis is `variant`: `default` is the standard bordered field; `unstyled` drops the field chrome so the input blends into a custom container.',
+      },
+    },
+  },
 };
 
 export const Disabled: Story = {
diff --git a/services/platform/app/components/ui/forms/input.test.tsx b/services/platform/app/components/ui/forms/input.test.tsx
index 62de2621ee..229ef9af5b 100644
--- a/services/platform/app/components/ui/forms/input.test.tsx
+++ b/services/platform/app/components/ui/forms/input.test.tsx
@@ -32,11 +32,14 @@ describe('Input', () => {
     });
   });
 
-  describe('sizes', () => {
-    it.each(['default', 'sm', 'lg'] as const)('renders %s size', (size) => {
-      render(<Input size={size} placeholder="Test" />);
-      expect(screen.getByPlaceholderText('Test')).toBeInTheDocument();
-    });
+  describe('variants', () => {
+    it.each(['default', 'unstyled'] as const)(
+      'renders %s variant',
+      (variant) => {
+        render(<Input variant={variant} placeholder="Test" />);
+        expect(screen.getByPlaceholderText('Test')).toBeInTheDocument();
+      },
+    );
   });
 
   describe('password input', () => {
diff --git a/services/platform/app/components/ui/forms/input.tsx b/services/platform/app/components/ui/forms/input.tsx
index 01c7a0fd98..7f3115acf5 100644
--- a/services/platform/app/components/ui/forms/input.tsx
+++ b/services/platform/app/components/ui/forms/input.tsx
@@ -21,7 +21,8 @@ import { cn } from '@/lib/utils/cn';
 import { Label } from './label';
 
 const inputVariants = cva(
-  'flex w-full text-base file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 transition-[border-color,box-shadow] duration-150',
+  // One height fits all controls (`h-9`) — no size axis.
+  'flex h-9 w-full text-base file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 transition-[border-color,box-shadow] duration-150',
   {
     variants: {
       variant: {
@@ -29,15 +30,9 @@ const inputVariants = cva(
           'rounded-lg border border-transparent bg-input px-3 py-2 ring-offset-background focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 ring-1 ring-[color:var(--color-border-input)] focus-visible:ring-primary',
         unstyled: 'bg-transparent border-0 ring-0 ring-offset-0',
       },
-      size: {
-        default: 'h-10',
-        sm: 'h-8',
-        lg: 'h-12',
-      },
     },
     defaultVariants: {
       variant: 'default',
-      size: 'default',
     },
   },
 );
@@ -73,7 +68,6 @@ const InputBase = forwardRef<HTMLInputElement, BaseProps>(
       sensitive,
       autoComplete,
       variant,
-      size,
       errorMessage,
       isInvalid,
       label,
@@ -190,7 +184,7 @@ const InputBase = forwardRef<HTMLInputElement, BaseProps>(
               type={inputType}
               {...sensitiveAttrs}
               className={cn(
-                inputVariants({ variant, size }),
+                inputVariants({ variant }),
                 showInvalid &&
                   'border-destructive focus-visible:ring-destructive',
                 showShake && 'animate-shake',
@@ -260,7 +254,7 @@ const InputBase = forwardRef<HTMLInputElement, BaseProps>(
           type={inputType}
           {...sensitiveAttrs}
           className={cn(
-            inputVariants({ variant, size }),
+            inputVariants({ variant }),
             showInvalid && 'border-destructive focus-visible:ring-destructive',
             showShake && 'animate-shake',
             className,
diff --git a/services/platform/app/components/ui/forms/model-selector.tsx b/services/platform/app/components/ui/forms/model-selector.tsx
index 526075d26f..563753eb6a 100644
--- a/services/platform/app/components/ui/forms/model-selector.tsx
+++ b/services/platform/app/components/ui/forms/model-selector.tsx
@@ -146,7 +146,7 @@ function ModelSelectorBase({
         emptyText={t('agents.form.noModelsFound')}
         aria-label={t('agents.form.addModel')}
         trigger={
-          <Button type="button" variant="link" size="sm" icon={Plus}>
+          <Button type="button" variant="link" icon={Plus}>
             {t('agents.form.addModel')}
           </Button>
         }
diff --git a/services/platform/app/components/ui/forms/searchable-select.tsx b/services/platform/app/components/ui/forms/searchable-select.tsx
index 1562131570..8caffefcd4 100644
--- a/services/platform/app/components/ui/forms/searchable-select.tsx
+++ b/services/platform/app/components/ui/forms/searchable-select.tsx
@@ -22,7 +22,7 @@ import {
 import { cn } from '@/lib/utils/cn';
 
 import { Label } from './label';
-import { selectTriggerClasses, type SelectTriggerSize } from './select';
+import { selectTriggerClasses } from './select';
 
 export interface SearchableSelectOption {
   value: string;
@@ -52,8 +52,6 @@ export interface SearchableSelectProps {
   label?: ReactNode;
   /** Placeholder shown on the default trigger when no value is selected. */
   placeholder?: ReactNode;
-  /** Size of the default trigger — matches the `Select` component's sizes. */
-  size?: SelectTriggerSize;
   /** Marks the default trigger as invalid (adds error ring + aria-invalid). */
   error?: boolean;
   /** Description text rendered below the default trigger. */
@@ -160,7 +158,6 @@ function SearchableSelectBase({
   trigger,
   label,
   placeholder,
-  size = 'default',
   error,
   description,
   required,
@@ -202,7 +199,7 @@ function SearchableSelectBase({
       id={triggerId}
       disabled={disabled}
       aria-describedby={description ? descriptionId : undefined}
-      className={cn(selectTriggerClasses({ size, error }), triggerClassName)}
+      className={cn(selectTriggerClasses({ error }), triggerClassName)}
     >
       <span className={cn(!selectedOption && 'text-muted-foreground')}>
         {selectedOption ? selectedOption.label : placeholder}
diff --git a/services/platform/app/components/ui/forms/select.tsx b/services/platform/app/components/ui/forms/select.tsx
index e36e183293..2667019e18 100644
--- a/services/platform/app/components/ui/forms/select.tsx
+++ b/services/platform/app/components/ui/forms/select.tsx
@@ -48,21 +48,15 @@ const selectViewportVariants = cva('p-1', {
   },
 });
 
-export type SelectTriggerSize = 'default' | 'sm' | 'lg';
-
 export function selectTriggerClasses({
-  size = 'default',
   error,
 }: {
-  size?: SelectTriggerSize;
   error?: boolean;
 } = {}) {
   return cn(
-    'flex w-full items-center justify-between whitespace-nowrap rounded-lg border border-transparent bg-input px-3 py-2 text-base md:text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1 ring-1 ring-border focus-visible:ring-primary transition-[border-color,box-shadow] duration-150',
+    // One height fits all controls (`h-9`) — no size axis.
+    'flex h-9 w-full items-center justify-between whitespace-nowrap rounded-lg border border-transparent bg-input px-3 py-2 text-base md:text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1 ring-1 ring-border focus-visible:ring-primary transition-[border-color,box-shadow] duration-150',
     error && 'border-destructive focus-visible:ring-destructive',
-    size === 'default' && 'h-10',
-    size === 'sm' && 'h-8',
-    size === 'lg' && 'h-12',
   );
 }
 
@@ -99,8 +93,6 @@ interface SelectProps extends Omit<
   position?: 'popper' | 'item-aligned';
   /** Side offset for popper position */
   sideOffset?: number;
-  /** Size of the select */
-  size?: 'default' | 'sm' | 'lg';
   /** Accessible name forwarded to the combobox trigger button. */
   'aria-label'?: string;
   /** Id of an element labelling the combobox trigger button. */
@@ -120,7 +112,6 @@ const SelectBase = forwardRef<
       placeholder,
       required,
       error,
-      size = 'default',
       description,
       className,
       wrapperClassName,
@@ -160,7 +151,7 @@ const SelectBase = forwardRef<
         <SelectPrimitive.Trigger
           ref={ref}
           id={id}
-          className={cn(selectTriggerClasses({ size, error }), className)}
+          className={cn(selectTriggerClasses({ error }), className)}
           aria-invalid={error}
           aria-label={ariaLabel}
           aria-labelledby={resolvedLabelledBy}
diff --git a/services/platform/app/components/ui/navigation/navigation.tsx b/services/platform/app/components/ui/navigation/navigation.tsx
index 51169357f9..083c23fdef 100644
--- a/services/platform/app/components/ui/navigation/navigation.tsx
+++ b/services/platform/app/components/ui/navigation/navigation.tsx
@@ -1,6 +1,7 @@
 'use client';
 
-import { Link, useLocation } from '@tanstack/react-router';
+import { Link, useLocation, useNavigate } from '@tanstack/react-router';
+import { useEffect } from 'react';
 
 import { useBrandingContext } from '@/app/components/branding/branding-provider';
 import { TaleLogo } from '@/app/components/ui/logo/tale-logo';
@@ -8,6 +9,7 @@ import { Tooltip } from '@/app/components/ui/overlays/tooltip';
 import { UserButton } from '@/app/components/user-button';
 import { NotificationBell } from '@/app/features/notifications/components/notification-bell';
 import { useAbility } from '@/app/hooks/use-ability';
+import { useIsMac } from '@/app/hooks/use-is-mac';
 import {
   useNavigationItems,
   type NavItem,
@@ -52,10 +54,23 @@ function NavigationItem({ item }: { item: NavItem }) {
   const iconActiveStyle =
     isActive && accentColor ? { color: accentColor } : undefined;
 
+  // Rail links are icon-only; the tooltip carries the label and, for items that
+  // own a global keyboard shortcut, a hint chip so the binding is discoverable.
+  const tooltipContent = item.shortcut ? (
+    <>
+      {item.label}
+      <span className="text-muted bg-muted-foreground/60 ml-3 rounded-sm px-1 py-0.5 text-xs">
+        {item.shortcut}
+      </span>
+    </>
+  ) : (
+    item.label
+  );
+
   if (item.external) {
     return (
       <NavigationMenuItem className={cn('relative')}>
-        <Tooltip content={item.label} side="right">
+        <Tooltip content={tooltipContent} side="right">
           <a
             href={item.href}
             target="_blank"
@@ -96,7 +111,7 @@ function NavigationItem({ item }: { item: NavItem }) {
 
   return (
     <NavigationMenuItem className={cn('relative')}>
-      <Tooltip content={item.label} side="right">
+      <Tooltip content={tooltipContent} side="right">
         <Link
           to={item.to}
           params={item.params}
@@ -142,6 +157,30 @@ export interface NavigationProps {
 export function Navigation({ organizationId }: NavigationProps) {
   const { t: tCommon } = useT('common');
   const { primary, pinned } = useNavigationItems(organizationId);
+  const navigate = useNavigate();
+  const isMac = useIsMac();
+
+  // New-chat shortcut, registered on the always-mounted rail so it works from
+  // anywhere in the dashboard (it used to live in the chat header and only
+  // fired while a chat was open). ⌥⌘N on Mac, Alt+Ctrl+N elsewhere — Option+N
+  // is a dead key on macOS, so match on `code` ("KeyN"), not `key`. Navigating
+  // to the base chat route resets to a fresh chat: when leaving an open thread
+  // the chat layout's own thread→new effect clears the prior state.
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      const isMod = isMac ? e.metaKey : e.ctrlKey;
+      if (isMod && e.altKey && e.code === 'KeyN') {
+        e.preventDefault();
+        e.stopPropagation();
+        void navigate({
+          to: '/dashboard/$id/chat',
+          params: { id: organizationId },
+        });
+      }
+    };
+    window.addEventListener('keydown', onKeyDown, true);
+    return () => window.removeEventListener('keydown', onKeyDown, true);
+  }, [isMac, navigate, organizationId]);
 
   return (
     <NavigationMenu
diff --git a/services/platform/app/components/ui/navigation/pagination.stories.tsx b/services/platform/app/components/ui/navigation/pagination.stories.tsx
deleted file mode 100644
index d11542b634..0000000000
--- a/services/platform/app/components/ui/navigation/pagination.stories.tsx
+++ /dev/null
@@ -1,185 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { useSearch } from '@tanstack/react-router';
-
-import { Pagination } from './pagination';
-
-function PaginationWrapper({
-  initialPage = 1,
-  total = 100,
-  pageSize = 10,
-  totalPages,
-  hasNextPage,
-}: {
-  initialPage?: number;
-  total?: number;
-  pageSize?: number;
-  totalPages?: number;
-  hasNextPage?: boolean;
-}) {
-  const search: Record<string, string | undefined> = useSearch({
-    strict: false,
-  });
-  const parsed = search.page ? parseInt(search.page, 10) : NaN;
-  const currentPage = Number.isNaN(parsed) ? initialPage : parsed;
-
-  return (
-    <Pagination
-      currentPage={currentPage}
-      total={total}
-      pageSize={pageSize}
-      totalPages={totalPages}
-      hasNextPage={hasNextPage}
-    />
-  );
-}
-
-const meta: Meta<typeof Pagination> = {
-  title: 'Navigation/Pagination',
-  component: Pagination,
-  tags: ['autodocs'],
-  parameters: {
-    layout: 'centered',
-    docs: {
-      description: {
-        component: `
-A pagination component with page navigation and page size selection.
-
-## Usage
-\`\`\`tsx
-import { Pagination } from '@/app/components/ui/navigation/pagination';
-
-<Pagination
-  currentPage={1}
-  total={100}
-  pageSize={10}
-/>
-\`\`\`
-
-## Features
-- Previous/Next buttons with loading states
-- Page selector dropdown
-- Shows current range and total count
-- URL-based navigation (updates search params)
-- Optional query string preservation
-        `,
-      },
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Pagination>;
-
-export const Default: Story = {
-  render: () => <PaginationWrapper total={100} pageSize={10} />,
-};
-
-export const MiddlePage: Story = {
-  render: () => <PaginationWrapper initialPage={5} total={100} pageSize={10} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Pagination starting on a middle page.',
-      },
-    },
-  },
-};
-
-export const LastPage: Story = {
-  render: () => (
-    <PaginationWrapper initialPage={10} total={100} pageSize={10} />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Next button disabled on last page.',
-      },
-    },
-  },
-};
-
-export const SmallDataset: Story = {
-  render: () => <PaginationWrapper total={25} pageSize={10} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Small dataset with only 3 pages.',
-      },
-    },
-  },
-};
-
-export const LargeDataset: Story = {
-  render: () => <PaginationWrapper total={1000} pageSize={10} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Large dataset with many pages.',
-      },
-    },
-  },
-};
-
-export const SinglePage: Story = {
-  render: () => <PaginationWrapper total={5} pageSize={10} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Single page - both buttons disabled.',
-      },
-    },
-  },
-};
-
-export const EmptyState: Story = {
-  render: () => <PaginationWrapper total={0} pageSize={10} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Empty state with no items - all controls disabled.',
-      },
-    },
-  },
-};
-
-export const WithTotalPages: Story = {
-  render: () => (
-    <PaginationWrapper
-      initialPage={3}
-      total={50}
-      pageSize={10}
-      totalPages={5}
-    />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Explicit totalPages prop for server-side pagination.',
-      },
-    },
-  },
-};
-
-export const WithHasNextPage: Story = {
-  render: () => (
-    <PaginationWrapper total={50} pageSize={10} hasNextPage={true} />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Using hasNextPage for cursor-based pagination.',
-      },
-    },
-  },
-};
-
-export const CustomPageSize: Story = {
-  render: () => <PaginationWrapper total={100} pageSize={25} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Custom page size of 25 items.',
-      },
-    },
-  },
-};
diff --git a/services/platform/app/components/ui/navigation/pagination.test.tsx b/services/platform/app/components/ui/navigation/pagination.test.tsx
deleted file mode 100644
index 7a6bf5329c..0000000000
--- a/services/platform/app/components/ui/navigation/pagination.test.tsx
+++ /dev/null
@@ -1,67 +0,0 @@
-import React from 'react';
-import { describe, it, vi } from 'vitest';
-
-import { checkAccessibility } from '@/tests/utils/a11y';
-import { render } from '@/tests/utils/render';
-
-import { Pagination } from './pagination';
-
-const stableSearch = {};
-
-vi.mock('@tanstack/react-router', () => ({
-  Link: React.forwardRef(
-    (
-      props: { to: string; children: React.ReactNode },
-      ref: React.Ref<HTMLAnchorElement>,
-    ) => (
-      <a ref={ref} href={props.to}>
-        {props.children}
-      </a>
-    ),
-  ),
-  useNavigate: () => vi.fn(),
-  useLocation: () => ({ pathname: '/dashboard/test-org/documents' }),
-  useSearch: () => stableSearch,
-}));
-
-vi.mock('@/app/components/ui/forms/select', () => ({
-  Select: (props: {
-    value: string;
-    onValueChange?: (v: string) => void;
-    options?: { value: string; label: string }[];
-    disabled?: boolean;
-  }) => (
-    <select
-      value={props.value}
-      onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
-        props.onValueChange?.(e.target.value)
-      }
-      disabled={props.disabled}
-      aria-label="Page"
-    >
-      {props.options?.map((opt) => (
-        <option key={opt.value} value={opt.value}>
-          {opt.label}
-        </option>
-      ))}
-    </select>
-  ),
-}));
-
-describe('Pagination', () => {
-  describe('accessibility', () => {
-    it('passes axe audit', async () => {
-      const { container } = render(
-        <Pagination currentPage={1} total={50} pageSize={10} />,
-      );
-      await checkAccessibility(container);
-    });
-
-    it('passes axe audit when empty', async () => {
-      const { container } = render(
-        <Pagination currentPage={1} total={0} pageSize={10} />,
-      );
-      await checkAccessibility(container);
-    });
-  });
-});
diff --git a/services/platform/app/components/ui/navigation/pagination.tsx b/services/platform/app/components/ui/navigation/pagination.tsx
deleted file mode 100644
index a8796165cc..0000000000
--- a/services/platform/app/components/ui/navigation/pagination.tsx
+++ /dev/null
@@ -1,168 +0,0 @@
-'use client';
-
-import { Button } from '@tale/ui/button';
-import { Text } from '@tale/ui/text';
-import { useNavigate, useLocation, useSearch } from '@tanstack/react-router';
-import { ChevronLeft, ChevronRight, Loader2 } from 'lucide-react';
-import { useState, useEffect, useTransition } from 'react';
-
-import { Select } from '@/app/components/ui/forms/select';
-import { useT } from '@/lib/i18n/client';
-
-interface PaginationProps {
-  currentPage: number;
-  total?: number;
-  pageSize?: number; // Used for pagination calculations and dynamic size options
-  totalPages?: number; // Optional, for compatibility
-  hasNextPage?: boolean;
-  className?: string;
-  queryString?: string; // Additional query parameters to preserve
-}
-
-export function Pagination({
-  currentPage,
-  total = 0,
-  pageSize = 10,
-  totalPages,
-  hasNextPage,
-  className = '',
-  queryString = '',
-}: PaginationProps) {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const pathname = location.pathname;
-  const search: Record<string, string | undefined> = useSearch({
-    strict: false,
-  });
-  const [loadingStates, setLoadingStates] = useState({
-    prev: false,
-    next: false,
-  });
-  const [, startTransition] = useTransition();
-
-  useEffect(() => {
-    setLoadingStates({
-      prev: false,
-      next: false,
-    });
-  }, [search, pathname]);
-
-  const commitPage = (page: number) => {
-    startTransition(() => {
-      const newSearch = { ...search };
-
-      // If additional query params are provided, ensure they're included
-      if (queryString) {
-        const additionalParams = new URLSearchParams(queryString);
-        additionalParams.forEach((value, key) => {
-          // Don't overwrite the page parameter that we're about to set
-          if (key !== 'page') {
-            newSearch[key] = value;
-          }
-        });
-      }
-
-      if (page === 1) {
-        delete newSearch.page;
-      } else {
-        newSearch.page = page.toString();
-      }
-
-      void navigate({
-        to: pathname,
-        search: newSearch,
-      });
-    });
-  };
-
-  const handlePageChange = (direction: 'prev' | 'next') => {
-    const page = direction === 'prev' ? currentPage - 1 : currentPage + 1;
-    if (page < 1) return;
-    if (totalPages !== undefined && page > totalPages) return;
-    if (direction === 'next' && hasNextPage === false) return;
-    setLoadingStates((prev) => ({ ...prev, [direction]: true }));
-    commitPage(page);
-  };
-
-  const handlePageSelect = (newPage: string) => {
-    const page = parseInt(newPage);
-    if (page < 1) return;
-    if (totalPages !== undefined && page > totalPages) return;
-
-    commitPage(page);
-  };
-
-  // Calculate range
-  const isEmpty = total === 0;
-  const startIdx = isEmpty ? 0 : (currentPage - 1) * pageSize + 1;
-  const endIdx = Math.min(currentPage * pageSize, total);
-  // Use provided totalPages or calculate from total and pageSize
-  const totalPageCount = totalPages ?? Math.ceil(total / pageSize);
-  // Disable next button if we're on the last page or hasNextPage is explicitly false
-  const isNextDisabled = currentPage >= totalPageCount || hasNextPage === false;
-  const { t } = useT('common');
-
-  return (
-    <nav
-      aria-label={t('aria.pageNavigation')}
-      className={`flex items-center gap-2 ${className}`}
-    >
-      <Button
-        variant="ghost"
-        size="icon"
-        onClick={() => handlePageChange('prev')}
-        disabled={
-          isEmpty ||
-          currentPage === 1 ||
-          loadingStates.prev ||
-          loadingStates.next
-        }
-        aria-label={t('aria.previousPage')}
-        className="p-1.5"
-      >
-        {loadingStates.prev ? (
-          <Loader2 className="size-4 animate-spin" />
-        ) : (
-          <ChevronLeft className="size-4" />
-        )}
-      </Button>
-
-      <Select
-        value={currentPage.toString()}
-        onValueChange={handlePageSelect}
-        disabled={isEmpty}
-        className="h-8 w-auto min-w-16"
-        placeholder="-"
-        options={Array.from({ length: totalPageCount }, (_, i) => ({
-          value: (i + 1).toString(),
-          label: (i + 1).toString(),
-        }))}
-      />
-
-      <Button
-        variant="ghost"
-        size="icon"
-        onClick={() => handlePageChange('next')}
-        disabled={
-          isEmpty || isNextDisabled || loadingStates.prev || loadingStates.next
-        }
-        aria-label={t('aria.nextPage')}
-        className="p-1.5"
-      >
-        {loadingStates.next ? (
-          <Loader2 className="size-4 animate-spin" />
-        ) : (
-          <ChevronRight className="size-4" />
-        )}
-      </Button>
-
-      <Text
-        as="span"
-        variant="caption"
-        className="font-semibold whitespace-nowrap"
-      >
-        {isEmpty ? 'No items' : `${startIdx}-${endIdx} of ${total}`}
-      </Text>
-    </nav>
-  );
-}
diff --git a/services/platform/app/components/ui/wizard/wizard-footer.tsx b/services/platform/app/components/ui/wizard/wizard-footer.tsx
index 525c8c3545..2e0ddbd798 100644
--- a/services/platform/app/components/ui/wizard/wizard-footer.tsx
+++ b/services/platform/app/components/ui/wizard/wizard-footer.tsx
@@ -77,7 +77,6 @@ export function WizardFooter({
         {showSkip && (
           <Button
             variant="ghost"
-            size="sm"
             onClick={skip}
             disabled={submitting}
             className="mx-auto"
diff --git a/services/platform/app/features/agents/components/agent-catalog.tsx b/services/platform/app/features/agents/components/agent-catalog.tsx
index 4d926fa363..da31473352 100644
--- a/services/platform/app/features/agents/components/agent-catalog.tsx
+++ b/services/platform/app/features/agents/components/agent-catalog.tsx
@@ -14,7 +14,7 @@ import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
 import { Card } from '@tale/ui/card';
 import { EmptyState } from '@tale/ui/empty-state';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -383,25 +383,19 @@ function AgentCatalogCard({
       }
       actions={
         !entry.installed ? (
-          <Button size="sm" isLoading={pending} onClick={onInstall}>
+          <Button isLoading={pending} onClick={onInstall}>
             {t('install')}
           </Button>
         ) : (
           <>
             <Button
-              size="sm"
               isLoading={pending}
               variant={entry.enabled ? 'secondary' : 'primary'}
               onClick={onToggleEnabled}
             >
               {entry.enabled ? t('disable') : t('enable')}
             </Button>
-            <Button
-              size="sm"
-              variant="ghost"
-              disabled={pending}
-              onClick={onUninstall}
-            >
+            <Button variant="ghost" disabled={pending} onClick={onUninstall}>
               {t('uninstall')}
             </Button>
           </>
@@ -419,25 +413,25 @@ function AgentCatalogCard({
  */
 function CatalogCardSkeleton() {
   return (
-    <Card contentClassName="flex h-full flex-col p-4">
-      <div className="flex items-start gap-3">
+    <Card padding="md" className="flex h-full flex-col">
+      <Row gap={3} align="start">
         <SkeletonBox>
           <div className="size-10 rounded-lg" />
         </SkeletonBox>
-        <div className="flex min-w-0 flex-1 flex-col gap-1">
-          <div className="flex items-start justify-between gap-2">
+        <Stack gap={1} className="min-w-0 flex-1">
+          <Row gap={2} align="start" justify="between">
             <div className="w-28 text-sm leading-none">
               <SkeletonText />
             </div>
             <SkeletonBox>
               <div className="h-5 w-16 rounded-full" />
             </SkeletonBox>
-          </div>
+          </Row>
           <div className="text-sm leading-snug">
             <SkeletonText lines={2} />
           </div>
-        </div>
-      </div>
+        </Stack>
+      </Row>
       <div className="mt-auto pt-4">
         <SkeletonBox>
           <div className="h-8 w-20 rounded-md" />
diff --git a/services/platform/app/features/agents/components/agent-knowledge.tsx b/services/platform/app/features/agents/components/agent-knowledge.tsx
index 37f7f79421..254e6c3e60 100644
--- a/services/platform/app/features/agents/components/agent-knowledge.tsx
+++ b/services/platform/app/features/agents/components/agent-knowledge.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { EmptyPlaceholder } from '@tale/ui/empty-placeholder';
+import { Row } from '@tale/ui/layout';
 import { PageSection } from '@tale/ui/page-section';
 import { SectionHeader } from '@tale/ui/section-header';
 import { Text } from '@tale/ui/text';
@@ -45,7 +46,7 @@ interface DocumentEntry {
 
 function DocumentRow({ doc }: { doc: DocumentEntry }) {
   return (
-    <div className="flex items-center gap-3 px-4 py-3">
+    <Row gap={3} className="px-4 py-3">
       <FileText
         className="text-muted-foreground size-4 shrink-0"
         aria-hidden="true"
@@ -64,7 +65,7 @@ function DocumentRow({ doc }: { doc: DocumentEntry }) {
         error={doc.ragError}
         documentId={doc.id}
       />
-    </div>
+    </Row>
   );
 }
 
@@ -81,7 +82,7 @@ function AgentFileRow({
   const [confirmOpen, setConfirmOpen] = useState(false);
 
   return (
-    <div className="flex items-center gap-3 px-4 py-3">
+    <Row gap={3} className="px-4 py-3">
       <FileText
         className="text-muted-foreground size-4 shrink-0"
         aria-hidden="true"
@@ -106,7 +107,7 @@ function AgentFileRow({
             variant="ghost"
             size="icon"
             onClick={() => setConfirmOpen(true)}
-            aria-label={t('agents.knowledge.removeFile')}
+            title={t('agents.knowledge.removeFile')}
           >
             <Trash2 className="text-muted-foreground size-4" />
           </Button>
@@ -123,7 +124,7 @@ function AgentFileRow({
           />
         </>
       )}
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/agents/components/agent-metrics-scorecard.test.tsx b/services/platform/app/features/agents/components/agent-metrics-scorecard.test.tsx
index 4bb5c03667..6c624a1ae4 100644
--- a/services/platform/app/features/agents/components/agent-metrics-scorecard.test.tsx
+++ b/services/platform/app/features/agents/components/agent-metrics-scorecard.test.tsx
@@ -7,7 +7,7 @@ import { render, screen } from '@/tests/utils/render';
 // (render-only, no run data)". A freshly-created agent has no runs, so the
 // scorecard route renders its KPI grid with zeroed values plus the "no runs"
 // empty state. The E2E only asserted the section's primary heading
-// (workforce.scorecard.title => "Performance") and the empty-state copy
+// (workforce.scorecard.title => "Agent Metrics") and the empty-state copy
 // (workforce.scorecard.noRuns => "No runs yet.") — i.e. pure prop/empty-state
 // render driven by the (empty) getAgentScorecard payload, not a backend
 // round-trip. The single Convex query is mocked to the no-data shape and the
@@ -63,10 +63,10 @@ describe('AgentMetricsTab scorecard (render-only, no run data)', () => {
 
     const { container } = render(<AgentMetricsTab />);
 
-    // workforce.scorecard.title — SectionHeader defaults to an <h2>, matching the
-    // E2E's getByRole('heading', { name, level: 2 }).
+    // workforce.scorecard.title — MetricsLayout renders the title as an <h2>,
+    // matching the E2E's getByRole('heading', { name, level: 2 }).
     expect(
-      screen.getByRole('heading', { name: 'Performance', level: 2 }),
+      screen.getByRole('heading', { name: 'Agent Metrics', level: 2 }),
     ).toBeInTheDocument();
 
     // workforce.scorecard.noRuns — the empty-state copy for an agent with no runs.
diff --git a/services/platform/app/features/agents/components/agent-navigation.tsx b/services/platform/app/features/agents/components/agent-navigation.tsx
index 8aba4281d3..78bcc477d9 100644
--- a/services/platform/app/features/agents/components/agent-navigation.tsx
+++ b/services/platform/app/features/agents/components/agent-navigation.tsx
@@ -84,7 +84,6 @@ const AGENT_TAB_DIRTY_KEYS = {
     'knowledgeTopK',
   ],
   delegation: [],
-  responseTuning: ['responseTuning'],
   conversationStarters: ['conversationStarters'],
   webhook: [],
   // Env/secrets live in the `agentEnv` side-table, not the agent file — so this
@@ -218,16 +217,6 @@ export function AgentNavigation({
       matchMode: 'exact',
       dirtyKeys: AGENT_TAB_DIRTY_KEYS.delegation,
     },
-    ...(isChat
-      ? [
-          {
-            label: t('agents.navigation.responseTuning'),
-            href: `${basePath}/response-tuning`,
-            matchMode: 'exact' as const,
-            dirtyKeys: AGENT_TAB_DIRTY_KEYS.responseTuning,
-          },
-        ]
-      : []),
     {
       label: t('agents.navigation.conversationStarters'),
       href: `${basePath}/conversation-starters`,
@@ -452,7 +441,6 @@ export function AgentNavigation({
                 <Button
                   variant="secondary"
                   size="sm"
-                  className="h-8 text-sm"
                   icon={History}
                   iconClassName="size-3.5"
                   collapseLabel
diff --git a/services/platform/app/features/agents/components/agent-response-tuning.tsx b/services/platform/app/features/agents/components/agent-response-tuning.tsx
deleted file mode 100644
index 19d602c36d..0000000000
--- a/services/platform/app/features/agents/components/agent-response-tuning.tsx
+++ /dev/null
@@ -1,158 +0,0 @@
-'use client';
-
-import { CollapsibleDetails } from '@tale/ui/collapsible-details';
-import { PageSection } from '@tale/ui/page-section';
-import { SectionHeader } from '@tale/ui/section-header';
-import { useCallback } from 'react';
-
-import { ContentArea } from '@/app/components/layout/content-area';
-import { RadioGroup } from '@/app/components/ui/forms/radio-group';
-import { useT } from '@/lib/i18n/client';
-import type { ResponseTuningConfig } from '@/lib/shared/schemas/agents';
-
-import { useAgentConfig } from '../hooks/use-agent-config-context';
-
-interface AgentResponseTuningProps {
-  organizationId: string;
-  agentId: string;
-}
-
-// Typed option lists — also used to narrow RadioGroup's `string` callback value
-// back to the literal union WITHOUT an unsafe cast (`find` returns the literal).
-const EFFORT = ['adaptive', 'low', 'medium', 'high'] as const;
-const CREATIVITY = ['adaptive', 'precise', 'balanced', 'creative'] as const;
-const STYLE = [
-  'adaptive',
-  'concise',
-  'detailed',
-  'formal',
-  'friendly',
-] as const;
-const VERBOSITY = ['adaptive', 'terse', 'normal', 'verbose'] as const;
-const QUALITY = ['lenient', 'balanced', 'strict'] as const;
-const BOUND = ['off', 'low', 'medium', 'high'] as const;
-
-function narrow<T extends string>(
-  value: string,
-  allowed: readonly T[],
-): T | undefined {
-  return allowed.find((a) => a === value);
-}
-
-const cap = (v: string) => `${v.charAt(0).toUpperCase()}${v.slice(1)}`;
-
-export function AgentResponseTuning(_props: AgentResponseTuningProps) {
-  const { t } = useT('settings');
-  const { config, updateConfig } = useAgentConfig();
-  const tuning: ResponseTuningConfig = config.responseTuning ?? {};
-
-  const patch = useCallback(
-    (next: Partial<ResponseTuningConfig>) => {
-      // Functional update so each field merges onto the LATEST responseTuning,
-      // not a render-closure snapshot — two fields committing in the same tick
-      // can't stomp each other.
-      updateConfig((prev) => ({
-        responseTuning: { ...prev.responseTuning, ...next },
-      }));
-    },
-    [updateConfig],
-  );
-
-  const k = (suffix: string) => t(`agents.responseTuning.${suffix}`);
-  const opt = (values: readonly string[], keyOf: (v: string) => string) =>
-    values.map((value) => ({ value, label: k(keyOf(value)) }));
-
-  // The four primary controls each map a value to its i18n label key: the
-  // `adaptive`/`off` sentinels have their own key, the rest are `<field><Cap>`.
-  const labelKey = (field: string) => (v: string) =>
-    v === 'adaptive' ? 'adaptive' : `${field}${cap(v)}`;
-  const boundKey = (v: string) =>
-    v === 'off' ? 'boundNone' : `effort${cap(v)}`;
-
-  return (
-    <ContentArea variant="narrow" gap={6}>
-      <SectionHeader title={k('title')} description={k('autoNote')} />
-
-      {/* The Auto router and adaptive reasoning governor handle these per
-          message; everything here is an optional override, collapsed by default
-          so the common (fully-automatic) case stays uncluttered. */}
-      <CollapsibleDetails summary={k('overridesSummary')}>
-        <div className="mt-4 flex flex-col gap-6">
-          <RadioGroup
-            label={k('effort')}
-            description={k('effortHelp')}
-            value={tuning.effort ?? 'adaptive'}
-            onValueChange={(v) => patch({ effort: narrow(v, EFFORT) })}
-            options={opt(EFFORT, labelKey('effort'))}
-          />
-
-          <RadioGroup
-            label={k('creativity')}
-            description={k('creativityHelp')}
-            value={tuning.creativity ?? 'adaptive'}
-            onValueChange={(v) => patch({ creativity: narrow(v, CREATIVITY) })}
-            options={opt(CREATIVITY, labelKey('creativity'))}
-          />
-
-          <RadioGroup
-            label={k('style')}
-            description={k('styleHelp')}
-            value={tuning.style ?? 'adaptive'}
-            onValueChange={(v) => patch({ style: narrow(v, STYLE) })}
-            options={opt(STYLE, labelKey('style'))}
-          />
-
-          <RadioGroup
-            label={k('verbosity')}
-            description={k('verbosityHelp')}
-            value={tuning.verbosity ?? 'adaptive'}
-            onValueChange={(v) => patch({ verbosity: narrow(v, VERBOSITY) })}
-            options={opt(VERBOSITY, labelKey('verbosity'))}
-          />
-
-          <PageSection
-            as="h3"
-            titleSize="sm"
-            titleWeight="medium"
-            title={k('advancedTitle')}
-            description={k('advancedHelp')}
-            gap={4}
-          >
-            <RadioGroup
-              label={k('qualityProfile')}
-              description={k('qualityProfileHelp')}
-              value={tuning.qualityProfile ?? 'balanced'}
-              onValueChange={(v) =>
-                patch({ qualityProfile: narrow(v, QUALITY) })
-              }
-              options={opt(QUALITY, (v) => `quality${cap(v)}`)}
-            />
-
-            <div className="grid grid-cols-2 gap-3">
-              <RadioGroup
-                label={k('effortFloor')}
-                description={k('effortFloorHelp')}
-                value={tuning.effortFloor ?? 'off'}
-                onValueChange={(v) => {
-                  const b = narrow(v, BOUND);
-                  patch({ effortFloor: b === 'off' ? undefined : b });
-                }}
-                options={opt(BOUND, boundKey)}
-              />
-              <RadioGroup
-                label={k('effortCeiling')}
-                description={k('effortCeilingHelp')}
-                value={tuning.effortCeiling ?? 'off'}
-                onValueChange={(v) => {
-                  const b = narrow(v, BOUND);
-                  patch({ effortCeiling: b === 'off' ? undefined : b });
-                }}
-                options={opt(BOUND, boundKey)}
-              />
-            </div>
-          </PageSection>
-        </div>
-      </CollapsibleDetails>
-    </ContentArea>
-  );
-}
diff --git a/services/platform/app/features/agents/components/agent-webhook-section.tsx b/services/platform/app/features/agents/components/agent-webhook-section.tsx
index f07849dde6..970dbf49da 100644
--- a/services/platform/app/features/agents/components/agent-webhook-section.tsx
+++ b/services/platform/app/features/agents/components/agent-webhook-section.tsx
@@ -3,6 +3,7 @@
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
 import { CodeBlock } from '@tale/ui/code-block';
+import { Row } from '@tale/ui/layout';
 import { SectionHeader } from '@tale/ui/section-header';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
@@ -162,7 +163,7 @@ export function AgentWebhookSection({
         cell: ({ row }) => {
           const url = getWebhookUrl(row.original.token);
           return (
-            <div className="flex min-w-0 items-center gap-2">
+            <Row gap={2} className="min-w-0">
               <code
                 className="max-w-[300px] truncate font-mono text-sm"
                 title={url}
@@ -171,7 +172,6 @@ export function AgentWebhookSection({
               </code>
               <Button
                 variant="ghost"
-                size="sm"
                 onClick={() => handleCopyUrl(row.original.token)}
                 aria-label={t('agents.webhook.copyUrl')}
                 className="shrink-0"
@@ -182,7 +182,7 @@ export function AgentWebhookSection({
                   <Copy className="size-3.5" />
                 )}
               </Button>
-            </div>
+            </Row>
           );
         },
         size: 400,
@@ -215,7 +215,7 @@ export function AgentWebhookSection({
         id: 'actions',
         header: '',
         cell: ({ row }) => (
-          <div className="flex items-center justify-end gap-1">
+          <Row gap={1} justify="end">
             <Button
               variant="ghost"
               size="sm"
@@ -232,7 +232,7 @@ export function AgentWebhookSection({
             >
               <Trash2 className="size-4" />
             </Button>
-          </div>
+          </Row>
         ),
         size: 100,
       },
@@ -298,7 +298,6 @@ export function AgentWebhookSection({
         action={
           <Button
             variant="secondary"
-            size="sm"
             onClick={handleCreate}
             disabled={isCreating}
           >
diff --git a/services/platform/app/features/agents/components/agents-table.tsx b/services/platform/app/features/agents/components/agents-table.tsx
index 334bd6ae93..5837c44770 100644
--- a/services/platform/app/features/agents/components/agents-table.tsx
+++ b/services/platform/app/features/agents/components/agents-table.tsx
@@ -3,7 +3,7 @@
 import { useQueryClient } from '@tanstack/react-query';
 import { useNavigate } from '@tanstack/react-router';
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { Bot, Plus } from 'lucide-react';
+import { Bot } from 'lucide-react';
 import { useMemo, useCallback, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -323,11 +323,6 @@ export function AgentsTable({
         icon: Bot,
         title: tEmpty('agents.title'),
         description: tEmpty('agents.description'),
-        action: {
-          label: tSettings('agents.createAgent'),
-          icon: Plus,
-          onClick: () => setCreateOpen(true),
-        },
       }}
       footer={
         <BulkDeleteBar
diff --git a/services/platform/app/features/agents/components/byo-model-editor.tsx b/services/platform/app/features/agents/components/byo-model-editor.tsx
index 7cce0b61b0..ea9a4a237e 100644
--- a/services/platform/app/features/agents/components/byo-model-editor.tsx
+++ b/services/platform/app/features/agents/components/byo-model-editor.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Plus } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
@@ -99,7 +100,7 @@ export function ByoModelEditor({ models, onChange }: ByoModelEditorProps) {
           </code>
         )}
       />
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <Input
           value={draft}
           onChange={(e) => setDraft(e.target.value)}
@@ -124,7 +125,7 @@ export function ByoModelEditor({ models, onChange }: ByoModelEditorProps) {
         >
           {t('agents.form.addModel')}
         </Button>
-      </div>
+      </Row>
     </div>
   );
 }
diff --git a/services/platform/app/features/agents/components/history-diff-dialog.tsx b/services/platform/app/features/agents/components/history-diff-dialog.tsx
index 8aca6210e0..6d9dbe28f5 100644
--- a/services/platform/app/features/agents/components/history-diff-dialog.tsx
+++ b/services/platform/app/features/agents/components/history-diff-dialog.tsx
@@ -2,6 +2,7 @@
 
 import 'json-diff-kit/viewer.css';
 import { Button } from '@tale/ui/button';
+import { Grid, Row } from '@tale/ui/layout';
 import { Differ, Viewer } from 'json-diff-kit';
 import { useMemo } from 'react';
 
@@ -66,7 +67,7 @@ export function HistoryDiffDialog({
       })}
       size="wide"
       footer={
-        <div className="flex justify-end gap-2">
+        <Row gap={2} align="stretch" justify="end">
           <Button
             variant="secondary"
             onClick={() => onOpenChange(false)}
@@ -83,7 +84,7 @@ export function HistoryDiffDialog({
               ? tCommon('actions.loading')
               : t('agents.history.restore')}
           </Button>
-        </div>
+        </Row>
       }
     >
       {!hasChanges ? (
@@ -92,14 +93,18 @@ export function HistoryDiffDialog({
         </p>
       ) : (
         <div className="json-diff-wrapper max-h-[50vh] overflow-auto rounded-md border">
-          <div className="bg-muted sticky top-0 z-20 grid grid-cols-2 border-b">
+          <Grid
+            cols={2}
+            gap={0}
+            className="bg-muted sticky top-0 z-20 border-b"
+          >
             <div className="text-muted-foreground px-3 py-1.5 text-xs font-medium">
               {t('agents.history.currentVersion')}
             </div>
             <div className="text-muted-foreground border-l px-3 py-1.5 text-xs font-medium">
               {t('agents.history.snapshotVersion')}
             </div>
-          </div>
+          </Grid>
           <Viewer
             diff={diff}
             indent={2}
diff --git a/services/platform/app/features/agents/hooks/use-agent-config-context.test.tsx b/services/platform/app/features/agents/hooks/use-agent-config-context.test.tsx
index 8db8810685..1ff1ee9117 100644
--- a/services/platform/app/features/agents/hooks/use-agent-config-context.test.tsx
+++ b/services/platform/app/features/agents/hooks/use-agent-config-context.test.tsx
@@ -193,12 +193,12 @@ describe('useAgentConfig', () => {
   it('stays clean when a nested patch only reorders keys (no false dirty)', () => {
     // Regression: dirty detection was `JSON.stringify(config) !==
     // JSON.stringify(saved)`, which is key-order-sensitive. Re-applying the
-    // same nested object with its keys in a different order (as the response
-    // tuning panel does on every patch) must NOT read as dirty.
+    // same nested object with its keys in a different order (as a config panel
+    // does on every patch) must NOT read as dirty.
     const { result } = renderHook(() => useAgentConfig(), {
       wrapper: createWrapper({
         ...BASE_CONFIG,
-        responseTuning: { effort: 'high', creativity: 'balanced' },
+        routing: { modelSelection: 'auto', cascade: true },
       }),
     });
     expect(result.current.isDirty).toBe(false);
@@ -206,10 +206,10 @@ describe('useAgentConfig', () => {
     act(() => {
       // Same content, keys reversed + an explicit `undefined` leaf.
       result.current.updateConfig({
-        responseTuning: {
-          creativity: 'balanced',
-          effort: 'high',
-          style: undefined,
+        routing: {
+          cascade: true,
+          modelSelection: 'auto',
+          cascadeDraftModel: undefined,
         },
       });
     });
@@ -217,16 +217,16 @@ describe('useAgentConfig', () => {
     expect(result.current.isDirty).toBe(false);
   });
 
-  it('becomes dirty on a real nested response-tuning change', () => {
+  it('becomes dirty on a real nested routing change', () => {
     const { result } = renderHook(() => useAgentConfig(), {
       wrapper: createWrapper({
         ...BASE_CONFIG,
-        responseTuning: { effort: 'high' },
+        routing: { modelSelection: 'auto' },
       }),
     });
 
     act(() => {
-      result.current.updateConfig({ responseTuning: { effort: 'low' } });
+      result.current.updateConfig({ routing: { modelSelection: 'config' } });
     });
 
     expect(result.current.isDirty).toBe(true);
diff --git a/services/platform/app/features/agents/hooks/use-agents-table-config.tsx b/services/platform/app/features/agents/hooks/use-agents-table-config.tsx
index 276f83a46e..027bdc7446 100644
--- a/services/platform/app/features/agents/hooks/use-agents-table-config.tsx
+++ b/services/platform/app/features/agents/hooks/use-agents-table-config.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Bot, Folder, Package } from 'lucide-react';
@@ -61,7 +61,7 @@ export function useAgentsTableConfig({
           if (row.original.type === 'folder') {
             const isApp = row.original.appSlug !== undefined;
             return (
-              <div className="flex min-h-8 items-center gap-3">
+              <Row gap={3} className="min-h-8">
                 {isApp ? (
                   <Package className="text-muted-foreground size-4 shrink-0" />
                 ) : (
@@ -72,11 +72,11 @@ export function useAgentsTableConfig({
                 </Text>
                 {isApp && <Badge variant="slate">{t('agents.appBadge')}</Badge>}
                 <Badge variant="outline">{row.original.agentCount}</Badge>
-              </div>
+              </Row>
             );
           }
           return (
-            <div className="flex min-h-8 items-center gap-3">
+            <Row gap={3} className="min-h-8">
               <Bot className="text-muted-foreground size-4 shrink-0" />
               <Text as="span" variant="label" truncate>
                 {showFolderPath && row.original.folderPath ? (
@@ -90,7 +90,7 @@ export function useAgentsTableConfig({
                   row.original.displayName
                 )}
               </Text>
-            </div>
+            </Row>
           );
         },
       },
diff --git a/services/platform/app/features/agents/organigram/humans-node.tsx b/services/platform/app/features/agents/organigram/humans-node.tsx
index ddb1082246..b78a144673 100644
--- a/services/platform/app/features/agents/organigram/humans-node.tsx
+++ b/services/platform/app/features/agents/organigram/humans-node.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Handle, Position, type NodeProps } from '@xyflow/react';
 import { Users } from 'lucide-react';
@@ -17,9 +18,10 @@ export function HumansNode({ data }: NodeProps<HumansFlowNode>) {
   const { t } = useT('organigram');
 
   return (
-    <div
+    <Row
       style={{ width: HUMANS_NODE_WIDTH }}
-      className="bg-muted/60 border-border flex items-center gap-3 rounded-lg border border-dashed p-3 text-left"
+      gap={3}
+      className="bg-muted/60 border-border rounded-lg border border-dashed p-3 text-left"
     >
       <span className="bg-foreground/10 text-foreground flex size-8 shrink-0 items-center justify-center rounded-md">
         <Users className="size-4.5" aria-hidden />
@@ -38,6 +40,6 @@ export function HumansNode({ data }: NodeProps<HumansFlowNode>) {
         isConnectable={false}
         className="size-1.5! border-0! bg-transparent!"
       />
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/agents/organigram/organigram-canvas.tsx b/services/platform/app/features/agents/organigram/organigram-canvas.tsx
index 6d90e85a7c..d546426575 100644
--- a/services/platform/app/features/agents/organigram/organigram-canvas.tsx
+++ b/services/platform/app/features/agents/organigram/organigram-canvas.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { EmptyState } from '@tale/ui/empty-state';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   Panel,
@@ -240,7 +241,11 @@ export function OrganigramCanvas({
   }
 
   return (
-    <div className="border-border flex h-[calc(100vh-220px)] min-h-105 overflow-hidden rounded-lg border">
+    <Row
+      gap={0}
+      align="stretch"
+      className="border-border h-[calc(100vh-220px)] min-h-105 overflow-hidden rounded-lg border"
+    >
       <div className="relative min-w-0 flex-1">
         <FlowCanvas
           nodes={nodes}
@@ -275,14 +280,16 @@ export function OrganigramCanvas({
         >
           {canEdit && isDirty && (
             <Panel position="top-right" className="m-3">
-              <div className="ring-border bg-background flex items-center gap-2 rounded-lg p-1.5 pl-3 shadow-sm ring-1">
+              <Row
+                gap={2}
+                className="ring-border bg-background rounded-lg p-1.5 pl-3 shadow-sm ring-1"
+              >
                 <Text variant="muted" className="text-xs">
                   {t('unsavedChanges')}
                 </Text>
                 <Button
                   type="button"
                   variant="secondary"
-                  size="sm"
                   icon={Undo2}
                   iconClassName="size-3.5"
                   disabled={isSaving}
@@ -292,7 +299,6 @@ export function OrganigramCanvas({
                 </Button>
                 <Button
                   type="button"
-                  size="sm"
                   disabled={isSaving}
                   aria-busy={isSaving ? 'true' : undefined}
                   onClick={() => void handleSave()}
@@ -306,7 +312,7 @@ export function OrganigramCanvas({
                     ? tCommon('actions.saving')
                     : tCommon('actions.save')}
                 </Button>
-              </div>
+              </Row>
             </Panel>
           )}
           {focusSlug && focusExists && <FocusOnNode slug={focusSlug} />}
@@ -343,6 +349,6 @@ export function OrganigramCanvas({
           }}
         />
       )}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/agents/organigram/organigram-panel.tsx b/services/platform/app/features/agents/organigram/organigram-panel.tsx
index 0384d04ea3..222cea2a14 100644
--- a/services/platform/app/features/agents/organigram/organigram-panel.tsx
+++ b/services/platform/app/features/agents/organigram/organigram-panel.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Link } from '@tanstack/react-router';
 import { ExternalLink, X } from 'lucide-react';
@@ -110,8 +111,11 @@ export function OrganigramPanel({
     }));
 
   return (
-    <aside className="border-border bg-card flex w-72 shrink-0 flex-col gap-4 overflow-y-auto border-l p-4">
-      <div className="flex items-start justify-between gap-2">
+    <Stack
+      as="aside"
+      className="border-border bg-card w-72 shrink-0 overflow-y-auto border-l p-4"
+    >
+      <Row gap={2} align="start" justify="between">
         <div className="min-w-0">
           <Text as="h3" variant="label" className="truncate">
             {node.displayName || node.slug}
@@ -124,10 +128,10 @@ export function OrganigramPanel({
           size="icon"
           variant="ghost"
           icon={X}
-          aria-label={t('panel.close')}
+          title={t('panel.close')}
           onClick={onClose}
         />
-      </div>
+      </Row>
 
       {node.description && (
         <Text as="p" variant="muted" className="text-sm">
@@ -157,7 +161,7 @@ export function OrganigramPanel({
         {t('panel.delegationHint')}
       </Text>
 
-      <Button asChild size="sm" variant="secondary" icon={ExternalLink}>
+      <Button asChild variant="secondary" icon={ExternalLink}>
         <Link
           to="/dashboard/$id/agents/$agentId"
           params={{ id: organizationId, agentId: node.slug }}
@@ -165,6 +169,6 @@ export function OrganigramPanel({
           {t('panel.openAgent')}
         </Link>
       </Button>
-    </aside>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/agents/workforce/hooks.ts b/services/platform/app/features/agents/workforce/hooks.ts
index 8db49f1d25..5a9e6e8d9e 100644
--- a/services/platform/app/features/agents/workforce/hooks.ts
+++ b/services/platform/app/features/agents/workforce/hooks.ts
@@ -47,8 +47,21 @@ export interface WorkforceLeaderboardRow {
   escalations: number;
 }
 
+/** Prior equal-length window totals (subset) — drives the KPI deltas. */
+export interface WorkforcePreviousTotals {
+  tasksCompleted: number;
+  agentRunsStarted: number;
+  reviewsPassed: number;
+  reviewsChangesRequested: number;
+  escalations: number;
+  cycleTimeSumMs: number;
+  cycleTimeCount: number;
+  totalCostCents: number;
+}
+
 export interface WorkforceMetricsPayload {
   totals: WorkforceTotals;
+  previousTotals: WorkforcePreviousTotals;
   trend: WorkforceTrendPoint[];
   leaderboard: WorkforceLeaderboardRow[];
 }
diff --git a/services/platform/app/features/agents/workforce/workforce-dashboard.tsx b/services/platform/app/features/agents/workforce/workforce-dashboard.tsx
index a065671a5f..3fa803cc09 100644
--- a/services/platform/app/features/agents/workforce/workforce-dashboard.tsx
+++ b/services/platform/app/features/agents/workforce/workforce-dashboard.tsx
@@ -1,10 +1,15 @@
 'use client';
 
+import { Alert } from '@tale/ui/alert';
 import { Badge } from '@tale/ui/badge';
-import { EmptyState } from '@tale/ui/empty-state';
-import { SkeletonBox } from '@tale/ui/skeleton';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
+import { Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
 import { Text } from '@tale/ui/text';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
 import { Link, useNavigate } from '@tanstack/react-router';
 import type { ColumnDef, Row } from '@tanstack/react-table';
 import {
@@ -15,17 +20,13 @@ import {
   PauseCircle,
   Power,
 } from 'lucide-react';
-import { useCallback, useMemo, type ReactNode } from 'react';
-import {
-  Bar,
-  BarChart,
-  CartesianGrid,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from 'recharts';
+import { useCallback, useMemo } from 'react';
 
+import {
+  seriesToLegend,
+  TrendBarChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { Switch } from '@/app/components/ui/forms/switch';
 import { useFormatDate } from '@/app/hooks/use-format-date';
@@ -51,61 +52,10 @@ function formatCents(cents: number): string {
   });
 }
 
-function formatHours(ms: number): string {
-  return (ms / (60 * 60 * 1000)).toFixed(1);
-}
-
 function shortDay(dateKey: string): string {
   return dateKey.slice(5);
 }
 
-/**
- * One bordered chart card — same chrome as the project metrics page: the
- * title always renders; the chart slot masks itself while loading and falls
- * back to an `EmptyState` when the period has no data.
- */
-function ChartCard({
-  title,
-  heightClassName,
-  isLoading,
-  isEmpty,
-  emptyTitle,
-  emptyDescription,
-  children,
-}: {
-  title: string;
-  heightClassName: string;
-  isLoading: boolean;
-  isEmpty: boolean;
-  emptyTitle: string;
-  emptyDescription: string;
-  children: ReactNode;
-}) {
-  return (
-    <section className="border-border bg-card rounded-lg border p-4">
-      <Text as="h3" variant="label">
-        {title}
-      </Text>
-      <div className={`mt-3 ${heightClassName}`}>
-        {isLoading ? (
-          <SkeletonBox fullWidth>
-            <div className={`w-full ${heightClassName}`} />
-          </SkeletonBox>
-        ) : isEmpty ? (
-          <EmptyState
-            icon={BarChart3}
-            title={emptyTitle}
-            description={emptyDescription}
-            className="h-full py-0"
-          />
-        ) : (
-          children
-        )}
-      </div>
-    </section>
-  );
-}
-
 /**
  * The workforce dashboard (mirrors the automations / project metrics pages):
  * master automation toggle, operational health strip, paired KPI stat cards
@@ -134,12 +84,20 @@ export function WorkforceDashboard({
   const setAutomation = useSetTaskAutomation();
 
   const totals = metrics?.totals;
+  const prevTotals = metrics?.previousTotals;
+
   const interventionEvents =
     (totals?.reviewsChangesRequested ?? 0) + (totals?.escalations ?? 0);
   const interventionRate =
     totals && totals.agentRunsStarted > 0
       ? Math.round((interventionEvents / totals.agentRunsStarted) * 100)
       : 0;
+  const prevInterventionEvents =
+    (prevTotals?.reviewsChangesRequested ?? 0) + (prevTotals?.escalations ?? 0);
+  const prevInterventionRate =
+    prevTotals && prevTotals.agentRunsStarted > 0
+      ? Math.round((prevInterventionEvents / prevTotals.agentRunsStarted) * 100)
+      : undefined;
   const reviewPassRate =
     totals && totals.reviewsPassed + totals.reviewsChangesRequested > 0
       ? Math.round(
@@ -150,51 +108,34 @@ export function WorkforceDashboard({
       : undefined;
   const avgCycleHours =
     totals && totals.cycleTimeCount > 0
-      ? formatHours(totals.cycleTimeSumMs / totals.cycleTimeCount)
+      ? totals.cycleTimeSumMs / totals.cycleTimeCount / 3_600_000
+      : undefined;
+  const prevAvgCycleHours =
+    prevTotals && prevTotals.cycleTimeCount > 0
+      ? prevTotals.cycleTimeSumMs / prevTotals.cycleTimeCount / 3_600_000
       : undefined;
 
-  const stats = [
-    {
-      label: t('kpi.completed', { days: periodDays }),
-      value: String(totals?.tasksCompleted ?? 0),
-      detail: t('kpi.completedDetail', {
-        agent: totals?.agentCompleted ?? 0,
-        human: totals?.humanCompleted ?? 0,
-      }),
-    },
-    {
-      label: t('kpi.intervention'),
-      value: `${interventionRate}%`,
-      detail:
-        reviewPassRate !== undefined
-          ? t('kpi.reviewPassRate', { pct: reviewPassRate })
-          : t('kpi.noReviews'),
-    },
+  const trendData = (metrics?.trend ?? []).map((point) => ({
+    dateKey: point.dateKey,
+    tasksCompleted: point.tasksCompleted,
+    agentRunsFailed: point.agentRunsFailed,
+  }));
+  const trendSeries: ChartSeries[] = [
     {
-      label: t('kpi.cycleTime'),
-      value: avgCycleHours !== undefined ? `${avgCycleHours}h` : '—',
-      detail: t('kpi.runs', {
-        started: totals?.agentRunsStarted ?? 0,
-        failed: totals?.agentRunsFailed ?? 0,
-      }),
+      key: 'tasksCompleted',
+      label: t('trend.completed'),
+      color: CHART_COLORS.success,
     },
     {
-      label: t('kpi.cost', { days: periodDays }),
-      value: formatCents(totals?.totalCostCents ?? 0),
-      detail: t('kpi.costDetail', {
-        perTask:
-          totals && totals.tasksCompleted > 0
-            ? formatCents(totals.totalCostCents / totals.tasksCompleted)
-            : '0.00',
-      }),
+      key: 'agentRunsFailed',
+      label: t('trend.failedRuns'),
+      color: CHART_COLORS.failure,
     },
   ];
-
-  const trendData = (metrics?.trend ?? []).map((point) => ({
-    label: shortDay(point.dateKey),
-    tasksCompleted: point.tasksCompleted,
-    agentRunsFailed: point.agentRunsFailed,
-  }));
+  // `every` is true for an empty array, so this also covers "no data at all".
+  const noTrend = trendData.every(
+    (d) => d.tasksCompleted + d.agentRunsFailed === 0,
+  );
 
   const leaderboardRows = useMemo(
     () => (metrics?.leaderboard ?? []).slice(0, 10),
@@ -301,9 +242,13 @@ export function WorkforceDashboard({
   };
 
   return (
-    <div className="flex flex-col gap-4">
+    <Stack>
       {/* Master toggle + health strip */}
-      <section className="border-border bg-card flex flex-col gap-3 rounded-lg border p-4">
+      <Stack
+        as="section"
+        gap={3}
+        className="border-border bg-card rounded-lg border p-4"
+      >
         <div className="flex flex-wrap items-center justify-between gap-3">
           <div className="flex items-center gap-2">
             <Power
@@ -362,73 +307,126 @@ export function WorkforceDashboard({
             )}
           </div>
         )}
-      </section>
+      </Stack>
 
       {!isLoading && totals?.capped ? (
-        <div className="border-border bg-muted/40 rounded-md border px-3 py-2 text-xs">
-          {t('cappedNotice')}
-        </div>
+        <Alert
+          variant="warning"
+          icon={AlertTriangle}
+          title={t('cappedNotice')}
+        />
       ) : null}
 
       <Skeletonize loading={isLoading} className="flex flex-col gap-4">
-        {/* Paired KPI stat cards */}
-        <section className="grid grid-cols-2 gap-3 lg:grid-cols-4">
-          {stats.map((stat) => (
-            <div
-              key={stat.label}
-              className="border-border bg-card flex flex-col gap-1 rounded-lg border p-3"
-            >
+        {/* Paired KPI stat cards — same StatCardGrid + delta treatment as the
+            other metrics surfaces. Outcome + intervention + cost always travel
+            together (cost is never shown alone). */}
+        <StatCardGrid cols={4}>
+          <StatCard
+            label={t('kpi.completed', { days: periodDays })}
+            value={String(totals?.tasksCompleted ?? 0)}
+          >
+            <div className="mt-0.5 flex flex-col gap-1">
+              <TrendIndicator
+                value={totals?.tasksCompleted ?? 0}
+                previous={prevTotals?.tasksCompleted}
+              />
               <Text as="p" variant="muted" className="text-xs">
-                {stat.label}
+                {t('kpi.completedDetail', {
+                  agent: totals?.agentCompleted ?? 0,
+                  human: totals?.humanCompleted ?? 0,
+                })}
               </Text>
-              <SkeletonBox>
-                <Text as="p" className="text-xl font-semibold tabular-nums">
-                  {stat.value}
-                </Text>
-              </SkeletonBox>
-              <SkeletonBox>
-                <Text as="p" variant="muted" className="text-xs">
-                  {stat.detail}
-                </Text>
-              </SkeletonBox>
             </div>
-          ))}
-        </section>
+          </StatCard>
 
-        {/* Trend */}
+          <StatCard
+            label={t('kpi.intervention')}
+            value={`${interventionRate}%`}
+          >
+            <div className="mt-0.5 flex flex-col gap-1">
+              <TrendIndicator
+                value={interventionRate}
+                previous={prevInterventionRate}
+                inverted
+              />
+              <Text as="p" variant="muted" className="text-xs">
+                {reviewPassRate !== undefined
+                  ? t('kpi.reviewPassRate', { pct: reviewPassRate })
+                  : t('kpi.noReviews')}
+              </Text>
+            </div>
+          </StatCard>
+
+          <StatCard
+            label={t('kpi.cycleTime')}
+            value={
+              avgCycleHours !== undefined ? `${avgCycleHours.toFixed(1)}h` : '—'
+            }
+          >
+            <div className="mt-0.5 flex flex-col gap-1">
+              {avgCycleHours !== undefined ? (
+                <TrendIndicator
+                  value={avgCycleHours}
+                  previous={prevAvgCycleHours}
+                  inverted
+                />
+              ) : null}
+              <Text as="p" variant="muted" className="text-xs">
+                {t('kpi.runs', {
+                  started: totals?.agentRunsStarted ?? 0,
+                  failed: totals?.agentRunsFailed ?? 0,
+                })}
+              </Text>
+            </div>
+          </StatCard>
+
+          <StatCard
+            label={t('kpi.cost', { days: periodDays })}
+            value={formatCents(totals?.totalCostCents ?? 0)}
+          >
+            <div className="mt-0.5 flex flex-col gap-1">
+              <TrendIndicator
+                value={totals?.totalCostCents ?? 0}
+                previous={prevTotals?.totalCostCents}
+                inverted
+              />
+              <Text as="p" variant="muted" className="text-xs">
+                {t('kpi.costDetail', {
+                  perTask:
+                    totals && totals.tasksCompleted > 0
+                      ? formatCents(
+                          totals.totalCostCents / totals.tasksCompleted,
+                        )
+                      : '0.00',
+                })}
+              </Text>
+            </div>
+          </StatCard>
+        </StatCardGrid>
+
+        {/* Activity trend */}
         <ChartCard
           title={t('trend.title')}
-          heightClassName="h-52"
-          isLoading={isLoading}
-          isEmpty={trendData.length === 0}
+          bodyClassName="h-52"
+          loading={isLoading}
+          isEmpty={noTrend}
+          emptyIcon={BarChart3}
           emptyTitle={t('noData')}
           emptyDescription={t('noDataDescription')}
+          legend={<ChartLegend items={seriesToLegend(trendSeries)} />}
         >
-          <ResponsiveContainer width="100%" height="100%">
-            <BarChart data={trendData}>
-              <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-              <XAxis dataKey="label" fontSize={11} />
-              <YAxis allowDecimals={false} fontSize={11} width={28} />
-              <Tooltip />
-              <Bar
-                dataKey="tasksCompleted"
-                name={t('trend.completed')}
-                fill="var(--color-chart-success, #10b981)"
-                radius={[2, 2, 0, 0]}
-              />
-              <Bar
-                dataKey="agentRunsFailed"
-                name={t('trend.failedRuns')}
-                fill="var(--color-chart-failure, #ef4444)"
-                radius={[2, 2, 0, 0]}
-              />
-            </BarChart>
-          </ResponsiveContainer>
+          <TrendBarChart
+            data={trendData}
+            series={trendSeries}
+            xKey="dateKey"
+            xTickFormatter={shortDay}
+          />
         </ChartCard>
       </Skeletonize>
 
       {/* Leaderboard */}
-      <div className="flex flex-col gap-3">
+      <Stack gap={3}>
         <h2 className="text-base font-semibold">{t('leaderboard.title')}</h2>
         <DataTable
           caption={t('leaderboard.title')}
@@ -444,7 +442,7 @@ export function WorkforceDashboard({
             description: t('noDataDescription'),
           }}
         />
-      </div>
+      </Stack>
 
       {/* Needs attention */}
       {attention && (
@@ -501,7 +499,7 @@ export function WorkforceDashboard({
           />
         </section>
       )}
-    </div>
+    </Stack>
   );
 }
 
@@ -540,7 +538,7 @@ function AttentionList({
           {emptyLabel}
         </Text>
       ) : (
-        <ul className="mt-2 flex flex-col gap-1">
+        <Stack as="ul" gap={1} className="mt-2">
           {items.slice(0, 8).map((item) => (
             <li
               key={item.key}
@@ -568,7 +566,7 @@ function AttentionList({
               )}
             </li>
           ))}
-        </ul>
+        </Stack>
       )}
     </div>
   );
diff --git a/services/platform/app/features/analytics/feedback/feedback-metrics-page.tsx b/services/platform/app/features/analytics/feedback/feedback-metrics-page.tsx
index 758aa52d72..a5e82201e1 100644
--- a/services/platform/app/features/analytics/feedback/feedback-metrics-page.tsx
+++ b/services/platform/app/features/analytics/feedback/feedback-metrics-page.tsx
@@ -2,13 +2,26 @@
 
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
+import { HStack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
-import { Text } from '@tale/ui/text';
 import type { FunctionReturnType } from 'convex/server';
 import { AlertTriangle } from 'lucide-react';
 import { useCallback, useMemo } from 'react';
 
+import {
+  seriesToLegend,
+  TrendBarChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
+import { MetricSelect } from '@/app/components/metrics/metric-select';
+import {
+  MetricsFilterChips,
+  type MetricsFilterChip,
+} from '@/app/components/metrics/metrics-filter-chips';
+import { MetricsLayout } from '@/app/components/metrics/metrics-layout';
 import { Select } from '@/app/components/ui/forms/select';
 import { Switch } from '@/app/components/ui/forms/switch';
 import { useCachedPaginatedQuery } from '@/app/hooks/use-cached-paginated-query';
@@ -19,7 +32,6 @@ import { useT } from '@/lib/i18n/client';
 import { ArenaSummary } from './arena-summary';
 import { periodToDays, type FeedbackPeriod } from './feedback-period';
 import { FeedbackSummaryCards } from './feedback-summary-cards';
-import { FilterChips } from './filter-chips';
 import { RecentFeedbackTable } from './recent-feedback-table';
 import { TopAgentsFeedbackTable } from './top-agents-feedback-table';
 import { TopMatchupsFeedbackTable } from './top-matchups-feedback-table';
@@ -139,84 +151,108 @@ export function FeedbackMetricsPageView({
   // structure so nothing pops in when the real numbers arrive.
   const showMatchups = loading || (stats?.topMatchups.length ?? 0) > 0;
 
-  return (
-    <Stack gap={6}>
-      <div className="flex flex-col gap-3 md:flex-row md:items-start md:justify-between">
-        <Header
-          title={t('feedback.title')}
-          description={t('feedback.description')}
-        />
-        <HStack gap={2} className="flex-wrap">
-          <div className="w-36">
-            <Select
-              options={periodOptions}
-              value={period}
-              onValueChange={onChangePeriod}
-              size="sm"
-              aria-label={t('feedback.period.label')}
-            />
-          </div>
-        </HStack>
-      </div>
-
-      <FilterChips
-        agentSlug={agentSlug}
-        model={model}
-        provider={provider}
-        onClearAgent={() => onSelectAgent(null)}
-        onClearModel={() => onSelectModel(null, null)}
-        onClearAll={onClearFilters}
-      />
-
-      {/* These notices describe a LOADED result (capped sample, empty
-          period/filter). They render only once stats arrive — never during
-          the skeleton — so they slot in at their natural position without
-          masking. */}
-      {stats?.capped ? (
-        <Alert
-          variant="warning"
-          icon={AlertTriangle}
-          title={t('feedback.cappedNotice.title')}
-          description={t('feedback.cappedNotice.description')}
-        />
-      ) : null}
+  const sentimentSeries: ChartSeries[] = [
+    {
+      key: 'positive',
+      label: t('feedback.cards.helpful'),
+      color: CHART_COLORS.success,
+      stackId: 'sentiment',
+    },
+    {
+      key: 'negative',
+      label: t('feedback.cards.notHelpful'),
+      color: CHART_COLORS.failure,
+      stackId: 'sentiment',
+    },
+  ];
+  const showSentimentTrend = loading || (stats?.series?.length ?? 0) > 0;
+
+  const filterChips: MetricsFilterChip[] = [];
+  if (agentSlug)
+    filterChips.push({
+      key: 'agent',
+      label: t('feedback.filterChips.agent', { value: agentSlug }),
+      onClear: () => onSelectAgent(null),
+    });
+  if (model)
+    filterChips.push({
+      key: 'model',
+      label: t('feedback.filterChips.model', { value: model }),
+      onClear: () => onSelectModel(null, null),
+    });
+  else if (provider)
+    filterChips.push({
+      key: 'provider',
+      label: t('feedback.filterChips.provider', { value: provider }),
+      onClear: () => onSelectModel(null, null),
+    });
 
-      {isPeriodEmpty ? (
-        <Alert
-          title={t('feedback.periodEmpty.title')}
-          description={
-            <span>
-              {t('feedback.periodEmpty.description')}{' '}
-              <Button
-                variant="link"
-                size="sm"
-                onClick={() => onChangePeriod('all')}
-              >
-                {t('feedback.periodEmpty.expand')}
-              </Button>
-            </span>
-          }
+  return (
+    <MetricsLayout
+      as="h3"
+      title={t('feedback.title')}
+      description={t('feedback.description')}
+      toolbar={
+        <MetricSelect
+          aria-label={t('feedback.period.label')}
+          options={periodOptions}
+          value={period}
+          onValueChange={onChangePeriod}
         />
-      ) : null}
-
-      {isFilteredZero ? (
-        <Alert
-          title={t('feedback.filterEmpty.title')}
-          description={
-            <span>
-              {t('feedback.filterEmpty.description')}{' '}
-              <Button variant="link" size="sm" onClick={onClearFilters}>
-                {t('feedback.filterEmpty.clear')}
-              </Button>
-            </span>
-          }
+      }
+      filters={
+        <MetricsFilterChips
+          chips={filterChips}
+          onClearAll={onClearFilters}
+          clearAllLabel={t('feedback.filterChips.clear')}
         />
-      ) : null}
-
+      }
+      notice={
+        // These notices describe a LOADED result (capped sample, empty
+        // period/filter) — they render only once stats arrive.
+        <>
+          {stats?.capped ? (
+            <Alert
+              variant="warning"
+              icon={AlertTriangle}
+              title={t('feedback.cappedNotice.title')}
+              description={t('feedback.cappedNotice.description')}
+            />
+          ) : null}
+          {isPeriodEmpty ? (
+            <Alert
+              title={t('feedback.periodEmpty.title')}
+              description={
+                <span>
+                  {t('feedback.periodEmpty.description')}{' '}
+                  <Button variant="link" onClick={() => onChangePeriod('all')}>
+                    {t('feedback.periodEmpty.expand')}
+                  </Button>
+                </span>
+              }
+            />
+          ) : null}
+          {isFilteredZero ? (
+            <Alert
+              title={t('feedback.filterEmpty.title')}
+              description={
+                <span>
+                  {t('feedback.filterEmpty.description')}{' '}
+                  <Button variant="link" onClick={onClearFilters}>
+                    {t('feedback.filterEmpty.clear')}
+                  </Button>
+                </span>
+              }
+            />
+          ) : null}
+        </>
+      }
+    >
       <FeedbackSummaryCards
         helpful={stats?.message.byRating.positive ?? 0}
         notHelpful={stats?.message.byRating.negative ?? 0}
         capped={stats?.capped ?? false}
+        previous={stats?.previous}
       />
 
       <ArenaSummary
@@ -231,6 +267,22 @@ export function FeedbackMetricsPageView({
         total={stats?.arena.total ?? 0}
       />
 
+      {showSentimentTrend ? (
+        <ChartCard
+          title={t('feedback.sentimentTrend')}
+          loading={loading}
+          bodyClassName="h-52"
+          legend={<ChartLegend items={seriesToLegend(sentimentSeries)} />}
+        >
+          <TrendBarChart
+            data={stats?.series ?? []}
+            series={sentimentSeries}
+            xKey="dateKey"
+            xTickFormatter={(key) => key.slice(5)}
+          />
+        </ChartCard>
+      ) : null}
+
       {showMatchups ? (
         <TopMatchupsFeedbackTable
           rows={stats?.topMatchups ?? []}
@@ -264,7 +316,6 @@ export function FeedbackMetricsPageView({
                 options={kindOptions}
                 value={kind}
                 onValueChange={onChangeKind}
-                size="sm"
                 aria-label={t('feedback.kind.label')}
               />
             </div>
@@ -279,7 +330,7 @@ export function FeedbackMetricsPageView({
           </HStack>
         }
       />
-    </Stack>
+    </MetricsLayout>
   );
 }
 
@@ -372,16 +423,16 @@ export function FeedbackMetricsPage({
   // Only knowable once stats resolve (during load we render the skeleton).
   if (!statsLoading && stats && !stats.hasAnyFeedback) {
     return (
-      <Stack gap={6}>
-        <Header
-          title={t('feedback.title')}
-          description={t('feedback.description')}
-        />
+      <MetricsLayout
+        as="h3"
+        title={t('feedback.title')}
+        description={t('feedback.description')}
+      >
         <Alert
           title={t('feedback.empty.title')}
           description={t('feedback.empty.description')}
         />
-      </Stack>
+      </MetricsLayout>
     );
   }
 
@@ -431,20 +482,3 @@ export function FeedbackMetricsPage({
     </Skeletonize>
   );
 }
-
-function Header({
-  title,
-  description,
-}: {
-  title: string;
-  description: string;
-}) {
-  return (
-    <div className="flex flex-col gap-1">
-      <Text as="h3" className="text-foreground text-base font-semibold">
-        {title}
-      </Text>
-      <Text variant="caption">{description}</Text>
-    </div>
-  );
-}
diff --git a/services/platform/app/features/analytics/feedback/feedback-page.test.tsx b/services/platform/app/features/analytics/feedback/feedback-page.test.tsx
index 6392549f14..f95c152600 100644
--- a/services/platform/app/features/analytics/feedback/feedback-page.test.tsx
+++ b/services/platform/app/features/analytics/feedback/feedback-page.test.tsx
@@ -107,7 +107,7 @@ describe('FeedbackMetricsPage', () => {
     render(<FeedbackMetricsPage {...baseProps} />);
 
     expect(
-      screen.getByRole('heading', { name: 'Feedback Analytics' }),
+      screen.getByRole('heading', { name: 'Feedback Metrics' }),
     ).toBeInTheDocument();
   });
 
@@ -121,7 +121,7 @@ describe('FeedbackMetricsPage', () => {
     render(<FeedbackMetricsPage {...baseProps} />);
 
     expect(
-      screen.getByRole('heading', { name: 'Feedback Analytics' }),
+      screen.getByRole('heading', { name: 'Feedback Metrics' }),
     ).toBeInTheDocument();
   });
 });
diff --git a/services/platform/app/features/analytics/feedback/feedback-summary-cards.tsx b/services/platform/app/features/analytics/feedback/feedback-summary-cards.tsx
index 2b5376126a..020a4f9e97 100644
--- a/services/platform/app/features/analytics/feedback/feedback-summary-cards.tsx
+++ b/services/platform/app/features/analytics/feedback/feedback-summary-cards.tsx
@@ -1,9 +1,10 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { useSkeleton } from '@tale/ui/skeleton-context';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
 import { Text } from '@tale/ui/text';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
 import { useTranslation } from 'react-i18next';
 
 import { useT } from '@/lib/i18n/client';
@@ -15,6 +16,8 @@ interface FeedbackSummaryCardsProps {
   notHelpful: number;
   /** When true, sentiment cell is greyed out — partial-sample percentages mislead. */
   capped: boolean;
+  /** Prior-window sentiment counts (from the query's `previous`), for deltas. */
+  previous?: { positive: number; negative: number; total: number };
 }
 
 function formatPercent(
@@ -38,6 +41,7 @@ export function FeedbackSummaryCards({
   helpful,
   notHelpful,
   capped,
+  previous,
 }: FeedbackSummaryCardsProps) {
   const { t } = useT('analytics');
   const { i18n } = useTranslation();
@@ -47,17 +51,27 @@ export function FeedbackSummaryCards({
   const negativePct = total === 0 ? 0 : notHelpful / total;
   const sentimentLabel = formatPercent(helpful, total, i18n.language);
 
+  // Sentiment delta compares the positive share across windows (higher = good).
+  const prevTotal = previous ? previous.positive + previous.negative : 0;
+  const prevPositivePct =
+    previous && prevTotal > 0
+      ? (previous.positive / prevTotal) * 100
+      : undefined;
+
   return (
-    <div className="border-border grid grid-cols-2 overflow-hidden rounded-lg border md:grid-cols-4">
-      <div className="border-border col-span-2 flex flex-col gap-3 border-b px-5 py-6 md:border-r md:border-b-0">
-        <Text className="text-muted-foreground text-sm">
+    <StatCardGrid className="overflow-hidden">
+      {/* Bespoke sentiment cell: a percentage with an inline denominator and a
+          positive/negative bar — too specialized for the plain StatCard, so it
+          rides along as a `col-span-2` child of the same grid. */}
+      <div className="col-span-2 flex flex-col gap-3 p-5">
+        <Text className="text-fg-muted text-sm">
           {t('feedback.cards.sentiment')}
         </Text>
         <div className="flex items-baseline gap-2">
           <Text
             className={cn(
-              'text-foreground font-mono text-3xl font-semibold',
-              capped && 'text-muted-foreground opacity-60',
+              'text-fg-base font-mono text-3xl font-semibold',
+              capped && 'text-fg-muted opacity-60',
             )}
             aria-label={
               capped
@@ -87,6 +101,12 @@ export function FeedbackSummaryCards({
               })}
             </Text>
           ) : null}
+          {!loading && !capped && total > 0 && prevPositivePct !== undefined ? (
+            <TrendIndicator
+              value={positivePct * 100}
+              previous={prevPositivePct}
+            />
+          ) : null}
         </div>
         {/* The sentiment bar only paints with data — reserve its exact 0.5rem
             height while loading so the sentiment cell doesn't grow on load. */}
@@ -96,7 +116,7 @@ export function FeedbackSummaryCards({
           </SkeletonBox>
         ) : total > 0 ? (
           <div
-            className="bg-muted relative h-2 w-full overflow-hidden rounded-full"
+            className="bg-bg-muted relative h-2 w-full overflow-hidden rounded-full"
             role="img"
             aria-hidden="true"
           >
@@ -114,48 +134,28 @@ export function FeedbackSummaryCards({
           </div>
         ) : null}
       </div>
-      <Cell
+      <StatCard
         label={t('feedback.cards.helpful')}
         value={formatNumber(helpful, i18n.language)}
-        accent="positive"
-      />
-      <Cell
+        valueClassName="text-emerald-600 dark:text-emerald-400"
+      >
+        <div className="mt-0.5">
+          <TrendIndicator value={helpful} previous={previous?.positive} />
+        </div>
+      </StatCard>
+      <StatCard
         label={t('feedback.cards.notHelpful')}
         value={formatNumber(notHelpful, i18n.language)}
-        accent="negative"
-      />
-    </div>
-  );
-}
-
-function Cell({
-  label,
-  value,
-  accent,
-}: {
-  label: string;
-  value: string;
-  accent: 'positive' | 'negative';
-}) {
-  const loading = useSkeleton();
-  return (
-    <Stack className="border-border border-b px-5 py-6 md:border-r md:border-b-0 last:md:border-r-0">
-      <Text className="text-muted-foreground text-sm">{label}</Text>
-      <Text
-        className={cn(
-          'text-foreground font-mono text-2xl font-semibold',
-          accent === 'positive' && 'text-emerald-600 dark:text-emerald-400',
-          accent === 'negative' && 'text-rose-600 dark:text-rose-400',
-        )}
+        valueClassName="text-rose-600 dark:text-rose-400"
       >
-        {loading ? (
-          <SkeletonBox>
-            <span className="my-0.5 inline-block h-7 w-16" />
-          </SkeletonBox>
-        ) : (
-          value
-        )}
-      </Text>
-    </Stack>
+        <div className="mt-0.5">
+          <TrendIndicator
+            value={notHelpful}
+            previous={previous?.negative}
+            inverted
+          />
+        </div>
+      </StatCard>
+    </StatCardGrid>
   );
 }
diff --git a/services/platform/app/features/analytics/feedback/filter-chips.tsx b/services/platform/app/features/analytics/feedback/filter-chips.tsx
deleted file mode 100644
index 57b90f05fd..0000000000
--- a/services/platform/app/features/analytics/feedback/filter-chips.tsx
+++ /dev/null
@@ -1,70 +0,0 @@
-'use client';
-
-import { Badge } from '@tale/ui/badge';
-import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
-import { X } from 'lucide-react';
-
-import { useT } from '@/lib/i18n/client';
-
-interface FilterChipsProps {
-  agentSlug?: string;
-  model?: string;
-  provider?: string;
-  onClearAgent: () => void;
-  onClearModel: () => void;
-  onClearAll: () => void;
-}
-
-export function FilterChips({
-  agentSlug,
-  model,
-  provider,
-  onClearAgent,
-  onClearModel,
-  onClearAll,
-}: FilterChipsProps) {
-  const { t } = useT('analytics');
-
-  if (!agentSlug && !model && !provider) {
-    return null;
-  }
-
-  return (
-    <HStack gap={2} className="flex-wrap items-center">
-      {agentSlug ? (
-        <Badge
-          variant="outline"
-          className="cursor-pointer"
-          onClick={onClearAgent}
-        >
-          {t('feedback.filterChips.agent', { value: agentSlug })}
-          <X className="ml-1 size-3" />
-        </Badge>
-      ) : null}
-      {model ? (
-        <Badge
-          variant="outline"
-          className="cursor-pointer"
-          onClick={onClearModel}
-        >
-          {t('feedback.filterChips.model', { value: model })}
-          <X className="ml-1 size-3" />
-        </Badge>
-      ) : null}
-      {provider && !model ? (
-        <Badge
-          variant="outline"
-          className="cursor-pointer"
-          onClick={onClearModel}
-        >
-          {t('feedback.filterChips.provider', { value: provider })}
-          <X className="ml-1 size-3" />
-        </Badge>
-      ) : null}
-      <Button variant="ghost" size="sm" onClick={onClearAll}>
-        {t('feedback.filterChips.clear')}
-      </Button>
-    </HStack>
-  );
-}
diff --git a/services/platform/app/features/analytics/usage/usage-metrics-page.test.tsx b/services/platform/app/features/analytics/usage/usage-metrics-page.test.tsx
index 4869605c9b..98bc9c3dae 100644
--- a/services/platform/app/features/analytics/usage/usage-metrics-page.test.tsx
+++ b/services/platform/app/features/analytics/usage/usage-metrics-page.test.tsx
@@ -63,7 +63,7 @@ describe('UsageMetricsPage', () => {
 
     // Page title (the E2E asserted this heading by name).
     expect(
-      screen.getByRole('heading', { name: 'Usage Analytics' }),
+      screen.getByRole('heading', { name: 'Usage Metrics' }),
     ).toBeInTheDocument();
 
     // The period Select control, addressed by its accessible label exactly as
diff --git a/services/platform/app/features/analytics/usage/usage-metrics-page.tsx b/services/platform/app/features/analytics/usage/usage-metrics-page.tsx
index 473ff54b73..269eb14ef7 100644
--- a/services/platform/app/features/analytics/usage/usage-metrics-page.tsx
+++ b/services/platform/app/features/analytics/usage/usage-metrics-page.tsx
@@ -1,15 +1,17 @@
 'use client';
 
-import { Badge } from '@tale/ui/badge';
-import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { Alert } from '@tale/ui/alert';
 import { Skeletonize } from '@tale/ui/skeleton-context';
-import { Text } from '@tale/ui/text';
 import type { FunctionReturnType } from 'convex/server';
-import { X } from 'lucide-react';
+import { AlertTriangle } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
-import { Select } from '@/app/components/ui/forms/select';
+import { MetricSelect } from '@/app/components/metrics/metric-select';
+import {
+  MetricsFilterChips,
+  type MetricsFilterChip,
+} from '@/app/components/metrics/metrics-filter-chips';
+import { MetricsLayout } from '@/app/components/metrics/metrics-layout';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { api } from '@/convex/_generated/api';
 import { useT } from '@/lib/i18n/client';
@@ -114,98 +116,76 @@ export function UsageMetricsPageView({
   const topVoiceModels = data?.topVoiceModels ?? [];
   const users = data?.users ?? [];
 
-  const hasFilters =
-    agentSlug !== undefined || model !== undefined || provider !== undefined;
+  const filterChips: MetricsFilterChip[] = [];
+  if (agentSlug !== undefined)
+    filterChips.push({
+      key: 'agent',
+      label: t('usage.filterChips.agent', { value: agentSlug }),
+      onClear: () => onSelectAgent(undefined),
+    });
+  if (model !== undefined)
+    filterChips.push({
+      key: 'model',
+      label: t('usage.filterChips.model', { value: model }),
+      onClear: () => onSelectModel(undefined),
+    });
+  if (provider !== undefined)
+    filterChips.push({
+      key: 'provider',
+      label: t('usage.filterChips.provider', { value: provider }),
+      onClear: () => onSelectProvider(undefined),
+    });
 
   return (
-    <Stack gap={6}>
-      <div className="flex flex-col gap-3 md:flex-row md:items-start md:justify-between">
-        <div className="flex flex-col gap-1">
-          <Text as="h3" className="text-foreground text-base font-semibold">
-            {t('usage.title')}
-          </Text>
-          <Text variant="caption">{t('usage.description')}</Text>
-        </div>
-        <HStack gap={2} className="flex-wrap">
-          <div className="w-36">
-            <Select
-              options={periodOptions}
-              value={String(periodDays)}
-              onValueChange={onPeriod}
-              size="sm"
-              aria-label={t('usage.period.label')}
-            />
-          </div>
-          <div className="w-36">
-            <Select
-              options={granularityOptions}
-              value={granularity}
-              onValueChange={onGranularity}
-              size="sm"
-              aria-label={t('usage.granularity.label')}
-            />
-          </div>
-          <div className="w-36">
-            <Select
-              options={metricOptions}
-              value={metric}
-              onValueChange={onMetric}
-              size="sm"
-              aria-label={t('usage.metric.label')}
-            />
-          </div>
-        </HStack>
-      </div>
-
-      {hasFilters ? (
-        <HStack gap={2} className="flex-wrap items-center">
-          {agentSlug ? (
-            <Badge
-              variant="outline"
-              className="cursor-pointer"
-              onClick={() => onSelectAgent(undefined)}
-            >
-              {t('usage.filterChips.agent', { value: agentSlug })}
-              <X className="ml-1 size-3" />
-            </Badge>
-          ) : null}
-          {model ? (
-            <Badge
-              variant="outline"
-              className="cursor-pointer"
-              onClick={() => onSelectModel(undefined)}
-            >
-              {t('usage.filterChips.model', { value: model })}
-              <X className="ml-1 size-3" />
-            </Badge>
-          ) : null}
-          {provider ? (
-            <Badge
-              variant="outline"
-              className="cursor-pointer"
-              onClick={() => onSelectProvider(undefined)}
-            >
-              {t('usage.filterChips.provider', { value: provider })}
-              <X className="ml-1 size-3" />
-            </Badge>
-          ) : null}
-          <Button variant="ghost" size="sm" onClick={onClearAll}>
-            {t('usage.filterChips.clear')}
-          </Button>
-        </HStack>
-      ) : null}
-
-      {summary?.capped ? (
-        <div className="border-border bg-muted/40 rounded-md border px-3 py-2 text-xs">
-          {t('usage.cappedNotice')}
-        </div>
-      ) : null}
-
+    <MetricsLayout
+      as="h3"
+      title={t('usage.title')}
+      description={t('usage.description')}
+      toolbar={
+        <>
+          <MetricSelect
+            aria-label={t('usage.period.label')}
+            options={periodOptions}
+            value={String(periodDays)}
+            onValueChange={onPeriod}
+          />
+          <MetricSelect
+            aria-label={t('usage.granularity.label')}
+            options={granularityOptions}
+            value={granularity}
+            onValueChange={onGranularity}
+          />
+          <MetricSelect
+            aria-label={t('usage.metric.label')}
+            options={metricOptions}
+            value={metric}
+            onValueChange={onMetric}
+          />
+        </>
+      }
+      filters={
+        <MetricsFilterChips
+          chips={filterChips}
+          onClearAll={onClearAll}
+          clearAllLabel={t('usage.filterChips.clear')}
+        />
+      }
+      notice={
+        summary?.capped ? (
+          <Alert
+            variant="warning"
+            icon={AlertTriangle}
+            title={t('usage.cappedNotice')}
+          />
+        ) : undefined
+      }
+    >
       <UsageSummaryCards
         totalRequests={summary?.totalRequests ?? 0}
         totalTokens={summary?.totalTokens ?? 0}
         totalCostCents={summary?.totalCostCents ?? 0}
         activeUsers={summary?.activeUsers ?? 0}
+        previous={data?.previousSummary}
       />
 
       <UsageTrendChart
@@ -234,7 +214,7 @@ export function UsageMetricsPageView({
       />
 
       <UsersTable rows={users} isLoading={isLoading} />
-    </Stack>
+    </MetricsLayout>
   );
 }
 
diff --git a/services/platform/app/features/analytics/usage/usage-summary-cards.tsx b/services/platform/app/features/analytics/usage/usage-summary-cards.tsx
index 1fc07579f2..d9230b4ee2 100644
--- a/services/platform/app/features/analytics/usage/usage-summary-cards.tsx
+++ b/services/platform/app/features/analytics/usage/usage-summary-cards.tsx
@@ -1,63 +1,27 @@
 'use client';
 
-import { SkeletonBox } from '@tale/ui/skeleton';
-import { useSkeleton } from '@tale/ui/skeleton-context';
-import { Text } from '@tale/ui/text';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
 import { Info } from 'lucide-react';
 
 import { Tooltip } from '@/app/components/ui/overlays/tooltip';
 import { useT } from '@/lib/i18n/client';
 import { formatCostCents, formatNumber } from '@/lib/utils/format/number';
 
-interface UsageSummaryCardsProps {
+/** Prior equal-length window totals (from the query's `previousSummary`). */
+interface PreviousSummary {
   totalRequests: number;
   totalTokens: number;
   totalCostCents: number;
   activeUsers: number;
 }
 
-interface StatCellProps {
-  label: string;
-  value: string;
-  tooltip?: string;
-}
-
-function StatCell({ label, value, tooltip }: StatCellProps) {
-  const loading = useSkeleton();
-  const labelNode = (
-    <Text className="text-muted-foreground text-sm">
-      {label}
-      {tooltip ? (
-        <Info className="ml-1 inline-block size-3 align-text-bottom" />
-      ) : null}
-    </Text>
-  );
-
-  return (
-    <div className="flex flex-1 flex-col gap-1 p-5">
-      {tooltip ? (
-        <Tooltip content={tooltip}>
-          <button type="button" className="text-left">
-            {labelNode}
-          </button>
-        </Tooltip>
-      ) : (
-        labelNode
-      )}
-      {/* The metric value arrives async — mask it to its natural line box
-          (font-mono text-2xl) so the card height is identical loading vs
-          loaded and the number doesn't flash from a placeholder 0. */}
-      <Text className="text-foreground font-mono text-2xl font-semibold">
-        {loading ? (
-          <SkeletonBox>
-            <span className="my-0.5 inline-block h-7 w-20" />
-          </SkeletonBox>
-        ) : (
-          value
-        )}
-      </Text>
-    </div>
-  );
+interface UsageSummaryCardsProps {
+  totalRequests: number;
+  totalTokens: number;
+  totalCostCents: number;
+  activeUsers: number;
+  previous?: PreviousSummary;
 }
 
 export function UsageSummaryCards({
@@ -65,28 +29,72 @@ export function UsageSummaryCards({
   totalTokens,
   totalCostCents,
   activeUsers,
+  previous,
 }: UsageSummaryCardsProps) {
   const { t } = useT('analytics');
 
   return (
-    <div className="border-border divide-border grid grid-cols-2 divide-y rounded-lg border md:grid-cols-4 md:divide-x md:divide-y-0">
-      <StatCell
+    <StatCardGrid>
+      <StatCard
         label={t('usage.cards.totalRequests')}
         value={formatNumber(totalRequests)}
-      />
-      <StatCell
+        loadingWidth="w-20"
+      >
+        <div className="mt-0.5">
+          <TrendIndicator
+            value={totalRequests}
+            previous={previous?.totalRequests}
+          />
+        </div>
+      </StatCard>
+      <StatCard
         label={t('usage.cards.totalTokens')}
         value={formatNumber(totalTokens)}
-      />
-      <StatCell
+        loadingWidth="w-20"
+      >
+        <div className="mt-0.5">
+          <TrendIndicator
+            value={totalTokens}
+            previous={previous?.totalTokens}
+          />
+        </div>
+      </StatCard>
+      <StatCard
         label={t('usage.cards.totalCost')}
         value={formatCostCents(totalCostCents)}
-      />
-      <StatCell
+        loadingWidth="w-20"
+      >
+        <div className="mt-0.5">
+          <TrendIndicator
+            value={totalCostCents}
+            previous={previous?.totalCostCents}
+            inverted
+          />
+        </div>
+      </StatCard>
+      <StatCard
         label={t('usage.cards.activeUsers')}
         value={formatNumber(activeUsers)}
-        tooltip={t('usage.activeUsersTooltip')}
-      />
-    </div>
+        loadingWidth="w-20"
+        tooltip={
+          <Tooltip content={t('usage.activeUsersTooltip')}>
+            <button
+              type="button"
+              className="align-text-bottom"
+              aria-label={t('usage.activeUsersTooltip')}
+            >
+              <Info className="ml-1 inline-block size-3" />
+            </button>
+          </Tooltip>
+        }
+      >
+        <div className="mt-0.5">
+          <TrendIndicator
+            value={activeUsers}
+            previous={previous?.activeUsers}
+          />
+        </div>
+      </StatCard>
+    </StatCardGrid>
   );
 }
diff --git a/services/platform/app/features/analytics/usage/usage-trend-chart.tsx b/services/platform/app/features/analytics/usage/usage-trend-chart.tsx
index 2ae7f24a13..c701c1f660 100644
--- a/services/platform/app/features/analytics/usage/usage-trend-chart.tsx
+++ b/services/platform/app/features/analytics/usage/usage-trend-chart.tsx
@@ -1,34 +1,31 @@
 'use client';
 
-import { SkeletonBox } from '@tale/ui/skeleton';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
 import { useSkeleton } from '@tale/ui/skeleton-context';
-import { Text } from '@tale/ui/text';
-import { useMemo } from 'react';
-import {
-  Bar,
-  BarChart,
-  CartesianGrid,
-  Legend,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from 'recharts';
 
+import {
+  seriesToLegend,
+  TrendBarChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
 import { useT } from '@/lib/i18n/client';
 import { formatCostCents, formatNumber } from '@/lib/utils/format/number';
 
 export type UsageMetric = 'requests' | 'tokens' | 'cost';
 export type UsageGranularity = 'daily' | 'weekly' | 'monthly';
 
-export interface UsageSeriesPoint {
+// A type alias (not an interface) so it carries an implicit index signature and
+// is assignable to the charts' `ChartRow` row type.
+export type UsageSeriesPoint = {
   periodKey: string;
   requests: number;
   inputTokens: number;
   outputTokens: number;
   tokens: number;
   costCents: number;
-}
+};
 
 interface UsageTrendChartProps {
   series: UsageSeriesPoint[];
@@ -37,14 +34,8 @@ interface UsageTrendChartProps {
 }
 
 function shortLabel(periodKey: string, granularity: UsageGranularity): string {
-  if (granularity === 'monthly') {
-    return periodKey; // YYYY-MM
-  }
-  if (granularity === 'weekly') {
-    return periodKey.slice(5); // "Www"
-  }
-  // daily YYYY-MM-DD → MM-DD
-  return periodKey.slice(5);
+  if (granularity === 'monthly') return periodKey; // YYYY-MM
+  return periodKey.slice(5); // daily YYYY-MM-DD → MM-DD, weekly → "Www"
 }
 
 export function UsageTrendChart({
@@ -55,28 +46,37 @@ export function UsageTrendChart({
   const { t } = useT('analytics');
   const loading = useSkeleton();
 
-  const data = useMemo(
-    () =>
-      series.map((p) => ({
-        ...p,
-        label: shortLabel(p.periodKey, granularity),
-      })),
-    [series, granularity],
-  );
-
-  const ariaLabel = t('usage.chart.ariaLabel', {
-    metric: t(`usage.metric.${metric}`),
-  });
-
-  const formatTooltipValue = (
-    value: number | undefined,
-    name: string | undefined,
-  ): [string, string] => {
-    const label = name ?? '';
-    if (value === undefined) return ['', label];
-    if (metric === 'cost') return [formatCostCents(value), label];
-    return [formatNumber(value), label];
-  };
+  const chartSeries: ChartSeries[] =
+    metric === 'tokens'
+      ? [
+          {
+            key: 'inputTokens',
+            label: t('usage.chart.inputTokens'),
+            color: CHART_COLORS.primary,
+            stackId: 'tokens',
+          },
+          {
+            key: 'outputTokens',
+            label: t('usage.chart.outputTokens'),
+            color: CHART_COLORS.success,
+            stackId: 'tokens',
+          },
+        ]
+      : metric === 'requests'
+        ? [
+            {
+              key: 'requests',
+              label: t('usage.metric.requests'),
+              color: CHART_COLORS.primary,
+            },
+          ]
+        : [
+            {
+              key: 'costCents',
+              label: t('usage.metric.cost'),
+              color: CHART_COLORS.warning,
+            },
+          ];
 
   const formatYTick = (value: number): string => {
     if (metric === 'cost') return formatCostCents(value);
@@ -86,106 +86,24 @@ export function UsageTrendChart({
   };
 
   return (
-    <div
-      className="border-border flex flex-col gap-4 rounded-lg border p-5"
-      aria-label={ariaLabel}
+    <ChartCard
+      title={t(`usage.metric.${metric}`)}
+      loading={loading}
+      bodyClassName="h-72"
+      legend={
+        metric === 'tokens' ? (
+          <ChartLegend items={seriesToLegend(chartSeries)} />
+        ) : undefined
+      }
     >
-      <Text as="h3" className="text-foreground text-base font-semibold">
-        {t(`usage.metric.${metric}`)}
-      </Text>
-      {/* Reserve the exact plot height (`h-72`) in both states. While the
-          series loads, mask the plot so axes/bars don't flash in once data
-          arrives — the bordered card + title stay put, so no shift. */}
-      <div className="h-72 w-full">
-        {loading ? (
-          <SkeletonBox fullWidth>
-            <div className="h-72 w-full" />
-          </SkeletonBox>
-        ) : (
-          <ResponsiveContainer width="100%" height="100%">
-            <BarChart
-              data={data}
-              margin={{ top: 8, right: 8, bottom: 0, left: -8 }}
-            >
-              <CartesianGrid
-                strokeDasharray="3 3"
-                className="stroke-border"
-                vertical={false}
-              />
-              <XAxis
-                dataKey="label"
-                tick={{ fontSize: 11 }}
-                stroke="currentColor"
-                className="text-muted-foreground"
-              />
-              <YAxis
-                allowDecimals={false}
-                tick={{ fontSize: 11 }}
-                tickFormatter={formatYTick}
-                stroke="currentColor"
-                className="text-muted-foreground"
-              />
-              <Tooltip
-                contentStyle={{
-                  fontSize: 12,
-                  borderRadius: 6,
-                  border: '1px solid var(--border)',
-                  background: 'var(--popover)',
-                }}
-                labelFormatter={(_value, payload) => {
-                  const first = payload?.[0];
-                  if (
-                    first &&
-                    typeof first === 'object' &&
-                    'payload' in first &&
-                    first.payload &&
-                    typeof first.payload === 'object' &&
-                    'periodKey' in first.payload &&
-                    typeof first.payload.periodKey === 'string'
-                  ) {
-                    return first.payload.periodKey;
-                  }
-                  return '';
-                }}
-                formatter={formatTooltipValue}
-              />
-              {metric === 'tokens' ? (
-                <>
-                  <Legend wrapperStyle={{ fontSize: 12 }} />
-                  <Bar
-                    dataKey="inputTokens"
-                    stackId="tokens"
-                    fill="var(--color-chart-primary, #3b82f6)"
-                    name={t('usage.chart.inputTokens')}
-                    radius={[0, 0, 0, 0]}
-                  />
-                  <Bar
-                    dataKey="outputTokens"
-                    stackId="tokens"
-                    fill="var(--color-chart-success, #16a34a)"
-                    name={t('usage.chart.outputTokens')}
-                    radius={[4, 4, 0, 0]}
-                  />
-                </>
-              ) : metric === 'requests' ? (
-                <Bar
-                  dataKey="requests"
-                  fill="var(--color-chart-primary, #3b82f6)"
-                  name={t('usage.metric.requests')}
-                  radius={[4, 4, 0, 0]}
-                />
-              ) : (
-                <Bar
-                  dataKey="costCents"
-                  fill="var(--color-chart-warning, #f59e0b)"
-                  name={t('usage.metric.cost')}
-                  radius={[4, 4, 0, 0]}
-                />
-              )}
-            </BarChart>
-          </ResponsiveContainer>
-        )}
-      </div>
-    </div>
+      <TrendBarChart
+        data={series}
+        series={chartSeries}
+        xKey="periodKey"
+        xTickFormatter={(key) => shortLabel(key, granularity)}
+        yTickFormatter={formatYTick}
+        valueFormatter={metric === 'cost' ? formatCostCents : formatNumber}
+      />
+    </ChartCard>
   );
 }
diff --git a/services/platform/app/features/apps/components/app-page.tsx b/services/platform/app/features/apps/components/app-page.tsx
index 0eda551210..b553ddfc96 100644
--- a/services/platform/app/features/apps/components/app-page.tsx
+++ b/services/platform/app/features/apps/components/app-page.tsx
@@ -20,7 +20,7 @@ import { Button } from '@tale/ui/button';
 import { Card } from '@tale/ui/card';
 import { EmptyState } from '@tale/ui/empty-state';
 import { useLocale } from '@tale/ui/i18n/locale-provider';
-import { HStack, VStack } from '@tale/ui/layout';
+import { Grid, HStack, VStack } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { Tabs } from '@tale/ui/tabs';
 import { Text } from '@tale/ui/text';
@@ -102,11 +102,7 @@ function ReadinessChecklist({
             <Text variant="muted" className="text-sm">
               {t('readiness.connect', { integration: slug })}
             </Text>
-            <Button
-              size="sm"
-              variant="secondary"
-              onClick={() => onConnect(slug)}
-            >
+            <Button variant="secondary" onClick={() => onConnect(slug)}>
               {t('readiness.connectButton')}
             </Button>
           </HStack>
@@ -230,11 +226,11 @@ function ReadinessSection({
 function TabContent({ tab }: { tab: AppTabDoc }) {
   if (tab.columns && tab.columns.length > 0) {
     return (
-      <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-2">
+      <Grid lg={2} className="items-start">
         {tab.columns.map((col, i) => (
           <AppView key={i} data={col} />
         ))}
-      </div>
+      </Grid>
     );
   }
   return <AppView data={tab.data} />;
diff --git a/services/platform/app/features/apps/components/apps-grid.tsx b/services/platform/app/features/apps/components/apps-grid.tsx
index 2cebf18fe4..959219f878 100644
--- a/services/platform/app/features/apps/components/apps-grid.tsx
+++ b/services/platform/app/features/apps/components/apps-grid.tsx
@@ -6,9 +6,9 @@
  * whole lifecycle starts here. */
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { Card } from '@tale/ui/card';
+import { Card, CardGrid } from '@tale/ui/card';
 import { EmptyState } from '@tale/ui/empty-state';
-import { Grid, HStack, VStack } from '@tale/ui/layout';
+import { HStack, Row, VStack } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { Text } from '@tale/ui/text';
 import { Link } from '@tanstack/react-router';
@@ -59,7 +59,7 @@ export function AppsGrid({ organizationId }: { organizationId: string }) {
   }
 
   return (
-    <Grid className="grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+    <CardGrid>
       {apps.map((app) => {
         const state = bySlug.get(app.slug);
         // Every card opens the org-level app page. For a project-scoped app that
@@ -73,13 +73,17 @@ export function AppsGrid({ organizationId }: { organizationId: string }) {
         return (
           <div key={app.slug} className="relative h-full">
             <Link {...cardLink} aria-label={app.name} className="block h-full">
-              <Card className="hover:border-primary/50 h-full transition-colors">
+              <Card interactive className="h-full">
                 <VStack gap={3}>
                   <HStack gap={3} className="items-start justify-between">
                     <HStack gap={3} className="min-w-0 items-start">
-                      <div className="bg-muted text-muted-foreground flex size-9 shrink-0 items-center justify-center rounded-md">
+                      <Row
+                        gap={0}
+                        justify="center"
+                        className="bg-muted text-muted-foreground size-9 shrink-0 rounded-md"
+                      >
                         <LayoutGrid className="size-5" />
-                      </div>
+                      </Row>
                       <VStack gap={1} className="min-w-0">
                         <Text as="span" className="font-semibold" truncate>
                           {app.name}
@@ -111,7 +115,6 @@ export function AppsGrid({ organizationId }: { organizationId: string }) {
             ) : (
               <div className="absolute bottom-3 left-3 z-10">
                 <Button
-                  size="sm"
                   disabled={isPending}
                   onClick={() =>
                     app.scope === 'project' ||
@@ -140,6 +143,6 @@ export function AppsGrid({ organizationId }: { organizationId: string }) {
           requiredIntegrations={wizardApp.requiredIntegrations}
         />
       )}
-    </Grid>
+    </CardGrid>
   );
 }
diff --git a/services/platform/app/features/apps/registry/connected/agent-env-dialog.tsx b/services/platform/app/features/apps/registry/connected/agent-env-dialog.tsx
index 3bfe58ceed..3273472a5c 100644
--- a/services/platform/app/features/apps/registry/connected/agent-env-dialog.tsx
+++ b/services/platform/app/features/apps/registry/connected/agent-env-dialog.tsx
@@ -244,7 +244,6 @@ function EnvEditor({
             </HStack>
           ))}
           <Button
-            size="sm"
             variant="ghost"
             disabled={saving}
             className="self-start"
diff --git a/services/platform/app/features/apps/registry/connected/agent-list.tsx b/services/platform/app/features/apps/registry/connected/agent-list.tsx
index 20d0e55c28..bb872f4e08 100644
--- a/services/platform/app/features/apps/registry/connected/agent-list.tsx
+++ b/services/platform/app/features/apps/registry/connected/agent-list.tsx
@@ -228,7 +228,6 @@ export function AgentList({ title, agents, roles }: AgentListProps) {
                       </HStack>
                       <HStack gap={2}>
                         <Button
-                          size="sm"
                           variant="secondary"
                           onClick={() =>
                             setEditing({
@@ -240,7 +239,6 @@ export function AgentList({ title, agents, roles }: AgentListProps) {
                           {t('agents.editInstructions')}
                         </Button>
                         <Button
-                          size="sm"
                           variant="ghost"
                           onClick={() =>
                             setEditingEnv({
diff --git a/services/platform/app/features/apps/registry/connected/data-table.tsx b/services/platform/app/features/apps/registry/connected/data-table.tsx
index 827ea4af4a..8acdd9fa98 100644
--- a/services/platform/app/features/apps/registry/connected/data-table.tsx
+++ b/services/platform/app/features/apps/registry/connected/data-table.tsx
@@ -10,6 +10,7 @@
  * framing. Pure: it takes already-parsed `rows`.
  */
 import { Badge } from '@tale/ui/badge';
+import { Row } from '@tale/ui/layout';
 import {
   Table,
   TableBody,
@@ -166,11 +167,11 @@ export function DataTable({
                 {acts.length > 0 && (
                   // Stop row-click expansion when interacting with actions.
                   <TableCell onClick={(e) => e.stopPropagation()}>
-                    <div className="flex flex-wrap gap-2">
+                    <Row gap={2} align="stretch" wrap>
                       {acts.map((a, ai) => (
                         <BoundButton key={ai} action={a} item={row} />
                       ))}
-                    </div>
+                    </Row>
                   </TableCell>
                 )}
               </TableRow>
diff --git a/services/platform/app/features/apps/registry/connected/external-list.tsx b/services/platform/app/features/apps/registry/connected/external-list.tsx
index 1397c0f8e2..91a2d3d107 100644
--- a/services/platform/app/features/apps/registry/connected/external-list.tsx
+++ b/services/platform/app/features/apps/registry/connected/external-list.tsx
@@ -176,7 +176,6 @@ export function ExternalList({
 
   const refresh = (
     <Button
-      size="sm"
       variant="ghost"
       disabled={query.isFetching}
       onClick={() => query.refetch()}
@@ -216,7 +215,6 @@ export function ExternalList({
           {paginated && (
             <HStack gap={3} className="items-center justify-end">
               <Button
-                size="sm"
                 variant="ghost"
                 disabled={query.isFetching || page <= 1}
                 onClick={() => setPage((p) => Math.max(1, p - 1))}
@@ -227,7 +225,6 @@ export function ExternalList({
                 {t('list.page', { page })}
               </Text>
               <Button
-                size="sm"
                 variant="ghost"
                 disabled={query.isFetching || !hasNext}
                 onClick={() => setPage((p) => p + 1)}
diff --git a/services/platform/app/features/apps/registry/connected/run-list.tsx b/services/platform/app/features/apps/registry/connected/run-list.tsx
index 73224c2d3e..26c2e9f040 100644
--- a/services/platform/app/features/apps/registry/connected/run-list.tsx
+++ b/services/platform/app/features/apps/registry/connected/run-list.tsx
@@ -107,7 +107,6 @@ export function RunList({ title, workflowSlug }: RunListProps) {
                   <TableCell>{fmt(run.startedAt)}</TableCell>
                   <TableCell>
                     <Button
-                      size="sm"
                       variant="secondary"
                       disabled={!id}
                       onClick={() =>
diff --git a/services/platform/app/features/apps/registry/connected/section.tsx b/services/platform/app/features/apps/registry/connected/section.tsx
index 23b7328bf3..b3c37393dc 100644
--- a/services/platform/app/features/apps/registry/connected/section.tsx
+++ b/services/platform/app/features/apps/registry/connected/section.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 /**
  * The card frame every connected block renders inside — a titled section (icon +
  * title + optional description + a right-aligned action slot) over a card
@@ -33,12 +34,16 @@ export function Section({
         className,
       )}
     >
-      <div className="flex items-start justify-between gap-3 p-5 pb-3">
+      <Row gap={3} align="start" justify="between" className="p-5 pb-3">
         <div className="flex min-w-0 items-center gap-2.5">
           {Icon && (
-            <div className="bg-muted text-muted-foreground flex size-8 shrink-0 items-center justify-center rounded-md">
+            <Row
+              gap={0}
+              justify="center"
+              className="bg-muted text-muted-foreground size-8 shrink-0 rounded-md"
+            >
               <Icon className="size-4" />
-            </div>
+            </Row>
           )}
           <div className="min-w-0">
             {title && (
@@ -54,7 +59,7 @@ export function Section({
           </div>
         </div>
         {action && <div className="shrink-0">{action}</div>}
-      </div>
+      </Row>
       <div className="px-5 pb-5">{children}</div>
     </section>
   );
diff --git a/services/platform/app/features/apps/registry/connected/workflow-dag.tsx b/services/platform/app/features/apps/registry/connected/workflow-dag.tsx
index 3e8dc1d633..77aed80c07 100644
--- a/services/platform/app/features/apps/registry/connected/workflow-dag.tsx
+++ b/services/platform/app/features/apps/registry/connected/workflow-dag.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 /**
  * Connected `WorkflowDag` block — the app's workflow display, which **fully
  * reuses the global automations canvas** (`AutomationSteps`), not a bespoke
@@ -168,7 +169,11 @@ export function WorkflowDag({
     // the test / step-config side panel — chat and side panel are mutually
     // exclusive, as in the global editor.
     body = (
-      <div className="relative flex h-[32rem] w-full overflow-hidden rounded-md border">
+      <Row
+        gap={0}
+        align="stretch"
+        className="relative h-[32rem] w-full overflow-hidden rounded-md border"
+      >
         <AutomationSteps
           steps={steps}
           hasActiveTrigger={false}
@@ -193,15 +198,15 @@ export function WorkflowDag({
             stepOptions={stepOptions}
           />
         )}
-      </div>
+      </Row>
     );
   } else {
     // The canvas fills a flex parent; give it a bounded height so it embeds
     // cleanly inside the app page rather than collapsing.
     const canvas = (
-      <div className="flex h-[28rem] w-full">
+      <Row gap={0} align="stretch" className="h-[28rem] w-full">
         <AutomationSteps steps={steps} hasActiveTrigger={false} />
-      </div>
+      </Row>
     );
     body = executionId ? (
       <ExecutionStatusProvider executionId={executionId}>
diff --git a/services/platform/app/features/apps/registry/tale-config.tsx b/services/platform/app/features/apps/registry/tale-config.tsx
index dd1eca2d75..0ba3af65d9 100644
--- a/services/platform/app/features/apps/registry/tale-config.tsx
+++ b/services/platform/app/features/apps/registry/tale-config.tsx
@@ -17,7 +17,13 @@
 import { type Config } from '@measured/puck';
 import { Alert } from '@tale/ui/alert';
 import { Badge } from '@tale/ui/badge';
-import { Card } from '@tale/ui/card';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@tale/ui/card';
 import { Heading } from '@tale/ui/heading';
 import { Text } from '@tale/ui/text';
 
@@ -140,8 +146,16 @@ export const taleConfig: Config<TaleComponents> = {
       },
       defaultProps: { title: '', description: '', body: '' },
       render: ({ title, description, body }) => (
-        <Card title={title} description={description}>
-          {body}
+        <Card>
+          {(title || description) && (
+            <CardHeader className="pb-3">
+              {title ? <CardTitle>{title}</CardTitle> : null}
+              {description ? (
+                <CardDescription>{description}</CardDescription>
+              ) : null}
+            </CardHeader>
+          )}
+          <CardContent>{body}</CardContent>
         </Card>
       ),
     },
diff --git a/services/platform/app/features/auth/components/conditional-access-error.tsx b/services/platform/app/features/auth/components/conditional-access-error.tsx
index aae25e9d82..bdd8ba0691 100644
--- a/services/platform/app/features/auth/components/conditional-access-error.tsx
+++ b/services/platform/app/features/auth/components/conditional-access-error.tsx
@@ -34,7 +34,7 @@ export function ConditionalAccessError({
 
       <Stack gap={2}>
         {isMfaError && (
-          <Button onClick={onRetry} size="lg" fullWidth>
+          <Button onClick={onRetry} fullWidth>
             {t('sso.actions.completeMfa')}
           </Button>
         )}
@@ -46,7 +46,7 @@ export function ConditionalAccessError({
         )}
 
         {!isBlockedError && (
-          <Button onClick={onRetry} variant="secondary" size="lg" fullWidth>
+          <Button onClick={onRetry} variant="secondary" fullWidth>
             {t('sso.actions.tryAgain')}
           </Button>
         )}
diff --git a/services/platform/app/features/auth/components/two-factor-grace-banner.tsx b/services/platform/app/features/auth/components/two-factor-grace-banner.tsx
index 5a201dd9d1..e9475cb2eb 100644
--- a/services/platform/app/features/auth/components/two-factor-grace-banner.tsx
+++ b/services/platform/app/features/auth/components/two-factor-grace-banner.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Link } from '@tanstack/react-router';
 
 import { useTwoFactorStatus } from '@/app/context/account-bootstrap-context';
@@ -38,9 +39,11 @@ export function TwoFactorGraceBanner({
 
   return (
     <div className="px-4 pt-2">
-      <div
+      <Row
         role="alert"
-        className="bg-warning/10 border-warning/30 flex flex-wrap items-center gap-2 rounded-lg border p-3 text-sm"
+        gap={2}
+        wrap
+        className="bg-warning/10 border-warning/30 rounded-lg border p-3 text-sm"
       >
         <span className="grow">
           <span className="font-medium">
@@ -56,7 +59,7 @@ export function TwoFactorGraceBanner({
         >
           {t('grace.setupLink')}
         </Link>
-      </div>
+      </Row>
     </div>
   );
 }
diff --git a/services/platform/app/features/auth/components/two-factor-low-backup-codes-banner.tsx b/services/platform/app/features/auth/components/two-factor-low-backup-codes-banner.tsx
index 13907ca938..d3b10a0861 100644
--- a/services/platform/app/features/auth/components/two-factor-low-backup-codes-banner.tsx
+++ b/services/platform/app/features/auth/components/two-factor-low-backup-codes-banner.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Link } from '@tanstack/react-router';
 
 import { useTwoFactorStatus } from '@/app/context/account-bootstrap-context';
@@ -40,9 +41,11 @@ export function TwoFactorLowBackupCodesBanner({
 
   return (
     <div className="px-4 pt-2">
-      <div
+      <Row
         role="alert"
-        className="bg-warning/10 border-warning/30 flex flex-wrap items-center gap-2 rounded-lg border p-3 text-sm"
+        gap={2}
+        wrap
+        className="bg-warning/10 border-warning/30 rounded-lg border p-3 text-sm"
       >
         <span className="grow">
           <span className="font-medium">{t(titleKey, { count })}</span>
@@ -56,7 +59,7 @@ export function TwoFactorLowBackupCodesBanner({
         >
           {t('lowBackupCodes.regenerateLink')}
         </Link>
-      </div>
+      </Row>
     </div>
   );
 }
diff --git a/services/platform/app/features/automations/components/automation-ai-chat-panel.tsx b/services/platform/app/features/automations/components/automation-ai-chat-panel.tsx
index 0bc069658d..93c1fe38ef 100644
--- a/services/platform/app/features/automations/components/automation-ai-chat-panel.tsx
+++ b/services/platform/app/features/automations/components/automation-ai-chat-panel.tsx
@@ -103,7 +103,7 @@ export function AutomationAIChatPanel({
             size="icon"
             className="size-8"
             onClick={onClose}
-            aria-label={t('sidePanel.close')}
+            title={t('sidePanel.close')}
           >
             <X className="size-4" />
           </Button>
diff --git a/services/platform/app/features/automations/components/automation-assistant.tsx b/services/platform/app/features/automations/components/automation-assistant.tsx
index aaece8492f..06fcd444b8 100644
--- a/services/platform/app/features/automations/components/automation-assistant.tsx
+++ b/services/platform/app/features/automations/components/automation-assistant.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { useEffect, useRef } from 'react';
 
 import { FileUpload } from '@/app/components/ui/forms/file-upload';
@@ -69,10 +70,11 @@ function AutomationAssistantContent({
   }, [itemCount, isLoading]);
 
   return (
-    <div className="relative flex min-h-0 flex-1 flex-col">
-      <div
+    <Stack gap={0} className="relative min-h-0 flex-1">
+      <Stack
         ref={containerRef}
-        className="flex min-h-0 flex-1 flex-col overflow-y-auto px-3 py-2"
+        gap={0}
+        className="min-h-0 flex-1 overflow-y-auto px-3 py-2"
       >
         {/* The SAME rendering stack as the chat page: ChatMessages →
             MessageBubble (markdown, thought timeline, attachments) +
@@ -103,7 +105,7 @@ function AutomationAssistantContent({
             />
           </ThreadMessageMetadataProvider>
         </BranchProvider>
-      </div>
+      </Stack>
 
       <ChatInput
         className="p-2"
@@ -125,7 +127,7 @@ function AutomationAssistantContent({
         isTranscribing={isTranscribing}
         transcriptionStatuses={transcriptionStatuses}
       />
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/automations/components/automation-debug-controls.tsx b/services/platform/app/features/automations/components/automation-debug-controls.tsx
index 7d8ab8b902..b63a38dee8 100644
--- a/services/platform/app/features/automations/components/automation-debug-controls.tsx
+++ b/services/platform/app/features/automations/components/automation-debug-controls.tsx
@@ -79,7 +79,6 @@ export function AutomationDebugControls({
 
         <HStack gap={2} wrap>
           <Button
-            size="sm"
             onClick={() => resumeDebugStep({ executionId, action: 'step' })}
             disabled={isBusy}
           >
@@ -87,7 +86,6 @@ export function AutomationDebugControls({
             {t('tester.debug.step')}
           </Button>
           <Button
-            size="sm"
             variant="secondary"
             onClick={() => resumeDebugStep({ executionId, action: 'continue' })}
             disabled={isBusy}
@@ -96,7 +94,6 @@ export function AutomationDebugControls({
             {t('tester.debug.continue')}
           </Button>
           <Button
-            size="sm"
             variant="destructive"
             onClick={() => cancelExecution({ executionId })}
             disabled={isBusy}
diff --git a/services/platform/app/features/automations/components/automation-group-node.tsx b/services/platform/app/features/automations/components/automation-group-node.tsx
index f304296149..c8e9e97958 100644
--- a/services/platform/app/features/automations/components/automation-group-node.tsx
+++ b/services/platform/app/features/automations/components/automation-group-node.tsx
@@ -1,3 +1,4 @@
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import React from 'react';
 
@@ -9,7 +10,7 @@ interface AutomationGroupNodeProps {
 
 export function AutomationGroupNode({ data }: AutomationGroupNodeProps) {
   return (
-    <div className="flex h-full w-full items-start justify-start p-2">
+    <Row gap={0} align="start" className="h-full w-full p-2">
       <Text
         as="span"
         variant="caption"
@@ -17,6 +18,6 @@ export function AutomationGroupNode({ data }: AutomationGroupNodeProps) {
       >
         {data.label}
       </Text>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/automations/components/automation-history-diff-dialog.tsx b/services/platform/app/features/automations/components/automation-history-diff-dialog.tsx
index d4f59ebe47..3df90d6b5a 100644
--- a/services/platform/app/features/automations/components/automation-history-diff-dialog.tsx
+++ b/services/platform/app/features/automations/components/automation-history-diff-dialog.tsx
@@ -2,6 +2,7 @@
 
 import 'json-diff-kit/viewer.css';
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Differ, Viewer } from 'json-diff-kit';
 import { useMemo } from 'react';
 
@@ -66,7 +67,7 @@ export function AutomationHistoryDiffDialog({
       })}
       size="wide"
       footer={
-        <div className="flex justify-end gap-2">
+        <Row gap={2} align="stretch" justify="end">
           <Button
             variant="secondary"
             onClick={() => onOpenChange(false)}
@@ -81,7 +82,7 @@ export function AutomationHistoryDiffDialog({
           >
             {isRestoring ? tCommon('actions.loading') : t('history.restore')}
           </Button>
-        </div>
+        </Row>
       }
     >
       {!hasChanges ? (
diff --git a/services/platform/app/features/automations/components/automation-loop-container.tsx b/services/platform/app/features/automations/components/automation-loop-container.tsx
index 6bd790a8c9..b5b5889621 100644
--- a/services/platform/app/features/automations/components/automation-loop-container.tsx
+++ b/services/platform/app/features/automations/components/automation-loop-container.tsx
@@ -2,6 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Heading } from '@tale/ui/heading';
+import { Row, Stack } from '@tale/ui/layout';
 import { Position } from '@xyflow/react';
 import { Repeat } from 'lucide-react';
 import React from 'react';
@@ -88,9 +89,9 @@ export function AutomationLoopContainer({
         onClick={() => data.onNodeClick?.(data.stepSlug)}
         style={{ overflow: 'visible', position: 'relative' }}
       >
-        <div className="flex h-full flex-col p-5">
+        <Stack gap={0} className="h-full p-5">
           {/* Header with icon, title, and label */}
-          <div className="mb-4 flex flex-shrink-0 items-start gap-3">
+          <Row gap={3} align="start" className="mb-4 flex-shrink-0">
             {/* Icon on left */}
             <Repeat className="size-6 shrink-0 rounded-md bg-cyan-100 p-1 text-cyan-700 dark:bg-cyan-950 dark:text-cyan-300" />
 
@@ -108,7 +109,7 @@ export function AutomationLoopContainer({
             >
               {t('stepTypes.loop')}
             </Badge>
-          </div>
+          </Row>
 
           {/* Loop Body Container - Children nodes will be rendered here */}
           <div
@@ -117,7 +118,7 @@ export function AutomationLoopContainer({
           >
             {/* Children nodes are rendered by ReactFlow's parent-child system */}
           </div>
-        </div>
+        </Stack>
       </button>
 
       {/* Execution status badge — sibling of the card button (nesting would
diff --git a/services/platform/app/features/automations/components/automation-navigation.tsx b/services/platform/app/features/automations/components/automation-navigation.tsx
index 67fb28bb5a..d80b087d57 100644
--- a/services/platform/app/features/automations/components/automation-navigation.tsx
+++ b/services/platform/app/features/automations/components/automation-navigation.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuItem } from '@tale/ui/dropdown-menu';
+import { Row } from '@tale/ui/layout';
 import { History, Sparkles } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
@@ -239,7 +240,6 @@ export function AutomationNavigation({
       trigger={
         <Button
           variant="secondary"
-          size="sm"
           className="h-8 text-sm"
           icon={History}
           iconClassName="size-3.5"
@@ -301,10 +301,10 @@ function AutomationEditorActionsSlot({
   const controller = useActiveEditor();
   if (!controller) {
     return (
-      <div className="ml-auto flex items-center gap-2">
+      <Row gap={2} className="ml-auto">
         {assistant}
         {history}
-      </div>
+      </Row>
     );
   }
   return (
diff --git a/services/platform/app/features/automations/components/automation-sidepanel.tsx b/services/platform/app/features/automations/components/automation-sidepanel.tsx
index d397f86224..8b22ec13de 100644
--- a/services/platform/app/features/automations/components/automation-sidepanel.tsx
+++ b/services/platform/app/features/automations/components/automation-sidepanel.tsx
@@ -2,7 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
-import { HStack, VStack } from '@tale/ui/layout';
+import { HStack, Stack, VStack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   TestTubeDiagonal,
@@ -195,7 +195,6 @@ const StepEditorContent = memo(function StepEditorContent({
         <Button
           onClick={onSave}
           disabled={isSaving || !isValid || !isDirty}
-          size="sm"
           className="flex-1"
         >
           <Save className="mr-1 size-4" />
@@ -292,7 +291,7 @@ export function AutomationSidePanel({
   if (!isOpen) return null;
 
   return (
-    <aside
+    <Stack
       ref={panelRef}
       role="complementary"
       aria-label={
@@ -301,7 +300,9 @@ export function AutomationSidePanel({
           : (step?.name ?? t('sidePanel.stepEditor'))
       }
       style={{ '--panel-width': `${width}px` }}
-      className="bg-background border-border relative flex min-h-0 w-(--panel-width) flex-[0_0_auto] flex-col overflow-hidden border-l max-md:absolute max-md:inset-0 max-md:z-10 max-md:w-full"
+      as="aside"
+      gap={0}
+      className="bg-background border-border relative min-h-0 w-(--panel-width) flex-[0_0_auto] overflow-hidden border-l max-md:absolute max-md:inset-0 max-md:z-10 max-md:w-full"
     >
       {/* Resize handle */}
       <div
@@ -366,7 +367,7 @@ export function AutomationSidePanel({
             size="icon"
             className="size-8"
             onClick={onClose}
-            aria-label={t('sidePanel.close')}
+            title={t('sidePanel.close')}
           >
             <X className="size-4" />
           </Button>
@@ -395,6 +396,6 @@ export function AutomationSidePanel({
           workflowSlug={automationId ? urlParamToSlug(automationId) : undefined}
         />
       ) : null}
-    </aside>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/automations/components/automation-step.tsx b/services/platform/app/features/automations/components/automation-step.tsx
index 0bca7816ab..742d0a125c 100644
--- a/services/platform/app/features/automations/components/automation-step.tsx
+++ b/services/platform/app/features/automations/components/automation-step.tsx
@@ -2,6 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Heading } from '@tale/ui/heading';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Position } from '@xyflow/react';
 
@@ -92,13 +93,13 @@ export function AutomationStep({ data }: AutomationStepProps) {
       )}
       onClick={() => onNodeClick(data.stepSlug)}
     >
-      <div className="flex gap-3 px-2.5 py-2">
+      <Row gap={3} align="stretch" className="px-2.5 py-2">
         {/* Icon on left */}
         {getIcon(data.stepType, data.actionType)}
 
         {/* Content in center */}
         <div className="min-w-0 flex-1">
-          <div className="flex items-center gap-2">
+          <Row gap={2}>
             <Heading level={3} size="sm">
               {data.label}
             </Heading>
@@ -108,7 +109,7 @@ export function AutomationStep({ data }: AutomationStepProps) {
                 {t('sidePanel.end')}
               </span>
             )}
-          </div>
+          </Row>
           {data.description && (
             <Text variant="caption" className="mt-1 line-clamp-2">
               {data.description}
@@ -123,7 +124,7 @@ export function AutomationStep({ data }: AutomationStepProps) {
         >
           {getStepTypeLabel(data.stepType)}
         </Badge>
-      </div>
+      </Row>
     </button>
   );
 
diff --git a/services/platform/app/features/automations/components/automation-steps.tsx b/services/platform/app/features/automations/components/automation-steps.tsx
index e04e88cd50..ce696ab5ee 100644
--- a/services/platform/app/features/automations/components/automation-steps.tsx
+++ b/services/platform/app/features/automations/components/automation-steps.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   ReactFlowProvider,
@@ -125,6 +125,7 @@ function AutomationStepsInner({
   onOpenAIChat,
 }: AutomationStepsProps) {
   const { t } = useT('automations');
+  const { t: tCommon } = useT('common');
   const hasSteps = steps && steps.length > 0;
   const [nodes, setNodes, onNodesChange] = useNodesState<Node>([]);
   // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- without explicit Edge, TS infers never[]
@@ -343,7 +344,11 @@ function AutomationStepsInner({
       onAddStepOnEdge={handleAddStepOnEdge}
       onDeleteEdge={handleDeleteEdge}
     >
-      <div className="relative flex w-full flex-1 justify-stretch overflow-auto">
+      <Row
+        gap={0}
+        align="stretch"
+        className="relative w-full flex-1 justify-stretch overflow-auto"
+      >
         <style>{MINIMAP_STYLES}</style>
         <div ref={containerRef} className="bg-background min-h-0 flex-[1_1_0]">
           <FlowCanvas
@@ -423,7 +428,11 @@ function AutomationStepsInner({
             }}
           >
             {!hasSteps && (
-              <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+              <Row
+                gap={0}
+                justify="center"
+                className="pointer-events-none absolute inset-0"
+              >
                 <Stack gap={2} className="text-center">
                   <Text as="div" variant="muted">
                     {t('emptyState.noSteps')}
@@ -432,7 +441,7 @@ function AutomationStepsInner({
                     {t('emptyState.createStepsHint')}
                   </Text>
                 </Stack>
-              </div>
+              </Row>
             )}
 
             {((showActivityBanner && hasActiveTrigger) ||
@@ -448,6 +457,7 @@ function AutomationStepsInner({
                       <Button
                         variant="ghost"
                         size="icon"
+                        title={tCommon('aria.dismiss')}
                         className="ml-auto size-6 shrink-0 p-1 text-amber-600 hover:bg-amber-100 hover:text-amber-700"
                         onClick={() => setShowActivityBanner(false)}
                       >
@@ -508,7 +518,7 @@ function AutomationStepsInner({
           onCreateStep={handleCreateStep}
           stepOptions={stepOptions}
         />
-      </div>
+      </Row>
     </AutomationCallbacksProvider>
   );
 }
diff --git a/services/platform/app/features/automations/components/automations-table.tsx b/services/platform/app/features/automations/components/automations-table.tsx
index 4e5357da5e..3c6fcb7185 100644
--- a/services/platform/app/features/automations/components/automations-table.tsx
+++ b/services/platform/app/features/automations/components/automations-table.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { LinkButton } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { useNavigate } from '@tanstack/react-router';
 import {
   type ColumnDef,
@@ -323,7 +324,7 @@ export function AutomationsTable({
     // `PageLayout` adds no padding, so without this the table renders flush to
     // the edge — no gap, and its select / 3-dot columns sit out of line with
     // the rest of the app. `gap-4` controls the search-bar / table spacing.
-    <div className="flex flex-col gap-4 p-4">
+    <Stack className="p-4">
       <div className="flex items-center justify-between gap-4">
         <SearchInput
           wrapperClassName="w-full max-w-sm"
@@ -393,6 +394,6 @@ export function AutomationsTable({
           />
         }
       />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/automations/components/workflow-template-grid.tsx b/services/platform/app/features/automations/components/workflow-template-grid.tsx
index 08dafb0da8..a3469cdd0a 100644
--- a/services/platform/app/features/automations/components/workflow-template-grid.tsx
+++ b/services/platform/app/features/automations/components/workflow-template-grid.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
 import { AlertCircle } from 'lucide-react';
@@ -39,13 +39,15 @@ function TemplateBrandChips({ integrations }: { integrations: string[] }) {
       {integrations.map((integration) => {
         const Icon = getIntegrationBrandIcon(integration);
         return (
-          <div
+          <Row
             key={integration}
-            className="border-border bg-background text-foreground flex size-5 items-center justify-center rounded border p-1"
+            gap={0}
+            justify="center"
+            className="border-border bg-background text-foreground size-5 rounded border p-1"
             aria-label={integration}
           >
             <Icon className="size-3" />
-          </div>
+          </Row>
         );
       })}
     </>
@@ -106,9 +108,9 @@ export function WorkflowTemplateGrid({
 
   if (isLoadingTemplates) {
     return (
-      <div className="flex items-center justify-center p-8">
+      <Row gap={0} justify="center" className="p-8">
         <Spinner size="sm" label={t('templates.fetching')} />
-      </div>
+      </Row>
     );
   }
 
@@ -121,13 +123,15 @@ export function WorkflowTemplateGrid({
       <Text variant="muted">{t('templates.description')}</Text>
 
       {error && (
-        <div
-          className="bg-destructive/10 text-destructive flex items-start gap-2 rounded-md p-3 text-sm"
+        <Row
+          gap={2}
+          align="start"
+          className="bg-destructive/10 text-destructive rounded-md p-3 text-sm"
           role="alert"
         >
           <AlertCircle className="mt-0.5 size-4 shrink-0" />
           <span>{error}</span>
-        </div>
+        </Row>
       )}
 
       <div
diff --git a/services/platform/app/features/automations/executions/executions-table.tsx b/services/platform/app/features/automations/executions/executions-table.tsx
index 05d0fb2d6c..48da4a0805 100644
--- a/services/platform/app/features/automations/executions/executions-table.tsx
+++ b/services/platform/app/features/automations/executions/executions-table.tsx
@@ -233,6 +233,7 @@ export function ExecutionsTable({
             <Button
               variant="ghost"
               size="icon"
+              title={tCommon('actions.copy')}
               className="p-1"
               onClick={(e) => {
                 e.stopPropagation();
@@ -306,6 +307,7 @@ export function ExecutionsTable({
       formatTimestampWithMillis,
       calculateDuration,
       tTables,
+      tCommon,
     ],
   );
 
diff --git a/services/platform/app/features/automations/hooks/use-automations-table-config.tsx b/services/platform/app/features/automations/hooks/use-automations-table-config.tsx
index 37d864a7b1..c109268f2b 100644
--- a/services/platform/app/features/automations/hooks/use-automations-table-config.tsx
+++ b/services/platform/app/features/automations/hooks/use-automations-table-config.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Folder, Package, Workflow } from 'lucide-react';
@@ -48,7 +49,7 @@ export function useAutomationsTableConfig(
           if (row.original.type === 'folder') {
             const isApp = row.original.appSlug !== undefined;
             return (
-              <div className="flex min-h-8 items-center gap-3">
+              <Row gap={3} className="min-h-8">
                 {isApp ? (
                   <Package className="text-muted-foreground size-4 shrink-0" />
                 ) : (
@@ -61,11 +62,11 @@ export function useAutomationsTableConfig(
                   <Badge variant="slate">{tAutomations('appBadge')}</Badge>
                 )}
                 <Badge variant="outline">{row.original.workflowCount}</Badge>
-              </div>
+              </Row>
             );
           }
           return (
-            <div className="flex min-h-8 items-center gap-3">
+            <Row gap={3} className="min-h-8">
               <Workflow className="text-muted-foreground size-4 shrink-0" />
               <Text as="span" variant="label" truncate>
                 {showFolderPath && row.original.folderPath ? (
@@ -79,7 +80,7 @@ export function useAutomationsTableConfig(
                   row.original.name
                 )}
               </Text>
-            </div>
+            </Row>
           );
         },
       },
@@ -118,8 +119,10 @@ export function useAutomationsTableConfig(
         cell: ({ row }) => {
           if (row.original.type === 'folder') return null;
           return (
-            <div
-              className="flex justify-end"
+            <Row
+              gap={0}
+              align="stretch"
+              justify="end"
               role="presentation"
               onClick={(e) => e.stopPropagation()}
               onKeyDown={(e) => e.stopPropagation()}
@@ -132,7 +135,7 @@ export function useAutomationsTableConfig(
                 }}
                 isAppOwned={row.original.appSlug !== undefined}
               />
-            </div>
+            </Row>
           );
         },
       },
diff --git a/services/platform/app/features/automations/metrics/chart-card-header.tsx b/services/platform/app/features/automations/metrics/chart-card-header.tsx
deleted file mode 100644
index a30c6c50cc..0000000000
--- a/services/platform/app/features/automations/metrics/chart-card-header.tsx
+++ /dev/null
@@ -1,32 +0,0 @@
-'use client';
-
-import { Text } from '@tale/ui/text';
-import { Info } from 'lucide-react';
-
-import { Tooltip } from '@/app/components/ui/overlays/tooltip';
-
-interface ChartCardHeaderProps {
-  title: string;
-  tooltip?: string;
-}
-
-export function ChartCardHeader({ title, tooltip }: ChartCardHeaderProps) {
-  return (
-    <div className="flex items-center justify-between gap-2">
-      <Text as="h3" className="text-sm font-semibold">
-        {title}
-      </Text>
-      {tooltip ? (
-        <Tooltip content={tooltip} side="top">
-          <button
-            type="button"
-            aria-label={tooltip}
-            className="text-muted-foreground hover:text-foreground focus-visible:ring-ring inline-flex h-6 w-6 items-center justify-center rounded focus-visible:ring-2 focus-visible:outline-none"
-          >
-            <Info className="h-4 w-4" aria-hidden />
-          </button>
-        </Tooltip>
-      ) : null}
-    </div>
-  );
-}
diff --git a/services/platform/app/features/automations/metrics/chart-tooltip-style.ts b/services/platform/app/features/automations/metrics/chart-tooltip-style.ts
deleted file mode 100644
index 141425af8b..0000000000
--- a/services/platform/app/features/automations/metrics/chart-tooltip-style.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import type { CSSProperties } from 'react';
-
-/** Shared recharts `<Tooltip contentStyle>` so the automation metric charts
- *  keep one tooltip appearance. */
-export const CHART_TOOLTIP_CONTENT_STYLE: CSSProperties = {
-  fontSize: 12,
-  borderRadius: 6,
-  border: '1px solid var(--border)',
-  background: 'var(--popover)',
-};
diff --git a/services/platform/app/features/automations/metrics/execution-trend-chart.tsx b/services/platform/app/features/automations/metrics/execution-trend-chart.tsx
index 33d8987f2e..fc100db30a 100644
--- a/services/platform/app/features/automations/metrics/execution-trend-chart.tsx
+++ b/services/platform/app/features/automations/metrics/execution-trend-chart.tsx
@@ -1,30 +1,29 @@
 'use client';
 
-import {
-  Bar,
-  BarChart,
-  CartesianGrid,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from 'recharts';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
 
+import {
+  seriesToLegend,
+  TrendBarChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
 import { useT } from '@/lib/i18n/client';
 
-import { ChartCardHeader } from './chart-card-header';
-import { CHART_TOOLTIP_CONTENT_STYLE } from './chart-tooltip-style';
-
-interface TrendPoint {
+// A type alias (not an interface) so it carries an implicit index signature and
+// is assignable to the charts' `ChartRow` row type.
+type TrendPoint = {
   dateKey: string;
   completed: number;
   failed: number;
-}
+};
 
 interface ExecutionTrendChartProps {
   series: TrendPoint[];
 }
 
+/** Short axis label `06-13` from a `2026-06-13` date key (tooltip keeps full). */
 function shortLabel(dateKey: string): string {
   const [, month, day] = dateKey.split('-');
   return `${month}-${day}`;
@@ -32,101 +31,39 @@ function shortLabel(dateKey: string): string {
 
 export function ExecutionTrendChart({ series }: ExecutionTrendChartProps) {
   const { t } = useT('automations');
-  const data = series.map((p) => ({
-    ...p,
-    label: shortLabel(p.dateKey),
-  }));
 
-  const legend = [
+  const chartSeries: ChartSeries[] = [
     {
-      name: t('metrics.chart.completed'),
-      color: 'var(--color-chart-success, #10b981)',
+      key: 'completed',
+      label: t('metrics.chart.completed'),
+      color: CHART_COLORS.success,
+      stackId: 'runs',
     },
     {
-      name: t('metrics.chart.failed'),
-      color: 'var(--color-chart-failure, #ef4444)',
+      key: 'failed',
+      label: t('metrics.chart.failed'),
+      color: CHART_COLORS.failure,
+      stackId: 'runs',
     },
   ];
 
+  const isEmpty = series.every((p) => !p.completed && !p.failed);
+
   return (
-    <div className="border-border bg-card flex h-full flex-col gap-4 rounded-lg border p-5">
-      <ChartCardHeader
-        title={t('metrics.chart.trendTitle')}
-        tooltip={t('metrics.chart.trendTooltip')}
+    <ChartCard
+      title={t('metrics.chart.trendTitle')}
+      tooltip={t('metrics.chart.trendTooltip')}
+      isEmpty={isEmpty}
+      emptyTitle={t('metrics.chart.noData')}
+      emptyDescription={t('metrics.chart.noDataDescription')}
+      legend={<ChartLegend items={seriesToLegend(chartSeries)} />}
+    >
+      <TrendBarChart
+        data={series}
+        series={chartSeries}
+        xKey="dateKey"
+        xTickFormatter={shortLabel}
       />
-      <div className="h-60 w-full">
-        <ResponsiveContainer width="100%" height="100%">
-          <BarChart
-            data={data}
-            margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
-          >
-            <CartesianGrid
-              strokeDasharray="3 3"
-              className="stroke-border"
-              vertical={false}
-            />
-            <XAxis
-              dataKey="label"
-              tick={{ fontSize: 11 }}
-              tickLine={false}
-              axisLine={false}
-              tickMargin={8}
-              className="text-muted-foreground"
-            />
-            <YAxis
-              allowDecimals={false}
-              tick={{ fontSize: 11 }}
-              tickLine={false}
-              axisLine={false}
-              width={28}
-              className="text-muted-foreground"
-            />
-            <Tooltip
-              contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
-              labelFormatter={(value, payload) => {
-                const first = payload?.[0];
-                if (
-                  first &&
-                  typeof first === 'object' &&
-                  'payload' in first &&
-                  first.payload &&
-                  typeof first.payload === 'object' &&
-                  'dateKey' in first.payload &&
-                  typeof first.payload.dateKey === 'string'
-                ) {
-                  return first.payload.dateKey;
-                }
-                return String(value);
-              }}
-            />
-            <Bar
-              dataKey="completed"
-              stackId="runs"
-              fill="var(--color-chart-success, #10b981)"
-              name={t('metrics.chart.completed')}
-              radius={[0, 0, 0, 0]}
-            />
-            <Bar
-              dataKey="failed"
-              stackId="runs"
-              fill="var(--color-chart-failure, #ef4444)"
-              name={t('metrics.chart.failed')}
-              radius={[4, 4, 0, 0]}
-            />
-          </BarChart>
-        </ResponsiveContainer>
-      </div>
-      <div className="flex flex-wrap justify-center gap-x-4 gap-y-1">
-        {legend.map((d) => (
-          <div key={d.name} className="flex items-center gap-2 text-xs">
-            <span
-              className="h-3 w-3 rounded-[2px]"
-              style={{ background: d.color }}
-            />
-            <span className="text-muted-foreground">{d.name}</span>
-          </div>
-        ))}
-      </div>
-    </div>
+    </ChartCard>
   );
 }
diff --git a/services/platform/app/features/automations/metrics/metrics-page.tsx b/services/platform/app/features/automations/metrics/metrics-page.tsx
index fb5473fb84..2838d2b214 100644
--- a/services/platform/app/features/automations/metrics/metrics-page.tsx
+++ b/services/platform/app/features/automations/metrics/metrics-page.tsx
@@ -1,10 +1,12 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
-import { SectionHeader } from '@tale/ui/section-header';
+import { Alert } from '@tale/ui/alert';
+import { Grid } from '@tale/ui/layout';
+import { AlertTriangle } from 'lucide-react';
 import { useMemo } from 'react';
 
-import { Select } from '@/app/components/ui/forms/select';
+import { MetricSelect } from '@/app/components/metrics/metric-select';
+import { MetricsLayout } from '@/app/components/metrics/metrics-layout';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { api } from '@/convex/_generated/api';
 import { useT } from '@/lib/i18n/client';
@@ -48,41 +50,40 @@ export function WorkflowMetricsPage({
   const topWorkflows = data?.topWorkflows ?? [];
 
   return (
-    <Stack gap={6} className="p-6">
-      <SectionHeader
-        title={t('metrics.title')}
-        description={t('metrics.description')}
-        className="items-start"
-        action={
-          <div className="w-44">
-            <Select
-              options={periodOptions}
-              value={String(periodDays)}
-              onValueChange={(v) => {
-                const next = Number(v);
-                if (next === 7 || next === 30 || next === 90)
-                  onChangePeriod(next);
-              }}
-              size="sm"
-            />
-          </div>
-        }
-      />
-
-      {summary?.capped ? (
-        <div className="border-border bg-muted/40 rounded-md border px-3 py-2 text-xs">
-          {t('metrics.cappedNotice')}
-        </div>
-      ) : null}
-
+    <MetricsLayout
+      className="p-6"
+      title={t('metrics.title')}
+      description={t('metrics.description')}
+      toolbar={
+        <MetricSelect
+          aria-label={t('metrics.period.label')}
+          options={periodOptions}
+          value={String(periodDays)}
+          onValueChange={(v) => {
+            const next = Number(v);
+            if (next === 7 || next === 30 || next === 90) onChangePeriod(next);
+          }}
+        />
+      }
+      notice={
+        summary?.capped ? (
+          <Alert
+            variant="warning"
+            icon={AlertTriangle}
+            title={t('metrics.cappedNotice')}
+          />
+        ) : undefined
+      }
+    >
       <MetricsSummaryCards
         total={summary?.total ?? 0}
         successRate={summary?.successRate ?? 0}
         avgExecutionTimeSeconds={summary?.avgExecutionTimeSeconds ?? 0}
         failed={summary?.failed ?? 0}
+        previous={data?.previousSummary}
       />
 
-      <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+      <Grid lg={3}>
         <div className="lg:col-span-2">
           <ExecutionTrendChart series={series} />
         </div>
@@ -93,13 +94,13 @@ export function WorkflowMetricsPage({
             running={summary?.running ?? 0}
           />
         </div>
-      </div>
+      </Grid>
 
       <TopWorkflowsTable
         organizationId={organizationId}
         rows={topWorkflows}
         isLoading={isLoading}
       />
-    </Stack>
+    </MetricsLayout>
   );
 }
diff --git a/services/platform/app/features/automations/metrics/metrics-summary-cards.tsx b/services/platform/app/features/automations/metrics/metrics-summary-cards.tsx
index 2b3fd3d6cf..d3bdf3111c 100644
--- a/services/platform/app/features/automations/metrics/metrics-summary-cards.tsx
+++ b/services/platform/app/features/automations/metrics/metrics-summary-cards.tsx
@@ -1,30 +1,32 @@
 'use client';
 
-import { Text } from '@tale/ui/text';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
+import { type ReactNode } from 'react';
 
 import { useT } from '@/lib/i18n/client';
 import { formatNumber } from '@/lib/utils/format/number';
 
 import { formatDurationSeconds, formatSuccessRate } from './format-duration';
 
+/** Prior equal-length window totals (from the query's `previousSummary`). */
+interface PreviousSummary {
+  total: number;
+  successRate: number;
+  avgExecutionTimeSeconds: number;
+  failed: number;
+}
+
 interface MetricsSummaryCardsProps {
   total: number;
   successRate: number;
   avgExecutionTimeSeconds: number;
   failed: number;
+  previous?: PreviousSummary;
 }
 
-function StatCell({ label, value }: { label: string; value: string }) {
-  return (
-    <div className="flex flex-1 flex-col gap-1 px-5 py-4 first:pl-6 last:pr-6">
-      <Text className="text-muted-foreground text-[13px] font-normal">
-        {label}
-      </Text>
-      <Text className="text-2xl font-semibold tracking-tight tabular-nums">
-        {value}
-      </Text>
-    </div>
-  );
+function delta(node: ReactNode): ReactNode {
+  return <div className="mt-0.5">{node}</div>;
 }
 
 export function MetricsSummaryCards({
@@ -32,28 +34,54 @@ export function MetricsSummaryCards({
   successRate,
   avgExecutionTimeSeconds,
   failed,
+  previous,
 }: MetricsSummaryCardsProps) {
   const { t } = useT('automations');
   const successRateDisplay = formatSuccessRate(total, successRate);
 
   return (
-    <div className="border-border bg-card grid grid-cols-2 divide-y rounded-lg border md:grid-cols-4 md:divide-x md:divide-y-0">
-      <StatCell
+    <StatCardGrid>
+      <StatCard
         label={t('metrics.cards.totalRuns')}
         value={formatNumber(total)}
-      />
-      <StatCell
+      >
+        {delta(<TrendIndicator value={total} previous={previous?.total} />)}
+      </StatCard>
+      <StatCard
         label={t('metrics.cards.successRate')}
         value={successRateDisplay}
-      />
-      <StatCell
+      >
+        {delta(
+          <TrendIndicator
+            value={successRate}
+            previous={previous?.successRate}
+          />,
+        )}
+      </StatCard>
+      <StatCard
         label={t('metrics.cards.avgDuration')}
         value={formatDurationSeconds(avgExecutionTimeSeconds)}
-      />
-      <StatCell
+      >
+        {delta(
+          <TrendIndicator
+            value={avgExecutionTimeSeconds}
+            previous={previous?.avgExecutionTimeSeconds}
+            inverted
+          />,
+        )}
+      </StatCard>
+      <StatCard
         label={t('metrics.cards.failedRuns')}
         value={formatNumber(failed)}
-      />
-    </div>
+      >
+        {delta(
+          <TrendIndicator
+            value={failed}
+            previous={previous?.failed}
+            inverted
+          />,
+        )}
+      </StatCard>
+    </StatCardGrid>
   );
 }
diff --git a/services/platform/app/features/automations/metrics/status-breakdown.tsx b/services/platform/app/features/automations/metrics/status-breakdown.tsx
index 198c4fbd36..0fbdc97b63 100644
--- a/services/platform/app/features/automations/metrics/status-breakdown.tsx
+++ b/services/platform/app/features/automations/metrics/status-breakdown.tsx
@@ -1,15 +1,18 @@
 'use client';
 
-import { Text } from '@tale/ui/text';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
 import { Clock } from 'lucide-react';
-import { Cell, Pie, PieChart, ResponsiveContainer, Tooltip } from 'recharts';
 
+import {
+  DonutChart,
+  segmentsToLegend,
+  type DonutSegment,
+} from '@/app/components/metrics/charts';
 import { useT } from '@/lib/i18n/client';
 import { formatNumber } from '@/lib/utils/format/number';
 
-import { ChartCardHeader } from './chart-card-header';
-import { CHART_TOOLTIP_CONTENT_STYLE } from './chart-tooltip-style';
-
 interface StatusBreakdownProps {
   completed: number;
   failed: number;
@@ -24,96 +27,44 @@ export function StatusBreakdown({
   const { t } = useT('automations');
   const total = completed + failed + running;
 
-  const data = [
+  const segments: DonutSegment[] = [
     {
-      name: t('metrics.chart.completed'),
+      key: 'completed',
+      label: t('metrics.chart.completed'),
       value: completed,
-      color: 'var(--color-chart-success, #10b981)',
+      color: CHART_COLORS.success,
     },
     {
-      name: t('metrics.chart.failed'),
+      key: 'failed',
+      label: t('metrics.chart.failed'),
       value: failed,
-      color: 'var(--color-chart-failure, #ef4444)',
+      color: CHART_COLORS.failure,
     },
     {
-      name: t('metrics.chart.running'),
+      key: 'running',
+      label: t('metrics.chart.running'),
       value: running,
-      color: 'var(--color-chart-neutral, #9ca3af)',
+      color: CHART_COLORS.neutral,
     },
   ];
-  const slices = data.filter((d) => d.value > 0);
 
   return (
-    <div className="border-border bg-card flex h-full flex-col gap-4 rounded-lg border p-5">
-      <ChartCardHeader
-        title={t('metrics.chart.statusTitle')}
-        tooltip={t('metrics.chart.statusTooltip')}
+    <ChartCard
+      title={t('metrics.chart.statusTitle')}
+      tooltip={t('metrics.chart.statusTooltip')}
+      bodyClassName="h-48"
+      isEmpty={total === 0}
+      emptyIcon={Clock}
+      emptyTitle={t('metrics.chart.noData')}
+      emptyDescription={t('metrics.chart.noDataDescription')}
+      legend={<ChartLegend items={segmentsToLegend(segments, formatNumber)} />}
+    >
+      <DonutChart
+        segments={segments}
+        valueFormatter={formatNumber}
+        centerValue={formatNumber(total)}
+        centerLabel={t('metrics.chart.totalLabel')}
       />
-
-      <div className="relative flex flex-1 items-center justify-center">
-        {total === 0 ? (
-          <div className="text-muted-foreground flex flex-col items-center gap-2 py-8 text-center">
-            <Clock className="h-8 w-8 opacity-60" aria-hidden />
-            <Text className="text-sm font-medium">
-              {t('metrics.chart.noData')}
-            </Text>
-            <Text className="text-muted-foreground text-xs">
-              {t('metrics.chart.noDataDescription')}
-            </Text>
-          </div>
-        ) : (
-          <>
-            <div className="h-48 w-full">
-              <ResponsiveContainer width="100%" height="100%">
-                <PieChart>
-                  <Tooltip
-                    contentStyle={CHART_TOOLTIP_CONTENT_STYLE}
-                    formatter={(value) =>
-                      typeof value === 'number' ? formatNumber(value) : ''
-                    }
-                  />
-                  <Pie
-                    data={slices}
-                    dataKey="value"
-                    nameKey="name"
-                    innerRadius={56}
-                    outerRadius={84}
-                    paddingAngle={2}
-                    stroke="none"
-                  >
-                    {slices.map((entry) => (
-                      <Cell key={entry.name} fill={entry.color} />
-                    ))}
-                  </Pie>
-                </PieChart>
-              </ResponsiveContainer>
-            </div>
-            <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center">
-              <Text className="text-2xl font-semibold tabular-nums">
-                {formatNumber(total)}
-              </Text>
-              <Text className="text-muted-foreground text-xs">
-                {t('metrics.chart.totalLabel')}
-              </Text>
-            </div>
-          </>
-        )}
-      </div>
-
-      <div className="flex flex-wrap justify-center gap-x-4 gap-y-1">
-        {data.map((d) => (
-          <div key={d.name} className="flex items-center gap-2 text-xs">
-            <span
-              className="h-3 w-3 rounded-[2px]"
-              style={{ background: d.color }}
-            />
-            <span className="text-muted-foreground">{d.name}</span>
-            <span className="font-semibold tabular-nums">
-              {formatNumber(d.value)}
-            </span>
-          </div>
-        ))}
-      </div>
-    </div>
+    </ChartCard>
   );
 }
diff --git a/services/platform/app/features/automations/metrics/top-workflows-table.tsx b/services/platform/app/features/automations/metrics/top-workflows-table.tsx
index 13eafa511c..6ebae86d49 100644
--- a/services/platform/app/features/automations/metrics/top-workflows-table.tsx
+++ b/services/platform/app/features/automations/metrics/top-workflows-table.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useNavigate } from '@tanstack/react-router';
 import type { ColumnDef, Row } from '@tanstack/react-table';
@@ -140,7 +141,7 @@ export function TopWorkflowsTable({
   );
 
   return (
-    <div className="flex flex-col gap-3">
+    <Stack gap={3}>
       <h2 className="text-base font-semibold">{t('metrics.table.title')}</h2>
       <DataTable
         columns={columns}
@@ -157,6 +158,6 @@ export function TopWorkflowsTable({
           description: t('metrics.empty.description'),
         }}
       />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/automations/triggers/components/event-create-dialog.tsx b/services/platform/app/features/automations/triggers/components/event-create-dialog.tsx
index 82b4296a3b..23928fc25b 100644
--- a/services/platform/app/features/automations/triggers/components/event-create-dialog.tsx
+++ b/services/platform/app/features/automations/triggers/components/event-create-dialog.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useState, useMemo, useEffect } from 'react';
 
@@ -213,14 +214,14 @@ export function EventCreateDialog({
             <Text variant="label" className="mb-1">
               {t('triggers.events.form.eventType')}
             </Text>
-            <div className="flex items-center gap-2">
+            <Row gap={2}>
               <code className="bg-muted rounded px-2 py-1 font-mono text-sm">
                 {selectedEventType}
               </code>
               <Text as="span" variant="caption">
                 {selectedMeta?.label}
               </Text>
-            </div>
+            </Row>
           </div>
         ) : (
           <Select
diff --git a/services/platform/app/features/automations/triggers/components/events-section.tsx b/services/platform/app/features/automations/triggers/components/events-section.tsx
index 93e9d1512b..3ab5322940 100644
--- a/services/platform/app/features/automations/triggers/components/events-section.tsx
+++ b/services/platform/app/features/automations/triggers/components/events-section.tsx
@@ -259,11 +259,7 @@ export function EventsSection({
           description: t('triggers.events.emptyDescription'),
         }}
         actionMenu={
-          <Button
-            variant="secondary"
-            size="sm"
-            onClick={() => setIsCreateOpen(true)}
-          >
+          <Button variant="secondary" onClick={() => setIsCreateOpen(true)}>
             <Plus className="mr-2 size-4" />
             {t('triggers.events.createButton')}
           </Button>
diff --git a/services/platform/app/features/automations/triggers/components/schedule-create-dialog.tsx b/services/platform/app/features/automations/triggers/components/schedule-create-dialog.tsx
index f32ca6a690..6a94ec9ab6 100644
--- a/services/platform/app/features/automations/triggers/components/schedule-create-dialog.tsx
+++ b/services/platform/app/features/automations/triggers/components/schedule-create-dialog.tsx
@@ -2,6 +2,7 @@
 
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { Text } from '@tale/ui/text';
 import { CronExpressionParser } from 'cron-parser';
@@ -262,7 +263,7 @@ export function ScheduleCreateDialog({
             errorMessage={formErrors.cronExpression?.message}
           />
           <Text variant="caption">{t('triggers.schedules.form.cronHelp')}</Text>
-          <div className="flex flex-wrap gap-2">
+          <Row gap={2} align="stretch" wrap>
             {CRON_PRESETS.map((preset) => (
               <Button
                 key={preset.value}
@@ -299,7 +300,7 @@ export function ScheduleCreateDialog({
                 </Button>
               }
             >
-              <div className="flex flex-col gap-3">
+              <Stack gap={3}>
                 <Input
                   id="naturalLanguage"
                   label={t('triggers.schedules.form.ai.label')}
@@ -318,7 +319,6 @@ export function ScheduleCreateDialog({
                 <Button
                   type="button"
                   variant="primary"
-                  size="sm"
                   onClick={handleGenerate}
                   disabled={!naturalLanguage.trim() || isGenerating}
                   isLoading={isGenerating}
@@ -327,9 +327,9 @@ export function ScheduleCreateDialog({
                 >
                   {t('triggers.schedules.form.ai.generateButton')}
                 </Button>
-              </div>
+              </Stack>
             </Popover>
-          </div>
+          </Row>
           {cronDescription && (
             <output
               className="text-muted-foreground text-xs"
diff --git a/services/platform/app/features/automations/triggers/components/schedules-section.tsx b/services/platform/app/features/automations/triggers/components/schedules-section.tsx
index fe842b743f..9d3c950c2b 100644
--- a/services/platform/app/features/automations/triggers/components/schedules-section.tsx
+++ b/services/platform/app/features/automations/triggers/components/schedules-section.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Plus, Calendar, Pencil, Trash2 } from 'lucide-react';
@@ -98,14 +99,14 @@ export function SchedulesSection({
         id: 'cronExpression',
         header: t('triggers.schedules.columns.cronExpression'),
         cell: ({ row }) => (
-          <div className="flex items-center gap-2">
+          <Row gap={2}>
             <code className="bg-muted rounded px-2 py-0.5 font-mono text-sm">
               {row.original.cronExpression}
             </code>
             <Text as="span" variant="caption">
               {row.original.timezone}
             </Text>
-          </div>
+          </Row>
         ),
         size: 220,
       },
@@ -147,7 +148,7 @@ export function SchedulesSection({
         id: 'actions',
         header: '',
         cell: ({ row }) => (
-          <div className="flex items-center justify-end gap-1">
+          <Row gap={1} justify="end">
             <Button
               variant="ghost"
               size="sm"
@@ -164,7 +165,7 @@ export function SchedulesSection({
             >
               <Trash2 className="size-4" />
             </Button>
-          </div>
+          </Row>
         ),
         size: 100,
       },
@@ -191,11 +192,7 @@ export function SchedulesSection({
           description: t('triggers.schedules.emptyDescription'),
         }}
         actionMenu={
-          <Button
-            variant="secondary"
-            size="sm"
-            onClick={() => setIsCreateOpen(true)}
-          >
+          <Button variant="secondary" onClick={() => setIsCreateOpen(true)}>
             <Plus className="mr-2 size-4" />
             {t('triggers.schedules.createButton')}
           </Button>
diff --git a/services/platform/app/features/automations/triggers/components/secret-reveal-dialog.tsx b/services/platform/app/features/automations/triggers/components/secret-reveal-dialog.tsx
index de75873e34..fc0dd8eb5f 100644
--- a/services/platform/app/features/automations/triggers/components/secret-reveal-dialog.tsx
+++ b/services/platform/app/features/automations/triggers/components/secret-reveal-dialog.tsx
@@ -84,7 +84,6 @@ export function SecretRevealDialog({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 onClick={() => handleCopy(secret.value, index)}
                 className="absolute top-1/2 right-2 -translate-y-1/2"
                 aria-label={`Copy ${secret.label}`}
diff --git a/services/platform/app/features/automations/triggers/components/webhooks-section.tsx b/services/platform/app/features/automations/triggers/components/webhooks-section.tsx
index 1a06c87bd2..9d19fddcba 100644
--- a/services/platform/app/features/automations/triggers/components/webhooks-section.tsx
+++ b/services/platform/app/features/automations/triggers/components/webhooks-section.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Plus, Webhook, Copy, Check, Trash2 } from 'lucide-react';
@@ -153,7 +154,7 @@ export function WebhooksSection({
         cell: ({ row }) => {
           const url = getWebhookUrl(row.original.token);
           return (
-            <div className="flex min-w-0 items-center gap-2">
+            <Row gap={2} className="min-w-0">
               <code
                 className="max-w-[300px] truncate font-mono text-sm"
                 title={url}
@@ -173,7 +174,7 @@ export function WebhooksSection({
                   <Copy className="size-3.5" />
                 )}
               </Button>
-            </div>
+            </Row>
           );
         },
         size: 400,
@@ -206,7 +207,7 @@ export function WebhooksSection({
         id: 'actions',
         header: '',
         cell: ({ row }) => (
-          <div className="flex items-center justify-end">
+          <Row gap={0} justify="end">
             <Button
               variant="ghost"
               size="sm"
@@ -215,7 +216,7 @@ export function WebhooksSection({
             >
               <Trash2 className="size-4" />
             </Button>
-          </div>
+          </Row>
         ),
         size: 60,
       },
@@ -244,7 +245,6 @@ export function WebhooksSection({
         actionMenu={
           <Button
             variant="secondary"
-            size="sm"
             onClick={handleCreate}
             disabled={isCreating}
           >
diff --git a/services/platform/app/features/chat/components/agent-selector.tsx b/services/platform/app/features/chat/components/agent-selector.tsx
index 90167714a4..e23ac7a57c 100644
--- a/services/platform/app/features/chat/components/agent-selector.tsx
+++ b/services/platform/app/features/chat/components/agent-selector.tsx
@@ -110,10 +110,14 @@ export const AgentSelector = memo(function AgentSelector({
         return a.label.localeCompare(b.label);
       });
 
-    // "Auto" is the default mode (null selection). Always pinned first so the
-    // user can return to letting the system route. Only offered when there's
-    // more than one agent to route between — with a single agent there's
-    // nothing to choose, so Auto would be redundant.
+    // "Auto" (the null selection) is pinned first so the user can hand routing
+    // back to the system — but it is NOT the default. New sessions open on the
+    // Assistant (see DEFAULT_SELECTED_AGENT in chat-layout-context): Auto has to
+    // run a routing classifier to pick an agent before it can answer, adding
+    // latency to the first token, whereas the general-purpose Assistant is
+    // suitable for most messages and starts immediately. Auto is only offered
+    // when there's more than one agent to route between — with a single agent
+    // there's nothing to choose, so it would be redundant.
     if (visibleAgents.length <= 1) return agentOptions;
     return [
       {
@@ -244,8 +248,8 @@ export const AgentSelector = memo(function AgentSelector({
           <Button
             type="button"
             className="gap-1.5 sm:min-w-32"
-            size="icon"
             variant="ghost"
+            size="sm"
             aria-label={t('agentSelector.label')}
             disabled={isAgentLoading}
           >
@@ -269,7 +273,6 @@ export const AgentSelector = memo(function AgentSelector({
           canManageAgents ? (
             <Button
               variant="ghost"
-              size="sm"
               className="w-full"
               icon={Plus}
               onClick={handleAddAgentClick}
diff --git a/services/platform/app/features/chat/components/approval-card-renderer.tsx b/services/platform/app/features/chat/components/approval-card-renderer.tsx
index 279a4ef68b..a547303852 100644
--- a/services/platform/app/features/chat/components/approval-card-renderer.tsx
+++ b/services/platform/app/features/chat/components/approval-card-renderer.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import type { ReactNode } from 'react';
 
 import type { ChatItem } from '../hooks/use-merged-chat-items';
@@ -155,5 +156,9 @@ export function ApprovalCardRenderer({
   }
 
   if (!card) return null;
-  return <div className="flex justify-start">{card}</div>;
+  return (
+    <Row gap={0} align="stretch">
+      {card}
+    </Row>
+  );
 }
diff --git a/services/platform/app/features/chat/components/approval-card.tsx b/services/platform/app/features/chat/components/approval-card.tsx
new file mode 100644
index 0000000000..9da691ccb9
--- /dev/null
+++ b/services/platform/app/features/chat/components/approval-card.tsx
@@ -0,0 +1,45 @@
+'use client';
+
+import { Card } from '@tale/ui/card';
+import { type ReactNode } from 'react';
+
+import { cn } from '@/lib/utils/cn';
+
+/**
+ * The shared frame for every in-chat approval / request / control card
+ * (document writes, integration ops, workflow run/create/update, plans, human
+ * input/control/location). One `rounded-xl` `@tale/ui/card` surface so they all
+ * stay visually identical — replaces the per-card hand-rolled
+ * `rounded-xl border border-border p-4 bg-card …` divs.
+ */
+const MAX_WIDTH = {
+  md: 'max-w-md',
+  xl: 'w-full max-w-xl',
+  '2xl': 'w-full max-w-2xl',
+} as const;
+
+interface ApprovalCardProps {
+  /** Width cap. `md` is the default approval card; `xl`/`2xl` are the wider ones. */
+  maxWidth?: keyof typeof MAX_WIDTH;
+  /** Inner padding — `md` (p-4) for most, `lg` (p-5) for the request cards. */
+  padding?: 'md' | 'lg';
+  className?: string;
+  children: ReactNode;
+}
+
+export function ApprovalCard({
+  maxWidth = 'md',
+  padding = 'md',
+  className,
+  children,
+}: ApprovalCardProps) {
+  return (
+    <Card
+      radius="xl"
+      padding={padding}
+      className={cn('overflow-hidden', MAX_WIDTH[maxWidth], className)}
+    >
+      {children}
+    </Card>
+  );
+}
diff --git a/services/platform/app/features/chat/components/arena/arena-model-selector.tsx b/services/platform/app/features/chat/components/arena/arena-model-selector.tsx
index 50dea87c13..0aba394cae 100644
--- a/services/platform/app/features/chat/components/arena/arena-model-selector.tsx
+++ b/services/platform/app/features/chat/components/arena/arena-model-selector.tsx
@@ -2,6 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { Row } from '@tale/ui/layout';
 import { ChevronDown, Cpu } from 'lucide-react';
 import {
   type ReactNode,
@@ -206,7 +207,7 @@ export function ArenaModelSelector({
   if (filteredModels.length < 2) return null;
 
   return (
-    <div className="flex items-center gap-3 px-2">
+    <Row gap={3} className="px-2">
       <div className="flex items-center gap-1.5">
         <span className="text-muted-foreground text-xs font-medium">A</span>
         <SearchableSelect
@@ -274,6 +275,6 @@ export function ArenaModelSelector({
           }
         />
       </div>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/arena/arena-split-view.tsx b/services/platform/app/features/chat/components/arena/arena-split-view.tsx
index 553e675d63..bbd0c4671f 100644
--- a/services/platform/app/features/chat/components/arena/arena-split-view.tsx
+++ b/services/platform/app/features/chat/components/arena/arena-split-view.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { Loader2 } from 'lucide-react';
 import { useEffect, useMemo, useRef } from 'react';
 
@@ -218,17 +219,18 @@ function ArenaColumn({
   }, []);
 
   return (
-    <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+    <Stack gap={0} className="min-h-0 min-w-0 flex-1">
       <div className="border-border bg-muted/50 border-b px-4 py-2">
         <span className="text-muted-foreground text-xs font-medium">
           {label}
         </span>
       </div>
-      <div
+      <Stack
         ref={containerRef}
-        className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+        gap={0}
+        className="min-h-0 flex-1 overflow-y-auto"
       >
-        <div ref={contentRef} className="flex flex-col p-4 sm:p-6">
+        <Stack ref={contentRef} gap={0} className="p-4 sm:p-6">
           <ChatMessages
             items={mergedMessages}
             threadId={threadId}
@@ -249,24 +251,24 @@ function ArenaColumn({
             forkedFromShare={forkInfo?.forkedFromShare}
             hideBranchNavigator
           />
-        </div>
-      </div>
-    </div>
+        </Stack>
+      </Stack>
+    </Stack>
   );
 }
 
 function ArenaColumnSkeleton({ label }: { label: string }) {
   return (
-    <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+    <Stack gap={0} className="min-h-0 min-w-0 flex-1">
       <div className="border-border bg-muted/50 border-b px-4 py-2">
         <span className="text-muted-foreground text-xs font-medium">
           {label}
         </span>
       </div>
-      <div className="flex min-h-0 flex-1 items-center justify-center">
+      <Row gap={0} justify="center" className="min-h-0 flex-1">
         <Loader2 className="text-muted-foreground size-5 animate-spin" />
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
@@ -279,8 +281,8 @@ export function ArenaSplitView({ organizationId }: ArenaSplitViewProps) {
   const labelB = modelB ? `B - ${modelB}` : t('arena.modelBLabel');
 
   return (
-    <div className="flex min-h-0 flex-1 flex-col">
-      <div className="flex min-h-0 flex-1 overflow-hidden">
+    <Stack gap={0} className="min-h-0 flex-1">
+      <Row gap={0} align="stretch" className="min-h-0 flex-1 overflow-hidden">
         {arenaThreadIdA ? (
           <ArenaColumn
             label={labelA}
@@ -306,7 +308,7 @@ export function ArenaSplitView({ organizationId }: ArenaSplitViewProps) {
         ) : (
           <ArenaColumnSkeleton label={labelB} />
         )}
-      </div>
+      </Row>
       {arenaThreadIdA && arenaThreadIdB && (
         <ArenaVerdictBar
           threadIdA={arenaThreadIdA}
@@ -314,6 +316,6 @@ export function ArenaSplitView({ organizationId }: ArenaSplitViewProps) {
           organizationId={organizationId}
         />
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/arena/arena-verdict-bar.tsx b/services/platform/app/features/chat/components/arena/arena-verdict-bar.tsx
index 65546be2b1..c459cadd80 100644
--- a/services/platform/app/features/chat/components/arena/arena-verdict-bar.tsx
+++ b/services/platform/app/features/chat/components/arena/arena-verdict-bar.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { useState, useCallback } from 'react';
 
 import { useConvexMutation } from '@/app/hooks/use-convex-mutation';
@@ -92,8 +93,10 @@ export function ArenaVerdictBar({
   ];
 
   return (
-    <div
-      className="border-border flex items-center justify-center gap-2 border-t px-4 py-3"
+    <Row
+      gap={2}
+      justify="center"
+      className="border-border border-t px-4 py-3"
       role="group"
       aria-label={t('arena.verdictLabel')}
     >
@@ -112,6 +115,6 @@ export function ArenaVerdictBar({
           {label}
         </Button>
       ))}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/blocked-notice.tsx b/services/platform/app/features/chat/components/blocked-notice.tsx
index ff9a87c13a..25288a5553 100644
--- a/services/platform/app/features/chat/components/blocked-notice.tsx
+++ b/services/platform/app/features/chat/components/blocked-notice.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { ShieldAlert } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -20,16 +21,18 @@ export interface BlockedReasonProps {
 export function BlockedNotice(_props: BlockedReasonProps) {
   const { t } = useT('chat');
   return (
-    <div
+    <Row
       role="status"
       aria-live="polite"
-      className="text-muted-foreground flex items-start gap-2 text-sm"
+      gap={2}
+      align="start"
+      className="text-muted-foreground text-sm"
     >
       <ShieldAlert
         className="text-muted-foreground mt-0.5 size-4 shrink-0"
         aria-hidden
       />
       <span>{t('blockedNotice.body')}</span>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/branch-navigator.tsx b/services/platform/app/features/chat/components/branch-navigator.tsx
index 8fd70e2e3e..154b85c5e5 100644
--- a/services/platform/app/features/chat/components/branch-navigator.tsx
+++ b/services/platform/app/features/chat/components/branch-navigator.tsx
@@ -103,7 +103,7 @@ export const BranchNavigator = memo(function BranchNavigator({
         className="size-6"
         onClick={handlePrev}
         disabled={currentIndex <= 0}
-        aria-label={t('branchNavigator.previous')}
+        title={t('branchNavigator.previous')}
       >
         <ChevronLeft className="size-3.5" />
       </Button>
@@ -116,7 +116,7 @@ export const BranchNavigator = memo(function BranchNavigator({
         className="size-6"
         onClick={handleNext}
         disabled={currentIndex >= totalCount - 1}
-        aria-label={t('branchNavigator.next')}
+        title={t('branchNavigator.next')}
       >
         <ChevronRight className="size-3.5" />
       </Button>
diff --git a/services/platform/app/features/chat/components/chat-error-display.tsx b/services/platform/app/features/chat/components/chat-error-display.tsx
index 042d759c6d..1efe819a76 100644
--- a/services/platform/app/features/chat/components/chat-error-display.tsx
+++ b/services/platform/app/features/chat/components/chat-error-display.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
+import { Row, Stack } from '@tale/ui/layout';
 import { RotateCcw, TriangleAlert } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -27,29 +28,33 @@ export function ChatErrorDisplay({ error, onRetry }: ChatErrorDisplayProps) {
   const sanitized = sanitizeChatError(error);
 
   return (
-    <div className="mt-3 flex flex-col gap-2" role="alert" aria-live="polite">
-      <div className="text-destructive flex items-center gap-2">
+    <Stack gap={2} className="mt-3" role="alert" aria-live="polite">
+      <Row gap={2} className="text-destructive">
         <TriangleAlert className="size-4 shrink-0" />
         <span className="text-sm font-medium">{tChat('errorGenerating')}</span>
-      </div>
+      </Row>
       <p className="text-muted-foreground text-[13px]">
-        {tChat(sanitized.i18nKey)}
+        {tChat(sanitized.i18nKey, sanitized.params)}
       </p>
-      {error && (
+      {sanitized.triedCount != null && (
+        <p className="text-muted-foreground/70 text-xs">
+          {tChat('errorTriedModels', { count: sanitized.triedCount })}
+        </p>
+      )}
+      {sanitized.rawMessage && (
         <CollapsibleDetails
           variant="compact"
           summary={tChat('errorDetailsSummary')}
-          open={sanitized.category === 'generic'}
+          open={sanitized.code === 'generic'}
         >
           <p className="text-muted-foreground mt-1 font-mono text-xs break-all whitespace-pre-wrap opacity-70">
-            {error}
+            {sanitized.rawMessage}
           </p>
         </CollapsibleDetails>
       )}
       {onRetry && (
         <Button
           variant="secondary"
-          size="sm"
           className="text-foreground w-fit gap-1.5 rounded-lg border-[#E5E7EB] bg-transparent px-3 py-1.5 text-[13px] font-medium"
           onClick={onRetry}
         >
@@ -57,6 +62,6 @@ export function ChatErrorDisplay({ error, onRetry }: ChatErrorDisplayProps) {
           {tChat('retryGeneration')}
         </Button>
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/chat-header.tsx b/services/platform/app/features/chat/components/chat-header.tsx
index f6c57a6c0b..0f258caf40 100644
--- a/services/platform/app/features/chat/components/chat-header.tsx
+++ b/services/platform/app/features/chat/components/chat-header.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuGroup } from '@tale/ui/dropdown-menu';
+import { Row } from '@tale/ui/layout';
 import {
   SearchCommand,
   type SearchCommandLabels,
@@ -14,8 +15,6 @@ import {
   Ellipsis,
   Search,
   Share,
-  Plus,
-  SquarePen,
 } from 'lucide-react';
 import { useEffect, useState, useCallback, useMemo } from 'react';
 
@@ -24,6 +23,7 @@ import { Sheet } from '@/app/components/ui/overlays/sheet';
 import { Tooltip } from '@/app/components/ui/overlays/tooltip';
 import { useChatLayout } from '@/app/features/chat/context/chat-layout-context';
 import { useFormatDate } from '@/app/hooks/use-format-date';
+import { useIsMac } from '@/app/hooks/use-is-mac';
 import { useOptionalTeamFilter } from '@/app/hooks/use-team-filter';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
@@ -39,12 +39,12 @@ interface ChatHeaderProps {
 
 export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
   const navigate = useNavigate();
-  const { isHistoryOpen, setIsHistoryOpen, clearChatState } = useChatLayout();
+  const { isHistoryOpen, setIsHistoryOpen } = useChatLayout();
   const [isSearchOpen, setIsSearchOpen] = useState(false);
   const [isMobileHistoryOpen, setIsMobileHistoryOpen] = useState(false);
   const [isShareDialogOpen, setIsShareDialogOpen] = useState(false);
   const [isExportDialogOpen, setIsExportDialogOpen] = useState(false);
-  const [isMac, setIsMac] = useState(false);
+  const isMac = useIsMac();
 
   const { t: tChat } = useT('chat');
   const { t: tDialogs } = useT('dialogs');
@@ -86,19 +86,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
     [navigate, organizationId],
   );
 
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      const platform = (
-        navigator.platform ||
-        navigator.userAgent ||
-        ''
-      ).toLowerCase();
-      setIsMac(platform.includes('mac'));
-    }
-  }, []);
-
   const findShortcut = isMac ? '⌘ K' : 'CTRL + K';
-  const newChatShortcut = isMac ? '⌥ ⌘ N' : 'ALT + CTRL + N';
   const historyShortcut = isMac ? '⌘ H' : 'CTRL + H';
 
   const handleToggleSearch = useCallback(() => {
@@ -114,14 +102,6 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
     }
   }, [isHistoryOpen, setIsHistoryOpen]);
 
-  const handleNewChat = useCallback(() => {
-    clearChatState();
-    void navigate({
-      to: '/dashboard/$id/chat',
-      params: { id: organizationId },
-    });
-  }, [navigate, organizationId, clearChatState]);
-
   const handleChatSelect = useCallback(() => {
     setIsMobileHistoryOpen(false);
   }, []);
@@ -135,11 +115,6 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
         handleToggleSearch();
         return;
       }
-      if (isMod && e.altKey && e.code === 'KeyN') {
-        e.preventDefault();
-        e.stopPropagation();
-        handleNewChat();
-      }
       if (isMod && !e.shiftKey && (e.key === 'h' || e.key === 'H')) {
         e.preventDefault();
         e.stopPropagation();
@@ -148,7 +123,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
     };
     window.addEventListener('keydown', onKeyDown, true);
     return () => window.removeEventListener('keydown', onKeyDown, true);
-  }, [isMac, handleToggleSearch, handleNewChat, handleToggleHistory]);
+  }, [isMac, handleToggleSearch, handleToggleHistory]);
 
   // The per-thread voice toggle moved to the composer (next to dictation),
   // so the header dropdown now only carries the export action.
@@ -185,7 +160,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
         />
       </Sheet>
 
-      <div className="border-border bg-background/95 hidden h-13 items-center gap-1 border-b px-5 backdrop-blur-xs md:flex">
+      <div className="border-border bg-background/95 hidden h-13 items-center border-b px-4 backdrop-blur-xs md:flex">
         <Tooltip
           content={
             <>
@@ -205,7 +180,14 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
             aria-label={
               isHistoryOpen ? tChat('hideHistory') : tChat('showHistory')
             }
-            className={cn(isHistoryOpen && 'bg-accent text-accent-foreground')}
+            // Negative margin pulls the icon's glyph to the header's content
+            // edge so it lines up with page titles (which start at px-4), since
+            // a ghost icon button carries its own p-2 inset. Same idiom as the
+            // onboarding wizard's leading Back button.
+            className={cn(
+              '-ml-2',
+              isHistoryOpen && 'bg-accent text-accent-foreground',
+            )}
           >
             <MessagesSquare
               className={cn(
@@ -238,34 +220,11 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
           </Button>
         </Tooltip>
 
-        <Tooltip
-          content={
-            <>
-              {tChat('newChat')}
-              <span className="text-muted bg-muted-foreground/60 ml-3 rounded-sm px-1 py-0.5 text-xs">
-                {newChatShortcut}
-              </span>
-            </>
-          }
-          side="bottom"
-          contentClassName="py-1.5"
-        >
-          <Button
-            size="icon"
-            variant="ghost"
-            onClick={handleNewChat}
-            aria-label={tChat('newChat')}
-          >
-            <SquarePen className={baseIconClasses} />
-          </Button>
-        </Tooltip>
-
         {threadId && (
           <>
             <div className="flex-1" />
             <Button
               variant="ghost"
-              size="sm"
               onClick={() => setIsShareDialogOpen(true)}
               aria-label={tChat('share.button')}
               className="text-muted-foreground gap-1.5"
@@ -291,12 +250,12 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
       </div>
 
       <AdaptiveHeaderRoot className="md:hidden">
-        <div className="flex flex-1 justify-start">
+        <Row gap={0} align="stretch" className="flex-1">
           <Button
             size="icon"
             variant="ghost"
             onClick={handleToggleHistory}
-            aria-label={
+            title={
               isMobileHistoryOpen ? tChat('hideHistory') : tChat('showHistory')
             }
           >
@@ -311,7 +270,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
             size="icon"
             variant="ghost"
             onClick={handleToggleSearch}
-            aria-label={tChat('searchChat')}
+            title={tChat('searchChat')}
           >
             <Search className={baseIconClasses} />
           </Button>
@@ -321,7 +280,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
                 size="icon"
                 variant="ghost"
                 onClick={() => setIsShareDialogOpen(true)}
-                aria-label={tChat('share.button')}
+                title={tChat('share.button')}
               >
                 <Share className={baseIconClasses} />
               </Button>
@@ -340,15 +299,7 @@ export function ChatHeader({ organizationId, threadId }: ChatHeaderProps) {
               />
             </>
           )}
-          <Button
-            size="icon"
-            variant="ghost"
-            onClick={handleNewChat}
-            aria-label={tChat('newChat')}
-          >
-            <Plus className={baseIconClasses} />
-          </Button>
-        </div>
+        </Row>
       </AdaptiveHeaderRoot>
 
       <SearchCommand
diff --git a/services/platform/app/features/chat/components/chat-history-dnd.tsx b/services/platform/app/features/chat/components/chat-history-dnd.tsx
index 5bc417b9fa..d04078424e 100644
--- a/services/platform/app/features/chat/components/chat-history-dnd.tsx
+++ b/services/platform/app/features/chat/components/chat-history-dnd.tsx
@@ -20,6 +20,7 @@ import {
   type MeasuringConfiguration,
 } from '@dnd-kit/core';
 import { CSS } from '@dnd-kit/utilities';
+import { Row } from '@tale/ui/layout';
 import {
   type ReactNode,
   createContext,
@@ -204,9 +205,12 @@ export function ChatDndProvider({ children }: { children: ReactNode }) {
  */
 function ChatDragPreview({ title }: { title: string }) {
   return (
-    <div className="bg-popover text-popover-foreground border-border flex max-w-[15rem] rotate-2 cursor-grabbing items-center gap-2 rounded-md border px-2 py-1.5 text-sm shadow-xl">
+    <Row
+      gap={2}
+      className="bg-popover text-popover-foreground border-border max-w-[15rem] rotate-2 cursor-grabbing rounded-md border px-2 py-1.5 text-sm shadow-xl"
+    >
       <span className="truncate">{title}</span>
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/chat-history-sidebar.tsx b/services/platform/app/features/chat/components/chat-history-sidebar.tsx
index c8a1c65a32..2584ef5ae0 100644
--- a/services/platform/app/features/chat/components/chat-history-sidebar.tsx
+++ b/services/platform/app/features/chat/components/chat-history-sidebar.tsx
@@ -2,7 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuGroup } from '@tale/ui/dropdown-menu';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -520,8 +520,8 @@ export function ChatHistorySidebar({
       )}
       {...restProps}
     >
-      <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">
-        <section className="flex flex-col">
+      <Stack gap={0} className="min-h-0 flex-1 overflow-y-auto">
+        <Stack as="section" gap={0}>
           {showSkeleton ? (
             // Mirror the loaded sidebar geometry (Projects header + folder rows,
             // Chats header + chat rows) so the reveal is a mask swap, not a
@@ -532,11 +532,11 @@ export function ChatHistorySidebar({
             // or be ignored by the mask (fullWidth).
             <Skeletonize loading>
               <Stack gap={1} className="pb-2">
-                <div className="flex h-7 items-center px-2">
+                <Row gap={0} className="h-7 px-2">
                   <SkeletonBox>
                     <div className="h-3 w-16" />
                   </SkeletonBox>
-                </div>
+                </Row>
                 {Array.from({ length: 2 }).map((_, i) => (
                   <div
                     key={`project-${i}`}
@@ -559,22 +559,26 @@ export function ChatHistorySidebar({
                     </div>
                   </div>
                 ))}
-                <div className="border-border mt-1.5 flex h-7 items-center border-t px-2 pt-2.5">
+                <Row
+                  gap={0}
+                  className="border-border mt-1.5 h-7 border-t px-2 pt-2.5"
+                >
                   <SkeletonBox>
                     <div className="h-3 w-12" />
                   </SkeletonBox>
-                </div>
+                </Row>
                 {Array.from({ length: 6 }).map((_, i) => (
-                  <div
+                  <Row
                     key={`chat-${i}`}
-                    className="flex min-h-[1.5rem] items-center px-2 py-1.5"
+                    gap={0}
+                    className="min-h-[1.5rem] px-2 py-1.5"
                   >
                     <div style={{ width: `${82 - (i % 4) * 14}%` }}>
                       <SkeletonBox fullWidth>
                         <div className="h-3.5" />
                       </SkeletonBox>
                     </div>
-                  </div>
+                  </Row>
                 ))}
               </Stack>
             </Skeletonize>
@@ -584,7 +588,12 @@ export function ChatHistorySidebar({
                 label={t('projectsSection')}
                 action={newProjectButton}
               />
-              <div className="flex flex-col items-center justify-center gap-1 px-6 py-10 text-center">
+              <Stack
+                gap={1}
+                align="center"
+                justify="center"
+                className="px-6 py-10 text-center"
+              >
                 <MessageSquareDashedIcon
                   className="text-muted-foreground/60 mb-1 size-8"
                   aria-hidden
@@ -599,7 +608,7 @@ export function ChatHistorySidebar({
                 <Text as="div" variant="caption" className="text-nowrap">
                   {t('history.emptySubtitle')}
                 </Text>
-              </div>
+              </Stack>
             </>
           ) : (
             <ChatRowContext.Provider value={rowContext}>
@@ -655,8 +664,8 @@ export function ChatHistorySidebar({
               </ChatDndProvider>
             </ChatRowContext.Provider>
           )}
-        </section>
-      </div>
+        </Stack>
+      </Stack>
 
       {archivedChats && archivedChats.length > 0 && (
         <section className="border-border mt-2 shrink-0 border-t pt-2">
@@ -699,9 +708,10 @@ export function ChatHistorySidebar({
               className="max-h-64 min-h-0 overflow-y-auto pt-1 pb-2"
             >
               {archivedChats.map((chat) => (
-                <div
+                <Row
                   key={chat._id}
-                  className="group hover:bg-accent hover:text-accent-foreground relative flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors"
+                  gap={2}
+                  className="group hover:bg-accent hover:text-accent-foreground relative rounded-md px-2 py-1.5 text-sm transition-colors"
                 >
                   <button
                     type="button"
@@ -727,7 +737,7 @@ export function ChatHistorySidebar({
                       isArchived
                     />
                   </div>
-                </div>
+                </Row>
               ))}
               {canLoadMoreArchived && (
                 <button
@@ -856,7 +866,7 @@ function ProjectFolder({
 
   return (
     <div ref={setNodeRef} className={dropZoneClassName(isOver)}>
-      <div className="group relative flex items-center">
+      <Row gap={0} className="group relative">
         <button
           type="button"
           onClick={() => onSetCollapsed(!collapsed)}
@@ -909,7 +919,7 @@ function ProjectFolder({
             items={menuItems}
           />
         </div>
-      </div>
+      </Row>
       <div
         className={cn(
           'grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
diff --git a/services/platform/app/features/chat/components/chat-input.tsx b/services/platform/app/features/chat/components/chat-input.tsx
index 47dad3dbc4..505e25568c 100644
--- a/services/platform/app/features/chat/components/chat-input.tsx
+++ b/services/platform/app/features/chat/components/chat-input.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { ArrowUp, CircleStop } from 'lucide-react';
 import {
@@ -36,13 +36,24 @@ import {
   type KbMention,
   type MentionTrigger,
 } from '../hooks/use-kb-mentions';
-import { captureScreenshot } from '../utils/capture-screenshot';
+import { useVideoUrlIngest } from '../hooks/use-video-url-ingest';
 import { normalizeCopiedText } from '../utils/normalize-copied-text';
 import { AgentSelector } from './agent-selector';
 import { useArenaModeOptional } from './arena/arena-mode-context';
 import { ArenaModelSelector } from './arena/arena-model-selector';
 import { AttachmentTray } from './chat-input/attachment-tray';
 import { toBcp47 } from './chat-input/locale-defaults';
+import {
+  PasteImageOverlay,
+  type PasteImageChip,
+} from './chat-input/paste-image-overlay';
+import {
+  buildMarkerToken,
+  collapseMarkerSpaces,
+  nextPasteImageId,
+  pastedImageIdFromName,
+  tokenSpans,
+} from './chat-input/paste-image-tokens';
 import { ComposerCapabilityPills } from './composer-capability-pills';
 import { ComposerModeMenu } from './composer-mode-menu';
 import {
@@ -185,6 +196,23 @@ interface ChatInputProps extends Omit<
   variant?: 'full' | 'assistant';
 }
 
+/**
+ * Media-processing states that block sending, in send-button-tooltip
+ * precedence order; each maps to its `chat` i18n tooltip key.
+ */
+type MediaBlockReason =
+  | 'transcribing'
+  | 'processingVideo'
+  | 'failedVideo'
+  | 'failedAudio';
+
+const MEDIA_BLOCK_TOOLTIP_KEY: Record<MediaBlockReason, string> = {
+  transcribing: 'transcription.inProgressTooltip',
+  processingVideo: 'videoLink.chip.inProgressTooltip',
+  failedVideo: 'videoLink.chip.failedSendBlockedTooltip',
+  failedAudio: 'transcription.failedSendBlockedTooltip',
+};
+
 export function ChatInput({
   value = '',
   onChange,
@@ -259,14 +287,27 @@ export function ChatInput({
   // path so we don't mutate the textarea while an IME commit is in
   // flight (round-2 V10 / HIGH #19).
   const isComposingRef = useRef(false);
-  // Set as soon as a paste begins ingest; cleared in `.finally`. The
-  // send-gate ORs this in so a paste-then-Enter race can't bypass the
-  // chip rendering (chip query won't show the row until the mutation
-  // round-trip lands, but `ingestVideoUrlsFromText` runs fire-and-forget
-  // so without this flag the gate has nothing to watch) — round-2 V10 /
-  // HIGH #23.
-  const pasteIngestInFlightRef = useRef(false);
-  const [pasteIngestPending, setPasteIngestPending] = useState(false);
+  // A pasted/dropped video URL ingests fire-and-forget; `pasteIngestPending`
+  // lets the send-gate block a paste-then-Enter race until the chip row lands
+  // (round-2 V10 / HIGH #23). Shared by the paste + drag-drop handlers below.
+  const { pending: pasteIngestPending, ingest: ingestVideoUrls } =
+    useVideoUrlIngest(ingestVideoUrlsFromText, organizationId, i18n.language);
+
+  // Single source of truth for the media-processing states that block send.
+  // `mediaBlockReason` names the active one (precedence order) for the send-
+  // button tooltip; `mediaBlocksSend` is the OR consumed by the send-gate and
+  // the disabled state. `pasteIngestPending` (blocks send, no tooltip) and
+  // `sendBlocked` (carries its own reason string) stay separate.
+  const mediaBlockReason: MediaBlockReason | null = isTranscribing
+    ? 'transcribing'
+    : isProcessingVideo
+      ? 'processingVideo'
+      : hasFailedVideoJobs
+        ? 'failedVideo'
+        : hasFailedAudioJobs
+          ? 'failedAudio'
+          : null;
+  const mediaBlocksSend = mediaBlockReason !== null;
   const [previewImage, setPreviewImage] = useState<{
     src: string;
     alt: string;
@@ -423,10 +464,7 @@ export function ChatInput({
       disabled ||
       isUploading ||
       isIndexing ||
-      isTranscribing ||
-      isProcessingVideo ||
-      hasFailedVideoJobs ||
-      hasFailedAudioJobs ||
+      mediaBlocksSend ||
       pasteIngestPending ||
       sendBlocked
     )
@@ -449,8 +487,10 @@ export function ChatInput({
       attachments.length > 0 ? clearAttachments() : undefined;
 
     // Prepend any staged quote as a markdown blockquote so the model sees
-    // the referenced passage above the user's message, then clear it.
-    const trimmed = value.trim();
+    // the referenced passage above the user's message, then clear it. The
+    // `[N]` markers ride along (positional reference for the agent); their
+    // reserve spaces collapse to one so the sent text stays clean.
+    const trimmed = collapseMarkerSpaces(value).trim();
     const messageToSend = quotedText
       ? `> ${quotedText.replace(/\n/g, '\n> ')}\n\n${trimmed}`
       : trimmed;
@@ -471,28 +511,6 @@ export function ChatInput({
     onSendMessage(messageToSend, attachmentsToSend, kbRefsToSend);
   };
 
-  const screenshotSupported =
-    typeof navigator !== 'undefined' &&
-    !!navigator.mediaDevices?.getDisplayMedia;
-
-  const handleTakeScreenshot = useCallback(async () => {
-    try {
-      const file = await captureScreenshot();
-      if (file) await uploadFiles([file]);
-    } catch (err) {
-      // The user dismissing the OS picker rejects with NotAllowed/Abort —
-      // treat as a silent cancel, surface anything else.
-      if (
-        err instanceof DOMException &&
-        (err.name === 'NotAllowedError' || err.name === 'AbortError')
-      ) {
-        return;
-      }
-      console.error('[screenshot] capture failed', err);
-      toast({ title: tComposer('screenshotFailed'), variant: 'destructive' });
-    }
-  }, [uploadFiles, tComposer]);
-
   const imageAttachments = useMemo(
     () => attachments.filter((att) => att.fileType.startsWith('image/')),
     [attachments],
@@ -503,6 +521,106 @@ export function ChatInput({
     [attachments],
   );
 
+  // Chip data per image id, derived purely from the live attachments + uploads
+  // — the marker is independent of the image (deleting a `[N]` keeps the
+  // attachment, and vice-versa). An id present here means a `[N]` token refers
+  // to a real image, which also gates atomic marker deletion below.
+  const pasteChips = useMemo(() => {
+    const map = new Map<number, PasteImageChip>();
+    for (const id of uploadingFiles) {
+      const tokenId = pastedImageIdFromName(id);
+      if (tokenId !== null) map.set(tokenId, { status: 'uploading' });
+    }
+    for (const att of attachments) {
+      const tokenId = pastedImageIdFromName(att.fileName);
+      if (tokenId !== null && att.fileType.startsWith('image/')) {
+        map.set(tokenId, { status: 'ready', previewUrl: att.previewUrl });
+      }
+    }
+    return map;
+  }, [attachments, uploadingFiles]);
+
+  // Clicking an inline `[N]` chip opens the same preview dialog as its tray
+  // thumbnail (the chip mirrors the tray, it doesn't replace it).
+  const openPastedImage = useCallback(
+    (id: number) => {
+      const att = attachments.find(
+        (a) => pastedImageIdFromName(a.fileName) === id,
+      );
+      if (att?.previewUrl) {
+        setPreviewImage({ src: att.previewUrl, alt: att.fileName });
+      }
+    },
+    [attachments],
+  );
+
+  // Removing an image from the tray also strips its inline `[N]` marker, so a
+  // removed image never leaves an orphan token behind. (Deleting the marker
+  // alone keeps the image — see deletePastedTokenAtCaret.)
+  const handleRemoveAttachment = useCallback(
+    (fileId: Id<'_storage'>) => {
+      const att = attachments.find((a) => a.fileId === fileId);
+      const id = att ? pastedImageIdFromName(att.fileName) : null;
+      if (id !== null && onChange) {
+        const span = tokenSpans(value).find((s) => s.id === id);
+        if (span) {
+          let end = span.end;
+          while (value[end] === ' ') end += 1;
+          onChange(value.slice(0, span.start) + value.slice(end));
+        }
+      }
+      removeAttachment(fileId);
+    },
+    [attachments, value, onChange, removeAttachment],
+  );
+
+  // Insert `[N]` marker(s) (each with reserve spaces for the chip) at the
+  // caret. Shared by paste and the drag-from-tray drop below.
+  const insertMarkersAtCaret = (ids: number[]) => {
+    const textarea = textareaRef.current;
+    if (!textarea || !onChange || ids.length === 0) return;
+    const start = textarea.selectionStart ?? textarea.value.length;
+    const end = textarea.selectionEnd ?? textarea.value.length;
+    const before = textarea.value.slice(0, start);
+    const lead = before.length > 0 && !/\s$/.test(before) ? ' ' : '';
+    const tokenText = lead + ids.map(buildMarkerToken).join('');
+    textarea.setRangeText(tokenText, start, end, 'end');
+    onChange(textarea.value);
+  };
+
+  // Drag a tray image into the composer to drop its `[N]` marker. The tray
+  // thumbnail puts its id on the drag in this custom type; we move the caret to
+  // the drop point (best-effort) and insert the marker there.
+  const handleMarkerDragOver = (e: React.DragEvent) => {
+    if (e.dataTransfer.types.includes('application/x-tale-marker-id')) {
+      e.preventDefault();
+      e.stopPropagation(); // suppress the FileUpload drop overlay over the input
+    }
+  };
+  const handleMarkerDrop = (e: React.DragEvent) => {
+    const raw = e.dataTransfer.getData('application/x-tale-marker-id');
+    if (!raw) return; // not a marker drag — let the file DropZone handle it
+    const id = Number(raw);
+    if (!Number.isInteger(id)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const ta = textareaRef.current;
+    if (ta) {
+      const doc = document as Document & {
+        caretPositionFromPoint?: (
+          x: number,
+          y: number,
+        ) => { offsetNode: Node; offset: number } | null;
+      };
+      const pos = doc.caretPositionFromPoint?.(e.clientX, e.clientY);
+      if (pos && (pos.offsetNode === ta || ta.contains(pos.offsetNode))) {
+        ta.setSelectionRange(pos.offset, pos.offset);
+      }
+      ta.focus();
+    }
+    insertMarkersAtCaret([id]);
+  };
+
   const handleInputChange = (newValue: string) => {
     onChange?.(newValue);
     // Typing both opens and closes the `@` picker (caret-move events only
@@ -519,6 +637,41 @@ export function ChatInput({
     [value, onChange],
   );
 
+  // Treat a `[N]` marker as a single atomic unit when deleting: a plain
+  // Backspace at the end of `[1]` would otherwise erase only `]` and leave a
+  // dangling `[1`. When the caret sits inside/adjacent to a marker, wipe the
+  // whole token plus its reserve spaces. Deleting a marker only removes the
+  // marker — the image stays in the tray. Returns true when it handled the key.
+  const deletePastedTokenAtCaret = (
+    e: React.KeyboardEvent,
+    direction: 'back' | 'forward',
+  ): boolean => {
+    if (pasteChips.size === 0) return false;
+    const ta = textareaRef.current;
+    if (
+      !ta ||
+      ta.selectionStart === null ||
+      ta.selectionStart !== ta.selectionEnd
+    ) {
+      return false;
+    }
+    const caret = ta.selectionStart;
+    const span = tokenSpans(ta.value).find(
+      (s) =>
+        pasteChips.has(s.id) &&
+        (direction === 'back'
+          ? s.start < caret && caret <= s.end
+          : s.start <= caret && caret < s.end),
+    );
+    if (!span) return false;
+    e.preventDefault();
+    let end = span.end;
+    while (ta.value[end] === ' ') end += 1; // consume the reserve spaces
+    ta.setRangeText('', span.start, end, 'end');
+    onChange?.(ta.value);
+    return true;
+  };
+
   const handleKeyDown = (e: React.KeyboardEvent) => {
     // IME composition guard. macOS Pinyin / Japanese Kotoeri commits a
     // candidate via Enter; without these checks the textarea swallows
@@ -564,6 +717,13 @@ export function ChatInput({
       }
     }
 
+    // Atomic marker deletion (runs before the textarea's default edit so a
+    // Backspace can't shave a `[1]` token down to a dangling `[1`).
+    if (!isComposing) {
+      if (e.key === 'Backspace' && deletePastedTokenAtCaret(e, 'back')) return;
+      if (e.key === 'Delete' && deletePastedTokenAtCaret(e, 'forward')) return;
+    }
+
     if (e.key !== 'Enter' || e.shiftKey) return;
     if (isComposing) return;
     e.preventDefault();
@@ -592,26 +752,40 @@ export function ChatInput({
     const items = e.clipboardData?.items;
     if (!items) return;
 
+    // Name each pasted image `[N].<ext>`, where N is one past the highest `[N]`
+    // already in the text — so numbering restarts at 1 once a send clears the
+    // composer and never collides with a token the user typed.
     const imageFiles: File[] = [];
+    const newImageIds: number[] = [];
+    let nextId = nextPasteImageId(textareaRef.current?.value ?? value);
     for (let i = 0; i < items.length; i++) {
       const item = items[i];
       if (item.type.startsWith('image/')) {
         const file = item.getAsFile();
         if (file) {
           const extension = item.type.split('/')[1] || 'png';
-          const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-          const renamedFile = new File(
-            [file],
-            `pasted-image-${timestamp}.${extension}`,
-            { type: file.type },
+          const id = nextId++;
+          newImageIds.push(id);
+          imageFiles.push(
+            new File([file], `[${id}].${extension}`, { type: file.type }),
           );
-          imageFiles.push(renamedFile);
         }
       }
     }
 
     if (imageFiles.length > 0) {
+      // A pasted image is represented by its `[N]` marker, inserted
+      // programmatically below. Clipboards frequently ship a text/alt or URL
+      // fallback ALONGSIDE the image bytes, so prevent the native text paste
+      // (and skip the text-normalize path) — otherwise that fallback inserts
+      // on top of the marker and the message double-ups.
+      e.preventDefault();
+      // Drop a `[N]` reference marker at the caret so the image has a position
+      // in the message; the overlay paints a thumbnail badge over it and the
+      // agent sees `[N]` in the prose next to the `[N].ext` attachment.
+      insertMarkersAtCaret(newImageIds);
       void uploadFiles(imageFiles);
+      return;
     }
 
     // Video-link detection. Read both text/plain and text/html (rich-
@@ -629,23 +803,7 @@ export function ChatInput({
         // double, some older email clients ship single).
         html.match(/href=["']([^"']+)["']/g)?.join(' ') ||
         '';
-      if (text) {
-        // Set the in-flight ref BEFORE awaiting the ingest so the send-
-        // gate sees the pending state on the very next render. Cleared
-        // in `.finally`. Without this, a user who pastes then hits
-        // Enter immediately would ship the message before the mutation
-        // round-trip lands and the chip query reflects the new row.
-        pasteIngestInFlightRef.current = true;
-        setPasteIngestPending(true);
-        void ingestVideoUrlsFromText(
-          text,
-          organizationId,
-          i18n.language,
-        ).finally(() => {
-          pasteIngestInFlightRef.current = false;
-          setPasteIngestPending(false);
-        });
-      }
+      ingestVideoUrls(text);
     }
 
     // Normalize the pasted text: collapse the blank-line stacks that copying
@@ -683,27 +841,7 @@ export function ChatInput({
       <FileUpload.DropZone
         className="relative flex h-full min-h-0 flex-1 flex-col"
         onFilesSelected={uploadFiles}
-        onTextDrop={
-          ingestVideoUrlsFromText
-            ? (text) => {
-                // Mirror the paste-handler gate so a drag-and-drop URL
-                // followed by an immediate Enter doesn't beat the chip
-                // into existence — without this, the send-gate doesn't
-                // know an ingest is in-flight and the agent receives
-                // the raw URL instead of the transcript.
-                pasteIngestInFlightRef.current = true;
-                setPasteIngestPending(true);
-                void ingestVideoUrlsFromText(
-                  text,
-                  organizationId,
-                  i18n.language,
-                ).finally(() => {
-                  pasteIngestInFlightRef.current = false;
-                  setPasteIngestPending(false);
-                });
-              }
-            : undefined
-        }
+        onTextDrop={ingestVideoUrlsFromText ? ingestVideoUrls : undefined}
         clickable={false}
         disabled={attachDisabled || fileUploadDisabled}
       >
@@ -718,7 +856,10 @@ export function ChatInput({
         />
 
         {/* Soft top shadow lifts the composer off the conversation above it. */}
-        <div className="border-border sm:border-muted-foreground/50 relative mb-2 flex flex-col gap-2 rounded-xl border px-3 pt-3 shadow-[0_-6px_16px_-8px_rgb(0_0_0/0.15)] sm:rounded-2xl sm:px-5 sm:pt-4 dark:shadow-[0_-6px_16px_-8px_rgb(0_0_0/0.5)]">
+        <Stack
+          gap={2}
+          className="border-border sm:border-muted-foreground/50 relative mb-2 rounded-xl border px-3 pt-3 shadow-[0_-6px_16px_-8px_rgb(0_0_0/0.15)] sm:rounded-2xl sm:px-5 sm:pt-4 dark:shadow-[0_-6px_16px_-8px_rgb(0_0_0/0.5)]"
+        >
           {videoLinkJobs.length > 0 && (
             <HStack gap={1} wrap className="mb-2">
               {videoLinkJobs.map((job) => (
@@ -787,7 +928,7 @@ export function ChatInput({
               transcriptionStatuses={transcriptionStatuses}
               indexingStatuses={indexingStatuses}
               retryAudioTranscription={retryAudioTranscription}
-              removeAttachment={removeAttachment}
+              removeAttachment={handleRemoveAttachment}
               onPreviewImage={setPreviewImage}
               onPreviewTranscript={setPreviewTranscript}
             />
@@ -823,6 +964,8 @@ export function ChatInput({
               onFocus={onComposerActivate}
               onKeyDown={handleKeyDown}
               onPaste={handlePaste}
+              onDragOver={handleMarkerDragOver}
+              onDrop={handleMarkerDrop}
               // Caret moves (clicks, arrow keys) only update/close an open
               // mention picker — typing is what opens it (handleInputChange).
               onSelect={() => updateMentionTrigger(true)}
@@ -851,6 +994,12 @@ export function ChatInput({
                   : undefined
               }
             />
+            <PasteImageOverlay
+              textareaRef={textareaRef}
+              value={value}
+              chips={pasteChips}
+              onOpen={openPastedImage}
+            />
             {value.length === 0 && !inputDisabled && (
               <Text
                 as="div"
@@ -897,11 +1046,6 @@ export function ChatInput({
                 organizationId={organizationId}
                 threadId={threadId}
                 onAttachFile={() => fileInputRef.current?.click()}
-                onTakeScreenshot={
-                  screenshotSupported && !fileUploadDisabled
-                    ? () => void handleTakeScreenshot()
-                    : undefined
-                }
                 fileUploadDisabled={fileUploadDisabled}
                 disabled={attachDisabled}
               />
@@ -976,24 +1120,15 @@ export function ChatInput({
                       inputDisabled ||
                       isUploading ||
                       isIndexing ||
-                      isTranscribing ||
-                      isProcessingVideo ||
-                      hasFailedVideoJobs ||
-                      hasFailedAudioJobs ||
+                      mediaBlocksSend ||
                       pasteIngestPending ||
                       sendBlocked;
                 const tooltipContent =
-                  isTranscribing && !isLoading
-                    ? tChat('transcription.inProgressTooltip')
-                    : isProcessingVideo && !isLoading
-                      ? tChat('videoLink.chip.inProgressTooltip')
-                      : hasFailedVideoJobs && !isLoading
-                        ? tChat('videoLink.chip.failedSendBlockedTooltip')
-                        : hasFailedAudioJobs && !isLoading
-                          ? tChat('transcription.failedSendBlockedTooltip')
-                          : sendBlocked && sendBlockedReason && !isLoading
-                            ? sendBlockedReason
-                            : '';
+                  !isLoading && mediaBlockReason
+                    ? tChat(MEDIA_BLOCK_TOOLTIP_KEY[mediaBlockReason])
+                    : sendBlocked && sendBlockedReason && !isLoading
+                      ? sendBlockedReason
+                      : '';
                 // Native `disabled` swallows pointer events on
                 // Chromium/WebKit, so the Tooltip trigger never fires
                 // when the button is in exactly the states the tooltip
@@ -1063,7 +1198,7 @@ export function ChatInput({
               })()}
             </HStack>
           </HStack>
-        </div>
+        </Stack>
       </FileUpload.DropZone>
 
       <DataNoticeFooter organizationId={organizationId} className="pt-1 pb-1" />
diff --git a/services/platform/app/features/chat/components/chat-input/attachment-tray.tsx b/services/platform/app/features/chat/components/chat-input/attachment-tray.tsx
index 314ad738f1..e8f7dba873 100644
--- a/services/platform/app/features/chat/components/chat-input/attachment-tray.tsx
+++ b/services/platform/app/features/chat/components/chat-input/attachment-tray.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { HStack, VStack } from '@tale/ui/layout';
+import { HStack, Row, VStack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Eye, Loader, RotateCcw, X } from 'lucide-react';
 
@@ -17,6 +17,7 @@ import {
   type IndexingStatusInfo,
   type TranscriptionStatusInfo,
 } from './attachment-status-label';
+import { pastedImageIdFromName } from './paste-image-tokens';
 
 interface TranscriptPreview {
   fileName: string;
@@ -66,9 +67,10 @@ export function AttachmentTray({
     <HStack gap={1} wrap className="mb-2">
       {kbMentionsEnabled &&
         kbMentions?.map((mention) => (
-          <div
+          <Row
             key={mention.documentId}
-            className="bg-muted group relative flex max-w-[280px] items-center gap-3 rounded-lg px-3 py-2"
+            gap={3}
+            className="bg-muted group relative max-w-[280px] rounded-lg px-3 py-2"
           >
             <DocumentIcon
               fileName={
@@ -100,49 +102,78 @@ export function AttachmentTray({
             >
               <X className="text-muted-foreground size-3" />
             </button>
-          </div>
+          </Row>
         ))}
-      {imageAttachments.map((attachment) => (
-        <div
-          key={attachment.fileId}
-          className="ring-border group relative size-9 overflow-hidden rounded-lg ring-1"
-        >
-          <button
-            type="button"
-            aria-label={tChat('viewImage')}
-            onClick={() =>
-              attachment.previewUrl &&
-              onPreviewImage({
-                src: attachment.previewUrl,
-                alt: attachment.fileName,
-              })
+      {imageAttachments.map((attachment) => {
+        // Pasted images carry an inline `[N]` marker in the message; show the
+        // same index here so the tray thumbnail and the marker correlate.
+        const pasteIndex = pastedImageIdFromName(attachment.fileName);
+        return (
+          <div
+            key={attachment.fileId}
+            // Drag an image into the composer to drop its `[N]` marker (the
+            // composer reads this id on drop). Only images with a marker id are
+            // draggable.
+            draggable={pasteIndex !== null}
+            onDragStart={
+              pasteIndex !== null
+                ? (e) => {
+                    e.dataTransfer.setData(
+                      'application/x-tale-marker-id',
+                      String(pasteIndex),
+                    );
+                    e.dataTransfer.effectAllowed = 'copy';
+                  }
+                : undefined
             }
-            className="bg-muted focus:ring-ring size-full cursor-pointer transition-opacity hover:opacity-90 focus:ring-2 focus:ring-offset-2 focus:outline-none"
+            className="ring-border group relative size-9 overflow-hidden rounded-lg ring-1"
           >
-            {attachment.previewUrl ? (
-              <img
-                src={attachment.previewUrl}
-                alt={attachment.fileName}
-                className="size-full object-cover"
-              />
-            ) : (
-              <div className="flex size-full items-center justify-center bg-gradient-to-br from-blue-100 to-blue-200">
-                <span className="text-xs text-blue-600">
-                  {tChat('fileTypes.image')}
-                </span>
-              </div>
+            <button
+              type="button"
+              aria-label={tChat('viewImage')}
+              onClick={() =>
+                attachment.previewUrl &&
+                onPreviewImage({
+                  src: attachment.previewUrl,
+                  alt: attachment.fileName,
+                })
+              }
+              className="bg-muted focus:ring-ring size-full cursor-pointer transition-opacity hover:opacity-90 focus:ring-2 focus:ring-offset-2 focus:outline-none"
+            >
+              {attachment.previewUrl ? (
+                <img
+                  src={attachment.previewUrl}
+                  alt={attachment.fileName}
+                  className="size-full object-cover"
+                />
+              ) : (
+                <Row
+                  gap={0}
+                  justify="center"
+                  className="size-full bg-linear-to-br from-blue-100 to-blue-200"
+                >
+                  <span className="text-xs text-blue-600">
+                    {tChat('fileTypes.image')}
+                  </span>
+                </Row>
+              )}
+            </button>
+            {pasteIndex !== null && (
+              <span className="pointer-events-none absolute right-0 bottom-0 rounded-tl-[4px] bg-black/70 px-1 text-[10px] leading-[1.4] font-semibold text-white tabular-nums">
+                {pasteIndex}.
+              </span>
             )}
-          </button>
-          <button
-            type="button"
-            aria-label={tChat('removeAttachment')}
-            onClick={() => removeAttachment(attachment.fileId)}
-            className="bg-background absolute top-0.5 right-0.5 flex size-5 items-center justify-center rounded-full opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
-          >
-            <X className="text-muted-foreground size-3" />
-          </button>
-        </div>
-      ))}
+            <button
+              type="button"
+              aria-label={tChat('removeAttachment')}
+              onClick={() => removeAttachment(attachment.fileId)}
+              className="bg-background absolute top-0.5 right-0.5 flex size-5 items-center justify-center rounded-full opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
+            >
+              <X className="text-muted-foreground size-3" />
+            </button>
+          </div>
+        );
+      })}
 
       {fileAttachments.map((attachment) => {
         const audioInfo = isAudioOrVideo(attachment.fileType)
@@ -152,9 +183,10 @@ export function AttachmentTray({
           audioInfo?.status === 'completed' && !!audioInfo.transcript;
 
         return (
-          <div
+          <Row
             key={attachment.fileId}
-            className="bg-muted group relative flex max-w-[280px] items-center gap-3 rounded-lg px-3 py-2"
+            gap={3}
+            className="bg-muted group relative max-w-[280px] rounded-lg px-3 py-2"
           >
             <DocumentIcon fileName={attachment.fileName} />
             <VStack className="min-w-0 flex-1 gap-1">
@@ -209,19 +241,21 @@ export function AttachmentTray({
                 <RotateCcw className="size-3" />
               </button>
             )}
-          </div>
+          </Row>
         );
       })}
 
       {uploadingFiles.map((fileId) => (
-        <div
+        <Row
           key={fileId}
           role="status"
           aria-label={tChat('uploadingFile')}
-          className="border-border bg-muted flex size-9 items-center justify-center overflow-hidden rounded-lg border"
+          gap={0}
+          justify="center"
+          className="border-border bg-muted size-9 overflow-hidden rounded-lg border"
         >
           <Loader className="text-muted-foreground size-4 animate-spin" />
-        </div>
+        </Row>
       ))}
     </HStack>
   );
diff --git a/services/platform/app/features/chat/components/chat-input/paste-image-overlay.browser.test.tsx b/services/platform/app/features/chat/components/chat-input/paste-image-overlay.browser.test.tsx
new file mode 100644
index 0000000000..94da71598b
--- /dev/null
+++ b/services/platform/app/features/chat/components/chat-input/paste-image-overlay.browser.test.tsx
@@ -0,0 +1,120 @@
+import { waitFor } from '@testing-library/react';
+import { type CSSProperties, useRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { render } from '@/tests/utils/render';
+
+import { PasteImageOverlay, type PasteImageChip } from './paste-image-overlay';
+
+/**
+ * REAL Chromium (project `browser`) test. The overlay positions its chips by
+ * mirroring the textarea text into an off-screen `<div>` and reading each
+ * token span's `offsetLeft/Top/Width/Height` — geometry jsdom fakes as 0, so
+ * this needs real layout, hence the browser tier. Verifies the end-to-end
+ * pipeline: a `[N]` token in the textarea gets a thumbnail/spinner chip painted
+ * over it at a real position, and tokens without chip data are left alone.
+ */
+
+// Mirrors the composer textarea's box: zero padding/border so the overlay's
+// "assumes zero padding" measurement holds.
+const TEXTAREA_STYLE: CSSProperties = {
+  minHeight: 72,
+  width: 320,
+  padding: 0,
+  border: 0,
+  margin: 0,
+  font: '16px/1.5 sans-serif',
+  resize: 'none',
+  boxSizing: 'border-box',
+};
+
+// 1×1 transparent PNG — a valid <img> src so the "ready" chip renders an image.
+const PIXEL =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M8AAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
+
+function Harness({
+  value,
+  chips,
+  onOpen = vi.fn(),
+}: {
+  value: string;
+  chips: Map<number, PasteImageChip>;
+  onOpen?: (id: number) => void;
+}) {
+  const ref = useRef<HTMLTextAreaElement | null>(null);
+  return (
+    <div style={{ position: 'relative', width: 320 }}>
+      <textarea ref={ref} value={value} readOnly style={TEXTAREA_STYLE} />
+      <PasteImageOverlay
+        textareaRef={ref}
+        value={value}
+        chips={chips}
+        onOpen={onOpen}
+      />
+    </div>
+  );
+}
+
+function chipEls(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('[data-token-id]'));
+}
+
+describe('PasteImageOverlay (real browser)', () => {
+  it('paints a positioned chip over each pasted token and skips plain tokens', async () => {
+    const chips = new Map<number, PasteImageChip>([
+      [1, { status: 'ready', previewUrl: PIXEL }],
+      [2, { status: 'uploading' }],
+    ]);
+    // `[3]` has no chip data (e.g. the user typed it) — must stay plain text.
+    const { container } = render(
+      <Harness value="see [1] and [2] not [3]" chips={chips} />,
+    );
+
+    await waitFor(() => expect(chipEls(container)).toHaveLength(2));
+
+    const byId = new Map(
+      chipEls(container).map((el) => [el.getAttribute('data-token-id'), el]),
+    );
+    const chip1 = byId.get('1');
+    const chip2 = byId.get('2');
+    if (!chip1 || !chip2) throw new Error('expected chips for tokens 1 and 2');
+    expect(byId.has('3')).toBe(false);
+
+    // Ready chip shows the uploaded thumbnail + its id; uploading chip shows a
+    // spinner and no image.
+    expect(chip1.querySelector('img')).toBeTruthy();
+    expect(chip1.textContent).toContain('1');
+    expect(chip2.querySelector('img')).toBeNull();
+    expect(chip2.querySelector('svg')).toBeTruthy();
+
+    // Real geometry: both chips have a measured box, and `[2]` sits to the
+    // right of `[1]` on the same line (they fit in 320px).
+    const r1 = chip1.getBoundingClientRect();
+    const r2 = chip2.getBoundingClientRect();
+    expect(r1.width).toBeGreaterThan(0);
+    expect(r1.height).toBeGreaterThan(0);
+    expect(r2.left).toBeGreaterThan(r1.left);
+  });
+
+  it('opens the preview when a ready chip is clicked', async () => {
+    const onOpen = vi.fn();
+    const { container, user } = render(
+      <Harness
+        value="look at [1]"
+        chips={new Map([[1, { status: 'ready', previewUrl: PIXEL }]])}
+        onOpen={onOpen}
+      />,
+    );
+
+    await waitFor(() => expect(chipEls(container)).toHaveLength(1));
+    await user.click(chipEls(container)[0]);
+    expect(onOpen).toHaveBeenCalledWith(1);
+  });
+
+  it('renders nothing when there are no chips', () => {
+    const { container } = render(
+      <Harness value="just text [1]" chips={new Map()} />,
+    );
+    expect(chipEls(container)).toHaveLength(0);
+  });
+});
diff --git a/services/platform/app/features/chat/components/chat-input/paste-image-overlay.tsx b/services/platform/app/features/chat/components/chat-input/paste-image-overlay.tsx
new file mode 100644
index 0000000000..102425a8e4
--- /dev/null
+++ b/services/platform/app/features/chat/components/chat-input/paste-image-overlay.tsx
@@ -0,0 +1,122 @@
+'use client';
+
+import { Loader } from 'lucide-react';
+import { memo, type RefObject } from 'react';
+
+import { Tooltip } from '@/app/components/ui/overlays/tooltip';
+import { useT } from '@/lib/i18n/client';
+
+import { useTextareaTokenRects } from '../../hooks/use-textarea-token-rects';
+
+export interface PasteImageChip {
+  status: 'ready' | 'uploading';
+  previewUrl?: string;
+}
+
+interface PasteImageOverlayProps {
+  textareaRef: RefObject<HTMLTextAreaElement | null>;
+  value: string;
+  /** Chip data keyed by the `[N]` token id. */
+  chips: Map<number, PasteImageChip>;
+  /** Open the full-size preview for a pasted image (clicked chip). */
+  onOpen: (id: number) => void;
+}
+
+/**
+ * Paints a small rectangle badge — a square image thumbnail with the marker
+ * index (`1.`) to its right — over each `[N]` token in the composer textarea.
+ * Clicking opens the preview. Each badge is clamped to the footprint the token
+ * + its reserve spaces occupy in the text (`useTextareaTokenRects` measures
+ * `[N]` plus trailing spaces), so it never overlaps the following words. The
+ * wrapper is `pointer-events-none`; only the badge button is interactive, so
+ * text editing passes straight through. Tokens without chip data (e.g. a `[5]`
+ * the user typed) are left as plain text.
+ */
+export const PasteImageOverlay = memo(function PasteImageOverlay({
+  textareaRef,
+  value,
+  chips,
+  onOpen,
+}: PasteImageOverlayProps) {
+  const { t } = useT('chat');
+  const active = chips.size > 0;
+  const layout = useTextareaTokenRects(textareaRef, value, active);
+  if (!active || !layout) return null;
+
+  return (
+    <div
+      className="pointer-events-none absolute overflow-hidden"
+      style={{
+        left: layout.layer.left,
+        top: layout.layer.top,
+        width: layout.layer.width,
+        height: layout.layer.height,
+      }}
+    >
+      {layout.tokens.map((token, index) => {
+        const chip = chips.get(token.id);
+        if (!chip) return null;
+        // Clamp to the token + reserve-spaces footprint so the rectangle badge
+        // can't bleed over following text; the badge sizes to its content and
+        // is clipped if the footprint is narrower.
+        const footprint = {
+          left: token.left,
+          top: token.top,
+          width: token.width,
+          height: token.height,
+        };
+        const badgeStyle = { height: token.height };
+
+        if (chip.status !== 'ready' || !chip.previewUrl) {
+          return (
+            <span
+              key={`${token.id}-${index}`}
+              className="absolute overflow-hidden"
+              style={footprint}
+            >
+              <span
+                aria-hidden
+                data-token-id={token.id}
+                style={badgeStyle}
+                className="ring-border bg-muted flex aspect-square items-center justify-center rounded-md shadow-sm ring-1"
+              >
+                <Loader className="text-muted-foreground size-3 animate-spin" />
+              </span>
+            </span>
+          );
+        }
+
+        return (
+          <span
+            key={`${token.id}-${index}`}
+            className="absolute overflow-hidden"
+            style={footprint}
+          >
+            <Tooltip content={`${t('viewImage')} ${token.id}`} side="top">
+              <button
+                type="button"
+                // Mouse-only affordance — keyboard/AT use the textarea text and
+                // the attachment tray, so the badge stays out of the tab order.
+                tabIndex={-1}
+                data-token-id={token.id}
+                onClick={() => onOpen(token.id)}
+                aria-label={`${t('viewImage')} ${token.id}`}
+                style={badgeStyle}
+                className="ring-border bg-muted hover:ring-ring pointer-events-auto flex items-center gap-1 overflow-hidden rounded-md pr-1.5 shadow-sm ring-1 transition hover:ring-2"
+              >
+                <img
+                  src={chip.previewUrl}
+                  alt=""
+                  className="aspect-square h-full shrink-0 object-cover"
+                />
+                <span className="text-foreground text-[11px] leading-none font-semibold tabular-nums">
+                  {token.id}.
+                </span>
+              </button>
+            </Tooltip>
+          </span>
+        );
+      })}
+    </div>
+  );
+});
diff --git a/services/platform/app/features/chat/components/chat-input/paste-image-tokens.test.ts b/services/platform/app/features/chat/components/chat-input/paste-image-tokens.test.ts
new file mode 100644
index 0000000000..6c2976f961
--- /dev/null
+++ b/services/platform/app/features/chat/components/chat-input/paste-image-tokens.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildMarkerToken,
+  collapseMarkerSpaces,
+  isPastedImageRef,
+  MARKER_RESERVE_SPACES,
+  nextPasteImageId,
+  pastedImageIdFromName,
+  presentTokenIds,
+  tokenSpans,
+} from './paste-image-tokens';
+
+describe('pastedImageIdFromName', () => {
+  it('reads the id from a pasted-image file name', () => {
+    expect(pastedImageIdFromName('[1].png')).toBe(1);
+    expect(pastedImageIdFromName('[12].jpg')).toBe(12);
+  });
+
+  it('reads the id from the upload-tracking id (name + suffix)', () => {
+    // `useConvexFileUpload` keys in-flight uploads as `${file.name}-${ts}`.
+    expect(pastedImageIdFromName('[3].png-1718900000000')).toBe(3);
+  });
+
+  it('returns null for names that are not pasted images', () => {
+    expect(pastedImageIdFromName('report.pdf')).toBeNull();
+    expect(pastedImageIdFromName('pasted-image-2026.png')).toBeNull();
+    expect(pastedImageIdFromName('[abc].png')).toBeNull();
+    expect(pastedImageIdFromName('[1]')).toBeNull(); // no extension
+  });
+});
+
+describe('isPastedImageRef', () => {
+  it('matches pasted-image names and upload ids', () => {
+    expect(isPastedImageRef('[1].png')).toBe(true);
+    expect(isPastedImageRef('[7].jpeg-99')).toBe(true);
+  });
+
+  it('rejects everything else', () => {
+    expect(isPastedImageRef('notes.txt')).toBe(false);
+    expect(isPastedImageRef('[x].png')).toBe(false);
+    expect(isPastedImageRef('image[1].png')).toBe(false);
+  });
+});
+
+describe('presentTokenIds', () => {
+  it('collects every distinct [N] id in the text', () => {
+    expect([...presentTokenIds('compare [1] with [2] and [2]')]).toEqual([
+      1, 2,
+    ]);
+  });
+
+  it('handles multi-digit ids and no tokens', () => {
+    expect([...presentTokenIds('[10] vs [3]')].sort((a, b) => a - b)).toEqual([
+      3, 10,
+    ]);
+    expect(presentTokenIds('no tokens here').size).toBe(0);
+    expect(presentTokenIds('').size).toBe(0);
+  });
+});
+
+describe('nextPasteImageId', () => {
+  it('starts at 1 for empty / token-free text', () => {
+    expect(nextPasteImageId('')).toBe(1);
+    expect(nextPasteImageId('hello world')).toBe(1);
+  });
+
+  it('is one past the highest existing token (not the count)', () => {
+    expect(nextPasteImageId('here [1] is one')).toBe(2);
+    expect(nextPasteImageId('[1] [5] [3]')).toBe(6);
+  });
+
+  it('avoids colliding with a token the user typed', () => {
+    expect(nextPasteImageId('see footnote [9]')).toBe(10);
+  });
+
+  it('parses zero-padded ids by value', () => {
+    expect(nextPasteImageId('[007]')).toBe(8);
+  });
+});
+
+describe('tokenSpans', () => {
+  it('returns the char range of each token', () => {
+    expect(tokenSpans('a [1] b [22]')).toEqual([
+      { id: 1, start: 2, end: 5 },
+      { id: 22, start: 8, end: 12 },
+    ]);
+  });
+
+  it('is empty when there are no tokens', () => {
+    expect(tokenSpans('no tokens')).toEqual([]);
+  });
+
+  it('locates a token so a caret right after it can be matched (atomic delete)', () => {
+    const value = 'hi [3] there';
+    const [span] = tokenSpans(value);
+    // The slice covers exactly `[3]` — Backspace at `span.end` removes the
+    // whole token rather than just the trailing `]`.
+    expect(value.slice(span.start, span.end)).toBe('[3]');
+  });
+});
+
+describe('buildMarkerToken', () => {
+  it('is `[N]` followed by the reserve spaces (room for the rectangle badge)', () => {
+    const token = buildMarkerToken(2);
+    expect(token).toBe(`[2]${' '.repeat(MARKER_RESERVE_SPACES)}`);
+    expect(token.startsWith('[2]')).toBe(true);
+    expect(token.length).toBe(3 + MARKER_RESERVE_SPACES);
+  });
+});
+
+describe('collapseMarkerSpaces', () => {
+  it('collapses the reserve spaces after each token to one (outgoing text)', () => {
+    expect(collapseMarkerSpaces('compare [1]      with [2]      please')).toBe(
+      'compare [1] with [2] please',
+    );
+  });
+
+  it('leaves ordinary spacing untouched', () => {
+    expect(collapseMarkerSpaces('no markers here')).toBe('no markers here');
+    expect(collapseMarkerSpaces('[1] ')).toBe('[1] ');
+  });
+});
diff --git a/services/platform/app/features/chat/components/chat-input/paste-image-tokens.ts b/services/platform/app/features/chat/components/chat-input/paste-image-tokens.ts
new file mode 100644
index 0000000000..77c08c34a6
--- /dev/null
+++ b/services/platform/app/features/chat/components/chat-input/paste-image-tokens.ts
@@ -0,0 +1,98 @@
+/**
+ * Pasted-image reference tokens.
+ *
+ * When a user pastes an image into the composer we insert a short `[N]`
+ * reference token at the caret and name the uploaded file `[N].<ext>`. The
+ * token stays in the message text the agent receives (so the prose can say
+ * "compare [1] with [2]") and the backend's pre-analyzed image section labels
+ * the attachment `**Image: [N].<ext>**`, letting the model correlate the two.
+ * The `PasteImageOverlay` paints a thumbnail chip over each `[N]` in the
+ * textarea. These helpers are the single source of truth for the token shape so
+ * the paste handler, the overlay, the tray exclusion and the removal-sync all
+ * agree.
+ */
+
+/** Matches every `[N]` reference token in message text (global). */
+const TOKEN_RE = /\[(\d+)\]/g;
+
+/**
+ * Spaces inserted after a `[N]` token. The marker chip is a rectangle (square
+ * thumbnail + index) wider than the bare `[N]` text, so it would overlap the
+ * following words; these trailing spaces reserve room in the textarea for the
+ * chip to sit over. They're invisible (covered by the chip), consumed when the
+ * marker is deleted, and collapsed to a single space when the message is sent.
+ */
+export const MARKER_RESERVE_SPACES = 6;
+
+/** The text inserted for a pasted/dragged image marker: `[N]` + reserve. */
+export function buildMarkerToken(id: number): string {
+  return `[${id}]${' '.repeat(MARKER_RESERVE_SPACES)}`;
+}
+
+/** Collapse the reserve-spaces after every `[N]` token down to one, for the
+ *  outgoing message text (the textarea keeps the reserve for chip layout). */
+export function collapseMarkerSpaces(value: string): string {
+  return value.replace(/(\[\d+\]) +/g, '$1 ');
+}
+
+/** Matches a pasted-image file name: `[N].<ext>` (extension-agnostic — the
+ *  client compressor may rewrite `.png` → `.jpg`, but the `[N]` base is kept). */
+const PASTED_NAME_RE = /^\[(\d+)\]\.\w+/;
+
+/** The id `N` of a pasted-image file name, or `null` if it isn't one. Also
+ *  matches the upload-tracking id (`[N].<ext>-<timestamp>`) since that is just
+ *  the file name with a suffix. */
+export function pastedImageIdFromName(name: string): number | null {
+  const match = PASTED_NAME_RE.exec(name);
+  return match ? Number(match[1]) : null;
+}
+
+/** True for both a pasted-image file name and its upload-tracking id. */
+export function isPastedImageRef(name: string): boolean {
+  return PASTED_NAME_RE.test(name);
+}
+
+/** Every `[N]` id currently present in the message text. */
+export function presentTokenIds(value: string): Set<number> {
+  const ids = new Set<number>();
+  for (const match of value.matchAll(TOKEN_RE)) {
+    ids.add(Number(match[1]));
+  }
+  return ids;
+}
+
+export interface TokenSpan {
+  id: number;
+  /** Index of the opening `[`. */
+  start: number;
+  /** Index just past the closing `]`. */
+  end: number;
+}
+
+/**
+ * The character span of every `[N]` token. Used to delete a marker atomically
+ * (so Backspace can't leave a `[1` fragment behind).
+ */
+export function tokenSpans(value: string): TokenSpan[] {
+  const spans: TokenSpan[] = [];
+  for (const match of value.matchAll(TOKEN_RE)) {
+    const start = match.index ?? 0;
+    spans.push({ id: Number(match[1]), start, end: start + match[0].length });
+  }
+  return spans;
+}
+
+/**
+ * The next id to assign to a freshly pasted image: one past the highest `[N]`
+ * already in the text. Deriving from the text (rather than a running counter)
+ * means numbering restarts at 1 once the composer is cleared on send, never
+ * collides with a token the user typed, and survives send-failure rollbacks.
+ */
+export function nextPasteImageId(value: string): number {
+  let max = 0;
+  for (const match of value.matchAll(TOKEN_RE)) {
+    const id = Number(match[1]);
+    if (id > max) max = id;
+  }
+  return max + 1;
+}
diff --git a/services/platform/app/features/chat/components/chat-interface.tsx b/services/platform/app/features/chat/components/chat-interface.tsx
index bbcf6581e6..3d1f94b304 100644
--- a/services/platform/app/features/chat/components/chat-interface.tsx
+++ b/services/platform/app/features/chat/components/chat-interface.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { useNavigate, useSearch } from '@tanstack/react-router';
 import { ConvexError } from 'convex/values';
 import {
@@ -1146,10 +1147,11 @@ export function ChatInterface({
   const showWelcome = !showMessages && !showArena && !showExitingSkeleton;
 
   return (
-    <div
+    <Stack
       role="region"
       aria-labelledby={chatRegionLabelId}
-      className="flex h-full min-h-0 flex-1 flex-col"
+      gap={0}
+      className="h-full min-h-0 flex-1"
     >
       <h2 id={chatRegionLabelId} className="sr-only">
         {t('aria.chatRegion')}
@@ -1166,9 +1168,10 @@ export function ChatInterface({
         // instant scrolls (see useChatScroll). A CSS smooth-behavior would make
         // every pin animate against the still-settling response slack and land
         // short. The scroll-to-bottom button opts into smooth explicitly.
-        <div
+        <Stack
           ref={containerRef}
-          className="flex min-h-0 flex-1 flex-col overflow-y-auto will-change-transform"
+          gap={0}
+          className="min-h-0 flex-1 overflow-y-auto will-change-transform"
         >
           <div
             ref={contentRef}
@@ -1283,7 +1286,7 @@ export function ChatInterface({
               </ChatMessagesErrorBoundary>
             )}
           </div>
-        </div>
+        </Stack>
       )}
 
       {/* Floating "Quote" affordance on text selection inside messages.
@@ -1427,6 +1430,6 @@ export function ChatInterface({
           setInsertedPrompt(content);
         }}
       />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/chat-interface/archived-banner.tsx b/services/platform/app/features/chat/components/chat-interface/archived-banner.tsx
index aea33c827e..313481aa94 100644
--- a/services/platform/app/features/chat/components/chat-interface/archived-banner.tsx
+++ b/services/platform/app/features/chat/components/chat-interface/archived-banner.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Archive } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -20,19 +21,22 @@ export function ArchivedBanner({
 }: ArchivedBannerProps) {
   const { t } = useT('chat');
   return (
-    <div className="border-border bg-muted/50 flex items-center justify-center gap-2 border-t px-3 py-3">
+    <Row
+      gap={2}
+      justify="center"
+      className="border-border bg-muted/50 border-t px-3 py-3"
+    >
       <Archive className="text-muted-foreground size-4" />
       <span className="text-muted-foreground text-sm">
         {t('archivedBanner')}
       </span>
       <Button
         variant="secondary"
-        size="sm"
         disabled={isUnarchiving}
         onClick={onUnarchive}
       >
         {t('unarchive')}
       </Button>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/chat-interface/read-only-banner.tsx b/services/platform/app/features/chat/components/chat-interface/read-only-banner.tsx
index 4a8b08d17b..9af7e08940 100644
--- a/services/platform/app/features/chat/components/chat-interface/read-only-banner.tsx
+++ b/services/platform/app/features/chat/components/chat-interface/read-only-banner.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Share } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -11,11 +12,15 @@ import { useT } from '@/lib/i18n/client';
 export function ReadOnlyBanner() {
   const { t } = useT('chat');
   return (
-    <div className="border-border bg-muted/50 flex items-center justify-center gap-2 border-t px-3 py-3">
+    <Row
+      gap={2}
+      justify="center"
+      className="border-border bg-muted/50 border-t px-3 py-3"
+    >
       <Share className="text-muted-foreground size-4" />
       <span className="text-muted-foreground text-sm">
         {t('share.readOnlyBanner')}
       </span>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/chat-interface/scroll-to-bottom-button.tsx b/services/platform/app/features/chat/components/chat-interface/scroll-to-bottom-button.tsx
index f45683981e..a05ea12036 100644
--- a/services/platform/app/features/chat/components/chat-interface/scroll-to-bottom-button.tsx
+++ b/services/platform/app/features/chat/components/chat-interface/scroll-to-bottom-button.tsx
@@ -36,7 +36,7 @@ export function ScrollToBottomButton({
             size="icon"
             variant="secondary"
             className="bg-background/95 rounded-full shadow-lg backdrop-blur-xs"
-            aria-label={t('aria.scrollToBottom')}
+            title={t('aria.scrollToBottom')}
           >
             <ArrowDown className="h-4 w-4" />
           </Button>
diff --git a/services/platform/app/features/chat/components/chat-messages-skeleton.tsx b/services/platform/app/features/chat/components/chat-messages-skeleton.tsx
index 134b7aee63..35d3f0eeac 100644
--- a/services/platform/app/features/chat/components/chat-messages-skeleton.tsx
+++ b/services/platform/app/features/chat/components/chat-messages-skeleton.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 
@@ -42,13 +43,15 @@ export function ChatMessagesSkeleton() {
   const { t } = useT('chat');
   return (
     <Skeletonize loading label={t('skeleton.loadingMessage')}>
-      <div className="mx-auto flex w-full max-w-(--chat-max-width) flex-col gap-3 pt-6">
+      <Stack gap={3} className="mx-auto w-full max-w-(--chat-max-width) pt-6">
         {PLACEHOLDER_ROWS.map((row, rowIdx) =>
           row.role === 'user' ? (
-            <div
+            <Row
               // eslint-disable-next-line react/no-array-index-key
               key={rowIdx}
-              className="flex justify-end"
+              gap={0}
+              align="stretch"
+              justify="end"
             >
               {/* Hugging bubble, right-aligned. `h-11` matches a one-line user
                   bubble (text `leading-5` + `py-3`); the box's own rounding
@@ -58,17 +61,18 @@ export function ChatMessagesSkeleton() {
                   <div className="h-11" />
                 </SkeletonBox>
               </div>
-            </div>
+            </Row>
           ) : (
-            <div
+            <Row
               // eslint-disable-next-line react/no-array-index-key
               key={rowIdx}
-              className="flex justify-start"
+              gap={0}
+              align="stretch"
             >
               {/* Full-width prose, inset by the bubble's px-4/py-3 so the masked
                   lines align with the real rendered answer. */}
               <div className="w-full px-4 py-3">
-                <div className="flex flex-col gap-2">
+                <Stack gap={2}>
                   {row.lineWidths.map((lineWidth, lineIdx) => (
                     <div
                       // eslint-disable-next-line react/no-array-index-key
@@ -80,12 +84,12 @@ export function ChatMessagesSkeleton() {
                       </SkeletonBox>
                     </div>
                   ))}
-                </div>
+                </Stack>
               </div>
-            </div>
+            </Row>
           ),
         )}
-      </div>
+      </Stack>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/chat/components/chat-messages.tsx b/services/platform/app/features/chat/components/chat-messages.tsx
index c8367e5f6e..b2bf947ffe 100644
--- a/services/platform/app/features/chat/components/chat-messages.tsx
+++ b/services/platform/app/features/chat/components/chat-messages.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { useQuery } from 'convex/react';
 import { AlertTriangle, Loader2, CheckCircle2, Lock } from 'lucide-react';
 import {
@@ -17,6 +18,7 @@ import {
 import { api } from '@/convex/_generated/api';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
+import { SYSTEM_MSG_TAG } from '@/lib/shared/constants/system-message-tags';
 import { cn } from '@/lib/utils/cn';
 
 import { useBranchContext } from '../context/branch-context';
@@ -32,6 +34,7 @@ import { CollapsibleSystemMessage } from './collapsible-system-message';
 import { InlineEditInput } from './inline-edit-input';
 import { InlineMemoryProposals } from './inline-memory-proposals';
 import { MessageBubble } from './message-bubble';
+import { ModelFallbackNotice } from './model-fallback-notice';
 import { ThinkingIndicator } from './thought-timeline';
 import { VirtualizedChatMessageList } from './virtualized-chat-message-list';
 import { VoiceOutputAnnouncer } from './voice-output-announcer';
@@ -662,14 +665,28 @@ export const ChatMessages = memo(function ChatMessages({
     const message = item.data;
 
     if (message.role === 'system' && message.systemMessageDisplay) {
+      // Model-fallback notices carry a structured body — render a localized line.
+      if (message.systemMessageTag === SYSTEM_MSG_TAG.MODEL_FALLBACK) {
+        return (
+          <div key={message.key} data-message-key={message.key}>
+            <ModelFallbackNotice
+              body={message.systemMessageBody ?? message.content}
+            />
+          </div>
+        );
+      }
+
       if (message.systemMessageDisplay === 'pill') {
         return (
-          <div key={message.key} className="flex justify-end">
-            <div className="bg-primary/10 text-primary flex items-center gap-2 rounded-full px-4 py-2 text-sm">
+          <Row key={message.key} gap={0} align="stretch" justify="end">
+            <Row
+              gap={2}
+              className="bg-primary/10 text-primary rounded-full px-4 py-2 text-sm"
+            >
               <CheckCircle2 className="size-4" aria-hidden="true" />
               <span>{message.systemMessageBody ?? message.content}</span>
-            </div>
-          </div>
+            </Row>
+          </Row>
         );
       }
 
@@ -770,7 +787,7 @@ export const ChatMessages = memo(function ChatMessages({
         )}
       >
         {isEditing && onEditSubmit && onEditCancel ? (
-          <div className="flex justify-end" ref={editInputScrollRef}>
+          <Row gap={0} align="stretch" justify="end" ref={editInputScrollRef}>
             <div className="w-full max-w-[85%]">
               <InlineEditInput
                 messageContent={editingMessageContent ?? message.content}
@@ -778,7 +795,7 @@ export const ChatMessages = memo(function ChatMessages({
                 onCancel={onEditCancel}
               />
             </div>
-          </div>
+          </Row>
         ) : (
           <>
             <MessageBubble
@@ -874,18 +891,14 @@ export const ChatMessages = memo(function ChatMessages({
 
   const forkDivider =
     forkDividerAfterIdx >= 0 ? (
-      <div
-        key="fork-divider"
-        className="flex items-center gap-3 py-2"
-        role="separator"
-      >
+      <Row key="fork-divider" gap={3} className="py-2" role="separator">
         <div className="bg-border h-px flex-1" />
         <span className="text-muted-foreground flex items-center gap-1.5 text-xs">
           <Lock className="size-3" />
           {forkedFromShare ? t('shareBoundary') : t('forkBoundary')}
         </span>
         <div className="bg-border h-px flex-1" />
-      </div>
+      </Row>
     ) : null;
 
   const renderItemWithDivider = (item: ChatItem, idx: number) => {
@@ -914,10 +927,9 @@ export const ChatMessages = memo(function ChatMessages({
   // Shared between the virtualized and non-virtualized paths.
   const loadMoreHeader =
     canLoadMore || isLoadingMore ? (
-      <div className="flex justify-center py-2">
+      <Row gap={0} align="stretch" justify="center" className="py-2">
         <Button
           variant="ghost"
-          size="sm"
           onClick={() => loadMore(50)}
           disabled={isLoadingMore}
           className="text-muted-foreground hover:text-foreground"
@@ -931,7 +943,7 @@ export const ChatMessages = memo(function ChatMessages({
             t('loadOlderMessages')
           )}
         </Button>
-      </div>
+      </Row>
     ) : null;
 
   // Post-send gap affordance: shown only until the assistant message appears
@@ -1022,7 +1034,7 @@ export const ChatMessages = memo(function ChatMessages({
         // BARE (it owns internal sub-state live regions; see above). No
         // parent `gap` — the live wrapper carries its own bottom padding
         // only when populated, so an empty wrapper adds no phantom gap.
-        <div className="flex flex-col pb-2">
+        <Stack gap={0} className="pb-2">
           <div
             aria-live="polite"
             className={responseFooterLive ? 'pb-3' : undefined}
@@ -1030,12 +1042,13 @@ export const ChatMessages = memo(function ChatMessages({
             {responseFooterLive}
           </div>
           {responseFooterStatic}
-        </div>
+        </Stack>
       }
     />
   ) : (
-    <div
-      className="mx-auto flex w-full max-w-(--chat-max-width) flex-col"
+    <Stack
+      gap={0}
+      className="mx-auto w-full max-w-(--chat-max-width)"
       role="log"
       aria-live="polite"
       aria-labelledby={messageHistoryLabelId}
@@ -1043,13 +1056,13 @@ export const ChatMessages = memo(function ChatMessages({
       <h2 id={messageHistoryLabelId} className="sr-only">
         {t('aria.messageHistory')}
       </h2>
-      <div className="flex flex-col gap-3 pt-6">
+      <Stack gap={3} className="pt-6">
         {loadMoreHeader}
 
         {/* Messages before the last user message */}
-        <div className="flex flex-col gap-3">
+        <Stack gap={3}>
           {beforeItems.map((item, i) => renderItemWithDivider(item, i))}
-        </div>
+        </Stack>
 
         {/* Last user message */}
         {lastUserItem && renderItemWithDivider(lastUserItem, lastUserIdx)}
@@ -1057,9 +1070,10 @@ export const ChatMessages = memo(function ChatMessages({
         {/* Response area: min-height fills viewport so scroll-to-bottom
             positions the user message at the top. When AI response exceeds
             viewport height, min-height becomes irrelevant. */}
-        <div
+        <Stack
           ref={responseAreaRef}
-          className="flex shrink-0 flex-col gap-3 [overflow-anchor:none]"
+          gap={3}
+          className="shrink-0 [overflow-anchor:none]"
         >
           {afterItems.map((item, i) =>
             renderItemWithDivider(item, lastUserIdx + 1 + i),
@@ -1068,9 +1082,9 @@ export const ChatMessages = memo(function ChatMessages({
               aria-live="polite", so both pieces render inside it as before. */}
           {responseFooterLive}
           {responseFooterStatic}
-        </div>
-      </div>
-    </div>
+        </Stack>
+      </Stack>
+    </Stack>
   );
 
   return (
diff --git a/services/platform/app/features/chat/components/composer-capability-pills.tsx b/services/platform/app/features/chat/components/composer-capability-pills.tsx
index 44cb1c7ee1..3d9f20d927 100644
--- a/services/platform/app/features/chat/components/composer-capability-pills.tsx
+++ b/services/platform/app/features/chat/components/composer-capability-pills.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { X } from 'lucide-react';
 
 import { Tooltip } from '@/app/components/ui/overlays/tooltip';
@@ -26,7 +27,7 @@ export function ComposerCapabilityPills({
   if (active.length === 0) return null;
 
   return (
-    <div className="flex flex-wrap items-center gap-1">
+    <Row gap={1} wrap>
       {active.map((cap) => {
         const Icon = cap.icon;
         return (
@@ -46,6 +47,6 @@ export function ComposerCapabilityPills({
           </Tooltip>
         );
       })}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/composer-mode-menu.tsx b/services/platform/app/features/chat/components/composer-mode-menu.tsx
index 312374d65b..24b65dfca1 100644
--- a/services/platform/app/features/chat/components/composer-mode-menu.tsx
+++ b/services/platform/app/features/chat/components/composer-mode-menu.tsx
@@ -7,14 +7,7 @@ import {
   type DropdownMenuItem,
 } from '@tale/ui/dropdown-menu';
 import { useNavigate } from '@tanstack/react-router';
-import {
-  Camera,
-  FolderOpen,
-  MonitorPlay,
-  Paperclip,
-  Plus,
-  Swords,
-} from 'lucide-react';
+import { FolderOpen, MonitorPlay, Paperclip, Plus, Swords } from 'lucide-react';
 import { useCallback, useMemo } from 'react';
 
 import { useLiveBrowserOptional } from '@/app/features/workspace/components/live-browser-context';
@@ -40,8 +33,6 @@ interface ComposerModeMenuProps {
   /** Current thread (gates the mobile sandbox-view entries). */
   threadId?: string;
   onAttachFile?: () => void;
-  /** Capture a screenshot and attach it. Omitted when unsupported/disabled. */
-  onTakeScreenshot?: () => void;
   fileUploadDisabled?: boolean;
   disabled?: boolean;
 }
@@ -50,7 +41,6 @@ export function ComposerModeMenu({
   organizationId,
   threadId,
   onAttachFile,
-  onTakeScreenshot,
   fileUploadDisabled = false,
   disabled = false,
 }: ComposerModeMenuProps) {
@@ -122,25 +112,15 @@ export function ComposerModeMenu({
   const items = useMemo<DropdownMenuGroup[]>(() => {
     const groups: DropdownMenuGroup[] = [];
 
-    if ((!fileUploadDisabled && onAttachFile) || onTakeScreenshot) {
-      const attachGroup: DropdownMenuGroup = [];
-      if (!fileUploadDisabled && onAttachFile) {
-        attachGroup.push({
+    if (!fileUploadDisabled && onAttachFile) {
+      groups.push([
+        {
           type: 'item',
           label: t('addFiles'),
           icon: Paperclip,
           onClick: onAttachFile,
-        });
-      }
-      if (onTakeScreenshot) {
-        attachGroup.push({
-          type: 'item',
-          label: t('takeScreenshot'),
-          icon: Camera,
-          onClick: onTakeScreenshot,
-        });
-      }
-      groups.push(attachGroup);
+        },
+      ]);
     }
 
     const hasArena = arenaContext != null;
@@ -261,7 +241,6 @@ export function ComposerModeMenu({
     live,
     fileUploadDisabled,
     onAttachFile,
-    onTakeScreenshot,
     modeAgents,
     chatAgent,
     effectiveAgent?.name,
diff --git a/services/platform/app/features/chat/components/document-write-approval-card.tsx b/services/platform/app/features/chat/components/document-write-approval-card.tsx
index e6e7c673d5..5745432b65 100644
--- a/services/platform/app/features/chat/components/document-write-approval-card.tsx
+++ b/services/platform/app/features/chat/components/document-write-approval-card.tsx
@@ -3,7 +3,7 @@
 import { ActionRow } from '@tale/ui/action-row';
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   CheckCircle,
@@ -27,6 +27,8 @@ import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 import { formatBytes } from '@/lib/utils/format/number';
 
+import { ApprovalCard } from './approval-card';
+
 interface DocumentWriteApprovalCardProps {
   approvalId: Id<'approvals'>;
   organizationId: string;
@@ -113,12 +115,7 @@ function DocumentWriteApprovalCardComponent({
   const failedCount = files.filter((f) => f.executionError).length;
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="center" className="mb-2">
         <FileText className="text-primary size-4 shrink-0" />
@@ -135,7 +132,7 @@ function DocumentWriteApprovalCardComponent({
         className={cn('mb-3 pl-6', isBatch && 'max-h-48 overflow-y-auto')}
       >
         {files.map((file) => (
-          <div key={file.fileId} className="flex min-w-0 items-start gap-2">
+          <Row key={file.fileId} gap={2} align="start" className="min-w-0">
             {/* Per-file status icon (only after execution) */}
             {(status === 'executing' || status === 'completed') &&
               executedAt && (
@@ -176,7 +173,7 @@ function DocumentWriteApprovalCardComponent({
                 </Text>
               )}
             </div>
-          </div>
+          </Row>
         ))}
       </Stack>
 
@@ -281,7 +278,6 @@ function DocumentWriteApprovalCardComponent({
             content={isBatch ? t('approveTooltipBatch') : t('approveTooltip')}
           >
             <Button
-              size="sm"
               variant="primary"
               onClick={handleApprove}
               disabled={isProcessing}
@@ -296,7 +292,6 @@ function DocumentWriteApprovalCardComponent({
             content={isBatch ? t('rejectTooltipBatch') : t('rejectTooltip')}
           >
             <Button
-              size="sm"
               variant="secondary"
               onClick={handleReject}
               disabled={isProcessing}
@@ -337,7 +332,7 @@ function DocumentWriteApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/edit-message-dialog.tsx b/services/platform/app/features/chat/components/edit-message-dialog.tsx
index 1589920209..7e3ca8d391 100644
--- a/services/platform/app/features/chat/components/edit-message-dialog.tsx
+++ b/services/platform/app/features/chat/components/edit-message-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Loader2 } from 'lucide-react';
 import { useRef, useState, useEffect, useCallback } from 'react';
 
@@ -77,7 +78,7 @@ function EditMessageDialogContent({
       hideClose
       size="lg"
       footer={
-        <div className="flex justify-end gap-2">
+        <Row gap={2} align="stretch" justify="end">
           <Button
             variant="secondary"
             onClick={() => onOpenChange(false)}
@@ -95,7 +96,7 @@ function EditMessageDialogContent({
             )}
             {tChat('editSend')}
           </Button>
-        </div>
+        </Row>
       }
     >
       <textarea
diff --git a/services/platform/app/features/chat/components/editing-banner.tsx b/services/platform/app/features/chat/components/editing-banner.tsx
index f5e60125ae..f1983b00fc 100644
--- a/services/platform/app/features/chat/components/editing-banner.tsx
+++ b/services/platform/app/features/chat/components/editing-banner.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { AlertTriangle, ChevronDown, Pencil, X } from 'lucide-react';
 import { memo, useMemo, useState } from 'react';
@@ -155,9 +156,9 @@ export const EditingBanner = memo(function EditingBanner({
         </button>
       ) : (
         <div className="ring-border size-9 shrink-0 overflow-hidden rounded-md ring-1">
-          <div className="bg-muted flex size-full items-center justify-center">
+          <Row gap={0} justify="center" className="bg-muted size-full">
             <Pencil className="text-muted-foreground size-4" />
-          </div>
+          </Row>
         </div>
       )}
       {ref.url && (
diff --git a/services/platform/app/features/chat/components/export-chat-dialog.tsx b/services/platform/app/features/chat/components/export-chat-dialog.tsx
index d8cbee9e4b..400df5bcf6 100644
--- a/services/platform/app/features/chat/components/export-chat-dialog.tsx
+++ b/services/platform/app/features/chat/components/export-chat-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Download, FileText } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
@@ -245,10 +246,9 @@ function ExportChatDialogContent({
       icon={<Download className="text-muted-foreground size-5" />}
       size="lg"
       footer={
-        <div className="flex gap-2">
+        <Row gap={2} align="stretch">
           <Button
             variant="secondary"
-            size="sm"
             onClick={handleExportMarkdown}
             disabled={noneSelected}
             className="gap-1.5"
@@ -258,7 +258,6 @@ function ExportChatDialogContent({
           </Button>
           <Button
             variant="primary"
-            size="sm"
             onClick={handleExportPdf}
             disabled={noneSelected}
             className="gap-1.5"
@@ -266,26 +265,21 @@ function ExportChatDialogContent({
             <FileText className="size-3.5" />
             {t('export.downloadPdf')}
           </Button>
-        </div>
+        </Row>
       }
     >
-      <div className="flex flex-col gap-3">
-        <div className="flex items-center justify-between">
+      <Stack gap={3}>
+        <Row gap={0} justify="between">
           <Text variant="label" className="text-sm">
             {t('export.messagesCount', {
               count: effectiveSelected.size,
               total: messages.length,
             })}
           </Text>
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={handleToggleAll}
-            className="text-xs"
-          >
+          <Button variant="ghost" onClick={handleToggleAll} className="text-xs">
             {allSelected ? t('export.deselectAll') : t('export.selectAll')}
           </Button>
-        </div>
+        </Row>
 
         <div className="border-border max-h-80 overflow-y-auto rounded-lg border">
           {messages.map((msg) => (
@@ -324,7 +318,7 @@ function ExportChatDialogContent({
             </div>
           )}
         </div>
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/chat/components/external-agent-mode-toggle.tsx b/services/platform/app/features/chat/components/external-agent-mode-toggle.tsx
index d1dea1dd8e..32ab723480 100644
--- a/services/platform/app/features/chat/components/external-agent-mode-toggle.tsx
+++ b/services/platform/app/features/chat/components/external-agent-mode-toggle.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { useMutation } from 'convex/react';
 import { ClipboardList, Zap } from 'lucide-react';
 import { useCallback } from 'react';
@@ -75,10 +76,11 @@ export function ExternalAgentModeToggle({
   }
 
   return (
-    <div
+    <Row
       role="radiogroup"
       aria-label={t('planMode.label')}
-      className="border-border bg-muted/40 flex h-8 items-center rounded-full border p-0.5"
+      gap={0}
+      className="border-border bg-muted/40 h-8 rounded-full border p-0.5"
     >
       <Tooltip content={t('planMode.planTooltip')} side="top">
         <button
@@ -116,6 +118,6 @@ export function ExternalAgentModeToggle({
           {t('planMode.act')}
         </button>
       </Tooltip>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/human-control-card.tsx b/services/platform/app/features/chat/components/human-control-card.tsx
index a9cd6fcbf1..10625d8651 100644
--- a/services/platform/app/features/chat/components/human-control-card.tsx
+++ b/services/platform/app/features/chat/components/human-control-card.tsx
@@ -14,9 +14,10 @@ import { useLiveBrowserOptional } from '@/app/features/workspace/components/live
 import type { Id } from '@/convex/_generated/dataModel';
 import type { HumanControlMetadata } from '@/convex/approvals/types';
 import { useT } from '@/lib/i18n/client';
-import { cn } from '@/lib/utils/cn';
 import { isRecord } from '@/lib/utils/type-utils';
 
+import { ApprovalCard } from './approval-card';
+
 interface HumanControlCardProps {
   approvalId: Id<'approvals'>;
   organizationId: string;
@@ -98,12 +99,7 @@ function HumanControlCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'bg-card w-full max-w-2xl overflow-hidden rounded-xl border border-border p-4',
-        className,
-      )}
-    >
+    <ApprovalCard maxWidth="2xl" className={className}>
       <HStack gap={2} align="center" className="mb-2">
         <Hand className="text-primary size-4 shrink-0" />
         <Text as="div" variant="label">
@@ -135,7 +131,6 @@ function HumanControlCardComponent({
           <ActionRow gap={2} className="mt-1">
             {controlling ? (
               <Button
-                size="sm"
                 variant="primary"
                 onClick={handleReturn}
                 disabled={isReturning}
@@ -150,7 +145,6 @@ function HumanControlCardComponent({
               </Button>
             ) : (
               <Button
-                size="sm"
                 variant="primary"
                 onClick={handleTakeControl}
                 className="flex-1"
@@ -202,7 +196,7 @@ function HumanControlCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/human-input-fields.tsx b/services/platform/app/features/chat/components/human-input-fields.tsx
index a0f61f98a8..4f5913e60b 100644
--- a/services/platform/app/features/chat/components/human-input-fields.tsx
+++ b/services/platform/app/features/chat/components/human-input-fields.tsx
@@ -356,7 +356,7 @@ function TodoListFieldInput({
             size="icon"
             onClick={() => removeRow(todo.id)}
             disabled={disabled || items.length <= Math.max(1, minItems)}
-            aria-label={`Remove item ${index + 1}`}
+            title={`Remove item ${index + 1}`}
           >
             <Trash2 className="size-4" />
           </Button>
@@ -365,7 +365,6 @@ function TodoListFieldInput({
       <Button
         type="button"
         variant="secondary"
-        size="sm"
         onClick={addRow}
         disabled={disabled || items.length >= maxItems}
         className="gap-1 self-start"
diff --git a/services/platform/app/features/chat/components/human-input-request-card.tsx b/services/platform/app/features/chat/components/human-input-request-card.tsx
index 09ba83512c..18dae91a74 100644
--- a/services/platform/app/features/chat/components/human-input-request-card.tsx
+++ b/services/platform/app/features/chat/components/human-input-request-card.tsx
@@ -53,6 +53,7 @@ import {
 } from '../hooks/mutations';
 import { useEffectiveAgent } from '../hooks/use-effective-agent';
 import { useCancelExecution } from '../hooks/use-execution-status';
+import { ApprovalCard } from './approval-card';
 import { HumanInputFields } from './human-input-fields';
 import { markdownWrapperStyles } from './message-bubble/markdown-renderer';
 
@@ -457,7 +458,7 @@ function HumanInputRequestCardComponent({
                     setViewedVersionIdx(Math.max(0, displayedVersionIdx - 1))
                   }
                   disabled={displayedVersionIdx <= 0}
-                  aria-label={t('versionPrevious')}
+                  title={t('versionPrevious')}
                 >
                   <ChevronLeft className="size-3.5" />
                 </Button>
@@ -476,7 +477,7 @@ function HumanInputRequestCardComponent({
                     )
                   }
                   disabled={isViewingLatestVersion}
-                  aria-label={t('versionNext')}
+                  title={t('versionNext')}
                 >
                   <ChevronRight className="size-3.5" />
                 </Button>
@@ -489,12 +490,7 @@ function HumanInputRequestCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-5 bg-card w-full max-w-xl',
-        className,
-      )}
-    >
+    <ApprovalCard maxWidth="xl" padding="lg" className={className}>
       {/* Header */}
       <HStack gap={3} align="center" justify="between" className="mb-4">
         <HStack gap={3}>
@@ -700,7 +696,7 @@ function HumanInputRequestCardComponent({
           )}
         </HStack>
       ) : null}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/inline-edit-input.tsx b/services/platform/app/features/chat/components/inline-edit-input.tsx
index 83aa7050c9..f2e63a2ccc 100644
--- a/services/platform/app/features/chat/components/inline-edit-input.tsx
+++ b/services/platform/app/features/chat/components/inline-edit-input.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Loader2 } from 'lucide-react';
 import { useRef, useState, useEffect, useCallback } from 'react';
 
@@ -62,7 +63,7 @@ export function InlineEditInput({
   const canSubmit = !!value.trim() && value.trim() !== messageContent;
 
   return (
-    <div className="bg-muted/50 border-border flex flex-col gap-3 rounded-2xl border p-4">
+    <Stack gap={3} className="bg-muted/50 border-border rounded-2xl border p-4">
       <textarea
         ref={textareaRef}
         value={value}
@@ -77,10 +78,9 @@ export function InlineEditInput({
         className="text-foreground min-h-[2.5rem] w-full resize-none bg-transparent text-sm leading-6 focus:outline-none disabled:opacity-50"
         rows={1}
       />
-      <div className="flex items-center justify-end gap-2">
+      <Row gap={2} justify="end">
         <Button
           variant="secondary"
-          size="sm"
           onClick={onCancel}
           disabled={isSubmitting}
           className="rounded-full"
@@ -89,7 +89,6 @@ export function InlineEditInput({
         </Button>
         <Button
           variant="primary"
-          size="sm"
           onClick={() => void handleSubmit()}
           disabled={!canSubmit || isSubmitting}
           className="rounded-full"
@@ -97,7 +96,7 @@ export function InlineEditInput({
           {isSubmitting && <Loader2 className="mr-1.5 size-3.5 animate-spin" />}
           {tChat('editSend')}
         </Button>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/inline-memory-proposals.tsx b/services/platform/app/features/chat/components/inline-memory-proposals.tsx
index 9675e6f747..885c83c82e 100644
--- a/services/platform/app/features/chat/components/inline-memory-proposals.tsx
+++ b/services/platform/app/features/chat/components/inline-memory-proposals.tsx
@@ -1,5 +1,7 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
+
 import type { Doc } from '@/convex/_generated/dataModel';
 
 import { MemoryProposalCard } from './memory-proposal-card';
@@ -28,10 +30,10 @@ export function InlineMemoryProposals({
   if (memories.length === 0) return null;
 
   return (
-    <div className="mt-2 flex flex-col gap-2">
+    <Stack gap={2} className="mt-2">
       {memories.map((m) => (
         <MemoryProposalCard key={m._id} memory={m} />
       ))}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/integration-approval-card.tsx b/services/platform/app/features/chat/components/integration-approval-card.tsx
index a7b217dca2..2fb4363234 100644
--- a/services/platform/app/features/chat/components/integration-approval-card.tsx
+++ b/services/platform/app/features/chat/components/integration-approval-card.tsx
@@ -32,6 +32,7 @@ import type { IntegrationOperationMetadata } from '@/convex/approvals/types';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 
+import { ApprovalCard } from './approval-card';
 import { ImagePreviewDialog } from './message-bubble/image-preview-dialog';
 import { markdownWrapperStyles } from './message-bubble/markdown-renderer';
 
@@ -191,12 +192,7 @@ function IntegrationApprovalCardComponent({
   const IntegrationIcon = metadata.integrationType === 'sql' ? Database : Globe;
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="start" justify="between" className="mb-3">
         <HStack gap={2}>
@@ -316,7 +312,6 @@ function IntegrationApprovalCardComponent({
               />
               <ActionRow gap={2}>
                 <Button
-                  size="sm"
                   variant="secondary"
                   onClick={() => setShowFeedback(false)}
                   disabled={isProcessing}
@@ -326,7 +321,6 @@ function IntegrationApprovalCardComponent({
                   {t('backToActions')}
                 </Button>
                 <Button
-                  size="sm"
                   variant="secondary"
                   onClick={async () => {
                     if (feedbackText.trim()) {
@@ -371,7 +365,6 @@ function IntegrationApprovalCardComponent({
               <ActionRow gap={2}>
                 <Tooltip content={t('approveTooltip')}>
                   <Button
-                    size="sm"
                     variant="primary"
                     onClick={handleApprove}
                     disabled={isProcessing}
@@ -386,7 +379,6 @@ function IntegrationApprovalCardComponent({
 
                 <Tooltip content={t('rejectTooltip')}>
                   <Button
-                    size="sm"
                     variant="secondary"
                     onClick={handleReject}
                     disabled={isProcessing}
@@ -438,7 +430,7 @@ function IntegrationApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/kb-mention-popover.tsx b/services/platform/app/features/chat/components/kb-mention-popover.tsx
index fe1415b70b..3230dc85df 100644
--- a/services/platform/app/features/chat/components/kb-mention-popover.tsx
+++ b/services/platform/app/features/chat/components/kb-mention-popover.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import {
   Highlight,
   type SearchResult,
@@ -65,16 +66,17 @@ export function KbMentionPopover({
         {t('kbMention.title')}
       </div>
       {status === 'loading' ? (
-        <div
+        <Row
           role="status"
           aria-label={t('kbMention.loading')}
-          className="text-muted-foreground flex items-center gap-2 px-3 py-3"
+          gap={2}
+          className="text-muted-foreground px-3 py-3"
         >
           <Loader className="size-3.5 animate-spin" />
           <Text as="span" variant="caption">
             {t('kbMention.loading')}
           </Text>
-        </div>
+        </Row>
       ) : results.length === 0 ? (
         <Text
           as="div"
diff --git a/services/platform/app/features/chat/components/knowledge-write-approval-card.tsx b/services/platform/app/features/chat/components/knowledge-write-approval-card.tsx
index 3eabbbc046..4e8ce42997 100644
--- a/services/platform/app/features/chat/components/knowledge-write-approval-card.tsx
+++ b/services/platform/app/features/chat/components/knowledge-write-approval-card.tsx
@@ -23,7 +23,8 @@ import { useAuth } from '@/app/hooks/use-convex-auth';
 import type { Id } from '@/convex/_generated/dataModel';
 import type { KnowledgeWriteMetadata } from '@/convex/approvals/types';
 import { useT } from '@/lib/i18n/client';
-import { cn } from '@/lib/utils/cn';
+
+import { ApprovalCard } from './approval-card';
 
 interface KnowledgeWriteApprovalCardProps {
   approvalId: Id<'approvals'>;
@@ -102,12 +103,7 @@ function KnowledgeWriteApprovalCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="center" className="mb-2">
         <BookOpen className="text-primary size-4 shrink-0" />
@@ -212,7 +208,6 @@ function KnowledgeWriteApprovalCardComponent({
             }
           >
             <Button
-              size="sm"
               variant="primary"
               onClick={handleApprove}
               disabled={isProcessing}
@@ -225,7 +220,6 @@ function KnowledgeWriteApprovalCardComponent({
 
           <Tooltip content={t('rejectTooltip')}>
             <Button
-              size="sm"
               variant="secondary"
               onClick={handleReject}
               disabled={isProcessing}
@@ -266,7 +260,7 @@ function KnowledgeWriteApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/legal-hold-indicator.tsx b/services/platform/app/features/chat/components/legal-hold-indicator.tsx
index 1ea9d1ed6d..2afa05fed4 100644
--- a/services/platform/app/features/chat/components/legal-hold-indicator.tsx
+++ b/services/platform/app/features/chat/components/legal-hold-indicator.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Lock } from 'lucide-react';
 
 import { Tooltip } from '@/app/components/ui/overlays/tooltip';
@@ -75,7 +76,7 @@ export function LegalHoldIndicator({
       side="right"
       contentClassName="max-w-xs"
       content={
-        <div className="flex flex-col gap-1 p-1 text-left">
+        <Stack gap={1} className="p-1 text-left">
           <div className="text-xs font-medium">{heading}</div>
           <div className="text-[11px] opacity-90">{body}</div>
           {adminDetails && adminDetails.length > 0 && (
@@ -88,7 +89,7 @@ export function LegalHoldIndicator({
               ))}
             </dl>
           )}
-        </div>
+        </Stack>
       }
     >
       <button
diff --git a/services/platform/app/features/chat/components/location-request-card.tsx b/services/platform/app/features/chat/components/location-request-card.tsx
index adfc313d11..7f8c1474ee 100644
--- a/services/platform/app/features/chat/components/location-request-card.tsx
+++ b/services/platform/app/features/chat/components/location-request-card.tsx
@@ -11,11 +11,11 @@ import { useFormatDate } from '@/app/hooks/use-format-date';
 import type { Id } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
 import type { LocationRequestMetadata } from '@/lib/shared/schemas/approvals';
-import { cn } from '@/lib/utils/cn';
 
 import { useChatLayout } from '../context/chat-layout-context';
 import { useSubmitLocationResponse } from '../hooks/mutations';
 import { useEffectiveAgent } from '../hooks/use-effective-agent';
+import { ApprovalCard } from './approval-card';
 
 // No reverse-geocoding: resolving coords to an address would require a
 // third-party service (previously nominatim.openstreetmap.org), which breaks
@@ -149,12 +149,7 @@ function LocationRequestCardComponent({
   const isDisabled = isAcquiring || isSubmitting;
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-5 bg-card w-full max-w-xl',
-        className,
-      )}
-    >
+    <ApprovalCard maxWidth="xl" padding="lg" className={className}>
       {/* Header */}
       <HStack gap={3} align="center" className="mb-4">
         <MapPin className="text-primary size-5 shrink-0" />
@@ -253,7 +248,7 @@ function LocationRequestCardComponent({
           </HStack>
         </Stack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/memory-proposal-card.tsx b/services/platform/app/features/chat/components/memory-proposal-card.tsx
index 1b37c78026..b26b8a3d7d 100644
--- a/services/platform/app/features/chat/components/memory-proposal-card.tsx
+++ b/services/platform/app/features/chat/components/memory-proposal-card.tsx
@@ -1,7 +1,8 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { ConvexError } from 'convex/values';
+import { Card } from '@tale/ui/card';
+import { Row } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { Textarea } from '@/app/components/ui/forms/textarea';
@@ -12,6 +13,7 @@ import {
 import { useToast } from '@/app/hooks/use-toast';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
+import { convexErrorMessage } from '@/lib/utils/convex-error';
 
 const CARD_TEXTAREA_MAX = 800;
 
@@ -36,7 +38,7 @@ export function MemoryProposalCard({ memory }: MemoryProposalCardProps) {
       toast({ title: t('toasts.saved') });
     } catch (err) {
       toast({
-        title: errorMessage(err, t('errors.saveFailed')),
+        title: convexErrorMessage(err, t('errors.saveFailed')),
         variant: 'destructive',
       });
     }
@@ -48,15 +50,15 @@ export function MemoryProposalCard({ memory }: MemoryProposalCardProps) {
       toast({ title: t('toasts.discarded') });
     } catch (err) {
       toast({
-        title: errorMessage(err, t('errors.saveFailed')),
+        title: convexErrorMessage(err, t('errors.saveFailed')),
         variant: 'destructive',
       });
     }
   };
 
   return (
-    <div className="bg-card rounded-md border p-3">
-      <div className="text-muted-foreground mb-1 text-xs font-medium">
+    <Card padding="sm">
+      <div className="text-fg-muted mb-1 text-xs font-medium">
         💡 {t('card.label')}
       </div>
       {editing ? (
@@ -70,11 +72,10 @@ export function MemoryProposalCard({ memory }: MemoryProposalCardProps) {
       ) : (
         <p className="mb-2 text-sm">{memory.content}</p>
       )}
-      <div className="flex justify-end gap-2">
+      <Row gap={2} align="stretch" justify="end">
         {editing ? (
           <>
             <Button
-              size="sm"
               variant="ghost"
               onClick={() => {
                 setEditing(false);
@@ -84,7 +85,6 @@ export function MemoryProposalCard({ memory }: MemoryProposalCardProps) {
               {t('card.discard')}
             </Button>
             <Button
-              size="sm"
               variant="primary"
               disabled={!draft.trim() || draft === memory.content}
               onClick={() => handleApprove(draft)}
@@ -94,37 +94,18 @@ export function MemoryProposalCard({ memory }: MemoryProposalCardProps) {
           </>
         ) : (
           <>
-            <Button size="sm" variant="ghost" onClick={handleDismiss}>
+            <Button variant="ghost" onClick={handleDismiss}>
               {t('card.discard')}
             </Button>
-            <Button
-              size="sm"
-              variant="secondary"
-              onClick={() => setEditing(true)}
-            >
+            <Button variant="secondary" onClick={() => setEditing(true)}>
               {t('card.edit')}
             </Button>
-            <Button size="sm" variant="primary" onClick={() => handleApprove()}>
+            <Button variant="primary" onClick={() => handleApprove()}>
               {t('card.save')}
             </Button>
           </>
         )}
-      </div>
-    </div>
+      </Row>
+    </Card>
   );
 }
-
-function errorMessage(err: unknown, fallback: string): string {
-  if (err instanceof ConvexError) {
-    const data: unknown = err.data;
-    if (
-      data !== null &&
-      typeof data === 'object' &&
-      'message' in data &&
-      typeof data.message === 'string'
-    ) {
-      return data.message;
-    }
-  }
-  return fallback;
-}
diff --git a/services/platform/app/features/chat/components/message-bubble.tsx b/services/platform/app/features/chat/components/message-bubble.tsx
index f5cd88367c..3a6b833653 100644
--- a/services/platform/app/features/chat/components/message-bubble.tsx
+++ b/services/platform/app/features/chat/components/message-bubble.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuGroup } from '@tale/ui/dropdown-menu';
+import { Row, Stack } from '@tale/ui/layout';
 import {
   CopyIcon,
   CheckIcon,
@@ -688,6 +689,7 @@ function MessageBubbleComponent({
       <Button
         variant="ghost"
         size="icon"
+        aria-label={t('actions.showInfo')}
         className="p-1"
         onClick={handleInfoClick}
         data-testid="message-info-button"
@@ -765,7 +767,10 @@ function MessageBubbleComponent({
                     displayContent
                   )}
                 </p>
-              ) : (
+              ) : message.isFailed ? null : (
+                // Failed turns render only <ChatErrorDisplay/> below — the saved
+                // content is just an error sentence (kept for non-chat surfaces)
+                // and would duplicate the localized hint.
                 <CitationsContext.Provider value={citationsContextValue}>
                   {/*
                    * Voice-output indicator: lifted to the TOP of the
@@ -782,7 +787,7 @@ function MessageBubbleComponent({
                    * then renders with no extra chrome.
                    */}
                   {voiceIndicatorEnabled && message.threadId && (
-                    <div className="mb-2 flex items-center justify-start">
+                    <Row gap={0} className="mb-2">
                       <VoiceOutputIndicator
                         enabled
                         messageId={message.id}
@@ -791,7 +796,7 @@ function MessageBubbleComponent({
                         organizationId={organizationId}
                         isFreshSinceMount={isFreshSinceMount}
                       />
-                    </div>
+                    </Row>
                   )}
                   <MessageSegments
                     segments={messageSegments.segments}
@@ -815,18 +820,15 @@ function MessageBubbleComponent({
                     />
                   )}
                   {showTrailingLoader && (
-                    <div
-                      className="mt-2 flex h-5 items-center"
-                      aria-hidden="true"
-                    >
+                    <Row gap={0} className="mt-2 h-5" aria-hidden="true">
                       <ThinkingDots />
-                    </div>
+                    </Row>
                   )}
                 </CitationsContext.Provider>
               )}
             </div>
             {isUser && (isOverflowing || isExpanded) && (
-              <div className="flex justify-end">
+              <Row gap={0} align="stretch" justify="end">
                 <button
                   type="button"
                   onClick={() => setIsExpanded((v) => !v)}
@@ -834,7 +836,7 @@ function MessageBubbleComponent({
                 >
                   {isExpanded ? tChat('showLess') : tChat('showMore')}
                 </button>
-              </div>
+              </Row>
             )}
             {message.isFailed && (
               <ChatErrorDisplay error={message.error} onRetry={onRetry} />
@@ -853,7 +855,7 @@ function MessageBubbleComponent({
         )}
 
         {message.fileParts && message.fileParts.length > 0 && (
-          <div className="mt-2 flex flex-col gap-2">
+          <Stack gap={2} className="mt-2">
             {message.fileParts.map((part, i) => {
               const galleryIdx = filePartGalleryIndices[i];
               const isAssistantImage =
@@ -875,11 +877,11 @@ function MessageBubbleComponent({
                 />
               );
             })}
-          </div>
+          </Stack>
         )}
 
         {message.attachments && message.attachments.length > 0 && (
-          <div className="mt-2 flex flex-wrap gap-1">
+          <Row gap={1} align="stretch" wrap className="mt-2">
             {message.attachments.map((attachment, i) => {
               const galleryIdx = attachmentGalleryIndices[i];
               return (
@@ -892,7 +894,7 @@ function MessageBubbleComponent({
                 />
               );
             })}
-          </div>
+          </Row>
         )}
         {/* Errored turn: only Show Info is useful — collapse the toolbar.
             Entrance animation only on a live transition, not on remount. */}
@@ -950,6 +952,9 @@ function MessageBubbleComponent({
                         <Button
                           variant="ghost"
                           size="icon"
+                          aria-label={
+                            isCopied ? t('actions.copied') : t('actions.copy')
+                          }
                           className="p-1"
                           onClick={handleCopy}
                           data-testid="message-copy-button"
@@ -971,6 +976,7 @@ function MessageBubbleComponent({
                           <Button
                             variant="ghost"
                             size="icon"
+                            aria-label={tChat('forkChat')}
                             className="p-1"
                             onClick={handleForkClick}
                           >
@@ -983,7 +989,7 @@ function MessageBubbleComponent({
                   }
                 />
               ) : (
-                <div className="flex items-start gap-1 pt-2">
+                <Row gap={1} align="start" className="pt-2">
                   <Tooltip
                     content={isCopied ? t('actions.copied') : t('actions.copy')}
                     side="bottom"
@@ -991,6 +997,9 @@ function MessageBubbleComponent({
                     <Button
                       variant="ghost"
                       size="icon"
+                      aria-label={
+                        isCopied ? t('actions.copied') : t('actions.copy')
+                      }
                       className="p-1"
                       onClick={handleCopy}
                       data-testid="message-copy-button"
@@ -1008,6 +1017,7 @@ function MessageBubbleComponent({
                       <Button
                         variant="ghost"
                         size="icon"
+                        aria-label={tChat('forkChat')}
                         className="p-1"
                         onClick={handleForkClick}
                       >
@@ -1016,7 +1026,7 @@ function MessageBubbleComponent({
                     </Tooltip>
                   )}
                   {moreMenu}
-                </div>
+                </Row>
               )}
             </div>
           )}
@@ -1068,6 +1078,9 @@ function MessageBubbleComponent({
               <Button
                 variant="ghost"
                 size="icon"
+                aria-label={
+                  isSavedPrompt ? tChat('unsavePrompt') : tChat('savePrompt')
+                }
                 className="size-6 p-1"
                 onClick={handleBookmarkClick}
               >
@@ -1084,6 +1097,7 @@ function MessageBubbleComponent({
               <Button
                 variant="ghost"
                 size="icon"
+                aria-label={tChat('editMessage')}
                 className="size-6 p-1"
                 onClick={handleEditClick}
               >
diff --git a/services/platform/app/features/chat/components/message-bubble/code-block.tsx b/services/platform/app/features/chat/components/message-bubble/code-block.tsx
index 6ee86428bd..04b489baaa 100644
--- a/services/platform/app/features/chat/components/message-bubble/code-block.tsx
+++ b/services/platform/app/features/chat/components/message-bubble/code-block.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { useTheme } from '@tale/ui/theme';
 import { CheckIcon, CopyIcon } from 'lucide-react';
 import {
@@ -160,7 +161,11 @@ export function CodeBlock({
 
   return (
     <div className="border-border bg-background my-4 overflow-hidden rounded-lg border">
-      <div className="border-border flex items-center justify-between border-b px-4 py-2.5">
+      <Row
+        gap={0}
+        justify="between"
+        className="border-border border-b px-4 py-2.5"
+      >
         <span className="text-muted-foreground font-sans text-xs">
           {lang ?? 'code'}
         </span>
@@ -177,7 +182,7 @@ export function CodeBlock({
           )}
           {isCopied ? t('actions.copied') : t('actions.copy')}
         </Button>
-      </div>
+      </Row>
       <pre
         ref={preRef}
         {...props}
diff --git a/services/platform/app/features/chat/components/message-bubble/file-displays.tsx b/services/platform/app/features/chat/components/message-bubble/file-displays.tsx
index 636c6e4ca9..81cbbb0f87 100644
--- a/services/platform/app/features/chat/components/message-bubble/file-displays.tsx
+++ b/services/platform/app/features/chat/components/message-bubble/file-displays.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { VStack } from '@tale/ui/layout';
+import { Row, VStack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -274,7 +274,7 @@ export const FileAttachmentDisplay = memo(function FileAttachmentDisplay({
   if (!displayUrl) {
     return (
       <>
-        <div className="bg-muted flex max-w-[280px] items-center gap-3 rounded-lg px-3 py-2">
+        <Row gap={3} className="bg-muted max-w-[280px] rounded-lg px-3 py-2">
           <FileTypeIcon
             fileType={attachment.fileType}
             fileName={attachment.fileName}
@@ -288,7 +288,7 @@ export const FileAttachmentDisplay = memo(function FileAttachmentDisplay({
             </Text>
           </VStack>
           {viewTranscriptButton}
-        </div>
+        </Row>
         {transcriptDialog}
       </>
     );
@@ -296,7 +296,10 @@ export const FileAttachmentDisplay = memo(function FileAttachmentDisplay({
 
   return (
     <>
-      <div className="bg-muted hover:bg-muted/80 flex max-w-[280px] items-center gap-3 rounded-lg px-3 py-2 transition-colors">
+      <Row
+        gap={3}
+        className="bg-muted hover:bg-muted/80 max-w-[280px] rounded-lg px-3 py-2 transition-colors"
+      >
         <a
           href={displayUrl}
           target="_blank"
@@ -317,7 +320,7 @@ export const FileAttachmentDisplay = memo(function FileAttachmentDisplay({
           </VStack>
         </a>
         {viewTranscriptButton}
-      </div>
+      </Row>
       {transcriptDialog}
     </>
   );
@@ -421,7 +424,10 @@ export const FilePartDisplay = memo(function FilePartDisplay({
 
   return (
     <>
-      <div className="bg-background border-border flex w-full items-center gap-3 rounded-xl border px-4 py-3 shadow-xs">
+      <Row
+        gap={3}
+        className="bg-background border-border w-full rounded-xl border px-4 py-3 shadow-xs"
+      >
         {canPreview ? (
           <button
             type="button"
@@ -431,7 +437,9 @@ export const FilePartDisplay = memo(function FilePartDisplay({
             {body}
           </button>
         ) : (
-          <div className="flex min-w-0 flex-1 items-center gap-3">{body}</div>
+          <Row gap={3} className="min-w-0 flex-1">
+            {body}
+          </Row>
         )}
         <a
           href={filePart.url}
@@ -444,7 +452,7 @@ export const FilePartDisplay = memo(function FilePartDisplay({
         >
           <Download className="size-4" strokeWidth={1.5} />
         </a>
-      </div>
+      </Row>
       {canPreview && previewOpen && (
         <DocumentPreviewDialog
           open
diff --git a/services/platform/app/features/chat/components/message-bubble/image-preview-dialog.tsx b/services/platform/app/features/chat/components/message-bubble/image-preview-dialog.tsx
index 3851286d85..e9dfdccf1e 100644
--- a/services/platform/app/features/chat/components/message-bubble/image-preview-dialog.tsx
+++ b/services/platform/app/features/chat/components/message-bubble/image-preview-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { ChevronLeft, ChevronRight } from 'lucide-react';
 import { memo, useCallback, useEffect, useMemo } from 'react';
@@ -89,21 +90,21 @@ export const ImagePreviewDialog = memo(function ImagePreviewDialog({
         alt={currentAlt}
         toolbarPosition="overlay"
         headerContent={
-          <div className="flex min-w-0 items-center gap-2">
-            <Text as="span" truncate className="text-foreground/80 max-w-[60%]">
+          <Row gap={2} className="min-w-0 flex-1">
+            <Text as="span" truncate className="text-foreground/80 min-w-0">
               {currentAlt}
             </Text>
             {isGallery && (
-              <Text as="span" className="text-foreground/50 text-xs">
+              <Text as="span" className="text-foreground/50 shrink-0 text-xs">
                 {t('imageCounter', {
                   current: safeIndex + 1,
                   total: images?.length ?? 0,
                 })}
               </Text>
             )}
-          </div>
+          </Row>
         }
-        className="flex-1 p-8 pt-16"
+        className="flex-1 p-3"
         resetTrigger={currentSrc}
         // The Dialog renders with `hideClose` + empty customHeader, so the
         // only existing dismiss paths were Esc / backdrop click. Wiring
@@ -115,18 +116,20 @@ export const ImagePreviewDialog = memo(function ImagePreviewDialog({
           <Button
             variant="ghost"
             size="icon"
+            title={t('previousImage')}
+            tooltipSide="right"
             className="bg-background/80 hover:bg-background absolute top-1/2 left-4 z-10 -translate-y-1/2 rounded-full shadow-md"
             onClick={goToPrevious}
-            aria-label={t('previousImage')}
           >
             <ChevronLeft className="size-5" />
           </Button>
           <Button
             variant="ghost"
             size="icon"
+            title={t('nextImage')}
+            tooltipSide="left"
             className="bg-background/80 hover:bg-background absolute top-1/2 right-4 z-10 -translate-y-1/2 rounded-full shadow-md"
             onClick={goToNext}
-            aria-label={t('nextImage')}
           >
             <ChevronRight className="size-5" />
           </Button>
diff --git a/services/platform/app/features/chat/components/message-feedback.tsx b/services/platform/app/features/chat/components/message-feedback.tsx
index 5ac5c44d45..bd930bc61a 100644
--- a/services/platform/app/features/chat/components/message-feedback.tsx
+++ b/services/platform/app/features/chat/components/message-feedback.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { ThumbsUp, ThumbsDown } from 'lucide-react';
 import { ReactNode, useState, useCallback } from 'react';
 
@@ -110,8 +111,8 @@ export function MessageFeedback({
   );
 
   return (
-    <div className="flex flex-col pt-2">
-      <div className="flex items-center gap-1">
+    <Stack gap={0} className="pt-2">
+      <Row gap={1}>
         {before}
         <Tooltip content={t('feedback.thumbsUp')} side="bottom">
           <Button
@@ -152,10 +153,10 @@ export function MessageFeedback({
           </Button>
         </Tooltip>
         {after}
-      </div>
+      </Row>
 
       {showCommentBox && currentRating === 'negative' && (
-        <div className="mt-2 flex max-w-sm flex-col gap-2">
+        <Stack gap={2} className="mt-2 max-w-sm">
           <textarea
             value={comment}
             onChange={(e) => setComment(e.target.value)}
@@ -164,10 +165,9 @@ export function MessageFeedback({
             className="border-border bg-muted text-foreground placeholder:text-muted-foreground min-h-[60px] w-full resize-none rounded-lg border px-3 py-2 text-sm focus:ring-1 focus:ring-offset-0 focus:outline-none"
             aria-label={t('feedback.commentPlaceholder')}
           />
-          <div className="flex gap-2">
+          <Row gap={2} align="stretch">
             <Button
               variant="secondary"
-              size="sm"
               onClick={handleSubmitComment}
               disabled={isSubmitting || !comment.trim()}
             >
@@ -175,7 +175,6 @@ export function MessageFeedback({
             </Button>
             <Button
               variant="ghost"
-              size="sm"
               onClick={() => {
                 setShowCommentBox(false);
                 setComment('');
@@ -183,9 +182,9 @@ export function MessageFeedback({
             >
               {t('feedback.cancel')}
             </Button>
-          </div>
-        </div>
+          </Row>
+        </Stack>
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/message-info-dialog.tsx b/services/platform/app/features/chat/components/message-info-dialog.tsx
index f349751661..ee6d9e6981 100644
--- a/services/platform/app/features/chat/components/message-info-dialog.tsx
+++ b/services/platform/app/features/chat/components/message-info-dialog.tsx
@@ -3,7 +3,7 @@
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
 import { IconButton } from '@tale/ui/icon-button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { type StatGridItem, StatGrid } from '@tale/ui/stat-grid';
 import { Text } from '@tale/ui/text';
 import { useAction } from 'convex/react';
@@ -245,7 +245,7 @@ function DirectTtftProbe({
           Replay agent tools + system prompt
           {agentSlug ? '' : ' (unavailable — no agent on this message)'}
         </label>
-        <Button size="sm" className="w-fit" isLoading={running} onClick={onRun}>
+        <Button className="w-fit" isLoading={running} onClick={onRun}>
           Measure direct TTFT
         </Button>
         {error && (
@@ -738,7 +738,7 @@ export function MessageInfoDialog({
           </Field>
 
           <Field label={t('messageInfo.messageId')}>
-            <div className="flex items-center gap-1">
+            <Row gap={1}>
               <Text
                 as="div"
                 variant="code"
@@ -753,7 +753,7 @@ export function MessageInfoDialog({
                 }
                 onClick={handleCopyId}
               />
-            </div>
+            </Row>
           </Field>
 
           {metadata ? (
diff --git a/services/platform/app/features/chat/components/model-fallback-notice.tsx b/services/platform/app/features/chat/components/model-fallback-notice.tsx
new file mode 100644
index 0000000000..d22dadd4ff
--- /dev/null
+++ b/services/platform/app/features/chat/components/model-fallback-notice.tsx
@@ -0,0 +1,45 @@
+import { AlertTriangle } from 'lucide-react';
+
+import { useT } from '@/lib/i18n/client';
+import { parseModelFallbackBody } from '@/lib/shared/constants/system-message-tags';
+
+interface ModelFallbackNoticeProps {
+  /** The `[MODEL_FALLBACK]` body (structured `from=.. to=.. reason=..`). */
+  body: string;
+}
+
+/** Friendly, qualifier-free model label: `openrouter:anthropic/claude-opus-4.8` → `claude-opus-4.8`. */
+function friendlyModelLabel(ref: string | undefined): string | undefined {
+  if (!ref || ref === 'default') return undefined;
+  const afterProvider = ref.includes(':')
+    ? ref.slice(ref.indexOf(':') + 1)
+    : ref;
+  return afterProvider.includes('/')
+    ? afterProvider.slice(afterProvider.lastIndexOf('/') + 1)
+    : afterProvider;
+}
+
+/**
+ * Renders a `[MODEL_FALLBACK]` system message as a localized one-line warning
+ * ("X was unavailable — switched to Y"). Legacy English-sentence bodies (no
+ * structured fields) render verbatim.
+ */
+export function ModelFallbackNotice({ body }: ModelFallbackNoticeProps) {
+  const { t } = useT('chat');
+  const parsed = parseModelFallbackBody(body);
+
+  const line =
+    !parsed.from && !parsed.to
+      ? body
+      : t('modelFallbackNotice', {
+          from: friendlyModelLabel(parsed.from) ?? t('modelFallbackUnknown'),
+          to: friendlyModelLabel(parsed.to) ?? t('modelFallbackDefaultModel'),
+        });
+
+  return (
+    <div className="text-warning flex items-center gap-1.5 px-4 py-1 text-xs">
+      <AlertTriangle className="size-3.5 shrink-0" aria-hidden="true" />
+      <span>{line}</span>
+    </div>
+  );
+}
diff --git a/services/platform/app/features/chat/components/model-info-popover.tsx b/services/platform/app/features/chat/components/model-info-popover.tsx
index ea4cc85146..f9ec3abcc1 100644
--- a/services/platform/app/features/chat/components/model-info-popover.tsx
+++ b/services/platform/app/features/chat/components/model-info-popover.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { Text } from '@tale/ui/text';
 import { Link } from '@tanstack/react-router';
@@ -26,12 +27,12 @@ interface InfoRowProps {
 
 function InfoRow({ label, children }: InfoRowProps) {
   return (
-    <div className="flex items-start justify-between gap-3">
+    <Row gap={3} align="start" justify="between">
       <Text variant="muted" className="shrink-0 text-xs">
         {label}
       </Text>
       <div className="text-right text-xs">{children}</div>
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/model-selector.tsx b/services/platform/app/features/chat/components/model-selector.tsx
index 69af2884ed..3c89ed8afa 100644
--- a/services/platform/app/features/chat/components/model-selector.tsx
+++ b/services/platform/app/features/chat/components/model-selector.tsx
@@ -357,7 +357,7 @@ export const ModelSelector = memo(function ModelSelector({
       <Button
         type="button"
         className="gap-1.5"
-        size="icon"
+        size="sm"
         variant="ghost"
         aria-label={t('modelSelector.label')}
         disabled
@@ -553,8 +553,8 @@ export const ModelSelector = memo(function ModelSelector({
         <Button
           type="button"
           className="gap-1.5"
-          size="icon"
           variant="ghost"
+          size="sm"
           aria-label={t('modelSelector.label')}
         >
           <Cpu className="size-3.5" aria-hidden="true" />
diff --git a/services/platform/app/features/chat/components/model-tag-icons.tsx b/services/platform/app/features/chat/components/model-tag-icons.tsx
index f28ded54be..ff28731075 100644
--- a/services/platform/app/features/chat/components/model-tag-icons.tsx
+++ b/services/platform/app/features/chat/components/model-tag-icons.tsx
@@ -1,3 +1,4 @@
+import { Row } from '@tale/ui/layout';
 import {
   AudioLines,
   Brain,
@@ -42,7 +43,7 @@ export function ModelTagIcons({ tags, t }: ModelTagIconsProps) {
   if (tags.length === 0) return null;
 
   return (
-    <div className="mt-0.5 flex shrink-0 items-start gap-1">
+    <Row gap={1} align="start" className="mt-0.5 shrink-0">
       {tags.map((tag) => {
         const config = TAG_CONFIG[tag];
         if (!config) return null;
@@ -55,6 +56,6 @@ export function ModelTagIcons({ tags, t }: ModelTagIconsProps) {
           </Tooltip>
         );
       })}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/paginated-markdown-table.tsx b/services/platform/app/features/chat/components/paginated-markdown-table.tsx
index 68af292961..90b3523444 100644
--- a/services/platform/app/features/chat/components/paginated-markdown-table.tsx
+++ b/services/platform/app/features/chat/components/paginated-markdown-table.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Table, TableBody, TableCell } from '@tale/ui/table';
 import { Text } from '@tale/ui/text';
 import { ChevronLeft, ChevronRight } from 'lucide-react';
@@ -151,8 +152,8 @@ export function PaginatedMarkdownTable({
       </Table>
 
       {showPagination && (
-        <div className="border-border bg-background flex items-center gap-5 border-t p-2">
-          <div className="flex items-center gap-3">
+        <Row gap={5} className="border-border bg-background border-t p-2">
+          <Row gap={3}>
             {/* Previous button */}
             <button
               onClick={handlePrevPage}
@@ -183,7 +184,7 @@ export function PaginatedMarkdownTable({
             >
               <ChevronRight className="size-5" />
             </button>
-          </div>
+          </Row>
 
           {/* Page info text */}
           <Text
@@ -197,7 +198,7 @@ export function PaginatedMarkdownTable({
               total: totalRows,
             })}
           </Text>
-        </div>
+        </Row>
       )}
     </div>
   );
diff --git a/services/platform/app/features/chat/components/plan-approval-card.tsx b/services/platform/app/features/chat/components/plan-approval-card.tsx
index 3cad16a220..f6e251e9c2 100644
--- a/services/platform/app/features/chat/components/plan-approval-card.tsx
+++ b/services/platform/app/features/chat/components/plan-approval-card.tsx
@@ -24,6 +24,7 @@ import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
 import { isRecord } from '@/lib/utils/type-utils';
 
+import { ApprovalCard } from './approval-card';
 import { markdownWrapperStyles } from './message-bubble/markdown-renderer';
 
 // Beyond this many rendered lines the tail collapses behind "show more". The
@@ -125,12 +126,7 @@ function PlanApprovalCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'bg-card w-full max-w-2xl overflow-hidden rounded-xl border border-border p-4',
-        className,
-      )}
-    >
+    <ApprovalCard maxWidth="2xl" className={className}>
       <HStack gap={2} align="center" className="mb-2">
         <ClipboardList className="text-primary size-4 shrink-0" />
         <Text as="div" variant="label">
@@ -144,7 +140,6 @@ function PlanApprovalCardComponent({
       </div>
       {collapsible && (
         <Button
-          size="sm"
           variant="ghost"
           className="mb-2 px-2 text-xs"
           onClick={() => setExpanded((v) => !v)}
@@ -175,7 +170,6 @@ function PlanApprovalCardComponent({
               }
             >
               <Button
-                size="sm"
                 variant="primary"
                 onClick={handleApprove}
                 disabled={isProcessing || isGenerating}
@@ -189,7 +183,6 @@ function PlanApprovalCardComponent({
             </Tooltip>
             <Tooltip content={t('rejectTooltip')}>
               <Button
-                size="sm"
                 variant="secondary"
                 onClick={handleReject}
                 disabled={isProcessing || isGenerating}
@@ -225,7 +218,7 @@ function PlanApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/plan-pane/plan-pane.tsx b/services/platform/app/features/chat/components/plan-pane/plan-pane.tsx
index af0399e804..369eb73f74 100644
--- a/services/platform/app/features/chat/components/plan-pane/plan-pane.tsx
+++ b/services/platform/app/features/chat/components/plan-pane/plan-pane.tsx
@@ -2,6 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { useMatch } from '@tanstack/react-router';
 import { PanelRightClose, Telescope, X } from 'lucide-react';
 import { memo, useCallback, useEffect, useRef, useState } from 'react';
@@ -134,8 +135,9 @@ function PlanPaneComponent() {
   }
 
   return (
-    <div
-      className="border-border bg-background relative flex h-full shrink-0 flex-col border-l"
+    <Stack
+      gap={0}
+      className="border-border bg-background relative h-full shrink-0 border-l"
       style={{ width }}
       role="complementary"
       aria-label={t('ariaLabel')}
@@ -149,8 +151,8 @@ function PlanPaneComponent() {
         aria-label={t('paneResizeHandle')}
       />
 
-      <div className="border-border flex items-center justify-between gap-2 border-b p-3">
-        <div className="flex min-w-0 items-center gap-2">
+      <Row gap={2} justify="between" className="border-border border-b p-3">
+        <Row gap={2} className="min-w-0">
           <Telescope className="text-muted-foreground size-4 shrink-0" />
           <span className="truncate text-sm font-medium">{t('title')}</span>
           <Badge variant="outline" className="shrink-0 text-xs">
@@ -161,8 +163,8 @@ function PlanPaneComponent() {
               {t('failedCount', { count: counts.failed })}
             </Badge>
           )}
-        </div>
-        <div className="flex shrink-0 items-center gap-1">
+        </Row>
+        <Row gap={1} className="shrink-0">
           <Tooltip content={t('paneMinimize')} side="bottom">
             <Button
               variant="ghost"
@@ -185,8 +187,8 @@ function PlanPaneComponent() {
               <X className="size-3.5" />
             </Button>
           </Tooltip>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       <div className="min-h-0 flex-1 overflow-y-auto p-3">
         <TodoListCard
@@ -195,7 +197,7 @@ function PlanPaneComponent() {
           className="border-0 shadow-none"
         />
       </div>
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/quoted-reference-chip.tsx b/services/platform/app/features/chat/components/quoted-reference-chip.tsx
index ae4608579c..228f66ff2b 100644
--- a/services/platform/app/features/chat/components/quoted-reference-chip.tsx
+++ b/services/platform/app/features/chat/components/quoted-reference-chip.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { TextQuote, X } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -19,7 +20,11 @@ export function QuotedReferenceChip() {
   if (!quotedText) return null;
 
   return (
-    <div className="border-border bg-muted/60 mb-2 flex items-start gap-2 rounded-lg border px-3 py-2">
+    <Row
+      gap={2}
+      align="start"
+      className="border-border bg-muted/60 mb-2 rounded-lg border px-3 py-2"
+    >
       <TextQuote
         className="text-muted-foreground mt-0.5 size-4 shrink-0"
         aria-hidden="true"
@@ -40,6 +45,6 @@ export function QuotedReferenceChip() {
       >
         <X className="size-3.5" />
       </button>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/sandbox-state-indicator.tsx b/services/platform/app/features/chat/components/sandbox-state-indicator.tsx
index 64445a2e04..158085953c 100644
--- a/services/platform/app/features/chat/components/sandbox-state-indicator.tsx
+++ b/services/platform/app/features/chat/components/sandbox-state-indicator.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row } from '@tale/ui/layout';
 import { AlertTriangle, Box, Loader2, Moon, Pin } from 'lucide-react';
 import type { ComponentType } from 'react';
 
@@ -132,7 +133,7 @@ export function SandboxStateIndicator({
   const accessibleLabel = stateLabel ? `${identity} · ${stateLabel}` : identity;
 
   return (
-    <div className="flex items-center gap-1">
+    <Row gap={1}>
       <Tooltip content={tooltip} side="top" contentClassName="max-w-xs">
         <span
           className="inline-flex shrink-0 cursor-help"
@@ -152,6 +153,6 @@ export function SandboxStateIndicator({
           </span>
         </Tooltip>
       )}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/chat/components/share-chat-dialog.tsx b/services/platform/app/features/chat/components/share-chat-dialog.tsx
index e16503cf97..1fe7554501 100644
--- a/services/platform/app/features/chat/components/share-chat-dialog.tsx
+++ b/services/platform/app/features/chat/components/share-chat-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useNavigate } from '@tanstack/react-router';
 import { Check, Copy, ExternalLink, Link } from 'lucide-react';
@@ -113,7 +114,7 @@ function ShareChatDialogContent({
       icon={<Link className="text-muted-foreground size-5" />}
       size="md"
     >
-      <div className="flex min-w-0 flex-col gap-4 overflow-hidden">
+      <Stack className="min-w-0 overflow-hidden">
         <Switch
           label={t('share.enableSharing')}
           description={t('share.enableSharingDescription')}
@@ -123,7 +124,7 @@ function ShareChatDialogContent({
         />
 
         {isShared && shareToken && (
-          <div className="flex min-w-0 flex-col gap-2">
+          <Stack gap={2} className="min-w-0">
             <Text variant="label" className="text-sm">
               {t('share.linkLabel')}
             </Text>
@@ -138,7 +139,6 @@ function ShareChatDialogContent({
             <div className="flex gap-1.5">
               <Button
                 variant="secondary"
-                size="sm"
                 onClick={handleCopy}
                 className="gap-1.5"
                 aria-label={t('share.copyLink')}
@@ -152,7 +152,6 @@ function ShareChatDialogContent({
               </Button>
               <Button
                 variant="ghost"
-                size="sm"
                 onClick={() => {
                   onOpenChange(false);
                   void navigate({
@@ -173,9 +172,9 @@ function ShareChatDialogContent({
             <Text variant="muted" className="text-xs">
               {t('share.linkHint')}
             </Text>
-          </div>
+          </Stack>
         )}
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/chat/components/shared-chat-view.tsx b/services/platform/app/features/chat/components/shared-chat-view.tsx
index 8a1216d80f..2ee86626c1 100644
--- a/services/platform/app/features/chat/components/shared-chat-view.tsx
+++ b/services/platform/app/features/chat/components/shared-chat-view.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -147,13 +148,13 @@ export function SharedChatView({
   // loading state — render it as real text, never masked.
   if (!isLoading && !sharedThread) {
     return (
-      <div className="flex h-full flex-col items-center justify-center gap-4 p-8">
+      <Stack align="center" justify="center" className="h-full p-8">
         <Text variant="muted">{t('share.notFound')}</Text>
         <Button variant="secondary" onClick={handleBack}>
           <ArrowLeft className="mr-2 size-4" />
           {t('share.backToChat')}
         </Button>
-      </div>
+      </Stack>
     );
   }
 
@@ -163,14 +164,18 @@ export function SharedChatView({
   // inside <Skeletonize loading>. Static labels/headings stay real text.
   return (
     <Skeletonize loading={isLoading}>
-      <div className="flex h-full flex-col">
-        <div className="border-border flex h-13 items-center justify-between border-b px-5">
-          <div className="flex items-center gap-3">
+      <Stack gap={0} className="h-full">
+        <Row
+          gap={0}
+          justify="between"
+          className="border-border h-13 border-b px-5"
+        >
+          <Row gap={3}>
             <Button
               variant="ghost"
               size="icon"
               onClick={handleBack}
-              aria-label={t('share.backToChat')}
+              title={t('share.backToChat')}
             >
               <ArrowLeft className="text-muted-foreground size-5" />
             </Button>
@@ -184,7 +189,7 @@ export function SharedChatView({
                 {t('share.sharedChat')}
               </Text>
             </div>
-          </div>
+          </Row>
           <SkeletonBox>
             <Button
               variant="secondary"
@@ -200,15 +205,19 @@ export function SharedChatView({
               {t('share.forkChat')}
             </Button>
           </SkeletonBox>
-        </div>
+        </Row>
 
         {/* The input footer is a flex SIBLING of the scroller — never inside
             the scroll container — so it cannot move with content. */}
-        <div className="flex h-full min-h-0 flex-1 flex-col">
-          <div className="flex min-h-0 flex-1 flex-col overflow-y-auto scroll-smooth">
-            <div className="flex flex-col overflow-y-visible p-4 sm:p-6">
-              <div
-                className="mx-auto flex w-full max-w-(--chat-max-width) flex-col gap-3 pt-6"
+        <Stack gap={0} className="h-full min-h-0 flex-1">
+          <Stack
+            gap={0}
+            className="min-h-0 flex-1 overflow-y-auto scroll-smooth"
+          >
+            <Stack gap={0} className="overflow-y-visible p-4 sm:p-6">
+              <Stack
+                gap={3}
+                className="mx-auto w-full max-w-(--chat-max-width) pt-6"
                 role="log"
                 aria-live="polite"
                 aria-labelledby={messageHistoryLabelId}
@@ -251,9 +260,9 @@ export function SharedChatView({
                         ))}
                       </div>
                     ))}
-              </div>
-            </div>
-          </div>
+              </Stack>
+            </Stack>
+          </Stack>
 
           <PanelFooter>
             <FileUpload.Root>
@@ -277,8 +286,8 @@ export function SharedChatView({
               {t('share.inputHint')}
             </Text>
           </PanelFooter>
-        </div>
-      </div>
+        </Stack>
+      </Stack>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/chat/components/structured-message/section-renderers.tsx b/services/platform/app/features/chat/components/structured-message/section-renderers.tsx
index d7da4a8bae..279810abb2 100644
--- a/services/platform/app/features/chat/components/structured-message/section-renderers.tsx
+++ b/services/platform/app/features/chat/components/structured-message/section-renderers.tsx
@@ -51,7 +51,6 @@ export const NextStepsSection = memo(
             <Button
               key={item}
               variant="secondary"
-              size="sm"
               className={cn(
                 'h-auto whitespace-normal py-1.5 text-left text-xs',
                 'hover:bg-muted/50',
diff --git a/services/platform/app/features/chat/components/thought-timeline/step-rows.tsx b/services/platform/app/features/chat/components/thought-timeline/step-rows.tsx
index 7fd5e30b7c..d61b1d27cf 100644
--- a/services/platform/app/features/chat/components/thought-timeline/step-rows.tsx
+++ b/services/platform/app/features/chat/components/thought-timeline/step-rows.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import {
   ChevronRight,
   Loader2,
@@ -70,7 +71,7 @@ function StepRow({
   const bodyId = useId();
   const hasExpansion = expandedContent != null;
   return (
-    <div className="flex items-start gap-2 text-sm">
+    <Row gap={2} align="start" className="text-sm">
       <span className="mt-0.5 flex size-4 shrink-0 items-center justify-center">
         {status === 'active' ? (
           <Loader2 className="text-muted-foreground size-3.5 animate-spin" />
@@ -117,7 +118,7 @@ function StepRow({
           </span>
         )}
       </span>
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/thumbnail-picker.tsx b/services/platform/app/features/chat/components/thumbnail-picker.tsx
index b651f33dab..16606be734 100644
--- a/services/platform/app/features/chat/components/thumbnail-picker.tsx
+++ b/services/platform/app/features/chat/components/thumbnail-picker.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Grid } from '@tale/ui/layout';
 import { memo } from 'react';
 
 import type { Id } from '@/convex/_generated/dataModel';
@@ -63,7 +64,7 @@ export const ThumbnailPicker = memo(function ThumbnailPicker({
       <p className="text-muted-foreground mb-2 text-xs font-medium">
         {t('imageEdit.pickAnImage')}
       </p>
-      <div className="grid grid-cols-3 gap-2">
+      <Grid cols={3} gap={2}>
         {displayable.map((img) => {
           const isActive = img.key === activeKey;
           return (
@@ -85,7 +86,7 @@ export const ThumbnailPicker = memo(function ThumbnailPicker({
             </button>
           );
         })}
-      </div>
+      </Grid>
     </div>
   );
 });
diff --git a/services/platform/app/features/chat/components/todo-list-card.tsx b/services/platform/app/features/chat/components/todo-list-card.tsx
index 64a7a8696a..101b331ef2 100644
--- a/services/platform/app/features/chat/components/todo-list-card.tsx
+++ b/services/platform/app/features/chat/components/todo-list-card.tsx
@@ -119,11 +119,11 @@ function TodoListCardComponent({
         </HStack>
       )}
       {(hideHeader || !collapsed) && (
-        <ol className="m-0 flex list-none flex-col gap-0 p-0">
+        <Stack as="ol" gap={0} className="m-0 list-none p-0">
           {todosData.todos.map((todo) => (
             <TodoRow key={todo.id} todo={todo} />
           ))}
-        </ol>
+        </Stack>
       )}
     </div>
   );
@@ -287,7 +287,7 @@ function TodoSourceChips({ sources }: { sources: TodoSource[] }) {
   const visible = expanded ? sources : sources.slice(0, SOURCE_COLLAPSED_LIMIT);
 
   return (
-    <div className="mt-1 flex flex-col gap-1">
+    <Stack gap={1} className="mt-1">
       <div className="flex flex-wrap gap-1.5">
         {visible.map((src, idx) => (
           <TodoSourceChip key={`${src.url}-${idx}`} source={src} />
@@ -313,7 +313,7 @@ function TodoSourceChips({ sources }: { sources: TodoSource[] }) {
           )}
         </button>
       )}
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/video-link-chip.tsx b/services/platform/app/features/chat/components/video-link-chip.tsx
index 9ae0f475af..3566ab1695 100644
--- a/services/platform/app/features/chat/components/video-link-chip.tsx
+++ b/services/platform/app/features/chat/components/video-link-chip.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { AlertCircle, Loader2, RotateCcw, X } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -97,7 +98,7 @@ export function VideoLinkChip({ job, onCancel, onRetry }: VideoLinkChipProps) {
       <span aria-hidden="true" className="shrink-0 text-base leading-none">
         🎬
       </span>
-      <div className="flex min-w-0 flex-1 flex-col">
+      <Stack gap={0} className="min-w-0 flex-1">
         {/* Open-source affordance: when the job carries a sourceUrl,
             wrap the title in an external link so the user can verify
             which video the chip represents after the pasted URL gets
@@ -155,7 +156,7 @@ export function VideoLinkChip({ job, onCancel, onRetry }: VideoLinkChipProps) {
           )}
           <span className="truncate">{statusText}</span>
         </span>
-      </div>
+      </Stack>
       {isFailed && (
         <button
           type="button"
diff --git a/services/platform/app/features/chat/components/virtualized-chat-message-list.tsx b/services/platform/app/features/chat/components/virtualized-chat-message-list.tsx
index b852d407d6..0bdc299ccb 100644
--- a/services/platform/app/features/chat/components/virtualized-chat-message-list.tsx
+++ b/services/platform/app/features/chat/components/virtualized-chat-message-list.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { useVirtualizer } from '@tanstack/react-virtual';
 import {
   useLayoutEffect,
@@ -119,8 +120,9 @@ export function VirtualizedChatMessageList({
     // the user scrolls, and a polite live region here would announce that churn.
     // The stable footer (streaming response / thinking indicator) carries the
     // live region instead, so only genuinely-new content is announced.
-    <div
-      className="mx-auto flex w-full max-w-(--chat-max-width) flex-col [overflow-anchor:none]"
+    <Stack
+      gap={0}
+      className="mx-auto w-full max-w-(--chat-max-width) [overflow-anchor:none]"
       role="log"
       aria-labelledby={labelId}
     >
@@ -154,6 +156,6 @@ export function VirtualizedChatMessageList({
           thinking affordance (see ChatMessages). We must NOT wrap it again here
           or the approval card's internal live region would nest inside ours. */}
       {footer}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/chat/components/welcome-view.tsx b/services/platform/app/features/chat/components/welcome-view.tsx
index e4688e80c6..7b015fc08f 100644
--- a/services/platform/app/features/chat/components/welcome-view.tsx
+++ b/services/platform/app/features/chat/components/welcome-view.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Heading } from '@tale/ui/heading';
+import { Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 
@@ -41,7 +42,7 @@ export function WelcomeView({
 
   return (
     <Skeletonize loading={isLoading} label={t('skeleton.loadingWelcome')}>
-      <div className="mx-auto flex w-full max-w-(--chat-max-width) flex-col gap-6">
+      <Stack gap={6} className="mx-auto w-full max-w-(--chat-max-width)">
         <Heading level={1} weight="semibold" className="text-[1.75rem]">
           <SkeletonBox>
             {hasStarters ? (
@@ -57,7 +58,7 @@ export function WelcomeView({
         </Heading>
 
         {(hasStarters || isLoading) && (
-          <ul className="divide-border flex flex-col divide-y" role="list">
+          <Stack as="ul" gap={0} className="divide-border divide-y" role="list">
             {starters.map((starter, index) => (
               <li key={index} className="py-1">
                 <button
@@ -76,9 +77,9 @@ export function WelcomeView({
                 </button>
               </li>
             ))}
-          </ul>
+          </Stack>
         )}
-      </div>
+      </Stack>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/chat/components/workflow-creation-approval-card.tsx b/services/platform/app/features/chat/components/workflow-creation-approval-card.tsx
index dca783e8ef..8e70cf1bb7 100644
--- a/services/platform/app/features/chat/components/workflow-creation-approval-card.tsx
+++ b/services/platform/app/features/chat/components/workflow-creation-approval-card.tsx
@@ -35,6 +35,7 @@ import { cn } from '@/lib/utils/cn';
 import { isRecord } from '@/lib/utils/type-utils';
 import { slugToUrlParam } from '@/lib/utils/workflow-slug';
 
+import { ApprovalCard } from './approval-card';
 import { markdownWrapperStyles } from './message-bubble/markdown-renderer';
 
 interface WorkflowCreationApprovalCardProps {
@@ -322,12 +323,7 @@ function WorkflowCreationApprovalCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="start" justify="between" className="mb-3">
         <HStack gap={2}>
@@ -531,7 +527,6 @@ function WorkflowCreationApprovalCardComponent({
         <ActionRow gap={2}>
           <Tooltip content={t('approveTooltip')}>
             <Button
-              size="sm"
               variant="primary"
               onClick={handleApprove}
               disabled={isProcessing}
@@ -544,7 +539,6 @@ function WorkflowCreationApprovalCardComponent({
 
           <Tooltip content={t('rejectTooltip')}>
             <Button
-              size="sm"
               variant="secondary"
               onClick={handleReject}
               disabled={isProcessing}
@@ -583,7 +577,7 @@ function WorkflowCreationApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/components/workflow-run-approval-card.tsx b/services/platform/app/features/chat/components/workflow-run-approval-card.tsx
index cfbdba1365..4ff6b68216 100644
--- a/services/platform/app/features/chat/components/workflow-run-approval-card.tsx
+++ b/services/platform/app/features/chat/components/workflow-run-approval-card.tsx
@@ -49,6 +49,7 @@ import { cn } from '@/lib/utils/cn';
 import { stripLeadingPunctuation } from '@/lib/utils/string';
 import { slugToUrlParam } from '@/lib/utils/workflow-slug';
 
+import { ApprovalCard } from './approval-card';
 import { HumanInputFields } from './human-input-fields';
 import { markdownWrapperStyles } from './message-bubble/markdown-renderer';
 
@@ -212,12 +213,7 @@ function WorkflowRunApprovalCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="start" justify="between" className="mb-3">
         <HStack gap={2}>
@@ -457,7 +453,6 @@ function WorkflowRunApprovalCardComponent({
         <ActionRow gap={2}>
           <Tooltip content={t('approveTooltip')}>
             <Button
-              size="sm"
               variant="primary"
               onClick={handleApprove}
               disabled={isProcessing}
@@ -472,7 +467,6 @@ function WorkflowRunApprovalCardComponent({
 
           <Tooltip content={t('rejectTooltip')}>
             <Button
-              size="sm"
               variant="secondary"
               onClick={handleReject}
               disabled={isProcessing}
@@ -538,7 +532,7 @@ function WorkflowRunApprovalCardComponent({
           </HStack>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
@@ -695,7 +689,6 @@ function WorkflowHumanInputSection({
           <HStack gap={2}>
             <Button
               variant="secondary"
-              size="sm"
               onClick={() => setShowFeedback(false)}
               disabled={isSubmitting}
               className="flex-1"
@@ -705,7 +698,6 @@ function WorkflowHumanInputSection({
             </Button>
             <Button
               variant="secondary"
-              size="sm"
               onClick={handleSubmitFeedback}
               disabled={isSubmitting}
               className="flex-1"
@@ -730,7 +722,6 @@ function WorkflowHumanInputSection({
           <Button
             onClick={handleSubmit}
             disabled={isSubmitting}
-            size="sm"
             className="w-full"
           >
             {isSubmitting ? (
diff --git a/services/platform/app/features/chat/components/workflow-update-approval-card.tsx b/services/platform/app/features/chat/components/workflow-update-approval-card.tsx
index 587758afdd..44b66d6a27 100644
--- a/services/platform/app/features/chat/components/workflow-update-approval-card.tsx
+++ b/services/platform/app/features/chat/components/workflow-update-approval-card.tsx
@@ -35,6 +35,8 @@ import { cn } from '@/lib/utils/cn';
 import { isRecord } from '@/lib/utils/type-utils';
 import { slugToUrlParam } from '@/lib/utils/workflow-slug';
 
+import { ApprovalCard } from './approval-card';
+
 interface WorkflowUpdateApprovalCardProps {
   approvalId: Id<'approvals'>;
   organizationId: string;
@@ -172,12 +174,7 @@ function WorkflowUpdateApprovalCardComponent({
   };
 
   return (
-    <div
-      className={cn(
-        'rounded-xl border border-border p-4 bg-card max-w-md overflow-hidden',
-        className,
-      )}
-    >
+    <ApprovalCard className={className}>
       {/* Header */}
       <HStack gap={2} align="start" justify="between" className="mb-2">
         <HStack gap={2}>
@@ -393,7 +390,6 @@ function WorkflowUpdateApprovalCardComponent({
         <ActionRow gap={2}>
           <Tooltip content={t('approveTooltip')}>
             <Button
-              size="sm"
               variant="primary"
               onClick={handleApprove}
               disabled={isProcessing}
@@ -406,7 +402,6 @@ function WorkflowUpdateApprovalCardComponent({
 
           <Tooltip content={t('rejectTooltip')}>
             <Button
-              size="sm"
               variant="secondary"
               onClick={handleReject}
               disabled={isProcessing}
@@ -445,7 +440,7 @@ function WorkflowUpdateApprovalCardComponent({
           </Badge>
         </HStack>
       )}
-    </div>
+    </ApprovalCard>
   );
 }
 
diff --git a/services/platform/app/features/chat/context/chat-layout-context.tsx b/services/platform/app/features/chat/context/chat-layout-context.tsx
index 6c4128d98f..0a86be0bd5 100644
--- a/services/platform/app/features/chat/context/chat-layout-context.tsx
+++ b/services/platform/app/features/chat/context/chat-layout-context.tsx
@@ -46,7 +46,10 @@ export interface SelectedAgent {
 
 /**
  * Default composer selection: pin the general-purpose chat agent rather than
- * Auto. New sessions (no persisted choice) open on the Assistant; users can
+ * Auto. New sessions (no persisted choice) open on the Assistant because it's
+ * faster — Auto must first run a routing classifier to decide which agent
+ * should answer (extra latency before the first token), whereas the Assistant
+ * is suitable for most messages and starts replying immediately. Users can
  * still switch to Auto or any specialist. `displayName` here is only a fallback
  * label — the selector renders the catalogue-resolved (localized) name once the
  * agent list loads, so this placeholder is never user-visible in practice.
diff --git a/services/platform/app/features/chat/hooks/use-message-processing.ts b/services/platform/app/features/chat/hooks/use-message-processing.ts
index cf00a9541d..fcf5c5f233 100644
--- a/services/platform/app/features/chat/hooks/use-message-processing.ts
+++ b/services/platform/app/features/chat/hooks/use-message-processing.ts
@@ -4,7 +4,10 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { api } from '@/convex/_generated/api';
 import type { Id } from '@/convex/_generated/dataModel';
-import type { SystemMessageDisplay } from '@/lib/shared/constants/system-message-tags';
+import type {
+  SystemMessageDisplay,
+  SystemMsgTag,
+} from '@/lib/shared/constants/system-message-tags';
 import {
   getSystemMessageDisplay,
   parseSystemMessageTag,
@@ -85,6 +88,7 @@ export interface ChatMessage {
   error?: string;
   systemMessageDisplay?: SystemMessageDisplay;
   systemMessageBody?: string;
+  systemMessageTag?: SystemMsgTag;
   /** Raw UIMessage parts (reasoning + tool calls) for the thought-process
    *  timeline. Present on assistant messages; undefined elsewhere. */
   parts?: UIMessage['parts'];
@@ -126,6 +130,7 @@ function chatMessageRenderEqual(a: ChatMessage, b: ChatMessage): boolean {
     a.error === b.error &&
     a.systemMessageDisplay === b.systemMessageDisplay &&
     a.systemMessageBody === b.systemMessageBody &&
+    a.systemMessageTag === b.systemMessageTag &&
     sameParts(a.parts, b.parts) &&
     sameAttachments(a.attachments, b.attachments) &&
     sameFileParts(a.fileParts, b.fileParts)
@@ -401,10 +406,12 @@ export function useMessageProcessing(
 
         let systemMessageDisplay: SystemMessageDisplay | undefined;
         let systemMessageBody: string | undefined;
+        let systemMessageTag: SystemMsgTag | undefined;
         if (m.role === 'system' && m.text) {
           const parsed = parseSystemMessageTag(m.text);
           systemMessageDisplay = getSystemMessageDisplay(parsed.tag);
           systemMessageBody = parsed.body;
+          systemMessageTag = parsed.tag ?? undefined;
         }
 
         currentKeys.add(m.key);
@@ -503,6 +510,7 @@ export function useMessageProcessing(
               : undefined),
           systemMessageDisplay,
           systemMessageBody,
+          systemMessageTag,
         };
       });
 
diff --git a/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.test.ts b/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.test.ts
index 7475a5d33a..48c6d57173 100644
--- a/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.test.ts
+++ b/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.test.ts
@@ -2,6 +2,11 @@
 import { renderHook } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import {
+  formatModelFallbackBody,
+  SYSTEM_MSG_TAG,
+} from '@/lib/shared/constants/system-message-tags';
+
 import type { ChatMessage } from './use-message-processing';
 import { useModelFallbackAutoSwitch } from './use-model-fallback-auto-switch';
 
@@ -19,7 +24,12 @@ const fallback = (id: string, model: string): ChatMessage =>
   msg({
     id,
     role: 'system',
-    content: `[MODEL_FALLBACK] gpt-5 failed — retrying with ${model}.`,
+    systemMessageTag: SYSTEM_MSG_TAG.MODEL_FALLBACK,
+    systemMessageBody: formatModelFallbackBody({
+      from: 'gpt-5',
+      to: model,
+      reason: 'provider_unreachable',
+    }),
   });
 
 const assistant = (id: string): ChatMessage =>
diff --git a/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.ts b/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.ts
index dd0bb1c4d8..873667bda0 100644
--- a/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.ts
+++ b/services/platform/app/features/chat/hooks/use-model-fallback-auto-switch.ts
@@ -1,5 +1,10 @@
 import { useEffect, useRef } from 'react';
 
+import {
+  parseModelFallbackBody,
+  SYSTEM_MSG_TAG,
+} from '@/lib/shared/constants/system-message-tags';
+
 import type { ChatMessage } from './use-message-processing';
 
 interface UseModelFallbackAutoSwitchParams {
@@ -12,12 +17,11 @@ interface UseModelFallbackAutoSwitchParams {
 }
 
 /**
- * Auto-switch the model selector after a successful fallback, extracted from
- * ChatInterface.
+ * Auto-switch the model selector after a successful fallback.
  *
- * Watches messages reactively: when a `[MODEL_FALLBACK]` "retrying with X"
- * message is followed by a successful assistant response, update the selector
- * so future messages use the working model.
+ * Watches messages reactively: when a `[MODEL_FALLBACK]` notice is followed by a
+ * successful assistant response, pin the selector to the model that worked
+ * (the notice's structured `to` field) so future messages use it.
  *
  * The `isLoading` guard makes this only scan once a response has ended — the
  * detection requires "a successful assistant message AFTER the fallback", which
@@ -39,22 +43,15 @@ export function useModelFallbackAutoSwitch({
     if (isLoading) return;
     if (!agentName || !messages.length) return;
 
-    // Find the latest MODEL_FALLBACK "retrying with" message
+    // Find the latest model-fallback notice.
     const fallbackMsg = messages
       .toReversed()
-      .find(
-        (msg) =>
-          msg.role === 'system' &&
-          msg.content?.includes('[MODEL_FALLBACK]') &&
-          msg.content?.includes('retrying with'),
-      );
-    if (
-      !fallbackMsg?.content ||
-      fallbackMsg.id === lastProcessedFallbackRef.current
-    )
+      .find((msg) => msg.systemMessageTag === SYSTEM_MSG_TAG.MODEL_FALLBACK);
+    if (!fallbackMsg || fallbackMsg.id === lastProcessedFallbackRef.current) {
       return;
+    }
 
-    // Only switch after a successful assistant message appears after the fallback
+    // Only switch once a successful assistant message follows the fallback.
     const fallbackIdx = messages.findIndex((msg) => msg.id === fallbackMsg.id);
     const hasSuccessAfter = messages
       .slice(fallbackIdx + 1)
@@ -63,16 +60,14 @@ export function useModelFallbackAutoSwitch({
 
     lastProcessedFallbackRef.current = fallbackMsg.id;
 
-    // Extract target model: "X failed — retrying with <model>."
-    // Greedy match up to the trailing period to handle dots in model
-    // names (e.g. "moonshotai/kimi-k2.5").
-    const match = fallbackMsg.content.match(/retrying with (.+)\./);
-    if (!match) return;
+    const { to } = parseModelFallbackBody(
+      fallbackMsg.systemMessageBody ?? fallbackMsg.content ?? '',
+    );
+    // `to === 'default'` is the tag-default (no concrete ref to pin) — skip.
+    if (!to || to === 'default') return;
 
-    const successfulModel = match[1];
-    const currentSelected = selectedModelOverrides[agentName];
-    if (successfulModel && successfulModel !== currentSelected) {
-      setSelectedModelOverride(agentName, successfulModel);
+    if (to !== selectedModelOverrides[agentName]) {
+      setSelectedModelOverride(agentName, to);
     }
   }, [
     messages,
diff --git a/services/platform/app/features/chat/hooks/use-send-message.ts b/services/platform/app/features/chat/hooks/use-send-message.ts
index 97bbb5cfca..106e2d3e96 100644
--- a/services/platform/app/features/chat/hooks/use-send-message.ts
+++ b/services/platform/app/features/chat/hooks/use-send-message.ts
@@ -104,6 +104,47 @@ function isKbRefInvalidError(error: unknown): boolean {
   return data.code === 'KB_REF_INVALID';
 }
 
+/**
+ * `chatWithAgentTurn` throws `BACKEND_DRAINING` while a `tale deploy` is
+ * draining the convex backend before recreating it (the new-turn gate). It's
+ * transient — the backend accepts turns again within seconds once the restart
+ * settles — so the send auto-retries rather than surfacing an error.
+ */
+function isBackendDrainingError(error: unknown): boolean {
+  if (!(error instanceof ConvexError)) return false;
+  const data: unknown = error.data;
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'code' in data &&
+    data.code === 'BACKEND_DRAINING'
+  );
+}
+
+const DRAIN_RETRY_MAX = 8;
+const DRAIN_RETRY_DELAY_MS = 2_000;
+
+/**
+ * Retry `fn` while it throws `BACKEND_DRAINING` (a deploy drain window),
+ * bounded so a long drain doesn't hang the composer indefinitely — on exhaust
+ * the error propagates to the normal send-failure handling (friendly toast).
+ */
+async function withBackendDrainRetry<T>(fn: () => Promise<T>): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt < DRAIN_RETRY_MAX && isBackendDrainingError(error)) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, DRAIN_RETRY_DELAY_MS),
+        );
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
 /** Derive a thread title from the first message, truncating long input. */
 function buildThreadTitle(message: string): string {
   return message.length > 50 ? message.slice(0, 50) + '...' : message;
@@ -758,22 +799,25 @@ export function useSendMessage({
           markPending(tIdA);
           markPending(tIdB);
 
-          // Start both models generating (split view shows "Thinking")
-          await arenaChatRef.current({
-            // Guarded above: arena requires a pinned agent, so this is never
-            // the Auto sentinel here.
-            agentSlug: agentSlugToSend,
-            threadIdA: tIdA,
-            threadIdB: tIdB,
-            organizationId,
-            message: messageToSend,
-            modelIdA: modelA,
-            modelIdB: modelB,
-            attachments: mutationAttachments,
-            userContext: userContextPayload,
-            // History is copied when Thread B is created (arena enable),
-            // not at send time — no need to copy again.
-          });
+          // Start both models generating (split view shows "Thinking").
+          // Retry through a deploy drain window (transient BACKEND_DRAINING).
+          await withBackendDrainRetry(() =>
+            arenaChatRef.current({
+              // Guarded above: arena requires a pinned agent, so this is never
+              // the Auto sentinel here.
+              agentSlug: agentSlugToSend,
+              threadIdA: tIdA,
+              threadIdB: tIdB,
+              organizationId,
+              message: messageToSend,
+              modelIdA: modelA,
+              modelIdB: modelB,
+              attachments: mutationAttachments,
+              userContext: userContextPayload,
+              // History is copied when Thread B is created (arena enable),
+              // not at send time — no need to copy again.
+            }),
+          );
         } else {
           // --- Standard mode: send to one model ---
           let currentThreadId = threadId;
@@ -904,26 +948,34 @@ export function useSendMessage({
           // isThreadGenerating takes over once it arrives.
           markPending(currentThreadId);
 
-          await chatWithAgent({
-            agentSlug: agentSlugToSend,
-            threadId: currentThreadId,
-            organizationId,
-            message: messageToSend,
-            modelId: modelId || undefined,
-            capabilityBindings:
-              enabledCapabilities.length > 0 ? enabledCapabilities : undefined,
-            attachments: mutationAttachments,
-            // `@`-mention KB pins. Server-resolved (access + RAG status), so
-            // only the document ids travel — never client-supplied fileIds.
-            referencedDocumentIds,
-            userContext: userContextPayload,
-            // projectId from URL query is a string; chatWithAgent expects
-            // an Id<'projects'>. The branding is structural-only TS; server
-            // validates it via assertProjectAccessForChat. We use the
-            // dedicated `asProjectId` helper to keep the lint-disable in
-            // one place (see features/projects/hooks/use-project-id-param.ts).
-            projectId: projectId ? asProjectId(projectId) : undefined,
-          });
+          // Capture into a const so the narrowed `string` type survives inside
+          // the retry closure (a `let` widens back to `string | undefined`).
+          const threadIdForSend = currentThreadId;
+          // Retry through a deploy drain window (transient BACKEND_DRAINING).
+          await withBackendDrainRetry(() =>
+            chatWithAgent({
+              agentSlug: agentSlugToSend,
+              threadId: threadIdForSend,
+              organizationId,
+              message: messageToSend,
+              modelId: modelId || undefined,
+              capabilityBindings:
+                enabledCapabilities.length > 0
+                  ? enabledCapabilities
+                  : undefined,
+              attachments: mutationAttachments,
+              // `@`-mention KB pins. Server-resolved (access + RAG status), so
+              // only the document ids travel — never client-supplied fileIds.
+              referencedDocumentIds,
+              userContext: userContextPayload,
+              // projectId from URL query is a string; chatWithAgent expects
+              // an Id<'projects'>. The branding is structural-only TS; server
+              // validates it via assertProjectAccessForChat. We use the
+              // dedicated `asProjectId` helper to keep the lint-disable in
+              // one place (see features/projects/hooks/use-project-id-param.ts).
+              projectId: projectId ? asProjectId(projectId) : undefined,
+            }),
+          );
         }
       } catch (error) {
         console.error('Failed to send message:', error);
@@ -979,7 +1031,13 @@ export function useSendMessage({
 
         let title = t('toast.sendFailed');
         let description = errorMessage;
-        if (
+        if (isBackendDrainingError(error)) {
+          // Drain outlasted the retry budget — the backend is mid-restart
+          // (deploy). Tell the user to resend in a moment rather than show a
+          // raw error; their in-flight turn (if any) is recovered server-side.
+          title = t('toast.backendRestarting');
+          description = t('toast.backendRestartingDescription');
+        } else if (
           blockedCode === 'pii.blocked' ||
           errorMessage.includes('Message blocked: PII')
         ) {
diff --git a/services/platform/app/features/chat/hooks/use-textarea-token-rects.ts b/services/platform/app/features/chat/hooks/use-textarea-token-rects.ts
new file mode 100644
index 0000000000..21432a89d6
--- /dev/null
+++ b/services/platform/app/features/chat/hooks/use-textarea-token-rects.ts
@@ -0,0 +1,168 @@
+'use client';
+
+import { useLayoutEffect, useState, type RefObject } from 'react';
+
+// CSS properties the mirror must copy from the textarea so its text wraps and
+// measures identically. Kebab-case so they copy via get/setProperty without an
+// unsafe cast on CSSStyleDeclaration.
+const COPIED_STYLE_PROPS = [
+  'box-sizing',
+  'padding-top',
+  'padding-right',
+  'padding-bottom',
+  'padding-left',
+  'border-top-width',
+  'border-right-width',
+  'border-bottom-width',
+  'border-left-width',
+  'font-family',
+  'font-size',
+  'font-weight',
+  'font-style',
+  'font-variant',
+  'font-stretch',
+  'line-height',
+  'letter-spacing',
+  'text-transform',
+  'text-indent',
+  'word-spacing',
+  'word-break',
+  'tab-size',
+] as const;
+
+export interface TokenRect {
+  id: number;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface TokenLayout {
+  /**
+   * The textarea's box within its positioned ancestor. The overlay layer is
+   * sized/placed to match, so token coords are textarea-content-relative.
+   */
+  layer: { left: number; top: number; width: number; height: number };
+  /** Token rects relative to the layer, already adjusted for textarea scroll. */
+  tokens: TokenRect[];
+}
+
+/**
+ * Measure the on-screen rect of every `[N]` token inside a plain `<textarea>`.
+ *
+ * A textarea exposes no range geometry, so we mirror its text into an
+ * off-screen `<div>` that copies the textarea's box + typography, wrap each
+ * token in a `<span>`, and read the spans' offsets. Re-measures on value
+ * change, textarea scroll, and resize. Returns `null` while inactive or before
+ * the first measure. Assumes the textarea has zero padding (the composer
+ * does) — non-zero padding would need to be folded into `layer`.
+ */
+export function useTextareaTokenRects(
+  textareaRef: RefObject<HTMLTextAreaElement | null>,
+  value: string,
+  active: boolean,
+): TokenLayout | null {
+  const [layout, setLayout] = useState<TokenLayout | null>(null);
+
+  useLayoutEffect(() => {
+    if (!active || !textareaRef.current) {
+      setLayout(null);
+      return undefined;
+    }
+    const textarea = textareaRef.current;
+    let mirror: HTMLDivElement | null = null;
+
+    const measure = () => {
+      const ta = textareaRef.current;
+      if (!ta) return;
+      if (!mirror) {
+        mirror = document.createElement('div');
+        mirror.setAttribute('aria-hidden', 'true');
+        const s = mirror.style;
+        s.position = 'absolute';
+        s.top = '0';
+        s.left = '0';
+        s.visibility = 'hidden';
+        s.pointerEvents = 'none';
+        s.whiteSpace = 'pre-wrap';
+        s.overflowWrap = 'break-word';
+        s.overflow = 'hidden';
+        document.body.appendChild(mirror);
+      }
+      const cs = getComputedStyle(ta);
+      for (const prop of COPIED_STYLE_PROPS) {
+        mirror.style.setProperty(prop, cs.getPropertyValue(prop));
+      }
+      // clientWidth is the padding box minus any scrollbar — the wrap width the
+      // textarea actually uses. With border-box + the copied padding, the
+      // mirror's content area equals the textarea's.
+      mirror.style.boxSizing = 'border-box';
+      mirror.style.width = `${ta.clientWidth}px`;
+
+      // Rebuild content: text nodes + one <span> per token. textContent only
+      // (never innerHTML) — bracket chars are plain text, no escaping concerns.
+      // The span covers `[N]` AND its trailing reserve spaces so the chip's
+      // measured footprint matches the room reserved for it in the text.
+      mirror.textContent = '';
+      const spans: HTMLSpanElement[] = [];
+      const ids: number[] = [];
+      const re = /\[(\d+)\] */g;
+      let lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(value)) !== null) {
+        if (match.index > lastIndex) {
+          mirror.appendChild(
+            document.createTextNode(value.slice(lastIndex, match.index)),
+          );
+        }
+        const span = document.createElement('span');
+        span.textContent = match[0];
+        mirror.appendChild(span);
+        spans.push(span);
+        ids.push(Number(match[1]));
+        lastIndex = match.index + match[0].length;
+      }
+      if (lastIndex < value.length) {
+        mirror.appendChild(document.createTextNode(value.slice(lastIndex)));
+      }
+      // A trailing newline has no laid-out box without a follower; a zero-width
+      // space keeps the final line's geometry honest.
+      mirror.appendChild(document.createTextNode('\u200B'));
+
+      const { scrollLeft, scrollTop } = ta;
+      const tokens: TokenRect[] = spans.map((span, i) => ({
+        id: ids[i],
+        left: span.offsetLeft - scrollLeft,
+        top: span.offsetTop - scrollTop,
+        width: span.offsetWidth,
+        height: span.offsetHeight,
+      }));
+
+      setLayout({
+        layer: {
+          left: ta.offsetLeft,
+          top: ta.offsetTop,
+          width: ta.clientWidth,
+          height: ta.clientHeight,
+        },
+        tokens,
+      });
+    };
+
+    measure();
+    textarea.addEventListener('scroll', measure, { passive: true });
+    const observer = new ResizeObserver(measure);
+    observer.observe(textarea);
+    window.addEventListener('resize', measure);
+
+    return () => {
+      textarea.removeEventListener('scroll', measure);
+      observer.disconnect();
+      window.removeEventListener('resize', measure);
+      mirror?.remove();
+    };
+  }, [textareaRef, value, active]);
+
+  return layout;
+}
diff --git a/services/platform/app/features/chat/hooks/use-video-url-ingest.ts b/services/platform/app/features/chat/hooks/use-video-url-ingest.ts
new file mode 100644
index 0000000000..f01eab9074
--- /dev/null
+++ b/services/platform/app/features/chat/hooks/use-video-url-ingest.ts
@@ -0,0 +1,46 @@
+import { useCallback, useState } from 'react';
+
+/** Matches the composer's `ingestVideoUrlsFromText` prop. */
+type IngestVideoUrls = (
+  text: string,
+  organizationId: string,
+  userLocale?: string,
+) => Promise<number>;
+
+/**
+ * Owns the "a pasted/dropped video URL is being ingested" pending flag that the
+ * composer's paste handler and drag-and-drop handler previously each inlined as
+ * the same set-pending → call → clear-in-`finally` block.
+ *
+ * `pending` flips to `true` synchronously BEFORE the ingest awaits so the
+ * send-gate observes it on the very next render — a paste/drop-then-Enter race
+ * would otherwise ship the message before the ingest round-trip lands and the
+ * video-link chip reflects the new row. `ingest` is a no-op when ingestion is
+ * unavailable or the text is empty.
+ */
+export function useVideoUrlIngest(
+  ingestVideoUrlsFromText: IngestVideoUrls | undefined,
+  organizationId: string,
+  userLocale: string,
+): { pending: boolean; ingest: (text: string) => void } {
+  const [pending, setPending] = useState(false);
+
+  const ingest = useCallback(
+    (text: string) => {
+      if (!ingestVideoUrlsFromText || !text) return;
+      setPending(true);
+      void ingestVideoUrlsFromText(text, organizationId, userLocale)
+        .catch((err: unknown) => {
+          // Best-effort enrichment — a failed ingest must not surface as an
+          // unhandled rejection; the message still sends without the chip.
+          console.error('[useVideoUrlIngest] video URL ingest failed:', err);
+        })
+        .finally(() => {
+          setPending(false);
+        });
+    },
+    [ingestVideoUrlsFromText, organizationId, userLocale],
+  );
+
+  return { pending, ingest };
+}
diff --git a/services/platform/app/features/chat/utils/capture-screenshot.ts b/services/platform/app/features/chat/utils/capture-screenshot.ts
deleted file mode 100644
index 17e433702d..0000000000
--- a/services/platform/app/features/chat/utils/capture-screenshot.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-/**
- * Capture a screenshot via the Screen Capture API and return it as a PNG
- * `File` ready to feed into the chat upload pipeline. The browser shows its
- * native screen/window/tab picker (and permission prompt); the stream is
- * torn down immediately after a single frame is grabbed.
- *
- * Returns `null` when the API is unavailable. Throws on permission denial /
- * user cancellation (`NotAllowedError` / `AbortError`) — callers should
- * treat those as a silent no-op.
- */
-
-// `requestVideoFrameCallback` isn't in the DOM lib types everywhere yet.
-type VideoWithFrameCallback = HTMLVideoElement & {
-  requestVideoFrameCallback?: (callback: () => void) => number;
-};
-
-/**
- * Resolve once the video element actually has a decoded frame ready to draw.
- * `play()` resolving only means playback *started* — the first frame may not
- * be painted yet, and drawing too early is what produces a black capture.
- *
- * Prefer `requestVideoFrameCallback` (fires precisely when a frame is
- * presentable). Fall back to the `loadeddata` event plus two animation frames
- * so the frame is committed before we read it. A timeout backstop keeps us
- * from hanging if neither ever fires.
- */
-function waitForVideoFrame(video: HTMLVideoElement): Promise<void> {
-  return new Promise<void>((resolve) => {
-    let settled = false;
-    const finish = () => {
-      if (settled) return;
-      settled = true;
-      resolve();
-    };
-
-    const rvfc = (video as VideoWithFrameCallback).requestVideoFrameCallback;
-    if (typeof rvfc === 'function') {
-      rvfc.call(video, finish);
-    } else {
-      const onReady = () =>
-        requestAnimationFrame(() => requestAnimationFrame(finish));
-      if (video.readyState >= 2 /* HAVE_CURRENT_DATA */) {
-        onReady();
-      } else {
-        video.addEventListener('loadeddata', onReady, { once: true });
-      }
-    }
-
-    // Backstop: never wait forever for a frame callback that doesn't arrive.
-    setTimeout(finish, 1000);
-  });
-}
-
-export async function captureScreenshot(): Promise<File | null> {
-  if (
-    typeof navigator === 'undefined' ||
-    !navigator.mediaDevices?.getDisplayMedia
-  ) {
-    return null;
-  }
-
-  const stream = await navigator.mediaDevices.getDisplayMedia({
-    video: true,
-    audio: false,
-  });
-
-  try {
-    const video = document.createElement('video');
-    video.srcObject = stream;
-    video.muted = true;
-    video.playsInline = true;
-    await video.play();
-    // Wait for a real decoded frame — drawing before one exists yields a
-    // black rectangle.
-    await waitForVideoFrame(video);
-
-    const width = video.videoWidth;
-    const height = video.videoHeight;
-    if (!width || !height) return null;
-
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    const ctx = canvas.getContext('2d');
-    if (!ctx) return null;
-    ctx.drawImage(video, 0, 0, width, height);
-    video.pause();
-    video.srcObject = null;
-
-    const blob = await new Promise<Blob | null>((resolve) =>
-      canvas.toBlob(resolve, 'image/png'),
-    );
-    if (!blob) return null;
-
-    return new File([blob], `screenshot-${Date.now()}.png`, {
-      type: 'image/png',
-    });
-  } finally {
-    // Always release the capture so the browser's "sharing your screen"
-    // indicator clears immediately.
-    for (const track of stream.getTracks()) track.stop();
-  }
-}
diff --git a/services/platform/app/features/chat/utils/sanitize-chat-error.test.ts b/services/platform/app/features/chat/utils/sanitize-chat-error.test.ts
index e087f90d9a..fcc1128d4f 100644
--- a/services/platform/app/features/chat/utils/sanitize-chat-error.test.ts
+++ b/services/platform/app/features/chat/utils/sanitize-chat-error.test.ts
@@ -1,461 +1,98 @@
-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
+
+import { encodeChatError } from '@/lib/shared/chat-errors';
 
 import { sanitizeChatError } from './sanitize-chat-error';
 
-describe('sanitizeChatError', () => {
-  it('returns generic when rawError is undefined', () => {
-    expect(sanitizeChatError(undefined)).toEqual({
-      category: 'generic',
-      i18nKey: 'errorGeneratingDescription',
-    });
-  });
+// Exhaustive classification coverage lives in lib/shared/chat-errors.test.ts.
+// These tests cover the client adapter: envelope-authoritative decoding, named
+// variant selection, and raw-detail sanitization.
 
-  it('returns generic when rawError is empty string', () => {
-    expect(sanitizeChatError('')).toEqual({
-      category: 'generic',
-      i18nKey: 'errorGeneratingDescription',
-    });
+describe('sanitizeChatError — legacy raw strings', () => {
+  it('falls back to classifying an un-enveloped error', () => {
+    const result = sanitizeChatError('Error 402: payment required');
+    expect(result.code).toBe('credit_exhausted');
+    expect(result.i18nKey).toBe('errorHintCreditExhausted');
+    expect(result.params).toBeUndefined();
   });
 
-  it('returns generic with rawMessage for unknown error messages', () => {
-    expect(sanitizeChatError('Something unexpected happened')).toEqual({
-      category: 'generic',
-      i18nKey: 'errorGeneratingDescription',
-      rawMessage: 'Something unexpected happened',
-    });
+  it('defaults to generic for unrecognized errors', () => {
+    const result = sanitizeChatError('Something unexpected happened');
+    expect(result.code).toBe('generic');
+    expect(result.i18nKey).toBe('errorGeneratingDescription');
+    expect(result.rawMessage).toBe('Something unexpected happened');
   });
 
-  it('strips the stack trace from an uncategorized error (no file path leaks)', () => {
-    const raw = `Uncaught Error: Failed after 3 attempts
-    at <anonymous> (../../node_modules/ai/src/ui/process-ui-message-stream.ts:776:14)`;
+  it('strips stack frames / paths from the raw detail', () => {
+    const raw =
+      'Failed after 3 attempts\n    at process (/app/node_modules/ai/x.ts:7:1)';
     const result = sanitizeChatError(raw);
-    expect(result.category).toBe('generic');
-    expect(result.i18nKey).toBe('errorGeneratingDescription');
     expect(result.rawMessage).toBe('Failed after 3 attempts');
     expect(result.rawMessage).not.toContain('node_modules');
   });
 
-  it('suppresses rawMessage when a single-line error carries a path/frame', () => {
+  it('drops the raw detail entirely when only a stack frame is present', () => {
     const result = sanitizeChatError(
-      'boom at /node_modules/ai/dist/index.mjs:5758:14',
+      'at Object.<anonymous> (/app/node_modules/ai/index.js:1:1)',
     );
-    expect(result.category).toBe('generic');
     expect(result.rawMessage).toBeUndefined();
   });
+});
 
-  describe('credit exhausted errors', () => {
-    it('matches OpenRouter credit error', () => {
-      const raw =
-        'Uncaught Error: This request requires more credits. You requested up to 65536 tokens, but can only afford 23255.';
-      expect(sanitizeChatError(raw)).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('matches "can only afford" phrasing', () => {
-      expect(sanitizeChatError('can only afford 500 tokens')).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('matches credit insufficient error', () => {
-      expect(sanitizeChatError('Credit insufficient for request')).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('matches "Insufficient credits" phrasing', () => {
-      expect(
-        sanitizeChatError(
-          'Insufficient credits. This account never purchased credits. Make sure your key is on the correct account or org.',
-        ),
-      ).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('matches "never purchased credits" phrasing', () => {
-      expect(sanitizeChatError('This account never purchased credits')).toEqual(
-        {
-          category: 'creditExhausted',
-          i18nKey: 'errorHintCreditExhausted',
-        },
-      );
-    });
-
-    it('matches HTTP 402 error', () => {
-      expect(sanitizeChatError('Error 402: payment required')).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('matches backend "Provider credit limit reached" message', () => {
-      expect(sanitizeChatError('Provider credit limit reached')).toEqual({
-        category: 'creditExhausted',
-        i18nKey: 'errorHintCreditExhausted',
-      });
-    });
-
-    it('does not false-positive on numbers containing 402', () => {
-      expect(sanitizeChatError('Error code 14025 encountered')).toEqual({
-        category: 'generic',
-        i18nKey: 'errorGeneratingDescription',
-        rawMessage: 'Error code 14025 encountered',
-      });
-    });
-  });
-
-  describe('auth errors', () => {
-    it('matches HTTP 401 error', () => {
-      expect(sanitizeChatError('Error 401: unauthorized')).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches HTTP 403 error', () => {
-      expect(sanitizeChatError('Error 403: forbidden')).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches invalid key error', () => {
-      expect(sanitizeChatError('Invalid key provided for this model')).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches expired key error', () => {
-      expect(sanitizeChatError('Your expired key cannot be used')).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches authentication failed error', () => {
-      expect(
-        sanitizeChatError('Authentication failed for this request'),
-      ).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches "Missing Authentication header" error', () => {
-      const raw = `Uncaught Error: Missing Authentication header
-    at <anonymous> (../../../../node_modules/ai/src/ui/process-ui-message-stream.ts:776:14)`;
-      expect(sanitizeChatError(raw)).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('matches "User not found" error from invalid API key', () => {
-      const raw = `Uncaught Error: User not found.
-    at <anonymous> (../../../../node_modules/ai/src/ui/process-ui-message-stream.ts:776:14)`;
-      expect(sanitizeChatError(raw)).toEqual({
-        category: 'authError',
-        i18nKey: 'errorHintAuthError',
-      });
-    });
-
-    it('does not false-positive on numbers containing 401', () => {
-      expect(sanitizeChatError('Error code 14013 encountered')).toEqual({
-        category: 'generic',
-        i18nKey: 'errorGeneratingDescription',
-        rawMessage: 'Error code 14013 encountered',
-      });
-    });
-  });
-
-  describe('model not found errors', () => {
-    it('matches model not found error', () => {
-      expect(
-        sanitizeChatError('The model was not found on this provider'),
-      ).toEqual({
-        category: 'modelNotFound',
-        i18nKey: 'errorHintModelNotFound',
-      });
-    });
-
-    it('matches model not available error', () => {
-      expect(sanitizeChatError('Model gpt-5 is not available')).toEqual({
-        category: 'modelNotFound',
-        i18nKey: 'errorHintModelNotFound',
-      });
-    });
-
-    it('matches invalid model error', () => {
-      expect(sanitizeChatError('Invalid model specified')).toEqual({
-        category: 'modelNotFound',
-        i18nKey: 'errorHintModelNotFound',
-      });
-    });
-
-    it('matches HTTP 404 error', () => {
-      expect(sanitizeChatError('Error 404: not found')).toEqual({
-        category: 'modelNotFound',
-        i18nKey: 'errorHintModelNotFound',
-      });
-    });
-
-    it('does not false-positive on numbers containing 404', () => {
-      expect(sanitizeChatError('Error code 14043 encountered')).toEqual({
-        category: 'generic',
-        i18nKey: 'errorGeneratingDescription',
-        rawMessage: 'Error code 14043 encountered',
-      });
-    });
-  });
-
-  describe('token limit errors', () => {
-    it('matches fewer max_tokens error', () => {
-      const raw =
-        'This request requires fewer max_tokens. You requested up to 65536 tokens.';
-      expect(sanitizeChatError(raw)).toEqual({
-        category: 'tokenLimit',
-        i18nKey: 'errorHintTokenLimit',
-      });
-    });
-
-    it('matches token limit error', () => {
-      expect(sanitizeChatError('Exceeded token limit for this model')).toEqual({
-        category: 'tokenLimit',
-        i18nKey: 'errorHintTokenLimit',
-      });
-    });
-
-    it('matches max_tokens reference', () => {
-      expect(sanitizeChatError('max_tokens exceeded')).toEqual({
-        category: 'tokenLimit',
-        i18nKey: 'errorHintTokenLimit',
-      });
-    });
-  });
-
-  describe('output cap too high errors', () => {
-    it('classifies "max_tokens is too large ... supports at most N completion tokens" as outputCapTooHigh', () => {
-      // The CONFIGURED cap exceeds the model's real ceiling — the operator
-      // should lower maxOutputTokens, not the end-user shorten their request.
-      // Must NOT be mislabeled tokenLimit ("output token limit exceeded").
-      expect(
-        sanitizeChatError(
-          'max_tokens is too large: 200000. This model supports at most 128000 completion tokens.',
-        ),
-      ).toEqual({
-        category: 'outputCapTooHigh',
-        i18nKey: 'errorHintOutputCapTooHigh',
-      });
-    });
-
-    it('does not shadow the unsupported-parameter classifier', () => {
-      expect(
-        sanitizeChatError(
-          "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
-        ).category,
-      ).toBe('unsupportedParameter');
-    });
-  });
-
-  describe('unsupported parameter errors', () => {
-    it('classifies an Azure reasoning-model max_tokens rejection as unsupportedParameter, not tokenLimit', () => {
-      // GPT-5 / o-series reasoning deployments reject `max_tokens` and require
-      // `max_completion_tokens`. The verbatim 400 body contains "max_tokens",
-      // which must NOT be mislabeled as an output-token-limit problem.
-      const raw =
-        "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.";
-      expect(sanitizeChatError(raw)).toEqual({
-        category: 'unsupportedParameter',
-        i18nKey: 'errorHintUnsupportedParameter',
-      });
-    });
-
-    it('matches "is not supported with this model" phrasing', () => {
-      expect(
-        sanitizeChatError(
-          "Unsupported value: 'temperature' is not supported with this model.",
-        ),
-      ).toEqual({
-        category: 'unsupportedParameter',
-        i18nKey: 'errorHintUnsupportedParameter',
-      });
-    });
-
-    it('matches an unrecognized request argument error', () => {
-      expect(
-        sanitizeChatError('Unrecognized request argument supplied: foo'),
-      ).toEqual({
-        category: 'unsupportedParameter',
-        i18nKey: 'errorHintUnsupportedParameter',
-      });
-    });
-  });
-
-  describe('context length errors', () => {
-    it('matches context length exceeded', () => {
-      expect(sanitizeChatError('context_length exceeded')).toEqual({
-        category: 'contextLength',
-        i18nKey: 'errorHintContextLength',
-      });
-    });
-
-    it('matches context window error', () => {
-      expect(sanitizeChatError('Exceeded context window limit')).toEqual({
-        category: 'contextLength',
-        i18nKey: 'errorHintContextLength',
-      });
-    });
-
-    it('matches maximum context length', () => {
-      expect(
-        sanitizeChatError('maximum context length is 128000 tokens'),
-      ).toEqual({
-        category: 'contextLength',
-        i18nKey: 'errorHintContextLength',
-      });
-    });
-  });
-
-  describe('rate limit errors', () => {
-    it('matches rate limit error', () => {
-      expect(sanitizeChatError('Rate limit exceeded')).toEqual({
-        category: 'rateLimited',
-        i18nKey: 'errorHintRateLimited',
-      });
-    });
-
-    it('matches "too many requests"', () => {
-      expect(sanitizeChatError('Too many requests, please slow down')).toEqual({
-        category: 'rateLimited',
-        i18nKey: 'errorHintRateLimited',
-      });
-    });
-
-    it('matches HTTP 429 reference', () => {
-      expect(sanitizeChatError('Error 429: rate limited')).toEqual({
-        category: 'rateLimited',
-        i18nKey: 'errorHintRateLimited',
-      });
+describe('sanitizeChatError — structured envelope (authoritative)', () => {
+  it('trusts the backend code over what the raw text would classify as', () => {
+    // Raw text looks like a 500, but the backend stamped credit_exhausted.
+    const encoded = encodeChatError({
+      code: 'credit_exhausted',
+      provider: 'OpenRouter',
+      raw: 'HTTP 500 from upstream',
     });
+    const result = sanitizeChatError(encoded);
+    expect(result.code).toBe('credit_exhausted');
+    expect(result.rawMessage).toBe('HTTP 500 from upstream');
   });
 
-  describe('content filter errors', () => {
-    it('matches content filter error', () => {
-      expect(sanitizeChatError('Content filter triggered')).toEqual({
-        category: 'contentFilter',
-        i18nKey: 'errorHintContentFilter',
-      });
-    });
-
-    it('matches content policy error', () => {
-      expect(sanitizeChatError('Violated content policy')).toEqual({
-        category: 'contentFilter',
-        i18nKey: 'errorHintContentFilter',
-      });
-    });
-
-    it('matches moderation error', () => {
-      expect(sanitizeChatError('Request flagged by moderation system')).toEqual(
-        {
-          category: 'contentFilter',
-          i18nKey: 'errorHintContentFilter',
-        },
-      );
+  it('selects the named variant and passes params when a provider is known', () => {
+    const encoded = encodeChatError({
+      code: 'credit_exhausted',
+      provider: 'OpenRouter',
+      raw: 'requires more credits',
     });
+    const result = sanitizeChatError(encoded);
+    expect(result.i18nKey).toBe('errorHintCreditExhaustedNamed');
+    expect(result.params).toEqual({ provider: 'OpenRouter', model: undefined });
   });
 
-  describe('tool failure errors', () => {
-    it('matches tool error', () => {
-      expect(sanitizeChatError('Tool error: customer_read failed')).toEqual({
-        category: 'toolFailure',
-        i18nKey: 'errorHintToolFailure',
-      });
-    });
-
-    it('matches tool failure', () => {
-      expect(sanitizeChatError('Tool execution failed')).toEqual({
-        category: 'toolFailure',
-        i18nKey: 'errorHintToolFailure',
-      });
-    });
-
-    it('matches unable to complete', () => {
-      expect(
-        sanitizeChatError('Unable to complete the requested operation'),
-      ).toEqual({
-        category: 'toolFailure',
-        i18nKey: 'errorHintToolFailure',
-      });
+  it('uses the base variant when no provider/model is available', () => {
+    const encoded = encodeChatError({
+      code: 'credit_exhausted',
+      raw: 'requires more credits',
     });
+    const result = sanitizeChatError(encoded);
+    expect(result.i18nKey).toBe('errorHintCreditExhausted');
+    expect(result.params).toBeUndefined();
   });
 
-  describe('provider errors', () => {
-    it('matches 500 server error', () => {
-      expect(sanitizeChatError('Error 500: internal server error')).toEqual({
-        category: 'providerError',
-        i18nKey: 'errorHintProviderError',
-      });
-    });
-
-    it('matches 502 bad gateway', () => {
-      expect(sanitizeChatError('Error 502: bad gateway')).toEqual({
-        category: 'providerError',
-        i18nKey: 'errorHintProviderError',
-      });
-    });
-
-    it('matches 503 service unavailable', () => {
-      expect(sanitizeChatError('Error 503: service unavailable')).toEqual({
-        category: 'providerError',
-        i18nKey: 'errorHintProviderError',
-      });
+  it('passes the model name for model_not_found', () => {
+    const encoded = encodeChatError({
+      code: 'model_not_found',
+      provider: 'OpenRouter',
+      model: 'anthropic/claude-opus-4.8',
+      raw: 'model not found',
     });
-
-    it('matches overloaded error', () => {
-      expect(sanitizeChatError('The model is currently overloaded')).toEqual({
-        category: 'providerError',
-        i18nKey: 'errorHintProviderError',
-      });
-    });
-
-    it('matches capacity error', () => {
-      expect(sanitizeChatError('No capacity available for this model')).toEqual(
-        {
-          category: 'providerError',
-          i18nKey: 'errorHintProviderError',
-        },
-      );
-    });
-
-    it('does not false-positive on numbers containing 500', () => {
-      expect(sanitizeChatError('Processed 15003 items')).toEqual({
-        category: 'generic',
-        i18nKey: 'errorGeneratingDescription',
-        rawMessage: 'Processed 15003 items',
-      });
-    });
-  });
-
-  it('does not include rawMessage for categorized errors', () => {
-    const rawWithStack = `Uncaught Error: This request requires more credits.
-    at <anonymous> (../../node_modules/ai/dist/index.mjs:5758:14)
-    at runUpdateMessageJob (../../node_modules/ai/dist/index.mjs:8306:10)`;
-    const result = sanitizeChatError(rawWithStack);
-    expect(result.i18nKey).toBe('errorHintCreditExhausted');
-    expect(result.rawMessage).toBeUndefined();
+    const result = sanitizeChatError(encoded);
+    expect(result.i18nKey).toBe('errorHintModelNotFoundNamed');
+    expect(result.params?.model).toBe('anthropic/claude-opus-4.8');
   });
 
-  it('prioritizes credit exhausted over token limit for combined errors', () => {
-    const raw =
-      'This request requires more credits, or fewer max_tokens. You requested up to 65536 tokens, but can only afford 23255.';
-    const result = sanitizeChatError(raw);
-    expect(result.category).toBe('creditExhausted');
+  it('surfaces triedCount only when more than one model was attempted', () => {
+    const many = sanitizeChatError(
+      encodeChatError({ code: 'provider_error', triedCount: 3, raw: 'x' }),
+    );
+    expect(many.triedCount).toBe(3);
+    const one = sanitizeChatError(
+      encodeChatError({ code: 'provider_error', triedCount: 1, raw: 'x' }),
+    );
+    expect(one.triedCount).toBeUndefined();
   });
 });
diff --git a/services/platform/app/features/chat/utils/sanitize-chat-error.ts b/services/platform/app/features/chat/utils/sanitize-chat-error.ts
index 267677aced..be9249020c 100644
--- a/services/platform/app/features/chat/utils/sanitize-chat-error.ts
+++ b/services/platform/app/features/chat/utils/sanitize-chat-error.ts
@@ -1,120 +1,36 @@
-type ErrorCategory =
-  | 'missingApiKey'
-  | 'creditExhausted'
-  | 'authError'
-  | 'modelNotFound'
-  | 'unsupportedParameter'
-  | 'outputCapTooHigh'
-  | 'tokenLimit'
-  | 'rateLimited'
-  | 'contentFilter'
-  | 'contextLength'
-  | 'toolFailure'
-  | 'providerError'
-  | 'generic';
+import {
+  CHAT_ERROR_I18N_KEY,
+  CHAT_ERROR_I18N_KEY_NAMED,
+  type ChatErrorCode,
+  classifyChatErrorCode,
+  decodeChatError,
+} from '@/lib/shared/chat-errors';
 
-interface SanitizedError {
-  category: ErrorCategory;
+export interface SanitizedChatError {
+  /** Canonical error code (authoritative when the backend stamped it). */
+  code: ChatErrorCode;
+  /** Resolved chat i18n key — the named variant when a provider/model is known. */
   i18nKey: string;
+  /** Interpolation params for {@link i18nKey} (only the named variants use them). */
+  params?: { provider?: string; model?: string };
+  /** How many models were attempted before giving up (when known, > 1). */
+  triedCount?: number;
+  /**
+   * The verbatim provider/SDK error for the "Technical details" disclosure.
+   * Stack frames and file paths are stripped so they never reach the UI.
+   */
   rawMessage?: string;
 }
 
-const ERROR_PATTERNS: { pattern: RegExp; category: ErrorCategory }[] = [
-  // Match our typed error first — it's user-actionable and should override
-  // the generic auth/providerError matchers below (which the raw ENOENT
-  // stack trace would otherwise trip).
-  {
-    pattern:
-      /NoProviderAvailableError|No API key is configured for this organization/i,
-    category: 'missingApiKey',
-  },
-  {
-    pattern:
-      /more credits|can only afford|credit.*insufficient|insufficient.*credit|never purchased credits|credit.*limit|credit.*reached|\b402\b/i,
-    category: 'creditExhausted',
-  },
-  {
-    pattern:
-      /\b401\b|\b403\b|invalid.*key|expired.*key|api.?key.*invalid|unauthorized|forbidden|authentication.*fail|user not found|missing.*authentication/i,
-    category: 'authError',
-  },
-  {
-    pattern: /model.*not found|model.*not available|invalid model|\b404\b/i,
-    category: 'modelNotFound',
-  },
-  // A provider/model rejecting a request PARAMETER (e.g. Azure reasoning
-  // deployments returning "Unsupported parameter: 'max_tokens' ... Use
-  // 'max_completion_tokens' instead") is an operator-config mismatch, not an
-  // end-user token-limit problem. This must precede `tokenLimit` below, whose
-  // broad `max_tokens` match would otherwise mislabel it as "output token
-  // limit exceeded".
-  {
-    pattern:
-      /unsupported parameter|is not supported with this model|unsupported_parameter|unknown parameter|unrecognized request argument/i,
-    category: 'unsupportedParameter',
-  },
-  // The CONFIGURED output cap exceeds the model's real ceiling, e.g. Azure/
-  // OpenAI "max_tokens is too large: 32768 ... supports at most 16384 completion
-  // tokens". This is an operator-config problem (lower the model's
-  // `maxOutputTokens`), NOT an end-user "shorten your request" token-limit. Must
-  // precede `tokenLimit`, whose bare `max_tokens` alternative would otherwise
-  // mislabel it as "output token limit exceeded".
-  {
-    pattern:
-      /max_tokens.*too large|too large.*max_tokens|supports at most.*completion tokens|reduce.*max_tokens/i,
-    category: 'outputCapTooHigh',
-  },
-  {
-    pattern: /fewer max_tokens|token.*limit|max_tokens/i,
-    category: 'tokenLimit',
-  },
-  {
-    pattern: /context.?length|context.?window|maximum context/i,
-    category: 'contextLength',
-  },
-  {
-    pattern: /rate.?limit|too many requests|429/i,
-    category: 'rateLimited',
-  },
-  {
-    pattern: /content.?filter|content.?policy|moderation/i,
-    category: 'contentFilter',
-  },
-  {
-    pattern: /tool.*error|tool.*fail|unable to complete/i,
-    category: 'toolFailure',
-  },
-  {
-    pattern:
-      /\b5\d{2}\b|server error|overloaded|capacity|service.*unavailable|internal.*error/i,
-    category: 'providerError',
-  },
-];
-
-const CATEGORY_I18N_KEY: Record<ErrorCategory, string> = {
-  missingApiKey: 'errorHintMissingApiKey',
-  creditExhausted: 'errorHintCreditExhausted',
-  authError: 'errorHintAuthError',
-  modelNotFound: 'errorHintModelNotFound',
-  unsupportedParameter: 'errorHintUnsupportedParameter',
-  outputCapTooHigh: 'errorHintOutputCapTooHigh',
-  tokenLimit: 'errorHintTokenLimit',
-  rateLimited: 'errorHintRateLimited',
-  contentFilter: 'errorHintContentFilter',
-  contextLength: 'errorHintContextLength',
-  toolFailure: 'errorHintToolFailure',
-  providerError: 'errorHintProviderError',
-  generic: 'errorGeneratingDescription',
-};
-
 /**
- * Reduce a raw provider/SDK error to a single, path-free line safe to show the
- * user. Stack frames and file paths (e.g.
+ * Reduce a raw provider/SDK error to a single path-free line safe to show in
+ * the "Technical details" disclosure. Stack frames and file paths (e.g.
  * `node_modules/ai/src/ui/process-ui-message-stream.ts:776:14`) must NEVER reach
  * the UI — take only the first line, strip the `Uncaught`/`Error:` noise, and
  * drop the message entirely if a stack-frame or path token survives.
  */
-function cleanRawMessage(raw: string): string | undefined {
+function cleanRawMessage(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
   const firstLine = raw
     .split('\n')[0]
     .replace(/^\s*uncaught\s+/i, '')
@@ -122,7 +38,7 @@ function cleanRawMessage(raw: string): string | undefined {
     .trim();
   if (
     firstLine.length === 0 ||
-    firstLine.length > 200 ||
+    firstLine.length > 300 ||
     /\bat\s|node_modules|\.[cm]?[jt]sx?:\d+|https?:\/\/|(^|\s)\/\S/.test(
       firstLine,
     )
@@ -133,30 +49,30 @@ function cleanRawMessage(raw: string): string | undefined {
 }
 
 /**
- * Classify a raw error string from the AI provider into a user-friendly
- * i18n key. For known error types, only the i18n message is shown. For unknown
- * errors a short, sanitized first line is preserved for context — but never a
- * stack trace or file path (see `cleanRawMessage`).
+ * Resolve a failed chat turn's stored error into the localized, provider-aware
+ * pieces the UI renders.
+ *
+ * Prefers the structured code the backend stamped onto the error
+ * ({@link decodeChatError}); falls back to classifying the raw string when the
+ * error predates the envelope or came from a non-chat path. The classification
+ * logic itself is shared with the backend (see `lib/shared/chat-errors`).
  */
 export function sanitizeChatError(
   rawError: string | undefined,
-): SanitizedError {
-  if (!rawError) {
-    return { category: 'generic', i18nKey: CATEGORY_I18N_KEY.generic };
-  }
+): SanitizedChatError {
+  const decoded = decodeChatError(rawError);
+  const code = decoded.code ?? classifyChatErrorCode(decoded.raw ?? '');
+  const { provider, model, triedCount } = decoded;
 
-  for (const { pattern, category } of ERROR_PATTERNS) {
-    if (pattern.test(rawError)) {
-      return {
-        category,
-        i18nKey: CATEGORY_I18N_KEY[category],
-      };
-    }
-  }
+  // Use the richer "named" message only when there's a name to fill in.
+  const namedKey = CHAT_ERROR_I18N_KEY_NAMED[code];
+  const useNamed = !!namedKey && (!!provider || !!model);
 
   return {
-    category: 'generic',
-    i18nKey: CATEGORY_I18N_KEY.generic,
-    rawMessage: cleanRawMessage(rawError),
+    code,
+    i18nKey: useNamed && namedKey ? namedKey : CHAT_ERROR_I18N_KEY[code],
+    params: useNamed ? { provider, model } : undefined,
+    triedCount: triedCount != null && triedCount > 1 ? triedCount : undefined,
+    rawMessage: cleanRawMessage(decoded.raw),
   };
 }
diff --git a/services/platform/app/features/conversations/components/activate-conversations-empty-state.tsx b/services/platform/app/features/conversations/components/activate-conversations-empty-state.tsx
index e1ef3ad094..caeb7266ad 100644
--- a/services/platform/app/features/conversations/components/activate-conversations-empty-state.tsx
+++ b/services/platform/app/features/conversations/components/activate-conversations-empty-state.tsx
@@ -2,6 +2,7 @@
 
 import { LinkButton } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { MessageSquare } from 'lucide-react';
 
@@ -17,8 +18,8 @@ export function ActivateConversationsEmptyState({
   const { t } = useT('conversations');
 
   return (
-    <div className="m-4 flex flex-1 items-center justify-center rounded-xl px-4 py-12">
-      <div className="flex max-w-md flex-col items-center text-center">
+    <Row gap={0} justify="center" className="m-4 flex-1 rounded-xl px-4 py-12">
+      <Stack gap={0} align="center" className="max-w-md text-center">
         <MessageSquare className="text-muted-foreground mb-4 size-6" />
         <Heading level={2} size="lg" className="mb-1">
           {t('activate.title')}
@@ -31,7 +32,7 @@ export function ActivateConversationsEmptyState({
         >
           {t('activate.connectEmail')}
         </LinkButton>
-      </div>
-    </div>
+      </Stack>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/conversations/components/bulk-send-dialog.tsx b/services/platform/app/features/conversations/components/bulk-send-dialog.tsx
index bbe9136338..f1778eddf4 100644
--- a/services/platform/app/features/conversations/components/bulk-send-dialog.tsx
+++ b/services/platform/app/features/conversations/components/bulk-send-dialog.tsx
@@ -1,5 +1,6 @@
 import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Loader2Icon } from 'lucide-react';
 
@@ -22,7 +23,11 @@ export function BulkSendDialog({
   const { t: tCommon } = useT('common');
 
   return (
-    <div className="bg-background/80 fixed inset-0 z-50 flex items-center justify-center backdrop-blur-sm">
+    <Row
+      gap={0}
+      justify="center"
+      className="bg-background/80 fixed inset-0 z-50 backdrop-blur-sm"
+    >
       <div className="bg-background mx-4 w-full max-w-md rounded-lg border p-6">
         <Heading level={3} size="lg" className="mb-4">
           {tConversations('bulkSend.title', { count: selectedCount })}
@@ -30,7 +35,7 @@ export function BulkSendDialog({
         <Text variant="muted" className="mb-6">
           {tConversations('bulkSend.description', { count: selectedCount })}
         </Text>
-        <div className="flex justify-end gap-3">
+        <Row gap={3} align="stretch" justify="end">
           <Button variant="secondary" onClick={onCancel} disabled={isSending}>
             {tCommon('actions.cancel')}
           </Button>
@@ -38,8 +43,8 @@ export function BulkSendDialog({
             {isSending && <Loader2Icon className="mr-2 size-4 animate-spin" />}
             {tConversations('bulkSend.send')}
           </Button>
-        </div>
+        </Row>
       </div>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/conversations/components/conversation-header.tsx b/services/platform/app/features/conversations/components/conversation-header.tsx
index 2b2abd61a2..74c81a2bab 100644
--- a/services/platform/app/features/conversations/components/conversation-header.tsx
+++ b/services/platform/app/features/conversations/components/conversation-header.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuItem } from '@tale/ui/dropdown-menu';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   ArrowLeft,
@@ -208,7 +209,7 @@ export function ConversationHeader({
     : null;
 
   return (
-    <div className="border-border flex flex-col gap-3 border-b p-4 sm:px-6 sm:py-4">
+    <Stack gap={3} className="border-border border-b p-4 sm:px-6 sm:py-4">
       {/* Back button - visible only on mobile */}
       {onBack && (
         <Button
@@ -216,18 +217,18 @@ export function ConversationHeader({
           size="icon"
           className="shrink-0 md:hidden"
           onClick={onBack}
-          aria-label={tCommon('actions.back')}
+          title={tCommon('actions.back')}
         >
           <ArrowLeft className="size-5" />
         </Button>
       )}
 
       {/* Subject Row */}
-      <div className="flex items-center justify-between gap-4">
+      <Row justify="between">
         <Text className="min-w-0 truncate text-base font-semibold tracking-tight">
           {conversation.subject || conversation.title}
         </Text>
-        <div className="flex shrink-0 items-center gap-1">
+        <Row gap={1} className="shrink-0">
           <DropdownMenu
             trigger={
               <Button
@@ -243,8 +244,8 @@ export function ConversationHeader({
             align="end"
             onOpenChange={handleDropdownOpenChange}
           />
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       {/* Sender Row */}
       <div className="flex items-center gap-2.5">
@@ -272,7 +273,7 @@ export function ConversationHeader({
           >
             {customer.name || customer.email}
           </button>
-          <div className="text-muted-foreground flex items-center text-xs tracking-tight">
+          <Row gap={0} className="text-muted-foreground text-xs tracking-tight">
             <button
               type="button"
               className="cursor-pointer hover:underline"
@@ -286,9 +287,9 @@ export function ConversationHeader({
                 <span>{lastMessageTime}</span>
               </>
             )}
-          </div>
+          </Row>
         </div>
       </div>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/conversations/components/conversation-list-panel.tsx b/services/platform/app/features/conversations/components/conversation-list-panel.tsx
index 9e7441dcbd..99ea19be83 100644
--- a/services/platform/app/features/conversations/components/conversation-list-panel.tsx
+++ b/services/platform/app/features/conversations/components/conversation-list-panel.tsx
@@ -1,3 +1,4 @@
+import { Stack } from '@tale/ui/layout';
 import type { ReactNode } from 'react';
 
 import { cn } from '@/lib/utils/cn';
@@ -20,9 +21,9 @@ export function ConversationListPanel({
         hidden ? 'hidden md:flex' : 'flex',
       )}
     >
-      <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">
+      <Stack gap={0} className="min-h-0 flex-1 overflow-y-auto">
         {children}
-      </div>
+      </Stack>
       {overlay}
     </div>
   );
diff --git a/services/platform/app/features/conversations/components/conversation-panel.tsx b/services/platform/app/features/conversations/components/conversation-panel.tsx
index 83e50b5cd5..7ba9611df5 100644
--- a/services/platform/app/features/conversations/components/conversation-panel.tsx
+++ b/services/platform/app/features/conversations/components/conversation-panel.tsx
@@ -2,7 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { EmptyState } from '@tale/ui/empty-state';
-import { Center, Stack, VStack } from '@tale/ui/layout';
+import { Center, Row, Stack, VStack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -302,7 +302,6 @@ export function ConversationPanel({
         </div>
         <Button
           variant="secondary"
-          size="sm"
           onClick={() => void refetch()}
           className="mt-1"
         >
@@ -360,10 +359,11 @@ export function ConversationPanel({
     <Skeletonize loading={isLoading}>
       {/* The composer/banner footer is a flex SIBLING of the scroller — never
           inside the scroll container — so it cannot move with content. */}
-      <div className="relative flex min-h-0 flex-[1_1_0] flex-col">
-        <div
+      <Stack gap={0} className="relative min-h-0 flex-[1_1_0]">
+        <Stack
           ref={containerRef}
-          className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+          gap={0}
+          className="min-h-0 flex-1 overflow-y-auto"
         >
           <div className="bg-background sticky top-0 z-20">
             {conversation ? (
@@ -381,15 +381,18 @@ export function ConversationPanel({
                 }}
               />
             ) : (
-              <div className="border-border flex flex-col gap-3 border-b p-4 sm:px-6 sm:py-4">
-                <div className="flex items-center justify-between gap-4">
+              <Stack
+                gap={3}
+                className="border-border border-b p-4 sm:px-6 sm:py-4"
+              >
+                <Row justify="between">
                   <SkeletonBox>
                     <div className="h-5 w-64 max-w-full" />
                   </SkeletonBox>
                   <SkeletonBox>
                     <div className="size-7 shrink-0 rounded-md" />
                   </SkeletonBox>
-                </div>
+                </Row>
                 <div className="flex items-center gap-2.5">
                   <SkeletonBox>
                     <div className="size-8 shrink-0 rounded-full" />
@@ -403,18 +406,18 @@ export function ConversationPanel({
                     </SkeletonBox>
                   </VStack>
                 </div>
-              </div>
+              </Stack>
             )}
           </div>
           <div className="mx-auto w-full max-w-3xl flex-1 px-4 pt-2">
             {!conversation ? (
               <>
                 <div className="mb-4 py-2">
-                  <div className="flex justify-center">
+                  <Row gap={0} align="stretch" justify="center">
                     <SkeletonBox>
                       <div className="h-5 w-24 rounded-full" />
                     </SkeletonBox>
-                  </div>
+                  </Row>
                 </div>
                 <VStack gap={4} className="mb-8">
                   {PLACEHOLDER_MESSAGE_BUBBLES.map((row, i) => (
@@ -453,7 +456,12 @@ export function ConversationPanel({
             ) : (
               <>
                 {showCollapse && (
-                  <div className="flex justify-center py-3">
+                  <Row
+                    gap={0}
+                    align="stretch"
+                    justify="center"
+                    className="py-3"
+                  >
                     <button
                       type="button"
                       className="text-muted-foreground hover:text-foreground text-sm underline-offset-2 hover:underline"
@@ -463,7 +471,7 @@ export function ConversationPanel({
                         count: collapsedHiddenCount,
                       })}
                     </button>
-                  </div>
+                  </Row>
                 )}
                 {messageGroups.map((group, groupIndex) => {
                   const isLastGroup = groupIndex === messageGroups.length - 1;
@@ -480,7 +488,7 @@ export function ConversationPanel({
                     <div key={group.date} className="relative">
                       {/* Sticky Date Header */}
                       <div className="z-10 mb-4 py-2">
-                        <div className="flex justify-center">
+                        <Row gap={0} align="stretch" justify="center">
                           <div className="bg-background border-border rounded-full border px-2 py-0.5 shadow-sm">
                             <Text
                               as="span"
@@ -490,7 +498,7 @@ export function ConversationPanel({
                               {formatDateHeader(group.date)}
                             </Text>
                           </div>
-                        </div>
+                        </Row>
                       </div>
 
                       {/* Messages for this date */}
@@ -530,18 +538,18 @@ export function ConversationPanel({
               </>
             )}
           </div>
-        </div>
+        </Stack>
         {!conversation ? (
           isInactiveTab ? (
             <PanelFooter className="px-0 pt-3 pb-0">
-              <div className="flex items-center justify-center gap-2 border-t px-3 pt-3 pb-4">
+              <Row gap={2} justify="center" className="border-t px-3 pt-3 pb-4">
                 <SkeletonBox>
                   <div className="h-4 w-48" />
                 </SkeletonBox>
                 <SkeletonBox>
                   <div className="h-7 w-32 rounded-md" />
                 </SkeletonBox>
-              </div>
+              </Row>
             </PanelFooter>
           ) : (
             <PanelFooter className="px-4 py-3">
@@ -580,8 +588,10 @@ export function ConversationPanel({
                 />
               </div>
             ) : conversation.status === 'closed' ? (
-              <div
-                className="flex items-center justify-center gap-2 border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
+              <Row
+                gap={2}
+                justify="center"
+                className="border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
                 role="status"
               >
                 <CircleCheckIcon
@@ -597,7 +607,6 @@ export function ConversationPanel({
                 </span>
                 <Button
                   variant="secondary"
-                  size="sm"
                   disabled={isReopening}
                   className="h-auto px-3 py-1 text-[13px]"
                   onClick={() => {
@@ -628,10 +637,12 @@ export function ConversationPanel({
                     ? tConversations('header.reopening')
                     : tConversations('header.reopenConversation')}
                 </Button>
-              </div>
+              </Row>
             ) : conversation.status === 'archived' ? (
-              <div
-                className="flex items-center justify-center gap-2 border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
+              <Row
+                gap={2}
+                justify="center"
+                className="border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
                 role="status"
               >
                 <ArchiveIcon
@@ -643,7 +654,6 @@ export function ConversationPanel({
                 </span>
                 <Button
                   variant="secondary"
-                  size="sm"
                   disabled={isReopening}
                   className="h-auto px-3 py-1 text-[13px]"
                   onClick={() => {
@@ -674,10 +684,12 @@ export function ConversationPanel({
                     ? tConversations('header.reopening')
                     : tConversations('panel.unarchive')}
                 </Button>
-              </div>
+              </Row>
             ) : conversation.status === 'spam' ? (
-              <div
-                className="flex items-center justify-center gap-2 border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
+              <Row
+                gap={2}
+                justify="center"
+                className="border-t border-gray-200 bg-gray-50 px-3 pt-3 pb-4 dark:border-gray-600 dark:bg-gray-900"
                 role="status"
               >
                 <ShieldAlertIcon
@@ -687,10 +699,9 @@ export function ConversationPanel({
                 <span className="text-[13px] text-gray-500 dark:text-gray-400">
                   {tConversations('panel.spamBanner')}
                 </span>
-                <div className="flex items-center gap-2">
+                <Row gap={2}>
                   <Button
                     variant="secondary"
-                    size="sm"
                     disabled={isReopening || isDeleting}
                     className="h-auto px-3 py-1 text-[13px]"
                     onClick={() => {
@@ -728,7 +739,6 @@ export function ConversationPanel({
                   </Button>
                   <Button
                     variant="destructive"
-                    size="sm"
                     disabled={isDeleting || isReopening}
                     className="h-auto px-3 py-1 text-[13px]"
                     onClick={() => {
@@ -764,12 +774,12 @@ export function ConversationPanel({
                       ? tConversations('panel.deleting')
                       : tConversations('panel.delete')}
                   </Button>
-                </div>
-              </div>
+                </Row>
+              </Row>
             ) : null}
           </PanelFooter>
         )}
-      </div>
+      </Stack>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/conversations/components/conversations-list.tsx b/services/platform/app/features/conversations/components/conversations-list.tsx
index 779f45fc2c..9a7a5e26ad 100644
--- a/services/platform/app/features/conversations/components/conversations-list.tsx
+++ b/services/platform/app/features/conversations/components/conversations-list.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Heading } from '@tale/ui/heading';
-import { Center, HStack } from '@tale/ui/layout';
+import { Center, HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -206,7 +206,7 @@ const ConversationRow = memo(function ConversationRow({
         className="absolute inset-0 z-0"
       />
       <div className="pointer-events-none relative z-10 flex items-start gap-2.5">
-        <div className="pointer-events-auto mt-0.5 flex items-center">
+        <Row gap={0} className="pointer-events-auto mt-0.5">
           <SkeletonBox>
             <Checkbox
               checked={isChecked}
@@ -214,10 +214,10 @@ const ConversationRow = memo(function ConversationRow({
               aria-label={tDialogs ? tDialogs('selectConversation') : ''}
             />
           </SkeletonBox>
-        </div>
+        </Row>
 
         <div className="min-w-0 flex-1">
-          <div className="mb-1 flex items-center justify-between gap-2">
+          <Row gap={2} justify="between" className="mb-1">
             <div className="flex min-w-0 items-center gap-1.5">
               <Heading
                 level={3}
@@ -254,7 +254,7 @@ const ConversationRow = memo(function ConversationRow({
                   : '5m ago'}
               </SkeletonBox>
             </Text>
-          </div>
+          </Row>
 
           <Text variant="muted" truncate className="mb-1.5 tracking-tight">
             {conversation ? (
@@ -406,10 +406,15 @@ export function ConversationsList({
       {isEmpty ? (
         // Centered in the available space, no row dividers/border — it's a
         // message, not a row, so it shouldn't read as a boxed-off list item.
-        <div className="flex flex-1 flex-col items-center justify-center px-4 py-16 text-center">
+        <Stack
+          gap={0}
+          align="center"
+          justify="center"
+          className="flex-1 px-4 py-16 text-center"
+        >
           <Inbox className="text-muted-foreground/60 mb-3 size-6" />
           <Text variant="muted">{t('list.empty')}</Text>
-        </div>
+        </Stack>
       ) : (
         <div className="divide-border divide-y border-b">
           <>
diff --git a/services/platform/app/features/conversations/components/conversations.tsx b/services/platform/app/features/conversations/components/conversations.tsx
index 52ee333f53..607f7ba154 100644
--- a/services/platform/app/features/conversations/components/conversations.tsx
+++ b/services/platform/app/features/conversations/components/conversations.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuItem } from '@tale/ui/dropdown-menu';
+import { Row } from '@tale/ui/layout';
 import { LoadingOverlay } from '@tale/ui/loading-overlay';
 import type { UsePaginatedQueryResult } from 'convex/react';
 import {
@@ -252,7 +253,7 @@ export function Conversations({
               <span className="shrink-0 text-sm font-semibold">
                 {tConversations('bulk.selectedCount', { count: selectedCount })}
               </span>
-              <div className="ml-auto flex items-center gap-1">
+              <Row gap={1} className="ml-auto">
                 {status === 'open' && (
                   <Tooltip content={tConversations('bulk.sendMessages')}>
                     <Button
@@ -351,7 +352,7 @@ export function Conversations({
                     </Button>
                   </Tooltip>
                 )}
-              </div>
+              </Row>
             </>
           ) : (
             <SearchInput
diff --git a/services/platform/app/features/conversations/components/message-editor.tsx b/services/platform/app/features/conversations/components/message-editor.tsx
index 7c70e7aca9..088056154b 100644
--- a/services/platform/app/features/conversations/components/message-editor.tsx
+++ b/services/platform/app/features/conversations/components/message-editor.tsx
@@ -7,6 +7,7 @@ import {
   useEditor,
   useInstance,
 } from '@milkdown/react';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import DOMPurify from 'dompurify';
 import { LoaderIcon } from 'lucide-react';
@@ -18,10 +19,11 @@ import { useAuth } from '@/app/hooks/use-convex-auth';
 import { usePersistedState } from '@/app/hooks/use-persisted-state';
 import { toast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
-import { cn } from '@/lib/utils/cn';
 
 import '@milkdown/crepe/theme/common/style.css';
 import '@milkdown/crepe/theme/frame.css';
+import { cn } from '@/lib/utils/cn';
+
 import { useImproveMessage } from '../hooks/actions';
 import { EditorActionBar } from './message-editor/editor-action-bar';
 import { FileAttachmentsList } from './message-editor/file-attachments-list';
@@ -366,12 +368,12 @@ function MilkdownEditorInner({
           </div>
 
           {isImproving && (
-            <div className="flex h-full items-center justify-center pt-12 pb-4">
+            <Row gap={0} justify="center" className="h-full pt-12 pb-4">
               <LoaderIcon className="text-muted-foreground size-6 animate-spin" />
               <Text as="span" variant="muted" className="ml-2">
                 {tConversations('editor.improving')}
               </Text>
-            </div>
+            </Row>
           )}
         </div>
 
diff --git a/services/platform/app/features/conversations/components/message-editor/editor-action-bar.tsx b/services/platform/app/features/conversations/components/message-editor/editor-action-bar.tsx
index 70446e6b58..9bbaabd6e2 100644
--- a/services/platform/app/features/conversations/components/message-editor/editor-action-bar.tsx
+++ b/services/platform/app/features/conversations/components/message-editor/editor-action-bar.tsx
@@ -78,6 +78,7 @@ export const EditorActionBar = memo(function EditorActionBar({
             disabled={disabled || isSending}
             variant="ghost"
             size="icon"
+            title={tConversations('editor.attachFile')}
           >
             <PaperclipIcon className="size-4" />
           </Button>
@@ -89,6 +90,7 @@ export const EditorActionBar = memo(function EditorActionBar({
               }
               variant="ghost"
               size="icon"
+              aria-label={tConversations('editor.improveWithAi')}
             >
               {isImproving ? (
                 <LoaderCircleIcon className="text-muted-foreground size-4 animate-spin" />
@@ -105,6 +107,7 @@ export const EditorActionBar = memo(function EditorActionBar({
         <Button
           onClick={onSend}
           size="icon"
+          title={tConversations('editor.send')}
           disabled={
             disabled ||
             isLoading ||
@@ -132,6 +135,11 @@ export const EditorActionBar = memo(function EditorActionBar({
           <Button
             onClick={onImproveSubmit}
             size="icon"
+            aria-label={
+              isImproving
+                ? tConversations('editor.improving')
+                : tConversations('editor.generateImprovement')
+            }
             disabled={isImproving}
             className="rounded-full"
           >
diff --git a/services/platform/app/features/conversations/components/message-editor/file-attachments-list.tsx b/services/platform/app/features/conversations/components/message-editor/file-attachments-list.tsx
index 3a0c3844e4..4af312bb5a 100644
--- a/services/platform/app/features/conversations/components/message-editor/file-attachments-list.tsx
+++ b/services/platform/app/features/conversations/components/message-editor/file-attachments-list.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { XIcon } from 'lucide-react';
 import { memo } from 'react';
@@ -25,11 +26,12 @@ export const FileAttachmentsList = memo(function FileAttachmentsList({
 
   return (
     <div className="border-border border-t py-2">
-      <div className="flex flex-wrap gap-2">
+      <Row gap={2} align="stretch" wrap>
         {files.map((file) => (
-          <div
+          <Row
             key={file.id}
-            className="bg-muted flex items-center gap-2 rounded-md px-3 py-2 text-sm"
+            gap={2}
+            className="bg-muted rounded-md px-3 py-2 text-sm"
           >
             {getFileIcon(file.type)}
             <Text as="span" title={file.file?.name}>
@@ -45,9 +47,9 @@ export const FileAttachmentsList = memo(function FileAttachmentsList({
             >
               <XIcon className="size-3" />
             </button>
-          </div>
+          </Row>
         ))}
-      </div>
+      </Row>
     </div>
   );
 });
diff --git a/services/platform/app/features/conversations/components/message-editor/improve-mode.tsx b/services/platform/app/features/conversations/components/message-editor/improve-mode.tsx
index fb03d9409e..2868399fd5 100644
--- a/services/platform/app/features/conversations/components/message-editor/improve-mode.tsx
+++ b/services/platform/app/features/conversations/components/message-editor/improve-mode.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { ChevronLeft } from 'lucide-react';
 import { memo, useEffect, useRef } from 'react';
 
@@ -35,9 +36,14 @@ export const ImproveMode = memo(function ImproveMode({
   }, []);
 
   return (
-    <div className="flex items-start gap-2 p-2">
+    <Row gap={2} align="start" className="p-2">
       <Tooltip content={tConversations('editor.backToEditor')}>
-        <Button onClick={onClose} variant="ghost" size="icon">
+        <Button
+          onClick={onClose}
+          variant="ghost"
+          size="icon"
+          aria-label={tConversations('editor.backToEditor')}
+        >
           <ChevronLeft className="size-4" />
         </Button>
       </Tooltip>
@@ -61,6 +67,6 @@ export const ImproveMode = memo(function ImproveMode({
           }
         }}
       />
-    </div>
+    </Row>
   );
 });
diff --git a/services/platform/app/features/conversations/components/message-improvement-dialog.tsx b/services/platform/app/features/conversations/components/message-improvement-dialog.tsx
index 7dddf83193..d8deb551c1 100644
--- a/services/platform/app/features/conversations/components/message-improvement-dialog.tsx
+++ b/services/platform/app/features/conversations/components/message-improvement-dialog.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { PageSection } from '@tale/ui/page-section';
 import ReactMarkdown from 'react-markdown';
 
@@ -34,7 +35,7 @@ export function MessageImprovementDialog({
       onConfirm={onAccept}
       className="max-h-[80vh] max-w-4xl"
     >
-      <div className="flex grow flex-col gap-4">
+      <Stack className="grow">
         <PageSection
           as="h3"
           titleSize="sm"
@@ -62,7 +63,7 @@ export function MessageImprovementDialog({
             </div>
           </div>
         </PageSection>
-      </div>
+      </Stack>
     </ConfirmDialog>
   );
 }
diff --git a/services/platform/app/features/conversations/components/message.tsx b/services/platform/app/features/conversations/components/message.tsx
index d28e327d0a..e8c0a9abac 100644
--- a/services/platform/app/features/conversations/components/message.tsx
+++ b/services/platform/app/features/conversations/components/message.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Clock, AlertCircle, Paperclip, Download, Loader2 } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -86,10 +87,14 @@ function AttachmentCard({
   const hasUrl = !!attachment.url;
 
   return (
-    <div className="bg-background flex items-center gap-2 rounded-lg border p-2">
-      <div className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-gray-100">
+    <Row gap={2} className="bg-background rounded-lg border p-2">
+      <Row
+        gap={0}
+        justify="center"
+        className="size-8 shrink-0 rounded-lg bg-gray-100"
+      >
         <span className="text-sm">{icon}</span>
-      </div>
+      </Row>
       <div className="min-w-0 flex-1">
         <Text variant="label-sm" title={attachment.filename}>
           {middleEllipsis(attachment.filename, 28)}
@@ -101,9 +106,13 @@ function AttachmentCard({
         </Text>
       </div>
       {isDownloading ? (
-        <div className="text-muted-foreground flex size-6 shrink-0 items-center justify-center">
+        <Row
+          gap={0}
+          justify="center"
+          className="text-muted-foreground size-6 shrink-0"
+        >
           <Loader2 className="size-3.5 animate-spin" />
-        </div>
+        </Row>
       ) : hasUrl || onDownload ? (
         <button
           type="button"
@@ -123,7 +132,7 @@ function AttachmentCard({
           <Download className="size-3.5" />
         </button>
       ) : null}
-    </div>
+    </Row>
   );
 }
 
@@ -229,7 +238,7 @@ export function Message({ message, onDownloadAttachments }: MessageProps) {
   }, [message.attachments, message.content, message.id, onDownloadAttachments]);
 
   return (
-    <div className="flex flex-col">
+    <Stack gap={0}>
       <div
         className={cn(
           'flex',
@@ -280,15 +289,15 @@ export function Message({ message, onDownloadAttachments }: MessageProps) {
             </Text>
             {displayAttachments.length > 0 && (
               <div className="flex flex-col gap-1.5 px-3 pb-3">
-                <div className="flex items-center gap-1">
+                <Row gap={1}>
                   <Paperclip className="text-muted-foreground size-3" />
                   <Text as="span" variant="caption" className="text-[10px]">
                     {t('attachment.attachments', {
                       count: displayAttachments.length,
                     })}
                   </Text>
-                </div>
-                <div className="flex flex-col gap-1">
+                </Row>
+                <Stack gap={1}>
                   {displayAttachments.map((att: Attachment) => (
                     <AttachmentCard
                       key={att.id}
@@ -301,7 +310,7 @@ export function Message({ message, onDownloadAttachments }: MessageProps) {
                       }
                     />
                   ))}
-                </div>
+                </Stack>
               </div>
             )}
           </div>
@@ -324,6 +333,6 @@ export function Message({ message, onDownloadAttachments }: MessageProps) {
           </Text>
         </div>
       </div>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/customers/components/customer-delete-dialog.tsx b/services/platform/app/features/customers/components/customer-delete-dialog.tsx
index 8d87dd523a..6712fd98f0 100644
--- a/services/platform/app/features/customers/components/customer-delete-dialog.tsx
+++ b/services/platform/app/features/customers/components/customer-delete-dialog.tsx
@@ -66,7 +66,7 @@ export function CustomerDeleteDialog({
           variant="ghost"
           size="icon"
           onClick={dialog.open}
-          aria-label={tCustomers('deleteCustomer')}
+          title={tCustomers('deleteCustomer')}
         >
           <Trash2 className="text-muted-foreground size-4" />
         </Button>
diff --git a/services/platform/app/features/customers/components/customer-info-popover.tsx b/services/platform/app/features/customers/components/customer-info-popover.tsx
index bf03ee26de..e456f837ea 100644
--- a/services/platform/app/features/customers/components/customer-info-popover.tsx
+++ b/services/platform/app/features/customers/components/customer-info-popover.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { Text } from '@tale/ui/text';
 import { useMemo } from 'react';
@@ -22,12 +23,12 @@ interface InfoRowProps {
 
 function InfoRow({ label, children }: InfoRowProps) {
   return (
-    <div className="flex items-center justify-between">
+    <Row gap={0} justify="between">
       <Text variant="muted" className="text-[13px]">
         {label}
       </Text>
       <div className="text-[13px]">{children}</div>
-    </div>
+    </Row>
   );
 }
 
@@ -49,14 +50,14 @@ export function CustomerInfoCard({ customer }: { customer: CustomerData }) {
   return (
     <>
       <div className="border-border space-y-0.5 border-b px-5 py-4">
-        <div className="flex items-center gap-2">
+        <Row gap={2}>
           <Text className="text-sm font-semibold tracking-tight">
             {customer.name || t('labels.notAvailable')}
           </Text>
           {isValidStatus(customer.status) && (
             <CustomerStatusBadge status={customer.status} />
           )}
-        </div>
+        </Row>
         <Text variant="muted" className="text-xs tracking-tight break-all">
           {customer.email || t('labels.notAvailable')}
         </Text>
diff --git a/services/platform/app/features/customers/components/customers-table.tsx b/services/platform/app/features/customers/components/customers-table.tsx
index 81f3fb1fd4..ea4b44fc9d 100644
--- a/services/platform/app/features/customers/components/customers-table.tsx
+++ b/services/platform/app/features/customers/components/customers-table.tsx
@@ -2,12 +2,11 @@
 
 import { useNavigate } from '@tanstack/react-router';
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { Plus, Users } from 'lucide-react';
+import { Users } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { BulkDeleteBar } from '@/app/components/ui/data-table/data-table-bulk-actions';
-import { useAbility } from '@/app/hooks/use-ability';
 import { useListPage } from '@/app/hooks/use-list-page';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
@@ -159,9 +158,6 @@ export function CustomersTable({
 
   const [viewingCustomer, setViewingCustomer] = useState<Customer | null>(null);
   const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
-  const ability = useAbility();
-  const canWrite = ability.can('write', 'knowledgeWrite');
-  // Lifted so the action menu and the empty-state CTA share one dialog.
   const [createOpen, setCreateOpen] = useState(false);
   const deleteCustomer = useDeleteCustomer();
 
@@ -224,13 +220,6 @@ export function CustomersTable({
           icon: Users,
           title: tEmpty('customers.title'),
           description: tEmpty('customers.description'),
-          action: canWrite
-            ? {
-                label: tCustomers('addButton'),
-                icon: Plus,
-                onClick: () => setCreateOpen(true),
-              }
-            : undefined,
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/discussions/components/discussion-create-dialog.tsx b/services/platform/app/features/discussions/components/discussion-create-dialog.tsx
index ebbe25a02d..93550627ec 100644
--- a/services/platform/app/features/discussions/components/discussion-create-dialog.tsx
+++ b/services/platform/app/features/discussions/components/discussion-create-dialog.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { Dialog } from '@/app/components/ui/dialog/dialog';
@@ -103,7 +103,7 @@ export function DiscussionCreateDialog({
         />
         <div className="flex flex-col gap-1.5">
           <span className="text-sm font-medium">{t('create.category')}</span>
-          <div className="flex flex-wrap gap-2">
+          <Row gap={2} align="stretch" wrap>
             {DEFAULT_DISCUSSION_CATEGORIES.map((c) => (
               <button
                 key={c}
@@ -119,7 +119,7 @@ export function DiscussionCreateDialog({
                 {t(`categories.${c}`)}
               </button>
             ))}
-          </div>
+          </Row>
         </div>
         <FileUpload.Root>
           <ChatInput
@@ -141,11 +141,11 @@ export function DiscussionCreateDialog({
           />
         </FileUpload.Root>
         <p className="text-muted-foreground text-xs">{t('create.hint')}</p>
-        <div className="flex justify-end">
+        <Row gap={0} align="stretch" justify="end">
           <Button variant="ghost" onClick={() => onOpenChange(false)}>
             {t('create.cancel')}
           </Button>
-        </div>
+        </Row>
       </Stack>
     </Dialog>
   );
diff --git a/services/platform/app/features/discussions/components/discussion-thread-view.tsx b/services/platform/app/features/discussions/components/discussion-thread-view.tsx
index a887be01d5..e6b0cc9218 100644
--- a/services/platform/app/features/discussions/components/discussion-thread-view.tsx
+++ b/services/platform/app/features/discussions/components/discussion-thread-view.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Link, useNavigate } from '@tanstack/react-router';
 import {
@@ -169,14 +169,18 @@ export function DiscussionThreadView({
   }, [navigate, linkedTaskId, organizationId, projectId]);
 
   return (
-    <div className="flex h-full flex-col">
-      <div className="border-border flex min-h-13 items-center justify-between gap-3 border-b px-5 py-2">
+    <Stack gap={0} className="h-full">
+      <Row
+        gap={3}
+        justify="between"
+        className="border-border min-h-13 border-b px-5 py-2"
+      >
         <HStack gap={3} align="center" className="min-w-0">
           <Button
             variant="ghost"
             size="icon"
             onClick={onBack}
-            aria-label={t('backToList')}
+            title={t('backToList')}
           >
             <ArrowLeft className="text-muted-foreground size-5" />
           </Button>
@@ -198,12 +202,12 @@ export function DiscussionThreadView({
         </HStack>
         <HStack gap={2}>
           {linkedTaskId ? (
-            <Button variant="secondary" size="sm" onClick={goToTask}>
+            <Button variant="secondary" onClick={goToTask}>
               <ListChecks className="mr-1 size-4" />
               {t('spawnTask.viewTask')}
             </Button>
           ) : (
-            <Button variant="secondary" size="sm" onClick={handleSpawnTask}>
+            <Button variant="secondary" onClick={handleSpawnTask}>
               <ListPlus className="mr-1 size-4" />
               {t('spawnTask.cta')}
             </Button>
@@ -211,7 +215,6 @@ export function DiscussionThreadView({
           {status !== 'resolved' ? (
             <Button
               variant="secondary"
-              size="sm"
               onClick={() => void handleSetStatus('resolved')}
             >
               <CheckCircle2 className="mr-1 size-4" />
@@ -220,7 +223,6 @@ export function DiscussionThreadView({
           ) : (
             <Button
               variant="secondary"
-              size="sm"
               onClick={() => void handleSetStatus('open')}
             >
               <RotateCcw className="mr-1 size-4" />
@@ -229,20 +231,20 @@ export function DiscussionThreadView({
           )}
           <Button
             variant="secondary"
-            size="sm"
             onClick={() => void handleSetStatus(isLocked ? 'open' : 'locked')}
           >
             <Lock className="mr-1 size-4" />
             {isLocked ? t('unlock') : t('lock')}
           </Button>
         </HStack>
-      </div>
+      </Row>
 
-      <div className="flex h-full min-h-0 flex-1 flex-col">
-        <div className="flex min-h-0 flex-1 flex-col overflow-y-auto scroll-smooth">
-          <div className="flex flex-col overflow-y-visible p-4 sm:p-6">
-            <div
-              className="mx-auto flex w-full max-w-(--chat-max-width) flex-col gap-3 pt-2"
+      <Stack gap={0} className="h-full min-h-0 flex-1">
+        <Stack gap={0} className="min-h-0 flex-1 overflow-y-auto scroll-smooth">
+          <Stack gap={0} className="overflow-y-visible p-4 sm:p-6">
+            <Stack
+              gap={3}
+              className="mx-auto w-full max-w-(--chat-max-width) pt-2"
               role="log"
               aria-live="polite"
               aria-labelledby={messageHistoryLabelId}
@@ -258,7 +260,11 @@ export function DiscussionThreadView({
                 />
               ))}
               {linkedTaskId ? (
-                <div className="text-muted-foreground flex items-center justify-center gap-2 py-2 text-xs">
+                <Row
+                  gap={2}
+                  justify="center"
+                  className="text-muted-foreground py-2 text-xs"
+                >
                   <GitBranchPlus className="size-3.5 shrink-0" aria-hidden />
                   <span>{t('spawnTask.converted')}</span>
                   <Link
@@ -272,11 +278,11 @@ export function DiscussionThreadView({
                   >
                     {t('spawnTask.viewTask')}
                   </Link>
-                </div>
+                </Row>
               ) : null}
-            </div>
-          </div>
-        </div>
+            </Stack>
+          </Stack>
+        </Stack>
 
         <PanelFooter>
           <FileUpload.Root>
@@ -306,7 +312,7 @@ export function DiscussionThreadView({
             {t('reply.hint')}
           </Text>
         </PanelFooter>
-      </div>
-    </div>
+      </Stack>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/discussions/components/project-discussions-tab.tsx b/services/platform/app/features/discussions/components/project-discussions-tab.tsx
index bcdd3a9094..e02c99cfcd 100644
--- a/services/platform/app/features/discussions/components/project-discussions-tab.tsx
+++ b/services/platform/app/features/discussions/components/project-discussions-tab.tsx
@@ -65,9 +65,7 @@ export function ProjectDiscussionsTab({
           title={t('title')}
           description={t('subtitle')}
           action={
-            <Button size="sm" onClick={() => setCreateOpen(true)}>
-              {t('new')}
-            </Button>
+            <Button onClick={() => setCreateOpen(true)}>{t('new')}</Button>
           }
         />
 
diff --git a/services/platform/app/features/documents/components/breadcrumb-navigation.tsx b/services/platform/app/features/documents/components/breadcrumb-navigation.tsx
index cbc3685a19..ffc5419b19 100644
--- a/services/platform/app/features/documents/components/breadcrumb-navigation.tsx
+++ b/services/platform/app/features/documents/components/breadcrumb-navigation.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { ChevronLeft } from 'lucide-react';
 import { useEffect, useRef } from 'react';
 
@@ -42,7 +43,7 @@ export function BreadcrumbNavigation({
       className="bg-background sticky top-14 z-10 mb-4"
       aria-label={t('breadcrumb.navigation')}
     >
-      <ol className="flex items-center gap-1">
+      <Row as="ol" gap={1}>
         <li className="flex items-center gap-1">
           <button
             onClick={() => onNavigate(undefined)}
@@ -95,7 +96,7 @@ export function BreadcrumbNavigation({
             </li>
           );
         })}
-      </ol>
+      </Row>
     </nav>
   );
 }
diff --git a/services/platform/app/features/documents/components/document-comparison/comparison-change-block.tsx b/services/platform/app/features/documents/components/document-comparison/comparison-change-block.tsx
index 8dcaf0b68b..ff4d3d2ae5 100644
--- a/services/platform/app/features/documents/components/document-comparison/comparison-change-block.tsx
+++ b/services/platform/app/features/documents/components/document-comparison/comparison-change-block.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { useMemo } from 'react';
 
 import type { ChangeBlock } from '@/convex/agent_tools/documents/helpers/fetch_document_comparison';
@@ -43,7 +44,7 @@ export function ComparisonChangeBlock({
               item.type === 'context' && 'bg-muted/30',
             )}
           >
-            <div className="flex items-start gap-2">
+            <Row gap={2} align="start">
               <span
                 className={cn(
                   'mt-0.5 shrink-0 select-none font-mono text-xs font-semibold',
@@ -92,7 +93,7 @@ export function ComparisonChangeBlock({
                   </span>
                 )}
               </div>
-            </div>
+            </Row>
           </div>
         ))}
       </div>
@@ -142,7 +143,7 @@ function ModifiedContent({
   }
 
   return (
-    <div className="flex flex-col gap-1">
+    <Stack gap={1}>
       {baseContent && (
         <div className="text-red-700 line-through dark:text-red-400">
           <span className="sr-only">{t('comparison.removedText')}</span>
@@ -155,7 +156,7 @@ function ModifiedContent({
           {comparisonContent}
         </div>
       )}
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/documents/components/document-comparison/comparison-file-selector.tsx b/services/platform/app/features/documents/components/document-comparison/comparison-file-selector.tsx
index fc2ad1c52b..aa2f98a0f0 100644
--- a/services/platform/app/features/documents/components/document-comparison/comparison-file-selector.tsx
+++ b/services/platform/app/features/documents/components/document-comparison/comparison-file-selector.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Tabs } from '@tale/ui/tabs';
 import { FileText, Upload, X } from 'lucide-react';
 import { useState, useCallback, useMemo } from 'react';
@@ -121,9 +122,9 @@ export function ComparisonFileSelector({
 
   if (selectedFile) {
     return (
-      <div className="flex flex-col gap-2">
+      <Stack gap={2}>
         <span className="text-sm font-medium">{label}</span>
-        <div className="bg-muted/30 flex items-center gap-2 rounded-lg border px-3 py-2">
+        <Row gap={2} className="bg-muted/30 rounded-lg border px-3 py-2">
           <FileText
             className="text-muted-foreground size-4 shrink-0"
             aria-hidden="true"
@@ -137,17 +138,17 @@ export function ComparisonFileSelector({
             size="icon"
             onClick={handleClear}
             disabled={disabled}
-            aria-label={t('comparison.clearSelection')}
+            title={t('comparison.clearSelection')}
           >
             <X className="size-3.5" aria-hidden="true" />
           </Button>
-        </div>
-      </div>
+        </Row>
+      </Stack>
     );
   }
 
   return (
-    <div className="flex flex-col gap-2">
+    <Stack gap={2}>
       <span className="text-sm font-medium">{label}</span>
       <Tabs items={tabItems} value={activeTab} onValueChange={setActiveTab} />
 
@@ -207,6 +208,6 @@ export function ComparisonFileSelector({
           aria-label={label}
         />
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/documents/components/document-comparison/comparison-results.tsx b/services/platform/app/features/documents/components/document-comparison/comparison-results.tsx
index ad5698146b..2642aa6cd1 100644
--- a/services/platform/app/features/documents/components/document-comparison/comparison-results.tsx
+++ b/services/platform/app/features/documents/components/document-comparison/comparison-results.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row, Stack } from '@tale/ui/layout';
 import { AlertTriangle } from 'lucide-react';
 
 import type { DocumentComparisonResult } from '@/convex/agent_tools/documents/helpers/fetch_document_comparison';
@@ -17,12 +18,8 @@ export function ComparisonResults({ result }: ComparisonResultsProps) {
   const { stats, changeBlocks, truncated } = result;
 
   return (
-    <div className="flex flex-col gap-4">
-      <div
-        className="flex flex-wrap items-center gap-2"
-        role="group"
-        aria-label={t('comparison.statsSummary')}
-      >
+    <Stack>
+      <Row gap={2} wrap role="group" aria-label={t('comparison.statsSummary')}>
         {stats.added > 0 && (
           <Badge variant="green" dot>
             {t('comparison.statsAdded', { count: stats.added })}
@@ -43,11 +40,12 @@ export function ComparisonResults({ result }: ComparisonResultsProps) {
             {t('comparison.statsUnchanged', { count: stats.unchanged })}
           </Badge>
         )}
-      </div>
+      </Row>
 
       {stats.highDivergence && (
-        <div
-          className="flex items-center gap-2 rounded-lg border border-yellow-200 bg-yellow-50 px-3 py-2 dark:border-yellow-800 dark:bg-yellow-950/30"
+        <Row
+          gap={2}
+          className="rounded-lg border border-yellow-200 bg-yellow-50 px-3 py-2 dark:border-yellow-800 dark:bg-yellow-950/30"
           role="alert"
         >
           <AlertTriangle
@@ -57,18 +55,19 @@ export function ComparisonResults({ result }: ComparisonResultsProps) {
           <span className="text-sm text-yellow-800 dark:text-yellow-300">
             {t('comparison.highDivergence')}
           </span>
-        </div>
+        </Row>
       )}
 
       {truncated && (
-        <div
-          className="flex items-center gap-2 rounded-lg border border-blue-200 bg-blue-50 px-3 py-2 dark:border-blue-800 dark:bg-blue-950/30"
+        <Row
+          gap={2}
+          className="rounded-lg border border-blue-200 bg-blue-50 px-3 py-2 dark:border-blue-800 dark:bg-blue-950/30"
           role="status"
         >
           <span className="text-sm text-blue-800 dark:text-blue-300">
             {t('comparison.resultsTruncated')}
           </span>
-        </div>
+        </Row>
       )}
 
       {changeBlocks.length === 0 && (
@@ -78,18 +77,14 @@ export function ComparisonResults({ result }: ComparisonResultsProps) {
       )}
 
       {changeBlocks.length > 0 && (
-        <div
-          className="flex flex-col gap-3"
-          role="list"
-          aria-label={t('comparison.changesList')}
-        >
+        <Stack gap={3} role="list" aria-label={t('comparison.changesList')}>
           {changeBlocks.map((block, index) => (
             <div key={index} role="listitem">
               <ComparisonChangeBlock block={block} index={index} />
             </div>
           ))}
-        </div>
+        </Stack>
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/documents/components/document-comparison/document-comparison-dialog.tsx b/services/platform/app/features/documents/components/document-comparison/document-comparison-dialog.tsx
index 4687dbd48b..a0728aa899 100644
--- a/services/platform/app/features/documents/components/document-comparison/document-comparison-dialog.tsx
+++ b/services/platform/app/features/documents/components/document-comparison/document-comparison-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
 import { ArrowRightLeft } from 'lucide-react';
@@ -144,8 +145,8 @@ function DocumentComparisonDialogContent({
       description={t('comparison.description')}
       size="wide"
     >
-      <div className="flex min-w-0 flex-col gap-4 pt-2">
-        <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+      <Stack className="min-w-0 pt-2">
+        <Grid md={2}>
           <ComparisonFileSelector
             label={t('comparison.baseDocument')}
             selectedFile={baseFile}
@@ -162,9 +163,9 @@ function DocumentComparisonDialogContent({
             disabled={isRunning}
             inputId="comparison-target-upload"
           />
-        </div>
+        </Grid>
 
-        <div className="flex items-center justify-end gap-2">
+        <Row gap={2} justify="end">
           {error && (
             <Text variant="error" className="flex-1 text-sm">
               {error}
@@ -179,16 +180,16 @@ function DocumentComparisonDialogContent({
           >
             {t('comparison.compareButton')}
           </Button>
-        </div>
+        </Row>
 
         {isRunning && (
-          <div className="flex items-center justify-center py-8">
+          <Row gap={0} justify="center" className="py-8">
             <Spinner size="md" label={t('comparison.comparing')} />
-          </div>
+          </Row>
         )}
 
         {result && <ComparisonResults result={result} />}
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/documents/components/document-preview-dialog.tsx b/services/platform/app/features/documents/components/document-preview-dialog.tsx
index 3c528b19ef..9bc816000e 100644
--- a/services/platform/app/features/documents/components/document-preview-dialog.tsx
+++ b/services/platform/app/features/documents/components/document-preview-dialog.tsx
@@ -5,7 +5,7 @@ import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
 import { useLocale } from '@tale/ui/i18n/locale-provider';
 import { IconButton } from '@tale/ui/icon-button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Separator } from '@tale/ui/separator';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
@@ -115,8 +115,10 @@ function DetailsSidebar({
       label={t('preview.sidebar.document')}
       className="contents"
     >
-      <aside
-        className="flex w-[220px] shrink-0 flex-col gap-3 overflow-y-auto"
+      <Stack
+        as="aside"
+        gap={3}
+        className="w-[220px] shrink-0 overflow-y-auto"
         aria-label={t('preview.sidebar.document')}
       >
         <SidebarRow label={t('preview.sidebar.document')}>
@@ -195,7 +197,7 @@ function DetailsSidebar({
             </SidebarRow>
           </>
         )}
-      </aside>
+      </Stack>
     </Skeletonize>
   );
 }
@@ -279,7 +281,7 @@ export function DocumentPreviewDialog({
       hideClose
       className="flex h-[85vh] flex-col overflow-hidden p-0 sm:p-0"
       customHeader={
-        <div className="flex max-h-[4.5rem] flex-row items-center justify-between p-5">
+        <Row gap={0} justify="between" className="max-h-[4.5rem] p-5">
           <Heading level={2} tracking="tight" className="leading-none">
             {t('preview.title')}
           </Heading>
@@ -288,7 +290,6 @@ export function DocumentPreviewDialog({
             {resolvedUrl && (
               <Button
                 variant="secondary"
-                size="sm"
                 onClick={handleDownload}
                 disabled={isDownloading}
                 aria-label={t('preview.downloadFile')}
@@ -307,7 +308,7 @@ export function DocumentPreviewDialog({
               onClick={() => onOpenChange(false)}
             />
           </ActionRow>
-        </div>
+        </Row>
       }
     >
       {!isLoading && !resolvedUrl && open ? (
@@ -322,8 +323,8 @@ export function DocumentPreviewDialog({
         // layout jumping. The preview pane keeps the lazy/inflight
         // `PreviewPaneSkeleton` fallback until a URL resolves; the sidebar
         // renders its real structure with masked leaves while loading.
-        <div className="flex h-full min-h-0 gap-5 px-5 pb-5">
-          <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+        <Row gap={5} align="stretch" className="h-full min-h-0 px-5 pb-5">
+          <Stack gap={0} className="min-h-0 min-w-0 flex-1">
             {resolvedUrl ? (
               <DocumentPreview
                 url={resolvedUrl}
@@ -333,12 +334,12 @@ export function DocumentPreviewDialog({
             ) : (
               <PreviewPaneSkeleton />
             )}
-          </div>
+          </Stack>
           {/* The metadata sidebar only renders when a `documentId` is in play;
               gate it the same way so the citation-card (fileId-only) path isn't
               given a column it never fills. */}
           {documentId && <DetailsSidebar doc={doc} loading={isLoading} />}
-        </div>
+        </Row>
       )}
     </Dialog>
   );
diff --git a/services/platform/app/features/documents/components/document-preview-image.test.tsx b/services/platform/app/features/documents/components/document-preview-image.test.tsx
index 9fc75bf440..2ea025feab 100644
--- a/services/platform/app/features/documents/components/document-preview-image.test.tsx
+++ b/services/platform/app/features/documents/components/document-preview-image.test.tsx
@@ -14,9 +14,9 @@ vi.mock('@/lib/i18n/client', () => ({
           'preview.document': 'Document',
         },
         common: {
-          'imagePreview.zoomIn': 'Zoom in',
-          'imagePreview.zoomOut': 'Zoom out',
-          'imagePreview.resetZoom': 'Reset zoom',
+          'flow.zoomIn': 'Zoom in',
+          'flow.zoomOut': 'Zoom out',
+          'flow.resetView': 'Reset view',
         },
       };
       return translations[ns]?.[key] ?? key;
@@ -88,7 +88,7 @@ describe('DocumentPreviewImage', () => {
       screen.getByRole('button', { name: 'Zoom out' }),
     ).toBeInTheDocument();
     expect(
-      screen.getByRole('button', { name: 'Reset zoom' }),
+      screen.getByRole('button', { name: 'Reset view' }),
     ).toBeInTheDocument();
   });
 
diff --git a/services/platform/app/features/documents/components/document-preview-pdf.tsx b/services/platform/app/features/documents/components/document-preview-pdf.tsx
index cf51829de2..9e482a3679 100644
--- a/services/platform/app/features/documents/components/document-preview-pdf.tsx
+++ b/services/platform/app/features/documents/components/document-preview-pdf.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -457,9 +457,14 @@ export const DocumentPreviewPDF = ({ url }: { url: string }) => {
   };
 
   return (
-    <div ref={containerRef} className="relative flex min-h-0 flex-1 flex-col">
+    <Stack ref={containerRef} gap={0} className="relative min-h-0 flex-1">
       <PreviewPane className="overflow-x-auto">
-        <div className="flex min-h-full w-fit min-w-full justify-center">
+        <Row
+          gap={0}
+          align="stretch"
+          justify="center"
+          className="min-h-full w-fit min-w-full"
+        >
           {/* Sized imperatively to the page's CSS footprint after each render so
               the canvas and the pdfjs-appended text/annotation layers share
               identical dimensions and stay pixel-aligned. The click handler is
@@ -475,7 +480,7 @@ export const DocumentPreviewPDF = ({ url }: { url: string }) => {
           >
             <canvas ref={canvasRef} className="block size-full" />
           </div>
-        </div>
+        </Row>
         {!state.pdfDoc && (
           // Document-shaped pulse matching the rendered page footprint, so the
           // first painted page swaps in without the pane jumping from a
@@ -492,7 +497,12 @@ export const DocumentPreviewPDF = ({ url }: { url: string }) => {
         )}
       </PreviewPane>
       {/* Floating toolbar pinned to the bottom of the visible pane (draggable) */}
-      <div className="pointer-events-none absolute inset-x-0 bottom-4 z-50 flex justify-center">
+      <Row
+        gap={0}
+        align="stretch"
+        justify="center"
+        className="pointer-events-none absolute inset-x-0 bottom-4 z-50"
+      >
         <HStack
           ref={toolbarRef}
           gap={2}
@@ -561,10 +571,10 @@ export const DocumentPreviewPDF = ({ url }: { url: string }) => {
             </button>
           </HStack>
         </HStack>
-      </div>
+      </Row>
       {linkPopup && (
         <PdfLinkPopup state={linkPopup} onClose={() => setLinkPopup(null)} />
       )}
-    </div>
+    </Stack>
   );
 };
diff --git a/services/platform/app/features/documents/components/document-preview.tsx b/services/platform/app/features/documents/components/document-preview.tsx
index 05f4236613..df4042a5c2 100644
--- a/services/platform/app/features/documents/components/document-preview.tsx
+++ b/services/platform/app/features/documents/components/document-preview.tsx
@@ -168,7 +168,7 @@ export function DocumentPreview({
         title={t('preview.notAvailable')}
         description={t('preview.notAvailableDescription')}
         action={
-          <Button size="sm" onClick={handleDownload} disabled={isDownloading}>
+          <Button onClick={handleDownload} disabled={isDownloading}>
             {isDownloading ? (
               <>
                 <Loader2 className="mr-2 size-4 animate-spin" />{' '}
diff --git a/services/platform/app/features/documents/components/document-team-tags-dialog.tsx b/services/platform/app/features/documents/components/document-team-tags-dialog.tsx
index 076962dd8d..69fe0c75fe 100644
--- a/services/platform/app/features/documents/components/document-team-tags-dialog.tsx
+++ b/services/platform/app/features/documents/components/document-team-tags-dialog.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { EmptyState } from '@tale/ui/empty-state';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useNavigate } from '@tanstack/react-router';
 import { Settings, Users } from 'lucide-react';
@@ -165,11 +166,11 @@ function DocumentTeamDialogContent({
       }
     >
       {isLoading ? (
-        <div className="flex items-center justify-center py-8">
+        <Row gap={0} justify="center" className="py-8">
           <Text as="span" variant="muted">
             {tCommon('actions.loading')}
           </Text>
-        </div>
+        </Row>
       ) : !hasTeams ? (
         <EmptyState
           icon={Users}
@@ -179,7 +180,6 @@ function DocumentTeamDialogContent({
             <Button
               type="button"
               variant="secondary"
-              size="sm"
               onClick={handleGoToSettings}
             >
               <Settings className="size-3.5" aria-hidden="true" />
diff --git a/services/platform/app/features/documents/components/document-upload-dialog.tsx b/services/platform/app/features/documents/components/document-upload-dialog.tsx
index a1d0de96be..dd178fdda5 100644
--- a/services/platform/app/features/documents/components/document-upload-dialog.tsx
+++ b/services/platform/app/features/documents/components/document-upload-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { CircleCheck, RotateCw, Upload } from 'lucide-react';
 import { useState, useCallback, useEffect, useMemo } from 'react';
@@ -272,7 +273,7 @@ export function DocumentUploadDialog({
       title={tDocuments('upload.importDocuments')}
       size="md"
     >
-      <div className="flex min-w-0 flex-col gap-4 pt-2">
+      <Stack className="min-w-0 pt-2">
         {/* Drop zone */}
         <FileUpload.Root>
           <FileUpload.DropZone
@@ -302,14 +303,14 @@ export function DocumentUploadDialog({
         </FileUpload.Root>
 
         {/* Team selection */}
-        <div className="flex flex-col gap-2">
+        <Stack gap={2}>
           <span className="text-muted-foreground text-sm font-medium">
             {tDocuments('upload.selectTeams')}
           </span>
           {isLoadingTeams ? (
-            <div className="flex items-center justify-center py-3">
+            <Row gap={0} justify="center" className="py-3">
               <Spinner size="sm" label={tCommon('actions.loading')} />
-            </div>
+            </Row>
           ) : (
             <TeamMultiSelect
               teams={teams ?? []}
@@ -324,7 +325,7 @@ export function DocumentUploadDialog({
               {tDocuments('upload.teamLockedToFolder')}
             </span>
           )}
-        </div>
+        </Stack>
 
         {/* Upload progress summary */}
         {hasFiles && totalCount > 1 && (
@@ -344,7 +345,10 @@ export function DocumentUploadDialog({
 
         {/* Success banner */}
         {allCompleted && (
-          <div className="flex items-center gap-2 rounded-lg border border-green-200 bg-green-50 px-3 py-2">
+          <Row
+            gap={2}
+            className="rounded-lg border border-green-200 bg-green-50 px-3 py-2"
+          >
             <CircleCheck className="size-4 shrink-0 text-green-700" />
             <span className="flex-1 text-[13px] font-medium text-green-700">
               {tDocuments('upload.documentsUploadedSuccessfully', {
@@ -354,12 +358,12 @@ export function DocumentUploadDialog({
             <span className="shrink-0 text-xs text-green-600">
               {formatBytes(totalSize)}
             </span>
-          </div>
+          </Row>
         )}
 
         {/* File list */}
         {hasFiles && (
-          <div className="flex max-h-52 flex-col gap-1 overflow-y-auto">
+          <Stack gap={1} className="max-h-52 overflow-y-auto">
             {trackedFiles.map((tracked) => (
               <UploadFileRow
                 key={tracked.id}
@@ -377,42 +381,31 @@ export function DocumentUploadDialog({
                 }
               />
             ))}
-          </div>
+          </Stack>
         )}
 
         {/* Footer actions */}
-        <div className="flex items-center justify-end gap-2">
+        <Row gap={2} justify="end">
           {hasFailures && !isUploading && !hasPendingFiles && (
-            <Button
-              type="button"
-              size="sm"
-              onClick={handleRetryAll}
-              className="gap-1.5"
-            >
+            <Button type="button" onClick={handleRetryAll} className="gap-1.5">
               <RotateCw className="size-3.5" />
               {tDocuments('upload.retryUpload')}
             </Button>
           )}
           {isUploading && (
-            <Button
-              type="button"
-              variant="secondary"
-              size="sm"
-              onClick={handleCancel}
-            >
+            <Button type="button" variant="secondary" onClick={handleCancel}>
               {tDocuments('upload.cancelUpload')}
             </Button>
           )}
           <Button
             type="button"
-            size="sm"
             onClick={handleUpload}
             disabled={!hasPendingFiles || isUploading || allCompleted}
           >
             {tDocuments('upload.uploadDocuments')}
           </Button>
-        </div>
-      </div>
+        </Row>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/documents/components/onedrive-import/onedrive-picker-stage.tsx b/services/platform/app/features/documents/components/onedrive-import/onedrive-picker-stage.tsx
index 4229d9b3c3..5b1a0a13e4 100644
--- a/services/platform/app/features/documents/components/onedrive-import/onedrive-picker-stage.tsx
+++ b/services/platform/app/features/documents/components/onedrive-import/onedrive-picker-stage.tsx
@@ -167,7 +167,6 @@ export function OneDrivePickerStage({
                 wrapperClassName="flex-1"
               />
               <Button
-                size="sm"
                 onClick={onProceedToSettings}
                 disabled={selectedItems.size === 0}
                 className="px-6 whitespace-nowrap"
@@ -236,7 +235,6 @@ export function OneDrivePickerStage({
                     wrapperClassName="flex-1"
                   />
                   <Button
-                    size="sm"
                     onClick={onProceedToSettings}
                     disabled={selectedItems.size === 0}
                     className="px-6 whitespace-nowrap"
diff --git a/services/platform/app/features/documents/components/onedrive-import/onedrive-settings-stage.tsx b/services/platform/app/features/documents/components/onedrive-import/onedrive-settings-stage.tsx
index 996589477d..613e65166c 100644
--- a/services/platform/app/features/documents/components/onedrive-import/onedrive-settings-stage.tsx
+++ b/services/platform/app/features/documents/components/onedrive-import/onedrive-settings-stage.tsx
@@ -3,7 +3,7 @@
 import { Button } from '@tale/ui/button';
 import { Description } from '@tale/ui/description';
 import { EmptyPlaceholder } from '@tale/ui/empty-placeholder';
-import { Stack, HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SectionHeader } from '@tale/ui/section-header';
 import { SelectableRow } from '@tale/ui/selectable-row';
 import { Separator } from '@tale/ui/separator';
@@ -91,14 +91,19 @@ export function OneDriveSettingsStage({
     footer,
     footerClassName: 'border-t border-border p-4',
     customHeader: (
-      <div className="border-border flex items-start justify-between border-b px-6 py-5">
+      <Row
+        gap={0}
+        align="start"
+        justify="between"
+        className="border-border border-b px-6 py-5"
+      >
         <SectionHeader
           title={t('onedrive.importSettings')}
           description={t('onedrive.settingsDescription', {
             count: selectedItemCount,
           })}
         />
-      </div>
+      </Row>
     ),
     content: (
       <Stack gap={4} className="px-6 py-2">
@@ -155,9 +160,9 @@ export function OneDriveSettingsStage({
           description={t('upload.selectTeamsDescription')}
         >
           {isLoadingTeams ? (
-            <div className="flex items-center justify-center py-4">
+            <Row gap={0} justify="center" className="py-4">
               <Spinner size="sm" label={tCommon('actions.loading')} />
-            </div>
+            </Row>
           ) : !teams || teams.length === 0 ? (
             <EmptyPlaceholder icon={Users}>
               {t('upload.noTeamsAvailable')}
diff --git a/services/platform/app/features/documents/components/onedrive-import/sharepoint-drives-table.tsx b/services/platform/app/features/documents/components/onedrive-import/sharepoint-drives-table.tsx
index 009f4fe74c..208090840e 100644
--- a/services/platform/app/features/documents/components/onedrive-import/sharepoint-drives-table.tsx
+++ b/services/platform/app/features/documents/components/onedrive-import/sharepoint-drives-table.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { EmptyState } from '@tale/ui/empty-state';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Database } from 'lucide-react';
@@ -35,9 +35,13 @@ export function SharePointDrivesTable({
           const drive = row.original;
           return (
             <HStack gap={3}>
-              <div className="flex size-8 items-center justify-center rounded-md bg-amber-100 dark:bg-amber-900/30">
+              <Row
+                gap={0}
+                justify="center"
+                className="size-8 rounded-md bg-amber-100 dark:bg-amber-900/30"
+              >
                 <Database className="size-4 text-amber-600 dark:text-amber-400" />
-              </div>
+              </Row>
               <div className="min-w-0 flex-1">
                 <div className="text-foreground cursor-pointer truncate font-medium hover:text-blue-600">
                   {drive.name}
diff --git a/services/platform/app/features/documents/components/onedrive-import/sharepoint-sites-table.tsx b/services/platform/app/features/documents/components/onedrive-import/sharepoint-sites-table.tsx
index e86149105b..2eb0ff3944 100644
--- a/services/platform/app/features/documents/components/onedrive-import/sharepoint-sites-table.tsx
+++ b/services/platform/app/features/documents/components/onedrive-import/sharepoint-sites-table.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { EmptyState } from '@tale/ui/empty-state';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { useMemo } from 'react';
@@ -36,9 +36,13 @@ export function SharePointSitesTable({
           const site = row.original;
           return (
             <HStack gap={3}>
-              <div className="flex size-8 items-center justify-center rounded-md bg-teal-100 dark:bg-teal-900/30">
+              <Row
+                gap={0}
+                justify="center"
+                className="size-8 rounded-md bg-teal-100 dark:bg-teal-900/30"
+              >
                 <SharePointIcon className="size-5" />
-              </div>
+              </Row>
               <div className="min-w-0 flex-1">
                 <div className="text-foreground cursor-pointer truncate font-medium hover:text-blue-600">
                   {site.displayName}
diff --git a/services/platform/app/features/documents/components/upload-file-row.tsx b/services/platform/app/features/documents/components/upload-file-row.tsx
index 60b6b9f478..ddad3e0413 100644
--- a/services/platform/app/features/documents/components/upload-file-row.tsx
+++ b/services/platform/app/features/documents/components/upload-file-row.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { CircleAlert, CircleCheck, RotateCw, X } from 'lucide-react';
 import { memo } from 'react';
 
@@ -79,7 +80,7 @@ export const UploadFileRow = memo(function UploadFileRow({
       )}
     >
       {/* File info row */}
-      <div className="flex items-center gap-2">
+      <Row gap={2}>
         {/* Type badge */}
         <span
           className={cn(
@@ -161,7 +162,7 @@ export const UploadFileRow = memo(function UploadFileRow({
             <X className="text-muted-foreground size-2.5" />
           </button>
         )}
-      </div>
+      </Row>
 
       {/* Progress bar (only for uploading) */}
       {isUploading && (
diff --git a/services/platform/app/features/knowledge-entries/components/knowledge-entries-table.tsx b/services/platform/app/features/knowledge-entries/components/knowledge-entries-table.tsx
index 4656df64a7..e1be3b111d 100644
--- a/services/platform/app/features/knowledge-entries/components/knowledge-entries-table.tsx
+++ b/services/platform/app/features/knowledge-entries/components/knowledge-entries-table.tsx
@@ -1,12 +1,11 @@
 'use client';
 
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { BookOpen, Plus } from 'lucide-react';
+import { BookOpen } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { BulkDeleteBar } from '@/app/components/ui/data-table/data-table-bulk-actions';
-import { useAbility } from '@/app/hooks/use-ability';
 import { useListPage } from '@/app/hooks/use-list-page';
 import { toId } from '@/convex/lib/type_cast_helpers';
 import { useT } from '@/lib/i18n/client';
@@ -30,9 +29,6 @@ export function KnowledgeEntriesTable({
 }: KnowledgeEntriesTableProps) {
   const { t: tEmpty } = useT('emptyStates');
   const { t } = useT('knowledgeEntries');
-  const ability = useAbility();
-  const canWrite = ability.can('write', 'knowledgeWrite');
-  // Lifted so the action menu and the empty-state CTA share one dialog.
   const [createOpen, setCreateOpen] = useState(false);
 
   const { data: count } = useApproxKnowledgeEntryCount(organizationId);
@@ -109,13 +105,6 @@ export function KnowledgeEntriesTable({
           icon: BookOpen,
           title: tEmpty('knowledgeEntries.title'),
           description: tEmpty('knowledgeEntries.description'),
-          action: canWrite
-            ? {
-                label: t('addButton'),
-                icon: Plus,
-                onClick: () => setCreateOpen(true),
-              }
-            : undefined,
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/knowledge-entries/hooks/use-knowledge-entries-table-config.tsx b/services/platform/app/features/knowledge-entries/hooks/use-knowledge-entries-table-config.tsx
index f7917c9d5c..0b0139d401 100644
--- a/services/platform/app/features/knowledge-entries/hooks/use-knowledge-entries-table-config.tsx
+++ b/services/platform/app/features/knowledge-entries/hooks/use-knowledge-entries-table-config.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { BookOpen } from 'lucide-react';
@@ -40,9 +40,13 @@ export function useKnowledgeEntriesTableConfig(): KnowledgeEntriesTableConfig {
         size: 240,
         cell: ({ row }) => (
           <HStack gap={2}>
-            <div className="bg-muted flex size-5 shrink-0 items-center justify-center rounded">
+            <Row
+              gap={0}
+              justify="center"
+              className="bg-muted size-5 shrink-0 rounded"
+            >
               <BookOpen className="text-muted-foreground size-3" />
-            </div>
+            </Row>
             <Text as="span" variant="label" truncate>
               {row.original.topic}
             </Text>
diff --git a/services/platform/app/features/notifications/components/notification-list-panel.tsx b/services/platform/app/features/notifications/components/notification-list-panel.tsx
index 680b417abb..c7287ec669 100644
--- a/services/platform/app/features/notifications/components/notification-list-panel.tsx
+++ b/services/platform/app/features/notifications/components/notification-list-panel.tsx
@@ -2,7 +2,6 @@
 
 import { Button } from '@tale/ui/button';
 import { Tabs } from '@tale/ui/tabs';
-import { useNavigate } from '@tanstack/react-router';
 import { CheckCheck, ChevronLeft, Inbox, Loader2 } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
@@ -14,7 +13,6 @@ import {
   useMyNotifications,
   useUnreadNotificationCount,
 } from '@/app/features/inbox/hooks/queries';
-import { useFormatDate } from '@/app/hooks/use-format-date';
 import type { Id } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
@@ -29,6 +27,11 @@ import {
   useNotificationsUnreadCount,
   type NotificationsFilter,
 } from '../hooks/queries';
+import {
+  orgNotificationTarget,
+  personalNotificationTarget,
+} from '../lib/notification-target';
+import { NotificationRow } from './notification-row';
 import { ReviewActions } from './review-actions';
 
 interface NotificationListPanelProps {
@@ -73,8 +76,6 @@ export function NotificationListPanel({
   const { t } = useT('notifications');
   const { t: tInbox } = useT('inbox');
   const { t: tCommon } = useT('common');
-  const { formatRelative, formatDate } = useFormatDate();
-  const navigate = useNavigate();
 
   const { results, status, loadMore } = useNotificationsList(organizationId);
   const { data: unread } = useNotificationsUnreadCount(organizationId);
@@ -89,23 +90,6 @@ export function NotificationListPanel({
   const markMyRead = useMarkMyNotificationRead();
   const markAllMyRead = useMarkAllMyNotificationsRead();
 
-  const openMyNotification = useCallback(
-    (notif: (typeof myNotifications)[number]) => {
-      if (!notif.read) markMyRead.mutate({ notificationId: notif._id });
-      const params = isRecord(notif.params) ? notif.params : undefined;
-      const projectId = params?.projectId;
-      if (notif.taskId && typeof projectId === 'string') {
-        void navigate({
-          to: '/dashboard/$id/projects/$projectId/tasks',
-          params: { id: organizationId, projectId },
-          search: { task: String(notif.taskId) },
-        });
-        onNavigate?.();
-      }
-    },
-    [markMyRead, navigate, organizationId, onNavigate],
-  );
-
   const handleMarkRead = useCallback(
     (notificationId: Id<'notifications'>) => {
       setHiddenIds((prev) => {
@@ -118,6 +102,18 @@ export function NotificationListPanel({
     [markRead],
   );
 
+  const handleMarkMyRead = useCallback(
+    (notificationId: Id<'userNotifications'>) => {
+      setHiddenIds((prev) => {
+        const next = new Set(prev);
+        next.add(notificationId);
+        return next;
+      });
+      void markMyRead.mutateAsync({ notificationId });
+    },
+    [markMyRead],
+  );
+
   const handleMarkAllRead = useCallback(() => {
     if (filter === 'unread') {
       setHiddenIds((prev) => {
@@ -125,12 +121,22 @@ export function NotificationListPanel({
         for (const n of results) {
           if (!n.read) next.add(n._id);
         }
+        for (const n of myNotifications) {
+          if (!n.read) next.add(n._id);
+        }
         return next;
       });
     }
     void markAllRead.mutateAsync({ organizationId });
     void markAllMyRead.mutateAsync({ organizationId });
-  }, [filter, markAllRead, markAllMyRead, organizationId, results]);
+  }, [
+    filter,
+    markAllRead,
+    markAllMyRead,
+    organizationId,
+    results,
+    myNotifications,
+  ]);
 
   const handleFilterChange = useCallback((next: NotificationsFilter) => {
     setFilter(next);
@@ -143,10 +149,13 @@ export function NotificationListPanel({
     for (const n of results) {
       if (hiddenIds.has(n._id) && !n.read) stillPresent.add(n._id);
     }
+    for (const n of myNotifications) {
+      if (hiddenIds.has(n._id) && !n.read) stillPresent.add(n._id);
+    }
     if (stillPresent.size !== hiddenIds.size) {
       setHiddenIds(stillPresent);
     }
-  }, [results, hiddenIds]);
+  }, [results, myNotifications, hiddenIds]);
 
   // Filter client-side so toggling Unread/All never changes the query key (a
   // query reset would re-flash the skeleton). `hiddenIds` covers the optimistic
@@ -188,7 +197,6 @@ export function NotificationListPanel({
           </div>
           {unreadCount > 0 && (
             <Button
-              size="sm"
               variant="ghost"
               disabled={markAllRead.isPending}
               onClick={handleMarkAllRead}
@@ -259,118 +267,59 @@ export function NotificationListPanel({
                 typeof params?.approvalId === 'string'
                   ? params.approvalId
                   : undefined;
-              const canNavigate =
-                n.taskId !== undefined && typeof params?.projectId === 'string';
+              const target = personalNotificationTarget({
+                organizationId,
+                taskId: n.taskId,
+                params: n.params,
+              });
               return (
-                <li key={n._id} className={cn(!n.read && 'bg-accent/10')}>
-                  <div className="flex w-full items-start gap-3 px-4 py-3">
-                    <span
-                      aria-hidden
-                      className={cn(
-                        'mt-1.5 size-2 shrink-0 rounded-full',
-                        n.read ? 'bg-transparent' : 'bg-sky-500',
-                      )}
+                <NotificationRow
+                  key={n._id}
+                  title={tInbox(n.titleKey)}
+                  body={tInbox(
+                    n.bodyKey,
+                    // `params` is the i18n interpolation map (stored as
+                    // v.any()); narrow to what t() accepts.
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- jsonRecord interpolation map
+                    params as Record<string, string | number>,
+                  )}
+                  createdAt={n.createdAt}
+                  read={n.read}
+                  target={target}
+                  onActivate={() => {
+                    if (!n.read) handleMarkMyRead(n._id);
+                    if (target) onNavigate?.();
+                  }}
+                  onMarkRead={() => handleMarkMyRead(n._id)}
+                  markReadPending={markMyRead.isPending}
+                >
+                  {approvalId && (
+                    <ReviewActions
+                      notificationId={n._id}
+                      approvalId={approvalId}
                     />
-                    <div className="min-w-0 flex-1">
-                      <button
-                        type="button"
-                        onClick={() => openMyNotification(n)}
-                        disabled={!canNavigate && n.read}
-                        className={cn(
-                          'block w-full text-left',
-                          (canNavigate || !n.read) && 'cursor-pointer',
-                        )}
-                      >
-                        <div className="flex items-start justify-between gap-2">
-                          <div className="text-foreground text-sm font-medium">
-                            {tInbox(n.titleKey)}
-                          </div>
-                          <span
-                            className="text-muted-foreground shrink-0 text-[10px]"
-                            title={formatDate(new Date(n.createdAt), 'long')}
-                          >
-                            {formatRelative(new Date(n.createdAt))}
-                          </span>
-                        </div>
-                        <div className="text-muted-foreground mt-0.5 text-xs whitespace-pre-wrap">
-                          {tInbox(
-                            n.bodyKey,
-                            // `params` is the i18n interpolation map (stored
-                            // as v.any()); narrow to what t() accepts.
-                            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- jsonRecord interpolation map
-                            params as Record<string, string | number>,
-                          )}
-                        </div>
-                      </button>
-                      {approvalId && (
-                        <ReviewActions
-                          notificationId={n._id}
-                          approvalId={approvalId}
-                        />
-                      )}
-                    </div>
-                  </div>
-                </li>
+                  )}
+                </NotificationRow>
               );
             })}
             {items.map((n) => {
               const params = isRecord(n.params) ? n.params : undefined;
-              const title = t(stripNsPrefix(n.titleKey), params);
-              const body = t(stripNsPrefix(n.bodyKey), params);
-              const absoluteDate = formatDate(new Date(n.createdAt), 'long');
-
-              const rowClasses = cn(
-                'flex w-full items-start gap-3 px-4 py-3 text-left transition-colors',
-                !n.read && 'bg-accent/10 hover:bg-muted/60 cursor-pointer',
-                n.read && 'opacity-70 cursor-default',
-              );
-              const rowBody = (
-                <>
-                  {!n.read && (
-                    <span className="sr-only">{t('ariaUnread')}</span>
-                  )}
-                  <span
-                    aria-hidden
-                    className={cn(
-                      'mt-1.5 size-2 shrink-0 rounded-full',
-                      n.read ? 'bg-transparent' : 'bg-sky-500',
-                    )}
-                  />
-                  <div className="min-w-0 flex-1">
-                    <div className="flex items-start justify-between gap-2">
-                      <div className="text-foreground text-sm font-medium">
-                        {title}
-                      </div>
-                      <span
-                        className="text-muted-foreground shrink-0 text-[10px]"
-                        title={absoluteDate}
-                      >
-                        {formatRelative(new Date(n.createdAt))}
-                      </span>
-                    </div>
-                    <div className="text-muted-foreground mt-0.5 text-xs whitespace-pre-wrap">
-                      {body}
-                    </div>
-                  </div>
-                </>
-              );
-
+              const target = orgNotificationTarget(organizationId, n.link);
               return (
-                <li key={n._id}>
-                  {n.read ? (
-                    <div className={rowClasses}>{rowBody}</div>
-                  ) : (
-                    <button
-                      type="button"
-                      aria-label={t('markAsRead')}
-                      disabled={markRead.isPending}
-                      onClick={() => handleMarkRead(n._id)}
-                      className={rowClasses}
-                    >
-                      {rowBody}
-                    </button>
-                  )}
-                </li>
+                <NotificationRow
+                  key={n._id}
+                  title={t(stripNsPrefix(n.titleKey), params)}
+                  body={t(stripNsPrefix(n.bodyKey), params)}
+                  createdAt={n.createdAt}
+                  read={n.read}
+                  target={target}
+                  onActivate={() => {
+                    if (!n.read) handleMarkRead(n._id);
+                    if (target) onNavigate?.();
+                  }}
+                  onMarkRead={() => handleMarkRead(n._id)}
+                  markReadPending={markRead.isPending}
+                />
               );
             })}
           </ul>
@@ -378,7 +327,6 @@ export function NotificationListPanel({
         {(canLoadMore || isLoadingMore) && (
           <div className="border-border border-t p-2">
             <Button
-              size="sm"
               variant="ghost"
               className="w-full"
               disabled={!canLoadMore}
diff --git a/services/platform/app/features/notifications/components/notification-row.tsx b/services/platform/app/features/notifications/components/notification-row.tsx
new file mode 100644
index 0000000000..7e3252e6bc
--- /dev/null
+++ b/services/platform/app/features/notifications/components/notification-row.tsx
@@ -0,0 +1,127 @@
+'use client';
+
+import { IconButton } from '@tale/ui/icon-button';
+import { Link } from '@tanstack/react-router';
+import { Check } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { useFormatDate } from '@/app/hooks/use-format-date';
+import { useT } from '@/lib/i18n/client';
+import { cn } from '@/lib/utils/cn';
+
+import type { NotificationTarget } from '../lib/notification-target';
+
+interface NotificationRowProps {
+  /** Pre-localized title (each stream resolves its own i18n namespace). */
+  title: string;
+  /** Pre-localized body. */
+  body: string;
+  createdAt: number;
+  read: boolean;
+  /** Body deep-link target, or `null` when the row has no destination. */
+  target: NotificationTarget | null;
+  /**
+   * Invoked when the body is activated (clicked). Marks the row read and, when
+   * a `target` exists, closes the host popover. Navigation itself is handled by
+   * the `<Link>` — this is the side-effect hook.
+   */
+  onActivate: () => void;
+  /** Marks the row read WITHOUT navigating — the trailing icon button. */
+  onMarkRead: () => void;
+  markReadPending: boolean;
+  /** Extra content rendered below the body (e.g. `<ReviewActions />`). */
+  children?: ReactNode;
+}
+
+/**
+ * A single notification row shared by both streams (org alerts + personal). The
+ * body is a deep-link (`<Link>`) when a `target` exists, otherwise a plain
+ * dismiss button (unread) or inert text (read). The trailing "mark as read"
+ * icon button is a sibling of the body — never nested — so there is no
+ * interactive-element nesting.
+ */
+export function NotificationRow({
+  title,
+  body,
+  createdAt,
+  read,
+  target,
+  onActivate,
+  onMarkRead,
+  markReadPending,
+  children,
+}: NotificationRowProps) {
+  const { t } = useT('notifications');
+  const { formatRelative, formatDate } = useFormatDate();
+
+  // Clickable when it can navigate (has a target) or when it's unread (a
+  // body-click dismisses it — preserves the pre-existing behavior for rows
+  // without a destination).
+  const interactive = target !== null || !read;
+
+  const bodyClasses = cn(
+    'flex min-w-0 flex-1 items-start gap-3 px-4 py-3 text-left transition-colors',
+    interactive ? 'hover:bg-muted/60 cursor-pointer' : 'cursor-default',
+    read && target === null && 'opacity-70',
+  );
+
+  const inner = (
+    <>
+      {!read && <span className="sr-only">{t('ariaUnread')}</span>}
+      <span
+        aria-hidden
+        className={cn(
+          'mt-1.5 size-2 shrink-0 rounded-full',
+          read ? 'bg-transparent' : 'bg-sky-500',
+        )}
+      />
+      <div className="min-w-0 flex-1">
+        <div className="flex items-start justify-between gap-2">
+          <div className="text-foreground text-sm font-medium">{title}</div>
+          <span
+            className="text-muted-foreground shrink-0 text-[10px]"
+            title={formatDate(new Date(createdAt), 'long')}
+          >
+            {formatRelative(new Date(createdAt))}
+          </span>
+        </div>
+        <div className="text-muted-foreground mt-0.5 text-xs whitespace-pre-wrap">
+          {body}
+        </div>
+      </div>
+    </>
+  );
+
+  return (
+    <li className={cn(!read && 'bg-accent/10')}>
+      <div className="flex items-start">
+        {target ? (
+          <Link {...target} onClick={onActivate} className={bodyClasses}>
+            {inner}
+          </Link>
+        ) : read ? (
+          <div className={bodyClasses}>{inner}</div>
+        ) : (
+          <button type="button" onClick={onActivate} className={bodyClasses}>
+            {inner}
+          </button>
+        )}
+        {!read && (
+          <IconButton
+            icon={Check}
+            aria-label={t('markAsRead')}
+            iconSize={4}
+            disabled={markReadPending}
+            onClick={(e) => {
+              e.stopPropagation();
+              e.preventDefault();
+              onMarkRead();
+            }}
+            className="mt-2 mr-2 shrink-0"
+          />
+        )}
+      </div>
+      {children}
+    </li>
+  );
+}
diff --git a/services/platform/app/features/notifications/components/review-actions.tsx b/services/platform/app/features/notifications/components/review-actions.tsx
index c611f539b8..44a2ddc660 100644
--- a/services/platform/app/features/notifications/components/review-actions.tsx
+++ b/services/platform/app/features/notifications/components/review-actions.tsx
@@ -73,7 +73,6 @@ export function ReviewActions({
       />
       <div className="flex items-center gap-2">
         <Button
-          size="sm"
           variant="secondary"
           disabled={respond.isPending || feedback.trim().length === 0}
           onClick={(e) => {
@@ -84,7 +83,6 @@ export function ReviewActions({
           {t('review.sendFeedback')}
         </Button>
         <Button
-          size="sm"
           variant="ghost"
           disabled={respond.isPending}
           onClick={(e) => {
@@ -99,7 +97,6 @@ export function ReviewActions({
   ) : (
     <div className="mt-2 flex items-center gap-2">
       <Button
-        size="sm"
         icon={CheckCircle2}
         disabled={respond.isPending}
         onClick={(e) => {
@@ -110,7 +107,6 @@ export function ReviewActions({
         {t('review.approve')}
       </Button>
       <Button
-        size="sm"
         variant="secondary"
         disabled={respond.isPending}
         onClick={(e) => {
diff --git a/services/platform/app/features/notifications/lib/notification-target.test.ts b/services/platform/app/features/notifications/lib/notification-target.test.ts
new file mode 100644
index 0000000000..81833cce8f
--- /dev/null
+++ b/services/platform/app/features/notifications/lib/notification-target.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  orgNotificationTarget,
+  personalNotificationTarget,
+} from './notification-target';
+
+const ORG = 'org_123';
+
+describe('personalNotificationTarget', () => {
+  it('builds a task deep-link when taskId + projectId are present', () => {
+    const target = personalNotificationTarget({
+      organizationId: ORG,
+      taskId: 'task_abc',
+      params: { projectId: 'proj_xyz', title: 'Ship it' },
+    });
+    expect(target).toEqual({
+      to: '/dashboard/$id/projects/$projectId/tasks',
+      params: { id: ORG, projectId: 'proj_xyz' },
+      search: { task: 'task_abc' },
+    });
+  });
+
+  it('returns null when projectId is missing (legacy rows)', () => {
+    expect(
+      personalNotificationTarget({
+        organizationId: ORG,
+        taskId: 'task_abc',
+        params: { title: 'No project here' },
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null when taskId is missing', () => {
+    expect(
+      personalNotificationTarget({
+        organizationId: ORG,
+        taskId: undefined,
+        params: { projectId: 'proj_xyz' },
+      }),
+    ).toBeNull();
+  });
+
+  it('tolerates non-record params', () => {
+    expect(
+      personalNotificationTarget({
+        organizationId: ORG,
+        taskId: 'task_abc',
+        params: undefined,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('orgNotificationTarget', () => {
+  it('returns null when there is no link', () => {
+    expect(orgNotificationTarget(ORG, undefined)).toBeNull();
+  });
+
+  it('maps an agent link to the agent detail route', () => {
+    expect(
+      orgNotificationTarget(ORG, { kind: 'agent', agentSlug: 'researcher' }),
+    ).toEqual({
+      to: '/dashboard/$id/agents/$agentId',
+      params: { id: ORG, agentId: 'researcher' },
+    });
+  });
+
+  it('maps audit-logs to the governance logs route', () => {
+    expect(orgNotificationTarget(ORG, { kind: 'audit-logs' })).toEqual({
+      to: '/dashboard/$id/settings/governance/logs',
+      params: { id: ORG },
+    });
+  });
+
+  it('maps dsar to the data-subject-requests route', () => {
+    expect(orgNotificationTarget(ORG, { kind: 'dsar' })).toEqual({
+      to: '/dashboard/$id/settings/governance/data-subject-requests',
+      params: { id: ORG },
+    });
+  });
+
+  it('maps security-monitoring to the governance security route', () => {
+    expect(orgNotificationTarget(ORG, { kind: 'security-monitoring' })).toEqual(
+      {
+        to: '/dashboard/$id/settings/governance/security-monitoring',
+        params: { id: ORG },
+      },
+    );
+  });
+});
diff --git a/services/platform/app/features/notifications/lib/notification-target.ts b/services/platform/app/features/notifications/lib/notification-target.ts
new file mode 100644
index 0000000000..224c7f634b
--- /dev/null
+++ b/services/platform/app/features/notifications/lib/notification-target.ts
@@ -0,0 +1,101 @@
+import { isRecord } from '@/lib/utils/type-utils';
+
+/**
+ * A typed TanStack-Router navigate descriptor for a notification's in-app deep
+ * link. `to` is constrained to the routes we actually emit, so each member is
+ * validated against the real router wherever the value is spread into `<Link>`
+ * or passed to `navigate()`. Returning `null` means "no destination" — the row
+ * body is not a navigation link.
+ */
+export type NotificationTarget =
+  | {
+      to: '/dashboard/$id/projects/$projectId/tasks';
+      params: { id: string; projectId: string };
+      search: { task: string };
+    }
+  | {
+      to: '/dashboard/$id/agents/$agentId';
+      params: { id: string; agentId: string };
+    }
+  | {
+      to: '/dashboard/$id/settings/governance/logs';
+      params: { id: string };
+    }
+  | {
+      to: '/dashboard/$id/settings/governance/data-subject-requests';
+      params: { id: string };
+    }
+  | {
+      to: '/dashboard/$id/settings/governance/security-monitoring';
+      params: { id: string };
+    };
+
+/**
+ * The org-alert `link` shape. Mirrors `notificationLinkValidator` in
+ * `convex/notifications/schema.ts` — keep the two in sync (closed union).
+ */
+export type OrgNotificationLink =
+  | { kind: 'agent'; agentSlug: string }
+  | { kind: 'audit-logs' }
+  | { kind: 'dsar' }
+  | { kind: 'security-monitoring' };
+
+/**
+ * Deep-link target for a PERSONAL notification (`userNotifications`). Every
+ * task-bound type (assignment / status / comment / mention / review) routes to
+ * the task inside its project. Returns `null` when the row lacks the context to
+ * build a link — legacy rows written before `projectId` was stored in `params`,
+ * or non-task resources we don't deep-link yet.
+ */
+export function personalNotificationTarget(args: {
+  organizationId: string;
+  taskId: string | undefined;
+  params: unknown;
+}): NotificationTarget | null {
+  const params = isRecord(args.params) ? args.params : undefined;
+  const projectId = params?.projectId;
+  if (args.taskId && typeof projectId === 'string') {
+    return {
+      to: '/dashboard/$id/projects/$projectId/tasks',
+      params: { id: args.organizationId, projectId },
+      search: { task: args.taskId },
+    };
+  }
+  return null;
+}
+
+/**
+ * Deep-link target for an ORG notification's stored `link`. Returns `null` when
+ * the notification carries no link (legacy rows, or generic workflow alerts).
+ */
+export function orgNotificationTarget(
+  organizationId: string,
+  link: OrgNotificationLink | undefined,
+): NotificationTarget | null {
+  if (!link) return null;
+  const id = organizationId;
+  switch (link.kind) {
+    case 'agent':
+      return {
+        to: '/dashboard/$id/agents/$agentId',
+        params: { id, agentId: link.agentSlug },
+      };
+    case 'audit-logs':
+      return { to: '/dashboard/$id/settings/governance/logs', params: { id } };
+    case 'dsar':
+      return {
+        to: '/dashboard/$id/settings/governance/data-subject-requests',
+        params: { id },
+      };
+    case 'security-monitoring':
+      return {
+        to: '/dashboard/$id/settings/governance/security-monitoring',
+        params: { id },
+      };
+    default: {
+      // Exhaustiveness guard — a new `kind` must extend this switch.
+      const _exhaustive: never = link;
+      return _exhaustive;
+    }
+  }
+}
diff --git a/services/platform/app/features/operator/components/embedded-run.tsx b/services/platform/app/features/operator/components/embedded-run.tsx
index 78ef8cf3a0..ca7f041e69 100644
--- a/services/platform/app/features/operator/components/embedded-run.tsx
+++ b/services/platform/app/features/operator/components/embedded-run.tsx
@@ -18,6 +18,7 @@
  * user-facing way to halt a runaway run from where runs are actually viewed.
  */
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { Text } from '@tale/ui/text';
 import { useState } from 'react';
@@ -68,12 +69,7 @@ function RerunButton({ executionId }: { executionId: Id<'wfExecutions'> }) {
   };
 
   return (
-    <Button
-      size="sm"
-      variant="secondary"
-      disabled={isPending}
-      onClick={() => void run()}
-    >
+    <Button variant="secondary" disabled={isPending} onClick={() => void run()}>
       {t('rerun.button')}
     </Button>
   );
@@ -105,7 +101,6 @@ function StopButton({ executionId }: { executionId: Id<'wfExecutions'> }) {
   return (
     <>
       <Button
-        size="sm"
         variant="destructive"
         disabled={isPending}
         onClick={() => setConfirmOpen(true)}
@@ -143,17 +138,17 @@ export function EmbeddedRun({
   const showRerun = TERMINAL_STATUSES.has(projection.status);
   const showStop = RUNNING_STATUSES.has(projection.status);
   return (
-    <div className="flex flex-col gap-3">
+    <Stack gap={3}>
       {(showRerun || showStop) && (
-        <div className="flex justify-end">
+        <Row gap={0} align="stretch" justify="end">
           {showRerun ? (
             <RerunButton executionId={executionId} />
           ) : (
             <StopButton executionId={executionId} />
           )}
-        </div>
+        </Row>
       )}
       <OperatorView projection={projection} />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/operator/components/part-envelope.tsx b/services/platform/app/features/operator/components/part-envelope.tsx
index 113983b8f5..37fdfd2e21 100644
--- a/services/platform/app/features/operator/components/part-envelope.tsx
+++ b/services/platform/app/features/operator/components/part-envelope.tsx
@@ -105,7 +105,7 @@ export function PartEnvelope({
   );
 
   return (
-    <Card className={cn(isGate && 'bg-muted/30')}>
+    <Card className={cn(isGate && 'bg-bg-muted/30')}>
       <VStack gap={3}>
         <HStack gap={2} className="flex-wrap items-center justify-between">
           {hasBody ? (
diff --git a/services/platform/app/features/operator/components/render-kinds/artifact-panel.tsx b/services/platform/app/features/operator/components/render-kinds/artifact-panel.tsx
index 445007360a..bfc9e05fd1 100644
--- a/services/platform/app/features/operator/components/render-kinds/artifact-panel.tsx
+++ b/services/platform/app/features/operator/components/render-kinds/artifact-panel.tsx
@@ -40,7 +40,7 @@ export function ArtifactPanel({ part }: { part: RenderPart }) {
           <Text as="span" truncate>
             {label}
           </Text>
-          <Button asChild variant="secondary" size="sm">
+          <Button asChild variant="secondary">
             <a href={url} target="_blank" rel="noopener noreferrer">
               {t('action.open')}
             </a>
diff --git a/services/platform/app/features/operator/components/render-kinds/markdown-file-preview.tsx b/services/platform/app/features/operator/components/render-kinds/markdown-file-preview.tsx
index f04227f2d7..9461307a92 100644
--- a/services/platform/app/features/operator/components/render-kinds/markdown-file-preview.tsx
+++ b/services/platform/app/features/operator/components/render-kinds/markdown-file-preview.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import {
   ResponsiveDialog,
   ResponsiveDialogContent,
@@ -78,7 +79,7 @@ export function MarkdownFilePreview({
   return (
     <ResponsiveDialog open={open} onOpenChange={setOpen}>
       <ResponsiveDialogTrigger asChild>
-        <Button variant="secondary" size="sm" icon={FileText}>
+        <Button variant="secondary" icon={FileText}>
           {t('action.openFile', { name: file.name, defaultValue: file.name })}
         </Button>
       </ResponsiveDialogTrigger>
@@ -92,13 +93,13 @@ export function MarkdownFilePreview({
         </ResponsiveDialogDescription>
         <div className="mt-2 max-h-[70vh] overflow-y-auto">
           {state.status === 'loading' && (
-            <div className="flex justify-center py-12">
+            <Row gap={0} align="stretch" justify="center" className="py-12">
               <Spinner
                 label={t('filePreview.loading', {
                   defaultValue: 'Loading preview…',
                 })}
               />
-            </div>
+            </Row>
           )}
           {state.status === 'error' && (
             <div className="text-muted-foreground space-y-3 py-8 text-center text-sm">
@@ -107,7 +108,7 @@ export function MarkdownFilePreview({
                   defaultValue: "Couldn't load the preview.",
                 })}
               </p>
-              <Button asChild variant="secondary" size="sm">
+              <Button asChild variant="secondary">
                 <a href={file.url} target="_blank" rel="noopener noreferrer">
                   {t('filePreview.openInNewTab', {
                     defaultValue: 'Open in a new tab',
diff --git a/services/platform/app/features/operator/components/render-kinds/stream-panel.tsx b/services/platform/app/features/operator/components/render-kinds/stream-panel.tsx
index a65d5c47de..2d983f8fcb 100644
--- a/services/platform/app/features/operator/components/render-kinds/stream-panel.tsx
+++ b/services/platform/app/features/operator/components/render-kinds/stream-panel.tsx
@@ -34,7 +34,7 @@ function FileLinks({ files }: { files: NonNullable<RenderPart['files']> }) {
         isMarkdownFile(file.name) ? (
           <MarkdownFilePreview key={file.name} file={file} />
         ) : (
-          <Button key={file.name} asChild variant="secondary" size="sm">
+          <Button key={file.name} asChild variant="secondary">
             <a href={file.url} target="_blank" rel="noopener noreferrer">
               <FileText className="size-4" />
               {t('action.openFile', {
diff --git a/services/platform/app/features/organization/components/onboarding/onboarding-wizard.tsx b/services/platform/app/features/organization/components/onboarding/onboarding-wizard.tsx
index 07d0750d75..6e92e9aafd 100644
--- a/services/platform/app/features/organization/components/onboarding/onboarding-wizard.tsx
+++ b/services/platform/app/features/organization/components/onboarding/onboarding-wizard.tsx
@@ -2,6 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Link, useNavigate } from '@tanstack/react-router';
 import { useMutation } from 'convex/react';
@@ -145,16 +146,20 @@ export function OnboardingWizard({
   };
 
   return (
-    <div className="flex min-h-screen flex-col">
+    <Stack gap={0} className="min-h-screen">
       {/* Three zones, two distinct affordances: step Back (left) navigates
           within the flow; the close (right) leaves it. A back-chevron vs an
           ✕-close, on opposite sides — so they never read as duplicate "Back"s. */}
-      <header className="grid w-full grid-cols-3 items-center px-4 py-3">
+      <Grid
+        as="header"
+        cols={3}
+        gap={0}
+        className="w-full items-center px-4 py-3"
+      >
         <div className="justify-self-start">
           {stepIndex > 0 && (
             <Button
               variant="ghost"
-              size="sm"
               icon={ChevronLeft}
               onClick={() => setStepIndex((i) => Math.max(0, i - 1))}
               className="-ml-2"
@@ -166,7 +171,7 @@ export function OnboardingWizard({
         <div className="justify-self-center">
           <TaleLogo />
         </div>
-        <div className="flex items-center gap-2 justify-self-end">
+        <Row gap={2} className="justify-self-end">
           {/* No session yet on first-run until the account step completes. */}
           {user ? <UserButton align="end" /> : null}
           {/* add-org mode only: a close affordance to leave setup and return to
@@ -182,8 +187,8 @@ export function OnboardingWizard({
               <X className="size-4" aria-hidden />
             </Link>
           ) : null}
-        </div>
-      </header>
+        </Row>
+      </Grid>
       <main className="mx-auto w-full max-w-md flex-1 px-4 pt-20 pb-12">
         <Wizard
           steps={steps}
@@ -194,10 +199,10 @@ export function OnboardingWizard({
             t('progress', { current, total, label })
           }
         >
-          <div className="flex flex-col gap-8">
+          <Stack gap={8}>
             <WizardProgress segmented ariaLabel={t('stepsAriaLabel')} />
             <StepHero />
-          </div>
+          </Stack>
 
           {isFirstRun && <PreferencesStep />}
           {isFirstRun && <AccountStep />}
@@ -221,7 +226,7 @@ export function OnboardingWizard({
           />
         </Wizard>
       </main>
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/organization/components/onboarding/steps/finish-step.tsx b/services/platform/app/features/organization/components/onboarding/steps/finish-step.tsx
index e55ce3c44d..6fb430b2da 100644
--- a/services/platform/app/features/organization/components/onboarding/steps/finish-step.tsx
+++ b/services/platform/app/features/organization/components/onboarding/steps/finish-step.tsx
@@ -107,7 +107,6 @@ export function FinishStep({ onFinishTo, providerConnected }: FinishStepProps) {
               <Button
                 type="button"
                 variant="secondary"
-                size="sm"
                 disabled={!onFinishTo}
                 onClick={() => onFinishTo?.(target)}
               >
diff --git a/services/platform/app/features/organization/components/onboarding/steps/openrouter-step.tsx b/services/platform/app/features/organization/components/onboarding/steps/openrouter-step.tsx
index 90bb2fd1e8..725e0693a3 100644
--- a/services/platform/app/features/organization/components/onboarding/steps/openrouter-step.tsx
+++ b/services/platform/app/features/organization/components/onboarding/steps/openrouter-step.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { ExternalLink } from 'lucide-react';
 import { useEffect, useState } from 'react';
@@ -146,7 +147,7 @@ export function OpenRouterStep({ organizationId }: OpenRouterStepProps) {
     <WizardStep id="provider" onBeforeNext={connectOpenRouter}>
       {/* Heading + description live in the wizard hero now; the body is just
           the key field and its helper link, grouped tightly together. */}
-      <div className="flex flex-col gap-2">
+      <Stack gap={2}>
         <Input
           id="openrouter-key"
           type="password"
@@ -176,7 +177,7 @@ export function OpenRouterStep({ organizationId }: OpenRouterStepProps) {
             <ExternalLink className="size-3.5" aria-hidden />
           </a>
         </Text>
-      </div>
+      </Stack>
     </WizardStep>
   );
 }
diff --git a/services/platform/app/features/organization/components/onboarding/steps/preferences-step.tsx b/services/platform/app/features/organization/components/onboarding/steps/preferences-step.tsx
index 8d3b8b6cd5..7e334b7169 100644
--- a/services/platform/app/features/organization/components/onboarding/steps/preferences-step.tsx
+++ b/services/platform/app/features/organization/components/onboarding/steps/preferences-step.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { Row } from '@tale/ui/layout';
 import { ThemeSwitcher } from '@tale/ui/theme-switcher';
 import { useRef, type KeyboardEvent } from 'react';
 
@@ -77,10 +78,12 @@ export function PreferencesStep() {
         <legend className="text-fg-base mb-1 text-sm font-medium">
           {t('preferences.languageLabel')}
         </legend>
-        <div
+        <Row
           role="radiogroup"
           aria-label={t('preferences.languageLabel')}
-          className="flex flex-wrap gap-2"
+          gap={2}
+          align="stretch"
+          wrap
           onKeyDown={onLanguageKeyDown}
         >
           {LOCALES.map(({ code, label }, index) => {
@@ -107,7 +110,7 @@ export function PreferencesStep() {
               </button>
             );
           })}
-        </div>
+        </Row>
       </fieldset>
 
       <fieldset className="flex flex-col gap-2">
diff --git a/services/platform/app/features/organization/components/organization-list-panel.tsx b/services/platform/app/features/organization/components/organization-list-panel.tsx
index 51e554cc0a..3a76554c7d 100644
--- a/services/platform/app/features/organization/components/organization-list-panel.tsx
+++ b/services/platform/app/features/organization/components/organization-list-panel.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { useLocation, useNavigate } from '@tanstack/react-router';
 import { Check, Loader2, Plus } from 'lucide-react';
 import { useCallback, useState } from 'react';
@@ -55,7 +56,7 @@ export function OrganizationListPanel({
   const orgs = userOrgs ?? [];
 
   return (
-    <div className="flex flex-col">
+    <Stack gap={0}>
       {!hideHeader && (
         <div className="text-muted-foreground px-3 pt-2 pb-1.5 text-xs font-medium tracking-wide uppercase">
           {tNav('orgSwitcher.label')}
@@ -121,6 +122,6 @@ export function OrganizationListPanel({
           <span>{tSettings('organization.createOrganization')}</span>
         </button>
       </div>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/products/components/product-create-dialog.tsx b/services/platform/app/features/products/components/product-create-dialog.tsx
index 4553f5bbea..21b10a035a 100644
--- a/services/platform/app/features/products/components/product-create-dialog.tsx
+++ b/services/platform/app/features/products/components/product-create-dialog.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { zodResolver } from '@hookform/resolvers/zod';
-import { Grid } from '@tale/ui/layout';
+import { Grid, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useMemo } from 'react';
 import { useForm } from 'react-hook-form';
@@ -50,12 +50,12 @@ interface ProductCreateDialogProps {
 function ReviewRow({ label, value }: { label: string; value?: string }) {
   if (!value) return null;
   return (
-    <div className="flex justify-between gap-4 py-1">
+    <Row align="stretch" justify="between" className="py-1">
       <Text variant="muted" className="shrink-0">
         {label}
       </Text>
       <Text className="min-w-0 truncate text-right">{value}</Text>
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/products/components/product-image-field.tsx b/services/platform/app/features/products/components/product-image-field.tsx
index 6896d70e3a..874aae572b 100644
--- a/services/platform/app/features/products/components/product-image-field.tsx
+++ b/services/platform/app/features/products/components/product-image-field.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { ImagePlus, X } from 'lucide-react';
 import { useRef } from 'react';
@@ -71,7 +72,7 @@ export function ProductImageField({
   };
 
   return (
-    <div className="flex flex-col gap-2">
+    <Stack gap={2}>
       <Input
         id="imageUrl"
         type="url"
@@ -81,7 +82,7 @@ export function ProductImageField({
         placeholder={tProducts('edit.imageUrlPlaceholder')}
         disabled={isDisabled}
       />
-      <div className="flex items-center gap-3">
+      <Row gap={3}>
         {value && (
           <Image
             src={value}
@@ -99,7 +100,6 @@ export function ProductImageField({
         <Button
           type="button"
           variant="secondary"
-          size="sm"
           disabled={isDisabled}
           onClick={() => inputRef.current?.click()}
           className="gap-1.5"
@@ -115,7 +115,6 @@ export function ProductImageField({
           <Button
             type="button"
             variant="ghost"
-            size="sm"
             disabled={disabled}
             onClick={() => onChange('')}
             aria-label={tProducts('edit.removeImage')}
@@ -123,7 +122,7 @@ export function ProductImageField({
             <X className="size-4" />
           </Button>
         )}
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/products/components/product-image.tsx b/services/platform/app/features/products/components/product-image.tsx
index f3215f2df0..55da802a07 100644
--- a/services/platform/app/features/products/components/product-image.tsx
+++ b/services/platform/app/features/products/components/product-image.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Grid } from '@tale/ui/layout';
 import { ComponentPropsWithoutRef } from 'react';
 
 import { Image } from '@/app/components/ui/data-display/image';
@@ -40,7 +41,7 @@ export function ProductImage({
             +{images.length - 1}
           </div>
           <div className="bg-background absolute top-0 left-full z-50 ml-2 hidden min-w-[280px] rounded-md border p-4 shadow-lg group-hover:block">
-            <div className="grid grid-cols-2 gap-4">
+            <Grid cols={2}>
               {images.map((image, imgIndex) => (
                 <div
                   key={imgIndex}
@@ -55,7 +56,7 @@ export function ProductImage({
                   />
                 </div>
               ))}
-            </div>
+            </Grid>
           </div>
         </>
       )}
diff --git a/services/platform/app/features/products/components/products-table.tsx b/services/platform/app/features/products/components/products-table.tsx
index 410d075d91..f8309aec2b 100644
--- a/services/platform/app/features/products/components/products-table.tsx
+++ b/services/platform/app/features/products/components/products-table.tsx
@@ -2,12 +2,11 @@
 
 import { useNavigate } from '@tanstack/react-router';
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { Package, Plus } from 'lucide-react';
+import { Package } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { BulkDeleteBar } from '@/app/components/ui/data-table/data-table-bulk-actions';
-import { useAbility } from '@/app/hooks/use-ability';
 import { useListPage } from '@/app/hooks/use-list-page';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
@@ -39,9 +38,6 @@ export function ProductsTable({
   const { t: tCommon } = useT('common');
   const { t: tTables } = useT('tables');
   const { t: tProducts } = useT('products');
-  const ability = useAbility();
-  const canWrite = ability.can('write', 'knowledgeWrite');
-  // Lifted so the action menu and the empty-state CTA share one dialog.
   const [createOpen, setCreateOpen] = useState(false);
 
   const { data: count } = useApproxProductCount(organizationId);
@@ -157,13 +153,6 @@ export function ProductsTable({
           icon: Package,
           title: tEmpty('products.title'),
           description: tEmpty('products.description'),
-          action: canWrite
-            ? {
-                label: tProducts('addButton'),
-                icon: Plus,
-                onClick: () => setCreateOpen(true),
-              }
-            : undefined,
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/projects/components/project-agents-tab.tsx b/services/platform/app/features/projects/components/project-agents-tab.tsx
index 28c4d49a37..0b64c7fa82 100644
--- a/services/platform/app/features/projects/components/project-agents-tab.tsx
+++ b/services/platform/app/features/projects/components/project-agents-tab.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { Row } from '@tale/ui/layout';
 import { PageSection } from '@tale/ui/page-section';
 import { StickySectionHeader } from '@tale/ui/sticky-section-header';
 import { Text } from '@tale/ui/text';
@@ -281,9 +282,11 @@ export function ProjectAgentsTab({
       </PageSection>
 
       {showLockoutWarning ? (
-        <div
+        <Row
           role="note"
-          className="flex items-start gap-2 rounded-md border border-amber-500/40 bg-amber-500/5 p-3"
+          gap={2}
+          align="start"
+          className="rounded-md border border-amber-500/40 bg-amber-500/5 p-3"
         >
           <AlertTriangle
             className="mt-0.5 size-4 shrink-0 text-amber-600"
@@ -292,7 +295,7 @@ export function ProjectAgentsTab({
           <Text variant="caption" className="text-amber-700">
             {t('agents.lockoutWarning')}
           </Text>
-        </div>
+        </Row>
       ) : null}
     </ContentArea>
   );
diff --git a/services/platform/app/features/projects/components/project-files-tab.tsx b/services/platform/app/features/projects/components/project-files-tab.tsx
index f24d897bf5..bd7a5ab588 100644
--- a/services/platform/app/features/projects/components/project-files-tab.tsx
+++ b/services/platform/app/features/projects/components/project-files-tab.tsx
@@ -273,7 +273,6 @@ export function ProjectFilesTab({
                   {failed && canEdit ? (
                     <Button
                       variant="ghost"
-                      size="sm"
                       onClick={() => void handleRetryIndexing(doc._id)}
                       disabled={isRetrying}
                       isLoading={isRetrying}
@@ -285,7 +284,6 @@ export function ProjectFilesTab({
                   {canEdit ? (
                     <Button
                       variant="ghost"
-                      size="sm"
                       onClick={() => setConfirmDetachId(doc._id)}
                     >
                       {t('files.detachAction')}
diff --git a/services/platform/app/features/projects/components/project-instructions-editor.tsx b/services/platform/app/features/projects/components/project-instructions-editor.tsx
index c0740f4297..c2828aa8d8 100644
--- a/services/platform/app/features/projects/components/project-instructions-editor.tsx
+++ b/services/platform/app/features/projects/components/project-instructions-editor.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { StickySectionHeader } from '@tale/ui/sticky-section-header';
 import { Text } from '@tale/ui/text';
 import { ConvexError } from 'convex/values';
@@ -124,7 +125,7 @@ export function ProjectInstructionsEditor({
                 />
               );
             })()}
-            <div className="flex items-center justify-between">
+            <Row gap={0} justify="between">
               <Text
                 variant="caption"
                 className={cn(
@@ -146,7 +147,7 @@ export function ProjectInstructionsEditor({
                       })
                     : ''}
               </Text>
-            </div>
+            </Row>
           </FormSection>
         </fieldset>
       </form>
diff --git a/services/platform/app/features/projects/components/project-overview.tsx b/services/platform/app/features/projects/components/project-overview.tsx
index 12c3b985a1..c3ef2ff424 100644
--- a/services/platform/app/features/projects/components/project-overview.tsx
+++ b/services/platform/app/features/projects/components/project-overview.tsx
@@ -211,9 +211,7 @@ export function ProjectOverview({
         }
         description={statsLine}
         action={
-          <Button onClick={handleNewChat} size="sm">
-            {t('overview.newChatCta')}
-          </Button>
+          <Button onClick={handleNewChat}>{t('overview.newChatCta')}</Button>
         }
       />
 
diff --git a/services/platform/app/features/projects/components/project-read-only-banner.tsx b/services/platform/app/features/projects/components/project-read-only-banner.tsx
index 4ccdbba7b9..84dea51ade 100644
--- a/services/platform/app/features/projects/components/project-read-only-banner.tsx
+++ b/services/platform/app/features/projects/components/project-read-only-banner.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Eye } from 'lucide-react';
 
@@ -13,7 +13,11 @@ import { useT } from '@/lib/i18n/client';
 export function ProjectReadOnlyBanner() {
   const { t } = useT('projects');
   return (
-    <div className="border-border bg-muted/40 flex items-start gap-3 rounded-md border p-3">
+    <Row
+      gap={3}
+      align="start"
+      className="border-border bg-muted/40 rounded-md border p-3"
+    >
       <Eye
         className="text-muted-foreground mt-0.5 size-4 shrink-0"
         aria-hidden="true"
@@ -24,6 +28,6 @@ export function ProjectReadOnlyBanner() {
           {t('readOnlyBanner.description')}
         </Text>
       </Stack>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/projects/components/project-secrets-tab.tsx b/services/platform/app/features/projects/components/project-secrets-tab.tsx
index 3b3de5a651..599f8d587c 100644
--- a/services/platform/app/features/projects/components/project-secrets-tab.tsx
+++ b/services/platform/app/features/projects/components/project-secrets-tab.tsx
@@ -2,6 +2,7 @@
 
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { StickySectionHeader } from '@tale/ui/sticky-section-header';
 import { Text } from '@tale/ui/text';
 import { KeyRound, ShieldAlert, Trash2 } from 'lucide-react';
@@ -156,7 +157,7 @@ export function ProjectSecretsTab({
         title={t('title')}
         description={t('description')}
         action={
-          <Button size="sm" icon={KeyRound} onClick={() => setDialogOpen(true)}>
+          <Button icon={KeyRound} onClick={() => setDialogOpen(true)}>
             {t('addButton')}
           </Button>
         }
@@ -172,7 +173,7 @@ export function ProjectSecretsTab({
       {secrets.length === 0 ? (
         <Text variant="muted">{t('empty')}</Text>
       ) : (
-        <ul className="flex flex-col gap-2">
+        <Stack as="ul" gap={2}>
           {secrets.map((secret) => (
             <li
               key={secret.name}
@@ -188,7 +189,7 @@ export function ProjectSecretsTab({
                   </Text>
                 )}
               </div>
-              <div className="flex items-center gap-2">
+              <Row gap={2}>
                 <Text as="span" variant="muted" className="font-mono text-xs">
                   ••••••••
                 </Text>
@@ -196,13 +197,13 @@ export function ProjectSecretsTab({
                   size="icon"
                   variant="ghost"
                   icon={Trash2}
-                  aria-label={tCommon('actions.delete')}
+                  title={tCommon('actions.delete')}
                   onClick={() => void handleDelete(secret.name)}
                 />
-              </div>
+              </Row>
             </li>
           ))}
-        </ul>
+        </Stack>
       )}
 
       <FormDialog
diff --git a/services/platform/app/features/projects/components/project-slug-list-editor.tsx b/services/platform/app/features/projects/components/project-slug-list-editor.tsx
index 24106cc2c9..c6ba44d4ed 100644
--- a/services/platform/app/features/projects/components/project-slug-list-editor.tsx
+++ b/services/platform/app/features/projects/components/project-slug-list-editor.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Plus } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -218,8 +218,10 @@ export function ProjectSlugListEditor({
             // they're still discoverable in the searchable picker when
             // adding, and we surface them as a `title` tooltip here for
             // power users who want to recall the context on hover.
-            <div
-              className="flex min-w-0 items-baseline gap-2"
+            <Row
+              gap={2}
+              align="baseline"
+              className="min-w-0"
               title={item.description}
             >
               <Text as="span" variant="body" truncate className="min-w-0">
@@ -234,7 +236,7 @@ export function ProjectSlugListEditor({
                   ({t('editor.slugFallback')})
                 </Text>
               ) : null}
-            </div>
+            </Row>
           )}
         />
       ) : null}
@@ -259,11 +261,7 @@ export function ProjectSlugListEditor({
           />
         ) : (
           <div>
-            <Button
-              variant="ghost"
-              size="sm"
-              onClick={() => setPickerOpen(true)}
-            >
+            <Button variant="ghost" onClick={() => setPickerOpen(true)}>
               <Plus className="size-4" aria-hidden="true" />
               {addLabel}
             </Button>
diff --git a/services/platform/app/features/projects/components/project-threads-tab.tsx b/services/platform/app/features/projects/components/project-threads-tab.tsx
index 781e378fe6..f8801e7c60 100644
--- a/services/platform/app/features/projects/components/project-threads-tab.tsx
+++ b/services/platform/app/features/projects/components/project-threads-tab.tsx
@@ -81,9 +81,7 @@ export function ProjectThreadsTab({
         title={t('threads.yourChats')}
         description={t('threads.shareToggleDisclosure')}
         action={
-          <Button onClick={handleNewChat} size="sm">
-            {t('overview.newChatCta')}
-          </Button>
+          <Button onClick={handleNewChat}>{t('overview.newChatCta')}</Button>
         }
       />
 
diff --git a/services/platform/app/features/projects/components/projects-table.tsx b/services/platform/app/features/projects/components/projects-table.tsx
index ce6a17cde6..83376a5aa0 100644
--- a/services/platform/app/features/projects/components/projects-table.tsx
+++ b/services/platform/app/features/projects/components/projects-table.tsx
@@ -231,11 +231,6 @@ export function ProjectsTable({ organizationId }: ProjectsTableProps) {
           icon: Folder,
           title: t('list.emptyTitle'),
           description: t('list.emptyDescription'),
-          action: {
-            label: t('list.createButton'),
-            icon: Plus,
-            onClick: () => setCreateOpen(true),
-          },
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/prompts/components/category-filter-popover.tsx b/services/platform/app/features/prompts/components/category-filter-popover.tsx
index db0ea0f148..e6fa0934d4 100644
--- a/services/platform/app/features/prompts/components/category-filter-popover.tsx
+++ b/services/platform/app/features/prompts/components/category-filter-popover.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { Filter } from 'lucide-react';
 import { useState } from 'react';
@@ -93,7 +94,7 @@ export function CategoryFilterPopover({
       <p className="text-muted-foreground px-3 py-1.5 text-[11px] font-medium">
         {t('categoryFilter.title')}
       </p>
-      <div className="flex flex-col">
+      <Stack gap={0}>
         {categories.map((category) => {
           const checked = selectedIds.includes(category._id);
           return (
@@ -144,7 +145,7 @@ export function CategoryFilterPopover({
             </label>
           );
         })}
-      </div>
+      </Stack>
     </Popover>
   );
 }
diff --git a/services/platform/app/features/prompts/components/category-picker-popover.tsx b/services/platform/app/features/prompts/components/category-picker-popover.tsx
index f1843886f0..755d2850d6 100644
--- a/services/platform/app/features/prompts/components/category-picker-popover.tsx
+++ b/services/platform/app/features/prompts/components/category-picker-popover.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import {
   Check,
@@ -278,7 +279,7 @@ export function CategoryPickerPopover({
           </button>
         }
       >
-        <div role="listbox" className="flex flex-col">
+        <Stack role="listbox" gap={0}>
           {/*
            * No explicit "None" option. A prompt can still end up
            * uncategorized via category deletion or a scope change that
@@ -312,9 +313,8 @@ export function CategoryPickerPopover({
                   )}
                 >
                   {isRenaming ? (
-                    <div className="flex flex-1 items-center gap-1 px-2 py-1">
+                    <Row gap={1} className="flex-1 px-2 py-1">
                       <Input
-                        size="sm"
                         value={renameValue}
                         autoFocus
                         onChange={(e) => setRenameValue(e.target.value)}
@@ -344,7 +344,7 @@ export function CategoryPickerPopover({
                       >
                         <X className="size-4" />
                       </button>
-                    </div>
+                    </Row>
                   ) : (
                     <>
                       <button
@@ -386,10 +386,9 @@ export function CategoryPickerPopover({
             <>
               <div className="border-border my-1 border-t" />
               {creating ? (
-                <div className="flex items-center gap-2 px-2 py-1.5">
+                <Row gap={2} className="px-2 py-1.5">
                   <Input
                     ref={createInputRef}
-                    size="sm"
                     value={createValue}
                     onChange={(e) => setCreateValue(e.target.value)}
                     placeholder={t('addCategory.inputPlaceholder')}
@@ -406,13 +405,12 @@ export function CategoryPickerPopover({
                   />
                   <Button
                     type="button"
-                    size="sm"
                     onClick={() => void handleCreate()}
                     disabled={!createValue.trim() || createCategory.isPending}
                   >
                     {t('categories.create')}
                   </Button>
-                </div>
+                </Row>
               ) : (
                 <button
                   type="button"
@@ -425,7 +423,7 @@ export function CategoryPickerPopover({
               )}
             </>
           )}
-        </div>
+        </Stack>
       </Popover>
 
       <ConfirmDialog
diff --git a/services/platform/app/features/prompts/components/prompt-compare-view.tsx b/services/platform/app/features/prompts/components/prompt-compare-view.tsx
index af6c77a991..cf62650ba9 100644
--- a/services/platform/app/features/prompts/components/prompt-compare-view.tsx
+++ b/services/platform/app/features/prompts/components/prompt-compare-view.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { diffLines } from 'diff';
 import { ArrowLeft, RotateCcw } from 'lucide-react';
@@ -166,7 +167,7 @@ export function PromptCompareView({
   const hasChanges = hasContentChanges || hasMetadataChanges;
 
   return (
-    <div className="flex flex-col gap-3">
+    <Stack gap={3}>
       <Text variant="muted" className="text-xs">
         {t('history.compareDescription', {
           date: formatDate(new Date(snapshot.publishedAt), 'long'),
@@ -270,7 +271,7 @@ export function PromptCompareView({
         </div>
       ) : null}
 
-      <div className="flex items-center justify-between">
+      <Row gap={0} justify="between">
         <Button type="button" variant="ghost" onClick={onBack}>
           <ArrowLeft className="mr-1 size-4" />
           {t('history.backToList')}
@@ -284,7 +285,7 @@ export function PromptCompareView({
           <RotateCcw className="mr-1 size-3" />
           {t('history.restore')}
         </Button>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/prompts/components/prompt-form-dialog.tsx b/services/platform/app/features/prompts/components/prompt-form-dialog.tsx
index 8cd165079a..8c91f8d18b 100644
--- a/services/platform/app/features/prompts/components/prompt-form-dialog.tsx
+++ b/services/platform/app/features/prompts/components/prompt-form-dialog.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Tabs } from '@tale/ui/tabs';
 import { Text } from '@tale/ui/text';
 import { AlertTriangle } from 'lucide-react';
@@ -322,9 +322,11 @@ function PromptFormDialogContent({
         </HStack>
       )}
       {hasNewerVersion && (
-        <div
+        <Row
           role="alert"
-          className="border-warning bg-warning/10 text-warning-foreground flex items-start gap-2 rounded-md border p-3 text-sm"
+          gap={2}
+          align="start"
+          className="border-warning bg-warning/10 text-warning-foreground rounded-md border p-3 text-sm"
         >
           <AlertTriangle
             className="mt-0.5 size-4 shrink-0"
@@ -345,16 +347,15 @@ function PromptFormDialogContent({
           </div>
           <Button
             type="button"
-            size="sm"
             variant={isDirty ? 'destructive' : 'secondary'}
             onClick={handleLoadLatest}
             disabled={!live}
           >
             {t('form.loadLatest')}
           </Button>
-        </div>
+        </Row>
       )}
-      <div className="flex flex-col gap-1">
+      <Stack gap={1}>
         <Input
           label={t('form.titleLabel')}
           value={title}
@@ -367,8 +368,8 @@ function PromptFormDialogContent({
             {t('form.titleAutoGenHint')}
           </Text>
         )}
-      </div>
-      <div className="flex flex-col gap-1">
+      </Stack>
+      <Stack gap={1}>
         <Textarea
           id={contentId}
           value={content}
@@ -405,7 +406,7 @@ function PromptFormDialogContent({
             {t('form.bytesOverLimitAlert')}
           </Text>
         )}
-      </div>
+      </Stack>
       <div role="group" aria-label={t('form.scopeLabel')}>
         <Tabs
           items={scopeTabItems}
@@ -433,7 +434,7 @@ function PromptFormDialogContent({
         </Text>
       )}
       {!(scope === 'team' && teamOptions.length === 0) && (
-        <div className="flex flex-col gap-2">
+        <Stack gap={2}>
           <label id={categoryLabelId} className="text-sm font-medium">
             {t('form.categoryLabel')}
           </label>
@@ -448,7 +449,7 @@ function PromptFormDialogContent({
             onSelect={setCategoryId}
             ariaLabelledBy={categoryLabelId}
           />
-        </div>
+        </Stack>
       )}
       <TagChipInput
         value={tags}
diff --git a/services/platform/app/features/prompts/components/prompt-history-dialog.tsx b/services/platform/app/features/prompts/components/prompt-history-dialog.tsx
index a827a9d594..fcdc178a6f 100644
--- a/services/platform/app/features/prompts/components/prompt-history-dialog.tsx
+++ b/services/platform/app/features/prompts/components/prompt-history-dialog.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { RotateCcw } from 'lucide-react';
 import {
@@ -253,11 +253,7 @@ export function PromptHistoryDialog({
             onBack={() => setComparingVersion(null)}
           />
         ) : historyQuery.isLoading ? (
-          <div
-            className="flex flex-col gap-2 py-2"
-            role="status"
-            aria-busy="true"
-          >
+          <Stack gap={2} className="py-2" role="status" aria-busy="true">
             {[0, 1, 2].map((i) => (
               <div
                 key={i}
@@ -266,7 +262,7 @@ export function PromptHistoryDialog({
               />
             ))}
             <span className="sr-only">{t('history.loading')}</span>
-          </div>
+          </Stack>
         ) : historyQuery.isError ? (
           <QueryErrorBlock
             message={t('history.loadFailed')}
@@ -346,7 +342,6 @@ export function PromptHistoryDialog({
                           <Button
                             type="button"
                             variant="ghost"
-                            size="sm"
                             onClick={() => setComparingVersion(entry)}
                             aria-label={t('history.compareVersionAria', {
                               version: String(entry.version),
@@ -357,7 +352,6 @@ export function PromptHistoryDialog({
                           <Button
                             type="button"
                             variant="ghost"
-                            size="sm"
                             onClick={() => startRestore(entry)}
                             aria-label={t('history.restoreVersionAria', {
                               version: String(entry.version),
diff --git a/services/platform/app/features/prompts/components/prompt-library-dialog.tsx b/services/platform/app/features/prompts/components/prompt-library-dialog.tsx
index 071806f484..f39c59e120 100644
--- a/services/platform/app/features/prompts/components/prompt-library-dialog.tsx
+++ b/services/platform/app/features/prompts/components/prompt-library-dialog.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Tabs } from '@tale/ui/tabs';
 import { Text } from '@tale/ui/text';
 import { BookOpen, History, Plus, Search } from 'lucide-react';
@@ -321,7 +321,7 @@ function PromptLibraryDialogContent({
         description={t('library.description')}
         className="w-[95vw] max-w-[680px]"
       >
-        <div className="flex flex-col gap-4">
+        <Stack>
           <Tabs
             items={tabItems}
             value={activeTab}
@@ -387,7 +387,7 @@ function PromptLibraryDialogContent({
             aria-busy={isLoading || undefined}
           >
             {isLoading && prompts.length === 0 ? (
-              <div className="flex flex-col gap-2 py-2">
+              <Stack gap={2} className="py-2">
                 {[0, 1, 2].map((i) => (
                   <div
                     key={i}
@@ -396,13 +396,17 @@ function PromptLibraryDialogContent({
                   />
                 ))}
                 <span className="sr-only">{t('library.loading')}</span>
-              </div>
+              </Stack>
             ) : visiblePrompts.length === 0 ? (
-              <div className="flex h-[300px] flex-col items-center justify-center gap-4">
-                <div className="bg-muted flex size-12 items-center justify-center rounded-full">
+              <Stack align="center" justify="center" className="h-[300px]">
+                <Row
+                  gap={0}
+                  justify="center"
+                  className="bg-muted size-12 rounded-full"
+                >
                   <BookOpen className="text-muted-foreground size-6" />
-                </div>
-                <div className="flex flex-col items-center gap-2 text-center">
+                </Row>
+                <Stack gap={2} align="center" className="text-center">
                   <Text as="h3" variant="label" className="font-medium">
                     {filtersActive
                       ? t('emptyState.filteredTitle')
@@ -421,7 +425,6 @@ function PromptLibraryDialogContent({
                         <Button
                           type="button"
                           variant="secondary"
-                          size="sm"
                           onClick={loadMore}
                           disabled={isLoadingMore}
                         >
@@ -433,17 +436,16 @@ function PromptLibraryDialogContent({
                       <Button
                         type="button"
                         variant="secondary"
-                        size="sm"
                         onClick={clearFilters}
                       >
                         {t('emptyState.clearFilters')}
                       </Button>
                     </HStack>
                   )}
-                </div>
-              </div>
+                </Stack>
+              </Stack>
             ) : (
-              <div className="flex flex-col" role="list">
+              <Stack gap={0} role="list">
                 {visiblePrompts.map((prompt, index) => {
                   const canModify = canModifyPrompt(prompt);
                   return (
@@ -468,10 +470,14 @@ function PromptLibraryDialogContent({
                   );
                 })}
                 {canLoadMore && (
-                  <div className="flex justify-center py-3">
+                  <Row
+                    gap={0}
+                    align="stretch"
+                    justify="center"
+                    className="py-3"
+                  >
                     <Button
                       variant="ghost"
-                      size="sm"
                       onClick={loadMore}
                       disabled={isLoadingMore}
                     >
@@ -479,12 +485,12 @@ function PromptLibraryDialogContent({
                         ? t('library.loadingMore')
                         : t('library.loadMore')}
                     </Button>
-                  </div>
+                  </Row>
                 )}
-              </div>
+              </Stack>
             )}
           </div>
-        </div>
+        </Stack>
       </Dialog>
 
       <PromptFormDialog
@@ -506,7 +512,6 @@ function PromptLibraryDialogContent({
             <Button
               type="button"
               variant="ghost"
-              size="sm"
               onClick={() => setHistoryPrompt(editingPrompt)}
             >
               <History className="mr-1 size-3" />
diff --git a/services/platform/app/features/prompts/components/query-error-block.tsx b/services/platform/app/features/prompts/components/query-error-block.tsx
index 2c24d081ec..25a909148b 100644
--- a/services/platform/app/features/prompts/components/query-error-block.tsx
+++ b/services/platform/app/features/prompts/components/query-error-block.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 
 import { useT } from '@/lib/i18n/client';
@@ -20,16 +21,13 @@ interface QueryErrorBlockProps {
 export function QueryErrorBlock({ message, onRetry }: QueryErrorBlockProps) {
   const { t } = useT('common');
   return (
-    <div
-      role="alert"
-      className="flex flex-col items-center gap-3 py-6 text-center"
-    >
+    <Stack role="alert" gap={3} align="center" className="py-6 text-center">
       <Text variant="muted" className="text-sm">
         {message}
       </Text>
-      <Button type="button" variant="secondary" size="sm" onClick={onRetry}>
+      <Button type="button" variant="secondary" onClick={onRetry}>
         {t('retry')}
       </Button>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/prompts/components/save-prompt-dialog.tsx b/services/platform/app/features/prompts/components/save-prompt-dialog.tsx
index 982def23db..5d6eabd37c 100644
--- a/services/platform/app/features/prompts/components/save-prompt-dialog.tsx
+++ b/services/platform/app/features/prompts/components/save-prompt-dialog.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useCallback, useId, useMemo, useState } from 'react';
 
@@ -182,7 +183,7 @@ function SavePromptDialogContent({
       confirmDiscardOnDirty={hasUserEdits}
       submitText={t('form.save')}
     >
-      <div className="flex flex-col gap-1">
+      <Stack gap={1}>
         <Textarea
           value={content}
           onChange={(e) => setContent(e.target.value)}
@@ -217,7 +218,7 @@ function SavePromptDialogContent({
             {t('form.bytesOverLimitAlert')}
           </Text>
         )}
-      </div>
+      </Stack>
 
       <RadioGroup
         label={t('saveAs.saveTo')}
@@ -239,7 +240,7 @@ function SavePromptDialogContent({
         />
       )}
 
-      <div className="flex flex-col gap-2">
+      <Stack gap={2}>
         <label
           id={categoryLabelId}
           className="text-muted-foreground text-sm font-medium"
@@ -257,7 +258,7 @@ function SavePromptDialogContent({
           onSelect={setCategoryId}
           ariaLabelledBy={categoryLabelId}
         />
-      </div>
+      </Stack>
     </FormDialog>
   );
 }
diff --git a/services/platform/app/features/prompts/components/tag-filter-popover.tsx b/services/platform/app/features/prompts/components/tag-filter-popover.tsx
index 51a8673585..2b75e227cd 100644
--- a/services/platform/app/features/prompts/components/tag-filter-popover.tsx
+++ b/services/platform/app/features/prompts/components/tag-filter-popover.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { Tag } from 'lucide-react';
 import { useState } from 'react';
@@ -66,7 +67,7 @@ export function TagFilterPopover({
       <p className="text-muted-foreground px-3 py-1.5 text-[11px] font-medium">
         {t('tagFilter.title')}
       </p>
-      <div className="flex flex-col">
+      <Stack gap={0}>
         {tags.map((tag) => (
           <label
             key={tag}
@@ -88,7 +89,7 @@ export function TagFilterPopover({
             </span>
           </label>
         ))}
-      </div>
+      </Stack>
     </Popover>
   );
 }
diff --git a/services/platform/app/features/settings/account/components/account-form.tsx b/services/platform/app/features/settings/account/components/account-form.tsx
index 23937f55ac..628b297b56 100644
--- a/services/platform/app/features/settings/account/components/account-form.tsx
+++ b/services/platform/app/features/settings/account/components/account-form.tsx
@@ -2,6 +2,7 @@
 
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize, useSkeleton } from '@tale/ui/skeleton-context';
 import { useCallback, useMemo, useState } from 'react';
@@ -206,9 +207,12 @@ function EmailField({ email }: { email: string }) {
   const loading = useSkeleton();
 
   return (
-    <div className="bg-muted/40 ring-border text-muted-foreground flex w-full items-center rounded-lg border px-3 py-2.25 text-sm">
+    <Row
+      gap={0}
+      className="bg-muted/40 ring-border text-muted-foreground w-full rounded-lg border px-3 py-2.25 text-sm"
+    >
       {loading ? <SkeletonText /> : email}
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/settings/account/components/passkey-section.tsx b/services/platform/app/features/settings/account/components/passkey-section.tsx
index 95da0b6c5d..686116a951 100644
--- a/services/platform/app/features/settings/account/components/passkey-section.tsx
+++ b/services/platform/app/features/settings/account/components/passkey-section.tsx
@@ -107,7 +107,7 @@ export function PasskeySection() {
                   {pk.name?.trim() || t('passkeys.unnamed')}
                 </Text>
               </VStack>
-              <Button variant="ghost" size="sm" onClick={() => revoke(pk.id)}>
+              <Button variant="ghost" onClick={() => revoke(pk.id)}>
                 {t('passkeys.revokeButton')}
               </Button>
             </HStack>
diff --git a/services/platform/app/features/settings/account/components/saved-backup-codes-dialog.tsx b/services/platform/app/features/settings/account/components/saved-backup-codes-dialog.tsx
index b65c37450e..bae11b5694 100644
--- a/services/platform/app/features/settings/account/components/saved-backup-codes-dialog.tsx
+++ b/services/platform/app/features/settings/account/components/saved-backup-codes-dialog.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Grid, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
@@ -45,11 +45,16 @@ export function SavedBackupCodesDialog({
         <Text variant="muted" className="text-sm">
           {t('backupCodes.description')}
         </Text>
-        <ul className="bg-muted grid grid-cols-2 gap-2 rounded-md border p-3 font-mono text-sm">
+        <Grid
+          as="ul"
+          cols={2}
+          gap={2}
+          className="bg-muted rounded-md border p-3 font-mono text-sm"
+        >
           {backupCodes.map((code) => (
             <li key={code}>{code}</li>
           ))}
-        </ul>
+        </Grid>
       </Stack>
     </ConfirmDialog>
   );
diff --git a/services/platform/app/features/settings/api-keys/components/api-key-create-dialog.tsx b/services/platform/app/features/settings/api-keys/components/api-key-create-dialog.tsx
index f4b1386f5c..08d98d34ae 100644
--- a/services/platform/app/features/settings/api-keys/components/api-key-create-dialog.tsx
+++ b/services/platform/app/features/settings/api-keys/components/api-key-create-dialog.tsx
@@ -174,7 +174,6 @@ export function ApiKeyCreateDialog({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 onClick={handleCopyKey}
                 className="absolute top-1/2 right-2 -translate-y-1/2"
                 aria-label={tCommon('actions.copy')}
diff --git a/services/platform/app/features/settings/api-keys/components/api-keys-table.tsx b/services/platform/app/features/settings/api-keys/components/api-keys-table.tsx
index 241c766dfb..8c2ec998c8 100644
--- a/services/platform/app/features/settings/api-keys/components/api-keys-table.tsx
+++ b/services/platform/app/features/settings/api-keys/components/api-keys-table.tsx
@@ -1,9 +1,9 @@
 'use client';
 
 import { buttonVariants } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import type { RowSelectionState } from '@tanstack/react-table';
-import { BookOpen, Key, Plus } from 'lucide-react';
+import { BookOpen, Key } from 'lucide-react';
 import { useCallback, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
@@ -25,7 +25,7 @@ function ApiDocsLink() {
   const { t: tSettings } = useT('settings');
 
   return (
-    <div className="flex justify-center py-4">
+    <Row gap={0} align="stretch" justify="center" className="py-4">
       <a
         href="/docs"
         target="_blank"
@@ -35,7 +35,7 @@ function ApiDocsLink() {
         <BookOpen className="mr-2 size-4" />
         {tSettings('apiDocs.openDocs')}
       </a>
-    </div>
+    </Row>
   );
 }
 
@@ -98,11 +98,6 @@ export function ApiKeysTable({ apiKeys, organizationId }: ApiKeysTableProps) {
               <ApiDocsLink />
             </>
           ),
-          action: {
-            label: tSettings('apiKeys.createKey'),
-            icon: Plus,
-            onClick: () => setCreateOpen(true),
-          },
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/settings/audit-logs/components/activity-log-view.tsx b/services/platform/app/features/settings/audit-logs/components/activity-log-view.tsx
index 42f49a811b..899fb7db3a 100644
--- a/services/platform/app/features/settings/audit-logs/components/activity-log-view.tsx
+++ b/services/platform/app/features/settings/audit-logs/components/activity-log-view.tsx
@@ -1,8 +1,9 @@
 'use client';
 
-import { HStack, Stack } from '@tale/ui/layout';
+import { Grid, HStack, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
-import { Skeletonize, useSkeleton } from '@tale/ui/skeleton-context';
+import { Skeletonize } from '@tale/ui/skeleton-context';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
 import { Text } from '@tale/ui/text';
 import type { FunctionReturnType } from 'convex/server';
 import { useCallback, useMemo, useState } from 'react';
@@ -31,27 +32,6 @@ interface ActivityLogViewInnerProps {
   userEmailMap?: Map<string, string>;
 }
 
-function StatCell({ label, value }: { label: string; value: string }) {
-  const loading = useSkeleton();
-
-  return (
-    <div className="flex flex-1 flex-col gap-1 p-5">
-      <Text className="text-muted-foreground text-sm">{label}</Text>
-      {/* Mask the async value to its natural line box so the card height is
-          identical loading vs loaded and the number doesn't flash from 0. */}
-      <Text className="text-foreground font-mono text-2xl font-semibold">
-        {loading ? (
-          <SkeletonBox>
-            <span className="my-0.5 inline-block h-7 w-16" />
-          </SkeletonBox>
-        ) : (
-          value
-        )}
-      </Text>
-    </div>
-  );
-}
-
 function BreakdownRow({
   label,
   count,
@@ -161,32 +141,31 @@ function ActivityLogViewInner({
             options={periodOptions}
             value={String(periodDays)}
             onValueChange={onPeriod}
-            size="sm"
             aria-label={t('logs.activity.period.label')}
           />
         </div>
       </HStack>
 
-      <div className="border-border divide-border grid grid-cols-2 divide-y rounded-lg border md:grid-cols-4 md:divide-x md:divide-y-0">
-        <StatCell
+      <StatCardGrid>
+        <StatCard
           label={t('logs.activity.cards.total')}
           value={formatNumber(summary?.totalActions ?? 0)}
         />
-        <StatCell
+        <StatCard
           label={t('logs.activity.cards.success')}
           value={formatNumber(summary?.successCount ?? 0)}
         />
-        <StatCell
+        <StatCard
           label={t('logs.activity.cards.failure')}
           value={formatNumber(summary?.failureCount ?? 0)}
         />
-        <StatCell
+        <StatCard
           label={t('logs.activity.cards.denied')}
           value={formatNumber(summary?.deniedCount ?? 0)}
         />
-      </div>
+      </StatCardGrid>
 
-      <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+      <Grid lg={2}>
         <BreakdownPanel
           title={t('logs.activity.byCategory.title')}
           empty={categories.length === 0}
@@ -226,7 +205,7 @@ function ActivityLogViewInner({
             ))}
           </Stack>
         </BreakdownPanel>
-      </div>
+      </Grid>
     </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/audit-logs/components/audit-log-table.tsx b/services/platform/app/features/settings/audit-logs/components/audit-log-table.tsx
index 24e8b02381..47bcff5511 100644
--- a/services/platform/app/features/settings/audit-logs/components/audit-log-table.tsx
+++ b/services/platform/app/features/settings/audit-logs/components/audit-log-table.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Grid, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { UsePaginatedQueryResult } from 'convex/react';
 import { useCallback, useState } from 'react';
@@ -300,7 +300,7 @@ function DetailRow({
   isError?: boolean;
 }) {
   return (
-    <div className="grid grid-cols-1 gap-1 sm:grid-cols-3 sm:gap-4">
+    <Grid sm={3} gap={1} className="sm:gap-4">
       <Text as="span" variant="muted" className="font-medium">
         {label}
       </Text>
@@ -311,7 +311,7 @@ function DetailRow({
       >
         {value}
       </Text>
-    </div>
+    </Grid>
   );
 }
 
diff --git a/services/platform/app/features/settings/audit-logs/components/audit-logs-page.tsx b/services/platform/app/features/settings/audit-logs/components/audit-logs-page.tsx
index 1033baea80..1c1a159ded 100644
--- a/services/platform/app/features/settings/audit-logs/components/audit-logs-page.tsx
+++ b/services/platform/app/features/settings/audit-logs/components/audit-logs-page.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Tabs } from '@tale/ui/tabs';
 import { Download } from 'lucide-react';
 import { useCallback, useMemo } from 'react';
@@ -147,7 +148,7 @@ export function AuditLogsPage({
           defaultValue="audit"
           className="flex min-h-0 flex-1 flex-col"
           actions={
-            <div className="flex items-center gap-2">
+            <Row gap={2}>
               <DataTableFilters
                 filters={auditFilterConfigs}
                 onClearAll={handleClearFilters}
@@ -156,7 +157,6 @@ export function AuditLogsPage({
                 <>
                   <Button
                     variant="secondary"
-                    size="sm"
                     icon={Download}
                     onClick={() => handleExport('csv')}
                     disabled={exportAction.isPending}
@@ -168,7 +168,6 @@ export function AuditLogsPage({
                   </Button>
                   <Button
                     variant="secondary"
-                    size="sm"
                     icon={Download}
                     onClick={() => handleExport('json')}
                     disabled={exportAction.isPending}
@@ -180,7 +179,7 @@ export function AuditLogsPage({
                   </Button>
                 </>
               )}
-            </div>
+            </Row>
           }
           items={[
             {
diff --git a/services/platform/app/features/settings/audit-logs/components/block-counters-table.tsx b/services/platform/app/features/settings/audit-logs/components/block-counters-table.tsx
index ea9f01235d..0e48b817d0 100644
--- a/services/platform/app/features/settings/audit-logs/components/block-counters-table.tsx
+++ b/services/platform/app/features/settings/audit-logs/components/block-counters-table.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { useMemo } from 'react';
@@ -114,11 +115,11 @@ export function BlockCountersTable({
       }}
       footer={
         rows.length > 0 ? (
-          <div className="border-border flex h-10 items-center border-t px-4">
+          <Row gap={0} className="border-border h-10 border-t px-4">
             <Text variant="muted" className="text-xs">
               {t('logs.blockCounters.footerCount', { count: rows.length })}
             </Text>
-          </div>
+          </Row>
         ) : undefined
       }
     />
diff --git a/services/platform/app/features/settings/branding/components/branding-form.tsx b/services/platform/app/features/settings/branding/components/branding-form.tsx
index 33580f2749..10c54c7472 100644
--- a/services/platform/app/features/settings/branding/components/branding-form.tsx
+++ b/services/platform/app/features/settings/branding/components/branding-form.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { useSkeleton } from '@tale/ui/skeleton-context';
 import {
@@ -222,7 +222,7 @@ export function BrandingForm({
       onSubmit={handleSubmit((values) => save(values))}
       className="w-full max-w-sm shrink-0 space-y-0 self-start"
     >
-      <div className="flex h-full flex-col justify-between">
+      <Stack gap={0} justify="between" className="h-full">
         <FormSection>
           <Input
             id="branding-app-name"
@@ -350,14 +350,13 @@ export function BrandingForm({
             <Button
               type="button"
               variant="secondary"
-              size="sm"
               onClick={() => void handleClearBranding()}
             >
               {tCommon('actions.clearAll')}
             </Button>
           </HStack>
         )}
-      </div>
+      </Stack>
     </Form>
   );
 }
diff --git a/services/platform/app/features/settings/branding/components/branding-preview.tsx b/services/platform/app/features/settings/branding/components/branding-preview.tsx
index 053d484302..9d53d1f586 100644
--- a/services/platform/app/features/settings/branding/components/branding-preview.tsx
+++ b/services/platform/app/features/settings/branding/components/branding-preview.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import {
   MessageCircle,
   Inbox,
@@ -37,15 +38,16 @@ function BrowserChrome({
   faviconUrl?: string | null;
 }) {
   return (
-    <div
-      className="border-b-border flex h-9 items-center border-b px-6"
+    <Row
+      gap={0}
+      className="border-b-border h-9 border-b px-6"
       data-testid="browser-chrome"
     >
-      <div className="flex gap-1">
+      <Row gap={1} align="stretch">
         <div className="bg-border size-2 rounded-full" />
         <div className="bg-border size-2 rounded-full" />
         <div className="bg-border size-2 rounded-full" />
-      </div>
+      </Row>
       <div className="flex flex-1 items-center justify-center gap-1.5">
         {faviconUrl ? (
           <Image
@@ -67,7 +69,7 @@ function BrowserChrome({
         )}
       </div>
       <div className="bg-border size-2.5 rounded-sm" />
-    </div>
+    </Row>
   );
 }
 
@@ -80,8 +82,11 @@ export const BrandingPreview = memo(function BrandingPreview({
     data;
 
   return (
-    <div
-      className="bg-muted -mt-[106px] -mr-4 -mb-6 flex min-h-[calc(100vh-80px)] flex-1 items-start justify-center overflow-hidden p-6 pt-[130px]"
+    <Row
+      gap={0}
+      align="start"
+      justify="center"
+      className="bg-muted -mt-[106px] -mr-4 -mb-6 min-h-[calc(100vh-80px)] flex-1 overflow-hidden p-6 pt-[130px]"
       role="img"
       aria-label={t('branding.preview')}
     >
@@ -89,11 +94,15 @@ export const BrandingPreview = memo(function BrandingPreview({
         <BrowserChrome appName={appName} faviconUrl={faviconUrl} />
 
         {/* App layout preview */}
-        <div className="flex h-[400px]">
+        <Row gap={0} align="stretch" className="h-[400px]">
           {/* Sidebar */}
-          <div className="bg-muted/50 border-border flex w-12 shrink-0 flex-col items-center border-r py-3">
+          <Stack
+            gap={0}
+            align="center"
+            className="bg-muted/50 border-border w-12 shrink-0 border-r py-3"
+          >
             {/* Logo */}
-            <div className="flex size-8 items-center justify-center pb-4">
+            <Row gap={0} justify="center" className="size-8 pb-4">
               {logoUrl ? (
                 <Image
                   src={logoUrl}
@@ -117,14 +126,16 @@ export const BrandingPreview = memo(function BrandingPreview({
                   }
                 />
               )}
-            </div>
+            </Row>
 
             {/* Nav icons */}
-            <div className="flex flex-col gap-2 pt-4">
+            <Stack gap={2} className="pt-4">
               {NAV_ICONS.map((Icon, i) => (
-                <div
+                <Row
                   key={i}
-                  className="relative flex size-8 items-center justify-center rounded"
+                  gap={0}
+                  justify="center"
+                  className="relative size-8 rounded"
                 >
                   {i === 0 && accentColor && (
                     <div
@@ -144,24 +155,24 @@ export const BrandingPreview = memo(function BrandingPreview({
                         : undefined
                     }
                   />
-                </div>
+                </Row>
               ))}
-            </div>
+            </Stack>
 
             <div className="mt-auto">
               <User className="text-muted-foreground size-4" />
             </div>
-          </div>
+          </Stack>
 
           {/* Main content */}
-          <div className="flex flex-1 flex-col">
+          <Stack gap={0} className="flex-1">
             {/* Header */}
-            <div className="border-border flex h-10 items-center border-b px-4">
+            <Row gap={0} className="border-border h-10 border-b px-4">
               <div className="bg-muted h-2 w-16 rounded-sm" />
-            </div>
+            </Row>
 
             {/* Tab nav */}
-            <div className="border-border flex h-8 items-center gap-3 border-b px-4">
+            <Row gap={3} className="border-border h-8 border-b px-4">
               <span
                 className="text-foreground mt-auto border-b-2 pb-1.5 text-[10px] font-medium"
                 style={{
@@ -176,14 +187,14 @@ export const BrandingPreview = memo(function BrandingPreview({
               <span className="text-muted-foreground text-[10px]">
                 {tConversations('status.spam')}
               </span>
-            </div>
+            </Row>
 
             {/* Content placeholder */}
-            <div className="flex flex-1 flex-col gap-3 p-4">
+            <Stack gap={3} className="flex-1 p-4">
               {[...Array(4)].map((_, i) => (
-                <div key={i} className="flex items-center gap-3">
+                <Row key={i} gap={3}>
                   <div className="bg-muted size-6 rounded-full" />
-                  <div className="flex flex-1 flex-col gap-1">
+                  <Stack gap={1} className="flex-1">
                     <div
                       className="bg-muted h-2 rounded"
                       style={{ width: `${60 + i * 10}%` }}
@@ -192,14 +203,14 @@ export const BrandingPreview = memo(function BrandingPreview({
                       className="bg-muted/50 h-1.5 rounded"
                       style={{ width: `${40 + i * 5}%` }}
                     />
-                  </div>
+                  </Stack>
                   <div className="bg-muted/50 h-1.5 w-8 rounded" />
-                </div>
+                </Row>
               ))}
-            </div>
-          </div>
-        </div>
+            </Stack>
+          </Stack>
+        </Row>
       </div>
-    </div>
+    </Row>
   );
 });
diff --git a/services/platform/app/features/settings/branding/components/branding-settings.tsx b/services/platform/app/features/settings/branding/components/branding-settings.tsx
index e99d688ba9..9e5b0415fb 100644
--- a/services/platform/app/features/settings/branding/components/branding-settings.tsx
+++ b/services/platform/app/features/settings/branding/components/branding-settings.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { useCallback, useState } from 'react';
 
@@ -68,7 +69,7 @@ function BrandingSettingsView({
         {/* `justify-center` centers the fixed-width form on small screens where
             the preview is hidden; it's inert on lg where the flex-1 preview fills
             the row. */}
-        <div className="flex flex-1 justify-center gap-6">
+        <Row gap={6} align="stretch" justify="center" className="flex-1">
           <BrandingForm
             organizationId={organizationId}
             branding={branding}
@@ -78,7 +79,7 @@ function BrandingSettingsView({
           <div className="hidden flex-1 lg:flex">
             <BrandingPreview data={previewData} />
           </div>
-        </div>
+        </Row>
       </SettingsSection>
     </SettingsPage>
   );
diff --git a/services/platform/app/features/settings/branding/components/color-picker-input.tsx b/services/platform/app/features/settings/branding/components/color-picker-input.tsx
index 3462afe5fd..4bbf0159c9 100644
--- a/services/platform/app/features/settings/branding/components/color-picker-input.tsx
+++ b/services/platform/app/features/settings/branding/components/color-picker-input.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { useSkeleton } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -85,7 +86,7 @@ export function ColorPickerInput({
         tabIndex={-1}
         aria-hidden="true"
       />
-      <div className="flex items-center justify-center px-2 py-1.5">
+      <Row gap={0} justify="center" className="px-2 py-1.5">
         <Text as="span" variant="muted" className="leading-5">
           #
         </Text>
@@ -99,12 +100,12 @@ export function ColorPickerInput({
           className="text-foreground placeholder:text-muted-foreground w-[4.5rem] border-none bg-transparent text-sm leading-5 font-normal outline-none"
           aria-label={`${label} hex value`}
         />
-      </div>
+      </Row>
     </div>
   );
 
   return (
-    <div className="flex items-stretch justify-between">
+    <Row gap={0} align="stretch" justify="between">
       <label
         htmlFor={id}
         className="text-foreground text-sm leading-5 font-medium"
@@ -112,6 +113,6 @@ export function ColorPickerInput({
         {label}
       </label>
       {loading ? <SkeletonBox>{control}</SkeletonBox> : control}
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/settings/components/settings-field.test.tsx b/services/platform/app/features/settings/components/settings-field.test.tsx
deleted file mode 100644
index 135f664f9f..0000000000
--- a/services/platform/app/features/settings/components/settings-field.test.tsx
+++ /dev/null
@@ -1,103 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { Input } from '@/app/components/ui/forms/input';
-import { checkAccessibility } from '@/tests/utils/a11y';
-import { render, screen, waitFor } from '@/tests/utils/render';
-
-import { SettingsField } from './settings-field';
-
-describe('SettingsField', () => {
-  describe('rendering', () => {
-    it('renders the label paired with htmlFor', () => {
-      render(
-        <SettingsField label="Name" htmlFor="name">
-          <Input id="name" placeholder="Name" />
-        </SettingsField>,
-      );
-      expect(
-        screen.getByLabelText('Name', { exact: false }),
-      ).toBeInTheDocument();
-    });
-
-    it('renders the description when provided', () => {
-      render(
-        <SettingsField
-          label="Name"
-          htmlFor="name"
-          description="Your display name"
-        >
-          <Input id="name" />
-        </SettingsField>,
-      );
-      expect(screen.getByText('Your display name')).toBeInTheDocument();
-    });
-
-    it('shows the error message with role=alert', () => {
-      render(
-        <SettingsField label="Name" htmlFor="name" error="Required field">
-          <Input id="name" />
-        </SettingsField>,
-      );
-      const alert = screen.getByRole('alert');
-      expect(alert).toHaveTextContent('Required field');
-    });
-
-    it('prefers error message over description when both are set', () => {
-      render(
-        <SettingsField
-          label="Name"
-          htmlFor="name"
-          description="Your display name"
-          error="Required field"
-        >
-          <Input id="name" />
-        </SettingsField>,
-      );
-      expect(screen.getByText('Required field')).toBeInTheDocument();
-      expect(screen.queryByText('Your display name')).toBeNull();
-    });
-
-    it('renders without a label when none is provided', () => {
-      render(
-        <SettingsField htmlFor="name">
-          <Input id="name" placeholder="Name" />
-        </SettingsField>,
-      );
-      expect(screen.queryByText('Name')).toBeNull();
-      expect(screen.getByPlaceholderText('Name')).toBeInTheDocument();
-    });
-
-    it('applies the configured width class', () => {
-      const { container } = render(
-        <SettingsField label="Name" htmlFor="name" width="full">
-          <Input id="name" />
-        </SettingsField>,
-      );
-      expect(container.firstChild).toHaveClass('w-full');
-    });
-  });
-
-  describe('accessibility', () => {
-    it('passes axe audit', async () => {
-      const { container } = render(
-        <SettingsField
-          label="Name"
-          htmlFor="name"
-          description="Your display name"
-        >
-          <Input id="name" />
-        </SettingsField>,
-      );
-      await waitFor(() => checkAccessibility(container));
-    });
-
-    it('passes axe audit with an error', async () => {
-      const { container } = render(
-        <SettingsField label="Name" htmlFor="name" error="Required field">
-          <Input id="name" />
-        </SettingsField>,
-      );
-      await waitFor(() => checkAccessibility(container));
-    });
-  });
-});
diff --git a/services/platform/app/features/settings/components/settings-field.tsx b/services/platform/app/features/settings/components/settings-field.tsx
deleted file mode 100644
index 6aae874ed0..0000000000
--- a/services/platform/app/features/settings/components/settings-field.tsx
+++ /dev/null
@@ -1,86 +0,0 @@
-'use client';
-
-import { Description } from '@tale/ui/description';
-import { Info } from 'lucide-react';
-import { forwardRef, useId, type HTMLAttributes, type ReactNode } from 'react';
-
-import { Label } from '@/app/components/ui/forms/label';
-import { cn } from '@/lib/utils/cn';
-
-interface SettingsFieldProps extends Omit<
-  HTMLAttributes<HTMLDivElement>,
-  'children'
-> {
-  label?: ReactNode;
-  description?: ReactNode;
-  error?: string;
-  required?: boolean;
-  htmlFor?: string;
-  /** Width preset for the control. `sm` is the default for most inputs. */
-  width?: 'sm' | 'md' | 'lg' | 'full';
-  children: ReactNode;
-}
-
-const widthClass: Record<NonNullable<SettingsFieldProps['width']>, string> = {
-  sm: 'max-w-sm',
-  md: 'max-w-md',
-  lg: 'max-w-lg',
-  full: 'w-full',
-};
-
-export const SettingsField = forwardRef<HTMLDivElement, SettingsFieldProps>(
-  (
-    {
-      label,
-      description,
-      error,
-      required,
-      htmlFor,
-      width = 'sm',
-      children,
-      className,
-      ...props
-    },
-    ref,
-  ) => {
-    const id = useId();
-    const descId = description ? `${id}-desc` : undefined;
-    const errorId = error ? `${id}-err` : undefined;
-
-    return (
-      <div
-        ref={ref}
-        className={cn('flex flex-col gap-1.5', widthClass[width], className)}
-        {...props}
-      >
-        {label && (
-          <Label htmlFor={htmlFor} required={required} error={!!error}>
-            {label}
-          </Label>
-        )}
-        <div
-          aria-describedby={
-            [descId, errorId].filter(Boolean).join(' ') || undefined
-          }
-        >
-          {children}
-        </div>
-        {error && (
-          <p
-            id={errorId}
-            role="alert"
-            aria-live="polite"
-            className="text-destructive flex items-center gap-1.5 text-sm"
-          >
-            <Info className="size-4" aria-hidden="true" />
-            {error}
-          </p>
-        )}
-        {description && !error && (
-          <Description id={descId}>{description}</Description>
-        )}
-      </div>
-    );
-  },
-);
-SettingsField.displayName = 'SettingsField';
diff --git a/services/platform/app/features/settings/components/settings-page.test.tsx b/services/platform/app/features/settings/components/settings-page.test.tsx
index a3d62d3d72..3eb81c7902 100644
--- a/services/platform/app/features/settings/components/settings-page.test.tsx
+++ b/services/platform/app/features/settings/components/settings-page.test.tsx
@@ -21,11 +21,6 @@ describe('SettingsPage', () => {
       expect(container.firstChild).toHaveClass('custom-class');
     });
 
-    it('centers content when narrow', () => {
-      const { container } = render(<SettingsPage narrow />);
-      expect(container.firstChild).toHaveClass('mx-auto');
-    });
-
     it('claims remaining height when fitToContainer', () => {
       const { container } = render(<SettingsPage fitToContainer />);
       expect(container.firstChild).toHaveClass('min-h-0', 'flex-1');
diff --git a/services/platform/app/features/settings/components/settings-page.tsx b/services/platform/app/features/settings/components/settings-page.tsx
index 8c4e5433e1..bf372de386 100644
--- a/services/platform/app/features/settings/components/settings-page.tsx
+++ b/services/platform/app/features/settings/components/settings-page.tsx
@@ -5,15 +5,6 @@ import type { HTMLAttributes, ReactNode } from 'react';
 import { cn } from '@/lib/utils/cn';
 
 interface SettingsPageProps extends HTMLAttributes<HTMLDivElement> {
-  /**
-   * Constrains the page content to a centered reading column matching
-   * `ContentArea variant="narrow"` (`max-w-[544px] mx-auto`) used by other
-   * form-heavy pages (project overview, agent settings). Use for personal
-   * and org-level settings pages whose forms read better in a single
-   * column. Pages dominated by a data table or side-by-side preview should
-   * leave this `false` (default) and let their own layout dictate width.
-   */
-  narrow?: boolean;
   /**
    * Makes the page participate in its parent's flex height so a single
    * child can claim the remaining viewport — required when the child uses
@@ -35,7 +26,6 @@ interface SettingsPageProps extends HTMLAttributes<HTMLDivElement> {
  * the visual rhythm is the same on every page in the settings area.
  */
 export function SettingsPage({
-  narrow,
   fitToContainer,
   children,
   className,
@@ -45,7 +35,6 @@ export function SettingsPage({
     <div
       className={cn(
         'flex w-full flex-col gap-8',
-        narrow && 'mx-auto max-w-[544px] self-center',
         // Bottom breathing room. ContentArea's `py-6` lives on a `flex-1`
         // child of the scroll container, so its padding-bottom is clipped
         // at the scroll boundary; a `pb-6` on this content-sized wrapper
diff --git a/services/platform/app/features/settings/components/settings-rail.tsx b/services/platform/app/features/settings/components/settings-rail.tsx
index 02a006b1bd..31c84724fe 100644
--- a/services/platform/app/features/settings/components/settings-rail.tsx
+++ b/services/platform/app/features/settings/components/settings-rail.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Link, useRouterState } from '@tanstack/react-router';
 import { ChevronDown, ChevronRight } from 'lucide-react';
 import { useEffect, useMemo, useState } from 'react';
@@ -178,9 +179,11 @@ export function SettingsRail({
   };
 
   return (
-    <nav
+    <Stack
       aria-label={tNav('userSettings')}
-      className="bg-background border-border flex w-60 shrink-0 flex-col gap-6 overflow-y-auto border-r py-6 pr-3 pl-4"
+      as="nav"
+      gap={6}
+      className="bg-background border-border w-60 shrink-0 overflow-y-auto border-r py-6 pr-3 pl-4"
     >
       {sections.map((section) => {
         const visible = section.items.filter(
@@ -189,7 +192,7 @@ export function SettingsRail({
         if (visible.length === 0) return null;
 
         return (
-          <div key={section.key} className="flex flex-col gap-1">
+          <Stack key={section.key} gap={1}>
             <div className="px-2">
               <span className="text-muted-foreground text-[11px] font-semibold tracking-wider uppercase">
                 {tSettings(`menu.railSections.${section.labelKey}`)}
@@ -216,10 +219,10 @@ export function SettingsRail({
                 ),
               )}
             </ul>
-          </div>
+          </Stack>
         );
       })}
-    </nav>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/settings/components/settings-row.tsx b/services/platform/app/features/settings/components/settings-row.tsx
index 08f374d16d..084b6ac1ac 100644
--- a/services/platform/app/features/settings/components/settings-row.tsx
+++ b/services/platform/app/features/settings/components/settings-row.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Description } from '@tale/ui/description';
+import { Stack } from '@tale/ui/layout';
 import { forwardRef, useId, type HTMLAttributes, type ReactNode } from 'react';
 
 import { cn } from '@/lib/utils/cn';
@@ -37,7 +38,7 @@ export const SettingsRow = forwardRef<HTMLDivElement, SettingsRowProps>(
         )}
         {...props}
       >
-        <div className="flex min-w-0 flex-col gap-1">
+        <Stack gap={1} className="min-w-0">
           <span
             id={labelId}
             className="text-foreground text-sm leading-none font-medium"
@@ -45,7 +46,7 @@ export const SettingsRow = forwardRef<HTMLDivElement, SettingsRowProps>(
             {label}
           </span>
           {description && <Description id={descId}>{description}</Description>}
-        </div>
+        </Stack>
         <div className="shrink-0">{children}</div>
       </div>
     );
diff --git a/services/platform/app/features/settings/components/settings-section-list.tsx b/services/platform/app/features/settings/components/settings-section-list.tsx
index 564551602f..88b2e98b68 100644
--- a/services/platform/app/features/settings/components/settings-section-list.tsx
+++ b/services/platform/app/features/settings/components/settings-section-list.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Description } from '@tale/ui/description';
+import { Stack } from '@tale/ui/layout';
 import { Link } from '@tanstack/react-router';
 import { ChevronRight, type LucideIcon } from 'lucide-react';
 import type { ReactNode } from 'react';
@@ -43,15 +44,17 @@ export function SettingsSectionList({
       className={cn('flex flex-col gap-7', className)}
     >
       {groups.map((group) => (
-        <div key={group.key} className="flex flex-col gap-2">
+        <Stack key={group.key} gap={2}>
           {group.label && (
             <div className="text-muted-foreground px-1 text-xs font-medium tracking-wide uppercase">
               {group.label}
             </div>
           )}
-          <ul
+          <Stack
             role="list"
-            className="border-border bg-card flex flex-col rounded-lg border"
+            as="ul"
+            gap={0}
+            className="border-border bg-card rounded-lg border"
           >
             {group.items.map((item, index) => {
               const Icon = item.icon;
@@ -86,8 +89,8 @@ export function SettingsSectionList({
                 </li>
               );
             })}
-          </ul>
-        </div>
+          </Stack>
+        </Stack>
       ))}
     </nav>
   );
diff --git a/services/platform/app/features/settings/components/settings-section.tsx b/services/platform/app/features/settings/components/settings-section.tsx
index 485aee8a6f..3be4a50f82 100644
--- a/services/platform/app/features/settings/components/settings-section.tsx
+++ b/services/platform/app/features/settings/components/settings-section.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Description } from '@tale/ui/description';
+import { Stack } from '@tale/ui/layout';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { forwardRef, useId, type HTMLAttributes, type ReactNode } from 'react';
 
@@ -47,7 +48,7 @@ export const SettingsSection = forwardRef<HTMLElement, SettingsSectionProps>(
           {/* Cap the title/description column at a readable line length so long
               descriptions don't stretch the full content width (and run up
               against a right-aligned `action`). */}
-          <div className="flex max-w-2xl min-w-0 flex-col gap-1">
+          <Stack gap={1} className="max-w-2xl min-w-0">
             <h2
               id={headingId}
               className="text-foreground text-base leading-tight font-semibold"
@@ -67,7 +68,7 @@ export const SettingsSection = forwardRef<HTMLElement, SettingsSectionProps>(
                 {description}
               </Description>
             )}
-          </div>
+          </Stack>
           {action && <div className="shrink-0">{action}</div>}
         </div>
         {children}
diff --git a/services/platform/app/features/settings/components/settings-toggle-row.tsx b/services/platform/app/features/settings/components/settings-toggle-row.tsx
index 50ba289415..0cd1e444d8 100644
--- a/services/platform/app/features/settings/components/settings-toggle-row.tsx
+++ b/services/platform/app/features/settings/components/settings-toggle-row.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Description } from '@tale/ui/description';
+import { Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { forwardRef, useId, type ComponentRef, type ReactNode } from 'react';
 
@@ -32,7 +33,7 @@ interface SettingsToggleRowProps {
  * the Switch via `aria-labelledby` rather than relying on the row-level
  * association.
  *
- * Use this instead of pairing a `PageSection` with a bare `Switch`: the
+ * Use this instead of pairing a `SettingsSection` with a bare `Switch`: the
  * bare-switch layout leaves the toggle anchored to the left under a
  * heading, breaking the "controls live on the right" visual rhythm shared
  * with the rest of settings.
@@ -64,7 +65,7 @@ export const SettingsToggleRow = forwardRef<
           className,
         )}
       >
-        <div className="flex min-w-0 flex-col gap-1">
+        <Stack gap={1} className="min-w-0">
           <span
             id={labelId}
             className="text-foreground text-sm leading-none font-medium"
@@ -78,7 +79,7 @@ export const SettingsToggleRow = forwardRef<
               <SkeletonBox fullWidth>{description}</SkeletonBox>
             </Description>
           )}
-        </div>
+        </Stack>
         <div className="shrink-0">
           <Switch
             ref={ref}
diff --git a/services/platform/app/features/settings/deployment/components/deployment-settings.tsx b/services/platform/app/features/settings/deployment/components/deployment-settings.tsx
index c763f9b5d6..c75565dd99 100644
--- a/services/platform/app/features/settings/deployment/components/deployment-settings.tsx
+++ b/services/platform/app/features/settings/deployment/components/deployment-settings.tsx
@@ -8,7 +8,7 @@
  * stores panel.
  * `api.deployment.*` resolves after `convex codegen` (runs on dev/deploy).
  *
- * Built on the shared settings UI (`PageSection`, app `Input`/`Select`/
+ * Built on the shared settings UI (`SettingsSection`, app `Input`/`Select`/
  * `Switch`, `Alert`, `Stack`/`HStack`) so it matches every other settings page
  * instead of carrying bespoke banner / label / card chrome.
  *
@@ -19,8 +19,7 @@
 
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { Grid, HStack, Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Info } from 'lucide-react';
 import { type Dispatch, type SetStateAction, useEffect, useState } from 'react';
@@ -32,6 +31,7 @@ import { Input } from '@/app/components/ui/forms/input';
 import { Select } from '@/app/components/ui/forms/select';
 import { Switch } from '@/app/components/ui/forms/switch';
 import { SettingsPage } from '@/app/features/settings/components/settings-page';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility, useAbilityLoading } from '@/app/hooks/use-ability';
 import { useT } from '@/lib/i18n/client';
 import { cn } from '@/lib/utils/cn';
@@ -225,7 +225,7 @@ function PgSection({
 }) {
   const { t } = useT('settings');
   return (
-    <PageSection
+    <SettingsSection
       className={className}
       title={title}
       description={description}
@@ -243,7 +243,7 @@ function PgSection({
     >
       {state.enabled ? (
         <Stack gap={4}>
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+          <Grid sm={2}>
             <Input
               label={t('dataResidency.field.host')}
               value={state.host}
@@ -294,11 +294,10 @@ function PgSection({
                     : t('dataResidency.password.writeOnlyHint')
               }
             />
-          </div>
+          </Grid>
           <HStack gap={3} align="center" className="flex-wrap">
             <Button
               variant="secondary"
-              size="sm"
               onClick={onTest}
               disabled={disabled || testing}
             >
@@ -318,7 +317,7 @@ function PgSection({
           {t('dataResidency.usingSharedDatabase')}
         </p>
       )}
-    </PageSection>
+    </SettingsSection>
   );
 }
 
@@ -621,8 +620,8 @@ function DeploymentSettingsView({
           Save / Apply & restart bar stays pinned to the bottom of the viewport
           regardless of how short the content is (plain `position: sticky` only
           pins once the content is tall enough to scroll). */}
-      <div className="flex min-h-0 flex-1 flex-col">
-        <div className="flex min-h-0 flex-1 flex-col gap-8 overflow-y-auto pb-8">
+      <Stack gap={0} className="min-h-0 flex-1">
+        <Stack gap={8} className="min-h-0 flex-1 overflow-y-auto pb-8">
           {readOnly ||
           data?.secretsError === 'encrypted_no_key' ||
           data?.secretsError === 'unreadable' ? (
@@ -684,8 +683,7 @@ function DeploymentSettingsView({
             }
           />
 
-          <PageSection
-            className="border-border border-t pt-8"
+          <SettingsSection
             title={t('dataResidency.storage.title')}
             description={t('dataResidency.storage.description')}
             action={
@@ -702,7 +700,7 @@ function DeploymentSettingsView({
           >
             {storage.s3 ? (
               <Stack gap={5}>
-                <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                <Grid sm={2}>
                   <Input
                     label={t('dataResidency.storage.region')}
                     value={storage.region}
@@ -719,7 +717,7 @@ function DeploymentSettingsView({
                       setStorage({ ...storage, endpoint: e.target.value })
                     }
                   />
-                </div>
+                </Grid>
                 <Switch
                   label={t('dataResidency.storage.forcePathStyle')}
                   checked={storage.forcePathStyle}
@@ -729,7 +727,7 @@ function DeploymentSettingsView({
                   }
                 />
                 <FormSection label={t('dataResidency.storage.bucketsLabel')}>
-                  <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                  <Grid sm={2}>
                     <Input
                       label={t('dataResidency.storage.bucket.files')}
                       value={storage.files}
@@ -773,12 +771,12 @@ function DeploymentSettingsView({
                         setStorage({ ...storage, search: e.target.value })
                       }
                     />
-                  </div>
+                  </Grid>
                 </FormSection>
                 <FormSection
                   label={t('dataResidency.storage.credentialsLabel')}
                 >
-                  <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                  <Grid sm={2}>
                     <Input
                       label={t('dataResidency.storage.accessKeyId')}
                       value={storage.accessKeyId}
@@ -811,12 +809,11 @@ function DeploymentSettingsView({
                       }
                       description={t('dataResidency.storage.writeOnly')}
                     />
-                  </div>
+                  </Grid>
                 </FormSection>
                 <HStack gap={3} align="center" className="flex-wrap">
                   <Button
                     variant="secondary"
-                    size="sm"
                     onClick={() => void runTest('convexStorage')}
                     disabled={readOnly || testing === 'convexStorage'}
                   >
@@ -839,14 +836,13 @@ function DeploymentSettingsView({
                 {t('dataResidency.storage.localStorageNote')}
               </p>
             )}
-          </PageSection>
+          </SettingsSection>
 
           {/* Advanced Convex metadata DB — reuses the Postgres section chrome; its
           own header switch toggles `enabled`. Titled "(advanced)" rather than
           hidden behind a disclosure so it shares the rhythm of the sections
           above. */}
           <PgSection
-            className="border-border border-t pt-8"
             title={t('dataResidency.appDb.summary')}
             description={t('dataResidency.appDb.description')}
             state={appPg}
@@ -869,7 +865,7 @@ function DeploymentSettingsView({
               </p>
             }
           />
-        </div>
+        </Stack>
 
         {/* Footer docked to the bottom of the page (outside the scroll body)
             so Save / Apply & restart stay reachable regardless of content
@@ -928,7 +924,7 @@ function DeploymentSettingsView({
             </HStack>
           </Stack>
         </div>
-      </div>
+      </Stack>
 
       <ConfirmDialog
         open={restartConfirmOpen}
diff --git a/services/platform/app/features/settings/governance/components/budget-editor.tsx b/services/platform/app/features/settings/governance/components/budget-editor.tsx
index 5b647f013b..e76fa709ad 100644
--- a/services/platform/app/features/settings/governance/components/budget-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/budget-editor.tsx
@@ -1,8 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -23,6 +22,7 @@ import { FormDialog } from '@/app/components/ui/dialog/form-dialog';
 import { Input } from '@/app/components/ui/forms/input';
 import { SearchableSelect } from '@/app/components/ui/forms/searchable-select';
 import { Select } from '@/app/components/ui/forms/select';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useMembers } from '@/app/features/settings/organization/hooks/queries';
 import { useOrgTeams } from '@/app/features/settings/teams/hooks/queries';
 import { useAbility } from '@/app/hooks/use-ability';
@@ -140,7 +140,7 @@ function RuleDialog({
       submitText={t('budgets.confirm')}
     >
       <Stack gap={4}>
-        <div className="flex flex-wrap gap-3 *:min-w-[10rem] *:flex-1">
+        <Row gap={3} align="stretch" wrap className="*:min-w-[10rem] *:flex-1">
           <Select
             label={t('budgets.scope')}
             options={SCOPE_OPTIONS}
@@ -151,7 +151,6 @@ function RuleDialog({
               }
             }}
             disabled={cannotManage}
-            size="sm"
           />
 
           {draft.scope === 'role' && (
@@ -161,7 +160,6 @@ function RuleDialog({
               value={draft.scopeId ?? ''}
               onValueChange={(value) => updateDraft({ scopeId: value })}
               disabled={cannotManage}
-              size="sm"
             />
           )}
 
@@ -170,7 +168,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('budgets.user')}
                 placeholder={t('budgets.selectUser')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -187,7 +184,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('budgets.team')}
                 placeholder={t('budgets.selectTeam')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -209,9 +205,8 @@ function RuleDialog({
               }
             }}
             disabled={cannotManage}
-            size="sm"
           />
-        </div>
+        </Row>
 
         <Stack gap={3}>
           <div>
@@ -227,7 +222,6 @@ function RuleDialog({
                 })
               }
               disabled={cannotManage}
-              size="sm"
               placeholder="e.g. 1000000"
               min={0}
             />
@@ -249,7 +243,6 @@ function RuleDialog({
                 })
               }
               disabled={cannotManage}
-              size="sm"
               placeholder="e.g. 50.00"
               min={0}
               step={0.01}
@@ -272,7 +265,6 @@ function RuleDialog({
                 })
               }
               disabled={cannotManage}
-              size="sm"
               placeholder="e.g. 500"
               min={0}
             />
@@ -294,7 +286,6 @@ function RuleDialog({
                 })
               }
               disabled={cannotManage}
-              size="sm"
               placeholder="e.g. 80"
               min={0}
               max={100}
@@ -321,7 +312,7 @@ const COLUMN_COUNT = 7;
 
 // =============================================================================
 // Single editor — owns data fetching, rules state, dialog state, and
-// save/toast wiring. Renders the REAL `PageSection` once, always, wrapped in
+// save/toast wiring. Renders the REAL `SettingsSection` once, always, wrapped in
 // `<Skeletonize>`; the table renders fixed PLACEHOLDER rows while loading so an
 // empty `<tbody>` never reads as "no rules" during load.
 // =============================================================================
@@ -489,16 +480,11 @@ export function BudgetEditor({ organizationId }: BudgetEditorProps) {
 
   return (
     <Skeletonize loading={loading} label={t('budgets.title')}>
-      <PageSection
+      <SettingsSection
         title={t('budgets.title')}
         description={t('budgets.description')}
         action={
-          <Button
-            variant="primary"
-            size="sm"
-            onClick={onAddRule}
-            disabled={cannotManage}
-          >
+          <Button variant="primary" onClick={onAddRule} disabled={cannotManage}>
             <Plus className="mr-1.5 size-4" />
             {t('budgets.addRule')}
           </Button>
@@ -609,7 +595,7 @@ export function BudgetEditor({ organizationId }: BudgetEditorProps) {
                             size="icon"
                             onClick={() => onEditRule(index)}
                             disabled={cannotManage}
-                            aria-label={t('budgets.editRuleAriaLabel', {
+                            title={t('budgets.editRuleAriaLabel', {
                               index: index + 1,
                             })}
                           >
@@ -620,7 +606,7 @@ export function BudgetEditor({ organizationId }: BudgetEditorProps) {
                             size="icon"
                             onClick={() => onRemoveRule(index)}
                             disabled={cannotManage}
-                            aria-label={t('budgets.removeRuleAriaLabel', {
+                            title={t('budgets.removeRuleAriaLabel', {
                               index: index + 1,
                             })}
                           >
@@ -668,7 +654,7 @@ export function BudgetEditor({ organizationId }: BudgetEditorProps) {
           variant="destructive"
           onConfirm={onConfirmRemove}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/chat-filter-config.tsx b/services/platform/app/features/settings/governance/components/chat-filter-config.tsx
index 9ec876cef9..bdaa041c84 100644
--- a/services/platform/app/features/settings/governance/components/chat-filter-config.tsx
+++ b/services/platform/app/features/settings/governance/components/chat-filter-config.tsx
@@ -2,7 +2,7 @@
 
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
   Table,
@@ -22,6 +22,7 @@ import { Select } from '@/app/components/ui/forms/select';
 import { Switch } from '@/app/components/ui/forms/switch';
 import { Textarea } from '@/app/components/ui/forms/textarea';
 import { Sheet } from '@/app/components/ui/overlays/sheet';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -94,7 +95,7 @@ function deriveDraft(policy: ChatFilterPolicy): ChatFilterDraft {
 // =============================================================================
 // Container — owns data fetching, local edit state, save/toast wiring, and the
 // loading state. Wraps the plain `ChatFilterConfigForm` in `<Skeletonize>` so
-// the same tree renders the skeleton (the hand-rolled loading `PageSection`
+// the same tree renders the skeleton (the hand-rolled loading `SettingsSection`
 // with magic-height `Skeleton` boxes is gone — the skeleton-aware `<Switch>` /
 // `<Input>` mask themselves to their real height).
 //
@@ -285,7 +286,7 @@ export function ChatFilterConfigView({
 
   return (
     <Skeletonize loading={isLoading} label={t('contentSafety.title')}>
-      <PageSection
+      <SettingsSection
         title={t('contentSafety.title')}
         description={t('contentSafety.description')}
         action={
@@ -311,7 +312,7 @@ export function ChatFilterConfigView({
               label={t('contentSafety.applyTo')}
               description={t('contentSafety.applyToDescription')}
             >
-              <div className="flex flex-col gap-2">
+              <Stack gap={2}>
                 <label className="flex items-center gap-2">
                   <input
                     type="checkbox"
@@ -330,7 +331,7 @@ export function ChatFilterConfigView({
                   />
                   <span>{t('contentSafety.modelOutput')}</span>
                 </label>
-              </div>
+              </Stack>
             </FormSection>
 
             <FormSection label={t('contentSafety.maskReplacement')}>
@@ -405,7 +406,7 @@ export function ChatFilterConfigView({
             />
           </>
         )}
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
@@ -529,7 +530,7 @@ function CategoryEditForm({
   };
 
   return (
-    <div className="flex h-full flex-col">
+    <Stack gap={0} className="h-full">
       <div className="shrink-0 pr-10">
         <h2 className="text-lg font-semibold tracking-tight">
           {isNew
@@ -542,7 +543,7 @@ function CategoryEditForm({
       </div>
 
       <div className="-mx-6 min-h-0 flex-1 overflow-y-auto px-6 py-4">
-        <div className="flex flex-col gap-4">
+        <Stack>
           <FormSection label={t('contentSafety.categoryLabel')}>
             <Input
               value={label}
@@ -576,8 +577,8 @@ function CategoryEditForm({
             label={t('contentSafety.wordsCount', { count: wordLines.length })}
             description={t('contentSafety.wordsDescription')}
           >
-            <div className="flex flex-col gap-2">
-              <div className="flex gap-2">
+            <Stack gap={2}>
+              <Row gap={2} align="stretch">
                 <Button
                   variant="secondary"
                   size="sm"
@@ -604,7 +605,7 @@ function CategoryEditForm({
                     void handleImportFile(e);
                   }}
                 />
-              </div>
+              </Row>
               <Textarea
                 value={wordsText}
                 rows={14}
@@ -612,12 +613,17 @@ function CategoryEditForm({
                 onChange={(e) => setWordsText(e.target.value)}
                 placeholder={t('contentSafety.wordsPlaceholder')}
               />
-            </div>
+            </Stack>
           </FormSection>
-        </div>
+        </Stack>
       </div>
 
-      <div className="flex shrink-0 justify-end gap-2 border-t pt-4">
+      <Row
+        gap={2}
+        align="stretch"
+        justify="end"
+        className="shrink-0 border-t pt-4"
+      >
         <Button variant="ghost" onClick={onCancel}>
           {tCommon('actions.cancel')}
         </Button>
@@ -628,8 +634,8 @@ function CategoryEditForm({
         >
           {tCommon('actions.save')}
         </Button>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
@@ -657,7 +663,7 @@ function CategoryList({
   const { t } = useT('governance');
   const { t: tCommon } = useT('common');
   return (
-    <div className="flex flex-col gap-2">
+    <Stack gap={2}>
       {categories.length === 0 ? (
         <div className="text-muted-foreground text-sm">
           {t('contentSafety.categoriesEmpty')}
@@ -692,7 +698,7 @@ function CategoryList({
                 <TableCell>{category.words.length}</TableCell>
                 <TableCell>{category.patterns.length}</TableCell>
                 <TableCell>
-                  <div className="flex justify-end gap-1">
+                  <Row gap={1} align="stretch" justify="end">
                     <Button
                       variant="ghost"
                       size="sm"
@@ -715,7 +721,7 @@ function CategoryList({
                       disabled={disabled}
                       onClick={() => onDelete(index)}
                     />
-                  </div>
+                  </Row>
                 </TableCell>
               </TableRow>
             ))}
@@ -725,7 +731,6 @@ function CategoryList({
       <div>
         <Button
           variant="secondary"
-          size="sm"
           icon={Plus}
           disabled={disabled}
           onClick={onAdd}
@@ -733,7 +738,7 @@ function CategoryList({
           {t('contentSafety.addCategory')}
         </Button>
       </div>
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/settings/governance/components/default-model-editor.tsx b/services/platform/app/features/settings/governance/components/default-model-editor.tsx
index 55789b84e0..ffef21b5db 100644
--- a/services/platform/app/features/settings/governance/components/default-model-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/default-model-editor.tsx
@@ -3,7 +3,6 @@
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
 import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -26,6 +25,7 @@ import {
 } from '@/app/components/ui/forms/searchable-select';
 import { Select } from '@/app/components/ui/forms/select';
 import { ModelInfoPopover } from '@/app/features/chat/components/model-info-popover';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import {
   useListProviders,
   useModelCapabilities,
@@ -279,7 +279,6 @@ function RuleDialog({
                 }
               }}
               disabled={cannotManage}
-              size="sm"
             />
           </div>
 
@@ -291,7 +290,6 @@ function RuleDialog({
                 value={draft.scopeId ?? ''}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
                 disabled={cannotManage}
-                size="sm"
               />
             </div>
           )}
@@ -301,7 +299,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('defaultModels.target')}
                 placeholder={t('defaultModels.selectTeam')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -317,7 +314,6 @@ function RuleDialog({
         <SearchableSelect
           label={t('defaultModels.provider')}
           placeholder={t('defaultModels.selectProvider')}
-          size="sm"
           disabled={cannotManage}
           value={draft.providerName || null}
           onValueChange={(value) => updateDraft({ providerName: value })}
@@ -330,7 +326,6 @@ function RuleDialog({
         <SearchableSelect
           label={t('defaultModels.model')}
           placeholder={t('defaultModels.selectModel')}
-          size="sm"
           disabled={cannotManage || !draft.providerName}
           value={draft.modelId || null}
           onValueChange={(value) => updateDraft({ modelId: value })}
@@ -576,13 +571,12 @@ export function DefaultModelEditor({
 
   return (
     <Skeletonize loading={loading} label={t('defaultModels.title')}>
-      <PageSection
+      <SettingsSection
         title={t('defaultModels.title')}
         description={t('defaultModels.description')}
         action={
           <Button
             variant="primary"
-            size="sm"
             onClick={openAddDialog}
             disabled={cannotManage}
           >
@@ -657,7 +651,7 @@ export function DefaultModelEditor({
                           size="icon"
                           onClick={() => openEditDialog(index)}
                           disabled={cannotManage}
-                          aria-label={t('defaultModels.editRule', {
+                          title={t('defaultModels.editRule', {
                             index: index + 1,
                           })}
                         >
@@ -668,7 +662,7 @@ export function DefaultModelEditor({
                           size="icon"
                           onClick={() => setDeletingIndex(index)}
                           disabled={cannotManage}
-                          aria-label={t('defaultModels.removeRule', {
+                          title={t('defaultModels.removeRule', {
                             index: index + 1,
                           })}
                         >
@@ -721,7 +715,7 @@ export function DefaultModelEditor({
           variant="destructive"
           onConfirm={confirmRemoveRule}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/dsar-policy-editor.tsx b/services/platform/app/features/settings/governance/components/dsar-policy-editor.tsx
index fc9113c46e..719bb5405a 100644
--- a/services/platform/app/features/settings/governance/components/dsar-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/dsar-policy-editor.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
 import { AlertTriangle, Ban, Lock } from 'lucide-react';
@@ -10,6 +10,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
 import type { DsarGovernanceConfig } from '@/lib/shared/schemas/governance';
@@ -200,15 +201,17 @@ export function DsarPolicyEditor({ organizationId }: DsarPolicyEditorProps) {
 
   return (
     <Skeletonize loading={isLoading || !data} label={t('dsarPolicy.title')}>
-      <PageSection
+      <SettingsSection
         title={t('dsarPolicy.title')}
         description={t('dsarPolicy.description')}
       >
-        <div className="flex max-w-2xl flex-col gap-5">
+        <Stack gap={5} className="max-w-2xl">
           {data && !data.callerIsOwner && (
-            <div
+            <Row
               role="status"
-              className="border-border bg-muted/30 flex items-start gap-2 rounded-md border p-3 text-sm"
+              gap={2}
+              align="start"
+              className="border-border bg-muted/30 rounded-md border p-3 text-sm"
             >
               <Lock
                 className="text-muted-foreground mt-0.5 size-4 shrink-0"
@@ -217,7 +220,7 @@ export function DsarPolicyEditor({ organizationId }: DsarPolicyEditorProps) {
               <Text as="span" variant="muted" className="text-xs">
                 {t('dsarPolicy.ownerOnlyNotice')}
               </Text>
-            </div>
+            </Row>
           )}
 
           {data?.pending && (
@@ -246,7 +249,7 @@ export function DsarPolicyEditor({ organizationId }: DsarPolicyEditorProps) {
           </PendingFieldWrap>
 
           <PendingFieldWrap pending={pendingFields.requireDualApproval} t={t}>
-            <div className="flex items-start justify-between gap-3">
+            <Row gap={3} align="start" justify="between">
               <div className="flex flex-col gap-0.5">
                 <Text as="span" className="text-sm font-medium">
                   {t('dsarPolicy.requireDualApproval.label')}
@@ -261,7 +264,7 @@ export function DsarPolicyEditor({ organizationId }: DsarPolicyEditorProps) {
                 disabled={readOnly}
                 aria-label={t('dsarPolicy.requireDualApproval.label')}
               />
-            </div>
+            </Row>
           </PendingFieldWrap>
 
           <PendingFieldWrap pending={pendingFields.dailyLimitPerAdmin} t={t}>
@@ -279,8 +282,8 @@ export function DsarPolicyEditor({ organizationId }: DsarPolicyEditorProps) {
               disabled={readOnly}
             />
           </PendingFieldWrap>
-        </div>
-      </PageSection>
+        </Stack>
+      </SettingsSection>
     </Skeletonize>
   );
 }
@@ -303,10 +306,10 @@ function PendingFieldWrap({
   return (
     <div className="relative opacity-60">
       <div className="pointer-events-none">{children}</div>
-      <div className="text-muted-foreground mt-1 flex items-center gap-1 text-xs">
+      <Row gap={1} className="text-muted-foreground mt-1 text-xs">
         <Lock className="size-3" aria-hidden="true" />
         <span>{t('dsarPolicy.pendingFieldLocked')}</span>
-      </div>
+      </Row>
     </div>
   );
 }
@@ -353,16 +356,17 @@ function PendingChangeBanner({
     });
   }
   return (
-    <div
+    <Stack
       role="status"
-      className="text-foreground flex flex-col gap-2 rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-sm"
+      gap={2}
+      className="text-foreground rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-sm"
     >
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <AlertTriangle
           className="mt-0.5 size-4 shrink-0 text-amber-700 dark:text-amber-300"
           aria-hidden="true"
         />
-        <div className="flex flex-col gap-1">
+        <Stack gap={1}>
           <Text as="span" className="font-medium">
             {t('dsarPolicy.pendingBanner.title')}
           </Text>
@@ -390,20 +394,19 @@ function PendingChangeBanner({
               ))}
             </ul>
           )}
-        </div>
-      </div>
-      <div className="flex justify-end">
+        </Stack>
+      </Row>
+      <Row gap={0} align="stretch" justify="end">
         <Button
           type="button"
           variant="destructive"
-          size="sm"
           icon={Ban}
           onClick={onCancel}
           disabled={cancelDisabled}
         >
           {t('dsarPolicy.pendingBanner.cancel')}
         </Button>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/feature-flags-editor.tsx b/services/platform/app/features/settings/governance/components/feature-flags-editor.tsx
index 086b49efd3..6a40832023 100644
--- a/services/platform/app/features/settings/governance/components/feature-flags-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/feature-flags-editor.tsx
@@ -1,8 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -24,6 +23,7 @@ import { Input } from '@/app/components/ui/forms/input';
 import { SearchableSelect } from '@/app/components/ui/forms/searchable-select';
 import { Select } from '@/app/components/ui/forms/select';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useMembers } from '@/app/features/settings/organization/hooks/queries';
 import { useOrgTeams } from '@/app/features/settings/teams/hooks/queries';
 import { useAbility } from '@/app/hooks/use-ability';
@@ -163,7 +163,7 @@ function RuleDialog({
       isDirty={isDirty}
     >
       <Stack gap={4}>
-        <div className="flex flex-wrap gap-3 *:min-w-[10rem] *:flex-1">
+        <Row gap={3} align="stretch" wrap className="*:min-w-[10rem] *:flex-1">
           <Select
             label={t('featureFlags.scope')}
             options={scopeOptions}
@@ -174,7 +174,6 @@ function RuleDialog({
               }
             }}
             disabled={cannotManage}
-            size="sm"
           />
 
           {draft.scope === 'role' && (
@@ -184,7 +183,6 @@ function RuleDialog({
               value={draft.scopeId ?? ''}
               onValueChange={(value) => updateDraft({ scopeId: value })}
               disabled={cannotManage}
-              size="sm"
             />
           )}
 
@@ -193,7 +191,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('featureFlags.scopeLabels.user')}
                 placeholder={t('featureFlags.selectUser')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -210,7 +207,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('featureFlags.scopeLabels.team')}
                 placeholder={t('featureFlags.selectTeam')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -221,7 +217,7 @@ function RuleDialog({
               />
             </div>
           )}
-        </div>
+        </Row>
 
         <Stack gap={3}>
           <Switch
@@ -258,7 +254,6 @@ function RuleDialog({
                 })
               }
               disabled={cannotManage}
-              size="sm"
               placeholder="e.g. 50000"
               min={0}
             />
@@ -301,7 +296,7 @@ const COLUMN_COUNT = 7;
 
 // =============================================================================
 // Single editor — owns data fetching, rules state, dialog state, and save/toast
-// wiring. Renders the REAL `PageSection` once, always, wrapped in
+// wiring. Renders the REAL `SettingsSection` once, always, wrapped in
 // `<Skeletonize>`. The table renders fixed PLACEHOLDER rows while loading so an
 // empty `<tbody>` never reads as "no rules" during load; the real empty-state
 // only shows once loaded with zero rules.
@@ -465,16 +460,11 @@ export function FeatureFlagsEditor({
 
   return (
     <Skeletonize loading={loading} label={t('featureFlags.title')}>
-      <PageSection
+      <SettingsSection
         title={t('featureFlags.title')}
         description={t('featureFlags.description')}
         action={
-          <Button
-            variant="primary"
-            size="sm"
-            onClick={onAddRule}
-            disabled={cannotManage}
-          >
+          <Button variant="primary" onClick={onAddRule} disabled={cannotManage}>
             <Plus className="mr-1.5 size-4" />
             {t('featureFlags.addRule')}
           </Button>
@@ -578,7 +568,7 @@ export function FeatureFlagsEditor({
                           size="icon"
                           onClick={() => onEditRule(index)}
                           disabled={cannotManage}
-                          aria-label={`${t('featureFlags.editRule')} ${index + 1}`}
+                          title={`${t('featureFlags.editRule')} ${index + 1}`}
                         >
                           <Pencil className="size-4" />
                         </Button>
@@ -587,7 +577,7 @@ export function FeatureFlagsEditor({
                           size="icon"
                           onClick={() => onRemoveRule(index)}
                           disabled={cannotManage}
-                          aria-label={`${t('featureFlags.deleteRule')} ${index + 1}`}
+                          title={`${t('featureFlags.deleteRule')} ${index + 1}`}
                         >
                           <Trash2 className="size-4" />
                         </Button>
@@ -632,7 +622,7 @@ export function FeatureFlagsEditor({
           variant="destructive"
           onConfirm={onConfirmRemove}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/guardrails-overview.tsx b/services/platform/app/features/settings/governance/components/guardrails-overview.tsx
index 314b310406..fb9946cb82 100644
--- a/services/platform/app/features/settings/governance/components/guardrails-overview.tsx
+++ b/services/platform/app/features/settings/governance/components/guardrails-overview.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize, useSkeleton } from '@tale/ui/skeleton-context';
 import {
@@ -19,6 +19,7 @@ import { useMemo, useState } from 'react';
 
 import { Select } from '@/app/components/ui/forms/select';
 import { Sheet } from '@/app/components/ui/overlays/sheet';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { useFormatDate } from '@/app/hooks/use-format-date';
 import { useToast } from '@/app/hooks/use-toast';
@@ -82,7 +83,7 @@ function StatusCard({
   const loading = useSkeleton();
   return (
     <div className="border-border rounded-lg border p-4">
-      <div className="mb-2 flex items-center gap-2">
+      <Row gap={2} className="mb-2">
         <Icon
           className={
             enabled && !loading
@@ -92,7 +93,7 @@ function StatusCard({
           aria-hidden
         />
         <div className="font-medium">{title}</div>
-      </div>
+      </Row>
       <div className="text-muted-foreground mb-3 text-xs">{description}</div>
       {loading ? (
         <div className="text-xs">
@@ -211,11 +212,11 @@ export function GuardrailsOverview({
 
   return (
     <Skeletonize loading={isLoading} label={t('guardrailsOverview.title')}>
-      <PageSection
+      <SettingsSection
         title={t('guardrailsOverview.title')}
         description={t('guardrailsOverview.description')}
       >
-        <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
+        <Grid md={3}>
           <StatusCard
             title={t('guardrailsOverview.statusCards.contentSafety.title')}
             description={t(
@@ -248,13 +249,13 @@ export function GuardrailsOverview({
             )}
             icon={ShieldAlert}
           />
-        </div>
+        </Grid>
 
         <RecentEvents
           organizationId={organizationId}
           chatFilterLabels={chatFilterLabels}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
@@ -299,19 +300,18 @@ function RecentEvents({ organizationId, chatFilterLabels }: RecentEventsProps) {
   );
 
   return (
-    <section className="mt-8 flex flex-col gap-4">
-      <div className="flex flex-wrap items-start justify-between gap-3">
-        <div className="flex min-w-0 flex-col gap-1">
+    <Stack as="section" className="mt-8">
+      <Row gap={3} align="start" justify="between" wrap>
+        <Stack gap={1} className="min-w-0">
           <h2 className="text-foreground text-base leading-tight font-semibold">
             {t('guardrailsOverview.recentEvents.title')}
           </h2>
           <p className="text-muted-foreground text-sm">
             {t('guardrailsOverview.recentEvents.description')}
           </p>
-        </div>
-        <div className="flex gap-2">
+        </Stack>
+        <Row gap={2} align="stretch">
           <Select
-            size="sm"
             aria-label={t('guardrailsOverview.recentEvents.columnFilter')}
             value={filterName}
             onValueChange={(v) => {
@@ -344,7 +344,6 @@ function RecentEvents({ organizationId, chatFilterLabels }: RecentEventsProps) {
             ]}
           />
           <Select
-            size="sm"
             aria-label={t('guardrailsOverview.recentEvents.columnKind')}
             value={kind}
             onValueChange={(v) => {
@@ -381,8 +380,8 @@ function RecentEvents({ organizationId, chatFilterLabels }: RecentEventsProps) {
               },
             ]}
           />
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       {!isLoading && (!events || events.length === 0) ? (
         // Real empty-state only once the read has settled with zero rows.
@@ -510,7 +509,7 @@ function RecentEvents({ organizationId, chatFilterLabels }: RecentEventsProps) {
         chatFilterLabels={chatFilterLabels}
         onClose={() => setSelectedEvent(null)}
       />
-    </section>
+    </Stack>
   );
 }
 
@@ -560,7 +559,7 @@ function EventDetailSheet({
       description={t('guardrailsOverview.eventDetails.description')}
       className="sm:!max-w-xl"
     >
-      <div className="flex h-full flex-col">
+      <Stack gap={0} className="h-full">
         <div className="shrink-0 pr-10">
           <h2 className="text-lg font-semibold tracking-tight">
             {t('guardrailsOverview.eventDetails.title')}
@@ -590,7 +589,7 @@ function EventDetailSheet({
                 {event.categoryIds.length === 0 ? (
                   <span className="text-muted-foreground">—</span>
                 ) : (
-                  <ul className="flex flex-col gap-1">
+                  <Stack as="ul" gap={1}>
                     {event.categoryIds.map((id) => {
                       const label =
                         event.filterName === 'chat_filter'
@@ -617,7 +616,7 @@ function EventDetailSheet({
                         </li>
                       );
                     })}
-                  </ul>
+                  </Stack>
                 )}
               </DetailRow>
               <DetailRow label={t('guardrailsOverview.eventDetails.matches')}>
@@ -732,12 +731,17 @@ function EventDetailSheet({
           )}
         </div>
 
-        <div className="flex shrink-0 justify-end gap-2 border-t pt-4">
+        <Row
+          gap={2}
+          align="stretch"
+          justify="end"
+          className="shrink-0 border-t pt-4"
+        >
           <Button variant="ghost" onClick={onClose}>
             {t('guardrailsOverview.eventDetails.close')}
           </Button>
-        </div>
-      </div>
+        </Row>
+      </Stack>
     </Sheet>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/login-policy-editor.tsx b/services/platform/app/features/settings/governance/components/login-policy-editor.tsx
index 2fdea1c1ca..d578db1fd4 100644
--- a/services/platform/app/features/settings/governance/components/login-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/login-policy-editor.tsx
@@ -1,15 +1,15 @@
 'use client';
 
 import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useMemo } from 'react';
 import { z } from 'zod';
 
 import { EditorActions, useFormEditor } from '@/app/components/ui/editor';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -20,10 +20,11 @@ import {
   loginPolicyConfigSchema,
   type LoginPolicyConfig,
 } from '@/lib/shared/schemas/governance';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
+import { useGovernancePolicyToggle } from '../hooks/use-governance-policy-toggle';
 
 interface LoginPolicyEditorProps {
   organizationId: string;
@@ -37,17 +38,12 @@ interface LoginPolicyForm {
 
 const FORM_ID = 'governance-login-policy-form';
 
-function parseConfig(raw: unknown): LoginPolicyConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = loginPolicyConfigSchema.safeParse(obj);
-  if (result.success) return result.data;
-  return {
-    enabled: true,
-    maxAttemptsBeforeLockout: DEFAULT_LOGIN_MAX_ATTEMPTS,
-    backoffSchedule: [...DEFAULT_LOGIN_BACKOFF_MS],
-    trustedProxies: [...DEFAULT_TRUSTED_PROXIES],
-  };
-}
+const parseConfig = createConfigParser(loginPolicyConfigSchema, () => ({
+  enabled: true,
+  maxAttemptsBeforeLockout: DEFAULT_LOGIN_MAX_ATTEMPTS,
+  backoffSchedule: [...DEFAULT_LOGIN_BACKOFF_MS],
+  trustedProxies: [...DEFAULT_TRUSTED_PROXIES],
+}));
 
 function stringToProxyList(value: string): string[] | null {
   const parts = value
@@ -103,10 +99,18 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
 
   // `enabled` is instant-save (a switch in the section header); the other
   // fields are batched through the EditorActions cluster at the bottom.
-  const [enabled, setEnabled] = useState(false);
-  useEffect(() => {
-    if (!isLoading) setEnabled(savedConfig.enabled);
-  }, [isLoading, savedConfig]);
+  const { enabled, isToggling, onToggle } = useGovernancePolicyToggle({
+    organizationId,
+    policyType: 'login_policy',
+    savedEnabled: savedConfig.enabled,
+    isLoading,
+    buildConfig: (next): LoginPolicyConfig => ({
+      ...savedConfig,
+      enabled: next,
+    }),
+    failureTitle: t('toastSaveFailedTitle'),
+    failureDescription: t('loginPolicy.saveFailed'),
+  });
 
   const schema = useMemo(
     () =>
@@ -187,36 +191,10 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
     formState: { errors },
   } = editor.form;
   const canEdit = !cannotManage;
-  const isToggling = upsertMutation.isPending;
-
-  const handleToggleEnabled = useCallback(
-    async (next: boolean) => {
-      setEnabled(next);
-      try {
-        await upsertMutation.mutateAsync({
-          organizationId,
-          policyType: 'login_policy',
-          config: {
-            ...savedConfig,
-            enabled: next,
-          } satisfies LoginPolicyConfig,
-        });
-      } catch (err) {
-        console.error('[loginPolicy toggle]', err);
-        setEnabled(!next);
-        toast({
-          title: t('toastSaveFailedTitle'),
-          description: t('loginPolicy.saveFailed'),
-          variant: 'destructive',
-        });
-      }
-    },
-    [organizationId, savedConfig, t, toast, upsertMutation],
-  );
 
   return (
     <Skeletonize loading={isLoading} label={t('loginPolicy.title')}>
-      <PageSection
+      <SettingsSection
         title={t('loginPolicy.title')}
         description={t('loginPolicy.description')}
         action={
@@ -224,8 +202,8 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
             label={t('loginPolicy.enabled')}
             hideLabelOnMobile
             checked={enabled}
-            onCheckedChange={handleToggleEnabled}
-            disabled={!canEdit || isToggling}
+            onCheckedChange={onToggle}
+            disabled={!canEdit || isToggling || editor.isSaving}
           />
         }
       >
@@ -241,7 +219,6 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
                     <Input
                       label={t('loginPolicy.maxAttempts')}
                       type="number"
-                      size="sm"
                       min={1}
                       max={50}
                       step={1}
@@ -257,7 +234,6 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
                     <Input
                       label={t('loginPolicy.backoffSchedule')}
                       placeholder="1, 10, 60, 600"
-                      size="sm"
                       errorMessage={errors.scheduleSeconds?.message}
                       {...register('scheduleSeconds')}
                     />
@@ -270,7 +246,6 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
                     <Input
                       label={t('loginPolicy.trustedProxies')}
                       placeholder="loopback, uniquelocal, 10.0.0.0/8"
-                      size="sm"
                       errorMessage={errors.trustedProxies?.message}
                       {...register('trustedProxies')}
                     />
@@ -288,13 +263,14 @@ export function LoginPolicyEditor({ organizationId }: LoginPolicyEditorProps) {
                     formId={FORM_ID}
                     canEdit={canEdit}
                     entityKind="governance_login_policy"
+                    suppressServerErrorToast
                   />
                 </HStack>
               )}
             </Stack>
           </fieldset>
         </form>
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/model-access-editor.tsx b/services/platform/app/features/settings/governance/components/model-access-editor.tsx
index b8a7aab247..dfd6d409b3 100644
--- a/services/platform/app/features/settings/governance/components/model-access-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/model-access-editor.tsx
@@ -1,8 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { Grid, HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -29,6 +28,7 @@ import {
   type ModelInfoCapabilities,
   ModelInfoPopover,
 } from '@/app/features/chat/components/model-info-popover';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useMembers } from '@/app/features/settings/organization/hooks/queries';
 import {
   useListProviders,
@@ -213,7 +213,7 @@ function RuleDialog({
       className="sm:max-w-2xl"
     >
       <Stack gap={4}>
-        <div className="flex flex-wrap gap-3 *:min-w-[10rem] *:flex-1">
+        <Row gap={3} align="stretch" wrap className="*:min-w-[10rem] *:flex-1">
           <Select
             label={t('modelAccess.scope')}
             options={SCOPE_OPTIONS}
@@ -224,7 +224,6 @@ function RuleDialog({
               }
             }}
             disabled={cannotManage}
-            size="sm"
           />
 
           {draft.scope === 'role' && (
@@ -234,7 +233,6 @@ function RuleDialog({
               value={draft.scopeId ?? ''}
               onValueChange={(value) => updateDraft({ scopeId: value })}
               disabled={cannotManage}
-              size="sm"
             />
           )}
 
@@ -243,7 +241,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('modelAccess.user')}
                 placeholder={t('modelAccess.selectUser')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -260,7 +257,6 @@ function RuleDialog({
               <SearchableSelect
                 label={t('modelAccess.team')}
                 placeholder={t('modelAccess.selectTeam')}
-                size="sm"
                 disabled={cannotManage}
                 value={draft.scopeId ?? null}
                 onValueChange={(value) => updateDraft({ scopeId: value })}
@@ -271,7 +267,7 @@ function RuleDialog({
               />
             </div>
           )}
-        </div>
+        </Row>
 
         <CheckboxGroup
           label={
@@ -281,7 +277,7 @@ function RuleDialog({
           }
           disabled={cannotManage}
         >
-          <div className="grid grid-cols-2 gap-2">
+          <Grid cols={2} gap={2}>
             {allModelOptions.map((option) => {
               const selected =
                 mode === 'allowlist'
@@ -299,10 +295,7 @@ function RuleDialog({
                 }
               };
               return (
-                <div
-                  key={option.value}
-                  className="flex items-start justify-between gap-1"
-                >
+                <Row key={option.value} gap={1} align="start" justify="between">
                   <Checkbox
                     label={option.label}
                     checked={checked}
@@ -314,10 +307,10 @@ function RuleDialog({
                     capabilities={modelCapabilities.get(option.value)}
                     organizationId={organizationId}
                   />
-                </div>
+                </Row>
               );
             })}
-          </div>
+          </Grid>
         </CheckboxGroup>
       </Stack>
     </FormDialog>
@@ -594,7 +587,7 @@ export function ModelAccessEditor({ organizationId }: ModelAccessEditorProps) {
 
   return (
     <Skeletonize loading={loading} label={t('modelAccess.title')}>
-      <PageSection
+      <SettingsSection
         title={t('modelAccess.title')}
         description={t('modelAccess.description')}
         action={
@@ -620,14 +613,12 @@ export function ModelAccessEditor({ organizationId }: ModelAccessEditorProps) {
                     value={mode}
                     onValueChange={handleModeChange}
                     disabled={cannotManage || isPending}
-                    size="sm"
                     aria-label={t('modelAccess.mode')}
                   />
                 </div>
               </HStack>
               <Button
                 variant="primary"
-                size="sm"
                 onClick={openAddDialog}
                 disabled={cannotManage}
               >
@@ -705,7 +696,7 @@ export function ModelAccessEditor({ organizationId }: ModelAccessEditorProps) {
                               size="icon"
                               onClick={() => openEditDialog(index)}
                               disabled={cannotManage}
-                              aria-label={t('modelAccess.editRule')}
+                              title={t('modelAccess.editRule')}
                             >
                               <Pencil className="size-4" />
                             </Button>
@@ -714,7 +705,7 @@ export function ModelAccessEditor({ organizationId }: ModelAccessEditorProps) {
                               size="icon"
                               onClick={() => setDeletingIndex(index)}
                               disabled={cannotManage}
-                              aria-label={t('modelAccess.deleteRule')}
+                              title={t('modelAccess.deleteRule')}
                             >
                               <Trash2 className="size-4" />
                             </Button>
@@ -802,7 +793,7 @@ export function ModelAccessEditor({ organizationId }: ModelAccessEditorProps) {
             }
           }}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-api-key-panel.tsx b/services/platform/app/features/settings/governance/components/moderation-api-key-panel.tsx
index a0bad23385..92be205874 100644
--- a/services/platform/app/features/settings/governance/components/moderation-api-key-panel.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-api-key-panel.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { FormSection } from '@/app/components/ui/forms/form-section';
@@ -50,7 +51,7 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
       })}
     >
       {editing ? (
-        <div className="flex flex-col gap-2">
+        <Stack gap={2}>
           <Input
             type="password"
             value={draft}
@@ -59,10 +60,9 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
             placeholder={t('moderationProvider.apiKeyPlaceholder')}
             autoFocus
           />
-          <div className="flex gap-2">
+          <Row gap={2} align="stretch">
             <Button
               variant="primary"
-              size="sm"
               disabled={
                 disabled || saveSecret.isPending || draft.trim().length === 0
               }
@@ -72,7 +72,6 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
             </Button>
             <Button
               variant="ghost"
-              size="sm"
               disabled={saveSecret.isPending}
               onClick={() => {
                 setEditing(false);
@@ -81,10 +80,10 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
             >
               {tCommon('actions.cancel')}
             </Button>
-          </div>
-        </div>
+          </Row>
+        </Stack>
       ) : (
-        <div className="flex items-center gap-3">
+        <Row gap={3}>
           <code className="text-muted-foreground bg-muted rounded px-2 py-1 text-xs">
             {isLoading
               ? t('moderationProvider.apiKeyLoading')
@@ -94,7 +93,6 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
           </code>
           <Button
             variant="secondary"
-            size="sm"
             disabled={disabled}
             onClick={() => setEditing(true)}
           >
@@ -102,7 +100,7 @@ export function ApiKeyPanel({ organizationId, disabled }: ApiKeyPanelProps) {
               ? t('moderationProvider.replaceKey')
               : t('moderationProvider.setKey')}
           </Button>
-        </div>
+        </Row>
       )}
     </FormSection>
   );
diff --git a/services/platform/app/features/settings/governance/components/moderation-custom-json-path-section.tsx b/services/platform/app/features/settings/governance/components/moderation-custom-json-path-section.tsx
index 703672cb7f..94d06da29e 100644
--- a/services/platform/app/features/settings/governance/components/moderation-custom-json-path-section.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-custom-json-path-section.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { FormSection } from '@/app/components/ui/forms/form-section';
@@ -82,7 +83,7 @@ export function CustomJsonPathSection({
       label={t('moderationProvider.parseResponseLabel')}
       description={t('moderationProvider.parseResponseDescription')}
     >
-      <div className="flex flex-col gap-4">
+      <Stack>
         <div>
           <p className="text-sm font-medium">
             {t('moderationProvider.shapeStepTitle')}
@@ -178,7 +179,7 @@ export function CustomJsonPathSection({
             />
           </div>
         )}
-      </div>
+      </Stack>
     </FormSection>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-endpoint-edit-dialog.tsx b/services/platform/app/features/settings/governance/components/moderation-endpoint-edit-dialog.tsx
index 9866851737..80692807a6 100644
--- a/services/platform/app/features/settings/governance/components/moderation-endpoint-edit-dialog.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-endpoint-edit-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Plus, Trash2 } from 'lucide-react';
 import { useEffect, useState } from 'react';
 
@@ -107,7 +108,7 @@ export function EndpointEditDialog({
         </>
       }
     >
-      <div className="flex flex-col gap-4">
+      <Stack>
         <FormSection
           label={t('moderationProvider.endpointUrlField')}
           description={t('moderationProvider.endpointUrlFieldDescription')}
@@ -120,9 +121,9 @@ export function EndpointEditDialog({
         </FormSection>
 
         <FormSection label={t('moderationProvider.headersTitle')}>
-          <div className="flex flex-col gap-2">
+          <Stack gap={2}>
             {draft.headers.map((header, index) => (
-              <div key={index} className="flex gap-2">
+              <Row key={index} gap={2} align="stretch">
                 <Input
                   aria-label={t('moderationProvider.headerNameAria')}
                   value={header.key}
@@ -141,23 +142,17 @@ export function EndpointEditDialog({
                 />
                 <Button
                   variant="ghost"
-                  size="sm"
                   aria-label={t('moderationProvider.removeHeaderAria')}
                   onClick={() => removeHeader(index)}
                 >
                   <Trash2 className="size-4" />
                 </Button>
-              </div>
+              </Row>
             ))}
-            <Button
-              variant="secondary"
-              size="sm"
-              icon={Plus}
-              onClick={addHeader}
-            >
+            <Button variant="secondary" icon={Plus} onClick={addHeader}>
               {t('moderationProvider.addHeader')}
             </Button>
-          </div>
+          </Stack>
         </FormSection>
 
         <FormSection
@@ -195,7 +190,7 @@ export function EndpointEditDialog({
             footer — the scrollbar already takes the overflow, this is
             just visual breathing room. */}
         <div className="pb-2" />
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-endpoint-summary.tsx b/services/platform/app/features/settings/governance/components/moderation-endpoint-summary.tsx
index eb68e82e98..6b629cce3d 100644
--- a/services/platform/app/features/settings/governance/components/moderation-endpoint-summary.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-endpoint-summary.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Pencil } from 'lucide-react';
 
 import { useT } from '@/lib/i18n/client';
@@ -23,9 +24,13 @@ export function EndpointSummary({
   const { t } = useT('governance');
   const { t: tCommon } = useT('common');
   return (
-    <div className="border-border flex items-start justify-between gap-4 rounded-lg border p-4">
+    <Row
+      align="start"
+      justify="between"
+      className="border-border rounded-lg border p-4"
+    >
       <dl className="min-w-0 flex-1 space-y-1 text-sm">
-        <div className="flex gap-2">
+        <Row gap={2} align="stretch">
           <dt className="text-muted-foreground w-36 shrink-0">
             {t('moderationProvider.endpointUrlLabel')}
           </dt>
@@ -36,31 +41,30 @@ export function EndpointSummary({
               </span>
             )}
           </dd>
-        </div>
-        <div className="flex gap-2">
+        </Row>
+        <Row gap={2} align="stretch">
           <dt className="text-muted-foreground w-36 shrink-0">
             {t('moderationProvider.endpointHeadersLabel')}
           </dt>
           <dd>{headersCount}</dd>
-        </div>
-        <div className="flex gap-2">
+        </Row>
+        <Row gap={2} align="stretch">
           <dt className="text-muted-foreground w-36 shrink-0">
             {t('moderationProvider.endpointTimeoutLabel')}
           </dt>
           <dd>
             {t('moderationProvider.endpointTimeoutValue', { ms: timeoutMs })}
           </dd>
-        </div>
+        </Row>
       </dl>
       <Button
         variant="secondary"
-        size="sm"
         icon={Pencil}
         disabled={disabled}
         onClick={onEdit}
       >
         {tCommon('actions.edit')}
       </Button>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-mapping-edit-dialog.tsx b/services/platform/app/features/settings/governance/components/moderation-mapping-edit-dialog.tsx
index 66c38a3fe8..66c77fdedf 100644
--- a/services/platform/app/features/settings/governance/components/moderation-mapping-edit-dialog.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-mapping-edit-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { Dialog } from '@/app/components/ui/dialog/dialog';
@@ -104,7 +105,7 @@ export function MappingEditDialog({
         </>
       }
     >
-      <div className="flex flex-col gap-4">
+      <Stack>
         <FormSection
           label={t('moderationProvider.providerCategoryLabel')}
           description={t('moderationProvider.providerCategoryDescription')}
@@ -166,7 +167,7 @@ export function MappingEditDialog({
         <FormSection label={t('moderationProvider.enabled')}>
           <Switch checked={enabled} onCheckedChange={setEnabled} />
         </FormSection>
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-mapping-list.tsx b/services/platform/app/features/settings/governance/components/moderation-mapping-list.tsx
index 8d4fe8fe45..e3f279c3b9 100644
--- a/services/platform/app/features/settings/governance/components/moderation-mapping-list.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-mapping-list.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import {
   Table,
   TableBody,
@@ -31,7 +32,7 @@ export function MappingList({
   const { t } = useT('governance');
   const { t: tCommon } = useT('common');
   return (
-    <div className="flex flex-col gap-2">
+    <Stack gap={2}>
       {mappings.length === 0 ? (
         <div className="text-muted-foreground text-sm">
           {t('moderationProvider.mappingsEmpty')}
@@ -80,7 +81,6 @@ export function MappingList({
                 <TableCell className="text-right">
                   <Button
                     variant="ghost"
-                    size="sm"
                     icon={Pencil}
                     disabled={disabled}
                     onClick={() => onEdit(index)}
@@ -96,7 +96,6 @@ export function MappingList({
       <div>
         <Button
           variant="secondary"
-          size="sm"
           icon={Plus}
           disabled={disabled}
           onClick={onAdd}
@@ -104,6 +103,6 @@ export function MappingList({
           {t('moderationProvider.addMapping')}
         </Button>
       </div>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-provider-config.tsx b/services/platform/app/features/settings/governance/components/moderation-provider-config.tsx
index 5514c78c1c..7e023c93c3 100644
--- a/services/platform/app/features/settings/governance/components/moderation-provider-config.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-provider-config.tsx
@@ -2,7 +2,7 @@
 
 import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { useCallback, useMemo, useRef, useState } from 'react';
 
@@ -10,6 +10,7 @@ import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
 import { FormSection } from '@/app/components/ui/forms/form-section';
 import { Select } from '@/app/components/ui/forms/select';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -88,7 +89,7 @@ function deriveDraft(policy: ModerationPolicy): ModerationDraft {
 // Container — owns data fetching, local edit state, save/toast wiring, and the
 // loading state. Wraps the plain `ModerationProviderConfigForm` in
 // `<Skeletonize>` so the same tree renders the skeleton (the hand-rolled
-// loading `PageSection` with magic-height `Skeleton` boxes is gone — the
+// loading `SettingsSection` with magic-height `Skeleton` boxes is gone — the
 // skeleton-aware `<Switch>` masks itself to its real track height).
 //
 // All draft fields are seeded LAZILY from the (possibly already-warm) policy so
@@ -462,7 +463,7 @@ export function ModerationProviderConfigView({
 
   return (
     <Skeletonize loading={isLoading} label={t('moderationProvider.title')}>
-      <PageSection
+      <SettingsSection
         title={t('moderationProvider.title')}
         description={t('moderationProvider.description', {
           secretPlaceholder: '{{secret}}',
@@ -486,7 +487,7 @@ export function ModerationProviderConfigView({
         {enabled && (
           <>
             <FormSection label={t('moderationProvider.applyTo')}>
-              <div className="flex flex-col gap-2">
+              <Stack gap={2}>
                 <label className="flex items-center gap-2">
                   <input
                     type="checkbox"
@@ -505,14 +506,14 @@ export function ModerationProviderConfigView({
                   />
                   <span>{t('moderationProvider.modelOutput')}</span>
                 </label>
-              </div>
+              </Stack>
             </FormSection>
 
             <FormSection
               label={t('moderationProvider.failBehavior')}
               description={t('moderationProvider.failBehaviorDescription')}
             >
-              <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+              <Grid sm={2} gap={3}>
                 <div>
                   <div className="text-muted-foreground mb-1 text-xs">
                     {t('moderationProvider.input')}
@@ -559,14 +560,14 @@ export function ModerationProviderConfigView({
                     ]}
                   />
                 </div>
-              </div>
+              </Grid>
             </FormSection>
 
             <FormSection
               label={t('moderationProvider.provider')}
               description={t('moderationProvider.providerDescription')}
             >
-              <div className="flex flex-wrap gap-2">
+              <Row gap={2} align="stretch" wrap>
                 {MODERATION_PRESETS.map((preset) => {
                   const active = responseShape === preset.id;
                   const label = active
@@ -598,7 +599,7 @@ export function ModerationProviderConfigView({
                     ? `✓ ${t('moderationProvider.presetCustomJsonPathActive')}`
                     : t('moderationProvider.presetCustomJsonPath')}
                 </Button>
-              </div>
+              </Row>
               {responseShape === 'custom_jsonpath' &&
                 !customCategoriesPath.trim() && (
                   <p className="mt-2 text-xs text-amber-600">
@@ -702,7 +703,7 @@ export function ModerationProviderConfigView({
             />
           </>
         )}
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/moderation-test-connection-panel.tsx b/services/platform/app/features/settings/governance/components/moderation-test-connection-panel.tsx
index ca19e86a74..270b2592b4 100644
--- a/services/platform/app/features/settings/governance/components/moderation-test-connection-panel.tsx
+++ b/services/platform/app/features/settings/governance/components/moderation-test-connection-panel.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { useState } from 'react';
 
 import { FormSection } from '@/app/components/ui/forms/form-section';
@@ -48,7 +49,7 @@ export function TestConnectionPanel({
       label={t('moderationProvider.testConnection')}
       description={t('moderationProvider.testConnectionDescription')}
     >
-      <div className="flex flex-col gap-3">
+      <Stack gap={3}>
         <Textarea
           value={text}
           onChange={(e) => setText(e.target.value)}
@@ -59,7 +60,6 @@ export function TestConnectionPanel({
         <div>
           <Button
             variant="secondary"
-            size="sm"
             onClick={() => void runTest()}
             disabled={
               disabled || testMutation.isPending || text.trim().length === 0
@@ -71,7 +71,7 @@ export function TestConnectionPanel({
           </Button>
         </div>
         {result && <TestResultView result={result} />}
-      </div>
+      </Stack>
     </FormSection>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/password-policy-editor.tsx b/services/platform/app/features/settings/governance/components/password-policy-editor.tsx
index 8c5e2a0bf1..0966325085 100644
--- a/services/platform/app/features/settings/governance/components/password-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/password-policy-editor.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
 import { useCallback, useMemo } from 'react';
@@ -11,6 +10,7 @@ import { EditorActions, useFormEditor } from '@/app/components/ui/editor';
 import { Checkbox } from '@/app/components/ui/forms/checkbox';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -19,8 +19,8 @@ import {
   type PasswordPolicyConfig,
   passwordPolicyConfigSchema,
 } from '@/lib/shared/schemas/governance';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
 
@@ -40,11 +40,10 @@ interface PasswordPolicyForm {
 
 const FORM_ID = 'governance-password-policy-form';
 
-function parseConfig(raw: unknown): PasswordPolicyConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = passwordPolicyConfigSchema.safeParse(obj);
-  return result.success ? result.data : DEFAULT_PASSWORD_POLICY;
-}
+const parseConfig = createConfigParser(
+  passwordPolicyConfigSchema,
+  () => DEFAULT_PASSWORD_POLICY,
+);
 
 // =============================================================================
 // Single editor — owns data fetching, the form controller, save/toast wiring,
@@ -177,7 +176,7 @@ export function PasswordPolicyEditor({
 
   return (
     <Skeletonize loading={isLoading} label={t('passwordPolicy.title')}>
-      <PageSection
+      <SettingsSection
         title={t('passwordPolicy.title')}
         description={t('passwordPolicy.description')}
       >
@@ -192,7 +191,6 @@ export function PasswordPolicyEditor({
                   <Input
                     label={t('passwordPolicy.minLength')}
                     type="number"
-                    size="sm"
                     min={6}
                     max={128}
                     step={1}
@@ -248,7 +246,6 @@ export function PasswordPolicyEditor({
                     <Input
                       label={t('passwordPolicy.rotationDays')}
                       type="number"
-                      size="sm"
                       min={1}
                       max={3650}
                       step={1}
@@ -268,12 +265,13 @@ export function PasswordPolicyEditor({
                   formId={FORM_ID}
                   canEdit={canEdit}
                   entityKind="governance_password_policy"
+                  suppressServerErrorToast
                 />
               </HStack>
             </Stack>
           </fieldset>
         </form>
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/personalization-policy-editor.tsx b/services/platform/app/features/settings/governance/components/personalization-policy-editor.tsx
index 0886218fc2..71d02e2bbd 100644
--- a/services/platform/app/features/settings/governance/components/personalization-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/personalization-policy-editor.tsx
@@ -1,10 +1,10 @@
 'use client';
 
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -28,7 +28,7 @@ function readEnabled(raw: unknown): boolean {
 
 // =============================================================================
 // Single toggle — owns data fetching, the local toggle state, save/toast
-// wiring, and the loading state. Renders the REAL `PageSection` +
+// wiring, and the loading state. Renders the REAL `SettingsSection` +
 // skeleton-aware `Switch` once, always, wrapped in `<Skeletonize>`. The
 // skeleton-aware `<Switch>` masks itself to its exact track size while loading.
 // =============================================================================
@@ -85,7 +85,7 @@ function PersonalizationPolicyToggle({
 
   return (
     <Skeletonize loading={isLoading} label={t(titleKey)}>
-      <PageSection
+      <SettingsSection
         title={t(titleKey)}
         description={t(descriptionKey)}
         action={
diff --git a/services/platform/app/features/settings/governance/components/pii-config.tsx b/services/platform/app/features/settings/governance/components/pii-config.tsx
index a4e1bc5a30..82b733806e 100644
--- a/services/platform/app/features/settings/governance/components/pii-config.tsx
+++ b/services/platform/app/features/settings/governance/components/pii-config.tsx
@@ -1,12 +1,12 @@
 'use client';
 
-import { PageSection } from '@tale/ui/page-section';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { lazy, useCallback, useRef, useState } from 'react';
 
 import { SuspenseBoundary } from '@/app/components/error-boundaries/core/suspense-boundary';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -145,7 +145,7 @@ export function PiiConfig({ organizationId }: PiiConfigProps) {
 
   return (
     <Skeletonize loading={isLoading} label={t('pii.title')}>
-      <PageSection
+      <SettingsSection
         title={t('pii.title')}
         description={t('pii.description')}
         action={
@@ -177,7 +177,7 @@ export function PiiConfig({ organizationId }: PiiConfigProps) {
             />
           </SuspenseBoundary>
         )}
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/pii/pii-config-panel.tsx b/services/platform/app/features/settings/governance/components/pii/pii-config-panel.tsx
index 821c0bd8c6..a177832b87 100644
--- a/services/platform/app/features/settings/governance/components/pii/pii-config-panel.tsx
+++ b/services/platform/app/features/settings/governance/components/pii/pii-config-panel.tsx
@@ -33,6 +33,7 @@ import { Button } from '@tale/ui/button';
 import { Checkbox } from '@tale/ui/checkbox';
 import { Field } from '@tale/ui/field';
 import { Input } from '@tale/ui/input';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import type { TFunction } from 'i18next';
 import { Plus, Trash2 } from 'lucide-react';
 import { lazy, Suspense, useMemo, useState, type ReactNode } from 'react';
@@ -162,8 +163,8 @@ interface SectionProps {
 
 function Section({ title, description, children }: SectionProps): ReactNode {
   return (
-    <section className="flex flex-col gap-3">
-      <header className="flex flex-col gap-1">
+    <Stack as="section" gap={3}>
+      <Stack as="header" gap={1}>
         <h3 className="text-sm font-semibold text-[color:var(--color-fg-base)]">
           {title}
         </h3>
@@ -172,9 +173,9 @@ function Section({ title, description, children }: SectionProps): ReactNode {
             {description}
           </p>
         )}
-      </header>
+      </Stack>
       {children}
-    </section>
+    </Stack>
   );
 }
 
@@ -299,7 +300,7 @@ function PatternsSection({
       title={tPiiConfigPanel('patternsTitle')}
       description={tPiiConfigPanel('patternsDescription')}
     >
-      <ul className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+      <Grid as="ul" sm={2} gap={2}>
         {BUILT_IN_PATTERN_NAMES.map((name) => {
           const Icon = piiTypeIcon(name);
           const id = `pii-pattern-${name}`;
@@ -333,7 +334,7 @@ function PatternsSection({
             </li>
           );
         })}
-      </ul>
+      </Grid>
     </Section>
   );
 }
@@ -418,13 +419,15 @@ function CustomPatternsSection({
       title={tPiiConfigPanel('customPatternsTitle')}
       description={tPiiConfigPanel('customPatternsDescription')}
     >
-      <div className="flex flex-col gap-2">
+      <Stack gap={2}>
         {value.customPatterns.map((p, index) => (
-          <div
+          <Row
             key={`${p.name}-${index}`}
-            className="flex items-center justify-between gap-3 rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)] px-3 py-2"
+            gap={3}
+            justify="between"
+            className="rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)] px-3 py-2"
           >
-            <div className="flex min-w-0 flex-col">
+            <Stack gap={0} className="min-w-0">
               <span className="truncate text-sm font-medium text-[color:var(--color-fg-base)]">
                 {p.name}
               </span>
@@ -433,7 +436,7 @@ function CustomPatternsSection({
                 <span aria-hidden>→</span>
                 <span className="font-mono">{p.replacement}</span>
               </div>
-            </div>
+            </Stack>
             <Button
               type="button"
               variant="ghost"
@@ -441,13 +444,16 @@ function CustomPatternsSection({
               icon={Trash2}
               disabled={disabled}
               onClick={() => removePattern(index)}
-              aria-label={`${tPiiConfigPanel('removeCustomPattern')} — ${p.name}`}
+              title={`${tPiiConfigPanel('removeCustomPattern')} — ${p.name}`}
             />
-          </div>
+          </Row>
         ))}
 
         {draft && (
-          <div className="flex flex-col gap-3 rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)] p-3">
+          <Stack
+            gap={3}
+            className="rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)] p-3"
+          >
             <Field label={tPiiConfigPanel('customPatternNameLabel')}>
               <Input
                 value={draft.name}
@@ -479,10 +485,9 @@ function CustomPatternsSection({
                 className="font-mono"
               />
             </Field>
-            <div className="flex gap-2">
+            <Row gap={2} align="stretch">
               <Button
                 type="button"
-                size="sm"
                 disabled={disabled || !canSave}
                 onClick={saveDraft}
               >
@@ -490,21 +495,19 @@ function CustomPatternsSection({
               </Button>
               <Button
                 type="button"
-                size="sm"
                 variant="secondary"
                 onClick={() => setDraft(null)}
               >
                 {tPiiConfigPanel('cancelCustomPattern')}
               </Button>
-            </div>
-          </div>
+            </Row>
+          </Stack>
         )}
 
         {!draft && (
           <Button
             type="button"
             variant="secondary"
-            size="sm"
             icon={Plus}
             disabled={disabled}
             onClick={() => setDraft({ name: '', regex: '', replacement: '' })}
@@ -513,7 +516,7 @@ function CustomPatternsSection({
             {tPiiConfigPanel('addCustomPattern')}
           </Button>
         )}
-      </div>
+      </Stack>
     </Section>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/pii/pii-config-preview.tsx b/services/platform/app/features/settings/governance/components/pii/pii-config-preview.tsx
index 56c9f4f12f..d89dc7ecfa 100644
--- a/services/platform/app/features/settings/governance/components/pii/pii-config-preview.tsx
+++ b/services/platform/app/features/settings/governance/components/pii/pii-config-preview.tsx
@@ -13,6 +13,7 @@
  * in via `React.lazy(() => import('./pii-config-preview'))`.
  */
 
+import { Row, Stack } from '@tale/ui/layout';
 import type { TFunction } from 'i18next';
 import { ShieldAlert, ShieldCheck, ShieldX } from 'lucide-react';
 import { useEffect, useMemo, useState, type ReactNode } from 'react';
@@ -103,7 +104,10 @@ export function PiiConfigPreview({
     config.enabledPatterns.length > 0 || config.customPatterns.length > 0;
 
   return (
-    <div className="flex flex-col gap-6 rounded-lg border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)]/40 p-4">
+    <Stack
+      gap={6}
+      className="rounded-lg border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-elevated)]/40 p-4"
+    >
       <Stage
         step={1}
         title={tPiiConfigPanel('inputTitle')}
@@ -168,7 +172,7 @@ export function PiiConfigPreview({
           tPiiConfigPanel={tPiiConfigPanel}
         />
       )}
-    </div>
+    </Stack>
   );
 }
 
@@ -182,13 +186,15 @@ function NoPatternsNotice({
   tPiiConfigPanel: TFunction;
 }): ReactNode {
   return (
-    <div
+    <Row
       role="status"
-      className="flex items-start gap-2 rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-base)] p-3 text-xs text-[color:var(--color-fg-muted)]"
+      gap={2}
+      align="start"
+      className="rounded-md border border-[color:var(--color-border-base)] bg-[color:var(--color-bg-base)] p-3 text-xs text-[color:var(--color-fg-muted)]"
     >
       <ShieldAlert className="mt-0.5 size-4 shrink-0 opacity-60" aria-hidden />
       <span>{tPiiConfigPanel('noPatternsEnabled')}</span>
-    </div>
+    </Row>
   );
 }
 
@@ -205,8 +211,8 @@ interface StageProps {
 
 function Stage({ step, title, hint, children }: StageProps): ReactNode {
   return (
-    <section className="flex flex-col gap-2">
-      <header className="flex items-baseline gap-3">
+    <Stack as="section" gap={2}>
+      <Row as="header" gap={3} align="baseline">
         <span
           aria-hidden
           className="flex h-6 w-6 items-center justify-center rounded-full bg-[color:var(--color-accent-base)] text-xs font-medium text-[color:var(--color-accent-fg)]"
@@ -221,9 +227,11 @@ function Stage({ step, title, hint, children }: StageProps): ReactNode {
             {hint}
           </span>
         )}
-      </header>
-      <div className="ml-9 flex flex-col gap-2">{children}</div>
-    </section>
+      </Row>
+      <Stack gap={2} className="ml-9">
+        {children}
+      </Stack>
+    </Stack>
   );
 }
 
@@ -396,31 +404,35 @@ function BlockNotice({
 }: BlockNoticeProps): ReactNode {
   if (!blocked) {
     return (
-      <div
+      <Row
         role="status"
         aria-live="polite"
-        className="flex items-start gap-2 rounded-md border border-[color:var(--color-success-base)]/40 bg-[color:var(--color-success-base)]/10 p-3 text-sm text-[color:var(--color-success-fg)]"
+        gap={2}
+        align="start"
+        className="rounded-md border border-[color:var(--color-success-base)]/40 bg-[color:var(--color-success-base)]/10 p-3 text-sm text-[color:var(--color-success-fg)]"
       >
         <ShieldCheck className="mt-0.5 size-4 shrink-0" aria-hidden />
         <span>{tPiiConfigPanel('blockPassBody')}</span>
-      </div>
+      </Row>
     );
   }
   return (
-    <div
+    <Row
       role="alert"
       aria-live="assertive"
-      className="flex items-start gap-2 rounded-md border border-[color:var(--color-danger)]/40 bg-[color:var(--color-danger)]/10 p-3 text-sm text-[color:var(--color-danger)]"
+      gap={2}
+      align="start"
+      className="rounded-md border border-[color:var(--color-danger)]/40 bg-[color:var(--color-danger)]/10 p-3 text-sm text-[color:var(--color-danger)]"
     >
       <ShieldX className="mt-0.5 size-4 shrink-0" aria-hidden />
-      <div className="flex flex-col gap-1">
+      <Stack gap={1}>
         <span>{tPiiConfigPanel('blockBody')}</span>
         <span className="text-xs opacity-80">
           {categories.join(', ')} · {matchCount}{' '}
           {tPiiConfigPanel('detectionCount')}
         </span>
-      </div>
-    </div>
+      </Stack>
+    </Row>
   );
 }
 
@@ -441,10 +453,10 @@ function DetectionSummary({
   }
   if (byType.size === 0) {
     return (
-      <div className="flex items-center gap-2 text-xs text-[color:var(--color-fg-muted)]">
+      <Row gap={2} className="text-xs text-[color:var(--color-fg-muted)]">
         <ShieldAlert className="size-3.5 shrink-0 opacity-60" aria-hidden />
         <span>{tPiiConfigPanel('noPii')}</span>
-      </div>
+      </Row>
     );
   }
   return (
diff --git a/services/platform/app/features/settings/governance/components/retention-bounds-proposal-banner.tsx b/services/platform/app/features/settings/governance/components/retention-bounds-proposal-banner.tsx
index b5d7cbfeb5..7169de46b7 100644
--- a/services/platform/app/features/settings/governance/components/retention-bounds-proposal-banner.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-bounds-proposal-banner.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Loader2, ShieldAlert } from 'lucide-react';
 import { lazy, Suspense, useState } from 'react';
@@ -114,10 +115,10 @@ export function RetentionBoundsProposalBanner({ organizationId }: Props) {
   const inFlight = apply.isPending || reject.isPending;
 
   return (
-    <div className="border-warning bg-warning/10 flex flex-col gap-3 rounded border p-3">
-      <div className="flex items-start gap-3">
+    <Stack gap={3} className="border-warning bg-warning/10 rounded border p-3">
+      <Row gap={3} align="start">
         <ShieldAlert className="text-warning mt-0.5 h-4 w-4 shrink-0" />
-        <div className="flex flex-1 flex-col gap-1">
+        <Stack gap={1} className="flex-1">
           <Text className="text-sm font-medium">
             {t(titleKey, titleFallback)}
           </Text>
@@ -138,16 +139,11 @@ export function RetentionBoundsProposalBanner({ organizationId }: Props) {
            * it the operator is asked to approve a black-box change.
            * Round-2 / M10.
            */}
-        </div>
-      </div>
-
-      <div className="ml-7 flex flex-wrap gap-2">
-        <Button
-          variant="primary"
-          size="sm"
-          onClick={handleApply}
-          disabled={inFlight}
-        >
+        </Stack>
+      </Row>
+
+      <Row gap={2} align="stretch" wrap className="ml-7">
+        <Button variant="primary" onClick={handleApply} disabled={inFlight}>
           {apply.isPending ? (
             <>
               <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
@@ -160,7 +156,6 @@ export function RetentionBoundsProposalBanner({ organizationId }: Props) {
         {!firstApply && (
           <Button
             variant="secondary"
-            size="sm"
             onClick={handleReject}
             disabled={inFlight}
           >
@@ -180,14 +175,13 @@ export function RetentionBoundsProposalBanner({ organizationId }: Props) {
         {hasDetails && (
           <Button
             variant="ghost"
-            size="sm"
             onClick={() => setDrawerOpen(true)}
             disabled={inFlight}
           >
             {t('retentionPolicy.boundsProposal.detailsLabel', 'View details')}
           </Button>
         )}
-      </div>
+      </Row>
 
       {drawerOpen && (
         <Suspense fallback={null}>
@@ -199,6 +193,6 @@ export function RetentionBoundsProposalBanner({ organizationId }: Props) {
           />
         </Suspense>
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/retention-edit-drawer.tsx b/services/platform/app/features/settings/governance/components/retention-edit-drawer.tsx
index fd0464673d..8fa763f92a 100644
--- a/services/platform/app/features/settings/governance/components/retention-edit-drawer.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-edit-drawer.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useCallback, useState, type ReactNode } from 'react';
 
@@ -178,7 +179,7 @@ function RetentionEditFormBody({
   );
 
   return (
-    <div className="flex h-full flex-col">
+    <Stack gap={0} className="h-full">
       <div className="shrink-0 pr-10">
         <h2 className="text-lg font-semibold tracking-tight">
           {t('retentionPolicy.drawer.title', 'Edit retention policy')}
@@ -192,7 +193,7 @@ function RetentionEditFormBody({
       </div>
 
       <div className="-mx-6 min-h-0 flex-1 overflow-y-auto px-6 py-4">
-        <div className="flex flex-col gap-6">
+        <Stack gap={6}>
           <RetentionForm
             value={config}
             onChange={setConfig}
@@ -218,7 +219,6 @@ function RetentionEditFormBody({
                 }))
               }
               disabled={inputDisabled}
-              size="sm"
               min={0}
               max={90}
               description={t(
@@ -227,32 +227,30 @@ function RetentionEditFormBody({
               )}
             />
           </div>
-        </div>
+        </Stack>
       </div>
 
-      <div className="flex shrink-0 items-center justify-between gap-2 border-t pt-4">
+      <Row gap={2} justify="between" className="shrink-0 border-t pt-4">
         <Button
           variant="secondary"
-          size="sm"
           disabled={inputDisabled}
           onClick={handleResetToDefaults}
         >
           {t('retentionPolicy.reset', 'Reset to defaults')}
         </Button>
-        <div className="flex gap-2">
-          <Button variant="ghost" size="sm" onClick={onClose}>
+        <Row gap={2} align="stretch">
+          <Button variant="ghost" onClick={onClose}>
             {tCommon('actions.cancel')}
           </Button>
           <Button
             variant="primary"
-            size="sm"
             disabled={!dirty || inputDisabled}
             onClick={() => setConfirmOpen(true)}
           >
             {t('retentionPolicy.save', 'Save changes')}
           </Button>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       <ConfirmDialog
         open={confirmOpen}
@@ -271,7 +269,7 @@ function RetentionEditFormBody({
       >
         <DiffList from={savedConfig} to={config} bounds={bounds} />
       </ConfirmDialog>
-    </div>
+    </Stack>
   );
 }
 
@@ -301,7 +299,7 @@ function DiffList({
     );
   }
   return (
-    <ul className="flex max-h-64 flex-col gap-1 overflow-y-auto text-sm">
+    <Stack as="ul" gap={1} className="max-h-64 overflow-y-auto text-sm">
       {entries.map((e) => (
         <li
           key={`${e.id}.${e.fromText}-${e.toText}`}
@@ -315,7 +313,7 @@ function DiffList({
           </span>
         </li>
       ))}
-    </ul>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/settings/governance/components/retention-editor.tsx b/services/platform/app/features/settings/governance/components/retention-editor.tsx
index 9513c4577e..c9883a6ed0 100644
--- a/services/platform/app/features/settings/governance/components/retention-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-editor.tsx
@@ -1,12 +1,12 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
 import { Pencil } from 'lucide-react';
 import { useMemo, useState } from 'react';
 
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useT } from '@/lib/i18n/client';
 import {
@@ -37,7 +37,7 @@ function parseRetentionConfig(policy: unknown): RetentionPolicyConfig {
 
 // =============================================================================
 // Single editor — owns data fetching (policy + bounds), the drawer open state,
-// and the loading state. Renders the REAL `PageSection` once, always, wrapped
+// and the loading state. Renders the REAL `SettingsSection` once, always, wrapped
 // in `<Skeletonize>` while the policy loads.
 //
 // The conditional banners (`RetentionBoundsProposalBanner`,
@@ -73,7 +73,7 @@ export function RetentionEditor({ organizationId }: RetentionEditorProps) {
       loading={isLoading}
       label={t('retentionPolicy.title', 'Retention policy')}
     >
-      <PageSection
+      <SettingsSection
         title={t('retentionPolicy.title', 'Retention policy')}
         description={t(
           'retentionPolicy.description',
@@ -82,7 +82,6 @@ export function RetentionEditor({ organizationId }: RetentionEditorProps) {
         action={
           <Button
             variant="secondary"
-            size="sm"
             icon={Pencil}
             disabled={cannotManage}
             onClick={() => setDrawerOpen(true)}
@@ -115,7 +114,7 @@ export function RetentionEditor({ organizationId }: RetentionEditorProps) {
           organizationId={organizationId}
           cannotManage={cannotManage}
         />
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/retention-form.tsx b/services/platform/app/features/settings/governance/components/retention-form.tsx
index 85825ce383..a9154f501c 100644
--- a/services/platform/app/features/settings/governance/components/retention-form.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-form.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 
 import { Input } from '@/app/components/ui/forms/input';
@@ -113,9 +113,12 @@ function CategoryRow({
     .join(' ');
 
   return (
-    <div className="border-border/50 flex flex-col gap-3 border-b border-dashed pb-4 last:border-b-0 last:pb-0">
-      <div className="flex items-start justify-between gap-4">
-        <div className="flex flex-col gap-1">
+    <Stack
+      gap={3}
+      className="border-border/50 border-b border-dashed pb-4 last:border-b-0 last:pb-0"
+    >
+      <Row align="start" justify="between">
+        <Stack gap={1}>
           <Text className="text-sm font-medium">{titleText}</Text>
           <Text className="text-muted-foreground text-xs">
             {descriptionText}
@@ -134,7 +137,7 @@ function CategoryRow({
               )}
             </Text>
           )}
-        </div>
+        </Stack>
         {enabledKey ? (
           <Switch
             label={t('retentionPolicy.enabled', 'Enabled')}
@@ -148,7 +151,7 @@ function CategoryRow({
             disabled={inputDisabled}
           />
         ) : null}
-      </div>
+      </Row>
       {enabled && (
         <div className="max-w-xs">
           <Input
@@ -164,13 +167,12 @@ function CategoryRow({
               } as RetentionPolicyConfig)
             }
             disabled={inputDisabled}
-            size="sm"
             errorMessage={error}
             isInvalid={Boolean(error)}
             description={helper && helper.trim() !== '' ? helper : undefined}
           />
         </div>
       )}
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/retention-pending-banner.tsx b/services/platform/app/features/settings/governance/components/retention-pending-banner.tsx
index 488ad0ffbf..be92ca9e38 100644
--- a/services/platform/app/features/settings/governance/components/retention-pending-banner.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-pending-banner.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useAction } from 'convex/react';
 import { Clock } from 'lucide-react';
@@ -42,9 +43,13 @@ export function RetentionPendingBanner({ organizationId }: Props) {
   );
 
   return (
-    <div className="border-warning bg-warning/10 flex items-start gap-3 rounded border p-3">
+    <Row
+      gap={3}
+      align="start"
+      className="border-warning bg-warning/10 rounded border p-3"
+    >
       <Clock className="text-warning mt-0.5 h-4 w-4 shrink-0" />
-      <div className="flex flex-1 flex-col gap-2">
+      <Stack gap={2} className="flex-1">
         <Text className="text-sm font-medium">
           {t(
             'retentionPolicy.pendingChange.title',
@@ -59,10 +64,9 @@ export function RetentionPendingBanner({ organizationId }: Props) {
             { days: daysRemaining },
           )}
         </Text>
-      </div>
+      </Stack>
       <Button
         variant="ghost"
-        size="sm"
         onClick={async () => {
           try {
             await cancel({
@@ -84,6 +88,6 @@ export function RetentionPendingBanner({ organizationId }: Props) {
       >
         {t('retentionPolicy.pendingChange.cancel', 'Cancel')}
       </Button>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/retention-policy-summary.tsx b/services/platform/app/features/settings/governance/components/retention-policy-summary.tsx
index 241e3654f2..7ee8d95767 100644
--- a/services/platform/app/features/settings/governance/components/retention-policy-summary.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-policy-summary.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 
 import { useT } from '@/lib/i18n/client';
@@ -26,7 +27,7 @@ export function RetentionPolicySummary({
   const graceDays = config.deletionGraceDays ?? 30;
 
   return (
-    <div className="border-border flex flex-col gap-4 rounded-lg border p-4">
+    <Stack className="border-border rounded-lg border p-4">
       <dl className="space-y-1 text-sm">
         {WIRE_MAPPING.map((wire) => (
           <SummaryRow
@@ -36,21 +37,21 @@ export function RetentionPolicySummary({
             bounds={bounds}
           />
         ))}
-        <div className="flex gap-2 pt-1">
+        <Row gap={2} align="stretch" className="pt-1">
           <dt className="text-muted-foreground w-44 shrink-0">
             {t('retentionPolicy.deletionGrace.label', 'Grace period (days)')}
           </dt>
           <dd>
             <SkeletonBox>{graceDays}</SkeletonBox>
           </dd>
-        </div>
+        </Row>
       </dl>
       <div className="border-border/50 border-t pt-4">
         <SkeletonBox fullWidth>
           <RetentionTimeline graceDays={graceDays} />
         </SkeletonBox>
       </div>
-    </div>
+    </Stack>
   );
 }
 
@@ -74,7 +75,7 @@ function SummaryRow({ wire, config, bounds }: SummaryRowProps) {
   const unit = bounds.get(id)?.unit ?? unitForCategory(id);
 
   return (
-    <div className="flex gap-2">
+    <Row gap={2} align="stretch">
       <dt className="text-muted-foreground w-44 shrink-0">{titleText}</dt>
       <dd>
         <SkeletonBox>
@@ -89,6 +90,6 @@ function SummaryRow({ wire, config, bounds }: SummaryRowProps) {
           )}
         </SkeletonBox>
       </dd>
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/retention-timeline.tsx b/services/platform/app/features/settings/governance/components/retention-timeline.tsx
index 946d4936ef..3aa0a13091 100644
--- a/services/platform/app/features/settings/governance/components/retention-timeline.tsx
+++ b/services/platform/app/features/settings/governance/components/retention-timeline.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 
 import { useT } from '@/lib/i18n/client';
@@ -23,15 +24,15 @@ export function RetentionTimeline({ graceDays }: Props) {
   const noGrace = graceDays <= 0;
 
   return (
-    <div
+    <Stack
       role="img"
       aria-label={t(
         'retentionPolicy.timeline.ariaLabel',
         'Deletion lifecycle visualization',
       )}
-      className="flex flex-col gap-3"
+      gap={3}
     >
-      <div className="relative flex items-start justify-between">
+      <Row gap={0} align="start" justify="between" className="relative">
         <Step
           label={t('retentionPolicy.timeline.activeLabel', 'Active')}
           sub={t(
@@ -90,8 +91,8 @@ export function RetentionTimeline({ graceDays }: Props) {
           )}
           tone="permanent"
         />
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
@@ -103,7 +104,7 @@ interface StepProps {
 
 function Step({ label, sub, tone }: StepProps) {
   return (
-    <div className="flex w-20 flex-col items-center gap-1 text-center sm:w-32">
+    <Stack gap={1} align="center" className="w-20 text-center sm:w-32">
       <div
         className={cn(
           'h-3 w-3 rounded-full ring-2 ring-offset-2 ring-offset-background',
@@ -118,7 +119,7 @@ function Step({ label, sub, tone }: StepProps) {
       <Text className="text-muted-foreground text-[0.65rem] leading-tight">
         {sub}
       </Text>
-    </div>
+    </Stack>
   );
 }
 
@@ -130,7 +131,7 @@ interface ConnectorProps {
 
 function Connector({ tone, label, dashed }: ConnectorProps) {
   return (
-    <div className="flex flex-1 flex-col items-center gap-1 pt-1">
+    <Stack gap={1} align="center" className="flex-1 pt-1">
       <div
         aria-hidden="true"
         className={cn(
@@ -144,6 +145,6 @@ function Connector({ tone, label, dashed }: ConnectorProps) {
       <Text className="text-muted-foreground text-[0.65rem] leading-tight">
         {label}
       </Text>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/session-idle-timeout-editor.tsx b/services/platform/app/features/settings/governance/components/session-idle-timeout-editor.tsx
index 04c4033b18..8b5631f446 100644
--- a/services/platform/app/features/settings/governance/components/session-idle-timeout-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/session-idle-timeout-editor.tsx
@@ -1,15 +1,15 @@
 'use client';
 
 import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useMemo } from 'react';
 import { z } from 'zod';
 
 import { EditorActions, useFormEditor } from '@/app/components/ui/editor';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -22,10 +22,11 @@ import {
   SESSION_IDLE_TIMEOUT_MAX_MINUTES,
   SESSION_IDLE_TIMEOUT_MIN_MINUTES,
 } from '@/lib/shared/session-idle';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
+import { useGovernancePolicyToggle } from '../hooks/use-governance-policy-toggle';
 
 interface SessionIdleTimeoutEditorProps {
   organizationId: string;
@@ -37,11 +38,9 @@ interface SessionIdleTimeoutForm {
 
 const FORM_ID = 'governance-session-idle-timeout-form';
 
-function parseConfig(raw: unknown): SessionIdleTimeoutConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = sessionIdleTimeoutConfigSchema.safeParse(obj);
-  return result.success ? result.data : { ...DEFAULT_SESSION_IDLE_TIMEOUT };
-}
+const parseConfig = createConfigParser(sessionIdleTimeoutConfigSchema, () => ({
+  ...DEFAULT_SESSION_IDLE_TIMEOUT,
+}));
 
 // =============================================================================
 // Mirrors `LoginPolicyEditor`: owns data fetching, the form controller, the
@@ -69,10 +68,18 @@ export function SessionIdleTimeoutEditor({
 
   // `enabled` is instant-save (header switch); `idleTimeoutMinutes` is batched
   // through the EditorActions cluster.
-  const [enabled, setEnabled] = useState(false);
-  useEffect(() => {
-    if (!isLoading) setEnabled(savedConfig.enabled);
-  }, [isLoading, savedConfig]);
+  const { enabled, isToggling, onToggle } = useGovernancePolicyToggle({
+    organizationId,
+    policyType: 'session_idle_timeout',
+    savedEnabled: savedConfig.enabled,
+    isLoading,
+    buildConfig: (next): SessionIdleTimeoutConfig => ({
+      ...savedConfig,
+      enabled: next,
+    }),
+    failureTitle: t('toastSaveFailedTitle'),
+    failureDescription: t('sessionIdleTimeout.saveFailed'),
+  });
 
   const schema = useMemo(
     () =>
@@ -137,36 +144,10 @@ export function SessionIdleTimeoutEditor({
     formState: { errors },
   } = editor.form;
   const canEdit = !cannotManage;
-  const isToggling = upsertMutation.isPending;
-
-  const handleToggleEnabled = useCallback(
-    async (next: boolean) => {
-      setEnabled(next);
-      try {
-        await upsertMutation.mutateAsync({
-          organizationId,
-          policyType: 'session_idle_timeout',
-          config: {
-            ...savedConfig,
-            enabled: next,
-          } satisfies SessionIdleTimeoutConfig,
-        });
-      } catch (err) {
-        console.error('[sessionIdleTimeout toggle]', err);
-        setEnabled(!next);
-        toast({
-          title: t('toastSaveFailedTitle'),
-          description: t('sessionIdleTimeout.saveFailed'),
-          variant: 'destructive',
-        });
-      }
-    },
-    [organizationId, savedConfig, t, toast, upsertMutation],
-  );
 
   return (
     <Skeletonize loading={isLoading} label={t('sessionIdleTimeout.title')}>
-      <PageSection
+      <SettingsSection
         title={t('sessionIdleTimeout.title')}
         description={t('sessionIdleTimeout.description')}
         action={
@@ -174,8 +155,8 @@ export function SessionIdleTimeoutEditor({
             label={t('sessionIdleTimeout.enabled')}
             hideLabelOnMobile
             checked={enabled}
-            onCheckedChange={handleToggleEnabled}
-            disabled={!canEdit || isToggling}
+            onCheckedChange={onToggle}
+            disabled={!canEdit || isToggling || editor.isSaving}
           />
         }
       >
@@ -190,7 +171,6 @@ export function SessionIdleTimeoutEditor({
                   <Input
                     label={t('sessionIdleTimeout.minutes')}
                     type="number"
-                    size="sm"
                     min={SESSION_IDLE_TIMEOUT_MIN_MINUTES}
                     max={SESSION_IDLE_TIMEOUT_MAX_MINUTES}
                     step={1}
@@ -210,13 +190,14 @@ export function SessionIdleTimeoutEditor({
                     formId={FORM_ID}
                     canEdit={canEdit}
                     entityKind="governance_session_idle_timeout"
+                    suppressServerErrorToast
                   />
                 </HStack>
               )}
             </Stack>
           </fieldset>
         </form>
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/system-prompt-editor.tsx b/services/platform/app/features/settings/governance/components/system-prompt-editor.tsx
index a30d64f7fe..913e86c469 100644
--- a/services/platform/app/features/settings/governance/components/system-prompt-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/system-prompt-editor.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -11,6 +10,7 @@ import { z } from 'zod';
 import { EditorActions, useFormEditor } from '@/app/components/ui/editor';
 import { FormSection } from '@/app/components/ui/forms/form-section';
 import { Textarea } from '@/app/components/ui/forms/textarea';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
 import { isRecord } from '@/lib/utils/type-utils';
@@ -122,7 +122,7 @@ export function SystemPromptEditor({
 
   return (
     <Skeletonize loading={isLoading} label={t('systemPrompt.title')}>
-      <PageSection
+      <SettingsSection
         title={t('systemPrompt.title')}
         description={t('systemPrompt.description')}
       >
@@ -181,7 +181,7 @@ export function SystemPromptEditor({
             </Stack>
           </fieldset>
         </form>
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/trash-page.tsx b/services/platform/app/features/settings/governance/components/trash-page.tsx
index 758890f9be..43605b1393 100644
--- a/services/platform/app/features/settings/governance/components/trash-page.tsx
+++ b/services/platform/app/features/settings/governance/components/trash-page.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import {
@@ -22,6 +22,7 @@ import {
   type FilterConfig,
 } from '@/app/components/ui/data-table/data-table-filters';
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useRestoreSoftDeletedRow } from '@/app/features/settings/governance/hooks/mutations';
 import { useListTrashedRows } from '@/app/features/settings/governance/hooks/queries';
 import { useAbility } from '@/app/hooks/use-ability';
@@ -70,7 +71,7 @@ interface TrashCursor {
 
 // =============================================================================
 // Single page — owns data fetching, pagination/filter state, the access check,
-// the restore mutation, and the loading state. Renders the REAL `PageSection` +
+// the restore mutation, and the loading state. Renders the REAL `SettingsSection` +
 // trash table once, always, wrapped in `<Skeletonize>` (no horizontal/vertical
 // shift on load). While loading, the table renders fixed PLACEHOLDER rows (same
 // cell count/height) so an empty body never reads as "nothing trashed"; the
@@ -212,7 +213,7 @@ export function TrashPage({ organizationId }: Props) {
 
   return (
     <>
-      <PageSection
+      <SettingsSection
         title={t('trash.title', 'Trash')}
         description={t(
           'trash.description',
@@ -339,7 +340,6 @@ export function TrashPage({ organizationId }: Props) {
                           <TableCell className="text-right">
                             <Button
                               variant="secondary"
-                              size="sm"
                               icon={Undo2}
                               onClick={() =>
                                 onRequestRestore({
@@ -366,7 +366,12 @@ export function TrashPage({ organizationId }: Props) {
               while the first page loads), so revealing it never pushes the
               page. It only shows the real button once more pages exist. */}
               {(loading || hasMore) && (
-                <div className="border-border flex justify-center border-t p-2">
+                <Row
+                  gap={0}
+                  align="stretch"
+                  justify="center"
+                  className="border-border border-t p-2"
+                >
                   {loading ? (
                     <SkeletonBox>
                       <div className="h-8 w-24 rounded-md" />
@@ -374,7 +379,6 @@ export function TrashPage({ organizationId }: Props) {
                   ) : (
                     <Button
                       variant="ghost"
-                      size="sm"
                       disabled={isLoadingMore}
                       onClick={onLoadMore}
                     >
@@ -383,12 +387,12 @@ export function TrashPage({ organizationId }: Props) {
                         : t('trash.loadMore', 'Load more')}
                     </Button>
                   )}
-                </div>
+                </Row>
               )}
             </div>
           )}
         </Skeletonize>
-      </PageSection>
+      </SettingsSection>
 
       <ConfirmDialog
         open={restoreTarget !== null}
diff --git a/services/platform/app/features/settings/governance/components/two-factor-policy-editor.tsx b/services/platform/app/features/settings/governance/components/two-factor-policy-editor.tsx
index c5c6dc3bcd..87633061e1 100644
--- a/services/platform/app/features/settings/governance/components/two-factor-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/two-factor-policy-editor.tsx
@@ -1,13 +1,13 @@
 'use client';
 
 import { Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
 import { useCallback, useMemo, useRef, useState } from 'react';
 
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -17,8 +17,8 @@ import {
   type TwoFactorPolicyConfig,
 } from '@/lib/shared/schemas/governance';
 import { cn } from '@/lib/utils/cn';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
 
@@ -26,12 +26,9 @@ interface TwoFactorPolicyEditorProps {
   organizationId: string;
 }
 
-function parseConfig(raw: unknown): TwoFactorPolicyConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = twoFactorPolicyConfigSchema.safeParse(obj);
-  if (result.success) return result.data;
-  return { ...DEFAULT_TWO_FACTOR_POLICY };
-}
+const parseConfig = createConfigParser(twoFactorPolicyConfigSchema, () => ({
+  ...DEFAULT_TWO_FACTOR_POLICY,
+}));
 
 // =============================================================================
 // Single editor — owns data fetching, the local state mirrors, instant-save
@@ -159,7 +156,7 @@ export function TwoFactorPolicyEditor({
 
   return (
     <Skeletonize loading={loading} label={t('twoFactorPolicy.title')}>
-      <PageSection
+      <SettingsSection
         title={t('twoFactorPolicy.title')}
         description={t('twoFactorPolicy.description')}
         action={
@@ -196,7 +193,6 @@ export function TwoFactorPolicyEditor({
                   if (e.key === 'Enter') e.currentTarget.blur();
                 }}
                 disabled={!canEdit || !enforced || isSaving}
-                size="sm"
                 min={0}
                 max={30}
                 step={1}
@@ -215,7 +211,7 @@ export function TwoFactorPolicyEditor({
             </Stack>
           </div>
         </Stack>
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/upload-policy-editor.tsx b/services/platform/app/features/settings/governance/components/upload-policy-editor.tsx
index af808aa564..195b0ad363 100644
--- a/services/platform/app/features/settings/governance/components/upload-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/upload-policy-editor.tsx
@@ -1,7 +1,6 @@
 'use client';
 
-import { HStack, Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { Grid, HStack, Stack } from '@tale/ui/layout';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { z } from 'zod';
@@ -9,6 +8,7 @@ import { z } from 'zod';
 import { EditorActions, useFormEditor } from '@/app/components/ui/editor';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
@@ -16,8 +16,8 @@ import {
   uploadPolicyConfigSchema,
   type UploadPolicyConfig,
 } from '@/lib/shared/schemas/governance';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
 import {
@@ -39,12 +39,9 @@ interface UploadPolicyForm {
 
 const FORM_ID = 'governance-upload-policy-form';
 
-function parseConfig(raw: unknown): UploadPolicyConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = uploadPolicyConfigSchema.safeParse(obj);
-  if (result.success) return result.data;
-  return { enabled: false };
-}
+const parseConfig = createConfigParser(uploadPolicyConfigSchema, () => ({
+  enabled: false,
+}));
 
 function extensionsToString(exts?: string[]): string {
   return exts?.join(', ') ?? '';
@@ -84,7 +81,7 @@ function buildConfig(
 // =============================================================================
 // Single editor — owns data fetching, the form controller, the enable toggle
 // state, save/toast wiring, and the loading state. Renders the REAL
-// `PageSection` once, always, wrapped in `<Skeletonize>`; the skeleton-aware
+// `SettingsSection` once, always, wrapped in `<Skeletonize>`; the skeleton-aware
 // `<Switch>`/`<Input>` leaves mask themselves while loading, so the loading and
 // loaded layouts are the SAME tree.
 // =============================================================================
@@ -236,7 +233,7 @@ export function UploadPolicyEditor({
 
   return (
     <Skeletonize loading={isLoading} label={t('uploadPolicy.title')}>
-      <PageSection
+      <SettingsSection
         title={t('uploadPolicy.title')}
         description={t('uploadPolicy.description')}
         action={
@@ -257,36 +254,32 @@ export function UploadPolicyEditor({
             >
               <Stack gap={6} className="max-w-2xl">
                 <Stack gap={4}>
-                  <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+                  <Grid md={2}>
                     <Input
                       label={t('uploadPolicy.allowedExtensions')}
                       placeholder={t('uploadPolicy.extensionPlaceholder')}
-                      size="sm"
                       errorMessage={errors.allowedExtensions?.message}
                       {...register('allowedExtensions')}
                     />
                     <Input
                       label={t('uploadPolicy.blockedExtensions')}
                       placeholder={t('uploadPolicy.extensionPlaceholder')}
-                      size="sm"
                       errorMessage={errors.blockedExtensions?.message}
                       {...register('blockedExtensions')}
                     />
-                  </div>
+                  </Grid>
 
                   <Input
                     label={t('uploadPolicy.allowedMimeTypes')}
                     placeholder={t('uploadPolicy.mimeTypePlaceholder')}
-                    size="sm"
                     errorMessage={errors.allowedMimeTypes?.message}
                     {...register('allowedMimeTypes')}
                   />
 
-                  <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+                  <Grid md={2}>
                     <Input
                       label={`${t('uploadPolicy.maxFileSize')} (${t('uploadPolicy.mbUnit')})`}
                       type="number"
-                      size="sm"
                       min={0}
                       step={1}
                       errorMessage={errors.maxFileSizeMB?.message}
@@ -295,13 +288,12 @@ export function UploadPolicyEditor({
                     <Input
                       label={`${t('uploadPolicy.maxVolumePerUser')} (${t('uploadPolicy.gbUnit')})`}
                       type="number"
-                      size="sm"
                       min={0}
                       step={0.1}
                       errorMessage={errors.maxVolumeGB?.message}
                       {...register('maxVolumeGB')}
                     />
-                  </div>
+                  </Grid>
                 </Stack>
 
                 <HStack justify="end">
@@ -310,13 +302,14 @@ export function UploadPolicyEditor({
                     formId={FORM_ID}
                     canEdit={canManage}
                     entityKind="governance_upload_policy"
+                    suppressServerErrorToast
                   />
                 </HStack>
               </Stack>
             </fieldset>
           </form>
         )}
-      </PageSection>
+      </SettingsSection>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/settings/governance/components/voice-output-policy-editor.tsx b/services/platform/app/features/settings/governance/components/voice-output-policy-editor.tsx
index 1df085e2da..b1b97c63fa 100644
--- a/services/platform/app/features/settings/governance/components/voice-output-policy-editor.tsx
+++ b/services/platform/app/features/settings/governance/components/voice-output-policy-editor.tsx
@@ -1,21 +1,18 @@
 'use client';
 
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
-import type { z } from 'zod';
 
 import { Switch } from '@/app/components/ui/forms/switch';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
 import { voiceOutputConfigSchema } from '@/lib/shared/schemas/governance';
-import { isRecord } from '@/lib/utils/type-utils';
 
+import { createConfigParser } from '../config-parser';
 import { useUpsertGovernancePolicy } from '../hooks/mutations';
 import { useGovernancePolicy } from '../hooks/queries';
 
-type VoiceOutputConfig = z.infer<typeof voiceOutputConfigSchema>;
-
 interface VoiceOutputPolicyEditorProps {
   organizationId: string;
 }
@@ -23,16 +20,13 @@ interface VoiceOutputPolicyEditorProps {
 // Backend default is ON when the policy row is missing (see
 // `isVoiceOutputOrgEnabled` in convex/tts/queries.ts). Mirror that here so
 // the toggle reflects effective state, not just persisted state.
-function parseConfig(raw: unknown): VoiceOutputConfig {
-  const obj = isRecord(raw) ? raw : {};
-  const result = voiceOutputConfigSchema.safeParse(obj);
-  if (result.success) return result.data;
-  return { enabled: true };
-}
+const parseConfig = createConfigParser(voiceOutputConfigSchema, () => ({
+  enabled: true,
+}));
 
 // =============================================================================
 // Single editor — owns data fetching, save/toast wiring, and the loading
-// state. Renders the REAL `PageSection` + skeleton-aware `Switch` once, always,
+// state. Renders the REAL `SettingsSection` + skeleton-aware `Switch` once, always,
 // wrapped in `<Skeletonize>`. The skeleton-aware `<Switch>` masks itself to its
 // exact track size while loading.
 // =============================================================================
@@ -82,7 +76,7 @@ export function VoiceOutputPolicyEditor({
 
   return (
     <Skeletonize loading={isLoading} label={t('voiceOutput.title')}>
-      <PageSection
+      <SettingsSection
         title={t('voiceOutput.title')}
         description={t('voiceOutput.description')}
         action={
diff --git a/services/platform/app/features/settings/governance/config-parser.test.ts b/services/platform/app/features/settings/governance/config-parser.test.ts
new file mode 100644
index 0000000000..d6eca6d760
--- /dev/null
+++ b/services/platform/app/features/settings/governance/config-parser.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { createConfigParser } from './config-parser';
+
+const schema = z.object({
+  enabled: z.boolean(),
+  count: z.number().default(0),
+});
+
+describe('createConfigParser', () => {
+  it('returns the parsed config when the input is valid', () => {
+    const parse = createConfigParser(schema, () => ({
+      enabled: false,
+      count: 0,
+    }));
+    expect(parse({ enabled: true, count: 5 })).toEqual({
+      enabled: true,
+      count: 5,
+    });
+  });
+
+  it('falls back when the input is not an object', () => {
+    const parse = createConfigParser(schema, () => ({
+      enabled: false,
+      count: 0,
+    }));
+    expect(parse(null)).toEqual({ enabled: false, count: 0 });
+    expect(parse('nope')).toEqual({ enabled: false, count: 0 });
+    expect(parse(undefined)).toEqual({ enabled: false, count: 0 });
+  });
+
+  it('falls back when the input is an object that fails validation', () => {
+    const parse = createConfigParser(schema, () => ({
+      enabled: false,
+      count: 0,
+    }));
+    // `enabled` is required and missing → safeParse fails → fallback.
+    expect(parse({ count: 3 })).toEqual({ enabled: false, count: 0 });
+  });
+
+  it('invokes the factory fallback fresh each call (no shared mutable default)', () => {
+    const parse = createConfigParser(schema, () => ({
+      enabled: false,
+      count: 0,
+    }));
+    const a = parse(null);
+    const b = parse(null);
+    expect(a).toEqual({ enabled: false, count: 0 });
+    expect(a).not.toBe(b);
+  });
+});
diff --git a/services/platform/app/features/settings/governance/config-parser.ts b/services/platform/app/features/settings/governance/config-parser.ts
new file mode 100644
index 0000000000..b94bbe68af
--- /dev/null
+++ b/services/platform/app/features/settings/governance/config-parser.ts
@@ -0,0 +1,25 @@
+import type { z } from 'zod';
+
+import { isRecord } from '@/lib/utils/type-utils';
+
+/**
+ * Builds the `(raw: unknown) => T` parser shared by the governance policy
+ * editors. Each editor previously inlined the same body: coerce a non-object to
+ * `{}`, validate the stored `policy.config` against the policy's Zod schema, and
+ * fall back to a default when it's missing or malformed.
+ *
+ * `makeFallback` is a factory (`() => T`, like `useState`'s lazy initializer) so
+ * callers whose default spreads arrays/objects (login backoff schedule,
+ * two-factor defaults, …) get a fresh instance per call rather than sharing one
+ * mutable object across every parse.
+ */
+export function createConfigParser<S extends z.ZodTypeAny>(
+  schema: S,
+  makeFallback: () => z.infer<S>,
+): (raw: unknown) => z.infer<S> {
+  return (raw: unknown) => {
+    const obj = isRecord(raw) ? raw : {};
+    const result = schema.safeParse(obj);
+    return result.success ? result.data : makeFallback();
+  };
+}
diff --git a/services/platform/app/features/settings/governance/data-subject-requests/legal-hold-block-panel.tsx b/services/platform/app/features/settings/governance/data-subject-requests/legal-hold-block-panel.tsx
index c7f443a8e9..6b1e6eb55f 100644
--- a/services/platform/app/features/settings/governance/data-subject-requests/legal-hold-block-panel.tsx
+++ b/services/platform/app/features/settings/governance/data-subject-requests/legal-hold-block-panel.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { Link } from '@tanstack/react-router';
 import { AlertOctagon } from 'lucide-react';
 
@@ -38,20 +39,21 @@ export function LegalHoldBlockPanel({
   const userCustodianHeld = request.errorMessage === 'user_custodian_hold';
 
   return (
-    <div
+    <Stack
       // `role="alert"` already implies `aria-live="assertive"`; an
       // explicit `aria-live="polite"` here was contradictory and
       // browser-defined. The panel is informational (not an interrupt),
       // so prefer `role="status"` (polite by default).
       role="status"
-      className="border-destructive/40 bg-destructive/5 flex flex-col gap-3 rounded-md border p-3 text-sm"
+      gap={3}
+      className="border-destructive/40 bg-destructive/5 rounded-md border p-3 text-sm"
     >
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <AlertOctagon
           className="text-destructive mt-0.5 size-4 shrink-0"
           aria-hidden="true"
         />
-        <div className="flex flex-col gap-1">
+        <Stack gap={1}>
           {/* Title uses `text-foreground` so contrast clears AA against
               the tinted destructive background. The icon above carries
               the destructive hue for visual emphasis. */}
@@ -65,11 +67,11 @@ export function LegalHoldBlockPanel({
                 ? t('dataSubjectRequests.legalHoldBlock.userCustodianHeld')
                 : t('dataSubjectRequests.legalHoldBlock.generic')}
           </span>
-        </div>
-      </div>
+        </Stack>
+      </Row>
 
       {(heldThreads.length > 0 || heldDocs.length > 0) && (
-        <div className="text-foreground/80 flex flex-col gap-1 text-xs">
+        <Stack gap={1} className="text-foreground/80 text-xs">
           {heldThreads.length > 0 && (
             <span>
               {t('dataSubjectRequests.legalHoldBlock.threadsCount', {
@@ -84,7 +86,7 @@ export function LegalHoldBlockPanel({
               })}
             </span>
           )}
-        </div>
+        </Stack>
       )}
 
       <Link
@@ -95,6 +97,6 @@ export function LegalHoldBlockPanel({
       >
         {t('dataSubjectRequests.legalHoldBlock.openLegalHold')}
       </Link>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/governance/data-subject-requests/request-detail-drawer.tsx b/services/platform/app/features/settings/governance/data-subject-requests/request-detail-drawer.tsx
index f9fb04b14d..aa4f465d56 100644
--- a/services/platform/app/features/settings/governance/data-subject-requests/request-detail-drawer.tsx
+++ b/services/platform/app/features/settings/governance/data-subject-requests/request-detail-drawer.tsx
@@ -2,7 +2,7 @@
 
 import { Button } from '@tale/ui/button';
 import { IconButton } from '@tale/ui/icon-button';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -124,24 +124,26 @@ export function RequestDetailDrawer({
 function DrawerErrorState({ onRetry }: { onRetry: () => void }) {
   const { t } = useT('governance');
   return (
-    <div
+    <Stack
       role="alert"
       aria-live="polite"
-      className="border-border bg-muted/30 flex flex-col items-start gap-3 rounded-md border p-4"
+      gap={3}
+      align="start"
+      className="border-border bg-muted/30 rounded-md border p-4"
     >
-      <div className="flex items-center gap-2">
+      <Row gap={2}>
         <AlertTriangle className="text-destructive size-4" aria-hidden="true" />
         <Text as="span" className="font-medium">
           {t('dataSubjectRequests.drawer.errorState.title')}
         </Text>
-      </div>
+      </Row>
       <Text variant="muted" className="text-sm">
         {t('dataSubjectRequests.drawer.errorState.description')}
       </Text>
-      <Button type="button" variant="secondary" size="sm" onClick={onRetry}>
+      <Button type="button" variant="secondary" onClick={onRetry}>
         {t('dataSubjectRequests.drawer.errorState.retry')}
       </Button>
-    </div>
+    </Stack>
   );
 }
 
@@ -215,8 +217,8 @@ function DrawerBody({
     request.effectiveAt > now;
 
   return (
-    <div className="flex flex-col gap-5">
-      <header className="flex flex-wrap items-center gap-2 pr-12">
+    <Stack gap={5}>
+      <Row as="header" gap={2} wrap className="pr-12">
         <SkeletonBox>
           <StatusBadge
             status={request.status}
@@ -230,7 +232,7 @@ function DrawerBody({
             status={request.status}
           />
         </SkeletonBox>
-      </header>
+      </Row>
 
       {isCoolingOff && request.effectiveAt !== undefined && (
         <CoolingOffBanner
@@ -280,7 +282,7 @@ function DrawerBody({
           ms={request.extensionDeadlineAt ?? request.slaDeadlineAt}
         />
         {request.extensionGrantedAt !== undefined && (
-          <div className="bg-muted/30 flex flex-col gap-1 rounded-md p-2 text-xs">
+          <Stack gap={1} className="bg-muted/30 rounded-md p-2 text-xs">
             <Text as="span" className="font-medium">
               {t('dataSubjectRequests.drawer.extensionGrantedTitle', {
                 name:
@@ -294,7 +296,7 @@ function DrawerBody({
                 {request.extensionReason}
               </Text>
             )}
-          </div>
+          </Stack>
         )}
       </Section>
 
@@ -376,7 +378,7 @@ function DrawerBody({
             {t('dataSubjectRequests.drawer.auditEmpty')}
           </Text>
         ) : (
-          <ol className="border-border flex flex-col gap-2 border-l pl-3">
+          <Stack as="ol" gap={2} className="border-border border-l pl-3">
             {auditEntries.map((entry) => (
               <li key={entry._id} className="flex flex-col gap-0.5">
                 <Text as="span" className="text-xs font-medium">
@@ -394,7 +396,7 @@ function DrawerBody({
                 </Text>
               </li>
             ))}
-          </ol>
+          </Stack>
         )}
       </Section>
 
@@ -402,12 +404,11 @@ function DrawerBody({
         <FullBreakdown snapshot={request.perCategorySnapshot} />
       )}
 
-      <footer className="flex flex-wrap gap-2">
+      <Row as="footer" gap={2} align="stretch" wrap>
         {canExtend && (
           <Button
             type="button"
             variant="secondary"
-            size="sm"
             icon={Clock}
             onClick={onExtend}
           >
@@ -418,15 +419,14 @@ function DrawerBody({
           <Button
             type="button"
             variant="secondary"
-            size="sm"
             icon={RefreshCcw}
             onClick={onRetry}
           >
             {t('dataSubjectRequests.actions.retry')}
           </Button>
         )}
-      </footer>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
@@ -439,16 +439,17 @@ function CoolingOffBanner({
 }) {
   const { t } = useT('governance');
   return (
-    <div
+    <Stack
       role="status"
-      className="text-foreground flex flex-col gap-2 rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-sm"
+      gap={2}
+      className="text-foreground rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-sm"
     >
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <Clock
           className="mt-0.5 size-4 shrink-0 text-amber-700 dark:text-amber-300"
           aria-hidden="true"
         />
-        <div className="flex flex-col gap-1">
+        <Stack gap={1}>
           <Text as="span" className="font-medium">
             {t('dataSubjectRequests.drawer.coolingOffBanner.title')}
           </Text>
@@ -458,20 +459,19 @@ function CoolingOffBanner({
           <Text as="span" variant="muted" className="text-xs">
             <TableDateCell date={effectiveAt} />
           </Text>
-        </div>
-      </div>
-      <div className="flex justify-end">
+        </Stack>
+      </Row>
+      <Row gap={0} align="stretch" justify="end">
         <Button
           type="button"
           variant="destructive"
-          size="sm"
           icon={Ban}
           onClick={onCancel}
         >
           {t('dataSubjectRequests.actions.cancel')}
         </Button>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
@@ -483,16 +483,17 @@ function CancelledBlock({
   const { t } = useT('governance');
   const { request } = data;
   return (
-    <div
+    <Stack
       role="status"
-      className="border-border bg-muted/30 text-foreground flex flex-col gap-2 rounded-md border p-3 text-sm"
+      gap={2}
+      className="border-border bg-muted/30 text-foreground rounded-md border p-3 text-sm"
     >
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <Ban
           className="text-muted-foreground mt-0.5 size-4 shrink-0"
           aria-hidden="true"
         />
-        <div className="flex flex-1 flex-col gap-1">
+        <Stack gap={1} className="flex-1">
           <Text as="span" className="font-medium">
             {t('dataSubjectRequests.drawer.cancelledBlock.title')}
           </Text>
@@ -511,9 +512,9 @@ function CancelledBlock({
               <TableDateCell date={request.cancelledAt} />
             </Text>
           )}
-        </div>
-      </div>
-    </div>
+        </Stack>
+      </Row>
+    </Stack>
   );
 }
 
@@ -557,7 +558,13 @@ function FullBreakdown({ snapshot }: { snapshot: Record<string, unknown> }) {
       </summary>
       <dl className="mt-2 flex flex-col gap-1 px-1">
         {visible.map(({ key, rows, skippedByHold }) => (
-          <div key={key} className="flex justify-between gap-2 text-xs">
+          <Row
+            key={key}
+            gap={2}
+            align="stretch"
+            justify="between"
+            className="text-xs"
+          >
             <dt className="text-muted-foreground">
               {t(`dataSubjectRequests.categories.${key}`, key)}
             </dt>
@@ -567,7 +574,7 @@ function FullBreakdown({ snapshot }: { snapshot: Record<string, unknown> }) {
                 skippedByHold,
               })}
             </dd>
-          </div>
+          </Row>
         ))}
         {zeroCount > 0 && (
           <Text as="span" variant="muted" className="text-xs italic">
@@ -589,10 +596,10 @@ function Section({
   children: React.ReactNode;
 }) {
   return (
-    <section className="flex flex-col gap-2">
+    <Stack as="section" gap={2}>
       <h3 className="text-foreground text-sm font-medium">{title}</h3>
-      <div className="flex flex-col gap-2">{children}</div>
-    </section>
+      <Stack gap={2}>{children}</Stack>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/settings/governance/data-subject-requests/requests-list-section.tsx b/services/platform/app/features/settings/governance/data-subject-requests/requests-list-section.tsx
index 46b8c49598..7230ad538f 100644
--- a/services/platform/app/features/settings/governance/data-subject-requests/requests-list-section.tsx
+++ b/services/platform/app/features/settings/governance/data-subject-requests/requests-list-section.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useNavigate } from '@tanstack/react-router';
 import type { ColumnDef } from '@tanstack/react-table';
@@ -15,6 +15,7 @@ import {
   DataTableFilters,
   type FilterConfig,
 } from '@/app/components/ui/data-table/data-table-filters';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import {
   ERASURE_STATUSES,
@@ -114,7 +115,7 @@ export function RequestsListSection({
         accessorKey: 'targetUserName',
         header: t('dataSubjectRequests.columns.target'),
         cell: ({ row }) => (
-          <div className="flex min-w-0 flex-col">
+          <Stack gap={0} className="min-w-0">
             <Text as="span" truncate title={row.original.targetUserName}>
               {row.original.targetUserName}
             </Text>
@@ -129,7 +130,7 @@ export function RequestsListSection({
                 {row.original.targetUserId}
               </Text>
             )}
-          </div>
+          </Stack>
         ),
         size: 220,
       },
@@ -179,14 +180,13 @@ export function RequestsListSection({
 
   return (
     <>
-      <PageSection
+      <SettingsSection
         title={t('dataSubjectRequests.title')}
         description={t('dataSubjectRequests.description')}
         action={
           <Button
             type="button"
             variant="primary"
-            size="sm"
             onClick={() => setFileOpen(true)}
           >
             {/* H9-5: FileText conveys "file an erasure request" — the
@@ -233,7 +233,7 @@ export function RequestsListSection({
           }}
           caption={t('dataSubjectRequests.sections.requestsList.title')}
         />
-      </PageSection>
+      </SettingsSection>
 
       <FileRequestDialog
         open={fileOpen}
diff --git a/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.test.ts b/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.test.ts
new file mode 100644
index 0000000000..f19af34b49
--- /dev/null
+++ b/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.test.ts
@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useGovernancePolicyToggle } from './use-governance-policy-toggle';
+
+const mutateAsync = vi.fn();
+let isPending = false;
+const toastMock = vi.fn();
+
+vi.mock('./mutations', () => ({
+  useUpsertGovernancePolicy: () => ({ mutateAsync, isPending }),
+}));
+
+vi.mock('@/app/hooks/use-toast', () => ({
+  toast: (...args: unknown[]) => toastMock(...args),
+}));
+
+const baseOpts = {
+  organizationId: 'org-1',
+  policyType: 'login_policy',
+  savedEnabled: false,
+  isLoading: false,
+  buildConfig: (next: boolean) => ({ enabled: next }),
+  failureTitle: 'Save failed',
+  failureDescription: 'Could not save the policy',
+};
+
+beforeEach(() => {
+  mutateAsync.mockReset();
+  toastMock.mockReset();
+  isPending = false;
+});
+
+describe('useGovernancePolicyToggle', () => {
+  it('seeds enabled from the persisted value once loaded', () => {
+    const { result } = renderHook(() =>
+      useGovernancePolicyToggle({ ...baseOpts, savedEnabled: true }),
+    );
+    expect(result.current.enabled).toBe(true);
+  });
+
+  it('does not seed while still loading', () => {
+    const { result } = renderHook(() =>
+      useGovernancePolicyToggle({
+        ...baseOpts,
+        savedEnabled: true,
+        isLoading: true,
+      }),
+    );
+    expect(result.current.enabled).toBe(false);
+  });
+
+  it('flips and persists the built config on success, without toasting', async () => {
+    mutateAsync.mockResolvedValue(undefined);
+    const { result } = renderHook(() => useGovernancePolicyToggle(baseOpts));
+
+    await act(async () => {
+      await result.current.onToggle(true);
+    });
+
+    expect(mutateAsync).toHaveBeenCalledWith({
+      organizationId: 'org-1',
+      policyType: 'login_policy',
+      config: { enabled: true },
+    });
+    expect(result.current.enabled).toBe(true);
+    expect(toastMock).not.toHaveBeenCalled();
+  });
+
+  it('reverts the optimistic flip and toasts on failure', async () => {
+    mutateAsync.mockRejectedValue(new Error('boom'));
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const { result } = renderHook(() => useGovernancePolicyToggle(baseOpts));
+
+    await act(async () => {
+      await result.current.onToggle(true);
+    });
+
+    expect(result.current.enabled).toBe(false);
+    expect(toastMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Save failed',
+        description: 'Could not save the policy',
+        variant: 'destructive',
+      }),
+    );
+    errorSpy.mockRestore();
+  });
+});
diff --git a/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.ts b/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.ts
new file mode 100644
index 0000000000..23568c611a
--- /dev/null
+++ b/services/platform/app/features/settings/governance/hooks/use-governance-policy-toggle.ts
@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { toast } from '@/app/hooks/use-toast';
+
+import { useUpsertGovernancePolicy } from './mutations';
+
+interface GovernancePolicyToggleOptions<C> {
+  organizationId: string;
+  /** The policy's file-backed type, e.g. `'login_policy'`. */
+  policyType: string;
+  /** The persisted `enabled` flag; seeds the optimistic mirror once loaded. */
+  savedEnabled: boolean;
+  isLoading: boolean;
+  /** Builds the full policy config to persist for the new toggle state. */
+  buildConfig: (next: boolean) => C;
+  /** Already-translated destructive-toast strings shown when the save fails. */
+  failureTitle: string;
+  failureDescription: string;
+}
+
+/**
+ * Shared logic for a governance policy's instant-save `enabled` header switch:
+ * an optimistic local mirror seeded from the persisted value, a save that flips
+ * it immediately, and a revert + destructive toast when the save fails. Extracted
+ * from the login/upload/session editors, which all reimplemented it identically
+ * (only the persisted config shape and the failure copy differ).
+ *
+ * The switch's `enabled` is a local mirror rather than derived state because the
+ * write is a filesystem action with no optimistic cache patch — the reactive
+ * `getPolicy` query only updates once the write + cache-sync complete, so the
+ * mirror gives immediate feedback and is rolled back by hand on failure.
+ */
+export function useGovernancePolicyToggle<C>(
+  options: GovernancePolicyToggleOptions<C>,
+): {
+  enabled: boolean;
+  isToggling: boolean;
+  onToggle: (next: boolean) => Promise<void>;
+} {
+  const { organizationId, policyType, savedEnabled, isLoading } = options;
+  const upsert = useUpsertGovernancePolicy();
+  const [enabled, setEnabled] = useState(false);
+
+  // Seed the optimistic mirror from the persisted value once the read settles
+  // (the leaf would otherwise flash `false` for a frame before data arrives).
+  useEffect(() => {
+    if (!isLoading) setEnabled(savedEnabled);
+  }, [isLoading, savedEnabled]);
+
+  // Keep the latest config-builder + copy in a ref so `onToggle` stays
+  // referentially stable while still reading fresh values (the saved config and
+  // locale change between renders without re-creating the handler).
+  const latest = useRef(options);
+  latest.current = options;
+
+  const onToggle = useCallback(
+    async (next: boolean) => {
+      setEnabled(next);
+      const { buildConfig, failureTitle, failureDescription } = latest.current;
+      try {
+        await upsert.mutateAsync({
+          organizationId,
+          policyType,
+          config: buildConfig(next),
+        });
+      } catch (err) {
+        console.error(`[${policyType} toggle]`, err);
+        setEnabled(!next);
+        toast({
+          title: failureTitle,
+          description: failureDescription,
+          variant: 'destructive',
+        });
+      }
+    },
+    [upsert, organizationId, policyType],
+  );
+
+  return { enabled, isToggling: upsert.isPending, onToggle };
+}
diff --git a/services/platform/app/features/settings/governance/legal-hold/active-holds-section.tsx b/services/platform/app/features/settings/governance/legal-hold/active-holds-section.tsx
index c5c82bf4c6..fbe71254db 100644
--- a/services/platform/app/features/settings/governance/legal-hold/active-holds-section.tsx
+++ b/services/platform/app/features/settings/governance/legal-hold/active-holds-section.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { Lock } from 'lucide-react';
@@ -11,6 +11,7 @@ import { useMemo, useState } from 'react';
 import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell';
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { Select } from '@/app/components/ui/forms/select';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import type { Id } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
 
@@ -91,7 +92,7 @@ export function ActiveHoldsSection({
         accessorKey: 'targetLabel',
         header: t('legalHold.columns.target'),
         cell: ({ row }) => (
-          <div className="flex min-w-0 flex-col">
+          <Stack gap={0} className="min-w-0">
             <Text as="span" truncate title={row.original.targetLabel}>
               {row.original.targetLabel}
             </Text>
@@ -104,7 +105,7 @@ export function ActiveHoldsSection({
             >
               {row.original.targetId}
             </Text>
-          </div>
+          </Stack>
         ),
         meta: { skeleton: { type: 'two-line' as const } },
         size: 180,
@@ -155,11 +156,10 @@ export function ActiveHoldsSection({
         header: t('legalHold.columns.actions'),
         meta: { isAction: true, align: 'right' as const },
         cell: ({ row }) => (
-          <div className="flex justify-end">
+          <Row gap={0} align="stretch" justify="end">
             <Button
               type="button"
               variant="ghost"
-              size="sm"
               onClick={(e) => {
                 e.stopPropagation();
                 setReleaseHoldId(row.original._id);
@@ -167,7 +167,7 @@ export function ActiveHoldsSection({
             >
               {t('legalHold.actions.requestRelease')}
             </Button>
-          </div>
+          </Row>
         ),
         size: 140,
       },
@@ -177,14 +177,13 @@ export function ActiveHoldsSection({
 
   return (
     <>
-      <PageSection
+      <SettingsSection
         title={t('legalHold.sections.activeHolds.title')}
         description={t('legalHold.sections.activeHolds.description')}
         action={
           <Button
             type="button"
             variant="primary"
-            size="sm"
             onClick={() => setPlaceOpen(true)}
           >
             <Lock className="mr-1.5 size-4" aria-hidden />
@@ -192,10 +191,9 @@ export function ActiveHoldsSection({
           </Button>
         }
       >
-        <div className="flex items-center gap-2">
+        <Row gap={2}>
           <Select
             id="active-holds-targettype-filter"
-            size="sm"
             value={targetTypeFilter}
             onValueChange={(v) =>
               // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Select onValueChange yields string; options are constrained to FilterTargetType | 'all'
@@ -204,7 +202,7 @@ export function ActiveHoldsSection({
             options={targetTypeOptions}
             aria-label={t('legalHold.filters.allTargets')}
           />
-        </div>
+        </Row>
         <DataTable<LegalHoldRow>
           columns={columns}
           data={rows ?? []}
@@ -217,7 +215,7 @@ export function ActiveHoldsSection({
           }}
           caption={t('legalHold.sections.activeHolds.title')}
         />
-      </PageSection>
+      </SettingsSection>
 
       <PlaceHoldDialog
         open={placeOpen}
diff --git a/services/platform/app/features/settings/governance/legal-hold/matters-section.tsx b/services/platform/app/features/settings/governance/legal-hold/matters-section.tsx
index 63b1301562..ff68dcf6e0 100644
--- a/services/platform/app/features/settings/governance/legal-hold/matters-section.tsx
+++ b/services/platform/app/features/settings/governance/legal-hold/matters-section.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { useMemo, useState } from 'react';
@@ -10,6 +10,7 @@ import { useMemo, useState } from 'react';
 import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell';
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { Select } from '@/app/components/ui/forms/select';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useT } from '@/lib/i18n/client';
 
 import { useLegalMatters } from '../hooks/queries';
@@ -91,7 +92,7 @@ export function MattersSection({ organizationId }: MattersSectionProps) {
         header: t('legalHold.columns.actions'),
         meta: { isAction: true, align: 'right' as const },
         cell: ({ row }) => (
-          <div className="flex justify-end gap-2">
+          <Row gap={2} align="stretch" justify="end">
             <Button
               type="button"
               variant="ghost"
@@ -116,7 +117,7 @@ export function MattersSection({ organizationId }: MattersSectionProps) {
                 {t('legalHold.actions.closeMatter')}
               </Button>
             )}
-          </div>
+          </Row>
         ),
         size: 200,
       },
@@ -126,24 +127,22 @@ export function MattersSection({ organizationId }: MattersSectionProps) {
 
   return (
     <>
-      <PageSection
+      <SettingsSection
         title={t('legalHold.sections.matters.title')}
         description={t('legalHold.sections.matters.description')}
         action={
           <Button
             type="button"
             variant="primary"
-            size="sm"
             onClick={() => setCreateOpen(true)}
           >
             {t('legalHold.actions.createMatter')}
           </Button>
         }
       >
-        <div className="flex items-center gap-2">
+        <Row gap={2}>
           <Select
             id="matters-status-filter"
-            size="sm"
             value={statusFilter}
             onValueChange={(v) =>
               // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Select onValueChange yields string; options are constrained
@@ -152,7 +151,7 @@ export function MattersSection({ organizationId }: MattersSectionProps) {
             options={statusOptions}
             aria-label={t('legalHold.filters.allStatuses')}
           />
-        </div>
+        </Row>
         <DataTable<MatterRow>
           columns={columns}
           data={matters ?? []}
@@ -165,7 +164,7 @@ export function MattersSection({ organizationId }: MattersSectionProps) {
           }}
           caption={t('legalHold.sections.matters.title')}
         />
-      </PageSection>
+      </SettingsSection>
 
       <UpsertMatterDialog
         open={createOpen}
diff --git a/services/platform/app/features/settings/governance/legal-hold/place-hold-dialog.tsx b/services/platform/app/features/settings/governance/legal-hold/place-hold-dialog.tsx
index 607354d81b..c1d6f7f2a7 100644
--- a/services/platform/app/features/settings/governance/legal-hold/place-hold-dialog.tsx
+++ b/services/platform/app/features/settings/governance/legal-hold/place-hold-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { zodResolver } from '@hookform/resolvers/zod';
+import { Row } from '@tale/ui/layout';
 import { AlertTriangle } from 'lucide-react';
 import { useEffect, useMemo, useState } from 'react';
 import { useForm } from 'react-hook-form';
@@ -243,16 +244,18 @@ export function PlaceHoldDialog({
             />
           ) : (
             <>
-              <div
+              <Row
                 role="alert"
-                className="border-destructive/40 bg-destructive/5 text-destructive flex items-start gap-2 rounded-md border px-3 py-2 text-xs"
+                gap={2}
+                align="start"
+                className="border-destructive/40 bg-destructive/5 text-destructive rounded-md border px-3 py-2 text-xs"
               >
                 <AlertTriangle
                   className="mt-0.5 size-4 shrink-0"
                   aria-hidden="true"
                 />
                 <span>{t('legalHold.dialogs.placeHold.orgWarning')}</span>
-              </div>
+              </Row>
               <Input
                 id="hold-org-confirm"
                 label={t('legalHold.dialogs.placeHold.orgConfirmLabel', {
diff --git a/services/platform/app/features/settings/governance/legal-hold/release-history-section.tsx b/services/platform/app/features/settings/governance/legal-hold/release-history-section.tsx
index fc76d9ff61..f8d5323837 100644
--- a/services/platform/app/features/settings/governance/legal-hold/release-history-section.tsx
+++ b/services/platform/app/features/settings/governance/legal-hold/release-history-section.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { useMemo, useState } from 'react';
@@ -9,6 +9,7 @@ import { useMemo, useState } from 'react';
 import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell';
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { Select } from '@/app/components/ui/forms/select';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useT } from '@/lib/i18n/client';
 
 import { useLegalHoldReleaseRequestsPaginated } from '../hooks/queries';
@@ -71,7 +72,7 @@ export function ReleaseHistorySection({
         accessorKey: 'targetType',
         header: t('legalHold.columns.target'),
         cell: ({ row }) => (
-          <div className="flex flex-col">
+          <Stack gap={0}>
             {row.original.targetType && (
               <Badge variant="outline" className="self-start">
                 {t(`legalHold.targetTypes.${row.original.targetType}`)}
@@ -86,7 +87,7 @@ export function ReleaseHistorySection({
             >
               {row.original.targetId ?? row.original.holdId}
             </Text>
-          </div>
+          </Stack>
         ),
         meta: { skeleton: { type: 'two-line' as const } },
         size: 180,
@@ -162,21 +163,20 @@ export function ReleaseHistorySection({
   const isLoadingMore = result.status === 'LoadingMore';
 
   return (
-    <PageSection
+    <SettingsSection
       title={t('legalHold.sections.history.title')}
       description={t('legalHold.sections.history.description')}
     >
-      <div className="flex items-center gap-2">
+      <Row gap={2}>
         <Select
           id="release-history-status-filter"
-          size="sm"
           value={status}
           // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Select onValueChange yields string; options are constrained to ReleaseStatus
           onValueChange={(v) => setStatus(v as ReleaseStatus)}
           options={statusOptions}
           aria-label={t('legalHold.columns.status')}
         />
-      </div>
+      </Row>
       <DataTable<HistoryRow>
         columns={columns}
         data={result.results as HistoryRow[]}
@@ -196,6 +196,6 @@ export function ReleaseHistorySection({
         }}
         caption={t('legalHold.sections.history.title')}
       />
-    </PageSection>
+    </SettingsSection>
   );
 }
diff --git a/services/platform/app/features/settings/governance/legal-hold/release-requests-section.tsx b/services/platform/app/features/settings/governance/legal-hold/release-requests-section.tsx
index 1993c65f8e..43f060c040 100644
--- a/services/platform/app/features/settings/governance/legal-hold/release-requests-section.tsx
+++ b/services/platform/app/features/settings/governance/legal-hold/release-requests-section.tsx
@@ -2,14 +2,14 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import type { ColumnDef } from '@tanstack/react-table';
 import { useMemo, useState } from 'react';
 
 import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell';
 import { DataTable } from '@/app/components/ui/data-table/data-table';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useCurrentUser } from '@/app/hooks/use-current-user';
 import type { Id } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
@@ -47,7 +47,7 @@ export function ReleaseRequestsSection({
         accessorKey: 'targetType',
         header: t('legalHold.columns.target'),
         cell: ({ row }) => (
-          <div className="flex flex-col">
+          <Stack gap={0}>
             {row.original.targetType && (
               <Badge variant="outline" className="self-start">
                 {t(`legalHold.targetTypes.${row.original.targetType}`)}
@@ -62,7 +62,7 @@ export function ReleaseRequestsSection({
             >
               {row.original.targetId ?? row.original.holdId}
             </Text>
-          </div>
+          </Stack>
         ),
         meta: { skeleton: { type: 'two-line' as const } },
         size: 200,
@@ -99,7 +99,7 @@ export function ReleaseRequestsSection({
         cell: ({ row }) => {
           const isSelf = currentUser?.userId === row.original.requestedBy;
           return (
-            <div className="flex justify-end gap-2">
+            <Row gap={2} align="stretch" justify="end">
               <Button
                 type="button"
                 variant="ghost"
@@ -127,7 +127,7 @@ export function ReleaseRequestsSection({
               >
                 {t('legalHold.actions.reject')}
               </Button>
-            </div>
+            </Row>
           );
         },
         size: 200,
@@ -142,7 +142,7 @@ export function ReleaseRequestsSection({
         accessorKey: 'targetType',
         header: t('legalHold.columns.target'),
         cell: ({ row }) => (
-          <div className="flex flex-col">
+          <Stack gap={0}>
             {row.original.targetType && (
               <Badge variant="outline" className="self-start">
                 {t(`legalHold.targetTypes.${row.original.targetType}`)}
@@ -157,7 +157,7 @@ export function ReleaseRequestsSection({
             >
               {row.original.targetId ?? row.original.holdId}
             </Text>
-          </div>
+          </Stack>
         ),
         meta: { skeleton: { type: 'two-line' as const } },
         size: 200,
@@ -191,7 +191,7 @@ export function ReleaseRequestsSection({
 
   return (
     <>
-      <PageSection
+      <SettingsSection
         title={t('legalHold.sections.releaseRequests.title')}
         description={t('legalHold.sections.releaseRequests.description')}
       >
@@ -235,7 +235,7 @@ export function ReleaseRequestsSection({
             />
           </div>
         </Stack>
-      </PageSection>
+      </SettingsSection>
 
       <ApproveReleaseDialog
         open={approveTarget !== null}
diff --git a/services/platform/app/features/settings/integrations/components/integration-details.tsx b/services/platform/app/features/settings/integrations/components/integration-details.tsx
index 3657102116..69d9058306 100644
--- a/services/platform/app/features/settings/integrations/components/integration-details.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-details.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row } from '@tale/ui/layout';
 import { type StatGridItem, StatGrid } from '@tale/ui/stat-grid';
 import { Text } from '@tale/ui/text';
 import { Check, ChevronDown, ChevronRight, Copy } from 'lucide-react';
@@ -343,14 +344,18 @@ export function IntegrationDetails({
           onToggle={() => toggle('operations')}
           isLast={lastSection === 'operations'}
         >
-          <div className="border-border bg-muted flex gap-3 border-x px-4 py-3">
+          <Row
+            gap={3}
+            align="stretch"
+            className="border-border bg-muted border-x px-4 py-3"
+          >
             <ul
               className="max-h-48 flex-1 space-y-1.5 overflow-y-auto text-sm"
               role="list"
             >
               {restOperations.map((op) => (
                 <li key={op.name} className="flex min-w-0 flex-col gap-0.5">
-                  <div className="flex min-w-0 items-center gap-1">
+                  <Row gap={1} className="min-w-0">
                     <Text as="span" variant="code" truncate>
                       {op.name}
                     </Text>
@@ -359,7 +364,7 @@ export function IntegrationDetails({
                         — {op.title}
                       </Text>
                     )}
-                  </div>
+                  </Row>
                   {op.description && (
                     <Text variant="caption">{op.description}</Text>
                   )}
@@ -368,7 +373,7 @@ export function IntegrationDetails({
               ))}
             </ul>
             <ContentCopyButton value={operationsSummary} />
-          </div>
+          </Row>
         </SectionRow>
       )}
 
@@ -384,14 +389,18 @@ export function IntegrationDetails({
           onToggle={() => toggle('sqlOperations')}
           isLast={lastSection === 'sqlOperations'}
         >
-          <div className="border-border bg-muted flex gap-3 border-x px-4 py-3">
+          <Row
+            gap={3}
+            align="stretch"
+            className="border-border bg-muted border-x px-4 py-3"
+          >
             <ul
               className="max-h-60 flex-1 space-y-2 overflow-y-auto text-sm"
               role="list"
             >
               {sqlOperations.map((op) => (
                 <li key={op.name}>
-                  <div className="flex min-w-0 items-center gap-2">
+                  <Row gap={2} className="min-w-0">
                     <Text as="span" variant="code" truncate>
                       {op.name}
                     </Text>
@@ -410,7 +419,7 @@ export function IntegrationDetails({
                         {t('integrations.manageDialog.requiresApproval')}
                       </Badge>
                     )}
-                  </div>
+                  </Row>
                   {op.description && (
                     <Text variant="caption" className="mt-0.5">
                       {op.description}
@@ -434,7 +443,7 @@ export function IntegrationDetails({
               ))}
             </ul>
             <ContentCopyButton value={sqlOperationsSummary} />
-          </div>
+          </Row>
         </SectionRow>
       )}
 
@@ -458,13 +467,18 @@ export function IntegrationDetails({
           onToggle={() => toggle('allowedHosts')}
           isLast={lastSection === 'allowedHosts'}
         >
-          <div className="border-border bg-muted flex flex-wrap gap-1 border-x px-4 py-3">
+          <Row
+            gap={1}
+            align="stretch"
+            wrap
+            className="border-border bg-muted border-x px-4 py-3"
+          >
             {allowedHosts.map((host) => (
               <Badge key={host} variant="outline">
                 {host}
               </Badge>
             ))}
-          </div>
+          </Row>
         </SectionRow>
       )}
 
@@ -482,7 +496,11 @@ export function IntegrationDetails({
           onToggle={() => toggle('connectorCode')}
           isLast={lastSection === 'connectorCode'}
         >
-          <div className="border-border bg-muted flex gap-3 border-x px-4 py-3">
+          <Row
+            gap={3}
+            align="stretch"
+            className="border-border bg-muted border-x px-4 py-3"
+          >
             {lineCount > 0 ? (
               <>
                 <pre className="relative max-h-96 flex-1 overflow-y-auto text-xs break-words whitespace-pre-wrap">
@@ -499,7 +517,7 @@ export function IntegrationDetails({
                 </pre>
               </div>
             )}
-          </div>
+          </Row>
         </SectionRow>
       )}
 
diff --git a/services/platform/app/features/settings/integrations/components/integration-manage/integration-credentials-form.tsx b/services/platform/app/features/settings/integrations/components/integration-manage/integration-credentials-form.tsx
index b1d70bf72f..69b85e5930 100644
--- a/services/platform/app/features/settings/integrations/components/integration-manage/integration-credentials-form.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-manage/integration-credentials-form.tsx
@@ -470,7 +470,6 @@ function OAuth2CredentialsEditor({
       {isEditingOAuth2 && (
         <Button
           variant="secondary"
-          size="sm"
           onClick={onCancelEdit}
           disabled={busy}
           className="w-full"
diff --git a/services/platform/app/features/settings/integrations/components/integration-manage/integration-related-automations.tsx b/services/platform/app/features/settings/integrations/components/integration-manage/integration-related-automations.tsx
index 15aa55e46b..89faa79f15 100644
--- a/services/platform/app/features/settings/integrations/components/integration-manage/integration-related-automations.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-manage/integration-related-automations.tsx
@@ -133,7 +133,6 @@ export function IntegrationRelatedAutomations({
           <div className="mt-3">
             <Button
               variant="secondary"
-              size="sm"
               icon={Plus}
               onClick={() => setCreateDialogOpen(true)}
             >
diff --git a/services/platform/app/features/settings/integrations/components/integration-manage/integration-update-section.tsx b/services/platform/app/features/settings/integrations/components/integration-manage/integration-update-section.tsx
index 6510bf0c3b..362ffb3c22 100644
--- a/services/platform/app/features/settings/integrations/components/integration-manage/integration-update-section.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-manage/integration-update-section.tsx
@@ -2,7 +2,7 @@
 
 import { ActionRow } from '@tale/ui/action-row';
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   AlertCircle,
@@ -102,15 +102,17 @@ export function IntegrationUpdateSection({
             </FileUpload.Root>
 
             {updateParseError && (
-              <div
-                className="bg-destructive/10 text-destructive flex items-start gap-2 rounded-md p-3 text-sm"
+              <Row
+                gap={2}
+                align="start"
+                className="bg-destructive/10 text-destructive rounded-md p-3 text-sm"
                 role="alert"
               >
                 <AlertCircle className="mt-0.5 size-4 shrink-0" />
                 <pre className="font-sans whitespace-pre-wrap">
                   {updateParseError}
                 </pre>
-              </div>
+              </Row>
             )}
 
             {parsedUpdate && (
@@ -146,7 +148,6 @@ export function IntegrationUpdateSection({
                   <Button
                     onClick={onApplyUpdate}
                     disabled={busy}
-                    size="sm"
                     className="flex-1"
                   >
                     {isApplyingUpdate ? (
@@ -160,7 +161,6 @@ export function IntegrationUpdateSection({
                   </Button>
                   <Button
                     variant="secondary"
-                    size="sm"
                     onClick={onClearUpdate}
                     disabled={busy}
                   >
diff --git a/services/platform/app/features/settings/integrations/components/integration-manage/slack-setup-guide.tsx b/services/platform/app/features/settings/integrations/components/integration-manage/slack-setup-guide.tsx
index 5facda44a5..04def34917 100644
--- a/services/platform/app/features/settings/integrations/components/integration-manage/slack-setup-guide.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-manage/slack-setup-guide.tsx
@@ -62,12 +62,7 @@ export function SlackSetupGuide({
       <Stack gap={2}>
         <HStack className="items-center justify-between">
           <Label>{t('integrations.slackSetup.manifest')}</Label>
-          <Button
-            type="button"
-            size="sm"
-            variant="secondary"
-            onClick={copyManifest}
-          >
+          <Button type="button" variant="secondary" onClick={copyManifest}>
             {copied ? (
               <Check className="mr-1.5 size-3.5" />
             ) : (
diff --git a/services/platform/app/features/settings/integrations/components/integration-upload/integration-upload-dialog.tsx b/services/platform/app/features/settings/integrations/components/integration-upload/integration-upload-dialog.tsx
index d4b0ce6561..d4332de68f 100644
--- a/services/platform/app/features/settings/integrations/components/integration-upload/integration-upload-dialog.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-upload/integration-upload-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { useAction } from 'convex/react';
 import { useCallback } from 'react';
 
@@ -127,7 +128,7 @@ export function IntegrationUploadDialog({
       footer={footer}
       className="max-h-[90vh] grid-rows-[auto_1fr_auto] overflow-hidden"
     >
-      <div className="flex min-h-0 min-w-0 flex-col gap-4 overflow-hidden">
+      <Stack className="min-h-0 min-w-0 overflow-hidden">
         {state.step === 'upload' && (
           <div className="min-h-0 min-w-0 flex-1 overflow-y-auto pr-2">
             <UploadStep onPackageParsed={state.setParsedPackage} />
@@ -143,7 +144,7 @@ export function IntegrationUploadDialog({
             />
           </div>
         )}
-      </div>
+      </Stack>
     </Dialog>
   );
 }
diff --git a/services/platform/app/features/settings/integrations/components/integration-upload/steps/upload-step.tsx b/services/platform/app/features/settings/integrations/components/integration-upload/steps/upload-step.tsx
index b9707e7eb2..32681ba075 100644
--- a/services/platform/app/features/settings/integrations/components/integration-upload/steps/upload-step.tsx
+++ b/services/platform/app/features/settings/integrations/components/integration-upload/steps/upload-step.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Upload, AlertCircle } from 'lucide-react';
 import { useState, useCallback } from 'react';
@@ -80,13 +80,15 @@ export function UploadStep({ onPackageParsed }: UploadStepProps) {
       </FileUpload.Root>
 
       {error && (
-        <div
-          className="bg-destructive/10 text-destructive flex items-start gap-2 rounded-md p-3 text-sm"
+        <Row
+          gap={2}
+          align="start"
+          className="bg-destructive/10 text-destructive rounded-md p-3 text-sm"
           role="alert"
         >
           <AlertCircle className="mt-0.5 size-4 shrink-0" />
           <pre className="font-sans whitespace-pre-wrap">{error}</pre>
-        </div>
+        </Row>
       )}
     </Stack>
   );
diff --git a/services/platform/app/features/settings/integrations/components/integrations.tsx b/services/platform/app/features/settings/integrations/components/integrations.tsx
index 33ad2de6c6..4b11785258 100644
--- a/services/platform/app/features/settings/integrations/components/integrations.tsx
+++ b/services/platform/app/features/settings/integrations/components/integrations.tsx
@@ -2,7 +2,7 @@
 
 import { Card } from '@tale/ui/card';
 import { EmptyState } from '@tale/ui/empty-state';
-import { HStack, Stack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Tabs } from '@tale/ui/tabs';
@@ -30,25 +30,25 @@ const PLACEHOLDER_CARD_COUNT = 6;
  */
 function IntegrationCardSkeleton() {
   return (
-    <Card contentClassName="p-4">
-      <div className="flex items-start gap-3">
+    <Card padding="md">
+      <Row gap={3} align="start">
         <SkeletonBox>
           <div className="size-10 rounded-lg" />
         </SkeletonBox>
-        <div className="flex min-w-0 flex-1 flex-col gap-1">
-          <div className="flex items-start justify-between gap-2">
+        <Stack gap={1} className="min-w-0 flex-1">
+          <Row gap={2} align="start" justify="between">
             <div className="w-24 text-sm leading-none">
               <SkeletonText />
             </div>
             <SkeletonBox>
               <div className="h-5 w-16 rounded-full" />
             </SkeletonBox>
-          </div>
+          </Row>
           <div className="text-sm leading-snug">
             <SkeletonText lines={2} />
           </div>
-        </div>
-      </div>
+        </Stack>
+      </Row>
     </Card>
   );
 }
diff --git a/services/platform/app/features/settings/integrations/components/sso-config/role-mapping-section.tsx b/services/platform/app/features/settings/integrations/components/sso-config/role-mapping-section.tsx
index 06a77d299b..5a0ef5574d 100644
--- a/services/platform/app/features/settings/integrations/components/sso-config/role-mapping-section.tsx
+++ b/services/platform/app/features/settings/integrations/components/sso-config/role-mapping-section.tsx
@@ -136,7 +136,7 @@ export function RoleMappingSection({
               size="icon"
               onClick={() => onRemove(index)}
               disabled={disabled}
-              aria-label={t('integrations.sso.removeRule')}
+              title={t('integrations.sso.removeRule')}
               className="shrink-0"
             >
               <Trash2 className="h-4 w-4" />
@@ -147,7 +147,6 @@ export function RoleMappingSection({
         <Button
           type="button"
           variant="secondary"
-          size="sm"
           onClick={onAdd}
           disabled={disabled}
         >
diff --git a/services/platform/app/features/settings/mcp-servers/components/mcp-server-card.tsx b/services/platform/app/features/settings/mcp-servers/components/mcp-server-card.tsx
index fa75d1859b..53120f5ae0 100644
--- a/services/platform/app/features/settings/mcp-servers/components/mcp-server-card.tsx
+++ b/services/platform/app/features/settings/mcp-servers/components/mcp-server-card.tsx
@@ -88,10 +88,7 @@ export function McpServerCard({
   );
 
   return (
-    <Card
-      className="hover:border-primary/50 cursor-pointer transition-colors"
-      contentClassName="p-0"
-    >
+    <Card padding="none" interactive className="cursor-pointer">
       <div className="relative">
         <div className="absolute right-5 bottom-5 z-10">
           <DropdownMenu
diff --git a/services/platform/app/features/settings/mcp-servers/components/mcp-server-form.tsx b/services/platform/app/features/settings/mcp-servers/components/mcp-server-form.tsx
index 264c226476..9c16acff8e 100644
--- a/services/platform/app/features/settings/mcp-servers/components/mcp-server-form.tsx
+++ b/services/platform/app/features/settings/mcp-servers/components/mcp-server-form.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { useCallback, useState } from 'react';
 
 import { FormSection } from '@/app/components/ui/forms/form-section';
@@ -416,7 +416,7 @@ export function McpServerForm({
         </FormSection>
 
         {!hideActions && (
-          <div className="flex justify-end gap-3">
+          <Row gap={3} align="stretch" justify="end">
             {onCancel && (
               <Button
                 type="button"
@@ -430,7 +430,7 @@ export function McpServerForm({
             <Button type="submit" disabled={isSubmitting}>
               {isSubmitting ? t('form.saving') : t('form.save')}
             </Button>
-          </div>
+          </Row>
         )}
       </Stack>
     </form>
diff --git a/services/platform/app/features/settings/mcp-servers/components/mcp-server-panel.tsx b/services/platform/app/features/settings/mcp-servers/components/mcp-server-panel.tsx
index 479a5388d8..e99b9d35f9 100644
--- a/services/platform/app/features/settings/mcp-servers/components/mcp-server-panel.tsx
+++ b/services/platform/app/features/settings/mcp-servers/components/mcp-server-panel.tsx
@@ -5,7 +5,7 @@ import { Button } from '@tale/ui/button';
 import { DropdownMenu, type DropdownMenuGroup } from '@tale/ui/dropdown-menu';
 import { Heading } from '@tale/ui/heading';
 import { IconButton } from '@tale/ui/icon-button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useAction } from 'convex/react';
 import {
@@ -376,7 +376,7 @@ export function McpServerPanel({
 
         <div className="border-border shrink-0 border-t p-4 sm:px-6 sm:py-4">
           {isEditing ? (
-            <div className="flex justify-end gap-3">
+            <Row gap={3} align="stretch" justify="end">
               <Button
                 type="button"
                 variant="secondary"
@@ -392,7 +392,7 @@ export function McpServerPanel({
               >
                 {isSubmitting ? t('form.saving') : t('form.save')}
               </Button>
-            </div>
+            </Row>
           ) : (
             <HStack justify="between" align="center">
               <Button
diff --git a/services/platform/app/features/settings/mcp-servers/components/mcp-servers.tsx b/services/platform/app/features/settings/mcp-servers/components/mcp-servers.tsx
index 01257c921e..3f21b50fa4 100644
--- a/services/platform/app/features/settings/mcp-servers/components/mcp-servers.tsx
+++ b/services/platform/app/features/settings/mcp-servers/components/mcp-servers.tsx
@@ -3,7 +3,7 @@
 import { Button } from '@tale/ui/button';
 import { EmptyState } from '@tale/ui/empty-state';
 import { IconButton } from '@tale/ui/icon-button';
-import { Grid, HStack, Stack } from '@tale/ui/layout';
+import { Grid, HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useAction } from 'convex/react';
 import { Server, X } from 'lucide-react';
@@ -167,7 +167,12 @@ export function McpServers({
             onSubmit={handleCreate}
           />
         </div>
-        <div className="border-border flex shrink-0 justify-end gap-3 border-t p-4 sm:px-6 sm:py-4">
+        <Row
+          gap={3}
+          align="stretch"
+          justify="end"
+          className="border-border shrink-0 border-t p-4 sm:px-6 sm:py-4"
+        >
           <Button
             type="button"
             variant="secondary"
@@ -179,7 +184,7 @@ export function McpServers({
           <Button type="submit" form="add-mcp-server" disabled={isCreating}>
             {isCreating ? t('form.saving') : t('form.save')}
           </Button>
-        </div>
+        </Row>
       </Sheet>
 
       {selectedServer && (
diff --git a/services/platform/app/features/settings/organization/components/member-edit-dialog.tsx b/services/platform/app/features/settings/organization/components/member-edit-dialog.tsx
index 5fd6d071c3..e42a959bcb 100644
--- a/services/platform/app/features/settings/organization/components/member-edit-dialog.tsx
+++ b/services/platform/app/features/settings/organization/components/member-edit-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { zodResolver } from '@hookform/resolvers/zod';
+import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
 import { HStack, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
@@ -10,7 +11,6 @@ import * as z from 'zod';
 
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
 import { FormDialog } from '@/app/components/ui/dialog/form-dialog';
-import { Banner } from '@/app/components/ui/feedback/banner';
 import { ValidationCheckList } from '@/app/components/ui/feedback/validation-check-item';
 import { Checkbox } from '@/app/components/ui/forms/checkbox';
 import { FormSection } from '@/app/components/ui/forms/form-section';
@@ -247,10 +247,9 @@ export function EditMemberDialog({
           isMemberRole(member?.role) &&
           member.role === 'admin' &&
           watch('role') !== 'admin' && (
-            <Banner
+            <Alert
               variant="warning"
-              message={t('organization.adminWarning')}
-              dismissible={false}
+              description={t('organization.adminWarning')}
               className="mt-2"
             />
           )}
@@ -436,7 +435,6 @@ function PasskeyAdminControl({ memberId }: { memberId: string }) {
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 onClick={() => setConfirmTarget({ id: pk.id, name })}
               >
                 {t('passkeys.revokeButton')}
diff --git a/services/platform/app/features/settings/organization/components/member-table.tsx b/services/platform/app/features/settings/organization/components/member-table.tsx
index 36c47a879f..2699c7989f 100644
--- a/services/platform/app/features/settings/organization/components/member-table.tsx
+++ b/services/platform/app/features/settings/organization/components/member-table.tsx
@@ -83,8 +83,8 @@ export function MemberTable({
   );
 
   // Column sizes double as the table's min-width floor (DataTable sums them).
-  // They must total ≤ 540px so the table fits the `SettingsPage narrow`
-  // 544px column on the Organization page without horizontal scroll.
+  // Keep the total within the full-width settings page budget (≤ 940px) so the
+  // table never forces horizontal scroll on the Organization page.
   const columns = useMemo<ColumnDef<Member>[]>(
     () => [
       // Multi-row select — canonical 40px column. Enables bulk-remove via
diff --git a/services/platform/app/features/settings/organization/components/members-settings.tsx b/services/platform/app/features/settings/organization/components/members-settings.tsx
index 6d3727d27f..b9ee994592 100644
--- a/services/platform/app/features/settings/organization/components/members-settings.tsx
+++ b/services/platform/app/features/settings/organization/components/members-settings.tsx
@@ -2,6 +2,7 @@
 
 import { ActionRow } from '@tale/ui/action-row';
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { Plus } from 'lucide-react';
 import { useMemo, useState } from 'react';
 
@@ -66,7 +67,7 @@ export function MembersSettings({
   }, [allMembers, debouncedSearch, sortOrder]);
 
   return (
-    <div className="flex flex-col gap-5">
+    <Stack gap={4}>
       <ActionRow justify="between">
         <SearchInput
           placeholder={tSettings('organization.searchMember')}
@@ -119,6 +120,6 @@ export function MembersSettings({
         open={isAddMemberDialogOpen}
         onOpenChange={setIsAddMemberDialogOpen}
       />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/personalization/components/personalization-settings.tsx b/services/platform/app/features/settings/personalization/components/personalization-settings.tsx
index c6901ef80a..f39be73ced 100644
--- a/services/platform/app/features/settings/personalization/components/personalization-settings.tsx
+++ b/services/platform/app/features/settings/personalization/components/personalization-settings.tsx
@@ -33,6 +33,7 @@ import { useToast } from '@/app/hooks/use-toast';
 import { api } from '@/convex/_generated/api';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
+import { convexErrorMessage } from '@/lib/utils/convex-error';
 import { isRecord } from '@/lib/utils/type-utils';
 
 import {
@@ -308,7 +309,7 @@ function CustomInstructionsToggleSection({
           toast({ title: t('toasts.preferencesUpdated') });
         } catch (err) {
           toast({
-            title: errorMessage(err, t('errors.saveFailed')),
+            title: convexErrorMessage(err, t('errors.saveFailed')),
             variant: 'destructive',
           });
         }
@@ -347,7 +348,7 @@ function MemoriesToggleSection({
           toast({ title: t('toasts.preferencesUpdated') });
         } catch (err) {
           toast({
-            title: errorMessage(err, t('errors.saveFailed')),
+            title: convexErrorMessage(err, t('errors.saveFailed')),
             variant: 'destructive',
           });
         }
@@ -397,7 +398,7 @@ function CustomInstructionsSection({
         toast({ title: t('toasts.saved') });
       } catch (err) {
         toast({
-          title: errorMessage(err, t('errors.saveFailed')),
+          title: convexErrorMessage(err, t('errors.saveFailed')),
           variant: 'destructive',
         });
         throw err;
@@ -554,7 +555,7 @@ function VoiceOutputSection({
           }
         } catch (err) {
           toast({
-            title: errorMessage(err, t('errors.saveFailed')),
+            title: convexErrorMessage(err, t('errors.saveFailed')),
             variant: 'destructive',
           });
         }
@@ -622,7 +623,7 @@ function SavedMemoriesSection({
                     toast({ title: t('toasts.deleted') });
                   } catch (err) {
                     toast({
-                      title: errorMessage(err, t('errors.saveFailed')),
+                      title: convexErrorMessage(err, t('errors.saveFailed')),
                       variant: 'destructive',
                     });
                   }
@@ -664,7 +665,6 @@ function PendingMemoriesSection({
             <li key={m._id} className="flex items-start gap-3 py-2">
               <Text className="flex-1">{m.content}</Text>
               <Button
-                size="sm"
                 variant="primary"
                 onClick={async () => {
                   try {
@@ -672,7 +672,7 @@ function PendingMemoriesSection({
                     toast({ title: t('toasts.saved') });
                   } catch (err) {
                     toast({
-                      title: errorMessage(err, t('errors.saveFailed')),
+                      title: convexErrorMessage(err, t('errors.saveFailed')),
                       variant: 'destructive',
                     });
                   }
@@ -681,7 +681,6 @@ function PendingMemoriesSection({
                 {t('card.save')}
               </Button>
               <Button
-                size="sm"
                 variant="ghost"
                 onClick={async () => {
                   try {
@@ -689,7 +688,7 @@ function PendingMemoriesSection({
                     toast({ title: t('toasts.discarded') });
                   } catch (err) {
                     toast({
-                      title: errorMessage(err, t('errors.saveFailed')),
+                      title: convexErrorMessage(err, t('errors.saveFailed')),
                       variant: 'destructive',
                     });
                   }
@@ -704,18 +703,3 @@ function PendingMemoriesSection({
     </SettingsSection>
   );
 }
-
-function errorMessage(err: unknown, fallback: string): string {
-  if (err instanceof ConvexError) {
-    const data: unknown = err.data;
-    if (
-      data !== null &&
-      typeof data === 'object' &&
-      'message' in data &&
-      typeof data.message === 'string'
-    ) {
-      return data.message;
-    }
-  }
-  return fallback;
-}
diff --git a/services/platform/app/features/settings/providers/components/model-catalog-card.tsx b/services/platform/app/features/settings/providers/components/model-catalog-card.tsx
index eaf7a9bc17..2c5eab0d2e 100644
--- a/services/platform/app/features/settings/providers/components/model-catalog-card.tsx
+++ b/services/platform/app/features/settings/providers/components/model-catalog-card.tsx
@@ -1,11 +1,12 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { PageSection } from '@tale/ui/page-section';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { RefreshCw } from 'lucide-react';
 import { useCallback } from 'react';
 
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { SettingsToggleRow } from '@/app/features/settings/components/settings-toggle-row';
 import { useConvexAction } from '@/app/hooks/use-convex-action';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
@@ -90,13 +91,12 @@ export function ModelCatalogCard({
   }, [organizationId, sync, t]);
 
   return (
-    <PageSection
-      as="h2"
+    <SettingsSection
       className={className}
       title={t('providers.modelCatalog.title')}
       description={t('providers.modelCatalog.description')}
     >
-      <div className="flex items-center justify-between gap-4 rounded-lg border px-4 py-3">
+      <Row justify="between" className="rounded-lg border px-4 py-3">
         <Text as="span" variant="caption" className="text-muted-foreground">
           {latest
             ? latest.ok
@@ -111,7 +111,6 @@ export function ModelCatalogCard({
         </Text>
         <Button
           variant="secondary"
-          size="sm"
           onClick={onRefresh}
           disabled={sync.isPending}
           icon={RefreshCw}
@@ -119,7 +118,7 @@ export function ModelCatalogCard({
         >
           {t('providers.modelCatalog.refresh')}
         </Button>
-      </div>
+      </Row>
       <SettingsToggleRow
         label={t('providers.modelCatalog.autoSync')}
         description={t('providers.modelCatalog.autoSyncHelp')}
@@ -128,6 +127,6 @@ export function ModelCatalogCard({
         disabled={setAutoSync.isPending}
         onCheckedChange={onToggleAutoSync}
       />
-    </PageSection>
+    </SettingsSection>
   );
 }
diff --git a/services/platform/app/features/settings/providers/components/provider-add-panel.tsx b/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
index 4b6139742f..fdad9d6ca4 100644
--- a/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-add-panel.tsx
@@ -4,7 +4,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
 import { IconButton } from '@tale/ui/icon-button';
-import { Grid, HStack, Stack } from '@tale/ui/layout';
+import { Grid, HStack, Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useNavigate } from '@tanstack/react-router';
 import { Loader2, Pencil, Plus, RefreshCw, Trash2, X } from 'lucide-react';
@@ -657,7 +657,6 @@ export function ProviderAddPanel({
                     <Button
                       type="button"
                       variant="ghost"
-                      size="sm"
                       onClick={() => void handleFetchModels()}
                       disabled={isFetching}
                     >
@@ -669,12 +668,7 @@ export function ProviderAddPanel({
                       {t('providers.fetchModels')}
                     </Button>
                   )}
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    size="sm"
-                    onClick={openAddDialog}
-                  >
+                  <Button type="button" variant="ghost" onClick={openAddDialog}>
                     <Plus className="mr-1 size-3.5" />
                     {t('providers.addModel')}
                   </Button>
@@ -702,8 +696,10 @@ export function ProviderAddPanel({
               )}
 
               {isFetching && rows.length === 0 && (
-                <div
-                  className="border-border flex items-center justify-center gap-2 rounded-xl border px-4 py-8"
+                <Row
+                  gap={2}
+                  justify="center"
+                  className="border-border rounded-xl border px-4 py-8"
                   role="status"
                   aria-live="polite"
                 >
@@ -711,7 +707,7 @@ export function ProviderAddPanel({
                   <Text variant="caption" className="text-muted-foreground">
                     {t('providers.fetchingModels')}
                   </Text>
-                </div>
+                </Row>
               )}
 
               {rows.length > 0 && (
@@ -726,7 +722,12 @@ export function ProviderAddPanel({
                   </div>
                   <Stack gap={0}>
                     {filteredRows.length === 0 && (
-                      <div className="flex flex-col items-center justify-center gap-1 px-4 py-8">
+                      <Stack
+                        gap={1}
+                        align="center"
+                        justify="center"
+                        className="px-4 py-8"
+                      >
                         <Text className="text-sm font-medium">
                           {t('providers.modelsEmpty.searchTitle')}
                         </Text>
@@ -736,7 +737,7 @@ export function ProviderAddPanel({
                         >
                           {t('providers.modelsEmpty.searchDescription')}
                         </Text>
-                      </div>
+                      </Stack>
                     )}
                     {visibleRows.map((row, rowIdx) => {
                       const model =
diff --git a/services/platform/app/features/settings/providers/components/provider-default-models-panel.tsx b/services/platform/app/features/settings/providers/components/provider-default-models-panel.tsx
index 611211fc01..a7837d806a 100644
--- a/services/platform/app/features/settings/providers/components/provider-default-models-panel.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-default-models-panel.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useCallback, useEffect, useState } from 'react';
 
@@ -126,7 +127,7 @@ export function ProviderDefaultModelsPanel({
             ? modelsWithTag.find((m) => m.id === selectedId)
             : undefined;
         return (
-          <div key={tag} className="flex items-end gap-2">
+          <Row key={tag} gap={2} align="end">
             <Select
               wrapperClassName="flex-1"
               label={modelTagLabel(tag, t)}
@@ -147,7 +148,7 @@ export function ProviderDefaultModelsPanel({
             />
             {/* Match the default trigger's height (h-10) so the info icon
                 centers against the select, not its label. */}
-            <div className="flex h-10 items-center">
+            <Row gap={0} className="h-10">
               {selected ? (
                 <ModelInfoPopover
                   tags={selected.tags as string[]}
@@ -156,8 +157,8 @@ export function ProviderDefaultModelsPanel({
                   triggerClassName="mt-0"
                 />
               ) : null}
-            </div>
-          </div>
+            </Row>
+          </Row>
         );
       })}
     </FormDialog>
diff --git a/services/platform/app/features/settings/providers/components/provider-detail-drawer/api-key-section.tsx b/services/platform/app/features/settings/providers/components/provider-detail-drawer/api-key-section.tsx
index 730cfeeb7a..34406f6e8d 100644
--- a/services/platform/app/features/settings/providers/components/provider-detail-drawer/api-key-section.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-detail-drawer/api-key-section.tsx
@@ -271,15 +271,11 @@ export function ApiKeySection({
             wrap
             className="ml-auto justify-end gap-y-1"
           >
-            <Button
-              variant="ghost"
-              size="sm"
-              onClick={() => setTestDialogOpen(true)}
-            >
+            <Button variant="ghost" onClick={() => setTestDialogOpen(true)}>
               <Zap className="mr-1 size-3.5" />
               {t('providers.testConnection')}
             </Button>
-            <Button variant="ghost" size="sm" onClick={openDialog}>
+            <Button variant="ghost" onClick={openDialog}>
               <Pencil className="mr-1 size-3.5" />
               {hasSecret || config.secretsEnv
                 ? t('providers.editKey')
@@ -287,7 +283,7 @@ export function ApiKeySection({
             </Button>
           </HStack>
         </HStack>
-        <Card contentClassName="p-0">
+        <Card padding="none">
           {/* Env-var key source (issue #1711). When a `secretsEnv` is
               configured it is the preferred source; show whether it currently
               resolves. A stored key is shown below whenever one exists — even
@@ -404,7 +400,6 @@ export function ApiKeySection({
           />
           <Button
             type="button"
-            size="sm"
             className="self-start"
             onClick={() => performSave(false)}
             disabled={saving || apiKey.trim().length === 0}
@@ -434,7 +429,6 @@ export function ApiKeySection({
           <HStack gap={2} align="center" wrap>
             <Button
               type="button"
-              size="sm"
               onClick={performSaveEnv}
               disabled={
                 saving ||
@@ -448,7 +442,6 @@ export function ApiKeySection({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 onClick={clearEnv}
                 disabled={saving}
               >
diff --git a/services/platform/app/features/settings/providers/components/provider-detail-drawer/default-models-section.tsx b/services/platform/app/features/settings/providers/components/provider-detail-drawer/default-models-section.tsx
index 1d62397e6f..3d4ec5c99b 100644
--- a/services/platform/app/features/settings/providers/components/provider-detail-drawer/default-models-section.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-detail-drawer/default-models-section.tsx
@@ -52,7 +52,6 @@ export function DefaultModelsSection({
           </Stack>
           <Button
             variant="ghost"
-            size="sm"
             className="ml-auto"
             onClick={() => setPanelOpen(true)}
           >
@@ -60,7 +59,7 @@ export function DefaultModelsSection({
             {t('providers.editDefaults')}
           </Button>
         </HStack>
-        <Card contentClassName="p-0">
+        <Card padding="none">
           <InfoRow label={t('providers.tagChat')}>
             <SkeletonBox>{modelDisplayName(config.defaults?.chat)}</SkeletonBox>
           </InfoRow>
diff --git a/services/platform/app/features/settings/providers/components/provider-detail-drawer/general-section.tsx b/services/platform/app/features/settings/providers/components/provider-detail-drawer/general-section.tsx
index b62edd6a24..ba001da370 100644
--- a/services/platform/app/features/settings/providers/components/provider-detail-drawer/general-section.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-detail-drawer/general-section.tsx
@@ -36,7 +36,6 @@ export function GeneralSection({
         </Text>
         <Button
           variant="ghost"
-          size="sm"
           className="ml-auto"
           onClick={() => setPanelOpen(true)}
         >
@@ -44,7 +43,7 @@ export function GeneralSection({
           {t('providers.editGeneral')}
         </Button>
       </HStack>
-      <Card contentClassName="p-0">
+      <Card padding="none">
         <InfoRow label={t('providers.displayName')}>
           <SkeletonBox>{config.displayName}</SkeletonBox>
         </InfoRow>
diff --git a/services/platform/app/features/settings/providers/components/provider-detail-drawer/models-section.tsx b/services/platform/app/features/settings/providers/components/provider-detail-drawer/models-section.tsx
index 12a4636737..89a5412462 100644
--- a/services/platform/app/features/settings/providers/components/provider-detail-drawer/models-section.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-detail-drawer/models-section.tsx
@@ -776,7 +776,6 @@ export function ModelsSection({
             <Button
               type="button"
               variant="ghost"
-              size="sm"
               onClick={() => void handleFetchFromProvider()}
               disabled={isFetchingFromProvider}
             >
@@ -791,7 +790,6 @@ export function ModelsSection({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 onClick={() => void syncAllFromCatalog()}
                 disabled={syncingAll || isSaving}
               >
@@ -803,12 +801,7 @@ export function ModelsSection({
                 {t('providers.modelCapabilities.syncAll')}
               </Button>
             )}
-            <Button
-              type="button"
-              variant="ghost"
-              size="sm"
-              onClick={openAddDialog}
-            >
+            <Button type="button" variant="ghost" onClick={openAddDialog}>
               <Plus className="mr-1 size-3.5" />
               {t('providers.addModelShort')}
             </Button>
@@ -850,7 +843,12 @@ export function ModelsSection({
             </div>
             <Stack gap={0}>
               {filteredRows.length === 0 && (
-                <div className="flex flex-col items-center justify-center gap-1 px-4 py-8">
+                <Stack
+                  gap={1}
+                  align="center"
+                  justify="center"
+                  className="px-4 py-8"
+                >
                   <Text className="text-sm font-medium">
                     {t('providers.modelsEmpty.searchTitle')}
                   </Text>
@@ -860,7 +858,7 @@ export function ModelsSection({
                   >
                     {t('providers.modelsEmpty.searchDescription')}
                   </Text>
-                </div>
+                </Stack>
               )}
               {visibleRows.map((row, rowIdx) => {
                 const model =
@@ -1308,7 +1306,6 @@ export function ModelsSection({
                     <Button
                       type="button"
                       variant="secondary"
-                      size="sm"
                       onClick={fillFromCatalog}
                       disabled={!capsByModelId.has(form.id.trim())}
                     >
diff --git a/services/platform/app/features/settings/providers/components/provider-options-editor.tsx b/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
index 515d86c7a7..1309b6d3a2 100644
--- a/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
+++ b/services/platform/app/features/settings/providers/components/provider-options-editor.tsx
@@ -286,7 +286,6 @@ export function ProviderOptionsEditor({
           </Text>
           <Button
             variant="ghost"
-            size="sm"
             className="ml-auto"
             onClick={() => setOpen(true)}
           >
@@ -297,7 +296,7 @@ export function ProviderOptionsEditor({
 
         <CollapsibleGuide label={copy.guideLabel} content={copy.description} />
 
-        <Card contentClassName="px-4 py-2.5">
+        <Card padding="none" className="px-4 py-2.5">
           {isEmpty ? (
             <Text className="text-muted-foreground text-sm italic">
               {copy.notConfigured}
@@ -420,7 +419,7 @@ function ProviderOptionsEditorSheet({
         />
       </HStack>
 
-      <div className="flex min-h-0 flex-1 flex-col">
+      <Stack gap={0} className="min-h-0 flex-1">
         <div className="flex-1 overflow-y-auto p-4 sm:px-6 sm:py-5">
           <Stack gap={3}>
             <CollapsibleGuide label={guideLabel} content={description} />
@@ -451,7 +450,6 @@ function ProviderOptionsEditorSheet({
             <Button
               type="button"
               variant="ghost"
-              size="sm"
               onClick={onClose}
               disabled={inFlight}
             >
@@ -459,7 +457,6 @@ function ProviderOptionsEditorSheet({
             </Button>
             <Button
               type="button"
-              size="sm"
               onClick={onSave}
               disabled={inFlight || !isDirty || !validation.ok}
             >
@@ -467,7 +464,7 @@ function ProviderOptionsEditorSheet({
             </Button>
           </HStack>
         </div>
-      </div>
+      </Stack>
     </>
   );
 }
diff --git a/services/platform/app/features/settings/runtimes/runtimes-settings.tsx b/services/platform/app/features/settings/runtimes/runtimes-settings.tsx
index de04502a92..7f0c6e892c 100644
--- a/services/platform/app/features/settings/runtimes/runtimes-settings.tsx
+++ b/services/platform/app/features/settings/runtimes/runtimes-settings.tsx
@@ -4,7 +4,7 @@ import { Badge } from '@tale/ui/badge';
 import { LinkButton } from '@tale/ui/button';
 import { CodeBlock } from '@tale/ui/code-block';
 import { EmptyState } from '@tale/ui/empty-state';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Cpu, KeyRound } from 'lucide-react';
 import { useMemo } from 'react';
@@ -65,14 +65,13 @@ export function RuntimesSettings({
   }, [data]);
 
   return (
-    <Stack gap={8}>
+    <>
       <SettingsSection
         title={t('install.title')}
         description={t('description')}
         action={
           <LinkButton
-            size="sm"
-            variant="secondary"
+            variant="primary"
             icon={KeyRound}
             href="/dashboard/$id/settings/api/rest"
             params={{ id: organizationId }}
@@ -96,10 +95,7 @@ export function RuntimesSettings({
         </Text>
       </SettingsSection>
 
-      <SettingsSection
-        className="border-border border-t pt-8"
-        title={t('list.title')}
-      >
+      <SettingsSection title={t('list.title')}>
         {daemons.length === 0 ? (
           <EmptyState
             icon={Cpu}
@@ -107,7 +103,7 @@ export function RuntimesSettings({
             description={t('list.emptyHint')}
           />
         ) : (
-          <ul className="flex flex-col gap-2">
+          <Stack as="ul" gap={2}>
             {daemons.map(([daemonId, adapters]) => {
               const first = adapters[0];
               const worst: RuntimeRow['status'] = adapters.some(
@@ -122,7 +118,7 @@ export function RuntimesSettings({
                   key={daemonId}
                   className="border-border flex flex-col gap-2 rounded-lg border p-3"
                 >
-                  <div className="flex flex-wrap items-center gap-2">
+                  <Row gap={2} wrap>
                     <Text as="h3" variant="label" className="min-w-0 truncate">
                       {first?.name || daemonId}
                     </Text>
@@ -145,7 +141,7 @@ export function RuntimesSettings({
                         ),
                       })}
                     </Text>
-                  </div>
+                  </Row>
                   <Text as="p" variant="muted" className="font-mono text-xs">
                     {daemonId}
                   </Text>
@@ -169,9 +165,9 @@ export function RuntimesSettings({
                 </li>
               );
             })}
-          </ul>
+          </Stack>
         )}
       </SettingsSection>
-    </Stack>
+    </>
   );
 }
diff --git a/services/platform/app/features/settings/sandboxes/sandboxes-settings.tsx b/services/platform/app/features/settings/sandboxes/sandboxes-settings.tsx
index e3f6e38e77..2c392ebf21 100644
--- a/services/platform/app/features/settings/sandboxes/sandboxes-settings.tsx
+++ b/services/platform/app/features/settings/sandboxes/sandboxes-settings.tsx
@@ -1,5 +1,5 @@
 import { Badge } from '@tale/ui/badge';
-import { PageSection } from '@tale/ui/page-section';
+import { Row, Stack } from '@tale/ui/layout';
 import type { ColumnDef } from '@tanstack/react-table';
 import type { FunctionReturnType } from 'convex/server';
 import { Pin, PinOff, Square, Trash2 } from 'lucide-react';
@@ -9,6 +9,7 @@ import { TableDateCell } from '@/app/components/ui/data-display/table-date-cell'
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
 import { EntityRowActions } from '@/app/components/ui/entity/entity-row-actions';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useConvexAction } from '@/app/hooks/use-convex-action';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { useToast } from '@/app/hooks/use-toast';
@@ -101,7 +102,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
           // deleted user). Constrained width + truncate so a long id/email can't
           // bleed into the Agent column.
           return (
-            <div className="flex max-w-[220px] min-w-0 flex-col">
+            <Stack gap={0} className="max-w-[220px] min-w-0">
               <span className="truncate font-medium">
                 {s.ownerName ?? s.ownerEmail ?? s.createdBy}
               </span>
@@ -110,7 +111,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
                   {s.ownerEmail}
                 </span>
               )}
-            </div>
+            </Stack>
           );
         },
       },
@@ -130,7 +131,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
           // would mislabel as "Idle" (which means a live, non-busy container).
           const stopped = s.status === 'stopped';
           return (
-            <div className="flex flex-wrap gap-1">
+            <Row gap={1} align="stretch" wrap>
               {paused ? (
                 <Badge variant="destructive">{t('status.pausedBudget')}</Badge>
               ) : stopped ? (
@@ -141,7 +142,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
                 <Badge variant="outline">{t('status.idle')}</Badge>
               )}
               {s.pinned && <Badge variant="blue">{t('status.pinned')}</Badge>}
-            </div>
+            </Row>
           );
         },
       },
@@ -157,7 +158,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
           }
           const count = op.continuationCount ?? 0;
           return (
-            <div className="flex flex-col">
+            <Stack gap={0}>
               {op.threadId && (
                 <span className="text-xs">
                   {t('task.thread')}{' '}
@@ -169,7 +170,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
                   {count} {t('task.continuations')}
                 </span>
               )}
-            </div>
+            </Stack>
           );
         },
       },
@@ -193,7 +194,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
           const s = row.original;
           const busy = pendingId === s.sessionId;
           return (
-            <div className="flex justify-end">
+            <Row gap={0} align="stretch" justify="end">
               <EntityRowActions
                 actions={[
                   {
@@ -243,7 +244,7 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
                   },
                 ]}
               />
-            </div>
+            </Row>
           );
         },
       },
@@ -254,14 +255,14 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
   // Non-privileged member (or unauthenticated) → query returns null.
   if (data === null) {
     return (
-      <PageSection title={t('title')}>
+      <SettingsSection title={t('title')}>
         <p className="text-muted-foreground text-sm">{t('accessDenied')}</p>
-      </PageSection>
+      </SettingsSection>
     );
   }
 
   return (
-    <PageSection title={t('title')} description={t('description')}>
+    <SettingsSection title={t('title')} description={t('description')}>
       <DataTable<SandboxRow>
         columns={columns}
         data={data ?? []}
@@ -292,6 +293,6 @@ export function SandboxesSettings({ organizationId }: SandboxesSettingsProps) {
           ).finally(() => setConfirmDestroy(null));
         }}
       />
-    </PageSection>
+    </SettingsSection>
   );
 }
diff --git a/services/platform/app/features/settings/teams/components/team-detail-dialog.tsx b/services/platform/app/features/settings/teams/components/team-detail-dialog.tsx
index 86f04d45b6..283f9d80a1 100644
--- a/services/platform/app/features/settings/teams/components/team-detail-dialog.tsx
+++ b/services/platform/app/features/settings/teams/components/team-detail-dialog.tsx
@@ -2,7 +2,7 @@
 
 import { Badge } from '@tale/ui/badge';
 import { Button } from '@tale/ui/button';
-import { HStack, Stack } from '@tale/ui/layout';
+import { HStack, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonCircle } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -93,12 +93,12 @@ function TeamDetailDialogContent({
               </Stack>
             </Skeletonize>
           ) : !teamMembers || teamMembers.length === 0 ? (
-            <div className="flex flex-col items-center justify-center gap-2 py-6">
+            <Stack gap={2} align="center" justify="center" className="py-6">
               <Users className="text-muted-foreground size-8" />
               <Text variant="muted" className="text-sm">
                 {tSettings('teams.noTeamMembers')}
               </Text>
-            </div>
+            </Stack>
           ) : (
             <div className="border-border overflow-hidden rounded-lg border">
               {teamMembers.map((member: TeamDetailMember, index: number) => (
@@ -110,13 +110,17 @@ function TeamDetailDialogContent({
                       : ''
                   }`}
                 >
-                  <div className="bg-muted flex size-8 shrink-0 items-center justify-center rounded-full">
+                  <Row
+                    gap={0}
+                    justify="center"
+                    className="bg-muted size-8 shrink-0 rounded-full"
+                  >
                     <Text className="text-muted-foreground text-xs font-medium">
                       {(member.displayName || member.email || '?')
                         .charAt(0)
                         .toUpperCase()}
                     </Text>
-                  </div>
+                  </Row>
                   <Stack gap={0} className="min-w-0 flex-1">
                     <Text className="truncate text-sm font-medium">
                       {member.displayName ||
diff --git a/services/platform/app/features/settings/teams/components/team-list-panel.tsx b/services/platform/app/features/settings/teams/components/team-list-panel.tsx
index a42d408c8d..22045357a8 100644
--- a/services/platform/app/features/settings/teams/components/team-list-panel.tsx
+++ b/services/platform/app/features/settings/teams/components/team-list-panel.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Stack } from '@tale/ui/layout';
 import { Check, Plus } from 'lucide-react';
 import { useCallback, useState } from 'react';
 
@@ -64,7 +65,7 @@ export function TeamListPanel({
   ];
 
   return (
-    <div className="flex flex-col">
+    <Stack gap={0}>
       {!hideHeader && (
         <div className="text-muted-foreground px-3 pt-2 pb-1.5 text-xs font-medium tracking-wide uppercase">
           {tNav('teamFilter.label')}
@@ -132,6 +133,6 @@ export function TeamListPanel({
         open={createOpen}
         onOpenChange={setCreateOpen}
       />
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/teams/components/team-member-checklist.tsx b/services/platform/app/features/settings/teams/components/team-member-checklist.tsx
index 231f70fb14..26e35ee855 100644
--- a/services/platform/app/features/settings/teams/components/team-member-checklist.tsx
+++ b/services/platform/app/features/settings/teams/components/team-member-checklist.tsx
@@ -1,5 +1,7 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
+
 import { Checkbox } from '@/app/components/ui/forms/checkbox';
 import { useT } from '@/lib/i18n/client';
 
@@ -27,26 +29,26 @@ export function TeamMemberChecklist({
 
   if (isLoading) {
     return (
-      <div className="flex items-center justify-center py-4">
+      <Row gap={0} justify="center" className="py-4">
         <p className="text-muted-foreground text-sm">
           {tSettings('teams.loadingMembers')}
         </p>
-      </div>
+      </Row>
     );
   }
 
   if (!orgMembers || orgMembers.length === 0) {
     return (
-      <div className="flex items-center justify-center py-4">
+      <Row gap={0} justify="center" className="py-4">
         <p className="text-muted-foreground text-sm">
           {tSettings('teams.noMembersToAdd')}
         </p>
-      </div>
+      </Row>
     );
   }
 
   return (
-    <div className="flex flex-col gap-2">
+    <Stack gap={2}>
       <p className="text-foreground/80 text-sm font-medium">
         {tSettings('teams.manageMembers')}
       </p>
@@ -87,6 +89,6 @@ export function TeamMemberChecklist({
           );
         })}
       </div>
-    </div>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/settings/teams/components/teams-table.tsx b/services/platform/app/features/settings/teams/components/teams-table.tsx
index 6bc6c181b2..3591adf5e5 100644
--- a/services/platform/app/features/settings/teams/components/teams-table.tsx
+++ b/services/platform/app/features/settings/teams/components/teams-table.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import type { RowSelectionState } from '@tanstack/react-table';
-import { Plus, Users } from 'lucide-react';
+import { Users } from 'lucide-react';
 import { useCallback, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
@@ -91,7 +91,9 @@ export function TeamsTable({ teams, organizationId }: TeamsTableProps) {
   return (
     // No section header here — the Teams settings page already renders the
     // "Teams" title + description, so the table is just the bare content.
-    <div className="flex flex-col gap-3">
+    // No wrapper gap: the preloader renders null and the dialog portals, so the
+    // DataTable is the only visible child of the enclosing SettingsSection.
+    <>
       {teamIds.length > 0 && <TeamMembersPreloader teamIds={teamIds} />}
 
       <DataTable
@@ -111,11 +113,6 @@ export function TeamsTable({ teams, organizationId }: TeamsTableProps) {
           icon: Users,
           title: tEmpty('teams.title'),
           description: tEmpty('teams.description'),
-          action: {
-            label: tSettings('teams.createTeam'),
-            icon: Plus,
-            onClick: () => setCreateOpen(true),
-          },
         }}
         onRowClick={(row) => setSelectedTeam(row.original)}
         clickableRows
@@ -140,6 +137,6 @@ export function TeamsTable({ teams, organizationId }: TeamsTableProps) {
           }}
         />
       )}
-    </div>
+    </>
   );
 }
diff --git a/services/platform/app/features/settings/user-env/components/user-env-settings.tsx b/services/platform/app/features/settings/user-env/components/user-env-settings.tsx
index f75542f623..47dddc0ef2 100644
--- a/services/platform/app/features/settings/user-env/components/user-env-settings.tsx
+++ b/services/platform/app/features/settings/user-env/components/user-env-settings.tsx
@@ -1,15 +1,17 @@
 'use client';
 
+import { Alert } from '@tale/ui/alert';
 import { Button } from '@tale/ui/button';
 import { IconButton } from '@tale/ui/icon-button';
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { Skeletonize, useSkeleton } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
-import { ConvexError } from 'convex/values';
-import { Trash2 } from 'lucide-react';
+import { Plus, ShieldAlert, Trash2 } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
 import { DeleteDialog } from '@/app/components/ui/dialog/delete-dialog';
+import { FormDialog } from '@/app/components/ui/dialog/form-dialog';
 import { Input } from '@/app/components/ui/forms/input';
 import { Switch } from '@/app/components/ui/forms/switch';
 import { SettingsPage } from '@/app/features/settings/components/settings-page';
@@ -19,6 +21,7 @@ import { useFormatDate } from '@/app/hooks/use-format-date';
 import { useOrganizationId } from '@/app/hooks/use-organization-id';
 import { useToast } from '@/app/hooks/use-toast';
 import { useT } from '@/lib/i18n/client';
+import { convexErrorMessage } from '@/lib/utils/convex-error';
 
 import { useDeleteMyEnvVar, useUpsertMyEnvVar } from '../hooks/mutations';
 import { useMyEnv } from '../hooks/queries';
@@ -62,38 +65,45 @@ function UserEnvSettingsView({
   vars: EnvVar[];
 }) {
   const { t } = useT('userEnv');
+  const [addOpen, setAddOpen] = useState(false);
 
   return (
     <SettingsPage>
       <SettingsSection
         title={t('page.title')}
         description={t('page.description')}
+        action={
+          <Button icon={Plus} onClick={() => setAddOpen(true)}>
+            {t('add.button')}
+          </Button>
+        }
       >
-        <Text className="text-muted-foreground text-sm">{t('page.note')}</Text>
-        <AddEnvVarForm organizationId={organizationId} />
+        <Alert
+          variant="warning"
+          icon={ShieldAlert}
+          title={t('page.agentAccessTitle')}
+          description={t('page.note')}
+        />
         <EnvVarList organizationId={organizationId} vars={vars} />
       </SettingsSection>
+      <AddEnvVarDialog
+        organizationId={organizationId}
+        open={addOpen}
+        onOpenChange={setAddOpen}
+      />
     </SettingsPage>
   );
 }
 
-/** Pull `{ code, message }` off a thrown `ConvexError`, else the fallback. */
-function errorMessage(err: unknown, fallback: string): string {
-  if (err instanceof ConvexError) {
-    const data: unknown = err.data;
-    if (
-      data !== null &&
-      typeof data === 'object' &&
-      'message' in data &&
-      typeof data.message === 'string'
-    ) {
-      return data.message;
-    }
-  }
-  return fallback;
-}
-
-function AddEnvVarForm({ organizationId }: { organizationId: string }) {
+function AddEnvVarDialog({
+  organizationId,
+  open,
+  onOpenChange,
+}: {
+  organizationId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
   const { t } = useT('userEnv');
   const { toast } = useToast();
   const { mutateAsync: upsert, isPending } = useUpsertMyEnvVar();
@@ -108,12 +118,12 @@ function AddEnvVarForm({ organizationId }: { organizationId: string }) {
     trimmedKey.length > 0 &&
     (!KEY_RE.test(trimmedKey) || trimmedKey.length > KEY_MAX);
   // A secret's value must be non-empty (the backend rejects an empty secret).
-  const canSubmit =
+  const isValid =
     trimmedKey.length > 0 &&
     !keyInvalid &&
     value.length <= VALUE_MAX &&
-    (!isSecret || value.length > 0) &&
-    !isPending;
+    (!isSecret || value.length > 0);
+  const isDirty = trimmedKey.length > 0 || value.length > 0;
   // Interior whitespace (space/tab/newline after trimming the ends) almost
   // always means a token wrapped across terminal lines was pasted — a silent,
   // painful-to-debug corruption. Warn loudly but don't block: legitimately
@@ -128,67 +138,82 @@ function AddEnvVarForm({ organizationId }: { organizationId: string }) {
     setError(null);
   }, []);
 
-  const handleSubmit = useCallback(async () => {
-    if (!canSubmit) return;
-    setError(null);
-    try {
-      await upsert({
-        organizationId,
-        key: trimmedKey,
-        value,
-        isSecret,
-      });
-      toast({ title: t('toasts.saved'), variant: 'success' });
-      reset();
-    } catch (err) {
-      console.error('[user-env upsert]', err);
-      setError(errorMessage(err, t('errors.saveFailed')));
-    }
-  }, [
-    canSubmit,
-    upsert,
-    organizationId,
-    trimmedKey,
-    value,
-    isSecret,
-    toast,
-    t,
-    reset,
-  ]);
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      if (!next) reset();
+      onOpenChange(next);
+    },
+    [reset, onOpenChange],
+  );
+
+  const handleSubmit = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      if (!isValid || isPending) return;
+      setError(null);
+      try {
+        await upsert({
+          organizationId,
+          key: trimmedKey,
+          value,
+          isSecret,
+        });
+        toast({ title: t('toasts.saved'), variant: 'success' });
+        reset();
+        onOpenChange(false);
+      } catch (err) {
+        console.error('[user-env upsert]', err);
+        setError(convexErrorMessage(err, t('errors.saveFailed')));
+      }
+    },
+    [
+      isValid,
+      isPending,
+      upsert,
+      organizationId,
+      trimmedKey,
+      value,
+      isSecret,
+      toast,
+      t,
+      reset,
+      onOpenChange,
+    ],
+  );
 
   return (
-    <form
-      className="border-border flex flex-col gap-4 rounded-lg border p-4"
-      onSubmit={(e) => {
-        e.preventDefault();
-        void handleSubmit();
-      }}
+    <FormDialog
+      open={open}
+      onOpenChange={handleOpenChange}
+      title={t('add.title')}
+      isSubmitting={isPending}
+      isDirty={isDirty}
+      isValid={isValid}
+      confirmDiscardOnDirty
+      submitText={t('add.submit')}
+      onSubmit={handleSubmit}
     >
-      <div className="flex flex-col gap-4 sm:flex-row sm:items-start">
-        <Input
-          label={t('add.keyLabel')}
-          placeholder={t('add.keyPlaceholder')}
-          value={key}
-          onChange={(e) => setKey(e.target.value)}
-          maxLength={KEY_MAX}
-          errorMessage={keyInvalid ? t('add.keyInvalid') : undefined}
-          wrapperClassName="flex-1"
-          autoComplete="off"
-          spellCheck={false}
-        />
-        <Input
-          label={t('add.valueLabel')}
-          placeholder={t('add.valuePlaceholder')}
-          // Secret values render masked while typing and never round-trip back.
-          sensitive={isSecret}
-          value={value}
-          onChange={(e) => setValue(e.target.value)}
-          maxLength={VALUE_MAX}
-          wrapperClassName="flex-1"
-          autoComplete="off"
-          spellCheck={false}
-        />
-      </div>
+      <Input
+        label={t('add.keyLabel')}
+        placeholder={t('add.keyPlaceholder')}
+        value={key}
+        onChange={(e) => setKey(e.target.value)}
+        maxLength={KEY_MAX}
+        errorMessage={keyInvalid ? t('add.keyInvalid') : undefined}
+        autoComplete="off"
+        spellCheck={false}
+      />
+      <Input
+        label={t('add.valueLabel')}
+        placeholder={t('add.valuePlaceholder')}
+        // Secret values render masked while typing and never round-trip back.
+        sensitive={isSecret}
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        maxLength={VALUE_MAX}
+        autoComplete="off"
+        spellCheck={false}
+      />
       {showWhitespaceWarning && (
         <Text
           role="alert"
@@ -198,8 +223,7 @@ function AddEnvVarForm({ organizationId }: { organizationId: string }) {
         </Text>
       )}
       {/* Secret as a full-width settings row (label + help left, toggle pinned
-          right) so the toggle stays anchored to the right edge instead of
-          floating mid-row at full width. Add gets its own right-aligned row. */}
+          right) so the toggle stays anchored to the right edge. */}
       <SettingsRow
         label={t('add.secretLabel')}
         description={t('add.secretHelp')}
@@ -210,17 +234,12 @@ function AddEnvVarForm({ organizationId }: { organizationId: string }) {
           aria-label={t('add.secretLabel')}
         />
       </SettingsRow>
-      <div className="flex justify-end">
-        <Button type="submit" variant="primary" disabled={!canSubmit}>
-          {t('add.submit')}
-        </Button>
-      </div>
       {error && (
         <Text role="alert" className="text-destructive text-sm">
           {error}
         </Text>
       )}
-    </form>
+    </FormDialog>
   );
 }
 
@@ -236,15 +255,17 @@ function EnvVarList({
 
   if (loading) {
     return (
-      <ul className="divide-border divide-y" aria-hidden="true">
+      <Stack as="ul" gap={2} aria-hidden="true">
         {Array.from({ length: 3 }).map((_, i) => (
-          <li key={i} className="flex items-start gap-3 py-2">
-            <div className="flex-1" style={{ width: `${70 - i * 10}%` }}>
-              <SkeletonText />
-            </div>
+          <li
+            key={i}
+            className="border-border flex flex-col gap-0.5 rounded-lg border p-3"
+            style={{ width: `${90 - i * 8}%` }}
+          >
+            <SkeletonText />
           </li>
         ))}
-      </ul>
+      </Stack>
     );
   }
 
@@ -255,7 +276,7 @@ function EnvVarList({
   }
 
   return (
-    <ul className="divide-border divide-y">
+    <Stack as="ul" gap={2}>
       {vars.map((envVar) => (
         <EnvVarRow
           key={envVar.key}
@@ -263,7 +284,7 @@ function EnvVarList({
           envVar={envVar}
         />
       ))}
-    </ul>
+    </Stack>
   );
 }
 
@@ -300,9 +321,9 @@ function EnvVarRow({
   }, [deleteVar, organizationId, envVar.key, toast, t]);
 
   return (
-    <li className="flex items-start justify-between gap-3 py-3">
+    <li className="border-border flex items-start justify-between gap-3 rounded-lg border p-3">
       <div className="flex min-w-0 flex-col gap-0.5">
-        <div className="flex items-baseline gap-2">
+        <Row gap={2} align="baseline">
           <code className="text-foreground truncate text-sm font-medium">
             {envVar.key}
           </code>
@@ -311,7 +332,7 @@ function EnvVarRow({
               {t('list.secretBadge')}
             </span>
           )}
-        </div>
+        </Row>
         <code className="text-muted-foreground truncate font-mono text-xs">
           {displayValue}
         </code>
diff --git a/services/platform/app/features/settings/webdav/components/webdav-settings.tsx b/services/platform/app/features/settings/webdav/components/webdav-settings.tsx
index 7d23aa1982..d39c5ff31b 100644
--- a/services/platform/app/features/settings/webdav/components/webdav-settings.tsx
+++ b/services/platform/app/features/settings/webdav/components/webdav-settings.tsx
@@ -51,7 +51,7 @@ export function WebdavSettings(props: WebdavSettingsProps) {
   const url = `${props.siteOrigin}/dav/${props.orgSlug}/documents/`;
 
   return (
-    <Stack gap={8}>
+    <>
       <SettingsSection
         title={t('connectionDetails.title')}
         description={t('description')}
@@ -64,23 +64,22 @@ export function WebdavSettings(props: WebdavSettingsProps) {
             description={t('connectionDetails.usernameHelp')}
             copyAriaLabel={t('connectionDetails.copyUsername')}
           />
-          <div className="flex flex-col gap-1">
+          <Stack gap={1}>
             <Text as="span" variant="label">
               {t('connectionDetails.passwordLabel')}
             </Text>
             <Text as="span" variant="muted" className="text-sm">
               {t('connectionDetails.passwordHelp')}
             </Text>
-          </div>
+          </Stack>
         </Stack>
       </SettingsSection>
 
       <SettingsSection
-        className="border-border border-t pt-8"
         title={t('list.title')}
         description={t('create.description')}
         action={
-          <Button size="sm" icon={KeyRound} onClick={() => setCreateOpen(true)}>
+          <Button icon={KeyRound} onClick={() => setCreateOpen(true)}>
             {t('create.submit')}
           </Button>
         }
@@ -98,7 +97,7 @@ export function WebdavSettings(props: WebdavSettingsProps) {
         revealed={revealed}
         onClose={() => setRevealed(null)}
       />
-    </Stack>
+    </>
   );
 }
 
@@ -133,8 +132,8 @@ function WebdavAppPasswordsTable({
         ),
       },
       // Column sizes double as the table's min-width floor (DataTable sums
-      // them) — keep the total ≤ 540px so the table fits this page's
-      // `SettingsPage narrow` 544px column without horizontal scroll.
+      // them) — keep the total within the full-width settings page budget
+      // (≤ 940px) so the table never forces horizontal scroll.
       {
         accessorKey: 'prefix',
         header: t('list.prefix'),
@@ -231,7 +230,7 @@ function WebdavRowActions({ row }: { row: WebdavAppPasswordRow }) {
         size="icon"
         variant="ghost"
         icon={Trash2}
-        aria-label={t('list.revoke')}
+        title={t('list.revoke')}
         disabled={isRevoking}
         onClick={() => setOpen(true)}
       />
diff --git a/services/platform/app/features/skills/components/skill-asset-viewer.tsx b/services/platform/app/features/skills/components/skill-asset-viewer.tsx
index 24c21bab9b..00e9b62cad 100644
--- a/services/platform/app/features/skills/components/skill-asset-viewer.tsx
+++ b/services/platform/app/features/skills/components/skill-asset-viewer.tsx
@@ -158,7 +158,7 @@ export function SkillAssetViewer({
       className="flex h-full min-h-0 flex-col"
       label={assetPath}
     >
-      <div key={assetPath} className="flex h-full min-h-0 flex-col">
+      <Stack key={assetPath} gap={0} className="h-full min-h-0">
         <HStack
           gap={2}
           align="center"
@@ -277,7 +277,7 @@ export function SkillAssetViewer({
             </>
           )}
         </div>
-      </div>
+      </Stack>
     </Skeletonize>
   );
 }
diff --git a/services/platform/app/features/skills/components/skill-detail-panel.tsx b/services/platform/app/features/skills/components/skill-detail-panel.tsx
index 92d615f736..38befe8cd6 100644
--- a/services/platform/app/features/skills/components/skill-detail-panel.tsx
+++ b/services/platform/app/features/skills/components/skill-detail-panel.tsx
@@ -196,7 +196,6 @@ export function SkillDetailPanel({
               <>
                 <Button
                   variant="ghost"
-                  size="sm"
                   icon={RotateCw}
                   onClick={() => setReplaceDialogOpen(true)}
                   disabled={isDuplicating}
@@ -207,7 +206,6 @@ export function SkillDetailPanel({
                 </Button>
                 <Button
                   variant="ghost"
-                  size="sm"
                   icon={Copy}
                   onClick={() => void handleDuplicate()}
                   isLoading={isDuplicating}
@@ -217,7 +215,6 @@ export function SkillDetailPanel({
                 </Button>
                 <Button
                   variant="ghost"
-                  size="sm"
                   icon={Trash2}
                   onClick={() => setDeleteDialogOpen(true)}
                   disabled={isDuplicating}
diff --git a/services/platform/app/features/skills/components/skill-upload/skill-upload-dialog.tsx b/services/platform/app/features/skills/components/skill-upload/skill-upload-dialog.tsx
index a4b464442b..b0a1e553f3 100644
--- a/services/platform/app/features/skills/components/skill-upload/skill-upload-dialog.tsx
+++ b/services/platform/app/features/skills/components/skill-upload/skill-upload-dialog.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Stack } from '@tale/ui/layout';
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { ConfirmDialog } from '@/app/components/ui/dialog/confirm-dialog';
@@ -238,7 +239,7 @@ export function SkillUploadDialog({
         footer={footer}
         className="max-h-[90vh] grid-rows-[auto_1fr_auto] overflow-hidden"
       >
-        <div className="flex min-h-0 min-w-0 flex-col gap-4 overflow-hidden">
+        <Stack className="min-h-0 min-w-0 overflow-hidden">
           {state.step === 'upload' ? (
             <div className="min-h-0 min-w-0 flex-1 overflow-y-auto pr-2">
               <UploadStep onBundleParsed={state.setParsedBundle} />
@@ -248,7 +249,7 @@ export function SkillUploadDialog({
               <PreviewStep parsedBundle={state.parsedBundle} />
             </div>
           ) : null}
-        </div>
+        </Stack>
       </Dialog>
 
       <ConfirmDialog
diff --git a/services/platform/app/features/skills/components/skill-upload/steps/upload-step.tsx b/services/platform/app/features/skills/components/skill-upload/steps/upload-step.tsx
index 8e44c1f9f5..c102d00f0a 100644
--- a/services/platform/app/features/skills/components/skill-upload/steps/upload-step.tsx
+++ b/services/platform/app/features/skills/components/skill-upload/steps/upload-step.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { AlertCircle, Upload } from 'lucide-react';
 import { useCallback, useEffect, useState } from 'react';
@@ -150,13 +150,15 @@ export function UploadStep({ onBundleParsed }: UploadStepProps) {
       </FileUpload.Root>
 
       {error ? (
-        <div
-          className="bg-destructive/10 text-destructive flex items-start gap-2 rounded-md p-3 text-sm"
+        <Row
+          gap={2}
+          align="start"
+          className="bg-destructive/10 text-destructive rounded-md p-3 text-sm"
           role="alert"
         >
           <AlertCircle className="mt-0.5 size-4 shrink-0" />
           <pre className="font-sans whitespace-pre-wrap">{error}</pre>
-        </div>
+        </Row>
       ) : null}
     </Stack>
   );
diff --git a/services/platform/app/features/skills/components/skills-table.tsx b/services/platform/app/features/skills/components/skills-table.tsx
index 0ad2d45311..a5484e3964 100644
--- a/services/platform/app/features/skills/components/skills-table.tsx
+++ b/services/platform/app/features/skills/components/skills-table.tsx
@@ -204,7 +204,7 @@ export function SkillsTable({
   ) : null;
 
   return (
-    <Stack gap={2}>
+    <Stack gap={4}>
       {atCapReason}
       {bindingCaption}
       <DataTable
diff --git a/services/platform/app/features/tasks/components/assignee-picker.tsx b/services/platform/app/features/tasks/components/assignee-picker.tsx
index 1ad87d0c27..494860926a 100644
--- a/services/platform/app/features/tasks/components/assignee-picker.tsx
+++ b/services/platform/app/features/tasks/components/assignee-picker.tsx
@@ -172,7 +172,6 @@ export function AssigneePicker({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 className="w-full justify-start"
                 icon={UserX}
                 onClick={() => {
diff --git a/services/platform/app/features/tasks/components/board-column.tsx b/services/platform/app/features/tasks/components/board-column.tsx
index bc3beb5a2e..8cb36a5ee2 100644
--- a/services/platform/app/features/tasks/components/board-column.tsx
+++ b/services/platform/app/features/tasks/components/board-column.tsx
@@ -3,6 +3,7 @@ import {
   SortableContext,
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 
 import { useT } from '@/lib/i18n/client';
@@ -35,13 +36,17 @@ export function BoardColumn({
   });
 
   return (
-    <section className="bg-muted/40 flex w-[80vw] max-w-72 shrink-0 snap-start flex-col rounded-lg sm:w-72">
-      <div className="flex items-center justify-between gap-2 px-2.5 py-2">
+    <Stack
+      as="section"
+      gap={0}
+      className="bg-muted/40 w-[80vw] max-w-72 shrink-0 snap-start rounded-lg sm:w-72"
+    >
+      <Row gap={2} justify="between" className="px-2.5 py-2">
         <TaskStatusBadge status={status} />
         <Text as="span" variant="caption" className="pr-1 tabular-nums">
           {tasks.length}
         </Text>
-      </div>
+      </Row>
       <div
         ref={setNodeRef}
         className={cn(
@@ -64,11 +69,15 @@ export function BoardColumn({
           ))}
         </SortableContext>
         {tasks.length === 0 && (
-          <div className="border-border text-muted-foreground m-1 flex flex-1 items-center justify-center rounded-lg border border-dashed px-3 py-6 text-center text-xs">
+          <Row
+            gap={0}
+            justify="center"
+            className="border-border text-muted-foreground m-1 flex-1 rounded-lg border border-dashed px-3 py-6 text-center text-xs"
+          >
             {t('board.noTasks')}
-          </div>
+          </Row>
         )}
       </div>
-    </section>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/tasks/components/kanban-board.tsx b/services/platform/app/features/tasks/components/kanban-board.tsx
index 442c258464..ae809164ad 100644
--- a/services/platform/app/features/tasks/components/kanban-board.tsx
+++ b/services/platform/app/features/tasks/components/kanban-board.tsx
@@ -1,4 +1,5 @@
 import { DndContext, DragOverlay } from '@dnd-kit/core';
+import { Row } from '@tale/ui/layout';
 import { useMemo } from 'react';
 
 import { useTaskBoardDnd } from '../hooks/use-task-board-dnd';
@@ -39,7 +40,11 @@ export function KanbanBoard({
       onDragCancel={dnd.onDragCancel}
       autoScroll={dnd.autoScroll}
     >
-      <div className="flex h-full snap-x gap-3 overflow-x-auto px-0.5 pb-4">
+      <Row
+        gap={3}
+        align="stretch"
+        className="h-full snap-x overflow-x-auto px-0.5 pb-4"
+      >
         {TASK_STATUS_ORDER.map((status) => (
           <BoardColumn
             key={status}
@@ -52,7 +57,7 @@ export function KanbanBoard({
             projectKey={projectKey}
           />
         ))}
-      </div>
+      </Row>
       <DragOverlay>
         {dnd.activeTask ? (
           <TaskCard
diff --git a/services/platform/app/features/tasks/components/label-editor.tsx b/services/platform/app/features/tasks/components/label-editor.tsx
index e8c2e4cd82..b2188d968c 100644
--- a/services/platform/app/features/tasks/components/label-editor.tsx
+++ b/services/platform/app/features/tasks/components/label-editor.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Grid, Row, Stack } from '@tale/ui/layout';
 import { Popover } from '@tale/ui/popover';
 import { ArrowLeft, Check, Plus, Search, X } from 'lucide-react';
 import { useMemo, useState, type KeyboardEvent } from 'react';
@@ -173,7 +174,7 @@ export function LabelEditor({
             />
           ) : (
             <>
-              <div className="border-border flex items-center gap-2 border-b p-2.5">
+              <Row gap={2} className="border-border border-b p-2.5">
                 <Search
                   className="text-muted-foreground size-3.5 shrink-0"
                   aria-hidden="true"
@@ -192,7 +193,7 @@ export function LabelEditor({
                   onKeyDown={onSearchKeyDown}
                   className="placeholder:text-muted-foreground flex-1 bg-transparent text-sm outline-none"
                 />
-              </div>
+              </Row>
               <div
                 role="listbox"
                 aria-multiselectable="true"
@@ -292,7 +293,7 @@ function ColorSwatchView({
 }) {
   const { t } = useT('tasks');
   return (
-    <div className="flex flex-col gap-1 p-1">
+    <Stack gap={1} className="p-1">
       <div className="flex items-center gap-1.5 p-1">
         <button
           type="button"
@@ -306,7 +307,7 @@ function ColorSwatchView({
           {label}
         </span>
       </div>
-      <div className="grid grid-cols-5 gap-1 p-1">
+      <Grid cols={5} gap={1} className="p-1">
         {TASK_LABEL_COLORS.map((color) => (
           <button
             key={color}
@@ -325,7 +326,7 @@ function ColorSwatchView({
             />
           </button>
         ))}
-      </div>
-    </div>
+      </Grid>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/tasks/components/project-metrics-page.tsx b/services/platform/app/features/tasks/components/project-metrics-page.tsx
index 51e921aceb..3819640eef 100644
--- a/services/platform/app/features/tasks/components/project-metrics-page.tsx
+++ b/services/platform/app/features/tasks/components/project-metrics-page.tsx
@@ -1,29 +1,30 @@
 'use client';
 
-import { EmptyState } from '@tale/ui/empty-state';
+import { Alert } from '@tale/ui/alert';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS, getChartSeriesColor } from '@tale/ui/chart-theme';
+import { Grid, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
+import { Sparkline } from '@tale/ui/sparkline';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
 import { Text } from '@tale/ui/text';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
 import { Link } from '@tanstack/react-router';
-import { BarChart3, ChevronLeft } from 'lucide-react';
-import { useMemo, type ReactNode } from 'react';
-import {
-  Area,
-  AreaChart,
-  Bar,
-  BarChart,
-  CartesianGrid,
-  Line,
-  LineChart,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from 'recharts';
+import { AlertTriangle, BarChart3, ChevronLeft } from 'lucide-react';
+import { useMemo } from 'react';
 
 import { ContentArea } from '@/app/components/layout/content-area';
-import { PageHeader } from '@/app/components/layout/page-header';
-import { Select } from '@/app/components/ui/forms/select';
+import {
+  seriesToLegend,
+  TrendAreaChart,
+  TrendBarChart,
+  TrendLineChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
+import { MetricSelect } from '@/app/components/metrics/metric-select';
+import { MetricsLayout } from '@/app/components/metrics/metrics-layout';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { api } from '@/convex/_generated/api';
 import type { Id } from '@/convex/_generated/dataModel';
@@ -60,6 +61,54 @@ interface ProjectMetricsDay {
   capped: boolean;
 }
 
+interface ProjectTotals {
+  created: number;
+  completed: number;
+  agent: number;
+  human: number;
+  cycleSum: number;
+  cycleCount: number;
+  cost: number;
+  runs: number;
+  failed: number;
+  changes: number;
+  escalations: number;
+  capped: boolean;
+}
+
+function reduceTotals(days: ProjectMetricsDay[]): ProjectTotals {
+  return days.reduce<ProjectTotals>(
+    (acc, day) => ({
+      created: acc.created + day.tasksCreated,
+      completed: acc.completed + day.tasksCompleted,
+      agent: acc.agent + day.agentCompleted,
+      human: acc.human + day.humanCompleted,
+      cycleSum: acc.cycleSum + day.cycleTimeSumMs,
+      cycleCount: acc.cycleCount + day.cycleTimeCount,
+      cost: acc.cost + day.totalCostCents,
+      runs: acc.runs + day.agentRunsStarted,
+      failed: acc.failed + day.agentRunsFailed,
+      changes: acc.changes + day.reviewsChangesRequested,
+      escalations: acc.escalations + day.escalations,
+      capped: acc.capped || day.capped,
+    }),
+    {
+      created: 0,
+      completed: 0,
+      agent: 0,
+      human: 0,
+      cycleSum: 0,
+      cycleCount: 0,
+      cost: 0,
+      runs: 0,
+      failed: 0,
+      changes: 0,
+      escalations: 0,
+      capped: false,
+    },
+  );
+}
+
 function formatCents(cents: number): string {
   return (cents / 100).toLocaleString(undefined, {
     minimumFractionDigits: 2,
@@ -67,55 +116,18 @@ function formatCents(cents: number): string {
   });
 }
 
-function shortDay(dateKey: string): string {
-  return dateKey.slice(5);
+function avgCycleHours(t: ProjectTotals): number | undefined {
+  return t.cycleCount > 0 ? t.cycleSum / t.cycleCount / 3_600_000 : undefined;
 }
 
-/**
- * One bordered chart card. The card chrome (title) always renders; the chart
- * slot masks itself while loading and falls back to an `EmptyState` when the
- * period has no data — the page never goes blank.
- */
-function ChartCard({
-  title,
-  heightClassName,
-  isLoading,
-  isEmpty,
-  emptyTitle,
-  emptyDescription,
-  children,
-}: {
-  title: string;
-  heightClassName: string;
-  isLoading: boolean;
-  isEmpty: boolean;
-  emptyTitle: string;
-  emptyDescription: string;
-  children: ReactNode;
-}) {
-  return (
-    <section className="border-border bg-card rounded-lg border p-4">
-      <Text as="h3" variant="label">
-        {title}
-      </Text>
-      <div className={`mt-3 ${heightClassName}`}>
-        {isLoading ? (
-          <SkeletonBox fullWidth>
-            <div className={`w-full ${heightClassName}`} />
-          </SkeletonBox>
-        ) : isEmpty ? (
-          <EmptyState
-            icon={BarChart3}
-            title={emptyTitle}
-            description={emptyDescription}
-            className="h-full py-0"
-          />
-        ) : (
-          children
-        )}
-      </div>
-    </section>
-  );
+function interventionRateOf(t: ProjectTotals): number {
+  return t.runs > 0
+    ? Math.round(((t.changes + t.escalations) / t.runs) * 100)
+    : 0;
+}
+
+function shortDay(dateKey: string): string {
+  return dateKey.slice(5);
 }
 
 interface ProjectMetricsPageProps {
@@ -126,12 +138,12 @@ interface ProjectMetricsPageProps {
 }
 
 /**
- * The project's dedicated metrics page (mirrors the automations metrics
- * page): period switcher, paired-KPI stat cards honoring the KPI pairing
- * contract, and the task charts — cumulative flow from the EOD status
- * snapshots, created-vs-completed throughput, the cycle-time trend,
- * agent-vs-human completions, and daily spend. Reads only the per-project
- * daily rollups.
+ * The project's dedicated metrics page (mirrors the automations metrics page):
+ * period switcher, paired-KPI stat cards honoring the KPI pairing contract
+ * with period-over-period deltas, and the task charts — cumulative flow,
+ * created-vs-completed throughput, the cycle-time trend, agent-vs-human
+ * completions, and daily spend. Reads only the per-project daily rollups; all
+ * charts share the chart-theme tokens (theme-aware in dark mode).
  */
 export function ProjectMetricsPage({
   organizationId,
@@ -147,6 +159,7 @@ export function ProjectMetricsPage({
   );
   // The query returns v.any(); the shape is owned by getProjectTaskMetrics.
   const daily: ProjectMetricsDay[] = data?.daily ?? [];
+  const previousDaily: ProjectMetricsDay[] = data?.previousDaily ?? [];
 
   const periodOptions = useMemo(
     () => [
@@ -157,56 +170,25 @@ export function ProjectMetricsPage({
     [t],
   );
 
-  const totals = daily.reduce(
-    (acc, day) => ({
-      created: acc.created + day.tasksCreated,
-      completed: acc.completed + day.tasksCompleted,
-      agent: acc.agent + day.agentCompleted,
-      human: acc.human + day.humanCompleted,
-      cycleSum: acc.cycleSum + day.cycleTimeSumMs,
-      cycleCount: acc.cycleCount + day.cycleTimeCount,
-      cost: acc.cost + day.totalCostCents,
-      runs: acc.runs + day.agentRunsStarted,
-      failed: acc.failed + day.agentRunsFailed,
-      changes: acc.changes + day.reviewsChangesRequested,
-      escalations: acc.escalations + day.escalations,
-      capped: acc.capped || day.capped,
-    }),
-    {
-      created: 0,
-      completed: 0,
-      agent: 0,
-      human: 0,
-      cycleSum: 0,
-      cycleCount: 0,
-      cost: 0,
-      runs: 0,
-      failed: 0,
-      changes: 0,
-      escalations: 0,
-      capped: false,
-    },
-  );
-  const avgCycleHours =
-    totals.cycleCount > 0
-      ? (totals.cycleSum / totals.cycleCount / 3_600_000).toFixed(1)
-      : undefined;
-  const interventionRate =
-    totals.runs > 0
-      ? Math.round(((totals.changes + totals.escalations) / totals.runs) * 100)
-      : 0;
+  const totals = reduceTotals(daily);
+  const prev = reduceTotals(previousDaily);
+
+  const cycleHours = avgCycleHours(totals);
+  const prevCycleHours = avgCycleHours(prev);
+  const interventionRate = interventionRateOf(totals);
+  const prevInterventionRate = interventionRateOf(prev);
 
   const flowData = daily.map((day) => ({
-    label: shortDay(day.dateKey),
+    dateKey: day.dateKey,
     ...day.statusCountsEod,
   }));
   const throughputData = daily.map((day) => ({
-    label: shortDay(day.dateKey),
+    dateKey: day.dateKey,
     completed: day.tasksCompleted,
     created: day.tasksCreated,
   }));
   const cycleTimeData = daily.map((day) => ({
-    label: shortDay(day.dateKey),
+    dateKey: day.dateKey,
     hours:
       day.cycleTimeCount > 0
         ? Number(
@@ -215,12 +197,12 @@ export function ProjectMetricsPage({
         : null,
   }));
   const completionsData = daily.map((day) => ({
-    label: shortDay(day.dateKey),
+    dateKey: day.dateKey,
     agent: day.agentCompleted,
     human: day.humanCompleted,
   }));
   const costData = daily.map((day) => ({
-    label: shortDay(day.dateKey),
+    dateKey: day.dateKey,
     cost: Number((day.totalCostCents / 100).toFixed(2)),
   }));
 
@@ -229,35 +211,48 @@ export function ProjectMetricsPage({
   const emptyTitle = t('metrics.noData');
   const emptyDescription = t('metrics.noDataDescription');
 
-  const stats = [
+  const flowSeries: ChartSeries[] = [
+    {
+      key: 'backlog',
+      label: t('status.backlog'),
+      color: getChartSeriesColor(0),
+    },
+    { key: 'todo', label: t('status.todo'), color: getChartSeriesColor(1) },
     {
-      label: t('metrics.completed', { days: periodDays }),
-      value: String(totals.completed),
-      detail: t('metrics.completedDetail', {
-        agent: totals.agent,
-        human: totals.human,
-      }),
+      key: 'in_progress',
+      label: t('status.in_progress'),
+      color: getChartSeriesColor(2),
     },
     {
-      label: t('metrics.cycleTime'),
-      value: avgCycleHours !== undefined ? `${avgCycleHours}h` : '—',
-      detail: t('metrics.created', { count: totals.created }),
+      key: 'in_review',
+      label: t('status.in_review'),
+      color: getChartSeriesColor(3),
     },
+  ];
+  const throughputSeries: ChartSeries[] = [
     {
-      label: t('metrics.intervention'),
-      value: `${interventionRate}%`,
-      detail: t('metrics.interventionDetail', {
-        changes: totals.changes,
-        escalations: totals.escalations,
-      }),
+      key: 'created',
+      label: t('metrics.createdLabel'),
+      color: CHART_COLORS.primary,
     },
     {
-      label: t('metrics.cost', { days: periodDays }),
-      value: formatCents(totals.cost),
-      detail: t('metrics.costDetail', {
-        runs: totals.runs,
-        failed: totals.failed,
-      }),
+      key: 'completed',
+      label: t('metrics.completedLabel'),
+      color: CHART_COLORS.success,
+    },
+  ];
+  const completionsSeries: ChartSeries[] = [
+    {
+      key: 'agent',
+      label: t('metrics.agentLabel'),
+      color: CHART_COLORS.success,
+      stackId: 'completions',
+    },
+    {
+      key: 'human',
+      label: t('metrics.humanLabel'),
+      color: CHART_COLORS.primary,
+      stackId: 'completions',
     },
   ];
 
@@ -274,218 +269,232 @@ export function ProjectMetricsPage({
           <ChevronLeft className="size-4" aria-hidden="true" />
           {t('title')}
         </Link>
-        <PageHeader
+        <MetricsLayout
           title={t('metrics.title')}
           description={t('metrics.description')}
-          action={
-            <div className="w-44 shrink-0">
-              <Select
-                options={periodOptions}
-                value={String(periodDays)}
-                onValueChange={(v) => {
-                  const next = Number(v);
-                  if (next === 7 || next === 30 || next === 90)
-                    onChangePeriod(next);
-                }}
-                size="sm"
+          toolbar={
+            <MetricSelect
+              aria-label={t('metrics.period.label')}
+              options={periodOptions}
+              value={String(periodDays)}
+              onValueChange={(v) => {
+                const next = Number(v);
+                if (next === 7 || next === 30 || next === 90)
+                  onChangePeriod(next);
+              }}
+            />
+          }
+          notice={
+            !isLoading && totals.capped ? (
+              <Alert
+                variant="warning"
+                icon={AlertTriangle}
+                title={t('metrics.cappedNotice')}
               />
-            </div>
+            ) : undefined
           }
-        />
-
-        {!isLoading && totals.capped ? (
-          <div className="border-border bg-muted/40 rounded-md border px-3 py-2 text-xs">
-            {t('metrics.cappedNotice')}
-          </div>
-        ) : null}
-
-        <section className="grid grid-cols-2 gap-3 lg:grid-cols-4">
-          {stats.map((stat) => (
-            <div
-              key={stat.label}
-              className="border-border bg-card flex flex-col gap-1 rounded-lg border p-3"
+        >
+          <StatCardGrid cols={4}>
+            <StatCard
+              label={t('metrics.completed', { days: periodDays })}
+              value={String(totals.completed)}
             >
-              <Text as="p" variant="muted" className="text-xs">
-                {stat.label}
-              </Text>
-              <SkeletonBox>
-                <Text as="p" className="text-xl font-semibold tabular-nums">
-                  {stat.value}
-                </Text>
-              </SkeletonBox>
-              <SkeletonBox>
-                <Text as="p" variant="muted" className="text-xs">
-                  {stat.detail}
-                </Text>
-              </SkeletonBox>
-            </div>
-          ))}
-        </section>
+              <Stack gap={1} className="mt-0.5">
+                <TrendIndicator
+                  value={totals.completed}
+                  previous={prev.completed}
+                />
+                <SkeletonBox>
+                  <Text as="p" variant="muted" className="text-xs">
+                    {t('metrics.completedDetail', {
+                      agent: totals.agent,
+                      human: totals.human,
+                    })}
+                  </Text>
+                </SkeletonBox>
+                {daily.length > 1 ? (
+                  <Sparkline
+                    data={daily.map((day) => day.tasksCompleted)}
+                    filled
+                    color="var(--color-chart-success)"
+                    className="mt-1"
+                  />
+                ) : null}
+              </Stack>
+            </StatCard>
 
-        <ChartCard
-          title={t('metrics.cumulativeFlow')}
-          heightClassName="h-52"
-          isLoading={isLoading}
-          isEmpty={noDays}
-          emptyTitle={emptyTitle}
-          emptyDescription={emptyDescription}
-        >
-          <ResponsiveContainer width="100%" height="100%">
-            <AreaChart data={flowData}>
-              <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-              <XAxis dataKey="label" fontSize={11} />
-              <YAxis allowDecimals={false} fontSize={11} width={28} />
-              <Tooltip />
-              <Area
-                dataKey="backlog"
-                stackId="flow"
-                name={t('status.backlog')}
-                fill="#94a3b8"
-                stroke="#94a3b8"
-              />
-              <Area
-                dataKey="todo"
-                stackId="flow"
-                name={t('status.todo')}
-                fill="#60a5fa"
-                stroke="#60a5fa"
-              />
-              <Area
-                dataKey="in_progress"
-                stackId="flow"
-                name={t('status.in_progress')}
-                fill="#f59e0b"
-                stroke="#f59e0b"
-              />
-              <Area
-                dataKey="in_review"
-                stackId="flow"
-                name={t('status.in_review')}
-                fill="#a78bfa"
-                stroke="#a78bfa"
-              />
-            </AreaChart>
-          </ResponsiveContainer>
-        </ChartCard>
+            <StatCard
+              label={t('metrics.cycleTime')}
+              value={
+                cycleHours !== undefined ? `${cycleHours.toFixed(1)}h` : '—'
+              }
+            >
+              <Stack gap={1} className="mt-0.5">
+                {cycleHours !== undefined ? (
+                  <TrendIndicator
+                    value={cycleHours}
+                    previous={prevCycleHours}
+                    inverted
+                  />
+                ) : null}
+                <SkeletonBox>
+                  <Text as="p" variant="muted" className="text-xs">
+                    {t('metrics.created', { count: totals.created })}
+                  </Text>
+                </SkeletonBox>
+              </Stack>
+            </StatCard>
 
-        <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-          <ChartCard
-            title={t('metrics.throughput')}
-            heightClassName="h-44"
-            isLoading={isLoading}
-            isEmpty={noDays}
-            emptyTitle={emptyTitle}
-            emptyDescription={emptyDescription}
-          >
-            <ResponsiveContainer width="100%" height="100%">
-              <BarChart data={throughputData}>
-                <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-                <XAxis dataKey="label" fontSize={11} />
-                <YAxis allowDecimals={false} fontSize={11} width={28} />
-                <Tooltip />
-                <Bar
-                  dataKey="created"
-                  name={t('metrics.createdLabel')}
-                  fill="#60a5fa"
-                  radius={[2, 2, 0, 0]}
-                />
-                <Bar
-                  dataKey="completed"
-                  name={t('metrics.completedLabel')}
-                  fill="var(--color-chart-success, #10b981)"
-                  radius={[2, 2, 0, 0]}
+            <StatCard
+              label={t('metrics.intervention')}
+              value={`${interventionRate}%`}
+            >
+              <Stack gap={1} className="mt-0.5">
+                <TrendIndicator
+                  value={interventionRate}
+                  previous={prevInterventionRate}
+                  inverted
                 />
-              </BarChart>
-            </ResponsiveContainer>
-          </ChartCard>
+                <SkeletonBox>
+                  <Text as="p" variant="muted" className="text-xs">
+                    {t('metrics.interventionDetail', {
+                      changes: totals.changes,
+                      escalations: totals.escalations,
+                    })}
+                  </Text>
+                </SkeletonBox>
+              </Stack>
+            </StatCard>
 
-          <ChartCard
-            title={t('metrics.cycleTimeTrend')}
-            heightClassName="h-44"
-            isLoading={isLoading}
-            isEmpty={noCycleTimes}
-            emptyTitle={emptyTitle}
-            emptyDescription={emptyDescription}
-          >
-            <ResponsiveContainer width="100%" height="100%">
-              <LineChart data={cycleTimeData}>
-                <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-                <XAxis dataKey="label" fontSize={11} />
-                <YAxis fontSize={11} width={28} />
-                <Tooltip />
-                <Line
-                  dataKey="hours"
-                  name={t('metrics.cycleHoursLabel')}
-                  stroke="#a78bfa"
-                  dot={false}
-                  connectNulls
+            <StatCard
+              label={t('metrics.cost', { days: periodDays })}
+              value={formatCents(totals.cost)}
+            >
+              <Stack gap={1} className="mt-0.5">
+                <TrendIndicator
+                  value={totals.cost}
+                  previous={prev.cost}
+                  inverted
                 />
-              </LineChart>
-            </ResponsiveContainer>
-          </ChartCard>
-        </div>
+                <SkeletonBox>
+                  <Text as="p" variant="muted" className="text-xs">
+                    {t('metrics.costDetail', {
+                      runs: totals.runs,
+                      failed: totals.failed,
+                    })}
+                  </Text>
+                </SkeletonBox>
+              </Stack>
+            </StatCard>
+          </StatCardGrid>
 
-        <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
           <ChartCard
-            title={t('metrics.agentVsHuman')}
-            heightClassName="h-44"
-            isLoading={isLoading}
+            title={t('metrics.cumulativeFlow')}
+            bodyClassName="h-52"
+            loading={isLoading}
             isEmpty={noDays}
+            emptyIcon={BarChart3}
             emptyTitle={emptyTitle}
             emptyDescription={emptyDescription}
+            legend={<ChartLegend items={seriesToLegend(flowSeries)} />}
           >
-            <ResponsiveContainer width="100%" height="100%">
-              <BarChart data={completionsData}>
-                <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-                <XAxis dataKey="label" fontSize={11} />
-                <YAxis allowDecimals={false} fontSize={11} width={28} />
-                <Tooltip />
-                <Bar
-                  dataKey="agent"
-                  stackId="completions"
-                  name={t('metrics.agentLabel')}
-                  fill="var(--color-chart-success, #10b981)"
-                  radius={[0, 0, 0, 0]}
-                />
-                <Bar
-                  dataKey="human"
-                  stackId="completions"
-                  name={t('metrics.humanLabel')}
-                  fill="#60a5fa"
-                  radius={[2, 2, 0, 0]}
-                />
-              </BarChart>
-            </ResponsiveContainer>
+            <TrendAreaChart
+              data={flowData}
+              series={flowSeries}
+              xKey="dateKey"
+              xTickFormatter={shortDay}
+            />
           </ChartCard>
 
-          <ChartCard
-            title={t('metrics.costTrend')}
-            heightClassName="h-44"
-            isLoading={isLoading}
-            isEmpty={noDays}
-            emptyTitle={emptyTitle}
-            emptyDescription={emptyDescription}
-          >
-            <ResponsiveContainer width="100%" height="100%">
-              <BarChart data={costData}>
-                <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
-                <XAxis dataKey="label" fontSize={11} />
-                <YAxis fontSize={11} width={36} />
-                <Tooltip
-                  formatter={(value) =>
-                    typeof value === 'number' ? formatCents(value * 100) : ''
-                  }
-                />
-                <Bar
-                  dataKey="cost"
-                  name={t('metrics.costLabel')}
-                  fill="#f59e0b"
-                  radius={[2, 2, 0, 0]}
-                />
-              </BarChart>
-            </ResponsiveContainer>
-          </ChartCard>
-        </div>
+          <Grid lg={2}>
+            <ChartCard
+              title={t('metrics.throughput')}
+              bodyClassName="h-44"
+              loading={isLoading}
+              isEmpty={noDays}
+              emptyIcon={BarChart3}
+              emptyTitle={emptyTitle}
+              emptyDescription={emptyDescription}
+              legend={<ChartLegend items={seriesToLegend(throughputSeries)} />}
+            >
+              <TrendBarChart
+                data={throughputData}
+                series={throughputSeries}
+                xKey="dateKey"
+                xTickFormatter={shortDay}
+              />
+            </ChartCard>
+
+            <ChartCard
+              title={t('metrics.cycleTimeTrend')}
+              bodyClassName="h-44"
+              loading={isLoading}
+              isEmpty={noCycleTimes}
+              emptyIcon={BarChart3}
+              emptyTitle={emptyTitle}
+              emptyDescription={emptyDescription}
+            >
+              <TrendLineChart
+                data={cycleTimeData}
+                series={[
+                  {
+                    key: 'hours',
+                    label: t('metrics.cycleHoursLabel'),
+                    color: getChartSeriesColor(3),
+                  },
+                ]}
+                xKey="dateKey"
+                xTickFormatter={shortDay}
+                valueFormatter={(v) => `${v.toFixed(1)}h`}
+              />
+            </ChartCard>
+          </Grid>
+
+          <Grid lg={2}>
+            <ChartCard
+              title={t('metrics.agentVsHuman')}
+              bodyClassName="h-44"
+              loading={isLoading}
+              isEmpty={noDays}
+              emptyIcon={BarChart3}
+              emptyTitle={emptyTitle}
+              emptyDescription={emptyDescription}
+              legend={<ChartLegend items={seriesToLegend(completionsSeries)} />}
+            >
+              <TrendBarChart
+                data={completionsData}
+                series={completionsSeries}
+                xKey="dateKey"
+                xTickFormatter={shortDay}
+              />
+            </ChartCard>
+
+            <ChartCard
+              title={t('metrics.costTrend')}
+              bodyClassName="h-44"
+              loading={isLoading}
+              isEmpty={noDays}
+              emptyIcon={BarChart3}
+              emptyTitle={emptyTitle}
+              emptyDescription={emptyDescription}
+            >
+              <TrendBarChart
+                data={costData}
+                series={[
+                  {
+                    key: 'cost',
+                    label: t('metrics.costLabel'),
+                    color: CHART_COLORS.warning,
+                  },
+                ]}
+                xKey="dateKey"
+                xTickFormatter={shortDay}
+                allowDecimals
+                valueFormatter={(v) => formatCents(v * 100)}
+              />
+            </ChartCard>
+          </Grid>
+        </MetricsLayout>
       </Skeletonize>
     </ContentArea>
   );
diff --git a/services/platform/app/features/tasks/components/task-agent-runs.tsx b/services/platform/app/features/tasks/components/task-agent-runs.tsx
index cd504ecae1..2c0eeed9dc 100644
--- a/services/platform/app/features/tasks/components/task-agent-runs.tsx
+++ b/services/platform/app/features/tasks/components/task-agent-runs.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Bot } from 'lucide-react';
 
@@ -40,8 +41,8 @@ export function TaskAgentRuns({ taskId }: { taskId: Id<'tasks'> }) {
   const totalCostCents = runs.reduce((sum, run) => sum + run.costCents, 0);
 
   return (
-    <section className="flex flex-col gap-2">
-      <div className="flex items-center justify-between gap-2">
+    <Stack as="section" gap={2}>
+      <Row gap={2} justify="between">
         <div className="flex items-center gap-1.5">
           <Bot className="text-muted-foreground size-4" aria-hidden />
           <Text as="h3" variant="label">
@@ -53,7 +54,7 @@ export function TaskAgentRuns({ taskId }: { taskId: Id<'tasks'> }) {
             {t('agentRuns.totalCost', { amount: formatCents(totalCostCents) })}
           </Text>
         )}
-      </div>
+      </Row>
       <ul className="border-border divide-border divide-y overflow-hidden rounded-lg border">
         {runs.map((run) => (
           <li
@@ -83,6 +84,6 @@ export function TaskAgentRuns({ taskId }: { taskId: Id<'tasks'> }) {
           </li>
         ))}
       </ul>
-    </section>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/tasks/components/task-card.tsx b/services/platform/app/features/tasks/components/task-card.tsx
index e7cf428e83..327bd482fa 100644
--- a/services/platform/app/features/tasks/components/task-card.tsx
+++ b/services/platform/app/features/tasks/components/task-card.tsx
@@ -1,5 +1,7 @@
 import { useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
+import { Card } from '@tale/ui/card';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { GitBranch } from 'lucide-react';
 
@@ -68,22 +70,13 @@ export function TaskCard({
   };
 
   return (
-    // oxlint-disable-next-line jsx-a11y/no-static-element-interactions -- draggable kanban card; dnd-kit's {...sortable.attributes} injects role/tabIndex at runtime and keyboard activation is handled via onKeyDown
-    <div
-      ref={sortable.setNodeRef}
-      style={style}
-      {...sortable.attributes}
-      {...sortable.listeners}
-      onClick={() => onOpen?.(task)}
-      onKeyDown={(e) => {
-        if (e.key === 'Enter' || e.key === ' ') {
-          e.preventDefault();
-          onOpen?.(task);
-        }
-      }}
+    <Card
+      asChild
+      padding="sm"
+      shadow="sm"
+      interactive
       className={cn(
-        'group border-border bg-card cursor-pointer rounded-lg border p-3 text-left shadow-sm transition-[colors,box-shadow]',
-        'hover:border-border-strong hover:shadow-md focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none',
+        'group cursor-pointer text-left hover:shadow-md',
         // While dragging, the in-place card becomes a faint placeholder marking
         // the slot the floating overlay will land in.
         sortable.isDragging && 'opacity-40',
@@ -91,69 +84,84 @@ export function TaskCard({
         dragging && 'ring-border rotate-1 shadow-lg ring-1',
       )}
     >
-      {identifier && (
-        <Text
-          as="span"
-          variant="caption"
-          className="font-mono text-[10px] tracking-wide"
-        >
-          {identifier}
+      {/* oxlint-disable-next-line jsx-a11y/no-static-element-interactions -- draggable kanban card; dnd-kit's {...sortable.attributes} injects role/tabIndex at runtime and keyboard activation is handled via onKeyDown */}
+      <div
+        ref={sortable.setNodeRef}
+        style={style}
+        {...sortable.attributes}
+        {...sortable.listeners}
+        onClick={() => onOpen?.(task)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            onOpen?.(task);
+          }
+        }}
+      >
+        {identifier && (
+          <Text
+            as="span"
+            variant="caption"
+            className="font-mono text-[10px] tracking-wide"
+          >
+            {identifier}
+          </Text>
+        )}
+        <Text as="p" variant="label" className="line-clamp-2 leading-snug">
+          {task.title}
         </Text>
-      )}
-      <Text as="p" variant="label" className="line-clamp-2 leading-snug">
-        {task.title}
-      </Text>
 
-      {task.labels && task.labels.length > 0 && (
-        <div className="mt-2 flex flex-wrap gap-1">
-          {task.labels.slice(0, 4).map((label) => (
-            <TaskLabelBadge
-              key={label}
-              label={label}
-              projectId={task.projectId}
-              className="px-1.5 py-px text-[10px]"
-            />
-          ))}
-          <TaskLabelOverflow labels={task.labels.slice(4)} />
-        </div>
-      )}
+        {task.labels && task.labels.length > 0 && (
+          <Row gap={1} align="stretch" wrap className="mt-2">
+            {task.labels.slice(0, 4).map((label) => (
+              <TaskLabelBadge
+                key={label}
+                label={label}
+                projectId={task.projectId}
+                className="px-1.5 py-px text-[10px]"
+              />
+            ))}
+            <TaskLabelOverflow labels={task.labels.slice(4)} />
+          </Row>
+        )}
 
-      <div className="mt-3 flex items-center justify-between gap-2">
-        <div className="flex items-center gap-1.5">
-          <PriorityPicker
-            priority={task.priority ?? null}
-            onChange={(priority) =>
-              updateTask.mutate({ taskId: task._id, priority })
+        <Row gap={2} justify="between" className="mt-3">
+          <div className="flex items-center gap-1.5">
+            <PriorityPicker
+              priority={task.priority ?? null}
+              onChange={(priority) =>
+                updateTask.mutate({ taskId: task._id, priority })
+              }
+            />
+            {task.parentTaskId && (
+              <Tooltip content={parentLabel}>
+                <span className="inline-flex" aria-label={parentLabel}>
+                  <GitBranch
+                    className="text-muted-foreground size-3.5"
+                    aria-hidden="true"
+                  />
+                </span>
+              </Tooltip>
+            )}
+            <BlockedIndicator blocked={blocked} />
+            <AgentWorkingIndicator working={isAgentWorking(task._id)} />
+            <NeedsReviewIndicator needsReview={needsReview(task._id)} />
+            <DueDateIndicator dueDate={task.dueDate} status={task.status} />
+            {total > 0 && <SubtaskProgress done={done} total={total} />}
+            <CommentCountIndicator count={task.commentCount} />
+          </div>
+          <AssigneePicker
+            organizationId={task.organizationId}
+            projectId={task.projectId}
+            assigneeType={task.assigneeType}
+            assigneeId={task.assigneeId}
+            onAssign={(assigneeType, assigneeId) =>
+              assignTask.mutate({ taskId: task._id, assigneeType, assigneeId })
             }
+            onUnassign={() => assignTask.mutate({ taskId: task._id })}
           />
-          {task.parentTaskId && (
-            <Tooltip content={parentLabel}>
-              <span className="inline-flex" aria-label={parentLabel}>
-                <GitBranch
-                  className="text-muted-foreground size-3.5"
-                  aria-hidden="true"
-                />
-              </span>
-            </Tooltip>
-          )}
-          <BlockedIndicator blocked={blocked} />
-          <AgentWorkingIndicator working={isAgentWorking(task._id)} />
-          <NeedsReviewIndicator needsReview={needsReview(task._id)} />
-          <DueDateIndicator dueDate={task.dueDate} status={task.status} />
-          {total > 0 && <SubtaskProgress done={done} total={total} />}
-          <CommentCountIndicator count={task.commentCount} />
-        </div>
-        <AssigneePicker
-          organizationId={task.organizationId}
-          projectId={task.projectId}
-          assigneeType={task.assigneeType}
-          assigneeId={task.assigneeId}
-          onAssign={(assigneeType, assigneeId) =>
-            assignTask.mutate({ taskId: task._id, assigneeType, assigneeId })
-          }
-          onUnassign={() => assignTask.mutate({ taskId: task._id })}
-        />
+        </Row>
       </div>
-    </div>
+    </Card>
   );
 }
diff --git a/services/platform/app/features/tasks/components/task-comments.tsx b/services/platform/app/features/tasks/components/task-comments.tsx
index d56cf25c77..54f8dd4ab0 100644
--- a/services/platform/app/features/tasks/components/task-comments.tsx
+++ b/services/platform/app/features/tasks/components/task-comments.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { useState } from 'react';
 
@@ -131,7 +132,7 @@ export function TaskComments({
     const author = resolveActor(c.authorType, c.authorId);
     const isEditing = editingId === c.messageId;
     return (
-      <div className="group/comment flex items-start gap-2">
+      <Row gap={2} align="start" className="group/comment">
         <AssigneeAvatar
           assigneeType={c.authorType}
           assigneeId={c.authorId}
@@ -153,7 +154,7 @@ export function TaskComments({
           </div>
 
           {isEditing ? (
-            <div className="mt-1 flex flex-col gap-2">
+            <Stack gap={2} className="mt-1">
               <MentionTextarea
                 id={`edit-comment-${c.messageId}`}
                 organizationId={organizationId}
@@ -164,23 +165,18 @@ export function TaskComments({
                 onKeyDown={onModEnter(() => void submitEdit(c.messageId))}
                 autoFocus
               />
-              <div className="flex gap-2">
+              <Row gap={2} align="stretch">
                 <Button
-                  size="sm"
                   disabled={editDraft.trim().length === 0}
                   onClick={() => void submitEdit(c.messageId)}
                 >
                   {tCommon('actions.save')}
                 </Button>
-                <Button
-                  size="sm"
-                  variant="secondary"
-                  onClick={() => setEditingId(null)}
-                >
+                <Button variant="secondary" onClick={() => setEditingId(null)}>
                   {tCommon('actions.cancel')}
                 </Button>
-              </div>
-            </div>
+              </Row>
+            </Stack>
           ) : (
             <MentionText
               body={c.body}
@@ -191,7 +187,10 @@ export function TaskComments({
           )}
 
           {!isEditing && canEdit && (
-            <div className="mt-1 flex items-center gap-3 text-xs opacity-0 transition-opacity group-focus-within/comment:opacity-100 group-hover/comment:opacity-100">
+            <Row
+              gap={3}
+              className="mt-1 text-xs opacity-0 transition-opacity group-focus-within/comment:opacity-100 group-hover/comment:opacity-100"
+            >
               {canManage(c) && (
                 <CommentAction
                   onClick={() => {
@@ -210,10 +209,10 @@ export function TaskComments({
                   {tCommon('actions.delete')}
                 </CommentAction>
               )}
-            </div>
+            </Row>
           )}
         </div>
-      </div>
+      </Row>
     );
   };
 
@@ -223,7 +222,7 @@ export function TaskComments({
         {t('detail.comments')} ({comments.length})
       </Text>
 
-      <ul className="mt-3 flex flex-col gap-4">
+      <Stack as="ul" className="mt-3">
         {comments.length === 0 && (
           <li>
             <Text as="p" variant="muted">
@@ -234,10 +233,10 @@ export function TaskComments({
         {comments.map((c) => (
           <li key={c.messageId}>{renderItem(c)}</li>
         ))}
-      </ul>
+      </Stack>
 
       {canEdit && (
-        <div className="mt-4 flex items-start gap-2">
+        <Row gap={2} align="start" className="mt-4">
           {currentUser && (
             <AssigneeAvatar
               assigneeType="user"
@@ -245,7 +244,7 @@ export function TaskComments({
               name={currentUser.name}
             />
           )}
-          <div className="flex min-w-0 flex-1 flex-col gap-2">
+          <Stack gap={2} className="min-w-0 flex-1">
             <MentionTextarea
               id="new-comment"
               organizationId={organizationId}
@@ -261,17 +260,16 @@ export function TaskComments({
               target={{ taskId }}
               draft={draft}
             />
-            <div className="flex justify-end">
+            <Row gap={0} align="stretch" justify="end">
               <Button
-                size="sm"
                 disabled={draft.trim().length === 0}
                 onClick={() => void submitNew()}
               >
                 {t('actions.comment')}
               </Button>
-            </div>
-          </div>
-        </div>
+            </Row>
+          </Stack>
+        </Row>
       )}
     </section>
   );
diff --git a/services/platform/app/features/tasks/components/task-dependencies.tsx b/services/platform/app/features/tasks/components/task-dependencies.tsx
index 26841331fd..f1b97b6762 100644
--- a/services/platform/app/features/tasks/components/task-dependencies.tsx
+++ b/services/platform/app/features/tasks/components/task-dependencies.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { ConvexError } from 'convex/values';
 import { Plus, X } from 'lucide-react';
@@ -79,7 +80,7 @@ export function TaskDependencies({
   return (
     // Lives in the modal's side property panel — the heading mirrors the
     // panel's PropertyField label style so the column reads as one list.
-    <section className="flex flex-col gap-3">
+    <Stack as="section" gap={3}>
       <h3 className="text-muted-foreground text-xs font-medium">
         {t('detail.dependencies')}
       </h3>
@@ -119,7 +120,7 @@ export function TaskDependencies({
             .catch(onMutationError)
         }
       />
-    </section>
+    </Stack>
   );
 }
 
@@ -155,7 +156,7 @@ function DependencyGroup({
 
   return (
     <div className="flex flex-col gap-1.5">
-      <div className="flex items-center justify-between">
+      <Row gap={0} justify="between">
         <Text as="span" variant="caption">
           {label}
         </Text>
@@ -179,7 +180,6 @@ function DependencyGroup({
               <Button
                 type="button"
                 variant="ghost"
-                size="sm"
                 icon={Plus}
                 className="text-muted-foreground -mr-1 h-auto px-1.5 py-0.5"
               >
@@ -188,9 +188,9 @@ function DependencyGroup({
             }
           />
         )}
-      </div>
+      </Row>
       {items.length > 0 ? (
-        <ul className="flex flex-col gap-1">
+        <Stack as="ul" gap={1}>
           {items.map((item) => (
             <li key={item._id} className="flex items-center gap-1">
               <button
@@ -220,14 +220,14 @@ function DependencyGroup({
                   variant="ghost"
                   size="icon"
                   icon={X}
-                  aria-label={t('detail.removeDependency')}
+                  title={t('detail.removeDependency')}
                   className="text-muted-foreground hover:text-foreground size-7 shrink-0"
                   onClick={() => onRemove(item._id)}
                 />
               )}
             </li>
           ))}
-        </ul>
+        </Stack>
       ) : (
         <Text as="p" variant="muted" className="text-xs">
           {t('detail.noDependencies')}
diff --git a/services/platform/app/features/tasks/components/task-modal.tsx b/services/platform/app/features/tasks/components/task-modal.tsx
index a1e50e3939..b9fe6d35ea 100644
--- a/services/platform/app/features/tasks/components/task-modal.tsx
+++ b/services/platform/app/features/tasks/components/task-modal.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import {
   ResponsiveDialog,
   ResponsiveDialogContent,
@@ -133,7 +134,7 @@ function ModalLayout({
   footer?: ReactNode;
 }) {
   return (
-    <div className="flex min-h-0 flex-1 flex-col gap-4">
+    <Stack className="min-h-0 flex-1">
       <div className="shrink-0">{header}</div>
       {/* Inside the fixed-height edit dialog each column owns its scroll; in
           the auto-height create dialog these min-h/overflow rules are inert.
@@ -144,15 +145,21 @@ function ModalLayout({
           the scrollport slightly so focus rings on full-width fields aren't
           clipped at the column edge. */}
       <div className="flex min-h-0 flex-1 flex-col gap-6 md:flex-row md:gap-0">
-        <div className="flex min-w-0 flex-1 flex-col gap-5 md:-ml-2 md:min-h-0 md:overflow-y-auto md:py-0.5 md:pr-6 md:pl-2">
+        <Stack
+          gap={5}
+          className="min-w-0 flex-1 md:-ml-2 md:min-h-0 md:overflow-y-auto md:py-0.5 md:pr-6 md:pl-2"
+        >
           {main}
-        </div>
-        <aside className="flex shrink-0 flex-col gap-4 md:-mr-2 md:min-h-0 md:w-[15.5rem] md:overflow-y-auto md:border-l md:py-0.5 md:pr-2 md:pl-6">
+        </Stack>
+        <Stack
+          as="aside"
+          className="shrink-0 md:-mr-2 md:min-h-0 md:w-[15.5rem] md:overflow-y-auto md:border-l md:py-0.5 md:pr-2 md:pl-6"
+        >
           {panel}
-        </aside>
+        </Stack>
       </div>
       {footer && <div className="shrink-0">{footer}</div>}
-    </div>
+    </Stack>
   );
 }
 
@@ -178,12 +185,12 @@ function PropertyField({
     );
   }
   return (
-    <div className="flex min-h-7 items-center gap-2">
+    <Row gap={2} className="min-h-7">
       <span className="text-muted-foreground w-20 shrink-0 text-xs font-medium">
         {label}
       </span>
       <div className="min-w-0 flex-1">{children}</div>
-    </div>
+    </Row>
   );
 }
 
@@ -330,7 +337,7 @@ function CreateTaskBody({
         </>
       }
       footer={
-        <div className="flex items-center justify-end gap-2">
+        <Row gap={2} justify="end">
           <Button variant="secondary" onClick={onClose} disabled={submitting}>
             {tCommon('actions.cancel')}
           </Button>
@@ -340,7 +347,7 @@ function CreateTaskBody({
           >
             {t('actions.create')}
           </Button>
-        </div>
+        </Row>
       }
     />
   );
@@ -421,7 +428,7 @@ function EditTaskBody({
   return (
     <ModalLayout
       header={
-        <div className="flex flex-col gap-2">
+        <Stack gap={2}>
           {identifier && (
             <Text
               as="span"
@@ -450,7 +457,7 @@ function EditTaskBody({
               {task.title}
             </h2>
           )}
-        </div>
+        </Stack>
       }
       main={
         <>
@@ -492,15 +499,15 @@ function EditTaskBody({
 
           <TaskAgentRuns taskId={task._id} />
 
-          <section className="flex flex-col gap-2">
-            <div className="flex items-center gap-2">
+          <Stack as="section" gap={2}>
+            <Row gap={2}>
               <Text as="h3" variant="label">
                 {t('detail.subtasks')}
               </Text>
               {subtasksTotal > 0 && (
                 <SubtaskProgress done={subtasksDone} total={subtasksTotal} />
               )}
-            </div>
+            </Row>
             {subtasks.length > 0 && (
               <ul className="border-border divide-border divide-y overflow-hidden rounded-lg border">
                 {subtasks.map((sub) => {
@@ -556,7 +563,7 @@ function EditTaskBody({
               </ul>
             )}
             {canEdit && (
-              <div className="flex items-center gap-2">
+              <Row gap={2}>
                 <Textarea
                   id="new-subtask"
                   rows={1}
@@ -572,7 +579,6 @@ function EditTaskBody({
                   className="min-h-0"
                 />
                 <Button
-                  size="sm"
                   icon={Plus}
                   variant="secondary"
                   disabled={subtaskTitle.trim().length === 0}
@@ -580,9 +586,9 @@ function EditTaskBody({
                 >
                   {t('actions.add')}
                 </Button>
-              </div>
+              </Row>
             )}
-          </section>
+          </Stack>
 
           <TaskComments
             taskId={task._id}
@@ -597,7 +603,7 @@ function EditTaskBody({
             <Text as="h3" variant="label">
               {t('detail.activity')}
             </Text>
-            <ul className="mt-3 flex flex-col gap-3">
+            <Stack as="ul" gap={3} className="mt-3">
               {activity.map((entry) => {
                 const labelKey = TASK_ACTIVITY_LABEL_KEY[entry.action];
                 const label = labelKey ? t(labelKey) : entry.action;
@@ -637,7 +643,7 @@ function EditTaskBody({
                   </li>
                 );
               })}
-            </ul>
+            </Stack>
           </section>
         </>
       }
@@ -854,14 +860,12 @@ function EditableDescription({
         baseline={value}
       />
       {isDirty && (
-        <div className="flex gap-2">
-          <Button size="sm" onClick={save}>
-            {tCommon('actions.save')}
-          </Button>
-          <Button size="sm" variant="secondary" onClick={discard}>
+        <Row gap={2} align="stretch">
+          <Button onClick={save}>{tCommon('actions.save')}</Button>
+          <Button variant="secondary" onClick={discard}>
             {tCommon('actions.discard')}
           </Button>
-        </div>
+        </Row>
       )}
     </>
   );
diff --git a/services/platform/app/features/tasks/components/task-review-card.tsx b/services/platform/app/features/tasks/components/task-review-card.tsx
index 302df29779..998f1828fe 100644
--- a/services/platform/app/features/tasks/components/task-review-card.tsx
+++ b/services/platform/app/features/tasks/components/task-review-card.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Bot, CheckCircle2 } from 'lucide-react';
 import { useState } from 'react';
@@ -52,11 +53,13 @@ export function TaskReviewCard({ taskId }: { taskId: Id<'tasks'> }) {
   };
 
   return (
-    <section
-      className="border-primary/40 bg-primary/5 flex flex-col gap-3 rounded-lg border p-3"
+    <Stack
+      as="section"
+      gap={3}
+      className="border-primary/40 bg-primary/5 rounded-lg border p-3"
       aria-label={t('review.needsReview')}
     >
-      <div className="flex items-start gap-2">
+      <Row gap={2} align="start">
         <Bot className="text-primary mt-0.5 size-4 shrink-0" aria-hidden />
         <div className="flex flex-col gap-0.5">
           <Text as="h3" variant="label">
@@ -69,10 +72,10 @@ export function TaskReviewCard({ taskId }: { taskId: Id<'tasks'> }) {
               })}
           </Text>
         </div>
-      </div>
+      </Row>
 
       {requestingChanges ? (
-        <div className="flex flex-col gap-2">
+        <Stack gap={2}>
           <Textarea
             value={feedback}
             onChange={(e) => setFeedback(e.target.value)}
@@ -80,9 +83,8 @@ export function TaskReviewCard({ taskId }: { taskId: Id<'tasks'> }) {
             rows={3}
             autoFocus
           />
-          <div className="flex items-center justify-end gap-2">
+          <Row gap={2} justify="end">
             <Button
-              size="sm"
               variant="ghost"
               onClick={() => setRequestingChanges(false)}
               disabled={respond.isPending}
@@ -90,19 +92,17 @@ export function TaskReviewCard({ taskId }: { taskId: Id<'tasks'> }) {
               {tCommon('actions.cancel')}
             </Button>
             <Button
-              size="sm"
               variant="secondary"
               onClick={() => void submit('request_changes')}
               disabled={respond.isPending || feedback.trim().length === 0}
             >
               {t('review.sendFeedback')}
             </Button>
-          </div>
-        </div>
+          </Row>
+        </Stack>
       ) : (
-        <div className="flex items-center gap-2">
+        <Row gap={2}>
           <Button
-            size="sm"
             icon={CheckCircle2}
             onClick={() => void submit('approve')}
             disabled={respond.isPending}
@@ -110,15 +110,14 @@ export function TaskReviewCard({ taskId }: { taskId: Id<'tasks'> }) {
             {t('review.approve')}
           </Button>
           <Button
-            size="sm"
             variant="secondary"
             onClick={() => setRequestingChanges(true)}
             disabled={respond.isPending}
           >
             {t('review.requestChanges')}
           </Button>
-        </div>
+        </Row>
       )}
-    </section>
+    </Stack>
   );
 }
diff --git a/services/platform/app/features/tasks/components/tasks-list.tsx b/services/platform/app/features/tasks/components/tasks-list.tsx
index 594786e9e3..a321c363ed 100644
--- a/services/platform/app/features/tasks/components/tasks-list.tsx
+++ b/services/platform/app/features/tasks/components/tasks-list.tsx
@@ -5,6 +5,7 @@ import {
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
+import { Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { ChevronRight } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
@@ -160,7 +161,7 @@ function ListSwimlane({
     <section>
       {/* Slim, Linear-style section header: a single full-width toggle
           (chevron + status + count). */}
-      <div className="bg-background sticky top-0 z-10 flex items-center gap-2 px-3 py-1.5">
+      <Row gap={2} className="bg-background sticky top-0 z-10 px-3 py-1.5">
         <button
           type="button"
           aria-expanded={!isCollapsed}
@@ -179,7 +180,7 @@ function ListSwimlane({
             {rows.length}
           </Text>
         </button>
-      </div>
+      </Row>
       {!isCollapsed && (
         <div ref={setNodeRef} className={cn(isOver && 'bg-accent/30')}>
           <SortableContext
diff --git a/services/platform/app/features/tasks/components/tasks-skeleton.tsx b/services/platform/app/features/tasks/components/tasks-skeleton.tsx
index 39c9eeff63..61027e9f7e 100644
--- a/services/platform/app/features/tasks/components/tasks-skeleton.tsx
+++ b/services/platform/app/features/tasks/components/tasks-skeleton.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Tabs } from '@tale/ui/tabs';
@@ -25,14 +26,14 @@ function TaskCardSkeleton({ titleWidth }: { titleWidth: string }) {
           <div className="h-3.5" />
         </SkeletonBox>
       </div>
-      <div className="mt-3 flex items-center justify-between">
+      <Row gap={0} justify="between" className="mt-3">
         <SkeletonBox>
           <div className="h-3.5 w-10" />
         </SkeletonBox>
         <SkeletonBox>
           <div className="size-6 rounded-full" />
         </SkeletonBox>
-      </div>
+      </Row>
     </div>
   );
 }
@@ -51,29 +52,35 @@ export function TasksSkeleton({ view }: { view: TaskView }) {
   if (view === 'board') {
     return (
       <Skeletonize loading>
-        <div className="flex min-h-0 flex-1 gap-3 overflow-hidden px-0.5 pb-4">
+        <Row
+          gap={3}
+          align="stretch"
+          className="min-h-0 flex-1 overflow-hidden px-0.5 pb-4"
+        >
           {TASK_STATUS_ORDER.map((status, col) => (
-            <section
+            <Stack
               key={status}
-              className="bg-muted/40 flex w-[80vw] max-w-72 shrink-0 flex-col rounded-lg sm:w-72"
+              as="section"
+              gap={0}
+              className="bg-muted/40 w-[80vw] max-w-72 shrink-0 rounded-lg sm:w-72"
             >
-              <div className="flex items-center justify-between gap-2 px-2.5 py-2">
+              <Row gap={2} justify="between" className="px-2.5 py-2">
                 <TaskStatusBadge status={status} />
                 <SkeletonBox>
                   <div className="h-3.5 w-4" />
                 </SkeletonBox>
-              </div>
-              <div className="flex flex-col gap-2 overflow-hidden px-2 pt-0.5 pb-2">
+              </Row>
+              <Stack gap={2} className="overflow-hidden px-2 pt-0.5 pb-2">
                 {Array.from({ length: 5 }).map((_, card) => (
                   <TaskCardSkeleton
                     key={card}
                     titleWidth={`${55 + (((col + card) * 17) % 36)}%`}
                   />
                 ))}
-              </div>
-            </section>
+              </Stack>
+            </Stack>
           ))}
-        </div>
+        </Row>
       </Skeletonize>
     );
   }
@@ -82,7 +89,7 @@ export function TasksSkeleton({ view }: { view: TaskView }) {
       <div className="min-h-0 flex-1 overflow-hidden">
         {TASK_STATUS_ORDER.map((status, section) => (
           <section key={status}>
-            <div className="bg-background flex items-center gap-2 px-3 py-1.5">
+            <Row gap={2} className="bg-background px-3 py-1.5">
               <span className="text-muted-foreground -ml-1 flex items-center gap-2 p-1">
                 <ChevronRight
                   className="size-3.5 shrink-0 rotate-90"
@@ -93,7 +100,7 @@ export function TasksSkeleton({ view }: { view: TaskView }) {
                   <div className="h-3.5 w-4" />
                 </SkeletonBox>
               </span>
-            </div>
+            </Row>
             {Array.from({ length: 5 }).map((_, row) => (
               <div
                 key={row}
@@ -141,7 +148,7 @@ export function TasksPageSkeleton({ view }: { view: TaskView }) {
   const { t } = useT('tasks');
   return (
     <ContentArea gap={4} className="flex h-full flex-col py-4">
-      <div className="flex items-center justify-between gap-3">
+      <Row gap={3} justify="between">
         <Tabs
           variant="pill"
           value={view}
@@ -151,16 +158,16 @@ export function TasksPageSkeleton({ view }: { view: TaskView }) {
           ]}
         />
         <Skeletonize loading>
-          <div className="flex items-center gap-2">
+          <Row gap={2}>
             <SkeletonBox>
               <div className="h-8 w-24 rounded-md" />
             </SkeletonBox>
             <SkeletonBox>
               <div className="h-8 w-20 rounded-md" />
             </SkeletonBox>
-          </div>
+          </Row>
         </Skeletonize>
-      </div>
+      </Row>
       <TasksSkeleton view={view} />
     </ContentArea>
   );
diff --git a/services/platform/app/features/tasks/components/tasks-workspace.tsx b/services/platform/app/features/tasks/components/tasks-workspace.tsx
index b3fa52d6e3..bd70935056 100644
--- a/services/platform/app/features/tasks/components/tasks-workspace.tsx
+++ b/services/platform/app/features/tasks/components/tasks-workspace.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button, LinkButton } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { Tabs } from '@tale/ui/tabs';
 import { BarChart3, Plus } from 'lucide-react';
 import { useState } from 'react';
@@ -82,7 +83,7 @@ export function TasksWorkspace({
 
   return (
     <ContentArea gap={4} className="flex h-full flex-col py-4">
-      <div className="flex items-center justify-between gap-3">
+      <Row gap={3} justify="between">
         <Tabs
           variant="pill"
           value={view}
@@ -94,7 +95,7 @@ export function TasksWorkspace({
             { value: 'list', label: t('views.list') },
           ]}
         />
-        <div className="flex items-center gap-2">
+        <Row gap={2}>
           <LinkButton
             href="/dashboard/$id/projects/$projectId/metrics"
             params={{ id: organizationId, projectId }}
@@ -107,8 +108,8 @@ export function TasksWorkspace({
           <Button size="sm" icon={Plus} onClick={() => setCreateOpen(true)}>
             {t('actions.create')}
           </Button>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       {isFirstLoad ? (
         <TasksSkeleton view={view} />
diff --git a/services/platform/app/features/vendors/components/vendor-delete-dialog.tsx b/services/platform/app/features/vendors/components/vendor-delete-dialog.tsx
index 74dc578082..3d268c9a1a 100644
--- a/services/platform/app/features/vendors/components/vendor-delete-dialog.tsx
+++ b/services/platform/app/features/vendors/components/vendor-delete-dialog.tsx
@@ -65,7 +65,7 @@ export function VendorDeleteDialog({
           variant="ghost"
           size="icon"
           onClick={dialog.open}
-          aria-label={tVendors('deleteVendor')}
+          title={tVendors('deleteVendor')}
           className="hover:bg-transparent"
         >
           <Trash2 className="size-4" />
diff --git a/services/platform/app/features/vendors/components/vendors-table.tsx b/services/platform/app/features/vendors/components/vendors-table.tsx
index bc4ecb5fd8..dcd6cb6bdb 100644
--- a/services/platform/app/features/vendors/components/vendors-table.tsx
+++ b/services/platform/app/features/vendors/components/vendors-table.tsx
@@ -2,12 +2,11 @@
 
 import { useNavigate } from '@tanstack/react-router';
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { Plus, Store } from 'lucide-react';
+import { Store } from 'lucide-react';
 import { useCallback, useMemo, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { BulkDeleteBar } from '@/app/components/ui/data-table/data-table-bulk-actions';
-import { useAbility } from '@/app/hooks/use-ability';
 import { useListPage } from '@/app/hooks/use-list-page';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { useT } from '@/lib/i18n/client';
@@ -129,9 +128,6 @@ export function VendorsTable({
 
   const [viewingVendor, setViewingVendor] = useState<Vendor | null>(null);
   const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
-  const ability = useAbility();
-  const canWrite = ability.can('write', 'knowledgeWrite');
-  // Lifted so the action menu and the empty-state CTA share one dialog.
   const [createOpen, setCreateOpen] = useState(false);
   const deleteVendor = useDeleteVendor();
 
@@ -194,13 +190,6 @@ export function VendorsTable({
           icon: Store,
           title: tEmpty('vendors.title'),
           description: tEmpty('vendors.description'),
-          action: canWrite
-            ? {
-                label: tVendors('addButton'),
-                icon: Plus,
-                onClick: () => setCreateOpen(true),
-              }
-            : undefined,
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/websites/components/website-pages-dialog.tsx b/services/platform/app/features/websites/components/website-pages-dialog.tsx
index 4d9795b43f..a3082263a3 100644
--- a/services/platform/app/features/websites/components/website-pages-dialog.tsx
+++ b/services/platform/app/features/websites/components/website-pages-dialog.tsx
@@ -5,6 +5,7 @@ import { Button } from '@tale/ui/button';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
 import { EmptyState } from '@tale/ui/empty-state';
 import { Heading } from '@tale/ui/heading';
+import { Row } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Spinner } from '@tale/ui/spinner';
@@ -98,7 +99,7 @@ function PageRow({
           </a>
         </Text>
       )}
-      <div className="text-muted-foreground flex gap-4 text-xs">
+      <Row align="stretch" className="text-muted-foreground text-xs">
         <span>
           <SkeletonBox>
             {t('pagesDialog.wordCount', { count: page.word_count })}
@@ -116,7 +117,7 @@ function PageRow({
             })}
           </span>
         )}
-      </div>
+      </Row>
     </div>
   );
 
@@ -125,9 +126,9 @@ function PageRow({
       <CollapsibleDetails summary={summary} onToggle={handleToggle}>
         <div className="mt-3 space-y-2">
           {isPending && (
-            <div className="flex justify-center py-2">
+            <Row gap={0} align="stretch" justify="center" className="py-2">
               <Spinner size="sm" />
-            </div>
+            </Row>
           )}
           {chunks?.length === 0 && (
             <Text variant="muted" className="text-sm">
@@ -156,7 +157,7 @@ function SearchResultItem({ result }: { result: CrawlerSearchResult }) {
   return (
     <BorderedSection>
       <div className="space-y-2">
-        <div className="flex items-start justify-between gap-2">
+        <Row gap={2} align="start" justify="between">
           <Heading level={3} size="sm" weight="medium">
             {result.title || result.url}
           </Heading>
@@ -165,7 +166,7 @@ function SearchResultItem({ result }: { result: CrawlerSearchResult }) {
               score: (result.score * 100).toFixed(0) + '%',
             })}
           </Text>
-        </div>
+        </Row>
         <Text variant="caption">
           <a
             href={result.url}
@@ -295,7 +296,7 @@ export function WebsitePagesDialog({
       size="wide"
     >
       <div className="min-h-[400px] space-y-4">
-        <div className="flex gap-2">
+        <Row gap={2} align="stretch">
           <SearchInput
             value={searchQuery}
             onChange={handleSearchChange}
@@ -312,14 +313,14 @@ export function WebsitePagesDialog({
           >
             <SearchIcon className="size-4" />
           </Button>
-        </div>
+        </Row>
 
         {isSearchMode ? (
           <>
             {isSearching && (
-              <div className="flex justify-center py-4">
+              <Row gap={0} align="stretch" justify="center" className="py-4">
                 <Spinner size="sm" />
-              </div>
+              </Row>
             )}
 
             {!isSearching && searchResults.length === 0 && (
@@ -359,16 +360,15 @@ export function WebsitePagesDialog({
             </Skeletonize>
 
             {hasMore && (
-              <div className="flex justify-center pt-2">
+              <Row gap={0} align="stretch" justify="center" className="pt-2">
                 <Button
                   variant="secondary"
-                  size="sm"
                   onClick={loadMore}
                   disabled={isPending}
                 >
                   {isPending ? '...' : t('pagesDialog.loadMore')}
                 </Button>
-              </div>
+              </Row>
             )}
           </>
         )}
diff --git a/services/platform/app/features/websites/components/website-view-dialog.tsx b/services/platform/app/features/websites/components/website-view-dialog.tsx
index 2d056bcf66..b0052325bd 100644
--- a/services/platform/app/features/websites/components/website-view-dialog.tsx
+++ b/services/platform/app/features/websites/components/website-view-dialog.tsx
@@ -6,7 +6,7 @@ import { Button } from '@tale/ui/button';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
 import { EmptyState } from '@tale/ui/empty-state';
 import { Heading } from '@tale/ui/heading';
-import { HStack } from '@tale/ui/layout';
+import { Grid, HStack, Row } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Spinner } from '@tale/ui/spinner';
@@ -110,7 +110,7 @@ function PageRow({
           </a>
         </Text>
       )}
-      <div className="text-muted-foreground flex gap-4 text-xs">
+      <Row align="stretch" className="text-muted-foreground text-xs">
         <span>
           <SkeletonBox>
             {t('pagesDialog.wordCount', { count: page.word_count })}
@@ -128,7 +128,7 @@ function PageRow({
             })}
           </span>
         )}
-      </div>
+      </Row>
     </div>
   );
 
@@ -137,9 +137,9 @@ function PageRow({
       <CollapsibleDetails summary={summary} onToggle={handleToggle}>
         <div className="mt-3 space-y-2">
           {isPending && (
-            <div className="flex justify-center py-2">
+            <Row gap={0} align="stretch" justify="center" className="py-2">
               <Spinner size="sm" />
-            </div>
+            </Row>
           )}
           {chunks?.length === 0 && (
             <Text variant="muted" className="text-sm">
@@ -168,7 +168,7 @@ function SearchResultItem({ result }: { result: CrawlerSearchResult }) {
   return (
     <BorderedSection>
       <div className="space-y-2">
-        <div className="flex min-w-0 items-start justify-between gap-2">
+        <Row gap={2} align="start" justify="between" className="min-w-0">
           <Heading
             level={3}
             size="sm"
@@ -182,7 +182,7 @@ function SearchResultItem({ result }: { result: CrawlerSearchResult }) {
               score: (result.score * 100).toFixed(0) + '%',
             })}
           </Text>
-        </div>
+        </Row>
         <Text variant="caption">
           <a
             href={result.url}
@@ -330,7 +330,7 @@ export function ViewWebsiteDialog({
       {
         label: t('viewDialog.status'),
         value: (
-          <div className="flex flex-wrap items-center gap-2">
+          <Row gap={2} wrap>
             <Badge
               variant={
                 website.status && website.status in statusVariant
@@ -357,7 +357,7 @@ export function ViewWebsiteDialog({
                 {String(website.metadata.lastSyncError)}
               </Text>
             )}
-          </div>
+          </Row>
         ),
       },
       {
@@ -419,7 +419,7 @@ export function ViewWebsiteDialog({
           </Text>
         </HStack>
 
-        <div className="flex gap-2">
+        <Row gap={2} align="stretch">
           <SearchInput
             value={searchQuery}
             onChange={handleSearchChange}
@@ -436,14 +436,14 @@ export function ViewWebsiteDialog({
           >
             <SearchIcon className="size-4" />
           </Button>
-        </div>
+        </Row>
 
         {isSearchMode ? (
           <>
             {isSearching && (
-              <div className="flex justify-center py-4">
+              <Row gap={0} align="stretch" justify="center" className="py-4">
                 <Spinner size="sm" />
-              </div>
+              </Row>
             )}
 
             {!isSearching && searchResults.length === 0 && (
@@ -467,7 +467,7 @@ export function ViewWebsiteDialog({
             )}
 
             <Skeletonize loading={isFirstLoad && isPending}>
-              <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-3">
+              <Grid sm={2} xl={3} gap={3}>
                 {(isFirstLoad && isPending
                   ? [
                       { ...PLACEHOLDER_PAGE, url: 'placeholder-1' },
@@ -478,14 +478,13 @@ export function ViewWebsiteDialog({
                 ).map((page) => (
                   <PageRow key={page.url} page={page} websiteId={website._id} />
                 ))}
-              </div>
+              </Grid>
             </Skeletonize>
 
             {hasMore && (
-              <div className="flex justify-center pt-2">
+              <Row gap={0} align="stretch" justify="center" className="pt-2">
                 <Button
                   variant="secondary"
-                  size="sm"
                   onClick={loadMore}
                   disabled={isPending}
                 >
@@ -495,7 +494,7 @@ export function ViewWebsiteDialog({
                     t('pagesDialog.loadMore')
                   )}
                 </Button>
-              </div>
+              </Row>
             )}
           </>
         )}
diff --git a/services/platform/app/features/websites/components/websites-table.tsx b/services/platform/app/features/websites/components/websites-table.tsx
index e34ebade03..ca162a9981 100644
--- a/services/platform/app/features/websites/components/websites-table.tsx
+++ b/services/platform/app/features/websites/components/websites-table.tsx
@@ -2,12 +2,11 @@
 
 import { useNavigate } from '@tanstack/react-router';
 import type { Row, RowSelectionState } from '@tanstack/react-table';
-import { Globe, Plus } from 'lucide-react';
+import { Globe } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { DataTable } from '@/app/components/ui/data-table/data-table';
 import { BulkDeleteBar } from '@/app/components/ui/data-table/data-table-bulk-actions';
-import { useAbility } from '@/app/hooks/use-ability';
 import { useListPage } from '@/app/hooks/use-list-page';
 import type { Doc } from '@/convex/_generated/dataModel';
 import { toId } from '@/convex/lib/type_cast_helpers';
@@ -39,9 +38,6 @@ export function WebsitesTable({
   const { t: tTables } = useT('tables');
   const { t: tEmpty } = useT('emptyStates');
   const { t: tWebsites } = useT('websites');
-  const ability = useAbility();
-  const canWrite = ability.can('write', 'knowledgeWrite');
-  // Lifted so the action menu and the empty-state CTA share one dialog.
   const [createOpen, setCreateOpen] = useState(false);
 
   const { data: count } = useApproxWebsiteCount(organizationId);
@@ -210,13 +206,6 @@ export function WebsitesTable({
           icon: Globe,
           title: tEmpty('websites.title'),
           description: tEmpty('websites.description'),
-          action: canWrite
-            ? {
-                label: tWebsites('addButton'),
-                icon: Plus,
-                onClick: () => setCreateOpen(true),
-              }
-            : undefined,
         }}
         footer={
           <BulkDeleteBar
diff --git a/services/platform/app/features/websites/hooks/use-websites-table-config.tsx b/services/platform/app/features/websites/hooks/use-websites-table-config.tsx
index 76c0d9dd46..f6ce2d7c2c 100644
--- a/services/platform/app/features/websites/hooks/use-websites-table-config.tsx
+++ b/services/platform/app/features/websites/hooks/use-websites-table-config.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Badge } from '@tale/ui/badge';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Row } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import { Globe, Loader } from 'lucide-react';
 
@@ -33,9 +33,13 @@ export const useWebsitesTableConfig = createTableConfigHook<'websites'>(
       size: 256,
       cell: ({ row }) => (
         <HStack gap={2}>
-          <div className="bg-muted flex size-5 shrink-0 items-center justify-center rounded">
+          <Row
+            gap={0}
+            justify="center"
+            className="bg-muted size-5 shrink-0 rounded"
+          >
             <Globe className="text-muted-foreground size-3" />
-          </div>
+          </Row>
           <Text as="span" variant="label" truncate>
             {row.original.domain}
           </Text>
@@ -98,9 +102,9 @@ export const useWebsitesTableConfig = createTableConfigHook<'websites'>(
             alignRight
           />
         ) : (
-          <div className="flex justify-end">
+          <Row gap={0} align="stretch" justify="end">
             <Loader className="text-muted-foreground size-4 animate-spin" />
-          </div>
+          </Row>
         ),
     },
     {
diff --git a/services/platform/app/features/workspace/components/canvas-pane.tsx b/services/platform/app/features/workspace/components/canvas-pane.tsx
index e04bf51a8e..cd557f1b4f 100644
--- a/services/platform/app/features/workspace/components/canvas-pane.tsx
+++ b/services/platform/app/features/workspace/components/canvas-pane.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { useMatch } from '@tanstack/react-router';
 import { parsePartialJson } from 'ai';
 import { Download, PanelRightOpen, X } from 'lucide-react';
@@ -255,8 +256,9 @@ function CanvasPaneComponent({ organizationId }: CanvasPaneProps) {
   const filename = resolvedPath?.split('/').pop() ?? '';
 
   return (
-    <div
-      className="border-border bg-background relative flex h-full shrink-0 flex-col border-l"
+    <Stack
+      gap={0}
+      className="border-border bg-background relative h-full shrink-0 border-l"
       style={{ width }}
       role="complementary"
       aria-label={t('canvas.ariaLabel', { defaultValue: 'Canvas panel' })}
@@ -272,8 +274,8 @@ function CanvasPaneComponent({ organizationId }: CanvasPaneProps) {
         })}
       />
 
-      <div className="border-border flex items-center justify-between gap-2 border-b p-3">
-        <div className="flex min-w-0 items-center gap-2">
+      <Row gap={2} justify="between" className="border-border border-b p-3">
+        <Row gap={2} className="min-w-0">
           {isActiveStreaming && (
             <span
               className="bg-primary inline-block size-1.5 shrink-0 animate-pulse rounded-full"
@@ -296,8 +298,8 @@ function CanvasPaneComponent({ organizationId }: CanvasPaneProps) {
               {t('canvas.writing', { defaultValue: 'Writing…' })}
             </span>
           )}
-        </div>
-        <div className="flex shrink-0 items-center gap-1">
+        </Row>
+        <Row gap={1} className="shrink-0">
           <Tooltip
             content={t('canvas.download', { defaultValue: 'Download' })}
             side="bottom"
@@ -329,10 +331,10 @@ function CanvasPaneComponent({ organizationId }: CanvasPaneProps) {
               <X className="size-3.5" />
             </Button>
           </Tooltip>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
-      <div className="flex min-h-0 flex-1">
+      <Row gap={0} align="stretch" className="min-h-0 flex-1">
         <WorkspaceFileSidebar
           files={mergedFiles}
           activePath={resolvedPath}
@@ -350,8 +352,8 @@ function CanvasPaneComponent({ organizationId }: CanvasPaneProps) {
             liveEncoding={activeLive?.encoding}
           />
         </div>
-      </div>
-    </div>
+      </Row>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/workspace/components/live-browser-pane.tsx b/services/platform/app/features/workspace/components/live-browser-pane.tsx
index 5024c45753..1806f76d81 100644
--- a/services/platform/app/features/workspace/components/live-browser-pane.tsx
+++ b/services/platform/app/features/workspace/components/live-browser-pane.tsx
@@ -2,7 +2,7 @@
 
 import RFB, { type RFBEventDetail } from '@novnc/novnc';
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
 import { useMatch } from '@tanstack/react-router';
@@ -284,7 +284,7 @@ function ScreencastViewport({
       )}
 
       {status === 'connecting' && (
-        <div className="absolute inset-0 flex items-center justify-center">
+        <Row gap={0} justify="center" className="absolute inset-0">
           <Stack gap={2} className="items-center">
             <Spinner
               label={t('liveBrowser.connecting', {
@@ -295,47 +295,37 @@ function ScreencastViewport({
               {t('liveBrowser.connecting', { defaultValue: 'Connecting…' })}
             </Text>
           </Stack>
-        </div>
+        </Row>
       )}
 
       {status === 'disconnected' && (
-        <div className="absolute inset-0 flex items-center justify-center p-8">
+        <Row gap={0} justify="center" className="absolute inset-0 p-8">
           <Stack gap={3} className="items-center text-center">
             <Text variant="label" className="text-sm text-white">
               {t('liveBrowser.disconnected', {
                 defaultValue: 'Stream ended',
               })}
             </Text>
-            <Button
-              variant="secondary"
-              size="sm"
-              icon={RefreshCw}
-              onClick={reconnect}
-            >
+            <Button variant="secondary" icon={RefreshCw} onClick={reconnect}>
               {t('liveBrowser.reconnect', { defaultValue: 'Reconnect' })}
             </Button>
           </Stack>
-        </div>
+        </Row>
       )}
 
       {status === 'error' && (
-        <div className="absolute inset-0 flex items-center justify-center p-8">
+        <Row gap={0} justify="center" className="absolute inset-0 p-8">
           <Stack gap={3} className="items-center text-center">
             <Text variant="label" className="text-sm text-white">
               {t('liveBrowser.error', {
                 defaultValue: 'Couldn’t connect to the live view.',
               })}
             </Text>
-            <Button
-              variant="secondary"
-              size="sm"
-              icon={RefreshCw}
-              onClick={reconnect}
-            >
+            <Button variant="secondary" icon={RefreshCw} onClick={reconnect}>
               {t('liveBrowser.retry', { defaultValue: 'Retry' })}
             </Button>
           </Stack>
-        </div>
+        </Row>
       )}
     </div>
   );
@@ -382,8 +372,8 @@ function LiveBrowserBody({ threadId }: { threadId: string }) {
 
   return (
     <>
-      <div className="border-border flex items-center justify-between gap-2 border-b p-3">
-        <div className="flex min-w-0 items-center gap-2">
+      <Row gap={2} justify="between" className="border-border border-b p-3">
+        <Row gap={2} className="min-w-0">
           <MonitorPlay
             className="text-muted-foreground size-4 shrink-0"
             aria-hidden
@@ -402,12 +392,12 @@ function LiveBrowserBody({ threadId }: { threadId: string }) {
               {t('liveBrowser.viewOnly', { defaultValue: 'View only' })}
             </span>
           )}
-        </div>
+        </Row>
         {/* Rendered in every variant. On desktop it's the pane's close; in the
             mobile Sheet (`embedded`) it replaces the Sheet's own absolute
             top-right close (suppressed via `hideClose`) so the close affordance
             stays aligned with this header row. */}
-        <div className="flex shrink-0 items-center gap-1">
+        <Row gap={1} className="shrink-0">
           {/* Reset browser — only while a session is live (nothing to reset
               otherwise). Recovery of last resort; wipes saved logins. */}
           {sessionActive && (
@@ -448,16 +438,16 @@ function LiveBrowserBody({ threadId }: { threadId: string }) {
               <X className="size-3.5" />
             </Button>
           </Tooltip>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
-      <div className="flex min-h-0 flex-1 flex-col">
+      <Stack gap={0} className="min-h-0 flex-1">
         <ScreencastViewport
           threadId={threadId}
           sessionActive={sessionActive}
           control={control}
         />
-      </div>
+      </Stack>
 
       <ConfirmDialog
         open={confirmOpen}
@@ -485,9 +475,9 @@ function LiveBrowserBody({ threadId }: { threadId: string }) {
  *  only one WebSocket. */
 export function LiveBrowserMobileBody({ threadId }: { threadId: string }) {
   return (
-    <div className="flex h-full min-h-0 flex-col">
+    <Stack gap={0} className="h-full min-h-0">
       <LiveBrowserBody threadId={threadId} />
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/workspace/components/workspace-file-sidebar.tsx b/services/platform/app/features/workspace/components/workspace-file-sidebar.tsx
index e25242ec34..eacdd1eaf0 100644
--- a/services/platform/app/features/workspace/components/workspace-file-sidebar.tsx
+++ b/services/platform/app/features/workspace/components/workspace-file-sidebar.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { useLocale } from '@tale/ui/i18n/locale-provider';
+import { Stack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 import {
   ChevronDown,
@@ -117,7 +118,10 @@ function WorkspaceFileSidebarComponent({
   const totalCount = files.length;
 
   return (
-    <div className="border-border flex w-56 shrink-0 flex-col overflow-y-auto border-r py-1">
+    <Stack
+      gap={0}
+      className="border-border w-56 shrink-0 overflow-y-auto border-r py-1"
+    >
       {SECTIONS.map((section) => {
         const items = grouped[section.key];
         if (items.length === 0) return null;
@@ -156,7 +160,7 @@ function WorkspaceFileSidebarComponent({
               </span>
             </button>
             {isOpen && (
-              <ul className="flex flex-col py-0.5">
+              <Stack as="ul" gap={0} className="py-0.5">
                 {items.map((f) => {
                   const isActive = f.path === activePath;
                   const isStreaming = streamingPaths?.has(f.path) ?? false;
@@ -201,7 +205,7 @@ function WorkspaceFileSidebarComponent({
                     </li>
                   );
                 })}
-              </ul>
+              </Stack>
             )}
           </div>
         );
@@ -213,7 +217,7 @@ function WorkspaceFileSidebarComponent({
           </Text>
         </div>
       )}
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/workspace/components/workspace-files-pane.tsx b/services/platform/app/features/workspace/components/workspace-files-pane.tsx
index 3817e6cd3c..b06ba0a281 100644
--- a/services/platform/app/features/workspace/components/workspace-files-pane.tsx
+++ b/services/platform/app/features/workspace/components/workspace-files-pane.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
 import { useMatch } from '@tanstack/react-router';
@@ -439,7 +439,6 @@ function DirChildren({
           </Text>
           <Button
             variant="ghost"
-            size="sm"
             icon={RefreshCw}
             onClick={() => onRetry(dirPath)}
           >
@@ -732,10 +731,14 @@ function WorkspaceFileViewer({ threadId, path }: WorkspaceFileViewerProps) {
   }, [previewable, loadPreview, revokeObjectUrl]);
 
   return (
-    <div className="flex h-full min-h-0 flex-col">
+    <Stack gap={0} className="h-full min-h-0">
       {/* Toolbar: filename + actions. Download is ALWAYS available (any file,
           any size/type); Preview is offered only for previewable types. */}
-      <div className="border-border flex items-center justify-between gap-2 border-b px-3 py-2">
+      <Row
+        gap={2}
+        justify="between"
+        className="border-border border-b px-3 py-2"
+      >
         <Text variant="caption" className="truncate font-mono" title={path}>
           {filename}
         </Text>
@@ -769,7 +772,7 @@ function WorkspaceFileViewer({ threadId, path }: WorkspaceFileViewerProps) {
             </a>
           </Button>
         </div>
-      </div>
+      </Row>
       <div className="min-h-0 flex-1 overflow-hidden">
         <WorkspaceFileViewerContent
           state={state}
@@ -778,7 +781,7 @@ function WorkspaceFileViewer({ threadId, path }: WorkspaceFileViewerProps) {
           previewable={previewable}
         />
       </div>
-    </div>
+    </Stack>
   );
 }
 
@@ -925,8 +928,8 @@ function WorkspaceFilesBody({ threadId }: { threadId: string }) {
 
   return (
     <>
-      <div className="border-border flex items-center justify-between gap-2 border-b p-3">
-        <div className="flex min-w-0 items-center gap-2">
+      <Row gap={2} justify="between" className="border-border border-b p-3">
+        <Row gap={2} className="min-w-0">
           <Folder
             className="text-muted-foreground size-4 shrink-0"
             aria-hidden
@@ -934,8 +937,8 @@ function WorkspaceFilesBody({ threadId }: { threadId: string }) {
           <span className="truncate text-sm font-medium">
             {t('workspaceFiles.title', { defaultValue: 'Workspace files' })}
           </span>
-        </div>
-        <div className="flex shrink-0 items-center gap-1">
+        </Row>
+        <Row gap={1} className="shrink-0">
           <Tooltip
             content={t('workspaceFiles.showHidden', {
               defaultValue: 'Show hidden files',
@@ -997,8 +1000,8 @@ function WorkspaceFilesBody({ threadId }: { threadId: string }) {
               <X className="size-3.5" />
             </Button>
           </Tooltip>
-        </div>
-      </div>
+        </Row>
+      </Row>
 
       {!sessionRunning ? (
         <SessionStoppedState />
@@ -1046,9 +1049,9 @@ function WorkspaceFilesBody({ threadId }: { threadId: string }) {
  *  caller (the chat Sheet) supplies the panel chrome. */
 export function WorkspaceFilesMobileBody({ threadId }: { threadId: string }) {
   return (
-    <div className="flex h-full min-h-0 flex-col">
+    <Stack gap={0} className="h-full min-h-0">
       <WorkspaceFilesBody threadId={threadId} />
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/workspace/viewers/code-viewer.tsx b/services/platform/app/features/workspace/viewers/code-viewer.tsx
index 3b98af5ab4..70710bb51a 100644
--- a/services/platform/app/features/workspace/viewers/code-viewer.tsx
+++ b/services/platform/app/features/workspace/viewers/code-viewer.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { useTheme } from '@tale/ui/theme';
 import { WrapText } from 'lucide-react';
 import { memo, useCallback, useEffect, useRef, useState } from 'react';
@@ -93,7 +94,11 @@ function CodeViewerComponent({
   return (
     <div className={cn('flex h-full min-h-0 flex-col', className)}>
       {showWrapToggle && (
-        <div className="border-border bg-muted/30 flex shrink-0 items-center justify-end border-b px-2 py-1">
+        <Row
+          gap={0}
+          justify="end"
+          className="border-border bg-muted/30 shrink-0 border-b px-2 py-1"
+        >
           <Button
             variant="ghost"
             size="sm"
@@ -104,7 +109,7 @@ function CodeViewerComponent({
               defaultValue: 'Toggle line wrap',
             })}
           />
-        </div>
+        </Row>
       )}
       <div className="min-h-0 flex-1 overflow-auto">
         {oversize ? (
diff --git a/services/platform/app/features/workspace/viewers/image-viewer.tsx b/services/platform/app/features/workspace/viewers/image-viewer.tsx
index ac8364fb50..3894449436 100644
--- a/services/platform/app/features/workspace/viewers/image-viewer.tsx
+++ b/services/platform/app/features/workspace/viewers/image-viewer.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { memo } from 'react';
 
 interface ImageViewerProps {
@@ -9,14 +10,18 @@ interface ImageViewerProps {
 
 function ImageViewerComponent({ url, alt }: ImageViewerProps) {
   return (
-    <div className="bg-checkerboard flex h-full w-full items-center justify-center overflow-auto p-4">
+    <Row
+      gap={0}
+      justify="center"
+      className="bg-checkerboard h-full w-full overflow-auto p-4"
+    >
       <img
         src={url}
         alt={alt}
         className="max-h-full max-w-full object-contain"
         draggable={false}
       />
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/features/workspace/viewers/mermaid-viewer.tsx b/services/platform/app/features/workspace/viewers/mermaid-viewer.tsx
index a8f59da412..54578eeffa 100644
--- a/services/platform/app/features/workspace/viewers/mermaid-viewer.tsx
+++ b/services/platform/app/features/workspace/viewers/mermaid-viewer.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
 import { useTheme } from '@tale/ui/theme';
@@ -72,24 +73,26 @@ function MermaidViewerComponent({ code }: MermaidViewerProps) {
 
   if (error) {
     return (
-      <div className="flex h-full items-center justify-center p-4">
+      <Row gap={0} justify="center" className="h-full p-4">
         <Text variant="muted" className="text-sm">
           {error}
         </Text>
-      </div>
+      </Row>
     );
   }
 
   return (
     <div className="relative h-full overflow-auto p-4">
       {isLoading && (
-        <div className="absolute inset-0 flex items-center justify-center">
+        <Row gap={0} justify="center" className="absolute inset-0">
           <Spinner />
-        </div>
+        </Row>
       )}
-      <div
+      <Row
         ref={containerRef}
-        className="flex items-center justify-center [&_svg]:max-w-full"
+        gap={0}
+        justify="center"
+        className="[&_svg]:max-w-full"
       />
     </div>
   );
diff --git a/services/platform/app/features/workspace/viewers/renderable-file-viewer.tsx b/services/platform/app/features/workspace/viewers/renderable-file-viewer.tsx
index 865b7177d8..8419dedb46 100644
--- a/services/platform/app/features/workspace/viewers/renderable-file-viewer.tsx
+++ b/services/platform/app/features/workspace/viewers/renderable-file-viewer.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { Code, Eye } from 'lucide-react';
 import { memo, useEffect, useState } from 'react';
 
@@ -57,9 +58,11 @@ function RenderableFileViewerComponent({
   const effectiveMode: 'source' | 'preview' = isStreaming ? 'source' : viewMode;
 
   return (
-    <div className="flex h-full min-h-0 flex-col">
-      <div
-        className="border-border bg-muted/30 flex shrink-0 items-center justify-end gap-1 border-b px-2 py-1"
+    <Stack gap={0} className="h-full min-h-0">
+      <Row
+        gap={1}
+        justify="end"
+        className="border-border bg-muted/30 shrink-0 border-b px-2 py-1"
         role="group"
         aria-label={t('canvas.viewToggleAriaLabel', {
           defaultValue: 'Toggle source / preview',
@@ -84,7 +87,7 @@ function RenderableFileViewerComponent({
         >
           {t('canvas.viewPreview', { defaultValue: 'Preview' })}
         </Button>
-      </div>
+      </Row>
       <div className="min-h-0 flex-1 overflow-hidden">
         {effectiveMode === 'source' ? (
           <CodeViewer path={path} content={content} />
@@ -98,7 +101,7 @@ function RenderableFileViewerComponent({
           <MarkdownViewer content={content} />
         )}
       </div>
-    </div>
+    </Stack>
   );
 }
 
diff --git a/services/platform/app/features/workspace/viewers/svg-viewer.tsx b/services/platform/app/features/workspace/viewers/svg-viewer.tsx
index 695c851cc9..3948ce131e 100644
--- a/services/platform/app/features/workspace/viewers/svg-viewer.tsx
+++ b/services/platform/app/features/workspace/viewers/svg-viewer.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { Row } from '@tale/ui/layout';
 import { memo, useMemo } from 'react';
 
 interface SvgViewerProps {
@@ -32,14 +33,14 @@ function sanitizeSvg(input: string): string {
 function SvgViewerComponent({ svg }: SvgViewerProps) {
   const safe = useMemo(() => sanitizeSvg(svg), [svg]);
   return (
-    <div className="flex h-full w-full items-center justify-center overflow-auto p-4">
+    <Row gap={0} justify="center" className="h-full w-full overflow-auto p-4">
       <div
         className="max-h-full max-w-full [&_svg]:h-auto [&_svg]:max-h-full [&_svg]:max-w-full"
         // eslint-disable-next-line react/no-danger -- sanitized above
         // nosemgrep: typescript.react.security.audit.react-dangerouslysetinnerhtml.react-dangerouslysetinnerhtml -- `safe` is sanitizeSvg() output
         dangerouslySetInnerHTML={{ __html: safe }}
       />
-    </div>
+    </Row>
   );
 }
 
diff --git a/services/platform/app/hooks/use-is-mac.ts b/services/platform/app/hooks/use-is-mac.ts
new file mode 100644
index 0000000000..fb87cafdbf
--- /dev/null
+++ b/services/platform/app/hooks/use-is-mac.ts
@@ -0,0 +1,25 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * True when the client runs on macOS. Use it to pick the right modifier key for
+ * keyboard shortcuts (⌘ on Mac, Ctrl elsewhere) and to render the matching
+ * shortcut hint. SSR-safe: returns `false` until the effect runs on the client,
+ * which is fine for shortcut chrome (it resolves before first interaction).
+ */
+export function useIsMac(): boolean {
+  const [isMac, setIsMac] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const platform = (
+      navigator.platform ||
+      navigator.userAgent ||
+      ''
+    ).toLowerCase();
+    setIsMac(platform.includes('mac'));
+  }, []);
+
+  return isMac;
+}
diff --git a/services/platform/app/hooks/use-navigation-items.ts b/services/platform/app/hooks/use-navigation-items.ts
index 95e5c0f35f..71bd0d6f67 100644
--- a/services/platform/app/hooks/use-navigation-items.ts
+++ b/services/platform/app/hooks/use-navigation-items.ts
@@ -15,6 +15,8 @@ import { useMemo } from 'react';
 import { useT } from '@/lib/i18n/client';
 import { type AppAction, type AppSubject } from '@/lib/permissions/ability';
 
+import { useIsMac } from './use-is-mac';
+
 export interface NavItem {
   label: string;
   to: string;
@@ -30,6 +32,12 @@ export interface NavItem {
   subItems?: NavItem[];
   /** Unread count rendered as a chip on the nav icon (omit/0 = no chip). */
   badge?: number;
+  /**
+   * Platform-resolved keyboard-shortcut hint (e.g. `⌥ ⌘ N`) shown as a chip in
+   * the item's hover tooltip. Present only for items that own a global
+   * shortcut; the binding itself lives in the `Navigation` component.
+   */
+  shortcut?: string;
   /**
    * Custom active-path matcher. When provided, replaces the default
    * `pathname === href || pathname.startsWith(href + '/')` check. Useful when
@@ -50,15 +58,18 @@ export function useNavigationItems(businessId: string): NavigationItems {
   const { t: tKnowledge } = useT('knowledge');
   const { t: tConversations } = useT('conversations');
   const { t: tProjects } = useT('projects');
+  const isMac = useIsMac();
+  const newChatShortcut = isMac ? '⌥ ⌘ N' : 'ALT + CTRL + N';
   return useMemo(
     (): NavigationItems => ({
       primary: [
         {
-          label: tNav('chatWithAI'),
+          label: tNav('newChat'),
           to: '/dashboard/$id/chat',
           params: { id: businessId },
           href: `/dashboard/${businessId}/chat`,
           icon: MessageCircle,
+          shortcut: newChatShortcut,
         },
         {
           label: tNav('apps'),
@@ -178,6 +189,6 @@ export function useNavigationItems(businessId: string): NavigationItems {
       ],
       pinned: [],
     }),
-    [businessId, tNav, tKnowledge, tConversations, tProjects],
+    [businessId, tNav, tKnowledge, tConversations, tProjects, newChatShortcut],
   );
 }
diff --git a/services/platform/app/routeTree.gen.ts b/services/platform/app/routeTree.gen.ts
index d5577ae3e7..442bae48c4 100644
--- a/services/platform/app/routeTree.gen.ts
+++ b/services/platform/app/routeTree.gen.ts
@@ -117,7 +117,6 @@ import { Route as DashboardIdAutomationsAmIdConfigurationRouteImport } from './r
 import { Route as DashboardIdAgentsAgentIdWebhookRouteImport } from './routes/dashboard/$id/agents/$agentId/webhook';
 import { Route as DashboardIdAgentsAgentIdToolsRouteImport } from './routes/dashboard/$id/agents/$agentId/tools';
 import { Route as DashboardIdAgentsAgentIdSkillsRouteImport } from './routes/dashboard/$id/agents/$agentId/skills';
-import { Route as DashboardIdAgentsAgentIdResponseTuningRouteImport } from './routes/dashboard/$id/agents/$agentId/response-tuning';
 import { Route as DashboardIdAgentsAgentIdMetricsRouteImport } from './routes/dashboard/$id/agents/$agentId/metrics';
 import { Route as DashboardIdAgentsAgentIdKnowledgeRouteImport } from './routes/dashboard/$id/agents/$agentId/knowledge';
 import { Route as DashboardIdAgentsAgentIdInstructionsRouteImport } from './routes/dashboard/$id/agents/$agentId/instructions';
@@ -749,12 +748,6 @@ const DashboardIdAgentsAgentIdSkillsRoute =
     path: '/skills',
     getParentRoute: () => DashboardIdAgentsAgentIdRoute,
   } as any);
-const DashboardIdAgentsAgentIdResponseTuningRoute =
-  DashboardIdAgentsAgentIdResponseTuningRouteImport.update({
-    id: '/response-tuning',
-    path: '/response-tuning',
-    getParentRoute: () => DashboardIdAgentsAgentIdRoute,
-  } as any);
 const DashboardIdAgentsAgentIdMetricsRoute =
   DashboardIdAgentsAgentIdMetricsRouteImport.update({
     id: '/metrics',
@@ -923,7 +916,6 @@ export interface FileRoutesByFullPath {
   '/dashboard/$id/agents/$agentId/instructions': typeof DashboardIdAgentsAgentIdInstructionsRoute;
   '/dashboard/$id/agents/$agentId/knowledge': typeof DashboardIdAgentsAgentIdKnowledgeRoute;
   '/dashboard/$id/agents/$agentId/metrics': typeof DashboardIdAgentsAgentIdMetricsRoute;
-  '/dashboard/$id/agents/$agentId/response-tuning': typeof DashboardIdAgentsAgentIdResponseTuningRoute;
   '/dashboard/$id/agents/$agentId/skills': typeof DashboardIdAgentsAgentIdSkillsRoute;
   '/dashboard/$id/agents/$agentId/tools': typeof DashboardIdAgentsAgentIdToolsRoute;
   '/dashboard/$id/agents/$agentId/webhook': typeof DashboardIdAgentsAgentIdWebhookRoute;
@@ -1033,7 +1025,6 @@ export interface FileRoutesByTo {
   '/dashboard/$id/agents/$agentId/instructions': typeof DashboardIdAgentsAgentIdInstructionsRoute;
   '/dashboard/$id/agents/$agentId/knowledge': typeof DashboardIdAgentsAgentIdKnowledgeRoute;
   '/dashboard/$id/agents/$agentId/metrics': typeof DashboardIdAgentsAgentIdMetricsRoute;
-  '/dashboard/$id/agents/$agentId/response-tuning': typeof DashboardIdAgentsAgentIdResponseTuningRoute;
   '/dashboard/$id/agents/$agentId/skills': typeof DashboardIdAgentsAgentIdSkillsRoute;
   '/dashboard/$id/agents/$agentId/tools': typeof DashboardIdAgentsAgentIdToolsRoute;
   '/dashboard/$id/agents/$agentId/webhook': typeof DashboardIdAgentsAgentIdWebhookRoute;
@@ -1159,7 +1150,6 @@ export interface FileRoutesById {
   '/dashboard/$id/agents/$agentId/instructions': typeof DashboardIdAgentsAgentIdInstructionsRoute;
   '/dashboard/$id/agents/$agentId/knowledge': typeof DashboardIdAgentsAgentIdKnowledgeRoute;
   '/dashboard/$id/agents/$agentId/metrics': typeof DashboardIdAgentsAgentIdMetricsRoute;
-  '/dashboard/$id/agents/$agentId/response-tuning': typeof DashboardIdAgentsAgentIdResponseTuningRoute;
   '/dashboard/$id/agents/$agentId/skills': typeof DashboardIdAgentsAgentIdSkillsRoute;
   '/dashboard/$id/agents/$agentId/tools': typeof DashboardIdAgentsAgentIdToolsRoute;
   '/dashboard/$id/agents/$agentId/webhook': typeof DashboardIdAgentsAgentIdWebhookRoute;
@@ -1285,7 +1275,6 @@ export interface FileRouteTypes {
     | '/dashboard/$id/agents/$agentId/instructions'
     | '/dashboard/$id/agents/$agentId/knowledge'
     | '/dashboard/$id/agents/$agentId/metrics'
-    | '/dashboard/$id/agents/$agentId/response-tuning'
     | '/dashboard/$id/agents/$agentId/skills'
     | '/dashboard/$id/agents/$agentId/tools'
     | '/dashboard/$id/agents/$agentId/webhook'
@@ -1395,7 +1384,6 @@ export interface FileRouteTypes {
     | '/dashboard/$id/agents/$agentId/instructions'
     | '/dashboard/$id/agents/$agentId/knowledge'
     | '/dashboard/$id/agents/$agentId/metrics'
-    | '/dashboard/$id/agents/$agentId/response-tuning'
     | '/dashboard/$id/agents/$agentId/skills'
     | '/dashboard/$id/agents/$agentId/tools'
     | '/dashboard/$id/agents/$agentId/webhook'
@@ -1520,7 +1508,6 @@ export interface FileRouteTypes {
     | '/dashboard/$id/agents/$agentId/instructions'
     | '/dashboard/$id/agents/$agentId/knowledge'
     | '/dashboard/$id/agents/$agentId/metrics'
-    | '/dashboard/$id/agents/$agentId/response-tuning'
     | '/dashboard/$id/agents/$agentId/skills'
     | '/dashboard/$id/agents/$agentId/tools'
     | '/dashboard/$id/agents/$agentId/webhook'
@@ -2338,13 +2325,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DashboardIdAgentsAgentIdSkillsRouteImport;
       parentRoute: typeof DashboardIdAgentsAgentIdRoute;
     };
-    '/dashboard/$id/agents/$agentId/response-tuning': {
-      id: '/dashboard/$id/agents/$agentId/response-tuning';
-      path: '/response-tuning';
-      fullPath: '/dashboard/$id/agents/$agentId/response-tuning';
-      preLoaderRoute: typeof DashboardIdAgentsAgentIdResponseTuningRouteImport;
-      parentRoute: typeof DashboardIdAgentsAgentIdRoute;
-    };
     '/dashboard/$id/agents/$agentId/metrics': {
       id: '/dashboard/$id/agents/$agentId/metrics';
       path: '/metrics';
@@ -2496,7 +2476,6 @@ interface DashboardIdAgentsAgentIdRouteChildren {
   DashboardIdAgentsAgentIdInstructionsRoute: typeof DashboardIdAgentsAgentIdInstructionsRoute;
   DashboardIdAgentsAgentIdKnowledgeRoute: typeof DashboardIdAgentsAgentIdKnowledgeRoute;
   DashboardIdAgentsAgentIdMetricsRoute: typeof DashboardIdAgentsAgentIdMetricsRoute;
-  DashboardIdAgentsAgentIdResponseTuningRoute: typeof DashboardIdAgentsAgentIdResponseTuningRoute;
   DashboardIdAgentsAgentIdSkillsRoute: typeof DashboardIdAgentsAgentIdSkillsRoute;
   DashboardIdAgentsAgentIdToolsRoute: typeof DashboardIdAgentsAgentIdToolsRoute;
   DashboardIdAgentsAgentIdWebhookRoute: typeof DashboardIdAgentsAgentIdWebhookRoute;
@@ -2516,8 +2495,6 @@ const DashboardIdAgentsAgentIdRouteChildren: DashboardIdAgentsAgentIdRouteChildr
     DashboardIdAgentsAgentIdKnowledgeRoute:
       DashboardIdAgentsAgentIdKnowledgeRoute,
     DashboardIdAgentsAgentIdMetricsRoute: DashboardIdAgentsAgentIdMetricsRoute,
-    DashboardIdAgentsAgentIdResponseTuningRoute:
-      DashboardIdAgentsAgentIdResponseTuningRoute,
     DashboardIdAgentsAgentIdSkillsRoute: DashboardIdAgentsAgentIdSkillsRoute,
     DashboardIdAgentsAgentIdToolsRoute: DashboardIdAgentsAgentIdToolsRoute,
     DashboardIdAgentsAgentIdWebhookRoute: DashboardIdAgentsAgentIdWebhookRoute,
diff --git a/services/platform/app/routes/2fa-enroll.tsx b/services/platform/app/routes/2fa-enroll.tsx
index a8f6455823..7e491a90c3 100644
--- a/services/platform/app/routes/2fa-enroll.tsx
+++ b/services/platform/app/routes/2fa-enroll.tsx
@@ -1,6 +1,6 @@
 import { Button } from '@tale/ui/button';
 import { Heading } from '@tale/ui/heading';
-import { Stack, VStack } from '@tale/ui/layout';
+import { Grid, Stack, VStack } from '@tale/ui/layout';
 import { Text } from '@tale/ui/text';
 /**
  * Post-grace enrollment wall. The sign-in after-hook returns
@@ -253,11 +253,16 @@ function TwoFactorEnrollPage() {
               <Text variant="muted" className="text-sm">
                 {t('backupCodes.warningOnce')}
               </Text>
-              <ul className="bg-muted grid grid-cols-2 gap-2 rounded-md border p-3 font-mono text-sm">
+              <Grid
+                as="ul"
+                cols={2}
+                gap={2}
+                className="bg-muted rounded-md border p-3 font-mono text-sm"
+              >
                 {step.backupCodes.map((c) => (
                   <li key={c}>{c}</li>
                 ))}
-              </ul>
+              </Grid>
               <Stack gap={2}>
                 <Button
                   variant="secondary"
diff --git a/services/platform/app/routes/_auth/log-in.tsx b/services/platform/app/routes/_auth/log-in.tsx
index 0ce395d2ef..89feec3b91 100644
--- a/services/platform/app/routes/_auth/log-in.tsx
+++ b/services/platform/app/routes/_auth/log-in.tsx
@@ -1,6 +1,6 @@
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Button } from '@tale/ui/button';
-import { Stack } from '@tale/ui/layout';
+import { Row, Stack } from '@tale/ui/layout';
 import {
   createFileRoute,
   useNavigate,
@@ -342,12 +342,11 @@ export function LogInPage() {
                 right) — the standard pattern — so the space directly under the
                 input is free for the error message to read as field feedback. */}
             <div className="flex flex-col gap-1.5">
-              <div className="flex items-center justify-between gap-2">
+              <Row gap={2} justify="between">
                 <Label htmlFor="password">{t('password')}</Label>
                 <Button
                   type="button"
                   variant="link"
-                  size="sm"
                   className="h-auto p-0"
                   onClick={() =>
                     toast({
@@ -359,7 +358,7 @@ export function LogInPage() {
                 >
                   {t('login.forgotPassword')}
                 </Button>
-              </div>
+              </Row>
               <Input
                 id="password"
                 type="password"
@@ -378,10 +377,11 @@ export function LogInPage() {
               // `space-y-4`) so the message reads as feedback on the inputs —
               // matching the ~6px gap a field-level error uses — rather than
               // floating midway to the button.
-              <div
+              <Stack
                 role="alert"
                 aria-live="polite"
-                className="-mt-2.5 flex flex-col gap-1"
+                gap={1}
+                className="-mt-2.5"
               >
                 <p className="text-destructive flex items-start gap-1.5 text-sm font-medium">
                   <AlertCircle className="mt-0.5 size-4 shrink-0" aria-hidden />
@@ -392,7 +392,7 @@ export function LogInPage() {
                     {t('login.lockoutAdvisory')}
                   </p>
                 )}
-              </div>
+              </Stack>
             )}
 
             <Button type="submit" fullWidth disabled={isSubmitting || !isValid}>
@@ -404,11 +404,11 @@ export function LogInPage() {
         {/* A single "or" divider separates the credential method above from the
             alternative sign-in methods grouped below — it reads correctly with
             one alternative (passkey) or two (passkey + SSO). */}
-        <div className="flex items-center gap-3" aria-hidden="true">
+        <Row gap={3} aria-hidden="true">
           <span className="bg-border h-px flex-1" />
           <span className="text-muted-foreground text-xs">{tCommon('or')}</span>
           <span className="bg-border h-px flex-1" />
-        </div>
+        </Row>
 
         <Stack gap={3}>
           <Button
diff --git a/services/platform/app/routes/dashboard/$id.tsx b/services/platform/app/routes/dashboard/$id.tsx
index 5ad626fd29..4919053448 100644
--- a/services/platform/app/routes/dashboard/$id.tsx
+++ b/services/platform/app/routes/dashboard/$id.tsx
@@ -1,6 +1,6 @@
 import { convexQuery } from '@convex-dev/react-query';
 import { FullPageCenter } from '@tale/ui/full-page-center';
-import { VStack } from '@tale/ui/layout';
+import { Row, Stack, VStack } from '@tale/ui/layout';
 import { SkeletonBox, SkeletonCircle } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Spinner } from '@tale/ui/spinner';
@@ -293,12 +293,12 @@ function DashboardLayout() {
                     vertically centers the title and profile button so neither
                     sits high/low in the bar on notch devices. */}
                 <header className="bg-background border-border border-b px-4 pt-(--safe-top) md:hidden">
-                  <div className="flex min-h-12 items-center gap-2">
+                  <Row gap={2} className="min-h-12">
                     <div className="min-w-0 flex-1">
                       <AdaptiveHeaderSlot />
                     </div>
                     <UserButton align="end" />
-                  </div>
+                  </Row>
                 </header>
 
                 <div className="bg-background hidden h-full px-2 md:flex md:flex-[0_0_var(--nav-size)]">
@@ -309,9 +309,11 @@ function DashboardLayout() {
                   )}
                 </div>
 
-                <main
+                <Stack
                   id="main-content"
-                  className="border-border bg-background flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden md:border-l"
+                  as="main"
+                  gap={0}
+                  className="border-border bg-background min-h-0 min-w-0 flex-1 overflow-hidden md:border-l"
                 >
                   {hasRole && (
                     <TwoFactorGraceBanner organizationId={organizationId} />
@@ -339,7 +341,7 @@ function DashboardLayout() {
                       <Outlet />
                     )
                   ) : null}
-                </main>
+                </Stack>
                 {hasRole && <MobileBottomNav organizationId={organizationId} />}
               </div>
             </AdaptiveHeaderProvider>
@@ -355,11 +357,11 @@ function DashboardLayout() {
 // list and the pinned footer buttons so the rail reads as a populated nav.
 function NavIconSkeleton() {
   return (
-    <div className="flex items-center justify-center rounded-lg p-2">
+    <Row gap={0} justify="center" className="rounded-lg p-2">
       <SkeletonBox>
         <div className="size-5" />
       </SkeletonBox>
-    </div>
+    </Row>
   );
 }
 
@@ -378,14 +380,14 @@ const PLACEHOLDER_NAV_ITEMS = 7;
 function NavRailPlaceholder() {
   return (
     <Skeletonize loading>
-      <div className="border-border flex h-full flex-col">
-        <div className="flex flex-shrink-0 items-center justify-center py-3">
-          <div className="flex size-8 items-center justify-center">
+      <Stack gap={0} className="border-border h-full">
+        <Row gap={0} justify="center" className="flex-shrink-0 py-3">
+          <Row gap={0} justify="center" className="size-8">
             <SkeletonBox>
               <div className="size-5" />
             </SkeletonBox>
-          </div>
-        </div>
+          </Row>
+        </Row>
         <div className="mx-1 min-h-0 flex-1 overflow-y-auto py-4">
           <div className="space-y-2">
             {Array.from({ length: PLACEHOLDER_NAV_ITEMS }, (_, i) => (
@@ -394,17 +396,17 @@ function NavRailPlaceholder() {
             ))}
           </div>
         </div>
-        <div className="flex flex-shrink-0 flex-col items-center gap-2 py-3">
+        <Stack gap={2} align="center" className="flex-shrink-0 py-3">
           {/* Notification bell */}
           <NavIconSkeleton />
           {/* UserButton avatar */}
-          <div className="flex items-center justify-center rounded-lg p-2">
+          <Row gap={0} justify="center" className="rounded-lg p-2">
             <SkeletonCircle>
               <div className="size-5" />
             </SkeletonCircle>
-          </div>
-        </div>
-      </div>
+          </Row>
+        </Stack>
+      </Stack>
     </Skeletonize>
   );
 }
@@ -423,25 +425,25 @@ export function DashboardShellFrame() {
           DashboardLayout header geometry above (px-4, min-h-12). */}
       <div className="bg-background border-border border-b px-4 pt-(--safe-top) md:hidden">
         <Skeletonize loading>
-          <div className="flex min-h-12 items-center gap-2">
+          <Row gap={2} className="min-h-12">
             {/* Leading action icons (chat history / search / new chat). */}
-            <div className="flex flex-1 justify-start">
+            <Row gap={0} align="stretch" className="flex-1">
               {Array.from({ length: 3 }, (_, i) => (
                 // eslint-disable-next-line react/no-array-index-key
-                <div key={i} className="flex items-center justify-center p-2">
+                <Row key={i} gap={0} justify="center" className="p-2">
                   <SkeletonBox>
                     <div className="size-5" />
                   </SkeletonBox>
-                </div>
+                </Row>
               ))}
-            </div>
+            </Row>
             {/* Trailing account avatar (UserButton). */}
-            <div className="flex items-center justify-center p-2">
+            <Row gap={0} justify="center" className="p-2">
               <SkeletonCircle>
                 <div className="size-5" />
               </SkeletonCircle>
-            </div>
-          </div>
+            </Row>
+          </Row>
         </Skeletonize>
       </div>
 
@@ -450,10 +452,18 @@ export function DashboardShellFrame() {
         <NavRailPlaceholder />
       </div>
 
-      <main className="border-border bg-background flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden md:border-l" />
+      <Stack
+        as="main"
+        gap={0}
+        className="border-border bg-background min-h-0 min-w-0 flex-1 overflow-hidden md:border-l"
+      />
 
       {/* Mobile bottom-nav placeholder */}
-      <div className="bg-background border-border flex min-h-12 border-t pb-(--safe-bottom) md:hidden" />
+      <Row
+        gap={0}
+        align="stretch"
+        className="bg-background border-border min-h-12 border-t pb-(--safe-bottom) md:hidden"
+      />
     </div>
   );
 }
diff --git a/services/platform/app/routes/dashboard/$id/agents/$agentId/conversation-starters.tsx b/services/platform/app/routes/dashboard/$id/agents/$agentId/conversation-starters.tsx
index 8213f51bda..9b56cd7980 100644
--- a/services/platform/app/routes/dashboard/$id/agents/$agentId/conversation-starters.tsx
+++ b/services/platform/app/routes/dashboard/$id/agents/$agentId/conversation-starters.tsx
@@ -1,4 +1,5 @@
 import { Button } from '@tale/ui/button';
+import { Row } from '@tale/ui/layout';
 import { SectionHeader } from '@tale/ui/section-header';
 import { Tabs, type TabItem } from '@tale/ui/tabs';
 import { createFileRoute } from '@tanstack/react-router';
@@ -309,7 +310,7 @@ function ConversationStartersTab() {
           dragHandleLabel={t('agents.conversationStarters.dragHandle')}
           removeLabel={t('agents.conversationStarters.remove')}
           renderItem={({ item, index }) => (
-            <div className="flex items-center gap-2">
+            <Row gap={2}>
               <span className="text-muted-foreground text-sm">
                 {index + 1}.
               </span>
@@ -321,7 +322,7 @@ function ConversationStartersTab() {
                 maxLength={MAX_CONVERSATION_STARTER_LENGTH}
                 wrapperClassName="min-w-0 flex-1"
               />
-            </div>
+            </Row>
           )}
         />
 
@@ -329,7 +330,6 @@ function ConversationStartersTab() {
           <Button
             type="button"
             variant="secondary"
-            size="sm"
             onClick={handleAdd}
             className="self-start"
           >
diff --git a/services/platform/app/routes/dashboard/$id/agents/$agentId/instructions.tsx b/services/platform/app/routes/dashboard/$id/agents/$agentId/instructions.tsx
index 4940f00add..9e125fb50f 100644
--- a/services/platform/app/routes/dashboard/$id/agents/$agentId/instructions.tsx
+++ b/services/platform/app/routes/dashboard/$id/agents/$agentId/instructions.tsx
@@ -1,7 +1,7 @@
 import { Button } from '@tale/ui/button';
 import { CodeBlock } from '@tale/ui/code-block';
 import { CollapsibleDetails } from '@tale/ui/collapsible-details';
-import { HStack } from '@tale/ui/layout';
+import { HStack, Stack } from '@tale/ui/layout';
 import { PageSection } from '@tale/ui/page-section';
 import { SectionHeader } from '@tale/ui/section-header';
 import { createFileRoute } from '@tanstack/react-router';
@@ -421,8 +421,8 @@ function InstructionsTab() {
         title={t('agents.form.sectionInstructions')}
         description={t('agents.form.sectionInstructionsDescription')}
       />
-      <div className="flex flex-col gap-4">
-        <div className="flex flex-col gap-3">
+      <Stack>
+        <Stack gap={3}>
           <HStack justify="between" align="center">
             <label htmlFor="systemInstructions" className="text-sm font-medium">
               {t('agents.form.systemInstructions')}
@@ -430,7 +430,6 @@ function InstructionsTab() {
             <Tooltip content={t('agents.form.browsePrompts')} side="top">
               <Button
                 variant="ghost"
-                size="sm"
                 onClick={() => setPromptLibraryOpen(true)}
                 aria-label={t('agents.form.browsePrompts')}
               >
@@ -465,7 +464,7 @@ function InstructionsTab() {
             rows={8}
             className="font-mono text-sm"
           />
-        </div>
+        </Stack>
         <CollapsibleDetails
           variant="compact"
           summary={t('agents.form.templateVariablesLabel')}
@@ -482,7 +481,7 @@ function InstructionsTab() {
             ))}
           </ul>
         </CollapsibleDetails>
-      </div>
+      </Stack>
 
       {isExternalAgent && (
         <PageSection
diff --git a/services/platform/app/routes/dashboard/$id/agents/$agentId/metrics.tsx b/services/platform/app/routes/dashboard/$id/agents/$agentId/metrics.tsx
index 0b0432eb91..54712ff0b1 100644
--- a/services/platform/app/routes/dashboard/$id/agents/$agentId/metrics.tsx
+++ b/services/platform/app/routes/dashboard/$id/agents/$agentId/metrics.tsx
@@ -1,9 +1,20 @@
 import { Badge } from '@tale/ui/badge';
-import { SectionHeader } from '@tale/ui/section-header';
+import { ChartCard } from '@tale/ui/chart-card';
+import { ChartLegend } from '@tale/ui/chart-legend';
+import { CHART_COLORS } from '@tale/ui/chart-theme';
+import { Stack } from '@tale/ui/layout';
+import { StatCard, StatCardGrid } from '@tale/ui/stat-card-grid';
 import { Text } from '@tale/ui/text';
+import { TrendIndicator } from '@tale/ui/trend-indicator';
 import { createFileRoute } from '@tanstack/react-router';
 
 import { ContentArea } from '@/app/components/layout/content-area';
+import {
+  seriesToLegend,
+  TrendBarChart,
+  type ChartSeries,
+} from '@/app/components/metrics/charts';
+import { MetricsLayout } from '@/app/components/metrics/metrics-layout';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
 import { useFormatDate } from '@/app/hooks/use-format-date';
 import { api } from '@/convex/_generated/api';
@@ -48,9 +59,64 @@ interface ScorecardRun {
 
 interface ScorecardPayload {
   daily: ScorecardDay[];
+  /** Same shape as `daily` for the immediately-preceding window (deltas). */
+  previousDaily: ScorecardDay[];
   recentRuns: ScorecardRun[];
 }
 
+interface ScorecardTotals {
+  runsStarted: number;
+  runsFailed: number;
+  durationSum: number;
+  durationCount: number;
+  costCents: number;
+  tasksCompleted: number;
+  reviewsPassed: number;
+  reviewsChangesRequested: number;
+  escalations: number;
+}
+
+function reduceDaily(days: ScorecardDay[]): ScorecardTotals {
+  return days.reduce(
+    (acc, day) => ({
+      runsStarted: acc.runsStarted + day.runsStarted,
+      runsFailed: acc.runsFailed + day.runsFailed,
+      durationSum: acc.durationSum + day.runDurationSumMs,
+      durationCount: acc.durationCount + day.runDurationCount,
+      costCents: acc.costCents + day.costCents,
+      tasksCompleted: acc.tasksCompleted + day.tasksCompleted,
+      reviewsPassed: acc.reviewsPassed + day.reviewsPassed,
+      reviewsChangesRequested:
+        acc.reviewsChangesRequested + day.reviewsChangesRequested,
+      escalations: acc.escalations + day.escalations,
+    }),
+    {
+      runsStarted: 0,
+      runsFailed: 0,
+      durationSum: 0,
+      durationCount: 0,
+      costCents: 0,
+      tasksCompleted: 0,
+      reviewsPassed: 0,
+      reviewsChangesRequested: 0,
+      escalations: 0,
+    },
+  );
+}
+
+function passRateOf(t: ScorecardTotals): number | undefined {
+  const reviews = t.reviewsPassed + t.reviewsChangesRequested;
+  return reviews > 0
+    ? Math.round((t.reviewsPassed / reviews) * 100)
+    : undefined;
+}
+
+function avgRunSecondsOf(t: ScorecardTotals): number | undefined {
+  return t.durationCount > 0
+    ? Math.round(t.durationSum / t.durationCount / 1000)
+    : undefined;
+}
+
 function formatCents(cents: number): string {
   return (cents / 100).toLocaleString(undefined, {
     minimumFractionDigits: 2,
@@ -83,140 +149,175 @@ function AgentMetricsTab() {
   // The query returns v.any(); the payload shape is owned by getAgentScorecard.
   const scorecard: ScorecardPayload | undefined = data ?? undefined;
 
-  const totals = (scorecard?.daily ?? []).reduce(
-    (acc, day) => ({
-      runsStarted: acc.runsStarted + day.runsStarted,
-      runsFailed: acc.runsFailed + day.runsFailed,
-      durationSum: acc.durationSum + day.runDurationSumMs,
-      durationCount: acc.durationCount + day.runDurationCount,
-      costCents: acc.costCents + day.costCents,
-      tasksCompleted: acc.tasksCompleted + day.tasksCompleted,
-      reviewsPassed: acc.reviewsPassed + day.reviewsPassed,
-      reviewsChangesRequested:
-        acc.reviewsChangesRequested + day.reviewsChangesRequested,
-      escalations: acc.escalations + day.escalations,
-    }),
-    {
-      runsStarted: 0,
-      runsFailed: 0,
-      durationSum: 0,
-      durationCount: 0,
-      costCents: 0,
-      tasksCompleted: 0,
-      reviewsPassed: 0,
-      reviewsChangesRequested: 0,
-      escalations: 0,
-    },
-  );
-  const reviews = totals.reviewsPassed + totals.reviewsChangesRequested;
-  const passRate =
-    reviews > 0
-      ? Math.round((totals.reviewsPassed / reviews) * 100)
-      : undefined;
-  const avgRunSeconds =
-    totals.durationCount > 0
-      ? Math.round(totals.durationSum / totals.durationCount / 1000)
-      : undefined;
-
-  const stats: Array<{ label: string; value: string; detail?: string }> = [
-    {
-      label: t('scorecard.tasksCompleted'),
-      value: String(totals.tasksCompleted),
-      detail: t('kpi.runs', {
-        started: totals.runsStarted,
-        failed: totals.runsFailed,
-      }),
-    },
-    {
-      label: t('scorecard.reviewOutcome'),
-      value: passRate !== undefined ? `${passRate}%` : '—',
-      detail: t('scorecard.reviewDetail', {
-        passed: totals.reviewsPassed,
-        changes: totals.reviewsChangesRequested,
-        escalations: totals.escalations,
-      }),
-    },
+  const totals = reduceDaily(scorecard?.daily ?? []);
+  const prev = reduceDaily(scorecard?.previousDaily ?? []);
+
+  const passRate = passRateOf(totals);
+  const prevPassRate = passRateOf(prev);
+  const avgRunSeconds = avgRunSecondsOf(totals);
+  const prevAvgRunSeconds = avgRunSecondsOf(prev);
+
+  const activityData = (scorecard?.daily ?? []).map((day) => ({
+    dateKey: day.dateKey,
+    completed: day.runsCompleted,
+    failed: day.runsFailed,
+  }));
+  const activitySeries: ChartSeries[] = [
     {
-      label: t('scorecard.avgRun'),
-      value: avgRunSeconds !== undefined ? `${avgRunSeconds}s` : '—',
+      key: 'completed',
+      label: t('scorecard.runsCompleted'),
+      color: CHART_COLORS.success,
+      stackId: 'runs',
     },
     {
-      label: t('scorecard.spend'),
-      value: formatCents(totals.costCents),
-      detail: t('kpi.costDetail', {
-        perTask:
-          totals.tasksCompleted > 0
-            ? formatCents(totals.costCents / totals.tasksCompleted)
-            : '0.00',
-      }),
+      key: 'failed',
+      label: t('scorecard.runsFailed'),
+      color: CHART_COLORS.failure,
+      stackId: 'runs',
     },
   ];
+  const noActivity = !(scorecard?.daily ?? []).some(
+    (day) => day.runsCompleted + day.runsFailed > 0,
+  );
 
   return (
     <ContentArea variant="narrow" gap={6}>
-      <SectionHeader
+      <MetricsLayout
         title={t('scorecard.title')}
         description={t('scorecard.subtitle')}
-      />
+      >
+        <StatCardGrid cols={2}>
+          <StatCard
+            label={t('scorecard.tasksCompleted')}
+            value={String(totals.tasksCompleted)}
+          >
+            <Stack gap={1} className="mt-0.5">
+              <TrendIndicator
+                value={totals.tasksCompleted}
+                previous={prev.tasksCompleted}
+              />
+              <Text as="p" variant="muted" className="text-xs">
+                {t('kpi.runs', {
+                  started: totals.runsStarted,
+                  failed: totals.runsFailed,
+                })}
+              </Text>
+            </Stack>
+          </StatCard>
 
-      <section className="grid grid-cols-2 gap-3">
-        {stats.map((stat) => (
-          <div
-            key={stat.label}
-            className="border-border bg-card flex flex-col gap-1 rounded-lg border p-4"
+          <StatCard
+            label={t('scorecard.reviewOutcome')}
+            value={passRate !== undefined ? `${passRate}%` : '—'}
           >
-            <Text as="p" variant="muted" className="text-xs">
-              {stat.label}
-            </Text>
-            <Text as="p" className="text-2xl font-semibold tabular-nums">
-              {stat.value}
-            </Text>
-            {stat.detail && (
+            <Stack gap={1} className="mt-0.5">
+              {passRate !== undefined ? (
+                <TrendIndicator value={passRate} previous={prevPassRate} />
+              ) : null}
               <Text as="p" variant="muted" className="text-xs">
-                {stat.detail}
+                {t('scorecard.reviewDetail', {
+                  passed: totals.reviewsPassed,
+                  changes: totals.reviewsChangesRequested,
+                  escalations: totals.escalations,
+                })}
               </Text>
-            )}
-          </div>
-        ))}
-      </section>
-
-      <section className="flex flex-col gap-2">
-        <Text as="h3" variant="label">
-          {t('scorecard.recentRuns')}
-        </Text>
-        {(scorecard?.recentRuns.length ?? 0) === 0 ? (
-          <Text as="p" variant="muted" className="text-sm italic">
-            {t('scorecard.noRuns')}
+            </Stack>
+          </StatCard>
+
+          <StatCard
+            label={t('scorecard.avgRun')}
+            value={avgRunSeconds !== undefined ? `${avgRunSeconds}s` : '—'}
+          >
+            {avgRunSeconds !== undefined ? (
+              <div className="mt-0.5">
+                <TrendIndicator
+                  value={avgRunSeconds}
+                  previous={prevAvgRunSeconds}
+                  inverted
+                />
+              </div>
+            ) : null}
+          </StatCard>
+
+          <StatCard
+            label={t('scorecard.spend')}
+            value={formatCents(totals.costCents)}
+          >
+            <Stack gap={1} className="mt-0.5">
+              <TrendIndicator
+                value={totals.costCents}
+                previous={prev.costCents}
+                inverted
+              />
+              <Text as="p" variant="muted" className="text-xs">
+                {t('kpi.costDetail', {
+                  perTask:
+                    totals.tasksCompleted > 0
+                      ? formatCents(totals.costCents / totals.tasksCompleted)
+                      : '0.00',
+                })}
+              </Text>
+            </Stack>
+          </StatCard>
+        </StatCardGrid>
+
+        {/* Only render the activity chart when there's activity — a zero-run
+            agent is communicated by the "no runs" recent-runs empty state, so an
+            empty chart placeholder would just duplicate that message. */}
+        {noActivity ? null : (
+          <ChartCard
+            title={t('trend.title')}
+            bodyClassName="h-44"
+            legend={<ChartLegend items={seriesToLegend(activitySeries)} />}
+          >
+            <TrendBarChart
+              data={activityData}
+              series={activitySeries}
+              xKey="dateKey"
+              xTickFormatter={(key) => key.slice(5)}
+            />
+          </ChartCard>
+        )}
+
+        <Stack as="section" gap={2}>
+          <Text as="h3" variant="label">
+            {t('scorecard.recentRuns')}
           </Text>
-        ) : (
-          <ul className="border-border divide-border divide-y overflow-hidden rounded-lg border">
-            {scorecard?.recentRuns.map((run) => (
-              <li
-                key={run.runId}
-                className="flex items-center gap-2 px-2.5 py-2 text-sm"
-              >
-                <Badge
-                  variant="outline"
-                  className={cn('text-[10px]', STATUS_COLOR[run.status])}
+          {(scorecard?.recentRuns.length ?? 0) === 0 ? (
+            <Text as="p" variant="muted" className="text-sm italic">
+              {t('scorecard.noRuns')}
+            </Text>
+          ) : (
+            <ul className="border-border divide-border divide-y overflow-hidden rounded-lg border">
+              {scorecard?.recentRuns.map((run) => (
+                <li
+                  key={run.runId}
+                  className="flex items-center gap-2 px-2.5 py-2 text-sm"
                 >
-                  {tTasks(`agentRuns.status.${run.status}`)}
-                </Badge>
-                <span className="text-muted-foreground min-w-0 flex-1 truncate">
-                  {tTasks(`agentRuns.trigger.${run.trigger}`)}
-                  {run.error ? ` · ${run.error}` : ''}
-                </span>
-                <span className="text-muted-foreground shrink-0 text-xs tabular-nums">
-                  {run.durationMs !== undefined
-                    ? `${Math.round(run.durationMs / 1000)}s · `
-                    : ''}
-                  {run.costCents > 0 ? `${formatCents(run.costCents)} · ` : ''}
-                  {formatRelative(new Date(run.startedAt))}
-                </span>
-              </li>
-            ))}
-          </ul>
-        )}
-      </section>
+                  <Badge
+                    variant="outline"
+                    className={cn('text-[10px]', STATUS_COLOR[run.status])}
+                  >
+                    {tTasks(`agentRuns.status.${run.status}`)}
+                  </Badge>
+                  <span className="text-muted-foreground min-w-0 flex-1 truncate">
+                    {tTasks(`agentRuns.trigger.${run.trigger}`)}
+                    {run.error ? ` · ${run.error}` : ''}
+                  </span>
+                  <span className="text-muted-foreground shrink-0 text-xs tabular-nums">
+                    {run.durationMs !== undefined
+                      ? `${Math.round(run.durationMs / 1000)}s · `
+                      : ''}
+                    {run.costCents > 0
+                      ? `${formatCents(run.costCents)} · `
+                      : ''}
+                    {formatRelative(new Date(run.startedAt))}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </Stack>
+      </MetricsLayout>
     </ContentArea>
   );
 }
diff --git a/services/platform/app/routes/dashboard/$id/agents/$agentId/response-tuning.tsx b/services/platform/app/routes/dashboard/$id/agents/$agentId/response-tuning.tsx
deleted file mode 100644
index 40ed9a0984..0000000000
--- a/services/platform/app/routes/dashboard/$id/agents/$agentId/response-tuning.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router';
-
-import { AgentResponseTuning } from '@/app/features/agents/components/agent-response-tuning';
-import { seo } from '@/lib/utils/seo';
-
-export const Route = createFileRoute(
-  '/dashboard/$id/agents/$agentId/response-tuning',
-)({
-  head: () => ({
-    meta: seo('agentResponseTuning'),
-  }),
-  component: ResponseTuningTab,
-});
-
-function ResponseTuningTab() {
-  const { id: organizationId, agentId } = Route.useParams();
-
-  return (
-    <AgentResponseTuning organizationId={organizationId} agentId={agentId} />
-  );
-}
diff --git a/services/platform/app/routes/dashboard/$id/agents/metrics.tsx b/services/platform/app/routes/dashboard/$id/agents/metrics.tsx
index d75d66b7c4..b55c67f0be 100644
--- a/services/platform/app/routes/dashboard/$id/agents/metrics.tsx
+++ b/services/platform/app/routes/dashboard/$id/agents/metrics.tsx
@@ -90,7 +90,6 @@ function AgentsMetricsPage() {
                 if (next === 7 || next === 30 || next === 90)
                   handleChangePeriod(next);
               }}
-              size="sm"
             />
           </div>
         }
diff --git a/services/platform/app/routes/dashboard/$id/automations/$amId.tsx b/services/platform/app/routes/dashboard/$id/automations/$amId.tsx
index edc79938aa..d2ad17aedb 100644
--- a/services/platform/app/routes/dashboard/$id/automations/$amId.tsx
+++ b/services/platform/app/routes/dashboard/$id/automations/$amId.tsx
@@ -1,6 +1,6 @@
 import { Badge } from '@tale/ui/badge';
 import { Heading } from '@tale/ui/heading';
-import { Center } from '@tale/ui/layout';
+import { Center, Row, Stack } from '@tale/ui/layout';
 import { SkeletonBox } from '@tale/ui/skeleton';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { Text } from '@tale/ui/text';
@@ -110,7 +110,11 @@ const PLACEHOLDER_STEPS = [
  */
 function AutomationCanvasSkeleton() {
   return (
-    <div className="relative flex w-full flex-1 justify-stretch overflow-auto">
+    <Row
+      gap={0}
+      align="stretch"
+      className="relative w-full flex-1 justify-stretch overflow-auto"
+    >
       <div className="bg-background relative min-h-0 flex-[1_1_0]">
         <div
           className="absolute inset-0 opacity-20"
@@ -121,7 +125,7 @@ function AutomationCanvasSkeleton() {
           }}
         />
         <Center className="absolute inset-0">
-          <div className="flex flex-col items-center">
+          <Stack gap={0} align="center">
             {PLACEHOLDER_STEPS.map((step, index) => (
               <div key={step.name}>
                 {index > 0 && (
@@ -130,7 +134,7 @@ function AutomationCanvasSkeleton() {
                 {/* Real step-card shape (mirrors AutomationStep):
                     icon, heading, caption, trailing type badge. */}
                 <div className="border-border bg-card w-[18.75rem] rounded-lg border shadow-sm">
-                  <div className="flex gap-3 px-2.5 py-2">
+                  <Row gap={3} align="stretch" className="px-2.5 py-2">
                     <SkeletonBox>
                       <div className="size-5 shrink-0 rounded-sm" />
                     </SkeletonBox>
@@ -148,11 +152,11 @@ function AutomationCanvasSkeleton() {
                     >
                       <SkeletonBox>{step.type}</SkeletonBox>
                     </Badge>
-                  </div>
+                  </Row>
                 </div>
               </div>
             ))}
-          </div>
+          </Stack>
         </Center>
         <div className="absolute right-4 bottom-4">
           <SkeletonBox>
@@ -160,7 +164,10 @@ function AutomationCanvasSkeleton() {
           </SkeletonBox>
         </div>
         <div className="absolute bottom-4 left-1/2 -translate-x-1/2">
-          <div className="ring-border bg-background flex items-center gap-2 rounded-lg p-1 shadow-sm ring-1">
+          <Row
+            gap={2}
+            className="ring-border bg-background rounded-lg p-1 shadow-sm ring-1"
+          >
             <SkeletonBox>
               <div className="size-8 rounded-md" />
             </SkeletonBox>
@@ -173,10 +180,10 @@ function AutomationCanvasSkeleton() {
             <SkeletonBox>
               <div className="size-8 rounded-md" />
             </SkeletonBox>
-          </div>
+          </Row>
         </div>
       </div>
-    </div>
+    </Row>
   );
 }
 
@@ -242,20 +249,20 @@ function AutomationDetailLayout() {
             {/* Real tab strip: the static tab labels are known at load and
                 stay real text; only the trailing assistant/history actions
                 (data-dependent) are masked. */}
-            <div className="border-border flex min-h-12 shrink-0 flex-nowrap items-center gap-4 border-b px-4">
+            <Row className="border-border min-h-12 shrink-0 border-b px-4">
               <Text variant="caption">{t('navigation.editor')}</Text>
               <Text variant="caption">{t('executions.title')}</Text>
               <Text variant="caption">{t('configuration.title')}</Text>
               <Text variant="caption">{t('triggers.title')}</Text>
-              <div className="ml-auto flex items-center gap-2">
+              <Row gap={2} className="ml-auto">
                 <SkeletonBox>
                   <div className="size-8 rounded-md" />
                 </SkeletonBox>
                 <SkeletonBox>
                   <div className="h-8 w-20 rounded-md" />
                 </SkeletonBox>
-              </div>
-            </div>
+              </Row>
+            </Row>
           </Skeletonize>
         }
         organizationId={organizationId}
@@ -271,17 +278,17 @@ function AutomationDetailLayout() {
             With `contents`, the row below is the direct flex child of the
             column, exactly like the loaded layout. */}
         <Skeletonize loading className="contents">
-          <div className="relative flex min-h-0 flex-1">
-            <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto">
+          <Row gap={0} align="stretch" className="relative min-h-0 flex-1">
+            <Stack gap={0} className="min-h-0 min-w-0 flex-1 overflow-y-auto">
               <AutomationCanvasSkeleton />
-            </div>
+            </Stack>
             {/* Real AI-panel aside (mounts open by default once loaded): same
                 fixed-width bordered column with a masked header. */}
             <aside
               style={{ width: 384 }}
               className="bg-background border-border hidden min-h-0 shrink-0 flex-col border-l md:flex"
             >
-              <div className="border-border flex shrink-0 items-center gap-3 border-b p-3">
+              <Row gap={3} className="border-border shrink-0 border-b p-3">
                 <SkeletonBox>
                   <div className="size-8 rounded-lg" />
                 </SkeletonBox>
@@ -293,9 +300,9 @@ function AutomationDetailLayout() {
                     <div className="size-8 rounded-md" />
                   </SkeletonBox>
                 </div>
-              </div>
+              </Row>
             </aside>
-          </div>
+          </Row>
         </Skeletonize>
       </PageLayout>
     );
@@ -470,8 +477,8 @@ function AutomationDetailInner({
       organizationId={organizationId}
     >
       <ExecutionStatusProvider>
-        <div className="relative flex min-h-0 flex-1">
-          <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto">
+        <Row gap={0} align="stretch" className="relative min-h-0 flex-1">
+          <Stack gap={0} className="min-h-0 min-w-0 flex-1 overflow-y-auto">
             {isExactAutomationPage ? (
               <SuspenseBoundary
                 fallback={
@@ -496,7 +503,7 @@ function AutomationDetailInner({
             ) : (
               <Outlet />
             )}
-          </div>
+          </Stack>
 
           {isAIChatOpen && !isUrlSidePanelOpen && (
             <AutomationAIChatPanel
@@ -522,7 +529,7 @@ function AutomationDetailInner({
               onPanelWidthChange={setPanelWidth}
             />
           )}
-        </div>
+        </Row>
       </ExecutionStatusProvider>
     </PageLayout>
   );
diff --git a/services/platform/app/routes/dashboard/$id/automations/index.tsx b/services/platform/app/routes/dashboard/$id/automations/index.tsx
index f75324b17e..b636a1b7a7 100644
--- a/services/platform/app/routes/dashboard/$id/automations/index.tsx
+++ b/services/platform/app/routes/dashboard/$id/automations/index.tsx
@@ -1,3 +1,4 @@
+import { Row, Stack } from '@tale/ui/layout';
 import { createFileRoute } from '@tanstack/react-router';
 import { z } from 'zod';
 
@@ -45,8 +46,8 @@ function AutomationsPage() {
     // The DataTable renders its own loading skeleton; mirror AutomationsTable's
     // header so the layout doesn't shift once the ability check resolves.
     return (
-      <div className="flex flex-col gap-4 p-4">
-        <div className="flex items-center justify-between gap-4">
+      <Stack className="p-4">
+        <Row justify="between">
           <SearchInput
             wrapperClassName="w-full max-w-sm"
             placeholder={searchPlaceholder}
@@ -56,7 +57,7 @@ function AutomationsPage() {
             readOnly
           />
           <AutomationsActionMenu organizationId={organizationId} />
-        </div>
+        </Row>
         <DataTable<AutomationTableItem>
           columns={columns}
           data={[]}
@@ -69,7 +70,7 @@ function AutomationsPage() {
             totalCount: 0,
           }}
         />
-      </div>
+      </Stack>
     );
   }
 
diff --git a/services/platform/app/routes/dashboard/$id/chat.tsx b/services/platform/app/routes/dashboard/$id/chat.tsx
index 74015f0da0..fa91a0e45a 100644
--- a/services/platform/app/routes/dashboard/$id/chat.tsx
+++ b/services/platform/app/routes/dashboard/$id/chat.tsx
@@ -1,4 +1,5 @@
 import { Button } from '@tale/ui/button';
+import { Row, Stack } from '@tale/ui/layout';
 import { createFileRoute, useMatch, useNavigate } from '@tanstack/react-router';
 import { useQuery } from 'convex/react';
 import { m, AnimatePresence } from 'framer-motion';
@@ -174,9 +175,12 @@ function ThreadGate({
     return (
       <SuspenseBoundary
         fallback={
-          <div className="flex h-full min-h-0 flex-1 flex-col overflow-y-auto px-4 sm:px-6">
+          <Stack
+            gap={0}
+            className="h-full min-h-0 flex-1 overflow-y-auto px-4 sm:px-6"
+          >
             <ChatMessagesSkeleton />
-          </div>
+          </Stack>
         }
       >
         <ChatInterface
@@ -207,7 +211,7 @@ function ThreadGate({
   // Loaded but thread not found / not authorized
   if (threadStatus === null) {
     return (
-      <div className="flex h-full flex-col items-center justify-center gap-4 p-8">
+      <Stack align="center" justify="center" className="h-full p-8">
         <p className="text-muted-foreground text-sm">{tChat('notFound')}</p>
         <Button
           variant="secondary"
@@ -220,7 +224,7 @@ function ThreadGate({
         >
           {tChat('newChat')}
         </Button>
-      </div>
+      </Stack>
     );
   }
 
@@ -310,9 +314,9 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
         <LayoutErrorBoundary organizationId={organizationId}>
           <SuspenseBoundary
             fallback={
-              <div className="flex h-full flex-col overflow-y-auto px-4 sm:px-6">
+              <Stack gap={0} className="h-full overflow-y-auto px-4 sm:px-6">
                 <ChatMessagesSkeleton />
-              </div>
+              </Stack>
             }
           >
             <SharedChatView
@@ -331,7 +335,7 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
         <ChatHeader organizationId={organizationId} threadId={threadId} />
       </LayoutErrorBoundary>
 
-      <div className="flex min-h-0 flex-1 overflow-hidden">
+      <Row gap={0} align="stretch" className="min-h-0 flex-1 overflow-hidden">
         <AnimatePresence initial={false}>
           {isHistoryOpen && (
             <m.div
@@ -341,11 +345,14 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
               transition={{ duration: 0.3, ease: [0.25, 0.1, 0.25, 1] }}
               className="relative hidden w-[18rem] shrink-0 md:block"
             >
-              <div className="border-border bg-background flex h-full flex-col overflow-hidden border-r">
+              <Stack
+                gap={0}
+                className="border-border bg-background h-full overflow-hidden border-r"
+              >
                 <LayoutErrorBoundary organizationId={organizationId}>
                   <ChatHistorySidebar organizationId={organizationId} />
                 </LayoutErrorBoundary>
-              </div>
+              </Stack>
             </m.div>
           )}
         </AnimatePresence>
@@ -355,7 +362,7 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
             message list uses. Without this, the canvas reads files from the raw
             route threadId and branch-tip files vanish after streaming. */}
         <BranchProvider threadId={threadId} organizationId={organizationId}>
-          <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+          <Stack gap={0} className="min-h-0 flex-1 overflow-hidden">
             <BudgetBanner organizationId={organizationId} />
             <LayoutErrorBoundary organizationId={organizationId}>
               <ThreadGate
@@ -364,7 +371,7 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
                 newChatCount={newChatCount}
               />
             </LayoutErrorBoundary>
-          </div>
+          </Stack>
 
           <PlanPane />
           <CanvasPane organizationId={organizationId} />
@@ -386,7 +393,7 @@ function ChatLayoutContent({ organizationId }: { organizationId: string }) {
             </LayoutErrorBoundary>
           )}
         </BranchProvider>
-      </div>
+      </Row>
 
       {/* Mobile: present the workspace-files pane in a right Sheet like the
           mobile history sidebar, so the desktop split-pane never breaks the
diff --git a/services/platform/app/routes/dashboard/$id/chat/shared/$shareToken.tsx b/services/platform/app/routes/dashboard/$id/chat/shared/$shareToken.tsx
index 6562fe794e..eba838a646 100644
--- a/services/platform/app/routes/dashboard/$id/chat/shared/$shareToken.tsx
+++ b/services/platform/app/routes/dashboard/$id/chat/shared/$shareToken.tsx
@@ -1,3 +1,4 @@
+import { Stack } from '@tale/ui/layout';
 import { SkeletonText } from '@tale/ui/skeleton';
 import { createFileRoute } from '@tanstack/react-router';
 
@@ -22,9 +23,9 @@ function SharedChatLayout() {
       <LayoutErrorBoundary organizationId={organizationId}>
         <SuspenseBoundary
           fallback={
-            <div className="flex h-full flex-col p-4 sm:p-6">
+            <Stack gap={0} className="h-full p-4 sm:p-6">
               <SkeletonText lines={3} />
-            </div>
+            </Stack>
           }
         >
           <SharedChatView
diff --git a/services/platform/app/routes/dashboard/$id/settings.tsx b/services/platform/app/routes/dashboard/$id/settings.tsx
index 375af6a2f1..961ce34cdf 100644
--- a/services/platform/app/routes/dashboard/$id/settings.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings.tsx
@@ -1,3 +1,4 @@
+import { Row } from '@tale/ui/layout';
 import { Outlet, createFileRoute, useLocation } from '@tanstack/react-router';
 
 import {
@@ -112,8 +113,12 @@ function SettingsMobileActionBar() {
   if (!controller) return null;
 
   return (
-    <div className="border-border flex items-center justify-end gap-2 border-b px-4 py-2 md:hidden">
+    <Row
+      gap={2}
+      justify="end"
+      className="border-border border-b px-4 py-2 md:hidden"
+    >
       <EditorActions controller={controller} entityKind="settings" />
-    </div>
+    </Row>
   );
 }
diff --git a/services/platform/app/routes/dashboard/$id/settings/governance/run-code-policy.tsx b/services/platform/app/routes/dashboard/$id/settings/governance/run-code-policy.tsx
index 9717673e1a..fccbc239c8 100644
--- a/services/platform/app/routes/dashboard/$id/settings/governance/run-code-policy.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/governance/run-code-policy.tsx
@@ -2,7 +2,6 @@
 
 import { Button } from '@tale/ui/button';
 import { Stack } from '@tale/ui/layout';
-import { PageSection } from '@tale/ui/page-section';
 import { Skeletonize } from '@tale/ui/skeleton-context';
 import { createFileRoute } from '@tanstack/react-router';
 import { CheckCircle2, XCircle } from 'lucide-react';
@@ -12,6 +11,7 @@ import { Input } from '@/app/components/ui/forms/input';
 import { RadioGroup } from '@/app/components/ui/forms/radio-group';
 import { Textarea } from '@/app/components/ui/forms/textarea';
 import { SettingsPage } from '@/app/features/settings/components/settings-page';
+import { SettingsSection } from '@/app/features/settings/components/settings-section';
 import { useAbility } from '@/app/hooks/use-ability';
 import { useConvexMutation } from '@/app/hooks/use-convex-mutation';
 import { useConvexQuery } from '@/app/hooks/use-convex-query';
@@ -200,16 +200,12 @@ function RunCodePolicyRoute() {
 
   return (
     <SettingsPage>
-      <PageSection
-        title={t('runCodePolicy.title')}
-        description={t('runCodePolicy.description')}
-      />
       <Skeletonize
         loading={isLoading}
         label={t('runCodePolicy.title')}
-        className="flex flex-col gap-6"
+        className="flex flex-col gap-8"
       >
-        <PageSection
+        <SettingsSection
           title={t('runCodePolicy.modeSectionTitle')}
           description={t('runCodePolicy.modeSectionDescription')}
         >
@@ -235,9 +231,9 @@ function RunCodePolicyRoute() {
               },
             ]}
           />
-        </PageSection>
+        </SettingsSection>
 
-        <PageSection
+        <SettingsSection
           title={t('runCodePolicy.pythonSectionTitle')}
           description={t('runCodePolicy.listsHint')}
         >
@@ -261,9 +257,9 @@ function RunCodePolicyRoute() {
               rows={4}
             />
           </Stack>
-        </PageSection>
+        </SettingsSection>
 
-        <PageSection
+        <SettingsSection
           title={t('runCodePolicy.nodeSectionTitle')}
           description={t('runCodePolicy.listsHint')}
         >
@@ -287,12 +283,11 @@ function RunCodePolicyRoute() {
               rows={4}
             />
           </Stack>
-        </PageSection>
+        </SettingsSection>
 
         <Button
           onClick={handleSave}
           disabled={cannotManage || upsertMutation.isPending}
-          size="sm"
           className="self-start"
         >
           {upsertMutation.isPending
@@ -300,7 +295,7 @@ function RunCodePolicyRoute() {
             : t('runCodePolicy.save')}
         </Button>
 
-        <PageSection
+        <SettingsSection
           title={t('runCodePolicy.testerTitle')}
           description={t('runCodePolicy.testerDescription')}
         >
@@ -328,12 +323,10 @@ function RunCodePolicyRoute() {
               }
               value={testInput}
               onChange={(e) => setTestInput(e.target.value)}
-              size="sm"
             />
             <Button
               type="button"
               variant="secondary"
-              size="sm"
               onClick={handleRunTest}
               className="self-start"
               disabled={testInput.trim().length === 0}
@@ -342,9 +335,11 @@ function RunCodePolicyRoute() {
             </Button>
 
             {testRows.length > 0 && (
-              <ul
+              <Stack
                 role="list"
-                className="border-border bg-card divide-border flex flex-col divide-y rounded-md border"
+                as="ul"
+                gap={0}
+                className="border-border bg-card divide-border divide-y rounded-md border"
               >
                 {testRows.map((row, idx) => {
                   const allowed = row.decision.decision === 'allowed';
@@ -385,10 +380,10 @@ function RunCodePolicyRoute() {
                     </li>
                   );
                 })}
-              </ul>
+              </Stack>
             )}
           </Stack>
-        </PageSection>
+        </SettingsSection>
       </Skeletonize>
     </SettingsPage>
   );
diff --git a/services/platform/app/routes/dashboard/$id/settings/governance/security-monitoring.tsx b/services/platform/app/routes/dashboard/$id/settings/governance/security-monitoring.tsx
index 6cd82307ca..749f3bfab2 100644
--- a/services/platform/app/routes/dashboard/$id/settings/governance/security-monitoring.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/governance/security-monitoring.tsx
@@ -31,7 +31,7 @@ function SecurityMonitoringRoute() {
   // reveal together under one coordinated skeletonization and are spaced by
   // SettingsPage's layout.
   return (
-    <SettingsPage narrow>
+    <SettingsPage>
       <LoginPolicyEditor organizationId={organizationId} />
       <PasswordPolicyEditor organizationId={organizationId} />
       <TwoFactorPolicyEditor organizationId={organizationId} />
diff --git a/services/platform/app/routes/dashboard/$id/settings/organization.tsx b/services/platform/app/routes/dashboard/$id/settings/organization.tsx
index bf154650c8..561baf9cc1 100644
--- a/services/platform/app/routes/dashboard/$id/settings/organization.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/organization.tsx
@@ -29,6 +29,6 @@ export const Route = createFileRoute('/dashboard/$id/settings/organization')({
 function OrganizationSettingsPage() {
   const { id: organizationId } = Route.useParams();
   // The container owns loading + access + the skeletonized view, so the
-  // skeleton IS the real `SettingsPage narrow` layout (matched centering).
+  // skeleton IS the real `SettingsPage` layout.
   return <OrganizationSettings organizationId={organizationId} />;
 }
diff --git a/services/platform/app/routes/dashboard/$id/settings/providers.tsx b/services/platform/app/routes/dashboard/$id/settings/providers.tsx
index a6c81f0b3b..dad8143864 100644
--- a/services/platform/app/routes/dashboard/$id/settings/providers.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/providers.tsx
@@ -30,7 +30,7 @@ function ProvidersLayout() {
     // (driven by `useListPage`'s `isLoading`), so no bespoke skeleton is
     // needed — the table swaps in under a stable header.
     return (
-      <SettingsPage narrow>
+      <SettingsPage>
         <SettingsSection
           title={tNav('providers')}
           description={tSettings('menu.providers.description')}
diff --git a/services/platform/app/routes/dashboard/$id/settings/providers/$providerName.tsx b/services/platform/app/routes/dashboard/$id/settings/providers/$providerName.tsx
index b8b5c7259b..74d4ab2815 100644
--- a/services/platform/app/routes/dashboard/$id/settings/providers/$providerName.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/providers/$providerName.tsx
@@ -23,7 +23,7 @@ function ProviderDetailRoute() {
   // identical on both routes (no shift when navigating between them, and
   // none when the layout-route skeleton hands off to this view).
   return (
-    <SettingsPage narrow>
+    <SettingsPage>
       <SettingsSection
         title={tNav('providers')}
         description={tSettings('menu.providers.description')}
diff --git a/services/platform/app/routes/dashboard/$id/settings/providers/index.tsx b/services/platform/app/routes/dashboard/$id/settings/providers/index.tsx
index d3359759ae..b1bf810d99 100644
--- a/services/platform/app/routes/dashboard/$id/settings/providers/index.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/providers/index.tsx
@@ -23,10 +23,7 @@ function ProvidersIndexRoute() {
       >
         <ProvidersTable organizationId={id} />
       </SettingsSection>
-      <ModelCatalogCard
-        organizationId={id}
-        className="border-border border-t pt-8"
-      />
+      <ModelCatalogCard organizationId={id} />
     </SettingsPage>
   );
 }
diff --git a/services/platform/app/routes/dashboard/$id/settings/sandboxes.tsx b/services/platform/app/routes/dashboard/$id/settings/sandboxes.tsx
index 8b2e3acb00..0274a03bf1 100644
--- a/services/platform/app/routes/dashboard/$id/settings/sandboxes.tsx
+++ b/services/platform/app/routes/dashboard/$id/settings/sandboxes.tsx
@@ -1,5 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router';
 
+import { SettingsPage } from '@/app/features/settings/components/settings-page';
 import { SandboxesSettings } from '@/app/features/settings/sandboxes/sandboxes-settings';
 import { seo } from '@/lib/utils/seo';
 
@@ -12,5 +13,9 @@ export const Route = createFileRoute('/dashboard/$id/settings/sandboxes')({
 
 function SandboxesPage() {
   const { id: organizationId } = Route.useParams();
-  return <SandboxesSettings organizationId={organizationId} />;
+  return (
+    <SettingsPage>
+      <SandboxesSettings organizationId={organizationId} />
+    </SettingsPage>
+  );
 }
diff --git a/services/platform/app/routes/dashboard/changelog.tsx b/services/platform/app/routes/dashboard/changelog.tsx
index 5d69ffff21..4f1300b19d 100644
--- a/services/platform/app/routes/dashboard/changelog.tsx
+++ b/services/platform/app/routes/dashboard/changelog.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useLocale } from '@tale/ui/i18n/locale-provider';
-import { VStack } from '@tale/ui/layout';
+import { Row, Stack, VStack } from '@tale/ui/layout';
 import { Accordion } from '@tale/ui/markdown/components/accordion';
 import { Spinner } from '@tale/ui/spinner';
 import { Text } from '@tale/ui/text';
@@ -157,9 +157,9 @@ function ChangelogPage() {
 
   if (releases === null && !error) {
     return (
-      <div className="flex min-h-[60vh] items-center justify-center">
+      <Row gap={0} justify="center" className="min-h-[60vh]">
         <Spinner size="lg" />
-      </div>
+      </Row>
     );
   }
 
@@ -252,7 +252,7 @@ function ChangelogPage() {
         ) : count === 0 ? (
           <Text variant="muted">{t('viewer.upToDate')}</Text>
         ) : (
-          <div className="flex flex-col gap-2">
+          <Stack gap={2}>
             {visibleReleases.map((release, i) => {
               const formattedDate = release.publishedAt
                 ? dateFormatter.format(new Date(release.publishedAt))
@@ -284,7 +284,7 @@ function ChangelogPage() {
                 </Accordion>
               );
             })}
-          </div>
+          </Stack>
         )}
 
         <div className="border-border-base mt-8 border-t pt-4">
diff --git a/services/platform/app/routes/forced-change-password.$id.tsx b/services/platform/app/routes/forced-change-password.$id.tsx
index af185eb15e..81cf25a310 100644
--- a/services/platform/app/routes/forced-change-password.$id.tsx
+++ b/services/platform/app/routes/forced-change-password.$id.tsx
@@ -182,7 +182,6 @@ function ForcedChangePasswordPage() {
                     <Input
                       id="new-password"
                       type="password"
-                      size="lg"
                       autoComplete="new-password"
                       label={tAuth('changePassword.newPassword')}
                       placeholder={tAuth('changePassword.placeholder.new')}
@@ -200,7 +199,6 @@ function ForcedChangePasswordPage() {
                   <Input
                     id="confirm-password"
                     type="password"
-                    size="lg"
                     autoComplete="new-password"
                     label={tAuth('changePassword.confirmPassword')}
                     placeholder={tAuth('changePassword.placeholder.confirm')}
@@ -210,7 +208,6 @@ function ForcedChangePasswordPage() {
                   />
                   <Button
                     type="submit"
-                    size="lg"
                     fullWidth
                     disabled={isSubmitting || !isValid}
                   >
diff --git a/services/platform/convex/_generated/api.d.ts b/services/platform/convex/_generated/api.d.ts
index 42a89d242f..76a27b82c1 100644
--- a/services/platform/convex/_generated/api.d.ts
+++ b/services/platform/convex/_generated/api.d.ts
@@ -190,6 +190,7 @@ import type * as agents_org_chart_graph from "../agents/org_chart_graph.js";
 import type * as agents_provision_defaults from "../agents/provision_defaults.js";
 import type * as agents_provision_defaults_mutations from "../agents/provision_defaults_mutations.js";
 import type * as agents_queries from "../agents/queries.js";
+import type * as agents_recover_stuck_chat_turns from "../agents/recover_stuck_chat_turns.js";
 import type * as agents_resolve_agent_config from "../agents/resolve_agent_config.js";
 import type * as agents_resolve_role_to_agent from "../agents/resolve_role_to_agent.js";
 import type * as agents_rest_api from "../agents/rest_api.js";
@@ -250,6 +251,7 @@ import type * as collab_notify from "../collab/notify.js";
 import type * as collab_notify_workforce from "../collab/notify_workforce.js";
 import type * as collab_preferences from "../collab/preferences.js";
 import type * as collab_subscriptions from "../collab/subscriptions.js";
+import type * as control_drain from "../control/drain.js";
 import type * as conversations_actions from "../conversations/actions.js";
 import type * as conversations_add_message_to_conversation from "../conversations/add_message_to_conversation.js";
 import type * as conversations_build_threading_headers from "../conversations/build_threading_headers.js";
@@ -1032,6 +1034,7 @@ import type * as providers_auth from "../providers/auth.js";
 import type * as providers_circuit_breaker from "../providers/circuit_breaker.js";
 import type * as providers_errors from "../providers/errors.js";
 import type * as providers_failover from "../providers/failover.js";
+import type * as providers_failure_scope from "../providers/failure_scope.js";
 import type * as providers_file_actions from "../providers/file_actions.js";
 import type * as providers_file_utils from "../providers/file_utils.js";
 import type * as providers_provider_attribution from "../providers/provider_attribution.js";
@@ -1162,6 +1165,7 @@ import type * as threads_fork_and_chat from "../threads/fork_and_chat.js";
 import type * as threads_fork_own_thread from "../threads/fork_own_thread.js";
 import type * as threads_fork_thread from "../threads/fork_thread.js";
 import type * as threads_generate_thread_title from "../threads/generate_thread_title.js";
+import type * as threads_generation_liveness from "../threads/generation_liveness.js";
 import type * as threads_get_latest_thread_with_message_count from "../threads/get_latest_thread_with_message_count.js";
 import type * as threads_get_latest_tool_message from "../threads/get_latest_tool_message.js";
 import type * as threads_get_message_error from "../threads/get_message_error.js";
@@ -1734,6 +1738,7 @@ declare const fullApi: ApiFromModules<{
   "agents/provision_defaults": typeof agents_provision_defaults;
   "agents/provision_defaults_mutations": typeof agents_provision_defaults_mutations;
   "agents/queries": typeof agents_queries;
+  "agents/recover_stuck_chat_turns": typeof agents_recover_stuck_chat_turns;
   "agents/resolve_agent_config": typeof agents_resolve_agent_config;
   "agents/resolve_role_to_agent": typeof agents_resolve_role_to_agent;
   "agents/rest_api": typeof agents_rest_api;
@@ -1794,6 +1799,7 @@ declare const fullApi: ApiFromModules<{
   "collab/notify_workforce": typeof collab_notify_workforce;
   "collab/preferences": typeof collab_preferences;
   "collab/subscriptions": typeof collab_subscriptions;
+  "control/drain": typeof control_drain;
   "conversations/actions": typeof conversations_actions;
   "conversations/add_message_to_conversation": typeof conversations_add_message_to_conversation;
   "conversations/build_threading_headers": typeof conversations_build_threading_headers;
@@ -2576,6 +2582,7 @@ declare const fullApi: ApiFromModules<{
   "providers/circuit_breaker": typeof providers_circuit_breaker;
   "providers/errors": typeof providers_errors;
   "providers/failover": typeof providers_failover;
+  "providers/failure_scope": typeof providers_failure_scope;
   "providers/file_actions": typeof providers_file_actions;
   "providers/file_utils": typeof providers_file_utils;
   "providers/provider_attribution": typeof providers_provider_attribution;
@@ -2706,6 +2713,7 @@ declare const fullApi: ApiFromModules<{
   "threads/fork_own_thread": typeof threads_fork_own_thread;
   "threads/fork_thread": typeof threads_fork_thread;
   "threads/generate_thread_title": typeof threads_generate_thread_title;
+  "threads/generation_liveness": typeof threads_generation_liveness;
   "threads/get_latest_thread_with_message_count": typeof threads_get_latest_thread_with_message_count;
   "threads/get_latest_tool_message": typeof threads_get_latest_tool_message;
   "threads/get_message_error": typeof threads_get_message_error;
diff --git a/services/platform/convex/agents/auto_route.ts b/services/platform/convex/agents/auto_route.ts
index 71e205c22a..e23fff57c5 100644
--- a/services/platform/convex/agents/auto_route.ts
+++ b/services/platform/convex/agents/auto_route.ts
@@ -57,11 +57,12 @@ import {
   parseRouterDecision,
   pickDefault,
   type RouterDecision,
+  type RouterReasoningSeed,
   type RouterTuningAdvice,
 } from './auto_route_helpers';
 import type { AgentReadResult } from './file_utils';
 import { listInstalledAgentsForOrg } from './internal_actions';
-import { routeTuningValidator } from './schema';
+import { routeSeedValidator, routeTuningValidator } from './schema';
 
 /** Hard ceiling on the classifier call — beyond this we use the default. Kept
  *  in step with the `router` agent's declared `timeoutMs` so a fast classifier
@@ -80,8 +81,10 @@ interface AutoRouteResult {
   reason: AutoRouteReason;
   /** Advisory reply-language hint (BCP-47 or language name); fallback only. */
   language?: string;
-  /** Advisory qualitative response shaping (merged onto the agent's tuning). */
+  /** Advisory qualitative response shaping (drives the prose style suffix). */
   tuning?: RouterTuningAdvice;
+  /** Advisory reasoning seed (governor prior for effort/creativity). */
+  seed?: RouterReasoningSeed;
   /** Capability slugs the router suggests enabling (allowlist-gated by caller). */
   capabilities?: string[];
 }
@@ -89,7 +92,7 @@ interface AutoRouteResult {
 /** The advisory fields shared by a cached entry and a fresh decision. */
 type RouteAdvice = Pick<
   AutoRouteResult,
-  'language' | 'tuning' | 'capabilities'
+  'language' | 'tuning' | 'seed' | 'capabilities'
 >;
 
 /**
@@ -100,6 +103,7 @@ function advisoryFields(advice: RouteAdvice): RouteAdvice {
   return {
     ...(advice.language ? { language: advice.language } : {}),
     ...(advice.tuning ? { tuning: advice.tuning } : {}),
+    ...(advice.seed ? { seed: advice.seed } : {}),
     ...(advice.capabilities ? { capabilities: advice.capabilities } : {}),
   };
 }
@@ -114,11 +118,11 @@ function createRouter(
     instructions,
     // Cap output so a chatty model can't ramble, but leave room for the full
     // single-line decision object — slug PLUS the advisory fields (language,
-    // style, verbosity, capabilities). Too tight and the JSON gets truncated
-    // mid-object, the parser finds no closing brace, and the route silently
-    // falls back to the default agent (notably for any reply that carries a
-    // `language` hint, e.g. "translate this to German").
-    callSettings: { maxOutputTokens: 128 },
+    // style, verbosity, effort, creativity, capabilities). Too tight and the
+    // JSON gets truncated mid-object, the parser finds no closing brace, and
+    // the route silently falls back to the default agent (notably for any reply
+    // that carries a `language` hint, e.g. "translate this to German").
+    callSettings: { maxOutputTokens: 160 },
   });
 }
 
@@ -203,6 +207,7 @@ export const resolveAutoRoute = internalAction({
     reason: autoRouteReasonValidator,
     language: v.optional(v.string()),
     tuning: v.optional(routeTuningValidator),
+    seed: v.optional(routeSeedValidator),
     capabilities: v.optional(v.array(v.string())),
   }),
   handler: async (ctx: ActionCtx, args): Promise<AutoRouteResult> => {
diff --git a/services/platform/convex/agents/auto_route_helpers.test.ts b/services/platform/convex/agents/auto_route_helpers.test.ts
index d44090b633..6f824b1cd1 100644
--- a/services/platform/convex/agents/auto_route_helpers.test.ts
+++ b/services/platform/convex/agents/auto_route_helpers.test.ts
@@ -6,7 +6,6 @@ import {
   filterRoutingCandidates,
   matchSlug,
   hashCandidates,
-  mergeRouterTuning,
   normalizeMessageKey,
   parseRouterDecision,
   pickDefault,
@@ -224,28 +223,25 @@ describe('parseRouterDecision', () => {
       )?.capabilities,
     ).toEqual(['web']);
   });
-});
 
-describe('mergeRouterTuning', () => {
-  it('fills only unset / adaptive fields; author values win', () => {
+  it('extracts only valid effort/creativity enum values into seed', () => {
     expect(
-      mergeRouterTuning(
-        { style: 'formal', verbosity: 'adaptive' },
-        { style: 'concise', verbosity: 'terse' },
-      ),
-    ).toEqual({ style: 'formal', verbosity: 'terse' });
-  });
-
-  it('returns the author config untouched when there is no advice', () => {
-    const author = { style: 'concise' as const };
-    expect(mergeRouterTuning(author, undefined)).toBe(author);
-    expect(mergeRouterTuning(author, {})).toBe(author);
-  });
-
-  it('applies advice when the author config is absent', () => {
-    expect(mergeRouterTuning(undefined, { style: 'detailed' })).toEqual({
-      style: 'detailed',
-    });
+      parseRouterDecision(
+        '{"slug":"assistant","effort":"high","creativity":"precise"}',
+        cands,
+      )?.seed,
+    ).toEqual({ effort: 'high', creativity: 'precise' });
+    // Unknown / out-of-enum values are dropped; with none valid, seed is omitted.
+    expect(
+      parseRouterDecision(
+        '{"slug":"assistant","effort":"turbo","creativity":"wild"}',
+        cands,
+      )?.seed,
+    ).toBeUndefined();
+    // A partial seed keeps only the valid field.
+    expect(
+      parseRouterDecision('{"slug":"assistant","effort":"low"}', cands)?.seed,
+    ).toEqual({ effort: 'low' });
   });
 });
 
diff --git a/services/platform/convex/agents/auto_route_helpers.ts b/services/platform/convex/agents/auto_route_helpers.ts
index 22f99ab9cd..7311f909b2 100644
Binary files a/services/platform/convex/agents/auto_route_helpers.ts and b/services/platform/convex/agents/auto_route_helpers.ts differ
diff --git a/services/platform/convex/agents/chat_turn.ts b/services/platform/convex/agents/chat_turn.ts
index d4f79e90f3..166cf634fa 100644
--- a/services/platform/convex/agents/chat_turn.ts
+++ b/services/platform/convex/agents/chat_turn.ts
@@ -28,6 +28,7 @@ import {
 import { internal } from '../_generated/api';
 import type { Id } from '../_generated/dataModel';
 import { mutation, type MutationCtx } from '../_generated/server';
+import { isDrainingNow } from '../control/drain';
 import { isActiveDocument } from '../documents/_helpers';
 import { userContextValidator } from '../lib/agent_response/validators';
 import { getUserTeamIds } from '../lib/get_user_teams';
@@ -206,6 +207,16 @@ export const chatWithAgentTurn = mutation({
       return { messageAlreadyExists: false, streamId: '' };
     }
 
+    // Deploy drain gate: a `tale deploy` recreates the convex container in
+    // place, killing every in-flight (non-durable) chat generation. While the
+    // CLI is draining, refuse NEW turns so nothing starts mid-restart — the
+    // client retries this coded error onto the restarted backend (mirrors the
+    // sandbox spawner's 503 "draining"). Prewarm bypasses (it returned above);
+    // in-flight turns keep running and the CLI waits for them.
+    if (await isDrainingNow(ctx)) {
+      throw new ConvexError({ code: 'BACKEND_DRAINING' });
+    }
+
     // Projects: validate access here (DB query) so a denial throws
     // synchronously and the client shows a PROJECT_* toast (same UX as before
     // Track B). The thread↔project persist + PROJECT_MISMATCH check stay in
diff --git a/services/platform/convex/agents/chat_turn_generate.ts b/services/platform/convex/agents/chat_turn_generate.ts
index c6c186e13c..e6f6c70ddf 100644
--- a/services/platform/convex/agents/chat_turn_generate.ts
+++ b/services/platform/convex/agents/chat_turn_generate.ts
@@ -25,6 +25,10 @@ import { saveMessage } from '@convex-dev/agent';
 import { ConvexError, v } from 'convex/values';
 
 import { AUTO_AGENT_SLUG } from '../../lib/shared/constants/agents';
+import type {
+  ResponseReasoningSeed,
+  ResponseStyleAdvice,
+} from '../../lib/shared/response-tuning';
 import { stripModelRefQualifier } from '../../lib/shared/utils/model-ref';
 import { components, internal } from '../_generated/api';
 import { internalAction, type ActionCtx } from '../_generated/server';
@@ -132,6 +136,11 @@ export const runChatTurnGeneration = internalAction({
       // 1. Auto-route (LLM classifier) — only when no agent is pinned.
       let resolvedAgentSlug = args.agentSlug;
       let autoRouteReason: AutoRouteReason | undefined;
+      // The router's per-message advice (Auto mode only) — applied to the
+      // agentConfig once it's built below. `routeStyle` shapes the prose
+      // suffix; `routeSeed` seeds the reasoning governor's prior.
+      let routeStyle: ResponseStyleAdvice | undefined;
+      let routeSeed: ResponseReasoningSeed | undefined;
       if (args.agentSlug === AUTO_AGENT_SLUG) {
         const allowedAgentSlugs = args.projectId
           ? await ctx.runQuery(
@@ -154,6 +163,8 @@ export const runChatTurnGeneration = internalAction({
         );
         resolvedAgentSlug = resolved.agentSlug;
         autoRouteReason = resolved.reason;
+        routeStyle = resolved.tuning;
+        routeSeed = resolved.seed;
 
         // Broadcast the resolved route the instant routing settles so the
         // client's thinking timeline flips "Routing…" → "Routed to X" BEFORE
@@ -197,6 +208,10 @@ export const runChatTurnGeneration = internalAction({
         modelId: args.modelId,
       });
       const agentConfig = configResult.config;
+      // Carry the Auto router's per-message advice onto the config for this turn
+      // (both unset for a pinned agent — the router only runs under Auto).
+      agentConfig.responseStyle = routeStyle;
+      agentConfig.routeSeed = routeSeed;
       // BYO external agents bypass platform model governance entirely: their
       // model is a raw provider id (or empty = the credential's default), not a
       // catalog entry subject to default-model resolution or model-access RBAC.
diff --git a/services/platform/convex/agents/config.ts b/services/platform/convex/agents/config.ts
index 2d7cfa2d74..eafe84f63f 100644
--- a/services/platform/convex/agents/config.ts
+++ b/services/platform/convex/agents/config.ts
@@ -136,7 +136,6 @@ export function toSerializableConfig(
     structuredResponsesEnabled: config.structuredResponsesEnabled ?? false,
     timeoutMs: config.timeoutMs,
     outputReserve: config.outputReserve,
-    responseTuning: config.responseTuning,
     routing: config.routing,
     fallbackModels:
       config.supportedModels.length > 1
diff --git a/services/platform/convex/agents/external_agent/continue_external_agent_turn.ts b/services/platform/convex/agents/external_agent/continue_external_agent_turn.ts
index 4821c2e3db..86683b3a62 100644
--- a/services/platform/convex/agents/external_agent/continue_external_agent_turn.ts
+++ b/services/platform/convex/agents/external_agent/continue_external_agent_turn.ts
@@ -66,6 +66,10 @@ export const continueExternalAgentTurn = internalAction({
     interactionMode: v.optional(
       v.union(v.literal('interactive'), v.literal('autonomous')),
     ),
+    /** Blue-green colour the session lives on — routes the re-attach to
+     * `sandbox-<color>` so a resume reaches a session lingering on the old
+     * colour after a deploy flip. Optional: single-colour / pre-blue-green. */
+    spawnerColor: v.optional(v.string()),
   },
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -162,6 +166,9 @@ export const continueExternalAgentTurn = internalAction({
         ...(args.interactionMode !== undefined && {
           interactionMode: args.interactionMode,
         }),
+        ...(args.spawnerColor !== undefined && {
+          spawnerColor: args.spawnerColor,
+        }),
         resumeFrom,
         onTimeline: async (content) => {
           await patchStreamingMessage(ctx, args.assistantMessageId, content);
diff --git a/services/platform/convex/agents/external_agent/recover_external_agent_turns.ts b/services/platform/convex/agents/external_agent/recover_external_agent_turns.ts
index 2032fd7413..b3214ef40e 100644
--- a/services/platform/convex/agents/external_agent/recover_external_agent_turns.ts
+++ b/services/platform/convex/agents/external_agent/recover_external_agent_turns.ts
@@ -61,7 +61,11 @@ export const recoverStuckExternalAgentTurns = internalAction({
         //    finalize on a hiccup (that was the old bug that killed live agents).
         let liveness;
         try {
-          liveness = await sessionExecStatus(op.sessionId, op.execId);
+          liveness = await sessionExecStatus(
+            op.sessionId,
+            op.execId,
+            op.spawnerColor,
+          );
         } catch (probeErr) {
           console.warn(
             `[recoverStuckExternalAgentTurns] exec probe failed for ${op.execId} (leaving for next sweep):`,
@@ -115,7 +119,11 @@ export const recoverStuckExternalAgentTurns = internalAction({
                   },
                 )
                 .catch((e) => console.warn('[recover] supersede op:', e));
-              await sessionCancelExec(op.sessionId, op.execId).catch((e) =>
+              await sessionCancelExec(
+                op.sessionId,
+                op.execId,
+                op.spawnerColor,
+              ).catch((e) =>
                 console.warn('[recover] supersede cancel exec:', e),
               );
               finalized += 1;
@@ -158,6 +166,9 @@ export const recoverStuckExternalAgentTurns = internalAction({
               ...(op.agentSlug !== undefined && { agentSlug: op.agentSlug }),
               ...(op.userId !== undefined && { userId: op.userId }),
               ...(op.streamId !== undefined && { streamId: op.streamId }),
+              ...(op.spawnerColor !== undefined && {
+                spawnerColor: op.spawnerColor,
+              }),
             },
           );
           resumed += 1;
diff --git a/services/platform/convex/agents/external_agent/run_external_agent.ts b/services/platform/convex/agents/external_agent/run_external_agent.ts
index 1c254e91f0..315b1e379f 100644
--- a/services/platform/convex/agents/external_agent/run_external_agent.ts
+++ b/services/platform/convex/agents/external_agent/run_external_agent.ts
@@ -207,6 +207,11 @@ export const runExternalAgentTurn = internalAction({
     // Hoisted so the catch can finalize side-effects (it's assigned once the
     // sandbox is resolved, before the message + op row exist).
     let sessionId: string | null = null;
+    // Blue-green colour the live session is on (from the create response or the
+    // existing row). Threaded into run_agent so its session ops route to
+    // `sandbox-<color>` — keeping a turn reachable if a deploy flip lingers the
+    // old colour mid-turn. `null` ⇒ single-colour / unknown → bare alias.
+    let liveSpawnerColor: string | null = null;
     // Mirror of the most recent content patched into the streaming message, so
     // the catch can mark it failed while preserving the partial tool timeline.
     let lastContent: AgentAssistantContent = '';
@@ -247,18 +252,24 @@ export const runExternalAgentTurn = internalAction({
       if (existing) {
         sessionId = existing.sessionId;
         sessionCreatedAt = existing.createdAt;
-        const alive = await sessionIsAlive(existing.sessionId);
+        // Default to the row's recorded colour; a re-create below may move it.
+        liveSpawnerColor = existing.spawnerColor ?? null;
+        const alive = await sessionIsAlive(
+          existing.sessionId,
+          existing.spawnerColor,
+        );
         if (!alive) {
           console.warn(
             '[runExternalAgentTurn] resuming stopped session in place:',
             sessionId,
           );
           try {
-            await sessionCreate({
+            const created = await sessionCreate({
               sessionId,
               organizationId: args.organizationId,
               profile: 'agent',
             });
+            liveSpawnerColor = created.spawnerColor;
           } catch (createErr) {
             // 409: the container is actually still live (race with the reaper /
             // a re-adopted session). That's a successful resume, NOT an orphan
@@ -309,11 +320,12 @@ export const runExternalAgentTurn = internalAction({
         );
         try {
           try {
-            await sessionCreate({
+            const created = await sessionCreate({
               sessionId,
               organizationId: args.organizationId,
               profile: 'agent',
             });
+            liveSpawnerColor = created.spawnerColor;
           } catch (createErr) {
             // 409 duplicate: the spawner still owns a session under this
             // deterministic id that the platform no longer tracks (e.g. a
@@ -325,11 +337,12 @@ export const runExternalAgentTurn = internalAction({
               `[runExternalAgentTurn] reaping orphan spawner session ${sessionId} (create 409)`,
             );
             await sessionDestroy(sessionId);
-            await sessionCreate({
+            const recreated = await sessionCreate({
               sessionId,
               organizationId: args.organizationId,
               profile: 'agent',
             });
+            liveSpawnerColor = recreated.spawnerColor;
           }
         } catch (createErr) {
           await ctx.runMutation(
@@ -344,6 +357,20 @@ export const runExternalAgentTurn = internalAction({
         );
       }
 
+      // Persist the colour the session landed on so a recovery/continuation
+      // after a deploy flip routes session ops to the lingering colour. No-ops
+      // on a null colour (single-colour mode) and only when it changed.
+      if (sessionId !== null && liveSpawnerColor !== null) {
+        await ctx.runMutation(
+          internal.sandbox.session_mutations.setSessionSpawnerColor,
+          {
+            organizationId: args.organizationId,
+            sessionId,
+            spawnerColor: liveSpawnerColor,
+          },
+        );
+      }
+
       // EVERY turn (created OR reused): ensure the org's per-org upstream key +
       // provider config are in the gateway BEFORE the mint below binds the VK to
       // that key. provisionProviders is idempotent and memoized (steady-state =
@@ -659,6 +686,7 @@ export const runExternalAgentTurn = internalAction({
           sessionId: liveSessionId,
           threadId: args.threadId,
           ...(args.streamId !== undefined && { streamId: args.streamId }),
+          ...(liveSpawnerColor !== null && { spawnerColor: liveSpawnerColor }),
           execId: id,
           agentSlug: args.agentKind,
           prompt: args.rawPrompt,
diff --git a/services/platform/convex/agents/file_utils.ts b/services/platform/convex/agents/file_utils.ts
index 2e56c9d075..0ec57642a8 100644
--- a/services/platform/convex/agents/file_utils.ts
+++ b/services/platform/convex/agents/file_utils.ts
@@ -15,7 +15,6 @@ import {
   agentJsonSchema,
   type AgentMetadata,
   type AgentRoutingConfig,
-  type ResponseTuningConfig,
 } from '../../lib/shared/schemas/agents';
 import { canonicalizeAgentConfig } from '../../lib/shared/utils/canonicalize-config';
 import { resolveAppDir } from '../apps/file_utils';
@@ -119,9 +118,6 @@ export interface AgentJsonConfig {
     tooltip?: string;
     order?: number;
   };
-  /** Per-agent response tuning (effort/creativity/style + bounds). Mirrors
-   *  `responseTuningSchema` in `lib/shared/schemas/agents.ts`. */
-  responseTuning?: ResponseTuningConfig;
   /** Per-agent routing / cascade behaviour. Mirrors `agentRoutingSchema`. */
   routing?: AgentRoutingConfig;
   roleRestriction?: 'admin_developer';
diff --git a/services/platform/convex/agents/guardrails/internal_mutations.ts b/services/platform/convex/agents/guardrails/internal_mutations.ts
index 815caa37cd..b987253033 100644
--- a/services/platform/convex/agents/guardrails/internal_mutations.ts
+++ b/services/platform/convex/agents/guardrails/internal_mutations.ts
@@ -99,6 +99,7 @@ export const recordBudgetWarnCrossing = internalMutation({
         spentCents: args.spentCents,
         monthlyCents: args.monthlyCents,
       },
+      link: { kind: 'agent', agentSlug: args.agentSlug },
     });
     return null;
   },
@@ -134,6 +135,7 @@ export const recordBudgetPause = internalMutation({
         spentCents: args.spentCents,
         monthlyCents: args.monthlyCents,
       },
+      link: { kind: 'agent', agentSlug: args.agentSlug },
     });
     await createAuditLog(ctx, {
       organizationId: args.organizationId,
@@ -253,6 +255,7 @@ export const tripTaskCircuitBreaker = internalMutation({
         windowRuns: args.windowRuns,
         windowHours: args.windowHours,
       },
+      link: { kind: 'agent', agentSlug: args.agentSlug },
     });
     await createAuditLog(ctx, {
       organizationId: args.organizationId,
diff --git a/services/platform/convex/agents/internal_mutations.ts b/services/platform/convex/agents/internal_mutations.ts
index f01f39cb6f..b061f6ceee 100644
--- a/services/platform/convex/agents/internal_mutations.ts
+++ b/services/platform/convex/agents/internal_mutations.ts
@@ -3,6 +3,7 @@ import { v } from 'convex/values';
 import { internalMutation } from '../_generated/server';
 import {
   knowledgeFileRagStatusValidator,
+  routeSeedValidator,
   routeTuningValidator,
 } from './schema';
 
@@ -21,6 +22,7 @@ export const upsertAutoRouteCache = internalMutation({
     nowMs: v.number(),
     language: v.optional(v.string()),
     tuning: v.optional(routeTuningValidator),
+    seed: v.optional(routeSeedValidator),
     capabilities: v.optional(v.array(v.string())),
   },
   returns: v.null(),
@@ -42,6 +44,7 @@ export const upsertAutoRouteCache = internalMutation({
         // also CLEAR a hint it no longer emits — `undefined` overwrites.
         language: args.language,
         tuning: args.tuning,
+        seed: args.seed,
         capabilities: args.capabilities,
         hits: existing.hits + 1,
         lastUsedAt: args.nowMs,
@@ -55,6 +58,7 @@ export const upsertAutoRouteCache = internalMutation({
         source: args.source,
         language: args.language,
         tuning: args.tuning,
+        seed: args.seed,
         capabilities: args.capabilities,
         hits: 1,
         createdAt: args.nowMs,
@@ -114,6 +118,7 @@ export const recordRouteOverride = internalMutation({
         // manual switch to a different agent invalidates them.
         language: undefined,
         tuning: undefined,
+        seed: undefined,
         capabilities: undefined,
         lastUsedAt: args.nowMs,
       });
diff --git a/services/platform/convex/agents/internal_queries.ts b/services/platform/convex/agents/internal_queries.ts
index ec5611bd7c..7fccc104d7 100644
--- a/services/platform/convex/agents/internal_queries.ts
+++ b/services/platform/convex/agents/internal_queries.ts
@@ -8,7 +8,7 @@
 import { v } from 'convex/values';
 
 import { internalQuery } from '../_generated/server';
-import { routeTuningValidator } from './schema';
+import { routeSeedValidator, routeTuningValidator } from './schema';
 
 export const getBindingByAgent = internalQuery({
   args: {
@@ -77,6 +77,7 @@ export const getAutoRouteCache = internalQuery({
       agentSlug: v.string(),
       language: v.optional(v.string()),
       tuning: v.optional(routeTuningValidator),
+      seed: v.optional(routeSeedValidator),
       capabilities: v.optional(v.array(v.string())),
     }),
     v.null(),
@@ -97,6 +98,7 @@ export const getAutoRouteCache = internalQuery({
       agentSlug: row.agentSlug,
       language: row.language,
       tuning: row.tuning,
+      seed: row.seed,
       capabilities: row.capabilities,
     };
   },
diff --git a/services/platform/convex/agents/knowledge_file_rag_info.test.ts b/services/platform/convex/agents/knowledge_file_rag_info.test.ts
index 38eccc7924..f9639a844d 100644
--- a/services/platform/convex/agents/knowledge_file_rag_info.test.ts
+++ b/services/platform/convex/agents/knowledge_file_rag_info.test.ts
@@ -5,13 +5,15 @@ vi.mock('../_generated/server', () => ({
 }));
 
 vi.mock('./schema', async () => {
-  // `routeTuningValidator` is wrapped in `v.optional(...)` at import time, so it
-  // must be a real validator — a string placeholder throws. `knowledgeFile...`
-  // is used directly as a field value, so a stub string is fine there.
+  // `routeTuningValidator` / `routeSeedValidator` are wrapped in `v.optional(...)`
+  // at import time, so they must be real validators — a string placeholder
+  // throws. `knowledgeFile...` is used directly as a field value, so a stub
+  // string is fine there.
   const { v } = await import('convex/values');
   return {
     knowledgeFileRagStatusValidator: 'mock-validator',
     routeTuningValidator: v.object({}),
+    routeSeedValidator: v.object({}),
   };
 });
 
diff --git a/services/platform/convex/agents/recover_stuck_chat_turns.ts b/services/platform/convex/agents/recover_stuck_chat_turns.ts
new file mode 100644
index 0000000000..f4daa4178c
--- /dev/null
+++ b/services/platform/convex/agents/recover_stuck_chat_turns.ts
@@ -0,0 +1,164 @@
+/**
+ * Recovery watchdog for plain chat turns whose generation action was killed
+ * without finalizing — the backstop to the deploy drain (`control/drain.ts`).
+ *
+ * The deploy drain waits for in-flight generations before recreating convex,
+ * but a turn that outlasts the drain budget (or a crash / the 30-min action
+ * ceiling) is still hard-killed mid-stream. A plain chat turn has no
+ * out-of-process source of truth (unlike a sandbox exec), so there is nothing
+ * to resume — re-calling the LLM would lose the partial stream and double-bill.
+ * The honest recovery is to FINALIZE: keep whatever streamed as a success
+ * bubble, else mark the turn failed with a clear, retryable "backend restarted"
+ * envelope, and clear the stuck `generating` lock so the UI unblocks.
+ *
+ * Plain chat turns have no recovery cron today (only external-agent turns and
+ * sandbox executions do); this fills that gap. External-agent turns are handled
+ * by their own 2-min restorative sweep well before this 35-min threshold, so
+ * this watchdog effectively only finalizes plain turns and any straggler the
+ * other sweeps missed.
+ */
+
+import {
+  abortStream,
+  listMessages,
+  listStreams,
+  saveMessage,
+} from '@convex-dev/agent';
+import { v } from 'convex/values';
+
+import {
+  buildHumanErrorSentence,
+  encodeChatError,
+} from '../../lib/shared/chat-errors';
+import { components } from '../_generated/api';
+import { internalMutation } from '../_generated/server';
+import { GENERATION_STALE_THRESHOLD_MS } from '../threads/generation_liveness';
+
+/**
+ * Cap finalizations per run so a pathological backlog can't blow the mutation's
+ * read/time budget; the next 5-min tick continues. (Iterating the `generating`
+ * index itself is cheap — it's the small set of currently-active threads.)
+ */
+const RECOVERY_SWEEP_LIMIT = 50;
+
+/** A failed turn cut by a backend restart: a clear, localized, retryable bubble. */
+function backendRestartError(): string {
+  return encodeChatError({
+    code: 'provider_unreachable',
+    raw: 'The backend restarted during generation (deploy or crash). Please send the message again.',
+  });
+}
+
+export const recoverStuckChatTurns = internalMutation({
+  args: {},
+  returns: v.object({ finalized: v.number() }),
+  handler: async (ctx) => {
+    const staleBefore = Date.now() - GENERATION_STALE_THRESHOLD_MS;
+    let finalized = 0;
+
+    for await (const meta of ctx.db
+      .query('threadMetadata')
+      .withIndex('by_generationStatus', (q) =>
+        q.eq('generationStatus', 'generating'),
+      )) {
+      if (finalized >= RECOVERY_SWEEP_LIMIT) break;
+
+      const lastAlive = Math.max(
+        meta.generationStartTime ?? 0,
+        meta.generationHeartbeatAt ?? 0,
+      );
+      // Legacy rows with no liveness anchor are treated as "not stale" (matches
+      // isGenerationFresh) so the UI never unblocks them prematurely; skip.
+      if (lastAlive === 0 || lastAlive > staleBefore) continue;
+
+      try {
+        // Finalize-once guard: re-read and confirm still generating on the SAME
+        // stream before mutating, so a turn that recovered between the scan and
+        // now is never clobbered (mirrors clearGenerationStatus).
+        const fresh = await ctx.db.get(meta._id);
+        if (
+          !fresh ||
+          fresh.generationStatus !== 'generating' ||
+          fresh.streamId !== meta.streamId
+        ) {
+          continue;
+        }
+
+        // Abort any lingering SDK streams for this thread.
+        const streams = await listStreams(ctx, components.agent, {
+          threadId: fresh.threadId,
+          includeStatuses: ['streaming'],
+        });
+        for (const stream of streams) {
+          await abortStream(ctx, components.agent, {
+            streamId: stream.streamId,
+            reason: 'backend-restart',
+          });
+        }
+
+        // Finalize the newest assistant message: preserve streamed text as a
+        // success bubble (mirrors cancelGeneration), else surface the error.
+        const msgs = await listMessages(ctx, components.agent, {
+          threadId: fresh.threadId,
+          paginationOpts: { numItems: 5, cursor: null },
+          excludeToolMessages: true,
+        });
+        const latestAssistant = msgs.page.find(
+          (m) => m.message?.role === 'assistant',
+        );
+
+        if (latestAssistant && latestAssistant.status !== 'success') {
+          if (latestAssistant.text?.trim()) {
+            await ctx.runMutation(components.agent.messages.updateMessage, {
+              messageId: latestAssistant._id,
+              patch: { status: 'success' },
+            });
+          } else {
+            await ctx.runMutation(components.agent.messages.updateMessage, {
+              messageId: latestAssistant._id,
+              patch: {
+                status: 'failed',
+                error: backendRestartError(),
+                message: {
+                  role: 'assistant' as const,
+                  content: buildHumanErrorSentence('provider_unreachable'),
+                },
+              },
+            });
+          }
+        } else if (!latestAssistant) {
+          // No assistant message was saved before the kill — surface one so the
+          // user sees why the turn ended rather than a silent unblock.
+          await saveMessage(ctx, components.agent, {
+            threadId: fresh.threadId,
+            message: {
+              role: 'assistant',
+              content: buildHumanErrorSentence('provider_unreachable'),
+            },
+            metadata: { status: 'failed', error: backendRestartError() },
+          });
+        }
+
+        await ctx.db.patch(fresh._id, {
+          generationStatus: 'idle' as const,
+          streamId: undefined,
+          updatedAt: Date.now(),
+          lastReplyAt: Date.now(),
+        });
+        finalized += 1;
+      } catch (err) {
+        console.warn(
+          `[recoverStuckChatTurns] finalize failed for thread ${meta.threadId}:`,
+          err,
+        );
+      }
+    }
+
+    if (finalized > 0) {
+      console.warn(
+        `[recoverStuckChatTurns] finalized ${finalized} stuck chat turn(s)`,
+      );
+    }
+    return { finalized };
+  },
+});
diff --git a/services/platform/convex/agents/schema.ts b/services/platform/convex/agents/schema.ts
index 788f6ec919..6698e950c6 100644
--- a/services/platform/convex/agents/schema.ts
+++ b/services/platform/convex/agents/schema.ts
@@ -61,6 +61,23 @@ export const routeTuningValidator = v.object({
   ),
 });
 
+/**
+ * Coarse per-message reasoning SEED the router may advise — distinct from the
+ * prose-level {@link routeTuningValidator}. Mirrors `RouterReasoningSeed` in
+ * `auto_route_helpers.ts`. Fed to the adaptive reasoning governor as a PRIOR
+ * (blended into the difficulty score), never a hard override: the online
+ * controller still refines effort/temperature from observed usage, so a wrong
+ * hint self-corrects within a few turns.
+ */
+export const routeSeedValidator = v.object({
+  effort: v.optional(
+    v.union(v.literal('low'), v.literal('medium'), v.literal('high')),
+  ),
+  creativity: v.optional(
+    v.union(v.literal('precise'), v.literal('balanced'), v.literal('creative')),
+  ),
+});
+
 /**
  * "Auto" routing decision cache. Skips the router classifier when the exact
  * same normalized message has already been routed for the same candidate set.
@@ -82,6 +99,8 @@ export const autoRouteCacheTable = defineTable({
   language: v.optional(v.string()),
   /** Advisory qualitative response shaping. */
   tuning: v.optional(routeTuningValidator),
+  /** Advisory reasoning seed (governor prior). */
+  seed: v.optional(routeSeedValidator),
   /** Capability slugs the router suggested enabling. */
   capabilities: v.optional(v.array(v.string())),
   hits: v.number(),
diff --git a/services/platform/convex/audit_logs/integrity_check.ts b/services/platform/convex/audit_logs/integrity_check.ts
index c3c3cebe80..441b25d99f 100644
--- a/services/platform/convex/audit_logs/integrity_check.ts
+++ b/services/platform/convex/audit_logs/integrity_check.ts
@@ -135,6 +135,7 @@ export const notifyIntegrityFailure = internalMutation({
         ? 'auditIntegrityUnverifiableDetails'
         : 'auditIntegrityFailedDetails',
       params: { reason: args.reason },
+      link: { kind: 'audit-logs' },
     });
     return null;
   },
diff --git a/services/platform/convex/collab/notify.ts b/services/platform/convex/collab/notify.ts
index d41c64b81b..07640c2b86 100644
--- a/services/platform/convex/collab/notify.ts
+++ b/services/platform/convex/collab/notify.ts
@@ -202,6 +202,7 @@ export async function notifyTaskStatusChanged(
       bodyKey: actorName ? 'taskStatusChangedByBody' : 'taskStatusChangedBody',
       params: {
         title: args.task.title,
+        projectId: String(args.task.projectId),
         from: args.fromStatus,
         to: args.toStatus,
         ...(actorName ? { actor: actorName } : {}),
@@ -241,9 +242,11 @@ export async function notifyTaskAssigned(
     type: 'task_assigned',
     titleKey: 'taskAssigned',
     bodyKey: actorName ? 'taskAssignedByBody' : 'taskAssignedBody',
-    params: actorName
-      ? { title: args.task.title, actor: actorName }
-      : { title: args.task.title },
+    params: {
+      title: args.task.title,
+      projectId: String(args.task.projectId),
+      ...(actorName ? { actor: actorName } : {}),
+    },
     resourceType: 'task',
     resourceId: String(args.task._id),
     taskId: args.task._id,
@@ -283,9 +286,11 @@ export async function notifyTaskMentions(
       type: 'mention',
       titleKey: 'mention',
       bodyKey: actorName ? 'mentionByBody' : 'mentionBody',
-      params: actorName
-        ? { title: args.task.title, actor: actorName }
-        : { title: args.task.title },
+      params: {
+        title: args.task.title,
+        projectId: String(args.task.projectId),
+        ...(actorName ? { actor: actorName } : {}),
+      },
       resourceType: 'task',
       resourceId: String(args.task._id),
       taskId: args.task._id,
@@ -340,9 +345,11 @@ export async function notifyTaskComment(
       type: 'mention',
       titleKey: 'mention',
       bodyKey: actorName ? 'mentionByBody' : 'mentionBody',
-      params: actorName
-        ? { title: args.task.title, actor: actorName }
-        : { title: args.task.title },
+      params: {
+        title: args.task.title,
+        projectId: String(args.task.projectId),
+        ...(actorName ? { actor: actorName } : {}),
+      },
       resourceType: 'comment',
       resourceId: args.commentId,
       taskId: args.task._id,
@@ -365,9 +372,11 @@ export async function notifyTaskComment(
       type: 'task_commented',
       titleKey: 'taskCommented',
       bodyKey: actorName ? 'taskCommentedByBody' : 'taskCommentedBody',
-      params: actorName
-        ? { title: args.task.title, actor: actorName }
-        : { title: args.task.title },
+      params: {
+        title: args.task.title,
+        projectId: String(args.task.projectId),
+        ...(actorName ? { actor: actorName } : {}),
+      },
       resourceType: 'comment',
       resourceId: args.commentId,
       taskId: args.task._id,
diff --git a/services/platform/convex/control/drain.test.ts b/services/platform/convex/control/drain.test.ts
new file mode 100644
index 0000000000..3143818a90
--- /dev/null
+++ b/services/platform/convex/control/drain.test.ts
@@ -0,0 +1,119 @@
+import { convexTest } from 'convex-test';
+import { defineSchema, defineTable } from 'convex/server';
+import { v } from 'convex/values';
+import { describe, expect, it } from 'vitest';
+
+import { buildModules } from '../migrations/framework/test_helpers';
+import { countActiveGenerations, isDrainingNow } from './drain';
+
+// convex-test locates the project root via a module path containing
+// `_generated`; the helpers run inside `t.run` (no function dispatch) so the
+// `_generated` glob alone is enough — no need to load the whole convex tree.
+const modules = buildModules(
+  import.meta.glob('../_generated/**/*.*s'),
+  'control',
+);
+
+// Minimal fixture mirroring the two tables the drain helpers read. `as never`
+// bridges the fixture ctx to the helpers' generated ctx type (same pattern the
+// migration tests use); the helpers only touch `ctx.db.query(...).withIndex`.
+const fixtureSchema = defineSchema({
+  backendControl: defineTable({
+    key: v.literal('singleton'),
+    draining: v.boolean(),
+    drainStartedAt: v.optional(v.number()),
+    drainExpiresAt: v.optional(v.number()),
+  }).index('by_key', ['key']),
+  threadMetadata: defineTable({
+    generationStatus: v.optional(
+      v.union(v.literal('generating'), v.literal('idle')),
+    ),
+    generationStartTime: v.optional(v.number()),
+    generationHeartbeatAt: v.optional(v.number()),
+  }).index('by_generationStatus', ['generationStatus']),
+});
+
+describe('isDrainingNow', () => {
+  it('returns false when no control row exists', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      expect(await isDrainingNow(ctx as never)).toBe(false);
+    });
+  });
+
+  it('returns true while draining and unexpired', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      await ctx.db.insert('backendControl', {
+        key: 'singleton',
+        draining: true,
+        drainStartedAt: Date.now(),
+        drainExpiresAt: Date.now() + 60_000,
+      });
+      expect(await isDrainingNow(ctx as never)).toBe(true);
+    });
+  });
+
+  it('treats an expired drain flag as not draining (crashed-deploy backstop)', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      await ctx.db.insert('backendControl', {
+        key: 'singleton',
+        draining: true,
+        drainStartedAt: Date.now() - 120_000,
+        drainExpiresAt: Date.now() - 1_000,
+      });
+      expect(await isDrainingNow(ctx as never)).toBe(false);
+    });
+  });
+
+  it('returns false when the flag is explicitly cleared', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      await ctx.db.insert('backendControl', {
+        key: 'singleton',
+        draining: false,
+      });
+      expect(await isDrainingNow(ctx as never)).toBe(false);
+    });
+  });
+});
+
+describe('countActiveGenerations', () => {
+  it('counts only fresh generating threads', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      // Fresh generating — counts.
+      await ctx.db.insert('threadMetadata', {
+        generationStatus: 'generating',
+        generationStartTime: Date.now(),
+      });
+      // Stale generating (last sign of life > 35min ago) — does NOT count.
+      await ctx.db.insert('threadMetadata', {
+        generationStatus: 'generating',
+        generationStartTime: Date.now() - (35 * 60 * 1000 + 60_000),
+      });
+      // Idle — does NOT count.
+      await ctx.db.insert('threadMetadata', {
+        generationStatus: 'idle',
+        generationStartTime: Date.now(),
+      });
+      // Fresh via heartbeat even though startTime is old — counts.
+      await ctx.db.insert('threadMetadata', {
+        generationStatus: 'generating',
+        generationStartTime: Date.now() - 40 * 60 * 1000,
+        generationHeartbeatAt: Date.now() - 10_000,
+      });
+
+      expect(await countActiveGenerations(ctx as never)).toBe(2);
+    });
+  });
+
+  it('returns 0 when nothing is generating', async () => {
+    const t = convexTest(fixtureSchema, modules);
+    await t.run(async (ctx) => {
+      await ctx.db.insert('threadMetadata', { generationStatus: 'idle' });
+      expect(await countActiveGenerations(ctx as never)).toBe(0);
+    });
+  });
+});
diff --git a/services/platform/convex/control/drain.ts b/services/platform/convex/control/drain.ts
new file mode 100644
index 0000000000..7257ee5d6f
--- /dev/null
+++ b/services/platform/convex/control/drain.ts
@@ -0,0 +1,117 @@
+/**
+ * Deploy DRAIN control plane (V8). Mirrors the sandbox spawner's
+ * `/v1/drain` + `/v1/drain-status` pattern, but for the Convex backend.
+ *
+ * `tale deploy` recreates the convex container in-place on a version change,
+ * which restarts the backend and kills every in-flight action — including
+ * non-durable chat generation. Before recreating, the CLI calls `beginDrain`
+ * (the new-turn gate in `agents/chat_turn.ts` then refuses new turns so the
+ * client retries onto the restarted backend) and polls `drainStatus` until
+ * `inFlight === 0`, then recreates and calls `endDrain`.
+ *
+ * Reachable from the CLI via `bunx convex run` with the admin key (no user
+ * identity), exactly like the migration entrypoints and `provisioning:*` — so
+ * these are raw `internalMutation`/`internalQuery`, not the RLS wrappers.
+ */
+
+import { v } from 'convex/values';
+
+import { internalMutation, internalQuery } from '../_generated/server';
+import type { MutationCtx, QueryCtx } from '../_generated/server';
+import { isGenerationFresh } from '../threads/generation_liveness';
+
+/**
+ * Hard expiry for a drain flag. Set well above the CLI's drain budget
+ * (`DRAIN_TIMEOUT_MS` in `tools/cli/.../drain-convex.ts`, 3 min) so it never
+ * fires during a healthy deploy, but bounds the blast radius of a deploy that
+ * dies after `beginDrain` and never reaches `endDrain` — chats self-heal in 15
+ * min instead of being refused forever.
+ */
+const DRAIN_MAX_MS = 15 * 60 * 1000;
+
+const SINGLETON = 'singleton' as const;
+
+/** Whether new chat turns should currently be refused (drain active + unexpired). */
+export async function isDrainingNow(
+  ctx: QueryCtx | MutationCtx,
+): Promise<boolean> {
+  const row = await ctx.db
+    .query('backendControl')
+    .withIndex('by_key', (q) => q.eq('key', SINGLETON))
+    .first();
+  if (!row || !row.draining) return false;
+  // Unexpired drain only — a stale flag (crashed deploy) reads as "not draining".
+  return row.drainExpiresAt === undefined || Date.now() < row.drainExpiresAt;
+}
+
+/**
+ * Count threads with a genuinely in-flight generation: `generating` AND still
+ * fresh (a stale lock means the action is already dead — not something to wait
+ * on). Index-scoped to the small `generating` set; never a full-table scan.
+ */
+export async function countActiveGenerations(
+  ctx: QueryCtx | MutationCtx,
+): Promise<number> {
+  let count = 0;
+  for await (const meta of ctx.db
+    .query('threadMetadata')
+    .withIndex('by_generationStatus', (q) =>
+      q.eq('generationStatus', 'generating'),
+    )) {
+    if (isGenerationFresh(meta)) count += 1;
+  }
+  return count;
+}
+
+async function getSingleton(ctx: MutationCtx) {
+  return ctx.db
+    .query('backendControl')
+    .withIndex('by_key', (q) => q.eq('key', SINGLETON))
+    .first();
+}
+
+export const beginDrain = internalMutation({
+  args: {},
+  returns: v.object({ inFlight: v.number() }),
+  handler: async (ctx) => {
+    const now = Date.now();
+    const patch = {
+      key: SINGLETON,
+      draining: true,
+      drainStartedAt: now,
+      drainExpiresAt: now + DRAIN_MAX_MS,
+    } as const;
+    const row = await getSingleton(ctx);
+    if (row) {
+      await ctx.db.patch(row._id, patch);
+    } else {
+      await ctx.db.insert('backendControl', patch);
+    }
+    return { inFlight: await countActiveGenerations(ctx) };
+  },
+});
+
+export const endDrain = internalMutation({
+  args: {},
+  returns: v.null(),
+  handler: async (ctx) => {
+    const row = await getSingleton(ctx);
+    if (row) {
+      await ctx.db.patch(row._id, {
+        draining: false,
+        drainStartedAt: undefined,
+        drainExpiresAt: undefined,
+      });
+    }
+    return null;
+  },
+});
+
+export const drainStatus = internalQuery({
+  args: {},
+  returns: v.object({ draining: v.boolean(), inFlight: v.number() }),
+  handler: async (ctx) => ({
+    draining: await isDrainingNow(ctx),
+    inFlight: await countActiveGenerations(ctx),
+  }),
+});
diff --git a/services/platform/convex/control/schema.ts b/services/platform/convex/control/schema.ts
new file mode 100644
index 0000000000..bfee062c69
--- /dev/null
+++ b/services/platform/convex/control/schema.ts
@@ -0,0 +1,34 @@
+import { defineTable } from 'convex/server';
+import { v } from 'convex/values';
+
+/**
+ * Backend-wide control flags, keyed by a single `'singleton'` row.
+ *
+ * Today it carries the deploy DRAIN flag: before `tale deploy` recreates the
+ * convex container in-place (which restarts the backend process and kills every
+ * in-flight action, including non-durable chat generation), the CLI sets
+ * `draining: true` so new chat turns are refused (the client retries) while
+ * in-flight generations finish. The CLI polls the in-flight count, then
+ * recreates and clears the flag once the backend is healthy again.
+ *
+ * Why a DB row and not a module variable or a Convex env var:
+ *  - A module variable lives in the very process being restarted — it can't be
+ *    set by the CLI and survive.
+ *  - A Convex env var change forces a function re-push/restart — the wrong tool
+ *    for a transient runtime flag.
+ *  - The `convex-data` volume persists this row across the recreate, so the
+ *    CLI's `endDrain` after the restart is what clears it (with `drainExpiresAt`
+ *    as the self-healing backstop if a deploy dies mid-flight).
+ */
+export const backendControlTable = defineTable({
+  key: v.literal('singleton'),
+  draining: v.boolean(),
+  /** When the current drain began (telemetry / TTL anchor). */
+  drainStartedAt: v.optional(v.number()),
+  /**
+   * Hard expiry: `isDrainingNow` treats the flag as off past this instant so a
+   * crashed deploy can never strand the backend refusing chats forever. Set
+   * well above the CLI's drain budget so it never fires during a healthy deploy.
+   */
+  drainExpiresAt: v.optional(v.number()),
+}).index('by_key', ['key']);
diff --git a/services/platform/convex/crons.ts b/services/platform/convex/crons.ts
index 90f2de320f..ec12d0ad9a 100644
--- a/services/platform/convex/crons.ts
+++ b/services/platform/convex/crons.ts
@@ -181,6 +181,20 @@ cron(
   {},
 );
 
+// Plain chat-turn recovery — the deploy-drain backstop. A turn killed mid-
+// generation (drain budget exceeded, crash, or the 30-min action ceiling) with
+// no out-of-process source of truth to resume is finalized here: keep streamed
+// text as success, else mark it failed with a retryable "backend restarted"
+// bubble, and clear the stuck `generating` lock. Own cron entry (a throw must
+// not disable a sibling watchdog). External-agent turns have their own 2-min
+// restorative sweep above; this only finalizes plain turns + any straggler.
+cron(
+  'recover stuck chat turns (every 5 min)',
+  '*/5 * * * *',
+  internal.agents.recover_stuck_chat_turns.recoverStuckChatTurns,
+  {},
+);
+
 // GDPR erasure watchdog (round-2 V5 P0-14) - the same shape as the
 // transcription watchdog above. Convex actions hard-stop at 30 min;
 // `gdprErasureRequests` rows whose subject has too many rows / RAG
diff --git a/services/platform/convex/feedback/queries.ts b/services/platform/convex/feedback/queries.ts
index 87a65b80ae..8a52e6b362 100644
--- a/services/platform/convex/feedback/queries.ts
+++ b/services/platform/convex/feedback/queries.ts
@@ -69,6 +69,9 @@ export const getMessageFeedback = query({
 
 export interface FeedbackStatsResult extends FeedbackStats {
   hasAnyFeedback: boolean;
+  /** Prior equal-length window sentiment counts — drives the card deltas.
+   *  Absent for the all-time view (no comparable prior window). */
+  previous?: { positive: number; negative: number; total: number };
 }
 
 export const getFeedbackStats = query({
@@ -94,6 +97,13 @@ export const getFeedbackStats = query({
 
     const now = Date.now();
     const cutoffMs = periodCutoffMs(args.periodDays, now);
+    // Prior equal-length window for period-over-period deltas. Day-aligned like
+    // `cutoffMs`. Absent for the all-time view (no comparable prior window).
+    const prevCutoffMs =
+      cutoffMs !== null && args.periodDays !== undefined
+        ? cutoffMs - args.periodDays * DAY_MS
+        : null;
+    const scanCutoffMs = prevCutoffMs ?? cutoffMs;
 
     // hasAnyFeedback is a single org-scoped existence probe, used by the UI
     // to distinguish "org has never collected feedback" from "no feedback
@@ -111,16 +121,23 @@ export const getFeedbackStats = query({
       .query('messageFeedback')
       .withIndex('by_org_createdAt', (q) => {
         const eq = q.eq('organizationId', args.organizationId);
-        return cutoffMs !== null ? eq.gte('createdAt', cutoffMs) : eq;
+        // Widen to the prior window's start when computing deltas.
+        return scanCutoffMs !== null ? eq.gte('createdAt', scanCutoffMs) : eq;
       })
       .order('desc');
 
-    const rows: Awaited<ReturnType<typeof baseQuery.collect>> = [];
+    // Split into the current window vs the immediately-preceding one so we can
+    // run the (pure) reducer over each. With a period bound both windows are
+    // index-bounded; only the all-time view (no prev) pulls a capped slab.
+    type FeedbackRow = Awaited<ReturnType<typeof baseQuery.collect>>[number];
+    const rows: FeedbackRow[] = [];
+    const prevRows: FeedbackRow[] = [];
     for await (const row of baseQuery) {
-      rows.push(row);
-      // The reducer applies its own MAX_SCAN cap; this loop is bounded by
-      // the index range when cutoffMs is set. For all-time we still pull
-      // a full slab into memory — tighten if it ever bites.
+      if (cutoffMs === null || row.createdAt >= cutoffMs) {
+        rows.push(row);
+      } else {
+        prevRows.push(row);
+      }
       if (cutoffMs === null && rows.length > MAX_SCAN_ALL_TIME) break;
     }
 
@@ -132,7 +149,23 @@ export const getFeedbackStats = query({
       maxScan: cutoffMs === null ? MAX_SCAN_ALL_TIME : Number.POSITIVE_INFINITY,
     });
 
-    return { ...stats, hasAnyFeedback };
+    let previous: FeedbackStatsResult['previous'];
+    if (prevCutoffMs !== null) {
+      const prevStats = computeFeedbackStats(prevRows, {
+        cutoffMs: prevCutoffMs,
+        agentSlug: args.agentSlug,
+        model: args.model,
+        provider: args.provider,
+        maxScan: Number.POSITIVE_INFINITY,
+      });
+      previous = {
+        positive: prevStats.message.byRating.positive,
+        negative: prevStats.message.byRating.negative,
+        total: prevStats.message.total,
+      };
+    }
+
+    return { ...stats, hasAnyFeedback, previous };
   },
 });
 
diff --git a/services/platform/convex/feedback/stats.ts b/services/platform/convex/feedback/stats.ts
index 435b65a8ed..b13117059f 100644
--- a/services/platform/convex/feedback/stats.ts
+++ b/services/platform/convex/feedback/stats.ts
@@ -57,6 +57,16 @@ export interface FeedbackStatsMatchupBucket {
   total: number;
 }
 
+/** One day of message sentiment for the sentiment-over-time trend. A type
+ *  alias (not an interface) so it carries an implicit index signature and is
+ *  assignable to the charts' `ChartRow` row type. */
+export type FeedbackDailyPoint = {
+  /** UTC `YYYY-MM-DD`. */
+  dateKey: string;
+  positive: number;
+  negative: number;
+};
+
 export interface FeedbackStats {
   message: {
     byRating: { positive: number; negative: number };
@@ -66,6 +76,8 @@ export interface FeedbackStats {
     byVerdict: Record<ArenaVerdict, number>;
     total: number;
   };
+  /** Message sentiment bucketed by UTC day (days with feedback only), ascending. */
+  series: FeedbackDailyPoint[];
   topAgents: FeedbackStatsAgentBucket[];
   topModels: FeedbackStatsModelBucket[];
   topMatchups: FeedbackStatsMatchupBucket[];
@@ -76,6 +88,14 @@ export interface FeedbackStats {
 
 const TOP_N = 10;
 
+function utcDayKey(ms: number): string {
+  const d = new Date(ms);
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
 function isArenaRow(row: Doc<'messageFeedback'>): boolean {
   return row.metadata?.arenaVerdict !== undefined;
 }
@@ -116,6 +136,7 @@ export function computeFeedbackStats(
   const agentBuckets = new Map<string, FeedbackStatsAgentBucket>();
   const modelBuckets = new Map<string, FeedbackStatsModelBucket>();
   const matchupBuckets = new Map<string, FeedbackStatsMatchupBucket>();
+  const byDay = new Map<string, { positive: number; negative: number }>();
 
   let scanned = 0;
   let capped = false;
@@ -188,9 +209,17 @@ export function computeFeedbackStats(
       }
     } else {
       messageTotal++;
-      if (row.rating === 'positive') messageByRating.positive++;
+      const isPositive = row.rating === 'positive';
+      if (isPositive) messageByRating.positive++;
       else messageByRating.negative++;
 
+      // Bucket by UTC day for the sentiment-over-time trend.
+      const dayKey = utcDayKey(row.createdAt);
+      const dayBucket = byDay.get(dayKey) ?? { positive: 0, negative: 0 };
+      if (isPositive) dayBucket.positive++;
+      else dayBucket.negative++;
+      byDay.set(dayKey, dayBucket);
+
       // topAgents / topModels are message-level only. Arena rows have no
       // single agent owner; folding them in would double-count and produce
       // misleading sentiment ratios per agent.
@@ -255,9 +284,18 @@ export function computeFeedbackStats(
     )
     .slice(0, TOP_N);
 
+  const series: FeedbackDailyPoint[] = [...byDay.entries()]
+    .map(([dateKey, v]) => ({
+      dateKey,
+      positive: v.positive,
+      negative: v.negative,
+    }))
+    .sort((a, b) => a.dateKey.localeCompare(b.dateKey));
+
   return {
     message: { byRating: messageByRating, total: messageTotal },
     arena: { byVerdict: arenaByVerdict, total: arenaTotal },
+    series,
     topAgents,
     topModels,
     topMatchups,
diff --git a/services/platform/convex/governance/dsar_policy.ts b/services/platform/convex/governance/dsar_policy.ts
index 6b26874eb0..c7ba20bb3f 100644
--- a/services/platform/convex/governance/dsar_policy.ts
+++ b/services/platform/convex/governance/dsar_policy.ts
@@ -351,6 +351,7 @@ export const recordDsarTighten = internalMutation({
       titleKey: 'dsarPolicyTightened',
       bodyKey: 'dsarPolicyTightenedBody',
       params: { proposedBy: args.actorId },
+      link: { kind: 'dsar' },
     });
     return null;
   },
@@ -399,6 +400,7 @@ export const stageDsarLoosen = internalMutation({
       titleKey: 'dsarPolicyLoosenProposed',
       bodyKey: 'dsarPolicyLoosenProposedBody',
       params: { proposedBy: args.proposedBy, effectiveAt: args.effectiveAt },
+      link: { kind: 'dsar' },
     });
     return null;
   },
@@ -476,6 +478,7 @@ export const cancelPendingDsarPolicyChange = mutation({
       titleKey: 'dsarPolicyLoosenCancelled',
       bodyKey: 'dsarPolicyLoosenCancelledBody',
       params: { cancelledBy: callerId },
+      link: { kind: 'dsar' },
     });
     return null;
   },
@@ -552,6 +555,7 @@ export const finalizeDsarApply = internalMutation({
       titleKey: 'dsarPolicyLoosenApplied',
       bodyKey: 'dsarPolicyLoosenAppliedBody',
       params: { proposedBy },
+      link: { kind: 'dsar' },
     });
     return null;
   },
diff --git a/services/platform/convex/governance/erasure.ts b/services/platform/convex/governance/erasure.ts
index 13dabfe493..35f5ef9bde 100644
--- a/services/platform/convex/governance/erasure.ts
+++ b/services/platform/convex/governance/erasure.ts
@@ -548,6 +548,7 @@ export const requestErasure = mutation({
             : {}),
         },
         subjectUserId: args.userId,
+        link: { kind: 'dsar' },
       });
     } else {
       // Default cooling-off path: row stays `pending` until
@@ -587,6 +588,7 @@ export const requestErasure = mutation({
             : {}),
         },
         subjectUserId: args.userId,
+        link: { kind: 'dsar' },
       });
     }
 
@@ -2482,6 +2484,7 @@ export const cancelErasureRequest = mutation({
           : {}),
       },
       subjectUserId: row.targetUserId,
+      link: { kind: 'dsar' },
     });
 
     await createAuditLog(ctx, {
@@ -2571,6 +2574,7 @@ export const confirmAndScheduleErasure = internalMutation({
           : {}),
       },
       subjectUserId: row.targetUserId,
+      link: { kind: 'dsar' },
     });
 
     return null;
@@ -2738,6 +2742,7 @@ export const retryErasureRequest = mutation({
           : {}),
       },
       subjectUserId: row.targetUserId,
+      link: { kind: 'dsar' },
     });
 
     await createAuditLog(ctx, {
diff --git a/services/platform/convex/governance/get_org_usage_metrics.ts b/services/platform/convex/governance/get_org_usage_metrics.ts
index f5f13b72ec..5164786b46 100644
--- a/services/platform/convex/governance/get_org_usage_metrics.ts
+++ b/services/platform/convex/governance/get_org_usage_metrics.ts
@@ -80,8 +80,17 @@ export interface UsageSummary {
   capped: boolean;
 }
 
+/** Prior equal-length window totals — drives the summary-card deltas. */
+export interface UsagePrevSummary {
+  totalRequests: number;
+  totalTokens: number;
+  totalCostCents: number;
+  activeUsers: number;
+}
+
 export interface OrgUsageMetrics {
   summary: UsageSummary;
+  previousSummary: UsagePrevSummary;
   series: UsageSeriesPoint[];
   topAgents: UsageTopAgent[];
   topModels: UsageTopModel[];
@@ -118,6 +127,30 @@ export async function getOrgUsageMetrics(
   const windowKeys = buildWindowKeys(args.granularity, args.periodDays, now);
   const windowStartKey = windowKeys[0] ?? '';
 
+  // Prior equal-length window keys, for period-over-period deltas. We widen the
+  // ledger scan back to this window's start and bucket those rows separately.
+  const prevKeys: string[] = [];
+  {
+    const seen = new Set<string>();
+    for (let i = args.periodDays * 2 - 1; i >= args.periodDays; i--) {
+      const key = buildPeriodKeyFromTimestamp(
+        args.granularity,
+        now - i * DAY_MS,
+      );
+      if (!seen.has(key)) {
+        seen.add(key);
+        prevKeys.push(key);
+      }
+    }
+  }
+  const prevKeySet = new Set(prevKeys);
+  const scanStartKey = prevKeys[0] ?? windowStartKey;
+
+  let prevTotalRequests = 0;
+  let prevTotalTokens = 0;
+  let prevTotalCostCents = 0;
+  const prevActiveUserIds = new Set<string>();
+
   const seriesMap = new Map<string, UsageSeriesPoint>();
   for (const key of windowKeys) {
     seriesMap.set(key, {
@@ -162,7 +195,7 @@ export async function getOrgUsageMetrics(
       q
         .eq('organizationId', args.organizationId)
         .eq('granularity', args.granularity)
-        .gte('periodKey', windowStartKey),
+        .gte('periodKey', scanStartKey),
     )) {
     scanned++;
     if (scanned > MAX_SCAN) {
@@ -182,7 +215,16 @@ export async function getOrgUsageMetrics(
     }
 
     const seriesPoint = seriesMap.get(row.periodKey);
-    if (!seriesPoint) continue;
+    if (!seriesPoint) {
+      // Rows outside the current window but inside the prior one feed deltas.
+      if (prevKeySet.has(row.periodKey)) {
+        prevTotalRequests += row.requestCount;
+        prevTotalTokens += row.totalTokens;
+        prevTotalCostCents += row.costEstimate;
+        if (row.requestCount > 0) prevActiveUserIds.add(row.userId);
+      }
+      continue;
+    }
 
     seriesPoint.requests += row.requestCount;
     seriesPoint.inputTokens += row.inputTokens;
@@ -354,6 +396,12 @@ export async function getOrgUsageMetrics(
       activeUsers: activeUserIds.size,
       capped,
     },
+    previousSummary: {
+      totalRequests: prevTotalRequests,
+      totalTokens: prevTotalTokens,
+      totalCostCents: prevTotalCostCents,
+      activeUsers: prevActiveUserIds.size,
+    },
     series: [...seriesMap.values()],
     topAgents,
     topModels,
diff --git a/services/platform/convex/lib/agent_chat/internal_actions.ts b/services/platform/convex/lib/agent_chat/internal_actions.ts
index 9a3aa1876a..fa95e74ef0 100644
--- a/services/platform/convex/lib/agent_chat/internal_actions.ts
+++ b/services/platform/convex/lib/agent_chat/internal_actions.ts
@@ -9,6 +9,15 @@ import {
 import type { ModelMessage } from 'ai';
 import { type ObjectType, v } from 'convex/values';
 
+import {
+  buildHumanErrorSentence,
+  classifyChatErrorCode,
+  encodeChatError,
+} from '../../../lib/shared/chat-errors';
+import {
+  formatModelFallbackBody,
+  SYSTEM_MSG_TAG,
+} from '../../../lib/shared/constants/system-message-tags';
 import { parseModelRef } from '../../../lib/shared/utils/model-ref';
 import {
   isRecord,
@@ -18,13 +27,18 @@ import {
 import { components, internal } from '../../_generated/api';
 import { internalAction, type ActionCtx } from '../../_generated/server';
 import { TOOL_NAMES, type ToolName } from '../../agent_tools/tool_names';
+import { routeSeedValidator, routeTuningValidator } from '../../agents/schema';
 import { resolveOrgSlug } from '../../organizations/resolve_org_slug';
 import { recordFailure } from '../../providers/circuit_breaker';
 import {
+  classifyFailureScope,
   isTransientProviderError,
-  shouldFailoverToNextModel,
 } from '../../providers/errors';
 import { resolveLanguageModelWithFallback } from '../../providers/failover';
+import {
+  isModelScopeRetired,
+  retiredScopeKey,
+} from '../../providers/failure_scope';
 // Node-only fast-path resolver — in-process, skips the ~340ms runAction hop
 // that resolve_model.ts uses to stay V8-importable.
 import { resolveLanguageModelByIdNode } from '../../providers/resolve_model_node';
@@ -48,10 +62,7 @@ import {
 } from '../context_management/constants';
 import { createAgentConfig } from '../create_agent_config';
 import { createDebugLog } from '../debug_log';
-import {
-  NonRetryableError,
-  classifyProviderError,
-} from '../error_classification';
+import { NonRetryableError } from '../error_classification';
 import { buildCallProviderOptions } from '../provider_options';
 import { buildHooksFromConfig } from './build_hooks';
 import {
@@ -71,76 +82,6 @@ import {
 
 const debugLog = createDebugLog('DEBUG_CHAT_AGENT', '[runAgentGeneration]');
 
-/**
- * Convex validator mirror of `responseTuningSchema` (lib/shared/schemas/agents).
- * Kept in lockstep so the serializable config can carry per-agent tuning
- * through the scheduler arg boundary.
- */
-const responseTuningValidator = v.object({
-  effort: v.optional(
-    v.union(
-      v.literal('adaptive'),
-      v.literal('low'),
-      v.literal('medium'),
-      v.literal('high'),
-    ),
-  ),
-  creativity: v.optional(
-    v.union(
-      v.literal('adaptive'),
-      v.literal('precise'),
-      v.literal('balanced'),
-      v.literal('creative'),
-    ),
-  ),
-  style: v.optional(
-    v.union(
-      v.literal('adaptive'),
-      v.literal('concise'),
-      v.literal('detailed'),
-      v.literal('formal'),
-      v.literal('friendly'),
-    ),
-  ),
-  effortFloor: v.optional(
-    v.union(
-      v.literal('off'),
-      v.literal('low'),
-      v.literal('medium'),
-      v.literal('high'),
-    ),
-  ),
-  effortCeiling: v.optional(
-    v.union(
-      v.literal('off'),
-      v.literal('low'),
-      v.literal('medium'),
-      v.literal('high'),
-    ),
-  ),
-  budgetCaps: v.optional(
-    v.object({
-      easy: v.optional(v.number()),
-      medium: v.optional(v.number()),
-      hard: v.optional(v.number()),
-    }),
-  ),
-  temperatureRange: v.optional(
-    v.object({ min: v.optional(v.number()), max: v.optional(v.number()) }),
-  ),
-  verbosity: v.optional(
-    v.union(
-      v.literal('adaptive'),
-      v.literal('terse'),
-      v.literal('normal'),
-      v.literal('verbose'),
-    ),
-  ),
-  qualityProfile: v.optional(
-    v.union(v.literal('lenient'), v.literal('balanced'), v.literal('strict')),
-  ),
-});
-
 const serializableAgentConfigValidator = v.object({
   name: v.string(),
   /**
@@ -216,7 +157,11 @@ const serializableAgentConfigValidator = v.object({
   outputReserve: v.optional(v.number()),
   fallbackModels: v.optional(v.array(v.string())),
   personalizationMode: v.optional(v.union(v.literal('on'), v.literal('off'))),
-  responseTuning: v.optional(responseTuningValidator),
+  /** Prose-level style/verbosity the Auto router advised (Auto mode only). */
+  responseStyle: v.optional(routeTuningValidator),
+  /** Coarse reasoning seed (effort/creativity) the Auto router advised, fed to
+   *  the governor as a prior (Auto mode only). */
+  routeSeed: v.optional(routeSeedValidator),
   /** Advisory reply-language hint from the Auto router (feeds the language
    *  directive's fallback only). See `SerializableAgentConfig.replyLocaleHint`. */
   replyLocaleHint: v.optional(v.string()),
@@ -393,6 +338,13 @@ export async function runGenerationCore(
     throw new Error(`Invalid agent type: ${agentTypeStr}`);
   }
 
+  // Tracked across the fallback loop so the final catch-all can build an
+  // accurate, provider-specific error envelope (which model/provider failed
+  // last, and how many were attempted).
+  let lastResolvedProvider: string | undefined;
+  let lastResolvedModelId: string | undefined;
+  let attemptedCount = 0;
+
   try {
     const toolBuildStart = Date.now();
 
@@ -549,27 +501,39 @@ export async function runGenerationCore(
       }
     }
 
-    // Fallback retry loop — try each model in order until one succeeds
+    // Fallback retry loop — try each model in order until one succeeds.
+    //
+    // A model that fails with a DETERMINISTIC provider-level error retires the
+    // failing *resource* — the credential (provider + API key) for funds/auth,
+    // or the endpoint (provider + baseUrl) for an unreachable host — and every
+    // later model sharing that resource is skipped instead of waiting on a
+    // doomed request. Keying by credential (not provider name) means a sibling
+    // model with its own `secretsEnv` key is still tried after another key dies.
     let lastFallbackError: unknown;
-    for (let attempt = 0; attempt < modelsToTry.length; attempt++) {
-      const currentModelId = modelsToTry[attempt];
-
-      // RESOLUTION (no HTTP). A model/provider that is not configured or
-      // wrongly configured — missing/unknown provider or model, unresolvable
-      // API key, malformed baseURL — throws synchronously here. When that
-      // happens we go straight to the next model in line WITHOUT making (and
-      // waiting on) a doomed request, and without recording a circuit-breaker
-      // failure (it's a config problem, not provider flakiness).
-      // orgSlug was resolved once in the outer Promise.all and is shared across
-      // model lookup + delegation + workflows so multi-org deployments read each
-      // org's own provider/API-key files. Per-entry provider qualifier (e.g.
-      // "openrouter:foo") takes precedence over the agent's.
-      let resolved: Awaited<ReturnType<typeof resolveLanguageModelByIdNode>>;
+    const deadScopes = new Set<string>();
+
+    // RESOLUTION (no HTTP) is memoized per model index so the catch can look
+    // ahead for the next attemptable model without paying for it twice. A
+    // model/provider that is not configured or wrongly configured — missing
+    // provider/model, unresolvable key, malformed baseURL — resolves to an
+    // error here, and we move on WITHOUT a doomed request or a circuit-breaker
+    // record (config problem, not provider flakiness). Per-entry provider
+    // qualifier ("openrouter:foo") takes precedence over the agent's.
+    type Resolution =
+      | {
+          ok: true;
+          resolved: Awaited<ReturnType<typeof resolveLanguageModelByIdNode>>;
+        }
+      | { ok: false; error: unknown };
+    const resolutionCache = new Map<number, Resolution>();
+    const resolveAt = async (index: number): Promise<Resolution> => {
+      const cached = resolutionCache.get(index);
+      if (cached) return cached;
+      const ref = modelsToTry[index];
+      let result: Resolution;
       try {
-        const parsed = currentModelId
-          ? parseModelRef(currentModelId)
-          : undefined;
-        resolved = parsed
+        const parsed = ref ? parseModelRef(ref) : undefined;
+        const resolved = parsed
           ? await resolveLanguageModelByIdNode(ctx, {
               modelId: parsed.modelId,
               providerName: parsed.providerName ?? agentConfig.provider,
@@ -580,26 +544,64 @@ export async function runGenerationCore(
               tag: 'chat',
               organizationId,
             });
-      } catch (resolveError) {
-        lastFallbackError = resolveError;
+        result = { ok: true, resolved };
+      } catch (error) {
+        result = { ok: false, error };
+      }
+      resolutionCache.set(index, result);
+      return result;
+    };
+    // First index ≥ `from` that resolves to a configured model on a live scope.
+    const findNextAttemptable = async (from: number): Promise<number> => {
+      for (let i = from; i < modelsToTry.length; i++) {
+        const r = await resolveAt(i);
+        if (r.ok && !isModelScopeRetired(r.resolved.modelData, deadScopes)) {
+          return i;
+        }
+      }
+      return -1;
+    };
+
+    for (let attempt = 0; attempt < modelsToTry.length; attempt++) {
+      const currentModelId = modelsToTry[attempt];
+
+      const resolution = await resolveAt(attempt);
+      if (!resolution.ok) {
+        lastFallbackError = resolution.error;
         if (attempt < modelsToTry.length - 1) {
           debugLog('SKIP_UNCONFIGURED_MODEL', {
             model: currentModelId ?? 'default',
             nextModel: modelsToTry[attempt + 1] ?? 'default',
             reason:
-              resolveError instanceof Error
-                ? resolveError.message
-                : String(resolveError),
+              resolution.error instanceof Error
+                ? resolution.error.message
+                : String(resolution.error),
           });
           continue;
         }
-        throw resolveError;
+        throw resolution.error;
+      }
+      const resolved = resolution.resolved;
+
+      // Skip a resource already retired this turn — no HTTP call, no
+      // circuit-breaker record, no fallback notice. If it's the last entry the
+      // loop falls through to the throw below, carrying the real cause.
+      if (isModelScopeRetired(resolved.modelData, deadScopes)) {
+        debugLog('SKIP_DEAD_SCOPE', {
+          model: resolved.modelData.modelId,
+          provider: resolved.modelData.providerName,
+        });
+        if (attempt < modelsToTry.length - 1) continue;
+        break;
       }
 
       try {
         const { languageModel, modelData } = resolved;
         const resolvedProvider = modelData.providerName;
         const resolvedModelId = modelData.modelId;
+        lastResolvedProvider = resolvedProvider;
+        lastResolvedModelId = resolvedModelId;
+        attemptedCount += 1;
 
         // Prewarm only pays off when there is a cache to warm. For a model whose
         // caching strategy resolves to 'none' (unknown family, no operator
@@ -735,6 +737,11 @@ export async function runGenerationCore(
             : undefined,
         });
 
+        // Is another model still worth trying if this one fails? (Resolution is
+        // memoized, so this lookahead is reused by the catch's failover.)
+        const hasNextAttemptable =
+          (await findNextAttemptable(attempt + 1)) !== -1;
+
         const result = await generateAgentResponse(
           {
             agentType,
@@ -762,7 +769,8 @@ export async function runGenerationCore(
             modelMaxOutputTokens: modelData.maxOutputTokens,
             modelContextWindow: modelData.contextWindow,
             reasoningCapability: modelData.reasoning,
-            responseTuning: agentConfig.responseTuning,
+            responseStyle: agentConfig.responseStyle,
+            routeSeed: agentConfig.routeSeed,
             replyLocaleHint: agentConfig.replyLocaleHint,
           },
           {
@@ -795,9 +803,10 @@ export async function runGenerationCore(
             pinnedFileIds: args.pinnedFileIds,
             requestStartMs: args.requestStartMs,
             // Suppress error cleanup (stream error, generation status clear,
-            // failed message) when there are more fallback models to try.
-            // The fallback loop handles cleanup itself.
-            suppressErrorCleanup: attempt < modelsToTry.length - 1,
+            // failed message) when there is another model still worth trying.
+            // The fallback loop handles cleanup itself; the final catch-all
+            // owns it when nothing attemptable remains.
+            suppressErrorCleanup: hasNextAttemptable,
             prewarm: args.prewarm,
           },
         );
@@ -845,103 +854,108 @@ export async function runGenerationCore(
         return result;
       } catch (fallbackError) {
         lastFallbackError = fallbackError;
-        const hasMoreFallbacks = attempt < modelsToTry.length - 1;
-
-        // Retry on any provider-specific error with remaining fallbacks.
-        // This includes transient errors (429, 5xx) AND non-transient
-        // provider errors (401 auth, 404 model-not-found) because a
-        // different fallback model may use a different provider.
-        if (hasMoreFallbacks && shouldFailoverToNextModel(fallbackError)) {
-          const failedModelLabel = currentModelId ?? model;
-          const nextModel = modelsToTry[attempt + 1] ?? 'default';
-
-          // Record circuit breaker failure only for transient errors
-          // (429, 5xx, timeouts). Non-transient errors like 401/404 are
-          // config issues, not provider flakiness.
-          if (
-            currentModelId &&
-            agentConfig.provider &&
-            isTransientProviderError(fallbackError)
-          ) {
-            recordFailure(agentConfig.provider, currentModelId);
-          }
 
-          // Check remaining deadline budget before retrying
-          if (deadlineMs && Date.now() >= deadlineMs - 5000) {
+        const scope = classifyFailureScope(fallbackError);
+
+        // Terminal: would fail on ANY model (content policy, context length,
+        // no provider configured). Don't walk the chain at all.
+        if (scope === 'terminal') throw fallbackError;
+
+        const failedRef = currentModelId ?? model;
+        const reasonCode = classifyChatErrorCode(fallbackError);
+
+        // Deterministic provider-level failure (out of funds / invalid key /
+        // host down): retire the failing RESOURCE — the credential (provider +
+        // key) for funds/auth, the endpoint for an unreachable host — so its
+        // siblings are skipped, but a sibling with its OWN key is still tried.
+        const retired = retiredScopeKey(reasonCode, resolved.modelData);
+        if (retired) deadScopes.add(retired);
+
+        // Record a circuit-breaker failure only for transient errors (429,
+        // 5xx, timeouts) — config/account issues aren't provider flakiness.
+        if (
+          currentModelId &&
+          agentConfig.provider &&
+          isTransientProviderError(fallbackError)
+        ) {
+          recordFailure(agentConfig.provider, currentModelId);
+        }
+
+        // The next model still worth attempting (skips retired resources).
+        const nextIndex = await findNextAttemptable(attempt + 1);
+        const outOfTime = deadlineMs != null && Date.now() >= deadlineMs - 5000;
+
+        // Nothing attemptable left, or no time budget — surface the cause.
+        if (nextIndex === -1 || outOfTime) {
+          if (outOfTime) {
             debugLog('FALLBACK_SKIP_DEADLINE', {
-              failedModel: failedModelLabel,
-              remainingMs: deadlineMs - Date.now(),
+              failedModel: failedRef,
+              remainingMs:
+                deadlineMs != null ? deadlineMs - Date.now() : undefined,
             });
-            throw fallbackError;
           }
+          throw fallbackError;
+        }
+
+        const nextRef = modelsToTry[nextIndex] ?? 'default';
+        // Machine-readable body — the chat UI renders a localized line and the
+        // model auto-switch reads `to`.
+        const fallbackBody = `${SYSTEM_MSG_TAG.MODEL_FALLBACK} ${formatModelFallbackBody(
+          { from: failedRef, to: nextRef, reason: reasonCode },
+        )}`;
+
+        debugLog('MODEL_FALLBACK', {
+          attempt: attempt + 1,
+          failedModel: failedRef,
+          nextModel: nextRef,
+          scope,
+          reason: reasonCode,
+        });
 
-          const errStatus = isRecord(fallbackError)
-            ? (fallbackError['status'] ?? fallbackError['statusCode'])
-            : undefined;
-          const errMessage = isRecord(fallbackError)
-            ? getString(fallbackError, 'message')
-            : undefined;
-          debugLog('MODEL_FALLBACK', {
-            attempt: attempt + 1,
-            failedModel: failedModelLabel,
-            nextModel,
-            errorStatus: typeof errStatus === 'number' ? errStatus : undefined,
-            errorMessage: errMessage?.slice(0, 200),
+        // Save a structured system message so the user sees the fallback.
+        try {
+          await saveMessage(ctx, components.agent, {
+            threadId,
+            message: { role: 'system', content: fallbackBody },
           });
+        } catch (msgError) {
+          console.error(
+            '[runAgentGeneration] Failed to save fallback message:',
+            msgError,
+          );
+        }
 
-          // Save system message so the user sees the fallback in chat
-          try {
-            await saveMessage(ctx, components.agent, {
-              threadId,
-              message: {
-                role: 'system',
-                content: `[MODEL_FALLBACK] ${failedModelLabel} was unavailable. Trying ${nextModel}...`,
+        // Convert any stale failed/pending assistant message from this attempt
+        // (suppressErrorCleanup left it untouched) into the same structured
+        // fallback note so the thread doesn't show an orphaned error bubble.
+        try {
+          const msgs = await listMessages(ctx, components.agent, {
+            threadId,
+            paginationOpts: { cursor: null, numItems: 5 },
+            excludeToolMessages: true,
+          });
+          const staleAssistants = msgs.page.filter(
+            (m: MessageDoc) =>
+              m.message?.role === 'assistant' &&
+              (m.status === 'failed' || m.status === 'pending'),
+          );
+          for (const stale of staleAssistants) {
+            await ctx.runMutation(components.agent.messages.updateMessage, {
+              messageId: stale._id,
+              patch: {
+                status: 'success',
+                message: { role: 'system', content: fallbackBody },
               },
             });
-          } catch (msgError) {
-            console.error(
-              '[runAgentGeneration] Failed to save fallback message:',
-              msgError,
-            );
-          }
-
-          // Clean up stale assistant messages from this attempt.
-          // With suppressErrorCleanup, generateAgentResponse skips saving
-          // failed messages, but the Agent SDK may have created a pending
-          // message before the error. Convert any failed/pending assistant
-          // messages to a system fallback note.
-          try {
-            const msgs = await listMessages(ctx, components.agent, {
-              threadId,
-              paginationOpts: { cursor: null, numItems: 5 },
-              excludeToolMessages: true,
-            });
-            const staleAssistants = msgs.page.filter(
-              (m: MessageDoc) =>
-                m.message?.role === 'assistant' &&
-                (m.status === 'failed' || m.status === 'pending'),
-            );
-            for (const stale of staleAssistants) {
-              await ctx.runMutation(components.agent.messages.updateMessage, {
-                messageId: stale._id,
-                patch: {
-                  status: 'success',
-                  message: {
-                    role: 'system',
-                    content: `[MODEL_FALLBACK] ${failedModelLabel} failed — retrying with ${nextModel}.`,
-                  },
-                },
-              });
-            }
-          } catch (cleanupError) {
-            debugLog('FALLBACK_CLEANUP_ERROR', { error: cleanupError });
           }
-
-          continue;
+        } catch (cleanupError) {
+          debugLog('FALLBACK_CLEANUP_ERROR', { error: cleanupError });
         }
 
-        // Non-transient error or no more fallbacks — rethrow
-        throw fallbackError;
+        // Advance to the next model; the dead-provider guard at the top of the
+        // loop skips any retired-provider entries before `nextRef` cheaply
+        // (resolution only, no request).
+        continue;
       }
     }
 
@@ -1013,20 +1027,43 @@ export async function runGenerationCore(
         const newestAssistant = msgs.page.find(
           (m: MessageDoc) => m.message?.role === 'assistant',
         );
-        const hasFailedAssistant = newestAssistant?.status === 'failed';
-        if (!hasFailedAssistant) {
-          const providerError = classifyProviderError(error);
-          await saveMessage(ctx, components.agent, {
-            threadId,
-            message: {
-              role: 'assistant',
-              content: providerError.userMessage,
-            },
-            metadata: {
+        // Structured, machine-readable error: the chat UI decodes it into an
+        // authoritative, localized, provider-specific message; non-chat
+        // surfaces fall back to the human sentence in `content`.
+        const code = classifyChatErrorCode(error);
+        const failedContent = buildHumanErrorSentence(code, {
+          provider: lastResolvedProvider,
+          model: lastResolvedModelId,
+        });
+        const failedError = encodeChatError({
+          code,
+          provider: lastResolvedProvider,
+          model: lastResolvedModelId,
+          triedCount: attemptedCount > 0 ? attemptedCount : undefined,
+          raw: getString(err, 'message') ?? 'Unknown error',
+        });
+
+        if (newestAssistant?.status === 'failed') {
+          // Already failed (generateAgentResponse saved it with its own
+          // envelope) — leave it.
+        } else if (newestAssistant?.status === 'pending') {
+          // Zombie pending message — the SDK created it but generation threw
+          // before finalize. Update in place so the user sees the error
+          // instead of a perpetual spinner.
+          await ctx.runMutation(components.agent.messages.updateMessage, {
+            messageId: newestAssistant._id,
+            patch: {
               status: 'failed',
-              error: `[${providerError.errorType}] ${getString(err, 'message') ?? 'Unknown error'}`,
+              error: failedError,
+              message: { role: 'assistant' as const, content: failedContent },
             },
           });
+        } else {
+          await saveMessage(ctx, components.agent, {
+            threadId,
+            message: { role: 'assistant', content: failedContent },
+            metadata: { status: 'failed', error: failedError },
+          });
         }
       } catch (saveError) {
         console.error(
diff --git a/services/platform/convex/lib/agent_chat/types.ts b/services/platform/convex/lib/agent_chat/types.ts
index fa188ff34d..9522d8ed8d 100644
--- a/services/platform/convex/lib/agent_chat/types.ts
+++ b/services/platform/convex/lib/agent_chat/types.ts
@@ -6,9 +6,10 @@
  */
 
 import type {
-  AgentRoutingConfig,
-  ResponseTuningConfig,
-} from '../../../lib/shared/schemas/agents';
+  ResponseReasoningSeed,
+  ResponseStyleAdvice,
+} from '../../../lib/shared/response-tuning';
+import type { AgentRoutingConfig } from '../../../lib/shared/schemas/agents';
 import type { ToolName } from '../../agent_tools/tool_registry';
 import type { AgentType } from '../context_management/constants';
 
@@ -99,12 +100,19 @@ export interface SerializableAgentConfig {
   /** Ordered fallback model IDs (tried in sequence when primary fails) */
   fallbackModels?: string[];
   /**
-   * Per-agent response tuning (effort/creativity/style + governor bounds).
-   * Consumed by `buildReasoningOptions` and the style/verbosity prompt
-   * fragments. Mirrors `responseTuningSchema` in
-   * `lib/shared/schemas/agents.ts`.
+   * Prose-level response shaping (style/verbosity) the Auto router advised for
+   * this turn. Rendered into a short system-prompt suffix by
+   * `tuningInstructionSuffix`. Set ONLY in Auto mode; a pinned agent's tone
+   * comes from its own `instructions`.
    */
-  responseTuning?: ResponseTuningConfig;
+  responseStyle?: ResponseStyleAdvice;
+  /**
+   * Coarse reasoning seed (effort/creativity) the Auto router advised for this
+   * turn. Fed to `buildReasoningOptions` as a PRIOR — blended into the
+   * difficulty score, never a hard override; the online controller still
+   * refines from observed usage. Set ONLY in Auto mode.
+   */
+  routeSeed?: ResponseReasoningSeed;
   /**
    * Advisory reply-language hint set by the Auto router for this turn (BCP-47
    * code or language name). Feeds ONLY the response-language directive's
diff --git a/services/platform/convex/lib/agent_response/generate_response.ts b/services/platform/convex/lib/agent_response/generate_response.ts
index e64936b6ad..c981bdf114 100644
--- a/services/platform/convex/lib/agent_response/generate_response.ts
+++ b/services/platform/convex/lib/agent_response/generate_response.ts
@@ -25,10 +25,10 @@ import type { StreamMessage } from '@convex-dev/agent/validators';
 import type { ModelMessage } from 'ai';
 
 import {
-  creativityToScoreOverride,
-  effortToTierOverride,
-  tuningInstructionSuffix,
-} from '../../../lib/shared/response-tuning';
+  classifyChatErrorCode,
+  encodeChatError,
+} from '../../../lib/shared/chat-errors';
+import { tuningInstructionSuffix } from '../../../lib/shared/response-tuning';
 import { isRecord, getString } from '../../../lib/utils/type-utils';
 import { components, internal } from '../../_generated/api';
 import { queryRagContext } from '../../agent_tools/rag/query_rag_context';
@@ -178,7 +178,8 @@ export async function generateAgentResponse(
     modelMaxOutputTokens,
     modelContextWindow,
     reasoningCapability,
-    responseTuning,
+    responseStyle,
+    routeSeed,
     replyLocaleHint,
   } = config;
   const {
@@ -927,18 +928,14 @@ export async function generateAgentResponse(
             maxSteps: args.maxSteps,
             agentType,
             historyMessageCount: structuredThreadContext?.stats.messageCount,
+            // Auto-router reasoning seed (Auto mode only): blends the heuristic
+            // difficulty prior toward the router's coarse read as a PRIOR — the
+            // controller still refines from observed usage.
+            effortSeed: routeSeed?.effort,
+            creativitySeed: routeSeed?.creativity,
           },
           state: reasoningState,
           profile: reasoningProfile ?? undefined,
-          effortOverride: effortToTierOverride(responseTuning?.effort),
-          creativityOverride: creativityToScoreOverride(
-            responseTuning?.creativity,
-          ),
-          effortFloorTier: responseTuning?.effortFloor,
-          effortCeilingTier: responseTuning?.effortCeiling,
-          budgetCaps: responseTuning?.budgetCaps,
-          temperatureRange: responseTuning?.temperatureRange,
-          qualityProfile: responseTuning?.qualityProfile,
         })
       : undefined;
     const reasoningProviderOptions =
@@ -948,10 +945,10 @@ export async function generateAgentResponse(
     const effectiveTemperature =
       generationParams?.temperature ?? reasoningDecision?.temperature;
 
-    // Per-agent response-tuning style/verbosity fragment, appended to the
-    // agent's instructions for this turn (replaces the old per-message composer
-    // style application in start_chat).
-    const tuningSuffix = tuningInstructionSuffix(responseTuning);
+    // Auto-router style/verbosity fragment, appended to the agent's
+    // instructions for this turn. Set only in Auto mode; a pinned agent's tone
+    // comes from its own instructions, so this is empty there.
+    const tuningSuffix = tuningInstructionSuffix(responseStyle);
     const tunedInstructions = tuningSuffix
       ? instructions
         ? `${instructions}\n\n${tuningSuffix}`
@@ -2165,22 +2162,38 @@ export async function generateAgentResponse(
 
     const cancelled = await checkCancelled();
 
+    // The model is reasoning-STEERABLE this turn (has a capability) — true even
+    // when the governor chose `off`. We record an outcome for every steerable
+    // turn, INCLUDING a self-truncating model parked at `off`: a bad off-turn is
+    // exactly the signal that it under-reasoned, and without recording it the
+    // class could never climb out of off. `selfTruncates` is undefined only for
+    // non-steerable models.
+    const reasoningSteered =
+      reasoningDecision != null &&
+      reasoningDecision.selfTruncates !== undefined;
+
     // Score the final answer's quality (hedging / specificity / hallucination /
     // length) so the governor's online controller learns from whether the
-    // budget produced GOOD answers, not just token counts. Only when the model
-    // was actually steered this turn and produced text.
+    // budget produced GOOD answers, not just token counts. The quality profile
+    // is fixed at 'balanced' (the manual per-agent override was removed).
     const reasoningQualityScore =
-      reasoningDecision?.applied && responseResult.text
+      reasoningSteered && responseResult.text
         ? analyzeResponseQuality({
             text: responseResult.text,
             complexity: reasoningDecision.difficultyClass,
-            thresholds: thresholdsFor(
-              responseTuning?.qualityProfile ?? 'balanced',
-            ),
+            thresholds: thresholdsFor('balanced'),
             isMathLike: /\d\s*[+\-*/×÷=]\s*\d/.test(responseResult.text),
           }).score
         : undefined;
 
+    // Don't feed a thinking-token sample for a turn that wasn't actually steered
+    // to think (a self-truncating model at `off`): a `0` sample would poison the
+    // Welford mean ("this class needs 0 tokens") and trap the class at off. The
+    // qualityScore still flows, so a bad off-turn can still push it up.
+    const recordedReasoningTokens = reasoningDecision?.applied
+      ? responseResult.usage?.reasoningTokens
+      : undefined;
+
     // Run the remaining post-processing in parallel — clearGenerationStatus
     // (the only operation the user perceives), onAgentComplete (metadata +
     // ledger + audit), and persistent stream finalization are all
@@ -2234,8 +2247,9 @@ export async function generateAgentResponse(
           : Promise.resolve(),
         // Adaptive Reasoning Governor (Layer C): fold this turn's outcome into
         // the thread's learned state so the next turn converges toward the
-        // model's revealed need. Only when the model is actually steerable.
-        reasoningDecision?.applied
+        // model's revealed need. Recorded for every steerable turn (incl. a
+        // self-truncating model parked at `off`).
+        reasoningSteered
           ? ctx
               .runMutation(
                 internal.threads.internal_mutations.updateThreadReasoningState,
@@ -2244,12 +2258,13 @@ export async function generateAgentResponse(
                   difficultyClass: reasoningDecision.difficultyClass,
                   budgetTokens: reasoningDecision.budgetTokens,
                   selfTruncates: reasoningDecision.selfTruncates ?? false,
-                  reasoningTokens: responseResult.usage?.reasoningTokens,
+                  reasoningTokens: recordedReasoningTokens,
                   outputTokens: responseResult.usage?.outputTokens,
                   intensity: reasoningDecision.intensity,
                   finishReason: responseResult.finishReason,
                   retried: didRetry,
                   qualityScore: reasoningQualityScore,
+                  chosenTier: reasoningDecision.tier,
                 },
               )
               .catch((reasoningErr: unknown) =>
@@ -2263,7 +2278,7 @@ export async function generateAgentResponse(
           : Promise.resolve(),
         // Also fold the outcome into the cross-thread profile (per org + model)
         // so future threads — and the stateless API path — warm-start from it.
-        reasoningDecision?.applied && organizationId
+        reasoningSteered && organizationId
           ? ctx
               .runMutation(
                 internal.threads.internal_mutations.updateReasoningProfile,
@@ -2273,12 +2288,13 @@ export async function generateAgentResponse(
                   difficultyClass: reasoningDecision.difficultyClass,
                   budgetTokens: reasoningDecision.budgetTokens,
                   selfTruncates: reasoningDecision.selfTruncates ?? false,
-                  reasoningTokens: responseResult.usage?.reasoningTokens,
+                  reasoningTokens: recordedReasoningTokens,
                   outputTokens: responseResult.usage?.outputTokens,
                   intensity: reasoningDecision.intensity,
                   finishReason: responseResult.finishReason,
                   retried: didRetry,
                   qualityScore: reasoningQualityScore,
+                  chosenTier: reasoningDecision.tier,
                 },
               )
               .catch((profileErr: unknown) =>
@@ -2537,6 +2553,15 @@ export async function generateAgentResponse(
         );
         const failedContent =
           'I was unable to complete your request. Please try again.';
+        // Stamp a structured, machine-readable envelope on the error so the
+        // chat UI can render an authoritative, localized, provider-specific
+        // message instead of regex-guessing the raw provider string.
+        const failedError = encodeChatError({
+          code: classifyChatErrorCode(error),
+          provider,
+          model,
+          raw: errorMessage || 'Unknown error',
+        });
 
         if (newestAssistant?.status === 'failed') {
           // Already marked as failed (e.g. by SDK's call.fail())
@@ -2549,7 +2574,7 @@ export async function generateAgentResponse(
             messageId: newestAssistant._id,
             patch: {
               status: 'failed',
-              error: errorMessage || 'Unknown error',
+              error: failedError,
               message: {
                 role: 'assistant' as const,
                 content: failedContent,
@@ -2570,7 +2595,7 @@ export async function generateAgentResponse(
               },
               metadata: {
                 status: 'failed',
-                error: errorMessage || 'Unknown error',
+                error: failedError,
               },
             },
           );
diff --git a/services/platform/convex/lib/agent_response/generate_response_error_handling.test.ts b/services/platform/convex/lib/agent_response/generate_response_error_handling.test.ts
index cafc7fd6d7..799e9c0034 100644
--- a/services/platform/convex/lib/agent_response/generate_response_error_handling.test.ts
+++ b/services/platform/convex/lib/agent_response/generate_response_error_handling.test.ts
@@ -1,5 +1,10 @@
 import { afterEach, describe, it, expect, vi, beforeEach } from 'vitest';
 
+import {
+  classifyChatErrorCode,
+  encodeChatError,
+} from '../../../lib/shared/chat-errors';
+
 // Mock @convex-dev/agent before importing the module under test
 const mockAbortStream = vi.fn();
 const mockListMessages = vi.fn();
@@ -171,7 +176,15 @@ describe('generateAgentResponse error handling', () => {
         },
         metadata: {
           status: 'failed',
-          error: 'Model API unavailable',
+          // The error is stamped with the structured `TALE_ERR1` envelope so the
+          // chat UI can render a localized, provider-specific message; the raw
+          // provider text is preserved after the header line.
+          error: encodeChatError({
+            code: classifyChatErrorCode(testError),
+            provider: 'openai',
+            model: 'gpt-4',
+            raw: 'Model API unavailable',
+          }),
         },
       },
     );
@@ -242,14 +255,19 @@ describe('generateAgentResponse error handling', () => {
       generateAgentResponse(createMockConfig(), createMockArgs(ctx)),
     ).rejects.toBe('string error');
 
-    // Non-Error thrown values are wrapped as { message: String(error) }
+    // Non-Error thrown values are stringified into the envelope's raw tail.
     expect(mockSaveMessage).toHaveBeenCalledWith(
       ctx,
       expect.objectContaining({ streams: expect.anything() }),
       expect.objectContaining({
         metadata: expect.objectContaining({
           status: 'failed',
-          error: 'string error',
+          error: encodeChatError({
+            code: classifyChatErrorCode('string error'),
+            provider: 'openai',
+            model: 'gpt-4',
+            raw: 'string error',
+          }),
         }),
       }),
     );
diff --git a/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.test.ts b/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.test.ts
index 4cac12d79a..32a73cbdad 100644
--- a/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.test.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.test.ts
@@ -147,89 +147,60 @@ describe('buildReasoningOptions', () => {
     });
   });
 
-  describe('per-agent response-tuning bounds', () => {
-    it('caps the tier at the effort ceiling on a hard turn', () => {
-      const decision = buildReasoningOptions({
-        modelData: {
-          providerName: 'openai',
-          modelId: 'gpt-5',
-          reasoning: { knob: 'effort', supportsMinimal: true },
-        },
-        signals: HARD,
-        effortCeilingTier: 'low',
+  describe('router reasoning seed (Auto-mode prior blend)', () => {
+    const RANK: Record<string, number> = { off: 0, low: 1, medium: 2, high: 3 };
+    const GPT5 = {
+      providerName: 'openai',
+      modelId: 'gpt-5',
+      reasoning: { knob: 'effort' as const, supportsMinimal: true },
+    };
+
+    it('lifts a lexically-plain prompt when the router seeds high effort', () => {
+      const seeded = buildReasoningOptions({
+        modelData: GPT5,
+        signals: { ...TRIVIAL, effortSeed: 'high' },
       });
-      // HARD alone would be 'high'; the ceiling clamps it to 'low'.
-      expect(decision.tier).toBe('low');
-      expect(decision.providerOptions).toEqual({
-        openai: { reasoningEffort: 'low' },
+      const unseeded = buildReasoningOptions({
+        modelData: GPT5,
+        signals: TRIVIAL,
       });
+      // The seed pulls the heuristic prior up, so a trivial-LOOKING prompt the
+      // router judged hard reasons harder than the pure heuristic would.
+      expect(RANK[seeded.tier]).toBeGreaterThan(RANK[unseeded.tier]);
     });
 
-    it('lifts the tier to the effort floor on a trivial turn', () => {
-      const decision = buildReasoningOptions({
-        modelData: {
-          providerName: 'openai',
-          modelId: 'gpt-5',
-          reasoning: { knob: 'effort', supportsMinimal: true },
-        },
-        signals: TRIVIAL,
-        effortFloorTier: 'high',
+    it('an undefined seed reproduces the pure-heuristic decision (additive only)', () => {
+      const base = buildReasoningOptions({ modelData: GPT5, signals: HARD });
+      const seedless = buildReasoningOptions({
+        modelData: GPT5,
+        signals: { ...HARD, effortSeed: undefined, creativitySeed: undefined },
       });
-      expect(decision.tier).toBe('high');
+      expect(seedless.tier).toBe(base.tier);
+      expect(seedless.providerOptions).toEqual(base.providerOptions);
     });
 
-    it('caps the thinking budget by the per-class budgetCap', () => {
-      const decision = buildReasoningOptions({
-        modelData: {
-          providerName: 'anthropic',
-          modelId: 'anthropic/claude-sonnet-4',
-          reasoning: { knob: 'budgetTokens', minBudgetTokens: 1024 },
-          maxOutputTokens: 64000,
-        },
+    it('a creativity seed shifts the sampling temperature on a non-reasoning model', () => {
+      const sampling = {
+        providerName: 'openai',
+        modelId: 'openai/gpt-4o',
+      };
+      const precise = buildReasoningOptions({
+        modelData: sampling,
         signals: {
           kind: 'chat',
-          promptText:
-            'Refactor and analyze this large module thoroughly. '.repeat(60),
+          promptText: 'summarize this',
+          creativitySeed: 'precise',
         },
-        budgetCaps: { hard: 4096, medium: 4096, easy: 4096 },
       });
-      const thinking = (
-        decision.providerOptions?.anthropic as Record<string, unknown>
-      )?.thinking as { budget_tokens: number };
-      expect(thinking.budget_tokens).toBeLessThanOrEqual(4096);
-    });
-
-    it('honors a custom temperature range for sampling models', () => {
-      const decision = buildReasoningOptions({
-        modelData: { providerName: 'openai', modelId: 'openai/gpt-4o' },
-        signals: { kind: 'chat', promptText: 'write a creative poem' },
-        creativityOverride: 1,
-        temperatureRange: { min: 0.2, max: 0.5 },
-      });
-      // creativity=1 maps to the top of the band → 0.5.
-      expect(decision.temperature).toBe(0.5);
-    });
-
-    it('is identical to no-tuning when no bounds are set', () => {
-      const base = buildReasoningOptions({
-        modelData: {
-          providerName: 'openai',
-          modelId: 'gpt-5',
-          reasoning: { knob: 'effort', supportsMinimal: true },
-        },
-        signals: HARD,
-      });
-      const tuned = buildReasoningOptions({
-        modelData: {
-          providerName: 'openai',
-          modelId: 'gpt-5',
-          reasoning: { knob: 'effort', supportsMinimal: true },
+      const creative = buildReasoningOptions({
+        modelData: sampling,
+        signals: {
+          kind: 'chat',
+          promptText: 'summarize this',
+          creativitySeed: 'creative',
         },
-        signals: HARD,
-        qualityProfile: 'balanced',
       });
-      expect(tuned.tier).toBe(base.tier);
-      expect(tuned.providerOptions).toEqual(base.providerOptions);
+      expect(creative.temperature).toBeGreaterThan(precise.temperature ?? 0);
     });
   });
 });
diff --git a/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.ts b/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.ts
index 6dc5d1c459..059dc11d2c 100644
--- a/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/build_reasoning_options.ts
@@ -22,19 +22,14 @@ import {
   type ReasoningCapability,
   type ReasoningCapabilityConfig,
 } from './capability';
-import { adjustTarget, type QualityProfile } from './controller';
+import { adjustTarget } from './controller';
 import { decideTemperature } from './generation_params';
 import { scoreDifficulty, type DifficultySignals } from './signals';
 import {
   adaptiveDifficultyThresholds,
   classFromIntensity,
-  maxTier,
-  minTier,
-  TIER_BUDGET_TOKENS,
-  TIER_RANK,
   type DifficultyClass,
   type ReasoningState,
-  type ReasoningTarget,
   type ReasoningTier,
 } from './types';
 
@@ -66,37 +61,6 @@ export interface BuildReasoningOptionsInput {
    * from the org's accumulated learning from turn one.
    */
   profile?: ReasoningState;
-  /**
-   * Composer-sourced FIXED reasoning tier. When set, the adaptive controller
-   * is bypassed and this tier (with its canonical budget) is used directly.
-   * `undefined` keeps the governor in charge.
-   */
-  effortOverride?: ReasoningTier;
-  /**
-   * Composer-sourced FIXED creativity score in [0, 1]. Overrides the
-   * difficulty-scaled creativity fed to `decideTemperature` (which still
-   * drops temperature for reasoning-only models). `undefined` = adaptive.
-   */
-  creativityOverride?: number;
-  /**
-   * Agent-configured FLOOR — the adaptive controller may not settle below this
-   * tier. `undefined` = no floor beyond the per-turn hard floor (Layer A).
-   */
-  effortFloorTier?: ReasoningTier;
-  /**
-   * Agent-configured CEILING — the adaptive controller may not exceed this
-   * tier. Applied after the floor (the schema enforces floor ≤ ceiling).
-   */
-  effortCeilingTier?: ReasoningTier;
-  /**
-   * Agent-configured per-difficulty-class hard cap on the thinking-token
-   * budget (budgetTokens-knob models). `undefined` = no extra cap.
-   */
-  budgetCaps?: Partial<Record<DifficultyClass, number>>;
-  /** Agent-configured temperature band override for `decideTemperature`. */
-  temperatureRange?: { min?: number; max?: number };
-  /** Agent-configured quality-feedback preset for the controller deadbands. */
-  qualityProfile?: QualityProfile;
 }
 
 export interface ReasoningDecision {
@@ -120,20 +84,7 @@ export interface ReasoningDecision {
 export function buildReasoningOptions(
   input: BuildReasoningOptionsInput,
 ): ReasoningDecision {
-  const {
-    modelData,
-    baseProviderOptions,
-    signals,
-    state,
-    profile,
-    effortOverride,
-    creativityOverride,
-    effortFloorTier,
-    effortCeilingTier,
-    budgetCaps,
-    temperatureRange,
-    qualityProfile,
-  } = input;
+  const { modelData, baseProviderOptions, signals, state, profile } = input;
 
   const difficulty = scoreDifficulty(signals);
   const capability = resolveReasoningCapability(modelData);
@@ -151,29 +102,19 @@ export function buildReasoningOptions(
     adaptiveDifficultyThresholds(thresholdSource),
   );
 
-  // Fixed effort profile bypasses the adaptive controller entirely; otherwise
-  // use the controller-adjusted target (when steerable) / raw prior.
-  const rawTarget = effortOverride
-    ? { tier: effortOverride, budgetTokens: TIER_BUDGET_TOKENS[effortOverride] }
-    : capability
-      ? adjustTarget(
-          difficulty.target,
-          difficulty.floorTier,
-          difficultyClass,
-          state,
-          capability,
-          profile,
-          qualityProfile,
-        )
-      : difficulty.target;
-
-  // Apply the agent-configured floor/ceiling band and per-class budget cap. The
-  // controller still adapts WITHIN the band; the floor never undercuts Layer A.
-  const target = applyTuningBounds(rawTarget, {
-    effortFloorTier,
-    effortCeilingTier,
-    budgetCap: budgetCaps?.[difficultyClass],
-  });
+  // The governor is fully in charge: the controller-adjusted target when the
+  // model is steerable, else the Layer-A prior. (Any router effort/creativity
+  // hint already shaped `difficulty` inside `scoreDifficulty` as a prior.)
+  const target = capability
+    ? adjustTarget(
+        difficulty.target,
+        difficulty.floorTier,
+        difficultyClass,
+        state,
+        capability,
+        profile,
+      )
+    : difficulty.target;
 
   const { overlay, applied } = capability
     ? buildOverlay(target.tier, target.budgetTokens, capability, modelData)
@@ -181,10 +122,9 @@ export function buildReasoningOptions(
 
   const reasoningActive = applied && target.tier !== 'off';
   const temperature = decideTemperature(
-    creativityOverride ?? difficulty.creativity,
+    difficulty.creativity,
     capability,
     reasoningActive,
-    temperatureRange,
   );
 
   const providerOptions = asProviderOptions(
@@ -205,40 +145,6 @@ export function buildReasoningOptions(
   };
 }
 
-/**
- * Apply the per-agent effort floor/ceiling and per-class budget cap to a target.
- * Ceiling is applied first, then the floor (floor wins on conflict; the schema
- * already enforces floor ≤ ceiling). Tier and budget are kept consistent.
- */
-function applyTuningBounds(
-  target: ReasoningTarget,
-  bounds: {
-    effortFloorTier?: ReasoningTier;
-    effortCeilingTier?: ReasoningTier;
-    budgetCap?: number;
-  },
-): ReasoningTarget {
-  let { tier, budgetTokens } = target;
-
-  if (bounds.effortCeilingTier) {
-    tier = minTier(tier, bounds.effortCeilingTier);
-    if (TIER_RANK[tier] < TIER_RANK[target.tier]) {
-      budgetTokens = Math.min(budgetTokens, TIER_BUDGET_TOKENS[tier]);
-    }
-  }
-  if (bounds.effortFloorTier) {
-    tier = maxTier(tier, bounds.effortFloorTier);
-    budgetTokens = Math.max(
-      budgetTokens,
-      TIER_BUDGET_TOKENS[bounds.effortFloorTier],
-    );
-  }
-  if (bounds.budgetCap != null && bounds.budgetCap > 0) {
-    budgetTokens = Math.min(budgetTokens, bounds.budgetCap);
-  }
-  return { tier, budgetTokens };
-}
-
 function buildOverlay(
   tier: ReasoningTier,
   budgetTokens: number,
diff --git a/services/platform/convex/lib/agent_response/reasoning/controller.test.ts b/services/platform/convex/lib/agent_response/reasoning/controller.test.ts
index bcbbfdcc02..b7f6c8f84c 100644
--- a/services/platform/convex/lib/agent_response/reasoning/controller.test.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/controller.test.ts
@@ -501,6 +501,70 @@ describe('adjustTarget — effort bandit (tier hysteresis)', () => {
   });
 });
 
+describe('adjustTarget — anti-oscillation + cold-quality (P1-B / P1-C)', () => {
+  it('resists a marginal tier reversal once a tier is settled (lastTier guard)', () => {
+    // One retry → underResourcedEma = 0.5 (= underHi exactly): the bandit would
+    // bump low→medium, but if we last settled on 'low' and the signal is not
+    // decisively past the deadband, the guard holds at 'low'.
+    const mildlyUnder: ReasoningOutcome = {
+      difficultyClass: 'medium',
+      budgetTokens: 0,
+      selfTruncates: false,
+      retried: true,
+    };
+    const settledLow = recordOutcome(undefined, {
+      ...mildlyUnder,
+      chosenTier: 'low',
+    });
+    expect(adjustTarget(low, 'off', 'medium', settledLow, EFFORT).tier).toBe(
+      'low',
+    );
+    // Same signal with no settled lastTier bumps as the bandit normally would.
+    const noLast = recordOutcome(undefined, mildlyUnder);
+    expect(adjustTarget(low, 'off', 'medium', noLast, EFFORT).tier).toBe(
+      'medium',
+    );
+  });
+
+  it('needs two usage samples before trusting estimate on a self-trunc model (P1-B)', () => {
+    const lowUsage: ReasoningOutcome = {
+      difficultyClass: 'hard',
+      reasoningTokens: 1200,
+      budgetTokens: TIER_BUDGET_TOKENS.high,
+      selfTruncates: true,
+      finishReason: 'stop',
+    };
+    // One sample: still trust the (high) prior, not the single low reading.
+    const one = recordOutcome(undefined, lowUsage);
+    expect(adjustTarget(high, 'off', 'hard', one, SELF_TRUNC).tier).toBe(
+      'high',
+    );
+    // Two samples: estimate from usage now engages and drops below the prior.
+    const two = recordOutcome(one, lowUsage);
+    expect(
+      adjustTarget(high, 'off', 'hard', two, SELF_TRUNC).budgetTokens,
+    ).toBeLessThan(high.budgetTokens);
+  });
+
+  it('lifts a self-trunc off-class on sustained low quality with no usage (P1-C)', () => {
+    // Off-turns record a quality score but NO reasoning-token sample, so the
+    // estimate path stays cold — a deadlock the cold-quality bump breaks.
+    const badOff: ReasoningOutcome = {
+      difficultyClass: 'easy',
+      budgetTokens: 0,
+      selfTruncates: true,
+      qualityScore: 0.1,
+      chosenTier: 'off',
+    };
+    const bad = recordMany(6, badOff);
+    expect(adjustTarget(off, 'off', 'easy', bad, SELF_TRUNC).tier).toBe('low');
+
+    // A well-scoring off-class is left at off (no needless escalation).
+    const good = recordMany(6, { ...badOff, qualityScore: 0.95 });
+    expect(adjustTarget(off, 'off', 'easy', good, SELF_TRUNC).tier).toBe('off');
+  });
+});
+
 describe('adjustTarget — hierarchical profile (warm start)', () => {
   const selfTrunc = (reasoningTokens: number): ReasoningOutcome => ({
     difficultyClass: 'hard',
diff --git a/services/platform/convex/lib/agent_response/reasoning/controller.ts b/services/platform/convex/lib/agent_response/reasoning/controller.ts
index d70053ffaa..a55a5e0ace 100644
--- a/services/platform/convex/lib/agent_response/reasoning/controller.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/controller.ts
@@ -71,10 +71,15 @@ const WASTE_BUDGET_FRACTION = 0.6;
 const WASTE_OUTPUT_FLOOR = 256;
 // The controller may not exceed this multiple of the per-turn prior.
 const BAND_MAX = 1.5;
-// Samples required before the controller adjusts a bucket at all.
-const MIN_SAMPLES_TO_TRUST = 1;
+// Samples required before the controller trusts usage to estimate a budget. Two
+// (not one) so a single noisy reasoning-token reading can't swing the estimate;
+// the org-wide profile warm-start already covers a fresh thread in a known org.
+const MIN_SAMPLES_TO_TRUST = 2;
 // Samples required before an effort-tier bucket may be trimmed below the prior.
 const MIN_N_TO_TRIM = 2;
+// Anti-oscillation: a reversing tier move must clear its deadband by this margin
+// before it may flip the tier the controller last settled on (see adjustTarget).
+const HYSTERESIS_MARGIN = 0.15;
 // Cap on how much a cross-thread profile counts as evidence, so a thread's own
 // observations eventually dominate its inherited (org/model) warm start.
 const PROFILE_SAMPLE_CAP = 20;
@@ -103,13 +108,19 @@ export interface ReasoningOutcome {
    * (e.g. tool-only turns) — the EMA simply isn't updated.
    */
   qualityScore?: number;
+  /**
+   * The reasoning tier the controller settled on for this turn. Persisted to the
+   * bucket's `lastTier` to drive the effort-tier anti-oscillation guard next
+   * turn. Omit when unknown — the prior `lastTier` is then preserved.
+   */
+  chosenTier?: ReasoningTier;
 }
 
 /**
- * Quality-feedback tuning, selected per agent via `responseTuning.qualityProfile`.
- * `balanced` reproduces the original deadband constants exactly (so an agent
- * without a profile behaves identically to before). `strict` reasons more
- * readily and trims less; `lenient` is the opposite.
+ * Quality-feedback tuning preset for the controller deadbands. The governor
+ * always runs `balanced` now (the manual per-agent `qualityProfile` override was
+ * removed); `strict`/`lenient` are retained as the preset vocabulary for the
+ * deadband table and tests. `balanced` is `adjustTarget`'s default.
  */
 export type QualityProfile = 'lenient' | 'balanced' | 'strict';
 
@@ -131,6 +142,12 @@ const QUALITY_DEADBANDS: Record<QualityProfile, QualityDeadbands> = {
 
 // How strongly a quality shortfall lifts the effective under-resourced signal.
 const QUALITY_UNDER_WEIGHT = 0.5;
+// Quality-shortfall fraction at/above which a self-truncating class with NO
+// usage samples (e.g. parked at `off`/`low`, so it never produced thinking
+// tokens) is nudged up one tier — so the model gets to think and reveal its real
+// need instead of being deadlocked by a too-low prior. Conservative: only fires
+// on a clear, sustained quality complaint (qualityEma well below the target).
+const QUALITY_COLD_BUMP = 0.25;
 
 function welfordUpdate(b: BucketStats, x: number): BucketStats {
   const count = b.count + 1;
@@ -199,7 +216,10 @@ export function recordOutcome(
     ? ema(priorQualityEma, clamp01(q))
     : priorQualityEma;
 
-  bucket = { ...bucket, underResourcedEma, wastefulEma, qualityEma };
+  // Remember the tier we settled on (anti-oscillation guard); preserve the
+  // prior when this turn didn't report one (e.g. a non-steerable / tool turn).
+  const lastTier = outcome.chosenTier ?? bucket.lastTier;
+  bucket = { ...bucket, underResourcedEma, wastefulEma, qualityEma, lastTier };
 
   // Cross-class Welford over the difficulty intensity (self-calibration input).
   let { intensityCount, intensityMean, intensityM2 } = base;
@@ -246,6 +266,8 @@ interface CombinedView {
   wastefulEma: number;
   /** Response-quality EMA from the level with evidence (thread preferred). */
   qualityEma: number;
+  /** Last settled tier from the level with evidence (anti-oscillation guard). */
+  lastTier?: ReasoningTier;
 }
 
 /**
@@ -291,6 +313,10 @@ function combineBuckets(
   const qualityEma = threadBucket
     ? (threadBucket.qualityEma ?? 1)
     : (profileBucket?.qualityEma ?? 1);
+  // Prefer the thread's own settled tier; fall back to the inherited profile
+  // when the thread bucket exists but hasn't recorded a tier yet (mirrors the
+  // `?? default` coalescing the sibling EMAs above use).
+  const lastTier = threadBucket?.lastTier ?? profileBucket?.lastTier;
   return {
     mean,
     std,
@@ -298,6 +324,7 @@ function combineBuckets(
     underResourcedEma,
     wastefulEma,
     qualityEma,
+    lastTier,
   };
 }
 
@@ -341,9 +368,23 @@ export function adjustTarget(
   );
 
   if (capability.selfTruncates) {
-    // Need at least one token sample to estimate the budget from usage;
-    // otherwise trust the prior (floored).
+    // Not enough token samples to estimate the budget from usage yet. Trust the
+    // (floored) prior — UNLESS the class has been answering poorly with no way
+    // to learn: a self-truncating model parked at a low tier never produces
+    // thinking-token samples, so without this nudge a genuinely-underpowered
+    // class could stay deadlocked. A clear, sustained quality shortfall bumps it
+    // one tier so the model gets to think and reveal its real need next turn.
     if (view.count < MIN_SAMPLES_TO_TRUST) {
+      if (
+        qualityShortfall >= QUALITY_COLD_BUMP &&
+        TIER_RANK[prior.tier] < TIER_RANK.high
+      ) {
+        const bumped = maxTier(
+          tierFromRank(TIER_RANK[prior.tier] + 1),
+          floorTier,
+        );
+        return { tier: bumped, budgetTokens: TIER_BUDGET_TOKENS[bumped] };
+      }
       return clampToFloor(prior, floorTier, floorBudget);
     }
     // Usage reveals the true need: estimate it plus an uncertainty headroom,
@@ -382,7 +423,28 @@ export function adjustTarget(
     rank -= 1;
   }
   rank = Math.max(TIER_RANK[floorTier], Math.min(rank, TIER_RANK.high));
-  const tier = maxTier(tierFromRank(rank), floorTier);
+  let tier = maxTier(tierFromRank(rank), floorTier);
+
+  // Anti-oscillation: once the class has settled on a tier, don't flip back the
+  // other way on a marginal signal — a class hovering on a seam would otherwise
+  // wobble every turn (the reason someone reached for a manual effort floor).
+  // Hold at the last tier unless the reversing signal clears its deadband by
+  // HYSTERESIS_MARGIN. Never holds below the floor; strong starvation (effUnder
+  // ≥ UNDER_RESOURCED_STRONG) always escalates, so a starved class still jumps.
+  const lastTier = view.lastTier;
+  if (
+    lastTier &&
+    lastTier !== tier &&
+    TIER_RANK[lastTier] >= TIER_RANK[floorTier]
+  ) {
+    const movingUp = TIER_RANK[tier] > TIER_RANK[lastTier];
+    const decisive = movingUp
+      ? effUnder >= UNDER_RESOURCED_STRONG ||
+        effUnder >= db.underHi + HYSTERESIS_MARGIN
+      : effUnder < db.underLo - HYSTERESIS_MARGIN ||
+        view.wastefulEma >= db.wasteHi + HYSTERESIS_MARGIN;
+    if (!decisive) tier = lastTier;
+  }
   return { tier, budgetTokens: TIER_BUDGET_TOKENS[tier] };
 }
 
diff --git a/services/platform/convex/lib/agent_response/reasoning/generation_params.ts b/services/platform/convex/lib/agent_response/reasoning/generation_params.ts
index cee714202e..e61b89f708 100644
--- a/services/platform/convex/lib/agent_response/reasoning/generation_params.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/generation_params.ts
@@ -20,22 +20,21 @@ const DEFAULT_TEMP_MAX = 0.9;
  *  - self-truncating thinking (Anthropic) requires temperature unset/1 *while
  *    thinking is enabled* (it's fine to set when reasoning is off).
  *
- * `range` lets a per-agent `responseTuning.temperatureRange` override the
- * default [0.4, 0.9] band; partial ranges fall back to the default endpoint.
- * Callers still let an explicit per-request temperature win over this default.
+ * Interpolates the default [0.4, 0.9] band by the turn's creativity signal
+ * (which a router creativity hint may already have shaped upstream). Callers
+ * still let an explicit per-request temperature win over this default.
  */
 export function decideTemperature(
   creativity: number,
   capability: ReasoningCapability | null,
   reasoningActive: boolean,
-  range?: { min?: number; max?: number },
 ): number | undefined {
   if (capability) {
     if (capability.knob === 'effort') return undefined;
     if (capability.selfTruncates && reasoningActive) return undefined;
   }
-  const min = range?.min ?? DEFAULT_TEMP_MIN;
-  const max = Math.max(min, range?.max ?? DEFAULT_TEMP_MAX);
-  const t = min + clamp01(creativity) * (max - min);
+  const t =
+    DEFAULT_TEMP_MIN +
+    clamp01(creativity) * (DEFAULT_TEMP_MAX - DEFAULT_TEMP_MIN);
   return Math.round(t * 100) / 100;
 }
diff --git a/services/platform/convex/lib/agent_response/reasoning/signals.test.ts b/services/platform/convex/lib/agent_response/reasoning/signals.test.ts
index 5ed3ce3a08..801889f893 100644
--- a/services/platform/convex/lib/agent_response/reasoning/signals.test.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/signals.test.ts
@@ -98,4 +98,65 @@ describe('scoreDifficulty', () => {
     expect(['off', 'low', 'medium']).toContain(borderline.target.tier);
     expect(borderline.intensity).toBeLessThan(1);
   });
+
+  it('does not damp a terse HARD rework deep in a thread (P1-A)', () => {
+    // A short message deep in a thread WITH code is a rework, not a casual
+    // follow-up — the follow-up penalty must not pull it below its code floor.
+    const rework = scoreDifficulty({
+      kind: 'chat',
+      promptText: 'now redo it in Rust:\n```rs\nfn main(){}\n```',
+      historyMessageCount: 12,
+    });
+    expect(rework.floorTier).toBe('medium');
+    expect(['medium', 'high']).toContain(rework.target.tier);
+    // A plain short follow-up in the same deep thread still damps to easy.
+    const casual = scoreDifficulty({
+      kind: 'chat',
+      promptText: 'and the next one?',
+      historyMessageCount: 12,
+    });
+    expect(['off', 'low']).toContain(casual.target.tier);
+  });
+
+  it('blends the prior toward a router effort seed (P0-A)', () => {
+    // A lexically-plain prompt the heuristic rates low, lifted by a high seed.
+    const plain = 'walk me through the options here';
+    const unseeded = scoreDifficulty({ kind: 'chat', promptText: plain });
+    const seeded = scoreDifficulty({
+      kind: 'chat',
+      promptText: plain,
+      effortSeed: 'high',
+    });
+    expect(seeded.intensity).toBeGreaterThan(unseeded.intensity);
+  });
+
+  it('is byte-identical to the pure heuristic when no seed is given (P0-A)', () => {
+    const signals = {
+      kind: 'chat' as const,
+      promptText: 'Please analyze and evaluate this rigorously.',
+      historyMessageCount: 3,
+    };
+    const base = scoreDifficulty(signals);
+    const seedless = scoreDifficulty({
+      ...signals,
+      effortSeed: undefined,
+      creativitySeed: undefined,
+    });
+    expect(seedless).toEqual(base);
+  });
+
+  it('blends creativity toward a router creativity seed (P0-A)', () => {
+    const plain = 'tell me about cats';
+    const precise = scoreDifficulty({
+      kind: 'chat',
+      promptText: plain,
+      creativitySeed: 'precise',
+    });
+    const creative = scoreDifficulty({
+      kind: 'chat',
+      promptText: plain,
+      creativitySeed: 'creative',
+    });
+    expect(creative.creativity).toBeGreaterThan(precise.creativity);
+  });
 });
diff --git a/services/platform/convex/lib/agent_response/reasoning/signals.ts b/services/platform/convex/lib/agent_response/reasoning/signals.ts
index a8593a12f3..c0299c13a6 100644
--- a/services/platform/convex/lib/agent_response/reasoning/signals.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/signals.ts
@@ -52,6 +52,19 @@ export interface DifficultySignals {
   agentType?: string;
   /** Count of prior messages in the thread (follow-up detection). */
   historyMessageCount?: number;
+  /**
+   * Coarse reasoning-effort seed from the Auto router (low/medium/high). Blends
+   * the heuristic difficulty prior toward this hint (a PRIOR, weight {@link
+   * SEED_WEIGHT}) — never a hard override; the online controller still refines
+   * from observed usage. Undefined = heuristic prior only (pinned agents and
+   * non-Auto turns), so behaviour is byte-identical to before.
+   */
+  effortSeed?: 'low' | 'medium' | 'high';
+  /**
+   * Coarse creativity seed from the Auto router (precise/balanced/creative).
+   * Blends the creativity signal feeding the temperature governor, same weight.
+   */
+  creativitySeed?: 'precise' | 'balanced' | 'creative';
 }
 
 /**
@@ -165,6 +178,21 @@ const OFF_INTENSITY = 0.12;
 const PRIOR_BUDGET_GAMMA = 1.4;
 const PRIOR_BUDGET_MAX = TIER_BUDGET_TOKENS.high;
 
+// How far the Auto router's coarse hint pulls the heuristic prior toward it — a
+// blend, not an override (the online controller still refines from observed
+// usage). Representative prior intensity / creativity score per hint level.
+const SEED_WEIGHT = 0.5;
+const SEED_INTENSITY: Record<'low' | 'medium' | 'high', number> = {
+  low: 0.25,
+  medium: 0.55,
+  high: 0.85,
+};
+const SEED_CREATIVITY: Record<'precise' | 'balanced' | 'creative', number> = {
+  precise: 0,
+  balanced: 0.5,
+  creative: 1,
+};
+
 /**
  * Score a turn's reasoning difficulty into a continuous intensity, a creativity
  * signal, a coarse class, a canonical target, and a hard floor.
@@ -234,7 +262,12 @@ export function scoreDifficulty(signals: DifficultySignals): DifficultyResult {
   // ~2 turns and saturates by ~8; shortness fades out by ~40 tokens.
   const historyDepth = clamp01(((signals.historyMessageCount ?? 0) - 2) / 6);
   const shortness = 1 - clamp01(tokens / 40);
-  const followUpScore = historyDepth * shortness;
+  // A genuinely hard turn is never damped as a follow-up: a terse rework deep in
+  // a thread ("now redo it in Rust", "make it handle the edge cases") carries
+  // code / hard-verb / math signal and must score on its content, not be pulled
+  // down for being short. Plain short follow-ups still damp.
+  const followUpScore =
+    density > 0 || hardStrength > 0 || hasMath ? 0 : historyDepth * shortness;
 
   const z =
     W.bias +
@@ -266,13 +299,30 @@ export function scoreDifficulty(signals: DifficultySignals): DifficultyResult {
     !isTrivial;
   if (longContextQa) intensity *= 0.85;
 
+  // Router seed (Auto mode only): blend the heuristic prior toward the LLM's
+  // coarse effort read. The router actually read the message, so this fixes
+  // cold-start and the heuristic's semantic blind spots (a terse-but-hard ask)
+  // on turn one; the online controller then refines from observed usage, so a
+  // wrong hint self-corrects. Absent = byte-identical to the pure heuristic.
+  if (signals.effortSeed) {
+    intensity =
+      (1 - SEED_WEIGHT) * intensity +
+      SEED_WEIGHT * SEED_INTENSITY[signals.effortSeed];
+  }
+
   // Creativity: precise/deterministic work pulls temperature down, open-ended
   // generation pulls it up. Code / math / analytical intent are precise.
   const analytical =
     hasAnalyticalVerb || density > 0 || hasMath || hardStrength > 0;
-  const creativity = clamp01(
+  let creativity = clamp01(
     0.5 + 0.7 * creativeStrength - (analytical ? 0.35 : 0) - 0.2 * easyStrength,
   );
+  if (signals.creativitySeed) {
+    creativity = clamp01(
+      (1 - SEED_WEIGHT) * creativity +
+        SEED_WEIGHT * SEED_CREATIVITY[signals.creativitySeed],
+    );
+  }
 
   // Hard floors: a genuinely hard turn can't be starved by history.
   let floorTier: ReasoningTier = 'off';
diff --git a/services/platform/convex/lib/agent_response/reasoning/types.ts b/services/platform/convex/lib/agent_response/reasoning/types.ts
index a86e8cf2c8..51e990d8fa 100644
--- a/services/platform/convex/lib/agent_response/reasoning/types.ts
+++ b/services/platform/convex/lib/agent_response/reasoning/types.ts
@@ -72,6 +72,14 @@ export interface BucketStats {
    * coalesce to a neutral 1.0 = "no quality complaint yet").
    */
   qualityEma?: number;
+  /**
+   * The reasoning tier the controller last settled on for this class. Drives the
+   * effort-tier bandit's anti-oscillation: a class hovering on a tier seam may
+   * not flip back the other way on EMA noise unless the reversing signal clears
+   * its deadband by a margin. Optional (legacy rows / pre-decision buckets omit
+   * it; absence disables the guard, so behaviour matches the unsmoothed bandit).
+   */
+  lastTier?: ReasoningTier;
 }
 
 /**
diff --git a/services/platform/convex/lib/agent_response/types.ts b/services/platform/convex/lib/agent_response/types.ts
index fed7fd1d86..0f19adabaa 100644
--- a/services/platform/convex/lib/agent_response/types.ts
+++ b/services/platform/convex/lib/agent_response/types.ts
@@ -6,7 +6,10 @@ import type { SharedV3ProviderOptions } from '@ai-sdk/provider';
 import type { Agent } from '@convex-dev/agent';
 import type { ModelMessage } from 'ai';
 
-import type { ResponseTuningConfig } from '../../../lib/shared/schemas/agents';
+import type {
+  ResponseReasoningSeed,
+  ResponseStyleAdvice,
+} from '../../../lib/shared/response-tuning';
 import type { ActionCtx } from '../../_generated/server';
 import type { AutoRouteReason } from '../../streaming/validators';
 import type { FileAttachment } from '../attachments';
@@ -83,13 +86,18 @@ export interface GenerateResponseConfig {
    */
   reasoningCapability?: ReasoningCapabilityConfig;
   /**
-   * Per-agent response tuning (`agentConfig.responseTuning`). Drives the
-   * governor's fixed-effort / floor / ceiling / budget-cap / temperature-range
-   * / quality-profile inputs and the style/verbosity prompt fragments. Replaces
-   * the old per-message `reasoningOverride` path. Optional — absence = today's
-   * fully-adaptive behaviour.
+   * Prose-level response shaping (style/verbosity) the Auto router advised for
+   * this turn, rendered into the style/verbosity prompt fragment. Set ONLY in
+   * Auto mode; absent for pinned agents (tone comes from their instructions).
    */
-  responseTuning?: ResponseTuningConfig;
+  responseStyle?: ResponseStyleAdvice;
+  /**
+   * Coarse reasoning seed (effort/creativity) the Auto router advised for this
+   * turn. Fed to `buildReasoningOptions` as a PRIOR (blended into the difficulty
+   * score), never a hard override — the online controller still refines from
+   * observed usage. Set ONLY in Auto mode; absent = fully-heuristic prior.
+   */
+  routeSeed?: ResponseReasoningSeed;
   /**
    * Advisory reply-language hint from the Auto router (BCP-47 code or language
    * name). Inserted into the response-language directive's fallback chain just
diff --git a/services/platform/convex/lib/error_classification.test.ts b/services/platform/convex/lib/error_classification.test.ts
index e0251d70e5..f1cc5a1aeb 100644
--- a/services/platform/convex/lib/error_classification.test.ts
+++ b/services/platform/convex/lib/error_classification.test.ts
@@ -1,10 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import {
-  classifyError,
-  classifyProviderError,
-  NonRetryableError,
-} from './error_classification';
+import { classifyError, NonRetryableError } from './error_classification';
 
 describe('classifyError', () => {
   it('classifies 400 as non-retryable bad_request', () => {
@@ -50,101 +46,6 @@ describe('classifyError', () => {
   });
 });
 
-describe('classifyProviderError', () => {
-  it('returns model_not_found for 404 errors', () => {
-    const result = classifyProviderError({
-      status: 404,
-      message: 'Not found',
-    });
-    expect(result.errorType).toBe('model_not_found');
-    expect(result.userMessage).toContain('not found');
-  });
-
-  it('returns auth_failed for 401 errors', () => {
-    const result = classifyProviderError({
-      status: 401,
-      message: 'Unauthorized',
-    });
-    expect(result.errorType).toBe('auth_failed');
-    expect(result.userMessage).toContain('API key');
-  });
-
-  it('returns auth_failed for 403 errors', () => {
-    const result = classifyProviderError({
-      status: 403,
-      message: 'Forbidden',
-    });
-    expect(result.errorType).toBe('auth_failed');
-    expect(result.userMessage).toContain('access');
-  });
-
-  it('returns rate_limited for 429 errors', () => {
-    const result = classifyProviderError({
-      status: 429,
-      message: 'Rate limit exceeded',
-    });
-    expect(result.errorType).toBe('rate_limited');
-    expect(result.userMessage).toContain('rate limit');
-  });
-
-  it('returns bad_request for 400 errors', () => {
-    const result = classifyProviderError({
-      status: 400,
-      message: 'Invalid request',
-    });
-    expect(result.errorType).toBe('bad_request');
-  });
-
-  it('returns provider_error for 500+ errors', () => {
-    const result = classifyProviderError({
-      status: 502,
-      message: 'Bad gateway',
-    });
-    expect(result.errorType).toBe('provider_error');
-  });
-
-  it('returns model_not_found for "model not found" message regardless of status', () => {
-    const result = classifyProviderError({
-      message: 'Model "test/model" not found in any provider',
-    });
-    expect(result.errorType).toBe('model_not_found');
-  });
-
-  it('returns unknown for unrecognized errors', () => {
-    const result = classifyProviderError({
-      message: 'Something unexpected happened',
-    });
-    expect(result.errorType).toBe('unknown');
-  });
-
-  it('handles non-object errors gracefully', () => {
-    const result = classifyProviderError('string error');
-    expect(result.errorType).toBe('unknown');
-  });
-
-  it('handles null error gracefully', () => {
-    const result = classifyProviderError(null);
-    expect(result.errorType).toBe('unknown');
-  });
-
-  it('returns provider_error for 503 errors', () => {
-    const result = classifyProviderError({
-      status: 503,
-      message: 'Service unavailable',
-    });
-    expect(result.errorType).toBe('provider_error');
-    expect(result.userMessage).toContain('experiencing issues');
-  });
-
-  it('uses statusCode property when status is absent', () => {
-    const result = classifyProviderError({
-      statusCode: 429,
-      message: 'Rate limit',
-    });
-    expect(result.errorType).toBe('rate_limited');
-  });
-});
-
 describe('NonRetryableError', () => {
   it('preserves original error and reason', () => {
     const original = new Error('original');
diff --git a/services/platform/convex/lib/error_classification.ts b/services/platform/convex/lib/error_classification.ts
index 31927cbe2b..80edf9419d 100644
--- a/services/platform/convex/lib/error_classification.ts
+++ b/services/platform/convex/lib/error_classification.ts
@@ -230,105 +230,6 @@ export class NonRetryableError extends Error {
   }
 }
 
-/**
- * Provider error classification for user-facing messages.
- *
- * Maps HTTP status codes and error patterns to actionable descriptions
- * that tell the user what went wrong and what to do about it.
- */
-export interface ProviderErrorClassification {
-  errorType:
-    | 'model_not_found'
-    | 'auth_failed'
-    | 'rate_limited'
-    | 'bad_request'
-    | 'provider_error'
-    | 'unknown';
-  userMessage: string;
-}
-
-export function classifyProviderError(
-  error: unknown,
-): ProviderErrorClassification {
-  const isObject = (val: unknown): val is Record<string, unknown> =>
-    val !== null && typeof val === 'object';
-
-  const err = isObject(error) ? error : {};
-
-  const status =
-    typeof err.status === 'number'
-      ? err.status
-      : typeof err.statusCode === 'number'
-        ? err.statusCode
-        : undefined;
-  const message = (
-    typeof err.message === 'string' ? err.message : ''
-  ).toLowerCase();
-
-  // Check message-based patterns first (more specific than status code)
-  if (message.includes('model') && message.includes('not found')) {
-    return {
-      errorType: 'model_not_found',
-      userMessage:
-        'The selected model was not found on the provider. It may have been renamed or is not available.',
-    };
-  }
-
-  if (status === 404) {
-    return {
-      errorType: 'model_not_found',
-      userMessage:
-        'The selected model was not found on the provider. It may have been renamed or is not available.',
-    };
-  }
-
-  if (status === 401) {
-    return {
-      errorType: 'auth_failed',
-      userMessage:
-        'The API key is invalid or expired. Check your provider configuration.',
-    };
-  }
-
-  if (status === 403) {
-    return {
-      errorType: 'auth_failed',
-      userMessage:
-        'The API key does not have access to this model. Check your provider permissions.',
-    };
-  }
-
-  if (status === 429) {
-    return {
-      errorType: 'rate_limited',
-      userMessage:
-        'The rate limit was exceeded for this model. Try again later or switch to a different model.',
-    };
-  }
-
-  if (status === 400) {
-    return {
-      errorType: 'bad_request',
-      userMessage:
-        'The model rejected the request. This may be a compatibility issue with the current tools or message format.',
-    };
-  }
-
-  if (status !== undefined && status >= 500) {
-    return {
-      errorType: 'provider_error',
-      userMessage:
-        'The model provider is experiencing issues. Try again later or switch to a different model.',
-    };
-  }
-
-  return {
-    errorType: 'unknown',
-    userMessage:
-      'An unexpected error occurred. Try again or switch to a different model.',
-  };
-}
-
 /**
  * Wraps an error based on its classification.
  * Non-retryable errors are wrapped in NonRetryableError.
diff --git a/services/platform/convex/lib/prompts/registry/entries/routing.ts b/services/platform/convex/lib/prompts/registry/entries/routing.ts
index 3bd32e825b..dda6396c70 100644
--- a/services/platform/convex/lib/prompts/registry/entries/routing.ts
+++ b/services/platform/convex/lib/prompts/registry/entries/routing.ts
@@ -21,12 +21,14 @@ export const routerScaffoldFooterEntry: PromptEntry = {
   required: ['defaultSlug'],
   usedBy: ['agents/auto_route_helpers.ts:buildRouterInstructions'],
   template: `Reply with ONLY a single-line JSON object. The "slug" field is REQUIRED and must be one of the slugs above. All other fields are OPTIONAL — include one only when the message gives a clear signal, and omit it otherwise:
-{"slug":"<one-of-the-slugs-above>","language":"<BCP-47 code or language name for the reply, e.g. fr, de, en — omit unless the intended reply language is clear>","style":"concise|detailed|formal|friendly","verbosity":"terse|normal|verbose","capabilities":["<capability slug the message needs>"]}
+{"slug":"<one-of-the-slugs-above>","language":"<BCP-47 code or language name for the reply, e.g. fr, de, en — omit unless the intended reply language is clear>","style":"concise|detailed|formal|friendly","verbosity":"terse|normal|verbose","effort":"low|medium|high","creativity":"precise|balanced|creative","capabilities":["<capability slug the message needs>"]}
 
 Guidance:
 - "slug": pick the specialist whose description or tools match the request, even when the general-purpose assistant could also handle it — a translation request goes to a translator, a coding request to a coder. The general assistant is the LAST resort: use "{{defaultSlug}}" only when no assistant is a good match (e.g. small talk) or several match equally well.
 - "language": set only the reply language the user evidently wants; omit for short greetings, code, or ambiguous input.
 - "style"/"verbosity": advise the response shape the message calls for (e.g. a quick factual question → concise/terse; "explain in detail" → detailed/verbose). Omit when neutral.
+- "effort": how much step-by-step reasoning THIS message needs — "low" for greetings, lookups, simple rewrites; "medium" for typical multi-part questions; "high" for genuinely hard analysis, debugging, multi-step problem-solving, or careful reworks (even when phrased briefly). Omit when unsure.
+- "creativity": "precise" for factual/code/extraction answers, "creative" for brainstorming/writing/ideation, "balanced" otherwise. Omit when unsure.
 - "capabilities": list only the capability slugs the chosen assistant needs for THIS message (from the assistant's tools above); omit when none are needed.`,
 };
 
diff --git a/services/platform/convex/login_attempts/internal_mutations.ts b/services/platform/convex/login_attempts/internal_mutations.ts
index 2fe112c62b..9a414f809d 100644
--- a/services/platform/convex/login_attempts/internal_mutations.ts
+++ b/services/platform/convex/login_attempts/internal_mutations.ts
@@ -222,6 +222,7 @@ export const recordFailure = internalMutation({
         // audit-pepper rotation or email change. Without this, rows
         // written under one pepper become unmatchable after rotation.
         subjectUserId: user.userId,
+        link: { kind: 'security-monitoring' },
       });
     }
 
diff --git a/services/platform/convex/node_only/sandbox/helpers/session_client.ts b/services/platform/convex/node_only/sandbox/helpers/session_client.ts
index 5976fa4577..caec313413 100644
--- a/services/platform/convex/node_only/sandbox/helpers/session_client.ts
+++ b/services/platform/convex/node_only/sandbox/helpers/session_client.ts
@@ -70,6 +70,34 @@ function getSpawnerUrl(): string {
   return process.env.SANDBOX_URL ?? 'http://localhost:8003';
 }
 
+/**
+ * Resolve the spawner URL for a SPECIFIC blue-green colour, so a session op
+ * reaches the exact colour the session lives on even after a deploy flip moved
+ * the bare `sandbox` alias to the new colour (and lingered the old one). Mirrors
+ * spawner_client.ts's `spawnerUrlForColor`. `null`/empty colour (single-colour
+ * dev, or a non-`sandbox` docker host) falls back to the bare URL — today's
+ * behaviour, so callers that don't yet pass a colour are unaffected.
+ */
+function spawnerUrlForColor(color: string | null | undefined): string {
+  const base = getSpawnerUrl();
+  if (!color) return base;
+  try {
+    const u = new URL(base);
+    if (u.hostname !== 'sandbox') return base; // dev/loopback → no per-colour host
+    return `${u.protocol}//sandbox-${color}:${u.port || '8003'}`;
+  } catch {
+    return base;
+  }
+}
+
+/** The blue-green colour the spawner reported for a session at create, or null
+ * in single-colour mode. Persisted on the session row so later ops route to the
+ * right (possibly-lingering) colour. */
+export interface SessionCreateResult {
+  session: SessionInfo;
+  spawnerColor: string | null;
+}
+
 function getSpawnerToken(): string | null {
   // Trim so a whitespace-only token is treated as unset — must match the
   // server (sandbox config.ts) and spawner_client trim or a padded token would
@@ -153,10 +181,15 @@ const IDLE_READ_TIMEOUT_MS = Number(
   process.env.EXTERNAL_AGENT_IDLE_READ_MS ?? 60_000,
 );
 
-/** POST /v1/sessions — create + wait for runnerd ready. Throws on 4xx/5xx. */
+/**
+ * POST /v1/sessions — create + wait for runnerd ready. Throws on 4xx/5xx.
+ * Targets the bare `sandbox` alias (a create must land on the ACTIVE colour),
+ * and returns the colour the spawner reported via `X-Sandbox-Color` so the
+ * caller can persist it for colour-routed follow-up ops.
+ */
 export async function sessionCreate(
   body: SessionCreateBody,
-): Promise<SessionInfo> {
+): Promise<SessionCreateResult> {
   const path = '/v1/sessions';
   const bodyJson = JSON.stringify(body);
   const res = await fetch(`${getSpawnerUrl()}${path}`, {
@@ -173,16 +206,22 @@ export async function sessionCreate(
   }
   // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
   const parsed = (await res.json()) as { session: SessionInfo };
-  return parsed.session;
+  return {
+    session: parsed.session,
+    spawnerColor: res.headers.get('x-sandbox-color'),
+  };
 }
 
 /** DELETE /v1/sessions/:id — idempotent teardown. */
 /** GET /v1/sessions/:id — is the session alive spawner-side? `false` ONLY on
  * a definitive 404 (the phantom-session signal); transport errors throw so a
  * spawner blip is never misread as "session gone". */
-export async function sessionIsAlive(sessionId: string): Promise<boolean> {
+export async function sessionIsAlive(
+  sessionId: string,
+  spawnerColor?: string | null,
+): Promise<boolean> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}`;
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'GET',
     headers: signedHeaders('GET', path, ''),
     signal: AbortSignal.timeout(15_000),
@@ -265,9 +304,10 @@ export async function sessionSetPinned(
 export async function sessionCancelExec(
   sessionId: string,
   execId: string,
+  spawnerColor?: string | null,
 ): Promise<boolean> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}/exec/${encodeURIComponent(execId)}/cancel`;
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'POST',
     headers: signedHeaders('POST', path, ''),
     body: '',
@@ -357,9 +397,10 @@ export type ExecLiveness =
 export async function sessionExecStatus(
   sessionId: string,
   execId: string,
+  spawnerColor?: string | null,
 ): Promise<ExecLiveness> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}/exec/${encodeURIComponent(execId)}`;
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'GET',
     headers: signedHeaders('GET', path, ''),
     signal: AbortSignal.timeout(30_000),
@@ -407,10 +448,11 @@ export interface SessionStageResult {
 export async function sessionStageFiles(
   sessionId: string,
   files: SessionStageFile[],
+  spawnerColor?: string | null,
 ): Promise<SessionStageResult> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}/files/stage`;
   const bodyJson = JSON.stringify({ files });
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'POST',
     headers: signedHeaders('POST', path, bodyJson),
     body: bodyJson,
@@ -466,9 +508,10 @@ export interface SessionFsEntry {
 export async function sessionListFiles(
   sessionId: string,
   dirPath: string,
+  spawnerColor?: string | null,
 ): Promise<SessionFsEntry[] | null> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}/files?path=${encodeURIComponent(dirPath)}`;
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'GET',
     headers: signedHeaders('GET', path, ''),
     signal: AbortSignal.timeout(30_000),
@@ -592,6 +635,7 @@ export async function sessionExec(
   signal: AbortSignal,
   callbacks: SessionExecCallbacks = {},
   cursor?: ExecCursor,
+  spawnerColor?: string | null,
 ): Promise<SessionExecResult> {
   const path = `/v1/sessions/${encodeURIComponent(sessionId)}/exec`;
   const bodyJson = JSON.stringify(body);
@@ -604,7 +648,7 @@ export async function sessionExec(
       (body.timeoutMs ?? EXEC_FALLBACK_TIMEOUT_MS) + EXEC_FETCH_GRACE_MS,
     ),
   ]);
-  const res = await fetch(`${getSpawnerUrl()}${path}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${path}`, {
     method: 'POST',
     headers: signedHeaders('POST', path, bodyJson, 'text/event-stream'),
     body: bodyJson,
@@ -632,6 +676,7 @@ export async function sessionAttachExec(
   callbacks: SessionExecCallbacks = {},
   cursor?: ExecCursor,
   timeoutMs?: number,
+  spawnerColor?: string | null,
 ): Promise<SessionExecResult> {
   const query = sinceSeq > 0 ? `?sinceSeq=${sinceSeq}` : '';
   // The spawner verifies the HMAC over pathname+search, so the signed string
@@ -645,7 +690,7 @@ export async function sessionAttachExec(
       (timeoutMs ?? EXEC_FALLBACK_TIMEOUT_MS) + EXEC_FETCH_GRACE_MS,
     ),
   ]);
-  const res = await fetch(`${getSpawnerUrl()}${signedPath}`, {
+  const res = await fetch(`${spawnerUrlForColor(spawnerColor)}${signedPath}`, {
     method: 'GET',
     headers: signedHeaders('GET', signedPath, '', 'text/event-stream'),
     signal: fetchAbort,
@@ -674,7 +719,13 @@ export async function drainSessionExecResilient(
   body: SessionExecBody,
   signal: AbortSignal,
   callbacks: SessionExecCallbacks = {},
-  opts: { cursor?: ExecCursor; resumeSinceSeq?: number } = {},
+  opts: {
+    cursor?: ExecCursor;
+    resumeSinceSeq?: number;
+    /** Blue-green colour the session lives on — routes exec/attach to
+     * `sandbox-<color>` so a resume reaches a lingering old-colour spawner. */
+    spawnerColor?: string | null;
+  } = {},
 ): Promise<SessionExecResult> {
   // External cursor lets the caller (run_agent) read the resume position; on a
   // continuation it starts at the handoff seq. `resumeSinceSeq` makes the FIRST
@@ -696,8 +747,16 @@ export async function drainSessionExecResilient(
             callbacks,
             cursor,
             body.timeoutMs,
+            opts.spawnerColor,
           )
-        : await sessionExec(sessionId, body, signal, callbacks, cursor);
+        : await sessionExec(
+            sessionId,
+            body,
+            signal,
+            callbacks,
+            cursor,
+            opts.spawnerColor,
+          );
     } catch (err) {
       if (signal.aborted) throw err;
       // A 404 means the session is gone, not a transient drop — retrying can't
diff --git a/services/platform/convex/node_only/sandbox/helpers/spawner_client.ts b/services/platform/convex/node_only/sandbox/helpers/spawner_client.ts
index 01d1e769fd..d4dd455686 100644
--- a/services/platform/convex/node_only/sandbox/helpers/spawner_client.ts
+++ b/services/platform/convex/node_only/sandbox/helpers/spawner_client.ts
@@ -234,15 +234,36 @@ function signRequest(
   return createHmac('sha256', token).update(signedString).digest('hex');
 }
 
-function getSpawnerUrl(): string {
+function spawnerBaseUrl(): string {
   // Mirrors RAG_URL / CRAWLER_URL convention: default to host loopback
   // so `bun dev`'s local convex-local-backend (running on the host) can
   // reach the spawner via the published port. Docker compose sets
   // SANDBOX_URL=http://sandbox:8003 on the tale-convex container so the
-  // dockerized convex resolves through Docker DNS instead.
+  // dockerized convex resolves through Docker DNS instead. In blue-green
+  // mode `sandbox` is the bare alias that the deploy flip points at the
+  // ACTIVE colour — so new executions always reach the live spawner.
   return process.env.SANDBOX_URL ?? 'http://localhost:8003';
 }
 
+/**
+ * Resolve the spawner URL for a SPECIFIC blue-green colour — used by cancel /
+ * session ops so they reach the exact colour an execution started on, even
+ * after a flip moved the bare `sandbox` alias to the new colour. `null`/empty
+ * colour (single-colour mode, or the docker DNS host isn't `sandbox`) falls
+ * back to the base URL.
+ */
+export function spawnerUrlForColor(color: string | null | undefined): string {
+  const base = spawnerBaseUrl();
+  if (!color) return base;
+  try {
+    const u = new URL(base);
+    if (u.hostname !== 'sandbox') return base; // dev/loopback → no per-colour host
+    return `${u.protocol}//sandbox-${color}:${u.port || '8003'}`;
+  } catch {
+    return base;
+  }
+}
+
 function getSpawnerToken(): string | null {
   // Opt-in HMAC: when SANDBOX_TOKEN is unset (or empty/whitespace-only) the
   // spawner skips signature verification and this client sends unsigned
@@ -266,8 +287,23 @@ interface SpawnerExecuteCallbacks {
   onStdout?: (text: string) => void;
   /** Live stderr tail. Fires per spawner-side chunk (not line-buffered). */
   onStderr?: (text: string) => void;
+  /**
+   * Fired once, as soon as the spawner's response headers arrive, with the
+   * blue-green colour it reported via `X-Sandbox-Color` (or `null` in
+   * single-colour mode). The action persists it on the execution row BEFORE
+   * the body streams, so a concurrent user-Stop routes its cancel to the SAME
+   * colour even after a deploy flip.
+   */
+  onSpawnerColor?: (color: string | null) => Promise<void> | void;
 }
 
+// How many times to re-POST /v1/execute when the spawner answers 503 "draining"
+// (it's mid-flip and refusing new work). A handful of fast retries re-resolves
+// the `sandbox` DNS alias onto the freshly-active colour. Bounded so a genuinely
+// down tier still fails fast into SPAWNER_UNAVAILABLE.
+const DRAIN_RETRY_MAX = 5;
+const DRAIN_RETRY_DELAY_MS = 400;
+
 /**
  * POST /v1/execute as SSE. The spawner emits zero or more `event: phase`
  * lines followed by exactly one `event: result` line. We invoke `onPhase`
@@ -293,27 +329,32 @@ export async function spawnerExecute(
   signal: AbortSignal,
   callbacks: SpawnerExecuteCallbacks = {},
 ): Promise<SpawnerExecuteResponse> {
-  const baseUrl = getSpawnerUrl();
+  const baseUrl = spawnerBaseUrl();
   const url = `${baseUrl}/v1/execute`;
   const path = new URL(url).pathname;
   const token = getSpawnerToken();
   const bodyJson = JSON.stringify(body);
-  const timestamp = String(Date.now());
 
-  const headers: Record<string, string> = {
-    'content-type': 'application/json',
-    accept: 'text/event-stream',
+  // Re-signed per attempt: each retry needs a fresh timestamp within the
+  // spawner's clock-skew tolerance.
+  const buildHeaders = (): Record<string, string> => {
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'text/event-stream',
+    };
+    if (token !== null) {
+      const timestamp = String(Date.now());
+      headers[SIGNATURE_HEADER] = signRequest(
+        'POST',
+        path,
+        timestamp,
+        bodyJson,
+        token,
+      );
+      headers[TIMESTAMP_HEADER] = timestamp;
+    }
+    return headers;
   };
-  if (token !== null) {
-    headers[SIGNATURE_HEADER] = signRequest(
-      'POST',
-      path,
-      timestamp,
-      bodyJson,
-      token,
-    );
-    headers[TIMESTAMP_HEADER] = timestamp;
-  }
 
   // Independent client-side timeout. Without this a stalled SSE stream
   // (network or spawner hang) would block the Convex action until its 30-min
@@ -321,25 +362,45 @@ export async function spawnerExecute(
   // user-stop still aborts immediately.
   const fetchTimeoutMs =
     (body.timeoutMs ?? SPAWNER_DEFAULT_TIMEOUT_MS) + SPAWNER_FETCH_OVERHEAD_MS;
-  const fetchAbort = AbortSignal.any([
-    signal,
-    AbortSignal.timeout(fetchTimeoutMs),
-  ]);
 
-  let res: Response;
-  try {
-    res = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: bodyJson,
-      signal: fetchAbort,
-    });
-  } catch (err) {
-    throw new Error(
-      `sandbox spawner unreachable at ${url}: ${err instanceof Error ? err.message : String(err)}`,
-      { cause: err },
-    );
-  }
+  // Fetch with blue-green drain-retry: a 503 "draining" means the targeted
+  // colour is mid-flip; re-POST so the `sandbox` alias re-resolves onto the
+  // now-active colour. Other statuses are handled below.
+  const doFetch = async (): Promise<Response> => {
+    for (let attempt = 0; ; attempt++) {
+      const fetchAbort = AbortSignal.any([
+        signal,
+        AbortSignal.timeout(fetchTimeoutMs),
+      ]);
+      let r: Response;
+      try {
+        r = await fetch(url, {
+          method: 'POST',
+          headers: buildHeaders(),
+          body: bodyJson,
+          signal: fetchAbort,
+        });
+      } catch (err) {
+        throw new Error(
+          `sandbox spawner unreachable at ${url}: ${err instanceof Error ? err.message : String(err)}`,
+          { cause: err },
+        );
+      }
+      if (r.status === 503 && attempt < DRAIN_RETRY_MAX) {
+        const peek = await r.text().catch(() => '');
+        if (peek.includes('draining')) {
+          await new Promise((resolve) =>
+            setTimeout(resolve, DRAIN_RETRY_DELAY_MS),
+          );
+          continue;
+        }
+        throw new Error(`sandbox spawner 503: ${peek || r.statusText}`);
+      }
+      return r;
+    }
+  };
+
+  const res = await doFetch();
 
   if (res.status === 401) {
     throw new Error(
@@ -365,6 +426,20 @@ export async function spawnerExecute(
     throw new Error('sandbox spawner returned no body');
   }
 
+  // Blue-green: report the colour the spawner self-identified (X-Sandbox-Color)
+  // so the caller can persist it on the execution row BEFORE streaming begins —
+  // a concurrent user-Stop then routes its cancel to this exact colour.
+  if (callbacks.onSpawnerColor) {
+    const reported = res.headers.get('x-sandbox-color');
+    try {
+      await callbacks.onSpawnerColor(
+        reported && reported.length > 0 ? reported : null,
+      );
+    } catch (err) {
+      console.warn(`[spawnerExecute] onSpawnerColor callback failed:`, err);
+    }
+  }
+
   // SSE parser: events are separated by `\n\n`; each event has `event:` and
   // `data:` lines. Handles CRLF line endings (any future proxy) as well as
   // LF. Accumulates text and processes complete events as they arrive,
@@ -597,8 +672,13 @@ function validateExecuteResponse(
   return raw as unknown as SpawnerExecuteResponse;
 }
 
-export async function spawnerCancel(executionId: string): Promise<void> {
-  const url = `${getSpawnerUrl()}/v1/cancel/${encodeURIComponent(executionId)}`;
+export async function spawnerCancel(
+  executionId: string,
+  spawnerColor?: string | null,
+): Promise<void> {
+  // Route to the SAME colour the execution started on (persisted on the row),
+  // so a cancel still lands after a deploy flip moved the bare `sandbox` alias.
+  const url = `${spawnerUrlForColor(spawnerColor)}/v1/cancel/${encodeURIComponent(executionId)}`;
   const path = new URL(url).pathname;
   const token = getSpawnerToken();
   const body = '';
diff --git a/services/platform/convex/node_only/sandbox/helpers/spawner_color_routing.test.ts b/services/platform/convex/node_only/sandbox/helpers/spawner_color_routing.test.ts
new file mode 100644
index 0000000000..5a1f8268fc
--- /dev/null
+++ b/services/platform/convex/node_only/sandbox/helpers/spawner_color_routing.test.ts
@@ -0,0 +1,36 @@
+// Unit tests for blue-green cancel routing — `spawnerUrlForColor` picks the
+// colour-suffixed spawner host so a cancel reaches the SAME colour an execution
+// started on, even after a deploy flip moved the bare `sandbox` alias.
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { spawnerUrlForColor } from './spawner_client';
+
+describe('spawnerUrlForColor', () => {
+  let saved: string | undefined;
+  beforeEach(() => {
+    saved = process.env.SANDBOX_URL;
+  });
+  afterEach(() => {
+    if (saved === undefined) delete process.env.SANDBOX_URL;
+    else process.env.SANDBOX_URL = saved;
+  });
+
+  test('rewrites the docker `sandbox` host to the colour-suffixed host', () => {
+    process.env.SANDBOX_URL = 'http://sandbox:8003';
+    expect(spawnerUrlForColor('blue')).toBe('http://sandbox-blue:8003');
+    expect(spawnerUrlForColor('green')).toBe('http://sandbox-green:8003');
+  });
+
+  test('null/undefined colour falls back to the base alias (single-colour)', () => {
+    process.env.SANDBOX_URL = 'http://sandbox:8003';
+    expect(spawnerUrlForColor(null)).toBe('http://sandbox:8003');
+    expect(spawnerUrlForColor(undefined)).toBe('http://sandbox:8003');
+  });
+
+  test('leaves a non-`sandbox` host (dev loopback) untouched', () => {
+    process.env.SANDBOX_URL = 'http://localhost:8003';
+    // Dev is single-colour; a colour value must not invent a localhost-X host.
+    expect(spawnerUrlForColor('blue')).toBe('http://localhost:8003');
+  });
+});
diff --git a/services/platform/convex/node_only/sandbox/internal_actions.ts b/services/platform/convex/node_only/sandbox/internal_actions.ts
index 365d5cbd18..107b030e15 100644
--- a/services/platform/convex/node_only/sandbox/internal_actions.ts
+++ b/services/platform/convex/node_only/sandbox/internal_actions.ts
@@ -388,7 +388,25 @@ export const executeCode = internalAction({
           timeoutMs,
         },
         abort.signal,
-        {},
+        {
+          // Blue-green: persist the colour the spawner landed on so a
+          // concurrent user-Stop routes its cancel to the SAME colour even
+          // after a deploy flip. Best-effort — a failed patch just falls back
+          // to the bare `sandbox` alias on cancel.
+          onSpawnerColor: async (color) => {
+            await ctx
+              .runMutation(
+                internal.sandbox.internal_mutations.setSpawnerColor,
+                { executionId, spawnerColor: color },
+              )
+              .catch((err: unknown) => {
+                console.warn(
+                  `[sandbox.executeCode] setSpawnerColor failed (continuing):`,
+                  err,
+                );
+              });
+          },
+        },
       );
     } catch (err) {
       return failExecution(
@@ -576,7 +594,9 @@ export const cancelExecutionsForThread = internalAction({
     let cancelled = 0;
     for (const row of rows) {
       try {
-        await spawnerCancel(String(row._id));
+        // Route to the colour this execution started on so the cancel lands
+        // even after a deploy flip moved the bare `sandbox` alias.
+        await spawnerCancel(String(row._id), row.spawnerColor);
       } catch (err) {
         console.warn(
           `[sandbox.cancelExecutionsForThread] spawnerCancel(${row._id}) failed (continuing):`,
diff --git a/services/platform/convex/node_only/sandbox/run_agent.ts b/services/platform/convex/node_only/sandbox/run_agent.ts
index e39bd9cc7f..5a5ce86790 100644
--- a/services/platform/convex/node_only/sandbox/run_agent.ts
+++ b/services/platform/convex/node_only/sandbox/run_agent.ts
@@ -141,6 +141,11 @@ export interface RunAgentInSessionArgs {
    * skip mid-turn steering / the human-control card for autonomous runs.
    * Independent of permissionMode. */
   interactionMode?: 'interactive' | 'autonomous';
+  /** Blue-green colour the session lives on. Routes the session exec/attach,
+   * cancel, and file ops to `sandbox-<spawnerColor>` so a turn (or its resume)
+   * reaches a session lingering on the old colour after a deploy flip.
+   * `undefined` ⇒ single-colour / pre-blue-green → the bare `sandbox` alias. */
+  spawnerColor?: string | null;
   /** Extra system-prompt text appended to the agent CLI's own prompt. */
   systemPromptAppend?: string;
   /** Credential mode (default 'managed'). 'byo' skips the gateway entirely. */
@@ -533,9 +538,12 @@ export async function runAgentInSessionImpl(
       console.warn(
         `[run_agent] exec ${args.execId} still alive ${STDIN_EOF_GRACE_MS}ms after stdin EOF — reaping`,
       );
-      void sessionCancelExec(args.sessionId, args.execId).catch(
-        (err: unknown) =>
-          console.warn('[run_agent] post-EOF reap failed:', err),
+      void sessionCancelExec(
+        args.sessionId,
+        args.execId,
+        args.spawnerColor,
+      ).catch((err: unknown) =>
+        console.warn('[run_agent] post-EOF reap failed:', err),
       );
     }, STDIN_EOF_GRACE_MS);
   };
@@ -590,6 +598,7 @@ export async function runAgentInSessionImpl(
             'utf8',
           ).toString('base64'),
         })),
+        args.spawnerColor,
       );
     }
     const rows = [...fileRows, ...queued].sort(
@@ -1067,6 +1076,7 @@ export async function runAgentInSessionImpl(
           const entries = await sessionListFiles(
             args.sessionId,
             steerDirFor(args.execId),
+            args.spawnerColor,
           );
           const consumedIds = matchConsumedSteerFiles(fileDelivered, entries);
           if (consumedIds.length > 0) {
@@ -1203,6 +1213,7 @@ export async function runAgentInSessionImpl(
     {
       cursor,
       ...(resuming && { resumeSinceSeq: args.resumeFrom?.lastSeq ?? 0 }),
+      ...(args.spawnerColor != null && { spawnerColor: args.spawnerColor }),
     },
   );
   let hardDeadlineTimer: ReturnType<typeof setTimeout> | undefined;
diff --git a/services/platform/convex/notifications/helpers.ts b/services/platform/convex/notifications/helpers.ts
index 82bb4fafdc..c87253b19e 100644
--- a/services/platform/convex/notifications/helpers.ts
+++ b/services/platform/convex/notifications/helpers.ts
@@ -1,6 +1,12 @@
+import type { Infer } from 'convex/values';
+
 import { internal } from '../_generated/api';
 import type { MutationCtx } from '../_generated/server';
-import { NOTIFICATION_CATEGORIES, NOTIFICATION_SEVERITIES } from './schema';
+import {
+  NOTIFICATION_CATEGORIES,
+  NOTIFICATION_SEVERITIES,
+  notificationLinkValidator,
+} from './schema';
 
 type Category = (typeof NOTIFICATION_CATEGORIES)[number];
 type Severity = (typeof NOTIFICATION_SEVERITIES)[number];
@@ -19,6 +25,8 @@ interface WriteNotificationArgs {
    * regardless of audit-pepper rotation or email change.
    */
   subjectUserId?: string;
+  /** Optional in-app deep-link target for the notification body. */
+  link?: Infer<typeof notificationLinkValidator>;
 }
 
 /**
@@ -40,6 +48,7 @@ export async function writeNotificationForOrgs(
       bodyKey: args.bodyKey,
       params: args.params,
       subjectUserId: args.subjectUserId,
+      link: args.link,
       createdAt: now,
       readBy: [],
     });
diff --git a/services/platform/convex/notifications/queries.ts b/services/platform/convex/notifications/queries.ts
index b54f2ae179..cf250f7ca7 100644
--- a/services/platform/convex/notifications/queries.ts
+++ b/services/platform/convex/notifications/queries.ts
@@ -4,6 +4,7 @@ import { v } from 'convex/values';
 import { query } from '../_generated/server';
 import { getAuthUserIdentity } from '../lib/rls/auth/get_auth_user_identity';
 import { getOrganizationMember } from '../lib/rls/organization/get_organization_member';
+import { notificationLinkValidator } from './schema';
 
 const notificationDocValidator = v.object({
   _id: v.id('notifications'),
@@ -18,6 +19,7 @@ const notificationDocValidator = v.object({
   titleKey: v.string(),
   bodyKey: v.string(),
   params: v.optional(v.any()),
+  link: v.optional(notificationLinkValidator),
   createdAt: v.number(),
   readBy: v.array(v.string()),
   read: v.boolean(),
@@ -65,6 +67,7 @@ export const list = query({
       titleKey: n.titleKey,
       bodyKey: n.bodyKey,
       params: n.params,
+      link: n.link,
       createdAt: n.createdAt,
       readBy: n.readBy,
       read: n.readBy.includes(userId),
diff --git a/services/platform/convex/notifications/schema.ts b/services/platform/convex/notifications/schema.ts
index 9cb35b9fac..51f8c55bb2 100644
--- a/services/platform/convex/notifications/schema.ts
+++ b/services/platform/convex/notifications/schema.ts
@@ -13,6 +13,20 @@ const severityValidator = v.union(
   ...NOTIFICATION_SEVERITIES.map((s) => v.literal(s)),
 );
 
+/**
+ * Optional in-app deep-link target for a notification. The client maps each
+ * `kind` to a concrete dashboard route (see `notification-target.ts`) so the
+ * stored value stays route-agnostic (survives route refactors, locale-safe).
+ * Closed union — schema ships one release ahead of new emitters, per the
+ * Convex closed-union deploy-order constraint.
+ */
+export const notificationLinkValidator = v.union(
+  v.object({ kind: v.literal('agent'), agentSlug: v.string() }),
+  v.object({ kind: v.literal('audit-logs') }),
+  v.object({ kind: v.literal('dsar') }),
+  v.object({ kind: v.literal('security-monitoring') }),
+);
+
 export const notificationsTable = defineTable({
   organizationId: v.string(),
   category: categoryValidator,
@@ -34,6 +48,9 @@ export const notificationsTable = defineTable({
    * undefined and fall back to a best-effort email-hash match.
    */
   subjectUserId: v.optional(v.string()),
+  // Optional in-app deep-link target. Legacy rows pre-fix have it undefined and
+  // render without a body link (icon-only mark-as-read).
+  link: v.optional(notificationLinkValidator),
   createdAt: v.number(),
   // userIds (Better Auth user document _id, stored as string) that have dismissed this notification
   readBy: v.array(v.string()),
diff --git a/services/platform/convex/providers/errors.test.ts b/services/platform/convex/providers/errors.test.ts
index 6ebcd1a91a..43c0c6fce3 100644
--- a/services/platform/convex/providers/errors.test.ts
+++ b/services/platform/convex/providers/errors.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+  classifyFailureScope,
   isTransientProviderError,
   MissingApiKeyError,
   NoProviderAvailableError,
@@ -293,6 +294,44 @@ describe('shouldFailoverToNextModel', () => {
   });
 });
 
+describe('classifyFailureScope', () => {
+  it('marks deterministic provider-level failures as provider-scoped', () => {
+    expect(classifyFailureScope({ status: 402 })).toBe('provider');
+    expect(classifyFailureScope({ message: 'requires more credits' })).toBe(
+      'provider',
+    );
+    expect(classifyFailureScope({ status: 401 })).toBe('provider');
+    expect(classifyFailureScope({ status: 403 })).toBe('provider');
+    expect(classifyFailureScope({ code: 'ECONNREFUSED' })).toBe('provider');
+    expect(classifyFailureScope({ message: 'fetch failed' })).toBe('provider');
+  });
+
+  it('keeps transient and model-specific failures model-scoped', () => {
+    expect(classifyFailureScope({ status: 429 })).toBe('model');
+    expect(classifyFailureScope({ status: 503 })).toBe('model');
+    expect(classifyFailureScope({ code: 'ECONNRESET' })).toBe('model');
+    expect(classifyFailureScope({ message: 'Request timed out' })).toBe(
+      'model',
+    );
+    expect(classifyFailureScope({ status: 404 })).toBe('model');
+    expect(classifyFailureScope(new MissingApiKeyError('p', 'm'))).toBe(
+      'model',
+    );
+  });
+
+  it('marks universal failures as terminal (no failover)', () => {
+    expect(classifyFailureScope({ message: 'content policy violation' })).toBe(
+      'terminal',
+    );
+    expect(classifyFailureScope({ message: 'context_length exceeded' })).toBe(
+      'terminal',
+    );
+    expect(
+      classifyFailureScope(new NoProviderAvailableError('x', 'no_providers')),
+    ).toBe('terminal');
+  });
+});
+
 describe('ProviderUnavailableError', () => {
   it('stores provider and model info', () => {
     const err = new ProviderUnavailableError(
diff --git a/services/platform/convex/providers/errors.ts b/services/platform/convex/providers/errors.ts
index 13f9b5dd00..668149fa21 100644
--- a/services/platform/convex/providers/errors.ts
+++ b/services/platform/convex/providers/errors.ts
@@ -1,3 +1,8 @@
+import {
+  classifyChatErrorCode,
+  PROVIDER_SCOPED_ERROR_CODES,
+} from '../../lib/shared/chat-errors';
+
 /**
  * Typed error for provider unavailability (HTTP 429, 502, 503, timeout).
  *
@@ -244,3 +249,29 @@ export function shouldFailoverToNextModel(error: unknown): boolean {
   // Conservative default: try the fallback for unrecognised errors.
   return true;
 }
+
+/**
+ * Failure scope: how widely a model failure should suppress retries.
+ *
+ * - `'terminal'`  — would fail on ANY model (content policy, context length,
+ *   no provider configured). Don't fall over at all. Equivalent to
+ *   `!shouldFailoverToNextModel(error)`.
+ * - `'provider'`  — a DETERMINISTIC property of the provider/account (out of
+ *   funds, invalid API key, host unreachable). Every model on that provider
+ *   would fail the same way, so the fallback loop skips the rest of the
+ *   provider's models and jumps to a model on a different provider.
+ * - `'model'`     — specific to this model OR transient (404 not-found, 429,
+ *   5xx, timeout, reset, missing per-model key). Try the next model in line,
+ *   even on the same provider — a sibling may succeed.
+ *
+ * The provider-scoped set lives in `lib/shared/chat-errors` so the backend
+ * failover decision and the client-facing error code stay in lockstep.
+ */
+export function classifyFailureScope(
+  error: unknown,
+): 'terminal' | 'provider' | 'model' {
+  if (!shouldFailoverToNextModel(error)) return 'terminal';
+  return PROVIDER_SCOPED_ERROR_CODES.has(classifyChatErrorCode(error))
+    ? 'provider'
+    : 'model';
+}
diff --git a/services/platform/convex/providers/failure_scope.test.ts b/services/platform/convex/providers/failure_scope.test.ts
new file mode 100644
index 0000000000..3cf098b477
--- /dev/null
+++ b/services/platform/convex/providers/failure_scope.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  credentialScopeKey,
+  endpointScopeKey,
+  isModelScopeRetired,
+  modelScopeKeys,
+  retiredScopeKey,
+} from './failure_scope';
+
+const model = (
+  over: Partial<{ providerName: string; apiKey: string; baseUrl: string }> = {},
+) => ({
+  providerName: 'openrouter',
+  apiKey: 'key-A',
+  baseUrl: 'https://openrouter.ai/api/v1',
+  ...over,
+});
+
+describe('credentialScopeKey', () => {
+  it('is identical for the same provider + key', () => {
+    expect(credentialScopeKey(model())).toBe(credentialScopeKey(model()));
+  });
+
+  it('differs when the key differs (same provider)', () => {
+    expect(credentialScopeKey(model({ apiKey: 'key-A' }))).not.toBe(
+      credentialScopeKey(model({ apiKey: 'key-B' })),
+    );
+  });
+
+  it('does not contain the raw key', () => {
+    expect(
+      credentialScopeKey(model({ apiKey: 'super-secret-123' })),
+    ).not.toContain('super-secret-123');
+  });
+});
+
+describe('endpointScopeKey', () => {
+  it('is provider + baseUrl scoped', () => {
+    expect(endpointScopeKey(model())).toBe(
+      endpointScopeKey(model({ apiKey: 'different-key' })),
+    );
+    expect(endpointScopeKey(model({ baseUrl: 'https://a' }))).not.toBe(
+      endpointScopeKey(model({ baseUrl: 'https://b' })),
+    );
+  });
+});
+
+describe('retiredScopeKey', () => {
+  it('retires the CREDENTIAL for funds and auth failures', () => {
+    expect(retiredScopeKey('credit_exhausted', model())).toBe(
+      credentialScopeKey(model()),
+    );
+    expect(retiredScopeKey('auth_error', model())).toBe(
+      credentialScopeKey(model()),
+    );
+  });
+
+  it('retires the ENDPOINT for an unreachable host', () => {
+    expect(retiredScopeKey('provider_unreachable', model())).toBe(
+      endpointScopeKey(model()),
+    );
+  });
+
+  it('retires nothing for transient or model-scoped failures', () => {
+    expect(retiredScopeKey('provider_error', model())).toBeNull();
+    expect(retiredScopeKey('rate_limited', model())).toBeNull();
+    expect(retiredScopeKey('model_not_found', model())).toBeNull();
+    expect(retiredScopeKey('generic', model())).toBeNull();
+  });
+});
+
+describe('isModelScopeRetired', () => {
+  it('skips a sibling that shares the dead credential', () => {
+    const dead = new Set([credentialScopeKey(model({ apiKey: 'shared' }))]);
+    expect(isModelScopeRetired(model({ apiKey: 'shared' }), dead)).toBe(true);
+  });
+
+  it('does NOT skip a sibling on the same provider with a different key', () => {
+    const dead = new Set([credentialScopeKey(model({ apiKey: 'key-A' }))]);
+    // Same provider + baseUrl, different key → independent credential.
+    expect(isModelScopeRetired(model({ apiKey: 'key-B' }), dead)).toBe(false);
+  });
+
+  it('skips every model on a dead endpoint regardless of key', () => {
+    const dead = new Set([endpointScopeKey(model())]);
+    expect(isModelScopeRetired(model({ apiKey: 'any-other-key' }), dead)).toBe(
+      true,
+    );
+  });
+
+  it('returns false against an empty dead-set', () => {
+    expect(isModelScopeRetired(model(), new Set())).toBe(false);
+  });
+
+  it('exposes both scopes a model belongs to', () => {
+    expect(modelScopeKeys(model())).toEqual([
+      credentialScopeKey(model()),
+      endpointScopeKey(model()),
+    ]);
+  });
+});
diff --git a/services/platform/convex/providers/failure_scope.ts b/services/platform/convex/providers/failure_scope.ts
new file mode 100644
index 0000000000..ee87e9dcc1
--- /dev/null
+++ b/services/platform/convex/providers/failure_scope.ts
@@ -0,0 +1,80 @@
+/**
+ * Failure-scope identities for the model fallback loop.
+ *
+ * When a model fails with a *deterministic* provider-level error, every model
+ * that shares the failing resource is doomed too and should be skipped — but
+ * the resource is NOT the provider name. It is:
+ *
+ * - the **credential** (provider + API key) for out-of-funds (402) and invalid
+ *   key (401/403) — these are account/key-level, so two models on the same
+ *   provider with DIFFERENT per-model `secretsEnv` keys are independent;
+ * - the **endpoint** (provider + baseUrl) for an unreachable host — this is
+ *   provider-wide (models can't override baseUrl).
+ *
+ * Keying the dead-set by these identities (instead of the provider name) means
+ * a sibling model with its own key is still tried after the first key fails.
+ *
+ * Pure, V8-safe module (no Node, no crypto): the key fingerprint is a plain
+ * FNV-1a hash, used only to bucket identical keys without holding the raw key
+ * in the set — not a security primitive.
+ */
+
+import type { ChatErrorCode } from '../../lib/shared/chat-errors';
+
+/** The minimal resolved-model shape these helpers need. */
+interface ScopeModelData {
+  providerName: string;
+  /** Per-model API key; absent for keyless/local providers (treated as ''). */
+  apiKey?: string;
+  /** Endpoint base URL; absent when the provider default is used (treated as ''). */
+  baseUrl?: string;
+}
+
+/** FNV-1a 32-bit → 8-char hex. Stable, non-reversible bucket id for an API key. */
+function fingerprint(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Credential identity: provider + API key (funds / auth are key-scoped). */
+export function credentialScopeKey(data: ScopeModelData): string {
+  return `cred:${data.providerName}:${fingerprint(data.apiKey ?? '')}`;
+}
+
+/** Endpoint identity: provider + baseUrl (reachability is endpoint-scoped). */
+export function endpointScopeKey(data: ScopeModelData): string {
+  return `host:${data.providerName}:${data.baseUrl ?? ''}`;
+}
+
+/** Every scope a model belongs to — for dead-set membership tests. */
+export function modelScopeKeys(data: ScopeModelData): readonly string[] {
+  return [credentialScopeKey(data), endpointScopeKey(data)];
+}
+
+/**
+ * The scope a deterministic provider-level failure retires for THIS model, or
+ * `null` when the error is not deterministic-provider-level (nothing is retired,
+ * so the next model — even on the same provider — is still attempted).
+ */
+export function retiredScopeKey(
+  code: ChatErrorCode,
+  data: ScopeModelData,
+): string | null {
+  if (code === 'provider_unreachable') return endpointScopeKey(data);
+  if (code === 'credit_exhausted' || code === 'auth_error') {
+    return credentialScopeKey(data);
+  }
+  return null;
+}
+
+/** True if any of the model's scopes has already been retired this turn. */
+export function isModelScopeRetired(
+  data: ScopeModelData,
+  deadScopes: ReadonlySet<string>,
+): boolean {
+  return modelScopeKeys(data).some((key) => deadScopes.has(key));
+}
diff --git a/services/platform/convex/reasoning_profiles/schema.ts b/services/platform/convex/reasoning_profiles/schema.ts
index d6ba60ffa7..4aad73b5aa 100644
--- a/services/platform/convex/reasoning_profiles/schema.ts
+++ b/services/platform/convex/reasoning_profiles/schema.ts
@@ -12,6 +12,16 @@ const bucket = v.object({
   // Response-quality EMA per class (quality-feedback governor). Optional;
   // legacy rows omit it and readers coalesce to a neutral 1.0.
   qualityEma: v.optional(v.number()),
+  // Last tier the controller settled on (effort-tier anti-oscillation guard).
+  // Optional; absence disables the guard for that bucket.
+  lastTier: v.optional(
+    v.union(
+      v.literal('off'),
+      v.literal('low'),
+      v.literal('medium'),
+      v.literal('high'),
+    ),
+  ),
 });
 
 /**
diff --git a/services/platform/convex/sandbox/internal_mutations.ts b/services/platform/convex/sandbox/internal_mutations.ts
index d0118705f2..c0e1c813b4 100644
--- a/services/platform/convex/sandbox/internal_mutations.ts
+++ b/services/platform/convex/sandbox/internal_mutations.ts
@@ -302,6 +302,27 @@ export const heartbeat = internalMutation({
   },
 });
 
+/**
+ * Persist the blue-green spawner colour the execution landed on (self-reported
+ * by the spawner via X-Sandbox-Color at execute start). Lets the user-Stop /
+ * cancel path route to the SAME colour after a deploy flip. No-op for a null
+ * colour (single-colour mode) or a vanished row.
+ */
+export const setSpawnerColor = internalMutation({
+  args: {
+    executionId: v.id('sandboxExecutions'),
+    spawnerColor: v.union(v.string(), v.null()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    if (args.spawnerColor === null) return null;
+    const row = await ctx.db.get(args.executionId);
+    if (!row) return null;
+    await ctx.db.patch(args.executionId, { spawnerColor: args.spawnerColor });
+    return null;
+  },
+});
+
 /**
  * Settles an audit row into a terminal state. Idempotent w.r.t. duplicate
  * Convex retries AND races with the watchdog: if the row is already in a
@@ -489,6 +510,8 @@ export const listNonTerminalByThread = internalQuery({
   returns: v.array(
     v.object({
       _id: v.id('sandboxExecutions'),
+      // Blue-green colour for cancel-routing (undefined in single-colour mode).
+      spawnerColor: v.optional(v.string()),
     }),
   ),
   handler: async (ctx, args) => {
@@ -498,10 +521,11 @@ export const listNonTerminalByThread = internalQuery({
       .collect();
     const out: Array<{
       _id: Id<'sandboxExecutions'>;
+      spawnerColor?: string;
     }> = [];
     for (const row of rows) {
       if (sandboxTerminalStatuses.has(row.status)) continue;
-      out.push({ _id: row._id });
+      out.push({ _id: row._id, spawnerColor: row.spawnerColor });
     }
     return out;
   },
diff --git a/services/platform/convex/sandbox/schema.ts b/services/platform/convex/sandbox/schema.ts
index e5dcb45fd1..0594cf648f 100644
--- a/services/platform/convex/sandbox/schema.ts
+++ b/services/platform/convex/sandbox/schema.ts
@@ -174,6 +174,15 @@ export const sandboxExecutionsTable = defineTable({
 
   errorCode: v.optional(sandboxErrorCodeValidator),
   errorMessage: v.optional(v.string()),
+
+  /**
+   * Blue-green colour of the spawner this execution is running on, self-reported
+   * by the spawner via the `X-Sandbox-Color` response header at execute start.
+   * `undefined` in single-colour mode. The user-Stop / cancel path reads it so
+   * `spawnerCancel` reaches the SAME colour even after a deploy flip moved the
+   * bare `sandbox` alias to the new colour.
+   */
+  spawnerColor: v.optional(v.string()),
 })
   .index('by_organizationId_and_status', ['organizationId', 'status'])
   .index('by_organizationId', ['organizationId'])
diff --git a/services/platform/convex/sandbox/session_mutations.ts b/services/platform/convex/sandbox/session_mutations.ts
index 4be667c533..815adb8390 100644
--- a/services/platform/convex/sandbox/session_mutations.ts
+++ b/services/platform/convex/sandbox/session_mutations.ts
@@ -284,6 +284,35 @@ export const markSessionRowStopped = internalMutation({
  * lets the turn call it on resume without re-reading the post-reconcile status.
  * Returns whether a row was patched.
  */
+/**
+ * Persist the blue-green spawner colour a session landed on (self-reported via
+ * `X-Sandbox-Color` at create/resume). Session ops then route to
+ * `sandbox-<spawnerColor>` so a long agent turn survives a deploy flip that
+ * lingered the old colour. Patches the LIVE row only (mirrors setSessionPinned),
+ * and no-ops on a `null` colour (single-colour mode) so it never clobbers a
+ * real colour with nothing.
+ */
+export const setSessionSpawnerColor = internalMutation({
+  args: {
+    organizationId: v.string(),
+    sessionId: v.string(),
+    spawnerColor: v.union(v.string(), v.null()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    if (args.spawnerColor === null) return null;
+    for await (const row of ctx.db
+      .query('sandboxSessions')
+      .withIndex('by_sessionId', (q) => q.eq('sessionId', args.sessionId))) {
+      if (row.organizationId !== args.organizationId) continue;
+      if (!isLiveSessionStatus(row.status)) continue;
+      if (row.spawnerColor === args.spawnerColor) continue;
+      await ctx.db.patch(row._id, { spawnerColor: args.spawnerColor });
+    }
+    return null;
+  },
+});
+
 export const resumeStoppedSession = internalMutation({
   args: { organizationId: v.string(), sessionId: v.string() },
   returns: v.boolean(),
diff --git a/services/platform/convex/sandbox/session_queries.ts b/services/platform/convex/sandbox/session_queries.ts
index 97d21b7bf1..77914172be 100644
--- a/services/platform/convex/sandbox/session_queries.ts
+++ b/services/platform/convex/sandbox/session_queries.ts
@@ -204,6 +204,11 @@ export const listAbandonedAgentOps = internalQuery({
       progressText: v.optional(v.string()),
       exitCode: v.optional(v.number()),
       heartbeatAt: v.optional(v.number()),
+      // Blue-green colour the session lives on — the watchdog probes/cancels via
+      // `sandbox-<spawnerColor>` so it reaches a session lingering on the old
+      // colour after a deploy flip (else the bare alias hits the new colour →
+      // spurious 404 → the live turn gets finalized as failed).
+      spawnerColor: v.optional(v.string()),
     }),
   ),
   handler: async (ctx, args) => {
@@ -216,12 +221,18 @@ export const listAbandonedAgentOps = internalQuery({
       if (row.kind !== 'agent-run') continue;
       if (row.finalizedAt !== undefined) continue;
       // Join the session's agentKind (the op doesn't store it) so a resumed
-      // continuation runs the right adapter. Default 'claude-code' if unknown.
+      // continuation runs the right adapter, and its spawnerColor so recovery
+      // routes to the colour the session lives on. Default 'claude-code' if
+      // unknown. Pick the LIVE row's colour (skip historical dead incarnations
+      // under the reused deterministic id).
       let agentKind: string | undefined;
+      let spawnerColor: string | undefined;
       for await (const session of ctx.db
         .query('sandboxSessions')
         .withIndex('by_sessionId', (q) => q.eq('sessionId', row.sessionId))) {
+        if (!isLiveSessionStatus(session.status)) continue;
         agentKind = session.agentKind;
+        spawnerColor = session.spawnerColor;
         break;
       }
       out.push({
@@ -256,6 +267,7 @@ export const listAbandonedAgentOps = internalQuery({
         }),
         ...(row.exitCode !== undefined && { exitCode: row.exitCode }),
         ...(row.heartbeatAt !== undefined && { heartbeatAt: row.heartbeatAt }),
+        ...(spawnerColor !== undefined && { spawnerColor }),
       });
       if (out.length >= args.limit) break;
     }
diff --git a/services/platform/convex/sandbox/sessions_schema.ts b/services/platform/convex/sandbox/sessions_schema.ts
index a6e9508b5d..856f4c11da 100644
--- a/services/platform/convex/sandbox/sessions_schema.ts
+++ b/services/platform/convex/sandbox/sessions_schema.ts
@@ -58,6 +58,16 @@ export const sandboxSessionsTable = defineTable({
    * sandbox-management page, so the warm-container cost is bounded. */
   pinned: v.optional(v.boolean()),
   pinnedAt: v.optional(v.number()),
+  /**
+   * Blue-green spawner colour this session was created on (self-reported via
+   * `X-Sandbox-Color` at create). Session ops route to `sandbox-<spawnerColor>`
+   * so a long agent turn survives a deploy flip that LINGERS the old colour:
+   * after the alias moves to the new colour, the recovery/continuation path
+   * still reaches the lingering spawner. `undefined` ⇒ single-colour (dev) or a
+   * pre-blue-green row → ops fall back to the bare `sandbox` alias. Re-stamped
+   * on resume (a resume may land on a different colour). Additive + optional →
+   * no migration. */
+  spawnerColor: v.optional(v.string()),
 })
   .index('by_organizationId_and_status', ['organizationId', 'status'])
   .index('by_owner', ['ownerType', 'ownerId'])
diff --git a/services/platform/convex/schema.ts b/services/platform/convex/schema.ts
index 90d686ad2b..d8507c4760 100644
--- a/services/platform/convex/schema.ts
+++ b/services/platform/convex/schema.ts
@@ -25,6 +25,7 @@ import {
   taskSubscriptionsTable,
   userNotificationsTable,
 } from './collab/schema';
+import { backendControlTable } from './control/schema';
 import {
   conversationsTable,
   conversationMessagesTable,
@@ -162,6 +163,9 @@ export default defineSchema({
   // `$TALE_CONFIG_DIR/<org>/governance/`; this table is re-derivable. See
   // `lib/config_cache/schema.ts`.
   configCache: configCacheTable,
+  // Backend-wide control flags (deploy drain). Singleton row; re-derivable /
+  // transient. See `control/schema.ts`.
+  backendControl: backendControlTable,
   // Versioned data-migration framework. `migrationLedger` records which
   // migrations have applied (and their resume cursors); `migrationSnapshots`
   // holds pre-`up` backups so destructive migrations can be rolled back. See
diff --git a/services/platform/convex/task_metrics/queries.ts b/services/platform/convex/task_metrics/queries.ts
index 9d24a4255c..4695e03a8d 100644
--- a/services/platform/convex/task_metrics/queries.ts
+++ b/services/platform/convex/task_metrics/queries.ts
@@ -35,10 +35,19 @@ async function requireMember(
   return { userId: member.userId, role: member.role };
 }
 
-function windowKeys(days: number): { startKey: string; todayKey: string } {
+function windowKeys(days: number): {
+  startKey: string;
+  /** Start of the immediately-preceding equal-length window (for deltas). */
+  prevStartKey: string;
+  todayKey: string;
+} {
   const clamped = Math.min(Math.max(days, 1), TREND_MAX_DAYS);
   const todayKey = utcDayKey(Date.now());
-  return { startKey: dayKeyDaysBefore(todayKey, clamped), todayKey };
+  return {
+    startKey: dayKeyDaysBefore(todayKey, clamped),
+    prevStartKey: dayKeyDaysBefore(todayKey, clamped * 2),
+    todayKey,
+  };
 }
 
 /**
@@ -53,7 +62,7 @@ export const getWorkforceMetrics = query({
   returns: v.any(),
   handler: async (ctx, args) => {
     await requireMember(ctx, args.organizationId);
-    const { startKey } = windowKeys(args.days ?? 30);
+    const { startKey, prevStartKey } = windowKeys(args.days ?? 30);
 
     const totals = {
       tasksCreated: 0,
@@ -74,6 +83,17 @@ export const getWorkforceMetrics = query({
       leadTimeCount: 0,
       capped: false,
     };
+    // Prior equal-length window — totals only, for the KPI deltas.
+    const prevTotals = {
+      tasksCompleted: 0,
+      agentRunsStarted: 0,
+      reviewsPassed: 0,
+      reviewsChangesRequested: 0,
+      escalations: 0,
+      cycleTimeSumMs: 0,
+      cycleTimeCount: 0,
+      totalCostCents: 0,
+    };
     const byDay = new Map<
       string,
       {
@@ -91,8 +111,22 @@ export const getWorkforceMetrics = query({
     for await (const row of ctx.db
       .query('taskMetricsDaily')
       .withIndex('by_org_date', (q) =>
-        q.eq('organizationId', args.organizationId).gte('dateKey', startKey),
+        q
+          .eq('organizationId', args.organizationId)
+          .gte('dateKey', prevStartKey),
       )) {
+      if (row.dateKey < startKey) {
+        // Prior window — accumulate the delta-relevant totals only.
+        prevTotals.tasksCompleted += row.tasksCompleted;
+        prevTotals.agentRunsStarted += row.agentRunsStarted;
+        prevTotals.reviewsPassed += row.reviewsPassed;
+        prevTotals.reviewsChangesRequested += row.reviewsChangesRequested;
+        prevTotals.escalations += row.escalations;
+        prevTotals.cycleTimeSumMs += row.cycleTimeSumMs;
+        prevTotals.cycleTimeCount += row.cycleTimeCount;
+        prevTotals.totalCostCents += row.totalCostCents;
+        continue;
+      }
       totals.tasksCreated += row.tasksCreated;
       totals.tasksCompleted += row.tasksCompleted;
       totals.tasksCancelled += row.tasksCancelled;
@@ -180,6 +214,7 @@ export const getWorkforceMetrics = query({
 
     return {
       totals,
+      previousTotals: prevTotals,
       trend: [...byDay.values()].sort((a, b) =>
         a.dateKey.localeCompare(b.dateKey),
       ),
@@ -200,20 +235,43 @@ export const getAgentScorecard = query({
   returns: v.any(),
   handler: async (ctx, args) => {
     await requireMember(ctx, args.organizationId);
-    const { startKey } = windowKeys(args.days ?? 30);
+    const { startKey, prevStartKey } = windowKeys(args.days ?? 30);
 
-    const daily: Array<Doc<'agentTaskMetricsDaily'>> = [];
+    // Scan from the previous window's start so we can split current vs prior
+    // period in one pass — the prior totals power the scorecard's deltas.
+    const allRows: Array<Doc<'agentTaskMetricsDaily'>> = [];
     for await (const row of ctx.db
       .query('agentTaskMetricsDaily')
       .withIndex('by_org_agent_date', (q) =>
         q
           .eq('organizationId', args.organizationId)
           .eq('agentSlug', args.agentSlug)
-          .gte('dateKey', startKey),
+          .gte('dateKey', prevStartKey),
       )) {
-      daily.push(row);
+      allRows.push(row);
     }
-    daily.sort((a, b) => a.dateKey.localeCompare(b.dateKey));
+    allRows.sort((a, b) => a.dateKey.localeCompare(b.dateKey));
+
+    const toDay = (row: Doc<'agentTaskMetricsDaily'>) => ({
+      dateKey: row.dateKey,
+      runsStarted: row.runsStarted,
+      runsCompleted: row.runsCompleted,
+      runsFailed: row.runsFailed,
+      runDurationSumMs: row.runDurationSumMs,
+      runDurationCount: row.runDurationCount,
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      costCents: row.costCents,
+      tasksCompleted: row.tasksCompleted,
+      reviewsPassed: row.reviewsPassed,
+      reviewsChangesRequested: row.reviewsChangesRequested,
+      escalations: row.escalations,
+      staleEod: row.staleEod,
+    });
+    const daily = allRows.filter((r) => r.dateKey >= startKey).map(toDay);
+    const previousDaily = allRows
+      .filter((r) => r.dateKey < startKey)
+      .map(toDay);
 
     const recentRuns = await ctx.db
       .query('taskAgentRuns')
@@ -226,22 +284,8 @@ export const getAgentScorecard = query({
       .take(20);
 
     return {
-      daily: daily.map((row) => ({
-        dateKey: row.dateKey,
-        runsStarted: row.runsStarted,
-        runsCompleted: row.runsCompleted,
-        runsFailed: row.runsFailed,
-        runDurationSumMs: row.runDurationSumMs,
-        runDurationCount: row.runDurationCount,
-        inputTokens: row.inputTokens,
-        outputTokens: row.outputTokens,
-        costCents: row.costCents,
-        tasksCompleted: row.tasksCompleted,
-        reviewsPassed: row.reviewsPassed,
-        reviewsChangesRequested: row.reviewsChangesRequested,
-        escalations: row.escalations,
-        staleEod: row.staleEod,
-      })),
+      daily,
+      previousDaily,
       recentRuns: recentRuns.map((run) => ({
         runId: run._id,
         taskId: run.taskId,
@@ -487,44 +531,49 @@ export const getProjectTaskMetrics = query({
     const access = checkProjectAccess(project, teamIds, role);
     if (!access.canRead) throw new Error('TASK_FORBIDDEN');
 
-    const { startKey } = windowKeys(args.days ?? 30);
-    const daily: Array<Doc<'taskMetricsDaily'>> = [];
+    const { startKey, prevStartKey } = windowKeys(args.days ?? 30);
+    // Scan from the previous window's start; split current vs prior period so
+    // the metrics tab can show period-over-period deltas.
+    const allRows: Array<Doc<'taskMetricsDaily'>> = [];
     for await (const row of ctx.db
       .query('taskMetricsDaily')
       .withIndex('by_org_project_date', (q) =>
         q
           .eq('organizationId', project.organizationId)
           .eq('projectId', args.projectId)
-          .gte('dateKey', startKey),
+          .gte('dateKey', prevStartKey),
       )) {
-      daily.push(row);
+      allRows.push(row);
     }
-    daily.sort((a, b) => a.dateKey.localeCompare(b.dateKey));
+    allRows.sort((a, b) => a.dateKey.localeCompare(b.dateKey));
+
+    const toDay = (row: Doc<'taskMetricsDaily'>) => ({
+      dateKey: row.dateKey,
+      tasksCreated: row.tasksCreated,
+      tasksCompleted: row.tasksCompleted,
+      tasksCancelled: row.tasksCancelled,
+      cycleTimeSumMs: row.cycleTimeSumMs,
+      cycleTimeCount: row.cycleTimeCount,
+      leadTimeSumMs: row.leadTimeSumMs,
+      leadTimeCount: row.leadTimeCount,
+      statusCountsEod: row.statusCountsEod,
+      wipEod: row.wipEod,
+      overdueEod: row.overdueEod,
+      staleEod: row.staleEod,
+      agentCompleted: row.agentCompleted,
+      humanCompleted: row.humanCompleted,
+      agentRunsStarted: row.agentRunsStarted,
+      agentRunsFailed: row.agentRunsFailed,
+      totalCostCents: row.totalCostCents,
+      reviewsPassed: row.reviewsPassed,
+      reviewsChangesRequested: row.reviewsChangesRequested,
+      escalations: row.escalations,
+      capped: row.capped,
+    });
 
     return {
-      daily: daily.map((row) => ({
-        dateKey: row.dateKey,
-        tasksCreated: row.tasksCreated,
-        tasksCompleted: row.tasksCompleted,
-        tasksCancelled: row.tasksCancelled,
-        cycleTimeSumMs: row.cycleTimeSumMs,
-        cycleTimeCount: row.cycleTimeCount,
-        leadTimeSumMs: row.leadTimeSumMs,
-        leadTimeCount: row.leadTimeCount,
-        statusCountsEod: row.statusCountsEod,
-        wipEod: row.wipEod,
-        overdueEod: row.overdueEod,
-        staleEod: row.staleEod,
-        agentCompleted: row.agentCompleted,
-        humanCompleted: row.humanCompleted,
-        agentRunsStarted: row.agentRunsStarted,
-        agentRunsFailed: row.agentRunsFailed,
-        totalCostCents: row.totalCostCents,
-        reviewsPassed: row.reviewsPassed,
-        reviewsChangesRequested: row.reviewsChangesRequested,
-        escalations: row.escalations,
-        capped: row.capped,
-      })),
+      daily: allRows.filter((r) => r.dateKey >= startKey).map(toDay),
+      previousDaily: allRows.filter((r) => r.dateKey < startKey).map(toDay),
     };
   },
 });
diff --git a/services/platform/convex/threads/generation_liveness.ts b/services/platform/convex/threads/generation_liveness.ts
new file mode 100644
index 0000000000..1e2f7cc763
--- /dev/null
+++ b/services/platform/convex/threads/generation_liveness.ts
@@ -0,0 +1,44 @@
+/**
+ * Shared "is this generation still alive?" guard.
+ *
+ * A thread's `generationStatus === 'generating'` is the lock that blocks the
+ * client UI and the new-turn gate. If the server action crashed (or was killed
+ * by a deploy / the 30-min action ceiling) without resetting it, the lock would
+ * stick forever. These helpers judge liveness against the latest sign of life so
+ * three consumers stay in lockstep:
+ *   - `isThreadGenerating` (UI unblock),
+ *   - the deploy drain count (`control/drain.ts:countActiveGenerations`),
+ *   - the recovery watchdog (`agents/recover_stuck_chat_turns.ts`).
+ * Keeping them on ONE threshold means the drain never waits on a turn the UI
+ * already considers stale, and the watchdog never finalizes one still fresh.
+ */
+
+/**
+ * Maximum time (ms) a generation is considered active before it's treated as
+ * stale. Sized to cover the longest legitimate run: self-hosted Convex actions
+ * have a 30-minute Docker ceiling, and the researcher agent runs up to ~25 min.
+ * A 5-minute buffer above the hard ceiling avoids killing the UI on slow tails.
+ *
+ * Staleness is judged against the latest sign of life — `generationStartTime`
+ * OR `generationHeartbeatAt` (bumped ~20s by the sandbox runner) — so
+ * external-agent turns that legitimately outlive this window via cross-action
+ * continuation stay "generating" as long as they keep heartbeating.
+ */
+export const GENERATION_STALE_THRESHOLD_MS = 30 * 60 * 1000 + 5 * 60 * 1000;
+
+/**
+ * A 'generating' thread counts as live when it has no liveness timestamps at
+ * all (legacy rows — preserve the historical "no startTime → not stale"
+ * semantics) or its most recent sign of life is within the threshold.
+ */
+export function isGenerationFresh(metadata: {
+  generationStartTime?: number;
+  generationHeartbeatAt?: number;
+}): boolean {
+  const lastAliveAt = Math.max(
+    metadata.generationStartTime ?? 0,
+    metadata.generationHeartbeatAt ?? 0,
+  );
+  if (lastAliveAt === 0) return true;
+  return Date.now() - lastAliveAt <= GENERATION_STALE_THRESHOLD_MS;
+}
diff --git a/services/platform/convex/threads/internal_mutations.ts b/services/platform/convex/threads/internal_mutations.ts
index cbf70ed2fd..56fbeb98cb 100644
--- a/services/platform/convex/threads/internal_mutations.ts
+++ b/services/platform/convex/threads/internal_mutations.ts
@@ -87,6 +87,14 @@ const reasoningOutcomeArgs = {
   finishReason: v.optional(v.string()),
   retried: v.optional(v.boolean()),
   qualityScore: v.optional(v.number()),
+  chosenTier: v.optional(
+    v.union(
+      v.literal('off'),
+      v.literal('low'),
+      v.literal('medium'),
+      v.literal('high'),
+    ),
+  ),
 } as const;
 
 function toReasoningOutcome(args: {
@@ -99,6 +107,7 @@ function toReasoningOutcome(args: {
   finishReason?: string;
   retried?: boolean;
   qualityScore?: number;
+  chosenTier?: ReasoningOutcome['chosenTier'];
 }): ReasoningOutcome {
   return {
     difficultyClass: args.difficultyClass,
@@ -110,6 +119,7 @@ function toReasoningOutcome(args: {
     finishReason: args.finishReason,
     retried: args.retried,
     qualityScore: args.qualityScore,
+    chosenTier: args.chosenTier,
   };
 }
 
diff --git a/services/platform/convex/threads/message_queue.ts b/services/platform/convex/threads/message_queue.ts
index 74298139c6..c3568318f8 100644
--- a/services/platform/convex/threads/message_queue.ts
+++ b/services/platform/convex/threads/message_queue.ts
@@ -10,10 +10,21 @@ import {
   query,
   type MutationCtx,
 } from '../_generated/server';
+import { isDrainingNow } from '../control/drain';
 import { canAccessThread } from '../lib/rls/auth/can_access_thread';
 import { getAuthUserIdentity } from '../lib/rls/auth/get_auth_user_identity';
 import { persistentStreaming } from '../streaming/helpers';
 
+/**
+ * While a deploy drain is active, queued messages must NOT start a new
+ * `runChatTurnGeneration` — the imminent convex recreate would kill it. Instead
+ * the drain points defer to `drainQueuedMessages` after this delay; that
+ * mutation self-reschedules while draining and fires for real once the flag
+ * clears (`endDrain`, or `drainExpiresAt` if a deploy died). Rows stay queued
+ * meanwhile (their user bubbles are already saved), so nothing is lost.
+ */
+const DRAIN_REQUEUE_DELAY_MS = 5_000;
+
 /**
  * Queue for messages sent while a turn is already running ("keep typing while
  * it works"). The timeline user message is saved at enqueue so it renders
@@ -168,6 +179,18 @@ export async function settleQueueOnTurnEnd(
   const queued = await listByStatus(ctx, meta.threadId, 'queued');
   if (queued.length === 0) return { drained: false };
 
+  // Deploy drain: don't start the drain turn now (the convex recreate would
+  // kill it). Let the ending turn finalize to idle (drained:false) and hand off
+  // to the deferred drainQueuedMessages, which resumes once the backend is back.
+  if (await isDrainingNow(ctx)) {
+    await ctx.scheduler.runAfter(
+      DRAIN_REQUEUE_DELAY_MS,
+      internal.threads.message_queue.drainQueuedMessages,
+      { threadId: meta.threadId },
+    );
+    return { drained: false };
+  }
+
   await startQueuedTurn(ctx, meta, queued);
   return { drained: true };
 }
@@ -192,6 +215,18 @@ export const drainQueuedMessages = internalMutation({
     const queued = await listByStatus(ctx, args.threadId, 'queued');
     if (queued.length === 0) return null;
 
+    // Still draining → re-defer rather than start a turn the recreate would
+    // kill. Self-rescheduling resolves once isDrainingNow clears (endDrain or
+    // drainExpiresAt backstop).
+    if (await isDrainingNow(ctx)) {
+      await ctx.scheduler.runAfter(
+        DRAIN_REQUEUE_DELAY_MS,
+        internal.threads.message_queue.drainQueuedMessages,
+        { threadId: args.threadId },
+      );
+      return null;
+    }
+
     await startQueuedTurn(ctx, meta, queued);
     return null;
   },
@@ -267,7 +302,17 @@ export const enqueueMessage = mutation({
     }
 
     // Idle (or this enqueue raced past the finalize): start the turn directly
-    // in the same transaction so the send is self-sufficient.
+    // in the same transaction so the send is self-sufficient — unless a deploy
+    // drain is active, in which case keep it queued and defer the drain so the
+    // recreate doesn't kill a turn started here.
+    if (await isDrainingNow(ctx)) {
+      await ctx.scheduler.runAfter(
+        DRAIN_REQUEUE_DELAY_MS,
+        internal.threads.message_queue.drainQueuedMessages,
+        { threadId: args.threadId },
+      );
+      return { queued: true, messageId };
+    }
     const inserted = await ctx.db.get(rowId);
     if (inserted) {
       await startQueuedTurn(ctx, meta, [...queuedRows, inserted]);
diff --git a/services/platform/convex/threads/queries.ts b/services/platform/convex/threads/queries.ts
index c34179d929..cbf4111bd6 100644
--- a/services/platform/convex/threads/queries.ts
+++ b/services/platform/convex/threads/queries.ts
@@ -7,6 +7,7 @@ import { query } from '../_generated/server';
 import { getAuthUserIdentity } from '../lib/rls';
 import { canAccessThread } from '../lib/rls/auth/can_access_thread';
 import { autoRouteReasonValidator } from '../streaming/validators';
+import { isGenerationFresh } from './generation_liveness';
 import { getThreadMessages as getThreadMessagesHelper } from './get_thread_messages';
 import { getThreadMessagesStreaming as getThreadMessagesStreamingHelper } from './get_thread_messages_streaming';
 import { listArchivedThreads as listArchivedThreadsHelper } from './list_archived_threads';
@@ -65,40 +66,6 @@ export const listArchivedThreads = query({
   },
 });
 
-/**
- * Maximum time (ms) a generation is considered active before it's treated as
- * stale. If the server-side action crashed without resetting generationStatus,
- * this prevents the client from being permanently blocked.
- *
- * Sized to cover the longest legitimate run: self-hosted Convex actions have a
- * 30-minute Docker ceiling, and the researcher agent runs up to ~25 min. A
- * 5-minute buffer above the hard ceiling avoids killing the UI on slow tails.
- *
- * Staleness is judged against the latest sign of life — `generationStartTime`
- * OR `generationHeartbeatAt` (bumped ~20s by the sandbox runner) — so
- * external-agent turns that legitimately outlive this window via cross-action
- * continuation stay "generating" as long as they keep heartbeating.
- */
-const GENERATION_STALE_THRESHOLD_MS = 30 * 60 * 1000 + 5 * 60 * 1000;
-
-/**
- * Shared stale-guard: a 'generating' thread counts as live when it has no
- * liveness timestamps at all (legacy rows — preserve the historical "no
- * startTime → not stale" semantics) or its most recent sign of life is within
- * the threshold.
- */
-function isGenerationFresh(metadata: {
-  generationStartTime?: number;
-  generationHeartbeatAt?: number;
-}): boolean {
-  const lastAliveAt = Math.max(
-    metadata.generationStartTime ?? 0,
-    metadata.generationHeartbeatAt ?? 0,
-  );
-  if (lastAliveAt === 0) return true;
-  return Date.now() - lastAliveAt <= GENERATION_STALE_THRESHOLD_MS;
-}
-
 export const isThreadGenerating = query({
   args: { threadId: v.string() },
   returns: v.boolean(),
diff --git a/services/platform/convex/threads/schema.ts b/services/platform/convex/threads/schema.ts
index 42a70efb76..c85307938c 100644
--- a/services/platform/convex/threads/schema.ts
+++ b/services/platform/convex/threads/schema.ts
@@ -16,6 +16,16 @@ const reasoningBucketValidator = v.object({
   // Response-quality EMA per class (quality-feedback governor). Optional;
   // legacy rows omit it and readers coalesce to a neutral 1.0.
   qualityEma: v.optional(v.number()),
+  // Last tier the controller settled on (effort-tier anti-oscillation guard).
+  // Optional; absence disables the guard for that bucket.
+  lastTier: v.optional(
+    v.union(
+      v.literal('off'),
+      v.literal('low'),
+      v.literal('medium'),
+      v.literal('high'),
+    ),
+  ),
 });
 
 export const threadMetadataTable = defineTable({
@@ -308,7 +318,12 @@ export const threadMetadataTable = defineTable({
   .index('by_projectId_and_userId', ['projectId', 'userId'])
   // Discussions: list a project's discussions, and a task's discussion(s).
   .index('by_kind_projectId', ['kind', 'projectId'])
-  .index('by_kind_taskId', ['kind', 'taskId']);
+  .index('by_kind_taskId', ['kind', 'taskId'])
+  // Deploy drain + recovery watchdog: enumerate the (small) set of threads
+  // currently `generating` without scanning every thread. Used by
+  // `control/drain.ts:countActiveGenerations` and
+  // `agents/recover_stuck_chat_turns.ts`.
+  .index('by_generationStatus', ['generationStatus']);
 
 /**
  * Messages sent while a turn is running (Claude-Code-TUI-style "keep typing
diff --git a/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.test.ts b/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.test.ts
index 150cbabaab..a14dfe2684 100644
--- a/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.test.ts
+++ b/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.test.ts
@@ -55,13 +55,17 @@ const baseConfig: LLMNodeConfig = {
   systemPrompt: 'sys',
 };
 
-const stubResolved = (modelId: string, providerName = 'openrouter') => ({
+const stubResolved = (
+  modelId: string,
+  providerName = 'openrouter',
+  apiKey = 'key',
+) => ({
   languageModel: { provider: 'mock' } as never,
   modelData: {
     providerName,
     modelId,
     baseUrl: 'http://example',
-    apiKey: 'key',
+    apiKey,
     apiFormat: 'openai' as const,
     tags: ['chat'],
     supportsStructuredOutputs: false,
@@ -200,6 +204,80 @@ describe('executeLLMNode chain mode', () => {
     expect(executeAgentWithTools).toHaveBeenCalledTimes(2);
   });
 
+  it('retires the credential on a deterministic error and skips same-key siblings', async () => {
+    // Two models on the same provider sharing the same key; the first hits 402.
+    vi.mocked(resolveLanguageModelById)
+      .mockResolvedValueOnce(stubResolved('a', 'openrouter', 'shared-key'))
+      .mockResolvedValueOnce(stubResolved('b', 'openrouter', 'shared-key'));
+    vi.mocked(executeAgentWithTools).mockRejectedValueOnce(
+      Object.assign(new Error('requires more credits'), { status: 402 }),
+    );
+
+    await expect(
+      executeLLMNode(
+        ctx,
+        { ...baseConfig, models: ['openrouter:a', 'openrouter:b'] },
+        {},
+        'exec1',
+        'org1',
+      ),
+    ).rejects.toThrow('requires more credits');
+    // b shares a's credential → skipped (resolved only to check scope, never run).
+    expect(executeAgentWithTools).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT skip a same-provider sibling that has its own key', async () => {
+    // a and b are both on openrouter but with DIFFERENT keys. a's 401 must not
+    // retire b — b uses an independent credential and is still tried.
+    vi.mocked(resolveLanguageModelById)
+      .mockResolvedValueOnce(stubResolved('a', 'openrouter', 'key-A'))
+      .mockResolvedValueOnce(stubResolved('b', 'openrouter', 'key-B'));
+    vi.mocked(executeAgentWithTools)
+      .mockRejectedValueOnce(
+        Object.assign(new Error('unauthorized'), { status: 401 }),
+      )
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- test stub
+      .mockResolvedValueOnce(stubLLMResult('result-b') as never);
+
+    const result = await executeLLMNode(
+      ctx,
+      { ...baseConfig, models: ['openrouter:a', 'openrouter:b'] },
+      {},
+      'exec1',
+      'org1',
+    );
+
+    expect(result.output).toBe('result-b');
+    expect(executeAgentWithTools).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips the dead credential but still tries a model on a live one', async () => {
+    // a (openrouter) hits 402 → its credential retired → b (openrouter, same
+    // key) skipped → c (openai) attempted.
+    vi.mocked(resolveLanguageModelById)
+      .mockResolvedValueOnce(stubResolved('a', 'openrouter', 'shared-key'))
+      .mockResolvedValueOnce(stubResolved('b', 'openrouter', 'shared-key'))
+      .mockResolvedValueOnce(stubResolved('c', 'openai', 'openai-key'));
+    vi.mocked(executeAgentWithTools)
+      .mockRejectedValueOnce(
+        Object.assign(new Error('insufficient credit'), { status: 402 }),
+      )
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- test stub
+      .mockResolvedValueOnce(stubLLMResult('result-c') as never);
+
+    const result = await executeLLMNode(
+      ctx,
+      { ...baseConfig, models: ['openrouter:a', 'openrouter:b', 'openai:c'] },
+      {},
+      'exec1',
+      'org1',
+    );
+
+    expect(result.output).toBe('result-c');
+    // b (dead credential) is skipped; a runs (fails) and c runs (succeeds).
+    expect(executeAgentWithTools).toHaveBeenCalledTimes(2);
+  });
+
   it('falls over when resolution itself fails (e.g. provider not found)', async () => {
     vi.mocked(resolveLanguageModelById)
       .mockRejectedValueOnce(new Error('Provider "openrouter" not found'))
diff --git a/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.ts b/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.ts
index 19950463b6..f784a0ebf6 100644
--- a/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.ts
+++ b/services/platform/convex/workflow_engine/helpers/nodes/llm/execute_llm_node.ts
@@ -7,6 +7,7 @@
 
 import { ConvexError } from 'convex/values';
 
+import { classifyChatErrorCode } from '../../../../../lib/shared/chat-errors';
 import { parseModelRef } from '../../../../../lib/shared/utils/model-ref';
 import type { Id } from '../../../../_generated/dataModel';
 import type { ActionCtx } from '../../../../_generated/server';
@@ -14,9 +15,13 @@ import { reasoningProviderOptionsFor } from '../../../../lib/agent_response/reas
 import { buildCallProviderOptions } from '../../../../lib/provider_options';
 import { recordFailure } from '../../../../providers/circuit_breaker';
 import {
+  classifyFailureScope,
   isTransientProviderError,
-  shouldFailoverToNextModel,
 } from '../../../../providers/errors';
+import {
+  isModelScopeRetired,
+  retiredScopeKey,
+} from '../../../../providers/failure_scope';
 import { resolveLanguageModelById } from '../../../../providers/resolve_model';
 import type { StepExecutionResult, LLMNodeConfig } from '../../../types';
 import { executeAgentWithTools } from './execute_agent_with_tools';
@@ -73,16 +78,79 @@ export async function executeLLMNode(
     typeof variables.userId === 'string' ? variables.userId : undefined;
 
   // Chain mode: per-attempt resolve + generate, with failover on errors.
+  //
+  // A model that fails with a DETERMINISTIC provider-level error retires the
+  // failing resource — the credential (provider + key) for funds/auth, the
+  // endpoint for an unreachable host — so its siblings are skipped, while a
+  // sibling with its own `secretsEnv` key is still tried. Resolution (no HTTP)
+  // is memoized per index so the failover lookahead doesn't pay for it twice.
   if (chainEntries.length > 0) {
     let lastError: unknown;
+    const deadScopes = new Set<string>();
+    type Resolution =
+      | {
+          ok: true;
+          resolved: Awaited<ReturnType<typeof resolveLanguageModelById>>;
+        }
+      | { ok: false; error: unknown };
+    const resolutionCache = new Map<number, Resolution>();
+    const resolveAt = async (index: number): Promise<Resolution> => {
+      const cached = resolutionCache.get(index);
+      if (cached) return cached;
+      const { providerName, modelId } = parseModelRef(chainEntries[index]);
+      let result: Resolution;
+      try {
+        result = {
+          ok: true,
+          resolved: await resolveLanguageModelById(ctx, {
+            modelId,
+            providerName,
+            organizationId,
+          }),
+        };
+      } catch (error) {
+        result = { ok: false, error };
+      }
+      resolutionCache.set(index, result);
+      return result;
+    };
+    const findNextAttemptable = async (from: number): Promise<number> => {
+      for (let i = from; i < chainEntries.length; i++) {
+        const r = await resolveAt(i);
+        if (r.ok && !isModelScopeRetired(r.resolved.modelData, deadScopes)) {
+          return i;
+        }
+      }
+      return -1;
+    };
+
     for (let attempt = 0; attempt < chainEntries.length; attempt++) {
       const ref = chainEntries[attempt];
       const { providerName, modelId } = parseModelRef(ref);
+
+      const resolution = await resolveAt(attempt);
+      if (!resolution.ok) {
+        lastError = resolution.error;
+        if (attempt < chainEntries.length - 1) {
+          console.warn(
+            `[workflow LLM] model "${ref}" failed to resolve (${
+              resolution.error instanceof Error
+                ? resolution.error.message
+                : String(resolution.error)
+            }); trying the next model`,
+          );
+          continue;
+        }
+        throw resolution.error;
+      }
+
+      // Skip a model whose credential/endpoint was already retired this chain.
+      if (isModelScopeRetired(resolution.resolved.modelData, deadScopes)) {
+        continue;
+      }
+
       try {
-        const { languageModel, modelData } = await resolveLanguageModelById(
-          ctx,
-          { modelId, providerName, organizationId },
-        );
+        const { languageModel, modelData } = resolution.resolved;
         assertChatTag(modelData, ref);
         const normalizedConfig = validateAndNormalizeConfig(
           config,
@@ -123,18 +191,30 @@ export async function executeLLMNode(
         });
       } catch (err) {
         lastError = err;
-        const hasMore = attempt < chainEntries.length - 1;
-        if (!hasMore || !shouldFailoverToNextModel(err)) throw err;
+
+        // Terminal: fails on any model — don't walk the chain.
+        if (classifyFailureScope(err) === 'terminal') throw err;
+
+        // Deterministic provider-level failure — retire the failing resource
+        // (credential for funds/auth, endpoint for an unreachable host).
+        const retired = retiredScopeKey(
+          classifyChatErrorCode(err),
+          resolution.resolved.modelData,
+        );
+        if (retired) deadScopes.add(retired);
 
         // Only transient failures count toward the circuit breaker.
         // Non-transient (401/404 config errors) are config bugs, not flakiness.
         if (isTransientProviderError(err)) {
           recordFailure(providerName ?? '', modelId);
         }
+
+        const nextIndex = await findNextAttemptable(attempt + 1);
+        if (nextIndex === -1) throw err;
         console.warn(
           `[workflow LLM] model "${ref}" failed (${
             err instanceof Error ? err.message : String(err)
-          }); falling over to "${chainEntries[attempt + 1]}"`,
+          }); falling over to "${chainEntries[nextIndex]}"`,
         );
       }
     }
diff --git a/services/platform/convex/workflows/executions/get_org_workflow_metrics.ts b/services/platform/convex/workflows/executions/get_org_workflow_metrics.ts
index dbefc94fd3..e041048952 100644
--- a/services/platform/convex/workflows/executions/get_org_workflow_metrics.ts
+++ b/services/platform/convex/workflows/executions/get_org_workflow_metrics.ts
@@ -39,8 +39,18 @@ export type OrgWorkflowTopItem = {
   lastExecution: number | null;
 };
 
+/** Prior equal-length window totals — drives the summary-card deltas. */
+export type OrgWorkflowPrevSummary = {
+  total: number;
+  completed: number;
+  failed: number;
+  successRate: number;
+  avgExecutionTimeSeconds: number;
+};
+
 export type OrgWorkflowMetrics = {
   summary: OrgWorkflowSummary;
+  previousSummary: OrgWorkflowPrevSummary;
   series: OrgWorkflowSeriesPoint[];
   topWorkflows: OrgWorkflowTopItem[];
 };
@@ -75,6 +85,8 @@ export async function getOrgWorkflowMetrics(
 ): Promise<OrgWorkflowMetrics> {
   const now = Date.now();
   const windowStart = now - args.periodDays * DAY_MS;
+  // Immediately-preceding equal-length window, for period-over-period deltas.
+  const prevWindowStart = now - args.periodDays * 2 * DAY_MS;
 
   let total = 0;
   let completed = 0;
@@ -84,6 +96,13 @@ export async function getOrgWorkflowMetrics(
   let durationCount = 0;
   let lastExecution: number | null = null;
 
+  // Prior-window accumulators (totals only — no series/buckets needed).
+  let prevTotal = 0;
+  let prevCompleted = 0;
+  let prevFailed = 0;
+  let prevDurationSumMs = 0;
+  let prevDurationCount = 0;
+
   const seriesMap = new Map<string, OrgWorkflowSeriesPoint>();
   const todayStart = utcDayStart(now);
   for (let i = args.periodDays - 1; i >= 0; i--) {
@@ -105,7 +124,21 @@ export async function getOrgWorkflowMetrics(
       capped = true;
       break;
     }
-    if (e.startedAt < windowStart) continue;
+    if (e.startedAt < prevWindowStart) continue;
+    if (e.startedAt < windowStart) {
+      // Prior window — accumulate totals only.
+      prevTotal++;
+      if (e.status === 'completed') {
+        prevCompleted++;
+        if (e.completedAt) {
+          prevDurationSumMs += e.completedAt - e.startedAt;
+          prevDurationCount++;
+        }
+      } else if (e.status === 'failed') {
+        prevFailed++;
+      }
+      continue;
+    }
 
     total++;
     if (lastExecution === null || e.startedAt > lastExecution) {
@@ -197,6 +230,16 @@ export async function getOrgWorkflowMetrics(
       lastExecution,
       capped,
     },
+    previousSummary: {
+      total: prevTotal,
+      completed: prevCompleted,
+      failed: prevFailed,
+      successRate: prevTotal > 0 ? (prevCompleted / prevTotal) * 100 : 0,
+      avgExecutionTimeSeconds:
+        prevDurationCount > 0
+          ? Math.round(prevDurationSumMs / prevDurationCount / 1000)
+          : 0,
+    },
     series: [...seriesMap.values()],
     topWorkflows,
   };
diff --git a/services/platform/lib/shared/chat-errors.test.ts b/services/platform/lib/shared/chat-errors.test.ts
new file mode 100644
index 0000000000..8b288eca44
--- /dev/null
+++ b/services/platform/lib/shared/chat-errors.test.ts
@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildHumanErrorSentence,
+  CHAT_ERROR_CODES,
+  CHAT_ERROR_I18N_KEY,
+  classifyChatErrorCode,
+  decodeChatError,
+  encodeChatError,
+  isChatErrorCode,
+  PROVIDER_SCOPED_ERROR_CODES,
+} from './chat-errors';
+
+describe('classifyChatErrorCode', () => {
+  it('classifies funds errors by status and by message', () => {
+    expect(classifyChatErrorCode({ status: 402 })).toBe('credit_exhausted');
+    expect(
+      classifyChatErrorCode({ message: 'This request requires more credits' }),
+    ).toBe('credit_exhausted');
+    expect(
+      classifyChatErrorCode({ message: 'You can only afford 10 tokens' }),
+    ).toBe('credit_exhausted');
+  });
+
+  it('classifies auth errors by 401/403 and message', () => {
+    expect(classifyChatErrorCode({ status: 401 })).toBe('auth_error');
+    expect(classifyChatErrorCode({ status: 403 })).toBe('auth_error');
+    expect(classifyChatErrorCode({ message: 'invalid api key' })).toBe(
+      'auth_error',
+    );
+  });
+
+  it('classifies model-not-found by 404 and message', () => {
+    expect(classifyChatErrorCode({ status: 404 })).toBe('model_not_found');
+    expect(
+      classifyChatErrorCode({ message: 'The model gpt-x was not found' }),
+    ).toBe('model_not_found');
+  });
+
+  it('distinguishes unreachable host from transient provider error', () => {
+    expect(classifyChatErrorCode({ code: 'ECONNREFUSED' })).toBe(
+      'provider_unreachable',
+    );
+    expect(classifyChatErrorCode({ code: 'ENOTFOUND' })).toBe(
+      'provider_unreachable',
+    );
+    expect(classifyChatErrorCode({ message: 'fetch failed' })).toBe(
+      'provider_unreachable',
+    );
+    // resets/timeouts/5xx stay transient
+    expect(classifyChatErrorCode({ code: 'ECONNRESET' })).toBe(
+      'provider_error',
+    );
+    expect(classifyChatErrorCode({ status: 503 })).toBe('provider_error');
+    expect(classifyChatErrorCode({ message: 'Request timed out' })).toBe(
+      'provider_error',
+    );
+  });
+
+  it('classifies rate limits, content filter, context length', () => {
+    expect(classifyChatErrorCode({ status: 429 })).toBe('rate_limited');
+    expect(classifyChatErrorCode({ message: 'content policy violation' })).toBe(
+      'content_filter',
+    );
+    expect(
+      classifyChatErrorCode({ message: 'maximum context length exceeded' }),
+    ).toBe('context_length');
+  });
+
+  it('prefers operator-config parameter mismatch over token_limit', () => {
+    expect(
+      classifyChatErrorCode({
+        message:
+          "Unsupported parameter: 'max_tokens'. Use 'max_completion_tokens'",
+      }),
+    ).toBe('unsupported_parameter');
+    expect(
+      classifyChatErrorCode({
+        message: 'max_tokens is too large: 32768; supports at most 16384',
+      }),
+    ).toBe('output_cap_too_high');
+  });
+
+  it('accepts a raw string and falls back to generic', () => {
+    expect(classifyChatErrorCode('429 too many requests')).toBe('rate_limited');
+    expect(classifyChatErrorCode('something weird happened')).toBe('generic');
+    expect(classifyChatErrorCode(null)).toBe('generic');
+  });
+
+  it('treats missing-provider / missing-key as missing_api_key', () => {
+    expect(
+      classifyChatErrorCode({
+        message: 'Uncaught NoProviderAvailableError: no providers',
+      }),
+    ).toBe('missing_api_key');
+    expect(
+      classifyChatErrorCode({ message: 'MissingApiKeyError: no key' }),
+    ).toBe('missing_api_key');
+  });
+});
+
+describe('PROVIDER_SCOPED_ERROR_CODES', () => {
+  it('contains exactly the deterministic provider-level codes', () => {
+    expect([...PROVIDER_SCOPED_ERROR_CODES].sort()).toEqual([
+      'auth_error',
+      'credit_exhausted',
+      'provider_unreachable',
+    ]);
+  });
+
+  it('does not include transient or model-scoped codes', () => {
+    for (const code of ['provider_error', 'rate_limited', 'model_not_found']) {
+      expect(PROVIDER_SCOPED_ERROR_CODES.has(code as never)).toBe(false);
+    }
+  });
+});
+
+describe('isChatErrorCode', () => {
+  it('accepts every declared code and rejects others', () => {
+    for (const code of CHAT_ERROR_CODES) {
+      expect(isChatErrorCode(code)).toBe(true);
+    }
+    expect(isChatErrorCode('nope')).toBe(false);
+    expect(isChatErrorCode(42)).toBe(false);
+  });
+});
+
+describe('i18n key coverage', () => {
+  it('maps every code to a base i18n key', () => {
+    for (const code of CHAT_ERROR_CODES) {
+      expect(CHAT_ERROR_I18N_KEY[code]).toMatch(/^error/);
+    }
+  });
+});
+
+describe('buildHumanErrorSentence', () => {
+  it('names the provider for funds/auth/unreachable', () => {
+    expect(
+      buildHumanErrorSentence('credit_exhausted', { provider: 'OpenRouter' }),
+    ).toContain('OpenRouter');
+    expect(
+      buildHumanErrorSentence('auth_error', { provider: 'OpenRouter' }),
+    ).toContain('OpenRouter');
+  });
+
+  it('falls back gracefully when no provider is known', () => {
+    expect(buildHumanErrorSentence('credit_exhausted')).toContain('credits');
+  });
+});
+
+describe('encodeChatError / decodeChatError', () => {
+  it('round-trips structured fields', () => {
+    const encoded = encodeChatError({
+      code: 'credit_exhausted',
+      provider: 'openrouter',
+      model: 'anthropic/claude-opus-4.8',
+      triedCount: 3,
+      raw: 'HTTP 402: requires more credits',
+    });
+    const decoded = decodeChatError(encoded);
+    expect(decoded.code).toBe('credit_exhausted');
+    expect(decoded.provider).toBe('openrouter');
+    expect(decoded.model).toBe('anthropic/claude-opus-4.8');
+    expect(decoded.triedCount).toBe(3);
+    expect(decoded.raw).toBe('HTTP 402: requires more credits');
+  });
+
+  it('survives raw messages containing newlines and special chars', () => {
+    const raw = 'line one\nline two: {"a":1}\nat /node_modules/x.ts:1:2';
+    const decoded = decodeChatError(
+      encodeChatError({ code: 'provider_error', raw }),
+    );
+    expect(decoded.code).toBe('provider_error');
+    expect(decoded.raw).toBe(raw);
+  });
+
+  it('treats legacy (un-enveloped) errors as raw only', () => {
+    const decoded = decodeChatError('plain provider error string');
+    expect(decoded.code).toBeUndefined();
+    expect(decoded.raw).toBe('plain provider error string');
+  });
+
+  it('returns empty object for undefined', () => {
+    expect(decodeChatError(undefined)).toEqual({});
+  });
+
+  it('ignores an unknown code in the envelope', () => {
+    const encoded = `TALE_ERR1 ${encodeURIComponent(
+      JSON.stringify({ code: 'bogus', provider: 'x' }),
+    )}\nraw`;
+    const decoded = decodeChatError(encoded);
+    expect(decoded.code).toBeUndefined();
+    expect(decoded.provider).toBe('x');
+    expect(decoded.raw).toBe('raw');
+  });
+});
diff --git a/services/platform/lib/shared/chat-errors.ts b/services/platform/lib/shared/chat-errors.ts
new file mode 100644
index 0000000000..a39c3f41d0
--- /dev/null
+++ b/services/platform/lib/shared/chat-errors.ts
@@ -0,0 +1,352 @@
+/**
+ * Single source of truth for chat-generation error classification, shared by
+ * the Convex backend (which classifies the real provider/SDK error object) and
+ * the React chat UI (which renders a localized, actionable message).
+ *
+ * The backend stamps a structured, machine-readable code onto the failed
+ * message via {@link encodeChatError}; the client reads it back authoritatively
+ * via {@link decodeChatError} instead of re-deriving the category by regex.
+ * Errors that predate the envelope (or come from a non-chat path) decode to
+ * `{ raw }`, and the client falls back to {@link classifyChatErrorCode} over
+ * the raw string — so the contract degrades gracefully.
+ *
+ * Pure module: no Node, no Convex, no React imports — safe in both the V8
+ * Convex runtime and the browser bundle.
+ */
+
+export const CHAT_ERROR_CODES = [
+  'missing_api_key',
+  'credit_exhausted',
+  'auth_error',
+  'model_not_found',
+  'unsupported_parameter',
+  'output_cap_too_high',
+  'token_limit',
+  'rate_limited',
+  'content_filter',
+  'context_length',
+  'tool_failure',
+  'provider_unreachable',
+  'provider_error',
+  'generic',
+] as const;
+
+export type ChatErrorCode = (typeof CHAT_ERROR_CODES)[number];
+
+export function isChatErrorCode(value: unknown): value is ChatErrorCode {
+  return (
+    typeof value === 'string' &&
+    (CHAT_ERROR_CODES as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Codes that are a property of the PROVIDER/account, not the specific model:
+ * every model on the same provider would fail the same way deterministically.
+ * The failover loop skips the rest of the provider's models when one of these
+ * occurs (see `classifyFailureScope` in convex/providers/errors.ts).
+ *
+ * Transient failures (5xx, overload, timeout, ECONNRESET, 429) are deliberately
+ * NOT here: on an aggregator a sibling model may route to a healthy upstream,
+ * and the circuit breaker already de-prioritizes repeat offenders.
+ */
+export const PROVIDER_SCOPED_ERROR_CODES: ReadonlySet<ChatErrorCode> = new Set([
+  'credit_exhausted',
+  'auth_error',
+  'provider_unreachable',
+]);
+
+/** Code → base chat i18n key (in the `chat` namespace). */
+export const CHAT_ERROR_I18N_KEY: Readonly<Record<ChatErrorCode, string>> = {
+  missing_api_key: 'errorHintMissingApiKey',
+  credit_exhausted: 'errorHintCreditExhausted',
+  auth_error: 'errorHintAuthError',
+  model_not_found: 'errorHintModelNotFound',
+  unsupported_parameter: 'errorHintUnsupportedParameter',
+  output_cap_too_high: 'errorHintOutputCapTooHigh',
+  token_limit: 'errorHintTokenLimit',
+  rate_limited: 'errorHintRateLimited',
+  content_filter: 'errorHintContentFilter',
+  context_length: 'errorHintContextLength',
+  tool_failure: 'errorHintToolFailure',
+  provider_unreachable: 'errorHintProviderUnreachable',
+  provider_error: 'errorHintProviderError',
+  generic: 'errorGeneratingDescription',
+};
+
+/**
+ * Richer "named" i18n variant used when the failing provider/model is known.
+ * Falls back to {@link CHAT_ERROR_I18N_KEY} when no name is available. Only the
+ * codes where a name materially helps the user have one.
+ */
+export const CHAT_ERROR_I18N_KEY_NAMED: Readonly<
+  Partial<Record<ChatErrorCode, string>>
+> = {
+  credit_exhausted: 'errorHintCreditExhaustedNamed',
+  auth_error: 'errorHintAuthErrorNamed',
+  provider_unreachable: 'errorHintProviderUnreachableNamed',
+  model_not_found: 'errorHintModelNotFoundNamed',
+  rate_limited: 'errorHintRateLimitedNamed',
+};
+
+interface ErrorFacts {
+  status?: number;
+  code?: string;
+  message: string;
+}
+
+function extractErrorFacts(error: unknown): ErrorFacts {
+  if (typeof error === 'string') return { message: error.toLowerCase() };
+  if (error === null || typeof error !== 'object') return { message: '' };
+
+  const err = error as Record<string, unknown>;
+  const status =
+    typeof err.status === 'number'
+      ? err.status
+      : typeof err.statusCode === 'number'
+        ? err.statusCode
+        : undefined;
+  const code = typeof err.code === 'string' ? err.code : undefined;
+  const message = typeof err.message === 'string' ? err.message : '';
+  return { status, code, message: message.toLowerCase() };
+}
+
+/**
+ * Classify a provider/SDK error (object OR raw string) into a {@link ChatErrorCode}.
+ *
+ * Order is significant — the most specific patterns win. This is the merged,
+ * canonical version of the previously-duplicated backend status logic and the
+ * client regex matcher.
+ */
+export function classifyChatErrorCode(error: unknown): ChatErrorCode {
+  const { status, code, message } = extractErrorFacts(error);
+
+  // Org has no usable provider / no API key at all — actionable setup error.
+  if (
+    /noprovideravailableerror|missingapikeyerror|no api key is configured for this organization/i.test(
+      message,
+    )
+  ) {
+    return 'missing_api_key';
+  }
+
+  // Out of funds — account-level, every model on the provider fails the same.
+  if (
+    status === 402 ||
+    /more credits|can only afford|credit.*insufficient|insufficient.*credit|never purchased credits|credit.*(limit|reached)|\b402\b/i.test(
+      message,
+    )
+  ) {
+    return 'credit_exhausted';
+  }
+
+  // Invalid / expired / unauthorized key — bad for the whole provider.
+  if (
+    status === 401 ||
+    status === 403 ||
+    /\b401\b|\b403\b|invalid.*key|expired.*key|api.?key.*invalid|unauthorized|forbidden|authentication.*fail|user not found|missing.*authentication/i.test(
+      message,
+    )
+  ) {
+    return 'auth_error';
+  }
+
+  if (
+    status === 404 ||
+    /model.*not found|model.*not available|invalid model|\b404\b/i.test(message)
+  ) {
+    return 'model_not_found';
+  }
+
+  // Operator-config parameter mismatch — must precede token_limit, whose broad
+  // `max_tokens` match would otherwise mislabel it.
+  if (
+    /unsupported parameter|is not supported with this model|unsupported_parameter|unknown parameter|unrecognized request argument/i.test(
+      message,
+    )
+  ) {
+    return 'unsupported_parameter';
+  }
+
+  // Configured output cap exceeds the model's real ceiling — must precede
+  // token_limit for the same reason.
+  if (
+    /max_tokens.*too large|too large.*max_tokens|supports at most.*completion tokens|reduce.*max_tokens/i.test(
+      message,
+    )
+  ) {
+    return 'output_cap_too_high';
+  }
+
+  if (/fewer max_tokens|token.*limit|max_tokens/i.test(message)) {
+    return 'token_limit';
+  }
+
+  if (/context.?length|context.?window|maximum context/i.test(message)) {
+    return 'context_length';
+  }
+
+  if (
+    status === 429 ||
+    /rate.?limit|too many requests|\b429\b/i.test(message)
+  ) {
+    return 'rate_limited';
+  }
+
+  if (/content.?filter|content.?policy|moderation/i.test(message)) {
+    return 'content_filter';
+  }
+
+  // Host unreachable — DNS / refused connection. Distinct from a transient
+  // provider 5xx/reset below: the endpoint itself can't be reached, so every
+  // model on the provider is dead. ECONNRESET/ETIMEDOUT are NOT here (transient).
+  if (
+    code === 'ECONNREFUSED' ||
+    code === 'ENOTFOUND' ||
+    code === 'EAI_AGAIN' ||
+    /econnrefused|enotfound|getaddrinfo|fetch failed|dns/i.test(message)
+  ) {
+    return 'provider_unreachable';
+  }
+
+  if (/tool.*error|tool.*fail|unable to complete/i.test(message)) {
+    return 'tool_failure';
+  }
+
+  // Transient provider trouble — server errors, overload, timeouts, resets.
+  if (
+    (status !== undefined && status >= 500) ||
+    code === 'ECONNRESET' ||
+    code === 'ETIMEDOUT' ||
+    /\b5\d{2}\b|server error|overloaded|capacity|service.?unavailable|internal.?error|timeout|timed out|econnreset|etimedout/i.test(
+      message,
+    )
+  ) {
+    return 'provider_error';
+  }
+
+  return 'generic';
+}
+
+/**
+ * Build a concise, human-readable English sentence for a failed turn. Used as
+ * the saved message CONTENT, which non-chat surfaces (Slack, notifications)
+ * read verbatim. The chat UI ignores this and renders the localized hint from
+ * the structured code instead.
+ */
+export function buildHumanErrorSentence(
+  code: ChatErrorCode,
+  ctx: { provider?: string; model?: string } = {},
+): string {
+  const provider = ctx.provider;
+  const model = ctx.model;
+  switch (code) {
+    case 'missing_api_key':
+      return 'No AI provider API key is configured. Add one in Settings → AI providers.';
+    case 'credit_exhausted':
+      return `${provider ? `${provider} is` : 'The AI provider is'} out of credits. Ask an administrator to add credits or switch providers.`;
+    case 'auth_error':
+      return `The API key for ${provider ?? 'the AI provider'} is invalid or expired. Ask an administrator to update it.`;
+    case 'provider_unreachable':
+      return `Could not reach ${provider ?? 'the AI provider'}. It may be down or misconfigured.`;
+    case 'model_not_found':
+      return `The model ${model ? `"${model}" ` : ''}was not found on ${provider ?? 'the provider'}. It may have been renamed or removed.`;
+    case 'rate_limited':
+      return `Rate limit reached${provider ? ` on ${provider}` : ''}. Please wait a moment and try again.`;
+    case 'content_filter':
+      return 'The request was blocked by a content filter. Try rephrasing your message.';
+    case 'context_length':
+      return 'The conversation is too long for the model’s context window. Start a new chat.';
+    case 'token_limit':
+      return 'The model’s output token limit was exceeded. Try a shorter request.';
+    case 'unsupported_parameter':
+      return 'The model rejected a request parameter — likely a provider or model configuration mismatch.';
+    case 'output_cap_too_high':
+      return 'The model’s configured max output tokens exceeds what it supports. Ask an administrator to lower it.';
+    case 'tool_failure':
+      return 'The agent hit an error while accessing data. Try rephrasing your request.';
+    case 'provider_error':
+      return `${provider ?? 'The AI provider'} is temporarily experiencing issues. Please try again shortly.`;
+    case 'generic':
+      return 'An unexpected error occurred. Try again or switch to a different model.';
+    default: {
+      const _exhaustive: never = code;
+      return _exhaustive;
+    }
+  }
+}
+
+/** Structured fields carried alongside a failed chat turn's error string. */
+interface ChatErrorInfo {
+  code?: ChatErrorCode;
+  provider?: string;
+  model?: string;
+  /** How many models were attempted before giving up. */
+  triedCount?: number;
+  /** The verbatim provider/SDK error, for the "Technical details" disclosure. */
+  raw?: string;
+}
+
+const ENVELOPE_PREFIX = 'TALE_ERR1 ';
+
+/**
+ * Encode structured error facts into a single string suitable for the message
+ * `error` field: a machine-only header line, then the raw provider message.
+ * The header is URL-encoded JSON so field values can't collide with the
+ * delimiter or contain newlines.
+ */
+export function encodeChatError(info: ChatErrorInfo): string {
+  const header = encodeURIComponent(
+    JSON.stringify({
+      code: info.code,
+      provider: info.provider,
+      model: info.model,
+      tried: info.triedCount,
+    }),
+  );
+  return `${ENVELOPE_PREFIX}${header}\n${info.raw ?? ''}`;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function asPositiveInt(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+/**
+ * Decode a message `error` string. Returns the structured fields when the
+ * envelope header is present; otherwise `{ raw: <original> }` so legacy /
+ * non-chat errors still surface their raw text for client-side fallback.
+ */
+export function decodeChatError(error: string | undefined): ChatErrorInfo {
+  if (!error) return {};
+  const newlineIdx = error.indexOf('\n');
+  const firstLine = newlineIdx >= 0 ? error.slice(0, newlineIdx) : error;
+  if (!firstLine.startsWith(ENVELOPE_PREFIX)) {
+    return { raw: error };
+  }
+  const rawTail = newlineIdx >= 0 ? error.slice(newlineIdx + 1) : '';
+  try {
+    const parsed: unknown = JSON.parse(
+      decodeURIComponent(firstLine.slice(ENVELOPE_PREFIX.length)),
+    );
+    if (parsed === null || typeof parsed !== 'object') {
+      return { raw: error };
+    }
+    const fields = parsed as Record<string, unknown>;
+    return {
+      code: isChatErrorCode(fields.code) ? fields.code : undefined,
+      provider: asString(fields.provider),
+      model: asString(fields.model),
+      triedCount: asPositiveInt(fields.tried),
+      raw: rawTail.length > 0 ? rawTail : undefined,
+    };
+  } catch {
+    // Malformed header — treat the whole thing as raw text.
+    return { raw: error };
+  }
+}
diff --git a/services/platform/lib/shared/constants/system-message-tags.ts b/services/platform/lib/shared/constants/system-message-tags.ts
index 5b11101396..6aee7d3f62 100644
--- a/services/platform/lib/shared/constants/system-message-tags.ts
+++ b/services/platform/lib/shared/constants/system-message-tags.ts
@@ -15,7 +15,7 @@ export const SYSTEM_MSG_TAG = {
   MODEL_FALLBACK: '[MODEL_FALLBACK]',
 } as const;
 
-type SystemMsgTag = (typeof SYSTEM_MSG_TAG)[keyof typeof SYSTEM_MSG_TAG];
+export type SystemMsgTag = (typeof SYSTEM_MSG_TAG)[keyof typeof SYSTEM_MSG_TAG];
 
 const TAG_REGEX = /^\[([A-Z][A-Z_]+)\]/;
 const KNOWN_TAGS = new Set<string>(Object.values(SYSTEM_MSG_TAG));
@@ -65,3 +65,51 @@ export function getSystemMessageDisplay(
   if (!tag) return 'info';
   return DISPLAY_MAP[tag];
 }
+
+/**
+ * Structured payload carried in a `[MODEL_FALLBACK]` system-message body.
+ *
+ * The backend writes it machine-readably (URL-encoded values, no localized
+ * prose) so the chat UI can render a localized line and the model auto-switch
+ * can read `to` reliably — instead of regex-scraping an English sentence.
+ */
+interface ModelFallbackBody {
+  /** The model ref that just failed. */
+  from?: string;
+  /** The next model ref being attempted ('default' for the tag-default). */
+  to?: string;
+  /** A `ChatErrorCode`-style reason the previous model failed. */
+  reason?: string;
+}
+
+export function formatModelFallbackBody(body: ModelFallbackBody): string {
+  const parts: string[] = [];
+  if (body.from) parts.push(`from=${encodeURIComponent(body.from)}`);
+  if (body.to) parts.push(`to=${encodeURIComponent(body.to)}`);
+  if (body.reason) parts.push(`reason=${encodeURIComponent(body.reason)}`);
+  return parts.join(' ');
+}
+
+/**
+ * Parse a `[MODEL_FALLBACK]` body. Returns an empty object for legacy bodies
+ * (the previous English-sentence format), so callers can fall back gracefully.
+ */
+export function parseModelFallbackBody(body: string): ModelFallbackBody {
+  const result: ModelFallbackBody = {};
+  for (const token of body.trim().split(/\s+/)) {
+    const eq = token.indexOf('=');
+    if (eq <= 0) continue;
+    const key = token.slice(0, eq);
+    const rawValue = token.slice(eq + 1);
+    let value: string;
+    try {
+      value = decodeURIComponent(rawValue);
+    } catch {
+      value = rawValue;
+    }
+    if (key === 'from') result.from = value;
+    else if (key === 'to') result.to = value;
+    else if (key === 'reason') result.reason = value;
+  }
+  return result;
+}
diff --git a/services/platform/lib/shared/model-sync.test.ts b/services/platform/lib/shared/model-sync.test.ts
index 517e5a3b62..c083acfe19 100644
--- a/services/platform/lib/shared/model-sync.test.ts
+++ b/services/platform/lib/shared/model-sync.test.ts
@@ -41,8 +41,11 @@ describe('parseModelId / compareVersions', () => {
 describe('isFlagshipChatModel', () => {
   it('accepts frontier chat models, rejects non-frontier / non-chat / noise', () => {
     expect(isFlagshipChatModel(fact('anthropic/claude-opus-4.7'))).toBe(true);
-    // Non-frontier vendor.
-    expect(isFlagshipChatModel(fact('cohere/command-r'))).toBe(false);
+    // Newly-curated frontier vendors are eligible too.
+    expect(isFlagshipChatModel(fact('amazon/nova-pro-v1'))).toBe(true);
+    expect(isFlagshipChatModel(fact('x-ai/grok-4.20'))).toBe(true);
+    // Non-frontier vendor (still outside FRONTIER_VENDORS).
+    expect(isFlagshipChatModel(fact('nousresearch/hermes-4'))).toBe(false);
     // Not a text model.
     expect(
       isFlagshipChatModel(fact('openai/gpt-image-1', { isChat: false })),
@@ -161,6 +164,24 @@ describe('syncProviderModels — add + hide', () => {
     ]);
   });
 
+  it('version-bumps a newly-curated frontier vendor (amazon)', () => {
+    const current = [chat('amazon/nova-lite-v1')];
+    const facts = [
+      fact('amazon/nova-2-lite-v1', {
+        displayName: 'Nova 2 Lite',
+        contextWindow: 1000000,
+      }),
+    ];
+    const { models, changes } = syncProviderModels({ current, facts });
+    const byId = new Map(models.map((m) => [m.id, m]));
+    expect(byId.get('amazon/nova-2-lite-v1')).toBeDefined();
+    expect(byId.get('amazon/nova-lite-v1')?.hidden).toBe(true);
+    expect(changes).toContainEqual({
+      kind: 'added',
+      modelId: 'amazon/nova-2-lite-v1',
+    });
+  });
+
   it('hides every older version of a family when a newer one is added', () => {
     const current = [
       chat('anthropic/claude-opus-4.5'),
diff --git a/services/platform/lib/shared/model-sync.ts b/services/platform/lib/shared/model-sync.ts
index a4e64f4bb5..ed671dd319 100644
--- a/services/platform/lib/shared/model-sync.ts
+++ b/services/platform/lib/shared/model-sync.ts
@@ -46,7 +46,9 @@ export interface ModelFacts {
 /**
  * Curated frontier vendors (the `vendor` prefix before `/` in a model id).
  * Only models under these prefixes are auto-added; everything else is left to
- * operators. Open- and closed-weight both included.
+ * operators. Open- and closed-weight both included. Kept in sync with the
+ * vendors curated in `builtin-configs/providers/openrouter.json` so the weekly
+ * sync version-bumps every shipped preset family.
  */
 const FRONTIER_VENDORS: readonly string[] = [
   'anthropic',
@@ -61,6 +63,14 @@ const FRONTIER_VENDORS: readonly string[] = [
   'z-ai',
   'meta-llama',
   'nvidia',
+  'xiaomi',
+  'cohere',
+  'microsoft',
+  'amazon',
+  'perplexity',
+  'ai21',
+  'rekaai',
+  'liquid',
 ];
 
 /**
diff --git a/services/platform/lib/shared/response-tuning.test.ts b/services/platform/lib/shared/response-tuning.test.ts
index 1eaed17cba..160f0314fe 100644
--- a/services/platform/lib/shared/response-tuning.test.ts
+++ b/services/platform/lib/shared/response-tuning.test.ts
@@ -1,46 +1,18 @@
 import { describe, expect, it } from 'vitest';
 
 import {
-  creativityToScoreOverride,
-  effortToTierOverride,
   styleInstructionFragment,
   tuningInstructionSuffix,
   verbosityInstructionFragment,
 } from './response-tuning';
 
-describe('response-tuning mappings', () => {
-  describe('effortToTierOverride', () => {
-    it('returns undefined for adaptive / unset (keeps the governor in charge)', () => {
-      expect(effortToTierOverride('adaptive')).toBeUndefined();
-      expect(effortToTierOverride(undefined)).toBeUndefined();
-    });
-    it('maps fixed efforts straight to reasoning tiers', () => {
-      expect(effortToTierOverride('low')).toBe('low');
-      expect(effortToTierOverride('medium')).toBe('medium');
-      expect(effortToTierOverride('high')).toBe('high');
-    });
-  });
-
-  describe('creativityToScoreOverride', () => {
-    it('returns undefined for adaptive / unset', () => {
-      expect(creativityToScoreOverride('adaptive')).toBeUndefined();
-      expect(creativityToScoreOverride(undefined)).toBeUndefined();
-    });
-    it('maps fixed creativity to a [0,1] score', () => {
-      expect(creativityToScoreOverride('precise')).toBe(0);
-      expect(creativityToScoreOverride('balanced')).toBe(0.5);
-      expect(creativityToScoreOverride('creative')).toBe(1);
-    });
-  });
-
+describe('response-tuning fragments', () => {
   describe('style + verbosity fragments', () => {
-    it('returns empty string for adaptive / unset (no prompt override)', () => {
-      expect(styleInstructionFragment('adaptive')).toBe('');
+    it('returns empty string when unset (no prompt fragment)', () => {
       expect(styleInstructionFragment(undefined)).toBe('');
-      expect(verbosityInstructionFragment('adaptive')).toBe('');
       expect(verbosityInstructionFragment(undefined)).toBe('');
     });
-    it('returns a non-empty fragment for each fixed style/verbosity', () => {
+    it('returns a non-empty fragment for each style/verbosity', () => {
       for (const style of [
         'concise',
         'detailed',
@@ -59,9 +31,6 @@ describe('response-tuning mappings', () => {
     it('is empty when nothing is set', () => {
       expect(tuningInstructionSuffix(undefined)).toBe('');
       expect(tuningInstructionSuffix({})).toBe('');
-      expect(
-        tuningInstructionSuffix({ style: 'adaptive', verbosity: 'adaptive' }),
-      ).toBe('');
     });
     it('joins style and verbosity when both set', () => {
       const out = tuningInstructionSuffix({
@@ -72,5 +41,13 @@ describe('response-tuning mappings', () => {
       expect(out).toContain('few words');
       expect(out.split('\n').length).toBe(2);
     });
+    it('renders a single fragment when only one is set', () => {
+      expect(tuningInstructionSuffix({ style: 'friendly' })).toContain(
+        'friendly',
+      );
+      expect(tuningInstructionSuffix({ verbosity: 'verbose' })).toContain(
+        'expansive',
+      );
+    });
   });
 });
diff --git a/services/platform/lib/shared/response-tuning.ts b/services/platform/lib/shared/response-tuning.ts
index ca6b818898..d4cfee5193 100644
--- a/services/platform/lib/shared/response-tuning.ts
+++ b/services/platform/lib/shared/response-tuning.ts
@@ -1,60 +1,53 @@
 /**
- * Pure helpers that translate the per-agent `responseTuning` config (see
- * `responseTuningSchema` in `./schemas/agents`) into the primitives the chat
- * backend consumes:
+ * The per-message response-shaping advice the Auto router classifier produces,
+ * and the pure helpers that turn the prose part of it into a system-prompt
+ * fragment.
  *
- *  - a FIXED reasoning-tier override (bypasses the adaptive controller),
- *  - a creativity score in [0,1] feeding the temperature governor,
- *  - effort floor/ceiling tiers that BOUND the adaptive controller,
- *  - per-difficulty thinking-budget caps,
- *  - a temperature range,
- *  - a quality-feedback preset,
- *  - system-prompt fragments for style and verbosity.
+ * Two distinct, advisory shapes — there are NO per-agent manual overrides any
+ * more; the adaptive reasoning governor (effort/temperature) and the router
+ * (style/verbosity + a reasoning seed) are the sole, automatic deciders:
  *
- * Pure and dependency-free — shared by the agent settings UI and the chat
- * backend.
+ *  - {@link ResponseStyleAdvice} — prose-level tone/depth (`style`) and length
+ *    (`verbosity`), rendered into a short instruction suffix appended to the
+ *    agent's system prompt for the turn.
+ *  - {@link ResponseReasoningSeed} — a coarse effort/creativity hint fed to the
+ *    governor as a PRIOR (blended into the difficulty score), never a hard
+ *    override. The online controller still refines from observed usage.
+ *
+ * Pure and dependency-free — the canonical home shared by the router helpers
+ * (`auto_route_helpers.ts` aliases these) and the chat backend.
  */
 
-import type { ResponseTuningConfig } from './schemas/agents';
-
 /**
- * Fixed effort → reasoning-tier override. `undefined` means "adaptive": leave
- * the governor in control. ('off' is not a valid *fixed* effort — the composer
- * only ever exposed low/medium/high — so the enum here excludes it.)
+ * Prose-level response shaping the router advises per message: tone/depth
+ * (`style`) and length (`verbosity`). `style` controls phrasing; `verbosity`
+ * targets length specifically, so both can be set together. Only emitted in
+ * Auto mode; a pinned agent's tone comes from its own `systemInstructions`.
  */
-export function effortToTierOverride(
-  effort: ResponseTuningConfig['effort'],
-): 'low' | 'medium' | 'high' | undefined {
-  if (!effort || effort === 'adaptive') return undefined;
-  return effort;
+export interface ResponseStyleAdvice {
+  style?: 'concise' | 'detailed' | 'formal' | 'friendly';
+  verbosity?: 'terse' | 'normal' | 'verbose';
 }
 
 /**
- * Fixed creativity → sampling-creativity score in [0,1]. `undefined` = adaptive
- * (difficulty-scaled). The backend feeds this into `decideTemperature`, so
- * reasoning-only models that forbid temperature still correctly omit it.
+ * Coarse per-message reasoning seed the router advises — a PRIOR for the
+ * adaptive reasoning governor, never a hard override. `effort` seeds how much
+ * step-by-step reasoning the turn gets; `creativity` seeds the sampling
+ * temperature. The governor blends these into its difficulty score on the first
+ * turn (fixing cold-start), then the online controller refines from observed
+ * reasoning-token usage + response quality, so a wrong hint self-corrects.
  */
-export function creativityToScoreOverride(
-  creativity: ResponseTuningConfig['creativity'],
-): number | undefined {
-  switch (creativity) {
-    case 'precise':
-      return 0;
-    case 'balanced':
-      return 0.5;
-    case 'creative':
-      return 1;
-    default:
-      return undefined;
-  }
+export interface ResponseReasoningSeed {
+  effort?: 'low' | 'medium' | 'high';
+  creativity?: 'precise' | 'balanced' | 'creative';
 }
 
 /**
- * Fixed style → a short system-prompt instruction fragment. Empty string means
- * "adaptive" (no override). Appended to the agent instructions for the turn.
+ * Style → a short system-prompt instruction fragment. Empty string means "no
+ * advice" (the default). Appended to the agent instructions for the turn.
  */
 export function styleInstructionFragment(
-  style: ResponseTuningConfig['style'],
+  style: ResponseStyleAdvice['style'],
 ): string {
   switch (style) {
     case 'concise':
@@ -72,11 +65,11 @@ export function styleInstructionFragment(
 
 /**
  * Verbosity → a soft length-target fragment, independent of `style`. Empty
- * string means "adaptive". `style` controls tone/depth phrasing; `verbosity`
+ * string means "no advice". `style` controls tone/depth phrasing; `verbosity`
  * targets length specifically, so both can be set together.
  */
 export function verbosityInstructionFragment(
-  verbosity: ResponseTuningConfig['verbosity'],
+  verbosity: ResponseStyleAdvice['verbosity'],
 ): string {
   switch (verbosity) {
     case 'terse':
@@ -96,12 +89,12 @@ export function verbosityInstructionFragment(
  * neither is set.
  */
 export function tuningInstructionSuffix(
-  tuning: ResponseTuningConfig | undefined,
+  advice: ResponseStyleAdvice | undefined,
 ): string {
-  if (!tuning) return '';
+  if (!advice) return '';
   const parts = [
-    styleInstructionFragment(tuning.style),
-    verbosityInstructionFragment(tuning.verbosity),
+    styleInstructionFragment(advice.style),
+    verbosityInstructionFragment(advice.verbosity),
   ].filter(Boolean);
   return parts.join('\n');
 }
diff --git a/services/platform/lib/shared/schemas/agents.test.ts b/services/platform/lib/shared/schemas/agents.test.ts
index 12bafaca2d..6865711ea1 100644
--- a/services/platform/lib/shared/schemas/agents.test.ts
+++ b/services/platform/lib/shared/schemas/agents.test.ts
@@ -1,10 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import {
-  agentJsonSchema,
-  agentRoutingSchema,
-  responseTuningSchema,
-} from './agents';
+import { agentJsonSchema, agentRoutingSchema } from './agents';
 
 const baseAgent = {
   displayName: 'Test',
@@ -12,53 +8,6 @@ const baseAgent = {
   supportedModels: ['openrouter:anthropic/claude-sonnet-4.6'],
 };
 
-describe('responseTuningSchema', () => {
-  it('accepts a full valid config', () => {
-    const r = responseTuningSchema.safeParse({
-      effort: 'high',
-      creativity: 'precise',
-      style: 'concise',
-      verbosity: 'terse',
-      effortFloor: 'low',
-      effortCeiling: 'high',
-      budgetCaps: { easy: 1024, medium: 4096, hard: 16384 },
-      temperatureRange: { min: 0.2, max: 0.8 },
-      qualityProfile: 'strict',
-    });
-    expect(r.success).toBe(true);
-  });
-
-  it('rejects temperatureRange with min > max', () => {
-    const r = responseTuningSchema.safeParse({
-      temperatureRange: { min: 0.9, max: 0.2 },
-    });
-    expect(r.success).toBe(false);
-  });
-
-  it('rejects effortFloor > effortCeiling', () => {
-    const r = responseTuningSchema.safeParse({
-      effortFloor: 'high',
-      effortCeiling: 'low',
-    });
-    expect(r.success).toBe(false);
-  });
-
-  it('rejects out-of-range budget caps', () => {
-    expect(
-      responseTuningSchema.safeParse({ budgetCaps: { easy: 1 } }).success,
-    ).toBe(false);
-    expect(
-      responseTuningSchema.safeParse({ budgetCaps: { hard: 999999 } }).success,
-    ).toBe(false);
-  });
-
-  it('rejects unknown enum values', () => {
-    expect(responseTuningSchema.safeParse({ effort: 'turbo' }).success).toBe(
-      false,
-    );
-  });
-});
-
 describe('agentRoutingSchema', () => {
   it('accepts auto selection + cascade with a draft model', () => {
     const r = agentRoutingSchema.safeParse({
@@ -75,17 +24,16 @@ describe('agentRoutingSchema', () => {
   });
 });
 
-describe('agentJsonSchema carries the new optional blocks', () => {
-  it('accepts an agent with responseTuning + routing', () => {
+describe('agentJsonSchema carries the optional routing block', () => {
+  it('accepts an agent with routing', () => {
     const r = agentJsonSchema.safeParse({
       ...baseAgent,
-      responseTuning: { effort: 'medium', qualityProfile: 'balanced' },
       routing: { modelSelection: 'auto' },
     });
     expect(r.success).toBe(true);
   });
 
-  it('still accepts an agent without them (back-compat)', () => {
+  it('still accepts an agent without it (back-compat)', () => {
     expect(agentJsonSchema.safeParse(baseAgent).success).toBe(true);
   });
 });
diff --git a/services/platform/lib/shared/schemas/agents.ts b/services/platform/lib/shared/schemas/agents.ts
index f929f45f62..d97af91c17 100644
--- a/services/platform/lib/shared/schemas/agents.ts
+++ b/services/platform/lib/shared/schemas/agents.ts
@@ -39,71 +39,6 @@ const composerModeSchema = z.object({
   order: z.number().int().optional(),
 });
 
-/**
- * Per-agent "response tuning" — the agent-author home for what was previously
- * the per-message composer menu. Every field is optional; absence (or
- * `adaptive`) leaves the Adaptive Reasoning Governor fully in charge, so an
- * agent without this block behaves exactly as before.
- *
- *  - `effort` (fixed tier) BYPASSES the adaptive controller for that turn.
- *  - `effortFloor`/`effortCeiling` keep adaptivity but BOUND it.
- *  - `verbosity`/`style` append a system-prompt fragment.
- *  - `qualityProfile` selects the quality-feedback thresholds + controller
- *    deadband preset (`lenient`/`balanced`/`strict`).
- *
- * The settings UI surfaces the common knobs above. `budgetCaps` (per-class
- * hard cap on the thinking-token budget) and `temperatureRange` (override the
- * governor's temperature band) are advanced, JSON-only knobs — kept in the
- * schema for power users editing the agent config directly, but deliberately
- * left out of the UI to keep it simple.
- */
-const EFFORT_TIER_RANK: Record<'off' | 'low' | 'medium' | 'high', number> = {
-  off: 0,
-  low: 1,
-  medium: 2,
-  high: 3,
-};
-const effortTierEnum = z.enum(['off', 'low', 'medium', 'high']);
-export const responseTuningSchema = z
-  .object({
-    effort: z.enum(['adaptive', 'low', 'medium', 'high']).optional(),
-    creativity: z
-      .enum(['adaptive', 'precise', 'balanced', 'creative'])
-      .optional(),
-    style: z
-      .enum(['adaptive', 'concise', 'detailed', 'formal', 'friendly'])
-      .optional(),
-    effortFloor: effortTierEnum.optional(),
-    effortCeiling: effortTierEnum.optional(),
-    budgetCaps: z
-      .object({
-        easy: z.number().int().min(256).max(32768).optional(),
-        medium: z.number().int().min(256).max(32768).optional(),
-        hard: z.number().int().min(256).max(32768).optional(),
-      })
-      .optional(),
-    temperatureRange: z
-      .object({
-        min: z.number().min(0).max(2).optional(),
-        max: z.number().min(0).max(2).optional(),
-      })
-      .refine((r) => r.min == null || r.max == null || r.min <= r.max, {
-        message: 'temperatureRange.min must be ≤ temperatureRange.max',
-      })
-      .optional(),
-    verbosity: z.enum(['adaptive', 'terse', 'normal', 'verbose']).optional(),
-    qualityProfile: z.enum(['lenient', 'balanced', 'strict']).optional(),
-  })
-  .refine(
-    (t) =>
-      t.effortFloor == null ||
-      t.effortCeiling == null ||
-      EFFORT_TIER_RANK[t.effortFloor] <= EFFORT_TIER_RANK[t.effortCeiling],
-    { message: 'effortFloor must be ≤ effortCeiling', path: ['effortFloor'] },
-  );
-
-export type ResponseTuningConfig = z.infer<typeof responseTuningSchema>;
-
 /**
  * Per-agent routing/cascade behaviour (opt-in; defaults preserve today's
  * config-order model selection with no cascade).
@@ -301,8 +236,6 @@ export const agentJsonSchema = z
      */
     maxIntegrationCallsPerRun: z.number().int().min(1).max(500).optional(),
     composerMode: composerModeSchema.optional(),
-    /** Per-agent response tuning; see `responseTuningSchema`. */
-    responseTuning: responseTuningSchema.optional(),
     /** Per-agent routing / cascade behaviour; see `agentRoutingSchema`. */
     routing: agentRoutingSchema.optional(),
     roleRestriction: z.literal('admin_developer').optional(),
diff --git a/services/platform/lib/utils/convex-error.test.ts b/services/platform/lib/utils/convex-error.test.ts
new file mode 100644
index 0000000000..860453da8d
--- /dev/null
+++ b/services/platform/lib/utils/convex-error.test.ts
@@ -0,0 +1,57 @@
+import { ConvexError } from 'convex/values';
+import { describe, expect, it } from 'vitest';
+
+import { convexErrorCode, convexErrorMessage } from './convex-error';
+
+describe('convexErrorCode', () => {
+  it('extracts a string code from a ConvexError', () => {
+    expect(convexErrorCode(new ConvexError({ code: 'forbidden' }))).toBe(
+      'forbidden',
+    );
+  });
+
+  it('returns undefined for non-ConvexError throws', () => {
+    expect(convexErrorCode(new Error('boom'))).toBeUndefined();
+    expect(convexErrorCode('boom')).toBeUndefined();
+    expect(convexErrorCode(undefined)).toBeUndefined();
+  });
+
+  it('returns undefined when data lacks a string code', () => {
+    expect(
+      convexErrorCode(new ConvexError({ message: 'no code' })),
+    ).toBeUndefined();
+    expect(convexErrorCode(new ConvexError({ code: 42 }))).toBeUndefined();
+    expect(
+      convexErrorCode(new ConvexError('plain string data')),
+    ).toBeUndefined();
+  });
+});
+
+describe('convexErrorMessage', () => {
+  it('extracts a string message from a ConvexError', () => {
+    expect(
+      convexErrorMessage(
+        new ConvexError({ message: 'Key already exists' }),
+        'fallback',
+      ),
+    ).toBe('Key already exists');
+  });
+
+  it('returns the fallback for non-ConvexError throws', () => {
+    expect(convexErrorMessage(new Error('boom'), 'fallback')).toBe('fallback');
+    expect(convexErrorMessage('boom', 'fallback')).toBe('fallback');
+    expect(convexErrorMessage(undefined, 'fallback')).toBe('fallback');
+  });
+
+  it('returns the fallback when data lacks a string message', () => {
+    expect(
+      convexErrorMessage(new ConvexError({ code: 'forbidden' }), 'fallback'),
+    ).toBe('fallback');
+    expect(
+      convexErrorMessage(new ConvexError({ message: 99 }), 'fallback'),
+    ).toBe('fallback');
+    expect(
+      convexErrorMessage(new ConvexError('plain string data'), 'fallback'),
+    ).toBe('fallback');
+  });
+});
diff --git a/services/platform/lib/utils/convex-error.ts b/services/platform/lib/utils/convex-error.ts
index 4e3c8b69a9..126c581dbc 100644
--- a/services/platform/lib/utils/convex-error.ts
+++ b/services/platform/lib/utils/convex-error.ts
@@ -11,3 +11,27 @@ export function convexErrorCode(err: unknown): string | undefined {
   const candidate: unknown = data.code;
   return typeof candidate === 'string' ? candidate : undefined;
 }
+
+// Extract the human-readable `{ message: string }` our Convex internal mutations
+// raise on expected failures, falling back to `fallback` for non-ConvexError
+// throws or unstructured data. Centralizes the toast-message helper that was
+// copied verbatim across several settings/chat components.
+//
+// Uses `instanceof ConvexError` to match the prior call-site behavior. A more
+// chunk-split-robust duck-typed variant lives in
+// `app/features/settings/governance/convex-error-data.ts` (Vite can emit
+// multiple ConvexError class copies, breaking instanceof) — switch to it only
+// if a regression surfaces, since that would be a behavior change.
+export function convexErrorMessage(err: unknown, fallback: string): string {
+  if (!(err instanceof ConvexError)) return fallback;
+  const data: unknown = err.data;
+  if (
+    data !== null &&
+    typeof data === 'object' &&
+    'message' in data &&
+    typeof data.message === 'string'
+  ) {
+    return data.message;
+  }
+  return fallback;
+}
diff --git a/services/platform/messages/de.json b/services/platform/messages/de.json
index 4e593c0cf9..f8ae6493be 100644
--- a/services/platform/messages/de.json
+++ b/services/platform/messages/de.json
@@ -258,7 +258,7 @@
   },
   "analytics": {
     "usage": {
-      "title": "Nutzungsanalyse",
+      "title": "Nutzungs-Metriken",
       "description": "Tokenverbrauch, Anfragen und aktive Benutzer im Zeitverlauf.",
       "cappedNotice": "Ergebnisse sind begrenzt, weil der Zeitraum zu viele Datensätze enthält. Verringere den Zeitraum für vollständige Daten.",
       "activeUsersTooltip": "Benutzer, die in diesem Zeitraum KI-Anfragen gestellt haben.",
@@ -291,7 +291,6 @@
         "activeUsers": "Aktive Benutzer"
       },
       "chart": {
-        "ariaLabel": "{metric} im Zeitverlauf",
         "inputTokens": "Eingabe",
         "outputTokens": "Ausgabe"
       },
@@ -347,7 +346,7 @@
       }
     },
     "feedback": {
-      "title": "Feedback-Analyse",
+      "title": "Feedback-Metriken",
       "description": "Daumen-Bewertungen und Arena-Urteile zu Assistenten-Antworten.",
       "commentsOnly": "Nur Kommentare",
       "errors": {
@@ -466,7 +465,8 @@
           "arena": "Arena-Paarung",
           "attribution": "Zuordnung"
         }
-      }
+      },
+      "sentimentTrend": "Stimmung im Zeitverlauf"
     }
   },
   "approvalCommon": {
@@ -616,7 +616,8 @@
       "period": {
         "last7Days": "Letzte 7 Tage",
         "last30Days": "Letzte 30 Tage",
-        "last90Days": "Letzte 90 Tage"
+        "last90Days": "Letzte 90 Tage",
+        "label": "Zeitraum"
       },
       "cards": {
         "totalRuns": "Ausführungen gesamt",
@@ -1090,7 +1091,9 @@
       "policyViolation": "Nachricht durch Inhaltsrichtlinie blockiert",
       "modelAccessDenied": "Modell nicht verfügbar",
       "budgetExceeded": "Nutzungslimit erreicht",
-      "kbRefInvalid": "Ein referenziertes Dokument ist nicht mehr verfügbar. Entferne es und versuche es erneut."
+      "kbRefInvalid": "Ein referenziertes Dokument ist nicht mehr verfügbar. Entferne es und versuche es erneut.",
+      "backendRestarting": "Server wird neu gestartet",
+      "backendRestartingDescription": "Der Server wird kurz für ein Update neu gestartet. Bitte sende deine Nachricht gleich erneut."
     },
     "blockedNotice": {
       "body": "Diese Antwort wurde durch die Inhaltsrichtlinie deiner Organisation blockiert."
@@ -1700,6 +1703,16 @@
     "errorHintTokenLimit": "Das Token-Limit des Modells wurde überschritten. Versuche eine kürzere Anfrage oder bitte deinen Administrator, die Modelleinstellungen anzupassen.",
     "errorHintToolFailure": "Der Agent hat beim Datenzugriff einen Fehler festgestellt. Versuche, deine Anfrage umzuformulieren oder weniger Daten anzufordern.",
     "errorHintUnsupportedParameter": "Das Modell hat einen der Anfrageparameter abgelehnt. Das deutet meist auf eine falsch konfigurierte Anbieter- oder Modelleinstellung hin – prüfe die Modelleinstellungen oder öffne die Details unten.",
+    "errorHintProviderUnreachable": "Der KI-Anbieter konnte nicht erreicht werden. Er ist möglicherweise offline oder falsch konfiguriert. Versuche es erneut oder kontaktiere deinen Administrator.",
+    "errorHintCreditExhaustedNamed": "{provider} hat kein Guthaben mehr. Kontaktiere deinen Administrator, um Guthaben aufzuladen oder den Anbieter zu wechseln.",
+    "errorHintAuthErrorNamed": "Der API-Schlüssel für {provider} ist ungültig oder abgelaufen. Kontaktiere deinen Administrator, um ihn zu aktualisieren.",
+    "errorHintProviderUnreachableNamed": "{provider} konnte nicht erreicht werden. Der Anbieter ist möglicherweise offline oder falsch konfiguriert. Versuche es erneut oder kontaktiere deinen Administrator.",
+    "errorHintModelNotFoundNamed": "Das ausgewählte Modell wurde bei {provider} nicht gefunden. Es wurde möglicherweise umbenannt oder entfernt.",
+    "errorHintRateLimitedNamed": "Ratenlimit bei {provider} erreicht. Bitte warte einen Moment und versuche es erneut.",
+    "errorTriedModels": "{count} Modelle wurden vor dem Abbruch versucht.",
+    "modelFallbackNotice": "{from} war nicht verfügbar – zu {to} gewechselt.",
+    "modelFallbackDefaultModel": "das Standardmodell",
+    "modelFallbackUnknown": "das vorherige Modell",
     "workspaceFiles": {
       "title": "Arbeitsbereichsdateien",
       "toggleLabel": "Arbeitsbereichsdateien",
@@ -1921,7 +1934,6 @@
       "validationStatus": "{message}: {status}",
       "skipToContent": "Zum Hauptinhalt springen",
       "mainNavigation": "Hauptnavigation",
-      "pageNavigation": "Seitennavigation",
       "projectsNavigation": "Projektnavigation"
     },
     "pagination": {
@@ -1995,8 +2007,6 @@
     "capabilityHeader": "Fähigkeiten",
     "capabilityDisable": "{name} deaktivieren",
     "requiresIntegration": "Benötigt {name}",
-    "takeScreenshot": "Screenshot aufnehmen",
-    "screenshotFailed": "Screenshot konnte nicht aufgenommen werden",
     "kbMention": {
       "title": "Wissensdatenbank",
       "loading": "Dokumente werden durchsucht …",
@@ -2096,7 +2106,9 @@
       "improving": "Wird verbessert...",
       "improveWithAi": "Mit KI verbessern",
       "generateImprovement": "Verbesserung generieren",
-      "replyImproved": "Antwort verbessert"
+      "replyImproved": "Antwort verbessert",
+      "attachFile": "Datei anhängen",
+      "send": "Nachricht senden"
     },
     "attachment": {
       "download": "Herunterladen",
@@ -2178,7 +2190,6 @@
     },
     "editCustomer": "Kunde bearbeiten",
     "deleteCustomer": "Kunde löschen",
-    "addButton": "Kunde hinzufügen",
     "importMenu": {
       "importCustomers": "Kunden importieren",
       "fromDevice": "Von deinem Gerät",
@@ -4119,7 +4130,7 @@
       "description": "Hilf dem Assistenten, sich Dinge über dich chat-übergreifend zu merken."
     },
     "environment": {
-      "title": "Umgebung & Geheimnisse",
+      "title": "Umgebungsvariablen & Geheimnisse",
       "description": "Umgebungsvariablen und Geheimnisse, die in deine Agent-Sandboxes eingespeist werden."
     },
     "organization": {
@@ -4222,10 +4233,6 @@
       "title": "Agent-Delegation",
       "description": "Agent-Delegation an andere Agents konfigurieren."
     },
-    "agentResponseTuning": {
-      "title": "Antwort-Feinabstimmung",
-      "description": "Stelle ein, wie dieser Agent denkt und schreibt."
-    },
     "automationTriggers": {
       "title": "Trigger",
       "description": "Automatisierungstrigger, Zeitpläne und Webhooks verwalten."
@@ -4252,7 +4259,8 @@
     }
   },
   "navigation": {
-    "chatWithAI": "Chat",
+    "newChat": "Neuer Chat",
+    "chat": "Chat",
     "apps": "Apps",
     "conversations": "Konversationen",
     "knowledge": "Wissen",
@@ -4388,11 +4396,14 @@
   },
   "userEnv": {
     "page": {
-      "title": "Umgebung & Geheimnisse",
+      "title": "Umgebungsvariablen & Geheimnisse",
       "description": "Variablen und Geheimnisse, die in alle deine Agent-Sandboxes eingespeist werden.",
+      "agentAccessTitle": "In deine Sandboxes eingespeist",
       "note": "Geheimnisse werden verschlüsselt und sind nur beschreibbar — nach dem Speichern werden sie nie wieder angezeigt. Diese Variablen werden in alle deine Sandboxes eingespeist."
     },
     "add": {
+      "button": "Variable hinzufügen",
+      "title": "Variable hinzufügen",
       "keyLabel": "Name",
       "keyPlaceholder": "z. B. MY_API_KEY",
       "keyInvalid": "Muss mit einem Buchstaben oder Unterstrich beginnen und darf nur Buchstaben, Zahlen und Unterstriche enthalten.",
@@ -5048,7 +5059,6 @@
         "knowledge": "Wissen",
         "webhook": "Webhook",
         "delegation": "Delegation",
-        "responseTuning": "Antwort-Feinabstimmung",
         "conversationStarters": "Gesprächseinstiege",
         "history": "Verlauf",
         "metrics": "Leistung",
@@ -5242,46 +5252,6 @@
         "fileTooLarge": "Datei zu groß",
         "removeFailed": "Datei konnte nicht entfernt werden"
       },
-      "responseTuning": {
-        "title": "Antwort-Feinabstimmung",
-        "description": "Steuere, wie dieser Agent denkt und schreibt. Jede Option steht standardmäßig auf Automatisch — die Plattform wählt dann pro Nachricht die beste Einstellung. Wähle einen festen Wert, um sie zu überschreiben.",
-        "autoNote": "Der Auto-Router und der adaptive Reasoning-Governor stimmen jede Antwort automatisch ab — Sprache, Stil, Länge und Aufwand. Normalerweise musst du hier nichts ändern. Öffne die Überschreibungen unten nur, um für jede Nachricht dieses Agenten eine feste Einstellung zu erzwingen.",
-        "overridesSummary": "Manuelle Überschreibungen",
-        "adaptive": "Automatisch",
-        "effort": "Denkaufwand",
-        "effortHelp": "Wie gründlich das Modell nachdenkt. Automatisch skaliert den Aufwand pro Nachricht — mehr bei schweren, weniger bei einfachen Fragen. Ein fester Wert nutzt immer denselben Aufwand.",
-        "effortLow": "Niedrig",
-        "effortMedium": "Mittel",
-        "effortHigh": "Hoch",
-        "creativity": "Kreativität",
-        "creativityHelp": "Wie abwechslungsreich die Formulierung ist. Präzise liefert fokussierte, wiederholbare Antworten; Kreativ liefert vielfältigere. Automatisch entscheidet pro Nachricht.",
-        "creativityPrecise": "Präzise",
-        "creativityBalanced": "Ausgewogen",
-        "creativityCreative": "Kreativ",
-        "style": "Stil",
-        "styleHelp": "Gibt Antworten einen festen Ton. Automatisch fügt keinen hinzu.",
-        "styleConcise": "Prägnant",
-        "styleDetailed": "Ausführlich",
-        "styleFormal": "Formell",
-        "styleFriendly": "Freundlich",
-        "verbosity": "Antwortlänge",
-        "verbosityHelp": "Wie lang Antworten tendenziell sind, unabhängig vom Ton. Automatisch entscheidet pro Nachricht.",
-        "verbosityTerse": "Kurz",
-        "verbosityNormal": "Mittel",
-        "verbosityVerbose": "Lang",
-        "advancedTitle": "Erweitert",
-        "advancedHelp": "Diese überschreiben Automatisch nicht — sie setzen Grenzen, in denen es bleibt, und gelten nur für oben auf Automatisch belassene Einstellungen.",
-        "qualityProfile": "Qualität vs. Tempo",
-        "qualityProfileHelp": "Wie bereitwillig der Agent zusätzliches Nachdenken einsetzt, wenn eine Antwort schwach wirkt. Streng bevorzugt Qualität; Nachsichtig bevorzugt Tempo und Kosten.",
-        "qualityLenient": "Nachsichtig",
-        "qualityBalanced": "Ausgewogen",
-        "qualityStrict": "Streng",
-        "effortFloor": "Mindestaufwand",
-        "effortFloorHelp": "Niemals weniger nachdenken als dies, auch bei einfachen Nachrichten.",
-        "effortCeiling": "Maximalaufwand",
-        "effortCeilingHelp": "Niemals mehr nachdenken als dies — begrenzt die Kosten bei schweren Nachrichten.",
-        "boundNone": "Kein Limit"
-      },
       "tools": {
         "webSearchMode": "Websuche",
         "webSearchModeDescription": "Konfigurieren, wie Websuchergebnisse abgerufen werden",
@@ -6711,7 +6681,8 @@
       "period": {
         "last7Days": "Letzte 7 Tage",
         "last30Days": "Letzte 30 Tage",
-        "last90Days": "Letzte 90 Tage"
+        "last90Days": "Letzte 90 Tage",
+        "label": "Zeitraum"
       },
       "cappedNotice": "Einige Tage haben das Scan-Limit des Rollups erreicht — die Summen in diesem Zeitraum können zu niedrig ausfallen.",
       "noData": "Keine Daten",
@@ -6944,7 +6915,6 @@
     },
     "editVendor": "Lieferant bearbeiten",
     "deleteVendor": "Lieferant löschen",
-    "addButton": "Lieferant hinzufügen",
     "importMenu": {
       "importVendors": "Lieferanten importieren",
       "fromDevice": "Von deinem Gerät",
@@ -7618,7 +7588,7 @@
       "none": "Nichts vorhanden."
     },
     "scorecard": {
-      "title": "Leistung",
+      "title": "Agent-Metriken",
       "subtitle": "Letzte 30 Tage — Ergebnisse, Review-Qualität und Kosten dieses Agenten.",
       "tasksCompleted": "Abgeschlossene Aufgaben",
       "reviewOutcome": "Direkt-Freigabequote",
@@ -7626,7 +7596,9 @@
       "avgRun": "Ø Laufzeit",
       "spend": "Ausgaben",
       "recentRuns": "Letzte Läufe",
-      "noRuns": "Noch keine Läufe."
+      "noRuns": "Noch keine Läufe.",
+      "runsCompleted": "Abgeschlossen",
+      "runsFailed": "Fehlgeschlagen"
     }
   },
   "runtimes": {
diff --git a/services/platform/messages/en.json b/services/platform/messages/en.json
index bbbdf8d424..814195aa4e 100644
--- a/services/platform/messages/en.json
+++ b/services/platform/messages/en.json
@@ -258,7 +258,7 @@
   },
   "analytics": {
     "usage": {
-      "title": "Usage Analytics",
+      "title": "Usage Metrics",
       "description": "Token consumption, requests, and active users over time.",
       "cappedNotice": "Results are capped because the time range contains too many records. Narrow the range for complete data.",
       "activeUsersTooltip": "Users who made AI requests during this period.",
@@ -291,7 +291,6 @@
         "activeUsers": "Active Users"
       },
       "chart": {
-        "ariaLabel": "{metric} over time",
         "inputTokens": "Input",
         "outputTokens": "Output"
       },
@@ -347,7 +346,7 @@
       }
     },
     "feedback": {
-      "title": "Feedback Analytics",
+      "title": "Feedback Metrics",
       "description": "User-submitted thumbs up/down and arena verdicts on assistant responses.",
       "commentsOnly": "Comments only",
       "errors": {
@@ -466,7 +465,8 @@
           "arena": "Arena pairing",
           "attribution": "Attribution"
         }
-      }
+      },
+      "sentimentTrend": "Sentiment over time"
     }
   },
   "approvalCommon": {
@@ -610,13 +610,14 @@
     },
     "metrics": {
       "link": "Metrics",
-      "title": "Automation metrics",
+      "title": "Automation Metrics",
       "description": "Usage and performance KPIs across your automations.",
       "cappedNotice": "Showing the most recent 5,000 runs in this window. Older runs in this period are not included in these totals.",
       "period": {
         "last7Days": "Last 7 days",
         "last30Days": "Last 30 days",
-        "last90Days": "Last 90 days"
+        "last90Days": "Last 90 days",
+        "label": "Period"
       },
       "cards": {
         "totalRuns": "Total runs",
@@ -1090,7 +1091,9 @@
       "policyViolation": "Message blocked by content policy",
       "modelAccessDenied": "Model not available",
       "budgetExceeded": "Usage limit reached",
-      "kbRefInvalid": "A referenced document is no longer available. Remove it and try again."
+      "kbRefInvalid": "A referenced document is no longer available. Remove it and try again.",
+      "backendRestarting": "Server is restarting",
+      "backendRestartingDescription": "The server is briefly restarting for an update. Please send your message again in a moment."
     },
     "blockedNotice": {
       "body": "This response was blocked by your organization's content policy."
@@ -1720,6 +1723,16 @@
     "errorHintTokenLimit": "The model's output token limit was exceeded. Try a shorter request or ask your administrator to adjust the model settings.",
     "errorHintToolFailure": "The agent encountered an error while accessing data. Try rephrasing your request or asking for a smaller set of data.",
     "errorHintUnsupportedParameter": "The model rejected one of the request parameters. This usually means a provider or model configuration mismatch — check the model settings, or expand the details below.",
+    "errorHintProviderUnreachable": "The AI provider could not be reached. It may be offline or misconfigured. Try again, or contact your administrator.",
+    "errorHintCreditExhaustedNamed": "{provider} is out of credits. Contact your administrator to add credits or switch providers.",
+    "errorHintAuthErrorNamed": "The API key for {provider} is invalid or expired. Contact your administrator to update it.",
+    "errorHintProviderUnreachableNamed": "{provider} could not be reached. It may be offline or misconfigured. Try again, or contact your administrator.",
+    "errorHintModelNotFoundNamed": "The selected model was not found on {provider}. It may have been renamed or removed.",
+    "errorHintRateLimitedNamed": "Rate limit reached on {provider}. Please wait a moment and try again.",
+    "errorTriedModels": "Tried {count} models before giving up.",
+    "modelFallbackNotice": "{from} was unavailable — switched to {to}.",
+    "modelFallbackDefaultModel": "the default model",
+    "modelFallbackUnknown": "the previous model",
     "liveBrowser": {
       "title": "Live browser",
       "toggleLabel": "Live browser",
@@ -1921,7 +1934,6 @@
       "validationStatus": "{message}: {status}",
       "skipToContent": "Skip to main content",
       "mainNavigation": "Main navigation",
-      "pageNavigation": "Page navigation",
       "projectsNavigation": "Projects navigation"
     },
     "pagination": {
@@ -1991,8 +2003,6 @@
   "composer": {
     "openMenu": "Open composer menu",
     "addFiles": "Add photos & files",
-    "takeScreenshot": "Take screenshot",
-    "screenshotFailed": "Couldn't capture screenshot",
     "modeHeader": "Modes",
     "capabilityHeader": "Capabilities",
     "capabilityDisable": "Disable {name}",
@@ -2096,7 +2106,9 @@
       "improving": "Improving...",
       "improveWithAi": "Improve with AI",
       "generateImprovement": "Generate improvement",
-      "replyImproved": "Reply improved"
+      "replyImproved": "Reply improved",
+      "attachFile": "Attach file",
+      "send": "Send message"
     },
     "attachment": {
       "download": "Download",
@@ -2178,7 +2190,6 @@
     },
     "editCustomer": "Edit customer",
     "deleteCustomer": "Delete customer",
-    "addButton": "Add customer",
     "importMenu": {
       "importCustomers": "Import customers",
       "fromDevice": "From your device",
@@ -4119,7 +4130,7 @@
       "description": "Help the assistant remember things about you across chats."
     },
     "environment": {
-      "title": "Environment & secrets",
+      "title": "Environment variables & secrets",
       "description": "Environment variables and secrets injected into your agent sandboxes."
     },
     "organization": {
@@ -4222,10 +4233,6 @@
       "title": "Agent delegation",
       "description": "Configure agent delegation to other agents."
     },
-    "agentResponseTuning": {
-      "title": "Response tuning",
-      "description": "Tune how this agent reasons and writes."
-    },
     "automationTriggers": {
       "title": "Triggers",
       "description": "Manage automation triggers, schedules, and webhooks."
@@ -4252,7 +4259,8 @@
     }
   },
   "navigation": {
-    "chatWithAI": "Chat",
+    "newChat": "New chat",
+    "chat": "Chat",
     "apps": "Apps",
     "conversations": "Conversations",
     "knowledge": "Knowledge",
@@ -4388,11 +4396,14 @@
   },
   "userEnv": {
     "page": {
-      "title": "Environment & secrets",
+      "title": "Environment variables & secrets",
       "description": "Variables and secrets injected into all of your agent sandboxes.",
+      "agentAccessTitle": "Injected into your sandboxes",
       "note": "Secrets are encrypted and write-only — once saved they are never shown again. These variables are injected into all of your sandboxes."
     },
     "add": {
+      "button": "Add variable",
+      "title": "Add variable",
       "keyLabel": "Name",
       "keyPlaceholder": "e.g. MY_API_KEY",
       "keyInvalid": "Must start with a letter or underscore and contain only letters, numbers, and underscores.",
@@ -5310,7 +5321,6 @@
         "knowledge": "Knowledge",
         "webhook": "Webhooks",
         "delegation": "Delegation",
-        "responseTuning": "Response tuning",
         "conversationStarters": "Starters",
         "history": "History",
         "metrics": "Performance",
@@ -5504,46 +5514,6 @@
         "fileTooLarge": "File too large",
         "removeFailed": "Failed to remove file"
       },
-      "responseTuning": {
-        "title": "Response tuning",
-        "description": "Control how this agent reasons and writes. Every option defaults to Automatic, where the platform picks the best setting for each message. Choose a fixed value to override it.",
-        "autoNote": "The Auto router and adaptive reasoning governor tune every reply automatically — language, style, length, and effort. You normally don't need to change anything here. Expand the overrides below only to force a fixed setting for every message this agent sends.",
-        "overridesSummary": "Manual overrides",
-        "adaptive": "Automatic",
-        "effort": "Reasoning effort",
-        "effortHelp": "How much the model thinks before answering. Automatic scales effort to each message — more for hard questions, less for simple ones. A fixed level applies the same effort every time.",
-        "effortLow": "Low",
-        "effortMedium": "Medium",
-        "effortHigh": "High",
-        "creativity": "Creativity",
-        "creativityHelp": "How varied the wording is. Precise gives focused, repeatable answers; Creative gives more exploratory ones. Automatic decides per message.",
-        "creativityPrecise": "Precise",
-        "creativityBalanced": "Balanced",
-        "creativityCreative": "Creative",
-        "style": "Style",
-        "styleHelp": "Gives replies a consistent tone. Automatic adds none.",
-        "styleConcise": "Concise",
-        "styleDetailed": "Detailed",
-        "styleFormal": "Formal",
-        "styleFriendly": "Friendly",
-        "verbosity": "Answer length",
-        "verbosityHelp": "How long answers tend to be, independent of tone. Automatic decides per message.",
-        "verbosityTerse": "Short",
-        "verbosityNormal": "Medium",
-        "verbosityVerbose": "Long",
-        "advancedTitle": "Advanced",
-        "advancedHelp": "These don't override Automatic — they set limits it stays within, and only apply to settings left on Automatic above.",
-        "qualityProfile": "Quality vs. speed",
-        "qualityProfileHelp": "How readily the agent spends extra reasoning when an answer looks weak. Strict favors quality; Lenient favors speed and cost.",
-        "qualityLenient": "Lenient",
-        "qualityBalanced": "Balanced",
-        "qualityStrict": "Strict",
-        "effortFloor": "Minimum effort",
-        "effortFloorHelp": "Never think less than this, even on simple messages.",
-        "effortCeiling": "Maximum effort",
-        "effortCeilingHelp": "Never think more than this — caps cost on hard messages.",
-        "boundNone": "No limit"
-      },
       "tools": {
         "webSearchMode": "Web search",
         "webSearchModeDescription": "Configure how web search results are retrieved",
@@ -6968,12 +6938,13 @@
     },
     "metrics": {
       "link": "Metrics",
-      "title": "Task metrics",
+      "title": "Task Metrics",
       "description": "Delivery, intervention, and cost KPIs for this project's tasks.",
       "period": {
         "last7Days": "Last 7 days",
         "last30Days": "Last 30 days",
-        "last90Days": "Last 90 days"
+        "last90Days": "Last 90 days",
+        "label": "Period"
       },
       "cappedNotice": "Some days hit the rollup scan cap — totals in this window may undercount.",
       "noData": "No data",
@@ -7206,7 +7177,6 @@
     },
     "editVendor": "Edit vendor",
     "deleteVendor": "Delete vendor",
-    "addButton": "Add vendor",
     "importMenu": {
       "importVendors": "Import vendors",
       "fromDevice": "From your device",
@@ -7618,7 +7588,7 @@
       "none": "Nothing here."
     },
     "scorecard": {
-      "title": "Performance",
+      "title": "Agent Metrics",
       "subtitle": "Last 30 days — outcomes, review quality, and cost for this agent.",
       "tasksCompleted": "Tasks completed",
       "reviewOutcome": "First-pass approval",
@@ -7626,7 +7596,9 @@
       "avgRun": "Avg run time",
       "spend": "Spend",
       "recentRuns": "Recent runs",
-      "noRuns": "No runs yet."
+      "noRuns": "No runs yet.",
+      "runsCompleted": "Completed",
+      "runsFailed": "Failed"
     }
   },
   "runtimes": {
@@ -7636,7 +7608,7 @@
       "cliHint": "First, install the Tale CLI if you haven't already:",
       "description": "Install once per machine: setup asks for this workspace URL, an API key, and the git workspace agents may work in. Then bind an agent to a runtime in its config — its board tasks will run on your machine and report back for review.",
       "privacy": "Local workspace paths never leave your machine — only the workspace keys you choose are advertised here. full_auto permission requires opting in on both the server and the daemon.",
-      "createKey": "Create an API key"
+      "createKey": "Create API key"
     },
     "list": {
       "title": "Connected daemons",
diff --git a/services/platform/messages/fr.json b/services/platform/messages/fr.json
index ad0ff44c16..111d497597 100644
--- a/services/platform/messages/fr.json
+++ b/services/platform/messages/fr.json
@@ -258,7 +258,7 @@
   },
   "analytics": {
     "usage": {
-      "title": "Analyse d'utilisation",
+      "title": "Métriques d'utilisation",
       "description": "Consommation de tokens, requêtes et utilisateurs actifs au fil du temps.",
       "cappedNotice": "Les résultats sont limités car la plage temporelle contient trop d'enregistrements. Réduis la plage pour obtenir des données complètes.",
       "activeUsersTooltip": "Utilisateurs ayant effectué des requêtes IA durant cette période.",
@@ -292,7 +292,6 @@
         "tokens": {}
       },
       "chart": {
-        "ariaLabel": "{metric} au fil du temps",
         "inputTokens": "Entrée",
         "outputTokens": "Sortie"
       },
@@ -348,7 +347,7 @@
       }
     },
     "feedback": {
-      "title": "Analyse des retours",
+      "title": "Métriques des retours",
       "description": "Évaluations pouce levé/baissé et verdicts d'arène sur les réponses de l'assistant.",
       "commentsOnly": "Commentaires uniquement",
       "errors": {
@@ -467,7 +466,8 @@
           "arena": "Pairing d'arène",
           "attribution": "Attribution"
         }
-      }
+      },
+      "sentimentTrend": "Sentiment au fil du temps"
     }
   },
   "approvalCommon": {
@@ -617,7 +617,8 @@
       "period": {
         "last7Days": "7 derniers jours",
         "last30Days": "30 derniers jours",
-        "last90Days": "90 derniers jours"
+        "last90Days": "90 derniers jours",
+        "label": "Période"
       },
       "cards": {
         "totalRuns": "Exécutions totales",
@@ -1091,7 +1092,9 @@
       "policyViolation": "Message bloqué par la politique de contenu",
       "modelAccessDenied": "Modèle non disponible",
       "budgetExceeded": "Limite d'utilisation atteinte",
-      "kbRefInvalid": "Un document référencé n’est plus disponible. Supprime-le et réessaie."
+      "kbRefInvalid": "Un document référencé n’est plus disponible. Supprime-le et réessaie.",
+      "backendRestarting": "Le serveur redémarre",
+      "backendRestartingDescription": "Le serveur redémarre brièvement pour une mise à jour. Merci de renvoyer ton message dans un instant."
     },
     "blockedNotice": {
       "body": "Cette réponse a été bloquée par la politique de contenu de ton organisation."
@@ -1701,6 +1704,16 @@
     "errorHintTokenLimit": "La limite de tokens en sortie du modèle a été dépassée. Essaie une requête plus courte ou demande à ton administrateur d'ajuster les paramètres du modèle.",
     "errorHintToolFailure": "L'agent a rencontré une erreur lors de l'accès aux données. Essaie de reformuler ta demande ou de demander un ensemble de données plus restreint.",
     "errorHintUnsupportedParameter": "Le modèle a rejeté l'un des paramètres de la requête. Cela indique généralement une mauvaise configuration du fournisseur ou du modèle — vérifie les paramètres du modèle ou ouvre les détails ci-dessous.",
+    "errorHintProviderUnreachable": "Le fournisseur d'IA est injoignable. Il est peut-être hors ligne ou mal configuré. Réessaie ou contacte ton administrateur.",
+    "errorHintCreditExhaustedNamed": "{provider} n'a plus de crédits. Contacte ton administrateur pour ajouter des crédits ou changer de fournisseur.",
+    "errorHintAuthErrorNamed": "La clé API de {provider} est invalide ou expirée. Contacte ton administrateur pour la mettre à jour.",
+    "errorHintProviderUnreachableNamed": "{provider} est injoignable. Le fournisseur est peut-être hors ligne ou mal configuré. Réessaie ou contacte ton administrateur.",
+    "errorHintModelNotFoundNamed": "Le modèle sélectionné est introuvable chez {provider}. Il a peut-être été renommé ou supprimé.",
+    "errorHintRateLimitedNamed": "Limite de débit atteinte chez {provider}. Merci de patienter un moment puis de réessayer.",
+    "errorTriedModels": "{count} modèles ont été essayés avant d'abandonner.",
+    "modelFallbackNotice": "{from} était indisponible — passage à {to}.",
+    "modelFallbackDefaultModel": "le modèle par défaut",
+    "modelFallbackUnknown": "le modèle précédent",
     "workspaceFiles": {
       "title": "Fichiers de l'espace de travail",
       "toggleLabel": "Fichiers de l'espace de travail",
@@ -1922,7 +1935,6 @@
       "validationStatus": "{message} : {status}",
       "skipToContent": "Aller au contenu principal",
       "mainNavigation": "Navigation principale",
-      "pageNavigation": "Navigation de page",
       "projectsNavigation": "Navigation des projets"
     },
     "pagination": {
@@ -1996,8 +2008,6 @@
     "capabilityHeader": "Capacités",
     "capabilityDisable": "Désactiver {name}",
     "requiresIntegration": "Nécessite {name}",
-    "takeScreenshot": "Faire une capture d'écran",
-    "screenshotFailed": "Impossible de faire la capture d'écran",
     "kbMention": {
       "title": "Base de connaissances",
       "loading": "Recherche de documents…",
@@ -2097,7 +2107,9 @@
       "improving": "Amélioration...",
       "improveWithAi": "Améliorer avec l'IA",
       "generateImprovement": "Générer une amélioration",
-      "replyImproved": "Réponse améliorée"
+      "replyImproved": "Réponse améliorée",
+      "attachFile": "Joindre un fichier",
+      "send": "Envoyer le message"
     },
     "attachment": {
       "download": "Télécharger",
@@ -2179,7 +2191,6 @@
     },
     "editCustomer": "Modifier le client",
     "deleteCustomer": "Supprimer le client",
-    "addButton": "Ajouter un client",
     "importMenu": {
       "importCustomers": "Importer des clients",
       "fromDevice": "Depuis ton appareil",
@@ -4120,7 +4131,7 @@
       "description": "Aide l'assistant à se souvenir de choses sur toi d'une conversation à l'autre."
     },
     "environment": {
-      "title": "Environnement et secrets",
+      "title": "Variables d'environnement et secrets",
       "description": "Variables d'environnement et secrets injectés dans tes sandboxes d'agent."
     },
     "organization": {
@@ -4223,10 +4234,6 @@
       "title": "Délégation de l'agent",
       "description": "Configure la délégation de l'agent vers d'autres agents."
     },
-    "agentResponseTuning": {
-      "title": "Réglage des réponses",
-      "description": "Règle la façon dont cet agent raisonne et rédige."
-    },
     "automationTriggers": {
       "title": "Déclencheurs",
       "description": "Gère les déclencheurs, planifications et webhooks d'automatisation."
@@ -4253,7 +4260,8 @@
     }
   },
   "navigation": {
-    "chatWithAI": "Chat",
+    "newChat": "Nouveau chat",
+    "chat": "Chat",
     "apps": "Applications",
     "conversations": "Conversations",
     "knowledge": "Connaissances",
@@ -4389,11 +4397,14 @@
   },
   "userEnv": {
     "page": {
-      "title": "Environnement et secrets",
+      "title": "Variables d'environnement et secrets",
       "description": "Variables et secrets injectés dans toutes tes sandboxes d'agent.",
+      "agentAccessTitle": "Injectés dans tes sandboxes",
       "note": "Les secrets sont chiffrés et en écriture seule — une fois enregistrés, ils ne sont plus jamais affichés. Ces variables sont injectées dans toutes tes sandboxes."
     },
     "add": {
+      "button": "Ajouter une variable",
+      "title": "Ajouter une variable",
       "keyLabel": "Nom",
       "keyPlaceholder": "ex. MY_API_KEY",
       "keyInvalid": "Doit commencer par une lettre ou un trait de soulignement et ne contenir que des lettres, des chiffres et des traits de soulignement.",
@@ -5049,7 +5060,6 @@
         "knowledge": "Base de connaissances",
         "webhook": "Webhooks",
         "delegation": "Délégation",
-        "responseTuning": "Réglage des réponses",
         "conversationStarters": "Amorces",
         "history": "Historique",
         "metrics": "Performance",
@@ -5243,46 +5253,6 @@
         "fileTooLarge": "Fichier trop volumineux",
         "removeFailed": "Échec du retrait du fichier"
       },
-      "responseTuning": {
-        "title": "Réglage des réponses",
-        "description": "Détermine comment cet agent raisonne et rédige. Chaque option est sur Automatique par défaut — la plateforme choisit alors le meilleur réglage pour chaque message. Choisis une valeur fixe pour la remplacer.",
-        "autoNote": "Le routeur Auto et le gouverneur de raisonnement adaptatif ajustent chaque réponse automatiquement — langue, style, longueur et effort. En général, tu n'as rien à modifier ici. Développe les remplacements ci-dessous uniquement pour imposer un réglage fixe à chaque message envoyé par cet agent.",
-        "overridesSummary": "Remplacements manuels",
-        "adaptive": "Automatique",
-        "effort": "Effort de raisonnement",
-        "effortHelp": "À quel point le modèle réfléchit. Automatique ajuste l'effort à chaque message — davantage pour les questions difficiles, moins pour les simples. Une valeur fixe applique toujours le même effort.",
-        "effortLow": "Faible",
-        "effortMedium": "Moyen",
-        "effortHigh": "Élevé",
-        "creativity": "Créativité",
-        "creativityHelp": "À quel point la formulation varie. Précis donne des réponses ciblées et reproductibles ; Créatif en donne de plus exploratoires. Automatique décide par message.",
-        "creativityPrecise": "Précis",
-        "creativityBalanced": "Équilibré",
-        "creativityCreative": "Créatif",
-        "style": "Style",
-        "styleHelp": "Donne un ton constant aux réponses. Automatique n'en ajoute aucun.",
-        "styleConcise": "Concis",
-        "styleDetailed": "Détaillé",
-        "styleFormal": "Formel",
-        "styleFriendly": "Amical",
-        "verbosity": "Longueur des réponses",
-        "verbosityHelp": "La longueur habituelle des réponses, indépendamment du ton. Automatique décide par message.",
-        "verbosityTerse": "Courte",
-        "verbosityNormal": "Moyenne",
-        "verbosityVerbose": "Longue",
-        "advancedTitle": "Avancé",
-        "advancedHelp": "Ceci ne remplace pas Automatique — ces options fixent des limites qu'il respecte, et ne s'appliquent qu'aux réglages laissés sur Automatique ci-dessus.",
-        "qualityProfile": "Qualité vs. rapidité",
-        "qualityProfileHelp": "À quel point l'agent ajoute du raisonnement quand une réponse semble faible. Strict privilégie la qualité ; Indulgent privilégie la rapidité et le coût.",
-        "qualityLenient": "Indulgent",
-        "qualityBalanced": "Équilibré",
-        "qualityStrict": "Strict",
-        "effortFloor": "Effort minimal",
-        "effortFloorHelp": "Ne jamais réfléchir moins que cela, même pour les messages simples.",
-        "effortCeiling": "Effort maximal",
-        "effortCeilingHelp": "Ne jamais réfléchir plus que cela — limite le coût sur les messages difficiles.",
-        "boundNone": "Aucune limite"
-      },
       "tools": {
         "webSearchMode": "Recherche web",
         "webSearchModeDescription": "Configure la façon dont les résultats de recherche web sont récupérés",
@@ -6712,7 +6682,8 @@
       "period": {
         "last7Days": "7 derniers jours",
         "last30Days": "30 derniers jours",
-        "last90Days": "90 derniers jours"
+        "last90Days": "90 derniers jours",
+        "label": "Période"
       },
       "cappedNotice": "Certains jours ont atteint la limite de scan du rollup — les totaux de cette période peuvent être sous-estimés.",
       "noData": "Aucune donnée",
@@ -6945,7 +6916,6 @@
     },
     "editVendor": "Modifier le fournisseur",
     "deleteVendor": "Supprimer le fournisseur",
-    "addButton": "Ajouter un fournisseur",
     "importMenu": {
       "importVendors": "Importer des fournisseurs",
       "fromDevice": "Depuis ton appareil",
@@ -7619,7 +7589,7 @@
       "none": "Rien ici."
     },
     "scorecard": {
-      "title": "Performance",
+      "title": "Métriques de l'agent",
       "subtitle": "Les 30 derniers jours — résultats, qualité des revues et coûts de cet agent.",
       "tasksCompleted": "Tâches terminées",
       "reviewOutcome": "Approbation du premier coup",
@@ -7627,7 +7597,9 @@
       "avgRun": "Durée moyenne d'exécution",
       "spend": "Dépenses",
       "recentRuns": "Exécutions récentes",
-      "noRuns": "Pas encore d'exécutions."
+      "noRuns": "Pas encore d'exécutions.",
+      "runsCompleted": "Terminées",
+      "runsFailed": "Échouées"
     }
   },
   "runtimes": {
diff --git a/services/platform/scripts/dev-engine.ts b/services/platform/scripts/dev-engine.ts
index 6b98625ff3..bd4cf00a0e 100644
--- a/services/platform/scripts/dev-engine.ts
+++ b/services/platform/scripts/dev-engine.ts
@@ -449,6 +449,73 @@ function probeDocker(
   });
 }
 
+/** Launch the Docker engine for the host OS, fire-and-forget — the engine then
+ *  comes up asynchronously (which {@link startDockerDaemon} polls for). Returns
+ *  whether the launch command itself succeeded. Mirrors the per-OS launch in the
+ *  CLI's ensureDocker (tools/cli/src/lib/docker/ensure-docker.ts): `open -a
+ *  Docker` on macOS, Start-Process on Windows, `systemctl start docker` on Linux.
+ *  The Linux path uses `sudo -n` so it FAILS FAST when passwordless sudo isn't
+ *  configured, rather than hanging the boot on a hidden password prompt. */
+function launchDockerEngine(): boolean {
+  try {
+    if (process.platform === 'darwin') {
+      return (
+        spawnSync('open', ['-a', 'Docker'], { stdio: 'ignore' }).status === 0
+      );
+    }
+    if (process.platform === 'win32') {
+      return (
+        spawnSync(
+          'powershell',
+          [
+            '-NoProfile',
+            '-Command',
+            'Start-Process -FilePath "$env:ProgramFiles\\Docker\\Docker\\Docker Desktop.exe"',
+          ],
+          { stdio: 'ignore' },
+        ).status === 0
+      );
+    }
+    // Linux: the engine runs as a privileged systemd service. `-n` makes sudo
+    // fail immediately (instead of prompting) when passwordless sudo is absent.
+    return (
+      spawnSync('sudo', ['-n', 'systemctl', 'start', 'docker'], {
+        stdio: 'ignore',
+      }).status === 0
+    );
+  } catch (err) {
+    warnLine(
+      `Could not start the Docker engine: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
+
+/** Wake a stopped Docker engine so `bun dev` doesn't dead-end when Docker Desktop
+ *  just isn't running — the common case on a dev machine. Launches it (see
+ *  {@link launchDockerEngine}) then polls until it answers or ~60s elapse.
+ *  Best-effort and non-fatal: returns the re-probed status; the caller degrades
+ *  to a warning when it stays down. */
+async function startDockerDaemon(): Promise<'ok' | 'no-daemon'> {
+  const ready = await runStep(
+    { active: 'Starting the Docker engine', done: 'Docker engine started' },
+    async () => {
+      if (!launchDockerEngine()) {
+        throw new StepWarning(
+          'could not launch it (start Docker manually if this keeps happening)',
+        );
+      }
+      const deadline = Date.now() + 60_000;
+      while (Date.now() < deadline) {
+        if ((await probeDocker(5_000)) === 'ok') return true;
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+      }
+      throw new StepWarning('the engine did not come up within 60s');
+    },
+  );
+  return ready ? 'ok' : 'no-daemon';
+}
+
 /** Probe the bifrost gateway on its host-published loopback port until it
  *  accepts connections — this is the axis that breaks when the dev overlay's
  *  port binding is missing. Honours BIFROST_URL; warn-and-continue on timeout. */
@@ -494,8 +561,11 @@ async function waitForBifrostGateway(
  *  `up` it recreates whatever config drifted (bifrost gains its port, the rest
  *  gain source mounts / extra_hosts) — the intended convergence to dev config.
  *
- *  Docker absent is NON-FATAL: warn with the concrete side-effects and let the
- *  app come up anyway (pure frontend/Convex work doesn't need the gateway). */
+ *  A stopped engine is auto-started first (Docker Desktop / systemd) so a dev
+ *  machine where Docker simply isn't running doesn't have to start it by hand.
+ *  Docker absent (or unstartable) is NON-FATAL: warn with the concrete
+ *  side-effects and let the app come up anyway (pure frontend/Convex work
+ *  doesn't need it). */
 async function ensureDockerDependencies(): Promise<void> {
   // The hermetic E2E stack (playwright.config.ts) is anonymous-Convex + mock
   // LLM with "no external services" — the backing images aren't built in the
@@ -503,7 +573,7 @@ async function ensureDockerDependencies(): Promise<void> {
   // wastes the cold-boot budget and destabilizes the Convex pre-warm that
   // follows. Let the E2E webServer opt out explicitly.
   if (isTruthy(process.env.TALE_DEV_SKIP_DOCKER)) {
-    infoLine('Skipping docker backing services (TALE_DEV_SKIP_DOCKER set)');
+    infoLine('Skipping Docker backing services (TALE_DEV_SKIP_DOCKER set)');
     return;
   }
 
@@ -529,15 +599,22 @@ async function ensureDockerDependencies(): Promise<void> {
   // around the pipe. Explicit override still wins.
   process.env.BUILDKIT_PROGRESS ??= 'plain';
 
-  const status = await probeDocker(10_000);
+  let status = await probeDocker(10_000);
+  // CLI present but the engine is down: try to start it instead of dead-ending —
+  // the common case on a dev machine where Docker Desktop simply isn't running.
+  if (status === 'no-daemon') {
+    status = await startDockerDaemon();
+  }
   if (status !== 'ok') {
-    const why =
-      status === 'no-binary'
-        ? 'Docker is not installed'
-        : 'Docker daemon is not running / unreachable';
-    warnLine(`${why} — skipping docker backing services.`);
+    // A failed start already explained itself via startDockerDaemon's warning;
+    // only the not-installed case still needs a warning here.
+    if (status === 'no-binary') {
+      warnLine(
+        'Docker is not installed — continuing without the backing services.',
+      );
+    }
     infoLine(
-      'Until started: the LLM gateway (bifrost) is unreachable (external agents / chat fail), the sandbox is down (no agent code execution), and db / knowledge-db are down (no knowledge base / RAG).',
+      "While the backing services are down: chat and external agents fail (no LLM gateway), agents can't run code (no sandbox), and the knowledge base / RAG is unavailable (no db).",
     );
     infoLine(
       `Start them with: docker ${dockerComposeArgs(['up', '-d', ...DEV_DOCKER_SERVICES]).join(' ')}`,
@@ -690,7 +767,7 @@ export async function runDevFleet() {
   infoLine('Starting Tale dev environment');
   if (useExternalConvex) {
     infoLine(
-      `Convex: external (${process.env.CONVEX_URL || 'http://127.0.0.1:3210'})`,
+      `Using external Convex (${process.env.CONVEX_URL || 'http://127.0.0.1:3210'})`,
     );
   }
 
@@ -766,7 +843,7 @@ export async function runDevFleet() {
     // the READY banner below. Everything between "Starting" and here is silent,
     // so this lands as the second line the developer sees.
     infoLine(
-      `Cold start can take 30-90s; ${appUrl} is unreachable until the READY banner below.`,
+      `Cold start takes 30-90s — ${appUrl} won't load until the READY banner below.`,
     );
 
     // Bring up the docker backing stack (gateway, sandbox, db, knowledge-db)
diff --git a/services/platform/scripts/update-model-catalog.ts b/services/platform/scripts/update-model-catalog.ts
index 3acb0e58e4..9c9649845a 100644
Binary files a/services/platform/scripts/update-model-catalog.ts and b/services/platform/scripts/update-model-catalog.ts differ
diff --git a/services/platform/tests/e2e/fixtures/config/default/agents/assistant.json b/services/platform/tests/e2e/fixtures/config/default/agents/assistant.json
index 562ff3bd2d..ab1c3c39d5 100644
--- a/services/platform/tests/e2e/fixtures/config/default/agents/assistant.json
+++ b/services/platform/tests/e2e/fixtures/config/default/agents/assistant.json
@@ -10,5 +10,6 @@
   "structuredResponsesEnabled": false,
   "toolNames": ["request_human_input"],
   "maxSteps": 1,
-  "timeoutMs": 120000
+  "timeoutMs": 120000,
+  "metadata": { "autoInstall": true }
 }
diff --git a/services/platform/tests/e2e/fixtures/config/default/apps/.gitkeep b/services/platform/tests/e2e/fixtures/config/default/apps/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/services/platform/tests/e2e/fixtures/config/default/branding/.gitkeep b/services/platform/tests/e2e/fixtures/config/default/branding/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/services/platform/tests/e2e/fixtures/config/default/governance/.gitkeep b/services/platform/tests/e2e/fixtures/config/default/governance/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/services/platform/tests/e2e/fixtures/config/default/skills/.gitkeep b/services/platform/tests/e2e/fixtures/config/default/skills/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/services/platform/tests/e2e/specs/agent-editor.spec.ts b/services/platform/tests/e2e/specs/agent-editor.spec.ts
index 89afdb97e3..4a3cf7c129 100644
--- a/services/platform/tests/e2e/specs/agent-editor.spec.ts
+++ b/services/platform/tests/e2e/specs/agent-editor.spec.ts
@@ -179,52 +179,6 @@ test.describe('agent editor depth', () => {
     await expect(reloaded).toHaveValue(newText, { timeout: TIMEOUT.PERSIST });
   });
 
-  test('response tuning: overrides reasoning effort, saves, persists', async ({
-    page,
-    org,
-  }) => {
-    await openAgentTab(page, org.organizationId, 'response-tuning');
-    await expect(
-      page.getByRole('heading', {
-        name: t('settings.agents.responseTuning.title'),
-        level: 2,
-      }),
-    ).toBeVisible({ timeout: TIMEOUT.VISIBLE });
-
-    // The overrides live inside a collapsed <details>; expand it.
-    await page
-      .getByText(t('settings.agents.responseTuning.overridesSummary'))
-      .click();
-
-    // "Medium" also appears in the floor/ceiling groups, so scope to the
-    // "Reasoning effort" radiogroup.
-    const effortGroup = page.getByRole('radiogroup', {
-      name: t('settings.agents.responseTuning.effort'),
-    });
-    await effortGroup
-      .getByRole('radio', {
-        name: t('settings.agents.responseTuning.effortMedium'),
-        exact: true,
-      })
-      .click();
-    await saveAndExpectToast(page);
-
-    await page.reload();
-    await page
-      .getByText(t('settings.agents.responseTuning.overridesSummary'))
-      .click();
-    await expect(
-      page
-        .getByRole('radiogroup', {
-          name: t('settings.agents.responseTuning.effort'),
-        })
-        .getByRole('radio', {
-          name: t('settings.agents.responseTuning.effortMedium'),
-          exact: true,
-        }),
-    ).toBeChecked({ timeout: TIMEOUT.PERSIST });
-  });
-
   test('conversation starters: adds a starter, saves, persists', async ({
     page,
     org,
diff --git a/services/platform/tests/e2e/specs/agents.spec.ts b/services/platform/tests/e2e/specs/agents.spec.ts
index e994370256..606df695de 100644
--- a/services/platform/tests/e2e/specs/agents.spec.ts
+++ b/services/platform/tests/e2e/specs/agents.spec.ts
@@ -48,7 +48,6 @@ test('lists the seeded agent and opens its editor tab navigation', async ({
     'settings.agents.navigation.skills',
     'settings.agents.navigation.knowledge',
     'settings.agents.navigation.delegation',
-    'settings.agents.navigation.responseTuning',
     'settings.agents.navigation.conversationStarters',
     'settings.agents.navigation.webhook',
   ]) {
diff --git a/services/platform/tests/e2e/specs/automation-editor.spec.ts b/services/platform/tests/e2e/specs/automation-editor.spec.ts
index 817ed590e4..8044fe1788 100644
--- a/services/platform/tests/e2e/specs/automation-editor.spec.ts
+++ b/services/platform/tests/e2e/specs/automation-editor.spec.ts
@@ -64,12 +64,20 @@ test.describe.serial('automation editor', () => {
     );
 
     // The bottom-center canvas toolbar carries the add-step and test controls —
-    // a stable signal the flow editor (not a skeleton) mounted.
+    // a stable signal the flow editor (not a skeleton) mounted. The shared
+    // Button suppresses the native `title` attribute (it routes `title` into
+    // aria-label + a tooltip), so locate by role + accessible name, not title.
     await expect(
-      page.getByTitle(t('automations.steps.toolbar.addStep')),
+      page.getByRole('button', {
+        name: t('automations.steps.toolbar.addStep'),
+        exact: true,
+      }),
     ).toBeVisible({ timeout: TIMEOUT.VISIBLE });
     await expect(
-      page.getByTitle(t('automations.steps.toolbar.testAutomation')),
+      page.getByRole('button', {
+        name: t('automations.steps.toolbar.testAutomation'),
+        exact: true,
+      }),
     ).toBeVisible({ timeout: TIMEOUT.VISIBLE });
   });
 
@@ -129,9 +137,10 @@ test.describe.serial('automation editor', () => {
       `/dashboard/${organizationId}/automations/${automationSlug}`,
     );
 
-    const openTester = page.getByTitle(
-      t('automations.steps.toolbar.testAutomation'),
-    );
+    const openTester = page.getByRole('button', {
+      name: t('automations.steps.toolbar.testAutomation'),
+      exact: true,
+    });
     await expect(openTester).toBeEnabled({ timeout: TIMEOUT.FIRST_PAINT });
     await openTester.click();
 
diff --git a/services/platform/tests/e2e/specs/automation.spec.ts b/services/platform/tests/e2e/specs/automation.spec.ts
index 21280198c9..3721490335 100644
--- a/services/platform/tests/e2e/specs/automation.spec.ts
+++ b/services/platform/tests/e2e/specs/automation.spec.ts
@@ -44,10 +44,13 @@ test('runs the seeded test automation to completion', async ({ page, org }) => {
     timeout: TIMEOUT.NAV,
   });
 
-  // The editor toolbar's flask button opens the tester side panel.
-  const openTester = page.getByTitle(
-    t('automations.steps.toolbar.testAutomation'),
-  );
+  // The editor toolbar's flask button opens the tester side panel. The shared
+  // Button suppresses the native `title` attribute (it routes `title` into
+  // aria-label + a tooltip), so locate by role + accessible name, not title.
+  const openTester = page.getByRole('button', {
+    name: t('automations.steps.toolbar.testAutomation'),
+    exact: true,
+  });
   await expect(openTester).toBeEnabled({ timeout: TIMEOUT.VISIBLE });
   await openTester.click();
 
diff --git a/services/platform/tests/e2e/specs/chat-threads.spec.ts b/services/platform/tests/e2e/specs/chat-threads.spec.ts
index dcce5f70d0..0d8adbb6f6 100644
--- a/services/platform/tests/e2e/specs/chat-threads.spec.ts
+++ b/services/platform/tests/e2e/specs/chat-threads.spec.ts
@@ -37,10 +37,14 @@ test('starts a thread, reopens it by URL, then deletes it', async ({
     page.getByText(t('chat.chatsSection'), { exact: true }).first(),
   ).toBeVisible({ timeout: TIMEOUT.VISIBLE });
 
-  // Leave the thread, then re-open it by URL — a deterministic "open from
-  // history" that doesn't depend on the auto-generated title.
+  // Leave the thread via the side-nav "New chat" rail link (the header button
+  // was removed; new chat now lives on the rail + a global shortcut). The rail
+  // links are icon-only, so scope to the nav landmark and target the chat href.
+  // Then re-open by URL — a deterministic "open from history" that doesn't
+  // depend on the auto-generated title.
   await page
-    .getByRole('button', { name: t('chat.newChat') })
+    .getByRole('navigation', { name: t('common.aria.mainNavigation') })
+    .locator(`a[href$="/dashboard/${organizationId}/chat"]`)
     .first()
     .click();
   await page.waitForURL(/\/chat(?:[/?#]|$)/, { timeout: TIMEOUT.NAV });
diff --git a/services/platform/tests/e2e/specs/navigation.spec.ts b/services/platform/tests/e2e/specs/navigation.spec.ts
index 4c11804ab4..5e674ff77d 100644
--- a/services/platform/tests/e2e/specs/navigation.spec.ts
+++ b/services/platform/tests/e2e/specs/navigation.spec.ts
@@ -42,9 +42,14 @@ function navLinkByHref(page: Page, hrefSuffix: string): Locator {
   return primaryNav(page).locator(`a[href$="${hrefSuffix}"]`);
 }
 
-/** "New chat" renders in both the desktop bar and mobile header; pin the first. */
-function newChatButton(page: Page): Locator {
-  return page.getByRole('button', { name: t('chat.newChat') }).first();
+/**
+ * The chat surface is settled once its header search control renders. (New chat
+ * is no longer a header button — it lives on the side-nav rail and a global
+ * shortcut — so the search control is the stable "we're on chat" anchor.) It
+ * renders in both the desktop bar and mobile header; pin the first (visible).
+ */
+function chatSurfaceAnchor(page: Page): Locator {
+  return page.getByRole('button', { name: t('chat.searchChat') }).first();
 }
 
 interface NavCase {
@@ -137,7 +142,7 @@ test.describe('navigation: primary side-nav rail', () => {
     await page.waitForURL(/\/chat(?:[/?#]|$)/, {
       timeout: TIMEOUT.FIRST_PAINT,
     });
-    await expect(newChatButton(page)).toBeVisible({
+    await expect(chatSurfaceAnchor(page)).toBeVisible({
       timeout: TIMEOUT.FIRST_PAINT,
     });
     await expect(primaryNav(page)).toBeVisible({ timeout: TIMEOUT.VISIBLE });
@@ -159,7 +164,9 @@ test.describe('navigation: primary side-nav rail', () => {
       .first()
       .click();
     await page.waitForURL(/\/chat(?:[/?#]|$)/, { timeout: TIMEOUT.NAV });
-    await expect(newChatButton(page)).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+    await expect(chatSurfaceAnchor(page)).toBeVisible({
+      timeout: TIMEOUT.VISIBLE,
+    });
   });
 });
 
@@ -286,7 +293,9 @@ test.describe('navigation: 404 and history', () => {
     await page.waitForURL(/\/chat(?:[/?#]|$)/, {
       timeout: TIMEOUT.FIRST_PAINT,
     });
-    await expect(newChatButton(page)).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+    await expect(chatSurfaceAnchor(page)).toBeVisible({
+      timeout: TIMEOUT.VISIBLE,
+    });
 
     // Step 2: deep-link into a nested settings page (a distinct history entry).
     await page.goto(dashboardUrl(organizationId, '/settings/account'));
@@ -303,7 +312,9 @@ test.describe('navigation: 404 and history', () => {
     // Back → chat surface (URL + content track the history pop).
     await page.goBack();
     await page.waitForURL(/\/chat(?:[/?#]|$)/, { timeout: TIMEOUT.NAV });
-    await expect(newChatButton(page)).toBeVisible({ timeout: TIMEOUT.VISIBLE });
+    await expect(chatSurfaceAnchor(page)).toBeVisible({
+      timeout: TIMEOUT.VISIBLE,
+    });
 
     // Forward → back to the settings account page.
     await page.goForward();
diff --git a/services/platform/tests/e2e/specs/page-loads.spec.ts b/services/platform/tests/e2e/specs/page-loads.spec.ts
index 971f87cf2c..a9a92b1d26 100644
--- a/services/platform/tests/e2e/specs/page-loads.spec.ts
+++ b/services/platform/tests/e2e/specs/page-loads.spec.ts
@@ -12,9 +12,13 @@ import { t } from '../helpers/i18n';
  * route. Read-only — only navigates and asserts.
  */
 
-/** "New chat" renders in both the desktop bar and mobile header; pin the first. */
-function newChatButton(page: Page): Locator {
-  return page.getByRole('button', { name: t('chat.newChat') }).first();
+/**
+ * The chat surface is settled once its header search control renders (New chat
+ * is no longer a header button — it moved to the side-nav rail). It renders in
+ * both the desktop bar and mobile header; pin the first (visible).
+ */
+function chatSurfaceAnchor(page: Page): Locator {
+  return page.getByRole('button', { name: t('chat.searchChat') }).first();
 }
 
 interface RouteCase {
@@ -30,7 +34,7 @@ function routeCases(): readonly RouteCase[] {
       // Org index `beforeLoad` redirect to the chat surface (no heading there).
       key: 'org-landing',
       path: (id) => `/dashboard/${id}`,
-      anchor: (page) => newChatButton(page),
+      anchor: (page) => chatSurfaceAnchor(page),
     },
     {
       // Viewer fetches GitHub releases first; the <h1> renders in BOTH the
diff --git a/services/platform/tests/manual/TEMPLATE.md b/services/platform/tests/manual/TEMPLATE.md
index 513b0e7b2c..e37d277c06 100644
--- a/services/platform/tests/manual/TEMPLATE.md
+++ b/services/platform/tests/manual/TEMPLATE.md
@@ -12,7 +12,7 @@ human and an AI agent):
    NOT appear in the URL — it's `/log-in` and `/dashboard/{org}/documents`, not
    `/_auth/log-in`. `{org}` is the 16+ char id in the dashboard URL.
 2. Every control is named by its VISIBLE label plus the i18n key that resolves
-   it, e.g. the **New chat** button (`chat.newChat`). Labels live in
+   it, e.g. the **Send** button (`chat.send`). Labels live in
    `services/platform/messages/en.json`; the app pins `en` in test contexts.
    Locate by role + name (`getByRole('button', { name: … })`), never by CSS or
    guessed text. This is the same rule the e2e suite follows (helpers/i18n.ts).
diff --git a/services/platform/tests/manual/agents.md b/services/platform/tests/manual/agents.md
index c58237eda0..2f860ec54b 100644
--- a/services/platform/tests/manual/agents.md
+++ b/services/platform/tests/manual/agents.md
@@ -7,12 +7,12 @@
 
 ## Scope & routes
 
-| Surface           | Route                                                                                                                                                             |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| List              | `/dashboard/{org}/agents`                                                                                                                                         |
-| Editor (tabs)     | `/dashboard/{org}/agents/{slug}/{general\|instructions\|tools\|knowledge\|skills\|delegation\|response-tuning\|conversation-starters\|webhook\|metrics\|history}` |
-| Organigram        | `/dashboard/{org}/agents/organigram`                                                                                                                              |
-| Workforce metrics | `/dashboard/{org}/agents/metrics`                                                                                                                                 |
+| Surface           | Route                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| List              | `/dashboard/{org}/agents`                                                                                                                        |
+| Editor (tabs)     | `/dashboard/{org}/agents/{slug}/{general\|instructions\|tools\|knowledge\|skills\|delegation\|conversation-starters\|webhook\|metrics\|history}` |
+| Organigram        | `/dashboard/{org}/agents/organigram`                                                                                                             |
+| Workforce metrics | `/dashboard/{org}/agents/metrics`                                                                                                                |
 
 ## Prerequisites
 
@@ -35,25 +35,24 @@ delete them after.
 
 ## Functional tests
 
-| ID  | Test            | Steps (route + control)                                                                                                                                                       | Expected                                                                    |
-| --- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| F1  | List loads      | `/dashboard/{org}/agents`                                                                                                                                                     | Table (`settings.agents.title`); seeded `E2E Assistant` listed              |
-| F2  | Create agent    | **Create** (`settings.agents.createAgent`) → name (`settings.agents.form.name`) + display name (`form.displayName`) → **Continue** (`createDialog.continue`)                  | Editor opens for the new agent                                              |
-| F3  | Tab nav         | Open each editor tab (`settings.agents.navigation.{general,instructionsModel,tools,knowledge,skills,delegation,responseTuning,conversationStarters,webhook,metrics,history}`) | Each renders without error; URL reflects the tab                            |
-| F4  | General         | General tab → display name, description, team binding, task timeout → **Save**                                                                                                | Persists across reload                                                      |
-| F5  | Instructions    | Instructions tab → system prompt (`settings.agents.form.systemInstructions`) + model select → **Save**                                                                        | Saved toast (`settings.agents.agentSaved`); persists                        |
-| F6  | Tools           | Tools tab → toggle a custom tool + set web-search mode (`settings.agents.tools.modeTool`) → **Save**                                                                          | Persists                                                                    |
-| F7  | Knowledge       | Knowledge tab → RAG retrieval mode (`settings.agents.knowledge.modeTool`) → **Save**                                                                                          | Persists                                                                    |
-| F8  | Skills          | Skills tab → bind a skill → **Save**                                                                                                                                          | Persists; over the per-agent max is blocked                                 |
-| F9  | Delegation      | Delegation tab → add a delegate in the editor                                                                                                                                 | Delegate added to the graph                                                 |
-| F10 | Response tuning | Tuning tab → expand (`responseTuning.overridesSummary`), set effort (`responseTuning.effort` → `effortMedium`) → **Save**                                                     | Persists                                                                    |
-| F11 | Starters        | Starters tab → **Add** (`conversationStarters.add`) → type (`conversationStarters.placeholder`) → **Save**; reorder                                                           | Persists; per-locale starters supported                                     |
-| F12 | Webhook         | Webhook tab → configure URL                                                                                                                                                   | Saved; payload contract shown                                               |
-| F13 | Metrics         | Metrics tab ("Performance")                                                                                                                                                   | Daily scorecard (runs, tokens, cost, review pass/fail)                      |
-| F14 | Delete agent    | Row **⋯** (`common.actions.openMenu`) → **Delete** (`common.actions.delete`) → confirm (`settings.agents.deleteAgent`)                                                        | Agent removed from list                                                     |
-| F15 | Organigram      | `/dashboard/{org}/agents/organigram`                                                                                                                                          | Org chart canvas; Humans root; drag to set delegation; edits via side panel |
-| F16 | Workforce       | `/dashboard/{org}/agents/metrics`                                                                                                                                             | Workforce dashboard (`workforce.title`) with cross-agent metrics            |
-| F17 | History         | History tab (`settings.agents.navigation.history`)                                                                                                                            | Past runs/changes for the agent are listed                                  |
+| ID  | Test         | Steps (route + control)                                                                                                                                        | Expected                                                                    |
+| --- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| F1  | List loads   | `/dashboard/{org}/agents`                                                                                                                                      | Table (`settings.agents.title`); seeded `E2E Assistant` listed              |
+| F2  | Create agent | **Create** (`settings.agents.createAgent`) → name (`settings.agents.form.name`) + display name (`form.displayName`) → **Continue** (`createDialog.continue`)   | Editor opens for the new agent                                              |
+| F3  | Tab nav      | Open each editor tab (`settings.agents.navigation.{general,instructionsModel,tools,knowledge,skills,delegation,conversationStarters,webhook,metrics,history}`) | Each renders without error; URL reflects the tab                            |
+| F4  | General      | General tab → display name, description, team binding, task timeout → **Save**                                                                                 | Persists across reload                                                      |
+| F5  | Instructions | Instructions tab → system prompt (`settings.agents.form.systemInstructions`) + model select → **Save**                                                         | Saved toast (`settings.agents.agentSaved`); persists                        |
+| F6  | Tools        | Tools tab → toggle a custom tool + set web-search mode (`settings.agents.tools.modeTool`) → **Save**                                                           | Persists                                                                    |
+| F7  | Knowledge    | Knowledge tab → RAG retrieval mode (`settings.agents.knowledge.modeTool`) → **Save**                                                                           | Persists                                                                    |
+| F8  | Skills       | Skills tab → bind a skill → **Save**                                                                                                                           | Persists; over the per-agent max is blocked                                 |
+| F9  | Delegation   | Delegation tab → add a delegate in the editor                                                                                                                  | Delegate added to the graph                                                 |
+| F10 | Starters     | Starters tab → **Add** (`conversationStarters.add`) → type (`conversationStarters.placeholder`) → **Save**; reorder                                            | Persists; per-locale starters supported                                     |
+| F11 | Webhook      | Webhook tab → configure URL                                                                                                                                    | Saved; payload contract shown                                               |
+| F12 | Metrics      | Metrics tab ("Performance")                                                                                                                                    | Daily scorecard (runs, tokens, cost, review pass/fail)                      |
+| F13 | Delete agent | Row **⋯** (`common.actions.openMenu`) → **Delete** (`common.actions.delete`) → confirm (`settings.agents.deleteAgent`)                                         | Agent removed from list                                                     |
+| F14 | Organigram   | `/dashboard/{org}/agents/organigram`                                                                                                                           | Org chart canvas; Humans root; drag to set delegation; edits via side panel |
+| F15 | Workforce    | `/dashboard/{org}/agents/metrics`                                                                                                                              | Workforce dashboard (`workforce.title`) with cross-agent metrics            |
+| F16 | History      | History tab (`settings.agents.navigation.history`)                                                                                                             | Past runs/changes for the agent are listed                                  |
 
 ## Boundary & error tests
 
diff --git a/services/platform/tests/manual/chat.md b/services/platform/tests/manual/chat.md
index a6ce5b3d93..dc85cc6445 100644
--- a/services/platform/tests/manual/chat.md
+++ b/services/platform/tests/manual/chat.md
@@ -44,7 +44,7 @@ seeded knowledge), so they're best run in **mode B**.
 | --- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | F1  | Chat loads      | Open `/dashboard/{org}/chat`                                                                                                                            | Composer, agent picker (`chat.agentSelector.label`), model picker, conversation starters                                                                              |
 | F2  | Send a message  | Type a prompt, send                                                                                                                                     | Reply streams (canned in mode A); send disabled while composer empty                                                                                                  |
-| F3  | New chat        | **New chat** (`chat.newChat`)                                                                                                                           | Fresh thread; prior thread under history (`chat.showHistory` → `chat.chatsSection`)                                                                                   |
+| F3  | New chat        | Side-nav **New chat** rail link (`navigation.newChat`), or the `⌥⌘N` / `Alt+Ctrl+N` global shortcut                                                     | Fresh thread; prior thread under history (`chat.showHistory` → `chat.chatsSection`)                                                                                   |
 | F4  | Title auto-gen  | First message in a new thread                                                                                                                           | Concise AI title (not "New Chat", not raw metadata)                                                                                                                   |
 | F5  | Agent picker    | Open `chat.agentSelector.label`, pick another agent                                                                                                     | Selected agent drives the next turn                                                                                                                                   |
 | F6  | Model picker    | Open the model selector, pick a model                                                                                                                   | Next turn uses it; **Auto** routes to the agent default                                                                                                               |
diff --git a/services/sandbox/src/backend/docker/docker-session-backend.ts b/services/sandbox/src/backend/docker/docker-session-backend.ts
index e60f1fcd99..b42c7c6de0 100644
--- a/services/sandbox/src/backend/docker/docker-session-backend.ts
+++ b/services/sandbox/src/backend/docker/docker-session-backend.ts
@@ -377,6 +377,11 @@ export class DockerSessionBackend implements SessionBackend {
 
   async listSessions(organizationId?: string): Promise<BackendSession[]> {
     const filters = ['--filter', 'label=tale.sandbox-session=1'];
+    // Blue-green: only this colour's sessions, so a draining old colour and a
+    // fresh new colour never both adopt/manage the same session container.
+    if (this.cfg.color) {
+      filters.push('--filter', `label=tale.color=${this.cfg.color}`);
+    }
     if (organizationId) {
       filters.push('--filter', `label=tale.org=${organizationId}`);
     }
diff --git a/services/sandbox/src/cleanup.ts b/services/sandbox/src/cleanup.ts
index 8c96993376..a505aad6ff 100644
--- a/services/sandbox/src/cleanup.ts
+++ b/services/sandbox/src/cleanup.ts
@@ -200,8 +200,11 @@ export async function releaseSpawnerLock(cfg: SpawnerConfig): Promise<void> {
   }
 }
 
-async function listLabeledContainers(label: string): Promise<string[]> {
-  const result = await runDocker(['ps', '-aq', '-f', `label=${label}`]);
+async function listLabeledContainers(...labels: string[]): Promise<string[]> {
+  // Each `-f label=…` is AND-ed by docker, so passing the colour label
+  // restricts the sweep to this spawner colour's own containers.
+  const filters = labels.flatMap((l) => ['-f', `label=${l}`]);
+  const result = await runDocker(['ps', '-aq', ...filters]);
   if (result.exitCode !== 0) return [];
   return result.stdout
     .split('\n')
@@ -209,6 +212,11 @@ async function listLabeledContainers(label: string): Promise<string[]> {
     .filter((s) => s.length > 0);
 }
 
+/** The colour label filter for this spawner, or empty in single-colour mode. */
+function colorLabelFilter(cfg?: SpawnerConfig): string[] {
+  return cfg?.color ? [`tale.color=${cfg.color}`] : [];
+}
+
 async function sweepHostSessionDirs(
   cfg: SpawnerConfig,
   staleThreshold: number,
@@ -259,7 +267,14 @@ async function sweepHostSessionDirs(
 }
 
 export async function bootSweep(cfg?: SpawnerConfig): Promise<void> {
-  const containers = await listLabeledContainers('tale.sandbox=1');
+  // Scope to this spawner's colour so a green boot never reaps blue's
+  // in-flight one-shot containers (and vice-versa). Single-colour mode reaps
+  // all, as before.
+  const colorFilter = colorLabelFilter(cfg);
+  const containers = await listLabeledContainers(
+    'tale.sandbox=1',
+    ...colorFilter,
+  );
   for (const c of containers) {
     try {
       await dockerRm(c);
@@ -269,6 +284,7 @@ export async function bootSweep(cfg?: SpawnerConfig): Promise<void> {
   }
   const stagingContainers = await listLabeledContainers(
     'tale.sandbox-staging=1',
+    ...colorFilter,
   );
   for (const c of stagingContainers) {
     try {
@@ -320,11 +336,15 @@ export async function dockerSweepOrphans(
   // is unreachable.
   let containerProbeOk = false;
   try {
+    const colorFilter = cfg.color
+      ? ['--filter', `label=tale.color=${cfg.color}`]
+      : [];
     const result = await runDocker([
       'ps',
       '-a',
       '--filter',
       'label=tale.sandbox=1',
+      ...colorFilter,
       '--format',
       '{{.Names}}\t{{.Labels}}',
     ]);
diff --git a/services/sandbox/src/config.test.ts b/services/sandbox/src/config.test.ts
index ee7b964570..bd3256a6ee 100644
--- a/services/sandbox/src/config.test.ts
+++ b/services/sandbox/src/config.test.ts
@@ -13,6 +13,8 @@ const KEYS = [
   'SANDBOX_RUNTIME_CLASS',
   'SANDBOX_BACKEND',
   'SANDBOX_AGENT_MEMORY',
+  'SANDBOX_COLOR',
+  'SANDBOX_HOST_SESSION_ROOT',
   'TALE_PLATFORM_SHARED_CONFIG_DIR',
 ] as const;
 
@@ -198,3 +200,26 @@ describe('loadConfig — deployment.json sandboxRuntime', () => {
     expect(() => loadConfig()).toThrow(/not valid JSON/);
   });
 });
+
+describe('blue-green colour', () => {
+  test('unset SANDBOX_COLOR ⇒ single-colour (null), flat session root', () => {
+    process.env.SANDBOX_HOST_SESSION_ROOT = '/var/lib/tale-sandbox/sessions';
+    const cfg = loadConfig();
+    expect(cfg.color).toBeNull();
+    expect(cfg.hostSessionRoot).toBe('/var/lib/tale-sandbox/sessions');
+  });
+
+  test('SANDBOX_COLOR scopes the host session root per colour', () => {
+    process.env.SANDBOX_HOST_SESSION_ROOT = '/var/lib/tale-sandbox/sessions';
+    process.env.SANDBOX_COLOR = 'green';
+    const cfg = loadConfig();
+    expect(cfg.color).toBe('green');
+    expect(cfg.hostSessionRoot).toBe('/var/lib/tale-sandbox/sessions/green');
+  });
+
+  test('invalid SANDBOX_COLOR is ignored (single-colour)', () => {
+    process.env.SANDBOX_COLOR = 'Blue/../etc'; // path traversal / bad chars
+    const cfg = loadConfig();
+    expect(cfg.color).toBeNull();
+  });
+});
diff --git a/services/sandbox/src/config.ts b/services/sandbox/src/config.ts
index 9b345fb0fb..d35fd7b290 100644
--- a/services/sandbox/src/config.ts
+++ b/services/sandbox/src/config.ts
@@ -2,6 +2,7 @@
 // every knob is overridable so an operator can tune without rebuilding.
 
 import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 
 import {
   dindDefaultEnabled,
@@ -196,6 +197,21 @@ export function loadConfig(): SpawnerConfig {
     );
   }
 
+  // Blue-green colour (optional). Trimmed + validated to a short alnum token so
+  // it's a safe path/label segment; unset ⇒ single-colour mode.
+  const rawColor = (process.env.SANDBOX_COLOR ?? '').trim();
+  const sandboxColor =
+    rawColor.length > 0 && /^[a-z0-9][a-z0-9-]{0,31}$/.test(rawColor)
+      ? rawColor
+      : null;
+  if (rawColor.length > 0 && sandboxColor === null) {
+    console.warn(
+      `[sandbox.config] ignoring invalid SANDBOX_COLOR "${rawColor}" (expected [a-z0-9][a-z0-9-]*); running single-colour.`,
+    );
+  }
+  const sessionRootBase =
+    process.env.SANDBOX_HOST_SESSION_ROOT ?? '/var/lib/tale-sandbox/sessions';
+
   const rawBackend = process.env.SANDBOX_BACKEND ?? 'docker';
   if (rawBackend !== 'docker' && rawBackend !== 'kubernetes') {
     throw new Error(
@@ -291,8 +307,12 @@ export function loadConfig(): SpawnerConfig {
     defaultTimeoutMs: numEnv('SANDBOX_DEFAULT_TIMEOUT_MS', 30_000, { min: 1 }),
     maxTimeoutMs: numEnv('SANDBOX_MAX_TIMEOUT_MS', 300_000, { min: 1 }),
     maxConcurrent: numEnv('SANDBOX_MAX_CONCURRENT', 4, { min: 1 }),
-    hostSessionRoot:
-      process.env.SANDBOX_HOST_SESSION_ROOT ?? '/var/lib/tale-sandbox/sessions',
+    color: sandboxColor,
+    // Per-colour session root so blue/green don't share the `.spawner.lock` or
+    // the host-dir sweep (single-colour mode keeps the flat base path).
+    hostSessionRoot: sandboxColor
+      ? join(sessionRootBase, sandboxColor)
+      : sessionRootBase,
     cacheVolumePrefix: {
       pip:
         process.env.SANDBOX_PIP_CACHE_VOLUME_PREFIX ?? 'tale-sandbox-pip-cache',
@@ -346,6 +366,13 @@ export function loadConfig(): SpawnerConfig {
       maxIdleMs: numEnv('SANDBOX_SESSION_MAX_IDLE_MS', 30 * 60 * 1000, {
         min: 60_000,
       }),
+      // How long a drained (lingering) colour keeps serving its sessions after
+      // a flip before reclaiming their compute itself. 30 min covers a typical
+      // long agent turn; the deploy CLI normally tears the colour down sooner
+      // once its sessions end. Min 1 min so it can't thrash.
+      maxLingerMs: numEnv('SANDBOX_SESSION_MAX_LINGER_MS', 30 * 60 * 1000, {
+        min: 60_000,
+      }),
       execDefaultTimeoutMs: numEnv(
         'SANDBOX_SESSION_EXEC_DEFAULT_TIMEOUT_MS',
         10 * 60 * 1000,
diff --git a/services/sandbox/src/docker-args.test.ts b/services/sandbox/src/docker-args.test.ts
index 30b8dbc56a..359505a6bb 100644
Binary files a/services/sandbox/src/docker-args.test.ts and b/services/sandbox/src/docker-args.test.ts differ
diff --git a/services/sandbox/src/docker-args.ts b/services/sandbox/src/docker-args.ts
index d99a322e7b..41e19cc447 100644
--- a/services/sandbox/src/docker-args.ts
+++ b/services/sandbox/src/docker-args.ts
@@ -125,6 +125,10 @@ export function buildDockerRunArgs(
   }
 
   const containerName = `tale-sbx-${inp.executionId}`;
+  // Blue-green: stamp the spawner's own colour so each colour's boot/orphan
+  // sweep reaps only its OWN containers (cleanup.ts filters on this label).
+  // Omitted in single-colour mode so today's behaviour is unchanged.
+  const colorLabel = cfg.color ? ['--label', `tale.color=${cfg.color}`] : [];
   // No `--rm` because spawn.ts removes the container explicitly after
   // harvesting outputs from the host bind-mounted workspace dir.
   return [
@@ -134,6 +138,7 @@ export function buildDockerRunArgs(
     containerName,
     '--label',
     'tale.sandbox=1',
+    ...colorLabel,
     `--label`,
     `tale.session=${inp.executionId}`,
     `--label`,
diff --git a/services/sandbox/src/server.ts b/services/sandbox/src/server.ts
index 4a3f999c1e..ed865eda6b 100644
--- a/services/sandbox/src/server.ts
+++ b/services/sandbox/src/server.ts
@@ -31,6 +31,7 @@ import { SessionRoutes } from './session/session-routes.ts';
 import {
   cancelExecution,
   executeRequest,
+  inFlightIds,
   inFlightSize,
   isInFlight,
   registerInFlight,
@@ -43,6 +44,24 @@ const cfg = loadConfig();
 // Execution backend (docker | kubernetes), chosen once at boot. Constructing
 // it has no side effects; init() runs the docker lock + boot sweep in main().
 const backend = createBackend(cfg);
+
+// Blue-green drain state. `POST /v1/drain` flips this so the spawner stops
+// accepting NEW work (one-shot executions + new sessions) while still serving
+// cancels, existing-session execs, and `/v1/drain-status` — letting the CLI
+// flip traffic to the new colour, poll until in-flight reaches zero, then stop
+// this colour. Unlike SIGTERM it does NOT exit or cancel in-flight work.
+let draining = false;
+// When this colour entered drain mode (the max-linger self-reap anchor). The
+// CLI flip lingers a colour that still has live sessions instead of tearing it
+// down; if the deploy dies mid-flip, this lets the spawner reclaim the session
+// compute itself once `cfg.session.maxLingerMs` elapses, so a colour can never
+// hold a session forever. `null` when not draining.
+let drainStartedAt: number | null = null;
+// One-shot guard so the linger reap fires once (it stops sessions; the thin
+// spawner then sits idle until the next flip's teardown removes its container —
+// we deliberately do NOT process.exit, which `restart: unless-stopped` would
+// just bounce back into a zombie old-colour spawner).
+let lingerReaped = false;
 // Session subsystem (persistent sessions). Lazily constructed on first session
 // route hit so a kubernetes deployment (session backend not yet implemented)
 // only errors when sessions are actually used, never at boot.
@@ -124,7 +143,53 @@ async function handleHealth(): Promise<Response> {
   );
 }
 
+/**
+ * Control-plane drain endpoints (no HMAC — like `/health`). The spawner is not
+ * host-exposed in production (internal network only); the CLI reaches these via
+ * `docker exec <spawner> curl -s localhost:8003/v1/drain[-status]` during a
+ * blue-green flip, and `docker exec` already implies host-root.
+ */
+function handleDrain(): Response {
+  if (!draining) {
+    draining = true;
+    drainStartedAt = Date.now();
+  }
+  console.log(
+    '[sandbox] entered drain mode — refusing new executions/sessions',
+  );
+  return jsonResponse({ draining: true, inFlight: inFlightSize() }, 200);
+}
+
+function handleDrainStatus(): Response {
+  // Read the session count without force-constructing the session subsystem
+  // (a status probe must never trigger backend init).
+  return jsonResponse(
+    {
+      draining,
+      color: cfg.color,
+      inFlight: inFlightSize(),
+      inFlightIds: inFlightIds(),
+      sessions: sessionRoutes?.sessionCount() ?? 0,
+      // Live session ids — the flip lingers this colour while any remain.
+      sessionIds: sessionRoutes?.sessionIds() ?? [],
+    },
+    200,
+  );
+}
+
 async function handleExecute(req: Request): Promise<Response> {
+  // Draining: this colour is being rolled out — reject new one-shot work so
+  // Convex's next /v1/execute lands on the new colour. In-flight executions
+  // continue; the CLI waits for them via /v1/drain-status.
+  if (draining) {
+    return jsonResponse(
+      {
+        error: 'draining',
+        message: 'spawner is draining; retry on the active colour',
+      },
+      503,
+    );
+  }
   let body: string;
   try {
     body = await readBodyCapped(req, cfg.maxRequestBodyBytes);
@@ -216,27 +281,30 @@ async function handleExecute(req: Request): Promise<Response> {
 
   // Keepalive + stream-close handling live in sseResponse (extracted to
   // sse.ts so the session exec route shares them).
-  return sseResponse(async ({ send }) => {
-    try {
-      const result = await executeRequest(backend, cfg, parsed, {
-        onPhase: (e) => send('phase', e),
-        // Live stdout/stderr tail. Per-line for stdout (PHASE markers
-        // stripped); per-chunk for stderr. Coalescing is left to the
-        // platform-side action because that's where the cost of "too
-        // many mutations" actually lives — SSE event overhead is small.
-        onStdoutDelta: (text) => send('stdout', { text }),
-        onStderrDelta: (text) => send('stderr', { text }),
-      });
-      send('result', result);
-    } catch (err) {
-      send('error', {
-        message: err instanceof Error ? err.message : String(err),
-      });
-    } finally {
-      unregisterInFlight(parsed.executionId);
-      req.signal.removeEventListener('abort', abortHandler);
-    }
-  });
+  return sseResponse(
+    async ({ send }) => {
+      try {
+        const result = await executeRequest(backend, cfg, parsed, {
+          onPhase: (e) => send('phase', e),
+          // Live stdout/stderr tail. Per-line for stdout (PHASE markers
+          // stripped); per-chunk for stderr. Coalescing is left to the
+          // platform-side action because that's where the cost of "too
+          // many mutations" actually lives — SSE event overhead is small.
+          onStdoutDelta: (text) => send('stdout', { text }),
+          onStderrDelta: (text) => send('stderr', { text }),
+        });
+        send('result', result);
+      } catch (err) {
+        send('error', {
+          message: err instanceof Error ? err.message : String(err),
+        });
+      } finally {
+        unregisterInFlight(parsed.executionId);
+        req.signal.removeEventListener('abort', abortHandler);
+      }
+    },
+    cfg.color ? { 'x-sandbox-color': cfg.color } : undefined,
+  );
 }
 
 async function handleCancel(req: Request, id: string): Promise<Response> {
@@ -351,6 +419,17 @@ async function handleSessionRoutes(
 
   // POST /v1/sessions (create)
   if (req.method === 'POST' && path === '/v1/sessions') {
+    // Draining: refuse NEW sessions so they land on the active colour. Execs
+    // on existing sessions (below) keep working until the session is reaped.
+    if (draining) {
+      return jsonResponse(
+        {
+          error: 'draining',
+          message: 'spawner is draining; create on the active colour',
+        },
+        503,
+      );
+    }
     const r = await readAndAuth(req);
     if ('error' in r) return r.error;
     return getSessionRoutes().handleCreate(r.body);
@@ -534,6 +613,12 @@ async function router(req: Request): Promise<Response> {
   if (req.method === 'GET' && url.pathname === '/health') {
     return handleHealth();
   }
+  if (req.method === 'POST' && url.pathname === '/v1/drain') {
+    return handleDrain();
+  }
+  if (req.method === 'GET' && url.pathname === '/v1/drain-status') {
+    return handleDrainStatus();
+  }
   if (req.method === 'POST' && url.pathname === '/v1/execute') {
     return handleExecute(req);
   }
@@ -595,6 +680,32 @@ async function main(): Promise<void> {
       void sessions.sweepExpired().catch((err) => {
         console.warn('[sandbox.session] periodic sweep failed:', err);
       });
+      // Max-linger self-reap (CLI-independent safety net): if this colour has
+      // been draining longer than the linger TTL, reclaim its session compute
+      // ourselves so a deploy that died mid-flip can't pin compute forever.
+      // Stop-only (workspace preserved); the spawner stays up — `restart:
+      // unless-stopped` would otherwise bounce a self-exit into a zombie
+      // old-colour spawner. The next flip's teardown removes this container.
+      if (
+        draining &&
+        !lingerReaped &&
+        drainStartedAt !== null &&
+        Date.now() - drainStartedAt > cfg.session.maxLingerMs
+      ) {
+        lingerReaped = true;
+        void sessions
+          .stopAllSessions()
+          .then((n) => {
+            if (n > 0) {
+              console.warn(
+                `[sandbox.session] max-linger (${cfg.session.maxLingerMs}ms) reached while draining — reclaimed ${n} session(s); workspaces preserved for resume on the active colour.`,
+              );
+            }
+          })
+          .catch((err) => {
+            console.warn('[sandbox.session] linger reap failed:', err);
+          });
+      }
     }, SESSION_SWEEP_INTERVAL_MS);
     stopSessionSweep = () => clearInterval(sweepTimer);
   } catch (err) {
diff --git a/services/sandbox/src/session/docker-session-args.ts b/services/sandbox/src/session/docker-session-args.ts
index 2a75318a49..49c0a64f36 100644
--- a/services/sandbox/src/session/docker-session-args.ts
+++ b/services/sandbox/src/session/docker-session-args.ts
@@ -308,6 +308,9 @@ export function buildDockerSessionRunArgs(
     // metadata read on boot.
     '--label',
     'tale.sandbox-session=1',
+    // Blue-green colour so `listSessions` (adoption) only sees this colour's
+    // sessions — a fresh green never adopts a draining blue's sessions.
+    ...(cfg.color ? ['--label', `tale.color=${cfg.color}`] : []),
     '--label',
     `tale.session=${inp.sessionId}`,
     '--label',
diff --git a/services/sandbox/src/session/session-routes.ts b/services/sandbox/src/session/session-routes.ts
index bb4288fc52..5c58632288 100644
--- a/services/sandbox/src/session/session-routes.ts
+++ b/services/sandbox/src/session/session-routes.ts
@@ -47,6 +47,39 @@ export class SessionRoutes {
     private readonly backend: SessionBackend,
   ) {}
 
+  /** Number of live sessions this spawner currently manages (drain readiness). */
+  sessionCount(): number {
+    return this.registry.size();
+  }
+
+  /** Live session ids — the deploy flip reads these from `/v1/drain-status` to
+   * decide whether to LINGER this colour (keep it serving its sessions) rather
+   * than tear it down. */
+  sessionIds(): string[] {
+    return this.registry.list().map((s) => s.sessionId);
+  }
+
+  /** Force-stop every non-finished session (compute reclaimed, workspace
+   * preserved). Used by the spawner's max-linger self-reap so a colour that
+   * lingered past its TTL can shut down without orphaning containers — even if
+   * the deploy CLI died mid-flip. Returns the number stopped. */
+  async stopAllSessions(): Promise<number> {
+    let stopped = 0;
+    for (const s of this.registry.list()) {
+      try {
+        await this.backend.stopSession(s.sessionId);
+        this.registry.delete(s.sessionId);
+        stopped += 1;
+      } catch (err) {
+        console.warn(
+          `[sandbox.session] linger stop failed for ${s.sessionId}:`,
+          err,
+        );
+      }
+    }
+    return stopped;
+  }
+
   /** runnerd token for a session: derived from SANDBOX_TOKEN when signed, or
    * '' in unsigned dev mode (runnerd skips the check, matching the spawner's
    * own opt-in HMAC policy). */
@@ -368,7 +401,14 @@ export class SessionRoutes {
         endpoint,
         liveExecs: new Map(),
       });
-      return jsonResponse({ session: this.toInfo(req.sessionId) }, 201);
+      // Report the blue-green colour the session landed on so the platform can
+      // route later session ops to `sandbox-<color>` even after a flip lingers
+      // this colour (mirrors the execution path's X-Sandbox-Color).
+      return jsonResponse(
+        { session: this.toInfo(req.sessionId) },
+        201,
+        this.cfg.color ? { 'x-sandbox-color': this.cfg.color } : undefined,
+      );
     } finally {
       this.creating.delete(req.sessionId);
     }
diff --git a/services/sandbox/src/session/session-test-config.ts b/services/sandbox/src/session/session-test-config.ts
index 50bf2a07ed..8ff874c760 100644
--- a/services/sandbox/src/session/session-test-config.ts
+++ b/services/sandbox/src/session/session-test-config.ts
@@ -10,6 +10,7 @@ export const TEST_SESSION_CONFIG: SessionConfig = {
   maxSessionsPerOrg: 2,
   maxLifetimeMs: 86_400_000,
   maxIdleMs: 1_800_000,
+  maxLingerMs: 1_800_000,
   execDefaultTimeoutMs: 600_000,
   execMaxTimeoutMs: 7_200_000,
   createHealthTimeoutMs: 180_000,
diff --git a/services/sandbox/src/sse.ts b/services/sandbox/src/sse.ts
index 66dfe3e09d..a744486d1d 100644
--- a/services/sandbox/src/sse.ts
+++ b/services/sandbox/src/sse.ts
@@ -15,6 +15,7 @@ const SSE_KEEPALIVE_INTERVAL_MS = 20_000;
 
 export function sseResponse(
   run: (handle: SseHandle) => Promise<void>,
+  extraHeaders?: Record<string, string>,
 ): Response {
   const stream = new ReadableStream<Uint8Array>({
     async start(controller) {
@@ -52,7 +53,11 @@ export function sseResponse(
   });
   return new Response(stream, {
     status: 200,
+    // Core SSE headers spread LAST so a caller's `extraHeaders` (e.g. the
+    // blue-green `X-Sandbox-Color`) can add fields but never clobber the
+    // content-type / cache-control / buffering headers streaming depends on.
     headers: {
+      ...extraHeaders,
       'content-type': 'text/event-stream',
       'cache-control': 'no-cache, no-transform',
       'x-accel-buffering': 'no',
diff --git a/services/sandbox/src/types.ts b/services/sandbox/src/types.ts
index 1c53e7961e..3fa529eba5 100644
--- a/services/sandbox/src/types.ts
+++ b/services/sandbox/src/types.ts
@@ -338,6 +338,18 @@ export interface SpawnerConfig {
   defaultTimeoutMs: number;
   maxTimeoutMs: number;
   maxConcurrent: number;
+  /**
+   * Blue-green colour of this spawner instance (`SANDBOX_COLOR`), or `null` in
+   * single-colour mode (dev / unset). When set it (a) scopes `hostSessionRoot`
+   * to a per-colour sub-directory so two colours don't share the `.spawner.lock`
+   * or the host-dir sweep, and (b) stamps a `tale.color=<color>` label on
+   * spawned containers so each colour's boot/orphan sweep only reaps its OWN
+   * containers — a green boot must never `docker rm` blue's in-flight work.
+   * Set from the spawner's own env (never request input), so it is not
+   * attacker-controllable. Optional only for test fixtures; `loadConfig`
+   * always sets it (to a colour string or `null`).
+   */
+  color?: string | null;
   hostSessionRoot: string;
   cacheVolumePrefix: { pip: string; npm: string; bun: string };
   egressNetwork: string;
@@ -366,6 +378,11 @@ export interface SessionConfig {
   maxLifetimeMs: number;
   /** Idle ceiling — sessions with no runnerd activity past this are reaped. */
   maxIdleMs: number;
+  /** Max time this colour will LINGER (keep serving its sessions) after a deploy
+   * flip put it into drain mode before the spawner reclaims that compute itself
+   * (CLI-independent safety net). Workspaces are preserved for resume on the
+   * active colour. See server.ts's linger self-reap. */
+  maxLingerMs: number;
   /** Default + ceiling for per-exec timeoutMs inside a session. */
   execDefaultTimeoutMs: number;
   execMaxTimeoutMs: number;
diff --git a/services/web/app/components/blocks/form-card.tsx b/services/web/app/components/blocks/form-card.tsx
index 36a72e3f6c..8d5205de9a 100644
--- a/services/web/app/components/blocks/form-card.tsx
+++ b/services/web/app/components/blocks/form-card.tsx
@@ -213,7 +213,6 @@ export function FormCard<T extends BasePayload>({
                     type="submit"
                     isLoading={form.formState.isSubmitting}
                     fullWidth
-                    size="lg"
                   >
                     {submitLabel}
                   </Button>
diff --git a/services/web/app/components/layout/site-header.tsx b/services/web/app/components/layout/site-header.tsx
index 51e7bc9864..7b590f744c 100644
--- a/services/web/app/components/layout/site-header.tsx
+++ b/services/web/app/components/layout/site-header.tsx
@@ -35,14 +35,13 @@ export function SiteHeader() {
       <Button
         asChild
         variant="secondary"
-        size="sm"
         className="text-fg-muted hover:text-fg-base text-sm"
       >
         <a href={DOCS_URL} target="_blank" rel="noopener noreferrer">
           {t('readDocs')}
         </a>
       </Button>
-      <Button asChild size="sm" className="text-sm">
+      <Button asChild className="text-sm">
         <LocalizedLink to="/request-demo">{t('requestDemo')}</LocalizedLink>
       </Button>
     </>
diff --git a/services/web/index.html b/services/web/index.html
index b13f9393e5..2df244a2c1 100644
--- a/services/web/index.html
+++ b/services/web/index.html
@@ -72,7 +72,7 @@
       title="llms-full.txt"
     />
   </head>
-  <body>
+  <body class="font-sans antialiased">
     <div id="root"></div>
     <script type="module" src="/app/main.tsx"></script>
   </body>
diff --git a/tools/cli/README.md b/tools/cli/README.md
index 29519ee4c1..474355c481 100644
--- a/tools/cli/README.md
+++ b/tools/cli/README.md
@@ -43,18 +43,21 @@ bun run build:linux
 # Deploy the current CLI version (blue-green, zero-downtime)
 tale deploy
 
-# Also update stateful services
-tale deploy --all
+# Also update the stop-gated tier (db, proxy) — brief downtime
+tale deploy --stop
 
 # Deploy specific services only (in-place update)
-tale deploy --services platform,rag
+tale deploy --services platform
 
 # Dry run to preview changes
 tale deploy --dry-run
 ```
 
-The deployed version always matches the running CLI's version. To move
-to a newer version, run `tale upgrade` first, then `tale deploy`.
+The deployed version always matches the running CLI's version. The CLI keeps
+itself aligned to the instance automatically — every command checks the
+workspace's recorded version and self-updates the binary to match. To move to a
+new version, run `tale update` (updates the CLI + syncs project files), then
+`tale deploy` to roll the containers.
 
 ### Management Commands
 
@@ -92,17 +95,36 @@ tale reset --force --all
 ### `tale deploy`
 
 Deploy the current CLI version with the blue-green strategy. The deployed
-platform version always matches the running CLI; to upgrade, run
-`tale upgrade` first.
+platform version always matches the running CLI. To move to a different version,
+use `tale update` first (updates the CLI + syncs project files), then `tale
+deploy` to roll the containers.
 
 | Option                  | Description                                                   |
 | ----------------------- | ------------------------------------------------------------- |
-| `-a, --all`             | Also update infrastructure (db, proxy)                        |
+| `--stop`                | Also update the stop-gated tier (db, proxy) — brief downtime  |
 | `-s, --services <list>` | Specific services to update (comma-separated)                 |
 | `--dry-run`             | Preview deployment without making changes                     |
 | `--skip-backup`         | Skip the automatic pre-deploy volume snapshot (logged loudly) |
 | `--host <hostname>`     | Host alias for proxy (default: `tale.local` or `$HOST`)       |
 
+### `tale update`
+
+Move the CLI and your on-disk project files to a new version. Updates the CLI
+binary first, then syncs the project files to that version's templates. It does
+**not** roll the containers — run `tale deploy` afterwards for that. If the file
+sync fails, the CLI is rolled back to the workspace's previous version so the
+binary and `tale.json` never drift apart. With no `--version`, targets the
+latest release.
+
+The CLI also self-aligns to the instance version on every command, so you rarely
+run `tale update` except to deliberately move versions.
+
+| Option                | Description                                                       |
+| --------------------- | ----------------------------------------------------------------- |
+| `-v, --version <ver>` | Update to this exact version instead of latest (allows downgrade) |
+| `-f, --force`         | Force re-sync of locally modified project files                   |
+| `--dry-run`           | Preview the version change and file sync without modifying        |
+
 ### `tale status`
 
 Show current deployment status including active color, running containers, and health.
@@ -131,7 +153,7 @@ the archive is crash-consistent.
 List snapshots, or restore one into the data volumes. Restoring verifies
 the sha256 sidecars first, refuses while any project container is running,
 and asks for confirmation. After a restore, redeploy the version recorded
-in the snapshot (`tale upgrade --version <version> && tale deploy --all`).
+in the snapshot (`tale update --version <version>` then `tale deploy --stop`).
 
 | Option      | Description                                      |
 | ----------- | ------------------------------------------------ |
diff --git a/tools/cli/src/commands/deploy/index.ts b/tools/cli/src/commands/deploy/index.ts
index 118a8281a3..ca13022544 100644
--- a/tools/cli/src/commands/deploy/index.ts
+++ b/tools/cli/src/commands/deploy/index.ts
@@ -1,29 +1,15 @@
 import { Command } from 'commander';
 
-import pkg from '../../../package.json';
-import { deploy } from '../../lib/actions/deploy';
-import { runDeployPreflight } from '../../lib/actions/deploy-preflight';
-import {
-  type ServiceName,
-  ALL_SERVICES,
-  STATEFUL_SERVICES,
-  isValidService,
-} from '../../lib/compose/types';
-import { ensureEnv, ensureProductionDomain } from '../../lib/config/ensure-env';
-import { ensureDocker } from '../../lib/docker/ensure-docker';
-import { requireProject } from '../../lib/project/find-project';
-import { resolveOrAssignProjectContext } from '../../lib/project/project-context';
-import { preconditionError, usageError } from '../../utils/fail';
-import { loadEnv } from '../../utils/load-env';
-import * as logger from '../../utils/logger';
+import { runDeploy } from '../../lib/actions/run-deploy';
+import { ALL_SERVICES, STOP_GATED_SERVICES } from '../../lib/compose/types';
 import { action } from '../../utils/run-command';
 
 export function createDeployCommand(): Command {
   return new Command('deploy')
     .description('Deploy the current CLI version to the environment')
     .option(
-      '-a, --all',
-      `Also update infrastructure (${STATEFUL_SERVICES.join(', ')})`,
+      '--stop',
+      `Also update the stop-gated tier (${STOP_GATED_SERVICES.join(', ')}) — recreates them, so accepts a brief downtime. Without it, running ${STOP_GATED_SERVICES.join('/')} are left untouched.`,
       false,
     )
     .option(
@@ -41,7 +27,7 @@ export function createDeployCommand(): Command {
       '--override-all',
       'After deploy, factory-reseed the builtin catalog into ALL orgs server-side ' +
         '(preserves *.secrets.json, .history/, and uploaded branding/images/). ' +
-        'Implies --all (recreates stateful services so the new entrypoint runs).',
+        'Implies --stop (recreates stateful services so the new entrypoint runs).',
       false,
     )
     .option(
@@ -57,102 +43,15 @@ export function createDeployCommand(): Command {
     )
     .action(
       action(async (options) => {
-        // `--override` and `--override-all` are semantically incompatible:
-        // host push runs first, then the catalog factory reseed clobbers
-        // everything --override would have written (host push effectively
-        // becomes a no-op for non-secrets / non-history / non-branding-
-        // images). Reject the combination at parse time so operators
-        // don't reason about a silently-discarded flag.
-        if (options.override && options.overrideAll) {
-          throw usageError(
-            '--override and --override-all cannot be combined: ' +
-              '--override-all factory-reseeds from the builtin catalog and ' +
-              'would clobber whatever --override just pushed. ' +
-              'Pick one: --override (push host workspace to container) ' +
-              'OR --override-all (factory-reseed all orgs server-side).',
-          );
-        }
-        const projectDir = requireProject();
-        await resolveOrAssignProjectContext(projectDir);
-
-        // Zero-prerequisite: make sure Docker is usable before anything else.
-        const docker = await ensureDocker({ assumeYes: options.yes });
-        if (docker.status === 'refused' || docker.status === 'failed') {
-          throw preconditionError(docker.detail);
-        }
-
-        const { success: envSetupSuccess, regeneratedAutoSecrets } =
-          await ensureEnv({
-            deployDir: projectDir,
-          });
-        if (!envSetupSuccess) {
-          throw preconditionError(
-            `Environment setup failed. Cannot deploy without ${projectDir}/.env.`,
-          );
-        }
-        // If ensureEnv had to mint missing auto-gen secrets headlessly
-        // (typical: a new `SANDBOX_TOKEN` for an existing deployment),
-        // force-recreate the running services so their in-memory env
-        // refreshes to the new value rather than keeping the stale null.
-        // Also force-recreate on --override-all so the reseed action
-        // runs against the new binary, not a stale container that the
-        // image/config-unchanged path would have left running.
-        const forceRecreate =
-          (regeneratedAutoSecrets !== undefined &&
-            regeneratedAutoSecrets.length > 0) ||
-          (options.overrideAll ?? false);
-
-        // `tale init` leaves a local default (localhost + self-signed). Choose
-        // the production domain + TLS here: prompts interactively, honors
-        // --host, and is a no-op in CI when HOST is already a public domain.
-        await ensureProductionDomain(projectDir, { host: options.host });
-
-        const env = loadEnv(projectDir);
-
-        // Catch fixable problems (daemon down, letsencrypt misconfig) before
-        // mutating any container. Throws on a real deploy; warns on --dry-run.
-        // Pass the env source explicitly (TLS_MODE/HOST/TLS_EMAIL live in
-        // process.env, populated by loadEnv above) so preflight doesn't depend
-        // on an implicit default.
-        await runDeployPreflight({ dryRun: options.dryRun, env: process.env });
-
-        const version = pkg.version.includes('-dev') ? 'latest' : pkg.version;
-        if (version === 'latest') {
-          logger.info(
-            'Dev build detected — deploying `latest` images. Run `tale upgrade` for a release build.',
-          );
-        }
-
-        let services: ServiceName[] | undefined;
-        if (options.services) {
-          const serviceList = options.services
-            .split(',')
-            .map((s: string) => s.trim());
-          const invalid = serviceList.filter((s: string) => !isValidService(s));
-          if (invalid.length > 0) {
-            throw usageError(`Invalid service(s): ${invalid.join(', ')}`, [
-              `Valid services: ${ALL_SERVICES.join(', ')}`,
-            ]);
-          }
-          // All validated above; the type guard narrows to ServiceName[].
-          services = serviceList.filter(isValidService);
-        }
-
-        const hostAlias = options.host ?? process.env.HOST ?? 'tale.local';
-        await deploy({
-          version,
-          // --override-all implies --all so the convex container restarts
-          // with the new entrypoint + new code before the reseed action runs.
-          updateStateful: options.all || options.overrideAll,
-          env,
-          hostAlias,
+        await runDeploy({
+          stop: options.stop,
+          services: options.services,
           dryRun: options.dryRun,
-          services,
+          host: options.host,
           override: options.override,
           overrideAll: options.overrideAll,
           quiet: options.quiet,
-          assumeYes: options.yes,
-          forceRecreate,
+          yes: options.yes,
           skipBackup: options.skipBackup,
         });
       }),
diff --git a/tools/cli/src/commands/rollback.ts b/tools/cli/src/commands/rollback.ts
index f5a390dd3c..9680a8ac72 100644
--- a/tools/cli/src/commands/rollback.ts
+++ b/tools/cli/src/commands/rollback.ts
@@ -14,8 +14,9 @@ export function createRollbackCommand(): Command {
       'Roll back to the previous version (patch-level rollbacks only — ' +
         'minor/major recovery goes through backup restore)',
     )
+    .option('-y, --yes', 'Non-interactive: skip the confirmation prompt', false)
     .action(
-      action(async () => {
+      action(async (options: { yes: boolean }) => {
         const projectDir = requireProject();
         await resolveProjectContext(projectDir);
         const { success: envSetupSuccess } = await ensureEnv({
@@ -27,7 +28,7 @@ export function createRollbackCommand(): Command {
           );
         }
         const env = loadEnv(projectDir);
-        await rollback({ env });
+        await rollback({ env, assumeYes: options.yes });
       }),
     );
 }
diff --git a/tools/cli/src/commands/uninstall.ts b/tools/cli/src/commands/uninstall.ts
new file mode 100644
index 0000000000..2dfbbf316e
--- /dev/null
+++ b/tools/cli/src/commands/uninstall.ts
@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+
+import { uninstall } from '../lib/actions/uninstall';
+import { action } from '../utils/run-command';
+
+export function createUninstallCommand(): Command {
+  return new Command('uninstall')
+    .description(
+      'Remove the Tale CLI binary from this system (optionally purge the per-user config and a project)',
+    )
+    .option('-f, --force', 'skip the binary-removal confirmation', false)
+    .option(
+      '--purge',
+      "also remove the per-user config (~/.tale-daemon) and tear down the current project's Docker resources + files",
+      false,
+    )
+    .option(
+      '--dry-run',
+      'show what would be removed without removing anything',
+      false,
+    )
+    .action(
+      action(async (opts) => {
+        await uninstall({
+          force: opts.force,
+          purge: opts.purge,
+          dryRun: opts.dryRun,
+        });
+      }),
+    );
+}
diff --git a/tools/cli/src/commands/update/index.ts b/tools/cli/src/commands/update/index.ts
new file mode 100644
index 0000000000..20076a530b
--- /dev/null
+++ b/tools/cli/src/commands/update/index.ts
@@ -0,0 +1,37 @@
+import { Command, Option } from 'commander';
+
+import { runUpdate } from '../../lib/actions/run-update';
+import { action } from '../../utils/run-command';
+
+export function createUpdateCommand(): Command {
+  return (
+    new Command('update')
+      .description(
+        'Update this Tale instance: move the CLI to a new version and sync project files (run `tale deploy` afterwards to roll the containers)',
+      )
+      .option(
+        '-v, --version <version>',
+        'update to this exact version (e.g. 0.9.0) instead of the latest release; allows downgrades',
+      )
+      .option(
+        '-f, --force',
+        'force re-sync and overwrite locally modified project files',
+      )
+      .option('--dry-run', 'show what would change without modifying anything')
+      // Hidden continuation: run only the file-sync phase under the binary that
+      // the parent invocation just installed. Internal use — do not call directly.
+      .addOption(
+        new Option('--internal-instance', 'file-sync phase only').hideHelp(),
+      )
+      .action(
+        action(async (opts) => {
+          await runUpdate({
+            version: opts.version,
+            force: opts.force,
+            dryRun: opts.dryRun,
+            internalInstance: opts.internalInstance,
+          });
+        }),
+      )
+  );
+}
diff --git a/tools/cli/src/commands/upgrade/index.ts b/tools/cli/src/commands/upgrade/index.ts
deleted file mode 100644
index 22aa3c3df0..0000000000
--- a/tools/cli/src/commands/upgrade/index.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { Command, Option } from 'commander';
-
-import { upgrade } from '../../lib/actions/upgrade';
-import { action } from '../../utils/run-command';
-
-export function createUpgradeCommand(): Command {
-  return new Command('upgrade')
-    .alias('update')
-    .description(
-      'Upgrade or migrate the CLI to a specific version, then sync project files',
-    )
-    .option(
-      '-v, --version <version>',
-      'install this exact version (e.g. 0.9.0) instead of the latest release; allows downgrades',
-    )
-    .option(
-      '-f, --force',
-      'force re-download and overwrite locally modified files',
-    )
-    .option('--dry-run', 'show what would change without modifying anything')
-    .addOption(
-      new Option('--internal-sync-only', 'sync project files only').hideHelp(),
-    )
-    .action(
-      action(
-        async (opts: {
-          version?: string;
-          force?: boolean;
-          dryRun?: boolean;
-          internalSyncOnly?: boolean;
-        }) => {
-          await upgrade({
-            version: opts.version,
-            force: opts.force,
-            dryRun: opts.dryRun,
-            internalSyncOnly: opts.internalSyncOnly,
-          });
-        },
-      ),
-    );
-}
diff --git a/tools/cli/src/index.ts b/tools/cli/src/index.ts
index 08ec8fcf28..2aea045806 100644
--- a/tools/cli/src/index.ts
+++ b/tools/cli/src/index.ts
@@ -17,7 +17,9 @@ import { createRestoreCommand } from './commands/restore';
 import { createRollbackCommand } from './commands/rollback';
 import { createStartCommand } from './commands/start';
 import { createStatusCommand } from './commands/status';
-import { createUpgradeCommand } from './commands/upgrade';
+import { createUninstallCommand } from './commands/uninstall';
+import { createUpdateCommand } from './commands/update';
+import { ensureAligned } from './lib/version/align';
 import * as logger from './utils/logger';
 import {
   configureOutput,
@@ -36,8 +38,8 @@ program
   .name('tale')
   .description('Tale CLI - deployment and management tools')
   // `--version` keeps Commander's default `-V`. `--verbose` is intentionally
-  // long-only: a root `-v` would shadow `upgrade`'s local `-v, --version`,
-  // which Commander resolves globally (parsing `tale upgrade -v X` as the root
+  // long-only: a root `-v` would shadow `update`'s local `-v, --version`,
+  // which Commander resolves globally (parsing `tale update -v X` as the root
   // flag and erroring on the leftover arg).
   .version(pkg.version)
   .option('--verbose', 'verbose output (debug logs, raw passthrough)')
@@ -57,10 +59,17 @@ program
 // Resolve the global flags into ONE output mode and apply it before any command
 // runs, so every command inherits the same color/verbosity/json configuration.
 // Global flags go before the subcommand: `tale --json status`.
-program.hook('preAction', () => {
+//
+// Then keep the CLI in lockstep with the instance it manages: `ensureAligned`
+// re-execs under the workspace's recorded version when the running binary
+// differs. It's a pure file read (no network) when already aligned — the
+// common case. `--version`/`--help`/bare `tale` never reach `preAction`, so
+// they always report/run the binary as-is.
+program.hook('preAction', async (_thisCommand, actionCommand) => {
   const mode = resolveOutputMode(program.opts<GlobalFlags>());
   configureOutput(mode);
   setActiveOutputMode(mode);
+  await ensureAligned(actionCommand.name());
 });
 
 // Group headings keep the command list scannable. Commander renders each
@@ -80,10 +89,11 @@ program.addCommand(createBackupCommand().helpGroup(OPERATE));
 program.addCommand(createRestoreCommand().helpGroup(OPERATE));
 program.addCommand(createRollbackCommand().helpGroup(OPERATE));
 
-program.addCommand(createUpgradeCommand().helpGroup(MAINTAIN));
+program.addCommand(createUpdateCommand().helpGroup(MAINTAIN));
 program.addCommand(createMigrateCommand().helpGroup(MAINTAIN));
 program.addCommand(createCleanupCommand().helpGroup(MAINTAIN));
 program.addCommand(createResetCommand().helpGroup(MAINTAIN));
+program.addCommand(createUninstallCommand().helpGroup(MAINTAIN));
 program.addCommand(createConfigCommand().helpGroup(MAINTAIN));
 
 program.addCommand(createAuthCommand().helpGroup(ADVANCED));
diff --git a/tools/cli/src/lib/actions/deploy.ts b/tools/cli/src/lib/actions/deploy.ts
index 9a0acc647b..41ccf8542d 100644
--- a/tools/cli/src/lib/actions/deploy.ts
+++ b/tools/cli/src/lib/actions/deploy.ts
@@ -11,14 +11,13 @@ import { rotateSnapshots } from '../backup/rotate-snapshots';
 import { REQUIRED_VOLUMES } from '../compose/generators/constants';
 import { generateColorCompose } from '../compose/generators/generate-color-compose';
 import { generateStatefulCompose } from '../compose/generators/generate-stateful-compose';
+import { selectDefaultServices } from '../compose/select-services';
 import {
   type RotatableService,
   type ServiceName,
   type StatefulService,
-  LOCKSTEP_SERVICES,
-  ROTATABLE_SERVICES,
-  STATEFUL_SERVICES,
-  isLockstepService,
+  type StopGatedService,
+  STOP_GATED_SERVICES,
   isRotatableService,
   isStatefulService,
 } from '../compose/types';
@@ -38,6 +37,8 @@ import { getNextColor } from '../state/get-next-color';
 import { setCurrentColor } from '../state/set-current-color';
 import { setPreviousVersion } from '../state/set-previous-version';
 import { withLock } from '../state/with-lock';
+import { drainConvex, endDrainConvex } from './drain-convex';
+import { flipSandboxTier } from './flip-sandbox';
 import { reseedAllOrgsFromBuiltin } from './reseed-all-orgs';
 
 async function ensureInfrastructure(
@@ -70,7 +71,12 @@ async function ensureInfrastructure(
 
 interface DeployOptions {
   version: string;
-  updateStateful: boolean;
+  /**
+   * Opt into updating the stop-gated tier (`db`, `proxy`) even while it's
+   * running — accepts the brief downtime of recreating Postgres / the proxy.
+   * Without it, a running stop-gated service is left untouched (with a hint).
+   */
+  stop: boolean;
   env: DeploymentEnv;
   hostAlias: string;
   dryRun: boolean;
@@ -105,7 +111,7 @@ interface DeployOptions {
 }
 
 export async function deploy(options: DeployOptions): Promise<void> {
-  const { version, updateStateful, env, hostAlias, dryRun, services } = options;
+  const { version, stop, env, hostAlias, dryRun, services } = options;
   const streamLogs = !options.quiet && (process.stdout.isTTY ?? false);
 
   // Track containers started during this deploy for cleanup on interrupt
@@ -203,51 +209,37 @@ export async function deploy(options: DeployOptions): Promise<void> {
         rotatableToUpdate = services.filter(isRotatableService);
         statefulToUpdate = services.filter(isStatefulService);
       } else {
-        // Default: all rotatable services PLUS lockstep services.
-        //
-        // Lockstep services (sandbox, sandbox-egress) version in step with
-        // the platform image — shipping an old sandbox against new
-        // platform code would break the SSE wire contract. Including
-        // them on every default deploy matches the build matrix's
-        // single-version policy and avoids the "platform upgraded but
-        // sandbox stayed on yesterday's image" failure mode that drove
-        // the sandbox-wobbly-origami plan §5 rollout decision.
-        rotatableToUpdate = [...ROTATABLE_SERVICES];
-
-        if (isFirstDeploy || updateStateful) {
-          statefulToUpdate = [...STATEFUL_SERVICES];
-          if (isFirstDeploy) {
-            logger.notice(
-              'First deployment detected - including infrastructure services',
-            );
-          }
-        } else {
-          // Check if any required stateful services are not running, and
-          // ALWAYS include lockstep services so they roll forward with
-          // the platform image.
-          const missingStateful: StatefulService[] = [];
-          for (const service of STATEFUL_SERVICES) {
-            if (isLockstepService(service)) continue; // handled below
-            const containerName = `${getProjectId()}-${service}`;
-            const running = await isContainerRunning(containerName);
-            if (!running) {
-              missingStateful.push(service);
-            }
-          }
-
-          const lockstepToUpdate: StatefulService[] = [...LOCKSTEP_SERVICES];
+        // Default deploy uses the three-tier policy (see select-services.ts):
+        // rotatable (platform) blue-green; convex always-rolls in-place; the
+        // sandbox tier (sandbox + sandbox-egress) rolls separately via
+        // flipSandboxTier in lockstep with platform's colour; stop-gated
+        // (db, proxy) only when stopped / first deploy / --stop, else left
+        // running with a hint.
+        const runningState = new Map<StopGatedService, boolean>();
+        for (const service of STOP_GATED_SERVICES) {
+          runningState.set(
+            service,
+            await isContainerRunning(`${getProjectId()}-${service}`),
+          );
+        }
+        const selection = selectDefaultServices({
+          isFirstDeploy,
+          stop,
+          isStopGatedRunning: (s) => runningState.get(s) ?? false,
+        });
+        rotatableToUpdate = selection.rotatable;
+        statefulToUpdate = selection.stateful;
 
-          if (missingStateful.length > 0) {
-            logger.notice(
-              `Infrastructure services not running: ${missingStateful.join(', ')} - including automatically`,
-            );
-          }
-          if (lockstepToUpdate.length > 0) {
-            logger.info(
-              `Lockstep services: ${lockstepToUpdate.join(', ')} - included on every default deploy`,
-            );
-          }
-          statefulToUpdate = [...missingStateful, ...lockstepToUpdate];
+        if (isFirstDeploy) {
+          logger.notice(
+            'First deployment detected — including infrastructure services',
+          );
+        }
+        if (selection.leftRunning.length > 0) {
+          logger.warn(
+            `Left running, not updated: ${selection.leftRunning.join(', ')}. ` +
+              'Re-run with `tale deploy --stop` to update them (brief downtime).',
+          );
         }
       }
 
@@ -277,6 +269,12 @@ export async function deploy(options: DeployOptions): Promise<void> {
 
       // Pull all required images first
       logger.step(`${prefix}Pulling images...`);
+      // On a default (blue-green) deploy the sandbox tier rolls via
+      // flipSandboxTier — NOT through statefulToUpdate — so its images must be
+      // pulled here even though sandbox isn't in statefulToUpdate. An explicit
+      // `--services` deploy is in-place and never rolls the sandbox tier
+      // (run-deploy rejects `--services sandbox`).
+      const sandboxTierRolls = !inPlaceUpdate;
       const imagesToPull = [
         ...rotatableToUpdate.map(
           (s) => `${env.GHCR_REGISTRY}/tale-${s}:${version}`,
@@ -284,6 +282,12 @@ export async function deploy(options: DeployOptions): Promise<void> {
         ...statefulToUpdate.map(
           (s) => `${env.GHCR_REGISTRY}/tale-${s}:${version}`,
         ),
+        ...(sandboxTierRolls
+          ? [
+              `${env.GHCR_REGISTRY}/tale-sandbox:${version}`,
+              `${env.GHCR_REGISTRY}/tale-sandbox-egress:${version}`,
+            ]
+          : []),
       ];
 
       // The spawner's runtime image (consumed by `docker run` of user code,
@@ -291,9 +295,11 @@ export async function deploy(options: DeployOptions): Promise<void> {
       // spawner's `SANDBOX_RUNTIME_IMAGE` default (`tale-sandbox-runtime:latest`).
       // Without this, a fresh deploy host has no local runtime image and the
       // first /v1/execute fails with image-not-found. Mirrors build.yml's
-      // re-tag step. Pulled whenever sandbox or sandbox-egress is being
-      // updated, since the runtime image versions in lockstep with the spawner.
+      // re-tag step. Needed whenever the sandbox tier rolls — which on a default
+      // deploy happens via flipSandboxTier, not statefulToUpdate — since the
+      // runtime image versions in lockstep with the spawner.
       const needsRuntimeImage =
+        sandboxTierRolls ||
         statefulToUpdate.includes('sandbox') ||
         statefulToUpdate.includes('sandbox-egress');
       const runtimeImageRemote = needsRuntimeImage
@@ -371,7 +377,21 @@ export async function deploy(options: DeployOptions): Promise<void> {
         // block db/proxy/convex.
         const controllerEnabled = Boolean(process.env.CONTROLLER_TOKEN);
 
+        // Will this deploy actually recreate convex? `docker compose up -d` is a
+        // no-op when the image + config are unchanged, so only drain in-flight
+        // chat generation when convex's image version is changing (or a forced
+        // recreate). Draining a no-op deploy would refuse chats for nothing.
+        const convexWillRecreate =
+          !isFirstDeploy &&
+          statefulToUpdate.includes('convex') &&
+          (Boolean(options.forceRecreate) ||
+            (await getContainerVersion(`${getProjectId()}-convex`)) !==
+              version);
+
         if (dryRun) {
+          if (convexWillRecreate) {
+            await drainConvex({ dryRun: true });
+          }
           for (const service of statefulToUpdate) {
             logger.info(`${prefix}Would deploy stateful service: ${service}`);
           }
@@ -381,6 +401,13 @@ export async function deploy(options: DeployOptions): Promise<void> {
             );
           }
         } else {
+          // Drain in-flight chat generations before the in-place recreate kills
+          // them. Best-effort (see drain-convex.ts); the recovery watchdog
+          // finalizes anything that outlasts the drain budget.
+          if (convexWillRecreate) {
+            await drainConvex({ dryRun: false });
+          }
+
           const result = await dockerCompose(
             statefulCompose,
             [
@@ -416,6 +443,13 @@ export async function deploy(options: DeployOptions): Promise<void> {
             }
           }
 
+          // Convex is back and healthy — lift the drain flag so new chat turns
+          // are accepted again. Best-effort; the backend's auto-expiry clears it
+          // anyway if this fails (see drain-convex.ts).
+          if (convexWillRecreate) {
+            await endDrainConvex();
+          }
+
           // The controller is a non-critical opt-in sidecar. Bring it up in its
           // OWN `up -d` only after the core services are healthy, and treat any
           // failure (e.g. the image isn't published/pulled yet) as a warning —
@@ -578,6 +612,15 @@ export async function deploy(options: DeployOptions): Promise<void> {
                 );
               }
             }
+            await flipSandboxTier({
+              config: serviceConfig,
+              deployDir: env.DEPLOY_DIR,
+              currentColor,
+              nextColor,
+              dryRun: true,
+              streamLogs,
+              healthTimeout: env.HEALTH_CHECK_TIMEOUT,
+            });
           } else {
             // Clean up any stale next-color containers from a previous failed deployment
             for (const service of rotatableToUpdate) {
@@ -640,6 +683,29 @@ export async function deploy(options: DeployOptions): Promise<void> {
 
             // Drain old color (if exists)
             if (currentColor) {
+              // Pre-mark the old platform colour as shutting down BEFORE the
+              // drain sleep. Its /api/health then returns 503, so the proxy
+              // ejects it and routes NEW requests only to the new colour while
+              // in-flight requests finish during the window. Without this, both
+              // colours keep the `platform` alias for the whole sleep and
+              // traffic is split across two versions. Best-effort + platform-
+              // specific (the marker lives in the platform entrypoint); a
+              // failure just falls back to the graceful stop below.
+              for (const service of rotatableToUpdate) {
+                if (service !== 'platform') continue;
+                const oldName = `${getProjectId()}-${service}-${currentColor}`;
+                const marked = await exec('docker', [
+                  'exec',
+                  oldName,
+                  'touch',
+                  '/tmp/platform-shutting-down',
+                ]);
+                if (!marked.success) {
+                  logger.debug(
+                    `Could not pre-mark ${oldName} for shutdown (continuing): ${marked.stderr.trim()}`,
+                  );
+                }
+              }
               logger.step(
                 `Draining ${currentColor} services (${env.DRAIN_TIMEOUT}s)...`,
               );
@@ -661,6 +727,19 @@ export async function deploy(options: DeployOptions): Promise<void> {
                 }
               }
             }
+
+            // Roll the sandbox tier (sandbox + sandbox-egress) onto the same
+            // new colour with its own zero-gap blue-green flip (bring up new
+            // colour → move the `sandbox` alias → drain + tear down the old).
+            await flipSandboxTier({
+              config: serviceConfig,
+              deployDir: env.DEPLOY_DIR,
+              currentColor,
+              nextColor,
+              dryRun: false,
+              streamLogs,
+              healthTimeout: env.HEALTH_CHECK_TIMEOUT,
+            });
           }
         }
       }
diff --git a/tools/cli/src/lib/actions/drain-convex.test.ts b/tools/cli/src/lib/actions/drain-convex.test.ts
new file mode 100644
index 0000000000..4407e33c1c
--- /dev/null
+++ b/tools/cli/src/lib/actions/drain-convex.test.ts
@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+const runConvexAdminMock = mock();
+const findPlatformContainerMock = mock();
+const loggerWarnMock = mock();
+const loggerInfoMock = mock();
+
+mock.module('../docker/find-platform-container', () => ({
+  findPlatformContainer: findPlatformContainerMock,
+}));
+// Keep the pure helpers faithful (drain-convex relies on their contract); only
+// the docker-touching `runConvexAdmin` is stubbed.
+mock.module('../docker/convex-run', () => ({
+  runConvexAdmin: runConvexAdminMock,
+  redactAdminKey: (s: string) => s,
+  parseTrailingJson: (
+    stdout: string,
+    isT: (value: unknown) => boolean,
+  ): unknown => {
+    const lines = stdout.trim().split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i].trimStart().startsWith('{')) continue;
+      try {
+        const parsed: unknown = JSON.parse(lines.slice(i).join('\n'));
+        if (isT(parsed)) return parsed;
+      } catch {
+        /* try earlier */
+      }
+    }
+    return null;
+  },
+}));
+mock.module('../../utils/logger', () => ({
+  info: loggerInfoMock,
+  warn: loggerWarnMock,
+  step: mock(),
+  debug: mock(),
+  error: mock(),
+  success: mock(),
+}));
+
+const { drainConvex, endDrainConvex } = await import('./drain-convex');
+
+function ok(stdout: string) {
+  return { success: true, stdout, stderr: '', exitCode: 0 };
+}
+function fail(stderr: string) {
+  return { success: false, stdout: '', stderr, exitCode: 1 };
+}
+
+beforeEach(() => {
+  findPlatformContainerMock.mockResolvedValue('tale-platform-blue');
+});
+afterEach(() => {
+  runConvexAdminMock.mockReset();
+  findPlatformContainerMock.mockReset();
+  loggerWarnMock.mockReset();
+  loggerInfoMock.mockReset();
+});
+
+describe('drainConvex', () => {
+  test('dry-run never touches the container or the backend', async () => {
+    await drainConvex({ dryRun: true });
+    expect(findPlatformContainerMock).not.toHaveBeenCalled();
+    expect(runConvexAdminMock).not.toHaveBeenCalled();
+  });
+
+  test('skips gracefully when no platform container is found', async () => {
+    findPlatformContainerMock.mockRejectedValue(new Error('no container'));
+    await drainConvex({ dryRun: false });
+    expect(runConvexAdminMock).not.toHaveBeenCalled();
+  });
+
+  test('proceeds (warns) when the backend lacks the drain control plane', async () => {
+    // beginDrain fails → older backend; do NOT poll, just warn and return.
+    runConvexAdminMock.mockResolvedValueOnce(fail('function not found'));
+    await drainConvex({ dryRun: false });
+    expect(runConvexAdminMock).toHaveBeenCalledTimes(1);
+    expect(loggerWarnMock).toHaveBeenCalledTimes(1);
+  });
+
+  test('returns as soon as inFlight reaches 0', async () => {
+    runConvexAdminMock
+      .mockResolvedValueOnce(ok('{"inFlight":2}')) // beginDrain
+      .mockResolvedValueOnce(ok('{"draining":true,"inFlight":1}')) // poll 1
+      .mockResolvedValueOnce(ok('{"draining":true,"inFlight":0}')); // poll 2
+    await drainConvex({ dryRun: false, pollMs: 1, timeoutMs: 5_000 });
+    expect(runConvexAdminMock).toHaveBeenCalledTimes(3);
+    const infoLines = loggerInfoMock.mock.calls.map((c) => String(c[0]));
+    expect(infoLines.some((l) => l.includes('finished'))).toBe(true);
+  });
+
+  test('gives up and warns after the budget, leaving recreate to proceed', async () => {
+    runConvexAdminMock.mockImplementation((fn: string) =>
+      fn.endsWith('beginDrain')
+        ? Promise.resolve(ok('{"inFlight":1}'))
+        : Promise.resolve(ok('{"draining":true,"inFlight":1}')),
+    );
+    await drainConvex({ dryRun: false, pollMs: 1, timeoutMs: 10 });
+    expect(loggerWarnMock).toHaveBeenCalledTimes(1);
+    const warn = String(loggerWarnMock.mock.calls[0]?.[0] ?? '');
+    expect(warn).toContain('recreating anyway');
+  });
+});
+
+describe('endDrainConvex', () => {
+  test('clears the flag through the platform container', async () => {
+    runConvexAdminMock.mockResolvedValue(ok('null'));
+    await endDrainConvex();
+    expect(runConvexAdminMock).toHaveBeenCalledWith(
+      'control/drain:endDrain',
+      expect.objectContaining({ container: 'tale-platform-blue' }),
+    );
+  });
+
+  test('never throws when the container is gone', async () => {
+    findPlatformContainerMock.mockRejectedValue(new Error('no container'));
+    await endDrainConvex();
+    expect(runConvexAdminMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/tools/cli/src/lib/actions/drain-convex.ts b/tools/cli/src/lib/actions/drain-convex.ts
new file mode 100644
index 0000000000..e63e5485db
--- /dev/null
+++ b/tools/cli/src/lib/actions/drain-convex.ts
@@ -0,0 +1,128 @@
+/**
+ * Deploy DRAIN orchestration for the always-roll convex tier.
+ *
+ * `tale deploy` recreates the convex container in-place on a version change,
+ * restarting the backend and killing every in-flight action — including
+ * non-durable chat generation. `drainConvex` tells the backend to refuse NEW
+ * chat turns (the client retries onto the restart) and waits for in-flight
+ * generations to finish before the recreate; `endDrainConvex` clears the flag
+ * once convex is healthy again. Mirrors the sandbox tier's `/v1/drain` flow
+ * (flip-sandbox.ts), but the control channel is `bunx convex run` through the
+ * platform container (docker/convex-run.ts).
+ *
+ * Best-effort by design: an older backend that predates the drain control
+ * plane (the first deploy that ships this feature), or any transient error,
+ * just skips the drain and proceeds — the recovery watchdog
+ * (`agents/recover_stuck_chat_turns.ts`) finalizes whatever the recreate cuts.
+ */
+
+import * as logger from '../../utils/logger';
+import {
+  parseTrailingJson,
+  redactAdminKey,
+  runConvexAdmin,
+} from '../docker/convex-run';
+import { findPlatformContainer } from '../docker/find-platform-container';
+
+// Plain chat turns are short (seconds–~2 min); 3 min covers the tail without
+// stalling the deploy. Past the budget we recreate anyway and let the watchdog
+// finalize stragglers (mirrors flip-sandbox.ts's drain ceiling).
+const DRAIN_POLL_MS = 2_000;
+const DRAIN_TIMEOUT_MS = 3 * 60_000;
+
+interface DrainStatus {
+  draining: boolean;
+  inFlight: number;
+}
+
+function isDrainStatus(value: unknown): value is DrainStatus {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Record<string, unknown>).inFlight === 'number'
+  );
+}
+
+function short(text: string): string {
+  return redactAdminKey(text).trim().slice(0, 200);
+}
+
+/**
+ * Refuse new chat turns and wait (bounded) for in-flight generations to finish
+ * before the convex recreate. Never throws — a drain failure degrades to
+ * "proceed; the watchdog recovers cut turns". `pollMs`/`timeoutMs` default to
+ * the module constants and exist only so unit tests can run the loop fast.
+ */
+export async function drainConvex(opts: {
+  dryRun: boolean;
+  pollMs?: number;
+  timeoutMs?: number;
+}): Promise<void> {
+  if (opts.dryRun) {
+    logger.info(
+      '[DRY-RUN] Would drain in-flight chat generations before recreating convex',
+    );
+    return;
+  }
+
+  const pollMs = opts.pollMs ?? DRAIN_POLL_MS;
+  const timeoutMs = opts.timeoutMs ?? DRAIN_TIMEOUT_MS;
+
+  let container: string;
+  try {
+    container = await findPlatformContainer();
+  } catch {
+    logger.debug('No platform container found; skipping convex drain.');
+    return;
+  }
+
+  logger.step('Draining in-flight chat generations before convex recreate...');
+  const begin = await runConvexAdmin('control/drain:beginDrain', { container });
+  if (!begin.success) {
+    logger.warn(
+      `Convex drain unavailable — proceeding (cut turns will be recovered by the watchdog): ${short(begin.stderr || begin.stdout)}`,
+    );
+    return;
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const res = await runConvexAdmin('control/drain:drainStatus', {
+      container,
+    });
+    const status = res.success
+      ? parseTrailingJson(res.stdout, isDrainStatus)
+      : null;
+    if (status && status.inFlight === 0) {
+      logger.info('All in-flight chat generations finished.');
+      return;
+    }
+    if (Date.now() >= deadline) {
+      logger.warn(
+        `Convex still has ${status?.inFlight ?? 'unknown'} generation(s) after ${timeoutMs / 1000}s — recreating anyway; the recovery watchdog will finalize them.`,
+      );
+      return;
+    }
+    await Bun.sleep(pollMs);
+  }
+}
+
+/**
+ * Clear the drain flag after convex is healthy again. Best-effort: if it fails
+ * (older backend, transient error), the backend's `drainExpiresAt` auto-expiry
+ * clears the flag within 15 min so chats can never be refused forever.
+ */
+export async function endDrainConvex(): Promise<void> {
+  let container: string;
+  try {
+    container = await findPlatformContainer();
+  } catch {
+    return;
+  }
+  const res = await runConvexAdmin('control/drain:endDrain', { container });
+  if (!res.success) {
+    logger.debug(
+      `endDrain failed (auto-expiry backstop will clear the flag): ${short(res.stderr || res.stdout)}`,
+    );
+  }
+}
diff --git a/tools/cli/src/lib/actions/flip-sandbox.test.ts b/tools/cli/src/lib/actions/flip-sandbox.test.ts
new file mode 100644
index 0000000000..ecea3cfcde
--- /dev/null
+++ b/tools/cli/src/lib/actions/flip-sandbox.test.ts
@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import type { ServiceConfig } from '../compose/types';
+import { setProjectId } from '../project/project-context';
+
+setProjectId('tale');
+
+const dockerMock = mock();
+const dockerComposeMock = mock();
+const stopContainerMock = mock();
+const removeContainerMock = mock();
+const waitForHealthyMock = mock();
+const loggerWarnMock = mock();
+
+mock.module('../docker/docker', () => ({ docker: dockerMock }));
+mock.module('../docker/docker-compose', () => ({
+  dockerCompose: dockerComposeMock,
+}));
+mock.module('../docker/stop-container', () => ({
+  stopContainer: stopContainerMock,
+}));
+mock.module('../docker/remove-container', () => ({
+  removeContainer: removeContainerMock,
+}));
+mock.module('../docker/wait-for-healthy', () => ({
+  waitForHealthy: waitForHealthyMock,
+}));
+mock.module('../../utils/logger', () => ({
+  info: mock(),
+  warn: loggerWarnMock,
+  step: mock(),
+  debug: mock(),
+  error: mock(),
+  success: mock(),
+}));
+
+const { flipSandboxTier } = await import('./flip-sandbox');
+
+const config: ServiceConfig = {
+  version: '1.2.3',
+  registry: 'ghcr.io/tale-project/tale',
+};
+
+function ok(stdout = '') {
+  return { success: true, stdout, stderr: '', exitCode: 0 };
+}
+
+/**
+ * Route the `docker` mock by argv: drain-status returns the per-test JSON; the
+ * session-container `ps -aq` returns the per-test ids; everything else
+ * (network connect/disconnect, drain POST) succeeds with empty stdout.
+ */
+function arrangeDocker(opts: {
+  drainStatusJson: string;
+  sessionContainerIds?: string[];
+}): void {
+  dockerMock.mockImplementation((...args: string[]) => {
+    const joined = args.join(' ');
+    if (joined.includes('/v1/drain-status')) {
+      return Promise.resolve(ok(opts.drainStatusJson));
+    }
+    if (args[0] === 'ps') {
+      return Promise.resolve(ok((opts.sessionContainerIds ?? []).join('\n')));
+    }
+    return Promise.resolve(ok());
+  });
+}
+
+beforeEach(() => {
+  dockerComposeMock.mockResolvedValue(ok());
+  waitForHealthyMock.mockResolvedValue(true);
+  stopContainerMock.mockResolvedValue(true);
+  removeContainerMock.mockResolvedValue(true);
+});
+afterEach(() => {
+  dockerMock.mockReset();
+  dockerComposeMock.mockReset();
+  stopContainerMock.mockReset();
+  removeContainerMock.mockReset();
+  waitForHealthyMock.mockReset();
+  loggerWarnMock.mockReset();
+});
+
+function oldSpawnerStopped(): boolean {
+  // The old colour's spawner container is `tale-sandbox-blue` here.
+  return stopContainerMock.mock.calls.some(
+    (c) => String(c[0]) === 'tale-sandbox-blue',
+  );
+}
+
+describe('flipSandboxTier teardown vs linger', () => {
+  test('tears the old colour down when it has no live sessions', async () => {
+    arrangeDocker({ drainStatusJson: '{"inFlight":0,"sessions":0}' });
+
+    await flipSandboxTier({
+      config,
+      deployDir: '/tmp/tale-flip-test',
+      currentColor: 'blue',
+      nextColor: 'green',
+      dryRun: false,
+      streamLogs: false,
+      healthTimeout: 1,
+    });
+
+    expect(oldSpawnerStopped()).toBe(true);
+  });
+
+  test('lingers the old colour when it still has live sessions', async () => {
+    arrangeDocker({ drainStatusJson: '{"inFlight":0,"sessions":2}' });
+
+    await flipSandboxTier({
+      config,
+      deployDir: '/tmp/tale-flip-test',
+      currentColor: 'blue',
+      nextColor: 'green',
+      dryRun: false,
+      streamLogs: false,
+      healthTimeout: 1,
+    });
+
+    // Teardown skipped — the old spawner keeps running for its sessions.
+    expect(oldSpawnerStopped()).toBe(false);
+    const warned = loggerWarnMock.mock.calls.map((c) => String(c[0]));
+    expect(warned.some((l) => l.includes('lingering'))).toBe(true);
+  });
+
+  test('lingers (does not tear down) when the session count stays unknown', async () => {
+    // Drain POST succeeds (default mock) but every drain-status read is
+    // unparseable → the final status is unknown. Tearing down here could kill
+    // live sessions, so the flip must linger instead.
+    arrangeDocker({ drainStatusJson: 'not json at all' });
+
+    await flipSandboxTier({
+      config,
+      deployDir: '/tmp/tale-flip-test',
+      currentColor: 'blue',
+      nextColor: 'green',
+      dryRun: false,
+      streamLogs: false,
+      healthTimeout: 1,
+      // Drive the drain loop to its (unknown) deadline fast.
+      drainPollMs: 1,
+      drainTimeoutMs: 5,
+    });
+
+    expect(oldSpawnerStopped()).toBe(false);
+    const warned = loggerWarnMock.mock.calls.map((c) => String(c[0]));
+    expect(warned.some((l) => l.includes('session count is unknown'))).toBe(
+      true,
+    );
+  });
+});
diff --git a/tools/cli/src/lib/actions/flip-sandbox.ts b/tools/cli/src/lib/actions/flip-sandbox.ts
new file mode 100644
index 0000000000..5d3f5663a2
--- /dev/null
+++ b/tools/cli/src/lib/actions/flip-sandbox.ts
@@ -0,0 +1,337 @@
+import { getProjectId } from '../../utils/load-env';
+import * as logger from '../../utils/logger';
+import { generateSandboxColorCompose } from '../compose/generators/generate-sandbox-color-compose';
+import type { DeploymentColor, ServiceConfig } from '../compose/types';
+import { docker } from '../docker/docker';
+import { dockerCompose } from '../docker/docker-compose';
+import { removeContainer } from '../docker/remove-container';
+import { stopContainer } from '../docker/stop-container';
+import { waitForHealthy } from '../docker/wait-for-healthy';
+
+// One-shot sandbox executions are short (default 30s, max 5min), so the drain
+// poll is bounded — past the ceiling we tear down anyway (the spawner's own
+// SIGTERM drain + stop_grace_period is the backstop).
+const DRAIN_POLL_MS = 2_000;
+const DRAIN_TIMEOUT_MS = 5 * 60_000;
+
+interface FlipSandboxOptions {
+  config: ServiceConfig;
+  deployDir: string;
+  /** Platform's current (old) colour, or `null` on a first deploy / legacy single-container migration. */
+  currentColor: DeploymentColor | null;
+  /** Platform's next (new) colour — the sandbox tier rides the same colour. */
+  nextColor: DeploymentColor;
+  dryRun: boolean;
+  streamLogs: boolean;
+  /** env.HEALTH_CHECK_TIMEOUT (seconds). */
+  healthTimeout: number;
+  /** Drain poll interval / ceiling. Default to the module constants; exposed
+   *  only so unit tests can run the drain loop fast. */
+  drainPollMs?: number;
+  drainTimeoutMs?: number;
+}
+
+/**
+ * Zero-gap blue-green roll of the sandbox tier (`sandbox` + `sandbox-egress`),
+ * sharing the platform's colour. Sequence:
+ *
+ *   1. Bring up the NEXT colour's spawner + egress (their own containers, on the
+ *      shared `tale-sandbox-net`; the spawner advertises `tale.color=<next>`).
+ *   2. Wait for the next spawner to pass its health check.
+ *   3. Move the bare `sandbox` network alias onto the next spawner (Convex's
+ *      `http://sandbox:8003` now resolves to the new colour for NEW executions;
+ *      in-flight cancels still target the old colour via its stored row colour).
+ *   4. Drain the OLD colour: POST /v1/drain (it 503s new work; spawner_client
+ *      retries land on the new colour), then poll /v1/drain-status until its
+ *      in-flight one-shot count hits 0.
+ *   5. If the old colour has NO live sessions, tear it down (spawner + egress +
+ *      its session containers). If it DOES, LINGER it: leave the spawner +
+ *      egress + session containers running on the still-resolvable
+ *      `sandbox-<old>` alias so a long agent turn survives the deploy. The old
+ *      spawner keeps serving exec/cancel/attach for its sessions while 503ing
+ *      NEW work; Convex routes session ops to `sandbox-<spawnerColor>` (the
+ *      colour recorded on the session row at create).
+ *
+ * Linger bounds (no orphans): the lingering spawner self-reaps its sessions
+ * after `SANDBOX_SESSION_MAX_LINGER_MS` even if this CLI dies mid-flip, and the
+ * NEXT flip back to that colour reaps any leftover session containers (step 1).
+ * Because the model is exactly two colours, a session survives AT MOST one flip;
+ * a second flip reclaims it (compute released, workspace preserved for resume).
+ *
+ * NOTE: the drain channel is `docker exec <spawner> curl localhost:8003/...`
+ * (the spawner is not host-exposed; `docker exec` implies host-root).
+ */
+export async function flipSandboxTier(opts: FlipSandboxOptions): Promise<void> {
+  const pid = getProjectId();
+  const { config, deployDir, currentColor, nextColor, dryRun } = opts;
+  const prefix = dryRun ? '[DRY-RUN] ' : '';
+  const internalNet = `${pid}_internal`;
+  const nextSpawner = `${pid}-sandbox-${nextColor}`;
+  const services = [`sandbox-egress-${nextColor}`, `sandbox-${nextColor}`];
+
+  logger.step(`${prefix}Rolling sandbox tier → ${nextColor} (blue-green)...`);
+
+  if (dryRun) {
+    logger.info(
+      `${prefix}Would bring up ${services.join(', ')}, move the \`sandbox\` ` +
+        `alias to ${nextColor}, drain ${currentColor ?? 'the legacy spawner'}, ` +
+        `then remove it.`,
+    );
+    return;
+  }
+
+  // 1. Clean any stale next-colour containers from an aborted prior flip, then
+  //    bring the next colour up. Because the model is exactly two colours, the
+  //    nextColour is also the colour that may still be LINGERING from the last
+  //    flip (it kept serving its sessions) — so reap its leftover session
+  //    containers here too, the reaper-of-last-resort for a session that
+  //    survived one flip but not a second.
+  for (const svc of services) {
+    const name = `${pid}-${svc}`;
+    if (await stopContainer(name)) await removeContainer(name);
+  }
+  await removeColorSessionContainers(pid, nextColor);
+  const compose = generateSandboxColorCompose(config, nextColor);
+  const up = await dockerCompose(compose, ['up', '-d', ...services], {
+    projectName: `${pid}-sandbox-${nextColor}`,
+    cwd: deployDir,
+  });
+  if (!up.success) {
+    throw new Error(
+      `Failed to start sandbox ${nextColor}: ${up.stderr.trim()}`,
+    );
+  }
+
+  // 2. Health.
+  const healthy = await waitForHealthy(nextSpawner, {
+    timeout: opts.healthTimeout,
+    streamLogs: opts.streamLogs,
+  });
+  if (!healthy) {
+    throw new Error(`sandbox-${nextColor} failed its health check`);
+  }
+
+  // 3. Point the active `sandbox` alias at the new colour.
+  await moveSandboxAlias(internalNet, nextSpawner, nextColor);
+
+  // 4 + 5. Drain the previous colour, then EITHER tear it down (no live
+  //         sessions) or LINGER it (live sessions keep running on
+  //         `sandbox-<old>` until they end or the spawner's max-linger reap).
+  if (currentColor) {
+    const outcome = await drainOldColor(pid, currentColor, {
+      pollMs: opts.drainPollMs,
+      timeoutMs: opts.drainTimeoutMs,
+    });
+    if (outcome.kind === 'gone') {
+      // Drain signal never landed — the old colour is already gone or predates
+      // the drain endpoint. Nothing alive to linger; reclaim its containers.
+      await teardownColor(pid, currentColor);
+    } else if (outcome.status && outcome.status.sessions > 0) {
+      logger.warn(
+        `sandbox ${currentColor} has ${outcome.status.sessions} live session(s) — lingering on sandbox-${currentColor} until they end or its max-linger TTL; not tearing it down. A subsequent flip back to ${currentColor} reclaims it.`,
+      );
+    } else if (outcome.status === null) {
+      // Drain was acknowledged but its session count stayed UNKNOWN to the
+      // deadline (status endpoint unreachable / malformed). Treat unknown as
+      // "may still have sessions" and LINGER — tearing down here could kill a
+      // live agent turn. The spawner's own max-linger reap is the backstop.
+      logger.warn(
+        `sandbox ${currentColor} drained but its session count is unknown — lingering on sandbox-${currentColor} rather than risk tearing down live sessions. Its max-linger TTL (or the next flip back) reclaims it.`,
+      );
+    } else {
+      await teardownColor(pid, currentColor);
+    }
+  } else {
+    await teardownLegacy(pid);
+  }
+
+  logger.success(`Sandbox tier is now on ${nextColor}`);
+}
+
+/**
+ * Give the next spawner the bare `sandbox` alias on the internal network. It is
+ * already attached (compose added the `sandbox-<color>` service-key alias), so
+ * we disconnect + reconnect with BOTH aliases. The brief disconnect is safe:
+ * the new colour isn't serving `sandbox` yet (Convex still resolves it to the
+ * old colour), and the old colour keeps the alias until teardown.
+ */
+async function moveSandboxAlias(
+  network: string,
+  container: string,
+  color: DeploymentColor,
+): Promise<void> {
+  // Disconnect is best-effort: if it wasn't connected (unexpected) the connect
+  // below still establishes the aliases.
+  const dis = await docker('network', 'disconnect', network, container);
+  if (!dis.success) {
+    logger.debug(
+      `network disconnect ${container} (continuing): ${dis.stderr.trim()}`,
+    );
+  }
+  const con = await docker(
+    'network',
+    'connect',
+    '--alias',
+    'sandbox',
+    '--alias',
+    `sandbox-${color}`,
+    network,
+    container,
+  );
+  if (!con.success) {
+    throw new Error(
+      `Failed to move the \`sandbox\` alias to ${container}: ${con.stderr.trim()}`,
+    );
+  }
+}
+
+interface DrainStatus {
+  inFlight: number;
+  sessions: number;
+}
+
+/**
+ * Read + validate a colour's `/v1/drain-status`. Returns `null` when the
+ * endpoint is unreachable or the JSON shape is unexpected — callers must treat
+ * `null` as "unknown" and NOT as "0 in flight / 0 sessions" (that would tear a
+ * colour down while work is still running). `sessions` defaults to 0 on an
+ * older spawner that doesn't report it.
+ */
+async function readDrainStatus(
+  pid: string,
+  color: DeploymentColor,
+): Promise<DrainStatus | null> {
+  const res = await docker(
+    'exec',
+    `${pid}-sandbox-${color}`,
+    'curl',
+    '-fsS',
+    'http://localhost:8003/v1/drain-status',
+  );
+  if (!res.success) return null;
+  try {
+    const parsed: unknown = JSON.parse(res.stdout);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const o = parsed as Record<string, unknown>;
+    if (typeof o.inFlight !== 'number') return null;
+    return {
+      inFlight: o.inFlight,
+      sessions: typeof o.sessions === 'number' ? o.sessions : 0,
+    };
+  } catch (err) {
+    logger.debug(`drain-status parse failed: ${String(err)}`);
+    return null;
+  }
+}
+
+/**
+ * Result of draining a colour:
+ *  - `gone`: the drain signal never landed (old colour already gone / predates
+ *    the endpoint) — there's nothing alive to linger, so teardown is safe.
+ *  - `drained`: the drain was acknowledged. `status` is the FINAL drain status
+ *    (so the caller can decide teardown vs. linger on the session count), or
+ *    `null` when the session count stayed UNKNOWN to the deadline — which the
+ *    caller must treat as "may still have sessions", NOT as zero.
+ */
+type DrainOutcome =
+  | { kind: 'gone' }
+  | { kind: 'drained'; status: DrainStatus | null };
+
+/**
+ * Tell the old colour to stop accepting new work and wait for its in-flight
+ * one-shots to drain. See {@link DrainOutcome} for how the caller reads the
+ * result.
+ */
+async function drainOldColor(
+  pid: string,
+  oldColor: DeploymentColor,
+  timing: { pollMs?: number; timeoutMs?: number } = {},
+): Promise<DrainOutcome> {
+  const pollMs = timing.pollMs ?? DRAIN_POLL_MS;
+  const timeoutMs = timing.timeoutMs ?? DRAIN_TIMEOUT_MS;
+  const container = `${pid}-sandbox-${oldColor}`;
+  logger.step(`Draining sandbox ${oldColor}...`);
+
+  const drain = await docker(
+    'exec',
+    container,
+    'curl',
+    '-fsS',
+    '-X',
+    'POST',
+    'http://localhost:8003/v1/drain',
+  );
+  if (!drain.success) {
+    // Old colour may already be gone / lack the endpoint — nothing to drain.
+    logger.debug(
+      `drain signal to ${container} failed (continuing): ${drain.stderr.trim()}`,
+    );
+    return { kind: 'gone' };
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const status = await readDrainStatus(pid, oldColor);
+    if (status && status.inFlight === 0) return { kind: 'drained', status };
+    if (Date.now() >= deadline) {
+      logger.warn(
+        `sandbox ${oldColor} still draining after ${timeoutMs / 1000}s — proceeding.`,
+      );
+      return { kind: 'drained', status };
+    }
+    await Bun.sleep(pollMs);
+  }
+}
+
+/**
+ * Reclaim a colour's session containers (spawned by `docker run`, not compose,
+ * labelled `tale.color=<color>` + `tale.sandbox-session=1`). Used both by
+ * `teardownColor` and by the next flip's stale-cleanup (the linger reaper of
+ * last resort).
+ */
+async function removeColorSessionContainers(
+  pid: string,
+  color: DeploymentColor,
+): Promise<void> {
+  void pid; // labels carry the colour; the project scope is implicit per host.
+  const ps = await docker(
+    'ps',
+    '-aq',
+    '--filter',
+    `label=tale.color=${color}`,
+    '--filter',
+    'label=tale.sandbox-session=1',
+  );
+  if (ps.success) {
+    for (const id of ps.stdout
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0)) {
+      await removeContainer(id);
+    }
+  }
+}
+
+/** Stop + remove a colour's spawner, egress, and its (now-drained) session containers. */
+async function teardownColor(
+  pid: string,
+  color: DeploymentColor,
+): Promise<void> {
+  logger.step(`Removing sandbox ${color}...`);
+  for (const svc of [`sandbox-${color}`, `sandbox-egress-${color}`]) {
+    const name = `${pid}-${svc}`;
+    await stopContainer(name);
+    await removeContainer(name);
+  }
+  await removeColorSessionContainers(pid, color);
+}
+
+/** First colored deploy: remove the pre-blue-green single-colour containers (no /v1/drain). */
+async function teardownLegacy(pid: string): Promise<void> {
+  for (const name of [`${pid}-sandbox`, `${pid}-sandbox-egress`]) {
+    if (await stopContainer(name)) {
+      await removeContainer(name);
+      logger.info(`Removed legacy single-colour ${name}`);
+    }
+  }
+}
diff --git a/tools/cli/src/lib/actions/restore.test.ts b/tools/cli/src/lib/actions/restore.test.ts
index 99b8c494ef..cab581d2b4 100644
--- a/tools/cli/src/lib/actions/restore.test.ts
+++ b/tools/cli/src/lib/actions/restore.test.ts
@@ -171,7 +171,7 @@ describe('restore', () => {
     // Prints the redeploy-the-matching-version runbook.
     const infoLines = loggerInfoMock.mock.calls.map((call) => String(call[0]));
     expect(
-      infoLines.some((line) => line.includes('tale upgrade --version 0.9.6')),
+      infoLines.some((line) => line.includes('tale update --version 0.9.6')),
     ).toBe(true);
   });
 
diff --git a/tools/cli/src/lib/actions/restore.ts b/tools/cli/src/lib/actions/restore.ts
index ec4c7422dd..a46e500415 100644
--- a/tools/cli/src/lib/actions/restore.ts
+++ b/tools/cli/src/lib/actions/restore.ts
@@ -201,9 +201,9 @@ export async function restore(options: RestoreOptions): Promise<void> {
       logger.info('  tale start');
     } else {
       logger.info(
-        `  tale upgrade --version ${manifest.platformVersion ?? '<version-at-snapshot-time>'}`,
+        `  tale update --version ${manifest.platformVersion ?? '<version-at-snapshot-time>'}`,
       );
-      logger.info('  tale deploy --all');
+      logger.info('  tale deploy --stop');
     }
   });
 }
diff --git a/tools/cli/src/lib/actions/rollback.test.ts b/tools/cli/src/lib/actions/rollback.test.ts
index 49ce653a3e..2f48f0c3a0 100644
--- a/tools/cli/src/lib/actions/rollback.test.ts
+++ b/tools/cli/src/lib/actions/rollback.test.ts
@@ -22,8 +22,15 @@ const stopContainerMock = mock();
 const removeContainerMock = mock();
 const setCurrentColorMock = mock();
 const setPreviousVersionMock = mock();
+const confirmMock = mock();
 const loggerInfoMock = mock();
 const loggerErrorMock = mock();
+const execMock = mock(async () => ({
+  success: true,
+  stdout: '',
+  stderr: '',
+  exitCode: 0,
+}));
 
 mock.module('../state/with-lock', () => ({
   withLock: (_dir: string, _cmd: string, fn: () => Promise<unknown>) => fn(),
@@ -64,6 +71,15 @@ mock.module('../docker/stop-container', () => ({
 mock.module('../docker/remove-container', () => ({
   removeContainer: removeContainerMock,
 }));
+// rollback pre-marks the old platform colour for shutdown via `docker exec`
+// before draining. Stub it deterministically (a sibling suite's exec mock
+// otherwise leaks in process-globally and returns undefined).
+mock.module('../docker/exec', () => ({
+  exec: execMock,
+}));
+mock.module('../../utils/prompt', () => ({
+  confirm: confirmMock,
+}));
 mock.module('../../utils/logger', () => ({
   info: loggerInfoMock,
   error: loggerErrorMock,
@@ -84,10 +100,10 @@ const env: DeploymentEnv = {
 
 function expectRunbookPrinted(): void {
   const infoLines = loggerInfoMock.mock.calls.map((c) => String(c[0]));
-  expect(
-    infoLines.some((line) => line.includes('tale upgrade --version')),
-  ).toBe(true);
-  expect(infoLines.some((line) => line.includes('tale deploy --all'))).toBe(
+  expect(infoLines.some((line) => line.includes('tale update --version'))).toBe(
+    true,
+  );
+  expect(infoLines.some((line) => line.includes('tale deploy --stop'))).toBe(
     true,
   );
 }
@@ -105,8 +121,10 @@ afterEach(() => {
   removeContainerMock.mockReset();
   setCurrentColorMock.mockReset();
   setPreviousVersionMock.mockReset();
+  confirmMock.mockReset();
   loggerInfoMock.mockReset();
   loggerErrorMock.mockReset();
+  execMock.mockClear();
 });
 
 describe('rollback gate', () => {
@@ -116,7 +134,7 @@ describe('rollback gate', () => {
     getContainerVersionMock.mockResolvedValue('0.10.1');
 
     await expect(
-      rollback({ env }, { pullImage: pullImageMock }),
+      rollback({ env, assumeYes: false }, { pullImage: pullImageMock }),
     ).rejects.toThrow('Rollback refused: not a patch-level rollback');
 
     expect(pullImageMock).not.toHaveBeenCalled();
@@ -129,7 +147,7 @@ describe('rollback gate', () => {
     getPreviousVersionMock.mockResolvedValue(null);
 
     await expect(
-      rollback({ env }, { pullImage: pullImageMock }),
+      rollback({ env, assumeYes: false }, { pullImage: pullImageMock }),
     ).rejects.toThrow('No previous version');
 
     expect(pullImageMock).not.toHaveBeenCalled();
@@ -142,7 +160,7 @@ describe('rollback gate', () => {
     getContainerVersionMock.mockResolvedValue(null);
 
     await expect(
-      rollback({ env }, { pullImage: pullImageMock }),
+      rollback({ env, assumeYes: false }, { pullImage: pullImageMock }),
     ).rejects.toThrow('Unknown running version');
 
     expect(pullImageMock).not.toHaveBeenCalled();
@@ -155,14 +173,17 @@ describe('rollback gate', () => {
     getContainerVersionMock.mockResolvedValue('latest');
 
     await expect(
-      rollback({ env }, { pullImage: pullImageMock }),
+      rollback({ env, assumeYes: false }, { pullImage: pullImageMock }),
     ).rejects.toThrow('Rollback refused: cannot compare versions');
 
     expect(pullImageMock).not.toHaveBeenCalled();
     expectRunbookPrinted();
   });
+});
 
-  test('allows a patch-level rollback to the previous version', async () => {
+describe('rollback confirmation', () => {
+  /** Seed the mocks so a patch-level rollback passes the gate and succeeds. */
+  function arrangePatchRollback(): void {
     getCurrentColorMock.mockResolvedValue('blue');
     getPreviousVersionMock.mockResolvedValue('0.9.2');
     getContainerVersionMock.mockResolvedValue('0.9.3');
@@ -178,9 +199,15 @@ describe('rollback gate', () => {
     waitForHealthyMock.mockResolvedValue(true);
     stopContainerMock.mockResolvedValue(true);
     removeContainerMock.mockResolvedValue(true);
+  }
+
+  test('proceeds with a patch-level rollback once the operator confirms', async () => {
+    arrangePatchRollback();
+    confirmMock.mockResolvedValue(true);
 
-    await rollback({ env }, { pullImage: pullImageMock });
+    await rollback({ env, assumeYes: false }, { pullImage: pullImageMock });
 
+    expect(confirmMock).toHaveBeenCalledTimes(1);
     // platform — the only rotatable service
     expect(pullImageMock).toHaveBeenCalledTimes(1);
     expect(pullImageMock).toHaveBeenCalledWith(
@@ -192,4 +219,26 @@ describe('rollback gate', () => {
       '0.9.3',
     );
   });
+
+  test('aborts before pulling anything when the operator declines', async () => {
+    arrangePatchRollback();
+    confirmMock.mockResolvedValue(false);
+
+    await rollback({ env, assumeYes: false }, { pullImage: pullImageMock });
+
+    expect(confirmMock).toHaveBeenCalledTimes(1);
+    expect(pullImageMock).not.toHaveBeenCalled();
+    expect(setCurrentColorMock).not.toHaveBeenCalled();
+    expect(setPreviousVersionMock).not.toHaveBeenCalled();
+  });
+
+  test('skips the prompt and proceeds when --yes is set', async () => {
+    arrangePatchRollback();
+
+    await rollback({ env, assumeYes: true }, { pullImage: pullImageMock });
+
+    expect(confirmMock).not.toHaveBeenCalled();
+    expect(pullImageMock).toHaveBeenCalledTimes(1);
+    expect(setCurrentColorMock).toHaveBeenCalledWith(env.DEPLOY_DIR, 'green');
+  });
 });
diff --git a/tools/cli/src/lib/actions/rollback.ts b/tools/cli/src/lib/actions/rollback.ts
index e77dcff580..3e2e591da5 100644
--- a/tools/cli/src/lib/actions/rollback.ts
+++ b/tools/cli/src/lib/actions/rollback.ts
@@ -2,12 +2,14 @@ import { sameMinor } from '../../utils/compare-versions';
 import { getProjectId, type DeploymentEnv } from '../../utils/load-env';
 import * as logger from '../../utils/logger';
 import { runStepsInParallel } from '../../utils/progress';
+import { confirm } from '../../utils/prompt';
 import { REQUIRED_VOLUMES } from '../compose/generators/constants';
 import { generateColorCompose } from '../compose/generators/generate-color-compose';
 import { ROTATABLE_SERVICES } from '../compose/types';
 import { dockerCompose } from '../docker/docker-compose';
 import { ensureNetwork } from '../docker/ensure-network';
 import { ensureVolumes } from '../docker/ensure-volumes';
+import { exec } from '../docker/exec';
 import { getContainerVersion } from '../docker/get-container-version';
 import { pullImage } from '../docker/pull-image';
 import { removeContainer } from '../docker/remove-container';
@@ -22,6 +24,8 @@ import { withLock } from '../state/with-lock';
 
 interface RollbackOptions {
   env: DeploymentEnv;
+  /** Skip the confirmation prompt (the `-y/--yes` flag / non-interactive use). */
+  assumeYes: boolean;
 }
 
 /**
@@ -54,10 +58,11 @@ function printSnapshotRestoreRunbook(): void {
   logger.info('     (interactive, snapshot-backed):');
   logger.info('       tale migrate down --to <version> --step');
   logger.info(
-    '  2. Re-deploy the version that matches the migrated-down data:',
+    '  2. Move the CLI to the version that matches the migrated-down data,',
   );
-  logger.info('       tale upgrade --version <version>');
-  logger.info('       tale deploy --all');
+  logger.info('     then roll the containers to match:');
+  logger.info('       tale update --version <version>');
+  logger.info('       tale deploy --stop');
   logger.info('  If a migration is not reversible, restore the data-volume');
   logger.info('  backup taken before the upgrade instead');
   logger.info('  (see docs/self-hosted/operate/backups-and-restore.md).');
@@ -67,7 +72,7 @@ export async function rollback(
   options: RollbackOptions,
   deps: RollbackDeps = {},
 ): Promise<void> {
-  const { env } = options;
+  const { env, assumeYes } = options;
   const pull = deps.pullImage ?? pullImage;
 
   await withLock(env.DEPLOY_DIR, 'rollback', async () => {
@@ -133,6 +138,28 @@ export async function rollback(
       `Rolling back to: ${rollbackColor} (version ${rollbackVersion})`,
     );
 
+    // Destructive, hard-to-undo: this redeploys the previous patch on the idle
+    // colour, flips traffic, then drains and tears down the running containers.
+    // Warn what's about to happen and require explicit consent before pulling a
+    // single image. `--yes` (assumeYes) skips the prompt for non-interactive use;
+    // we gate on it rather than letting `confirm` resolve, because `confirm`
+    // returns its `default` (false here) under --yes, which would cancel.
+    logger.warn(
+      `About to roll the live platform back from ${currentVersion} to ${rollbackVersion}.`,
+    );
+    logger.warn(
+      'This redeploys the previous patch on the idle colour, flips traffic, and ' +
+        'tears down the current containers. It rolls back the binary only — ' +
+        'data is not migrated down.',
+    );
+    if (!assumeYes) {
+      const ok = await confirm({ message: 'Roll back now?', default: false });
+      if (!ok) {
+        logger.info('Rollback cancelled');
+        return;
+      }
+    }
+
     const serviceConfig = {
       version: rollbackVersion,
       registry: env.GHCR_REGISTRY,
@@ -212,6 +239,26 @@ export async function rollback(
     await setPreviousVersion(env.DEPLOY_DIR, currentVersion);
     logger.info(`Version history updated: previous=${currentVersion}`);
 
+    // Pre-mark the old platform colour as shutting down BEFORE the drain sleep
+    // so its /api/health 503s and the proxy stops routing new requests to it
+    // while in-flight ones finish (mirrors deploy.ts). Best-effort + platform-
+    // specific; a failure just falls back to the graceful stop below.
+    for (const service of ROTATABLE_SERVICES) {
+      if (service !== 'platform') continue;
+      const oldName = `${getProjectId()}-${service}-${currentColor}`;
+      const marked = await exec('docker', [
+        'exec',
+        oldName,
+        'touch',
+        '/tmp/platform-shutting-down',
+      ]);
+      if (!marked.success) {
+        logger.debug(
+          `Could not pre-mark ${oldName} for shutdown (continuing): ${marked.stderr.trim()}`,
+        );
+      }
+    }
+
     // Drain current color
     logger.step(`Draining ${currentColor} services (${env.DRAIN_TIMEOUT}s)...`);
     await Bun.sleep(env.DRAIN_TIMEOUT * 1000);
diff --git a/tools/cli/src/lib/actions/run-deploy.ts b/tools/cli/src/lib/actions/run-deploy.ts
new file mode 100644
index 0000000000..e8f6bc8f71
--- /dev/null
+++ b/tools/cli/src/lib/actions/run-deploy.ts
@@ -0,0 +1,152 @@
+import pkg from '../../../package.json';
+import { preconditionError, usageError } from '../../utils/fail';
+import { loadEnv } from '../../utils/load-env';
+import * as logger from '../../utils/logger';
+import {
+  type ServiceName,
+  ALL_SERVICES,
+  isValidService,
+} from '../compose/types';
+import { ensureEnv, ensureProductionDomain } from '../config/ensure-env';
+import { ensureDocker } from '../docker/ensure-docker';
+import { requireProject } from '../project/find-project';
+import { resolveOrAssignProjectContext } from '../project/project-context';
+import { isDevBuild } from '../version/self-update';
+import { deploy } from './deploy';
+import { runDeployPreflight } from './deploy-preflight';
+
+/**
+ * Options for {@link runDeploy} — the flag surface of `tale deploy`, also
+ * reused by `tale update`'s instance phase. Mirrors the command's CLI options
+ * one-to-one.
+ */
+interface RunDeployOptions {
+  /** Also update the stop-gated tier (db, proxy) even while running. */
+  stop?: boolean;
+  services?: string;
+  dryRun?: boolean;
+  host?: string;
+  override?: boolean;
+  overrideAll?: boolean;
+  quiet?: boolean;
+  yes?: boolean;
+  skipBackup?: boolean;
+}
+
+/**
+ * Deploy the current CLI version to the environment: Docker/env preflight,
+ * version resolution, then {@link deploy}.
+ *
+ * The deployed version is always the CLI's own version. Because the
+ * version-alignment hook forces the CLI binary to match the workspace's
+ * recorded `cliVersion` before any command runs, a bare `tale deploy` can only
+ * ever (re)deploy that recorded version — it never needs to write `cliVersion`
+ * itself. Moving to a new version is `tale update`'s job.
+ */
+export async function runDeploy(options: RunDeployOptions): Promise<void> {
+  // `--override` and `--override-all` are semantically incompatible: host push
+  // runs first, then the catalog factory reseed clobbers whatever --override
+  // just wrote. Reject the combination so operators don't reason about a
+  // silently-discarded flag.
+  if (options.override && options.overrideAll) {
+    throw usageError(
+      '--override and --override-all cannot be combined: ' +
+        '--override-all factory-reseeds from the builtin catalog and ' +
+        'would clobber whatever --override just pushed. ' +
+        'Pick one: --override (push host workspace to container) ' +
+        'OR --override-all (factory-reseed all orgs server-side).',
+    );
+  }
+
+  const projectDir = requireProject();
+  await resolveOrAssignProjectContext(projectDir);
+
+  // Zero-prerequisite: make sure Docker is usable before anything else.
+  const docker = await ensureDocker({ assumeYes: options.yes });
+  if (docker.status === 'refused' || docker.status === 'failed') {
+    throw preconditionError(docker.detail);
+  }
+
+  const { success: envSetupSuccess, regeneratedAutoSecrets } = await ensureEnv({
+    deployDir: projectDir,
+  });
+  if (!envSetupSuccess) {
+    throw preconditionError(
+      `Environment setup failed. Cannot deploy without ${projectDir}/.env.`,
+    );
+  }
+  // If ensureEnv had to mint missing auto-gen secrets headlessly (typical: a
+  // new `SANDBOX_TOKEN` for an existing deployment), force-recreate the running
+  // services so their in-memory env refreshes to the new value rather than
+  // keeping the stale null. Also force-recreate on --override-all so the reseed
+  // action runs against the new binary, not a stale container the
+  // image/config-unchanged path would have left running.
+  const forceRecreate =
+    (regeneratedAutoSecrets !== undefined &&
+      regeneratedAutoSecrets.length > 0) ||
+    (options.overrideAll ?? false);
+
+  // `tale init` leaves a local default (localhost + self-signed). Choose the
+  // production domain + TLS here: prompts interactively, honors --host, and is
+  // a no-op in CI when HOST is already a public domain.
+  await ensureProductionDomain(projectDir, { host: options.host });
+
+  const env = loadEnv(projectDir);
+
+  // Catch fixable problems (daemon down, letsencrypt misconfig) before mutating
+  // any container. Throws on a real deploy; warns on --dry-run.
+  await runDeployPreflight({
+    dryRun: options.dryRun ?? false,
+    env: process.env,
+  });
+
+  const version = isDevBuild() ? 'latest' : pkg.version;
+  if (version === 'latest') {
+    logger.info(
+      'Dev build detected — deploying `latest` images. Released binaries deploy their pinned version.',
+    );
+  }
+
+  let services: ServiceName[] | undefined;
+  if (options.services) {
+    const serviceList = options.services.split(',').map((s) => s.trim());
+    const invalid = serviceList.filter((s) => !isValidService(s));
+    if (invalid.length > 0) {
+      throw usageError(`Invalid service(s): ${invalid.join(', ')}`, [
+        `Valid services: ${ALL_SERVICES.join(', ')}`,
+      ]);
+    }
+    // The sandbox tier rolls only through the blue-green flip (a full deploy),
+    // never an in-place `--services` update — bringing up the legacy
+    // single-colour container would collide with the colour-suffixed ones.
+    const sandboxIsh = serviceList.filter(
+      (s) => s === 'sandbox' || s === 'sandbox-egress',
+    );
+    if (sandboxIsh.length > 0) {
+      throw usageError(
+        `${sandboxIsh.join(', ')} can't be deployed with --services — the ` +
+          'sandbox tier rolls via the blue-green flip.',
+        ['Run a full `tale deploy` (no --services) to roll the sandbox tier.'],
+      );
+    }
+    services = serviceList.filter(isValidService);
+  }
+
+  const hostAlias = options.host ?? process.env.HOST ?? 'tale.local';
+  await deploy({
+    version,
+    // --override-all implies --stop so the stop-gated tier rolls and the
+    // forceRecreate below restarts services for the reseed entrypoint.
+    stop: (options.stop || options.overrideAll) ?? false,
+    env,
+    hostAlias,
+    dryRun: options.dryRun ?? false,
+    services,
+    override: options.override,
+    overrideAll: options.overrideAll,
+    quiet: options.quiet,
+    assumeYes: options.yes,
+    forceRecreate,
+    skipBackup: options.skipBackup,
+  });
+}
diff --git a/tools/cli/src/lib/actions/run-update.test.ts b/tools/cli/src/lib/actions/run-update.test.ts
new file mode 100644
index 0000000000..3bc2397f6e
--- /dev/null
+++ b/tools/cli/src/lib/actions/run-update.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, mock, test } from 'bun:test';
+
+import type { InstallHandle, ResolvedRelease } from '../version/self-update';
+import { type RunUpdateDeps, runUpdate } from './run-update';
+
+const HANDLE: InstallHandle = {
+  installPath: '/usr/local/bin/tale',
+  backupPath: '/usr/local/bin/tale.bak',
+};
+
+function resolved(version: string): ResolvedRelease {
+  return {
+    release: { tag: `v${version}`, version, assetNames: ['tale_macos'] },
+    skipped: [],
+  };
+}
+
+/** Fully-mocked deps; defaults describe a successful 0.8.0 → 0.9.0 update. */
+function makeDeps(overrides: Partial<RunUpdateDeps> = {}): RunUpdateDeps {
+  return {
+    currentVersion: '0.8.0',
+    isDevBuild: mock(() => false),
+    requireProject: mock(() => '/project'),
+    readWorkspaceVersion: mock(async () => '0.8.0'),
+    writeWorkspaceVersion: mock(async () => {}),
+    resolveRelease: mock(async () => resolved('0.9.0')),
+    installBinary: mock(async () => HANDLE),
+    commitInstall: mock(async () => {}),
+    rollbackInstall: mock(async () => {}),
+    spawnFileSync: mock((_args: string[]) => 0),
+    syncProjectFiles: mock(async () => {}),
+    ...overrides,
+  };
+}
+
+describe('runUpdate', () => {
+  test('happy path: installs target, syncs files, commits backup', async () => {
+    const deps = makeDeps();
+    await runUpdate({}, deps);
+
+    expect(deps.installBinary).toHaveBeenCalledTimes(1);
+    expect(deps.spawnFileSync).toHaveBeenCalledTimes(1);
+    expect(deps.commitInstall).toHaveBeenCalledWith(HANDLE);
+    expect(deps.rollbackInstall).not.toHaveBeenCalled();
+  });
+
+  test('does not deploy — only the file-sync child is spawned', async () => {
+    const spawnFileSync = mock((_args: string[]) => 0);
+    const deps = makeDeps({ spawnFileSync });
+    await runUpdate({ force: true }, deps);
+
+    const argv = spawnFileSync.mock.calls[0][0];
+    expect(argv).toEqual(['update', '--internal-instance', '--force']);
+  });
+
+  test('file sync fails: rolls the CLI back and resets the workspace version', async () => {
+    const deps = makeDeps({ spawnFileSync: mock((_args: string[]) => 1) });
+
+    await expect(runUpdate({}, deps)).rejects.toThrow('rolled back to v0.8.0');
+
+    expect(deps.rollbackInstall).toHaveBeenCalledWith(HANDLE);
+    expect(deps.writeWorkspaceVersion).toHaveBeenCalledWith(
+      '/project',
+      '0.8.0',
+    );
+    expect(deps.commitInstall).not.toHaveBeenCalled();
+  });
+
+  test('already on target: syncs files in-process, no binary swap', async () => {
+    const deps = makeDeps({
+      currentVersion: '0.9.0',
+      readWorkspaceVersion: mock(async () => '0.9.0'),
+      resolveRelease: mock(async () => resolved('0.9.0')),
+    });
+    await runUpdate({}, deps);
+
+    expect(deps.installBinary).not.toHaveBeenCalled();
+    expect(deps.spawnFileSync).not.toHaveBeenCalled();
+    expect(deps.syncProjectFiles).toHaveBeenCalledTimes(1);
+  });
+
+  test('internal-instance continuation: only runs the file-sync phase', async () => {
+    const deps = makeDeps();
+    await runUpdate({ internalInstance: true }, deps);
+
+    expect(deps.syncProjectFiles).toHaveBeenCalledTimes(1);
+    expect(deps.requireProject).not.toHaveBeenCalled();
+    expect(deps.resolveRelease).not.toHaveBeenCalled();
+    expect(deps.installBinary).not.toHaveBeenCalled();
+  });
+
+  test('pinned version: targets that release exactly', async () => {
+    const resolveRelease = mock(async () => resolved('0.7.0'));
+    const deps = makeDeps({ resolveRelease });
+    await runUpdate({ version: '0.7.0' }, deps);
+
+    expect(resolveRelease).toHaveBeenCalledWith({ version: '0.7.0' });
+    expect(deps.installBinary).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/tools/cli/src/lib/actions/run-update.ts b/tools/cli/src/lib/actions/run-update.ts
new file mode 100644
index 0000000000..c140283944
--- /dev/null
+++ b/tools/cli/src/lib/actions/run-update.ts
@@ -0,0 +1,219 @@
+import { join } from 'node:path';
+
+import pkg from '../../../package.json';
+import { compareVersions } from '../../utils/compare-versions';
+import * as logger from '../../utils/logger';
+import { requireProject } from '../project/find-project';
+import { readProject } from '../project/read-project';
+import { writeProject } from '../project/write-project';
+import { ALIGN_GUARD_ENV } from '../version/align';
+import {
+  type InstallHandle,
+  type ResolvedRelease,
+  commitInstall,
+  installBinary,
+  isDevBuild,
+  resolveRelease,
+  rollbackInstall,
+} from '../version/self-update';
+import { update } from './update';
+
+/**
+ * Options for `tale update` — move the CLI and the on-disk project files to a
+ * new version. Rolling the running containers is a separate step (`tale
+ * deploy`); `tale update` does not deploy.
+ */
+export interface RunUpdateOptions {
+  /** Target version (e.g. "0.9.0"); defaults to the latest release. */
+  version?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  /**
+   * Hidden continuation: run ONLY the file-sync phase under the freshly-
+   * installed target binary (so it syncs the new version's templates). Set by
+   * the parent invocation when it re-spawns itself after the CLI self-update.
+   */
+  internalInstance?: boolean;
+}
+
+/**
+ * Injectable seams so the orchestration (CLI bump → file sync → rollback) is
+ * unit-testable without real downloads or subprocesses. Production passes the
+ * defaults below.
+ */
+export interface RunUpdateDeps {
+  currentVersion: string;
+  isDevBuild: (version?: string) => boolean;
+  requireProject: () => string;
+  readWorkspaceVersion: (dir: string) => Promise<string>;
+  writeWorkspaceVersion: (dir: string, version: string) => Promise<void>;
+  resolveRelease: (opts: { version?: string }) => Promise<ResolvedRelease>;
+  installBinary: (
+    release: ResolvedRelease['release'],
+  ) => Promise<InstallHandle>;
+  commitInstall: (handle: InstallHandle) => Promise<void>;
+  rollbackInstall: (handle: InstallHandle) => Promise<void>;
+  /** Spawn `tale update --internal-instance ...` under the new binary; returns the exit code. */
+  spawnFileSync: (childArgs: string[]) => number;
+  /** Run the file-sync phase in-process (no binary change). */
+  syncProjectFiles: (opts: RunUpdateOptions) => Promise<void>;
+}
+
+const defaultDeps: RunUpdateDeps = {
+  currentVersion: pkg.version,
+  isDevBuild,
+  requireProject,
+  readWorkspaceVersion: async (dir) => (await readProject(dir)).cliVersion,
+  writeWorkspaceVersion: async (dir, version) => {
+    const project = await readProject(dir);
+    if (project.cliVersion !== version) {
+      await writeProject(join(dir, 'tale.json'), {
+        ...project,
+        cliVersion: version,
+      });
+    }
+  },
+  resolveRelease,
+  installBinary,
+  commitInstall,
+  rollbackInstall,
+  spawnFileSync: (childArgs) => {
+    const result = Bun.spawnSync([process.execPath, ...childArgs], {
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+      env: { ...process.env, [ALIGN_GUARD_ENV]: '1' },
+    });
+    // A signal-killed child reports `exitCode === null`; treat that as a
+    // failure (1) rather than masking it as success (0) — the caller rolls the
+    // binary back on any non-zero file-sync result.
+    return result.exitCode ?? 1;
+  },
+  syncProjectFiles,
+};
+
+/** Sync the project files to the running binary's embedded templates. */
+async function syncProjectFiles(opts: RunUpdateOptions): Promise<void> {
+  await update({
+    force: opts.force,
+    dryRun: opts.dryRun,
+    skipHeader: true,
+  });
+}
+
+/** Build the `--internal-instance` child argv from the user's options. */
+function fileSyncChildArgs(opts: RunUpdateOptions): string[] {
+  const args = ['update', '--internal-instance'];
+  if (opts.force) args.push('--force');
+  return args;
+}
+
+/**
+ * `tale update`: bring the CLI and the on-disk project files to a new version.
+ *
+ * Updates the CLI binary first, then syncs the project files to the new
+ * version's templates (which stamps `tale.json`'s `cliVersion`). If the file
+ * sync fails, the CLI is rolled back to the workspace's previous version so
+ * the binary and `cliVersion` stay in lockstep (and the next command's
+ * automatic alignment is a no-op). Rolling the running containers is a
+ * separate step — run `tale deploy` afterwards.
+ */
+export async function runUpdate(
+  opts: RunUpdateOptions,
+  deps: RunUpdateDeps = defaultDeps,
+): Promise<void> {
+  // Continuation under the new binary: just do the file-sync phase.
+  if (opts.internalInstance) {
+    await deps.syncProjectFiles(opts);
+    return;
+  }
+
+  const projectDir = deps.requireProject();
+  const prev = await deps.readWorkspaceVersion(projectDir);
+
+  const { release, skipped } = await deps.resolveRelease({
+    version: opts.version,
+  });
+  const target = release.version;
+  const comparison = compareVersions(target, deps.currentVersion);
+  const isDev = deps.isDevBuild();
+
+  logger.header(opts.dryRun ? '[DRY-RUN] Updating Tale' : 'Updating Tale');
+  logger.info(`CLI version:       ${deps.currentVersion}`);
+  logger.info(`Workspace version: ${prev}`);
+  logger.info(`Target version:    ${target}`);
+
+  if (!opts.version && skipped.length > 0) {
+    logger.warn(
+      `Skipping ${skipped.map((t) => t.replace(/^v/, '')).join(', ')} — ` +
+        `binary not yet uploaded. Re-run 'tale update' later to pick them up.`,
+    );
+  }
+  if (opts.version && !isDev && comparison < 0) {
+    logger.warn(
+      `Downgrading from ${deps.currentVersion} to ${target}. Data migrations ` +
+        `from the newer version persist — reverse them FIRST with ` +
+        `\`tale migrate down --to ${target}\` (check \`tale migrate status\`).`,
+    );
+  }
+
+  if (opts.dryRun) {
+    logger.blank();
+    logger.info(
+      `[DRY-RUN] Would update the CLI to v${target}, then sync project files. ` +
+        `Run \`tale deploy\` afterwards to roll the containers.`,
+    );
+    logger.info(
+      'Project-file preview below is based on the current templates; actual ' +
+        'changes may differ after the CLI is updated.',
+    );
+    logger.blank();
+    await update({ force: opts.force, dryRun: true, skipHeader: true });
+    return;
+  }
+
+  // Already on the target binary → no replace/rollback needed; sync in-process.
+  if (comparison === 0 && !isDev && !opts.force) {
+    logger.blank();
+    await deps.syncProjectFiles(opts);
+    logger.success(
+      `Tale CLI is up to date (v${target}); project files synced. ` +
+        `Run \`tale deploy\` to roll the instance.`,
+    );
+    return;
+  }
+
+  // Phase 1: install the target binary, keeping a backup for rollback.
+  logger.step(`Updating CLI ${deps.currentVersion} → ${target}...`);
+  const handle = await deps.installBinary(release);
+
+  // Phase 2: sync project files under the new binary, in a child process so
+  // this (old-binary) parent stays alive to orchestrate a rollback on failure.
+  logger.step('Syncing project files...');
+  const exitCode = deps.spawnFileSync(fileSyncChildArgs(opts));
+
+  if (exitCode !== 0) {
+    logger.blank();
+    logger.warn(`File sync failed — rolling the CLI back to v${prev}.`);
+    await deps.rollbackInstall(handle);
+    // The file sync stamps cliVersion only on success, so a failed run leaves
+    // it at `prev`; reset defensively to keep binary ↔ cliVersion in lockstep.
+    try {
+      await deps.writeWorkspaceVersion(projectDir, prev);
+    } catch (err) {
+      // tale.json unreadable post-failure — nothing more to reconcile here.
+      logger.debug(`could not reset cliVersion after rollback: ${String(err)}`);
+    }
+    throw new Error(
+      `Update to v${target} failed during file sync; CLI rolled back to ` +
+        `v${prev}. See the output above for the cause.`,
+    );
+  }
+
+  await deps.commitInstall(handle);
+  logger.blank();
+  logger.success(
+    `Tale CLI updated to v${target} and project files synced. ` +
+      `Run \`tale deploy\` to roll the instance to v${target}.`,
+  );
+}
diff --git a/tools/cli/src/lib/actions/uninstall.test.ts b/tools/cli/src/lib/actions/uninstall.test.ts
new file mode 100644
index 0000000000..333c636900
--- /dev/null
+++ b/tools/cli/src/lib/actions/uninstall.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, mock, test } from 'bun:test';
+
+import { type UninstallDeps, uninstall } from './uninstall';
+
+const BINARY = '/usr/local/bin/tale';
+const DAEMON = '/home/user/.tale-daemon';
+const PROJECT = '/home/user/acme';
+
+/** Build a fully-mocked UninstallDeps; every field is a bun mock for assertions. */
+function makeDeps(overrides: Partial<UninstallDeps> = {}): UninstallDeps {
+  return {
+    isDevBuild: mock(() => false),
+    getBinaryPath: mock(() => BINARY),
+    removeBinary: mock(async () => {}),
+    removeBinaryBackups: mock(async () => {}),
+    removeDir: mock(async () => {}),
+    findProject: mock(() => PROJECT),
+    getDaemonHome: mock(() => DAEMON),
+    tearDownDocker: mock(async () => {}),
+    confirm: mock(async () => true),
+    isInteractive: mock(() => true),
+    assumeYes: mock(() => false),
+    ...overrides,
+  };
+}
+
+describe('uninstall', () => {
+  test('dev build: refuses and removes nothing', async () => {
+    const deps = makeDeps({ isDevBuild: mock(() => true) });
+    await expect(uninstall({}, deps)).rejects.toThrow(/dev build/);
+    expect(deps.removeBinary).not.toHaveBeenCalled();
+    expect(deps.removeDir).not.toHaveBeenCalled();
+  });
+
+  test('--force: removes only the binary + backups, no extras', async () => {
+    const deps = makeDeps();
+    await uninstall({ force: true }, deps);
+
+    expect(deps.removeBinaryBackups).toHaveBeenCalledWith(BINARY);
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+    // --force skips both the primary prompt and the optional offers.
+    expect(deps.confirm).not.toHaveBeenCalled();
+    expect(deps.tearDownDocker).not.toHaveBeenCalled();
+    expect(deps.removeDir).not.toHaveBeenCalled();
+  });
+
+  test('--purge: removes binary, daemon config, and the project', async () => {
+    const deps = makeDeps({ assumeYes: mock(() => true) }); // skip primary prompt
+    await uninstall({ purge: true }, deps);
+
+    expect(deps.tearDownDocker).toHaveBeenCalledWith(PROJECT);
+    expect(deps.removeDir).toHaveBeenCalledWith(PROJECT);
+    expect(deps.removeDir).toHaveBeenCalledWith(DAEMON);
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+    // --purge selects extras non-interactively — no prompting.
+    expect(deps.confirm).not.toHaveBeenCalled();
+  });
+
+  test('--purge with no project: removes daemon config only, no teardown', async () => {
+    const deps = makeDeps({
+      assumeYes: mock(() => true),
+      findProject: mock(() => null),
+    });
+    await uninstall({ purge: true }, deps);
+
+    expect(deps.tearDownDocker).not.toHaveBeenCalled();
+    expect(deps.removeDir).toHaveBeenCalledTimes(1);
+    expect(deps.removeDir).toHaveBeenCalledWith(DAEMON);
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+  });
+
+  test('declining the primary prompt cancels — nothing removed', async () => {
+    const deps = makeDeps({ confirm: mock(async () => false) });
+    await uninstall({}, deps);
+
+    expect(deps.removeBinary).not.toHaveBeenCalled();
+    expect(deps.removeDir).not.toHaveBeenCalled();
+    expect(deps.tearDownDocker).not.toHaveBeenCalled();
+  });
+
+  test('non-interactive without --purge/--force: only the binary is offered', async () => {
+    // assumeYes skips the primary prompt; not a TTY → optional offers default
+    // to "no", so CI never surprise-deletes data.
+    const deps = makeDeps({
+      assumeYes: mock(() => true),
+      isInteractive: mock(() => false),
+    });
+    await uninstall({}, deps);
+
+    expect(deps.confirm).not.toHaveBeenCalled();
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+    expect(deps.tearDownDocker).not.toHaveBeenCalled();
+    expect(deps.removeDir).not.toHaveBeenCalled();
+  });
+
+  test('--dry-run: removes nothing and never prompts', async () => {
+    const deps = makeDeps();
+    await uninstall({ dryRun: true, purge: true }, deps);
+
+    expect(deps.confirm).not.toHaveBeenCalled();
+    expect(deps.removeBinary).not.toHaveBeenCalled();
+    expect(deps.removeBinaryBackups).not.toHaveBeenCalled();
+    expect(deps.removeDir).not.toHaveBeenCalled();
+    expect(deps.tearDownDocker).not.toHaveBeenCalled();
+  });
+
+  test('Docker teardown failure still deletes the project dir and the binary', async () => {
+    const deps = makeDeps({
+      assumeYes: mock(() => true),
+      tearDownDocker: mock(async () => {
+        throw new Error('docker daemon not running');
+      }),
+    });
+    await uninstall({ purge: true }, deps);
+
+    expect(deps.removeDir).toHaveBeenCalledWith(PROJECT);
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+  });
+
+  test('interactive: offers extras via prompt and honors per-offer answers', async () => {
+    // Accept the primary + project teardown, decline the daemon-config removal.
+    const confirm = mock(
+      async (message: string) => !message.includes('per-user'),
+    );
+    const deps = makeDeps({ confirm });
+    await uninstall({}, deps);
+
+    expect(deps.tearDownDocker).toHaveBeenCalledWith(PROJECT);
+    expect(deps.removeDir).toHaveBeenCalledWith(PROJECT);
+    expect(deps.removeDir).not.toHaveBeenCalledWith(DAEMON);
+    expect(deps.removeBinary).toHaveBeenCalledWith(BINARY);
+  });
+});
diff --git a/tools/cli/src/lib/actions/uninstall.ts b/tools/cli/src/lib/actions/uninstall.ts
new file mode 100644
index 0000000000..f7c63a0a59
--- /dev/null
+++ b/tools/cli/src/lib/actions/uninstall.ts
@@ -0,0 +1,183 @@
+import { rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { configPath } from '../../daemon/config';
+import { preconditionError } from '../../utils/fail';
+import { loadEnv } from '../../utils/load-env';
+import * as logger from '../../utils/logger';
+import { getOutputMode } from '../../utils/output-mode';
+import { confirm as promptConfirm, isInteractive } from '../../utils/prompt';
+import { findProject } from '../project/find-project';
+import { resolveProjectContext } from '../project/project-context';
+import {
+  getBinaryPath,
+  isDevBuild,
+  removeBinary,
+  removeBinaryBackups,
+} from '../version/self-update';
+import { reset } from './reset';
+
+/**
+ * `tale uninstall` — the inverse of the install script. It always removes the
+ * CLI binary, and *offers* (interactively, or non-interactively via `--purge`)
+ * to also remove the per-user config (`~/.tale-daemon`) and tear down a
+ * detected project's Docker resources + files.
+ *
+ * Destructive extras never run silently: they require an interactive "yes" or
+ * the explicit `--purge` flag, so a CI / piped run only ever removes the binary.
+ * The binary is removed LAST so a failure mid-run leaves a working CLI to retry.
+ */
+interface UninstallOptions {
+  /** Skip the binary-removal confirmation (binary only — does not select extras). */
+  force?: boolean;
+  /** Non-interactively select all destructive extras (daemon config + project). */
+  purge?: boolean;
+  /** Preview what would be removed without touching anything. */
+  dryRun?: boolean;
+}
+
+/**
+ * Injectable seams (binary I/O, file removal, Docker teardown, prompting) so the
+ * decision logic is unit-testable without deleting the real binary. Production
+ * passes the defaults below.
+ */
+export interface UninstallDeps {
+  isDevBuild: () => boolean;
+  getBinaryPath: () => string;
+  removeBinary: (path: string) => Promise<void>;
+  removeBinaryBackups: (path: string) => Promise<void>;
+  removeDir: (path: string) => Promise<void>;
+  findProject: () => string | null;
+  getDaemonHome: () => string;
+  tearDownDocker: (projectDir: string) => Promise<void>;
+  confirm: (message: string) => Promise<boolean>;
+  isInteractive: () => boolean;
+  assumeYes: () => boolean;
+}
+
+const defaultDeps: UninstallDeps = {
+  isDevBuild,
+  getBinaryPath,
+  removeBinary,
+  removeBinaryBackups,
+  removeDir: (path) => rm(path, { recursive: true, force: true }),
+  findProject: () => findProject(),
+  // The daemon config lives at `<home>/config.json`; its parent is the home dir.
+  getDaemonHome: () => dirname(configPath()),
+  tearDownDocker: async (projectDir) => {
+    await resolveProjectContext(projectDir);
+    const env = loadEnv(projectDir);
+    // `force: true` — we already consented at the uninstall level, so skip
+    // reset's own inner confirmation. `includeStateful` removes the db/proxy
+    // containers and prunes the project's volumes too.
+    await reset({ env, force: true, includeStateful: true, dryRun: false });
+  },
+  confirm: (message) => promptConfirm({ message, default: false }),
+  isInteractive,
+  assumeYes: () => getOutputMode().assumeYes,
+};
+
+export async function uninstall(
+  options: UninstallOptions,
+  deps: UninstallDeps = defaultDeps,
+): Promise<void> {
+  const { force = false, purge = false, dryRun = false } = options;
+
+  // A dev build runs under the `bun` runtime, so `process.execPath` is bun —
+  // not a tale release binary. Removing it would delete the user's bun install.
+  if (deps.isDevBuild()) {
+    throw preconditionError(
+      'tale uninstall removes an installed release binary, but you are running a dev build (bun). Nothing to uninstall.',
+      'Run the compiled binary, or remove your dev checkout manually.',
+    );
+  }
+
+  const binaryPath = deps.getBinaryPath();
+  const prefix = dryRun ? '[DRY-RUN] ' : '';
+  logger.header(`${prefix}Uninstalling Tale CLI`);
+  logger.info(`Binary: ${binaryPath}`);
+
+  // Dry-run: report and exit without prompting or touching anything.
+  if (dryRun) {
+    logger.info(`${prefix}Would remove the binary and any update backups`);
+    if (purge) {
+      logger.info(`${prefix}Would remove ${deps.getDaemonHome()}`);
+      const project = deps.findProject();
+      if (project) {
+        logger.info(
+          `${prefix}Would tear down Docker resources and delete ${project}`,
+        );
+      }
+    } else {
+      logger.info(
+        `${prefix}Re-run with --purge to also remove ~/.tale-daemon and a project's Docker resources + files`,
+      );
+    }
+    logger.success(`${prefix}Dry-run complete`);
+    return;
+  }
+
+  // Primary confirmation. `--force` or the global `--yes` proceeds without it.
+  if (!force && !deps.assumeYes()) {
+    const confirmed = await deps.confirm(
+      `Remove the Tale CLI binary at ${binaryPath}?`,
+    );
+    if (!confirmed) {
+      logger.info('Uninstall cancelled');
+      return;
+    }
+  }
+
+  // Resolve the opt-in destructive extras. `--purge` selects all of them
+  // non-interactively; otherwise we only offer them on a real terminal so a
+  // CI / piped run never surprise-deletes data.
+  const offerExtra = async (message: string): Promise<boolean> => {
+    if (purge) return true;
+    if (force) return false; // --force = binary only, no further prompts
+    if (!deps.isInteractive()) return false;
+    return deps.confirm(message);
+  };
+
+  const project = deps.findProject();
+  const removeProject =
+    project !== null &&
+    (await offerExtra(
+      `Also tear down Docker resources and delete the project at ${project}? This is irreversible.`,
+    ));
+  const removeDaemon = await offerExtra(
+    `Also remove the per-user config at ${deps.getDaemonHome()}?`,
+  );
+
+  // Run the extras BEFORE deleting the binary, so a failure here leaves a
+  // working CLI to retry with.
+  if (removeProject && project) {
+    try {
+      await deps.tearDownDocker(project);
+    } catch (err) {
+      logger.warn(
+        `Skipped Docker teardown for ${project}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    await deps.removeDir(project);
+    logger.success(`Removed project directory ${project}`);
+  }
+
+  if (removeDaemon) {
+    const daemonHome = deps.getDaemonHome();
+    await deps.removeDir(daemonHome);
+    logger.success(`Removed ${daemonHome}`);
+  }
+
+  // Binary last — clean up leftover update backups, then remove the binary.
+  await deps.removeBinaryBackups(binaryPath);
+  await deps.removeBinary(binaryPath);
+  logger.success(`Removed ${binaryPath}`);
+
+  logger.success('Tale CLI uninstalled');
+  if (project && !removeProject) {
+    logger.info(
+      `Project at ${project} and its Docker resources were left intact. ` +
+        'Run `tale reset --all` there to remove them.',
+    );
+  }
+}
diff --git a/tools/cli/src/lib/compose/generators/generate-color-compose.test.ts b/tools/cli/src/lib/compose/generators/generate-color-compose.test.ts
index e9c0cc2e49..9163fa31b9 100644
--- a/tools/cli/src/lib/compose/generators/generate-color-compose.test.ts
+++ b/tools/cli/src/lib/compose/generators/generate-color-compose.test.ts
@@ -33,3 +33,26 @@ describe('generateColorCompose ↔ controller restart contract', () => {
     });
   }
 });
+
+describe('generateColorCompose ↔ graceful-shutdown budget', () => {
+  // The platform entrypoint's SIGTERM trap drains for SHUTDOWN_DRAIN_SECONDS
+  // (6) + SHUTDOWN_GRACE_SECONDS (5) + up to SHUTDOWN_TIMEOUT_SECONDS (30) ≈
+  // 41s. `docker stop` (no -t) honors the container StopTimeout set by
+  // stop_grace_period, so this MUST cover that budget — otherwise Docker's
+  // default 10s SIGKILLs the old colour mid-drain on a flip, cutting in-flight
+  // HTTP/SSE chat streams. Pin a floor so a SHUTDOWN_* default bump trips here.
+  const MIN_GRACE_SECONDS = 41;
+  for (const color of ['blue', 'green'] as const) {
+    test(`platform-${color} sets stop_grace_period >= ${MIN_GRACE_SECONDS}s`, () => {
+      const compose = parse(generateColorCompose(config, color)) as {
+        services: Record<string, { stop_grace_period?: string }>;
+      };
+      const grace = compose.services[`platform-${color}`]?.stop_grace_period;
+      expect(grace).toBeDefined();
+      expect(grace).toMatch(/^\d+s$/);
+      expect(Number.parseInt(grace as string, 10)).toBeGreaterThanOrEqual(
+        MIN_GRACE_SECONDS,
+      );
+    });
+  }
+});
diff --git a/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.test.ts b/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.test.ts
new file mode 100644
index 0000000000..dfebf21cb1
--- /dev/null
+++ b/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+
+import { parse } from 'yaml';
+
+import { setProjectId } from '../../project/project-context';
+import { generateSandboxColorCompose } from './generate-sandbox-color-compose';
+
+// getProjectId() is used for container_name / volume / network names.
+setProjectId('tale');
+
+const config = { version: '0.9.0', registry: 'ghcr.io/tale-project/tale' };
+
+interface ParsedService {
+  container_name?: string;
+  environment?: Record<string, string>;
+  depends_on?: Record<string, unknown>;
+}
+interface ParsedCompose {
+  services: Record<string, ParsedService>;
+  networks: Record<string, { name?: string }>;
+}
+
+describe('generateSandboxColorCompose', () => {
+  test('emits colour-suffixed spawner + egress on the shared sandbox net', () => {
+    const parsed = parse(
+      generateSandboxColorCompose(config, 'green'),
+    ) as ParsedCompose;
+
+    // Colour-suffixed service keys (these become the Docker DNS aliases).
+    expect(Object.keys(parsed.services).sort()).toEqual([
+      'sandbox-egress-green',
+      'sandbox-green',
+    ]);
+
+    const spawner = parsed.services['sandbox-green'];
+    expect(spawner.container_name).toBe('tale-sandbox-green');
+    // Spawner targets its OWN colour's egress + advertises its colour.
+    expect(spawner.environment?.SANDBOX_EGRESS_PROXY).toBe(
+      'http://sandbox-egress-green:3128',
+    );
+    expect(spawner.environment?.SANDBOX_COLOR).toBe('green');
+    expect(spawner.environment?.SANDBOX_EGRESS_NETWORK).toBe(
+      'tale-sandbox-net',
+    );
+    // depends_on points at the colour's egress, not the bare name.
+    expect(Object.keys(spawner.depends_on ?? {})).toEqual([
+      'sandbox-egress-green',
+    ]);
+
+    expect(parsed.services['sandbox-egress-green'].container_name).toBe(
+      'tale-sandbox-egress-green',
+    );
+
+    // Shared sandbox network (not per-colour) so bifrost/convex stay single-homed.
+    expect(parsed.networks.sandbox.name).toBe('tale-sandbox-net');
+    expect(parsed.networks.internal.name).toBe('tale_internal');
+  });
+
+  test('blue and green generate distinct, non-colliding names', () => {
+    const blue = parse(
+      generateSandboxColorCompose(config, 'blue'),
+    ) as ParsedCompose;
+    const green = parse(
+      generateSandboxColorCompose(config, 'green'),
+    ) as ParsedCompose;
+    expect(blue.services['sandbox-blue'].container_name).toBe(
+      'tale-sandbox-blue',
+    );
+    expect(green.services['sandbox-green'].container_name).toBe(
+      'tale-sandbox-green',
+    );
+    expect(
+      blue.services['sandbox-blue'].environment?.SANDBOX_EGRESS_PROXY,
+    ).toBe('http://sandbox-egress-blue:3128');
+  });
+});
diff --git a/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.ts b/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.ts
new file mode 100644
index 0000000000..13a14f62bd
--- /dev/null
+++ b/tools/cli/src/lib/compose/generators/generate-sandbox-color-compose.ts
@@ -0,0 +1,43 @@
+import { stringify } from 'yaml';
+
+import { getProjectId } from '../../../utils/load-env';
+import { createSandboxEgressService } from '../services/create-sandbox-egress-service';
+import { createSandboxService } from '../services/create-sandbox-service';
+import type { ComposeConfig, DeploymentColor, ServiceConfig } from '../types';
+
+/**
+ * Compose for ONE colour of the blue-green sandbox tier: a colour-suffixed
+ * spawner (`sandbox-<color>`) + its own egress sidecar (`sandbox-egress-<color>`)
+ * on the shared `tale-sandbox-net`. The deploy flip brings up the inactive
+ * colour with this, moves the bare `sandbox` network alias onto it once healthy,
+ * drains the old colour via `/v1/drain`, then tears the old colour down.
+ *
+ * The egress's container-local IMDS/RFC1918 iptables fence runs per-colour, so
+ * each colour keeps the full SSRF posture independently.
+ */
+export function generateSandboxColorCompose(
+  config: ServiceConfig,
+  color: DeploymentColor,
+): string {
+  const prefix = `${getProjectId()}_`;
+  const compose: ComposeConfig = {
+    services: {
+      // Egress first so the spawner's `depends_on: service_healthy` resolves.
+      [`sandbox-egress-${color}`]: createSandboxEgressService(config, color),
+      [`sandbox-${color}`]: createSandboxService(config, color),
+    },
+    volumes: {
+      // Spawner mounts the shared deployment config read-only (sandboxRuntime
+      // tier). Same external volume as the stateful compose.
+      'convex-data': { external: true, name: `${prefix}convex-data` },
+    },
+    networks: {
+      internal: { external: true, name: `${prefix}internal` },
+      // Shared across colours and dev/prod; pinned name so spawned runtime
+      // containers can `--network tale-sandbox-net` directly.
+      sandbox: { external: true, name: 'tale-sandbox-net' },
+    },
+  };
+
+  return stringify(compose);
+}
diff --git a/tools/cli/src/lib/compose/select-services.test.ts b/tools/cli/src/lib/compose/select-services.test.ts
new file mode 100644
index 0000000000..2836a04683
--- /dev/null
+++ b/tools/cli/src/lib/compose/select-services.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test';
+
+import { selectDefaultServices } from './select-services';
+
+const ALL_RUNNING = () => true;
+const NONE_RUNNING = () => false;
+
+describe('selectDefaultServices', () => {
+  test('always rolls platform + the always-roll tier (convex); sandbox flips separately', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: false,
+      stop: false,
+      isStopGatedRunning: ALL_RUNNING,
+    });
+    expect(sel.rotatable).toEqual(['platform']);
+    // sandbox / sandbox-egress are NOT here — they roll via the blue-green flip.
+    expect(sel.stateful).toEqual(['convex']);
+  });
+
+  test('running db/proxy are left untouched without --stop', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: false,
+      stop: false,
+      isStopGatedRunning: ALL_RUNNING,
+    });
+    expect(sel.leftRunning).toEqual(['db', 'proxy']);
+    expect(sel.stateful).not.toContain('db');
+    expect(sel.stateful).not.toContain('proxy');
+  });
+
+  test('--stop includes db/proxy even when running', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: false,
+      stop: true,
+      isStopGatedRunning: ALL_RUNNING,
+    });
+    expect(sel.leftRunning).toEqual([]);
+    expect(sel.stateful).toEqual(['convex', 'db', 'proxy']);
+  });
+
+  test('stopped db/proxy are updated without --stop', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: false,
+      stop: false,
+      isStopGatedRunning: NONE_RUNNING,
+    });
+    expect(sel.leftRunning).toEqual([]);
+    expect(sel.stateful).toContain('db');
+    expect(sel.stateful).toContain('proxy');
+  });
+
+  test('a partially-running stop-gated tier updates only the stopped one', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: false,
+      stop: false,
+      isStopGatedRunning: (s) => s === 'db', // db running, proxy stopped
+    });
+    expect(sel.leftRunning).toEqual(['db']);
+    expect(sel.stateful).toContain('proxy');
+    expect(sel.stateful).not.toContain('db');
+  });
+
+  test('first deploy includes everything regardless of running state', () => {
+    const sel = selectDefaultServices({
+      isFirstDeploy: true,
+      stop: false,
+      isStopGatedRunning: ALL_RUNNING,
+    });
+    expect(sel.leftRunning).toEqual([]);
+    expect(sel.stateful).toEqual(['convex', 'db', 'proxy']);
+  });
+});
diff --git a/tools/cli/src/lib/compose/select-services.ts b/tools/cli/src/lib/compose/select-services.ts
new file mode 100644
index 0000000000..7045cb296e
--- /dev/null
+++ b/tools/cli/src/lib/compose/select-services.ts
@@ -0,0 +1,55 @@
+import {
+  type RotatableService,
+  type StatefulService,
+  type StopGatedService,
+  ALWAYS_ROLL_SERVICES,
+  ROTATABLE_SERVICES,
+  STOP_GATED_SERVICES,
+} from './types';
+
+interface DefaultServiceSelection {
+  /** Blue-green rotated (platform). */
+  rotatable: RotatableService[];
+  /** Deployed via the stateful compose: always-roll tier + any stop-gated to update. */
+  stateful: StatefulService[];
+  /** Running stop-gated services deliberately left untouched (operator must pass --stop). */
+  leftRunning: StopGatedService[];
+}
+
+/**
+ * Decide which services a default `tale deploy` (no explicit `--services`)
+ * touches, per the three-tier policy:
+ *
+ *  - rotatable (`platform`) → always, blue-green.
+ *  - always-roll (`convex`) → always, in-place via the stateful compose. The
+ *    sandbox tier (`sandbox`, `sandbox-egress`) also rolls every deploy, but
+ *    through its own zero-gap blue-green flip (`flipSandboxTier`), not here —
+ *    so it is deliberately absent from the returned `stateful` list.
+ *  - stop-gated (`db`, `proxy`) → only when already stopped, on a first deploy,
+ *    or when the operator opts into the downtime with `--stop`; otherwise left
+ *    running and surfaced in `leftRunning` so the caller can warn.
+ *
+ * Pure (the running-state probe is injected) so it's unit-testable without Docker.
+ */
+export function selectDefaultServices(opts: {
+  isFirstDeploy: boolean;
+  stop: boolean;
+  isStopGatedRunning: (service: StopGatedService) => boolean;
+}): DefaultServiceSelection {
+  const stopGatedToUpdate: StopGatedService[] = [];
+  const leftRunning: StopGatedService[] = [];
+
+  for (const service of STOP_GATED_SERVICES) {
+    if (opts.isFirstDeploy || opts.stop || !opts.isStopGatedRunning(service)) {
+      stopGatedToUpdate.push(service);
+    } else {
+      leftRunning.push(service);
+    }
+  }
+
+  return {
+    rotatable: [...ROTATABLE_SERVICES],
+    stateful: [...ALWAYS_ROLL_SERVICES, ...stopGatedToUpdate],
+    leftRunning,
+  };
+}
diff --git a/tools/cli/src/lib/compose/services/create-platform-service.ts b/tools/cli/src/lib/compose/services/create-platform-service.ts
index a0cab245fd..204d9de062 100644
--- a/tools/cli/src/lib/compose/services/create-platform-service.ts
+++ b/tools/cli/src/lib/compose/services/create-platform-service.ts
@@ -16,6 +16,17 @@ export function createPlatformService(
     volumes: ['convex-data:/app/data:ro'],
     env_file: ['.env'],
     restart: 'unless-stopped',
+    // Graceful shutdown budget. The entrypoint's SIGTERM trap
+    // (services/platform/docker-entrypoint.sh) drains for
+    // SHUTDOWN_DRAIN_SECONDS (6) so the proxy stops routing, waits
+    // SHUTDOWN_GRACE_SECONDS (5) for in-flight requests, then gives Vite up to
+    // SHUTDOWN_TIMEOUT_SECONDS (30) to exit = ~41s worst case. Without this,
+    // Docker's default 10s grace SIGKILLs the old colour mid-drain on a
+    // blue-green flip, cutting in-flight HTTP/SSE chat streams. `docker stop`
+    // (no -t, see stop-container.ts) honors this StopTimeout — the same
+    // mechanism the sandbox tier relies on (create-sandbox-service.ts). Keep
+    // this >= the SHUTDOWN_* budget; bump it if those defaults grow.
+    stop_grace_period: '45s',
     healthcheck: {
       test: [
         'CMD-SHELL',
diff --git a/tools/cli/src/lib/compose/services/create-sandbox-egress-service.ts b/tools/cli/src/lib/compose/services/create-sandbox-egress-service.ts
index 796344d205..415b570f13 100644
--- a/tools/cli/src/lib/compose/services/create-sandbox-egress-service.ts
+++ b/tools/cli/src/lib/compose/services/create-sandbox-egress-service.ts
@@ -1,5 +1,5 @@
 import { getProjectId } from '../../../utils/load-env';
-import type { ComposeService, ServiceConfig } from '../types';
+import type { ComposeService, DeploymentColor, ServiceConfig } from '../types';
 import { DEFAULT_LOGGING } from '../types';
 
 /**
@@ -29,10 +29,17 @@ import { DEFAULT_LOGGING } from '../types';
  */
 export function createSandboxEgressService(
   config: ServiceConfig,
+  color?: DeploymentColor,
 ): ComposeService {
+  // Per-colour egress: each colour's runtime containers reach their own egress
+  // sidecar via its colour-suffixed service-key alias (`sandbox-egress-<color>`)
+  // on the shared sandbox network. The container-local iptables SSRF fence
+  // (IMDS/RFC1918) runs independently in each colour. Single-colour mode keeps
+  // the bare `sandbox-egress` name.
+  const suffix = color ? `-${color}` : '';
   return {
     image: `${config.registry}/tale-sandbox-egress:${config.version}`,
-    container_name: `${getProjectId()}-sandbox-egress`,
+    container_name: `${getProjectId()}-sandbox-egress${suffix}`,
     env_file: ['.env'],
     restart: 'unless-stopped',
     // Least privilege: drop the full default cap set, add back only what the
diff --git a/tools/cli/src/lib/compose/services/create-sandbox-service.ts b/tools/cli/src/lib/compose/services/create-sandbox-service.ts
index 4b2ad9cc55..0865287440 100644
--- a/tools/cli/src/lib/compose/services/create-sandbox-service.ts
+++ b/tools/cli/src/lib/compose/services/create-sandbox-service.ts
@@ -1,5 +1,5 @@
 import { getProjectId } from '../../../utils/load-env';
-import type { ComposeService, ServiceConfig } from '../types';
+import type { ComposeService, DeploymentColor, ServiceConfig } from '../types';
 import { DEFAULT_LOGGING } from '../types';
 
 /**
@@ -22,10 +22,29 @@ import { DEFAULT_LOGGING } from '../types';
  * Operators wanting stronger isolation set SANDBOX_RUNTIME=runsc and
  * install gVisor on the host; the spawner picks the runtime via env.
  */
-export function createSandboxService(config: ServiceConfig): ComposeService {
+export function createSandboxService(
+  config: ServiceConfig,
+  color?: DeploymentColor,
+): ComposeService {
+  // Blue-green: each colour is a distinct container, addressed by Convex on the
+  // `internal` network via the `sandbox-<color>` alias (the active colour also
+  // carries the bare `sandbox` alias, added at runtime by the deploy flip). It
+  // talks to its OWN egress (`sandbox-egress-<color>`) on the shared sandbox
+  // network. Single-colour mode (no `color`) keeps today's names/aliases.
+  const suffix = color ? `-${color}` : '';
+  const egressProxy = color
+    ? `http://sandbox-egress-${color}:3128`
+    : 'http://sandbox-egress:3128';
   return {
     image: `${config.registry}/tale-sandbox:${config.version}`,
-    container_name: `${getProjectId()}-sandbox`,
+    container_name: `${getProjectId()}-sandbox${suffix}`,
+    // Graceful drain on stop: the spawner's SIGTERM handler stops accepting new
+    // executions, cancels in-flight ones, and waits up to ~20s for them to tear
+    // down (services/sandbox/src/cleanup.ts installSignalHandlers). Give Docker
+    // a grace window past that deadline so a roll drains cleanly instead of
+    // SIGKILL'ing mid-execution. The blue-green flip drains via /v1/drain first;
+    // this is the backstop.
+    stop_grace_period: '30s',
     // NOTE: no published `ports` here. Convex (in-container, stateful
     // compose) reaches the spawner via the `internal` Docker network at
     // http://sandbox:8003 — publishing a host-side port is unnecessary
@@ -54,8 +73,15 @@ export function createSandboxService(config: ServiceConfig): ComposeService {
       SANDBOX_DOCKER_IN_CONTAINER: '${SANDBOX_DOCKER_IN_CONTAINER:-}',
       SANDBOX_RUNTIME_IMAGE:
         '${SANDBOX_RUNTIME_IMAGE:-tale-sandbox-runtime:latest}',
+      // Shared sandbox network across colours; the per-colour egress is
+      // addressed by its colour-suffixed alias so blue/green runtime
+      // containers each use their own egress sidecar.
       SANDBOX_EGRESS_NETWORK: 'tale-sandbox-net',
-      SANDBOX_EGRESS_PROXY: 'http://sandbox-egress:3128',
+      SANDBOX_EGRESS_PROXY: egressProxy,
+      // Colour identity: scopes the spawner's host-session root + .spawner.lock
+      // and stamps the `tale.color` label so each colour's sweeps only reap
+      // their own containers (services/sandbox/src/{config,cleanup,docker-args}).
+      ...(color ? { SANDBOX_COLOR: color } : {}),
     },
     volumes: [
       '/var/run/docker.sock:/var/run/docker.sock',
@@ -77,9 +103,12 @@ export function createSandboxService(config: ServiceConfig): ComposeService {
       start_period: '15s',
     },
     depends_on: {
-      'sandbox-egress': { condition: 'service_healthy' },
+      [`sandbox-egress${suffix}`]: { condition: 'service_healthy' },
     },
     logging: DEFAULT_LOGGING,
+    // Convex reaches the spawner on `internal` via the compose service-key
+    // alias (`sandbox` single-colour, `sandbox-<color>` per-colour); the bare
+    // `sandbox` alias for the active colour is added at runtime by the flip.
     networks: ['internal', 'sandbox'],
   };
 }
diff --git a/tools/cli/src/lib/compose/types.ts b/tools/cli/src/lib/compose/types.ts
index 9897da7440..083a9b4c82 100644
--- a/tools/cli/src/lib/compose/types.ts
+++ b/tools/cli/src/lib/compose/types.ts
@@ -65,34 +65,51 @@ export interface ServiceConfig {
 
 export const ROTATABLE_SERVICES = ['platform'] as const;
 /**
- * Lockstep services — always re-deployed on default `tale deploy`, even
- * though they're stateful (no blue/green rotation). Sandbox-side wire
- * protocol versions in lockstep with platform: shipping an old sandbox
- * image against new platform code would fail with HARVEST_FAILED on the
- * first run. Distinct from STATEFUL_SERVICES so the policy is explicit;
- * see deploy.ts default-services logic.
- *
- * Plan: sandbox-wobbly-origami §5 "Rollout".
+ * Sandbox tier — the spawner and its egress proxy. Kept in STATEFUL_SERVICES so
+ * `isStatefulService` / `isValidService` still recognize them as real service
+ * names, but they are NOT rolled through the stateful compose path: a default
+ * `tale deploy` rolls them via their own zero-gap blue-green flip
+ * (`flipSandboxTier`, in lockstep with platform's colour). The wire protocol
+ * versions with platform, so an old sandbox image against new platform code
+ * would fail with HARVEST_FAILED on the first run — hence the lockstep flip.
  */
-export const LOCKSTEP_SERVICES = ['sandbox', 'sandbox-egress'] as const;
+const SANDBOX_TIER_SERVICES = ['sandbox', 'sandbox-egress'] as const;
 export const STATEFUL_SERVICES = [
   'db',
   'proxy',
   'convex',
-  // Lockstep entries are part of STATEFUL_SERVICES for legacy
-  // back-compat (existing isStatefulService callers depend on this).
-  // The deploy.ts default path treats LOCKSTEP_SERVICES specially —
-  // see below.
-  ...LOCKSTEP_SERVICES,
+  // Listed only for service-name recognition (isStatefulService /
+  // isValidService); the default deploy rolls these via flipSandboxTier,
+  // never through the stateful compose path.
+  ...SANDBOX_TIER_SERVICES,
 ] as const;
 export const ALL_SERVICES = [
   ...ROTATABLE_SERVICES,
   ...STATEFUL_SERVICES,
 ] as const;
 
+/**
+ * Stop-gated tier — data/proxy infrastructure that is NOT rolled on a default
+ * deploy while it's running. A running stop-gated container is left untouched
+ * (with a warning) unless the operator opts into the downtime with
+ * `tale deploy --stop` (or it's already stopped, or it's a first deploy),
+ * because recreating Postgres / the proxy means an availability blip that a
+ * routine app-tier roll shouldn't incur.
+ */
+export const STOP_GATED_SERVICES = ['db', 'proxy'] as const;
+/**
+ * Always-roll-in-place tier — deployed via the stateful compose on EVERY
+ * default deploy. `convex` must never version-skew from platform but can't be
+ * two-color (it owns the single `convex-data` volume), so it's recreated in
+ * place and only when its image actually changed. `sandbox` / `sandbox-egress`
+ * are NOT here: they roll through their own zero-gap blue-green flip
+ * (`flipSandboxTier`, alongside platform's colour), not the stateful path.
+ */
+export const ALWAYS_ROLL_SERVICES = ['convex'] as const;
+
 export type RotatableService = (typeof ROTATABLE_SERVICES)[number];
 export type StatefulService = (typeof STATEFUL_SERVICES)[number];
-type LockstepService = (typeof LOCKSTEP_SERVICES)[number];
+export type StopGatedService = (typeof STOP_GATED_SERVICES)[number];
 export type ServiceName = RotatableService | StatefulService;
 
 export function isValidService(name: string): name is ServiceName {
@@ -106,7 +123,3 @@ export function isRotatableService(name: string): name is RotatableService {
 export function isStatefulService(name: string): name is StatefulService {
   return (STATEFUL_SERVICES as readonly string[]).includes(name);
 }
-
-export function isLockstepService(name: string): name is LockstepService {
-  return (LOCKSTEP_SERVICES as readonly string[]).includes(name);
-}
diff --git a/tools/cli/src/lib/docker/convex-run.ts b/tools/cli/src/lib/docker/convex-run.ts
new file mode 100644
index 0000000000..0f3f921e41
--- /dev/null
+++ b/tools/cli/src/lib/docker/convex-run.ts
@@ -0,0 +1,101 @@
+/**
+ * Shared "run a deployed Convex function with the admin key" channel.
+ *
+ * The platform container holds the convex CLI plus the env (`INSTANCE_NAME` /
+ * `INSTANCE_SECRET`) needed to derive the admin key, and reaches the convex
+ * backend over the internal network at `http://convex:3210`. So every CLI →
+ * Convex control call (`--override-all` reseed, deploy drain) runs the same
+ * incantation: `docker exec -i <platform> bash -s` piping a script that sources
+ * `env.sh`, derives `ADMIN_KEY`, then runs `bunx convex run <fn>`.
+ *
+ * `--no-push` invokes the ALREADY-DEPLOYED function rather than pushing the
+ * container's bundled code first (faster, and correct here — the function we
+ * call is whatever the running backend has). A function that doesn't exist on
+ * the running backend (e.g. an older version that predates it) makes
+ * `bunx convex run` exit non-zero; callers decide whether that's fatal.
+ */
+
+import { exec, type ExecResult } from './exec';
+import { findPlatformContainer } from './find-platform-container';
+
+const DEFAULT_TIMEOUT_S = 120;
+
+/**
+ * Re-derive `ADMIN_KEY` inline from `env.sh`'s helpers (NOT
+ * `generate-admin-key.sh`, which echoes a dashboard banner that would leak the
+ * key into stdout). `2>&1` merges stderr so a function-not-found / auth error is
+ * captured for the caller. No banner-stripping grep: callers extract the
+ * trailing JSON via `parseTrailingJson`, which is robust to banner noise.
+ */
+function buildScript(fn: string, timeoutS: number): string {
+  return `set -eo pipefail
+source /app/env.sh
+env_normalize_common
+ensure_instance_secret
+ADMIN_KEY=$(generate_key "$INSTANCE_NAME" "$INSTANCE_SECRET")
+cd /app
+HOME=/home/app timeout ${timeoutS} bunx convex run \\
+  ${fn} \\
+  --url "\${CONVEX_URL:-http://convex:3210}" \\
+  --admin-key "$ADMIN_KEY" \\
+  --no-push 2>&1
+`;
+}
+
+/**
+ * Invoke a deployed Convex function (no args) with the admin key, via the
+ * platform container. Returns the raw `ExecResult` — `success` reflects the
+ * `bunx convex run` exit code; `stdout` carries the function's JSON return value
+ * (plus banner noise). Resolve the container once and pass it in to avoid a
+ * lookup per poll.
+ */
+export async function runConvexAdmin(
+  fn: string,
+  opts: { container?: string; timeoutS?: number } = {},
+): Promise<ExecResult> {
+  const container = opts.container ?? (await findPlatformContainer());
+  return exec('docker', ['exec', '-i', container, 'bash', '-s'], {
+    stdin: buildScript(fn, opts.timeoutS ?? DEFAULT_TIMEOUT_S),
+  });
+}
+
+/**
+ * Extract the trailing JSON value from mixed stdout (`bunx convex run` prints
+ * the return value after decorative banner lines). Walks backward for the first
+ * line that begins a parseable value matching `isT`. Object-shaped values only
+ * (the predicate enforces the shape), so a banner line containing a stray `{`
+ * never mis-parses.
+ */
+export function parseTrailingJson<T>(
+  stdout: string,
+  isT: (value: unknown) => value is T,
+): T | null {
+  const trimmed = stdout.trim();
+  if (!trimmed) return null;
+  const lines = trimmed.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const candidate = lines[i].trimStart();
+    if (!candidate.startsWith('{')) continue;
+    const slice = lines.slice(i).join('\n');
+    try {
+      const parsed: unknown = JSON.parse(slice);
+      if (isT(parsed)) return parsed;
+    } catch {
+      // Not a complete JSON value starting here; try an earlier line.
+    }
+  }
+  return null;
+}
+
+// Self-hosted Convex admin keys are `<INSTANCE_NAME>|<base64>` — the charset
+// includes `|` so the redactor doesn't stop at the first pipe and leak the tail.
+const ADMIN_KEY_RE =
+  /\b([Aa]dmin[\s\-_][Kk]ey)\s*[:=]?\s*[A-Za-z0-9+/=._\-|]{12,}/g;
+const ADMIN_KEY_ARG_RE = /--admin-key([\s=]+)\S+/g;
+
+/** Defense-in-depth: strip any admin-key value before logging captured output. */
+export function redactAdminKey(text: string): string {
+  return text
+    .replace(ADMIN_KEY_RE, '$1: <redacted>')
+    .replace(ADMIN_KEY_ARG_RE, '--admin-key$1<redacted>');
+}
diff --git a/tools/cli/src/lib/project/project-context.ts b/tools/cli/src/lib/project/project-context.ts
index 56a5e5dd9c..8468546499 100644
--- a/tools/cli/src/lib/project/project-context.ts
+++ b/tools/cli/src/lib/project/project-context.ts
@@ -36,14 +36,14 @@ export function getProjectId(): string {
  * that uses Docker before any Docker operation runs.
  *
  * Throws with an actionable message if the project has no valid ID,
- * directing the user to `tale upgrade` (which auto-assigns IDs to legacy projects).
+ * directing the user to `tale update` (which auto-assigns IDs to legacy projects).
  */
 export async function resolveProjectContext(projectDir: string): Promise<void> {
   const project = await readProject(projectDir);
   const id = project.id;
   if (typeof id !== 'string' || id.trim() === '') {
     throw new Error(
-      'Project has no valid ID. Run "tale upgrade" to assign one.',
+      'Project has no valid ID. Run "tale update" to assign one.',
     );
   }
   if (!isValidProjectId(id)) {
@@ -58,7 +58,7 @@ export async function resolveProjectContext(projectDir: string): Promise<void> {
  * Like `resolveProjectContext`, but if the project has no `id` yet (legacy
  * project pre-dating per-project isolation) auto-assigns one, persists it
  * atomically, and proceeds. This is a UX smoothing for `tale start` /
- * `tale deploy` so users don't have to run `tale upgrade` as a separate step.
+ * `tale deploy` so users don't have to run `tale update` as a separate step.
  *
  * An invalid (non-empty but malformed) ID still throws — it signals
  * tampering or corruption that the user should resolve explicitly.
diff --git a/tools/cli/src/lib/project/types.ts b/tools/cli/src/lib/project/types.ts
index 5c36dd92ae..24abe1a814 100644
--- a/tools/cli/src/lib/project/types.ts
+++ b/tools/cli/src/lib/project/types.ts
@@ -6,7 +6,7 @@ export interface TaleProject {
   /**
    * Unique project ID used to namespace Docker resources (containers, volumes,
    * networks). Format: `{sanitized-name}-{6-hex}` (e.g. `my-app-a3f1b2`).
-   * Optional for backwards compatibility with pre-ID projects; `tale upgrade`
+   * Optional for backwards compatibility with pre-ID projects; `tale update`
    * auto-assigns one to legacy projects.
    */
   id?: string;
diff --git a/tools/cli/src/lib/version/align.test.ts b/tools/cli/src/lib/version/align.test.ts
new file mode 100644
index 0000000000..2f37b01a4c
--- /dev/null
+++ b/tools/cli/src/lib/version/align.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+
+import { type AlignDeps, ALIGN_GUARD_ENV, ensureAligned } from './align';
+import type { InstallHandle, ReleaseInfo } from './self-update';
+
+const RELEASE: ReleaseInfo = {
+  tag: 'v0.9.0',
+  version: '0.9.0',
+  assetNames: ['tale_macos'],
+};
+const HANDLE: InstallHandle = {
+  installPath: '/usr/local/bin/tale',
+  backupPath: '/usr/local/bin/tale.bak',
+};
+
+/** Build a fully-mocked AlignDeps; every field is a bun mock for assertions. */
+function makeDeps(overrides: Partial<AlignDeps> = {}): AlignDeps {
+  return {
+    currentVersion: '0.8.0',
+    isDevBuild: mock(() => false),
+    findProject: mock(() => '/project'),
+    readWorkspaceVersion: mock(async () => '0.9.0'),
+    resolveRelease: mock(async () => ({ release: RELEASE })),
+    installBinary: mock(async () => HANDLE),
+    commitInstall: mock(async () => {}),
+    reExec: mock(() => {}),
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  delete process.env[ALIGN_GUARD_ENV];
+});
+
+describe('ensureAligned', () => {
+  test('mismatch: installs the workspace version and re-execs', async () => {
+    const deps = makeDeps({ currentVersion: '0.8.0' }); // workspace = 0.9.0
+    await ensureAligned('status', deps);
+
+    expect(deps.resolveRelease).toHaveBeenCalledWith({ version: '0.9.0' });
+    expect(deps.installBinary).toHaveBeenCalledWith(RELEASE);
+    expect(deps.commitInstall).toHaveBeenCalledTimes(1);
+    expect(deps.reExec).toHaveBeenCalledTimes(1);
+  });
+
+  test('downgrade mismatch also aligns (workspace older than binary)', async () => {
+    const deps = makeDeps({
+      currentVersion: '0.9.0',
+      readWorkspaceVersion: mock(async () => '0.8.0'),
+      resolveRelease: mock(async () => ({
+        release: { tag: 'v0.8.0', version: '0.8.0', assetNames: [] },
+      })),
+    });
+    await ensureAligned('status', deps);
+
+    expect(deps.resolveRelease).toHaveBeenCalledWith({ version: '0.8.0' });
+    expect(deps.installBinary).toHaveBeenCalledTimes(1);
+    expect(deps.reExec).toHaveBeenCalledTimes(1);
+  });
+
+  test('already aligned: no install, no re-exec, no network', async () => {
+    const deps = makeDeps({
+      currentVersion: '0.9.0',
+      readWorkspaceVersion: mock(async () => '0.9.0'),
+    });
+    await ensureAligned('status', deps);
+
+    expect(deps.resolveRelease).not.toHaveBeenCalled();
+    expect(deps.installBinary).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('dev build: skips before touching the filesystem', async () => {
+    const deps = makeDeps({ isDevBuild: mock(() => true) });
+    await ensureAligned('status', deps);
+
+    expect(deps.findProject).not.toHaveBeenCalled();
+    expect(deps.installBinary).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('no project: nothing to align to', async () => {
+    const deps = makeDeps({ findProject: mock(() => null) });
+    await ensureAligned('status', deps);
+
+    expect(deps.readWorkspaceVersion).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('self-managing commands (update/init) never align', async () => {
+    const deps = makeDeps();
+    await ensureAligned('update', deps);
+    await ensureAligned('init', deps);
+
+    expect(deps.findProject).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('guard env set (re-exec child): skips to avoid an align loop', async () => {
+    process.env[ALIGN_GUARD_ENV] = '1';
+    const deps = makeDeps();
+    await ensureAligned('status', deps);
+
+    expect(deps.findProject).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('offline (resolveRelease throws): warns and proceeds, no re-exec', async () => {
+    const deps = makeDeps({
+      resolveRelease: mock(async () => {
+        throw new Error('network down');
+      }),
+    });
+    await ensureAligned('status', deps);
+
+    expect(deps.installBinary).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('install failure: does not re-exec', async () => {
+    const deps = makeDeps({
+      installBinary: mock(async () => {
+        throw new Error('permission denied');
+      }),
+    });
+    await ensureAligned('status', deps);
+
+    expect(deps.commitInstall).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+
+  test('unreadable tale.json: skips quietly', async () => {
+    const deps = makeDeps({
+      readWorkspaceVersion: mock(async () => {
+        throw new Error('invalid tale.json');
+      }),
+    });
+    await ensureAligned('status', deps);
+
+    expect(deps.resolveRelease).not.toHaveBeenCalled();
+    expect(deps.reExec).not.toHaveBeenCalled();
+  });
+});
diff --git a/tools/cli/src/lib/version/align.ts b/tools/cli/src/lib/version/align.ts
new file mode 100644
index 0000000000..d9208f78c4
--- /dev/null
+++ b/tools/cli/src/lib/version/align.ts
@@ -0,0 +1,132 @@
+import pkg from '../../../package.json';
+import * as logger from '../../utils/logger';
+import { findProject } from '../project/find-project';
+import { readProject } from '../project/read-project';
+import {
+  type InstallHandle,
+  type ReleaseInfo,
+  commitInstall,
+  installBinary,
+  isDevBuild,
+  resolveRelease,
+} from './self-update';
+
+/**
+ * Automatic CLI ↔ instance version alignment.
+ *
+ * The CLI binary must always be the same version as the instance it manages.
+ * The workspace records that version in `tale.json` (`cliVersion`), kept in
+ * sync by `tale update` / `tale deploy`. On every command we compare the
+ * compiled-in {@link pkg.version} against that field; when they match — the
+ * overwhelmingly common case — this is a pure file read with zero network
+ * cost. Only a genuine mismatch triggers a download + binary replace, after
+ * which we re-exec the same command under the freshly-installed binary.
+ *
+ * There is no opt-out: the alignment is intentional and not user-configurable.
+ * The one concession is robustness — if the target release can't be fetched
+ * (offline, rate-limited, asset not uploaded), we warn and proceed with the
+ * current binary rather than bricking the CLI.
+ */
+
+/** Set on a re-exec'd / spawned child to break any possibility of an align loop. */
+export const ALIGN_GUARD_ENV = 'TALE_ALIGNED';
+
+/**
+ * Commands that manage versions themselves and must NOT trigger alignment:
+ * `update` performs its own CLI bump + rollback, `init` runs before any
+ * instance/workspace version exists, and `uninstall` is about to delete the
+ * binary — aligning (download + re-exec) right before removal is wasteful and
+ * would re-exec a binary we're tearing down.
+ */
+const SELF_MANAGING_COMMANDS = new Set(['update', 'init', 'uninstall']);
+
+/**
+ * Injectable seams (re-exec, network, binary I/O) so the decision logic is
+ * unit-testable without real subprocesses or downloads. Production passes the
+ * defaults below.
+ */
+export interface AlignDeps {
+  currentVersion: string;
+  isDevBuild: (version?: string) => boolean;
+  findProject: () => string | null;
+  readWorkspaceVersion: (dir: string) => Promise<string | null>;
+  resolveRelease: (opts: {
+    version?: string;
+  }) => Promise<{ release: ReleaseInfo }>;
+  installBinary: (release: ReleaseInfo) => Promise<InstallHandle>;
+  commitInstall: (handle: InstallHandle) => Promise<void>;
+  reExec: () => void;
+}
+
+const defaultDeps: AlignDeps = {
+  currentVersion: pkg.version,
+  isDevBuild,
+  findProject,
+  readWorkspaceVersion: async (dir) => (await readProject(dir)).cliVersion,
+  resolveRelease,
+  installBinary,
+  commitInstall,
+  reExec,
+};
+
+/**
+ * Align the running binary to the workspace's recorded version, re-exec'ing
+ * under the new binary on a mismatch. A no-op when already aligned, on a dev
+ * build, outside a project, for self-managing commands, or in a re-exec'd
+ * child.
+ */
+export async function ensureAligned(
+  commandName: string | undefined,
+  deps: AlignDeps = defaultDeps,
+): Promise<void> {
+  if (process.env[ALIGN_GUARD_ENV] === '1') return;
+  if (deps.isDevBuild()) return;
+  if (commandName && SELF_MANAGING_COMMANDS.has(commandName)) return;
+
+  const projectDir = deps.findProject();
+  if (!projectDir) return; // No instance to align to.
+
+  let target: string | null;
+  try {
+    target = await deps.readWorkspaceVersion(projectDir);
+  } catch (err) {
+    // Unreadable / invalid tale.json — don't block the command on it.
+    logger.debug(`align: could not read instance version: ${String(err)}`);
+    return;
+  }
+
+  // The fast path: versions already match → nothing to do, no network.
+  if (!target || target === deps.currentVersion) return;
+
+  try {
+    const { release } = await deps.resolveRelease({ version: target });
+    logger.step(
+      `Aligning CLI to instance version ${release.version} (currently ${deps.currentVersion})...`,
+    );
+    const handle = await deps.installBinary(release);
+    await deps.commitInstall(handle);
+  } catch (err) {
+    logger.warn(
+      `Could not align the CLI to instance version ${target}: ` +
+        `${err instanceof Error ? err.message : String(err)}. ` +
+        `Continuing with v${deps.currentVersion}.`,
+    );
+    return;
+  }
+
+  deps.reExec();
+}
+
+/**
+ * Re-run the current invocation under the now-installed binary, passing a
+ * guard env var so the child never re-aligns. Replaces this process.
+ */
+function reExec(): never {
+  const result = Bun.spawnSync([process.execPath, ...process.argv.slice(2)], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env: { ...process.env, [ALIGN_GUARD_ENV]: '1' },
+  });
+  process.exit(result.exitCode ?? 0);
+}
diff --git a/tools/cli/src/lib/actions/upgrade.ts b/tools/cli/src/lib/version/self-update.ts
similarity index 57%
rename from tools/cli/src/lib/actions/upgrade.ts
rename to tools/cli/src/lib/version/self-update.ts
index b987d56a10..d20e43dccd 100644
--- a/tools/cli/src/lib/actions/upgrade.ts
+++ b/tools/cli/src/lib/version/self-update.ts
@@ -1,18 +1,25 @@
 import { chmod, rename, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 
 import pkg from '../../../package.json';
 import { compareVersions, extractVersion } from '../../utils/compare-versions';
 import * as logger from '../../utils/logger';
-import { requireProject } from '../project/find-project';
-import { update } from './update';
 
-const GITHUB_REPO = 'tale-project/tale';
+/**
+ * CLI binary self-management: resolve a GitHub release, download + verify its
+ * platform binary, and atomically replace the running binary — keeping a
+ * backup so the caller can roll back if a *subsequent* step fails.
+ *
+ * Extracted from the old `tale upgrade` action so both the version-alignment
+ * hook ({@link ../version/align}) and `tale update` reuse one implementation.
+ * The binary mechanics are unchanged; the only behavioural difference is that
+ * {@link installBinary} hands the backup path back to the caller instead of
+ * deleting it inline — {@link commitInstall} / {@link rollbackInstall} decide
+ * its fate.
+ */
 
-// First release that ships `tale upgrade --internal-sync-only`. Older binaries
-// don't have the subcommand, so re-spawning them with this flag would fail.
-const MIN_VERSION_WITH_INTERNAL_SYNC = '0.2.8';
+const GITHUB_REPO = 'tale-project/tale';
 
 const SUPPORTED_TARGETS: Record<string, string> = {
   'linux-x64': 'tale_linux',
@@ -20,30 +27,41 @@ const SUPPORTED_TARGETS: Record<string, string> = {
   'win32-x64': 'tale_windows.exe',
 };
 
-interface UpgradeOptions {
-  /** Install this exact version (e.g. "0.9.0" or "v0.9.0") instead of latest. */
-  version?: string;
-  force?: boolean;
-  dryRun?: boolean;
-  internalSyncOnly?: boolean;
-}
-
-function normalizeTag(input: string): string {
-  const trimmed = input.trim();
-  return trimmed.startsWith('v') ? trimmed : `v${trimmed}`;
-}
-
-interface ReleaseInfo {
+export interface ReleaseInfo {
   tag: string;
   version: string;
   assetNames: string[];
 }
 
-interface ReadyReleaseResult {
+export interface ResolvedRelease {
   release: ReleaseInfo;
+  /**
+   * Tags newer than `release` that lack the binary for this platform — i.e.
+   * a newer version exists but its binary hasn't been uploaded yet. Empty
+   * when a specific version was requested. Newest-first.
+   */
   skipped: string[];
 }
 
+/**
+ * Opaque handle returned by {@link installBinary}. Carries the path of the
+ * backed-up previous binary so the caller can {@link commitInstall} (discard
+ * it) or {@link rollbackInstall} (restore it).
+ */
+export interface InstallHandle {
+  installPath: string;
+  backupPath: string;
+}
+
+export function isDevBuild(version: string = pkg.version): boolean {
+  return version.includes('-dev');
+}
+
+function normalizeTag(input: string): string {
+  const trimmed = input.trim();
+  return trimmed.startsWith('v') ? trimmed : `v${trimmed}`;
+}
+
 function getAuthHeaders(): Record<string, string> {
   const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
   if (token) {
@@ -67,7 +85,7 @@ function parseRelease(data: Record<string, unknown>): ReleaseInfo | null {
 
 async function fetchLatestReadyRelease(
   asset: string,
-): Promise<ReadyReleaseResult> {
+): Promise<ResolvedRelease> {
   const url = `https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=15`;
   const response = await fetch(url, {
     headers: {
@@ -129,7 +147,7 @@ async function fetchLatestReadyRelease(
     );
   }
 
-  // Collect versions that are newer than the best ready release but lack the binary
+  // Collect versions newer than the best ready release but lacking the binary
   for (const candidate of candidates) {
     if (compareVersions(candidate.version, best.version) > 0) {
       skipped.push(candidate.tag);
@@ -201,10 +219,26 @@ function getAssetName(): string {
   return asset;
 }
 
-function getInstallPath(): string {
+/** The on-disk path of the running `tale` binary — what install replaced and uninstall removes. */
+export function getBinaryPath(): string {
   return process.execPath;
 }
 
+/**
+ * Resolve the release to install: a specific version when `version` is set,
+ * otherwise the latest release whose platform binary is uploaded.
+ */
+export async function resolveRelease(opts: {
+  version?: string;
+}): Promise<ResolvedRelease> {
+  const asset = getAssetName();
+  if (opts.version) {
+    const release = await fetchReleaseByTag(asset, normalizeTag(opts.version));
+    return { release, skipped: [] };
+  }
+  return fetchLatestReadyRelease(asset);
+}
+
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -296,7 +330,16 @@ async function verifyBinary(binaryPath: string, expectedVersion: string) {
   }
 }
 
-async function replaceBinary(tmpPath: string, installPath: string) {
+/**
+ * Replace the binary at `installPath` with `tmpPath`, backing up the current
+ * binary to `${installPath}.bak`. Returns the backup path — the caller owns it
+ * ({@link commitInstall} / {@link rollbackInstall}). Throws (and self-restores
+ * the backup) if the move fails.
+ */
+async function replaceBinary(
+  tmpPath: string,
+  installPath: string,
+): Promise<string> {
   const bakPath = `${installPath}.bak`;
 
   // Back up current binary (instant rename on same filesystem)
@@ -306,7 +349,7 @@ async function replaceBinary(tmpPath: string, installPath: string) {
     const code = (err as NodeJS.ErrnoException).code;
     if (code === 'EACCES' || code === 'EPERM') {
       throw new Error(
-        `Permission denied backing up ${installPath}. Try: sudo tale upgrade`,
+        `Permission denied backing up ${installPath}. Try: sudo tale update`,
         { cause: err },
       );
     }
@@ -340,7 +383,7 @@ async function replaceBinary(tmpPath: string, installPath: string) {
   }
 
   if (!succeeded) {
-    // Attempt to restore backup
+    // Move failed — restore the backup so the running binary is intact.
     try {
       await rename(bakPath, installPath);
     } catch {
@@ -355,25 +398,36 @@ async function replaceBinary(tmpPath: string, installPath: string) {
     );
   }
 
-  // Clean up backup (best-effort)
-  await unlink(bakPath).catch(() => {});
+  return bakPath;
 }
 
-function replaceBinaryWindows(tmpPath: string, installPath: string) {
-  const oldPath = `${installPath}.old`;
-
-  // Clean up previous .old file if exists
+/**
+ * Windows variant: rename the running exe out of the way (allowed on Windows)
+ * and move the new binary into place. Returns the `.old` backup path.
+ */
+function replaceBinaryWindows(tmpPath: string, installPath: string): string {
+  // `ren` takes a bare destination NAME (same directory), so the backup lands
+  // at `${dir}\\${oldName}` — derive everything from installPath's basename so
+  // the returned handle, the restore-on-failure rename, and commitInstall /
+  // rollbackInstall all reference the SAME real file regardless of the binary's
+  // name. (A prior `${installPath}.old` mismatched the literal `tale.old.exe`
+  // it actually created, silently breaking rollback.)
+  const base = basename(installPath);
+  const oldName = `${base}.old`;
+  const oldPath = join(dirname(installPath), oldName);
+
+  // Clean up a stale backup from a previous run if present
   try {
     Bun.spawnSync(['cmd', '/c', 'del', '/f', oldPath], { stdout: 'pipe' });
   } catch {
-    // ignore
+    // ignore — best-effort cleanup of a leftover backup
   }
 
   // Windows allows renaming a running exe
-  const renameOld = Bun.spawnSync(
-    ['cmd', '/c', 'ren', installPath, 'tale.old.exe'],
-    { stdout: 'pipe', stderr: 'pipe' },
-  );
+  const renameOld = Bun.spawnSync(['cmd', '/c', 'ren', installPath, oldName], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
   if (renameOld.exitCode !== 0) {
     throw new Error(
       `Failed to rename running binary. Try closing other tale processes.`,
@@ -385,201 +439,140 @@ function replaceBinaryWindows(tmpPath: string, installPath: string) {
     { stdout: 'pipe', stderr: 'pipe' },
   );
   if (renameNew.exitCode !== 0) {
-    // Attempt to restore
-    Bun.spawnSync(
-      ['cmd', '/c', 'ren', `${dirname(installPath)}\\tale.old.exe`, 'tale.exe'],
-      { stdout: 'pipe' },
-    );
+    // Restore the previous binary (rename the backup back to the original name).
+    Bun.spawnSync(['cmd', '/c', 'ren', oldPath, base], { stdout: 'pipe' });
     throw new Error(`Failed to place new binary. Previous version restored.`);
   }
-}
-
-export async function upgrade(options: UpgradeOptions): Promise<void> {
-  // Phase 4 shortcut: internal sync-only mode (called after binary replacement)
-  if (options.internalSyncOnly) {
-    await update({
-      force: options.force,
-      dryRun: options.dryRun,
-      skipHeader: true,
-    });
-    return;
-  }
 
-  requireProject();
-
-  const prefix = options.dryRun ? '[DRY-RUN] ' : '';
-  const pinnedVersion = options.version;
-  logger.header(
-    pinnedVersion
-      ? `${prefix}Migrating Tale CLI to ${pinnedVersion}`
-      : `${prefix}Upgrading Tale CLI`,
-  );
+  return oldPath;
+}
 
-  // Phase 1: Resolve target release (latest, or pinned)
+/**
+ * Download, verify, and install the given release over the running binary.
+ * Returns an {@link InstallHandle} whose backup the caller must dispose of via
+ * {@link commitInstall} (on success) or {@link rollbackInstall} (on failure).
+ */
+export async function installBinary(
+  release: ReleaseInfo,
+): Promise<InstallHandle> {
   const asset = getAssetName();
-  let release: ReleaseInfo;
-  let skipped: string[] = [];
-  if (pinnedVersion) {
-    const tag = normalizeTag(pinnedVersion);
-    logger.step(`${prefix}Looking up release ${tag}...`);
-    release = await fetchReleaseByTag(asset, tag);
-  } else {
-    logger.step(`${prefix}Checking for updates...`);
-    try {
-      ({ release, skipped } = await fetchLatestReadyRelease(asset));
-    } catch (err) {
-      throw new Error(
-        `Could not check for updates. ${err instanceof Error ? err.message : String(err)}`,
-        { cause: err },
-      );
-    }
-  }
-
-  const currentVersion = pkg.version;
-  const comparison = compareVersions(release.version, currentVersion);
+  const installPath = getBinaryPath();
+  const tmpPath = join(tmpdir(), `tale-update-${Date.now()}`);
 
-  logger.info(`Current version: ${currentVersion}`);
-  if (pinnedVersion) {
-    logger.info(`Target version:  ${release.version}`);
-  } else if (skipped.length > 0) {
-    logger.info(
-      `Latest version:  ${skipped[0].replace(/^v/, '')} (binary not yet available)`,
-    );
-    logger.info(`Upgrading to:    ${release.version}`);
-    logger.warn(
-      `Skipping ${skipped.map((t) => t.replace(/^v/, '')).join(', ')} — binary not yet uploaded. ` +
-        `Re-run 'tale upgrade' later to pick up newer versions.`,
-    );
-  } else {
-    logger.info(`Latest version:  ${release.version}`);
+  try {
+    await downloadBinary(release.tag, asset, tmpPath);
+    await verifyBinary(tmpPath, release.version);
+  } catch (err) {
+    await unlink(tmpPath).catch((e: unknown) => {
+      console.warn('[tale] failed to clean up temp download:', e);
+    });
+    throw err;
   }
 
-  if (pinnedVersion && comparison < 0) {
-    logger.warn(
-      `Downgrading from ${currentVersion} to ${release.version}. ` +
-        `Data migrations from the newer version persist in the database — reverse ` +
-        `them FIRST with \`tale migrate down --to ${release.version}\` (check ` +
-        `\`tale migrate status\`), then deploy the older binary.`,
-    );
-  }
+  const backupPath =
+    process.platform === 'win32'
+      ? replaceBinaryWindows(tmpPath, installPath)
+      : await replaceBinary(tmpPath, installPath);
 
-  const isDevBuild = currentVersion.includes('dev');
-  // When pinnedVersion, always replace unless the user is already on the exact target.
-  const needsBinaryUpgrade = pinnedVersion
-    ? comparison !== 0 || isDevBuild || options.force
-    : isDevBuild || comparison > 0 || options.force;
+  return { installPath, backupPath };
+}
 
-  if (!needsBinaryUpgrade) {
-    logger.success(
-      pinnedVersion
-        ? `CLI is already on v${currentVersion}`
-        : `CLI is up to date (v${currentVersion})`,
-    );
-    if (!pinnedVersion && skipped.length > 0) {
-      logger.info(
-        `Note: ${skipped[0].replace(/^v/, '')} is available but binary not yet uploaded — re-run 'tale upgrade' later.`,
-      );
-    }
-    logger.blank();
-
-    // Still sync project files even if binary is current
-    logger.step(`${prefix}Syncing project files...`);
-    await update({
-      force: options.force,
-      dryRun: options.dryRun,
-      skipHeader: true,
+/** Discard the backup after a successful install (best-effort). */
+export async function commitInstall(handle: InstallHandle): Promise<void> {
+  if (process.platform === 'win32') {
+    Bun.spawnSync(['cmd', '/c', 'del', '/f', handle.backupPath], {
+      stdout: 'pipe',
     });
     return;
   }
+  await unlink(handle.backupPath).catch((e: unknown) => {
+    console.warn('[tale] failed to remove install backup:', e);
+  });
+}
 
-  if (options.dryRun) {
-    logger.info(`${prefix}Would download ${asset} from ${release.tag}`);
-    logger.info(`${prefix}Would replace ${getInstallPath()}`);
-    logger.blank();
-    logger.step(
-      `${prefix}Project file sync preview (based on current v${currentVersion} templates):`,
+/** Restore the backed-up previous binary, undoing an {@link installBinary}. */
+export async function rollbackInstall(handle: InstallHandle): Promise<void> {
+  if (process.platform === 'win32') {
+    Bun.spawnSync(
+      ['cmd', '/c', 'move', '/y', handle.backupPath, handle.installPath],
+      { stdout: 'pipe', stderr: 'pipe' },
     );
-    logger.info('Note: actual changes may differ after upgrading.');
-    await update({
-      force: options.force,
-      dryRun: true,
-      skipHeader: true,
-    });
     return;
   }
+  await rename(handle.backupPath, handle.installPath);
+}
 
-  // Phase 2: Download & verify
-  const tmpPath = join(tmpdir(), `tale-upgrade-${Date.now()}`);
-
-  logger.step(`Downloading ${asset} (${release.tag})...`);
-  try {
-    await downloadBinary(release.tag, asset, tmpPath);
-  } catch (err) {
-    await unlink(tmpPath).catch(() => {});
-    throw err;
+/**
+ * Delete the `tale` binary at `installPath` (defaults to the running binary) —
+ * the inverse of {@link installBinary}, used by `tale uninstall`.
+ *
+ * Unix: `unlink` works even on the running binary (the inode lives until this
+ * process exits). A permission error retries under `sudo rm` — the same
+ * escalation {@link replaceBinary} uses for the install path. An already-gone
+ * binary is a no-op.
+ *
+ * Windows can't delete a running `.exe`, so we hand the deletion to a detached
+ * `cmd` that waits for this process to exit, then deletes the file. Best-effort:
+ * removal completes a moment after the command returns.
+ */
+export async function removeBinary(
+  installPath: string = getBinaryPath(),
+): Promise<void> {
+  if (process.platform === 'win32') {
+    // Detached so it outlives this process; the short ping is a portable
+    // "sleep" that lets the running .exe release before `del` runs.
+    Bun.spawn(
+      ['cmd', '/c', `ping 127.0.0.1 -n 2 >nul & del /f /q "${installPath}"`],
+      { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' },
+    );
+    logger.info(
+      'Windows cannot delete a running binary — it will be removed once this process exits.',
+    );
+    return;
   }
 
-  logger.step('Verifying downloaded binary...');
   try {
-    await verifyBinary(tmpPath, release.version);
+    await unlink(installPath);
   } catch (err) {
-    await unlink(tmpPath).catch(() => {});
-    throw err;
-  }
-
-  // Phase 3: Replace binary
-  logger.step('Installing new binary...');
-  try {
-    if (process.platform === 'win32') {
-      replaceBinaryWindows(tmpPath, getInstallPath());
-    } else {
-      await replaceBinary(tmpPath, getInstallPath());
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return; // already gone — nothing to do
+    if (code === 'EACCES' || code === 'EPERM') {
+      logger.info('Requesting sudo to remove binary...');
+      const sudoResult = Bun.spawnSync(['sudo', 'rm', '-f', installPath], {
+        stdout: 'inherit',
+        stderr: 'inherit',
+        stdin: 'inherit',
+      });
+      if (sudoResult.exitCode !== 0) {
+        throw new Error(
+          `Permission denied removing ${installPath}. Try: sudo tale uninstall`,
+          { cause: err },
+        );
+      }
+      return;
     }
-  } catch (err) {
-    await unlink(tmpPath).catch(() => {});
     throw err;
   }
+}
 
-  logger.success(`CLI upgraded to v${release.version}`);
-  if (skipped.length > 0) {
-    logger.info(
-      `Note: ${skipped[0].replace(/^v/, '')} binary may become available soon — re-run 'tale upgrade' later.`,
-    );
-  }
-
-  // Phase 4: Sync project files using the NEW binary.
-  // Older releases (pre-0.2.8) don't have `tale upgrade --internal-sync-only`,
-  // so when downgrading past that boundary we fall back to running the sync
-  // in-process with the current binary's logic.
-  logger.blank();
-  logger.step('Syncing project files with new version...');
+/**
+ * Best-effort cleanup of leftover update backups next to the binary —
+ * `${installPath}.bak` (Unix) and `${dir}/${basename}.old` (Windows). A missing
+ * backup is the common case and is silently ignored.
+ */
+export async function removeBinaryBackups(
+  installPath: string = getBinaryPath(),
+): Promise<void> {
+  const backups =
+    process.platform === 'win32'
+      ? [join(dirname(installPath), `${basename(installPath)}.old`)]
+      : [`${installPath}.bak`];
 
-  if (compareVersions(release.version, MIN_VERSION_WITH_INTERNAL_SYNC) < 0) {
-    logger.warn(
-      `Target v${release.version} predates 'upgrade --internal-sync-only'; running sync in-process instead.`,
-    );
-    await update({
-      force: options.force,
-      dryRun: options.dryRun,
-      skipHeader: true,
+  for (const backup of backups) {
+    await unlink(backup).catch((err: NodeJS.ErrnoException) => {
+      if (err.code !== 'ENOENT') {
+        logger.warn(`Failed to remove backup ${backup}: ${err.message}`);
+      }
     });
-    return;
-  }
-
-  const installPath = getInstallPath();
-  const syncArgs = [installPath, 'upgrade', '--internal-sync-only'];
-  if (options.force) syncArgs.push('--force');
-
-  const syncResult = Bun.spawnSync(syncArgs, {
-    stdout: 'inherit',
-    stderr: 'inherit',
-    stdin: 'inherit',
-  });
-
-  if (syncResult.exitCode !== 0) {
-    throw new Error(
-      'Project file sync failed. The CLI binary was upgraded successfully. ' +
-        'Run "tale upgrade --internal-sync-only" to retry syncing project files.',
-    );
   }
 }
diff --git a/tools/cli/src/utils/prompt.ts b/tools/cli/src/utils/prompt.ts
index 27651f7be6..dacfafee91 100644
--- a/tools/cli/src/utils/prompt.ts
+++ b/tools/cli/src/utils/prompt.ts
@@ -57,7 +57,8 @@ export class NonInteractiveError extends Error {
   }
 }
 
-function isInteractive(): boolean {
+/** Whether a real terminal is attached on both stdin and stdout. */
+export function isInteractive(): boolean {
   return process.stdin.isTTY && process.stdout.isTTY;
 }
 
diff --git a/tools/cli/tests/smoke.test.ts b/tools/cli/tests/smoke.test.ts
index aef6bb9c3b..fff2114f32 100644
--- a/tools/cli/tests/smoke.test.ts
+++ b/tools/cli/tests/smoke.test.ts
@@ -133,6 +133,36 @@ describe.skipIf(!BIN)('tale binary smoke tests', () => {
     SMOKE_TIMEOUT,
   );
 
+  test(
+    'uninstall --help documents the removal flags',
+    async () => {
+      const result = await run(['uninstall', '--help'], dir);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.toLowerCase()).toContain('remove the tale cli');
+      expect(result.stdout).toContain('-f, --force');
+      expect(result.stdout).toContain('--purge');
+      expect(result.stdout).toContain('--dry-run');
+    },
+    SMOKE_TIMEOUT,
+  );
+
+  test(
+    'uninstall --dry-run is non-destructive and leaves the binary working',
+    async () => {
+      // The command loads, never prompts, and removes nothing. Exit 0 on a
+      // release binary (dry-run previews) or 3 on a `-dev` binary (the dev
+      // guard refuses) — both are non-destructive. The binary must still run
+      // afterward, which is the invariant that matters regardless of build.
+      const result = await run(['uninstall', '--dry-run'], dir);
+      expect([0, 3]).toContain(result.exitCode);
+
+      const version = await run(['--version'], dir);
+      expect(version.exitCode).toBe(0);
+      expect(version.stdout.trim()).not.toBe('');
+    },
+    SMOKE_TIMEOUT,
+  );
+
   test(
     'start from a parent dir points at the child project, not a re-init',
     async () => {