champollion 0.3.4 → 0.4.0

package/lib/methods/llm-coached.js

@@ -56,20 +56,18 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { TranslationMethod } from './base.js';
 import { callOpenRouterJSON } from './openrouter-client.js';
+import { isCapturing, PREVIEW_KEY } from './request-capture.js';
 import { estimateOpenRouterCost } from './openrouter-pricing.js';
 
 // Re-use the LLM method's infrastructure (prompt building, key validation, cascade)
-import { LLMMethod, inferKeyTypes, isUnsafeKey, buildSystemMessage } from './llm.js';
+import { LLMMethod, inferKeyTypes, isUnsafeKey, buildSystemMessage, buildUserMessage, promptSettingsFor } from './llm.js';
+// The coaching file + glossary helpers live in coaching-data.js (llm.js uses
+// them too); re-exported below under their old names.
+import { DEFAULT_COACHING_DIR, loadCoachingData, findDictionaryMatches, projectGlossary } from './coaching-data.js';
 import { DEFAULT_OPENROUTER_MODEL, DEFAULT_BATCH_SIZE, DEFAULT_COACHED_TEMPERATURE, DEFAULT_MAX_RETRIES, DEFAULT_METHOD_CONCURRENCY } from '../config.js';
 import { pMap } from '../concurrent.js';
 import { output } from '../output.js';
 
