champollion 0.3.4 → 0.4.0

package/lib/content.js

@@ -1,5 +1,8 @@
 /**
- * Markdown content translation — translates Hugo content files.
+ * Markdown content translation — translates the Markdown/MDX files in a
+ * `contentDir`: a Hugo site's content/ folder, or any folder of Markdown
+ * (a Next.js app's newsletters/, a docs/ folder…). The naming rule below is
+ * the same for both; detectContentSite() only labels which one it is.
  *
  * WHY: Hugo stores page content as Markdown files with YAML front matter.
  * Unlike i18n string files (key→value pairs), content files need:
@@ -9,16 +12,18 @@
  *   3. Body translation — send the protected Markdown to the LLM
  *   4. Reassembly — restore protected blocks and rebuild the file
  *
- * Hugo's translation-by-filename convention:
+ * Hugo's translation-by-filename convention (used for every contentDir):
  *   content/posts/my-post.md       → default language
  *   content/posts/my-post.fr.md    → French
  *   content/posts/my-post.ja.md    → Japanese
+ *   newsletters/2026-10.md         → newsletters/2026-10.crk.md (Plains Cree)
  *
  * This module handles the parse→protect→translate→restore→write pipeline.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { nameRules } from './name-rules.js';
 
 // Sentinel used for protected block placeholders. Uses Unicode brackets
 // that are extremely unlikely to appear in real content, making them
@@ -481,7 +486,7 @@ function hasOrphanedPlaceholders(text) {
 // -----------------------------------------------------------------
 
 /**
- * Scan a Hugo content directory for source language Markdown files.
+ * Scan a content directory (Hugo's content/ or any folder) for source-language Markdown files.
  *
  * Uses Hugo's filename convention: files without a language suffix
  * (e.g., my-post.md) or with the source language suffix
@@ -523,14 +528,95 @@ function discoverContentFiles(contentDir, sourceLocale) {
 }
 
 /**
- * Check if a string looks like a language code (2-3 lowercase letters,
- * optionally with a region suffix like zh-TW).
+ * Check if a string looks like a language code: 2-3 lowercase letters,
+ * optionally a script (Hant, Latn) and/or a region (TW, BR, 419) —
+ * the shapes a target code takes in a translated file's name.
  *
  * WHY: We need to distinguish "my-post.md" (no lang suffix) from
  * "my-post.fr.md" (French) and "version.2.md" (not a lang code).
+ * Script and numeric-region codes matter: before they were recognised,
+ * "my-post.zh-Hant.md" (written by sync for a zh-Hant target) was taken
+ * for a SOURCE file on the next run and translated into every target.
  */
 function isLikelyLangCode(str) {
-  return /^[a-z]{2,3}(-[A-Z]{2})?$/.test(str);
+  return /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/.test(str);
+}
+
+// -----------------------------------------------------------------
+// Which kind of site a content directory belongs to
+// -----------------------------------------------------------------
+
+// Hugo's own configuration file names (Hugo ≥ 0.110 prefers hugo.*).
+const HUGO_CONFIG_FILES = ['hugo.toml', 'hugo.yaml', 'hugo.yml', 'hugo.json'];
+// Older Hugo sites use config.*, but so do many other tools — such a file
+// counts as Hugo evidence only when it carries a setting only Hugo uses.
+const GENERIC_CONFIG_FILES = ['config.toml', 'config.yaml', 'config.yml', 'config.json'];
+const HUGO_SETTING_REGEX = /^[ \t]*["']?(?:baseURL|baseurl|defaultContentLanguage|languageCode|disableKinds|enableRobotsTXT|hasCJKLanguage|enableGitInfo|enableEmoji|summaryLength|pluralizeListTitles)["']?[ \t]*[:=]/m;
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function isDirectory(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Say what a content directory belongs to — for the sync banner, which used
+ * to announce "Detected framework: Hugo" for ANY contentDir, including a
+ * plain folder of Markdown newsletters in a Next.js app. Hugo is reported
+ * only on real Hugo evidence, looked for in the project root and in the
+ * folder that holds the content directory (Hugo's own layout: site/content):
+ *
+ *   - a hugo.toml / hugo.yaml / hugo.yml / hugo.json,
+ *   - Hugo's config directory (config/_default/…),
+ *   - a config.toml / .yaml / .yml / .json carrying a Hugo-only setting
+ *     (baseURL, defaultContentLanguage, languageCode, …),
+ *   - an archetypes/ folder, or a layouts/ folder of Hugo templates
+ *     (layouts/_default/, or .html files).
+ *
+ * Detection changes no behaviour: every content directory is translated the
+ * same way — each translation written beside its source as
+ * <name>.<locale>.md (or .mdx).
+ *
+ * @param {string} contentDir - The configured content directory
+ * @param {string} [cwd] - Project root
+ * @returns {{ site: 'hugo'|'markdown', evidence: string|null }}
+ *   evidence: the project-relative path that identified a Hugo site.
+ */
+function detectContentSite(contentDir, cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  const roots = [...new Set([root, path.dirname(path.resolve(cwd, contentDir))])];
+  const rel = (p) => path.relative(root, p) || '.';
+
+  for (const dir of roots) {
+    for (const name of HUGO_CONFIG_FILES) {
+      const p = path.join(dir, name);
+      if (isFile(p)) return { site: 'hugo', evidence: rel(p) };
+    }
+    for (const name of [...HUGO_CONFIG_FILES, ...GENERIC_CONFIG_FILES]) {
+      const p = path.join(dir, 'config', '_default', name);
+      if (isFile(p)) return { site: 'hugo', evidence: rel(p) };
+    }
+    for (const name of GENERIC_CONFIG_FILES) {
+      const p = path.join(dir, name);
+      if (!isFile(p)) continue;
+      let text = '';
+      try { text = fs.readFileSync(p, 'utf-8'); } catch { continue; }
+      if (HUGO_SETTING_REGEX.test(text)) return { site: 'hugo', evidence: `${rel(p)} (Hugo settings)` };
+    }
+    const archetypes = path.join(dir, 'archetypes');
+    if (isDirectory(archetypes)) return { site: 'hugo', evidence: `${rel(archetypes)}/` };
+    const layouts = path.join(dir, 'layouts');
+    if (isDirectory(layouts)) {
+      let hugoTemplates = isDirectory(path.join(layouts, '_default'));
+      if (!hugoTemplates) {
+        try { hugoTemplates = fs.readdirSync(layouts).some(n => n.endsWith('.html')); } catch { hugoTemplates = false; }
+      }
+      if (hugoTemplates) return { site: 'hugo', evidence: `${rel(layouts)}/` };
+    }
+  }
+  return { site: 'markdown', evidence: null };
 }
 
 /**
@@ -596,7 +682,7 @@ Rules:
 - Translate ALL human-readable text in the Markdown.
 - Preserve ALL Markdown formatting: headers (#), bold (**), italic (*), links, images, lists, blockquotes, etc.${placeholderRule}
 - Preserve all line breaks, paragraph spacing, and document structure.
-- Proper nouns, product names, and technical terms should remain in the source language.
+${nameRules(options.protectedTerms)}
 - Translate link text but preserve link URLs. For example: [Read more](url) → [Lire la suite](url)
 - Return ONLY the translated Markdown. No code fences, no explanation, no preamble.
 
@@ -724,6 +810,7 @@ export {
   buildContentPrompt,
   reassembleContentFile,
   isLikelyLangCode,
+  detectContentSite,
   DEFAULT_TRANSLATABLE_FIELDS,
   NON_TRANSLATABLE_NESTED_FIELDS,
   PLACEHOLDER_PREFIX,

package/lib/corpus-registration.mjs

@@ -34,8 +34,9 @@ import { classifyLicense, TIERS } from './license-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // LICENSE OPTIONS — the plain-language picklist. `commercial` / `redistribution`
-// are the booleans written onto the card's `license` block (the license's plain
-// terms for OUR lanes). `publicEligible` is the author-facing hint; the real
+// are the booleans written onto the card's `license` block: the licence's OWN
+// terms — what it lets others do — never which of our lanes the corpus may
+// enter. That is `publicEligible`, the author-facing hint; the real
 // gate is gatePublicRegistration(), which cross-checks license-gate.mjs and
 // fails safe to blocked.
 // ---------------------------------------------------------------------------
@@ -72,9 +73,12 @@ export const LICENSE_OPTIONS = [
     label: 'CC-BY-NC-4.0',
     spdx: 'CC-BY-NC-4.0',
     commercial: false,
-    redistribution: false,
+    // CC BY-NC 4.0 §2(a)(1)(B): the licence lets anyone share the material
+    // for non-commercial purposes. It said `false` here — a statement about
+    // OUR public lane written as a licence term (the lane is publicEligible).
+    redistribution: true,
     publicEligible: false,
-    explanation: 'Free for non-commercial use only. Cannot enter the public ranked or commercial lanes — register privately or local-only.',
+    explanation: 'Free for non-commercial use and sharing only. Cannot enter the public ranked or commercial lanes — register privately or local-only.',
   },
   {
     key: 'cc-by-nc-sa-4.0',
@@ -234,23 +238,75 @@ export function resolveLicense(input) {
   );
   if (hit) return hit;
 
-  // Anything else: a raw SPDX the author typed. Classify it through the gate so
-  // a real permissive/share-alike id still works, but unknowns fail safe.
+  // Anything else: an SPDX id the author typed. A standard licence the gate
+  // recognises (CC-BY-2.0, MIT, CC-BY-NC-SA-3.0 …) is recorded as the
+  // standard licence it is, with that licence's own terms; only an id the
+  // gate does not know — or a LicenseRef-, which is never a standard SPDX
+  // id — is custom/unconfirmed and fails safe. CC-BY-2.0 used to be called
+  // "Custom/unconfirmed" on the card (Round 14, researcher persona).
   const cls = classifyLicense({ license_spdx: raw });
-  const permissive = cls.tier === TIERS.PERMISSIVE;
-  const shareAlike = cls.tier === TIERS.SHAREALIKE;
+  const terms = /^LicenseRef-/i.test(raw) ? null : STANDARD_TIER_TERMS[cls.tier];
+  if (terms) {
+    return {
+      key: raw.toLowerCase(),
+      label: raw,
+      spdx: raw,
+      commercial: terms.commercial,
+      redistribution: terms.redistribution,
+      publicEligible: terms.publicEligible,
+      explanation: `${raw} — a standard licence (${cls.tier}): ${terms.plain}`,
+      standard: true,
+    };
+  }
   return {
     key: 'custom',
     label: raw,
     spdx: raw,
-    commercial: permissive || shareAlike,
-    redistribution: permissive || shareAlike,
-    publicEligible: permissive || shareAlike,
-    explanation: `Custom license "${raw}" classified as ${cls.tier} by the license gate.`,
+    commercial: false,
+    redistribution: false,
+    publicEligible: false,
+    explanation: `Custom license "${raw}" (${cls.tier} to the license gate) — treated as not-redistributable until its terms are confirmed.`,
     custom: true,
   };
 }
 
+/**
+ * A standard licence's own terms, by the license gate's tier: what the
+ * licence lets others do (`commercial`, `redistribution`) — never a statement
+ * about which of OUR lanes it may enter (that is `publicEligible`, and the
+ * public gate re-checks it).
+ */
+const STANDARD_TIER_TERMS = Object.freeze({
+  [TIERS.PERMISSIVE]: { commercial: true, redistribution: true, publicEligible: true,
+    plain: 'anyone may use and share it, commercially too, under its terms (attribution where it asks).' },
+  [TIERS.SHAREALIKE]: { commercial: true, redistribution: true, publicEligible: true,
+    plain: 'anyone may use and share it, commercially too; what is built on it is shared under the same terms.' },
+  [TIERS.NONCOMMERCIAL]: { commercial: false, redistribution: true, publicEligible: false,
+    plain: 'non-commercial use and sharing only, under the same terms.' },
+  [TIERS.NODERIVATIVES]: { commercial: true, redistribution: true, publicEligible: false,
+    plain: 'may be shared verbatim under its terms; no modified versions may be distributed.' },
+});
+
+/**
+ * The licence's redistribution term, in the card's usageRestrictions enum:
+ * 'prohibited' when the licence does not allow it, 'permitted' for a
+ * permissive licence, 'same-terms' for any other that allows it (share-alike,
+ * non-commercial, no-derivatives: shared only under the licence's own terms).
+ * From the LICENCE only — never from the exposure tier: a local-only card
+ * used to say "prohibited" here beside license.redistribution: true, and
+ * `mt-eval contest prepare` then told the organizer not to release a
+ * CC-BY-2.0 dev set (Round 14, researcher persona). Where the steward lets
+ * the text travel is the separate `transmission` mark.
+ *
+ * @param {{spdx: string, redistribution: boolean}} license - the card's license block
+ * @returns {'prohibited'|'permitted'|'same-terms'}
+ */
+export function redistributionTerm(license) {
+  if (license.redistribution !== true) return 'prohibited';
+  const tier = classifyLicense({ license_spdx: license.spdx }).tier;
+  return tier === TIERS.PERMISSIVE ? 'permitted' : 'same-terms';
+}
+
 /**
  * Resolve an exposure-tier choice to a tier object. Accepts a key, a label, a
  * 1-based index, or the aliases 'local'/'secret'/'sovereign'. Defaults to the
@@ -292,7 +348,9 @@ export function deriveLicenseBlock(option) {
     commercial: option.commercial,
     redistribution: option.redistribution,
     aiTraining: option.aiTraining === undefined ? null : option.aiTraining,
-    notes: option.custom ? 'Custom/unconfirmed license — verify terms before any commercial or redistribution use.' : null,
+    // Only a licence whose terms are not known: an id the gate does not
+    // recognise, or the picklist's "Other / custom (unconfirmed)".
+    notes: option.custom || option.key === 'other' ? 'Custom/unconfirmed license — verify terms before any commercial or redistribution use.' : null,
   };
 }
 
@@ -396,15 +454,58 @@ export function slugify(text) {
 }
 
 /**
- * Derive a default card id from the pair + a name/publisher slug.
- * Shape mirrors existing cards: eval-<src>-<tgt>-<slug>-dev-v<major>.
+ * What a registered set is FOR, as the author states it (`--role`). Optional:
+ * the card id carries a role segment only when the author gave one.
+ *
+ * WHY optional: the id scheme does not require a role — the corpora-card
+ * schema's id pattern is `^(ref|eval)-[a-z0-9][a-z0-9-]*$`, and tracked cards
+ * already exist without one (eval-in22-gen-v1, eval-smol-doc-v1). No consumer
+ * (registry builder, harness, MCP server, database) parses the role out of an
+ * id. Stamping `dev` on every registration (2026-10-03 hospital persona) told
+ * readers a nurse-checked held-out TEST set was a development split.
+ */
+export const CORPUS_ROLES = Object.freeze(['test', 'dev', 'train']);
+
+/** Normalise a --role value: lower-cased + trimmed, or null when not given. */
+export function normalizeRole(value) {
+  if (value === undefined || value === null || value === false) return null;
+  const s = String(value).trim().toLowerCase();
+  return s ? s : null;
+}
+
+/**
+ * The id slug: from the corpus NAME, falling back to the publisher only when
+ * the name has no a–z/0–9 characters (e.g. a name written in syllabics), then
+ * to 'custom'. Before 2026-10-03 the publisher won whenever one was given, so
+ * "Hospital nurse-checked test" by "Hospital clinical informatics" became
+ * eval-…-hospital-clinical-informatics-dev-v1.
  */
-export function deriveCardId({ source, target, slug, version = '1' }) {
+export function deriveIdSlug({ name, publisher } = {}) {
+  return slugify(name) || slugify(publisher) || 'custom';
+}
+
+/**
+ * Derive a NEW card id: eval-<src>-<tgt>-<slug>[-<role>]-v<major>.
+ *
+ * The role segment appears only when the author stated one, and is not
+ * repeated when the slug already ends with it ("… test" + --role test →
+ * …-test-v1, not …-test-test-v1). Only ever used for a registration that has
+ * no id yet — an id already registered is never re-derived.
+ */
+export function deriveCardId({ source, target, slug, role = null, version = '1' }) {
   const major = String(version).split('.')[0] || '1';
   const tag = slug && slug.length ? slug : 'custom';
-  return `eval-${source}-${target}-${tag}-dev-v${major}`;
+  const r = normalizeRole(role);
+  if (r !== null && !CORPUS_ROLES.includes(r)) {
+    throw new Error(`Unknown role '${role}'. Use one of: ${CORPUS_ROLES.join(', ')} (or none).`);
+  }
+  const withRole = r === null || tag === r || tag.endsWith(`-${r}`) ? tag : `${tag}-${r}`;
+  return `eval-${source}-${target}-${withRole}-v${major}`;
 }
 
+/** The corpora-card schema's id pattern (cli/shared/schemas/corpora-card.schema.json). */
+export const CARD_ID_PATTERN = /^(ref|eval)-[a-z0-9][a-z0-9-]*$/;
+
 /**
  * Build a corpora card object for a registration.
  *
@@ -421,12 +522,17 @@ export function deriveCardId({ source, target, slug, version = '1' }) {
  * @param {string|null} [o.sha256]      built-corpus hash (optional)
  * @param {object} o.licenseOption      a resolveLicense() result
  * @param {object} o.tier               a resolveTier() result
- * @param {string} [o.contaminationRisk]  NONE|LOW|MEDIUM|HIGH
+ * @param {string} [o.contaminationRisk]  NONE|LOW|MEDIUM|HIGH, or UNCHECKED (the
+ *        file could not be compared with the public corpora and no grade was stated)
+ * @param {string|null} [o.role]        test|dev|train — `test` writes the size under `test`
+ * @param {boolean} [o.dataRead]        a local data file was read (to count + checksum)
  * @param {string} [o.contaminationReasoning]
  * @param {number} o.size
  * @param {string} [o.sizeUnit]
  * @param {string} o.domain
  * @param {boolean} [o.doNotTrain]
+ * @param {string|null} [o.transmission] 'local-only' when the data file is already
+ *        marked local-only (its sidecar); a local-only tier is marked regardless
  * @param {string} o.addedAt            ISO date (injected for determinism)
  * @param {string} [o.populatedFrom]
  * @param {object} [o.sealed]           content-free sealed block (sealed tier
@@ -434,6 +540,21 @@ export function deriveCardId({ source, target, slug, version = '1' }) {
  *        ciphertextDigest/aad + key + qualifier refs). NEVER contains text.
  * @returns {object} a corpora card (metadata only — never contains text)
  */
+/**
+ * What registration did with the corpus text, truthfully (Round 9, hospital
+ * persona: a local-only card said "corpus content was never read" while the
+ * command had just read the file to count and checksum it).
+ */
+function readNote(o) {
+  if (o.tier.key === 'sealed') {
+    return 'Metadata only — the plaintext was read on this machine only to encrypt it; only ciphertext and this content-free card were written, and no text was uploaded or hosted.';
+  }
+  if (o.dataRead) {
+    return 'Metadata only — the text was read on this machine only to count its entries and compute its sha256; none of it was uploaded or hosted, and none of it left the machine.';
+  }
+  return 'Metadata only — corpus content was never read, uploaded, or hosted.';
+}
+
 export function buildCorpusCard(o) {
   const tierKey = o.tier.key;
   const isPublic = tierKey === 'public';
@@ -464,30 +585,54 @@ export function buildCorpusCard(o) {
     if (o.licenseUrl) source.license_url = o.licenseUrl;
   }
 
-  // dev block — records the consumer-reports length/size + domain. dataFile
-  // (a hosted-content path) is set ONLY for the public tier, where the builder
-  // reproduces it from source; private/local-only never name a data file.
-  const dev = {
+  // The split block — size, unit and domain, under the split the author
+  // named: `test` for a test set (the schema's public test split), `dev`
+  // otherwise (a dev set, a role not stated, and `train`, which the schema
+  // has no block for). A test set used to be written under `dev` (Round 9,
+  // hospital persona). Readers of `dev` (arena build_registry, corpus_fetch)
+  // fall back to `test`. dataFile (a hosted-content path) is set ONLY for the
+  // public tier, where the builder reproduces it from source;
+  // private/local-only never name a data file. It is named after the card
+  // id: a pair-only name stamped a `dev` role the author never stated, and
+  // two public cards for one pair shared one path.
+  const splitKey = o.role === 'test' ? 'test' : 'dev';
+  const split = {
     size: o.size,
     sizeUnit: o.sizeUnit || 'entries',
     domain: o.domain,
   };
   if (isPublic) {
-    dev.dataFile = `curated/${o.pair.source}-${o.pair.target}-dev-v1.json`;
-    dev.format = 'harness-json';
+    split.dataFile = `curated/${o.id}.json`;
+    split.format = 'harness-json';
   }
 
-  const doNotTrain = o.doNotTrain !== false; // default true (benchmark integrity)
-
+  // Training: ONE source of truth, doNotTrain (default true — an evaluation
+  // set is not trained on). A licence that itself refuses training (the
+  // steward-terms options: license.aiTraining false) makes it true.
+  // usageRestrictions.training says only WHO set it, and agrees with it.
+  // It used to say "discouraged" (not prohibited) beside doNotTrain: true
+  // ("must not"), and "prohibited-by-license" for any non-commercial licence
+  // although NC says nothing about training (Round 14, researcher persona).
+  const licenceRefusesTraining = license.aiTraining === false;
+  const doNotTrain = o.doNotTrain !== false || licenceRefusesTraining;
+
+  // Each term is stated once, from where it comes from: commercial use and
+  // redistribution by the licence (license.*; commercialUse null = "defer to
+  // license.commercial", as the schema reads it); redistribution is repeated
+  // in the enum `mt-eval contest prepare` reads, from the licence only —
+  // never from the exposure tier (see redistributionTerm).
   const usageRestrictions = {
-    training: doNotTrain ? (license.commercial ? 'discouraged' : 'prohibited-by-license') : 'permitted',
-    commercialUse: license.commercial ? 'permitted' : 'prohibited-by-license',
-    redistribution: isPublic
-      ? (o.licenseOption.spdx.toUpperCase().includes('-SA') ? 'same-terms' : 'permitted')
-      : 'prohibited',
+    training: !doNotTrain ? 'permitted' : (licenceRefusesTraining ? 'prohibited-by-license' : 'prohibited-by-community'),
+    commercialUse: null,
+    redistribution: redistributionTerm(license),
     communityNotes: null,
   };
 
+  // Where the steward lets the text travel — a mark, not a licence term
+  // (schema: `transmission`). A local-only set, or a file already marked
+  // local-only (its sidecar keeps the mark; the card says the same).
+  const localOnly = tierKey === 'local-only' || o.transmission === 'local-only';
+
   const card = {
     id: o.id,
     type: 'eval',
@@ -501,16 +646,17 @@ export function buildCorpusCard(o) {
     description: o.description,
     source,
     license,
-    dev,
+    [splitKey]: split,
     contamination: { risk, reasoning },
     doNotTrain,
     exposureTier: tierKey,
+    ...(localOnly ? { transmission: 'local-only' } : {}),
     usageRestrictions,
     _provenance: {
       addedAt: o.addedAt,
       populatedFrom:
         o.populatedFrom ||
-        `Registered via 'champollion register-corpus' (exposureTier=${tierKey}). Metadata only — corpus content was never read, uploaded, or hosted.`,
+        `Registered via 'champollion register-corpus' (exposureTier=${tierKey}). ${readNote(o)}`,
     },
   };
 
@@ -569,11 +715,13 @@ export function resolveDestination({ tier, id, corporaCardsDir, localDir }) {
  * @param {object} o.tier
  * @param {object|null} o.licenseOption
  * @param {{source?:string,target?:string}} o.pair
+ * @param {string|null} [o.pairError]  why --pair could not be read (lib/language-pair.js), if it could not
  * @param {string} o.name
  * @param {string|null} [o.repoUrl]
  * @param {string|null} [o.builder]
  * @param {number|null} [o.size]
  * @param {string} [o.domain]
+ * @param {string|null} [o.role]               optional: test | dev | train (see CORPUS_ROLES)
  * @param {string|null} [o.custodianGroupId]   sealed tier: custodian group id
  * @param {string|null} [o.thresholdPublicKey] sealed tier: threshold pubkey (path/value)
  * @param {string|null} [o.sealInput]          sealed tier: local corpus file to encrypt
@@ -583,11 +731,22 @@ export function resolveDestination({ tier, id, corporaCardsDir, localDir }) {
 export function validateRegistration(o) {
   const errors = [];
   if (!o.name || !String(o.name).trim()) errors.push('A corpus name is required (--name).');
-  if (!o.pair || !o.pair.source) errors.push('A source language code is required (--pair "src>tgt" or --source-lang).');
-  if (!o.pair || !o.pair.target) errors.push('A target language code is required (--pair "src>tgt" or --target-lang).');
+  if (o.pairError) {
+    // --pair was given but could not be read: say why, not "a code is required".
+    errors.push(o.pairError);
+  } else {
+    if (!o.pair || !o.pair.source) errors.push('A source language code is required (--pair "src>tgt" or src-tgt, or --source-lang).');
+    if (!o.pair || !o.pair.target) errors.push('A target language code is required (--pair "src>tgt" or src-tgt, or --target-lang).');
+  }
   if (!o.licenseOption) errors.push('A license is required (--license). Run with --list to see options.');
   if (!(Number(o.size) > 0)) errors.push('A positive corpus size is required (--size).');
   if (!o.domain || !String(o.domain).trim()) errors.push('A domain is required (--domain), e.g. news, conversational, educational.');
+  const role = o.role === true ? null : normalizeRole(o.role);
+  if (o.role === true) {
+    errors.push(`--role needs a value: ${CORPUS_ROLES.join(', ')} (or leave --role out, and the id names no role).`);
+  } else if (role !== null && !CORPUS_ROLES.includes(role)) {
+    errors.push(`Unknown --role '${o.role}'. Use ${CORPUS_ROLES.join(', ')} — or leave --role out, and the id names no role.`);
+  }
 
   if (o.tier.key === 'public') {
     if (!o.repoUrl) errors.push('Public registration needs a fetch-from-source pointer (--repo-url) — we never host content.');

package/lib/cost-label.js

@@ -0,0 +1,29 @@
+/**
+ * One wording for a cost estimate, wherever a price is named beside a command
+ * or an answer: the redo notes of `sync`, the named-key cache note, and the
+ * MCP server's `translate` answer (Round 9: the MCP said "0 USD" for a model
+ * on this machine, where the CLI says "$0 API cost (runs on this machine)").
+ *
+ * Pure, no imports: the MCP server reads it from the package's exports.
+ *
+ * The estimate is the object a method's estimateCost() returns
+ * ({ estimatedCost: number|null, local?: true, … }):
+ *   - a model served on this machine (local: true, $0)  → "$0 API cost (runs on this machine)"
+ *   - a known price                                     → "est. ~$0.0123"
+ *   - no published price (null), or no estimate at all  → "cost unknown — no published price" / "cost unknown"
+ */
+
+/** What a model on this machine costs, in the words every surface uses. */
+export const LOCAL_COST_LABEL = '$0 API cost (runs on this machine)';
+
+/**
+ * @param {{ estimatedCost?: number|null, local?: boolean }|null|undefined} estimate
+ * @returns {string}
+ */
+export function costLabel(estimate) {
+  if (!estimate || typeof estimate !== 'object') return 'cost unknown';
+  const cost = estimate.estimatedCost;
+  if (estimate.local && cost === 0) return LOCAL_COST_LABEL;
+  if (typeof cost === 'number' && Number.isFinite(cost)) return `est. ~$${cost.toFixed(4)}`;
+  return 'cost unknown — no published price';
+}