From ed804a14e9f3e2a4df8e1e7906ad066a94b484a8 Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Sun, 27 Sep 2026 16:17:59 +0400
Subject: [PATCH 1/7] Cards standartization

---
 frontend/DESIGN.md                            |  81 +++--
 frontend/eslint.config.js                     |   5 +
 frontend/eslint/card-surfaces.d.ts            |   4 +
 frontend/eslint/card-surfaces.js              |  36 +++
 frontend/src/agents/NewAgent.test.tsx         |  45 ++-
 frontend/src/agents/NewAgent.tsx              |  56 ++--
 frontend/src/agents/SharedAgentCard.test.tsx  |  22 ++
 frontend/src/agents/SharedAgentCard.tsx       |   2 +-
 .../components/GuardrailsSection.test.tsx     |   7 +-
 .../agents/components/GuardrailsSection.tsx   |  18 +-
 .../src/agents/schedules/SchedulesView.tsx    | 289 +++++++++---------
 frontend/src/components/Chunks.test.tsx       |  13 +
 frontend/src/components/Chunks.tsx            |  27 +-
 frontend/src/components/SkeletonLoader.tsx    |  29 +-
 frontend/src/components/ui/card.test.tsx      |  10 +
 frontend/src/components/ui/card.tsx           |  19 +-
 frontend/src/design/DesignSystem.tsx          |  18 +-
 frontend/src/design/cardSurfaces.lint.test.ts |  85 ++++++
 frontend/src/settings/Teams.tsx               |   2 +
 19 files changed, 535 insertions(+), 233 deletions(-)
 create mode 100644 frontend/eslint/card-surfaces.d.ts
 create mode 100644 frontend/eslint/card-surfaces.js
 create mode 100644 frontend/src/agents/SharedAgentCard.test.tsx
 create mode 100644 frontend/src/design/cardSurfaces.lint.test.ts

diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
index 3584eab5..f45d45b1 100644
--- a/frontend/DESIGN.md
+++ b/frontend/DESIGN.md
@@ -91,6 +91,8 @@ One tint scale, by purpose:
 - Neutral hover: solid `bg-accent` in both themes (ghost buttons, combobox,
   SelectTrigger, Card `interactive`, Dropzone, every list-row highlight).
 - Quiet panel inside a page or card: `bg-muted`, not `bg-muted/40` or `/60`.
+  It is a small box inside a panel (a well, a guardrail stage), never a
+  page-sized panel around cards (see Card surfaces).
 - Dividers: `border-border`, not `border-border/60`.
 
 Patterns:
@@ -242,10 +244,11 @@ rounded-3xl`) are `variant="sidebar-item"`: left-aligned, full-radius, normal
 justify-start` and `aria-expanded`: a lucide `ChevronRight` first
   (`rotate-90` while open) in primary, then the foreground title, with a
   primary underline on hover. The button draws no focus ring; the panel does,
-  so keyboard focus outlines the whole white block:
-  `has-[[data-variant=section-toggle]:focus-visible]:ring-3 …:ring-ring/50
-…:ring-inset` on the panel `<div>` (inset, because a scrolling column clips
-  an outset ring). Status badges go beside the button, not inside it, or the
+  so keyboard focus outlines the whole panel. The panel is a `Card` (a place,
+  `subtle lg`), and every Card carries that ring
+  (`has-[[data-variant=section-toggle]:focus-visible]:ring-3 … ring-inset`,
+  inset because a scrolling column clips an outset ring), so pages pass
+  nothing for it. Status badges go beside the button, not inside it, or the
   hover underline runs under them.
 - Drop `text-white` on default and destructive buttons; the foreground token
   already provides it. Drop `disabled:cursor-not-allowed` on buttons; the
@@ -267,28 +270,68 @@ justify-start` and `aria-expanded`: a lucide `ChevronRight` first
 
 ### Card (`ui/card.tsx`)
 
-| Prop          | Values                                                                                                                                                        |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`     | `outline` (border + card surface, the default), `filled` (muted fill, no border, for tiles on a card-coloured page), `subtle` (border on the page background) |
-| `tone`        | `default`, `destructive` (the status soft fill and border, `border-destructive/50 bg-destructive/10`, over any variant)                                       |
-| `padding`     | `none`, `sm` (p-3, row boxes and code blocks), `default` (p-4), `lg` (p-6, tiles, chart panels and stat tiles)                                                |
-| `interactive` | whole card is the target: hover, focus ring and `selected` highlight; pair with `asChild` around a `<button>` or `<Link>`                                     |
+| Prop          | Values                                                                                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`     | `outline` (border + card surface, the default), `filled` (muted fill, no border), `subtle` (border on the page background); which one is decided by role, below |
+| `tone`        | `default`, `destructive` (the status soft fill and border, `border-destructive/50 bg-destructive/10`, over any variant)                                         |
+| `padding`     | `none`, `sm` (p-3, row boxes and code blocks), `default` (p-4), `lg` (p-6, tiles, panels and stat tiles)                                                        |
+| `interactive` | whole card is the target: hover, focus ring and `selected` highlight; pair with `asChild` around a `<button>` or `<Link>`                                       |
 
 Parts: `CardHeader` (title left, `CardAction` top-right), `CardTitle`,
 `CardDescription`, `CardContent`, `CardFooter` (meta row, sticks to the
 bottom). One radius for every card (`rounded-2xl`); pass only layout and
 `gap-*` on `Card`. Children are spaced by Card's `gap-3`, so they carry no
 `mt-*`. Replaces every hand-rolled
-`rounded-(md|lg|xl|2xl|3xl|4xl) border bg-(card|muted) p-*` box:
+`rounded-(md|lg|xl|2xl|3xl|4xl) border bg-(card|muted) p-*` box.
 
-- Tiles (sources, tools, custom models, agents, folders) are `filled`, `lg`
-  (a folder row `default`), `interactive` only when a click navigates (a
-  draft agent is not). The Add tool picker tiles sit on the modal's card, so
-  they are `outline interactive lg` with `asChild` around a `<button>`.
+#### Card surfaces: a thing or a place
+
+The variant follows what the card is, not where it looks nice. Ask one
+question: is it a **thing** you open, move, share or delete as a whole, or a
+**place** where you read or edit content? The fill marks objects; the border
+marks structure.
+
+| Role                 | Variant                                                   | Examples                                                                                          |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Thing (a tile)       | `filled`, on a page or in a modal                         | agents, folders, sources, tools, custom models, teams, chunks, the shared agent card              |
+| Place (a panel)      | `subtle` on the page, `outline` on a card (modal, drawer) | the agent form's sections, chart panels, stat tiles, log tables, schedule rows, the agent preview |
+| Choice (picker tile) | `outline interactive`, or `OptionCard`                    | the Add tool tiles; selection is drawn by the border, so the border stays                         |
+| Well                 | `filled padding="sm"`                                     | code, a token to copy, run output, inside a panel (see Code blocks below)                         |
+
+- Layers go page → panel (border) → well (fill), or page → tile (fill).
+  `subtle` and `outline` are one role on two surfaces; in light mode they
+  look the same.
+- An item that you read inside, rather than open elsewhere, is a place: a
+  schedule is an item, but its row expands into a run table, so it is a
+  `subtle` panel. The tile look is for a summary you open.
+- **No fill on a fill.** Nothing on a `filled` tile repeats its muted fill,
+  or it disappears: no `bg-muted` strip or box, no filled Card inside it, and
+  Skeleton bars take `surface="muted"`. Put a meta line such as a token count
+  in `CardFooter` instead of a muted header strip. The neutral Badge and the
+  muted Avatar are `bg-muted-foreground/15`, a tint that shows on the fill,
+  so they are fine on a tile. `no-restricted-syntax` enforces this for
+  children written in the same JSX as the `<Card variant="filled">`
+  (`eslint/card-surfaces.js`).
+- Never a page-sized `bg-muted` panel around a page's cards: panels sit on
+  the page background, as on Logs and Analytics.
+- A field in a `subtle` panel sits on the page background, so its floating
+  label passes `labelSurface="background"`; in an `outline` panel it keeps
+  the default `card`.
+
+Recipes by role:
+
+- Tiles are `filled`, `lg` (a folder row `default`), `interactive` only when a
+  click navigates (a draft agent is not). The Add tool picker tiles are
+  choices: `outline interactive lg` with `asChild` around a `<button>`.
 - Chart panels are `subtle lg` with fixed heights passed as layout; a chart
   panel inside a modal is `outline` (the modal is already `bg-card`).
-- Row boxes inside a form or panel (a guardrail check, the schedule's
-  timezone box, the discovered MCP tools) are `padding="sm"`.
+- Form sections (the agent form's Meta, Source, Prompt, Advanced,
+  Guardrails) are `subtle lg`; a disclosure section's header is a
+  `section-toggle`, and Card draws its focus ring.
+- Row boxes inside a form or panel (a guardrail check, a schedule row, the
+  schedule's timezone box, the discovered MCP tools) are `padding="sm"`, in
+  the panel variant of the surface they sit on (`subtle` in a page panel,
+  `outline` in a modal).
 - A danger zone (Delete agent, Revoke a device) and a failing stat are
   `tone="destructive"`; the title beside it is `SectionHeader
 tone="destructive"`. Muted text fails AA on the red fill, so the tone turns
@@ -296,8 +339,8 @@ tone="destructive"`. Muted text fails AA on the red fill, so the tone turns
   lighter colour back. Icon buttons inside a destructive-tone row are
   `ghost-destructive-on-accent`, whose red tint shows on the fill where
   ghost's grey square would not.
-- A card on the page background that must not look raised (the shared
-  agent card) is `subtle lg`. Cards never take a shadow.
+- The shared agent card (its page and a new agent chat) is a thing:
+  `filled lg`. Cards never take a shadow.
 - The shared agent card's description is `line-clamp-3` with no inner
   scroller (`max-h-* overflow-y-auto`) and no hover hint for the cut text.
 
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index ade63a0a..92b303b8 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -7,6 +7,8 @@ import unusedImports from 'eslint-plugin-unused-imports';
 import prettier from 'eslint-plugin-prettier';
 import globals from 'globals';
 
+import { cardSurfaceSelectors } from './eslint/card-surfaces.js';
+
 export default [
   {
     ignores: [
@@ -113,6 +115,9 @@ export default [
           message:
             'Modal, Sheet and DialogContent already return focus to what had it on open (ui/use-focus-return.ts). Don\'t hand-roll onCloseAutoFocus. See DESIGN.md "Focus return".',
         },
+        // Nothing on a filled tile repeats its muted fill (DESIGN.md "Card
+        // surfaces").
+        ...cardSurfaceSelectors,
       ],
       // Design-system rules (@shadcn/lint). Tokens, variants and the
       // approved exceptions are documented in DESIGN.md.
diff --git a/frontend/eslint/card-surfaces.d.ts b/frontend/eslint/card-surfaces.d.ts
new file mode 100644
index 00000000..f9722fb9
--- /dev/null
+++ b/frontend/eslint/card-surfaces.d.ts
@@ -0,0 +1,4 @@
+export declare const cardSurfaceSelectors: {
+  selector: string;
+  message: string;
+}[];
diff --git a/frontend/eslint/card-surfaces.js b/frontend/eslint/card-surfaces.js
new file mode 100644
index 00000000..d5ca6a29
--- /dev/null
+++ b/frontend/eslint/card-surfaces.js
@@ -0,0 +1,36 @@
+// Card surface rule (DESIGN.md "Card surfaces"): a tile is `filled`, and
+// nothing on a tile repeats its muted fill, or it disappears into it. The
+// neutral Badge and the muted Avatar are `bg-muted-foreground/15`, a tint
+// that shows on muted, so they are fine; a literal `bg-muted` is not. These
+// are `no-restricted-syntax` entries; they see children written in the same
+// JSX tree as the `<Card variant="filled">`, not ones a child component
+// renders.
+
+const FILLED_CARD =
+  'JSXElement:has(> JSXOpeningElement[name.name="Card"]:has(> JSXAttribute[name.name="variant"][value.value="filled"]))';
+
+// `bg-muted` or `bg-muted/NN`, with any variant prefix, but not
+// `bg-muted-foreground`.
+const BG_MUTED = '/(^|[\\s:])bg-muted([^-a-z]|$)/';
+
+/** @type {{ selector: string, message: string }[]} */
+export const cardSurfaceSelectors = [
+  {
+    selector: `${FILLED_CARD} JSXElement > JSXOpeningElement[name.name="Card"] > JSXAttribute[name.name="variant"][value.value="filled"]`,
+    message:
+      'A filled Card inside a filled Card is a fill on a fill. A well inside a tile needs a panel around it, or none. See DESIGN.md "Card surfaces".',
+  },
+  ...[
+    `${FILLED_CARD} JSXElement JSXAttribute[name.name="className"] Literal[value=${BG_MUTED}]`,
+    `${FILLED_CARD} JSXElement JSXAttribute[name.name="className"] TemplateElement[value.raw=${BG_MUTED}]`,
+  ].map((selector) => ({
+    selector,
+    message:
+      'bg-muted inside a filled tile is a fill on a fill and disappears. Drop the fill (use a Separator or border-border for structure). See DESIGN.md "Card surfaces".',
+  })),
+  {
+    selector: `${FILLED_CARD} JSXOpeningElement[name.name="Skeleton"]:not(:has(JSXAttribute[name.name="surface"]))`,
+    message:
+      'Skeleton bars on a filled tile need surface="muted", or they vanish into the fill. See DESIGN.md "Skeleton".',
+  },
+];
diff --git a/frontend/src/agents/NewAgent.test.tsx b/frontend/src/agents/NewAgent.test.tsx
index 55d0b937..9b96baea 100644
--- a/frontend/src/agents/NewAgent.test.tsx
+++ b/frontend/src/agents/NewAgent.test.tsx
@@ -221,7 +221,7 @@ describe('NewAgent form', () => {
     expect(toggle.querySelectorAll('svg')).toHaveLength(1);
     expect(toggle.querySelector('h2')).toBeNull();
     expect(toggle.parentElement!.tagName).toBe('H2');
-    const panel = toggle.closest('.bg-card')!;
+    const panel = toggle.closest('[data-slot="card"]')!;
     expect(panel.className).toContain(
       'has-[[data-variant=section-toggle]:focus-visible]:ring-3',
     );
@@ -327,6 +327,49 @@ describe('NewAgent form', () => {
     expect(valid.querySelector('svg.lucide-circle-check')).not.toBeNull();
   });
 
+  // Card surfaces: the form is a place, so each section is a subtle panel
+  // straight on the page, with no muted panel around the form.
+  it('draws each form section as a subtle panel on the page', async () => {
+    await render();
+    const titles = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="section-header"]'),
+    );
+    expect(titles.length).toBeGreaterThan(0);
+    for (const title of titles) {
+      const panel = title.closest<HTMLElement>('[data-slot="card"]')!;
+      expect(panel.dataset.variant).toBe(
+        title.closest('[data-tone="destructive"]')
+          ? panel.dataset.variant
+          : 'subtle',
+      );
+    }
+    const advanced = buttonByText('agents.form.sections.advanced');
+    const panel = advanced.closest<HTMLElement>('[data-slot="card"]')!;
+    expect(panel.dataset.variant).toBe('subtle');
+    expect(panel.dataset.padding).toBe('lg');
+    expect(container.querySelector('.bg-muted.rounded-2xl')).toBeNull();
+  });
+
+  it('notches floating labels on the page background', async () => {
+    await render();
+    const labels = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="form-field-label"]'),
+    );
+    expect(labels.length).toBeGreaterThan(0);
+    for (const label of labels) {
+      expect(label.className).toContain('bg-background');
+    }
+  });
+
+  it('draws the preview area as a subtle panel', async () => {
+    await render();
+    const hint = Array.from(container.querySelectorAll('p')).find(
+      (p) => p.textContent === 'agents.form.preview.publishedPreview',
+    )!;
+    const panel = hint.closest<HTMLElement>('[data-slot="card"]')!;
+    expect(panel.dataset.variant).toBe('subtle');
+  });
+
   it('shows the preview placeholder illustration as decorative images', async () => {
     await render();
     const images = container.querySelectorAll('img[alt=""]');
diff --git a/frontend/src/agents/NewAgent.tsx b/frontend/src/agents/NewAgent.tsx
index d34a3478..a8b832eb 100644
--- a/frontend/src/agents/NewAgent.tsx
+++ b/frontend/src/agents/NewAgent.tsx
@@ -873,12 +873,15 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
           <AlertDescription>{submitError}</AlertDescription>
         </Alert>
       )}
-      <div className="bg-muted mt-3 flex w-full flex-1 grid-cols-5 flex-col gap-10 rounded-2xl p-5 xl:grid xl:gap-5 xl:overflow-hidden">
+      <div className="mt-3 flex w-full flex-1 grid-cols-5 flex-col gap-10 xl:grid xl:gap-5 xl:overflow-hidden">
         <div className="scrollbar-overlay col-span-2 flex flex-col gap-5 xl:max-h-full xl:overflow-y-auto xl:pr-3">
-          <div className="bg-card flex flex-col gap-5 rounded-2xl px-6 py-3">
+          <Card variant="subtle" padding="lg" className="gap-5">
             <SectionHeader title={t('agents.form.sections.meta')} />
             <div className="flex flex-col gap-5">
-              <FormField label={t('agents.form.labels.name')}>
+              <FormField
+                labelSurface="background"
+                label={t('agents.form.labels.name')}
+              >
                 <Input
                   shape="pill"
                   type="text"
@@ -887,7 +890,10 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   onChange={(e) => setAgent({ ...agent, name: e.target.value })}
                 />
               </FormField>
-              <FormField label={t('agents.form.labels.description')}>
+              <FormField
+                labelSurface="background"
+                label={t('agents.form.labels.description')}
+              >
                 <Textarea
                   size="lg"
                   className="h-32"
@@ -915,8 +921,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 ]}
               />
             </div>
-          </div>
-          <div className="bg-card flex flex-col gap-3 rounded-2xl px-6 py-3">
+          </Card>
+          <Card variant="subtle" padding="lg">
             <SectionHeader title={t('agents.form.sections.source')} />
             <div>
               <div className="flex flex-wrap items-center gap-1">
@@ -970,8 +976,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 </p>
               )}
             </div>
-          </div>
-          <div className="bg-card rounded-2xl px-6 py-3">
+          </Card>
+          <Card variant="subtle" padding="lg">
             <div className="flex flex-wrap items-end gap-1">
               <div className="min-w-20 grow basis-full sm:basis-0">
                 <Prompts
@@ -1015,8 +1021,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 {t('agents.form.buttons.add')}
               </Button>
             </div>
-          </div>
-          <div className="bg-card flex flex-col gap-3 rounded-2xl px-6 py-3">
+          </Card>
+          <Card variant="subtle" padding="lg">
             <SectionHeader title={t('agents.form.sections.tools')} />
             <div className="flex flex-wrap items-center gap-1">
               <MultiSelectPopover
@@ -1069,8 +1075,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 }
               />
             </div>
-          </div>
-          <div className="bg-card flex flex-col gap-3 rounded-2xl px-6 py-3">
+          </Card>
+          <Card variant="subtle" padding="lg">
             <SectionHeader title={t('agents.form.sections.agentType')} />
             <div>
               <Select
@@ -1093,8 +1099,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 </SelectContent>
               </Select>
             </div>
-          </div>
-          <div className="bg-card flex flex-col gap-3 rounded-2xl px-6 py-3">
+          </Card>
+          <Card variant="subtle" padding="lg">
             <SectionHeader title={t('agents.form.sections.models')} />
             <div className="flex flex-col gap-3">
               <MultiSelectPopover
@@ -1154,7 +1160,10 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 }
               />
               {selectedModelIds.size > 0 && (
-                <FormField label={t('agents.form.labels.defaultModel')}>
+                <FormField
+                  labelSurface="background"
+                  label={t('agents.form.labels.defaultModel')}
+                >
                   <Select
                     value={agent.default_model_id || undefined}
                     onValueChange={(value) =>
@@ -1181,8 +1190,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 </FormField>
               )}
             </div>
-          </div>
-          <div className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset">
+          </Card>
+          <Card variant="subtle" padding="lg" className="gap-5">
             {/* The heading wraps the toggle: a button's children are
                 presentational, so a heading inside it is lost to screen readers. */}
             <h2>
@@ -1209,8 +1218,9 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
               </Button>
             </h2>
             {isAdvancedSectionExpanded && (
-              <div className="mt-5">
+              <div>
                 <FormField
+                  labelSurface="background"
                   label={t('agents.form.advanced.jsonSchema')}
                   hint={t('agents.form.advanced.jsonSchemaDescription')}
                 >
@@ -1355,7 +1365,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 </SettingRows>
               </div>
             )}
-          </div>
+          </Card>
           <GuardrailsSection
             value={agent.config?.guardrails}
             token={token}
@@ -1460,7 +1470,11 @@ function AgentPreviewArea() {
   const { t } = useTranslation();
   const selectedAgent = useSelector(selectSelectedAgent);
   return (
-    <div className="bg-card border-border h-[600px] w-full rounded-2xl border xl:h-full">
+    <Card
+      variant="subtle"
+      padding="none"
+      className="h-[600px] w-full xl:h-full"
+    >
       {selectedAgent?.status === 'published' ? (
         <div className="flex h-full w-full flex-col overflow-hidden rounded-2xl">
           <AgentPreview />
@@ -1484,7 +1498,7 @@ function AgentPreviewArea() {
           </p>
         </div>
       )}
-    </div>
+    </Card>
   );
 }
 
diff --git a/frontend/src/agents/SharedAgentCard.test.tsx b/frontend/src/agents/SharedAgentCard.test.tsx
new file mode 100644
index 00000000..a6e98c0b
--- /dev/null
+++ b/frontend/src/agents/SharedAgentCard.test.tsx
@@ -0,0 +1,22 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import SharedAgentCard from './SharedAgentCard';
+
+describe('SharedAgentCard', () => {
+  // Card surfaces: a summary of one agent is a thing, so it is a filled tile.
+  it('is a filled tile', () => {
+    const html = renderToStaticMarkup(
+      <SharedAgentCard
+        agent={
+          { id: 'a1', name: 'Carrier FAQ', description: 'Answers' } as never
+        }
+      />,
+    );
+    expect(html).toContain('data-slot="card"');
+    expect(html).toContain('data-variant="filled"');
+  });
+});
diff --git a/frontend/src/agents/SharedAgentCard.tsx b/frontend/src/agents/SharedAgentCard.tsx
index f4a8b44c..167313b8 100644
--- a/frontend/src/agents/SharedAgentCard.tsx
+++ b/frontend/src/agents/SharedAgentCard.tsx
@@ -27,7 +27,7 @@ export default function SharedAgentCard({
     Object.keys(agent.shared_metadata).length > 0;
   return (
     <Card
-      variant="subtle"
+      variant="filled"
       padding="lg"
       className="w-full max-w-[720px] sm:w-fit sm:min-w-[480px]"
     >
diff --git a/frontend/src/agents/components/GuardrailsSection.test.tsx b/frontend/src/agents/components/GuardrailsSection.test.tsx
index 581d1f34..72091bf5 100644
--- a/frontend/src/agents/components/GuardrailsSection.test.tsx
+++ b/frontend/src/agents/components/GuardrailsSection.test.tsx
@@ -179,12 +179,16 @@ describe('GuardrailsSection', () => {
     expect(active.parentElement).toBe(heading.parentElement);
     expect(heading.parentElement?.firstElementChild).toBe(heading);
 
+    // A place, not a thing: the section is a subtle panel on the page, and
+    // Card draws the ring for the section-toggle inside it.
     const panel = q('guardrails-section')!;
     expect(panel.contains(toggle)).toBe(true);
+    expect(panel.dataset.slot).toBe('card');
+    expect(panel.dataset.variant).toBe('subtle');
+    expect(panel.dataset.padding).toBe('lg');
     expect(panel.className).toContain(
       'has-[[data-variant=section-toggle]:focus-visible]:ring-3',
     );
-    expect(panel.className).toContain('bg-card');
 
     await act(async () => toggle.click());
     expect(toggle.getAttribute('aria-expanded')).toBe('false');
@@ -343,6 +347,7 @@ describe('GuardrailsSection', () => {
     await render();
     const card = q('guardrail-check-pii');
     expect(card?.dataset.slot).toBe('card');
+    expect(card?.dataset.variant).toBe('subtle');
     expect(card?.dataset.padding).toBe('sm');
   });
 
diff --git a/frontend/src/agents/components/GuardrailsSection.tsx b/frontend/src/agents/components/GuardrailsSection.tsx
index 3d27dd45..63259e59 100644
--- a/frontend/src/agents/components/GuardrailsSection.tsx
+++ b/frontend/src/agents/components/GuardrailsSection.tsx
@@ -216,10 +216,7 @@ export default function GuardrailsSection({
   const instanceDisabled = catalog !== null && catalog.enabled === false;
 
   return (
-    <div
-      className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset"
-      data-testid="guardrails-section"
-    >
+    <Card variant="subtle" padding="lg" data-testid="guardrails-section">
       <div className="flex flex-wrap items-center gap-2">
         {/* The heading wraps the toggle: a button's children are
             presentational, so a heading inside it is lost to screen readers. */}
@@ -265,7 +262,7 @@ export default function GuardrailsSection({
       </div>
 
       {expanded && (
-        <div className="mt-3 pb-3">
+        <div>
           {loadError && (
             <EmptyState
               tone="destructive"
@@ -339,6 +336,7 @@ export default function GuardrailsSection({
             <>
               <div className="mt-5">
                 <FormField
+                  labelSurface="background"
                   label={t('agents.form.guardrails.mode')}
                   hint={
                     config.mode === 'monitor_only'
@@ -426,6 +424,7 @@ export default function GuardrailsSection({
               </div>
 
               <FormField
+                labelSurface="background"
                 className="mt-6"
                 label={t('agents.form.guardrails.blockMessage')}
                 hint={t('agents.form.guardrails.blockMessageDescription')}
@@ -457,6 +456,7 @@ export default function GuardrailsSection({
               </SettingRow>
 
               <FormField
+                labelSurface="background"
                 className="mt-5"
                 label={t('agents.form.guardrails.timeout')}
                 disabled={disabled}
@@ -476,7 +476,7 @@ export default function GuardrailsSection({
           )}
         </div>
       )}
-    </div>
+    </Card>
   );
 }
 
@@ -597,7 +597,11 @@ function CheckCard({
   );
 
   return (
-    <Card padding="sm" data-testid={`guardrail-check-${info.name}`}>
+    <Card
+      variant="subtle"
+      padding="sm"
+      data-testid={`guardrail-check-${info.name}`}
+    >
       <div className="min-w-0 flex-1">
         <div className="flex flex-wrap items-center gap-2">
           <SectionHeader as="h4" size="xs" title={info.label} />
diff --git a/frontend/src/agents/schedules/SchedulesView.tsx b/frontend/src/agents/schedules/SchedulesView.tsx
index 9ab49b60..fefa1f29 100644
--- a/frontend/src/agents/schedules/SchedulesView.tsx
+++ b/frontend/src/agents/schedules/SchedulesView.tsx
@@ -7,6 +7,7 @@ import userService from '../../api/services/userService';
 import { LoadingState } from '@/components/ui/loading-state';
 import { SectionHeader } from '@/components/ui/section-header';
 import { Button } from '../../components/ui/button';
+import { Card } from '../../components/ui/card';
 import ConfirmationModal from '../../modals/ConfirmationModal';
 import { ActiveState } from '../../models/misc';
 import { selectToken } from '../../preferences/preferenceSlice';
@@ -193,112 +194,117 @@ export default function SchedulesView() {
               ) : (
                 <ul className="flex flex-col gap-3">
                   {recurring.map((schedule) => (
-                    <li
+                    <Card
+                      asChild
                       key={schedule.id}
-                      className="border-border bg-card rounded-lg border p-3"
+                      variant="subtle"
+                      padding="sm"
+                      className="gap-0"
                     >
-                      <div className="flex items-start justify-between">
-                        <div>
-                          <div className="flex items-center gap-2">
-                            <p className="font-semibold">
-                              {schedule.name ||
-                                schedule.instruction.slice(0, 80)}
+                      <li>
+                        <div className="flex items-start justify-between">
+                          <div>
+                            <div className="flex items-center gap-2">
+                              <p className="font-semibold">
+                                {schedule.name ||
+                                  schedule.instruction.slice(0, 80)}
+                              </p>
+                              <ScheduleStatusBadge status={schedule.status} />
+                            </div>
+                            <p className="text-muted-foreground text-xs">
+                              {formatCron(schedule.cron, t)} ·{' '}
+                              {t('agents.schedules.timezoneMeta', {
+                                ...NO_ESCAPE,
+                                timezone: schedule.timezone,
+                              })}{' '}
+                              ·{' '}
+                              {t('agents.schedules.nextRunMeta', {
+                                ...NO_ESCAPE,
+                                time: formatTimestamp(schedule.next_run_at),
+                              })}
                             </p>
-                            <ScheduleStatusBadge status={schedule.status} />
                           </div>
-                          <p className="text-muted-foreground text-xs">
-                            {formatCron(schedule.cron, t)} ·{' '}
-                            {t('agents.schedules.timezoneMeta', {
-                              ...NO_ESCAPE,
-                              timezone: schedule.timezone,
-                            })}{' '}
-                            ·{' '}
-                            {t('agents.schedules.nextRunMeta', {
-                              ...NO_ESCAPE,
-                              time: formatTimestamp(schedule.next_run_at),
-                            })}
-                          </p>
+                          <div className="flex gap-2">
+                            <Button
+                              type="button"
+                              variant="outline-primary"
+                              size="sm"
+                              shape="pill"
+                              onClick={() => openEdit(schedule)}
+                            >
+                              {t('agents.schedules.edit')}
+                            </Button>
+                            <Button
+                              type="button"
+                              variant="outline-primary"
+                              size="sm"
+                              shape="pill"
+                              onClick={() =>
+                                dispatch(
+                                  setSchedulePaused({
+                                    id: schedule.id,
+                                    action:
+                                      schedule.status === 'active'
+                                        ? 'pause'
+                                        : 'resume',
+                                    token,
+                                  }),
+                                )
+                              }
+                            >
+                              {schedule.status === 'active'
+                                ? t('agents.schedules.pause')
+                                : t('agents.schedules.resume')}
+                            </Button>
+                            <Button
+                              type="button"
+                              variant="outline-primary"
+                              size="sm"
+                              shape="pill"
+                              onClick={() =>
+                                dispatch(
+                                  runScheduleNow({ id: schedule.id, token }),
+                                )
+                              }
+                            >
+                              {t('agents.schedules.runNow')}
+                            </Button>
+                            <Button
+                              type="button"
+                              variant="destructive-outline"
+                              size="sm"
+                              shape="pill"
+                              onClick={() => requestDelete(schedule)}
+                            >
+                              {t('agents.schedules.delete')}
+                            </Button>
+                          </div>
                         </div>
-                        <div className="flex gap-2">
-                          <Button
-                            type="button"
-                            variant="outline-primary"
-                            size="sm"
-                            shape="pill"
-                            onClick={() => openEdit(schedule)}
-                          >
-                            {t('agents.schedules.edit')}
-                          </Button>
-                          <Button
-                            type="button"
-                            variant="outline-primary"
-                            size="sm"
-                            shape="pill"
-                            onClick={() =>
-                              dispatch(
-                                setSchedulePaused({
-                                  id: schedule.id,
-                                  action:
-                                    schedule.status === 'active'
-                                      ? 'pause'
-                                      : 'resume',
-                                  token,
-                                }),
-                              )
-                            }
-                          >
-                            {schedule.status === 'active'
-                              ? t('agents.schedules.pause')
-                              : t('agents.schedules.resume')}
-                          </Button>
-                          <Button
-                            type="button"
-                            variant="outline-primary"
-                            size="sm"
-                            shape="pill"
-                            onClick={() =>
-                              dispatch(
-                                runScheduleNow({ id: schedule.id, token }),
-                              )
-                            }
-                          >
-                            {t('agents.schedules.runNow')}
-                          </Button>
-                          <Button
-                            type="button"
-                            variant="destructive-outline"
-                            size="sm"
-                            shape="pill"
-                            onClick={() => requestDelete(schedule)}
-                          >
-                            {t('agents.schedules.delete')}
-                          </Button>
-                        </div>
-                      </div>
-                      <Button
-                        type="button"
-                        variant="link"
-                        size="xs"
-                        onClick={() =>
-                          setExpanded(
-                            expanded === schedule.id ? null : schedule.id,
-                          )
-                        }
-                        className="mt-0.5 -ml-2"
-                      >
-                        {expanded === schedule.id
-                          ? t('agents.schedules.hideRuns')
-                          : t('agents.schedules.showRuns')}
-                      </Button>
-                      {expanded === schedule.id && (
-                        <div className="mt-2">
-                          <RunLog
-                            scheduleId={schedule.id}
-                            onSelect={(run) => setActiveRun(run)}
-                          />
-                        </div>
-                      )}
-                    </li>
+                        <Button
+                          type="button"
+                          variant="link"
+                          size="xs"
+                          onClick={() =>
+                            setExpanded(
+                              expanded === schedule.id ? null : schedule.id,
+                            )
+                          }
+                          className="mt-0.5 -ml-2"
+                        >
+                          {expanded === schedule.id
+                            ? t('agents.schedules.hideRuns')
+                            : t('agents.schedules.showRuns')}
+                        </Button>
+                        {expanded === schedule.id && (
+                          <div className="mt-2">
+                            <RunLog
+                              scheduleId={schedule.id}
+                              onSelect={(run) => setActiveRun(run)}
+                            />
+                          </div>
+                        )}
+                      </li>
+                    </Card>
                   ))}
                 </ul>
               )}
@@ -316,49 +322,54 @@ export default function SchedulesView() {
               ) : (
                 <ul className="flex flex-col gap-2">
                   {oneTime.map((schedule) => (
-                    <li
+                    <Card
+                      asChild
                       key={schedule.id}
-                      className="border-border bg-card rounded-lg border p-3 text-sm"
+                      variant="subtle"
+                      padding="sm"
+                      className="gap-0"
                     >
-                      <div className="flex items-start justify-between">
-                        <div>
-                          <div className="flex items-center gap-2">
-                            <p className="font-semibold">
-                              {schedule.name ||
-                                schedule.instruction.slice(0, 80)}
+                      <li>
+                        <div className="flex items-start justify-between">
+                          <div>
+                            <div className="flex items-center gap-2">
+                              <p className="font-semibold">
+                                {schedule.name ||
+                                  schedule.instruction.slice(0, 80)}
+                              </p>
+                              <ScheduleStatusBadge status={schedule.status} />
+                            </div>
+                            <p className="text-muted-foreground text-xs">
+                              runs at {formatTimestamp(schedule.run_at)}
                             </p>
-                            <ScheduleStatusBadge status={schedule.status} />
                           </div>
-                          <p className="text-muted-foreground text-xs">
-                            runs at {formatTimestamp(schedule.run_at)}
-                          </p>
+                          <div className="flex gap-2">
+                            {schedule.status === 'active' && (
+                              <Button
+                                type="button"
+                                variant="outline-primary"
+                                size="sm"
+                                shape="pill"
+                                onClick={() => openEdit(schedule)}
+                              >
+                                {t('agents.schedules.edit')}
+                              </Button>
+                            )}
+                            {schedule.status === 'active' && (
+                              <Button
+                                type="button"
+                                variant="destructive-outline"
+                                size="sm"
+                                shape="pill"
+                                onClick={() => requestDelete(schedule)}
+                              >
+                                {t('agents.schedules.cancel')}
+                              </Button>
+                            )}
+                          </div>
                         </div>
-                        <div className="flex gap-2">
-                          {schedule.status === 'active' && (
-                            <Button
-                              type="button"
-                              variant="outline-primary"
-                              size="sm"
-                              shape="pill"
-                              onClick={() => openEdit(schedule)}
-                            >
-                              {t('agents.schedules.edit')}
-                            </Button>
-                          )}
-                          {schedule.status === 'active' && (
-                            <Button
-                              type="button"
-                              variant="destructive-outline"
-                              size="sm"
-                              shape="pill"
-                              onClick={() => requestDelete(schedule)}
-                            >
-                              {t('agents.schedules.cancel')}
-                            </Button>
-                          )}
-                        </div>
-                      </div>
-                    </li>
+                      </li>
+                    </Card>
                   ))}
                 </ul>
               )}
diff --git a/frontend/src/components/Chunks.test.tsx b/frontend/src/components/Chunks.test.tsx
index 0124a09e..0a2ef6ad 100644
--- a/frontend/src/components/Chunks.test.tsx
+++ b/frontend/src/components/Chunks.test.tsx
@@ -111,6 +111,19 @@ describe('Chunks', () => {
     expect(tile!.className).not.toContain('hover:scale-105');
   });
 
+  it('draws each chunk as a filled tile with its token count in the footer', async () => {
+    await render();
+    const tile = container.querySelector<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    )!;
+    expect(tile.dataset.variant).toBe('filled');
+    expect(tile.dataset.padding).toBe('lg');
+    const footer = tile.querySelector('[data-slot="card-footer"]')!;
+    expect(footer.textContent).toContain('settings.sources.tokensUnit');
+    // No muted strip on the muted tile: it would disappear.
+    expect(tile.querySelector('.bg-muted')).toBeNull();
+  });
+
   const renderPath = async (props: {
     onPathSelect?: (depth: number) => void;
     handleGoBack?: () => void;
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index 5623ccc1..513e5d8c 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -20,7 +20,7 @@ import { formatChunkTokens } from './chunkUtils';
 import SkeletonLoader from './SkeletonLoader';
 import PathHeader from './tree/PathHeader';
 import { Button } from './ui/button';
-import { Card } from './ui/card';
+import { Card, CardFooter } from './ui/card';
 import {
   Command,
   CommandEmpty,
@@ -611,10 +611,11 @@ const Chunks: React.FC<ChunksProps> = ({
                     filteredChunks.map((chunk, index) => (
                       <Card
                         key={index}
+                        variant="filled"
+                        padding="lg"
                         interactive
-                        padding="none"
                         asChild
-                        className="relative h-[197px] w-full max-w-[487px] justify-between gap-0 overflow-hidden"
+                        className="h-50 w-full justify-between"
                       >
                         <button
                           type="button"
@@ -624,19 +625,13 @@ const Chunks: React.FC<ChunksProps> = ({
                             setEditingText(chunk.text || '');
                           }}
                         >
-                          <div className="w-full">
-                            <div className="border-border bg-muted flex w-full items-center justify-between border-b px-4 py-3">
-                              <div className="text-muted-foreground text-sm">
-                                {formatChunkTokens(chunk.metadata)}{' '}
-                                {t('settings.sources.tokensUnit')}
-                              </div>
-                            </div>
-                            <div className="px-4 pt-3 pb-6">
-                              <p className="text-foreground line-clamp-6 text-sm leading-5 font-normal">
-                                {chunk.text}
-                              </p>
-                            </div>
-                          </div>
+                          <p className="text-foreground line-clamp-6 text-sm leading-5 font-normal">
+                            {chunk.text}
+                          </p>
+                          <CardFooter>
+                            {formatChunkTokens(chunk.metadata)}{' '}
+                            {t('settings.sources.tokensUnit')}
+                          </CardFooter>
                         </button>
                       </Card>
                     ))
diff --git a/frontend/src/components/SkeletonLoader.tsx b/frontend/src/components/SkeletonLoader.tsx
index 47975001..e35c9f1a 100644
--- a/frontend/src/components/SkeletonLoader.tsx
+++ b/frontend/src/components/SkeletonLoader.tsx
@@ -185,27 +185,26 @@ const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({
     </>
   );
 
+  // Mirrors the chunk tile: a filled Card with text lines, then the token
+  // count in the footer.
   const renderChunkCards = () => (
     <>
       {Array.from({ length: count }).map((_, index) => (
-        <div
+        <Card
           key={`chunk-skel-${index}`}
-          className="border-border relative flex h-[197px] w-full max-w-[487px] animate-pulse flex-col overflow-hidden rounded-2xl border"
+          variant="filled"
+          padding="lg"
+          className="h-50 w-full justify-between"
         >
-          <div className="w-full">
-            <div className="border-border bg-muted flex w-full items-center justify-between border-b px-4 py-3">
-              <div className="bg-muted-foreground/20 h-4 w-20 rounded"></div>
-            </div>
-            <div className="flex flex-col gap-3 px-4 pt-4 pb-6">
-              <div className="bg-muted h-3 w-full rounded"></div>
-              <div className="bg-muted h-3 w-11/12 rounded"></div>
-              <div className="bg-muted h-3 w-5/6 rounded"></div>
-              <div className="bg-muted h-3 w-4/5 rounded"></div>
-              <div className="bg-muted h-3 w-3/4 rounded"></div>
-              <div className="bg-muted h-3 w-2/3 rounded"></div>
-            </div>
+          <div className="flex flex-col gap-3">
+            <Skeleton surface="muted" className="h-3 w-full" />
+            <Skeleton surface="muted" className="h-3 w-11/12" />
+            <Skeleton surface="muted" className="h-3 w-5/6" />
+            <Skeleton surface="muted" className="h-3 w-4/5" />
+            <Skeleton surface="muted" className="h-3 w-2/3" />
           </div>
-        </div>
+          <Skeleton surface="muted" className="h-3 w-20" />
+        </Card>
       ))}
     </>
   );
diff --git a/frontend/src/components/ui/card.test.tsx b/frontend/src/components/ui/card.test.tsx
index 6e78a6e8..af73133c 100644
--- a/frontend/src/components/ui/card.test.tsx
+++ b/frontend/src/components/ui/card.test.tsx
@@ -32,6 +32,16 @@ describe('Card', () => {
     expect(html).toContain('data-tone="destructive"');
   });
 
+  it('rings the whole card while a section-toggle inside it has keyboard focus', () => {
+    const classes = cardVariants({ variant: 'subtle' });
+    expect(classes).toContain(
+      'has-[[data-variant=section-toggle]:focus-visible]:ring-3',
+    );
+    expect(classes).toContain(
+      'has-[[data-variant=section-toggle]:focus-visible]:ring-inset',
+    );
+  });
+
   it('destructive tone turns muted text inside it to foreground', () => {
     const classes = cardVariants({ tone: 'destructive' });
     expect(classes).toContain('[&_.text-muted-foreground]:text-foreground');
diff --git a/frontend/src/components/ui/card.tsx b/frontend/src/components/ui/card.tsx
index 11a88eae..8e05c629 100644
--- a/frontend/src/components/ui/card.tsx
+++ b/frontend/src/components/ui/card.tsx
@@ -4,16 +4,27 @@ import { cva, type VariantProps } from 'class-variance-authority';
 
 import { cn, focusRing } from '@/lib/utils';
 
+// A card holding a section-toggle (a disclosure panel's header) draws the
+// toggle's keyboard focus as a ring round the whole panel; the toggle itself
+// has none. Inset, because a scrolling column clips an outset ring.
+const sectionToggleRing =
+  'has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 has-[[data-variant=section-toggle]:focus-visible]:ring-inset';
+
+// Variants by role (DESIGN.md "Card surfaces"): a thing is `filled`, a place
+// is `subtle` on the page or `outline` on a card-coloured surface.
 const cardVariants = cva(
-  'text-card-foreground flex flex-col gap-3 rounded-2xl text-sm transition-colors',
+  `text-card-foreground flex flex-col gap-3 rounded-2xl text-sm transition-colors ${sectionToggleRing}`,
   {
     variants: {
       variant: {
-        // Bordered surface: lists of entities, panels, headers.
+        // A place on a card-coloured surface (a modal, a floating panel), and
+        // picker choices, whose selection is the border.
         outline: 'border-border bg-card border',
-        // Filled, no border: tiles on a card-coloured page (sources, tools).
+        // A thing: a tile you open, move, share or delete as a whole
+        // (agents, sources, tools, teams, chunks). Also a well (code,
+        // output) inside a panel.
         filled: 'bg-muted',
-        // Bordered on a muted page background.
+        // A place on the page: form sections, charts, tables, logs.
         subtle: 'border-border bg-background border',
       },
       tone: {
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
index 50910fad..7b936af2 100644
--- a/frontend/src/design/DesignSystem.tsx
+++ b/frontend/src/design/DesignSystem.tsx
@@ -856,10 +856,10 @@ export default function DesignSystem() {
           </Example>
           <Example
             title="Section panel toggle"
-            code='<div className="has-[[data-variant=section-toggle]:focus-visible]:ring-3 …"><Button variant="section-toggle" size="sm" aria-expanded>'
+            code='<Card variant="subtle" padding="lg"><Button variant="section-toggle" size="sm" aria-expanded> (Card draws the focus ring)'
           >
-            <div className="bg-muted max-w-md rounded-2xl p-4">
-              <div className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset">
+            <div className="max-w-md">
+              <Card variant="subtle" padding="lg">
                 <div className="flex flex-wrap items-center gap-2">
                   <Button
                     variant="section-toggle"
@@ -878,11 +878,11 @@ export default function DesignSystem() {
                   <Badge variant="destructive">1 needs setup</Badge>
                 </div>
                 {sectionOpen && (
-                  <p className="text-muted-foreground mt-2 text-sm">
+                  <p className="text-muted-foreground text-sm">
                     Run the selected checks on this agent&apos;s runs.
                   </p>
                 )}
-              </div>
+              </Card>
             </div>
           </Example>
           <Example
@@ -1536,14 +1536,14 @@ export default function DesignSystem() {
           </Example>
           <Example
             title="Subtle surface and paddings"
-            code='<Card variant="subtle"> on bg-muted · tone="destructive" · padding="lg" · padding="none"'
+            code='<Card variant="subtle"> a place on the page · tone="destructive" · padding="lg" · padding="none"'
           >
-            <div className="bg-muted grid items-start gap-4 rounded-2xl p-4 md:grid-cols-2">
+            <div className="grid items-start gap-4 md:grid-cols-2">
               <Card variant="subtle" padding="lg">
                 <CardTitle>Subtle</CardTitle>
                 <CardDescription>
-                  subtle is a bordered background-coloured box on a muted page;
-                  lg pads it 24px.
+                  subtle is a place: a bordered panel on the page background
+                  (form sections, charts, logs); lg pads it 24px.
                 </CardDescription>
               </Card>
               <Card tone="destructive" padding="lg">
diff --git a/frontend/src/design/cardSurfaces.lint.test.ts b/frontend/src/design/cardSurfaces.lint.test.ts
new file mode 100644
index 00000000..30ef1d07
--- /dev/null
+++ b/frontend/src/design/cardSurfaces.lint.test.ts
@@ -0,0 +1,85 @@
+// @vitest-environment node
+import tsParser from '@typescript-eslint/parser';
+import { Linter } from 'eslint';
+
+import { cardSurfaceSelectors } from '../../eslint/card-surfaces.js';
+
+const linter = new Linter({ configType: 'flat' });
+
+function lint(code: string): string[] {
+  return linter
+    .verify(
+      code,
+      [
+        {
+          files: ['**/*.tsx'],
+          languageOptions: {
+            parser: tsParser,
+            parserOptions: { ecmaFeatures: { jsx: true } },
+          },
+          rules: { 'no-restricted-syntax': ['error', ...cardSurfaceSelectors] },
+        },
+      ],
+      'fixture.tsx',
+    )
+    .map((m) => m.message);
+}
+
+describe('card surface lint: no fill on a fill', () => {
+  it('rejects bg-muted on an element inside a filled tile, in cn() too', () => {
+    expect(
+      lint(
+        `<Card variant="filled"><div className="bg-muted px-4">x</div></Card>`,
+      ),
+    ).toHaveLength(1);
+    expect(
+      lint(
+        `<Card variant="filled"><div className={cn('hover:bg-muted/60', a && 'p-2')}>x</div></Card>`,
+      ),
+    ).toHaveLength(1);
+  });
+
+  it('rejects a filled Card nested in a filled Card', () => {
+    expect(
+      lint(
+        `<Card variant="filled"><Card variant="filled" padding="sm">x</Card></Card>`,
+      ),
+    ).toHaveLength(1);
+  });
+
+  it('rejects a Skeleton without surface="muted" on a filled tile', () => {
+    expect(
+      lint(`<Card variant="filled"><Skeleton className="h-4" /></Card>`),
+    ).toHaveLength(1);
+    expect(
+      lint(
+        `<Card variant="filled"><Skeleton surface="muted" className="h-4" /></Card>`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  it('allows the neutral Badge and muted Avatar tints on a filled tile', () => {
+    expect(
+      lint(`<Card variant="filled">
+        <Badge variant="neutral">Member</Badge>
+        <Avatar variant="muted">M</Avatar>
+      </Card>`),
+    ).toHaveLength(0);
+  });
+
+  it('allows the same children on panels and allows muted-foreground', () => {
+    expect(
+      lint(`<Card variant="subtle">
+        <Badge variant="neutral">2</Badge>
+        <Avatar variant="muted">M</Avatar>
+        <div className="bg-muted">well</div>
+        <Card variant="filled" padding="sm"><pre className="text-muted-foreground">x</pre></Card>
+      </Card>`),
+    ).toHaveLength(0);
+    expect(
+      lint(
+        `<Card variant="filled"><p className="text-muted-foreground bg-muted-foreground/20">x</p></Card>`,
+      ),
+    ).toHaveLength(0);
+  });
+});
diff --git a/frontend/src/settings/Teams.tsx b/frontend/src/settings/Teams.tsx
index 30a31de4..de14fb5c 100644
--- a/frontend/src/settings/Teams.tsx
+++ b/frontend/src/settings/Teams.tsx
@@ -543,6 +543,8 @@ export default function Teams() {
                 <Card
                   key={team.id}
                   asChild
+                  variant="filled"
+                  padding="lg"
                   interactive
                   className="group h-full"
                 >

From 20bcd9294259d8cdd259ccf76439166f4cc5c6a1 Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Sun, 27 Sep 2026 16:53:18 +0400
Subject: [PATCH 2/7] updated drawer

---
 frontend/DESIGN.md                            |  24 +-
 .../components/AgentPreviewSheet.test.tsx     | 101 +++++
 .../agents/components/AgentPreviewSheet.tsx   |  81 ++++
 .../src/agents/workflow/WorkflowBuilder.tsx   |  78 ++--
 .../agents/workflow/WorkflowPreview.test.tsx  | 134 ++++++
 .../src/agents/workflow/WorkflowPreview.tsx   | 405 +++++++++---------
 frontend/src/design/DesignSystem.tsx          |  68 +++
 7 files changed, 636 insertions(+), 255 deletions(-)
 create mode 100644 frontend/src/agents/components/AgentPreviewSheet.test.tsx
 create mode 100644 frontend/src/agents/components/AgentPreviewSheet.tsx
 create mode 100644 frontend/src/agents/workflow/WorkflowPreview.test.tsx

diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
index f45d45b1..0d776303 100644
--- a/frontend/DESIGN.md
+++ b/frontend/DESIGN.md
@@ -291,12 +291,12 @@ question: is it a **thing** you open, move, share or delete as a whole, or a
 **place** where you read or edit content? The fill marks objects; the border
 marks structure.
 
-| Role                 | Variant                                                   | Examples                                                                                          |
-| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Thing (a tile)       | `filled`, on a page or in a modal                         | agents, folders, sources, tools, custom models, teams, chunks, the shared agent card              |
-| Place (a panel)      | `subtle` on the page, `outline` on a card (modal, drawer) | the agent form's sections, chart panels, stat tiles, log tables, schedule rows, the agent preview |
-| Choice (picker tile) | `outline interactive`, or `OptionCard`                    | the Add tool tiles; selection is drawn by the border, so the border stays                         |
-| Well                 | `filled padding="sm"`                                     | code, a token to copy, run output, inside a panel (see Code blocks below)                         |
+| Role                 | Variant                                                                           | Examples                                                                                          |
+| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Thing (a tile)       | `filled`, on a page or in a modal                                                 | agents, folders, sources, tools, custom models, teams, chunks, the shared agent card              |
+| Place (a panel)      | `subtle` on the page or a right drawer, `outline` on a card (modal, bottom sheet) | the agent form's sections, chart panels, stat tiles, log tables, schedule rows, the agent preview |
+| Choice (picker tile) | `outline interactive`, or `OptionCard`                                            | the Add tool tiles; selection is drawn by the border, so the border stays                         |
+| Well                 | `filled padding="sm"`                                                             | code, a token to copy, run output, inside a panel (see Code blocks below)                         |
 
 - Layers go page → panel (border) → well (fill), or page → tile (fill).
   `subtle` and `outline` are one role on two surfaces; in light mode they
@@ -898,6 +898,17 @@ scroller) and the same blurred overlay. Modal, DialogContent and every Sheet sha
 `overlayScrim` in `lib/utils.ts` (`bg-black/25 backdrop-blur-xs
 dark:bg-black/50`).
 
+A right drawer (`SheetContent side="right"`) is on `bg-background`, like the
+page: its content paints no surface of its own, and panels in it are
+`subtle` (see Card surfaces). An agent is previewed in one shared drawer,
+`agents/components/AgentPreviewSheet`, for workflow and classic agents alike:
+`w-full sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]`, a `SheetTitle`
+and a one-line `SheetDescription` (the agent's name) in a header padded
+`pr-12` to clear the close X, an `info` Running badge while it answers, a
+`Separator`, then the preview. The workflow preview's Execution details and
+Artifacts rows are the answer's step-row recipe (see Alert), each step a
+`subtle sm` panel with its output in a `filled sm` well.
+
 Every phone bottom sheet has one shape: `bg-card`, 16px top corners, no top
 border, `max-h-sheet` (the visible viewport less the top safe-area inset and a
 3rem strip, so the scrim above it can always be tapped to close), and bottom
@@ -1184,6 +1195,7 @@ list stays reviewable.
 | `agents/workflow/WorkflowBuilder.tsx`                               | `shadcn/no-restyle`             | The "Learn more" links in the Set state and Condition nodes' 12px hints keep the sentence's size and weight (`text-xs font-normal` on `link inline`). Two disables.                                                                                                                                                                                                                                                                                                                             |
 | `components/MessageInput.tsx`                                       | `shadcn/no-restyle`             | The queued-send Cancel is a `link inline` inside the composer's 12px status line, so it takes the line's size (`text-xs`). One disable, beside the send button's.                                                                                                                                                                                                                                                                                                                               |
 | `settings/PersonalAccessTokens.tsx`                                 | `shadcn/no-restyle`             | Token scope chips are identifiers, so the `neutral` Badge is set in mono (`font-mono`). One disable.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `agents/workflow/WorkflowPreview.tsx`                               | `shadcn/no-restyle`             | A step's state changes (keys and values the app serialised) are `neutral` Badges set in mono (`font-mono`), like token scopes. One disable.                                                                                                                                                                                                                                                                                                                                                     |
 | `settings/traces/TraceChips.tsx`                                    | `shadcn/no-restyle`             | Trace stat chips (durations, counts) use tabular figures so they don't jitter between rows (`tabular-nums` on Badge). One disable.                                                                                                                                                                                                                                                                                                                                                              |
 | `modals/MCPServerModal.tsx`                                         | `shadcn/no-restyle`             | The authorization link inside the test-result Alert keeps the Alert's status colour (`text-current` on `link inline`). One disable (phase 11, 63g).                                                                                                                                                                                                                                                                                                                                             |
 | `components/MermaidRenderer.tsx`                                    | `shadcn/no-restyle`             | The zoom readout between − and + is a `link inline` Button on the `bg-black/70` overlay; it keeps the overlay's white 12px regular text (`text-xs font-normal text-current`). One disable, beside the two zoom-button ones above (phase 11, 63g).                                                                                                                                                                                                                                               |
diff --git a/frontend/src/agents/components/AgentPreviewSheet.test.tsx b/frontend/src/agents/components/AgentPreviewSheet.test.tsx
new file mode 100644
index 00000000..15e1f914
--- /dev/null
+++ b/frontend/src/agents/components/AgentPreviewSheet.test.tsx
@@ -0,0 +1,101 @@
+import { act } from 'react';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+import { createRoot, type Root } from 'react-dom/client';
+
+import AgentPreviewSheet from './AgentPreviewSheet';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('AgentPreviewSheet', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <AgentPreviewSheet
+          open
+          onOpenChange={() => undefined}
+          title="Preview"
+          description="Carrier onboarding FAQ"
+          actions={<span data-testid="action">Running</span>}
+        >
+          <div data-testid="body">Chat</div>
+        </AgentPreviewSheet>,
+      );
+    });
+  };
+
+  it('is a right Sheet at the workflow preview widths', async () => {
+    await render();
+    const content = document.querySelector<HTMLElement>(
+      '[data-slot="sheet-content"]',
+    )!;
+    expect(content.dataset.side).toBe('right');
+    expect(content.className).toContain('lg:max-w-[800px]');
+    expect(content.className).toContain('p-0');
+  });
+
+  it('titles the drawer with SheetTitle and SheetDescription', async () => {
+    await render();
+    expect(
+      document.querySelector('[data-slot="sheet-title"]')?.textContent,
+    ).toBe('Preview');
+    expect(
+      document.querySelector('[data-slot="sheet-description"]')?.textContent,
+    ).toBe('Carrier onboarding FAQ');
+  });
+
+  it('keeps header actions clear of the close button', async () => {
+    await render();
+    const action = document.querySelector('[data-testid="action"]')!;
+    const header = action.parentElement!;
+    // The X sits at top-2 right-2 (32px wide); pr-12 keeps 48px free.
+    expect(header.className).toContain('pr-12');
+    expect(
+      header.contains(document.querySelector('[data-slot="sheet-title"]')),
+    ).toBe(true);
+  });
+
+  // DESIGN maps "running" to info, as schedule runs do (was primary text).
+  it('shows a running run as an info badge in the header', async () => {
+    await act(async () => {
+      root.render(
+        <AgentPreviewSheet
+          open
+          onOpenChange={() => undefined}
+          title="Preview"
+          running
+        >
+          <div />
+        </AgentPreviewSheet>,
+      );
+    });
+    const badge = document.querySelector<HTMLElement>('[data-slot="badge"]')!;
+    expect(badge.dataset.variant).toBe('info');
+    expect(badge.textContent).toBe('agents.schedules.status.running');
+  });
+
+  it('renders the body under a separator on the sheet surface', async () => {
+    await render();
+    const body = document.querySelector('[data-testid="body"]')!;
+    expect(body.textContent).toBe('Chat');
+    expect(document.querySelector('[data-slot="separator"]')).not.toBeNull();
+    const content = document.querySelector('[data-slot="sheet-content"]')!;
+    expect(content.querySelector('.bg-card')).toBeNull();
+  });
+});
diff --git a/frontend/src/agents/components/AgentPreviewSheet.tsx b/frontend/src/agents/components/AgentPreviewSheet.tsx
new file mode 100644
index 00000000..18dcc8c4
--- /dev/null
+++ b/frontend/src/agents/components/AgentPreviewSheet.tsx
@@ -0,0 +1,81 @@
+import type { ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Badge } from '@/components/ui/badge';
+import { Separator } from '@/components/ui/separator';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetTitle,
+} from '@/components/ui/sheet';
+
+type AgentPreviewSheetProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The drawer's title, e.g. "Preview". */
+  title: string;
+  /** One muted line under the title: the agent's name. */
+  description?: string;
+  /** Shows an info "Running" badge while the preview is answering. */
+  running?: boolean;
+  /** Actions at the header's right end (New chat). */
+  actions?: ReactNode;
+  /** The preview itself; fills the rest of the drawer. */
+  children: ReactNode;
+};
+
+/**
+ * The drawer an agent is previewed in, for workflow and classic agents alike:
+ * a right Sheet with a title row, a rule, then the preview filling the rest.
+ *
+ * Args:
+ *   open: Whether the drawer is open.
+ *   onOpenChange: Called with the next open state (the X, Escape, the scrim).
+ *   title: The drawer's title.
+ *   description: A muted line under the title.
+ *   running: Whether the preview is answering; shows a Running badge.
+ *   actions: Nodes at the right end of the header, clear of the close button.
+ *   children: The preview body.
+ */
+export default function AgentPreviewSheet({
+  open,
+  onOpenChange,
+  title,
+  description,
+  running = false,
+  actions,
+  children,
+}: AgentPreviewSheetProps) {
+  const { t } = useTranslation();
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        className="w-full max-w-none p-0 sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]"
+      >
+        <div className="flex min-h-0 flex-1 flex-col">
+          {/* pr-12 keeps the header clear of the close X at top-2 right-2. */}
+          <div className="flex items-center gap-3 px-6 pt-6 pr-12 pb-4">
+            <div className="flex min-w-0 flex-1 flex-col gap-1">
+              <SheetTitle>{title}</SheetTitle>
+              {description && (
+                <SheetDescription className="truncate" title={description}>
+                  {description}
+                </SheetDescription>
+              )}
+            </div>
+            {running && (
+              <Badge variant="info">
+                {t('agents.schedules.status.running')}
+              </Badge>
+            )}
+            {actions}
+          </div>
+          <Separator />
+          <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/frontend/src/agents/workflow/WorkflowBuilder.tsx b/frontend/src/agents/workflow/WorkflowBuilder.tsx
index 830170c3..3a155584 100644
--- a/frontend/src/agents/workflow/WorkflowBuilder.tsx
+++ b/frontend/src/agents/workflow/WorkflowBuilder.tsx
@@ -72,7 +72,6 @@ import {
 } from '@/components/ui/select';
 import { SectionHeader } from '@/components/ui/section-header';
 import { SettingRow } from '@/components/ui/setting-row';
-import { Sheet, SheetContent } from '@/components/ui/sheet';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { cn } from '@/lib/utils';
@@ -90,6 +89,7 @@ import {
 import { getToolDisplayName } from '../../utils/toolUtils';
 import { agentEditPath, agentsListPath } from '../paths';
 import AgentPageHeader from '../AgentPageHeader';
+import AgentPreviewSheet from '../components/AgentPreviewSheet';
 import { Agent } from '../types';
 import { ConditionCase, WorkflowNode } from '../types/workflow';
 import {
@@ -122,6 +122,7 @@ import {
   StartNode,
 } from './nodes';
 import WorkflowPreview from './WorkflowPreview';
+import { selectWorkflowPreviewStatus } from './workflowPreviewSlice';
 
 import type { Model } from '../../models/types';
 
@@ -448,6 +449,7 @@ function WorkflowBuilderInner() {
   const navigate = useNavigate();
   const token = useSelector(selectToken);
   const sourceDocs = useSelector(selectSourceDocs);
+  const previewStatus = useSelector(selectWorkflowPreviewStatus);
   const { agentId } = useParams<{ agentId?: string }>();
   const [searchParams] = useSearchParams();
   const folderId = searchParams.get('folder_id');
@@ -3299,42 +3301,46 @@ function WorkflowBuilderInner() {
           </div>
         </div>
 
-        <Sheet open={showPreview} onOpenChange={setShowPreview}>
-          <SheetContent
-            side="right"
-            className="w-full max-w-none p-0 sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]"
-          >
-            <WorkflowPreview
-              workflowId={workflowId}
-              workflowData={{
-                name: workflowName,
-                description: workflowDescription,
-                nodes: nodes
-                  .filter((n) => n.type !== 'note')
-                  .map((n) => ({
-                    id: n.id,
-                    type: n.type as
-                      'start' | 'end' | 'agent' | 'state' | 'code',
-                    title: n.data.title || n.data.label || n.type,
-                    position: n.position,
-                    data:
-                      n.type === 'code'
-                        ? serializeCodeConfig(n.data.config)
-                        : n.type === 'agent'
-                          ? n.data.config
-                          : n.data,
-                  })),
-                edges: edges.map((e) => ({
-                  id: e.id,
-                  source: e.source,
-                  target: e.target,
-                  sourceHandle: e.sourceHandle || undefined,
-                  targetHandle: e.targetHandle || undefined,
+        <AgentPreviewSheet
+          open={showPreview}
+          onOpenChange={setShowPreview}
+          title={t('agents.form.sections.preview')}
+          description={
+            workflowDescription
+              ? `${workflowName} · ${workflowDescription}`
+              : workflowName
+          }
+          running={previewStatus === 'loading'}
+        >
+          <WorkflowPreview
+            workflowId={workflowId}
+            workflowData={{
+              name: workflowName,
+              description: workflowDescription,
+              nodes: nodes
+                .filter((n) => n.type !== 'note')
+                .map((n) => ({
+                  id: n.id,
+                  type: n.type as 'start' | 'end' | 'agent' | 'state' | 'code',
+                  title: n.data.title || n.data.label || n.type,
+                  position: n.position,
+                  data:
+                    n.type === 'code'
+                      ? serializeCodeConfig(n.data.config)
+                      : n.type === 'agent'
+                        ? n.data.config
+                        : n.data,
                 })),
-              }}
-            />
-          </SheetContent>
-        </Sheet>
+              edges: edges.map((e) => ({
+                id: e.id,
+                source: e.source,
+                target: e.target,
+                sourceHandle: e.sourceHandle || undefined,
+                targetHandle: e.targetHandle || undefined,
+              })),
+            }}
+          />
+        </AgentPreviewSheet>
         <ConfirmationModal
           message={
             workflowName
diff --git a/frontend/src/agents/workflow/WorkflowPreview.test.tsx b/frontend/src/agents/workflow/WorkflowPreview.test.tsx
new file mode 100644
index 00000000..186ab5b4
--- /dev/null
+++ b/frontend/src/agents/workflow/WorkflowPreview.test.tsx
@@ -0,0 +1,134 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => null,
+  useDispatch: () => vi.fn(),
+}));
+
+vi.mock('./WorkflowRunArtifacts', () => ({ default: () => null }));
+
+import { ExecutionDetails, RunArtifactsSection } from './WorkflowPreview';
+import type { WorkflowNode } from '../types/workflow';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const nodes = [
+  {
+    id: 'n1',
+    type: 'agent',
+    title: 'Summarise',
+    position: { x: 0, y: 0 },
+    data: {},
+  },
+] as unknown as WorkflowNode[];
+
+const steps = [
+  {
+    nodeId: 'n1',
+    nodeType: 'agent',
+    nodeTitle: 'Summarise',
+    status: 'completed',
+    output: 'Three carriers expire this month.',
+    stateDelta: { region: 'EU', query: 'ignored' },
+  },
+] as never;
+
+describe('WorkflowPreview execution sections', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const renderDetails = async (isOpen = true) => {
+    await act(async () => {
+      root.render(
+        <ExecutionDetails
+          steps={steps}
+          nodes={nodes}
+          isOpen={isOpen}
+          onToggle={() => undefined}
+        />,
+      );
+    });
+  };
+
+  // The answer's step-row recipe (AnswerFlow): ghost sm at ml-3.5, a muted
+  // icon, muted text, and a chevron that turns while open.
+  it('draws the Execution details toggle as an answer step row', async () => {
+    await renderDetails();
+    const toggle = container.querySelector<HTMLButtonElement>('button')!;
+    expect(toggle.dataset.variant).toBe('ghost');
+    expect(toggle.dataset.size).toBe('sm');
+    expect(toggle.getAttribute('aria-expanded')).toBe('true');
+    expect(toggle.className).toContain('ml-3.5');
+    const icons = toggle.querySelectorAll('svg');
+    expect(icons[0].getAttribute('class')).toContain('text-muted-foreground');
+    expect(icons[icons.length - 1].getAttribute('class')).toContain(
+      'rotate-180',
+    );
+    expect(toggle.querySelector('p')).toBeNull();
+  });
+
+  it('draws each step as a subtle panel with its output in a filled well', async () => {
+    await renderDetails();
+    const step = container.querySelector<HTMLElement>(
+      '[data-slot="card"][data-variant="subtle"]',
+    )!;
+    expect(step.dataset.padding).toBe('sm');
+    const well = step.querySelector<HTMLElement>(
+      '[data-slot="card"][data-variant="filled"]',
+    )!;
+    expect(well.dataset.padding).toBe('sm');
+    expect(well.textContent).toContain('Three carriers expire this month.');
+    // No hand-rolled muted boxes: a muted box in a muted box disappears.
+    expect(
+      container.querySelector(
+        'div.bg-muted:not([data-slot="card"]), span.bg-muted',
+      ),
+    ).toBeNull();
+  });
+
+  it('shows state changes as mono neutral badges, without query', async () => {
+    await renderDetails();
+    const badges = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="badge"]'),
+    );
+    expect(badges).toHaveLength(1);
+    expect(badges[0].dataset.variant).toBe('neutral');
+    expect(badges[0].className).toContain('font-mono');
+    expect(badges[0].textContent).toContain('region');
+    expect(badges[0].textContent).toContain('EU');
+  });
+
+  it('draws the Artifacts toggle as the same step row', async () => {
+    await act(async () => {
+      root.render(
+        <RunArtifactsSection
+          workflowRunId="run-1"
+          isOpen={false}
+          onToggle={() => undefined}
+        />,
+      );
+    });
+    const toggle = container.querySelector<HTMLButtonElement>('button')!;
+    expect(toggle.dataset.variant).toBe('ghost');
+    expect(toggle.dataset.size).toBe('sm');
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+    expect(toggle.className).toContain('ml-3.5');
+    expect(toggle.querySelector('p')).toBeNull();
+  });
+});
diff --git a/frontend/src/agents/workflow/WorkflowPreview.tsx b/frontend/src/agents/workflow/WorkflowPreview.tsx
index b8fc8429..d15d4664 100644
--- a/frontend/src/agents/workflow/WorkflowPreview.tsx
+++ b/frontend/src/agents/workflow/WorkflowPreview.tsx
@@ -11,7 +11,6 @@ import {
   Flag,
   GitBranch,
   type LucideIcon,
-  MessageSquare,
   Play,
   StickyNote,
   Workflow,
@@ -21,9 +20,11 @@ import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
 import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { EmptyState } from '@/components/ui/empty-state';
 import { SectionHeader } from '@/components/ui/section-header';
-import { SheetTitle } from '@/components/ui/sheet';
 import { Spinner } from '@/components/ui/spinner';
 import {
   MessageScroller,
@@ -94,7 +95,64 @@ const NODE_COLORS: Record<string, string> = {
   code: 'text-info',
 };
 
-function ExecutionDetails({
+/**
+ * A step row under an answer, like Reasoning in chat (AnswerFlow): a ghost
+ * button whose muted icon sits on the answer's ml-6 column, then the panel it
+ * opens in place on that column.
+ */
+function StepDisclosure({
+  icon: Icon,
+  label,
+  count,
+  isOpen,
+  onToggle,
+  children,
+}: {
+  icon: LucideIcon;
+  label: string;
+  count?: string;
+  isOpen: boolean;
+  onToggle: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="my-2 flex w-full flex-col">
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        onClick={onToggle}
+        aria-expanded={isOpen}
+        // ml-3.5 plus size sm's own has-[>svg]:px-2.5 puts the icon on the
+        // answer's ml-6 text column.
+        className="ml-3.5 w-fit max-w-full justify-start"
+      >
+        <Icon className="text-muted-foreground" aria-hidden />
+        <span className="text-muted-foreground min-w-0 truncate">{label}</span>
+        {count && (
+          <span className="text-muted-foreground/70 font-normal">{count}</span>
+        )}
+        <ChevronDown
+          aria-hidden
+          className={cn(
+            'text-muted-foreground shrink-0 transition-transform duration-200',
+            isOpen && 'rotate-180',
+          )}
+        />
+      </Button>
+      <div
+        className={cn(
+          'mr-5 ml-6 grid transition-[grid-template-rows,opacity] duration-300 ease-out',
+          isOpen ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0',
+        )}
+      >
+        <div className="min-h-0 overflow-hidden">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+export function ExecutionDetails({
   steps,
   nodes,
   isOpen,
@@ -122,153 +180,121 @@ function ExecutionDetails({
   };
 
   return (
-    <div className="mb-4 flex w-full flex-col flex-wrap items-start self-start lg:flex-nowrap">
-      <div className="my-2 flex flex-row items-center justify-center gap-3">
-        <div className="flex h-[26px] w-[30px] items-center justify-center">
-          <Workflow className="text-muted-foreground size-5" />
-        </div>
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          onClick={onToggle}
-          className="-ml-2.5"
-        >
-          <p className="text-base font-semibold">
-            {t('agents.workflow.preview.executionDetails')}
-            <span className="text-muted-foreground ml-1.5 text-sm font-normal">
-              {t('agents.workflow.preview.stepCount', {
-                count: completedSteps.length,
-              })}
-            </span>
-          </p>
-          <ChevronDown
-            className={cn(
-              'transition-transform duration-200',
-              isOpen && 'rotate-180',
-            )}
-          />
-        </Button>
-      </div>
-      <div
-        className={cn(
-          'ml-3 grid w-full transition-[grid-template-rows,opacity] duration-300 ease-out',
-          isOpen ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0',
-        )}
-      >
-        <div className="overflow-hidden">
-          <div className="flex flex-col gap-2 pr-2">
-            {completedSteps.map((step, stepIndex) => {
-              const node = nodes.find((n) => n.id === step.nodeId);
-              const displayName =
-                node?.title || node?.data?.title || step.nodeTitle;
-              const StepIcon = NODE_ICONS[step.nodeType] || Circle;
-              const stateVars = step.stateDelta
-                ? Object.entries(step.stateDelta).filter(
-                    ([key]) => !['query', 'chat_history'].includes(key),
-                  )
-                : [];
+    <StepDisclosure
+      icon={Workflow}
+      label={t('agents.workflow.preview.executionDetails')}
+      count={t('agents.workflow.preview.stepCount', {
+        count: completedSteps.length,
+      })}
+      isOpen={isOpen}
+      onToggle={onToggle}
+    >
+      <div className="flex flex-col gap-2 pt-1">
+        {completedSteps.map((step, stepIndex) => {
+          const node = nodes.find((n) => n.id === step.nodeId);
+          const displayName =
+            node?.title || node?.data?.title || step.nodeTitle;
+          const StepIcon = NODE_ICONS[step.nodeType] || Circle;
+          const stateVars = step.stateDelta
+            ? Object.entries(step.stateDelta).filter(
+                ([key]) => !['query', 'chat_history'].includes(key),
+              )
+            : [];
 
-              const truncateText = (text: string, maxLength: number) => {
-                if (text.length <= maxLength) return text;
-                return text.slice(0, maxLength) + '...';
-              };
-              const hasOutput =
-                step.output !== undefined &&
-                step.output !== null &&
-                formatValue(step.output) !== '';
-              const formattedOutput = hasOutput ? formatValue(step.output) : '';
+          const truncateText = (text: string, maxLength: number) => {
+            if (text.length <= maxLength) return text;
+            return text.slice(0, maxLength) + '...';
+          };
+          const hasOutput =
+            step.output !== undefined &&
+            step.output !== null &&
+            formatValue(step.output) !== '';
+          const formattedOutput = hasOutput ? formatValue(step.output) : '';
 
-              return (
-                <div
-                  key={step.nodeId}
-                  ref={(el) => {
-                    if (el && stepRefs) stepRefs.current.set(step.nodeId, el);
-                  }}
-                  className="bg-muted rounded-xl p-3"
-                >
-                  <div className="flex items-center gap-2 text-sm">
-                    <span className="text-muted-foreground flex size-5 shrink-0 items-center justify-center text-xs font-medium">
-                      {stepIndex + 1}.
-                    </span>
-                    <div
-                      className={cn(
-                        'shrink-0',
-                        NODE_COLORS[step.nodeType] || NODE_COLORS.state,
-                      )}
-                    >
-                      <StepIcon className="size-3" />
-                    </div>
-                    <span className="text-foreground min-w-0 truncate font-medium">
-                      {displayName}
-                    </span>
-                    <div className="ml-auto shrink-0">
-                      {step.status === 'completed' && (
-                        <CircleCheck className="text-success size-4" />
-                      )}
-                      {step.status === 'failed' && (
-                        <CircleX className="text-destructive size-4" />
-                      )}
-                    </div>
-                  </div>
-                  {(hasOutput || step.error || stateVars.length > 0) && (
-                    <div className="mt-3 flex flex-col gap-2 text-sm">
-                      {hasOutput && (
-                        <div className="bg-muted rounded-lg p-2">
-                          <span className="text-muted-foreground font-medium">
-                            {t('agents.workflow.preview.outputLabel')}{' '}
-                          </span>
-                          <span className="text-foreground wrap-break-word whitespace-pre-wrap">
-                            {truncateText(formattedOutput, 300)}
-                          </span>
-                        </div>
-                      )}
-                      {step.error && (
-                        <Alert variant="destructive" role="status">
-                          <CircleAlert />
-                          <AlertDescription>
-                            <span className="font-medium">
-                              {t('agents.workflow.preview.errorLabel')}{' '}
-                            </span>
-                            <span className="wrap-break-word whitespace-pre-wrap">
-                              {step.error}
-                            </span>
-                          </AlertDescription>
-                        </Alert>
-                      )}
-                      {stateVars.length > 0 && (
-                        <div className="flex flex-wrap gap-2">
-                          {stateVars.map(([key, value]) => (
-                            <span
-                              key={key}
-                              className="bg-muted inline-flex items-center rounded-lg px-2 py-1 text-xs"
-                            >
-                              <span className="text-muted-foreground max-w-[100px] truncate font-medium">
-                                {key}:
-                              </span>
-                              <span
-                                className="text-foreground ml-1 max-w-[200px] truncate"
-                                title={formatValue(value)}
-                              >
-                                {truncateText(formatValue(value), 50)}
-                              </span>
-                            </span>
-                          ))}
-                        </div>
-                      )}
-                    </div>
+          // A step is a place you read inside: a subtle panel on the
+          // drawer's background, with its output in a filled well.
+          return (
+            <Card
+              key={step.nodeId}
+              ref={(el: HTMLDivElement | null) => {
+                if (el && stepRefs) stepRefs.current.set(step.nodeId, el);
+              }}
+              variant="subtle"
+              padding="sm"
+            >
+              <div className="flex items-center gap-2">
+                <span className="text-muted-foreground flex size-5 shrink-0 items-center justify-center text-xs font-medium">
+                  {stepIndex + 1}.
+                </span>
+                <StepIcon
+                  aria-hidden
+                  className={cn(
+                    'size-3 shrink-0',
+                    NODE_COLORS[step.nodeType] || NODE_COLORS.state,
+                  )}
+                />
+                <span className="text-foreground min-w-0 truncate font-medium">
+                  {displayName}
+                </span>
+                <div className="ml-auto shrink-0">
+                  {step.status === 'completed' && (
+                    <CircleCheck className="text-success size-4" />
+                  )}
+                  {step.status === 'failed' && (
+                    <CircleX className="text-destructive size-4" />
                   )}
                 </div>
-              );
-            })}
-          </div>
-        </div>
+              </div>
+              {hasOutput && (
+                <Card variant="filled" padding="sm">
+                  <p className="wrap-break-word whitespace-pre-wrap">
+                    <span className="text-muted-foreground font-medium">
+                      {t('agents.workflow.preview.outputLabel')}{' '}
+                    </span>
+                    <span className="text-foreground">
+                      {truncateText(formattedOutput, 300)}
+                    </span>
+                  </p>
+                </Card>
+              )}
+              {step.error && (
+                <Alert variant="destructive" role="status">
+                  <CircleAlert />
+                  <AlertDescription>
+                    <span className="font-medium">
+                      {t('agents.workflow.preview.errorLabel')}{' '}
+                    </span>
+                    <span className="wrap-break-word whitespace-pre-wrap">
+                      {step.error}
+                    </span>
+                  </AlertDescription>
+                </Alert>
+              )}
+              {stateVars.length > 0 && (
+                <div className="flex flex-wrap gap-2">
+                  {stateVars.map(([key, value]) => (
+                    // eslint-disable-next-line shadcn/no-restyle -- state keys and values are serialised by the app, so the chip is set in mono
+                    <Badge key={key} variant="neutral" className="font-mono">
+                      <span className="max-w-[100px] truncate">{key}:</span>
+                      <span
+                        className="text-foreground max-w-[200px] truncate"
+                        title={formatValue(value)}
+                      >
+                        {truncateText(formatValue(value), 50)}
+                      </span>
+                    </Badge>
+                  ))}
+                </div>
+              )}
+            </Card>
+          );
+        })}
       </div>
-    </div>
+    </StepDisclosure>
   );
 }
 
-function RunArtifactsSection({
+export function RunArtifactsSection({
   workflowRunId,
   isOpen,
   onToggle,
@@ -281,47 +307,21 @@ function RunArtifactsSection({
 }) {
   const { t } = useTranslation();
   return (
-    <div className="mb-4 flex w-full flex-col flex-wrap items-start self-start lg:flex-nowrap">
-      <div className="my-2 flex flex-row items-center justify-center gap-3">
-        <div className="flex h-[26px] w-[30px] items-center justify-center">
-          <FileBox className="text-muted-foreground size-5" />
-        </div>
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          onClick={onToggle}
-          className="-ml-2.5"
-        >
-          <p className="text-base font-semibold">
-            {t('agents.workflow.preview.artifacts')}
-          </p>
-          <ChevronDown
-            className={cn(
-              'transition-transform duration-200',
-              isOpen && 'rotate-180',
-            )}
+    <StepDisclosure
+      icon={FileBox}
+      label={t('agents.workflow.preview.artifacts')}
+      isOpen={isOpen}
+      onToggle={onToggle}
+    >
+      <div className="max-h-[480px] overflow-y-auto pt-1">
+        {isOpen && (
+          <WorkflowRunArtifacts
+            workflowRunId={workflowRunId}
+            inProgress={runInProgress}
           />
-        </Button>
-      </div>
-      <div
-        className={cn(
-          'ml-3 grid w-full transition-[grid-template-rows,opacity] duration-300 ease-out',
-          isOpen ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0',
         )}
-      >
-        <div className="overflow-hidden">
-          <div className="max-h-[480px] overflow-y-auto pr-2">
-            {isOpen && (
-              <WorkflowRunArtifacts
-                workflowRunId={workflowRunId}
-                inProgress={runInProgress}
-              />
-            )}
-          </div>
-        </div>
       </div>
-    </div>
+    </StepDisclosure>
   );
 }
 
@@ -616,28 +616,7 @@ export default function WorkflowPreview({
     queries.length > 0 ? queries[queries.length - 1].executionSteps || [] : [];
 
   return (
-    <div className="bg-card flex h-full flex-col">
-      <div className="border-border flex h-[77px] items-center justify-between border-b px-6">
-        <div className="flex items-center gap-3">
-          <div className="bg-muted text-muted-foreground flex items-center justify-center rounded-full p-3">
-            <Play className="size-4" />
-          </div>
-          <div>
-            <SheetTitle>{t('agents.form.sections.preview')}</SheetTitle>
-            <p className="text-muted-foreground max-w-md truncate text-xs">
-              {workflowData.name}
-              {workflowData.description && ` - ${workflowData.description}`}
-            </p>
-          </div>
-        </div>
-        {status === 'loading' && (
-          <span className="text-primary flex items-center gap-1 text-xs">
-            <Spinner size="xs" />
-            {t('agents.schedules.status.running')}
-          </span>
-        )}
-      </div>
-
+    <div className="flex h-full min-h-0 flex-col">
       <div className="flex min-h-0 flex-1">
         <div className="border-border flex w-64 shrink-0 flex-col border-r">
           <div className="flex items-center justify-between px-4 py-3">
@@ -662,13 +641,12 @@ export default function WorkflowPreview({
         <div className="flex min-w-0 flex-1 flex-col">
           <div className="relative min-h-0 flex-1">
             {queries.length === 0 ? (
-              <div className="flex h-full flex-col items-center justify-center px-4">
-                <div className="bg-muted mb-2 flex size-14 shrink-0 items-center justify-center rounded-xl">
-                  <MessageSquare className="text-muted-foreground size-6" />
-                </div>
-                <p className="text-foreground text-xl font-semibold">
-                  {t('agents.workflow.preview.emptyTitle')}
-                </p>
+              <div className="flex h-full items-center justify-center px-4">
+                <EmptyState
+                  size="sm"
+                  illustration="none"
+                  title={t('agents.workflow.preview.emptyTitle')}
+                />
               </div>
             ) : (
               <MessageScrollerProvider autoScroll>
@@ -788,11 +766,12 @@ export default function WorkflowPreview({
               </MessageScrollerProvider>
             )}
           </div>
-          <div className="bg-card flex w-full flex-col gap-2 px-4 pt-2 pb-4">
+          <div className="flex w-full flex-col gap-2 px-4 pt-2 pb-4">
             {sendBlockedMessage && (
-              <p className="text-destructive text-xs" role="alert">
-                {t(sendBlockedMessage)}
-              </p>
+              <Alert variant="destructive">
+                <CircleAlert />
+                <AlertDescription>{t(sendBlockedMessage)}</AlertDescription>
+              </Alert>
             )}
             <MessageInput
               onSubmit={(text) => handleQuestionSubmission(text)}
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
index 7b936af2..44315656 100644
--- a/frontend/src/design/DesignSystem.tsx
+++ b/frontend/src/design/DesignSystem.tsx
@@ -173,8 +173,46 @@ import {
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { TimePicker } from '@/components/ui/time-picker';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import AgentPreviewSheet from '../agents/components/AgentPreviewSheet';
+import type { WorkflowNode } from '../agents/types/workflow';
+import {
+  ExecutionDetails,
+  RunArtifactsSection,
+} from '../agents/workflow/WorkflowPreview';
+import type { WorkflowExecutionStep } from '../agents/workflow/workflowPreviewSlice';
 import { useDarkTheme } from '../hooks';
 
+// Sample run for the Agent preview drawer example.
+const DEMO_WORKFLOW_NODES = [
+  { id: 'd1', type: 'agent', title: 'Find expiring certificates' },
+  { id: 'd2', type: 'state', title: 'Set region' },
+  { id: 'd3', type: 'agent', title: 'Draft reminders' },
+] as unknown as WorkflowNode[];
+
+const DEMO_WORKFLOW_STEPS = [
+  {
+    nodeId: 'd1',
+    nodeType: 'agent',
+    nodeTitle: 'Find expiring certificates',
+    status: 'completed',
+    output: 'Three carriers have certificates expiring before 31 October.',
+  },
+  {
+    nodeId: 'd2',
+    nodeType: 'state',
+    nodeTitle: 'Set region',
+    status: 'completed',
+    stateDelta: { region: 'EU', carriers: ['Halvorsen', 'Nordline'] },
+  },
+  {
+    nodeId: 'd3',
+    nodeType: 'agent',
+    nodeTitle: 'Draft reminders',
+    status: 'failed',
+    error: 'The email tool timed out after 30 s.',
+  },
+] as unknown as WorkflowExecutionStep[];
+
 /**
  * Dev-only style guide, served at /design. It renders every component in
  * src/components/ui with the variants DESIGN.md documents as the defaults,
@@ -422,6 +460,8 @@ export default function DesignSystem() {
   const [agentType, setAgentType] = useState<'classic' | 'workflow'>('classic');
   const [toolOn, setToolOn] = useState(false);
   const [sectionOpen, setSectionOpen] = useState(false);
+  const [agentPreviewOpen, setAgentPreviewOpen] = useState(false);
+  const [demoStepsOpen, setDemoStepsOpen] = useState(true);
   const [scopes, setScopes] = useState<string[]>(['agents:read']);
   const [tokenLimit, setTokenLimit] = useState(true);
   const [saving, setSaving] = useState(false);
@@ -2621,6 +2661,34 @@ export default function DesignSystem() {
                   </SheetHeader>
                 </SheetContent>
               </Sheet>
+              <Button
+                variant="outline"
+                onClick={() => setAgentPreviewOpen(true)}
+                data-testid="ds-agent-preview"
+              >
+                Agent preview
+              </Button>
+              <AgentPreviewSheet
+                open={agentPreviewOpen}
+                onOpenChange={setAgentPreviewOpen}
+                title="Preview"
+                description="Carrier compliance workflow · Checks certificates weekly"
+                running
+              >
+                <div className="flex min-h-0 flex-1 flex-col overflow-y-auto py-4">
+                  <ExecutionDetails
+                    steps={DEMO_WORKFLOW_STEPS}
+                    nodes={DEMO_WORKFLOW_NODES}
+                    isOpen={demoStepsOpen}
+                    onToggle={() => setDemoStepsOpen(!demoStepsOpen)}
+                  />
+                  <RunArtifactsSection
+                    workflowRunId="demo"
+                    isOpen={false}
+                    onToggle={() => undefined}
+                  />
+                </div>
+              </AgentPreviewSheet>
               <Sheet>
                 <SheetTrigger asChild>
                   <Button variant="outline">Open bottom sheet</Button>

From d4c97a49cec2874aa745a665762f5c37b33e1d6e Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Sun, 27 Sep 2026 19:45:05 +0400
Subject: [PATCH 3/7] Agent menu in new style

---
 docsgpt/api/user/schedules/routes.py          |   49 +
 .../storage/db/repositories/schedule_runs.py  |   73 ++
 frontend/DESIGN.md                            |  497 ++++---
 frontend/eslint.config.js                     |  121 +-
 frontend/eslint/design-rules.d.ts             |    3 +
 frontend/eslint/design-rules.js               |   92 ++
 frontend/scripts/design-lint-report.mjs       |   16 +-
 frontend/src/Navigation.tsx                   |    7 +-
 frontend/src/agents/AgentLogs.test.tsx        |   73 ++
 frontend/src/agents/AgentLogs.tsx             |   28 +-
 frontend/src/agents/AgentPageHeader.tsx       |    9 +-
 frontend/src/agents/AgentPreview.tsx          |   22 +-
 frontend/src/agents/NewAgent.test.tsx         |  237 +++-
 frontend/src/agents/NewAgent.tsx              | 1154 +++++++++--------
 .../components/AgentPageToolbar.test.tsx      |   67 +
 .../agents/components/AgentPageToolbar.tsx    |   94 ++
 .../components/AgentPreviewSheet.test.tsx     |   19 +
 .../agents/components/AgentPreviewSheet.tsx   |   22 +-
 .../components/GuardrailEvents.test.tsx       |    8 +
 .../src/agents/components/GuardrailEvents.tsx |    2 +-
 .../components/GuardrailsSection.test.tsx     |   22 +
 .../agents/components/GuardrailsSection.tsx   |   93 +-
 .../agents/schedules/RunDetailDrawer.test.tsx |    8 +-
 .../src/agents/schedules/RunDetailDrawer.tsx  |   20 +-
 frontend/src/agents/schedules/RunLog.test.tsx |   69 +
 frontend/src/agents/schedules/RunLog.tsx      |   88 +-
 .../src/agents/schedules/ScheduleRow.test.tsx |  138 ++
 frontend/src/agents/schedules/ScheduleRow.tsx |  257 ++++
 .../agents/schedules/SchedulesView.test.tsx   |  170 +++
 .../src/agents/schedules/SchedulesView.tsx    |  415 +++---
 .../agents/schedules/schedulesSlice.test.ts   |   10 +
 .../src/agents/schedules/schedulesSlice.ts    |    9 +-
 frontend/src/agents/types/schedule.ts         |   13 +
 .../src/agents/workflow/WorkflowBuilder.tsx   |   50 +-
 .../agents/workflow/WorkflowMiniMap.test.tsx  |    8 +-
 .../src/agents/workflow/WorkflowPreview.tsx   |    7 +-
 .../workflow/components/PromptTextArea.tsx    |    2 +-
 frontend/src/api/endpoints.ts                 |    2 +
 .../src/api/services/schedulesService.test.ts |   32 +
 frontend/src/api/services/schedulesService.ts |   18 +
 .../src/components/ArtifactSidebar.test.tsx   |   25 +
 frontend/src/components/ArtifactSidebar.tsx   |   34 +-
 frontend/src/components/Chunks.test.tsx       |   12 +
 frontend/src/components/Chunks.tsx            |    4 +-
 frontend/src/components/ConnectorTree.tsx     |    7 -
 frontend/src/components/FileUpload.test.tsx   |   22 +
 frontend/src/components/FileUpload.tsx        |   35 +-
 frontend/src/components/MermaidRenderer.tsx   |   29 +-
 frontend/src/components/MessageInput.tsx      |    2 +-
 frontend/src/components/PageToolbar.test.tsx  |    9 +
 frontend/src/components/PageToolbar.tsx       |    6 +-
 .../src/components/SkeletonLoader.test.tsx    |   58 +
 frontend/src/components/SkeletonLoader.tsx    |   74 +-
 .../message-input/AttachFileButton.tsx        |    2 +-
 .../components/message-input/MicButton.tsx    |    1 -
 .../message-input/SourcesTrigger.tsx          |   16 +-
 .../components/message-input/ToolsTrigger.tsx |    2 +-
 .../message-input/composerControls.test.tsx   |   55 +
 frontend/src/components/ui/button.tsx         |    2 +-
 .../src/components/ui/dropdown-menu.test.tsx  |   14 +
 frontend/src/components/ui/dropdown-menu.tsx  |   16 +-
 frontend/src/components/ui/dropzone.test.tsx  |   20 +
 frontend/src/components/ui/dropzone.tsx       |   54 +-
 frontend/src/components/ui/modal.test.tsx     |    3 +
 frontend/src/components/ui/modal.tsx          |   10 +-
 .../src/components/ui/multi-select.test.tsx   |   11 +-
 frontend/src/components/ui/multi-select.tsx   |    6 +-
 frontend/src/components/ui/sheet.test.tsx     |   35 +
 frontend/src/components/ui/sheet.tsx          |   35 +-
 frontend/src/components/ui/table.test.tsx     |   45 +-
 frontend/src/components/ui/table.tsx          |   21 +-
 frontend/src/components/ui/toast.tsx          |    4 +-
 frontend/src/components/ui/tooltip.tsx        |    2 +-
 .../conversation/ConversationBubble.test.tsx  |    8 +-
 .../src/conversation/ConversationBubble.tsx   |   20 +-
 frontend/src/conversation/MarkdownAnswer.tsx  |   69 +-
 frontend/src/design/DesignSystem.tsx          |  104 +-
 frontend/src/design/designRules.lint.test.ts  |   88 ++
 frontend/src/locale/de.json                   |   57 +-
 frontend/src/locale/en.json                   |   55 +-
 frontend/src/locale/es.json                   |   57 +-
 frontend/src/locale/jp.json                   |   57 +-
 frontend/src/locale/ru.json                   |   63 +-
 frontend/src/locale/zh-TW.json                |   57 +-
 frontend/src/locale/zh.json                   |   57 +-
 frontend/src/navigation/SectionPageHeader.tsx |   46 +-
 frontend/src/navigation/SectionPills.tsx      |    7 +-
 frontend/src/navigation/SectionShell.test.tsx |   41 +
 frontend/src/navigation/SectionShell.tsx      |   16 +-
 frontend/src/settings/Prompts.test.tsx        |   21 +
 frontend/src/settings/Prompts.tsx             |   25 +-
 frontend/src/settings/RemoteDeviceConfig.tsx  |    2 +-
 frontend/src/settings/Sources.tsx             |    1 -
 frontend/src/settings/ToolConfig.test.tsx     |    4 +-
 frontend/src/settings/ToolConfig.tsx          |   18 +-
 frontend/src/settings/traces/TraceSheet.tsx   |    3 +-
 frontend/src/upload/Upload.test.tsx           |  128 ++
 frontend/src/upload/Upload.tsx                |   99 +-
 frontend/src/utils/dateTimeUtils.test.ts      |   17 +
 frontend/src/utils/dateTimeUtils.ts           |   21 +-
 tests/api/user/test_schedules_routes.py       |  133 ++
 .../db/repositories/test_schedule_runs.py     |   87 ++
 102 files changed, 4476 insertions(+), 1580 deletions(-)
 create mode 100644 frontend/eslint/design-rules.d.ts
 create mode 100644 frontend/eslint/design-rules.js
 create mode 100644 frontend/src/agents/AgentLogs.test.tsx
 create mode 100644 frontend/src/agents/components/AgentPageToolbar.test.tsx
 create mode 100644 frontend/src/agents/components/AgentPageToolbar.tsx
 create mode 100644 frontend/src/agents/schedules/RunLog.test.tsx
 create mode 100644 frontend/src/agents/schedules/ScheduleRow.test.tsx
 create mode 100644 frontend/src/agents/schedules/ScheduleRow.tsx
 create mode 100644 frontend/src/agents/schedules/SchedulesView.test.tsx
 create mode 100644 frontend/src/api/services/schedulesService.test.ts
 create mode 100644 frontend/src/components/SkeletonLoader.test.tsx
 create mode 100644 frontend/src/components/message-input/composerControls.test.tsx
 create mode 100644 frontend/src/design/designRules.lint.test.ts
 create mode 100644 frontend/src/navigation/SectionShell.test.tsx

diff --git a/docsgpt/api/user/schedules/routes.py b/docsgpt/api/user/schedules/routes.py
index 6f2d259a..b63e39a3 100644
--- a/docsgpt/api/user/schedules/routes.py
+++ b/docsgpt/api/user/schedules/routes.py
@@ -317,6 +317,55 @@ class AgentSchedules(Resource):
         return _ok({"schedule": _format_schedule(created)}, status=201)
 
 
+@schedules_ns.route("/agents/<string:agent_id>/schedules/stats")
+class AgentScheduleStats(Resource):
+    @api.doc(
+        description="Run stats for an agent's schedules over a recent window.",
+        params={"days": "Window in days (default 30, clamped to 1..365)"},
+    )
+    @_safe_route
+    def get(self, agent_id: str):
+        """Return run count, failures, tokens and latest failure for an agent.
+
+        Args:
+            agent_id: Agent id from the URL.
+
+        Returns:
+            A Flask response with ``days``, ``runs``, ``failed``, ``tokens``
+            and ``latest_failure`` (or an error envelope).
+        """
+        user_id = _user_id()
+        if not user_id:
+            return _err("unauthorized", 401)
+        agent = _agent_owned(agent_id, user_id)
+        if agent is None:
+            return _err("agent not found", 404)
+        try:
+            days = max(1, min(int(request.args.get("days", 30)), 365))
+        except (TypeError, ValueError):
+            days = 30
+        try:
+            with db_readonly() as conn:
+                stats = ScheduleRunsRepository(conn).stats_for_agent(
+                    str(agent["id"]), user_id, days=days,
+                )
+        except Exception as exc:
+            current_app.logger.error(
+                "schedule stats failed: %s", exc, exc_info=True,
+            )
+            return _err("internal error", 500)
+        latest = stats.get("latest_failure")
+        return _ok(
+            {
+                "days": days,
+                "runs": stats["runs"],
+                "failed": stats["failed"],
+                "tokens": stats["tokens"],
+                "latest_failure": _format_run(latest) if latest else None,
+            }
+        )
+
+
 @schedules_ns.route("/schedules/<string:schedule_id>")
 class ScheduleResource(Resource):
     @api.doc(description="Get schedule by id.")
diff --git a/docsgpt/storage/db/repositories/schedule_runs.py b/docsgpt/storage/db/repositories/schedule_runs.py
index 22fb1d9c..95311d45 100644
--- a/docsgpt/storage/db/repositories/schedule_runs.py
+++ b/docsgpt/storage/db/repositories/schedule_runs.py
@@ -167,6 +167,79 @@ class ScheduleRunsRepository:
         ).fetchall()
         return [row_to_dict(r) for r in rows]
 
+    def stats_for_agent(
+        self, agent_id: str, user_id: str, *, days: int = 30,
+    ) -> dict:
+        """Aggregate run stats for an agent's owned schedules over a window.
+
+        Only runs of schedules owned by ``user_id`` on ``agent_id`` whose
+        ``scheduled_for`` falls within the last ``days`` days are counted.
+
+        Args:
+            agent_id: Agent UUID the schedules belong to.
+            user_id: Owner of the schedules (and runs).
+            days: Window length in days, counted back from now.
+
+        Returns:
+            Dict with ``runs``, ``failed`` (``failed``/``timeout``),
+            ``tokens`` (prompt + generated) and ``latest_failure`` — the
+            most recent failed run's ``scheduled_for``/``status``/
+            ``error_type``, or ``None`` when there is none.
+        """
+        row = self._conn.execute(
+            text(
+                """
+                WITH window_runs AS (
+                    SELECT r.scheduled_for, r.status, r.error_type,
+                           r.prompt_tokens, r.generated_tokens
+                    FROM schedule_runs r
+                    JOIN schedules s ON s.id = r.schedule_id
+                    WHERE s.agent_id = CAST(:agent_id AS uuid)
+                      AND s.user_id = :user_id
+                      AND r.user_id = :user_id
+                      AND r.scheduled_for >= now() - make_interval(days => :days)
+                ),
+                latest_failure AS (
+                    SELECT scheduled_for, status, error_type
+                    FROM window_runs
+                    WHERE status IN ('failed', 'timeout')
+                    ORDER BY scheduled_for DESC
+                    LIMIT 1
+                )
+                SELECT agg.runs, agg.failed, agg.tokens,
+                       lf.scheduled_for AS latest_failure_scheduled_for,
+                       lf.status AS latest_failure_status,
+                       lf.error_type AS latest_failure_error_type
+                FROM (
+                    SELECT count(*) AS runs,
+                           count(*) FILTER (
+                               WHERE status IN ('failed', 'timeout')
+                           ) AS failed,
+                           COALESCE(
+                               SUM(prompt_tokens + generated_tokens), 0
+                           ) AS tokens
+                    FROM window_runs
+                ) agg
+                LEFT JOIN latest_failure lf ON true
+                """
+            ),
+            {"agent_id": str(agent_id), "user_id": user_id, "days": int(days)},
+        ).fetchone()
+        data = row_to_dict(row)
+        latest_failure = None
+        if data.get("latest_failure_scheduled_for") is not None:
+            latest_failure = {
+                "scheduled_for": data["latest_failure_scheduled_for"],
+                "status": data["latest_failure_status"],
+                "error_type": data["latest_failure_error_type"],
+            }
+        return {
+            "runs": int(data.get("runs") or 0),
+            "failed": int(data.get("failed") or 0),
+            "tokens": int(data.get("tokens") or 0),
+            "latest_failure": latest_failure,
+        }
+
     def update(self, run_id: str, fields: dict) -> Optional[dict]:
         """Apply a whitelisted partial update to a run row."""
         filtered = {k: v for k, v in fields.items() if k in _ALLOWED_UPDATES}
diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
index 0d776303..289d9d97 100644
--- a/frontend/DESIGN.md
+++ b/frontend/DESIGN.md
@@ -1,8 +1,9 @@
 # DocsGPT frontend design system
 
 The UI is Tailwind v4 plus the shadcn-style components in
-`src/components/ui/`. `@shadcn/lint` enforces the rules below through
-`npm run lint`; its messages point here. Everything in this file is either a
+`src/components/ui/`. `@shadcn/lint` and the `no-restricted-syntax`
+selectors in `eslint/` enforce the rules below through `npm run lint`; their
+messages point here. Everything in this file is either a
 token in `src/index.css` or a variant in a `ui/` component, so an agent or a
 contributor can always find the concrete thing to use.
 
@@ -36,7 +37,7 @@ through `@theme inline`, so `bg-`, `text-`, `border-`, `ring-`, `fill-` and
 | `popover`, `popover-foreground`         | floating menus and popovers                                                       | same as card                                                        |
 | `muted`, `muted-foreground`             | quiet fills and secondary text, icons, placeholders, timestamps                   | `bg-gray-100/200`, `text-gray-400/500/600`, `dark:text-gray-400`    |
 | `accent`, `accent-foreground`           | hover and selected fills                                                          | `hover:bg-gray-100`, `dark:hover:bg-gray-700`                       |
-| `border`, `input`, `ring`               | dividers and field borders (fields use `border-border`), focus rings              | `border-gray-200/300`, `dark:border-gray-600/700`                   |
+| `border`, `input`, `ring`               | dividers, field borders (fields use `border-input`, `fieldFrame`), focus rings    | `border-gray-200/300`, `dark:border-gray-600/700`                   |
 | `primary`, `primary-foreground`         | brand purple: primary actions, links, selected states                             | `bg-purple-*`, `text-purple-*`, `#7D54D1`, `#A076F6`                |
 | `secondary`, `secondary-foreground`     | pressed and active toggles (a brand tint), secondary buttons, the question bubble | `bg-accent` on an active icon button                                |
 | `destructive`, `destructive-foreground` | errors, failed states, dangerous actions                                          | `text-red-*`, `bg-red-50/100`, `#B42318`, `#E60000`                 |
@@ -45,7 +46,7 @@ through `@theme inline`, so `bg-`, `text-`, `border-`, `ring-`, `fill-` and
 | `info`, `info-foreground`               | running, informational                                                            | `text-blue-*`, `bg-blue-50/100`                                     |
 | `sidebar-*`                             | the navigation rail                                                               |                                                                     |
 | `chart-1` to `chart-5`                  | data series only, never UI chrome (see below)                                     |                                                                     |
-| `answer-bubble`                         | assistant message background                                                      |                                                                     |
+| `answer-bubble`                         | the source cards under an answer and the answer-side panels (AnswerFlow)          |                                                                     |
 
 Status colours are tuned to stay vivid rather than turning brown or olive,
 so their contrast is low. Against white in light mode, `destructive` and
@@ -82,7 +83,8 @@ One tint scale, by purpose:
   `selected`, Dropzone drag-active and drag-reject). The border carries the
   state; the wash only warms the surface. Never on a chip or a text fill.
 - Brand soft fill: `bg-secondary text-secondary-foreground` (Badge `default`,
-  Avatar `primary`, the OptionCard icon square), never `bg-primary/10`.
+  Avatar `primary`, the OptionCard icon square), never `bg-primary/10`
+  (enforced).
 - Status soft fill: `bg-<role>/10` in both themes (Badge, Alert, ToastHeader,
   a danger-zone panel); no `dark:` twin.
 - Status border: `border-<role>/50`.
@@ -102,12 +104,11 @@ Patterns:
 - Solid status fill: `bg-warning text-warning-foreground`.
 - Guardrail outcomes: block `destructive`, flag `warning`, redact `info`,
   not evaluated `neutral`.
-- Status border: `border-destructive/50`.
 - De-emphasised text: `text-muted-foreground`; go lighter with an opacity
   modifier (`text-muted-foreground/70`) rather than a lighter grey.
 - Text on the brand colour is `text-primary-foreground`, not `text-white`.
-- `secondary` is a brand tint, not a grey: primary at 10% (light) or 15%
-  (dark) over whatever sits behind it, with `primary` text in light and a
+- `secondary` is a brand tint, not a grey: primary at 10% (light) or the
+  lighter #976af3 at 15% (dark) over whatever sits behind it, with `primary` text in light and a
   lighter purple (#b89cf8) in dark. So a pressed toggle (CopyButton's copied
   state, text-to-speech while speaking) shows on card, background and muted
   alike, and never reads as the neutral ghost hover. Use it as
@@ -142,7 +143,7 @@ Patterns:
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `variant` | `default`, `secondary`, `outline`, `outline-primary`, `ghost`, `ghost-muted`, `ghost-destructive`, `ghost-on-accent`, `ghost-destructive-on-accent`, `link`, `destructive`, `destructive-outline`, `combobox`, `sidebar-item`, `tab`, `section-toggle` |
 | `size`    | `xs`, `sm`, `default`, `lg`, `field`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `inline`                                                                                                                                                                |
-| `shape`   | `default` (rounded-md), `pill` (rounded-full, wider padding)                                                                                                                                                                                           |
+| `shape`   | `default` (rounded-md), `pill` (rounded-full, wider padding at `default`, `lg` and `field`)                                                                                                                                                            |
 
 - Round brand buttons (`rounded-3xl px-5`, `rounded-full px-6`): `shape="pill"`,
   plus `size="lg"` if they were `px-6`.
@@ -159,9 +160,10 @@ Patterns:
   ghost's accent square would not.
 - Icons are `lucide-react` at the default stroke (2). Don't pass
   `strokeWidth`, and don't use an `<img>` for a glyph lucide has. The one
-  exception is a tiny check mark inside a status circle (the custom-model
-  test result, the artifact and research step ticks), drawn at 2.5 to 3 so
-  it stays legible at 10 to 12px; raw progress-ring `<svg>`s are not icons.
+  exception is a tiny glyph inside a status circle or chip (the custom-model
+  test result and capability chips, the artifact and research step ticks,
+  `ToastStatus`'s four status icons), drawn at 2.5 to 3 so it stays legible
+  at 10 to 12px; raw progress-ring `<svg>`s are not icons.
 - Icon size is one `size-N` class (never `h-N w-N`, never lucide's `size`
   prop); colour goes on the icon (`text-muted-foreground`), spacing on the
   parent (`gap-*`, not `mr-2` on the icon). Use current lucide names
@@ -181,9 +183,9 @@ Patterns:
   hint passes `text-xs font-normal` (an approved exception), and a link that
   must keep the colour of what it sits in (a status Alert, a dark overlay, a
   source card's URL row) passes `text-current`. Never style a raw `<a>` as a
-  link.
-- Icon-only buttons are `IconButton` (below), never a `Button` with a
-  `title`.
+  link (enforced).
+- Icon-only buttons: see IconButton below. A `title` on a `Button` is
+  rejected (enforced).
 - An action whose label doesn't fit beside a name on a phone (the shared
   agent card's Edit, in a long locale) is two elements: an `IconButton`
   with `sm:hidden` and the labelled `Button` with `hidden sm:inline-flex`.
@@ -196,7 +198,7 @@ Patterns:
   editor. A Cancel inside a line of text (the composer's queued send) is
   `link inline`.
 - The composer controls under the chat field (Attach, Voice, Tools,
-  Sources) are `size="sm" shape="pill"`. Their icons are `size-3.5 sm:size-4`
+  Sources) are `outline sm pill`. Their icons are `size-3.5 sm:size-4`
   with no margin; the size's `gap-1.5` spaces them, and the label span keeps
   `text-xs sm:text-sm` so the row still fits on a phone.
 - Popover comboboxes (`role="combobox"` + `Command`) use `variant="combobox"`,
@@ -211,7 +213,28 @@ Patterns:
   retrieval, Sync) are `size="field" shape="pill"` too, with no min-width
   or hand height. With `shape="pill"` its text starts 21px in, like the
   Input and Select pills beside it. The agent form's pickers are
-  `combobox field pill`, its Add button `outline-primary field pill`.
+  `combobox field pill`, each labelled by a `FormField` (the Prompt picker
+  through `Prompts titleAs="field"`), its Add button `outline-primary field
+pill`, the only `outline-primary` on the agent pages themselves (the Access
+  details modal they open has its own).
+- One variant and size per role on the agent pages (Overview, Logs,
+  Schedules, the workflow builder's toolbar): the page's primary action is
+  `default field pill` (Publish, Save, New schedule), a secondary action
+  `outline field pill` (Save draft, Preview with `Play` first), Cancel `ghost
+field pill`, and page-level actions go in the `ActionMenu` (`size="toolbar"`)
+  at the end of the title row, through `SectionShell titleAction`: Access
+  details and Share with team on Overview, and Preview until the agent is
+  published (before that the preview only says "Publish to preview"). So the
+  row never holds more than three buttons and fits a phone, where the main
+  one stretches across it (`flex-1 sm:flex-none`; `PageToolbar`'s action slot
+  spans the stacked row below `sm`). The workflow builder's toolbar has no
+  title row and keeps its ⋯ at the row's end. The
+  agent's Delete is in Overview's danger zone; only the workflow builder's
+  toolbar has it in the ⋯ menu, as a `destructive` item. The row itself is
+  `agents/components/AgentPageToolbar` (see Page chrome). A row's common
+  action is `outline sm pill` (a schedule's Run now or Resume) with its other
+  actions in the row's `ActionMenu`; a delete there is a `destructive` item
+  that opens the confirm modal.
 - Rows in the navigation sidebar (`hover:bg-sidebar-accent … pl-3 gap-2.5
 rounded-3xl`) are `variant="sidebar-item"`: left-aligned, full-radius, normal
   weight, `bg-sidebar-accent` on hover and while `aria-current="page"`. Use it
@@ -226,24 +249,30 @@ rounded-3xl`) are `variant="sidebar-item"`: left-aligned, full-radius, normal
   are `variant="link" size="sm"` with only `-ml-3 w-fit justify-start`;
   a chevron, when the toggle has one, is a lucide `ChevronRight` (so it
   takes the link colour) as the first child.
-- Underline tabs (FilePicker's My Files / Shared with Me, the agent page
-  sub-nav) are `variant="tab"`: muted text on a transparent 2px bottom border,
-  square corners, no hover fill. Mark the current tab with `data-active`, which
-  gives it `foreground` text and a `primary` underline. Padding-free tabs (a
-  sub-nav with `gap-6`) add `size="inline"`, which keeps 4px above the line;
-  the row draws the 1px baseline, and `-mb-px` lays the underline over it.
-  Use them for a row of route links (the agent sub-nav: a `<nav>` whose
-  current link carries `aria-current="page"`). Tabs that switch a panel in
-  place are `ui/tabs` with `variant="underline"` on `TabsList` and each
-  `TabsTrigger`: the same pixels, plus `role="tablist"`/`"tab"`,
-  `aria-selected` and arrow-key focus; wrap the panel in `TabsContent`
-  (FilePicker's My Files / Shared with Me). The `default` variant is a pill
-  tab, unused in the app.
+- Underline route tabs are `variant="tab"`: muted text on a transparent 2px
+  bottom border, square corners, no hover fill. Mark the current tab with
+  `data-active`, which gives it `foreground` text and a `primary` underline.
+  Padding-free tabs (a sub-nav with `gap-6`) add `size="inline"`, which keeps
+  4px above the line; the row draws the 1px baseline, and `-mb-px` lays the
+  underline over it. Its one use is `agents/AgentPageHeader.tsx`, the workflow
+  builder's fixed toolbar: a breadcrumb and the Overview / Logs / Schedules
+  tabs in a `<nav>`, the others `<Link>`s and the current one a `<span
+aria-current="page">` with `data-active`. The
+  agent section pages switch with the section sidebar (the phone menu below
+  `lg`) and carry no pill row; the agent tile's ⋯ also opens Logs. Tabs that switch a panel in place are
+  `ui/tabs` with `variant="underline"` on `TabsList` and each `TabsTrigger`:
+  the same pixels, plus `role="tablist"`/`"tab"`, `aria-selected` and
+  arrow-key focus; wrap the panel in `TabsContent` (FilePicker's My Files /
+  Shared with Me, Schedules' Recurring / One-time in
+  `agents/schedules/SchedulesView.tsx`). The `default` variant is a pill tab,
+  unused in the app.
 - A section panel's disclosure header (NewAgent's Advanced and Guardrails
   panels) is `variant="section-toggle" size="sm"` with `-ml-3 w-fit
 justify-start` and `aria-expanded`: a lucide `ChevronRight` first
   (`rotate-90` while open) in primary, then the foreground title, with a
-  primary underline on hover. The button draws no focus ring; the panel does,
+  primary underline on hover. Both call sites wrap the Button in an `<h2>`
+  (a button flattens heading children, so the heading goes outside) and put
+  the title in a `text-lg font-semibold` span. The button draws no focus ring; the panel does,
   so keyboard focus outlines the whole panel. The panel is a `Card` (a place,
   `subtle lg`), and every Card carries that ring
   (`has-[[data-variant=section-toggle]:focus-visible]:ring-3 … ring-inset`,
@@ -276,6 +305,7 @@ justify-start` and `aria-expanded`: a lucide `ChevronRight` first
 | `tone`        | `default`, `destructive` (the status soft fill and border, `border-destructive/50 bg-destructive/10`, over any variant)                                         |
 | `padding`     | `none`, `sm` (p-3, row boxes and code blocks), `default` (p-4), `lg` (p-6, tiles, panels and stat tiles)                                                        |
 | `interactive` | whole card is the target: hover, focus ring and `selected` highlight; pair with `asChild` around a `<button>` or `<Link>`                                       |
+| `selected`    | an `interactive` card that is the current choice: `border-primary` and the `/5` wash                                                                            |
 
 Parts: `CardHeader` (title left, `CardAction` top-right), `CardTitle`,
 `CardDescription`, `CardContent`, `CardFooter` (meta row, sticks to the
@@ -291,19 +321,19 @@ question: is it a **thing** you open, move, share or delete as a whole, or a
 **place** where you read or edit content? The fill marks objects; the border
 marks structure.
 
-| Role                 | Variant                                                                           | Examples                                                                                          |
-| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Thing (a tile)       | `filled`, on a page or in a modal                                                 | agents, folders, sources, tools, custom models, teams, chunks, the shared agent card              |
-| Place (a panel)      | `subtle` on the page or a right drawer, `outline` on a card (modal, bottom sheet) | the agent form's sections, chart panels, stat tiles, log tables, schedule rows, the agent preview |
-| Choice (picker tile) | `outline interactive`, or `OptionCard`                                            | the Add tool tiles; selection is drawn by the border, so the border stays                         |
-| Well                 | `filled padding="sm"`                                                             | code, a token to copy, run output, inside a panel (see Code blocks below)                         |
+| Role                 | Variant                                                                           | Examples                                                                             |
+| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Thing (a tile)       | `filled`, on a page or in a modal                                                 | agents, folders, sources, tools, custom models, teams, chunks, the shared agent card |
+| Place (a panel)      | `subtle` on the page or a right drawer, `outline` on a card (modal, bottom sheet) | the agent form's sections, chart panels, stat tiles, log tables, schedule rows       |
+| Choice (picker tile) | `outline interactive`, or `OptionCard`                                            | the Add tool tiles; selection is drawn by the border, so the border stays            |
+| Well                 | `filled padding="sm"`                                                             | code, a token to copy, run output, inside a panel (see Code blocks below)            |
 
 - Layers go page → panel (border) → well (fill), or page → tile (fill).
   `subtle` and `outline` are one role on two surfaces; in light mode they
   look the same.
 - An item that you read inside, rather than open elsewhere, is a place: a
-  schedule is an item, but its row expands into a run table, so it is a
-  `subtle` panel. The tile look is for a summary you open.
+  schedule is an item, but its row (`agents/schedules/ScheduleRow`) expands
+  into a run table, so it is a `subtle` panel. The tile look is for a summary you open.
 - **No fill on a fill.** Nothing on a `filled` tile repeats its muted fill,
   or it disappears: no `bg-muted` strip or box, no filled Card inside it, and
   Skeleton bars take `surface="muted"`. Put a meta line such as a token count
@@ -314,9 +344,8 @@ marks structure.
   (`eslint/card-surfaces.js`).
 - Never a page-sized `bg-muted` panel around a page's cards: panels sit on
   the page background, as on Logs and Analytics.
-- A field in a `subtle` panel sits on the page background, so its floating
-  label passes `labelSurface="background"`; in an `outline` panel it keeps
-  the default `card`.
+- A field in a `subtle` panel passes `labelSurface="background"` (see
+  FormField).
 
 Recipes by role:
 
@@ -325,13 +354,20 @@ Recipes by role:
   choices: `outline interactive lg` with `asChild` around a `<button>`.
 - Chart panels are `subtle lg` with fixed heights passed as layout; a chart
   panel inside a modal is `outline` (the modal is already `bg-card`).
-- Form sections (the agent form's Meta, Source, Prompt, Advanced,
-  Guardrails) are `subtle lg`; a disclosure section's header is a
-  `section-toggle`, and Card draws its focus ring.
-- Row boxes inside a form or panel (a guardrail check, a schedule row, the
-  schedule's timezone box, the discovered MCP tools) are `padding="sm"`, in
-  the panel variant of the surface they sit on (`subtle` in a page panel,
-  `outline` in a modal).
+- Form sections (the agent form's Basics, Knowledge and behaviour, Model,
+  Advanced, Guardrails) are `subtle lg` with `gap-5`; Basics, Knowledge and
+  behaviour and Model are titled by a `SectionHeader`, Advanced and
+  Guardrails by a `section-toggle` (see Button). A disclosure panel's body
+  under its toggle is one `flex flex-col gap-5` wrapper, its rows carrying
+  no `mt-*`, so every section has 20px under its title. The destructive
+  danger-zone Card follows them.
+- Row boxes inside a form or panel (a guardrail check, the schedule's
+  timezone box, the discovered MCP tools) are `padding="sm"`, in the panel
+  variant of the surface they sit on (`subtle` in a page panel, `outline` in
+  a modal).
+- A schedule is `agents/schedules/ScheduleRow`: `subtle`, `padding="none"`,
+  with its run log flush under it; a chevron `IconButton ghost-muted
+icon-xs` toggles the runs.
 - A danger zone (Delete agent, Revoke a device) and a failing stat are
   `tone="destructive"`; the title beside it is `SectionHeader
 tone="destructive"`. Muted text fails AA on the red fill, so the tone turns
@@ -358,8 +394,10 @@ well) on a card or background surface, `subtle padding="sm"` on a muted one
 (the tool-approval card, an expanded log row). A copy row is the same Card
 with `className="flex-row items-start gap-2"` and the `CopyButton` inside.
 Inside an Alert or a trace's tool panel, and in a full-pane viewer, the
-`<pre>` takes the recipe with no Card, so boxes don't nest. Put scroll caps
-(`max-h-* overflow-y-auto`) on the Card; never `break-all`.
+`<pre>` takes the recipe with no Card, so boxes don't nest. A scroll cap
+goes on an inner `<div className="scrollbar-overlay max-h-* overflow-y-auto">`
+around the `<pre>`, inside the Card's padding, never on the Card: on the Card
+the scrollbar runs into its rounded corners. Never `break-all` (enforced).
 This recipe is for app output. A fenced code block in a markdown answer is
 source code: it keeps its lines (`white-space: pre`, indentation intact) and
 scrolls sideways inside its own bordered frame (see Chat answer column).
@@ -408,7 +446,8 @@ modal) leave it out and stay plain buttons. Only layout classes on it.
 `variant`: `default` (brand), `neutral`, `success`, `warning`, `destructive`,
 `info`, `outline`. Replaces every hand-rolled
 `rounded-full bg-<colour>-100 px-2 py-0.5 text-xs text-<colour>-700 dark:...`
-pill, including schedule and run status pills, trace chips and statuses,
+pill, including schedule and run status pills (`agents/schedules/StatusBadge.tsx`
+maps schedule and run statuses to Badge variants), trace chips and statuses,
 token scope chips, "Disabled" and tool chips. A grey chip is `neutral`, never
 a `bg-muted` pill. The admin role is `default` wherever it shows (Teams, Admin
 → Users); every other role is `neutral`. Chips that show code (token scopes) pass `font-mono`, and
@@ -419,7 +458,22 @@ stat chips `tabular-nums`, as approved exceptions. HTTP method pills take their
 `default` Badges with a remove X, then "+N more", on a `Button
 variant="combobox" size="field"` trigger that grows past 38px when the chips
 wrap, with SelectTrigger's turning chevron; each row in its list shows a
-`Checkbox size="sm"`.
+`Checkbox size="sm"`. Inside a Modal pass `modal`, or its popover can't
+scroll and doesn't close on an outside click.
+
+In a picker list, mark the item that is currently chosen with
+`CommandItem checked` (a `secondary` brand tint through `data-checked`), not
+with `bg-accent`: cmdk's own `data-selected` highlight is `bg-accent` and
+follows the pointer and arrow keys, so an accent fill would look like hover.
+While a checked item is also highlighted it keeps its tint and text and gains
+a 1px inset `primary` ring, so the chosen row never turns plain grey.
+
+A picker's footer (`MultiSelectPopover footer`) links to the page that manages
+the list, as a `link inline` Button with a 12px `ArrowRight` (Go to Sources, Go
+to Tools). A shortcut action (Upload new, an `outline-primary pill`) sits at the
+right end of the same row: `flex flex-wrap items-center justify-between gap-3`,
+so on a narrow sheet or in a long locale it wraps under the link rather than
+taking a row of its own everywhere (`SourcesPopoverFooter`).
 
 ### Input (`ui/input.tsx`)
 
@@ -431,11 +485,8 @@ wrap, with SelectTrigger's turning chevron; each row in its list shows a
 
 Text alignment classes (`text-right`) and `font-mono` (code fields) are
 allowed on Input and Textarea. `<Input label>` is the shorthand for a
-one-field `FormField`: the same floating label on the border, the same
-`labelSurface` (`card` default, forms in cards and modals; `background`,
-fields straight on a page; `muted`, fields on a muted panel). Never pass a
-background class for it. A placeholder under a floating label is an example:
-it stays hidden while the label rests inside and shows on focus. The chat and hero
+one-field `FormField`: the same floating label on the border and the same
+`labelSurface` (see FormField). The chat and hero
 fields (`rounded-3xl px-5 py-3`) are `size="lg" shape="pill"`. A
 default-size pill (38px, the form-row height) pads `px-5` like the large
 one, so its text lines up with the Select pills. Compact table
@@ -475,9 +526,11 @@ variable highlighter and the chunk editor behind its line-number gutter.
 
 Every boxed form control is labelled by a floating label:
 `<FormField label required hint error disabled labelSurface>` with the field
-as its only child. The label sits on the field's border (12px muted,
-`labelSurface` `card` | `background` | `muted` to match the surface behind
-the field, so the notch hides the line). It rests inside an empty, unfocused
+as its only child. The label sits on the field's border (12px muted), and
+`labelSurface` matches the surface behind the field so the notch hides the
+line: `card` (the default: forms in cards, modals and `outline` panels),
+`background` (fields straight on a page or in a `subtle` panel), `muted`
+(fields on a muted panel). Never pass a background class for it. It rests inside an empty, unfocused
 `Input` or `Textarea` and moves up on focus; on a `SelectTrigger`, combobox,
 `MultiSelect`, number field or `Dropzone` it stays on the border. It turns
 red (`text-destructive`) with an `error`, and dims while `disabled`. Under
@@ -526,13 +579,30 @@ toggle) are not SettingRows.
 
 ### Checkbox (`ui/checkbox.tsx`)
 
-`<Checkbox checked onCheckedChange>` (Radix), never `<input type="checkbox">`:
-native boxes take the OS accent and ignore dark mode. `size`: `default`
+`<Checkbox checked onCheckedChange>` (Radix), never `<input type="checkbox">`
+(enforced): native boxes take the OS accent and ignore dark mode. `size`: `default`
 (16px, option rows), `sm` (14px, table cells). Unchecked it is an
 `border-input` box; checked, `primary` with a `primary-foreground` check.
 Name it with a `Label htmlFor` or `aria-label`. For an on/off setting with a
 description use a Switch in a SettingRow instead.
 
+### Switch, TimePicker and Calendar (`ui/switch.tsx`, `ui/time-picker.tsx`, `ui/calendar.tsx`)
+
+`Switch` (Radix) is an on/off setting, placed inside a `SettingRow` that names
+it. The track is `primary` when on and `bg-input` when off, with a white
+thumb in both themes (see Elevation).
+
+`TimePicker` picks a time of day as two `SelectTrigger`s, hours and minutes,
+with a `value`/`onChange` pair in 24-hour `"HH:MM"`. `minuteStep` sets the
+minute list's step (default 1), `ariaLabel` names the group and each select,
+and `showIcon={false}` drops the leading clock. Never a native
+`<input type="time">`, which ignores dark mode.
+
+`Calendar` is react-day-picker styled with the theme tokens, its days `ghost`
+Buttons; open it in a `Popover` from a field (ScheduleFormModal's date). Its
+day button carries the one approved lint exception in the file (see Approved
+exceptions).
+
 ### Tooltip (`ui/tooltip.tsx`) and IconButton (`ui/icon-button.tsx`)
 
 Every icon-only button is an `IconButton`: `<IconButton label icon hint?
@@ -579,24 +649,32 @@ Replaces every `<hr>` and every `border-b` or `h-px` div that is only a line.
 `currentColor`, so colour it with a `text-*` token on it or its parent. `xs`
 is the icon-sized step: a busy Button, a step's status in a Preview or
 research row. Never shrink a larger size with `className="size-*"`, and don't
-use lucide `LoaderCircle` (formerly `Loader2`) or a hand-drawn SVG as a loader. `Skeleton` is a pulsing
+use lucide `LoaderCircle`/`Loader2` or a hand-drawn SVG as a loader (the
+`Loader`, `Loader2` and `LoaderCircle` imports are enforced). `Skeleton` is a pulsing
 muted block sized with layout classes; its default radius (`rounded-sm`, 6px)
 is the bar radius, so pass none (`rounded-full` for an avatar or switch
 stand-in). Bars inside a muted surface (a `Card variant="filled"` tile) take
 `surface="muted"` (`bg-muted-foreground/20`), since `bg-muted` would vanish
 there. A tile's loading mirror is the same `Card` as the tile (variant,
 padding, height) with Skeleton bars laid out like its content; the Card
-itself never pulses, only the bars do. Never put a Skeleton inside an
-element that pulses itself; the two animations multiply.
+itself never pulses, only the bars do. A loader inside a panel that is
+already on screen (a chart panel whose title shows while its data loads) is
+bars only, shaped like the content; the panel is the Card. A loader for an
+`Alert` or row box is an `outline sm` Card in a modal with bars inside. Never
+put a Skeleton inside an element that pulses itself; the two animations
+multiply.
 
 ### LoadingState and EmptyState (`ui/loading-state.tsx`, `ui/empty-state.tsx`)
 
 A page, panel or dialog that is still loading shows `LoadingState`, never a
 hand-centred `Spinner`. `fill`: `parent` (`h-full`, needs a parent with a
-height: the artifact panel, a drawer body), `screen` (`h-screen`, the app and
+height: the artifact panel, a drawer body), `screen` (`h-dvh`, the app and
 admin guards) or `block` (`py-10`, a page section or dialog body with no
 height of its own). `label` puts a muted caption under the ring (a long job:
-Convert to wiki, Enable GraphRAG); it is also the ring's name. Spinners
+Convert to wiki, Enable GraphRAG); it is also the ring's name. `size` takes
+the Spinner sizes (`default` unless set): `sm` inside a picker (the
+MultiSelect popover's list), `lg` for a full panel (a remote device's
+config). Spinners
 inside a control (a busy Button, a picker's `sm` ring) stay `Spinner`.
 
 Nothing to show is `EmptyState`: `size` `default | sm | xs` (128 / 96 / 64px
@@ -618,20 +696,33 @@ width-percent divs in quota, indexing and guardrail views.
 `size`: `none` (image decides, the default), `xs` (28px), `sm` (32px),
 `default` (36px), `lg` (40px): Button's names at Button's heights;
 `shape`: `none`, `circle`, `square`; `variant`: `default`, `primary` (brand
-initials on `secondary`), `muted` (grey initials). Initials boxes pass the letters as
+initials on `secondary`), `muted` (a grey `bg-muted-foreground/15` box with
+`foreground` initials). Initials boxes pass the letters as
 children.
 
 ### Dropzone (`ui/dropzone.tsx`)
 
-`size`: `default` (tall target), `compact` (one row, for forms and modals).
+`size`: `default` (tall target, for a step whose whole job is the file: Upload
+from device, Import agent, Import API specification), `compact` (one row, a
+file field among other fields),
+`tile` (a square beside a form's fields, the agent's avatar: 64px and
+icon-only on a phone beside the Name field, 88px with a one-word title from
+`sm` beside Name and Description; no description). `FileUpload size="tile"` fills the tile
+with the picked image, or with `currentImage` (the saved one) until then.
 Props: `onDrop`, `accept`, `multiple`, `maxFiles`, `maxSize`, `disabled`,
-`title`, `description`, `icon`, `error`. Border and fill follow the drag
+`title`, `description`, `icon`, `error`, `validator` (react-dropzone's
+per-file check) and `children`, which replaces the icon, title and
+description block. Border and fill follow the drag
 state through `data-drag-active` and `data-drag-reject` (the `/5` wash);
 it hovers to solid `accent`. Every drop
 target renders it, including `components/FileUpload.tsx` (which keeps its
 preview and validation logic) and the Import agent / Import API
 specification dialogs; don't hand-roll a `border-2 border-dashed` target
-around `useDropzone`.
+around `useDropzone`. Picked files show under it as `ListRows` (name and
+size) in an `outline` Card, and rejected files (too large, wrong type) as the
+Dropzone's `error`, never dropped silently. The chat composer is the one other
+`useDropzone` host: the whole composer is the drop area, with its own
+overlay, whose prompt is a Title (see Typography roles).
 
 ### Toast (`ui/toast.tsx`)
 
@@ -644,8 +735,8 @@ overlay. The app has one
 (`role="status"`, `aria-live="polite"`) and the fixed stack, so `Toast`
 cards carry no role and no toast renders its own rail or positioning. Top
 to bottom it holds `TeamNotificationToast`, `ToolApprovalToast`,
-`UploadToast` and `ActionToast`, and it moves to the bottom-left while the
-workflow Preview drawer is open. A new toast component returns only its
+`UploadToast` and `ActionToast`, and it moves to the bottom-left while any
+agent preview drawer is open (workflow or classic). A new toast component returns only its
 `Toast` cards and is added to that viewport. A page that reports the result
 of an action (the admin Users actions) dispatches
 `showActionToast({ variant: 'success' | 'destructive', message })` from
@@ -770,15 +861,42 @@ Previous / Next buttons. Don't hand-roll a Previous / Next row.
 
 Every section page (settings, admin, agents, teams) is wrapped in
 `navigation/SectionShell` (`width` `default` 6xl, `wide` 7xl for admin,
-`narrow` 5xl; `pills` for the phone destination pills); it draws the title and
+`narrow` 5xl; `title` replaces the section title; `titleAction` puts a page-level
+control, such as a toolbar `ActionMenu`, at the title row's end;
+`header={false}` drops the title for the phone section index, which draws
+its own);
+it draws the title and
 starts the content 32px below it, so pages carry no root `mt-*`. The block
 under the title is `components/PageToolbar`: `intro`, then the page `search`
 (left, `max-w-md`) and the page `action` (right, `Button size="field"
-shape="pill"`), then `divider` (a `Separator`). A page search is
-`components/SearchInput`: the 38px pill with a search icon and a floating
-`label`. The chunk viewer's and file tree's searches stay `CommandInput` in
+shape="pill"`), then `children` (notices that belong to the action, such as
+a limit warning), then `divider` (a `Separator`). With no `search` the intro
+moves into the row's left slot (`max-w-2xl`) beside the action. A page search
+is `components/SearchInput`: the 38px pill (`size="sm"` for 32px) with a
+search icon and a floating `label` on `labelSurface="background"` (its
+default); a placeholder-only search is named by its placeholder. The chunk viewer's and file tree's searches stay `CommandInput` in
 their frame, because their results are `CommandItem`s.
 
+An agent's tabs (Overview, Logs, Schedules) share one header,
+`agents/components/AgentPageToolbar` on top of `PageToolbar`, under
+`SectionShell`'s title (the tab's name, or "New agent" through SectionShell's
+`title` prop). Its props: `name` (the agent, first in a muted byline),
+`status` (a Badge beside the name, Overview's Published / Draft), `meta` (the
+tab's context after a middle dot, "Last used" on Logs and Schedules),
+`actions` (the tab's buttons on the right, at most three; the page's ⋯ goes
+in the title row, not here), `intro` (a line that replaces
+the byline: the new-agent form) and `children` (notices between the row and
+the rule, such as the failed-save `Alert`). With a status badge the meta
+takes its own line on a phone. The row keeps the 38px field height when a
+tab has no actions, so the rule lands in the same place on every tab.
+`AgentPageHeader` remains only in the workflow builder's fixed toolbar. All
+three tabs are `SectionShell` pages at the default width; the agent preview
+is a drawer (see Modal, not Dialog). Overview groups its fields into three
+`subtle lg` panels (Basics, Knowledge and behaviour, Model) with the two-up
+field grid, then Advanced, Guardrails and the danger zone. Schedules shows a
+`StatCard` row, Recurring / One-time as `ui/tabs variant="underline"`, and
+each schedule as a `ScheduleRow` (see Card surfaces).
+
 ### App chrome: the phone top bar and New Chat
 
 Below `lg` the top of every page is `navigation/MobileTopBar` (56px, `h-14`):
@@ -829,12 +947,15 @@ wrapper).
 
 ### Grids
 
-Two recipes, no component. Tiles (sources, tools, custom models, agents):
+Three recipes, no component. Tiles (sources, tools, custom models, agents):
 `grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4`; tiles
 take the column width, never a fixed `w-[300px]`. Team cards stop at three
 columns (`lg:grid-cols-3`): their header row holds an initial, the name, a
 role badge and a chevron. Stat rows: `grid grid-cols-2 gap-4 md:grid-cols-4`
-(five tiles: `md:grid-cols-3 lg:grid-cols-5`; a dialog: `grid-cols-3`). A
+(five tiles: `md:grid-cols-3 lg:grid-cols-5`; a dialog: `grid-cols-3`). Text
+tiles whose body is the content (chunks) follow their container, since the
+same list renders beside a file-search column: `grid grid-cols-1 gap-4
+sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]`. A
 grid inside a Modal keeps its own column counts, because breakpoints follow
 the window, not the dialog.
 Skeleton mirrors follow the grid they stand in for.
@@ -853,12 +974,12 @@ rejects imports of it elsewhere. App code uses `Modal` (sizes `sm` to
 `full`, `mobileVariant="sheet"`) or `CommandDialog`.
 
 The width comes from `size` only: `sm` 384, `md` 512 (the default), `lg` 672
-(a form or a one-column list: Move to folder, Upload), `xl` 896 (a grid of
+(a form or a one-column list: Move to folder), `xl` 896 (a grid of
 tiles or a wide editor: Add tool, Test retrieval, the prompt editor), `full`.
 Never add a width or height class. The dialog caps itself at `85dvh` and
 its body is the one scroller, so the header and footer stay put; don't cap
 the body with `contentClassName`. `contentClassName="overflow-visible"`
-(`!overflow-visible`) is only for a body whose popover must escape it (the
+(`cn` drops the body's `overflow-y-auto` for it) is only for a body whose popover must escape it (the
 prompt editor, Share conversation, Move to folder). `className` is placement
 only.
 
@@ -894,23 +1015,31 @@ the same (`modals/SearchConversationsModal.tsx`). `CommandDialog` sits on
 `DialogContent`, which has Modal's surface (`bg-card rounded-2xl
 shadow-modal`, no border, `p-8`, a 20px title, a `gap-3` footer, a left-aligned
 header, and the `flex-col max-h-[85dvh]` column whose body the caller makes the
-scroller) and the same blurred overlay. Modal, DialogContent and every Sheet share one scrim,
+scroller) and the same blurred overlay. Modal, DialogContent, every Sheet and
+the phone sidebar's backdrop (`Navigation.tsx`, at `z-20` so an open sidebar
+dims the top bar, with SheetOverlay's `animate-in fade-in-0`) share one scrim,
 `overlayScrim` in `lib/utils.ts` (`bg-black/25 backdrop-blur-xs
 dark:bg-black/50`).
 
 A right drawer (`SheetContent side="right"`) is on `bg-background`, like the
 page: its content paints no surface of its own, and panels in it are
-`subtle` (see Card surfaces). An agent is previewed in one shared drawer,
-`agents/components/AgentPreviewSheet`, for workflow and classic agents alike:
-`w-full sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]`, a `SheetTitle`
+`subtle` (see Card surfaces). Its width is `size`, by role, never a `w-*` or
+`max-w-*` class (enforced): `default` (384px, 75% on a phone) for a companion
+list read beside the chat (an answer's sources, the phone artifact sheet);
+`detail` (576px, full width on a phone) for one record's fields (a schedule
+run); `wide` (600 / 700 / 800px at `sm` / `md` / `lg`, full width on a phone)
+for a working surface (a trace, an agent preview). An agent is previewed in
+one shared drawer, `agents/components/AgentPreviewSheet`, for workflow and
+classic agents alike: `size="wide"`, a `SheetTitle`
 and a one-line `SheetDescription` (the agent's name) in a header padded
 `pr-12` to clear the close X, an `info` Running badge while it answers, a
 `Separator`, then the preview. The workflow preview's Execution details and
 Artifacts rows are the answer's step-row recipe (see Alert), each step a
 `subtle sm` panel with its output in a `filled sm` well.
 
-Every phone bottom sheet has one shape: `bg-card`, 16px top corners, no top
-border, `max-h-sheet` (the visible viewport less the top safe-area inset and a
+Every phone bottom sheet has one shape: `bg-card`, 18px top corners (`rounded-t-2xl`), no top
+border, `shadow-lg` (both `SheetContent side="bottom"` and Modal's phone
+sheet), `max-h-sheet` (the visible viewport less the top safe-area inset and a
 3rem strip, so the scrim above it can always be tapped to close), and bottom
 padding that clears the iPhone home indicator. Never cap a sheet with `vh` (see
 Viewport heights): a `90vh` sheet slides under Safari's URL bar and covers its
@@ -918,8 +1047,9 @@ scrim. `SheetContent side="bottom"` gives the
 shape with `pb-safe-0` (the bare inset); pass `handle` for the grab bar, which
 also hides the X (the overlay dismisses it; the handle is only a cue and doesn't
 drag; pass `showCloseButton` to keep an X).
-`Modal mobileVariant="sheet"` shares the shape and the `SheetHandle`, with
-`pb-safe` (the inset, at least 1rem) under its footer. `pb-safe`, `pb-safe-0`
+`Modal mobileVariant="sheet"` shares the shape and the `SheetHandle` (and,
+like a handled sheet, has no X), with `pb-safe` (the inset, at least 1rem)
+under its footer. `pb-safe`, `pb-safe-0`
 and `max-h-sheet` are the `index.css` utilities for the safe-area insets; never
 spell `env()` in a class.
 
@@ -933,35 +1063,14 @@ unmounts, and Safari samples the page colour again. `useDarkTheme` calls
 `resetBottomTint()` and `resetTopTint()` (a 16px strip on the top edge) when the
 theme changes. Anything else fixed to the bottom edge that can go away (a
 drawer, a bottom banner) calls `resetBottomTint()` when it is removed. The sizes
-and the one-frame life were measured on an iPhone: 4px at the bottom, 6px at
-the top and a 16ms timer all failed, and a strip behind the content,
-transparent or at `opacity-0` isn't sampled, so don't shrink or hide it.
+and the one-frame life were measured on an iPhone (6px at the bottom, 16px at
+the top), and a strip behind the content, transparent or at `opacity-0` isn't
+sampled, so don't shrink or hide the strip.
 
-**Open question: side panel or right sheet for chat content.** Chat has two
-ways to show something beside an answer. Notes, todos and files open in
-`components/ArtifactSidebar`, a panel that takes a column and leaves the chat
-usable. An answer's full source list opens in a right `Sheet`, which blurs
-and blocks the chat, so the answer being checked is hidden while its sources
-are read. No rule picks between them yet. The leading proposal is one
-surface: content read alongside the chat (artifacts, sources, a cited
-source) opens in the side panel, with citation chips opening it at that
-source; overlays stay for tasks that interrupt (forms, confirmations,
-pickers); phones keep the bottom sheet. Until that is decided, don't add a
-third pattern: new "read beside the chat" content uses the side panel.
-
-In a picker list, mark the item that is currently chosen with
-`CommandItem checked` (a `secondary` brand tint through `data-checked`), not
-with `bg-accent`: cmdk's own `data-selected` highlight is `bg-accent` and
-follows the pointer and arrow keys, so an accent fill would look like hover.
-While a checked item is also highlighted it keeps its tint and text and gains
-a 1px inset `primary` ring, so the chosen row never turns plain grey.
-
-A picker's footer (`MultiSelectPopover footer`) links to the page that manages
-the list, as a `link inline` Button with a 12px `ArrowRight` (Go to Sources, Go
-to Tools). A shortcut action (Upload new, an `outline-primary pill`) sits at the
-right end of the same row: `flex flex-wrap items-center justify-between gap-3`,
-so on a narrow sheet or in a long locale it wraps under the link rather than
-taking a row of its own everywhere (`SourcesPopoverFooter`).
+Content read alongside the chat (notes, todos, files) opens in
+`components/ArtifactSidebar`: a split column beside the chat on desktop, a
+right `Sheet` on phones. An answer's full source list is a right `Sheet`.
+Don't add a third pattern.
 
 ### ActionMenu (`ui/dropdown-menu.tsx`)
 
@@ -970,23 +1079,30 @@ The three-dots menu on a card, tile or row. Pass `options: MenuOption[]`
 `disabled`) and a `triggerLabel`. It renders a `ghost-on-accent` `icon-xs`
 trigger with `EllipsisVertical`, and stops clicks and keys on the trigger and
 the menu from reaching the host, so it can sit inside a clickable card.
-`className` takes layout only (position, margin) and lands on the trigger;
+In a page header or toolbar on a plain surface (the agent Overview's title
+row, through `SectionShell titleAction`; the workflow builder's toolbar), pass
+`size="toolbar"`: the trigger is a 36px `ghost-muted` icon button like the
+others there, hovering to `accent`, with its tooltip below. The default
+`row` trigger's darker hover is only for hosts that turn `accent` themselves.
+`align` (default `end`) places the menu, `disabled` greys the trigger, and
+`triggerTestId` puts a `data-testid` on it. `className` takes layout only (position, margin) and lands on the trigger;
 the menu is at least 144px wide and grows with its labels. `open`/`onOpenChange` make it controlled. Don't hand-build
 this menu from `DropdownMenu`, and don't declare a local option type.
 
 ### Table, Label, dialog text
 
-Every table is `ui/table`; never a raw `<table>` or a table utility class (the
-chat's markdown tables are the one exception). The header row is dense by
-default (`px-2 py-1 text-sm font-normal text-foreground`, 28px, on
+Every table is `ui/table`; never a raw `<table>` (enforced) or a table
+utility class (the chat's markdown tables are the one exception, see Approved
+exceptions). The header row is dense by
+default (`px-2 py-1 lg:px-3 text-sm font-normal text-foreground`, 28px, on
 `TableHead`'s sticky `bg-muted` strip). A `TableRow` hovers (`bg-accent`,
 pointer) only when it has an `onClick`; a read-only row does not. Use
 `TableContainer` for the bordered, scrolling frame; a table that already sits
 in a frame renders `Table` alone. `Table` keeps a 600px minimum so wide
 tables scroll sideways; a narrow one inside a panel passes
-`minWidth="min-w-0"`. A fixed icon column is `width="50px" align="center"`.
+`minWidth="min-w-0"`. A fixed icon column is `width="40px" align="center"`.
 `TableCell` and `TableHeader` accept typography and alignment classes and
-`text-muted-foreground` (RunLog's headers pass the eyebrow). `Label`, `DialogTitle`, `DialogDescription`,
+`text-muted-foreground`. `Label`, `DialogTitle`, `DialogDescription`,
 `SheetTitle` and `SheetDescription` accept typography plus
 `text-foreground` and `text-muted-foreground`. `DialogContent`,
 `PopoverContent`, `SheetContent`, `SheetHeader`, `SheetFooter`,
@@ -1019,8 +1135,8 @@ runs under the tab bar, and the app shell can be dragged and bounce. ESLint
 (`no-restricted-syntax`) rejects both. Pick by what the height does:
 
 - **`dvh`** (the visible viewport, follows the toolbars): the app shell
-  (`h-dvh`), full-screen states (`min-h-dvh`: 404, MobileBlocker, the `screen`
-  `LoadingState`), and caps on things that pop up over the page (a search
+  and the `screen` `LoadingState` (`h-dvh`), full-screen states (`min-h-dvh`:
+  404, MobileBlocker), and caps on things that pop up over the page (a search
   dropdown's `max-h-[calc(100dvh-200px)]`, `Modal`'s `85dvh`).
 - **`svh`** (the smallest viewport, steady): a fixed-size panel inside a page
   that scrolls (the Logs panel's `h-[55svh]`, a list's `max-h-[45svh]`, the
@@ -1033,12 +1149,16 @@ runs under the tab bar, and the app shell can be dragged and bounce. ESLint
 
 ### Typography roles
 
-- **Page title**: `SectionPageHeader` (24px bold); the only other text at
-  that size is a stat figure (`StatCard`).
+- **Page title**: `SectionPageHeader` (24px bold; the phone section index,
+  `SectionIndexPage`, draws the same `h1`); the only other text at that size
+  is a stat figure (`StatCard`).
 - **Title** of a dialog, sheet, drawer header or detail page: `text-xl
 leading-tight font-semibold`. `DialogTitle` and `SheetTitle` default to it;
   `font-bold` is never a title weight. A picker popover's header is a
-  sub-heading, not a title.
+  sub-heading, not a title. The composer's drag-and-drop prompt is a Title
+  in `foreground`. The artifact panel's title (phone sheet and desktop split
+  column alike) is a sub-heading, `text-sm font-semibold wrap-anywhere`: the
+  panel sits beside the chat and its title is often a long generated name.
 - **Section title**: `SectionHeader` (18px). **Sub-heading** inside a panel,
   drawer or modal: `SectionHeader size="xs"` (14px semibold). **Eyebrow**
   (anything set in caps): `SectionHeader size="sm"`; never `uppercase` on a
@@ -1064,7 +1184,7 @@ leading-tight font-semibold`. `DialogTitle` and `SheetTitle` default to it;
   is `wrap-anywhere`, which also lets a table cell or flex item shrink below
   the token instead of widening the table. Both break at spaces first and
   split a token only when it would overflow. Never `break-all`: it splits
-  ordinary words mid-word ("notif / ications").
+  ordinary words mid-word ("notif / ications"); the lint rejects it.
 
 ### Rhythm
 
@@ -1078,11 +1198,14 @@ gap, so drop it).
 ### Radius by role
 
 `rounded-xs` 2px, `rounded-sm` 6px, `rounded-md` 8px, `rounded-lg` 10px,
-`rounded-xl` 14px, `rounded-2xl` 18px (from `--radius`); bare `rounded` is a
-fixed 4px, so don't use it. Skeleton bars: the default. Tinted icon squares:
+`rounded-xl` 14px, `rounded-2xl` 18px, `rounded-3xl` 22px, `rounded-4xl`
+26px (from `--radius`); bare `rounded` is a fixed 4px, so don't use it
+(enforced). `3xl` is the chat's own shapes (the composer, the question
+bubble) and `4xl` the answer's source cards and the landing page's model
+picker; app chrome stops at `2xl`. Skeleton bars: the default. Tinted icon squares:
 `rounded-md` at `size-7|8`, `rounded-xl` at `size-12|14`, `rounded-2xl` at
-`size-20`. `rounded-full` only for avatars, status dots and the workflow
-palette pills.
+`size-20`. `rounded-full` only for pills (`shape="pill"` controls and
+fields), avatars, status dots and the workflow palette pills.
 
 ## Motion
 
@@ -1093,8 +1216,8 @@ collapsibles, `duration-300 ease-in-out` on the named property for the shell
 (sidebar, main column, top buttons); a shadow or ring change is
 `transition-shadow`, several at once a bare `transition`. No `transition-all`
 (the floating labels in `form-field.tsx` and `input.tsx`, which move and
-resize, are the exception) and no `hover:scale`: hover is a fill, border or
-text-colour change.
+resize, are the exception) and no `hover:scale-*`, both enforced: hover is a
+fill, border or text-colour change.
 
 New entrances are `animate-in fade-in duration-200 motion-reduce:animate-none`
 (`SectionRail`). Two chat timings are decided exceptions: the disclosure fade
@@ -1106,16 +1229,16 @@ fade-in slide-in-from-bottom-1.5 duration-260 ease-out`, both with
 
 Phone / desktop is `lg` (1024px) in classes and `isDesktop` in JS
 (`useMediaQuery`); `sm` and `md` only reflow content. Wide two-column layouts
-that need more room (Analytics' chart rows, the agent form beside its preview)
-go two-up at `xl`. No custom breakpoints (`min-[…]`, `max-[…]`,
-`[@media(…)]`). The workflow builder needs `lg`; below it `MobileBlocker`
+that need more room (Analytics' chart rows) go two-up at `xl`. No custom
+breakpoints (`min-[…]`, `max-[…]`, `[@media(…)]`; enforced). The workflow builder needs `lg`; below it `MobileBlocker`
 shows.
 
 ## Focus, elevation and stacking
 
 - **Focus ring**: `focus-visible:ring-3 focus-visible:ring-ring/50` plus
   `focus-visible:border-ring` on fields. Never `focus:` (mouse users see it)
-  and never `ring-2` or `ring-[3px]`; the `ui/` components already carry it,
+  and never `ring-2` or `ring-[3px]` (a `focus:` or `focus-within:` ring
+  with `ring-2` is enforced); the `ui/` components already carry it,
   so plain elements should become components rather than copy the classes.
   Inside `ui/`, spell it with the `focusRing` constant from `lib/utils.ts`
   (with `invalidState` and `fieldFrame` for fields) rather than retyping it.
@@ -1130,8 +1253,10 @@ shows.
   A dialog panel is a `tabIndex=-1` focus target that Radix can focus, so it
   carries `outline-none`: Safari draws its own blue `outline: auto` there and
   ignores our `outline-color`. Any new focusable container needs the same.
-- **Close buttons** on Modal, Sheet and DialogContent are a `ghost-muted`
-  `size="icon-sm"` Button (32px, accent square on hover) at `top-2 right-2`.
+- **Close buttons**: every Modal, Sheet and DialogContent uses its built-in
+  close (a phone sheet with a handle has none), a `ghost-muted` `size="icon-sm"` Button (32px, accent square on
+  hover) at `top-2 right-2`, the artifact sheet included; never hand-place
+  another X.
 - **Disabled**: buttons (Button, Accordion, Tabs) use
   `disabled:pointer-events-none disabled:opacity-50`, so the pointer passes
   through. Fields (Input, SelectTrigger, Switch, Textarea, CommandInput,
@@ -1150,15 +1275,18 @@ shadow-lg` in both themes: the knob is white on any track, and a white knob
   publish-error panel, which float over the canvas at popover elevation
   (`shadow-md`, `z-20`); the chunk viewer's and file tree's search result
   lists (`shadow-md`, in-page `z-20`, their results are `CommandItem`s inside
-  the search frame); and the Hero model picker's menu (an Approved
-  exception). Don't add new ones: a floating panel is a `Popover`,
+  the search frame); the sliding panel in `navigation/SidebarLevel.tsx`,
+  which casts a horizontal shadow while it slides; and the Hero model
+  picker's menu (both Approved exceptions). Don't add new ones: a floating panel is a `Popover`,
   `DropdownMenu` or `Modal`, which carry their own shadow and stacking; never
   an `absolute` div with a shadow and a hand-picked `z-*`.
 - **Stacking**: `z-10` sticky headers and table heads inside a page;
   `z-20` in-page floating chrome (banners, scroll-to-bottom, drag
   handles); `z-50` overlays, modals, sheets, toasts and the one-frame
   bar-tint strips; `z-200` every portalled floating list (popover, menu,
-  select, tooltip), so it opens above a Modal without an override. Do not invent values in between. The app
+  select, tooltip), so it opens above a Modal without an override. Do not
+  invent values in between: a `z-*` outside 0, 10, 20, 50, 200 and `auto` is
+  rejected (enforced). The app
   shell uses the low layers too: the phone top bar is `z-10`, and the
   sidebar and its phone backdrop are `z-20`, so an open sidebar dims the bar.
 
@@ -1189,7 +1317,7 @@ list stays reviewable.
 | `agents/workflow/WorkflowPreview.tsx`                               | `shadcn/no-restyle`             | The Preview minimap's node rows are status tiles: the fill, border and ring follow the step (success, primary running + pulse, destructive, muted pending; a ring on the active row) and stay pinned on hover, pending and running rows stay unfaded while disabled, and clickable rows dim to 80% on hover. No Button variant is status-tinted. The rule reports each string inside `cn(...)`, so it's a `/* eslint-disable */` … `/* eslint-enable */` pair around the `className` attribute. |
 | `agents/schedules/ScheduleFormModal.tsx`                            | `shadcn/no-restyle`             | The schedule's name is the dialog's editable title: a `bare` Input with title type (`text-xl font-semibold`), so the dialog passes `hideTitle`. One disable.                                                                                                                                                                                                                                                                                                                                    |
 | `components/MermaidRenderer.tsx`                                    | `shadcn/no-restyle`             | The zoom − / + buttons sit on the diagram's `bg-black/70` overlay, where ghost's accent hover paints a light square with dark text; they hover to `white/20` with white text instead, in both themes. Two disables.                                                                                                                                                                                                                                                                             |
-| `Hero.tsx`                                                          | `shadcn/no-restyle`             | The landing page's demo cards are `Button outline lg pill`, but each is a two-line pill (a title over a clamped 12px query), so it undoes lg's height, the base's one-row layout, weight and nowrap: `h-auto w-full flex-col items-start gap-0 py-3.5 text-left text-xs font-normal whitespace-normal`. One disable (phase 7, 36a).                                                                                                                                                             |
+| `Hero.tsx`                                                          | `shadcn/no-restyle`             | The landing page's demo cards are `Button outline lg pill`, but each is a two-line pill (a title over a clamped 12px query), so it undoes lg's height, the base's one-row layout, weight and nowrap: `h-auto w-full flex-col items-start gap-0 py-3.5 text-left text-xs font-normal whitespace-normal`. One disable.                                                                                                                                                                            |
 | `Navigation.tsx`, `conversation/ConversationTile.tsx`               | `shadcn/no-restyle`             | A sidebar row whose link has sibling buttons (an agent's pin, a conversation's menu and rename Save / Cancel) keeps its fill while the pointer is on a sibling or the menu is open (`group-hover:bg-sidebar-accent`, `bg-sidebar-accent`), and `pr-10` keeps the label clear of the buttons. ConversationTile's `cn(...)` needs a `/* eslint-disable */` … `/* eslint-enable */` pair.                                                                                                          |
 | `admin/Usage.tsx`                                                   | `shadcn/no-restyle`             | The Top users id is a `link inline` Button inside a mono table cell; it keeps the cell's type and wraps (`font-mono text-xs font-normal whitespace-normal text-left`). One disable.                                                                                                                                                                                                                                                                                                             |
 | `agents/workflow/WorkflowBuilder.tsx`                               | `shadcn/no-restyle`             | The "Learn more" links in the Set state and Condition nodes' 12px hints keep the sentence's size and weight (`text-xs font-normal` on `link inline`). Two disables.                                                                                                                                                                                                                                                                                                                             |
@@ -1197,35 +1325,23 @@ list stays reviewable.
 | `settings/PersonalAccessTokens.tsx`                                 | `shadcn/no-restyle`             | Token scope chips are identifiers, so the `neutral` Badge is set in mono (`font-mono`). One disable.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `agents/workflow/WorkflowPreview.tsx`                               | `shadcn/no-restyle`             | A step's state changes (keys and values the app serialised) are `neutral` Badges set in mono (`font-mono`), like token scopes. One disable.                                                                                                                                                                                                                                                                                                                                                     |
 | `settings/traces/TraceChips.tsx`                                    | `shadcn/no-restyle`             | Trace stat chips (durations, counts) use tabular figures so they don't jitter between rows (`tabular-nums` on Badge). One disable.                                                                                                                                                                                                                                                                                                                                                              |
-| `modals/MCPServerModal.tsx`                                         | `shadcn/no-restyle`             | The authorization link inside the test-result Alert keeps the Alert's status colour (`text-current` on `link inline`). One disable (phase 11, 63g).                                                                                                                                                                                                                                                                                                                                             |
-| `components/MermaidRenderer.tsx`                                    | `shadcn/no-restyle`             | The zoom readout between − and + is a `link inline` Button on the `bg-black/70` overlay; it keeps the overlay's white 12px regular text (`text-xs font-normal text-current`). One disable, beside the two zoom-button ones above (phase 11, 63g).                                                                                                                                                                                                                                               |
-| `conversation/SharedConversation.tsx`                               | `shadcn/no-restyle`             | The "DocsGPT" link sits in the `/share/:id` page's regular-weight byline (`font-normal`). One disable (phase 11, 63g).                                                                                                                                                                                                                                                                                                                                                                          |
-| `conversation/ConversationBubble.tsx`                               | `shadcn/no-restyle`             | A source card's URL row is a `link inline` around an `<a>`: foreground at rest, primary on hover, regular weight, truncating (`text-current font-normal hover:text-primary underline-offset-2 max-w-full justify-start`). One disable (phase 11, 63g).                                                                                                                                                                                                                                          |
-| `admin/Overview.tsx`                                                | `shadcn/no-restyle`             | "View in Audit" under the denied-sign-ins tile keeps the tile's destructive tone at hint size (`text-destructive text-xs font-normal`). One disable (phase 11, 63g).                                                                                                                                                                                                                                                                                                                            |
-| `settings/PairDeviceModal.tsx`                                      | `shadcn/no-restyle`             | The install link in Pair a remote machine sits in a 12px hint (`text-xs font-normal`, `self-start` in its column). One disable (phase 11, 63g).                                                                                                                                                                                                                                                                                                                                                 |
+| `modals/MCPServerModal.tsx`                                         | `shadcn/no-restyle`             | The authorization link inside the test-result Alert keeps the Alert's status colour (`text-current` on `link inline`). One disable.                                                                                                                                                                                                                                                                                                                                                             |
+| `components/MermaidRenderer.tsx`                                    | `shadcn/no-restyle`             | The zoom readout between − and + is a `link inline` Button on the `bg-black/70` overlay; it keeps the overlay's white 12px regular text (`text-xs font-normal text-current`). One disable, beside the two zoom-button ones above.                                                                                                                                                                                                                                                               |
+| `conversation/SharedConversation.tsx`                               | `shadcn/no-restyle`             | The "DocsGPT" link sits in the `/share/:id` page's regular-weight byline (`font-normal`). One disable.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `conversation/ConversationBubble.tsx`                               | `shadcn/no-restyle`             | A source card's URL row is a `link inline` around an `<a>`: foreground at rest, primary on hover, regular weight, truncating (`text-current font-normal hover:text-primary underline-offset-2 max-w-full justify-start`). One disable.                                                                                                                                                                                                                                                          |
+| `admin/Overview.tsx`                                                | `shadcn/no-restyle`             | "View in Audit" under the denied-sign-ins tile keeps the tile's destructive tone at hint size (`text-destructive text-xs font-normal`). One disable.                                                                                                                                                                                                                                                                                                                                            |
+| `settings/PairDeviceModal.tsx`                                      | `shadcn/no-restyle`             | The install link in Pair a remote machine sits in a 12px hint (`text-xs font-normal`, `self-start` in its column). One disable.                                                                                                                                                                                                                                                                                                                                                                 |
 | `agents/workflow/WorkflowBuilder.tsx`                               | `shadcn/no-restyle`             | The publish-error Alert floats over the canvas with its close button in the top-right corner, so it pads `pr-10` to keep a long title clear of the button. One disable.                                                                                                                                                                                                                                                                                                                         |
+| `conversation/MarkdownAnswer.tsx`                                   | `no-restricted-syntax`          | Markdown answer tables render the model's own table markup with its own styling, so they stay a raw `<table>`.                                                                                                                                                                                                                                                                                                                                                                                  |
 
 Note that a multi-line reason has to be a `/* ... */` block comment;
 consecutive `//` lines only disable the next comment line, not the code.
 
 ## Removed classes
 
-The lint reports classes Tailwind cannot generate; `no-unknown-classes` is at
-`error`, so none remain. For the record, they were bugs, not missing
-configuration:
-
-- `xs:` has never been a breakpoint here (not in the old Tailwind v3 config
-  either), so `xs:px-3`, `xs:text-xs` never applied. Remove them rather than
-  declaring the breakpoint, which would change layouts that were never seen.
-- `text-s`, `dark:text-gray`, `w-inherit` are typos for `text-sm`,
-  `dark:text-gray-*` and `w-[inherit]`.
-- `agents-container`, `conversations-container`, `loader` and `mermaid` are
-  unused hooks; nothing selects them. Before deleting a class like these,
-  grep for it in `querySelector` and `classList` calls too. `star` was
-  defined at runtime by a `<style>` element in `components/Notification.tsx`;
-  it is now the `notification-star` utility in `src/index.css`. `msc-spacer`
-  was a lookup hook for `ConversationMessages`' `querySelector`; the lookup
-  now uses the primitive's `[data-message-scroller-spacer]` attribute.
+`no-unknown-classes` is at `error`. Before deleting a class the lint calls
+unknown, grep for it in `querySelector`, `classList` and `data-` lookups; a
+class can be a hook for code rather than a style.
 
 ## Live style guide
 
@@ -1237,20 +1353,21 @@ variant or token, add it there too.
 
 ## Cleanup playbook
 
-Every `shadcn/*` rule is at `error`, and `lint-staged` runs the lint on
-staged files, so a violation blocks the commit. Work one file at a time and
+Every `shadcn/*` rule is at `error`, and on commit `lint-staged` runs
+`npm run lint-fix` and `npm run format` (both over the whole `src`), so a
+violation blocks the commit. Work one file at a time and
 keep every step green.
 
-1. **See the state.** `npm run lint:design` prints warnings by rule and the
-   worst files. `npm run lint:design -- --file src/settings/Teams.tsx` lists
-   every warning in one file with the fix the message proposes;
+1. **See the state.** `npm run lint:design` prints violations (`shadcn/*`
+   and the design `no-restricted-syntax` selectors) by rule and the worst
+   files. `npm run lint:design -- --file src/settings/Teams.tsx`
+   lists every violation in one file with the fix the message proposes;
    `-- --rule no-raw-colors` lists files for one rule.
-2. **Pick a file, read it whole**, then fix all of its design warnings in
+2. **Pick a file, read it whole**, then fix all of its design violations in
    one pass. Map raw colours to tokens (table above), replace hand-rolled
    boxes, pills, tiles, spinners and dropzones with the `ui/` components,
    and move Button/Input/Select overrides onto `variant`, `size`, `shape`.
-   Delete the `dark:` twin of every class you tokenise. Remove classes the
-   lint calls unknown (`xs:*`, `text-s`, `dark:text-gray`, unused hooks).
+   Delete the `dark:` twin of every class you tokenise.
 3. **Do not restyle `ui/` components from a page.** If a treatment is used
    in more than one place and no variant fits, add the variant in the
    component file, add it to `src/design/DesignSystem.tsx`, and document it
@@ -1259,26 +1376,23 @@ keep every step green.
    translations (`t(...)` keys stay). Only classes and component choice
    change. Prettier with the Tailwind plugin reorders classes; run
    `npm run lint-fix` rather than fighting it.
-5. **Verify per file**: `npx eslint <file>` (zero `shadcn/*` warnings),
+5. **Verify per file**: `npx eslint <file>` (zero errors),
    `npx tsc --noEmit -p tsconfig.json`, `npm test`, and look at the screen
    in the running app (`npm run dev`, then the page that renders the file)
    in both themes.
 
 Known traps:
 
-- `npm run lint` also reports 6 pre-existing Prettier errors (union-type
-  line breaks in `cronBuilder.ts`, `types/schedule.ts`, `types/workflow.ts`,
-  `api/client.ts`, `models/misc.ts`, `models/types.ts`) and about 330
-  TypeScript warnings unrelated to design; `npm run lint-fix` clears the
-  Prettier ones.
+- `npm run lint` reports 0 errors and about 325 `@typescript-eslint`
+  warnings (mostly `no-explicit-any`) unrelated to design; `tsc` is clean.
 - Port 5173 may be held by another checkout; check the Vite banner shows
   this repo's path before trusting what you see.
-- `components/SkeletonLoader.tsx` renders `Skeleton` in its table, logs,
-  default and files layouts and its four tile mirrors (Card + bars). Its
-  analysis, dropdown, chunk-card and connected-state layouts still pulse their
-  own surface; move them onto Card + `Skeleton` the same way when you touch
-  them. (`agents/schedules/StatusBadge.tsx` is a status→variant map over
-  `Badge`, not a wrapper; keep it.)
+- `components/SkeletonLoader.tsx`: the chunk, source, tool, add-tool and
+  agent layouts are Card mirrors with `Skeleton` bars, and the `chatbot`,
+  table, logs, default, analysis, connected-state and files layouts use
+  `Skeleton`; none pulses its own surface. `renderFilesSection` (and the
+  GoogleDrivePicker box it mirrors) is still a raw `border rounded-lg` box;
+  move both onto `Card` when you touch them.
 
 ## Working with the lint
 
@@ -1286,6 +1400,11 @@ Known traps:
 cd frontend && npm run lint
 ```
 
-All `shadcn/*` rules are `error`. Add a variant or token only when a treatment
+All `shadcn/*` rules are `error`, and so are the DESIGN.md selectors under
+`no-restricted-syntax`: `eslint/design-rules.js` (class and markup rules,
+tested in `src/design/designRules.lint.test.ts`), `eslint/card-surfaces.js`
+(tested in `src/design/cardSurfaces.lint.test.ts`) and the viewport-height
+and focus-return entries in `eslint.config.js`. Add a new checkable rule as
+a selector there, with a test and a line here. Add a variant or token only when a treatment
 is used in more than one place and none of the existing ones fits; a single
 special case gets a disable comment with a reason.
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index 92b303b8..4b2d6fdd 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -8,6 +8,40 @@ import prettier from 'eslint-plugin-prettier';
 import globals from 'globals';
 
 import { cardSurfaceSelectors } from './eslint/card-surfaces.js';
+import { everywhereSelectors, pageSelectors } from './eslint/design-rules.js';
+
+// Selectors every file gets: viewport heights, focus return, card surfaces.
+// On iOS Safari vh (and h-screen, which is 100vh) is the viewport with the
+// toolbars hidden, so a vh height overflows the visible screen. w-screen is
+// vw, which the toolbars don't change, so it stays allowed.
+const baseSyntaxRules = [
+  ...['Literal[value=/\\dvh\\b/]', 'TemplateElement[value.raw=/\\dvh\\b/]'].map(
+    (selector) => ({
+      selector,
+      message:
+        'vh is the toolbar-hidden viewport on iOS Safari. Use dvh for the app shell and caps on things that pop up, svh for a fixed-size panel in a page that scrolls, or max-h-sheet for a bottom sheet. See DESIGN.md.',
+    }),
+  ),
+  ...[
+    'Literal[value=/(^|[\\s:])(min-|max-)?h-screen\\b/]',
+    'TemplateElement[value.raw=/(^|[\\s:])(min-|max-)?h-screen\\b/]',
+  ].map((selector) => ({
+    selector,
+    message:
+      "Tailwind's screen heights (h-/min-h-/max-h-screen) are the toolbar-hidden viewport on iOS Safari, taller than the visible screen. Use h-dvh / min-h-dvh, or svh for a fixed panel. See DESIGN.md.",
+  })),
+  // Modal, Sheet and DialogContent return focus to what had it on open
+  // (ui/use-focus-return.ts). A hand-rolled return focuses the trigger
+  // even after a tap, which lights its ring on iOS.
+  {
+    selector: 'JSXAttribute[name.name="onCloseAutoFocus"]',
+    message:
+      'Modal, Sheet and DialogContent already return focus to what had it on open (ui/use-focus-return.ts). Don\'t hand-roll onCloseAutoFocus. See DESIGN.md "Focus return".',
+  },
+  // Nothing on a filled tile repeats its muted fill (DESIGN.md "Card
+  // surfaces").
+  ...cardSurfaceSelectors,
+];
 
 export default [
   {
@@ -15,16 +49,11 @@ export default [
       'node_modules/',
       'dist/',
       'prettier.config.cjs',
-      '.eslintrc.cjs',
-      'env.d.ts',
       'public/',
-      'assets/',
-      'vite-env.d.ts',
       '.prettierignore',
       'package-lock.json',
       'package.json',
       'postcss.config.cjs',
-      'tailwind.config.cjs',
       'tsconfig.json',
       'tsconfig.node.json',
       'vite.config.ts',
@@ -86,38 +115,14 @@ export default [
           ],
         },
       ],
-      // On iOS Safari vh (and h-screen, which is 100vh) is the viewport with
-      // the toolbars hidden, so a vh height overflows the visible screen.
-      // w-screen is vw, which the toolbars don't change, so it stays allowed.
+      // DESIGN.md rules a selector can check: viewport heights, focus return
+      // and card surfaces (baseSyntaxRules above), plus the class and markup
+      // rules in eslint/design-rules.js.
       'no-restricted-syntax': [
         'error',
-        ...[
-          'Literal[value=/\\dvh\\b/]',
-          'TemplateElement[value.raw=/\\dvh\\b/]',
-        ].map((selector) => ({
-          selector,
-          message:
-            'vh is the toolbar-hidden viewport on iOS Safari. Use dvh for the app shell and caps on things that pop up, svh for a fixed-size panel in a page that scrolls, or max-h-sheet for a bottom sheet. See DESIGN.md.',
-        })),
-        ...[
-          'Literal[value=/(^|[\\s:])(min-|max-)?h-screen\\b/]',
-          'TemplateElement[value.raw=/(^|[\\s:])(min-|max-)?h-screen\\b/]',
-        ].map((selector) => ({
-          selector,
-          message:
-            "Tailwind's screen heights (h-/min-h-/max-h-screen) are the toolbar-hidden viewport on iOS Safari, taller than the visible screen. Use h-dvh / min-h-dvh, or svh for a fixed panel. See DESIGN.md.",
-        })),
-        // Modal, Sheet and DialogContent return focus to what had it on open
-        // (ui/use-focus-return.ts). A hand-rolled return focuses the trigger
-        // even after a tap, which lights its ring on iOS.
-        {
-          selector: 'JSXAttribute[name.name="onCloseAutoFocus"]',
-          message:
-            'Modal, Sheet and DialogContent already return focus to what had it on open (ui/use-focus-return.ts). Don\'t hand-roll onCloseAutoFocus. See DESIGN.md "Focus return".',
-        },
-        // Nothing on a filled tile repeats its muted fill (DESIGN.md "Card
-        // surfaces").
-        ...cardSurfaceSelectors,
+        ...baseSyntaxRules,
+        ...everywhereSelectors,
+        ...pageSelectors,
       ],
       // Design-system rules (@shadcn/lint). Tokens, variants and the
       // approved exceptions are documented in DESIGN.md.
@@ -210,23 +215,7 @@ export default [
               allow: ['layout'],
               message: {
                 default:
-                  '"{{className}}" is not allowed on <{{component}}>: use Alert variant (default, destructive, success, warning, info) from {{file}}.',
-              },
-            },
-            {
-              pattern: '^Checkbox$',
-              allow: ['layout'],
-              message: {
-                default:
-                  '"{{className}}" is not allowed on <Checkbox>: use size from {{file}}.',
-              },
-            },
-            {
-              pattern: '^Dropzone$',
-              allow: ['layout'],
-              message: {
-                default:
-                  '"{{className}}" is not allowed on <Dropzone>: use size (default, compact); colours, border and radius follow the drag state in {{file}}.',
+                  '"{{className}}" is not allowed on <{{component}}>: use Alert variant (default, neutral, success, warning, info, destructive) from {{file}}.',
               },
             },
             {
@@ -253,14 +242,6 @@ export default [
               pattern: '^Spinner$',
               allow: ['layout', 'color'],
             },
-            {
-              pattern: '^Progress$',
-              allow: ['layout'],
-            },
-            {
-              pattern: '^(Toast|ToastViewport)$',
-              allow: ['layout'],
-            },
             {
               pattern: '^(ToastContent|ToastItem|ToastFooter)$',
               allow: ['layout', 'spacing'],
@@ -272,10 +253,6 @@ export default [
               pattern: '^MessageScroller(Viewport|Content)$',
               allow: ['layout', 'spacing'],
             },
-            {
-              pattern: '^OptionCard$',
-              allow: ['layout'],
-            },
             {
               pattern: '^(CardHeader|CardContent|CardFooter|CardAction)$',
               allow: ['layout', 'spacing', 'gap-*', 'bg-muted/*'],
@@ -339,6 +316,22 @@ export default [
     rules: {
       'shadcn/no-restyle': 'off',
       'no-restricted-imports': 'off',
+      // ui/ defines the parts the page rules ask for (the table, the
+      // checkbox, the floating label's transition-all), so only the
+      // everywhere rules apply here.
+      'no-restricted-syntax': [
+        'error',
+        ...baseSyntaxRules,
+        ...everywhereSelectors,
+      ],
+    },
+  },
+  {
+    // Tests hold class strings as fixtures (often asserting their absence),
+    // so the class-token rules don't apply to them.
+    files: ['src/**/*.test.{ts,tsx}'],
+    rules: {
+      'no-restricted-syntax': ['error', ...baseSyntaxRules],
     },
   },
   {
diff --git a/frontend/eslint/design-rules.d.ts b/frontend/eslint/design-rules.d.ts
new file mode 100644
index 00000000..aaf3e40d
--- /dev/null
+++ b/frontend/eslint/design-rules.d.ts
@@ -0,0 +1,3 @@
+type Selector = { selector: string; message: string };
+export declare const everywhereSelectors: Selector[];
+export declare const pageSelectors: Selector[];
diff --git a/frontend/eslint/design-rules.js b/frontend/eslint/design-rules.js
new file mode 100644
index 00000000..8473de38
--- /dev/null
+++ b/frontend/eslint/design-rules.js
@@ -0,0 +1,92 @@
+// Class and markup rules from DESIGN.md that a `no-restricted-syntax`
+// selector can check. `everywhereSelectors` apply to ui/ too; `pageSelectors`
+// are about app code composing ui/ parts, so ui/ (which defines those parts)
+// is exempt from them.
+
+// A class token in a string: start of string, a space or a variant colon
+// before it; a space or the end after it.
+const cls = (body) => `/(^|[\\s:])${body}(\\s|$)/`;
+
+const inStrings = (regex, message) =>
+  [`Literal[value=${regex}]`, `TemplateElement[value.raw=${regex}]`].map(
+    (selector) => ({ selector, message }),
+  );
+
+/** @type {{ selector: string, message: string }[]} */
+export const everywhereSelectors = [
+  ...inStrings(
+    cls('break-all'),
+    'break-all splits ordinary words mid-word. Use wrap-break-word for prose and wrap-anywhere for a long token (URL, id, email). See DESIGN.md "Typography roles".',
+  ),
+  ...inStrings(
+    cls('rounded'),
+    'Bare `rounded` is a fixed 4px, outside the radius scale. Use rounded-sm (6px, bars), rounded-md (8px) or the role radius in DESIGN.md "Radius by role".',
+  ),
+  ...inStrings(
+    '/(^|[\\s:])(min|max)-\\[|\\[@media/',
+    'No custom breakpoints (min-[…], max-[…], [@media…]). Phone / desktop is lg; sm and md only reflow content. See DESIGN.md "Breakpoints".',
+  ),
+  ...inStrings(
+    '/(^|[\\s:])-?z-(?!(0|10|20|50|200|auto)(\\s|$))/',
+    'z-index comes from the stacking layers: z-10 sticky headers, z-20 in-page floating chrome, z-50 overlays, z-200 portalled floating lists. See DESIGN.md "Stacking".',
+  ),
+  ...inStrings(
+    '/(^|\\s)(focus|focus-visible|focus-within):ring-2(\\s|$)/',
+    'The focus ring is ring-3 ring-ring/50 on focus-visible (fields: focus-within on a frame the same way). ring-2 is only for selection rings. See DESIGN.md "Focus ring".',
+  ),
+  {
+    selector:
+      'ImportDeclaration[source.value="lucide-react"] > ImportSpecifier[imported.name=/^(Loader|Loader2|LoaderCircle)$/]',
+    message:
+      'A loader is <Spinner> (ui/spinner) or <LoadingState>, never a lucide loader icon. See DESIGN.md "Spinner and Skeleton".',
+  },
+];
+
+/** @type {{ selector: string, message: string }[]} */
+export const pageSelectors = [
+  ...inStrings(
+    cls('transition-all'),
+    'Transition only the property that changes: transition-colors by default, transition-transform for chevrons, transition-shadow for a ring. See DESIGN.md "Motion".',
+  ),
+  ...inStrings(
+    '/(^|\\s)hover:scale-(?!x-|y-)/',
+    'Hover is a fill, border or text-colour change, never a scale. See DESIGN.md "Motion".',
+  ),
+  ...inStrings(
+    '/(^|[\\s:])bg-primary\\u002f10(\\s|$)/',
+    'The brand soft fill is bg-secondary text-secondary-foreground, not bg-primary/10. See DESIGN.md "Colour tokens".',
+  ),
+  {
+    selector:
+      'JSXOpeningElement[name.name="input"] > JSXAttribute[name.name="type"][value.value="checkbox"]',
+    message:
+      'A checkbox is <Checkbox> (ui/checkbox); native boxes take the OS accent and ignore dark mode. See DESIGN.md "Checkbox".',
+  },
+  {
+    selector:
+      'JSXOpeningElement[name.name="Button"] > JSXAttribute[name.name="title"]',
+    message:
+      'An icon-only button is <IconButton label> (its tooltip is the label); a labelled Button needs no title. See DESIGN.md "Tooltip and IconButton".',
+  },
+  ...[
+    'JSXOpeningElement[name.name="SheetContent"] > JSXAttribute[name.name="className"] Literal[value=/(^|[\\s:])(max-)?w-/]',
+    'JSXOpeningElement[name.name="SheetContent"] > JSXAttribute[name.name="className"] TemplateElement[value.raw=/(^|[\\s:])(max-)?w-/]',
+  ].map((selector) => ({
+    selector,
+    message:
+      'A drawer\'s width comes from SheetContent size (default 384px, detail 576px, wide 800px), never a w-* or max-w-* class. See DESIGN.md "Modal, not Dialog".',
+  })),
+  {
+    selector: 'JSXOpeningElement[name.name="table"]',
+    message:
+      'Every table is ui/table (Table, TableHead, TableRow…), never a raw <table>. See DESIGN.md "Table".',
+  },
+  ...[
+    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] Literal[value=/(^|\\s)(underline|text-primary)(\\s|$)/]',
+    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] TemplateElement[value.raw=/(^|\\s)(underline|text-primary)(\\s|$)/]',
+  ].map((selector) => ({
+    selector,
+    message:
+      'A link is <Button variant="link" size="inline" asChild> around the <a>, never a raw <a> styled as a link. See DESIGN.md "Button".',
+  })),
+];
diff --git a/frontend/scripts/design-lint-report.mjs b/frontend/scripts/design-lint-report.mjs
index b7d64e80..aa9c9b4a 100644
--- a/frontend/scripts/design-lint-report.mjs
+++ b/frontend/scripts/design-lint-report.mjs
@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 /**
- * Summarise @shadcn/lint warnings from ESLint JSON output.
+ * Summarise design-lint violations from ESLint JSON output: the @shadcn/lint
+ * rules and the DESIGN.md selectors under no-restricted-syntax
+ * (eslint/design-rules.js, eslint/card-surfaces.js, viewport heights).
  *
  *   npm run lint:design              rules × counts, then the 25 worst files
  *   npm run lint:design -- --rule no-raw-colors   files for one rule
@@ -26,10 +28,12 @@ const rows = [];
 for (const file of results) {
   const rel = file.filePath.replace(`${process.cwd()}/`, '');
   for (const m of file.messages) {
-    if (!m.ruleId?.startsWith('shadcn/')) continue;
+    const design =
+      m.ruleId?.startsWith('shadcn/') || m.ruleId === 'no-restricted-syntax';
+    if (!design) continue;
     rows.push({
       file: rel,
-      rule: m.ruleId.slice(7),
+      rule: m.ruleId.replace(/^shadcn\//, ''),
       line: m.line,
       msg: m.message,
     });
@@ -47,7 +51,7 @@ if (onlyFile) {
   const mine = rows.filter(
     (r) => r.file === onlyFile || r.file.endsWith(onlyFile),
   );
-  console.log(`${mine.length} design warnings in ${onlyFile}\n`);
+  console.log(`${mine.length} design violations in ${onlyFile}\n`);
   for (const r of mine.sort((a, b) => a.line - b.line)) {
     console.log(
       `${pad(r.line, 5)}  ${r.rule}\n       ${r.msg.split(' See frontend/DESIGN.md')[0]}\n`,
@@ -55,14 +59,14 @@ if (onlyFile) {
   }
 } else if (onlyRule) {
   const mine = rows.filter((r) => r.rule === onlyRule);
-  console.log(`${mine.length} warnings for shadcn/${onlyRule}\n`);
+  console.log(`${mine.length} violations of ${onlyRule}\n`);
   const byFile = new Map();
   for (const r of mine) byFile.set(r.file, (byFile.get(r.file) ?? 0) + 1);
   for (const [f, n] of [...byFile.entries()].sort((a, b) => b[1] - a[1]))
     console.log(`${pad(n, 5)}  ${f}`);
 } else {
   console.log(
-    `${rows.length} design warnings in ${new Set(rows.map((r) => r.file)).size} files\n`,
+    `${rows.length} design violations in ${new Set(rows.map((r) => r.file)).size} files\n`,
   );
   console.log('By rule:');
   for (const [rule, n] of count('rule')) console.log(`${pad(n, 5)}  ${rule}`);
diff --git a/frontend/src/Navigation.tsx b/frontend/src/Navigation.tsx
index f576da40..690d2bd0 100644
--- a/frontend/src/Navigation.tsx
+++ b/frontend/src/Navigation.tsx
@@ -40,7 +40,7 @@ import {
 import ConversationTile from './conversation/ConversationTile';
 import { useMediaQuery } from './hooks';
 import useTokenAuth from './hooks/useTokenAuth';
-import { cn } from './lib/utils';
+import { cn, overlayScrim } from './lib/utils';
 import ConfirmationModal from './modals/ConfirmationModal';
 import JWTModal from './modals/JWTModal';
 import SearchConversationsModal from './modals/SearchConversationsModal';
@@ -402,7 +402,10 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
     <>
       {isMobile && navOpen && (
         <div
-          className="fixed inset-0 z-20 bg-black opacity-50 transition-opacity duration-300"
+          className={cn(
+            'animate-in fade-in-0 fixed inset-0 z-20',
+            overlayScrim,
+          )}
           onClick={() => setNavOpen(false)}
         />
       )}
diff --git a/frontend/src/agents/AgentLogs.test.tsx b/frontend/src/agents/AgentLogs.test.tsx
new file mode 100644
index 00000000..8cbda4a4
--- /dev/null
+++ b/frontend/src/agents/AgentLogs.test.tsx
@@ -0,0 +1,73 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+vi.mock('react-redux', () => ({ useSelector: () => 'token' }));
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getAgent: () =>
+      Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            id: 'a1',
+            name: 'Carrier FAQ',
+            last_used_at: null,
+          }),
+      }),
+  },
+}));
+vi.mock('../settings/Analytics', () => ({
+  default: () => <div data-testid="analytics" />,
+}));
+vi.mock('../settings/Logs', () => ({
+  default: () => <div data-testid="logs" />,
+}));
+vi.mock('./components/GuardrailEvents', () => ({ default: () => null }));
+vi.mock('../navigation/SectionPageHeader', () => ({
+  CurrentSectionHeader: () => <h1>Logs</h1>,
+}));
+vi.mock('../navigation/SectionPills', () => ({ default: () => null }));
+
+import AgentLogs from './AgentLogs';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('AgentLogs', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  // A3: the same toolbar as Overview and Schedules, the agent in its byline.
+  it('names the agent in the shared agent toolbar', async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={['/agents/manage/logs/a1']}>
+          <Routes>
+            <Route
+              path="/agents/manage/logs/:agentId"
+              element={<AgentLogs />}
+            />
+          </Routes>
+        </MemoryRouter>,
+      );
+    });
+    const toolbar = container.querySelector('[data-slot="page-toolbar"]')!;
+    expect(toolbar.textContent).toContain('Carrier FAQ');
+    expect(toolbar.textContent).toContain('agents.logs.noUsageHistory');
+    expect(toolbar.querySelector('[data-slot="separator"]')).not.toBeNull();
+  });
+});
diff --git a/frontend/src/agents/AgentLogs.tsx b/frontend/src/agents/AgentLogs.tsx
index a286ae28..114e3a7b 100644
--- a/frontend/src/agents/AgentLogs.tsx
+++ b/frontend/src/agents/AgentLogs.tsx
@@ -7,8 +7,8 @@ import userService from '../api/services/userService';
 import { selectToken } from '../preferences/preferenceSlice';
 import Analytics from '../settings/Analytics';
 import Logs from '../settings/Logs';
-import { formatDateTime } from '../utils/dateTimeUtils';
 import SectionShell from '../navigation/SectionShell';
+import AgentPageToolbar, { LastUsedMeta } from './components/AgentPageToolbar';
 import GuardrailEvents from './components/GuardrailEvents';
 import { Agent } from './types';
 
@@ -39,26 +39,16 @@ export default function AgentLogs() {
   }, [agentId, token]);
 
   return (
-    <SectionShell pills>
-      <div className="flex flex-col gap-3">
-        {agent && (
-          <div className="flex flex-col gap-1">
-            <p className="text-foreground">{agent.name}</p>
-            <p className="text-muted-foreground text-xs">
-              {agent.last_used_at
-                ? t('agents.logs.lastUsedAt') +
-                  ' ' +
-                  formatDateTime(agent.last_used_at)
-                : t('agents.logs.noUsageHistory')}
-            </p>
-          </div>
-        )}
-      </div>
+    <SectionShell>
+      {agent && (
+        <AgentPageToolbar
+          name={agent.name}
+          meta={<LastUsedMeta lastUsedAt={agent.last_used_at} />}
+        />
+      )}
       {agentId && (
         <>
-          <div className="mt-8">
-            <Analytics agentId={agentId} />
-          </div>
+          <Analytics agentId={agentId} />
           <GuardrailEvents agentId={agentId} />
           <div className="mt-8">
             <Logs
diff --git a/frontend/src/agents/AgentPageHeader.tsx b/frontend/src/agents/AgentPageHeader.tsx
index 38966892..45139091 100644
--- a/frontend/src/agents/AgentPageHeader.tsx
+++ b/frontend/src/agents/AgentPageHeader.tsx
@@ -39,10 +39,11 @@ type AgentPageHeaderProps = {
 };
 
 /**
- * Shared chrome for the agent sub-pages (Overview/Edit, Logs, Schedules).
- *
- * Top: shadcn Breadcrumb (`Agents > <agent name> > <current page>`).
- * Bottom: underline-style sub-nav linking between the agent's sub-pages.
+ * The workflow builder's toolbar chrome: a Breadcrumb (`Agents > <agent
+ * name> > <current page>`) and underline tab links to the agent's Overview,
+ * Logs and Schedules. The builder is full-screen with no sidebar, so it needs
+ * its own way between them. Section pages use `components/AgentPageToolbar`
+ * and the sidebar (or `SectionPills` on a phone) instead.
  */
 export default function AgentPageHeader({
   agentId,
diff --git a/frontend/src/agents/AgentPreview.tsx b/frontend/src/agents/AgentPreview.tsx
index 74a1494b..0c0d681c 100644
--- a/frontend/src/agents/AgentPreview.tsx
+++ b/frontend/src/agents/AgentPreview.tsx
@@ -1,8 +1,9 @@
-import { MessageSquare } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
+import { EmptyState } from '@/components/ui/empty-state';
+
 import MessageInput from '../components/MessageInput';
 import ConversationMessages from '../conversation/ConversationMessages';
 import { Query } from '../conversation/conversationModels';
@@ -13,7 +14,6 @@ import {
   fetchPreviewAnswer,
   handlePreviewAbort,
   resendQuery,
-  resetPreview,
   selectPreviewQueries,
   selectPreviewStatus,
 } from './agentPreviewSlice';
@@ -96,12 +96,13 @@ export default function AgentPreview() {
     }
   };
 
+  // Closing the drawer unmounts the preview: stop a stream in flight, but
+  // keep the chat. The page that hosts the drawer decides when it starts
+  // over (New chat, a save, leaving the page).
   useEffect(() => {
-    dispatch(resetPreview());
     return () => {
       if (fetchStream.current) fetchStream.current.abort();
       handlePreviewAbort();
-      dispatch(resetPreview());
     };
   }, [dispatch]);
 
@@ -115,13 +116,12 @@ export default function AgentPreview() {
     <div className="relative h-full w-full">
       <div className="scrollbar-overlay absolute inset-0 bottom-[180px] overflow-hidden px-4 pt-4 [&>div>div]:w-full! [&>div>div]:max-w-none!">
         {queries.length === 0 ? (
-          <section className="flex h-full flex-col items-center justify-center">
-            <div className="bg-muted mb-2 flex size-14 shrink-0 items-center justify-center rounded-xl">
-              <MessageSquare className="text-muted-foreground size-6" />
-            </div>
-            <p className="text-foreground text-sm font-medium">
-              {t('agents.preview.emptyTitle')}
-            </p>
+          <section className="flex h-full items-center justify-center">
+            <EmptyState
+              size="sm"
+              illustration="none"
+              title={t('agents.preview.emptyTitle')}
+            />
           </section>
         ) : (
           <ConversationMessages
diff --git a/frontend/src/agents/NewAgent.test.tsx b/frontend/src/agents/NewAgent.test.tsx
index 9b96baea..08b06060 100644
--- a/frontend/src/agents/NewAgent.test.tsx
+++ b/frontend/src/agents/NewAgent.test.tsx
@@ -1,6 +1,6 @@
 import { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import { MemoryRouter } from 'react-router-dom';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
 
 import type { MultiSelectPopoverItem } from '../components/MultiSelectPopover';
 
@@ -16,16 +16,26 @@ const mockState = {
     prompts: [],
     agentFolders: [],
   },
+  agentPreview: { queries: [], status: 'idle' },
 };
 
+const mocks = vi.hoisted(() => {
+  const jsonResponse = (body: unknown, ok = true) =>
+    Promise.resolve({ ok, json: () => Promise.resolve(body) });
+  return {
+    jsonResponse,
+    dispatch: vi.fn(),
+    getAgent: vi.fn(() => jsonResponse({})),
+    createAgent: vi.fn(() => jsonResponse({ message: 'Name is taken' }, false)),
+  };
+});
+const { jsonResponse } = mocks;
+
 vi.mock('react-redux', () => ({
   useSelector: (selector: (state: unknown) => unknown) => selector(mockState),
-  useDispatch: () => vi.fn(),
+  useDispatch: () => mocks.dispatch,
 }));
 
-const jsonResponse = (body: unknown, ok = true) =>
-  Promise.resolve({ ok, json: () => Promise.resolve(body) });
-
 vi.mock('../api/services/userService', () => ({
   default: {
     getUserTools: () =>
@@ -40,8 +50,8 @@ vi.mock('../api/services/userService', () => ({
         ],
       }),
     getAgentFolders: () => jsonResponse({ folders: [] }),
-    getAgent: () => jsonResponse({}),
-    createAgent: () => jsonResponse({ message: 'Name is taken' }, false),
+    getAgent: mocks.getAgent,
+    createAgent: mocks.createAgent,
     updateAgent: () => jsonResponse({}),
     deleteAgent: () => jsonResponse({}),
     createPrompt: () => jsonResponse({}),
@@ -95,9 +105,22 @@ vi.mock('../modals/AgentDetailsModal', () => ({ default: () => null }));
 vi.mock('../teams/ShareToTeamModal', () => ({ default: () => null }));
 vi.mock('../modals/ConfirmationModal', () => ({ default: () => null }));
 vi.mock('../preferences/PromptsModal', () => ({ default: () => null }));
-vi.mock('../navigation/SectionPills', () => ({ default: () => null }));
+vi.mock('../navigation/SectionPills', () => ({
+  default: () => <div data-testid="section-pills" />,
+}));
 vi.mock('../navigation/SectionPageHeader', () => ({
-  CurrentSectionHeader: () => null,
+  CurrentSectionHeader: ({
+    title,
+    titleAction,
+  }: {
+    title?: React.ReactNode;
+    titleAction?: React.ReactNode;
+  }) => (
+    <div>
+      {title ? <h1>{title}</h1> : null}
+      {titleAction}
+    </div>
+  ),
 }));
 vi.mock('../components/FileUpload', () => ({ FileUpload: () => null }));
 vi.mock('../components/SourcesPopoverFooter', () => ({ default: () => null }));
@@ -132,6 +155,9 @@ describe('NewAgent form', () => {
   afterEach(async () => {
     await act(async () => root.unmount());
     container.remove();
+    mocks.dispatch.mockClear();
+    mocks.getAgent.mockClear();
+    mocks.createAgent.mockClear();
   });
 
   const render = async () => {
@@ -182,33 +208,176 @@ describe('NewAgent form', () => {
     }
   });
 
-  it('titles each form panel with a SectionHeader spaced by the panel gap', async () => {
+  // A1a: three grouped sections instead of six one-field panels.
+  it('groups the form into Basics, Knowledge and behaviour, and Model', async () => {
     await render();
     const titles = Array.from(
       container.querySelectorAll('[data-slot="section-header"] > h2'),
     ).map((h) => h.textContent);
-    expect(titles).toEqual(
+    expect(titles).toEqual([
+      'agents.form.sections.basics',
+      'agents.form.sections.knowledge',
+      'agents.form.sections.model',
+    ]);
+    const basics = Array.from(
+      container.querySelectorAll('[data-slot="section-header"]'),
+    ).find((h) => h.textContent === 'agents.form.sections.basics')!;
+    expect(basics.parentElement!.className.split(' ')).toEqual(
+      expect.arrayContaining(['flex', 'flex-col', 'gap-5']),
+    );
+  });
+
+  // On a phone the avatar sits beside Name and Description spans the row;
+  // from sm the avatar spans both rows beside the fields.
+  it('lays Basics out as avatar beside Name, Description full width on a phone', async () => {
+    await render();
+    const name = container.querySelector(
+      'input[placeholder="agents.form.placeholders.agentName"]',
+    )!;
+    const grid = name.closest('.grid')!;
+    expect(grid.className).toContain('grid-cols-[auto_1fr]');
+    const description = container
+      .querySelector(
+        'textarea[placeholder="agents.form.placeholders.describeAgent"]',
+      )!
+      .closest('[data-slot="form-field"]')!;
+    expect(description.className).toContain('col-span-2');
+    expect(description.className).toContain('sm:col-start-2');
+  });
+
+  it('labels every picker with a floating label', async () => {
+    await render();
+    const labels = Array.from(
+      container.querySelectorAll('[data-slot="form-field-label"]'),
+    ).map((l) => l.textContent);
+    expect(labels).toEqual(
       expect.arrayContaining([
-        'agents.form.sections.meta',
-        'agents.form.sections.source',
+        'agents.form.labels.name',
+        'agents.form.labels.description',
+        'agents.form.labels.sources',
         'agents.form.sections.tools',
         'agents.form.sections.agentType',
         'agents.form.sections.models',
       ]),
     );
-    const meta = Array.from(
-      container.querySelectorAll('[data-slot="section-header"]'),
-    ).find((h) => h.textContent === 'agents.form.sections.meta')!;
-    expect(meta.parentElement!.className.split(' ')).toEqual(
-      expect.arrayContaining(['flex', 'flex-col', 'gap-5']),
+  });
+
+  it('puts Sources beside Tools in a two-up field grid', async () => {
+    await render();
+    const [sources, tools] = Array.from(
+      container.querySelectorAll('[data-testid="picker"] > button'),
     );
-    expect((meta.nextElementSibling as HTMLElement).className).not.toContain(
-      'mt-5',
+    const grid = sources.closest('.grid')!;
+    expect(grid.className).toContain('sm:grid-cols-2');
+    expect(grid.contains(tools)).toBe(true);
+  });
+
+  it('titles the new-agent page and puts its actions in the agent toolbar', async () => {
+    await render();
+    expect(container.querySelector('h1')?.textContent).toBe('agents.newAgent');
+    const toolbar = container.querySelector('[data-slot="page-toolbar"]')!;
+    expect(toolbar.textContent).toContain('agents.form.byline.new');
+    expect(toolbar.contains(buttonByText('agents.form.buttons.publish'))).toBe(
+      true,
     );
   });
 
-  // Decision 64: the Advanced header is a section-toggle with a leading
-  // lucide chevron; the panel draws the focus ring.
+  // Before publishing, Preview can only say "Publish to preview", so it is a
+  // ⋯ item beside the title rather than a toolbar button.
+  it('drops the New agent title once the agent is saved', async () => {
+    await render();
+    mocks.createAgent.mockImplementationOnce(() =>
+      jsonResponse({ id: 'agent-1' }),
+    );
+    await act(async () =>
+      buttonByText('agents.form.buttons.saveDraft').click(),
+    );
+    expect(container.querySelector('h1')?.textContent).not.toBe(
+      'agents.newAgent',
+    );
+  });
+
+  // The preview talks to the saved agent; Redux must hold that snapshot, not
+  // the unsaved form, or the preview picks up an unsaved model.
+  it('keeps the preview on the saved agent while editing a published one', async () => {
+    mocks.getAgent.mockImplementationOnce(() =>
+      jsonResponse({
+        id: 'agent-1',
+        name: 'Saved name',
+        description: 'Saved description',
+        status: 'published',
+        agent_type: 'classic',
+        prompt_id: 'default',
+      }),
+    );
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={['/agents/edit/agent-1']}>
+          <Routes>
+            <Route
+              path="/agents/edit/:agentId"
+              element={<NewAgent mode="edit" />}
+            />
+          </Routes>
+        </MemoryRouter>,
+      );
+    });
+    const name = container.querySelector<HTMLInputElement>(
+      'input[placeholder="agents.form.placeholders.agentName"]',
+    )!;
+    await act(async () => setNativeValue(name, 'Unsaved name'));
+
+    const pushed = mocks.dispatch.mock.calls
+      .map(([action]) => action)
+      .filter((a) => a?.type === 'preference/setSelectedAgent' && a.payload);
+    expect(pushed.length).toBeGreaterThan(0);
+    for (const action of pushed) {
+      expect(action.payload.name).toBe('Saved name');
+    }
+  });
+
+  it('offers Preview from the title-row menu until the agent is published', async () => {
+    await render();
+    const toolbar = container.querySelector('[data-slot="page-toolbar"]')!;
+    expect(
+      Array.from(toolbar.querySelectorAll('button')).some((b) =>
+        b.textContent?.includes('agents.form.sections.preview'),
+      ),
+    ).toBe(false);
+    const menu = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="agents.form.buttons.moreActions"]',
+    )!;
+    expect(menu.getAttribute('data-size')).toBe('icon');
+    // Beside the page title, not in the toolbar row.
+    expect(menu.closest('[data-slot="page-toolbar"]')).toBeNull();
+    expect(menu.parentElement!.querySelector('h1')).not.toBeNull();
+    await act(async () => {
+      menu.dispatchEvent(
+        new PointerEvent('pointerdown', { bubbles: true, button: 0 }),
+      );
+    });
+    const preview = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).find((item) => item.textContent === 'agents.form.sections.preview')!;
+    await act(async () => preview.click());
+    const sheet = document.querySelector('[data-slot="sheet-content"]')!;
+    expect(sheet.textContent).toContain('agents.form.preview.publishTitle');
+  });
+
+  it('stretches the main button on a phone', async () => {
+    await render();
+    const publish = buttonByText('agents.form.buttons.publish');
+    expect(publish.className).toContain('flex-1');
+    expect(publish.className).toContain('sm:flex-none');
+  });
+
+  // The sidebar (and the agent card's menu) already switch between an
+  // agent's pages, so the pages carry no pill row.
+  it('has no destination pills', async () => {
+    await render();
+    expect(container.querySelector('[data-testid="section-pills"]')).toBeNull();
+  });
+
   it('renders the Advanced header as a section-toggle', async () => {
     await render();
     const toggle = buttonByText('agents.form.sections.advanced');
@@ -265,11 +434,14 @@ describe('NewAgent form', () => {
 
   it('renders Save draft and Publish as pill button variants', async () => {
     await render();
+    // A4: one purple button per page; every header button is field pill.
     const draft = buttonByText('agents.form.buttons.saveDraft');
-    expect(draft.getAttribute('data-variant')).toBe('outline-primary');
+    expect(draft.getAttribute('data-variant')).toBe('outline');
+    expect(draft.getAttribute('data-size')).toBe('field');
     expect(draft.getAttribute('data-shape')).toBe('pill');
     const publish = buttonByText('agents.form.buttons.publish');
     expect(publish.getAttribute('data-variant')).toBe('default');
+    expect(publish.getAttribute('data-size')).toBe('field');
     expect(publish.getAttribute('data-shape')).toBe('pill');
     expect(publish.disabled).toBe(true);
   });
@@ -283,6 +455,7 @@ describe('NewAgent form', () => {
     await act(async () => setNativeValue(name, 'Support bot'));
     const cancel = buttonByText('agents.form.buttons.cancel');
     expect(cancel.getAttribute('data-variant')).toBe('ghost');
+    expect(cancel.getAttribute('data-size')).toBe('field');
     expect(cancel.getAttribute('data-shape')).toBe('pill');
   });
 
@@ -360,22 +533,4 @@ describe('NewAgent form', () => {
       expect(label.className).toContain('bg-background');
     }
   });
-
-  it('draws the preview area as a subtle panel', async () => {
-    await render();
-    const hint = Array.from(container.querySelectorAll('p')).find(
-      (p) => p.textContent === 'agents.form.preview.publishedPreview',
-    )!;
-    const panel = hint.closest<HTMLElement>('[data-slot="card"]')!;
-    expect(panel.dataset.variant).toBe('subtle');
-  });
-
-  it('shows the preview placeholder illustration as decorative images', async () => {
-    await render();
-    const images = container.querySelectorAll('img[alt=""]');
-    expect(images).toHaveLength(2);
-    for (const img of images) {
-      expect(img.getAttribute('aria-hidden')).toBe('true');
-    }
-  });
 });
diff --git a/frontend/src/agents/NewAgent.tsx b/frontend/src/agents/NewAgent.tsx
index a8b832eb..0de8b87d 100644
--- a/frontend/src/agents/NewAgent.tsx
+++ b/frontend/src/agents/NewAgent.tsx
@@ -1,5 +1,13 @@
 import isEqual from 'lodash/isEqual';
-import { ChevronRight, CircleCheck, CircleX, Database } from 'lucide-react';
+import {
+  ChevronRight,
+  CircleCheck,
+  CircleX,
+  Database,
+  Info,
+  Play,
+  SquarePen,
+} from 'lucide-react';
 import React, {
   useCallback,
   useEffect,
@@ -17,6 +25,7 @@ import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
 import { ActionMenu } from '@/components/ui/dropdown-menu';
+import { EmptyState } from '@/components/ui/empty-state';
 import { FormField } from '@/components/ui/form-field';
 import { Input } from '@/components/ui/input';
 
@@ -36,8 +45,6 @@ import { cn } from '@/lib/utils';
 import devicesService from '../api/services/devicesService';
 import modelService from '../api/services/modelService';
 import userService from '../api/services/userService';
-import ScienceSparkDarkIcon from '../assets/science-spark-dark.svg';
-import ScienceSparkIcon from '../assets/science-spark.svg';
 import { FileUpload } from '../components/FileUpload';
 import {
   MultiSelectPopover,
@@ -73,13 +80,15 @@ import {
   getToolDisplayName,
   isClassicAgentToolVisible,
 } from '../utils/toolUtils';
-import { CurrentSectionHeader } from '../navigation/SectionPageHeader';
 import { agentsListPath } from './paths';
-import SectionPills from '../navigation/SectionPills';
 import GuardrailsSection, {
   guardrailsIncomplete,
 } from './components/GuardrailsSection';
 import AgentPreview from './AgentPreview';
+import { resetPreview, selectPreviewStatus } from './agentPreviewSlice';
+import AgentPageToolbar, { LastUsedMeta } from './components/AgentPageToolbar';
+import AgentPreviewSheet from './components/AgentPreviewSheet';
+import SectionShell from '../navigation/SectionShell';
 import { Agent, ToolSummary } from './types';
 import WorkflowBuilder from './workflow/WorkflowBuilder';
 
@@ -180,6 +189,20 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
   const tokenLimitSwitchId = useId();
   const requestLimitSwitchId = useId();
   const promptOverrideSwitchId = useId();
+  const sourcesPickerId = useId();
+  const toolsPickerId = useId();
+  const modelsPickerId = useId();
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const previewStatus = useSelector(selectPreviewStatus);
+
+  // The preview chat outlives its drawer: closing and reopening keeps the
+  // conversation. It starts over on New chat, after a save, and on leaving.
+  useEffect(() => {
+    dispatch(resetPreview());
+    return () => {
+      dispatch(resetPreview());
+    };
+  }, [dispatch]);
   const [isAdvancedSectionExpanded, setIsAdvancedSectionExpanded] =
     useState(false);
 
@@ -520,6 +543,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
       };
       setAgent(updatedAgent);
       initialAgentRef.current = updatedAgent;
+      // The saved agent is what the preview talks to; start its chat over.
+      dispatch(resetPreview());
 
       if (effectiveMode === 'new' || effectiveMode === 'draft') {
         setEffectiveMode('edit');
@@ -777,7 +802,11 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
   }, [selectedTools]);
 
   useEffect(() => {
-    if (isPublishable()) dispatch(setSelectedAgent(agent));
+    // Editing a published agent: the preview talks to the saved version, so
+    // Redux keeps that snapshot (the preview reads its model from it).
+    const saved = effectiveMode === 'edit' ? initialAgentRef.current : null;
+    if (saved) dispatch(setSelectedAgent(saved));
+    else if (isPublishable()) dispatch(setSelectedAgent(agent));
 
     if (!modeConfig[effectiveMode].trackChanges) {
       setHasChanges(true);
@@ -798,233 +827,243 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
       jsonSchemaText !== initialJsonSchemaText;
     setHasChanges(isChanged);
   }, [agent, dispatch, effectiveMode, imageFile, jsonSchemaText]);
-  // Only show the agent sub-nav once the agent has an id (i.e. not the bare
-  // ``new`` mode). The sub-nav links to Logs/Schedules which require an id.
-  const showAgentNav = effectiveMode === 'edit' && Boolean(agent.id);
+
+  const isPublished = agent.status === 'published';
+  const agentDisplayName =
+    agent.name?.trim() || t('agents.pageHeader.fallbackName');
+
+  // Page-level actions live in the ⋯ beside the title. Until the agent is
+  // published the preview can only say "Publish to preview", so Preview is a
+  // menu item then and a toolbar button after.
+  const menuOptions = [
+    ...(isPublished
+      ? []
+      : [
+          {
+            label: t('agents.form.sections.preview'),
+            icon: Play,
+            onClick: () => setPreviewOpen(true),
+          },
+        ]),
+    ...(modeConfig[effectiveMode].showAccessDetails
+      ? [
+          {
+            label: t('agents.form.buttons.accessDetails'),
+            onClick: () => setAgentDetails('ACTIVE'),
+          },
+        ]
+      : []),
+    // Sharing is owner-only — hidden for agents shared into the workspace by
+    // a team (ownership === 'team').
+    ...(modeConfig[effectiveMode].showAccessDetails &&
+    agent.ownership !== 'team' &&
+    agent.id
+      ? [
+          {
+            label: t('agents.shareWithTeam'),
+            onClick: () => setShareModalOpen(true),
+          },
+        ]
+      : []),
+  ];
+
+  // At most three buttons, so the row fits a phone; the main one stretches
+  // across it there.
+  const headerActions = (
+    <div className="flex flex-wrap items-center gap-2">
+      {hasChanges && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="field"
+          shape="pill"
+          onClick={handleCancel}
+        >
+          {t('agents.form.buttons.cancel')}
+        </Button>
+      )}
+      {modeConfig[effectiveMode].showSaveDraft && (
+        <Button
+          type="button"
+          variant="outline"
+          size="field"
+          shape="pill"
+          disabled={isDraftBlocked()}
+          loading={draftLoading}
+          onClick={handleSaveDraft}
+        >
+          {t('agents.form.buttons.saveDraft')}
+        </Button>
+      )}
+      {isPublished && (
+        <Button
+          type="button"
+          variant="outline"
+          size="field"
+          shape="pill"
+          onClick={() => setPreviewOpen(true)}
+        >
+          <Play />
+          {t('agents.form.sections.preview')}
+        </Button>
+      )}
+      <Button
+        type="button"
+        size="field"
+        shape="pill"
+        disabled={!isPublishable() || !hasChanges}
+        loading={publishLoading}
+        onClick={handlePublish}
+        className="flex-1 sm:flex-none"
+      >
+        {modeConfig[effectiveMode].buttonText}
+      </Button>
+    </div>
+  );
 
   return (
-    <div className="flex min-h-dvh flex-col p-4 pb-2 md:p-12 md:pt-4 md:pb-3 xl:h-dvh">
-      {agent.agent_type === 'workflow' && (
-        <div className="mt-4 w-full">
-          <WorkflowBuilder />
-        </div>
-      )}
-      <div className="flex w-full flex-wrap items-center justify-between gap-2">
-        {showAgentNav ? <CurrentSectionHeader /> : <span aria-hidden />}
-        <div className="flex flex-wrap items-center gap-2">
-          {hasChanges && (
-            <Button
-              type="button"
-              variant="ghost"
-              shape="pill"
-              onClick={handleCancel}
-            >
-              {t('agents.form.buttons.cancel')}
-            </Button>
-          )}
-          {modeConfig[effectiveMode].showSaveDraft && (
-            <Button
-              type="button"
-              variant="outline-primary"
-              shape="pill"
-              disabled={isDraftBlocked()}
-              loading={draftLoading}
-              onClick={handleSaveDraft}
-            >
-              {t('agents.form.buttons.saveDraft')}
-            </Button>
-          )}
-          <Button
-            type="button"
-            disabled={!isPublishable() || !hasChanges}
-            loading={publishLoading}
-            onClick={handlePublish}
-            shape="pill"
-          >
-            {modeConfig[effectiveMode].buttonText}
-          </Button>
-          {modeConfig[effectiveMode].showAccessDetails && (
-            <ActionMenu
-              triggerLabel={t('agents.form.buttons.moreActions')}
-              options={[
-                {
-                  label: t('agents.form.buttons.accessDetails'),
-                  onClick: () => setAgentDetails('ACTIVE'),
-                },
-                // Sharing is owner-only — hidden for agents shared into the
-                // workspace by a team (ownership === 'team').
-                ...(agent.ownership !== 'team' && agent.id
-                  ? [
-                      {
-                        label: t('agents.shareWithTeam'),
-                        onClick: () => setShareModalOpen(true),
-                      },
-                    ]
-                  : []),
-              ]}
+    <SectionShell
+      title={effectiveMode === 'new' ? t('agents.newAgent') : undefined}
+      titleAction={
+        <ActionMenu
+          size="toolbar"
+          triggerLabel={t('agents.form.buttons.moreActions')}
+          options={menuOptions}
+        />
+      }
+    >
+      {agent.agent_type === 'workflow' && <WorkflowBuilder />}
+      <AgentPageToolbar
+        intro={agent.id ? undefined : t('agents.form.byline.new')}
+        name={agentDisplayName}
+        status={
+          isPublished ? (
+            <Badge variant="success">{t('agents.form.status.published')}</Badge>
+          ) : (
+            <Badge variant="neutral">{t('agents.card.draft')}</Badge>
+          )
+        }
+        meta={
+          effectiveMode === 'edit' ? (
+            <LastUsedMeta lastUsedAt={agent.last_used_at} />
+          ) : undefined
+        }
+        actions={headerActions}
+      >
+        {submitError && (
+          <Alert variant="destructive" className="mb-6">
+            <CircleX aria-hidden="true" />
+            <AlertDescription>{submitError}</AlertDescription>
+          </Alert>
+        )}
+      </AgentPageToolbar>
+      <div className="flex flex-col gap-5">
+        <Card variant="subtle" padding="lg" className="gap-5">
+          <SectionHeader title={t('agents.form.sections.basics')} />
+          {/* Phone: the avatar beside Name, Description across the row.
+              From sm: the avatar spans both rows beside the fields. */}
+          <div className="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-5 sm:items-start">
+            <FileUpload
+              showPreview
+              size="tile"
+              currentImage={agent.image || undefined}
+              onUpload={handleUpload}
+              onRemove={() => setImageFile(null)}
+              uploadText={t('agents.form.labels.avatar')}
+              className="sm:row-span-2"
             />
-          )}
-        </div>
-      </div>
-      {showAgentNav && <SectionPills className="mt-4" />}
-      {submitError && (
-        <Alert variant="destructive" className="mt-3">
-          <CircleX aria-hidden="true" className="size-4" />
-          <AlertDescription>{submitError}</AlertDescription>
-        </Alert>
-      )}
-      <div className="mt-3 flex w-full flex-1 grid-cols-5 flex-col gap-10 xl:grid xl:gap-5 xl:overflow-hidden">
-        <div className="scrollbar-overlay col-span-2 flex flex-col gap-5 xl:max-h-full xl:overflow-y-auto xl:pr-3">
-          <Card variant="subtle" padding="lg" className="gap-5">
-            <SectionHeader title={t('agents.form.sections.meta')} />
-            <div className="flex flex-col gap-5">
-              <FormField
-                labelSurface="background"
-                label={t('agents.form.labels.name')}
-              >
-                <Input
-                  shape="pill"
-                  type="text"
-                  value={agent.name}
-                  placeholder={t('agents.form.placeholders.agentName')}
-                  onChange={(e) => setAgent({ ...agent, name: e.target.value })}
-                />
-              </FormField>
-              <FormField
-                labelSurface="background"
-                label={t('agents.form.labels.description')}
-              >
-                <Textarea
-                  size="lg"
-                  className="h-32"
-                  placeholder={t('agents.form.placeholders.describeAgent')}
-                  value={agent.description}
-                  onChange={(e) =>
-                    setAgent({ ...agent, description: e.target.value })
-                  }
-                />
-              </FormField>
-              <FileUpload
-                showPreview
-                size="compact"
-                previewSize={56}
-                onUpload={handleUpload}
-                onRemove={() => setImageFile(null)}
-                uploadText={[
-                  {
-                    text: t('agents.form.upload.clickToUpload'),
-                    highlight: true,
-                  },
-                  {
-                    text: t('agents.form.upload.dragAndDrop'),
-                  },
-                ]}
-              />
-            </div>
-          </Card>
-          <Card variant="subtle" padding="lg">
-            <SectionHeader title={t('agents.form.sections.source')} />
-            <div>
-              <div className="flex flex-wrap items-center gap-1">
-                <MultiSelectPopover
-                  open={isSourcePopupOpen}
-                  onOpenChange={setIsSourcePopupOpen}
-                  title={t('agents.form.sourcePopup.title')}
-                  items={sourceItems}
-                  selectedIds={Array.from(selectedSourceIds)}
-                  onToggle={(id) => {
-                    const next = new Set(selectedSourceIds);
-                    if (next.has(id)) next.delete(id);
-                    else next.add(id);
-                    setSelectedSourceIds(next);
-                  }}
-                  searchPlaceholder={t(
-                    'agents.form.sourcePopup.searchPlaceholder',
-                  )}
-                  emptyMessage={t('agents.form.sourcePopup.noOptionsMessage')}
-                  footer={
-                    <SourcesPopoverFooter
-                      onNavigate={() => setIsSourcePopupOpen(false)}
-                      onUploadClick={handleUploadClick}
-                    />
-                  }
-                  trigger={
-                    <Button
-                      type="button"
-                      variant="combobox"
-                      size="field"
-                      shape="pill"
-                      ref={sourceAnchorButtonRef}
-                      data-placeholder={
-                        selectedSourceIds.size > 0 ? undefined : ''
-                      }
-                      className="w-full justify-start text-left"
-                    >
-                      <span
-                        className="truncate"
-                        title={selectedSourceNames.join(', ')}
-                      >
-                        {sourceTriggerLabel}
-                      </span>
-                    </Button>
-                  }
-                />
-              </div>
-              {selectedSourceIds.size === 0 && (
-                <p className="text-muted-foreground mt-1.5 text-xs">
-                  {t('agents.form.sourcePopup.noSourceHint')}
-                </p>
-              )}
-            </div>
-          </Card>
-          <Card variant="subtle" padding="lg">
-            <div className="flex flex-wrap items-end gap-1">
-              <div className="min-w-20 grow basis-full sm:basis-0">
-                <Prompts
-                  prompts={prompts}
-                  selectedPrompt={
-                    prompts.find((prompt) => prompt.id === agent.prompt_id) ||
-                    // Owner-resolved name from the agent payload: lets a team
-                    // member see the owner's prompt name (which isn't in their
-                    // own prompts list). 'public' hides owner-only edit/share
-                    // affordances on a prompt the viewer doesn't own.
-                    (agent.prompt_name
-                      ? {
-                          name: agent.prompt_name,
-                          id: agent.prompt_id || 'default',
-                          type: 'public',
-                        }
-                      : prompts[0]) || {
-                      name: 'default',
-                      id: 'default',
-                      type: 'public',
-                    }
-                  }
-                  onSelectPrompt={(name, id, type) =>
-                    setAgent({ ...agent, prompt_id: id })
-                  }
-                  setPrompts={(newPrompts) => dispatch(setPrompts(newPrompts))}
-                  title={t('agents.form.sections.prompt')}
-                  titleAs="heading"
-                  showAddButton={false}
-                  dropdownProps={{ className: 'w-full' }}
-                />
-              </div>
-              <Button
-                type="button"
-                variant="outline-primary"
-                size="field"
+            <FormField
+              labelSurface="background"
+              label={t('agents.form.labels.name')}
+            >
+              <Input
                 shape="pill"
-                onClick={() => setAddPromptModal('ACTIVE')}
-                className="min-w-20 shrink-0 basis-full sm:basis-auto"
-              >
-                {t('agents.form.buttons.add')}
-              </Button>
-            </div>
-          </Card>
-          <Card variant="subtle" padding="lg">
-            <SectionHeader title={t('agents.form.sections.tools')} />
-            <div className="flex flex-wrap items-center gap-1">
+                type="text"
+                value={agent.name}
+                placeholder={t('agents.form.placeholders.agentName')}
+                onChange={(e) => setAgent({ ...agent, name: e.target.value })}
+              />
+            </FormField>
+            <FormField
+              labelSurface="background"
+              label={t('agents.form.labels.description')}
+              className="col-span-2 sm:col-span-1 sm:col-start-2"
+            >
+              <Textarea
+                size="lg"
+                className="h-32 sm:h-24"
+                placeholder={t('agents.form.placeholders.describeAgent')}
+                value={agent.description}
+                onChange={(e) =>
+                  setAgent({ ...agent, description: e.target.value })
+                }
+              />
+            </FormField>
+          </div>
+        </Card>
+        <Card variant="subtle" padding="lg" className="gap-5">
+          <SectionHeader title={t('agents.form.sections.knowledge')} />
+          <div className="grid grid-cols-1 gap-x-4 gap-y-5 sm:grid-cols-2">
+            <FormField
+              id={sourcesPickerId}
+              labelSurface="background"
+              label={t('agents.form.labels.sources')}
+              hint={
+                selectedSourceIds.size === 0
+                  ? t('agents.form.sourcePopup.noSourceHint')
+                  : undefined
+              }
+            >
+              <MultiSelectPopover
+                open={isSourcePopupOpen}
+                onOpenChange={setIsSourcePopupOpen}
+                title={t('agents.form.sourcePopup.title')}
+                items={sourceItems}
+                selectedIds={Array.from(selectedSourceIds)}
+                onToggle={(id) => {
+                  const next = new Set(selectedSourceIds);
+                  if (next.has(id)) next.delete(id);
+                  else next.add(id);
+                  setSelectedSourceIds(next);
+                }}
+                searchPlaceholder={t(
+                  'agents.form.sourcePopup.searchPlaceholder',
+                )}
+                emptyMessage={t('agents.form.sourcePopup.noOptionsMessage')}
+                footer={
+                  <SourcesPopoverFooter
+                    onNavigate={() => setIsSourcePopupOpen(false)}
+                    onUploadClick={handleUploadClick}
+                  />
+                }
+                trigger={
+                  <Button
+                    type="button"
+                    variant="combobox"
+                    size="field"
+                    shape="pill"
+                    id={sourcesPickerId}
+                    ref={sourceAnchorButtonRef}
+                    data-placeholder={
+                      selectedSourceIds.size > 0 ? undefined : ''
+                    }
+                    className="w-full justify-start text-left"
+                  >
+                    <span
+                      className="truncate"
+                      title={selectedSourceNames.join(', ')}
+                    >
+                      {sourceTriggerLabel}
+                    </span>
+                  </Button>
+                }
+              />
+            </FormField>
+            <FormField
+              id={toolsPickerId}
+              labelSurface="background"
+              label={t('agents.form.sections.tools')}
+            >
               <MultiSelectPopover
                 open={isToolsPopupOpen}
                 onOpenChange={setIsToolsPopupOpen}
@@ -1059,6 +1098,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                     variant="combobox"
                     size="field"
                     shape="pill"
+                    id={toolsPickerId}
                     ref={toolAnchorButtonRef}
                     data-placeholder={selectedTools.length > 0 ? undefined : ''}
                     className="w-full justify-start text-left"
@@ -1074,11 +1114,58 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   </Button>
                 }
               />
+            </FormField>
+            <div className="flex items-center gap-2 sm:col-span-2">
+              <div className="min-w-0 flex-1">
+                <Prompts
+                  prompts={prompts}
+                  selectedPrompt={
+                    prompts.find((prompt) => prompt.id === agent.prompt_id) ||
+                    // Owner-resolved name from the agent payload: lets a team
+                    // member see the owner's prompt name (which isn't in their
+                    // own prompts list). 'public' hides owner-only edit/share
+                    // affordances on a prompt the viewer doesn't own.
+                    (agent.prompt_name
+                      ? {
+                          name: agent.prompt_name,
+                          id: agent.prompt_id || 'default',
+                          type: 'public',
+                        }
+                      : prompts[0]) || {
+                      name: 'default',
+                      id: 'default',
+                      type: 'public',
+                    }
+                  }
+                  onSelectPrompt={(name, id, type) =>
+                    setAgent({ ...agent, prompt_id: id })
+                  }
+                  setPrompts={(newPrompts) => dispatch(setPrompts(newPrompts))}
+                  title={t('agents.form.sections.prompt')}
+                  titleAs="field"
+                  labelSurface="background"
+                  showAddButton={false}
+                />
+              </div>
+              <Button
+                type="button"
+                variant="outline-primary"
+                size="field"
+                shape="pill"
+                onClick={() => setAddPromptModal('ACTIVE')}
+              >
+                {t('agents.form.buttons.add')}
+              </Button>
             </div>
-          </Card>
-          <Card variant="subtle" padding="lg">
-            <SectionHeader title={t('agents.form.sections.agentType')} />
-            <div>
+          </div>
+        </Card>
+        <Card variant="subtle" padding="lg" className="gap-5">
+          <SectionHeader title={t('agents.form.sections.model')} />
+          <div className="grid grid-cols-1 gap-x-4 gap-y-5 sm:grid-cols-2">
+            <FormField
+              labelSurface="background"
+              label={t('agents.form.sections.agentType')}
+            >
               <Select
                 value={agent.agent_type || undefined}
                 onValueChange={(value) =>
@@ -1098,11 +1185,12 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   ))}
                 </SelectContent>
               </Select>
-            </div>
-          </Card>
-          <Card variant="subtle" padding="lg">
-            <SectionHeader title={t('agents.form.sections.models')} />
-            <div className="flex flex-col gap-3">
+            </FormField>
+            <FormField
+              id={modelsPickerId}
+              labelSurface="background"
+              label={t('agents.form.sections.models')}
+            >
               <MultiSelectPopover
                 open={isModelsPopupOpen}
                 onOpenChange={setIsModelsPopupOpen}
@@ -1142,6 +1230,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                     variant="combobox"
                     size="field"
                     shape="pill"
+                    id={modelsPickerId}
                     ref={modelAnchorButtonRef}
                     data-placeholder={
                       selectedModelIds.size > 0 ? undefined : ''
@@ -1159,262 +1248,257 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   </Button>
                 }
               />
-              {selectedModelIds.size > 0 && (
-                <FormField
-                  labelSurface="background"
-                  label={t('agents.form.labels.defaultModel')}
-                >
-                  <Select
-                    value={agent.default_model_id || undefined}
-                    onValueChange={(value) =>
-                      setAgent({ ...agent, default_model_id: value })
-                    }
-                  >
-                    <SelectTrigger className="w-full" shape="pill" size="field">
-                      <SelectValue
-                        placeholder={t(
-                          'agents.form.placeholders.selectDefaultModel',
-                        )}
-                      />
-                    </SelectTrigger>
-                    <SelectContent>
-                      {availableModels
-                        .filter((m) => selectedModelIds.has(m.id))
-                        .map((m) => (
-                          <SelectItem key={m.id} value={m.id}>
-                            {m.display_name}
-                          </SelectItem>
-                        ))}
-                    </SelectContent>
-                  </Select>
-                </FormField>
-              )}
-            </div>
-          </Card>
-          <Card variant="subtle" padding="lg" className="gap-5">
-            {/* The heading wraps the toggle: a button's children are
-                presentational, so a heading inside it is lost to screen readers. */}
-            <h2>
-              <Button
-                type="button"
-                variant="section-toggle"
-                onClick={() =>
-                  setIsAdvancedSectionExpanded(!isAdvancedSectionExpanded)
-                }
-                size="sm"
-                aria-expanded={isAdvancedSectionExpanded}
-                className="-ml-3 w-fit justify-start"
+            </FormField>
+            {selectedModelIds.size > 0 && (
+              <FormField
+                labelSurface="background"
+                label={t('agents.form.labels.defaultModel')}
               >
-                <ChevronRight
-                  aria-hidden="true"
-                  className={cn(
-                    'transition-transform duration-200',
-                    isAdvancedSectionExpanded && 'rotate-90',
-                  )}
-                />
-                <span className="text-lg font-semibold">
-                  {t('agents.form.sections.advanced')}
-                </span>
-              </Button>
-            </h2>
-            {isAdvancedSectionExpanded && (
-              <div>
-                <FormField
-                  labelSurface="background"
-                  label={t('agents.form.advanced.jsonSchema')}
-                  hint={t('agents.form.advanced.jsonSchemaDescription')}
+                <Select
+                  value={agent.default_model_id || undefined}
+                  onValueChange={(value) =>
+                    setAgent({ ...agent, default_model_id: value })
+                  }
                 >
-                  <Textarea
-                    size="lg"
-                    value={jsonSchemaText}
-                    onChange={(e) => validateAndSetJsonSchema(e.target.value)}
-                    placeholder={`{
-  "type": "object",
-  "properties": {
-    "name": {"type": "string"},
-    "email": {"type": "string"}
-  },
-  "required": ["name", "email"],
-  "additionalProperties": false
-}`}
-                    rows={9}
-                    className="font-mono"
-                  />
-                </FormField>
-                {jsonSchemaText.trim() !== '' && (
-                  <div
-                    className={cn(
-                      'mt-2 flex items-center gap-2 text-sm',
-                      jsonSchemaValid ? 'text-success' : 'text-destructive',
-                    )}
-                  >
-                    {jsonSchemaValid ? (
-                      <CircleCheck className="size-4" aria-hidden="true" />
-                    ) : (
-                      <CircleX className="size-4" aria-hidden="true" />
-                    )}
-                    {jsonSchemaValid
-                      ? t('agents.form.advanced.validJson')
-                      : t('agents.form.advanced.invalidJson')}
-                  </div>
+                  <SelectTrigger className="w-full" shape="pill" size="field">
+                    <SelectValue
+                      placeholder={t(
+                        'agents.form.placeholders.selectDefaultModel',
+                      )}
+                    />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {availableModels
+                      .filter((m) => selectedModelIds.has(m.id))
+                      .map((m) => (
+                        <SelectItem key={m.id} value={m.id}>
+                          {m.display_name}
+                        </SelectItem>
+                      ))}
+                  </SelectContent>
+                </Select>
+              </FormField>
+            )}
+          </div>
+        </Card>
+        <Card variant="subtle" padding="lg" className="gap-5">
+          {/* The heading wraps the toggle: a button's children are
+              presentational, so a heading inside it is lost to screen readers. */}
+          <h2>
+            <Button
+              type="button"
+              variant="section-toggle"
+              onClick={() =>
+                setIsAdvancedSectionExpanded(!isAdvancedSectionExpanded)
+              }
+              size="sm"
+              aria-expanded={isAdvancedSectionExpanded}
+              className="-ml-3 w-fit justify-start"
+            >
+              <ChevronRight
+                aria-hidden="true"
+                className={cn(
+                  'transition-transform duration-200',
+                  isAdvancedSectionExpanded && 'rotate-90',
                 )}
+              />
+              <span className="text-lg font-semibold">
+                {t('agents.form.sections.advanced')}
+              </span>
+            </Button>
+          </h2>
+          {isAdvancedSectionExpanded && (
+            <div>
+              <FormField
+                labelSurface="background"
+                label={t('agents.form.advanced.jsonSchema')}
+                hint={t('agents.form.advanced.jsonSchemaDescription')}
+              >
+                <Textarea
+                  size="lg"
+                  value={jsonSchemaText}
+                  onChange={(e) => validateAndSetJsonSchema(e.target.value)}
+                  placeholder={`{
+"type": "object",
+"properties": {
+  "name": {"type": "string"},
+  "email": {"type": "string"}
+},
+"required": ["name", "email"],
+"additionalProperties": false
+}`}
+                  rows={9}
+                  className="font-mono"
+                />
+              </FormField>
+              {jsonSchemaText.trim() !== '' && (
+                <div
+                  className={cn(
+                    'mt-2 flex items-center gap-2 text-sm',
+                    jsonSchemaValid ? 'text-success' : 'text-destructive',
+                  )}
+                >
+                  {jsonSchemaValid ? (
+                    <CircleCheck className="size-4" aria-hidden="true" />
+                  ) : (
+                    <CircleX className="size-4" aria-hidden="true" />
+                  )}
+                  {jsonSchemaValid
+                    ? t('agents.form.advanced.validJson')
+                    : t('agents.form.advanced.invalidJson')}
+                </div>
+              )}
 
-                <SettingRows className="mt-6">
-                  <SettingRow
-                    label={t('agents.form.advanced.tokenLimiting')}
-                    description={t(
-                      'agents.form.advanced.tokenLimitingDescription',
-                    )}
-                    htmlFor={tokenLimitSwitchId}
-                    after={
-                      <Input
-                        type="number"
-                        min="0"
-                        value={agent.token_limit || ''}
-                        onChange={(e) =>
-                          setAgent({
-                            ...agent,
-                            token_limit: e.target.value
-                              ? parseInt(e.target.value)
-                              : undefined,
-                          })
-                        }
-                        disabled={!agent.limited_token_mode}
-                        placeholder={t(
-                          'agents.form.placeholders.enterTokenLimit',
-                        )}
-                        aria-label={t('agents.form.advanced.tokenLimit')}
-                        shape="pill"
-                      />
-                    }
-                  >
-                    <Switch
-                      id={tokenLimitSwitchId}
-                      checked={agent.limited_token_mode}
-                      onCheckedChange={(checked) => {
+              <SettingRows className="mt-6">
+                <SettingRow
+                  label={t('agents.form.advanced.tokenLimiting')}
+                  description={t(
+                    'agents.form.advanced.tokenLimitingDescription',
+                  )}
+                  htmlFor={tokenLimitSwitchId}
+                  after={
+                    <Input
+                      type="number"
+                      min="0"
+                      value={agent.token_limit || ''}
+                      onChange={(e) =>
                         setAgent({
                           ...agent,
-                          limited_token_mode: checked,
-                          limited_request_mode: checked
-                            ? false
-                            : agent.limited_request_mode,
-                        });
-                      }}
-                    />
-                  </SettingRow>
-                  <SettingRow
-                    label={t('agents.form.advanced.requestLimiting')}
-                    description={t(
-                      'agents.form.advanced.requestLimitingDescription',
-                    )}
-                    htmlFor={requestLimitSwitchId}
-                    after={
-                      <Input
-                        type="number"
-                        min="0"
-                        value={agent.request_limit || ''}
-                        onChange={(e) =>
-                          setAgent({
-                            ...agent,
-                            request_limit: e.target.value
-                              ? parseInt(e.target.value)
-                              : undefined,
-                          })
-                        }
-                        disabled={!agent.limited_request_mode}
-                        placeholder={t(
-                          'agents.form.placeholders.enterRequestLimit',
-                        )}
-                        aria-label={t('agents.form.advanced.requestLimit')}
-                        shape="pill"
-                      />
-                    }
-                  >
-                    <Switch
-                      id={requestLimitSwitchId}
-                      checked={agent.limited_request_mode}
-                      onCheckedChange={(checked) => {
-                        setAgent({
-                          ...agent,
-                          limited_request_mode: checked,
-                          limited_token_mode: checked
-                            ? false
-                            : agent.limited_token_mode,
-                        });
-                      }}
-                    />
-                  </SettingRow>
-                  <SettingRow
-                    label={t('agents.form.advanced.systemPromptOverride')}
-                    description={t(
-                      'agents.form.advanced.systemPromptOverrideDescription',
-                    )}
-                    htmlFor={promptOverrideSwitchId}
-                  >
-                    <Switch
-                      id={promptOverrideSwitchId}
-                      checked={agent.allow_system_prompt_override}
-                      onCheckedChange={(checked) =>
-                        setAgent({
-                          ...agent,
-                          allow_system_prompt_override: checked,
+                          token_limit: e.target.value
+                            ? parseInt(e.target.value)
+                            : undefined,
                         })
                       }
+                      disabled={!agent.limited_token_mode}
+                      placeholder={t(
+                        'agents.form.placeholders.enterTokenLimit',
+                      )}
+                      aria-label={t('agents.form.advanced.tokenLimit')}
+                      shape="pill"
                     />
-                  </SettingRow>
-                </SettingRows>
-              </div>
-            )}
-          </Card>
-          <GuardrailsSection
-            value={agent.config?.guardrails}
-            token={token}
-            // Guardrails are the owner's policy: the update route drops
-            // ``config`` for team members, editors included. Leaving the
-            // controls live for editors let them save a change the server
-            // silently discarded, and the success toast said it had worked.
-            disabled={Boolean(agent.team_access)}
-            disabledNotice={
-              agent.team_access
-                ? t('agents.form.guardrails.ownerOnly')
-                : undefined
-            }
-            onChange={(guardrails) =>
-              setAgent({
-                ...agent,
-                config: { ...(agent.config ?? {}), guardrails },
-              })
-            }
-          />
-          {modeConfig[effectiveMode].showDelete && agent.id && (
-            <Card
-              tone="destructive"
-              padding="lg"
-              className="flex-row flex-wrap items-start justify-between"
-            >
-              <SectionHeader
-                tone="destructive"
-                title={t('agents.form.dangerZone.heading')}
-                description={t('agents.form.dangerZone.description')}
-                className="min-w-0 flex-1"
-              />
-              <Button
-                type="button"
-                variant="destructive-outline"
-                size="sm"
-                onClick={() => setDeleteConfirmation('ACTIVE')}
-                className="shrink-0"
-              >
-                {t('agents.form.dangerZone.deleteButton')}
-              </Button>
-            </Card>
+                  }
+                >
+                  <Switch
+                    id={tokenLimitSwitchId}
+                    checked={agent.limited_token_mode}
+                    onCheckedChange={(checked) => {
+                      setAgent({
+                        ...agent,
+                        limited_token_mode: checked,
+                        limited_request_mode: checked
+                          ? false
+                          : agent.limited_request_mode,
+                      });
+                    }}
+                  />
+                </SettingRow>
+                <SettingRow
+                  label={t('agents.form.advanced.requestLimiting')}
+                  description={t(
+                    'agents.form.advanced.requestLimitingDescription',
+                  )}
+                  htmlFor={requestLimitSwitchId}
+                  after={
+                    <Input
+                      type="number"
+                      min="0"
+                      value={agent.request_limit || ''}
+                      onChange={(e) =>
+                        setAgent({
+                          ...agent,
+                          request_limit: e.target.value
+                            ? parseInt(e.target.value)
+                            : undefined,
+                        })
+                      }
+                      disabled={!agent.limited_request_mode}
+                      placeholder={t(
+                        'agents.form.placeholders.enterRequestLimit',
+                      )}
+                      aria-label={t('agents.form.advanced.requestLimit')}
+                      shape="pill"
+                    />
+                  }
+                >
+                  <Switch
+                    id={requestLimitSwitchId}
+                    checked={agent.limited_request_mode}
+                    onCheckedChange={(checked) => {
+                      setAgent({
+                        ...agent,
+                        limited_request_mode: checked,
+                        limited_token_mode: checked
+                          ? false
+                          : agent.limited_token_mode,
+                      });
+                    }}
+                  />
+                </SettingRow>
+                <SettingRow
+                  label={t('agents.form.advanced.systemPromptOverride')}
+                  description={t(
+                    'agents.form.advanced.systemPromptOverrideDescription',
+                  )}
+                  htmlFor={promptOverrideSwitchId}
+                >
+                  <Switch
+                    id={promptOverrideSwitchId}
+                    checked={agent.allow_system_prompt_override}
+                    onCheckedChange={(checked) =>
+                      setAgent({
+                        ...agent,
+                        allow_system_prompt_override: checked,
+                      })
+                    }
+                  />
+                </SettingRow>
+              </SettingRows>
+            </div>
           )}
-        </div>
-        <div className="col-span-3 flex flex-col gap-2 xl:h-full xl:py-2">
-          <div className="flex-1 xl:min-h-0 xl:overflow-hidden">
-            <AgentPreviewArea />
-          </div>
-        </div>
+        </Card>
+        <GuardrailsSection
+          value={agent.config?.guardrails}
+          token={token}
+          // Guardrails are the owner's policy: the update route drops
+          // ``config`` for team members, editors included. Leaving the
+          // controls live for editors let them save a change the server
+          // silently discarded, and the success toast said it had worked.
+          disabled={Boolean(agent.team_access)}
+          disabledNotice={
+            agent.team_access
+              ? t('agents.form.guardrails.ownerOnly')
+              : undefined
+          }
+          onChange={(guardrails) =>
+            setAgent({
+              ...agent,
+              config: { ...(agent.config ?? {}), guardrails },
+            })
+          }
+        />
+        {modeConfig[effectiveMode].showDelete && agent.id && (
+          <Card
+            tone="destructive"
+            padding="lg"
+            className="flex-row flex-wrap items-start justify-between"
+          >
+            <SectionHeader
+              tone="destructive"
+              title={t('agents.form.dangerZone.heading')}
+              description={t('agents.form.dangerZone.description')}
+              className="min-w-0 flex-1"
+            />
+            <Button
+              type="button"
+              variant="destructive-outline"
+              size="sm"
+              onClick={() => setDeleteConfirmation('ACTIVE')}
+              className="shrink-0"
+            >
+              {t('agents.form.dangerZone.deleteButton')}
+            </Button>
+          </Card>
+        )}
       </div>
       <ConfirmationModal
         message={t('agents.deleteConfirmation')}
@@ -1462,43 +1546,71 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
           setAgent({ ...agent, prompt_id: id });
         }}
       />
-    </div>
-  );
-}
-
-function AgentPreviewArea() {
-  const { t } = useTranslation();
-  const selectedAgent = useSelector(selectSelectedAgent);
-  return (
-    <Card
-      variant="subtle"
-      padding="none"
-      className="h-[600px] w-full xl:h-full"
-    >
-      {selectedAgent?.status === 'published' ? (
-        <div className="flex h-full w-full flex-col overflow-hidden rounded-2xl">
-          <AgentPreview />
-        </div>
-      ) : (
-        <div className="flex h-full w-full flex-col items-center justify-center gap-2">
-          <img
-            src={ScienceSparkIcon}
-            alt=""
-            aria-hidden="true"
-            className="block size-12 dark:hidden"
-          />
-          <img
-            src={ScienceSparkDarkIcon}
-            alt=""
-            aria-hidden="true"
-            className="hidden size-12 dark:block"
-          />{' '}
-          <p className="text-muted-foreground text-xs">
-            {t('agents.form.preview.publishedPreview')}
-          </p>
-        </div>
-      )}
-    </Card>
+      <AgentPreviewSheet
+        open={previewOpen}
+        onOpenChange={setPreviewOpen}
+        title={t('agents.form.sections.preview')}
+        description={`${agentDisplayName} · ${
+          isPublished
+            ? t('agents.form.preview.savedVersion')
+            : t('agents.card.draft')
+        }`}
+        running={previewStatus === 'loading'}
+        actions={
+          isPublished ? (
+            <Button
+              type="button"
+              variant="ghost-muted"
+              size="sm"
+              shape="pill"
+              onClick={() => dispatch(resetPreview())}
+            >
+              <SquarePen />
+              {t('newChat')}
+            </Button>
+          ) : undefined
+        }
+      >
+        {isPublished ? (
+          <div className="flex min-h-0 flex-1 flex-col">
+            {effectiveMode === 'edit' && hasChanges && (
+              <div className="px-4 pt-4">
+                <Alert role="note">
+                  <Info />
+                  <AlertDescription>
+                    {t('agents.form.preview.unsavedChanges')}
+                  </AlertDescription>
+                </Alert>
+              </div>
+            )}
+            <div className="relative min-h-0 flex-1">
+              <AgentPreview />
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-1 items-center justify-center px-6">
+            <EmptyState
+              size="sm"
+              illustration="none"
+              title={t('agents.form.preview.publishTitle')}
+              description={t('agents.form.preview.publishDescription')}
+              action={
+                <Button
+                  type="button"
+                  size="sm"
+                  shape="pill"
+                  disabled={!isPublishable()}
+                  loading={publishLoading}
+                  onClick={handlePublish}
+                >
+                  {t('agents.form.buttons.publish')}
+                </Button>
+              }
+            />
+          </div>
+        )}
+      </AgentPreviewSheet>
+    </SectionShell>
   );
 }
 
diff --git a/frontend/src/agents/components/AgentPageToolbar.test.tsx b/frontend/src/agents/components/AgentPageToolbar.test.tsx
new file mode 100644
index 00000000..14c3c403
--- /dev/null
+++ b/frontend/src/agents/components/AgentPageToolbar.test.tsx
@@ -0,0 +1,67 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import AgentPageToolbar from './AgentPageToolbar';
+
+describe('AgentPageToolbar', () => {
+  it('puts the agent byline beside the actions and closes with a rule', () => {
+    const html = renderToStaticMarkup(
+      <AgentPageToolbar
+        name="Carrier onboarding FAQ"
+        status={<span data-testid="status">Published</span>}
+        meta="Last used at 21 Sep"
+        actions={<button type="button">Save</button>}
+      />,
+    );
+    expect(html).toContain('data-slot="page-toolbar"');
+    expect(html).toContain('Carrier onboarding FAQ');
+    expect(html).toContain('data-testid="status"');
+    expect(html).toContain('Last used at 21 Sep');
+    expect(html).toContain('<button type="button">Save</button>');
+    expect(html).toContain('data-slot="separator"');
+  });
+
+  // On a phone, a status badge fills the first line: the meta takes a line
+  // of its own there, without a dangling separator.
+  it('moves the meta to its own line on a phone when there is a status', () => {
+    const html = renderToStaticMarkup(
+      <AgentPageToolbar
+        name="FAQ"
+        status={<span>Published</span>}
+        meta="Last used"
+      />,
+    );
+    expect(html).toContain(
+      '<span aria-hidden="true" class="hidden sm:inline">·</span>',
+    );
+    expect(html).toContain(
+      '<span class="basis-full sm:basis-auto">Last used</span>',
+    );
+  });
+
+  it('keeps the meta on the name line when there is no status', () => {
+    const html = renderToStaticMarkup(
+      <AgentPageToolbar name="FAQ" meta="Last used" />,
+    );
+    expect(html).toContain(
+      '<span aria-hidden="true">·</span><span>Last used</span>',
+    );
+  });
+
+  it('keeps the row at field height when a tab has no actions', () => {
+    const html = renderToStaticMarkup(<AgentPageToolbar name="FAQ" />);
+    // A 38px spacer stands in for the actions, so the rule lands in the same
+    // place on every agent tab.
+    expect(html).toContain('h-9.5');
+  });
+
+  it('renders notices between the row and the rule', () => {
+    const html = renderToStaticMarkup(
+      <AgentPageToolbar name="FAQ">
+        <p>Save failed</p>
+      </AgentPageToolbar>,
+    );
+    expect(html.indexOf('Save failed')).toBeLessThan(
+      html.indexOf('data-slot="separator"'),
+    );
+  });
+});
diff --git a/frontend/src/agents/components/AgentPageToolbar.tsx b/frontend/src/agents/components/AgentPageToolbar.tsx
new file mode 100644
index 00000000..7a35a7d5
--- /dev/null
+++ b/frontend/src/agents/components/AgentPageToolbar.tsx
@@ -0,0 +1,94 @@
+import type { ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import PageToolbar from '../../components/PageToolbar';
+import { formatDateTime } from '../../utils/dateTimeUtils';
+
+type AgentPageToolbarProps = {
+  /** The agent's name, first in the byline. */
+  name?: string;
+  /** A status Badge beside the name (Overview's Published / Draft). */
+  status?: ReactNode;
+  /** The tab's context after the name, e.g. "Last used at …". */
+  meta?: ReactNode;
+  /** The tab's buttons, on the right of the row. */
+  actions?: ReactNode;
+  /** A line of its own in place of the name byline (the new-agent form). */
+  intro?: ReactNode;
+  /** Notices under the row, above the rule (a failed save). */
+  children?: ReactNode;
+};
+
+/**
+ * The block under an agent tab's title (Overview, Logs, Schedules): a muted
+ * byline naming the agent, the tab's actions on the right, then a rule. The
+ * row keeps the field height when a tab has no actions, so the rule lands in
+ * the same place on every tab and nothing jumps when switching.
+ *
+ * Args:
+ *   name: The agent's name.
+ *   status: A Badge shown beside the name.
+ *   meta: Tab context shown after the name, separated by a middle dot.
+ *   actions: The tab's buttons.
+ *   intro: Replaces the name byline.
+ *   children: Notices between the row and the rule.
+ */
+export default function AgentPageToolbar({
+  name,
+  status,
+  meta,
+  actions,
+  intro,
+  children,
+}: AgentPageToolbarProps) {
+  const byline = intro ?? (
+    <span className="inline-flex flex-wrap items-center gap-x-2 gap-y-1">
+      {name ? <span className="wrap-break-word">{name}</span> : null}
+      {status}
+      {meta ? (
+        status ? (
+          // With a status badge the first line is full on a phone: the meta
+          // takes its own line there, so no separator is left hanging.
+          <>
+            <span aria-hidden className="hidden sm:inline">
+              ·
+            </span>
+            <span className="basis-full sm:basis-auto">{meta}</span>
+          </>
+        ) : (
+          <>
+            <span aria-hidden>·</span>
+            <span>{meta}</span>
+          </>
+        )
+      ) : null}
+    </span>
+  );
+
+  return (
+    <PageToolbar
+      intro={byline}
+      action={actions ?? <div aria-hidden className="h-9.5" />}
+      divider
+    >
+      {children}
+    </PageToolbar>
+  );
+}
+
+/**
+ * The agent tabs' usage meta: "Last used at …", or "no usage history".
+ *
+ * Args:
+ *   lastUsedAt: The agent's `last_used_at` timestamp.
+ */
+export function LastUsedMeta({ lastUsedAt }: { lastUsedAt?: string | null }) {
+  const { t } = useTranslation();
+  return (
+    <>
+      {lastUsedAt
+        ? `${t('agents.logs.lastUsedAt')} ${formatDateTime(lastUsedAt)}`
+        : t('agents.logs.noUsageHistory')}
+    </>
+  );
+}
diff --git a/frontend/src/agents/components/AgentPreviewSheet.test.tsx b/frontend/src/agents/components/AgentPreviewSheet.test.tsx
index 15e1f914..5dbebd6f 100644
--- a/frontend/src/agents/components/AgentPreviewSheet.test.tsx
+++ b/frontend/src/agents/components/AgentPreviewSheet.test.tsx
@@ -3,6 +3,9 @@ import { act } from 'react';
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({ t: (key: string) => key }),
 }));
+
+const dispatch = vi.fn();
+vi.mock('react-redux', () => ({ useDispatch: () => dispatch }));
 import { createRoot, type Root } from 'react-dom/client';
 
 import AgentPreviewSheet from './AgentPreviewSheet';
@@ -90,6 +93,22 @@ describe('AgentPreviewSheet', () => {
     expect(badge.textContent).toBe('agents.schedules.status.running');
   });
 
+  // The toast stack moves bottom-left while any agent preview is open.
+  it('reports whether it is open, and closed when it goes away', async () => {
+    dispatch.mockClear();
+    await render();
+    expect(dispatch).toHaveBeenCalledWith({
+      type: 'workflowPreview/setPreviewOpen',
+      payload: true,
+    });
+    await act(async () => root.unmount());
+    root = createRoot(container);
+    expect(dispatch).toHaveBeenLastCalledWith({
+      type: 'workflowPreview/setPreviewOpen',
+      payload: false,
+    });
+  });
+
   it('renders the body under a separator on the sheet surface', async () => {
     await render();
     const body = document.querySelector('[data-testid="body"]')!;
diff --git a/frontend/src/agents/components/AgentPreviewSheet.tsx b/frontend/src/agents/components/AgentPreviewSheet.tsx
index 18dcc8c4..0b5ae644 100644
--- a/frontend/src/agents/components/AgentPreviewSheet.tsx
+++ b/frontend/src/agents/components/AgentPreviewSheet.tsx
@@ -1,5 +1,6 @@
-import type { ReactNode } from 'react';
+import { type ReactNode, useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
+import { useDispatch } from 'react-redux';
 
 import { Badge } from '@/components/ui/badge';
 import { Separator } from '@/components/ui/separator';
@@ -10,6 +11,8 @@ import {
   SheetTitle,
 } from '@/components/ui/sheet';
 
+import { setPreviewOpen } from '../workflow/workflowPreviewSlice';
+
 type AgentPreviewSheetProps = {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -48,12 +51,21 @@ export default function AgentPreviewSheet({
   children,
 }: AgentPreviewSheetProps) {
   const { t } = useTranslation();
+  const dispatch = useDispatch();
+
+  // App moves the toast stack bottom-left while a preview drawer is open, so
+  // it doesn't sit over the chat. The flag lives in the workflow preview
+  // slice for both agent types.
+  useEffect(() => {
+    dispatch(setPreviewOpen(open));
+    return () => {
+      dispatch(setPreviewOpen(false));
+    };
+  }, [dispatch, open]);
+
   return (
     <Sheet open={open} onOpenChange={onOpenChange}>
-      <SheetContent
-        side="right"
-        className="w-full max-w-none p-0 sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]"
-      >
+      <SheetContent side="right" size="wide" className="p-0">
         <div className="flex min-h-0 flex-1 flex-col">
           {/* pr-12 keeps the header clear of the close X at top-2 right-2. */}
           <div className="flex items-center gap-3 px-6 pt-6 pr-12 pb-4">
diff --git a/frontend/src/agents/components/GuardrailEvents.test.tsx b/frontend/src/agents/components/GuardrailEvents.test.tsx
index d5e6bc62..cc7511d6 100644
--- a/frontend/src/agents/components/GuardrailEvents.test.tsx
+++ b/frontend/src/agents/components/GuardrailEvents.test.tsx
@@ -78,6 +78,14 @@ describe('GuardrailEvents tones', () => {
     container.remove();
   });
 
+  // A3: the section lines up with Analytics and the log table on Logs.
+  it('is not indented against the sections around it', () => {
+    const root = document.querySelector<HTMLElement>(
+      '[data-testid="guardrail-events"]',
+    )!;
+    expect(root.className).not.toMatch(/(^|\s)px-/);
+  });
+
   it('colours outcome badges by meaning', () => {
     const variants = Array.from(
       container.querySelectorAll(
diff --git a/frontend/src/agents/components/GuardrailEvents.tsx b/frontend/src/agents/components/GuardrailEvents.tsx
index d1b5acf4..e8814621 100644
--- a/frontend/src/agents/components/GuardrailEvents.tsx
+++ b/frontend/src/agents/components/GuardrailEvents.tsx
@@ -127,7 +127,7 @@ export default function GuardrailEvents({ agentId }: Props) {
   const tableHeadingId = React.useId();
 
   return (
-    <div className="mt-8 px-4" data-testid="guardrail-events">
+    <div className="mt-8" data-testid="guardrail-events">
       <SectionHeader
         title={t('agents.guardrailEvents.heading')}
         description={t('agents.guardrailEvents.description')}
diff --git a/frontend/src/agents/components/GuardrailsSection.test.tsx b/frontend/src/agents/components/GuardrailsSection.test.tsx
index 72091bf5..521c54d1 100644
--- a/frontend/src/agents/components/GuardrailsSection.test.tsx
+++ b/frontend/src/agents/components/GuardrailsSection.test.tsx
@@ -195,6 +195,28 @@ describe('GuardrailsSection', () => {
     expect(chevron.getAttribute('class')).not.toContain('rotate-90');
   });
 
+  // Decision 74: the panel spaces header and body with gap-5 like the other
+  // form sections, and the body stacks its rows with a gap-5 flex column
+  // rather than per-child margins.
+  it('spaces the panel and its body with gap-5, not margins', async () => {
+    await render({ disabled: true });
+    const panel = q('guardrails-section')!;
+    expect(panel.className.split(' ')).toContain('gap-5');
+    expect(panel.className.split(' ')).not.toContain('gap-3');
+    const body = panel.children[1] as HTMLElement;
+    expect(body.className.split(' ')).toEqual(
+      expect.arrayContaining(['flex', 'flex-col', 'gap-5']),
+    );
+    // Notices, Enable row, mode, checks, block message, fail-open, timeout.
+    expect(body.children.length).toBeGreaterThanOrEqual(9);
+    for (const child of Array.from(body.children)) {
+      expect(child.getAttribute('class') ?? '').not.toMatch(/(^|\s)mt-\d/);
+    }
+    // The checks list keeps its own tighter gap.
+    const checks = q('guardrail-orphan-gone')!.parentElement!;
+    expect(checks.className.split(' ')).toContain('gap-3');
+  });
+
   it('renders the header pills as badges in their status roles', async () => {
     await render();
     expect(q('guardrails-active-badge')?.dataset.slot).toBe('badge');
diff --git a/frontend/src/agents/components/GuardrailsSection.tsx b/frontend/src/agents/components/GuardrailsSection.tsx
index 63259e59..cac93cf6 100644
--- a/frontend/src/agents/components/GuardrailsSection.tsx
+++ b/frontend/src/agents/components/GuardrailsSection.tsx
@@ -216,7 +216,12 @@ export default function GuardrailsSection({
   const instanceDisabled = catalog !== null && catalog.enabled === false;
 
   return (
-    <Card variant="subtle" padding="lg" data-testid="guardrails-section">
+    <Card
+      variant="subtle"
+      padding="lg"
+      className="gap-5"
+      data-testid="guardrails-section"
+    >
       <div className="flex flex-wrap items-center gap-2">
         {/* The heading wraps the toggle: a button's children are
             presentational, so a heading inside it is lost to screen readers. */}
@@ -262,7 +267,7 @@ export default function GuardrailsSection({
       </div>
 
       {expanded && (
-        <div>
+        <div className="flex flex-col gap-5">
           {loadError && (
             <EmptyState
               tone="destructive"
@@ -283,22 +288,14 @@ export default function GuardrailsSection({
           )}
 
           {disabled && disabledNotice && (
-            <Alert
-              role="status"
-              className="mt-3"
-              data-testid="guardrails-read-only"
-            >
+            <Alert role="status" data-testid="guardrails-read-only">
               <Lock aria-hidden="true" className="size-4" />
               <AlertDescription>{disabledNotice}</AlertDescription>
             </Alert>
           )}
 
           {instanceDisabled && (
-            <Alert
-              variant="warning"
-              className="mt-3"
-              data-testid="guardrails-instance-disabled"
-            >
+            <Alert variant="warning" data-testid="guardrails-instance-disabled">
               <TriangleAlert aria-hidden="true" className="size-4" />
               <AlertDescription>
                 {t('agents.form.guardrails.instanceDisabled')}
@@ -307,7 +304,7 @@ export default function GuardrailsSection({
           )}
 
           {floorControls.size > 0 && (
-            <Alert variant="info" role="status" className="mt-3">
+            <Alert variant="info" role="status">
               <Info aria-hidden="true" className="size-4" />
               <AlertDescription>
                 {t('agents.form.guardrails.floorNotice', {
@@ -318,7 +315,6 @@ export default function GuardrailsSection({
           )}
 
           <SettingRow
-            className="mt-4"
             label={t('agents.form.guardrails.enable')}
             description={t('agents.form.guardrails.enableDescription')}
             htmlFor={enabledId}
@@ -334,46 +330,42 @@ export default function GuardrailsSection({
 
           {config.enabled && (
             <>
-              <div className="mt-5">
-                <FormField
-                  labelSurface="background"
-                  label={t('agents.form.guardrails.mode')}
-                  hint={
-                    config.mode === 'monitor_only'
-                      ? t('agents.form.guardrails.monitorHint')
-                      : undefined
+              <FormField
+                labelSurface="background"
+                label={t('agents.form.guardrails.mode')}
+                hint={
+                  config.mode === 'monitor_only'
+                    ? t('agents.form.guardrails.monitorHint')
+                    : undefined
+                }
+                disabled={disabled}
+              >
+                <Select
+                  value={config.mode}
+                  onValueChange={(mode) =>
+                    patch({ mode: mode as GuardrailsConfig['mode'] })
                   }
                   disabled={disabled}
                 >
-                  <Select
-                    value={config.mode}
-                    onValueChange={(mode) =>
-                      patch({ mode: mode as GuardrailsConfig['mode'] })
-                    }
-                    disabled={disabled}
+                  <SelectTrigger
+                    className="w-full"
+                    size="field"
+                    shape="pill"
+                    data-testid="guardrails-mode"
                   >
-                    <SelectTrigger
-                      className="w-full"
-                      size="field"
-                      shape="pill"
-                      data-testid="guardrails-mode"
-                    >
-                      <SelectValue />
-                    </SelectTrigger>
-                    <SelectContent>
-                      {(catalog?.modes ?? Object.keys(MODE_KEYS)).map(
-                        (mode) => (
-                          <SelectItem key={mode} value={mode}>
-                            {t(MODE_KEYS[mode] ?? mode)}
-                          </SelectItem>
-                        ),
-                      )}
-                    </SelectContent>
-                  </Select>
-                </FormField>
-              </div>
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {(catalog?.modes ?? Object.keys(MODE_KEYS)).map((mode) => (
+                      <SelectItem key={mode} value={mode}>
+                        {t(MODE_KEYS[mode] ?? mode)}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </FormField>
 
-              <div className="mt-5">
+              <div>
                 <p className="mb-3 text-sm font-medium">
                   {t('agents.form.guardrails.checks')}
                 </p>
@@ -425,7 +417,6 @@ export default function GuardrailsSection({
 
               <FormField
                 labelSurface="background"
-                className="mt-6"
                 label={t('agents.form.guardrails.blockMessage')}
                 hint={t('agents.form.guardrails.blockMessageDescription')}
                 disabled={disabled}
@@ -441,7 +432,6 @@ export default function GuardrailsSection({
               </FormField>
 
               <SettingRow
-                className="mt-6"
                 label={t('agents.form.guardrails.failOpen')}
                 description={t('agents.form.guardrails.failOpenDescription')}
                 htmlFor={failOpenId}
@@ -457,7 +447,6 @@ export default function GuardrailsSection({
 
               <FormField
                 labelSurface="background"
-                className="mt-5"
                 label={t('agents.form.guardrails.timeout')}
                 disabled={disabled}
               >
diff --git a/frontend/src/agents/schedules/RunDetailDrawer.test.tsx b/frontend/src/agents/schedules/RunDetailDrawer.test.tsx
index ef36b8fa..3a12a3f3 100644
--- a/frontend/src/agents/schedules/RunDetailDrawer.test.tsx
+++ b/frontend/src/agents/schedules/RunDetailDrawer.test.tsx
@@ -81,7 +81,13 @@ describe('RunDetailDrawer', () => {
       root.render(<RunDetailDrawer run={run} onClose={vi.fn()} />),
     );
     const pre = content()!.querySelector('pre')!;
-    const card = pre.parentElement!;
+    // The scroll cap sits on an inner scroller inside the Card's padding,
+    // so the scrollbar stays clear of the rounded corners.
+    const scroller = pre.parentElement!;
+    expect(scroller.className.split(' ')).toEqual(
+      expect.arrayContaining(['scrollbar-overlay', 'overflow-y-auto']),
+    );
+    const card = scroller.parentElement!;
     expect(card.getAttribute('data-slot')).toBe('card');
     expect(card.getAttribute('data-variant')).toBe('filled');
     expect(card.className.split(' ')).toContain('bg-muted');
diff --git a/frontend/src/agents/schedules/RunDetailDrawer.tsx b/frontend/src/agents/schedules/RunDetailDrawer.tsx
index d134d247..5011b27d 100644
--- a/frontend/src/agents/schedules/RunDetailDrawer.tsx
+++ b/frontend/src/agents/schedules/RunDetailDrawer.tsx
@@ -29,11 +29,7 @@ export default function RunDetailDrawer({
   if (!run) return null;
   return (
     <Sheet open onOpenChange={(open) => !open && onClose()}>
-      <SheetContent
-        side="right"
-        className="sm:max-w-xl"
-        aria-describedby={undefined}
-      >
+      <SheetContent side="right" size="detail" aria-describedby={undefined}>
         {/* The sheet owns no padding of its own; the body sets it. */}
         <div className="flex min-h-0 flex-1 flex-col gap-4 p-6">
           <SheetTitle>{t('agents.schedules.runDetails.title')}</SheetTitle>
@@ -78,14 +74,12 @@ export default function RunDetailDrawer({
                     : t('agents.schedules.runDetails.error')
                 }
               />
-              <Card
-                variant="filled"
-                padding="sm"
-                className="max-h-48 overflow-y-auto"
-              >
-                <pre className="font-mono text-xs wrap-break-word whitespace-pre-wrap">
-                  {run.error}
-                </pre>
+              <Card variant="filled" padding="sm">
+                <div className="scrollbar-overlay max-h-48 overflow-y-auto">
+                  <pre className="font-mono text-xs wrap-break-word whitespace-pre-wrap">
+                    {run.error}
+                  </pre>
+                </div>
               </Card>
             </section>
           )}
diff --git a/frontend/src/agents/schedules/RunLog.test.tsx b/frontend/src/agents/schedules/RunLog.test.tsx
new file mode 100644
index 00000000..63cb4a60
--- /dev/null
+++ b/frontend/src/agents/schedules/RunLog.test.tsx
@@ -0,0 +1,69 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const runs = [
+  {
+    id: 'r1',
+    schedule_id: 's1',
+    status: 'success',
+    scheduled_for: '2026-09-21T09:00:00Z',
+    started_at: '2026-09-21T09:00:00Z',
+    finished_at: '2026-09-21T09:00:42Z',
+    trigger_source: 'cron',
+    prompt_tokens: 4000,
+    generated_tokens: 812,
+  },
+];
+vi.mock('react-redux', () => ({
+  useSelector: (selector: (s: unknown) => unknown) =>
+    selector({
+      preference: { token: 't' },
+      schedules: { byAgent: {}, runsBySchedule: { s1: runs } },
+    }),
+  useDispatch: () => vi.fn(),
+}));
+
+import RunLog from './RunLog';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('RunLog', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('opens a run from its whole row, with duration and grouped tokens', async () => {
+    const onSelect = vi.fn();
+    await act(async () => {
+      root.render(<RunLog scheduleId="s1" onSelect={onSelect} />);
+    });
+    const heads = Array.from(container.querySelectorAll('th')).map(
+      (th) => th.textContent,
+    );
+    expect(heads).toContain('agents.schedules.runLog.duration');
+    // The default table head, not the eyebrow.
+    expect(container.querySelector('th')!.className).not.toContain('uppercase');
+    const row = container.querySelector('tbody tr') as HTMLTableRowElement;
+    expect(row.textContent).toContain('42.0 s');
+    expect(row.textContent).toContain('4.8k');
+    expect(row.querySelector('svg.lucide-chevron-right')).not.toBeNull();
+    // No separate Details link: the row is the target.
+    expect(row.querySelector('button')).toBeNull();
+    await act(async () => row.click());
+    expect(onSelect).toHaveBeenCalledWith(runs[0]);
+  });
+});
diff --git a/frontend/src/agents/schedules/RunLog.tsx b/frontend/src/agents/schedules/RunLog.tsx
index c8cfbd4f..4cb6d26c 100644
--- a/frontend/src/agents/schedules/RunLog.tsx
+++ b/frontend/src/agents/schedules/RunLog.tsx
@@ -1,8 +1,9 @@
+import { ChevronRight } from 'lucide-react';
 import { useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
-import { Button } from '../../components/ui/button';
+import { EmptyState } from '../../components/ui/empty-state';
 import {
   Table,
   TableBody,
@@ -12,16 +13,16 @@ import {
   TableRow,
 } from '../../components/ui/table';
 import { selectToken } from '../../preferences/preferenceSlice';
+import {
+  formatDurationMs,
+  formatTokens,
+} from '../../settings/traces/traceUtils';
 import type { AppDispatch, RootState } from '../../store';
 import { formatDateTime } from '../../utils/dateTimeUtils';
 import type { ScheduleRun } from '../types/schedule';
 import ScheduleStatusBadge from './StatusBadge';
 import { loadRunsForSchedule, selectRunsForSchedule } from './schedulesSlice';
 
-// The column heads are a label row, so they take the eyebrow recipe.
-const HEADER_CELL =
-  'text-muted-foreground text-xs font-semibold tracking-wider uppercase';
-
 export type RunLogProps = {
   scheduleId: string;
   onSelect?: (run: ScheduleRun) => void;
@@ -31,7 +32,18 @@ const formatTimestamp = (value?: string | null): string => {
   return value ? formatDateTime(value) : '—';
 };
 
-/** Paginated run log for a schedule (SSE updates merge via schedulesSlice). */
+/** How long a run took, or a dash while it hasn't started or finished. */
+const runDuration = (run: ScheduleRun): string => {
+  if (!run.started_at || !run.finished_at) return '—';
+  return formatDurationMs(
+    Date.parse(run.finished_at) - Date.parse(run.started_at),
+  );
+};
+
+/**
+ * A schedule's run log (SSE updates merge via schedulesSlice). Each row opens
+ * the run's details when `onSelect` is given.
+ */
 export default function RunLog({ scheduleId, onSelect }: RunLogProps) {
   const { t } = useTranslation();
   const dispatch = useDispatch<AppDispatch>();
@@ -47,9 +59,11 @@ export default function RunLog({ scheduleId, onSelect }: RunLogProps) {
 
   if (runs.length === 0) {
     return (
-      <p className="text-muted-foreground py-3 text-sm">
-        {t('agents.schedules.runLog.empty')}
-      </p>
+      <EmptyState
+        size="xs"
+        illustration="none"
+        title={t('agents.schedules.runLog.empty')}
+      />
     );
   }
 
@@ -57,24 +71,26 @@ export default function RunLog({ scheduleId, onSelect }: RunLogProps) {
     <Table minWidth="min-w-0">
       <TableHead>
         <TableRow>
-          <TableHeader className={HEADER_CELL}>
-            {t('agents.schedules.runLog.when')}
-          </TableHeader>
-          <TableHeader className={HEADER_CELL}>
-            {t('agents.schedules.runDetails.status')}
-          </TableHeader>
-          <TableHeader className={HEADER_CELL}>
-            {t('agents.schedules.runDetails.tokens')}
-          </TableHeader>
-          <TableHeader className={HEADER_CELL}>
-            {t('agents.schedules.runDetails.trigger')}
-          </TableHeader>
-          <TableHeader className={HEADER_CELL}></TableHeader>
+          <TableHeader>{t('agents.schedules.runLog.when')}</TableHeader>
+          <TableHeader>{t('agents.schedules.runDetails.status')}</TableHeader>
+          <TableHeader>{t('agents.schedules.runLog.duration')}</TableHeader>
+          <TableHeader>{t('agents.schedules.runDetails.tokens')}</TableHeader>
+          <TableHeader>{t('agents.schedules.runDetails.trigger')}</TableHeader>
+          {onSelect && (
+            <TableHeader width="40px" align="center">
+              <span className="sr-only">
+                {t('agents.schedules.runLog.details')}
+              </span>
+            </TableHeader>
+          )}
         </TableRow>
       </TableHead>
       <TableBody>
         {runs.map((run) => (
-          <TableRow key={run.id}>
+          <TableRow
+            key={run.id}
+            onClick={onSelect ? () => onSelect(run) : undefined}
+          >
             <TableCell>{formatTimestamp(run.scheduled_for)}</TableCell>
             <TableCell>
               <div className="flex items-center gap-1.5">
@@ -86,25 +102,23 @@ export default function RunLog({ scheduleId, onSelect }: RunLogProps) {
                 )}
               </div>
             </TableCell>
-            <TableCell>{run.prompt_tokens + run.generated_tokens}</TableCell>
+            <TableCell className="tabular-nums">{runDuration(run)}</TableCell>
+            <TableCell className="tabular-nums">
+              {formatTokens(run.prompt_tokens + run.generated_tokens)}
+            </TableCell>
             <TableCell>
               {t(`agents.schedules.trigger.${run.trigger_source}`, {
                 defaultValue: run.trigger_source,
               })}
             </TableCell>
-            <TableCell>
-              {onSelect && (
-                <Button
-                  type="button"
-                  variant="link"
-                  size="xs"
-                  onClick={() => onSelect(run)}
-                  className="-mx-2 -my-1"
-                >
-                  {t('agents.schedules.runLog.details')}
-                </Button>
-              )}
-            </TableCell>
+            {onSelect && (
+              <TableCell align="center">
+                <ChevronRight
+                  aria-hidden
+                  className="text-muted-foreground size-4"
+                />
+              </TableCell>
+            )}
           </TableRow>
         ))}
       </TableBody>
diff --git a/frontend/src/agents/schedules/ScheduleRow.test.tsx b/frontend/src/agents/schedules/ScheduleRow.test.tsx
new file mode 100644
index 00000000..a2620b5f
--- /dev/null
+++ b/frontend/src/agents/schedules/ScheduleRow.test.tsx
@@ -0,0 +1,138 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts && 'count' in opts ? `${key}:${opts.count}` : key,
+  }),
+}));
+vi.mock('./RunLog', () => ({ default: () => <div data-testid="runlog" /> }));
+
+import ScheduleRow from './ScheduleRow';
+import type { Schedule } from '../types/schedule';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const base: Schedule = {
+  id: 's1',
+  user_id: 'u',
+  agent_id: 'a1',
+  trigger_type: 'recurring',
+  name: 'Weekly compliance digest',
+  instruction: 'Summarise expiring certificates.',
+  status: 'active',
+  cron: '0 9 * * 1',
+  timezone: 'Europe/Berlin',
+  next_run_at: '2026-09-28T07:00:00Z',
+  last_run_at: '2026-09-21T07:00:00Z',
+  tool_allowlist: [],
+  created_via: 'ui',
+  consecutive_failure_count: 0,
+  created_at: '2026-09-01T00:00:00Z',
+  updated_at: '2026-09-01T00:00:00Z',
+};
+
+describe('ScheduleRow', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const handlers = {
+    onToggleRuns: vi.fn(),
+    onEdit: vi.fn(),
+    onSetPaused: vi.fn(),
+    onRunNow: vi.fn(),
+    onDelete: vi.fn(),
+    onSelectRun: vi.fn(),
+  };
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (schedule: Schedule, expanded = false) => {
+    await act(async () => {
+      root.render(
+        <ScheduleRow schedule={schedule} expanded={expanded} {...handlers} />,
+      );
+    });
+  };
+
+  const buttons = () =>
+    Array.from(container.querySelectorAll<HTMLButtonElement>('button'));
+
+  it('is a subtle panel with one visible action and a menu', async () => {
+    await render(base);
+    const card = container.querySelector<HTMLElement>('[data-slot="card"]')!;
+    expect(card.dataset.variant).toBe('subtle');
+    const runNow = buttons().find((b) =>
+      b.textContent?.includes('agents.schedules.runNow'),
+    )!;
+    expect(runNow.dataset.variant).toBe('outline');
+    expect(runNow.dataset.size).toBe('sm');
+    expect(runNow.dataset.shape).toBe('pill');
+    // Edit, Pause and Delete live in the menu, not as pills.
+    expect(
+      buttons().some((b) => b.textContent === 'agents.schedules.edit'),
+    ).toBe(false);
+    expect(
+      container.querySelector('[aria-label="agents.schedules.actions"]'),
+    ).not.toBeNull();
+    await act(async () => runNow.click());
+    expect(handlers.onRunNow).toHaveBeenCalledWith(base);
+  });
+
+  it('reads its meta with icons, and shows the instruction under a name', async () => {
+    await render(base);
+    expect(container.textContent).toContain('Summarise expiring certificates.');
+    expect(container.textContent).toContain('Europe/Berlin');
+    expect(container.textContent).toContain('agents.schedules.meta.nextRun');
+    expect(container.textContent).not.toContain('tz:');
+    expect(container.querySelector('svg.lucide-repeat')).not.toBeNull();
+  });
+
+  it('offers Resume while paused and flags a failure streak', async () => {
+    await render({ ...base, status: 'paused', consecutive_failure_count: 2 });
+    expect(
+      buttons().some((b) => b.textContent?.includes('agents.schedules.resume')),
+    ).toBe(true);
+    const streak = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="badge"]'),
+    ).find((b) => b.textContent?.includes('agents.schedules.failureStreak'))!;
+    expect(streak.dataset.variant).toBe('destructive');
+    expect(streak.textContent).toContain(':2');
+  });
+
+  it('toggles its runs with a chevron and shows them flush in the card', async () => {
+    await render(base, true);
+    const toggle = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="agents.schedules.hideRuns"]',
+    )!;
+    expect(toggle.getAttribute('aria-expanded')).toBe('true');
+    expect(container.querySelector('[data-testid="runlog"]')).not.toBeNull();
+    await act(async () => toggle.click());
+    expect(handlers.onToggleRuns).toHaveBeenCalledWith('s1');
+  });
+
+  it('shows a one-time task with its run time and only a menu', async () => {
+    await render({
+      ...base,
+      trigger_type: 'once',
+      cron: null,
+      run_at: '2026-10-01T08:00:00Z',
+    });
+    expect(container.textContent).toContain('agents.schedules.meta.runsAt');
+    expect(
+      buttons().some((b) => b.textContent?.includes('agents.schedules.runNow')),
+    ).toBe(false);
+    expect(
+      container.querySelector('button[aria-label="agents.schedules.showRuns"]'),
+    ).toBeNull();
+  });
+});
diff --git a/frontend/src/agents/schedules/ScheduleRow.tsx b/frontend/src/agents/schedules/ScheduleRow.tsx
new file mode 100644
index 00000000..8d25c98f
--- /dev/null
+++ b/frontend/src/agents/schedules/ScheduleRow.tsx
@@ -0,0 +1,257 @@
+import {
+  ChevronDown,
+  Clock,
+  History,
+  Pause,
+  Pencil,
+  Play,
+  Repeat,
+  Trash2,
+  TriangleAlert,
+} from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { Badge } from '../../components/ui/badge';
+import { Button } from '../../components/ui/button';
+import { Card } from '../../components/ui/card';
+import { ActionMenu, type MenuOption } from '../../components/ui/dropdown-menu';
+import { IconButton } from '../../components/ui/icon-button';
+import { cn } from '@/lib/utils';
+import { formatDateTime, formatRelative } from '../../utils/dateTimeUtils';
+import type { Schedule, ScheduleRun } from '../types/schedule';
+import RunLog from './RunLog';
+import ScheduleStatusBadge from './StatusBadge';
+import { formatCron } from './cronBuilder';
+
+// Timezones and dates carry slashes: React escapes on render, so i18next
+// must not escape them first.
+const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
+
+const STATUS_DOT: Record<Schedule['status'], string> = {
+  active: 'bg-success',
+  paused: 'bg-warning',
+  completed: 'bg-muted-foreground',
+  cancelled: 'bg-muted-foreground',
+};
+
+export type ScheduleRowProps = {
+  schedule: Schedule;
+  /** Whether the run log is open under the row (recurring schedules). */
+  expanded: boolean;
+  onToggleRuns: (scheduleId: string) => void;
+  onEdit: (schedule: Schedule) => void;
+  onSetPaused: (schedule: Schedule, paused: boolean) => void;
+  onRunNow: (schedule: Schedule) => void;
+  onDelete: (schedule: Schedule) => void;
+  onSelectRun: (run: ScheduleRun) => void;
+};
+
+/**
+ * One schedule on an agent's Schedules page: a subtle panel with a status dot,
+ * the name and status, the instruction, one meta line, the common action as
+ * a button (Run now, or Resume while paused) and the rest in a menu. A
+ * recurring schedule opens its run log flush under the row.
+ *
+ * Args:
+ *   schedule: The schedule to show.
+ *   expanded: Whether its run log is open.
+ *   onToggleRuns: Opens or closes the run log.
+ *   onEdit: Opens the schedule form.
+ *   onSetPaused: Pauses (true) or resumes (false) a recurring schedule.
+ *   onRunNow: Runs the schedule once now.
+ *   onDelete: Asks to delete the schedule (or cancel a one-time task).
+ *   onSelectRun: Opens a run's details.
+ */
+export default function ScheduleRow({
+  schedule,
+  expanded,
+  onToggleRuns,
+  onEdit,
+  onSetPaused,
+  onRunNow,
+  onDelete,
+  onSelectRun,
+}: ScheduleRowProps) {
+  const { t } = useTranslation();
+  const recurring = schedule.trigger_type === 'recurring';
+  const active = schedule.status === 'active';
+  const paused = schedule.status === 'paused';
+  const title = schedule.name || schedule.instruction.slice(0, 80);
+
+  const edit: MenuOption = {
+    label: t('agents.schedules.edit'),
+    icon: Pencil,
+    onClick: () => onEdit(schedule),
+  };
+  const remove: MenuOption = {
+    label: t('agents.schedules.delete'),
+    icon: Trash2,
+    variant: 'destructive',
+    onClick: () => onDelete(schedule),
+  };
+  const menu: MenuOption[] = recurring
+    ? active
+      ? [
+          edit,
+          {
+            label: t('agents.schedules.pause'),
+            icon: Pause,
+            onClick: () => onSetPaused(schedule, true),
+          },
+          remove,
+        ]
+      : paused
+        ? [
+            edit,
+            {
+              label: t('agents.schedules.runNow'),
+              icon: Play,
+              onClick: () => onRunNow(schedule),
+            },
+            remove,
+          ]
+        : [remove]
+    : active
+      ? [
+          edit,
+          {
+            label: t('agents.schedules.cancelTask'),
+            icon: Trash2,
+            variant: 'destructive',
+            onClick: () => onDelete(schedule),
+          },
+        ]
+      : [remove];
+
+  const meta: { icon: typeof Clock; text: string }[] = [];
+  if (recurring) {
+    meta.push({
+      icon: Repeat,
+      text: `${formatCron(schedule.cron, t)}, ${schedule.timezone}`,
+    });
+    if (active && schedule.next_run_at) {
+      meta.push({
+        icon: Clock,
+        text: t('agents.schedules.meta.nextRun', {
+          ...NO_ESCAPE,
+          // A past next run (the scheduler is behind) reads as a date, not
+          // "… ago".
+          time:
+            Date.parse(schedule.next_run_at) > Date.now()
+              ? formatRelative(schedule.next_run_at, { future: true })
+              : formatDateTime(schedule.next_run_at),
+        }),
+      });
+    }
+  } else if (schedule.run_at) {
+    meta.push({
+      icon: Clock,
+      text: t('agents.schedules.meta.runsAt', {
+        ...NO_ESCAPE,
+        time: `${formatDateTime(schedule.run_at)}, ${schedule.timezone}`,
+      }),
+    });
+  }
+  if (schedule.last_run_at) {
+    meta.push({
+      icon: History,
+      text: t('agents.schedules.meta.lastRun', {
+        ...NO_ESCAPE,
+        time: formatRelative(schedule.last_run_at),
+      }),
+    });
+  }
+
+  return (
+    <Card variant="subtle" padding="none" data-schedule-id={schedule.id}>
+      <div className="flex flex-col gap-3 p-4 sm:flex-row sm:items-start">
+        <div className="flex min-w-0 flex-1 items-start gap-3">
+          <span
+            aria-hidden
+            className={cn(
+              'mt-1.5 size-2 shrink-0 rounded-full',
+              STATUS_DOT[schedule.status],
+            )}
+          />
+          <div className="flex min-w-0 flex-1 flex-col gap-1">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-medium wrap-break-word">{title}</span>
+              <ScheduleStatusBadge status={schedule.status} />
+              {schedule.consecutive_failure_count > 0 && (
+                <Badge variant="destructive">
+                  <TriangleAlert aria-hidden />
+                  {t('agents.schedules.failureStreak', {
+                    count: schedule.consecutive_failure_count,
+                  })}
+                </Badge>
+              )}
+            </div>
+            {schedule.name && (
+              <p className="text-muted-foreground line-clamp-1 text-sm">
+                {schedule.instruction}
+              </p>
+            )}
+            {meta.length > 0 && (
+              <p className="text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-1 text-xs">
+                {meta.map(({ icon: Icon, text }) => (
+                  <span key={text} className="inline-flex items-center gap-1">
+                    <Icon aria-hidden className="size-3.5 shrink-0" />
+                    {text}
+                  </span>
+                ))}
+              </p>
+            )}
+          </div>
+        </div>
+        <div className="flex shrink-0 items-center gap-1 pl-5 sm:pl-0">
+          {recurring && (active || paused) && (
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={() =>
+                active ? onRunNow(schedule) : onSetPaused(schedule, false)
+              }
+            >
+              <Play />
+              {active
+                ? t('agents.schedules.runNow')
+                : t('agents.schedules.resume')}
+            </Button>
+          )}
+          <ActionMenu
+            triggerLabel={t('agents.schedules.actions')}
+            options={menu}
+          />
+          {recurring && (
+            <IconButton
+              label={
+                expanded
+                  ? t('agents.schedules.hideRuns')
+                  : t('agents.schedules.showRuns')
+              }
+              variant="ghost-muted"
+              size="icon-xs"
+              aria-expanded={expanded}
+              onClick={() => onToggleRuns(schedule.id)}
+            >
+              <ChevronDown
+                aria-hidden
+                className={cn(
+                  'transition-transform duration-200',
+                  expanded && 'rotate-180',
+                )}
+              />
+            </IconButton>
+          )}
+        </div>
+      </div>
+      {recurring && expanded && (
+        <div className="border-border border-t">
+          <RunLog scheduleId={schedule.id} onSelect={onSelectRun} />
+        </div>
+      )}
+    </Card>
+  );
+}
diff --git a/frontend/src/agents/schedules/SchedulesView.test.tsx b/frontend/src/agents/schedules/SchedulesView.test.tsx
new file mode 100644
index 00000000..e979fc44
--- /dev/null
+++ b/frontend/src/agents/schedules/SchedulesView.test.tsx
@@ -0,0 +1,170 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts && 'count' in opts ? `${key}:${opts.count}` : key,
+  }),
+}));
+
+const schedules = [
+  {
+    id: 's1',
+    agent_id: 'a1',
+    trigger_type: 'recurring',
+    name: 'Weekly digest',
+    instruction: 'Summarise.',
+    status: 'active',
+    cron: '0 9 * * 1',
+    timezone: 'Europe/Berlin',
+    next_run_at: '2099-09-28T07:00:00Z',
+    consecutive_failure_count: 0,
+  },
+  {
+    id: 's2',
+    agent_id: 'a1',
+    trigger_type: 'recurring',
+    name: 'Daily queue',
+    instruction: 'Check.',
+    status: 'paused',
+    cron: '30 8 * * 1-5',
+    timezone: 'Europe/Berlin',
+    consecutive_failure_count: 2,
+  },
+];
+
+vi.mock('react-redux', () => ({
+  useSelector: (selector: (s: unknown) => unknown) =>
+    selector({
+      preference: { token: 't' },
+      schedules: { byAgent: { a1: schedules }, runsBySchedule: {} },
+    }),
+  useDispatch: () => vi.fn(() => ({ unwrap: () => Promise.resolve() })),
+}));
+vi.mock('../../api/services/userService', () => ({
+  default: {
+    getAgent: () =>
+      Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({ id: 'a1', name: 'Carrier FAQ', tools: [] }),
+      }),
+  },
+}));
+vi.mock('../../api/services/schedulesService', () => ({
+  default: {
+    statsForAgent: () =>
+      Promise.resolve({
+        days: 30,
+        runs: 14,
+        failed: 3,
+        tokens: 48230,
+        latest_failure: {
+          scheduled_for: '2026-09-14T09:00:00Z',
+          status: 'timeout',
+          error_type: 'timeout',
+        },
+      }),
+  },
+}));
+vi.mock('./ScheduleRow', () => ({
+  default: ({ schedule }: { schedule: { id: string } }) => (
+    <div data-testid={`row-${schedule.id}`} />
+  ),
+}));
+vi.mock('./ScheduleFormModal', () => ({ default: () => null }));
+vi.mock('./RunDetailDrawer', () => ({ default: () => null }));
+vi.mock('../../modals/ConfirmationModal', () => ({ default: () => null }));
+vi.mock('../../navigation/SectionPageHeader', () => ({
+  CurrentSectionHeader: () => <h1>Schedules</h1>,
+}));
+vi.mock('../../navigation/SectionPills', () => ({ default: () => null }));
+
+import SchedulesView from './SchedulesView';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('SchedulesView', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={['/agents/manage/schedules/a1']}>
+          <Routes>
+            <Route
+              path="/agents/manage/schedules/:agentId"
+              element={<SchedulesView />}
+            />
+          </Routes>
+        </MemoryRouter>,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('puts New schedule in the agent toolbar, with no second heading', async () => {
+    const toolbar = container.querySelector('[data-slot="page-toolbar"]')!;
+    expect(toolbar.textContent).toContain('Carrier FAQ');
+    const create = Array.from(toolbar.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes('agents.schedules.newRecurring'),
+    )!;
+    expect(create.dataset.variant).toBe('default');
+    expect(create.dataset.size).toBe('field');
+    expect(create.dataset.shape).toBe('pill');
+    expect(container.querySelectorAll('h1, h2')).toHaveLength(1);
+  });
+
+  it('shows the stat row as StatCards, failures in the destructive tone', async () => {
+    const tiles = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="card"]'),
+    );
+    expect(tiles).toHaveLength(4);
+    expect(container.textContent).toContain('agents.schedules.stats.active');
+    expect(container.textContent).toContain('14');
+    const failed = tiles.find((c) =>
+      c.textContent?.includes('agents.schedules.stats.failed'),
+    )!;
+    expect(failed.dataset.tone).toBe('destructive');
+    expect(failed.textContent).toContain('3');
+  });
+
+  it('switches Recurring and One-time with underline tabs', async () => {
+    const tabs = Array.from(container.querySelectorAll('[role="tab"]'));
+    expect(tabs.map((t) => t.textContent)).toEqual([
+      'agents.schedules.recurring2',
+      'agents.schedules.oneTime0',
+    ]);
+    expect(tabs[0].getAttribute('data-variant')).toBe('underline');
+    expect(container.querySelector('[data-testid="row-s1"]')).not.toBeNull();
+    expect(container.querySelector('[data-testid="row-s2"]')).not.toBeNull();
+  });
+
+  it('shows an empty tab as an EmptyState with New schedule', async () => {
+    const oneTime = Array.from(
+      container.querySelectorAll<HTMLElement>('[role="tab"]'),
+    )[1];
+    await act(async () => {
+      oneTime.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+      oneTime.dispatchEvent(
+        new PointerEvent('pointerdown', { bubbles: true, button: 0 }),
+      );
+      oneTime.click();
+    });
+    const empty = container.querySelector('[data-slot="empty-state"]')!;
+    expect(empty.textContent).toContain('agents.schedules.noOneTime');
+    expect(empty.querySelector('button')?.textContent).toContain(
+      'agents.schedules.newRecurring',
+    );
+  });
+});
diff --git a/frontend/src/agents/schedules/SchedulesView.tsx b/frontend/src/agents/schedules/SchedulesView.tsx
index fefa1f29..5b690744 100644
--- a/frontend/src/agents/schedules/SchedulesView.tsx
+++ b/frontend/src/agents/schedules/SchedulesView.tsx
@@ -4,27 +4,38 @@ import { useDispatch, useSelector } from 'react-redux';
 import { useParams } from 'react-router-dom';
 
 import userService from '../../api/services/userService';
+import { Plus } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { EmptyState } from '@/components/ui/empty-state';
 import { LoadingState } from '@/components/ui/loading-state';
-import { SectionHeader } from '@/components/ui/section-header';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import schedulesService from '../../api/services/schedulesService';
+import StatCard from '../../components/StatCard';
 import { Button } from '../../components/ui/button';
 import { Card } from '../../components/ui/card';
 import ConfirmationModal from '../../modals/ConfirmationModal';
 import { ActiveState } from '../../models/misc';
 import { selectToken } from '../../preferences/preferenceSlice';
 import type { AppDispatch, RootState } from '../../store';
-import { formatDateTime } from '../../utils/dateTimeUtils';
+import { formatTokens } from '../../settings/traces/traceUtils';
+import {
+  formatDateOnly,
+  formatDateTime,
+  formatRelative,
+} from '../../utils/dateTimeUtils';
+import AgentPageToolbar, { LastUsedMeta } from '../components/AgentPageToolbar';
 import SectionShell from '../../navigation/SectionShell';
 import type { Agent } from '../types';
 import type {
   Schedule,
   ScheduleCreatePayload,
   ScheduleRun,
+  ScheduleStats,
 } from '../types/schedule';
 import RunDetailDrawer from './RunDetailDrawer';
-import RunLog from './RunLog';
 import ScheduleFormModal from './ScheduleFormModal';
-import ScheduleStatusBadge from './StatusBadge';
-import { formatCron } from './cronBuilder';
+import ScheduleRow from './ScheduleRow';
 import {
   createSchedule,
   deleteSchedule,
@@ -39,9 +50,8 @@ import {
 // must not escape them first.
 const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
 
-const formatTimestamp = (value?: string | null): string => {
-  return value ? formatDateTime(value) : '—';
-};
+// The stat row's window, in days.
+const STATS_DAYS = 30;
 
 /** Standalone Schedules page for an agent: list, create, edit, pause, run, delete. */
 export default function SchedulesView() {
@@ -66,6 +76,28 @@ export default function SchedulesView() {
   const schedules = useSelector((state: RootState) =>
     selectSchedulesForAgent(state, agentId ?? ''),
   );
+  // undefined while loading, null when the stats request failed.
+  const [stats, setStats] = useState<ScheduleStats | null | undefined>(
+    undefined,
+  );
+
+  // Refresh the totals whenever the list changes (a run finished, a
+  // schedule was paused or removed): the SSE feed updates `schedules`.
+  useEffect(() => {
+    if (!agentId) return;
+    let cancelled = false;
+    schedulesService
+      .statsForAgent(agentId, token, STATS_DAYS)
+      .then((next) => {
+        if (!cancelled) setStats(next);
+      })
+      .catch(() => {
+        if (!cancelled) setStats(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [agentId, token, schedules]);
 
   useEffect(() => {
     if (!agentId) return;
@@ -152,228 +184,165 @@ export default function SchedulesView() {
     }
   };
 
+  const activeCount = schedules.filter((s) => s.status === 'active').length;
+  const pausedCount = schedules.filter((s) => s.status === 'paused').length;
+  const nextRunAt = schedules
+    .filter((s) => s.status === 'active' && s.next_run_at)
+    .map((s) => s.next_run_at as string)
+    .sort()[0];
+  // A next run in the past means the scheduler hasn't picked it up yet.
+  const nextRunOverdue =
+    Boolean(nextRunAt) && Date.parse(nextRunAt as string) < Date.now();
+  const statsLoading = stats === undefined;
+  const failedCount = stats?.failed ?? 0;
+  const latestFailure = stats?.latest_failure;
+
+  const newScheduleButton = (
+    <Button type="button" size="field" shape="pill" onClick={openCreate}>
+      <Plus />
+      {t('agents.schedules.newRecurring')}
+    </Button>
+  );
+
+  const renderList = (list: Schedule[], emptyKey: string) =>
+    list.length === 0 ? (
+      <Card variant="subtle" padding="lg">
+        <EmptyState
+          size="sm"
+          illustration="none"
+          title={t(emptyKey)}
+          action={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={openCreate}
+            >
+              <Plus />
+              {t('agents.schedules.newRecurring')}
+            </Button>
+          }
+        />
+      </Card>
+    ) : (
+      <ul className="flex flex-col gap-3">
+        {list.map((schedule) => (
+          <li key={schedule.id}>
+            <ScheduleRow
+              schedule={schedule}
+              expanded={expanded === schedule.id}
+              onToggleRuns={(id) => setExpanded(expanded === id ? null : id)}
+              onEdit={openEdit}
+              onSetPaused={(target, paused) =>
+                dispatch(
+                  setSchedulePaused({
+                    id: target.id,
+                    action: paused ? 'pause' : 'resume',
+                    token,
+                  }),
+                )
+              }
+              onRunNow={(target) =>
+                dispatch(runScheduleNow({ id: target.id, token }))
+              }
+              onDelete={requestDelete}
+              onSelectRun={(run) => setActiveRun(run)}
+            />
+          </li>
+        ))}
+      </ul>
+    );
+
   return (
-    <SectionShell pills>
-      <div className="flex flex-col gap-3">
-        {agent && (
-          <div className="flex flex-col gap-1">
-            <p className="text-foreground">{agent.name}</p>
-            <p className="text-muted-foreground text-xs">
-              {agent.last_used_at
-                ? t('agents.logs.lastUsedAt') +
-                  ' ' +
-                  formatDateTime(agent.last_used_at)
-                : t('agents.logs.noUsageHistory')}
-            </p>
-          </div>
-        )}
-      </div>
+    <SectionShell>
+      {agent && (
+        <AgentPageToolbar
+          name={agent.name}
+          meta={<LastUsedMeta lastUsedAt={agent.last_used_at} />}
+          actions={newScheduleButton}
+        />
+      )}
       {loadingAgent ? (
         <LoadingState fill="block" />
       ) : (
         agent && (
-          <div className="flex flex-col gap-4 p-4">
-            <SectionHeader
-              title={t('agents.schedules.heading')}
-              actions={
-                <Button type="button" size="sm" onClick={openCreate}>
-                  {t('agents.schedules.newRecurring')}
-                </Button>
-              }
-            />
-            <section className="flex flex-col gap-2">
-              <SectionHeader
-                as="h3"
-                size="sm"
-                title={`${t('agents.schedules.recurring')} (${recurring.length})`}
+          <div className="flex flex-col gap-8">
+            <div className="grid grid-cols-2 gap-4 md:grid-cols-4">
+              <StatCard
+                label={t('agents.schedules.stats.active')}
+                value={activeCount}
+                sub={
+                  pausedCount > 0
+                    ? t('agents.schedules.stats.paused', {
+                        count: pausedCount,
+                      })
+                    : undefined
+                }
               />
-              {recurring.length === 0 ? (
-                <p className="text-muted-foreground text-sm">
-                  {t('agents.schedules.noRecurring')}
-                </p>
-              ) : (
-                <ul className="flex flex-col gap-3">
-                  {recurring.map((schedule) => (
-                    <Card
-                      asChild
-                      key={schedule.id}
-                      variant="subtle"
-                      padding="sm"
-                      className="gap-0"
-                    >
-                      <li>
-                        <div className="flex items-start justify-between">
-                          <div>
-                            <div className="flex items-center gap-2">
-                              <p className="font-semibold">
-                                {schedule.name ||
-                                  schedule.instruction.slice(0, 80)}
-                              </p>
-                              <ScheduleStatusBadge status={schedule.status} />
-                            </div>
-                            <p className="text-muted-foreground text-xs">
-                              {formatCron(schedule.cron, t)} ·{' '}
-                              {t('agents.schedules.timezoneMeta', {
-                                ...NO_ESCAPE,
-                                timezone: schedule.timezone,
-                              })}{' '}
-                              ·{' '}
-                              {t('agents.schedules.nextRunMeta', {
-                                ...NO_ESCAPE,
-                                time: formatTimestamp(schedule.next_run_at),
-                              })}
-                            </p>
-                          </div>
-                          <div className="flex gap-2">
-                            <Button
-                              type="button"
-                              variant="outline-primary"
-                              size="sm"
-                              shape="pill"
-                              onClick={() => openEdit(schedule)}
-                            >
-                              {t('agents.schedules.edit')}
-                            </Button>
-                            <Button
-                              type="button"
-                              variant="outline-primary"
-                              size="sm"
-                              shape="pill"
-                              onClick={() =>
-                                dispatch(
-                                  setSchedulePaused({
-                                    id: schedule.id,
-                                    action:
-                                      schedule.status === 'active'
-                                        ? 'pause'
-                                        : 'resume',
-                                    token,
-                                  }),
-                                )
-                              }
-                            >
-                              {schedule.status === 'active'
-                                ? t('agents.schedules.pause')
-                                : t('agents.schedules.resume')}
-                            </Button>
-                            <Button
-                              type="button"
-                              variant="outline-primary"
-                              size="sm"
-                              shape="pill"
-                              onClick={() =>
-                                dispatch(
-                                  runScheduleNow({ id: schedule.id, token }),
-                                )
-                              }
-                            >
-                              {t('agents.schedules.runNow')}
-                            </Button>
-                            <Button
-                              type="button"
-                              variant="destructive-outline"
-                              size="sm"
-                              shape="pill"
-                              onClick={() => requestDelete(schedule)}
-                            >
-                              {t('agents.schedules.delete')}
-                            </Button>
-                          </div>
-                        </div>
-                        <Button
-                          type="button"
-                          variant="link"
-                          size="xs"
-                          onClick={() =>
-                            setExpanded(
-                              expanded === schedule.id ? null : schedule.id,
-                            )
-                          }
-                          className="mt-0.5 -ml-2"
-                        >
-                          {expanded === schedule.id
-                            ? t('agents.schedules.hideRuns')
-                            : t('agents.schedules.showRuns')}
-                        </Button>
-                        {expanded === schedule.id && (
-                          <div className="mt-2">
-                            <RunLog
-                              scheduleId={schedule.id}
-                              onSelect={(run) => setActiveRun(run)}
-                            />
-                          </div>
-                        )}
-                      </li>
-                    </Card>
-                  ))}
-                </ul>
-              )}
-            </section>
-            <section className="flex flex-col gap-2">
-              <SectionHeader
-                as="h3"
-                size="sm"
-                title={`${t('agents.schedules.oneTime')} (${oneTime.length})`}
+              <StatCard
+                label={t('agents.schedules.stats.nextRun')}
+                value={
+                  !nextRunAt
+                    ? '—'
+                    : nextRunOverdue
+                      ? t('agents.schedules.stats.overdue')
+                      : formatRelative(nextRunAt, { future: true })
+                }
+                valueTone={nextRunOverdue ? 'warning' : undefined}
+                sub={nextRunAt ? formatDateTime(nextRunAt) : undefined}
               />
-              {oneTime.length === 0 ? (
-                <p className="text-muted-foreground text-sm">
-                  {t('agents.schedules.noOneTime')}
-                </p>
-              ) : (
-                <ul className="flex flex-col gap-2">
-                  {oneTime.map((schedule) => (
-                    <Card
-                      asChild
-                      key={schedule.id}
-                      variant="subtle"
-                      padding="sm"
-                      className="gap-0"
-                    >
-                      <li>
-                        <div className="flex items-start justify-between">
-                          <div>
-                            <div className="flex items-center gap-2">
-                              <p className="font-semibold">
-                                {schedule.name ||
-                                  schedule.instruction.slice(0, 80)}
-                              </p>
-                              <ScheduleStatusBadge status={schedule.status} />
-                            </div>
-                            <p className="text-muted-foreground text-xs">
-                              runs at {formatTimestamp(schedule.run_at)}
-                            </p>
-                          </div>
-                          <div className="flex gap-2">
-                            {schedule.status === 'active' && (
-                              <Button
-                                type="button"
-                                variant="outline-primary"
-                                size="sm"
-                                shape="pill"
-                                onClick={() => openEdit(schedule)}
-                              >
-                                {t('agents.schedules.edit')}
-                              </Button>
-                            )}
-                            {schedule.status === 'active' && (
-                              <Button
-                                type="button"
-                                variant="destructive-outline"
-                                size="sm"
-                                shape="pill"
-                                onClick={() => requestDelete(schedule)}
-                              >
-                                {t('agents.schedules.cancel')}
-                              </Button>
-                            )}
-                          </div>
-                        </div>
-                      </li>
-                    </Card>
-                  ))}
-                </ul>
-              )}
-            </section>
+              <StatCard
+                label={t('agents.schedules.stats.runs', { days: STATS_DAYS })}
+                value={stats ? stats.runs : '—'}
+                loading={statsLoading}
+                sub={
+                  stats
+                    ? t('agents.schedules.stats.tokens', {
+                        tokens: formatTokens(stats.tokens),
+                      })
+                    : undefined
+                }
+              />
+              <StatCard
+                label={t('agents.schedules.stats.failed', {
+                  days: STATS_DAYS,
+                })}
+                value={stats ? failedCount : '—'}
+                loading={statsLoading}
+                tone={failedCount > 0 ? 'destructive' : 'default'}
+                valueTone={failedCount > 0 ? 'destructive' : undefined}
+                sub={
+                  latestFailure
+                    ? t('agents.schedules.stats.latestFailure', {
+                        ...NO_ESCAPE,
+                        status: t(
+                          `agents.schedules.status.${latestFailure.status}`,
+                        ),
+                        date: formatDateOnly(latestFailure.scheduled_for),
+                      })
+                    : undefined
+                }
+              />
+            </div>
+            <Tabs defaultValue="recurring">
+              <TabsList variant="underline">
+                <TabsTrigger value="recurring" variant="underline">
+                  {t('agents.schedules.recurring')}
+                  <Badge variant="neutral">{recurring.length}</Badge>
+                </TabsTrigger>
+                <TabsTrigger value="once" variant="underline">
+                  {t('agents.schedules.oneTime')}
+                  <Badge variant="neutral">{oneTime.length}</Badge>
+                </TabsTrigger>
+              </TabsList>
+              <TabsContent value="recurring" className="mt-4">
+                {renderList(recurring, 'agents.schedules.noRecurring')}
+              </TabsContent>
+              <TabsContent value="once" className="mt-4">
+                {renderList(oneTime, 'agents.schedules.noOneTime')}
+              </TabsContent>
+            </Tabs>
             <RunDetailDrawer
               run={activeRun}
               onClose={() => setActiveRun(null)}
diff --git a/frontend/src/agents/schedules/schedulesSlice.test.ts b/frontend/src/agents/schedules/schedulesSlice.test.ts
index cb49d066..95e22ce1 100644
--- a/frontend/src/agents/schedules/schedulesSlice.test.ts
+++ b/frontend/src/agents/schedules/schedulesSlice.test.ts
@@ -268,3 +268,13 @@ describe('schedulesSlice SSE event handling', () => {
     expect(stub.trigger_source).toBe('cron');
   });
 });
+
+describe('selectSchedulesForAgent', () => {
+  it('returns a stable empty list for an agent that has not loaded', () => {
+    // A fresh [] per call re-runs every effect that depends on the list.
+    const state = { schedules: reducer(undefined, { type: '@@init' }) };
+    expect(selectSchedulesForAgent(state, 'missing')).toBe(
+      selectSchedulesForAgent(state, 'missing'),
+    );
+  });
+});
diff --git a/frontend/src/agents/schedules/schedulesSlice.ts b/frontend/src/agents/schedules/schedulesSlice.ts
index 3828c95c..4d092f34 100644
--- a/frontend/src/agents/schedules/schedulesSlice.ts
+++ b/frontend/src/agents/schedules/schedulesSlice.ts
@@ -333,12 +333,17 @@ const schedulesSlice = createSlice({
 export const { applyEvent, resetSchedules } = schedulesSlice.actions;
 export default schedulesSlice.reducer;
 
+// Shared fallbacks: a fresh [] per call would change identity on every render
+// and re-run any effect that depends on the selected list.
+const NO_SCHEDULES: Schedule[] = [];
+const NO_RUNS: ScheduleRun[] = [];
+
 export const selectSchedulesForAgent = (
   state: { schedules: SchedulesState },
   agentId: string,
-): Schedule[] => state.schedules.byAgent[agentId] ?? [];
+): Schedule[] => state.schedules.byAgent[agentId] ?? NO_SCHEDULES;
 
 export const selectRunsForSchedule = (
   state: { schedules: SchedulesState },
   scheduleId: string,
-): ScheduleRun[] => state.schedules.runsBySchedule[scheduleId] ?? [];
+): ScheduleRun[] => state.schedules.runsBySchedule[scheduleId] ?? NO_RUNS;
diff --git a/frontend/src/agents/types/schedule.ts b/frontend/src/agents/types/schedule.ts
index 75fa7971..02241354 100644
--- a/frontend/src/agents/types/schedule.ts
+++ b/frontend/src/agents/types/schedule.ts
@@ -68,6 +68,19 @@ export type ScheduleRun = {
 };
 
 export type ScheduleListResponse = { schedules: Schedule[] };
+
+/** Run totals for an agent's schedules over the last `days` days. */
+export type ScheduleStats = {
+  days: number;
+  runs: number;
+  failed: number;
+  tokens: number;
+  latest_failure: {
+    scheduled_for: string;
+    status: ScheduleRunStatus;
+    error_type?: ScheduleRunErrorType | null;
+  } | null;
+};
 export type ScheduleResponse = { schedule: Schedule };
 export type ScheduleRunListResponse = {
   runs: ScheduleRun[];
diff --git a/frontend/src/agents/workflow/WorkflowBuilder.tsx b/frontend/src/agents/workflow/WorkflowBuilder.tsx
index 3a155584..09be651d 100644
--- a/frontend/src/agents/workflow/WorkflowBuilder.tsx
+++ b/frontend/src/agents/workflow/WorkflowBuilder.tsx
@@ -88,6 +88,7 @@ import {
 } from '../../preferences/preferenceSlice';
 import { getToolDisplayName } from '../../utils/toolUtils';
 import { agentEditPath, agentsListPath } from '../paths';
+import { ActionMenu } from '@/components/ui/dropdown-menu';
 import AgentPageHeader from '../AgentPageHeader';
 import AgentPreviewSheet from '../components/AgentPreviewSheet';
 import { Agent } from '../types';
@@ -133,7 +134,7 @@ type PaletteTone = 'primary' | 'success' | 'warning' | 'info';
 // Whole class strings per tone so Tailwind sees them.
 const PALETTE_TONE_CLASSES: Record<PaletteTone, string> = {
   primary:
-    'bg-primary/10 text-primary group-hover:bg-primary group-hover:text-primary-foreground',
+    'bg-secondary text-secondary-foreground group-hover:bg-primary group-hover:text-primary-foreground',
   success:
     'bg-success/10 text-success group-hover:bg-success group-hover:text-success-foreground',
   warning:
@@ -1795,6 +1796,7 @@ function WorkflowBuilderInner() {
               <Button
                 type="button"
                 variant="outline"
+                size="field"
                 shape="pill"
                 onClick={navigateBackToAgents}
               >
@@ -1931,32 +1933,10 @@ function WorkflowBuilderInner() {
             </Popover>
           </div>
           <div className="flex items-center gap-2">
-            {canManageAgent && (
-              <Button
-                type="button"
-                variant="outline"
-                shape="pill"
-                onClick={() => setAgentDetails('ACTIVE')}
-              >
-                <Link />
-                {t('agents.form.buttons.accessDetails')}
-              </Button>
-            )}
-            {canManageAgent && (
-              <Button
-                type="button"
-                variant="destructive-outline"
-                shape="pill"
-                onClick={() => setDeleteConfirmation('ACTIVE')}
-                loading={isDeletingAgent}
-              >
-                <Trash2 />
-                {t('agents.form.buttons.delete')}
-              </Button>
-            )}
             <Button
               type="button"
               variant="outline"
+              size="field"
               shape="pill"
               onClick={() => {
                 const validationErrors = validateWorkflow();
@@ -1976,11 +1956,31 @@ function WorkflowBuilderInner() {
               onClick={handlePrimaryAction}
               disabled={isPrimaryActionDisabled}
               loading={showPrimaryActionSpinner}
-              size="lg"
+              size="field"
               shape="pill"
             >
               {primaryActionLabel}
             </Button>
+            {canManageAgent && (
+              <ActionMenu
+                size="toolbar"
+                triggerLabel={t('agents.form.buttons.moreActions')}
+                options={[
+                  {
+                    label: t('agents.form.buttons.accessDetails'),
+                    icon: Link,
+                    onClick: () => setAgentDetails('ACTIVE'),
+                  },
+                  {
+                    label: t('agents.form.buttons.delete'),
+                    icon: Trash2,
+                    variant: 'destructive',
+                    disabled: isDeletingAgent,
+                    onClick: () => setDeleteConfirmation('ACTIVE'),
+                  },
+                ]}
+              />
+            )}
           </div>
         </div>
 
diff --git a/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx b/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx
index ebff359b..ceb97597 100644
--- a/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx
+++ b/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx
@@ -103,8 +103,8 @@ describe('WorkflowMiniMap', () => {
     );
     expect(tokens(r.busy)).toEqual(
       expect.arrayContaining([
-        'hover:bg-primary/10',
-        'dark:hover:bg-primary/10',
+        'hover:bg-secondary',
+        'dark:hover:bg-secondary',
         'animate-pulse',
       ]),
     );
@@ -125,8 +125,8 @@ describe('WorkflowMiniMap', () => {
       expect.arrayContaining([
         'ring-2',
         'ring-primary',
-        'hover:bg-primary/10',
-        'dark:hover:bg-primary/10',
+        'hover:bg-secondary',
+        'dark:hover:bg-secondary',
       ]),
     );
     expect(done).not.toContain('hover:bg-accent');
diff --git a/frontend/src/agents/workflow/WorkflowPreview.tsx b/frontend/src/agents/workflow/WorkflowPreview.tsx
index d15d4664..4caf952d 100644
--- a/frontend/src/agents/workflow/WorkflowPreview.tsx
+++ b/frontend/src/agents/workflow/WorkflowPreview.tsx
@@ -51,7 +51,6 @@ import {
   resendQuery,
   resetWorkflowPreview,
   selectActiveNodeId,
-  setPreviewOpen,
   selectWorkflowExecutionSteps,
   selectWorkflowPreviewQueries,
   selectWorkflowPreviewStatus,
@@ -409,11 +408,11 @@ export function WorkflowMiniMap({
               className={cn(
                 'h-12 w-full justify-start disabled:opacity-100',
                 isActive
-                  ? 'bg-primary/10 ring-primary hover:bg-primary/10 dark:bg-primary/10 dark:hover:bg-primary/10 ring-2'
+                  ? 'bg-secondary ring-primary hover:bg-secondary dark:bg-secondary dark:hover:bg-secondary ring-2'
                   : status === 'completed'
                     ? 'border-success/50 bg-success/10 hover:bg-success/10 dark:border-success/50 dark:bg-success/10 dark:hover:bg-success/10'
                     : status === 'running'
-                      ? 'border-primary/50 bg-primary/10 hover:bg-primary/10 dark:border-primary/50 dark:bg-primary/10 dark:hover:bg-primary/10 animate-pulse'
+                      ? 'border-primary/50 bg-secondary hover:bg-secondary dark:border-primary/50 dark:bg-secondary dark:hover:bg-secondary animate-pulse'
                       : status === 'failed'
                         ? 'border-destructive/50 bg-destructive/10 hover:bg-destructive/10 dark:border-destructive/50 dark:bg-destructive/10 dark:hover:bg-destructive/10'
                         : 'border-border bg-muted hover:bg-muted dark:border-border dark:bg-muted dark:hover:bg-muted',
@@ -596,12 +595,10 @@ export default function WorkflowPreview({
 
   useEffect(() => {
     dispatch(resetWorkflowPreview());
-    dispatch(setPreviewOpen(true));
     return () => {
       if (fetchStream.current) fetchStream.current.abort();
       handleWorkflowPreviewAbort();
       dispatch(resetWorkflowPreview());
-      dispatch(setPreviewOpen(false));
     };
   }, [dispatch]);
 
diff --git a/frontend/src/agents/workflow/components/PromptTextArea.tsx b/frontend/src/agents/workflow/components/PromptTextArea.tsx
index c63842f4..880d705f 100644
--- a/frontend/src/agents/workflow/components/PromptTextArea.tsx
+++ b/frontend/src/agents/workflow/components/PromptTextArea.tsx
@@ -442,7 +442,7 @@ export default function PromptTextArea({
   // so typing keeps filtering it.
   const field = (
     <PopoverAnchor asChild>
-      <div className="border-border focus-within:ring-ring bg-card relative rounded-xl border transition-shadow focus-within:ring-2">
+      <div className="border-border focus-within:border-ring focus-within:ring-ring/50 bg-card relative rounded-xl border transition-shadow focus-within:ring-3">
         <div
           ref={overlayRef}
           aria-hidden
diff --git a/frontend/src/api/endpoints.ts b/frontend/src/api/endpoints.ts
index 7989be60..143a168b 100644
--- a/frontend/src/api/endpoints.ts
+++ b/frontend/src/api/endpoints.ts
@@ -141,6 +141,8 @@ const endpoints = {
     CUSTOM_MODEL_TEST: (id: string) => `/api/user/models/${id}/test`,
     CUSTOM_MODEL_TEST_PAYLOAD: '/api/user/models/test',
     AGENT_SCHEDULES: (agentId: string) => `/api/agents/${agentId}/schedules`,
+    AGENT_SCHEDULE_STATS: (agentId: string, days?: number) =>
+      `/api/agents/${agentId}/schedules/stats?days=${days ?? 30}`,
     SCHEDULE: (id: string) => `/api/schedules/${id}`,
     SCHEDULE_RUN_NOW: (id: string) => `/api/schedules/${id}/run`,
     SCHEDULE_RUNS: (id: string, limit?: number, offset?: number) =>
diff --git a/frontend/src/api/services/schedulesService.test.ts b/frontend/src/api/services/schedulesService.test.ts
new file mode 100644
index 00000000..e3f6f33c
--- /dev/null
+++ b/frontend/src/api/services/schedulesService.test.ts
@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import apiClient from '../client';
+import schedulesService from './schedulesService';
+
+afterEach(() => vi.restoreAllMocks());
+
+const response = (body: unknown, status = 200) =>
+  ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  }) as unknown as Response;
+
+describe('schedulesService.statsForAgent', () => {
+  it('returns the stats body on success', async () => {
+    const body = { days: 30, runs: 4, failed: 1, tokens: 120 };
+    vi.spyOn(apiClient, 'get').mockResolvedValue(response(body));
+
+    await expect(schedulesService.statsForAgent('a1', 't')).resolves.toEqual(
+      body,
+    );
+  });
+
+  it('rejects on an error response instead of returning its body as stats', async () => {
+    vi.spyOn(apiClient, 'get').mockResolvedValue(
+      response({ success: false, message: 'Agent not found' }, 404),
+    );
+
+    await expect(schedulesService.statsForAgent('a1', 't')).rejects.toThrow();
+  });
+});
diff --git a/frontend/src/api/services/schedulesService.ts b/frontend/src/api/services/schedulesService.ts
index 7b9d3193..64a3bf35 100644
--- a/frontend/src/api/services/schedulesService.ts
+++ b/frontend/src/api/services/schedulesService.ts
@@ -6,6 +6,7 @@ import type {
   ScheduleResponse,
   ScheduleRunListResponse,
   ScheduleRunResponse,
+  ScheduleStats,
   ScheduleUpdatePayload,
 } from '../../agents/types/schedule';
 
@@ -27,6 +28,23 @@ const schedulesService = {
     return (await json(r)) as ScheduleListResponse;
   },
 
+  statsForAgent: async (
+    agentId: string,
+    token: string | null,
+    days = 30,
+  ): Promise<ScheduleStats> => {
+    const r = await apiClient.get(
+      endpoints.USER.AGENT_SCHEDULE_STATS(agentId, days),
+      token,
+    );
+    // The error body ({success: false, message}) is not stats: reject so the
+    // caller shows "—" instead of empty totals.
+    if (!(r as Response).ok) {
+      throw new Error(`Schedule stats failed: ${(r as Response).status}`);
+    }
+    return (await json(r)) as ScheduleStats;
+  },
+
   create: async (
     agentId: string,
     payload: ScheduleCreatePayload,
diff --git a/frontend/src/components/ArtifactSidebar.test.tsx b/frontend/src/components/ArtifactSidebar.test.tsx
index 43a2d6ed..3899af0d 100644
--- a/frontend/src/components/ArtifactSidebar.test.tsx
+++ b/frontend/src/components/ArtifactSidebar.test.tsx
@@ -43,6 +43,31 @@ describe('ArtifactSidebar', () => {
     container.remove();
   });
 
+  // Every Sheet closes with its built-in X (ghost-muted icon-sm, top-2
+  // right-2); the header only names the artifact.
+  it('closes the phone sheet with the built-in close button', async () => {
+    documentMock.mockResolvedValue({ ok: false, status: 500 });
+    legacyMock.mockRejectedValue(new Error('offline'));
+    await act(async () => {
+      root.render(
+        <ArtifactSidebar
+          isOpen
+          onClose={vi.fn()}
+          artifactId="a1"
+          conversationId="c1"
+          variant="overlay"
+        />,
+      );
+    });
+    const sheet = document.querySelector('[data-slot="sheet-content"]')!;
+    // One close: the Sheet's built-in X, named in the UI language.
+    const closes = sheet.querySelectorAll('button[aria-label="agents.close"]');
+    expect(closes).toHaveLength(1);
+    expect(closes[0].getAttribute('data-variant')).toBe('ghost-muted');
+    expect(sheet.querySelector('[aria-label="Close"]')).toBeNull();
+    expect(sheet.querySelector('[data-slot="sheet-title"]')).not.toBeNull();
+  });
+
   it('shows a failed load as an alert with Retry that refetches', async () => {
     documentMock.mockResolvedValue({ ok: false, status: 500 });
     legacyMock.mockRejectedValue(new Error('offline'));
diff --git a/frontend/src/components/ArtifactSidebar.tsx b/frontend/src/components/ArtifactSidebar.tsx
index 7f465d06..8bfd8914 100644
--- a/frontend/src/components/ArtifactSidebar.tsx
+++ b/frontend/src/components/ArtifactSidebar.tsx
@@ -26,7 +26,7 @@ import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Card } from './ui/card';
 import { IconButton } from './ui/icon-button';
-import { Sheet, SheetContent } from './ui/sheet';
+import { Sheet, SheetContent, SheetTitle } from './ui/sheet';
 
 type TodoItem = {
   todo_id: number;
@@ -528,10 +528,10 @@ export default function ArtifactSidebar({
         <div className="h-14 shrink-0" />
         {/* Artifact panel */}
         <div className="border-border flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border bg-transparent">
-          <div className="flex w-full items-center justify-between px-4 py-2">
-            <span className="text-muted-foreground text-sm font-medium">
+          <div className="flex w-full items-center justify-between gap-2 px-4 py-2">
+            <h2 className="text-foreground min-w-0 text-sm leading-tight font-semibold wrap-anywhere">
               {title}
-            </span>
+            </h2>
             <IconButton
               label={t('agents.close')}
               side="bottom"
@@ -556,27 +556,13 @@ export default function ArtifactSidebar({
         if (!open) onClose();
       }}
     >
-      <SheetContent
-        side="right"
-        showCloseButton={false}
-        title={title || t('components.artifact.preview')}
-        className="h-full w-80 p-0 sm:w-96 sm:max-w-none"
-      >
+      <SheetContent side="right" closeLabel={t('agents.close')} className="p-0">
         <div className="flex min-h-0 flex-1 flex-col">
-          <div className="border-border flex w-full items-center justify-between border-b px-4 py-3">
-            <span className="text-muted-foreground text-sm font-medium">
-              {title}
-            </span>
-            <IconButton
-              label={t('agents.close')}
-              side="bottom"
-              variant="ghost"
-              size="icon"
-              shape="pill"
-              onClick={onClose}
-            >
-              <X aria-hidden="true" className="size-4" />
-            </IconButton>
+          {/* pr-12 keeps the title clear of the built-in close X. */}
+          <div className="border-border flex w-full items-center border-b px-4 py-3 pr-12">
+            <SheetTitle className="min-w-0 text-sm font-semibold wrap-anywhere">
+              {title || t('components.artifact.preview')}
+            </SheetTitle>
           </div>
           <div className="flex-1 overflow-hidden p-4">{renderContent()}</div>
         </div>
diff --git a/frontend/src/components/Chunks.test.tsx b/frontend/src/components/Chunks.test.tsx
index 0a2ef6ad..c3fac55e 100644
--- a/frontend/src/components/Chunks.test.tsx
+++ b/frontend/src/components/Chunks.test.tsx
@@ -124,6 +124,18 @@ describe('Chunks', () => {
     expect(tile.querySelector('.bg-muted')).toBeNull();
   });
 
+  // Decision 79: text tiles follow the container with an auto-fit track that
+  // can't overflow a container narrower than 400px.
+  it('lays the tiles out on the guarded auto-fit text-tile grid', async () => {
+    await render();
+    const grid = container.querySelector<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    )!.parentElement!;
+    expect(grid.className).toBe(
+      'grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]',
+    );
+  });
+
   const renderPath = async (props: {
     onPathSelect?: (depth: number) => void;
     handleGoBack?: () => void;
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index 513e5d8c..541912b9 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -596,11 +596,11 @@ const Chunks: React.FC<ChunksProps> = ({
                 </Button>
               </div>
               {loading ? (
-                <div className="grid w-full grid-cols-1 justify-items-start gap-4 sm:grid-cols-[repeat(auto-fit,minmax(400px,1fr))]">
+                <div className="grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]">
                   <SkeletonLoader component="chunkCards" count={perPage} />
                 </div>
               ) : (
-                <div className="grid w-full grid-cols-1 justify-items-start gap-4 sm:grid-cols-[repeat(auto-fit,minmax(400px,1fr))]">
+                <div className="grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]">
                   {filteredChunks.length === 0 ? (
                     <EmptyState
                       size="sm"
diff --git a/frontend/src/components/ConnectorTree.tsx b/frontend/src/components/ConnectorTree.tsx
index 53538189..a3d8135b 100644
--- a/frontend/src/components/ConnectorTree.tsx
+++ b/frontend/src/components/ConnectorTree.tsx
@@ -113,13 +113,6 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
         shape="pill"
         onClick={() => setSyncConfirmationModal('ACTIVE')}
         disabled={isSyncing}
-        title={
-          isSyncing
-            ? `${t('settings.sources.syncing')} ${syncProgress}%`
-            : syncDone
-              ? 'Done'
-              : t('settings.sources.sync')
-        }
       >
         {syncDone ? (
           <Check />
diff --git a/frontend/src/components/FileUpload.test.tsx b/frontend/src/components/FileUpload.test.tsx
index 33f3ccc4..55ff3e35 100644
--- a/frontend/src/components/FileUpload.test.tsx
+++ b/frontend/src/components/FileUpload.test.tsx
@@ -65,6 +65,28 @@ describe('FileUpload', () => {
     ).toBe('compact');
   });
 
+  it('shows the current image inside a tile until a new one is picked', async () => {
+    await act(async () => {
+      root.render(
+        <FileUpload
+          onUpload={vi.fn()}
+          size="tile"
+          showPreview
+          currentImage="https://example.com/agent.png"
+          uploadText="Avatar"
+        />,
+      );
+    });
+    const zone = container.querySelector('[data-slot="dropzone"]')!;
+    expect(zone.getAttribute('data-size')).toBe('tile');
+    const img = zone.querySelector('img')!;
+    expect(img.getAttribute('src')).toBe('https://example.com/agent.png');
+    expect(img.className).toContain('object-cover');
+    expect(container.textContent).not.toContain(
+      'components.fileUpload.fileTypes',
+    );
+  });
+
   it('renders highlighted upload text segments', async () => {
     await act(async () => {
       root.render(
diff --git a/frontend/src/components/FileUpload.tsx b/frontend/src/components/FileUpload.tsx
index 2fd94c68..f9d65ae8 100644
--- a/frontend/src/components/FileUpload.tsx
+++ b/frontend/src/components/FileUpload.tsx
@@ -21,7 +21,9 @@ interface FileUploadProps {
   showPreview?: boolean;
   previewSize?: number;
   /** `compact` is a one-row target for forms and panels. */
-  size?: 'default' | 'compact';
+  size?: 'default' | 'compact' | 'tile';
+  /** An image already saved (an agent's avatar), shown in a tile until a new one is picked. */
+  currentImage?: string;
 
   children?: React.ReactNode;
   /** Layout classes only; the Dropzone owns colours, border and radius. */
@@ -53,6 +55,7 @@ export const FileUpload = ({
   showPreview = false,
   previewSize = 80,
   size = 'default',
+  currentImage,
   children,
   className,
   uploadText,
@@ -196,8 +199,36 @@ export const FileUpload = ({
 
   // With a preview, the image takes the icon's place; the text block mirrors
   // the Dropzone's own title/description layout.
+  // A tile shows the picked image (with Remove) or the saved one filling it.
+  const tileImage = preview ?? currentImage;
+  const tileContent =
+    size === 'tile' && showPreview && tileImage ? (
+      <span className="relative size-full">
+        <img
+          src={tileImage}
+          alt={t('components.fileUpload.preview')}
+          className="size-full rounded-xl object-cover"
+        />
+        {preview ? (
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              handleRemove();
+            }}
+            className="bg-primary hover:bg-primary/90 absolute -top-2 -right-2 rounded-full p-1 transition-colors"
+            aria-label={t('components.fileUpload.remove')}
+          >
+            <X className="text-primary-foreground size-3" />
+          </button>
+        ) : null}
+      </span>
+    ) : undefined;
+
   const previewContent =
-    showPreview && preview ? (
+    size === 'tile' ? (
+      tileContent
+    ) : showPreview && preview ? (
       <>
         {renderPreview()}
         <span className="flex min-w-0 flex-col gap-0.5">
diff --git a/frontend/src/components/MermaidRenderer.tsx b/frontend/src/components/MermaidRenderer.tsx
index 16c41e2d..1169acf1 100644
--- a/frontend/src/components/MermaidRenderer.tsx
+++ b/frontend/src/components/MermaidRenderer.tsx
@@ -15,6 +15,7 @@ import { renderMermaidDiagram } from './mermaidSecurity';
 import { Alert, AlertDescription } from './ui/alert';
 import { Button } from './ui/button';
 import { IconButton } from './ui/icon-button';
+import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -357,18 +358,22 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
                   >
                     -
                   </IconButton>
-                  <Button
-                    type="button"
-                    variant="link"
-                    size="inline"
-                    onClick={() => setZoomFactor(2)}
-                    title={t('mermaid.resetZoom')}
-                    /* eslint-disable-next-line shadcn/no-restyle --
-                       on the bg-black/70 zoom overlay, like its − / + siblings: keeps the overlay's white 12px regular */
-                    className="text-xs font-normal text-current"
-                  >
-                    {zoomFactor.toFixed(1)}x
-                  </Button>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        type="button"
+                        variant="link"
+                        size="inline"
+                        onClick={() => setZoomFactor(2)}
+                        /* eslint-disable-next-line shadcn/no-restyle --
+                           on the bg-black/70 zoom overlay, like its − / + siblings: keeps the overlay's white 12px regular */
+                        className="text-xs font-normal text-current"
+                      >
+                        {zoomFactor.toFixed(1)}x
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>{t('mermaid.resetZoom')}</TooltipContent>
+                  </Tooltip>
                   <IconButton
                     label={t('mermaid.increaseZoom')}
                     side="bottom"
diff --git a/frontend/src/components/MessageInput.tsx b/frontend/src/components/MessageInput.tsx
index c9a90216..49a7046c 100644
--- a/frontend/src/components/MessageInput.tsx
+++ b/frontend/src/components/MessageInput.tsx
@@ -1851,7 +1851,7 @@ export default function MessageInput({
         createPortal(
           <div className="bg-background/85 pointer-events-none fixed top-0 left-0 z-50 flex size-full flex-col items-center justify-center">
             <CloudUpload className="size-18" />
-            <span className="text-muted-foreground px-2 text-2xl font-bold">
+            <span className="text-foreground px-2 text-xl leading-tight font-semibold">
               {t('modals.uploadDoc.drag.title')}
             </span>
             <span className="text-muted-foreground w-48 p-2 text-center text-sm">
diff --git a/frontend/src/components/PageToolbar.test.tsx b/frontend/src/components/PageToolbar.test.tsx
index 44c95675..1f48c53c 100644
--- a/frontend/src/components/PageToolbar.test.tsx
+++ b/frontend/src/components/PageToolbar.test.tsx
@@ -33,6 +33,15 @@ describe('PageToolbar', () => {
     expect(html).not.toContain('data-slot="separator"');
   });
 
+  // On a phone the row stacks; the action slot spans it, so a caller can
+  // stretch its main button. From sm the slot hugs its buttons.
+  it('lets the action slot span the stacked row on a phone', () => {
+    const html = renderToStaticMarkup(
+      <PageToolbar intro="x" action={<button type="button">Add</button>} />,
+    );
+    expect(html).toContain('<div class="w-full shrink-0 sm:w-auto">');
+  });
+
   it('renders notices between the row and the rule', () => {
     const html = renderToStaticMarkup(
       <PageToolbar intro="x" action={<span />} divider>
diff --git a/frontend/src/components/PageToolbar.tsx b/frontend/src/components/PageToolbar.tsx
index cba98bc9..b1cf3bdd 100644
--- a/frontend/src/components/PageToolbar.tsx
+++ b/frontend/src/components/PageToolbar.tsx
@@ -37,7 +37,11 @@ export default function PageToolbar({
         ) : search ? (
           <div className="w-full max-w-md">{search}</div>
         ) : null}
-        {action ? <div className="shrink-0">{action}</div> : null}
+        {/* Spans the stacked row on a phone, so a caller can stretch its
+            main button; hugs its buttons from sm. */}
+        {action ? (
+          <div className="w-full shrink-0 sm:w-auto">{action}</div>
+        ) : null}
       </div>
       {children}
       {divider ? <Separator className="mb-8" /> : null}
diff --git a/frontend/src/components/SkeletonLoader.test.tsx b/frontend/src/components/SkeletonLoader.test.tsx
new file mode 100644
index 00000000..2a4d07a4
--- /dev/null
+++ b/frontend/src/components/SkeletonLoader.test.tsx
@@ -0,0 +1,58 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import SkeletonLoader from './SkeletonLoader';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('@/hooks', () => ({
+  useMediaQuery: () => ({ isDesktop: true }),
+}));
+
+describe('SkeletonLoader analysis', () => {
+  const html = renderToStaticMarkup(<SkeletonLoader component="analysis" />);
+
+  it('renders chart-shaped Skeleton bars with no pulsing wrapper', () => {
+    expect(html).toContain('flex h-full flex-col justify-end gap-3');
+    expect(html).toContain('grid grid-cols-8 items-end gap-3');
+    // Eight chart bars plus the x-axis bar, all Skeletons.
+    expect(html.match(/data-slot="skeleton"/g)).toHaveLength(9);
+    expect(html).not.toContain('bg-card');
+    expect(html).not.toContain('rounded-3xl');
+    expect(html).not.toContain('p-6');
+    // Only the Skeleton bars pulse.
+    expect(html.match(/animate-pulse/g)).toHaveLength(9);
+  });
+
+  it('fits the 245px chart box: the tallest bar is h-44', () => {
+    expect(html).toContain('h-44');
+    expect(html).not.toMatch(/\bh-(48|52|56|60|64|72|80|96)\b/);
+  });
+
+  it('keeps the loading status for screen readers', () => {
+    expect(html).toContain('role="status"');
+  });
+});
+
+describe('SkeletonLoader connectedState', () => {
+  const html = renderToStaticMarkup(
+    <SkeletonLoader component="connectedState" />,
+  );
+
+  it('is an outline Card row with default-surface Skeleton bars', () => {
+    expect(html).toContain('data-slot="card"');
+    expect(html).toContain('data-variant="outline"');
+    expect(html).toContain('data-padding="sm"');
+    expect(html).toContain('mb-4');
+    expect(html).toContain('flex-row');
+    expect(html).toContain('items-center');
+    expect(html).toContain('justify-between');
+    expect(html.match(/data-slot="skeleton"/g)).toHaveLength(3);
+    expect(html.match(/data-surface="default"/g)).toHaveLength(3);
+    expect(html).not.toContain('bg-muted-foreground/20');
+    // The box does not pulse; only the three bars do.
+    expect(html.match(/animate-pulse/g)).toHaveLength(3);
+  });
+});
diff --git a/frontend/src/components/SkeletonLoader.tsx b/frontend/src/components/SkeletonLoader.tsx
index e35c9f1a..5a4afe74 100644
--- a/frontend/src/components/SkeletonLoader.tsx
+++ b/frontend/src/components/SkeletonLoader.tsx
@@ -14,7 +14,6 @@ interface SkeletonLoaderProps {
     | 'logs'
     | 'fileTable'
     | 'chatbot'
-    | 'dropdown'
     | 'chunkCards'
     | 'sourceCards'
     | 'toolCards'
@@ -86,16 +85,6 @@ const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({
     </>
   );
 
-  const renderDropdown = () => (
-    <div className="animate-pulse">
-      <div className="bg-muted mb-2 h-4 w-24 rounded-sm"></div>
-      <div className="bg-muted flex h-14 w-[360px] items-center justify-between rounded-3xl px-4">
-        <div className="bg-muted-foreground/20 h-3 w-24 rounded-sm"></div>
-        <div className="bg-muted-foreground/20 size-3 rounded-sm"></div>
-      </div>
-    </div>
-  );
-
   const renderLogs = () => (
     <div className="flex w-full flex-col gap-px">
       {[...Array(8)].map((_, idx) => (
@@ -155,34 +144,22 @@ const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({
     </>
   );
 
+  // Renders inside a chart panel's 245px chart box: the panel is the Card,
+  // so only chart-shaped bars (tallest h-44 plus the x-axis, no wrapper).
   const renderAnalysis = () => (
-    <>
-      {[...Array(skeletonCount)].map((_, idx) => (
-        <div key={idx} className="bg-card w-full animate-pulse rounded-3xl p-6">
-          <div className="flex flex-col gap-6">
-            <div className="flex flex-col gap-4">
-              <div className="bg-muted h-4 w-1/3 rounded-sm"></div>
-              <div className="grid grid-cols-6 items-end gap-2">
-                <div className="bg-muted h-32 rounded-sm"></div>
-                <div className="bg-muted h-24 rounded-sm"></div>
-                <div className="bg-muted h-40 rounded-sm"></div>
-                <div className="bg-muted h-28 rounded-sm"></div>
-                <div className="bg-muted h-36 rounded-sm"></div>
-                <div className="bg-muted h-20 rounded-sm"></div>
-              </div>
-            </div>
-            <div className="flex flex-col gap-4">
-              <div className="bg-muted h-4 w-1/4 rounded-sm"></div>
-              <div className="bg-muted h-32 rounded-sm"></div>
-            </div>
-            <div className="grid grid-cols-2 gap-4">
-              <div className="bg-muted h-4 w-full rounded-sm"></div>
-              <div className="bg-muted h-4 w-full rounded-sm"></div>
-            </div>
-          </div>
-        </div>
-      ))}
-    </>
+    <div className="flex h-full flex-col justify-end gap-3">
+      <div className="grid grid-cols-8 items-end gap-3">
+        <Skeleton className="h-20" />
+        <Skeleton className="h-32" />
+        <Skeleton className="h-24" />
+        <Skeleton className="h-40" />
+        <Skeleton className="h-28" />
+        <Skeleton className="h-36" />
+        <Skeleton className="h-16" />
+        <Skeleton className="h-44" />
+      </div>
+      <Skeleton className="h-3 w-full" />
+    </div>
   );
 
   // Mirrors the chunk tile: a filled Card with text lines, then the token
@@ -327,16 +304,20 @@ const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({
     </>
   );
 
+  // Stands in for ConnectorAuth's success Alert: a bordered row box, and
+  // only the bars pulse.
   const renderConnectedState = () => (
-    <div className="mb-4">
-      <div className="bg-muted flex w-full animate-pulse items-center justify-between rounded-lg px-4 py-2">
-        <div className="flex items-center gap-2">
-          <div className="bg-muted-foreground/20 size-4 rounded"></div>
-          <div className="bg-muted-foreground/20 h-4 w-32 rounded"></div>
-        </div>
-        <div className="bg-muted-foreground/20 h-4 w-16 rounded"></div>
+    <Card
+      variant="outline"
+      padding="sm"
+      className="mb-4 flex-row items-center justify-between"
+    >
+      <div className="flex items-center gap-3">
+        <Skeleton className="size-4" />
+        <Skeleton className="h-4 w-48" />
       </div>
-    </div>
+      <Skeleton className="h-4 w-16" />
+    </Card>
   );
 
   const renderFilesSection = () => (
@@ -354,7 +335,6 @@ const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({
   const componentMap = {
     fileTable: renderTable,
     chatbot: renderChatbot,
-    dropdown: renderDropdown,
     logs: renderLogs,
     default: renderDefault,
     analysis: renderAnalysis,
diff --git a/frontend/src/components/message-input/AttachFileButton.tsx b/frontend/src/components/message-input/AttachFileButton.tsx
index a33763ce..b8d9170f 100644
--- a/frontend/src/components/message-input/AttachFileButton.tsx
+++ b/frontend/src/components/message-input/AttachFileButton.tsx
@@ -18,7 +18,7 @@ export default function AttachFileButton({ onChange }: AttachFileButtonProps) {
           user with auto-translate on rage-clicked a dead Attach button until
           they reloaded. Keep the composer's controls out of the translator. */}
       <label translate="no" className="cursor-pointer justify-start">
-        <Paperclip />
+        <Paperclip className="size-3.5 sm:size-4" />
         <span className="text-foreground text-xs sm:text-sm">
           {t('conversation.attachments.attach')}
         </span>
diff --git a/frontend/src/components/message-input/MicButton.tsx b/frontend/src/components/message-input/MicButton.tsx
index c2b17110..4fac5373 100644
--- a/frontend/src/components/message-input/MicButton.tsx
+++ b/frontend/src/components/message-input/MicButton.tsx
@@ -44,7 +44,6 @@ export default function MicButton({
       shape="pill"
       onClick={onClick}
       aria-label={voiceButtonLabel}
-      title={voiceButtonLabel}
       disabled={loading || recordingState === 'transcribing'}
       className="justify-start"
     >
diff --git a/frontend/src/components/message-input/SourcesTrigger.tsx b/frontend/src/components/message-input/SourcesTrigger.tsx
index dbdb86cc..448fe4d4 100644
--- a/frontend/src/components/message-input/SourcesTrigger.tsx
+++ b/frontend/src/components/message-input/SourcesTrigger.tsx
@@ -53,14 +53,16 @@ export default function SourcesTrigger({
           size="sm"
           shape="pill"
           className="max-w-[130px] justify-start sm:max-w-[150px]"
-          title={
-            selectedDocs && selectedDocs.length > 0
-              ? selectedDocs.map((doc) => doc.name).join(', ')
-              : t('conversation.sources.title')
-          }
         >
-          <Database />
-          <span className="text-foreground truncate overflow-hidden text-xs sm:text-sm">
+          <Database className="size-3.5 sm:size-4" />
+          <span
+            className="text-foreground truncate overflow-hidden text-xs sm:text-sm"
+            title={
+              selectedDocs && selectedDocs.length > 0
+                ? selectedDocs.map((doc) => doc.name).join(', ')
+                : undefined
+            }
+          >
             {selectedDocs && selectedDocs.length > 0
               ? selectedDocs.length === 1
                 ? selectedDocs[0].name
diff --git a/frontend/src/components/message-input/ToolsTrigger.tsx b/frontend/src/components/message-input/ToolsTrigger.tsx
index 9fa67a22..c81e1870 100644
--- a/frontend/src/components/message-input/ToolsTrigger.tsx
+++ b/frontend/src/components/message-input/ToolsTrigger.tsx
@@ -53,7 +53,7 @@ export default function ToolsTrigger({
           shape="pill"
           className="max-w-[130px] justify-start"
         >
-          <Wrench />
+          <Wrench className="size-3.5 sm:size-4" />
           <span className="text-foreground truncate overflow-hidden text-xs sm:text-sm">
             {t('settings.tools.label')}
           </span>
diff --git a/frontend/src/components/message-input/composerControls.test.tsx b/frontend/src/components/message-input/composerControls.test.tsx
new file mode 100644
index 00000000..27f3f4f6
--- /dev/null
+++ b/frontend/src/components/message-input/composerControls.test.tsx
@@ -0,0 +1,55 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import AttachFileButton from './AttachFileButton';
+import SourcesTrigger from './SourcesTrigger';
+import ToolsTrigger from './ToolsTrigger';
+
+const iconClass = (html: string, icon: string): string => {
+  const match = html.match(
+    new RegExp(`<svg[^>]*class="([^"]*lucide-${icon}[^"]*)"`),
+  );
+  return match ? match[1] : '';
+};
+
+const noop = () => undefined;
+
+describe('composer controls', () => {
+  it('sizes every control icon size-3.5 sm:size-4', () => {
+    const cases: Array<[string, string]> = [
+      [renderToStaticMarkup(<AttachFileButton onChange={noop} />), 'paperclip'],
+      [
+        renderToStaticMarkup(
+          <ToolsTrigger
+            open={false}
+            onOpenChange={noop}
+            items={[]}
+            selectedIds={[]}
+            onToggle={noop}
+            loading={false}
+          />,
+        ),
+        'wrench',
+      ],
+      [
+        renderToStaticMarkup(
+          <SourcesTrigger
+            open={false}
+            onOpenChange={noop}
+            items={[]}
+            selectedIds={[]}
+            onToggle={noop}
+            selectedDocs={null}
+            onUploadClick={noop}
+          />,
+        ),
+        'database',
+      ],
+    ];
+    for (const [html, icon] of cases) {
+      const classes = iconClass(html, icon).split(' ');
+      expect(classes, icon).toContain('size-3.5');
+      expect(classes, icon).toContain('sm:size-4');
+    }
+  });
+});
diff --git a/frontend/src/components/ui/button.tsx b/frontend/src/components/ui/button.tsx
index d327505d..62832c1d 100644
--- a/frontend/src/components/ui/button.tsx
+++ b/frontend/src/components/ui/button.tsx
@@ -46,7 +46,7 @@ const buttonVariants = cva(
         // (the base is shrink-0), keeping a neighbour's edit button in view.
         combobox:
           'min-w-0 shrink border border-input bg-card font-normal shadow-xs hover:bg-accent data-placeholder:text-muted-foreground',
-        // Underline tabs (FilePicker's drives, the agent page sub-nav). Mark the
+        // Underline route tabs (the workflow builder's sub-nav). Mark the
         // current tab with data-active; the 2px border is always there so the
         // row height doesn't move. The compound variant squares the corners.
         tab: 'border-b-2 border-transparent text-muted-foreground hover:text-foreground hover:border-border data-[active=true]:border-primary data-[active=true]:text-foreground',
diff --git a/frontend/src/components/ui/dropdown-menu.test.tsx b/frontend/src/components/ui/dropdown-menu.test.tsx
index 129db538..77ae2937 100644
--- a/frontend/src/components/ui/dropdown-menu.test.tsx
+++ b/frontend/src/components/ui/dropdown-menu.test.tsx
@@ -50,6 +50,20 @@ describe('ActionMenu', () => {
     expect(trigger().querySelector('svg')).not.toBeNull();
   });
 
+  // A page header or toolbar: the trigger matches the icon buttons beside
+  // 38px buttons on a plain surface, not a highlighted row.
+  it('renders a 36px ghost-muted trigger with size="toolbar"', async () => {
+    await render(
+      <ActionMenu
+        options={options()}
+        triggerLabel="More actions"
+        size="toolbar"
+      />,
+    );
+    expect(trigger().getAttribute('data-variant')).toBe('ghost-muted');
+    expect(trigger().getAttribute('data-size')).toBe('icon');
+  });
+
   it('passes layout classes, disabled and a test id to the trigger', async () => {
     await render(
       <ActionMenu
diff --git a/frontend/src/components/ui/dropdown-menu.tsx b/frontend/src/components/ui/dropdown-menu.tsx
index 48b23dec..33989bb7 100644
--- a/frontend/src/components/ui/dropdown-menu.tsx
+++ b/frontend/src/components/ui/dropdown-menu.tsx
@@ -263,9 +263,12 @@ const stopPropagation = (event: React.SyntheticEvent) =>
  * Clicks and keys on the trigger and the menu stop propagating, because the
  * menu usually sits inside a clickable card and a portal still bubbles
  * through the React tree. The trigger is `ghost-on-accent`: most hosts turn
- * bg-accent while the pointer is on them.
+ * bg-accent while the pointer is on them. In a page header or toolbar
+ * (`size="toolbar"`) it is a 36px `ghost-muted` icon button like the others
+ * there, with its tooltip below.
  *
  * @param options The menu rows.
+ * @param size `row` (a card, tile or row; the default) or `toolbar`.
  * @param triggerLabel The trigger's accessible name.
  * @param className Layout classes for the trigger (position, margin).
  * @param triggerTestId A `data-testid` for the trigger.
@@ -279,6 +282,7 @@ function ActionMenu({
   disabled,
   className,
   triggerTestId,
+  size = 'row',
 }: {
   options: MenuOption[];
   triggerLabel: string;
@@ -288,7 +292,9 @@ function ActionMenu({
   disabled?: boolean;
   className?: string;
   triggerTestId?: string;
+  size?: 'row' | 'toolbar';
 }) {
+  const toolbar = size === 'toolbar';
   return (
     <DropdownMenu open={open} onOpenChange={onOpenChange}>
       <Tooltip>
@@ -297,8 +303,8 @@ function ActionMenu({
           <TooltipTrigger asChild>
             <Button
               type="button"
-              variant="ghost-on-accent"
-              size="icon-xs"
+              variant={toolbar ? 'ghost-muted' : 'ghost-on-accent'}
+              size={toolbar ? 'icon' : 'icon-xs'}
               aria-label={triggerLabel}
               disabled={disabled}
               data-testid={triggerTestId}
@@ -310,7 +316,9 @@ function ActionMenu({
             </Button>
           </TooltipTrigger>
         </DropdownMenuTrigger>
-        <TooltipContent>{triggerLabel}</TooltipContent>
+        <TooltipContent side={toolbar ? 'bottom' : undefined}>
+          {triggerLabel}
+        </TooltipContent>
       </Tooltip>
       <DropdownMenuContent
         align={align}
diff --git a/frontend/src/components/ui/dropzone.test.tsx b/frontend/src/components/ui/dropzone.test.tsx
index 83dbbfbd..d8457a23 100644
--- a/frontend/src/components/ui/dropzone.test.tsx
+++ b/frontend/src/components/ui/dropzone.test.tsx
@@ -36,6 +36,26 @@ describe('Dropzone', () => {
     expect(html).toContain('data-size="compact"');
   });
 
+  it('draws the tile size as an 88px square with a short muted label', () => {
+    const html = renderToStaticMarkup(
+      <Dropzone
+        onDrop={vi.fn()}
+        size="tile"
+        title="Avatar"
+        description="hidden"
+      />,
+    );
+    expect(html).toContain('data-size="tile"');
+    // 64px beside the Name field on a phone, 88px beside both fields from sm.
+    expect(html).toContain('size-16');
+    expect(html).toContain('sm:size-22');
+    // The word shows from sm; on a phone the tile is icon-only.
+    expect(html).toMatch(/class="[^"]*\bsr-only\b[^"]*sm:not-sr-only/);
+    expect(html).not.toContain('w-full cursor-pointer');
+    expect(html).toContain('Avatar');
+    expect(html).not.toContain('hidden</span>');
+  });
+
   it('never uses raw palette colours', () => {
     const html = renderToStaticMarkup(<Dropzone onDrop={vi.fn()} />);
     expect(html).not.toMatch(/\b(bg|text|border)-(gray|red|green|blue)-\d+/);
diff --git a/frontend/src/components/ui/dropzone.tsx b/frontend/src/components/ui/dropzone.tsx
index bd450ef4..656be88b 100644
--- a/frontend/src/components/ui/dropzone.tsx
+++ b/frontend/src/components/ui/dropzone.tsx
@@ -19,6 +19,10 @@ const dropzoneVariants = cva(
       size: {
         default: 'px-6 py-10',
         compact: 'flex-row justify-start px-4 py-3 text-left',
+        // An 88px square beside a form's fields (an agent's avatar): the icon
+        // and a one-word label, or the picked image filling it.
+        // 64px and icon-only on a phone (beside the Name field), 88px from sm.
+        tile: 'size-16 shrink-0 gap-1 rounded-2xl p-2 sm:size-22',
       },
     },
     defaultVariants: { size: 'default' },
@@ -32,6 +36,7 @@ const dropzoneIconVariants = cva(
       size: {
         default: 'size-12 [&>svg]:size-6',
         compact: 'size-8 [&>svg]:size-4',
+        tile: 'size-8 [&>svg]:size-4',
       },
     },
     defaultVariants: { size: 'default' },
@@ -47,8 +52,11 @@ type DropzoneProps = {
   maxFiles?: number;
   maxSize?: number;
   disabled?: boolean;
-  /** Compact fits inside forms and modals; default is the full-height target. */
-  size?: 'default' | 'compact';
+  /**
+   * Compact fits inside forms and modals; default is the full-height target;
+   * tile is an 88px square that shows only the icon and the title.
+   */
+  size?: 'default' | 'compact' | 'tile';
   /** Main line. Defaults to the generic upload prompt. */
   title?: React.ReactNode;
   /** Secondary line for accepted types and limits, e.g. ".yaml, up to 5 MB". */
@@ -111,24 +119,34 @@ function Dropzone({
         data-disabled={disabled || undefined}
         data-drag-active={isDragActive || undefined}
         data-drag-reject={isDragReject || undefined}
-        className={dropzoneVariants({ size })}
+        className={cn(dropzoneVariants({ size }))}
       >
         <input {...getInputProps({ id: field.id })} />
-        {children ?? (
-          <>
-            <span className={dropzoneIconVariants({ size })}>
-              {icon ?? <CloudUpload />}
-            </span>
-            <span className="flex min-w-0 flex-col gap-0.5">
-              <span className="text-sm font-medium">{title}</span>
-              {description ? (
-                <span className="text-muted-foreground text-xs">
-                  {description}
-                </span>
-              ) : null}
-            </span>
-          </>
-        )}
+        {children ??
+          (size === 'tile' ? (
+            <>
+              <span className={dropzoneIconVariants({ size })}>
+                {icon ?? <CloudUpload />}
+              </span>
+              <span className="text-muted-foreground sr-only text-xs sm:not-sr-only">
+                {title}
+              </span>
+            </>
+          ) : (
+            <>
+              <span className={dropzoneIconVariants({ size })}>
+                {icon ?? <CloudUpload />}
+              </span>
+              <span className="flex min-w-0 flex-col gap-0.5">
+                <span className="text-sm font-medium">{title}</span>
+                {description ? (
+                  <span className="text-muted-foreground text-xs">
+                    {description}
+                  </span>
+                ) : null}
+              </span>
+            </>
+          ))}
       </div>
       {error ? <p className="text-destructive text-xs">{error}</p> : null}
     </div>
diff --git a/frontend/src/components/ui/modal.test.tsx b/frontend/src/components/ui/modal.test.tsx
index ca85d0df..834a70b0 100644
--- a/frontend/src/components/ui/modal.test.tsx
+++ b/frontend/src/components/ui/modal.test.tsx
@@ -211,6 +211,9 @@ describe('Modal mobile sheet', () => {
       ]),
     );
     expect(sheet.className).not.toContain('env(');
+    // Every bottom sheet has the sheet elevation, like SheetContent.
+    expect(classes).toContain('shadow-lg');
+    expect(classes).not.toContain('shadow-modal');
     expect(sheet.firstElementChild!.getAttribute('data-slot')).toBe(
       'sheet-handle',
     );
diff --git a/frontend/src/components/ui/modal.tsx b/frontend/src/components/ui/modal.tsx
index 5d2b818c..d41381f4 100644
--- a/frontend/src/components/ui/modal.tsx
+++ b/frontend/src/components/ui/modal.tsx
@@ -127,12 +127,14 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
           // onClick when the user interacts inside the modal.
           onClick={(event) => event.stopPropagation()}
           className={cn(
-            'bg-card text-foreground data-[state=open]:animate-in data-[state=closed]:animate-out shadow-modal fixed z-50 duration-200 outline-none',
+            'bg-card text-foreground data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 duration-200 outline-none',
             isMobileSheet
-              ? // The shared bottom-sheet shape; pb-safe clears the iPhone
-                // home indicator and keeps 1rem under the footer elsewhere.
-                `${sheetBottomShape} pb-safe flex w-full flex-col gap-3 px-4`
+              ? // The shared bottom-sheet shape and the sheet elevation;
+                // pb-safe clears the iPhone home indicator and keeps 1rem
+                // under the footer elsewhere.
+                `${sheetBottomShape} pb-safe flex w-full flex-col gap-3 px-4 shadow-lg`
               : cn(
+                  'shadow-modal',
                   'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 top-1/2 left-1/2 flex max-h-[85dvh] w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 rounded-2xl p-8',
                   SIZE_CLASSES[size],
                   className,
diff --git a/frontend/src/components/ui/multi-select.test.tsx b/frontend/src/components/ui/multi-select.test.tsx
index b5e86acd..704c16bc 100644
--- a/frontend/src/components/ui/multi-select.test.tsx
+++ b/frontend/src/components/ui/multi-select.test.tsx
@@ -1,5 +1,12 @@
 import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: { count?: number }) =>
+      opts?.count !== undefined ? `${key}:${opts.count}` : key,
+  }),
+}));
 
 import { MultiSelect } from './multi-select';
 
@@ -58,7 +65,7 @@ describe('MultiSelect', () => {
       // The hand-rolled chip's heavier tint is gone.
       expect(chip.className.split(' ')).not.toContain('bg-primary/20');
     });
-    expect(host.textContent).toContain('+1 more');
+    expect(host.textContent).toContain('components.multiSelect.more:1');
   });
 });
 
diff --git a/frontend/src/components/ui/multi-select.tsx b/frontend/src/components/ui/multi-select.tsx
index 34cbe59b..855068e3 100644
--- a/frontend/src/components/ui/multi-select.tsx
+++ b/frontend/src/components/ui/multi-select.tsx
@@ -1,5 +1,6 @@
 import { ChevronDown, X } from 'lucide-react';
 import * as React from 'react';
+import { useTranslation } from 'react-i18next';
 
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
@@ -57,6 +58,7 @@ export function MultiSelect({
   modal = false,
   id,
 }: MultiSelectProps) {
+  const { t } = useTranslation();
   const [open, setOpen] = React.useState(false);
   const control = useFormFieldControl<{
     id?: string;
@@ -146,7 +148,9 @@ export function MultiSelect({
                 })}
                 {selected.length > 2 && (
                   <span className="text-muted-foreground text-xs">
-                    +{selected.length - 2} more
+                    {t('components.multiSelect.more', {
+                      count: selected.length - 2,
+                    })}
                   </span>
                 )}
               </>
diff --git a/frontend/src/components/ui/sheet.test.tsx b/frontend/src/components/ui/sheet.test.tsx
index 972ac6a9..bd1a6e33 100644
--- a/frontend/src/components/ui/sheet.test.tsx
+++ b/frontend/src/components/ui/sheet.test.tsx
@@ -103,6 +103,41 @@ describe('SheetContent side="bottom"', () => {
   });
 });
 
+describe('SheetContent side="right" size', () => {
+  const widthClasses = async (size?: 'default' | 'detail' | 'wide') => {
+    await render(
+      <Sheet open>
+        <SheetContent
+          side="right"
+          size={size}
+          title="Drawer"
+          aria-describedby={undefined}
+        />
+      </Sheet>,
+    );
+    return content()
+      .className.split(' ')
+      .filter((c) => /^(sm:|md:|lg:)?(max-)?w-/.test(c));
+  };
+
+  it('is a 384px companion drawer by default', async () => {
+    expect(await widthClasses()).toEqual(['w-3/4', 'sm:max-w-sm']);
+  });
+
+  it('is full width on a phone and 576px from sm at detail', async () => {
+    expect(await widthClasses('detail')).toEqual(['w-full', 'sm:max-w-xl']);
+  });
+
+  it('steps 600 / 700 / 800px at wide', async () => {
+    expect(await widthClasses('wide')).toEqual([
+      'w-full',
+      'sm:max-w-[600px]',
+      'md:max-w-[700px]',
+      'lg:max-w-[800px]',
+    ]);
+  });
+});
+
 describe('SheetOverlay', () => {
   it('uses the blurred scrim every Modal uses', async () => {
     await render(
diff --git a/frontend/src/components/ui/sheet.tsx b/frontend/src/components/ui/sheet.tsx
index eda968bc..96c49a35 100644
--- a/frontend/src/components/ui/sheet.tsx
+++ b/frontend/src/components/ui/sheet.tsx
@@ -47,7 +47,7 @@ function SheetOverlay({
 }
 
 /**
- * The phone bottom-sheet shape: card fill, 16px top corners, capped by
+ * The phone bottom-sheet shape: card fill, 18px top corners, capped by
  * `max-h-sheet` so the scrim above it stays tappable. Shared with Modal's `mobileVariant="sheet"` so every bottom
  * sheet looks the same; the caller adds its own bottom padding (`pb-safe` or
  * `pb-safe-0`).
@@ -76,15 +76,34 @@ const sheetContentVariants = cva(
     variants: {
       side: {
         right:
-          'data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm',
+          'data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full border-l',
         left: 'data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm',
         top: 'data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top inset-x-0 top-0 h-auto border-b',
         // A bottom sheet stacks its handle and parts flush; SheetHeader and
         // SheetFooter bring their own padding.
         bottom: `${sheetBottomShape} pb-safe-0 gap-0`,
       },
+      // A right drawer's width by role (DESIGN.md "Modal, not Dialog"):
+      // default, a companion list read beside the chat (384px); detail, one
+      // record's fields (576px, full width on a phone); wide, a working
+      // surface such as a trace waterfall or an agent preview (600 / 700 /
+      // 800px).
+      size: {
+        default: '',
+        detail: '',
+        wide: '',
+      },
     },
-    defaultVariants: { side: 'right' },
+    compoundVariants: [
+      { side: 'right', size: 'default', class: 'w-3/4 sm:max-w-sm' },
+      { side: 'right', size: 'detail', class: 'w-full sm:max-w-xl' },
+      {
+        side: 'right',
+        size: 'wide',
+        class: 'w-full sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]',
+      },
+    ],
+    defaultVariants: { side: 'right', size: 'default' },
   },
 );
 
@@ -92,17 +111,23 @@ function SheetContent({
   className,
   children,
   side = 'right',
+  size = 'default',
   handle = false,
   // A bottom sheet with a grab handle closes by its scrim, not an X (the
   // handle is only a cue; it doesn't drag).
   showCloseButton = !handle,
+  closeLabel = 'Close',
   title,
   onOpenAutoFocus,
   onCloseAutoFocus,
   ...props
 }: React.ComponentProps<typeof SheetPrimitive.Content> & {
   side?: 'top' | 'right' | 'bottom' | 'left';
+  /** Width of a right drawer: default (384px), detail (576px), wide (800px). */
+  size?: 'default' | 'detail' | 'wide';
   showCloseButton?: boolean;
+  /** Accessible name for the built-in X; pass a translated one. */
+  closeLabel?: string;
   /** Draw the grab bar first (bottom sheets). */
   handle?: boolean;
   // Accessible name for the dialog. Radix warns when a Dialog has no Title;
@@ -117,7 +142,7 @@ function SheetContent({
       <SheetPrimitive.Content
         data-slot="sheet-content"
         data-side={side}
-        className={cn(sheetContentVariants({ side }), className)}
+        className={cn(sheetContentVariants({ side, size }), className)}
         {...props}
         {...focusReturn}
       >
@@ -130,7 +155,7 @@ function SheetContent({
             <Button
               variant="ghost-muted"
               size="icon-sm"
-              aria-label="Close"
+              aria-label={closeLabel}
               className="absolute top-2 right-2"
             >
               <XIcon />
diff --git a/frontend/src/components/ui/table.test.tsx b/frontend/src/components/ui/table.test.tsx
index 85b4b274..c4ce2666 100644
--- a/frontend/src/components/ui/table.test.tsx
+++ b/frontend/src/components/ui/table.test.tsx
@@ -1,5 +1,7 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import {
   Table,
@@ -90,6 +92,47 @@ describe('Table parts', () => {
     expect(clickable).toContain('cursor-pointer');
   });
 
+  it('makes a clickable row focusable and opens it with Enter or Space', async () => {
+    Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+    const onClick = vi.fn();
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    await act(async () =>
+      root.render(
+        <table>
+          <tbody>
+            <TableRow data-testid="plain" />
+            <TableRow data-testid="clickable" onClick={onClick}>
+              <td>
+                <button type="button">Inner</button>
+              </td>
+            </TableRow>
+          </tbody>
+        </table>,
+      ),
+    );
+    const plain = host.querySelector('[data-testid="plain"]')!;
+    const row = host.querySelector<HTMLElement>('[data-testid="clickable"]')!;
+    expect(plain.hasAttribute('tabindex')).toBe(false);
+    expect(row.getAttribute('tabindex')).toBe('0');
+    expect(row.className).toContain('focus-visible:ring-3');
+
+    const key = (target: Element, k: string) =>
+      target.dispatchEvent(
+        new KeyboardEvent('keydown', { key: k, bubbles: true }),
+      );
+    await act(async () => key(row, 'Enter'));
+    await act(async () => key(row, ' '));
+    expect(onClick).toHaveBeenCalledTimes(2);
+    // A key on a control inside the row belongs to that control.
+    await act(async () => key(row.querySelector('button')!, 'Enter'));
+    expect(onClick).toHaveBeenCalledTimes(2);
+
+    await act(async () => root.unmount());
+    host.remove();
+  });
+
   it('keeps the default minimum width on the table', () => {
     const table = render(<Table>{null}</Table>).querySelector('table')!;
     expect(table.className.split(' ')).toContain('min-w-[600px]');
diff --git a/frontend/src/components/ui/table.tsx b/frontend/src/components/ui/table.tsx
index fd96c24f..60c2eecf 100644
--- a/frontend/src/components/ui/table.tsx
+++ b/frontend/src/components/ui/table.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 
-import { cn } from '@/lib/utils';
+import { cn, focusRing } from '@/lib/utils';
 
 type TableProps = React.ComponentProps<'table'> & {
   /** A min-width class; the table scrolls inside TableContainer below it. */
@@ -110,20 +110,37 @@ function TableBody({ className, ...props }: React.ComponentProps<'tbody'>) {
   );
 }
 
+/**
+ * A table row. With `onClick` the whole row is the target, so it also takes
+ * focus and opens with Enter or Space for keyboard users.
+ */
 function TableRow({
   className,
   onClick,
+  onKeyDown,
   ...props
 }: React.ComponentProps<'tr'>) {
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLTableRowElement>) => {
+    onKeyDown?.(event);
+    // Keys on a control inside the row belong to that control.
+    if (event.defaultPrevented || event.target !== event.currentTarget) return;
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      event.currentTarget.click();
+    }
+  };
   return (
     <tr
       data-slot="table-row"
       className={cn(
         'border-border border-b',
-        onClick && 'hover:bg-accent cursor-pointer transition-colors',
+        onClick &&
+          `hover:bg-accent cursor-pointer transition-colors outline-none ${focusRing}`,
         className,
       )}
       onClick={onClick}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? handleKeyDown : onKeyDown}
       {...props}
     />
   );
diff --git a/frontend/src/components/ui/toast.tsx b/frontend/src/components/ui/toast.tsx
index 69ad264b..fc9195c5 100644
--- a/frontend/src/components/ui/toast.tsx
+++ b/frontend/src/components/ui/toast.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { cva, type VariantProps } from 'class-variance-authority';
-import { AlertCircle, Check, Info, TriangleAlert } from 'lucide-react';
+import { Check, CircleAlert, Info, TriangleAlert } from 'lucide-react';
 
 import { Spinner } from '@/components/ui/spinner';
 import { cn } from '@/lib/utils';
@@ -198,7 +198,7 @@ const STATUS_ICON = {
   pending: <Spinner size="sm" />,
   success: <Check strokeWidth={3} />,
   warning: <TriangleAlert strokeWidth={3} />,
-  destructive: <AlertCircle strokeWidth={3} />,
+  destructive: <CircleAlert strokeWidth={3} />,
   info: <Info strokeWidth={3} />,
 } as const;
 
diff --git a/frontend/src/components/ui/tooltip.tsx b/frontend/src/components/ui/tooltip.tsx
index 79a11ad3..c13af465 100644
--- a/frontend/src/components/ui/tooltip.tsx
+++ b/frontend/src/components/ui/tooltip.tsx
@@ -3,7 +3,7 @@ import { Tooltip as TooltipPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
-/** Hover delay before a tooltip opens (Pavel, phase 7: 400ms, not shadcn's 0). */
+/** Hover delay before a tooltip opens: 400ms, not shadcn's 0 (DESIGN.md). */
 const TOOLTIP_DELAY_MS = 400;
 
 /** True under a TooltipProvider, so a Tooltip knows not to add its own. */
diff --git a/frontend/src/conversation/ConversationBubble.test.tsx b/frontend/src/conversation/ConversationBubble.test.tsx
index 62016644..6ae7edd2 100644
--- a/frontend/src/conversation/ConversationBubble.test.tsx
+++ b/frontend/src/conversation/ConversationBubble.test.tsx
@@ -147,7 +147,13 @@ describe('ConversationBubble', () => {
         'wrap-break-word',
       ]),
     );
-    const card = pre.parentElement!;
+    // The scroll cap sits on an inner scroller inside the Card's padding,
+    // so the scrollbar stays clear of the rounded corners.
+    const scroller = pre.parentElement!;
+    expect(scroller.className.split(' ')).toEqual(
+      expect.arrayContaining(['scrollbar-overlay', 'overflow-y-auto']),
+    );
+    const card = scroller.parentElement!;
     expect(card.getAttribute('data-slot')).toBe('card');
     expect(card.getAttribute('data-variant')).toBe('subtle');
     expect(card.getAttribute('data-padding')).toBe('sm');
diff --git a/frontend/src/conversation/ConversationBubble.tsx b/frontend/src/conversation/ConversationBubble.tsx
index 7c3fa653..f8c484c5 100644
--- a/frontend/src/conversation/ConversationBubble.tsx
+++ b/frontend/src/conversation/ConversationBubble.tsx
@@ -612,11 +612,7 @@ const ConversationBubble = forwardRef<
         )}
         {sources && (
           <Sheet open={isSidebarOpen} onOpenChange={setIsSidebarOpen}>
-            <SheetContent
-              side="right"
-              title={t('conversation.sources.title')}
-              className="w-64 sm:w-80 sm:max-w-none"
-            >
+            <SheetContent side="right" title={t('conversation.sources.title')}>
               <div className="flex h-full flex-col items-center gap-2 px-6 py-4 text-center">
                 <AllSources sources={sources} />
               </div>
@@ -832,14 +828,12 @@ function ToolCallApprovalBar({
           <p className="text-muted-foreground mb-1 text-xs font-medium">
             {t('conversation.inlineSteps.arguments')}
           </p>
-          <Card
-            variant="subtle"
-            padding="sm"
-            className="mb-2 max-h-40 overflow-y-auto"
-          >
-            <pre className="font-mono text-xs wrap-break-word whitespace-pre-wrap">
-              {JSON.stringify(toolCall.arguments, null, 2)}
-            </pre>
+          <Card variant="subtle" padding="sm" className="mb-2">
+            <div className="scrollbar-overlay max-h-40 overflow-y-auto">
+              <pre className="font-mono text-xs wrap-break-word whitespace-pre-wrap">
+                {JSON.stringify(toolCall.arguments, null, 2)}
+              </pre>
+            </div>
           </Card>
           <Input
             type="text"
diff --git a/frontend/src/conversation/MarkdownAnswer.tsx b/frontend/src/conversation/MarkdownAnswer.tsx
index 8736645b..ed7c387b 100644
--- a/frontend/src/conversation/MarkdownAnswer.tsx
+++ b/frontend/src/conversation/MarkdownAnswer.tsx
@@ -17,6 +17,11 @@ import { markdownHeadings } from '@/lib/markdown';
 import CopyButton from '../components/CopyButton';
 import MermaidRenderer from '../components/MermaidRenderer';
 import { Button } from '../components/ui/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '../components/ui/tooltip';
 import { useDarkTheme } from '../hooks';
 import classes from './ConversationBubble.module.css';
 import {
@@ -218,33 +223,42 @@ export default function MarkdownAnswer({
                       const num = href.replace('#cite-', '');
                       const sourceIdx = parseInt(num, 10) - 1;
                       return (
-                        <Button
-                          type="button"
-                          variant="secondary"
-                          size="xs"
-                          shape="pill"
-                          onClick={() => {
-                            const el = document.getElementById(
-                              `source-${sourceIdx}`,
-                            );
-                            if (el) {
-                              el.scrollIntoView({
-                                behavior: 'smooth',
-                                block: 'center',
-                              });
-                              el.classList.add('ring-3', 'ring-primary');
-                              setTimeout(
-                                () =>
-                                  el.classList.remove('ring-3', 'ring-primary'),
-                                2000,
-                              );
-                            }
-                          }}
-                          className="mx-0.5 h-5 min-w-5"
-                          title={t('conversation.jumpToSource', { num })}
-                        >
-                          {num}
-                        </Button>
+                        <Tooltip>
+                          <TooltipTrigger asChild>
+                            <Button
+                              type="button"
+                              variant="secondary"
+                              size="xs"
+                              shape="pill"
+                              onClick={() => {
+                                const el = document.getElementById(
+                                  `source-${sourceIdx}`,
+                                );
+                                if (el) {
+                                  el.scrollIntoView({
+                                    behavior: 'smooth',
+                                    block: 'center',
+                                  });
+                                  el.classList.add('ring-3', 'ring-primary');
+                                  setTimeout(
+                                    () =>
+                                      el.classList.remove(
+                                        'ring-3',
+                                        'ring-primary',
+                                      ),
+                                    2000,
+                                  );
+                                }
+                              }}
+                              className="mx-0.5 h-5 min-w-5"
+                            >
+                              {num}
+                            </Button>
+                          </TooltipTrigger>
+                          <TooltipContent>
+                            {t('conversation.jumpToSource', { num })}
+                          </TooltipContent>
+                        </Tooltip>
                       );
                     }
                     return (
@@ -340,6 +354,7 @@ export default function MarkdownAnswer({
                   table({ children }) {
                     return (
                       <div className="border-border relative overflow-x-auto rounded-lg border">
+                        {/* eslint-disable-next-line no-restricted-syntax -- the model's own markdown table, styled by the answer (DESIGN.md, Approved exceptions) */}
                         <table className="text-foreground w-full text-left">
                           {children}
                         </table>
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
index 44315656..742a4ac4 100644
--- a/frontend/src/design/DesignSystem.tsx
+++ b/frontend/src/design/DesignSystem.tsx
@@ -10,6 +10,7 @@ import {
   MoreHorizontal,
   Pencil,
   Pin,
+  Play,
   Plus,
   Search,
   Settings,
@@ -1142,25 +1143,44 @@ export default function DesignSystem() {
           </Example>
           <Example
             title="Action menu"
-            code="<ActionMenu options triggerLabel />"
+            code='<ActionMenu options triggerLabel /> on a tile · size="toolbar" in a page header'
           >
-            <div className="bg-muted hover:bg-accent relative h-24 w-48 rounded-2xl p-4 text-sm">
-              <span className="font-semibold">Vendor Due Diligence</span>
-              <ActionMenu
-                triggerLabel="Agent actions"
-                className="absolute top-3 right-3"
-                options={[
-                  { icon: Pencil, label: 'Edit', onClick: () => {} },
-                  { icon: Copy, label: 'Duplicate', onClick: () => {} },
-                  { icon: Pin, label: 'Pin agent', onClick: () => {} },
-                  {
-                    icon: Trash2,
-                    label: 'Delete',
-                    variant: 'destructive',
-                    onClick: () => {},
-                  },
-                ]}
-              />
+            <div className="flex flex-wrap items-center gap-6">
+              <div className="bg-muted hover:bg-accent relative h-24 w-48 rounded-2xl p-4 text-sm">
+                <span className="font-semibold">Vendor Due Diligence</span>
+                <ActionMenu
+                  triggerLabel="Agent actions"
+                  className="absolute top-3 right-3"
+                  options={[
+                    { icon: Pencil, label: 'Edit', onClick: () => {} },
+                    { icon: Copy, label: 'Duplicate', onClick: () => {} },
+                    { icon: Pin, label: 'Pin agent', onClick: () => {} },
+                    {
+                      icon: Trash2,
+                      label: 'Delete',
+                      variant: 'destructive',
+                      onClick: () => {},
+                    },
+                  ]}
+                />
+              </div>
+              <div className="flex items-center gap-2">
+                <Button variant="outline" size="field" shape="pill">
+                  <Play />
+                  Preview
+                </Button>
+                <Button size="field" shape="pill">
+                  Save
+                </Button>
+                <ActionMenu
+                  size="toolbar"
+                  triggerLabel="More actions"
+                  options={[
+                    { label: 'Access details', onClick: () => {} },
+                    { label: 'Share with team', onClick: () => {} },
+                  ]}
+                />
+              </div>
             </div>
           </Example>
           <Example title="States" code="disabled · asChild">
@@ -2109,8 +2129,8 @@ export default function DesignSystem() {
           intro="Click-or-drag file target used by imports and uploads. Colours follow the drag state; pass accept and limits and describe them in the second line."
         >
           <Example
-            title="Default and compact"
-            code='<Dropzone accept={…} description="…" size="compact">'
+            title="Default, compact and tile"
+            code='<Dropzone accept={…} description="…" size="compact | tile">'
           >
             <div className="grid gap-6 md:grid-cols-2">
               <Dropzone
@@ -2141,6 +2161,17 @@ export default function DesignSystem() {
                   title="With an error"
                   error="Only .yaml or .yml files are supported"
                 />
+                <div className="flex items-center gap-3">
+                  <Dropzone
+                    size="tile"
+                    onDrop={(files) => setDropped(files.map((f) => f.name))}
+                    title="Avatar"
+                  />
+                  <span className="text-muted-foreground text-xs">
+                    size=&quot;tile&quot;: the agent&apos;s avatar beside its
+                    name and description.
+                  </span>
+                </div>
                 <p className="text-muted-foreground text-xs">
                   Last drop:{' '}
                   {dropped.length ? dropped.join(', ') : 'nothing yet'}
@@ -2589,7 +2620,7 @@ export default function DesignSystem() {
         >
           <Example
             title="Modal and sheet"
-            code='<Modal size="md" title description footer={<ModalActions …/>}> · <SheetContent side="right | left | top"> · <SheetContent side="bottom" handle>'
+            code='<Modal size="md" title description footer={<ModalActions …/>}> · <SheetContent side="right" size="default | detail | wide"> · <SheetContent side="left | top"> · <SheetContent side="bottom" handle>'
           >
             <div className="flex flex-wrap items-center gap-3">
               <Button variant="outline" onClick={() => setModalOpen(true)}>
@@ -2627,10 +2658,39 @@ export default function DesignSystem() {
                   <Button variant="outline">Open sheet</Button>
                 </SheetTrigger>
                 <SheetContent side="right">
+                  <SheetHeader>
+                    <SheetTitle>Sources</SheetTitle>
+                    <SheetDescription>
+                      size=&quot;default&quot; (384px): a companion list read
+                      beside the chat.
+                    </SheetDescription>
+                  </SheetHeader>
+                </SheetContent>
+              </Sheet>
+              <Sheet>
+                <SheetTrigger asChild>
+                  <Button variant="outline">Detail sheet</Button>
+                </SheetTrigger>
+                <SheetContent side="right" size="detail">
                   <SheetHeader>
                     <SheetTitle>Run details</SheetTitle>
                     <SheetDescription>
-                      Started 09:30, finished 09:31, 3 tools called.
+                      size=&quot;detail&quot; (576px, full width on a phone):
+                      one record&apos;s fields.
+                    </SheetDescription>
+                  </SheetHeader>
+                </SheetContent>
+              </Sheet>
+              <Sheet>
+                <SheetTrigger asChild>
+                  <Button variant="outline">Wide sheet</Button>
+                </SheetTrigger>
+                <SheetContent side="right" size="wide">
+                  <SheetHeader>
+                    <SheetTitle>Trace</SheetTitle>
+                    <SheetDescription>
+                      size=&quot;wide&quot; (600 / 700 / 800px): a working
+                      surface such as a trace or an agent preview.
                     </SheetDescription>
                   </SheetHeader>
                 </SheetContent>
diff --git a/frontend/src/design/designRules.lint.test.ts b/frontend/src/design/designRules.lint.test.ts
new file mode 100644
index 00000000..654b06a8
--- /dev/null
+++ b/frontend/src/design/designRules.lint.test.ts
@@ -0,0 +1,88 @@
+// @vitest-environment node
+import tsParser from '@typescript-eslint/parser';
+import { Linter } from 'eslint';
+
+import {
+  everywhereSelectors,
+  pageSelectors,
+} from '../../eslint/design-rules.js';
+
+const linter = new Linter({ configType: 'flat' });
+
+const lint = (code: string): number =>
+  linter.verify(
+    code,
+    [
+      {
+        files: ['**/*.tsx'],
+        languageOptions: {
+          parser: tsParser,
+          parserOptions: {
+            ecmaFeatures: { jsx: true },
+            sourceType: 'module',
+          },
+        },
+        rules: {
+          'no-restricted-syntax': [
+            'error',
+            ...everywhereSelectors,
+            ...pageSelectors,
+          ],
+        },
+      },
+    ],
+    'fixture.tsx',
+  ).length;
+
+describe('design rules lint', () => {
+  it.each([
+    ['break-all', `<p className="break-all" />`],
+    ['bare rounded', `<div className="bg-muted rounded px-2" />`],
+    ['bare rounded in cn()', `<div className={cn('p-2 rounded', a && 'x')} />`],
+    ['custom breakpoint', `<div className="min-[500px]:flex" />`],
+    ['media breakpoint', `<div className="[@media(hover:hover)]:block" />`],
+    ['off-scale z', `<div className="absolute z-30" />`],
+    ['arbitrary z', `<div className="z-[60]" />`],
+    ['focus ring-2', `<div className="focus-within:ring-2" />`],
+    ['lucide loader', `import { Loader2 } from 'lucide-react';`],
+    ['transition-all', `<div className="transition-all duration-200" />`],
+    ['hover scale', `<div className="hover:scale-105" />`],
+    ['bg-primary/10', `const tone = 'bg-primary/10 text-primary';`],
+    ['native checkbox', `<input type="checkbox" />`],
+    ['title on Button', `<Button title="Delete" />`],
+    ['raw table', `<table><tbody /></table>`],
+    ['link-styled a', `<a className="text-primary underline" href="#">x</a>`],
+    ['drawer width', `<SheetContent side="right" className="sm:max-w-xl" />`],
+    ['drawer w-', `<SheetContent className="w-80 p-0" />`],
+  ])('rejects %s', (_name, code) => {
+    expect(lint(code)).toBeGreaterThan(0);
+  });
+
+  it.each([
+    [
+      'rounded scale steps',
+      `<div className="rounded-md rounded-t-2xl rounded-full" />`,
+    ],
+    [
+      'layer z values',
+      `<div className="z-10 lg:z-20 z-50 z-200 z-0 z-auto -z-10" />`,
+    ],
+    ['size and max-w', `<div className="size-4 max-w-[520px] min-h-dvh" />`],
+    ['selection ring-2', `<div className="ring-2 ring-primary" />`],
+    ['hover:scale-x underline wipe', `<span className="hover:scale-x-100" />`],
+    ['transition-colors', `<div className="transition-colors" />`],
+    [
+      'other lucide icons',
+      `import { Loader as L } from './local'; import { Plus } from 'lucide-react';`,
+    ],
+    ['a without link styling', `<a className="flex items-center" href="#" />`],
+    ['IconButton label', `<IconButton label="Delete" />`],
+    ['secondary fill', `<span className="bg-secondary bg-primary/90" />`],
+    [
+      'drawer size and layout',
+      `<SheetContent size="wide" className="min-w-0 p-0" />`,
+    ],
+  ])('allows %s', (_name, code) => {
+    expect(lint(code)).toBe(0);
+  });
+});
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index e788de44..0e11563d 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -1018,6 +1018,9 @@
       "start": "Chat starten",
       "name": "Name",
       "choose": "Dateien auswählen",
+      "dropzoneText": "Zum Hochladen klicken oder per Drag & Drop ablegen",
+      "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, Bilder, Audio, EPUB, JSON oder ZIP, jeweils bis zu 25 MB",
+      "filesRejected": "Nicht hinzugefügt (größer als 25 MB oder kein unterstützter Dateityp): {{files}}",
       "info": "Bitte lade .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip hoch (max. 25 MB)",
       "uploadedFiles": "Hochgeladene Dateien",
       "cancel": "Abbrechen",
@@ -1568,15 +1571,16 @@
         "moreActions": "Weitere Aktionen"
       },
       "sections": {
-        "meta": "Meta",
-        "source": "Quelle",
         "prompt": "Prompt",
         "tools": "Werkzeuge",
         "agentType": "Agententyp",
         "models": "Modelle",
         "advanced": "Erweitert",
         "guardrails": "Guardrails",
-        "preview": "Vorschau"
+        "preview": "Vorschau",
+        "basics": "Grundlagen",
+        "knowledge": "Wissen und Verhalten",
+        "model": "Modell"
       },
       "placeholders": {
         "agentName": "Agentenname",
@@ -1621,7 +1625,11 @@
         "research": "Recherche"
       },
       "labels": {
-        "defaultModel": "Standardmodell"
+        "defaultModel": "Standardmodell",
+        "name": "Name",
+        "description": "Beschreibung",
+        "sources": "Quellen",
+        "avatar": "Avatar"
       },
       "advanced": {
         "jsonSchema": "JSON-Antwortschema",
@@ -1636,7 +1644,10 @@
         "systemPromptOverrideDescription": "Erlaubt v1-API-Aufrufern, den System-Prompt dieses Agenten zu ersetzen"
       },
       "preview": {
-        "publishedPreview": "Veröffentlichte Agenten können hier in der Vorschau angezeigt werden"
+        "savedVersion": "gespeicherte Version",
+        "publishTitle": "Zum Testen veröffentlichen",
+        "publishDescription": "Die Vorschau chattet mit dem veröffentlichten Agenten. Entwürfe bleiben privat, bis Sie sie veröffentlichen.",
+        "unsavedChanges": "Sie haben ungespeicherte Änderungen. Die Vorschau nutzt die gespeicherte Version, bis Sie speichern."
       },
       "dangerZone": {
         "heading": "Gefahrenzone",
@@ -1699,6 +1710,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "Richten Sie den Agenten ein und veröffentlichen Sie ihn, um mit ihm zu chatten."
+      },
+      "status": {
+        "published": "Veröffentlicht"
       }
     },
     "logs": {
@@ -1709,7 +1726,6 @@
     },
     "schedules": {
       "title": "Agenten-Zeitpläne",
-      "heading": "Zeitpläne",
       "newRecurring": "Neuer Zeitplan",
       "closeForm": "Formular schließen",
       "edit": "Bearbeiten",
@@ -1805,8 +1821,6 @@
         "output": "Ausgabe",
         "truncated": "(gekürzt)"
       },
-      "timezoneMeta": "Zeitzone: {{timezone}}",
-      "nextRunMeta": "nächster Lauf: {{time}}",
       "toolCard": {
         "cancelFailed": "Abbrechen fehlgeschlagen",
         "taskCancelled": "Geplante Aufgabe abgebrochen.",
@@ -1849,7 +1863,28 @@
       "runLog": {
         "when": "Wann",
         "details": "Details",
-        "empty": "Für diesen Zeitplan wurden noch keine Läufe aufgezeichnet."
+        "empty": "Für diesen Zeitplan wurden noch keine Läufe aufgezeichnet.",
+        "duration": "Dauer"
+      },
+      "actions": "Aktionen für den Zeitplan",
+      "cancelTask": "Aufgabe abbrechen",
+      "failureStreak_one": "{{count}} Fehlschlag in Folge",
+      "failureStreak_other": "{{count}} Fehlschläge in Folge",
+      "meta": {
+        "nextRun": "Nächster Lauf {{time}}",
+        "runsAt": "Läuft am {{time}}",
+        "lastRun": "Letzter Lauf {{time}}"
+      },
+      "stats": {
+        "active": "Aktive Zeitpläne",
+        "nextRun": "Nächster Lauf",
+        "runs": "Läufe, letzte {{days}} Tage",
+        "tokens": "{{tokens}} Tokens",
+        "failed": "Fehlgeschlagen, letzte {{days}} Tage",
+        "latestFailure": "Zuletzt: {{status}}, {{date}}",
+        "paused_one": "{{count}} pausiert",
+        "paused_other": "{{count}} pausiert",
+        "overdue": "Überfällig"
       }
     },
     "shared": {
@@ -2140,6 +2175,10 @@
     },
     "profile": {
       "avatarAlt": "Benutzeravatar"
+    },
+    "multiSelect": {
+      "more_one": "+{{count}} weitere",
+      "more_other": "+{{count}} weitere"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index 1d3e4a2a..00448e40 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -1024,6 +1024,9 @@
       "start": "Start Chatting",
       "name": "Name",
       "choose": "Choose Files",
+      "dropzoneText": "Click to upload or drag and drop",
+      "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, images, audio, EPUB, JSON or ZIP, up to 25 MB each",
+      "filesRejected": "Not added (over 25 MB or not a supported type): {{files}}",
       "info": "Please upload .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip limited to 25mb",
       "uploadedFiles": "Uploaded Files",
       "cancel": "Cancel",
@@ -1585,15 +1588,16 @@
         "moreActions": "More actions"
       },
       "sections": {
-        "meta": "Meta",
-        "source": "Source",
         "prompt": "Prompt",
         "tools": "Tools",
         "agentType": "Agent type",
         "models": "Models",
         "advanced": "Advanced",
         "guardrails": "Guardrails",
-        "preview": "Preview"
+        "preview": "Preview",
+        "basics": "Basics",
+        "knowledge": "Knowledge and behaviour",
+        "model": "Model"
       },
       "placeholders": {
         "agentName": "Agent name",
@@ -1640,7 +1644,9 @@
       "labels": {
         "defaultModel": "Default Model",
         "name": "Name",
-        "description": "Description"
+        "description": "Description",
+        "sources": "Sources",
+        "avatar": "Avatar"
       },
       "advanced": {
         "jsonSchema": "JSON response schema",
@@ -1657,7 +1663,10 @@
         "requestLimit": "Request limit"
       },
       "preview": {
-        "publishedPreview": "Published agents can be previewed here"
+        "savedVersion": "saved version",
+        "publishTitle": "Publish to preview",
+        "publishDescription": "The preview chats with the published agent. Drafts stay private until you publish.",
+        "unsavedChanges": "You have unsaved changes. The preview uses the saved version until you save."
       },
       "dangerZone": {
         "heading": "Danger zone",
@@ -1720,6 +1729,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "Set up the agent, then publish it to chat with it."
+      },
+      "status": {
+        "published": "Published"
       }
     },
     "logs": {
@@ -1730,7 +1745,6 @@
     },
     "schedules": {
       "title": "Agent Schedules",
-      "heading": "Schedules",
       "newRecurring": "New schedule",
       "closeForm": "Close form",
       "edit": "Edit",
@@ -1828,8 +1842,6 @@
         "output": "Output",
         "truncated": "(truncated)"
       },
-      "timezoneMeta": "tz: {{timezone}}",
-      "nextRunMeta": "next: {{time}}",
       "toolCard": {
         "cancelFailed": "Cancel failed",
         "taskCancelled": "Scheduled task cancelled.",
@@ -1872,7 +1884,28 @@
       "runLog": {
         "when": "When",
         "details": "Details",
-        "empty": "No runs recorded for this schedule yet."
+        "empty": "No runs recorded for this schedule yet.",
+        "duration": "Duration"
+      },
+      "actions": "Schedule actions",
+      "cancelTask": "Cancel task",
+      "failureStreak_one": "{{count}} failure in a row",
+      "failureStreak_other": "{{count}} failures in a row",
+      "meta": {
+        "nextRun": "Next run {{time}}",
+        "runsAt": "Runs on {{time}}",
+        "lastRun": "Last run {{time}}"
+      },
+      "stats": {
+        "active": "Active schedules",
+        "nextRun": "Next run",
+        "runs": "Runs, last {{days}} days",
+        "tokens": "{{tokens}} tokens",
+        "failed": "Failed, last {{days}} days",
+        "latestFailure": "Latest: {{status}}, {{date}}",
+        "paused_one": "{{count}} paused",
+        "paused_other": "{{count}} paused",
+        "overdue": "Overdue"
       }
     },
     "shared": {
@@ -2176,6 +2209,10 @@
     },
     "profile": {
       "avatarAlt": "User avatar"
+    },
+    "multiSelect": {
+      "more_one": "+{{count}} more",
+      "more_other": "+{{count}} more"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index 90b38b89..fc0cdc10 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -1018,6 +1018,9 @@
       "start": "Comenzar a chatear",
       "name": "Nombre",
       "choose": "Seleccionar Archivos",
+      "dropzoneText": "Haz clic para subir o arrastra y suelta",
+      "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, imágenes, audio, EPUB, JSON o ZIP, hasta 25 MB cada uno",
+      "filesRejected": "No se añadieron (más de 25 MB o tipo no admitido): {{files}}",
       "info": "Por favor, sube archivos .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip limitados a 25MB",
       "uploadedFiles": "Archivos Subidos",
       "cancel": "Cancelar",
@@ -1568,15 +1571,16 @@
         "moreActions": "Más acciones"
       },
       "sections": {
-        "meta": "Meta",
-        "source": "Fuente",
         "prompt": "Prompt",
         "tools": "Herramientas",
         "agentType": "Tipo de agente",
         "models": "Modelos",
         "advanced": "Avanzado",
         "guardrails": "Guardrails",
-        "preview": "Vista previa"
+        "preview": "Vista previa",
+        "basics": "Básico",
+        "knowledge": "Conocimiento y comportamiento",
+        "model": "Modelo"
       },
       "placeholders": {
         "agentName": "Nombre del agente",
@@ -1621,7 +1625,11 @@
         "research": "Investigación"
       },
       "labels": {
-        "defaultModel": "Modelo Predeterminado"
+        "defaultModel": "Modelo Predeterminado",
+        "name": "Nombre",
+        "description": "Descripción",
+        "sources": "Fuentes",
+        "avatar": "Avatar"
       },
       "advanced": {
         "jsonSchema": "Esquema de respuesta JSON",
@@ -1636,7 +1644,10 @@
         "systemPromptOverrideDescription": "Permitir que los llamadores de la API v1 reemplacen el prompt del sistema de este agente"
       },
       "preview": {
-        "publishedPreview": "Los agentes publicados se pueden previsualizar aquí"
+        "savedVersion": "versión guardada",
+        "publishTitle": "Publica para probarlo",
+        "publishDescription": "La vista previa chatea con el agente publicado. Los borradores siguen siendo privados hasta que los publiques.",
+        "unsavedChanges": "Tienes cambios sin guardar. La vista previa usa la versión guardada hasta que guardes."
       },
       "dangerZone": {
         "heading": "Zona de peligro",
@@ -1699,6 +1710,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "Configura el agente y publícalo para chatear con él."
+      },
+      "status": {
+        "published": "Publicado"
       }
     },
     "logs": {
@@ -1709,7 +1726,6 @@
     },
     "schedules": {
       "title": "Programaciones del Agente",
-      "heading": "Programaciones",
       "newRecurring": "Nueva programación",
       "closeForm": "Cerrar formulario",
       "edit": "Editar",
@@ -1805,8 +1821,6 @@
         "output": "Salida",
         "truncated": "(truncada)"
       },
-      "timezoneMeta": "zona horaria: {{timezone}}",
-      "nextRunMeta": "próxima: {{time}}",
       "toolCard": {
         "cancelFailed": "No se pudo cancelar",
         "taskCancelled": "Tarea programada cancelada.",
@@ -1849,7 +1863,28 @@
       "runLog": {
         "when": "Cuándo",
         "details": "Detalles",
-        "empty": "Aún no hay ejecuciones registradas para esta programación."
+        "empty": "Aún no hay ejecuciones registradas para esta programación.",
+        "duration": "Duración"
+      },
+      "actions": "Acciones de la programación",
+      "cancelTask": "Cancelar tarea",
+      "failureStreak_one": "{{count}} fallo seguido",
+      "failureStreak_other": "{{count}} fallos seguidos",
+      "meta": {
+        "nextRun": "Próxima ejecución {{time}}",
+        "runsAt": "Se ejecuta el {{time}}",
+        "lastRun": "Última ejecución {{time}}"
+      },
+      "stats": {
+        "active": "Programaciones activas",
+        "nextRun": "Próxima ejecución",
+        "runs": "Ejecuciones, últimos {{days}} días",
+        "tokens": "{{tokens}} tokens",
+        "failed": "Fallidas, últimos {{days}} días",
+        "latestFailure": "Última: {{status}}, {{date}}",
+        "paused_one": "{{count}} en pausa",
+        "paused_other": "{{count}} en pausa",
+        "overdue": "Atrasada"
       }
     },
     "shared": {
@@ -2140,6 +2175,10 @@
     },
     "profile": {
       "avatarAlt": "Avatar del usuario"
+    },
+    "multiSelect": {
+      "more_one": "+{{count}} más",
+      "more_other": "+{{count}} más"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index 41cf29f1..76ddede1 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -1017,6 +1017,9 @@
       "start": "チャットを開始する",
       "name": "名前",
       "choose": "ファイルを選択",
+      "dropzoneText": "クリックしてアップロード、またはドラッグ＆ドロップ",
+      "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、画像、音声、EPUB、JSON、ZIP（各 25 MB まで）",
+      "filesRejected": "追加されませんでした（25 MB を超えているか、未対応の形式です）: {{files}}",
       "info": "25MBまでの.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zipファイルをアップロードしてください",
       "uploadedFiles": "アップロードされたファイル",
       "cancel": "キャンセル",
@@ -1564,15 +1567,16 @@
         "moreActions": "その他のアクション"
       },
       "sections": {
-        "meta": "メタ",
-        "source": "ソース",
         "prompt": "プロンプト",
         "tools": "ツール",
         "agentType": "エージェントタイプ",
         "models": "モデル",
         "advanced": "詳細設定",
         "guardrails": "Guardrails",
-        "preview": "プレビュー"
+        "preview": "プレビュー",
+        "basics": "基本情報",
+        "knowledge": "ナレッジと動作",
+        "model": "モデル"
       },
       "placeholders": {
         "agentName": "エージェント名",
@@ -1617,7 +1621,11 @@
         "research": "リサーチ"
       },
       "labels": {
-        "defaultModel": "デフォルトモデル"
+        "defaultModel": "デフォルトモデル",
+        "name": "名前",
+        "description": "説明",
+        "sources": "ソース",
+        "avatar": "アバター"
       },
       "advanced": {
         "jsonSchema": "JSON応答スキーマ",
@@ -1632,7 +1640,10 @@
         "systemPromptOverrideDescription": "v1 API呼び出し元がこのエージェントのシステムプロンプトを置き換えることを許可します"
       },
       "preview": {
-        "publishedPreview": "公開されたエージェントはここでプレビューできます"
+        "savedVersion": "保存済みバージョン",
+        "publishTitle": "公開してプレビュー",
+        "publishDescription": "プレビューは公開済みのエージェントとチャットします。下書きは公開するまで非公開のままです。",
+        "unsavedChanges": "保存されていない変更があります。保存するまで、プレビューは保存済みのバージョンを使います。"
       },
       "dangerZone": {
         "heading": "危険ゾーン",
@@ -1694,6 +1705,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "エージェントを設定し、公開するとチャットできます。"
+      },
+      "status": {
+        "published": "公開済み"
       }
     },
     "logs": {
@@ -1704,7 +1721,6 @@
     },
     "schedules": {
       "title": "エージェントスケジュール",
-      "heading": "スケジュール",
       "newRecurring": "新しいスケジュール",
       "closeForm": "フォームを閉じる",
       "edit": "編集",
@@ -1800,8 +1816,6 @@
         "output": "出力",
         "truncated": "（切り詰め）"
       },
-      "timezoneMeta": "タイムゾーン: {{timezone}}",
-      "nextRunMeta": "次回: {{time}}",
       "toolCard": {
         "cancelFailed": "キャンセルに失敗しました",
         "taskCancelled": "予約タスクをキャンセルしました。",
@@ -1844,7 +1858,28 @@
       "runLog": {
         "when": "日時",
         "details": "詳細",
-        "empty": "このスケジュールの実行記録はまだありません。"
+        "empty": "このスケジュールの実行記録はまだありません。",
+        "duration": "所要時間"
+      },
+      "actions": "スケジュールの操作",
+      "cancelTask": "タスクをキャンセル",
+      "failureStreak_one": "{{count}}回連続で失敗",
+      "failureStreak_other": "{{count}}回連続で失敗",
+      "meta": {
+        "nextRun": "次回実行: {{time}}",
+        "runsAt": "実行日時: {{time}}",
+        "lastRun": "前回実行: {{time}}"
+      },
+      "stats": {
+        "active": "有効なスケジュール",
+        "nextRun": "次回実行",
+        "runs": "実行回数（過去{{days}}日）",
+        "tokens": "{{tokens}} トークン",
+        "failed": "失敗（過去{{days}}日）",
+        "latestFailure": "最新: {{status}}、{{date}}",
+        "paused_one": "{{count}}件一時停止中",
+        "paused_other": "{{count}}件一時停止中",
+        "overdue": "期限超過"
       }
     },
     "shared": {
@@ -2134,6 +2169,10 @@
     },
     "profile": {
       "avatarAlt": "ユーザーのアバター"
+    },
+    "multiSelect": {
+      "more_one": "他{{count}}件",
+      "more_other": "他{{count}}件"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index 7a9d0352..556a85d3 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -1058,6 +1058,9 @@
       "start": "Начать чат",
       "name": "Имя",
       "choose": "Выбрать файлы",
+      "dropzoneText": "Нажмите, чтобы загрузить, или перетащите файлы",
+      "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, изображения, аудио, EPUB, JSON или ZIP, до 25 МБ каждый",
+      "filesRejected": "Не добавлены (больше 25 МБ или неподдерживаемый формат): {{files}}",
       "info": "Пожалуйста, загрузите файлы .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip размером до 25 МБ",
       "uploadedFiles": "Загруженные файлы",
       "cancel": "Отмена",
@@ -1614,15 +1617,16 @@
         "moreActions": "Другие действия"
       },
       "sections": {
-        "meta": "Мета",
-        "source": "Источник",
         "prompt": "Промпт",
         "tools": "Инструменты",
         "agentType": "Тип агента",
         "models": "Модели",
         "advanced": "Расширенные",
         "guardrails": "Guardrails",
-        "preview": "Предпросмотр"
+        "preview": "Предпросмотр",
+        "basics": "Основное",
+        "knowledge": "Знания и поведение",
+        "model": "Модель"
       },
       "placeholders": {
         "agentName": "Имя агента",
@@ -1667,7 +1671,11 @@
         "research": "Исследование"
       },
       "labels": {
-        "defaultModel": "Модель по умолчанию"
+        "defaultModel": "Модель по умолчанию",
+        "name": "Имя",
+        "description": "Описание",
+        "sources": "Источники",
+        "avatar": "Аватар"
       },
       "advanced": {
         "jsonSchema": "Схема ответа JSON",
@@ -1682,7 +1690,10 @@
         "systemPromptOverrideDescription": "Разрешить вызовам API v1 заменять системный промпт этого агента"
       },
       "preview": {
-        "publishedPreview": "Опубликованные агенты можно просмотреть здесь"
+        "savedVersion": "сохранённая версия",
+        "publishTitle": "Опубликуйте, чтобы проверить",
+        "publishDescription": "Предпросмотр общается с опубликованным агентом. Черновики остаются приватными, пока вы их не опубликуете.",
+        "unsavedChanges": "Есть несохранённые изменения. Пока вы не сохраните, предпросмотр использует сохранённую версию."
       },
       "dangerZone": {
         "heading": "Опасная зона",
@@ -1747,6 +1758,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "Настройте агента и опубликуйте его, чтобы с ним общаться."
+      },
+      "status": {
+        "published": "Опубликован"
       }
     },
     "logs": {
@@ -1757,7 +1774,6 @@
     },
     "schedules": {
       "title": "Расписания агента",
-      "heading": "Расписания",
       "newRecurring": "Новое расписание",
       "closeForm": "Закрыть форму",
       "edit": "Редактировать",
@@ -1853,8 +1869,6 @@
         "output": "Результат",
         "truncated": "(обрезано)"
       },
-      "timezoneMeta": "часовой пояс: {{timezone}}",
-      "nextRunMeta": "следующий: {{time}}",
       "toolCard": {
         "cancelFailed": "Не удалось отменить",
         "taskCancelled": "Запланированная задача отменена.",
@@ -1899,7 +1913,32 @@
       "runLog": {
         "when": "Когда",
         "details": "Подробнее",
-        "empty": "Для этого расписания пока нет запусков."
+        "empty": "Для этого расписания пока нет запусков.",
+        "duration": "Длительность"
+      },
+      "actions": "Действия с расписанием",
+      "cancelTask": "Отменить задачу",
+      "failureStreak_one": "{{count}} сбой подряд",
+      "failureStreak_few": "{{count}} сбоя подряд",
+      "failureStreak_many": "{{count}} сбоев подряд",
+      "failureStreak_other": "{{count}} сбоя подряд",
+      "meta": {
+        "nextRun": "Следующий запуск {{time}}",
+        "runsAt": "Запуск {{time}}",
+        "lastRun": "Последний запуск {{time}}"
+      },
+      "stats": {
+        "active": "Активные расписания",
+        "nextRun": "Следующий запуск",
+        "runs": "Запуски за {{days}} дней",
+        "tokens": "{{tokens}} токенов",
+        "failed": "Сбои за {{days}} дней",
+        "latestFailure": "Последний: {{status}}, {{date}}",
+        "paused_one": "{{count}} приостановлено",
+        "paused_few": "{{count}} приостановлено",
+        "paused_many": "{{count}} приостановлено",
+        "paused_other": "{{count}} приостановлено",
+        "overdue": "Просрочено"
       }
     },
     "shared": {
@@ -2198,6 +2237,12 @@
     },
     "profile": {
       "avatarAlt": "Аватар пользователя"
+    },
+    "multiSelect": {
+      "more_one": "+ещё {{count}}",
+      "more_few": "+ещё {{count}}",
+      "more_many": "+ещё {{count}}",
+      "more_other": "+ещё {{count}}"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index ff1d2efc..4b9a5170 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -1017,6 +1017,9 @@
       "start": "開始對話",
       "name": "名稱",
       "choose": "選擇檔案",
+      "dropzoneText": "點擊上傳或拖放檔案",
+      "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、圖片、音訊、EPUB、JSON 或 ZIP，每個最大 25 MB",
+      "filesRejected": "未新增（超過 25 MB 或不支援的類型）：{{files}}",
       "info": "請上傳限制為25MB的.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zip檔案",
       "uploadedFiles": "已上傳檔案",
       "cancel": "取消",
@@ -1564,15 +1567,16 @@
         "moreActions": "更多操作"
       },
       "sections": {
-        "meta": "中繼資料",
-        "source": "來源",
         "prompt": "提示詞",
         "tools": "工具",
         "agentType": "代理類型",
         "models": "模型",
         "advanced": "進階",
         "guardrails": "Guardrails",
-        "preview": "預覽"
+        "preview": "預覽",
+        "basics": "基本資訊",
+        "knowledge": "知識與行為",
+        "model": "模型"
       },
       "placeholders": {
         "agentName": "代理名稱",
@@ -1617,7 +1621,11 @@
         "research": "研究"
       },
       "labels": {
-        "defaultModel": "預設模型"
+        "defaultModel": "預設模型",
+        "name": "名稱",
+        "description": "描述",
+        "sources": "來源",
+        "avatar": "頭像"
       },
       "advanced": {
         "jsonSchema": "JSON回應架構",
@@ -1632,7 +1640,10 @@
         "systemPromptOverrideDescription": "允許 v1 API 呼叫者替換此代理的系統提示詞"
       },
       "preview": {
-        "publishedPreview": "已發佈的代理可以在此處預覽"
+        "savedVersion": "已儲存版本",
+        "publishTitle": "發佈後即可預覽",
+        "publishDescription": "預覽會與已發佈的代理對話。草稿在發佈前會保持私密。",
+        "unsavedChanges": "你有未儲存的變更。儲存之前，預覽會使用已儲存的版本。"
       },
       "dangerZone": {
         "heading": "危險區域",
@@ -1694,6 +1705,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "設定好代理後發佈，即可與它對話。"
+      },
+      "status": {
+        "published": "已發佈"
       }
     },
     "logs": {
@@ -1704,7 +1721,6 @@
     },
     "schedules": {
       "title": "代理排程",
-      "heading": "排程",
       "newRecurring": "新增排程",
       "closeForm": "關閉表單",
       "edit": "編輯",
@@ -1800,8 +1816,6 @@
         "output": "輸出",
         "truncated": "（已截斷）"
       },
-      "timezoneMeta": "時區：{{timezone}}",
-      "nextRunMeta": "下次：{{time}}",
       "toolCard": {
         "cancelFailed": "取消失敗",
         "taskCancelled": "已取消排程工作。",
@@ -1844,7 +1858,28 @@
       "runLog": {
         "when": "時間",
         "details": "詳細資料",
-        "empty": "此排程尚無執行紀錄。"
+        "empty": "此排程尚無執行紀錄。",
+        "duration": "時長"
+      },
+      "actions": "排程操作",
+      "cancelTask": "取消任務",
+      "failureStreak_one": "連續失敗 {{count}} 次",
+      "failureStreak_other": "連續失敗 {{count}} 次",
+      "meta": {
+        "nextRun": "下次執行：{{time}}",
+        "runsAt": "執行時間：{{time}}",
+        "lastRun": "上次執行：{{time}}"
+      },
+      "stats": {
+        "active": "啟用中的排程",
+        "nextRun": "下次執行",
+        "runs": "執行次數（近 {{days}} 天）",
+        "tokens": "{{tokens}} 個權杖",
+        "failed": "失敗（近 {{days}} 天）",
+        "latestFailure": "最近：{{status}}，{{date}}",
+        "paused_one": "{{count}} 個已暫停",
+        "paused_other": "{{count}} 個已暫停",
+        "overdue": "已逾期"
       }
     },
     "shared": {
@@ -2134,6 +2169,10 @@
     },
     "profile": {
       "avatarAlt": "使用者頭像"
+    },
+    "multiSelect": {
+      "more_one": "另外 {{count}} 個",
+      "more_other": "另外 {{count}} 個"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index 36dc4e58..ce9a846f 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -1017,6 +1017,9 @@
       "start": "开始聊天",
       "name": "名称",
       "choose": "选择文件",
+      "dropzoneText": "点击上传或拖放文件",
+      "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、图片、音频、EPUB、JSON 或 ZIP，每个最大 25 MB",
+      "filesRejected": "未添加（超过 25 MB 或不支持的类型）：{{files}}",
       "info": "请上传限制为25MB的.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zip文件",
       "uploadedFiles": "已上传文件",
       "cancel": "取消",
@@ -1564,15 +1567,16 @@
         "moreActions": "更多操作"
       },
       "sections": {
-        "meta": "元数据",
-        "source": "来源",
         "prompt": "提示词",
         "tools": "工具",
         "agentType": "代理类型",
         "models": "模型",
         "advanced": "高级",
         "guardrails": "Guardrails",
-        "preview": "预览"
+        "preview": "预览",
+        "basics": "基本信息",
+        "knowledge": "知识与行为",
+        "model": "模型"
       },
       "placeholders": {
         "agentName": "代理名称",
@@ -1617,7 +1621,11 @@
         "research": "研究"
       },
       "labels": {
-        "defaultModel": "默认模型"
+        "defaultModel": "默认模型",
+        "name": "名称",
+        "description": "描述",
+        "sources": "来源",
+        "avatar": "头像"
       },
       "advanced": {
         "jsonSchema": "JSON响应架构",
@@ -1632,7 +1640,10 @@
         "systemPromptOverrideDescription": "允许 v1 API 调用者替换此代理的系统提示词"
       },
       "preview": {
-        "publishedPreview": "已发布的代理可以在此处预览"
+        "savedVersion": "已保存版本",
+        "publishTitle": "发布后即可预览",
+        "publishDescription": "预览会与已发布的智能体对话。草稿在发布前保持私密。",
+        "unsavedChanges": "你有未保存的更改。保存之前，预览使用已保存的版本。"
       },
       "dangerZone": {
         "heading": "危险区域",
@@ -1694,6 +1705,12 @@
           "monitorOnly": "Monitor only",
           "scanAll": "Enforce everywhere"
         }
+      },
+      "byline": {
+        "new": "设置好智能体后发布，即可与它对话。"
+      },
+      "status": {
+        "published": "已发布"
       }
     },
     "logs": {
@@ -1704,7 +1721,6 @@
     },
     "schedules": {
       "title": "代理计划",
-      "heading": "计划",
       "newRecurring": "新建计划",
       "closeForm": "关闭表单",
       "edit": "编辑",
@@ -1800,8 +1816,6 @@
         "output": "输出",
         "truncated": "（已截断）"
       },
-      "timezoneMeta": "时区：{{timezone}}",
-      "nextRunMeta": "下次：{{time}}",
       "toolCard": {
         "cancelFailed": "取消失败",
         "taskCancelled": "已取消计划任务。",
@@ -1844,7 +1858,28 @@
       "runLog": {
         "when": "时间",
         "details": "详情",
-        "empty": "此计划尚无运行记录。"
+        "empty": "此计划尚无运行记录。",
+        "duration": "时长"
+      },
+      "actions": "计划操作",
+      "cancelTask": "取消任务",
+      "failureStreak_one": "连续失败 {{count}} 次",
+      "failureStreak_other": "连续失败 {{count}} 次",
+      "meta": {
+        "nextRun": "下次运行：{{time}}",
+        "runsAt": "运行时间：{{time}}",
+        "lastRun": "上次运行：{{time}}"
+      },
+      "stats": {
+        "active": "活跃的计划",
+        "nextRun": "下次运行",
+        "runs": "运行次数（近 {{days}} 天）",
+        "tokens": "{{tokens}} 个令牌",
+        "failed": "失败（近 {{days}} 天）",
+        "latestFailure": "最近：{{status}}，{{date}}",
+        "paused_one": "{{count}} 个已暂停",
+        "paused_other": "{{count}} 个已暂停",
+        "overdue": "已逾期"
       }
     },
     "shared": {
@@ -2134,6 +2169,10 @@
     },
     "profile": {
       "avatarAlt": "用户头像"
+    },
+    "multiSelect": {
+      "more_one": "另外 {{count}} 个",
+      "more_other": "另外 {{count}} 个"
     }
   },
   "pageNotFound": {
diff --git a/frontend/src/navigation/SectionPageHeader.tsx b/frontend/src/navigation/SectionPageHeader.tsx
index 2e79e903..615d92d2 100644
--- a/frontend/src/navigation/SectionPageHeader.tsx
+++ b/frontend/src/navigation/SectionPageHeader.tsx
@@ -1,3 +1,4 @@
+import type React from 'react';
 import { ArrowLeft } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { Link, useLocation } from 'react-router-dom';
@@ -59,22 +60,39 @@ export function SectionBackLink({
 export default function SectionPageHeader({
   section,
   item,
+  title,
+  titleAction,
   className,
 }: {
   section: Section;
   item: SectionItem | null;
+  /** Replaces the resolved title. */
+  title?: React.ReactNode;
+  /** A control at the end of the title row. */
+  titleAction?: React.ReactNode;
   className?: string;
 }) {
   const { t } = useTranslation();
+  const heading = (
+    <h1 className="text-foreground text-2xl font-bold">
+      {title ??
+        (item && section.pageTitle !== 'section'
+          ? t(item.labelKey)
+          : (section.title ?? t(section.titleKey)))}
+    </h1>
+  );
 
   return (
     <div className={cn('flex flex-col', className)}>
       <SectionBackLink section={section} />
-      <h1 className="text-foreground text-2xl font-bold">
-        {item && section.pageTitle !== 'section'
-          ? t(item.labelKey)
-          : (section.title ?? t(section.titleKey))}
-      </h1>
+      {titleAction ? (
+        <div className="flex items-center justify-between gap-3">
+          {heading}
+          {titleAction}
+        </div>
+      ) : (
+        heading
+      )}
     </div>
   );
 }
@@ -84,11 +102,25 @@ export default function SectionPageHeader({
  * from resolving its own section, and keeps the heading identical across
  * settings, admin and agents.
  */
-export function CurrentSectionHeader({ className }: { className?: string }) {
+export function CurrentSectionHeader({
+  title,
+  titleAction,
+  className,
+}: {
+  title?: React.ReactNode;
+  titleAction?: React.ReactNode;
+  className?: string;
+}) {
   const { section, item } = useSectionContext();
 
   if (!section) return null;
   return (
-    <SectionPageHeader section={section} item={item} className={className} />
+    <SectionPageHeader
+      section={section}
+      item={item}
+      title={title}
+      titleAction={titleAction}
+      className={className}
+    />
   );
 }
diff --git a/frontend/src/navigation/SectionPills.tsx b/frontend/src/navigation/SectionPills.tsx
index 4a4d10f0..4ecb590e 100644
--- a/frontend/src/navigation/SectionPills.tsx
+++ b/frontend/src/navigation/SectionPills.tsx
@@ -15,9 +15,10 @@ import { useSectionContext } from './useSectionContext';
  *
  * Sections whose destinations are separate pages (settings, admin) use
  * `SectionIndexPage` instead. This is for sections whose destinations are
- * views of the page you are already on — the agent list's filters, an
- * agent's own pages — where bouncing out to a menu to switch would be worse
- * than a row of pills.
+ * views of the page you are already on — the agent list's filters — where
+ * bouncing out to a menu to switch would be worse than a row of pills. An
+ * agent's own pages don't use it: the sidebar and the agent tile's menu
+ * already move between them.
  */
 export default function SectionPills({ className }: { className?: string }) {
   const { t } = useTranslation();
diff --git a/frontend/src/navigation/SectionShell.test.tsx b/frontend/src/navigation/SectionShell.test.tsx
new file mode 100644
index 00000000..088fbf2c
--- /dev/null
+++ b/frontend/src/navigation/SectionShell.test.tsx
@@ -0,0 +1,41 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { MemoryRouter } from 'react-router-dom';
+
+vi.mock('react-redux', () => ({ useSelector: () => null }));
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+vi.mock('@/hooks', () => ({ useMediaQuery: () => ({ isMobile: false }) }));
+
+import SectionShell from './SectionShell';
+
+describe('SectionShell', () => {
+  it('draws a title override in place of the section title', () => {
+    const html = renderToStaticMarkup(
+      <MemoryRouter initialEntries={['/agents/manage/new']}>
+        <SectionShell title="New agent">
+          <p>body</p>
+        </SectionShell>
+      </MemoryRouter>,
+    );
+    expect(html).toMatch(/<h1[^>]*>New agent<\/h1>/);
+    expect(html).toContain('body');
+  });
+
+  // A page-level menu (the agent Overview's ⋯) sits at the title row's end.
+  it('puts a title action at the end of the title row', () => {
+    const html = renderToStaticMarkup(
+      <MemoryRouter initialEntries={['/agents/manage/new']}>
+        <SectionShell
+          title="Overview"
+          titleAction={<button type="button">menu</button>}
+        >
+          <p>body</p>
+        </SectionShell>
+      </MemoryRouter>,
+    );
+    expect(html).toMatch(
+      /<div class="flex items-center justify-between gap-3"><h1[^>]*>Overview<\/h1><button type="button">menu<\/button><\/div>/,
+    );
+  });
+});
diff --git a/frontend/src/navigation/SectionShell.tsx b/frontend/src/navigation/SectionShell.tsx
index e023f6f6..64422986 100644
--- a/frontend/src/navigation/SectionShell.tsx
+++ b/frontend/src/navigation/SectionShell.tsx
@@ -3,7 +3,6 @@ import type { ReactNode } from 'react';
 import { cn } from '@/lib/utils';
 
 import { CurrentSectionHeader } from './SectionPageHeader';
-import SectionPills from './SectionPills';
 
 const WIDTH_CLASSES = {
   default: 'max-w-6xl',
@@ -14,19 +13,23 @@ const WIDTH_CLASSES = {
 
 /**
  * The frame of every section page (settings, admin, agents, teams): the
- * scroll container, the centred column, the section title and, with `pills`,
- * the phone/tablet destination pills. Content starts 32px under the title.
+ * scroll container, the centred column and the section title. Content starts
+ * 32px under the title.
  */
 export default function SectionShell({
   width = 'default',
-  pills = false,
   header = true,
+  title,
+  titleAction,
   children,
 }: {
   width?: keyof typeof WIDTH_CLASSES;
-  pills?: boolean;
   /** False for the phone section index, which draws its own title. */
   header?: boolean;
+  /** Replaces the section's own title (the new-agent form, which has no nav item). */
+  title?: ReactNode;
+  /** A page-level control at the title row's end (the agent Overview's ⋯). */
+  titleAction?: ReactNode;
   children: ReactNode;
 }) {
   return (
@@ -34,8 +37,7 @@ export default function SectionShell({
       <div className={cn('mx-auto w-full', WIDTH_CLASSES[width])}>
         {header ? (
           <>
-            <CurrentSectionHeader />
-            {pills ? <SectionPills className="mt-4" /> : null}
+            <CurrentSectionHeader title={title} titleAction={titleAction} />
             <div className="mt-8">{children}</div>
           </>
         ) : (
diff --git a/frontend/src/settings/Prompts.test.tsx b/frontend/src/settings/Prompts.test.tsx
index 276d589d..39c2fcef 100644
--- a/frontend/src/settings/Prompts.test.tsx
+++ b/frontend/src/settings/Prompts.test.tsx
@@ -124,6 +124,27 @@ describe('Prompts', () => {
     ).toBe('Prompt');
   });
 
+  it('labels the picker with a floating FormField label with titleAs="field"', () => {
+    renderPrompts({
+      titleAs: 'field',
+      title: 'Prompt',
+      labelSurface: 'background',
+      showAddButton: false,
+    });
+    expect(container.querySelector('[data-slot="section-header"]')).toBeNull();
+    const label = container.querySelector<HTMLLabelElement>(
+      '[data-slot="form-field-label"]',
+    )!;
+    expect(label.textContent).toBe('Prompt');
+    expect(label.className).toContain('bg-background');
+    const trigger = container.querySelector<HTMLButtonElement>(
+      'button[role="combobox"]',
+    )!;
+    expect(label.htmlFor).toBe(trigger.id);
+    expect(trigger.hasAttribute('aria-label')).toBe(false);
+    expect(trigger.className).toContain('w-full');
+  });
+
   it('makes Add a neutral outline pill sized to the field row', () => {
     renderPrompts();
     const add = Array.from(
diff --git a/frontend/src/settings/Prompts.tsx b/frontend/src/settings/Prompts.tsx
index 40039d43..5601111b 100644
--- a/frontend/src/settings/Prompts.tsx
+++ b/frontend/src/settings/Prompts.tsx
@@ -12,6 +12,7 @@ import {
   CommandList,
 } from '../components/ui/command';
 import { Button } from '../components/ui/button';
+import { FormField } from '../components/ui/form-field';
 import { IconButton } from '../components/ui/icon-button';
 import {
   Popover,
@@ -35,9 +36,13 @@ type ExtendedPromptProps = PromptProps & {
   title?: string;
   /**
    * `row` (Settings → General): a SettingRow whose label names the picker.
-   * `heading` (the agent form): the title is a section heading above it.
+   * `heading`: the title is a section heading above it.
+   * `field` (the agent form): the title is the picker's floating FormField
+   * label, like the fields around it.
    */
-  titleAs?: 'row' | 'heading';
+  titleAs?: 'row' | 'heading' | 'field';
+  /** The surface behind a `field` picker, for its label's notch. */
+  labelSurface?: 'card' | 'background' | 'muted';
   /** The row's muted description, for `titleAs="row"`. */
   description?: string;
   dropdownProps?: PromptsDropdownProps;
@@ -54,6 +59,7 @@ export default function Prompts({
   description,
   dropdownProps = {},
   showAddButton = true,
+  labelSurface = 'card',
 }: ExtendedPromptProps) {
   const token = useSelector(selectToken);
   const { t } = useTranslation();
@@ -448,6 +454,21 @@ export default function Prompts({
             {addButton}
           </div>
         </SettingRow>
+      ) : titleAs === 'field' ? (
+        <div className="flex items-center gap-2">
+          <div className="flex min-w-0 flex-1 items-center gap-1">
+            <FormField
+              id={pickerId}
+              label={titleText}
+              labelSurface={labelSurface}
+              className="min-w-0 flex-1"
+            >
+              {picker}
+            </FormField>
+            {editButton}
+          </div>
+          {addButton}
+        </div>
       ) : (
         <div className="flex flex-col gap-3">
           <SectionHeader as="h2" title={titleText} />
diff --git a/frontend/src/settings/RemoteDeviceConfig.tsx b/frontend/src/settings/RemoteDeviceConfig.tsx
index 1f844e4c..b3c1cf58 100644
--- a/frontend/src/settings/RemoteDeviceConfig.tsx
+++ b/frontend/src/settings/RemoteDeviceConfig.tsx
@@ -336,7 +336,7 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
           </DescriptionItem>
           <DescriptionItem label={t('settings.devices.deviceIdLabel')}>
             <div className="flex flex-wrap items-center gap-2">
-              <code className="text-foreground bg-muted max-w-full truncate rounded px-2 py-0.5 font-mono text-xs">
+              <code className="text-foreground bg-muted max-w-full truncate rounded-md px-2 py-0.5 font-mono text-xs">
                 {deviceId || '-'}
               </code>
               {deviceId && <CopyButton textToCopy={deviceId} />}
diff --git a/frontend/src/settings/Sources.tsx b/frontend/src/settings/Sources.tsx
index 38aa5297..f870c075 100644
--- a/frontend/src/settings/Sources.tsx
+++ b/frontend/src/settings/Sources.tsx
@@ -598,7 +598,6 @@ export default function Sources({
               type="button"
               size="field"
               shape="pill"
-              title={t('settings.sources.addSource')}
               onClick={() => {
                 setIsOnboarding(false);
                 setModalState('ACTIVE');
diff --git a/frontend/src/settings/ToolConfig.test.tsx b/frontend/src/settings/ToolConfig.test.tsx
index d38cf092..7950c13d 100644
--- a/frontend/src/settings/ToolConfig.test.tsx
+++ b/frontend/src/settings/ToolConfig.test.tsx
@@ -351,7 +351,7 @@ describe('ToolConfig', () => {
     });
   });
 
-  it('renders the API property tables from the ui/table parts with 50px delete columns', async () => {
+  it('renders the API property tables from the ui/table parts with 40px delete columns', async () => {
     await render(apiTool);
     await act(async () => {
       (
@@ -373,7 +373,7 @@ describe('ToolConfig', () => {
       .querySelector('table button[data-variant="ghost-destructive"]')
       ?.closest('td');
     expect(deleteCell?.dataset.slot).toBe('table-cell');
-    expect(deleteCell?.style.getPropertyValue('--cell-width')).toBe('50px');
+    expect(deleteCell?.style.getPropertyValue('--cell-width')).toBe('40px');
     expect(deleteCell?.className).toContain('text-center');
     expect(deleteCell?.className).not.toMatch(/p-0|!/);
   });
diff --git a/frontend/src/settings/ToolConfig.tsx b/frontend/src/settings/ToolConfig.tsx
index cc66f616..65e7f9d9 100644
--- a/frontend/src/settings/ToolConfig.tsx
+++ b/frontend/src/settings/ToolConfig.tsx
@@ -1548,7 +1548,7 @@ function APIActionTable({
                   size="sm"
                 />
               </TableCell>
-              <TableCell width="50px" align="center">
+              <TableCell width="40px" align="center">
                 <IconButton
                   label={t('convTile.delete')}
                   icon={Trash2}
@@ -1613,7 +1613,7 @@ function APIActionTable({
                 {t('settings.tools.cancel')}
               </Button>
             </TableCell>
-            <TableCell width="50px" align="center"></TableCell>
+            <TableCell width="40px" align="center"></TableCell>
           </TableRow>
         ) : (
           <TableRow>
@@ -1628,7 +1628,7 @@ function APIActionTable({
                 {t('settings.tools.addNew')}
               </Button>
             </TableCell>
-            <TableCell width="50px" align="center"></TableCell>
+            <TableCell width="40px" align="center"></TableCell>
           </TableRow>
         )}
       </>
@@ -1715,7 +1715,7 @@ function APIActionTable({
                   }
                 />
               </TableCell>
-              <TableCell width="50px" align="center">
+              <TableCell width="40px" align="center">
                 <IconButton
                   label={t('convTile.delete')}
                   icon={Trash2}
@@ -1764,7 +1764,7 @@ function APIActionTable({
                 {t('settings.tools.cancel')}
               </Button>
             </TableCell>
-            <TableCell width="50px" align="center"></TableCell>
+            <TableCell width="40px" align="center"></TableCell>
           </TableRow>
         ) : (
           <TableRow>
@@ -1779,7 +1779,7 @@ function APIActionTable({
                 {t('settings.tools.addNew')}
               </Button>
             </TableCell>
-            <TableCell width="50px" align="center"></TableCell>
+            <TableCell width="40px" align="center"></TableCell>
           </TableRow>
         )}
       </>
@@ -1797,7 +1797,7 @@ function APIActionTable({
                 <TableHeader>{t('settings.tools.name')}</TableHeader>
                 <TableHeader>{t('settings.tools.value')}</TableHeader>
                 <TableHeader>{t('settings.tools.description')}</TableHeader>
-                <TableHeader width="50px" align="center"></TableHeader>
+                <TableHeader width="40px" align="center"></TableHeader>
               </TableRow>
             </TableHead>
             <TableBody>{renderHeadersTable()}</TableBody>
@@ -1819,7 +1819,7 @@ function APIActionTable({
                 <TableHeader>{t('settings.tools.filledByLLM')}</TableHeader>
                 <TableHeader>{t('settings.tools.description')}</TableHeader>
                 <TableHeader>{t('settings.tools.value')}</TableHeader>
-                <TableHeader width="50px" align="center"></TableHeader>
+                <TableHeader width="40px" align="center"></TableHeader>
               </TableRow>
             </TableHead>
             <TableBody>{renderPropertiesTable('query_params')}</TableBody>
@@ -1837,7 +1837,7 @@ function APIActionTable({
                 <TableHeader>{t('settings.tools.filledByLLM')}</TableHeader>
                 <TableHeader>{t('settings.tools.description')}</TableHeader>
                 <TableHeader>{t('settings.tools.value')}</TableHeader>
-                <TableHeader width="50px" align="center"></TableHeader>
+                <TableHeader width="40px" align="center"></TableHeader>
               </TableRow>
             </TableHead>
             <TableBody>{renderPropertiesTable('body')}</TableBody>
diff --git a/frontend/src/settings/traces/TraceSheet.tsx b/frontend/src/settings/traces/TraceSheet.tsx
index 9ca67214..d2d7a6ec 100644
--- a/frontend/src/settings/traces/TraceSheet.tsx
+++ b/frontend/src/settings/traces/TraceSheet.tsx
@@ -84,7 +84,8 @@ export default function TraceSheet({
         side="right"
         title={t('settings.logs.trace.title')}
         aria-describedby={undefined}
-        className="w-full overflow-y-auto sm:max-w-3xl"
+        size="wide"
+        className="overflow-y-auto"
       >
         <div className="flex flex-col gap-6 px-4 pt-4 pb-6">
           {loading && <LoadingState fill="block" />}
diff --git a/frontend/src/upload/Upload.test.tsx b/frontend/src/upload/Upload.test.tsx
index f7ff6c36..dbe5daf3 100644
--- a/frontend/src/upload/Upload.test.tsx
+++ b/frontend/src/upload/Upload.test.tsx
@@ -99,3 +99,131 @@ describe('Upload source-type tiles', () => {
     expect(train!.className).toContain('bg-primary');
   });
 });
+
+function makeFile(name: string, type: string, bytes = 10): File {
+  return new File([new Uint8Array(bytes)], name, { type });
+}
+
+describe('Upload local file step', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const openLocalFile = async () => {
+    await act(async () => {
+      root.render(
+        <Upload
+          receivedFile={[]}
+          setModalState={vi.fn()}
+          isOnboarding={false}
+          renderTab={null}
+          close={vi.fn()}
+        />,
+      );
+    });
+    const tile = Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="option-card"]',
+      ),
+    ).find((el) =>
+      el.textContent?.includes('modals.uploadDoc.ingestors.local_file.label'),
+    )!;
+    await act(async () => tile.click());
+  };
+
+  const pick = async (files: File[]) => {
+    const input = document.body.querySelector(
+      '[data-slot="dropzone"] input[type="file"]',
+    );
+    if (!input) throw new Error('no dropzone input');
+    Object.defineProperty(input, 'files', { value: files, configurable: true });
+    await act(async () => {
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+    });
+    // react-dropzone resolves the selected files asynchronously.
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  };
+
+  it('renders the file field as a default-size Dropzone', async () => {
+    await openLocalFile();
+    const zone = document.body.querySelector('[data-slot="dropzone"]');
+    expect(zone).not.toBeNull();
+    expect(zone!.getAttribute('data-size')).toBe('default');
+    expect(zone!.textContent).toContain('modals.uploadDoc.dropzoneText');
+    expect(zone!.textContent).toContain('modals.uploadDoc.dropzoneHint');
+    expect(document.body.textContent).not.toContain('modals.uploadDoc.choose');
+    expect(document.body.textContent).not.toContain(
+      'modals.uploadDoc.selectedFiles',
+    );
+    // No list until something is picked.
+    expect(document.body.querySelector('[data-slot="list-rows"]')).toBeNull();
+  });
+
+  it('lists picked files as rows with their size and fills the name', async () => {
+    await openLocalFile();
+    await pick([
+      makeFile('rates.pdf', 'application/pdf', 2048),
+      makeFile('notes.md', 'text/x-markdown', 10),
+    ]);
+    const rows = Array.from(
+      document.body.querySelectorAll('[data-slot="list-row"]'),
+    );
+    expect(rows).toHaveLength(2);
+    expect(rows[0].textContent).toContain('rates.pdf');
+    expect(rows[0].textContent).toContain('2 KB');
+    expect(rows[1].textContent).toContain('notes.md');
+    const card = rows[0].closest('[data-slot="card"]');
+    expect(card).not.toBeNull();
+    expect(card!.getAttribute('data-variant')).toBe('outline');
+    const textInputs = Array.from(
+      document.body.querySelectorAll<HTMLInputElement>('input[type="text"]'),
+    );
+    expect(textInputs.some((el) => el.value === 'rates.pdf')).toBe(true);
+    const train = Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>('button'),
+    ).find((b) => b.textContent === 'modals.uploadDoc.train');
+    expect(train!.disabled).toBe(false);
+  });
+
+  it('replaces the selection on a new drop', async () => {
+    await openLocalFile();
+    await pick([makeFile('a.pdf', 'application/pdf')]);
+    await pick([makeFile('b.pdf', 'application/pdf')]);
+    const rows = document.body.querySelectorAll('[data-slot="list-row"]');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].textContent).toContain('b.pdf');
+  });
+
+  it('reports files that are too large or of an unsupported type', async () => {
+    await openLocalFile();
+    const big = makeFile('huge.pdf', 'application/pdf');
+    Object.defineProperty(big, 'size', { value: 26_000_000 });
+    await pick([
+      big,
+      makeFile('setup.exe', 'application/x-msdownload'),
+      makeFile('ok.pdf', 'application/pdf'),
+    ]);
+    const rows = document.body.querySelectorAll('[data-slot="list-row"]');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].textContent).toContain('ok.pdf');
+    const zone = document.body.querySelector('[data-slot="dropzone"]')!;
+    expect(zone.parentElement!.querySelector('p')?.textContent).toBe(
+      'modals.uploadDoc.filesRejected',
+    );
+    // A clean drop clears the message.
+    await pick([makeFile('next.pdf', 'application/pdf')]);
+    expect(zone.parentElement!.querySelector('p')).toBeNull();
+  });
+});
diff --git a/frontend/src/upload/Upload.tsx b/frontend/src/upload/Upload.tsx
index 257032c5..1ebbcf5d 100644
--- a/frontend/src/upload/Upload.tsx
+++ b/frontend/src/upload/Upload.tsx
@@ -1,9 +1,9 @@
-import { ChevronLeft } from 'lucide-react';
+import { ChevronLeft, FileText } from 'lucide-react';
 import { envVar } from '@/env';
 import { cn } from '@/lib/utils';
 import { useCallback, useEffect, useState } from 'react';
 import { nanoid } from '@reduxjs/toolkit';
-import { useDropzone } from 'react-dropzone';
+import type { FileRejection } from 'react-dropzone';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector, useStore } from 'react-redux';
 
@@ -28,6 +28,10 @@ import { Textarea } from '../components/ui/textarea';
 import { Modal } from '../components/ui/modal';
 import { Separator } from '../components/ui/separator';
 import { OptionCard } from '../components/ui/option-card';
+import { Card } from '../components/ui/card';
+import { Dropzone } from '../components/ui/dropzone';
+import { ListRow, ListRows } from '../components/ui/list-row';
+import { formatBytes } from '../components/artifactViewUtils';
 import { ActiveState, Doc } from '../models/misc';
 
 import { getDocs } from '../preferences/preferenceApi';
@@ -57,6 +61,9 @@ import RetrievalOptions, {
   type RetrievalOptionsValue,
 } from '../settings/components/RetrievalOptions';
 
+/** Per-file limit for local uploads (25 MB), enforced by the dropzone. */
+const MAX_UPLOAD_BYTES = 25000000;
+
 function Upload({
   receivedFile = [],
   setModalState,
@@ -84,6 +91,9 @@ function Upload({
   const selectedDocs = useSelector(selectSelectedDocs);
 
   const [files, setfiles] = useState<File[]>(receivedFile);
+  // Names of the files the last drop turned away (over the size limit or of
+  // an unaccepted type), shown under the dropzone.
+  const [rejectedFiles, setRejectedFiles] = useState<string[]>([]);
   const [activeTab, setActiveTab] = useState<boolean>(true);
   const [showAdvancedOptions, setShowAdvancedOptions] = useState(false);
   const [retrievalOptions, setRetrievalOptions] =
@@ -293,34 +303,45 @@ function Upload({
         );
       case 'local_file_picker':
         return (
-          <div key={field.name}>
-            <div className="mb-3" {...getRootProps()}>
-              <span className="text-primary dark:text-muted-foreground border-border inline-block rounded-3xl border bg-transparent px-4 py-2 font-medium hover:cursor-pointer">
-                <input type="button" {...getInputProps()} />
-                {t('modals.uploadDoc.choose')}
-              </span>
-            </div>
-            <div className="mt-4 max-w-full">
-              <p className="text-foreground mb-3.5 text-sm font-medium">
-                {t('modals.uploadDoc.selectedFiles')}
-              </p>
-              <div className="max-w-full overflow-hidden">
-                {files.map((file) => (
-                  <p
-                    key={file.name}
-                    className="text-muted-foreground truncate"
-                    title={file.name}
-                  >
-                    {file.name}
-                  </p>
-                ))}
-                {files.length === 0 && (
-                  <p className="text-muted-foreground text-sm">
-                    {t('modals.uploadDoc.noFilesSelected')}
-                  </p>
-                )}
-              </div>
-            </div>
+          <div key={field.name} className="flex flex-col gap-3">
+            <Dropzone
+              onDrop={onDrop}
+              multiple
+              accept={FILE_UPLOAD_ACCEPT}
+              maxSize={MAX_UPLOAD_BYTES}
+              title={t('modals.uploadDoc.dropzoneText')}
+              description={t('modals.uploadDoc.dropzoneHint')}
+              error={
+                rejectedFiles.length > 0
+                  ? t('modals.uploadDoc.filesRejected', {
+                      files: rejectedFiles.join(', '),
+                      // React escapes the text; i18next must not do it twice.
+                      interpolation: { escapeValue: false },
+                    })
+                  : undefined
+              }
+            />
+            {files.length > 0 && (
+              <Card variant="outline" padding="none">
+                <ListRows>
+                  {files.map((file) => (
+                    <ListRow
+                      key={`${file.name}-${file.size}-${file.lastModified}`}
+                      leading={
+                        <span
+                          aria-hidden="true"
+                          className="bg-muted text-muted-foreground flex size-8 shrink-0 items-center justify-center rounded-md"
+                        >
+                          <FileText className="size-4" />
+                        </span>
+                      }
+                      title={<span title={file.name}>{file.name}</span>}
+                      description={formatBytes(file.size)}
+                    />
+                  ))}
+                </ListRows>
+              </Card>
+            )}
           </div>
         );
       case 'remote_file_picker':
@@ -417,6 +438,7 @@ function Upload({
   const resetUploaderState = useCallback(() => {
     setIngestor({ type: null, name: '', config: {} });
     setfiles([]);
+    setRejectedFiles([]);
     setSelectedFiles([]);
     setSelectedFolders([]);
     setShowAdvancedOptions(false);
@@ -580,8 +602,9 @@ function Upload({
   );
 
   const onDrop = useCallback(
-    (acceptedFiles: File[]) => {
+    (acceptedFiles: File[], rejections: FileRejection[] = []) => {
       setfiles(acceptedFiles);
+      setRejectedFiles(rejections.map((rejection) => rejection.file.name));
       const pickedName = acceptedFiles[0]?.name;
       if (!nameTouched && pickedName) {
         setIngestor((prev) => ({ ...prev, name: pickedName }));
@@ -601,8 +624,6 @@ function Upload({
     [ingestor.type, nameTouched],
   );
 
-  const doNothing = () => undefined;
-
   const uploadFile = (clientTaskId: string) => {
     const formData = new FormData();
     files.forEach((file) => {
@@ -902,16 +923,6 @@ function Upload({
     handleClose();
   };
 
-  const { getRootProps, getInputProps } = useDropzone({
-    onDrop,
-    multiple: true,
-    onDragEnter: doNothing,
-    onDragOver: doNothing,
-    onDragLeave: doNothing,
-    maxSize: 25000000,
-    accept: FILE_UPLOAD_ACCEPT,
-  });
-
   const isUploadDisabled = (): boolean => {
     if (!activeTab) return true;
 
@@ -1008,6 +1019,7 @@ function Upload({
         config: {},
       });
       setfiles([]);
+      setRejectedFiles([]);
       setNameTouched(false);
       return;
     }
@@ -1023,6 +1035,7 @@ function Upload({
     // Clear files if switching away from local_file
     if (type !== 'local_file') {
       setfiles([]);
+      setRejectedFiles([]);
     }
   };
 
diff --git a/frontend/src/utils/dateTimeUtils.test.ts b/frontend/src/utils/dateTimeUtils.test.ts
index 89eaa8c4..c72a7c80 100644
--- a/frontend/src/utils/dateTimeUtils.test.ts
+++ b/frontend/src/utils/dateTimeUtils.test.ts
@@ -52,6 +52,23 @@ describe('formatRelative', () => {
     expect(formatRelative('garbage', { now: NOW })).toBeNull();
   });
 
+  it('words a future time as "in …" when asked (the next scheduled run)', async () => {
+    const { formatRelative } = await import('./dateTimeUtils');
+    const ahead = (ms: number) => new Date(NOW + ms).toISOString();
+    const opts = { now: NOW, locale: 'en', future: true };
+    expect(formatRelative(ahead(18 * 3_600_000), opts)).toBe('in 18 hours');
+    // Clock skew under a minute still reads "now".
+    expect(formatRelative(ahead(20_000), opts)).toBe('now');
+  });
+
+  it('clamps a future time to "now" by default (server clock skew)', async () => {
+    const { formatRelative } = await import('./dateTimeUtils');
+    const ahead = (ms: number) => new Date(NOW + ms).toISOString();
+    expect(formatRelative(ahead(3 * 60_000), { now: NOW, locale: 'en' })).toBe(
+      'now',
+    );
+  });
+
   it('words the gap with Intl in the given language', async () => {
     const { formatRelative } = await import('./dateTimeUtils');
     expect(formatRelative(ago(20_000), { now: NOW, locale: 'en' })).toBe('now');
diff --git a/frontend/src/utils/dateTimeUtils.ts b/frontend/src/utils/dateTimeUtils.ts
index d0f5a334..fb42e1ab 100644
--- a/frontend/src/utils/dateTimeUtils.ts
+++ b/frontend/src/utils/dateTimeUtils.ts
@@ -92,26 +92,36 @@ const RELATIVE_UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
 ];
 
 /**
- * "3 minutes ago", "yesterday", "now" in the UI language.
+ * "3 minutes ago", "yesterday", "now", "in 18 hours" in the UI language.
  *
  * Args:
  *   value: an ISO timestamp.
  *   options.now: the reference time (tests).
  *   options.locale: an app language code; defaults to the current one.
  *   options.dateAfterDays: past this many days, show the date instead.
+ *   options.future: word future times as "in …"; otherwise they read "now"
+ *     (a past-event field under server clock skew).
  *
  * Returns:
  *   The phrase, or null when the value is empty or unparseable.
  */
 export function formatRelative(
   value: string | null | undefined,
-  options: { now?: number; locale?: string; dateAfterDays?: number } = {},
+  options: {
+    now?: number;
+    locale?: string;
+    dateAfterDays?: number;
+    future?: boolean;
+  } = {},
 ): string | null {
   if (!value) return null;
   const then = Date.parse(value);
   if (Number.isNaN(then)) return null;
-  const { now = Date.now(), locale, dateAfterDays } = options;
-  const diffMs = Math.max(0, now - then);
+  const { now = Date.now(), locale, dateAfterDays, future = false } = options;
+  // Past times read "… ago"; future ones "in …" only when the caller expects
+  // them (a schedule's next run), else they clamp to "now".
+  const sign = then > now ? 1 : -1;
+  const diffMs = future ? Math.abs(now - then) : Math.max(0, now - then);
   if (dateAfterDays !== undefined && diffMs > dateAfterDays * 86_400_000) {
     return formatDateOnly(value);
   }
@@ -119,7 +129,8 @@ export function formatRelative(
     numeric: 'auto',
   });
   for (const [unit, ms] of RELATIVE_UNITS) {
-    if (diffMs >= ms) return formatter.format(-Math.round(diffMs / ms), unit);
+    if (diffMs >= ms)
+      return formatter.format(sign * Math.round(diffMs / ms), unit);
   }
   return formatter.format(0, 'second');
 }
diff --git a/tests/api/user/test_schedules_routes.py b/tests/api/user/test_schedules_routes.py
index 3948e1d3..7baf5256 100644
--- a/tests/api/user/test_schedules_routes.py
+++ b/tests/api/user/test_schedules_routes.py
@@ -506,3 +506,136 @@ class TestUnexpectedExceptionMasked:
         assert body["message"] == "internal error"
         # Defensive: the internal-sounding detail must not leak through.
         assert "secret connection string" not in resp.get_data(as_text=True)
+
+
+class TestAgentScheduleStats:
+    def _get(self, app, pg_conn, agent_id: str, *, user="u1", query=""):
+        from docsgpt.api.user.schedules.routes import AgentScheduleStats
+
+        with _patch_db(pg_conn), app.test_request_context(
+            f"/api/agents/{agent_id}/schedules/stats{query}", method="GET",
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user} if user else None
+            return AgentScheduleStats().get(agent_id)
+
+    def _run(self, conn, schedule_id, user_id, agent_id, *, ago, **fields):
+        from docsgpt.storage.db.repositories.schedule_runs import (
+            ScheduleRunsRepository,
+        )
+
+        repo = ScheduleRunsRepository(conn)
+        run = repo.record_pending(schedule_id, user_id, agent_id, _now() - ago)
+        return repo.update(str(run["id"]), fields)
+
+    def test_unauthorized(self, app):
+        resp = self._get(app, None, "x", user=None)
+        assert resp.status_code == 401
+
+    def test_agent_not_found(self, app, pg_conn):
+        resp = self._get(
+            app, pg_conn, "00000000-0000-0000-0000-000000000000",
+        )
+        assert resp.status_code == 404
+        assert resp.get_json()["message"] == "agent not found"
+
+    def test_other_users_agent_not_found(self, app, pg_conn):
+        agent_id = _make_agent(pg_conn, user_id="u2")
+        resp = self._get(app, pg_conn, agent_id)
+        assert resp.status_code == 404
+
+    def test_empty_window(self, app, pg_conn):
+        agent_id = _make_agent(pg_conn)
+        resp = self._get(app, pg_conn, agent_id)
+        assert resp.status_code == 200
+        assert resp.get_json() == {
+            "days": 30, "runs": 0, "failed": 0, "tokens": 0,
+            "latest_failure": None,
+        }
+
+    def test_counts_and_latest_failure(self, app, pg_conn):
+        agent_id = _make_agent(pg_conn)
+        s = SchedulesRepository(pg_conn).create(
+            user_id="u1", agent_id=agent_id, trigger_type="recurring",
+            instruction="i", cron="* * * * *",
+            next_run_at=_now() + timedelta(hours=1),
+        )
+        sid = str(s["id"])
+        self._run(
+            pg_conn, sid, "u1", agent_id, ago=timedelta(days=1),
+            status="success", prompt_tokens=100, generated_tokens=50,
+        )
+        self._run(
+            pg_conn, sid, "u1", agent_id, ago=timedelta(days=5),
+            status="failed", prompt_tokens=10, generated_tokens=5,
+            error_type="agent_error",
+        )
+        latest = self._run(
+            pg_conn, sid, "u1", agent_id, ago=timedelta(days=2),
+            status="timeout", prompt_tokens=1, generated_tokens=2,
+            error_type="timeout",
+        )
+        self._run(
+            pg_conn, sid, "u1", agent_id, ago=timedelta(days=45),
+            status="failed", prompt_tokens=999, generated_tokens=999,
+        )
+        other = SchedulesRepository(pg_conn).create(
+            user_id="u2", agent_id=agent_id, trigger_type="recurring",
+            instruction="i", cron="* * * * *",
+            next_run_at=_now() + timedelta(hours=1),
+        )
+        self._run(
+            pg_conn, str(other["id"]), "u2", agent_id, ago=timedelta(hours=1),
+            status="failed", prompt_tokens=7, generated_tokens=7,
+        )
+
+        resp = self._get(app, pg_conn, agent_id)
+        assert resp.status_code == 200
+        body = resp.get_json()
+        assert body["days"] == 30
+        assert body["runs"] == 3
+        assert body["failed"] == 2
+        assert body["tokens"] == 168
+        assert body["latest_failure"] == {
+            "scheduled_for": latest["scheduled_for"],
+            "status": "timeout",
+            "error_type": "timeout",
+        }
+
+    @pytest.mark.parametrize(
+        "query, expected",
+        [("?days=0", 1), ("?days=-5", 1), ("?days=9999", 365),
+         ("?days=7", 7), ("?days=abc", 30), ("", 30)],
+    )
+    def test_days_clamped(self, app, pg_conn, query, expected):
+        agent_id = _make_agent(pg_conn)
+        resp = self._get(app, pg_conn, agent_id, query=query)
+        assert resp.status_code == 200
+        assert resp.get_json()["days"] == expected
+
+    def test_db_error_returns_500(self, app, pg_conn):
+        from docsgpt.storage.db.repositories.schedule_runs import (
+            ScheduleRunsRepository,
+        )
+
+        agent_id = _make_agent(pg_conn)
+        with patch.object(
+            ScheduleRunsRepository, "stats_for_agent",
+            side_effect=RuntimeError("secret detail"), create=True,
+        ):
+            resp = self._get(app, pg_conn, agent_id)
+        assert resp.status_code == 500
+        assert "secret detail" not in resp.get_data(as_text=True)
+
+    def test_route_registered_without_collision(self):
+        from docsgpt.api.user.schedules.routes import (
+            AgentScheduleStats,
+            schedules_ns,
+        )
+
+        paths = {
+            r.urls[0]: r.resource for r in schedules_ns.resources
+        }
+        assert paths["/agents/<string:agent_id>/schedules/stats"] is (
+            AgentScheduleStats
+        )
diff --git a/tests/storage/db/repositories/test_schedule_runs.py b/tests/storage/db/repositories/test_schedule_runs.py
index d6e72763..3cb58966 100644
--- a/tests/storage/db/repositories/test_schedule_runs.py
+++ b/tests/storage/db/repositories/test_schedule_runs.py
@@ -196,3 +196,90 @@ class TestCleanup:
         )
         deleted = repo.cleanup_older_than(90, keep_recent_per_schedule=2)
         assert deleted >= 1
+
+
+def _add_run(
+    conn,
+    schedule_id: str,
+    user_id: str,
+    agent_id: str,
+    *,
+    ago: timedelta,
+    status: str,
+    prompt_tokens: int = 0,
+    generated_tokens: int = 0,
+    error_type: str | None = None,
+) -> dict:
+    repo = ScheduleRunsRepository(conn)
+    run = repo.record_pending(schedule_id, user_id, agent_id, _now() - ago)
+    return repo.update(
+        str(run["id"]),
+        {
+            "status": status,
+            "prompt_tokens": prompt_tokens,
+            "generated_tokens": generated_tokens,
+            "error_type": error_type,
+        },
+    )
+
+
+class TestStatsForAgent:
+    def test_empty_window_returns_zeros(self, pg_conn):
+        _, agent_id = _make_schedule(pg_conn)
+        stats = ScheduleRunsRepository(pg_conn).stats_for_agent(
+            agent_id, "u1", days=30,
+        )
+        assert stats == {
+            "runs": 0, "failed": 0, "tokens": 0, "latest_failure": None,
+        }
+
+    def test_aggregates_window_and_scopes_owner(self, pg_conn):
+        schedule_id, agent_id = _make_schedule(pg_conn)
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=timedelta(hours=12),
+            status="success", prompt_tokens=100, generated_tokens=50,
+        )
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=timedelta(days=3),
+            status="failed", prompt_tokens=10, generated_tokens=5,
+            error_type="agent_error",
+        )
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=timedelta(days=2),
+            status="timeout", prompt_tokens=1, generated_tokens=2,
+            error_type="timeout",
+        )
+        # Outside the window: must not count.
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=timedelta(days=40),
+            status="failed", prompt_tokens=1000, generated_tokens=1000,
+        )
+        # Another user's schedule on the same agent: must not count.
+        other = SchedulesRepository(pg_conn).create(
+            user_id="u2", agent_id=agent_id, trigger_type="recurring",
+            instruction="i", cron="* * * * *",
+            next_run_at=_now() + timedelta(minutes=5),
+        )
+        _add_run(
+            pg_conn, str(other["id"]), "u2", agent_id, ago=timedelta(hours=1),
+            status="failed", prompt_tokens=7, generated_tokens=7,
+        )
+
+        stats = ScheduleRunsRepository(pg_conn).stats_for_agent(
+            agent_id, "u1", days=30,
+        )
+        assert stats["runs"] == 3
+        assert stats["failed"] == 2
+        assert stats["tokens"] == 168
+        latest = stats["latest_failure"]
+        assert latest["status"] == "timeout"
+        assert latest["error_type"] == "timeout"
+        assert isinstance(latest["scheduled_for"], str)
+
+        # A tighter window drops the older runs.
+        narrow = ScheduleRunsRepository(pg_conn).stats_for_agent(
+            agent_id, "u1", days=1,
+        )
+        assert narrow["runs"] == 1
+        assert narrow["failed"] == 0
+        assert narrow["latest_failure"] is None

From 4070b0305307c99dc1055d8564a6837b568a890b Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Sun, 27 Sep 2026 21:31:01 +0400
Subject: [PATCH 4/7] Workflow revamp

---
 frontend/DESIGN.md                            |   98 +-
 frontend/src/agents/AgentPageHeader.test.tsx  |   48 +
 frontend/src/agents/AgentPageHeader.tsx       |  178 +-
 .../src/agents/workflow/CanvasControls.tsx    |   89 +
 .../src/agents/workflow/NodePalette.test.tsx  |   83 +
 frontend/src/agents/workflow/NodePalette.tsx  |  123 +
 .../src/agents/workflow/WorkflowBuilder.tsx   | 2114 +++--------------
 .../agents/workflow/WorkflowModelsContext.ts  |   25 +
 .../components/NodeDocumentsControl.tsx       |    4 +-
 .../workflow/components/PromptTextArea.tsx    |    7 +-
 .../components/WorkflowDetailsSheet.test.tsx  |  113 +
 .../components/WorkflowDetailsSheet.tsx       |  226 ++
 .../src/agents/workflow/nodeTones.test.ts     |   38 +
 frontend/src/agents/workflow/nodeTones.ts     |   71 +
 .../src/agents/workflow/nodes/BaseNode.tsx    |   48 +-
 .../src/agents/workflow/nodes/CodeNode.tsx    |   17 +-
 .../agents/workflow/nodes/ConditionNode.tsx   |   14 +-
 .../workflow/nodes/OutputVariableLine.tsx     |   25 +
 frontend/src/agents/workflow/nodes/index.tsx  |   51 +-
 .../workflow/panels/AgentPanel.test.tsx       |  138 ++
 .../src/agents/workflow/panels/AgentPanel.tsx |  403 ++++
 .../src/agents/workflow/panels/CodePanel.tsx  |  152 ++
 .../workflow/panels/ConditionPanel.test.tsx   |  107 +
 .../agents/workflow/panels/ConditionPanel.tsx |  291 +++
 .../agents/workflow/panels/NodePanel.test.tsx |  123 +
 .../src/agents/workflow/panels/NodePanel.tsx  |  151 ++
 .../src/agents/workflow/panels/NotePanel.tsx  |   31 +
 .../workflow/panels/StatePanel.test.tsx       |   92 +
 .../src/agents/workflow/panels/StatePanel.tsx |  132 +
 frontend/src/agents/workflow/panels/types.ts  |   12 +
 .../agents/workflow/workflowHelpers.test.ts   |   39 +
 .../src/agents/workflow/workflowHelpers.ts    |  204 ++
 frontend/src/components/FileUpload.tsx        |    4 +
 frontend/src/components/ui/dropzone.test.tsx  |   12 +
 frontend/src/components/ui/dropzone.tsx       |   27 +-
 frontend/src/design/DesignSystem.tsx          |   12 +
 frontend/src/locale/de.json                   |   38 +-
 frontend/src/locale/en.json                   |   39 +-
 frontend/src/locale/es.json                   |   38 +-
 frontend/src/locale/jp.json                   |   38 +-
 frontend/src/locale/ru.json                   |   38 +-
 frontend/src/locale/zh-TW.json                |   38 +-
 frontend/src/locale/zh.json                   |   38 +-
 43 files changed, 3559 insertions(+), 2010 deletions(-)
 create mode 100644 frontend/src/agents/workflow/CanvasControls.tsx
 create mode 100644 frontend/src/agents/workflow/NodePalette.test.tsx
 create mode 100644 frontend/src/agents/workflow/NodePalette.tsx
 create mode 100644 frontend/src/agents/workflow/WorkflowModelsContext.ts
 create mode 100644 frontend/src/agents/workflow/components/WorkflowDetailsSheet.test.tsx
 create mode 100644 frontend/src/agents/workflow/components/WorkflowDetailsSheet.tsx
 create mode 100644 frontend/src/agents/workflow/nodeTones.test.ts
 create mode 100644 frontend/src/agents/workflow/nodeTones.ts
 create mode 100644 frontend/src/agents/workflow/nodes/OutputVariableLine.tsx
 create mode 100644 frontend/src/agents/workflow/panels/AgentPanel.test.tsx
 create mode 100644 frontend/src/agents/workflow/panels/AgentPanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/CodePanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/ConditionPanel.test.tsx
 create mode 100644 frontend/src/agents/workflow/panels/ConditionPanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/NodePanel.test.tsx
 create mode 100644 frontend/src/agents/workflow/panels/NodePanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/NotePanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/StatePanel.test.tsx
 create mode 100644 frontend/src/agents/workflow/panels/StatePanel.tsx
 create mode 100644 frontend/src/agents/workflow/panels/types.ts
 create mode 100644 frontend/src/agents/workflow/workflowHelpers.test.ts
 create mode 100644 frontend/src/agents/workflow/workflowHelpers.ts

diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
index 289d9d97..078e4ed8 100644
--- a/frontend/DESIGN.md
+++ b/frontend/DESIGN.md
@@ -228,7 +228,8 @@ field pill`, and page-level actions go in the `ActionMenu` (`size="toolbar"`)
   row never holds more than three buttons and fits a phone, where the main
   one stretches across it (`flex-1 sm:flex-none`; `PageToolbar`'s action slot
   spans the stacked row below `sm`). The workflow builder's toolbar has no
-  title row and keeps its ⋯ at the row's end. The
+  title row and keeps its ⋯ at the row's end, holding Edit details, Access
+  details and Delete (see Workflow builder). The
   agent's Delete is in Overview's danger zone; only the workflow builder's
   toolbar has it in the ⋯ menu, as a `destructive` item. The row itself is
   `agents/components/AgentPageToolbar` (see Page chrome). A row's common
@@ -255,8 +256,9 @@ rounded-3xl`) are `variant="sidebar-item"`: left-aligned, full-radius, normal
   Padding-free tabs (a sub-nav with `gap-6`) add `size="inline"`, which keeps
   4px above the line; the row draws the 1px baseline, and `-mb-px` lays the
   underline over it. Its one use is `agents/AgentPageHeader.tsx`, the workflow
-  builder's fixed toolbar: a breadcrumb and the Overview / Logs / Schedules
-  tabs in a `<nav>`, the others `<Link>`s and the current one a `<span
+  builder's fixed toolbar: a breadcrumb, the status Badge and the Overview /
+  Logs / Schedules tabs in a `<nav>` (no tabs until the workflow has an
+  id), the others `<Link>`s and the current one a `<span
 aria-current="page">` with `data-active`. The
   agent section pages switch with the section sidebar (the phone menu below
   `lg`) and carry no pill row; the agent tile's ⋯ also opens Logs. Tabs that switch a panel in place are
@@ -556,8 +558,10 @@ controls in a row, a loading or error line in place of the field. Controls
 whose label sits beside them (Switch, Checkbox, radio) use `SettingRow` or
 an inline `Label`, not FormField. An editing surface that fills its area
 (the chat composer, the chunk and wiki editors, editing a sent question) and
-repeated rows in a list (workflow expressions) have no visible label and
-must have an `aria-label`. Never hand-build a label above a field, a
+bare repeated rows in a list have no visible label and must have an
+`aria-label`. A row box that is a small form (a workflow condition case or
+state assignment) is not a bare row: each of its fields has a floating
+label. Never hand-build a label above a field, a
 hand-positioned floating label, or a `div.flex-col` + `Label` + `<p>` stack.
 
 ### SettingRow (`ui/setting-row.tsx`)
@@ -707,7 +711,10 @@ from device, Import agent, Import API specification), `compact` (one row, a
 file field among other fields),
 `tile` (a square beside a form's fields, the agent's avatar: 64px and
 icon-only on a phone beside the Name field, 88px with a one-word title from
-`sm` beside Name and Description; no description). `FileUpload size="tile"` fills the tile
+`sm` beside Name and Description; no description). `tileSize="fixed"` keeps
+it 64px and icon-only at every width, for a tile in a narrow drawer (the
+workflow details sheet), where the breakpoint follows the window rather than
+the drawer. `FileUpload size="tile"` fills the tile
 with the picked image, or with `currentImage` (the saved one) until then.
 Props: `onDrop`, `accept`, `multiple`, `maxFiles`, `maxSize`, `disabled`,
 `title`, `description`, `icon`, `error`, `validator` (react-dropzone's
@@ -960,6 +967,74 @@ grid inside a Modal keeps its own column counts, because breakpoints follow
 the window, not the dialog.
 Skeleton mirrors follow the grid they stand in for.
 
+### Workflow builder (`agents/workflow/`)
+
+The toolbar is `AgentPageHeader` on `bg-background` with a `border-b`. Its
+current crumb is the agent's `Avatar` (circle, 20px image, the robot when
+there is none), the name (`truncate`, `max-w-[24ch]`) and a muted
+`ChevronDown` in a `ghost sm` Button, the phone top bar's title recipe; it
+opens the workflow details. The status Badge follows (`success` Published,
+`neutral` Draft until the first save), then the tabs. On the right: "Unsaved
+changes" as muted `text-sm` meta while there are any, Preview, Save, and the
+⋯ (`ActionMenu size="toolbar"`): Edit details first (the same drawer, for
+anyone who doesn't try the name), then Access details and Delete once the
+workflow is saved.
+
+The workflow details are a right `Sheet size="default"`
+(`components/WorkflowDetailsSheet.tsx`), built like AgentPreviewSheet (header,
+`Separator`, one scrolling body) with the classic Basics phone layout: a
+`subtle lg` Basics panel with `FileUpload size="tile" tileSize="fixed"` beside
+the Name pill and Description across the row, then an Advanced panel with the
+prompt-override `SettingRow`. Its footer is a `ghost lg pill` Cancel and a
+`default lg pill` Save after a `Separator`. The sheet edits a copy: Cancel,
+the X, Escape and the scrim drop the edits; Save is disabled until something
+changes, then saves the workflow and closes, or stays open with a destructive
+`Alert` listing the errors.
+
+The canvas is `bg-muted`; the node palette to its left is a `bg-background`
+rail with `border-r` (`NodePalette.tsx`), and each palette pill is a
+`<button>` that is also `draggable`: drag it onto the canvas, or click (or
+press Enter) to add the node beside the selected one, or in the middle of the
+view. Each pill's icon is a `size-8 rounded-md` tinted square, like the
+settings panel's header (the pill is round, its icon is not; the canvas
+nodes keep their `size-10` circles). Pills hover to `bg-accent` only, with
+the focus ring, and a muted `text-xs` line under the groups says so.
+
+- **One tone per node type**: `nodeTones.ts` (`NODE_TONES`, `nodeToneClass`)
+  is read by the palette, every canvas node and the settings panel's header.
+  Agent is the brand soft fill (`bg-secondary text-secondary-foreground`),
+  Start and End `success`, Note and If / Else `warning`, Set State and Code
+  `info`, each `bg-<tone>/10 text-<tone>`. End is never `destructive`.
+- **Selected node**: `border-primary ring-3 ring-ring/50`, the focus-ring
+  look, with no scale (the Note node: `border-warning ring-3
+ring-warning/50`). Node meta is translated and muted (the agent type · the
+  model's display name, from `WorkflowModelsContext`); an output variable is
+  an `ArrowRight` then the name in `font-mono`.
+- **Canvas controls**: one `bg-card border rounded-full p-1` strip at the
+  bottom left (`CanvasControls.tsx`, no shadow): Undo, Redo, a vertical
+  `Separator`, Zoom out, the zoom level, Zoom in and Fit view, each
+  `ghost-muted icon-sm pill` with a top tooltip. React Flow's own
+  `<Controls />` and attribution are not shown.
+- **Node settings** dock at the canvas's right edge (`panels/NodePanel.tsx`):
+  a `w-96 border-l bg-background` column at full height whose body is the one
+  scroller, with no shadow or `z-*`. The header holds the type's `size-8
+rounded-md` icon square, the node's title with a `neutral` type Badge (only
+  once the title differs from the type's name), the
+  id in `font-mono text-xs` with a `CopyButton`, an `ActionMenu
+size="toolbar"` (Duplicate, Delete node; none on Start) and the close
+  button. Start and End have no Title field: their body is one muted
+  `text-sm` line saying what the node does. The body is `flex flex-col gap-6
+p-4`, so its fields pass
+  `labelSurface="background"` and its row boxes (a condition case, a state
+  assignment) are `Card variant="subtle" padding="sm"`. The agent node's
+  fields are grouped by `SectionHeader size="xs" as="h3"` (Model, Prompt,
+  Knowledge, Output) with an Advanced settings `link sm` disclosure that
+  opens on its own when one of its settings is set. The column is narrow, so
+  every field stacks at full width (`flex flex-col gap-5`), Agent type and
+  Model included; no two-up grids. A row box's title is `SectionHeader
+size="xs" as="h4"`. In an If / Else case's Simple mode, the operator Select
+  and Value each carry a floating label (Operator, Value).
+
 ### Accordion (`ui/accordion.tsx`)
 
 `AccordionTrigger` carries its own inset and type (`px-4 py-3 text-sm
@@ -1205,7 +1280,8 @@ bubble) and `4xl` the answer's source cards and the landing page's model
 picker; app chrome stops at `2xl`. Skeleton bars: the default. Tinted icon squares:
 `rounded-md` at `size-7|8`, `rounded-xl` at `size-12|14`, `rounded-2xl` at
 `size-20`. `rounded-full` only for pills (`shape="pill"` controls and
-fields), avatars, status dots and the workflow palette pills.
+fields), avatars, status dots, the workflow palette pills (not their icon
+squares) and the canvas nodes' icon circles.
 
 ## Motion
 
@@ -1271,9 +1347,9 @@ shadow-lg` in both themes: the knob is white on any track, and a white knob
   `bg-input`. Accordions are
   panels and have none. Outside `ui/` the only shadows are: the workflow
   canvas nodes (`shadow-md`, `hover:shadow-lg`: a node lifts off the canvas
-  while you drag it); the workflow builder's node-settings panel and its
-  publish-error panel, which float over the canvas at popover elevation
-  (`shadow-md`, `z-20`); the chunk viewer's and file tree's search result
+  while you drag it); the workflow builder's publish-error panel, which
+  floats over the canvas at popover elevation (`shadow-md`, `z-20`); the
+  chunk viewer's and file tree's search result
   lists (`shadow-md`, in-page `z-20`, their results are `CommandItem`s inside
   the search frame); the sliding panel in `navigation/SidebarLevel.tsx`,
   which casts a horizontal shadow while it slides; and the Hero model
@@ -1320,7 +1396,7 @@ list stays reviewable.
 | `Hero.tsx`                                                          | `shadcn/no-restyle`             | The landing page's demo cards are `Button outline lg pill`, but each is a two-line pill (a title over a clamped 12px query), so it undoes lg's height, the base's one-row layout, weight and nowrap: `h-auto w-full flex-col items-start gap-0 py-3.5 text-left text-xs font-normal whitespace-normal`. One disable.                                                                                                                                                                            |
 | `Navigation.tsx`, `conversation/ConversationTile.tsx`               | `shadcn/no-restyle`             | A sidebar row whose link has sibling buttons (an agent's pin, a conversation's menu and rename Save / Cancel) keeps its fill while the pointer is on a sibling or the menu is open (`group-hover:bg-sidebar-accent`, `bg-sidebar-accent`), and `pr-10` keeps the label clear of the buttons. ConversationTile's `cn(...)` needs a `/* eslint-disable */` … `/* eslint-enable */` pair.                                                                                                          |
 | `admin/Usage.tsx`                                                   | `shadcn/no-restyle`             | The Top users id is a `link inline` Button inside a mono table cell; it keeps the cell's type and wraps (`font-mono text-xs font-normal whitespace-normal text-left`). One disable.                                                                                                                                                                                                                                                                                                             |
-| `agents/workflow/WorkflowBuilder.tsx`                               | `shadcn/no-restyle`             | The "Learn more" links in the Set state and Condition nodes' 12px hints keep the sentence's size and weight (`text-xs font-normal` on `link inline`). Two disables.                                                                                                                                                                                                                                                                                                                             |
+| `agents/workflow/panels/ConditionPanel.tsx`                         | `shadcn/no-restyle`             | The "Learn more" link in the Condition node's Advanced-mode 12px hint keeps the sentence's size and weight (`text-xs font-normal` on `link inline`). One disable; the Set state node's link sits in its `text-sm` intro and needs none.                                                                                                                                                                                                                                                         |
 | `components/MessageInput.tsx`                                       | `shadcn/no-restyle`             | The queued-send Cancel is a `link inline` inside the composer's 12px status line, so it takes the line's size (`text-xs`). One disable, beside the send button's.                                                                                                                                                                                                                                                                                                                               |
 | `settings/PersonalAccessTokens.tsx`                                 | `shadcn/no-restyle`             | Token scope chips are identifiers, so the `neutral` Badge is set in mono (`font-mono`). One disable.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `agents/workflow/WorkflowPreview.tsx`                               | `shadcn/no-restyle`             | A step's state changes (keys and values the app serialised) are `neutral` Badges set in mono (`font-mono`), like token scopes. One disable.                                                                                                                                                                                                                                                                                                                                                     |
diff --git a/frontend/src/agents/AgentPageHeader.test.tsx b/frontend/src/agents/AgentPageHeader.test.tsx
index d3604a1d..32fc5b5d 100644
--- a/frontend/src/agents/AgentPageHeader.test.tsx
+++ b/frontend/src/agents/AgentPageHeader.test.tsx
@@ -53,4 +53,52 @@ describe('AgentPageHeader sub-nav', () => {
     expect(tabs[0].tagName).toBe('A');
     expect(tabs[0].getAttribute('data-active')).not.toBe('true');
   });
+
+  it('makes the current crumb a button with the avatar and a chevron that opens the details', () => {
+    const onNameClick = vi.fn();
+    act(() => {
+      root.render(
+        <MemoryRouter>
+          <AgentPageHeader
+            agentId="a1"
+            agentName="Helpdesk Triage"
+            currentPage="overview"
+            onNameClick={onNameClick}
+            status={<span data-testid="status">Published</span>}
+          />
+        </MemoryRouter>,
+      );
+    });
+    const crumb = container.querySelector(
+      'button[aria-haspopup="dialog"]',
+    ) as HTMLButtonElement;
+    expect(crumb).not.toBeNull();
+    expect(crumb.getAttribute('data-variant')).toBe('ghost');
+    expect(crumb.getAttribute('data-size')).toBe('sm');
+    expect(crumb.querySelector('img')).not.toBeNull();
+    expect(crumb.querySelector('.lucide-chevron-down')).not.toBeNull();
+    expect(crumb.textContent).toContain('Helpdesk Triage');
+    expect(container.querySelector('[data-testid="status"]')).not.toBeNull();
+    act(() => crumb.click());
+    expect(onNameClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('hides the tabs for a workflow that has no id yet', () => {
+    act(() => {
+      root.render(
+        <MemoryRouter>
+          <AgentPageHeader
+            agentName="New workflow"
+            currentPage="overview"
+            onNameClick={vi.fn()}
+          />
+        </MemoryRouter>,
+      );
+    });
+    expect(
+      container.querySelector(
+        'nav[aria-label="agents.pageHeader.subnavAriaLabel"]',
+      ),
+    ).toBeNull();
+  });
 });
diff --git a/frontend/src/agents/AgentPageHeader.tsx b/frontend/src/agents/AgentPageHeader.tsx
index 45139091..6bc6c23f 100644
--- a/frontend/src/agents/AgentPageHeader.tsx
+++ b/frontend/src/agents/AgentPageHeader.tsx
@@ -1,4 +1,5 @@
-import { useMemo } from 'react';
+import { ChevronDown } from 'lucide-react';
+import { type ReactNode, useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Link } from 'react-router-dom';
 
@@ -10,6 +11,7 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from '@/components/ui/breadcrumb';
+import { Avatar } from '@/components/ui/avatar';
 import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 
@@ -36,14 +38,26 @@ type AgentPageHeaderProps = {
    * (e.g. the workflow builder's fixed toolbar) to avoid a double rule.
    */
   inline?: boolean;
+  /** The agent's avatar URL; the robot is drawn when it's empty. */
+  agentImage?: string;
+  /**
+   * Makes the current crumb a button (avatar, name, chevron) that opens the
+   * agent's details. Only with `currentPage="overview"`.
+   */
+  onNameClick?: () => void;
+  /** A status Badge placed after the crumbs. */
+  status?: ReactNode;
 };
 
 /**
  * The workflow builder's toolbar chrome: a Breadcrumb (`Agents > <agent
- * name> > <current page>`) and underline tab links to the agent's Overview,
- * Logs and Schedules. The builder is full-screen with no sidebar, so it needs
- * its own way between them. Section pages use `components/AgentPageToolbar`
- * and the sidebar (or `SectionPills` on a phone) instead.
+ * name> > <current page>`), an optional status Badge, and underline tab links
+ * to the agent's Overview, Logs and Schedules (hidden until the agent has an
+ * id). The builder is full-screen with no sidebar, so it needs its own way
+ * between them. With `onNameClick` the current crumb is the agent's avatar,
+ * name and a chevron in a `ghost sm` Button that opens the details, like the
+ * phone top bar's chat title. Section pages use
+ * `components/AgentPageToolbar` and the sidebar instead.
  */
 export default function AgentPageHeader({
   agentId,
@@ -52,6 +66,9 @@ export default function AgentPageHeader({
   currentPage,
   className,
   inline = false,
+  agentImage,
+  onNameClick,
+  status,
 }: AgentPageHeaderProps) {
   const { t } = useTranslation();
 
@@ -86,83 +103,116 @@ export default function AgentPageHeader({
   return (
     <div
       className={cn(
-        'flex flex-col gap-3 md:flex-row md:items-baseline md:gap-6',
+        // The builder only renders from lg, so one row.
+        'flex min-w-0 items-center gap-6',
         className,
       )}
     >
-      <Breadcrumb className="shrink-0">
-        <BreadcrumbList className="flex-nowrap">
-          <BreadcrumbItem>
-            <BreadcrumbLink asChild>
-              <Link to={AGENTS_MANAGE_ROOT}>
-                {t('agents.pageHeader.crumbs.agents')}
-              </Link>
-            </BreadcrumbLink>
-          </BreadcrumbItem>
-          <BreadcrumbSeparator />
-          <BreadcrumbItem>
-            {currentPage === 'overview' ? (
-              <BreadcrumbPage title={displayName} className="w-[16ch]">
-                {displayName}
-              </BreadcrumbPage>
-            ) : (
+      <div className="flex min-w-0 items-center gap-2">
+        <Breadcrumb className="min-w-0">
+          <BreadcrumbList className="flex-nowrap">
+            <BreadcrumbItem>
               <BreadcrumbLink asChild>
-                <Link to={editPath} className="max-w-[40ch] truncate">
-                  {displayName}
+                <Link to={AGENTS_MANAGE_ROOT}>
+                  {t('agents.pageHeader.crumbs.agents')}
                 </Link>
               </BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              {currentPage === 'overview' && onNameClick ? (
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  aria-haspopup="dialog"
+                  onClick={onNameClick}
+                  // Button is shrink-0; shrink lets a long name truncate.
+                  className="min-w-0 shrink"
+                >
+                  <Avatar
+                    src={agentImage}
+                    alt=""
+                    shape="circle"
+                    className="shrink-0 overflow-hidden"
+                    imgClassName="size-5 object-contain"
+                  />
+                  {/* The list's muted colour would reach the name; the current crumb
+                    is foreground, like BreadcrumbPage. */}
+                  <span
+                    className="text-foreground max-w-[24ch] truncate"
+                    title={displayName}
+                  >
+                    {displayName}
+                  </span>
+                  <ChevronDown className="text-muted-foreground" aria-hidden />
+                </Button>
+              ) : currentPage === 'overview' ? (
+                <BreadcrumbPage title={displayName} className="w-[16ch]">
+                  {displayName}
+                </BreadcrumbPage>
+              ) : (
+                <BreadcrumbLink asChild>
+                  <Link to={editPath} className="max-w-[40ch] truncate">
+                    {displayName}
+                  </Link>
+                </BreadcrumbLink>
+              )}
+            </BreadcrumbItem>
+            {currentPage !== 'overview' && (
+              <>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>{currentTabLabel}</BreadcrumbPage>
+                </BreadcrumbItem>
+              </>
             )}
-          </BreadcrumbItem>
-          {currentPage !== 'overview' && (
-            <>
-              <BreadcrumbSeparator />
-              <BreadcrumbItem>
-                <BreadcrumbPage>{currentTabLabel}</BreadcrumbPage>
-              </BreadcrumbItem>
-            </>
-          )}
-        </BreadcrumbList>
-      </Breadcrumb>
+          </BreadcrumbList>
+        </Breadcrumb>
+        {status}
+      </div>
 
-      <nav
-        aria-label={t('agents.pageHeader.subnavAriaLabel')}
-        className={cn(
-          'flex items-center gap-6',
-          // 1px baseline rule under the whole row; the active tab's 2px
-          // primary underline sits on top of it for the GitHub-style look.
-          !inline && 'border-border border-b',
-        )}
-      >
-        {tabs.map((tab) => {
-          const isActive = tab.id === currentPage;
-          // -mb-px lays the tab's 2px underline over the nav's 1px baseline.
-          if (isActive) {
+      {agentId && (
+        <nav
+          aria-label={t('agents.pageHeader.subnavAriaLabel')}
+          className={cn(
+            'flex items-center gap-6',
+            // 1px baseline rule under the whole row; the active tab's 2px
+            // primary underline sits on top of it for the GitHub-style look.
+            !inline && 'border-border border-b',
+          )}
+        >
+          {tabs.map((tab) => {
+            const isActive = tab.id === currentPage;
+            // -mb-px lays the tab's 2px underline over the nav's 1px baseline.
+            if (isActive) {
+              return (
+                <Button
+                  key={tab.id}
+                  asChild
+                  variant="tab"
+                  size="inline"
+                  data-active
+                  className="-mb-px"
+                >
+                  <span aria-current="page">{tab.label}</span>
+                </Button>
+              );
+            }
             return (
               <Button
                 key={tab.id}
                 asChild
                 variant="tab"
                 size="inline"
-                data-active
                 className="-mb-px"
               >
-                <span aria-current="page">{tab.label}</span>
+                <Link to={tab.href}>{tab.label}</Link>
               </Button>
             );
-          }
-          return (
-            <Button
-              key={tab.id}
-              asChild
-              variant="tab"
-              size="inline"
-              className="-mb-px"
-            >
-              <Link to={tab.href}>{tab.label}</Link>
-            </Button>
-          );
-        })}
-      </nav>
+          })}
+        </nav>
+      )}
     </div>
   );
 }
diff --git a/frontend/src/agents/workflow/CanvasControls.tsx b/frontend/src/agents/workflow/CanvasControls.tsx
new file mode 100644
index 00000000..54835a86
--- /dev/null
+++ b/frontend/src/agents/workflow/CanvasControls.tsx
@@ -0,0 +1,89 @@
+import { Maximize, Minus, Plus, Redo2, Undo2 } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { Panel, useReactFlow, useStore } from 'reactflow';
+
+import { IconButton } from '@/components/ui/icon-button';
+import { Separator } from '@/components/ui/separator';
+
+interface CanvasControlsProps {
+  onUndo: () => void;
+  onRedo: () => void;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+const ZOOM_DURATION_MS = 200;
+
+/**
+ * The canvas's one control strip, bottom left: undo and redo, then zoom out,
+ * the zoom level, zoom in and fit view. Replaces React Flow's own
+ * `<Controls />`, whose buttons ignore the theme. Render inside `<ReactFlow>`.
+ */
+export default function CanvasControls({
+  onUndo,
+  onRedo,
+  canUndo,
+  canRedo,
+}: CanvasControlsProps) {
+  const { t } = useTranslation();
+  const { zoomIn, zoomOut, fitView } = useReactFlow();
+  const zoom = useStore((state) => state.transform[2]);
+
+  return (
+    <Panel
+      position="bottom-left"
+      className="bg-card border-border flex items-center gap-0.5 rounded-full border p-1"
+    >
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={onUndo}
+        disabled={!canUndo}
+        label={t('agents.workflow.undo')}
+        hint={t('agents.workflow.undoHint')}
+        icon={Undo2}
+      />
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={onRedo}
+        disabled={!canRedo}
+        label={t('agents.workflow.redo')}
+        hint={t('agents.workflow.redoHint')}
+        icon={Redo2}
+      />
+      <Separator orientation="vertical" className="mx-1 h-5" />
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={() => zoomOut({ duration: ZOOM_DURATION_MS })}
+        label={t('agents.workflow.zoomOut')}
+        icon={Minus}
+      />
+      <span className="text-foreground w-11 text-center text-xs tabular-nums">
+        {Math.round(zoom * 100)}%
+      </span>
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={() => zoomIn({ duration: ZOOM_DURATION_MS })}
+        label={t('agents.workflow.zoomIn')}
+        icon={Plus}
+      />
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={() =>
+          fitView({ padding: 0.2, maxZoom: 0.8, duration: ZOOM_DURATION_MS })
+        }
+        label={t('agents.workflow.fitView')}
+        icon={Maximize}
+      />
+    </Panel>
+  );
+}
diff --git a/frontend/src/agents/workflow/NodePalette.test.tsx b/frontend/src/agents/workflow/NodePalette.test.tsx
new file mode 100644
index 00000000..53c164f5
--- /dev/null
+++ b/frontend/src/agents/workflow/NodePalette.test.tsx
@@ -0,0 +1,83 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import NodePalette from './NodePalette';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('NodePalette', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = (onAdd = vi.fn(), onDragStart = vi.fn()) => {
+    act(() => {
+      root.render(<NodePalette onAdd={onAdd} onDragStart={onDragStart} />);
+    });
+    return { onAdd, onDragStart };
+  };
+
+  const pill = (labelKey: string) =>
+    Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes(labelKey),
+    ) as HTMLButtonElement;
+
+  it('renders each node type as a draggable button', () => {
+    render();
+    const buttons = container.querySelectorAll('button');
+    expect(buttons).toHaveLength(6);
+    buttons.forEach((button) => {
+      expect(button.getAttribute('type')).toBe('button');
+      expect(button.getAttribute('draggable')).toBe('true');
+    });
+  });
+
+  it('adds a node of the pill type on click', () => {
+    const { onAdd } = render();
+    act(() => pill('agents.workflow.nodes.condition').click());
+    expect(onAdd).toHaveBeenCalledWith('condition');
+    act(() => pill('agents.workflow.builder.aiAgent').click());
+    expect(onAdd).toHaveBeenLastCalledWith('agent');
+  });
+
+  it('starts a drag with the pill type', () => {
+    const { onDragStart } = render();
+    const button = pill('agents.workflow.nodes.code');
+    act(() => {
+      button.dispatchEvent(new Event('dragstart', { bubbles: true }));
+    });
+    expect(onDragStart).toHaveBeenCalledWith(expect.anything(), 'code');
+  });
+
+  it('shows the shared tone on the icon square, with no hover swap', () => {
+    render();
+    const square = pill('agents.workflow.nodes.end').querySelector(
+      'span',
+    ) as HTMLElement;
+    expect(square.className).toContain('bg-success/10');
+    // Radius by role: a tinted icon square at size-8 is rounded-md.
+    expect(square.className).toContain('rounded-md');
+    expect(container.innerHTML).not.toContain('group-hover:');
+  });
+
+  it('explains click-to-add under the groups', () => {
+    render();
+    expect(container.textContent).toContain(
+      'agents.workflow.builder.paletteHint',
+    );
+  });
+});
diff --git a/frontend/src/agents/workflow/NodePalette.tsx b/frontend/src/agents/workflow/NodePalette.tsx
new file mode 100644
index 00000000..76864338
--- /dev/null
+++ b/frontend/src/agents/workflow/NodePalette.tsx
@@ -0,0 +1,123 @@
+import { type DragEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { SectionHeader } from '@/components/ui/section-header';
+import { cn, focusRing } from '@/lib/utils';
+
+import { NODE_META, nodeToneClass, type WorkflowNodeType } from './nodeTones';
+
+interface PaletteEntry {
+  type: WorkflowNodeType;
+  group: 'core' | 'logic';
+  hintKey?: string;
+}
+
+const PALETTE: PaletteEntry[] = [
+  { type: 'agent', group: 'core' },
+  { type: 'end', group: 'core' },
+  { type: 'note', group: 'core' },
+  {
+    type: 'state',
+    group: 'logic',
+    hintKey: 'agents.workflow.builder.setStateHint',
+  },
+  {
+    type: 'condition',
+    group: 'logic',
+    hintKey: 'agents.workflow.builder.conditionHint',
+  },
+  { type: 'code', group: 'logic', hintKey: 'agents.workflow.builder.codeHint' },
+];
+
+const GROUPS: { group: PaletteEntry['group']; titleKey: string }[] = [
+  { group: 'core', titleKey: 'agents.workflow.builder.coreNodes' },
+  { group: 'logic', titleKey: 'agents.workflow.builder.logicNodes' },
+];
+
+interface NodePaletteItemProps {
+  entry: PaletteEntry;
+  onAdd: (nodeType: WorkflowNodeType) => void;
+  onDragStart: (e: DragEvent, nodeType: string) => void;
+}
+
+/**
+ * A palette pill: drag it onto the canvas, or click (or press Enter) to add
+ * the node without dragging.
+ *
+ * Args:
+ *   entry: The palette entry to render.
+ *   onAdd: Adds a node of the entry's type beside the selection.
+ *   onDragStart: Starts dragging a node of the entry's type onto the canvas.
+ */
+function NodePaletteItem({ entry, onAdd, onDragStart }: NodePaletteItemProps) {
+  const { t } = useTranslation();
+  const { icon: Icon, labelKey } = NODE_META[entry.type];
+  const label = (
+    <span className="text-foreground text-sm font-medium">{t(labelKey)}</span>
+  );
+  return (
+    <button
+      type="button"
+      draggable
+      onDragStart={(e) => onDragStart(e, entry.type)}
+      onClick={() => onAdd(entry.type)}
+      className={cn(
+        'border-border bg-card hover:bg-accent flex cursor-grab items-center gap-3 rounded-full border px-4 py-2.5 text-left transition-colors outline-none',
+        focusRing,
+      )}
+    >
+      <span
+        className={cn(
+          'flex size-8 shrink-0 items-center justify-center rounded-md',
+          nodeToneClass(entry.type),
+        )}
+      >
+        <Icon className="size-4.5" aria-hidden="true" />
+      </span>
+      {entry.hintKey ? (
+        <span className="flex flex-col">
+          {label}
+          <span className="text-muted-foreground text-xs">
+            {t(entry.hintKey)}
+          </span>
+        </span>
+      ) : (
+        label
+      )}
+    </button>
+  );
+}
+
+interface NodePaletteProps {
+  /** Adds a node of the given type without dragging (click or Enter). */
+  onAdd: (nodeType: WorkflowNodeType) => void;
+  /** Starts dragging a node of the given type onto the canvas. */
+  onDragStart: (e: DragEvent, nodeType: string) => void;
+}
+
+/** The builder's left rail of node types, grouped Core and Logic. */
+export default function NodePalette({ onAdd, onDragStart }: NodePaletteProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="border-border bg-background flex w-64 shrink-0 flex-col gap-6 overflow-y-auto border-r p-4">
+      {GROUPS.map(({ group, titleKey }) => (
+        <div key={group} className="flex flex-col gap-3">
+          <SectionHeader as="h3" size="sm" title={t(titleKey)} />
+          <div className="flex flex-col gap-2">
+            {PALETTE.filter((entry) => entry.group === group).map((entry) => (
+              <NodePaletteItem
+                key={entry.type}
+                entry={entry}
+                onAdd={onAdd}
+                onDragStart={onDragStart}
+              />
+            ))}
+          </div>
+        </div>
+      ))}
+      <p className="text-muted-foreground text-xs">
+        {t('agents.workflow.builder.paletteHint')}
+      </p>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/WorkflowBuilder.tsx b/frontend/src/agents/workflow/WorkflowBuilder.tsx
index 09be651d..bd94b8ee 100644
--- a/frontend/src/agents/workflow/WorkflowBuilder.tsx
+++ b/frontend/src/agents/workflow/WorkflowBuilder.tsx
@@ -1,33 +1,8 @@
 import 'reactflow/dist/style.css';
 
-import {
-  Bot,
-  CircleAlert,
-  CodeXml,
-  Database,
-  Flag,
-  GitBranch,
-  Link,
-  Pencil,
-  Play,
-  Plus,
-  Redo2,
-  StickyNote,
-  Trash2,
-  Undo2,
-  X,
-  type LucideIcon,
-} from 'lucide-react';
-import {
-  type DragEvent,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
-import { type TFunction } from 'i18next';
-import { Trans, useTranslation } from 'react-i18next';
+import { CircleAlert, Link, Pencil, Play, Trash2, X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 import { useNavigate, useParams, useSearchParams } from 'react-router-dom';
 import ReactFlow, {
@@ -36,49 +11,23 @@ import ReactFlow, {
   applyNodeChanges,
   Background,
   Connection,
-  Controls,
   Edge,
   EdgeChange,
   Node,
   NodeChange,
   NodeTypes,
-  Panel,
   ReactFlowProvider,
   useReactFlow,
+  XYPosition,
 } from 'reactflow';
 
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
-import { Avatar } from '@/components/ui/avatar';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-import { Checkbox } from '@/components/ui/checkbox';
 import { IconButton } from '@/components/ui/icon-button';
-import { FormField } from '@/components/ui/form-field';
-import { Input } from '@/components/ui/input';
-import { MultiSelect } from '@/components/ui/multi-select';
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from '@/components/ui/popover';
-import {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectLabel,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import { SectionHeader } from '@/components/ui/section-header';
-import { SettingRow } from '@/components/ui/setting-row';
-import { Switch } from '@/components/ui/switch';
-import { Textarea } from '@/components/ui/textarea';
-import { cn } from '@/lib/utils';
 
 import modelService from '../../api/services/modelService';
 import userService from '../../api/services/userService';
-import { FileUpload } from '../../components/FileUpload';
 import AgentDetailsModal from '../../modals/AgentDetailsModal';
 import ConfirmationModal from '../../modals/ConfirmationModal';
 import { ActiveState } from '../../models/misc';
@@ -86,11 +35,13 @@ import {
   selectSourceDocs,
   selectToken,
 } from '../../preferences/preferenceSlice';
-import { getToolDisplayName } from '../../utils/toolUtils';
 import { agentEditPath, agentsListPath } from '../paths';
 import { ActionMenu } from '@/components/ui/dropdown-menu';
 import AgentPageHeader from '../AgentPageHeader';
 import AgentPreviewSheet from '../components/AgentPreviewSheet';
+import WorkflowDetailsSheet, {
+  type WorkflowDetailsSave,
+} from './components/WorkflowDetailsSheet';
 import { Agent } from '../types';
 import { ConditionCase, WorkflowNode } from '../types/workflow';
 import {
@@ -101,17 +52,9 @@ import {
   validateCodeJsonSchema,
 } from './codeNodeConfig';
 import MobileBlocker from './components/MobileBlocker';
-import { buildSimpleCel, parseSimpleCel } from './simpleCel';
-import NodeDocumentsControl from './components/NodeDocumentsControl';
-import PromptTextArea, {
-  extractUpstreamVariables,
-} from './components/PromptTextArea';
-import {
-  FILE_PASSING_OPTIONS,
-  FilePassing,
-  normalizeFilePassing,
-  toDocumentVariableOptions,
-} from './documentConfig';
+import { parseSimpleCel } from './simpleCel';
+import { extractUpstreamVariables } from './components/PromptTextArea';
+import { toDocumentVariableOptions } from './documentConfig';
 import { useUndoRedo, WorkflowSnapshot } from './hooks/useUndoRedo';
 import {
   AgentNode,
@@ -122,200 +65,38 @@ import {
   SetStateNode,
   StartNode,
 } from './nodes';
+import CanvasControls from './CanvasControls';
+import NodePalette from './NodePalette';
+import NodePanel from './panels/NodePanel';
+import { WorkflowModelsContext } from './WorkflowModelsContext';
+import AgentPanel from './panels/AgentPanel';
+import CodePanel from './panels/CodePanel';
+import ConditionPanel from './panels/ConditionPanel';
+import NotePanel from './panels/NotePanel';
+import StatePanel from './panels/StatePanel';
 import WorkflowPreview from './WorkflowPreview';
+import {
+  type AgentNodeConfig,
+  findFreePosition,
+  NO_ESCAPE,
+  normalizeConditionCases,
+  schemaErrorText,
+  type UserTool,
+  validateJsonSchemaConfig,
+} from './workflowHelpers';
 import { selectWorkflowPreviewStatus } from './workflowPreviewSlice';
 
 import type { Model } from '../../models/types';
 
 const PRIMARY_ACTION_SPINNER_DELAY_MS = 180;
-
-type PaletteTone = 'primary' | 'success' | 'warning' | 'info';
-
-// Whole class strings per tone so Tailwind sees them.
-const PALETTE_TONE_CLASSES: Record<PaletteTone, string> = {
-  primary:
-    'bg-secondary text-secondary-foreground group-hover:bg-primary group-hover:text-primary-foreground',
-  success:
-    'bg-success/10 text-success group-hover:bg-success group-hover:text-success-foreground',
-  warning:
-    'bg-warning/10 text-warning group-hover:bg-warning group-hover:text-warning-foreground',
-  info: 'bg-info/10 text-info group-hover:bg-info group-hover:text-info-foreground',
-};
-
-interface PaletteEntry {
-  type: string;
-  group: 'core' | 'logic';
-  icon: LucideIcon;
-  tone: PaletteTone;
-  labelKey: string;
-  hintKey?: string;
-}
-
-const PALETTE: PaletteEntry[] = [
-  {
-    type: 'agent',
-    group: 'core',
-    icon: Bot,
-    tone: 'primary',
-    labelKey: 'agents.workflow.builder.aiAgent',
-  },
-  {
-    type: 'end',
-    group: 'core',
-    icon: Flag,
-    tone: 'success',
-    labelKey: 'agents.workflow.nodes.end',
-  },
-  {
-    type: 'note',
-    group: 'core',
-    icon: StickyNote,
-    tone: 'warning',
-    labelKey: 'agents.workflow.nodes.note',
-  },
-  {
-    type: 'state',
-    group: 'logic',
-    icon: Database,
-    tone: 'info',
-    labelKey: 'agents.workflow.nodes.setState',
-    hintKey: 'agents.workflow.builder.setStateHint',
-  },
-  {
-    type: 'condition',
-    group: 'logic',
-    icon: GitBranch,
-    tone: 'warning',
-    labelKey: 'agents.workflow.nodes.condition',
-    hintKey: 'agents.workflow.builder.conditionHint',
-  },
-  {
-    type: 'code',
-    group: 'logic',
-    icon: CodeXml,
-    tone: 'info',
-    labelKey: 'agents.workflow.nodes.code',
-    hintKey: 'agents.workflow.builder.codeHint',
-  },
-];
-
-/**
- * A draggable pill in the builder's node palette.
- *
- * Args:
- *   entry: The palette entry to render.
- *   onDragStart: Starts dragging a node of the entry's type onto the canvas.
- */
-function NodePaletteItem({
-  entry,
-  onDragStart,
-}: {
-  entry: PaletteEntry;
-  onDragStart: (e: DragEvent, nodeType: string) => void;
-}) {
-  const { t } = useTranslation();
-  const Icon = entry.icon;
-  const label = (
-    <span className="text-foreground text-sm font-medium">
-      {t(entry.labelKey)}
-    </span>
-  );
-  return (
-    <div
-      className="group border-border bg-card hover:border-primary/40 flex cursor-move items-center gap-3 rounded-full border px-4 py-3 transition-colors"
-      draggable
-      onDragStart={(e) => onDragStart(e, entry.type)}
-    >
-      <div
-        className={cn(
-          'flex size-8 shrink-0 items-center justify-center rounded-full transition-colors',
-          PALETTE_TONE_CLASSES[entry.tone],
-        )}
-      >
-        <Icon className="size-4.5" />
-      </div>
-      {entry.hintKey ? (
-        <div className="flex flex-col">
-          {label}
-          <span className="text-muted-foreground text-xs">
-            {t(entry.hintKey)}
-          </span>
-        </div>
-      ) : (
-        label
-      )}
-    </div>
-  );
-}
-
-interface AgentNodeConfig {
-  agent_type: 'classic' | 'research';
-  llm_name?: string;
-  model_id?: string;
-  system_prompt: string;
-  prompt_template: string;
-  output_variable?: string;
-  stream_to_user: boolean;
-  sources: string[];
-  tools: string[];
-  chunks?: string;
-  retriever?: string;
-  json_schema?: Record<string, unknown>;
-  input_documents?: string[];
-  file_passing?: FilePassing;
-}
-
-interface UserTool {
-  id: string;
-  name: string;
-  displayName: string;
-  customName?: string;
-  // Workflow-only builtins (e.g. read_document) are kept here; the classic
-  // agent picker filters them out.
-  workflow_only?: boolean;
-}
-
-function validateJsonSchemaConfig(schema: unknown): string | null {
-  if (schema === undefined || schema === null) return null;
-  if (typeof schema !== 'object' || Array.isArray(schema)) {
-    return 'must be a valid JSON object';
-  }
-
-  const schemaObject = schema as Record<string, unknown>;
-  if (!('schema' in schemaObject) && !('type' in schemaObject)) {
-    return 'must include either a "type" or "schema" field';
-  }
-
-  return null;
-}
-
-// The schema validators return short English fragments (tests and the
-// validation list key off them); these map each to its locale key.
-// Names and handles are the user's own text: React escapes on render, so
-// i18next must not escape them first.
-const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
-
-const SCHEMA_ERROR_KEYS: Record<string, string> = {
-  'must be a valid JSON object': 'agents.workflow.schema.notObject',
-  'must include either a "type" or "schema" field':
-    'agents.workflow.schema.missingType',
-  'must be valid JSON': 'agents.workflow.schema.invalidJson',
-};
-
-/**
- * Translate a JSON schema validation fragment.
- *
- * Args:
- *   t: The i18next translate function.
- *   fragment: The fragment a schema validator returned.
- *
- * Returns:
- *   The translated fragment, or the fragment itself when it is unknown.
- */
-function schemaErrorText(t: TFunction, fragment: string): string {
-  const key = SCHEMA_ERROR_KEYS[fragment];
-  return key ? t(key) : fragment;
-}
+// A node added from the palette while one is selected lands this far right
+// of it (then moves down until it covers nothing).
+const ADD_BESIDE_GAP_X = 80;
+// Roughly half a node's size, to centre a new node in the view.
+const NEW_NODE_HALF_WIDTH = 100;
+const NEW_NODE_HALF_HEIGHT = 32;
+// A duplicate sits this far down and right of its original.
+const DUPLICATE_OFFSET = 40;
 
 function isEditableTarget(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) return false;
@@ -355,52 +136,6 @@ function canReachEnd(
     .some((e) => canReachEnd(e.target, edges, nodeIds, endIds, visited));
 }
 
-function normalizeConditionCases(cases: ConditionCase[]): ConditionCase[] {
-  const usedHandles = new Set<string>();
-  let nextIndex = 0;
-
-  return cases.map((conditionCase) => {
-    const candidate = (conditionCase.sourceHandle || '').trim();
-    if (candidate && !usedHandles.has(candidate)) {
-      usedHandles.add(candidate);
-      const match = candidate.match(/^case_(\d+)$/);
-      if (match) {
-        nextIndex = Math.max(nextIndex, Number(match[1]) + 1);
-      }
-      return conditionCase;
-    }
-
-    while (usedHandles.has(`case_${nextIndex}`)) {
-      nextIndex += 1;
-    }
-    const generatedHandle = `case_${nextIndex}`;
-    usedHandles.add(generatedHandle);
-    nextIndex += 1;
-
-    return {
-      ...conditionCase,
-      sourceHandle: generatedHandle,
-    };
-  });
-}
-
-function getNextConditionHandle(cases: ConditionCase[]): string {
-  const usedHandles = new Set(
-    cases.map((conditionCase) => conditionCase.sourceHandle).filter(Boolean),
-  );
-  const usedIndices = Array.from(usedHandles)
-    .map((handle) => handle.match(/^case_(\d+)$/))
-    .filter((match): match is RegExpMatchArray => Boolean(match))
-    .map((match) => Number(match[1]));
-
-  let nextIndex = usedIndices.length > 0 ? Math.max(...usedIndices) + 1 : 0;
-  while (usedHandles.has(`case_${nextIndex}`)) {
-    nextIndex += 1;
-  }
-
-  return `case_${nextIndex}`;
-}
-
 function createWorkflowPayload(
   name: string,
   description: string,
@@ -467,7 +202,11 @@ function WorkflowBuilderInner() {
   const [selectedNode, setSelectedNode] = useState<Node | null>(null);
   const [workflowName, setWorkflowName] = useState('New Workflow');
   const [workflowDescription, setWorkflowDescription] = useState('');
-  const [showWorkflowSettings, setShowWorkflowSettings] = useState(false);
+  const [showDetails, setShowDetails] = useState(false);
+  // A save asked for by the details sheet runs after its values reach state.
+  const [detailsSaveRequested, setDetailsSaveRequested] = useState(false);
+  const [detailsSaving, setDetailsSaving] = useState(false);
+  const [detailsSaveFailed, setDetailsSaveFailed] = useState(false);
   const [isPublishing, setIsPublishing] = useState(false);
   const [showPrimaryActionSpinner, setShowPrimaryActionSpinner] =
     useState(false);
@@ -489,6 +228,13 @@ function WorkflowBuilderInner() {
     string | null
   >(null);
   const [availableModels, setAvailableModels] = useState<Model[]>([]);
+  const modelNames = useMemo(
+    () =>
+      Object.fromEntries(
+        availableModels.map((model) => [model.id, model.display_name]),
+      ),
+    [availableModels],
+  );
   const [defaultAgentModelId, setDefaultAgentModelId] = useState('');
   const [availableTools, setAvailableTools] = useState<UserTool[]>([]);
   const sourceOptions = useMemo(
@@ -635,20 +381,14 @@ function WorkflowBuilderInner() {
     event.dataTransfer.dropEffect = 'move';
   }, []);
 
-  const onDrop = useCallback(
-    (event: React.DragEvent) => {
-      event.preventDefault();
-
-      const type = event.dataTransfer.getData('application/reactflow');
-      if (!type) return;
-
+  /**
+   * Add a node of a palette type at a flow position, with its default config.
+   * Takes an undo snapshot first; the selection is left as it was.
+   */
+  const createNode = useCallback(
+    (type: string, position: XYPosition) => {
       takeSnapshot();
 
-      const position = reactFlowInstance.screenToFlowPosition({
-        x: event.clientX,
-        y: event.clientY,
-      });
-
       const baseNode: Node = {
         id: `${type}_${Date.now()}`,
         type,
@@ -696,7 +436,61 @@ function WorkflowBuilderInner() {
 
       setNodes((nds) => nds.concat(baseNode));
     },
-    [reactFlowInstance, availableModels, defaultAgentModelId, takeSnapshot],
+    [availableModels, defaultAgentModelId, takeSnapshot],
+  );
+
+  const onDrop = useCallback(
+    (event: React.DragEvent) => {
+      event.preventDefault();
+
+      const type = event.dataTransfer.getData('application/reactflow');
+      if (!type) return;
+
+      createNode(
+        type,
+        reactFlowInstance.screenToFlowPosition({
+          x: event.clientX,
+          y: event.clientY,
+        }),
+      );
+    },
+    [reactFlowInstance, createNode],
+  );
+
+  // Click or Enter on a palette pill: beside the selected node, else in the
+  // middle of what the canvas shows.
+  const handleAddNodeFromPalette = useCallback(
+    (type: string) => {
+      const anchor = selectedNode
+        ? nodes.find((n) => n.id === selectedNode.id)
+        : undefined;
+      if (anchor) {
+        createNode(
+          type,
+          findFreePosition(nodes, {
+            x: anchor.position.x + (anchor.width ?? 0) + ADD_BESIDE_GAP_X,
+            y: anchor.position.y,
+          }),
+        );
+        return;
+      }
+      const rect = reactFlowWrapper.current?.getBoundingClientRect();
+      const center = rect
+        ? reactFlowInstance.screenToFlowPosition({
+            x: rect.left + rect.width / 2,
+            y: rect.top + rect.height / 2,
+          })
+        : { x: 0, y: 0 };
+      // Positions are a node's top-left corner; centre a typical node.
+      createNode(
+        type,
+        findFreePosition(nodes, {
+          x: center.x - NEW_NODE_HALF_WIDTH,
+          y: center.y - NEW_NODE_HALF_HEIGHT,
+        }),
+      );
+    },
+    [selectedNode, nodes, createNode, reactFlowInstance],
   );
 
   const handleNodeClick = useCallback(
@@ -751,6 +545,43 @@ function WorkflowBuilderInner() {
     deleteNodesAndEdges([selectedNode], []);
   }, [selectedNode, deleteNodesAndEdges]);
 
+  // Clone the open node beside itself and open the copy.
+  const handleDuplicateNode = useCallback(() => {
+    if (!selectedNode || selectedNode.type === 'start') return;
+    const original = nodes.find((n) => n.id === selectedNode.id);
+    if (!original) return;
+    takeSnapshot();
+    const copy: Node = {
+      id: `${original.type}_${Date.now()}`,
+      type: original.type,
+      position: {
+        x: original.position.x + DUPLICATE_OFFSET,
+        y: original.position.y + DUPLICATE_OFFSET,
+      },
+      data: structuredClone(original.data),
+      selected: true,
+    };
+    setNodes((nds) =>
+      nds.map((n) => (n.selected ? { ...n, selected: false } : n)).concat(copy),
+    );
+    setSelectedNode(copy);
+    setShowNodeConfig(true);
+  }, [selectedNode, nodes, takeSnapshot]);
+
+  const handleRemoveConditionBranch = useCallback(
+    (sourceHandle: string) => {
+      if (!selectedNode) return;
+      const nodeId = selectedNode.id;
+      setEdges((eds) =>
+        eds.filter(
+          (edge) =>
+            !(edge.source === nodeId && edge.sourceHandle === sourceHandle),
+        ),
+      );
+    },
+    [selectedNode],
+  );
+
   const handleUpdateNodeData = useCallback(
     (data: Record<string, unknown>, options?: { snapshot?: boolean }) => {
       if (!selectedNode) return;
@@ -834,12 +665,6 @@ function WorkflowBuilderInner() {
     [handleUpdateNodeData, selectedNode],
   );
 
-  const handleUpload = useCallback((files: File[]) => {
-    if (files && files.length > 0) {
-      setImageFile(files[0]);
-    }
-  }, []);
-
   const navigateBackToAgents = useCallback(() => {
     navigate(agentsListPath(folderId));
   }, [navigate, folderId]);
@@ -890,7 +715,10 @@ function WorkflowBuilderInner() {
     // behind it), or once another handler has already consumed the event. Kept
     // in one place so the branches can't drift apart.
     const shouldIgnoreShortcut = (e: KeyboardEvent): boolean =>
-      e.defaultPrevented || showPreview || isEditableTarget(e.target);
+      e.defaultPrevented ||
+      showPreview ||
+      showDetails ||
+      isEditableTarget(e.target);
 
     const handleKeyDown = (e: KeyboardEvent) => {
       if (shouldIgnoreShortcut(e)) return;
@@ -931,12 +759,12 @@ function WorkflowBuilderInner() {
     undo,
     redo,
     showPreview,
+    showDetails,
   ]);
 
   const handlePaneClick = useCallback(() => {
     setShowNodeConfig(false);
     setSelectedNode(null);
-    setShowWorkflowSettings(false);
   }, []);
 
   useEffect(() => {
@@ -1652,17 +1480,42 @@ function WorkflowBuilderInner() {
       workflowName,
       workflowDescription,
       imageFile,
+      currentAgent.allow_system_prompt_override,
       folderId,
       navigateBackToAgents,
       t,
     ],
   );
 
-  const handleWorkflowSettingsDone = useCallback(() => {
-    setShowWorkflowSettings(false);
-    if (!canManageAgent || !hasSavableChanges || isPublishing) return;
-    void persistWorkflow(false);
-  }, [canManageAgent, hasSavableChanges, isPublishing, persistWorkflow]);
+  const openDetails = useCallback(() => {
+    setDetailsSaveFailed(false);
+    setShowDetails(true);
+  }, []);
+
+  // Save from the details sheet: put its values into the builder, then save
+  // once they are in state (the effect below), so the request carries them.
+  const handleDetailsSave = useCallback((values: WorkflowDetailsSave) => {
+    setWorkflowName(values.name);
+    setWorkflowDescription(values.description);
+    setCurrentAgent((prev) => ({
+      ...prev,
+      allow_system_prompt_override: values.allowPromptOverride,
+    }));
+    if (values.imageFile) setImageFile(values.imageFile);
+    setDetailsSaveRequested(true);
+  }, []);
+
+  useEffect(() => {
+    if (!detailsSaveRequested) return;
+    setDetailsSaveRequested(false);
+    setDetailsSaving(true);
+    setDetailsSaveFailed(false);
+    void persistWorkflow(false).then((ok) => {
+      setDetailsSaving(false);
+      if (ok) setShowDetails(false);
+      else setDetailsSaveFailed(true);
+    });
+  }, [detailsSaveRequested, persistWorkflow]);
 
   const isPrimaryActionDisabled =
     isPublishing || (canManageAgent && !hasSavableChanges);
@@ -1782,157 +1635,31 @@ function WorkflowBuilderInner() {
     <>
       <MobileBlocker />
       <div className="bg-background fixed inset-0 z-50 hidden h-dvh w-full flex-col lg:flex">
-        <div className="border-border bg-card flex items-center justify-between border-b px-6 py-4">
-          <div className="flex items-center gap-4">
-            {canManageAgent ? (
-              <AgentPageHeader
-                agentId={effectiveAgentId}
-                agentName={workflowName}
-                agentEditPath={agentEditPath(effectiveAgentId, true)}
-                currentPage="overview"
-                inline
-              />
-            ) : (
-              <Button
-                type="button"
-                variant="outline"
-                size="field"
-                shape="pill"
-                onClick={navigateBackToAgents}
-              >
-                {t('agents.backToAll')}
-              </Button>
+        <div className="border-border bg-background flex items-center justify-between gap-4 border-b px-6 py-4">
+          <AgentPageHeader
+            agentId={canManageAgent ? effectiveAgentId : undefined}
+            agentName={workflowName || t('agents.workflow.builder.newWorkflow')}
+            agentEditPath={agentEditPath(effectiveAgentId, true)}
+            agentImage={currentAgentImage}
+            currentPage="overview"
+            onNameClick={openDetails}
+            status={
+              canManageAgent && currentAgent.status !== 'draft' ? (
+                <Badge variant="success">
+                  {t('agents.form.status.published')}
+                </Badge>
+              ) : (
+                <Badge variant="neutral">{t('agents.card.draft')}</Badge>
+              )
+            }
+            inline
+          />
+          <div className="flex shrink-0 items-center gap-2">
+            {(!canManageAgent || hasSavableChanges) && (
+              <span className="text-muted-foreground mr-2 text-sm">
+                {t('agents.workflow.builder.unsavedChanges')}
+              </span>
             )}
-            {!canManageAgent && (
-              <div className="min-w-0">
-                <div
-                  className="text-foreground max-w-xs truncate text-xl leading-tight font-semibold"
-                  title={
-                    workflowName || t('agents.workflow.builder.newWorkflow')
-                  }
-                >
-                  {workflowName || t('agents.workflow.builder.newWorkflow')}
-                </div>
-                {workflowDescription && (
-                  <div
-                    className="text-muted-foreground max-w-xs truncate text-xs"
-                    title={workflowDescription}
-                  >
-                    {workflowDescription}
-                  </div>
-                )}
-              </div>
-            )}
-            <Popover
-              open={showWorkflowSettings}
-              onOpenChange={setShowWorkflowSettings}
-            >
-              <PopoverTrigger asChild>
-                <IconButton
-                  variant="ghost-muted"
-                  size="icon-xs"
-                  side="bottom"
-                  label={t('agents.workflow.builder.editDetails')}
-                  hint={
-                    workflowDescription
-                      ? `${workflowName || t('agents.workflow.builder.newWorkflow')} — ${workflowDescription}`
-                      : undefined
-                  }
-                  icon={Pencil}
-                />
-              </PopoverTrigger>
-              <PopoverContent align="start" className="w-80">
-                <div className="flex flex-col gap-5">
-                  <FormField label={t('agents.workflow.builder.workflowName')}>
-                    <Input
-                      type="text"
-                      value={workflowName}
-                      onChange={(e) => setWorkflowName(e.target.value)}
-                      placeholder={t(
-                        'agents.workflow.builder.workflowNamePlaceholder',
-                      )}
-                    />
-                  </FormField>
-                  <FormField label={t('agents.form.labels.description')}>
-                    <Textarea
-                      value={workflowDescription}
-                      onChange={(e) => setWorkflowDescription(e.target.value)}
-                      rows={3}
-                      placeholder={t(
-                        'agents.workflow.builder.workflowDescriptionPlaceholder',
-                      )}
-                    />
-                  </FormField>
-                  {currentAgentImage && !imageFile && (
-                    <div className="flex items-center gap-2">
-                      <Avatar
-                        src={currentAgentImage}
-                        alt={t('agents.workflow.builder.agentImageAlt')}
-                        size="lg"
-                        shape="circle"
-                        imgClassName="size-full object-cover"
-                      />
-                      <span className="text-muted-foreground text-xs">
-                        {t('agents.workflow.builder.currentImage')}
-                      </span>
-                    </div>
-                  )}
-                  <FormField
-                    label={t('agents.workflow.builder.agentImage')}
-                    hint={t('agents.workflow.builder.agentImageHint')}
-                  >
-                    <FileUpload
-                      showPreview
-                      maxFiles={1}
-                      previewSize={56}
-                      size="compact"
-                      onUpload={handleUpload}
-                      onRemove={() => setImageFile(null)}
-                      uploadText={[
-                        {
-                          text: t('agents.form.upload.clickToUpload'),
-                          highlight: true,
-                        },
-                        {
-                          text: t('agents.form.upload.dragAndDrop'),
-                        },
-                      ]}
-                    />
-                  </FormField>
-                  <SettingRow
-                    label={t('agents.form.advanced.systemPromptOverride')}
-                    description={t(
-                      'agents.form.advanced.systemPromptOverrideDescription',
-                    )}
-                    htmlFor="workflow-system-prompt-override"
-                  >
-                    <Switch
-                      id="workflow-system-prompt-override"
-                      checked={Boolean(
-                        currentAgent.allow_system_prompt_override,
-                      )}
-                      onCheckedChange={() =>
-                        setCurrentAgent((prev) => ({
-                          ...prev,
-                          allow_system_prompt_override:
-                            !prev.allow_system_prompt_override,
-                        }))
-                      }
-                    />
-                  </SettingRow>
-                  <Button
-                    type="button"
-                    onClick={handleWorkflowSettingsDone}
-                    disabled={isPublishing}
-                    className="w-full"
-                  >
-                    {t('agents.workflow.builder.done')}
-                  </Button>
-                </div>
-              </PopoverContent>
-            </Popover>
-          </div>
-          <div className="flex items-center gap-2">
             <Button
               type="button"
               variant="outline"
@@ -1961,30 +1688,37 @@ function WorkflowBuilderInner() {
             >
               {primaryActionLabel}
             </Button>
-            {canManageAgent && (
-              <ActionMenu
-                size="toolbar"
-                triggerLabel={t('agents.form.buttons.moreActions')}
-                options={[
-                  {
-                    label: t('agents.form.buttons.accessDetails'),
-                    icon: Link,
-                    onClick: () => setAgentDetails('ACTIVE'),
-                  },
-                  {
-                    label: t('agents.form.buttons.delete'),
-                    icon: Trash2,
-                    variant: 'destructive',
-                    disabled: isDeletingAgent,
-                    onClick: () => setDeleteConfirmation('ACTIVE'),
-                  },
-                ]}
-              />
-            )}
+            <ActionMenu
+              size="toolbar"
+              triggerLabel={t('agents.form.buttons.moreActions')}
+              options={[
+                {
+                  label: t('agents.workflow.builder.editDetailsMenu'),
+                  icon: Pencil,
+                  onClick: openDetails,
+                },
+                ...(canManageAgent
+                  ? [
+                      {
+                        label: t('agents.form.buttons.accessDetails'),
+                        icon: Link,
+                        onClick: () => setAgentDetails('ACTIVE'),
+                      },
+                      {
+                        label: t('agents.form.buttons.delete'),
+                        icon: Trash2,
+                        variant: 'destructive' as const,
+                        disabled: isDeletingAgent,
+                        onClick: () => setDeleteConfirmation('ACTIVE'),
+                      },
+                    ]
+                  : []),
+              ]}
+            />
           </div>
         </div>
 
-        {publishErrors.length > 0 && (
+        {publishErrors.length > 0 && !showDetails && (
           <div className="pointer-events-none absolute top-20 right-0 left-0 z-20 flex justify-center px-4">
             <div className="bg-card pointer-events-auto w-full max-w-md rounded-xl shadow-md">
               <Alert
@@ -2021,1286 +1755,122 @@ function WorkflowBuilderInner() {
           </div>
         )}
 
-        <div className="flex flex-1 overflow-hidden">
-          <div className="border-border bg-muted flex w-64 flex-col gap-6 border-r p-4">
-            <div className="flex flex-col gap-3">
-              <SectionHeader
-                as="h3"
-                size="sm"
-                title={t('agents.workflow.builder.coreNodes')}
-              />
-              <div className="flex flex-col gap-2">
-                {PALETTE.filter((entry) => entry.group === 'core').map(
-                  (entry) => (
-                    <NodePaletteItem
-                      key={entry.type}
-                      entry={entry}
-                      onDragStart={handleNodeDragStart}
-                    />
-                  ),
-                )}
-              </div>
-            </div>
+        <div className="flex min-h-0 flex-1 overflow-hidden">
+          <NodePalette
+            onAdd={handleAddNodeFromPalette}
+            onDragStart={handleNodeDragStart}
+          />
 
-            <div className="flex flex-col gap-3">
-              <SectionHeader
-                as="h3"
-                size="sm"
-                title={t('agents.workflow.builder.logicNodes')}
-              />
-              <div className="flex flex-col gap-2">
-                {PALETTE.filter((entry) => entry.group === 'logic').map(
-                  (entry) => (
-                    <NodePaletteItem
-                      key={entry.type}
-                      entry={entry}
-                      onDragStart={handleNodeDragStart}
-                    />
-                  ),
-                )}
-              </div>
-            </div>
+          <div
+            ref={reactFlowWrapper}
+            className="bg-muted relative min-w-0 flex-1"
+          >
+            <WorkflowModelsContext.Provider value={modelNames}>
+              <ReactFlow
+                nodes={nodes}
+                edges={edges}
+                onNodesChange={onNodesChange}
+                onEdgesChange={onEdgesChange}
+                onConnect={onConnect}
+                onEdgeClick={onEdgeClick}
+                onDrop={onDrop}
+                onDragOver={onDragOver}
+                onNodeClick={handleNodeClick}
+                onPaneClick={handlePaneClick}
+                onNodeDragStart={snapshotBeforeCanvasChange}
+                onSelectionDragStart={snapshotBeforeCanvasChange}
+                nodeTypes={nodeTypes}
+                nodeDragThreshold={1}
+                deleteKeyCode={null}
+                proOptions={{ hideAttribution: true }}
+                fitView
+              >
+                <Background />
+                <CanvasControls
+                  onUndo={undo}
+                  onRedo={redo}
+                  canUndo={canUndo}
+                  canRedo={canRedo}
+                />
+              </ReactFlow>
+            </WorkflowModelsContext.Provider>
           </div>
 
-          <div ref={reactFlowWrapper} className="bg-muted relative flex-1">
-            <ReactFlow
-              nodes={nodes}
-              edges={edges}
-              onNodesChange={onNodesChange}
-              onEdgesChange={onEdgesChange}
-              onConnect={onConnect}
-              onEdgeClick={onEdgeClick}
-              onDrop={onDrop}
-              onDragOver={onDragOver}
-              onNodeClick={handleNodeClick}
-              onPaneClick={handlePaneClick}
-              onNodeDragStart={snapshotBeforeCanvasChange}
-              onSelectionDragStart={snapshotBeforeCanvasChange}
-              nodeTypes={nodeTypes}
-              nodeDragThreshold={1}
-              deleteKeyCode={null}
-              fitView
+          {showNodeConfig && selectedNode && (
+            <NodePanel
+              key={selectedNode.id}
+              node={selectedNode}
+              onClose={() => setShowNodeConfig(false)}
+              onDuplicate={handleDuplicateNode}
+              onDelete={handleDeleteNode}
+              onUpdate={handleUpdateNodeData}
             >
-              <Background />
-              <Controls />
-              <Panel position="top-left" className="flex gap-1.5">
-                <IconButton
-                  variant="outline"
-                  size="icon-sm"
-                  side="bottom"
-                  onClick={undo}
-                  disabled={!canUndo}
-                  label={t('agents.workflow.undo')}
-                  hint={t('agents.workflow.undoHint')}
-                  icon={Undo2}
+              {selectedNode.type === 'agent' && (
+                <AgentPanel
+                  node={selectedNode}
+                  onUpdate={handleUpdateNodeData}
+                  nodes={nodes}
+                  edges={edges}
+                  availableModels={availableModels}
+                  availableTools={availableTools}
+                  sourceOptions={sourceOptions}
+                  documentOptions={selectedAgentDocumentOptions}
+                  jsonSchemaText={selectedAgentJsonSchemaText}
+                  jsonSchemaError={selectedAgentJsonSchemaError}
+                  modelSupportsStructuredOutput={
+                    selectedAgentModelSupportsStructuredOutput
+                  }
+                  onJsonSchemaChange={handleAgentJsonSchemaChange}
                 />
-                <IconButton
-                  variant="outline"
-                  size="icon-sm"
-                  side="bottom"
-                  onClick={redo}
-                  disabled={!canRedo}
-                  label={t('agents.workflow.redo')}
-                  hint={t('agents.workflow.redoHint')}
-                  icon={Redo2}
+              )}
+              {selectedNode.type === 'note' && (
+                <NotePanel
+                  node={selectedNode}
+                  onUpdate={handleUpdateNodeData}
                 />
-              </Panel>
-            </ReactFlow>
-
-            {showNodeConfig && selectedNode && (
-              <>
-                <div className="border-border bg-card absolute top-4 right-4 z-20 w-96 rounded-2xl border shadow-md">
-                  <div className="border-border flex items-center justify-between border-b p-4">
-                    <h3 className="text-foreground text-sm font-semibold">
-                      {selectedNode.type === 'start' &&
-                        t('agents.workflow.builder.startNode')}
-                      {selectedNode.type === 'end' &&
-                        t('agents.workflow.builder.endNode')}
-                      {selectedNode.type === 'agent' &&
-                        t('agents.workflow.builder.aiAgent')}
-                      {selectedNode.type === 'note' &&
-                        t('agents.workflow.nodes.note')}
-                      {selectedNode.type === 'state' &&
-                        t('agents.workflow.builder.stateTitle')}
-                      {selectedNode.type === 'condition' &&
-                        t('agents.workflow.nodes.condition')}
-                      {selectedNode.type === 'code' &&
-                        t('agents.workflow.nodes.code')}
-                    </h3>
-                    <IconButton
-                      variant="ghost-muted"
-                      size="icon-xs"
-                      side="bottom"
-                      onClick={() => setShowNodeConfig(false)}
-                      label={t('agents.close')}
-                    >
-                      <X className="size-5" aria-hidden />
-                    </IconButton>
-                  </div>
-
-                  <div className="max-h-[calc(100dvh-200px)] overflow-y-auto p-4">
-                    <div className="mb-4 flex flex-col gap-5">
-                      <div className="bg-muted rounded-lg p-3">
-                        <div className="text-muted-foreground mb-1 text-xs">
-                          {t('agents.workflow.builder.nodeId')}
-                        </div>
-                        <div className="text-foreground truncate font-mono text-xs">
-                          {selectedNode.id}
-                        </div>
-                      </div>
-
-                      {selectedNode.type !== 'start' &&
-                        selectedNode.type !== 'end' && (
-                          <>
-                            <FormField
-                              label={t('agents.workflow.builder.title')}
-                            >
-                              <Input
-                                type="text"
-                                value={
-                                  selectedNode.data.title ||
-                                  selectedNode.data.label ||
-                                  ''
-                                }
-                                onChange={(e) =>
-                                  handleUpdateNodeData({
-                                    title: e.target.value,
-                                    label: e.target.value,
-                                  })
-                                }
-                                placeholder={t(
-                                  'agents.workflow.builder.titlePlaceholder',
-                                )}
-                              />
-                            </FormField>
-
-                            {selectedNode.type === 'agent' && (
-                              <>
-                                <FormField
-                                  label={t('agents.workflow.builder.agentType')}
-                                >
-                                  <Select
-                                    value={
-                                      selectedNode.data.config?.agent_type ||
-                                      'classic'
-                                    }
-                                    onValueChange={(value) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          agent_type: value,
-                                        },
-                                      })
-                                    }
-                                  >
-                                    <SelectTrigger
-                                      size="field"
-                                      className="w-full"
-                                    >
-                                      <SelectValue
-                                        placeholder={t(
-                                          'agents.workflow.builder.agentTypePlaceholder',
-                                        )}
-                                      />
-                                    </SelectTrigger>
-                                    <SelectContent>
-                                      <SelectItem value="classic">
-                                        {t('agents.form.agentTypes.classic')}
-                                      </SelectItem>
-                                      <SelectItem value="research">
-                                        {t('agents.form.agentTypes.research')}
-                                      </SelectItem>
-                                    </SelectContent>
-                                  </Select>
-                                </FormField>
-                                <FormField
-                                  label={t('agents.workflow.builder.model')}
-                                >
-                                  <Select
-                                    value={
-                                      selectedNode.data.config?.model_id || ''
-                                    }
-                                    onValueChange={(value) => {
-                                      const selectedModel =
-                                        availableModels.find(
-                                          (m) => m.id === value,
-                                        );
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          model_id: value,
-                                          llm_name:
-                                            selectedModel?.provider || '',
-                                        },
-                                      });
-                                    }}
-                                  >
-                                    <SelectTrigger
-                                      size="field"
-                                      className="w-full"
-                                    >
-                                      <SelectValue
-                                        placeholder={t(
-                                          'agents.workflow.builder.modelPlaceholder',
-                                        )}
-                                      />
-                                    </SelectTrigger>
-                                    <SelectContent>
-                                      {(() => {
-                                        const builtin = availableModels.filter(
-                                          (m) => m.source !== 'user',
-                                        );
-                                        const user = availableModels.filter(
-                                          (m) => m.source === 'user',
-                                        );
-                                        return (
-                                          <>
-                                            {builtin.length > 0 && (
-                                              <SelectGroup>
-                                                <SelectLabel>
-                                                  {t(
-                                                    'settings.customModels.modelsGroup.builtin',
-                                                  )}
-                                                </SelectLabel>
-                                                {builtin.map((model) => (
-                                                  <SelectItem
-                                                    key={model.id}
-                                                    value={model.id}
-                                                  >
-                                                    {model.display_name} ·{' '}
-                                                    {model.provider}
-                                                  </SelectItem>
-                                                ))}
-                                              </SelectGroup>
-                                            )}
-                                            {user.length > 0 && (
-                                              <SelectGroup>
-                                                <SelectLabel>
-                                                  {t(
-                                                    'settings.customModels.modelsGroup.user',
-                                                  )}
-                                                </SelectLabel>
-                                                {user.map((model) => (
-                                                  <SelectItem
-                                                    key={model.id}
-                                                    value={model.id}
-                                                  >
-                                                    {model.display_name} ·{' '}
-                                                    {model.provider}
-                                                  </SelectItem>
-                                                ))}
-                                              </SelectGroup>
-                                            )}
-                                          </>
-                                        );
-                                      })()}
-                                    </SelectContent>
-                                  </Select>
-                                </FormField>
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.systemPrompt',
-                                  )}
-                                >
-                                  <Textarea
-                                    value={
-                                      selectedNode.data.config?.system_prompt ??
-                                      ''
-                                    }
-                                    onChange={(e) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          system_prompt: e.target.value,
-                                        },
-                                      })
-                                    }
-                                    rows={3}
-                                    placeholder={t(
-                                      'agents.workflow.builder.systemPromptPlaceholder',
-                                    )}
-                                  />
-                                </FormField>
-                                <PromptTextArea
-                                  label={t(
-                                    'agents.workflow.builder.promptTemplate',
-                                  )}
-                                  value={
-                                    selectedNode.data.config?.prompt_template ||
-                                    ''
-                                  }
-                                  onChange={(val) =>
-                                    handleUpdateNodeData({
-                                      config: {
-                                        ...(selectedNode.data.config || {}),
-                                        prompt_template: val,
-                                      },
-                                    })
-                                  }
-                                  nodes={nodes}
-                                  edges={edges}
-                                  selectedNodeId={selectedNode.id}
-                                  placeholder={t(
-                                    'agents.workflow.builder.promptTemplatePlaceholder',
-                                    {
-                                      ...NO_ESCAPE,
-                                      example: '{{ agent.variable }}',
-                                    },
-                                  )}
-                                />
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.outputVariable',
-                                  )}
-                                >
-                                  <Input
-                                    type="text"
-                                    value={
-                                      selectedNode.data.config
-                                        ?.output_variable || ''
-                                    }
-                                    onChange={(e) => {
-                                      const nextOutputVariable = e.target.value;
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          output_variable: nextOutputVariable,
-                                        },
-                                      });
-                                    }}
-                                    placeholder={t(
-                                      'agents.workflow.builder.outputVariablePlaceholder',
-                                    )}
-                                  />
-                                </FormField>
-                                <div className="flex items-center gap-2">
-                                  <Checkbox
-                                    id="stream_to_user"
-                                    checked={
-                                      selectedNode.data.config
-                                        ?.stream_to_user ?? true
-                                    }
-                                    onCheckedChange={(checked) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          stream_to_user: checked === true,
-                                        },
-                                      })
-                                    }
-                                  />
-                                  <label
-                                    htmlFor="stream_to_user"
-                                    className="text-foreground text-sm"
-                                  >
-                                    {t('agents.workflow.builder.streamToUser')}
-                                  </label>
-                                </div>{' '}
-                                <FormField
-                                  label={t('agents.form.sections.tools')}
-                                >
-                                  <MultiSelect
-                                    options={availableTools.map((tool) => ({
-                                      value: tool.id,
-                                      label: getToolDisplayName(tool),
-                                    }))}
-                                    selected={
-                                      selectedNode.data.config?.tools || []
-                                    }
-                                    onChange={(newTools) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          tools: newTools,
-                                        },
-                                      })
-                                    }
-                                    placeholder={t(
-                                      'agents.form.placeholders.selectTools',
-                                    )}
-                                    searchPlaceholder={t(
-                                      'agents.form.toolsPopup.searchPlaceholder',
-                                    )}
-                                    emptyText={t(
-                                      'agents.form.toolsPopup.noOptionsMessage',
-                                    )}
-                                  />
-                                </FormField>
-                                <FormField
-                                  label={t('agents.workflow.builder.sources')}
-                                >
-                                  <MultiSelect
-                                    options={sourceOptions}
-                                    selected={
-                                      selectedNode.data.config?.sources || []
-                                    }
-                                    onChange={(newSources) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          sources: newSources,
-                                        },
-                                      })
-                                    }
-                                    placeholder={t(
-                                      'agents.form.placeholders.selectSources',
-                                    )}
-                                    searchPlaceholder={t(
-                                      'agents.form.sourcePopup.searchPlaceholder',
-                                    )}
-                                    emptyText={t(
-                                      'agents.form.sourcePopup.noOptionsMessage',
-                                    )}
-                                  />
-                                </FormField>
-                                <NodeDocumentsControl
-                                  key={selectedNode.id}
-                                  value={
-                                    selectedNode.data.config?.input_documents ??
-                                    []
-                                  }
-                                  onChange={(nextInputDocuments) =>
-                                    handleUpdateNodeData({
-                                      config: {
-                                        ...(selectedNode.data.config || {}),
-                                        input_documents: nextInputDocuments,
-                                      },
-                                    })
-                                  }
-                                  options={selectedAgentDocumentOptions}
-                                  label={t('agents.workflow.builder.documents')}
-                                  helpText={t(
-                                    'agents.workflow.builder.documentsHint',
-                                  )}
-                                />
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.filePassing',
-                                  )}
-                                  hint={t(
-                                    'agents.workflow.builder.filePassingHint',
-                                  )}
-                                >
-                                  <Select
-                                    value={normalizeFilePassing(
-                                      selectedNode.data.config?.file_passing,
-                                    )}
-                                    onValueChange={(value) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          file_passing: value as FilePassing,
-                                        },
-                                      })
-                                    }
-                                  >
-                                    <SelectTrigger
-                                      size="field"
-                                      className="w-full"
-                                    >
-                                      <SelectValue />
-                                    </SelectTrigger>
-                                    <SelectContent>
-                                      {FILE_PASSING_OPTIONS.map((option) => (
-                                        <SelectItem
-                                          key={option.value}
-                                          value={option.value}
-                                        >
-                                          {t(
-                                            `agents.workflow.filePassing.${option.value}`,
-                                            { defaultValue: option.label },
-                                          )}
-                                        </SelectItem>
-                                      ))}
-                                    </SelectContent>
-                                  </Select>
-                                </FormField>
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.structuredOutput',
-                                  )}
-                                  hint={
-                                    [
-                                      !selectedAgentModelSupportsStructuredOutput
-                                        ? t(
-                                            'agents.workflow.builder.modelNoStructuredOutput',
-                                          )
-                                        : null,
-                                      selectedAgentJsonSchemaText.trim() !==
-                                        '' && !selectedAgentJsonSchemaError
-                                        ? t(
-                                            'agents.workflow.builder.validSchema',
-                                          )
-                                        : null,
-                                    ]
-                                      .filter(Boolean)
-                                      .join(' ') || undefined
-                                  }
-                                  error={
-                                    selectedAgentJsonSchemaText.trim() !== '' &&
-                                    selectedAgentJsonSchemaError
-                                      ? t(
-                                          'agents.workflow.builder.invalidSchema',
-                                          {
-                                            ...NO_ESCAPE,
-                                            error: schemaErrorText(
-                                              t,
-                                              selectedAgentJsonSchemaError,
-                                            ),
-                                          },
-                                        )
-                                      : undefined
-                                  }
-                                >
-                                  <Textarea
-                                    value={selectedAgentJsonSchemaText}
-                                    onChange={(e) =>
-                                      handleAgentJsonSchemaChange(
-                                        e.target.value,
-                                      )
-                                    }
-                                    className="font-mono"
-                                    rows={8}
-                                    placeholder={`{
-  "type": "object",
-  "properties": {
-    "summary": { "type": "string" }
-  },
-  "required": ["summary"]
-}`}
-                                  />
-                                </FormField>
-                              </>
-                            )}
-
-                            {selectedNode.type === 'note' && (
-                              <FormField
-                                label={t('agents.workflow.builder.noteContent')}
-                              >
-                                <Textarea
-                                  value={selectedNode.data.content || ''}
-                                  onChange={(e) =>
-                                    handleUpdateNodeData({
-                                      content: e.target.value,
-                                    })
-                                  }
-                                  rows={4}
-                                  placeholder={t(
-                                    'agents.workflow.builder.noteContentPlaceholder',
-                                  )}
-                                />
-                              </FormField>
-                            )}
-
-                            {selectedNode.type === 'state' && (
-                              <>
-                                <p className="text-muted-foreground text-xs">
-                                  {t('agents.workflow.builder.stateIntro')}
-                                </p>
-                                {(
-                                  selectedNode.data.config?.operations || []
-                                ).map(
-                                  (
-                                    op: {
-                                      expression: string;
-                                      target_variable: string;
-                                    },
-                                    idx: number,
-                                  ) => (
-                                    <Card
-                                      key={idx}
-                                      padding="sm"
-                                      className="gap-2"
-                                    >
-                                      <div className="flex items-center justify-between">
-                                        <span className="text-foreground text-sm font-medium">
-                                          {t(
-                                            'agents.workflow.builder.assignValue',
-                                          )}
-                                        </span>
-                                        {(
-                                          selectedNode.data.config
-                                            ?.operations || []
-                                        ).length > 1 && (
-                                          <IconButton
-                                            variant="ghost-destructive"
-                                            size="icon-xs"
-                                            label={t(
-                                              'agents.workflow.removeAssignment',
-                                              { index: idx + 1 },
-                                            )}
-                                            icon={Trash2}
-                                            onClick={() => {
-                                              const ops = [
-                                                ...(selectedNode.data.config
-                                                  ?.operations || []),
-                                              ];
-                                              ops.splice(idx, 1);
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  operations: ops,
-                                                },
-                                              });
-                                            }}
-                                          />
-                                        )}
-                                      </div>
-                                      <div className="flex flex-col gap-5">
-                                        <div className="flex flex-col gap-1">
-                                          <Textarea
-                                            value={op.expression}
-                                            onChange={(e) => {
-                                              const ops = [
-                                                ...(selectedNode.data.config
-                                                  ?.operations || []),
-                                              ];
-                                              ops[idx] = {
-                                                ...ops[idx],
-                                                expression: e.target.value,
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  operations: ops,
-                                                },
-                                              });
-                                            }}
-                                            rows={2}
-                                            placeholder="query"
-                                            aria-label={t(
-                                              'agents.workflow.expressionRow',
-                                              { index: idx + 1 },
-                                            )}
-                                          />
-                                          <p className="text-muted-foreground text-xs">
-                                            <Trans
-                                              i18nKey="agents.workflow.builder.celHint"
-                                              components={{ code: <code /> }}
-                                              values={{ braced: '{{query}}' }}
-                                            />{' '}
-                                            <Button
-                                              variant="link"
-                                              size="inline"
-                                              asChild
-                                              // eslint-disable-next-line shadcn/no-restyle -- a link in a 12px hint keeps the sentence's size and weight
-                                              className="text-xs font-normal"
-                                            >
-                                              <a
-                                                href="https://cel.dev/"
-                                                target="_blank"
-                                                rel="noreferrer"
-                                              >
-                                                {t(
-                                                  'agents.workflow.builder.learnMore',
-                                                )}
-                                              </a>
-                                            </Button>
-                                          </p>
-                                        </div>
-                                        <FormField
-                                          label={t(
-                                            'agents.workflow.builder.toVariable',
-                                          )}
-                                        >
-                                          <Input
-                                            type="text"
-                                            value={op.target_variable}
-                                            onChange={(e) => {
-                                              const ops = [
-                                                ...(selectedNode.data.config
-                                                  ?.operations || []),
-                                              ];
-                                              ops[idx] = {
-                                                ...ops[idx],
-                                                target_variable: e.target.value,
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  operations: ops,
-                                                },
-                                              });
-                                            }}
-                                            placeholder="variable_name"
-                                          />
-                                        </FormField>
-                                      </div>
-                                    </Card>
-                                  ),
-                                )}
-                                <Button
-                                  type="button"
-                                  variant="ghost-muted"
-                                  size="sm"
-                                  onClick={() => {
-                                    const ops = [
-                                      ...(selectedNode.data.config
-                                        ?.operations || []),
-                                      { expression: '', target_variable: '' },
-                                    ];
-                                    handleUpdateNodeData({
-                                      config: {
-                                        ...(selectedNode.data.config || {}),
-                                        operations: ops,
-                                      },
-                                    });
-                                  }}
-                                  className="self-start"
-                                >
-                                  <Plus className="size-3.5" />
-                                  {t('agents.form.buttons.add')}
-                                </Button>
-                              </>
-                            )}
-
-                            {selectedNode.type === 'condition' && (
-                              <>
-                                <p className="text-muted-foreground text-xs">
-                                  {t('agents.workflow.builder.conditionIntro')}
-                                </p>
-                                <div className="border-border bg-card flex gap-1 rounded-xl border p-1">
-                                  <Button
-                                    type="button"
-                                    variant={
-                                      (selectedNode.data.config?.mode ||
-                                        'simple') === 'simple'
-                                        ? 'outline'
-                                        : 'ghost-muted'
-                                    }
-                                    size="xs"
-                                    onClick={() =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          mode: 'simple',
-                                        },
-                                      })
-                                    }
-                                    className="flex-1"
-                                  >
-                                    {t('agents.workflow.builder.modeSimple')}
-                                  </Button>
-                                  <Button
-                                    type="button"
-                                    variant={
-                                      selectedNode.data.config?.mode ===
-                                      'advanced'
-                                        ? 'outline'
-                                        : 'ghost-muted'
-                                    }
-                                    size="xs"
-                                    onClick={() =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          mode: 'advanced',
-                                        },
-                                      })
-                                    }
-                                    className="flex-1"
-                                  >
-                                    {t('agents.workflow.builder.modeAdvanced')}
-                                  </Button>
-                                </div>
-
-                                {(selectedNode.data.config?.cases || []).map(
-                                  (c: ConditionCase, idx: number) => (
-                                    <Card
-                                      key={c.sourceHandle}
-                                      padding="sm"
-                                      className="gap-2"
-                                    >
-                                      <div className="flex items-center justify-between">
-                                        <span className="text-warning text-sm font-semibold">
-                                          {idx === 0
-                                            ? t('agents.workflow.nodes.if')
-                                            : t('agents.workflow.nodes.elseIf')}
-                                        </span>
-                                        {(selectedNode.data.config?.cases || [])
-                                          .length > 1 && (
-                                          <IconButton
-                                            variant="ghost-destructive"
-                                            size="icon-xs"
-                                            label={t(
-                                              'agents.workflow.removeCondition',
-                                              { index: idx + 1 },
-                                            )}
-                                            icon={Trash2}
-                                            onClick={() => {
-                                              const cases =
-                                                normalizeConditionCases([
-                                                  ...(selectedNode.data.config
-                                                    ?.cases || []),
-                                                ]);
-                                              const removedHandle =
-                                                cases[idx]?.sourceHandle;
-                                              cases.splice(idx, 1);
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  cases,
-                                                },
-                                              });
-                                              if (removedHandle) {
-                                                setEdges((eds) =>
-                                                  eds.filter(
-                                                    (edge) =>
-                                                      !(
-                                                        edge.source ===
-                                                          selectedNode.id &&
-                                                        edge.sourceHandle ===
-                                                          removedHandle
-                                                      ),
-                                                  ),
-                                                );
-                                              }
-                                            }}
-                                          />
-                                        )}
-                                      </div>
-                                      <Input
-                                        type="text"
-                                        value={c.name || ''}
-                                        onChange={(e) => {
-                                          const cases = [
-                                            ...(selectedNode.data.config
-                                              ?.cases || []),
-                                          ];
-                                          cases[idx] = {
-                                            ...cases[idx],
-                                            name: e.target.value,
-                                          };
-                                          handleUpdateNodeData({
-                                            config: {
-                                              ...(selectedNode.data.config ||
-                                                {}),
-                                              cases,
-                                            },
-                                          });
-                                        }}
-                                        placeholder={t(
-                                          'agents.workflow.builder.caseNamePlaceholder',
-                                        )}
-                                        aria-label={t(
-                                          'agents.workflow.conditionNameRow',
-                                          { index: idx + 1 },
-                                        )}
-                                      />
-                                      {(selectedNode.data.config?.mode ||
-                                        'simple') === 'simple' ? (
-                                        <div className="flex items-center gap-2">
-                                          <Input
-                                            type="text"
-                                            value={
-                                              parseSimpleCel(c.expression)
-                                                .variable
-                                            }
-                                            onChange={(e) => {
-                                              const parsed = parseSimpleCel(
-                                                c.expression,
-                                              );
-                                              const cases = [
-                                                ...(selectedNode.data.config
-                                                  ?.cases || []),
-                                              ];
-                                              cases[idx] = {
-                                                ...cases[idx],
-                                                expression: buildSimpleCel(
-                                                  e.target.value,
-                                                  parsed.operator,
-                                                  parsed.value,
-                                                ),
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  cases,
-                                                },
-                                              });
-                                            }}
-                                            placeholder={t(
-                                              'agents.workflow.builder.variablePlaceholder',
-                                            )}
-                                            aria-label={t(
-                                              'agents.workflow.conditionVariableRow',
-                                              { index: idx + 1 },
-                                            )}
-                                          />
-                                          <Select
-                                            value={
-                                              parseSimpleCel(c.expression)
-                                                .operator
-                                            }
-                                            onValueChange={(op) => {
-                                              const parsed = parseSimpleCel(
-                                                c.expression,
-                                              );
-                                              const cases = [
-                                                ...(selectedNode.data.config
-                                                  ?.cases || []),
-                                              ];
-                                              cases[idx] = {
-                                                ...cases[idx],
-                                                expression: buildSimpleCel(
-                                                  parsed.variable,
-                                                  op,
-                                                  parsed.value,
-                                                ),
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  cases,
-                                                },
-                                              });
-                                            }}
-                                          >
-                                            <SelectTrigger
-                                              size="field"
-                                              className="w-24 shrink-0"
-                                              aria-label={t(
-                                                'agents.workflow.conditionOperatorRow',
-                                                { index: idx + 1 },
-                                              )}
-                                            >
-                                              <SelectValue />
-                                            </SelectTrigger>
-                                            <SelectContent>
-                                              <SelectItem value="==">
-                                                =
-                                              </SelectItem>
-                                              <SelectItem value="!=">
-                                                !=
-                                              </SelectItem>
-                                              <SelectItem value=">">
-                                                &gt;
-                                              </SelectItem>
-                                              <SelectItem value="<">
-                                                &lt;
-                                              </SelectItem>
-                                              <SelectItem value=">=">
-                                                &gt;=
-                                              </SelectItem>
-                                              <SelectItem value="<=">
-                                                &lt;=
-                                              </SelectItem>
-                                              <SelectItem value="contains">
-                                                {t(
-                                                  'agents.workflow.builder.opContains',
-                                                )}
-                                              </SelectItem>
-                                              <SelectItem value="startsWith">
-                                                {t(
-                                                  'agents.workflow.builder.opStartsWith',
-                                                )}
-                                              </SelectItem>
-                                            </SelectContent>
-                                          </Select>
-                                          <Input
-                                            type="text"
-                                            value={
-                                              parseSimpleCel(c.expression).value
-                                            }
-                                            onChange={(e) => {
-                                              const parsed = parseSimpleCel(
-                                                c.expression,
-                                              );
-                                              const cases = [
-                                                ...(selectedNode.data.config
-                                                  ?.cases || []),
-                                              ];
-                                              cases[idx] = {
-                                                ...cases[idx],
-                                                expression: buildSimpleCel(
-                                                  parsed.variable,
-                                                  parsed.operator,
-                                                  e.target.value,
-                                                ),
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  cases,
-                                                },
-                                              });
-                                            }}
-                                            placeholder={t(
-                                              'agents.workflow.builder.valuePlaceholder',
-                                            )}
-                                            aria-label={t(
-                                              'agents.workflow.conditionValueRow',
-                                              { index: idx + 1 },
-                                            )}
-                                          />
-                                        </div>
-                                      ) : (
-                                        <FormField
-                                          label={t(
-                                            'agents.workflow.conditionRow',
-                                            { index: idx + 1 },
-                                          )}
-                                          hint={
-                                            <>
-                                              <Trans
-                                                i18nKey="agents.workflow.builder.celHint"
-                                                components={{ code: <code /> }}
-                                                values={{ braced: '{{query}}' }}
-                                              />{' '}
-                                              <Button
-                                                variant="link"
-                                                size="inline"
-                                                asChild
-                                                // eslint-disable-next-line shadcn/no-restyle -- a link in a 12px hint keeps the sentence's size and weight
-                                                className="text-xs font-normal"
-                                              >
-                                                <a
-                                                  href="https://cel.dev/"
-                                                  target="_blank"
-                                                  rel="noreferrer"
-                                                >
-                                                  {t(
-                                                    'agents.workflow.builder.learnMore',
-                                                  )}
-                                                </a>
-                                              </Button>
-                                            </>
-                                          }
-                                        >
-                                          <Textarea
-                                            value={c.expression}
-                                            onChange={(e) => {
-                                              const cases = [
-                                                ...(selectedNode.data.config
-                                                  ?.cases || []),
-                                              ];
-                                              cases[idx] = {
-                                                ...cases[idx],
-                                                expression: e.target.value,
-                                              };
-                                              handleUpdateNodeData({
-                                                config: {
-                                                  ...(selectedNode.data
-                                                    .config || {}),
-                                                  cases,
-                                                },
-                                              });
-                                            }}
-                                            rows={2}
-                                            placeholder={t(
-                                              'agents.workflow.builder.conditionPlaceholder',
-                                            )}
-                                          />
-                                        </FormField>
-                                      )}
-                                    </Card>
-                                  ),
-                                )}
-
-                                <Button
-                                  type="button"
-                                  variant="ghost-muted"
-                                  size="sm"
-                                  onClick={() => {
-                                    const cases = normalizeConditionCases([
-                                      ...(selectedNode.data.config?.cases ||
-                                        []),
-                                    ]);
-                                    const nextHandle =
-                                      getNextConditionHandle(cases);
-                                    cases.push({
-                                      name: '',
-                                      expression: '',
-                                      sourceHandle: nextHandle,
-                                    });
-                                    handleUpdateNodeData({
-                                      config: {
-                                        ...(selectedNode.data.config || {}),
-                                        cases,
-                                      },
-                                    });
-                                  }}
-                                  className="self-start"
-                                >
-                                  <Plus className="size-3.5" />
-                                  {t('agents.form.buttons.add')}
-                                </Button>
-                              </>
-                            )}
-
-                            {selectedNode.type === 'code' && (
-                              <>
-                                <p className="text-muted-foreground text-xs">
-                                  {t('agents.workflow.builder.codeIntro')}
-                                </p>
-                                <FormField
-                                  label={t('agents.workflow.nodes.code')}
-                                >
-                                  <Textarea
-                                    value={selectedNode.data.config?.code ?? ''}
-                                    onChange={(e) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          code: e.target.value,
-                                        },
-                                      })
-                                    }
-                                    className="font-mono"
-                                    rows={10}
-                                    spellCheck={false}
-                                    placeholder={'print("hello world")'}
-                                  />
-                                </FormField>
-                                <NodeDocumentsControl
-                                  key={selectedNode.id}
-                                  value={selectedNode.data.config?.inputs ?? []}
-                                  onChange={(nextInputs) =>
-                                    handleUpdateNodeData({
-                                      config: {
-                                        ...(selectedNode.data.config || {}),
-                                        inputs: nextInputs,
-                                      },
-                                    })
-                                  }
-                                  options={selectedCodeDocumentOptions}
-                                  label={t(
-                                    'agents.workflow.builder.inputFiles',
-                                  )}
-                                  helpText={t(
-                                    'agents.workflow.builder.inputFilesHint',
-                                  )}
-                                />
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.outputVariable',
-                                  )}
-                                >
-                                  <Input
-                                    type="text"
-                                    value={
-                                      selectedNode.data.config
-                                        ?.output_variable || ''
-                                    }
-                                    onChange={(e) =>
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          output_variable: e.target.value,
-                                        },
-                                      })
-                                    }
-                                    placeholder={t(
-                                      'agents.workflow.builder.outputVariablePlaceholder',
-                                    )}
-                                  />
-                                </FormField>
-                                <FormField
-                                  label={t('agents.workflow.builder.timeout')}
-                                >
-                                  <Input
-                                    type="number"
-                                    min={1}
-                                    value={
-                                      selectedNode.data.config?.timeout ?? ''
-                                    }
-                                    onChange={(e) => {
-                                      const raw = e.target.value;
-                                      const parsed =
-                                        raw.trim() === ''
-                                          ? undefined
-                                          : Number.parseInt(raw, 10);
-                                      handleUpdateNodeData({
-                                        config: {
-                                          ...(selectedNode.data.config || {}),
-                                          timeout:
-                                            parsed !== undefined &&
-                                            Number.isFinite(parsed)
-                                              ? parsed
-                                              : undefined,
-                                        },
-                                      });
-                                    }}
-                                    placeholder={t(
-                                      'agents.workflow.builder.optional',
-                                    )}
-                                  />
-                                </FormField>
-                                <FormField
-                                  label={t(
-                                    'agents.workflow.builder.structuredOutput',
-                                  )}
-                                  hint={
-                                    selectedCodeJsonSchemaText.trim() !== '' &&
-                                    !selectedCodeJsonSchemaError
-                                      ? t('agents.workflow.builder.validSchema')
-                                      : undefined
-                                  }
-                                  error={
-                                    selectedCodeJsonSchemaText.trim() !== '' &&
-                                    selectedCodeJsonSchemaError
-                                      ? t(
-                                          'agents.workflow.builder.invalidSchema',
-                                          {
-                                            ...NO_ESCAPE,
-                                            error: schemaErrorText(
-                                              t,
-                                              selectedCodeJsonSchemaError,
-                                            ),
-                                          },
-                                        )
-                                      : undefined
-                                  }
-                                >
-                                  <Textarea
-                                    value={selectedCodeJsonSchemaText}
-                                    onChange={(e) =>
-                                      handleCodeJsonSchemaChange(e.target.value)
-                                    }
-                                    className="font-mono"
-                                    rows={6}
-                                    placeholder={`{
-  "type": "object",
-  "properties": {
-    "result": { "type": "string" }
-  },
-  "required": ["result"]
-}`}
-                                  />
-                                </FormField>
-                              </>
-                            )}
-                          </>
-                        )}
-                    </div>
-
-                    <Button
-                      type="button"
-                      variant="destructive-outline"
-                      onClick={handleDeleteNode}
-                      disabled={selectedNode?.type === 'start'}
-                      shape="pill"
-                      className="w-full"
-                    >
-                      <Trash2 />
-                      {selectedNode?.type === 'start'
-                        ? t('agents.workflow.builder.cannotDeleteStart')
-                        : t('agents.workflow.builder.deleteNode')}
-                    </Button>
-                  </div>
-                </div>
-              </>
-            )}
-          </div>
+              )}
+              {selectedNode.type === 'state' && (
+                <StatePanel
+                  node={selectedNode}
+                  onUpdate={handleUpdateNodeData}
+                />
+              )}
+              {selectedNode.type === 'condition' && (
+                <ConditionPanel
+                  node={selectedNode}
+                  onUpdate={handleUpdateNodeData}
+                  onRemoveBranch={handleRemoveConditionBranch}
+                />
+              )}
+              {selectedNode.type === 'code' && (
+                <CodePanel
+                  node={selectedNode}
+                  onUpdate={handleUpdateNodeData}
+                  documentOptions={selectedCodeDocumentOptions}
+                  jsonSchemaText={selectedCodeJsonSchemaText}
+                  jsonSchemaError={selectedCodeJsonSchemaError}
+                  onJsonSchemaChange={handleCodeJsonSchemaChange}
+                />
+              )}
+            </NodePanel>
+          )}
         </div>
 
+        <WorkflowDetailsSheet
+          open={showDetails}
+          onOpenChange={setShowDetails}
+          details={{
+            name: workflowName,
+            description: workflowDescription,
+            allowPromptOverride: Boolean(
+              currentAgent.allow_system_prompt_override,
+            ),
+          }}
+          currentImage={currentAgentImage}
+          saving={detailsSaving}
+          errors={detailsSaveFailed ? publishErrors : []}
+          onSave={handleDetailsSave}
+        />
         <AgentPreviewSheet
           open={showPreview}
           onOpenChange={setShowPreview}
diff --git a/frontend/src/agents/workflow/WorkflowModelsContext.ts b/frontend/src/agents/workflow/WorkflowModelsContext.ts
new file mode 100644
index 00000000..eb6a6eb9
--- /dev/null
+++ b/frontend/src/agents/workflow/WorkflowModelsContext.ts
@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Model display names by model id, provided by the builder so the canvas
+ * nodes (rendered by React Flow, out of reach of props) can name a model.
+ */
+export const WorkflowModelsContext = createContext<Record<string, string>>({});
+
+/**
+ * A model's display name.
+ *
+ * Args:
+ *   modelId: The model id stored on the node.
+ *
+ * Returns:
+ *   The display name, the id itself when the model is unknown, or undefined
+ *   when no id is set.
+ */
+export function useModelDisplayName(
+  modelId: string | undefined,
+): string | undefined {
+  const names = useContext(WorkflowModelsContext);
+  if (!modelId) return undefined;
+  return names[modelId] || modelId;
+}
diff --git a/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx b/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
index 4ffc4876..658e0a96 100644
--- a/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
+++ b/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
@@ -66,7 +66,7 @@ export default function NodeDocumentsControl({
   return (
     <FormField label={label} hint={helpText} id={fieldId} float={false}>
       {/* The track is a plain wrapper: ToggleGroup takes layout only. */}
-      <div className="border-border bg-card rounded-xl border p-1">
+      <div className="bg-muted rounded-full p-1">
         <ToggleGroup
           id={fieldId}
           type="single"
@@ -121,7 +121,7 @@ export default function NodeDocumentsControl({
               onClick={addRef}
               className="shrink-0"
             >
-              <Plus className="size-3.5" />
+              <Plus />
               {t('agents.form.buttons.add')}
             </Button>
           </div>
diff --git a/frontend/src/agents/workflow/components/PromptTextArea.tsx b/frontend/src/agents/workflow/components/PromptTextArea.tsx
index 880d705f..7cb56c8e 100644
--- a/frontend/src/agents/workflow/components/PromptTextArea.tsx
+++ b/frontend/src/agents/workflow/components/PromptTextArea.tsx
@@ -337,6 +337,8 @@ interface PromptTextAreaProps {
   placeholder?: string;
   rows?: number;
   label?: string;
+  /** Surface behind the field, for the floating label's notch. */
+  labelSurface?: 'card' | 'background' | 'muted';
 }
 
 export default function PromptTextArea({
@@ -348,6 +350,7 @@ export default function PromptTextArea({
   placeholder,
   rows = 4,
   label,
+  labelSurface = 'card',
 }: PromptTextAreaProps) {
   const { t } = useTranslation();
   const textareaId = useId();
@@ -442,7 +445,7 @@ export default function PromptTextArea({
   // so typing keeps filtering it.
   const field = (
     <PopoverAnchor asChild>
-      <div className="border-border focus-within:border-ring focus-within:ring-ring/50 bg-card relative rounded-xl border transition-shadow focus-within:ring-3">
+      <div className="border-border focus-within:border-ring focus-within:ring-ring/50 relative rounded-xl border transition-shadow focus-within:ring-3">
         <div
           ref={overlayRef}
           aria-hidden
@@ -525,7 +528,7 @@ export default function PromptTextArea({
       }}
     >
       {label ? (
-        <FormField label={label} id={textareaId}>
+        <FormField label={label} id={textareaId} labelSurface={labelSurface}>
           {field}
         </FormField>
       ) : (
diff --git a/frontend/src/agents/workflow/components/WorkflowDetailsSheet.test.tsx b/frontend/src/agents/workflow/components/WorkflowDetailsSheet.test.tsx
new file mode 100644
index 00000000..61089e4e
--- /dev/null
+++ b/frontend/src/agents/workflow/components/WorkflowDetailsSheet.test.tsx
@@ -0,0 +1,113 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import WorkflowDetailsSheet from './WorkflowDetailsSheet';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const details = {
+  name: 'Helpdesk Triage',
+  description: 'Routes internal requests',
+  allowPromptOverride: false,
+};
+
+describe('WorkflowDetailsSheet', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = (props: { errors?: string[]; saving?: boolean } = {}) => {
+    const handlers = { onOpenChange: vi.fn(), onSave: vi.fn() };
+    act(() => {
+      root.render(
+        <WorkflowDetailsSheet
+          open
+          details={details}
+          currentImage=""
+          saving={props.saving ?? false}
+          errors={props.errors ?? []}
+          {...handlers}
+        />,
+      );
+    });
+    return handlers;
+  };
+
+  const button = (name: string) =>
+    Array.from(document.querySelectorAll('button')).find(
+      (b) => b.textContent === name,
+    ) as HTMLButtonElement;
+
+  const nameInput = () =>
+    document.querySelector('input[type="text"]') as HTMLInputElement;
+
+  const type = (input: HTMLInputElement, value: string) => {
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      'value',
+    )?.set;
+    act(() => {
+      setter?.call(input, value);
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+  };
+
+  it('opens with the workflow details filled in', () => {
+    render();
+    expect(document.body.textContent).toContain(
+      'agents.workflow.builder.detailsTitle',
+    );
+    expect(nameInput().value).toBe('Helpdesk Triage');
+    expect(document.querySelector('textarea')?.value).toBe(
+      'Routes internal requests',
+    );
+    expect(document.querySelector('[role="switch"]')).not.toBeNull();
+  });
+
+  it('keeps Save disabled until something changes, then saves the edits', () => {
+    const { onSave } = render();
+    const save = button('agents.form.buttons.save');
+    expect(save.disabled).toBe(true);
+
+    type(nameInput(), 'Helpdesk Router');
+    expect(save.disabled).toBe(false);
+
+    act(() => save.click());
+    expect(onSave).toHaveBeenCalledWith({
+      name: 'Helpdesk Router',
+      description: 'Routes internal requests',
+      allowPromptOverride: false,
+      imageFile: null,
+    });
+  });
+
+  it('closes on Cancel without saving', () => {
+    const { onOpenChange, onSave } = render();
+    type(nameInput(), 'Something else');
+    act(() => button('agents.form.buttons.cancel').click());
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  it('lists save errors in an alert inside the sheet', () => {
+    render({ errors: ['Workflow must have an end node'] });
+    const alert = document.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('agents.workflow.builder.unableSave');
+    expect(alert?.textContent).toContain('Workflow must have an end node');
+  });
+});
diff --git a/frontend/src/agents/workflow/components/WorkflowDetailsSheet.tsx b/frontend/src/agents/workflow/components/WorkflowDetailsSheet.tsx
new file mode 100644
index 00000000..84dc9e67
--- /dev/null
+++ b/frontend/src/agents/workflow/components/WorkflowDetailsSheet.tsx
@@ -0,0 +1,226 @@
+import { CircleX } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { FormField } from '@/components/ui/form-field';
+import { Input } from '@/components/ui/input';
+import { SectionHeader } from '@/components/ui/section-header';
+import { Separator } from '@/components/ui/separator';
+import { SettingRow } from '@/components/ui/setting-row';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetTitle,
+} from '@/components/ui/sheet';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+
+import { FileUpload } from '../../../components/FileUpload';
+
+export interface WorkflowDetailsValues {
+  name: string;
+  description: string;
+  allowPromptOverride: boolean;
+}
+
+export interface WorkflowDetailsSave extends WorkflowDetailsValues {
+  /** A newly picked avatar, or null to keep the current one. */
+  imageFile: File | null;
+}
+
+interface WorkflowDetailsSheetProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The builder's current values; the sheet edits a copy of them. */
+  details: WorkflowDetailsValues;
+  /** The saved avatar's URL, shown in the tile until a new one is picked. */
+  currentImage: string;
+  saving: boolean;
+  /** Errors from the last save started here, shown at the top of the body. */
+  errors: string[];
+  onSave: (values: WorkflowDetailsSave) => void;
+}
+
+/**
+ * The workflow's name, description, avatar and prompt-override setting, in a
+ * right drawer laid out like the classic agent's Basics on a phone.
+ *
+ * The sheet edits a copy: Cancel, the X, Escape and the scrim drop the edits,
+ * and Save hands them to the builder, which saves the workflow.
+ *
+ * Args:
+ *   open: Whether the sheet is open.
+ *   onOpenChange: Opens or closes the sheet.
+ *   details: The values to start from each time it opens.
+ *   currentImage: The saved avatar's URL.
+ *   saving: Whether a save started here is running.
+ *   errors: Errors from that save.
+ *   onSave: Receives the edited values.
+ */
+export default function WorkflowDetailsSheet({
+  open,
+  onOpenChange,
+  details,
+  currentImage,
+  saving,
+  errors,
+  onSave,
+}: WorkflowDetailsSheetProps) {
+  const { t } = useTranslation();
+  const [draft, setDraft] = useState<WorkflowDetailsValues>(details);
+  const [imageFile, setImageFile] = useState<File | null>(null);
+
+  // Start from the builder's values every time the sheet opens.
+  useEffect(() => {
+    if (!open) return;
+    setDraft(details);
+    setImageFile(null);
+    // Only on open: later changes to `details` come from this sheet's own save.
+  }, [open]);
+
+  const dirty =
+    imageFile !== null ||
+    draft.name !== details.name ||
+    draft.description !== details.description ||
+    draft.allowPromptOverride !== details.allowPromptOverride;
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        size="default"
+        className="p-0"
+        closeLabel={t('agents.close')}
+      >
+        <div className="flex min-h-0 flex-1 flex-col">
+          {/* pr-12 keeps the header clear of the close X at top-2 right-2. */}
+          <div className="flex flex-col gap-1 px-6 pt-6 pr-12 pb-4">
+            <SheetTitle>{t('agents.workflow.builder.detailsTitle')}</SheetTitle>
+            <SheetDescription>
+              {t('agents.workflow.builder.detailsDescription')}
+            </SheetDescription>
+          </div>
+          <Separator />
+          <div className="flex min-h-0 flex-1 flex-col gap-6 overflow-y-auto px-6 py-6">
+            {errors.length > 0 && (
+              <Alert variant="destructive">
+                <CircleX />
+                <AlertTitle>
+                  {t('agents.workflow.builder.unableSave')}
+                </AlertTitle>
+                <AlertDescription>
+                  <ul className="flex list-inside list-disc flex-col gap-1 wrap-break-word">
+                    {errors.map((error, index) => (
+                      <li key={index}>{error}</li>
+                    ))}
+                  </ul>
+                </AlertDescription>
+              </Alert>
+            )}
+            <Card variant="subtle" padding="lg" className="gap-5">
+              <SectionHeader
+                as="h3"
+                size="xs"
+                title={t('agents.form.sections.basics')}
+              />
+              {/* The phone layout of classic Basics: the avatar beside Name,
+                Description across the row. */}
+              <div className="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-5">
+                <FileUpload
+                  showPreview
+                  size="tile"
+                  tileSize="fixed"
+                  currentImage={currentImage || undefined}
+                  onUpload={(files) => setImageFile(files[0] ?? null)}
+                  onRemove={() => setImageFile(null)}
+                  uploadText={t('agents.form.labels.avatar')}
+                />
+                <FormField
+                  labelSurface="background"
+                  label={t('agents.form.labels.name')}
+                >
+                  <Input
+                    shape="pill"
+                    type="text"
+                    value={draft.name}
+                    placeholder={t(
+                      'agents.workflow.builder.workflowNamePlaceholder',
+                    )}
+                    onChange={(e) =>
+                      setDraft({ ...draft, name: e.target.value })
+                    }
+                  />
+                </FormField>
+                <FormField
+                  labelSurface="background"
+                  label={t('agents.form.labels.description')}
+                  className="col-span-2"
+                >
+                  <Textarea
+                    size="lg"
+                    className="h-32"
+                    placeholder={t(
+                      'agents.workflow.builder.workflowDescriptionPlaceholder',
+                    )}
+                    value={draft.description}
+                    onChange={(e) =>
+                      setDraft({ ...draft, description: e.target.value })
+                    }
+                  />
+                </FormField>
+              </div>
+            </Card>
+            <Card variant="subtle" padding="lg" className="gap-5">
+              <SectionHeader
+                as="h3"
+                size="xs"
+                title={t('agents.form.sections.advanced')}
+              />
+              <SettingRow
+                label={t('agents.form.advanced.systemPromptOverride')}
+                description={t(
+                  'agents.form.advanced.systemPromptOverrideDescription',
+                )}
+                htmlFor="workflow-system-prompt-override"
+              >
+                <Switch
+                  id="workflow-system-prompt-override"
+                  checked={draft.allowPromptOverride}
+                  onCheckedChange={(checked) =>
+                    setDraft({ ...draft, allowPromptOverride: checked })
+                  }
+                />
+              </SettingRow>
+            </Card>
+          </div>
+          <Separator />
+          <div className="flex justify-end gap-3 px-6 py-4">
+            <Button
+              type="button"
+              variant="ghost"
+              size="lg"
+              shape="pill"
+              onClick={() => onOpenChange(false)}
+            >
+              {t('agents.form.buttons.cancel')}
+            </Button>
+            <Button
+              type="button"
+              size="lg"
+              shape="pill"
+              disabled={!dirty}
+              loading={saving}
+              onClick={() => onSave({ ...draft, imageFile })}
+            >
+              {t('agents.form.buttons.save')}
+            </Button>
+          </div>
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/frontend/src/agents/workflow/nodeTones.test.ts b/frontend/src/agents/workflow/nodeTones.test.ts
new file mode 100644
index 00000000..940259ce
--- /dev/null
+++ b/frontend/src/agents/workflow/nodeTones.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { NODE_TONES, nodeToneClass, TONE_CLASSES } from './nodeTones';
+
+describe('nodeTones', () => {
+  it('maps every node type to one tone', () => {
+    expect(NODE_TONES).toEqual({
+      start: 'success',
+      agent: 'primary',
+      end: 'success',
+      note: 'warning',
+      state: 'info',
+      condition: 'warning',
+      code: 'info',
+    });
+  });
+
+  it('never paints End red', () => {
+    expect(nodeToneClass('end')).not.toMatch(/destructive/);
+    expect(nodeToneClass('end')).toBe('bg-success/10 text-success');
+  });
+
+  it('uses the brand soft fill for primary, not bg-primary/10', () => {
+    expect(TONE_CLASSES.primary).toBe('bg-secondary text-secondary-foreground');
+    expect(nodeToneClass('agent')).toBe(TONE_CLASSES.primary);
+  });
+
+  it('gives status tones their /10 fill and text', () => {
+    expect(TONE_CLASSES.info).toBe('bg-info/10 text-info');
+    expect(TONE_CLASSES.warning).toBe('bg-warning/10 text-warning');
+  });
+
+  it('falls back to a neutral tint for an unknown type', () => {
+    expect(nodeToneClass('mystery')).toBe(
+      'bg-muted-foreground/15 text-muted-foreground',
+    );
+  });
+});
diff --git a/frontend/src/agents/workflow/nodeTones.ts b/frontend/src/agents/workflow/nodeTones.ts
new file mode 100644
index 00000000..c5f91234
--- /dev/null
+++ b/frontend/src/agents/workflow/nodeTones.ts
@@ -0,0 +1,71 @@
+import {
+  Bot,
+  CodeXml,
+  Database,
+  Flag,
+  GitBranch,
+  Play,
+  StickyNote,
+  type LucideIcon,
+} from 'lucide-react';
+
+/** The node types the builder draws. */
+export type WorkflowNodeType =
+  'start' | 'agent' | 'end' | 'note' | 'state' | 'condition' | 'code';
+
+/** A node's colour role: the brand tint or one status tint. */
+export type NodeTone = 'primary' | 'success' | 'warning' | 'info';
+
+/**
+ * One colour per node type, read by the palette, every canvas node and the
+ * settings panel's header. Start and End share `success` as the two ends of
+ * the flow; `destructive` is kept for errors, so End is never red.
+ */
+export const NODE_TONES: Record<WorkflowNodeType, NodeTone> = {
+  start: 'success',
+  agent: 'primary',
+  end: 'success',
+  note: 'warning',
+  state: 'info',
+  condition: 'warning',
+  code: 'info',
+};
+
+// Whole class strings per tone so Tailwind sees them. Brand is the soft
+// `secondary` fill (never bg-primary/10); status tones are the /10 fill.
+export const TONE_CLASSES: Record<NodeTone, string> = {
+  primary: 'bg-secondary text-secondary-foreground',
+  success: 'bg-success/10 text-success',
+  warning: 'bg-warning/10 text-warning',
+  info: 'bg-info/10 text-info',
+};
+
+const NEUTRAL_TONE_CLASS = 'bg-muted-foreground/15 text-muted-foreground';
+
+/**
+ * The icon-square classes for a node type.
+ *
+ * Args:
+ *   type: The node's type.
+ *
+ * Returns:
+ *   The tone's fill and text classes, or a neutral tint for an unknown type.
+ */
+export function nodeToneClass(type: string | undefined): string {
+  const tone = NODE_TONES[type as WorkflowNodeType];
+  return tone ? TONE_CLASSES[tone] : NEUTRAL_TONE_CLASS;
+}
+
+/** Each node type's icon and its name's locale key. */
+export const NODE_META: Record<
+  WorkflowNodeType,
+  { icon: LucideIcon; labelKey: string }
+> = {
+  start: { icon: Play, labelKey: 'agents.workflow.nodes.start' },
+  agent: { icon: Bot, labelKey: 'agents.workflow.builder.aiAgent' },
+  end: { icon: Flag, labelKey: 'agents.workflow.nodes.end' },
+  note: { icon: StickyNote, labelKey: 'agents.workflow.nodes.note' },
+  state: { icon: Database, labelKey: 'agents.workflow.nodes.setState' },
+  condition: { icon: GitBranch, labelKey: 'agents.workflow.nodes.condition' },
+  code: { icon: CodeXml, labelKey: 'agents.workflow.nodes.code' },
+};
diff --git a/frontend/src/agents/workflow/nodes/BaseNode.tsx b/frontend/src/agents/workflow/nodes/BaseNode.tsx
index e24ecf3f..7f832213 100644
--- a/frontend/src/agents/workflow/nodes/BaseNode.tsx
+++ b/frontend/src/agents/workflow/nodes/BaseNode.tsx
@@ -3,11 +3,14 @@ import { Handle, Position } from 'reactflow';
 
 import { cn } from '@/lib/utils';
 
+import { nodeToneClass, type WorkflowNodeType } from '../nodeTones';
+
 interface BaseNodeProps {
   title: string;
   children?: ReactNode;
   selected?: boolean;
-  type?: 'start' | 'end' | 'default' | 'state' | 'agent' | 'condition' | 'code';
+  /** The node type; picks the icon square's tone from the shared map. */
+  type: WorkflowNodeType;
   icon?: ReactNode;
   handles?: {
     source?: boolean;
@@ -15,47 +18,25 @@ interface BaseNodeProps {
   };
 }
 
+/**
+ * The pill every canvas node but Note and If / Else is drawn as: a tinted
+ * icon, the title, a muted meta block and the handles. Selected is the focus
+ * ring look (`border-primary ring-3 ring-ring/50`), with no scale, so the
+ * node stays put under the pointer.
+ */
 export const BaseNode: React.FC<BaseNodeProps> = ({
   title,
   children,
   selected,
-  type = 'default',
+  type,
   icon,
   handles = { source: true, target: true },
 }) => {
-  let bgColor = 'bg-card';
-  let borderColor = 'border-border';
-  let iconBg = 'bg-muted';
-  let iconColor = 'text-muted-foreground';
-
-  if (selected) {
-    borderColor = 'border-primary ring-2 ring-primary';
-  }
-
-  if (type === 'start') {
-    iconBg = 'bg-success/10';
-    iconColor = 'text-success';
-  } else if (type === 'end') {
-    iconBg = 'bg-destructive/10';
-    iconColor = 'text-destructive';
-  } else if (type === 'state') {
-    iconBg = 'bg-muted';
-    iconColor = 'text-muted-foreground';
-  } else if (type === 'condition') {
-    iconBg = 'bg-warning/10';
-    iconColor = 'text-warning';
-  } else if (type === 'code') {
-    iconBg = 'bg-info/10';
-    iconColor = 'text-info';
-  }
-
   return (
     <div
       className={cn(
-        'rounded-full border shadow-md transition hover:shadow-lg',
-        bgColor,
-        borderColor,
-        selected && 'scale-105',
+        'bg-card rounded-full border shadow-md transition hover:shadow-lg',
+        selected ? 'border-primary ring-ring/50 ring-3' : 'border-border',
         'max-w-[250px] min-w-[180px]',
       )}
     >
@@ -72,8 +53,7 @@ export const BaseNode: React.FC<BaseNodeProps> = ({
         <div
           className={cn(
             'flex size-10 shrink-0 items-center justify-center rounded-full',
-            iconBg,
-            iconColor,
+            nodeToneClass(type),
           )}
         >
           {icon}
diff --git a/frontend/src/agents/workflow/nodes/CodeNode.tsx b/frontend/src/agents/workflow/nodes/CodeNode.tsx
index edb4731f..259b95cf 100644
--- a/frontend/src/agents/workflow/nodes/CodeNode.tsx
+++ b/frontend/src/agents/workflow/nodes/CodeNode.tsx
@@ -5,9 +5,7 @@ import { NodeProps } from 'reactflow';
 
 import { CodeNodeConfig } from '../../types/workflow';
 import { BaseNode } from './BaseNode';
-
-// Variable names are the user's own text: React escapes on render.
-const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
+import OutputVariableLine from './OutputVariableLine';
 
 type CodeNodeData = {
   title?: string;
@@ -46,18 +44,7 @@ const CodeNode = ({ data, selected }: NodeProps<CodeNodeData>) => {
           </div>
         )}
         {config.output_variable && (
-          <div
-            className="text-muted-foreground truncate text-xs"
-            title={t('agents.workflow.nodes.output', {
-              ...NO_ESCAPE,
-              variable: config.output_variable,
-            })}
-          >
-            {t('agents.workflow.nodes.output', {
-              ...NO_ESCAPE,
-              variable: config.output_variable,
-            })}
-          </div>
+          <OutputVariableLine variable={config.output_variable} />
         )}
       </div>
     </BaseNode>
diff --git a/frontend/src/agents/workflow/nodes/ConditionNode.tsx b/frontend/src/agents/workflow/nodes/ConditionNode.tsx
index cdbabeac..e73a5a12 100644
--- a/frontend/src/agents/workflow/nodes/ConditionNode.tsx
+++ b/frontend/src/agents/workflow/nodes/ConditionNode.tsx
@@ -6,6 +6,7 @@ import { Handle, NodeProps, Position } from 'reactflow';
 import { cn } from '@/lib/utils';
 
 import { ConditionCase } from '../../types/workflow';
+import { nodeToneClass } from '../nodeTones';
 
 type ConditionNodeData = {
   label?: string;
@@ -44,7 +45,7 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
       className={cn(
         'bg-card relative rounded-2xl border shadow-md transition',
         selected
-          ? 'border-primary ring-primary scale-105 ring-2'
+          ? 'border-primary ring-ring/50 ring-3'
           : 'border-border hover:shadow-lg',
       )}
       style={{ minWidth: 180, maxWidth: 220, height }}
@@ -57,7 +58,12 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
       />
 
       <div className="flex items-center gap-3 px-3 py-2">
-        <div className="bg-warning/10 text-warning flex size-9 shrink-0 items-center justify-center rounded-full">
+        <div
+          className={cn(
+            'flex size-9 shrink-0 items-center justify-center rounded-full',
+            nodeToneClass('condition'),
+          )}
+        >
           <GitBranch className="size-3.5" />
         </div>
         <div className="min-w-0 flex-1 pr-2">
@@ -69,8 +75,8 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
           </div>
           <div className="text-muted-foreground text-xs">
             {data.config?.mode === 'advanced'
-              ? t('agents.workflow.nodes.modeAdvanced')
-              : t('agents.workflow.nodes.modeSimple')}
+              ? t('agents.workflow.builder.modeAdvanced')
+              : t('agents.workflow.builder.modeSimple')}
           </div>
         </div>
       </div>
diff --git a/frontend/src/agents/workflow/nodes/OutputVariableLine.tsx b/frontend/src/agents/workflow/nodes/OutputVariableLine.tsx
new file mode 100644
index 00000000..e6bc4ece
--- /dev/null
+++ b/frontend/src/agents/workflow/nodes/OutputVariableLine.tsx
@@ -0,0 +1,25 @@
+import { ArrowRight } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+// Variable names are the user's own text: React escapes on render.
+const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
+
+/**
+ * A node's output variable on the canvas: an arrow, then the name in mono,
+ * because it is what the next node reads.
+ *
+ * Args:
+ *   variable: The output variable's name.
+ */
+export default function OutputVariableLine({ variable }: { variable: string }) {
+  const { t } = useTranslation();
+  return (
+    <div
+      className="text-muted-foreground flex min-w-0 items-center gap-1 text-xs"
+      title={t('agents.workflow.nodes.output', { ...NO_ESCAPE, variable })}
+    >
+      <ArrowRight className="size-3 shrink-0" aria-hidden="true" />
+      <span className="truncate font-mono">{variable}</span>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/nodes/index.tsx b/frontend/src/agents/workflow/nodes/index.tsx
index d1a8c10c..fa16fcd2 100644
--- a/frontend/src/agents/workflow/nodes/index.tsx
+++ b/frontend/src/agents/workflow/nodes/index.tsx
@@ -4,14 +4,14 @@ import { useTranslation } from 'react-i18next';
 
 import { cn } from '@/lib/utils';
 
+import { nodeToneClass } from '../nodeTones';
+import { useModelDisplayName } from '../WorkflowModelsContext';
 import { BaseNode } from './BaseNode';
+import OutputVariableLine from './OutputVariableLine';
 import CodeNode from './CodeNode';
 import ConditionNode from './ConditionNode';
 import SetStateNode from './SetStateNode';
 
-// Variable names are the user's own text: React escapes on render.
-const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
-
 export const StartNode = memo(function StartNode({
   selected,
 }: {
@@ -73,6 +73,12 @@ export const AgentNode = memo(function AgentNode({
   const { t } = useTranslation();
   const title = data.title || data.label || t('agents.workflow.nodes.agent');
   const config = data.config || {};
+  const modelName = useModelDisplayName(config.model_id);
+  const agentType =
+    config.agent_type === 'research' || config.agent_type === 'classic'
+      ? t(`agents.form.agentTypes.${config.agent_type}`)
+      : config.agent_type;
+  const meta = [agentType, modelName].filter(Boolean).join(' · ');
   return (
     <BaseNode
       title={title}
@@ -81,35 +87,13 @@ export const AgentNode = memo(function AgentNode({
       icon={<Bot className="size-4" />}
     >
       <div className="flex flex-col gap-1">
-        {config.agent_type && (
-          <div
-            className="text-muted-foreground truncate text-xs"
-            title={config.agent_type}
-          >
-            {config.agent_type}
-          </div>
-        )}
-        {config.model_id && (
-          <div
-            className="text-primary truncate text-xs"
-            title={config.model_id}
-          >
-            {config.model_id}
+        {meta && (
+          <div className="text-muted-foreground truncate text-xs" title={meta}>
+            {meta}
           </div>
         )}
         {config.output_variable && (
-          <div
-            className="text-muted-foreground truncate text-xs"
-            title={t('agents.workflow.nodes.output', {
-              ...NO_ESCAPE,
-              variable: config.output_variable,
-            })}
-          >
-            {t('agents.workflow.nodes.output', {
-              ...NO_ESCAPE,
-              variable: config.output_variable,
-            })}
-          </div>
+          <OutputVariableLine variable={config.output_variable} />
         )}
       </div>
     </BaseNode>
@@ -138,12 +122,17 @@ export const NoteNode = memo(function NoteNode({
         // over it as a flat gradient, so the canvas grid doesn't show through.
         'bg-card from-warning/10 to-warning/10 max-w-[250px] rounded-3xl border bg-linear-to-b px-5 py-3 shadow-md transition',
         selected
-          ? 'border-warning ring-warning scale-105 ring-2'
+          ? 'border-warning ring-warning/50 ring-3'
           : 'border-warning/50 hover:shadow-lg',
       )}
     >
       <div className="flex items-start gap-3">
-        <div className="bg-warning/15 text-warning flex size-10 shrink-0 items-center justify-center rounded-full">
+        <div
+          className={cn(
+            'flex size-10 shrink-0 items-center justify-center rounded-full',
+            nodeToneClass('note'),
+          )}
+        >
           <StickyNote className="size-4.5" />
         </div>
         <div className="min-w-0 flex-1">
diff --git a/frontend/src/agents/workflow/panels/AgentPanel.test.tsx b/frontend/src/agents/workflow/panels/AgentPanel.test.tsx
new file mode 100644
index 00000000..2d63f351
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/AgentPanel.test.tsx
@@ -0,0 +1,138 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { type Node } from 'reactflow';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import AgentPanel from './AgentPanel';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeNode = (config: Record<string, unknown> = {}): Node => ({
+  id: 'agent_1',
+  type: 'agent',
+  position: { x: 0, y: 0 },
+  data: {
+    title: 'Classify',
+    config: {
+      agent_type: 'classic',
+      system_prompt: '',
+      prompt_template: '',
+      stream_to_user: true,
+      sources: [],
+      tools: [],
+      ...config,
+    },
+  },
+});
+
+describe('AgentPanel', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = (node: Node, jsonSchemaText = '') => {
+    const onUpdate = vi.fn();
+    act(() => {
+      root.render(
+        <AgentPanel
+          node={node}
+          onUpdate={onUpdate}
+          nodes={[node]}
+          edges={[]}
+          availableModels={[]}
+          availableTools={[]}
+          sourceOptions={[]}
+          documentOptions={[]}
+          jsonSchemaText={jsonSchemaText}
+          jsonSchemaError={null}
+          modelSupportsStructuredOutput
+          onJsonSchemaChange={vi.fn()}
+        />,
+      );
+    });
+    return { onUpdate };
+  };
+
+  const advancedToggle = () =>
+    Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes('agents.workflow.builder.advancedSettings'),
+    ) as HTMLButtonElement;
+
+  it('groups the fields under Model, Prompt, Knowledge and Output', () => {
+    render(makeNode());
+    const headings = Array.from(container.querySelectorAll('h3')).map(
+      (h) => h.textContent,
+    );
+    expect(headings).toEqual([
+      'agents.form.sections.model',
+      'agents.form.sections.prompt',
+      'agents.workflow.builder.knowledge',
+      'agents.workflow.builder.output',
+    ]);
+  });
+
+  it('stacks Agent type and Model at full width in the narrow panel', () => {
+    render(makeNode());
+    const modelSection = container.querySelector('section')!;
+    expect(modelSection.querySelector('.grid')).toBeNull();
+    const triggers = modelSection.querySelectorAll('[role="combobox"]');
+    expect(triggers).toHaveLength(2);
+    triggers.forEach((trigger) =>
+      expect(trigger.className).toContain('w-full'),
+    );
+  });
+
+  it('streams through a Switch with a description, not a Checkbox', () => {
+    const { onUpdate } = render(makeNode());
+    expect(container.querySelector('[role="checkbox"]')).toBeNull();
+    const toggle = container.querySelector(
+      '[role="switch"]',
+    ) as HTMLButtonElement;
+    expect(toggle.getAttribute('aria-checked')).toBe('true');
+    expect(container.textContent).toContain(
+      'agents.workflow.builder.streamToUserDescription',
+    );
+    act(() => toggle.click());
+    expect(onUpdate).toHaveBeenCalledWith({
+      config: expect.objectContaining({ stream_to_user: false }),
+    });
+  });
+
+  it('keeps advanced settings closed when none is set', () => {
+    render(makeNode());
+    const toggle = advancedToggle();
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+    expect(container.textContent).not.toContain(
+      'agents.workflow.builder.filePassing',
+    );
+    act(() => toggle.click());
+    expect(toggle.getAttribute('aria-expanded')).toBe('true');
+    expect(container.textContent).toContain(
+      'agents.workflow.builder.filePassing',
+    );
+  });
+
+  it('opens advanced settings when one of them is set', () => {
+    render(makeNode({ file_passing: 'native' }));
+    expect(advancedToggle().getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('opens advanced settings when a schema is present', () => {
+    render(makeNode({ json_schema: { type: 'object' } }), '{"type":"object"}');
+    expect(advancedToggle().getAttribute('aria-expanded')).toBe('true');
+  });
+});
diff --git a/frontend/src/agents/workflow/panels/AgentPanel.tsx b/frontend/src/agents/workflow/panels/AgentPanel.tsx
new file mode 100644
index 00000000..b7ddfc89
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/AgentPanel.tsx
@@ -0,0 +1,403 @@
+import { ChevronRight } from 'lucide-react';
+import { useId, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { type Edge, type Node } from 'reactflow';
+
+import { Button } from '@/components/ui/button';
+import { FormField } from '@/components/ui/form-field';
+import { Input } from '@/components/ui/input';
+import { MultiSelect } from '@/components/ui/multi-select';
+import { SectionHeader } from '@/components/ui/section-header';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { SettingRow, SettingRows } from '@/components/ui/setting-row';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { cn } from '@/lib/utils';
+
+import { getToolDisplayName } from '../../../utils/toolUtils';
+import NodeDocumentsControl from '../components/NodeDocumentsControl';
+import PromptTextArea from '../components/PromptTextArea';
+import {
+  DEFAULT_FILE_PASSING,
+  FILE_PASSING_OPTIONS,
+  FilePassing,
+  normalizeFilePassing,
+} from '../documentConfig';
+import { NO_ESCAPE, schemaErrorText, type UserTool } from '../workflowHelpers';
+import { type NodePanelBodyProps } from './types';
+
+import type { Model } from '../../../models/types';
+
+interface AgentPanelProps extends NodePanelBodyProps {
+  nodes: Node[];
+  edges: Edge[];
+  availableModels: Model[];
+  availableTools: UserTool[];
+  sourceOptions: { value: string; label: string }[];
+  /** Upstream file variables the agent can read. */
+  documentOptions: { value: string; label: string }[];
+  /** The structured-output schema as typed. */
+  jsonSchemaText: string;
+  /** The schema's validation fragment, or null. */
+  jsonSchemaError: string | null;
+  /** False when the picked model can't return structured output. */
+  modelSupportsStructuredOutput: boolean;
+  onJsonSchemaChange: (text: string) => void;
+}
+
+const SCHEMA_PLACEHOLDER = `{
+  "type": "object",
+  "properties": {
+    "summary": { "type": "string" }
+  },
+  "required": ["summary"]
+}`;
+
+/**
+ * Whether any advanced setting (documents, file passing, structured output)
+ * differs from its default, so the disclosure opens on its own.
+ *
+ * Args:
+ *   config: The agent node's config.
+ *   jsonSchemaText: The schema as typed.
+ *   jsonSchemaError: The schema's validation fragment, or null.
+ *
+ * Returns:
+ *   True when the advanced settings should start open.
+ */
+export function hasAdvancedAgentSettings(
+  config: Record<string, unknown> | undefined,
+  jsonSchemaText: string,
+  jsonSchemaError: string | null,
+): boolean {
+  const inputDocuments = config?.input_documents;
+  return (
+    (Array.isArray(inputDocuments) && inputDocuments.length > 0) ||
+    normalizeFilePassing(config?.file_passing) !== DEFAULT_FILE_PASSING ||
+    (config?.json_schema !== undefined && config?.json_schema !== null) ||
+    jsonSchemaText.trim() !== '' ||
+    Boolean(jsonSchemaError)
+  );
+}
+
+/**
+ * Settings for an AI Agent node, grouped Model, Prompt, Knowledge and Output
+ * like classic Overview, with documents, file passing and structured output
+ * under an Advanced settings disclosure.
+ */
+export default function AgentPanel({
+  node,
+  onUpdate,
+  nodes,
+  edges,
+  availableModels,
+  availableTools,
+  sourceOptions,
+  documentOptions,
+  jsonSchemaText,
+  jsonSchemaError,
+  modelSupportsStructuredOutput,
+  onJsonSchemaChange,
+}: AgentPanelProps) {
+  const { t } = useTranslation();
+  const streamId = useId();
+  const config = node.data.config || {};
+  const [advancedOpen, setAdvancedOpen] = useState(() =>
+    hasAdvancedAgentSettings(config, jsonSchemaText, jsonSchemaError),
+  );
+
+  const updateConfig = (patch: Record<string, unknown>) =>
+    onUpdate({ config: { ...(node.data.config || {}), ...patch } });
+
+  const builtinModels = availableModels.filter((m) => m.source !== 'user');
+  const userModels = availableModels.filter((m) => m.source === 'user');
+  const schemaInvalid = jsonSchemaText.trim() !== '' && jsonSchemaError;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <section className="flex flex-col gap-5">
+        <SectionHeader
+          as="h3"
+          size="xs"
+          title={t('agents.form.sections.model')}
+        />
+        <div className="flex flex-col gap-5">
+          <FormField
+            label={t('agents.workflow.builder.agentType')}
+            labelSurface="background"
+          >
+            <Select
+              value={config.agent_type || 'classic'}
+              onValueChange={(value) => updateConfig({ agent_type: value })}
+            >
+              <SelectTrigger size="field" className="w-full">
+                <SelectValue
+                  placeholder={t(
+                    'agents.workflow.builder.agentTypePlaceholder',
+                  )}
+                />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="classic">
+                  {t('agents.form.agentTypes.classic')}
+                </SelectItem>
+                <SelectItem value="research">
+                  {t('agents.form.agentTypes.research')}
+                </SelectItem>
+              </SelectContent>
+            </Select>
+          </FormField>
+          <FormField
+            label={t('agents.workflow.builder.model')}
+            labelSurface="background"
+          >
+            <Select
+              value={config.model_id || ''}
+              onValueChange={(value) =>
+                updateConfig({
+                  model_id: value,
+                  llm_name:
+                    availableModels.find((m) => m.id === value)?.provider || '',
+                })
+              }
+            >
+              <SelectTrigger size="field" className="w-full">
+                <SelectValue
+                  placeholder={t('agents.workflow.builder.modelPlaceholder')}
+                />
+              </SelectTrigger>
+              <SelectContent>
+                {builtinModels.length > 0 && (
+                  <SelectGroup>
+                    <SelectLabel>
+                      {t('settings.customModels.modelsGroup.builtin')}
+                    </SelectLabel>
+                    {builtinModels.map((model) => (
+                      <SelectItem key={model.id} value={model.id}>
+                        {model.display_name} · {model.provider}
+                      </SelectItem>
+                    ))}
+                  </SelectGroup>
+                )}
+                {userModels.length > 0 && (
+                  <SelectGroup>
+                    <SelectLabel>
+                      {t('settings.customModels.modelsGroup.user')}
+                    </SelectLabel>
+                    {userModels.map((model) => (
+                      <SelectItem key={model.id} value={model.id}>
+                        {model.display_name} · {model.provider}
+                      </SelectItem>
+                    ))}
+                  </SelectGroup>
+                )}
+              </SelectContent>
+            </Select>
+          </FormField>
+        </div>
+      </section>
+
+      <section className="flex flex-col gap-5">
+        <SectionHeader
+          as="h3"
+          size="xs"
+          title={t('agents.form.sections.prompt')}
+        />
+        <FormField
+          label={t('agents.workflow.builder.systemPrompt')}
+          labelSurface="background"
+        >
+          <Textarea
+            value={config.system_prompt ?? ''}
+            onChange={(e) => updateConfig({ system_prompt: e.target.value })}
+            rows={3}
+            placeholder={t('agents.workflow.builder.systemPromptPlaceholder')}
+          />
+        </FormField>
+        <PromptTextArea
+          label={t('agents.workflow.builder.promptTemplate')}
+          labelSurface="background"
+          value={config.prompt_template || ''}
+          onChange={(val) => updateConfig({ prompt_template: val })}
+          nodes={nodes}
+          edges={edges}
+          selectedNodeId={node.id}
+          placeholder={t('agents.workflow.builder.promptTemplatePlaceholder', {
+            ...NO_ESCAPE,
+            example: '{{ agent.variable }}',
+          })}
+        />
+      </section>
+
+      <section className="flex flex-col gap-5">
+        <SectionHeader
+          as="h3"
+          size="xs"
+          title={t('agents.workflow.builder.knowledge')}
+        />
+        <FormField
+          label={t('agents.workflow.builder.sources')}
+          labelSurface="background"
+        >
+          <MultiSelect
+            options={sourceOptions}
+            selected={config.sources || []}
+            onChange={(newSources) => updateConfig({ sources: newSources })}
+            placeholder={t('agents.form.placeholders.selectSources')}
+            searchPlaceholder={t('agents.form.sourcePopup.searchPlaceholder')}
+            emptyText={t('agents.form.sourcePopup.noOptionsMessage')}
+          />
+        </FormField>
+        <FormField
+          label={t('agents.form.sections.tools')}
+          labelSurface="background"
+        >
+          <MultiSelect
+            options={availableTools.map((tool) => ({
+              value: tool.id,
+              label: getToolDisplayName(tool),
+            }))}
+            selected={config.tools || []}
+            onChange={(newTools) => updateConfig({ tools: newTools })}
+            placeholder={t('agents.form.placeholders.selectTools')}
+            searchPlaceholder={t('agents.form.toolsPopup.searchPlaceholder')}
+            emptyText={t('agents.form.toolsPopup.noOptionsMessage')}
+          />
+        </FormField>
+      </section>
+
+      <section className="flex flex-col gap-5">
+        <SectionHeader
+          as="h3"
+          size="xs"
+          title={t('agents.workflow.builder.output')}
+        />
+        <FormField
+          label={t('agents.workflow.builder.outputVariable')}
+          labelSurface="background"
+        >
+          <Input
+            type="text"
+            value={config.output_variable || ''}
+            onChange={(e) => updateConfig({ output_variable: e.target.value })}
+            placeholder={t('agents.workflow.builder.outputVariablePlaceholder')}
+          />
+        </FormField>
+        <SettingRows>
+          <SettingRow
+            label={t('agents.workflow.builder.streamToUser')}
+            description={t('agents.workflow.builder.streamToUserDescription')}
+            htmlFor={streamId}
+          >
+            <Switch
+              id={streamId}
+              checked={config.stream_to_user ?? true}
+              onCheckedChange={(checked) =>
+                updateConfig({ stream_to_user: checked })
+              }
+            />
+          </SettingRow>
+        </SettingRows>
+      </section>
+
+      <div className="flex flex-col gap-5">
+        <Button
+          type="button"
+          variant="link"
+          size="sm"
+          aria-expanded={advancedOpen}
+          onClick={() => setAdvancedOpen((open) => !open)}
+          className="-ml-3 w-fit justify-start"
+        >
+          <ChevronRight
+            aria-hidden="true"
+            className={cn(
+              'transition-transform duration-200',
+              advancedOpen && 'rotate-90',
+            )}
+          />
+          {t('agents.workflow.builder.advancedSettings')}
+        </Button>
+        {advancedOpen && (
+          <div className="flex flex-col gap-5">
+            <NodeDocumentsControl
+              key={node.id}
+              value={config.input_documents ?? []}
+              onChange={(nextInputDocuments) =>
+                updateConfig({ input_documents: nextInputDocuments })
+              }
+              options={documentOptions}
+              label={t('agents.workflow.builder.documents')}
+              helpText={t('agents.workflow.builder.documentsHint')}
+            />
+            <FormField
+              label={t('agents.workflow.builder.filePassing')}
+              hint={t('agents.workflow.builder.filePassingHint')}
+              labelSurface="background"
+            >
+              <Select
+                value={normalizeFilePassing(config.file_passing)}
+                onValueChange={(value) =>
+                  updateConfig({ file_passing: value as FilePassing })
+                }
+              >
+                <SelectTrigger size="field" className="w-full">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {FILE_PASSING_OPTIONS.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {t(`agents.workflow.filePassing.${option.value}`, {
+                        defaultValue: option.label,
+                      })}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FormField>
+            <FormField
+              label={t('agents.workflow.builder.structuredOutput')}
+              labelSurface="background"
+              hint={
+                [
+                  !modelSupportsStructuredOutput
+                    ? t('agents.workflow.builder.modelNoStructuredOutput')
+                    : null,
+                  jsonSchemaText.trim() !== '' && !jsonSchemaError
+                    ? t('agents.workflow.builder.validSchema')
+                    : null,
+                ]
+                  .filter(Boolean)
+                  .join(' ') || undefined
+              }
+              error={
+                schemaInvalid
+                  ? t('agents.workflow.builder.invalidSchema', {
+                      ...NO_ESCAPE,
+                      error: schemaErrorText(t, jsonSchemaError),
+                    })
+                  : undefined
+              }
+            >
+              <Textarea
+                value={jsonSchemaText}
+                onChange={(e) => onJsonSchemaChange(e.target.value)}
+                className="font-mono"
+                rows={4}
+                placeholder={SCHEMA_PLACEHOLDER}
+              />
+            </FormField>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/CodePanel.tsx b/frontend/src/agents/workflow/panels/CodePanel.tsx
new file mode 100644
index 00000000..6b36b9e8
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/CodePanel.tsx
@@ -0,0 +1,152 @@
+import { useTranslation } from 'react-i18next';
+
+import { FormField } from '@/components/ui/form-field';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+
+import NodeDocumentsControl from '../components/NodeDocumentsControl';
+import { NO_ESCAPE, schemaErrorText } from '../workflowHelpers';
+import { type NodePanelBodyProps } from './types';
+
+interface CodePanelProps extends NodePanelBodyProps {
+  /** Upstream file variables the code can take as inputs. */
+  documentOptions: { value: string; label: string }[];
+  /** The structured-output schema as typed. */
+  jsonSchemaText: string;
+  /** The schema's validation fragment, or null. */
+  jsonSchemaError: string | null;
+  onJsonSchemaChange: (text: string) => void;
+}
+
+/** Settings for a Code node: code, inputs, output and schema. */
+export default function CodePanel({
+  node: selectedNode,
+  onUpdate: handleUpdateNodeData,
+  documentOptions: selectedCodeDocumentOptions,
+  jsonSchemaText: selectedCodeJsonSchemaText,
+  jsonSchemaError: selectedCodeJsonSchemaError,
+  onJsonSchemaChange: handleCodeJsonSchemaChange,
+}: CodePanelProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="flex flex-col gap-5">
+      <p className="text-muted-foreground text-sm">
+        {t('agents.workflow.builder.codeIntro')}
+      </p>
+      <FormField
+        labelSurface="background"
+        label={t('agents.workflow.nodes.code')}
+      >
+        <Textarea
+          value={selectedNode.data.config?.code ?? ''}
+          onChange={(e) =>
+            handleUpdateNodeData({
+              config: {
+                ...(selectedNode.data.config || {}),
+                code: e.target.value,
+              },
+            })
+          }
+          className="font-mono"
+          rows={10}
+          spellCheck={false}
+          placeholder={t('agents.workflow.builder.examplePlaceholder', {
+            ...NO_ESCAPE,
+            example: 'print("hello world")',
+          })}
+        />
+      </FormField>
+      <NodeDocumentsControl
+        key={selectedNode.id}
+        value={selectedNode.data.config?.inputs ?? []}
+        onChange={(nextInputs) =>
+          handleUpdateNodeData({
+            config: {
+              ...(selectedNode.data.config || {}),
+              inputs: nextInputs,
+            },
+          })
+        }
+        options={selectedCodeDocumentOptions}
+        label={t('agents.workflow.builder.inputFiles')}
+        helpText={t('agents.workflow.builder.inputFilesHint')}
+      />
+      <FormField
+        labelSurface="background"
+        label={t('agents.workflow.builder.outputVariable')}
+      >
+        <Input
+          type="text"
+          value={selectedNode.data.config?.output_variable || ''}
+          onChange={(e) =>
+            handleUpdateNodeData({
+              config: {
+                ...(selectedNode.data.config || {}),
+                output_variable: e.target.value,
+              },
+            })
+          }
+          placeholder={t('agents.workflow.builder.outputVariablePlaceholder')}
+        />
+      </FormField>
+      <FormField
+        labelSurface="background"
+        label={t('agents.workflow.builder.timeout')}
+      >
+        <Input
+          type="number"
+          min={1}
+          value={selectedNode.data.config?.timeout ?? ''}
+          onChange={(e) => {
+            const raw = e.target.value;
+            const parsed =
+              raw.trim() === '' ? undefined : Number.parseInt(raw, 10);
+            handleUpdateNodeData({
+              config: {
+                ...(selectedNode.data.config || {}),
+                timeout:
+                  parsed !== undefined && Number.isFinite(parsed)
+                    ? parsed
+                    : undefined,
+              },
+            });
+          }}
+          placeholder={t('agents.workflow.builder.optional')}
+        />
+      </FormField>
+      <FormField
+        labelSurface="background"
+        label={t('agents.workflow.builder.structuredOutput')}
+        hint={
+          selectedCodeJsonSchemaText.trim() !== '' &&
+          !selectedCodeJsonSchemaError
+            ? t('agents.workflow.builder.validSchema')
+            : undefined
+        }
+        error={
+          selectedCodeJsonSchemaText.trim() !== '' &&
+          selectedCodeJsonSchemaError
+            ? t('agents.workflow.builder.invalidSchema', {
+                ...NO_ESCAPE,
+                error: schemaErrorText(t, selectedCodeJsonSchemaError),
+              })
+            : undefined
+        }
+      >
+        <Textarea
+          value={selectedCodeJsonSchemaText}
+          onChange={(e) => handleCodeJsonSchemaChange(e.target.value)}
+          className="font-mono"
+          rows={6}
+          placeholder={`{
+  "type": "object",
+  "properties": {
+    "result": { "type": "string" }
+  },
+  "required": ["result"]
+}`}
+        />
+      </FormField>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/ConditionPanel.test.tsx b/frontend/src/agents/workflow/panels/ConditionPanel.test.tsx
new file mode 100644
index 00000000..022f01d4
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/ConditionPanel.test.tsx
@@ -0,0 +1,107 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { type Node } from 'reactflow';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+  Trans: ({ i18nKey }: { i18nKey: string }) => i18nKey,
+}));
+
+import ConditionPanel from './ConditionPanel';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const node: Node = {
+  id: 'condition_1',
+  type: 'condition',
+  position: { x: 0, y: 0 },
+  data: {
+    title: 'Route',
+    config: {
+      mode: 'simple',
+      cases: [
+        {
+          name: 'People Ops',
+          expression: 'category.contains("people")',
+          sourceHandle: 'case_0',
+        },
+      ],
+    },
+  },
+};
+
+describe('ConditionPanel', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = () => {
+    const onUpdate = vi.fn();
+    act(() => {
+      root.render(
+        <ConditionPanel
+          node={node}
+          onUpdate={onUpdate}
+          onRemoveBranch={vi.fn()}
+        />,
+      );
+    });
+    return { onUpdate };
+  };
+
+  it('picks the mode with a ToggleGroup in the muted track', () => {
+    const { onUpdate } = render();
+    const group = container.querySelector('[role="radiogroup"]')!;
+    expect(group.parentElement!.className).toContain('bg-muted');
+    const advanced = Array.from(group.querySelectorAll('button')).find(
+      (b) => b.textContent === 'agents.workflow.builder.modeAdvanced',
+    )!;
+    act(() => advanced.click());
+    expect(onUpdate).toHaveBeenCalledWith({
+      config: expect.objectContaining({ mode: 'advanced' }),
+    });
+  });
+
+  it('labels the branch name, variable, operator and value fields', () => {
+    render();
+    const labels = Array.from(
+      container.querySelectorAll('[data-slot="form-field-label"]'),
+    ).map((l) => l.textContent);
+    expect(labels).toEqual([
+      'agents.workflow.builder.branchName',
+      'agents.workflow.builder.variable',
+      'agents.workflow.builder.operator',
+      'agents.workflow.builder.value',
+    ]);
+  });
+
+  it('wires the operator label to its select, with no aria-label', () => {
+    render();
+    const trigger = container.querySelector('[role="combobox"]')!;
+    expect(trigger.hasAttribute('aria-label')).toBe(false);
+    const label = container.querySelector(`label[for="${trigger.id}"]`);
+    expect(label?.textContent).toBe('agents.workflow.builder.operator');
+  });
+
+  it('adds a condition with an outline pill button', () => {
+    const { onUpdate } = render();
+    const add = Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes('agents.workflow.builder.addCondition'),
+    )!;
+    expect(add.getAttribute('data-variant')).toBe('outline');
+    act(() => add.click());
+    const cases = onUpdate.mock.calls[0][0].config.cases;
+    expect(cases).toHaveLength(2);
+    expect(cases[1].sourceHandle).toBe('case_1');
+  });
+});
diff --git a/frontend/src/agents/workflow/panels/ConditionPanel.tsx b/frontend/src/agents/workflow/panels/ConditionPanel.tsx
new file mode 100644
index 00000000..bffa53b2
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/ConditionPanel.tsx
@@ -0,0 +1,291 @@
+import { Plus, Trash2 } from 'lucide-react';
+import { Trans, useTranslation } from 'react-i18next';
+
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { FormField } from '@/components/ui/form-field';
+import { IconButton } from '@/components/ui/icon-button';
+import { Input } from '@/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { SectionHeader } from '@/components/ui/section-header';
+import { Textarea } from '@/components/ui/textarea';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+
+import { ConditionCase } from '../../types/workflow';
+import { buildSimpleCel, parseSimpleCel } from '../simpleCel';
+import {
+  getNextConditionHandle,
+  normalizeConditionCases,
+} from '../workflowHelpers';
+import { type NodePanelBodyProps } from './types';
+
+interface ConditionPanelProps extends NodePanelBodyProps {
+  /** Drop the edges leaving the node from a removed case's handle. */
+  onRemoveBranch: (sourceHandle: string) => void;
+}
+
+type ConditionMode = 'simple' | 'advanced';
+
+/**
+ * Settings for an If / Else node: Simple or Advanced mode, then one row box
+ * per case (If, Else if, …) and Add condition.
+ */
+export default function ConditionPanel({
+  node,
+  onUpdate,
+  onRemoveBranch,
+}: ConditionPanelProps) {
+  const { t } = useTranslation();
+  const config = node.data.config || {};
+  const mode: ConditionMode =
+    config.mode === 'advanced' ? 'advanced' : 'simple';
+  const cases: ConditionCase[] = config.cases || [];
+
+  const updateConfig = (patch: Record<string, unknown>) =>
+    onUpdate({ config: { ...(node.data.config || {}), ...patch } });
+
+  const updateCase = (idx: number, patch: Partial<ConditionCase>) => {
+    const next = [...cases];
+    next[idx] = { ...next[idx], ...patch };
+    updateConfig({ cases: next });
+  };
+
+  const removeCase = (idx: number) => {
+    const next = normalizeConditionCases([...cases]);
+    const removedHandle = next[idx]?.sourceHandle;
+    next.splice(idx, 1);
+    updateConfig({ cases: next });
+    if (removedHandle) onRemoveBranch(removedHandle);
+  };
+
+  const addCase = () => {
+    const next = normalizeConditionCases([...cases]);
+    next.push({
+      name: '',
+      expression: '',
+      sourceHandle: getNextConditionHandle(next),
+    });
+    updateConfig({ cases: next });
+  };
+
+  return (
+    <div className="flex flex-col gap-5">
+      <p className="text-muted-foreground text-sm">
+        {t('agents.workflow.builder.conditionIntro')}
+      </p>
+      {/* The track is a plain wrapper: ToggleGroup takes layout only. */}
+      <div className="bg-muted rounded-full p-1">
+        <ToggleGroup
+          type="single"
+          size="xs"
+          value={mode}
+          onValueChange={(next) => next && updateConfig({ mode: next })}
+          aria-label={t('agents.workflow.builder.conditionMode')}
+          className="flex-nowrap"
+        >
+          <ToggleGroupItem value="simple" className="flex-1">
+            {t('agents.workflow.builder.modeSimple')}
+          </ToggleGroupItem>
+          <ToggleGroupItem value="advanced" className="flex-1">
+            {t('agents.workflow.builder.modeAdvanced')}
+          </ToggleGroupItem>
+        </ToggleGroup>
+      </div>
+
+      {cases.map((c, idx) => {
+        const parsed = parseSimpleCel(c.expression);
+        return (
+          <Card
+            key={c.sourceHandle}
+            variant="subtle"
+            padding="sm"
+            className="gap-4"
+          >
+            <div className="flex items-center gap-2">
+              <span
+                aria-hidden="true"
+                className="bg-warning size-2 shrink-0 rounded-full"
+              />
+              <SectionHeader
+                as="h4"
+                size="xs"
+                className="flex-1"
+                title={
+                  idx === 0
+                    ? t('agents.workflow.nodes.if')
+                    : t('agents.workflow.nodes.elseIf')
+                }
+              />
+              {cases.length > 1 && (
+                <IconButton
+                  variant="ghost-destructive"
+                  size="icon-xs"
+                  label={t('agents.workflow.removeCondition', {
+                    index: idx + 1,
+                  })}
+                  icon={Trash2}
+                  onClick={() => removeCase(idx)}
+                />
+              )}
+            </div>
+            <FormField
+              label={t('agents.workflow.builder.branchName')}
+              labelSurface="background"
+            >
+              <Input
+                type="text"
+                value={c.name || ''}
+                onChange={(e) => updateCase(idx, { name: e.target.value })}
+                placeholder={t('agents.workflow.builder.caseNamePlaceholder')}
+              />
+            </FormField>
+            {mode === 'simple' ? (
+              <>
+                <FormField
+                  label={t('agents.workflow.builder.variable')}
+                  labelSurface="background"
+                >
+                  <Input
+                    type="text"
+                    className="font-mono"
+                    value={parsed.variable}
+                    onChange={(e) =>
+                      updateCase(idx, {
+                        expression: buildSimpleCel(
+                          e.target.value,
+                          parsed.operator,
+                          parsed.value,
+                        ),
+                      })
+                    }
+                    placeholder={t(
+                      'agents.workflow.builder.variablePlaceholder',
+                    )}
+                  />
+                </FormField>
+                <div className="flex gap-2">
+                  <FormField
+                    label={t('agents.workflow.builder.operator')}
+                    labelSurface="background"
+                    className="w-32 shrink-0"
+                  >
+                    <Select
+                      value={parsed.operator}
+                      onValueChange={(op) =>
+                        updateCase(idx, {
+                          expression: buildSimpleCel(
+                            parsed.variable,
+                            op,
+                            parsed.value,
+                          ),
+                        })
+                      }
+                    >
+                      <SelectTrigger size="field" className="w-full">
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        <SelectItem value="==">=</SelectItem>
+                        <SelectItem value="!=">!=</SelectItem>
+                        <SelectItem value=">">&gt;</SelectItem>
+                        <SelectItem value="<">&lt;</SelectItem>
+                        <SelectItem value=">=">&gt;=</SelectItem>
+                        <SelectItem value="<=">&lt;=</SelectItem>
+                        <SelectItem value="contains">
+                          {t('agents.workflow.builder.opContains')}
+                        </SelectItem>
+                        <SelectItem value="startsWith">
+                          {t('agents.workflow.builder.opStartsWith')}
+                        </SelectItem>
+                      </SelectContent>
+                    </Select>
+                  </FormField>
+                  <FormField
+                    label={t('agents.workflow.builder.value')}
+                    labelSurface="background"
+                    className="min-w-0 flex-1"
+                  >
+                    <Input
+                      type="text"
+                      value={parsed.value}
+                      onChange={(e) =>
+                        updateCase(idx, {
+                          expression: buildSimpleCel(
+                            parsed.variable,
+                            parsed.operator,
+                            e.target.value,
+                          ),
+                        })
+                      }
+                      placeholder={t(
+                        'agents.workflow.builder.valuePlaceholder',
+                      )}
+                    />
+                  </FormField>
+                </div>
+              </>
+            ) : (
+              <FormField
+                label={t('agents.workflow.conditionRow', { index: idx + 1 })}
+                labelSurface="background"
+                hint={
+                  <>
+                    <Trans
+                      i18nKey="agents.workflow.builder.celHint"
+                      components={{ code: <code /> }}
+                      values={{ braced: '{{query}}' }}
+                    />{' '}
+                    <Button
+                      variant="link"
+                      size="inline"
+                      asChild
+                      // eslint-disable-next-line shadcn/no-restyle -- a link in a 12px hint keeps the sentence's size and weight
+                      className="text-xs font-normal"
+                    >
+                      <a
+                        href="https://cel.dev/"
+                        target="_blank"
+                        rel="noreferrer"
+                      >
+                        {t('agents.workflow.builder.learnMore')}
+                      </a>
+                    </Button>
+                  </>
+                }
+              >
+                <Textarea
+                  value={c.expression}
+                  onChange={(e) =>
+                    updateCase(idx, { expression: e.target.value })
+                  }
+                  rows={2}
+                  placeholder={t(
+                    'agents.workflow.builder.conditionPlaceholder',
+                  )}
+                />
+              </FormField>
+            )}
+          </Card>
+        );
+      })}
+
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        shape="pill"
+        onClick={addCase}
+        className="self-start"
+      >
+        <Plus />
+        {t('agents.workflow.builder.addCondition')}
+      </Button>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/NodePanel.test.tsx b/frontend/src/agents/workflow/panels/NodePanel.test.tsx
new file mode 100644
index 00000000..9f4ac8d5
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/NodePanel.test.tsx
@@ -0,0 +1,123 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { type Node } from 'reactflow';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import NodePanel from './NodePanel';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const agentNode: Node = {
+  id: 'classify',
+  type: 'agent',
+  position: { x: 0, y: 0 },
+  data: { title: 'Classify request' },
+};
+
+const startNode: Node = {
+  id: 'start',
+  type: 'start',
+  position: { x: 0, y: 0 },
+  data: { label: 'Start' },
+};
+
+describe('NodePanel', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = (node: Node) => {
+    const handlers = {
+      onClose: vi.fn(),
+      onDuplicate: vi.fn(),
+      onDelete: vi.fn(),
+      onUpdate: vi.fn(),
+    };
+    act(() => {
+      root.render(
+        <NodePanel node={node} {...handlers}>
+          <div data-testid="body">body</div>
+        </NodePanel>,
+      );
+    });
+    return handlers;
+  };
+
+  const menuTrigger = () =>
+    container.querySelector(
+      '[aria-label="agents.workflow.builder.nodeActions"]',
+    ) as HTMLButtonElement | null;
+
+  it('shows the icon, own title, type badge and id', () => {
+    render(agentNode);
+    const header = container.querySelector('header')!;
+    expect(header.textContent).toContain('Classify request');
+    const badge = header.querySelector('[data-slot="badge"]')!;
+    expect(badge.textContent).toBe('agents.workflow.builder.aiAgent');
+    expect(badge.getAttribute('data-variant')).toBe('neutral');
+    expect(header.textContent).toContain('classify');
+    expect(header.querySelector('.bg-secondary')).not.toBeNull();
+  });
+
+  it('offers Duplicate and Delete node in the node menu', () => {
+    const { onDuplicate, onDelete } = render(agentNode);
+    const trigger = menuTrigger();
+    expect(trigger).not.toBeNull();
+    act(() => {
+      trigger!.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
+      );
+    });
+    const items = Array.from(
+      document.querySelectorAll('[role="menuitem"]'),
+    ) as HTMLElement[];
+    expect(items.map((i) => i.textContent)).toEqual([
+      'agents.workflow.builder.duplicateNode',
+      'agents.workflow.builder.deleteNode',
+    ]);
+    expect(items[1].getAttribute('data-variant')).toBe('destructive');
+    act(() => items[0].click());
+    expect(onDuplicate).toHaveBeenCalled();
+    expect(onDelete).not.toHaveBeenCalled();
+  });
+
+  it('has no node menu and no title field for the start node', () => {
+    render(startNode);
+    expect(menuTrigger()).toBeNull();
+    expect(container.querySelector('input')).toBeNull();
+    expect(container.textContent).not.toContain('cannotDeleteStart');
+  });
+
+  it('closes from the header', () => {
+    const { onClose } = render(agentNode);
+    const close = container.querySelector(
+      '[aria-label="agents.close"]',
+    ) as HTMLButtonElement;
+    act(() => close.click());
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('edits the title on the background surface and renders the body', () => {
+    const { onUpdate } = render(agentNode);
+    const label = container.querySelector(
+      '[data-slot="form-field-label"]',
+    ) as HTMLElement;
+    expect(label.className).toContain('bg-background');
+    expect(container.querySelector('[data-testid="body"]')).not.toBeNull();
+    expect(onUpdate).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/agents/workflow/panels/NodePanel.tsx b/frontend/src/agents/workflow/panels/NodePanel.tsx
new file mode 100644
index 00000000..3143894a
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/NodePanel.tsx
@@ -0,0 +1,151 @@
+import { Copy, Trash2, X } from 'lucide-react';
+import { type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import { type Node } from 'reactflow';
+
+import { Badge } from '@/components/ui/badge';
+import { ActionMenu } from '@/components/ui/dropdown-menu';
+import { FormField } from '@/components/ui/form-field';
+import { IconButton } from '@/components/ui/icon-button';
+import { Input } from '@/components/ui/input';
+import { cn } from '@/lib/utils';
+
+import CopyButton from '../../../components/CopyButton';
+import { NODE_META, nodeToneClass, type WorkflowNodeType } from '../nodeTones';
+
+interface NodePanelProps {
+  /** The node being edited. */
+  node: Node;
+  onClose: () => void;
+  onDuplicate: () => void;
+  onDelete: () => void;
+  /** Merge fields into the node's data (used by the title field). */
+  onUpdate: (data: Record<string, unknown>) => void;
+  /** The type's own settings (AgentPanel, ConditionPanel, …). */
+  children?: ReactNode;
+}
+
+// Start and End have fixed names and no settings of their own.
+const FIXED_TYPES = new Set(['start', 'end']);
+
+const FIXED_HINT_KEYS: Record<string, string> = {
+  start: 'agents.workflow.nodes.startHint',
+  end: 'agents.workflow.nodes.endHint',
+};
+
+/**
+ * The node settings column docked at the canvas's right edge: a header with
+ * the type's icon, the node's title, its type and id, a ⋯ menu (Duplicate,
+ * Delete node; none for Start) and close, then the one scrolling body.
+ */
+export default function NodePanel({
+  node,
+  onClose,
+  onDuplicate,
+  onDelete,
+  onUpdate,
+  children,
+}: NodePanelProps) {
+  const { t } = useTranslation();
+  const meta = NODE_META[node.type as WorkflowNodeType];
+  const Icon = meta?.icon;
+  const typeLabel = meta ? t(meta.labelKey) : (node.type ?? '');
+  const fixed = FIXED_TYPES.has(node.type ?? '');
+  const title = fixed
+    ? typeLabel
+    : node.data.title || node.data.label || typeLabel;
+
+  return (
+    <aside className="bg-background border-border flex w-96 shrink-0 flex-col border-l">
+      <header className="border-border flex items-start gap-3 border-b px-4 py-3">
+        <span
+          className={cn(
+            'flex size-8 shrink-0 items-center justify-center rounded-md',
+            nodeToneClass(node.type),
+          )}
+        >
+          {Icon && <Icon className="size-4" aria-hidden="true" />}
+        </span>
+        <div className="flex min-w-0 flex-1 flex-col">
+          <div className="flex min-w-0 items-center gap-2">
+            <h2
+              className="text-foreground truncate text-sm font-semibold"
+              title={title}
+            >
+              {title}
+            </h2>
+            {title !== typeLabel && (
+              <Badge variant="neutral">{typeLabel}</Badge>
+            )}
+          </div>
+          <div className="flex min-w-0 items-center gap-1">
+            <span
+              className="text-muted-foreground truncate font-mono text-xs"
+              title={node.id}
+            >
+              {node.id}
+            </span>
+            <CopyButton
+              textToCopy={node.id}
+              size="xs"
+              copyLabel={t('agents.workflow.builder.copyNodeId')}
+              side="bottom"
+            />
+          </div>
+        </div>
+        {node.type !== 'start' && (
+          <ActionMenu
+            size="toolbar"
+            triggerLabel={t('agents.workflow.builder.nodeActions')}
+            options={[
+              {
+                label: t('agents.workflow.builder.duplicateNode'),
+                icon: Copy,
+                onClick: onDuplicate,
+              },
+              {
+                label: t('agents.workflow.builder.deleteNode'),
+                icon: Trash2,
+                variant: 'destructive',
+                onClick: onDelete,
+              },
+            ]}
+          />
+        )}
+        <IconButton
+          variant="ghost-muted"
+          size="icon-sm"
+          side="bottom"
+          onClick={onClose}
+          label={t('agents.close')}
+          icon={X}
+        />
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        <div className="flex flex-col gap-6 p-4">
+          {fixed ? (
+            <p className="text-muted-foreground text-sm">
+              {t(FIXED_HINT_KEYS[node.type ?? ''])}
+            </p>
+          ) : (
+            <FormField
+              label={t('agents.workflow.builder.title')}
+              labelSurface="background"
+            >
+              <Input
+                type="text"
+                value={node.data.title || node.data.label || ''}
+                onChange={(e) =>
+                  onUpdate({ title: e.target.value, label: e.target.value })
+                }
+                placeholder={t('agents.workflow.builder.titlePlaceholder')}
+              />
+            </FormField>
+          )}
+          {children}
+        </div>
+      </div>
+    </aside>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/NotePanel.tsx b/frontend/src/agents/workflow/panels/NotePanel.tsx
new file mode 100644
index 00000000..f4115c85
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/NotePanel.tsx
@@ -0,0 +1,31 @@
+import { useTranslation } from 'react-i18next';
+
+import { FormField } from '@/components/ui/form-field';
+import { Textarea } from '@/components/ui/textarea';
+
+import { type NodePanelBodyProps } from './types';
+
+/** Settings for a note node: its text. */
+export default function NotePanel({
+  node: selectedNode,
+  onUpdate: handleUpdateNodeData,
+}: NodePanelBodyProps) {
+  const { t } = useTranslation();
+  return (
+    <FormField
+      labelSurface="background"
+      label={t('agents.workflow.builder.noteContent')}
+    >
+      <Textarea
+        value={selectedNode.data.content || ''}
+        onChange={(e) =>
+          handleUpdateNodeData({
+            content: e.target.value,
+          })
+        }
+        rows={4}
+        placeholder={t('agents.workflow.builder.noteContentPlaceholder')}
+      />
+    </FormField>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/StatePanel.test.tsx b/frontend/src/agents/workflow/panels/StatePanel.test.tsx
new file mode 100644
index 00000000..c3cf0094
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/StatePanel.test.tsx
@@ -0,0 +1,92 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { type Node } from 'reactflow';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: { index?: number }) =>
+      opts?.index !== undefined ? `${key}:${opts.index}` : key,
+  }),
+  Trans: ({ i18nKey }: { i18nKey: string }) => i18nKey,
+}));
+
+import StatePanel from './StatePanel';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const node: Node = {
+  id: 'state_1',
+  type: 'state',
+  position: { x: 0, y: 0 },
+  data: {
+    title: 'Set priority',
+    config: {
+      operations: [
+        { expression: '"P1"', target_variable: 'priority' },
+        { expression: '"4h"', target_variable: 'sla' },
+      ],
+    },
+  },
+};
+
+describe('StatePanel', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = () => {
+    const onUpdate = vi.fn();
+    act(() => {
+      root.render(<StatePanel node={node} onUpdate={onUpdate} />);
+    });
+    return { onUpdate };
+  };
+
+  it('explains CEL once, in the intro', () => {
+    render();
+    const matches = container.textContent!.match(
+      /agents\.workflow\.builder\.celHint/g,
+    );
+    expect(matches).toHaveLength(1);
+    expect(
+      container.querySelectorAll('a[href="https://cel.dev/"]'),
+    ).toHaveLength(1);
+  });
+
+  it('numbers each assignment and puts the variable before the value', () => {
+    render();
+    expect(container.textContent).toContain(
+      'agents.workflow.builder.assignment:1',
+    );
+    expect(container.textContent).toContain(
+      'agents.workflow.builder.assignment:2',
+    );
+    const labels = Array.from(
+      container.querySelectorAll('[data-slot="form-field-label"]'),
+    ).map((l) => l.textContent);
+    expect(labels.slice(0, 2)).toEqual([
+      'agents.workflow.builder.variable',
+      'agents.workflow.builder.valueCel',
+    ]);
+  });
+
+  it('adds an assignment with an outline pill button', () => {
+    const { onUpdate } = render();
+    const add = Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes('agents.workflow.builder.addAssignment'),
+    )!;
+    expect(add.getAttribute('data-variant')).toBe('outline');
+    act(() => add.click());
+    expect(onUpdate.mock.calls[0][0].config.operations).toHaveLength(3);
+  });
+});
diff --git a/frontend/src/agents/workflow/panels/StatePanel.tsx b/frontend/src/agents/workflow/panels/StatePanel.tsx
new file mode 100644
index 00000000..597cef82
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/StatePanel.tsx
@@ -0,0 +1,132 @@
+import { Plus, Trash2 } from 'lucide-react';
+import { Trans, useTranslation } from 'react-i18next';
+
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { FormField } from '@/components/ui/form-field';
+import { IconButton } from '@/components/ui/icon-button';
+import { Input } from '@/components/ui/input';
+import { SectionHeader } from '@/components/ui/section-header';
+import { Textarea } from '@/components/ui/textarea';
+
+import { StateOperationConfig } from '../../types/workflow';
+import { NO_ESCAPE } from '../workflowHelpers';
+import { type NodePanelBodyProps } from './types';
+
+/**
+ * Settings for a Set State node: an intro that explains CEL once, then one
+ * numbered row box per assignment (variable, then its CEL value).
+ */
+export default function StatePanel({ node, onUpdate }: NodePanelBodyProps) {
+  const { t } = useTranslation();
+  const operations: StateOperationConfig[] = node.data.config?.operations || [];
+
+  const setOperations = (next: StateOperationConfig[]) =>
+    onUpdate({ config: { ...(node.data.config || {}), operations: next } });
+
+  const updateOperation = (
+    idx: number,
+    patch: Partial<StateOperationConfig>,
+  ) => {
+    const next = [...operations];
+    next[idx] = { ...next[idx], ...patch };
+    setOperations(next);
+  };
+
+  return (
+    <div className="flex flex-col gap-5">
+      <p className="text-muted-foreground text-sm">
+        {t('agents.workflow.builder.stateIntro')}{' '}
+        <Trans
+          i18nKey="agents.workflow.builder.celHint"
+          components={{ code: <code /> }}
+          values={{ braced: '{{query}}' }}
+        />{' '}
+        <Button variant="link" size="inline" asChild>
+          <a href="https://cel.dev/" target="_blank" rel="noreferrer">
+            {t('agents.workflow.builder.learnMore')}
+          </a>
+        </Button>
+      </p>
+
+      {operations.map((op, idx) => (
+        <Card key={idx} variant="subtle" padding="sm" className="gap-4">
+          <div className="flex items-center gap-2">
+            <SectionHeader
+              as="h4"
+              size="xs"
+              className="flex-1"
+              title={t('agents.workflow.builder.assignment', {
+                index: idx + 1,
+              })}
+            />
+            {operations.length > 1 && (
+              <IconButton
+                variant="ghost-destructive"
+                size="icon-xs"
+                label={t('agents.workflow.removeAssignment', {
+                  index: idx + 1,
+                })}
+                icon={Trash2}
+                onClick={() =>
+                  setOperations(operations.filter((_, i) => i !== idx))
+                }
+              />
+            )}
+          </div>
+          <FormField
+            label={t('agents.workflow.builder.variable')}
+            labelSurface="background"
+          >
+            <Input
+              type="text"
+              className="font-mono"
+              value={op.target_variable}
+              onChange={(e) =>
+                updateOperation(idx, { target_variable: e.target.value })
+              }
+              placeholder={t('agents.workflow.builder.examplePlaceholder', {
+                ...NO_ESCAPE,
+                example: 'variable_name',
+              })}
+            />
+          </FormField>
+          <FormField
+            label={t('agents.workflow.builder.valueCel')}
+            labelSurface="background"
+          >
+            <Textarea
+              className="font-mono"
+              value={op.expression}
+              onChange={(e) =>
+                updateOperation(idx, { expression: e.target.value })
+              }
+              rows={2}
+              placeholder={t('agents.workflow.builder.examplePlaceholder', {
+                ...NO_ESCAPE,
+                example: 'query',
+              })}
+            />
+          </FormField>
+        </Card>
+      ))}
+
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        shape="pill"
+        onClick={() =>
+          setOperations([
+            ...operations,
+            { expression: '', target_variable: '' },
+          ])
+        }
+        className="self-start"
+      >
+        <Plus />
+        {t('agents.workflow.builder.addAssignment')}
+      </Button>
+    </div>
+  );
+}
diff --git a/frontend/src/agents/workflow/panels/types.ts b/frontend/src/agents/workflow/panels/types.ts
new file mode 100644
index 00000000..7eb26680
--- /dev/null
+++ b/frontend/src/agents/workflow/panels/types.ts
@@ -0,0 +1,12 @@
+import { type Node } from 'reactflow';
+
+/** Props every node settings panel body takes. */
+export interface NodePanelBodyProps {
+  /** The node being edited. */
+  node: Node;
+  /** Merge fields into the node's data (a snapshot first unless disabled). */
+  onUpdate: (
+    data: Record<string, unknown>,
+    options?: { snapshot?: boolean },
+  ) => void;
+}
diff --git a/frontend/src/agents/workflow/workflowHelpers.test.ts b/frontend/src/agents/workflow/workflowHelpers.test.ts
new file mode 100644
index 00000000..a882a777
--- /dev/null
+++ b/frontend/src/agents/workflow/workflowHelpers.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { findFreePosition } from './workflowHelpers';
+
+const box = (id: string, x: number, y: number, width = 200, height = 60) => ({
+  id,
+  position: { x, y },
+  width,
+  height,
+});
+
+describe('findFreePosition', () => {
+  it('keeps the wanted spot when nothing is there', () => {
+    expect(findFreePosition([box('a', 0, 0)], { x: 400, y: 0 })).toEqual({
+      x: 400,
+      y: 0,
+    });
+  });
+
+  it('moves down past a node that covers the spot', () => {
+    const spot = findFreePosition([box('a', 380, 0)], { x: 400, y: 0 });
+    expect(spot.x).toBe(400);
+    expect(spot.y).toBeGreaterThanOrEqual(60 + 24);
+  });
+
+  it('keeps moving down past a column of nodes', () => {
+    const nodes = [box('a', 400, 0), box('b', 400, 84), box('c', 400, 168)];
+    const spot = findFreePosition(nodes, { x: 400, y: 0 });
+    expect(spot.y).toBeGreaterThanOrEqual(168 + 60 + 24);
+  });
+
+  it('uses a default size for nodes React Flow has not measured yet', () => {
+    const spot = findFreePosition([{ id: 'a', position: { x: 400, y: 0 } }], {
+      x: 450,
+      y: 10,
+    });
+    expect(spot.y).toBeGreaterThan(10);
+  });
+});
diff --git a/frontend/src/agents/workflow/workflowHelpers.ts b/frontend/src/agents/workflow/workflowHelpers.ts
new file mode 100644
index 00000000..16c1f459
--- /dev/null
+++ b/frontend/src/agents/workflow/workflowHelpers.ts
@@ -0,0 +1,204 @@
+import { type TFunction } from 'i18next';
+
+import { ConditionCase } from '../types/workflow';
+import { FilePassing } from './documentConfig';
+
+// Names and handles are the user's own text: React escapes on render, so
+// i18next must not escape them first.
+export const NO_ESCAPE = { interpolation: { escapeValue: false } } as const;
+
+export interface AgentNodeConfig {
+  agent_type: 'classic' | 'research';
+  llm_name?: string;
+  model_id?: string;
+  system_prompt: string;
+  prompt_template: string;
+  output_variable?: string;
+  stream_to_user: boolean;
+  sources: string[];
+  tools: string[];
+  chunks?: string;
+  retriever?: string;
+  json_schema?: Record<string, unknown>;
+  input_documents?: string[];
+  file_passing?: FilePassing;
+}
+
+export interface UserTool {
+  id: string;
+  name: string;
+  displayName: string;
+  customName?: string;
+  // Workflow-only builtins (e.g. read_document) are kept here; the classic
+  // agent picker filters them out.
+  workflow_only?: boolean;
+}
+
+/**
+ * Check an agent node's structured-output schema.
+ *
+ * Args:
+ *   schema: The parsed schema, or undefined when none is set.
+ *
+ * Returns:
+ *   A short English error fragment, or null when the schema is usable.
+ */
+export function validateJsonSchemaConfig(schema: unknown): string | null {
+  if (schema === undefined || schema === null) return null;
+  if (typeof schema !== 'object' || Array.isArray(schema)) {
+    return 'must be a valid JSON object';
+  }
+
+  const schemaObject = schema as Record<string, unknown>;
+  if (!('schema' in schemaObject) && !('type' in schemaObject)) {
+    return 'must include either a "type" or "schema" field';
+  }
+
+  return null;
+}
+
+// The schema validators return short English fragments (tests and the
+// validation list key off them); these map each to its locale key.
+const SCHEMA_ERROR_KEYS: Record<string, string> = {
+  'must be a valid JSON object': 'agents.workflow.schema.notObject',
+  'must include either a "type" or "schema" field':
+    'agents.workflow.schema.missingType',
+  'must be valid JSON': 'agents.workflow.schema.invalidJson',
+};
+
+/**
+ * Translate a JSON schema validation fragment.
+ *
+ * Args:
+ *   t: The i18next translate function.
+ *   fragment: The fragment a schema validator returned.
+ *
+ * Returns:
+ *   The translated fragment, or the fragment itself when it is unknown.
+ */
+export function schemaErrorText(t: TFunction, fragment: string): string {
+  const key = SCHEMA_ERROR_KEYS[fragment];
+  return key ? t(key) : fragment;
+}
+
+/**
+ * Give every condition case a unique `case_N` source handle.
+ *
+ * Args:
+ *   cases: The cases as stored.
+ *
+ * Returns:
+ *   The cases, with missing or duplicate handles replaced.
+ */
+export function normalizeConditionCases(
+  cases: ConditionCase[],
+): ConditionCase[] {
+  const usedHandles = new Set<string>();
+  let nextIndex = 0;
+
+  return cases.map((conditionCase) => {
+    const candidate = (conditionCase.sourceHandle || '').trim();
+    if (candidate && !usedHandles.has(candidate)) {
+      usedHandles.add(candidate);
+      const match = candidate.match(/^case_(\d+)$/);
+      if (match) {
+        nextIndex = Math.max(nextIndex, Number(match[1]) + 1);
+      }
+      return conditionCase;
+    }
+
+    while (usedHandles.has(`case_${nextIndex}`)) {
+      nextIndex += 1;
+    }
+    const generatedHandle = `case_${nextIndex}`;
+    usedHandles.add(generatedHandle);
+    nextIndex += 1;
+
+    return {
+      ...conditionCase,
+      sourceHandle: generatedHandle,
+    };
+  });
+}
+
+/**
+ * The next free `case_N` handle for a new condition case.
+ *
+ * Args:
+ *   cases: The existing cases.
+ *
+ * Returns:
+ *   An unused handle.
+ */
+export function getNextConditionHandle(cases: ConditionCase[]): string {
+  const usedHandles = new Set(
+    cases.map((conditionCase) => conditionCase.sourceHandle).filter(Boolean),
+  );
+  const usedIndices = Array.from(usedHandles)
+    .map((handle) => handle.match(/^case_(\d+)$/))
+    .filter((match): match is RegExpMatchArray => Boolean(match))
+    .map((match) => Number(match[1]));
+
+  let nextIndex = usedIndices.length > 0 ? Math.max(...usedIndices) + 1 : 0;
+  while (usedHandles.has(`case_${nextIndex}`)) {
+    nextIndex += 1;
+  }
+
+  return `case_${nextIndex}`;
+}
+
+interface PlacedNode {
+  id: string;
+  position: { x: number; y: number };
+  width?: number | null;
+  height?: number | null;
+}
+
+// Nodes React Flow hasn't measured yet count as a typical node.
+const DEFAULT_NODE_WIDTH = 200;
+const DEFAULT_NODE_HEIGHT = 64;
+const NODE_GAP = 24;
+const MAX_PLACEMENT_STEPS = 50;
+
+/**
+ * Find a spot for a new node that doesn't cover an existing one.
+ *
+ * Starts at `wanted` (the new node's top-left corner) and steps straight down
+ * until the new node's box, with a gap around it, clears every other node.
+ *
+ * Args:
+ *   nodes: The nodes already on the canvas.
+ *   wanted: Where the new node would ideally go.
+ *   size: The new node's expected size.
+ *
+ * Returns:
+ *   The first free top-left position at or below `wanted`.
+ */
+export function findFreePosition(
+  nodes: PlacedNode[],
+  wanted: { x: number; y: number },
+  size: { width: number; height: number } = {
+    width: DEFAULT_NODE_WIDTH,
+    height: DEFAULT_NODE_HEIGHT,
+  },
+): { x: number; y: number } {
+  const overlapping = (y: number) =>
+    nodes.find((node) => {
+      const width = node.width ?? DEFAULT_NODE_WIDTH;
+      const height = node.height ?? DEFAULT_NODE_HEIGHT;
+      return (
+        wanted.x < node.position.x + width + NODE_GAP &&
+        wanted.x + size.width + NODE_GAP > node.position.x &&
+        y < node.position.y + height + NODE_GAP &&
+        y + size.height + NODE_GAP > node.position.y
+      );
+    });
+
+  let y = wanted.y;
+  for (let step = 0; step < MAX_PLACEMENT_STEPS; step += 1) {
+    const blocker = overlapping(y);
+    if (!blocker) break;
+    y = blocker.position.y + (blocker.height ?? DEFAULT_NODE_HEIGHT) + NODE_GAP;
+  }
+  return { x: wanted.x, y };
+}
diff --git a/frontend/src/components/FileUpload.tsx b/frontend/src/components/FileUpload.tsx
index f9d65ae8..8caa8541 100644
--- a/frontend/src/components/FileUpload.tsx
+++ b/frontend/src/components/FileUpload.tsx
@@ -22,6 +22,8 @@ interface FileUploadProps {
   previewSize?: number;
   /** `compact` is a one-row target for forms and panels. */
   size?: 'default' | 'compact' | 'tile';
+  /** A tile's width; `fixed` keeps it 64px in a narrow drawer. */
+  tileSize?: 'responsive' | 'fixed';
   /** An image already saved (an agent's avatar), shown in a tile until a new one is picked. */
   currentImage?: string;
 
@@ -55,6 +57,7 @@ export const FileUpload = ({
   showPreview = false,
   previewSize = 80,
   size = 'default',
+  tileSize,
   currentImage,
   children,
   className,
@@ -256,6 +259,7 @@ export const FileUpload = ({
       maxSize={maxSize}
       disabled={disabled}
       size={size}
+      tileSize={tileSize}
       title={title}
       description={description}
       icon={<ImageUp />}
diff --git a/frontend/src/components/ui/dropzone.test.tsx b/frontend/src/components/ui/dropzone.test.tsx
index d8457a23..b440107b 100644
--- a/frontend/src/components/ui/dropzone.test.tsx
+++ b/frontend/src/components/ui/dropzone.test.tsx
@@ -56,6 +56,18 @@ describe('Dropzone', () => {
     expect(html).not.toContain('hidden</span>');
   });
 
+  it('keeps a fixed tile at 64px and icon-only at every width', () => {
+    const html = renderToStaticMarkup(
+      <Dropzone onDrop={vi.fn()} size="tile" tileSize="fixed" title="Avatar" />,
+    );
+    expect(html).toContain('data-tile-size="fixed"');
+    expect(html).toContain('size-16');
+    expect(html).not.toContain('sm:size-22');
+    expect(html).not.toContain('sm:not-sr-only');
+    // The word is still the target's accessible name.
+    expect(html).toMatch(/class="[^"]*\bsr-only\b[^"]*">Avatar/);
+  });
+
   it('never uses raw palette colours', () => {
     const html = renderToStaticMarkup(<Dropzone onDrop={vi.fn()} />);
     expect(html).not.toMatch(/\b(bg|text|border)-(gray|red|green|blue)-\d+/);
diff --git a/frontend/src/components/ui/dropzone.tsx b/frontend/src/components/ui/dropzone.tsx
index 656be88b..8bd46590 100644
--- a/frontend/src/components/ui/dropzone.tsx
+++ b/frontend/src/components/ui/dropzone.tsx
@@ -22,10 +22,17 @@ const dropzoneVariants = cva(
         // An 88px square beside a form's fields (an agent's avatar): the icon
         // and a one-word label, or the picked image filling it.
         // 64px and icon-only on a phone (beside the Name field), 88px from sm.
-        tile: 'size-16 shrink-0 gap-1 rounded-2xl p-2 sm:size-22',
+        tile: 'size-16 shrink-0 gap-1 rounded-2xl p-2',
       },
+      // Only for size tile. responsive grows to 88px from sm; fixed stays
+      // 64px at every width, for a tile in a narrow drawer, where the
+      // breakpoint follows the window, not the drawer.
+      tileSize: { responsive: '', fixed: '' },
     },
-    defaultVariants: { size: 'default' },
+    compoundVariants: [
+      { size: 'tile', tileSize: 'responsive', class: 'sm:size-22' },
+    ],
+    defaultVariants: { size: 'default', tileSize: 'responsive' },
   },
 );
 
@@ -57,6 +64,11 @@ type DropzoneProps = {
    * tile is an 88px square that shows only the icon and the title.
    */
   size?: 'default' | 'compact' | 'tile';
+  /**
+   * A tile's width: `responsive` (64px on a phone, 88px with its title from
+   * sm) or `fixed` (64px and icon-only everywhere, for a narrow drawer).
+   */
+  tileSize?: 'responsive' | 'fixed';
   /** Main line. Defaults to the generic upload prompt. */
   title?: React.ReactNode;
   /** Secondary line for accepted types and limits, e.g. ".yaml, up to 5 MB". */
@@ -84,6 +96,7 @@ function Dropzone({
   maxSize,
   disabled = false,
   size = 'default',
+  tileSize = 'responsive',
   title = 'Click to upload or drag and drop',
   description,
   icon,
@@ -116,10 +129,11 @@ function Dropzone({
         aria-describedby={field['aria-describedby']}
         data-slot="dropzone"
         data-size={size}
+        data-tile-size={size === 'tile' ? tileSize : undefined}
         data-disabled={disabled || undefined}
         data-drag-active={isDragActive || undefined}
         data-drag-reject={isDragReject || undefined}
-        className={cn(dropzoneVariants({ size }))}
+        className={cn(dropzoneVariants({ size, tileSize }))}
       >
         <input {...getInputProps({ id: field.id })} />
         {children ??
@@ -128,7 +142,12 @@ function Dropzone({
               <span className={dropzoneIconVariants({ size })}>
                 {icon ?? <CloudUpload />}
               </span>
-              <span className="text-muted-foreground sr-only text-xs sm:not-sr-only">
+              <span
+                className={cn(
+                  'text-muted-foreground sr-only text-xs',
+                  tileSize === 'responsive' && 'sm:not-sr-only',
+                )}
+              >
                 {title}
               </span>
             </>
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
index 742a4ac4..5c8d72eb 100644
--- a/frontend/src/design/DesignSystem.tsx
+++ b/frontend/src/design/DesignSystem.tsx
@@ -2172,6 +2172,18 @@ export default function DesignSystem() {
                     name and description.
                   </span>
                 </div>
+                <div className="flex items-center gap-3">
+                  <Dropzone
+                    size="tile"
+                    tileSize="fixed"
+                    onDrop={(files) => setDropped(files.map((f) => f.name))}
+                    title="Avatar"
+                  />
+                  <span className="text-muted-foreground text-xs">
+                    tileSize=&quot;fixed&quot;: 64px and icon-only at every
+                    width, for a narrow drawer.
+                  </span>
+                </div>
                 <p className="text-muted-foreground text-xs">
                   Last drop:{' '}
                   {dropped.length ? dropped.join(', ') : 'nothing yet'}
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index 0e11563d..84d1bb0e 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -1963,15 +1963,8 @@
         "saveFailed": "Workflow konnte nicht gespeichert werden",
         "defaultDescription": "Workflow-Agent: {{name}}",
         "newWorkflow": "Neuer Workflow",
-        "editDetails": "Workflow-Details bearbeiten",
-        "workflowName": "Workflow-Name",
         "workflowNamePlaceholder": "Workflow-Namen eingeben",
         "workflowDescriptionPlaceholder": "Beschreibe, was dieser Workflow macht",
-        "agentImageAlt": "Agentenbild",
-        "currentImage": "Aktuelles Bild",
-        "agentImage": "Agentenbild",
-        "agentImageHint": "Bildänderungen werden beim nächsten Speichern übernommen.",
-        "done": "Fertig",
         "unablePreview": "Workflow-Vorschau nicht möglich",
         "unableSave": "Workflow kann nicht gespeichert werden",
         "unablePublish": "Workflow kann nicht veröffentlicht werden",
@@ -1981,6 +1974,22 @@
         "setStateHint": "Workflow-Variablen ändern",
         "conditionHint": "Bedingte Verzweigung",
         "codeHint": "Code in einer Sandbox ausführen",
+        "paletteHint": "Auf die Arbeitsfläche ziehen oder zum Hinzufügen klicken.",
+        "nodeActions": "Knotenaktionen",
+        "duplicateNode": "Duplizieren",
+        "copyNodeId": "Knoten-ID kopieren",
+        "knowledge": "Wissen",
+        "output": "Ausgabe",
+        "streamToUserDescription": "Die Antwort dieses Knotens beim Schreiben im Chat anzeigen",
+        "advancedSettings": "Erweiterte Einstellungen",
+        "conditionMode": "Bedingungsmodus",
+        "branchName": "Name des Zweigs",
+        "variable": "Variable",
+        "value": "Wert",
+        "valueCel": "Wert (CEL)",
+        "addCondition": "Bedingung hinzufügen",
+        "assignment": "Zuweisung {{index}}",
+        "addAssignment": "Zuweisung hinzufügen",
         "startNode": "Startknoten",
         "endNode": "Endknoten",
         "stateTitle": "Globale Variablen setzen",
@@ -2009,7 +2018,7 @@
         "invalidSchema": "Ungültiges JSON-Schema: {{error}}",
         "noteContent": "Notizinhalt",
         "noteContentPlaceholder": "Notizinhalt eingeben",
-        "stateIntro": "Den Zustandsvariablen des Workflows Werte zuweisen",
+        "stateIntro": "Den Zustandsvariablen des Workflows Werte zuweisen.",
         "assignValue": "Wert zuweisen",
         "celHint": "Erstelle mit der Common Expression Language einen eigenen Ausdruck. Verweise auf den Zustand mit dem reinen Namen (<code>query</code>), nicht <code>{{braced}}</code>.",
         "learnMore": "Mehr erfahren",
@@ -2020,6 +2029,8 @@
         "caseNamePlaceholder": "Fallname (optional)",
         "variablePlaceholder": "Variable",
         "valuePlaceholder": "Wert",
+        "operator": "Operator",
+        "examplePlaceholder": "z. B. {{example}}",
         "opContains": "enthält",
         "opStartsWith": "beginnt",
         "conditionPlaceholder": "Bedingung eingeben, z. B. query.contains(\"refund\")",
@@ -2031,7 +2042,11 @@
         "cannotDeleteStart": "Startknoten kann nicht gelöscht werden",
         "deleteNode": "Knoten löschen",
         "deleteConfirm": "Möchtest du „{{name}}“ wirklich löschen?",
-        "deleteConfirmUnnamed": "Möchtest du diesen Workflow-Agenten wirklich löschen?"
+        "deleteConfirmUnnamed": "Möchtest du diesen Workflow-Agenten wirklich löschen?",
+        "detailsTitle": "Workflow-Details",
+        "detailsDescription": "Name, Beschreibung und Bild, die auf der Agentenkarte angezeigt werden.",
+        "unsavedChanges": "Nicht gespeicherte Änderungen",
+        "editDetailsMenu": "Details bearbeiten"
       },
       "validation": {
         "nameRequired": "Workflow-Name ist erforderlich",
@@ -2124,7 +2139,10 @@
         "searchPlaceholder": "Variablen suchen...",
         "empty": "Keine Variablen gefunden",
         "addContext": "Kontext hinzufügen"
-      }
+      },
+      "zoomIn": "Vergrößern",
+      "zoomOut": "Verkleinern",
+      "fitView": "Ansicht anpassen"
     },
     "typeModal": {
       "title": "Neuen Agenten erstellen",
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index 00448e40..355ffcfc 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -1969,12 +1969,14 @@
       "conditionRow": "Condition {{index}}",
       "conditionNameRow": "Condition {{index}} name",
       "conditionVariableRow": "Condition {{index}} variable",
-      "conditionOperatorRow": "Condition {{index}} operator",
       "conditionValueRow": "Condition {{index}} value",
       "undo": "Undo",
       "undoHint": "Undo (Ctrl+Z)",
       "redo": "Redo",
       "redoHint": "Redo (Ctrl+Shift+Z)",
+      "zoomIn": "Zoom in",
+      "zoomOut": "Zoom out",
+      "fitView": "Fit view",
       "removeAssignment": "Remove assignment {{index}}",
       "removeCondition": "Remove condition {{index}}",
       "artifacts": {
@@ -1997,15 +1999,8 @@
         "saveFailed": "Failed to save workflow",
         "defaultDescription": "Workflow agent: {{name}}",
         "newWorkflow": "New Workflow",
-        "editDetails": "Edit workflow details",
-        "workflowName": "Workflow Name",
         "workflowNamePlaceholder": "Enter workflow name",
         "workflowDescriptionPlaceholder": "Describe what this workflow does",
-        "agentImageAlt": "Agent image",
-        "currentImage": "Current image",
-        "agentImage": "Agent Image",
-        "agentImageHint": "Image updates are included the next time you save.",
-        "done": "Done",
         "unablePreview": "Unable to preview workflow",
         "unableSave": "Unable to save workflow",
         "unablePublish": "Unable to publish workflow",
@@ -2015,6 +2010,22 @@
         "setStateHint": "Modify workflow variables",
         "conditionHint": "Conditional branching",
         "codeHint": "Run code in a sandbox",
+        "paletteHint": "Drag onto the canvas, or click to add.",
+        "nodeActions": "Node actions",
+        "duplicateNode": "Duplicate",
+        "copyNodeId": "Copy node ID",
+        "knowledge": "Knowledge",
+        "output": "Output",
+        "streamToUserDescription": "Show this node's answer in the chat as it's written",
+        "advancedSettings": "Advanced settings",
+        "conditionMode": "Condition mode",
+        "branchName": "Branch name",
+        "variable": "Variable",
+        "value": "Value",
+        "valueCel": "Value (CEL)",
+        "addCondition": "Add condition",
+        "assignment": "Assignment {{index}}",
+        "addAssignment": "Add assignment",
         "startNode": "Start Node",
         "endNode": "End Node",
         "stateTitle": "Set global variables",
@@ -2043,7 +2054,7 @@
         "invalidSchema": "Invalid JSON schema: {{error}}",
         "noteContent": "Note Content",
         "noteContentPlaceholder": "Enter note content",
-        "stateIntro": "Assign values to workflow's state variables",
+        "stateIntro": "Assign values to the workflow's state variables.",
         "assignValue": "Assign value",
         "celHint": "Use Common Expression Language to create a custom expression. Reference state by bare name (<code>query</code>), not <code>{{braced}}</code>.",
         "learnMore": "Learn more",
@@ -2054,6 +2065,8 @@
         "caseNamePlaceholder": "Case name (optional)",
         "variablePlaceholder": "Variable",
         "valuePlaceholder": "Value",
+        "operator": "Operator",
+        "examplePlaceholder": "e.g. {{example}}",
         "opContains": "contains",
         "opStartsWith": "starts",
         "conditionPlaceholder": "Enter condition, e.g. query.contains(\"refund\")",
@@ -2063,9 +2076,13 @@
         "timeout": "Timeout (seconds)",
         "optional": "Optional",
         "cannotDeleteStart": "Cannot Delete Start Node",
-        "deleteNode": "Delete Node",
+        "deleteNode": "Delete node",
         "deleteConfirm": "Are you sure you want to delete \"{{name}}\"?",
-        "deleteConfirmUnnamed": "Are you sure you want to delete \"this workflow agent\"?"
+        "deleteConfirmUnnamed": "Are you sure you want to delete \"this workflow agent\"?",
+        "detailsTitle": "Workflow details",
+        "detailsDescription": "Name, description and image shown on the agent card.",
+        "unsavedChanges": "Unsaved changes",
+        "editDetailsMenu": "Edit details"
       },
       "validation": {
         "nameRequired": "Workflow name is required",
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index fc0cdc10..40c4703c 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -1963,15 +1963,8 @@
         "saveFailed": "No se pudo guardar el flujo de trabajo",
         "defaultDescription": "Agente de flujo de trabajo: {{name}}",
         "newWorkflow": "Nuevo flujo de trabajo",
-        "editDetails": "Editar detalles del flujo de trabajo",
-        "workflowName": "Nombre del flujo de trabajo",
         "workflowNamePlaceholder": "Introduce el nombre del flujo de trabajo",
         "workflowDescriptionPlaceholder": "Describe qué hace este flujo de trabajo",
-        "agentImageAlt": "Imagen del agente",
-        "currentImage": "Imagen actual",
-        "agentImage": "Imagen del agente",
-        "agentImageHint": "Los cambios de imagen se incluyen la próxima vez que guardes.",
-        "done": "Listo",
         "unablePreview": "No se puede previsualizar el flujo de trabajo",
         "unableSave": "No se puede guardar el flujo de trabajo",
         "unablePublish": "No se puede publicar el flujo de trabajo",
@@ -1981,6 +1974,22 @@
         "setStateHint": "Modifica las variables del flujo de trabajo",
         "conditionHint": "Ramificación condicional",
         "codeHint": "Ejecuta código en un entorno aislado",
+        "paletteHint": "Arrástralo al lienzo o haz clic para añadirlo.",
+        "nodeActions": "Acciones del nodo",
+        "duplicateNode": "Duplicar",
+        "copyNodeId": "Copiar ID del nodo",
+        "knowledge": "Conocimiento",
+        "output": "Salida",
+        "streamToUserDescription": "Muestra la respuesta de este nodo en el chat mientras se escribe",
+        "advancedSettings": "Configuración avanzada",
+        "conditionMode": "Modo de condición",
+        "branchName": "Nombre de la rama",
+        "variable": "Variable",
+        "value": "Valor",
+        "valueCel": "Valor (CEL)",
+        "addCondition": "Añadir condición",
+        "assignment": "Asignación {{index}}",
+        "addAssignment": "Añadir asignación",
         "startNode": "Nodo de inicio",
         "endNode": "Nodo final",
         "stateTitle": "Establecer variables globales",
@@ -2009,7 +2018,7 @@
         "invalidSchema": "Esquema JSON no válido: {{error}}",
         "noteContent": "Contenido de la nota",
         "noteContentPlaceholder": "Introduce el contenido de la nota",
-        "stateIntro": "Asigna valores a las variables de estado del flujo de trabajo",
+        "stateIntro": "Asigna valores a las variables de estado del flujo de trabajo.",
         "assignValue": "Asignar valor",
         "celHint": "Usa Common Expression Language para crear una expresión personalizada. Haz referencia al estado por su nombre sin llaves (<code>query</code>), no <code>{{braced}}</code>.",
         "learnMore": "Más información",
@@ -2020,6 +2029,8 @@
         "caseNamePlaceholder": "Nombre del caso (opcional)",
         "variablePlaceholder": "Variable",
         "valuePlaceholder": "Valor",
+        "operator": "Operador",
+        "examplePlaceholder": "p. ej. {{example}}",
         "opContains": "contiene",
         "opStartsWith": "empieza",
         "conditionPlaceholder": "Introduce una condición, p. ej. query.contains(\"refund\")",
@@ -2031,7 +2042,11 @@
         "cannotDeleteStart": "No se puede eliminar el nodo de inicio",
         "deleteNode": "Eliminar nodo",
         "deleteConfirm": "¿Seguro que quieres eliminar «{{name}}»?",
-        "deleteConfirmUnnamed": "¿Seguro que quieres eliminar este agente de flujo de trabajo?"
+        "deleteConfirmUnnamed": "¿Seguro que quieres eliminar este agente de flujo de trabajo?",
+        "detailsTitle": "Detalles del flujo de trabajo",
+        "detailsDescription": "Nombre, descripción e imagen que se muestran en la tarjeta del agente.",
+        "unsavedChanges": "Cambios sin guardar",
+        "editDetailsMenu": "Editar detalles"
       },
       "validation": {
         "nameRequired": "El nombre del flujo de trabajo es obligatorio",
@@ -2124,7 +2139,10 @@
         "searchPlaceholder": "Buscar variables...",
         "empty": "No se encontraron variables",
         "addContext": "Añadir contexto"
-      }
+      },
+      "zoomIn": "Acercar",
+      "zoomOut": "Alejar",
+      "fitView": "Ajustar vista"
     },
     "typeModal": {
       "title": "Crear un agente nuevo",
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index 76ddede1..90386da1 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -1958,15 +1958,8 @@
         "saveFailed": "ワークフローを保存できませんでした",
         "defaultDescription": "ワークフローエージェント: {{name}}",
         "newWorkflow": "新しいワークフロー",
-        "editDetails": "ワークフローの詳細を編集",
-        "workflowName": "ワークフロー名",
         "workflowNamePlaceholder": "ワークフロー名を入力",
         "workflowDescriptionPlaceholder": "このワークフローの内容を説明してください",
-        "agentImageAlt": "エージェント画像",
-        "currentImage": "現在の画像",
-        "agentImage": "エージェント画像",
-        "agentImageHint": "画像の変更は次回の保存時に反映されます。",
-        "done": "完了",
         "unablePreview": "ワークフローをプレビューできません",
         "unableSave": "ワークフローを保存できません",
         "unablePublish": "ワークフローを公開できません",
@@ -1976,6 +1969,22 @@
         "setStateHint": "ワークフロー変数を変更",
         "conditionHint": "条件分岐",
         "codeHint": "サンドボックスでコードを実行",
+        "paletteHint": "キャンバスにドラッグするか、クリックして追加します。",
+        "nodeActions": "ノードの操作",
+        "duplicateNode": "複製",
+        "copyNodeId": "ノード ID をコピー",
+        "knowledge": "ナレッジ",
+        "output": "出力",
+        "streamToUserDescription": "このノードの回答を生成中にチャットへ表示します",
+        "advancedSettings": "詳細設定",
+        "conditionMode": "条件モード",
+        "branchName": "分岐名",
+        "variable": "変数",
+        "value": "値",
+        "valueCel": "値 (CEL)",
+        "addCondition": "条件を追加",
+        "assignment": "割り当て {{index}}",
+        "addAssignment": "割り当てを追加",
         "startNode": "開始ノード",
         "endNode": "終了ノード",
         "stateTitle": "グローバル変数を設定",
@@ -2004,7 +2013,7 @@
         "invalidSchema": "無効な JSON スキーマ: {{error}}",
         "noteContent": "メモの内容",
         "noteContentPlaceholder": "メモの内容を入力",
-        "stateIntro": "ワークフローの状態変数に値を割り当てます",
+        "stateIntro": "ワークフローの状態変数に値を割り当てます。",
         "assignValue": "値を割り当て",
         "celHint": "Common Expression Language でカスタム式を作成します。状態は名前だけで参照します（<code>query</code>）。<code>{{braced}}</code> ではありません。",
         "learnMore": "詳細",
@@ -2015,6 +2024,8 @@
         "caseNamePlaceholder": "ケース名（任意）",
         "variablePlaceholder": "変数",
         "valuePlaceholder": "値",
+        "operator": "演算子",
+        "examplePlaceholder": "例: {{example}}",
         "opContains": "含む",
         "opStartsWith": "で始まる",
         "conditionPlaceholder": "条件を入力（例: query.contains(\"refund\")）",
@@ -2026,7 +2037,11 @@
         "cannotDeleteStart": "開始ノードは削除できません",
         "deleteNode": "ノードを削除",
         "deleteConfirm": "「{{name}}」を削除してもよろしいですか？",
-        "deleteConfirmUnnamed": "このワークフローエージェントを削除してもよろしいですか？"
+        "deleteConfirmUnnamed": "このワークフローエージェントを削除してもよろしいですか？",
+        "detailsTitle": "ワークフローの詳細",
+        "detailsDescription": "エージェントカードに表示される名前、説明、画像です。",
+        "unsavedChanges": "未保存の変更",
+        "editDetailsMenu": "詳細を編集"
       },
       "validation": {
         "nameRequired": "ワークフロー名は必須です",
@@ -2119,7 +2134,10 @@
         "searchPlaceholder": "変数を検索...",
         "empty": "変数が見つかりません",
         "addContext": "コンテキストを追加"
-      }
+      },
+      "zoomIn": "拡大",
+      "zoomOut": "縮小",
+      "fitView": "全体を表示"
     },
     "typeModal": {
       "title": "新しいエージェントを作成",
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index 556a85d3..9ce855e9 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -2017,15 +2017,8 @@
         "saveFailed": "Не удалось сохранить рабочий процесс",
         "defaultDescription": "Агент рабочего процесса: {{name}}",
         "newWorkflow": "Новый рабочий процесс",
-        "editDetails": "Изменить сведения о рабочем процессе",
-        "workflowName": "Название рабочего процесса",
         "workflowNamePlaceholder": "Введите название рабочего процесса",
         "workflowDescriptionPlaceholder": "Опишите, что делает этот рабочий процесс",
-        "agentImageAlt": "Изображение агента",
-        "currentImage": "Текущее изображение",
-        "agentImage": "Изображение агента",
-        "agentImageHint": "Изменения изображения применятся при следующем сохранении.",
-        "done": "Готово",
         "unablePreview": "Не удалось запустить предпросмотр рабочего процесса",
         "unableSave": "Не удалось сохранить рабочий процесс",
         "unablePublish": "Не удалось опубликовать рабочий процесс",
@@ -2035,6 +2028,22 @@
         "setStateHint": "Изменение переменных рабочего процесса",
         "conditionHint": "Условное ветвление",
         "codeHint": "Запуск кода в песочнице",
+        "paletteHint": "Перетащите на холст или нажмите, чтобы добавить.",
+        "nodeActions": "Действия с узлом",
+        "duplicateNode": "Дублировать",
+        "copyNodeId": "Копировать ID узла",
+        "knowledge": "Знания",
+        "output": "Вывод",
+        "streamToUserDescription": "Показывать ответ этого узла в чате по мере написания",
+        "advancedSettings": "Дополнительные настройки",
+        "conditionMode": "Режим условия",
+        "branchName": "Название ветки",
+        "variable": "Переменная",
+        "value": "Значение",
+        "valueCel": "Значение (CEL)",
+        "addCondition": "Добавить условие",
+        "assignment": "Присваивание {{index}}",
+        "addAssignment": "Добавить присваивание",
         "startNode": "Начальный узел",
         "endNode": "Конечный узел",
         "stateTitle": "Задать глобальные переменные",
@@ -2063,7 +2072,7 @@
         "invalidSchema": "Некорректная JSON-схема: {{error}}",
         "noteContent": "Текст заметки",
         "noteContentPlaceholder": "Введите текст заметки",
-        "stateIntro": "Присвойте значения переменным состояния рабочего процесса",
+        "stateIntro": "Присвойте значения переменным состояния рабочего процесса.",
         "assignValue": "Присвоить значение",
         "celHint": "Используйте Common Expression Language, чтобы создать собственное выражение. Ссылайтесь на состояние по имени (<code>query</code>), а не <code>{{braced}}</code>.",
         "learnMore": "Подробнее",
@@ -2074,6 +2083,8 @@
         "caseNamePlaceholder": "Название варианта (необязательно)",
         "variablePlaceholder": "Переменная",
         "valuePlaceholder": "Значение",
+        "operator": "Оператор",
+        "examplePlaceholder": "напр. {{example}}",
         "opContains": "содержит",
         "opStartsWith": "начинается",
         "conditionPlaceholder": "Введите условие, например query.contains(\"refund\")",
@@ -2085,7 +2096,11 @@
         "cannotDeleteStart": "Начальный узел нельзя удалить",
         "deleteNode": "Удалить узел",
         "deleteConfirm": "Вы уверены, что хотите удалить «{{name}}»?",
-        "deleteConfirmUnnamed": "Вы уверены, что хотите удалить этого агента рабочего процесса?"
+        "deleteConfirmUnnamed": "Вы уверены, что хотите удалить этого агента рабочего процесса?",
+        "detailsTitle": "Сведения о рабочем процессе",
+        "detailsDescription": "Название, описание и изображение, которые показываются на карточке агента.",
+        "unsavedChanges": "Несохранённые изменения",
+        "editDetailsMenu": "Изменить сведения"
       },
       "validation": {
         "nameRequired": "Укажите название рабочего процесса",
@@ -2184,7 +2199,10 @@
         "searchPlaceholder": "Поиск переменных...",
         "empty": "Переменные не найдены",
         "addContext": "Добавить контекст"
-      }
+      },
+      "zoomIn": "Увеличить",
+      "zoomOut": "Уменьшить",
+      "fitView": "Уместить на экране"
     },
     "typeModal": {
       "title": "Создать нового агента",
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index 4b9a5170..c39b2240 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -1958,15 +1958,8 @@
         "saveFailed": "無法儲存工作流程",
         "defaultDescription": "工作流程代理：{{name}}",
         "newWorkflow": "新增工作流程",
-        "editDetails": "編輯工作流程詳細資料",
-        "workflowName": "工作流程名稱",
         "workflowNamePlaceholder": "輸入工作流程名稱",
         "workflowDescriptionPlaceholder": "描述此工作流程的用途",
-        "agentImageAlt": "代理圖片",
-        "currentImage": "目前圖片",
-        "agentImage": "代理圖片",
-        "agentImageHint": "圖片更新將於下次儲存時生效。",
-        "done": "完成",
         "unablePreview": "無法預覽工作流程",
         "unableSave": "無法儲存工作流程",
         "unablePublish": "無法發佈工作流程",
@@ -1976,6 +1969,22 @@
         "setStateHint": "修改工作流程變數",
         "conditionHint": "條件分支",
         "codeHint": "在沙箱中執行程式碼",
+        "paletteHint": "拖曳到畫布上，或點擊新增。",
+        "nodeActions": "節點操作",
+        "duplicateNode": "複製",
+        "copyNodeId": "複製節點 ID",
+        "knowledge": "知識",
+        "output": "輸出",
+        "streamToUserDescription": "在生成過程中將此節點的回答顯示在聊天中",
+        "advancedSettings": "進階設定",
+        "conditionMode": "條件模式",
+        "branchName": "分支名稱",
+        "variable": "變數",
+        "value": "值",
+        "valueCel": "值 (CEL)",
+        "addCondition": "新增條件",
+        "assignment": "指定 {{index}}",
+        "addAssignment": "新增指定",
         "startNode": "開始節點",
         "endNode": "結束節點",
         "stateTitle": "設定全域變數",
@@ -2004,7 +2013,7 @@
         "invalidSchema": "JSON Schema 無效：{{error}}",
         "noteContent": "備註內容",
         "noteContentPlaceholder": "輸入備註內容",
-        "stateIntro": "為工作流程的狀態變數指定值",
+        "stateIntro": "為工作流程的狀態變數指定值。",
         "assignValue": "指定值",
         "celHint": "使用 Common Expression Language 撰寫自訂運算式。直接以名稱參照狀態（<code>query</code>），而非 <code>{{braced}}</code>。",
         "learnMore": "瞭解更多",
@@ -2015,6 +2024,8 @@
         "caseNamePlaceholder": "分支名稱（選填）",
         "variablePlaceholder": "變數",
         "valuePlaceholder": "值",
+        "operator": "運算子",
+        "examplePlaceholder": "例如 {{example}}",
         "opContains": "包含",
         "opStartsWith": "開頭為",
         "conditionPlaceholder": "輸入條件，例如 query.contains(\"refund\")",
@@ -2026,7 +2037,11 @@
         "cannotDeleteStart": "無法刪除開始節點",
         "deleteNode": "刪除節點",
         "deleteConfirm": "確定要刪除「{{name}}」嗎？",
-        "deleteConfirmUnnamed": "確定要刪除此工作流程代理嗎？"
+        "deleteConfirmUnnamed": "確定要刪除此工作流程代理嗎？",
+        "detailsTitle": "工作流程詳細資料",
+        "detailsDescription": "顯示在代理卡片上的名稱、說明和圖片。",
+        "unsavedChanges": "未儲存的變更",
+        "editDetailsMenu": "編輯詳細資料"
       },
       "validation": {
         "nameRequired": "工作流程名稱為必填",
@@ -2119,7 +2134,10 @@
         "searchPlaceholder": "搜尋變數...",
         "empty": "找不到變數",
         "addContext": "新增內容"
-      }
+      },
+      "zoomIn": "放大",
+      "zoomOut": "縮小",
+      "fitView": "符合檢視"
     },
     "typeModal": {
       "title": "建立新代理",
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index ce9a846f..983f7019 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -1958,15 +1958,8 @@
         "saveFailed": "无法保存工作流",
         "defaultDescription": "工作流智能体：{{name}}",
         "newWorkflow": "新建工作流",
-        "editDetails": "编辑工作流详情",
-        "workflowName": "工作流名称",
         "workflowNamePlaceholder": "输入工作流名称",
         "workflowDescriptionPlaceholder": "描述此工作流的用途",
-        "agentImageAlt": "智能体图片",
-        "currentImage": "当前图片",
-        "agentImage": "智能体图片",
-        "agentImageHint": "图片更新将在下次保存时生效。",
-        "done": "完成",
         "unablePreview": "无法预览工作流",
         "unableSave": "无法保存工作流",
         "unablePublish": "无法发布工作流",
@@ -1976,6 +1969,22 @@
         "setStateHint": "修改工作流变量",
         "conditionHint": "条件分支",
         "codeHint": "在沙箱中运行代码",
+        "paletteHint": "拖到画布上，或点击添加。",
+        "nodeActions": "节点操作",
+        "duplicateNode": "复制",
+        "copyNodeId": "复制节点 ID",
+        "knowledge": "知识",
+        "output": "输出",
+        "streamToUserDescription": "在生成过程中将此节点的回答显示在聊天中",
+        "advancedSettings": "高级设置",
+        "conditionMode": "条件模式",
+        "branchName": "分支名称",
+        "variable": "变量",
+        "value": "值",
+        "valueCel": "值 (CEL)",
+        "addCondition": "添加条件",
+        "assignment": "赋值 {{index}}",
+        "addAssignment": "添加赋值",
         "startNode": "开始节点",
         "endNode": "结束节点",
         "stateTitle": "设置全局变量",
@@ -2004,7 +2013,7 @@
         "invalidSchema": "JSON Schema 无效：{{error}}",
         "noteContent": "备注内容",
         "noteContentPlaceholder": "输入备注内容",
-        "stateIntro": "为工作流的状态变量赋值",
+        "stateIntro": "为工作流的状态变量赋值。",
         "assignValue": "赋值",
         "celHint": "使用 Common Expression Language 编写自定义表达式。直接用名称引用状态（<code>query</code>），而不是 <code>{{braced}}</code>。",
         "learnMore": "了解更多",
@@ -2015,6 +2024,8 @@
         "caseNamePlaceholder": "分支名称（可选）",
         "variablePlaceholder": "变量",
         "valuePlaceholder": "值",
+        "operator": "运算符",
+        "examplePlaceholder": "例如 {{example}}",
         "opContains": "包含",
         "opStartsWith": "开头为",
         "conditionPlaceholder": "输入条件，例如 query.contains(\"refund\")",
@@ -2026,7 +2037,11 @@
         "cannotDeleteStart": "无法删除开始节点",
         "deleteNode": "删除节点",
         "deleteConfirm": "确定要删除“{{name}}”吗？",
-        "deleteConfirmUnnamed": "确定要删除此工作流智能体吗？"
+        "deleteConfirmUnnamed": "确定要删除此工作流智能体吗？",
+        "detailsTitle": "工作流详情",
+        "detailsDescription": "显示在代理卡片上的名称、描述和图片。",
+        "unsavedChanges": "未保存的更改",
+        "editDetailsMenu": "编辑详情"
       },
       "validation": {
         "nameRequired": "工作流名称为必填项",
@@ -2119,7 +2134,10 @@
         "searchPlaceholder": "搜索变量...",
         "empty": "未找到变量",
         "addContext": "添加上下文"
-      }
+      },
+      "zoomIn": "放大",
+      "zoomOut": "缩小",
+      "fitView": "适应视图"
     },
     "typeModal": {
       "title": "创建新智能体",

From 706a0cb2b2872a2336f1b6459ba9a4adca23a447 Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Mon, 28 Sep 2026 17:35:16 +0400
Subject: [PATCH 5/7] Big source revamp

---
 docsgpt/api/pat/rules.py                      |    4 +
 docsgpt/api/user/sources/chunks.py            |  105 +-
 docsgpt/api/user/sources/routes.py            |  182 ++-
 docsgpt/graphrag/store.py                     |  410 +++++-
 docsgpt/parser/remote/base.py                 |  150 +-
 docsgpt/parser/remote/crawler_loader.py       |   31 +-
 docsgpt/parser/remote/crawler_markdown.py     |   32 +-
 docsgpt/parser/remote/sitemap_loader.py       |   18 +-
 docsgpt/parser/remote/web_loader.py           |   20 +-
 docsgpt/vectorstore/base.py                   |   34 +
 docsgpt/vectorstore/faiss.py                  |   52 +
 docsgpt/vectorstore/mongodb.py                |   64 +-
 docsgpt/vectorstore/pgvector.py               |   54 +-
 docsgpt/vectorstore/qdrant.py                 |   44 +
 frontend/DESIGN.md                            |  249 +++-
 frontend/src/api/endpoints.ts                 |   13 +
 frontend/src/api/services/userService.ts      |    9 +
 frontend/src/components/ArtifactSidebar.tsx   |    3 +-
 frontend/src/components/Chunks.test.tsx       |  857 ++++++++++--
 frontend/src/components/Chunks.tsx            | 1231 +++++++++--------
 .../src/components/ConnectorTree.test.tsx     |  147 ++
 frontend/src/components/ConnectorTree.tsx     |   56 +-
 frontend/src/components/FileTree.tsx          |   22 +-
 frontend/src/components/GraphView.tsx         |  843 +++++++----
 frontend/src/components/MarkdownPreview.tsx   |    3 +-
 .../src/components/MultiSelectPopover.tsx     |    2 +-
 .../src/components/SourceMarkdown.test.tsx    |   55 +
 frontend/src/components/SourceMarkdown.tsx    |  128 ++
 frontend/src/components/WikiViewer.test.tsx   |  407 ++++++
 frontend/src/components/WikiViewer.tsx        |  554 +++++---
 frontend/src/components/chunkUtils.test.ts    |   75 +-
 frontend/src/components/chunkUtils.ts         |   46 +-
 .../components/graph/GraphCanvasControls.tsx  |   58 +
 .../components/graph/GraphChunkSheet.test.tsx |  214 +++
 .../src/components/graph/GraphChunkSheet.tsx  |  237 ++++
 .../src/components/graph/GraphEntities.tsx    |  350 +++++
 .../components/graph/GraphEntitySearch.tsx    |  191 +++
 .../components/graph/GraphNodePanel.test.tsx  |  459 ++++++
 .../src/components/graph/GraphNodePanel.tsx   |  419 ++++++
 .../components/graph/GraphSourceView.test.tsx |  573 ++++++++
 .../src/components/graph/GraphSourceView.tsx  |  293 ++++
 .../src/components/graph/GraphTypeDot.tsx     |   66 +
 .../components/graph/graphCanvasUtils.test.ts |  270 ++++
 .../src/components/graph/graphCanvasUtils.ts  |  281 ++++
 .../components/graph/useGraphNodeDetail.ts    |   69 +
 .../src/components/graphViewUtils.test.ts     |  242 +++-
 frontend/src/components/graphViewUtils.ts     |  247 +++-
 .../src/components/tree/PathHeader.test.tsx   |   59 +-
 frontend/src/components/tree/PathHeader.tsx   |  143 +-
 frontend/src/components/tree/ReaderPanel.tsx  |   45 +
 .../components/tree/SourceEditSheet.test.tsx  |  112 ++
 .../src/components/tree/SourceEditSheet.tsx   |  183 +++
 .../components/tree/SourceNavigator.test.tsx  |  175 +++
 .../src/components/tree/SourceNavigator.tsx   |  277 ++++
 .../src/components/tree/TreeBrowser.test.tsx  |  388 +++++-
 frontend/src/components/tree/TreeBrowser.tsx  |  750 +++++-----
 .../components/tree/navigatorUtils.test.ts    |  109 ++
 .../src/components/tree/navigatorUtils.ts     |  174 +++
 frontend/src/components/tree/types.ts         |    6 -
 frontend/src/components/ui/breadcrumb.tsx     |    7 +-
 frontend/src/components/ui/command.test.tsx   |   44 +
 frontend/src/components/ui/command.tsx        |   32 +-
 frontend/src/components/ui/form-field.tsx     |    9 +-
 frontend/src/components/ui/input.tsx          |   12 +-
 frontend/src/components/ui/list-row.test.tsx  |   11 +
 frontend/src/components/ui/list-row.tsx       |   13 +-
 frontend/src/components/ui/multi-select.tsx   |    1 -
 .../src/components/ui/pagination.test.tsx     |   16 +
 frontend/src/components/ui/pagination.tsx     |   10 +-
 frontend/src/components/ui/table.test.tsx     |   21 +
 frontend/src/components/ui/table.tsx          |   10 +-
 .../src/components/wikiViewerUtils.test.ts    |   65 +-
 frontend/src/components/wikiViewerUtils.ts    |   77 ++
 frontend/src/conversation/MarkdownAnswer.tsx  |   33 +-
 frontend/src/design/DesignSystem.tsx          |   90 +-
 frontend/src/lib/markdown.test.tsx            |   55 +-
 frontend/src/lib/markdown.tsx                 |   52 +
 frontend/src/locale/de.json                   |  110 +-
 frontend/src/locale/en.json                   |  110 +-
 frontend/src/locale/es.json                   |  110 +-
 frontend/src/locale/jp.json                   |  102 +-
 frontend/src/locale/ru.json                   |  126 +-
 frontend/src/locale/zh-TW.json                |  102 +-
 frontend/src/locale/zh.json                   |  102 +-
 frontend/src/settings/Sources.tsx             |    6 +-
 .../src/settings/components/UsageQuota.tsx    |    6 +-
 frontend/src/utils/dateTimeUtils.test.ts      |   24 +-
 frontend/src/utils/dateTimeUtils.ts           |   18 +
 tests/api/user/sources/test_chunks.py         |  274 +++-
 tests/api/user/sources/test_graph_view.py     |  321 +++++
 tests/api/user/sources/test_routes.py         |   43 +
 tests/graphrag/test_store.py                  |  614 ++++++++
 tests/parser/remote/test_base.py              |  133 ++
 tests/parser/remote/test_crawler_loader.py    |   25 +
 tests/parser/remote/test_crawler_markdown.py  |   25 +
 tests/parser/remote/test_sitemap_loader.py    |   23 +-
 tests/parser/remote/test_web_loader.py        |   47 +-
 tests/vectorstore/test_base.py                |   52 +
 tests/vectorstore/test_faiss.py               |   85 ++
 tests/vectorstore/test_mongodb.py             |  122 ++
 tests/vectorstore/test_pgvector.py            |   86 ++
 .../vectorstore/test_pgvector_live_schema.py  |   33 +
 tests/vectorstore/test_qdrant.py              |   77 ++
 103 files changed, 13687 insertions(+), 1937 deletions(-)
 create mode 100644 frontend/src/components/ConnectorTree.test.tsx
 create mode 100644 frontend/src/components/SourceMarkdown.test.tsx
 create mode 100644 frontend/src/components/SourceMarkdown.tsx
 create mode 100644 frontend/src/components/WikiViewer.test.tsx
 create mode 100644 frontend/src/components/graph/GraphCanvasControls.tsx
 create mode 100644 frontend/src/components/graph/GraphChunkSheet.test.tsx
 create mode 100644 frontend/src/components/graph/GraphChunkSheet.tsx
 create mode 100644 frontend/src/components/graph/GraphEntities.tsx
 create mode 100644 frontend/src/components/graph/GraphEntitySearch.tsx
 create mode 100644 frontend/src/components/graph/GraphNodePanel.test.tsx
 create mode 100644 frontend/src/components/graph/GraphNodePanel.tsx
 create mode 100644 frontend/src/components/graph/GraphSourceView.test.tsx
 create mode 100644 frontend/src/components/graph/GraphSourceView.tsx
 create mode 100644 frontend/src/components/graph/GraphTypeDot.tsx
 create mode 100644 frontend/src/components/graph/graphCanvasUtils.test.ts
 create mode 100644 frontend/src/components/graph/graphCanvasUtils.ts
 create mode 100644 frontend/src/components/graph/useGraphNodeDetail.ts
 create mode 100644 frontend/src/components/tree/ReaderPanel.tsx
 create mode 100644 frontend/src/components/tree/SourceEditSheet.test.tsx
 create mode 100644 frontend/src/components/tree/SourceEditSheet.tsx
 create mode 100644 frontend/src/components/tree/SourceNavigator.test.tsx
 create mode 100644 frontend/src/components/tree/SourceNavigator.tsx
 create mode 100644 frontend/src/components/tree/navigatorUtils.test.ts
 create mode 100644 frontend/src/components/tree/navigatorUtils.ts
 create mode 100644 tests/parser/remote/test_base.py

diff --git a/docsgpt/api/pat/rules.py b/docsgpt/api/pat/rules.py
index c1d7683d..cea33e79 100644
--- a/docsgpt/api/pat/rules.py
+++ b/docsgpt/api/pat/rules.py
@@ -201,6 +201,9 @@ RULES: dict[tuple[str, str], Rule] = {
     ("/api/agents/<string:agent_id>/schedules", "GET"): _rule(
         "schedules:read", refs=(("agents", (VIEW, "agent_id")),), blocked_by=_NON_AGENT_FAMILIES
     ),
+    ("/api/agents/<string:agent_id>/schedules/stats", "GET"): _rule(
+        "schedules:read", refs=(("agents", (VIEW, "agent_id")),), blocked_by=_NON_AGENT_FAMILIES
+    ),
     ("/api/agents/<string:agent_id>/schedules", "POST"): _rule(
         "schedules:write", refs=(("agents", (VIEW, "agent_id")),), blocked_by=_NON_AGENT_FAMILIES
     ),
@@ -225,6 +228,7 @@ RULES: dict[tuple[str, str], Rule] = {
     ("/api/sources/<string:source_id>/graph/node/<string:node_id>", "GET"): _rule(
         "sources:read", (VIEW, "source_id")
     ),
+    ("/api/sources/<string:source_id>/graph/nodes", "GET"): _rule("sources:read", (VIEW, "source_id")),
     # Ingestion and attachment extraction both report through this poll.
     ("/api/task_status", "GET"): _rule(any_of=("sources:read", "sources:write", "chat:run"), open=True),
     ("/api/upload", "POST"): _rule("sources:write"),
diff --git a/docsgpt/api/user/sources/chunks.py b/docsgpt/api/user/sources/chunks.py
index ae289aa6..240ed571 100644
--- a/docsgpt/api/user/sources/chunks.py
+++ b/docsgpt/api/user/sources/chunks.py
@@ -7,10 +7,11 @@ from flask_restx import fields, Namespace, Resource
 
 from docsgpt.api import api
 from docsgpt.api.user.base import get_vector_store
-from docsgpt.api.user.team_sharing import effective_write_owner
+from docsgpt.api.user.team_sharing import can_access, effective_write_owner
 from docsgpt.storage.db.repositories.sources import SourcesRepository
 from docsgpt.storage.db.session import db_readonly
 from docsgpt.utils import check_required_fields, num_tokens_from_string
+from docsgpt.vectorstore.base import InvalidChunkMetadataError
 
 sources_chunks_ns = Namespace(
     "sources", description="Source document management operations", path="/api"
@@ -18,12 +19,18 @@ sources_chunks_ns = Namespace(
 
 
 def _resolve_source(doc_id: str, user: str):
-    """Resolve a source (UUID or legacy ObjectId) for the caller.
+    """Resolve a source (UUID or legacy ObjectId) the caller may READ.
 
-    Returns the row dict (with PG UUID in ``id``) or ``None`` if missing.
+    Read access = owner or any team grant (viewer/editor). Returns the row
+    dict (with PG UUID in ``id``) or ``None`` if missing or not visible.
     """
     with db_readonly() as conn:
-        return SourcesRepository(conn).get_any(doc_id, user)
+        doc = SourcesRepository(conn).get_any(doc_id, user)
+        if doc is not None:
+            return doc
+        if not can_access(conn, "source", doc_id, user):
+            return None
+        return SourcesRepository(conn).get_by_id(doc_id)
 
 
 def _resolve_source_for_write(doc_id: str, user: str):
@@ -45,6 +52,35 @@ def _resolve_source_for_write(doc_id: str, user: str):
         return SourcesRepository(conn).get_any(doc_id, owner)
 
 
+def _remap_graph_chunk(doc: dict, old_chunk_id: str, new_chunk_id: str) -> None:
+    """Move a graphrag source's links from an edited chunk's old id to its new one.
+
+    Only needed when the store's ``update_chunk`` fell back to re-adding the
+    chunk under a new id (stores that update in place keep the id). Without
+    this the graph keeps pointing at the deleted row: the entity loses the
+    chunk and retrieval stops returning it. A failure is logged, not raised,
+    because the edit itself has already been saved.
+
+    Args:
+        doc: The resolved source row.
+        old_chunk_id: The edited chunk's previous id.
+        new_chunk_id: The id the edit was saved under.
+    """
+    from docsgpt.storage.db.source_config import SourceConfig
+
+    if SourceConfig.parse(doc.get("config")).kind != "graphrag":
+        return
+    try:
+        from docsgpt.graphrag.store import GraphStore
+
+        GraphStore().remap_chunk(str(doc["id"]), old_chunk_id, new_chunk_id)
+    except Exception as e:
+        current_app.logger.error(
+            f"Failed to remap graph links from chunk {old_chunk_id} to {new_chunk_id}: {e}",
+            exc_info=True,
+        )
+
+
 def _has_usable_token_count(metadata: dict) -> bool:
     """Whether ``metadata`` already carries a count worth showing.
 
@@ -98,6 +134,38 @@ def _with_token_counts(chunks: list) -> list:
     return chunks
 
 
+def _path_ends_with(value: str, path: str) -> bool:
+    """Return whether ``value`` is ``path`` or ends with it at a ``/`` boundary.
+
+    A bare ``endswith`` let a root ``setup.md`` also claim the chunks of
+    ``guides/setup.md`` (and ``a.md`` those of ``data.md``).
+    """
+    return bool(value) and (value == path or value.endswith(f"/{path}"))
+
+
+def _chunk_matches_path(metadata: dict, path: str) -> bool:
+    """Return whether a chunk belongs to the tree file at ``path``.
+
+    Args:
+        metadata: The chunk's stored metadata.
+        path: The file's key path in the source's ``directory_structure``.
+
+    Returns:
+        True when the chunk's ``source`` or ``file_path`` names that file, or
+        when the worker could only have keyed it by title: a remote ingest
+        (web page, Reddit post) whose chunks carry no ``file_path`` or ``key``
+        (see ``remote_worker``). Sources ingested that way stay browsable
+        without a re-ingest.
+    """
+    source = metadata.get("source") or ""
+    file_path = metadata.get("file_path") or ""
+    if _path_ends_with(source, path) or _path_ends_with(file_path, path):
+        return True
+    if "://" in source and not file_path and not metadata.get("key"):
+        return metadata.get("title") == path
+    return False
+
+
 @sources_chunks_ns.route("/get_chunks")
 class GetChunks(Resource):
     @api.doc(
@@ -141,14 +209,8 @@ class GetChunks(Resource):
             for chunk in chunks:
                 metadata = chunk.get("metadata", {})
 
-                if path:
-                    chunk_source = metadata.get("source", "")
-                    chunk_file_path = metadata.get("file_path", "")
-                    source_match = chunk_source and chunk_source.endswith(path)
-                    file_path_match = chunk_file_path and chunk_file_path.endswith(path)
-
-                    if not (source_match or file_path_match):
-                        continue
+                if path and not _chunk_matches_path(metadata, path):
+                    continue
                 if search_term:
                     text_match = search_term in chunk.get("text", "").lower()
                     title_match = search_term in metadata.get("title", "").lower()
@@ -339,13 +401,11 @@ class UpdateChunk(Resource):
             if text is not None:
                 new_metadata["token_count"] = num_tokens_from_string(new_text)
             try:
-                new_chunk_id = store.add_chunk(new_text, new_metadata)
-
-                deleted = store.delete_chunk(chunk_id)
-                if not deleted:
-                    current_app.logger.warning(
-                        f"Failed to delete old chunk {chunk_id}, but new chunk {new_chunk_id} was created"
-                    )
+                # In place where the store supports it (same id, same list
+                # position); the base fallback re-adds under a new id.
+                new_chunk_id = store.update_chunk(chunk_id, new_text, new_metadata)
+                if new_chunk_id != chunk_id:
+                    _remap_graph_chunk(doc, chunk_id, new_chunk_id)
                 return make_response(
                     jsonify(
                         {
@@ -356,8 +416,13 @@ class UpdateChunk(Resource):
                     ),
                     200,
                 )
+            except InvalidChunkMetadataError as meta_error:
+                current_app.logger.warning(
+                    f"Rejected metadata for chunk {chunk_id}: {meta_error}"
+                )
+                return make_response(jsonify({"error": "Invalid metadata"}), 400)
             except Exception as add_error:
-                current_app.logger.error(f"Failed to add updated chunk: {add_error}")
+                current_app.logger.error(f"Failed to update chunk {chunk_id}: {add_error}")
                 return make_response(
                     jsonify({"error": "Failed to update chunk - addition failed"}), 500
                 )
diff --git a/docsgpt/api/user/sources/routes.py b/docsgpt/api/user/sources/routes.py
index 6826c9e9..0930d689 100644
--- a/docsgpt/api/user/sources/routes.py
+++ b/docsgpt/api/user/sources/routes.py
@@ -545,7 +545,7 @@ class DirectoryStructure(Resource):
             return make_response(jsonify({"error": "Document ID is required"}), 400)
         try:
             with db_readonly() as conn:
-                doc = SourcesRepository(conn).get_any(doc_id, user)
+                doc = _resolve_readable_source(conn, doc_id, user)
             if not doc:
                 return make_response(
                     jsonify({"error": "Document not found or access denied"}), 404
@@ -1247,18 +1247,50 @@ class EnableSourceGraphRAG(Resource):
         )
 
 
-def _graph_overview_payload(source_id, limit):
-    """Return a bounded ``{nodes, edges}`` overview for a graphrag source.
+def _graph_overview_payload(source_id: str, limit: int) -> dict:
+    """Return a bounded ``{nodes, edges, stats}`` overview for a graphrag source.
 
     An empty graph (extraction pending/capped/failed) yields empty lists rather
-    than an error, mirroring the ClassicRAG degradation guarantee.
+    than an error, mirroring the ClassicRAG degradation guarantee, and skips
+    the overview query entirely. ``stats`` carries the whole graph's totals,
+    not the bounded overview's.
+
+    Args:
+        source_id: The resolved source id.
+        limit: Requested overview size; the store clamps it.
+
+    Returns:
+        dict: ``{"nodes": [...], "edges": [...], "stats": {"nodes": int,
+        "edges": int}}``.
     """
     from docsgpt.graphrag.store import GraphStore
 
     store = GraphStore()
-    if store.count_nodes(source_id) == 0:
-        return {"nodes": [], "edges": []}
-    return store.get_graph_overview(source_id, limit)
+    node_count = store.count_nodes(source_id)
+    if node_count == 0:
+        return {"nodes": [], "edges": [], "stats": {"nodes": 0, "edges": 0}}
+    overview = store.get_graph_overview(source_id, limit)
+    return {
+        "nodes": overview["nodes"],
+        "edges": overview["edges"],
+        "stats": {"nodes": node_count, "edges": store.count_edges(source_id)},
+    }
+
+
+def _int_arg(name: str, default: int) -> int:
+    """Read an integer query arg, falling back to ``default`` when unparsable.
+
+    Args:
+        name: Query-string parameter name.
+        default: Value used when the arg is missing or not an integer.
+
+    Returns:
+        int: The parsed value or ``default``.
+    """
+    try:
+        return int(request.args.get(name, default))
+    except (TypeError, ValueError):
+        return default
 
 
 @sources_ns.route("/sources/<string:source_id>/graph")
@@ -1310,6 +1342,142 @@ class SourceGraph(Resource):
                     "success": True,
                     "nodes": overview["nodes"],
                     "edges": overview["edges"],
+                    "stats": overview["stats"],
+                }
+            ),
+            200,
+        )
+
+
+def _graph_node_page(
+    source_id: str,
+    query: str | None,
+    type_key: str | None,
+    page: int,
+    per_page: int,
+) -> tuple[dict, list]:
+    """Return ``(listing, type_facets)`` for one page of a source's graph nodes.
+
+    A graph store that is not configured, or whose tables do not exist yet
+    (no graph has ever been built on this deployment), yields an empty page,
+    matching :func:`_graph_overview_payload`. Every other failure propagates,
+    so a broken query is never shown as an empty graph.
+
+    Args:
+        source_id: The resolved source id.
+        query: Name substring filter, or ``None``.
+        type_key: Type key filter, or ``None`` for no filter.
+        page: 1-based page, already clamped.
+        per_page: Page size, already clamped.
+
+    Returns:
+        tuple: ``({"nodes": [...], "total": int}, [{"key", "label", "count"}])``.
+
+    Raises:
+        Exception: Any store failure other than a missing store or schema.
+    """
+    import psycopg
+
+    from docsgpt.graphrag.store import GraphStore
+
+    empty = ({"nodes": [], "total": 0}, [])
+    try:
+        store = GraphStore()
+    except (ValueError, ImportError) as err:
+        current_app.logger.info("Graph store unavailable, listing no nodes: %s", err)
+        return empty
+    try:
+        listing = store.list_nodes(
+            source_id,
+            query=query,
+            type_key=type_key,
+            offset=(page - 1) * per_page,
+            limit=per_page,
+        )
+        types = store.node_type_facets(source_id)
+    except psycopg.errors.UndefinedTable as err:
+        current_app.logger.info("Graph tables missing, listing no nodes: %s", err)
+        return empty
+    return listing, types
+
+
+@sources_ns.route("/sources/<string:source_id>/graph/nodes")
+class SourceGraphNodes(Resource):
+    @api.doc(
+        description="Paged, searchable list of a graphrag source's nodes, "
+        "highest degree first, plus type facets over all its nodes (read "
+        "access: owner or shared). Query params: q (name substring), type "
+        "(type key), page (1-based), per_page (1-100, default 25)."
+    )
+    def get(self, source_id: str):
+        """List one page of a source's graph nodes with type facets.
+
+        Args:
+            source_id: The source id from the URL.
+
+        Returns:
+            Response: ``{success, nodes, total, page, per_page, types}``, or
+            401/404/400 on missing auth, no read access or a failure. ``page``
+            is clamped to ``1..GRAPH_NODE_LIST_MAX_PAGE`` and ``per_page`` to
+            ``1..GRAPH_NODE_LIST_MAX_LIMIT``. A graph store that is not
+            configured or has no tables yet reads as an empty page, like the
+            overview; any other store query failure is a 400, never an empty
+            200.
+        """
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        from docsgpt.graphrag.store import (
+            GRAPH_NODE_LIST_DEFAULT_LIMIT,
+            GRAPH_NODE_LIST_MAX_LIMIT,
+            GRAPH_NODE_LIST_MAX_PAGE,
+        )
+
+        page = max(1, min(_int_arg("page", 1), GRAPH_NODE_LIST_MAX_PAGE))
+        per_page = max(
+            1,
+            min(
+                _int_arg("per_page", GRAPH_NODE_LIST_DEFAULT_LIMIT),
+                GRAPH_NODE_LIST_MAX_LIMIT,
+            ),
+        )
+        query = (request.args.get("q") or "").strip() or None
+        type_key = request.args.get("type")
+        try:
+            with db_readonly() as conn:
+                doc = _resolve_readable_source(conn, source_id, user)
+                if doc is None:
+                    return make_response(
+                        jsonify({"success": False, "message": "Source not found"}),
+                        404,
+                    )
+                resolved_source_id = str(doc["id"])
+        except Exception as err:
+            current_app.logger.error(
+                f"Error resolving source {source_id} for graph nodes: {err}",
+                exc_info=True,
+            )
+            return make_response(jsonify({"success": False}), 400)
+        try:
+            listing, types = _graph_node_page(
+                resolved_source_id, query, type_key, page, per_page
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error listing graph nodes for {source_id}: {err}",
+                exc_info=True,
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(
+            jsonify(
+                {
+                    "success": True,
+                    "nodes": listing["nodes"],
+                    "total": listing["total"],
+                    "page": page,
+                    "per_page": per_page,
+                    "types": types,
                 }
             ),
             200,
diff --git a/docsgpt/graphrag/store.py b/docsgpt/graphrag/store.py
index 0b73d031..d19c94d1 100644
--- a/docsgpt/graphrag/store.py
+++ b/docsgpt/graphrag/store.py
@@ -39,8 +39,49 @@ MAX_SUBGRAPH_EDGES = 2000
 GRAPH_OVERVIEW_DEFAULT_LIMIT = 100
 GRAPH_OVERVIEW_MAX_LIMIT = 250
 
+GRAPH_NODE_LIST_DEFAULT_LIMIT = 25
+GRAPH_NODE_LIST_MAX_LIMIT = 100
+# Highest 1-based page the node-list route accepts. Keeps ``OFFSET`` (at most
+# ~1e8 rows at the max page size) far inside Postgres' bigint range, so a huge
+# ``page`` query arg yields an empty page with the real total, not an error.
+GRAPH_NODE_LIST_MAX_PAGE = 1_000_000
+
+MAX_NODE_RELATIONSHIPS = 300
+
 PGVECTOR_SOURCE_COLUMN = "source_id"
 
+def graph_type_key(type_value: Optional[str]) -> str:
+    """Return the grouping key for a node type.
+
+    ``"Person"``, ``"PERSON"`` and ``"per son"`` all fold to ``"person"``, so
+    the extractor's inconsistent spellings land in one facet. Computed in
+    Python on purpose, never in SQL: ``lower()`` and ``[:alnum:]`` follow the
+    database's ``LC_CTYPE``, and on a ``C``-locale database (common on managed
+    Postgres) they fold every Cyrillic or CJK type to ``""``. Must agree with
+    the frontend, which filters and colours by this key with
+    ``/[^\\p{L}\\p{N}]/gu`` and ``toLowerCase``.
+
+    Args:
+        type_value: The raw node type, possibly ``None`` or empty.
+
+    Returns:
+        str: The lower-cased type with non-alphanumerics removed; ``""`` for a
+        missing type.
+    """
+    return "".join(ch for ch in (type_value or "").lower() if ch.isalnum())
+
+
+def _escape_like(value: str) -> str:
+    """Escape ``value`` so ``LIKE``/``ILIKE`` treats it as a literal.
+
+    Args:
+        value: Raw user text.
+
+    Returns:
+        str: ``value`` with ``\\``, ``%`` and ``_`` backslash-escaped.
+    """
+    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
 
 def _safe_identifier(name: str) -> str:
     """Return ``name`` if it is a bare SQL identifier, else raise.
@@ -857,6 +898,174 @@ class GraphStore:
             cursor.close()
             conn.rollback()
 
+    def count_edges(self, source_id: str) -> int:
+        """Number of edges for a source.
+
+        Args:
+            source_id: Source whose edges to count.
+
+        Returns:
+            int: The edge count, or ``0`` when the query fails.
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                "SELECT count(*) FROM graph_edges WHERE source_id = %s;",
+                (source_id,),
+            )
+            return int(cursor.fetchone()[0])
+        except Exception as e:
+            logging.error(f"Error counting edges: {e}")
+            return 0
+        finally:
+            cursor.close()
+            conn.rollback()
+
+    def list_nodes(
+        self,
+        source_id: str,
+        query: Optional[str] = None,
+        type_key: Optional[str] = None,
+        offset: int = 0,
+        limit: int = GRAPH_NODE_LIST_DEFAULT_LIMIT,
+    ) -> Dict[str, Any]:
+        """One page of a source's nodes, highest degree first, with the match count.
+
+        Args:
+            source_id: Source whose nodes to list.
+            query: Case-insensitive substring of the node name; ``%``, ``_``
+                and ``\\`` match literally. Blank means no name filter.
+            type_key: Only nodes whose :func:`graph_type_key` equals this;
+                ``""`` selects untyped nodes and ``None`` applies no filter.
+            offset: Rows to skip (floored at 0).
+            limit: Page size, clamped to ``1..GRAPH_NODE_LIST_MAX_LIMIT``.
+
+        Returns:
+            dict: ``{"nodes": [{id, name, type, degree, doc_freq}], "total": int}``
+            where ``total`` counts every match, not just this page. A source
+            with no graph yields ``{"nodes": [], "total": 0}``.
+
+        Raises:
+            Exception: Any query failure, so a caller never mistakes a broken
+                query for an empty graph.
+        """
+        limit = max(1, min(int(limit), GRAPH_NODE_LIST_MAX_LIMIT))
+        offset = max(0, int(offset))
+        clauses = ["source_id = %s"]
+        params: List[Any] = [source_id]
+        clean = (query or "").strip()
+        if clean:
+            clauses.append("name ILIKE %s ESCAPE '\\'")
+            params.append(f"%{_escape_like(clean)}%")
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        try:
+            if type_key is not None:
+                # The key is folded in Python (see ``graph_type_key``), so the
+                # filter matches the raw spellings whose key equals it.
+                cursor.execute(
+                    "SELECT DISTINCT type FROM graph_nodes WHERE source_id = %s;",
+                    (source_id,),
+                )
+                raw_types = sorted(
+                    row[0]
+                    for row in cursor.fetchall()
+                    if row[0] is not None and graph_type_key(row[0]) == type_key
+                )
+                if type_key == "":
+                    clauses.append("(type IS NULL OR type = ANY(%s))")
+                elif not raw_types:
+                    return {"nodes": [], "total": 0}
+                else:
+                    clauses.append("type = ANY(%s)")
+                params.append(raw_types)
+            where = " AND ".join(clauses)
+            cursor.execute(
+                f"SELECT count(*) FROM graph_nodes WHERE {where};", tuple(params)
+            )
+            total = int(cursor.fetchone()[0])
+            cursor.execute(
+                f"""
+                SELECT id, name, type, degree, doc_freq
+                FROM graph_nodes
+                WHERE {where}
+                ORDER BY degree DESC, id
+                LIMIT %s OFFSET %s;
+                """,
+                (*params, limit, offset),
+            )
+            nodes = [
+                {
+                    "id": str(row[0]),
+                    "name": row[1],
+                    "type": row[2],
+                    "degree": row[3],
+                    "doc_freq": row[4],
+                }
+                for row in cursor.fetchall()
+            ]
+            return {"nodes": nodes, "total": total}
+        finally:
+            cursor.close()
+            conn.rollback()
+
+    def node_type_facets(self, source_id: str) -> List[Dict[str, Any]]:
+        """Node counts per type key over every node of a source.
+
+        Spellings that share a :func:`graph_type_key` are folded into one
+        facet labelled with the most frequent spelling (ties go to the
+        alphabetically first). Untyped nodes form the ``""`` facet with a
+        ``None`` label.
+
+        Args:
+            source_id: Source whose node types to count.
+
+        Returns:
+            list: ``[{"key", "label", "count"}]`` sorted by count descending,
+            then label. Empty for a source with no graph.
+
+        Raises:
+            Exception: Any query failure, so a caller never mistakes a broken
+                query for an empty graph.
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        try:
+            # Group by the raw spelling only; the key is folded in Python so it
+            # does not depend on the database locale (see ``graph_type_key``).
+            cursor.execute(
+                """
+                SELECT type, count(*)
+                FROM graph_nodes
+                WHERE source_id = %s
+                GROUP BY type;
+                """,
+                (source_id,),
+            )
+            rows = cursor.fetchall()
+        finally:
+            cursor.close()
+            conn.rollback()
+        spellings: Dict[str, List[tuple]] = {}
+        for raw_type, n in rows:
+            spellings.setdefault(graph_type_key(raw_type), []).append(
+                (int(n), raw_type)
+            )
+        facets = []
+        for key, variants in spellings.items():
+            label = None
+            if key:
+                # Most frequent spelling; a tie goes to the alphabetically first.
+                label = min(variants, key=lambda v: (-v[0], v[1]))[1]
+            facets.append(
+                {"key": key, "label": label, "count": sum(v[0] for v in variants)}
+            )
+        facets.sort(
+            key=lambda f: (-f["count"], f["label"] is None, f["label"] or "")
+        )
+        return facets
+
     def count_nodes_many(self, source_ids: List[str]) -> Dict[str, int]:
         """Node counts for several sources in one round trip.
 
@@ -1390,11 +1599,26 @@ class GraphStore:
     def get_node_detail(
         self, source_id: str, node_id: str, max_chunks: int = 20
     ) -> Optional[Dict[str, Any]]:
-        """A node's full record plus a bounded list of its linked chunks.
+        """A node's full record, its relationships and a bounded list of its chunks.
 
-        Returns ``None`` when the node does not belong to the source. Chunk texts
-        are read from the co-located pgvector table; at most ``max_chunks`` are
-        returned so a hub node never streams an unbounded payload.
+        Chunk texts are read from the co-located pgvector table; at most
+        ``max_chunks`` are returned so a hub node never streams an unbounded
+        payload. ``relationships`` holds every edge touching the node in either
+        direction (self-loops skipped), joined to the other endpoint, strongest
+        neighbour first and capped at ``MAX_NODE_RELATIONSHIPS``;
+        ``relationships_total`` is how many such edges there are, so a capped
+        list can say what it leaves out.
+
+        Args:
+            source_id: Source the node must belong to.
+            node_id: The node's id.
+            max_chunks: Most linked chunks to return.
+
+        Returns:
+            dict | None: ``{id, name, type, description, degree, doc_freq,
+            relationships: [{id, name, type, degree, edge_type, direction}],
+            relationships_total, chunks: [{chunk_id, text, metadata}]}``; ``None`` when the node does
+            not belong to the source or the read fails.
         """
         conn = self._get_connection()
         try:
@@ -1421,6 +1645,15 @@ class GraphStore:
                 "degree": row[4],
                 "doc_freq": row[5],
             }
+            relationships = self._node_relationships(conn, source_id, node_id)
+            node["relationships"] = relationships
+            node["relationships_total"] = (
+                self._node_relationships_total(
+                    conn, source_id, node_id, len(relationships)
+                )
+                if len(relationships) >= MAX_NODE_RELATIONSHIPS
+                else len(relationships)
+            )
 
             chunk_ids = self.get_chunk_ids_for_nodes(source_id, [node_id]).get(
                 str(node_id), []
@@ -1443,6 +1676,107 @@ class GraphStore:
         finally:
             conn.rollback()
 
+    def _node_relationships(
+        self, conn, source_id: str, node_id: str
+    ) -> List[Dict[str, Any]]:
+        """Edges touching ``node_id``, joined to the neighbour at the other end.
+
+        Args:
+            conn: Open connection; the caller owns the transaction.
+            source_id: Source the edges and neighbours must belong to.
+            node_id: The node whose relationships to read.
+
+        Returns:
+            list: ``[{id, name, type, degree, edge_type, direction}]`` where
+            ``direction`` is ``"out"`` when the node is the edge's source,
+            ordered by neighbour degree descending, neighbour id, edge type.
+            Empty when the read fails (the transaction is rolled back).
+        """
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                """
+                SELECT o.id, o.name, o.type, o.degree, e.type,
+                       CASE WHEN e.src_node_id = %s THEN 'out' ELSE 'in' END AS direction
+                FROM graph_edges e
+                JOIN graph_nodes o
+                  ON o.id = CASE WHEN e.src_node_id = %s
+                                 THEN e.dst_node_id ELSE e.src_node_id END
+                WHERE e.source_id = %s
+                  AND (e.src_node_id = %s OR e.dst_node_id = %s)
+                  AND e.src_node_id <> e.dst_node_id
+                  AND o.source_id = %s
+                ORDER BY o.degree DESC, o.id, e.type
+                LIMIT %s;
+                """,
+                (
+                    node_id, node_id, source_id, node_id, node_id, source_id,
+                    MAX_NODE_RELATIONSHIPS,
+                ),
+            )
+            return [
+                {
+                    "id": str(row[0]),
+                    "name": row[1],
+                    "type": row[2],
+                    "degree": row[3],
+                    "edge_type": row[4],
+                    "direction": row[5],
+                }
+                for row in cursor.fetchall()
+            ]
+        except Exception as e:
+            # Degrade to no relationships rather than failing the whole node
+            # detail; roll back so the caller's chunk read can reuse ``conn``.
+            logging.error(f"Error reading node relationships: {e}")
+            conn.rollback()
+            return []
+        finally:
+            cursor.close()
+
+    def _node_relationships_total(
+        self, conn, source_id: str, node_id: str, fallback: int
+    ) -> int:
+        """How many edges ``_node_relationships`` would return without its cap.
+
+        Same filters as the list: either direction, self-loops skipped, the
+        neighbour in the same source.
+
+        Args:
+            conn: Open connection; the caller owns the transaction.
+            source_id: Source the edges and neighbours must belong to.
+            node_id: The node whose relationships to count.
+            fallback: What to return when the count fails (the list's length).
+
+        Returns:
+            int: The edge count, or ``fallback`` when the read fails (the
+            transaction is rolled back).
+        """
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                """
+                SELECT COUNT(*)
+                FROM graph_edges e
+                JOIN graph_nodes o
+                  ON o.id = CASE WHEN e.src_node_id = %s
+                                 THEN e.dst_node_id ELSE e.src_node_id END
+                WHERE e.source_id = %s
+                  AND (e.src_node_id = %s OR e.dst_node_id = %s)
+                  AND e.src_node_id <> e.dst_node_id
+                  AND o.source_id = %s;
+                """,
+                (node_id, source_id, node_id, node_id, source_id),
+            )
+            row = cursor.fetchone()
+            return int(row[0]) if row else fallback
+        except Exception as e:
+            logging.error(f"Error counting node relationships: {e}")
+            conn.rollback()
+            return fallback
+        finally:
+            cursor.close()
+
     def set_node_degrees(self, source_id: str):
         """Recompute every node's degree from its incident edges for a source.
 
@@ -1506,6 +1840,74 @@ class GraphStore:
 
         return self._write_with_reconnect(_write)
 
+    def remap_chunk(self, source_id: str, old_chunk_id: str, new_chunk_id: str) -> None:
+        """Point every graph reference to a chunk at its replacement id.
+
+        A chunk edit re-adds the chunk under a new id and deletes the old row,
+        so without this the node links, edge provenance and extraction
+        checkpoint would all name a chunk that no longer exists. The graph
+        itself is not re-extracted from the edited text.
+
+        Args:
+            source_id: Source the chunk belongs to.
+            old_chunk_id: The id the graph currently references.
+            new_chunk_id: The id of the chunk that replaced it.
+
+        Raises:
+            Exception: The underlying write failure, after a rollback.
+        """
+        self._ensure_tables_once()
+        old_id, new_id = str(old_chunk_id), str(new_chunk_id)
+
+        def _write(conn):
+            cursor = conn.cursor()
+            try:
+                _lock_source(cursor, source_id)
+                cursor.execute(
+                    """
+                    UPDATE graph_node_chunks SET chunk_id = %s
+                    WHERE source_id = %s AND chunk_id = %s;
+                    """,
+                    (new_id, source_id, old_id),
+                )
+                # Rewrite the matching element in place, keeping array order.
+                cursor.execute(
+                    """
+                    UPDATE graph_edges
+                    SET source_chunk_ids = (
+                        SELECT jsonb_agg(
+                            CASE WHEN t.v #>> '{}' = %s THEN to_jsonb(%s::text) ELSE t.v END
+                            ORDER BY t.ord
+                        )
+                        FROM jsonb_array_elements(source_chunk_ids)
+                             WITH ORDINALITY AS t(v, ord)
+                    )
+                    WHERE source_id = %s
+                      AND jsonb_typeof(source_chunk_ids) = 'array'
+                      AND EXISTS (
+                          SELECT 1 FROM jsonb_array_elements(source_chunk_ids) AS s(v)
+                          WHERE s.v #>> '{}' = %s
+                      );
+                    """,
+                    (old_id, new_id, source_id, old_id),
+                )
+                cursor.execute(
+                    """
+                    UPDATE graph_ingest_progress SET chunk_id = %s
+                    WHERE source_id = %s AND chunk_id = %s;
+                    """,
+                    (new_id, source_id, old_id),
+                )
+                conn.commit()
+            except Exception as e:
+                _safe_rollback(conn)
+                logging.error(f"Error remapping graph chunk: {e}")
+                raise
+            finally:
+                cursor.close()
+
+        return self._write_with_reconnect(_write)
+
     def pending_chunks(self, source_id: str, all_chunk_ids: List[str]) -> List[str]:
         """Chunk ids from ``all_chunk_ids`` not yet marked ``done`` for the source."""
         if not all_chunk_ids:
diff --git a/docsgpt/parser/remote/base.py b/docsgpt/parser/remote/base.py
index 5030ccc9..2cbfaf37 100644
--- a/docsgpt/parser/remote/base.py
+++ b/docsgpt/parser/remote/base.py
@@ -1,10 +1,158 @@
 """Base reader class."""
+import hashlib
+import os
+import re
 from abc import abstractmethod
-from typing import Any, List
+from typing import Any, Dict, List
+from urllib.parse import parse_qsl, urldefrag, urlencode, urlparse
 
 from docsgpt.parser.schema.base import Document
 from docsgpt.vectorstore.document_class import Document as VectorDocument
 
+_PAGE_EXTENSIONS = (".html", ".htm", ".php", ".asp", ".aspx", ".jsp")
+
+# Joins a page's path to its encoded query string in the virtual file name.
+_QUERY_SEPARATOR = "__"
+# Longest encoded query kept verbatim; longer ones keep a prefix plus a hash.
+MAX_QUERY_SEGMENT_LENGTH = 64
+_QUERY_HASH_LENGTH = 10
+# Anything but letters, digits, ``_``, ``.`` and ``-`` in a query key or value.
+_UNSAFE_QUERY_CHARS = re.compile(r"[^\w.-]+")
+
+
+def _query_segment(query: str) -> str:
+    """Encode a URL query string as a deterministic, tree-safe name segment.
+
+    Parameters are sorted so the same page maps to the same name across
+    re-syncs whatever order its links list them in. Keys and values are
+    percent-decoded and every run of characters outside ``[\\w.-]`` becomes
+    ``-``, so the segment carries no ``/``, ``?``, ``#`` or ``%``. A segment
+    longer than ``MAX_QUERY_SEGMENT_LENGTH`` keeps a prefix and a hash of the
+    full query, which keeps it bounded and still distinct.
+
+    Args:
+        query: The raw query string, without the leading ``?``.
+
+    Returns:
+        The encoded segment, or ``""`` when the query has no parameters.
+    """
+    pairs = sorted(parse_qsl(query, keep_blank_values=True))
+    if not pairs:
+        return ""
+    parts = []
+    for key, value in pairs:
+        key = _UNSAFE_QUERY_CHARS.sub("-", key)
+        value = _UNSAFE_QUERY_CHARS.sub("-", value)
+        parts.append(f"{key}={value}" if value else key)
+    segment = "&".join(parts)
+    if len(segment) <= MAX_QUERY_SEGMENT_LENGTH:
+        return segment
+    digest = hashlib.sha1(urlencode(pairs).encode("utf-8")).hexdigest()
+    keep = MAX_QUERY_SEGMENT_LENGTH - _QUERY_HASH_LENGTH - 1
+    return f"{segment[:keep]}-{digest[:_QUERY_HASH_LENGTH]}"
+
+
+def url_to_virtual_path(url: str, include_host: bool = False) -> str:
+    """Convert a page URL to the virtual ``.md`` path used as its tree key.
+
+    Web ingests store this as the chunk's ``file_path``: the worker keys the
+    source's file tree by it and the chunks view filters by it, so the two
+    agree on which chunks belong to which file.
+
+    The fragment is dropped (it names a spot on the same page), but the query
+    string is kept, encoded into the file name (see ``_query_segment``), so
+    ``/p?page=1`` and ``/p?page=2`` stay two files. A URL without a query maps
+    exactly as before. Paths that still collide, such as ``/a`` and
+    ``/a.html``, are told apart by ``dedupe_virtual_paths``.
+
+    Args:
+        url: Page URL, e.g. ``"https://docs.docsgpt.cloud/guides/setup"``.
+        include_host: Prefix the host, for ingests spanning several hosts
+            whose paths would otherwise collide (every root is ``index.md``).
+
+    Returns:
+        A relative path such as ``"index.md"``, ``"guides/setup.md"``,
+        ``"list__page=2.md"`` or, with ``include_host``,
+        ``"docs.docsgpt.cloud/guides/setup.md"``.
+    """
+    parsed = urlparse(url)
+    path = parsed.path.strip("/")
+
+    if not path:
+        path = "index.md"
+    else:
+        base, ext = os.path.splitext(path)
+        if ext.lower() in _PAGE_EXTENSIONS:
+            path = base
+        if not path.endswith(".md"):
+            path = f"{path}.md"
+
+    query = _query_segment(parsed.query)
+    if query:
+        path = f"{path[:-len('.md')]}{_QUERY_SEPARATOR}{query}.md"
+
+    if include_host and parsed.netloc:
+        return f"{parsed.netloc}/{path}"
+    return path
+
+
+def spans_multiple_hosts(urls: List[str]) -> bool:
+    """Return whether ``urls`` point at more than one host.
+
+    Args:
+        urls: Page URLs about to be ingested together.
+
+    Returns:
+        True when paths alone could collide and need a host prefix.
+    """
+    return len({urlparse(u).netloc for u in urls}) > 1
+
+
+def dedupe_virtual_paths(documents: List[Document]) -> List[Document]:
+    """Give distinct pages that share a virtual ``file_path`` distinct ones.
+
+    ``url_to_virtual_path`` folds some different URLs onto one path (``/a`` and
+    ``/a.html`` are both ``a.md``), and the worker would then merge those pages
+    into one tree entry. Within a path, the pages are ordered by URL (fragment
+    dropped): the first keeps the path and each later one gets ``-2``, ``-3``
+    and so on before ``.md``, skipping any path another page already has.
+    Ordering by URL rather than by fetch order keeps the names stable across
+    re-syncs of the same pages. Documents for the same URL (one page reached
+    via two fragments) are one page and keep one path.
+
+    Args:
+        documents: Loaded documents; each ``extra_info`` carries ``source``
+            (the page URL) and ``file_path``. Others are left untouched.
+
+    Returns:
+        ``documents``, with colliding ``file_path`` values rewritten in place.
+    """
+    pages_by_path: Dict[str, Dict[str, List[Document]]] = {}
+    for doc in documents:
+        info = doc.extra_info or {}
+        path = info.get("file_path")
+        if not path:
+            continue
+        page = urldefrag(str(info.get("source") or path))[0]
+        pages_by_path.setdefault(path, {}).setdefault(page, []).append(doc)
+
+    taken = set(pages_by_path)
+    for path in sorted(pages_by_path):
+        pages = pages_by_path[path]
+        if len(pages) < 2:
+            continue
+        stem = path[: -len(".md")] if path.endswith(".md") else path
+        suffix = 1
+        for page in sorted(pages)[1:]:
+            suffix += 1
+            while f"{stem}-{suffix}.md" in taken:
+                suffix += 1
+            new_path = f"{stem}-{suffix}.md"
+            taken.add(new_path)
+            for doc in pages[page]:
+                doc.extra_info["file_path"] = new_path
+    return documents
+
 
 class BaseRemote:
     """Utilities for loading data from a directory."""
diff --git a/docsgpt/parser/remote/crawler_loader.py b/docsgpt/parser/remote/crawler_loader.py
index f75f054a..e6d2b8d5 100644
--- a/docsgpt/parser/remote/crawler_loader.py
+++ b/docsgpt/parser/remote/crawler_loader.py
@@ -1,9 +1,8 @@
 import logging
-import os
 from bs4 import BeautifulSoup
 from urllib.parse import urljoin, urlparse
 
-from docsgpt.parser.remote.base import BaseRemote
+from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, url_to_virtual_path
 from docsgpt.parser.schema.base import Document
 from docsgpt.core.url_validation import validate_url, SSRFError
 from docsgpt.security.safe_url import pinned_request
@@ -73,30 +72,8 @@ class CrawlerLoader(BaseRemote):
             if self.limit is not None and len(visited_urls) >= self.limit:
                 break
 
-        return loaded_content
+        return dedupe_virtual_paths(loaded_content)
 
     def _url_to_virtual_path(self, url):
-        """
-        Convert a URL to a virtual file path ending with .md.
-
-        Examples:
-            https://docs.docsgpt.cloud/ -> index.md
-            https://docs.docsgpt.cloud/guides/setup -> guides/setup.md
-            https://docs.docsgpt.cloud/guides/setup/ -> guides/setup.md
-            https://example.com/page.html -> page.md
-        """
-        parsed = urlparse(url)
-        path = parsed.path.strip("/")
-
-        if not path:
-            return "index.md"
-
-        # Remove common file extensions and add .md
-        base, ext = os.path.splitext(path)
-        if ext.lower() in [".html", ".htm", ".php", ".asp", ".aspx", ".jsp"]:
-            path = base
-
-        if not path.endswith(".md"):
-            path = f"{path}.md"
-
-        return path
+        """Convert a URL to a virtual ``.md`` path; see ``url_to_virtual_path``."""
+        return url_to_virtual_path(url)
diff --git a/docsgpt/parser/remote/crawler_markdown.py b/docsgpt/parser/remote/crawler_markdown.py
index b2de5cbb..db8693cc 100644
--- a/docsgpt/parser/remote/crawler_markdown.py
+++ b/docsgpt/parser/remote/crawler_markdown.py
@@ -1,13 +1,12 @@
 from urllib.parse import urlparse, urljoin
 from bs4 import BeautifulSoup
-from docsgpt.parser.remote.base import BaseRemote
+from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, url_to_virtual_path
 from docsgpt.core.url_validation import validate_url, SSRFError
 from docsgpt.security.safe_url import UnsafeUserUrlError, pinned_request
 import re
 from markdownify import markdownify
 from docsgpt.parser.schema.base import Document
 import tldextract
-import os
 
 # The bundled public-suffix snapshot is enough for domain matching; the
 # default extractor would fetch the live list on first use and cache it on
@@ -91,7 +90,7 @@ class CrawlerLoader(BaseRemote):
             if self.limit is not None and len(visited_urls) >= self.limit:
                 break
 
-        return documents
+        return dedupe_virtual_paths(documents)
 
     def _fetch_page(self, url):
         try:
@@ -160,28 +159,5 @@ class CrawlerLoader(BaseRemote):
         return filtered
 
     def _url_to_virtual_path(self, url):
-        """
-        Convert a URL to a virtual file path ending with .md.
-
-        Examples:
-            https://docs.docsgpt.cloud/ -> index.md
-            https://docs.docsgpt.cloud/guides/setup -> guides/setup.md
-            https://docs.docsgpt.cloud/guides/setup/ -> guides/setup.md
-            https://example.com/page.html -> page.md
-        """
-        parsed = urlparse(url)
-        path = parsed.path.strip("/")
-
-        if not path:
-            return "index.md"
-
-        # Remove common file extensions and add .md
-        base, ext = os.path.splitext(path)
-        if ext.lower() in [".html", ".htm", ".php", ".asp", ".aspx", ".jsp"]:
-            path = base
-
-        # Ensure path ends with .md
-        if not path.endswith(".md"):
-            path = path + ".md"
-
-        return path
\ No newline at end of file
+        """Convert a URL to a virtual ``.md`` path; see ``url_to_virtual_path``."""
+        return url_to_virtual_path(url)
diff --git a/docsgpt/parser/remote/sitemap_loader.py b/docsgpt/parser/remote/sitemap_loader.py
index a8500c79..fa686b28 100644
--- a/docsgpt/parser/remote/sitemap_loader.py
+++ b/docsgpt/parser/remote/sitemap_loader.py
@@ -4,7 +4,12 @@ import re
 import defusedxml.ElementTree as ET
 from bs4 import BeautifulSoup
 
-from docsgpt.parser.remote.base import BaseRemote
+from docsgpt.parser.remote.base import (
+    BaseRemote,
+    dedupe_virtual_paths,
+    spans_multiple_hosts,
+    url_to_virtual_path,
+)
 from docsgpt.parser.schema.base import Document
 from docsgpt.core.url_validation import validate_url, SSRFError
 from docsgpt.security.safe_url import UnsafeUserUrlError, pinned_request
@@ -32,6 +37,7 @@ class SitemapLoader(BaseRemote):
             return []
 
         # Load content of extracted URLs
+        include_host = spans_multiple_hosts(urls)
         documents = []
         processed_urls = 0  # Counter for processed URLs
         for url in urls:
@@ -50,7 +56,13 @@ class SitemapLoader(BaseRemote):
                 documents.append(
                     Document(
                         soup.get_text(separator="\n", strip=True),
-                        extra_info={"source": url},
+                        # Without file_path the worker had no tree key (no
+                        # title, key or doc_id), so sitemap pages never
+                        # appeared in the file tree.
+                        extra_info={
+                            "source": url,
+                            "file_path": url_to_virtual_path(url, include_host),
+                        },
                     )
                 )
                 processed_urls += 1  # Increment the counter after processing each URL
@@ -58,7 +70,7 @@ class SitemapLoader(BaseRemote):
                 logging.error(f"Error processing URL {url}: {e}", exc_info=True)
                 continue
 
-        return documents
+        return dedupe_virtual_paths(documents)
 
     def _extract_urls(self, sitemap_url):
         try:
diff --git a/docsgpt/parser/remote/web_loader.py b/docsgpt/parser/remote/web_loader.py
index a5a19e49..1eacbc8b 100644
--- a/docsgpt/parser/remote/web_loader.py
+++ b/docsgpt/parser/remote/web_loader.py
@@ -3,7 +3,12 @@ import logging
 from bs4 import BeautifulSoup
 
 from docsgpt.core.url_validation import SSRFError, validate_url
-from docsgpt.parser.remote.base import BaseRemote
+from docsgpt.parser.remote.base import (
+    BaseRemote,
+    dedupe_virtual_paths,
+    spans_multiple_hosts,
+    url_to_virtual_path,
+)
 from docsgpt.parser.schema.base import Document
 from docsgpt.security.safe_url import pinned_request
 
@@ -24,15 +29,17 @@ class WebLoader(BaseRemote):
         urls = inputs
         if isinstance(urls, str):
             urls = [urls]
-        documents = []
+        valid_urls = []
         for url in urls:
             try:
-                url = validate_url(url)
+                valid_urls.append(validate_url(url))
             except SSRFError as e:
                 logging.warning(
                     f"Skipping URL due to SSRF validation failure: {url} - {e}"
                 )
-                continue
+        include_host = spans_multiple_hosts(valid_urls)
+        documents = []
+        for url in valid_urls:
             try:
                 response = pinned_request("GET", url, headers=headers, timeout=30)
                 response.raise_for_status()
@@ -45,6 +52,9 @@ class WebLoader(BaseRemote):
                 html_tag = soup.find("html")
                 if html_tag and html_tag.get("lang"):
                     metadata["language"] = html_tag.get("lang")
+                # The worker keys the file tree by file_path; without it the
+                # tree fell back to the title, which the chunks view can't match.
+                metadata["file_path"] = url_to_virtual_path(url, include_host)
                 documents.append(
                     Document(
                         soup.get_text(separator="\n", strip=True),
@@ -54,4 +64,4 @@ class WebLoader(BaseRemote):
             except Exception as e:
                 logging.error(f"Error processing URL {url}: {e}", exc_info=True)
                 continue
-        return documents
+        return dedupe_virtual_paths(documents)
diff --git a/docsgpt/vectorstore/base.py b/docsgpt/vectorstore/base.py
index d0c63c04..348f99e5 100644
--- a/docsgpt/vectorstore/base.py
+++ b/docsgpt/vectorstore/base.py
@@ -362,6 +362,14 @@ def build_local_embeddings(
     return embedding_instance
 
 
+class InvalidChunkMetadataError(ValueError):
+    """Chunk metadata the store cannot write, such as a key it reserves.
+
+    A client-input error, distinct from a store or embedding failure: the
+    chunk routes answer it with a 400 rather than a 500.
+    """
+
+
 class BaseVectorStore(ABC):
     def __init__(self):
         pass
@@ -431,6 +439,32 @@ class BaseVectorStore(ABC):
         """Delete a specific chunk from the vectorstore"""
         pass
 
+    def update_chunk(self, chunk_id: str, text: str, metadata: dict) -> str:
+        """Replace a chunk's text and metadata, returning the id it is now under.
+
+        Stores that can rewrite a row in place override this and keep both the
+        id and the chunk's position in :meth:`get_chunks`. This default works
+        for any store but re-adds the chunk and deletes the old one, so the
+        returned id differs and the chunk moves; callers holding the old id
+        (graph links, for one) must follow the returned id.
+
+        Args:
+            chunk_id: Id of the chunk to replace.
+            text: The chunk's new text.
+            metadata: The chunk's complete new metadata.
+
+        Returns:
+            The id the updated chunk is stored under.
+        """
+        new_chunk_id = self.add_chunk(text, metadata)
+        if not self.delete_chunk(chunk_id):
+            logging.warning(
+                "Failed to delete old chunk %s, but new chunk %s was created",
+                chunk_id,
+                new_chunk_id,
+            )
+        return new_chunk_id
+
     def delete_chunks_by_source_path(self, path) -> int:
         """Delete every chunk whose ``metadata.source`` equals ``path``.
 
diff --git a/docsgpt/vectorstore/faiss.py b/docsgpt/vectorstore/faiss.py
index 03dc4dd6..0c2d1aba 100644
--- a/docsgpt/vectorstore/faiss.py
+++ b/docsgpt/vectorstore/faiss.py
@@ -306,6 +306,58 @@ class FaissStore(BaseVectorStore):
         self._save_to_storage()
         return ids[0]
 
+    def update_chunk(self, chunk_id: str, text: str, metadata: Dict[str, Any]) -> str:
+        """Replace a chunk in place, keeping its id and its place in the docstore.
+
+        The new vector is computed before anything changes, so a failed embed
+        leaves the chunk as it was. Its old row is removed from the index and
+        the new vector appended; the row mapping is renumbered to match, and
+        the docstore entry is replaced where it stands so :meth:`get_chunks`
+        keeps its order. Saved to storage once.
+
+        Args:
+            chunk_id: Id of the chunk to replace.
+            text: The chunk's new text.
+            metadata: The chunk's complete new metadata.
+
+        Returns:
+            ``chunk_id``, unchanged.
+
+        Raises:
+            KeyError: If ``chunk_id`` is not in this index.
+            ValueError: If the new vector's width does not match the index.
+        """
+        if chunk_id not in self.documents:
+            raise KeyError(f"Chunk id not found in index: {chunk_id}")
+        rows_by_id = {doc_id: row for row, doc_id in self.index_to_docstore_id.items()}
+        if chunk_id not in rows_by_id:
+            raise KeyError(f"Chunk id has no row in the FAISS index: {chunk_id}")
+
+        vector = np.array(self.embeddings.embed_documents([text]), dtype=np.float32)
+        if vector.ndim != 2 or vector.shape != (1, self.index.d):
+            raise ValueError(
+                f"Embedding for chunk {chunk_id} has shape {vector.shape}, "
+                f"expected (1, {self.index.d})"
+            )
+
+        row = rows_by_id[chunk_id]
+        self.index.remove_ids(np.array([row], dtype=np.int64))
+        self.index.add(vector)
+        # remove_ids compacts the index and add appends, so the edited chunk's
+        # vector is now the last row; renumber as delete_index does.
+        remaining = [
+            doc_id
+            for current_row, doc_id in sorted(self.index_to_docstore_id.items())
+            if current_row != row
+        ]
+        self.index_to_docstore_id = dict(enumerate(remaining + [chunk_id]))
+        self.documents[chunk_id] = {
+            "page_content": text,
+            "metadata": dict(metadata or {}),
+        }
+        self._save_to_storage()
+        return chunk_id
+
     def delete_chunk(self, chunk_id: str) -> bool:
         """Delete a chunk and save to storage."""
         self.delete_index([chunk_id])
diff --git a/docsgpt/vectorstore/mongodb.py b/docsgpt/vectorstore/mongodb.py
index cb735310..96c58cb1 100644
--- a/docsgpt/vectorstore/mongodb.py
+++ b/docsgpt/vectorstore/mongodb.py
@@ -2,7 +2,7 @@ import logging
 from functools import cached_property
 
 from docsgpt.core.settings import settings
-from docsgpt.vectorstore.base import BaseVectorStore
+from docsgpt.vectorstore.base import BaseVectorStore, InvalidChunkMetadataError
 from docsgpt.vectorstore.document_class import Document
 
 
@@ -224,6 +224,68 @@ class MongoDBVectorStore(BaseVectorStore):
         result = self._collection.insert_one(chunk_data)
         return str(result.inserted_id)
 
+    def update_chunk(self, chunk_id: str, text: str, metadata: dict) -> str:
+        """Rewrite a chunk's document in place, keeping its ``_id``.
+
+        Metadata lives as top-level fields, so the new metadata is ``$set``
+        and any field the record carries but the new metadata lacks is
+        ``$unset``; the record then holds exactly the new metadata. ``_id``,
+        the text, the embedding and ``source_id`` are reserved and cannot be
+        overwritten through ``metadata``. The embedding is computed before
+        anything is written.
+
+        Args:
+            chunk_id: Id of the chunk to replace.
+            text: The chunk's new text.
+            metadata: The chunk's complete new metadata.
+
+        Returns:
+            ``chunk_id``, unchanged.
+
+        Raises:
+            KeyError: If this source has no chunk with that id.
+            InvalidChunkMetadataError: If a metadata key is empty, contains
+                ``.`` or starts with ``$``. Mongo reads those as a path or an
+                operator, so ``$set`` would fail or write a nested field.
+            ValueError: If no embedding could be generated.
+        """
+        from bson.objectid import ObjectId
+
+        for key in metadata or {}:
+            if not isinstance(key, str) or not key or "." in key or key.startswith("$"):
+                raise InvalidChunkMetadataError(
+                    f"Metadata key {key!r} is not allowed: keys must be non-empty, "
+                    "contain no '.' and not start with '$'"
+                )
+
+        query = {"_id": ObjectId(chunk_id), "source_id": self._source_id}
+        existing = self._collection.find_one(query)
+        if existing is None:
+            raise KeyError(f"Chunk {chunk_id} not found for source {self._source_id}")
+
+        embeddings = self._embedding.embed_documents([text])
+        if not embeddings:
+            raise ValueError("Could not generate embedding for chunk")
+
+        reserved = {"_id", self._text_key, self._embedding_key, "source_id"}
+        fields = {k: v for k, v in (metadata or {}).items() if k not in reserved}
+        update = {
+            "$set": {
+                self._text_key: text,
+                self._embedding_key: embeddings[0],
+                "source_id": self._source_id,
+                **fields,
+            }
+        }
+        stale = {k: "" for k in existing if k not in reserved and k not in fields}
+        if stale:
+            update["$unset"] = stale
+
+        result = self._collection.update_one(query, update)
+        if result.matched_count == 0:
+            raise KeyError(f"Chunk {chunk_id} not found for source {self._source_id}")
+        return chunk_id
+
     def delete_chunk(self, chunk_id):
         try:
             from bson.objectid import ObjectId
diff --git a/docsgpt/vectorstore/pgvector.py b/docsgpt/vectorstore/pgvector.py
index 60bb5262..ca657b7d 100644
--- a/docsgpt/vectorstore/pgvector.py
+++ b/docsgpt/vectorstore/pgvector.py
@@ -637,7 +637,7 @@ class PGVectorStore(BaseVectorStore):
             select_query = f"""
             SELECT id, {self._text_column}, {self._metadata_column}
             FROM {self._table_name}
-            WHERE source_id = %s;
+            WHERE source_id = %s ORDER BY id;
             """
             cursor.execute(select_query, (self._source_id,))
             results = cursor.fetchall()
@@ -704,6 +704,58 @@ class PGVectorStore(BaseVectorStore):
         finally:
             cursor.close()
 
+    def update_chunk(self, chunk_id: str, text: str, metadata: Dict[str, Any]) -> str:
+        """Rewrite a chunk's row in place, keeping its id.
+
+        One ``UPDATE`` scoped to this source. The embedding is computed first,
+        so a failed embed writes nothing. ``get_chunks`` orders by id, so the
+        chunk also keeps its place in the list.
+
+        Args:
+            chunk_id: Id of the chunk to replace.
+            text: The chunk's new text.
+            metadata: The chunk's complete new metadata; ``source_id`` is
+                stamped on it as :meth:`add_chunk` does.
+
+        Returns:
+            ``chunk_id``, unchanged.
+
+        Raises:
+            KeyError: If this source has no chunk with that id.
+            ValueError: If no embedding could be generated.
+        """
+        final_metadata = dict(metadata or {})
+        final_metadata["source_id"] = self._source_id
+
+        embeddings = self._embedding.embed_documents([text])
+        if not embeddings:
+            raise ValueError("Could not generate embedding for chunk")
+
+        conn = self._get_connection()
+        cursor = conn.cursor()
+
+        try:
+            update_query = f"""
+            UPDATE {self._table_name}
+            SET {self._text_column} = %s, {self._vector_column} = %s, {self._metadata_column} = %s
+            WHERE id = %s AND source_id = %s;
+            """
+            cursor.execute(
+                update_query,
+                (text, embeddings[0], Jsonb(final_metadata), int(chunk_id), self._source_id),
+            )
+            if cursor.rowcount == 0:
+                raise KeyError(f"Chunk {chunk_id} not found for source {self._source_id}")
+            conn.commit()
+            return str(chunk_id)
+
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error updating chunk: {e}")
+            raise
+        finally:
+            cursor.close()
+
     def delete_chunk(self, chunk_id: str) -> bool:
         """Delete a specific chunk by its ID"""
         conn = self._get_connection()
diff --git a/docsgpt/vectorstore/qdrant.py b/docsgpt/vectorstore/qdrant.py
index a3822e9b..5b169416 100644
--- a/docsgpt/vectorstore/qdrant.py
+++ b/docsgpt/vectorstore/qdrant.py
@@ -206,6 +206,50 @@ class QdrantStore(BaseVectorStore):
         ids = self.add_texts([text], [metadata or {}])
         return ids[0]
 
+    def update_chunk(self, chunk_id: str, text: str, metadata: Dict[str, Any]) -> str:
+        """Overwrite a chunk's point in place, keeping its id.
+
+        Upserting the same id replaces the vector and payload; ``scroll``
+        orders by point id, so the chunk also keeps its place in
+        :meth:`get_chunks`. The payload has the shape :meth:`add_texts` writes.
+
+        Args:
+            chunk_id: Id of the point to replace.
+            text: The chunk's new text.
+            metadata: The chunk's complete new metadata; ``source_id`` is
+                stamped on it for source scoping.
+
+        Returns:
+            ``chunk_id``, unchanged.
+
+        Raises:
+            KeyError: If this source has no point with that id.
+        """
+        records = self._client.retrieve(
+            collection_name=self._collection,
+            ids=[chunk_id],
+            with_payload=True,
+            with_vectors=False,
+        )
+        payload = (records[0].payload or {}) if records else {}
+        if (payload.get("metadata") or {}).get("source_id") != self._source_id:
+            raise KeyError(f"Chunk {chunk_id} not found for source {self._source_id}")
+
+        vector = self._embeddings.embed_documents([text])[0]
+        payload_metadata = dict(metadata or {})
+        payload_metadata["source_id"] = self._source_id
+        self._client.upsert(
+            collection_name=self._collection,
+            points=[
+                self._models.PointStruct(
+                    id=chunk_id,
+                    vector=vector,
+                    payload={"page_content": text, "metadata": payload_metadata},
+                )
+            ],
+        )
+        return chunk_id
+
     def delete_chunk(self, chunk_id: str) -> bool:
         """Delete a single chunk by id."""
         try:
diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
index 078e4ed8..eaf5651a 100644
--- a/frontend/DESIGN.md
+++ b/frontend/DESIGN.md
@@ -71,7 +71,12 @@ ones `warning`. Series with no meaning (models, agents, sources) take
 `chart-1` to `chart-5` in order. When there are more than five, the four
 largest keep `chart-1` to `chart-4` and the rest are summed into one
 "Other" series in `chart-5`, so no colour repeats (`settings/foldSeries.ts`).
-`secondary` is never a chart colour.
+`secondary` is never a chart colour. The knowledge graph is the one
+place Other is not `chart-5`: its entity types have no meaning to map, and
+half a graph often folds into Other, so red would read as "these failed".
+There the four largest types take `chart-1` to `chart-4` and Other is
+`muted-foreground` (`foldGraphTypes`, `readGraphPalette` in
+`components/graphViewUtils.ts`).
 
 The status set is `success | warning | destructive | info`. `default` is the
 component's own base tone (brand on a Badge or Button, quiet on an Alert or
@@ -266,8 +271,17 @@ aria-current="page">` with `data-active`. The
   the same pixels, plus `role="tablist"`/`"tab"`, `aria-selected` and
   arrow-key focus; wrap the panel in `TabsContent` (FilePicker's My Files /
   Shared with Me, Schedules' Recurring / One-time in
-  `agents/schedules/SchedulesView.tsx`). The `default` variant is a pill tab,
-  unused in the app.
+  `agents/schedules/SchedulesView.tsx`, the graph source view, the source
+  edit drawer). Each trigger keeps its `px-4`, so the first label sits 16px
+  in from the content edge and the underline runs past the label on both
+  sides. That inset is deliberate (decided 2026-09-28): the tab row reads as
+  its own strip, with a wider target per tab, so don't pull it flush with
+  `-ml-4` or strip the padding. Only the workflow builder's toolbar, where
+  the tabs share a row with a breadcrumb, uses the padding-free `Button
+variant="tab" size="inline"`. The `default` variant is a pill tab, unused
+  in the app. Panels unmount when hidden, except one whose state is costly to
+  rebuild (the graph source view's laid-out canvas and zoom): that
+  `TabsContent` takes `forceMount` plus `data-[state=inactive]:hidden`.
 - A section panel's disclosure header (NewAgent's Advanced and Guardrails
   panels) is `variant="section-toggle" size="sm"` with `-ml-3 w-fit
 justify-start` and `aria-expanded`: a lucide `ChevronRight` first
@@ -499,7 +513,10 @@ that already draws the frame (the renaming sidebar row, a search strip in a
 bordered panel) is `variant="bare"`; the host shows focus, and any inset
 padding goes on the host, not the field. A field on a muted panel (the
 ImportSpec Base URL box) is `variant="filled"`, so it keeps the card fill
-instead of showing the panel through; never pass `bg-card` for it.
+instead of showing the panel through; never pass `bg-card` for it. A floating
+label rests at the field's own text size (16px, 14px from `md`), so a
+labelled search and a placeholder-only one read the same, and with a
+`leftIcon` it rests where the text starts (40px in).
 
 ### SelectTrigger (`ui/select.tsx`)
 
@@ -520,9 +537,29 @@ lg` and CommandInput. The `sm` sizes stay 14px. A highlighted list row is
 `none`, `vertical` (default), `both`. Same border, ring and invalid styling
 as Input. `variant`: `default` (transparent), `filled` (card fill), with
 the same rule as Input: a textarea on a muted panel is `variant="filled"`,
-never `bg-card`. Three raw `<textarea>` elements stay, because each sits
-under an overlay it must line up with: the chat composer, PromptTextArea's
-variable highlighter and the chunk editor behind its line-number gutter.
+never `bg-card`. Two raw `<textarea>` elements stay, because each sits
+under an overlay it must line up with: the chat composer and PromptTextArea's
+variable highlighter.
+
+### Command (`ui/command.tsx`)
+
+`Command` is the list primitive (cmdk) behind comboboxes, pickers, the
+search palette and the source navigator; its `variant` is `default` or
+`palette` (the search palette's spacing, see Modal, not Dialog).
+`CommandInput`'s `variant` is `default`, the `h-9` row with a bottom border
+at the top of a popover or palette list, or `field`, the 38px pill of a
+list that sits on the page (a source view's navigator filter, see Page
+chrome and Source views); nothing else hand-frames it. `CommandList` caps
+itself at `max-h-75` and scrolls; a list that already scrolls inside its
+host (a `Modal mobileVariant="sheet"` body) passes `max-h-none` so there is
+one scroller. `CommandItem` rows are `cursor-default` like Select and menu
+items, highlight `bg-accent` and mark the open item `checked`
+(`bg-secondary`); don't add `cursor-pointer`. cmdk highlights the first row
+by default, which reads as hover. A list used as navigation, where a current
+item exists (the source navigator), starts the highlight on that item, or on
+a value that matches no row while nothing is open
+(`tree/SourceNavigator`'s `NO_HIGHLIGHT`); a search-then-pick list keeps
+cmdk's first-row highlight.
 
 ### FormField (`ui/form-field.tsx`)
 
@@ -533,7 +570,9 @@ as its only child. The label sits on the field's border (12px muted), and
 line: `card` (the default: forms in cards, modals and `outline` panels),
 `background` (fields straight on a page or in a `subtle` panel), `muted`
 (fields on a muted panel). Never pass a background class for it. It rests inside an empty, unfocused
-`Input` or `Textarea` and moves up on focus; on a `SelectTrigger`, combobox,
+`Input` or `Textarea` at the field's own text size (16px, 14px from `md`;
+14px on an `sm` Input), where the text starts (40px in beside a `leftIcon`),
+and moves up to the 12px border label on focus; on a `SelectTrigger`, combobox,
 `MultiSelect`, number field or `Dropzone` it stays on the border. It turns
 red (`text-destructive`) with an `error`, and dims while `disabled`. Under
 the field come a muted `text-xs` hint and a red `text-xs` error
@@ -557,7 +596,7 @@ FormField with no single box to sit on: a list of checkboxes, several
 controls in a row, a loading or error line in place of the field. Controls
 whose label sits beside them (Switch, Checkbox, radio) use `SettingRow` or
 an inline `Label`, not FormField. An editing surface that fills its area
-(the chat composer, the chunk and wiki editors, editing a sent question) and
+(the chat composer, the source edit drawer's field, editing a sent question) and
 bare repeated rows in a list have no visible label and must have an
 `aria-label`. A row box that is a small form (a workflow condition case or
 state assignment) is not a bare row: each of its fields has a floating
@@ -686,7 +725,8 @@ art, page / panel / popover), `illustration` `no-files | none` (a "no
 results" line is `size="xs" illustration="none"`), `title`, `description`
 (plain `muted-foreground`), `action`. A page or panel whose fetch failed is
 `EmptyState tone="destructive" illustration="none"` with a `Retry` action
-(`t('retry')`): a red `CircleAlert`, a red title, `role="alert"`. Never a bare
+(`t('retry')`, an `outline sm pill` Button at every EmptyState size): a red
+`CircleAlert`, a red title, `role="alert"`. Never a bare
 `text-destructive` paragraph.
 
 ### Progress (`ui/progress.tsx`)
@@ -833,12 +873,15 @@ Sources adds its count and a right chevron, and opens the All sources sheet.
 an ellipsis. Pages pass only its width (`w-[16ch]`, `max-w-[32ch]`) and a
 `title` with the full text; never `truncate` or typography. Give every
 current crumb a width cap so a long name cannot push the row past the
-screen. A crumb that runs a handler instead of navigating is
+screen. It carries the link's focus ring: after a crumb step, PathHeader
+moves focus to the new current crumb (`tabIndex={-1}`) so keyboard focus
+never drops to the page. A crumb that runs a handler instead of navigating is
 `BreadcrumbLink asChild` around a `<button type="button">`; the link carries
-the focus ring. The current crumb is never a disabled button. The path row above a
-source's file tree and chunk viewer is `components/tree/PathHeader`
-(back button, chevron crumbs, the last capped at `max-w-[32ch]`, actions on
-the right); don't hand-roll a `/`-separated path.
+the focus ring. Parent crumbs cap at `max-w-[16ch]` with `truncate` on the
+button itself (a parent with no handler is a plain truncating `<span>`, never
+a disabled button). The current crumb is never a disabled button. The header of
+every source view is `components/tree/PathHeader` (see Source views); don't
+hand-roll a `/`-separated path.
 
 ### ListRow and DescriptionList (`ui/list-row.tsx`, `ui/description-list.tsx`)
 
@@ -849,6 +892,11 @@ bordered list for one). Rows are `px-4 py-3`, the title `text-sm
 font-medium`. `interactive` (with `asChild` around a `<Link>` or `<button>`)
 hovers to `bg-accent` and draws an inset focus ring. An icon square in
 `leading` is a plain `bg-muted text-muted-foreground size-8 rounded-md` span.
+In a narrow side panel (the graph node panel's relationships) rows are
+`size="sm"`: `px-2 py-1.5`, `gap-2.5`, `rounded-md` and top-aligned so a small
+leading mark (a `GraphTypeDot` with `mt-1.5`) sits on the title line. They go
+in a plain `<ul className="-mx-2">`, not `ListRows` (no divide rules), and
+are `interactive asChild` around a `<button>` like the others.
 
 Key/value rows are `DescriptionList` + `DescriptionItem`, never a hand-rolled
 `flex` of label and value. `layout="columns"` (default) is an 8rem label
@@ -860,9 +908,24 @@ right-aligns the values (a phone card; `columns={2}` for a stats dialog).
 ### Pagination (`ui/pagination.tsx`)
 
 The pager under a table, tile grid or list: "Page N of M" and four chevron
-`IconButton`s. `pageSize` adds the Rows per page select; `summary` puts a
+`IconButton`s. `pageSize` adds the Rows per page select (`pageSizeLabel`
+renames it when the items aren't rows: the chunk grid's "Chunks per page",
+with `pageSizeOptions={[12, 24, 48]}` so a full page fills 2, 3 or 4
+columns); `summary` puts a
 count on the left ("1,024 users"). `labels="text"` swaps the chevrons for
-Previous / Next buttons. Don't hand-roll a Previous / Next row.
+Previous / Next buttons. Don't hand-roll a Previous / Next row. With a page
+size select, keep the pager while the total exceeds the smallest option, not
+the current page size, so picking a bigger size never hides the way back
+("Page 1 of 1", chevrons off). Counts and numbers in the UI format on the app
+language: `formatCount` (`utils/dateTimeUtils`, `Intl` on `intlLocale()`), never
+`toLocaleString()` or a raw `{{count}}`; plural keys get the number as `count`
+and the formatted text as its own param. The one exception is a headline
+total that can reach tens of thousands (the chunk count in the Chunks byline
+and embedded toolbar): it may use `abbreviateCount` (`components/chunkUtils`,
+`Intl` compact notation: "12K", "12 тыс.", "1.2万"; grouped digits where the
+language has no short form). Counts in tables, pagers and inline text use
+`formatCount`. Lists of names join with
+`Intl.ListFormat`, never a hard-coded `', '`.
 
 ### Page chrome: SectionShell, PageToolbar, SearchInput
 
@@ -881,8 +944,13 @@ a limit warning), then `divider` (a `Separator`). With no `search` the intro
 moves into the row's left slot (`max-w-2xl`) beside the action. A page search
 is `components/SearchInput`: the 38px pill (`size="sm"` for 32px) with a
 search icon and a floating `label` on `labelSurface="background"` (its
-default); a placeholder-only search is named by its placeholder. The chunk viewer's and file tree's searches stay `CommandInput` in
-their frame, because their results are `CommandItem`s.
+default); a placeholder-only search is named by its placeholder. A source
+view's navigator filter is a `CommandInput variant="field"` (the same 38px
+pill, text 40px in, the ring on the frame), because its rows are
+`CommandItem`s (see Source views and Command). `CommandInput`'s `default` variant is the
+`h-9` row with a bottom border at the top of a popover or palette list; the
+wrapper carries `data-variant` for styling from the parent. Nothing else
+hand-frames a `CommandInput`.
 
 An agent's tabs (Overview, Logs, Schedules) share one header,
 `agents/components/AgentPageToolbar` on top of `PageToolbar`, under
@@ -940,6 +1008,116 @@ New Chat is `SquarePen` everywhere: the phone bar, the sidebar's New Chat row
 and the collapsed rail. `Plus` means "add an item to this list", not "start
 a chat".
 
+### Source views (`components/tree/`, `WikiViewer`, `components/graph/`, `GraphView`)
+
+Every source view (a file or connector tree, a one-document chunk list, a
+wiki, a knowledge graph) is one shell:
+
+- **Header**: `PathHeader`, 16px (`gap-4`) above the content in every
+  source view, crumbs and no back button: Sources (leaves the source view),
+  the source, its folders, the open file and the open chunk ("Chunk 12"),
+  each opening its level, the last one current. A wiki's open page is not a
+  crumb: its crumbs stop at the source, and the page is marked in the
+  navigator and named by its path in the reader's meta. Up one level is
+  a crumb, as on the Tools and Teams detail pages (`DetailBreadcrumb`); the
+  phone's `SectionBackLink` above the title is the only arrow, and it leaves
+  the section. Crumbs never take `text-primary`; parents are muted like any
+  crumb, truncate at `max-w-[16ch]` with a `title`, and the row stays on one
+  line (`flex-nowrap`). A tree embedded in another source view (a graph
+  source's Files tab) draws no Sources crumb and reports its crumbs to the
+  host (`onCrumbsChange`), whose header shows them while that tab is open. The
+  file table has no `..` row. `badge` is the source kind as a `neutral` Badge with a 12px lucide
+  icon (Living wiki, Knowledge graph, a connector's provider; plain uploads
+  have none); `byline` is one muted `text-sm` line of counts ("33 files ·
+  11,420 tokens", "12 pages · 8,111 tokens · …", "371 entities · 1,172
+  relationships"), where a kind that needs explaining adds one sentence. No
+  explainer box. Actions on the right: Test retrieval (`outline field pill`)
+  and the kind's one primary action (Add file, Sync).
+- **Navigator**: `SourceNavigator`, a `w-64` column shown only when there is
+  more than one thing to open (files, wiki pages). A filter `CommandInput
+variant="field"` over a `CommandList` of `CommandItem`s, so the arrow keys
+  walk from the field into the list; the open item is `checked`. Files are a
+  tree (folders expand, a folder opens its table on the right and expands,
+  24px of indent per level to depth 4 and 12px per level below it, every row
+  with its path as `title`); wiki pages are grouped under their top folder as
+  `CommandGroup` headings, labelled by title or by file name in sentence case
+  (`wikiPageLabel`). Typing flattens the list to matching leaves with their
+  full parent path as a muted second line. The column caps its list at
+  `max-h-[70svh]`. Below `lg` it is a `combobox field pill`
+  that opens the same list in a bottom sheet, uncapped (the sheet body
+  scrolls). A source with one file opens
+  straight on its chunk list, and a wiki with one page on its reader at full
+  width: no navigator, no table.
+- **Reader**: `ReaderPanel`, the content you read (a wiki page, an open
+  chunk): a `subtle` Card with `padding="none"`, its meta (muted 12px lines)
+  left and its actions right in a `min-h-14 px-6` header row, a `Separator`,
+  then the body at `px-6 py-5`. The body is always rendered markdown,
+  `components/SourceMarkdown` (the chat answer's headings and tables, lists
+  outside the text); raw text is never the reading view. Actions: an open
+  chunk's previous / next (`IconButton ghost-muted icon-sm pill`, and the
+  arrow keys), then Edit (`outline sm pill`, `Pencil` first) and an
+  `ActionMenu size="toolbar"` (Copy text; a chunk's also has Delete, a
+  destructive item). A wiki page has Edit (editors only) and the same menu
+  with Copy text, and no previous / next; the navigator walks them.
+- **Read in the page, edit in a drawer**: Edit and Add chunk open
+  `SourceEditSheet`, a right `Sheet size="wide"` (a working surface): title
+  and a mono description (path, version, tokens), then any `fields` edited
+  with the content (a chunk's Title, a `FormField` + `Input` with
+  `labelSurface="background"` and the hint "The name answers cite this
+  chunk by."; Add prefills it with the title the file's chunks already use,
+  else the file's name), Write · Preview
+  (`ui/tabs variant="underline"`; Preview renders the draft with
+  `SourceMarkdown`), one filling `font-mono` Textarea, then Cancel (`ghost lg
+pill`) and Save (`default lg pill`, off until the draft or a field changes, and while the draft is blank). The drawer
+  edits a copy: closing with changes asks "Discard your unsaved changes?". A
+  save result stays in the drawer as an Alert above the field (a wiki
+  conflict `warning`, forbidden and failures `destructive`); success closes
+  it and the page re-renders behind. Never edit in place in the reader.
+- **Chunk grid**: `SearchInput` ("Search chunks"), then Add chunk at the end.
+  The count is in the header's byline; only a chunk list inside a file tree,
+  whose byline is the tree's totals, repeats it as muted meta beside the
+  search; tiles show `chunkPreviewText` (heading markers and dot
+  leaders removed, display only) and `#n · tokens` in `CardFooter`.
+- **Graph**: under the header, `ui/tabs variant="underline"` Graph · Entities
+  · Files (Files is the embedded file tree; a source with no folder structure
+  shows its embedded chunk list there instead, as the plain view does). A tab's own action goes in the
+  header's action row after Test retrieval, only while that tab is open (the
+  Files tab's Add file or Sync, portalled through `TreeBrowser`'s
+  `actionsTarget`), as on the agent pages; the embedded tree draws no row of
+  its own. The Graph tab's toolbar holds the
+  entity search (a Popover + Command over the server's `/graph/nodes?q=`),
+  the phrase "Show top [50 | 100 | 250] by connections" (muted `text-sm`
+  words, the `ToggleGroup xs` alone in its muted track) and the legend, which
+  is the type filter (`ToggleGroup type="multiple" xs` in its own muted track,
+  a colour dot per item). The surface is one `subtle` Card, `padding="none"`, at `h-[70svh]`;
+  the canvas controls (`graph/GraphCanvasControls`) are the workflow
+  builder's `CanvasControls` strip without React Flow or Undo / Redo; change
+  the two together. Type colours come from `graph/GraphTypeDot`
+  (`GraphTypeDot`, `GraphTypeBadge`, `GraphSeriesDot`), never a hand-picked
+  hue; the node panel docks
+  inside it only while a node is selected (a bottom Sheet on phones), as
+  `GraphNodePanelDock`: a `border-l` column at `w-80`, `xl:w-2/5` capped at
+  `max-w-xl` (the detail drawer's 576px). Its header is the workflow node
+  panel's (`px-4 py-3`, the close `ghost-muted icon-sm`); in the phone bottom
+  Sheet (`handle`) the panel passes `showClose={false}`, so there's no X and the
+  scrim closes it. The Entities tab is
+  the same frame: toolbar (`SearchInput` with a `label`, the type Select),
+  then the `h-[70svh]` Card holding the `Table` (no `TableContainer`, it
+  scrolls inside) and the same dock, the open entity's row `selected`, and the
+  pager under the frame. The canvas labels only the ten biggest hubs, the
+  hovered node and the selection with its neighbours, and dims everything
+  unconnected to the selection to 15%. The panel lists the node's
+  relationships, one row per neighbour with its normalised edge labels
+  (`groupRelationships`), each a button that selects that neighbour, then its
+  source chunks as `filled sm interactive` tiles. A tile opens a read drawer
+  (`Sheet size="detail"`, one record) with the chunk rendered and the entity's
+  name marked in the brand tint (`bg-secondary`), and Open in Files and Edit
+  (the same `SourceEditSheet`) in its footer; Cancel or Discard in that edit
+  drawer returns to the read drawer, Save closes both, and closing it leaves
+  the node selected. The relationship list is capped server-side: its heading
+  counts the true total (`relationships_total`) and, when the list is partial,
+  a muted `text-xs` line says how many are shown.
+
 ### Chat answer column
 
 The answer column never scrolls sideways. Its boxes, from AnswerFlow down to
@@ -961,7 +1139,7 @@ columns (`lg:grid-cols-3`): their header row holds an initial, the name, a
 role badge and a chevron. Stat rows: `grid grid-cols-2 gap-4 md:grid-cols-4`
 (five tiles: `md:grid-cols-3 lg:grid-cols-5`; a dialog: `grid-cols-3`). Text
 tiles whose body is the content (chunks) follow their container, since the
-same list renders beside a file-search column: `grid grid-cols-1 gap-4
+same list renders beside the source navigator: `grid grid-cols-1 gap-4
 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]`. A
 grid inside a Modal keeps its own column counts, because breakpoints follow
 the window, not the dialog.
@@ -1166,12 +1344,17 @@ this menu from `DropdownMenu`, and don't declare a local option type.
 
 ### Table, Label, dialog text
 
-Every table is `ui/table`; never a raw `<table>` (enforced) or a table
-utility class (the chat's markdown tables are the one exception, see Approved
-exceptions). The header row is dense by
+Every table is `ui/table`, markdown tables included (`markdownTables` renders
+its parts); never a raw `<table>` (enforced) or a table utility class. The header row is dense by
 default (`px-2 py-1 lg:px-3 text-sm font-normal text-foreground`, 28px, on
 `TableHead`'s sticky `bg-muted` strip). A `TableRow` hovers (`bg-accent`,
-pointer) only when it has an `onClick`; a read-only row does not. Use
+pointer) only when it has an `onClick`; a read-only row does not. `selected`
+marks the row whose detail is open beside the table (the graph's Entities):
+`bg-secondary`, the brand tint of an open navigator item, kept on hover, with
+`aria-current`. Use
+A number column (sizes, tokens, counts) is `align="right"` with
+`tabular-nums` on its cells, header included in the alignment, whatever the
+column order (the file table, the graph's Entities). Use
 `TableContainer` for the bordered, scrolling frame; a table that already sits
 in a frame renders `Table` alone. `Table` keeps a 600px minimum so wide
 tables scroll sideways; a narrow one inside a panel passes
@@ -1215,7 +1398,7 @@ runs under the tab bar, and the app shell can be dragged and bounce. ESLint
   dropdown's `max-h-[calc(100dvh-200px)]`, `Modal`'s `85dvh`).
 - **`svh`** (the smallest viewport, steady): a fixed-size panel inside a page
   that scrolls (the Logs panel's `h-[55svh]`, a list's `max-h-[45svh]`, the
-  chunk editor's `min-h`), so it doesn't resize while Safari's bars slide in
+  graph surface's `h-[70svh]`, the source edit drawer's `min-h`), so it doesn't resize while Safari's bars slide in
   and out.
 - **`max-h-sheet`**: every bottom sheet (see Modal, not Dialog).
 - A row or control has a fixed height (`h-12`), never a share of the viewport.
@@ -1246,7 +1429,11 @@ leading-tight font-semibold`. `DialogTitle` and `SheetTitle` default to it;
   a heading: `text-sm text-muted-foreground`.
 - **Markdown**: every renderer spreads `markdownHeadings` from
   `lib/markdown.tsx` (h1 20px, h2 18px, h3 16px, semibold, `mt-4|3 mb-2`);
-  don't declare a local heading map.
+  don't declare a local heading map. Tables are `markdownTables` from the same
+  file: the `ui/table` parts in a `TableContainer` (the frame scrolls
+  sideways, `minWidth="min-w-0"` so a narrow table shrinks), so a table in a
+  chat answer, a wiki page, a chunk, a note or a preview looks like every
+  other table. Every markdown renderer spreads it.
 - **Mono**: ids, keys and code snippets are `font-mono text-xs`; code fields
   (textareas) follow the field size; code blocks follow the Card recipe
   (see Card). A preview of text a person or a model wrote (a trace's query
@@ -1325,7 +1512,9 @@ shows.
   keyboard open the trigger did have focus and still gets it back. Don't pass
   `onCloseAutoFocus` from app code to remember focus yourself (ESLint rejects
   it); the primitive already does. `onOpenAutoFocus` with `preventDefault()`
-  is still how a phone picker keeps the keyboard down (`MultiSelectPopover`).
+  is still how a phone picker keeps the keyboard down (`MultiSelectPopover`),
+  and how a phone panel sheet opens without a focus ring on its first control
+  (the graph node panel's bottom Sheet).
   A dialog panel is a `tabIndex=-1` focus target that Radix can focus, so it
   carries `outline-none`: Safari draws its own blue `outline: auto` there and
   ignores our `outline-color`. Any new focusable container needs the same.
@@ -1348,10 +1537,7 @@ shadow-lg` in both themes: the knob is white on any track, and a white knob
   panels and have none. Outside `ui/` the only shadows are: the workflow
   canvas nodes (`shadow-md`, `hover:shadow-lg`: a node lifts off the canvas
   while you drag it); the workflow builder's publish-error panel, which
-  floats over the canvas at popover elevation (`shadow-md`, `z-20`); the
-  chunk viewer's and file tree's search result
-  lists (`shadow-md`, in-page `z-20`, their results are `CommandItem`s inside
-  the search frame); the sliding panel in `navigation/SidebarLevel.tsx`,
+  floats over the canvas at popover elevation (`shadow-md`, `z-20`); the sliding panel in `navigation/SidebarLevel.tsx`,
   which casts a horizontal shadow while it slides; and the Hero model
   picker's menu (both Approved exceptions). Don't add new ones: a floating panel is a `Popover`,
   `DropdownMenu` or `Modal`, which carry their own shadow and stacking; never
@@ -1408,7 +1594,6 @@ list stays reviewable.
 | `admin/Overview.tsx`                                                | `shadcn/no-restyle`             | "View in Audit" under the denied-sign-ins tile keeps the tile's destructive tone at hint size (`text-destructive text-xs font-normal`). One disable.                                                                                                                                                                                                                                                                                                                                            |
 | `settings/PairDeviceModal.tsx`                                      | `shadcn/no-restyle`             | The install link in Pair a remote machine sits in a 12px hint (`text-xs font-normal`, `self-start` in its column). One disable.                                                                                                                                                                                                                                                                                                                                                                 |
 | `agents/workflow/WorkflowBuilder.tsx`                               | `shadcn/no-restyle`             | The publish-error Alert floats over the canvas with its close button in the top-right corner, so it pads `pr-10` to keep a long title clear of the button. One disable.                                                                                                                                                                                                                                                                                                                         |
-| `conversation/MarkdownAnswer.tsx`                                   | `no-restricted-syntax`          | Markdown answer tables render the model's own table markup with its own styling, so they stay a raw `<table>`.                                                                                                                                                                                                                                                                                                                                                                                  |
 
 Note that a multi-line reason has to be a `/* ... */` block comment;
 consecutive `//` lines only disable the next comment line, not the code.
diff --git a/frontend/src/api/endpoints.ts b/frontend/src/api/endpoints.ts
index 143a168b..2983ea7e 100644
--- a/frontend/src/api/endpoints.ts
+++ b/frontend/src/api/endpoints.ts
@@ -68,6 +68,19 @@ const endpoints = {
     ENABLE_GRAPHRAG: (id: string) => `/api/sources/${id}/graphrag/enable`,
     SOURCE_GRAPH: (id: string, limit?: number) =>
       `/api/sources/${id}/graph${limit ? `?limit=${limit}` : ''}`,
+    SOURCE_GRAPH_NODES: (
+      id: string,
+      params: { q?: string; type?: string; page?: number; perPage?: number },
+    ) => {
+      const search = new URLSearchParams();
+      if (params.q) search.set('q', params.q);
+      // An empty type filters to untyped nodes, so it is sent only when set.
+      if (params.type !== undefined) search.set('type', params.type);
+      if (params.page) search.set('page', String(params.page));
+      if (params.perPage) search.set('per_page', String(params.perPage));
+      const qs = search.toString();
+      return `/api/sources/${id}/graph/nodes${qs ? `?${qs}` : ''}`;
+    },
     SOURCE_GRAPH_NODE: (id: string, nodeId: string) =>
       `/api/sources/${id}/graph/node/${encodeURIComponent(nodeId)}`,
     TASK_STATUS: (taskId: string) => `/api/task_status?task_id=${taskId}`,
diff --git a/frontend/src/api/services/userService.ts b/frontend/src/api/services/userService.ts
index 85253b01..46062aa6 100644
--- a/frontend/src/api/services/userService.ts
+++ b/frontend/src/api/services/userService.ts
@@ -153,6 +153,15 @@ const userService = {
     limit?: number,
   ): Promise<Response> =>
     throttledApiClient.get(endpoints.USER.SOURCE_GRAPH(sourceId, limit), token),
+  getSourceGraphNodes: (
+    sourceId: string,
+    params: { q?: string; type?: string; page?: number; perPage?: number },
+    token: string | null,
+  ): Promise<Response> =>
+    throttledApiClient.get(
+      endpoints.USER.SOURCE_GRAPH_NODES(sourceId, params),
+      token,
+    ),
   getSourceGraphNode: (
     sourceId: string,
     nodeId: string,
diff --git a/frontend/src/components/ArtifactSidebar.tsx b/frontend/src/components/ArtifactSidebar.tsx
index 8bfd8914..82ad8001 100644
--- a/frontend/src/components/ArtifactSidebar.tsx
+++ b/frontend/src/components/ArtifactSidebar.tsx
@@ -11,7 +11,7 @@ import {
 } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import remarkGfm from 'remark-gfm';
 
-import { markdownHeadings } from '@/lib/markdown';
+import { markdownHeadings, markdownTables } from '@/lib/markdown';
 import { cn } from '@/lib/utils';
 
 import userService from '../api/services/userService';
@@ -197,6 +197,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
               remarkPlugins={[remarkGfm]}
               components={{
                 ...markdownHeadings,
+                ...markdownTables,
                 code(props) {
                   const {
                     children,
diff --git a/frontend/src/components/Chunks.test.tsx b/frontend/src/components/Chunks.test.tsx
index c3fac55e..de91252e 100644
--- a/frontend/src/components/Chunks.test.tsx
+++ b/frontend/src/components/Chunks.test.tsx
@@ -1,47 +1,87 @@
 import { act, useState } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 
+const { dispatch, service, pagerProps } = vi.hoisted(() => ({
+  pagerProps: {
+    current: null as null | { onPageSizeChange?: (size: number) => void },
+  },
+  dispatch: vi.fn(),
+  service: {
+    getDocumentChunks: vi.fn(),
+    addChunk: vi.fn(),
+    updateChunk: vi.fn(),
+    deleteChunk: vi.fn(),
+  },
+}));
+
+// Keys come back as-is; interpolation values are appended so the tests can
+// read them ("key {"n":1}").
 vi.mock('react-i18next', () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts ? `${key} ${JSON.stringify(opts)}` : key,
+  }),
 }));
 
 vi.mock('react-redux', () => ({
   useSelector: () => null,
+  useDispatch: () => dispatch,
 }));
 
 vi.mock('../hooks', () => ({
   useDarkTheme: () => [false],
   useDebouncedValue: (value: unknown) => value,
   useLoaderState: (initial: boolean) => useState(initial),
-  useMediaQuery: () => ({ isMobile: false }),
+  useMediaQuery: () => ({ isMobile: false, isDesktop: true }),
   useOutsideAlerter: () => undefined,
 }));
 
-vi.mock('../api/services/userService', () => ({
-  default: {
-    getDocumentChunks: vi.fn(async () => ({
-      ok: true,
-      json: async () => ({
-        page: 1,
-        per_page: 5,
-        total: 1,
-        chunks: [{ doc_id: 'c1', text: 'Late pickup clause', metadata: {} }],
-      }),
-    })),
-  },
-}));
+vi.mock('../api/services/userService', () => ({ default: service }));
+
+// The real pager, with its props kept so a test can pick a page size without
+// driving the Select popover.
+vi.mock('./ui/pagination', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('./ui/pagination')>();
+  return {
+    ...mod,
+    Pagination: (props: React.ComponentProps<typeof mod.Pagination>) => {
+      pagerProps.current = props;
+      return mod.Pagination(props);
+    },
+  };
+});
 
 import Chunks from './Chunks';
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
-const setInputValue = (input: HTMLInputElement, value: string) => {
-  const setter = Object.getOwnPropertyDescriptor(
-    HTMLInputElement.prototype,
-    'value',
-  )!.set!;
-  setter.call(input, value);
-  input.dispatchEvent(new Event('input', { bubbles: true }));
+const chunksResponse = (overrides: Record<string, unknown> = {}) => ({
+  ok: true,
+  json: async () => ({
+    page: 1,
+    per_page: 12,
+    total: 1,
+    chunks: [
+      {
+        doc_id: 'c1',
+        text: '## Late pickup clause',
+        metadata: { token_count: 42 },
+      },
+    ],
+    ...overrides,
+  }),
+});
+
+const setFieldValue = (
+  field: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) => {
+  const proto =
+    field instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : HTMLInputElement.prototype;
+  Object.getOwnPropertyDescriptor(proto, 'value')!.set!.call(field, value);
+  field.dispatchEvent(new Event('input', { bubbles: true }));
 };
 
 describe('Chunks', () => {
@@ -49,6 +89,12 @@ describe('Chunks', () => {
   let root: Root;
 
   beforeEach(() => {
+    dispatch.mockReset();
+    service.getDocumentChunks.mockReset();
+    service.getDocumentChunks.mockImplementation(async () => chunksResponse());
+    service.addChunk.mockReset();
+    service.updateChunk.mockReset();
+    service.deleteChunk.mockReset();
     container = document.createElement('div');
     document.body.appendChild(container);
     root = createRoot(container);
@@ -57,129 +103,726 @@ describe('Chunks', () => {
   afterEach(async () => {
     await act(async () => root.unmount());
     container.remove();
+    document.body.innerHTML = '';
   });
 
-  const render = async (onFileSelect = vi.fn()) => {
+  const render = async (
+    props: Partial<React.ComponentProps<typeof Chunks>> = {},
+  ) => {
     await act(async () => {
       root.render(
         <Chunks
           documentId="doc"
           documentName="Contracts"
           handleGoBack={vi.fn()}
-          onFileSearch={() => [
-            { name: 'msa.pdf', path: 'contracts/msa.pdf', isFile: true },
-            { name: 'sla.docx', path: 'contracts/sla.docx', isFile: true },
-          ]}
-          onFileSelect={onFileSelect}
+          {...props}
         />,
       );
     });
-    return onFileSelect;
   };
 
-  it('picks a file search result with the keyboard', async () => {
-    const onFileSelect = await render();
-    const input = container.querySelector<HTMLInputElement>(
-      '[data-slot="command-input"]',
-    )!;
-    expect(input).not.toBeNull();
+  const tile = () =>
+    container.querySelector<HTMLButtonElement>('button[data-slot="card"]');
 
-    await act(async () => setInputValue(input, 'contracts'));
-    const items = container.querySelectorAll('[data-slot="command-item"]');
-    expect(items).toHaveLength(2);
+  const buttonByText = (text: string) =>
+    Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>('button'),
+    ).find((el) => el.textContent?.trim() === text);
 
-    await act(async () => {
-      input.dispatchEvent(
-        new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
-      );
-    });
-    await act(async () => {
-      input.dispatchEvent(
-        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
-      );
-    });
-    expect(onFileSelect).toHaveBeenCalledWith('contracts/sla.docx');
-  });
-
-  it('renders each chunk tile as a button', async () => {
-    await render();
-    const tile = container.querySelector<HTMLButtonElement>(
-      'button[data-slot="card"]',
+  const crumbs = () =>
+    Array.from(container.querySelectorAll('[data-slot="breadcrumb-item"]')).map(
+      (el) => el.textContent,
     );
-    expect(tile).not.toBeNull();
-    expect(tile!.textContent).toContain('Late pickup clause');
-    expect(tile!.className).not.toContain('hover:scale-105');
+
+  const clickCrumb = async (label: string) => {
+    const link = Array.from(
+      container.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="breadcrumb-link"]',
+      ),
+    ).find((el) => el.textContent === label);
+    if (!link) throw new Error(`no crumb link ${label}`);
+    await act(async () => link.click());
+  };
+
+  const buttonByLabel = (label: string) =>
+    document.body.querySelector<HTMLButtonElement>(
+      `button[aria-label="${label}"]`,
+    );
+
+  it('has no file search column', async () => {
+    await render();
+    expect(container.querySelector('[data-slot="command-input"]')).toBeNull();
+    expect(container.innerHTML).not.toContain('198px');
   });
 
-  it('draws each chunk as a filled tile with its token count in the footer', async () => {
+  it('draws each chunk as a filled tile with a cleaned preview and #n · tokens footer', async () => {
     await render();
-    const tile = container.querySelector<HTMLButtonElement>(
-      'button[data-slot="card"]',
-    )!;
-    expect(tile.dataset.variant).toBe('filled');
-    expect(tile.dataset.padding).toBe('lg');
-    const footer = tile.querySelector('[data-slot="card-footer"]')!;
-    expect(footer.textContent).toContain('settings.sources.tokensUnit');
+    const card = tile()!;
+    expect(card.dataset.variant).toBe('filled');
+    expect(card.dataset.padding).toBe('lg');
+    expect(card.querySelector('p')!.textContent).toBe('Late pickup clause');
+    const footer = card.querySelector('[data-slot="card-footer"]')!;
+    expect(footer.textContent).toBe(
+      'settings.sources.chunkTileMeta {"n":1,"tokens":"42"}',
+    );
     // No muted strip on the muted tile: it would disappear.
-    expect(tile.querySelector('.bg-muted')).toBeNull();
+    expect(card.querySelector('.bg-muted')).toBeNull();
+  });
+
+  it('numbers tiles from the page offset', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({
+        page: 2,
+        total: 30,
+        chunks: [
+          { doc_id: 'a', text: 'A', metadata: {} },
+          { doc_id: 'b', text: 'B', metadata: {} },
+        ],
+      }),
+    );
+    await render();
+    const footers = Array.from(
+      container.querySelectorAll('[data-slot="card-footer"]'),
+    ).map((el) => el.textContent);
+    expect(footers[0]).toContain('"n":13');
+    expect(footers[1]).toContain('"n":14');
   });
 
   // Decision 79: text tiles follow the container with an auto-fit track that
   // can't overflow a container narrower than 400px.
   it('lays the tiles out on the guarded auto-fit text-tile grid', async () => {
     await render();
-    const grid = container.querySelector<HTMLButtonElement>(
-      'button[data-slot="card"]',
-    )!.parentElement!;
-    expect(grid.className).toBe(
+    expect(tile()!.parentElement!.className).toBe(
       'grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]',
     );
   });
 
-  const renderPath = async (props: {
-    onPathSelect?: (depth: number) => void;
-    handleGoBack?: () => void;
-  }) => {
+  it('shows the search field, the muted count and Add chunk', async () => {
+    await render({ embedded: true });
+    expect(container.textContent).toContain('settings.sources.searchChunks');
+    expect(container.textContent).toContain(
+      'settings.sources.chunkCount {"count":1,"formatted":"1"}',
+    );
+    expect(buttonByText('settings.sources.addChunk')).toBeDefined();
+  });
+
+  // The header's byline already carries it; only a chunk list inside a file
+  // tree (whose byline is the tree's totals) repeats the count in the toolbar.
+  it('standalone: the chunk count shows once, in the byline', async () => {
+    await render();
+    const count = 'settings.sources.chunkCount {"count":1,"formatted":"1"}';
+    expect(container.textContent!.split(count)).toHaveLength(2);
+    expect(
+      container.querySelector('p.text-sm.text-muted-foreground')?.textContent,
+    ).toBe(count);
+  });
+
+  it('asks for 12 chunks per page and labels the page-size select', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({ total: 30 }),
+    );
+    await render();
+    expect(service.getDocumentChunks.mock.calls[0][2]).toBe(12);
+    const pager = container.querySelector('[data-slot="pagination"]')!;
+    expect(pager.textContent).toContain('pagination.chunksPerPage');
+  });
+
+  // Bugs row 1: at 48 per page a 30-chunk source still keeps its pager, so a
+  // smaller page size can be picked again.
+  it('keeps the pager when the page size outgrows the chunk count', async () => {
+    service.getDocumentChunks.mockImplementation(
+      async (_id: string, _page: number, perPage: number) =>
+        chunksResponse({ total: 30, per_page: perPage }),
+    );
+    await render();
+    await act(async () => pagerProps.current!.onPageSizeChange!(48));
+    expect(service.getDocumentChunks.mock.lastCall![2]).toBe(48);
+    const pager = container.querySelector('[data-slot="pagination"]');
+    expect(pager).not.toBeNull();
+    expect(pager!.textContent).toContain('pagination.chunksPerPage');
+  });
+
+  it('draws no pager for 12 chunks or fewer', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({ total: 12 }),
+    );
+    await render();
+    expect(container.querySelector('[data-slot="pagination"]')).toBeNull();
+  });
+
+  it('standalone: Sources › the source, and the Sources crumb leaves it', async () => {
+    const handleGoBack = vi.fn();
+    await render({ handleGoBack, headerAction: <span>retrieval</span> });
+    expect(crumbs()).toEqual(['settings.sources.label', 'Contracts']);
+    expect(container.textContent).toContain('retrieval');
+    await clickCrumb('settings.sources.label');
+    expect(handleGoBack).toHaveBeenCalledTimes(1);
+  });
+
+  it('embedded: draws no header', async () => {
+    await render({ embedded: true });
+    expect(container.querySelector('[data-slot="breadcrumb-item"]')).toBeNull();
+  });
+
+  const drawer = () => document.body.querySelector('[role="dialog"]');
+
+  // Chunk n of a 3-chunk list served one per page.
+  const THREE = ['# First', '# Second', '# Third'];
+  const serveThree = () =>
+    service.getDocumentChunks.mockImplementation(
+      async (_id: string, page: number, perPage: number) =>
+        perPage === 1
+          ? chunksResponse({
+              page,
+              per_page: 1,
+              total: 3,
+              chunks: [
+                {
+                  doc_id: `c${page}`,
+                  text: THREE[page - 1],
+                  metadata: { token_count: page },
+                },
+              ],
+            })
+          : chunksResponse({
+              total: 3,
+              chunks: THREE.map((text, i) => ({
+                doc_id: `c${i + 1}`,
+                text,
+                metadata: { token_count: i + 1 },
+              })),
+            }),
+    );
+
+  it('opens a chunk rendered in the reader panel and returns to the list', async () => {
+    const controllerRef: React.ComponentProps<typeof Chunks>['controllerRef'] =
+      { current: null };
+    const onOpenChunkChange = vi.fn();
+    await render({ embedded: true, controllerRef, onOpenChunkChange });
+    await act(async () => tile()!.click());
+    expect(tile()).toBeNull();
+    expect(container.textContent).toContain(
+      'settings.sources.chunkPosition {"n":1,"total":1,"tokens":"42"}',
+    );
+    // Markdown reads rendered: no textarea, the heading is a heading.
+    expect(container.querySelector('textarea')).toBeNull();
+    expect(container.querySelector('h2')?.textContent).toBe(
+      'Late pickup clause',
+    );
+    // The host's crumbs close it; the reader has no Back of its own.
+    expect(onOpenChunkChange).toHaveBeenLastCalledWith(1);
+    expect(container.querySelector('.lucide-arrow-left')).toBeNull();
+
+    await act(async () => controllerRef.current!.closeChunk());
+    expect(tile()).not.toBeNull();
+    expect(onOpenChunkChange).toHaveBeenLastCalledWith(null);
+  });
+
+  it('renders a markdown heading as an h1', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({
+        chunks: [{ doc_id: 'c1', text: '# Rates\n\nBody', metadata: {} }],
+      }),
+    );
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    expect(container.querySelector('h1')?.textContent).toBe('Rates');
+  });
+
+  it('standalone: an open chunk is the last crumb and the source crumb closes it', async () => {
+    const handleGoBack = vi.fn();
+    await render({ handleGoBack });
+    await act(async () => tile()!.click());
+    expect(crumbs()).toEqual([
+      'settings.sources.label',
+      'Contracts',
+      'settings.sources.chunkCrumb {"n":1}',
+    ]);
+    await clickCrumb('Contracts');
+    expect(handleGoBack).not.toHaveBeenCalled();
+    expect(tile()).not.toBeNull();
+    expect(crumbs()).toEqual(['settings.sources.label', 'Contracts']);
+  });
+
+  it('previous / next fetch chunk n one per page and stop at the ends', async () => {
+    serveThree();
+    await render({ embedded: true, path: 'a/b.md' });
+    await act(async () => tile()!.click());
+    const prev = () => buttonByLabel('settings.sources.previousChunk')!;
+    const next = () => buttonByLabel('settings.sources.nextChunk')!;
+    expect(prev().disabled).toBe(true);
+    expect(next().disabled).toBe(false);
+
+    service.getDocumentChunks.mockClear();
+    await act(async () => next().click());
+    expect(service.getDocumentChunks).toHaveBeenCalledWith(
+      'doc',
+      2,
+      1,
+      null,
+      'a/b.md',
+      '',
+    );
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
+    expect(container.textContent).toContain(
+      'settings.sources.chunkPosition {"n":2,"total":3,"tokens":"2"}',
+    );
+
+    await act(async () => next().click());
+    expect(container.querySelector('h1')?.textContent).toBe('Third');
+    expect(next().disabled).toBe(true);
+    expect(prev().disabled).toBe(false);
+
+    await act(async () => prev().click());
+    expect(service.getDocumentChunks).toHaveBeenLastCalledWith(
+      'doc',
+      2,
+      1,
+      null,
+      'a/b.md',
+      '',
+    );
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
+  });
+
+  it('the arrow keys walk the chunks while no field has focus', async () => {
+    serveThree();
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
     await act(async () => {
-      root.render(
-        <Chunks
-          documentId="doc"
-          documentName="Contracts"
-          handleGoBack={props.handleGoBack ?? vi.fn()}
-          path="legal/2024/msa.pdf"
-          displayPath="legal/2024/msa.pdf"
-          onPathSelect={props.onPathSelect}
-        />,
-      );
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight' }));
     });
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
+    await act(async () => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft' }));
+    });
+    expect(container.querySelector('h1')?.textContent).toBe('First');
+  });
+
+  // 13 chunks, 12 per page: chunk 13 sits on page 2.
+  const serveThirteen = () =>
+    service.getDocumentChunks.mockImplementation(
+      async (_id: string, page: number, perPage: number) =>
+        perPage === 1
+          ? chunksResponse({
+              page,
+              per_page: 1,
+              total: 13,
+              chunks: [
+                { doc_id: `c${page}`, text: `# C${page}`, metadata: {} },
+              ],
+            })
+          : chunksResponse({
+              page,
+              total: 13,
+              chunks: Array.from({ length: page === 2 ? 1 : 12 }, (_, i) => ({
+                doc_id: `p${page}-${i}`,
+                text: `tile ${page}-${i}`,
+                metadata: {},
+              })),
+            }),
+    );
+
+  it('back to the grid lands on the page holding the last chunk', async () => {
+    const controllerRef: React.ComponentProps<typeof Chunks>['controllerRef'] =
+      { current: null };
+    serveThirteen();
+    await render({ embedded: true, controllerRef });
+    const tiles = container.querySelectorAll<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    );
+    await act(async () => tiles[11].click());
+    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
+    expect(container.querySelector('h1')?.textContent).toBe('C13');
+    await act(async () => controllerRef.current!.closeChunk());
+    const lastGridCall = service.getDocumentChunks.mock.calls
+      .filter((call) => call[2] !== 1)
+      .pop()!;
+    expect(lastGridCall[1]).toBe(2);
+    expect(tile()!.textContent).toContain('tile 2-0');
+  });
+
+  it('Edit opens the drawer with the chunk text and saves it', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({
+        chunks: [
+          {
+            doc_id: 'c1',
+            text: '## Late pickup clause',
+            metadata: { token_count: 42, title: 'Clause' },
+          },
+        ],
+      }),
+    );
+    service.updateChunk.mockImplementation(async () => ({
+      ok: true,
+      json: async () => ({ chunk_id: 'c1-new' }),
+    }));
+    await render({ embedded: true, path: 'legal/msa.pdf' });
+    await act(async () => tile()!.click());
+    // No in-panel edit mode any more.
+    expect(buttonByText('modals.chunk.cancel')).toBeUndefined();
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    expect(drawer()).not.toBeNull();
+    expect(drawer()!.textContent).toContain('settings.sources.editChunk');
+    expect(drawer()!.textContent).toContain(
+      'settings.sources.editChunkDescription {"file":"legal/msa.pdf","n":1,"tokens":"42"',
+    );
+    const field = drawer()!.querySelector('textarea')!;
+    expect(field.value).toBe('## Late pickup clause');
+
+    await act(async () => setFieldValue(field, '## New text'));
+    service.getDocumentChunks.mockClear();
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    expect(service.updateChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        chunk_id: 'c1',
+        text: '## New text',
+        metadata: { title: 'Clause' },
+      },
+      null,
+    );
+    expect(drawer()).toBeNull();
+    // That chunk and the grid page are fetched again.
+    const sizes = service.getDocumentChunks.mock.calls.map((call) => call[2]);
+    expect(sizes).toContain(1);
+    expect(sizes).toContain(12);
+  });
+
+  it('an edit the search no longer matches still shows the saved text', async () => {
+    service.updateChunk.mockImplementation(async () => ({
+      ok: true,
+      json: async () => ({ chunk_id: 'c1-new' }),
+    }));
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    // After the save, the open position holds nothing (or another chunk).
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({ total: 0, chunks: [] }),
+    );
+    const field = drawer()!.querySelector('textarea')!;
+    await act(async () => setFieldValue(field, '## Rewritten'));
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    expect(drawer()).toBeNull();
+    expect(container.querySelector('h2')?.textContent).toBe('Rewritten');
+  });
+
+  it('deleting the only chunk on the last page lands on the page before', async () => {
+    const controllerRef: React.ComponentProps<typeof Chunks>['controllerRef'] =
+      { current: null };
+    serveThirteen();
+    service.deleteChunk.mockImplementation(async () => ({ ok: true }));
+    await render({ embedded: true, controllerRef });
+    const tiles = container.querySelectorAll<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    );
+    await act(async () => tiles[11].click());
+    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
+    expect(container.querySelector('h1')?.textContent).toBe('C13');
+
+    const trigger = buttonByLabel('settings.sources.menuAlt')!;
+    await act(async () => {
+      trigger.dispatchEvent(
+        new PointerEvent('pointerdown', { bubbles: true, button: 0 }),
+      );
+      trigger.click();
+    });
+    const del = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).find((el) => el.textContent === 'modals.chunk.delete')!;
+    await act(async () => del.click());
+    await act(async () => buttonByText('modals.chunk.delete')!.click());
+
+    expect(service.deleteChunk).toHaveBeenCalledWith('doc', 'c13', null);
+    const lastGridCall = service.getDocumentChunks.mock.calls
+      .filter((call) => call[2] !== 1)
+      .pop()!;
+    expect(lastGridCall[1]).toBe(1);
+  });
+
+  it('drops a grid response that a newer fetch overtook', async () => {
+    const controllerRef: React.ComponentProps<typeof Chunks>['controllerRef'] =
+      { current: null };
+    serveThirteen();
+    await render({ embedded: true, controllerRef });
+    // Open chunk 13 (page 2), then start a slow page-1 refresh and close the
+    // chunk before it answers.
+    const tiles = container.querySelectorAll<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    );
+    await act(async () => tiles[11].click());
+    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
+    let release: () => void = () => undefined;
+    const slow = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const fast = service.getDocumentChunks.getMockImplementation()! as (
+      ...a: unknown[]
+    ) => unknown;
+    // Grid page 1 answers only once released.
+    service.getDocumentChunks.mockImplementation(async (...args: unknown[]) => {
+      if (args[1] === 1 && args[2] !== 1) await slow;
+      return fast(...args);
+    });
+    service.updateChunk.mockImplementation(async () => ({
+      ok: true,
+      json: async () => ({ chunk_id: 'c13' }),
+    }));
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    const field = drawer()!.querySelector('textarea')!;
+    await act(async () => setFieldValue(field, '# C13 edited'));
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    await act(async () => controllerRef.current!.closeChunk());
+    expect(tile()!.textContent).toContain('tile 2-0');
+    await act(async () => release());
+    expect(tile()!.textContent).toContain('tile 2-0');
+  });
+
+  it('a failed save keeps the drawer open with a destructive alert', async () => {
+    service.updateChunk.mockImplementation(async () => ({ ok: false }));
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    const field = drawer()!.querySelector('textarea')!;
+    await act(async () => setFieldValue(field, 'New text'));
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    expect(service.updateChunk).toHaveBeenCalledTimes(1);
+    expect(drawer()).not.toBeNull();
+    const alert = drawer()!.querySelector('[data-slot="alert"]')!;
+    expect(alert.getAttribute('data-variant')).toBe('destructive');
+    expect(alert.textContent).toBe('settings.sources.chunkErrors.save');
+    expect(dispatch).not.toHaveBeenCalled();
+    // The edits stay in the drawer.
+    expect(drawer()!.querySelector('textarea')!.value).toBe('New text');
+  });
+
+  it('Add chunk opens the drawer empty, adds and stays on the grid', async () => {
+    service.addChunk.mockImplementation(async () => ({ ok: true }));
+    await render({ embedded: true, path: 'a.md' });
+    await act(async () => buttonByText('settings.sources.addChunk')!.click());
+    expect(
+      drawer()!.querySelector('h2, [data-slot="sheet-title"]')!.textContent,
+    ).toBe('settings.sources.addChunk');
+    const field = drawer()!.querySelector('textarea')!;
+    expect(field.value).toBe('');
+    // The title defaults to the file's name, as ingest sets it.
+    expect(drawer()!.querySelector('input')!.value).toBe('a.md');
+    await act(async () => setFieldValue(field, 'Fresh'));
+    service.getDocumentChunks.mockClear();
+    await act(async () => buttonByText('modals.chunk.add')!.click());
+    expect(service.addChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        text: 'Fresh',
+        metadata: { source: 'a.md', source_id: 'doc', title: 'a.md' },
+      },
+      null,
+    );
+    expect(drawer()).toBeNull();
+    expect(service.getDocumentChunks).toHaveBeenCalledTimes(1);
+    expect(tile()).not.toBeNull();
+  });
+
+  it("Add chunk's title follows the file's other chunks, then its display name", async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({
+        chunks: [
+          { doc_id: 'c1', text: 'x', metadata: { title: 'Carrier profile' } },
+        ],
+      }),
+    );
+    await render({
+      embedded: true,
+      path: 'x_1.docx',
+      fileName: 'Carrier.docx',
+    });
+    await act(async () => buttonByText('settings.sources.addChunk')!.click());
+    expect(drawer()!.querySelector('input')!.value).toBe('Carrier profile');
+    await act(async () =>
+      buttonByText('settings.sources.editor.cancel')!.click(),
+    );
+
+    service.getDocumentChunks.mockImplementation(async () => chunksResponse());
+    await render({ embedded: true, path: 'x_2.docx', fileName: 'Other.docx' });
+    await act(async () => buttonByText('settings.sources.addChunk')!.click());
+    expect(drawer()!.querySelector('input')!.value).toBe('Other.docx');
+  });
+
+  it('editing only the title enables Save and sends it', async () => {
+    service.getDocumentChunks.mockImplementation(async () =>
+      chunksResponse({
+        chunks: [
+          { doc_id: 'c1', text: 'Body', metadata: { title: 'Old name' } },
+        ],
+      }),
+    );
+    service.updateChunk.mockImplementation(async () => ({
+      ok: true,
+      json: async () => ({ chunk_id: 'c1-new' }),
+    }));
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    const title = drawer()!.querySelector('input')!;
+    expect(title.value).toBe('Old name');
+    expect(buttonByText('modals.chunk.save')!.disabled).toBe(true);
+    await act(async () => setFieldValue(title, 'New name'));
+    expect(buttonByText('modals.chunk.save')!.disabled).toBe(false);
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    expect(service.updateChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        chunk_id: 'c1',
+        text: 'Body',
+        metadata: { title: 'New name' },
+      },
+      null,
+    );
+  });
+
+  it('saving an untitled chunk sends no empty title', async () => {
+    service.updateChunk.mockImplementation(async () => ({
+      ok: true,
+      json: async () => ({ chunk_id: 'c1-new' }),
+    }));
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    await act(async () =>
+      setFieldValue(drawer()!.querySelector('textarea')!, 'Rewritten'),
+    );
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+    expect(service.updateChunk).toHaveBeenCalledWith(
+      { id: 'doc', chunk_id: 'c1', text: 'Rewritten' },
+      null,
+    );
+  });
+
+  it('an Add drawer opened before the grid lands closes without a discard prompt', async () => {
+    let release: () => void = () => undefined;
+    const slow = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    service.getDocumentChunks.mockImplementation(async () => {
+      await slow;
+      return chunksResponse({
+        chunks: [{ doc_id: 'c1', text: 'x', metadata: { title: 'Profile' } }],
+      });
+    });
+    await render({ embedded: true, fileName: 'Carrier.docx' });
+    await act(async () => buttonByText('settings.sources.addChunk')!.click());
+    expect(drawer()!.querySelector('input')!.value).toBe('Carrier.docx');
+    await act(async () => release());
+    await act(async () =>
+      buttonByText('settings.sources.editor.cancel')!.click(),
+    );
+    expect(document.body.textContent).not.toContain(
+      'settings.sources.editor.discardMessage',
+    );
+    expect(drawer()).toBeNull();
+  });
+
+  /**
+   * A 3-chunk store the tests reorder: an update adds the new copy where
+   * `placeAt` says (the end by default) and drops the old one.
+   */
+  const serveStore = (placeAt?: number) => {
+    const store = [
+      { doc_id: 'c1', text: '# First', metadata: {} },
+      { doc_id: 'c2', text: '# Second', metadata: {} },
+      { doc_id: 'c3', text: '# Third', metadata: {} },
+    ];
+    service.getDocumentChunks.mockImplementation(
+      async (_id: string, page: number, perPage: number) => {
+        const start = (page - 1) * perPage;
+        return chunksResponse({
+          page,
+          per_page: perPage,
+          total: store.length,
+          chunks: store.slice(start, start + perPage),
+        });
+      },
+    );
+    service.updateChunk.mockImplementation(
+      async (body: { chunk_id: string; text: string }) => {
+        const index = store.findIndex((c) => c.doc_id === body.chunk_id);
+        const [old] = store.splice(index, 1);
+        const copy = { ...old, doc_id: `${old.doc_id}-new`, text: body.text };
+        store.splice(placeAt ?? store.length, 0, copy);
+        return { ok: true, json: async () => ({ chunk_id: copy.doc_id }) };
+      },
+    );
   };
 
-  const crumbButton = (label: string) =>
-    Array.from(
-      container.querySelectorAll<HTMLButtonElement>(
-        '[data-slot="breadcrumb-link"]',
-      ),
-    ).find((el) => el.textContent === label);
+  const editOpenChunk = async (text: string) => {
+    await act(async () => buttonByText('modals.chunk.edit')!.click());
+    await act(async () =>
+      setFieldValue(drawer()!.querySelector('textarea')!, text),
+    );
+    await act(async () => buttonByText('modals.chunk.save')!.click());
+  };
 
-  it('opens the root and parent folders from the path crumbs', async () => {
-    const onPathSelect = vi.fn();
-    await renderPath({ onPathSelect });
+  const position = () =>
+    container
+      .textContent!.match(/chunkPosition \{"n":(\d+),"total":(\d+)/)!
+      .slice(1)
+      .map(Number);
 
-    await act(async () => crumbButton('Contracts')!.click());
-    expect(onPathSelect).toHaveBeenLastCalledWith(0);
-    await act(async () => crumbButton('2024')!.click());
-    expect(onPathSelect).toHaveBeenLastCalledWith(2);
-    // The file is the current crumb, not a link.
-    expect(crumbButton('msa.pdf')).toBeUndefined();
+  it('an edited chunk the store moved to the end is shown at its new position', async () => {
+    serveStore();
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await editOpenChunk('# First edited');
+    expect(container.querySelector('h1')?.textContent).toBe('First edited');
+    expect(position()).toEqual([3, 3]);
+    expect(buttonByLabel('settings.sources.nextChunk')!.disabled).toBe(true);
+    // Previous walks the store's current order: nothing is skipped.
+    await act(async () =>
+      buttonByLabel('settings.sources.previousChunk')!.click(),
+    );
+    expect(container.querySelector('h1')?.textContent).toBe('Third');
+    await act(async () =>
+      buttonByLabel('settings.sources.previousChunk')!.click(),
+    );
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
   });
 
-  it('without onPathSelect the root goes back and folders are text', async () => {
-    const handleGoBack = vi.fn();
-    await renderPath({ handleGoBack });
+  it('an edited chunk the store moved elsewhere is found by its id', async () => {
+    serveStore(1);
+    await render({ embedded: true });
+    const tiles = container.querySelectorAll<HTMLButtonElement>(
+      'button[data-slot="card"]',
+    );
+    await act(async () => tiles[2].click());
+    await editOpenChunk('# Third edited');
+    expect(container.querySelector('h1')?.textContent).toBe('Third edited');
+    expect(position()).toEqual([2, 3]);
+    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
+  });
 
-    await act(async () => crumbButton('Contracts')!.click());
-    expect(handleGoBack).toHaveBeenCalledTimes(1);
-    expect(crumbButton('legal')).toBeUndefined();
-    expect(crumbButton('2024')).toBeUndefined();
+  it('an edited chunk that keeps its place stays put', async () => {
+    serveStore(0);
+    await render({ embedded: true });
+    await act(async () => tile()!.click());
+    await editOpenChunk('# First edited');
+    expect(position()).toEqual([1, 3]);
+    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
+    expect(container.querySelector('h1')?.textContent).toBe('Second');
+  });
+
+  it('shows a destructive empty state with Retry when the fetch fails', async () => {
+    service.getDocumentChunks.mockImplementation(async () => ({ ok: false }));
+    await render();
+    const alert = container.querySelector('[role="alert"]')!;
+    expect(alert).not.toBeNull();
+    expect(alert.textContent).toContain('settings.sources.chunkErrors.load');
+    expect(tile()).toBeNull();
+
+    service.getDocumentChunks.mockImplementation(async () => chunksResponse());
+    await act(async () => buttonByText('retry')!.click());
+    expect(tile()).not.toBeNull();
   });
 });
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index 541912b9..7ecd0ced 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -1,124 +1,67 @@
-import { File, Folder } from 'lucide-react';
-import React, { useEffect, useRef, useState } from 'react';
+import copy from 'copy-to-clipboard';
+import { ChevronLeft, ChevronRight, Copy, Pencil, Trash2 } from 'lucide-react';
+import React, { useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { useSelector } from 'react-redux';
-
-import { cn, fieldFrame } from '@/lib/utils';
+import { useDispatch, useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
-import {
-  useDebouncedValue,
-  useLoaderState,
-  useMediaQuery,
-  useOutsideAlerter,
-} from '../hooks';
+import { useDebouncedValue, useLoaderState } from '../hooks';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { ActiveState } from '../models/misc';
+import { showActionToast } from '../notifications/actionToastSlice';
 import { selectToken } from '../preferences/preferenceSlice';
 import { ChunkType } from '../settings/types';
-import { formatChunkTokens } from './chunkUtils';
+import {
+  abbreviateCount,
+  chunkPreviewText,
+  formatChunkTokens,
+} from './chunkUtils';
+import SearchInput from './SearchInput';
 import SkeletonLoader from './SkeletonLoader';
+import SourceMarkdown from './SourceMarkdown';
 import PathHeader from './tree/PathHeader';
+import ReaderPanel from './tree/ReaderPanel';
+import SourceEditSheet from './tree/SourceEditSheet';
+import { Alert, AlertDescription } from './ui/alert';
 import { Button } from './ui/button';
 import { Card, CardFooter } from './ui/card';
-import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-} from './ui/command';
-import { EmptyState } from './ui/empty-state';
+import { FormField } from './ui/form-field';
 import { Input } from './ui/input';
+import { ActionMenu } from './ui/dropdown-menu';
+import { EmptyState } from './ui/empty-state';
+import { IconButton } from './ui/icon-button';
 import { Pagination } from './ui/pagination';
 
-// The search field's frame: the Input look around a CommandInput (38px,
-// rounded-md, focus ring while the input has keyboard focus). CommandInput's
-// row is 36px with a bottom rule; pt-px + overflow-hidden clips that rule.
-const SEARCH_FRAME = cn(
-  fieldFrame,
-  'border-border has-[input:focus-visible]:border-ring has-[input:focus-visible]:ring-ring/50 h-9.5 overflow-hidden rounded-md pt-px has-[input:focus-visible]:ring-3',
-);
+/** Chunks per page: divisible by 2, 3 and 4 columns, so a page fills the grid. */
+const PAGE_SIZE_OPTIONS = [12, 24, 48];
 
-interface LineNumberedTextareaProps {
-  value: string;
-  onChange: (value: string) => void;
-  placeholder?: string;
-  ariaLabel?: string;
-  className?: string;
-  editable?: boolean;
-  onDoubleClick?: () => void;
+/** Lets the host's crumbs close the open chunk (see TreeBrowser). */
+export interface ChunksController {
+  closeChunk: () => void;
 }
 
-const LineNumberedTextarea: React.FC<LineNumberedTextareaProps> = ({
-  value,
-  onChange,
-  placeholder,
-  ariaLabel,
-  className = '',
-  editable = true,
-  onDoubleClick,
-}) => {
-  const { isMobile } = useMediaQuery();
+const TILE_GRID =
+  'grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]';
 
-  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    onChange(e.target.value);
-  };
-
-  const lineHeight = 20;
-  const contentLines = value.split('\n').length;
-
-  const heightOffset = isMobile ? 200 : 300;
-  const minLinesForDisplay = Math.ceil(
-    (typeof window !== 'undefined' ? window.innerHeight - heightOffset : 600) /
-      lineHeight,
-  );
-  const totalLines = Math.max(contentLines, minLinesForDisplay);
-
-  return (
-    <div
-      className={cn('relative w-full', className)}
-      style={
-        {
-          '--numbered-height': `${totalLines * lineHeight}px`,
-        } as React.CSSProperties
-      }
-    >
-      <div className="text-muted-foreground pointer-events-none absolute top-0 left-0 h-(--numbered-height) w-8 pr-2 text-right font-mono text-xs leading-5 select-none lg:w-12 lg:pr-3 lg:text-sm">
-        {Array.from({ length: totalLines }, (_, i) => (
-          <div
-            key={i + 1}
-            className="flex h-5 items-center justify-end leading-5"
-          >
-            {i + 1}
-          </div>
-        ))}
-      </div>
-      <textarea
-        className={cn(
-          'text-foreground focus-visible:ring-ring/50 focus-visible:border-ring h-(--numbered-height) w-full resize-none overflow-hidden border-none bg-transparent pl-8 text-sm leading-5 outline-none focus-visible:ring-3 lg:pl-12',
-          isMobile
-            ? 'min-h-[calc(100svh-200px)]'
-            : 'min-h-[calc(100svh-300px)]',
-          !editable && 'select-none',
-        )}
-        value={value}
-        onChange={editable ? handleChange : undefined}
-        onDoubleClick={onDoubleClick}
-        placeholder={placeholder}
-        aria-label={ariaLabel}
-        rows={totalLines}
-        readOnly={!editable}
-      />
-    </div>
-  );
-};
-
-interface SearchResult {
-  path: string;
-  isFile: boolean;
-  name?: string;
+/**
+ * Whether a key press belongs to something else: a field being typed in, an
+ * open dialog, drawer or menu.
+ *
+ * @param event The keydown event.
+ * @returns True when the chunk arrows should leave the key alone.
+ */
+function keyBelongsElsewhere(event: KeyboardEvent): boolean {
+  if (event.defaultPrevented) return true;
+  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+    return true;
+  const target = event.target as HTMLElement | null;
+  if (
+    target &&
+    (target.isContentEditable ||
+      ['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName))
+  )
+    return true;
+  return !!document.querySelector('[role="dialog"], [role="menu"]');
 }
 
 interface ChunksProps {
@@ -126,57 +69,76 @@ interface ChunksProps {
   documentName?: string;
   handleGoBack: () => void;
   path?: string;
-  displayPath?: string;
-  onFileSearch?: (query: string) => SearchResult[];
-  onFileSelect?: (path: string) => void;
-  /** Extra header control, rendered left of the chunk actions. */
+  /** The open file's display name: a new chunk's default title. */
+  fileName?: string;
+  /** Extra header control (Test retrieval); standalone only. */
   headerAction?: React.ReactNode;
   /**
-   * Opens a level of the path: 0 is the source root, n the folder made of
-   * the first n path segments. Without it the root crumb calls handleGoBack
-   * and folder crumbs are plain text.
+   * Rendered inside a source view that draws the header itself (TreeBrowser):
+   * no PathHeader here. The host's crumbs show the open chunk
+   * (`onOpenChunkChange`) and close it (`controllerRef`).
    */
-  onPathSelect?: (depth: number) => void;
+  embedded?: boolean;
+  /** The open chunk's position (1-based), or null while the grid shows. */
+  onOpenChunkChange?: (position: number | null) => void;
+  controllerRef?: React.MutableRefObject<ChunksController | null>;
 }
 
+type SheetMode = 'edit' | 'add';
+
 const Chunks: React.FC<ChunksProps> = ({
   documentId,
   documentName,
   handleGoBack,
   path,
-  displayPath,
-  onFileSearch,
-  onFileSelect,
+  fileName,
   headerAction,
-  onPathSelect,
+  embedded = false,
+  onOpenChunkChange,
+  controllerRef,
 }) => {
-  const [fileSearchQuery, setFileSearchQuery] = useState('');
-  const [fileSearchResults, setFileSearchResults] = useState<SearchResult[]>(
-    [],
-  );
-  const searchDropdownRef = useRef<HTMLDivElement>(null);
   const { t } = useTranslation();
+  const dispatch = useDispatch();
   const token = useSelector(selectToken);
   const [paginatedChunks, setPaginatedChunks] = useState<ChunkType[]>([]);
   const [page, setPage] = useState(1);
-  const [perPage, setPerPage] = useState(5);
+  const [perPage, setPerPage] = useState(PAGE_SIZE_OPTIONS[0]);
   const [totalChunks, setTotalChunks] = useState(0);
   const [loading, setLoading] = useLoaderState(true);
+  const [loadFailed, setLoadFailed] = useState(false);
   const [searchTerm, setSearchTerm] = useState<string>('');
   const debouncedSearchTerm = useDebouncedValue(searchTerm, 300);
-  const [editingChunk, setEditingChunk] = useState<ChunkType | null>(null);
-  const [editingTitle, setEditingTitle] = useState('');
-  const [editingText, setEditingText] = useState('');
-  const [isAddingChunk, setIsAddingChunk] = useState(false);
+  const [openChunk, setOpenChunk] = useState<ChunkType | null>(null);
+  // The open chunk's position in the whole filtered list (1-based).
+  const [openPosition, setOpenPosition] = useState(0);
+  // A previous / next fetch in flight.
+  const [stepping, setStepping] = useState(false);
+  const stepRef = useRef(0);
+  const [sheetOpen, setSheetOpen] = useState(false);
+  // Kept after closing so the title holds through the exit animation.
+  const [sheetMode, setSheetMode] = useState<SheetMode>('add');
+  const [draft, setDraft] = useState('');
+  // The chunk's title: the name answers cite it by.
+  const [draftTitle, setDraftTitle] = useState('');
+  // A new chunk's default title as it was when the Add drawer opened: the
+  // discard check compares against it, not a default a later fetch moved.
+  const [addBaselineTitle, setAddBaselineTitle] = useState('');
+  const [saving, setSaving] = useState(false);
+  const [saveFailed, setSaveFailed] = useState(false);
   const [deleteModalState, setDeleteModalState] =
     useState<ActiveState>('INACTIVE');
   const [chunkToDelete, setChunkToDelete] = useState<ChunkType | null>(null);
-  const [isEditing, setIsEditing] = useState(false);
 
-  const displayPathValue = displayPath ?? path ?? '';
-  const pathParts = displayPathValue ? displayPathValue.split('/') : [];
+  const showError = (message: string) =>
+    dispatch(showActionToast({ variant: 'destructive', message }));
 
+  const fileLabel = path || documentName || '';
+
+  // Only the latest grid fetch may write: an older response (a refresh after
+  // a save, a page just left) is dropped.
+  const fetchRef = useRef(0);
   const fetchChunks = async () => {
+    const request = ++fetchRef.current;
     setLoading(true);
     try {
       const response = await userService.getDocumentChunks(
@@ -193,101 +155,283 @@ const Chunks: React.FC<ChunksProps> = ({
       }
 
       const data = await response.json();
+      if (request !== fetchRef.current) return;
 
       setPage(data.page);
       setPerPage(data.per_page);
       setTotalChunks(data.total);
       setPaginatedChunks(data.chunks);
+      setLoadFailed(false);
     } catch (error) {
-      setPaginatedChunks([]);
       console.error(error);
+      if (request !== fetchRef.current) return;
+      setPaginatedChunks([]);
+      setLoadFailed(true);
     } finally {
-      // ✅ always runs, success or failure
-      setLoading(false);
+      if (request === fetchRef.current) setLoading(false);
     }
   };
 
-  const handleAddChunk = (title: string, text: string) => {
-    if (!text.trim()) {
-      return;
-    }
-
+  /**
+   * Open chunk n of the current (searched, per-file) list: one chunk per
+   * page, so the page number is the position.
+   */
+  const goToChunk = async (position: number) => {
+    if (position < 1 || (totalChunks > 0 && position > totalChunks)) return;
+    const request = ++stepRef.current;
+    setStepping(true);
     try {
-      const metadata = {
-        source: path || documentName,
-        source_id: documentId,
-        title: title,
+      const response = await userService.getDocumentChunks(
+        documentId,
+        position,
+        1,
+        token,
+        path,
+        debouncedSearchTerm,
+      );
+      if (!response.ok) throw new Error('Failed to fetch chunk');
+      const data = await response.json();
+      if (request !== stepRef.current) return;
+      const chunk: ChunkType | undefined = data.chunks?.[0];
+      if (typeof data.total === 'number') setTotalChunks(data.total);
+      if (chunk) {
+        setOpenChunk(chunk);
+        setOpenPosition(position);
+      }
+    } catch (error) {
+      console.error(error);
+      if (request === stepRef.current)
+        showError(t('settings.sources.chunkErrors.load'));
+    } finally {
+      if (request === stepRef.current) setStepping(false);
+    }
+  };
+
+  /**
+   * After a save, find the edited chunk in the store's current order and show
+   * its stored copy (fresh metadata) at that position, so "n of total" and
+   * previous / next follow the list as it now is. Checked in turn: the open
+   * position (the chunk stayed), the last one (a store that appends the new
+   * copy), then the whole filtered list. Each probe matches by id, so no
+   * store ordering is assumed. When the chunk is not in the list (a search
+   * it no longer matches), what is shown stays.
+   *
+   * @param chunk The chunk just saved, with its new id.
+   */
+  const locateOpenChunk = async (chunk: ChunkType) => {
+    const request = ++stepRef.current;
+    const fetchPage = async (pageNumber: number, size: number) => {
+      const response = await userService.getDocumentChunks(
+        documentId,
+        pageNumber,
+        size,
+        token,
+        path,
+        debouncedSearchTerm,
+      );
+      if (!response.ok) return null;
+      const data = await response.json();
+      return request === stepRef.current ? data : null;
+    };
+    const show = (stored: ChunkType, at: number, total: number) => {
+      setTotalChunks(total);
+      setOpenChunk(stored);
+      setOpenPosition(at);
+    };
+    try {
+      const here = await fetchPage(openPosition, 1);
+      if (!here) return;
+      const total: number =
+        typeof here.total === 'number' ? here.total : totalChunks;
+      const stored: ChunkType | undefined = here.chunks?.[0];
+      if (stored?.doc_id === chunk.doc_id) {
+        show(stored, openPosition, total);
+        return;
+      }
+      if (total < 1) return;
+      if (total !== openPosition) {
+        const last = await fetchPage(total, 1);
+        if (!last) return;
+        const lastChunk: ChunkType | undefined = last.chunks?.[0];
+        if (lastChunk?.doc_id === chunk.doc_id) {
+          show(lastChunk, total, total);
+          return;
+        }
+      }
+      const all = await fetchPage(1, total);
+      if (!all) return;
+      const list: ChunkType[] = all.chunks ?? [];
+      const index = list.findIndex((c) => c.doc_id === chunk.doc_id);
+      if (index >= 0)
+        show(
+          list[index],
+          index + 1,
+          typeof all.total === 'number' ? all.total : total,
+        );
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  /**
+   * Back to the grid, on the page holding the chunk last open.
+   *
+   * @param total The chunk count to page against, when it just changed (a
+   *   delete); the page is clamped to the last one that still exists.
+   * @returns Whether the page changed (and so fetches by itself).
+   */
+  const closeChunk = (total = totalChunks) => {
+    stepRef.current++;
+    setStepping(false);
+    const lastPage = Math.max(1, Math.ceil(total / perPage));
+    const target = Math.min(
+      lastPage,
+      Math.max(1, Math.ceil(openPosition / perPage)),
+    );
+    setOpenChunk(null);
+    if (target !== page) setPage(target);
+    return target !== page;
+  };
+
+  useImperativeHandle(controllerRef, () => ({
+    closeChunk: () => closeChunk(),
+  }));
+
+  const openChunkPosition = openChunk ? openPosition : null;
+  const onOpenChunkChangeRef = useRef(onOpenChunkChange);
+  useEffect(() => {
+    onOpenChunkChangeRef.current = onOpenChunkChange;
+  });
+  useEffect(() => {
+    onOpenChunkChangeRef.current?.(openChunkPosition);
+  }, [openChunkPosition]);
+  useEffect(() => () => onOpenChunkChangeRef.current?.(null), []);
+
+  const showChunk = (chunk: ChunkType, position: number) => {
+    setOpenChunk(chunk);
+    setOpenPosition(position);
+  };
+
+  /**
+   * A new chunk's title: the one this file's chunks are cited by, else the
+   * file's name, as ingest sets it.
+   */
+  const defaultTitle = () =>
+    paginatedChunks.find((chunk) => chunk.metadata?.title)?.metadata.title ||
+    fileName ||
+    path?.split('/').pop() ||
+    documentName ||
+    '';
+
+  const openSheet = (mode: SheetMode) => {
+    const baseline = mode === 'add' ? defaultTitle() : '';
+    setDraft(mode === 'edit' ? openChunk?.text || '' : '');
+    setDraftTitle(
+      mode === 'edit' ? openChunk?.metadata?.title || '' : baseline,
+    );
+    setAddBaselineTitle(baseline);
+    setSaveFailed(false);
+    setSheetMode(mode);
+    setSheetOpen(true);
+  };
+
+  const closeSheet = () => {
+    setSheetOpen(false);
+    setSaveFailed(false);
+  };
+
+  const handleAddChunk = async (text: string, title: string) => {
+    if (!text.trim()) return;
+    setSaving(true);
+    setSaveFailed(false);
+    try {
+      const response = await userService.addChunk(
+        {
+          id: documentId,
+          text,
+          metadata: {
+            source: path || documentName,
+            source_id: documentId,
+            title: title.trim(),
+          },
+        },
+        token,
+      );
+      if (!response.ok) throw new Error('Failed to add chunk');
+      closeSheet();
+      fetchChunks();
+    } catch (e) {
+      console.error(e);
+      setSaveFailed(true);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleUpdateChunk = async (
+    text: string,
+    title: string,
+    chunk: ChunkType,
+  ) => {
+    const savedTitle = chunk.metadata?.title || '';
+    if (!text.trim()) return;
+    if (text === (chunk.text || '') && title.trim() === savedTitle) return;
+    setSaving(true);
+    setSaveFailed(false);
+    // The backend merges metadata: send a title only when the chunk had one
+    // (clearing it sends '') or one was entered, never '' onto an untitled one.
+    const sendTitle = !!savedTitle || !!title.trim();
+    try {
+      const response = await userService.updateChunk(
+        {
+          id: documentId,
+          chunk_id: chunk.doc_id,
+          text,
+          ...(sendTitle ? { metadata: { title: title.trim() } } : {}),
+        },
+        token,
+      );
+      if (!response.ok) throw new Error('Failed to update chunk');
+      const data = await response.json().catch(() => ({}));
+      closeSheet();
+      // The edit is saved under a new id. Show it straight away (its token
+      // count is recomputed server-side, so it is dropped until the reload),
+      // then find where the store now keeps it: the update re-adds the chunk,
+      // so it can move (FAISS appends it; pgvector has no ORDER BY).
+      const edited: ChunkType = {
+        ...chunk,
+        doc_id: data.chunk_id ?? chunk.doc_id,
+        text,
+        metadata: {
+          ...chunk.metadata,
+          ...(sendTitle ? { title: title.trim() } : {}),
+          token_count: undefined,
+        },
       };
-
-      userService
-        .addChunk(
-          {
-            id: documentId,
-            text: text,
-            metadata: metadata,
-          },
-          token,
-        )
-        .then((response) => {
-          if (!response.ok) {
-            throw new Error('Failed to add chunk');
-          }
-          fetchChunks();
-        });
+      setOpenChunk(edited);
+      locateOpenChunk(edited);
+      fetchChunks();
     } catch (e) {
-      console.log(e);
+      console.error(e);
+      setSaveFailed(true);
+    } finally {
+      setSaving(false);
     }
   };
 
-  const handleUpdateChunk = (title: string, text: string, chunk: ChunkType) => {
-    if (!text.trim()) {
-      return;
-    }
-
-    const originalTitle = chunk.metadata?.title || '';
-    const originalText = chunk.text || '';
-
-    if (title === originalTitle && text === originalText) {
-      return;
-    }
-
+  const handleDeleteChunk = async (chunk: ChunkType) => {
     try {
-      userService
-        .updateChunk(
-          {
-            id: documentId,
-            chunk_id: chunk.doc_id,
-            text: text,
-            metadata: {
-              title: title,
-            },
-          },
-          token,
-        )
-        .then((response) => {
-          if (!response.ok) {
-            throw new Error('Failed to update chunk');
-          }
-          fetchChunks();
-        });
+      const response = await userService.deleteChunk(
+        documentId,
+        chunk.doc_id,
+        token,
+      );
+      if (!response.ok) throw new Error('Failed to delete chunk');
+      // A page change fetches by itself; otherwise refresh this page.
+      if (!closeChunk(Math.max(0, totalChunks - 1))) fetchChunks();
     } catch (e) {
-      console.log(e);
-    }
-  };
-
-  const handleDeleteChunk = (chunk: ChunkType) => {
-    try {
-      userService
-        .deleteChunk(documentId, chunk.doc_id, token)
-        .then((response) => {
-          if (!response.ok) {
-            throw new Error('Failed to delete chunk');
-          }
-          setEditingChunk(null);
-          fetchChunks();
-        });
-    } catch (e) {
-      console.log(e);
+      console.error(e);
+      showError(t('settings.sources.chunkErrors.delete'));
     }
   };
 
@@ -309,396 +453,335 @@ const Chunks: React.FC<ChunksProps> = ({
     setChunkToDelete(null);
   };
 
+  // One fetch per page, page size, file or search; a new search starts on
+  // page 1 (that page change then fetches).
+  const fetchedSearchRef = useRef(debouncedSearchTerm);
   useEffect(() => {
-    if (page !== 1) {
-      setPage(1);
-    } else {
-      fetchChunks();
+    if (fetchedSearchRef.current !== debouncedSearchTerm) {
+      fetchedSearchRef.current = debouncedSearchTerm;
+      if (page !== 1) {
+        setPage(1);
+        return;
+      }
     }
-  }, [debouncedSearchTerm]);
-
-  useEffect(() => {
-    !loading && fetchChunks();
-  }, [page, perPage, path]);
+    fetchChunks();
+  }, [page, perPage, path, debouncedSearchTerm]);
 
   useEffect(() => {
     setSearchTerm('');
     setPage(1);
   }, [path]);
 
-  const filteredChunks = paginatedChunks;
+  const canGoPrevious = !!openChunk && !stepping && openPosition > 1;
+  const canGoNext = !!openChunk && !stepping && openPosition < totalChunks;
 
-  // The root crumb returns to the source (TreeBrowser: its top folder;
-  // standalone: back to the source list). Folder crumbs only navigate when
-  // the parent can open a folder (onPathSelect); the file is the current one.
-  const renderPathNavigation = () => {
-    const rootLabel = documentName ?? '';
-    const selectRoot = onPathSelect ? () => onPathSelect(0) : handleGoBack;
-    return (
-      <PathHeader
-        root={{
-          label: rootLabel,
-          onSelect: pathParts.length > 0 ? selectRoot : undefined,
-        }}
-        segments={pathParts.map((part, index) => ({
-          label: part,
-          onSelect:
-            onPathSelect && index < pathParts.length - 1
-              ? () => onPathSelect(index + 1)
-              : undefined,
-        }))}
-        backLabel={t('settings.sources.back')}
-        onBack={
-          editingChunk
-            ? () => setEditingChunk(null)
-            : isAddingChunk
-              ? () => setIsAddingChunk(false)
-              : handleGoBack
-        }
-        actions={
-          headerAction || editingChunk || isAddingChunk ? (
-            <>
-              {headerAction}
-              {editingChunk ? (
-                !isEditing ? (
-                  <>
-                    <Button
-                      type="button"
-                      size="field"
-                      shape="pill"
-                      onClick={() => setIsEditing(true)}
-                    >
-                      {t('modals.chunk.edit')}
-                    </Button>
-                    <Button
-                      type="button"
-                      variant="destructive-outline"
-                      size="field"
-                      shape="pill"
-                      onClick={() => {
-                        confirmDeleteChunk(editingChunk);
-                      }}
-                    >
-                      {t('modals.chunk.delete')}
-                    </Button>
-                  </>
-                ) : (
-                  <>
-                    <Button
-                      type="button"
-                      variant="ghost"
-                      onClick={() => {
-                        setIsEditing(false);
-                      }}
-                      size="field"
-                      shape="pill"
-                    >
-                      {t('modals.chunk.cancel')}
-                    </Button>
-                    <Button
-                      type="button"
-                      onClick={() => {
-                        if (editingText.trim()) {
-                          const hasChanges =
-                            editingTitle !==
-                              (editingChunk?.metadata?.title || '') ||
-                            editingText !== (editingChunk?.text || '');
+  // ← / → walk the chunks while nothing else owns the keys.
+  const goToChunkRef = useRef(goToChunk);
+  goToChunkRef.current = goToChunk;
+  useEffect(() => {
+    if (!openChunk || sheetOpen) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
+      if (keyBelongsElsewhere(event)) return;
+      if (event.key === 'ArrowLeft' && !canGoPrevious) return;
+      if (event.key === 'ArrowRight' && !canGoNext) return;
+      event.preventDefault();
+      goToChunkRef.current(openPosition + (event.key === 'ArrowLeft' ? -1 : 1));
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [openChunk, sheetOpen, canGoPrevious, canGoNext, openPosition]);
 
-                          if (hasChanges) {
-                            handleUpdateChunk(
-                              editingTitle,
-                              editingText,
-                              editingChunk,
-                            );
-                          }
-                          setIsEditing(false);
-                          setEditingChunk(null);
-                        }
-                      }}
-                      disabled={
-                        !editingText.trim() ||
-                        (editingTitle ===
-                          (editingChunk?.metadata?.title || '') &&
-                          editingText === (editingChunk?.text || ''))
-                      }
-                      size="field"
-                      shape="pill"
-                    >
-                      {t('modals.chunk.save')}
-                    </Button>
-                  </>
-                )
-              ) : isAddingChunk ? (
-                <>
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    onClick={() => setIsAddingChunk(false)}
-                    size="field"
-                    shape="pill"
-                  >
-                    {t('modals.chunk.cancel')}
-                  </Button>
-                  <Button
-                    type="button"
-                    onClick={() => {
-                      if (editingText.trim()) {
-                        handleAddChunk(editingTitle, editingText);
-                        setIsAddingChunk(false);
-                      }
-                    }}
-                    disabled={!editingText.trim()}
-                    size="field"
-                    shape="pill"
-                  >
-                    {t('modals.chunk.add')}
-                  </Button>
-                </>
-              ) : null}
-            </>
-          ) : undefined
-        }
-      />
-    );
-  };
-
-  // File search handling
-  const handleFileSearchChange = (query: string) => {
-    setFileSearchQuery(query);
-    if (query.trim() && onFileSearch) {
-      const results = onFileSearch(query);
-      setFileSearchResults(results);
-    } else {
-      setFileSearchResults([]);
-    }
-  };
-
-  const handleSearchResultClick = (result: SearchResult) => {
-    if (!onFileSelect) return;
-
-    if (result.isFile) {
-      onFileSelect(result.path);
-    } else {
-      // For directories, navigate to the directory and return to file tree
-      onFileSelect(result.path);
-      handleGoBack();
-    }
-    setFileSearchQuery('');
-    setFileSearchResults([]);
-  };
-
-  useOutsideAlerter(
-    searchDropdownRef,
-    () => {
-      setFileSearchQuery('');
-      setFileSearchResults([]);
-    },
-    [], // No additional dependencies
-    false, // Don't handle escape key
+  // Standalone (a non-nested source): Sources, the source, then the open
+  // chunk; the source crumb closes the chunk, the Sources crumb leaves.
+  const renderHeader = () => (
+    <PathHeader
+      root={{ label: t('settings.sources.label'), onSelect: handleGoBack }}
+      segments={[
+        {
+          label: documentName ?? '',
+          onSelect: openChunk ? () => closeChunk() : undefined,
+        },
+        ...(openChunk
+          ? [{ label: t('settings.sources.chunkCrumb', { n: openPosition }) }]
+          : []),
+      ]}
+      byline={
+        loading && totalChunks === 0
+          ? undefined
+          : t('settings.sources.chunkCount', {
+              count: totalChunks,
+              formatted: abbreviateCount(totalChunks),
+            })
+      }
+      actions={headerAction}
+    />
   );
 
-  const renderFileSearch = () => {
-    return (
-      <div className="relative" ref={searchDropdownRef}>
-        {/* `contents`: the Command only scopes cmdk (the arrow keys move from
-            the input to the rows); the frame and the dropdown draw the look. */}
-        <Command shouldFilter={false} className="contents">
-          <div className={SEARCH_FRAME}>
-            <CommandInput
-              value={fileSearchQuery}
-              onValueChange={handleFileSearchChange}
-              placeholder={t('settings.sources.searchFiles')}
-            />
-          </div>
+  const renderToolbar = () => (
+    <div className="flex flex-col gap-3 sm:flex-row sm:items-center">
+      <div className="w-full min-w-0 sm:max-w-md sm:flex-1">
+        <SearchInput
+          label={t('settings.sources.searchChunks')}
+          value={searchTerm}
+          onChange={(e) => setSearchTerm(e.target.value)}
+        />
+      </div>
+      {/* Standalone, the header's byline already shows the count. */}
+      {embedded && !(loading && totalChunks === 0) ? (
+        <p className="text-muted-foreground text-sm whitespace-nowrap">
+          {t('settings.sources.chunkCount', {
+            count: totalChunks,
+            formatted: abbreviateCount(totalChunks),
+          })}
+        </p>
+      ) : null}
+      <Button
+        type="button"
+        size="field"
+        shape="pill"
+        className="sm:ml-auto"
+        onClick={() => openSheet('add')}
+      >
+        {t('settings.sources.addChunk')}
+      </Button>
+    </div>
+  );
 
-          {fileSearchQuery && (
-            <div className="border-border bg-popover text-popover-foreground absolute top-full right-0 left-0 z-20 mt-1 w-full overflow-hidden rounded-xl border shadow-md">
-              <CommandList className="max-h-[calc(100dvh-200px)]">
-                {fileSearchResults.length === 0 ? (
-                  <CommandEmpty>{t('settings.sources.noResults')}</CommandEmpty>
-                ) : (
-                  <CommandGroup>
-                    {fileSearchResults.map((result) => (
-                      <CommandItem
-                        key={result.path}
-                        value={result.path}
-                        title={result.path}
-                        onSelect={() => handleSearchResultClick(result)}
-                      >
-                        {result.isFile ? (
-                          <File />
-                        ) : (
-                          <Folder className="text-primary" />
-                        )}
-                        <span className="truncate">
-                          {result.name ||
-                            result.path.split('/').pop() ||
-                            result.path}
-                        </span>
-                      </CommandItem>
-                    ))}
-                  </CommandGroup>
-                )}
-              </CommandList>
-            </div>
-          )}
-        </Command>
+  const renderList = () => {
+    if (loading) {
+      return (
+        <div className={TILE_GRID}>
+          <SkeletonLoader component="chunkCards" count={perPage} />
+        </div>
+      );
+    }
+    if (loadFailed) {
+      return (
+        <EmptyState
+          tone="destructive"
+          illustration="none"
+          title={t('settings.sources.chunkErrors.load')}
+          action={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={() => fetchChunks()}
+            >
+              {t('retry')}
+            </Button>
+          }
+        />
+      );
+    }
+    return (
+      <div className={TILE_GRID}>
+        {paginatedChunks.length === 0 ? (
+          <EmptyState
+            size="sm"
+            title={t('settings.sources.noChunks')}
+            className="col-span-full min-h-[50svh] w-full"
+          />
+        ) : (
+          paginatedChunks.map((chunk, index) => {
+            const position = (page - 1) * perPage + index + 1;
+            return (
+              <Card
+                key={chunk.doc_id}
+                variant="filled"
+                padding="lg"
+                interactive
+                asChild
+                className="h-50 w-full justify-between"
+              >
+                <button
+                  type="button"
+                  onClick={() => showChunk(chunk, position)}
+                >
+                  <p className="text-foreground line-clamp-6 text-sm leading-5 font-normal">
+                    {chunkPreviewText(chunk.text)}
+                  </p>
+                  <CardFooter>
+                    {t('settings.sources.chunkTileMeta', {
+                      n: position,
+                      tokens: formatChunkTokens(chunk.metadata),
+                    })}
+                  </CardFooter>
+                </button>
+              </Card>
+            );
+          })
+        )}
       </div>
     );
   };
 
+  const renderOpenChunk = (chunk: ChunkType) => (
+    <ReaderPanel
+      meta={
+        <span>
+          {t('settings.sources.chunkPosition', {
+            n: openPosition,
+            total: totalChunks,
+            tokens: formatChunkTokens(chunk.metadata),
+          })}
+        </span>
+      }
+      actions={
+        <>
+          <IconButton
+            variant="ghost-muted"
+            size="icon-sm"
+            shape="pill"
+            label={t('settings.sources.previousChunk')}
+            icon={ChevronLeft}
+            side="bottom"
+            disabled={!canGoPrevious}
+            onClick={() => goToChunk(openPosition - 1)}
+          />
+          <IconButton
+            variant="ghost-muted"
+            size="icon-sm"
+            shape="pill"
+            label={t('settings.sources.nextChunk')}
+            icon={ChevronRight}
+            side="bottom"
+            disabled={!canGoNext}
+            onClick={() => goToChunk(openPosition + 1)}
+          />
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            shape="pill"
+            onClick={() => openSheet('edit')}
+          >
+            <Pencil />
+            {t('modals.chunk.edit')}
+          </Button>
+          <ActionMenu
+            size="toolbar"
+            triggerLabel={t('settings.sources.menuAlt')}
+            options={[
+              {
+                icon: Copy,
+                label: t('settings.sources.copyText'),
+                onClick: () => {
+                  copy(chunk.text || '');
+                  dispatch(
+                    showActionToast({
+                      variant: 'success',
+                      message: t('conversation.copied'),
+                    }),
+                  );
+                },
+              },
+              {
+                icon: Trash2,
+                label: t('modals.chunk.delete'),
+                variant: 'destructive',
+                onClick: () => confirmDeleteChunk(chunk),
+              },
+            ]}
+          />
+        </>
+      }
+    >
+      <SourceMarkdown content={chunk.text || ''} />
+    </ReaderPanel>
+  );
+
+  const editing = sheetMode === 'edit' && !!openChunk;
+  const savedText = editing ? openChunk?.text || '' : '';
+  const savedTitle = editing
+    ? openChunk?.metadata?.title || ''
+    : addBaselineTitle;
+
   return (
-    <div className="flex flex-col">
-      <div className="mb-2">{renderPathNavigation()}</div>
-      <div className="flex gap-4">
-        {onFileSearch && onFileSelect && (
-          <div className="hidden w-[198px] lg:block">{renderFileSearch()}</div>
-        )}
-
-        {/* Right side: Chunks content */}
-        <div className="flex-1">
-          {!editingChunk && !isAddingChunk ? (
-            <>
-              <div className="mb-3 flex flex-col items-start justify-between gap-3 sm:flex-row sm:items-center">
-                <div className="border-border flex h-9.5 w-full flex-1 items-center overflow-hidden rounded-md border">
-                  <div className="text-foreground flex h-full items-center px-4 font-medium whitespace-nowrap">
-                    {totalChunks > 999999
-                      ? `${(totalChunks / 1000000).toFixed(2)}M`
-                      : totalChunks > 999
-                        ? `${(totalChunks / 1000).toFixed(2)}K`
-                        : totalChunks}{' '}
-                    {t('settings.sources.chunks')}
-                  </div>
-                  <div className="bg-border h-full w-px"></div>
-                  <div className="h-full flex-1 px-3 py-2">
-                    <Input
-                      type="text"
-                      variant="bare"
-                      placeholder={t('settings.sources.searchPlaceholder')}
-                      value={searchTerm}
-                      onChange={(e) => setSearchTerm(e.target.value)}
-                      className="h-full"
-                    />
-                  </div>
-                </div>
-                <Button
-                  type="button"
-                  size="field"
-                  shape="pill"
-                  className="w-full shrink-0 sm:w-auto"
-                  onClick={() => {
-                    setIsAddingChunk(true);
-                    setEditingTitle('');
-                    setEditingText('');
-                  }}
-                >
-                  {t('settings.sources.addChunk')}
-                </Button>
-              </div>
-              {loading ? (
-                <div className="grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]">
-                  <SkeletonLoader component="chunkCards" count={perPage} />
-                </div>
-              ) : (
-                <div className="grid grid-cols-1 gap-4 sm:grid-cols-[repeat(auto-fit,minmax(min(400px,100%),1fr))]">
-                  {filteredChunks.length === 0 ? (
-                    <EmptyState
-                      size="sm"
-                      title={t('settings.sources.noChunks')}
-                      className="col-span-full min-h-[50svh] w-full"
-                    />
-                  ) : (
-                    filteredChunks.map((chunk, index) => (
-                      <Card
-                        key={index}
-                        variant="filled"
-                        padding="lg"
-                        interactive
-                        asChild
-                        className="h-50 w-full justify-between"
-                      >
-                        <button
-                          type="button"
-                          onClick={() => {
-                            setEditingChunk(chunk);
-                            setEditingTitle(chunk.metadata?.title || '');
-                            setEditingText(chunk.text || '');
-                          }}
-                        >
-                          <p className="text-foreground line-clamp-6 text-sm leading-5 font-normal">
-                            {chunk.text}
-                          </p>
-                          <CardFooter>
-                            {formatChunkTokens(chunk.metadata)}{' '}
-                            {t('settings.sources.tokensUnit')}
-                          </CardFooter>
-                        </button>
-                      </Card>
-                    ))
-                  )}
-                </div>
-              )}
-            </>
-          ) : isAddingChunk ? (
-            <div className="w-full">
-              <div className="border-border relative overflow-hidden rounded-lg border">
-                <LineNumberedTextarea
-                  value={editingText}
-                  onChange={setEditingText}
-                  ariaLabel={t('modals.chunk.promptText')}
-                  editable={true}
-                />
-              </div>
-            </div>
-          ) : (
-            editingChunk && (
-              <div className="w-full">
-                <div className="border-border relative flex w-full flex-col overflow-hidden rounded-md border">
-                  <div className="border-border bg-muted flex w-full items-center justify-between border-b px-4 py-3">
-                    <div className="text-muted-foreground text-sm">
-                      {formatChunkTokens(editingChunk.metadata)}{' '}
-                      {t('settings.sources.tokensUnit')}
-                    </div>
-                  </div>
-                  <div className="overflow-hidden p-4">
-                    <LineNumberedTextarea
-                      value={isEditing ? editingText : editingChunk.text}
-                      onChange={setEditingText}
-                      ariaLabel={t('modals.chunk.promptText')}
-                      editable={isEditing}
-                      onDoubleClick={() => {
-                        if (!isEditing) {
-                          setIsEditing(true);
-                          setEditingTitle(editingChunk.metadata.title || '');
-                          setEditingText(editingChunk.text);
-                        }
-                      }}
-                    />
-                  </div>
-                </div>
-              </div>
-            )
-          )}
-
-          {!loading &&
-            totalChunks > perPage &&
-            !editingChunk &&
-            !isAddingChunk && (
-              <Pagination
-                page={page}
-                pageCount={Math.ceil(totalChunks / perPage)}
-                pageSize={perPage}
-                onPageChange={setPage}
-                onPageSizeChange={(rows) => {
-                  setPerPage(rows);
-                  setPage(1);
-                }}
-              />
-            )}
+    <div className="flex min-w-0 flex-col gap-4">
+      {embedded ? null : renderHeader()}
+      {openChunk ? (
+        renderOpenChunk(openChunk)
+      ) : (
+        <div className="flex flex-col gap-4">
+          {renderToolbar()}
+          {renderList()}
+          {/* Past the smallest page size a different size can change the
+              grid, so the pager (and its size select) stays even at 1 page. */}
+          {!loading && !loadFailed && totalChunks > PAGE_SIZE_OPTIONS[0] ? (
+            <Pagination
+              page={page}
+              pageCount={Math.ceil(totalChunks / perPage)}
+              pageSize={perPage}
+              pageSizeOptions={PAGE_SIZE_OPTIONS}
+              pageSizeLabel={t('pagination.chunksPerPage')}
+              onPageChange={setPage}
+              onPageSizeChange={(rows) => {
+                setPerPage(rows);
+                setPage(1);
+              }}
+            />
+          ) : null}
         </div>
-      </div>
+      )}
+
+      <SourceEditSheet
+        open={sheetOpen}
+        onClose={closeSheet}
+        title={
+          editing
+            ? t('settings.sources.editChunk')
+            : t('settings.sources.addChunk')
+        }
+        description={
+          editing
+            ? t('settings.sources.editChunkDescription', {
+                file: fileLabel,
+                n: openPosition,
+                tokens: formatChunkTokens(openChunk?.metadata),
+                interpolation: { escapeValue: false },
+              })
+            : fileLabel || undefined
+        }
+        value={draft}
+        onChange={setDraft}
+        dirty={draft !== savedText || draftTitle.trim() !== savedTitle}
+        onSave={() =>
+          editing && openChunk
+            ? handleUpdateChunk(draft, draftTitle, openChunk)
+            : handleAddChunk(draft, draftTitle)
+        }
+        fields={
+          <FormField
+            label={t('modals.chunk.title')}
+            hint={t('settings.sources.chunkTitleHint')}
+            labelSurface="background"
+          >
+            <Input
+              value={draftTitle}
+              onChange={(event) => setDraftTitle(event.target.value)}
+              disabled={saving}
+            />
+          </FormField>
+        }
+        saving={saving}
+        saveLabel={editing ? t('modals.chunk.save') : t('modals.chunk.add')}
+        alert={
+          saveFailed ? (
+            <Alert variant="destructive">
+              <AlertDescription>
+                {editing
+                  ? t('settings.sources.chunkErrors.save')
+                  : t('settings.sources.chunkErrors.add')}
+              </AlertDescription>
+            </Alert>
+          ) : undefined
+        }
+        fieldLabel={t('modals.chunk.bodyText')}
+      />
 
-      {/* Delete Confirmation Modal */}
       <ConfirmationModal
         message={t('modals.chunk.deleteConfirmation')}
         modalState={deleteModalState}
diff --git a/frontend/src/components/ConnectorTree.test.tsx b/frontend/src/components/ConnectorTree.test.tsx
new file mode 100644
index 00000000..cde38ca5
--- /dev/null
+++ b/frontend/src/components/ConnectorTree.test.tsx
@@ -0,0 +1,147 @@
+import { act, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => null,
+  useDispatch: () => vi.fn(),
+  useStore: () => ({ getState: () => ({}), subscribe: () => () => {} }),
+}));
+
+vi.mock('../hooks', () => ({
+  useDarkTheme: () => [false],
+  useDebouncedValue: (value: unknown) => value,
+  useLoaderState: (initial: boolean) => useState(initial),
+  useMediaQuery: () => ({ isMobile: false, isDesktop: true }),
+  useOutsideAlerter: () => undefined,
+}));
+
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getDirectoryStructure: vi.fn(async () => ({
+      json: async () => ({
+        provider: 'google_drive',
+        directory_structure: {
+          'a.docx': { type: 'docx' },
+          'b.docx': { type: 'docx' },
+        },
+      }),
+    })),
+    getDocumentChunks: vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ page: 1, per_page: 12, total: 0, chunks: [] }),
+    })),
+  },
+}));
+
+import ConnectorTree, { providerLabel } from './ConnectorTree';
+import FileTree from './FileTree';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('providerLabel', () => {
+  it('names known providers and title-cases the rest', () => {
+    expect(providerLabel('google_drive')).toBe('Google Drive');
+    expect(providerLabel('share_point')).toBe('SharePoint');
+    expect(providerLabel('box_sync')).toBe('Box Sync');
+  });
+});
+
+describe('ConnectorTree and FileTree headers', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (node: React.ReactNode) => {
+    await act(async () => root.render(node));
+  };
+
+  const badge = () => container.querySelector('[data-slot="badge"]');
+  const retrieval = <button type="button">retrieval</button>;
+
+  it('ConnectorTree shows the provider badge, headerAction and Sync', async () => {
+    await render(
+      <ConnectorTree
+        docId="doc"
+        sourceName="Drive"
+        onBackToDocuments={vi.fn()}
+        headerAction={retrieval}
+      />,
+    );
+    expect(badge()!.textContent).toBe('Google Drive');
+    expect(badge()!.getAttribute('data-variant')).toBe('neutral');
+    expect(container.textContent).toContain('retrieval');
+    expect(container.textContent).toContain('settings.sources.sync');
+  });
+
+  it('embedded ConnectorTree drops the badge and headerAction, keeps Sync', async () => {
+    await render(
+      <ConnectorTree
+        embedded
+        docId="doc"
+        sourceName="Drive"
+        onBackToDocuments={vi.fn()}
+        headerAction={retrieval}
+      />,
+    );
+    expect(badge()).toBeNull();
+    expect(container.textContent).not.toContain('retrieval');
+    expect(container.textContent).toContain('settings.sources.sync');
+    expect(container.textContent).not.toContain('settings.sources.label');
+  });
+
+  it('embedded FileTree drops headerAction, keeps Add file', async () => {
+    await render(
+      <FileTree
+        embedded
+        docId="doc"
+        sourceName="Files"
+        onBackToDocuments={vi.fn()}
+        headerAction={retrieval}
+      />,
+    );
+    expect(badge()).toBeNull();
+    expect(container.textContent).not.toContain('retrieval');
+    expect(container.textContent).toContain('settings.sources.addFile');
+  });
+
+  const crumbs = () =>
+    Array.from(container.querySelectorAll('[data-slot="breadcrumb-item"]')).map(
+      (el) => el.textContent,
+    );
+
+  it('ConnectorTree and FileTree open the initialPath file', async () => {
+    await render(
+      <ConnectorTree
+        docId="doc"
+        sourceName="Drive"
+        onBackToDocuments={vi.fn()}
+        initialPath="b.docx"
+      />,
+    );
+    expect(crumbs()).toEqual(['settings.sources.label', 'Drive', 'b.docx']);
+
+    await render(
+      <FileTree
+        docId="doc"
+        sourceName="Files"
+        onBackToDocuments={vi.fn()}
+        initialPath="a.docx"
+      />,
+    );
+    expect(crumbs()).toEqual(['settings.sources.label', 'Files', 'a.docx']);
+  });
+});
diff --git a/frontend/src/components/ConnectorTree.tsx b/frontend/src/components/ConnectorTree.tsx
index a3d8135b..3b5bac0a 100644
--- a/frontend/src/components/ConnectorTree.tsx
+++ b/frontend/src/components/ConnectorTree.tsx
@@ -1,14 +1,16 @@
 import React, { useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
-import { Check, RefreshCw } from 'lucide-react';
+import { Check, Cloud, RefreshCw } from 'lucide-react';
 
 import userService from '../api/services/userService';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Spinner } from '@/components/ui/spinner';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { ActiveState } from '../models/misc';
 import { selectToken } from '../preferences/preferenceSlice';
+import type { Crumb } from './tree/PathHeader';
 import TreeBrowser from './tree/TreeBrowser';
 import type { TreeBrowserController } from './tree/types';
 import { useReingestSseWaiter } from './tree/useReingestWait';
@@ -19,6 +21,38 @@ interface ConnectorTreeProps {
   onBackToDocuments: () => void;
   /** Extra header control, rendered left of the Sync button. */
   headerAction?: React.ReactNode;
+  /**
+   * Inside another source view (the graph source's Files tab): no Sources
+   * crumb, badge or byline, and no headerAction; Sync stays.
+   */
+  embedded?: boolean;
+  /** Embedded only: the host header's action slot (see TreeBrowser). */
+  actionsTarget?: HTMLElement | null;
+  /** A file to open once the structure loads (path, file name or display name). */
+  initialPath?: string;
+  /** Embedded only: the tree's crumbs, for the host's header (see TreeBrowser). */
+  onCrumbsChange?: (crumbs: Crumb[]) => void;
+}
+
+// Provider names are brand names, so they are not translated.
+const PROVIDER_LABELS: Record<string, string> = {
+  google_drive: 'Google Drive',
+  share_point: 'SharePoint',
+  confluence: 'Confluence',
+};
+
+/**
+ * The display name of a connector provider: a known brand name, else the raw
+ * id with underscores as spaces, title-cased ("box_sync" → "Box Sync").
+ */
+export function providerLabel(provider: string): string {
+  const known = PROVIDER_LABELS[provider.toLowerCase()];
+  if (known) return known;
+  return provider
+    .split('_')
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
 }
 
 const ConnectorTree: React.FC<ConnectorTreeProps> = ({
@@ -26,6 +60,10 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
   sourceName,
   onBackToDocuments,
   headerAction,
+  embedded = false,
+  actionsTarget,
+  initialPath,
+  onCrumbsChange,
 }) => {
   const { t } = useTranslation();
   const token = useSelector(selectToken);
@@ -106,7 +144,7 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
 
   const topRightAction = (
     <>
-      {headerAction}
+      {embedded ? null : headerAction}
       <Button
         type="button"
         size="field"
@@ -126,7 +164,7 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
         {isSyncing
           ? `${syncProgress}%`
           : syncDone
-            ? 'Done'
+            ? t('settings.sources.syncDone')
             : t('settings.sources.sync')}
       </Button>
     </>
@@ -148,6 +186,18 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
       docId={docId}
       sourceName={sourceName}
       onBackToDocuments={onBackToDocuments}
+      embedded={embedded}
+      onCrumbsChange={onCrumbsChange}
+      actionsTarget={actionsTarget}
+      initialPath={initialPath}
+      badge={
+        sourceProvider ? (
+          <Badge variant="neutral">
+            <Cloud />
+            {providerLabel(sourceProvider)}
+          </Badge>
+        ) : undefined
+      }
       columnOrder="tokens-first"
       sortEntries
       controllerRef={controllerRef}
diff --git a/frontend/src/components/FileTree.tsx b/frontend/src/components/FileTree.tsx
index b406a2d2..f4f78e1e 100644
--- a/frontend/src/components/FileTree.tsx
+++ b/frontend/src/components/FileTree.tsx
@@ -6,6 +6,7 @@ import { Trash2 } from 'lucide-react';
 import { SOURCE_FILE_TREE_ACCEPT_ATTR } from '../constants/fileUpload';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { selectToken } from '../preferences/preferenceSlice';
+import type { Crumb } from './tree/PathHeader';
 import TreeBrowser from './tree/TreeBrowser';
 import { Button } from './ui/button';
 import type { MenuOption } from './ui/dropdown-menu';
@@ -26,6 +27,17 @@ interface FileTreeProps {
   onBackToDocuments: () => void;
   /** Extra header control, rendered left of "Add file". */
   headerAction?: React.ReactNode;
+  /**
+   * Inside another source view (the graph source's Files tab): no Sources
+   * crumb, badge or byline, and no headerAction; Add file stays.
+   */
+  embedded?: boolean;
+  /** Embedded only: the host header's action slot (see TreeBrowser). */
+  actionsTarget?: HTMLElement | null;
+  /** A file to open once the structure loads (path, file name or display name). */
+  initialPath?: string;
+  /** Embedded only: the tree's crumbs, for the host's header (see TreeBrowser). */
+  onCrumbsChange?: (crumbs: Crumb[]) => void;
 }
 
 const FileTree: React.FC<FileTreeProps> = ({
@@ -33,6 +45,10 @@ const FileTree: React.FC<FileTreeProps> = ({
   sourceName,
   onBackToDocuments,
   headerAction,
+  embedded = false,
+  actionsTarget,
+  initialPath,
+  onCrumbsChange,
 }) => {
   const { t } = useTranslation();
   const token = useSelector(selectToken);
@@ -231,7 +247,7 @@ const FileTree: React.FC<FileTreeProps> = ({
   // Add file button is suppressed then.
   const topRightAction = (
     <>
-      {headerAction}
+      {embedded ? null : headerAction}
       {!isProcessing ? (
         <Button type="button" size="field" shape="pill" onClick={handleAddFile}>
           {t('settings.sources.addFile')}
@@ -263,6 +279,10 @@ const FileTree: React.FC<FileTreeProps> = ({
       docId={docId}
       sourceName={sourceName}
       onBackToDocuments={onBackToDocuments}
+      embedded={embedded}
+      onCrumbsChange={onCrumbsChange}
+      actionsTarget={actionsTarget}
+      initialPath={initialPath}
       columnOrder="size-first"
       sortEntries={false}
       controllerRef={controllerRef}
diff --git a/frontend/src/components/GraphView.tsx b/frontend/src/components/GraphView.tsx
index c4c048e3..3147edf3 100644
--- a/frontend/src/components/GraphView.tsx
+++ b/frontend/src/components/GraphView.tsx
@@ -1,103 +1,193 @@
 import { forceCollide, type SimulationNodeDatum } from 'd3-force';
-import { ArrowLeft, Network, X } from 'lucide-react';
-import React, { useEffect, useMemo, useRef, useState } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { useTranslation } from 'react-i18next';
-import { useSelector } from 'react-redux';
-import ForceGraph2D, { type ForceGraphMethods } from 'react-force-graph-2d';
+import ForceGraph2D, {
+  type ForceGraphMethods,
+  type LinkObject,
+  type NodeObject,
+} from 'react-force-graph-2d';
 
-import userService from '../api/services/userService';
-import { selectToken } from '../preferences/preferenceSlice';
+import { useMediaQuery } from '../hooks';
 import { useThemeVersion } from '../utils/chartUtils';
-import { Badge } from './ui/badge';
-import { IconButton } from './ui/icon-button';
-import { SectionHeader } from './ui/section-header';
-import SkeletonLoader from './SkeletonLoader';
+import { formatCount } from '../utils/dateTimeUtils';
+import GraphCanvasControls from './graph/GraphCanvasControls';
+import GraphEntitySearch from './graph/GraphEntitySearch';
+import GraphNodePanel, {
+  GraphNodePanelDock,
+  type GraphNodeRef,
+} from './graph/GraphNodePanel';
+import { GraphSeriesDot } from './graph/GraphTypeDot';
 import {
-  ForceGraphData,
-  GraphNode,
-  GraphNodeDetail,
-  GraphOverview,
+  DIM_ALPHA,
+  OTHER_GROUP_KEY,
+  buildAdjacency,
+  endpointId,
+  focusSet,
+  legendGroupOf,
+  linkTouches,
+  nodeHasLabel,
+  pickLabels,
+  topHubIds,
+  type LabelBox,
+} from './graph/graphCanvasUtils';
+import { useGraphNodeDetail } from './graph/useGraphNodeDetail';
+import { Button } from './ui/button';
+import { Card } from './ui/card';
+import { EmptyState } from './ui/empty-state';
+import { LoadingState } from './ui/loading-state';
+import { Sheet, SheetContent } from './ui/sheet';
+import { ToggleGroup, ToggleGroupItem } from './ui/toggle-group';
+import {
+  type FoldedGraphTypes,
+  type ForceGraphData,
+  type GraphEdge,
+  type GraphNode,
   collideRadius,
+  escapeDeselects,
   maxDegree,
   nodeAtPoint,
   nodeRadius,
+  otherTypesList,
   readGraphPalette,
-  toForceGraphData,
 } from './graphViewUtils';
 
+/** The overview sizes the "Show top" control offers. */
+const GRAPH_LIMITS = [50, 100, 250] as const;
+
+export type GraphLoadStatus = 'loading' | 'error' | 'ready';
+
 interface GraphViewProps {
   docId: string;
-  sourceName: string;
-  onBackToDocuments: () => void;
-  /** Extra header control, right-aligned in the title row. */
-  headerAction?: React.ReactNode;
+  /** The loaded overview (top nodes by degree and the edges among them). */
+  data: ForceGraphData;
+  /** The one type fold shared with the header, the entity list and the panel. */
+  fold: FoldedGraphTypes;
+  status: GraphLoadStatus;
+  onRetry: () => void;
+  limit: number;
+  onLimitChange: (limit: number) => void;
+  selected: GraphNodeRef | null;
+  onSelect: (node: GraphNodeRef | null) => void;
+  /** False while another tab is showing; Escape then leaves the selection alone. */
+  active?: boolean;
+  /** Show a chunk's file on the Files tab (the chunk drawer's "Open in Files"). */
+  onOpenInFiles?: (path: string) => void;
 }
 
-const GRAPH_LIMIT = 100;
-const HIT_SLOP = 4;
+type PositionedNode = NodeObject<GraphNode> & { x?: number; y?: number };
 
+const HIT_SLOP = 4;
+const ZOOM_STEP = 1.3;
+const ZOOM_MS = 200;
+const FOCUS_MS = 400;
+const FOCUS_ZOOM = 2;
+const FIT_PADDING = 40;
+const LABEL_PX = 11;
+/** Screen-pixel clearance kept between two labels. */
+const LABEL_GAP_PX = 2;
+
+/**
+ * The Graph tab of a knowledge-graph source: entity search, the "Show top"
+ * size, the type legend (a filter), and the canvas with its controls and the
+ * docked node panel (a bottom sheet on a phone).
+ */
 const GraphView: React.FC<GraphViewProps> = ({
   docId,
-  sourceName,
-  onBackToDocuments,
-  headerAction,
+  data,
+  fold,
+  status,
+  onRetry,
+  limit,
+  onLimitChange,
+  selected,
+  onSelect,
+  active = true,
+  onOpenInFiles,
 }) => {
   const { t } = useTranslation();
-  const token = useSelector(selectToken);
-
-  const [data, setData] = useState<ForceGraphData>({ nodes: [], links: [] });
-  const [loading, setLoading] = useState(true);
-  const [selectedNode, setSelectedNode] = useState<GraphNodeDetail | null>(
-    null,
-  );
-  const [loadingNode, setLoadingNode] = useState(false);
+  const { isDesktop } = useMediaQuery();
+  const showTopId = useId();
 
   const containerRef = useRef<HTMLDivElement>(null);
-  const hoveredNodeIdRef = useRef<string | null>(null);
-  const fgRef = useRef<ForceGraphMethods | undefined>(undefined);
-  const [size, setSize] = useState({ width: 0, height: 480 });
+  const fgRef = useRef<ForceGraphMethods<GraphNode, GraphEdge> | undefined>(
+    undefined,
+  );
+  const hoveredIdRef = useRef<string | null>(null);
+  const fittedRef = useRef(false);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const [zoom, setZoom] = useState(1);
+  const [hidden, setHidden] = useState<Set<string>>(() => new Set());
+
   // The canvas can't read CSS variables: resolve the tokens, and re-read them
   // whenever the theme changes.
   const themeVersion = useThemeVersion();
   // themeVersion is not used inside the factory: it only signals a change.
   const palette = useMemo(() => readGraphPalette(), [themeVersion]);
+  const fadedLink = `color-mix(in srgb, ${palette.link} 15%, transparent)`;
 
-  useEffect(() => {
-    let cancelled = false;
-    setLoading(true);
-    userService
-      .getSourceGraph(docId, token, GRAPH_LIMIT)
-      .then((response) => response.json())
-      .then((body) => {
-        if (cancelled) return;
-        const overview: GraphOverview = {
-          nodes: body?.nodes ?? [],
-          edges: body?.edges ?? [],
-        };
-        setData(toForceGraphData(overview));
-      })
-      .catch((error) => console.error('Error loading graph:', error))
-      .finally(() => {
-        if (!cancelled) setLoading(false);
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [docId, token]);
-
-  useEffect(() => {
-    if (!containerRef.current) return;
-    const element = containerRef.current;
-    const observer = new ResizeObserver(() => {
-      setSize({ width: element.clientWidth, height: 480 });
-    });
-    observer.observe(element);
-    setSize({ width: element.clientWidth, height: 480 });
-    return () => observer.disconnect();
-  }, [loading, data.nodes.length]);
+  const selectedId = selected?.id ?? null;
+  const nodeDetail = useGraphNodeDetail(docId, selectedId);
 
   const maxNodeDegree = useMemo(() => maxDegree(data.nodes), [data.nodes]);
+  const nodeById = useMemo(
+    () => new Map(data.nodes.map((node) => [node.id, node])),
+    [data.nodes],
+  );
+  const loadedIds = useMemo(() => new Set(nodeById.keys()), [nodeById]);
+  const adjacency = useMemo(() => buildAdjacency(data.links), [data.links]);
+  const focus = useMemo(
+    () => focusSet(selectedId, adjacency, loadedIds),
+    [selectedId, adjacency, loadedIds],
+  );
 
+  const legendKeys = useMemo(
+    () => [
+      ...fold.groups.map((group) => group.key),
+      ...(fold.other.count > 0 ? [OTHER_GROUP_KEY] : []),
+    ],
+    [fold],
+  );
+
+  const isVisible = useCallback(
+    (node: GraphNode | undefined) =>
+      !!node && !hidden.has(legendGroupOf(fold, node.type)),
+    [fold, hidden],
+  );
+  const visibleNodes = useMemo(
+    () => data.nodes.filter((node) => isVisible(node)),
+    [data.nodes, isVisible],
+  );
+
+  // The busiest of what's shown keep their labels.
+  const hubs = useMemo(() => topHubIds(visibleNodes), [visibleNodes]);
+
+  // A new overview (another "Show top") starts with a fresh fit.
+  useEffect(() => {
+    fittedRef.current = false;
+  }, [data]);
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+    const measure = () => {
+      // A hidden tab measures 0: keep the last size so the canvas survives.
+      if (element.clientWidth === 0) return;
+      setSize({ width: element.clientWidth, height: element.clientHeight });
+    };
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    measure();
+    return () => observer.disconnect();
+  }, [status, data.nodes.length]);
+
+  const hasCanvas = size.width > 0;
   useEffect(() => {
     if (!fgRef.current || data.nodes.length === 0) return;
     fgRef.current.d3Force(
@@ -107,239 +197,480 @@ const GraphView: React.FC<GraphViewProps> = ({
       ),
     );
     fgRef.current.d3ReheatSimulation();
-  }, [data, maxNodeDegree, size.width]);
+  }, [data, maxNodeDegree, hasCanvas]);
 
-  const handleNodeClick = (node: GraphNode) => {
-    setLoadingNode(true);
-    setSelectedNode(null);
-    userService
-      .getSourceGraphNode(docId, node.id, token)
-      .then((response) => response.json())
-      .then((body) => {
-        if (body?.node) setSelectedNode(body.node as GraphNodeDetail);
-      })
-      .catch((error) => console.error('Error loading graph node:', error))
-      .finally(() => setLoadingNode(false));
-  };
+  // A settled simulation stops drawing, so paint changes once.
+  const repaint = useCallback(() => {
+    const fg = fgRef.current;
+    if (fg) fg.zoom(fg.zoom());
+  }, []);
+
+  useEffect(() => {
+    repaint();
+  }, [palette, focus, hidden, fold, repaint]);
+
+  const fitView = useCallback(
+    (durationMs = FOCUS_MS) => {
+      fgRef.current?.zoomToFit(durationMs, FIT_PADDING, (node) =>
+        isVisible(node as GraphNode),
+      );
+    },
+    [isVisible],
+  );
+
+  // Centre the selection; zoom in once per new selection. Re-centre when the
+  // docked panel changes the canvas width.
+  const zoomedForRef = useRef<string | null>(null);
+  const hadSelectionRef = useRef(false);
+  useEffect(() => {
+    const fg = fgRef.current;
+    if (!fg) return;
+    if (!selectedId) {
+      zoomedForRef.current = null;
+      if (!hadSelectionRef.current) return;
+      hadSelectionRef.current = false;
+      // Deselecting hands the width back to the canvas: refit.
+      const frame = requestAnimationFrame(() => fitView());
+      return () => cancelAnimationFrame(frame);
+    }
+    hadSelectionRef.current = true;
+    const node = nodeById.get(selectedId) as PositionedNode | undefined;
+    if (!node || node.x == null || node.y == null) return;
+    const { x, y } = node;
+    const frame = requestAnimationFrame(() => {
+      fg.centerAt(x, y, FOCUS_MS);
+      if (zoomedForRef.current !== selectedId) {
+        zoomedForRef.current = selectedId;
+        fg.zoom(Math.max(fg.zoom(), FOCUS_ZOOM), FOCUS_MS);
+      }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [selectedId, nodeById, size.width, fitView]);
+
+  useEffect(() => {
+    if (!active || !selectedId) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (escapeDeselects(event)) onSelect(null);
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [active, selectedId, onSelect]);
 
   // Geometric hit test, immune to canvas read-back farbling (e.g. Brave): map
-  // the pointer into graph coordinates and pick the nearest node directly.
+  // the pointer into graph coordinates and pick the nearest visible node.
   const pickNodeAt = (clientX: number, clientY: number): GraphNode | null => {
     const fg = fgRef.current;
     if (!fg || !containerRef.current) return null;
     const rect = containerRef.current.getBoundingClientRect();
     const g = fg.screen2GraphCoords(clientX - rect.left, clientY - rect.top);
-    return nodeAtPoint(data.nodes, g.x, g.y, maxNodeDegree, HIT_SLOP);
+    return nodeAtPoint(visibleNodes, g.x, g.y, maxNodeDegree, HIT_SLOP);
   };
 
-  const repaint = () => {
-    const fg = fgRef.current;
-    if (fg) fg.zoom(fg.zoom());
-  };
-
-  // A settled simulation stops drawing, so paint the new colours once.
-  useEffect(() => {
-    repaint();
-  }, [palette]);
+  const onCanvas = (event: React.MouseEvent) =>
+    event.target instanceof HTMLCanvasElement;
 
   const handlePointerMove = (event: React.MouseEvent<HTMLDivElement>) => {
-    const node = pickNodeAt(event.clientX, event.clientY);
+    const node = onCanvas(event)
+      ? pickNodeAt(event.clientX, event.clientY)
+      : null;
     if (containerRef.current) {
       containerRef.current.style.cursor = node ? 'pointer' : 'default';
     }
     const nextId = node?.id ?? null;
-    if (nextId !== hoveredNodeIdRef.current) {
-      hoveredNodeIdRef.current = nextId;
+    if (nextId !== hoveredIdRef.current) {
+      hoveredIdRef.current = nextId;
       repaint();
     }
   };
 
   const handlePointerLeave = () => {
     if (containerRef.current) containerRef.current.style.cursor = 'default';
-    if (hoveredNodeIdRef.current !== null) {
-      hoveredNodeIdRef.current = null;
+    if (hoveredIdRef.current !== null) {
+      hoveredIdRef.current = null;
       repaint();
     }
   };
 
   const handleContainerClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    // Clicks on the controls strip are not canvas clicks.
+    if (!onCanvas(event)) return;
     const node = pickNodeAt(event.clientX, event.clientY);
-    if (node) handleNodeClick(node);
+    if (node) onSelect({ id: node.id, name: node.name, type: node.type });
+    else if (selectedId) onSelect(null);
   };
 
-  const isEmpty = !loading && data.nodes.length === 0;
+  const nodeVisibility = useCallback(
+    (node: NodeObject<GraphNode>) => isVisible(node as GraphNode),
+    [isVisible],
+  );
+  const linkVisibility = useCallback(
+    (link: LinkObject<GraphNode, GraphEdge>) =>
+      isVisible(nodeById.get(endpointId(link.source as never))) &&
+      isVisible(nodeById.get(endpointId(link.target as never))),
+    [isVisible, nodeById],
+  );
+  const linkColor = useCallback(
+    (link: LinkObject<GraphNode, GraphEdge>) => {
+      if (!focus) return palette.link;
+      return linkTouches(link as GraphEdge, selectedId)
+        ? palette.primary
+        : fadedLink;
+    },
+    [focus, selectedId, palette, fadedLink],
+  );
+  const linkWidth = useCallback(
+    (link: LinkObject<GraphNode, GraphEdge>) =>
+      focus && linkTouches(link as GraphEdge, selectedId) ? 1.5 : 1,
+    [focus, selectedId],
+  );
+  const nodeVal = useCallback(
+    (node: NodeObject<GraphNode>) =>
+      nodeRadius((node as GraphNode).degree, maxNodeDegree),
+    [maxNodeDegree],
+  );
+
+  const nodeCanvasObject = useCallback(
+    (
+      node: NodeObject<GraphNode>,
+      ctx: CanvasRenderingContext2D,
+      globalScale: number,
+    ) => {
+      const graphNode = node as PositionedNode;
+      if (graphNode.x == null || graphNode.y == null) return;
+      const { x, y } = graphNode;
+      const r = nodeRadius(graphNode.degree, maxNodeDegree);
+      const hoveredId = hoveredIdRef.current;
+      const isSelected = graphNode.id === selectedId;
+      const series = fold.seriesOf(graphNode.type);
+
+      ctx.save();
+      ctx.globalAlpha = focus && !focus.has(graphNode.id) ? DIM_ALPHA : 1;
+      ctx.beginPath();
+      ctx.arc(x, y, r, 0, 2 * Math.PI);
+      ctx.fillStyle =
+        series == null
+          ? palette.other
+          : (palette.series[series] ?? palette.other);
+      ctx.fill();
+      if (isSelected || graphNode.id === hoveredId) {
+        ctx.lineWidth = (isSelected ? 2.5 : 1.5) / globalScale;
+        ctx.strokeStyle = palette.hoverStroke;
+        ctx.stroke();
+      }
+      ctx.restore();
+    },
+    [maxNodeDegree, selectedId, fold, focus, palette],
+  );
+
+  // Labels go on top of every node (a per-node label would sit under the
+  // nodes drawn after it): one pass after the frame. In priority order (the
+  // selection, the hovered node, then by degree) a label that would sit on
+  // one already placed is skipped; the first two always draw.
+  const drawLabels = useCallback(
+    (ctx: CanvasRenderingContext2D, globalScale: number) => {
+      const hoveredId = hoveredIdRef.current;
+      const rank = (node: GraphNode) =>
+        node.id === selectedId ? 0 : node.id === hoveredId ? 1 : 2;
+      const labelled = (visibleNodes as PositionedNode[])
+        .filter(
+          (node) =>
+            node.x != null &&
+            node.y != null &&
+            nodeHasLabel(node.id, { hubs, focus, hoveredId }),
+        )
+        .sort(
+          (a, b) =>
+            rank(a) - rank(b) ||
+            (b.degree || 0) - (a.degree || 0) ||
+            a.id.localeCompare(b.id),
+        );
+      ctx.save();
+      ctx.font = `${LABEL_PX / globalScale}px ${palette.font}`;
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'top';
+      ctx.lineWidth = 3 / globalScale;
+      ctx.lineJoin = 'round';
+      const boxes: (LabelBox & { label: string })[] = labelled.map((node) => {
+        const label = node.name ?? '';
+        return {
+          id: node.id,
+          label,
+          x: node.x as number,
+          y:
+            (node.y as number) +
+            nodeRadius(node.degree, maxNodeDegree) +
+            2 / globalScale,
+          width: ctx.measureText(label).width,
+          height: LABEL_PX / globalScale,
+          always: rank(node) < 2,
+        };
+      });
+      const shown = pickLabels(boxes, LABEL_GAP_PX / globalScale);
+      for (const box of boxes) {
+        if (!shown.has(box.id)) continue;
+        ctx.strokeStyle = palette.halo;
+        ctx.strokeText(box.label, box.x, box.y);
+        ctx.fillStyle = palette.label;
+        ctx.fillText(box.label, box.x, box.y);
+      }
+      ctx.restore();
+    },
+    [visibleNodes, hubs, focus, maxNodeDegree, palette, selectedId],
+  );
+
+  // Once a new layout settles: fit it, or, with a node selected, centre on
+  // that node (its position only exists now; the focus effect ran before).
+  const handleEngineStop = useCallback(() => {
+    if (fittedRef.current) return;
+    fittedRef.current = true;
+    const node = selectedId
+      ? (nodeById.get(selectedId) as PositionedNode | undefined)
+      : undefined;
+    if (node && node.x != null && node.y != null) {
+      fgRef.current?.centerAt(node.x, node.y, FOCUS_MS);
+    } else {
+      fitView();
+    }
+  }, [fitView, selectedId, nodeById]);
+
+  // The graph reports zoom while it renders (a prop update can move the
+  // view), so the readout follows on the next frame, at most once a frame.
+  const zoomFrameRef = useRef<number | null>(null);
+  const handleZoom = useCallback(({ k }: { k: number }) => {
+    if (zoomFrameRef.current !== null)
+      cancelAnimationFrame(zoomFrameRef.current);
+    zoomFrameRef.current = requestAnimationFrame(() => {
+      zoomFrameRef.current = null;
+      setZoom(k);
+    });
+  }, []);
+  useEffect(
+    () => () => {
+      if (zoomFrameRef.current !== null)
+        cancelAnimationFrame(zoomFrameRef.current);
+    },
+    [],
+  );
+
+  const zoomBy = (factor: number) => {
+    const fg = fgRef.current;
+    if (fg) fg.zoom(fg.zoom() * factor, ZOOM_MS);
+  };
+
+  const legendValue = legendKeys.filter((key) => !hidden.has(key));
+  const otherLabels = fold.other.labels;
+
+  const toolbar = (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-wrap items-center gap-3">
+        <GraphEntitySearch docId={docId} fold={fold} onPick={onSelect} />
+        {/* One phrase at one size: "Show top [50 | 100 | 250] by
+            connections"; the muted track holds only the group. */}
+        <div className="flex flex-wrap items-center gap-2">
+          <span id={showTopId} className="text-muted-foreground text-sm">
+            {t('settings.sources.graphrag.view.showTop')}
+          </span>
+          <div className="bg-muted shrink-0 rounded-full p-1">
+            <ToggleGroup
+              type="single"
+              size="xs"
+              className="flex-nowrap"
+              value={String(limit)}
+              onValueChange={(value) => value && onLimitChange(Number(value))}
+              aria-labelledby={showTopId}
+            >
+              {GRAPH_LIMITS.map((option) => (
+                <ToggleGroupItem key={option} value={String(option)}>
+                  {option}
+                </ToggleGroupItem>
+              ))}
+            </ToggleGroup>
+          </div>
+          <span className="text-muted-foreground text-sm">
+            {t('settings.sources.graphrag.view.byConnections')}
+          </span>
+        </div>
+      </div>
+      {legendKeys.length > 0 ? (
+        <div className="flex flex-wrap items-center gap-2">
+          <div className="bg-muted rounded-full p-1">
+            <ToggleGroup
+              type="multiple"
+              size="xs"
+              value={legendValue}
+              onValueChange={(values) =>
+                setHidden(
+                  new Set(legendKeys.filter((key) => !values.includes(key))),
+                )
+              }
+              aria-label={t('settings.sources.graphrag.view.typeFilter')}
+            >
+              {fold.groups.map((group) => (
+                <ToggleGroupItem key={group.key} value={group.key}>
+                  <GraphSeriesDot series={group.series} />
+                  {group.label}
+                  <span className="text-muted-foreground tabular-nums">
+                    {formatCount(group.count)}
+                  </span>
+                </ToggleGroupItem>
+              ))}
+              {fold.other.count > 0 ? (
+                <ToggleGroupItem value={OTHER_GROUP_KEY}>
+                  <GraphSeriesDot series={null} />
+                  {t('settings.analytics.otherSeries')}
+                  <span className="text-muted-foreground tabular-nums">
+                    {formatCount(fold.other.count)}
+                  </span>
+                </ToggleGroupItem>
+              ) : null}
+            </ToggleGroup>
+          </div>
+          {otherLabels.length > 0 ? (
+            <span className="text-muted-foreground text-xs">
+              {t('settings.sources.graphrag.view.otherTypes', {
+                types: otherTypesList(otherLabels, (count) =>
+                  t('settings.sources.graphrag.view.otherTypesMore', {
+                    count,
+                    formatted: formatCount(count),
+                  }),
+                ),
+                interpolation: { escapeValue: false },
+              })}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+
+  if (status === 'error') {
+    return (
+      <EmptyState
+        size="sm"
+        tone="destructive"
+        illustration="none"
+        title={t('settings.sources.graphrag.view.loadFailed')}
+        action={
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            shape="pill"
+            onClick={onRetry}
+          >
+            {t('retry')}
+          </Button>
+        }
+      />
+    );
+  }
+
+  if (status === 'ready' && data.nodes.length === 0) {
+    return (
+      <EmptyState
+        size="sm"
+        illustration="none"
+        title={t('settings.sources.graphrag.view.empty')}
+      />
+    );
+  }
+
+  const panel = selected ? (
+    <GraphNodePanel
+      key={selected.id}
+      docId={docId}
+      node={selected}
+      detail={nodeDetail.detail}
+      status={nodeDetail.status}
+      onRetry={nodeDetail.retry}
+      fold={fold}
+      onClose={() => onSelect(null)}
+      showClose={isDesktop}
+      onSelectNode={onSelect}
+      overview={data}
+      onOpenInFiles={onOpenInFiles}
+      onChunkSaved={nodeDetail.reload}
+    />
+  ) : null;
 
   return (
-    <div className="flex flex-col">
-      <div className="mb-4 flex items-center">
-        <IconButton
-          variant="outline"
-          size="icon-xs"
-          shape="pill"
-          className="mr-3"
-          onClick={onBackToDocuments}
-          label={t('settings.sources.backToAll')}
-          icon={ArrowLeft}
-          side="bottom"
-        />
-        <span className="text-primary font-semibold wrap-break-word">
-          {sourceName}
-        </span>
-        {headerAction ? <div className="ml-auto">{headerAction}</div> : null}
-      </div>
-
-      <div className="bg-muted text-muted-foreground mb-4 flex items-start gap-2 rounded-xl px-4 py-3 text-xs">
-        <Network className="mt-0.5 size-4 shrink-0" aria-hidden="true" />
-        <p>
-          <span className="text-foreground font-medium">
-            {t('settings.sources.graphrag.view.title')}
-          </span>{' '}
-          {t('settings.sources.graphrag.view.explainer')}
-        </p>
-      </div>
-
-      {loading ? (
-        <SkeletonLoader count={4} />
-      ) : isEmpty ? (
-        <div className="border-border text-muted-foreground flex flex-col items-center gap-2 rounded-xl border border-dashed px-6 py-12 text-center text-sm">
-          <Network className="size-7" aria-hidden="true" />
-          <p>{t('settings.sources.graphrag.view.empty')}</p>
-        </div>
-      ) : (
-        <div className="flex flex-col gap-2">
-          <p className="text-muted-foreground text-xs">
-            {t('settings.sources.graphrag.view.stats', {
-              nodes: data.nodes.length,
-              edges: data.links.length,
-            })}
-          </p>
-          <div className="flex flex-col gap-4 lg:flex-row lg:items-start">
-            <div
-              ref={containerRef}
-              onMouseMove={handlePointerMove}
-              onMouseLeave={handlePointerLeave}
-              onClick={handleContainerClick}
-              className="border-border bg-card relative min-h-[480px] flex-1 overflow-hidden rounded-xl border"
-            >
-              {size.width > 0 && (
-                <ForceGraph2D
+    <div className="flex flex-col gap-4">
+      {toolbar}
+      <Card
+        variant="subtle"
+        padding="none"
+        className="h-[70svh] flex-row gap-0 overflow-hidden"
+      >
+        <div
+          ref={containerRef}
+          onMouseMove={handlePointerMove}
+          onMouseLeave={handlePointerLeave}
+          onClick={handleContainerClick}
+          className="relative min-w-0 flex-1"
+        >
+          {status === 'loading' ? (
+            <LoadingState fill="parent" />
+          ) : (
+            <>
+              {hasCanvas && (
+                <ForceGraph2D<GraphNode, GraphEdge>
                   ref={fgRef}
                   graphData={data}
                   width={size.width}
                   height={size.height}
                   nodeRelSize={1}
+                  minZoom={0.2}
+                  maxZoom={8}
                   enablePointerInteraction={false}
                   enableNodeDrag={false}
-                  nodeVal={(node) =>
-                    nodeRadius((node as GraphNode).degree, maxNodeDegree)
-                  }
-                  linkColor={() => palette.link}
+                  nodeVal={nodeVal}
+                  nodeVisibility={nodeVisibility}
+                  linkVisibility={linkVisibility}
+                  linkColor={linkColor}
+                  linkWidth={linkWidth}
                   cooldownTicks={80}
-                  nodeCanvasObject={(node, ctx, globalScale) => {
-                    const graphNode = node as GraphNode & {
-                      x?: number;
-                      y?: number;
-                    };
-                    if (graphNode.x == null) return;
-                    const r = nodeRadius(graphNode.degree, maxNodeDegree);
-                    const hovered = hoveredNodeIdRef.current === graphNode.id;
-                    ctx.beginPath();
-                    ctx.arc(graphNode.x, graphNode.y ?? 0, r, 0, 2 * Math.PI);
-                    ctx.fillStyle = palette.node;
-                    ctx.fill();
-                    if (hovered) {
-                      ctx.lineWidth = 2 / globalScale;
-                      ctx.strokeStyle = palette.hoverStroke;
-                      ctx.stroke();
-                    }
-                    if (globalScale >= 1.2) {
-                      const label = graphNode.name ?? '';
-                      const x = graphNode.x;
-                      const y = (graphNode.y ?? 0) + r + 1;
-                      ctx.font = `${10 / globalScale}px sans-serif`;
-                      ctx.textAlign = 'center';
-                      ctx.textBaseline = 'top';
-                      ctx.lineWidth = 3 / globalScale;
-                      ctx.lineJoin = 'round';
-                      ctx.strokeStyle = palette.halo;
-                      ctx.strokeText(label, x, y);
-                      ctx.fillStyle = palette.label;
-                      ctx.fillText(label, x, y);
-                    }
-                  }}
+                  onEngineStop={handleEngineStop}
+                  onZoom={handleZoom}
+                  nodeCanvasObject={nodeCanvasObject}
+                  onRenderFramePost={drawLabels}
                 />
               )}
-            </div>
-
-            <aside className="border-border bg-card flex max-h-[480px] w-full shrink-0 flex-col overflow-y-auto rounded-xl border p-4 lg:w-80">
-              {loadingNode ? (
-                <SkeletonLoader count={3} />
-              ) : selectedNode ? (
-                <div className="flex flex-col">
-                  <div className="mb-2 flex items-start justify-between gap-2">
-                    <div className="min-w-0">
-                      <SectionHeader
-                        as="h3"
-                        size="xs"
-                        className="wrap-break-word"
-                        title={selectedNode.name}
-                      />
-                      {selectedNode.type && (
-                        <Badge variant="neutral" className="mt-1">
-                          {selectedNode.type}
-                        </Badge>
-                      )}
-                    </div>
-                    <IconButton
-                      variant="ghost-muted"
-                      size="icon-xs"
-                      className="shrink-0"
-                      onClick={() => setSelectedNode(null)}
-                      label={t('settings.sources.graphrag.view.close')}
-                      icon={X}
-                      side="bottom"
-                    />
-                  </div>
-
-                  {selectedNode.description && (
-                    <p className="text-muted-foreground mb-3 text-sm leading-relaxed wrap-break-word">
-                      {selectedNode.description}
-                    </p>
-                  )}
-
-                  <div className="flex flex-col gap-2">
-                    <SectionHeader
-                      as="h4"
-                      size="xs"
-                      title={t('settings.sources.graphrag.view.linkedChunks')}
-                    />
-                    {selectedNode.chunks.length === 0 ? (
-                      <p className="text-muted-foreground text-xs">
-                        {t('settings.sources.graphrag.view.noChunks')}
-                      </p>
-                    ) : (
-                      <ul className="flex flex-col gap-2">
-                        {selectedNode.chunks.map((chunk) => (
-                          <li
-                            key={chunk.chunk_id}
-                            className="border-border text-muted-foreground rounded-md border px-3 py-2 text-xs leading-relaxed wrap-break-word"
-                          >
-                            {chunk.text}
-                          </li>
-                        ))}
-                      </ul>
-                    )}
-                  </div>
-                </div>
-              ) : (
-                <p className="text-muted-foreground py-2 text-sm">
+              {!selected ? (
+                <p className="text-muted-foreground pointer-events-none absolute top-3 left-3 text-xs">
                   {t('settings.sources.graphrag.view.selectNode')}
                 </p>
-              )}
-            </aside>
-          </div>
+              ) : null}
+              <GraphCanvasControls
+                zoom={zoom}
+                onZoomIn={() => zoomBy(ZOOM_STEP)}
+                onZoomOut={() => zoomBy(1 / ZOOM_STEP)}
+                onFit={() => fitView()}
+              />
+            </>
+          )}
         </div>
-      )}
+        {isDesktop && panel ? (
+          <GraphNodePanelDock>{panel}</GraphNodePanelDock>
+        ) : null}
+      </Card>
+      {!isDesktop ? (
+        <Sheet
+          open={!!selected && active}
+          onOpenChange={(open) => {
+            if (!open) onSelect(null);
+          }}
+        >
+          <SheetContent
+            side="bottom"
+            handle
+            title={selected?.name}
+            // Open on the panel, not with a ring on its first control.
+            onOpenAutoFocus={(event) => event.preventDefault()}
+          >
+            {panel}
+          </SheetContent>
+        </Sheet>
+      ) : null}
     </div>
   );
 };
diff --git a/frontend/src/components/MarkdownPreview.tsx b/frontend/src/components/MarkdownPreview.tsx
index dcb595a2..1c050ff4 100644
--- a/frontend/src/components/MarkdownPreview.tsx
+++ b/frontend/src/components/MarkdownPreview.tsx
@@ -1,7 +1,7 @@
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 
-import { markdownHeadings } from '@/lib/markdown';
+import { markdownHeadings, markdownTables } from '@/lib/markdown';
 
 import { Button } from './ui/button';
 
@@ -18,6 +18,7 @@ export default function MarkdownPreview({ content }: { content: string }) {
           remarkPlugins={[remarkGfm]}
           components={{
             ...markdownHeadings,
+            ...markdownTables,
             a({ children, href }) {
               return (
                 <Button variant="link" size="inline" asChild>
diff --git a/frontend/src/components/MultiSelectPopover.tsx b/frontend/src/components/MultiSelectPopover.tsx
index d93ec1c4..61abbdda 100644
--- a/frontend/src/components/MultiSelectPopover.tsx
+++ b/frontend/src/components/MultiSelectPopover.tsx
@@ -124,7 +124,7 @@ export function MultiSelectPopover({
           if (!item.disabled) onToggle(item.id);
         }}
         checked={isSelected}
-        className="cursor-pointer justify-between"
+        className="justify-between"
         aria-selected={isSelected}
       >
         <div className="mr-3 flex grow items-center gap-3 overflow-hidden">
diff --git a/frontend/src/components/SourceMarkdown.test.tsx b/frontend/src/components/SourceMarkdown.test.tsx
new file mode 100644
index 00000000..c174d8b1
--- /dev/null
+++ b/frontend/src/components/SourceMarkdown.test.tsx
@@ -0,0 +1,55 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import SourceMarkdown from './SourceMarkdown';
+
+const render = (content: string, highlight?: string) =>
+  renderToStaticMarkup(
+    <SourceMarkdown content={content} highlight={highlight} />,
+  );
+
+describe('SourceMarkdown', () => {
+  it('renders headings, lists and tables like a chat answer', () => {
+    const html = render(
+      '# Title\n\n- one\n- two\n\n| A | B |\n|---|---|\n| 1 | 2 |',
+    );
+    expect(html).toContain('<h1 class="mt-4 mb-2 text-xl font-semibold">');
+    expect(html).toContain('list-outside list-disc pl-5');
+    expect(html).toContain('<table');
+    expect(html).toContain('overflow-x-auto');
+  });
+
+  it('marks every case-insensitive match of the highlight in text, not in code', () => {
+    const html = render(
+      'Nordhaven Logistics B.V. is a carrier; nordhaven logistics b.v. again. `Nordhaven Logistics B.V.`',
+      'Nordhaven Logistics B.V.',
+    );
+    expect(html.match(/<mark/g)).toHaveLength(2);
+    expect(html).toContain('>Nordhaven Logistics B.V.</mark>');
+    expect(html).toContain('>nordhaven logistics b.v.</mark>');
+    expect(html).toContain('<code');
+  });
+
+  it('treats the highlight as literal text, not a pattern', () => {
+    const html = render('Assured+ tier and Assured tier', 'Assured+');
+    expect(html.match(/<mark/g)).toHaveLength(1);
+  });
+
+  it('renders no marks without a highlight or for a blank one', () => {
+    expect(render('plain text')).not.toContain('<mark');
+    expect(render('plain text', '  ')).not.toContain('<mark');
+  });
+
+  it('puts fenced code in a scrolling box, and keeps the pill for inline code', () => {
+    const html = render(
+      'Run `npm ci` first.\n\n```sh\nnpm ci\nnpm run build\n```',
+    );
+    const host = document.createElement('div');
+    host.innerHTML = html;
+    const pre = host.querySelector('pre')!;
+    expect(pre.className).toContain('overflow-x-auto');
+    expect(pre.className).toContain('border');
+    expect(pre.textContent).toContain('npm run build');
+    expect(host.querySelector('p code')!.className).toContain('bg-muted');
+  });
+});
diff --git a/frontend/src/components/SourceMarkdown.tsx b/frontend/src/components/SourceMarkdown.tsx
new file mode 100644
index 00000000..090a91d1
--- /dev/null
+++ b/frontend/src/components/SourceMarkdown.tsx
@@ -0,0 +1,128 @@
+import React from 'react';
+import ReactMarkdown, {
+  type Components,
+  type ExtraProps,
+} from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+import { markdownHeadings, markdownTables } from '@/lib/markdown';
+
+import { Button } from './ui/button';
+
+type TableProps = React.ComponentProps<'table'> & ExtraProps;
+
+// The shared table frame, with the paragraph's bottom margin so the next
+// block does not butt against it.
+const SharedTable = markdownTables.table as React.ComponentType<TableProps>;
+const TableFrame = (props: TableProps) => (
+  <div className="mb-3">
+    <SharedTable {...props} />
+  </div>
+);
+
+const components: Components = {
+  ...markdownHeadings,
+  ...markdownTables,
+  table: TableFrame,
+  p: ({ children }) => <p className="mb-3">{children}</p>,
+  ul: ({ children }) => (
+    <ul className="mb-3 list-outside list-disc pl-5">{children}</ul>
+  ),
+  ol: ({ children }) => (
+    <ol className="mb-3 list-outside list-decimal pl-5">{children}</ol>
+  ),
+  a: ({ children, href }) => (
+    <Button variant="link" size="inline" asChild>
+      <a href={href} target="_blank" rel="noreferrer">
+        {children}
+      </a>
+    </Button>
+  ),
+  // Fenced and indented code keep their lines and scroll sideways in a
+  // bordered box; the inline pill below applies to inline code only.
+  pre: ({ children }) => (
+    <pre className="border-border mb-3 overflow-x-auto rounded-md border p-3 font-mono text-xs leading-5 [&>code]:bg-transparent [&>code]:p-0">
+      {children}
+    </pre>
+  ),
+  code: ({ children }) => (
+    <code className="bg-muted rounded-sm px-1 py-0.5 font-mono text-xs">
+      {children}
+    </code>
+  ),
+  mark: ({ children }) => (
+    <mark className="bg-secondary text-foreground rounded-xs px-0.5">
+      {children}
+    </mark>
+  ),
+};
+
+type MdNode = {
+  type: string;
+  value?: string;
+  children?: MdNode[];
+  data?: { hName?: string };
+};
+
+/**
+ * A remark plugin that wraps every case-insensitive, literal match of `term`
+ * in text (never in code) in a `<mark>`.
+ */
+function remarkHighlight(term: string) {
+  const needle = term.toLowerCase();
+  const split = (value: string): MdNode[] => {
+    const out: MdNode[] = [];
+    const lower = value.toLowerCase();
+    let from = 0;
+    let at = lower.indexOf(needle);
+    while (at !== -1) {
+      if (at > from) out.push({ type: 'text', value: value.slice(from, at) });
+      const hit = value.slice(at, at + needle.length);
+      out.push({
+        type: 'highlight',
+        data: { hName: 'mark' },
+        children: [{ type: 'text', value: hit }],
+      });
+      from = at + needle.length;
+      at = lower.indexOf(needle, from);
+    }
+    if (from < value.length)
+      out.push({ type: 'text', value: value.slice(from) });
+    return out;
+  };
+  const walk = (node: MdNode) => {
+    if (!node.children) return;
+    node.children = node.children.flatMap((child) => {
+      if (child.type === 'text' && child.value) return split(child.value);
+      walk(child);
+      return [child];
+    });
+  };
+  return () => (tree: MdNode) => walk(tree);
+}
+
+/**
+ * Markdown as a source view renders it: a wiki page, an open chunk, the edit
+ * drawer's preview. The chat answer's headings and tables, lists outside the
+ * text, links as `link inline`. `highlight` marks an entity's name (the graph's
+ * chunk drawer).
+ */
+export default function SourceMarkdown({
+  content,
+  highlight,
+}: {
+  content: string;
+  highlight?: string;
+}) {
+  const term = highlight?.trim();
+  return (
+    <div className="text-foreground text-sm leading-relaxed wrap-break-word">
+      <ReactMarkdown
+        remarkPlugins={term ? [remarkGfm, remarkHighlight(term)] : [remarkGfm]}
+        components={components}
+      >
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+}
diff --git a/frontend/src/components/WikiViewer.test.tsx b/frontend/src/components/WikiViewer.test.tsx
new file mode 100644
index 00000000..76c6d442
--- /dev/null
+++ b/frontend/src/components/WikiViewer.test.tsx
@@ -0,0 +1,407 @@
+import { act, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts && key === 'settings.sources.wiki.byline'
+        ? `${opts.pages} pages · ${opts.tokens} tokens`
+        : key,
+  }),
+}));
+
+const auth = vi.hoisted(() => ({ token: null as string | null }));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => auth.token,
+  useDispatch: () => vi.fn(),
+}));
+
+vi.mock('../hooks', () => ({
+  useDarkTheme: () => [false],
+  useDebouncedValue: (value: unknown) => value,
+  useLoaderState: (initial: boolean) => useState(initial),
+  useMediaQuery: () => ({ isMobile: false, isDesktop: true }),
+  useOutsideAlerter: () => undefined,
+}));
+
+const PAGES = [
+  { path: 'company/meeting-types.md', title: null, token_count: 1000 },
+  { path: 'index.md', title: null, token_count: 200 },
+  { path: 'company/async_by-default.md', title: null, token_count: 34 },
+];
+
+const ok = (body: unknown) => ({
+  ok: true,
+  status: 200,
+  json: async () => body,
+});
+
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getWikiPages: vi.fn(),
+    getWikiPage: vi.fn(),
+    updateWikiPage: vi.fn(),
+  },
+}));
+
+import i18next from 'i18next';
+
+import userService from '../api/services/userService';
+import { TooltipProvider } from './ui/tooltip';
+import WikiViewer from './WikiViewer';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const service = userService as unknown as {
+  getWikiPages: ReturnType<typeof vi.fn>;
+  getWikiPage: ReturnType<typeof vi.fn>;
+  updateWikiPage: ReturnType<typeof vi.fn>;
+};
+
+describe('WikiViewer', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    auth.token = null;
+    service.getWikiPages.mockReset();
+    service.getWikiPage.mockReset();
+    service.updateWikiPage.mockReset();
+    service.getWikiPages.mockResolvedValue(ok({ pages: PAGES }));
+    service.getWikiPage.mockImplementation(async (_id: string, path: string) =>
+      ok({ page: { path, content: '# Hello\n\nBody text', version: 1 } }),
+    );
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = async (canEdit = false) => {
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <WikiViewer
+            docId="doc"
+            sourceName="Handbook"
+            canEdit={canEdit}
+            onBackToDocuments={vi.fn()}
+          />
+        </TooltipProvider>,
+      );
+    });
+  };
+
+  const buttonByText = (text: string) =>
+    Array.from(document.body.querySelectorAll('button')).find(
+      (b) => b.textContent?.trim() === text,
+    );
+
+  const sheet = () =>
+    document.body.querySelector<HTMLElement>('[data-slot="sheet-content"]');
+
+  const editor = () =>
+    sheet()?.querySelector<HTMLTextAreaElement>('textarea') ?? null;
+
+  const typeDraft = async (value: string) => {
+    const field = editor()!;
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLTextAreaElement.prototype,
+      'value',
+    )!.set!;
+    await act(async () => {
+      setter.call(field, value);
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+  };
+
+  const openEditor = async () => {
+    await act(async () => buttonByText('settings.sources.wiki.edit')!.click());
+  };
+
+  const save = async () => {
+    await act(async () => buttonByText('settings.sources.wiki.save')!.click());
+  };
+
+  // Bugs row 8: the app language's separators, not the browser's.
+  it('formats the byline counts in the app language', async () => {
+    const language = i18next.language;
+    i18next.language = 'de';
+    try {
+      await render();
+      expect(container.textContent).toContain('3 pages · 1.234 tokens');
+    } finally {
+      i18next.language = language;
+    }
+  });
+
+  it('renders the living wiki badge and the page and token counts', async () => {
+    await render();
+    const text = container.textContent ?? '';
+    expect(text).toContain('Handbook');
+    expect(text).toContain('settings.sources.wiki.badge');
+    expect(text).toContain(
+      `3 pages · ${(1234).toLocaleString()} tokens · settings.sources.wiki.explainer`,
+    );
+    expect(text).not.toContain('settings.sources.wiki.livingTitle');
+  });
+
+  it('uses the editable explainer when the wiki can be edited', async () => {
+    await render(true);
+    expect(container.textContent).toContain(
+      'settings.sources.wiki.explainerEditable',
+    );
+  });
+
+  it('groups pages under their folder with readable labels', async () => {
+    await render();
+    const nav = container.querySelector(
+      'nav[aria-label="settings.sources.wiki.pagesTitle"]',
+    )!;
+    const text = nav.textContent ?? '';
+    expect(text).toContain('settings.sources.wiki.home');
+    expect(text).toContain('company');
+    expect(text).toContain('Meeting types');
+    expect(text).toContain('Async by default');
+    // The home page leads, before the folder group.
+    expect(text.indexOf('settings.sources.wiki.home')).toBeLessThan(
+      text.indexOf('company'),
+    );
+    // The first page in the list opens, its path in the reader meta.
+    expect(service.getWikiPage).toHaveBeenCalledWith(
+      'doc',
+      'company/meeting-types.md',
+      null,
+    );
+    expect(container.textContent).toContain('Body text');
+  });
+
+  it('hides Edit without canEdit', async () => {
+    await render(false);
+    expect(buttonByText('settings.sources.wiki.edit')).toBeUndefined();
+    expect(sheet()).toBeNull();
+  });
+
+  // The chunk reader's actions: Edit, then the toolbar ⋯ with Copy text. A
+  // viewer who can't edit still gets the menu.
+  it('puts a toolbar ⋯ menu after Edit, for editors and viewers alike', async () => {
+    const menu = () =>
+      container.querySelector<HTMLButtonElement>(
+        'button[aria-label="settings.sources.menuAlt"]',
+      );
+    await render(true);
+    const edit = buttonByText('settings.sources.wiki.edit')!;
+    expect(menu()).not.toBeNull();
+    expect(
+      edit.compareDocumentPosition(menu()!) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+
+    await render(false);
+    expect(menu()).not.toBeNull();
+  });
+
+  it('renders the page body as markdown through SourceMarkdown, tables included', async () => {
+    service.getWikiPage.mockImplementation(async (_id: string, path: string) =>
+      ok({
+        page: {
+          path,
+          content: '# Hello\n\n| Name | Role |\n| --- | --- |\n| Ana | Lead |',
+          version: 1,
+        },
+      }),
+    );
+    await render();
+    const table = container.querySelector('table');
+    expect(table).not.toBeNull();
+    expect(table?.textContent).toContain('Ana');
+    expect(container.querySelector('h1, h2, h3')?.textContent).toBe('Hello');
+    expect(container.querySelector('textarea')).toBeNull();
+  });
+
+  it('opens the edit drawer with the page content as the draft', async () => {
+    await render(true);
+    expect(sheet()).toBeNull();
+    await openEditor();
+    expect(sheet()).not.toBeNull();
+    expect(sheet()!.textContent).toContain('settings.sources.wiki.editTitle');
+    expect(sheet()!.textContent).toContain('company/meeting-types.md');
+    expect(editor()?.value).toBe('# Hello\n\nBody text');
+    // The path is the drawer's description; the field is named by a label.
+    expect(editor()?.getAttribute('aria-label')).toBe('modals.chunk.bodyText');
+    // The panel itself never swaps to an editor.
+    expect(container.querySelector('textarea')).toBeNull();
+  });
+
+  it('closes the drawer and shows the new content when the save succeeds', async () => {
+    service.updateWikiPage.mockResolvedValue(
+      ok({
+        page: {
+          path: 'company/meeting-types.md',
+          content: '# Hello\n\nNew body',
+          version: 2,
+        },
+      }),
+    );
+    await render(true);
+    await openEditor();
+    await typeDraft('# Hello\n\nNew body');
+    await save();
+    expect(service.updateWikiPage).toHaveBeenCalled();
+    expect(sheet()).toBeNull();
+    expect(container.textContent).toContain('New body');
+    expect(container.textContent).not.toContain('Body text');
+  });
+
+  it('a token refresh keeps the open drawer and its draft', async () => {
+    auth.token = 'old';
+    await render(true);
+    await openEditor();
+    await typeDraft('# Hello\n\nHalf-written');
+    service.getWikiPages.mockClear();
+    service.getWikiPage.mockClear();
+    // SSE 401 recovery dispatches a fresh token for the same user.
+    auth.token = 'new';
+    await render(true);
+    expect(sheet()).not.toBeNull();
+    expect(editor()?.value).toBe('# Hello\n\nHalf-written');
+    expect(service.getWikiPage).not.toHaveBeenCalled();
+    expect(service.getWikiPages).not.toHaveBeenCalled();
+    // Later requests carry the fresh token.
+    service.updateWikiPage.mockResolvedValue(ok({ page: null }));
+    await save();
+    expect(service.updateWikiPage.mock.calls[0]).toContain('new');
+  });
+
+  it('a saved page updates the byline token total', async () => {
+    service.updateWikiPage.mockResolvedValue(
+      ok({
+        page: {
+          path: 'company/meeting-types.md',
+          content: '# Hello\n\nLonger body',
+          token_count: 1500,
+          version: 2,
+        },
+      }),
+    );
+    await render(true);
+    await openEditor();
+    await typeDraft('# Hello\n\nLonger body');
+    await save();
+    expect(container.textContent).toContain(
+      `3 pages · ${(1734).toLocaleString()} tokens`,
+    );
+  });
+
+  it('keeps the drawer open with a warning and the draft when the save conflicts', async () => {
+    service.updateWikiPage.mockResolvedValue({
+      ok: false,
+      status: 409,
+      json: async () => ({}),
+    });
+    await render(true);
+    await openEditor();
+    await typeDraft('My edit');
+    await save();
+    expect(sheet()).not.toBeNull();
+    const alert = sheet()!.querySelector('[data-slot="alert"]');
+    expect(alert?.getAttribute('data-variant')).toBe('warning');
+    expect(alert?.textContent).toContain('settings.sources.wiki.conflict');
+    expect(editor()?.value).toBe('My edit');
+  });
+
+  it('shows a destructive Alert in the drawer when the save is forbidden', async () => {
+    service.updateWikiPage.mockResolvedValue({
+      ok: false,
+      status: 403,
+      json: async () => ({}),
+    });
+    await render(true);
+    await openEditor();
+    await typeDraft('My edit');
+    await save();
+    expect(sheet()).not.toBeNull();
+    const alert = sheet()!.querySelector('[data-slot="alert"]');
+    expect(alert?.getAttribute('data-variant')).toBe('destructive');
+    expect(alert?.textContent).toContain('settings.sources.wiki.forbidden');
+    expect(editor()?.value).toBe('My edit');
+  });
+
+  // DESIGN.md: the navigator shows only when there is more than one thing to
+  // open; a one-page wiki reads full width, like a one-file source.
+  it('hides the navigator for a one-page wiki and opens that page', async () => {
+    service.getWikiPages.mockResolvedValue(
+      ok({ pages: [{ path: 'index.md', title: null, token_count: 5 }] }),
+    );
+    await render();
+    expect(
+      container.querySelector(
+        'nav[aria-label="settings.sources.wiki.pagesTitle"]',
+      ),
+    ).toBeNull();
+    expect(service.getWikiPage).toHaveBeenCalledWith('doc', 'index.md', null);
+    expect(container.textContent).toContain('index.md');
+    expect(container.textContent).toContain('Body text');
+  });
+
+  it('shows the empty state when the wiki has no pages', async () => {
+    service.getWikiPages.mockResolvedValue(ok({ pages: [] }));
+    await render();
+    expect(container.textContent).toContain('settings.sources.wiki.empty');
+    expect(
+      container.querySelector(
+        'nav[aria-label="settings.sources.wiki.pagesTitle"]',
+      ),
+    ).toBeNull();
+  });
+
+  it('offers Retry when the pages fail to load', async () => {
+    service.getWikiPages.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      json: async () => ({}),
+    });
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await render();
+    expect(container.textContent).toContain('settings.sources.wiki.loadFailed');
+    await act(async () => buttonByText('retry')!.click());
+    expect(service.getWikiPages).toHaveBeenCalledTimes(2);
+    expect(
+      container.querySelector(
+        'nav[aria-label="settings.sources.wiki.pagesTitle"]',
+      ),
+    ).not.toBeNull();
+    spy.mockRestore();
+  });
+
+  // Bug: a failed page switch kept the previous page's "Edited by · vN".
+  it("drops the previous page's stamp when the next page fails to load", async () => {
+    service.getWikiPage.mockImplementation(async (_id: string, path: string) =>
+      path === 'index.md'
+        ? { ok: false, status: 500, json: async () => ({}) }
+        : ok({ page: { path, content: 'Body text', version: 3 } }),
+    );
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await render();
+    expect(container.textContent).toContain(
+      'settings.sources.wiki.stamp.editedBy',
+    );
+    const home = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="command-item"]'),
+    ).find((el) => el.textContent?.includes('settings.sources.wiki.home'))!;
+    await act(async () => home.click());
+    expect(container.textContent).toContain(
+      'settings.sources.wiki.pageLoadFailed',
+    );
+    expect(container.textContent).not.toContain(
+      'settings.sources.wiki.stamp.editedBy',
+    );
+    expect(container.textContent).not.toContain('Body text');
+    spy.mockRestore();
+  });
+});
diff --git a/frontend/src/components/WikiViewer.tsx b/frontend/src/components/WikiViewer.tsx
index 47942cb7..6424e4bb 100644
--- a/frontend/src/components/WikiViewer.tsx
+++ b/frontend/src/components/WikiViewer.tsx
@@ -1,22 +1,37 @@
-import { ArrowLeft, BookOpen } from 'lucide-react';
-import React, { useEffect, useState } from 'react';
+import copy from 'copy-to-clipboard';
+import {
+  BookOpen,
+  CircleAlert,
+  Copy,
+  FileText,
+  Pencil,
+  TriangleAlert,
+} from 'lucide-react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { useSelector } from 'react-redux';
-import ReactMarkdown from 'react-markdown';
-import remarkGfm from 'remark-gfm';
-
-import { markdownHeadings } from '@/lib/markdown';
-import { cn } from '@/lib/utils';
-
+import { useDispatch, useSelector } from 'react-redux';
 import userService from '../api/services/userService';
+import { showActionToast } from '../notifications/actionToastSlice';
 import { selectToken } from '../preferences/preferenceSlice';
-import { formatRelative } from '../utils/dateTimeUtils';
+import { formatCount, formatRelative } from '../utils/dateTimeUtils';
 import { decodeJwtPayload } from '../utils/jwtUtils';
+import SourceMarkdown from './SourceMarkdown';
+import PathHeader from './tree/PathHeader';
+import ReaderPanel from './tree/ReaderPanel';
+import SourceEditSheet from './tree/SourceEditSheet';
+import SourceNavigator from './tree/SourceNavigator';
+import { Alert, AlertDescription } from './ui/alert';
+import { Badge } from './ui/badge';
 import { Button } from './ui/button';
-import { IconButton } from './ui/icon-button';
-import { Textarea } from './ui/textarea';
-import SkeletonLoader from './SkeletonLoader';
-import { WikiPageNode, provenanceKey, saveWikiPage } from './wikiViewerUtils';
+import { ActionMenu } from './ui/dropdown-menu';
+import { EmptyState } from './ui/empty-state';
+import { Skeleton } from './ui/skeleton';
+import {
+  WikiPageNode,
+  buildWikiNavigator,
+  provenanceKey,
+  saveWikiPage,
+} from './wikiViewerUtils';
 
 interface WikiViewerProps {
   docId: string;
@@ -27,30 +42,19 @@ interface WikiViewerProps {
   headerAction?: React.ReactNode;
 }
 
-const markdownComponents = {
-  ...markdownHeadings,
-  p: ({ children }: { children?: React.ReactNode }) => (
-    <p className="mb-3">{children}</p>
-  ),
-  ul: ({ children }: { children?: React.ReactNode }) => (
-    <ul className="mb-3 list-inside list-disc pl-4">{children}</ul>
-  ),
-  ol: ({ children }: { children?: React.ReactNode }) => (
-    <ol className="mb-3 list-inside list-decimal pl-4">{children}</ol>
-  ),
-  a: ({ children, href }: { children?: React.ReactNode; href?: string }) => (
-    <Button variant="link" size="inline" asChild>
-      <a href={href} target="_blank" rel="noreferrer">
-        {children}
-      </a>
-    </Button>
-  ),
-  code: ({ children }: { children?: React.ReactNode }) => (
-    <code className="bg-accent rounded-md px-1.5 py-0.5 text-xs">
-      {children}
-    </code>
-  ),
-};
+type EditError = { kind: 'conflict' | 'forbidden' | 'failed' } | null;
+
+/** Bars in the reader body while a page loads. */
+function ReaderBars() {
+  return (
+    <div className="flex flex-col gap-3" data-testid="wiki-reader-loading">
+      <Skeleton className="h-6 w-1/3" />
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-11/12" />
+      <Skeleton className="h-4 w-4/5" />
+    </div>
+  );
+}
 
 const WikiViewer: React.FC<WikiViewerProps> = ({
   docId,
@@ -60,6 +64,7 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
   headerAction,
 }) => {
   const { t } = useTranslation();
+  const dispatch = useDispatch();
   const token = useSelector(selectToken);
   const currentUserSub = token
     ? ((decodeJwtPayload(token)?.sub as string | undefined) ?? null)
@@ -70,70 +75,108 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
   const [page, setPage] = useState<WikiPageNode | null>(null);
   const [content, setContent] = useState<string>('');
   const [loadingPages, setLoadingPages] = useState(true);
+  const [pagesFailed, setPagesFailed] = useState(false);
+  const [pagesAttempt, setPagesAttempt] = useState(0);
   const [loadingContent, setLoadingContent] = useState(false);
+  const [contentFailed, setContentFailed] = useState(false);
+  const [contentAttempt, setContentAttempt] = useState(0);
 
-  const [isEditing, setIsEditing] = useState(false);
+  const [editorOpen, setEditorOpen] = useState(false);
   const [draft, setDraft] = useState<string>('');
   const [saving, setSaving] = useState(false);
-  const [editError, setEditError] = useState<string | null>(null);
+  const [editError, setEditError] = useState<EditError>(null);
+
+  // The loads read the token through a ref: a refresh (setToken during SSE
+  // 401 recovery) is the same user, so it must not refetch, and above all not
+  // reset the page and close an open editor with its draft.
+  const tokenRef = useRef(token);
+  tokenRef.current = token;
 
   useEffect(() => {
     let cancelled = false;
     setLoadingPages(true);
+    setPagesFailed(false);
     userService
-      .getWikiPages(docId, token)
-      .then((response) => response.json())
+      .getWikiPages(docId, tokenRef.current)
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
       .then((data) => {
         if (cancelled) return;
         const list: WikiPageNode[] = data?.pages ?? [];
         setPages(list);
-        if (list.length > 0) setSelectedPath(list[0].path);
+        setSelectedPath((prev) =>
+          prev && list.some((p) => p.path === prev)
+            ? prev
+            : (list[0]?.path ?? null),
+        );
+      })
+      .catch((error) => {
+        console.error('Error loading wiki pages:', error);
+        if (!cancelled) setPagesFailed(true);
       })
-      .catch((error) => console.error('Error loading wiki pages:', error))
       .finally(() => {
         if (!cancelled) setLoadingPages(false);
       });
     return () => {
       cancelled = true;
     };
-  }, [docId, token]);
+  }, [docId, pagesAttempt]);
 
   useEffect(() => {
-    setIsEditing(false);
+    setEditorOpen(false);
     setEditError(null);
-    if (!selectedPath) {
-      setPage(null);
-      setContent('');
-      return;
-    }
+    setContentFailed(false);
+    // Drop the last page before the next loads, so a failed load never shows
+    // its stamp (editor, version) or its text under the new path.
+    setPage(null);
+    setContent('');
+    if (!selectedPath) return;
     let cancelled = false;
     setLoadingContent(true);
     userService
-      .getWikiPage(docId, selectedPath, token)
-      .then((response) => response.json())
+      .getWikiPage(docId, selectedPath, tokenRef.current)
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
       .then((data) => {
         if (cancelled) return;
         const node: WikiPageNode | null = data?.page ?? null;
         setPage(node);
         setContent((data?.page?.content as string) ?? '');
       })
-      .catch((error) => console.error('Error loading wiki page:', error))
+      .catch((error) => {
+        console.error('Error loading wiki page:', error);
+        if (!cancelled) setContentFailed(true);
+      })
       .finally(() => {
         if (!cancelled) setLoadingContent(false);
       });
     return () => {
       cancelled = true;
     };
-  }, [docId, selectedPath, token]);
+  }, [docId, selectedPath, contentAttempt]);
+
+  const homeLabel = t('settings.sources.wiki.home');
+  const navigatorNodes = useMemo(
+    () => buildWikiNavigator(pages, homeLabel),
+    [pages, homeLabel],
+  );
+  const totalTokens = useMemo(
+    () => pages.reduce((sum, p) => sum + (p.token_count ?? 0), 0),
+    [pages],
+  );
 
   const startEditing = () => {
     setDraft(content);
     setEditError(null);
-    setIsEditing(true);
+    setEditorOpen(true);
   };
 
-  const cancelEditing = () => {
-    setIsEditing(false);
+  const closeEditor = () => {
+    setEditorOpen(false);
     setEditError(null);
   };
 
@@ -152,26 +195,38 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
       );
       switch (outcome.status) {
         case 'saved':
-          if (outcome.page) setPage(outcome.page);
+          if (outcome.page) {
+            const saved = outcome.page;
+            setPage(saved);
+            // The list feeds the byline's token total and the navigator's
+            // labels; keep its entry in step (the list carries no content).
+            setPages((list) =>
+              list.map((p) =>
+                p.path === selectedPath
+                  ? { ...p, ...saved, content: p.content }
+                  : p,
+              ),
+            );
+          }
           setContent(draft);
-          setIsEditing(false);
+          setEditorOpen(false);
           break;
         case 'conflict':
           if (outcome.page) {
             setPage(outcome.page);
             setContent(outcome.page.content ?? '');
           }
-          setEditError(t('settings.sources.wiki.conflict'));
+          setEditError({ kind: 'conflict' });
           break;
         case 'forbidden':
-          setEditError(t('settings.sources.wiki.forbidden'));
+          setEditError({ kind: 'forbidden' });
           break;
         default:
-          setEditError(t('settings.sources.wiki.saveFailed'));
+          setEditError({ kind: 'failed' });
       }
     } catch (error) {
       console.error('Error saving wiki page:', error);
-      setEditError(t('settings.sources.wiki.saveFailed'));
+      setEditError({ kind: 'failed' });
     } finally {
       setSaving(false);
     }
@@ -180,7 +235,7 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
   const provenanceLabel = (via?: string | null, by?: string | null): string =>
     t(`settings.sources.wiki.stamp.${provenanceKey(via, by, currentUserSub)}`);
 
-  const renderStamp = () => {
+  const stamp = (): string | null => {
     if (!page) return null;
     const who = provenanceLabel(page.updated_via, page.updated_by);
     const when = formatRelative(page.updated_at);
@@ -191,150 +246,243 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
         t('settings.sources.wiki.stamp.version', { version: page.version }),
       );
     }
+    return parts.join(' · ');
+  };
+
+  const explainer = canEdit
+    ? t('settings.sources.wiki.explainerEditable')
+    : t('settings.sources.wiki.explainer');
+  const byline = loadingPages
+    ? explainer
+    : `${t('settings.sources.wiki.byline', {
+        count: pages.length,
+        pages: formatCount(pages.length),
+        tokens: formatCount(totalTokens),
+      })} · ${explainer}`;
+
+  const renderEditError = () => {
+    if (!editError) return null;
+    if (editError.kind === 'conflict') {
+      return (
+        <Alert variant="warning">
+          <TriangleAlert />
+          <AlertDescription>
+            {t('settings.sources.wiki.conflict')}
+          </AlertDescription>
+        </Alert>
+      );
+    }
     return (
-      <p className="text-muted-foreground mb-3 text-xs">{parts.join(' · ')}</p>
+      <Alert variant="destructive">
+        <CircleAlert />
+        <AlertDescription>
+          {editError.kind === 'forbidden'
+            ? t('settings.sources.wiki.forbidden')
+            : t('settings.sources.wiki.saveFailed')}
+        </AlertDescription>
+      </Alert>
+    );
+  };
+
+  // The chunk reader's actions: Edit (editors only), then the toolbar ⋯.
+  const readerActions =
+    loadingContent || contentFailed ? null : (
+      <>
+        {canEdit ? (
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            shape="pill"
+            onClick={startEditing}
+          >
+            <Pencil />
+            {t('settings.sources.wiki.edit')}
+          </Button>
+        ) : null}
+        <ActionMenu
+          size="toolbar"
+          triggerLabel={t('settings.sources.menuAlt')}
+          options={[
+            {
+              icon: Copy,
+              label: t('settings.sources.copyText'),
+              onClick: () => {
+                copy(content);
+                dispatch(
+                  showActionToast({
+                    variant: 'success',
+                    message: t('conversation.copied'),
+                  }),
+                );
+              },
+            },
+          ]}
+        />
+      </>
+    );
+
+  const readerMeta = selectedPath ? (
+    <>
+      <span className="font-mono wrap-anywhere">{selectedPath}</span>
+      {!loadingContent && !contentFailed && stamp() ? (
+        <span>{stamp()}</span>
+      ) : null}
+    </>
+  ) : null;
+
+  const readerBody = () => {
+    if (loadingContent) return <ReaderBars />;
+    if (contentFailed) {
+      return (
+        <EmptyState
+          size="xs"
+          tone="destructive"
+          illustration="none"
+          title={t('settings.sources.wiki.pageLoadFailed')}
+          action={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={() => setContentAttempt((n) => n + 1)}
+            >
+              {t('retry')}
+            </Button>
+          }
+        />
+      );
+    }
+    return <SourceMarkdown content={content} />;
+  };
+
+  const renderBody = () => {
+    if (loadingPages) {
+      return (
+        <div
+          className="flex flex-col gap-4 lg:flex-row lg:gap-6"
+          data-testid="wiki-loading"
+        >
+          <div className="flex w-full shrink-0 flex-col gap-2 lg:w-64">
+            <Skeleton className="h-9.5 w-full" />
+            <Skeleton className="h-8 w-full" />
+            <Skeleton className="h-8 w-5/6" />
+            <Skeleton className="h-8 w-4/6" />
+            <Skeleton className="h-8 w-5/6" />
+          </div>
+          <ReaderPanel
+            className="min-w-0 flex-1"
+            meta={<Skeleton className="h-3 w-40" />}
+          >
+            <ReaderBars />
+          </ReaderPanel>
+        </div>
+      );
+    }
+    if (pagesFailed) {
+      return (
+        <EmptyState
+          tone="destructive"
+          illustration="none"
+          title={t('settings.sources.wiki.loadFailed')}
+          action={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={() => setPagesAttempt((n) => n + 1)}
+            >
+              {t('retry')}
+            </Button>
+          }
+        />
+      );
+    }
+    if (pages.length === 0) {
+      return (
+        <EmptyState
+          size="xs"
+          illustration="none"
+          title={t('settings.sources.wiki.empty')}
+        />
+      );
+    }
+    const reader = selectedPath ? (
+      <ReaderPanel meta={readerMeta} actions={readerActions}>
+        {readerBody()}
+      </ReaderPanel>
+    ) : (
+      <EmptyState
+        size="xs"
+        illustration="none"
+        title={t('settings.sources.wiki.selectPage')}
+      />
+    );
+    // One page: nothing to choose between, so no navigator; the reader takes
+    // the full width, as TreeBrowser does for a one-file source.
+    if (pages.length === 1) return reader;
+    return (
+      <div className="flex flex-col gap-4 lg:flex-row lg:gap-6">
+        <SourceNavigator
+          nodes={navigatorNodes}
+          selectedId={selectedPath}
+          onSelect={(node) => {
+            if (node.kind === 'leaf') setSelectedPath(node.id);
+          }}
+          filterLabel={t('settings.sources.wiki.filterPages')}
+          emptyLabel={t('settings.sources.noResults')}
+          title={t('settings.sources.wiki.pagesTitle')}
+          folderMode="groups"
+          leafIcon={FileText}
+        />
+        <div className="min-w-0 flex-1">{reader}</div>
+      </div>
     );
   };
 
   return (
-    <div className="flex flex-col">
-      <div className="mb-4 flex items-center">
-        <IconButton
-          variant="outline"
-          size="icon-xs"
-          shape="pill"
-          className="mr-3"
-          onClick={onBackToDocuments}
-          label={t('settings.sources.backToAll')}
-          icon={ArrowLeft}
-          side="bottom"
+    <div className="flex flex-col gap-4">
+      <PathHeader
+        root={{
+          label: t('settings.sources.label'),
+          onSelect: onBackToDocuments,
+        }}
+        segments={[{ label: sourceName }]}
+        badge={
+          <Badge variant="neutral">
+            <BookOpen />
+            {t('settings.sources.wiki.badge')}
+          </Badge>
+        }
+        byline={byline}
+        actions={headerAction}
+      />
+      {renderBody()}
+      {canEdit && selectedPath ? (
+        <SourceEditSheet
+          open={editorOpen}
+          onClose={closeEditor}
+          title={t('settings.sources.wiki.editTitle')}
+          description={
+            page?.version != null
+              ? `${selectedPath} · ${t('settings.sources.wiki.stamp.version', {
+                  version: page.version,
+                })}`
+              : selectedPath
+          }
+          value={draft}
+          onChange={setDraft}
+          dirty={draft !== content}
+          onSave={handleSave}
+          saving={saving}
+          saveLabel={t('settings.sources.wiki.save')}
+          alert={renderEditError()}
+          fieldLabel={t('modals.chunk.bodyText')}
+          placeholder={t('settings.sources.wiki.editPlaceholder')}
         />
-        <span className="text-primary font-semibold wrap-break-word">
-          {sourceName}
-        </span>
-        {headerAction ? <div className="ml-auto">{headerAction}</div> : null}
-      </div>
-
-      <div className="bg-muted text-muted-foreground mb-4 flex items-start gap-2 rounded-xl px-4 py-3 text-xs">
-        <BookOpen className="mt-0.5 size-4 shrink-0" aria-hidden="true" />
-        <p>
-          <span className="text-foreground font-medium">
-            {t('settings.sources.wiki.livingTitle')}
-          </span>{' '}
-          {t('settings.sources.wiki.livingExplainer')}
-          {canEdit && (
-            <> {t('settings.sources.wiki.livingExplainerEditable')}</>
-          )}
-        </p>
-      </div>
-
-      <div className="flex flex-col gap-4 md:flex-row">
-        <div className="border-border md:w-64 md:shrink-0 md:border-r md:pr-4">
-          {loadingPages ? (
-            <SkeletonLoader count={3} />
-          ) : pages.length === 0 ? (
-            <p className="text-muted-foreground py-2 text-sm">
-              {t('settings.sources.wiki.empty')}
-            </p>
-          ) : (
-            <ul className="flex flex-col gap-1">
-              {pages.map((p) => (
-                <li key={p.path}>
-                  <button
-                    type="button"
-                    onClick={() => setSelectedPath(p.path)}
-                    className={cn(
-                      'w-full truncate rounded-lg px-3 py-2 text-left text-sm transition-colors',
-                      selectedPath === p.path
-                        ? 'bg-accent text-foreground'
-                        : 'text-muted-foreground hover:bg-accent',
-                    )}
-                    title={p.path}
-                  >
-                    {p.title || p.path}
-                  </button>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-
-        <div className="min-w-0 flex-1">
-          {loadingContent ? (
-            <SkeletonLoader count={4} />
-          ) : selectedPath ? (
-            <div className="flex flex-col">
-              <div className="mb-2 flex items-center justify-between gap-2">
-                {renderStamp()}
-                {canEdit && !isEditing && (
-                  <Button
-                    type="button"
-                    variant="outline"
-                    size="sm"
-                    onClick={startEditing}
-                  >
-                    {t('settings.sources.wiki.edit')}
-                  </Button>
-                )}
-              </div>
-
-              {editError && (
-                <p
-                  role="alert"
-                  className="border-border text-muted-foreground mb-3 rounded-md border px-3 py-2 text-xs"
-                >
-                  {editError}
-                </p>
-              )}
-
-              {isEditing ? (
-                <div className="flex flex-col gap-3">
-                  <Textarea
-                    value={draft}
-                    onChange={(e) => setDraft(e.target.value)}
-                    placeholder={t('settings.sources.wiki.editPlaceholder')}
-                    variant="filled"
-                    className="min-h-[320px] font-mono"
-                    aria-label={selectedPath}
-                  />
-                  <div className="flex items-center gap-2">
-                    <Button
-                      type="button"
-                      size="sm"
-                      onClick={handleSave}
-                      loading={saving}
-                    >
-                      {t('settings.sources.wiki.save')}
-                    </Button>
-                    <Button
-                      type="button"
-                      variant="ghost"
-                      size="sm"
-                      onClick={cancelEditing}
-                      disabled={saving}
-                    >
-                      {t('settings.sources.wiki.cancel')}
-                    </Button>
-                  </div>
-                </div>
-              ) : (
-                <article className="text-foreground max-w-none text-sm leading-relaxed wrap-break-word">
-                  <ReactMarkdown
-                    remarkPlugins={[remarkGfm]}
-                    components={markdownComponents}
-                  >
-                    {content}
-                  </ReactMarkdown>
-                </article>
-              )}
-            </div>
-          ) : (
-            <p className="text-muted-foreground py-2 text-sm">
-              {t('settings.sources.wiki.selectPage')}
-            </p>
-          )}
-        </div>
-      </div>
+      ) : null}
     </div>
   );
 };
diff --git a/frontend/src/components/chunkUtils.test.ts b/frontend/src/components/chunkUtils.test.ts
index 6ff36b9a..f676f6fc 100644
--- a/frontend/src/components/chunkUtils.test.ts
+++ b/frontend/src/components/chunkUtils.test.ts
@@ -1,20 +1,36 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 
-import { formatChunkTokens, UNKNOWN_TOKEN_COUNT } from './chunkUtils';
+import i18next from 'i18next';
+
+import {
+  abbreviateCount,
+  chunkPreviewText,
+  formatChunkTokens,
+  UNKNOWN_TOKEN_COUNT,
+} from './chunkUtils';
 
 type ChunkMetadata = Parameters<typeof formatChunkTokens>[0];
 
 describe('formatChunkTokens', () => {
+  const language = i18next.language;
+  afterEach(() => {
+    i18next.language = language;
+  });
+
   it('formats a numeric count with separators', () => {
-    expect(formatChunkTokens({ token_count: 1234 })).toBe(
-      (1234).toLocaleString(),
-    );
+    i18next.language = 'en';
+    expect(formatChunkTokens({ token_count: 1234 })).toBe('1,234');
   });
 
   it('formats a count a store handed back as a string', () => {
-    expect(formatChunkTokens({ token_count: '1234' })).toBe(
-      (1234).toLocaleString(),
-    );
+    i18next.language = 'en';
+    expect(formatChunkTokens({ token_count: '1234' })).toBe('1,234');
+  });
+
+  // Bugs row 8: the app language's separators, not the browser's.
+  it('groups in the app language', () => {
+    i18next.language = 'de';
+    expect(formatChunkTokens({ token_count: 11420 })).toBe('11.420');
   });
 
   it('falls back to a dash when the count is unusable', () => {
@@ -29,3 +45,46 @@ describe('formatChunkTokens', () => {
     );
   });
 });
+
+describe('chunkPreviewText', () => {
+  it('strips markdown heading markers and folds line breaks', () => {
+    expect(
+      chunkPreviewText('##### Taxation and\n\n##### Customs Union\n# 2026'),
+    ).toBe('Taxation and · Customs Union · 2026');
+  });
+
+  it('collapses dot leaders and runs of whitespace', () => {
+    expect(chunkPreviewText('List of Tables......................12')).toBe(
+      'List of Tables … 12',
+    );
+    expect(chunkPreviewText('a   b\t\tc')).toBe('a b c');
+  });
+
+  it('keeps ordinary text, an ellipsis and a hash inside a line', () => {
+    expect(chunkPreviewText('Wait... issue #12 is open.')).toBe(
+      'Wait... issue #12 is open.',
+    );
+    expect(chunkPreviewText('')).toBe('');
+  });
+});
+
+describe('abbreviateCount', () => {
+  it('shortens where the language has a short form', () => {
+    expect(abbreviateCount(1234, 'en')).toBe('1.2K');
+    expect(abbreviateCount(1500000, 'en')).toBe('1.5M');
+    expect(abbreviateCount(1234, 'ru')).toBe('1,2\u00a0тыс.');
+    expect(abbreviateCount(1500000, 'jp')).toBe('150万');
+  });
+
+  // de and ja have no compact thousands: the digits still group.
+  it('groups the digits where it has none', () => {
+    expect(abbreviateCount(1234, 'de')).toBe('1.234');
+    expect(abbreviateCount(1234, 'jp')).toBe('1,234');
+    expect(abbreviateCount(1500000, 'de')).toBe('1,5\u00a0Mio.');
+  });
+
+  it('leaves counts under a thousand as they are', () => {
+    expect(abbreviateCount(999, 'en')).toBe('999');
+    expect(abbreviateCount(0, 'zhTW')).toBe('0');
+  });
+});
diff --git a/frontend/src/components/chunkUtils.ts b/frontend/src/components/chunkUtils.ts
index 56853106..351887fd 100644
--- a/frontend/src/components/chunkUtils.ts
+++ b/frontend/src/components/chunkUtils.ts
@@ -3,7 +3,10 @@
  * the formatting rules are unit-testable in isolation.
  */
 
+import i18next from 'i18next';
+
 import { ChunkType } from '../settings/types';
+import { formatCount, intlLocale } from '../utils/dateTimeUtils';
 
 /** What a chunk card shows when the token count is genuinely unknown. */
 export const UNKNOWN_TOKEN_COUNT = '-';
@@ -14,7 +17,7 @@ export const UNKNOWN_TOKEN_COUNT = '-';
  * The backend fills the count in for chunks that were indexed without one, but
  * stores round-trip metadata types differently: pgvector keeps JSON numbers
  * while other backends hand the same value back as a string. Both are counts,
- * so both get thousands separators; only a missing or unusable value falls
+ * so both get the UI language's thousands separators; only a missing or unusable value falls
  * back to a dash.
  */
 export function formatChunkTokens(metadata: ChunkType['metadata']): string {
@@ -23,5 +26,44 @@ export function formatChunkTokens(metadata: ChunkType['metadata']): string {
   if (typeof count !== 'number' || !Number.isFinite(count) || count <= 0) {
     return UNKNOWN_TOKEN_COUNT;
   }
-  return count.toLocaleString();
+  return formatCount(count);
+}
+
+/**
+ * The chunk count beside the search and in the byline: short where the
+ * language has a short form ("1.2K", "1,2 тыс.", "150万"), grouped digits where
+ * it has none (de and ja below 10,000: "1.234").
+ *
+ * @param total The chunk count.
+ * @param language An app language code; defaults to the current one.
+ * @returns The formatted count.
+ */
+export function abbreviateCount(
+  total: number,
+  language: string = i18next.language,
+): string {
+  return new Intl.NumberFormat(intlLocale(language), {
+    notation: 'compact',
+    useGrouping: 'always',
+  }).format(total);
+}
+
+/**
+ * The text a chunk tile previews: the stored text with markdown heading
+ * markers stripped, table-of-contents dot leaders collapsed to "…", runs of
+ * whitespace folded and line breaks joined with " · ". Display only; the
+ * stored text and the editor keep the original.
+ */
+export function chunkPreviewText(text: string): string {
+  return (text ?? '')
+    .split(/\r?\n/)
+    .map((line) =>
+      line
+        .replace(/^\s*#+\s*/, '')
+        .replace(/\.{4,}/g, ' … ')
+        .replace(/[ \t]+/g, ' ')
+        .trim(),
+    )
+    .filter(Boolean)
+    .join(' · ');
 }
diff --git a/frontend/src/components/graph/GraphCanvasControls.tsx b/frontend/src/components/graph/GraphCanvasControls.tsx
new file mode 100644
index 00000000..ce00a389
--- /dev/null
+++ b/frontend/src/components/graph/GraphCanvasControls.tsx
@@ -0,0 +1,58 @@
+import { Maximize, Minus, Plus } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { IconButton } from '../ui/icon-button';
+
+interface GraphCanvasControlsProps {
+  /** The current zoom factor (1 = 100%). */
+  zoom: number;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onFit: () => void;
+}
+
+/**
+ * The graph canvas's control strip, bottom left: zoom out, the zoom level,
+ * zoom in, then fit view. The workflow builder's `CanvasControls` recipe
+ * without React Flow.
+ */
+export default function GraphCanvasControls({
+  zoom,
+  onZoomIn,
+  onZoomOut,
+  onFit,
+}: GraphCanvasControlsProps) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="bg-card border-border absolute bottom-3 left-3 flex items-center gap-0.5 rounded-full border p-1">
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={onZoomOut}
+        label={t('agents.workflow.zoomOut')}
+        icon={Minus}
+      />
+      <span className="text-foreground w-11 text-center text-xs tabular-nums">
+        {Math.round(zoom * 100)}%
+      </span>
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={onZoomIn}
+        label={t('agents.workflow.zoomIn')}
+        icon={Plus}
+      />
+      <IconButton
+        variant="ghost-muted"
+        size="icon-sm"
+        shape="pill"
+        onClick={onFit}
+        label={t('agents.workflow.fitView')}
+        icon={Maximize}
+      />
+    </div>
+  );
+}
diff --git a/frontend/src/components/graph/GraphChunkSheet.test.tsx b/frontend/src/components/graph/GraphChunkSheet.test.tsx
new file mode 100644
index 00000000..262a9586
--- /dev/null
+++ b/frontend/src/components/graph/GraphChunkSheet.test.tsx
@@ -0,0 +1,214 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const dispatch = vi.fn();
+vi.mock('react-redux', () => ({
+  useSelector: () => 'tok',
+  useDispatch: () => dispatch,
+}));
+
+vi.mock('../../api/services/userService', () => ({
+  default: { updateChunk: vi.fn() },
+}));
+
+import userService from '../../api/services/userService';
+import type { GraphNodeChunk } from '../graphViewUtils';
+import GraphChunkSheet from './GraphChunkSheet';
+
+const updateChunk = (
+  userService as unknown as { updateChunk: ReturnType<typeof vi.fn> }
+).updateChunk;
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('GraphChunkSheet', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    updateChunk.mockReset();
+    updateChunk.mockResolvedValue({ ok: true, status: 200 });
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+    dispatch.mockReset();
+  });
+
+  const button = (text: string) =>
+    [...document.body.querySelectorAll('button')].find(
+      (b) => b.textContent === text,
+    ) as HTMLButtonElement | undefined;
+
+  const saveEdit = async (chunk: GraphNodeChunk, value: string) => {
+    await act(async () => {
+      root.render(
+        <GraphChunkSheet
+          docId="doc"
+          chunk={chunk}
+          highlight=""
+          onClose={vi.fn()}
+        />,
+      );
+    });
+    await act(async () => button('modals.chunk.edit')!.click());
+    const field = document.body.querySelector('textarea')!;
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLTextAreaElement.prototype,
+        'value',
+      )!.set!.call(field, value);
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await act(async () => button('modals.chunk.save')!.click());
+  };
+
+  it('saving an untitled chunk sends no title', async () => {
+    await saveEdit(
+      { chunk_id: 'c1', text: 'Old', metadata: { source: 'a.md' } },
+      'New',
+    );
+    expect(updateChunk).toHaveBeenCalledTimes(1);
+    const body = updateChunk.mock.calls[0][0];
+    expect(body).toEqual({ id: 'doc', chunk_id: 'c1', text: 'New' });
+    expect(body.metadata?.title).toBeUndefined();
+  });
+
+  it('saving a titled chunk keeps its title', async () => {
+    await saveEdit(
+      { chunk_id: 'c1', text: 'Old', metadata: { title: 'Brief.md' } },
+      'New',
+    );
+    expect(updateChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        chunk_id: 'c1',
+        text: 'New',
+        metadata: { title: 'Brief.md' },
+      },
+      'tok',
+    );
+  });
+
+  it('the edit drawer edits the title like Chunks', async () => {
+    await act(async () => {
+      root.render(
+        <GraphChunkSheet
+          docId="doc"
+          chunk={{ chunk_id: 'c1', text: 'Body', metadata: { title: 'Old' } }}
+          highlight=""
+          onClose={vi.fn()}
+        />,
+      );
+    });
+    await act(async () => button('modals.chunk.edit')!.click());
+    const input = document.body.querySelector(
+      'input[type="text"], input:not([type])',
+    ) as HTMLInputElement;
+    expect(input).not.toBeNull();
+    expect(input.value).toBe('Old');
+    expect(document.body.textContent).toContain('modals.chunk.title');
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        'value',
+      )!.set!.call(input, ' New title ');
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    // A title-only edit is a change: Save is enabled and sends it trimmed.
+    await act(async () => button('modals.chunk.save')!.click());
+    expect(updateChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        chunk_id: 'c1',
+        text: 'Body',
+        metadata: { title: 'New title' },
+      },
+      'tok',
+    );
+  });
+
+  it('Open in Files opens the tree path, not a web page URL', async () => {
+    const onOpenInFiles = vi.fn();
+    await act(async () => {
+      root.render(
+        <GraphChunkSheet
+          docId="doc"
+          chunk={{
+            chunk_id: 'c1',
+            text: 'Body',
+            metadata: {
+              source: 'https://docs.example.com/guides/setup',
+              file_path: 'guides/setup.md',
+              title: 'Setup',
+            },
+          }}
+          highlight=""
+          onClose={vi.fn()}
+          onOpenInFiles={onOpenInFiles}
+        />,
+      );
+    });
+    await act(async () =>
+      button('settings.sources.graphrag.view.openInFiles')!.click(),
+    );
+    expect(onOpenInFiles).toHaveBeenCalledWith('guides/setup.md');
+  });
+
+  // Leaving the edit drawer (Cancel, Discard, Esc, X) returns to the read
+  // drawer on the same chunk; only a successful save closes both.
+  it('Cancel in the edit drawer returns to the read drawer', async () => {
+    const onClose = vi.fn();
+    await act(async () => {
+      root.render(
+        <GraphChunkSheet
+          docId="doc"
+          chunk={{ chunk_id: 'c1', text: 'Old body', metadata: {} }}
+          highlight=""
+          onClose={onClose}
+        />,
+      );
+    });
+    await act(async () => button('modals.chunk.edit')!.click());
+    expect(document.body.querySelector('textarea')).not.toBeNull();
+    await act(async () => button('settings.sources.editor.cancel')!.click());
+    expect(onClose).not.toHaveBeenCalled();
+    expect(document.body.querySelector('textarea')).toBeNull();
+    expect(button('modals.chunk.edit')).toBeDefined();
+    expect(document.body.textContent).toContain('Old body');
+  });
+
+  it('a successful save closes both drawers', async () => {
+    const onClose = vi.fn();
+    await act(async () => {
+      root.render(
+        <GraphChunkSheet
+          docId="doc"
+          chunk={{ chunk_id: 'c1', text: 'Old', metadata: {} }}
+          highlight=""
+          onClose={onClose}
+        />,
+      );
+    });
+    await act(async () => button('modals.chunk.edit')!.click());
+    const field = document.body.querySelector('textarea')!;
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLTextAreaElement.prototype,
+        'value',
+      )!.set!.call(field, 'New');
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await act(async () => button('modals.chunk.save')!.click());
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/frontend/src/components/graph/GraphChunkSheet.tsx b/frontend/src/components/graph/GraphChunkSheet.tsx
new file mode 100644
index 00000000..d3327277
--- /dev/null
+++ b/frontend/src/components/graph/GraphChunkSheet.tsx
@@ -0,0 +1,237 @@
+import { Pencil } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useDispatch, useSelector } from 'react-redux';
+
+import userService from '../../api/services/userService';
+import { showActionToast } from '../../notifications/actionToastSlice';
+import { selectToken } from '../../preferences/preferenceSlice';
+import { UNKNOWN_TOKEN_COUNT, formatChunkTokens } from '../chunkUtils';
+import SourceMarkdown from '../SourceMarkdown';
+import SourceEditSheet from '../tree/SourceEditSheet';
+import { Alert, AlertDescription } from '../ui/alert';
+import { Button } from '../ui/button';
+import { FormField } from '../ui/form-field';
+import { Input } from '../ui/input';
+import { Separator } from '../ui/separator';
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from '../ui/sheet';
+import type { GraphNodeChunk } from '../graphViewUtils';
+import { chunkFileName, chunkFilePath, chunkHeading } from './graphCanvasUtils';
+
+interface GraphChunkSheetProps {
+  docId: string;
+  /** The chunk to show; null closes both drawers. */
+  chunk: GraphNodeChunk | null;
+  /** The entity's name, marked in the rendered chunk. */
+  highlight: string;
+  /** Called once the drawers close (the node stays selected). */
+  onClose: () => void;
+  /** Show the chunk's file on the Files tab; omitted hides the button. */
+  onOpenInFiles?: (path: string) => void;
+  /** Called after a saved edit, to refetch the node detail. */
+  onSaved?: () => void;
+}
+
+/**
+ * A source chunk of a graph entity, opened from the node panel: a read drawer
+ * with the chunk rendered (the entity's name marked), "Open in Files" and
+ * Edit; Edit swaps it for the shared edit drawer. Built like
+ * WorkflowDetailsSheet: header, one scrolling body, then the actions.
+ */
+export default function GraphChunkSheet({
+  docId,
+  chunk,
+  highlight,
+  onClose,
+  onOpenInFiles,
+  onSaved,
+}: GraphChunkSheetProps) {
+  const { t } = useTranslation();
+  const dispatch = useDispatch();
+  const token = useSelector(selectToken);
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState('');
+  const [draftTitle, setDraftTitle] = useState('');
+  const [saving, setSaving] = useState(false);
+  const [saveFailed, setSaveFailed] = useState(false);
+
+  // Every newly opened chunk starts in the read drawer.
+  useEffect(() => {
+    setEditing(false);
+    setSaveFailed(false);
+  }, [chunk?.chunk_id]);
+
+  if (!chunk) return null;
+
+  const file = chunkFileName(chunk.metadata);
+  // The tree path "Open in Files" opens (a web page's is not its URL).
+  const path = chunkFilePath(chunk.metadata);
+  const tokens = formatChunkTokens(
+    (chunk.metadata ?? {}) as Parameters<typeof formatChunkTokens>[0],
+  );
+  const hasTokens = tokens !== UNKNOWN_TOKEN_COUNT;
+  const heading = chunkHeading(chunk.text);
+  const title = heading || file || t('settings.sources.graphrag.view.chunk');
+  const meta =
+    file && hasTokens
+      ? t('settings.sources.graphrag.view.chunkMeta', {
+          file,
+          tokens,
+          interpolation: { escapeValue: false },
+        })
+      : hasTokens
+        ? t('settings.sources.graphrag.view.chunkTokens', { tokens })
+        : file;
+  // When the file name is already the title, the read header shows only the
+  // token count; the edit drawer keeps the full line.
+  const readMeta =
+    heading || !file
+      ? meta
+      : hasTokens
+        ? t('settings.sources.graphrag.view.chunkTokens', { tokens })
+        : '';
+
+  const close = () => {
+    setEditing(false);
+    setSaveFailed(false);
+    onClose();
+  };
+
+  // Leaving the edit drawer without saving returns to the read drawer.
+  const leaveEdit = () => {
+    setEditing(false);
+    setSaveFailed(false);
+  };
+
+  const savedTitle =
+    typeof chunk.metadata?.title === 'string' ? chunk.metadata.title : '';
+
+  const startEdit = () => {
+    setDraft(chunk.text ?? '');
+    setDraftTitle(savedTitle);
+    setSaveFailed(false);
+    setEditing(true);
+  };
+
+  const save = async () => {
+    setSaving(true);
+    setSaveFailed(false);
+    // The backend merges metadata: send a title only when the chunk had one
+    // (clearing it sends '') or one was entered, never '' onto an untitled
+    // one. As Chunks does.
+    const sendTitle = !!savedTitle || !!draftTitle.trim();
+    try {
+      const response = await userService.updateChunk(
+        {
+          id: docId,
+          chunk_id: chunk.chunk_id,
+          text: draft,
+          ...(sendTitle ? { metadata: { title: draftTitle.trim() } } : {}),
+        },
+        token,
+      );
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      close();
+      onSaved?.();
+      dispatch(
+        showActionToast({
+          variant: 'success',
+          message: t('settings.sources.graphrag.view.chunkSaved'),
+        }),
+      );
+    } catch (error) {
+      console.error('Error saving chunk:', error);
+      setSaveFailed(true);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <>
+      <Sheet open={!editing} onOpenChange={(open) => !open && close()}>
+        <SheetContent
+          side="right"
+          size="detail"
+          className="p-0"
+          closeLabel={t('settings.sources.editor.close')}
+        >
+          <div className="flex min-h-0 flex-1 flex-col">
+            {/* pr-12 keeps the header clear of the close X at top-2 right-2. */}
+            <div className="flex flex-col gap-1 px-6 pt-6 pr-12 pb-4">
+              <SheetTitle className="wrap-break-word">{title}</SheetTitle>
+              {readMeta ? (
+                <SheetDescription className="wrap-anywhere">
+                  {readMeta}
+                </SheetDescription>
+              ) : null}
+            </div>
+            <Separator />
+            <div className="min-h-0 flex-1 overflow-y-auto px-6 py-6">
+              <SourceMarkdown
+                content={chunk.text ?? ''}
+                highlight={highlight}
+              />
+            </div>
+            <Separator />
+            <div className="flex justify-end gap-3 px-6 py-4">
+              {onOpenInFiles && path ? (
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="lg"
+                  shape="pill"
+                  onClick={() => {
+                    close();
+                    onOpenInFiles(path);
+                  }}
+                >
+                  {t('settings.sources.graphrag.view.openInFiles')}
+                </Button>
+              ) : null}
+              <Button type="button" size="lg" shape="pill" onClick={startEdit}>
+                <Pencil />
+                {t('modals.chunk.edit')}
+              </Button>
+            </div>
+          </div>
+        </SheetContent>
+      </Sheet>
+      <SourceEditSheet
+        open={editing}
+        onClose={leaveEdit}
+        title={t('settings.sources.graphrag.view.editChunk')}
+        description={meta || undefined}
+        value={draft}
+        onChange={setDraft}
+        dirty={draft !== (chunk.text ?? '') || draftTitle.trim() !== savedTitle}
+        fields={
+          <FormField
+            label={t('modals.chunk.title')}
+            hint={t('settings.sources.chunkTitleHint')}
+            labelSurface="background"
+          >
+            <Input
+              value={draftTitle}
+              onChange={(event) => setDraftTitle(event.target.value)}
+              disabled={saving}
+            />
+          </FormField>
+        }
+        onSave={save}
+        saving={saving}
+        saveLabel={t('modals.chunk.save')}
+        alert={
+          saveFailed ? (
+            <Alert variant="destructive">
+              <AlertDescription>
+                {t('settings.sources.chunkErrors.save')}
+              </AlertDescription>
+            </Alert>
+          ) : null
+        }
+        fieldLabel={t('modals.chunk.bodyText')}
+      />
+    </>
+  );
+}
diff --git a/frontend/src/components/graph/GraphEntities.tsx b/frontend/src/components/graph/GraphEntities.tsx
new file mode 100644
index 00000000..42e9057c
--- /dev/null
+++ b/frontend/src/components/graph/GraphEntities.tsx
@@ -0,0 +1,350 @@
+import { Waypoints } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useSelector } from 'react-redux';
+
+import userService from '../../api/services/userService';
+import { useDebouncedValue, useMediaQuery } from '../../hooks';
+import { selectToken } from '../../preferences/preferenceSlice';
+import { formatCount } from '../../utils/dateTimeUtils';
+import SearchInput from '../SearchInput';
+import { Button } from '../ui/button';
+import { Card } from '../ui/card';
+import { EmptyState } from '../ui/empty-state';
+import { Pagination } from '../ui/pagination';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '../ui/select';
+import { Sheet, SheetContent } from '../ui/sheet';
+import { Skeleton } from '../ui/skeleton';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '../ui/table';
+import type {
+  FoldedGraphTypes,
+  ForceGraphData,
+  GraphNodeSummary,
+  GraphTypeFacet,
+} from '../graphViewUtils';
+import GraphNodePanel, {
+  GraphNodePanelDock,
+  type GraphNodeRef,
+} from './GraphNodePanel';
+import { GraphTypeBadge } from './GraphTypeDot';
+import { useGraphNodeDetail } from './useGraphNodeDetail';
+
+const ENTITIES_PER_PAGE = 25;
+// Radix Select can't hold "" as a value, and "" is the untyped key.
+const ALL_TYPES = '__all';
+const UNTYPED = '__untyped';
+
+type ListStatus = 'loading' | 'error' | 'ready';
+
+/**
+ * The Entities tab: every node of the source, searchable and filterable by
+ * type, busiest first, paged. The frame is the Graph tab's: one `subtle`
+ * Card at `h-[70svh]` with the table scrolling inside and a row's node panel
+ * docked at its right edge (a bottom sheet on a phone), whose "Show in graph"
+ * jumps to the canvas.
+ */
+export default function GraphEntities({
+  docId,
+  fold,
+  onShowInGraph,
+  overview,
+  onOpenInFiles,
+}: {
+  docId: string;
+  fold: FoldedGraphTypes;
+  onShowInGraph: (node: GraphNodeRef) => void;
+  /** The loaded overview, for the node panel's relationships fallback. */
+  overview?: ForceGraphData;
+  /** Show a chunk's file on the Files tab. */
+  onOpenInFiles?: (path: string) => void;
+}) {
+  const { t } = useTranslation();
+  const token = useSelector(selectToken);
+  const { isDesktop } = useMediaQuery();
+
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebouncedValue(query.trim(), 300);
+  const [typeFilter, setTypeFilter] = useState(ALL_TYPES);
+  const [page, setPage] = useState(1);
+  const [nodes, setNodes] = useState<GraphNodeSummary[]>([]);
+  const [total, setTotal] = useState(0);
+  const [types, setTypes] = useState<GraphTypeFacet[]>([]);
+  const [status, setStatus] = useState<ListStatus>('loading');
+  const [attempt, setAttempt] = useState(0);
+  const [selected, setSelected] = useState<GraphNodeRef | null>(null);
+  const nodeDetail = useGraphNodeDetail(docId, selected?.id ?? null);
+
+  // A new search or type filter starts on page 1; that page change then
+  // fetches, so the old page is never requested with the new filter.
+  const filterKey = `${debouncedQuery}\u0000${typeFilter}`;
+  const fetchedFilterRef = useRef(filterKey);
+  useEffect(() => {
+    if (fetchedFilterRef.current !== filterKey) {
+      fetchedFilterRef.current = filterKey;
+      if (page !== 1) {
+        setPage(1);
+        return;
+      }
+    }
+    let cancelled = false;
+    setStatus('loading');
+    userService
+      .getSourceGraphNodes(
+        docId,
+        {
+          q: debouncedQuery || undefined,
+          type:
+            typeFilter === ALL_TYPES
+              ? undefined
+              : typeFilter === UNTYPED
+                ? ''
+                : typeFilter,
+          page,
+          perPage: ENTITIES_PER_PAGE,
+        },
+        token,
+      )
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
+      .then((body) => {
+        if (cancelled) return;
+        setNodes(body?.nodes ?? []);
+        setTotal(body?.total ?? 0);
+        setTypes(body?.types ?? []);
+        setStatus('ready');
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        console.error('Error loading graph entities:', error);
+        setStatus('error');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [docId, filterKey, page, token, attempt]);
+
+  const pageCount = Math.max(1, Math.ceil(total / ENTITIES_PER_PAGE));
+  const untypedLabel = t('settings.sources.graphrag.view.untyped');
+  const filtered = debouncedQuery !== '' || typeFilter !== ALL_TYPES;
+
+  const panel = selected ? (
+    <GraphNodePanel
+      key={selected.id}
+      docId={docId}
+      node={selected}
+      detail={nodeDetail.detail}
+      status={nodeDetail.status}
+      onRetry={nodeDetail.retry}
+      fold={fold}
+      onClose={() => setSelected(null)}
+      showClose={isDesktop}
+      onSelectNode={setSelected}
+      overview={overview}
+      onOpenInFiles={onOpenInFiles}
+      onChunkSaved={nodeDetail.reload}
+      action={
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          shape="pill"
+          onClick={() => onShowInGraph(selected)}
+        >
+          <Waypoints />
+          {t('settings.sources.graphrag.view.showInGraph')}
+        </Button>
+      }
+    />
+  ) : null;
+
+  const body =
+    status === 'error' ? (
+      <EmptyState
+        size="sm"
+        tone="destructive"
+        illustration="none"
+        title={t('settings.sources.graphrag.view.entitiesLoadFailed')}
+        action={
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            shape="pill"
+            onClick={() => setAttempt((n) => n + 1)}
+          >
+            {t('retry')}
+          </Button>
+        }
+      />
+    ) : status === 'ready' && nodes.length === 0 ? (
+      <EmptyState
+        size="xs"
+        illustration="none"
+        title={
+          filtered
+            ? t('settings.sources.graphrag.view.noEntities')
+            : t('settings.sources.graphrag.view.empty')
+        }
+      />
+    ) : (
+      <div className="scrollbar-overlay min-h-0 flex-1 overflow-auto">
+        <Table minWidth="min-w-0">
+          <TableHead>
+            <TableRow>
+              <TableHeader>
+                {t('settings.sources.graphrag.view.entityName')}
+              </TableHeader>
+              <TableHeader>{t('settings.sources.type')}</TableHeader>
+              <TableHeader align="right">
+                {t('settings.sources.graphrag.view.connections')}
+              </TableHeader>
+              <TableHeader align="right">
+                {t('settings.sources.chunks')}
+              </TableHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {status === 'loading'
+              ? Array.from({ length: 6 }, (_, index) => (
+                  <TableRow key={index}>
+                    <TableCell>
+                      <Skeleton className="h-3 w-40" />
+                    </TableCell>
+                    <TableCell>
+                      <Skeleton className="h-3 w-20" />
+                    </TableCell>
+                    <TableCell align="right">
+                      <Skeleton className="ml-auto h-3 w-8" />
+                    </TableCell>
+                    <TableCell align="right">
+                      <Skeleton className="ml-auto h-3 w-8" />
+                    </TableCell>
+                  </TableRow>
+                ))
+              : nodes.map((node) => (
+                  <TableRow
+                    key={node.id}
+                    selected={selected?.id === node.id}
+                    onClick={() =>
+                      setSelected({
+                        id: node.id,
+                        name: node.name,
+                        type: node.type,
+                      })
+                    }
+                  >
+                    <TableCell className="font-medium wrap-break-word">
+                      {node.name}
+                    </TableCell>
+                    <TableCell>
+                      <GraphTypeBadge fold={fold} type={node.type} />
+                    </TableCell>
+                    <TableCell align="right" className="tabular-nums">
+                      {formatCount(node.degree)}
+                    </TableCell>
+                    <TableCell align="right" className="tabular-nums">
+                      {formatCount(node.doc_freq ?? 0)}
+                    </TableCell>
+                  </TableRow>
+                ))}
+          </TableBody>
+        </Table>
+      </div>
+    );
+  // Kept through a page load (the previous page's rows stay until the next
+  // arrive), so Prev / Next do not shift the layout.
+  const showPager = status !== 'error' && nodes.length > 0;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <div className="w-full sm:w-72">
+          <SearchInput
+            label={t('settings.sources.graphrag.view.findEntity')}
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+          />
+        </div>
+        <Select value={typeFilter} onValueChange={setTypeFilter}>
+          <SelectTrigger
+            size="field"
+            shape="pill"
+            className="w-full sm:w-56"
+            aria-label={t('settings.sources.type')}
+          >
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value={ALL_TYPES}>
+              {t('settings.sources.graphrag.view.allTypes')}
+            </SelectItem>
+            {types.map((facet) => (
+              <SelectItem
+                key={facet.key || UNTYPED}
+                value={facet.key || UNTYPED}
+              >
+                {facet.key ? (facet.label ?? facet.key) : untypedLabel}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+      <Card
+        variant="subtle"
+        padding="none"
+        className="h-[70svh] flex-row gap-0 overflow-hidden"
+      >
+        <div className="flex min-w-0 flex-1 flex-col justify-center">
+          {body}
+        </div>
+        {isDesktop && panel ? (
+          <GraphNodePanelDock>{panel}</GraphNodePanelDock>
+        ) : null}
+      </Card>
+      {showPager ? (
+        <Pagination
+          page={page}
+          pageCount={pageCount}
+          onPageChange={setPage}
+          summary={t('settings.sources.graphrag.view.entityCount', {
+            count: total,
+            formatted: formatCount(total),
+          })}
+        />
+      ) : null}
+      {!isDesktop ? (
+        <Sheet
+          open={!!selected}
+          onOpenChange={(open) => {
+            if (!open) setSelected(null);
+          }}
+        >
+          <SheetContent
+            side="bottom"
+            handle
+            title={selected?.name}
+            // Open on the panel, not with a ring on its first control.
+            onOpenAutoFocus={(event) => event.preventDefault()}
+          >
+            {panel}
+          </SheetContent>
+        </Sheet>
+      ) : null}
+    </div>
+  );
+}
diff --git a/frontend/src/components/graph/GraphEntitySearch.tsx b/frontend/src/components/graph/GraphEntitySearch.tsx
new file mode 100644
index 00000000..bbd9dc14
--- /dev/null
+++ b/frontend/src/components/graph/GraphEntitySearch.tsx
@@ -0,0 +1,191 @@
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useSelector } from 'react-redux';
+
+import userService from '../../api/services/userService';
+import { useDebouncedValue } from '../../hooks';
+import { selectToken } from '../../preferences/preferenceSlice';
+import SearchInput from '../SearchInput';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandList,
+} from '../ui/command';
+import { EmptyState } from '../ui/empty-state';
+import { LoadingState } from '../ui/loading-state';
+import { Popover, PopoverAnchor, PopoverContent } from '../ui/popover';
+import type { FoldedGraphTypes, GraphNodeSummary } from '../graphViewUtils';
+import type { GraphNodeRef } from './GraphNodePanel';
+import { GraphTypeDot, useGraphTypeLabel } from './GraphTypeDot';
+
+const SEARCH_PAGE_SIZE = 8;
+
+/**
+ * "Find an entity": searches every node of the source by name (not only the
+ * loaded overview) and selects the pick. The results are a Popover + Command
+ * anchored under the field; arrows and Enter drive it from the field.
+ */
+export default function GraphEntitySearch({
+  docId,
+  fold,
+  onPick,
+}: {
+  docId: string;
+  fold: FoldedGraphTypes;
+  onPick: (node: GraphNodeRef) => void;
+}) {
+  const { t } = useTranslation();
+  const token = useSelector(selectToken);
+  const labelOf = useGraphTypeLabel(fold);
+  const [query, setQuery] = useState('');
+  const [open, setOpen] = useState(false);
+  const [hits, setHits] = useState<GraphNodeSummary[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [active, setActive] = useState('');
+  const anchorRef = useRef<HTMLDivElement>(null);
+  const debounced = useDebouncedValue(query.trim(), 250);
+
+  useEffect(() => {
+    if (!debounced) {
+      setHits([]);
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    userService
+      .getSourceGraphNodes(
+        docId,
+        { q: debounced, perPage: SEARCH_PAGE_SIZE },
+        token,
+      )
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
+      .then((body) => {
+        if (cancelled) return;
+        const nodes: GraphNodeSummary[] = body?.nodes ?? [];
+        setHits(nodes);
+        setActive(nodes[0]?.id ?? '');
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        console.error('Error searching graph nodes:', error);
+        setHits([]);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [docId, debounced, token]);
+
+  const pick = (hit: GraphNodeSummary) => {
+    setQuery('');
+    setOpen(false);
+    onPick({ id: hit.id, name: hit.name, type: hit.type });
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Escape') {
+      if (open) {
+        event.preventDefault();
+        setOpen(false);
+      }
+      return;
+    }
+    if (!hits.length) return;
+    const index = hits.findIndex((hit) => hit.id === active);
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      setOpen(true);
+      const step = event.key === 'ArrowDown' ? 1 : -1;
+      const next = (index + step + hits.length) % hits.length;
+      setActive(hits[next].id);
+    } else if (event.key === 'Enter' && open) {
+      event.preventDefault();
+      // Still debouncing: the listed hits belong to the previous query.
+      if (query.trim() !== debounced) return;
+      const hit = hits[index] ?? hits[0];
+      if (hit) pick(hit);
+    }
+  };
+
+  const showPopover = open && query.trim() !== '';
+  // Still typing, or the request is out: don't flash "No entities found".
+  const pending = loading || query.trim() !== debounced;
+
+  return (
+    <Popover open={showPopover} onOpenChange={setOpen}>
+      <PopoverAnchor asChild>
+        <div ref={anchorRef} className="w-full sm:w-72">
+          <SearchInput
+            label={t('settings.sources.graphrag.view.findEntity')}
+            value={query}
+            role="combobox"
+            aria-expanded={showPopover}
+            aria-autocomplete="list"
+            onChange={(event) => {
+              setQuery(event.target.value);
+              setOpen(true);
+            }}
+            onFocus={() => {
+              if (query.trim()) setOpen(true);
+            }}
+            onKeyDown={onKeyDown}
+          />
+        </div>
+      </PopoverAnchor>
+      <PopoverContent
+        align="start"
+        className="w-(--radix-popover-trigger-width) p-0"
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        onInteractOutside={(event) => {
+          // A click back in the field keeps the list open.
+          if (anchorRef.current?.contains(event.target as Node)) {
+            event.preventDefault();
+          }
+        }}
+      >
+        <Command shouldFilter={false} value={active} onValueChange={setActive}>
+          <CommandList>
+            {pending && hits.length === 0 ? (
+              <LoadingState fill="block" size="sm" />
+            ) : (
+              <CommandEmpty>
+                <EmptyState
+                  size="xs"
+                  illustration="none"
+                  title={t('settings.sources.graphrag.view.noEntities')}
+                />
+              </CommandEmpty>
+            )}
+            {hits.length ? (
+              <CommandGroup>
+                {hits.map((hit) => (
+                  <CommandItem
+                    key={hit.id}
+                    value={hit.id}
+                    onSelect={() => pick(hit)}
+                  >
+                    <GraphTypeDot fold={fold} type={hit.type} />
+                    <span className="min-w-0 flex-1 truncate" title={hit.name}>
+                      {hit.name}
+                    </span>
+                    <span className="text-muted-foreground max-w-[40%] truncate text-xs">
+                      {labelOf(hit.type)}
+                    </span>
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            ) : null}
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/frontend/src/components/graph/GraphNodePanel.test.tsx b/frontend/src/components/graph/GraphNodePanel.test.tsx
new file mode 100644
index 00000000..46117c4b
--- /dev/null
+++ b/frontend/src/components/graph/GraphNodePanel.test.tsx
@@ -0,0 +1,459 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    // "key:count", then any other params: "key:20 {"formatted":"20"}".
+    t: (key: string, opts?: Record<string, unknown>) => {
+      if (!opts || !('count' in opts)) return key;
+      const { count, ...rest } = opts;
+      return Object.keys(rest).length
+        ? `${key}:${count} ${JSON.stringify(rest)}`
+        : `${key}:${count}`;
+    },
+  }),
+}));
+
+const dispatch = vi.fn();
+vi.mock('react-redux', () => ({
+  useSelector: () => 'tok',
+  useDispatch: () => dispatch,
+}));
+
+vi.mock('../../api/services/userService', () => ({
+  default: { updateChunk: vi.fn() },
+}));
+
+import i18next from 'i18next';
+
+import userService from '../../api/services/userService';
+import { foldGraphTypes, type GraphNodeDetail } from '../graphViewUtils';
+import GraphNodePanel, { RELATIONSHIP_PREVIEW } from './GraphNodePanel';
+
+const updateChunk = (
+  userService as unknown as {
+    updateChunk: ReturnType<typeof vi.fn>;
+  }
+).updateChunk;
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const fold = foldGraphTypes([
+  { type: 'Company' },
+  { type: 'Company' },
+  { type: 'Person' },
+  { type: 'Lane' },
+]);
+
+const DETAIL: GraphNodeDetail = {
+  id: 'nord',
+  name: 'Nordhaven Logistics B.V.',
+  type: 'Company',
+  description: 'Dutch road haulier based in Schiedam.',
+  degree: 55,
+  doc_freq: 20,
+  relationships: [
+    {
+      id: 'anneke',
+      name: 'Anneke de Vries',
+      type: 'Person',
+      degree: 40,
+      edge_type: 'MANAGES',
+      direction: 'in',
+    },
+    {
+      id: 'anneke',
+      name: 'Anneke de Vries',
+      type: 'Person',
+      degree: 40,
+      edge_type: 'manages',
+      direction: 'out',
+    },
+    {
+      id: 'anneke',
+      name: 'Anneke de Vries',
+      type: 'Person',
+      degree: 40,
+      edge_type: 'CARRIER_MANAGER_FOR',
+      direction: 'in',
+    },
+    {
+      id: 'duisport',
+      name: 'Duisport',
+      type: 'Port',
+      degree: 12,
+      edge_type: null,
+      direction: 'out',
+    },
+  ],
+  chunks: [
+    {
+      chunk_id: 'c1',
+      text: 'Carrier profile — Nordhaven Logistics B.V.',
+      metadata: { source: 'inputs/local/Carrier_profile_Nordhaven.docx' },
+    },
+  ],
+};
+
+describe('GraphNodePanel', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+    updateChunk.mockReset();
+    dispatch.mockReset();
+  });
+
+  const render = async (
+    props: Partial<React.ComponentProps<typeof GraphNodePanel>> = {},
+  ) => {
+    const handlers = {
+      onClose: vi.fn(),
+      onSelectNode: vi.fn(),
+      onRetry: vi.fn(),
+      onOpenInFiles: vi.fn(),
+      onChunkSaved: vi.fn(),
+    };
+    await act(async () => {
+      root.render(
+        <GraphNodePanel
+          docId="doc"
+          node={{ id: 'nord', name: 'Nordhaven', type: 'Company' }}
+          detail={DETAIL}
+          status="ready"
+          fold={fold}
+          {...handlers}
+          {...props}
+        />,
+      );
+    });
+    return handlers;
+  };
+
+  const relationshipButtons = () =>
+    Array.from(container.querySelectorAll('ul button'));
+
+  it('shows the facts, one row per neighbour and the chunk file', async () => {
+    await render();
+    const text = container.textContent ?? '';
+    expect(container.querySelector('h3')?.textContent).toBe(
+      'Nordhaven Logistics B.V.',
+    );
+    expect(text).toContain('55');
+    expect(text).toContain('settings.sources.graphrag.view.chunkCount:20');
+
+    const rows = relationshipButtons();
+    expect(rows).toHaveLength(2);
+    // The busiest neighbour first, its labels normalised and deduplicated.
+    expect(rows[0].textContent).toContain('Anneke de Vries');
+    expect(rows[0].textContent).toContain('manages · carrier manager for');
+    // No label on the edge: the "related to" fallback.
+    expect(rows[1].textContent).toContain('Duisport');
+    expect(rows[1].textContent).toContain(
+      'settings.sources.graphrag.view.relatedTo',
+    );
+
+    expect(text).toContain('Carrier profile — Nordhaven Logistics B.V.');
+    expect(text).toContain('Carrier_profile_Nordhaven.docx');
+    expect(text).not.toContain('inputs/local');
+  });
+
+  it('draws its close X unless the sheet hides it', async () => {
+    const closeButton = () =>
+      container.querySelector(
+        'button[aria-label="settings.sources.graphrag.view.close"]',
+      );
+    const { onClose } = await render();
+    await act(async () => {
+      (closeButton() as HTMLButtonElement).click();
+    });
+    expect(onClose).toHaveBeenCalled();
+
+    await render({ showClose: false });
+    expect(closeButton()).toBeNull();
+  });
+
+  it('selects the neighbour a row points at', async () => {
+    const { onSelectNode } = await render();
+    await act(async () => {
+      (relationshipButtons()[1] as HTMLButtonElement).click();
+    });
+    expect(onSelectNode).toHaveBeenCalledWith({
+      id: 'duisport',
+      name: 'Duisport',
+      type: 'Port',
+    });
+  });
+
+  it('shows the first rows and a Show all toggle for a busy node', async () => {
+    const relationships = Array.from({ length: 15 }, (_, i) => ({
+      id: `n${i}`,
+      name: `Neighbour ${i}`,
+      type: 'Person',
+      degree: 30 - i,
+      edge_type: 'knows',
+    }));
+    await render({ detail: { ...DETAIL, relationships } });
+    expect(relationshipButtons()).toHaveLength(RELATIONSHIP_PREVIEW);
+    const toggle = Array.from(container.querySelectorAll('button')).find(
+      (b) =>
+        b.textContent ===
+        'settings.sources.graphrag.view.showAll:15 {"formatted":"15"}',
+    )!;
+    await act(async () => toggle.click());
+    expect(relationshipButtons()).toHaveLength(15);
+  });
+
+  const relationshipsHeader = () =>
+    Array.from(container.querySelectorAll('h4')).find((h) =>
+      h.textContent?.startsWith('settings.sources.graphrag.view.relationships'),
+    )!;
+  const cappedNote = () =>
+    Array.from(container.querySelectorAll('p')).find((p) =>
+      p.textContent?.startsWith(
+        'settings.sources.graphrag.view.relationshipsCapped',
+      ),
+    );
+
+  // Bugs row 10: the backend caps the list; the header counts every edge and
+  // a note says the list is partial.
+  it('heads a capped list with the true total and says what it shows', async () => {
+    await render({ detail: { ...DETAIL, relationships_total: 1204 } });
+    expect(relationshipsHeader().textContent).toContain('1,204');
+    const note = cappedNote();
+    expect(note?.textContent).toBe(
+      'settings.sources.graphrag.view.relationshipsCapped:1204 {"shown":"4","total":"1,204"}',
+    );
+    expect(note?.className).toContain('text-xs');
+    expect(note?.className).toContain('text-muted-foreground');
+  });
+
+  it('adds no note when every relationship came back', async () => {
+    await render({ detail: { ...DETAIL, relationships_total: 4 } });
+    expect(relationshipsHeader().textContent).toContain('4');
+    expect(cappedNote()).toBeUndefined();
+  });
+
+  it('counts the neighbour rows when the API sends no total', async () => {
+    await render();
+    expect(relationshipsHeader().textContent).toMatch(/2$/);
+    expect(cappedNote()).toBeUndefined();
+  });
+
+  // Bugs row 8: counts in the app language, not the browser's.
+  it('formats its counts in the app language', async () => {
+    const language = i18next.language;
+    i18next.language = 'de';
+    try {
+      await render({
+        detail: { ...DETAIL, degree: 1234, doc_freq: 5678 },
+      });
+      const text = container.textContent ?? '';
+      expect(text).toContain('1.234');
+      expect(text).toContain(
+        'settings.sources.graphrag.view.chunkCount:5678 {"formatted":"5.678"}',
+      );
+    } finally {
+      i18next.language = language;
+    }
+  });
+
+  it('offers Show more only for a long description', async () => {
+    await render();
+    expect(container.textContent).not.toContain(
+      'settings.sources.graphrag.view.showMore',
+    );
+    await render({
+      detail: { ...DETAIL, description: 'Long. '.repeat(60) },
+    });
+    expect(container.textContent).toContain(
+      'settings.sources.graphrag.view.showMore',
+    );
+  });
+
+  it('shows the known name while loading, and Retry on failure', async () => {
+    await render({ detail: null, status: 'loading' });
+    expect(container.querySelector('h3')?.textContent).toBe('Nordhaven');
+    expect(container.querySelector('[aria-busy="true"]')).not.toBeNull();
+
+    const { onRetry } = await render({ detail: null, status: 'error' });
+    expect(container.querySelector('[role="alert"]')?.textContent).toContain(
+      'settings.sources.graphrag.view.nodeLoadFailed',
+    );
+    const retry = Array.from(container.querySelectorAll('button')).find(
+      (b) => b.textContent === 'retry',
+    )!;
+    await act(async () => retry.click());
+    expect(onRetry).toHaveBeenCalled();
+  });
+
+  const CHUNK_DETAIL: GraphNodeDetail = {
+    ...DETAIL,
+    chunks: [
+      {
+        chunk_id: 'c1',
+        text: '# Account brief\n\nNordhaven Logistics B.V. hauls the Rotterdam lane.',
+        metadata: {
+          source: 'inputs/local/Account_brief.md',
+          title: 'Account_brief.md',
+          token_count: 1234,
+        },
+      },
+    ],
+  };
+
+  const bodyButton = (text: string) =>
+    [...document.body.querySelectorAll('button')].find(
+      (b) => b.textContent === text,
+    ) as HTMLButtonElement | undefined;
+
+  const openTile = async () => {
+    const tile = container.querySelector(
+      '[data-slot="card"]',
+    ) as HTMLButtonElement;
+    expect(tile.tagName).toBe('BUTTON');
+    await act(async () => tile.click());
+  };
+
+  const typeDraft = async (value: string) => {
+    const field = document.body.querySelector('textarea')!;
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLTextAreaElement.prototype,
+      'value',
+    )!.set!;
+    await act(async () => {
+      setter.call(field, value);
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+  };
+
+  it('previews a tile without markdown markers', async () => {
+    await render({ detail: CHUNK_DETAIL });
+    const tile = container.querySelector('[data-slot="card"]')!;
+    expect(tile.textContent).toContain(
+      'Account brief · Nordhaven Logistics B.V. hauls the Rotterdam lane.',
+    );
+    expect(tile.textContent).not.toContain('#');
+  });
+
+  it('opens a tile in a read drawer with the entity name marked', async () => {
+    await render({ detail: CHUNK_DETAIL });
+    await openTile();
+    const dialog = document.body.querySelector('[role="dialog"]')!;
+    expect(dialog.querySelector('h2')?.textContent).toBe('Account brief');
+    expect(dialog.textContent).toContain(
+      'settings.sources.graphrag.view.chunkMeta',
+    );
+    // The body renders the heading and marks the entity's name.
+    const rendered = [...dialog.querySelectorAll('h1, h2, h3')].filter(
+      (h) => h.textContent === 'Account brief',
+    );
+    expect(rendered).toHaveLength(2);
+    expect(dialog.textContent).not.toContain('# Account brief');
+    expect(dialog.querySelector('mark')?.textContent).toBe(
+      'Nordhaven Logistics B.V.',
+    );
+  });
+
+  it('opens the file on the Files tab and closes the drawer', async () => {
+    const { onOpenInFiles, onClose } = await render({ detail: CHUNK_DETAIL });
+    await openTile();
+    await act(async () =>
+      bodyButton('settings.sources.graphrag.view.openInFiles')!.click(),
+    );
+    expect(onOpenInFiles).toHaveBeenCalledWith('inputs/local/Account_brief.md');
+    expect(document.body.querySelector('[role="dialog"]')).toBeNull();
+    // The node stays selected.
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('edits a chunk in the edit drawer, saves and refetches', async () => {
+    updateChunk.mockResolvedValue({ ok: true, status: 200 });
+    const { onChunkSaved } = await render({ detail: CHUNK_DETAIL });
+    await openTile();
+    await act(async () => bodyButton('modals.chunk.edit')!.click());
+    expect(document.body.textContent).toContain(
+      'settings.sources.graphrag.view.editChunk',
+    );
+    await typeDraft('# Account brief\n\nUpdated.');
+    await act(async () => bodyButton('modals.chunk.save')!.click());
+    expect(updateChunk).toHaveBeenCalledWith(
+      {
+        id: 'doc',
+        chunk_id: 'c1',
+        text: '# Account brief\n\nUpdated.',
+        metadata: { title: 'Account_brief.md' },
+      },
+      'tok',
+    );
+    expect(onChunkSaved).toHaveBeenCalled();
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payload: expect.objectContaining({ variant: 'success' }),
+      }),
+    );
+    expect(document.body.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  it('keeps the edit drawer open with an alert when the save fails', async () => {
+    updateChunk.mockResolvedValue({ ok: false, status: 500 });
+    const { onChunkSaved } = await render({ detail: CHUNK_DETAIL });
+    await openTile();
+    await act(async () => bodyButton('modals.chunk.edit')!.click());
+    await typeDraft('Changed');
+    await act(async () => bodyButton('modals.chunk.save')!.click());
+    const dialog = document.body.querySelector('[role="dialog"]')!;
+    expect(dialog.querySelector('[role="alert"]')?.textContent).toBe(
+      'settings.sources.chunkErrors.save',
+    );
+    expect(document.body.querySelector('textarea')?.value).toBe('Changed');
+    expect(onChunkSaved).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the overview links when the detail has no relationships', async () => {
+    const overview = {
+      nodes: [
+        {
+          id: 'nord',
+          name: 'Nordhaven Logistics B.V.',
+          type: 'Company',
+          degree: 2,
+        },
+        { id: 'duisport', name: 'Duisport', type: 'Port', degree: 7 },
+        { id: 'marta', name: 'Marta Keller', type: 'Person', degree: 3 },
+        { id: 'far', name: 'Far away', type: 'Port', degree: 1 },
+      ],
+      links: [
+        { source: 'nord', target: 'duisport', type: 'SHIPS_VIA' },
+        { source: 'marta', target: 'nord', type: 'manages' },
+        { source: 'marta', target: 'far', type: 'visits' },
+      ],
+    };
+    await render({
+      detail: { ...DETAIL, relationships: undefined },
+      overview,
+    });
+    const rows = relationshipButtons();
+    expect(rows.map((row) => row.textContent)).toEqual([
+      'Duisportships via',
+      'Marta Kellermanages',
+    ]);
+    expect(container.textContent).not.toContain(
+      'settings.sources.graphrag.view.noRelationships',
+    );
+
+    await render({ detail: { ...DETAIL, relationships: undefined } });
+    expect(container.textContent).toContain(
+      'settings.sources.graphrag.view.noRelationships',
+    );
+  });
+});
diff --git a/frontend/src/components/graph/GraphNodePanel.tsx b/frontend/src/components/graph/GraphNodePanel.tsx
new file mode 100644
index 00000000..ac92a17e
--- /dev/null
+++ b/frontend/src/components/graph/GraphNodePanel.tsx
@@ -0,0 +1,419 @@
+import { File, X } from 'lucide-react';
+import { useMemo, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import { cn } from '@/lib/utils';
+
+import { Button } from '../ui/button';
+import { Card, CardFooter } from '../ui/card';
+import { DescriptionItem, DescriptionList } from '../ui/description-list';
+import { EmptyState } from '../ui/empty-state';
+import { IconButton } from '../ui/icon-button';
+import { ListRow } from '../ui/list-row';
+import { SectionHeader } from '../ui/section-header';
+import { Separator } from '../ui/separator';
+import { Skeleton } from '../ui/skeleton';
+import { formatCount } from '../../utils/dateTimeUtils';
+import { chunkPreviewText } from '../chunkUtils';
+import {
+  groupRelationships,
+  type ForceGraphData,
+  type GraphNodeChunk,
+  type GraphNodeDetail,
+  type FoldedGraphTypes,
+} from '../graphViewUtils';
+import GraphChunkSheet from './GraphChunkSheet';
+import {
+  chunkFileName,
+  overviewRelationships,
+  relationshipLabelText,
+} from './graphCanvasUtils';
+import { GraphTypeBadge, GraphTypeDot } from './GraphTypeDot';
+import type { GraphNodeDetailStatus } from './useGraphNodeDetail';
+
+/** What the views know about a node before its detail loads. */
+export interface GraphNodeRef {
+  id: string;
+  name: string;
+  type?: string | null;
+}
+
+/** Relationship rows shown before "Show all". */
+export const RELATIONSHIP_PREVIEW = 12;
+/** A description longer than this gets a Show more toggle. */
+const LONG_DESCRIPTION = 240;
+
+interface GraphNodePanelProps {
+  /** The source id (a chunk edit saves against it). */
+  docId: string;
+  node: GraphNodeRef;
+  detail: GraphNodeDetail | null;
+  status: GraphNodeDetailStatus;
+  onRetry: () => void;
+  fold: FoldedGraphTypes;
+  onClose: () => void;
+  /**
+   * Draw the panel's own close X. Off in the phone bottom sheet, whose
+   * handle means no X (the scrim closes it).
+   */
+  showClose?: boolean;
+  /** Select another node (a relationship row). */
+  onSelectNode: (node: GraphNodeRef) => void;
+  /** An extra control under the type badge ("Show in graph"). */
+  action?: ReactNode;
+  /**
+   * The loaded overview: its links around the node stand in for the
+   * relationships when the detail has none (an API that predates them).
+   */
+  overview?: ForceGraphData;
+  /** Show a chunk's file on the Files tab (the chunk drawer's "Open in Files"). */
+  onOpenInFiles?: (path: string) => void;
+  /** Refetch the detail after a chunk edit, keeping it on screen. */
+  onChunkSaved?: () => void;
+}
+
+/**
+ * The node panel docked in a graph frame, the Graph tab's canvas and the
+ * Entities table alike: a `border-l` column at 320px, 40% of the frame from
+ * `xl` (capped at the 576px detail-drawer width), so the relationship list has
+ * room once the screen does.
+ */
+export function GraphNodePanelDock({ children }: { children: ReactNode }) {
+  return (
+    <aside className="border-border flex w-80 shrink-0 flex-col border-l xl:w-2/5 xl:max-w-xl">
+      {children}
+    </aside>
+  );
+}
+
+/**
+ * One entity's panel: its facts, the relationships you can follow, then the
+ * chunks it was extracted from. Docked beside the canvas or the entity table
+ * on desktop, in a bottom sheet on a phone. Key it on the node id so the
+ * disclosures reset per node.
+ */
+export default function GraphNodePanel({
+  docId,
+  node,
+  detail,
+  status,
+  onRetry,
+  fold,
+  onClose,
+  showClose = true,
+  onSelectNode,
+  action,
+  overview,
+  onOpenInFiles,
+  onChunkSaved,
+}: GraphNodePanelProps) {
+  const { t } = useTranslation();
+  const name = detail?.name ?? node.name;
+  const type = detail ? detail.type : node.type;
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex items-start gap-3 px-4 py-3">
+        <div className="flex min-w-0 flex-1 flex-col gap-3">
+          <div className="flex flex-col gap-1.5">
+            <SectionHeader
+              as="h3"
+              size="xs"
+              className="wrap-break-word"
+              title={name}
+            />
+            <GraphTypeBadge fold={fold} type={type} />
+          </div>
+          {action ? <div>{action}</div> : null}
+        </div>
+        {showClose ? (
+          <IconButton
+            variant="ghost-muted"
+            size="icon-sm"
+            className="shrink-0"
+            onClick={onClose}
+            label={t('settings.sources.graphrag.view.close')}
+            icon={X}
+            side="bottom"
+          />
+        ) : null}
+      </div>
+      <Separator />
+      <div className="scrollbar-overlay flex min-h-0 flex-1 flex-col gap-6 overflow-y-auto p-4">
+        {status === 'error' ? (
+          <EmptyState
+            size="sm"
+            tone="destructive"
+            illustration="none"
+            title={t('settings.sources.graphrag.view.nodeLoadFailed')}
+            action={
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                shape="pill"
+                onClick={onRetry}
+              >
+                {t('retry')}
+              </Button>
+            }
+          />
+        ) : detail && status === 'ready' ? (
+          <NodeDetailBody
+            docId={docId}
+            detail={detail}
+            fold={fold}
+            onSelectNode={onSelectNode}
+            overview={overview}
+            onOpenInFiles={onOpenInFiles}
+            onChunkSaved={onChunkSaved}
+          />
+        ) : (
+          <div
+            className="flex flex-col gap-3"
+            aria-busy="true"
+            aria-label={t('settings.sources.graphrag.view.loadingNode')}
+          >
+            <Skeleton className="h-3 w-1/2" />
+            <Skeleton className="h-3 w-2/5" />
+            <Skeleton className="mt-3 h-3 w-full" />
+            <Skeleton className="h-3 w-5/6" />
+            <Skeleton className="h-3 w-3/4" />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function NodeDetailBody({
+  docId,
+  detail,
+  fold,
+  onSelectNode,
+  overview,
+  onOpenInFiles,
+  onChunkSaved,
+}: {
+  docId: string;
+  detail: GraphNodeDetail;
+  fold: FoldedGraphTypes;
+  onSelectNode: (node: GraphNodeRef) => void;
+  overview?: ForceGraphData;
+  onOpenInFiles?: (path: string) => void;
+  onChunkSaved?: () => void;
+}) {
+  const { t } = useTranslation();
+  const [descriptionOpen, setDescriptionOpen] = useState(false);
+  const [allRelationships, setAllRelationships] = useState(false);
+  const [openChunk, setOpenChunk] = useState<GraphNodeChunk | null>(null);
+  const rows = useMemo(
+    () =>
+      groupRelationships(
+        detail.relationships ??
+          (overview
+            ? overviewRelationships(detail.id, overview.links, overview.nodes)
+            : []),
+      ),
+    [detail.relationships, detail.id, overview],
+  );
+  const mentions = detail.doc_freq ?? detail.chunks.length;
+  // The list is capped server-side; the total counts every edge.
+  const returned = detail.relationships?.length ?? 0;
+  const relationshipsTotal = detail.relationships_total ?? rows.length;
+  const capped =
+    detail.relationships_total !== undefined &&
+    detail.relationships_total > returned;
+  const shownRows = allRelationships
+    ? rows
+    : rows.slice(0, RELATIONSHIP_PREVIEW);
+  const description = (detail.description ?? '').trim();
+  const relatedTo = t('settings.sources.graphrag.view.relatedTo');
+
+  return (
+    <>
+      <DescriptionList size="xs">
+        <DescriptionItem
+          label={t('settings.sources.graphrag.view.connections')}
+        >
+          <span className="tabular-nums">{formatCount(detail.degree)}</span>
+        </DescriptionItem>
+        <DescriptionItem
+          label={t('settings.sources.graphrag.view.mentionedIn')}
+        >
+          <span className="tabular-nums">
+            {t('settings.sources.graphrag.view.chunkCount', {
+              count: mentions,
+              formatted: formatCount(mentions),
+            })}
+          </span>
+        </DescriptionItem>
+      </DescriptionList>
+
+      {description ? (
+        <div className="flex flex-col gap-1">
+          <p
+            className={cn(
+              'text-muted-foreground text-sm leading-relaxed wrap-break-word',
+              !descriptionOpen && 'line-clamp-4',
+            )}
+          >
+            {description}
+          </p>
+          {description.length > LONG_DESCRIPTION ? (
+            <Button
+              type="button"
+              variant="link"
+              size="sm"
+              className="-ml-3 w-fit justify-start"
+              aria-expanded={descriptionOpen}
+              onClick={() => setDescriptionOpen((open) => !open)}
+            >
+              {descriptionOpen
+                ? t('settings.sources.graphrag.view.showLess')
+                : t('settings.sources.graphrag.view.showMore')}
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+
+      <section className="flex flex-col gap-2">
+        <SectionHeader
+          as="h4"
+          size="xs"
+          title={
+            <>
+              {t('settings.sources.graphrag.view.relationships')}{' '}
+              <span className="text-muted-foreground font-normal tabular-nums">
+                {formatCount(relationshipsTotal)}
+              </span>
+            </>
+          }
+        />
+        {rows.length === 0 ? (
+          <p className="text-muted-foreground text-xs">
+            {t('settings.sources.graphrag.view.noRelationships')}
+          </p>
+        ) : (
+          <ul className="-mx-2 flex flex-col">
+            {shownRows.map((row) => {
+              const labels = relationshipLabelText(row.labels, relatedTo);
+              return (
+                <ListRow
+                  key={row.id}
+                  interactive
+                  asChild
+                  size="sm"
+                  leading={
+                    <GraphTypeDot
+                      fold={fold}
+                      type={row.type}
+                      className="mt-1.5"
+                    />
+                  }
+                  title={<span title={row.name}>{row.name}</span>}
+                  description={<span title={labels}>{labels}</span>}
+                >
+                  <button
+                    type="button"
+                    onClick={() =>
+                      onSelectNode({
+                        id: row.id,
+                        name: row.name,
+                        type: row.type,
+                      })
+                    }
+                  />
+                </ListRow>
+              );
+            })}
+          </ul>
+        )}
+        {rows.length > RELATIONSHIP_PREVIEW ? (
+          <Button
+            type="button"
+            variant="link"
+            size="sm"
+            className="-ml-3 w-fit justify-start"
+            aria-expanded={allRelationships}
+            onClick={() => setAllRelationships((open) => !open)}
+          >
+            {allRelationships
+              ? t('settings.sources.graphrag.view.showFewer')
+              : t('settings.sources.graphrag.view.showAll', {
+                  count: rows.length,
+                  formatted: formatCount(rows.length),
+                })}
+          </Button>
+        ) : null}
+        {capped ? (
+          <p className="text-muted-foreground text-xs">
+            {t('settings.sources.graphrag.view.relationshipsCapped', {
+              count: relationshipsTotal,
+              shown: formatCount(returned),
+              total: formatCount(relationshipsTotal),
+            })}
+          </p>
+        ) : null}
+      </section>
+
+      <section className="flex flex-col gap-2">
+        <SectionHeader
+          as="h4"
+          size="xs"
+          title={
+            <>
+              {t('settings.sources.graphrag.view.sourceChunks')}{' '}
+              <span className="text-muted-foreground font-normal tabular-nums">
+                {formatCount(detail.chunks.length)}
+              </span>
+            </>
+          }
+        />
+        {detail.chunks.length === 0 ? (
+          <p className="text-muted-foreground text-xs">
+            {t('settings.sources.graphrag.view.noChunks')}
+          </p>
+        ) : (
+          <div className="flex flex-col gap-2">
+            {detail.chunks.map((chunk) => {
+              const file = chunkFileName(chunk.metadata);
+              return (
+                <Card
+                  key={chunk.chunk_id}
+                  variant="filled"
+                  padding="sm"
+                  interactive
+                  className="gap-2 text-left"
+                  asChild
+                >
+                  <button type="button" onClick={() => setOpenChunk(chunk)}>
+                    <p className="text-foreground line-clamp-3 text-xs leading-relaxed wrap-break-word">
+                      {chunkPreviewText(chunk.text)}
+                    </p>
+                    {file ? (
+                      <CardFooter className="min-w-0 gap-1.5">
+                        <File className="size-3 shrink-0" aria-hidden="true" />
+                        <span className="truncate" title={file}>
+                          {file}
+                        </span>
+                      </CardFooter>
+                    ) : null}
+                  </button>
+                </Card>
+              );
+            })}
+          </div>
+        )}
+      </section>
+
+      <GraphChunkSheet
+        docId={docId}
+        chunk={openChunk}
+        highlight={detail.name}
+        onClose={() => setOpenChunk(null)}
+        onOpenInFiles={onOpenInFiles}
+        onSaved={onChunkSaved}
+      />
+    </>
+  );
+}
diff --git a/frontend/src/components/graph/GraphSourceView.test.tsx b/frontend/src/components/graph/GraphSourceView.test.tsx
new file mode 100644
index 00000000..87da9a5f
--- /dev/null
+++ b/frontend/src/components/graph/GraphSourceView.test.tsx
@@ -0,0 +1,573 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) => {
+      // The header totals: plural keys joined by the stats key.
+      if (key === 'settings.sources.graphrag.view.stats' && opts) {
+        return `${opts.entities} · ${opts.relationships}`;
+      }
+      if (key === 'settings.sources.graphrag.view.entityCount' && opts) {
+        return `${opts.formatted} ${opts.count === 1 ? 'entity' : 'entities'}`;
+      }
+      if (key === 'settings.sources.graphrag.view.relationshipCount' && opts) {
+        return `${opts.formatted} ${opts.count === 1 ? 'relationship' : 'relationships'}`;
+      }
+      return opts && 'count' in opts ? `${key}:${opts.count}` : key;
+    },
+  }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => null,
+  useDispatch: () => vi.fn(),
+}));
+
+vi.mock('../../hooks', () => ({
+  useDebouncedValue: (value: unknown) => value,
+  useMediaQuery: () => ({ isMobile: false, isDesktop: true }),
+}));
+
+// The canvas can't render in the DOM test environment.
+vi.mock('react-force-graph-2d', () => ({
+  default: () => <canvas data-testid="force-graph" />,
+}));
+
+vi.mock('../FileTree', async () => {
+  const { createPortal } = await import('react-dom');
+  const { useEffect } = await import('react');
+  return {
+    default: (props: {
+      embedded?: boolean;
+      initialPath?: string;
+      actionsTarget?: HTMLElement | null;
+      onCrumbsChange?: (crumbs: { label: string }[]) => void;
+    }) => {
+      const { onCrumbsChange } = props;
+      useEffect(() => {
+        onCrumbsChange?.([{ label: 'Key Accounts' }, { label: 'carriers' }]);
+      }, [onCrumbsChange]);
+      return (
+        <div
+          data-testid="file-tree"
+          data-initial-path={props.initialPath ?? ''}
+        >
+          {props.embedded ? 'embedded' : 'page'}
+          {props.actionsTarget
+            ? createPortal(
+                <button type="button">ADD FILE</button>,
+                props.actionsTarget,
+              )
+            : null}
+        </div>
+      );
+    },
+  };
+});
+// The embedded chunk list of a source with no folder structure; its "open
+// chunk" button reports position 2 like the real list does.
+vi.mock('../Chunks', async () => {
+  const { useEffect, useState } = await import('react');
+  return {
+    default: (props: {
+      embedded?: boolean;
+      documentId: string;
+      onOpenChunkChange?: (position: number | null) => void;
+      controllerRef?: { current: { closeChunk: () => boolean } | null };
+    }) => {
+      const [open, setOpen] = useState(false);
+      const { onOpenChunkChange, controllerRef } = props;
+      useEffect(() => {
+        onOpenChunkChange?.(open ? 2 : null);
+      }, [open, onOpenChunkChange]);
+      if (controllerRef) {
+        controllerRef.current = {
+          closeChunk: () => {
+            setOpen(false);
+            return false;
+          },
+        };
+      }
+      return (
+        <div data-testid="chunks" data-doc={props.documentId}>
+          {props.embedded ? 'embedded' : 'page'}
+          <button type="button" onClick={() => setOpen(true)}>
+            OPEN CHUNK
+          </button>
+        </div>
+      );
+    },
+  };
+});
+vi.mock('../ConnectorTree', () => ({
+  default: () => <div data-testid="connector-tree" />,
+}));
+
+vi.mock('../../api/services/userService', () => ({
+  default: {
+    getSourceGraph: vi.fn(),
+    getSourceGraphNodes: vi.fn(),
+    getSourceGraphNode: vi.fn(),
+  },
+}));
+
+import i18next from 'i18next';
+
+import userService from '../../api/services/userService';
+import GraphSourceView from './GraphSourceView';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const service = userService as unknown as {
+  getSourceGraph: ReturnType<typeof vi.fn>;
+  getSourceGraphNodes: ReturnType<typeof vi.fn>;
+  getSourceGraphNode: ReturnType<typeof vi.fn>;
+};
+
+const ok = (body: unknown) => ({
+  ok: true,
+  status: 200,
+  json: async () => body,
+});
+const failed = () => ({ ok: false, status: 400, json: async () => ({}) });
+
+const OVERVIEW = {
+  nodes: [
+    { id: 'a', name: 'Anneke de Vries', type: 'Person', degree: 5 },
+    { id: 'b', name: 'Bram', type: 'PERSON', degree: 3 },
+    { id: 'n', name: 'Nordhaven', type: 'Company', degree: 9 },
+  ],
+  edges: [
+    { source: 'a', target: 'n', type: 'manages' },
+    { source: 'b', target: 'n', type: 'works_for' },
+  ],
+  stats: { nodes: 371, edges: 1172 },
+};
+
+const flush = async () => {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+};
+
+describe('GraphSourceView', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    service.getSourceGraph.mockReset();
+    service.getSourceGraphNodes.mockReset();
+    service.getSourceGraphNode.mockReset();
+    service.getSourceGraph.mockResolvedValue(ok(OVERVIEW));
+    service.getSourceGraphNodes.mockResolvedValue(
+      ok({
+        nodes: [
+          {
+            id: 'n',
+            name: 'Nordhaven',
+            type: 'Company',
+            degree: 9,
+            doc_freq: 4,
+          },
+        ],
+        total: 1,
+        page: 1,
+        per_page: 25,
+        types: [{ key: 'company', label: 'Company', count: 1 }],
+      }),
+    );
+    service.getSourceGraphNode.mockResolvedValue(
+      ok({
+        node: {
+          id: 'n',
+          name: 'Nordhaven',
+          type: 'Company',
+          degree: 9,
+          doc_freq: 4,
+          relationships: [],
+          chunks: [],
+        },
+      }),
+    );
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (
+    sourceType?: string,
+    onBack = vi.fn(),
+    isNested?: boolean,
+  ) => {
+    await act(async () => {
+      root.render(
+        <GraphSourceView
+          docId="doc"
+          sourceName="Key Accounts"
+          sourceType={sourceType}
+          isNested={isNested}
+          onBackToDocuments={onBack}
+          headerAction={<button type="button">Test retrieval</button>}
+        />,
+      );
+    });
+    await flush();
+  };
+
+  const buttonByText = (text: string) =>
+    Array.from(container.querySelectorAll('button')).find(
+      (b) => b.textContent?.trim() === text,
+    );
+
+  const openTab = async (label: string) => {
+    const tab = Array.from(container.querySelectorAll('[role="tab"]')).find(
+      (b) => b.textContent === label,
+    ) as HTMLButtonElement;
+    await act(async () => {
+      tab.dispatchEvent(
+        new MouseEvent('mousedown', { bubbles: true, button: 0 }),
+      );
+    });
+    await flush();
+  };
+
+  // Bugs row 8: the app language's separators, not the browser's.
+  it('formats the graph totals in the app language', async () => {
+    const language = i18next.language;
+    i18next.language = 'de';
+    try {
+      await render();
+      expect(container.textContent).toContain(
+        '371 entities · 1.172 relationships',
+      );
+    } finally {
+      i18next.language = language;
+    }
+  });
+
+  it('pluralises the graph totals by the raw counts', async () => {
+    service.getSourceGraph.mockResolvedValue(
+      ok({ ...OVERVIEW, stats: { nodes: 1, edges: 1 } }),
+    );
+    await render();
+    expect(container.textContent).toContain('1 entity · 1 relationship');
+  });
+
+  it('heads the view with the whole graph totals and the kind badge', async () => {
+    await render();
+    const text = container.textContent ?? '';
+    expect(text).toContain('Key Accounts');
+    expect(text).toContain('settings.sources.graphrag.view.title');
+    expect(text).toContain(
+      `${(371).toLocaleString()} entities · ${(1172).toLocaleString()} relationships`,
+    );
+    expect(buttonByText('Test retrieval')).toBeDefined();
+    expect(service.getSourceGraph).toHaveBeenCalledWith('doc', null, 100);
+  });
+
+  const crumbs = () =>
+    Array.from(container.querySelectorAll('[data-slot="breadcrumb-item"]')).map(
+      (el) => el.textContent,
+    );
+
+  it('crumbs: Sources › the source; the Files tab adds where the tree is', async () => {
+    const onBack = vi.fn();
+    await render(undefined, onBack);
+    expect(crumbs()).toEqual(['settings.sources.label', 'Key Accounts']);
+    expect(container.querySelector('.lucide-arrow-left')).toBeNull();
+
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    expect(crumbs()).toEqual([
+      'settings.sources.label',
+      'Key Accounts',
+      'carriers',
+    ]);
+
+    await openTab('settings.sources.graphrag.view.tabs.graph');
+    expect(crumbs()).toEqual(['settings.sources.label', 'Key Accounts']);
+
+    const sources = container.querySelector<HTMLButtonElement>(
+      '[data-slot="breadcrumb-link"]',
+    )!;
+    await act(async () => sources.click());
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
+
+  it('builds the legend from one fold of the loaded types', async () => {
+    await render();
+    const legend = container.querySelector(
+      '[aria-label="settings.sources.graphrag.view.typeFilter"]',
+    )!;
+    const items = Array.from(legend.querySelectorAll('button')).map(
+      (b) => b.textContent,
+    );
+    // "Person" and "PERSON" fold into one group.
+    expect(items).toEqual(['Person2', 'Company1']);
+    // xs groups sit in a muted track (DESIGN.md ToggleGroup).
+    expect(legend.parentElement!.className).toContain('bg-muted');
+  });
+
+  it('reads "Show top [50 | 100 | 250] by connections" at one size, the track holding only the group', async () => {
+    await render();
+    const limits = buttonByText('100')!.closest('[role="radiogroup"]')!;
+    const track = limits.parentElement!;
+    expect(track.className).toContain('bg-muted');
+    expect(track.textContent).not.toContain(
+      'settings.sources.graphrag.view.showTop',
+    );
+    const label = Array.from(container.querySelectorAll('span')).find(
+      (el) => el.textContent === 'settings.sources.graphrag.view.showTop',
+    )!;
+    expect(label.className).toContain('text-sm');
+    expect(label.className).not.toContain('text-xs');
+  });
+
+  it('refetches the overview with the chosen size', async () => {
+    await render();
+    await act(async () => buttonByText('250')!.click());
+    await flush();
+    expect(service.getSourceGraph).toHaveBeenLastCalledWith('doc', null, 250);
+  });
+
+  it('shows the empty state for a graph with no entities', async () => {
+    service.getSourceGraph.mockResolvedValue(
+      ok({ nodes: [], edges: [], stats: { nodes: 0, edges: 0 } }),
+    );
+    await render();
+    expect(container.textContent).toContain(
+      'settings.sources.graphrag.view.empty',
+    );
+    expect(container.querySelector('[data-testid="force-graph"]')).toBeNull();
+  });
+
+  it('shows a retry when the overview fails', async () => {
+    service.getSourceGraph.mockResolvedValueOnce(failed());
+    await render();
+    expect(container.querySelector('[role="alert"]')?.textContent).toContain(
+      'settings.sources.graphrag.view.loadFailed',
+    );
+    await act(async () => buttonByText('retry')!.click());
+    await flush();
+    expect(service.getSourceGraph).toHaveBeenCalledTimes(2);
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it('opens an entity from the table and shows it in the graph', async () => {
+    await render();
+    await openTab('settings.sources.graphrag.view.tabs.entities');
+    expect(service.getSourceGraphNodes).toHaveBeenCalledWith(
+      'doc',
+      { q: undefined, type: undefined, page: 1, perPage: 25 },
+      null,
+    );
+    const row = Array.from(container.querySelectorAll('tbody tr')).find((r) =>
+      r.textContent?.includes('Nordhaven'),
+    ) as HTMLTableRowElement;
+    expect(row.textContent).toContain('Company');
+    await act(async () => row.click());
+    await flush();
+    expect(service.getSourceGraphNode).toHaveBeenCalledWith('doc', 'n', null);
+
+    // One frame, as on the Graph tab: the table and the panel docked beside
+    // it (border-l, 40% from xl), the open entity's row marked.
+    const openRow = Array.from(container.querySelectorAll('tbody tr')).find(
+      (r) => r.textContent?.includes('Nordhaven'),
+    ) as HTMLTableRowElement;
+    expect(openRow.getAttribute('aria-current')).toBe('true');
+    const frame = openRow.closest('[data-slot="card"]')!;
+    expect(frame.getAttribute('data-variant')).toBe('subtle');
+    expect(frame.className).toContain('h-[70svh]');
+    const dock = frame.querySelector('aside')!;
+    expect(dock.className).toContain('border-l');
+    expect(dock.className).toContain('xl:w-2/5');
+    expect(dock.querySelector('h3')?.textContent).toBe('Nordhaven');
+    expect(container.querySelector('[data-slot="table-container"]')).toBeNull();
+    const close = dock.querySelector(
+      'button[aria-label="settings.sources.graphrag.view.close"]',
+    )!;
+    expect(close.getAttribute('data-size')).toBe('icon-sm');
+
+    await act(async () =>
+      buttonByText('settings.sources.graphrag.view.showInGraph')!.click(),
+    );
+    await flush();
+    const graphTab = Array.from(
+      container.querySelectorAll('[role="tab"]'),
+    ).find(
+      (b) => b.textContent === 'settings.sources.graphrag.view.tabs.graph',
+    )!;
+    expect(graphTab.getAttribute('aria-selected')).toBe('true');
+    // The graph tab's docked panel has the node open.
+    expect(container.querySelector('aside h3')?.textContent).toBe('Nordhaven');
+  });
+
+  it('renders the embedded file view on the Files tab', async () => {
+    await render();
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    expect(
+      container.querySelector('[data-testid="file-tree"]')?.textContent,
+    ).toBe('embedded');
+  });
+
+  it("puts the Files tab's action in the header, only on that tab", async () => {
+    await render();
+    const addFile = () =>
+      Array.from(container.querySelectorAll('button')).find(
+        (b) => b.textContent === 'ADD FILE',
+      );
+    expect(addFile()).toBeUndefined();
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    const button = addFile();
+    expect(button).toBeDefined();
+    // It sits in the header, above the tab list, not inside the Files panel.
+    const tabList = container.querySelector('[role="tablist"]')!;
+    expect(
+      button!.compareDocumentPosition(tabList) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(
+      container.querySelector('[data-testid="file-tree"]')?.contains(button!),
+    ).toBe(false);
+    await openTab('settings.sources.graphrag.view.tabs.graph');
+    expect(addFile()).toBeUndefined();
+  });
+
+  // A source with no directory structure (one uploaded file) shows its chunk
+  // list, as the plain source view does.
+  it('shows the embedded chunk list on the Files tab of a flat source', async () => {
+    await render(undefined, vi.fn(), false);
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    const chunks = container.querySelector('[data-testid="chunks"]');
+    expect(chunks?.textContent).toContain('embedded');
+    expect(chunks?.getAttribute('data-doc')).toBe('doc');
+    expect(container.querySelector('[data-testid="file-tree"]')).toBeNull();
+    expect(crumbs()).toEqual(['settings.sources.label', 'Key Accounts']);
+
+    // An open chunk adds its crumb; the source crumb closes it.
+    await act(async () => buttonByText('OPEN CHUNK')!.click());
+    expect(crumbs()).toEqual([
+      'settings.sources.label',
+      'Key Accounts',
+      'settings.sources.chunkCrumb',
+    ]);
+    const source = Array.from(
+      container.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="breadcrumb-link"]',
+      ),
+    ).find((b) => b.textContent === 'Key Accounts')!;
+    await act(async () => source.click());
+    expect(crumbs()).toEqual(['settings.sources.label', 'Key Accounts']);
+  });
+
+  it('uses the connector tree for a connector source', async () => {
+    await render('connector:file');
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    expect(
+      container.querySelector('[data-testid="connector-tree"]'),
+    ).not.toBeNull();
+  });
+
+  it("opens a chunk's file on the Files tab from the chunk drawer", async () => {
+    service.getSourceGraphNode.mockResolvedValue(
+      ok({
+        node: {
+          id: 'n',
+          name: 'Nordhaven',
+          type: 'Company',
+          degree: 9,
+          relationships: [],
+          chunks: [
+            {
+              chunk_id: 'c1',
+              text: 'Nordhaven runs the lane.',
+              metadata: { source: 'briefs/Nordhaven.md' },
+            },
+          ],
+        },
+      }),
+    );
+    await render();
+    await openTab('settings.sources.graphrag.view.tabs.entities');
+    const row = Array.from(container.querySelectorAll('tbody tr')).find((r) =>
+      r.textContent?.includes('Nordhaven'),
+    ) as HTMLTableRowElement;
+    await act(async () => row.click());
+    await flush();
+    const tile = Array.from(
+      container.querySelectorAll('button[data-slot="card"]'),
+    ).find((b) =>
+      b.textContent?.includes('Nordhaven runs the lane.'),
+    ) as HTMLButtonElement;
+    await act(async () => tile.click());
+    const openInFiles = Array.from(
+      document.body.querySelectorAll('button'),
+    ).find(
+      (b) => b.textContent === 'settings.sources.graphrag.view.openInFiles',
+    )!;
+    await act(async () => openInFiles.click());
+    await flush();
+
+    const filesTab = Array.from(
+      container.querySelectorAll('[role="tab"]'),
+    ).find(
+      (b) => b.textContent === 'settings.sources.graphrag.view.tabs.files',
+    )!;
+    expect(filesTab.getAttribute('aria-selected')).toBe('true');
+    expect(
+      container
+        .querySelector('[data-testid="file-tree"]')
+        ?.getAttribute('data-initial-path'),
+    ).toBe('briefs/Nordhaven.md');
+
+    // The request is one-off: a later visit opens the tree at its root.
+    await openTab('settings.sources.graphrag.view.tabs.entities');
+    await openTab('settings.sources.graphrag.view.tabs.files');
+    expect(
+      container
+        .querySelector('[data-testid="file-tree"]')
+        ?.getAttribute('data-initial-path'),
+    ).toBe('');
+  });
+
+  it('a new entity filter fetches page 1 once, not the old page first', async () => {
+    service.getSourceGraphNodes.mockImplementation(async () =>
+      ok({
+        nodes: [{ id: 'n', name: 'Nordhaven', type: 'Company', degree: 9 }],
+        total: 60,
+        types: [{ type: 'Company', count: 60 }],
+      }),
+    );
+    await render();
+    await openTab('settings.sources.graphrag.view.tabs.entities');
+    const next = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="pagination.nextPage"]',
+    )!;
+    await act(async () => next.click());
+    await flush();
+    expect(service.getSourceGraphNodes.mock.lastCall![1].page).toBe(2);
+    service.getSourceGraphNodes.mockClear();
+
+    const search = container.querySelector<HTMLInputElement>(
+      '[role="tabpanel"][data-state="active"] input',
+    )!;
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      'value',
+    )!.set!;
+    await act(async () => {
+      setter.call(search, 'nord');
+      search.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await flush();
+    const pages = service.getSourceGraphNodes.mock.calls.map(
+      (call) => call[1].page,
+    );
+    expect(pages).toEqual([1]);
+  });
+});
diff --git a/frontend/src/components/graph/GraphSourceView.tsx b/frontend/src/components/graph/GraphSourceView.tsx
new file mode 100644
index 00000000..53816b1d
--- /dev/null
+++ b/frontend/src/components/graph/GraphSourceView.tsx
@@ -0,0 +1,293 @@
+import { Waypoints } from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+import { useSelector } from 'react-redux';
+
+import userService from '../../api/services/userService';
+import { selectToken } from '../../preferences/preferenceSlice';
+import { formatCount } from '../../utils/dateTimeUtils';
+import Chunks, { type ChunksController } from '../Chunks';
+import ConnectorTree from '../ConnectorTree';
+import FileTree from '../FileTree';
+import GraphView, { type GraphLoadStatus } from '../GraphView';
+import PathHeader, { type Crumb } from '../tree/PathHeader';
+import { Badge } from '../ui/badge';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs';
+import {
+  foldGraphTypes,
+  toForceGraphData,
+  type ForceGraphData,
+  type GraphStats,
+} from '../graphViewUtils';
+import GraphEntities from './GraphEntities';
+import type { GraphNodeRef } from './GraphNodePanel';
+
+const DEFAULT_LIMIT = 100;
+
+type GraphTab = 'graph' | 'entities' | 'files';
+
+interface GraphSourceViewProps {
+  docId: string;
+  sourceName: string;
+  /** The source's `type`; `connector:file` sources browse as a connector tree. */
+  sourceType?: string;
+  /**
+   * Whether the source has a folder structure (`bool(directory_structure)`).
+   * Without one the Files tab shows the chunk list, as the plain source view
+   * does. Defaults to true.
+   */
+  isNested?: boolean;
+  onBackToDocuments: () => void;
+  /** Extra header control (Test retrieval), right-aligned in the title row. */
+  headerAction?: ReactNode;
+}
+
+/**
+ * A knowledge-graph source: the header (source name, the Knowledge graph
+ * badge, the whole graph's totals) over three tabs, Graph (the canvas),
+ * Entities (a searchable table) and Files (the ordinary file view). The
+ * overview is fetched here so the header, the canvas and the entity list
+ * share one fold of the types, and so one type has one colour everywhere.
+ */
+export default function GraphSourceView({
+  docId,
+  sourceName,
+  sourceType,
+  isNested = true,
+  onBackToDocuments,
+  headerAction,
+}: GraphSourceViewProps) {
+  const { t } = useTranslation();
+  const token = useSelector(selectToken);
+
+  const [tab, setTab] = useState<GraphTab>('graph');
+  const [limit, setLimit] = useState(DEFAULT_LIMIT);
+  const [data, setData] = useState<ForceGraphData>({ nodes: [], links: [] });
+  const [stats, setStats] = useState<GraphStats | null>(null);
+  const [status, setStatus] = useState<GraphLoadStatus>('loading');
+  const [attempt, setAttempt] = useState(0);
+  const [selected, setSelected] = useState<GraphNodeRef | null>(null);
+  // The file a chunk drawer's "Open in Files" asked the Files tab to open.
+  const [filesPath, setFilesPath] = useState<string | undefined>(undefined);
+  // Where the Files tab's tree is (the source, folders, file, chunk); the
+  // header shows it while that tab is open.
+  const [filesCrumbs, setFilesCrumbs] = useState<Crumb[]>([]);
+  // A flat source's open chunk (its crumb), reported by the chunk list.
+  const [openChunkPosition, setOpenChunkPosition] = useState<number | null>(
+    null,
+  );
+  const chunksControllerRef = useRef<ChunksController | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setStatus('loading');
+    userService
+      .getSourceGraph(docId, token, limit)
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
+      .then((body) => {
+        if (cancelled) return;
+        const nodes = body?.nodes ?? [];
+        const edges = body?.edges ?? [];
+        setData(toForceGraphData({ nodes, edges }));
+        setStats(body?.stats ?? { nodes: nodes.length, edges: edges.length });
+        setStatus('ready');
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        console.error('Error loading graph:', error);
+        setStatus('error');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [docId, token, limit, attempt]);
+
+  const fold = useMemo(() => foldGraphTypes(data.nodes), [data.nodes]);
+  const retry = useCallback(() => setAttempt((n) => n + 1), []);
+
+  // "Open in Files" is a one-off request: leaving the Files tab drops it, so
+  // a later visit opens the tree at its root rather than on that file again.
+  const changeTab = useCallback(
+    (next: GraphTab) => {
+      if (tab === 'files' && next !== 'files') setFilesPath(undefined);
+      setTab(next);
+    },
+    [tab],
+  );
+
+  const showInGraph = useCallback(
+    (node: GraphNodeRef) => {
+      setSelected(node);
+      changeTab('graph');
+    },
+    [changeTab],
+  );
+
+  const [filesActions, setFilesActions] = useState<HTMLDivElement | null>(null);
+
+  // A flat source has no file to open: "Open in Files" just shows the tab.
+  const openInFiles = useCallback(
+    (path: string) => {
+      if (isNested) setFilesPath(path);
+      setTab('files');
+    },
+    [isNested],
+  );
+
+  // The flat source's crumbs: the source, then the open chunk; the source
+  // crumb closes the chunk.
+  const chunkCrumbs: Crumb[] = [
+    {
+      label: sourceName,
+      onSelect:
+        openChunkPosition !== null
+          ? () => chunksControllerRef.current?.closeChunk()
+          : undefined,
+    },
+    ...(openChunkPosition !== null
+      ? [
+          {
+            label: t('settings.sources.chunkCrumb', { n: openChunkPosition }),
+          },
+        ]
+      : []),
+  ];
+  const filesSegments = isNested ? filesCrumbs : chunkCrumbs;
+
+  const files = !isNested ? (
+    <Chunks
+      embedded
+      documentId={docId}
+      documentName={sourceName}
+      handleGoBack={onBackToDocuments}
+      controllerRef={chunksControllerRef}
+      onOpenChunkChange={setOpenChunkPosition}
+    />
+  ) : sourceType === 'connector:file' ? (
+    <ConnectorTree
+      embedded
+      docId={docId}
+      sourceName={sourceName}
+      onBackToDocuments={onBackToDocuments}
+      initialPath={filesPath}
+      actionsTarget={filesActions}
+      onCrumbsChange={setFilesCrumbs}
+    />
+  ) : (
+    <FileTree
+      embedded
+      docId={docId}
+      sourceName={sourceName}
+      onBackToDocuments={onBackToDocuments}
+      initialPath={filesPath}
+      actionsTarget={filesActions}
+      onCrumbsChange={setFilesCrumbs}
+    />
+  );
+
+  return (
+    <div className="flex flex-col gap-4">
+      <PathHeader
+        root={{
+          label: t('settings.sources.label'),
+          onSelect: onBackToDocuments,
+        }}
+        segments={
+          tab === 'files' && filesSegments.length
+            ? filesSegments
+            : [{ label: sourceName }]
+        }
+        badge={
+          <Badge variant="neutral">
+            <Waypoints />
+            {t('settings.sources.graphrag.view.title')}
+          </Badge>
+        }
+        byline={
+          stats
+            ? t('settings.sources.graphrag.view.stats', {
+                entities: t('settings.sources.graphrag.view.entityCount', {
+                  count: stats.nodes,
+                  formatted: formatCount(stats.nodes),
+                }),
+                relationships: t(
+                  'settings.sources.graphrag.view.relationshipCount',
+                  {
+                    count: stats.edges,
+                    formatted: formatCount(stats.edges),
+                  },
+                ),
+                interpolation: { escapeValue: false },
+              })
+            : undefined
+        }
+        actions={
+          <>
+            {headerAction}
+            {/* The Files tab's own action (Add file, Sync) portals in here,
+                beside Test retrieval, like on a plain source. */}
+            {tab === 'files' && isNested ? (
+              <div ref={setFilesActions} className="flex items-center gap-2" />
+            ) : null}
+          </>
+        }
+      />
+      <Tabs value={tab} onValueChange={(value) => changeTab(value as GraphTab)}>
+        <TabsList variant="underline">
+          <TabsTrigger value="graph" variant="underline">
+            {t('settings.sources.graphrag.view.tabs.graph')}
+          </TabsTrigger>
+          <TabsTrigger value="entities" variant="underline">
+            {t('settings.sources.graphrag.view.tabs.entities')}
+          </TabsTrigger>
+          <TabsTrigger value="files" variant="underline">
+            {t('settings.sources.graphrag.view.tabs.files')}
+          </TabsTrigger>
+        </TabsList>
+        {/* Kept mounted so the layout and zoom survive a trip to another tab. */}
+        <TabsContent
+          value="graph"
+          forceMount
+          className="mt-4 data-[state=inactive]:hidden"
+        >
+          <GraphView
+            docId={docId}
+            data={data}
+            fold={fold}
+            status={status}
+            onRetry={retry}
+            limit={limit}
+            onLimitChange={setLimit}
+            selected={selected}
+            onSelect={setSelected}
+            active={tab === 'graph'}
+            onOpenInFiles={openInFiles}
+          />
+        </TabsContent>
+        <TabsContent value="entities" className="mt-4">
+          <GraphEntities
+            docId={docId}
+            fold={fold}
+            onShowInGraph={showInGraph}
+            overview={data}
+            onOpenInFiles={openInFiles}
+          />
+        </TabsContent>
+        <TabsContent value="files" className="mt-4">
+          {/* Remounted per requested file so the tree opens on it. */}
+          <div key={filesPath ?? ''}>{files}</div>
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}
diff --git a/frontend/src/components/graph/GraphTypeDot.tsx b/frontend/src/components/graph/GraphTypeDot.tsx
new file mode 100644
index 00000000..4eaec8ad
--- /dev/null
+++ b/frontend/src/components/graph/GraphTypeDot.tsx
@@ -0,0 +1,66 @@
+import { useTranslation } from 'react-i18next';
+
+import { cn } from '@/lib/utils';
+
+import { Badge } from '../ui/badge';
+import type { FoldedGraphTypes } from '../graphViewUtils';
+import { seriesDotClass } from './graphCanvasUtils';
+
+/** The 8px colour dot of a type's fold series (Other is muted). */
+export function GraphTypeDot({
+  fold,
+  type,
+  className,
+}: {
+  fold: FoldedGraphTypes;
+  type: string | null | undefined;
+  className?: string;
+}) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        'inline-block size-2 shrink-0 rounded-full',
+        seriesDotClass(fold.seriesOf(type)),
+        className,
+      )}
+    />
+  );
+}
+
+/** The dot for a fold series index (null for Other), for the legend. */
+export function GraphSeriesDot({ series }: { series: number | null }) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        'inline-block size-2 shrink-0 rounded-full',
+        seriesDotClass(series),
+      )}
+    />
+  );
+}
+
+/** The display label of a type: its folded spelling, or "Untyped". */
+export function useGraphTypeLabel(fold: FoldedGraphTypes) {
+  const { t } = useTranslation();
+  return (type: string | null | undefined) =>
+    fold.labelOf(type) || t('settings.sources.graphrag.view.untyped');
+}
+
+/** A neutral Badge with the type's dot and folded label. */
+export function GraphTypeBadge({
+  fold,
+  type,
+}: {
+  fold: FoldedGraphTypes;
+  type: string | null | undefined;
+}) {
+  const labelOf = useGraphTypeLabel(fold);
+  return (
+    <Badge variant="neutral" className="max-w-full min-w-0">
+      <GraphTypeDot fold={fold} type={type} />
+      <span className="truncate">{labelOf(type)}</span>
+    </Badge>
+  );
+}
diff --git a/frontend/src/components/graph/graphCanvasUtils.test.ts b/frontend/src/components/graph/graphCanvasUtils.test.ts
new file mode 100644
index 00000000..4c7eb54a
--- /dev/null
+++ b/frontend/src/components/graph/graphCanvasUtils.test.ts
@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest';
+
+import { foldGraphTypes } from '../graphViewUtils';
+import {
+  OTHER_GROUP_KEY,
+  buildAdjacency,
+  chunkFileName,
+  chunkFilePath,
+  chunkHeading,
+  endpointId,
+  focusSet,
+  labelBoxesOverlap,
+  legendGroupOf,
+  linkTouches,
+  overviewRelationships,
+  pickLabels,
+  relationshipLabelText,
+  seriesDotClass,
+  topHubIds,
+} from './graphCanvasUtils';
+
+const nodes = Array.from({ length: 14 }, (_, i) => ({
+  id: `n${i}`,
+  name: `Node ${i}`,
+  degree: 14 - i,
+}));
+
+describe('topHubIds', () => {
+  it('keeps the ten busiest nodes', () => {
+    const hubs = topHubIds(nodes);
+    expect(hubs.size).toBe(10);
+    expect(hubs.has('n0')).toBe(true);
+    expect(hubs.has('n9')).toBe(true);
+    expect(hubs.has('n10')).toBe(false);
+  });
+});
+
+describe('buildAdjacency', () => {
+  it('links both ends and reads node objects from a running simulation', () => {
+    const adjacency = buildAdjacency([
+      { source: 'a', target: 'b' },
+      {
+        source: { id: 'b' } as unknown as string,
+        target: { id: 'c' } as unknown as string,
+      },
+      { source: 'a', target: 'a' },
+    ]);
+    expect([...(adjacency.get('b') ?? [])].sort()).toEqual(['a', 'c']);
+    expect([...(adjacency.get('a') ?? [])]).toEqual(['b']);
+  });
+
+  it('reads either end shape', () => {
+    expect(endpointId('x')).toBe('x');
+    expect(endpointId({ id: 'y' })).toBe('y');
+    expect(endpointId(null)).toBe('');
+  });
+});
+
+describe('focusSet (dimming)', () => {
+  const adjacency = buildAdjacency([
+    { source: 'a', target: 'b' },
+    { source: 'a', target: 'c' },
+    { source: 'c', target: 'd' },
+  ]);
+  const loaded = new Set(['a', 'b', 'c', 'd']);
+
+  it('is the selection and its neighbours', () => {
+    expect([...(focusSet('a', adjacency, loaded) ?? [])].sort()).toEqual([
+      'a',
+      'b',
+      'c',
+    ]);
+  });
+
+  it('is null with no selection, or one outside the loaded overview', () => {
+    expect(focusSet(null, adjacency, loaded)).toBeNull();
+    expect(focusSet('zz', adjacency, loaded)).toBeNull();
+  });
+
+  it('keeps an isolated selection on its own', () => {
+    expect([...(focusSet('e', new Map(), new Set(['e'])) ?? [])]).toEqual([
+      'e',
+    ]);
+  });
+});
+
+describe('linkTouches', () => {
+  it('matches either end', () => {
+    expect(linkTouches({ source: 'a', target: 'b' }, 'b')).toBe(true);
+    expect(linkTouches({ source: 'a', target: 'b' }, 'c')).toBe(false);
+    expect(linkTouches({ source: 'a', target: 'b' }, null)).toBe(false);
+  });
+});
+
+describe('relationshipLabelText', () => {
+  it('falls back when there are no labels', () => {
+    expect(relationshipLabelText([], 'related to')).toBe('related to');
+  });
+
+  it('joins two labels', () => {
+    expect(relationshipLabelText(['manages', 'owns'], 'x')).toBe(
+      'manages · owns',
+    );
+  });
+
+  it('counts the rest after two', () => {
+    expect(relationshipLabelText(['a', 'b', 'c', 'd'], 'x')).toBe('a · b · +2');
+  });
+});
+
+describe('chunkFileName', () => {
+  it('takes the last segment of the source path', () => {
+    expect(chunkFileName({ source: 'inputs/u/Carrier_profile.docx' })).toBe(
+      'Carrier_profile.docx',
+    );
+  });
+
+  it('falls back to the title, then nothing', () => {
+    expect(chunkFileName({ title: 'Notes.md' })).toBe('Notes.md');
+    expect(chunkFileName(undefined)).toBe('');
+  });
+
+  it("names a web page by its tree path, not the URL's last segment", () => {
+    expect(
+      chunkFileName({
+        source: 'https://docs.example.com/guides/setup?x=1',
+        file_path: 'guides/setup.md',
+        title: 'Setup',
+      }),
+    ).toBe('setup.md');
+  });
+
+  it('never splits a title', () => {
+    expect(
+      chunkFileName({ source: 'https://example.com/a/b', title: 'A / B' }),
+    ).toBe('A / B');
+  });
+});
+
+describe('chunkFilePath', () => {
+  it('prefers file_path, then key', () => {
+    expect(
+      chunkFilePath({
+        file_path: 'guides/setup.md',
+        key: 'other.md',
+        source: 'https://x.dev/guides/setup',
+      }),
+    ).toBe('guides/setup.md');
+    expect(
+      chunkFilePath({ key: 'docs/a.md', source: 'inputs/u/docs/a.md' }),
+    ).toBe('docs/a.md');
+  });
+
+  it('uses a local source path but never a URL', () => {
+    expect(chunkFilePath({ source: 'inputs/u/Brief.docx' })).toBe(
+      'inputs/u/Brief.docx',
+    );
+    expect(
+      chunkFilePath({ source: 'https://x.dev/page', title: 'Page title' }),
+    ).toBe('Page title');
+    expect(chunkFilePath({ source: 'https://x.dev/page' })).toBe('');
+  });
+});
+
+describe('legend groups and dots', () => {
+  const fold = foldGraphTypes([
+    { type: 'Person' },
+    { type: 'Person' },
+    { type: 'Port' },
+    { type: 'Lane' },
+    { type: 'Company' },
+    { type: 'Event' },
+    { type: null },
+  ]);
+
+  it('maps a type to its fold group, the rest to Other', () => {
+    expect(legendGroupOf(fold, 'PERSON')).toBe('person');
+    expect(legendGroupOf(fold, null)).toBe(OTHER_GROUP_KEY);
+  });
+
+  it('uses a static class per series', () => {
+    expect(seriesDotClass(0)).toBe('bg-chart-1');
+    expect(seriesDotClass(3)).toBe('bg-chart-4');
+    expect(seriesDotClass(null)).toBe('bg-muted-foreground');
+  });
+});
+
+describe('overviewRelationships', () => {
+  const overviewNodes = [
+    { id: 'n', name: 'Nordhaven', type: 'Company', degree: 9 },
+    { id: 'a', name: 'Anneke', type: 'Person', degree: 5 },
+    { id: 'b', name: 'Bram', type: 'Person', degree: 3 },
+  ];
+  it('joins each link touching the node to its neighbour, both directions', () => {
+    const rels = overviewRelationships(
+      'n',
+      [
+        { source: 'a', target: 'n', type: 'manages' },
+        // A simulation link: node objects at the ends.
+        {
+          source: { id: 'n' } as never,
+          target: { id: 'b' } as never,
+          type: null,
+        },
+        { source: 'a', target: 'b', type: 'knows' },
+        { source: 'n', target: 'missing', type: 'x' },
+      ],
+      overviewNodes,
+    );
+    expect(rels).toEqual([
+      {
+        id: 'a',
+        name: 'Anneke',
+        type: 'Person',
+        degree: 5,
+        edge_type: 'manages',
+        direction: 'in',
+      },
+      {
+        id: 'b',
+        name: 'Bram',
+        type: 'Person',
+        degree: 3,
+        edge_type: null,
+        direction: 'out',
+      },
+    ]);
+  });
+});
+
+describe('label collision', () => {
+  const box = (id: string, x: number, y: number, always = false) => ({
+    id,
+    x,
+    y,
+    width: 40,
+    height: 10,
+    always,
+  });
+
+  it('tests intersection of centred boxes', () => {
+    expect(labelBoxesOverlap(box('a', 0, 0), box('b', 39, 9))).toBe(true);
+    expect(labelBoxesOverlap(box('a', 0, 0), box('b', 40, 0))).toBe(false);
+    expect(labelBoxesOverlap(box('a', 0, 0), box('b', 0, 10))).toBe(false);
+    expect(labelBoxesOverlap(box('a', 0, 0), box('b', 0, 11), 2)).toBe(true);
+  });
+
+  it('keeps labels in priority order and skips the ones they cover', () => {
+    const picked = pickLabels([
+      box('selected', 0, 0, true),
+      box('hovered', 10, 2, true),
+      box('hub', 20, 5),
+      box('clear', 100, 0),
+      box('under-clear', 110, 4),
+    ]);
+    expect([...picked]).toEqual(['selected', 'hovered', 'clear']);
+  });
+});
+
+describe('chunkHeading', () => {
+  it('reads a first-line markdown heading, else nothing', () => {
+    expect(chunkHeading('# Account brief — Nordhaven\nBody')).toBe(
+      'Account brief — Nordhaven',
+    );
+    expect(chunkHeading('\n  ### Rates ##\ntext')).toBe('Rates');
+    expect(chunkHeading('Plain text\n# Later')).toBeNull();
+    expect(chunkHeading('#hashtag')).toBeNull();
+    expect(chunkHeading('')).toBeNull();
+  });
+});
diff --git a/frontend/src/components/graph/graphCanvasUtils.ts b/frontend/src/components/graph/graphCanvasUtils.ts
new file mode 100644
index 00000000..10c1a3c3
--- /dev/null
+++ b/frontend/src/components/graph/graphCanvasUtils.ts
@@ -0,0 +1,281 @@
+import type {
+  FoldedGraphTypes,
+  GraphEdge,
+  GraphNode,
+  GraphRelationship,
+} from '../graphViewUtils';
+
+/** The legend's key for everything folded into "Other". */
+export const OTHER_GROUP_KEY = '__other';
+
+/** How many of the busiest nodes keep a label while nothing is selected. */
+const HUB_LABEL_COUNT = 10;
+
+/** How much of a node or edge outside the selection stays visible. */
+export const DIM_ALPHA = 0.15;
+
+// Static class strings so Tailwind sees them: series 0..3, then Other.
+const SERIES_DOT_CLASSES = [
+  'bg-chart-1',
+  'bg-chart-2',
+  'bg-chart-3',
+  'bg-chart-4',
+] as const;
+const OTHER_DOT_CLASS = 'bg-muted-foreground';
+
+/**
+ * The dot colour class for a fold series.
+ *
+ * @param series The series index from `foldGraphTypes().seriesOf`, or null for Other.
+ * @returns A static `bg-*` class.
+ */
+export function seriesDotClass(series: number | null | undefined): string {
+  if (series == null) return OTHER_DOT_CLASS;
+  return SERIES_DOT_CLASSES[series] ?? OTHER_DOT_CLASS;
+}
+
+/**
+ * The legend group a type belongs to: its fold group's key, or Other.
+ *
+ * @param fold The shared type fold.
+ * @param type A node's raw type.
+ * @returns A group key, or `OTHER_GROUP_KEY`.
+ */
+export function legendGroupOf(
+  fold: FoldedGraphTypes,
+  type: string | null | undefined,
+): string {
+  const series = fold.seriesOf(type);
+  if (series == null) return OTHER_GROUP_KEY;
+  return (
+    fold.groups.find((group) => group.series === series)?.key ?? OTHER_GROUP_KEY
+  );
+}
+
+type LinkEnd = string | { id?: string | number } | undefined | null;
+
+/**
+ * The node id at one end of a link. The force simulation swaps the ids for
+ * the node objects once it starts, so both shapes are read.
+ */
+export function endpointId(end: LinkEnd): string {
+  if (end == null) return '';
+  if (typeof end === 'object') return String(end.id ?? '');
+  return String(end);
+}
+
+/** Neighbour ids per node id, from the loaded links (both directions). */
+export function buildAdjacency(
+  links: Pick<GraphEdge, 'source' | 'target'>[],
+): Map<string, Set<string>> {
+  const adjacency = new Map<string, Set<string>>();
+  const add = (from: string, to: string) => {
+    const set = adjacency.get(from) ?? new Set<string>();
+    set.add(to);
+    adjacency.set(from, set);
+  };
+  for (const link of links) {
+    const source = endpointId(link.source as LinkEnd);
+    const target = endpointId(link.target as LinkEnd);
+    if (!source || !target || source === target) continue;
+    add(source, target);
+    add(target, source);
+  }
+  return adjacency;
+}
+
+/** Ids of the `count` highest-degree nodes (ties by id, so the pick is stable). */
+export function topHubIds(
+  nodes: Pick<GraphNode, 'id' | 'degree'>[],
+  count = HUB_LABEL_COUNT,
+): Set<string> {
+  return new Set(
+    [...nodes]
+      .sort(
+        (a, b) => (b.degree || 0) - (a.degree || 0) || a.id.localeCompare(b.id),
+      )
+      .slice(0, count)
+      .map((node) => node.id),
+  );
+}
+
+/**
+ * The nodes that stay at full strength while one is selected: the selection
+ * and its neighbours. Null when nothing on the canvas is selected (a pick
+ * outside the loaded overview draws no highlight).
+ */
+export function focusSet(
+  selectedId: string | null | undefined,
+  adjacency: Map<string, Set<string>>,
+  loadedIds: Set<string>,
+): Set<string> | null {
+  if (!selectedId || !loadedIds.has(selectedId)) return null;
+  return new Set([selectedId, ...(adjacency.get(selectedId) ?? [])]);
+}
+
+interface LabelContext {
+  hubs: Set<string>;
+  focus: Set<string> | null;
+  hoveredId: string | null | undefined;
+}
+
+/**
+ * Whether a node gets a label: with a selection, the selection and its
+ * neighbours; without one, the hubs. The hovered node always does.
+ */
+export function nodeHasLabel(
+  id: string,
+  { hubs, focus, hoveredId }: LabelContext,
+): boolean {
+  if (id === hoveredId) return true;
+  return focus ? focus.has(id) : hubs.has(id);
+}
+
+/** Whether a link touches the node. */
+export function linkTouches(
+  link: Pick<GraphEdge, 'source' | 'target'>,
+  nodeId: string | null | undefined,
+): boolean {
+  if (!nodeId) return false;
+  return (
+    endpointId(link.source as LinkEnd) === nodeId ||
+    endpointId(link.target as LinkEnd) === nodeId
+  );
+}
+
+/**
+ * A relationship row's label line: the first two labels joined by " · ",
+ * then "+N" for the rest; the fallback ("related to") when there are none.
+ */
+export function relationshipLabelText(
+  labels: string[],
+  fallback: string,
+): string {
+  if (labels.length === 0) return fallback;
+  const shown = labels.slice(0, 2).join(' · ');
+  return labels.length > 2 ? `${shown} · +${labels.length - 2}` : shown;
+}
+
+const pickString = (value: unknown): string =>
+  typeof value === 'string' && value.trim() ? value.trim() : '';
+
+/**
+ * The tree path a chunk belongs to, as the Files tab (`directory_structure`)
+ * keys it: `metadata.file_path`, else `key`, else `source` unless it is a URL
+ * (a web page's source is its address, not its tree path), else `title`.
+ * Mirrors the backend's `_chunk_matches_path`.
+ *
+ * @param metadata The chunk's metadata.
+ * @returns The path, or '' when the chunk names none.
+ */
+export function chunkFilePath(
+  metadata: Record<string, unknown> | undefined,
+): string {
+  const filePath = pickString(metadata?.file_path);
+  if (filePath) return filePath;
+  const key = pickString(metadata?.key);
+  if (key) return key;
+  const source = pickString(metadata?.source);
+  if (source && !source.includes('://')) return source;
+  return pickString(metadata?.title);
+}
+
+/**
+ * The file a chunk came from, for its tile's meta row: the last segment of
+ * its tree path (see `chunkFilePath`), or its title as is.
+ */
+export function chunkFileName(
+  metadata: Record<string, unknown> | undefined,
+): string {
+  // A title is a name, not a path: shown whole.
+  const path = chunkFilePath({ ...metadata, title: undefined });
+  if (!path) return pickString(metadata?.title);
+  return path.split(/[\\/]/).filter(Boolean).pop() ?? path;
+}
+
+/**
+ * The relationships of a node as the loaded overview knows them: one entry
+ * per link touching it, joined to the node at the other end. The fallback
+ * for an API whose node detail predates `relationships`.
+ *
+ * @param nodeId The node.
+ * @param links The overview links (ids or simulation node objects at the ends).
+ * @param nodes The overview nodes, for the neighbour's name, type and degree.
+ * @returns Relationships in the shape of `GraphNodeDetail.relationships`.
+ */
+export function overviewRelationships(
+  nodeId: string,
+  links: Pick<GraphEdge, 'source' | 'target' | 'type'>[],
+  nodes: Pick<GraphNode, 'id' | 'name' | 'type' | 'degree'>[],
+): GraphRelationship[] {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const out: GraphRelationship[] = [];
+  for (const link of links) {
+    const source = endpointId(link.source as LinkEnd);
+    const target = endpointId(link.target as LinkEnd);
+    if (source === target) continue;
+    const direction =
+      source === nodeId ? 'out' : target === nodeId ? 'in' : null;
+    if (!direction) continue;
+    const other = byId.get(direction === 'out' ? target : source);
+    if (!other) continue;
+    out.push({
+      id: other.id,
+      name: other.name,
+      type: other.type,
+      degree: other.degree,
+      edge_type: link.type ?? null,
+      direction,
+    });
+  }
+  return out;
+}
+
+/** A label's text box on the canvas: centred on `x`, its top at `y`. */
+export interface LabelBox {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Drawn whatever it overlaps (the selection, the hovered node). */
+  always?: boolean;
+}
+
+/** Whether two label boxes intersect, with `gap` of clearance kept between them. */
+export function labelBoxesOverlap(a: LabelBox, b: LabelBox, gap = 0): boolean {
+  return (
+    Math.abs(a.x - b.x) * 2 < a.width + b.width + gap * 2 &&
+    a.y < b.y + b.height + gap &&
+    b.y < a.y + a.height + gap
+  );
+}
+
+/**
+ * Which labels to draw so none sits on another: walk the boxes in priority
+ * order and keep each one that clears every box kept so far. `always` boxes
+ * are kept regardless (and still block the ones after them).
+ *
+ * @param boxes Label boxes, highest priority first.
+ * @param gap Clearance between two kept boxes.
+ * @returns The ids to draw.
+ */
+export function pickLabels(boxes: LabelBox[], gap = 0): Set<string> {
+  const kept: LabelBox[] = [];
+  for (const box of boxes) {
+    if (box.always || !kept.some((other) => labelBoxesOverlap(box, other, gap)))
+      kept.push(box);
+  }
+  return new Set(kept.map((box) => box.id));
+}
+
+/**
+ * A chunk's heading for its drawer title: the first line's text when that
+ * line is a markdown heading (the `#`s stripped), else null.
+ */
+export function chunkHeading(text: string | null | undefined): string | null {
+  const first = (text ?? '').trimStart().split(/\r?\n/, 1)[0] ?? '';
+  const match = /^#{1,6}\s+(.*?)\s*#*\s*$/.exec(first);
+  const heading = match?.[1]?.trim();
+  return heading ? heading : null;
+}
diff --git a/frontend/src/components/graph/useGraphNodeDetail.ts b/frontend/src/components/graph/useGraphNodeDetail.ts
new file mode 100644
index 00000000..cc42510f
--- /dev/null
+++ b/frontend/src/components/graph/useGraphNodeDetail.ts
@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSelector } from 'react-redux';
+
+import userService from '../../api/services/userService';
+import { selectToken } from '../../preferences/preferenceSlice';
+import type { GraphNodeDetail } from '../graphViewUtils';
+
+export type GraphNodeDetailStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+/**
+ * Fetch one graph node's detail (description, relationships, chunks).
+ *
+ * @param docId The source id.
+ * @param nodeId The node to load; null loads nothing.
+ * @returns The detail, its status, a retry (shows the loading state) and a
+ *   reload (refetches behind the loaded detail, e.g. after a chunk edit).
+ */
+export function useGraphNodeDetail(docId: string, nodeId: string | null) {
+  const token = useSelector(selectToken);
+  const [detail, setDetail] = useState<GraphNodeDetail | null>(null);
+  const [status, setStatus] = useState<GraphNodeDetailStatus>('idle');
+  const [attempt, setAttempt] = useState(0);
+  // Set by reload: keep the current detail on screen while refetching.
+  const silentRef = useRef(false);
+  const shownIdRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    const silent = silentRef.current && shownIdRef.current === nodeId;
+    silentRef.current = false;
+    if (!silent) setDetail(null);
+    if (!nodeId) {
+      shownIdRef.current = null;
+      setStatus('idle');
+      return;
+    }
+    let cancelled = false;
+    if (!silent) setStatus('loading');
+    userService
+      .getSourceGraphNode(docId, nodeId, token)
+      .then((response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return response.json();
+      })
+      .then((body) => {
+        if (cancelled) return;
+        if (!body?.node) throw new Error('No node');
+        const node = body.node as GraphNodeDetail;
+        shownIdRef.current = nodeId;
+        setDetail({ ...node, chunks: node.chunks ?? [] });
+        setStatus('ready');
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        console.error('Error loading graph node:', error);
+        // A failed background reload keeps what is shown.
+        if (!silent) setStatus('error');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [docId, nodeId, token, attempt]);
+
+  const retry = useCallback(() => setAttempt((n) => n + 1), []);
+  const reload = useCallback(() => {
+    silentRef.current = true;
+    setAttempt((n) => n + 1);
+  }, []);
+  return { detail, status, retry, reload };
+}
diff --git a/frontend/src/components/graphViewUtils.test.ts b/frontend/src/components/graphViewUtils.test.ts
index db43fd72..7f170467 100644
--- a/frontend/src/components/graphViewUtils.test.ts
+++ b/frontend/src/components/graphViewUtils.test.ts
@@ -4,10 +4,15 @@ import {
   GraphNode,
   GraphOverview,
   collideRadius,
+  escapeDeselects,
+  foldGraphTypes,
+  graphTypeKey,
+  groupRelationships,
   maxDegree,
   nodeAtPoint,
-  nodeLabelEl,
   nodeRadius,
+  normalizeEdgeLabel,
+  otherTypesList,
   readGraphPalette,
   toForceGraphData,
 } from './graphViewUtils';
@@ -58,20 +63,6 @@ describe('maxDegree', () => {
   });
 });
 
-describe('nodeLabelEl', () => {
-  it('renders an untrusted name as text, not live HTML', () => {
-    const payload = '<img src=x onerror=alert(1)>';
-    const el = nodeLabelEl(payload);
-    expect(el.textContent).toBe(payload);
-    expect(el.querySelector('img')).toBeNull();
-    expect(el.innerHTML).not.toContain('<img');
-  });
-
-  it('handles a missing name', () => {
-    expect(nodeLabelEl('').textContent).toBe('');
-  });
-});
-
 describe('nodeRadius', () => {
   it('returns the minimum radius when there is no spread', () => {
     expect(nodeRadius(0, 0)).toBe(3);
@@ -132,32 +123,237 @@ describe('nodeAtPoint', () => {
 });
 
 describe('readGraphPalette', () => {
-  const tokens = ['--primary', '--foreground', '--border', '--card'];
+  const tokens = [
+    '--chart-1',
+    '--chart-2',
+    '--chart-3',
+    '--chart-4',
+    '--muted-foreground',
+    '--primary',
+    '--foreground',
+    '--border',
+    '--background',
+    '--font-sans',
+  ];
   afterEach(() =>
     tokens.forEach((name) => document.body.style.removeProperty(name)),
   );
 
-  it('maps nodes, hover ring, links, labels and halo onto the theme tokens', () => {
-    document.body.style.setProperty('--primary', '#976af3');
+  it('maps the type series, Other, links, labels, halo and font onto the theme tokens', () => {
+    document.body.style.setProperty('--chart-1', '#8855f1');
+    document.body.style.setProperty('--chart-2', '#60a5fa');
+    document.body.style.setProperty('--chart-3', '#22c55e');
+    document.body.style.setProperty('--chart-4', '#facc15');
+    document.body.style.setProperty('--muted-foreground', '#a1a1a1');
+    document.body.style.setProperty('--primary', '#8855f1');
     document.body.style.setProperty('--foreground', '#fafafa');
     document.body.style.setProperty('--border', '#44454c');
-    document.body.style.setProperty('--card', '#2b2c31');
+    document.body.style.setProperty('--background', '#222327');
+    document.body.style.setProperty('--font-sans', 'Inter, sans-serif');
     expect(readGraphPalette()).toEqual({
-      node: '#976af3',
+      series: ['#8855f1', '#60a5fa', '#22c55e', '#facc15'],
+      other: '#a1a1a1',
+      primary: '#8855f1',
       hoverStroke: '#fafafa',
       link: '#44454c',
       label: '#fafafa',
-      halo: '#2b2c31',
+      halo: '#222327',
+      font: 'Inter, sans-serif',
     });
   });
 
-  it('falls back to the light tokens', () => {
+  it('falls back to the light tokens, with grey (not chart-5 red) for Other', () => {
     expect(readGraphPalette()).toEqual({
-      node: '#7d54d1',
+      series: ['#7d54d1', '#2563eb', '#079455', '#ca8a04'],
+      other: '#737373',
+      primary: '#7d54d1',
       hoverStroke: '#171717',
       link: '#d9d9d9',
       label: '#171717',
       halo: '#ffffff',
+      font: 'sans-serif',
     });
   });
 });
+
+describe('graphTypeKey', () => {
+  it('lower-cases and drops everything but letters and digits', () => {
+    expect(graphTypeKey('Service Lane')).toBe('servicelane');
+    expect(graphTypeKey('ServiceLane')).toBe('servicelane');
+    expect(graphTypeKey('PORT')).toBe('port');
+    expect(graphTypeKey(null)).toBe('');
+    expect(graphTypeKey(undefined)).toBe('');
+  });
+});
+
+describe('foldGraphTypes', () => {
+  const nodes = [
+    ...Array.from({ length: 5 }, () => ({ type: 'Person' })),
+    { type: 'PERSON' },
+    ...Array.from({ length: 4 }, () => ({ type: 'Organization' })),
+    ...Array.from({ length: 3 }, () => ({ type: 'Location' })),
+    ...Array.from({ length: 2 }, () => ({ type: 'Service Lane' })),
+    { type: 'ServiceLane' },
+    { type: 'Port' },
+    { type: null },
+  ];
+
+  it('keeps the four largest keys as series and folds the rest into Other', () => {
+    const folded = foldGraphTypes(nodes);
+    expect(
+      folded.groups.map((g) => [g.key, g.label, g.count, g.series]),
+    ).toEqual([
+      ['person', 'Person', 6, 0],
+      ['organization', 'Organization', 4, 1],
+      ['location', 'Location', 3, 2],
+      ['servicelane', 'Service Lane', 3, 3],
+    ]);
+    expect(folded.other).toEqual({ count: 2, labels: ['Port'] });
+    expect(folded.seriesOf('SERVICELANE')).toBe(3);
+    expect(folded.seriesOf('Port')).toBeNull();
+    expect(folded.seriesOf(null)).toBeNull();
+    expect(folded.labelOf('PERSON')).toBe('Person');
+    expect(folded.labelOf('port')).toBe('Port');
+  });
+
+  it('has no Other when every type fits', () => {
+    const folded = foldGraphTypes([{ type: 'A' }, { type: 'b' }]);
+    expect(folded.groups).toHaveLength(2);
+    expect(folded.other).toEqual({ count: 0, labels: [] });
+  });
+});
+
+describe('normalizeEdgeLabel', () => {
+  it('lower-cases, turns underscores into spaces and trims', () => {
+    expect(normalizeEdgeLabel('PREFERRED_CARRIER_FOR')).toBe(
+      'preferred carrier for',
+    );
+    expect(normalizeEdgeLabel('  serves  ')).toBe('serves');
+    expect(normalizeEdgeLabel(null)).toBe('');
+  });
+});
+
+describe('groupRelationships', () => {
+  it('makes one row per neighbour with distinct labels, busiest neighbour first', () => {
+    const rows = groupRelationships([
+      {
+        id: 'm',
+        name: 'Meridian',
+        type: 'Org',
+        degree: 119,
+        edge_type: 'carrier_for',
+      },
+      {
+        id: 'a',
+        name: 'Anneke',
+        type: 'Person',
+        degree: 40,
+        edge_type: 'MANAGES',
+      },
+      {
+        id: 'm',
+        name: 'Meridian',
+        type: 'Org',
+        degree: 119,
+        edge_type: 'CARRIER_FOR',
+      },
+      {
+        id: 'm',
+        name: 'Meridian',
+        type: 'Org',
+        degree: 119,
+        edge_type: 'serves',
+      },
+      {
+        id: 'd',
+        name: 'Duisport',
+        type: 'Location',
+        degree: 9,
+        edge_type: null,
+      },
+    ]);
+    expect(rows.map((r) => [r.id, r.labels])).toEqual([
+      ['m', ['carrier for', 'serves']],
+      ['a', ['manages']],
+      ['d', []],
+    ]);
+  });
+});
+
+describe('escapeDeselects', () => {
+  const press = (target: EventTarget, init: KeyboardEventInit = {}) => {
+    let result: boolean | undefined;
+    const listener = (event: Event) => {
+      result = escapeDeselects(event as KeyboardEvent);
+    };
+    document.addEventListener('keydown', listener);
+    target.dispatchEvent(
+      new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        cancelable: true,
+        ...init,
+      }),
+    );
+    document.removeEventListener('keydown', listener);
+    return result;
+  };
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('deselects on Escape outside a field', () => {
+    const div = document.body.appendChild(document.createElement('div'));
+    expect(press(div)).toBe(true);
+    expect(press(document.body, { key: 'Enter' })).toBe(false);
+  });
+
+  it('leaves Escape to a field being typed in', () => {
+    for (const tag of ['input', 'textarea', 'select']) {
+      const field = document.body.appendChild(document.createElement(tag));
+      expect(press(field)).toBe(false);
+    }
+    const editable = document.body.appendChild(document.createElement('div'));
+    editable.contentEditable = 'true';
+    // jsdom does not derive isContentEditable from the attribute.
+    Object.defineProperty(editable, 'isContentEditable', { value: true });
+    expect(press(editable)).toBe(false);
+  });
+
+  it('leaves an Escape something else already handled', () => {
+    const div = document.body.appendChild(document.createElement('div'));
+    div.addEventListener('keydown', (event) => event.preventDefault());
+    expect(press(div)).toBe(false);
+  });
+});
+
+describe('otherTypesList', () => {
+  const more = (count: number) => `${count} more`;
+  const labels = ['Vessel', 'Port', 'Terminal', 'Broker', 'Law', 'Insurer'];
+
+  it('joins the folded types as a list in the app language', () => {
+    expect(otherTypesList(['Vessel', 'Port'], more, 'en')).toBe(
+      'Vessel and Port',
+    );
+    expect(otherTypesList(labels, more, 'en')).toBe(
+      'Vessel, Port, Terminal, Broker, Law, and Insurer',
+    );
+  });
+
+  it('names the rest past six as its last item', () => {
+    const nine = [...labels, 'Carrier', 'Forwarder', 'Shipper'];
+    expect(otherTypesList(nine, more, 'en')).toBe(
+      'Vessel, Port, Terminal, Broker, Law, Insurer, and 3 more',
+    );
+    expect(otherTypesList(nine, (n) => `${n} weitere`, 'de')).toBe(
+      'Vessel, Port, Terminal, Broker, Law, Insurer und 3 weitere',
+    );
+  });
+
+  it('maps the app codes Intl does not know', () => {
+    expect(otherTypesList(['A', 'B'], more, 'jp')).toBe(
+      new Intl.ListFormat('ja', { type: 'conjunction' }).format(['A', 'B']),
+    );
+  });
+});
diff --git a/frontend/src/components/graphViewUtils.ts b/frontend/src/components/graphViewUtils.ts
index dbd0d76a..9d7ca059 100644
--- a/frontend/src/components/graphViewUtils.ts
+++ b/frontend/src/components/graphViewUtils.ts
@@ -1,4 +1,7 @@
-import { readCssVar } from '../utils/chartUtils';
+import i18next from 'i18next';
+
+import { readCssVar, SERIES_TOKENS } from '../utils/chartUtils';
+import { intlLocale } from '../utils/dateTimeUtils';
 
 export interface GraphNode {
   id: string;
@@ -26,9 +29,45 @@ export interface GraphNodeChunk {
   metadata?: Record<string, unknown>;
 }
 
+/** One edge touching a node, joined to the node at its other end. */
+export interface GraphRelationship {
+  id: string;
+  name: string;
+  type?: string | null;
+  degree: number;
+  edge_type?: string | null;
+  direction?: 'out' | 'in';
+}
+
 export interface GraphNodeDetail extends GraphNode {
   doc_freq?: number;
   chunks: GraphNodeChunk[];
+  /** The strongest edges, capped server-side (`MAX_NODE_RELATIONSHIPS`). */
+  relationships?: GraphRelationship[];
+  /** Every edge the node takes part in; above `relationships.length` when capped. */
+  relationships_total?: number;
+}
+
+/** A row of the paged `/graph/nodes` list. */
+export interface GraphNodeSummary {
+  id: string;
+  name: string;
+  type?: string | null;
+  degree: number;
+  doc_freq?: number | null;
+}
+
+/** One type key over every node of the source (the `/graph/nodes` facet). */
+export interface GraphTypeFacet {
+  key: string;
+  label: string | null;
+  count: number;
+}
+
+/** Totals for the whole graph, beyond the loaded overview. */
+export interface GraphStats {
+  nodes: number;
+  edges: number;
 }
 
 export interface ForceGraphData {
@@ -94,24 +133,24 @@ export function nodeAtPoint(
   return best;
 }
 
-export function nodeLabelEl(name: string): HTMLDivElement {
-  const el = document.createElement('div');
-  el.textContent = name ?? '';
-  return el;
-}
-
 /** Resolved canvas colours for the graph view. */
 export interface GraphPalette {
-  /** Node fill (`--primary`). */
-  node: string;
-  /** Ring around the hovered node (`--foreground`). */
+  /** The four type series (`--chart-1` to `--chart-4`). */
+  series: string[];
+  /** Nodes folded into "Other" (`--muted-foreground`, not chart-5's red). */
+  other: string;
+  /** The selection's edges (`--primary`). */
+  primary: string;
+  /** Ring around the hovered and selected node (`--foreground`). */
   hoverStroke: string;
   /** Edge colour (`--border`). */
   link: string;
   /** Label text (`--foreground`). */
   label: string;
-  /** Label halo (`--card`, the canvas surface, so it works in both themes). */
+  /** Label halo (`--background`, the canvas surface, so it works in both themes). */
   halo: string;
+  /** The app font (`--font-sans`) for labels. */
+  font: string;
 }
 
 /**
@@ -125,10 +164,192 @@ export interface GraphPalette {
 export function readGraphPalette(): GraphPalette {
   const foreground = readCssVar('--foreground', '#171717');
   return {
-    node: readCssVar('--primary', '#7d54d1'),
+    series: SERIES_TOKENS.slice(0, GRAPH_TYPE_SERIES).map(([name, fallback]) =>
+      readCssVar(name, fallback),
+    ),
+    other: readCssVar('--muted-foreground', '#737373'),
+    primary: readCssVar('--primary', '#7d54d1'),
     hoverStroke: foreground,
     link: readCssVar('--border', '#d9d9d9'),
     label: foreground,
-    halo: readCssVar('--card', '#ffffff'),
+    halo: readCssVar('--background', '#ffffff'),
+    font: readCssVar('--font-sans', 'sans-serif'),
   };
 }
+
+/** How many entity types get their own colour; the rest fold into Other. */
+const GRAPH_TYPE_SERIES = 4;
+
+/**
+ * The key that folds spelling variants of one type together ("Service Lane",
+ * "ServiceLane", "SERVICE_LANE"): lower-cased, letters and digits only. The
+ * backend's `/graph/nodes?type=` filter uses the same rule.
+ */
+export function graphTypeKey(type: string | null | undefined): string {
+  return (type ?? '').toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+}
+
+export interface GraphTypeGroup {
+  key: string;
+  /** The most frequent spelling of the key. */
+  label: string;
+  count: number;
+  /** Index into the palette's series. */
+  series: number;
+}
+
+export interface FoldedGraphTypes {
+  groups: GraphTypeGroup[];
+  /** Everything outside the groups, untyped nodes included. */
+  other: { count: number; labels: string[] };
+  /** The series index of a type, or null for Other. */
+  seriesOf: (type: string | null | undefined) => number | null;
+  /** The display spelling of a type's key. */
+  labelOf: (type: string | null | undefined) => string;
+}
+
+/**
+ * Fold the loaded nodes' types for colour: the largest keys keep a series
+ * each, and the rest (and untyped nodes) fold into one "Other".
+ *
+ * @param nodes Nodes with a `type`.
+ * @param seriesCount How many keys keep their own colour.
+ * @returns The groups, the Other bucket and lookups by raw type.
+ */
+export function foldGraphTypes(
+  nodes: { type?: string | null }[],
+  seriesCount = GRAPH_TYPE_SERIES,
+): FoldedGraphTypes {
+  const spellings = new Map<string, Map<string, number>>();
+  let untyped = 0;
+  for (const node of nodes) {
+    const key = graphTypeKey(node.type);
+    if (!key) {
+      untyped += 1;
+      continue;
+    }
+    const counts = spellings.get(key) ?? new Map<string, number>();
+    const raw = (node.type ?? '').trim();
+    counts.set(raw, (counts.get(raw) ?? 0) + 1);
+    spellings.set(key, counts);
+  }
+  const ranked = [...spellings.entries()]
+    .map(([key, counts]) => {
+      const [label] = [...counts.entries()].sort(
+        (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
+      )[0];
+      const count = [...counts.values()].reduce((a, b) => a + b, 0);
+      return { key, label, count };
+    })
+    .sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+  const groups = ranked
+    .slice(0, seriesCount)
+    .map((group, series) => ({ ...group, series }));
+  const rest = ranked.slice(seriesCount);
+  const labels = new Map(ranked.map((g) => [g.key, g.label]));
+  const seriesByKey = new Map(groups.map((g) => [g.key, g.series]));
+  return {
+    groups,
+    other: {
+      count: untyped + rest.reduce((sum, g) => sum + g.count, 0),
+      labels: rest.map((g) => g.label),
+    },
+    seriesOf: (type) => seriesByKey.get(graphTypeKey(type)) ?? null,
+    labelOf: (type) => labels.get(graphTypeKey(type)) ?? (type ?? '').trim(),
+  };
+}
+
+/**
+ * An edge label for reading: lower-cased, underscores as spaces, trimmed.
+ * `PREFERRED_CARRIER_FOR` and `preferred_carrier_for` become one label.
+ */
+export function normalizeEdgeLabel(label: string | null | undefined): string {
+  return (label ?? '')
+    .replace(/_+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+export interface RelationshipRow {
+  id: string;
+  name: string;
+  type?: string | null;
+  degree: number;
+  /** Distinct normalised labels, first seen first; empty when none had one. */
+  labels: string[];
+}
+
+/**
+ * One row per neighbour: the node's edges grouped by the node at the other
+ * end, their labels normalised and deduplicated, the busiest neighbour first.
+ *
+ * @param relationships The node detail's `relationships`.
+ * @returns Rows for the node panel's Relationships list.
+ */
+export function groupRelationships(
+  relationships: GraphRelationship[],
+): RelationshipRow[] {
+  const rows = new Map<string, RelationshipRow>();
+  for (const rel of relationships) {
+    const row = rows.get(rel.id) ?? {
+      id: rel.id,
+      name: rel.name,
+      type: rel.type,
+      degree: rel.degree,
+      labels: [],
+    };
+    const label = normalizeEdgeLabel(rel.edge_type);
+    if (label && !row.labels.includes(label)) row.labels.push(label);
+    rows.set(rel.id, row);
+  }
+  return [...rows.values()].sort(
+    (a, b) => b.degree - a.degree || a.name.localeCompare(b.name),
+  );
+}
+
+/**
+ * Whether a keydown should clear the graph's selection: Escape, unless a
+ * field is being typed in (the Graph tab's search) or something else already
+ * handled the key.
+ *
+ * @param event The keydown event.
+ * @returns True when the selection should be cleared.
+ */
+export function escapeDeselects(event: KeyboardEvent): boolean {
+  if (event.key !== 'Escape' || event.defaultPrevented) return false;
+  const target = event.target as HTMLElement | null;
+  if (
+    target &&
+    (target.isContentEditable ||
+      ['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName))
+  )
+    return false;
+  return true;
+}
+
+/** Folded type names the "Other: …" line spells out before "and N more". */
+export const OTHER_TYPES_SHOWN = 6;
+
+/**
+ * The folded types as a list in the UI language ("A, B, and C"; "A, B und 3
+ * weitere"): the first six, then the rest as one last item.
+ *
+ * @param labels The folded type names, in legend order.
+ * @param more Words the rest ("3 more"); gets how many were left out.
+ * @param language An app language code; defaults to the current one.
+ * @returns The joined list.
+ */
+export function otherTypesList(
+  labels: string[],
+  more: (count: number) => string,
+  language: string = i18next.language,
+): string {
+  const items = labels.slice(0, OTHER_TYPES_SHOWN);
+  if (labels.length > OTHER_TYPES_SHOWN) {
+    items.push(more(labels.length - OTHER_TYPES_SHOWN));
+  }
+  return new Intl.ListFormat(intlLocale(language), {
+    type: 'conjunction',
+  }).format(items);
+}
diff --git a/frontend/src/components/tree/PathHeader.test.tsx b/frontend/src/components/tree/PathHeader.test.tsx
index b77d04a4..c3e229a2 100644
--- a/frontend/src/components/tree/PathHeader.test.tsx
+++ b/frontend/src/components/tree/PathHeader.test.tsx
@@ -11,8 +11,6 @@ describe('PathHeader', () => {
   it('renders a breadcrumb with clickable parents and a truncating last crumb', () => {
     const html = render(
       <PathHeader
-        backLabel="Back"
-        onBack={vi.fn()}
         root={{ label: 'Contracts', onSelect: vi.fn() }}
         segments={[
           { label: 'carriers', onSelect: vi.fn() },
@@ -26,13 +24,38 @@ describe('PathHeader', () => {
     expect(html).toContain('max-w-[32ch]');
     expect(html).toContain('title="a-very-long-file-name.pdf"');
     expect(html).not.toContain('text-primary');
-    expect(html).toContain('aria-label="Back"');
+  });
+
+  // Up one level is a crumb, as on the Tools and Teams detail pages
+  // (DetailBreadcrumb), never a second back arrow.
+  it('has no back button: the crumbs are the way up', () => {
+    const html = render(
+      <PathHeader
+        root={{ label: 'Sources', onSelect: vi.fn() }}
+        segments={[{ label: 'Contracts' }]}
+      />,
+    );
+    expect(html).not.toContain('lucide-arrow-left');
+    expect(html.match(/<button/g)).toHaveLength(1);
+  });
+
+  it('keeps the crumbs on one line: parents truncate with their full name as a title', () => {
+    const html = render(
+      <PathHeader
+        root={{ label: 'Sources', onSelect: vi.fn() }}
+        segments={[
+          { label: 'Key Accounts & Carrier Network', onSelect: vi.fn() },
+          { label: 'carriers' },
+        ]}
+      />,
+    );
+    expect(html).toContain('flex-nowrap');
+    expect(html).toContain('title="Key Accounts &amp; Carrier Network"');
+    expect(html).toMatch(/class="[^"]*truncate[^"]*"[^>]*>Key Accounts/);
   });
 
   it('makes the root the current crumb when there are no segments', () => {
-    const html = render(
-      <PathHeader backLabel="Back" onBack={vi.fn()} root={{ label: 'Docs' }} />,
-    );
+    const html = render(<PathHeader root={{ label: 'Docs' }} />);
     expect(html).toContain('data-slot="breadcrumb-page"');
     expect(html).not.toContain('data-slot="breadcrumb-link"');
   });
@@ -40,12 +63,32 @@ describe('PathHeader', () => {
   it('renders actions on the right', () => {
     const html = render(
       <PathHeader
-        backLabel="Back"
-        onBack={vi.fn()}
         root={{ label: 'Docs' }}
         actions={<button type="button">Sync</button>}
       />,
     );
     expect(html).toContain('Sync');
   });
+
+  it('puts the kind badge after the crumbs and the byline under the row', () => {
+    const html = render(
+      <PathHeader
+        root={{ label: 'Wiki' }}
+        badge={<span data-testid="badge">Living wiki</span>}
+        byline="12 pages · 8,111 tokens"
+      />,
+    );
+    expect(html.indexOf('data-slot="breadcrumb"')).toBeLessThan(
+      html.indexOf('data-testid="badge"'),
+    );
+    expect(html).toContain(
+      '<p class="text-muted-foreground text-sm">12 pages · 8,111 tokens</p>',
+    );
+  });
+
+  it('a lone crumb is the current page and no button', () => {
+    const html = render(<PathHeader root={{ label: 'Files' }} />);
+    expect(html).not.toContain('<button');
+    expect(html).toContain('data-slot="breadcrumb-page"');
+  });
 });
diff --git a/frontend/src/components/tree/PathHeader.tsx b/frontend/src/components/tree/PathHeader.tsx
index 369a378d..d2a908e6 100644
--- a/frontend/src/components/tree/PathHeader.tsx
+++ b/frontend/src/components/tree/PathHeader.tsx
@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react';
-import { ArrowLeft } from 'lucide-react';
-import { Fragment } from 'react';
+import { Fragment, useEffect, useRef } from 'react';
 
 import {
   Breadcrumb,
@@ -10,78 +9,110 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from '../ui/breadcrumb';
-import { IconButton } from '../ui/icon-button';
 
-type Crumb = { label: string; onSelect?: () => void };
+export type Crumb = { label: string; onSelect?: () => void };
 
 /**
- * The path row above a source's file tree and chunk viewer: a back button,
- * the source and folder crumbs, and actions (search, sync, edit) on the
- * right. The last crumb is the current one and truncates.
+ * The header of every source view (files, chunks, wiki, graph): the crumbs
+ * (Sources, the source, its folders, the open file and chunk), the source
+ * kind's badge, and actions (Test retrieval, the kind's primary action) on
+ * the right; the byline (the source's counts and a one-sentence explainer)
+ * goes under the row. Up one level is a crumb, as on the Tools and Teams
+ * detail pages (DetailBreadcrumb), never a back arrow. The crumbs stay on one
+ * line: parents truncate, and the last crumb is the current one.
  */
 export default function PathHeader({
   root,
   segments = [],
-  onBack,
-  backLabel,
+  badge,
+  byline,
   actions,
 }: {
+  /** The first crumb: Sources, or the source when a host draws Sources. */
   root: Crumb;
   segments?: Crumb[];
-  onBack: () => void;
-  backLabel: string;
+  /** The source kind (a neutral Badge), after the crumbs. */
+  badge?: ReactNode;
+  /** Muted meta line under the row. */
+  byline?: ReactNode;
   actions?: ReactNode;
 }) {
   const crumbs = [root, ...segments];
 
+  // A crumb step replaces the focused button (it becomes the current crumb,
+  // or goes), which would drop focus to <body>. Once the trail changes,
+  // focus lands on the new current crumb instead.
+  const currentRef = useRef<HTMLSpanElement>(null);
+  const refocusRef = useRef(false);
+  const trail = crumbs.map((crumb) => crumb.label).join('/');
+  useEffect(() => {
+    if (!refocusRef.current) return;
+    refocusRef.current = false;
+    currentRef.current?.focus();
+  }, [trail]);
+  const select = (crumb: Crumb) => {
+    refocusRef.current = true;
+    crumb.onSelect?.();
+  };
+
   return (
-    <div className="flex min-h-9.5 flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
-      <div className="flex w-full min-w-0 items-center sm:w-auto">
-        <IconButton
-          variant="outline"
-          size="icon-xs"
-          shape="pill"
-          className="mr-3"
-          label={backLabel}
-          icon={ArrowLeft}
-          side="bottom"
-          onClick={onBack}
-        />
-        <Breadcrumb className="min-w-0">
-          <BreadcrumbList>
-            {crumbs.map((crumb, index) => {
-              const isLast = index === crumbs.length - 1;
-              return (
-                <Fragment key={`${index}-${crumb.label}`}>
-                  {index > 0 ? <BreadcrumbSeparator /> : null}
-                  <BreadcrumbItem>
-                    {isLast ? (
-                      <BreadcrumbPage
-                        className="max-w-[32ch]"
-                        title={crumb.label}
-                      >
-                        {crumb.label}
-                      </BreadcrumbPage>
-                    ) : crumb.onSelect ? (
-                      <BreadcrumbLink asChild>
-                        <button type="button" onClick={crumb.onSelect}>
+    <div className="flex flex-col gap-2">
+      <div className="flex min-h-9.5 flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex w-full min-w-0 items-center gap-3 sm:w-auto">
+          <Breadcrumb className="min-w-0">
+            <BreadcrumbList className="flex-nowrap">
+              {crumbs.map((crumb, index) => {
+                const isLast = index === crumbs.length - 1;
+                return (
+                  <Fragment key={`${index}-${crumb.label}`}>
+                    {index > 0 ? (
+                      <BreadcrumbSeparator className="shrink-0" />
+                    ) : null}
+                    <BreadcrumbItem className="min-w-0">
+                      {isLast ? (
+                        <BreadcrumbPage
+                          ref={currentRef}
+                          tabIndex={-1}
+                          className="max-w-[32ch]"
+                          title={crumb.label}
+                        >
                           {crumb.label}
-                        </button>
-                      </BreadcrumbLink>
-                    ) : (
-                      <span>{crumb.label}</span>
-                    )}
-                  </BreadcrumbItem>
-                </Fragment>
-              );
-            })}
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-      {actions ? (
-        <div className="relative flex w-full flex-row flex-nowrap items-center justify-end gap-2 sm:w-auto">
-          {actions}
+                        </BreadcrumbPage>
+                      ) : crumb.onSelect ? (
+                        <BreadcrumbLink asChild>
+                          <button
+                            type="button"
+                            title={crumb.label}
+                            className="max-w-[16ch] truncate"
+                            onClick={() => select(crumb)}
+                          >
+                            {crumb.label}
+                          </button>
+                        </BreadcrumbLink>
+                      ) : (
+                        <span
+                          title={crumb.label}
+                          className="max-w-[16ch] truncate"
+                        >
+                          {crumb.label}
+                        </span>
+                      )}
+                    </BreadcrumbItem>
+                  </Fragment>
+                );
+              })}
+            </BreadcrumbList>
+          </Breadcrumb>
+          {badge ? <span className="flex shrink-0">{badge}</span> : null}
         </div>
+        {actions ? (
+          <div className="flex w-full flex-row flex-nowrap items-center justify-end gap-2 sm:w-auto">
+            {actions}
+          </div>
+        ) : null}
+      </div>
+      {byline ? (
+        <p className="text-muted-foreground text-sm">{byline}</p>
       ) : null}
     </div>
   );
diff --git a/frontend/src/components/tree/ReaderPanel.tsx b/frontend/src/components/tree/ReaderPanel.tsx
new file mode 100644
index 00000000..0b3bced0
--- /dev/null
+++ b/frontend/src/components/tree/ReaderPanel.tsx
@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+
+import { cn } from '@/lib/utils';
+
+import { Card } from '../ui/card';
+import { Separator } from '../ui/separator';
+
+/**
+ * The reader of a source view: the content you read and edit (a wiki page,
+ * an open chunk) in a `subtle` panel, a place per DESIGN.md's Card surfaces.
+ * Its meta sits left and its actions right in the panel's own header row, so
+ * Edit, then Cancel and Save, stay beside the text they act on.
+ */
+export default function ReaderPanel({
+  meta,
+  actions,
+  children,
+  className,
+}: {
+  /** Muted 12px lines (provenance, token count, path). */
+  meta?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+  /** Layout only. */
+  className?: string;
+}) {
+  return (
+    <Card
+      variant="subtle"
+      padding="none"
+      className={cn('min-w-0 gap-0', className)}
+    >
+      <div className="flex min-h-14 flex-wrap items-center justify-between gap-3 px-6 py-3">
+        <div className="text-muted-foreground flex min-w-0 flex-col text-xs">
+          {meta}
+        </div>
+        {actions ? (
+          <div className="flex items-center gap-2">{actions}</div>
+        ) : null}
+      </div>
+      <Separator />
+      <div className="min-w-0 px-6 py-5">{children}</div>
+    </Card>
+  );
+}
diff --git a/frontend/src/components/tree/SourceEditSheet.test.tsx b/frontend/src/components/tree/SourceEditSheet.test.tsx
new file mode 100644
index 00000000..50a2ec98
--- /dev/null
+++ b/frontend/src/components/tree/SourceEditSheet.test.tsx
@@ -0,0 +1,112 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { TooltipProvider } from '../ui/tooltip';
+import SourceEditSheet, { type SourceEditSheetProps } from './SourceEditSheet';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('SourceEditSheet', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = async (props: Partial<SourceEditSheetProps> = {}) => {
+    const all: SourceEditSheetProps = {
+      open: true,
+      onClose: vi.fn(),
+      title: 'Edit page',
+      description: '/a.md · v1',
+      value: '# Hello',
+      onChange: vi.fn(),
+      dirty: false,
+      onSave: vi.fn(),
+      saveLabel: 'Save',
+      fieldLabel: 'Page content',
+      ...props,
+    };
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <SourceEditSheet {...all} />
+        </TooltipProvider>,
+      );
+    });
+    return all;
+  };
+
+  const button = (text: string) =>
+    [...document.body.querySelectorAll('button')].find(
+      (b) => b.textContent === text,
+    ) as HTMLButtonElement | undefined;
+
+  it('shows the draft in a labelled field and keeps Save off until it changes', async () => {
+    await render();
+    const field = document.body.querySelector('textarea');
+    expect(field?.value).toBe('# Hello');
+    expect(field?.getAttribute('aria-label')).toBe('Page content');
+    expect(button('Save')?.disabled).toBe(true);
+    await render({ dirty: true });
+    expect(button('Save')?.disabled).toBe(false);
+  });
+
+  it('closes at once when nothing changed', async () => {
+    const props = await render();
+    await act(async () => button('settings.sources.editor.cancel')?.click());
+    expect(props.onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('asks before dropping unsaved edits', async () => {
+    const props = await render({ dirty: true });
+    await act(async () => button('settings.sources.editor.cancel')?.click());
+    expect(props.onClose).not.toHaveBeenCalled();
+    expect(document.body.textContent).toContain(
+      'settings.sources.editor.discardMessage',
+    );
+    await act(async () => button('settings.sources.editor.discard')?.click());
+    expect(props.onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the alert above the field', async () => {
+    await render({ alert: <div role="alert">Conflict</div> });
+    const alert = document.body.querySelector('[role="alert"]');
+    const field = document.body.querySelector('textarea');
+    expect(alert).not.toBeNull();
+    expect(
+      alert!.compareDocumentPosition(field!) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it('reopens on Write after the caller closed it from Preview', async () => {
+    await render();
+    const preview = [...document.body.querySelectorAll('[role="tab"]')].find(
+      (b) => b.textContent === 'settings.sources.editor.preview',
+    )!;
+    await act(async () => {
+      preview.dispatchEvent(
+        new MouseEvent('mousedown', { bubbles: true, button: 0 }),
+      );
+    });
+    expect(document.body.querySelector('textarea')).toBeNull();
+    // A save: the caller closes the sheet itself, then opens it again.
+    await render({ open: false });
+    await render({ open: true });
+    expect(document.body.querySelector('textarea')).not.toBeNull();
+  });
+});
diff --git a/frontend/src/components/tree/SourceEditSheet.tsx b/frontend/src/components/tree/SourceEditSheet.tsx
new file mode 100644
index 00000000..fd800527
--- /dev/null
+++ b/frontend/src/components/tree/SourceEditSheet.tsx
@@ -0,0 +1,183 @@
+import type { ReactNode } from 'react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import ConfirmationModal from '../../modals/ConfirmationModal';
+import type { ActiveState } from '../../models/misc';
+import SourceMarkdown from '../SourceMarkdown';
+import { Button } from '../ui/button';
+import { EmptyState } from '../ui/empty-state';
+import { Separator } from '../ui/separator';
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from '../ui/sheet';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs';
+import { Textarea } from '../ui/textarea';
+
+export interface SourceEditSheetProps {
+  open: boolean;
+  /** Called once the drawer may close (after the discard check). */
+  onClose: () => void;
+  title: string;
+  description?: ReactNode;
+  /** The draft, controlled by the caller. */
+  value: string;
+  onChange: (value: string) => void;
+  /** Whether the draft differs from what's saved; enables Save and the discard check. */
+  dirty: boolean;
+  onSave: () => void;
+  saving?: boolean;
+  /** Submit label ("Save", "Add chunk"). */
+  saveLabel: string;
+  /** A save result the user must read (conflict, failure), above the field. */
+  alert?: ReactNode;
+  /**
+   * Fields edited with the content (a chunk's title), under the header and
+   * above the Write / Preview tabs. Their changes count toward `dirty`.
+   */
+  fields?: ReactNode;
+  /** Accessible name of the editor. */
+  fieldLabel: string;
+  placeholder?: string;
+}
+
+/**
+ * The drawer a source view edits in (a wiki page, a chunk): the rendered
+ * content stays on the page behind the scrim while the raw markdown is
+ * edited here, with a Preview tab that renders the draft the same way. Built
+ * like WorkflowDetailsSheet: header, one filling body, then Cancel and Save.
+ * Closing with unsaved edits asks first.
+ */
+export default function SourceEditSheet({
+  open,
+  onClose,
+  title,
+  description,
+  value,
+  onChange,
+  dirty,
+  onSave,
+  saving = false,
+  saveLabel,
+  alert,
+  fields,
+  fieldLabel,
+  placeholder,
+}: SourceEditSheetProps) {
+  const { t } = useTranslation();
+  const [tab, setTab] = useState('write');
+  const [discardState, setDiscardState] = useState<ActiveState>('INACTIVE');
+
+  // Every open starts on Write, however the last one closed (the caller
+  // closes the sheet itself after a save).
+  useEffect(() => {
+    if (open) setTab('write');
+  }, [open]);
+
+  const requestClose = () => {
+    if (saving) return;
+    if (dirty) setDiscardState('ACTIVE');
+    else close();
+  };
+
+  const close = () => {
+    setTab('write');
+    onClose();
+  };
+
+  return (
+    <>
+      <Sheet open={open} onOpenChange={(next) => !next && requestClose()}>
+        <SheetContent
+          side="right"
+          size="wide"
+          className="p-0"
+          closeLabel={t('settings.sources.editor.close')}
+        >
+          <div className="flex min-h-0 flex-1 flex-col">
+            {/* pr-12 keeps the header clear of the close X at top-2 right-2. */}
+            <div className="flex flex-col gap-1 px-6 pt-6 pr-12 pb-4">
+              <SheetTitle>{title}</SheetTitle>
+              {description ? (
+                <SheetDescription className="font-mono text-xs wrap-anywhere">
+                  {description}
+                </SheetDescription>
+              ) : null}
+            </div>
+            {fields ? (
+              <div className="flex flex-col gap-5 px-6 pt-2 pb-5">{fields}</div>
+            ) : null}
+            <Tabs
+              value={tab}
+              onValueChange={setTab}
+              className="flex min-h-0 flex-1 flex-col"
+            >
+              <TabsList variant="underline" className="mx-6">
+                <TabsTrigger variant="underline" value="write">
+                  {t('settings.sources.editor.write')}
+                </TabsTrigger>
+                <TabsTrigger variant="underline" value="preview">
+                  {t('settings.sources.editor.preview')}
+                </TabsTrigger>
+              </TabsList>
+              <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-6 py-6">
+                {alert}
+                <TabsContent value="write" className="flex min-h-0 flex-1">
+                  <Textarea
+                    value={value}
+                    onChange={(event) => onChange(event.target.value)}
+                    aria-label={fieldLabel}
+                    placeholder={placeholder}
+                    resize="none"
+                    className="min-h-[50svh] flex-1 font-mono"
+                    disabled={saving}
+                  />
+                </TabsContent>
+                <TabsContent value="preview">
+                  {value.trim() ? (
+                    <SourceMarkdown content={value} />
+                  ) : (
+                    <EmptyState
+                      size="xs"
+                      illustration="none"
+                      title={t('settings.sources.editor.previewEmpty')}
+                    />
+                  )}
+                </TabsContent>
+              </div>
+            </Tabs>
+            <Separator />
+            <div className="flex justify-end gap-3 px-6 py-4">
+              <Button
+                type="button"
+                variant="ghost"
+                size="lg"
+                shape="pill"
+                onClick={requestClose}
+                disabled={saving}
+              >
+                {t('settings.sources.editor.cancel')}
+              </Button>
+              <Button
+                type="button"
+                size="lg"
+                shape="pill"
+                disabled={!dirty || !value.trim()}
+                loading={saving}
+                onClick={onSave}
+              >
+                {saveLabel}
+              </Button>
+            </div>
+          </div>
+        </SheetContent>
+      </Sheet>
+      <ConfirmationModal
+        message={t('settings.sources.editor.discardMessage')}
+        modalState={discardState}
+        setModalState={setDiscardState}
+        submitLabel={t('settings.sources.editor.discard')}
+        handleSubmit={close}
+        variant="destructive"
+      />
+    </>
+  );
+}
diff --git a/frontend/src/components/tree/SourceNavigator.test.tsx b/frontend/src/components/tree/SourceNavigator.test.tsx
new file mode 100644
index 00000000..695d9a4f
--- /dev/null
+++ b/frontend/src/components/tree/SourceNavigator.test.tsx
@@ -0,0 +1,175 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const media = vi.hoisted(() => ({ isDesktop: true }));
+vi.mock('../../hooks', () => ({
+  useMediaQuery: () => ({
+    isMobile: !media.isDesktop,
+    isDesktop: media.isDesktop,
+  }),
+}));
+
+import type { NavigatorNode } from './navigatorUtils';
+import SourceNavigator from './SourceNavigator';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const folder = (path: string, children: NavigatorNode[]): NavigatorNode => ({
+  id: path,
+  kind: 'folder',
+  label: path.split('/').pop()!,
+  path,
+  count: children.length,
+  children,
+});
+const leaf = (path: string): NavigatorNode => ({
+  id: path,
+  kind: 'leaf',
+  label: path.split('/').pop()!,
+  path,
+});
+
+// Six folders deep, a file at depth 6.
+const DEEP: NavigatorNode[] = [
+  folder('a', [
+    folder('a/b', [
+      folder('a/b/c', [
+        folder('a/b/c/d', [
+          folder('a/b/c/d/e', [
+            folder('a/b/c/d/e/f', [leaf('a/b/c/d/e/f/deep.pdf')]),
+          ]),
+        ]),
+      ]),
+    ]),
+  ]),
+];
+
+const TREE: NavigatorNode[] = [
+  folder('europe', [
+    folder('europe/germany', [
+      folder('europe/germany/bremen', [leaf('europe/germany/bremen/a.pdf')]),
+      leaf('europe/germany/hamburg.pdf'),
+    ]),
+  ]),
+  folder('rate-cards', [leaf('rate-cards/q1.pdf')]),
+];
+
+describe('SourceNavigator', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    media.isDesktop = true;
+    await act(async () => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = async (
+    nodes: NavigatorNode[],
+    selectedId: string | null,
+    onSelect = vi.fn(),
+  ) => {
+    await act(async () => {
+      root.render(
+        <SourceNavigator
+          nodes={nodes}
+          selectedId={selectedId}
+          onSelect={onSelect}
+          filterLabel="Filter"
+          emptyLabel="None"
+          title="Files"
+        />,
+      );
+    });
+  };
+
+  const row = (label: string) =>
+    Array.from(container.querySelectorAll<HTMLElement>('[cmdk-item]')).find(
+      (el) => el.textContent?.startsWith(label),
+    );
+
+  const indent = (label: string) =>
+    row(label)
+      ?.querySelector<HTMLElement>('span[aria-hidden]')
+      ?.style.getPropertyValue('--indent') ?? '';
+
+  it('steps 24px per level through depth 4, then 12px per level', async () => {
+    await render(DEEP, 'a/b/c/d/e/f/deep.pdf');
+    expect(row('a')?.querySelector('span[aria-hidden]')).toBeNull();
+    expect(indent('b')).toBe('24px');
+    expect(indent('c')).toBe('48px');
+    expect(indent('d')).toBe('72px');
+    expect(indent('e')).toBe('96px');
+    expect(indent('f')).toBe('108px');
+    expect(indent('deep.pdf')).toBe('120px');
+  });
+
+  it('titles folder rows with their full path, like files', async () => {
+    await render(DEEP, 'a/b/c/d/e/f/deep.pdf');
+    expect(row('f')?.getAttribute('title')).toBe('a/b/c/d/e/f');
+    expect(row('deep.pdf')?.getAttribute('title')).toBe('a/b/c/d/e/f/deep.pdf');
+  });
+
+  it('expands a folder opened elsewhere (a crumb, a table row), keeping other open folders', async () => {
+    await render(TREE, 'rate-cards/q1.pdf');
+    expect(row('rate-cards')?.getAttribute('aria-expanded')).toBe('true');
+    expect(row('germany')).toBeUndefined();
+
+    await render(TREE, 'europe/germany');
+    expect(row('europe')?.getAttribute('aria-expanded')).toBe('true');
+    expect(row('germany')?.getAttribute('aria-expanded')).toBe('true');
+    expect(row('bremen')).toBeDefined();
+    expect(row('hamburg.pdf')).toBeDefined();
+    // Rate cards, opened before, stays open.
+    expect(row('q1.pdf')).toBeDefined();
+  });
+
+  it('expands a folder that is open on the first render', async () => {
+    await render(TREE, 'europe/germany');
+    expect(row('germany')?.getAttribute('aria-expanded')).toBe('true');
+    expect(row('bremen')).toBeDefined();
+  });
+
+  it('clicking the open folder still collapses it', async () => {
+    const onSelect = vi.fn();
+    await render(TREE, 'europe/germany', onSelect);
+    await act(async () => row('germany')!.click());
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'europe/germany' }),
+    );
+    expect(row('germany')?.getAttribute('aria-expanded')).toBe('false');
+    expect(row('bremen')).toBeUndefined();
+  });
+
+  // The column caps its list; the phone sheet's body already scrolls, so a
+  // cap there would nest a second scroller inside it.
+  it('caps the list in the column but not in the phone sheet', async () => {
+    await render(TREE, null);
+    const columnList = document.body.querySelector(
+      '[data-slot="command-list"]',
+    )!;
+    expect(columnList.className).toContain('max-h-[70svh]');
+
+    await act(async () => root.unmount());
+    root = createRoot(container);
+    media.isDesktop = false;
+    await render(TREE, null);
+    const trigger = container.querySelector(
+      'button[aria-haspopup="dialog"]',
+    ) as HTMLButtonElement;
+    await act(async () => trigger.click());
+    const sheetList = document.body.querySelector(
+      '[data-slot="command-list"]',
+    )!;
+    expect(sheetList).not.toBeNull();
+    expect(sheetList.className).not.toContain('max-h-[70svh]');
+    expect(sheetList.className).toContain('max-h-none');
+  });
+});
diff --git a/frontend/src/components/tree/SourceNavigator.tsx b/frontend/src/components/tree/SourceNavigator.tsx
new file mode 100644
index 00000000..57ea0b83
--- /dev/null
+++ b/frontend/src/components/tree/SourceNavigator.tsx
@@ -0,0 +1,277 @@
+import {
+  ChevronDown,
+  ChevronRight,
+  File,
+  Folder,
+  type LucideIcon,
+} from 'lucide-react';
+import { Fragment, useEffect, useMemo, useState } from 'react';
+
+import { useMediaQuery } from '@/hooks';
+import { cn } from '@/lib/utils';
+
+import { Button } from '../ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '../ui/command';
+import { Modal } from '../ui/modal';
+import {
+  ancestorIds,
+  filterNavigatorLeaves,
+  findNode,
+  type NavigatorNode,
+} from './navigatorUtils';
+
+const NO_HIGHLIGHT = '__none__';
+
+/**
+ * Tree indent, before the row's icons: a 24px step per level through depth 4
+ * (96px), then 12px per further level, so deep rows still step in but keep
+ * room for a label in the w-64 column.
+ */
+function Indent({ depth }: { depth: number }) {
+  if (depth <= 0) return null;
+  const width = Math.min(depth, 4) * 24 + Math.max(depth - 4, 0) * 12;
+  return (
+    <span
+      aria-hidden
+      className="w-(--indent) shrink-0"
+      style={{ '--indent': `${width}px` } as React.CSSProperties}
+    />
+  );
+}
+
+/** The folders to expand to show a node: its ancestors, and itself if a folder. */
+function revealIds(nodes: NavigatorNode[], id: string): string[] {
+  const trail = ancestorIds(nodes, id);
+  return findNode(nodes, id)?.kind === 'folder' ? [...trail, id] : trail;
+}
+
+export interface SourceNavigatorProps {
+  nodes: NavigatorNode[];
+  /** The open leaf or folder. */
+  selectedId: string | null;
+  onSelect: (node: NavigatorNode) => void;
+  /** Placeholder and accessible name of the filter ("Filter files"). */
+  filterLabel: string;
+  /** Shown when the filter matches nothing. */
+  emptyLabel: string;
+  /** Names the phone picker button and its sheet ("Files", "Pages"). */
+  title: string;
+  /**
+   * `tree`: folders expand and collapse, and a folder can be opened (the file
+   * tree). `groups`: each folder is a heading over its pages (the wiki).
+   */
+  folderMode?: 'tree' | 'groups';
+  leafIcon?: LucideIcon;
+  /** Layout only. */
+  className?: string;
+}
+
+/**
+ * The navigator column of a source view: a filter field over the source's
+ * files or pages, both in one Command, so the arrow keys walk from the field
+ * into the list. The open item is `checked`. Below `lg` it collapses into a
+ * combobox that opens the same list in a bottom sheet.
+ */
+export default function SourceNavigator({
+  nodes,
+  selectedId,
+  onSelect,
+  filterLabel,
+  emptyLabel,
+  title,
+  folderMode = 'tree',
+  leafIcon: LeafIcon = File,
+  className,
+}: SourceNavigatorProps) {
+  const { isDesktop } = useMediaQuery();
+  const [query, setQuery] = useState('');
+  const [sheetOpen, setSheetOpen] = useState(false);
+  // cmdk highlights its first row by default, which reads as hover; start the
+  // highlight on the open item instead and let the keys and pointer move it.
+  // With nothing open, a value that matches no row: an empty one lets cmdk
+  // pick the first row again.
+  const [highlight, setHighlight] = useState(selectedId ?? NO_HIGHLIGHT);
+  useEffect(() => setHighlight(selectedId ?? NO_HIGHLIGHT), [selectedId]);
+  const [expanded, setExpanded] = useState<Set<string>>(
+    () => new Set(selectedId ? revealIds(nodes, selectedId) : []),
+  );
+
+  // Opening an item elsewhere (a crumb, a table row, a search) reveals it in
+  // the tree; an opened folder expands too. Other open folders stay open.
+  useEffect(() => {
+    if (!selectedId) return;
+    const trail = revealIds(nodes, selectedId);
+    if (trail.length === 0) return;
+    setExpanded((prev) =>
+      trail.every((id) => prev.has(id)) ? prev : new Set([...prev, ...trail]),
+    );
+  }, [nodes, selectedId]);
+
+  const matches = useMemo(
+    () => filterNavigatorLeaves(nodes, query),
+    [nodes, query],
+  );
+
+  const choose = (node: NavigatorNode) => {
+    if (node.kind === 'folder' && folderMode === 'tree') {
+      setExpanded((prev) => {
+        const next = new Set(prev);
+        if (next.has(node.id) && node.id === selectedId) next.delete(node.id);
+        else next.add(node.id);
+        return next;
+      });
+    }
+    onSelect(node);
+    if (node.kind === 'leaf') {
+      setQuery('');
+      setSheetOpen(false);
+    }
+  };
+
+  const leafItem = (node: NavigatorNode, depth: number, meta?: string) => (
+    <CommandItem
+      key={node.id}
+      value={node.id}
+      checked={node.id === selectedId}
+      onSelect={() => choose(node)}
+      title={node.path}
+    >
+      <Indent depth={depth} />
+      <LeafIcon />
+      <span className="flex min-w-0 flex-1 flex-col">
+        <span className="truncate">{node.label}</span>
+        {meta ? (
+          <span className="text-muted-foreground truncate text-xs">{meta}</span>
+        ) : null}
+      </span>
+    </CommandItem>
+  );
+
+  const treeRows = (list: NavigatorNode[], depth: number): React.ReactNode =>
+    list.map((node) => {
+      if (node.kind === 'leaf') return leafItem(node, depth);
+      const open = expanded.has(node.id);
+      const Chevron = open ? ChevronDown : ChevronRight;
+      return (
+        <Fragment key={node.id}>
+          <CommandItem
+            value={node.id}
+            checked={node.id === selectedId}
+            onSelect={() => choose(node)}
+            aria-expanded={open}
+            title={node.path}
+          >
+            <Indent depth={depth} />
+            <Chevron />
+            <Folder className="text-primary" />
+            <span className="min-w-0 flex-1 truncate">{node.label}</span>
+            {node.count !== undefined ? (
+              <span className="text-muted-foreground text-xs tabular-nums">
+                {node.count}
+              </span>
+            ) : null}
+          </CommandItem>
+          {open ? treeRows(node.children ?? [], depth + 1) : null}
+        </Fragment>
+      );
+    });
+
+  const list = (
+    <Command
+      shouldFilter={false}
+      className="contents"
+      loop
+      value={highlight}
+      onValueChange={setHighlight}
+    >
+      <CommandInput
+        variant="field"
+        value={query}
+        onValueChange={setQuery}
+        placeholder={filterLabel}
+        aria-label={filterLabel}
+      />
+      {/* The column caps its own list; in the phone sheet the Modal body
+          scrolls, so the list grows with it (no second scroller). */}
+      <CommandList
+        className={
+          isDesktop ? 'max-h-[70svh] overscroll-contain' : 'max-h-none'
+        }
+      >
+        {query.trim() ? (
+          matches.length === 0 ? (
+            <CommandEmpty>{emptyLabel}</CommandEmpty>
+          ) : (
+            <CommandGroup>
+              {matches.map(({ node, parentPath }) =>
+                leafItem(node, 0, parentPath || undefined),
+              )}
+            </CommandGroup>
+          )
+        ) : folderMode === 'groups' ? (
+          <>
+            <CommandGroup>
+              {nodes
+                .filter((node) => node.kind === 'leaf')
+                .map((node) => leafItem(node, 0))}
+            </CommandGroup>
+            {nodes
+              .filter((node) => node.kind === 'folder')
+              .map((folder) => (
+                <CommandGroup key={folder.id} heading={folder.label}>
+                  {(folder.children ?? []).map((node) => leafItem(node, 0))}
+                </CommandGroup>
+              ))}
+          </>
+        ) : (
+          <CommandGroup>{treeRows(nodes, 0)}</CommandGroup>
+        )}
+      </CommandList>
+    </Command>
+  );
+
+  if (isDesktop) {
+    return (
+      <nav
+        aria-label={title}
+        className={cn('flex w-64 shrink-0 flex-col gap-2', className)}
+      >
+        {list}
+      </nav>
+    );
+  }
+
+  const current = selectedId ? findNode(nodes, selectedId) : undefined;
+  return (
+    <>
+      <Button
+        type="button"
+        variant="combobox"
+        size="field"
+        shape="pill"
+        className={cn('w-full justify-between', className)}
+        onClick={() => setSheetOpen(true)}
+        data-placeholder={current ? undefined : ''}
+        aria-haspopup="dialog"
+      >
+        <span className="truncate">{current?.label ?? title}</span>
+        <ChevronDown className="opacity-50" />
+      </Button>
+      <Modal
+        open={sheetOpen}
+        onOpenChange={setSheetOpen}
+        title={title}
+        mobileVariant="sheet"
+      >
+        <div className="flex flex-col gap-2">{list}</div>
+      </Modal>
+    </>
+  );
+}
diff --git a/frontend/src/components/tree/TreeBrowser.test.tsx b/frontend/src/components/tree/TreeBrowser.test.tsx
index b0680589..5be1e555 100644
--- a/frontend/src/components/tree/TreeBrowser.test.tsx
+++ b/frontend/src/components/tree/TreeBrowser.test.tsx
@@ -1,61 +1,96 @@
 import { act, useState } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 
+const { state } = vi.hoisted(() => ({
+  state: {
+    structure: {} as Record<string, unknown>,
+    chunks: [] as Record<string, unknown>[],
+  },
+}));
+
 vi.mock('react-i18next', () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts ? `${key} ${JSON.stringify(opts)}` : key,
+  }),
 }));
 
 vi.mock('react-redux', () => ({
   useSelector: () => null,
+  useDispatch: () => vi.fn(),
 }));
 
 vi.mock('../../hooks', () => ({
   useDarkTheme: () => [false],
   useDebouncedValue: (value: unknown) => value,
   useLoaderState: (initial: boolean) => useState(initial),
-  useMediaQuery: () => ({ isMobile: false }),
+  useMediaQuery: () => ({ isMobile: false, isDesktop: true }),
   useOutsideAlerter: () => undefined,
 }));
 
 vi.mock('../../api/services/userService', () => ({
   default: {
     getDirectoryStructure: vi.fn(async () => ({
-      json: async () => ({
-        directory_structure: {
-          legal: { '2024': { 'msa.pdf': { type: 'pdf', size_bytes: 10 } } },
-        },
-      }),
+      json: async () => ({ directory_structure: state.structure }),
     })),
     getDocumentChunks: vi.fn(async () => ({
       ok: true,
-      json: async () => ({ page: 1, per_page: 5, total: 0, chunks: [] }),
+      json: async () => ({
+        page: 1,
+        per_page: 12,
+        total: state.chunks.length,
+        chunks: state.chunks,
+      }),
     })),
   },
 }));
 
+import i18next from 'i18next';
+
+import userService from '../../api/services/userService';
 import TreeBrowser from './TreeBrowser';
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
-describe('TreeBrowser path crumbs', () => {
+const SOURCES = 'settings.sources.label';
+
+const NESTED = {
+  legal: {
+    '2024': { 'msa.pdf': { type: 'pdf', size_bytes: 10, token_count: 700 } },
+  },
+  'readme.md': { type: 'md', size_bytes: 5, token_count: 300 },
+};
+
+describe('TreeBrowser', () => {
   let container: HTMLDivElement;
   let root: Root;
+  let onBack: ReturnType<typeof vi.fn<() => void>>;
 
-  beforeEach(async () => {
-    container = document.createElement('div');
-    document.body.appendChild(container);
-    root = createRoot(container);
+  const render = async (
+    structure: Record<string, unknown>,
+    props: Partial<React.ComponentProps<typeof TreeBrowser>> = {},
+  ) => {
+    state.structure = structure;
     await act(async () => {
       root.render(
         <TreeBrowser
           docId="doc"
           sourceName="Contracts"
-          onBackToDocuments={vi.fn()}
+          onBackToDocuments={onBack}
           columnOrder="size-first"
-          topRightAction={null}
+          topRightAction={<button type="button">Add file</button>}
+          {...props}
         />,
       );
     });
+  };
+
+  beforeEach(() => {
+    onBack = vi.fn<() => void>();
+    state.chunks = [];
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
   });
 
   afterEach(async () => {
@@ -63,6 +98,11 @@ describe('TreeBrowser path crumbs', () => {
     container.remove();
   });
 
+  const rows = () =>
+    Array.from(container.querySelectorAll('tbody tr')).map((tr) =>
+      tr.querySelector('td')?.textContent?.trim(),
+    );
+
   const openRow = async (name: string) => {
     const row = Array.from(container.querySelectorAll('tr')).find(
       (tr) => tr.querySelector('td')?.textContent?.trim() === name,
@@ -86,26 +126,330 @@ describe('TreeBrowser path crumbs', () => {
     await act(async () => link.click());
   };
 
+  const navItem = (label: string) =>
+    Array.from(
+      container.querySelectorAll<HTMLElement>(
+        'nav[aria-label="settings.sources.files"] [data-slot="command-item"]',
+      ),
+    ).find((el) => el.textContent?.includes(label));
+
+  const tile = () =>
+    container.querySelector<HTMLButtonElement>('button[data-slot="card"]');
+
+  const chunkListOpen = () =>
+    container.textContent?.includes('settings.sources.searchChunks') ?? false;
+
   it('returns to the root and to a parent folder from the crumbs', async () => {
+    await render(NESTED);
     await openRow('legal');
     await openRow('2024');
-    expect(crumbs()).toEqual(['Contracts', 'legal', '2024']);
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'legal', '2024']);
 
     await clickCrumb('legal');
-    expect(crumbs()).toEqual(['Contracts', 'legal']);
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'legal']);
 
     await clickCrumb('Contracts');
-    expect(crumbs()).toEqual(['Contracts']);
+    expect(crumbs()).toEqual([SOURCES, 'Contracts']);
   });
 
-  it('a folder crumb in the chunk viewer returns to that folder', async () => {
+  it('one header: the open file is the last crumb and a folder crumb returns to it', async () => {
+    await render(NESTED);
     await openRow('legal');
     await openRow('2024');
     await openRow('msa.pdf');
-    expect(crumbs()).toEqual(['Contracts', 'legal', '2024', 'msa.pdf']);
+    expect(crumbs()).toEqual([
+      SOURCES,
+      'Contracts',
+      'legal',
+      '2024',
+      'msa.pdf',
+    ]);
+    expect(container.querySelectorAll('[data-slot="breadcrumb"]')).toHaveLength(
+      1,
+    );
+    expect(chunkListOpen()).toBe(true);
 
     await clickCrumb('legal');
-    expect(crumbs()).toEqual(['Contracts', 'legal']);
-    expect(container.textContent).toContain('2024');
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'legal']);
+    expect(rows()).toContain('2024');
   });
+
+  // Bugs row 8: the app language's separators, not the browser's.
+  it('formats the byline and token cells in the app language', async () => {
+    const language = i18next.language;
+    i18next.language = 'de';
+    try {
+      await render({
+        'big.pdf': { type: 'pdf', size_bytes: 10, token_count: 12345 },
+        'small.md': { type: 'md', size_bytes: 5, token_count: 300 },
+      });
+      expect(container.textContent).toContain(
+        'settings.sources.filesByline {"count":2,"files":"2","tokens":"12.645"}',
+      );
+      const cells = Array.from(container.querySelectorAll('td')).map(
+        (td) => td.textContent,
+      );
+      expect(cells).toContain('12.345');
+    } finally {
+      i18next.language = language;
+    }
+  });
+
+  it('shows the byline, badge and actions', async () => {
+    await render(NESTED, { badge: <span>BADGE</span>, statusLabel: 'Busy' });
+    expect(container.textContent).toContain(
+      'settings.sources.filesByline {"count":2,"files":"2","tokens":"1,000"}',
+    );
+    expect(container.textContent).toContain('BADGE');
+    expect(container.textContent).toContain('Busy');
+    expect(container.textContent).toContain('Add file');
+    expect(
+      container.querySelector('[data-slot="command-input"]'),
+    ).not.toBeNull();
+    // The old header search is gone; the navigator's filter replaces it.
+    expect(container.textContent).not.toContain('settings.sources.searchFiles');
+  });
+
+  it('opens folders and files from the navigator', async () => {
+    await render(NESTED);
+    await act(async () => navItem('legal')!.click());
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'legal']);
+    expect(rows()).toEqual(['2024']);
+    expect(navItem('legal')!.dataset.checked).toBeDefined();
+
+    await act(async () => navItem('readme.md')!.click());
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'readme.md']);
+    expect(chunkListOpen()).toBe(true);
+    expect(navItem('readme.md')!.getAttribute('data-checked')).not.toBeNull();
+  });
+
+  it('no back button or .. row: the Sources crumb leaves the source', async () => {
+    await render(NESTED);
+    await openRow('legal');
+    expect(container.querySelector('.lucide-arrow-left')).toBeNull();
+    expect(rows()).not.toContain('..');
+
+    await clickCrumb('Contracts');
+    expect(onBack).not.toHaveBeenCalled();
+    await clickCrumb(SOURCES);
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
+
+  it('an open chunk is the last crumb, and the file crumb closes it', async () => {
+    state.chunks = [{ doc_id: 'c1', text: '# Rates', metadata: {} }];
+    await render(NESTED);
+    await openRow('readme.md');
+    await act(async () => tile()!.click());
+    expect(crumbs()).toEqual([
+      SOURCES,
+      'Contracts',
+      'readme.md',
+      'settings.sources.chunkCrumb {"n":1}',
+    ]);
+
+    await clickCrumb('readme.md');
+    expect(tile()).not.toBeNull();
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'readme.md']);
+  });
+
+  it('a one-file source opens straight on its chunk list', async () => {
+    await render({ 'report.pdf': { type: 'pdf', display_name: 'Report' } });
+    expect(
+      container.querySelector('nav[aria-label="settings.sources.files"]'),
+    ).toBeNull();
+    expect(container.querySelector('table')).toBeNull();
+    expect(chunkListOpen()).toBe(true);
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'Report']);
+    expect(
+      container.querySelectorAll('[data-slot="breadcrumb-link"]'),
+    ).toHaveLength(1);
+
+    await clickCrumb(SOURCES);
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
+
+  it('a one-file source inside a folder also opens straight on it', async () => {
+    await render({ docs: { 'a.pdf': { type: 'pdf' } } });
+    expect(
+      container.querySelector('nav[aria-label="settings.sources.files"]'),
+    ).toBeNull();
+    expect(container.querySelector('table')).toBeNull();
+    expect(chunkListOpen()).toBe(true);
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'a.pdf']);
+  });
+
+  it("a one-file source keeps the row menu's Delete in the header", async () => {
+    const getRowMenuOptions = vi.fn(
+      ({
+        defaultViewOption,
+        name,
+      }: {
+        defaultViewOption: unknown;
+        name: string;
+      }) => [defaultViewOption, { label: `delete ${name}`, onClick: vi.fn() }],
+    );
+    await render({ docs: { 'a.pdf': { type: 'pdf' } } }, {
+      getRowMenuOptions,
+    } as Partial<React.ComponentProps<typeof TreeBrowser>>);
+    expect(getRowMenuOptions).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'docs/a.pdf', isFile: true }),
+    );
+    expect(
+      container.querySelector('button[aria-label="settings.sources.menuAlt"]'),
+    ).not.toBeNull();
+  });
+
+  it('a failed load says so and retries', async () => {
+    const getDirectoryStructure = vi.mocked(userService.getDirectoryStructure);
+    getDirectoryStructure.mockImplementationOnce(async () => {
+      throw new Error('offline');
+    });
+    await render(NESTED);
+    expect(container.textContent).toContain('settings.sources.filesLoadError');
+    const retry = Array.from(container.querySelectorAll('button')).find(
+      (el) => el.textContent === 'retry',
+    )!;
+    await act(async () => retry.click());
+    expect(container.textContent).not.toContain(
+      'settings.sources.filesLoadError',
+    );
+    expect(rows()).toEqual(['legal', 'readme.md']);
+  });
+
+  it('unmounting clears the crumbs it reported', async () => {
+    const onCrumbsChange = vi.fn();
+    await render(NESTED, { embedded: true, onCrumbsChange });
+    expect(onCrumbsChange.mock.lastCall![0]).toHaveLength(1);
+    await act(async () => root.unmount());
+    expect(onCrumbsChange.mock.lastCall![0]).toEqual([]);
+    root = createRoot(container);
+  });
+
+  it('a crumb step keeps focus in the header, on the new current crumb', async () => {
+    await render(NESTED);
+    await openRow('legal');
+    await openRow('2024');
+    const link = Array.from(
+      container.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="breadcrumb-link"]',
+      ),
+    ).find((el) => el.textContent === 'legal')!;
+    link.focus();
+    await act(async () => link.click());
+    const current = container.querySelector('[data-slot="breadcrumb-page"]')!;
+    expect(current.textContent).toBe('legal');
+    expect(document.activeElement).toBe(current);
+  });
+
+  it('embedded: no Sources crumb, badge or byline', async () => {
+    await render(NESTED, { embedded: true, badge: <span>BADGE</span> });
+    expect(crumbs()).toEqual(['Contracts']);
+    expect(container.textContent).not.toContain('BADGE');
+    expect(container.textContent).not.toContain('settings.sources.filesByline');
+    expect(container.textContent).toContain('Add file');
+  });
+
+  it('embedded with an actions slot: no row of its own, actions in the slot', async () => {
+    const slot = document.createElement('div');
+    document.body.appendChild(slot);
+    const onCrumbsChange = vi.fn();
+    await render(NESTED, {
+      embedded: true,
+      actionsTarget: slot,
+      onCrumbsChange,
+    });
+    expect(container.querySelector('[data-slot="breadcrumb"]')).toBeNull();
+    expect(container.textContent).not.toContain('Add file');
+    expect(slot.textContent).toContain('Add file');
+    slot.remove();
+
+    // The host draws the crumbs: the tree reports where it is.
+    const labels = () =>
+      (
+        onCrumbsChange.mock.lastCall![0] as {
+          label: string;
+          onSelect?: () => void;
+        }[]
+      ).map((crumb) => crumb.label);
+    expect(labels()).toEqual(['Contracts']);
+    await openRow('legal');
+    expect(labels()).toEqual(['Contracts', 'legal']);
+    await act(async () => onCrumbsChange.mock.lastCall![0][0].onSelect());
+    expect(labels()).toEqual(['Contracts']);
+  });
+
+  it('initialPath opens a nested file by its name, and again when it changes', async () => {
+    await render(NESTED, { initialPath: 'msa.pdf' });
+    expect(crumbs()).toEqual([
+      SOURCES,
+      'Contracts',
+      'legal',
+      '2024',
+      'msa.pdf',
+    ]);
+    expect(chunkListOpen()).toBe(true);
+    expect(navItem('msa.pdf')!.getAttribute('data-checked')).not.toBeNull();
+
+    await render(NESTED, { initialPath: 'readme.md' });
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'readme.md']);
+  });
+
+  it('initialPath matches a full path or a display name', async () => {
+    const structure = {
+      docs: {
+        'x_1.docx': { type: 'docx', display_name: 'Carrier profile.docx' },
+      },
+      'y.md': { type: 'md' },
+    };
+    await render(structure, { initialPath: 'Carrier profile.docx' });
+    expect(crumbs()).toEqual([
+      SOURCES,
+      'Contracts',
+      'docs',
+      'Carrier profile.docx',
+    ]);
+
+    await render(structure, { initialPath: 'y.md' });
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'y.md']);
+  });
+
+  it('an initialPath not in the tree yet opens once a reload has it', async () => {
+    const controllerRef: React.ComponentProps<
+      typeof TreeBrowser
+    >['controllerRef'] = { current: null };
+    await render(NESTED, { initialPath: 'new.pdf', controllerRef });
+    expect(chunkListOpen()).toBe(false);
+    state.structure = { ...NESTED, 'new.pdf': { type: 'pdf' } };
+    await act(async () => {
+      await controllerRef.current!.refreshDirectory();
+    });
+    expect(crumbs()).toEqual([SOURCES, 'Contracts', 'new.pdf']);
+  });
+
+  it('an unknown initialPath leaves the root open', async () => {
+    await render(NESTED, { initialPath: 'missing.pdf' });
+    expect(crumbs()).toEqual([SOURCES, 'Contracts']);
+    expect(chunkListOpen()).toBe(false);
+  });
+
+  // Numbers read down a column: size and tokens are right-aligned with
+  // tabular figures in either column order, headers included.
+  it.each(['size-first', 'tokens-first'] as const)(
+    'right-aligns the numeric columns (%s)',
+    async (columnOrder) => {
+      await render(NESTED, { columnOrder });
+      const headers = Array.from(container.querySelectorAll('thead th'));
+      [1, 2].forEach((index) =>
+        expect(headers[index].className).toContain('text-right'),
+      );
+      const row = Array.from(container.querySelectorAll('tbody tr')).find(
+        (tr) => tr.querySelector('td')?.textContent?.trim() === 'readme.md',
+      )!;
+      const cells = Array.from(row.querySelectorAll('td'));
+      [1, 2].forEach((index) => {
+        expect(cells[index].className).toContain('text-right');
+        expect(cells[index].className).toContain('tabular-nums');
+      });
+    },
+  );
 });
diff --git a/frontend/src/components/tree/TreeBrowser.tsx b/frontend/src/components/tree/TreeBrowser.tsx
index 4863d3a8..e8d83388 100644
--- a/frontend/src/components/tree/TreeBrowser.tsx
+++ b/frontend/src/components/tree/TreeBrowser.tsx
@@ -1,29 +1,26 @@
+import { createPortal } from 'react-dom';
 import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
 } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 import { selectToken } from '../../preferences/preferenceSlice';
+import { formatCount } from '../../utils/dateTimeUtils';
 import { formatBytes } from '../../utils/stringUtils';
 import userService from '../../api/services/userService';
 import { Eye, File, Folder } from 'lucide-react';
-import { useLoaderState, useOutsideAlerter } from '../../hooks';
-import Chunks from '../Chunks';
-import PathHeader from './PathHeader';
+import { Button } from '../ui/button';
+import { EmptyState } from '../ui/empty-state';
+import { useLoaderState } from '../../hooks';
+import Chunks, { type ChunksController } from '../Chunks';
+import PathHeader, { type Crumb } from './PathHeader';
+import SourceNavigator from './SourceNavigator';
 import SkeletonLoader from '../SkeletonLoader';
-import { cn, fieldFrame } from '@/lib/utils';
-import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-} from '../ui/command';
 import {
   Table,
   TableBody,
@@ -34,11 +31,15 @@ import {
   TableRow,
 } from '../ui/table';
 import { ActionMenu, type MenuOption } from '../ui/dropdown-menu';
+import {
+  countLeaves,
+  directoryToNavigator,
+  type NavigatorNode,
+} from './navigatorUtils';
 import type {
   DirectoryStructure,
   FileNode,
   RowMenuContext,
-  SearchResult,
   TreeBrowserController,
 } from './types';
 
@@ -86,15 +87,70 @@ export interface TreeBrowserProps {
    * navigation state.
    */
   onCurrentPathChange?: (path: string[]) => void;
+  /** The source kind (a neutral Badge) after the crumbs. */
+  badge?: React.ReactNode;
+  /**
+   * Rendered inside another source view (the graph source's Files tab): no
+   * Sources crumb, no badge and no byline.
+   */
+  embedded?: boolean;
+  /**
+   * Embedded only: the tree's crumbs (the source, its folders, the open file
+   * and chunk), for a host that draws them in its own header.
+   */
+  onCrumbsChange?: (crumbs: Crumb[]) => void;
+  /**
+   * Embedded only: the host header's action slot. The tree then draws no row
+   * of its own and portals its status and `topRightAction` (Add file, Sync)
+   * into the slot, so a tab's action sits in the page header.
+   */
+  actionsTarget?: HTMLElement | null;
+  /**
+   * A file to open once the structure loads (the graph's "Open in Files"):
+   * its full path, its file name or its display name. Applied again when it
+   * changes.
+   */
+  initialPath?: string;
 }
 
-// The search field's frame: the pill Input look around a CommandInput
-// (38px, focus ring while the input has keyboard focus). CommandInput's row
-// is 36px with a bottom rule; pt-px + overflow-hidden clips that rule.
-const SEARCH_FRAME = cn(
-  fieldFrame,
-  'border-border has-[input:focus-visible]:border-ring has-[input:focus-visible]:ring-ring/50 h-9.5 overflow-hidden rounded-full px-2 pt-px has-[input:focus-visible]:ring-3',
-);
+/**
+ * Every file in the navigator tree, in tree order.
+ *
+ * @param nodes The navigator tree.
+ * @returns The leaves.
+ */
+function collectLeaves(nodes: NavigatorNode[]): NavigatorNode[] {
+  const leaves: NavigatorNode[] = [];
+  const walk = (list: NavigatorNode[]) => {
+    for (const node of list) {
+      if (node.kind === 'leaf') leaves.push(node);
+      else walk(node.children ?? []);
+    }
+  };
+  walk(nodes);
+  return leaves;
+}
+
+/**
+ * The file an `initialPath` names: an exact path first, then a file whose
+ * name (last path segment) or display name matches.
+ *
+ * @param nodes The navigator tree.
+ * @param target The path or name to look for.
+ * @returns The leaf, or undefined.
+ */
+function findFileByPathOrName(
+  nodes: NavigatorNode[],
+  target: string,
+): NavigatorNode | undefined {
+  const leaves = collectLeaves(nodes);
+  return (
+    leaves.find((leaf) => leaf.path === target) ??
+    leaves.find(
+      (leaf) => leaf.path.split('/').pop() === target || leaf.label === target,
+    )
+  );
+}
 
 function calculateDirectoryStats(structure: DirectoryStructure): {
   totalSize: number;
@@ -117,81 +173,6 @@ function calculateDirectoryStats(structure: DirectoryStructure): {
   return { totalSize, totalTokens };
 }
 
-function searchFiles(
-  query: string,
-  structure: DirectoryStructure,
-  currentPath: string[] = [],
-): SearchResult[] {
-  let results: SearchResult[] = [];
-
-  Object.entries(structure).forEach(([name, node]) => {
-    const fullPath = [...currentPath, name].join('/');
-    const displayName =
-      typeof node.display_name === 'string' && node.display_name.trim()
-        ? node.display_name
-        : '';
-    const queryLower = query.toLowerCase();
-    const matchTarget = displayName ? `${name} ${displayName}` : name;
-
-    if (matchTarget.toLowerCase().includes(queryLower)) {
-      results.push({
-        name: displayName || name,
-        path: fullPath,
-        isFile: !!node.type,
-      });
-    }
-
-    if (!node.type) {
-      results = [
-        ...results,
-        ...searchFiles(query, node as DirectoryStructure, [
-          ...currentPath,
-          name,
-        ]),
-      ];
-    }
-  });
-
-  return results;
-}
-
-function resolveDisplayName(
-  directoryStructure: DirectoryStructure | null,
-  path: string,
-): string {
-  if (!directoryStructure) {
-    return path.split('/').pop() || path;
-  }
-  let structure: any = directoryStructure;
-  if (typeof structure === 'string') {
-    try {
-      structure = JSON.parse(structure);
-    } catch (e) {
-      return path.split('/').pop() || path;
-    }
-  }
-  if (typeof structure !== 'object' || structure === null) {
-    return path.split('/').pop() || path;
-  }
-  const parts = path.split('/').filter(Boolean);
-  let current: any = structure;
-  for (const part of parts) {
-    if (!current || typeof current !== 'object') {
-      return parts[parts.length - 1] || path;
-    }
-    current = current[part];
-  }
-  if (
-    current &&
-    typeof current === 'object' &&
-    typeof current.display_name === 'string' &&
-    current.display_name.trim()
-  ) {
-    return current.display_name;
-  }
-  return parts[parts.length - 1] || path;
-}
-
 const TreeBrowser: React.FC<TreeBrowserProps> = ({
   docId,
   sourceName,
@@ -205,10 +186,17 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
   onDirectoryDataLoaded,
   controllerRef,
   onCurrentPathChange,
+  badge,
+  embedded = false,
+  actionsTarget,
+  initialPath,
+  onCrumbsChange,
 }) => {
   const { t } = useTranslation();
   const [loading, setLoading] = useLoaderState(true, 500);
-  const [, setError] = useState<string | null>(null);
+  const [loadFailed, setLoadFailed] = useState(false);
+  // Bumped to refetch the structure (Retry).
+  const [reloadKey, setReloadKey] = useState(0);
   const [directoryStructure, setDirectoryStructure] =
     useState<DirectoryStructure | null>(null);
   const [currentPath, setCurrentPath] = useState<string[]>([]);
@@ -217,10 +205,12 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
     id: string;
     name: string;
   } | null>(null);
-  const [searchQuery, setSearchQuery] = useState('');
-  const [searchResults, setSearchResults] = useState<SearchResult[]>([]);
-  const searchDropdownRef = useRef<HTMLDivElement>(null);
   const mountedRef = useRef(true);
+  // The open file's open chunk (its crumb), reported by Chunks.
+  const [openChunkPosition, setOpenChunkPosition] = useState<number | null>(
+    null,
+  );
+  const chunksControllerRef = useRef<ChunksController | null>(null);
 
   useEffect(
     () => () => {
@@ -239,16 +229,6 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
     onCurrentPathChangeRef.current?.(currentPath);
   }, [currentPath]);
 
-  useOutsideAlerter(
-    searchDropdownRef,
-    () => {
-      setSearchQuery('');
-      setSearchResults([]);
-    },
-    [],
-    false,
-  );
-
   const handleFileClick = useCallback(
     (fileName: string, displayName?: string) => {
       const fullPath = [...currentPath, fileName].join('/');
@@ -261,10 +241,6 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
     setCurrentPath((prev) => [...prev, dirName]);
   }, []);
 
-  const navigateUp = useCallback(() => {
-    setCurrentPath((prev) => prev.slice(0, -1));
-  }, []);
-
   const refreshDirectory = useCallback(async () => {
     try {
       const response = await userService.getDirectoryStructure(docId, token);
@@ -283,6 +259,7 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
   }, [docId, token]);
 
   const resetPath = useCallback(() => {
+    setSelectedFile(null);
     setCurrentPath([]);
   }, []);
 
@@ -293,30 +270,34 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
   );
 
   useEffect(() => {
+    if (!docId) return;
+    let cancelled = false;
     const fetchDirectoryStructure = async () => {
       try {
         setLoading(true);
+        setLoadFailed(false);
         const response = await userService.getDirectoryStructure(docId, token);
         const data = await response.json();
-
+        if (cancelled) return;
         if (data && data.directory_structure) {
           setDirectoryStructure(data.directory_structure);
           onDirectoryDataLoadedRef.current?.(data);
         } else {
-          setError('Invalid response format');
+          setLoadFailed(true);
         }
       } catch (err) {
-        setError('Failed to load directory structure');
         console.error(err);
+        if (!cancelled) setLoadFailed(true);
       } finally {
-        setLoading(false);
+        if (!cancelled) setLoading(false);
       }
     };
 
-    if (docId) {
-      fetchDirectoryStructure();
-    }
-  }, [docId, token]);
+    fetchDirectoryStructure();
+    return () => {
+      cancelled = true;
+    };
+  }, [docId, token, reloadKey]);
 
   const getCurrentDirectory = useCallback((): DirectoryStructure => {
     if (!directoryStructure) return {};
@@ -353,51 +334,67 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
     return current;
   }, [directoryStructure, currentPath]);
 
-  const handleBackNavigation = () => {
-    if (selectedFile) {
-      setSelectedFile(null);
-    } else if (currentPath.length === 0) {
-      onBackToDocuments?.();
-    } else {
-      navigateUp();
+  // The navigator's tree; a source with exactly one file (at any depth)
+  // opens straight on that file, with no navigator and no table.
+  const navigatorNodes = useMemo(
+    () => directoryToNavigator(directoryStructure),
+    [directoryStructure],
+  );
+  const singleFile = useMemo(() => {
+    const leaves = collectLeaves(navigatorNodes);
+    return leaves.length === 1 ? leaves[0] : null;
+  }, [navigatorNodes]);
+  const openFile = singleFile
+    ? { id: singleFile.path, name: singleFile.label }
+    : selectedFile;
+
+  const byline = useMemo(() => {
+    if (embedded || !directoryStructure) return undefined;
+    let structure: unknown = directoryStructure;
+    if (typeof structure === 'string') {
+      try {
+        structure = JSON.parse(structure);
+      } catch {
+        structure = {};
+      }
     }
-  };
-
-  const handleSearchSelect = (result: SearchResult) => {
-    if (result.isFile) {
-      const pathParts = result.path.split('/');
-      const fileName = pathParts.pop() || '';
-      setCurrentPath(pathParts);
-
-      setSelectedFile({
-        id: result.path,
-        name: result.name || fileName,
-      });
-    } else {
-      setCurrentPath(result.path.split('/'));
-      setSelectedFile(null);
-    }
-    setSearchQuery('');
-    setSearchResults([]);
-  };
-
-  const handleFileSearch = (q: string): SearchResult[] => {
-    if (directoryStructure) {
-      return searchFiles(q, directoryStructure);
-    }
-    return [];
-  };
-
-  const handleFileSelect = (path: string) => {
-    const pathParts = path.split('/');
-    const fileName = pathParts.pop() || '';
-    setCurrentPath(pathParts);
-    setSelectedFile({
-      id: path,
-      name: resolveDisplayName(directoryStructure, path) || fileName,
+    const { totalTokens } = calculateDirectoryStats(
+      structure && typeof structure === 'object'
+        ? (structure as DirectoryStructure)
+        : {},
+    );
+    const files = countLeaves(navigatorNodes);
+    return t('settings.sources.filesByline', {
+      count: files,
+      files: formatCount(files),
+      tokens: formatCount(totalTokens),
     });
+  }, [embedded, directoryStructure, navigatorNodes, t]);
+
+  const handleNavigatorSelect = (node: NavigatorNode) => {
+    const parts = node.path.split('/');
+    if (node.kind === 'folder') {
+      setSelectedFile(null);
+      setCurrentPath(parts);
+    } else {
+      setCurrentPath(parts.slice(0, -1));
+      setSelectedFile({ id: node.path, name: node.label });
+    }
   };
 
+  // Open the file the caller asked for, once per new initialPath; a path not
+  // found yet is tried again when the structure reloads.
+  const appliedInitialPath = useRef<string | null>(null);
+  useEffect(() => {
+    if (!initialPath || !directoryStructure) return;
+    if (appliedInitialPath.current === initialPath) return;
+    const file = findFileByPathOrName(navigatorNodes, initialPath);
+    if (!file) return;
+    appliedInitialPath.current = initialPath;
+    setCurrentPath(file.path.split('/').slice(0, -1));
+    setSelectedFile({ id: file.path, name: file.label });
+  }, [initialPath, directoryStructure, navigatorNodes]);
+
   const buildDefaultViewOption = (
     name: string,
     isFile: boolean,
@@ -453,28 +450,36 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
    */
   const renderColumnPair = (sizeBytes: number, tokens: number) => {
     const sizeDisplay = sizeBytes > 0 ? formatBytes(sizeBytes) : '-';
-    const tokensDisplay = tokens > 0 ? tokens.toLocaleString() : '-';
+    const tokensDisplay = tokens > 0 ? formatCount(tokens) : '-';
 
-    if (columnOrder === 'size-first') {
-      return (
-        <>
-          <TableCell width="30%" align="left">
-            {sizeDisplay}
-          </TableCell>
-          <TableCell width="20%" align="right">
-            {tokensDisplay}
-          </TableCell>
-        </>
-      );
-    }
-    return (
+    // Numbers read down a column: right-aligned, tabular figures.
+    const size = (
+      <TableCell
+        width={columnOrder === 'size-first' ? '30%' : '20%'}
+        align="right"
+        className="whitespace-nowrap tabular-nums"
+      >
+        {sizeDisplay}
+      </TableCell>
+    );
+    const tokenCell = (
+      <TableCell
+        width={columnOrder === 'size-first' ? '20%' : '30%'}
+        align="right"
+        className="tabular-nums"
+      >
+        {tokensDisplay}
+      </TableCell>
+    );
+    return columnOrder === 'size-first' ? (
       <>
-        <TableCell width="30%" align="left">
-          {tokensDisplay}
-        </TableCell>
-        <TableCell width="20%" align="left">
-          {sizeDisplay}
-        </TableCell>
+        {size}
+        {tokenCell}
+      </>
+    ) : (
+      <>
+        {tokenCell}
+        {size}
       </>
     );
   };
@@ -496,30 +501,6 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
     const directories = sortedEntries.filter(([, node]) => !node.type);
     const files = sortedEntries.filter(([, node]) => node.type);
 
-    const parentRow =
-      currentPath.length > 0
-        ? [
-            <TableRow key="parent-dir" onClick={navigateUp}>
-              <TableCell width="40%" align="left">
-                <div className="flex items-center gap-2">
-                  <Folder className="text-primary size-4 shrink-0" />
-                  <span className="truncate">..</span>
-                </div>
-              </TableCell>
-              <TableCell width="30%" align="left">
-                -
-              </TableCell>
-              <TableCell
-                width="20%"
-                align={columnOrder === 'size-first' ? 'right' : 'left'}
-              >
-                -
-              </TableCell>
-              <TableCell width="10%" align="right"></TableCell>
-            </TableRow>,
-          ]
-        : [];
-
     const directoryRows = directories.map(([name, node]) => {
       const itemId = `dir-${name}`;
       const dirStats = calculateDirectoryStats(node as DirectoryStructure);
@@ -570,162 +551,235 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
       );
     });
 
-    return [...parentRow, ...directoryRows, ...fileRows];
+    return [...directoryRows, ...fileRows];
   };
 
-  const renderFileSearch = () => (
-    <div className="relative w-52" ref={searchDropdownRef}>
-      {/* `contents`: the Command only scopes cmdk (the arrow keys move from
-          the input to the rows); the frame and the dropdown draw the look. */}
-      <Command shouldFilter={false} className="contents">
-        <div className={SEARCH_FRAME}>
-          <CommandInput
-            value={searchQuery}
-            onValueChange={(value) => {
-              setSearchQuery(value);
-              if (directoryStructure) {
-                setSearchResults(searchFiles(value, directoryStructure));
-              }
-            }}
-            placeholder={t('settings.sources.searchFiles')}
-          />
-        </div>
-
-        {searchQuery && (
-          <div className="border-border bg-popover text-popover-foreground absolute top-full right-0 left-0 z-20 mt-1 w-full overflow-hidden rounded-xl border shadow-md">
-            <CommandList className="max-h-[calc(100dvh-200px)] overscroll-contain">
-              {searchResults.length === 0 ? (
-                <CommandEmpty>{t('settings.sources.noResults')}</CommandEmpty>
-              ) : (
-                <CommandGroup>
-                  {searchResults.map((result) => (
-                    <CommandItem
-                      key={result.path}
-                      value={result.path}
-                      title={result.path}
-                      onSelect={() => handleSearchSelect(result)}
-                    >
-                      {result.isFile ? (
-                        <File />
-                      ) : (
-                        <Folder className="text-primary" />
-                      )}
-                      <span className="min-w-0 flex-1 truncate">
-                        {result.name}
-                      </span>
-                    </CommandItem>
-                  ))}
-                </CommandGroup>
-              )}
-            </CommandList>
-          </div>
-        )}
-      </Command>
-    </div>
-  );
-
   // Crumb n opens the folder made of the first n path segments (0 = root).
   const openPathDepth = useCallback((depth: number) => {
     setSelectedFile(null);
     setCurrentPath((prev) => prev.slice(0, depth));
   }, []);
 
-  const renderPathNavigation = () => (
-    <PathHeader
-      root={{
-        label: sourceName,
-        onSelect: currentPath.length > 0 ? () => openPathDepth(0) : undefined,
-      }}
-      segments={currentPath.map((dir, index) => ({
-        label: dir,
-        onSelect:
-          index < currentPath.length - 1
-            ? () => openPathDepth(index + 1)
-            : undefined,
-      }))}
-      onBack={handleBackNavigation}
-      backLabel={t('settings.sources.back')}
-      actions={
-        <>
-          {statusLabel && (
-            <div className="text-muted-foreground text-sm">{statusLabel}</div>
-          )}
-          {renderFileSearch()}
-          {topRightAction}
-        </>
-      }
-    />
+  // The source, the open folder's path, the open file, then the open chunk;
+  // every crumb but the current (last) one opens its level.
+  const folderPath = singleFile ? [] : currentPath;
+  const chunkOpen = !!openFile && openChunkPosition !== null;
+  const depth = folderPath.length + (openFile ? 1 : 0) + (chunkOpen ? 1 : 0);
+  const treeCrumbs: Crumb[] = [
+    {
+      label: sourceName,
+      onSelect: !singleFile && depth > 0 ? () => openPathDepth(0) : undefined,
+    },
+    ...folderPath.map((dir, index) => ({
+      label: dir,
+      onSelect: index < depth - 1 ? () => openPathDepth(index + 1) : undefined,
+    })),
+    ...(openFile
+      ? [
+          {
+            label: openFile.name,
+            onSelect: chunkOpen
+              ? () => chunksControllerRef.current?.closeChunk()
+              : undefined,
+          },
+        ]
+      : []),
+    ...(chunkOpen
+      ? [
+          {
+            label: t('settings.sources.chunkCrumb', { n: openChunkPosition }),
+          },
+        ]
+      : []),
+  ];
+
+  // An embedded tree's host draws the crumbs; report them when they change.
+  const treeCrumbsRef = useRef(treeCrumbs);
+  const onCrumbsChangeRef = useRef(onCrumbsChange);
+  useEffect(() => {
+    treeCrumbsRef.current = treeCrumbs;
+    onCrumbsChangeRef.current = onCrumbsChange;
+  });
+  const crumbsKey = treeCrumbs
+    .map((crumb) => `${crumb.label}${crumb.onSelect ? '>' : ''}`)
+    .join('/');
+  useEffect(() => {
+    onCrumbsChangeRef.current?.(treeCrumbsRef.current);
+  }, [crumbsKey]);
+  // Leaving (the host's tab changes) clears them, so a remount never shows
+  // the previous trail.
+  useEffect(() => () => onCrumbsChangeRef.current?.([]), []);
+
+  // A single-file source shows no table, so its row menu (Delete) moves to
+  // the header, less the View option (the file is already open). The path
+  // sits at the root, so the file's name is its full path.
+  useEffect(() => {
+    if (singleFile) setCurrentPath((prev) => (prev.length ? [] : prev));
+  }, [singleFile]);
+  const singleFileMenu = (() => {
+    if (!singleFile || !getRowMenuOptions) return null;
+    const defaultViewOption = buildDefaultViewOption(
+      singleFile.path,
+      true,
+      singleFile.label,
+    );
+    const options = getRowMenuOptions({
+      name: singleFile.path,
+      isFile: true,
+      itemId: `file-${singleFile.path}`,
+      displayName: singleFile.label,
+      defaultViewOption,
+    }).filter((option) => option !== defaultViewOption);
+    if (options.length === 0) return null;
+    return (
+      <ActionMenu
+        size="toolbar"
+        options={options}
+        triggerLabel={t('settings.sources.menuAlt')}
+      />
+    );
+  })();
+
+  const headerActions = (
+    <>
+      {statusLabel && (
+        <div className="text-muted-foreground text-sm">{statusLabel}</div>
+      )}
+      {singleFileMenu}
+      {topRightAction}
+    </>
   );
 
+  const renderPathNavigation = () => {
+    const [sourceCrumb, ...rest] = treeCrumbs;
+    return (
+      <PathHeader
+        root={
+          embedded
+            ? sourceCrumb
+            : {
+                label: t('settings.sources.label'),
+                onSelect: onBackToDocuments,
+              }
+        }
+        segments={embedded ? rest : treeCrumbs}
+        badge={embedded ? undefined : badge}
+        byline={byline}
+        actions={headerActions}
+      />
+    );
+  };
+
   const currentDirectory = getCurrentDirectory();
 
-  return (
-    <div>
-      {selectedFile ? (
-        <div className="flex">
-          <div className="flex-1">
-            <Chunks
-              documentId={docId}
-              documentName={sourceName}
-              handleGoBack={() => setSelectedFile(null)}
-              path={selectedFile.id}
-              displayPath={[...currentPath, selectedFile.name].join('/')}
-              onFileSearch={handleFileSearch}
-              onFileSelect={handleFileSelect}
-              onPathSelect={openPathDepth}
-            />
-          </div>
-        </div>
-      ) : (
-        <div className="flex w-full max-w-full flex-col overflow-x-clip">
-          <div className="mb-2">{renderPathNavigation()}</div>
+  const renderChunks = (file: { id: string; name: string }) => (
+    <Chunks
+      key={file.id}
+      embedded
+      documentId={docId}
+      documentName={sourceName}
+      handleGoBack={() => setSelectedFile(null)}
+      path={file.id}
+      fileName={file.name}
+      controllerRef={chunksControllerRef}
+      onOpenChunkChange={setOpenChunkPosition}
+    />
+  );
 
-          <div className="w-full">
-            <TableContainer>
-              <Table>
-                <TableHead>
-                  <TableRow>
-                    <TableHeader width="40%" align="left">
-                      {t('settings.sources.fileName')}
-                    </TableHeader>
-                    {columnOrder === 'size-first' ? (
-                      <>
-                        <TableHeader width="30%" align="left">
-                          {t('settings.sources.size')}
-                        </TableHeader>
-                        <TableHeader width="20%" align="right">
-                          {t('settings.sources.tokens')}
-                        </TableHeader>
-                      </>
-                    ) : (
-                      <>
-                        <TableHeader width="30%" align="left">
-                          {t('settings.sources.tokens')}
-                        </TableHeader>
-                        <TableHeader width="20%" align="left">
-                          {t('settings.sources.size')}
-                        </TableHeader>
-                      </>
-                    )}
-                    <TableHeader width="10%" align="right">
-                      <span className="sr-only">
-                        {t('settings.sources.actions')}
-                      </span>
-                    </TableHeader>
-                  </TableRow>
-                </TableHead>
-                <TableBody>
-                  {loading ? (
-                    <SkeletonLoader component="fileTable" />
-                  ) : (
-                    renderFileTree(currentDirectory)
-                  )}
-                </TableBody>
-              </Table>
-            </TableContainer>
-          </div>
+  const renderTable = () => (
+    <TableContainer>
+      <Table>
+        <TableHead>
+          <TableRow>
+            <TableHeader width="40%" align="left">
+              {t('settings.sources.fileName')}
+            </TableHeader>
+            {columnOrder === 'size-first' ? (
+              <>
+                <TableHeader width="30%" align="right">
+                  {t('settings.sources.size')}
+                </TableHeader>
+                <TableHeader width="20%" align="right">
+                  {t('settings.sources.tokens')}
+                </TableHeader>
+              </>
+            ) : (
+              <>
+                <TableHeader width="30%" align="right">
+                  {t('settings.sources.tokens')}
+                </TableHeader>
+                <TableHeader width="20%" align="right">
+                  {t('settings.sources.size')}
+                </TableHeader>
+              </>
+            )}
+            <TableHeader width="10%" align="right">
+              <span className="sr-only">{t('settings.sources.actions')}</span>
+            </TableHeader>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {loading ? (
+            <SkeletonLoader component="fileTable" />
+          ) : (
+            renderFileTree(currentDirectory)
+          )}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+
+  const renderContent = () => {
+    if (loading) return renderTable();
+    if (loadFailed) {
+      return (
+        <EmptyState
+          tone="destructive"
+          illustration="none"
+          title={t('settings.sources.filesLoadError')}
+          action={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              shape="pill"
+              onClick={() => setReloadKey((key) => key + 1)}
+            >
+              {t('retry')}
+            </Button>
+          }
+        />
+      );
+    }
+    if (singleFile) return renderChunks(openFile!);
+    if (navigatorNodes.length === 0) return renderTable();
+    return (
+      <div className="flex flex-col gap-4 lg:flex-row lg:gap-6">
+        <SourceNavigator
+          nodes={navigatorNodes}
+          selectedId={
+            selectedFile?.id ??
+            (currentPath.length > 0 ? currentPath.join('/') : null)
+          }
+          onSelect={handleNavigatorSelect}
+          folderMode="tree"
+          filterLabel={t('settings.sources.filterFiles')}
+          emptyLabel={t('settings.sources.noResults')}
+          title={t('settings.sources.files')}
+        />
+        <div className="min-w-0 flex-1">
+          {selectedFile ? renderChunks(selectedFile) : renderTable()}
         </div>
-      )}
+      </div>
+    );
+  };
+
+  return (
+    <div className="flex w-full max-w-full min-w-0 flex-col gap-4">
+      {embedded && actionsTarget
+        ? createPortal(headerActions, actionsTarget)
+        : renderPathNavigation()}
+      {renderContent()}
       {extraContent}
     </div>
   );
diff --git a/frontend/src/components/tree/navigatorUtils.test.ts b/frontend/src/components/tree/navigatorUtils.test.ts
new file mode 100644
index 00000000..cec89ad1
--- /dev/null
+++ b/frontend/src/components/tree/navigatorUtils.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  ancestorIds,
+  countLeaves,
+  directoryToNavigator,
+  filterNavigatorLeaves,
+  findNode,
+  type NavigatorNode,
+} from './navigatorUtils';
+
+const tree: NavigatorNode[] = [
+  {
+    id: 'briefs',
+    kind: 'folder',
+    label: 'briefs',
+    path: 'briefs',
+    children: [
+      {
+        id: 'briefs/kestrel.docx',
+        kind: 'leaf',
+        label: 'Kestrel brief',
+        path: 'briefs/kestrel.docx',
+      },
+      {
+        id: 'briefs/deep',
+        kind: 'folder',
+        label: 'deep',
+        path: 'briefs/deep',
+        children: [
+          {
+            id: 'briefs/deep/nordhaven.docx',
+            kind: 'leaf',
+            label: 'nordhaven.docx',
+            path: 'briefs/deep/nordhaven.docx',
+          },
+        ],
+      },
+    ],
+  },
+  { id: 'readme.md', kind: 'leaf', label: 'readme.md', path: 'readme.md' },
+];
+
+describe('filterNavigatorLeaves', () => {
+  it('matches leaves by label or path, case-insensitively, with their folder', () => {
+    expect(filterNavigatorLeaves(tree, 'NORD')).toEqual([
+      { node: tree[0].children![1].children![0], parentPath: 'briefs/deep' },
+    ]);
+    expect(filterNavigatorLeaves(tree, 'briefs').map((r) => r.node.id)).toEqual(
+      ['briefs/kestrel.docx', 'briefs/deep/nordhaven.docx'],
+    );
+  });
+
+  it('gives a root leaf an empty parent path and returns nothing for a blank query', () => {
+    expect(filterNavigatorLeaves(tree, 'readme')).toEqual([
+      { node: tree[1], parentPath: '' },
+    ]);
+    expect(filterNavigatorLeaves(tree, '   ')).toEqual([]);
+  });
+});
+
+describe('ancestorIds / findNode / countLeaves', () => {
+  it('lists the folders above a node, outermost first', () => {
+    expect(ancestorIds(tree, 'briefs/deep/nordhaven.docx')).toEqual([
+      'briefs',
+      'briefs/deep',
+    ]);
+    expect(ancestorIds(tree, 'readme.md')).toEqual([]);
+    expect(ancestorIds(tree, 'missing')).toEqual([]);
+  });
+
+  it('finds a node anywhere in the tree', () => {
+    expect(findNode(tree, 'briefs/deep')?.label).toBe('deep');
+    expect(findNode(tree, 'nope')).toBeUndefined();
+  });
+
+  it('counts leaves under a list of nodes', () => {
+    expect(countLeaves(tree)).toBe(3);
+    expect(countLeaves(tree[0].children!)).toBe(2);
+  });
+});
+
+describe('directoryToNavigator', () => {
+  it('builds folders first, then files, with display names and leaf counts', () => {
+    const nodes = directoryToNavigator({
+      'z.md': { type: 'text/markdown', display_name: 'Zed notes' },
+      docs: {
+        'b.pdf': { type: 'application/pdf' },
+        'a.pdf': { type: 'application/pdf' },
+      } as never,
+    });
+    expect(nodes.map((n) => [n.id, n.kind, n.label, n.count])).toEqual([
+      ['docs', 'folder', 'docs', 2],
+      ['z.md', 'leaf', 'Zed notes', undefined],
+    ]);
+    expect(nodes[0].children!.map((n) => n.id)).toEqual([
+      'docs/a.pdf',
+      'docs/b.pdf',
+    ]);
+  });
+
+  it('tolerates a structure stored as a JSON string', () => {
+    const nodes = directoryToNavigator(
+      JSON.stringify({ 'a.txt': { type: 'text/plain' } }) as never,
+    );
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].path).toBe('a.txt');
+  });
+});
diff --git a/frontend/src/components/tree/navigatorUtils.ts b/frontend/src/components/tree/navigatorUtils.ts
new file mode 100644
index 00000000..3e050abb
--- /dev/null
+++ b/frontend/src/components/tree/navigatorUtils.ts
@@ -0,0 +1,174 @@
+/**
+ * Pure helpers for the source navigator (the file tree and the wiki pages
+ * column): the node model, filtering and lookups. Kept free of React so the
+ * rules are unit-testable.
+ */
+
+import type { DirectoryStructure } from './types';
+
+export interface NavigatorNode {
+  /** Unique within the tree; a file's path, a folder's path, a wiki page's path. */
+  id: string;
+  kind: 'folder' | 'leaf';
+  label: string;
+  /** Full path, matched by the filter and shown as a folder's second line. */
+  path: string;
+  /** Leaves under a folder. */
+  count?: number;
+  children?: NavigatorNode[];
+}
+
+export interface NavigatorMatch {
+  node: NavigatorNode;
+  /** The leaf's own folder, its path minus the name ('' at the root). */
+  parentPath: string;
+}
+
+/** A path minus its last segment: 'a/b/c.md' → 'a/b', '/x.md' → ''. */
+function parentOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut > 0 ? path.slice(0, cut) : '';
+}
+
+/**
+ * Leaves whose label or path contains the query, in tree order.
+ *
+ * @param nodes The navigator tree.
+ * @param query What the user typed; blank returns nothing.
+ * @returns Each match with its parent path, taken from the leaf's own path
+ *   so a page deep inside a wiki group reads its full folder, not the group's.
+ */
+export function filterNavigatorLeaves(
+  nodes: NavigatorNode[],
+  query: string,
+): NavigatorMatch[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const matches: NavigatorMatch[] = [];
+  const walk = (list: NavigatorNode[]) => {
+    for (const node of list) {
+      if (node.kind === 'folder') {
+        walk(node.children ?? []);
+      } else if (
+        node.label.toLowerCase().includes(q) ||
+        node.path.toLowerCase().includes(q)
+      ) {
+        matches.push({ node, parentPath: parentOf(node.path) });
+      }
+    }
+  };
+  walk(nodes);
+  return matches;
+}
+
+/**
+ * The ids of the folders above a node, outermost first.
+ *
+ * @param nodes The navigator tree.
+ * @param id The node to look for.
+ * @returns Folder ids, or an empty list at the root or when not found.
+ */
+export function ancestorIds(nodes: NavigatorNode[], id: string): string[] {
+  const walk = (list: NavigatorNode[], trail: string[]): string[] | null => {
+    for (const node of list) {
+      if (node.id === id) return trail;
+      if (node.children) {
+        const found = walk(node.children, [...trail, node.id]);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+  return walk(nodes, []) ?? [];
+}
+
+/**
+ * Find a node anywhere in the tree.
+ *
+ * @param nodes The navigator tree.
+ * @param id The node id.
+ * @returns The node, or undefined.
+ */
+export function findNode(
+  nodes: NavigatorNode[],
+  id: string,
+): NavigatorNode | undefined {
+  for (const node of nodes) {
+    if (node.id === id) return node;
+    const found = node.children ? findNode(node.children, id) : undefined;
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/**
+ * Count the leaves under a list of nodes.
+ *
+ * @param nodes Nodes to count through.
+ * @returns The number of leaves.
+ */
+export function countLeaves(nodes: NavigatorNode[]): number {
+  return nodes.reduce(
+    (sum, node) =>
+      sum + (node.kind === 'leaf' ? 1 : countLeaves(node.children ?? [])),
+    0,
+  );
+}
+
+function parseStructure(
+  structure: DirectoryStructure | string | null | undefined,
+): DirectoryStructure {
+  if (!structure) return {};
+  if (typeof structure === 'string') {
+    try {
+      const parsed = JSON.parse(structure);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  return structure;
+}
+
+/**
+ * Turn a source's directory structure into navigator nodes: folders first,
+ * then files, each group sorted by name; a file shows its display name.
+ *
+ * @param structure The source's `directory_structure` (object or JSON string).
+ * @param parent The path prefix (used by the recursion).
+ * @returns Navigator nodes whose ids are the file and folder paths.
+ */
+export function directoryToNavigator(
+  structure: DirectoryStructure | string | null | undefined,
+  parent = '',
+): NavigatorNode[] {
+  const entries = Object.entries(parseStructure(structure));
+  const folders: NavigatorNode[] = [];
+  const files: NavigatorNode[] = [];
+  for (const [name, node] of entries) {
+    const path = parent ? `${parent}/${name}` : name;
+    if (node && typeof node === 'object' && !node.type) {
+      const children = directoryToNavigator(
+        node as unknown as DirectoryStructure,
+        path,
+      );
+      folders.push({
+        id: path,
+        kind: 'folder',
+        label: name,
+        path,
+        count: countLeaves(children),
+        children,
+      });
+    } else {
+      const displayName =
+        typeof node?.display_name === 'string' && node.display_name.trim()
+          ? node.display_name
+          : name;
+      files.push({ id: path, kind: 'leaf', label: displayName, path });
+    }
+  }
+  const byName = (a: NavigatorNode, b: NavigatorNode) =>
+    a.path.localeCompare(b.path);
+  return [...folders.sort(byName), ...files.sort(byName)];
+}
diff --git a/frontend/src/components/tree/types.ts b/frontend/src/components/tree/types.ts
index 9f3e980f..b2f7f94e 100644
--- a/frontend/src/components/tree/types.ts
+++ b/frontend/src/components/tree/types.ts
@@ -12,12 +12,6 @@ export interface DirectoryStructure {
   [key: string]: FileNode;
 }
 
-export interface SearchResult {
-  name: string;
-  path: string;
-  isFile: boolean;
-}
-
 /**
  * Row context passed to consumers' getRowMenuOptions callbacks so they
  * can build per-row menus (e.g. add a Delete option for upload trees).
diff --git a/frontend/src/components/ui/breadcrumb.tsx b/frontend/src/components/ui/breadcrumb.tsx
index 42f17397..9b3332fd 100644
--- a/frontend/src/components/ui/breadcrumb.tsx
+++ b/frontend/src/components/ui/breadcrumb.tsx
@@ -59,7 +59,12 @@ function BreadcrumbPage({ className, ...props }: React.ComponentProps<'span'>) {
       role="link"
       aria-disabled="true"
       aria-current="page"
-      className={cn('text-foreground truncate font-normal', className)}
+      // Focusable from script only (tabIndex -1): PathHeader moves focus here
+      // after a crumb step, so it takes the link's ring.
+      className={cn(
+        `${focusRing} text-foreground truncate rounded-sm font-normal outline-none`,
+        className,
+      )}
       {...props}
     />
   );
diff --git a/frontend/src/components/ui/command.test.tsx b/frontend/src/components/ui/command.test.tsx
index a8772601..c697e198 100644
--- a/frontend/src/components/ui/command.test.tsx
+++ b/frontend/src/components/ui/command.test.tsx
@@ -145,4 +145,48 @@ describe('CommandInput', () => {
     );
     expect(classes).not.toContain('h-10');
   });
+
+  it('is a plain row with a bottom rule by default', async () => {
+    await render(
+      <Command>
+        <CommandInput placeholder="Search" />
+      </Command>,
+    );
+    const wrapper = document.querySelector<HTMLElement>(
+      '[data-slot="command-input-wrapper"]',
+    )!;
+    expect(wrapper.dataset.variant).toBe('default');
+    expect(wrapper.className).toContain('border-b');
+  });
+
+  // A filter field above a list the arrow keys walk into (a source view's
+  // navigator): SearchInput's 38px pill, its text 40px in.
+  it('variant="field" is the SearchInput pill with the ring on the frame', async () => {
+    await render(
+      <Command>
+        <CommandInput variant="field" placeholder="Filter files" />
+      </Command>,
+    );
+    const wrapper = document.querySelector<HTMLElement>(
+      '[data-slot="command-input-wrapper"]',
+    )!;
+    const classes = wrapper.className.split(' ');
+    expect(wrapper.dataset.variant).toBe('field');
+    expect(classes).toEqual(
+      expect.arrayContaining([
+        'border-input',
+        'shadow-xs',
+        'h-9.5',
+        'rounded-full',
+        'px-3',
+        'gap-3',
+        'has-[input:focus-visible]:ring-3',
+        'has-[input:focus-visible]:border-ring',
+      ]),
+    );
+    expect(classes).not.toContain('border-b');
+    const icon = wrapper.querySelector('svg')!;
+    expect(icon.getAttribute('class')).toContain('text-muted-foreground');
+    expect(icon.getAttribute('class')).not.toContain('opacity-50');
+  });
 });
diff --git a/frontend/src/components/ui/command.tsx b/frontend/src/components/ui/command.tsx
index e8e7e903..1ced897f 100644
--- a/frontend/src/components/ui/command.tsx
+++ b/frontend/src/components/ui/command.tsx
@@ -9,7 +9,9 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@/components/ui/dialog';
-import { cn } from '@/lib/utils';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn, fieldFrame } from '@/lib/utils';
 
 // The search-palette spacing: a 48px input row and roomier rows. Shared by
 // CommandDialog and any palette rendered elsewhere (e.g. in a bottom sheet),
@@ -74,16 +76,38 @@ function CommandDialog({
   );
 }
 
+const commandInputWrapperVariants = cva('flex items-center', {
+  variants: {
+    variant: {
+      // The row at the top of a popover or palette list.
+      default: 'h-9 gap-2 border-b px-3',
+      // A filter field over a list the arrow keys walk into (a source view's
+      // navigator): SearchInput's 38px pill, text 40px in, the focus ring on
+      // the frame while the input has keyboard focus.
+      field: `${fieldFrame} has-[input:focus-visible]:border-ring has-[input:focus-visible]:ring-ring/50 h-9.5 gap-3 rounded-full px-3 has-[input:focus-visible]:ring-3`,
+    },
+  },
+  defaultVariants: { variant: 'default' },
+});
+
 function CommandInput({
   className,
+  variant = 'default',
   ...props
-}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+}: React.ComponentProps<typeof CommandPrimitive.Input> &
+  VariantProps<typeof commandInputWrapperVariants>) {
   return (
     <div
       data-slot="command-input-wrapper"
-      className="flex h-9 items-center gap-2 border-b px-3"
+      data-variant={variant}
+      className={commandInputWrapperVariants({ variant })}
     >
-      <SearchIcon className="size-4 shrink-0 opacity-50" />
+      <SearchIcon
+        className={cn(
+          'size-4 shrink-0',
+          variant === 'field' ? 'text-muted-foreground' : 'opacity-50',
+        )}
+      />
       <CommandPrimitive.Input
         data-slot="command-input"
         className={cn(
diff --git a/frontend/src/components/ui/form-field.tsx b/frontend/src/components/ui/form-field.tsx
index 2f0bf59e..272aeedb 100644
--- a/frontend/src/components/ui/form-field.tsx
+++ b/frontend/src/components/ui/form-field.tsx
@@ -84,15 +84,16 @@ const LABEL_SURFACE_CLASSES = {
 } as const;
 
 // Where the floating label rests while its Input or Textarea is empty and
-// unfocused, per control size; every other control keeps it on the border.
+// unfocused, per control size, at the field's own text size (16px, 14px from
+// md); every other control keeps it on the border.
 // Only the field itself counts (up to two levels down, for an Input with an
 // icon or a Textarea under an overlay), not a search box in an inline menu.
 const FLOATING_LABEL_REST = [
-  'group-has-[>input:placeholder-shown:not(:focus),>*>input:placeholder-shown:not(:focus)]/float:top-2 group-has-[>input:placeholder-shown:not(:focus),>*>input:placeholder-shown:not(:focus)]/float:text-base',
+  'group-has-[>input:placeholder-shown:not(:focus),>*>input:placeholder-shown:not(:focus)]/float:top-2 group-has-[>input:placeholder-shown:not(:focus),>*>input:placeholder-shown:not(:focus)]/float:text-base md:group-has-[>input:placeholder-shown:not(:focus),>*>input:placeholder-shown:not(:focus)]/float:text-sm',
   'group-has-[>input[data-size=sm]:placeholder-shown:not(:focus)]/float:top-1.5 group-has-[>input[data-size=sm]:placeholder-shown:not(:focus)]/float:text-sm',
   'group-has-[>input[data-size=lg]:placeholder-shown:not(:focus)]/float:top-3.5',
-  'group-has-[>*>input[data-left-icon]:placeholder-shown:not(:focus)]/float:left-7',
-  'group-has-[>textarea:placeholder-shown:not(:focus),>*>textarea:placeholder-shown:not(:focus)]/float:top-2 group-has-[>textarea:placeholder-shown:not(:focus),>*>textarea:placeholder-shown:not(:focus)]/float:text-base',
+  'group-has-[>*>input[data-left-icon]:placeholder-shown:not(:focus)]/float:left-8',
+  'group-has-[>textarea:placeholder-shown:not(:focus),>*>textarea:placeholder-shown:not(:focus)]/float:top-2 group-has-[>textarea:placeholder-shown:not(:focus),>*>textarea:placeholder-shown:not(:focus)]/float:text-base md:group-has-[>textarea:placeholder-shown:not(:focus),>*>textarea:placeholder-shown:not(:focus)]/float:text-sm',
   'group-has-[>textarea[data-size=lg]:placeholder-shown:not(:focus),>*>textarea[data-size=lg]:placeholder-shown:not(:focus)]/float:top-3',
 ].join(' ');
 
diff --git a/frontend/src/components/ui/input.tsx b/frontend/src/components/ui/input.tsx
index 7c7d5906..cb485bbe 100644
--- a/frontend/src/components/ui/input.tsx
+++ b/frontend/src/components/ui/input.tsx
@@ -55,14 +55,18 @@ const inputVariants = cva(
 );
 
 // Where the floating label sits while the field is empty, per input height.
+// It rests at the field's own text size (16px, 14px from md), so it doesn't
+// change size when the first character replaces it.
 const LABEL_RESTING_CLASSES: Record<
   NonNullable<VariantProps<typeof inputVariants>['size']>,
   string
 > = {
-  default: 'peer-placeholder-shown:top-2 peer-placeholder-shown:text-base',
+  default:
+    'peer-placeholder-shown:top-2 peer-placeholder-shown:text-base md:peer-placeholder-shown:text-sm md:peer-focus:text-xs',
   sm: 'peer-placeholder-shown:top-1.5 peer-placeholder-shown:text-sm',
-  lg: 'peer-placeholder-shown:top-3.5 peer-placeholder-shown:text-base',
-  field: 'peer-placeholder-shown:top-2 peer-placeholder-shown:text-base',
+  lg: 'peer-placeholder-shown:top-3.5 peer-placeholder-shown:text-base md:peer-placeholder-shown:text-sm md:peer-focus:text-xs',
+  field:
+    'peer-placeholder-shown:top-2 peer-placeholder-shown:text-base md:peer-placeholder-shown:text-sm md:peer-focus:text-xs',
 };
 
 // The floating label sits on the field's border, so its background has to
@@ -168,7 +172,7 @@ function Input(inputProps: InputProps) {
           'text-muted-foreground pointer-events-none absolute -top-2.5 left-3 max-w-[calc(100%-24px)] overflow-hidden px-2 text-xs text-ellipsis whitespace-nowrap transition-all select-none',
           LABEL_RESTING_CLASSES[size ?? 'default'],
           leftIcon
-            ? 'peer-placeholder-shown:left-7'
+            ? 'peer-placeholder-shown:left-8'
             : 'peer-placeholder-shown:left-3',
           'peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs',
           LABEL_SURFACE_CLASSES[labelSurface],
diff --git a/frontend/src/components/ui/list-row.test.tsx b/frontend/src/components/ui/list-row.test.tsx
index 013c4f7a..15094134 100644
--- a/frontend/src/components/ui/list-row.test.tsx
+++ b/frontend/src/components/ui/list-row.test.tsx
@@ -34,4 +34,15 @@ describe('ListRow', () => {
     expect(html).toContain('focus-visible:ring-inset');
     expect(html).toContain('Sources');
   });
+
+  it('is dense, rounded and top-aligned at size sm', () => {
+    const html = renderToStaticMarkup(
+      <ListRow size="sm" interactive asChild title="Duisport">
+        <button type="button" />
+      </ListRow>,
+    );
+    expect(html).toContain('items-start gap-2.5 rounded-md px-2 py-1.5');
+    expect(html).not.toContain('px-4 py-3');
+    expect(html).toContain('focus-visible:ring-inset');
+  });
 });
diff --git a/frontend/src/components/ui/list-row.tsx b/frontend/src/components/ui/list-row.tsx
index b8cae221..5487082e 100644
--- a/frontend/src/components/ui/list-row.tsx
+++ b/frontend/src/components/ui/list-row.tsx
@@ -24,6 +24,13 @@ type ListRowProps = Omit<React.ComponentProps<'li'>, 'title'> & {
   trailing?: React.ReactNode;
   /** The whole row is a target: hover fill and an inset focus ring. */
   interactive?: boolean;
+  /**
+   * `sm` is the dense row of a narrow side panel (the graph node panel's
+   * relationships): 6px / 8px padding, rounded, top-aligned so a small
+   * leading mark sits on the title line. Use it in a plain list, not in
+   * `ListRows` (no divide rules).
+   */
+  size?: 'default' | 'sm';
   /**
    * Render the row's content into its single child (a `<Link>` or
    * `<button>`), wrapped in the `<li>`.
@@ -38,13 +45,17 @@ function ListRow({
   description,
   trailing,
   interactive = false,
+  size = 'default',
   asChild = false,
   className,
   children,
   ...props
 }: ListRowProps) {
   const rowClass = cn(
-    'flex items-center gap-3 px-4 py-3',
+    'flex',
+    size === 'sm'
+      ? 'items-start gap-2.5 rounded-md px-2 py-1.5'
+      : 'items-center gap-3 px-4 py-3',
     // Inset, because a row list usually sits in an overflow-hidden rounded
     // box that would clip an outer ring.
     interactive &&
diff --git a/frontend/src/components/ui/multi-select.tsx b/frontend/src/components/ui/multi-select.tsx
index 855068e3..eea6de2d 100644
--- a/frontend/src/components/ui/multi-select.tsx
+++ b/frontend/src/components/ui/multi-select.tsx
@@ -177,7 +177,6 @@ export function MultiSelect({
                     key={option.value}
                     value={option.label}
                     onSelect={() => handleSelect(option.value)}
-                    className="cursor-pointer"
                   >
                     {/* Visual only: the row is the control (cmdk handles the
                         click and Enter), so the box takes no focus or events. */}
diff --git a/frontend/src/components/ui/pagination.test.tsx b/frontend/src/components/ui/pagination.test.tsx
index be199447..0708fe88 100644
--- a/frontend/src/components/ui/pagination.test.tsx
+++ b/frontend/src/components/ui/pagination.test.tsx
@@ -96,4 +96,20 @@ describe('Pagination', () => {
     );
     expect(texts).toEqual(['pagination.previousPage', 'pagination.nextPage']);
   });
+
+  it('names the page-size select with pageSizeLabel', async () => {
+    await render(
+      <Pagination
+        page={1}
+        pageCount={3}
+        onPageChange={() => undefined}
+        pageSize={12}
+        pageSizeOptions={[12, 24]}
+        pageSizeLabel="Chunks per page"
+      />,
+    );
+    expect(container.textContent).toContain('Chunks per page:');
+    expect(button('Chunks per page')).not.toBeNull();
+    expect(container.textContent).not.toContain('pagination.rowsPerPage');
+  });
 });
diff --git a/frontend/src/components/ui/pagination.tsx b/frontend/src/components/ui/pagination.tsx
index d0879ef0..b29af52a 100644
--- a/frontend/src/components/ui/pagination.tsx
+++ b/frontend/src/components/ui/pagination.tsx
@@ -28,6 +28,8 @@ type PaginationProps = {
   onPageChange: (page: number) => void;
   /** Shows the "Rows per page" select. */
   pageSize?: number;
+  /** Names the page-size select when the items aren't rows ("Chunks per page"). */
+  pageSizeLabel?: string;
   pageSizeOptions?: number[];
   onPageSizeChange?: (size: number) => void;
   /** A count on the left ("1,024 users"); the row then spreads to both ends. */
@@ -43,6 +45,7 @@ function Pagination({
   pageCount,
   onPageChange,
   pageSize,
+  pageSizeLabel,
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
   onPageSizeChange,
   summary,
@@ -50,6 +53,7 @@ function Pagination({
   className,
 }: PaginationProps) {
   const { t } = useTranslation();
+  const sizeLabel = pageSizeLabel ?? t('pagination.rowsPerPage');
   const atStart = page <= 1;
   const atEnd = page >= pageCount;
   const goTo = (next: number) =>
@@ -70,14 +74,12 @@ function Pagination({
       <div className="flex items-center gap-4">
         {pageSize !== undefined ? (
           <div className="flex items-center gap-2">
-            <span className="text-foreground">
-              {t('pagination.rowsPerPage')}:
-            </span>
+            <span className="text-foreground">{sizeLabel}:</span>
             <Select
               value={String(pageSize)}
               onValueChange={(value) => onPageSizeChange?.(Number(value))}
             >
-              <SelectTrigger size="sm" aria-label={t('pagination.rowsPerPage')}>
+              <SelectTrigger size="sm" aria-label={sizeLabel}>
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
diff --git a/frontend/src/components/ui/table.test.tsx b/frontend/src/components/ui/table.test.tsx
index c4ce2666..23c12ee3 100644
--- a/frontend/src/components/ui/table.test.tsx
+++ b/frontend/src/components/ui/table.test.tsx
@@ -73,6 +73,27 @@ describe('Table parts', () => {
     expect(classes).not.toContain('text-muted-foreground');
   });
 
+  // The row whose detail is open beside the table (the graph's Entities):
+  // the brand tint of an open navigator item, so it never reads as hover.
+  it('marks the open row with the secondary tint and aria-current', () => {
+    const host = render(
+      <table>
+        <tbody>
+          <TableRow data-testid="open" selected onClick={vi.fn()} />
+          <TableRow data-testid="other" onClick={vi.fn()} />
+        </tbody>
+      </table>,
+    );
+    const open = host.querySelector<HTMLElement>('[data-testid="open"]')!;
+    expect(open.dataset.selected).toBe('');
+    expect(open.getAttribute('aria-current')).toBe('true');
+    expect(open.className).toContain('bg-secondary');
+    expect(open.className).toContain('hover:bg-secondary');
+    const other = host.querySelector<HTMLElement>('[data-testid="other"]')!;
+    expect(other.dataset.selected).toBeUndefined();
+    expect(other.className).not.toContain('bg-secondary');
+  });
+
   it('hovers only rows that have an onClick', () => {
     const host = render(
       <table>
diff --git a/frontend/src/components/ui/table.tsx b/frontend/src/components/ui/table.tsx
index 60c2eecf..dc9dd7b6 100644
--- a/frontend/src/components/ui/table.tsx
+++ b/frontend/src/components/ui/table.tsx
@@ -112,14 +112,17 @@ function TableBody({ className, ...props }: React.ComponentProps<'tbody'>) {
 
 /**
  * A table row. With `onClick` the whole row is the target, so it also takes
- * focus and opens with Enter or Space for keyboard users.
+ * focus and opens with Enter or Space for keyboard users. `selected` marks the
+ * row whose detail is open beside the table, with the brand tint of an open
+ * navigator item (`CommandItem checked`), so it never reads as hover.
  */
 function TableRow({
   className,
   onClick,
   onKeyDown,
+  selected = false,
   ...props
-}: React.ComponentProps<'tr'>) {
+}: React.ComponentProps<'tr'> & { selected?: boolean }) {
   const handleKeyDown = (event: React.KeyboardEvent<HTMLTableRowElement>) => {
     onKeyDown?.(event);
     // Keys on a control inside the row belong to that control.
@@ -132,10 +135,13 @@ function TableRow({
   return (
     <tr
       data-slot="table-row"
+      data-selected={selected ? '' : undefined}
+      aria-current={selected ? 'true' : undefined}
       className={cn(
         'border-border border-b',
         onClick &&
           `hover:bg-accent cursor-pointer transition-colors outline-none ${focusRing}`,
+        selected && 'bg-secondary text-secondary-foreground hover:bg-secondary',
         className,
       )}
       onClick={onClick}
diff --git a/frontend/src/components/wikiViewerUtils.test.ts b/frontend/src/components/wikiViewerUtils.test.ts
index b4b0f7d5..4a93169b 100644
--- a/frontend/src/components/wikiViewerUtils.test.ts
+++ b/frontend/src/components/wikiViewerUtils.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { provenanceKey, saveWikiPage } from './wikiViewerUtils';
+import {
+  buildWikiNavigator,
+  provenanceKey,
+  saveWikiPage,
+  wikiPageLabel,
+} from './wikiViewerUtils';
+import { filterNavigatorLeaves } from './tree/navigatorUtils';
 
 const jsonResponse = (status: number, body: unknown): Response =>
   ({
@@ -116,3 +122,60 @@ describe('saveWikiPage', () => {
     expect(outcome).toEqual({ status: 'error' });
   });
 });
+
+describe('wikiPageLabel', () => {
+  it('prefers the stored title', () => {
+    expect(wikiPageLabel({ path: '/a/b.md', title: 'Hello' })).toBe('Hello');
+  });
+
+  it('turns a file name into sentence case', () => {
+    expect(
+      wikiPageLabel({ path: '/company/meeting-and-decision-norms.md' }),
+    ).toBe('Meeting and decision norms');
+    expect(wikiPageLabel({ path: '/people/leave_and_hours.md' })).toBe(
+      'Leave and hours',
+    );
+  });
+
+  it('calls the root index Home', () => {
+    expect(wikiPageLabel({ path: '/index.md' })).toBe('Home');
+    expect(wikiPageLabel({ path: '/sales/index.md' })).toBe('Index');
+  });
+});
+
+describe('buildWikiNavigator', () => {
+  it('puts root pages first (Home leading), then one group per top folder', () => {
+    const nodes = buildWikiNavigator([
+      { path: '/people/onboarding.md' },
+      { path: '/company/mission.md' },
+      { path: '/arc53.md' },
+      { path: '/index.md' },
+      { path: '/company/org/model.md' },
+    ]);
+    expect(nodes.map((n) => [n.kind, n.label])).toEqual([
+      ['leaf', 'Home'],
+      ['leaf', 'Arc53'],
+      ['folder', 'company'],
+      ['folder', 'people'],
+    ]);
+    expect(nodes[2].children!.map((n) => n.id)).toEqual([
+      '/company/mission.md',
+      '/company/org/model.md',
+    ]);
+    expect(nodes[2].count).toBe(2);
+  });
+
+  // A filter match's second line is the page's own folder, not only the top
+  // folder its group is named after.
+  it('gives each filter match its full parent path', () => {
+    const nodes = buildWikiNavigator([
+      { path: '/index.md' },
+      { path: '/contracts/europe/2026/hamburg-port-dues.md' },
+      { path: '/playbooks/hamburg-strike-plan.md' },
+    ]);
+    expect(
+      filterNavigatorLeaves(nodes, 'hamburg').map((m) => m.parentPath),
+    ).toEqual(['/contracts/europe/2026', '/playbooks']);
+    expect(filterNavigatorLeaves(nodes, 'index')[0].parentPath).toBe('');
+  });
+});
diff --git a/frontend/src/components/wikiViewerUtils.ts b/frontend/src/components/wikiViewerUtils.ts
index c596355c..0826d4fe 100644
--- a/frontend/src/components/wikiViewerUtils.ts
+++ b/frontend/src/components/wikiViewerUtils.ts
@@ -1,3 +1,5 @@
+import type { NavigatorNode } from './tree/navigatorUtils';
+
 export interface WikiPageNode {
   path: string;
   title?: string | null;
@@ -65,3 +67,78 @@ export async function saveWikiPage(
   if (response.status === 403) return { status: 'forbidden' };
   return { status: 'error' };
 }
+
+const ROOT_INDEX = /^\/?index\.md$/i;
+
+/**
+ * The name a wiki page shows in the pages column: its stored title, else its
+ * file name without `.md`, dashes and underscores as spaces, in sentence case.
+ * The root `index.md` is the wiki's home page.
+ *
+ * @param page The page (only `path` and `title` are read).
+ * @param homeLabel The translated name of the root index page.
+ * @returns The label.
+ */
+export function wikiPageLabel(
+  page: Pick<WikiPageNode, 'path' | 'title'>,
+  homeLabel = 'Home',
+): string {
+  const title = page.title?.trim();
+  if (title) return title;
+  if (ROOT_INDEX.test(page.path)) return homeLabel;
+  const file = page.path.split('/').filter(Boolean).pop() ?? page.path;
+  const words = file.replace(/\.md$/i, '').replace(/[-_]+/g, ' ').trim();
+  if (!words) return page.path;
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * Group wiki pages for the navigator: pages at the root first (the home page
+ * leading), then one group per top-level folder holding every page under it.
+ *
+ * @param pages The wiki's pages.
+ * @param homeLabel The translated name of the root index page.
+ * @returns Navigator nodes whose leaf ids are the page paths.
+ */
+export function buildWikiNavigator(
+  pages: Pick<WikiPageNode, 'path' | 'title'>[],
+  homeLabel = 'Home',
+): NavigatorNode[] {
+  const roots: NavigatorNode[] = [];
+  const groups = new Map<string, NavigatorNode[]>();
+  for (const page of pages) {
+    const parts = page.path.split('/').filter(Boolean);
+    const leaf: NavigatorNode = {
+      id: page.path,
+      kind: 'leaf',
+      label: wikiPageLabel(page, homeLabel),
+      path: page.path,
+    };
+    if (parts.length <= 1) {
+      roots.push(leaf);
+    } else {
+      const list = groups.get(parts[0]) ?? [];
+      list.push(leaf);
+      groups.set(parts[0], list);
+    }
+  }
+  const isHome = (node: NavigatorNode) => ROOT_INDEX.test(node.path);
+  roots.sort(
+    (a, b) =>
+      Number(isHome(b)) - Number(isHome(a)) || a.label.localeCompare(b.label),
+  );
+  const folders = [...groups.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, children]): NavigatorNode => {
+      children.sort((a, b) => a.path.localeCompare(b.path));
+      return {
+        id: `folder:/${name}`,
+        kind: 'folder',
+        label: name,
+        path: `/${name}`,
+        count: children.length,
+        children,
+      };
+    });
+  return [...roots, ...folders];
+}
diff --git a/frontend/src/conversation/MarkdownAnswer.tsx b/frontend/src/conversation/MarkdownAnswer.tsx
index ed7c387b..4f385ed0 100644
--- a/frontend/src/conversation/MarkdownAnswer.tsx
+++ b/frontend/src/conversation/MarkdownAnswer.tsx
@@ -12,7 +12,7 @@ import rehypeKatex from 'rehype-katex';
 import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
 
-import { markdownHeadings } from '@/lib/markdown';
+import { markdownHeadings, markdownTables } from '@/lib/markdown';
 
 import CopyButton from '../components/CopyButton';
 import MermaidRenderer from '../components/MermaidRenderer';
@@ -203,6 +203,7 @@ export default function MarkdownAnswer({
                 urlTransform={sandboxUrlTransform}
                 components={{
                   ...markdownHeadings,
+                  ...markdownTables,
                   a({ href, children }) {
                     // A generated file is already on the turn as a download
                     // chip, but the model links it with a `sandbox:`/`artifact:`
@@ -351,36 +352,6 @@ export default function MarkdownAnswer({
                       </ol>
                     );
                   },
-                  table({ children }) {
-                    return (
-                      <div className="border-border relative overflow-x-auto rounded-lg border">
-                        {/* eslint-disable-next-line no-restricted-syntax -- the model's own markdown table, styled by the answer (DESIGN.md, Approved exceptions) */}
-                        <table className="text-foreground w-full text-left">
-                          {children}
-                        </table>
-                      </div>
-                    );
-                  },
-                  thead({ children }) {
-                    return (
-                      <thead className="bg-muted text-foreground text-xs uppercase">
-                        {children}
-                      </thead>
-                    );
-                  },
-                  tr({ children }) {
-                    return (
-                      <tr className="border-border odd:bg-card even:bg-muted border-b">
-                        {children}
-                      </tr>
-                    );
-                  },
-                  th({ children }) {
-                    return <th className="px-6 py-3">{children}</th>;
-                  },
-                  td({ children }) {
-                    return <td className="px-6 py-3">{children}</td>;
-                  },
                 }}
               >
                 {segment.content}
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
index 5c8d72eb..b5fcdc8e 100644
--- a/frontend/src/design/DesignSystem.tsx
+++ b/frontend/src/design/DesignSystem.tsx
@@ -35,6 +35,8 @@ import {
   Trash2,
   Undo2,
   Redo2,
+  File,
+  Folder,
 } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 
@@ -1702,6 +1704,34 @@ export default function DesignSystem() {
               </ListRows>
             </Card>
           </Example>
+          <Example
+            title="Dense rows (side panel)"
+            code='<ul className="-mx-2"><ListRow size="sm" interactive asChild leading title description>'
+          >
+            <ul className="-mx-2 flex max-w-80 flex-col">
+              {[
+                ['Oslo Freight Terminal', 'operates · ships via', 'bg-chart-2'],
+                ['Meridian Freight Group', 'contracted by', 'bg-chart-1'],
+              ].map(([name, meta, dot]) => (
+                <ListRow
+                  key={name}
+                  size="sm"
+                  interactive
+                  asChild
+                  leading={
+                    <span
+                      aria-hidden="true"
+                      className={`mt-1.5 size-2 shrink-0 rounded-full ${dot}`}
+                    />
+                  }
+                  title={name}
+                  description={meta}
+                >
+                  <button type="button" />
+                </ListRow>
+              ))}
+            </ul>
+          </Example>
           <Example
             title="Key/value rows"
             code='<DescriptionList layout="columns | justified" size="sm | xs"><DescriptionItem label mono>'
@@ -1728,7 +1758,7 @@ export default function DesignSystem() {
           </Example>
           <Example
             title="Pager"
-            code='<Pagination page pageCount onPageChange pageSize? summary? labels="icons | text">'
+            code='<Pagination page pageCount onPageChange pageSize? pageSizeLabel? summary? labels="icons | text">'
           >
             <div className="flex flex-col gap-4">
               <Pagination
@@ -1744,6 +1774,15 @@ export default function DesignSystem() {
                 onPageChange={setPagerPage}
                 summary="1,024 users"
               />
+              <Pagination
+                page={pagerPage}
+                pageCount={9}
+                onPageChange={setPagerPage}
+                pageSize={12}
+                pageSizeOptions={[12, 24, 48]}
+                pageSizeLabel="Chunks per page"
+                onPageSizeChange={() => undefined}
+              />
             </div>
           </Example>
           <Example
@@ -2623,6 +2662,35 @@ export default function DesignSystem() {
               </Table>
             </TableContainer>
           </Example>
+          <Example
+            title="Clickable rows, one open beside the table"
+            code="<TableRow selected onClick={…}>"
+          >
+            <TableContainer>
+              <Table>
+                <TableHead>
+                  <TableRow>
+                    <TableHeader>Entity</TableHeader>
+                    <TableHeader align="right">Connections</TableHeader>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  {TABLE_ROWS.map((row, index) => (
+                    <TableRow
+                      key={row.name}
+                      selected={index === 1}
+                      onClick={() => undefined}
+                    >
+                      <TableCell className="font-medium">{row.name}</TableCell>
+                      <TableCell align="right" className="tabular-nums">
+                        {row.runs}
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </TableContainer>
+          </Example>
         </Section>
 
         <Section
@@ -3053,6 +3121,26 @@ export default function DesignSystem() {
               </div>
             </div>
           </Example>
+          <Example
+            title="Filter field over a list (source navigator)"
+            code='<CommandInput variant="field" placeholder="Filter files" />'
+          >
+            <div className="flex w-64 flex-col gap-2">
+              <Command className="contents">
+                <CommandInput variant="field" placeholder="Filter files" />
+                <CommandList>
+                  <CommandItem>
+                    <Folder />
+                    carriers
+                  </CommandItem>
+                  <CommandItem checked>
+                    <File />
+                    rate-card-2026.pdf
+                  </CommandItem>
+                </CommandList>
+              </Command>
+            </div>
+          </Example>
           <Example
             title="Chosen item in a picker"
             code="<CommandItem checked={item.id === selectedId}>"
diff --git a/frontend/src/lib/markdown.test.tsx b/frontend/src/lib/markdown.test.tsx
index cb0c9120..028c04be 100644
--- a/frontend/src/lib/markdown.test.tsx
+++ b/frontend/src/lib/markdown.test.tsx
@@ -1,8 +1,9 @@
 import { renderToStaticMarkup } from 'react-dom/server';
 import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
 import { describe, expect, it } from 'vitest';
 
-import { markdownHeadings } from './markdown';
+import { markdownHeadings, markdownTables } from './markdown';
 
 describe('markdownHeadings', () => {
   it('maps h1-h3 to the shared semibold sizes with margins', () => {
@@ -22,3 +23,55 @@ describe('markdownHeadings', () => {
     );
   });
 });
+
+const TABLE = `| Lane | Carrier |
+| --- | --- |
+| Rotterdam – Oslo | Baltic Star |
+| Rotterdam – Milan | Rhinehaul |`;
+
+const render = () => {
+  const host = document.createElement('div');
+  host.innerHTML = renderToStaticMarkup(
+    <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownTables}>
+      {TABLE}
+    </ReactMarkdown>,
+  );
+  return host;
+};
+
+describe('markdownTables', () => {
+  // One table style across the app: markdown tables (chat answers, wiki
+  // pages, chunks, previews) are the ui/table parts, not a copy of them.
+  it('renders the ui/table parts in their bordered, scrolling frame', () => {
+    const host = render();
+    expect(host.querySelector('[data-slot="table-container"]')).not.toBeNull();
+    expect(host.querySelector('[data-slot="table"]')).not.toBeNull();
+    expect(host.querySelector('thead')!.dataset.slot).toBe('table-head');
+    expect(host.querySelectorAll('[data-slot="table-header"]')).toHaveLength(2);
+    expect(host.querySelectorAll('[data-slot="table-cell"]')).toHaveLength(4);
+    expect(host.querySelector('th')!.textContent).toBe('Lane');
+  });
+
+  it('keeps the GFM column alignment', () => {
+    const host = document.createElement('div');
+    host.innerHTML = renderToStaticMarkup(
+      <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownTables}>
+        {'| A | B | C |\n| :-- | :-: | --: |\n| 1 | 2 | 3 |'}
+      </ReactMarkdown>,
+    );
+    const cells = host.querySelectorAll('[data-slot="table-cell"]');
+    expect(cells[0].className).toContain('text-left');
+    expect(cells[1].className).toContain('text-center');
+    expect(cells[2].className).toContain('text-right');
+    expect(
+      host.querySelectorAll('[data-slot="table-header"]')[2].className,
+    ).toContain('text-right');
+  });
+
+  it('keeps the authors’ capitals and lets a narrow table shrink', () => {
+    const host = render();
+    expect(host.innerHTML).not.toContain('uppercase');
+    expect(host.innerHTML).not.toContain('even:bg-muted');
+    expect(host.querySelector('table')!.className).toContain('min-w-0');
+  });
+});
diff --git a/frontend/src/lib/markdown.tsx b/frontend/src/lib/markdown.tsx
index e479639f..10200147 100644
--- a/frontend/src/lib/markdown.tsx
+++ b/frontend/src/lib/markdown.tsx
@@ -1,5 +1,16 @@
+import type { CSSProperties } from 'react';
 import type { Components } from 'react-markdown';
 
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+
 /**
  * Heading renderers shared by every markdown surface (chat answers, the wiki
  * view, note artifacts, document previews). Spread into `components`.
@@ -15,3 +26,44 @@ export const markdownHeadings: Components = {
     <h3 className="mt-3 mb-2 text-base font-semibold">{children}</h3>
   ),
 };
+
+/**
+ * A GFM column's alignment (`:---:`, `---:`), which react-markdown hands a
+ * cell as `style.textAlign`.
+ *
+ * @param style The cell's style prop.
+ * @returns The `ui/table` align value, or undefined for the default.
+ */
+function cellAlign(
+  style: CSSProperties | undefined,
+): 'left' | 'right' | 'center' | undefined {
+  const align = style?.textAlign;
+  return align === 'left' || align === 'right' || align === 'center'
+    ? align
+    : undefined;
+}
+
+/**
+ * Table renderers shared by every markdown surface (chat answers, wiki pages,
+ * chunks, note artifacts, document previews): the `ui/table` parts, so a
+ * markdown table looks like every other table in the app. The bordered frame
+ * scrolls sideways, so a wide table never widens the column, and a narrow
+ * one shrinks to fit (`min-w-0`). Spread into `components` after
+ * `markdownHeadings`.
+ */
+export const markdownTables: Components = {
+  table: ({ children }) => (
+    <TableContainer>
+      <Table minWidth="min-w-0">{children}</Table>
+    </TableContainer>
+  ),
+  thead: ({ children }) => <TableHead>{children}</TableHead>,
+  tbody: ({ children }) => <TableBody>{children}</TableBody>,
+  tr: ({ children }) => <TableRow>{children}</TableRow>,
+  th: ({ children, style }) => (
+    <TableHeader align={cellAlign(style)}>{children}</TableHeader>
+  ),
+  td: ({ children, style }) => (
+    <TableCell align={cellAlign(style)}>{children}</TableCell>
+  ),
+};
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index 84d1bb0e..837994a5 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -111,6 +111,7 @@
       "preLoaded": "Vorgeladen",
       "private": "Privat",
       "sync": "Synchronisieren",
+      "syncDone": "Fertig",
       "syncNow": "Jetzt synchronisieren",
       "syncing": "Synchronisiere...",
       "reingest": "Erneut indexieren",
@@ -131,14 +132,10 @@
         "selectPage": "Wähle eine Seite aus, um ihren Inhalt anzuzeigen.",
         "edit": "Bearbeiten",
         "save": "Speichern",
-        "cancel": "Abbrechen",
         "saveFailed": "Die Seite konnte nicht gespeichert werden. Bitte versuche es erneut.",
         "forbidden": "Du hast keine Berechtigung, diese Seite zu bearbeiten.",
         "conflict": "Diese Seite wurde seit dem Öffnen geändert und neu geladen. Deine Änderungen stehen unten – übernimm sie erneut und speichere noch einmal.",
         "editPlaceholder": "Schreibe die Seite in Markdown…",
-        "livingTitle": "Lebendiges Wiki.",
-        "livingExplainer": "Eine von Agenten bearbeitbare Quelle: Seiten werden gelesen und umgeschrieben, während Agenten arbeiten, und sie ist Agenten standardmäßig über das agentische Suchwerkzeug zugänglich.",
-        "livingExplainerEditable": "Jeder Agent, der diese Quelle verwendet, kann sie bearbeiten.",
         "stamp": {
           "editedBy": "Bearbeitet von {{who}}",
           "agent": "Agent",
@@ -168,7 +165,18 @@
             "forbidden": "Du hast keine Berechtigung, diese Quelle umzuwandeln.",
             "conflict": "Diese Quelle wird noch indexiert. Warte, bis der Vorgang abgeschlossen ist, bevor du sie umwandelst."
           }
-        }
+        },
+        "badge": "Lebendes Wiki",
+        "byline_one": "{{pages}} Seite · {{tokens}} Tokens",
+        "byline_other": "{{pages}} Seiten · {{tokens}} Tokens",
+        "explainer": "Agenten lesen und überarbeiten diese Seiten bei ihrer Arbeit.",
+        "explainerEditable": "Agenten lesen und überarbeiten diese Seiten bei ihrer Arbeit; jeder Agent, der diese Quelle nutzt, kann sie bearbeiten.",
+        "home": "Startseite",
+        "filterPages": "Seiten filtern",
+        "pagesTitle": "Seiten",
+        "loadFailed": "Die Wiki-Seiten konnten nicht geladen werden.",
+        "pageLoadFailed": "Diese Seite konnte nicht geladen werden.",
+        "editTitle": "Seite bearbeiten"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -201,13 +209,56 @@
         "view": {
           "action": "Graph anzeigen",
           "title": "Wissensgraph",
-          "explainer": "Knoten sind Entitäten, Kanten ihre Beziehungen. Klicke auf einen Knoten, um seine Beschreibung und die Chunks zu sehen, aus denen er extrahiert wurde.",
-          "stats": "{{nodes}} Entitäten · {{edges}} Beziehungen",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "Noch kein Graph – die Extraktion läuft möglicherweise noch.",
           "selectNode": "Wähle einen Knoten aus, um seine Details zu sehen.",
-          "linkedChunks": "Verknüpfte Chunks",
           "noChunks": "Keine verknüpften Chunks für diese Entität.",
-          "close": "Schließen"
+          "close": "Schließen",
+          "tabs": {
+            "graph": "Graph",
+            "entities": "Entitäten",
+            "files": "Dateien"
+          },
+          "findEntity": "Entität suchen",
+          "entityName": "Name",
+          "noEntities": "Keine Entitäten gefunden",
+          "showTop": "Top anzeigen",
+          "byConnections": "nach Verbindungen",
+          "typeFilter": "Nach Typ filtern",
+          "otherTypes": "Sonstige: {{types}}",
+          "otherTypesMore_one": "{{formatted}} weitere",
+          "otherTypesMore_other": "{{formatted}} weitere",
+          "untyped": "Ohne Typ",
+          "loadFailed": "Der Graph konnte nicht geladen werden.",
+          "entitiesLoadFailed": "Die Entitäten konnten nicht geladen werden.",
+          "nodeLoadFailed": "Diese Entität konnte nicht geladen werden.",
+          "loadingNode": "Entität wird geladen",
+          "connections": "Verbindungen",
+          "mentionedIn": "Erwähnt in",
+          "showMore": "Mehr anzeigen",
+          "showLess": "Weniger anzeigen",
+          "relationships": "Beziehungen",
+          "relationshipsCapped_one": "Die {{shown}} stärksten von {{total}} Beziehung.",
+          "relationshipsCapped_other": "Die {{shown}} stärksten von {{total}} Beziehungen.",
+          "noRelationships": "Keine Beziehungen für diese Entität.",
+          "relatedTo": "verbunden mit",
+          "showAll": "Alle {{formatted}} anzeigen",
+          "showFewer": "Weniger anzeigen",
+          "sourceChunks": "Quell-Chunks",
+          "showInGraph": "Im Graph zeigen",
+          "allTypes": "Alle Typen",
+          "chunkCount_one": "{{formatted}} Chunk",
+          "chunkCount_other": "{{formatted}} Chunks",
+          "entityCount_one": "{{formatted}} Entität",
+          "entityCount_other": "{{formatted}} Entitäten",
+          "relationshipCount_one": "{{formatted}} Beziehung",
+          "relationshipCount_other": "{{formatted}} Beziehungen",
+          "chunk": "Chunk",
+          "chunkMeta": "{{file}} · {{tokens}} Tokens",
+          "chunkTokens": "{{tokens}} Tokens",
+          "openInFiles": "In Dateien öffnen",
+          "editChunk": "Chunk bearbeiten",
+          "chunkSaved": "Chunk gespeichert"
         }
       },
       "testRetrieval": {
@@ -240,14 +291,11 @@
       "shareWithTeam": "Mit Team teilen",
       "deleteWarning": "Bist du sicher, dass du \"{{name}}\" löschen möchtest?",
       "confirmDelete": "Bist du sicher, dass du diese Datei löschen möchtest? Diese Aktion kann nicht rückgängig gemacht werden.",
-      "backToAll": "Zurück zu allen Quellen",
-      "back": "Zurück",
       "chunks": "Chunks",
       "noChunks": "Keine Chunks gefunden",
       "noChunksAlt": "Keine Chunks gefunden",
       "goToSources": "Zu den Quellen",
       "uploadNew": "Neu hochladen",
-      "searchFiles": "Dateien suchen...",
       "noResults": "Keine Ergebnisse gefunden",
       "fileName": "Name",
       "tokens": "Tokens",
@@ -354,7 +402,39 @@
           "forbidden": "Du hast keine Berechtigung, die Konfiguration dieser Quelle zu bearbeiten.",
           "saveFailed": "Konfiguration konnte nicht gespeichert werden. Bitte versuche es erneut."
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "Der Chunk konnte nicht hinzugefügt werden",
+        "save": "Der Chunk konnte nicht gespeichert werden",
+        "delete": "Der Chunk konnte nicht gelöscht werden",
+        "load": "Die Chunks konnten nicht geladen werden"
+      },
+      "chunkPosition": "Chunk {{n}} von {{total}} · {{tokens}} Tokens",
+      "chunkCrumb": "Chunk {{n}}",
+      "chunkTileMeta": "#{{n}} · {{tokens}} Tokens",
+      "copyText": "Text kopieren",
+      "chunkTitleHint": "Der Name, unter dem Antworten diesen Chunk zitieren.",
+      "files": "Dateien",
+      "filesLoadError": "Die Dateien konnten nicht geladen werden",
+      "filesByline_one": "{{files}} Datei · {{tokens}} Tokens",
+      "filesByline_other": "{{files}} Dateien · {{tokens}} Tokens",
+      "filterFiles": "Dateien filtern",
+      "searchChunks": "Chunks durchsuchen",
+      "chunkCount_one": "{{formatted}} Chunk",
+      "chunkCount_other": "{{formatted}} Chunks",
+      "editor": {
+        "write": "Schreiben",
+        "preview": "Vorschau",
+        "previewEmpty": "Noch nichts für die Vorschau.",
+        "cancel": "Abbrechen",
+        "close": "Schließen",
+        "discardMessage": "Ungespeicherte Änderungen verwerfen?",
+        "discard": "Verwerfen"
+      },
+      "editChunk": "Chunk bearbeiten",
+      "editChunkDescription": "{{file}} · Chunk {{n}} · {{tokens}} Tokens",
+      "previousChunk": "Vorheriger Chunk",
+      "nextChunk": "Nächster Chunk"
     },
     "analytics": {
       "label": "Analytik",
@@ -1252,7 +1332,6 @@
       "promptText": "Prompt-Text",
       "save": "Speichern",
       "close": "Schließen",
-      "cancel": "Abbrechen",
       "delete": "Löschen",
       "deleteConfirmation": "Bist du sicher, dass du diesen Chunk löschen möchtest?"
     },
@@ -1349,7 +1428,8 @@
     "firstPage": "Erste Seite",
     "previousPage": "Vorherige Seite",
     "nextPage": "Nächste Seite",
-    "lastPage": "Letzte Seite"
+    "lastPage": "Letzte Seite",
+    "chunksPerPage": "Chunks pro Seite"
   },
   "conversation": {
     "copy": "Kopieren",
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index 355ffcfc..b9fe4e03 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -115,6 +115,7 @@
       "preLoaded": "Pre-loaded",
       "private": "Private",
       "sync": "Sync",
+      "syncDone": "Done",
       "syncNow": "Sync now",
       "syncing": "Syncing...",
       "reingest": "Reingest",
@@ -136,14 +137,10 @@
         "selectPage": "Select a page to view its contents.",
         "edit": "Edit",
         "save": "Save",
-        "cancel": "Cancel",
         "saveFailed": "Could not save the page. Please try again.",
         "forbidden": "You do not have permission to edit this page.",
         "conflict": "This page changed since you opened it and has been reloaded. Your edits are below — reapply and save again.",
         "editPlaceholder": "Write the page in Markdown…",
-        "livingTitle": "Living wiki.",
-        "livingExplainer": "An agent-editable source: pages are read and rewritten as agents work, and it is exposed to agents through the agentic search tool by default.",
-        "livingExplainerEditable": "Any agent using this source can edit it.",
         "stamp": {
           "editedBy": "Edited by {{who}}",
           "agent": "agent",
@@ -173,7 +170,18 @@
             "forbidden": "You don't have permission to convert this source.",
             "conflict": "This source is still ingesting. Wait for it to finish before converting."
           }
-        }
+        },
+        "badge": "Living wiki",
+        "byline_one": "{{pages}} page · {{tokens}} tokens",
+        "byline_other": "{{pages}} pages · {{tokens}} tokens",
+        "explainer": "Agents read and rewrite these pages as they work.",
+        "explainerEditable": "Agents read and rewrite these pages as they work; any agent using this source can edit it.",
+        "home": "Home",
+        "filterPages": "Filter pages",
+        "pagesTitle": "Pages",
+        "loadFailed": "Could not load the wiki pages.",
+        "pageLoadFailed": "Could not load this page.",
+        "editTitle": "Edit page"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -206,13 +214,56 @@
         "view": {
           "action": "View graph",
           "title": "Knowledge graph",
-          "explainer": "Nodes are entities and edges are their relationships. Click a node to see its description and the chunks it was extracted from.",
-          "stats": "{{nodes}} entities · {{edges}} relationships",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "No graph yet — extraction may still be running.",
           "selectNode": "Select a node to see its details.",
-          "linkedChunks": "Linked chunks",
           "noChunks": "No linked chunks for this entity.",
-          "close": "Close"
+          "close": "Close",
+          "tabs": {
+            "graph": "Graph",
+            "entities": "Entities",
+            "files": "Files"
+          },
+          "findEntity": "Find an entity",
+          "entityName": "Name",
+          "noEntities": "No entities found",
+          "showTop": "Show top",
+          "byConnections": "by connections",
+          "typeFilter": "Filter by type",
+          "otherTypes": "Other: {{types}}",
+          "otherTypesMore_one": "{{formatted}} more",
+          "otherTypesMore_other": "{{formatted}} more",
+          "untyped": "Untyped",
+          "loadFailed": "Couldn't load the graph.",
+          "entitiesLoadFailed": "Couldn't load the entities.",
+          "nodeLoadFailed": "Couldn't load this entity.",
+          "loadingNode": "Loading entity",
+          "connections": "Connections",
+          "mentionedIn": "Mentioned in",
+          "showMore": "Show more",
+          "showLess": "Show less",
+          "relationships": "Relationships",
+          "relationshipsCapped_one": "Showing the {{shown}} strongest of {{total}} relationship.",
+          "relationshipsCapped_other": "Showing the {{shown}} strongest of {{total}} relationships.",
+          "noRelationships": "No relationships for this entity.",
+          "relatedTo": "related to",
+          "showAll": "Show all {{formatted}}",
+          "showFewer": "Show fewer",
+          "sourceChunks": "Source chunks",
+          "showInGraph": "Show in graph",
+          "allTypes": "All types",
+          "chunkCount_one": "{{formatted}} chunk",
+          "chunkCount_other": "{{formatted}} chunks",
+          "entityCount_one": "{{formatted}} entity",
+          "entityCount_other": "{{formatted}} entities",
+          "relationshipCount_one": "{{formatted}} relationship",
+          "relationshipCount_other": "{{formatted}} relationships",
+          "chunk": "Chunk",
+          "chunkMeta": "{{file}} · {{tokens}} tokens",
+          "chunkTokens": "{{tokens}} tokens",
+          "openInFiles": "Open in Files",
+          "editChunk": "Edit chunk",
+          "chunkSaved": "Chunk saved"
         }
       },
       "testRetrieval": {
@@ -245,14 +296,11 @@
       "shareWithTeam": "Share with team",
       "deleteWarning": "Are you sure you want to delete \"{{name}}\"?",
       "confirmDelete": "Are you sure you want to delete this file? This action cannot be undone.",
-      "backToAll": "Back to all sources",
-      "back": "Back",
       "chunks": "Chunks",
       "noChunks": "No chunks found",
       "noChunksAlt": "No chunks found",
       "goToSources": "Go to Sources",
       "uploadNew": "Upload new",
-      "searchFiles": "Search files...",
       "noResults": "No results found",
       "fileName": "Name",
       "tokens": "Tokens",
@@ -359,7 +407,39 @@
           "forbidden": "You don't have permission to edit this source's config.",
           "saveFailed": "Failed to save config. Please try again."
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "Could not add the chunk",
+        "save": "Could not save the chunk",
+        "delete": "Could not delete the chunk",
+        "load": "Could not load the chunks"
+      },
+      "chunkPosition": "Chunk {{n}} of {{total}} · {{tokens}} tokens",
+      "chunkCrumb": "Chunk {{n}}",
+      "chunkTileMeta": "#{{n}} · {{tokens}} tokens",
+      "copyText": "Copy text",
+      "chunkTitleHint": "The name answers cite this chunk by.",
+      "files": "Files",
+      "filesLoadError": "Could not load the files",
+      "filesByline_one": "{{files}} file · {{tokens}} tokens",
+      "filesByline_other": "{{files}} files · {{tokens}} tokens",
+      "filterFiles": "Filter files",
+      "searchChunks": "Search chunks",
+      "chunkCount_one": "{{formatted}} chunk",
+      "chunkCount_other": "{{formatted}} chunks",
+      "editor": {
+        "write": "Write",
+        "preview": "Preview",
+        "previewEmpty": "Nothing to preview yet.",
+        "cancel": "Cancel",
+        "close": "Close",
+        "discardMessage": "Discard your unsaved changes?",
+        "discard": "Discard"
+      },
+      "editChunk": "Edit chunk",
+      "editChunkDescription": "{{file}} · chunk {{n}} · {{tokens}} tokens",
+      "previousChunk": "Previous chunk",
+      "nextChunk": "Next chunk"
     },
     "analytics": {
       "label": "Analytics",
@@ -1258,7 +1338,6 @@
       "promptText": "Prompt Text",
       "save": "Save",
       "close": "Close",
-      "cancel": "Cancel",
       "delete": "Delete",
       "deleteConfirmation": "Are you sure you want to delete this chunk?"
     },
@@ -1355,7 +1434,8 @@
     "firstPage": "First page",
     "previousPage": "Previous page",
     "nextPage": "Next page",
-    "lastPage": "Last page"
+    "lastPage": "Last page",
+    "chunksPerPage": "Chunks per page"
   },
   "conversation": {
     "copy": "Copy",
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index 40c4703c..dd0ffe40 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -111,6 +111,7 @@
       "preLoaded": "Precargado",
       "private": "Privado",
       "sync": "Sincronizar",
+      "syncDone": "Listo",
       "syncNow": "Sincronizar ahora",
       "syncing": "Sincronizando...",
       "reingest": "Reindexar",
@@ -131,14 +132,10 @@
         "selectPage": "Selecciona una página para ver su contenido.",
         "edit": "Editar",
         "save": "Guardar",
-        "cancel": "Cancelar",
         "saveFailed": "No se pudo guardar la página. Inténtalo de nuevo.",
         "forbidden": "No tienes permiso para editar esta página.",
         "conflict": "Esta página cambió desde que la abriste y se ha recargado. Tus ediciones están abajo — vuelve a aplicarlas y guarda de nuevo.",
         "editPlaceholder": "Escribe la página en Markdown…",
-        "livingTitle": "Wiki viva.",
-        "livingExplainer": "Una fuente editable por agentes: las páginas se leen y reescriben mientras los agentes trabajan, y se expone a los agentes de forma predeterminada a través de la herramienta de búsqueda agéntica.",
-        "livingExplainerEditable": "Cualquier agente que use esta fuente puede editarla.",
         "stamp": {
           "editedBy": "Editado por {{who}}",
           "agent": "agente",
@@ -168,7 +165,18 @@
             "forbidden": "No tienes permiso para convertir esta fuente.",
             "conflict": "Esta fuente todavía se está indexando. Espera a que termine antes de convertirla."
           }
-        }
+        },
+        "badge": "Wiki vivo",
+        "byline_one": "{{pages}} página · {{tokens}} tokens",
+        "byline_other": "{{pages}} páginas · {{tokens}} tokens",
+        "explainer": "Los agentes leen y reescriben estas páginas mientras trabajan.",
+        "explainerEditable": "Los agentes leen y reescriben estas páginas mientras trabajan; cualquier agente que use esta fuente puede editarla.",
+        "home": "Inicio",
+        "filterPages": "Filtrar páginas",
+        "pagesTitle": "Páginas",
+        "loadFailed": "No se pudieron cargar las páginas del wiki.",
+        "pageLoadFailed": "No se pudo cargar esta página.",
+        "editTitle": "Editar página"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -201,13 +209,56 @@
         "view": {
           "action": "Ver grafo",
           "title": "Grafo de conocimiento",
-          "explainer": "Los nodos son entidades y las aristas son sus relaciones. Haz clic en un nodo para ver su descripción y los fragmentos de los que se extrajo.",
-          "stats": "{{nodes}} entidades · {{edges}} relaciones",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "Aún no hay grafo — la extracción puede seguir en curso.",
           "selectNode": "Selecciona un nodo para ver sus detalles.",
-          "linkedChunks": "Fragmentos vinculados",
           "noChunks": "No hay fragmentos vinculados para esta entidad.",
-          "close": "Cerrar"
+          "close": "Cerrar",
+          "tabs": {
+            "graph": "Grafo",
+            "entities": "Entidades",
+            "files": "Archivos"
+          },
+          "findEntity": "Buscar una entidad",
+          "entityName": "Nombre",
+          "noEntities": "No se encontraron entidades",
+          "showTop": "Mostrar los",
+          "byConnections": "por conexiones",
+          "typeFilter": "Filtrar por tipo",
+          "otherTypes": "Otros: {{types}}",
+          "otherTypesMore_one": "{{formatted}} más",
+          "otherTypesMore_other": "{{formatted}} más",
+          "untyped": "Sin tipo",
+          "loadFailed": "No se pudo cargar el grafo.",
+          "entitiesLoadFailed": "No se pudieron cargar las entidades.",
+          "nodeLoadFailed": "No se pudo cargar esta entidad.",
+          "loadingNode": "Cargando entidad",
+          "connections": "Conexiones",
+          "mentionedIn": "Mencionada en",
+          "showMore": "Mostrar más",
+          "showLess": "Mostrar menos",
+          "relationships": "Relaciones",
+          "relationshipsCapped_one": "Se muestran las {{shown}} más fuertes de {{total}} relación.",
+          "relationshipsCapped_other": "Se muestran las {{shown}} más fuertes de {{total}} relaciones.",
+          "noRelationships": "Esta entidad no tiene relaciones.",
+          "relatedTo": "relacionada con",
+          "showAll": "Mostrar las {{formatted}}",
+          "showFewer": "Mostrar menos",
+          "sourceChunks": "Fragmentos de origen",
+          "showInGraph": "Mostrar en el grafo",
+          "allTypes": "Todos los tipos",
+          "chunkCount_one": "{{formatted}} fragmento",
+          "chunkCount_other": "{{formatted}} fragmentos",
+          "entityCount_one": "{{formatted}} entidad",
+          "entityCount_other": "{{formatted}} entidades",
+          "relationshipCount_one": "{{formatted}} relación",
+          "relationshipCount_other": "{{formatted}} relaciones",
+          "chunk": "Fragmento",
+          "chunkMeta": "{{file}} · {{tokens}} tokens",
+          "chunkTokens": "{{tokens}} tokens",
+          "openInFiles": "Abrir en Archivos",
+          "editChunk": "Editar fragmento",
+          "chunkSaved": "Fragmento guardado"
         }
       },
       "testRetrieval": {
@@ -240,14 +291,11 @@
       "shareWithTeam": "Compartir con el equipo",
       "deleteWarning": "¿Estás seguro de que deseas eliminar \"{{name}}\"?",
       "confirmDelete": "¿Estás seguro de que deseas eliminar este archivo? Esta acción no se puede deshacer.",
-      "backToAll": "Volver a todas las fuentes",
-      "back": "Volver",
       "chunks": "Fragmentos",
       "noChunks": "No se encontraron fragmentos",
       "noChunksAlt": "No se encontraron fragmentos",
       "goToSources": "Ir a Fuentes",
       "uploadNew": "Subir nuevo",
-      "searchFiles": "Buscar archivos...",
       "noResults": "No se encontraron resultados",
       "fileName": "Nombre",
       "tokens": "Tokens",
@@ -354,7 +402,39 @@
           "forbidden": "No tienes permiso para editar la configuración de esta fuente.",
           "saveFailed": "No se pudo guardar la configuración. Inténtalo de nuevo."
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "No se pudo añadir el fragmento",
+        "save": "No se pudo guardar el fragmento",
+        "delete": "No se pudo eliminar el fragmento",
+        "load": "No se pudieron cargar los fragmentos"
+      },
+      "chunkPosition": "Fragmento {{n}} de {{total}} · {{tokens}} tokens",
+      "chunkCrumb": "Fragmento {{n}}",
+      "chunkTileMeta": "#{{n}} · {{tokens}} tokens",
+      "copyText": "Copiar texto",
+      "chunkTitleHint": "El nombre con el que las respuestas citan este fragmento.",
+      "files": "Archivos",
+      "filesLoadError": "No se pudieron cargar los archivos",
+      "filesByline_one": "{{files}} archivo · {{tokens}} tokens",
+      "filesByline_other": "{{files}} archivos · {{tokens}} tokens",
+      "filterFiles": "Filtrar archivos",
+      "searchChunks": "Buscar fragmentos",
+      "chunkCount_one": "{{formatted}} fragmento",
+      "chunkCount_other": "{{formatted}} fragmentos",
+      "editor": {
+        "write": "Escribir",
+        "preview": "Vista previa",
+        "previewEmpty": "Aún no hay nada que mostrar.",
+        "cancel": "Cancelar",
+        "close": "Cerrar",
+        "discardMessage": "¿Descartar los cambios sin guardar?",
+        "discard": "Descartar"
+      },
+      "editChunk": "Editar fragmento",
+      "editChunkDescription": "{{file}} · fragmento {{n}} · {{tokens}} tokens",
+      "previousChunk": "Fragmento anterior",
+      "nextChunk": "Fragmento siguiente"
     },
     "analytics": {
       "label": "Analítica",
@@ -1252,7 +1332,6 @@
       "promptText": "Texto del prompt",
       "save": "Guardar",
       "close": "Cerrar",
-      "cancel": "Cancelar",
       "delete": "Eliminar",
       "deleteConfirmation": "¿Estás seguro de que deseas eliminar este fragmento?"
     },
@@ -1349,7 +1428,8 @@
     "firstPage": "Primera página",
     "previousPage": "Página anterior",
     "nextPage": "Página siguiente",
-    "lastPage": "Última página"
+    "lastPage": "Última página",
+    "chunksPerPage": "Fragmentos por página"
   },
   "conversation": {
     "copy": "Copiar",
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index 90386da1..4608d0bb 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -111,6 +111,7 @@
       "preLoaded": "プリロード済み",
       "private": "プライベート",
       "sync": "同期",
+      "syncDone": "完了",
       "syncNow": "今すぐ同期",
       "syncing": "同期中...",
       "reingest": "再インデックス",
@@ -131,14 +132,10 @@
         "selectPage": "ページを選択して内容を表示します。",
         "edit": "編集",
         "save": "保存",
-        "cancel": "キャンセル",
         "saveFailed": "ページを保存できませんでした。もう一度お試しください。",
         "forbidden": "このページを編集する権限がありません。",
         "conflict": "このページは開いた後に変更されたため、再読み込みされました。あなたの編集内容は下にあります。再適用して、もう一度保存してください。",
         "editPlaceholder": "Markdownでページを記述…",
-        "livingTitle": "リビングWiki。",
-        "livingExplainer": "エージェントが編集可能なソースです。エージェントの作業中にページが読み書きされ、デフォルトでエージェント検索ツールを通じてエージェントに公開されます。",
-        "livingExplainerEditable": "このソースを使用するすべてのエージェントが編集できます。",
         "stamp": {
           "editedBy": "{{who}}が編集",
           "agent": "エージェント",
@@ -168,7 +165,17 @@
             "forbidden": "このソースを変換する権限がありません。",
             "conflict": "このソースはまだインデックス作成中です。完了してから変換してください。"
           }
-        }
+        },
+        "badge": "リビングWiki",
+        "byline_other": "{{pages}} ページ · {{tokens}} トークン",
+        "explainer": "エージェントは作業しながらこれらのページを読み、書き換えます。",
+        "explainerEditable": "エージェントは作業しながらこれらのページを読み、書き換えます。このソースを使うエージェントは誰でも編集できます。",
+        "home": "ホーム",
+        "filterPages": "ページを絞り込む",
+        "pagesTitle": "ページ",
+        "loadFailed": "Wikiページを読み込めませんでした。",
+        "pageLoadFailed": "このページを読み込めませんでした。",
+        "editTitle": "ページを編集"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -201,13 +208,51 @@
         "view": {
           "action": "グラフを表示",
           "title": "ナレッジグラフ",
-          "explainer": "ノードはエンティティ、エッジはその関係を表します。ノードをクリックすると、説明と抽出元のチャンクが表示されます。",
-          "stats": "{{nodes}}件のエンティティ · {{edges}}件の関係",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "グラフはまだありません。抽出が実行中の可能性があります。",
           "selectNode": "ノードを選択すると詳細が表示されます。",
-          "linkedChunks": "リンクされたチャンク",
           "noChunks": "このエンティティにリンクされたチャンクはありません。",
-          "close": "閉じる"
+          "close": "閉じる",
+          "tabs": {
+            "graph": "グラフ",
+            "entities": "エンティティ",
+            "files": "ファイル"
+          },
+          "findEntity": "エンティティを検索",
+          "entityName": "名前",
+          "noEntities": "エンティティが見つかりません",
+          "showTop": "上位を表示",
+          "byConnections": "（接続数順）",
+          "typeFilter": "種類で絞り込む",
+          "otherTypes": "その他: {{types}}",
+          "otherTypesMore_other": "他{{formatted}}件",
+          "untyped": "種類なし",
+          "loadFailed": "グラフを読み込めませんでした。",
+          "entitiesLoadFailed": "エンティティを読み込めませんでした。",
+          "nodeLoadFailed": "このエンティティを読み込めませんでした。",
+          "loadingNode": "エンティティを読み込み中",
+          "connections": "接続数",
+          "mentionedIn": "出現箇所",
+          "showMore": "もっと見る",
+          "showLess": "表示を減らす",
+          "relationships": "関係",
+          "relationshipsCapped_other": "{{total}}件の関係のうち、強い順に{{shown}}件を表示しています。",
+          "noRelationships": "このエンティティには関係がありません。",
+          "relatedTo": "関連",
+          "showAll": "すべて表示（{{formatted}}件）",
+          "showFewer": "表示を減らす",
+          "sourceChunks": "ソースチャンク",
+          "showInGraph": "グラフで表示",
+          "allTypes": "すべての種類",
+          "chunkCount_other": "{{formatted}}件のチャンク",
+          "entityCount_other": "{{formatted}}件のエンティティ",
+          "relationshipCount_other": "{{formatted}}件の関係",
+          "chunk": "チャンク",
+          "chunkMeta": "{{file}} · {{tokens}} トークン",
+          "chunkTokens": "{{tokens}} トークン",
+          "openInFiles": "ファイルで開く",
+          "editChunk": "チャンクを編集",
+          "chunkSaved": "チャンクを保存しました"
         }
       },
       "testRetrieval": {
@@ -239,14 +284,11 @@
       "shareWithTeam": "チームと共有",
       "deleteWarning": "\"{{name}}\"を削除してもよろしいですか？",
       "confirmDelete": "このファイルを削除してもよろしいですか？この操作は元に戻せません。",
-      "backToAll": "すべてのソースに戻る",
-      "back": "戻る",
       "chunks": "チャンク",
       "noChunks": "チャンクが見つかりません",
       "noChunksAlt": "チャンクが見つかりません",
       "goToSources": "ソースへ移動",
       "uploadNew": "新規アップロード",
-      "searchFiles": "ファイルを検索...",
       "noResults": "結果が見つかりません",
       "fileName": "名前",
       "tokens": "トークン",
@@ -353,7 +395,37 @@
           "forbidden": "このソースの設定を編集する権限がありません。",
           "saveFailed": "設定の保存に失敗しました。もう一度お試しください。"
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "チャンクを追加できませんでした",
+        "save": "チャンクを保存できませんでした",
+        "delete": "チャンクを削除できませんでした",
+        "load": "チャンクを読み込めませんでした"
+      },
+      "chunkPosition": "チャンク {{n}} / {{total}} · {{tokens}} トークン",
+      "chunkCrumb": "チャンク {{n}}",
+      "chunkTileMeta": "#{{n}} · {{tokens}} トークン",
+      "copyText": "テキストをコピー",
+      "chunkTitleHint": "回答がこのチャンクを引用するときの名前です。",
+      "files": "ファイル",
+      "filesLoadError": "ファイルを読み込めませんでした",
+      "filesByline_other": "{{files}} ファイル · {{tokens}} トークン",
+      "filterFiles": "ファイルを絞り込む",
+      "searchChunks": "チャンクを検索",
+      "chunkCount_other": "{{formatted}} 件のチャンク",
+      "editor": {
+        "write": "編集",
+        "preview": "プレビュー",
+        "previewEmpty": "プレビューする内容がまだありません。",
+        "cancel": "キャンセル",
+        "close": "閉じる",
+        "discardMessage": "保存されていない変更を破棄しますか?",
+        "discard": "破棄"
+      },
+      "editChunk": "チャンクを編集",
+      "editChunkDescription": "{{file}} · チャンク {{n}} · {{tokens}} トークン",
+      "previousChunk": "前のチャンク",
+      "nextChunk": "次のチャンク"
     },
     "analytics": {
       "label": "分析",
@@ -1251,7 +1323,6 @@
       "promptText": "プロンプトテキスト",
       "save": "保存",
       "close": "閉じる",
-      "cancel": "キャンセル",
       "delete": "削除",
       "deleteConfirmation": "このチャンクを削除してもよろしいですか？"
     },
@@ -1347,7 +1418,8 @@
     "firstPage": "最初のページ",
     "previousPage": "前のページ",
     "nextPage": "次のページ",
-    "lastPage": "最後のページ"
+    "lastPage": "最後のページ",
+    "chunksPerPage": "1ページあたりのチャンク数"
   },
   "conversation": {
     "copy": "コピー",
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index 9ce855e9..a590a6ef 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -111,6 +111,7 @@
       "preLoaded": "Предзагруженный",
       "private": "Частный",
       "sync": "Синхронизация",
+      "syncDone": "Готово",
       "syncNow": "Синхронизировать сейчас",
       "syncing": "Синхронизация...",
       "reingest": "Переиндексировать",
@@ -131,14 +132,10 @@
         "selectPage": "Выберите страницу, чтобы просмотреть её содержимое.",
         "edit": "Редактировать",
         "save": "Сохранить",
-        "cancel": "Отмена",
         "saveFailed": "Не удалось сохранить страницу. Пожалуйста, попробуйте ещё раз.",
         "forbidden": "У вас нет прав на редактирование этой страницы.",
         "conflict": "Страница изменилась с момента открытия и была перезагружена. Ваши правки ниже — примените их заново и сохраните ещё раз.",
         "editPlaceholder": "Напишите страницу в Markdown…",
-        "livingTitle": "Живая вики.",
-        "livingExplainer": "Источник, редактируемый агентами: страницы читаются и переписываются по мере работы агентов, и по умолчанию источник доступен агентам через инструмент агентного поиска.",
-        "livingExplainerEditable": "Любой агент, использующий этот источник, может его редактировать.",
         "stamp": {
           "editedBy": "Изменено: {{who}}",
           "agent": "агент",
@@ -172,7 +169,20 @@
             "forbidden": "У вас нет прав на преобразование этого источника.",
             "conflict": "Источник ещё индексируется. Дождитесь завершения, прежде чем преобразовывать."
           }
-        }
+        },
+        "badge": "Живая вики",
+        "byline_one": "Страниц: {{pages}} · токенов: {{tokens}}",
+        "byline_few": "Страниц: {{pages}} · токенов: {{tokens}}",
+        "byline_many": "Страниц: {{pages}} · токенов: {{tokens}}",
+        "byline_other": "Страниц: {{pages}} · токенов: {{tokens}}",
+        "explainer": "Агенты читают и переписывают эти страницы в ходе работы.",
+        "explainerEditable": "Агенты читают и переписывают эти страницы в ходе работы; любой агент, использующий этот источник, может его редактировать.",
+        "home": "Главная",
+        "filterPages": "Фильтр страниц",
+        "pagesTitle": "Страницы",
+        "loadFailed": "Не удалось загрузить страницы вики.",
+        "pageLoadFailed": "Не удалось загрузить эту страницу.",
+        "editTitle": "Редактировать страницу"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -211,13 +221,66 @@
         "view": {
           "action": "Просмотр графа",
           "title": "Граф знаний",
-          "explainer": "Узлы — это сущности, а рёбра — их связи. Нажмите на узел, чтобы увидеть его описание и фрагменты, из которых он был извлечён.",
-          "stats": "{{nodes}} сущностей · {{edges}} связей",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "Графа пока нет — извлечение, возможно, ещё выполняется.",
           "selectNode": "Выберите узел, чтобы увидеть подробности.",
-          "linkedChunks": "Связанные фрагменты",
           "noChunks": "Для этой сущности нет связанных фрагментов.",
-          "close": "Закрыть"
+          "close": "Закрыть",
+          "tabs": {
+            "graph": "Граф",
+            "entities": "Сущности",
+            "files": "Файлы"
+          },
+          "findEntity": "Найти сущность",
+          "entityName": "Название",
+          "noEntities": "Сущности не найдены",
+          "showTop": "Показать топ",
+          "byConnections": "по числу связей",
+          "typeFilter": "Фильтр по типу",
+          "otherTypes": "Прочие: {{types}}",
+          "otherTypesMore_one": "ещё {{formatted}}",
+          "otherTypesMore_few": "ещё {{formatted}}",
+          "otherTypesMore_many": "ещё {{formatted}}",
+          "otherTypesMore_other": "ещё {{formatted}}",
+          "untyped": "Без типа",
+          "loadFailed": "Не удалось загрузить граф.",
+          "entitiesLoadFailed": "Не удалось загрузить сущности.",
+          "nodeLoadFailed": "Не удалось загрузить эту сущность.",
+          "loadingNode": "Загрузка сущности",
+          "connections": "Связи",
+          "mentionedIn": "Упоминается в",
+          "showMore": "Показать больше",
+          "showLess": "Показать меньше",
+          "relationships": "Связи с сущностями",
+          "relationshipsCapped_one": "Показаны {{shown}} самых сильных из {{total}} связи.",
+          "relationshipsCapped_few": "Показаны {{shown}} самых сильных из {{total}} связей.",
+          "relationshipsCapped_many": "Показаны {{shown}} самых сильных из {{total}} связей.",
+          "relationshipsCapped_other": "Показаны {{shown}} самых сильных из {{total}} связи.",
+          "noRelationships": "У этой сущности нет связей.",
+          "relatedTo": "связана с",
+          "showAll": "Показать все ({{formatted}})",
+          "showFewer": "Показать меньше",
+          "sourceChunks": "Исходные фрагменты",
+          "showInGraph": "Показать на графе",
+          "allTypes": "Все типы",
+          "chunkCount_one": "{{formatted}} фрагменте",
+          "chunkCount_few": "{{formatted}} фрагментах",
+          "chunkCount_many": "{{formatted}} фрагментах",
+          "chunkCount_other": "{{formatted}} фрагментах",
+          "entityCount_one": "{{formatted}} сущность",
+          "entityCount_few": "{{formatted}} сущности",
+          "entityCount_many": "{{formatted}} сущностей",
+          "entityCount_other": "{{formatted}} сущности",
+          "relationshipCount_one": "{{formatted}} связь",
+          "relationshipCount_few": "{{formatted}} связи",
+          "relationshipCount_many": "{{formatted}} связей",
+          "relationshipCount_other": "{{formatted}} связи",
+          "chunk": "Фрагмент",
+          "chunkMeta": "{{file}} · токенов: {{tokens}}",
+          "chunkTokens": "токенов: {{tokens}}",
+          "openInFiles": "Открыть в файлах",
+          "editChunk": "Редактировать фрагмент",
+          "chunkSaved": "Фрагмент сохранён"
         }
       },
       "testRetrieval": {
@@ -252,14 +315,11 @@
       "shareWithTeam": "Поделиться с командой",
       "deleteWarning": "Вы уверены, что хотите удалить \"{{name}}\"?",
       "confirmDelete": "Вы уверены, что хотите удалить этот файл? Это действие нельзя отменить.",
-      "backToAll": "Вернуться ко всем источникам",
-      "back": "Назад",
       "chunks": "Фрагменты",
       "noChunks": "Фрагменты не найдены",
       "noChunksAlt": "Фрагменты не найдены",
       "goToSources": "Перейти к источникам",
       "uploadNew": "Загрузить новый",
-      "searchFiles": "Поиск файлов...",
       "noResults": "Результаты не найдены",
       "fileName": "Имя",
       "tokens": "Токены",
@@ -366,7 +426,43 @@
           "forbidden": "У вас нет прав на изменение настроек этого источника.",
           "saveFailed": "Не удалось сохранить настройки. Пожалуйста, попробуйте ещё раз."
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "Не удалось добавить фрагмент",
+        "save": "Не удалось сохранить фрагмент",
+        "delete": "Не удалось удалить фрагмент",
+        "load": "Не удалось загрузить фрагменты"
+      },
+      "chunkPosition": "Фрагмент {{n}} из {{total}} · токенов: {{tokens}}",
+      "chunkCrumb": "Фрагмент {{n}}",
+      "chunkTileMeta": "#{{n}} · токенов: {{tokens}}",
+      "copyText": "Копировать текст",
+      "chunkTitleHint": "Название, под которым ответы ссылаются на этот фрагмент.",
+      "files": "Файлы",
+      "filesLoadError": "Не удалось загрузить файлы",
+      "filesByline_one": "Файлов: {{files}} · токенов: {{tokens}}",
+      "filesByline_few": "Файлов: {{files}} · токенов: {{tokens}}",
+      "filesByline_many": "Файлов: {{files}} · токенов: {{tokens}}",
+      "filesByline_other": "Файлов: {{files}} · токенов: {{tokens}}",
+      "filterFiles": "Фильтр файлов",
+      "searchChunks": "Поиск по фрагментам",
+      "chunkCount_one": "{{formatted}} фрагмент",
+      "chunkCount_few": "{{formatted}} фрагмента",
+      "chunkCount_many": "{{formatted}} фрагментов",
+      "chunkCount_other": "{{formatted}} фрагмента",
+      "editor": {
+        "write": "Редактор",
+        "preview": "Предпросмотр",
+        "previewEmpty": "Пока нечего показать.",
+        "cancel": "Отмена",
+        "close": "Закрыть",
+        "discardMessage": "Отменить несохранённые изменения?",
+        "discard": "Отменить изменения"
+      },
+      "editChunk": "Редактировать фрагмент",
+      "editChunkDescription": "{{file}} · фрагмент {{n}} · токенов: {{tokens}}",
+      "previousChunk": "Предыдущий фрагмент",
+      "nextChunk": "Следующий фрагмент"
     },
     "analytics": {
       "label": "Аналитика",
@@ -1292,7 +1388,6 @@
       "promptText": "Текст подсказки",
       "save": "Сохранить",
       "close": "Закрыть",
-      "cancel": "Отмена",
       "delete": "Удалить",
       "deleteConfirmation": "Вы уверены, что хотите удалить этот фрагмент?"
     },
@@ -1391,7 +1486,8 @@
     "firstPage": "Первая страница",
     "previousPage": "Предыдущая страница",
     "nextPage": "Следующая страница",
-    "lastPage": "Последняя страница"
+    "lastPage": "Последняя страница",
+    "chunksPerPage": "Фрагментов на странице"
   },
   "conversation": {
     "copy": "Копировать",
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index c39b2240..d5b91546 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -111,6 +111,7 @@
       "preLoaded": "預載入",
       "private": "私人",
       "sync": "同步",
+      "syncDone": "完成",
       "syncNow": "立即同步",
       "syncing": "同步中...",
       "reingest": "重新索引",
@@ -131,14 +132,10 @@
         "selectPage": "選擇頁面以查看其內容。",
         "edit": "編輯",
         "save": "儲存",
-        "cancel": "取消",
         "saveFailed": "無法儲存頁面。請再試一次。",
         "forbidden": "您沒有編輯此頁面的權限。",
         "conflict": "此頁面在您開啟後已變更，並已重新載入。您的編輯內容如下——請重新套用後再次儲存。",
         "editPlaceholder": "以 Markdown 撰寫頁面…",
-        "livingTitle": "動態 Wiki。",
-        "livingExplainer": "可由代理編輯的來源：代理工作時會讀取並改寫頁面，且預設透過代理搜尋工具向代理開放。",
-        "livingExplainerEditable": "任何使用此來源的代理都可以編輯它。",
         "stamp": {
           "editedBy": "由 {{who}} 編輯",
           "agent": "代理",
@@ -168,7 +165,17 @@
             "forbidden": "您沒有轉換此來源的權限。",
             "conflict": "此來源仍在索引中。請等候完成後再轉換。"
           }
-        }
+        },
+        "badge": "動態 Wiki",
+        "byline_other": "{{pages}} 個頁面 · {{tokens}} 個 token",
+        "explainer": "代理在工作時會閱讀並改寫這些頁面。",
+        "explainerEditable": "代理在工作時會閱讀並改寫這些頁面；任何使用此來源的代理都可以編輯它。",
+        "home": "首頁",
+        "filterPages": "篩選頁面",
+        "pagesTitle": "頁面",
+        "loadFailed": "無法載入 Wiki 頁面。",
+        "pageLoadFailed": "無法載入此頁面。",
+        "editTitle": "編輯頁面"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -201,13 +208,51 @@
         "view": {
           "action": "查看圖譜",
           "title": "知識圖譜",
-          "explainer": "節點代表實體，邊代表它們之間的關係。點擊節點可查看其描述及擷取來源的區塊。",
-          "stats": "{{nodes}} 個實體 · {{edges}} 個關係",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "尚無圖譜——擷取可能仍在進行中。",
           "selectNode": "選擇節點以查看其詳細資訊。",
-          "linkedChunks": "關聯區塊",
           "noChunks": "此實體沒有關聯的區塊。",
-          "close": "關閉"
+          "close": "關閉",
+          "tabs": {
+            "graph": "圖譜",
+            "entities": "實體",
+            "files": "檔案"
+          },
+          "findEntity": "尋找實體",
+          "entityName": "名稱",
+          "noEntities": "找不到實體",
+          "showTop": "顯示前",
+          "byConnections": "（依連結數）",
+          "typeFilter": "依類型篩選",
+          "otherTypes": "其他：{{types}}",
+          "otherTypesMore_other": "另外 {{formatted}} 個",
+          "untyped": "無類型",
+          "loadFailed": "無法載入圖譜。",
+          "entitiesLoadFailed": "無法載入實體。",
+          "nodeLoadFailed": "無法載入此實體。",
+          "loadingNode": "正在載入實體",
+          "connections": "連結數",
+          "mentionedIn": "出現於",
+          "showMore": "顯示更多",
+          "showLess": "收合",
+          "relationships": "關係",
+          "relationshipsCapped_other": "顯示 {{total}} 個關係中最強的 {{shown}} 個。",
+          "noRelationships": "此實體沒有關係。",
+          "relatedTo": "相關",
+          "showAll": "顯示全部 {{formatted}} 個",
+          "showFewer": "收合",
+          "sourceChunks": "來源區塊",
+          "showInGraph": "在圖譜中顯示",
+          "allTypes": "所有類型",
+          "chunkCount_other": "{{formatted}} 個區塊",
+          "entityCount_other": "{{formatted}} 個實體",
+          "relationshipCount_other": "{{formatted}} 個關係",
+          "chunk": "區塊",
+          "chunkMeta": "{{file}} · {{tokens}} Token",
+          "chunkTokens": "{{tokens}} Token",
+          "openInFiles": "在檔案中開啟",
+          "editChunk": "編輯區塊",
+          "chunkSaved": "區塊已儲存"
         }
       },
       "testRetrieval": {
@@ -239,14 +284,11 @@
       "shareWithTeam": "與團隊分享",
       "deleteWarning": "您確定要刪除 \"{{name}}\" 嗎？",
       "confirmDelete": "您確定要刪除此檔案嗎？此操作無法復原。",
-      "backToAll": "返回所有來源",
-      "back": "返回",
       "chunks": "文本塊",
       "noChunks": "未找到文本塊",
       "noChunksAlt": "未找到文本塊",
       "goToSources": "前往來源",
       "uploadNew": "上傳新文件",
-      "searchFiles": "搜尋檔案...",
       "noResults": "未找到結果",
       "fileName": "名稱",
       "tokens": "Token",
@@ -353,7 +395,37 @@
           "forbidden": "您沒有編輯此來源設定的權限。",
           "saveFailed": "儲存設定失敗。請再試一次。"
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "無法新增文本塊",
+        "save": "無法儲存文本塊",
+        "delete": "無法刪除文本塊",
+        "load": "無法載入文本塊"
+      },
+      "chunkPosition": "第 {{n}} 個文本塊，共 {{total}} 個 · {{tokens}} Token",
+      "chunkCrumb": "第 {{n}} 個文本塊",
+      "chunkTileMeta": "#{{n}} · {{tokens}} Token",
+      "copyText": "複製文字",
+      "chunkTitleHint": "回答引用此文本塊時使用的名稱。",
+      "files": "檔案",
+      "filesLoadError": "無法載入檔案",
+      "filesByline_other": "{{files}} 個檔案 · {{tokens}} Token",
+      "filterFiles": "篩選檔案",
+      "searchChunks": "搜尋文本塊",
+      "chunkCount_other": "{{formatted}} 個文本塊",
+      "editor": {
+        "write": "編輯",
+        "preview": "預覽",
+        "previewEmpty": "目前沒有可預覽的內容。",
+        "cancel": "取消",
+        "close": "關閉",
+        "discardMessage": "要捨棄未儲存的變更嗎？",
+        "discard": "捨棄"
+      },
+      "editChunk": "編輯文本塊",
+      "editChunkDescription": "{{file}} · 第 {{n}} 個文本塊 · {{tokens}} Token",
+      "previousChunk": "上一個文本塊",
+      "nextChunk": "下一個文本塊"
     },
     "analytics": {
       "label": "分析",
@@ -1251,7 +1323,6 @@
       "promptText": "提示文字",
       "save": "儲存",
       "close": "關閉",
-      "cancel": "取消",
       "delete": "刪除",
       "deleteConfirmation": "您確定要刪除此區塊嗎？"
     },
@@ -1347,7 +1418,8 @@
     "firstPage": "第一頁",
     "previousPage": "上一頁",
     "nextPage": "下一頁",
-    "lastPage": "最後一頁"
+    "lastPage": "最後一頁",
+    "chunksPerPage": "每頁文本塊數"
   },
   "conversation": {
     "copy": "複製",
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index 983f7019..056a7f54 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -111,6 +111,7 @@
       "preLoaded": "预加载",
       "private": "私有",
       "sync": "同步",
+      "syncDone": "完成",
       "syncNow": "立即同步",
       "syncing": "同步中...",
       "reingest": "重新索引",
@@ -131,14 +132,10 @@
         "selectPage": "选择一个页面以查看其内容。",
         "edit": "编辑",
         "save": "保存",
-        "cancel": "取消",
         "saveFailed": "无法保存页面，请重试。",
         "forbidden": "您没有权限编辑此页面。",
         "conflict": "此页面在您打开后已被修改，并已重新加载。您的编辑内容在下方——请重新应用并再次保存。",
         "editPlaceholder": "使用 Markdown 编写页面…",
-        "livingTitle": "动态 Wiki。",
-        "livingExplainer": "可由代理编辑的来源：代理在工作时会读取和重写页面，并且它默认通过代理搜索工具向代理开放。",
-        "livingExplainerEditable": "任何使用此来源的代理都可以编辑它。",
         "stamp": {
           "editedBy": "由{{who}}编辑",
           "agent": "代理",
@@ -168,7 +165,17 @@
             "forbidden": "您没有权限转换此来源。",
             "conflict": "此来源仍在索引中。请等待完成后再转换。"
           }
-        }
+        },
+        "badge": "动态 Wiki",
+        "byline_other": "{{pages}} 个页面 · {{tokens}} 个 token",
+        "explainer": "代理在工作时会阅读并改写这些页面。",
+        "explainerEditable": "代理在工作时会阅读并改写这些页面；任何使用此来源的代理都可以编辑它。",
+        "home": "首页",
+        "filterPages": "筛选页面",
+        "pagesTitle": "页面",
+        "loadFailed": "无法加载 Wiki 页面。",
+        "pageLoadFailed": "无法加载此页面。",
+        "editTitle": "编辑页面"
       },
       "graphrag": {
         "badge": "GraphRAG",
@@ -201,13 +208,51 @@
         "view": {
           "action": "查看图谱",
           "title": "知识图谱",
-          "explainer": "节点表示实体，边表示它们之间的关系。点击节点可查看其描述以及提取它的文本块。",
-          "stats": "{{nodes}} 个实体 · {{edges}} 个关系",
+          "stats": "{{entities}} · {{relationships}}",
           "empty": "暂无图谱——提取可能仍在进行中。",
           "selectNode": "选择一个节点以查看其详情。",
-          "linkedChunks": "关联的文本块",
           "noChunks": "此实体没有关联的文本块。",
-          "close": "关闭"
+          "close": "关闭",
+          "tabs": {
+            "graph": "图谱",
+            "entities": "实体",
+            "files": "文件"
+          },
+          "findEntity": "查找实体",
+          "entityName": "名称",
+          "noEntities": "未找到实体",
+          "showTop": "显示前",
+          "byConnections": "（按连接数）",
+          "typeFilter": "按类型筛选",
+          "otherTypes": "其他：{{types}}",
+          "otherTypesMore_other": "另外 {{formatted}} 个",
+          "untyped": "无类型",
+          "loadFailed": "无法加载图谱。",
+          "entitiesLoadFailed": "无法加载实体。",
+          "nodeLoadFailed": "无法加载此实体。",
+          "loadingNode": "正在加载实体",
+          "connections": "连接数",
+          "mentionedIn": "出现于",
+          "showMore": "显示更多",
+          "showLess": "收起",
+          "relationships": "关系",
+          "relationshipsCapped_other": "显示 {{total}} 个关系中最强的 {{shown}} 个。",
+          "noRelationships": "此实体没有关系。",
+          "relatedTo": "相关",
+          "showAll": "显示全部 {{formatted}} 个",
+          "showFewer": "收起",
+          "sourceChunks": "来源分块",
+          "showInGraph": "在图谱中显示",
+          "allTypes": "所有类型",
+          "chunkCount_other": "{{formatted}} 个分块",
+          "entityCount_other": "{{formatted}} 个实体",
+          "relationshipCount_other": "{{formatted}} 个关系",
+          "chunk": "分块",
+          "chunkMeta": "{{file}} · {{tokens}} 个令牌",
+          "chunkTokens": "{{tokens}} 个令牌",
+          "openInFiles": "在文件中打开",
+          "editChunk": "编辑分块",
+          "chunkSaved": "分块已保存"
         }
       },
       "testRetrieval": {
@@ -239,14 +284,11 @@
       "shareWithTeam": "与团队共享",
       "deleteWarning": "您确定要删除 \"{{name}}\" 吗？",
       "confirmDelete": "您确定要删除此文件吗？此操作无法撤销。",
-      "backToAll": "返回所有来源",
-      "back": "返回",
       "chunks": "文本块",
       "noChunks": "未找到文本块",
       "noChunksAlt": "未找到文本块",
       "goToSources": "前往来源",
       "uploadNew": "上传新文档",
-      "searchFiles": "搜索文件...",
       "noResults": "未找到结果",
       "fileName": "名称",
       "tokens": "令牌",
@@ -353,7 +395,37 @@
           "forbidden": "您没有权限编辑此来源的配置。",
           "saveFailed": "保存配置失败，请重试。"
         }
-      }
+      },
+      "chunkErrors": {
+        "add": "无法添加文本块",
+        "save": "无法保存文本块",
+        "delete": "无法删除文本块",
+        "load": "无法加载文本块"
+      },
+      "chunkPosition": "第 {{n}} 个文本块，共 {{total}} 个 · {{tokens}} 个令牌",
+      "chunkCrumb": "第 {{n}} 个文本块",
+      "chunkTileMeta": "#{{n}} · {{tokens}} 个令牌",
+      "copyText": "复制文本",
+      "chunkTitleHint": "回答引用此文本块时使用的名称。",
+      "files": "文件",
+      "filesLoadError": "无法加载文件",
+      "filesByline_other": "{{files}} 个文件 · {{tokens}} 个令牌",
+      "filterFiles": "筛选文件",
+      "searchChunks": "搜索文本块",
+      "chunkCount_other": "{{formatted}} 个文本块",
+      "editor": {
+        "write": "编辑",
+        "preview": "预览",
+        "previewEmpty": "暂无可预览的内容。",
+        "cancel": "取消",
+        "close": "关闭",
+        "discardMessage": "放弃未保存的更改？",
+        "discard": "放弃"
+      },
+      "editChunk": "编辑文本块",
+      "editChunkDescription": "{{file}} · 第 {{n}} 个文本块 · {{tokens}} 个令牌",
+      "previousChunk": "上一个文本块",
+      "nextChunk": "下一个文本块"
     },
     "analytics": {
       "label": "分析",
@@ -1251,7 +1323,6 @@
       "promptText": "提示文本",
       "save": "保存",
       "close": "关闭",
-      "cancel": "取消",
       "delete": "删除",
       "deleteConfirmation": "您确定要删除此块吗？"
     },
@@ -1347,7 +1418,8 @@
     "firstPage": "第一页",
     "previousPage": "上一页",
     "nextPage": "下一页",
-    "lastPage": "最后一页"
+    "lastPage": "最后一页",
+    "chunksPerPage": "每页文本块数"
   },
   "conversation": {
     "copy": "复制",
diff --git a/frontend/src/settings/Sources.tsx b/frontend/src/settings/Sources.tsx
index f870c075..69f349cf 100644
--- a/frontend/src/settings/Sources.tsx
+++ b/frontend/src/settings/Sources.tsx
@@ -50,7 +50,7 @@ import FileTree from '../components/FileTree';
 import ConnectorTree from '../components/ConnectorTree';
 import Chunks from '../components/Chunks';
 import WikiViewer from '../components/WikiViewer';
-import GraphView from '../components/GraphView';
+import GraphSourceView from '../components/graph/GraphSourceView';
 import ConvertToWikiModal from './ConvertToWikiModal';
 import EnableGraphRAGModal from './EnableGraphRAGModal';
 import { clearGraphBuild, selectGraphBuilds } from './graphBuildSlice';
@@ -536,9 +536,11 @@ export default function Sources({
           headerAction={testRetrievalAction}
         />
       ) : documentToView.config?.kind === 'graphrag' ? (
-        <GraphView
+        <GraphSourceView
           docId={documentToView.id || ''}
           sourceName={documentToView.name}
+          sourceType={documentToView.type}
+          isNested={!!documentToView.isNested}
           onBackToDocuments={() => setDocumentToView(undefined)}
           headerAction={testRetrievalAction}
         />
diff --git a/frontend/src/settings/components/UsageQuota.tsx b/frontend/src/settings/components/UsageQuota.tsx
index 7d3e8f41..5f209076 100644
--- a/frontend/src/settings/components/UsageQuota.tsx
+++ b/frontend/src/settings/components/UsageQuota.tsx
@@ -8,7 +8,7 @@ import { Card } from '../../components/ui/card';
 import { SectionHeader } from '../../components/ui/section-header';
 import { Progress } from '../../components/ui/progress';
 import { selectToken } from '../../preferences/preferenceSlice';
-import { formatDateTime } from '../../utils/dateTimeUtils';
+import { formatDateTime, intlLocale } from '../../utils/dateTimeUtils';
 
 type Budget = { limit: number | null; used: number };
 type Bucket = {
@@ -80,8 +80,8 @@ export default function UsageQuota() {
 
   if (buckets.length === 0) return null;
 
-  const number = new Intl.NumberFormat(i18n.language);
-  const usd = new Intl.NumberFormat(i18n.language, {
+  const number = new Intl.NumberFormat(intlLocale(i18n.language));
+  const usd = new Intl.NumberFormat(intlLocale(i18n.language), {
     style: 'currency',
     currency: 'USD',
   });
diff --git a/frontend/src/utils/dateTimeUtils.test.ts b/frontend/src/utils/dateTimeUtils.test.ts
index c72a7c80..dc4dc83a 100644
--- a/frontend/src/utils/dateTimeUtils.test.ts
+++ b/frontend/src/utils/dateTimeUtils.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'vitest';
 
-import { formatDate, formatDateOnly, formatDateTime } from './dateTimeUtils';
+import {
+  formatCount,
+  formatDate,
+  formatDateOnly,
+  formatDateTime,
+} from './dateTimeUtils';
 
 describe('dateTimeUtils', () => {
   it('formats date-only values as DD/MM/YYYY', () => {
@@ -98,3 +103,20 @@ describe('formatRelative', () => {
     ).toBe(formatDateOnly(old));
   });
 });
+
+describe('formatCount', () => {
+  it('groups digits the way the app language does', () => {
+    expect(formatCount(1234567, 'en')).toBe('1,234,567');
+    expect(formatCount(1234567, 'de')).toBe('1.234.567');
+    expect(formatCount(1234, 'ru')).toBe('1\u00a0234');
+  });
+
+  it('maps the app codes Intl does not know', () => {
+    expect(formatCount(1234, 'jp')).toBe('1,234');
+    expect(formatCount(1234, 'zhTW')).toBe('1,234');
+  });
+
+  it('leaves small numbers alone', () => {
+    expect(formatCount(7, 'de')).toBe('7');
+  });
+});
diff --git a/frontend/src/utils/dateTimeUtils.ts b/frontend/src/utils/dateTimeUtils.ts
index fb42e1ab..04c529ab 100644
--- a/frontend/src/utils/dateTimeUtils.ts
+++ b/frontend/src/utils/dateTimeUtils.ts
@@ -82,6 +82,24 @@ export function intlLocale(language: string = i18next.language): string {
   return INTL_LOCALES[language] ?? language;
 }
 
+/**
+ * A count with the UI language's digit grouping ("1,234", "1.234", "1 234").
+ *
+ * Args:
+ *   value: the number.
+ *   language: an app language code; defaults to the current one.
+ *
+ * Returns:
+ *   The formatted number. Pass it to a plural key as its own param and keep
+ *   `count` numeric, so i18next still picks the plural form.
+ */
+export function formatCount(
+  value: number,
+  language: string = i18next.language,
+): string {
+  return new Intl.NumberFormat(intlLocale(language)).format(value);
+}
+
 const RELATIVE_UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
   ['year', 31_536_000_000],
   ['month', 2_592_000_000],
diff --git a/tests/api/user/sources/test_chunks.py b/tests/api/user/sources/test_chunks.py
index 83829b78..b46b30ee 100644
--- a/tests/api/user/sources/test_chunks.py
+++ b/tests/api/user/sources/test_chunks.py
@@ -49,6 +49,56 @@ class TestResolveSource:
         assert got is not None
         assert str(got["id"]) == str(src["id"])
 
+    def test_team_viewer_can_read(self, pg_conn):
+        from docsgpt.api.user.sources.chunks import _resolve_source
+        from docsgpt.storage.db.repositories.team_members import TeamMembersRepository
+        from docsgpt.storage.db.repositories.team_resource_grants import TeamResourceGrantsRepository
+        from docsgpt.storage.db.repositories.teams import TeamsRepository
+
+        owner, viewer = "u-resolve-owner", "u-resolve-viewer"
+        src = _seed_source(pg_conn, user=owner)
+        team = TeamsRepository(pg_conn).create("Acme", "acme-chunks", owner)
+        TeamMembersRepository(pg_conn).add_member(team["id"], viewer, role="team_member")
+        TeamResourceGrantsRepository(pg_conn).grant(
+            team["id"], "source", str(src["id"]), owner_id=owner, granted_by=owner,
+            access_level="viewer",
+        )
+        with _patch_db(pg_conn):
+            got = _resolve_source(str(src["id"]), viewer)
+            stranger = _resolve_source(str(src["id"]), "u-resolve-stranger")
+        assert got is not None
+        assert str(got["id"]) == str(src["id"])
+        assert stranger is None
+
+
+class TestChunkMatchesPath:
+    @pytest.mark.parametrize("metadata, path", [
+        ({"source": "/a/b/file.txt"}, "b/file.txt"),
+        ({"source": "file.txt"}, "file.txt"),
+        ({"source": "https://x.io/guides/setup", "file_path": "guides/setup.md"}, "guides/setup.md"),
+        ({"source": "https://github.com/o/r/blob/main/web/app.py", "title": "web/app.py"}, "web/app.py"),
+        ({"source": "s3://bkt/docs/a.pdf", "key": "docs/a.pdf", "title": "a.pdf"}, "docs/a.pdf"),
+        # Web and Reddit chunks carry no file_path/key: the tree keys them by title.
+        ({"source": "https://docs.docsgpt.cloud/", "title": "Home - DocsGPT"}, "Home - DocsGPT"),
+        ({"source": "https://reddit.com/r/x/comments/1", "title": "A post"}, "A post"),
+    ])
+    def test_matches(self, metadata, path):
+        from docsgpt.api.user.sources.chunks import _chunk_matches_path
+        assert _chunk_matches_path(metadata, path)
+
+    @pytest.mark.parametrize("metadata, path", [
+        ({"source": "/other.txt"}, "b/file.txt"),
+        # Suffixes only match at a path boundary.
+        ({"source": "docs/data.md"}, "a.md"),
+        # Title only stands in for remote chunks the tree could not key by file_path/key.
+        ({"source": "docs/readme.md", "title": "Readme"}, "Readme"),
+        ({"source": "s3://bkt/docs/a.pdf", "key": "docs/a.pdf", "title": "Report"}, "Report"),
+        ({"source": "https://x.io/a", "file_path": "a.md", "title": "A"}, "A"),
+    ])
+    def test_rejects(self, metadata, path):
+        from docsgpt.api.user.sources.chunks import _chunk_matches_path
+        assert not _chunk_matches_path(metadata, path)
+
 
 class TestGetChunks:
     def test_returns_401_unauthenticated(self, app):
@@ -146,6 +196,35 @@ class TestGetChunks:
         assert response.status_code == 200
         assert response.json["total"] == 1
 
+    def test_filters_title_keyed_web_page(self, app, pg_conn):
+        # Single-URL sources ingested before WebLoader set ``file_path`` key
+        # their only tree file by the page title; opening it must still list
+        # the page's chunks without a re-ingest.
+        from docsgpt.api.user.sources.chunks import GetChunks
+
+        user = "u-path-web"
+        src = _seed_source(pg_conn, user=user)
+
+        fake_store = MagicMock()
+        fake_store.get_chunks.return_value = [
+            {"text": "home", "metadata": {
+                "source": "https://docs.docsgpt.cloud/",
+                "title": "Home - DocsGPT Documentation",
+            }},
+        ]
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.api.user.sources.chunks.get_vector_store",
+            return_value=fake_store,
+        ), app.test_request_context(
+            f"/api/get_chunks?id={src['id']}&path=Home - DocsGPT Documentation"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = GetChunks().get()
+        assert response.status_code == 200
+        assert response.json["total"] == 1
+
     def test_filters_by_search(self, app, pg_conn):
         from docsgpt.api.user.sources.chunks import GetChunks
 
@@ -523,8 +602,7 @@ class TestUpdateChunk:
                 "metadata": {"title": "T"},
             }
         ]
-        fake_store.add_chunk.return_value = "new-chunk-id"
-        fake_store.delete_chunk.return_value = True
+        fake_store.update_chunk.return_value = "chunk-123"
 
         with _patch_db(pg_conn), patch(
             "docsgpt.api.user.sources.chunks.get_vector_store",
@@ -541,4 +619,194 @@ class TestUpdateChunk:
             request.decoded_token = {"sub": user}
             response = UpdateChunk().put()
         assert response.status_code == 200
-        assert response.json["chunk_id"] == "new-chunk-id"
+        assert response.json == {
+            "message": "Chunk updated successfully",
+            "chunk_id": "chunk-123",
+            "original_chunk_id": "chunk-123",
+        }
+        fake_store.update_chunk.assert_called_once()
+        chunk_id, new_text, new_metadata = fake_store.update_chunk.call_args[0]
+        assert (chunk_id, new_text) == ("chunk-123", "new text")
+        assert new_metadata["title"] == "T"
+        assert new_metadata["token_count"] > 0
+        fake_store.add_chunk.assert_not_called()
+        fake_store.delete_chunk.assert_not_called()
+
+    def test_update_failure_returns_500(self, app, pg_conn):
+        from docsgpt.api.user.sources.chunks import UpdateChunk
+
+        user = "u-upd-fail"
+        src = _seed_source(pg_conn, user=user)
+        fake_store = MagicMock()
+        fake_store.get_chunks.return_value = [
+            {"doc_id": "chunk-123", "text": "old", "metadata": {}}
+        ]
+        fake_store.update_chunk.side_effect = RuntimeError("embed down")
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.api.user.sources.chunks.get_vector_store",
+            return_value=fake_store,
+        ), app.test_request_context(
+            "/api/update_chunk", method="PUT",
+            json={"id": str(src["id"]), "chunk_id": "chunk-123", "text": "new"},
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = UpdateChunk().put()
+        assert response.status_code == 500
+        assert response.json == {"error": "Failed to update chunk - addition failed"}
+
+
+    def test_invalid_metadata_keys_return_400(self, app, pg_conn):
+        from docsgpt.api.user.sources.chunks import UpdateChunk
+        from docsgpt.vectorstore.base import InvalidChunkMetadataError
+
+        user = "u-upd-bad-meta"
+        src = _seed_source(pg_conn, user=user)
+        fake_store = MagicMock()
+        fake_store.get_chunks.return_value = [
+            {"doc_id": "chunk-123", "text": "old", "metadata": {}}
+        ]
+        fake_store.update_chunk.side_effect = InvalidChunkMetadataError(
+            "Metadata key 'a.b' is not allowed"
+        )
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.api.user.sources.chunks.get_vector_store",
+            return_value=fake_store,
+        ), app.test_request_context(
+            "/api/update_chunk", method="PUT",
+            json={
+                "id": str(src["id"]),
+                "chunk_id": "chunk-123",
+                "metadata": {"a.b": 1},
+            },
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = UpdateChunk().put()
+        assert response.status_code == 400
+        # Generic message; the offending key is only logged.
+        assert response.json == {"error": "Invalid metadata"}
+
+
+class TestUpdateChunkGraphLinks:
+    """A store that re-ids an edited chunk must take the graph links with it."""
+
+    def _put(self, app, pg_conn, src, user, graph_store, fake_store=None):
+        from docsgpt.api.user.sources.chunks import UpdateChunk
+
+        if fake_store is None:
+            fake_store = MagicMock()
+            # The base fallback: the edit comes back under a new id.
+            fake_store.update_chunk.return_value = "chunk-new"
+        fake_store.get_chunks.return_value = [
+            {"doc_id": "chunk-old", "text": "old", "metadata": {}}
+        ]
+        with _patch_db(pg_conn), patch(
+            "docsgpt.api.user.sources.chunks.get_vector_store",
+            return_value=fake_store,
+        ), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=graph_store
+        ), app.test_request_context(
+            "/api/update_chunk", method="PUT",
+            json={"id": str(src["id"]), "chunk_id": "chunk-old", "text": "new"},
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            return UpdateChunk().put()
+
+    def _graph_source(self, pg_conn, user):
+        from docsgpt.storage.db.repositories.sources import SourcesRepository
+        from docsgpt.storage.db.source_config import SourceConfig
+
+        return SourcesRepository(pg_conn).create(
+            "g", user_id=user, config=SourceConfig.parse({}).graph_enabled()
+        )
+
+    def test_graphrag_source_remaps_links_to_the_new_chunk(self, app, pg_conn):
+        user = "u-upd-graph"
+        src = self._graph_source(pg_conn, user)
+        graph_store = MagicMock()
+
+        response = self._put(app, pg_conn, src, user, graph_store)
+
+        assert response.status_code == 200
+        graph_store.remap_chunk.assert_called_once_with(
+            str(src["id"]), "chunk-old", "chunk-new"
+        )
+
+    def test_classic_source_skips_the_graph(self, app, pg_conn):
+        user = "u-upd-classic"
+        src = _seed_source(pg_conn, user=user)
+        graph_store = MagicMock()
+
+        response = self._put(app, pg_conn, src, user, graph_store)
+
+        assert response.status_code == 200
+        graph_store.remap_chunk.assert_not_called()
+
+    def test_remap_failure_keeps_the_saved_edit(self, app, pg_conn):
+        user = "u-upd-graph-fail"
+        src = self._graph_source(pg_conn, user)
+        graph_store = MagicMock()
+        graph_store.remap_chunk.side_effect = RuntimeError("boom")
+
+        response = self._put(app, pg_conn, src, user, graph_store)
+
+        assert response.status_code == 200
+        assert response.json["chunk_id"] == "chunk-new"
+
+    def test_in_place_update_skips_the_graph_remap(self, app, pg_conn):
+        user = "u-upd-graph-inplace"
+        src = self._graph_source(pg_conn, user)
+        graph_store = MagicMock()
+        fake_store = MagicMock()
+        fake_store.update_chunk.return_value = "chunk-old"
+
+        response = self._put(app, pg_conn, src, user, graph_store, fake_store)
+
+        assert response.status_code == 200
+        assert response.json["chunk_id"] == "chunk-old"
+        assert response.json["original_chunk_id"] == "chunk-old"
+        graph_store.remap_chunk.assert_not_called()
+
+    def test_default_fallback_store_remaps_to_the_new_id(self, app, pg_conn):
+        """A store without its own update (e.g. Milvus) re-adds and re-ids."""
+        from docsgpt.vectorstore.base import BaseVectorStore
+
+        class _FallbackStore(BaseVectorStore):
+            def __init__(self):
+                super().__init__()
+                self.deleted = []
+
+            def search(self, *args, **kwargs):
+                return []
+
+            def add_texts(self, texts, metadatas=None, *args, **kwargs):
+                return []
+
+            def get_chunks(self):
+                return [{"doc_id": "chunk-old", "text": "old", "metadata": {}}]
+
+            def add_chunk(self, text, metadata=None):
+                return "chunk-new"
+
+            def delete_chunk(self, chunk_id):
+                self.deleted.append(chunk_id)
+                return True
+
+        user = "u-upd-graph-fallback"
+        src = self._graph_source(pg_conn, user)
+        graph_store = MagicMock()
+        store = _FallbackStore()
+        store_proxy = MagicMock(wraps=store)
+
+        response = self._put(app, pg_conn, src, user, graph_store, store_proxy)
+
+        assert response.status_code == 200
+        assert response.json["chunk_id"] == "chunk-new"
+        assert store.deleted == ["chunk-old"]
+        graph_store.remap_chunk.assert_called_once_with(
+            str(src["id"]), "chunk-old", "chunk-new"
+        )
diff --git a/tests/api/user/sources/test_graph_view.py b/tests/api/user/sources/test_graph_view.py
index 3bd27f0c..8d06004f 100644
--- a/tests/api/user/sources/test_graph_view.py
+++ b/tests/api/user/sources/test_graph_view.py
@@ -89,6 +89,7 @@ class TestSourceGraph:
 
         store = MagicMock()
         store.count_nodes.return_value = 3
+        store.count_edges.return_value = 5
         store.get_graph_overview.return_value = {
             "nodes": [
                 {"id": "n1", "name": "A", "type": "person",
@@ -114,6 +115,9 @@ class TestSourceGraph:
         assert response.json["success"] is True
         assert {n["id"] for n in response.json["nodes"]} == {"n1", "n2"}
         assert response.json["edges"][0]["source"] == "n1"
+        # Totals describe the whole graph, not the bounded overview.
+        assert response.json["stats"] == {"nodes": 3, "edges": 5}
+        store.count_edges.assert_called_once_with(sid)
         # The store receives the source's resolved id and the clamped limit.
         args = store.get_graph_overview.call_args.args
         assert args[0] == sid
@@ -140,6 +144,7 @@ class TestSourceGraph:
         assert response.status_code == 200
         assert response.json["nodes"] == []
         assert response.json["edges"] == []
+        assert response.json["stats"] == {"nodes": 0, "edges": 0}
         # No graph rows → never query the overview.
         store.get_graph_overview.assert_not_called()
 
@@ -172,6 +177,7 @@ class TestSourceGraph:
 
         store = MagicMock()
         store.count_nodes.return_value = 1
+        store.count_edges.return_value = 0
         store.get_graph_overview.return_value = {
             "nodes": [
                 {"id": "n1", "name": "A", "type": None,
@@ -189,8 +195,315 @@ class TestSourceGraph:
 
         assert response.status_code == 200
         assert {n["id"] for n in response.json["nodes"]} == {"n1"}
+        assert response.json["stats"] == {"nodes": 1, "edges": 0}
 
 
+def _node_list_store():
+    store = MagicMock()
+    store.list_nodes.return_value = {
+        "nodes": [
+            {"id": "n1", "name": "Ada", "type": "Person", "degree": 3,
+             "doc_freq": 2},
+        ],
+        "total": 41,
+    }
+    store.node_type_facets.return_value = [
+        {"key": "person", "label": "Person", "count": 30},
+        {"key": "", "label": None, "count": 11},
+    ]
+    return store
+
+
+@pytest.mark.unit
+class TestSourceGraphNodes:
+    def test_returns_401_unauthenticated(self, app):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        with app.test_request_context("/api/sources/x/graph/nodes"):
+            from flask import request
+            request.decoded_token = None
+            response = SourceGraphNodes().get("x")
+        assert response.status_code == 401
+
+    def test_owner_gets_paged_nodes_and_type_facets(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-owner"
+        sid = _graphrag_source(pg_conn, user)
+        store = _node_list_store()
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert response.json == {
+            "success": True,
+            "nodes": [
+                {"id": "n1", "name": "Ada", "type": "Person", "degree": 3,
+                 "doc_freq": 2},
+            ],
+            "total": 41,
+            "page": 1,
+            "per_page": 25,
+            "types": [
+                {"key": "person", "label": "Person", "count": 30},
+                {"key": "", "label": None, "count": 11},
+            ],
+        }
+        store.list_nodes.assert_called_once_with(
+            sid, query=None, type_key=None, offset=0, limit=25
+        )
+        store.node_type_facets.assert_called_once_with(sid)
+
+    def test_forwards_filters_and_clamps_paging(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-params"
+        sid = _graphrag_source(pg_conn, user)
+        store = _node_list_store()
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(
+            f"/api/sources/{sid}/graph/nodes?q=%20ada%20&type=person&page=3&per_page=500"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert response.json["page"] == 3
+        assert response.json["per_page"] == 100
+        store.list_nodes.assert_called_once_with(
+            sid, query="ada", type_key="person", offset=200, limit=100
+        )
+
+    @pytest.mark.parametrize(
+        "qs, page, per_page",
+        [
+            ("page=0&per_page=0", 1, 1),
+            ("page=-4&per_page=-9", 1, 1),
+            ("page=abc&per_page=xyz", 1, 25),
+        ],
+    )
+    def test_bad_paging_values_fall_back(self, app, pg_conn, qs, page, per_page):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-bad-paging"
+        sid = _graphrag_source(pg_conn, user)
+        store = _node_list_store()
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes?{qs}"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert (response.json["page"], response.json["per_page"]) == (page, per_page)
+        kwargs = store.list_nodes.call_args.kwargs
+        assert kwargs["offset"] == (page - 1) * per_page
+        assert kwargs["limit"] == per_page
+
+    def test_non_owner_without_grant_404(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        owner = "u-graph-nodes-owner2"
+        stranger = "u-graph-nodes-stranger"
+        sid = _graphrag_source(pg_conn, owner)
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore"
+        ) as mock_store, app.test_request_context(
+            f"/api/sources/{sid}/graph/nodes"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": stranger}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 404
+        mock_store.assert_not_called()
+
+    def test_team_viewer_can_read(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        owner = "alice-graph-nodes"
+        viewer = "bob-graph-nodes-viewer"
+        sid = _graphrag_source(pg_conn, owner)
+        _grant_team_access(pg_conn, owner, viewer, sid, "viewer")
+        store = _node_list_store()
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes"):
+            from flask import request
+            request.decoded_token = {"sub": viewer}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert response.json["total"] == 41
+        assert store.list_nodes.call_args.args == (sid,)
+
+    def test_store_failure_returns_400(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-fail"
+        sid = _graphrag_source(pg_conn, user)
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", side_effect=RuntimeError("no db")
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 400
+
+
+def _real_store_with_mock_conn(fail: bool = False, total: int = 0):
+    """A real ``GraphStore`` whose connection is a mock, so the store's own
+    error handling runs. ``fail`` makes every query raise."""
+    from docsgpt.graphrag.store import GraphStore
+
+    store = GraphStore.__new__(GraphStore)
+    cursor = MagicMock()
+    cursor.fetchone.return_value = [total]
+    cursor.fetchall.return_value = []
+    if fail:
+        cursor.execute.side_effect = RuntimeError("connection reset")
+    conn = MagicMock()
+    conn.cursor.return_value = cursor
+    store._connection = conn
+    store._get_connection = lambda: conn
+    store._tables_ensured = True
+    return store, cursor
+
+
+@pytest.mark.unit
+class TestSourceGraphNodesRealStore:
+    def test_query_failure_returns_400_not_empty_200(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-query-fail"
+        sid = _graphrag_source(pg_conn, user)
+        store, _ = _real_store_with_mock_conn(fail=True)
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 400
+        assert response.json == {"success": False}
+
+    def test_empty_graph_returns_empty_200(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-empty"
+        sid = _graphrag_source(pg_conn, user)
+        store, _ = _real_store_with_mock_conn(total=0)
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert response.json["nodes"] == []
+        assert response.json["total"] == 0
+        assert response.json["types"] == []
+
+    def _get(self, app, pg_conn, user, store=None, store_error=None, qs=""):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        sid = _graphrag_source(pg_conn, user)
+        kwargs = {"side_effect": store_error} if store_error else {"return_value": store}
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", **kwargs
+        ), app.test_request_context(f"/api/sources/{sid}/graph/nodes{qs}"):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            return SourceGraphNodes().get(sid)
+
+    def test_missing_graph_tables_return_empty_200(self, app, pg_conn):
+        import psycopg
+
+        store, cursor = _real_store_with_mock_conn()
+        cursor.execute.side_effect = psycopg.errors.UndefinedTable(
+            'relation "graph_nodes" does not exist'
+        )
+
+        response = self._get(
+            app, pg_conn, "u-graph-nodes-no-tables", store=store,
+            qs="?type=person&page=2&per_page=10",
+        )
+
+        assert response.status_code == 200
+        assert response.json == {
+            "success": True,
+            "nodes": [],
+            "total": 0,
+            "page": 2,
+            "per_page": 10,
+            "types": [],
+        }
+
+    def test_unconfigured_graph_store_returns_empty_200(self, app, pg_conn):
+        response = self._get(
+            app, pg_conn, "u-graph-nodes-unconfigured",
+            store_error=ValueError("PostgreSQL connection string is required."),
+        )
+
+        assert response.status_code == 200
+        assert response.json["nodes"] == []
+        assert response.json["total"] == 0
+        assert response.json["types"] == []
+
+    def test_other_store_errors_still_return_400(self, app, pg_conn):
+        import psycopg
+
+        store, cursor = _real_store_with_mock_conn()
+        cursor.execute.side_effect = psycopg.errors.InvalidTextRepresentation("bad")
+
+        response = self._get(app, pg_conn, "u-graph-nodes-bad-input", store=store)
+
+        assert response.status_code == 400
+        assert response.json == {"success": False}
+
+    def test_huge_page_is_clamped_and_keeps_the_total(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+        from docsgpt.graphrag.store import GRAPH_NODE_LIST_MAX_PAGE
+
+        user = "u-graph-nodes-huge-page"
+        sid = _graphrag_source(pg_conn, user)
+        store, cursor = _real_store_with_mock_conn(total=41)
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(
+            f"/api/sources/{sid}/graph/nodes?page=100000000000000000000&per_page=100"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        assert response.json["total"] == 41
+        assert response.json["nodes"] == []
+        assert response.json["page"] == GRAPH_NODE_LIST_MAX_PAGE
+        offset = cursor.execute.call_args_list[1].args[1][-1]
+        assert offset == (GRAPH_NODE_LIST_MAX_PAGE - 1) * 100
+        assert offset < 2**63
+
 @pytest.mark.unit
 class TestSourceGraphNode:
     def test_returns_401_unauthenticated(self, app):
@@ -216,6 +529,11 @@ class TestSourceGraphNode:
             "description": "A mathematician.",
             "degree": 3,
             "doc_freq": 2,
+            "relationships": [
+                {"id": "n2", "name": "Alan", "type": "person", "degree": 2,
+                 "edge_type": "knows", "direction": "out"},
+            ],
+            "relationships_total": 1204,
             "chunks": [{"chunk_id": "5", "text": "body", "metadata": {}}],
         }
 
@@ -229,6 +547,9 @@ class TestSourceGraphNode:
         assert response.status_code == 200
         assert response.json["node"]["name"] == "Ada"
         assert response.json["node"]["chunks"][0]["text"] == "body"
+        # The capped list and its true total pass through untouched.
+        assert len(response.json["node"]["relationships"]) == 1
+        assert response.json["node"]["relationships_total"] == 1204
         store.get_node_detail.assert_called_once_with(sid, "n1")
 
     def test_unknown_node_404(self, app, pg_conn):
diff --git a/tests/api/user/sources/test_routes.py b/tests/api/user/sources/test_routes.py
index 35a57a68..0fb117c8 100644
--- a/tests/api/user/sources/test_routes.py
+++ b/tests/api/user/sources/test_routes.py
@@ -887,6 +887,49 @@ class TestDirectoryStructure:
         assert data["provider"] == "gdrive"
         assert data["base_path"] == "/data/nested"
 
+    def test_team_viewer_can_read(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import DirectoryStructure
+        from docsgpt.storage.db.repositories.team_members import TeamMembersRepository
+        from docsgpt.storage.db.repositories.team_resource_grants import TeamResourceGrantsRepository
+        from docsgpt.storage.db.repositories.teams import TeamsRepository
+
+        owner, viewer = "u-dir-owner", "u-dir-viewer"
+        src = _seed_source(
+            pg_conn, owner, name="shared",
+            directory_structure={"a.docx": {"type": "application/docx"}},
+        )
+        team = TeamsRepository(pg_conn).create("Acme", "acme-dir", owner)
+        TeamMembersRepository(pg_conn).add_member(team["id"], viewer, role="team_member")
+        TeamResourceGrantsRepository(pg_conn).grant(
+            team["id"], "source", str(src["id"]), owner_id=owner, granted_by=owner,
+            access_level="viewer",
+        )
+
+        with _patch_db(pg_conn), app.test_request_context(
+            f"/api/directory_structure?id={src['id']}"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": viewer}
+            response = DirectoryStructure().get()
+        assert response.status_code == 200
+        assert response.json["directory_structure"] == {"a.docx": {"type": "application/docx"}}
+
+    def test_non_owner_without_grant_404(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import DirectoryStructure
+
+        src = _seed_source(
+            pg_conn, "u-dir-owner2", name="private",
+            directory_structure={"a.txt": None},
+        )
+
+        with _patch_db(pg_conn), app.test_request_context(
+            f"/api/directory_structure?id={src['id']}"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": "u-dir-stranger"}
+            response = DirectoryStructure().get()
+        assert response.status_code == 404
+
 
 class TestSourceConfigResource:
     def test_returns_401_unauthenticated(self, app):
diff --git a/tests/graphrag/test_store.py b/tests/graphrag/test_store.py
index d9de877a..0d3e6c87 100644
--- a/tests/graphrag/test_store.py
+++ b/tests/graphrag/test_store.py
@@ -444,6 +444,197 @@ class TestGraphStoreLive:
         finally:
             store.delete_by_source(source_id)
 
+    def _seed_typed_graph(self, store, source_id):
+        """Six nodes whose types spell ``person`` three ways, plus edges for degree."""
+        ids = {
+            "ada": store.upsert_node(source_id, "Ada Lovelace", "ada lovelace", "Person"),
+            "alan": store.upsert_node(source_id, "Alan Turing", "alan turing", "Person"),
+            "grace": store.upsert_node(source_id, "Grace Hopper", "grace hopper", "PERSON"),
+            "babbage": store.upsert_node(source_id, "Babbage", "babbage", "per son"),
+            "acme": store.upsert_node(source_id, "Acme_Corp", "acme_corp", "org"),
+            "sure": store.upsert_node(source_id, "100%_Sure", "100%_sure"),
+        }
+        # Degrees: ada 3, alan 2, acme 2, grace 1, babbage 0, sure 0.
+        store.add_edge(source_id, ids["ada"], ids["alan"], "knows")
+        store.add_edge(source_id, ids["ada"], ids["acme"], "works_at")
+        store.add_edge(source_id, ids["grace"], ids["ada"], "cites")
+        store.add_edge(source_id, ids["alan"], ids["acme"], "works_at")
+        store.set_node_degrees(source_id)
+        return ids
+
+    def test_list_nodes_filters_pages_and_counts(self, store, source_id):
+        try:
+            ids = self._seed_typed_graph(store, source_id)
+
+            everything = store.list_nodes(source_id)
+            assert everything["total"] == 6
+            ordered = [n["id"] for n in everything["nodes"]]
+            assert ordered[0] == ids["ada"]
+            # Degree DESC, then id: alan and acme tie on 2.
+            assert set(ordered[1:3]) == {ids["alan"], ids["acme"]}
+            assert ordered[1:3] == sorted(ordered[1:3])
+            first = everything["nodes"][0]
+            assert set(first) == {"id", "name", "type", "degree", "doc_freq"}
+            assert first["degree"] == 3 and first["doc_freq"] == 1
+
+            by_name = store.list_nodes(source_id, query="ADA")
+            assert [n["id"] for n in by_name["nodes"]] == [ids["ada"]]
+            assert by_name["total"] == 1
+
+            # ``%`` and ``_`` are literals, not wildcards.
+            assert [n["id"] for n in store.list_nodes(source_id, query="%")["nodes"]] == [
+                ids["sure"]
+            ]
+            underscored = store.list_nodes(source_id, query="_")
+            assert {n["id"] for n in underscored["nodes"]} == {ids["acme"], ids["sure"]}
+
+            people = store.list_nodes(source_id, type_key="person")
+            assert people["total"] == 4
+            assert {n["id"] for n in people["nodes"]} == {
+                ids["ada"], ids["alan"], ids["grace"], ids["babbage"]
+            }
+
+            untyped = store.list_nodes(source_id, type_key="")
+            assert [n["id"] for n in untyped["nodes"]] == [ids["sure"]]
+
+            both = store.list_nodes(source_id, query="a", type_key="person")
+            assert both["total"] == 4
+
+            page = store.list_nodes(source_id, type_key="person", offset=1, limit=2)
+            assert page["total"] == 4
+            assert [n["id"] for n in page["nodes"]] == [
+                n["id"] for n in people["nodes"][1:3]
+            ]
+            beyond = store.list_nodes(source_id, offset=50, limit=10)
+            assert beyond == {"nodes": [], "total": 6}
+        finally:
+            store.delete_by_source(source_id)
+
+    def test_node_type_facets_fold_spellings_into_one_key(self, store, source_id):
+        try:
+            self._seed_typed_graph(store, source_id)
+
+            facets = store.node_type_facets(source_id)
+
+            assert facets == [
+                {"key": "person", "label": "Person", "count": 4},
+                {"key": "org", "label": "org", "count": 1},
+                {"key": "", "label": None, "count": 1},
+            ]
+            assert store.node_type_facets(str(uuid.uuid4())) == []
+        finally:
+            store.delete_by_source(source_id)
+
+    def test_count_edges(self, store, source_id):
+        try:
+            assert store.count_edges(source_id) == 0
+            self._seed_typed_graph(store, source_id)
+            assert store.count_edges(source_id) == 4
+            assert store.count_edges(str(uuid.uuid4())) == 0
+        finally:
+            store.delete_by_source(source_id)
+
+    def test_node_detail_lists_relationships_in_both_directions(self, store, source_id):
+        try:
+            ids = self._seed_typed_graph(store, source_id)
+            # ``add_edge`` drops self-loops, so plant one directly: the reader
+            # must skip it too.
+            conn = store._get_connection()
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO graph_edges (id, source_id, src_node_id, dst_node_id, type) "
+                    "VALUES (%s, %s, %s, %s, 'self');",
+                    (str(uuid.uuid4()), source_id, ids["ada"], ids["ada"]),
+                )
+            conn.commit()
+
+            detail = store.get_node_detail(source_id, ids["ada"])
+
+            assert detail["name"] == "Ada Lovelace"
+            assert "chunks" in detail
+            rels = detail["relationships"]
+            assert len(rels) == 3
+            # Neighbour degree DESC, then neighbour id: alan and acme tie on 2.
+            assert [r["id"] for r in rels[:2]] == sorted([ids["alan"], ids["acme"]])
+            by_id = {r["id"]: r for r in rels}
+            assert by_id[ids["alan"]] == {
+                "id": ids["alan"], "name": "Alan Turing", "type": "Person",
+                "degree": 2, "edge_type": "knows", "direction": "out",
+            }
+            assert by_id[ids["acme"]]["edge_type"] == "works_at"
+            assert by_id[ids["acme"]]["direction"] == "out"
+            assert rels[2] == {
+                "id": ids["grace"], "name": "Grace Hopper", "type": "PERSON",
+                "degree": 1, "edge_type": "cites", "direction": "in",
+            }
+
+            assert detail["relationships_total"] == 3
+
+            lonely = store.get_node_detail(source_id, ids["babbage"])
+            assert lonely["relationships"] == []
+            assert lonely["relationships_total"] == 0
+        finally:
+            store.delete_by_source(source_id)
+
+    def test_node_detail_counts_every_relationship_past_the_cap(
+        self, store, source_id, monkeypatch
+    ):
+        try:
+            ids = self._seed_typed_graph(store, source_id)
+            conn = store._get_connection()
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO graph_edges (id, source_id, src_node_id, dst_node_id, type) "
+                    "VALUES (%s, %s, %s, %s, 'self');",
+                    (str(uuid.uuid4()), source_id, ids["ada"], ids["ada"]),
+                )
+            conn.commit()
+            monkeypatch.setattr(store_module, "MAX_NODE_RELATIONSHIPS", 2)
+
+            detail = store.get_node_detail(source_id, ids["ada"])
+
+            # The list stops at the cap; the total counts both directions and
+            # still skips the self-loop.
+            assert len(detail["relationships"]) == 2
+            assert detail["relationships_total"] == 3
+        finally:
+            store.delete_by_source(source_id)
+
+    def test_remap_chunk_moves_every_link_to_the_new_id(self, store, source_id):
+        try:
+            ada = store.upsert_node(source_id, "Ada", "ada")
+            alan = store.upsert_node(source_id, "Alan", "alan")
+            store.link_node_chunk(source_id, ada, "old")
+            store.link_node_chunk(source_id, alan, "keep")
+            store.add_edge(
+                source_id, ada, alan, "knows", source_chunk_ids=["keep", "old"]
+            )
+            store.mark_chunk(source_id, "old", "done")
+            other = str(uuid.uuid4())
+            other_node = store.upsert_node(other, "Ada", "ada")
+            store.link_node_chunk(other, other_node, "old")
+
+            store.remap_chunk(source_id, "old", "new")
+
+            links = store.get_chunk_ids_for_nodes(source_id, [ada, alan])
+            assert links == {ada: ["new"], alan: ["keep"]}
+            conn = store._get_connection()
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "SELECT source_chunk_ids FROM graph_edges WHERE source_id = %s;",
+                    (source_id,),
+                )
+                assert cursor.fetchone()[0] == ["keep", "new"]
+            conn.rollback()
+            assert store.pending_chunks(source_id, ["old", "new"]) == ["old"]
+            # Another source's link to the same chunk id is left alone.
+            assert store.get_chunk_ids_for_nodes(other, [other_node]) == {
+                other_node: ["old"]
+            }
+        finally:
+            store.delete_by_source(source_id)
+            store.delete_by_source(other)
+
     def test_checkpoint_pending_and_mark(self, store, source_id):
         try:
             all_chunks = ["c1", "c2", "c3"]
@@ -648,6 +839,238 @@ class TestGraphStoreParameterization:
         # limit is clamped to the hard cap before binding.
         assert params == (sid, GRAPH_OVERVIEW_MAX_LIMIT)
 
+    def test_count_edges_binds_source(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchone.return_value = [7]
+        sid = str(uuid.uuid4())
+
+        assert store.count_edges(sid) == 7
+
+        sql, params = cursor.execute.call_args.args
+        assert "FROM graph_edges" in sql
+        assert "source_id = %s" in sql
+        assert sid not in sql
+        assert params == (sid,)
+
+    def test_count_edges_failure_reports_zero(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.execute.side_effect = RuntimeError("relation does not exist")
+
+        assert store.count_edges(str(uuid.uuid4())) == 0
+
+    def test_count_edges_has_no_strict_mode(self):
+        import inspect
+
+        assert "strict" not in inspect.signature(GraphStore.count_edges).parameters
+
+    def test_list_nodes_binds_values_and_escapes_the_pattern(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchone.return_value = [0]
+        cursor.fetchall.side_effect = [[("Person",), ("person",), ("Org",)], []]
+        sid = str(uuid.uuid4())
+        query = "50%_a\\b"
+
+        result = store.list_nodes(
+            sid, query=query, type_key="person", offset=40, limit=10_000
+        )
+
+        assert result == {"nodes": [], "total": 0}
+        pattern = "%50\\%\\_a\\\\b%"
+        types_sql, types_params = cursor.execute.call_args_list[0].args
+        assert "DISTINCT type" in types_sql
+        assert types_params == (sid,)
+        for call in cursor.execute.call_args_list[1:]:
+            sql, params = call.args
+            assert sid not in sql
+            assert query not in sql
+            assert "person" not in sql
+            assert "ILIKE %s" in sql
+            assert "type = ANY(%s)" in sql
+            assert params[:3] == (sid, pattern, ["Person", "person"])
+        count_sql, count_params = cursor.execute.call_args_list[1].args
+        assert "count(*)" in count_sql
+        page_sql, page_params = cursor.execute.call_args_list[-1].args
+        assert "ORDER BY degree DESC, id" in page_sql
+        # The page size is clamped to the hard cap before binding.
+        assert page_params[3:] == (store_module.GRAPH_NODE_LIST_MAX_LIMIT, 40)
+
+    def test_list_nodes_without_filters_binds_only_the_source(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchone.return_value = [0]
+        sid = str(uuid.uuid4())
+
+        store.list_nodes(sid, query="  ", offset=-5, limit=0)
+
+        count_sql, count_params = cursor.execute.call_args_list[0].args
+        assert "ILIKE" not in count_sql
+        assert "regexp_replace" not in count_sql
+        assert count_params == (sid,)
+        _, page_params = cursor.execute.call_args_list[-1].args
+        assert page_params == (sid, 1, 0)
+
+    def test_list_nodes_failure_propagates(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.execute.side_effect = RuntimeError("boom")
+
+        with pytest.raises(RuntimeError):
+            store.list_nodes("sid")
+        cursor.close.assert_called_once()
+
+    def test_list_nodes_empty_graph_returns_empty(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchone.return_value = [0]
+        cursor.fetchall.return_value = []
+
+        assert store.list_nodes("sid") == {"nodes": [], "total": 0}
+
+    def test_node_type_facets_bind_source(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchall.return_value = [("Person", 4), (None, 1)]
+        sid = str(uuid.uuid4())
+
+        facets = store.node_type_facets(sid)
+
+        sql, params = cursor.execute.call_args.args
+        assert sid not in sql
+        assert params == (sid,)
+        assert facets == [
+            {"key": "person", "label": "Person", "count": 4},
+            {"key": "", "label": None, "count": 1},
+        ]
+
+    def test_node_type_facets_failure_propagates(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.execute.side_effect = RuntimeError("boom")
+
+        with pytest.raises(RuntimeError):
+            store.node_type_facets("sid")
+        cursor.close.assert_called_once()
+
+    def test_node_type_facets_empty_graph_returns_empty(self):
+        store, cursor = self._store_with_mock_conn()
+        cursor.fetchall.return_value = []
+
+        assert store.node_type_facets("sid") == []
+
+    def test_node_detail_relationships_bind_ids_and_cap(self):
+        store, cursor = self._store_with_mock_conn()
+        sid = str(uuid.uuid4())
+        nid = str(uuid.uuid4())
+        other = str(uuid.uuid4())
+        cursor.fetchone.return_value = (nid, "Ada", "person", "d", 1, 1)
+        cursor.fetchall.side_effect = [
+            [(other, "Alan", "person", 2, "knows", "out")],  # relationships
+            [],  # chunk ids
+        ]
+
+        detail = store.get_node_detail(sid, nid)
+
+        assert detail["relationships"] == [
+            {"id": other, "name": "Alan", "type": "person", "degree": 2,
+             "edge_type": "knows", "direction": "out"},
+        ]
+        rel_call = next(
+            c for c in cursor.execute.call_args_list if "direction" in c.args[0]
+        )
+        sql, params = rel_call.args
+        assert sid not in sql and nid not in sql
+        assert "src_node_id <> e.dst_node_id" in sql
+        assert sid in params and nid in params
+        assert params[-1] == store_module.MAX_NODE_RELATIONSHIPS == 300
+        # Under the cap the list is the whole set: no COUNT query.
+        assert detail["relationships_total"] == 1
+        assert not any(
+            "COUNT(*)" in c.args[0] for c in cursor.execute.call_args_list
+        )
+
+    def test_node_detail_counts_relationships_when_capped(self, monkeypatch):
+        store, cursor = self._store_with_mock_conn()
+        monkeypatch.setattr(store_module, "MAX_NODE_RELATIONSHIPS", 2)
+        sid = str(uuid.uuid4())
+        nid = str(uuid.uuid4())
+        rel = (str(uuid.uuid4()), "Alan", "person", 2, "knows", "out")
+        cursor.fetchone.side_effect = [
+            (nid, "Ada", "person", "d", 1, 1),  # the node
+            (1204,),  # relationships total
+        ]
+        cursor.fetchall.side_effect = [[rel, rel], []]
+
+        detail = store.get_node_detail(sid, nid)
+
+        assert len(detail["relationships"]) == 2
+        assert detail["relationships_total"] == 1204
+        count_sql, count_params = next(
+            c.args for c in cursor.execute.call_args_list if "COUNT(*)" in c.args[0]
+        )
+        assert sid not in count_sql and nid not in count_sql
+        assert "src_node_id <> e.dst_node_id" in count_sql
+        assert "LIMIT" not in count_sql
+        assert sid in count_params and nid in count_params
+
+    def test_node_detail_total_falls_back_when_the_count_fails(self, monkeypatch):
+        store, cursor = self._store_with_mock_conn()
+        monkeypatch.setattr(store_module, "MAX_NODE_RELATIONSHIPS", 1)
+        sid = str(uuid.uuid4())
+        nid = str(uuid.uuid4())
+        cursor.fetchone.return_value = (nid, "Ada", "person", "d", 1, 1)
+        cursor.fetchall.side_effect = [
+            [(str(uuid.uuid4()), "Alan", "person", 2, "knows", "out")],
+            [],
+        ]
+
+        def execute(sql, params=None):
+            if "COUNT(*)" in sql:
+                raise RuntimeError("boom")
+
+        cursor.execute.side_effect = execute
+
+        detail = store.get_node_detail(sid, nid)
+
+        assert detail["relationships_total"] == 1
+        assert len(detail["relationships"]) == 1
+
+    def test_remap_chunk_binds_ids_under_the_source_lock(self):
+        store, cursor = self._store_with_mock_conn()
+        store._write_with_reconnect = lambda write: write(store._connection)
+        sid = str(uuid.uuid4())
+
+        store.remap_chunk(sid, "old-id", "new-id")
+
+        calls = cursor.execute.call_args_list
+        assert "pg_advisory_xact_lock" in calls[0].args[0]
+        tables = ["graph_node_chunks", "graph_edges", "graph_ingest_progress"]
+        for table in tables:
+            sql, params = next(c.args for c in calls if table in c.args[0])
+            assert sid not in sql and "old-id" not in sql and "new-id" not in sql
+            assert {sid, "old-id", "new-id"} <= set(params)
+        store._connection.commit.assert_called_once()
+
+    def test_node_detail_survives_a_relationships_failure(self):
+        # A failed relationships read degrades to an empty list; the node and
+        # its chunks still come back instead of the whole detail 404ing.
+        store, cursor = self._store_with_mock_conn()
+        conn = store._connection
+        sid = str(uuid.uuid4())
+        nid = str(uuid.uuid4())
+        cursor.fetchone.return_value = (nid, "Ada", "person", "d", 1, 1)
+
+        def execute(sql, params=None):
+            if "direction" in sql:
+                raise RuntimeError("boom")
+
+        cursor.execute.side_effect = execute
+        cursor.fetchall.return_value = []
+
+        detail = store.get_node_detail(sid, nid)
+
+        assert detail is not None
+        assert detail["name"] == "Ada"
+        assert detail["relationships"] == []
+        assert detail["relationships_total"] == 0
+        assert detail["chunks"] == []
+        # The aborted transaction is rolled back before the chunk read reuses it.
+        assert conn.rollback.call_count >= 2
+
     def test_upsert_node_binds_all_values(self):
         store, cursor = self._store_with_mock_conn()
         sid = str(uuid.uuid4())
@@ -1028,6 +1451,14 @@ class TestGraphSchemaIsBootOwned:
             lambda s: s.get_chunk_ids_for_nodes("sid", ["n"]),
             lambda s: s.pending_chunks("sid", ["c1"]),
             lambda s: s.get_progress("sid"),
+            lambda s: s.count_edges("sid"),
+            # list_nodes now surfaces query errors, so feed it a numeric count row.
+            lambda s: (
+                setattr(s._get_connection().cursor(), "fetchone", lambda: [0]),
+                s.list_nodes("sid", query="a", type_key="person"),
+            ),
+            lambda s: s.node_type_facets("sid"),
+            lambda s: s.get_node_detail("sid", "n"),
         ],
         ids=[
             "count_nodes",
@@ -1039,6 +1470,10 @@ class TestGraphSchemaIsBootOwned:
             "get_chunk_ids_for_nodes",
             "pending_chunks",
             "get_progress",
+            "count_edges",
+            "list_nodes",
+            "node_type_facets",
+            "get_node_detail",
         ],
     )
     def test_reads_never_create_tables(self, call):
@@ -1546,3 +1981,182 @@ class TestApplyChunkIsReplaySafe:
             assert node["doc_freq"] == 2
         finally:
             store.delete_by_source(source_id)
+
+
+@pytest.mark.unit
+class TestGraphTypeKey:
+    """The Python type key must match the frontend's."""
+
+    @pytest.mark.parametrize(
+        "raw, key",
+        [
+            ("Person", "person"),
+            ("PERSON", "person"),
+            ("per son", "person"),
+            ("Org-Unit_2", "orgunit2"),
+            ("", ""),
+            (None, ""),
+            ("---", ""),
+        ],
+    )
+    def test_key(self, raw, key):
+        assert store_module.graph_type_key(raw) == key
+        # Non-ASCII types fold the same way the frontend's ``\p{L}\p{N}`` does.
+        assert store_module.graph_type_key("Ком-пания") == "компания"
+        assert store_module.graph_type_key("人 物") == "人物"
+
+
+@pytest.mark.integration
+class TestTypeKeysOnACLocaleDatabase:
+    """Type keys must not depend on the database's ``LC_CTYPE``.
+
+    Managed Postgres commonly runs ``C``: there ``lower()`` leaves Cyrillic
+    alone and ``[:alnum:]`` matches ASCII only, so a key computed in SQL folds
+    ``Компания`` to ``""``. Only the columns these reads touch are created, so
+    the test runs without the pgvector extension.
+    """
+
+    @pytest.fixture
+    def c_store(self, postgresql):
+        import psycopg
+
+        base = _ephemeral_dsn(postgresql.info)
+        dbname = f"graph_c_{uuid.uuid4().hex[:8]}"
+        with psycopg.connect(base, autocommit=True) as admin:
+            admin.execute(
+                f"CREATE DATABASE {dbname} TEMPLATE template0 ENCODING 'UTF8' "
+                "LC_COLLATE 'C' LC_CTYPE 'C';"
+            )
+        dsn = base.rsplit("/", 1)[0] + f"/{dbname}"
+        with psycopg.connect(dsn, autocommit=True) as conn:
+            conn.execute(
+                """
+                CREATE TABLE graph_nodes (
+                    id UUID PRIMARY KEY, source_id UUID NOT NULL, name TEXT,
+                    normalized_name TEXT, type TEXT, description TEXT,
+                    degree INT DEFAULT 0, doc_freq INT DEFAULT 0
+                );
+                """
+            )
+        store = GraphStore(connection_string=dsn)
+        store._pool_max_size = 0
+        try:
+            yield store, dsn
+        finally:
+            store.close()
+            with psycopg.connect(base, autocommit=True) as admin:
+                admin.execute(f"DROP DATABASE IF EXISTS {dbname} WITH (FORCE);")
+
+    def test_non_ascii_types_facet_and_filter(self, c_store):
+        import psycopg
+
+        store, dsn = c_store
+        sid, other = str(uuid.uuid4()), str(uuid.uuid4())
+        rows = [
+            (sid, "a", "Компания", 5),
+            (sid, "b", "Компания", 4),
+            (sid, "c", "компания", 3),
+            (sid, "d", "人物", 2),
+            (sid, "e", "人 物", 1),
+            (sid, "f", None, 0),
+            (sid, "g", "---", 0),
+            (sid, "h", "Person", 0),
+            (other, "x", "Компания", 9),
+        ]
+        with psycopg.connect(dsn, autocommit=True) as conn:
+            for source, name, type_, degree in rows:
+                conn.execute(
+                    "INSERT INTO graph_nodes (id, source_id, name, normalized_name, "
+                    "type, degree) VALUES (%s, %s, %s, %s, %s, %s);",
+                    (str(uuid.uuid4()), source, name, name, type_, degree),
+                )
+
+        assert store.node_type_facets(sid) == [
+            {"key": "компания", "label": "Компания", "count": 3},
+            {"key": "人物", "label": "人 物", "count": 2},
+            {"key": "", "label": None, "count": 2},
+            {"key": "person", "label": "Person", "count": 1},
+        ]
+        companies = store.list_nodes(sid, type_key="компания")
+        assert companies["total"] == 3
+        assert [n["name"] for n in companies["nodes"]] == ["a", "b", "c"]
+        assert store.list_nodes(sid, type_key="人物")["total"] == 2
+        untyped = store.list_nodes(sid, type_key="")
+        assert sorted(n["name"] for n in untyped["nodes"]) == ["f", "g"]
+        assert store.list_nodes(sid, type_key="person", query="h")["total"] == 1
+        assert store.list_nodes(sid, type_key="missing") == {"nodes": [], "total": 0}
+
+
+@pytest.mark.unit
+class TestTypeKeyFoldingInPython:
+    """Facets and the type filter fold raw types with ``graph_type_key``."""
+
+    def _store(self):
+        store = GraphStore.__new__(GraphStore)
+        cursor = MagicMock()
+        conn = MagicMock()
+        conn.cursor.return_value = cursor
+        store._connection = conn
+        store._get_connection = lambda: conn
+        store._tables_ensured = True
+        return store, cursor
+
+    def test_facets_group_raw_types_and_pick_the_label(self):
+        store, cursor = self._store()
+        cursor.fetchall.return_value = [
+            ("Компания", 2), ("компания", 2), ("КОМПАНИЯ", 1),
+            (None, 1), ("---", 3), ("人物", 5),
+        ]
+        sid = str(uuid.uuid4())
+
+        facets = store.node_type_facets(sid)
+
+        sql_text, params = cursor.execute.call_args.args
+        assert "GROUP BY type" in sql_text
+        assert "regexp_replace" not in sql_text
+        assert params == (sid,)
+        # Most frequent spelling wins; a tie goes to the alphabetically first.
+        assert facets == [
+            {"key": "компания", "label": "Компания", "count": 5},
+            {"key": "人物", "label": "人物", "count": 5},
+            {"key": "", "label": None, "count": 4},
+        ]
+
+    def test_type_filter_binds_the_matching_raw_types(self):
+        store, cursor = self._store()
+        cursor.fetchall.side_effect = [
+            [("Компания",), ("компания",), ("Person",), (None,)],
+            [],
+        ]
+        cursor.fetchone.return_value = [3]
+        sid = str(uuid.uuid4())
+
+        result = store.list_nodes(sid, type_key="компания")
+
+        assert result == {"nodes": [], "total": 3}
+        distinct_sql, distinct_params = cursor.execute.call_args_list[0].args
+        assert "DISTINCT type" in distinct_sql
+        assert distinct_params == (sid,)
+        count_sql, count_params = cursor.execute.call_args_list[1].args
+        assert "type = ANY(%s)" in count_sql
+        assert "IS NULL" not in count_sql
+        assert count_params == (sid, ["Компания", "компания"])
+
+    def test_untyped_filter_includes_null_and_types_that_fold_to_empty(self):
+        store, cursor = self._store()
+        cursor.fetchall.side_effect = [[("---",), ("Person",), (None,)], []]
+        cursor.fetchone.return_value = [2]
+        sid = str(uuid.uuid4())
+
+        store.list_nodes(sid, type_key="")
+
+        count_sql, count_params = cursor.execute.call_args_list[1].args
+        assert "type IS NULL OR type = ANY(%s)" in count_sql
+        assert count_params == (sid, ["---"])
+
+    def test_unknown_type_key_short_circuits(self):
+        store, cursor = self._store()
+        cursor.fetchall.return_value = [("Person",)]
+
+        assert store.list_nodes("sid", type_key="org") == {"nodes": [], "total": 0}
+        assert cursor.execute.call_count == 1
diff --git a/tests/parser/remote/test_base.py b/tests/parser/remote/test_base.py
new file mode 100644
index 00000000..2f12f427
--- /dev/null
+++ b/tests/parser/remote/test_base.py
@@ -0,0 +1,133 @@
+"""Tests for the shared web-ingest path helpers in docsgpt/parser/remote/base.py."""
+
+import pytest
+
+from docsgpt.parser.remote.base import (
+    MAX_QUERY_SEGMENT_LENGTH,
+    dedupe_virtual_paths,
+    url_to_virtual_path,
+)
+from docsgpt.parser.schema.base import Document
+
+
+@pytest.mark.unit
+class TestUrlToVirtualPath:
+    @pytest.mark.parametrize(
+        "url, path",
+        [
+            # Paths without a query string are unchanged.
+            ("https://x.io/", "index.md"),
+            ("https://x.io", "index.md"),
+            ("https://x.io/guides/setup", "guides/setup.md"),
+            ("https://x.io/guides/setup/", "guides/setup.md"),
+            ("https://x.io/page.html", "page.md"),
+            ("https://x.io/readme.md", "readme.md"),
+            # The fragment names a spot on the same page.
+            ("https://x.io/p#install", "p.md"),
+            ("https://x.io/p?#install", "p.md"),
+        ],
+    )
+    def test_query_less_paths_are_unchanged(self, url, path):
+        assert url_to_virtual_path(url) == path
+
+    def test_distinct_queries_get_distinct_paths(self):
+        first = url_to_virtual_path("https://x.io/p?page=1")
+        second = url_to_virtual_path("https://x.io/p?page=2")
+
+        assert first == "p__page=1.md"
+        assert second == "p__page=2.md"
+        assert url_to_virtual_path("https://x.io/p") == "p.md"
+
+    def test_parameter_order_does_not_matter(self):
+        assert (
+            url_to_virtual_path("https://x.io/p?b=2&a=1")
+            == url_to_virtual_path("https://x.io/p?a=1&b=2")
+            == "p__a=1&b=2.md"
+        )
+
+    def test_query_on_the_root_and_on_page_extensions(self):
+        assert url_to_virtual_path("https://x.io/?page=2") == "index__page=2.md"
+        assert url_to_virtual_path("https://x.io/a.php?id=7#top") == "a__id=7.md"
+        assert url_to_virtual_path("https://x.io/doc.md?v=2") == "doc__v=2.md"
+
+    def test_query_is_sanitized_to_a_single_tree_segment(self):
+        path = url_to_virtual_path("https://x.io/p?q=a/b%20c&next=..%2Fetc&flag")
+
+        assert path == "p__flag&next=..-etc&q=a-b-c.md"
+        assert path.count("/") == 0
+        assert "?" not in path and "#" not in path and "%" not in path
+
+    def test_unicode_query_values_survive(self):
+        assert url_to_virtual_path("https://x.io/s?q=%D0%BA%D0%BE%D1%82") == "s__q=кот.md"
+
+    def test_long_queries_are_bounded_with_a_stable_hash(self):
+        long_a = "https://x.io/p?q=" + "a" * 500
+        long_b = "https://x.io/p?q=" + "a" * 499 + "b"
+
+        path_a = url_to_virtual_path(long_a)
+        path_b = url_to_virtual_path(long_b)
+
+        segment = path_a[len("p__"):-len(".md")]
+        assert len(segment) <= MAX_QUERY_SEGMENT_LENGTH
+        assert path_a != path_b
+        assert url_to_virtual_path(long_a) == path_a
+
+    def test_host_prefix_still_applies(self):
+        assert (
+            url_to_virtual_path("https://x.io/p?page=1", include_host=True)
+            == "x.io/p__page=1.md"
+        )
+
+
+def _doc(url, file_path=None):
+    return Document(
+        "text",
+        extra_info={"source": url, "file_path": file_path or url_to_virtual_path(url)},
+    )
+
+
+def _paths(docs):
+    return [d.extra_info["file_path"] for d in docs]
+
+
+@pytest.mark.unit
+class TestDedupeVirtualPaths:
+    def test_distinct_pages_are_left_alone(self):
+        docs = [_doc("https://x.io/"), _doc("https://x.io/a"), _doc("https://x.io/b")]
+
+        assert _paths(dedupe_virtual_paths(docs)) == ["index.md", "a.md", "b.md"]
+
+    def test_extension_collision_gets_a_numbered_suffix(self):
+        docs = [_doc("https://x.io/a.html"), _doc("https://x.io/a")]
+
+        assert _paths(dedupe_virtual_paths(docs)) == ["a-2.md", "a.md"]
+
+    def test_suffixes_do_not_depend_on_input_order(self):
+        urls = ["https://x.io/a", "https://x.io/a.htm", "https://x.io/a.html"]
+
+        forward = _paths(dedupe_virtual_paths([_doc(u) for u in urls]))
+        backward = _paths(dedupe_virtual_paths([_doc(u) for u in reversed(urls)]))
+
+        assert forward == ["a.md", "a-2.md", "a-3.md"]
+        assert backward == list(reversed(forward))
+
+    def test_suffix_skips_a_path_another_page_already_has(self):
+        docs = [
+            _doc("https://x.io/g/a-2"),
+            _doc("https://x.io/g/a"),
+            _doc("https://x.io/g/a.html"),
+        ]
+
+        assert _paths(dedupe_virtual_paths(docs)) == ["g/a-2.md", "g/a.md", "g/a-3.md"]
+
+    def test_the_same_page_reached_twice_keeps_one_path(self):
+        # A crawler that followed ``#section`` fetched the same page again.
+        docs = [_doc("https://x.io/a"), _doc("https://x.io/a#section")]
+
+        assert _paths(dedupe_virtual_paths(docs)) == ["a.md", "a.md"]
+
+    def test_documents_without_a_file_path_are_ignored(self):
+        doc = Document("text", extra_info={"source": "https://x.io/a"})
+
+        assert dedupe_virtual_paths([doc]) == [doc]
+        assert "file_path" not in doc.extra_info
diff --git a/tests/parser/remote/test_crawler_loader.py b/tests/parser/remote/test_crawler_loader.py
index 513cd7db..7af6c54c 100644
--- a/tests/parser/remote/test_crawler_loader.py
+++ b/tests/parser/remote/test_crawler_loader.py
@@ -183,3 +183,28 @@ class TestCrawlerLoaderGaps:
 
                 result = loader.load_data("https://example.com")
                 assert result[0].text == "test"
+
+
+@patch("docsgpt.parser.remote.crawler_loader.validate_url", side_effect=_mock_validate_url)
+@patch("docsgpt.parser.remote.crawler_loader.pinned_request")
+def test_colliding_pages_get_distinct_file_paths(mock_pinned_request, mock_validate_url):
+    responses = {
+        "http://example.com": DummyResponse(
+            "<html><body><a href='/a'>A</a><a href='/a.html'>A2</a>"
+            "<a href='/l?page=2'>L</a></body></html>"
+        ),
+        "http://example.com/a": DummyResponse("<html><body>a</body></html>"),
+        "http://example.com/a.html": DummyResponse("<html><body>a2</body></html>"),
+        "http://example.com/l?page=2": DummyResponse("<html><body>l</body></html>"),
+    }
+    mock_pinned_request.side_effect = lambda _m, url, timeout=30: responses[url]
+
+    result = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    paths = {doc.extra_info["source"]: doc.extra_info["file_path"] for doc in result}
+    assert paths == {
+        "http://example.com": "index.md",
+        "http://example.com/a": "a.md",
+        "http://example.com/a.html": "a-2.md",
+        "http://example.com/l?page=2": "l__page=2.md",
+    }
diff --git a/tests/parser/remote/test_crawler_markdown.py b/tests/parser/remote/test_crawler_markdown.py
index 567a8cbe..f8e54687 100644
--- a/tests/parser/remote/test_crawler_markdown.py
+++ b/tests/parser/remote/test_crawler_markdown.py
@@ -179,3 +179,28 @@ def test_load_data_returns_empty_on_ssrf_validation_failure(monkeypatch):
 
     assert result == []
 
+
+
+def test_colliding_pages_get_distinct_file_paths(monkeypatch, _patch_markdownify):
+    root_html = (
+        "<html><head><title>Home</title></head><body>"
+        "<a href='/a'>A</a><a href='/a.html'>A2</a><a href='/l?page=2'>L</a>"
+        "</body></html>"
+    )
+    responses = {
+        "http://example.com": DummyResponse(root_html),
+        "http://example.com/a": DummyResponse("<html><body>a</body></html>"),
+        "http://example.com/a.html": DummyResponse("<html><body>a2</body></html>"),
+        "http://example.com/l?page=2": DummyResponse("<html><body>l</body></html>"),
+    }
+    _patch_pinned_request(monkeypatch, lambda url: responses[url])
+
+    docs = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    paths = {doc.extra_info["source"]: doc.extra_info["file_path"] for doc in docs}
+    assert paths == {
+        "http://example.com": "index.md",
+        "http://example.com/a": "a.md",
+        "http://example.com/a.html": "a-2.md",
+        "http://example.com/l?page=2": "l__page=2.md",
+    }
diff --git a/tests/parser/remote/test_sitemap_loader.py b/tests/parser/remote/test_sitemap_loader.py
index 1b2699f1..88691233 100644
--- a/tests/parser/remote/test_sitemap_loader.py
+++ b/tests/parser/remote/test_sitemap_loader.py
@@ -246,7 +246,10 @@ class TestSitemapLoaderLoadData:
             assert len(docs) == 1
             assert isinstance(docs[0], Document)
             assert docs[0].text == "Page body"
-            assert docs[0].extra_info == {"source": "https://example.com/page1"}
+            assert docs[0].extra_info == {
+                "source": "https://example.com/page1",
+                "file_path": "page1.md",
+            }
 
     @patch("docsgpt.parser.remote.sitemap_loader.validate_url")
     def test_load_data_no_urls(self, mock_validate):
@@ -330,3 +333,21 @@ class TestSitemapLoaderLoadData:
         with patch.object(loader, "_extract_urls", return_value=urls):
             docs = loader.load_data("https://example.com/sitemap.xml")
             assert len(docs) == 5
+
+
+@pytest.mark.unit
+class TestSitemapLoaderDistinctPaths:
+    @patch("docsgpt.parser.remote.sitemap_loader.validate_url", side_effect=lambda url: url)
+    @patch("docsgpt.parser.remote.sitemap_loader.pinned_request")
+    def test_colliding_pages_get_distinct_file_paths(self, mock_pinned_request, mock_validate):
+        loader = SitemapLoader(limit=None)
+        response = MagicMock()
+        response.text = "Page body"
+        response.raise_for_status.return_value = None
+        mock_pinned_request.return_value = response
+        urls = ["https://x.io/p?page=2", "https://x.io/p", "https://x.io/p.htm"]
+
+        with patch.object(loader, "_extract_urls", return_value=urls):
+            docs = loader.load_data("https://x.io/sitemap.xml")
+
+        assert [d.extra_info["file_path"] for d in docs] == ["p__page=2.md", "p.md", "p-2.md"]
diff --git a/tests/parser/remote/test_web_loader.py b/tests/parser/remote/test_web_loader.py
index ee50024c..97c885c0 100644
--- a/tests/parser/remote/test_web_loader.py
+++ b/tests/parser/remote/test_web_loader.py
@@ -60,6 +60,20 @@ class TestWebLoaderHeaders:
 class TestWebLoaderLoadData:
     """Test WebLoader load_data method."""
 
+    @patch("docsgpt.parser.remote.web_loader.validate_url", side_effect=_mock_validate_url)
+    @patch("docsgpt.parser.remote.web_loader.pinned_request")
+    def test_same_host_urls_get_path_only_file_paths(self, mock_pinned_request, mock_validate, web_loader):
+        # The tree and the chunk path filter both key off file_path, so each
+        # page needs a stable, distinct one (not its title).
+        mock_pinned_request.side_effect = [
+            _fake_response("<html><head><title>Home</title></head><body>a</body></html>"),
+            _fake_response("<html><head><title>Setup</title></head><body>b</body></html>"),
+        ]
+
+        result = web_loader.load_data(["https://docs.x.io/", "https://docs.x.io/guides/setup.html"])
+
+        assert [d.extra_info["file_path"] for d in result] == ["index.md", "guides/setup.md"]
+
     @patch("docsgpt.parser.remote.web_loader.validate_url", side_effect=_mock_validate_url)
     @patch("docsgpt.parser.remote.web_loader.pinned_request")
     def test_load_data_single_url_string(self, mock_pinned_request, mock_validate, web_loader):
@@ -77,6 +91,7 @@ class TestWebLoaderLoadData:
             "source": "https://example.com",
             "title": "Test Page",
             "language": "en",
+            "file_path": "index.md",
         }
         mock_pinned_request.assert_called_once_with(
             "GET", "https://example.com", headers=headers, timeout=30
@@ -97,8 +112,9 @@ class TestWebLoaderLoadData:
         assert all(isinstance(doc, Document) for doc in result)
         assert result[0].text == "Content from site 1"
         assert result[1].text == "Content from site 2"
-        assert result[0].extra_info == {"source": "https://site1.com"}
-        assert result[1].extra_info == {"source": "https://site2.com"}
+        # Two hosts would both map to index.md, so the host prefixes the path.
+        assert result[0].extra_info == {"source": "https://site1.com", "file_path": "site1.com/index.md"}
+        assert result[1].extra_info == {"source": "https://site2.com", "file_path": "site2.com/index.md"}
 
         assert mock_pinned_request.call_count == 2
         mock_pinned_request.assert_any_call(
@@ -146,7 +162,7 @@ class TestWebLoaderLoadData:
 
         assert len(result) == 1
         assert result[0].text == "Bare body"
-        assert result[0].extra_info == {"source": "https://example.com"}
+        assert result[0].extra_info == {"source": "https://example.com", "file_path": "index.md"}
 
     @patch("docsgpt.parser.remote.web_loader.validate_url", side_effect=_mock_validate_url)
     @patch("docsgpt.parser.remote.web_loader.pinned_request")
@@ -203,7 +219,7 @@ class TestWebLoaderErrorHandling:
 
         assert len(result) == 1
         assert result[0].text == "Success content"
-        assert result[0].extra_info == {"source": "https://good-url.com"}
+        assert result[0].extra_info == {"source": "https://good-url.com", "file_path": "good-url.com/index.md"}
 
         mock_logging.error.assert_called_once()
         error_call = mock_logging.error.call_args
@@ -276,7 +292,7 @@ class TestWebLoaderEdgeCases:
 
         assert len(result) == 1
         assert result[0].text == ""
-        assert result[0].extra_info == {"source": "https://empty-page.com"}
+        assert result[0].extra_info == {"source": "https://empty-page.com", "file_path": "index.md"}
 
     def test_url_scheme_detection(self):
         """Test URL scheme detection logic."""
@@ -314,3 +330,24 @@ class TestWebLoaderIntegration:
         assert "Test web page content" in result[0].page_content
         assert result[0].metadata["source"] == "https://example.com"
         assert result[0].metadata["title"] == "Test Page"
+
+
+@pytest.mark.unit
+class TestWebLoaderDistinctPaths:
+    @patch("docsgpt.parser.remote.web_loader.validate_url", side_effect=_mock_validate_url)
+    @patch("docsgpt.parser.remote.web_loader.pinned_request")
+    def test_colliding_pages_get_distinct_file_paths(self, mock_pinned_request, mock_validate, web_loader):
+        mock_pinned_request.side_effect = lambda *a, **k: _fake_response("<html><body>x</body></html>")
+
+        result = web_loader.load_data(
+            [
+                "https://x.io/list?page=1",
+                "https://x.io/list?page=2",
+                "https://x.io/a.html",
+                "https://x.io/a",
+            ]
+        )
+
+        assert [d.extra_info["file_path"] for d in result] == [
+            "list__page=1.md", "list__page=2.md", "a-2.md", "a.md"
+        ]
diff --git a/tests/vectorstore/test_base.py b/tests/vectorstore/test_base.py
index 670880fe..37bf9cf8 100644
--- a/tests/vectorstore/test_base.py
+++ b/tests/vectorstore/test_base.py
@@ -660,3 +660,55 @@ class TestGetEmbeddingsResolver:
 
         assert result is sentinel
         mock_resolver.assert_called_once_with("a-name", "a-key")
+
+
+class _RecordingStore(ConcreteVectorStore):
+    """Store whose add/delete calls are recorded, for the update fallback."""
+
+    def __init__(self, delete_result=True):
+        super().__init__()
+        self.calls = []
+        self._delete_result = delete_result
+
+    def add_chunk(self, text, metadata=None, *args, **kwargs):
+        self.calls.append(("add", text, metadata))
+        return "new-id"
+
+    def delete_chunk(self, chunk_id, *args, **kwargs):
+        self.calls.append(("delete", chunk_id))
+        return self._delete_result
+
+
+@pytest.mark.unit
+class TestBaseUpdateChunkFallback:
+    def test_adds_then_deletes_and_returns_the_new_id(self):
+        store = _RecordingStore()
+
+        new_id = store.update_chunk("old-id", "new text", {"k": "v"})
+
+        assert new_id == "new-id"
+        assert store.calls == [("add", "new text", {"k": "v"}), ("delete", "old-id")]
+
+    def test_failed_delete_is_logged_not_raised(self, caplog):
+        store = _RecordingStore(delete_result=False)
+
+        with caplog.at_level("WARNING"):
+            new_id = store.update_chunk("old-id", "new text", {})
+
+        assert new_id == "new-id"
+        assert "old-id" in caplog.text
+
+    def test_failed_add_skips_the_delete(self):
+        store = _RecordingStore()
+        store.add_chunk = Mock(side_effect=RuntimeError("embed down"))
+
+        with pytest.raises(RuntimeError):
+            store.update_chunk("old-id", "new text", {})
+
+        assert ("delete", "old-id") not in store.calls
+
+    def test_milvus_keeps_the_default(self):
+        """Milvus has no in-place update here; it re-adds under a new id."""
+        from docsgpt.vectorstore.milvus import MilvusStore
+
+        assert MilvusStore.update_chunk is BaseVectorStore.update_chunk
diff --git a/tests/vectorstore/test_faiss.py b/tests/vectorstore/test_faiss.py
index f0245031..1f93ddd3 100644
--- a/tests/vectorstore/test_faiss.py
+++ b/tests/vectorstore/test_faiss.py
@@ -287,3 +287,88 @@ class TestBuildFromDocumentsBatching:
         store._build_from_documents(self._docs(3))
         assert len(store.documents) == 3
         assert all(len(k) == 36 for k in store.documents), "uuid4 ids by default"
+
+
+def _assert_rows_match_documents(store):
+    """Every FAISS row must hold the embedding of the chunk it maps to."""
+    import numpy as np
+
+    embeddings = _FakeEmbeddings()
+    assert store.index.ntotal == len(store.documents) == len(store.index_to_docstore_id)
+    assert sorted(store.index_to_docstore_id) == list(range(store.index.ntotal))
+    for row, doc_id in store.index_to_docstore_id.items():
+        expected = embeddings.embed_documents([store.documents[doc_id]["page_content"]])[0]
+        assert np.allclose(store.index.reconstruct(row), expected), (row, doc_id)
+
+
+@pytest.mark.unit
+class TestFaissUpdateChunk:
+    def test_keeps_id_and_position(self, populated):
+        before = [c["doc_id"] for c in populated.get_chunks()]
+        target = before[1]
+
+        returned = populated.update_chunk(target, "Redis caches things.", {"source": "cache.txt"})
+
+        assert returned == target
+        chunks = populated.get_chunks()
+        assert [c["doc_id"] for c in chunks] == before
+        assert chunks[1]["text"] == "Redis caches things."
+        assert chunks[1]["metadata"] == {"source": "cache.txt"}
+        assert populated.documents[target] == {
+            "page_content": "Redis caches things.",
+            "metadata": {"source": "cache.txt"},
+        }
+
+    def test_replaces_the_vector_and_keeps_rows_consistent(self, populated):
+        target = populated.get_chunks()[0]["doc_id"]
+
+        populated.update_chunk(target, "Redis caches things.", {})
+
+        _assert_rows_match_documents(populated)
+        # The old "Paris" vector is gone and the neutral query finds the edit.
+        assert "Paris" not in str(populated.search("Paris", k=1)[0])
+        assert "Redis" in str(populated.search("something neutral", k=1)[0])
+
+    def test_saves_once(self, populated):
+        target = populated.get_chunks()[0]["doc_id"]
+        with patch.object(populated, "_save_to_storage") as save:
+            populated.update_chunk(target, "Redis caches things.", {})
+        save.assert_called_once()
+
+    def test_embedding_failure_leaves_the_chunk_untouched(self, populated):
+        chunks_before = populated.get_chunks()
+        mapping_before = dict(populated.index_to_docstore_id)
+        target = chunks_before[1]["doc_id"]
+
+        with patch.object(
+            populated.embeddings, "embed_documents", side_effect=RuntimeError("embed down")
+        ), patch.object(populated, "_save_to_storage") as save:
+            with pytest.raises(RuntimeError):
+                populated.update_chunk(target, "Redis caches things.", {})
+
+        assert populated.get_chunks() == chunks_before
+        assert populated.index_to_docstore_id == mapping_before
+        assert populated.index.ntotal == 3
+        save.assert_not_called()
+
+    def test_unknown_id_raises(self, populated):
+        with pytest.raises(KeyError):
+            populated.update_chunk("nope", "text", {})
+        assert populated.index.ntotal == 3
+
+    @pytest.mark.parametrize("sidecar", ["json", "pickle"])
+    def test_survives_save_and_reload(self, populated, make_store, tmp_path, sidecar):
+        before = [c["doc_id"] for c in populated.get_chunks()]
+        target = before[1]
+        populated.update_chunk(target, "Redis caches things.", {"source": "cache.txt"})
+
+        if sidecar == "pickle":
+            (tmp_path / "indexes" / "src" / "index.json").unlink()
+        reloaded = make_store()
+
+        chunks = reloaded.get_chunks()
+        assert [c["doc_id"] for c in chunks] == before
+        assert chunks[1]["text"] == "Redis caches things."
+        assert chunks[1]["metadata"] == {"source": "cache.txt"}
+        _assert_rows_match_documents(reloaded)
+        assert "Redis" in str(reloaded.search("something neutral", k=1)[0])
diff --git a/tests/vectorstore/test_mongodb.py b/tests/vectorstore/test_mongodb.py
index 4f868812..bfb9bd94 100644
--- a/tests/vectorstore/test_mongodb.py
+++ b/tests/vectorstore/test_mongodb.py
@@ -324,3 +324,125 @@ class TestMongoDBSearchWithScores:
         pipeline = mock_collection.aggregate.call_args[0][0]
         assert any("$addFields" in stage for stage in pipeline)
         assert not any("$match" in stage for stage in pipeline)
+
+
+def _fake_bson():
+    """``bson.objectid`` stand-in: pymongo is an optional extra."""
+    objectid = MagicMock()
+    objectid.ObjectId = lambda value: ("oid", value)
+    return {"bson": MagicMock(objectid=objectid), "bson.objectid": objectid}
+
+
+@pytest.mark.unit
+class TestMongoDBVectorStoreUpdateChunk:
+    def _existing(self, **extra):
+        return {
+            "_id": ("oid", "abc"),
+            "text": "old",
+            "embedding": [0.0],
+            "source_id": "src1",
+            **extra,
+        }
+
+    def test_updates_in_place_with_set(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4, 0.5]]
+        mock_collection.find_one.return_value = self._existing(title="T")
+        mock_collection.update_one.return_value = Mock(matched_count=1)
+
+        with patch.dict("sys.modules", _fake_bson()):
+            returned = store.update_chunk("abc", "new text", {"title": "T2", "extra": 1})
+
+        assert returned == "abc"
+        query, update = mock_collection.update_one.call_args[0]
+        assert query == {"_id": ("oid", "abc"), "source_id": "src1"}
+        assert update == {
+            "$set": {
+                "text": "new text",
+                "embedding": [0.4, 0.5],
+                "source_id": "src1",
+                "title": "T2",
+                "extra": 1,
+            }
+        }
+        mock_collection.insert_one.assert_not_called()
+        mock_collection.delete_one.assert_not_called()
+
+    def test_unsets_keys_missing_from_the_new_metadata(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_collection.find_one.return_value = self._existing(title="T", stale="x")
+        mock_collection.update_one.return_value = Mock(matched_count=1)
+
+        with patch.dict("sys.modules", _fake_bson()):
+            store.update_chunk("abc", "new text", {"title": "T"})
+
+        _, update = mock_collection.update_one.call_args[0]
+        assert update["$unset"] == {"stale": ""}
+        assert "source_id" not in update["$unset"]
+
+    def test_reserved_keys_in_metadata_cannot_clobber_the_record(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_collection.find_one.return_value = self._existing()
+        mock_collection.update_one.return_value = Mock(matched_count=1)
+
+        with patch.dict("sys.modules", _fake_bson()):
+            store.update_chunk(
+                "abc", "new text",
+                {"_id": "x", "text": "x", "embedding": [9], "source_id": "other"},
+            )
+
+        _, update = mock_collection.update_one.call_args[0]
+        assert update["$set"] == {
+            "text": "new text", "embedding": [0.4], "source_id": "src1"
+        }
+
+    def test_embedding_failure_writes_nothing(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_emb.embed_documents.side_effect = RuntimeError("embed down")
+        mock_collection.find_one.return_value = self._existing()
+
+        with patch.dict("sys.modules", _fake_bson()):
+            with pytest.raises(RuntimeError):
+                store.update_chunk("abc", "new text", {})
+
+        mock_collection.update_one.assert_not_called()
+
+    @pytest.mark.parametrize("key", ["a.b", "$where", "", "meta.$x"])
+    def test_keys_mongo_cannot_store_are_rejected_before_any_write(self, key):
+        from docsgpt.vectorstore.base import InvalidChunkMetadataError
+
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_collection.find_one.return_value = self._existing()
+
+        with patch.dict("sys.modules", _fake_bson()):
+            with pytest.raises(InvalidChunkMetadataError) as excinfo:
+                store.update_chunk("abc", "new text", {"title": "T", key: 1})
+
+        assert isinstance(excinfo.value, ValueError)
+        mock_emb.embed_documents.assert_not_called()
+        mock_collection.update_one.assert_not_called()
+
+    def test_dollar_inside_a_key_is_allowed(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_collection.find_one.return_value = self._existing()
+        mock_collection.update_one.return_value = Mock(matched_count=1)
+
+        with patch.dict("sys.modules", _fake_bson()):
+            store.update_chunk("abc", "new text", {"price$": 1})
+
+        _, update = mock_collection.update_one.call_args[0]
+        assert update["$set"]["price$"] == 1
+
+    def test_unknown_id_raises(self):
+        store, mock_collection, mock_emb = _make_mongodb_store(source_id="src1")
+        mock_collection.find_one.return_value = None
+
+        with patch.dict("sys.modules", _fake_bson()):
+            with pytest.raises(KeyError):
+                store.update_chunk("abc", "new text", {})
+
+        mock_emb.embed_documents.assert_not_called()
+        mock_collection.update_one.assert_not_called()
diff --git a/tests/vectorstore/test_pgvector.py b/tests/vectorstore/test_pgvector.py
index bd1475b8..c3680621 100644
--- a/tests/vectorstore/test_pgvector.py
+++ b/tests/vectorstore/test_pgvector.py
@@ -486,3 +486,89 @@ class TestPGVectorPrecomputedQueryVector:
         store.search_with_scores("query", k=2, query_vector=None)
 
         mock_emb.embed_query.assert_called_once_with("query")
+
+
+@pytest.mark.unit
+class TestPGVectorStoreUpdateChunk:
+    def test_updates_the_row_in_place(self):
+        store, mock_conn, mock_cursor, mock_emb = _make_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4, 0.5]]
+        mock_cursor.rowcount = 1
+
+        with patch("docsgpt.vectorstore.pgvector.Jsonb", side_effect=lambda v: ("jsonb", v)):
+            returned = store.update_chunk("42", "new text", {"key": "val"})
+
+        assert returned == "42"
+        sql, params = mock_cursor.execute.call_args[0]
+        assert sql.strip().upper().startswith("UPDATE")
+        assert "WHERE id = %s AND source_id = %s" in sql
+        assert "INSERT" not in sql.upper() and "DELETE" not in sql.upper()
+        assert params == (
+            "new text",
+            [0.4, 0.5],
+            ("jsonb", {"key": "val", "source_id": "src1"}),
+            42,
+            "src1",
+        )
+        mock_emb.embed_documents.assert_called_once_with(["new text"])
+        mock_conn.commit.assert_called_once()
+
+    def test_does_not_mutate_the_callers_metadata(self):
+        store, _, mock_cursor, mock_emb = _make_store(source_id="src1")
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_cursor.rowcount = 1
+        metadata = {"key": "val"}
+
+        store.update_chunk("42", "new text", metadata)
+
+        assert metadata == {"key": "val"}
+
+    def test_embedding_failure_writes_nothing(self):
+        store, mock_conn, mock_cursor, mock_emb = _make_store()
+        mock_emb.embed_documents.side_effect = RuntimeError("embed down")
+
+        with pytest.raises(RuntimeError):
+            store.update_chunk("42", "new text", {})
+
+        mock_cursor.execute.assert_not_called()
+        mock_conn.commit.assert_not_called()
+
+    def test_empty_embedding_raises_before_writing(self):
+        store, _, mock_cursor, mock_emb = _make_store()
+        mock_emb.embed_documents.return_value = []
+
+        with pytest.raises(ValueError, match="Could not generate embedding"):
+            store.update_chunk("42", "new text", {})
+        mock_cursor.execute.assert_not_called()
+
+    def test_missing_row_raises_and_rolls_back(self):
+        store, mock_conn, mock_cursor, mock_emb = _make_store()
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_cursor.rowcount = 0
+
+        with pytest.raises(KeyError):
+            store.update_chunk("999", "new text", {})
+
+        mock_conn.commit.assert_not_called()
+        mock_conn.rollback.assert_called_once()
+
+    def test_db_error_rolls_back_and_raises(self):
+        store, mock_conn, mock_cursor, mock_emb = _make_store()
+        mock_emb.embed_documents.return_value = [[0.4]]
+        mock_cursor.execute.side_effect = RuntimeError("db down")
+
+        with pytest.raises(RuntimeError):
+            store.update_chunk("42", "new text", {})
+        mock_conn.rollback.assert_called_once()
+
+
+@pytest.mark.unit
+def test_get_chunks_orders_by_id():
+    """An UPDATE writes a new tuple, so an unordered scan could move the row."""
+    store, _, mock_cursor, _ = _make_store()
+    mock_cursor.fetchall.return_value = []
+
+    store.get_chunks()
+
+    sql = " ".join(mock_cursor.execute.call_args[0][0].split())
+    assert sql.endswith("WHERE source_id = %s ORDER BY id;")
diff --git a/tests/vectorstore/test_pgvector_live_schema.py b/tests/vectorstore/test_pgvector_live_schema.py
index b9d59c85..45f56e87 100644
--- a/tests/vectorstore/test_pgvector_live_schema.py
+++ b/tests/vectorstore/test_pgvector_live_schema.py
@@ -216,6 +216,39 @@ class TestStoreRoundTrip:
         assert store._connection is None
 
 
+class TestUpdateChunkInPlace:
+    def test_update_keeps_id_and_list_position(self, live_dsn, stub_embeddings):
+        ensure_vector_schema()
+        store = _store(live_dsn)
+        ids = store.add_texts(
+            ["first", "second", "third"],
+            [{"source": "a.txt"}, {"source": "b.txt"}, {"source": "c.txt"}],
+        )
+
+        # Rewrite the first row: an UPDATE writes a new tuple at the heap's
+        # end, which an unordered scan would return last.
+        assert store.update_chunk(ids[0], "first edited", {"source": "a2.txt"}) == ids[0]
+
+        chunks = store.get_chunks()
+        assert [c["doc_id"] for c in chunks] == ids
+        assert chunks[0]["text"] == "first edited"
+        assert chunks[0]["metadata"] == {"source": "a2.txt", "source_id": "live-source"}
+        store.close()
+
+    def test_update_of_another_sources_chunk_is_refused(self, live_dsn, stub_embeddings):
+        ensure_vector_schema()
+        owner = _store(live_dsn, source_id="owner")
+        (chunk_id,) = owner.add_texts(["mine"], [{}])
+
+        intruder = _store(live_dsn, source_id="intruder")
+        with pytest.raises(KeyError):
+            intruder.update_chunk(chunk_id, "hijack", {})
+        intruder.close()
+
+        assert owner.get_chunks()[0]["text"] == "mine"
+        owner.close()
+
+
 class TestWritePathSafetyNet:
     """A process that never ran the boot hook must still be able to ingest.
 
diff --git a/tests/vectorstore/test_qdrant.py b/tests/vectorstore/test_qdrant.py
index 753ab406..55a9a104 100644
--- a/tests/vectorstore/test_qdrant.py
+++ b/tests/vectorstore/test_qdrant.py
@@ -181,3 +181,80 @@ class TestQdrantClientKwargs:
         assert kwargs["url"] == "http://qdrant:6333"
         assert kwargs["api_key"] == "secret"
         assert "location" not in kwargs
+
+
+@pytest.mark.unit
+class TestQdrantUpdateChunk:
+    def test_keeps_id_and_position(self, populated):
+        before = populated.get_chunks()
+        target = before[1]["doc_id"]
+
+        returned = populated.update_chunk(target, "Redis caches things.", {"source": "cache.txt"})
+
+        assert returned == target
+        after = populated.get_chunks()
+        assert [c["doc_id"] for c in after] == [c["doc_id"] for c in before]
+        assert after[1]["text"] == "Redis caches things."
+        assert after[1]["metadata"] == {"source": "cache.txt", "source_id": "src-A"}
+
+    def test_replaces_the_vector(self, populated):
+        target = next(
+            c["doc_id"] for c in populated.get_chunks() if c["metadata"]["source"] == "geo.txt"
+        )
+
+        populated.update_chunk(target, "Celery workers are busy.", {"source": "geo.txt"})
+
+        hits = populated.search_with_scores("celery", k=3)
+        assert sorted(doc.page_content for doc, score in hits if score > 0.99) == [
+            "Celery runs background tasks.",
+            "Celery workers are busy.",
+        ]
+        assert not any("Paris" in doc.page_content for doc, _ in hits)
+
+    def test_payload_shape_matches_add_texts(self, populated):
+        target = populated.get_chunks()[0]["doc_id"]
+
+        populated.update_chunk(target, "Redis caches things.", {"source": "cache.txt"})
+
+        record = populated._client.retrieve(
+            populated._collection, ids=[target], with_payload=True
+        )[0]
+        assert record.payload == {
+            "page_content": "Redis caches things.",
+            "metadata": {"source": "cache.txt", "source_id": "src-A"},
+        }
+
+    def test_embedding_failure_leaves_the_point_untouched(self, populated):
+        before = populated.get_chunks()
+        target = before[0]["doc_id"]
+
+        with patch.object(
+            populated._embeddings, "embed_documents", side_effect=RuntimeError("embed down")
+        ):
+            with pytest.raises(RuntimeError):
+                populated.update_chunk(target, "Redis caches things.", {})
+
+        assert populated.get_chunks() == before
+
+    def test_unknown_id_raises(self, populated):
+        import uuid
+
+        with pytest.raises(KeyError):
+            populated.update_chunk(str(uuid.uuid4()), "text", {})
+        assert len(populated.get_chunks()) == 3
+
+    def test_other_sources_point_is_refused(self, populated):
+        from docsgpt.vectorstore.qdrant import QdrantStore
+
+        with patch(
+            "docsgpt.vectorstore.base.BaseVectorStore._get_embeddings",
+            return_value=_FakeEmbeddings(),
+        ), patch("docsgpt.vectorstore.qdrant.settings") as mock_settings:
+            _settings(mock_settings)
+            other = QdrantStore(source_id="src-B", embeddings_key="k")
+        other._client = populated._client
+        target = populated.get_chunks()[0]["doc_id"]
+
+        with pytest.raises(KeyError):
+            other.update_chunk(target, "hijack", {})
+        assert populated.get_chunks()[0]["text"] != "hijack"

From f4331cd3a36addc9727ea509752249b64b1fcc4c Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Mon, 28 Sep 2026 18:40:49 +0400
Subject: [PATCH 6/7] rabbit fixes

---
 docsgpt/api/user/sources/routes.py            |  5 +-
 docsgpt/core/url_validation.py                | 15 ++++--
 docsgpt/parser/remote/base.py                 | 45 +++++++++++++++---
 docsgpt/parser/remote/crawler_loader.py       | 29 ++++++++----
 docsgpt/parser/remote/crawler_markdown.py     | 22 ++++++---
 .../storage/db/repositories/schedule_runs.py  |  4 +-
 docsgpt/vectorstore/base.py                   | 24 ++++++++--
 frontend/eslint/card-surfaces.js              |  9 ++--
 frontend/eslint/design-rules.js               |  8 ++--
 frontend/src/components/Chunks.test.tsx       | 20 +++++---
 frontend/src/components/Chunks.tsx            | 41 ++++++----------
 frontend/src/design/cardSurfaces.lint.test.ts | 18 +++++++
 frontend/src/design/designRules.lint.test.ts  | 13 +++++
 frontend/src/locale/de.json                   |  1 -
 frontend/src/locale/en.json                   |  1 -
 frontend/src/locale/es.json                   |  1 -
 frontend/src/locale/jp.json                   |  1 -
 frontend/src/locale/ru.json                   |  1 -
 frontend/src/locale/zh-TW.json                |  1 -
 frontend/src/locale/zh.json                   |  1 -
 frontend/src/settings/Prompts.test.tsx        |  2 +
 tests/api/user/sources/test_chunks.py         | 37 +++++++++++++++
 tests/api/user/sources/test_graph_view.py     | 21 +++++++++
 tests/core/test_url_validation.py             | 19 ++++++++
 tests/parser/remote/test_base.py              | 27 +++++++++++
 tests/parser/remote/test_crawler_loader.py    | 40 ++++++++++++++++
 tests/parser/remote/test_crawler_markdown.py  | 46 ++++++++++++++++++
 tests/parser/remote/test_sitemap_loader.py    | 24 ++++++++++
 tests/parser/remote/test_web_loader.py        | 13 +++++
 .../db/repositories/test_schedule_runs.py     | 21 +++++++++
 tests/vectorstore/test_base.py                | 47 ++++++++++++++++---
 31 files changed, 470 insertions(+), 87 deletions(-)

diff --git a/docsgpt/api/user/sources/routes.py b/docsgpt/api/user/sources/routes.py
index 0930d689..9043e566 100644
--- a/docsgpt/api/user/sources/routes.py
+++ b/docsgpt/api/user/sources/routes.py
@@ -46,6 +46,9 @@ from docsgpt.vectorstore.vector_creator import VectorCreator
 
 WIKI_INDEX_PATH = "/index.md"
 
+# Longest graph-node search term forwarded to the store; longer input is truncated.
+_GRAPH_SEARCH_MAX_LEN = 200
+
 
 sources_ns = Namespace(
     "sources", description="Source document management operations", path="/api"
@@ -1442,7 +1445,7 @@ class SourceGraphNodes(Resource):
                 GRAPH_NODE_LIST_MAX_LIMIT,
             ),
         )
-        query = (request.args.get("q") or "").strip() or None
+        query = (request.args.get("q") or "").strip()[:_GRAPH_SEARCH_MAX_LEN] or None
         type_key = request.args.get("type")
         try:
             with db_readonly() as conn:
diff --git a/docsgpt/core/url_validation.py b/docsgpt/core/url_validation.py
index eaa4cf56..974bdb6d 100644
--- a/docsgpt/core/url_validation.py
+++ b/docsgpt/core/url_validation.py
@@ -112,17 +112,22 @@ def validate_url(url: str, allow_localhost: bool = False) -> str:
     """
     if not url or not isinstance(url, str):
         raise SSRFError("No URL was provided.")
-    # Ensure URL has a scheme
-    if not urlparse(url).scheme:
-        url = "http://" + url
+    # ``urlparse`` and ``.hostname`` raise ValueError on malformed input such
+    # as an unclosed IPv6 bracket (``http://[bad``); callers only catch SSRFError.
+    try:
+        # Ensure URL has a scheme
+        if not urlparse(url).scheme:
+            url = "http://" + url
 
-    parsed = urlparse(url)
+        parsed = urlparse(url)
+        hostname = parsed.hostname
+    except ValueError as e:
+        raise SSRFError(f"Invalid URL: {e}") from e
 
     # Check scheme
     if parsed.scheme not in ALLOWED_SCHEMES:
         raise SSRFError(f"URL scheme '{parsed.scheme}' is not allowed. Only HTTP(S) is permitted.")
 
-    hostname = parsed.hostname
     if not hostname:
         raise SSRFError("URL must have a valid hostname.")
 
diff --git a/docsgpt/parser/remote/base.py b/docsgpt/parser/remote/base.py
index 2cbfaf37..3f2a8e7e 100644
--- a/docsgpt/parser/remote/base.py
+++ b/docsgpt/parser/remote/base.py
@@ -4,7 +4,7 @@ import os
 import re
 from abc import abstractmethod
 from typing import Any, Dict, List
-from urllib.parse import parse_qsl, urldefrag, urlencode, urlparse
+from urllib.parse import parse_qsl, urlencode, urlparse, urlsplit, urlunsplit
 
 from docsgpt.parser.schema.base import Document
 from docsgpt.vectorstore.document_class import Document as VectorDocument
@@ -99,13 +99,44 @@ def url_to_virtual_path(url: str, include_host: bool = False) -> str:
 def spans_multiple_hosts(urls: List[str]) -> bool:
     """Return whether ``urls`` point at more than one host.
 
+    A URL ``urlparse`` rejects (an unclosed IPv6 bracket, say) is left out:
+    it fails validation and is never fetched, so it names no host here.
+
     Args:
         urls: Page URLs about to be ingested together.
 
     Returns:
         True when paths alone could collide and need a host prefix.
     """
-    return len({urlparse(u).netloc for u in urls}) > 1
+    hosts = set()
+    for url in urls:
+        try:
+            hosts.add(urlparse(url).netloc)
+        except ValueError:
+            continue
+    return len(hosts) > 1
+
+
+def normalize_page_url(url: str) -> str:
+    """Return the identity of the page ``url`` names, for deduplication.
+
+    The fragment is dropped (it names a spot on the same page) and the query
+    parameters are sorted, as ``_query_segment`` sorts them, so
+    ``/p?a=1&b=2`` and ``/p?b=2&a=1#top`` are one page. The result is a key
+    only; fetch the URL as it was written.
+
+    Args:
+        url: Page URL.
+
+    Returns:
+        The normalized URL.
+
+    Raises:
+        ValueError: If ``urlsplit`` cannot parse ``url``.
+    """
+    parts = urlsplit(url)
+    query = urlencode(sorted(parse_qsl(parts.query, keep_blank_values=True)))
+    return urlunsplit(parts._replace(query=query, fragment=""))
 
 
 def dedupe_virtual_paths(documents: List[Document]) -> List[Document]:
@@ -114,11 +145,13 @@ def dedupe_virtual_paths(documents: List[Document]) -> List[Document]:
     ``url_to_virtual_path`` folds some different URLs onto one path (``/a`` and
     ``/a.html`` are both ``a.md``), and the worker would then merge those pages
     into one tree entry. Within a path, the pages are ordered by URL (fragment
-    dropped): the first keeps the path and each later one gets ``-2``, ``-3``
-    and so on before ``.md``, skipping any path another page already has.
+    dropped, query parameters sorted; see ``normalize_page_url``): the first
+    keeps the path and each later one gets ``-2``, ``-3`` and so on before
+    ``.md``, skipping any path another page already has.
     Ordering by URL rather than by fetch order keeps the names stable across
     re-syncs of the same pages. Documents for the same URL (one page reached
-    via two fragments) are one page and keep one path.
+    via two fragments, or with its query parameters in another order) are one
+    page and keep one path.
 
     Args:
         documents: Loaded documents; each ``extra_info`` carries ``source``
@@ -133,7 +166,7 @@ def dedupe_virtual_paths(documents: List[Document]) -> List[Document]:
         path = info.get("file_path")
         if not path:
             continue
-        page = urldefrag(str(info.get("source") or path))[0]
+        page = normalize_page_url(str(info.get("source") or path))
         pages_by_path.setdefault(path, {}).setdefault(page, []).append(doc)
 
     taken = set(pages_by_path)
diff --git a/docsgpt/parser/remote/crawler_loader.py b/docsgpt/parser/remote/crawler_loader.py
index e6d2b8d5..e1e68858 100644
--- a/docsgpt/parser/remote/crawler_loader.py
+++ b/docsgpt/parser/remote/crawler_loader.py
@@ -2,7 +2,7 @@ import logging
 from bs4 import BeautifulSoup
 from urllib.parse import urljoin, urlparse
 
-from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, url_to_virtual_path
+from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, normalize_page_url, url_to_virtual_path
 from docsgpt.parser.schema.base import Document
 from docsgpt.core.url_validation import validate_url, SSRFError
 from docsgpt.security.safe_url import pinned_request
@@ -24,6 +24,8 @@ class CrawlerLoader(BaseRemote):
             logging.error(f"URL validation failed: {e}")
             return []
 
+        # Keyed by normalize_page_url, so fragment and query-order variants of
+        # one page are fetched once.
         visited_urls = set()
         base_url = urlparse(url).scheme + "://" + urlparse(url).hostname
         urls_to_visit = [url]
@@ -31,7 +33,10 @@ class CrawlerLoader(BaseRemote):
 
         while urls_to_visit:
             current_url = urls_to_visit.pop(0)
-            visited_urls.add(current_url)
+            page_key = normalize_page_url(current_url)
+            if page_key in visited_urls:
+                continue
+            visited_urls.add(page_key)
 
             try:
                 response = pinned_request("GET", current_url, timeout=30)
@@ -57,15 +62,21 @@ class CrawlerLoader(BaseRemote):
                 logging.error(f"Error processing URL {current_url}: {e}", exc_info=True)
                 continue
 
-            # Parse the HTML content to extract all links
-            all_links = [
-                urljoin(current_url, a['href'])
-                for a in soup.find_all('a', href=True)
-                if base_url in urljoin(current_url, a['href'])
-            ]
+            # Parse the HTML content to extract all links. A malformed href
+            # (``http://[bad``) makes urljoin or the key parse raise; skip it
+            # rather than abort the crawl.
+            all_links = []
+            for a in soup.find_all('a', href=True):
+                try:
+                    link = urljoin(current_url, a['href'])
+                    link_key = normalize_page_url(link)
+                except ValueError:
+                    continue
+                if base_url in link and link_key not in visited_urls:
+                    all_links.append(link)
 
             # Add new links to the list of URLs to visit if they haven't been visited yet
-            urls_to_visit.extend([link for link in all_links if link not in visited_urls])
+            urls_to_visit.extend(all_links)
             urls_to_visit = list(set(urls_to_visit))
 
             # Stop crawling if the limit of pages to scrape is reached
diff --git a/docsgpt/parser/remote/crawler_markdown.py b/docsgpt/parser/remote/crawler_markdown.py
index db8693cc..5812391e 100644
--- a/docsgpt/parser/remote/crawler_markdown.py
+++ b/docsgpt/parser/remote/crawler_markdown.py
@@ -1,6 +1,6 @@
 from urllib.parse import urlparse, urljoin
 from bs4 import BeautifulSoup
-from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, url_to_virtual_path
+from docsgpt.parser.remote.base import BaseRemote, dedupe_virtual_paths, normalize_page_url, url_to_virtual_path
 from docsgpt.core.url_validation import validate_url, SSRFError
 from docsgpt.security.safe_url import UnsafeUserUrlError, pinned_request
 import re
@@ -37,7 +37,8 @@ class CrawlerLoader(BaseRemote):
             print(f"URL validation failed: {e}")
             return []
 
-        # Keep track of visited URLs to avoid revisiting the same page
+        # Keep track of visited pages to avoid revisiting the same page. Keyed
+        # by normalize_page_url, so fragment and query-order variants are one.
         visited_urls = set()
 
         # Determine the base domain for link filtering using tldextract
@@ -49,9 +50,10 @@ class CrawlerLoader(BaseRemote):
             current_url = urls_to_visit.pop()
 
             # Skip if already visited
-            if current_url in visited_urls:
+            page_key = normalize_page_url(current_url)
+            if page_key in visited_urls:
                 continue
-            visited_urls.add(current_url)
+            visited_urls.add(page_key)
 
             # Fetch the page content
             html_content = self._fetch_page(current_url)
@@ -84,7 +86,9 @@ class CrawlerLoader(BaseRemote):
             filtered_links = self._filter_links(new_links, base_domain)
 
             # Add any new, not-yet-visited links to the queue
-            urls_to_visit.update(link for link in filtered_links if link not in visited_urls)
+            urls_to_visit.update(
+                link for link in filtered_links if normalize_page_url(link) not in visited_urls
+            )
 
             # If we've reached the limit, stop crawling
             if self.limit is not None and len(visited_urls) >= self.limit:
@@ -123,7 +127,13 @@ class CrawlerLoader(BaseRemote):
         soup = BeautifulSoup(html_content, 'html.parser')
         links = []
         for a in soup.find_all('a', href=True):
-            full_url = urljoin(current_url, a['href'])
+            # A malformed href (``http://[bad``) makes urljoin or the later
+            # parse raise; skip that link rather than abort the crawl.
+            try:
+                full_url = urljoin(current_url, a['href'])
+                normalize_page_url(full_url)
+            except ValueError:
+                continue
             links.append((full_url, a.text.strip()))
         return links
 
diff --git a/docsgpt/storage/db/repositories/schedule_runs.py b/docsgpt/storage/db/repositories/schedule_runs.py
index 95311d45..1156ffe0 100644
--- a/docsgpt/storage/db/repositories/schedule_runs.py
+++ b/docsgpt/storage/db/repositories/schedule_runs.py
@@ -173,7 +173,8 @@ class ScheduleRunsRepository:
         """Aggregate run stats for an agent's owned schedules over a window.
 
         Only runs of schedules owned by ``user_id`` on ``agent_id`` whose
-        ``scheduled_for`` falls within the last ``days`` days are counted.
+        ``scheduled_for`` falls within the last ``days`` days are counted;
+        runs scheduled in the future are not.
 
         Args:
             agent_id: Agent UUID the schedules belong to.
@@ -198,6 +199,7 @@ class ScheduleRunsRepository:
                       AND s.user_id = :user_id
                       AND r.user_id = :user_id
                       AND r.scheduled_for >= now() - make_interval(days => :days)
+                      AND r.scheduled_for <= now()
                 ),
                 latest_failure AS (
                     SELECT scheduled_for, status, error_type
diff --git a/docsgpt/vectorstore/base.py b/docsgpt/vectorstore/base.py
index 348f99e5..5498098f 100644
--- a/docsgpt/vectorstore/base.py
+++ b/docsgpt/vectorstore/base.py
@@ -455,15 +455,29 @@ class BaseVectorStore(ABC):
 
         Returns:
             The id the updated chunk is stored under.
+
+        Raises:
+            RuntimeError: The old chunk could not be deleted. The new chunk is
+                deleted again (best effort) so no duplicate is left behind.
         """
         new_chunk_id = self.add_chunk(text, metadata)
-        if not self.delete_chunk(chunk_id):
-            logging.warning(
-                "Failed to delete old chunk %s, but new chunk %s was created",
-                chunk_id,
+        delete_error: Optional[Exception] = None
+        try:
+            deleted = self.delete_chunk(chunk_id)
+        except Exception as err:
+            deleted, delete_error = False, err
+        if deleted:
+            return new_chunk_id
+        try:
+            self.delete_chunk(new_chunk_id)
+        except Exception:
+            logging.error(
+                "Failed to roll back new chunk %s after old chunk %s could not be deleted",
                 new_chunk_id,
+                chunk_id,
+                exc_info=True,
             )
-        return new_chunk_id
+        raise RuntimeError(f"Failed to delete old chunk {chunk_id} during update") from delete_error
 
     def delete_chunks_by_source_path(self, path) -> int:
         """Delete every chunk whose ``metadata.source`` equals ``path``.
diff --git a/frontend/eslint/card-surfaces.js b/frontend/eslint/card-surfaces.js
index d5ca6a29..3c5a5cca 100644
--- a/frontend/eslint/card-surfaces.js
+++ b/frontend/eslint/card-surfaces.js
@@ -6,8 +6,11 @@
 // JSX tree as the `<Card variant="filled">`, not ones a child component
 // renders.
 
-const FILLED_CARD =
-  'JSXElement:has(> JSXOpeningElement[name.name="Card"]:has(> JSXAttribute[name.name="variant"][value.value="filled"]))';
+// `variant="filled"` or `variant={'filled'}`.
+const FILLED_VARIANT =
+  'JSXAttribute[name.name="variant"]:matches([value.value="filled"], [value.expression.value="filled"])';
+
+const FILLED_CARD = `JSXElement:has(> JSXOpeningElement[name.name="Card"]:has(> ${FILLED_VARIANT}))`;
 
 // `bg-muted` or `bg-muted/NN`, with any variant prefix, but not
 // `bg-muted-foreground`.
@@ -16,7 +19,7 @@ const BG_MUTED = '/(^|[\\s:])bg-muted([^-a-z]|$)/';
 /** @type {{ selector: string, message: string }[]} */
 export const cardSurfaceSelectors = [
   {
-    selector: `${FILLED_CARD} JSXElement > JSXOpeningElement[name.name="Card"] > JSXAttribute[name.name="variant"][value.value="filled"]`,
+    selector: `${FILLED_CARD} JSXElement > JSXOpeningElement[name.name="Card"] > ${FILLED_VARIANT}`,
     message:
       'A filled Card inside a filled Card is a fill on a fill. A well inside a tile needs a panel around it, or none. See DESIGN.md "Card surfaces".',
   },
diff --git a/frontend/eslint/design-rules.js b/frontend/eslint/design-rules.js
index 8473de38..ba5d0bbd 100644
--- a/frontend/eslint/design-rules.js
+++ b/frontend/eslint/design-rules.js
@@ -31,7 +31,7 @@ export const everywhereSelectors = [
     'z-index comes from the stacking layers: z-10 sticky headers, z-20 in-page floating chrome, z-50 overlays, z-200 portalled floating lists. See DESIGN.md "Stacking".',
   ),
   ...inStrings(
-    '/(^|\\s)(focus|focus-visible|focus-within):ring-2(\\s|$)/',
+    '/(^|[\\s:-])(focus|focus-visible|focus-within):ring-2(\\s|$)/',
     'The focus ring is ring-3 ring-ring/50 on focus-visible (fields: focus-within on a frame the same way). ring-2 is only for selection rings. See DESIGN.md "Focus ring".',
   ),
   {
@@ -49,7 +49,7 @@ export const pageSelectors = [
     'Transition only the property that changes: transition-colors by default, transition-transform for chevrons, transition-shadow for a ring. See DESIGN.md "Motion".',
   ),
   ...inStrings(
-    '/(^|\\s)hover:scale-(?!x-|y-)/',
+    '/(^|[\\s:-])hover:scale-(?!x-|y-)/',
     'Hover is a fill, border or text-colour change, never a scale. See DESIGN.md "Motion".',
   ),
   ...inStrings(
@@ -82,8 +82,8 @@ export const pageSelectors = [
       'Every table is ui/table (Table, TableHead, TableRow…), never a raw <table>. See DESIGN.md "Table".',
   },
   ...[
-    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] Literal[value=/(^|\\s)(underline|text-primary)(\\s|$)/]',
-    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] TemplateElement[value.raw=/(^|\\s)(underline|text-primary)(\\s|$)/]',
+    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] Literal[value=/(^|[\\s:])(underline|text-primary)(\\s|$)/]',
+    'JSXOpeningElement[name.name="a"] > JSXAttribute[name.name="className"] TemplateElement[value.raw=/(^|[\\s:])(underline|text-primary)(\\s|$)/]',
   ].map((selector) => ({
     selector,
     message:
diff --git a/frontend/src/components/Chunks.test.tsx b/frontend/src/components/Chunks.test.tsx
index de91252e..c1778a9a 100644
--- a/frontend/src/components/Chunks.test.tsx
+++ b/frontend/src/components/Chunks.test.tsx
@@ -789,18 +789,24 @@ describe('Chunks', () => {
     expect(container.querySelector('h1')?.textContent).toBe('Second');
   });
 
-  it('an edited chunk the store moved elsewhere is found by its id', async () => {
+  it('an edited chunk the store moved off the probed positions keeps what is shown', async () => {
     serveStore(1);
     await render({ embedded: true });
     const tiles = container.querySelectorAll<HTMLButtonElement>(
       'button[data-slot="card"]',
     );
-    await act(async () => tiles[2].click());
-    await editOpenChunk('# Third edited');
-    expect(container.querySelector('h1')?.textContent).toBe('Third edited');
-    expect(position()).toEqual([2, 3]);
-    await act(async () => buttonByLabel('settings.sources.nextChunk')!.click());
-    expect(container.querySelector('h1')?.textContent).toBe('Second');
+    await act(async () => tiles[0].click());
+    service.getDocumentChunks.mockClear();
+    await editOpenChunk('# First edited');
+    expect(container.querySelector('h1')?.textContent).toBe('First edited');
+    expect(position()).toEqual([1, 3]);
+    // Only the open and last positions are probed: the whole filtered list
+    // (one page of `total`) is never fetched.
+    const sizes = service.getDocumentChunks.mock.calls.map(
+      (call: unknown[]) => call[2],
+    );
+    expect(sizes).toContain(1);
+    expect(sizes).not.toContain(3);
   });
 
   it('an edited chunk that keeps its place stays put', async () => {
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index 7ecd0ced..bd1c4039 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -211,10 +211,10 @@ const Chunks: React.FC<ChunksProps> = ({
    * After a save, find the edited chunk in the store's current order and show
    * its stored copy (fresh metadata) at that position, so "n of total" and
    * previous / next follow the list as it now is. Checked in turn: the open
-   * position (the chunk stayed), the last one (a store that appends the new
-   * copy), then the whole filtered list. Each probe matches by id, so no
-   * store ordering is assumed. When the chunk is not in the list (a search
-   * it no longer matches), what is shown stays.
+   * position (the chunk stayed), then the last one (a store that re-adds the
+   * copy at the end). Each probe matches by id, so no store ordering is
+   * assumed. When neither holds it (moved elsewhere, or a search it no longer
+   * matches), what is shown stays: the whole filtered list is never fetched.
    *
    * @param chunk The chunk just saved, with its new id.
    */
@@ -249,25 +249,11 @@ const Chunks: React.FC<ChunksProps> = ({
         return;
       }
       if (total < 1) return;
-      if (total !== openPosition) {
-        const last = await fetchPage(total, 1);
-        if (!last) return;
-        const lastChunk: ChunkType | undefined = last.chunks?.[0];
-        if (lastChunk?.doc_id === chunk.doc_id) {
-          show(lastChunk, total, total);
-          return;
-        }
-      }
-      const all = await fetchPage(1, total);
-      if (!all) return;
-      const list: ChunkType[] = all.chunks ?? [];
-      const index = list.findIndex((c) => c.doc_id === chunk.doc_id);
-      if (index >= 0)
-        show(
-          list[index],
-          index + 1,
-          typeof all.total === 'number' ? all.total : total,
-        );
+      if (total === openPosition) return;
+      const last = await fetchPage(total, 1);
+      if (!last) return;
+      const lastChunk: ChunkType | undefined = last.chunks?.[0];
+      if (lastChunk?.doc_id === chunk.doc_id) show(lastChunk, total, total);
     } catch (error) {
       console.error(error);
     }
@@ -394,10 +380,11 @@ const Chunks: React.FC<ChunksProps> = ({
       if (!response.ok) throw new Error('Failed to update chunk');
       const data = await response.json().catch(() => ({}));
       closeSheet();
-      // The edit is saved under a new id. Show it straight away (its token
-      // count is recomputed server-side, so it is dropped until the reload),
-      // then find where the store now keeps it: the update re-adds the chunk,
-      // so it can move (FAISS appends it; pgvector has no ORDER BY).
+      // Show the edit straight away (its token count is recomputed
+      // server-side, so it is dropped until the reload), then find where the
+      // store now keeps it. Most stores (FAISS, MongoDB, pgvector, Qdrant)
+      // update in place: same id, same position. Only the base add-then-delete
+      // fallback (Milvus) saves it under a new id, which can move it.
       const edited: ChunkType = {
         ...chunk,
         doc_id: data.chunk_id ?? chunk.doc_id,
diff --git a/frontend/src/design/cardSurfaces.lint.test.ts b/frontend/src/design/cardSurfaces.lint.test.ts
index 30ef1d07..7027ca3d 100644
--- a/frontend/src/design/cardSurfaces.lint.test.ts
+++ b/frontend/src/design/cardSurfaces.lint.test.ts
@@ -27,6 +27,11 @@ function lint(code: string): string[] {
 
 describe('card surface lint: no fill on a fill', () => {
   it('rejects bg-muted on an element inside a filled tile, in cn() too', () => {
+    expect(
+      lint(
+        `<Card variant={'filled'}><div className="bg-muted px-4">x</div></Card>`,
+      ),
+    ).toHaveLength(1);
     expect(
       lint(
         `<Card variant="filled"><div className="bg-muted px-4">x</div></Card>`,
@@ -45,12 +50,25 @@ describe('card surface lint: no fill on a fill', () => {
         `<Card variant="filled"><Card variant="filled" padding="sm">x</Card></Card>`,
       ),
     ).toHaveLength(1);
+    expect(
+      lint(
+        `<Card variant={'filled'}><Card variant="filled" padding="sm">x</Card></Card>`,
+      ),
+    ).toHaveLength(1);
+    expect(
+      lint(
+        `<Card variant="filled"><Card variant={'filled'} padding="sm">x</Card></Card>`,
+      ),
+    ).toHaveLength(1);
   });
 
   it('rejects a Skeleton without surface="muted" on a filled tile', () => {
     expect(
       lint(`<Card variant="filled"><Skeleton className="h-4" /></Card>`),
     ).toHaveLength(1);
+    expect(
+      lint(`<Card variant={'filled'}><Skeleton className="h-4" /></Card>`),
+    ).toHaveLength(1);
     expect(
       lint(
         `<Card variant="filled"><Skeleton surface="muted" className="h-4" /></Card>`,
diff --git a/frontend/src/design/designRules.lint.test.ts b/frontend/src/design/designRules.lint.test.ts
index 654b06a8..fc03cf92 100644
--- a/frontend/src/design/designRules.lint.test.ts
+++ b/frontend/src/design/designRules.lint.test.ts
@@ -44,14 +44,24 @@ describe('design rules lint', () => {
     ['off-scale z', `<div className="absolute z-30" />`],
     ['arbitrary z', `<div className="z-[60]" />`],
     ['focus ring-2', `<div className="focus-within:ring-2" />`],
+    ['md: focus ring-2', `<div className="md:focus-visible:ring-2" />`],
+    ['dark: focus ring-2', `<div className="dark:focus-visible:ring-2" />`],
+    ['peer focus ring-2', `<div className="peer-focus-visible:ring-2" />`],
     ['lucide loader', `import { Loader2 } from 'lucide-react';`],
     ['transition-all', `<div className="transition-all duration-200" />`],
     ['hover scale', `<div className="hover:scale-105" />`],
+    ['md:hover scale', `<div className="md:hover:scale-105" />`],
+    ['group-hover scale', `<div className="group-hover:scale-105" />`],
     ['bg-primary/10', `const tone = 'bg-primary/10 text-primary';`],
     ['native checkbox', `<input type="checkbox" />`],
     ['title on Button', `<Button title="Delete" />`],
     ['raw table', `<table><tbody /></table>`],
     ['link-styled a', `<a className="text-primary underline" href="#">x</a>`],
+    ['hover: underline a', `<a className="hover:underline" href="#">x</a>`],
+    [
+      'dark: text-primary a',
+      `<a className={\`dark:text-primary \${x}\`} href="#">x</a>`,
+    ],
     ['drawer width', `<SheetContent side="right" className="sm:max-w-xl" />`],
     ['drawer w-', `<SheetContent className="w-80 p-0" />`],
   ])('rejects %s', (_name, code) => {
@@ -70,6 +80,9 @@ describe('design rules lint', () => {
     ['size and max-w', `<div className="size-4 max-w-[520px] min-h-dvh" />`],
     ['selection ring-2', `<div className="ring-2 ring-primary" />`],
     ['hover:scale-x underline wipe', `<span className="hover:scale-x-100" />`],
+    ['md:hover:scale-x wipe', `<span className="md:hover:scale-x-100" />`],
+    ['no-underline a', `<a className="no-underline" href="#">x</a>`],
+    ['underline-offset a', `<a className="underline-offset-2" href="#">x</a>`],
     ['transition-colors', `<div className="transition-colors" />`],
     [
       'other lucide icons',
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index 6373950f..777ac34f 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -1101,7 +1101,6 @@
       "dropzoneText": "Zum Hochladen klicken oder per Drag & Drop ablegen",
       "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, Bilder, Audio, EPUB, JSON oder ZIP, jeweils bis zu 25 MB",
       "filesRejected": "Nicht hinzugefügt (größer als 25 MB oder kein unterstützter Dateityp): {{files}}",
-      "info": "Bitte lade .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip hoch (max. 25 MB)",
       "uploadedFiles": "Hochgeladene Dateien",
       "cancel": "Abbrechen",
       "train": "Trainieren",
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index a9cf4d9e..64710d2a 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -1107,7 +1107,6 @@
       "dropzoneText": "Click to upload or drag and drop",
       "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, images, audio, EPUB, JSON or ZIP, up to 25 MB each",
       "filesRejected": "Not added (over 25 MB or not a supported type): {{files}}",
-      "info": "Please upload .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip limited to 25mb",
       "uploadedFiles": "Uploaded Files",
       "cancel": "Cancel",
       "train": "Train",
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index 0d1de95c..be8701d6 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -1101,7 +1101,6 @@
       "dropzoneText": "Haz clic para subir o arrastra y suelta",
       "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, imágenes, audio, EPUB, JSON o ZIP, hasta 25 MB cada uno",
       "filesRejected": "No se añadieron (más de 25 MB o tipo no admitido): {{files}}",
-      "info": "Por favor, sube archivos .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip limitados a 25MB",
       "uploadedFiles": "Archivos Subidos",
       "cancel": "Cancelar",
       "train": "Entrenar",
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index b6545147..55cfe814 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -1092,7 +1092,6 @@
       "dropzoneText": "クリックしてアップロード、またはドラッグ＆ドロップ",
       "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、画像、音声、EPUB、JSON、ZIP（各 25 MB まで）",
       "filesRejected": "追加されませんでした（25 MB を超えているか、未対応の形式です）: {{files}}",
-      "info": "25MBまでの.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zipファイルをアップロードしてください",
       "uploadedFiles": "アップロードされたファイル",
       "cancel": "キャンセル",
       "train": "トレーニング",
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index b0e770f4..fd694e1e 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -1157,7 +1157,6 @@
       "dropzoneText": "Нажмите, чтобы загрузить, или перетащите файлы",
       "dropzoneHint": "PDF, Word, Excel, PowerPoint, Markdown, HTML, изображения, аудио, EPUB, JSON или ZIP, до 25 МБ каждый",
       "filesRejected": "Не добавлены (больше 25 МБ или неподдерживаемый формат): {{files}}",
-      "info": "Пожалуйста, загрузите файлы .pdf, .txt, .rst, .csv, .xlsx, .xlsm, .xlsb, .xls, .ods, .docx, .docm, .doc, .odt, .rtf, .md, .html, .xhtml, .png, .jpg, .jpeg, .epub, .json, .pptx, .pptm, .ppt, .pps, .ppsx, .ppsm, .pot, .odp, .zip размером до 25 МБ",
       "uploadedFiles": "Загруженные файлы",
       "cancel": "Отмена",
       "train": "Тренировка",
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index 33988770..35d1aebc 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -1092,7 +1092,6 @@
       "dropzoneText": "點擊上傳或拖放檔案",
       "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、圖片、音訊、EPUB、JSON 或 ZIP，每個最大 25 MB",
       "filesRejected": "未新增（超過 25 MB 或不支援的類型）：{{files}}",
-      "info": "請上傳限制為25MB的.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zip檔案",
       "uploadedFiles": "已上傳檔案",
       "cancel": "取消",
       "train": "訓練",
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index 5cb22646..e63ea714 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -1092,7 +1092,6 @@
       "dropzoneText": "点击上传或拖放文件",
       "dropzoneHint": "PDF、Word、Excel、PowerPoint、Markdown、HTML、图片、音频、EPUB、JSON 或 ZIP，每个最大 25 MB",
       "filesRejected": "未添加（超过 25 MB 或不支持的类型）：{{files}}",
-      "info": "请上传限制为25MB的.pdf、.txt、.rst、.csv、.xlsx、.xlsm、.xlsb、.xls、.ods、.docx、.docm、.doc、.odt、.rtf、.md、.html、.xhtml、.png、.jpg、.jpeg、.epub、.json、.pptx、.pptm、.ppt、.pps、.ppsx、.ppsm、.pot、.odp、.zip文件",
       "uploadedFiles": "已上传文件",
       "cancel": "取消",
       "train": "训练",
diff --git a/frontend/src/settings/Prompts.test.tsx b/frontend/src/settings/Prompts.test.tsx
index 39c2fcef..e45b5aef 100644
--- a/frontend/src/settings/Prompts.test.tsx
+++ b/frontend/src/settings/Prompts.test.tsx
@@ -93,6 +93,7 @@ describe('Prompts', () => {
     const row = container.querySelector('[data-slot="setting-row"]')!;
     const label = row.querySelector<HTMLLabelElement>('label')!;
     expect(label.textContent).toBe('settings.general.prompt');
+    expect(trigger.id).toBeTruthy();
     expect(label.htmlFor).toBe(trigger.id);
     expect(row.textContent).toContain('Used without an agent.');
     expect(trigger.hasAttribute('aria-label')).toBe(false);
@@ -140,6 +141,7 @@ describe('Prompts', () => {
     const trigger = container.querySelector<HTMLButtonElement>(
       'button[role="combobox"]',
     )!;
+    expect(trigger.id).toBeTruthy();
     expect(label.htmlFor).toBe(trigger.id);
     expect(trigger.hasAttribute('aria-label')).toBe(false);
     expect(trigger.className).toContain('w-full');
diff --git a/tests/api/user/sources/test_chunks.py b/tests/api/user/sources/test_chunks.py
index b46b30ee..052e54b4 100644
--- a/tests/api/user/sources/test_chunks.py
+++ b/tests/api/user/sources/test_chunks.py
@@ -810,3 +810,40 @@ class TestUpdateChunkGraphLinks:
         graph_store.remap_chunk.assert_called_once_with(
             str(src["id"]), "chunk-old", "chunk-new"
         )
+
+    def test_default_fallback_failed_delete_returns_500_without_duplicate(self, app, pg_conn):
+        """A failed old-chunk delete rolls the new chunk back and fails the request."""
+        from docsgpt.vectorstore.base import BaseVectorStore
+
+        class _FallbackStore(BaseVectorStore):
+            def __init__(self):
+                super().__init__()
+                self.deleted = []
+
+            def search(self, *args, **kwargs):
+                return []
+
+            def add_texts(self, texts, metadatas=None, *args, **kwargs):
+                return []
+
+            def get_chunks(self):
+                return [{"doc_id": "chunk-old", "text": "old", "metadata": {}}]
+
+            def add_chunk(self, text, metadata=None):
+                return "chunk-new"
+
+            def delete_chunk(self, chunk_id):
+                self.deleted.append(chunk_id)
+                return chunk_id != "chunk-old"
+
+        user = "u-upd-graph-fallback-fail"
+        src = self._graph_source(pg_conn, user)
+        graph_store = MagicMock()
+        store = _FallbackStore()
+        store_proxy = MagicMock(wraps=store)
+
+        response = self._put(app, pg_conn, src, user, graph_store, store_proxy)
+
+        assert response.status_code == 500
+        assert store.deleted == ["chunk-old", "chunk-new"]
+        graph_store.remap_chunk.assert_not_called()
diff --git a/tests/api/user/sources/test_graph_view.py b/tests/api/user/sources/test_graph_view.py
index 8d06004f..01203623 100644
--- a/tests/api/user/sources/test_graph_view.py
+++ b/tests/api/user/sources/test_graph_view.py
@@ -282,6 +282,27 @@ class TestSourceGraphNodes:
             sid, query="ada", type_key="person", offset=200, limit=100
         )
 
+    def test_caps_search_query_length(self, app, pg_conn):
+        from docsgpt.api.user.sources.routes import SourceGraphNodes
+
+        user = "u-graph-nodes-long-q"
+        sid = _graphrag_source(pg_conn, user)
+        store = _node_list_store()
+
+        with _patch_db(pg_conn), patch(
+            "docsgpt.graphrag.store.GraphStore", return_value=store
+        ), app.test_request_context(
+            f"/api/sources/{sid}/graph/nodes?q=%20{'a' * 500}"
+        ):
+            from flask import request
+            request.decoded_token = {"sub": user}
+            response = SourceGraphNodes().get(sid)
+
+        assert response.status_code == 200
+        store.list_nodes.assert_called_once_with(
+            sid, query="a" * 200, type_key=None, offset=0, limit=25
+        )
+
     @pytest.mark.parametrize(
         "qs, page, per_page",
         [
diff --git a/tests/core/test_url_validation.py b/tests/core/test_url_validation.py
index 4329054e..f06b893d 100644
--- a/tests/core/test_url_validation.py
+++ b/tests/core/test_url_validation.py
@@ -259,3 +259,22 @@ class TestValidateUrlExtended:
     def test_allows_localhost_ip_with_flag(self):
         result = validate_url("http://10.0.0.1", allow_localhost=True)
         assert result == "http://10.0.0.1"
+
+
+class TestValidateUrlMalformed:
+    """A URL ``urlparse`` cannot parse fails validation instead of escaping."""
+
+    def test_unclosed_ipv6_bracket_raises_ssrf_error(self):
+        with pytest.raises(SSRFError) as exc_info:
+            validate_url("http://[bad")
+        assert "invalid url" in str(exc_info.value).lower()
+
+    def test_unclosed_ipv6_bracket_without_scheme_raises_ssrf_error(self):
+        with pytest.raises(SSRFError):
+            validate_url("[bad")
+
+    def test_safe_variant_reports_failure(self):
+        is_valid, url, error = validate_url_safe("http://[bad")
+        assert is_valid is False
+        assert url == "http://[bad"
+        assert error
diff --git a/tests/parser/remote/test_base.py b/tests/parser/remote/test_base.py
index 2f12f427..6b68ae8e 100644
--- a/tests/parser/remote/test_base.py
+++ b/tests/parser/remote/test_base.py
@@ -5,6 +5,7 @@ import pytest
 from docsgpt.parser.remote.base import (
     MAX_QUERY_SEGMENT_LENGTH,
     dedupe_virtual_paths,
+    normalize_page_url,
     url_to_virtual_path,
 )
 from docsgpt.parser.schema.base import Document
@@ -131,3 +132,29 @@ class TestDedupeVirtualPaths:
 
         assert dedupe_virtual_paths([doc]) == [doc]
         assert "file_path" not in doc.extra_info
+
+
+@pytest.mark.unit
+class TestNormalizePageUrl:
+    def test_query_order_does_not_matter(self):
+        assert normalize_page_url("https://x.io/p?a=1&b=2") == normalize_page_url("https://x.io/p?b=2&a=1")
+
+    def test_fragment_is_dropped(self):
+        assert normalize_page_url("https://x.io/p?a=1#top") == normalize_page_url("https://x.io/p?a=1")
+
+    def test_distinct_queries_stay_distinct(self):
+        assert normalize_page_url("https://x.io/p?page=1") != normalize_page_url("https://x.io/p?page=2")
+
+    def test_blank_values_are_kept(self):
+        assert normalize_page_url("https://x.io/p?flag") != normalize_page_url("https://x.io/p")
+
+    def test_url_without_query_or_fragment_is_unchanged(self):
+        assert normalize_page_url("https://x.io/guides/setup") == "https://x.io/guides/setup"
+
+
+@pytest.mark.unit
+class TestDedupeReorderedQuery:
+    def test_reordered_query_is_one_page(self):
+        docs = [_doc("https://x.com/p?a=1&b=2"), _doc("https://x.com/p?b=2&a=1")]
+
+        assert _paths(dedupe_virtual_paths(docs)) == ["p__a=1&b=2.md", "p__a=1&b=2.md"]
diff --git a/tests/parser/remote/test_crawler_loader.py b/tests/parser/remote/test_crawler_loader.py
index 7af6c54c..7053cc04 100644
--- a/tests/parser/remote/test_crawler_loader.py
+++ b/tests/parser/remote/test_crawler_loader.py
@@ -208,3 +208,43 @@ def test_colliding_pages_get_distinct_file_paths(mock_pinned_request, mock_valid
         "http://example.com/a.html": "a-2.md",
         "http://example.com/l?page=2": "l__page=2.md",
     }
+
+
+@patch("docsgpt.parser.remote.crawler_loader.validate_url", side_effect=_mock_validate_url)
+@patch("docsgpt.parser.remote.crawler_loader.pinned_request")
+def test_reordered_query_and_fragment_variants_are_fetched_once(mock_pinned_request, mock_validate_url):
+    responses = {
+        "http://example.com": DummyResponse(
+            "<html><body><a href='/p?a=1&b=2'>P</a><a href='/p?b=2&a=1'>P2</a>"
+            "<a href='/p?a=1&b=2#top'>P3</a></body></html>"
+        ),
+        "http://example.com/p?a=1&b=2": DummyResponse("<html><body>p</body></html>"),
+        "http://example.com/p?b=2&a=1": DummyResponse("<html><body>p</body></html>"),
+        "http://example.com/p?a=1&b=2#top": DummyResponse("<html><body>p</body></html>"),
+    }
+    mock_pinned_request.side_effect = lambda _m, url, timeout=30: responses[url]
+
+    result = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    fetched = [c.args[1] for c in mock_pinned_request.call_args_list]
+    assert fetched[0] == "http://example.com"
+    assert len(fetched) == 2
+    # The page is fetched as a link wrote it, not as its normalized key.
+    assert fetched[1] in responses
+    assert len(result) == 2
+
+
+@patch("docsgpt.parser.remote.crawler_loader.validate_url", side_effect=_mock_validate_url)
+@patch("docsgpt.parser.remote.crawler_loader.pinned_request")
+def test_malformed_link_does_not_abort_the_crawl(mock_pinned_request, mock_validate_url):
+    responses = {
+        "http://example.com": DummyResponse(
+            "<html><body><a href='http://[bad'>Bad</a><a href='/good'>Good</a></body></html>"
+        ),
+        "http://example.com/good": DummyResponse("<html><body>good</body></html>"),
+    }
+    mock_pinned_request.side_effect = lambda _m, url, timeout=30: responses[url]
+
+    result = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    assert {d.extra_info["source"] for d in result} == {"http://example.com", "http://example.com/good"}
diff --git a/tests/parser/remote/test_crawler_markdown.py b/tests/parser/remote/test_crawler_markdown.py
index f8e54687..614e5d44 100644
--- a/tests/parser/remote/test_crawler_markdown.py
+++ b/tests/parser/remote/test_crawler_markdown.py
@@ -204,3 +204,49 @@ def test_colliding_pages_get_distinct_file_paths(monkeypatch, _patch_markdownify
         "http://example.com/a.html": "a-2.md",
         "http://example.com/l?page=2": "l__page=2.md",
     }
+
+
+def test_reordered_query_and_fragment_variants_are_fetched_once(monkeypatch, _patch_markdownify):
+    root_html = (
+        "<html><head><title>Home</title></head><body>"
+        "<a href='/p?a=1&b=2'>P</a><a href='/p?b=2&a=1'>P2</a><a href='/p?a=1&b=2#top'>P3</a>"
+        "</body></html>"
+    )
+    page_html = "<html><body>p</body></html>"
+    responses = {
+        "http://example.com": DummyResponse(root_html),
+        "http://example.com/p?a=1&b=2": DummyResponse(page_html),
+        "http://example.com/p?b=2&a=1": DummyResponse(page_html),
+        "http://example.com/p?a=1&b=2#top": DummyResponse(page_html),
+    }
+    fetched = []
+
+    def side_effect(url):
+        fetched.append(url)
+        return responses[url]
+
+    _patch_pinned_request(monkeypatch, side_effect)
+
+    docs = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    assert len(fetched) == 2
+    assert fetched[0] == "http://example.com"
+    # The page is fetched as a link wrote it, not as its normalized key.
+    assert fetched[1] in responses
+    assert len(docs) == 2
+
+
+def test_malformed_link_does_not_abort_the_crawl(monkeypatch, _patch_markdownify):
+    root_html = (
+        "<html><head><title>Home</title></head><body>"
+        "<a href='http://[bad'>Bad</a><a href='/good'>Good</a></body></html>"
+    )
+    responses = {
+        "http://example.com": DummyResponse(root_html),
+        "http://example.com/good": DummyResponse("<html><body>good</body></html>"),
+    }
+    _patch_pinned_request(monkeypatch, lambda url: responses[url])
+
+    docs = CrawlerLoader(limit=10).load_data("http://example.com")
+
+    assert {d.extra_info["source"] for d in docs} == {"http://example.com", "http://example.com/good"}
diff --git a/tests/parser/remote/test_sitemap_loader.py b/tests/parser/remote/test_sitemap_loader.py
index 88691233..c6f844e4 100644
--- a/tests/parser/remote/test_sitemap_loader.py
+++ b/tests/parser/remote/test_sitemap_loader.py
@@ -351,3 +351,27 @@ class TestSitemapLoaderDistinctPaths:
             docs = loader.load_data("https://x.io/sitemap.xml")
 
         assert [d.extra_info["file_path"] for d in docs] == ["p__page=2.md", "p.md", "p-2.md"]
+
+
+@pytest.mark.unit
+class TestSitemapLoaderMalformedEntry:
+
+    @patch("docsgpt.core.url_validation.resolve_hostname", return_value="93.184.216.34")
+    @patch("docsgpt.parser.remote.sitemap_loader.pinned_request")
+    def test_malformed_entry_is_skipped_and_the_rest_ingest(self, mock_pinned_request, _mock_resolve):
+        loader = SitemapLoader()
+        response = MagicMock()
+        response.text = "Good body"
+        response.raise_for_status.return_value = None
+        mock_pinned_request.return_value = response
+
+        with patch.object(
+            loader, "_extract_urls",
+            return_value=["http://[bad", "https://example.com/good"],
+        ):
+            docs = loader.load_data("https://example.com/sitemap.xml")
+
+        assert [d.extra_info for d in docs] == [
+            {"source": "https://example.com/good", "file_path": "good.md"}
+        ]
+        mock_pinned_request.assert_called_once()
diff --git a/tests/parser/remote/test_web_loader.py b/tests/parser/remote/test_web_loader.py
index 97c885c0..9284071f 100644
--- a/tests/parser/remote/test_web_loader.py
+++ b/tests/parser/remote/test_web_loader.py
@@ -351,3 +351,16 @@ class TestWebLoaderDistinctPaths:
         assert [d.extra_info["file_path"] for d in result] == [
             "list__page=1.md", "list__page=2.md", "a-2.md", "a.md"
         ]
+
+
+@pytest.mark.unit
+class TestWebLoaderMalformedUrl:
+    @patch("docsgpt.core.url_validation.resolve_hostname", return_value="93.184.216.34")
+    @patch("docsgpt.parser.remote.web_loader.pinned_request")
+    def test_malformed_url_is_skipped_and_the_rest_ingest(self, mock_pinned_request, _mock_resolve, web_loader):
+        mock_pinned_request.side_effect = lambda *a, **k: _fake_response("<html><body>good</body></html>")
+
+        result = web_loader.load_data(["http://[bad", "https://x.io/good"])
+
+        assert [d.extra_info["source"] for d in result] == ["https://x.io/good"]
+        assert result[0].extra_info["file_path"] == "good.md"
diff --git a/tests/storage/db/repositories/test_schedule_runs.py b/tests/storage/db/repositories/test_schedule_runs.py
index 3cb58966..9b4cd54c 100644
--- a/tests/storage/db/repositories/test_schedule_runs.py
+++ b/tests/storage/db/repositories/test_schedule_runs.py
@@ -283,3 +283,24 @@ class TestStatsForAgent:
         assert narrow["runs"] == 1
         assert narrow["failed"] == 0
         assert narrow["latest_failure"] is None
+
+    def test_future_runs_are_not_counted(self, pg_conn):
+        schedule_id, agent_id = _make_schedule(pg_conn)
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=timedelta(hours=1),
+            status="success", prompt_tokens=3, generated_tokens=4,
+        )
+        # Scheduled a day ahead: inside ``>= now() - days`` but not yet due.
+        _add_run(
+            pg_conn, schedule_id, "u1", agent_id, ago=-timedelta(days=1),
+            status="failed", prompt_tokens=500, generated_tokens=500,
+            error_type="agent_error",
+        )
+
+        stats = ScheduleRunsRepository(pg_conn).stats_for_agent(
+            agent_id, "u1", days=30,
+        )
+        assert stats["runs"] == 1
+        assert stats["failed"] == 0
+        assert stats["tokens"] == 7
+        assert stats["latest_failure"] is None
diff --git a/tests/vectorstore/test_base.py b/tests/vectorstore/test_base.py
index 37bf9cf8..92f0c047 100644
--- a/tests/vectorstore/test_base.py
+++ b/tests/vectorstore/test_base.py
@@ -665,10 +665,11 @@ class TestGetEmbeddingsResolver:
 class _RecordingStore(ConcreteVectorStore):
     """Store whose add/delete calls are recorded, for the update fallback."""
 
-    def __init__(self, delete_result=True):
+    def __init__(self, delete_result=True, delete_error=None):
         super().__init__()
         self.calls = []
         self._delete_result = delete_result
+        self._delete_error = delete_error
 
     def add_chunk(self, text, metadata=None, *args, **kwargs):
         self.calls.append(("add", text, metadata))
@@ -676,6 +677,10 @@ class _RecordingStore(ConcreteVectorStore):
 
     def delete_chunk(self, chunk_id, *args, **kwargs):
         self.calls.append(("delete", chunk_id))
+        if chunk_id != "old-id":
+            return True
+        if self._delete_error is not None:
+            raise self._delete_error
         return self._delete_result
 
 
@@ -689,14 +694,44 @@ class TestBaseUpdateChunkFallback:
         assert new_id == "new-id"
         assert store.calls == [("add", "new text", {"k": "v"}), ("delete", "old-id")]
 
-    def test_failed_delete_is_logged_not_raised(self, caplog):
+    def test_false_delete_rolls_back_the_new_chunk_and_raises(self):
         store = _RecordingStore(delete_result=False)
 
-        with caplog.at_level("WARNING"):
-            new_id = store.update_chunk("old-id", "new text", {})
+        with pytest.raises(RuntimeError, match="old-id"):
+            store.update_chunk("old-id", "new text", {})
 
-        assert new_id == "new-id"
-        assert "old-id" in caplog.text
+        assert store.calls == [
+            ("add", "new text", {}),
+            ("delete", "old-id"),
+            ("delete", "new-id"),
+        ]
+
+    def test_raising_delete_rolls_back_the_new_chunk_and_raises(self):
+        store = _RecordingStore(delete_error=ConnectionError("milvus down"))
+
+        with pytest.raises(RuntimeError, match="old-id") as excinfo:
+            store.update_chunk("old-id", "new text", {})
+
+        assert isinstance(excinfo.value.__cause__, ConnectionError)
+        assert store.calls[-1] == ("delete", "new-id")
+
+    def test_failed_rollback_still_raises_the_update_error(self, caplog):
+        store = _RecordingStore(delete_result=False)
+        real_delete = store.delete_chunk
+
+        def delete(chunk_id, *args, **kwargs):
+            if chunk_id == "new-id":
+                store.calls.append(("delete", chunk_id))
+                raise ConnectionError("rollback failed")
+            return real_delete(chunk_id)
+
+        store.delete_chunk = delete
+
+        with caplog.at_level("ERROR"), pytest.raises(RuntimeError, match="old-id"):
+            store.update_chunk("old-id", "new text", {})
+
+        assert ("delete", "new-id") in store.calls
+        assert "new-id" in caplog.text
 
     def test_failed_add_skips_the_delete(self):
         store = _RecordingStore()

From b12f5b6c81de907cbeb96bae1740a088ef852206 Mon Sep 17 00:00:00 2001
From: Pavel <pabin@yandex.ru>
Date: Mon, 28 Sep 2026 19:02:50 +0400
Subject: [PATCH 7/7] Chunk nav fixed

---
 frontend/src/components/Chunks.test.tsx | 13 ++++-
 frontend/src/components/Chunks.tsx      | 78 +++++++++++++++++--------
 frontend/src/locale/de.json             |  3 +
 frontend/src/locale/en.json             |  3 +
 frontend/src/locale/es.json             |  3 +
 frontend/src/locale/jp.json             |  3 +
 frontend/src/locale/ru.json             |  3 +
 frontend/src/locale/zh-TW.json          |  3 +
 frontend/src/locale/zh.json             |  3 +
 9 files changed, 87 insertions(+), 25 deletions(-)

diff --git a/frontend/src/components/Chunks.test.tsx b/frontend/src/components/Chunks.test.tsx
index c1778a9a..42a1e372 100644
--- a/frontend/src/components/Chunks.test.tsx
+++ b/frontend/src/components/Chunks.test.tsx
@@ -507,6 +507,8 @@ describe('Chunks', () => {
     await act(async () => buttonByText('modals.chunk.save')!.click());
     expect(drawer()).toBeNull();
     expect(container.querySelector('h2')?.textContent).toBe('Rewritten');
+    expect(container.textContent).toContain('chunkPositionUnplaced');
+    expect(buttonByLabel('settings.sources.nextChunk')!.disabled).toBe(true);
   });
 
   it('deleting the only chunk on the last page lands on the page before', async () => {
@@ -789,7 +791,7 @@ describe('Chunks', () => {
     expect(container.querySelector('h1')?.textContent).toBe('Second');
   });
 
-  it('an edited chunk the store moved off the probed positions keeps what is shown', async () => {
+  it('an edited chunk the store moved off the probed positions keeps its text but not its place', async () => {
     serveStore(1);
     await render({ embedded: true });
     const tiles = container.querySelectorAll<HTMLButtonElement>(
@@ -799,7 +801,14 @@ describe('Chunks', () => {
     service.getDocumentChunks.mockClear();
     await editOpenChunk('# First edited');
     expect(container.querySelector('h1')?.textContent).toBe('First edited');
-    expect(position()).toEqual([1, 3]);
+    // Its position is unknown: no number is claimed and paging is off, so
+    // previous / next can't step from a place the chunk no longer holds.
+    expect(container.textContent).not.toMatch(/chunkPosition \{/);
+    expect(container.textContent).toContain('chunkPositionUnplaced');
+    expect(buttonByLabel('settings.sources.previousChunk')!.disabled).toBe(
+      true,
+    );
+    expect(buttonByLabel('settings.sources.nextChunk')!.disabled).toBe(true);
     // Only the open and last positions are probed: the whole filtered list
     // (one page of `total`) is never fetched.
     const sizes = service.getDocumentChunks.mock.calls.map(
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index bd1c4039..ae6e0ddc 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -111,6 +111,9 @@ const Chunks: React.FC<ChunksProps> = ({
   const [openChunk, setOpenChunk] = useState<ChunkType | null>(null);
   // The open chunk's position in the whole filtered list (1-based).
   const [openPosition, setOpenPosition] = useState(0);
+  // Set when a save leaves the open chunk off every probed position: its
+  // place in the list is unknown, so position labels and paging are off.
+  const [positionLost, setPositionLost] = useState(false);
   // A previous / next fetch in flight.
   const [stepping, setStepping] = useState(false);
   const stepRef = useRef(0);
@@ -197,6 +200,7 @@ const Chunks: React.FC<ChunksProps> = ({
       if (chunk) {
         setOpenChunk(chunk);
         setOpenPosition(position);
+        setPositionLost(false);
       }
     } catch (error) {
       console.error(error);
@@ -214,7 +218,10 @@ const Chunks: React.FC<ChunksProps> = ({
    * position (the chunk stayed), then the last one (a store that re-adds the
    * copy at the end). Each probe matches by id, so no store ordering is
    * assumed. When neither holds it (moved elsewhere, or a search it no longer
-   * matches), what is shown stays: the whole filtered list is never fetched.
+   * matches), the saved text stays but its position is unknown, so the
+   * position labels drop the number and previous / next are off until the
+   * reader closes; the whole filtered list is never fetched. A failed or
+   * superseded probe leaves what is shown.
    *
    * @param chunk The chunk just saved, with its new id.
    */
@@ -237,6 +244,7 @@ const Chunks: React.FC<ChunksProps> = ({
       setTotalChunks(total);
       setOpenChunk(stored);
       setOpenPosition(at);
+      setPositionLost(false);
     };
     try {
       const here = await fetchPage(openPosition, 1);
@@ -248,12 +256,17 @@ const Chunks: React.FC<ChunksProps> = ({
         show(stored, openPosition, total);
         return;
       }
-      if (total < 1) return;
-      if (total === openPosition) return;
-      const last = await fetchPage(total, 1);
-      if (!last) return;
-      const lastChunk: ChunkType | undefined = last.chunks?.[0];
-      if (lastChunk?.doc_id === chunk.doc_id) show(lastChunk, total, total);
+      if (total >= 1 && total !== openPosition) {
+        const last = await fetchPage(total, 1);
+        if (!last) return;
+        const lastChunk: ChunkType | undefined = last.chunks?.[0];
+        if (lastChunk?.doc_id === chunk.doc_id) {
+          show(lastChunk, total, total);
+          return;
+        }
+      }
+      setTotalChunks(total);
+      setPositionLost(true);
     } catch (error) {
       console.error(error);
     }
@@ -296,6 +309,7 @@ const Chunks: React.FC<ChunksProps> = ({
   const showChunk = (chunk: ChunkType, position: number) => {
     setOpenChunk(chunk);
     setOpenPosition(position);
+    setPositionLost(false);
   };
 
   /**
@@ -459,8 +473,10 @@ const Chunks: React.FC<ChunksProps> = ({
     setPage(1);
   }, [path]);
 
-  const canGoPrevious = !!openChunk && !stepping && openPosition > 1;
-  const canGoNext = !!openChunk && !stepping && openPosition < totalChunks;
+  const canGoPrevious =
+    !!openChunk && !stepping && !positionLost && openPosition > 1;
+  const canGoNext =
+    !!openChunk && !stepping && !positionLost && openPosition < totalChunks;
 
   // ← / → walk the chunks while nothing else owns the keys.
   const goToChunkRef = useRef(goToChunk);
@@ -490,7 +506,13 @@ const Chunks: React.FC<ChunksProps> = ({
           onSelect: openChunk ? () => closeChunk() : undefined,
         },
         ...(openChunk
-          ? [{ label: t('settings.sources.chunkCrumb', { n: openPosition }) }]
+          ? [
+              {
+                label: positionLost
+                  ? t('settings.sources.chunkCrumbUnplaced')
+                  : t('settings.sources.chunkCrumb', { n: openPosition }),
+              },
+            ]
           : []),
       ]}
       byline={
@@ -609,11 +631,15 @@ const Chunks: React.FC<ChunksProps> = ({
     <ReaderPanel
       meta={
         <span>
-          {t('settings.sources.chunkPosition', {
-            n: openPosition,
-            total: totalChunks,
-            tokens: formatChunkTokens(chunk.metadata),
-          })}
+          {positionLost
+            ? t('settings.sources.chunkPositionUnplaced', {
+                tokens: formatChunkTokens(chunk.metadata),
+              })
+            : t('settings.sources.chunkPosition', {
+                n: openPosition,
+                total: totalChunks,
+                tokens: formatChunkTokens(chunk.metadata),
+              })}
         </span>
       }
       actions={
@@ -723,14 +749,20 @@ const Chunks: React.FC<ChunksProps> = ({
             : t('settings.sources.addChunk')
         }
         description={
-          editing
-            ? t('settings.sources.editChunkDescription', {
-                file: fileLabel,
-                n: openPosition,
-                tokens: formatChunkTokens(openChunk?.metadata),
-                interpolation: { escapeValue: false },
-              })
-            : fileLabel || undefined
+          !editing
+            ? fileLabel || undefined
+            : positionLost
+              ? t('settings.sources.editChunkDescriptionUnplaced', {
+                  file: fileLabel,
+                  tokens: formatChunkTokens(openChunk?.metadata),
+                  interpolation: { escapeValue: false },
+                })
+              : t('settings.sources.editChunkDescription', {
+                  file: fileLabel,
+                  n: openPosition,
+                  tokens: formatChunkTokens(openChunk?.metadata),
+                  interpolation: { escapeValue: false },
+                })
         }
         value={draft}
         onChange={setDraft}
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index 777ac34f..d1c06fc5 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -411,6 +411,9 @@
       },
       "chunkPosition": "Chunk {{n}} von {{total}} · {{tokens}} Tokens",
       "chunkCrumb": "Chunk {{n}}",
+      "chunkCrumbUnplaced": "Bearbeiteter Chunk",
+      "chunkPositionUnplaced": "Bearbeiteter Chunk · {{tokens}} Tokens",
+      "editChunkDescriptionUnplaced": "{{file}} · bearbeiteter Chunk · {{tokens}} Tokens",
       "chunkTileMeta": "#{{n}} · {{tokens}} Tokens",
       "copyText": "Text kopieren",
       "chunkTitleHint": "Der Name, unter dem Antworten diesen Chunk zitieren.",
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index 64710d2a..85db5a4c 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -416,6 +416,9 @@
       },
       "chunkPosition": "Chunk {{n}} of {{total}} · {{tokens}} tokens",
       "chunkCrumb": "Chunk {{n}}",
+      "chunkCrumbUnplaced": "Edited chunk",
+      "chunkPositionUnplaced": "Edited chunk · {{tokens}} tokens",
+      "editChunkDescriptionUnplaced": "{{file}} · edited chunk · {{tokens}} tokens",
       "chunkTileMeta": "#{{n}} · {{tokens}} tokens",
       "copyText": "Copy text",
       "chunkTitleHint": "The name answers cite this chunk by.",
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index be8701d6..fb2eeb4f 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -411,6 +411,9 @@
       },
       "chunkPosition": "Fragmento {{n}} de {{total}} · {{tokens}} tokens",
       "chunkCrumb": "Fragmento {{n}}",
+      "chunkCrumbUnplaced": "Fragmento editado",
+      "chunkPositionUnplaced": "Fragmento editado · {{tokens}} tokens",
+      "editChunkDescriptionUnplaced": "{{file}} · fragmento editado · {{tokens}} tokens",
       "chunkTileMeta": "#{{n}} · {{tokens}} tokens",
       "copyText": "Copiar texto",
       "chunkTitleHint": "El nombre con el que las respuestas citan este fragmento.",
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index 55cfe814..7b4ce48a 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -404,6 +404,9 @@
       },
       "chunkPosition": "チャンク {{n}} / {{total}} · {{tokens}} トークン",
       "chunkCrumb": "チャンク {{n}}",
+      "chunkCrumbUnplaced": "編集済みチャンク",
+      "chunkPositionUnplaced": "編集済みチャンク · {{tokens}} トークン",
+      "editChunkDescriptionUnplaced": "{{file}} · 編集済みチャンク · {{tokens}} トークン",
       "chunkTileMeta": "#{{n}} · {{tokens}} トークン",
       "copyText": "テキストをコピー",
       "chunkTitleHint": "回答がこのチャンクを引用するときの名前です。",
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index fd694e1e..d7e48ac6 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -435,6 +435,9 @@
       },
       "chunkPosition": "Фрагмент {{n}} из {{total}} · токенов: {{tokens}}",
       "chunkCrumb": "Фрагмент {{n}}",
+      "chunkCrumbUnplaced": "Изменённый фрагмент",
+      "chunkPositionUnplaced": "Изменённый фрагмент · токенов: {{tokens}}",
+      "editChunkDescriptionUnplaced": "{{file}} · изменённый фрагмент · токенов: {{tokens}}",
       "chunkTileMeta": "#{{n}} · токенов: {{tokens}}",
       "copyText": "Копировать текст",
       "chunkTitleHint": "Название, под которым ответы ссылаются на этот фрагмент.",
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index 35d1aebc..3d3f5e40 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -404,6 +404,9 @@
       },
       "chunkPosition": "第 {{n}} 個文本塊，共 {{total}} 個 · {{tokens}} Token",
       "chunkCrumb": "第 {{n}} 個文本塊",
+      "chunkCrumbUnplaced": "已編輯的文本塊",
+      "chunkPositionUnplaced": "已編輯的文本塊 · {{tokens}} Token",
+      "editChunkDescriptionUnplaced": "{{file}} · 已編輯的文本塊 · {{tokens}} Token",
       "chunkTileMeta": "#{{n}} · {{tokens}} Token",
       "copyText": "複製文字",
       "chunkTitleHint": "回答引用此文本塊時使用的名稱。",
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index e63ea714..34bb52b6 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -404,6 +404,9 @@
       },
       "chunkPosition": "第 {{n}} 个文本块，共 {{total}} 个 · {{tokens}} 个令牌",
       "chunkCrumb": "第 {{n}} 个文本块",
+      "chunkCrumbUnplaced": "已编辑的文本块",
+      "chunkPositionUnplaced": "已编辑的文本块 · {{tokens}} 个令牌",
+      "editChunkDescriptionUnplaced": "{{file}} · 已编辑的文本块 · {{tokens}} 个令牌",
       "chunkTileMeta": "#{{n}} · {{tokens}} 个令牌",
       "copyText": "复制文本",
       "chunkTitleHint": "回答引用此文本块时使用的名称。",