-/**
- * Default coaching data directory, relative to project root.
- * Users can override via config: coaching.dir
- */
-const DEFAULT_COACHING_DIR = '.champollion/coaching';
-
 /**
  * Direct-provider methods a coached run can dispatch to (in addition to the
  * default OpenRouter path). Imported lazily inside _getProviderMethod() because
@@ -83,6 +81,13 @@ const DIRECT_PROVIDER_MODULES = {
   local:     { module: './local.js',     export: 'LocalMethod' },
 };
 
+/**
+ * Every transport a coached (or plain llm) pair can name in `provider`.
+ * pairs.js validates config against this list, so an unknown provider fails at
+ * pair-graph build time instead of silently riding OpenRouter.
+ */
+const COACHED_PROVIDERS = ['openrouter', ...Object.keys(DIRECT_PROVIDER_MODULES)];
+
 /**
  * Normalize a pair config's `provider` to a lowercase key. Absent/blank → the
  * default OpenRouter path, matching config_exporter.py (which only emits
@@ -158,59 +163,16 @@ function resolveCoachingPrompt(pairConfig, options) {
   return { configured: false, text: null };
 }
 
-/**
- * Load coaching data for a locale from a JSON file, with caching.
- *
- * This is a standalone function so that any translation method (LLMCoached,
- * OpenAI, Anthropic, Gemini) can load coaching data without instantiating
- * the LLMCoachedMethod class.
- *
- * @param {string} coachingDir - Path to coaching data directory
- * @param {string} locale - Target locale code (e.g., 'fr', 'crk')
- * @param {Map} cache - Cache map to store loaded data (avoids re-reading files)
- * @returns {object|null} Coaching data { grammar_rules, dictionary, style_notes }, or null
- */
-function loadCoachingData(coachingDir, locale, cache) {
-  if (!locale) return null;
-
-  // Check cache first
-  const cacheKey = `${coachingDir}:${locale}`;
-  if (cache.has(cacheKey)) {
-    return cache.get(cacheKey);
-  }
-
-  const filePath = path.join(coachingDir, `${locale}.json`);
-
-  if (!fs.existsSync(filePath)) {
-    cache.set(cacheKey, null);
-    return null;
-  }
-
-  try {
-    const raw = fs.readFileSync(filePath, 'utf-8');
-    const data = JSON.parse(raw);
-
-    // Validate required structure — normalize missing fields to safe defaults
-    const coaching = {
-      grammar_rules: Array.isArray(data.grammar_rules) ? data.grammar_rules : [],
-      dictionary: (data.dictionary && typeof data.dictionary === 'object') ? data.dictionary : {},
-      style_notes: typeof data.style_notes === 'string' ? data.style_notes : '',
-    };
-
-    cache.set(cacheKey, coaching);
-    return coaching;
-  } catch (err) {
-    output.warn(`Failed to load coaching data: ${filePath}`);
-    output.warn(err.message);
-    cache.set(cacheKey, null);
-    return null;
-  }
-}
-
 class LLMCoachedMethod extends TranslationMethod {
   constructor(options = {}) {
     super('llm-coached', options);
+    this.acceptsKeyInstructions = true; // prompt "UI context" lines (lib/methods/base.js)
+    this.supportsRequestPreview = true; // its transport reports to request-capture.js
     this._coachingCache = new Map();
+    // The pair's transport, known at construction (getMethod passes the pair
+    // config) so preflight and cost estimation — which receive no pairConfig
+    // of their own — check the provider the run will actually call.
+    this._provider = normalizeProvider(options.provider);
   }
 
   /**
@@ -270,32 +232,35 @@ class LLMCoachedMethod extends TranslationMethod {
     // langConfig.coachingPrompt (exactly as the plain llm.js method injects
     // it), so it is part of EVERY batch and can never be silently dropped —
     // including for the openai/anthropic/gemini/local providers below.
-    const langConfig = {
-      name: pairConfig.name,
-      register: pairConfig.register,
-      genderGuidance: pairConfig.genderGuidance || null,
-      promptContext: pairConfig.promptContext || null,
-      coachingPrompt: coachingPromptInfo.text,
-    };
+    // The same reading of the pair as every LLM method (llm.js
+    // promptSettingsFor) — it used to leave out the protected terms — with
+    // the coaching prompt this method resolved itself.
+    const langConfig = promptSettingsFor(pairConfig, { coachingPrompt: coachingPromptInfo.text });
     const systemMessage = structured
       ? buildCoachedSystemMessage(langConfig, structured)
       : buildSystemMessage(langConfig);
+    // The glossary each batch is told about: the coaching file's dictionary,
+    // else the project's (the same file, unless a plugin brings its own).
+    const glossary = (structured && Object.keys(structured.dictionary).length > 0)
+      ? structured.dictionary
+      : projectGlossary(pairConfig, options, this._coachingCache);
 
     const batchSize = pairConfig.batchSize || options.batchSize || DEFAULT_BATCH_SIZE;
     const maxRetries = pairConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
 
     // ── Provider dispatch ──────────────────────────────────────────────
     if (provider === 'openrouter') {
-      const { apiKey } = options;
+      // A request preview needs no key: it is shown, never sent.
+      const apiKey = options.apiKey || (isCapturing() ? PREVIEW_KEY : null);
       if (!apiKey) {
         output.warn('LLM-Coached translate: no API key provided — skipping batch.');
         return null;
       }
       const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
       const llm = new LLMMethod();
-      const batchFn = (batch, opts) => this._callCoachedBatch(batch, structured, opts, pairConfig);
+      const batchFn = (batch, opts) => this._callCoachedBatch(batch, glossary, opts, pairConfig);
       return this._runCoachedBatches(llm, keys, sourceFlat, langConfig, {
-        apiKey, model, maxRetries, systemMessage, batchSize,
+        apiKey, model, maxRetries, systemMessage, batchSize, descriptions: options.descriptions || null,
       }, batchFn);
     }
 
@@ -304,18 +269,20 @@ class LLMCoachedMethod extends TranslationMethod {
     // (_translateWithCascade), but with the coached system message WE built —
     // so the coaching prompt is honored, not the default uncoached system.
     const directMethod = await this._getProviderMethod(provider);
-    const apiKey = directMethod._resolveApiKey(options);
+    const apiKey = directMethod._resolveApiKey(options) || (isCapturing() ? PREVIEW_KEY : null);
     if (!apiKey) {
       output.warn(`LLM-Coached translate (${provider}): no API key — set ${directMethod._getApiKeyEnvVar()}. Skipping batch.`);
       return null;
     }
-    const model = pairConfig.model || options.model || directMethod._getDefaultModel();
-    await directMethod._validateModel(model, apiKey); // DX warnings only; never blocks
+    // The provider's own name for the model; an OpenRouter slug is mapped or
+    // refused (direct-llm.js resolveModelId), never sent to it as is.
+    const model = directMethod.resolveModelId(pairConfig.model || options.model || directMethod._getDefaultModel(), { cwd });
+    if (!isCapturing()) await directMethod._validateModel(model, apiKey, cwd); // DX warnings only; never blocks
     const temperature = pairConfig.temperature ?? DEFAULT_COACHED_TEMPERATURE;
     const batchFn = (batch, opts) => directMethod._callProviderBatch(batch, opts);
     return this._runCoachedBatches(directMethod, keys, sourceFlat, langConfig, {
       apiKey, model, maxRetries, systemMessage, batchSize,
-      coaching: structured, temperature, descriptions: options.descriptions || null,
+      glossary, temperature, descriptions: options.descriptions || null, cwd,
     }, batchFn);
   }
 
@@ -424,26 +391,41 @@ class LLMCoachedMethod extends TranslationMethod {
     const coachingBlock = blocks.join('\n\n');
     const augmentedPrompt = coachingBlock ? `${coachingBlock}\n\n${prompt}` : prompt;
 
-    // Strip the target locale so a direct provider's translateContent does NOT
-    // re-load and re-prepend the SAME structured coaching block (it keys
-    // coaching loading off pairConfig.target; LLMMethod ignores target).
-    const safePairConfig = { ...pairConfig, target: undefined, locale: undefined };
-    return targetMethod.translateContent(augmentedPrompt, safePairConfig, options);
+    // The plain methods send a content prompt as they get it, so the
+    // coaching is prepended once, here, whichever provider carries it.
+    return targetMethod.translateContent(augmentedPrompt, pairConfig, options);
   }
 
   /**
    * Cost estimation — same as LLM but with coached:true flag
    * for the 2.5x input token multiplier (grammar/dictionary injection).
+   * A direct provider prices through its own method (and `local` honestly
+   * returns null) — never through OpenRouter's rate for a model it isn't
+   * sending to OpenRouter.
    *
    * @param {number} keyCount - Number of keys to translate
    * @param {object} [pairConfig] - Pair config containing the model ID
    */
-  async estimateCost(keyCount, pairConfig = {}) {
+  async estimateCost(keyCount, pairConfig = {}, context = {}) {
+    const provider = normalizeProvider(pairConfig.provider ?? this._provider);
+    if (provider !== 'openrouter') {
+      const directMethod = await this._getProviderMethod(provider);
+      return directMethod.estimateCost(keyCount, pairConfig, context);
+    }
     const model = pairConfig.model || DEFAULT_OPENROUTER_MODEL;
     return estimateOpenRouterCost(keyCount, model, { coached: true });
   }
 
-  checkReadiness(context) {
+  /**
+   * Preflight: the credential the run needs is the chosen provider's, not
+   * OpenRouter's. A coached openai pair must pass with only OPENAI_API_KEY set,
+   * and must fail (naming OPENAI_API_KEY) without it.
+   */
+  async checkReadiness(context) {
+    if (this._provider !== 'openrouter') {
+      const directMethod = await this._getProviderMethod(this._provider);
+      return directMethod.checkReadiness(context);
+    }
     if (!context.apiKey) {
       return { ready: false, reason: 'No OpenRouter API key (OPENROUTER_API_KEY).' };
     }
@@ -489,28 +471,15 @@ class LLMCoachedMethod extends TranslationMethod {
    * Make a single coached API call via the shared OpenRouter client.
    * Builds per-batch user message with dictionary hints, uses shared system message.
    */
-  async _callCoachedBatch(toTranslate, coaching, options, pairConfig = {}) {
+  async _callCoachedBatch(toTranslate, glossary, options, pairConfig = {}) {
     const { apiKey, model, batchNum, systemMessage } = options;
 
-    // Build per-batch user message with dictionary hints specific to this batch's
-    // values. `coaching` may be null when only a free-text coaching prompt is
-    // configured (no structured .champollion/coaching/<locale>.json) — in that
-    // case there is no dictionary to match against.
-    const dictHints = (coaching && coaching.dictionary)
-      ? findDictionaryMatches(toTranslate, coaching.dictionary)
-      : [];
-    const typeHints = inferKeyTypes(toTranslate);
-
-    let userMessage = '';
-    if (dictHints.length > 0) {
-      userMessage += 'REQUIRED TERMINOLOGY (use these exact translations):\n';
-      userMessage += dictHints.map(h => `  • "${h.term}" → "${h.translation}"`).join('\n');
-      userMessage += '\n\n';
-    }
-    if (typeHints.length > 0) {
-      userMessage += `UI context for these keys:\n${typeHints.join('\n')}\n\n`;
-    }
-    userMessage += JSON.stringify(toTranslate, null, 2);
+    // The user message every LLM method sends (llm.js buildUserMessage): the
+    // glossary terms this batch contains (none when only a free-text
+    // coaching prompt is configured and the project has no glossary), the
+    // per-key instructions (plural forms, ICU categories, gettext context,
+    // gate feedback), then the batch.
+    const userMessage = buildUserMessage(toTranslate, options.descriptions || undefined, glossary || null);
 
     return callOpenRouterJSON({
       prompt: userMessage,
@@ -628,39 +597,10 @@ function buildContentCoachingBlock(coaching) {
   return parts.length > 0 ? parts.join('\n') : '';
 }
 
-/**
- * Scan source values for dictionary term matches.
- *
- * Uses case-insensitive word-boundary matching to find terms from the
- * coaching dictionary that appear in the current batch's source values.
- *
- * @param {object} toTranslate - Key-value map to scan
- * @param {object} dictionary - Term → translation map
- * @returns {Array<{ term: string, translation: string }>} Matched hints
- */
-function findDictionaryMatches(toTranslate, dictionary) {
-  if (!dictionary || Object.keys(dictionary).length === 0) return [];
-
-  const matches = [];
-  const seen = new Set();
-  const values = Object.values(toTranslate).join(' ').toLowerCase();
-
-  for (const [term, translation] of Object.entries(dictionary)) {
-    if (seen.has(term)) continue;
-
-    // Case-insensitive word-boundary check
-    // Use a simple indexOf for performance — the dictionary is usually small
-    if (values.includes(term.toLowerCase())) {
-      matches.push({ term, translation });
-      seen.add(term);
-    }
-  }
-
-  return matches;
-}
-
 export {
   LLMCoachedMethod,
+  COACHED_PROVIDERS,
+  normalizeProvider,
   loadCoachingData,
   buildCoachedPrompt,
   buildCoachedSystemMessage,

package/lib/methods/llm.js

@@ -44,7 +44,13 @@ import { isUnsafeKey } from '../security.js';
 import { pMap } from '../concurrent.js';
 import { output } from '../output.js';
 import { getEnvOrFileVar } from '../api-key.js';
-
+import { nameRules } from '../name-rules.js';
+import { isCapturing, PREVIEW_KEY } from './request-capture.js';
+import { projectGlossary, terminologyBlock } from './coaching-data.js';
+// The plain LLM methods: one prompt (promptSettingsFor + buildSystemMessage
+// + buildUserMessage), different transports. llm-coached adds its coaching.
+// Defined beside the set the cache key reads (lib/tm.js tmMethodKey).
+import { PLAIN_LLM_METHODS } from './prompt-methods.js';
 
 /** Default per-cascade cap on individual-key fallback calls (see below). */
 const DEFAULT_MAX_KEY_FANOUT = 16;
@@ -72,6 +78,10 @@ function maxKeyFanout() {
 class LLMMethod extends TranslationMethod {
   constructor(options = {}) {
     super('llm', options);
+    this.acceptsKeyInstructions = true; // prompt "UI context" lines (lib/methods/base.js)
+    this.supportsRequestPreview = true; // its transport reports to request-capture.js
+    // Coaching-file cache (the project glossary, lib/methods/coaching-data.js)
+    this._coachingCache = new Map();
   }
 
   /**
@@ -84,7 +94,8 @@ class LLMMethod extends TranslationMethod {
    * @returns {object|null} Map of key → translated value, or null if all failed
    */
   async translate(keys, sourceFlat, pairConfig, options) {
-    const { apiKey } = options;
+    // A request preview needs no key: it is shown, never sent.
+    const apiKey = options.apiKey || (isCapturing() ? PREVIEW_KEY : null);
     const batchSize = pairConfig.batchSize || options.batchSize || DEFAULT_BATCH_SIZE;
     const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
     const maxRetries = pairConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -93,24 +104,16 @@ class LLMMethod extends TranslationMethod {
       return null;
     }
 
-    const langConfig = {
-      name: pairConfig.name,
-      register: pairConfig.register,
-      // Language-specific gender guidance from the card (e.g., écriture inclusive
-      // for French, Doppelpunkt notation for German). Falls back to a generic
-      // rule in buildSystemMessage when null.
-      genderGuidance: pairConfig.genderGuidance || null,
-      // User-provided global context (e.g., "This is a developer tool README").
-      // Injected into the system message to give the LLM domain awareness.
-      promptContext: pairConfig.promptContext || null,
-      // Coaching prompt text — free-text instructions read from a coaching file.
-      // Injected between register and rules in the system message.
-      coachingPrompt: pairConfig.coachingPrompt || null,
-    };
+    // What the pair tells its model — the same reading every LLM method
+    // uses (promptSettingsFor), so openai/anthropic/gemini/local send this
+    // exact system message too.
+    const langConfig = promptSettingsFor(pairConfig);
 
     // Build the system message once — identical across all batches for this locale.
     // This enables provider-level prompt caching (Anthropic, Gemini).
     const systemMessage = buildSystemMessage(langConfig);
+    // The project glossary: each batch is told the terms it contains.
+    const glossary = projectGlossary(pairConfig, options, this._coachingCache);
 
     const allTranslated = {};
 
@@ -140,6 +143,7 @@ class LLMMethod extends TranslationMethod {
         systemMessage,
         temperature: pairConfig.temperature ?? DEFAULT_TEMPERATURE,
         descriptions: options.descriptions || null,
+        glossary,
       }, this._callOpenRouterBatch.bind(this));
 
       if (result) {
@@ -418,7 +422,7 @@ class LLMMethod extends TranslationMethod {
    */
   async _callOpenRouterBatch(toTranslate, options) {
     const { apiKey, model, batchNum, systemMessage, temperature } = options;
-    const userMessage = buildUserMessage(toTranslate, options.descriptions || undefined);
+    const userMessage = buildUserMessage(toTranslate, options.descriptions || undefined, options.glossary || null);
 
     return callOpenRouterJSON({
       prompt: userMessage,
@@ -445,7 +449,7 @@ class LLMMethod extends TranslationMethod {
     output.error(`${keys.length} key(s) could not be translated.`);
     if (!label) {
       output.error(`Consider increasing maxRetries or using a more capable model:`);
-      output.error(`"languages": { "<code>": { "model": "google/gemini-2.5-pro", "batchSize": 5, "maxRetries": 5 } }`);
+      output.error(`"languages": { "<code>": { "model": "google/gemini-3.1-pro-preview", "batchSize": 5, "maxRetries": 5 } }`);
     }
   }
 }
@@ -454,6 +458,46 @@ class LLMMethod extends TranslationMethod {
 // Prompt building — split into system (cached) + user (per-batch)
 // -----------------------------------------------------------------
 
+/**
+ * What a pair tells its model, read from the pair config — the ONE reading
+ * every LLM-backed method uses (llm, openai, anthropic, gemini, local and
+ * llm-coached on any provider). Only the transport differs between them.
+ *
+ * WHY: the direct-provider methods used to build their own, shorter
+ * settings ({ name, register }), so a project's protected terms, its prompt
+ * context and the language's gender guidance never reached a model run
+ * through `local`, `openai`, `anthropic` or `gemini` — a brand name could
+ * be translated there and not through `llm` (found 2026-10-03).
+ *
+ * @param {object} pairConfig - Resolved pair config (lib/pairs.js)
+ * @param {object} [overrides] - Fields a method resolves itself (llm-coached:
+ *   the coaching prompt it read from coachingFile)
+ * @returns {{ name: string, register: string, genderGuidance: string|null,
+ *   promptContext: string|null, protectedTerms: string[], coachingPrompt: string|null }}
+ */
+function promptSettingsFor(pairConfig = {}, overrides = {}) {
+  return {
+    name: pairConfig.name,
+    register: pairConfig.register,
+    // Language-specific gender guidance from the card (e.g., écriture inclusive
+    // for French, Doppelpunkt notation for German). Falls back to a generic
+    // rule in buildSystemMessage when null.
+    genderGuidance: pairConfig.genderGuidance || null,
+    // "genderGuidance": false in the config — no gender instruction at all
+    // (not even the generic one).
+    genderOff: pairConfig.genderGuidanceSource === 'off',
+    // User-provided global context (e.g., "This is a developer tool README").
+    // Injected into the system message to give the LLM domain awareness.
+    promptContext: pairConfig.promptContext || null,
+    // Names the project keeps exactly as written (config.protectedTerms).
+    protectedTerms: pairConfig.protectedTerms || [],
+    // Coaching prompt text — free-text instructions read from a coaching file.
+    // Injected between register and rules in the system message.
+    coachingPrompt: pairConfig.coachingPrompt || null,
+    ...overrides,
+  };
+}
+
 /**
  * Build the system message preamble (cached across batches).
  *
@@ -470,15 +514,18 @@ class LLMMethod extends TranslationMethod {
  * being translated (e.g., "This is a developer tool for i18n"). Injected
  * after the role line to give the LLM domain awareness.
  *
- * @param {object} langConfig - { name, register, genderGuidance?, promptContext? }
+ * @param {object} langConfig - { name, register, genderGuidance?, promptContext?, protectedTerms? }
  * @returns {string} System message
  */
 function buildSystemMessage(langConfig) {
   // Use language-specific gender guidance when available from the card,
   // otherwise fall back to a generic rule for unknown languages.
-  const genderRule = langConfig.genderGuidance
-    ? `- Gender: ${langConfig.genderGuidance}`
-    : '- When gender is ambiguous, prefer gender-neutral forms or the most inclusive option available in ' + langConfig.name + '.';
+  // "genderGuidance": false — the config asked for none.
+  const genderRule = langConfig.genderOff
+    ? null
+    : langConfig.genderGuidance
+      ? `- Gender: ${langConfig.genderGuidance}`
+      : '- When gender is ambiguous, prefer gender-neutral forms or the most inclusive option available in ' + langConfig.name + '.';
 
   // Inject user-provided promptContext to give the LLM domain awareness.
   // This is set in the top-level config and flows through the pair graph.
@@ -499,10 +546,8 @@ Register/tone: ${langConfig.register}
 ${coachingBlock}
 Rules:
 - Translate ONLY the values, keep the keys exactly as-is.
-- Proper nouns (product names, company names, place names) should NOT be translated.
-- Technical terms and role descriptions that are industry-standard should stay in English.
-${genderRule}
-- Respect the UI element type: button labels should be concise, descriptions can be natural-length, error messages should be clear and direct.
+${nameRules(langConfig.protectedTerms)}
+${genderRule ? `${genderRule}\n` : ''}- Respect the UI element type: button labels should be concise, descriptions can be natural-length, error messages should be clear and direct.
 - Quotation marks inside a translated value: use the target language's typographic quotation marks (e.g. “…”, «…», 「…」); if you must use ASCII double quotes, escape them as \\" so the JSON stays valid.
 - Return ONLY valid JSON, no markdown fences, no explanation.`;
 }
@@ -510,8 +555,9 @@ ${genderRule}
 /**
  * Build the user message (varies per batch).
  *
- * Contains: UI context hints for key names + the JSON payload.
- * This changes with every batch, so it's never cached.
+ * Contains: the glossary terms this batch contains (REQUIRED TERMINOLOGY),
+ * UI context hints for key names + the JSON payload. This changes with
+ * every batch, so it's never cached.
  *
  * Descriptions: When Docusaurus {message, description} files provide
  * developer-written descriptions (e.g., "The title of the blog page"),
@@ -520,9 +566,12 @@ ${genderRule}
  *
  * @param {object} toTranslate - Key-value map to translate
  * @param {object} [descriptions] - Optional key→description map from Docusaurus
+ * @param {Object<string, string>|null} [glossary] - The project glossary
+ *   (lib/methods/coaching-data.js projectGlossary); only the terms this
+ *   batch contains are listed
  * @returns {string} User message
  */
-function buildUserMessage(toTranslate, descriptions) {
+function buildUserMessage(toTranslate, descriptions, glossary = null) {
   const typeHints = inferKeyTypes(toTranslate);
 
   // Merge auto-inferred type hints with Docusaurus descriptions.
@@ -547,7 +596,7 @@ function buildUserMessage(toTranslate, descriptions) {
     ? `UI context for these keys:\n${typeHints.join('\n')}\n\n`
     : '';
 
-  return `${hintsBlock}${JSON.stringify(toTranslate, null, 2)}`;
+  return `${terminologyBlock(toTranslate, glossary)}${hintsBlock}${JSON.stringify(toTranslate, null, 2)}`;
 }
 
 /**
@@ -589,4 +638,4 @@ function inferKeyTypes(toTranslate) {
   return hints;
 }
 
-export { LLMMethod, buildPrompt, buildSystemMessage, buildUserMessage, isUnsafeKey, inferKeyTypes };
+export { LLMMethod, PLAIN_LLM_METHODS, buildPrompt, buildSystemMessage, buildUserMessage, promptSettingsFor, isUnsafeKey, inferKeyTypes };

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).',
     ];
   }