champollion 0.3.3 → 0.4.0

package/README.md

@@ -16,9 +16,11 @@ npx champollion sync
 
 Champollion auto-detects your locale files, their format, and the target languages. It translates missing keys, skips what's already done, and writes the results. That's it.
 
-> **Part of Champollion** — infrastructure for trustworthy machine translation
-> across every language, source-available and free for noncommercial use (the
-> evaluation harness and shared registries are open source). This CLI is the
+**License:** source-available under the [PolyForm Noncommercial License 1.0.0](LICENSE) — free to use, change and share for noncommercial purposes (personal projects, research, teaching, and use by charities, schools and public bodies). Using it for a commercial purpose is not covered by this license. The evaluation harness is open source (AGPL-3.0-or-later). [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this) · [Details](#license).
+
+> **Part of Champollion** — infrastructure for trustworthy machine-translation
+> evaluation across every language, source-available and free for noncommercial
+> use (the evaluation harness and shared registries are open source). This CLI is the
 > deployment end of a larger
 > project that builds the test sets and the map showing who can translate what,
 > how good each method is on each kind of text, and where the gaps still are. It
@@ -26,8 +28,8 @@ Champollion auto-detects your locale files, their format, and the target languag
 > every method welcome) and sovereign benchmarks — secret test sets that
 > communities create, own, and control, and that we never see. The infrastructure
 > is source-available and singly stewarded; the test sets and the methods for a
