champollion 0.3.4 → 0.4.0

package/lib/commands/integrity.js

@@ -9,18 +9,47 @@
  */
 
 import fs from 'node:fs';
-import path from 'node:path';
 import { resolveConfig } from '../config.js';
-import { auditLocalePair, formatIntegrityReport } from '../integrity.js';
+import { auditLocalePair, formatIntegrityReport, auditARBDocument } from '../integrity.js';
 import { compileNoTranslate } from '../no-translate.js';
 import { resolvePairs } from '../pairs.js';
-import { loadTM, lookupTM, tmMethodKey } from '../tm.js';
+import { loadTM, saveTM, isTMDirty } from '../tm.js';
+import { tmTextFor, tmProofTextsFor, createTMEvictor } from '../tm-evict.js';
+import { poPluralSlots } from '../po.js';
+import { tmKeysForPair, tmHoldsValue } from '../fallback.js';
 import { getLanguageCard } from '../registers.js';
 import { SCRIPT_CONVERTERS, converterKeyForLocale } from '../scripts.js';
-import { flattenKeys } from '../flatten.js';
-import { readLocaleFile, detectFormatFromDir, getExtension } from '../format.js';
+import {
+  discoverLocaleLayout, loadSourceUnits, expectedForTarget, readLocaleFlat, NS_SEPARATOR,
+} from '../locale-layout.js';
 import { output } from '../output.js';
 
