champollion 0.3.4 → 0.5.0

package/lib/methods/local.js

@@ -13,7 +13,34 @@
  */
 
 import { OpenAIMethod } from './openai.js';
-import { getEnvOrFileVar } from '../api-key.js';
+import { isLoopbackEndpoint, localMachineCost } from './http-utils.js';
+import { onCIRunner } from '../missing-key.js';
+
+/** How long the readiness probe waits for a local endpoint to answer. */
+const PROBE_TIMEOUT_MS = 3000;
+// One probe per endpoint per process: a project with ten local pairs asks once.
+const probes = new Map();
+
+/** Does anything answer HTTP at `<base>/models`? (Any status counts.) */
+function endpointAnswers(base) {
+  if (!probes.has(base)) {
+    probes.set(base, (async () => {
+      const ctl = new AbortController();
+      const timer = setTimeout(() => ctl.abort(), PROBE_TIMEOUT_MS);
+      try {
+        const res = await fetch(`${base}/models`, { signal: ctl.signal });
+        // Drain it: the answer is all that matters, not the body.
+        try { await res.arrayBuffer(); } catch { /* the status was enough */ }
+        return true;
+      } catch {
+        return false;
+      } finally {
+        clearTimeout(timer);
+      }
+    })());
+  }
+  return probes.get(base);
+}
 
 class LocalMethod extends OpenAIMethod {
   constructor(options = {}) {
@@ -24,13 +51,16 @@ class LocalMethod extends OpenAIMethod {
   _getProviderLabel() { return 'Local (OpenAI-compatible)'; }
   _getApiKeyEnvVar()  { return 'OPENAI_API_KEY'; }
   _getDefaultModel()  { return 'llama3.1'; }
+  // A local server names its models itself ("llama3.1:8b",
+  // "Qwen/Qwen2.5-7B-Instruct"): ids are sent as written, never mapped.
+  _getModelVendor()   { return null; }
 
   // Endpoint precedence: options.baseUrl > LOCAL_API_BASE > OPENAI_API_BASE >
-  // Ollama default. (Matches the harness LocalProvider resolution order.)
+  // OPENAI_BASE_URL (the OpenAI SDK's name) > Ollama default. (Matches the harness LocalProvider resolution order.)
   _getApiBaseEnvVar() { return 'LOCAL_API_BASE'; }
-  _getDefaultApiBase() {
-    return getEnvOrFileVar('OPENAI_API_BASE') || 'http://localhost:11434/v1';
-  }
+  _getApiBaseEnvVars() { return ['LOCAL_API_BASE', 'OPENAI_API_BASE', 'OPENAI_BASE_URL']; }
+  _getDefaultApiBase() { return 'http://localhost:11434/v1'; }
+  _getDefaultApiBaseLabel() { return 'the default, Ollama'; }
 
   // Local servers ignore auth — supply a placeholder when no key is set so
   // translate() doesn't skip the run for a "missing" key.
@@ -38,12 +68,60 @@ class LocalMethod extends OpenAIMethod {
     return super._resolveApiKey(options) || 'not-needed';
   }
 
-  checkReadiness(_context) {
-    return { ready: true }; // local endpoint; no API key required
+  /**
+   * A local endpoint needs no key — but it must answer. Checked even when
+   * nothing is queued (as hosted methods' keys are): a project whose config
+   * says "local", synced in CI with the guide's default line, went green on
+   * every push that changed no string and failed only on the first that did
+   * (Round 8, i18next persona). Any HTTP answer from `<base>/models` counts
+   * (a server that does not list models still answers); refused, unknown
+   * host or no answer within a few seconds does not. A dry run reports it
+   * as a warning (lib/sync.js preflight).
+   *
+   * Off a CI runner the answer is `unreachable: true` (with the `endpoint`):
+   * sync decides after its plan — a run that sends nothing to the model (a
+   * redo served from the cache) goes on with a warning, one that sends
+   * something stops as before (Round 11, Django persona). On a runner it
+   * still stops at once, for the reason above.
+   */
+  async checkReadiness({ cwd } = {}) {
+    let resolved;
+    try { resolved = this._resolveApiBaseSource(cwd ? { cwd } : {}); } catch { resolved = { base: null, from: null }; }
+    if (!resolved.base) return { ready: true };
+    if (await endpointAnswers(resolved.base)) return { ready: true };
+    const where = this._describeEndpoint(cwd ? { cwd } : {}) || resolved.base;
+    const inCI = onCIRunner();
+    return {
+      ready: false,
+      unreachable: true,
+      endpoint: where,
+      reason: `the config uses the "local" method, and no model server answers at ${where}. `
+        + (inCI
+          ? 'A CI runner has no model server: pass --method llm (with OPENROUTER_API_KEY added as a repository secret and passed to the sync step), '
+            + 'or start one in the job and set LOCAL_API_BASE to it'
+          : 'Start it (e.g. `ollama serve`), set LOCAL_API_BASE to a server that runs, or pass --method llm to use a hosted model'),
+    };
+  }
+
+  // No model listing. The inherited OpenAI listing called
+  // api.openai.com/v1/models — a request off the machine on every "local"
+  // run, the one method people choose to stay on it (found 2026-10-03). A
+  // local server's own /models is not a reliable allow-list either (many
+  // serve whatever model name is asked), so the model is not pre-validated.
+  async _fetchModels(_apiKey) {
+    return null;
   }
 
-  // Cost is genuinely unknown for local/self-hosted models — never $0.
-  estimateCost(_keyCount, _pairConfig = {}) {
+  // A model served on THIS machine (Ollama's default, LM Studio, a forge
+  // model on 127.0.0.1) costs $0 in API fees — said as such, with what is not
+  // counted. Any other endpoint (Groq, Together, a LAN box) is genuinely
+  // unknown to the tool — never $0.
+  estimateCost(_keyCount, pairConfig = {}, { cwd = null } = {}) {
+    const base = this._resolveApiBase({
+      ...(pairConfig?.baseUrl ? { baseUrl: pairConfig.baseUrl } : {}),
+      ...(cwd && { cwd }),
+    });
+    if (isLoopbackEndpoint(base)) return localMachineCost(base);
     return {
       estimatedCost: null,
       currency: 'USD',
@@ -63,11 +141,16 @@ class LocalMethod extends OpenAIMethod {
   }
 
   getSetupHelp() {
+    // Name the endpoint this run used and the setting that chose it: "fetch
+    // failed" alone left people guessing which of four settings was in play.
+    const endpoint = this._describeEndpoint();
     return [
       '  Local (OpenAI-compatible) endpoint:',
+      ...(endpoint ? [`   • This run sent requests to ${endpoint}.`] : []),
       '   • Ollama: install from https://ollama.com, run `ollama serve`,',
       '     then `ollama pull llama3.1` (default http://localhost:11434/v1).',
-      '   • Or point at vLLM / LM Studio / Groq via LOCAL_API_BASE or OPENAI_API_BASE,',
+      '   • Or point at vLLM / LM Studio / Groq via LOCAL_API_BASE (checked first),',
+      '     OPENAI_API_BASE or OPENAI_BASE_URL — in the environment or .env.local / .env —',
       '     and set the model with --model (e.g. qwen2.5, mistral).',
     ];
   }

package/lib/methods/microsoft-translator.js

@@ -22,6 +22,7 @@ const MICROSOFT_REQUEST_TIMEOUT_MS = 15000;
 class MicrosoftTranslatorMethod extends TranslationMethod {
   constructor(options = {}) {
     super('microsoft-translator', options);
+    this.translatesRawText = true; // see base.js
   }
 
   // ── API resolution helpers ──────────────────────────────────────
@@ -47,7 +48,6 @@ class MicrosoftTranslatorMethod extends TranslationMethod {
    */
   _resolveRegion(options) {
     return options.microsoftRegion
-      || getEnvOrFileVar('MICROSOFT_TRANSLATOR_REGION')
       || getEnvOrFileVar('MICROSOFT_TRANSLATOR_REGION', options.cwd);
   }
 
@@ -66,7 +66,6 @@ class MicrosoftTranslatorMethod extends TranslationMethod {
    */
   _resolveEndpoint(options = {}) {
     let ep = options.microsoftEndpoint
-      || getEnvOrFileVar('MICROSOFT_TRANSLATOR_ENDPOINT')
       || getEnvOrFileVar('MICROSOFT_TRANSLATOR_ENDPOINT', options.cwd);
     if (!ep) return MICROSOFT_API_BASE;
     ep = ep.replace(/\/+$/, '');

package/lib/methods/openai.js

@@ -33,11 +33,12 @@ class OpenAIMethod extends DirectLLMMethod {
   _getApiKeyOptionsKey() { return 'openaiApiKey'; }
   _getDefaultModel()     { return DEFAULT_MODEL; }
   _getProviderLabel()    { return 'OpenAI'; }
+  _getModelVendor()      { return 'openai'; }
   _getDefaultApiBase()   { return 'https://api.openai.com/v1'; }
 
   // ── API request/response shape ───────────────────────────────────
 
-  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature, isJsonMode }) {
+  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature, isJsonMode, cwd = null }) {
     const messages = systemMessage
       ? [{ role: 'system', content: systemMessage }, { role: 'user', content: prompt }]
       : [{ role: 'user', content: prompt }];
@@ -47,7 +48,8 @@ class OpenAIMethod extends DirectLLMMethod {
       body.response_format = { type: 'json_object' };
     }
 
-    const base = this._resolveApiBase() || 'https://api.openai.com/v1';
+    // The project's .env (cwd) may point it at a gateway or a local server.
+    const base = this._resolveApiBase(cwd ? { cwd } : {}) || 'https://api.openai.com/v1';
     return {
       url: `${base}/chat/completions`,
       headers: {

package/lib/methods/openrouter-client.js

@@ -21,6 +21,7 @@ import {
 import { DEFAULT_TEMPERATURE } from '../config.js';
 import { output } from '../output.js';
 import { recordTranslationError } from './translation-error.js';
+import { captureRequest } from './request-capture.js';
 
 const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';
 
@@ -55,32 +56,32 @@ async function callOpenRouter({
   xTitle = 'champollion',
   systemMessage = null,
 }) {
+  // Build messages array — when systemMessage is provided, split preamble
+  // from payload to enable provider-level prompt caching. The system message
+  // (register + rules) is identical across batches for a given locale, so
+  // providers like Anthropic and Google cache it automatically.
+  const messages = systemMessage
+    ? [{ role: 'system', content: systemMessage }, { role: 'user', content: prompt }]
+    : [{ role: 'user', content: prompt }];
+  const headers = {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+    'HTTP-Referer': 'https://github.com/gamedaysuits/Champollion',
+    'X-Title': xTitle,
+  };
+  const body = { model, messages, temperature };
+  // `sync --dry --show-prompt`: hand over the exact request, send nothing.
+  if (captureRequest({ url: OPENROUTER_URL, headers, body })) return null;
+
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     try {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
-      // Build messages array — when systemMessage is provided, split preamble
-      // from payload to enable provider-level prompt caching. The system message
-      // (register + rules) is identical across batches for a given locale, so
-      // providers like Anthropic and Google cache it automatically.
-      const messages = systemMessage
-        ? [{ role: 'system', content: systemMessage }, { role: 'user', content: prompt }]
-        : [{ role: 'user', content: prompt }];
-
       const response = await fetch(OPENROUTER_URL, {
         method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${apiKey}`,
-          'Content-Type': 'application/json',
-          'HTTP-Referer': 'https://github.com/gamedaysuits/Champollion',
-          'X-Title': xTitle,
-        },
-        body: JSON.stringify({
-          model,
-          messages,
-          temperature,
-        }),
+        headers,
+        body: JSON.stringify(body),
         signal: controller.signal,
       });
 

package/lib/methods/openrouter-pricing.js

@@ -20,6 +20,7 @@
  */
 
 import { EST_INPUT_TOKENS_PER_KEY, EST_OUTPUT_TOKENS_PER_KEY } from '../config.js';
+import { editDistance } from '../edit-distance.js';
 
 const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
 
@@ -30,6 +31,13 @@ const COACHED_INPUT_MULTIPLIER = 2.5;
 // In-memory cache: fetched once per process
 let _pricingCache = null;
 let _pricingFetchPromise = null;
+// What the last fetch saw, beside the prices: whether the list came at all
+// (and why not), and every model id it listed — priced or not — so an
+// unpriced estimate can say WHICH it is: a name the list does not have (a
+// likely typo), a listed model with no per-token price, or no list at all.
+// A mistyped slug used to read exactly like an unpriced model: "unknown (no
+// method in this run has published pricing)" (Round 11, Next.js persona).
+let _catalog = { fetched: false, why: 'not fetched yet', ids: new Set() };
 
 /**
  * Fetch pricing for all OpenRouter models.
@@ -56,6 +64,13 @@ async function fetchModelPricing() {
 }
 
 async function _doFetch() {
+  // The live pricing draw is off (an air-gapped node — the same switch the
+  // direct providers' pricing honours, lib/methods/provider-pricing.js
+  // pricingOffline): no list, and the estimate says so.
+  if (process.env.CHAMPOLLION_PRICING_OFFLINE === '1') {
+    _catalog = { fetched: false, why: 'the live price draw is off: CHAMPOLLION_PRICING_OFFLINE=1', ids: new Set() };
+    return new Map();
+  }
   try {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 5000);
@@ -67,29 +82,93 @@ async function _doFetch() {
 
     clearTimeout(timeoutId);
 
-    if (!response.ok) return new Map();
+    if (!response.ok) {
+      _catalog = { fetched: false, why: `OpenRouter answered HTTP ${response.status}`, ids: new Set() };
+      return new Map();
+    }
 
     const json = await response.json();
     const models = json.data || [];
     const pricing = new Map();
+    const ids = new Set();
 
     for (const model of models) {
-      if (model.id && model.pricing) {
-        pricing.set(model.id, {
-          input: parseFloat(model.pricing.prompt) || 0,
-          output: parseFloat(model.pricing.completion) || 0,
-        });
-      }
+      if (!model.id) continue;
+      ids.add(model.id);
+      if (!model.pricing) continue;
+      const input = parseFloat(model.pricing.prompt);
+      const output = parseFloat(model.pricing.completion);
+      // A router whose price depends on the model it picks lists "-1": no
+      // per-token price — never a negative estimate (listed, unpriced).
+      if (!Number.isFinite(input) || !Number.isFinite(output) || input < 0 || output < 0) continue;
+      pricing.set(model.id, { input, output });
     }
 
+    // When the list was read: an estimate says which day's prices it used.
+    _catalog = { fetched: true, why: null, ids, fetchedAt: new Date().toISOString() };
     return pricing;
-  } catch {
+  } catch (err) {
     // Offline, timeout, or API issue — return empty map
-    // Cost estimation degrades gracefully to "unknown"
+    // Cost estimation degrades gracefully to "unknown", and says why.
+    _catalog = {
+      fetched: false,
+      why: err?.name === 'AbortError' ? 'the request timed out' : `the request failed (${err?.message || err})`,
+      ids: new Set(),
+    };
     return new Map();
   }
 }
 
+/**
+ * The listed model ids closest to a name the list does not have — a likely
+ * typo's intended slug. Cheap: one bounded edit distance per listed id.
+ *
+ * @param {string} model
+ * @param {Iterable<string>} ids
+ * @param {number} [n=3]
+ * @returns {string[]}
+ */
+function closestModelIds(model, ids, n = 3) {
+  const want = String(model).toLowerCase();
+  const max = Math.max(2, Math.floor(want.length / 5));
+  const scored = [];
+  for (const id of ids) {
+    const d = editDistance(id.toLowerCase(), want, max);
+    if (d <= max) scored.push([d, id]);
+  }
+  scored.sort((a, b) => a[0] - b[0] || a[1].localeCompare(b[1]));
+  return scored.slice(0, n).map(([, id]) => id);
+}
+
+/**
+ * Why a model has no price, in one sentence that names it — and the
+ * estimate's `source` for that case.
+ *
+ * @param {string} model
+ * @returns {{ source: string, note: string, closest?: string[] }}
+ */
+function unpricedReason(model) {
+  if (!_catalog.fetched) {
+    return {
+      source: 'openrouter-price-list-unavailable',
+      note: `OpenRouter's price list could not be read (${_catalog.why}), so the price of "${model}" is unknown.`,
+    };
+  }
+  if (_catalog.ids.has(model)) {
+    return {
+      source: 'openrouter-no-price',
+      note: `"${model}" is in OpenRouter's model list but has no published per-token price, so its cost cannot be estimated.`,
+    };
+  }
+  const closest = closestModelIds(model, _catalog.ids);
+  return {
+    source: 'openrouter-not-listed',
+    note: `"${model}" is not in OpenRouter's model list — likely a typo in the model name`
+      + (closest.length > 0 ? `. Closest listed: ${closest.join(', ')}.` : ' (nothing listed is close to it).'),
+    closest,
+  };
+}
+
 /**
  * Estimate cost for translating N keys with a specific model via OpenRouter.
  *
@@ -115,11 +194,16 @@ async function estimateOpenRouterCost(keyCount, model, options = {}) {
 
   const modelPricing = pricing.get(model);
   if (!modelPricing) {
+    // Named, and why: not in the list (a likely typo — with the closest
+    // listed slugs), listed with no price, or no list to look in.
+    const why = unpricedReason(model);
     return {
       estimatedCost: null,
       currency: 'USD',
-      source: 'unknown',
-      note: `Model "${model}" not found in OpenRouter pricing. Cost cannot be estimated.`,
+      source: why.source,
+      note: why.note,
+      model,
+      ...(why.closest && { closest: why.closest }),
     };
   }
 
@@ -136,21 +220,74 @@ async function estimateOpenRouterCost(keyCount, model, options = {}) {
   const inputCost = totalInputTokens * modelPricing.input;
   const outputCost = totalOutputTokens * modelPricing.output;
   const totalCost = inputCost + outputCost;
+  const rate = openRouterRate(model, modelPricing, { input: inputTokensPerKey, output: outputTokensPerKey });
 
   return {
     estimatedCost: Math.round(totalCost * 10000) / 10000,
     currency: 'USD',
     source: `openrouter (${model})`,
-    note: `Based on ${model} pricing: $${modelPricing.input}/tok in, $${modelPricing.output}/tok out.`,
+    note: `Based on ${model} pricing: $${formatPerMillion(rate.inputPerMillion)}/1M input tokens, `
+      + `$${formatPerMillion(rate.outputPerMillion)}/1M output tokens (OpenRouter's price list, read ${rate.fetchedAt}).`,
+    rate,
   };
 }
 
+/**
+ * The rate an estimate used, said in full: what one million tokens cost in
+ * and out, where the figure came from (OpenRouter's public price list) and
+ * when it was read, and the tokens per key the estimate assumes. An
+ * estimate used to give a figure with none of this (Round 14, Next.js
+ * persona) — no way to tell a stale or mistaken price from a real one.
+ *
+ * @param {string} model - The OpenRouter model id priced
+ * @param {{ input: number, output: number }} perToken - USD per token
+ * @param {{ input: number, output: number }} tokensPerKey - What the estimate assumes
+ * @returns {{ model: string, unit: 'token', inputPerMillion: number, outputPerMillion: number,
+ *   tokensPerKey: { input: number, output: number }, from: string, url: string, fetchedAt: string|null }}
+ */
+function openRouterRate(model, perToken, tokensPerKey) {
+  return {
+    model,
+    unit: 'token',
+    inputPerMillion: perMillion(perToken.input),
+    outputPerMillion: perMillion(perToken.output),
+    tokensPerKey,
+    from: 'openrouter-price-list',
+    url: OPENROUTER_MODELS_URL,
+    fetchedAt: _catalog.fetchedAt || null,
+  };
+}
+
+/** USD per token → USD per million tokens, without float noise (0.0000003 → 0.3). */
+function perMillion(perTokenUsd) {
+  return Number((perTokenUsd * 1_000_000).toPrecision(12));
+}
+
+/** $ per 1M, as people write it: 0.3 → "0.30", 2.5 → "2.50", 0.075 → "0.075". */
+function formatPerMillion(usd) {
+  return usd >= 0.01 && Number(usd.toFixed(2)) === usd ? usd.toFixed(2) : String(usd);
+}
+
 /**
  * Clear the pricing cache. Useful for testing.
  */
 function clearPricingCache() {
   _pricingCache = null;
   _pricingFetchPromise = null;
+  _catalog = { fetched: false, why: 'not fetched yet', ids: new Set() };
+}
+
+/**
+ * When OpenRouter's price list was read in this process (ISO 8601), or
+ * null when it was not (offline, failed, never asked).
+ *
+ * @returns {string|null}
+ */
+function priceListFetchedAt() {
+  return _catalog.fetched ? (_catalog.fetchedAt || null) : null;
 }
 
-export { fetchModelPricing, estimateOpenRouterCost, clearPricingCache };
+export {
+  fetchModelPricing, estimateOpenRouterCost, clearPricingCache, priceListFetchedAt, formatPerMillion,
+  OPENROUTER_MODELS_URL,
+};

package/lib/methods/prompt-methods.js

@@ -0,0 +1,20 @@
+/**
+ * prompt-methods.js — which methods send the `llm` method's prompt, and so
+ * carry a pair's free-text coaching (coachingFile / coachingPrompt).
+ *
+ * Dependency-free on purpose: the translation-memory key (lib/tm.js
+ * tmMethodKey) reads it, and tm.js imports nothing but Node built-ins.
+ */
+
+/**
+ * The plain LLM methods: one prompt (lib/methods/llm.js promptSettingsFor +
+ * buildSystemMessage + buildUserMessage), different transports. Their system
+ * message carries the pair's coaching text as a "Coaching guidance:" block.
+ */
+export const PLAIN_LLM_METHODS = new Set(['llm', 'openai', 'anthropic', 'gemini', 'local']);
+
+/**
+ * Every method whose prompt carries the pair's free-text coaching: the plain
+ * LLM methods, and llm-coached (which adds its structured coaching).
+ */
+export const COACHING_PROMPT_METHODS = new Set([...PLAIN_LLM_METHODS, 'llm-coached']);

package/lib/methods/provider-pricing.js

@@ -21,7 +21,7 @@ import {
   EST_INPUT_TOKENS_PER_KEY,
   EST_OUTPUT_TOKENS_PER_KEY,
 } from '../config.js';
-import { fetchModelPricing } from './openrouter-pricing.js';
+import { fetchModelPricing, priceListFetchedAt, OPENROUTER_MODELS_URL } from './openrouter-pricing.js';
 
 /**
  * Per-provider pricing data.
@@ -34,21 +34,29 @@ import { fetchModelPricing } from './openrouter-pricing.js';
 export const PROVIDER_RATES = {
   'google-translate': {
     costPerMillionChars: 20,
+    verified: '2026-06-08',
+    url: 'https://cloud.google.com/translate/pricing',
     source: 'google-cloud-pricing',
     note: 'Google Cloud Translation API v2 ($20/1M chars).',
   },
   'deepl': {
     costPerMillionChars: 25,
+    verified: '2026-06-08',
+    url: 'https://www.deepl.com/pro-api',
     source: 'deepl-api-pro-pricing',
     note: 'DeepL API Pro (~$25/1M chars). Free tier: 500K chars/month cap.',
   },
   'microsoft-translator': {
     costPerMillionChars: 10,
+    verified: '2026-06-08',
+    url: 'https://azure.microsoft.com/pricing/details/cognitive-services/translator/',
     source: 'microsoft-translator-pricing',
     note: 'Azure Translator S1 ($10/1M chars). 2M chars/month free tier.',
   },
   'libretranslate': {
     costPerMillionChars: 0,
+    verified: null,
+    url: null,
     source: 'libretranslate-self-hosted',
     note: 'Self-hosted, free. Infrastructure costs not included.',
   },
@@ -206,6 +214,8 @@ export async function estimateLlmCost(provider, model, keyCount) {
   let rate = null;
   let source = null;
   let divergence = '';
+  // Where the rate came from, for the estimate's `rate` (said in the table).
+  let from = null;
 
   // The OpenRouter namespace must match the provider being billed. Without
   // this, estimateLlmCost('anthropic', 'gpt-4o', …) would happily price the
@@ -229,6 +239,7 @@ export async function estimateLlmCost(provider, model, keyCount) {
       // dollars per million tokens.
       rate = { input: live.input * 1_000_000, output: live.output * 1_000_000 };
       source = `openrouter-live (proxy for ${provider} list price)`;
+      from = { from: 'openrouter-price-list', url: OPENROUTER_MODELS_URL, fetchedAt: priceListFetchedAt(), proxyFor: provider };
 
       if (pinnedUsable) {
         const drift = (a, b) => (b === 0 ? (a === 0 ? 0 : 1) : Math.abs(a - b) / b);
@@ -254,6 +265,13 @@ export async function estimateLlmCost(provider, model, keyCount) {
   if (!rate && pinnedUsable) {
     rate = { input: pinned.input, output: pinned.output };
     source = `pinned-table (${pinned.verified ? `verified ${pinned.verified}` : 'UNVERIFIED'}; live draw unavailable)`;
+    // Why the copy, not the live list: the draw is off, the list could not
+    // be read, or it was read and has no price for this model.
+    let liveDraw = 'unavailable';
+    if (pricingOffline()) liveDraw = 'off';
+    else if (!orId || !namespaceOk) liveDraw = 'not-listed';
+    else if (priceListFetchedAt()) liveDraw = 'no-price';
+    from = { from: 'pinned-table', verified: pinned.verified || null, liveDraw };
   }
 
   if (!rate) {
@@ -279,6 +297,16 @@ export async function estimateLlmCost(provider, model, keyCount) {
     note: `Based on ${provider} ${model} pricing `
       + `($${rate.input.toFixed(2)}/1M input, $${rate.output.toFixed(2)}/1M output, `
       + `${source}).${divergence}`,
+    // The rate used, where it came from and when (cost-report.js says it in
+    // one line; --json carries this whole object).
+    rate: {
+      model,
+      unit: 'token',
+      inputPerMillion: Number(rate.input.toPrecision(12)),
+      outputPerMillion: Number(rate.output.toPrecision(12)),
+      tokensPerKey: { input: EST_INPUT_TOKENS_PER_KEY, output: EST_OUTPUT_TOKENS_PER_KEY },
+      ...from,
+    },
   };
 }
 
@@ -306,5 +334,18 @@ export function estimateProviderCost(provider, keyCount) {
     currency: 'USD',
     source: rate.source,
     note: rate.note,
+    // A published per-character rate, as this file records it (no pricing
+    // API exists for these providers): its date says how old the figure is.
+    ...(rate.costPerMillionChars > 0 && {
+      rate: {
+        model: provider,
+        unit: 'char',
+        perMillionChars: rate.costPerMillionChars,
+        charsPerKey: EST_CHARS_PER_KEY,
+        from: 'published-rate',
+        url: rate.url,
+        verified: rate.verified,
+      },
+    }),
   };
 }