feat(walkthrough): guided AI walkthrough for diffs, branches, and PRs (#2572)

A diff is ordered by file path, which is almost never the order in which a
change makes sense. This adds a Walkthrough surface that reorders it: the model
groups related hunks into stops, explains what each group changes about
behavior, and orders the stops so each builds on the last. It explains and
orders; judging code stays with the existing Review action.

Reviews uncommitted work (all, staged, unstaged), a branch against its base, or
a pull request. Generation is always user-initiated — nothing runs on a timer,
on a file change, or as a side effect of opening a panel.

Invariants worth preserving:

- Hunk identity is derived on the server and only there. Ids are content
  hashes, so an anchor that no longer resolves is proof the code it described
  changed, and staleness needs no heuristics. The client matches ids to ids and
  never recomputes them; two implementations would have to agree forever.
- The digest is never truncated. A diff that does not fit the model's context
  is refused with an actionable reason, because a walkthrough written against
  half a diff reads as confident and is wrong.
- Nothing disappears. Lockfiles and other generated output are excluded from
  the model's input by name — never by size — and everything no stop covers is
  listed at the end, so "have I seen all of it" stays answerable.
- Cost is explicit. Results are content-addressed, so returning the working
  tree to an earlier state costs nothing; generation outlives its request, so a
  refresh detaches the client rather than discarding paid-for work, and only an
  explicit cancel stops it.

Supporting changes to shared modules:

- git: expose the existing getRangeDiff as GET /api/git
  listUntrackedPaths and getUntrackedDiffs. The latter resolve the repository
  once for a batch instead of per file, taking a panel
  ~340ms on an 80-file working tree.
- small-model: structured output across four wire forma
  and abort signal, and an onOverflow policy so an oversized prompt fails
  loudly instead of being silently clipped. A provider
  remembered so the prompt-side fallback goes first next time.
- models.dev metadata: surface structured_output as tri
  false blocks a model, a missing field does not, because the catalog omits it
  for roughly half of all models.

Desktop and tablet only: VS Code serves Git through its
these routes, and the mobile shell does not consume the surface registry.

Docs: packages/docs walkthrough page in English and all eight locales.

packages/ui/src/stores/useConfigStore.ts

@@ -441,6 +441,7 @@ interface ModelsDevModelEntry {
     reasoning?: boolean;
     temperature?: boolean;
     attachment?: boolean;
+    structured_output?: boolean;
     modalities?: {
         input?: string[];
         output?: string[];
@@ -577,6 +578,8 @@ const transformModelsDevResponse = (payload: unknown): Map<string, ModelMetadata
                 reasoning: typeof modelValue.reasoning === 'boolean' ? modelValue.reasoning : undefined,
                 temperature: typeof modelValue.temperature === 'boolean' ? modelValue.temperature : undefined,
                 attachment: typeof modelValue.attachment === 'boolean' ? modelValue.attachment : undefined,
+                structured_output:
+                    typeof modelValue.structured_output === 'boolean' ? modelValue.structured_output : undefined,
                 modalities: modelValue.modalities
                     ? {
                           input: isStringArray(modelValue.modalities.input) ? modelValue.modalities.input : undefined,

packages/ui/src/stores/useUIStore.ts

@@ -14,7 +14,7 @@ import { isWindowsArm64 } from '@/lib/platform';
 
 export type MainTab = 'chat' | 'plan' | 'git' | 'diff' | 'terminal' | 'files' | 'context' | 'diagram';
 export type PendingDiffScope = 'working' | 'staged' | 'turn';
-export type ContextPanelMode = 'diff' | 'file' | 'context' | 'plan' | 'chat' | 'preview' | 'browser' | 'git' | 'pr' | 'notes' | 'terminal';
+export type ContextPanelMode = 'diff' | 'walkthrough' | 'file' | 'context' | 'plan' | 'chat' | 'preview' | 'browser' | 'git' | 'pr' | 'notes' | 'terminal';
 export type MermaidRenderingMode = 'svg' | 'ascii';
 export type UserMessageRenderingMode = 'markdown' | 'plain';
 export type ChatRenderMode = 'sorted' | 'live';
@@ -288,7 +288,7 @@ const sanitizeContextPanelTabs = (tabs: unknown): ContextPanelTab[] => {
       touchedAt?: unknown;
     };
 
-    if (candidate.mode !== 'diff' && candidate.mode !== 'file' && candidate.mode !== 'context' && candidate.mode !== 'plan' && candidate.mode !== 'chat' && candidate.mode !== 'preview' && candidate.mode !== 'browser' && candidate.mode !== 'git' && candidate.mode !== 'pr' && candidate.mode !== 'notes' && candidate.mode !== 'terminal') {
+    if (candidate.mode !== 'diff' && candidate.mode !== 'walkthrough' && candidate.mode !== 'file' && candidate.mode !== 'context' && candidate.mode !== 'plan' && candidate.mode !== 'chat' && candidate.mode !== 'preview' && candidate.mode !== 'browser' && candidate.mode !== 'git' && candidate.mode !== 'pr' && candidate.mode !== 'notes' && candidate.mode !== 'terminal') {
       continue;
     }
 
@@ -654,6 +654,8 @@ interface UIStore {
   diffLayoutPreference: 'dynamic' | 'inline' | 'side-by-side';
   diffFileLayout: Record<string, 'inline' | 'side-by-side'>;
   diffWrapLines: boolean;
+  /** Width of the walkthrough table of contents, in pixels. */
+  walkthroughTocWidth: number;
   gitChangesViewMode: 'flat' | 'tree';
   isTimelineDialogOpen: boolean;
   isPromptNavigatorPanelOpen: boolean;
@@ -825,6 +827,7 @@ interface UIStore {
   setDiffLayoutPreference: (mode: 'dynamic' | 'inline' | 'side-by-side') => void;
   setDiffFileLayout: (filePath: string, mode: 'inline' | 'side-by-side') => void;
   setDiffWrapLines: (wrap: boolean) => void;
+  setWalkthroughTocWidth: (width: number) => void;
   setGitChangesViewMode: (mode: 'flat' | 'tree') => void;
   setMultiRunLauncherOpen: (open: boolean) => void;
   setTimelineDialogOpen: (open: boolean) => void;
@@ -966,6 +969,7 @@ export const useUIStore = create<UIStore>()(
         diffLayoutPreference: 'inline',
         diffFileLayout: {},
         diffWrapLines: false,
+        walkthroughTocWidth: 224,
         gitChangesViewMode: 'flat',
         isTimelineDialogOpen: false,
         isPromptNavigatorPanelOpen: false,
@@ -1828,6 +1832,10 @@ export const useUIStore = create<UIStore>()(
           set({ diffWrapLines: wrap });
         },
 
+        setWalkthroughTocWidth: (width) => {
+          set({ walkthroughTocWidth: Math.round(width) });
+        },
+
         setGitChangesViewMode: (mode) => {
           set({ gitChangesViewMode: mode });
         },
@@ -2434,6 +2442,7 @@ export const useUIStore = create<UIStore>()(
           recentEfforts: state.recentEfforts,
           diffLayoutPreference: state.diffLayoutPreference,
           diffWrapLines: state.diffWrapLines,
+          walkthroughTocWidth: state.walkthroughTocWidth,
           gitChangesViewMode: state.gitChangesViewMode,
           nativeNotificationsEnabled: state.nativeNotificationsEnabled,
           notificationMode: state.notificationMode,

packages/ui/src/stores/useWalkthroughStore.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import type { WalkthroughResult, WalkthroughSource } from '@/lib/walkthrough/types';
+
+const SOURCE: WalkthroughSource = { kind: 'working-tree', scope: 'all' };
+
+const result = (overrides: Partial<WalkthroughResult> = {}): WalkthroughResult => ({
+  source: SOURCE,
+  walkthrough: null,
+  hunks: [],
+  hunkCount: 0,
+  ...overrides,
+});
+
+const finished = result({
+  walkthrough: {
+    title: 'Change',
+    focus: '',
+    chapters: [{
+      id: 'chapter-1',
+      title: 'Data',
+      icon: 'doc',
+      blurb: '',
+      stops: [{ id: 'stop-1-1', title: 'A', hunkIds: ['h'], importance: 'normal', prose: 'p' }],
+    }],
+  },
+  generatedAt: '2026-08-02T00:00:00.000Z',
+});
+
+// Plain closures rather than mock helpers: bun's `mock()` is not typed with
+// vitest's `mockResolvedValue` family, and the repo already prefers this style.
+let readResult: WalkthroughResult = result();
+let generateCalls = 0;
+let releaseGeneration: (() => void) | undefined;
+let lastReadModel: string | undefined;
+let lastGenerateModel: string | undefined;
+
+mock.module('@/lib/walkthrough/api', () => ({
+  fetchWalkthrough: async (
+    _directory: string,
+    _source: WalkthroughSource,
+    options: { model?: string } = {},
+  ) => {
+    lastReadModel = options.model;
+    return readResult;
+  },
+  generateWalkthrough: async (
+    _directory: string,
+    _source: WalkthroughSource,
+    options: { model?: string } = {},
+  ) => {
+    generateCalls += 1;
+    lastGenerateModel = options.model;
+    return new Promise<WalkthroughResult>((resolve) => {
+      releaseGeneration = () => resolve(finished);
+    });
+  },
+  cancelWalkthroughGeneration: async () => {},
+}));
+mock.module('@/lib/runtime-switch', () => ({ getRuntimeKey: () => 'local' }));
+
+const { useWalkthroughStore } = await import('./useWalkthroughStore');
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('useWalkthroughStore — reattaching to a running generation', () => {
+  beforeEach(() => {
+    useWalkthroughStore.getState().reset();
+    readResult = result();
+    generateCalls = 0;
+    releaseGeneration = undefined;
+  });
+
+  afterEach(() => {
+    useWalkthroughStore.getState().reset();
+  });
+
+  test('a reload that finds work in progress ends up showing the finished result', async () => {
+    // What a refresh looks like: the read says a job is running, and the
+    // generation the client re-attaches to finishes a moment later.
+    readResult = result({ generating: true });
+
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+
+    expect(generateCalls).toBe(1);
+    expect(useWalkthroughStore.getState().getEntry('/repo', SOURCE).status).toBe('generating');
+
+    releaseGeneration?.();
+    await flush();
+
+    const entry = useWalkthroughStore.getState().getEntry('/repo', SOURCE);
+    expect(entry.status).toBe('ready');
+    expect(entry.result?.walkthrough?.title).toBe('Change');
+  });
+
+  test('does not re-attach when nothing is running', async () => {
+    readResult = result({ generating: false });
+
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+
+    expect(generateCalls).toBe(0);
+    expect(useWalkthroughStore.getState().getEntry('/repo', SOURCE).status).toBe('ready');
+  });
+
+  test('a load while generating does not overwrite the pending state', async () => {
+    readResult = result({ generating: true });
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+
+    expect(generateCalls).toBe(1);
+    expect(useWalkthroughStore.getState().getEntry('/repo', SOURCE).status).toBe('generating');
+  });
+});
+
+describe('useWalkthroughStore — model selection', () => {
+  beforeEach(() => {
+    useWalkthroughStore.getState().reset();
+    readResult = result();
+    generateCalls = 0;
+    lastReadModel = undefined;
+    lastGenerateModel = undefined;
+  });
+
+  afterEach(() => {
+    useWalkthroughStore.getState().reset();
+  });
+
+  test('sends the chosen model with both the read and the generation', async () => {
+    useWalkthroughStore.getState().selectModel('/repo', SOURCE, 'anthropic/claude-haiku-4-5');
+
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+    expect(lastReadModel).toBe('anthropic/claude-haiku-4-5');
+
+    void useWalkthroughStore.getState().generate('/repo', SOURCE);
+    await flush();
+    expect(lastGenerateModel).toBe('anthropic/claude-haiku-4-5');
+    releaseGeneration?.();
+    await flush();
+  });
+
+  test('clearing the choice falls back to whatever the server resolves', async () => {
+    useWalkthroughStore.getState().selectModel('/repo', SOURCE, 'anthropic/claude-haiku-4-5');
+    useWalkthroughStore.getState().selectModel('/repo', SOURCE, null);
+
+    await useWalkthroughStore.getState().load('/repo', SOURCE);
+    await flush();
+
+    expect(lastReadModel).toBe(undefined);
+  });
+
+  test('keeps choices apart per source', async () => {
+    const branch: WalkthroughSource = { kind: 'branch', baseRef: 'main', headRef: 'feature' };
+    useWalkthroughStore.getState().selectModel('/repo', SOURCE, 'anthropic/claude-haiku-4-5');
+
+    expect(useWalkthroughStore.getState().getSelectedModel("/repo", branch)).toBe(undefined);
+    expect(useWalkthroughStore.getState().getSelectedModel('/repo', SOURCE))
+      .toBe('anthropic/claude-haiku-4-5');
+  });
+});