+/**
+ * Fold one file's audit into a locale's running audit. In a namespaced
+ * layout every key is reported as "<ns>::<key>" so two files' findings for
+ * "title" stay distinguishable (same convention as the lock manifest).
+ *
+ * @param {object|null} into - Accumulated audit (null to start one)
+ * @param {object} audit - auditLocalePair() result for one file
+ * @param {string|null} ns - Namespace to prefix, or null for single-file layouts
+ * @returns {object} Merged audit
+ */
+function mergeAudits(into, audit, ns) {
+  const tag = (k) => (ns === null ? k : `${ns}${NS_SEPARATOR}${k}`);
+  const out = into || {
+    placeholderIssues: [], encodingIssues: [], copies: [], orphans: [], noTranslateDrift: [],
+    unexpectedPua: [], hollowedValues: [], icuIssues: [], documentIssues: [], pluralIssues: [], pluralNotes: [], bomFiles: [],
+  };
+  for (const field of ['placeholderIssues', 'encodingIssues', 'noTranslateDrift', 'unexpectedPua', 'hollowedValues', 'icuIssues', 'documentIssues', 'pluralIssues', 'pluralNotes']) {
+    for (const item of audit[field] || []) out[field].push({ ...item, key: tag(item.key) });
+  }
+  for (const field of ['copies', 'orphans']) {
+    for (const key of audit[field] || []) out[field].push(tag(key));
+  }
+  out.bomFiles.push(...(audit.bomFiles || []));
+  return out;
+}
+
 /**
  * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
  * @param {string} cwd - Working directory
@@ -46,9 +75,17 @@ async function run(args, cwd) {
   // applies; without it, integrity reported thousands of "untranslated
   // copies" on a project sync calls fully synced. Read-only TM load.
   const tm = loadTM(cwd);
+  // Damaged values the TM proves the pipeline wrote are evicted from it, so
+  // the `sync --force-keys` the report names re-translates them instead of
+  // re-serving the damage for free (lib/tm-evict.js). Hand-written values
+  // have no equal cache entry and are never touched.
+  const evictor = createTMEvictor(tm);
+  let tmEvicted = 0;
   const tmKeys = new Map();
-  for (const [, pc] of resolvePairs(config)) {
-    tmKeys.set(pc.target, tmMethodKey(pc));
+  for (const [, pc] of resolvePairs(config, { cwd })) {
+    // The pair's own key, then its fallback's: a value the fallback
+    // produced is cached under the fallback (lib/fallback.js).
+    tmKeys.set(pc.target, tmKeysForPair(pc));
     const key = converterKeyForLocale(pc.target, getLanguageCard(pc.target));
     if (!key || !SCRIPT_CONVERTERS[key].puaRange) continue;
     scriptExpectations.set(pc.target, {
@@ -57,57 +94,93 @@ async function run(args, cwd) {
     });
   }
 
-  const format = config.format !== 'auto'
-    ? config.format
-    : detectFormatFromDir(config.localesDir);
-  const ext = getExtension(format);
-  const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
-
-  if (!fs.existsSync(sourcePath)) {
+  // The project's files, per locale, from the ONE layout module (flat,
+  // folder per locale, or localesPattern).
+  const layout = discoverLocaleLayout(config, { cwd });
+  const sourceMissing = layout.namespaced
+    ? layout.sourceFiles.length === 0
+    : !fs.existsSync(layout.sourceFiles[0].path);
+  if (sourceMissing) {
+    const where = layout.namespaced
+      ? `${layout.display} (no ${layout.format} files for ${config.inputLocale})`
+      : layout.sourceFiles[0].path;
     if (json) {
       console.log(JSON.stringify({
         command: 'integrity',
-        error: `Source locale file not found: ${sourcePath}`,
+        error: `Source locale file not found: ${where}`,
       }, null, 2));
       return 1;
     }
-    output.error(`Source locale file not found: ${sourcePath}`);
+    output.error(`Source locale file not found: ${where}`);
     return 1;
   }
 
-  const sourceRaw = readLocaleFile(sourcePath, format);
-  const sourceFlat = format === 'json' ? flattenKeys(sourceRaw) : sourceRaw;
+  const units = loadSourceUnits(layout);
+  const sourceKeyCount = units.reduce((n, u) => n + Object.keys(u.flat).length, 0);
 
-  // Detect target locales from directory listing
-  const files = fs.readdirSync(config.localesDir);
-  const targetLocales = files
-    .filter(f => f.endsWith(ext) && !f.startsWith(config.inputLocale))
-    .map(f => f.replace(ext, ''));
+  // Target locales present on disk — EXACT code match. The old prefix test
+  // (`!f.startsWith(inputLocale)`) silently skipped en-GB/en-AU when the
+  // source was en, so those files were never audited.
+  const targetLocales = layout.listLocales();
 
   output.raw('\n  champollion integrity — Locale File Audit\n');
-  output.raw(`  Source: ${config.inputLocale} (${Object.keys(sourceFlat).length} keys)`);
+  output.raw(`  Source: ${config.inputLocale} (${sourceKeyCount} keys)`);
   output.raw(`  Targets: ${targetLocales.join(', ')}\n`);
 
   let totalIssues = 0;
+
+  let totalAdvisory = 0;
   const localeReports = [];
 
   for (const locale of targetLocales) {
-    const targetPath = path.join(config.localesDir, `${locale}${ext}`);
-    const targetRaw = readLocaleFile(targetPath, format);
-    const targetFlat = format === 'json' ? flattenKeys(targetRaw) : targetRaw;
-
-    const tmKey = tmKeys.get(locale) || null;
-    const audit = auditLocalePair(sourceFlat, targetFlat, locale, {
-      noTranslate,
-      scriptExpectation: scriptExpectations.get(locale) || null,
-      isConfirmedEcho: tmKey
-        ? (key, sourceValue) => lookupTM(tm, sourceValue, locale, tmKey) === sourceValue
-        : null,
-    });
+    const localeTmKeys = tmKeys.get(locale) || null;
+    // A borrowed i18next plural form is cached under its own text (tmTextFor).
+    const confirmedEchoFor = (expansion) => (localeTmKeys
+      ? (key, sourceValue) => tmHoldsValue(tm, tmTextFor(key, sourceValue, expansion), locale, localeTmKeys, sourceValue)
+      : null);
+    // One audit per file; namespaced keys ("common::nav.home") keep the
+    // per-file findings apart in the merged locale report.
+    let audit = null;
+    for (const unit of units) {
+      const file = layout.fileFor(locale, unit.ns);
+      if (!fs.existsSync(file.path) && !layout.namespaced) continue;
+      const targetFlat = fs.existsSync(file.path) ? readLocaleFlat(file) : {};
+      // Judge the file by the keys this locale should have — i18next
+      // plurals expand to the target's own CLDR categories.
+      const { flat: expected, expansion } = expectedForTarget(unit, config.inputLocale, locale);
+      const fileAudit = auditLocalePair(expected, targetFlat, locale, {
+        noTranslate,
+        scriptExpectation: scriptExpectations.get(locale) || null,
+        isConfirmedEcho: confirmedEchoFor(expansion),
+        // A gettext catalog holds only the plural forms its header has slots for.
+        pluralSlots: file.format === 'po' && fs.existsSync(file.path)
+          ? poPluralSlots(fs.readFileSync(file.path, 'utf-8'), locale) : null,
+      });
+      fileAudit.documentIssues = file.format === 'arb' && fs.existsSync(file.path)
+        ? auditARBDocument(unit.file.path, file.path, locale)
+        : [];
+      // Values damaged in a way the quality gate now refuses: evict the TM
+      // entries that produced them.
+      const damaged = [
+        ...fileAudit.icuIssues.map(i => [i.key, i.actual]),
+        ...fileAudit.placeholderIssues.map(i => [i.key, i.targetVal]),
+        ...fileAudit.hollowedValues.map(i => [i.key, i.actual]),
+      ];
+      for (const [key, value] of damaged) {
+        if (typeof expected[key] !== 'string') continue;
+        for (const text of tmProofTextsFor(key, expected[key], expansion)) {
+          tmEvicted += evictor.evictProducing(text, locale, value, localeTmKeys || []);
+        }
+      }
+      // Single-file layouts keep auditLocalePair's own result object (and
+      // its exact shape in --json); namespaced ones merge with ns tags.
+      audit = layout.namespaced ? mergeAudits(audit, fileAudit, unit.ns) : fileAudit;
+    }
+    if (!audit) continue;
     const report = formatIntegrityReport(locale, audit);
     output.raw(report);
 
-    // Only these five categories drive the exit code (pluralIssues and
+    // Only these categories drive the exit code (pluralIssues and
     // bomFiles are reported but advisory) — issueCount matches that.
     //
     // noTranslateDrift is an error, not advisory: a declared-verbatim key
@@ -124,21 +197,35 @@ async function run(args, cwd) {
       audit.orphans.length +
       audit.noTranslateDrift.length +
       audit.unexpectedPua.length +
-      audit.hollowedValues.length;
+      audit.hollowedValues.length +
+      // ICU structure damage and ARB document damage break the app at
+      // runtime / build time — errors, like the hollowed values.
+      (audit.icuIssues?.length || 0) +
+      (audit.documentIssues?.length || 0);
     totalIssues += issueCount;
+    totalAdvisory += (audit.pluralIssues?.length || 0) + (audit.bomFiles?.length || 0);
     localeReports.push({ locale, issues: audit, issueCount });
   }
 
-  output.raw(`  Total issues: ${totalIssues}`);
+  // Advisory findings (plural categories, BOMs) don't fail the run, but a
+  // bare "Total issues: 0" under a printed warning read as a contradiction.
+  output.raw(`  Total issues: ${totalIssues}`
+    + (totalAdvisory > 0 ? ` (+${totalAdvisory} advisory, listed above — they don't fail the check)` : ''));
+  if (tmEvicted > 0 && isTMDirty(tm)) {
+    saveTM(cwd, tm);
+    output.raw(`  [TM] Evicted ${tmEvicted} cached translation(s) that produced damaged values — `
+      + '`champollion sync --force-keys <key>` now re-translates them instead of re-serving them.');
+  }
 
   const exitCode = (totalIssues > 0 && !args['warn-only']) ? 1 : 0;
   if (json) {
     console.log(JSON.stringify({
       command: 'integrity',
       source: config.inputLocale,
-      sourceKeys: Object.keys(sourceFlat).length,
+      sourceKeys: sourceKeyCount,
       locales: localeReports,
       totalIssues,
+      tmEvicted,
       warnOnly: !!args['warn-only'],
     }, null, 2));
   }

package/lib/commands/leaderboard.js

@@ -6,8 +6,8 @@
  *
  * Usage:
  *   champollion leaderboard                      # Show all results
- *   champollion leaderboard --pair "en>crk"       # Filter by language pair (quote the >)
- *   champollion leaderboard --sort composite      # Sort by composite score
+ *   champollion leaderboard --pair "eng>crk"      # Filter by language pair (quote the >; eng-crk works too)
+ *   champollion leaderboard --sort bleu           # Sort by BLEU (default: chrF++)
  *   champollion leaderboard --json                # Machine-readable NDJSON
  *   champollion leaderboard --top 5               # Show top N results
  *   champollion leaderboard --install 1           # Install method config from rank 1
@@ -15,7 +15,8 @@
  */
 
 import { output } from '../output.js';
