What the bug is. load_glossary (scripts/docs/translations.py:307-317) promises in its docstring to raise ConfigError when glossary.json is "not that shape", but its exception net only catches OSError/JSONDecodeError/TypeError/KeyError from Term(**entry) and tuple(raw['keep']). Term is a plain frozen dataclass with avoid: Sequence[str] = () — dataclasses do not enforce annotations at runtime, and a Python str structurally is a Sequence[str]: iterating it yields its characters. So the natural singular slip "avoid": "Gastgeber" loads without error, and tuple("MCP") for a bare-string keep silently becomes ('M', 'C', 'P').\n\nThe code path that triggers it. Once loaded, glossary_prompt() renders the exploded string into every request's system prompt — - host → Host (never: G, a, s, t, g, e, b, e, r) — and validate()'s banned-rendering scan (translations.py:788-794, for avoid in term.avoid if avoid.casefold() in folded) checks each single letter as a banned substring of the translated output. A bare-string keep likewise lists single letters (- M, - C, - P) as "terms that stay in English" in every cached system prompt.\n\nStep-by-step proof (reproduced by verifiers executing the module's own functions on this head):\n\n1. Write glossary.json with {"keep": "MCP", "terms": [{"source": "host", "target": "Host", "avoid": "Gastgeber"}]}.\n2. load_glossary(path) returns successfully — no exception in the net fires, so the documented ConfigError never happens.\n3. glossary_prompt(g) renders - host → Host (never: G, a, s, t, g, e, b, e, r) into the system prompt for every page.\n4. validate('The server is great.', 'Der Server ist gut.', g, 'test') returns 7 findings of the form banned rendering 'e' of 'host' appears: use 'Host' — one per distinct character of "Gastgeber" present in the output.\n5. Since single letters like 'e' occur on essentially every page in every target language, the constraint is unsatisfiable: every open page of the next translate run burns its full 1 + MAX_REPAIRS paid model calls (no reply can avoid the letter 'e'), then fails with per-letter diagnostics that never point at the malformed glossary field.\n\nWhy existing code doesn't prevent it. The type annotation Sequence[str] is exactly the type that makes this slip invisible: it is satisfied at runtime by the wrong value, pyright doesn't check JSON-derived dicts, and no test exercises a bare-string shape. The failure surfaces two steps removed from its cause — in validate()'s output during a paid run — which is the opposite of the tool's documented fail-fast contract (offline exit 2 before any API call).\n\nWhy it's realistic and what the impact is. glossary.json is exactly the file this PR routes contributor and native-reviewer corrections into (CONTRIBUTING.md, docs/translations.md, and the i18n/README.md line this comment anchors on all direct edits there), and the singular "avoid": "X" is a natural mistake for a one-item ban list. The cost if it lands: one wasted paid run across all open pages, exit 1, and diagnostics that actively mislead. It's a nit rather than blocking because this is docs tooling, not the shipped mcp package — nothing in CI calls the API, the committed glossaries are well-formed, and recovery is just fixing the JSON and rerunning.\n\nHow to fix. In load_glossary, reject the string shape explicitly before constructing the dataclasses, e.g.:\n\npython\nif isinstance(raw["keep"], str) or any(isinstance(e.get("avoid"), str) for e in raw["terms"]):\n raise ConfigError(f"{path}: 'keep' and 'avoid' must be lists of strings, not a bare string")\n\n\nThis preserves the exit-2 fail-fast contract the docstring already documents.

What the bug is. serve() in scripts/docs/translations.py has two layout strategies. When state.changed is empty (pure reorder/removal), commit 00e9565 made it hash-correct: stored = recorded_sections(state.translation); body = "".join(stored[value] for value in state.hashes). But when state.changed is non-empty — an ordinary docs-restructure commit that edits one section and moves others — the first branch runs body = state.translation.body, i.e. the stored translation in its old positional order, against today's reordered English. reimpose() then pins today's English heading ids onto the translation purely by position (_pin_headings) and copies English fences by position (_restore_fences), cross-wiring both.\n\nStep-by-step proof (reproduced by three independent verifiers executing the module's own functions at PR head). (1) English page with sections [Alpha, Beta, Gamma], faithfully translated; provenance records the three hashes in that order. (2) One English commit edits Alpha and swaps Beta/Gamma → English is now [Alpha', Gamma, Beta]. (3) classify(): h(Beta) and h(Gamma) are both still in the recorded set, so only the edited index lands in changed — changed=[0], status outdated. (4) serve() takes the if state.changed: branch, so body is [tAlpha, tBeta, tGamma] against English [Alpha', Gamma, Beta]. (5) reimpose() returns a clean str: the staged page contains ## Beta-DE {#gamma} and ## Gamma-DE {#beta} — every cross-page link to #gamma lands on the Beta translation's text. When the swapped sections each carry one fence, _restore_fences splices Gamma's code block into the Beta section (per-position counts 1==1), silently.\n\nWhy the existing safety net misses it. The Mismatch → serve-English fallback fires only on heading count/level differences, per-position fence-count differences, or per-position link-target differences. Two swapped prose-shaped sections with the same internal structure match on all three checks, so the reply sails through and stage exits 0 with only the generic "outdated" notice. The regression test added in 00e9565 (test_stage_lays_out_reordered_and_removed_sections_by_their_recorded_hashes_never_by_position) exercises only the pure-reorder case (changed==[]), so the commit's claim that "a reordered English page can no longer pair code blocks or heading ids with the wrong section" does not hold for the edit+reorder combination.\n\nImpact. deploy-docs.yml rebuilds on any docs/** merge, so from the moment the English restructure merges until someone manually runs translate, all 12 language sites serve pages whose anchors point at the wrong section's text (and, in the fence variant, whose code blocks sit under the wrong headings) — an unbounded window, with no diagnostic beyond the generic outdated notice. The window closes on the next translate run because carry_forward() is already hash-correct (it keys prior sections by recorded hash via recorded_sections(job.previous)), so only the staged/deployed output is wrong, never the committed translation files.\n\nHow to fix. In the changed-non-empty branch, lay out sections by recorded hash exactly as the else branch does, substituting the positional text only for the indices in state.changed (whose sections have no stored counterpart): e.g. build stored = recorded_sections(state.translation) plus a positional list of the stored body's sections, then for each index in state.hashes take stored[hash] when the hash is recorded and the positional stored section otherwise. Alternatively, fall back to English whenever the recorded hashes of the unchanged sections are not in the same relative order as in state.hashes. Extending the 00e9565 regression test with an edit+reorder case would lock the behavior in.\n\nWhy normal severity. This is not a latent corner case: editing a section while moving others is a routine docs-restructure commit shape, the failure ships incorrect published content (wrong anchor targets, potentially wrong code blocks) on every language site, and it is specifically the surviving half of a defect class the author already judged fix-worthy during this PR's review — 00e9565 fixed the sibling pure-reorder case and its test now gives false confidence that the whole class is closed. The fix is small and local to serve().

What the bug is. unwrap() in scripts/docs/translations.py (lines 682-689) normalizes the tail of a model reply in one direction only: if english.endswith("\n") and not reply.endswith("\n"): reply += "\n". A reply that ends with a surplus newline (...\n\n where the English ends ...\n) is left untouched. No downstream check catches it either: reimpose() verifies fences, heading counts/ids and link targets, and validate() checks code spans, !!!/===/??? markers, list-item and table-row counts, banned glossary renderings and English placeholder patterns — a bare extra newline trips none of them. This was reproduced end-to-end by three independent verifiers executing the module's own functions on this head.\n\nWhy it persists forever. The accepted page is written with the surplus newline in its last section's bytes (sections() assigns trailing newlines to the last section), but with_provenance() records only the English section hashes (job.state.hashes) — never a digest of the translated bytes. classify() therefore reports the page current indefinitely; nothing ever flags the drifted section for re-translation, and carry_forward() reproduces it byte-for-byte on every subsequent run. update_request() even presents the drifted body to the model as the previous translation to reproduce line by line, so the drift self-propagates.\n\nHow it surfaces mid-page. The surplus newline is invisible while the section stays last. But when a later English edit appends a new section after it (or reorders sections), carry_forward()/serve() splice the stored section into a middle position via recorded_sections(). Because sections() assigns the blank line above a heading to the following section, the assembled body reads ...text.\n\n\n## Next where the English has ...text.\n\n## Next — a doubled blank line mid-page. The second reimpose/validate pass accepts this too (carried sections are exempt from validation anyway), the file re-records clean English hashes, and the drift is permanent.\n\nStep-by-step proof (as reproduced by the verifiers): (1) the model's reply for a two-section page ends Inhalt eins.\n\n against English Content one.\n; unwrap() leaves it, reimpose() and validate() return clean, the page is written and classified current. (2) The English page gains a new ## Two section after the last one; the page becomes outdated for that section only. (3) carry_forward() maps the stored first-section bytes (tail \n\n) ahead of the freshly translated new section (which starts \n## ), producing Inhalt eins.\n\n\n## Zwei — one blank line in the English, two in the translation. (4) All checks pass again; recorded_sections() stores the drifted bytes keyed by the clean English hash, so every future run carries them and status never reports anything wrong.\n\nImpact and why this is a nit. Rendered HTML is identical — Markdown collapses blank-line runs — so no reader ever sees the drift. The harm is that it permanently violates the tool's own contract (i18n/README.md line 18: sections are kept "byte for byte"; the PR description: "a one-line English edit is a one-line translated diff"; general-prompt.md: "the same blank lines between blocks"), producing unrelated whitespace hunks in generated-page diffs on every later partial update, with no detection or self-healing short of a full --pages retranslation of the affected page. The trigger also requires the model to emit a surplus trailing newline — plausible but not guaranteed — and this is docs-publishing tooling, not the shipped library.\n\nHow to fix. In unwrap(), when the English body ends with a single trailing newline, replace the append-only branch with reply = reply.rstrip("\n") + "\n" so both a missing and a surplus tail newline normalize to the English shape. (Alternatively, emit a findings entry for tail blank-line mismatches so the existing repair loop handles it, but the one-liner is simpler and mechanical.) A small unit test pairing an English page ending \n with replies ending `` (no newline), \n and `\n\n` would pin the behavior.