champollion 0.5.1 → 0.5.3

package/lib/command-help.js

@@ -711,7 +711,7 @@ const COMMAND_HELP = {
   },
 
   models: {
-    usage: 'champollion models --method <provider>',
+    usage: 'champollion models --method <provider> | champollion models check',
     description: [
       'Lists available models from a translation provider\'s API.',
       'Queries the provider\'s live model endpoint and displays all',
@@ -719,6 +719,7 @@ const COMMAND_HELP = {
     ],
     options: [
       ['--method <name>', 'Provider to query: gemini, openai, or anthropic (required)'],
+      ['check',           'Check every default model (shared/model-defaults.json) against the providers\' live lists; exit 1 if one is gone. Free (list endpoints are not billed)'],
       ['--json',          'Machine-readable JSON output (single document)'],
     ],
     examples: [

package/lib/commands/models.js

@@ -21,6 +21,8 @@ import { resolveConfig } from '../config.js';
 import { fetchAvailableModels, resolveProviderApiKey, getProviderLabel, getProviderEnvVar, isListableProvider, getListableProviders } from '../models.js';
 import { missingKeyAdvice } from '../missing-key.js';
 import { output } from '../output.js';
+import { checkModelDefaults } from '../model-defaults.js';
+import { fetchModelPricing } from '../methods/openrouter-pricing.js';
 
 /**
  * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
@@ -38,6 +40,8 @@ async function run(args, cwd) {
     return 0;
   }
 
+  if (args._[1] === 'check') return runCheck(args, cwd, json);
+
   const method = args.method;
   if (!method) {
     if (json) {
@@ -182,3 +186,49 @@ function showHelp() {
 }
 
 export { run };
+
+/**
+ * `champollion models check` — every default model (shared/model-defaults.json)
+ * against the providers' live lists. Read-only and free: list endpoints are
+ * not billed. Exit 1 when a pinned default is no longer listed (a run would
+ * fail on it); a newer model matching a role's rule is reported, not a
+ * failure — moving a default is a reviewed change, never automatic.
+ *
+ * @param {object} args
+ * @param {string} cwd
+ * @param {boolean} json
+ * @returns {Promise<number>}
+ */
+async function runCheck(args, cwd, json) {
+  const lists = { openrouter: null, openai: null, gemini: null, anthropic: null };
+  try {
+    const pricing = await fetchModelPricing();
+    if (pricing && pricing.size > 0) lists.openrouter = [...pricing.keys()];
+  } catch { /* unchecked */ }
+  for (const provider of ['openai', 'gemini', 'anthropic']) {
+    const key = resolveProviderApiKey(provider, cwd);
+    if (key) lists[provider] = await fetchAvailableModels(provider, key);
+  }
+  const rows = checkModelDefaults(lists);
+  const gone = rows.filter(r => r.status === 'gone');
+  if (json) {
+    console.log(JSON.stringify({ command: 'models check', ok: gone.length === 0, roles: rows }, null, 2));
+    return gone.length > 0 ? 1 : 0;
+  }
+  output.raw('\n  Default models (shared/model-defaults.json) against the providers\' live lists:\n');
+  for (const r of rows) {
+    const mark = { ok: '[OK]  ', newer: '[NEW] ', gone: '[GONE]', unchecked: '[--]  ' }[r.status];
+    output.raw(`  ${mark} ${r.role.padEnd(10)} ${r.model.padEnd(34)} ${r.note}`);
+  }
+  const unchecked = rows.filter(r => r.status === 'unchecked').map(r => r.provider);
+  if (unchecked.length > 0) {
+    output.raw(`\n  Not checked (no key for ${[...new Set(unchecked)].map(p => getProviderEnvVar(p) || p).join(', ')}): set it to check that provider's list.`);
+  }
+  output.raw('');
+  if (gone.length > 0) {
+    output.error(`${gone.length} default model(s) are no longer listed by their provider — a run on them would fail. `
+      + 'Update shared/model-defaults.json (in the repo: node cli/scripts/check-model-defaults.mjs --update) and release.');
+    return 1;
+  }
+  return 0;
+}

package/lib/config.js

@@ -11,6 +11,7 @@
  * complex setups with custom registers, models, and batch sizes.
  */
 
+import { defaultModel } from './model-defaults.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_REGISTERS, getLanguageCard, getRegister, resolveCode } from './registers.js';
@@ -25,7 +26,8 @@ const CONFIG_FILENAMES = ['champollion.config.json'];
 
 // Canonical defaults — import these in any module that needs a fallback
 // instead of hardcoding the string/number inline.
-const DEFAULT_OPENROUTER_MODEL = 'google/gemini-3.8-flash';
+// shared/model-defaults.json, role "translate" — never written here (lib/model-defaults.js).
+const DEFAULT_OPENROUTER_MODEL = defaultModel('translate');
 const DEFAULT_BATCH_SIZE = 80;
 // Max parallel API calls for JSON key-value translation. 50 is kind to
 // free/low-tier keys on a zero-config first run (200 would hammer 429s).

package/lib/content-refusals.js

@@ -51,6 +51,9 @@
  *   paragraph written by hand — drops its record.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { output } from './output.js';
 import { tmMethodKey, lookupTM } from './tm.js';
 import { GATE_VERSION } from './validate.js';
 import { holdState, shortSourceHash } from './locale-state.js';
@@ -282,3 +285,54 @@ export function previewHeld({ tm, code, pairConfig, fields, body, segMode, holds
   }
   return { names, pageHeld: false };
 }
+
+// ── What a run left in the source language ───────────────────────────
+
+/** Where refused answers are logged (the per-machine cache folder, never committed). */
+export const REFUSAL_LOG = path.join('.champollion', 'refused.jsonl');
+
+/**
+ * Append one refused answer to `.champollion/refused.jsonl`: the source, what
+ * the model answered, and why the gate refused it. WHY: a refused answer was
+ * thrown away, so "why did it refuse that twice?" could only be answered by
+ * paying the model again (2026-10-06 — and the answer then showed the gate,
+ * not the model, was wrong). Never fails the run.
+ *
+ * @param {string} cwd
+ * @param {object} rec - { pair, method, file, locale, paragraph, reason, source, answer }
+ */
+export function logRefusal(cwd, rec) {
+  try {
+    const file = path.join(cwd, REFUSAL_LOG);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), ...rec })}\n`, 'utf-8');
+  } catch { /* a diagnostic: never fails the run */ }
+}
+
+/**
+ * The run's closing report when anything was left in the source language —
+ * last, as an error, never under an [OK] (2026-10-06: a 1,082-page sync ended
+ * on "[OK] Created 1082 content file(s)" with seven untranslated blocks named
+ * only in warnings mid-stream).
+ *
+ * @param {Array<{ file: string, locale: string, pair: string, where: string, reason: string }>} items
+ */
+export function reportLeftInSource(items) {
+  if (!items || items.length === 0) return;
+  const pages = new Map();
+  for (const it of items) {
+    const k = `${it.file}\u0000${it.pair}`;
+    if (!pages.has(k)) pages.set(k, { ...it, wheres: [] });
+    pages.get(k).wheres.push(`${it.where}: ${it.reason}`);
+  }
+  output.raw('');
+  output.error(`Not finished: ${items.length} part(s) of ${pages.size} page translation(s) are still in the source language — `
+    + 'the quality gate refused the model\'s answer, also when asked again with the reason:');
+  for (const p of pages.values()) {
+    output.raw(`    ${p.file} → ${p.locale}: ${p.wheres.slice(0, 3).join('; ')}${p.wheres.length > 3 ? `; +${p.wheres.length - 3} more` : ''}`);
+  }
+  const first = [...pages.values()][0];
+  output.raw(`  The rest of each page is written. What the model answered is in ${REFUSAL_LOG}. `
+    + `Ask again: \`${contentRedoCommand(first.file, { pair: first.pair })}\`${pages.size > 1 ? ' (one per page)' : ''}, `
+    + 'or add a "fallback" method to the pair.');
+}