-> community's language belong to that community. Built with communities, never
-> scraped from them — they hold the keys. Every method is welcome, human and
+> community's language belong to that community. Designed to work with communities,
+> never hosting their corpora — the design puts the keys in their hands. Every method is welcome, human and
 > machine. Explore the network at
 > [champollion.dev/docs/network](https://champollion.dev/docs/network/).
 
@@ -37,7 +39,7 @@ You could write a quick script that loops through your English keys and calls Go
 
 - **No change detection.** When you update an English string, the translation stays stale forever. Champollion tracks every source value with SHA-256 hashes and re-translates only what changed.
 - **No batching.** One API call per key means 200 keys = 200 round trips. Champollion batches intelligently (configurable, default 80 keys/batch for LLM, 128 for Google).
-- **No quality gate.** Machine translation hallucinates, echoes the source back, or outputs in the wrong script. Champollion validates every translation before writing it — wrong-script, length inflation, and source echoes are caught and rejected.
+- **No quality gate.** Machine translation hallucinates, echoes the source back, or outputs in the wrong script. Champollion checks every translation before writing it — empty output, source echoes, repetition loops, length inflation, deleted content and wrong script are caught and rejected. The gate catches broken output, not wrong meaning.
 - **No format awareness.** Hardcoded to JSON? Champollion handles JSON, TOML, YAML, and Hugo Markdown (frontmatter + body) with auto-detection.
 - **No safety.** Champollion guards against prototype pollution, path traversal via crafted locale codes, and code block corruption during Markdown translation.
 
@@ -118,17 +120,17 @@ You handle the i18n framework (next-intl, i18next, Hugo). Champollion handles th
 - **Multi-format** — JSON, TOML, YAML, Hugo Markdown (front matter + body), and XLIFF 1.2
 - **Incremental** — Only translates what changed (SHA-256 hash tracking)
 - **Cached** — Translation Memory stores previous results; re-running sync costs nothing for unchanged keys
-- **Quality-gated** — Validates every translation: catches hallucinations, wrong-script output, source echoes, and length inflation
+- **Quality-gated** — Checks every translation for broken output: repetition loops, wrong-script output, source echoes, length inflation and deleted content (it does not check meaning)
 - **Content-aware** — LLM methods shield code blocks, shortcodes, links, and interpolation variables during Markdown translation
 - **Pipeline tools** — `lint`, `audit`, `integrity`, `seo` for CI gates
 - **XLIFF interop** — Export translations for professional review in CAT tools (memoQ, SDL Trados, Phrase), import them back
-- **Minimal dependencies** — two runtime dependencies (better-sqlite3 for the bundled language database, CLDR locale names); no provider SDKs. Requires Node 20+
+- **Minimal dependencies** — two runtime dependencies: `@translated/lara` (the Lara provider SDK) and `cree-sro-syllabics` (ALTLab/NRC's Plains Cree SRO ⇄ syllabics converter). Requires Node 20+
 
 ## Beyond Google Translate
 
 The quick start gets you running with an LLM or Google Translate. But Google Translate supports ~130 languages. There are over 7,000.
 
-**Champollion's core idea: the translation method is configurable per language pair.** Use Google Translate for French, an LLM with morphological coaching for Plains Cree, and a community-hosted API for Quechua — all in the same project, all with the same CLI.
+**Champollion's core idea: the translation method is configurable per language pair.** Use Google Translate for French, an LLM coached with your own grammar notes and dictionary for Plains Cree, and an API you host for a language no service covers — all in the same project, all with the same CLI.
 
 ```json
 {
@@ -136,7 +138,7 @@ The quick start gets you running with an LLM or Google Translate. But Google Tra
   "pairs": {
     "en:fr": { "method": "google-translate" },
     "en:ja": { "method": "llm" },
-    "en:crk": { "methodPlugin": "crk-coached-v1" }
+    "en:crk": { "method": "llm-coached" }
   }
 }
 ```
@@ -160,6 +162,7 @@ Champollion supports 10 translation methods. Each language pair can use a differ
 | `openai` | `OPENAI_API_KEY` | Direct OpenAI API (gpt-4o, gpt-4o-mini) |
 | `anthropic` | `ANTHROPIC_API_KEY` | Direct Anthropic API (Claude Sonnet, Haiku, Opus) |
 | `gemini` | `GEMINI_API_KEY` | Direct Google Gemini API (Flash, Pro) — free tier available |
+| `local` | *(none)* | Your own model behind an OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, a model trained with `nmt-forge`). Set `LOCAL_API_BASE` if it is not at Ollama's default. Text never leaves your infrastructure |
 
 **Traditional MT** — best for speed, cost, and high-volume key-value pairs:
 
@@ -188,7 +191,7 @@ champollion sync --method deepl
   "pairs": {
     "en:fr": { "method": "deepl" },
     "en:ja": { "method": "openai", "model": "gpt-4o" },
-    "en:crk": { "methodPlugin": "crk-coached-v1" }
+    "en:crk": { "method": "llm-coached" }
   }
 }
 ```
@@ -203,7 +206,7 @@ Plugins are pre-packaged translation recipes for specific language pairs. They'r
 champollion plugin install ./french-formal-v1/    # install from directory
 champollion plugin list                           # see installed plugins
 champollion plugin remove french-formal-v1        # uninstall
-champollion status                                # shows quality tiers + benchmarks
+champollion status                                # shows each pair's method, model + plugin benchmarks
 ```
 
 See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for the manifest format.
@@ -217,12 +220,8 @@ See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for
 | `serve` | Serve this project's translation stack over HTTP (api-method contract) |
 | `watch` | Auto-sync on file changes |
 | `audit` | Flag incomplete locales (CI gate) |
-| `card` | Pretty-print a language card (`card <code>`, `--json` for raw) |
-| `register-corpus` | Register an evaluation corpus: pick a license + exposure tier (local-only/private/public/sealed) |
-| `seal-corpus` | Sealed-tier crypto verbs: `keygen` / `seal` / `open` (organizer-node bridge) |
-| `submit` | Propose an index entry (review-gated) — prints a pre-filled GitHub issue |
 | `lint` | Find hardcoded strings in source code |
-| `status` | Show pair configuration, methods, registers, and quality tiers |
+| `status` | Show pair configuration, methods, registers, and plugin benchmarks |
 | `provenance` | Audit translation resource licensing |
 | `wrap` | Auto-wrap hardcoded strings in `t()` calls (with undo) |
 | `seo` | Generate hreflang, sitemap.xml, or JSON-LD schema |
