diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 60c3553ee3..45cd070c34 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -199,6 +199,13 @@ const preview: Preview = {
           styles: { width: "1280px", height: "800px" },
           type: "mobile",
         },
+        wide: {
+          // Wide enough to trigger the @container query that reveals the
+          // sticky plan TOC next to a centered max-w-4xl transcript.
+          name: "Desktop wide",
+          styles: { width: "1600px", height: "900px" },
+          type: "desktop",
+        },
       },
     },
     chromatic: {
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 670ee8bbde..62b7ed1aab 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -228,6 +228,7 @@ Freely make breaking changes, and reorganize / cleanup IPC as needed.
 - **Use conditional rendering for testability:** Components like `AgentModePicker` use `{isOpen && <div>...}` instead of Radix Portal. This renders inline and works in happy-dom.
 - When adding new dropdown/popover components that need tests/ui coverage, prefer the conditional rendering pattern over Radix Portal.
 - E2E tests (tests/e2e) work with Radix but are slow (~2min startup); reserve for scenarios that truly need real Electron.
+- **Storybook responsive/Chromatic validation:** Do not prove responsive snapshots by only resizing `iframe.html`; that bypasses Storybook/Chromatic viewport mode configuration. If a story depends on a breakpoint (wide gutters, mobile, touch), pin an explicit `parameters.chromatic.modes[*].viewport`, mirror it with story `globals.viewport` for local viewing, and validate through the Storybook manager or an equivalent Chromatic-mode check. Add a play/static contract when a missing mode would silently snapshot the wrong UI.
 - Only use `validateApiKeys()` in tests that actually make AI API calls.
 
 ## Tool: todo_write
diff --git a/src/browser/components/ChatPane/ChatPane.tsx b/src/browser/components/ChatPane/ChatPane.tsx
index b907b7e74d..2679a4ae17 100644
--- a/src/browser/components/ChatPane/ChatPane.tsx
+++ b/src/browser/components/ChatPane/ChatPane.tsx
@@ -1065,11 +1065,19 @@ const ChatPaneContent: React.FC<ChatPaneContentProps> = (props) => {
             // In manual reading mode, anchoring should preserve the user's viewport
             // when async highlights/diagrams above the fold settle.
             style={autoScroll ? AUTO_SCROLL_TRANSCRIPT_STYLE : undefined}
-            className="h-full overflow-x-hidden overflow-y-auto p-[15px] leading-[1.5] break-words whitespace-pre-wrap"
+            // The named `transcript` container is what the sticky plan TOC queries
+            // for visibility — using a container query rather than a viewport media
+            // query means sidebars opening/closing correctly hide the TOC even when
+            // the viewport width is unchanged. See `.plan-toc-aside` in globals.css.
+            className="@container/transcript h-full overflow-x-hidden overflow-y-auto p-[15px] leading-[1.5] break-words whitespace-pre-wrap"
           >
             <div
               className={cn(
-                chatTranscriptFullWidth ? "w-full" : "max-w-4xl mx-auto",
+                // `plan-toc-aware` opts only the centered max-w transcript into the
+                // sticky plan TOC layout. In `chatTranscriptFullWidth` mode the plan
+                // already fills the available width, so the TOC would either
+                // overlap content or get clipped by `overflow-x-hidden`.
+                chatTranscriptFullWidth ? "w-full" : "plan-toc-aware max-w-4xl mx-auto",
                 (showTranscriptHydrationPlaceholder || showEmptyTranscriptPlaceholder) && "h-full"
               )}
             >
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
new file mode 100644
index 0000000000..b98963b636
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { useRef } from "react";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+
+import { installDom } from "../../../../../tests/ui/dom";
+import { PlanTableOfContents } from "./PlanTableOfContents";
+import type { PlanHeading } from "./extractPlanHeadings";
+
+/**
+ * Renders the PlanTableOfContents against a hand-rolled DOM that contains real
+ * <h1>/<h2>/<h3> elements. We test the click → scrollIntoView wiring here
+ * (instead of inside ProposePlanToolCall.test.tsx) because sibling test files
+ * mock MarkdownCore at file scope; those mocks make Streamdown render plain text
+ * without heading tags, which would break index-based DOM lookups.
+ */
+function HarnessRenderer({ entries, title }: { entries: PlanHeading[]; title?: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  return (
+    <div>
+      <PlanTableOfContents entries={entries} contentRef={ref} title={title} />
+      <div ref={ref} data-testid="plan-body">
+        <h1>Intro</h1>
+        <p>...</p>
+        <h2>First section</h2>
+        <p>...</p>
+        <h2>Second section</h2>
+        <p>...</p>
+        <h3>Nested</h3>
+      </div>
+    </div>
+  );
+}
+
+describe("PlanTableOfContents", () => {
+  let cleanupDom: (() => void) | null = null;
+
+  beforeEach(() => {
+    cleanupDom = installDom();
+  });
+
+  afterEach(() => {
+    cleanup();
+    cleanupDom?.();
+    cleanupDom = null;
+  });
+
+  test("returns null when there are fewer than two visible (h2-h4) entries", () => {
+    // A lone h1 produces zero list entries (h1 is reserved for the heading)
+    // and would leave a TOC with only a title — useless for navigation.
+    const view = render(<HarnessRenderer entries={[{ renderIndex: 0, level: 1, text: "Only" }]} />);
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("ignores deeply nested headings (h5/h6) for display", () => {
+    const view = render(
+      <HarnessRenderer
+        entries={[
+          { renderIndex: 0, level: 5, text: "Too deep one" },
+          { renderIndex: 1, level: 6, text: "Too deep two" },
+        ]}
+      />
+    );
+    // Both entries are filtered out as too-deep, leaving 0 visible — TOC hidden.
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("filters h1 entries out of the navigation list (they live in the heading)", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="My Plan" />);
+
+    // h2 entries remain as navigable buttons; h1 does not.
+    expect(view.getByRole("button", { name: "First section" })).toBeDefined();
+    expect(view.getByRole("button", { name: "Second section" })).toBeDefined();
+    expect(view.queryByRole("button", { name: "Intro" })).toBeNull();
+  });
+
+  test("renders the supplied title as the TOC heading", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 2, text: "A" },
+      { renderIndex: 1, level: 2, text: "B" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="My Plan Title" />);
+    const toc = view.getByTestId("plan-toc");
+    expect(toc.textContent).toContain("My Plan Title");
+    // Without any h1 in entries, the heading should NOT be a clickable button.
+    expect(view.queryByRole("button", { name: "My Plan Title" })).toBeNull();
+  });
+
+  test("clicking the TOC heading scrolls to the plan's h1 when one exists", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Plan Title From Markdown" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="Plan Title From Markdown" />);
+
+    const headings = Array.from(view.container.querySelectorAll<HTMLElement>("h1, h2, h3"));
+    const scrollCalls: Array<{ target: HTMLElement; options: ScrollIntoViewOptions }> = [];
+    for (const heading of headings) {
+      heading.scrollIntoView = ((options: ScrollIntoViewOptions) => {
+        scrollCalls.push({ target: heading, options });
+      }) as HTMLElement["scrollIntoView"];
+    }
+
+    fireEvent.click(view.getByRole("button", { name: "Plan Title From Markdown" }));
+    expect(scrollCalls).toHaveLength(1);
+    expect(scrollCalls[0].target).toBe(headings[0]); // the h1
+  });
+
+  test("scrolls the correct rendered heading into view when an entry is clicked", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+      { renderIndex: 3, level: 3, text: "Nested" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} />);
+
+    const headings = Array.from(view.container.querySelectorAll<HTMLElement>("h1, h2, h3"));
+    expect(headings).toHaveLength(4);
+
+    const scrollCalls: Array<{ target: HTMLElement; options: ScrollIntoViewOptions }> = [];
+    for (const heading of headings) {
+      heading.scrollIntoView = ((options: ScrollIntoViewOptions) => {
+        scrollCalls.push({ target: heading, options });
+      }) as HTMLElement["scrollIntoView"];
+    }
+
+    fireEvent.click(view.getByRole("button", { name: "Second section" }));
+
+    expect(scrollCalls).toHaveLength(1);
+    expect(scrollCalls[0].target).toBe(headings[2]);
+    // Top alignment ensures the heading lands just below the scrollport edge.
+    expect(scrollCalls[0].options.block).toBe("start");
+  });
+
+  test("normalizes indentation so the shallowest visible level sits at column 0", () => {
+    // With h1 reserved for the heading, h2 (the shallowest visible) should
+    // render at data-level=1, and h3 at data-level=2.
+    const view = render(
+      <HarnessRenderer
+        entries={[
+          { renderIndex: 0, level: 1, text: "Title" },
+          { renderIndex: 1, level: 2, text: "Section" },
+          { renderIndex: 2, level: 3, text: "Subsection" },
+        ]}
+      />
+    );
+
+    const items = view.container.querySelectorAll<HTMLElement>(".plan-toc-item");
+    expect(items).toHaveLength(2);
+    expect(items[0].dataset.level).toBe("1");
+    expect(items[1].dataset.level).toBe("2");
+  });
+});
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
new file mode 100644
index 0000000000..79e8c9f703
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -0,0 +1,142 @@
+import React from "react";
+import { cn } from "@/common/lib/utils";
+import { TooltipIfPresent } from "@/browser/components/Tooltip/Tooltip";
+import type { PlanHeading } from "./extractPlanHeadings";
+
+/**
+ * Sticky table of contents rendered alongside a plan in the chat transcript.
+ *
+ * Layout:
+ * - At intermediate widths the left gutter shows only sideways hint text so
+ *   users can discover that widening the transcript reveals the TOC.
+ * - When the transcript container is wide enough, CSS reveals the same sticky
+ *   left-gutter nav (see `.plan-toc-aside` in globals.css). The sticky container
+ *   follows the user while the plan is on screen, then naturally scrolls away
+ *   once the plan exits the viewport.
+ *
+ * Heading navigation is index-based: each entry stores its position among ALL
+ * h1..h6 elements the plan renders, so clicking a TOC item does
+ * `container.querySelectorAll("h1,h2,h3,h4,h5,h6")[renderIndex].scrollIntoView()`.
+ * This avoids touching the shared markdown rehype pipeline just for plan TOC.
+ */
+export interface PlanTableOfContentsProps {
+  /** Heading entries extracted from the plan markdown, in document order. */
+  entries: PlanHeading[];
+  /**
+   * Ref to a DOM container whose subtree owns the rendered plan headings.
+   * Must be a stable ancestor of the markdown output for `scrollIntoView` to
+   * locate the right element.
+   */
+  contentRef: React.RefObject<HTMLElement | null>;
+  /**
+   * Heading rendered at the top of the TOC. Defaults to "Contents".
+   *
+   * The plan title is the natural label for a plan TOC, so we let the host
+   * surface it here — that conserves vertical space (no separate "CONTENTS"
+   * label *and* an h1 list entry) and tightens the visual hierarchy: the
+   * title sits at column 0, h2 entries align with it, and h3+ are indented
+   * under their parent h2.
+   */
+  title?: string;
+  className?: string;
+}
+
+const HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+const DEFAULT_HEADING = "Contents";
+
+export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) => {
+  // h1 is reserved for the TOC's heading (the plan title), so it never appears
+  // as a list entry — but it still consumes a renderIndex because the rendered
+  // DOM still contains an <h1>. h5/h6 are also hidden as visual noise.
+  const visibleEntries = props.entries.filter((entry) => entry.level >= 2 && entry.level <= 4);
+  if (visibleEntries.length < 2) {
+    // A TOC with 0 or 1 entries adds visual chrome without navigation value.
+    // (Note: this check intentionally excludes the title, since the title is
+    // a single label, not a navigable destination on its own.)
+    return null;
+  }
+
+  // Normalize indentation: anchor the shallowest visible level at column 0 so
+  // a plan that starts at "###" doesn't look uniformly indented.
+  const minLevel = Math.min(...visibleEntries.map((entry) => entry.level));
+
+  const handleNavigate = (renderIndex: number) => {
+    const container = props.contentRef.current;
+    if (!container) return;
+    const headings = container.querySelectorAll<HTMLElement>(HEADING_SELECTOR);
+    const target = headings.item(renderIndex);
+    // `scrollIntoView` is not implemented by happy-dom in unit tests; the guard
+    // keeps tests from crashing while still exercising the lookup path.
+    if (target && typeof target.scrollIntoView === "function") {
+      target.scrollIntoView({ block: "start" });
+    }
+  };
+
+  // Use the supplied title when non-blank; fall back to "Contents" otherwise.
+  // Treat "  " as blank — a whitespace-only title would render as an empty
+  // heading line and look broken.
+  const trimmedTitle = props.title?.trim();
+  const headingText = trimmedTitle && trimmedTitle.length > 0 ? trimmedTitle : DEFAULT_HEADING;
+  // If the plan's source markdown begins with an h1, clicking the TOC heading
+  // jumps to that h1 (the natural "top of plan" target). Otherwise the heading
+  // is a static label — there's nothing meaningful to scroll to.
+  const titleHeadingEntry = props.entries.find((entry) => entry.level === 1);
+
+  return (
+    <aside
+      className={cn("plan-toc-aside", props.className)}
+      aria-label="Plan contents"
+      // At intermediate widths CSS shows only the sideways hint; at wide widths
+      // it hides the hint and reveals the sticky nav in the same left gutter.
+      // The aside itself stays pointer-events:none so margin clicks fall through
+      // to transcript chrome; only the inner nav becomes interactive.
+      data-testid="plan-toc"
+    >
+      <div className="plan-toc-compact-hint" aria-hidden="true">
+        Expand to see ToC
+      </div>
+      <nav className="plan-toc" data-testid="plan-toc-nav">
+        {titleHeadingEntry ? (
+          <TooltipIfPresent tooltip={headingText} side="right" align="start">
+            <button
+              type="button"
+              className="plan-toc-heading plan-toc-heading-link"
+              onClick={() => handleNavigate(titleHeadingEntry.renderIndex)}
+            >
+              {headingText}
+            </button>
+          </TooltipIfPresent>
+        ) : (
+          <div className="plan-toc-heading">{headingText}</div>
+        )}
+        <ul className="plan-toc-list">
+          {visibleEntries.map((entry) => (
+            <li
+              key={entry.renderIndex}
+              className="plan-toc-item"
+              data-level={entry.level - minLevel + 1}
+            >
+              {/*
+               * Wrap with TooltipIfPresent so users can see the full heading
+               * in one place even when the side TOC wraps long text across
+               * multiple lines in the gutter.
+               *
+               * `side="right"` keeps the tooltip from drifting off the left
+               * edge of the transcript — the toc lives in the left gutter.
+               */}
+              <TooltipIfPresent tooltip={entry.text} side="right" align="start">
+                <button
+                  type="button"
+                  className="plan-toc-link"
+                  onClick={() => handleNavigate(entry.renderIndex)}
+                >
+                  {entry.text}
+                </button>
+              </TooltipIfPresent>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </aside>
+  );
+};
diff --git a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
index be85905d3d..2c4143b57f 100644
--- a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
+++ b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
@@ -1,3 +1,5 @@
+import { waitFor, within } from "@storybook/test";
+
 import type { AppStory } from "@/browser/stories/meta.js";
 import { appMeta, AppWithMocks } from "@/browser/stories/meta.js";
 import { setupSimpleChatStory } from "@/browser/stories/helpers/chatSetup";
@@ -8,6 +10,20 @@ import { STABLE_TIMESTAMP } from "@/browser/stories/mocks/workspaces";
 const meta = { ...appMeta, title: "App/Chat/Tools/ProposePlan" };
 export default meta;
 
+const PLAN_TOC_CHROMATIC_VIEWPORT = { width: 1600, height: 900 } as const;
+const PLAN_TOC_CHROMATIC_MODES = {
+  "dark-wide": { theme: "dark", viewport: PLAN_TOC_CHROMATIC_VIEWPORT },
+} as const;
+
+function isChromaticRuntime(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  const chromaticRuntimeFlag = (window as Window & { chromatic?: boolean }).chromatic;
+  return /Chromatic/i.test(window.navigator.userAgent) || chromaticRuntimeFlag === true;
+}
+
 /**
  * Story showing a propose_plan tool call with Plan UI.
  * Tests the plan card rendering with icon action buttons at the bottom.
@@ -180,6 +196,129 @@ export const ProposePlanMobile: AppStory = {
   },
 };
 
+/**
+ * Wide-viewport story that exercises the sticky plan TOC.
+ *
+ * The TOC lives in an absolutely-positioned `<aside>` outside the centered
+ * `max-w-4xl` transcript column, and is gated by a container query on the
+ * transcript scrollport. At desktop (1280px) viewport the gate stays closed;
+ * the `wide` viewport (1600px) gives the scrollport enough room to reveal
+ * the TOC alongside the plan.
+ */
+export const ProposePlanWithTableOfContents: AppStory = {
+  render: () => (
+    <AppWithMocks
+      setup={() =>
+        setupSimpleChatStory({
+          workspaceId: "ws-plan-toc",
+          messages: [
+            createUserMessage("msg-1", "Plan a multi-section refactor with deep structure.", {
+              historySequence: 1,
+              timestamp: STABLE_TIMESTAMP - 300000,
+            }),
+            createAssistantMessage("msg-2", "Here is the plan with a navigable outline:", {
+              historySequence: 2,
+              timestamp: STABLE_TIMESTAMP - 290000,
+              toolCalls: [
+                createProposePlanTool(
+                  "call-plan-toc",
+                  `# Authentication Module Refactor
+
+## Overview
+
+Refactor the auth system to improve security, maintainability, and observability.
+
+## Tasks
+
+### Extract JWT utilities
+
+Move token generation and validation to a dedicated module.
+
+### Add refresh token support
+
+Implement secure refresh token rotation.
+
+### Improve password hashing
+
+Upgrade to Argon2id with proper salt rounds.
+
+### Add rate limiting
+
+Implement per-IP and per-user rate limits.
+
+## Implementation Order
+
+\`\`\`mermaid
+graph TD
+    A[Extract JWT utils] --> B[Add refresh tokens]
+    B --> C[Improve hashing]
+    C --> D[Add rate limiting]
+\`\`\`
+
+## Rollout
+
+### Staging soak
+
+Two-week staging soak with synthetic traffic.
+
+### Production cutover
+
+Blue/green cutover with automatic rollback on auth-error spikes.
+
+## Success Criteria
+
+- All existing tests pass
+- New tests for refresh token flow
+- Security audit passes
+- Performance benchmarks maintained`
+                ),
+              ],
+            }),
+          ],
+        })
+      }
+    />
+  ),
+  globals: {
+    viewport: { value: "wide", isRotated: false },
+  },
+  play: async ({ canvasElement }) => {
+    const shouldAssertFullToc =
+      isChromaticRuntime() || window.innerWidth >= PLAN_TOC_CHROMATIC_VIEWPORT.width;
+    if (!shouldAssertFullToc) {
+      return;
+    }
+
+    const canvas = within(canvasElement);
+    const toc = await canvas.findByTestId("plan-toc-nav");
+    await waitFor(() => {
+      // User rationale: this story exists to snapshot the full sticky TOC. Make
+      // Chromatic fail loudly if a viewport/mode regression captures only the compact hint.
+      if (window.getComputedStyle(toc).display === "none" || toc.getClientRects().length === 0) {
+        throw new Error("Expected the full plan TOC to be visible in the wide Storybook story");
+      }
+    });
+  },
+  parameters: {
+    viewport: { defaultViewport: "wide" },
+    chromatic: {
+      ...(appMeta.parameters?.chromatic ?? {}),
+      modes: PLAN_TOC_CHROMATIC_MODES,
+    },
+    docs: {
+      description: {
+        story:
+          "Wide-viewport rendering of a multi-section plan. The sticky " +
+          '"Contents" navigation appears in the left gutter beside the plan ' +
+          "card, anchored to the plan's vertical bounds via `position: sticky` " +
+          "inside an absolutely-positioned `<aside>`. " +
+          "Visibility is purely CSS-driven (container query + visibility class) " +
+          "so toggling the plan tool expanded/collapsed produces no layout jank.",
+      },
+    },
+  },
+};
+
 /**
  * Story showing a propose_plan with a code block containing long horizontal content.
  * Tests that code blocks wrap correctly instead of overflowing the container.
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
new file mode 100644
index 0000000000..0219217f8a
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -0,0 +1,322 @@
+import { describe, expect, test } from "bun:test";
+import { extractPlanHeadings } from "./extractPlanHeadings";
+
+describe("extractPlanHeadings", () => {
+  test("returns empty array for empty input", () => {
+    expect(extractPlanHeadings("")).toEqual([]);
+  });
+
+  test("extracts ATX headings with correct level + text", () => {
+    const md = `# Title\n\nintro\n\n## Section A\n\nbody\n\n### Subsection\n\nmore`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title" },
+      { renderIndex: 1, level: 2, text: "Section A" },
+      { renderIndex: 2, level: 3, text: "Subsection" },
+    ]);
+  });
+
+  test("accepts trailing closing # markers on ATX headings", () => {
+    const md = `# Title #\n## With trailing ##`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title" },
+      { renderIndex: 1, level: 2, text: "With trailing" },
+    ]);
+  });
+
+  test("accepts ATX headings indented by up to three spaces", () => {
+    const md = ` ## One space\n  ### Two spaces\n   #### Three spaces\n    ##### Four-space code\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "One space" },
+      { renderIndex: 1, level: 3, text: "Two spaces" },
+      { renderIndex: 2, level: 4, text: "Three spaces" },
+      { renderIndex: 3, level: 2, text: "After" },
+    ]);
+  });
+
+  test("counts empty ATX headings so later renderIndex values stay aligned", () => {
+    const md = `#\n\n## Visible after blank heading`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 1, level: 2, text: "Visible after blank heading" },
+    ]);
+  });
+
+  test("strips inline formatting in heading text", () => {
+    const md = `# **Bold** and _italic_\n## With \`code\` inline\n### [Linked](https://example.com) heading\n#### ~~strike~~ through`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Bold and italic" },
+      { renderIndex: 1, level: 2, text: "With code inline" },
+      { renderIndex: 2, level: 3, text: "Linked heading" },
+      { renderIndex: 3, level: 4, text: "strike through" },
+    ]);
+  });
+
+  test("ignores hashtags without space after the markers", () => {
+    const md = `#nothashtag\n# Real heading`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Real heading" }]);
+  });
+
+  test("skips ATX-looking lines inside fenced code blocks", () => {
+    const md = `# Real heading\n\n\`\`\`markdown\n# Not a heading\n## Also not\n\`\`\`\n\n## After code`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Real heading" },
+      { renderIndex: 1, level: 2, text: "After code" },
+    ]);
+  });
+
+  test("handles tilde-fenced code blocks too", () => {
+    const md = `# Outer\n\n~~~\n# Not a heading\n~~~\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Outer" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("does not treat tilde fence as closing a backtick fence", () => {
+    // The tilde line is content inside the backtick fence, not a closer.
+    const md = `\`\`\`\n# Hidden\n~~~\n# Still hidden\n\`\`\`\n\n# Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Visible" }]);
+  });
+
+  test("counts headings inside blockquote and list containers", () => {
+    const md = `> # Quoted\n\n- ## Listed\n\n## Real\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Quoted" },
+      { renderIndex: 1, level: 2, text: "Listed" },
+      { renderIndex: 2, level: 2, text: "Real" },
+      { renderIndex: 3, level: 2, text: "Next" },
+    ]);
+  });
+
+  test("does not count list-contained indented code as headings", () => {
+    const md = `-     # Not a heading\n1.     ## Not a heading either\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Visible" }]);
+  });
+
+  test("skips headings inside container-prefixed fenced code blocks", () => {
+    const md = `> \`\`\`markdown\n> # Hidden quoted heading\n> \`\`\`\n\n- \`\`\`markdown\n  ## Hidden list heading\n  \`\`\`\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Visible" }]);
+  });
+
+  test("recognizes setext h1 and h2 underlines", () => {
+    const md = `Title One\n=========\n\nbody\n\nTitle Two\n---------\n\nmore`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title One" },
+      { renderIndex: 1, level: 2, text: "Title Two" },
+    ]);
+  });
+
+  test("combines multi-line setext heading text", () => {
+    const md = `Foo\nBar\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Foo Bar" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("allows inline HTML paragraph text as a setext heading", () => {
+    const md = `<em>Roadmap</em>\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Roadmap" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("recognizes setext headings inside blockquotes", () => {
+    const md = `> Quoted title\n> ===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Quoted title" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("does not trim four-space-indented setext underlines into headings", () => {
+    const md = `Title\n    ---\n\n> Quoted title\n>     ===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
+  });
+
+  test("ignores markdown-looking headings inside raw HTML blocks", () => {
+    const md = `<div>\n# Hidden ATX\n\nAfter html\n---\n\n<section>\nTitle inside section\n---\n</section>\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "After html" },
+      { renderIndex: 1, level: 2, text: "Visible" },
+    ]);
+  });
+
+  test("does not treat raw HTML blocks followed by rules as setext headings", () => {
+    const md = `<div>Intro</div>\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
+  });
+
+  test("allows setext text that starts with list punctuation but is not a list", () => {
+    const md = `-foo\n---\n\n+bar\n===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "-foo" },
+      { renderIndex: 1, level: 1, text: "+bar" },
+      { renderIndex: 2, level: 2, text: "After" },
+    ]);
+  });
+
+  test("does not confuse thematic breaks with setext underlines", () => {
+    const md = `Some intro paragraph.\n\n---\n\n# Heading`;
+    // The `---` here is preceded by a blank line, so it's a thematic break, not
+    // a setext underline. The TOC should only contain the ATX heading.
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Heading" }]);
+  });
+
+  test("does not treat ordered-list items followed by rules as setext headings", () => {
+    const md = `1. Step one\n---\n\n2) Step two\n---\n\n## Actual heading`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Actual heading" }]);
+  });
+
+  test("does not count heading markup inside single-line non-rendered HTML contexts", () => {
+    const md = `<!-- <h2>Comment heading</h2> -->\n<script><h2>Script heading</h2></script>\n<style><h2>Style heading</h2></style>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("does not count HTML-looking headings inside script or style blocks", () => {
+    const md = `<script>\n<h2>Hidden script heading</h2>\n</script>\n\n<style>\n<h3>Hidden style heading</h3>\n</style>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("ignores headings inside unsupported raw HTML blocks", () => {
+    const md = `<custom><h2>Unsupported</h2></custom>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("counts raw HTML headings nested inside raw HTML blocks", () => {
+    const md = `<div>\n<h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inner HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("does not count tab-indented raw HTML headings outside HTML blocks", () => {
+    const md = `\t<h2>Code sample heading</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("does not count four-space-indented raw HTML headings outside HTML blocks", () => {
+    const md = `    <h2>Code sample heading</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("counts indented raw HTML headings inside raw HTML blocks", () => {
+    const md = `<div>\n    <h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inner HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("counts raw HTML heading tags with surrounding inline content", () => {
+    const md = `<h2>Intro</h2> trailing text\n<h2>A</h2><h3>B</h3>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "A" },
+      { renderIndex: 2, level: 3, text: "B" },
+      { renderIndex: 3, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("counts multiline raw HTML headings so later renderIndex values stay aligned", () => {
+    const md = `<h2>\nMultiline HTML heading\n</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Multiline HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("preserves text after nested inline tags inside raw HTML headings", () => {
+    const md = `<h2><em>Auth</em> rollout</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Auth rollout" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
+  test("counts implicitly closed raw HTML headings to preserve DOM index alignment", () => {
+    const md = `<h2>Implicit close\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Implicit close" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("stops implicitly closed raw HTML headings before the next heading tag", () => {
+    const md = `<h2>Intro<h3>Nested close\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Intro" },
+      { renderIndex: 1, level: 3, text: "Nested close" },
+      { renderIndex: 2, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("counts raw HTML headings inside pre blocks to preserve DOM index alignment", () => {
+    const md = `<pre><h2>Rendered from raw HTML</h2></pre>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Rendered from raw HTML" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("does not count escaped raw HTML headings inside inline code", () => {
+    const md = `Intro \`<h2>Code</h2>\` <h2>Real</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Real" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
+  test("counts raw HTML headings inside inline paragraph tokens", () => {
+    const md = `Intro <h2>Inline Section</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inline Section" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
+  test("counts raw HTML headings so renderIndex stays aligned", () => {
+    const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Markdown one" },
+      { renderIndex: 1, level: 2, text: "Inline HTML two" },
+      { renderIndex: 2, level: 3, text: "Markdown three" },
+    ]);
+  });
+
+  test("counts empty raw HTML headings so later renderIndex values stay aligned", () => {
+    const md = `<h2></h2>\n\n## After empty HTML heading`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 1, level: 2, text: "After empty HTML heading" },
+    ]);
+  });
+
+  test("preserves stable render indices across mixed content", () => {
+    const md = [
+      "# A",
+      "",
+      "para",
+      "",
+      "## B",
+      "",
+      "```",
+      "# inside-fence",
+      "```",
+      "",
+      "### C",
+      "",
+      "<h4>D</h4>",
+      "",
+      "##### E",
+    ].join("\n");
+
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "A" },
+      { renderIndex: 1, level: 2, text: "B" },
+      { renderIndex: 2, level: 3, text: "C" },
+      { renderIndex: 3, level: 4, text: "D" },
+      { renderIndex: 4, level: 5, text: "E" },
+    ]);
+  });
+});
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
new file mode 100644
index 0000000000..f1319c868b
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -0,0 +1,215 @@
+import { rawHtmlUsesOnlyAllowedTags } from "@/browser/features/Messages/MarkdownCore";
+import MarkdownIt from "markdown-it";
+
+/**
+ * A heading entry extracted from a plan's markdown source.
+ *
+ * `renderIndex` is the position of this heading among ALL h1..h6 elements
+ * Streamdown will render for the same content. We use it to look up the matching
+ * DOM node via `container.querySelectorAll("h1,h2,h3,h4,h5,h6")[renderIndex]`.
+ * Keeping the index aligned to the rendered DOM (rather than slug IDs) avoids
+ * mutating the shared markdown rehype pipeline just for plan TOC scrolling.
+ */
+export interface PlanHeading {
+  renderIndex: number;
+  /** 1-6, matching the rendered hN tag. */
+  level: number;
+  /** Plain text (markdown formatting stripped) shown in the TOC. */
+  text: string;
+}
+
+interface HtmlHeading {
+  level: number;
+  text: string;
+}
+
+const markdownParser = new MarkdownIt({ html: true, linkify: false, typographer: false });
+const HTML_HEADING_OPEN_PATTERN = /<h([1-6])\b[^>]*>/gi;
+const NON_RENDERED_HTML_BLOCK_PATTERN =
+  /<!--([\s\S]*?)(?:-->|$)|<\?(?:[\s\S]*?)(?:\?>|$)|<!\[CDATA\[(?:[\s\S]*?)(?:\]\]>|$)|<![A-Z][\s\S]*?(?:>|$)|<(?:script|style)(?=[\s>]|$)[\s\S]*?(?:<\/(?:script|style)\s*>|$)/gi;
+
+const IMPLICIT_HEADING_BOUNDARY_PATTERN =
+  /<h[1-6]\b[^>]*>|<\/?(?:address|article|aside|blockquote|details|dialog|div|dl|dt|dd|fieldset|figcaption|figure|footer|form|header|hr|li|main|nav|ol|p|pre|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/i;
+
+/**
+ * Extract heading entries from a plan's markdown source.
+ *
+ * Markdown block structure is delegated to markdown-it so ATX, setext,
+ * blockquote/list containers, indented code, and fenced code stay aligned with
+ * the rendered markdown. Raw HTML h1-h6 tags are counted separately because the
+ * renderer allows raw HTML and those tags also appear in the heading NodeList.
+ */
+export function extractPlanHeadings(markdown: string): PlanHeading[] {
+  if (!markdown) {
+    return [];
+  }
+
+  const tokens = markdownParser.parse(markdown, {});
+  const headings: PlanHeading[] = [];
+  let renderIndex = 0;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token.type === "heading_open") {
+      const level = parseHeadingLevel(token.tag);
+      const inline = tokens[i + 1];
+      const text = stripMarkdownFormatting(inline?.type === "inline" ? inline.content : "");
+      if (text) {
+        headings.push({ renderIndex, level, text });
+      }
+      // Empty markdown headings still render hN elements, so they consume an
+      // index even when they do not produce a useful TOC entry.
+      renderIndex += 1;
+      continue;
+    }
+
+    if (token.type === "inline" && tokens[i - 1]?.type !== "heading_open") {
+      const children = token.children ?? [];
+      if (children.some((child) => child.type === "html_inline")) {
+        const inlineHtml = reconstructInlineHtml(children);
+        for (const htmlHeading of extractHtmlHeadings(inlineHtml)) {
+          if (htmlHeading.text) {
+            headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
+          }
+          renderIndex += 1;
+        }
+      }
+      continue;
+    }
+
+    if (token.type === "html_block" || token.type === "html_inline") {
+      for (const htmlHeading of extractHtmlHeadings(token.content)) {
+        if (htmlHeading.text) {
+          headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
+        }
+        // Empty raw HTML headings still render hN elements, so they consume an
+        // index even when they do not produce a useful TOC entry.
+        renderIndex += 1;
+      }
+    }
+  }
+
+  return headings;
+}
+
+interface InlineTokenChild {
+  type: string;
+  content: string;
+}
+
+function reconstructInlineHtml(children: InlineTokenChild[]): string {
+  const openTags: string[] = [];
+  let html = "";
+
+  for (const child of children) {
+    if (child.type === "html_inline") {
+      html += child.content;
+      updateInlineHtmlStack(openTags, child.content);
+      continue;
+    }
+
+    if (child.type === "text" && openTags.length > 0) {
+      html += child.content;
+    }
+  }
+
+  return html;
+}
+
+function updateInlineHtmlStack(openTags: string[], rawHtml: string): void {
+  const tagPattern = /<\s*(\/)?\s*([A-Za-z][A-Za-z0-9:-]*)\b[^>]*(\/)?\s*>/g;
+  let match = tagPattern.exec(rawHtml);
+  while (match) {
+    const tagName = match[2].toLowerCase();
+    const isClosingTag = match[1] != null;
+    const isSelfClosing = match[3] != null || /<[^>]*\/\s*>$/.test(match[0]);
+
+    if (isClosingTag) {
+      const openIndex = openTags.lastIndexOf(tagName);
+      if (openIndex >= 0) {
+        openTags.splice(openIndex, 1);
+      }
+    } else if (!isSelfClosing && !/<\/\s*[A-Za-z][A-Za-z0-9:-]*\s*>/.test(match[0])) {
+      openTags.push(tagName);
+    }
+
+    match = tagPattern.exec(rawHtml);
+  }
+}
+
+function parseHeadingLevel(tag: string): number {
+  const level = Number(tag.replace(/^h/i, ""));
+  return level >= 1 && level <= 6 ? level : 1;
+}
+
+function extractHtmlHeadings(html: string): HtmlHeading[] {
+  if (!rawHtmlUsesOnlyAllowedTags(html)) {
+    return [];
+  }
+
+  const renderedHtml = html.replace(NON_RENDERED_HTML_BLOCK_PATTERN, "");
+  const headings: HtmlHeading[] = [];
+  HTML_HEADING_OPEN_PATTERN.lastIndex = 0;
+
+  let match = HTML_HEADING_OPEN_PATTERN.exec(renderedHtml);
+  while (match) {
+    const level = parseInt(match[1], 10);
+    const contentStart = match.index + match[0].length;
+    const contentEnd = findHtmlHeadingContentEnd(renderedHtml, contentStart, level);
+
+    headings.push({
+      level,
+      text: stripMarkdownFormatting(
+        renderedHtml.slice(contentStart, contentEnd).replace(/<[^>]+>/g, "")
+      ),
+    });
+
+    HTML_HEADING_OPEN_PATTERN.lastIndex = Math.max(contentEnd, contentStart);
+    match = HTML_HEADING_OPEN_PATTERN.exec(renderedHtml);
+  }
+
+  return headings;
+}
+
+function findHtmlHeadingContentEnd(html: string, contentStart: number, level: number): number {
+  const remaining = html.slice(contentStart);
+  const explicitClose = new RegExp(`</h${level}\\s*>`, "i").exec(remaining);
+  const implicitBoundary = IMPLICIT_HEADING_BOUNDARY_PATTERN.exec(remaining);
+  const explicitCloseIndex = explicitClose?.index;
+  const implicitBoundaryIndex = implicitBoundary?.index;
+
+  if (
+    implicitBoundaryIndex != null &&
+    (explicitCloseIndex == null || implicitBoundaryIndex < explicitCloseIndex)
+  ) {
+    return contentStart + implicitBoundaryIndex;
+  }
+
+  if (explicitCloseIndex != null) {
+    return contentStart + explicitCloseIndex;
+  }
+
+  return html.length;
+}
+
+/**
+ * Lightweight inline-formatting stripper used only for TOC display text. Not a
+ * full markdown parser — markdown-it has already handled block structure; this
+ * only normalizes raw HTML heading text and a few markdown-ish inline remnants.
+ */
+function stripMarkdownFormatting(text: string): string {
+  return text
+    .replace(/\\([\\`*_{}\x5B\]()#+\-.!|~])/g, "$1") // unescape \*  \[ etc.
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // ![alt](src)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // [label](href)
+    .replace(/`([^`]+)`/g, "$1") // `code`
+    .replace(/\*\*([^*]+)\*\*/g, "$1") // **bold**
+    .replace(/__([^_]+)__/g, "$1") // __bold__
+    .replace(/\*([^*]+)\*/g, "$1") // *italic*
+    .replace(/(?<!\w)_([^_]+)_(?!\w)/g, "$1") // _italic_ (avoid mid-word matches)
+    .replace(/~~([^~]+)~~/g, "$1") // ~~strike~~
+    .replace(/<[^>]+>/g, "") // stray inline HTML tags
+    .replace(/\s+/g, " ")
+    .trim();
+}
diff --git a/src/browser/features/Tools/ProposePlanToolCall.test.tsx b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
index 7d9d38b8d5..a7748e6288 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.test.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
@@ -569,4 +569,61 @@ describe("ProposePlanToolCall", () => {
     expect(summaryMessage.parts?.[0]?.text).toContain("*Plan file preserved at:*");
     expect(summaryMessage.parts?.[0]?.text).toContain(PLAN_PATH);
   });
+
+  test("renders a plan table of contents derived from the plan's markdown headings", () => {
+    // Note: we deliberately don't assert against rendered <h1>/<h2> elements here
+    // because some sibling test files mock MarkdownCore at file scope (file-scope
+    // module mocks persist across files in this runner). The TOC's source of truth
+    // is the markdown TEXT, not the rendered DOM, so this assertion stays robust.
+    const planContent = [
+      "# Title",
+      "",
+      "intro paragraph",
+      "",
+      "## Section A",
+      "",
+      "body",
+      "",
+      "## Section B",
+      "",
+      "more",
+    ].join("\n");
+
+    const view = renderCompletedPlan({
+      result: { success: true, planPath: PLAN_PATH, planContent },
+    });
+
+    const toc = view.getByTestId("plan-toc");
+    expect(toc.textContent).toContain("Title");
+    expect(toc.textContent).toContain("Section A");
+    expect(toc.textContent).toContain("Section B");
+
+    // Each entry is a real <button>, so the user can drive navigation with the
+    // keyboard. The dedicated PlanTableOfContents.test.tsx verifies the
+    // scrollIntoView wiring directly.
+    expect(view.getByRole("button", { name: "Section A" })).toBeDefined();
+    expect(view.getByRole("button", { name: "Section B" })).toBeDefined();
+  });
+
+  test("does not render a plan TOC for plans with fewer than two visible headings", () => {
+    // PLAN_CONTENT only has one heading ("# My Plan"), so the TOC should not appear.
+    const view = renderCompletedPlan();
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("does not render a plan TOC while annotate mode is active", () => {
+    // Need at least two h2+ entries; h1 is reserved for the TOC's heading
+    // (the plan title) and never shows up as a list item.
+    const planContent = "# A\n\nbody\n\n## B\n\nmore\n\n## C\n\nmore";
+    const view = renderCompletedPlan({
+      result: { success: true, planPath: PLAN_PATH, planContent },
+    });
+
+    // Sanity: TOC is visible before annotate mode.
+    expect(view.queryByTestId("plan-toc")).not.toBeNull();
+
+    fireEvent.click(view.getByRole("button", { name: "Annotate" }));
+
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
 });
diff --git a/src/browser/features/Tools/ProposePlanToolCall.tsx b/src/browser/features/Tools/ProposePlanToolCall.tsx
index e4c1765e69..80c8b7dfd7 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.tsx
@@ -17,6 +17,8 @@ import {
 import { useToolExpansion, getStatusDisplay, type ToolStatus } from "./Shared/toolUtils";
 import { MarkdownRenderer } from "../Messages/MarkdownRenderer";
 import { PlanAnnotationView } from "./PlanAnnotationView";
+import { extractPlanHeadings } from "./ProposePlan/extractPlanHeadings";
+import { PlanTableOfContents } from "./ProposePlan/PlanTableOfContents";
 import { Button } from "@/browser/components/Button/Button";
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/browser/components/Tooltip/Tooltip";
 import { IconActionButton, type ButtonConfig } from "../Messages/MessageWindow";
@@ -178,6 +180,10 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
   const isImplementingRef = useRef(false);
   const isContinuingInAutoRef = useRef(false);
   const isMountedRef = useRef(true);
+  // Anchors the plan body so PlanTableOfContents can `querySelectorAll("h1,h2,h3...")`
+  // and `scrollIntoView` the matching rendered heading. Pointing at `plan-surface`
+  // also implicitly scopes lookups away from neighbouring tool calls/transcripts.
+  const planContentRef = useRef<HTMLDivElement>(null);
   const { api } = useAPI();
   const { agentId: currentAgentId } = useAgent();
   const isAutoMode = currentAgentId === "auto";
@@ -796,9 +802,16 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
     <div className={planBodyClassName}>{planContentBody}</div>
   );
 
+  // Show the table of contents only for normal markdown content. Annotate mode,
+  // raw text, and error states either have no headings or use a custom renderer,
+  // so a TOC there would be either empty or misleading.
+  const showToc = !errorMessage && !annotateMode && !showRaw && hasPlanContentInChat;
+  const tocEntries = showToc ? extractPlanHeadings(planContent) : [];
+
   // Shared plan UI content (used in both tool call and ephemeral preview modes)
   const planUI = (
     <div
+      ref={planContentRef}
       className={cn(
         "plan-surface rounded-md p-3 shadow-md",
         annotateMode && "ring-accent/30 ring-1"
@@ -902,11 +915,24 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
     </div>
   );
 
+  // Layout container that positions the TOC affordances alongside the plan. The
+  // `plan-toc-layout` class establishes `position: relative` so CSS can place a
+  // compact hint or sticky TOC in the left gutter when the transcript container
+  // has enough horizontal room.
+  const planLayout = (
+    <div className="plan-toc-layout">
+      {planUI}
+      {showToc && (
+        <PlanTableOfContents entries={tocEntries} contentRef={planContentRef} title={planTitle} />
+      )}
+    </div>
+  );
+
   // Ephemeral preview mode: simple wrapper without tool container
   if (isEphemeralPreview) {
     return (
       <>
-        <div className={cn("px-4 py-2", className)}>{planUI}</div>
+        <div className={cn("px-4 py-2", className)}>{planLayout}</div>
         <PopoverError error={editorError.error} prefix="Failed to open editor" />
       </>
     );
@@ -922,7 +948,7 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
           <StatusIndicator status={status}>{statusDisplay}</StatusIndicator>
         </ToolHeader>
 
-        {expanded && <ToolDetails text={errorMessage ?? planContent}>{planUI}</ToolDetails>}
+        {expanded && <ToolDetails text={errorMessage ?? planContent}>{planLayout}</ToolDetails>}
 
         {modal}
       </ToolContainer>
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index e26e21db98..261fd35425 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1519,6 +1519,249 @@ code {
   border-radius: 0 4px 4px 0;
 }
 
+/* -----------------------------------------------------------------------------
+ * Plan Table of Contents
+ *
+ * `.plan-toc-layout` wraps the plan card so an absolutely-positioned `aside`
+ * (`.plan-toc-aside`) can break out to the LEFT of the centered `max-w-4xl`
+ * transcript column. The aside has three width states controlled by container
+ * queries on the `transcript` scrollport in ChatPane:
+ *
+ *   1. hidden on narrow/mobile widths where even a hint would crowd content,
+ *   2. a small sideways "Expand to see ToC" hint when there is some gutter but
+ *      not enough for the full nav, and
+ *   3. the full sticky TOC once the gutter can fit it.
+ *
+ * The full TOC stays entirely in the existing left gutter; it must not shift
+ * the plan card away from the transcript's centered column. The aside spans the
+ * current gutter and centers the nav inside it so wider gutters give the TOC
+ * more room instead of leaving unused space while headings wrap too early.
+ * --------------------------------------------------------------------------- */
+
+.plan-toc-layout {
+  position: relative;
+  --plan-toc-compact-column: 2.5rem;
+  --plan-toc-compact-right-gap: 0.5rem;
+  --plan-toc-wide-column: 11rem;
+  --plan-toc-wide-gutter: 11.25rem;
+}
+
+.plan-toc-aside {
+  display: none;
+  /* Anchor the toc's right edge to the plan card's left edge so it extends
+     leftward into the transcript's left gutter. The compact width only shows a
+     discoverability hint; the wide container query below expands this to the
+     full navigation column. */
+  position: absolute;
+  inset: 0 100% 0 auto;
+  box-sizing: border-box;
+  width: var(--plan-toc-compact-column);
+  padding-inline: 0;
+  /* Margin clicks should fall through to the underlying transcript chrome;
+     only the inner <nav> is interactive when the full TOC is visible. */
+  pointer-events: none;
+}
+
+.plan-toc-aside > .plan-toc {
+  pointer-events: auto;
+}
+
+.plan-toc-compact-hint {
+  position: sticky;
+  top: 1rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 7.25rem;
+  width: 0.75rem;
+  margin-left: calc(var(--plan-toc-compact-column) - 0.75rem - var(--plan-toc-compact-right-gap));
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: color-mix(in srgb, var(--color-muted-foreground) 85%, transparent);
+  font-size: 9px;
+  font-weight: 500;
+  letter-spacing: 0.03em;
+  line-height: 1;
+  text-transform: uppercase;
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+}
+
+.plan-toc {
+  display: none;
+  width: min(100%, var(--plan-toc-wide-column));
+  margin-inline: auto;
+  /* Sticky inside the aside keeps the toc anchored while the plan is on
+     screen. Once the user scrolls past the plan, the sticky bottoms out at
+     the aside's lower edge (which matches the plan's lower edge), so the
+     toc naturally scrolls away with the plan instead of trailing forever. */
+  position: sticky;
+  top: 1rem;
+  /* Bound the toc to the visible viewport so even very tall plans never push
+     it off-screen, and let it scroll internally for huge plans. */
+  max-height: calc(100dvh - 2rem);
+  overflow-y: auto;
+  font-family: var(--font-primary);
+  font-size: 11px;
+  line-height: 1.4;
+  color: color-mix(in srgb, var(--color-muted-foreground) 88%, var(--color-foreground) 12%);
+  padding: 4px 0;
+}
+
+.plan-toc-heading {
+  /* The plan title sits at the top of the TOC, in place of a separate
+     "CONTENTS" label. A light plan tint ties the side nav back to the plan
+     card without competing with the main content. */
+  font-size: 12px;
+  font-weight: 600;
+  color: color-mix(in srgb, var(--color-plan-mode) 58%, var(--color-foreground) 42%);
+  margin: 0 0 6px 0;
+  padding: 2px 0;
+  /* Let long plan titles wrap inside the gutter instead of wasting available
+     horizontal space and hiding useful context behind an ellipsis. */
+  white-space: normal;
+  overflow-wrap: anywhere;
+  /* Match the .plan-toc-link reset for the clickable variant. */
+  text-align: left;
+}
+
+.plan-toc-heading-link {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  font: inherit;
+  cursor: pointer;
+  display: block;
+  width: 100%;
+  border-radius: 3px;
+  transition:
+    color 120ms ease,
+    background-color 120ms ease;
+}
+
+.plan-toc-heading-link:hover {
+  color: color-mix(in srgb, var(--color-plan-mode) 70%, var(--color-foreground) 30%);
+  background: var(--color-hover);
+}
+
+.plan-toc-heading-link:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--color-accent) 60%, transparent);
+  outline-offset: 1px;
+}
+
+.plan-toc-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.plan-toc-item {
+  /* Per-level indentation. The component normalizes `data-level` so the
+     shallowest visible heading sits at 1.
+     With the plan title acting as the TOC heading (h1), h2 entries align flush
+     with the title (data-level=1 → 0 indent) and deeper headings get a small
+     step per level. */
+  --plan-toc-indent: 0;
+}
+
+.plan-toc-item[data-level="1"] {
+  --plan-toc-indent: 0;
+}
+.plan-toc-item[data-level="2"] {
+  --plan-toc-indent: 8px;
+}
+.plan-toc-item[data-level="3"] {
+  --plan-toc-indent: 16px;
+}
+.plan-toc-item[data-level="4"] {
+  --plan-toc-indent: 24px;
+}
+
+.plan-toc-link {
+  /* Render as a flush text link rather than a chunky button. Using the same
+     zero left padding as the title is what keeps h1 and h2 visually aligned. */
+  appearance: none;
+  background: transparent;
+  border: 0;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  display: block;
+  width: 100%;
+  padding: 2px 0 2px var(--plan-toc-indent);
+  border-radius: 3px;
+  white-space: normal;
+  overflow-wrap: anywhere;
+  transition:
+    color 120ms ease,
+    background-color 120ms ease;
+}
+
+.plan-toc-item[data-level="1"] .plan-toc-link {
+  font-weight: 500;
+  color: var(--color-foreground);
+}
+
+.plan-toc-link:hover {
+  color: var(--color-foreground);
+  background: var(--color-hover);
+}
+
+.plan-toc-link:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--color-accent) 60%, transparent);
+  outline-offset: 1px;
+}
+
+/* Give plan headings breathing room so scrollIntoView({block:"start"}) lands
+   them just below the transcript's top padding rather than flush against the
+   scrollport edge. Applies to the markdown render inside `.plan-content`. */
+.plan-content h1,
+.plan-content h2,
+.plan-content h3,
+.plan-content h4,
+.plan-content h5,
+.plan-content h6 {
+  scroll-margin-top: 1rem;
+}
+
+/*
+ * Hint visibility. The transcript container is queried at its CONTENT box
+ * inline-size (padding excluded). The rail itself is a narrow text-only cue, but
+ * its invisible column is wider so the text sits in the gutter instead of
+ * touching the plan border.
+ */
+@container transcript (min-width: 56.25rem) {
+  .plan-toc-aware .plan-toc-aside {
+    display: block;
+  }
+}
+
+/*
+ * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
+ * the left gutter beside that centered column. The 78.5rem reveal point leaves
+ * enough mirrored gutter for the centered rail before overflow clipping can occur,
+ * including the 1600px wide Storybook viewport.
+ */
+@container transcript (min-width: 78.5rem) {
+  .plan-toc-aware .plan-toc-aside {
+    width: var(--plan-toc-wide-gutter);
+    padding-inline: 0;
+  }
+
+  .plan-toc-aware .plan-toc-compact-hint {
+    display: none;
+  }
+
+  .plan-toc-aware .plan-toc {
+    display: block;
+  }
+}
+
 [title]:hover::before {
   content: "";
   position: absolute;
diff --git a/src/node/services/agentSkills/builtInSkillContent.generated.ts b/src/node/services/agentSkills/builtInSkillContent.generated.ts
index 3f39493bf4..4e216c0f21 100644
--- a/src/node/services/agentSkills/builtInSkillContent.generated.ts
+++ b/src/node/services/agentSkills/builtInSkillContent.generated.ts
@@ -668,6 +668,7 @@ export const BUILTIN_SKILL_FILES: Record<string, Record<string, string>> = {
       "- **Use conditional rendering for testability:** Components like `AgentModePicker` use `{isOpen && <div>...}` instead of Radix Portal. This renders inline and works in happy-dom.",
       "- When adding new dropdown/popover components that need tests/ui coverage, prefer the conditional rendering pattern over Radix Portal.",
       "- E2E tests (tests/e2e) work with Radix but are slow (~2min startup); reserve for scenarios that truly need real Electron.",
+      "- **Storybook responsive/Chromatic validation:** Do not prove responsive snapshots by only resizing `iframe.html`; that bypasses Storybook/Chromatic viewport mode configuration. If a story depends on a breakpoint (wide gutters, mobile, touch), pin an explicit `parameters.chromatic.modes[*].viewport`, mirror it with story `globals.viewport` for local viewing, and validate through the Storybook manager or an equivalent Chromatic-mode check. Add a play/static contract when a missing mode would silently snapshot the wrong UI.",
       "- Only use `validateApiKeys()` in tests that actually make AI API calls.",
       "",
       "## Tool: todo_write",
diff --git a/tests/ui/storybook/budget.test.ts b/tests/ui/storybook/budget.test.ts
index 9d877c51e1..6ac9fdcfa2 100644
--- a/tests/ui/storybook/budget.test.ts
+++ b/tests/ui/storybook/budget.test.ts
@@ -5,7 +5,8 @@ import { join } from "node:path";
 const STORY_DIR = "src/browser/stories";
 const COLOCATED_STORY_DIRS = ["src/browser/components", "src/browser/features"];
 const MAX_SNAPSHOT_ENABLED_FILES = 70;
-const MAX_ESTIMATED_SNAPSHOTS = 300;
+// Includes the plan ToC wide-viewport story, which intentionally protects gutter-only UI.
+const MAX_ESTIMATED_SNAPSHOTS = 303;
 const STORY_EXPORT_PATTERN = /^export const \w+/gm;
 const SMOKE_MODE_PATTERN = /modes:\s*CHROMATIC_SMOKE_MODES/g;
 const INLINE_MODE_OBJECT_PATTERN = /modes:\s*{/g;
diff --git a/tests/ui/storybook/coverage.test.ts b/tests/ui/storybook/coverage.test.ts
index e2f7028def..f142d7b575 100644
--- a/tests/ui/storybook/coverage.test.ts
+++ b/tests/ui/storybook/coverage.test.ts
@@ -2,6 +2,9 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, readFileSync } from "node:fs";
 
 const STORY_DIR = "src/browser/stories";
+const PLAN_TOC_STORY_PATH =
+  "src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx";
+const PLAN_TOC_MIN_CHROMATIC_WIDTH = 1600;
 
 /** App-level integration allowlist — files that must exist with smoke coverage. */
 const REQUIRED_APP_STORIES = [
@@ -46,6 +49,25 @@ const hasSmokeStoryWithDualThemeCoverage = (content: string): boolean => {
   );
 };
 
+function getPlanTocChromaticWidth(content: string): number | null {
+  const viewportMatch = content.match(
+    /PLAN_TOC_CHROMATIC_VIEWPORT\s*=\s*\{\s*width:\s*(\d+),\s*height:\s*\d+\s*\}/
+  );
+  if (!viewportMatch?.[1]) {
+    return null;
+  }
+
+  return Number(viewportMatch[1]);
+}
+
+function hasPlanTocWideChromaticMode(content: string): boolean {
+  return (
+    /PLAN_TOC_CHROMATIC_MODES\s*=\s*\{[\s\S]*viewport:\s*PLAN_TOC_CHROMATIC_VIEWPORT/.test(
+      content
+    ) && /modes:\s*PLAN_TOC_CHROMATIC_MODES/.test(content)
+  );
+}
+
 describe("Storybook coverage contract", () => {
   describe("App stories", () => {
     for (const filename of REQUIRED_APP_STORIES) {
@@ -85,6 +107,19 @@ describe("Storybook coverage contract", () => {
     }
   });
 
+  describe("Story-specific visual contracts", () => {
+    test("plan ToC story pins a wide Chromatic viewport", () => {
+      const content = readFileSync(PLAN_TOC_STORY_PATH, "utf-8");
+
+      // This story validates gutter-only UI: the full ToC is hidden at Chromatic's
+      // default 1200px width, so it must carry an explicit wide mode.
+      expect(hasPlanTocWideChromaticMode(content)).toBe(true);
+      expect(getPlanTocChromaticWidth(content)).toBeGreaterThanOrEqual(
+        PLAN_TOC_MIN_CHROMATIC_WIDTH
+      );
+    });
+  });
+
   describe("Migrated files removed", () => {
     for (const filename of MIGRATED_APP_STORIES) {
       test(`${filename} does not exist in src/browser/stories`, () => {