feat(walkthrough): write walkthroughs in the reader's language

A guided explanation is only useful in a language the reader reads, so the
panel header gets a language picker alongside the model one, defaulting to
the interface language. Like the model, it is request state rather than a
setting: the language travels with the read and the generation, and the one
a walkthrough was written in is stored with it, so reopening a review
describes what is there instead of what a fresh one would be.

Only prose is translated. Hunk aliases resolve back to hunk ids and
icon/importance are validated against fixed English values, so a translated
one would be dropped by the normalizer — silently losing an anchor or a
style. Identifiers and paths stay as they appear in the code.

The language is part of the cache key, and a read now asks the cache for the
exact request it was given before falling back to the pointer. Without that
the panel answered a request to switch languages with the text it already
had, leaving the other language unused in the cache.

Alongside it:

- The answer budget is derived from the resolved model instead of a flat 24k.
  That number was the same for a 64k-context model and for one that admits to
  384k output tokens, and on the latter it was the only reason generation
  failed: the model spent the whole allowance reasoning and returned nothing.
  It is now min(96k, max(24k, a quarter of the context)) capped by the
  catalog's output limit, decided once so the input reserve and the request
  cannot drift apart.
- A read no longer offers Cancel. It is a few hundred milliseconds of git with
  nothing to cancel, and the button flickered on every model or language
  change. When the panel is showing a fallback, a banner names what is on
  screen versus what was asked for — only once the read has settled.
- The header keeps one 32px control height and drops its labels below 680px
  instead of squeezing them to two letters and an ellipsis.

Docs and module documentation updated in every locale.

packages/web/server/lib/small-model/DOCUMENTATION.md

@@ -56,6 +56,11 @@ other runtime API.
   stays at the default overruns the context, and the failure looks like a
   truncation bug rather than a budgeting one. `describeSmallModel` takes
   `outputReserveTokens` so readiness checks agree with what generation will do.
+  It may be a **function** of `{ contextTokens, outputTokenLimit }` for callers
+  that want as much answer room as the resolved model allows — they cannot name
+  a number before knowing which model they got. The resolved value comes back as
+  `outputTokens`, which is what the caller should then request, so the reserve
+  and the request are the same number by construction.
 - Reasoning models can spend the entire output budget thinking and return
   nothing. That case (empty content with `finish_reason: 'length'`, or content
   empty while `reasoning_content` is populated) throws with

packages/web/server/lib/small-model/index.js

@@ -205,6 +205,18 @@ export function listAuthenticatedProviders() {
  * proxies especially), and treating "unknown" as "unsupported" would hide
  * models that work fine.
  */
