champollion 0.3.4 → 0.5.0

package/lib/methods/llm-coached.js

@@ -56,20 +56,19 @@ 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 { requireExactModelId } from '../models.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 +82,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 +164,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 +233,36 @@ 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;
+      // Exact slugs only (founder ruling 2026-10-05): refused before anything is sent.
+      const model = requireExactModelId(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 +271,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 +393,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 +473,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 +599,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,14 @@ import { isUnsafeKey } from '../security.js';
 import { pMap } from '../concurrent.js';
 import { output } from '../output.js';
 import { getEnvOrFileVar } from '../api-key.js';
-
+import { requireExactModelId } from '../models.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 +79,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,33 +95,28 @@ 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;
+    // Exact slugs only (founder ruling 2026-10-05) — checked here too, since
+    // callers outside the pair graph (the MCP translate tool) reach this directly.
+    const model = requireExactModelId(pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL);
     const maxRetries = pairConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
     if (!apiKey) {
       output.warn('LLM translate: no API key provided — skipping batch.');
       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 +146,7 @@ class LLMMethod extends TranslationMethod {
         systemMessage,
         temperature: pairConfig.temperature ?? DEFAULT_TEMPERATURE,
         descriptions: options.descriptions || null,
+        glossary,
       }, this._callOpenRouterBatch.bind(this));
 
       if (result) {
@@ -177,7 +184,9 @@ class LLMMethod extends TranslationMethod {
    */
   async translateContent(prompt, pairConfig, options) {
     const { apiKey } = options;
-    const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
+    // Exact slugs only (founder ruling 2026-10-05) — checked here too, since
+    // callers outside the pair graph (the MCP translate tool) reach this directly.
+    const model = requireExactModelId(pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL);
     if (!apiKey) {
       output.warn('LLM translateContent: no API key provided — skipping.');
       return null;
@@ -418,7 +427,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 +454,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 +463,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 +519,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 +551,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 +560,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 +571,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 +601,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 +643,4 @@ function inferKeyTypes(toTranslate) {
   return hints;
 }
 
-export { LLMMethod, buildPrompt, buildSystemMessage, buildUserMessage, isUnsafeKey, inferKeyTypes };
+export { LLMMethod, PLAIN_LLM_METHODS, buildPrompt, buildSystemMessage, buildUserMessage, promptSettingsFor, isUnsafeKey, inferKeyTypes };