package/lib/content-sync.js

@@ -89,7 +89,7 @@ import {
 } from './fallback.js';
 import {
   readRefusals, contentHolds, nextRefusals, storeRefusals, blockUnit, fieldUnit, describeHeld, describeNewHold,
-  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME, pendingLockValue, isPendingLock,
+  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME, pendingLockValue, isPendingLock, logRefusal, reportLeftInSource,
 } from './content-refusals.js';
 import { contentRedoCommand } from './verify.js';
 
@@ -115,6 +115,8 @@ import { contentRedoCommand } from './verify.js';
  *   (null = no cap).
  */
 async function runContentSync(options) {
+  // Parts this run left in the source language — reported at the end, as an error.
+  const leftInSource = [];
   const {
     contentDir,
     sourceLocale,
@@ -700,6 +702,11 @@ async function runContentSync(options) {
               // field keeps its source text; the page is still written.
               fieldsLeftInSource = true;
               for (const h of fm.hollowed) {
+                leftInSource.push({ file: relPath, locale: code, pair: pairKey, where: `front matter "${h.field}"`, reason: h.reason });
+                logRefusal(cwd, {
+                  pair: pairKey, method: tmMethodKey(pairConfig), file: relPath, locale: code,
+                  field: h.field, reason: h.reason, source: fieldsToTranslate[h.field], answer: h.value ?? null,
+                });
                 const advice = h.sharedOutput
                   ? ` ${pairConfig.method} answers it only with a sentence it gave for other strings — `
                     + `${pairConfig.fallback ? 'and the fallback did not translate it either' : 'add a "fallback" method to the pair'}, or write it in ${targetRel} by hand (kept).`
@@ -990,6 +997,13 @@ async function runContentSync(options) {
                 // Blocks the quality gate refused — the key-value gate's checks
                 // (length inflation, echo, truncation, script), per block.
                 const refusedByGate = batchOutcome.refused || [];
+                for (const r of refusedByGate) {
+                  leftInSource.push({ file: relPath, locale: code, pair: pairKey, where: `paragraph ${r.block}`, reason: r.reason });
+                  logRefusal(cwd, {
+                    pair: pairKey, method: tmMethodKey(pairConfig), file: relPath, locale: code,
+                    paragraph: r.block, reason: r.reason, source: missed[r.i].source, answer: r.answer,
+                  });
+                }
                 if (refusedByGate.length > 0) {
                   output.warn(
                     `Content sync body for ${code}: ${refusedByGate.length} block(s) of ${relPath} refused by the quality gate, also when asked again with the reason — `
@@ -1210,9 +1224,11 @@ async function runContentSync(options) {
       const heldBackNote = heldBackSeen > 0 ? `; ${heldBackSeen} block(s)/field(s) refused before would be held back (not sent)` : '';
       output.info(`Would have created ${totalCreated} content file(s)${retranslateNote}${keptNote}, ${skipped} unchanged${heldNote}${heldBackNote}.`);
     } else {
-      output.ok(`Created ${totalCreated} content file(s)${retranslateNote}${keptNote}, ${skipped} unchanged${heldNote}.`);
+      const unfinished = leftInSource.length > 0 ? ` — ${leftInSource.length} part(s) left in the source language (below)` : '';
+      (unfinished ? output.warn : output.ok).call(output, `Created ${totalCreated} content file(s)${retranslateNote}${keptNote}, ${skipped} unchanged${heldNote}${unfinished}.`);
     }
   }
+  reportLeftInSource(leftInSource);
   if (heldBack > 0) {
     // Not sent, not billed — but not translated either (exit 2, as for a
     // held-back key). Each page was named above with its own repair.

package/lib/docusaurus-sync.js

@@ -74,7 +74,7 @@ import {
 import { walkFiles } from './locale-layout.js';
 import {
   readRefusals, contentHolds, nextRefusals, storeRefusals, blockUnit, fieldUnit, describeHeld, describeNewHold,
-  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME, pendingLockValue, isPendingLock,
+  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME, pendingLockValue, isPendingLock, logRefusal, reportLeftInSource,
 } from './content-refusals.js';
 import { applyNamedKeyRule, reportUnmatchedKeys, unmatchedKeysSummary, reportNamedFromCache } from './named-keys.js';
 
@@ -1209,6 +1209,8 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
   let contentHeldBack = 0;
   const contentHeldBackItems = [];
   let contentRefused = 0;
+  // Parts this run left in the source language — said last, as an error.
+  const leftInSource = [];
 
   if (contentSources.length === 0) {
     output.info('No docs/ or blog/ directories found — skipping content sync.');
@@ -1443,6 +1445,11 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                 // field keeps its source text; the page is still written.
                 fieldsLeftInSource = true;
                 for (const h of fm.hollowed) {
+                  leftInSource.push({ file: label, locale: code, pair: pairKey, where: `front matter "${h.field}"`, reason: h.reason });
+                  logRefusal(cwd, {
+                    pair: pairKey, method: tmMethodKey(pairConfig), file: label, locale: code,
+                    field: h.field, reason: h.reason, source: fieldsToTranslate[h.field], answer: h.value ?? null,
+                  });
                   output.warn(
                     `${label} → ${code}: front matter "${h.field}" kept in the source language — ${h.reason}`
                     + `${h.fallbackReason ? `; the fallback (${pairConfig.fallback.method}): ${h.fallbackReason}` : ''}.`
@@ -1666,6 +1673,13 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                       'the model gave for other, different source strings (a memorized sentence, not a translation) — refused.'
                     );
                   }
+                  for (const r of outcome.refused || []) {
+                    leftInSource.push({ file: `${dirName}/${relPath}`, locale: code, pair: pairKey, where: `paragraph ${r.block}`, reason: r.reason });
+                    logRefusal(cwd, {
+                      pair: pairKey, method: tmMethodKey(pairConfig), file: `${dirName}/${relPath}`, locale: code,
+                      paragraph: r.block, reason: r.reason, source: missed[r.i].source, answer: r.answer,
+                    });
+                  }
                   if ((outcome.refused || []).length > 0) {
                     output.warn(
                       `Docusaurus body for ${code}: ${outcome.refused.length} block(s) of ${dirName}/${relPath} refused by the quality gate, also when asked again with the reason — `
@@ -1845,7 +1859,8 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
     if (totalContent > 0 || totalContentSkipped > 0 || totalContentRetranslated > 0) {
       const action = dryRun ? 'Would create' : 'Created';
       const retranslateNote = totalContentRetranslated > 0 ? ` (${totalContentRetranslated} re-translated)` : '';
-      output.ok(`${action} ${totalContent} content file(s)${retranslateNote}, ${totalContentSkipped} unchanged`);
+      const unfinished = leftInSource.length > 0 ? ` — ${leftInSource.length} part(s) left in the source language (below)` : '';
+      (unfinished ? output.warn : output.ok).call(output, `${action} ${totalContent} content file(s)${retranslateNote}, ${totalContentSkipped} unchanged${unfinished}`);
     }
 
     contentTranslated = totalContent;
@@ -1891,6 +1906,10 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
     saveTM(cwd, tm);
     output.info(`[TM] Saved ${describeTMChanges(tm)} this sync`);
   }
+  {
+    // Last, so it is the run's closing word: what is still untranslated.
+    reportLeftInSource(leftInSource);
+  }
 
   // Failures are reported, not thrown: a partly failed run still did real
   // work, and the exit code says so (2 = partial, 1 = nothing succeeded).

package/lib/fallback.js

@@ -572,7 +572,8 @@ export async function translateFieldsWithFallback({
         if (typeof value !== 'string') continue;
         const f = failed.get(field);
         const fault = contentGateFault(fields[field], value, pairConfig);
-        const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(f.reason) && value === f.value;
+        const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(f.reason)
+          && [f.value, fields[field]].some(v => sameAnswer(v, value));
         if (!fault || insisted) againPassing.push([field, value]);
         else f.reason = `${f.reason}; asked again with that reason: ${fault}`;
       }
@@ -698,6 +699,17 @@ export function blockFault(protectedSource, protectedOut, restoredOut, restoredS
   return contentGateFault(restoredSource, restoredOut, pairConfig);
 }
 
+/**
+ * The same answer, give or take spacing and closing punctuation: a citation
+ * kept as written once with its final "." and once without was refused as a
+ * changed answer (dogfood 2026-10-06, a Thai reference) — the model had said
+ * "keep it" twice.
+ */
+function sameAnswer(a, b) {
+  const norm = (v) => String(v ?? '').replace(/\s+/g, ' ').trim().replace(/[.,;:!?。、]+$/u, '');
+  return norm(a) === norm(b);
+}
+
 /**
  * Ask the pair's method once more for the blocks the gate refused, telling it
  * why. WHY: a refusal used to be final for the run, and the block was left in
@@ -708,8 +720,9 @@ export function blockFault(protectedSource, protectedOut, restoredOut, restoredS
  * reason, the model either translates it or returns it unchanged again — and
  * a keep-as-written refusal (isKeepAsWrittenFault) answered the same way
  * twice is taken at its word, as the key-value lane takes a name. Every other
- * fault must clear the gate outright. One ask, never a loop; under --max-cost
- * it is billed like any other call (budget.approve).
+ * fault must clear the gate outright. One ask per block, alone (not in the
+ * page's batch), never a loop; under --max-cost it is billed like any other
+ * call (budget.approve).
  *
  * @param {object} p
  * @param {number[]} p.idx - Indices (into `missed`) the gate refused
@@ -724,7 +737,7 @@ export function blockFault(protectedSource, protectedOut, restoredOut, restoredS
  * @param {object|null} [p.budget]
  * @returns {Promise<Map<number,string>>} index → accepted (restored) answer
  */
-async function retryRefusedBlocks({ idx, texts, missed, blocks, pairConfig, runBatch, firstOut, reasons, budget = null }) {
+async function retryRefusedBlocks({ idx, texts, missed, blocks, pairConfig, runBatch, firstOut, reasons, answers = null, budget = null }) {
   const accepted = new Map();
   if (idx.length === 0) return accepted;
   // An endpoint that declares it follows no instructions (a trained NMT
@@ -740,20 +753,33 @@ async function retryRefusedBlocks({ idx, texts, missed, blocks, pairConfig, runB
     if (!verdict.ok) return accepted;
   }
   const retryNotes = new Map(idx.map(i => [texts[i], reasons.get(i)]));
-  let res = null;
-  try {
-    res = await runBatch(idx.map(i => texts[i]), { ...pairConfig, retryNotes });
-  } catch {
-    return accepted;
-  }
-  const fell = new Set(res?.fellBack || []);
-  idx.forEach((i, j) => {
-    if (!res || fell.has(j) || typeof res.blocks[j] !== 'string') return;
-    const restored = restoreBlocks(res.blocks[j], blocks);
-    const fault = blockFault(texts[i], res.blocks[j], restored, missed[i].source, pairConfig);
-    const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(reasons.get(i)) && restored === firstOut.get(i);
+  // Each block alone: away from the page's other segments, the model has one
+  // thing to do (and one reason to read). Refusals are rare, so the extra
+  // requests cost next to nothing; at most 4 at a time.
+  const answers1 = new Map();
+  let next = 0;
+  const worker = async () => {
+    while (next < idx.length) {
+      const i = idx[next++];
+      try {
+        const res = await runBatch([texts[i]], { ...pairConfig, retryNotes });
+        if (res && !(res.fellBack || []).includes(0) && typeof res.blocks[0] === 'string') answers1.set(i, res.blocks[0]);
+      } catch { /* no second answer for this block */ }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, idx.length) }, worker));
+  idx.forEach((i) => {
+    if (!answers1.has(i)) return;
+    const protectedOut = answers1.get(i);
+    const restored = restoreBlocks(protectedOut, blocks);
+    const fault = blockFault(texts[i], protectedOut, restored, missed[i].source, pairConfig);
+    const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(reasons.get(i))
+      && [firstOut.get(i), missed[i].source].some(v => sameAnswer(v, restored));
     if (!fault || insisted) accepted.set(i, restored);
-    else reasons.set(i, `${reasons.get(i)}; asked again with that reason: ${fault}`);
+    else {
+      reasons.set(i, `${reasons.get(i)}; asked again with that reason: ${fault}`);
+      if (answers) answers.set(i, restored);
+    }
   });
   return accepted;
 }
@@ -828,9 +854,13 @@ export async function translateBlocksWithFallback({
   };
   // Why the gate refused a block (index → reason), for the lane's warning.
   const refusedReason = new Map();
+  // The last answer the gate refused, per block — kept for the refusal log
+  // (.champollion/refused.jsonl), so "why was this refused?" can be read off
+  // what the model actually said instead of asked again.
+  const refusedAnswer = new Map();
   /** Blocks left as their source text because the gate refused them. */
   const refusedList = (fellBack) => fellBack.filter(i => refusedReason.has(i))
-    .map(i => ({ i, block: (Number.isInteger(missed[i].pos) ? missed[i].pos : i) + 1, reason: refusedReason.get(i) }));
+    .map(i => ({ i, block: (Number.isInteger(missed[i].pos) ? missed[i].pos : i) + 1, reason: refusedReason.get(i), answer: refusedAnswer.get(i) ?? null }));
 
   if (!fb) {
     const { blocks: translatedBlocks, fellBack } = await runBatch(texts, pairConfig);
@@ -841,14 +871,14 @@ export async function translateBlocksWithFallback({
     for (let i = 0; i < outs.length; i++) {
       if (fellSet.has(i)) continue;
       const fault = contentGateFault(missed[i].source, outs[i], pairConfig);
-      if (fault) refusedReason.set(i, fault);
+      if (fault) { refusedReason.set(i, fault); refusedAnswer.set(i, outs[i]); }
     }
     const shared = sharedFault(outs.map((out, i) => ({ i, out })).filter(({ i }) => !fellSet.has(i) && !refusedReason.has(i)));
     for (const i of shared) refusedReason.set(i, 'the same text the model gave for other, different source strings');
     // Refused: asked once more, with the reason.
     const again = await retryRefusedBlocks({
       idx: [...refusedReason.keys()], texts, missed, blocks, pairConfig, runBatch,
-      firstOut: new Map([...refusedReason.keys()].map(i => [i, outs[i]])), reasons: refusedReason, budget,
+      firstOut: new Map([...refusedReason.keys()].map(i => [i, outs[i]])), reasons: refusedReason, answers: refusedAnswer, budget,
     });
     const againShared = sharedFault([...again].map(([i, out]) => ({ i, out })));
     for (const [i, out] of again) {
@@ -914,6 +944,7 @@ export async function translateBlocksWithFallback({
       const fault = blockFault(texts[i], primary.blocks[i], restored, missed[i].source, pairConfig);
       if (fault) {
         refusedReason.set(i, fault);
+        refusedAnswer.set(i, restored);
         primaryRefused.add(i);
         failed.push(i);
         continue;
@@ -934,7 +965,7 @@ export async function translateBlocksWithFallback({
       if (refusedReason.has(i)) firstOut.set(i, restoreBlocks(primary.blocks[i], blocks));
     }
     const again = await retryRefusedBlocks({
-      idx: [...firstOut.keys()], texts, missed, blocks, pairConfig, runBatch, firstOut, reasons: refusedReason, budget,
+      idx: [...firstOut.keys()], texts, missed, blocks, pairConfig, runBatch, firstOut, reasons: refusedReason, answers: refusedAnswer, budget,
     });
     const againShared = sharedFault([...again].map(([i, out]) => ({ i, out })));
     const recovered = new Set();
@@ -1015,6 +1046,7 @@ export async function translateBlocksWithFallback({
       if (!fbFault) fbGood.push({ i, out: restored });
       else {
         refusedReason.set(i, refusedReason.has(i) ? `${refusedReason.get(i)}; the fallback's answer: ${fbFault}` : `the fallback's answer: ${fbFault}`);
+        refusedAnswer.set(i, restored);
         fallbackRefused.add(i);
       }
     }

package/lib/methods/anthropic.js

@@ -13,6 +13,7 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
@@ -21,7 +22,7 @@ import { estimateLlmCost } from './provider-pricing.js';
 // _getDefaultModel() and again as an inline `pairConfig.model || '...'`
 // fallback in estimateCost() — so the two could drift and price a run
 // against a model it did not use.
-const DEFAULT_MODEL = 'claude-sonnet-4-6';
+const DEFAULT_MODEL = defaultModel('anthropic'); // shared/model-defaults.json
 
 class AnthropicMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/methods/gemini.js

@@ -12,13 +12,14 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
 
 // The default model, named ONCE — it was previously written twice (here and
 // as an inline fallback in estimateCost()) and the two could drift.
-const DEFAULT_MODEL = 'gemini-3.8-flash';
+const DEFAULT_MODEL = defaultModel('gemini'); // shared/model-defaults.json
 
 class GeminiMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/methods/openai.js

@@ -13,15 +13,16 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
 
 // The default model, named ONCE — it was previously written twice (here and
 // as an inline fallback in estimateCost()) and the two could drift.
-// A dated snapshot: plain 'gpt-4o' was an alias OpenAI repoints (founder
-// ruling 2026-10-05: exact model ids only, nothing floating).
-const DEFAULT_MODEL = 'gpt-5.4-mini-2026-03-17';
+// shared/model-defaults.json: a dated snapshot (plain 'gpt-4o' was an alias
+// OpenAI repoints — founder ruling 2026-10-05: exact model ids only).
+const DEFAULT_MODEL = defaultModel('openai');
 
 class OpenAIMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/model-defaults.js

@@ -0,0 +1,113 @@
+/**
+ * model-defaults.js — the ONE place a default model comes from.
+ *
+ * WHY: the toolset's defaults were ten hand-written ids in seven files across
+ * five components (CLI, its three direct providers, the harness, forge, the
+ * MCP server, the site docent). Nothing kept them in step, so they drifted —
+ * the docent still named an undated `claude-haiku-4-5` after every other
+ * default had been made exact (founder, 2026-10-07: "we're gonna be getting
+ * our wires crossed no matter what doing it that way"). Every default now
+ * reads shared/model-defaults.json (bundled here as shared/model-defaults.json).
+ *
+ * A default is an exact id, fixed in that file — never resolved at run time:
+ * a run must say which model translated, and the translation memory is keyed
+ * by model, so a default that moved by itself would re-bill every cached
+ * string. What IS live is the check: `champollion models check` reads each
+ * provider's current list, fails when a pinned id is gone, and names the
+ * newest model each role's rule matches today.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FILE = path.join(__dirname, '..', 'shared', 'model-defaults.json');
+
+let _data = null;
+
+/** The parsed file. Missing or malformed is a broken install: fail loud. */
+export function modelDefaultsData() {
+  if (_data) return _data;
+  let raw;
+  try {
+    raw = fs.readFileSync(FILE, 'utf-8');
+  } catch (err) {
+    throw new Error(`${FILE} is missing (${err.code || err.message}): it names every default model. Reinstall champollion.`);
+  }
+  const data = JSON.parse(raw);
+  if (!data || typeof data.roles !== 'object') throw new Error(`${FILE} has no "roles" — it is not a model-defaults file.`);
+  _data = data;
+  return data;
+}
+
+/**
+ * The exact default model id for a role ("translate", "openai", "gemini",
+ * "anthropic", "harness", "docent"). Unknown role: a programming error.
+ *
+ * @param {string} role
+ * @returns {string}
+ */
+export function defaultModel(role) {
+  const r = modelDefaultsData().roles[role];
+  if (!r || typeof r.model !== 'string' || !r.model) throw new Error(`model-defaults.json has no "${role}" role.`);
+  return r.model;
+}
+
+/** Version string → comparable number array ("4-6" / "4.6" → [4, 6]). */
+function versionKey(v) {
+  return String(v || '0').split(/[.-]/).map((n) => Number(n) || 0);
+}
+
+function compareIds(a, b) {
+  const [va, vb] = [versionKey(a.v), versionKey(b.v)];
+  for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+    if ((va[i] || 0) !== (vb[i] || 0)) return (va[i] || 0) - (vb[i] || 0);
+  }
+  return String(a.date || '').localeCompare(String(b.date || ''));
+}
+
+/**
+ * The newest id in a provider's live list that a role's rule matches, or null.
+ *
+ * @param {object} role - A roles[] entry ({ rule: { match } })
+ * @param {string[]} ids - The provider's live model ids
+ * @returns {string|null}
+ */
+export function ruleCandidate(role, ids) {
+  const re = new RegExp(role.rule.match);
+  const hits = [];
+  for (const id of ids || []) {
+    const m = re.exec(id);
+    if (m) hits.push({ id, v: m.groups?.v, date: m.groups?.date });
+  }
+  if (hits.length === 0) return null;
+  hits.sort(compareIds);
+  return hits[hits.length - 1].id;
+}
+
+/**
+ * Check every role against live lists.
+ *
+ * @param {Record<string, string[]|null>} lists - provider → live ids (null = could not be read)
+ * @returns {Array<{ role: string, provider: string, model: string, status: 'ok'|'newer'|'gone'|'unchecked', candidate: string|null, note: string }>}
+ */
+export function checkModelDefaults(lists) {
+  const out = [];
+  for (const [name, role] of Object.entries(modelDefaultsData().roles)) {
+    const ids = lists[role.provider];
+    if (!ids) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'unchecked', candidate: null, note: `${role.provider}'s model list could not be read` });
+      continue;
+    }
+    const candidate = ruleCandidate(role, ids);
+    if (!ids.includes(role.model)) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'gone', candidate, note: `${role.model} is no longer in ${role.provider}'s list${candidate ? ` — the rule's model today: ${candidate}` : ''}` });
+    } else if (candidate && candidate !== role.model) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'newer', candidate, note: `a newer model matches the rule: ${candidate}` });
+    } else {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'ok', candidate, note: 'listed' });
+    }
+  }
+  return out;
+}