+/**
+ * The reserve, resolved against the model that was actually picked.
+ *
+ * A caller that wants "as much answer room as this model allows" cannot state a
+ * number up front — it does not know which model it will get. Passing a
+ * function lets it decide once the limits are known, and keeps the reserve and
+ * the eventual request the same number by construction.
+ */
+const resolveReserveTokens = (outputReserveTokens, limits) => (
+  typeof outputReserveTokens === 'function' ? outputReserveTokens(limits) : outputReserveTokens
+);
+
 export async function describeSmallModel({ directory, preferredProviderID, preferredModelID, outputReserveTokens, overrideModel } = {}) {
   const auth = readAuthFile();
   const catalog = await getModelCatalog().catch(() => ({}));
@@ -224,11 +236,20 @@ export async function describeSmallModel({ directory, preferredProviderID, prefe
   if (!resolved) return resolved;
 
   const entry = catalog?.[resolved.providerID]?.models?.[resolved.modelID];
-  const { maxChars, contextTokens, contextKnown } = getModelInputCharBudget({
+  const outputTokenLimit = Number(entry?.limit?.output) > 0 ? Number(entry.limit.output) : null;
+  // Two passes: the first only to learn the context, which a caller-supplied
+  // reserve function needs before it can answer.
+  const { contextTokens, contextKnown } = getModelInputCharBudget({
     catalog,
     providerID: resolved.providerID,
     modelID: resolved.modelID,
-    outputReserveTokens,
+  });
+  const reserveTokens = resolveReserveTokens(outputReserveTokens, { contextTokens, outputTokenLimit });
+  const { maxChars } = getModelInputCharBudget({
+    catalog,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    outputReserveTokens: reserveTokens,
   });
 
   return {
@@ -236,7 +257,10 @@ export async function describeSmallModel({ directory, preferredProviderID, prefe
     inputCharBudget: maxChars,
     contextTokens,
     contextKnown,
+    // What the caller should ask for, so the request and the reserve above
+    // cannot drift apart.
+    outputTokens: Number(reserveTokens) > 0 ? Number(reserveTokens) : null,
     structuredOutput: typeof entry?.structured_output === 'boolean' ? entry.structured_output : null,
-    outputTokenLimit: Number(entry?.limit?.output) > 0 ? Number(entry.limit.output) : null,
+    outputTokenLimit,
   };
 }

packages/web/server/lib/small-model/index.test.js

@@ -214,6 +214,29 @@ describe('output budget and input reserve', () => {
 
     expect(described.inputCharBudget).toBe(304_000);
   });
+
+  // A caller that wants "as much room as this model allows" cannot name a
+  // number before knowing which model it got, so it hands over the decision.
+  it('lets the reserve be decided from the resolved model\'s limits', async () => {
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/roomy' } });
+
+    const described = await describeSmallModel({
+      directory: '/proj',
+      outputReserveTokens: ({ contextTokens, outputTokenLimit }) => Math.min(contextTokens / 10, outputTokenLimit),
+    });
+
+    // 100k context, 8k output limit -> 8k reserved, leaving 92k tokens.
+    expect(described.outputTokens).toBe(8_000);
+    expect(described.inputCharBudget).toBe(92_000 * 4);
+  });
+
+  it('reports the reserve it used so the caller can request the same number', async () => {
+    readConfigLayers.mockReturnValue({ mergedConfig: { small_model: 'anthropic/unlisted' } });
+
+    const described = await describeSmallModel({ directory: '/proj', outputReserveTokens: 24_000 });
+
+    expect(described.outputTokens).toBe(24_000);
+  });
 });
 
 afterAll(() => {

packages/web/server/lib/walkthrough/DOCUMENTATION.md

@@ -22,6 +22,7 @@ has to ask for it.
 - `store.js` — content-addressed cache entries plus mutable pointers.
 - `pull-request.js` — PR diffs via the shared GitHub octokit helper.
 - `model-settings.js` — the feature's own model override.
+- `languages.js` — the languages the prose may be written in.
 - `index.js` — orchestration.
 - `routes.js` — `/api/walkthrough*`.
 
@@ -117,6 +118,53 @@ model picker, only shows providers with a usable login. The in-panel picker on a
 blocked walkthrough writes this setting too, so recovering from a refusal never
 silently changes the model behind commit messages.
 
+## Output language
+
+A walkthrough its reader cannot read is worth nothing, so the prose language is
+a per-review choice in the panel header, defaulting to the interface language.
+Like the model it is request state rather than a setting: it travels as
+`language` on `GET` and `POST`, and it is not persisted, because the language a
+walkthrough was written in is already recorded in its cache entry and returned
+as `language` — which makes it the better default on reopen than any remembered
+preference. Resolution is *explicit choice → language of what is on screen →
+interface locale*.
+
+Only prose is translated. Hunk aliases are keys that resolve back to hunk ids,
+and `icon`/`importance` are validated against fixed English values, so a
+translated one is dropped by the normalizer — losing an anchor or a style
+silently. The prompt says so explicitly.
+
+`languages.js` owns the accepted tags; they match the UI's `Locale` union, and
+anything else — unknown, malformed, absent — resolves to English rather than
+failing the request. The default language adds no instruction at all, since the
+system prompt is already English.
+
+The language is part of the cache key. Without that, asking for a translation
+would be answered with the untranslated entry that was already there; with it,
+switching language and back returns the earlier walkthrough for free, exactly as
+switching models does.
+
+The read follows the same rule: `GET` builds the cache key for the language and
+model being asked for and answers from that entry when it exists, before
+consulting the pointer. The pointer alone was not enough — it records what was
+generated here *last*, which after a switch is the answer to a different
+question, and the panel kept showing the English review while the picker said
+Ukrainian and the Ukrainian one sat unused in the cache. The key is computed
+from the diff the read already parsed, so this costs one file read and no extra
+git work.
+
+Falling back to the pointer still happens when nothing exists in the requested
+language: an English review beats an empty panel, and the response says which
+language it is in so the panel can say so too — it shows a banner naming what is
+on screen versus what was asked for, and only once a read has settled, because
+claiming something is missing while still looking for it is the same flicker in
+another place. Serving an entry makes it the last
+one shown here, so the pointer follows it — otherwise a regeneration would
+re-author from a walkthrough the reader is not looking at.
+
+Attaching to a running job still ignores the language of the second request,
+because the job already has one. That matches how the model behaves.
+
 ## Structured output, and what happens when it is refused
 
 `structured_output: false` in the catalog blocks generation up front. A
@@ -145,18 +193,36 @@ for a wasted first call.
 
 ## Output budget
 
-Generation asks for 24k output tokens (capped per model by the catalog), and the
-input budget reserves exactly that much. A walkthrough itself is only a few
-thousand tokens of JSON — the headroom exists because reasoning models spend the
-same budget thinking first and return nothing when it runs out. When that still
-happens, `code: 'output-exhausted'` reports it as what it is: this model cannot
-finish this job, so pick another or review a narrower scope.
+A walkthrough itself is only a few thousand tokens of JSON. The budget exists
+for what comes before it: reasoning models spend the same allowance thinking and
+return nothing when it runs out, which is a bill for no answer.
+
+The ask is therefore derived from the resolved model rather than fixed:
+`min(96k, max(24k, a quarter of the context))`, then capped by the catalog's
+`limit.output`. A flat 24k was the same number for a 64k-context model and for
+one that admits to 384k output tokens and a million of context — and on the
+latter it was the only reason generation failed.
+
+The bounds are not arbitrary. The **same number is reserved from the input
+allowance**, so the ceiling and the context share are what stop a generous
+answer budget from eating the diff it is supposed to describe; the 24k floor is
+what this feature always asked for, so no model gets less room than before. A
+model whose own `limit.output` is below the floor gets its limit, because asking
+for more than a provider allows is rejected by some and ignored by others.
+
+`describeSmallModel` decides this once — the walkthrough hands it the rule as a
+function and reads back `outputTokens` — so the reserve and the request cannot
+drift apart.
+
+When a model exhausts even that, `code: 'output-exhausted'` reports it as what
+it is: this model cannot finish this job, so pick another or review a narrower
+scope.
 
 ## Caching and staleness
 
 **Cache entries** (`entries/<sha256>.json`) are immutable and content-addressed.
 The key covers walkthrough version, prompt version, repo root, source, provider,
-model, and every file's path/status/hunk-ids. The key is computed from the
+model, output language, and every file's path/status/hunk-ids. The key is computed from the
 *current* diff, so a hit means the walkthrough was written about exactly this
 code; there is no freshness question to ask of an entry, because staleness is a
 miss. Returning the working tree to an earlier state therefore costs nothing.
@@ -167,6 +233,11 @@ cannot: which walkthrough was last shown here, and has the code moved since. A
 pointer whose entry has been evicted reads as "no walkthrough" — truthful, and
 the next generation overwrites it.
 
+A pointer is a *fallback*, not the primary lookup. A read that can name the
+entry it wants — same diff, same model, same language — goes straight to it and
+moves the pointer there; the pointer answers only when nothing matches the
+request exactly.
+
 Regeneration is manual and re-authors rather than merges: the previous
 walkthrough goes into the prompt as prose so the model can keep what is still
 true, with its anchors deliberately stripped so everything is re-anchored
@@ -275,9 +346,11 @@ be used for this: it re-runs the whole git pipeline.
 
 ## Routes
 
-- `GET /api/walkthrough?directory&source` — last walkthrough, the current hunk
-  index, staleness, and `readiness`. Never generates.
-- `POST /api/walkthrough/generate` — `{ directory, source, force }`. Survives
+- `GET /api/walkthrough?directory&source&model&language` — last walkthrough, the
+  current hunk index, staleness, and `readiness`. Never generates. `language`
+  matters here because readiness is measured against the prompt that would be
+  sent, and the language instruction is part of it.
+- `POST /api/walkthrough/generate` — `{ directory, source, force, model, language }`. Survives
   client disconnects; a concurrent call for the same source joins the running
   job.
 - `GET /api/walkthrough/progress?directory&source` — the current stage, or

packages/web/server/lib/walkthrough/index.js

@@ -2,6 +2,7 @@ import { getRepositoryRoot } from '../git/service.js';
 import { describeSmallModel, generateSmallModelText } from '../small-model/index.js';
 import { buildDigest } from './digest.js';
 import { indexHunks } from './hunks.js';
+import { normalizeLanguage } from './languages.js';
 import { buildPrompt, JSON_SHAPE_INSTRUCTION } from './prompt.js';
 import { normalizeWalkthrough, parseModelJson, responseSchema } from './schema.js';
 import {
@@ -41,11 +42,41 @@ const generationTimeoutMs = (hunkCount) => Math.min(
   GENERATION_TIMEOUT_MAX_MS,
   GENERATION_TIMEOUT_BASE_MS + Math.max(0, hunkCount) * GENERATION_TIMEOUT_PER_HUNK_MS,
 );
-// A full walkthrough is a few thousand tokens of JSON, but reasoning models
-// spend the same budget thinking first and return nothing if it runs out. The
-// reserve subtracted from the input budget matches this exactly, so a bigger
-// answer allowance costs input room rather than overrunning the context.
-const MAX_OUTPUT_TOKENS = 24_000;
+// A full walkthrough is a few thousand tokens of JSON. The budget exists for
+// what comes before it: reasoning models spend the same allowance thinking and
+// return nothing when it runs out, which is a bill for no answer.
+//
+// So the ask is derived from the model rather than fixed. A flat 24k was the
+// same number for a 64k-context model and for one that admits to 384k output
+// tokens, and on the latter it was the only reason generation failed.
+//
+// The reserve subtracted from the input budget is the same number, always: ask
+// for more than was reserved and a large diff overruns the context mid-answer,
+// which surfaces as a truncation bug rather than a budgeting one.
+const MIN_OUTPUT_TOKENS = 24_000;
+// A ceiling, because the reserve is taken out of the input allowance: a model
+// that would let us ask for 384k tokens of answer would also let us spend a
+// third of a million tokens of context reserving them, and no walkthrough needs
+// that much thinking.
+const MAX_OUTPUT_TOKENS = 96_000;
+// Above this share of the context, the reserve starts costing more diff than
+// the extra room is worth.
+const OUTPUT_CONTEXT_SHARE = 0.25;
+
+/**
+ * Answer allowance for a specific model: as much as it admits it can emit,
+ * bounded by a share of its context and never below what this feature always
+ * asked for.
+ */
+const walkthroughOutputTokens = ({ contextTokens, outputTokenLimit }) => {
+  const wanted = Math.min(
+    MAX_OUTPUT_TOKENS,
+    Math.max(MIN_OUTPUT_TOKENS, Math.floor((Number(contextTokens) || 0) * OUTPUT_CONTEXT_SHARE)),
+  );
+  // A model whose own limit is below the floor gets its limit: asking for more
+  // than a provider allows is rejected outright by some and ignored by others.
+  return Number(outputTokenLimit) > 0 ? Math.min(wanted, Number(outputTokenLimit)) : wanted;
+};
 
 const fail = (message, statusCode, extra = {}) =>
   Object.assign(new Error(message), { statusCode, ...extra });
@@ -138,11 +169,11 @@ const modelLabel = (model) => `${model.providerID}/${model.modelID}`;
  */
 const resolveModel = (directory, explicitModel) => describeSmallModel({
   directory,
-  outputReserveTokens: MAX_OUTPUT_TOKENS,
+  outputReserveTokens: walkthroughOutputTokens,
   overrideModel: explicitModel || readWalkthroughModelOverride(),
 });
 
-export const __testing = { generationTimeoutMs };
+export const __testing = { generationTimeoutMs, walkthroughOutputTokens };
 
 /**
  * Current diff for a source, parsed into files and hunks.
@@ -204,10 +235,11 @@ const serializeHunks = (files) => files.flatMap((file) => file.hunks.map((hunk)
  * Read the last walkthrough for a source, resolved against the current diff.
  * Never generates and never spends tokens.
  */
-export async function getWalkthrough({ directory, source: rawSource, model: explicitModel }, deps = {}) {
+export async function getWalkthrough({ directory, source: rawSource, model: explicitModel, language: rawLanguage }, deps = {}) {
   const source = parseSource(rawSource);
   const repoRoot = await getRepositoryRoot(directory);
   const key = sourceKey(source);
+  const language = normalizeLanguage(rawLanguage);
 
   const pointer = readPointer(repoRoot, key);
   // One diff, one model lookup, both answers. These used to be separate
@@ -219,7 +251,7 @@ export async function getWalkthrough({ directory, source: rawSource, model: expl
   ]);
   const { files } = built;
   const hunkIndex = indexHunks(files);
-  const readiness = computeReadiness({ ...built, model, source });
+  const readiness = computeReadiness({ ...built, model, source, language });
 
   const base = {
     source,
@@ -229,7 +261,27 @@ export async function getWalkthrough({ directory, source: rawSource, model: expl
     generating: isGenerating(repoRoot, key),
   };
 
-  const entry = pointer ? readCachedWalkthrough(pointer.cacheKey) : null;
+  // Ask the cache for *this* request before falling back to the pointer.
+  //
+  // The pointer only knows which walkthrough was generated here last, which
+  // after a model or language switch is the answer to a different question:
+  // the panel would keep showing the English review while the picker said
+  // Ukrainian, even though the Ukrainian one was sitting in the cache. The key
+  // is computed from the diff this read already parsed, so this costs a file
+  // read and no git work at all.
+  const requestedKey = model
+    ? buildCacheKey({
+      repoRoot,
+      sourceKey: key,
+      providerID: model.providerID,
+      modelID: model.modelID,
+      language,
+      files,
+    })
+    : null;
+
+  const requested = requestedKey ? readCachedWalkthrough(requestedKey) : null;
+  const entry = requested ?? (pointer ? readCachedWalkthrough(pointer.cacheKey) : null);
   if (!entry) {
     // No pointer, or the pointer outlived its entry (eviction, manual cleanup).
     // "No walkthrough" is the truthful answer either way; the pointer is left
@@ -237,10 +289,26 @@ export async function getWalkthrough({ directory, source: rawSource, model: expl
     return { ...base, walkthrough: null };
   }
 
+  // Showing it makes it the last walkthrough shown here, and a regeneration
+  // re-authors from whatever the reader is actually looking at. Only written
+  // when it moved, so an unchanged read stays a pure read.
+  if (requested && pointer?.cacheKey !== requestedKey) {
+    writePointer(repoRoot, key, {
+      repoRoot,
+      sourceKey: key,
+      cacheKey: requestedKey,
+      generatedAt: requested.generatedAt,
+    });
+  }
+
   return {
     ...base,
     walkthrough: entry.walkthrough,
     model: entry.model,
+    // The language the text on screen is actually written in, which is not
+    // necessarily the one being asked for now. The picker needs the difference:
+    // it is what lets it default to what produced this rather than to a setting.
+    language: entry.language ?? null,
     generatedAt: entry.generatedAt,
     ...resolveAgainstCurrent(entry.walkthrough, hunkIndex),
   };
@@ -254,7 +322,7 @@ export async function getWalkthrough({ directory, source: rawSource, model: expl
  * answers need the same diff, and computing it twice doubled the git work on
  * every panel open.
  */
-function computeReadiness({ model, digest, files, fileCount, hunkCount, generatedFileCount, source }) {
+function computeReadiness({ model, digest, files, fileCount, hunkCount, generatedFileCount, source, language }) {
   if (!model) return { ready: false, reason: 'no-model' };
 
   if (hunkCount === 0) {
@@ -265,7 +333,10 @@ function computeReadiness({ model, digest, files, fileCount, hunkCount, generate
     return { ready: false, reason, model, generatedFileCount };
   }
 
-  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source });
+  // Built with the same language the generation would use: the instruction is
+  // part of the prompt, so a readiness answer computed without it would be
+  // measuring a request nobody is going to send.
+  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source, language });
   const requiredChars = prompt.length + system.length;
 
   if (model.structuredOutput === false) {
@@ -292,10 +363,11 @@ function computeReadiness({ model, digest, files, fileCount, hunkCount, generate
  * which also means returning to a previous state of the working tree costs
  * nothing.
  */
-export async function generateWalkthrough({ directory, source: rawSource, force = false, model: explicitModel }, deps = {}) {
+export async function generateWalkthrough({ directory, source: rawSource, force = false, model: explicitModel, language: rawLanguage }, deps = {}) {
   const source = parseSource(rawSource);
   const repoRoot = await getRepositoryRoot(directory);
   const key = sourceKey(source);
+  const language = normalizeLanguage(rawLanguage);
 
   // Attach to a running job rather than starting a second one. A user who
   // refreshed and pressed the button again wants the answer, not two bills.
@@ -303,7 +375,7 @@ export async function generateWalkthrough({ directory, source: rawSource, force
   if (existing) return existing.promise;
 
   const controller = new AbortController();
-  const promise = runGeneration({ directory, source, repoRoot, key, force, explicitModel, signal: controller.signal }, deps)
+  const promise = runGeneration({ directory, source, repoRoot, key, force, explicitModel, language, signal: controller.signal }, deps)
     .finally(() => {
       if (jobs.get(jobKey(repoRoot, key))?.controller === controller) {
         jobs.delete(jobKey(repoRoot, key));
@@ -314,7 +386,7 @@ export async function generateWalkthrough({ directory, source: rawSource, force
   return promise;
 }
 
-async function runGeneration({ directory, source, repoRoot, key, force, explicitModel, signal }, deps) {
+async function runGeneration({ directory, source, repoRoot, key, force, explicitModel, language, signal }, deps) {
 
   const model = await resolveModel(directory, explicitModel);
   if (!model) {
@@ -335,6 +407,7 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     sourceKey: key,
     providerID: model.providerID,
     modelID: model.modelID,
+    language,
     files,
   });
 
@@ -353,6 +426,7 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
         source,
         walkthrough: cached.walkthrough,
         model: cached.model,
+        language: cached.language ?? null,
         generatedAt: cached.generatedAt,
         fromCache: true,
         hunks: serializeHunks(files),
@@ -374,7 +448,7 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     }
   }
 
-  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough });
+  const { prompt, system } = buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough, language });
 
   if (model.structuredOutput === false) {
     throw fail(
@@ -392,7 +466,8 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     responseSchema: options.responseSchema,
     onOverflow: 'error',
     timeoutMs: generationTimeoutMs(hunkCount),
-    maxOutputTokens: MAX_OUTPUT_TOKENS,
+    // The number the input budget was already reduced by, not a fresh guess.
+    maxOutputTokens: model.outputTokens ?? MIN_OUTPUT_TOKENS,
     signal,
   });
 
@@ -486,6 +561,7 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     repoRoot,
     sourceKey: key,
     model: { providerID: model.providerID, modelID: model.modelID, source: model.source },
+    language,
     walkthrough,
   };
 
@@ -498,6 +574,7 @@ async function runGeneration({ directory, source, repoRoot, key, force, explicit
     source,
     walkthrough,
     model: entry.model,
+    language,
     generatedAt,
     fromCache: false,
     hunks: serializeHunks(files),

packages/web/server/lib/walkthrough/jobs.test.js

@@ -137,6 +137,25 @@ describe('generation jobs', () => {
       .toEqual({ cancelled: false });
   });
 
+  // The reserve and the request must be the same number: asking for more than
+  // was subtracted from the input allowance overruns the context mid-answer.
+  it('requests exactly the budget the model resolution reserved', async () => {
+    describeSmallModel.mockResolvedValue({
+      providerID: 'opencode-go',
+      modelID: 'deepseek-v4-flash',
+      source: 'config',
+      inputCharBudget: 1_000_000,
+      structuredOutput: true,
+      outputTokens: 96_000,
+      outputTokenLimit: 384_000,
+    });
+    generateSmallModelText.mockResolvedValue({ text: RESPONSE });
+
+    await generateWalkthrough({ directory: '/repo', source: SOURCE });
+
+    expect(generateSmallModelText.mock.calls.at(-1)[0].maxOutputTokens).toBe(96_000);
+  });
+
   it('serves the cache once the job has finished, without calling the model again', async () => {
     generateSmallModelText.mockResolvedValue({ text: RESPONSE });
 
@@ -171,6 +190,34 @@ describe('generation timeout', () => {
   });
 });
 
+// The failure this replaced: a flat 24k ask, spent entirely on reasoning by a
+// model that advertises 384k output tokens and a million of context. The ceiling
+// exists because the same number is reserved out of the input allowance.
+describe('output budget', () => {
+  const { walkthroughOutputTokens } = walkthroughTesting;
+
+  it('asks a roomy model for far more than the old fixed budget', () => {
+    expect(walkthroughOutputTokens({ contextTokens: 1_000_000, outputTokenLimit: 384_000 })).toBe(96_000);
+  });
+
+  it('never asks for more than the model says it can emit', () => {
+    expect(walkthroughOutputTokens({ contextTokens: 202_752, outputTokenLimit: 32_768 })).toBe(32_768);
+  });
+
+  it('keeps the reserve to a share of the context', () => {
+    expect(walkthroughOutputTokens({ contextTokens: 200_000, outputTokenLimit: 64_000 })).toBe(50_000);
+  });
+
+  it('holds the old floor for a small or uncatalogued model', () => {
+    expect(walkthroughOutputTokens({ contextTokens: 64_000, outputTokenLimit: null })).toBe(24_000);
+    expect(walkthroughOutputTokens({ contextTokens: 0, outputTokenLimit: null })).toBe(24_000);
+  });
+
+  it('yields to a model whose own limit is below the floor', () => {
+    expect(walkthroughOutputTokens({ contextTokens: 128_000, outputTokenLimit: 8_192 })).toBe(8_192);
+  });
+});
+
 describe('generation stages', () => {
   beforeEach(() => {
     // Without this the previous suite's cache entry is a hit for the same

packages/web/server/lib/walkthrough/language.test.js

@@ -0,0 +1,226 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEMP_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'walkthrough-language-'));
+process.env.OPENCHAMBER_DATA_DIR = TEMP_DATA_DIR;
+
+vi.mock('../git/service.js', () => ({
+  getRepositoryRoot: vi.fn(async () => '/repo'),
+  getDiff: vi.fn(),
+  getRangeDiff: vi.fn(),
+  getUntrackedDiffs: vi.fn(async () => []),
+  listUntrackedPaths: vi.fn(async () => []),
+}));
+vi.mock('../small-model/index.js', () => ({
+  describeSmallModel: vi.fn(),
+  generateSmallModelText: vi.fn(),
+}));
+
+const { normalizeLanguage, languageName } = await import('./languages.js');
+const { buildPrompt } = await import('./prompt.js');
+const { buildCacheKey } = await import('./store.js');
+const { generateWalkthrough, getWalkthrough } = await import('./index.js');
+const { describeSmallModel, generateSmallModelText } = await import('../small-model/index.js');
+const { getDiff } = await import('../git/service.js');
+
+const SOURCE = { kind: 'working-tree', scope: 'all' };
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,1 +1,2 @@
++const added = true;
+`;
+
+const RESPONSE = JSON.stringify({
+  title: 'Change',
+  focus: 'why',
+  chapters: [{
+    title: 'Data',
+    icon: 'doc',
+    blurb: '',
+    stops: [{ title: 'Adds a flag', hunks: ['h1'], importance: 'normal', prose: 'It adds a flag.' }],
+  }],
+});
+
+const PROMPT_INPUT = {
+  digest: { files: [] },
+  fileCount: 1,
+  hunkCount: 1,
+  source: SOURCE,
+};
+
+const FILES = [{ path: 'src/a.ts', status: 'modified', hunks: [{ id: 'unstaged:src/a.ts:abcd1234' }] }];
+const keyFor = (language) => buildCacheKey({
+  repoRoot: '/repo',
+  sourceKey: 'working-tree:all',
+  providerID: 'anthropic',
+  modelID: 'claude-haiku-4-5',
+  language,
+  files: FILES,
+});
+
+describe('normalizeLanguage', () => {
+  it('accepts the tags the interface uses', () => {
+    expect(normalizeLanguage('uk')).toBe('uk');
+    expect(normalizeLanguage('zh-TW')).toBe('zh-TW');
+    expect(normalizeLanguage('pt-BR')).toBe('pt-BR');
+  });
+
+  it('tolerates case and separator drift from a platform locale', () => {
+    expect(normalizeLanguage('uk-UA')).toBe('uk');
+    expect(normalizeLanguage('pt_br')).toBe('pt-BR');
+    expect(normalizeLanguage('ja-JP')).toBe('ja');
+  });
+
+  // A language preference is about prose. Refusing to write a walkthrough over
+  // an unrecognised tag would be a worse answer than writing it in English.
+  it('falls back to English rather than failing', () => {
+    expect(normalizeLanguage('kl')).toBe('en');
+    expect(normalizeLanguage('')).toBe('en');
+    expect(normalizeLanguage(undefined)).toBe('en');
+    expect(normalizeLanguage({ toString: () => 'uk' })).toBe('en');
+  });
+
+  it('names languages in English, matching the language of the prompt', () => {
+    expect(languageName('uk')).toBe('Ukrainian');
+    expect(languageName('nope')).toBe('English');
+  });
+});
+
+describe('prompt language instruction', () => {
+  it('says nothing when the prompt language is already the output language', () => {
+    const { system } = buildPrompt({ ...PROMPT_INPUT, language: 'en' });
+    expect(system).not.toMatch(/Write all prose/);
+  });
+
+  it('asks for prose in the chosen language', () => {
+    const { system } = buildPrompt({ ...PROMPT_INPUT, language: 'uk' });
+    expect(system).toMatch(/Write all prose in Ukrainian/);
+  });
+
+  // Aliases are keys the server resolves back to hunk ids and icon/importance
+  // are validated against fixed English values, so a translated one is dropped
+  // by the normalizer — silently losing an anchor or a style.
+  it('holds back the parts that are not prose', () => {
+    const { system } = buildPrompt({ ...PROMPT_INPUT, language: 'ja' });
+    expect(system).toMatch(/Keep these in English exactly as given/);
+    expect(system).toMatch(/hunk aliases/);
+    expect(system).toMatch(/"importance"/);
+  });
+
+  it('defaults to English when no language is passed', () => {
+    expect(buildPrompt(PROMPT_INPUT).system).toBe(buildPrompt({ ...PROMPT_INPUT, language: 'en' }).system);
+  });
+});
+
+describe('cache key', () => {
+  // Without the language in the key, asking for a translation is answered with
+  // the untranslated entry that was already there.
+  it('separates walkthroughs written in different languages', () => {
+    expect(keyFor('uk')).not.toBe(keyFor('en'));
+  });
+
+  it('is stable for the same language', () => {
+    expect(keyFor('uk')).toBe(keyFor('uk'));
+  });
+});
+
+describe('generating in a language', () => {
+  beforeEach(() => {
+    fs.rmSync(path.join(TEMP_DATA_DIR, 'walkthroughs'), { recursive: true, force: true });
+    describeSmallModel.mockResolvedValue({
+      providerID: 'anthropic',
+      modelID: 'claude-haiku-4-5',
+      source: 'config',
+      inputCharBudget: 1_000_000,
+      structuredOutput: true,
+    });
+    getDiff.mockImplementation(async (_dir, options) => (options?.staged ? '' : PATCH));
+    generateSmallModelText.mockReset();
+    generateSmallModelText.mockResolvedValue({ text: RESPONSE });
+  });
+
+  afterAll(() => {
+    fs.rmSync(TEMP_DATA_DIR, { recursive: true, force: true });
+  });
+
+  it('sends the instruction and records the language with the result', async () => {
+    const result = await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+
+    expect(generateSmallModelText.mock.calls[0][0].system).toMatch(/Write all prose in Ukrainian/);
+    expect(result.language).toBe('uk');
+  });
+
+  it('does not serve one language from the other language cache entry', async () => {
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+    generateSmallModelText.mockClear();
+
+    const english = await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'en' });
+
+    expect(english.fromCache).toBeFalsy();
+    expect(generateSmallModelText).toHaveBeenCalledTimes(1);
+    expect(english.language).toBe('en');
+  });
+
+  // Switching away and back must not cost a second generation: the earlier
+  // walkthrough is still addressed by its own key.
+  it('returns the earlier language from cache when it is asked for again', async () => {
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'en' });
+    generateSmallModelText.mockClear();
+
+    const back = await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+
+    expect(back.fromCache).toBe(true);
+    expect(back.language).toBe('uk');
+    expect(generateSmallModelText).not.toHaveBeenCalled();
+  });
+
+  // The pointer only knows what was generated here last. After a language
+  // switch that is the answer to a different question, and reading it instead
+  // left the panel showing English while the picker said Ukrainian — with the
+  // Ukrainian walkthrough sitting unused in the cache.
+  it('reads back the walkthrough written in the language being asked for', async () => {
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'en' });
+    generateSmallModelText.mockClear();
+
+    const ukrainian = await getWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+
+    expect(ukrainian.language).toBe('uk');
+    expect(ukrainian.walkthrough).toBeTruthy();
+    expect(generateSmallModelText).not.toHaveBeenCalled();
+  });
+
+  it('switches back and forth without generating anything', async () => {
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' });
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'ja' });
+    generateSmallModelText.mockClear();
+
+    expect((await getWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' })).language).toBe('uk');
+    expect((await getWalkthrough({ directory: '/repo', source: SOURCE, language: 'ja' })).language).toBe('ja');
+    expect((await getWalkthrough({ directory: '/repo', source: SOURCE, language: 'uk' })).language).toBe('uk');
+    expect(generateSmallModelText).not.toHaveBeenCalled();
+  });
+
+  // Falling back is still right: an English review beats an empty panel, and
+  // the response says which language it is in so the panel can be honest.
+  it('falls back to the last walkthrough when none exists in that language', async () => {
+    await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'en' });
+
+    const korean = await getWalkthrough({ directory: '/repo', source: SOURCE, language: 'ko' });
+
+    expect(korean.walkthrough).toBeTruthy();
+    expect(korean.language).toBe('en');
+  });
+
+  it('treats an unknown language as English rather than failing the request', async () => {
+    const result = await generateWalkthrough({ directory: '/repo', source: SOURCE, language: 'kl' });
+
+    expect(result.language).toBe('en');
+    expect(generateSmallModelText.mock.calls[0][0].system).not.toMatch(/Write all prose/);
+  });
+});

packages/web/server/lib/walkthrough/languages.js

@@ -0,0 +1,59 @@
+// Language the walkthrough prose is written in.
+//
+// This is the server's own list rather than an import from the UI package: the
+// server cannot reach `packages/ui`, and the two lists answer different
+// questions anyway. The UI list is "which locales do we have a dictionary
+// for"; this one is "which languages may we ask a model to write in", and it
+// needs the English endonym-free name that goes into the prompt.
+//
+// The tags match the UI's `Locale` union so the picker can pass its own value
+// straight through. A tag we do not know resolves to English, which is exactly
+// what the feature did before the setting existed.
+
+export const DEFAULT_LANGUAGE = 'en';
+
+// Value is what the prompt says to write in. Naming the language in English
+// keeps the instruction in the same language as the rest of the system prompt,
+// which every model handles more reliably than a switch mid-sentence.
+const LANGUAGE_NAMES = {
+  en: 'English',
+  fr: 'French',
+  'zh-CN': 'Simplified Chinese',
+  'zh-TW': 'Traditional Chinese',
+  uk: 'Ukrainian',
+  es: 'Spanish',
+  'pt-BR': 'Brazilian Portuguese',
+  ko: 'Korean',
+  pl: 'Polish',
+  ja: 'Japanese',
+};
+
+/**
+ * Coerce a caller-supplied tag to one we support.
+ *
+ * Unknown, absent, and malformed all collapse to English rather than failing
+ * the request: the language is a preference about prose, and refusing to
+ * generate a walkthrough over one is a worse answer than writing it in English.
+ */
+export function normalizeLanguage(value) {
+  if (typeof value !== 'string' || !value) return DEFAULT_LANGUAGE;
+  if (Object.hasOwn(LANGUAGE_NAMES, value)) return value;
+
+  // Tolerate case and separator drift (`uk-UA`, `pt_br`) so a runtime that
+  // passes a platform locale does not silently fall back to English.
+  const normalized = value.toLowerCase().replace(/_/g, '-');
+  const match = Object.keys(LANGUAGE_NAMES).find((tag) => {
+    const lower = tag.toLowerCase();
+    return lower === normalized || normalized.startsWith(`${lower}-`);
+  });
+  if (match) return match;
+
+  const base = normalized.split('-')[0];
+  const baseMatch = Object.keys(LANGUAGE_NAMES).find((tag) => tag.toLowerCase() === base);
+  return baseMatch ?? DEFAULT_LANGUAGE;
+}
+
+/** English name of a normalized tag, for the prompt. */
+export function languageName(language) {
+  return LANGUAGE_NAMES[language] ?? LANGUAGE_NAMES[DEFAULT_LANGUAGE];
+}

packages/web/server/lib/walkthrough/prompt.js

@@ -1,3 +1,4 @@
+import { DEFAULT_LANGUAGE, languageName } from './languages.js';
 import { MAX_CHAPTERS, MAX_CHAPTER_TITLE_CHARS, MAX_HUNKS_PER_STOP, MAX_STOPS } from './schema.js';
 
 const SYSTEM = `You are writing a guided review of a code change for the engineer who is about to read it.
@@ -24,6 +25,21 @@ Rules:
 
 Respond with a single JSON object and nothing else. (Some providers refuse a structured-output request unless the word "json" appears in the request, which is why this is stated explicitly.)`;
 
+// A reader who cannot follow English prose gets nothing out of a walkthrough,
+// so the output language is the reader's, not the codebase's.
+//
+// Only prose is translated. Hunk aliases are keys the server resolves back to
+// hunk ids, and `icon`/`importance` are enums the normalizer validates against
+// fixed English values — translating either produces a walkthrough that drops
+// its anchors or loses its styling, silently and completely. Identifiers taken
+// from the diff stay verbatim for the same reason a translated function name
+// would be unsearchable.
+const languageInstruction = (language) => `
+
+Write all prose in ${languageName(language)}: the walkthrough title, the focus line, chapter titles and blurbs, and stop titles and prose. The reader of this review reads ${languageName(language)}.
+
+Keep these in English exactly as given, regardless of the prose language: hunk aliases (h1, h2, …), the "icon" values, and the "importance" values. Keep identifiers, file paths, and API names as they appear in the code — never translate them.`;
+
 const sizing = ({ fileCount, hunkCount }) => {
   const targetStops = Math.max(1, Math.min(MAX_STOPS, Math.round(hunkCount / 2.5) || 1));
   const targetChapters = hunkCount <= 4
@@ -65,7 +81,7 @@ export const JSON_SHAPE_INSTRUCTION = `
 Return ONLY a JSON object, with no prose around it and no markdown fences, in exactly this shape:
 {"title": string, "focus": string, "chapters": [{"title": string, "icon": "bug"|"wrench"|"path"|"flask"|"doc"|"gear", "blurb": string, "stops": [{"title": string, "hunks": [string], "importance": "critical"|"normal"|"context", "prose": string}]}]}`;
 
-export function buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough }) {
+export function buildPrompt({ digest, fileCount, hunkCount, source, previousWalkthrough, language = DEFAULT_LANGUAGE }) {
   const sourceLine = source.kind === 'working-tree'
     ? `Uncommitted local changes (${source.scope === 'all' ? 'staged and unstaged' : source.scope}).`
     : source.kind === 'branch'
@@ -79,5 +95,9 @@ ${previousWalkthroughSection(previousWalkthrough)}
 Change digest:
 ${JSON.stringify(digest)}`;
 
-  return { system: SYSTEM, prompt };
+  // The default language adds nothing: the system prompt is already English, so
+  // saying so would only spend context restating it.
+  const system = language === DEFAULT_LANGUAGE ? SYSTEM : `${SYSTEM}${languageInstruction(language)}`;
+
+  return { system, prompt };
 }

packages/web/server/lib/walkthrough/routes.js

@@ -41,6 +41,7 @@ export function registerWalkthroughRoutes(app, { getWalkthroughService }) {
           directory,
           source: readSource(req.query.source),
           model: typeof req.query.model === 'string' ? req.query.model : undefined,
+          language: typeof req.query.language === 'string' ? req.query.language : undefined,
         },
         { getPullRequestDiff },
       );
@@ -57,13 +58,19 @@ export function registerWalkthroughRoutes(app, { getWalkthroughService }) {
   app.post('/api/walkthrough/generate', async (req, res) => {
     try {
       const { generateWalkthrough, getPullRequestDiff } = await getWalkthroughService();
-      const { directory, source, force, model } = req.body || {};
+      const { directory, source, force, model, language } = req.body || {};
       if (!directory || typeof directory !== 'string') {
         return res.status(400).json({ error: 'directory is required' });
       }
 
       const result = await generateWalkthrough(
-        { directory, source, force: force === true, model: typeof model === 'string' ? model : undefined },
+        {
+          directory,
+          source,
+          force: force === true,
+          model: typeof model === 'string' ? model : undefined,
+          language: typeof language === 'string' ? language : undefined,
+        },
         { getPullRequestDiff },
       );
       if (clientIsGone(res)) return;

packages/web/server/lib/walkthrough/routes.test.js

@@ -14,11 +14,15 @@ describe('walkthrough routes', () => {
   let releaseJob;
   let job;
 
+  let lastArgs;
+
   const service = {
-    async getWalkthrough() {
+    async getWalkthrough(args) {
+      lastArgs = args;
       return { walkthrough: null, hunks: [], hunkCount: 0, generating: Boolean(job) };
     },
-    async generateWalkthrough() {
+    async generateWalkthrough(args) {
+      lastArgs = args;
       if (job) return job;
       job = new Promise((resolve) => {
         releaseJob = () => resolve({ walkthrough: { title: 'DONE' }, hunks: [], hunkCount: 1 });
@@ -40,6 +44,7 @@ describe('walkthrough routes', () => {
   beforeEach(async () => {
     job = null;
     releaseJob = undefined;
+    lastArgs = undefined;
     const app = express();
     app.use(express.json());
     registerWalkthroughRoutes(app, { getWalkthroughService: async () => service });
@@ -94,6 +99,35 @@ describe('walkthrough routes', () => {
     expect(job).toBeNull();
   });
 
+  // The language belongs to the request, not to a setting, so both the read
+  // and the generation have to carry it: readiness is computed from a prompt
+  // that contains the language instruction.
+  it('carries the requested language into the service', async () => {
+    await fetch(
+      `${base}/api/walkthrough?directory=/repo&language=uk&source=${encodeURIComponent(JSON.stringify(SOURCE))}`,
+    );
+    expect(lastArgs.language).toBe('uk');
+
+    const pending = fetch(`${base}/api/walkthrough/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ directory: '/repo', source: SOURCE, language: 'ja' }),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    releaseJob();
+    await pending;
+
+    expect(lastArgs.language).toBe('ja');
+  });
+
+  it('ignores a language that is not a string', async () => {
+    await fetch(
+      `${base}/api/walkthrough?directory=/repo&language[]=uk&source=${encodeURIComponent(JSON.stringify(SOURCE))}`,
+    );
+
+    expect(lastArgs.language).toBeUndefined();
+  });
+
   it('cancels through its own endpoint rather than a dropped connection', async () => {
     generate().catch(() => {});
     await new Promise((resolve) => setTimeout(resolve, 20));

packages/web/server/lib/walkthrough/schema.js

@@ -8,7 +8,7 @@ export const WALKTHROUGH_VERSION = 1;
 // Bumping this invalidates every cached walkthrough, which is the point: a
 // changed prompt produces different output and old entries would misrepresent
 // what the current code would say.
-export const PROMPT_VERSION = 2;
+export const PROMPT_VERSION = 3;
 
 export const MAX_CHAPTERS = 6;
 export const MAX_STOPS = 16;

packages/web/server/lib/walkthrough/store.js

@@ -78,7 +78,7 @@ const readJson = (filePath) => {
  * Content-addressed key. Every input that can change the output is in here:
  * change any of them and you get a miss rather than a stale hit.
  */
-export function buildCacheKey({ repoRoot, sourceKey, providerID, modelID, files }) {
+export function buildCacheKey({ repoRoot, sourceKey, providerID, modelID, language, files }) {
   const canonical = JSON.stringify({
     walkthroughVersion: WALKTHROUGH_VERSION,
     promptVersion: PROMPT_VERSION,
@@ -86,6 +86,10 @@ export function buildCacheKey({ repoRoot, sourceKey, providerID, modelID, files
     sourceKey,
     providerID,
     modelID,
+    // Without this, switching language hits the entry written in the previous
+    // one and the panel answers a request to translate with the untranslated
+    // text it already had.
+    language,
     files: [...files]
       .map((file) => ({ path: file.path, status: file.status, hunkIds: file.hunks.map((hunk) => hunk.id) }))
       .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),