i18n: move reference-pile docs into the repo; add the fan-out-sweep playbook

The reference-pile DOCS (what's collected, the authority tiers, provenance, and the per-source mining recipes) now live tracked at docs/i18n/reference-pile/ (README.md, inventory.md, how-to-mine.md). The ~3 GB of macOS/Microsoft/GNOME/Xfce reference DATA stays gitignored under _ignored/i18n/ with a thin pointer README. docs/guides/i18n-translation.md links the new docs.

Also adds a "Fan-out sweeps" section to docs/guides/multi-agent-refactors.md capturing this effort's learnings: cap concurrency at ~3 subagents (Anthropic API rate limits), give absolute write paths (subagents inherit the orchestrator cwd), terse returns with artifacts written to files, guardrails baked into the prompt, and a batched meta-check round after.

Author: vdavid

docs/guides/i18n-translation.md

@@ -28,13 +28,12 @@ Set a translator (human or agent) up for excellence with three inputs, never mix
 
 ## Researching terms: the reference pile
 
-Don't guess terms, and don't figure out the sources from scratch. A local reference pile at the repo root,
-`_ignored/i18n/`, holds authoritative localizations keyed by language: `_ignored/i18n/<tag>/` gathers, for that one
-language, the real macOS UI strings, the Microsoft terminology and localization style guide, and the GNOME/Xfce
-file-manager catalogs. Read `_ignored/i18n/CLAUDE.md` for what's there and the authority tiers, and
-`_ignored/i18n/HOW-TO-MINE.md` for tested per-source recipes (greps, jq, `msggrep`, `pdftotext`). (The pile is
-gitignored, so those paths are plain references, not links; in a linked worktree it's symlinked in, so the same paths
-resolve.)
+Don't guess terms, and don't figure out the sources from scratch. A reference pile holds authoritative localizations
+keyed by language: the ~3 GB of macOS, Microsoft, and GNOME/Xfce data sits gitignored at `_ignored/i18n/<tag>/` (one
+folder per language), and the docs explaining it are tracked in the repo. Read
+[`reference-pile/README.md`](../i18n/reference-pile/README.md) for what's there and the authority tiers, and
+[`reference-pile/how-to-mine.md`](../i18n/reference-pile/how-to-mine.md) for tested per-source recipes (greps, jq,
+`msggrep`, `pdftotext`).
 
 For each term or convention: triangulate across every source the language has (macOS is highest authority, then
 Microsoft, then GNOME/Xfce), pick the most native-sounding fit for Cmdr's voice, then record it in the style guide's

docs/guides/multi-agent-refactors.md

@@ -23,6 +23,24 @@ entry points; this is the playbook they assume.
 5. **Close out.** An end-of-phase adversarial conformance review agent (against the invariants register) plus a
    docs-audit agent that reads ALL commit bodies and verifies every touched `CLAUDE.md`.
 
+## Fan-out sweeps (parallel research or generation over a list)
+
+A different shape from the refactor loop above: many independent agents each handle a slice of a long list (e.g. one
+doc per language). Hard-won rules:
+
+- **Cap concurrency at ~3 subagents.** The Anthropic API rate-limits aggressively; a 14-agent burst gets throttled and
+  agents silently finish partial. Keep ~3 in flight; queue the rest. Batch size per agent (3 vs 10 items) is separate
+  and can stay large once concurrency is capped.
+- **Give ABSOLUTE write paths.** Subagents inherit the orchestrator's cwd (the main clone, not a worktree), so a
+  relative `docs/x.md` write scatters into the wrong tree. Pass the full worktree path.
+- **Terse returns, artifacts to files.** Tell agents to write their output to files and reply with one line per item
+  (plus flags), not a full report. Verbose returns blow the orchestrator's context over many waves. Persist a
+  progress/plan file so the loop survives a context compaction.
+- **Bake guardrails into the prompt.** Anti-hallucination (ground claims in local sources, mark web-only as unverified),
+  format rules, and "don't emit literal tool-call tags" prevent a cleanup pass later.
+- **Batched meta-check round after.** Independent reviewer agents (alphabet thirds) spot-check claims against ground
+  truth and flag stubs; this is what catches the fabrication-class errors the generators miss.
+
 ## Why it works
 
 The review rounds catch data-corruption-class design errors before implementation (a per-pane-vs-global counter that

docs/i18n/reference-pile/README.md

@@ -0,0 +1,37 @@
+# i18n terminology evidence pile
+
+Authoritative reference data for choosing translation terms with confidence, feeding the per-language translation style
+guides at [`/docs/i18n/`](..) (`<tag>-style.md`). Goal: every term we pick can cite what a real localized
+OS or an official vendor glossary actually says, so choices match user expectations instead of an agent's guess. Full
+inventory, provenance, layout rules, and open items: [inventory.md](inventory.md). Process and confidence model:
+[`/docs/guides/i18n-translation.md`](../../guides/i18n-translation.md).
+
+## Must-knows
+
+- **Language-first: one folder per locale gathers every source.** To research a language, point a translator at
+  `_ignored/i18n/<tag>/` (e.g. `i18n/fr/`); inside are `macOS/`, `microsoft-terminology/`, `microsoft-style-guides/`,
+  `gnome-nautilus/`, `xfce-thunar/` for that language. de, sv, hu, fr and every plain base language have all five.
+- **Mining recipes per source** (tested greps, jq, `msggrep`, `pdftotext`): [how-to-mine.md](how-to-mine.md). Use them;
+  don't reinvent the search per term.
+- **Reference for picking terms, never strings to copy.** Apple's and Microsoft's strings are copyrighted; the
+  GNOME/Xfce catalogs are GPL. We read them to decide what term matches user expectations, then write Cmdr's own catalog
+  value. Don't paste any vendor or upstream string verbatim into `apps/desktop/src/lib/intl/messages/`.
+- **Locale key = BCP-47, lossless, base-preferred.** Tags are normalized from each source's native code (punctuation +
+  script modifiers only: `pt_BR`→`pt-BR`, `sr@latin`→`sr-Latn`, legacy `no`→`nb`), with NO region↔script remapping. So
+  multi-script/region languages stay as separate sibling folders (`zh-Hans` vs `zh-CN`, `sr-Cyrl` vs `sr-Latn`, `nb` vs
+  `nb-NO`); those carry a `_see-also.txt` pointing to their siblings. This matches Cmdr's own `docs/i18n/<tag>-style.md`
+  tag convention.
+- **Gitignored, lives in the main clone.** `_ignored/` is untracked (`.gitignore` line 9), so this ~3 GB pile stays
+  local, isn't subject to the doc-system checks, and belongs in the main clone, not a worktree (worktrees get cleaned).
+- **Authority tiers** (how much a source proves "user expectation"): 1 = the real installed OS (macOS; strongest),
+  2 = vendor terminology + style guides (Microsoft), 3 = broad open-source corpora (GNOME/Xfce; cross-language parity),
+  4 = native human review (the only thing that makes a term "confirmed"; out of budget for now).
+
+## Structure
+
+```
+<tag>/<source>/…           one folder per BCP-47 locale (201 of them); see inventory.md for the sources
+_extract/macos-extract/    reproducible macOS extractor — emits the <tag>/macOS/… layout (go run main.go)
+_extract/reorg/            one-shot source-first → language-first restructure (already run; kept for reference)
+_downloads/                raw MS Terminology zip, kept for re-extraction
+```

docs/i18n/reference-pile/how-to-mine.md

@@ -0,0 +1,78 @@
+# How to mine the reference pile
+
+Tested recipes for extracting a term or convention from each source in `<tag>/`. The point: don't read whole files or
+reinvent the search each time. Triangulate a term across every source the language has, then record your choice with
+sources and a confidence in the per-language style guide (`docs/i18n/<tag>-style.md`). Structure and provenance of the
+pile: [README.md](README.md) and [inventory.md](inventory.md).
+
+First check which sources your language has: `ls <tag>/` (a source is absent if its subdir is missing). Run everything
+below from `_ignored/i18n/`.
+
+## macOS (Tier 1, strongest) — `<tag>/macOS/<bundle>/*.json`
+
+Flat `key: value` JSON per bundle (`Finder`, `AppKit`, `CoreTypes`, `SystemSettings`). Keys are stable across
+languages, so cross-reference English→target by key. The `en/` folder is the English side.
+
+```sh
+# 1. Find the key for an English term (which bundle/file, and the key):
+grep -rl '"Eject"' en/macOS/                    # which file has it
+grep -i 'eject' en/macOS/AppKit/AccessibilityImageDescriptions.json   # -> "NSNavEjectButton": "eject"
+# 2. Read the target translation of that same key:
+grep '"NSNavEjectButton"' sv/macOS/AppKit/AccessibilityImageDescriptions.json   # -> "mata ut"
+```
+
+Or with jq, search value strings and print key+value:
+```sh
+jq -r 'to_entries[]|select((.value|type)=="string" and (.value|test("eject";"i")))|"\(.key)\t\(.value)"' \
+  sv/macOS/Finder/*.json
+```
+macOS is the highest-authority source: it's what a user literally sees in Finder. Prefer it when sources disagree.
+
+## Microsoft terminology (Tier 2) — `<tag>/microsoft-terminology/<LANG>.tbx`
+
+Pretty-printed TBX XML, no namespace. Each `<termEntry>` has two `<langSet>`: `en-US` first, then the target. So in a
+window after the English `<term>`, the next `<term>` is the translation. `termNote type="geographicalUsage"` flags
+region (e.g. `AUT, DEU, CHE` for German), and `descrip type="definition"` gives the sense.
+
+```sh
+# English -> target (read the second <term> in the window, and any geographicalUsage):
+grep -i -A14 '<term[^>]*>folder</term>' de/microsoft-terminology/GERMAN.tbx | grep -iE '<term|xml:lang|geographicalUsage'
+#   -> folder ... <langSet xml:lang="de"> ... Ordner ... AUT, DEU, CHE, LUX
+
+# Validate a candidate target term exists, and see its English source (-B = lines before):
+grep -i -B14 '<term[^>]*>Ordner</term>' de/microsoft-terminology/GERMAN.tbx | grep -iE '<term'
+```
+Files are large; grep (streaming) beats loading them. `xmllint --xpath` works too but reads the whole doc into memory.
+
+## Microsoft style guide (Tier 2) — `<tag>/microsoft-style-guides/StyleGuide.pdf`
+
+Use for tone, formality (how to address the user), capitalization, and grammar conventions — not single terms. Extract
+text once, then grep; or open sections with the Read tool (it renders PDF pages).
+
+```sh
+pdftotext de/microsoft-style-guides/StyleGuide.pdf - | grep -iE -A3 'addressing the user|formal|du-form|anrede|tilltal'
+```
+The high-value sections are the early style/tone/grammar chapters and the "addressing the user" / formality section.
+
+## GNOME / Xfce (Tier 3, cross-language parity) — `<tag>/gnome-nautilus/nautilus.po`, `<tag>/xfce-thunar/thunar.po`
+
+gettext catalogs (`msgid` English, `msgstr` translation). Exactly the file-manager domain. Use `msggrep` (cleaner than
+grep for multi-line and plural entries):
+
+```sh
+msggrep --msgid -e 'Eject' sv/gnome-nautilus/nautilus.po          # entries whose msgid matches
+msggrep --msgstr -e 'papperskorg' sv/gnome-nautilus/nautilus.po   # reverse: find by target word
+grep -A2 'Plural-Forms' sv/gnome-nautilus/nautilus.po             # the language's plural rule
+```
+Plural entries use `msgid`/`msgid_plural` with `msgstr[0]`, `msgstr[1]`, … — good evidence for how a real catalog
+phrases counted strings in your language.
+
+## Confidence rubric (record this per term)
+
+- **confirmed**: David or a native reviewer signed off. Use freely.
+- **high**: macOS and/or Microsoft agree (cite which). Safe to use, still review-gated.
+- **tentative**: sources conflict or none had it; your best judgment. Push it to the style guide's "Decisions to confirm
+  with David" section rather than burying it.
+
+When sources disagree, weight by tier (macOS > Microsoft > GNOME/Xfce) but note the disagreement — it's often a
+macOS-vs-Windows split worth recording for the translator who comes after you.

docs/i18n/reference-pile/inventory.md

@@ -0,0 +1,100 @@
+# i18n terminology evidence pile — details
+
+Full inventory, provenance, layout rules, and open items for the reference pile. Must-knows and the top-level structure
+map: [README.md](README.md).
+
+## Layout and locale keys
+
+The pile is language-first: `_ignored/i18n/<tag>/<source>/…`, 201 locale folders. Inside each `<tag>` the sources are
+subdirs (`macOS/`, `microsoft-terminology/`, `microsoft-style-guides/`, `gnome-nautilus/`, `xfce-thunar/`), present only
+where that source has the language.
+
+`<tag>` is a BCP-47 locale, derived losslessly from each source's native code — punctuation and script-modifier
+normalization only, never region↔script remapping:
+
+- **macOS / GNOME / Xfce**: `_`→`-` (`pt_BR`→`pt-BR`, `en_GB`→`en-GB`); `@mod`→`-Subtag` (`sr@latin`→`sr-Latn`,
+  `ca@valencia`→`ca-valencia`, `uz@cyrillic`→`uz-Cyrl`); legacy macOS `no`→`nb`.
+- **microsoft-terminology**: the TBX's authoritative internal `xml:lang` (already BCP-47: `zh-Hans`, `pt-BR`, `sr-Latn`).
+- **microsoft-style-guides**: the slug→tag table in `_extract/reorg/main.go` — derived from terminology's codes by
+  name-matching, plus an override map for Microsoft's regional/script splits its terminology lumps (`french-canada`→
+  `fr-CA`, `spanish-mexico`→`es-MX`, `english-uk`→`en-GB`, `azerbaijani`→`az-Latn`, etc.). Unspecified-script slugs map
+  to base (`punjabi`→`pa`, `uzbek`→`uz`, `sanskrit`→`sa`).
+
+### Lossless sibling families
+
+Because we don't force region↔script merges, a few languages whose sources slice them differently end up as separate
+sibling folders, each with a `_see-also.txt` listing the set:
+
+- **Chinese**: `zh-Hans`/`zh-Hant` (Microsoft, script) vs `zh-CN`/`zh-TW`/`zh-HK` (macOS/GNOME, region).
+- **Serbian**: `sr-Cyrl`/`sr-Latn`/`sr-Cyrl-BA` (Microsoft) vs `sr`/`sr-Latn`/`sr-ije` (GNOME).
+- **Norwegian**: `nb`/`nn` (macOS/GNOME) vs `nb-NO`/`nn-NO` (Microsoft).
+
+For de, sv, hu, and every plain base language there are no such splits: one clean folder each.
+
+### Scripts
+
+- `_extract/macos-extract/` (`go run main.go`): harvests this Mac's bundles into `<tag>/macOS/<source>/…`. Re-runnable —
+  clears every `<tag>/macOS` subtree and rewrites it, leaving other sources untouched.
+- `_extract/reorg/` (`go run main.go`): the one-shot source-first→language-first restructure. Already run (it consumes
+  the flat source dirs). Kept as the documented, reproducible mapping.
+
+## What's collected
+
+### macOS (Tier 1)
+
+- **What**: localized UI strings from this Mac's system bundles, per language as JSON.
+- **Layout**: `<tag>/macOS/<source>/<file>.json`. Sources harvested: `Finder`, `CoreTypes` (kind names like folder,
+  volume), `AppKit` (standard buttons/menus: Cancel, Open, Eject, Move to Trash), `SystemSettings`.
+- **Coverage**: 42 languages, 6,174 JSON files, ~32 MB. Includes sv, de, hu plus the full macOS language set.
+- **Scope caveat**: curated to file-manager + standard-UI bundles, NOT every `.loctable` on the OS. Broaden by adding
+  entries to the `sources` list in `_extract/macos-extract/main.go` and re-running.
+- **Provenance**: extracted from `/System/…` on this machine via `plutil -convert json`, 2026-06-19. Re-run any time to
+  refresh against the current macOS build.
+
+### microsoft-terminology (Tier 2)
+
+- **What**: Microsoft Terminology Collection, the full per-language TBX glossaries.
+- **Layout**: `<tag>/microsoft-terminology/<LANGUAGE>.tbx` (e.g. `fr/microsoft-terminology/FRENCH.tbx`).
+- **Coverage**: 111 languages, ~2.6 GB. Pretty-printed XML (`xmllint --format --huge`, 111/111) so it's browsable.
+- **Provenance**: `https://download.microsoft.com/download/b/2/d/b2db7a7c-8d33-47f3-b2c1-ee5e6445cf45/MicrosoftTermCollection.zip`,
+  downloaded 2026-06-19; upstream files dated 2024-11-06. The source zip is kept in `_downloads/` for re-extraction
+  (note: re-extraction yields the original single-line TBX; re-run the `xmllint --format` pass after).
+- **License**: Microsoft Terminology license (reference use; see the usage rule in README.md).
+
+### microsoft-style-guides (Tier 2)
+
+- **What**: Microsoft Localization Style Guides (tone, formality, conventions, do/don't) per language.
+- **Layout**: `<tag>/microsoft-style-guides/StyleGuide.pdf`.
+- **Coverage**: all 102 available languages, ~82 MB, 0 download failures. German (82 pp), Swedish (58 pp), Hungarian
+  (62 pp) among them.
+- **Provenance**: `https://aka.ms/<language>-styleguide` redirects, downloaded 2026-06-19. Language list from
+  https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides.
+
+### gnome-nautilus, xfce-thunar (Tier 3)
+
+- **What**: translation catalogs (`.po`) for the two GTK file managers — exactly the file-manager domain, across many
+  languages — the cross-language parity source (equal depth for languages David speaks and ones he doesn't).
+- **Layout**: `<tag>/gnome-nautilus/nautilus.po`, `<tag>/xfce-thunar/thunar.po`.
+- **Coverage**: Nautilus 123 languages (~28 MB), Thunar 67 languages (~10 MB).
+- **License**: GPL (reference use; don't copy strings verbatim, same rule as the vendor sources).
+- **Provenance**: shallow `git clone` on 2026-06-19, `po/*.po` copied out, clones then removed:
+  - Nautilus `https://gitlab.gnome.org/GNOME/nautilus.git` @ `c4658b913a21740b874a4c955f51ff4494b8417b` (2026-06-19).
+  - Thunar `https://gitlab.xfce.org/xfce/thunar.git` @ `7410dc9b93a6c56b39ad2d0c6e29ccfbe1a76862` (2026-06-18).
+  - Re-clone to refresh.
+
+## Decisions made / open items
+
+- **Lossless siblings, separate regional/script folders (2026-06-19).** Chosen over collapsing to base or force-merging
+  scripts; the cost is that CJK/Serbian/Norwegian reference is spread across siblings (`_see-also.txt` bridges them), and
+  the gain is zero data loss and no opinionated remap. Irrelevant to de/sv/hu.
+- **Windows (Tier 1) — skipped, by decision (2026-06-19).** Reading the UTM VM's filesystem from here isn't feasible,
+  and Microsoft Terminology + Style Guides (Tier 2) already capture Windows terminology authoritatively. Revisit only if
+  a specific term needs the live Windows wording; then share a folder out of the VM (or mount its disk image) and
+  harvest the `.mui` resource strings.
+- **KDE Dolphin (Tier 3) — not collected.** KDE keeps translations in per-language l10n repos rather than the app repo,
+  so harvesting Dolphin across languages is more work than the clean `po/`-dir clones used for Nautilus and Thunar.
+  GNOME + Xfce already give broad file-manager parity; add Dolphin later if a term needs a third Linux data point.
+
+## Notes
+
+- (scratch space for term-by-term findings, conflicts, and rulings as the glossary work proceeds)