-import { getLanguageCard } from '../registers.js';
+import { getLanguageCard, resolveCode } from '../registers.js';
+import { parseLanguagePair, formatLanguagePair } from '../language-pair.js';
 // Supabase public config — shared with the dynamic card loader
 // (RLS restricts the anon role to read-only)
 import { SUPABASE_URL, SUPABASE_ANON_KEY } from '../cards/env.js';
@@ -26,31 +27,74 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Sortable metric definitions.
- * key: CLI flag value   →   column: Supabase column   →   label: Display header
+ * Scoring standard/1 (founder, 2026-10-04: "we want scoring to be industry
+ * standard"). As in WMT, FLORES-200 and AmericasNLP: ONE headline and ranking
+ * metric, chrF++ with its 95% bootstrap CI; the other standard metrics (BLEU,
+ * spBLEU, TER, COMET) beside it, never blended; diagnostics apart, never a
+ * headline or a default sort; no quality labels read off automatic scores.
+ * A run card declares `scores.scoring_standard`; a card without it is legacy,
+ * and only a legacy card's stored composite is ever shown — labelled
+ * "legacy composite (retired)".
  */
-const SORT_KEYS = {
-  composite:   { column: 'composite_score',     label: 'Composite',    desc: true },
-  chrf:        { column: 'chrf_plus_plus',      label: 'chrF++',       desc: true },
-  exact:       { column: 'exact_match_rate',     label: 'Exact Match',  desc: true },
-  fst:         { column: 'fst_acceptance_rate',  label: 'FST Accept',   desc: true },
-  equivalent:  { column: 'equivalent_match_rate', label: 'Equiv Match', desc: true },
-  semantic:    { column: 'semantic_score',       label: 'Semantic',     desc: true },
-  cost:        { column: 'total_cost_usd',       label: 'Cost (USD)',   desc: false },
-  date:        { column: 'run_timestamp',        label: 'Date',         desc: true },
-};
+const SCORING_STANDARD = 'standard/1';
+const LEGACY_COMPOSITE_LABEL = 'legacy composite (retired)';
+const DEFAULT_SORT = 'chrf';
 
 /**
- * Quality tier → display label with color hint.
+ * Sortable metric definitions.
+ * key: CLI flag value → column: Supabase column → label: display header →
+ * group: standard | diagnostic | legacy | other. Metrics sort best-first
+ * (desc), TER lowest-first; nulls always last.
  */
-const TIER_LABELS = {
-  baseline:    '○ Baseline',
-  emerging:    '◔ Emerging',
-  functional:  '◑ Functional',
-  deployable:  '◕ Deployable',
-  fluent:      '● Fluent',
+const SORT_KEYS = {
+  chrf:        { column: 'chrf_plus_plus',        label: 'chrF++',        desc: true,  group: 'standard' },
+  bleu:        { column: 'corpus_bleu',           label: 'BLEU',          desc: true,  group: 'standard' },
+  ter:         { column: 'ter',                   label: 'TER (lower is better)', desc: false, group: 'standard' },
+  comet:       { column: 'comet_score',           label: 'COMET',         desc: true,  group: 'standard' },
+  exact:       { column: 'exact_match_rate',      label: 'Exact Match (diagnostic)',  desc: true, group: 'diagnostic' },
+  fst:         { column: 'fst_acceptance_rate',   label: 'FST Accept (diagnostic)',   desc: true, group: 'diagnostic' },
+  equivalent:  { column: 'equivalent_match_rate', label: 'Equiv Match (diagnostic)',  desc: true, group: 'diagnostic' },
+  semantic:    { column: 'semantic_score',        label: 'Semantic (diagnostic)',     desc: true, group: 'diagnostic' },
+  cost:        { column: 'total_cost_usd',        label: 'Cost (USD)',    desc: false, group: 'other' },
+  date:        { column: 'run_timestamp',         label: 'Date',          desc: true,  group: 'other' },
+  // Kept so an existing `--sort composite` keeps working: it orders by the
+  // retired composite, which standard/1 cards do not carry (they sort last).
+  composite:   { column: 'composite_score',       label: 'Legacy composite (retired)', desc: true, group: 'legacy' },
 };
 
+/** True when the run card predates standard/1 (no scores.scoring_standard). */
+function isLegacyRow(row) {
+  return !row?.run_card?.scores?.scoring_standard;
+}
+
+/** A finite number or null (JSON-extracted values may be strings). */
+function num(v) {
+  if (v == null || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** [lo, hi] of the chrF++ 95% CI, or null when either bound is missing. */
+function chrfCi(row) {
+  const lo = num(row.chrf_ci_lower);
+  const hi = num(row.chrf_ci_upper);
+  return lo != null && hi != null ? [lo, hi] : null;
+}
+
+/** "47.5 [45.9, 49.0]" — the chrF++ headline with its CI (no label). */
+function fmtChrf(row) {
+  const v = num(row.chrf_plus_plus);
+  if (v == null) return '—';
+  const ci = chrfCi(row);
+  return ci ? `${v.toFixed(1)} [${ci[0].toFixed(1)}, ${ci[1].toFixed(1)}]` : v.toFixed(1);
+}
+
+/** The stored composite of a LEGACY card, else null (never a headline). */
+function legacyComposite(row) {
+  const c = num(row.composite_score);
+  return c != null && isLegacyRow(row) ? c : null;
+}
+
 // ---------------------------------------------------------------------------
 // Contamination lane — FAIL SAFE. The lane policy lives in
 // lib/contamination-lane.js (the CLI-side mirror of the SSOT in
@@ -108,16 +152,41 @@ function pad(str, width, align = 'left') {
   return align === 'right' ? padding + s : s + padding;
 }
 
+/**
+ * The board's key for a --pair value. Published runs store their pair as
+ * `eng>crk`: lower-case ISO 639-3 codes joined by > (mt-eval's publish writes
+ * it), and the filter is an exact match. So --pair is read in any spelling
+ * lib/language-pair.js accepts (eng-crk used to match nothing, silently), a
+ * bare 2-letter code goes to its ISO 639-3 code through the card aliases
+ * (en → eng, as `recommend` does), and the result is lower-cased. A code with
+ * a subtag (pt-BR) is kept as typed: the alias bridge would drop the subtag.
+ *
+ * @returns {{ok: true, pair: string, resolved: string[]} | {ok: false, error: string}}
+ */
+function boardPair(raw) {
+  const p = parseLanguagePair(raw, { label: '--pair' });
+  if (!p.ok) return p;
+  const resolved = [];
+  const toBoard = (code) => {
+    const lower = code.toLowerCase();
+    if (/[-_]/.test(code)) return lower;
+    const r = String(resolveCode(lower)).toLowerCase();
+    if (r !== lower) resolved.push(`${code} → ${r}`);
+    return r;
+  };
+  return { ok: true, pair: formatLanguagePair({ source: toBoard(p.source), target: toBoard(p.target) }), resolved };
+}
+
 /**
  * Fetch leaderboard data from Supabase.
  */
 async function fetchLeaderboard(sortKey, pair) {
-  const sort = SORT_KEYS[sortKey] || SORT_KEYS.composite;
+  const sort = SORT_KEYS[sortKey] || SORT_KEYS[DEFAULT_SORT];
   const order = `${sort.column}.${sort.desc ? 'desc' : 'asc'}.nullslast`;
 
   let url = `${SUPABASE_URL}/rest/v1/run_cards?select=*&order=${order}`;
   if (pair) {
-    url += `&language_pair=eq.${pair}`;
+    url += `&language_pair=eq.${encodeURIComponent(pair)}`;
   }
 
   const resp = await fetch(url, {
@@ -140,11 +209,27 @@ async function fetchLeaderboard(sortKey, pair) {
  * @returns {Promise<number>} Exit code (0 = success, 1 = error)
  */
 async function run(args, cwd) {
-  const sortKey = args.sort || 'composite';
-  const pair = args.pair || null;
+  const sortKey = args.sort || DEFAULT_SORT;
   const topN = args.top ? parseInt(args.top, 10) : null;
   const jsonMode = args.json || false;
 
+  // --pair: read in any accepted spelling, filtered as the board writes it.
+  let pair = null;
+  let resolvedNote = null;
+  if (args.pair !== undefined && args.pair !== false) {
+    const bp = boardPair(args.pair);
+    if (!bp.ok) {
+      output.error(bp.error);
+      return 1;
+    }
+    pair = bp.pair;
+    if (bp.resolved.length > 0) {
+      resolvedNote = `(codes resolved to ISO 639-3: ${bp.resolved.join(', ')})`;
+      // --json: on stderr, so stdout stays one JSON object per line.
+      if (jsonMode) console.error(`--pair ${pair} ${resolvedNote}`);
+    }
+  }
+
   // Resolve --install into an integer rank. Because --install is a string flag,
   // a bare `--install` (no rank) parses as boolean `true`, and parseInt(true)
   // is NaN — which previously slipped past the range check in _handleInstall
@@ -154,7 +239,7 @@ async function run(args, cwd) {
   if (args.install != null && args.install !== false) {
     installRank = parseInt(args.install, 10);
     if (!Number.isInteger(installRank) || installRank < 1) {
-      output.error('--install requires a positive integer rank, e.g. `champollion leaderboard --install 1`.');
+      output.error('--install requires a positive integer rank, e.g. `champollion network leaderboard --install 1`.');
       return 1;
     }
   }
@@ -175,7 +260,7 @@ async function run(args, cwd) {
         console.log('[]');
       } else {
         output.raw('\n  No leaderboard entries found.');
-        if (pair) output.raw(`  (filtered by pair: ${pair})`);
+        if (pair) output.raw(`  (filtered by pair: ${pair}${resolvedNote ? ` ${resolvedNote}` : ''})`);
         output.raw('  Submit results with `mt-eval publish`.\n');
       }
       return 0;
@@ -211,18 +296,32 @@ async function run(args, cwd) {
     if (jsonMode) {
       // NDJSON output for CI/CD piping
       for (const row of display) {
+        const legacy = isLegacyRow(row);
         console.log(JSON.stringify({
           rank: display.indexOf(row) + 1,
           model: row.model_slug,
           condition: row.condition,
           pair: row.language_pair,
-          composite: row.composite_score,
-          chrF: row.chrf_plus_plus,
-          exactMatch: row.exact_match_rate,
-          fstAcceptance: row.fst_acceptance_rate,
-          equivalentMatch: row.equivalent_match_rate,
-          semanticScore: row.semantic_score,
-          tier: row.quality_tier,
+          // Scoring standard/1: chrF++ (with its 95% CI) is the headline and
+          // the ranking metric; the other standard metrics sit beside it.
+          scoring_standard: legacy ? null : row.run_card.scores.scoring_standard,
+          primary_metric: 'chrf_plus_plus',
+          chrF: row.chrf_plus_plus ?? null,
+          chrF_ci: chrfCi(row),
+          bleu: row.corpus_bleu ?? null,
+          spbleu: num(row.run_card?.scores?.spbleu),
+          ter: row.ter ?? null,
+          comet: row.comet_score ?? null,
+          // Diagnostics: apart, never a headline or blended.
+          diagnostics: {
+            exactMatch: row.exact_match_rate ?? null,
+            fstAcceptance: row.fst_acceptance_rate ?? null,
+            equivalentMatch: row.equivalent_match_rate ?? null,
+            semanticScore: row.semantic_score ?? null,
+          },
+          // Only a legacy card's stored composite, under its retired name.
+          // No quality tier: tiers read off automatic scores are retired.
+          legacy_composite: legacyComposite(row),
           cost_usd: row.total_cost_usd,
           submitter: row.submitter,
           date: row.run_timestamp?.split('T')[0],
@@ -239,57 +338,75 @@ async function run(args, cwd) {
 
     // ---- Human-readable table output ----
 
-    const pairDisplay = pair ? formatPairDisplay(pair) : 'All Pairs';
+    const pairDisplay = pair ? `${formatPairDisplay(pair)} (${pair})` : 'All Pairs';
     const sortLabel = SORT_KEYS[sortKey].label;
 
     output.raw('');
     output.raw(`  champollion — Method Leaderboard`);
     output.raw(`  ${pairDisplay}  |  Sorted by: ${sortLabel}`);
+    if (resolvedNote) output.raw(`  ${resolvedNote}`);
     if (topN) output.raw(`  Showing top ${topN} of ${rows.length}`);
+    if (SORT_KEYS[sortKey].group === 'diagnostic') {
+      output.raw(`  (${sortLabel} is a diagnostic: it can explain a score, it does not rank quality — the headline is chrF++.)`);
+    }
+    if (sortKey === 'composite') {
+      output.raw(`  (The ${LEGACY_COMPOSITE_LABEL} exists only on cards scored before ${SCORING_STANDARD}; it is not a ranking of quality. Rank by chrF++.)`);
+    }
     output.raw('');
 
-    // Table header
-    const header = [
-      pad('#', 4),
-      pad('Model', 28),
-      pad('Condition', 12),
-      pad('Score', 7, 'right'),
-      pad('chrF++', 8, 'right'),
-      pad('EM%', 7, 'right'),
-      pad('Tier', 14),
-      pad('Date', 12),
-      pad('Lane', 9),
-    ].join('  ');
+    // Columns: the chrF++ headline with its CI, the other standard metrics
+    // beside it, then the diagnostics apart under their own label. The legacy
+    // composite is shown only when it is the requested sort.
+    const showLegacy = sortKey === 'composite';
+    const cols = [
+      { w: 4,  head: '#',                          cell: (r, i) => String(i + 1) },
+      { w: 28, head: 'Model',                      cell: (r) => r.model_slug || '—' },
+      { w: 12, head: 'Condition',                  cell: (r) => r.condition || '—' },
+      { w: 18, head: 'chrF++ [95% CI]', group: 'standard', align: 'right', cell: (r) => fmtChrf(r) },
+      { w: 6,  head: 'BLEU',  group: 'standard',   align: 'right', cell: (r) => fmtMetric(r.corpus_bleu, 1) },
+      { w: 6,  head: 'TER',   group: 'standard',   align: 'right', cell: (r) => fmtMetric(r.ter, 1) },
+      { w: 6,  head: 'COMET', group: 'standard',   align: 'right', cell: (r) => fmtMetric(r.comet_score, 3) },
+      { w: 7,  head: 'EM',    group: 'diagnostic', align: 'right', cell: (r) => fmtMetric(r.exact_match_rate) },
+      { w: 7,  head: 'FST',   group: 'diagnostic', align: 'right', cell: (r) => fmtMetric(r.fst_acceptance_rate) },
+      ...(showLegacy ? [{ w: 9, head: 'composite', group: 'legacy', align: 'right', cell: (r) => fmtMetric(legacyComposite(r), 4) }] : []),
+      { w: 12, head: 'Date',                       cell: (r) => r.run_timestamp?.split('T')[0] || '—' },
+      { w: 9,  head: 'Lane',                       cell: (r) => (rowIsRelativeOnly(r) ? 'rel-only' : 'abs') },
+    ];
+    const SEP = '  ';
+    const GROUP_TITLES = { standard: 'standard metrics', diagnostic: 'diagnostics', legacy: 'legacy (retired)' };
+    // Group line above the header: each group's title over its columns.
+    let groupLine = '';
+    for (let c = 0; c < cols.length; c++) {
+      const g = cols[c].group;
+      if (g && (c === 0 || cols[c - 1].group !== g)) {
+        let span = 0;
+        let k = c;
+        while (k < cols.length && cols[k].group === g) { span += cols[k].w + SEP.length; k++; }
+        groupLine += pad(`┌ ${GROUP_TITLES[g]}`, span - SEP.length) + SEP;
+        c = k - 1;
+      } else if (!g) {
+        groupLine += ' '.repeat(cols[c].w) + SEP;
+      }
+    }
+    const header = cols.map((c) => pad(c.head, c.w, c.align)).join(SEP);
 
+    output.raw(`  ${groupLine.trimEnd()}`);
     output.raw(`  ${header}`);
     output.raw(`  ${'─'.repeat(header.length)}`);
 
     for (let i = 0; i < display.length; i++) {
       const row = display[i];
-      const tier = TIER_LABELS[row.quality_tier?.toLowerCase()] || row.quality_tier || '—';
-      const date = row.run_timestamp?.split('T')[0] || '—';
-
-      const lane = rowIsRelativeOnly(row) ? 'rel-only' : 'abs';
-      const line = [
-        pad(String(i + 1), 4),
-        pad(row.model_slug || '—', 28),
-        pad(row.condition || '—', 12),
-        pad(fmtMetric(row.composite_score, 4), 7, 'right'),
-        pad(fmtMetric(row.chrf_plus_plus), 8, 'right'),
-        pad(fmtMetric(row.exact_match_rate), 7, 'right'),
-        pad(tier, 14),
-        pad(date, 12),
-        pad(lane, 9),
-      ].join('  ');
-
+      const line = cols.map((c) => pad(c.cell(row, i), c.w, c.align)).join(SEP);
       output.raw(`  ${line}`);
     }
 
     output.raw('');
     output.raw(`  ${display.length} result${display.length !== 1 ? 's' : ''} shown.`);
+    output.raw(`  Headline: chrF++ with its 95% bootstrap CI (${SCORING_STANDARD}); rows whose intervals overlap are not distinguishable.`);
+    output.raw(`  Diagnostics (EM = exact match, FST = FST acceptance) explain a score; they never rank and are never blended into it.`);
     output.raw(`  Lane: abs = absolute-quality · rel-only = relative-comparison-only`);
     output.raw(`        (HIGH/MEDIUM contamination, FLORES, or unknown grade — compare within that corpus only)`);
-    output.raw(`  → Install a method: champollion leaderboard --install <rank>`);
+    output.raw(`  → Install a method: champollion network leaderboard --install <rank>`);
     output.raw(`  View full leaderboard: https://champollion.dev/leaderboard`);
     output.raw('');
 
@@ -404,7 +521,10 @@ async function _handleInstall(rows, rank, sortKey, cwd, args = {}) {
   output.raw('');
   output.raw(`  Source: Rank #${rank} on leaderboard (${formatPairDisplay(pair)})`);
   output.raw(`  Model:  ${model}`);
-  output.raw(`  Score:  ${fmtMetric(row.composite_score, 4)} composite (${row.quality_tier || 'unscored'})`);
+  output.raw(`  Score:  chrF++ ${fmtChrf(row)}${chrfCi(row) ? ' (95% CI)' : ''}`);
+  if (legacyComposite(row) != null) {
+    output.raw(`          ${LEGACY_COMPOSITE_LABEL}: ${fmtMetric(legacyComposite(row), 4)} — scored before ${SCORING_STANDARD}; for the record only`);
+  }
   if (methodCard?.name) {
     output.raw(`  Method: ${methodCard.name} (${methodCard.class || 'unclassified'})`);
   }
@@ -445,7 +565,7 @@ async function _handleInstall(rows, rank, sortKey, cwd, args = {}) {
     output.raw('  To use this method in your project:');
     output.raw(`    "methodPlugin": "${safeName}"`);
     output.raw('');
-    output.raw('  Or auto-wire it: champollion leaderboard --install ' + rank + ' --apply');
+    output.raw('  Or auto-wire it: champollion network leaderboard --install ' + rank + ' --apply');
     output.raw('');
   }
 

package/lib/commands/models.js

@@ -18,7 +18,8 @@
  */
 
 import { resolveConfig } from '../config.js';
-import { fetchAvailableModels, resolveProviderApiKey, getProviderLabel, isListableProvider, getListableProviders } from '../models.js';
+import { fetchAvailableModels, resolveProviderApiKey, getProviderLabel, getProviderEnvVar, isListableProvider, getListableProviders } from '../models.js';
+import { missingKeyAdvice } from '../missing-key.js';
 import { output } from '../output.js';
 
 /**
@@ -91,7 +92,13 @@ async function run(args, cwd) {
     }
     output.warn(`No API key found for ${label}.`);
     output.raw('');
-    output.raw(`  Set the environment variable or add it to .env.local.`);
+    // On a CI runner: the repository secret, not the shell advice (lib/missing-key.js).
+    const envVar = getProviderEnvVar(method);
+    for (const line of missingKeyAdvice({
+      reasons: [envVar ? `No API key (${envVar})` : ''],
+      setupHelp: [`  Set ${envVar || 'the environment variable'} in the environment or add it to .env.local.`],
+      step: 'the step that runs it',
+    })) output.raw(line);
     output.raw(`  Then re-run: champollion models --method ${method}`);
     output.raw('');
     return 1;

package/lib/commands/provenance.js

@@ -34,8 +34,13 @@ async function run(args, cwd) {
   }
   config.resolvedLanguages = languages;
 
-  const pairs = resolvePairs(config);
-  const report = formatProvenanceReport(pairs);
+  const pairs = resolvePairs(config, { cwd });
+  // A pair's fallback method translates too: report it as its own route.
+  const routes = new Map(pairs);
+  for (const [key, pc] of pairs) {
+    if (pc.fallback) routes.set(`${key} (fallback)`, pc.fallback);
+  }
+  const report = formatProvenanceReport(routes);
   output.raw('\n  champollion — Provenance Report\n');
   output.raw(report);