@@ -233,10 +232,21 @@ See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for
 | `xliff` | Export/import XLIFF 1.2 for professional translator review |
 | `models` | List available models for a provider (`--method gemini`) |
 | `verify` | Re-read written locale files and confirm translations are present and correct (CI gate) |
-| `leaderboard` | Show the MT leaderboard (`--pair`, `--sort`, `--install N`) |
-| `recommend` | Method guidance for a pair — availability + cited evidence (`--use`, `--json`) |
 | `doctor` | System health check: cards, config, methods, and converters |
 
+The commands that work with the shared index and leaderboard, rather than your
+project, are grouped under `champollion network` (each also works without the
+prefix):
+
+| Command | Purpose |
+|---------|---------|
+| `network card` | Pretty-print a language card (`network card <code>`, `--json` for raw) |
+| `network recommend` | Method guidance for a pair — availability + cited evidence (`network recommend eng fra`, `--use`, `--json`) |
+| `network leaderboard` | Show the MT leaderboard (`--pair`, `--sort`, `--install N`) |
+| `network register-corpus` | Register an evaluation corpus: pick a license + exposure tier (local-only/private/public/sealed) |
+| `network seal-corpus` | Sealed-tier crypto verbs: `keygen` / `seal` / `open` (organizer-node bridge) |
+| `network submit` | Propose an index entry (review-gated) — prints a pre-filled GitHub issue |
+
 Run `champollion <command> --help` for detailed help on any command.
 
 Full reference: [the reference docs](https://champollion.dev/docs/reference/cli)
@@ -247,7 +257,7 @@ Full reference: [the reference docs](https://champollion.dev/docs/reference/cli)
 
 ```bash
 mkdir -p .githooks
-printf '#!/bin/sh\nnpx champollion lint\n' > .githooks/pre-commit
+printf '#!/bin/sh\nnpx --yes champollion@0.4 lint\n' > .githooks/pre-commit   # pinned: a new release never changes what the hook runs
 chmod +x .githooks/pre-commit
 git config core.hooksPath .githooks   # once per clone
 ```
@@ -284,8 +294,9 @@ Create `champollion.config.json` or run `champollion init`:
 | Option | Default | Description |
 |--------|---------|-------------|
 | `inputLocale` | `"en"` | Source language code |
-| `localesDir` | `"./locales"` | Path to locale files |
-| `contentDir` | `null` | Hugo content directory (enables Markdown translation) |
+| `localesDir` | `"./locales"` | Path to locale files: one file per language (`fr.json`) or one folder per language (`fr/common.json`, i18next) |
+| `localesPattern` | `null` | Any other layout, e.g. `"src/i18n/{ns}/{lang}.json"` (replaces `localesDir`) |
+| `contentDir` | `null` | Folder of Markdown/MDX to translate (a Hugo `content/` or any folder); each translation is written beside its source as `<name>.<locale>.md` |
 | `format` | `"auto"` | File format: `json`, `toml`, `yaml`, or `auto` |
 | `model` | `"google/gemini-3.5-flash"` | Default model (OpenRouter slug). Direct providers resolve their own default at runtime. Run `champollion models --method gemini` to discover available models. |
 | `defaultMethod` | `"llm"` | Default translation method (overridden by `--method` flag) |
@@ -302,7 +313,7 @@ Create `champollion.config.json` or run `champollion init`:
     "crk": {
       "name": "Plains Cree",
       "register": "SRO syllabics with grammatical precision.",
-      "model": "google/gemini-2.5-pro",
+      "model": "google/gemini-3.1-pro-preview",
       "batchSize": 5,
       "maxRetries": 5,
       "script": "Cans"
@@ -322,30 +333,34 @@ See the [CLI Reference](https://champollion.dev/docs/reference/cli) for framewor
 When you run `sync`, champollion shows exactly what's happening:
 
 ```
-champollion v0.1.0
+champollion v0.4.0
 
 [INFO] Detected format: json (auto)
 [INFO] Detected framework: Hugo
-[INFO] Source: en.json (2,847 keys)
+[INFO] Source: en.json (2847 keys)
 [INFO] Pairs: es-MX:llm, fr:deepl, it:llm
-[INFO] Estimated translation cost:
+Estimated translation cost:
 
-  Pair       Method   Keys  Est. Cost
-  ────────   ──────   ────  ─────────
-  en:es-MX   llm      2847    ~$0.8400
-  en:fr      deepl    2847    ~$0.5694
-  en:it      llm      2847    ~$0.8400
+  Pair      Method    Keys  TM hits   Est. Cost
+  ────────  ──────  ──────  ───────  ──────────
+  en:es-MX  llm       2847        0    ~$0.3843
+  en:fr     deepl     2847        0    ~$1.7794
+  en:it     llm       2847        0    ~$0.3843
 
-  Total: ~$2.2494
+  Total: ~$2.5480
+  Rates: google/gemini-3.5-flash $0.30 input / $2.50 output per 1M tokens — OpenRouter's price list, read 2026-10-04 14:02 UTC; deepl $25.00 per 1M characters — the provider's published price, as checked 2026-06-08. An estimate: ~200 input + ~30 output tokens or ~25 characters per key assumed — the bill depends on the real lengths (--json has the detail).
 
-[INFO] es-MX.json — 2,847 missing
+[INFO] Translating 3 locale(s) with concurrency 50
+[INFO] es-MX.json — 2847 missing
+     ████████████████████████████████ 2,847/2,847 keys
+[INFO] fr.json — 2847 missing
      ████████████████████████████████ 2,847/2,847 keys
-[INFO] fr.json — 2,847 missing
+[INFO] it.json — 2847 missing
      ████████████████████████████████ 2,847/2,847 keys
-[OK] Synced 5,694 keys total.
+[OK] Synced 8541 keys total — 8541 key(s) sent to the model, 0 served from the cache (free).
 ```
 
-The progress bar updates in-place as each batch completes (~80 keys per update). Framework detection shows `Hugo` when `contentDir` is set. Format detection distinguishes `(auto)` from `(config)` to clarify how the format was resolved.
+The estimate's last line names the rate each figure was priced at, where it came from and when (`--json` carries the detail). "Translating …" is said only when something will be sent: a dry run, or a run with nothing to send, says it is checking the locales instead. The progress bar updates in-place as each batch completes (~80 keys per update). When `contentDir` is set, sync names the folder and where its translations go; it says `Detected framework: Hugo` only when it finds a real Hugo site (`hugo.toml`, a `config.toml` with Hugo settings, `archetypes/`, …). Format detection distinguishes `(auto)` from `(config)` to clarify how the format was resolved.
 
 **Output modes**: `--quiet` suppresses informational output (errors and warnings only). `--json` emits machine-readable NDJSON for CI/CD pipelines.
 
@@ -384,4 +399,4 @@ npm run test:methods             # translation method suite
 
 ## License
 
-PolyForm Noncommercial 1.0.0. The Champollion CLI is source-available — free to install, use, and modify for noncommercial purposes (research, education, community work) under the [PolyForm Noncommercial License 1.0.0](LICENSE); commercial use requires the licensor's permission. The published `champollion` npm package is PolyForm-Noncommercial-1.0.0; `cli/LICENSE` is the authoritative license for the distributed package. The companion MT Eval Harness and specs are open source, licensed AGPL-3.0-or-later — with a §7 eval-standard-plugin exception — at the public [harness repository](https://github.com/gamedaysuits/Champollion).
+PolyForm Noncommercial 1.0.0. The Champollion CLI is source-available — free to install, use, and modify for noncommercial purposes (research, education, community work) under the [PolyForm Noncommercial License 1.0.0](LICENSE); using it for a commercial purpose is not covered by this license. In plain words, with examples — a school, a public hospital or clinic, a charity, a personal or research project is covered; a for-profit business's product, such as a shop's storefront, is not: [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this) (a summary, not legal advice; the license text governs). The published `champollion` npm package is PolyForm-Noncommercial-1.0.0; `cli/LICENSE` is the authoritative license for the distributed package. The companion MT Eval Harness and specs are open source, licensed AGPL-3.0-or-later — with a §7 eval-standard-plugin exception — at the public [harness repository](https://github.com/gamedaysuits/Champollion).

package/bin/cli.js

@@ -34,10 +34,17 @@ const CLI_OPTIONS = {
     version:          { type: 'boolean', short: 'v' },
     yes:              { type: 'boolean', short: 'y' },
     'warn-only':      { type: 'boolean' },
+    strict:           { type: 'boolean' },  // verify --strict: warnings fail the check (exit 1)
     'no-verify':      { type: 'boolean' },  // skip post-sync verification
     undo:             { type: 'boolean' },
     'force-content':  { type: 'boolean' },  // ignore the content lock (TM still serves unchanged bodies/blocks)
+    files:          { type: 'string', multiple: true },  // sync: only these content files (glob, repeatable)
+    retranslate:    { type: 'string', multiple: true },  // sync: translate these content files fresh (glob, repeatable)
+    redo:           { type: 'string', multiple: true },  // sync: queue again — all | keys:<k> | content | files:<glob> (lib/redo.js)
+    fresh:          { type: 'boolean' },  // sync: do not use the cache for what is queued (billed again)
+    prune:          { type: 'string', multiple: true },  // sync: remove what the locale cannot use — plural-extras (i18next keys for forms the language does not have)
     'no-tm':          { type: 'boolean' },  // skip Translation Memory for this sync run
+    'fresh-on-model-change': { type: 'boolean' },  // don't reuse other models' TM entries
     css:              { type: 'boolean' },  // fonts install --css: generate CSS snippet
     json:             { type: 'boolean' },  // machine-readable NDJSON output
     quiet:            { type: 'boolean', short: 'q' },  // suppress info/ok messages, show only warnings/errors
@@ -49,12 +56,14 @@ const CLI_OPTIONS = {
     'content-dir': { type: 'string' },
     source:        { type: 'string' },
     langs:         { type: 'string' },
+    script:        { type: 'string' },     // init: writing system per target, e.g. crk=Cans (a language with two real orthographies)
     model:         { type: 'string' },
     method:        { type: 'string' },
     format:        { type: 'string' },
     'base-url':    { type: 'string' },
     out:           { type: 'string' },
     src:           { type: 'string' },
+    ignore:        { type: 'string' },     // lint: comma-separated directory/file names to skip
     'min-length':  { type: 'string' },
     'force-keys':  { type: 'string' },
     'list-keys':   { type: 'boolean' },    // sync --dry: name every queued key per reason
@@ -63,7 +72,8 @@ const CLI_OPTIONS = {
     'json-concurrency':    { type: 'string' },     // max parallel API calls for JSON key-value translation (default: 50)
     'content-concurrency': { type: 'string' },     // max parallel API calls for markdown content (default: 12)
     'batch-size':  { type: 'string' },     // keys per translation API call (positive integer; overrides config batchSize)
-    'max-cost':    { type: 'string' },     // sync: USD cap — abort (exit 2) before any API call if the estimate exceeds it or is unknown
+    'max-cost':    { type: 'string' },
+    'show-prompt': { type: 'string' },     // sync --dry: print the exact request the method would get (optionally for one key)     // sync: USD cap — abort (exit 2) before any API call if the estimate exceeds it or is unknown
     temperature:   { type: 'string' },     // sampling temperature for LLM methods
     'coaching-file': { type: 'string' },   // path to coaching prompt text file
     locale:        { type: 'string' },     // target locale for xliff export, tm clear/seed
@@ -80,7 +90,7 @@ const CLI_OPTIONS = {
     license:       { type: 'string' },     // register-corpus: license key / SPDX id / list number
     tier:          { type: 'string' },     // register-corpus: exposure tier (local-only|private|public)
     exposure:      { type: 'string' },     // register-corpus: alias for --tier
-    name:          { type: 'string' },     // register-corpus: corpus name
+    name:          { type: 'string' },     // register-corpus: corpus name; init: display name of a language with no card (qaa="…")
     publisher:     { type: 'string' },     // register-corpus: publisher / author
     description:   { type: 'string' },     // register-corpus: one-line description
     'source-lang': { type: 'string' },     // register-corpus: source language code (alt to --pair)
@@ -90,10 +100,12 @@ const CLI_OPTIONS = {
     'license-url': { type: 'string' },     // register-corpus: upstream license URL
     builder:       { type: 'string' },     // register-corpus: builder adapter id
     sha256:        { type: 'string' },     // register-corpus: built-corpus hash (optional)
+    data:          { type: 'string' },     // register-corpus: the local file the card describes (hashed, never uploaded)
     contamination: { type: 'string' },     // register-corpus: NONE|LOW|MEDIUM|HIGH
     domain:        { type: 'string' },     // register-corpus: corpus domain
     size:          { type: 'string' },     // register-corpus: number of sentence pairs
     id:            { type: 'string' },     // register-corpus: override card id
+    role:          { type: 'string' },     // register-corpus: test|dev|train — in the id only when stated
     version:       { type: 'string' },     // register-corpus: corpus version (major)
     'do-not-train': { type: 'boolean' },   // register-corpus: benchmark-integrity flag (default true)
     'cards-dir':   { type: 'string' },     // register-corpus: corpora-cards dir override (advanced/testing)
@@ -133,7 +145,8 @@ const CLI_OPTIONS = {
     'max-cost-per-request':  { type: 'string' },   // serve: USD cap per request (unknown estimates refuse)
     'max-session-cost':      { type: 'string' },   // serve: USD spend ceiling for the server process
     'emit-manifest':         { type: 'boolean' },  // serve: write the consumer method.json and exit
-    endpoint:                { type: 'string' },   // serve --emit-manifest: public endpoint URL for the manifest
+    endpoint:                { type: 'string' },   // serve --emit-manifest: public endpoint URL; init --method api: the champollion API endpoint
+    'accepts-instructions':  { type: 'string' },   // init --method api: does the endpoint follow per-key instructions (true|false)
 };
 
 const { values, positionals } = parseArgs({
@@ -169,6 +182,17 @@ const args = { _: positionals, ...values };
 // --dry-run is an alias for --dry — merge so command modules only check args.dry
 if (args['dry-run']) args.dry = true;
 
+// --redo / --fresh are the one way to say "translate this again"; they are
+// rewritten into the older flags here so sync keeps one set of semantics.
+if (args.redo !== undefined || args.fresh) {
+  const { applyRedo } = await import('../lib/redo.js');
+  const redoError = applyRedo(args);
+  if (redoError) {
+    console.error(`[ERR] ${String(redoError).replace(/\u0004/g, '\u2404')}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Exit only once stdout has actually been written.
  *
@@ -187,7 +211,24 @@ function exitWhenFlushed(code) {
   process.stdout.write('', () => process.exit(code));
 }
 
-const command = args._[0] || 'help';
+// `champollion network <command>` — the commands that work with the shared
+// index and leaderboard rather than this project. Each also works without
+// the prefix (the names people already use).
+// (scripts/check_doc_commands.py reads COMMAND_GROUPS to check the docs.)
+const COMMAND_GROUPS = {
+  network: ['card', 'recommend', 'leaderboard', 'register-corpus', 'seal-corpus', 'submit'],
+};
+const NETWORK_COMMANDS = COMMAND_GROUPS.network;
+let command = args._[0] || 'help';
+if (command === 'network' && args._[1]) {
+  if (!NETWORK_COMMANDS.includes(args._[1])) {
+    console.error(`[ERR] Unknown network command: "${args._[1]}"`);
+    console.error(`      Network commands: ${NETWORK_COMMANDS.join(', ')}`);
+    process.exit(1);
+  }
+  args._ = args._.slice(1);
+  command = args._[0];
+}
 const cwd = process.cwd();
 
 // -----------------------------------------------------------------
@@ -264,11 +305,18 @@ if (args.help && command !== 'help') {
       .then(mod => mod.run(args, cwd))
       .then(code => exitWhenFlushed(code || 0))
       .catch(err => {
-        console.error(`[ERR] ${command} failed:`, err.message);
+        // A gettext context key in the message shows its U+0004 as "␄",
+        // the form --redo keys: accepts back (lib/output.js showKey).
+        console.error(`[ERR] ${command} failed:`, String(err.message).replace(/\u0004/g, '\u2404'));
         exitWhenFlushed(1);
       });
   } else if (command === 'help') {
     import('../lib/commands/help.js').then(mod => mod.run());
+  } else if (command === 'network') {
+    import('../lib/command-help.js').then(({ showCommandHelp }) => {
+      showCommandHelp('network');
+      process.exit(0);
+    });
   } else {
     // Unknown command — error loudly so CI typos don't silently pass
     console.error(`[ERR] Unknown command: "${command}"`);

package/index.js

@@ -15,8 +15,11 @@
  *     getRegisterPresets, getFormality, getGenderGuidance, getAllLanguageCodes,
  *     resolveCode
  *   - Sync: runSync, runContentSync
+ *   - One pair's pipeline: translateWithFallback, translateAndValidate,
+ *     previewRequests, createFallbackBudget
+ *   - Locale layout: discoverLocaleLayout, resolveLocaleFiles
  *   - Quality: validateTranslations
- *   - Utilities: loadApiKey, getEnvOrFileVar
+ *   - Utilities: loadApiKey, getEnvOrFileVar, costLabel
  */
 
 // ── Translation method classes ─────────────────────────────────────
@@ -49,6 +52,19 @@ export {
 } from './lib/config.js';
 export { resolvePairs } from './lib/pairs.js';
 
+// ── Writing systems (a pair's `script`) ────────────────────────────
+// The same decision sync makes: a locale with two real orthographies (crk,
+// sr) refuses until one is chosen; a chosen display script is produced by
+// converting the working-script translation. The MCP translate tool uses
+// these so it never picks an orthography sync would refuse to pick.
+export {
+  resolveTargetScript,
+  formatScriptChoiceError,
+  convertScript,
+  applyScriptFallback,
+  getConverterInfo,
+} from './lib/scripts.js';
+
 // ── Language cards & registers ─────────────────────────────────────
 export {
   getLanguageCard,
@@ -60,6 +76,10 @@ export {
   getAllLanguageCodes,
   getMethodSupport,
   resolveCode,
+  // A code or a language NAME ("French") → the code to work in; with a
+  // project's locales, the project's own spelling ("fr"). Never guesses.
+  findLanguagesByName,
+  resolveLanguageInput,
   // Dynamic card tier (packaged installs): warm the per-user cache up
   // front instead of paying a per-miss synchronous fetch.
   prefetchLanguageCards,
@@ -83,12 +103,39 @@ export {
 // ── Sync pipeline ──────────────────────────────────────────────────
 export { runSync, runContentSync } from './lib/sync.js';
 
+// ── One pair's translation pipeline ────────────────────────────────
+// What `champollion sync` and `serve` run for a batch of keys: cache →
+// method → quality gate → cache, then the pair's fallback for what that
+// left (a resolved pair from resolvePairs; `options.tm` from loadTM;
+// `options.cwd` = the project directory, where methods read their key,
+// endpoint, coaching and glossary). The MCP translate tool runs a project's
+// fallback through it. createFallbackBudget caps a fallback under a cost.
+export { translateWithFallback, translateAndValidate, previewRequests } from './lib/translate-pair.js';
+export { createFallbackBudget } from './lib/fallback.js';
+
+// ── Locale layout ───────────────────────────────────────────────────
+// Which files make up each locale (flat, folder per locale, localesPattern)
+// — the same answer sync, verify and xliff use, for build scripts and
+// agents that need to find a project's locale files.
+export { discoverLocaleLayout, resolveLocaleFiles } from './lib/locale-layout.js';
+
 // ── Quality gate ───────────────────────────────────────────────────
-export { validateTranslations } from './lib/validate.js';
+// The shared-output rule (one text for several different sources) — the MCP
+// translate tool holds its answers to it, as sync does.
+export { validateTranslations, SharedOutputIndex, sharedOutputItems, sharedOutputReason } from './lib/validate.js';
+// The index a sync of one locale starts with (the memorized sentences its
+// cache remembers + what the project's files and pages already hold): the
+// MCP translate tool, given a project_dir, refuses what sync would refuse.
+export { projectSharedOutputIndex } from './lib/shared-output-seed.js';
 
 // ── API key resolution ─────────────────────────────────────────────
 export { loadApiKey, getEnvOrFileVar } from './lib/api-key.js';
 
+// ── Cost wording ───────────────────────────────────────────────────
+// One label for an estimate ("$0 API cost (runs on this machine)",
+// "est. ~$0.0123"): the MCP translate tool names a price in the CLI's words.
+export { costLabel, LOCAL_COST_LABEL } from './lib/cost-label.js';
+
 // ── Coaching utilities (for custom method implementations) ─────────
 export {
   loadCoachingData,
@@ -107,7 +154,21 @@ export {
   partitionByTM,
   tmMethodKey,
   tmSize,
+  // A project's cache from before coaching was keyed reads as sync reads it.
+  adoptLegacyCoachingKeys,
+  // Which setup wrote the entry a lookup serves (an earlier model's, under
+  // model carry-over), and that key in words — so a cached answer can say
+  // who wrote it when that is not the engine named (MCP translate).
+  servingMethodKey,
+  describeMethodKey,
 } from './lib/tm.js';
+// The text a key is cached under — a gettext msgctxt folded in
+// ("msgctxt\u0004msgid" → "msgctxt\u0004<text>") — and which contexts a
+// project's source gives each text: the MCP translate tool keys a context as
+// sync does, and never writes a context-free entry for a text the project
+// has only with a context.
+export { tmSourceText, CONTEXT_SEPARATOR } from './lib/tm-evict.js';
+export { sourceTextContexts } from './lib/source-contexts.js';
 
 // ── XLIFF interchange ──────────────────────────────────────────────
 export {

package/lib/api-key.js

@@ -83,22 +83,35 @@ function loadApiKey(config, cwd) {
  * @returns {string|null} The variable value, or null if not found
  */
 function getEnvOrFileVar(keyName, cwd = process.cwd()) {
+  return findEnvOrFileVar(keyName, cwd)?.value ?? null;
+}
+
+/**
+ * getEnvOrFileVar, saying WHERE the value was found — for messages that
+ * must name the setting a run used (e.g. the endpoint a local method could
+ * not reach, and whether it came from the shell or a .env file).
+ *
+ * @param {string} keyName - Name of the environment variable
+ * @param {string} [cwd=process.cwd()] - Project root directory
+ * @returns {{ value: string, origin: 'environment'|'.env.local'|'.env', file: string|null }|null}
+ */
+function findEnvOrFileVar(keyName, cwd = process.cwd()) {
   // Priority 1: Check environment directly. Normalize identically to file
   // values (trim + strip surrounding quotes) so a quoted/padded exported secret
   // never reaches an Authorization header verbatim.
   if (process.env[keyName]) {
-    return normalizeKeyValue(process.env[keyName]);
+    return { value: normalizeKeyValue(process.env[keyName]), origin: 'environment', file: null };
   }
 
   // Priority 2: .env.local (Vercel/Next.js convention)
   const envLocalPath = path.join(cwd, '.env.local');
   const fromLocal = readKeyFromFile(envLocalPath, keyName);
-  if (fromLocal) return fromLocal;
+  if (fromLocal) return { value: fromLocal, origin: '.env.local', file: envLocalPath };
 
   // Priority 3: .env
   const envPath = path.join(cwd, '.env');
   const fromEnv = readKeyFromFile(envPath, keyName);
-  if (fromEnv) return fromEnv;
+  if (fromEnv) return { value: fromEnv, origin: '.env', file: envPath };
 
   return null;
 }
@@ -124,4 +137,4 @@ function readKeyFromFile(filePath, targetKey) {
   return null;
 }
 
-export { loadApiKey, parseEnvLine, getEnvOrFileVar };
+export { loadApiKey, parseEnvLine, getEnvOrFileVar, findEnvOrFileVar };