@the-i18n-kit/cli 6.0.0 → 8.0.0

package/dist/{index-w-EQZEZF.d.ts → index-CWFWYHf5.d.ts}

@@ -1,7 +1,127 @@
-import { a as LocaleDir, i as LocaleDefinition, n as defineI18nKitConfig, o as ProjectConfig, r as I18nConfig, s as LocaleFileFormat, t as I18nKitConfig } from "./define-config-DW-rgsU6.js";
+import { a as LocaleDir, i as LocaleDefinition, n as defineI18nKitConfig, o as ProjectConfig, r as I18nConfig, t as I18nKitConfig } from "./define-config-ZRZw5PWy.js";
 
-//#region src/core/types.d.ts
+//#region src/config/layer-graph.d.ts
 
+/**
+ * Queryable view over the layer topology a resolved {@link I18nConfig}
+ * already carries: which locale dirs are canonical (alias-free), which
+ * layer owns an aliased dir, and which apps consume which layers.
+ *
+ * This is a pure derivation — no filesystem access, no config-shape
+ * changes. Cross-layer tooling (duplicate detection, scope-aware orphan
+ * scanning) builds on these queries instead of name-matching heuristics.
+ *
+ * ## Degenerate-case semantics
+ *
+ * These are load-bearing for consumers (scope-aware scanning must never
+ * wrongly narrow its scan scope):
+ *
+ * - **No app info** (`config.apps` empty or absent, e.g. hand-built
+ *   configs): consumption edges are unknowable. `appsUsingLayer` and
+ *   `layersOfApp` return `[]`, and `sharedLayers` conservatively contains
+ *   *every* canonical layer — with no ownership information, every
+ *   layer's keys must be treated as globally visible.
+ * - **Single-app config** (generic/Laravel/React adapters, or a Nuxt
+ *   project with one app): the strict definition applies, so
+ *   `sharedLayers` is empty (no layer is consumed by more than one app)
+ *   and `appsUsingLayer` returns that one app for the layers it consumes.
+ *   Per-layer scope then equals the whole project, which is correct.
+ * - **Canonical layer consumed by no app** (in a multi-app config):
+ *   `appsUsingLayer` returns `[]` and the layer is not in `sharedLayers`.
+ *   Callers should treat such layers conservatively (global scope).
+ */
+interface LayerGraph {
+  /**
+   * Alias-free locale dirs, in `config.localeDirs` order. Aliased entries
+   * (e.g. `app-outlook` pointing at `app-shop`'s dir) are excluded.
+   */
+  canonicalLayers: LocaleDir[];
+  /**
+   * Resolve a layer name to the canonical layer that owns its locale dir.
+   * Follows chained `aliasOf` links (an alias may point at a layer that
+   * was itself demoted to an alias). Identity for canonical names and for
+   * names unknown to `localeDirs` (e.g. layers without locale dirs).
+   */
+  ownerOf: (layer: string) => string;
+  /**
+   * Names of apps whose consumed layers include the given layer. The
+   * queried name and each app's layer list are alias-resolved via
+   * {@link ownerOf} first, so querying an alias name yields the owner's
+   * consumers. Returns `[]` when no app info exists.
+   */
+  appsUsingLayer: (layer: string) => string[];
+  /**
+   * Canonical layers consumed by more than one app — e.g. a shared root
+   * layer in a multi-app monorepo, identified purely from consumption
+   * edges (no name matching). When no app info exists, contains every
+   * canonical layer (see degenerate-case semantics above).
+   */
+  sharedLayers: LocaleDir[];
+  /**
+   * Canonical layers the given app consumes (alias entries in the app's
+   * layer list resolve to their owners; layers without locale dirs are
+   * omitted). Returns `[]` for unknown apps or when no app info exists.
+   */
+  layersOfApp: (app: string) => LocaleDir[];
+}
+/**
+ * Build a {@link LayerGraph} from a resolved config's `localeDirs`
+ * (with their `aliasOf` markers) and `apps` (app → consumed-layers edges).
+ */
+declare function buildLayerGraph(config: I18nConfig): LayerGraph;
+/**
+ * The graph as plain data, for surfaces that can only carry JSON.
+ *
+ * {@link LayerGraph} is function-valued, so it cannot be serialised directly.
+ * This answers the question an agent actually has — *which layer does this key
+ * belong in* — which the flat layer list `discover` returned could not: a key
+ * used by more than one app belongs in a layer those apps share, and `shared`
+ * names those layers outright (#342).
+ *
+ * The degenerate cases documented on {@link LayerGraph} survive the flattening,
+ * because they are what keeps a consumer from wrongly narrowing scope:
+ * a config with no app info reports *every* canonical layer as shared, and a
+ * layer no app consumes appears in `consumers` with an empty array rather than
+ * being left out. Absent and "none" must not look alike here.
+ */
+interface SerializedLayerGraph {
+  /** Alias-free layer names, in `config.localeDirs` order. */
+  canonical: string[];
+  /** Canonical layers consumed by more than one app — where shared keys belong. */
+  shared: string[];
+  /** Alias layer name → the canonical layer whose locale dir it points at. */
+  aliases: Record<string, string>;
+  /** Canonical layer name → the apps consuming it. Every canonical layer is a key. */
+  consumers: Record<string, string[]>;
+}
+/** Flatten {@link buildLayerGraph}'s view of `config` into plain JSON. */
+declare function serializeLayerGraph(config: I18nConfig): SerializedLayerGraph;
+//# sourceMappingURL=layer-graph.d.ts.map
+//#endregion
+//#region src/core/types.d.ts
+/**
+ * The whole resolved project in one answer: the config, the locale dirs behind
+ * it, the topology those dirs form, and which locales are maintained by hand.
+ *
+ * A superset of `I18nConfig` rather than a wrapper around it, because every
+ * caller of the old three-call sequence merged the parts anyway and a nested
+ * `config` key would break each of them for nothing.
+ */
+interface DescribeProjectResult extends I18nConfig {
+  /**
+   * Canonical codes of the locales the translate operations leave alone. The
+   * raw refs stay visible under `projectConfig.protectedLocales`.
+   */
+  protectedLocales: string[];
+  /** One entry per locale directory, with file counts and key namespaces. */
+  layers: LocaleDirInfo[];
+  /**
+   * Which layers are shared, which apps consume which layer, and what each
+   * alias points at — the topology behind the flat `layers` list, and what
+   * answers where a new key belongs.
+   */
+  layerGraph: SerializedLayerGraph;
+}
 interface LocaleDirInfo {
   layer: string;
   path: string;
@@ -62,27 +182,6 @@ interface MutationResult {
   /** Present only when a ref matched several locales and precedence picked one. */
   ambiguousLocales?: LocaleRefAmbiguity[];
 }
-interface AddTranslationsResult {
-  /** Present when dryRun=true */
-  dryRun?: boolean;
-  wouldAdd?: MutationPreview[];
-  /** Present when dryRun=false */
-  added?: string[];
-  skipped: string[];
-  filesWritten?: number;
-  warnings?: string[];
-  /** Present only when a locale ref resolved to nothing — see UnresolvedLocaleRef. */
-  unresolvedLocales?: UnresolvedLocaleRef[];
-  /** Present only when a locale ref matched several locales. */
-  ambiguousLocales?: LocaleRefAmbiguity[];
-  placeholderValidation?: PlaceholderValidationResult;
-  summary?: {
-    keysToAdd: number;
-    keysSkipped: number;
-    message: string;
-  };
-  skippedKeys?: string[];
-}
 interface WriteTranslationsResult {
   /** Present when dryRun=true */
   dryRun?: boolean;
@@ -104,26 +203,6 @@ interface WriteTranslationsResult {
   };
   skippedKeys?: string[];
 }
-interface UpdateTranslationsResult {
-  /** Present when dryRun=true */
-  dryRun?: boolean;
-  wouldUpdate?: MutationPreview[];
-  /** Present when dryRun=false */
-  updated?: string[];
-  skipped: string[];
-  filesWritten?: number;
-  /** Present only when a locale ref resolved to nothing — see UnresolvedLocaleRef. */
-  unresolvedLocales?: UnresolvedLocaleRef[];
-  /** Present only when a locale ref matched several locales. */
-  ambiguousLocales?: LocaleRefAmbiguity[];
-  placeholderValidation?: PlaceholderValidationResult;
-  summary?: {
-    keysToUpdate: number;
-    keysSkipped: number;
-    message: string;
-  };
-  skippedKeys?: string[];
-}
 /**
  * The config `init` emits. Only fields the matched adapter cannot derive:
  * writing a copy of what the framework already states creates a second source
@@ -173,16 +252,13 @@ interface InitProjectConfigResult {
   overwritten: boolean;
 }
 interface MissingTranslationsResult {
-  /** Absent when the full report went to `reportFile` instead. */
-  missing?: Record<string, Record<string, string[]>>;
+  missing: Record<string, Record<string, string[]>>;
   summary: {
     referenceLocale: string | LocaleRefInfo;
     targetLocales: Array<string | LocaleRefInfo>;
     layersScanned: string[];
     totalMissingKeys: number;
   };
-  /** Present when reportOutput is configured */
-  reportFile?: string;
 }
 interface LocaleStatus extends LocaleRefInfo {
   total: number;
@@ -203,10 +279,21 @@ interface LayerStatus {
   missing: number;
   empty: number;
   completion: number;
+  /**
+   * Apps whose declared layers include this one. Empty means either no app
+   * information exists (hand-built configs) or nothing consumes the layer.
+   */
+  consumedBy: string[];
 }
 interface TranslationStatusSummary {
   referenceLocale: LocaleRefInfo;
   layersScanned: string[];
+  /**
+   * Scanned layers no app consumes — keys nothing can render. Stays empty
+   * unless the project declares more than one app, since a single-app project
+   * has no consumption edges worth reporting on.
+   */
+  unconsumedLayers: string[];
   localesChecked: number;
   protectedLocales: string[];
   totalKeys: number;
@@ -217,31 +304,76 @@ interface TranslationStatusSummary {
   completionPercent: number;
 }
 interface TranslationStatusResult {
-  locales?: LocaleStatus[];
-  layers?: LayerStatus[];
+  locales: LocaleStatus[];
+  layers: LayerStatus[];
+  /**
+   * Locale → layer → the keys `summary.emptyKeys` counts: empty in that target
+   * locale while the reference locale has a value. Present only when the caller
+   * asked to list them. Added to the result rather than replacing it, so asking
+   * which keys are empty still answers the coverage question that prompted it.
+   */
+  empty?: Record<string, Record<string, string[]>>;
+  /**
+   * Layer → keys whose value is empty in the reference locale itself. Nothing
+   * to translate from, so excluded from every count; listed so a deliberate
+   * blank and a forgotten one can be told apart. Present only with `empty`,
+   * and only when there are any.
+   */
+  emptyInReference?: Record<string, string[]>;
   summary: TranslationStatusSummary;
-  /** Present when the full breakdown went to a file instead. */
-  reportFile?: string;
 }
 interface EmptyTranslationsResult {
-  /** Absent when the full report went to `reportFile` instead. */
-  emptyKeys?: Record<string, Record<string, string[]>>;
+  emptyKeys: Record<string, Record<string, string[]>>;
   summary: {
     totalEmpty: number;
     localesChecked: string[];
     layersChecked: string[];
   };
-  /** Present when reportOutput is configured */
-  reportFile?: string;
 }
+/**
+ * One key in one locale of one layer — the detail rows, returned when the
+ * caller asks for them.
+ */
 interface SearchMatch {
   layer: string;
   locale: string;
   key: string;
   value: unknown;
 }
+/**
+ * One key, however many layers and locales define it — the row a search
+ * returns by default.
+ *
+ * A key that exists in seven layers and thirty locales used to come back as
+ * dozens of near-identical rows, which an agent pays for and then has to group
+ * itself before it can answer the question it asked: does a translation for
+ * this text already exist, and where. Grouped here instead, because `layers`
+ * is the answer to the second half — one layer means reuse it, several mean
+ * the key is already duplicated.
+ */
+interface SearchKeyMatch {
+  key: string;
+  /** Every searched layer that defines the key, in layer order. */
+  layers: string[];
+  /** What `locale` holds for the key. */
+  value: unknown;
+  /**
+   * Which locale `value` was read from: the reference locale where it defines
+   * the key, otherwise the first searched locale that does.
+   */
+  locale: string;
+  /** How many of the searched locales define the key. */
+  localeCount: number;
+}
+/** How `query` is compared against a key path or a value. */
+type SearchMatchMode = 'contains' | 'exact' | 'fuzzy';
 interface SearchTranslationsResult {
-  matches: SearchMatch[];
+  /**
+   * One row per key by default; one row per key and locale when the caller
+   * passed `includeLocales`.
+   */
+  matches: SearchKeyMatch[] | SearchMatch[];
+  /** How many rows `matches` holds, whichever shape it is in. */
   totalMatches: number;
 }
 interface RemoveTranslationsPreview {
@@ -297,6 +429,12 @@ interface MoveTranslationKeyPlanEntry {
    */
   action: 'move' | 'deduplicate';
 }
+/**
+ * What a move returns: a rename result when the key stayed in its layer, a move
+ * result when it changed layers. A union rather than one merged shape, so
+ * neither half carries fields that can never be set for the other.
+ */
+type MoveTranslationKeyOutcome = MoveTranslationKeyResult | RenameTranslationKeyResult;
 interface MoveTranslationKeyResult {
   /** Present when dryRun=true */
   dryRun?: boolean;
@@ -326,6 +464,29 @@ type TranslateMode = 'provider' | 'agent' | 'dry-run';
 type TranslateFailReason = 'provider-error' | 'omitted-by-model' | 'placeholder-mismatch' | 'plural-mismatch' | 'write-error' | 'truncated';
 /** Why a key or locale was intentionally not attempted. */
 type TranslateSkipReason = 'no-provider' | 'already-translated' | 'protected-locale';
+/** What translate_missing accepts. `layer` omitted means every layer at once. */
+interface TranslateMissingOptions {
+  layer?: string;
+  referenceLocale?: string;
+  targetLocales?: string[];
+  locales?: string[];
+  keys?: string[];
+  batchSize?: number;
+  dryRun?: boolean;
+  compact?: boolean;
+  projectDir?: string;
+  /**
+   * Also re-translate keys whose target was written from source text that has
+   * changed since (translation memory only). Off by default: without it the
+   * operation still never touches an existing value, it only reports the stale
+   * ones in `stale`.
+   */
+  overwriteStale?: boolean;
+  translateFn?: TranslateFn;
+  progressFn?: ProgressFn;
+  /** Called once after the pre-scan with the computed total number of progress steps. */
+  onProgressTotal?: (total: number) => void;
+}
 interface TranslateMissingLocaleResult {
   mode: TranslateMode;
   /** Number of missing keys found for this locale. Always equals
@@ -342,6 +503,14 @@ interface TranslateMissingLocaleResult {
     key: string;
     reason: TranslateSkipReason;
   }>;
+  /**
+   * Translation-memory only: keys whose target value was written from source
+   * text that has changed since, and which this run left untouched. A bucket of
+   * its own, not part of `missing` — these keys are translated, just outdated —
+   * so the invariant above still holds. Re-translating them needs
+   * `overwriteStale`, which counts them into `missing` instead.
+   */
+  stale?: string[];
   batches?: number;
   model?: string;
   writeError?: string;
@@ -356,6 +525,7 @@ interface TranslateMissingCompactEntry {
   failed: number;
   skipped: number;
   wouldTranslate?: number;
+  stale?: number;
   batches?: number;
   model?: string;
   writeError?: string;
@@ -372,6 +542,8 @@ interface TranslateMissingResult {
     totalFailed: number;
     totalSkipped: number;
     totalWouldTranslate?: number;
+    /** Translation-memory only: stale keys left untouched, across all locales. */
+    staleCount?: number;
     layer: string;
     referenceLocale: string | LocaleRefInfo;
     targetLocales: Array<string | LocaleRefInfo>;
@@ -393,6 +565,8 @@ interface TranslateAllLayersSummary {
   totalFailed: number;
   totalSkipped: number;
   totalWouldTranslate?: number;
+  /** Translation-memory only: stale keys left untouched, across all layers and locales. */
+  staleCount?: number;
   /** Layer names that were translated. */
   layers: string[];
   byLayer: TranslateLayerTotals[];
@@ -425,6 +599,18 @@ interface TranslateKeyLocaleIssue {
   reason: TranslateFailReason | 'read-error';
   detail?: string;
 }
+/**
+ * One locale translate_key deliberately left alone. `reason` is a closed set;
+ * `stale` refines 'already-translated' rather than extending it, so a caller
+ * can tell an existing translation that still matches its source from one the
+ * source has since outgrown.
+ */
+interface TranslateKeySkip {
+  locale: string;
+  reason: TranslateSkipReason;
+  /** Translation-memory only: whether the existing value is out of date. */
+  stale?: boolean;
+}
 interface TranslateKeyResult {
   key: string;
   sourceLocale: LocaleRefInfo;
@@ -433,10 +619,7 @@ interface TranslateKeyResult {
   translated: string[];
   /** Dry-run only: locales that would be translated. */
   wouldTranslate?: string[];
-  skipped: Array<{
-    locale: string;
-    reason: TranslateSkipReason;
-  }>;
+  skipped: TranslateKeySkip[];
   failed: TranslateKeyLocaleIssue[];
   filesWritten: number;
   dryRun: boolean;
@@ -468,9 +651,22 @@ interface UnresolvedKeyWarningRef {
   callee: string;
   suggestedIgnorePattern?: string;
 }
+/**
+ * One `declaredNamespaces` entry with the keys it answers for.
+ *
+ * `matchedKeys` is what makes a declaration auditable in both directions: the
+ * keys a reader would otherwise see in the orphan list, and — when it is empty
+ * — a declaration whose namespace no longer exists.
+ */
+interface DeclaredNamespaceRef {
+  pattern: string;
+  /** What keeps these keys alive, as declared in the config. */
+  reason: string;
+  /** Keys of the checked layers this pattern covers. Empty means the declaration is stale. */
+  matchedKeys: string[];
+}
 interface FindOrphanKeysResult {
-  /** Absent when the full report went to `reportFile` instead. */
-  orphanKeys?: Record<string, string[]>;
+  orphanKeys: Record<string, string[]>;
   uncertainKeys?: Record<string, string[]>;
   /**
    * Keys kept alive solely by the bare-candidate net — nothing a frontend
@@ -483,6 +679,9 @@ interface FindOrphanKeysResult {
   /** Keys used only from apps that do not consume the owning layer. */
   misplacedUsages?: MisplacedUsageRef[];
   misplacedUsageNote?: string;
+  /** Every declared namespace with the keys it covers. Present when any is declared. */
+  declaredNamespaces?: DeclaredNamespaceRef[];
+  declaredNamespaceNote?: string;
   summary: {
     totalKeys: number;
     orphanCount: number;
@@ -491,6 +690,8 @@ interface FindOrphanKeysResult {
     misplacedCount?: number;
     dynamicMatchedCount?: number;
     ignoredCount?: number;
+    /** Keys withheld from the orphan list by a declared namespace. */
+    declaredCount?: number;
     usedCount?: number;
     filesScanned: number;
     /** Files a syntax frontend declined; pattern matching read them instead. */
@@ -504,13 +705,10 @@ interface FindOrphanKeysResult {
   dynamicKeyWarning?: string;
   dynamicKeys?: DynamicKeyRef[];
   unresolvedKeyWarnings?: UnresolvedKeyWarningRef[];
-  /** Present when reportOutput is configured */
-  reportFile?: string;
 }
 /** Where each requested key is referenced in source. */
 interface CodeUsageResult {
-  /** Absent when the full report went to `reportFile` instead. */
-  usages?: Record<string, CodeUsageRef[]>;
+  usages: Record<string, CodeUsageRef[]>;
   /** Requested keys with no reference anywhere in the scanned source. */
   notFoundInCode?: string[];
   /** Dynamic expressions that could reach the requested keys. */
@@ -524,8 +722,6 @@ interface CodeUsageResult {
     dirsScanned?: string[];
     message?: string;
   };
-  /** Present when the full report went to a file instead. */
-  reportFile?: string;
 }
 interface CodeUsageRef {
   file: string;
@@ -544,8 +740,6 @@ interface ScanCodeUsageResult {
   };
   notFoundInCode?: string[];
   dynamicKeys?: DynamicKeyRef[];
-  /** Present when reportOutput is configured */
-  reportFile?: string;
 }
 interface RemoveOrphanKeysResult {
   orphanKeys?: Record<string, string[]>;
@@ -553,6 +747,9 @@ interface RemoveOrphanKeysResult {
   uncertainKeys?: Record<string, string[]>;
   misplacedUsages?: MisplacedUsageRef[];
   misplacedUsageNote?: string;
+  /** Every declared namespace with the keys it covers — the keys this run will not delete. */
+  declaredNamespaces?: DeclaredNamespaceRef[];
+  declaredNamespaceNote?: string;
   summary: {
     dryRun?: boolean;
     totalKeys: number;
@@ -562,6 +759,8 @@ interface RemoveOrphanKeysResult {
     misplacedCount?: number;
     dynamicMatchedCount?: number;
     ignoredCount?: number;
+    /** Keys withheld from the orphan list by a declared namespace. */
+    declaredCount?: number;
     usedCount?: number;
     remainingCount?: number;
     filesScanned?: number;
@@ -575,8 +774,6 @@ interface RemoveOrphanKeysResult {
   dynamicKeyWarning?: string;
   dynamicKeys?: DynamicKeyRef[];
   unresolvedKeyWarnings?: UnresolvedKeyWarningRef[];
-  /** Present when reportOutput is configured */
-  reportFile?: string;
 }
 interface ScaffoldLocaleFileInfo {
   locale: string;
@@ -625,7 +822,7 @@ declare function findLocaleImpl(config: I18nConfig, localeRef: string): LocaleDe
  * project default. Throws LOCALE_NOT_FOUND listing the available codes.
  */
 //#endregion
-//#region src/core/ops-translate.d.ts
+//#region src/core/translate/targets.d.ts
 /**
  * Resolve the config's `protectedLocales` entries (any locale ref: code,
  * language tag, or file name) against the known locales. Entries that do not
@@ -633,6 +830,15 @@ declare function findLocaleImpl(config: I18nConfig, localeRef: string): LocaleDe
  * definitions, deduplicated by canonical code.
  */
 declare function resolveProtectedLocales(config: I18nConfig): LocaleDefinition[];
+/**
+ * Resolve translate_missing target locales. Protected locales are excluded
+ * from the DEFAULT target set (returned separately so the caller can report
+ * them as skipped); naming one explicitly in targetLocales overrides the
+ * protection with a warning.
+ */
+
+//#endregion
+//#region src/core/translate/run.d.ts
 /**
  * Find keys missing in target locales and translate them.
  *
@@ -642,21 +848,7 @@ declare function resolveProtectedLocales(config: I18nConfig): LocaleDefinition[]
  * When `layer` is omitted, every canonical locale-backed layer is translated
  * in one run and the results are aggregated (see translateMissingAllLayers).
  */
-declare function translateMissing(opts: {
-  layer?: string;
-  referenceLocale?: string;
-  targetLocales?: string[];
-  locales?: string[];
-  keys?: string[];
-  batchSize?: number;
-  dryRun?: boolean;
-  compact?: boolean;
-  projectDir?: string;
-  translateFn?: TranslateFn;
-  progressFn?: ProgressFn;
-  /** Called once after the pre-scan with the computed total number of progress steps. */
-  onProgressTotal?: (total: number) => void;
-}): Promise<TranslateMissingOutcome>;
+declare function translateMissing(opts: TranslateMissingOptions): Promise<TranslateMissingOutcome>;
 /**
  * Translate one key from a source locale into target locales. Unlike
  * translate_missing, this can overwrite stale existing target values.
@@ -673,9 +865,23 @@ declare function translateKey(opts: {
   projectDir?: string;
   translateFn?: TranslateFn;
 }): Promise<TranslateKeyResult>;
-//# sourceMappingURL=ops-translate.d.ts.map
+//# sourceMappingURL=run.d.ts.map
 //#endregion
 //#region src/core/ops-read.d.ts
+/**
+ * Everything a caller needs to know about a project before touching it:
+ * resolved config, locale directories, the layer topology, and which locales
+ * are hand-maintained.
+ *
+ * This composition used to live in the MCP `discover` handler, so the terminal
+ * had no way to ask the question its own docs told people to ask — and the two
+ * surfaces would have had to be kept in step by hand once one of them grew a
+ * field. Callers add whatever is theirs alone (the MCP server adds the
+ * translation backend it resolved at startup); the project half is here.
+ */
+declare function describeProject(opts?: {
+  projectDir?: string;
+}): Promise<DescribeProjectResult>;
 /**
  * Detect the i18n configuration from the project, always bypassing the
  * config cache (clears it first).
@@ -704,7 +910,6 @@ declare function getMissingTranslations(opts: {
   targetLocales?: string[];
   locales?: string[];
   projectDir?: string;
-  outputFile?: string;
 }): Promise<MissingTranslationsResult>;
 /**
  * Find translation keys that have empty string values in locale files.
@@ -713,27 +918,30 @@ declare function findEmptyTranslations(opts: {
   layer?: string;
   locale?: string;
   projectDir?: string;
-  outputFile?: string;
 }): Promise<EmptyTranslationsResult>;
 /**
- * Search translation files by key pattern or value substring.
+ * The scan behind {@link findEmptyTranslations}, against a config the caller
+ * already has.
+ *
+ * Separate so `getTranslationStatus` can embed the listing under its own
+ * `--list-empty` flag without detecting the project a second time.
+ */
+
+/**
+ * Search translation files by key path or value.
+ *
+ * Returns one row per key. The detail rows — one per key and locale — are what
+ * `includeLocales` asks for.
  */
 declare function searchTranslations(opts: {
   query: string;
   searchIn?: 'keys' | 'values' | 'both';
+  matchMode?: SearchMatchMode;
+  includeLocales?: boolean;
   layer?: string;
   locale?: string;
   projectDir?: string;
-  outputFile?: string;
-}): Promise<{
-  matches: SearchMatch[];
-  totalMatches: number;
-} | {
-  reportFile: string;
-  summary: {
-    totalMatches: number;
-  };
-}>;
+}): Promise<SearchTranslationsResult>;
 interface NamespaceNode {
   keyCount: number;
   children?: Record<string, NamespaceNode>;
@@ -770,28 +978,6 @@ declare function writeTranslations(opts: {
   dryRun?: boolean;
   projectDir?: string;
 }): Promise<WriteTranslationsResult>;
-/**
- * Add new translation keys to the specified layer.
- *
- * @deprecated Use writeTranslations with mode: 'add' instead.
- */
-declare function addTranslations(opts: {
-  layer: string;
-  translations: Record<string, Record<string, string>>;
-  dryRun?: boolean;
-  projectDir?: string;
-}): Promise<AddTranslationsResult>;
-/**
- * Update existing translation keys in the specified layer.
- *
- * @deprecated Use writeTranslations with mode: 'update' instead.
- */
-declare function updateTranslations(opts: {
-  layer: string;
-  translations: Record<string, Record<string, string>>;
-  dryRun?: boolean;
-  projectDir?: string;
-}): Promise<UpdateTranslationsResult>;
 /**
  * Remove one or more translation keys from ALL locale files in the specified layer.
  */
@@ -802,7 +988,12 @@ declare function removeTranslations(opts: {
   projectDir?: string;
 }): Promise<RemoveTranslationsResult>;
 /**
- * Rename/move a translation key across ALL locale files in a layer.
+ * Rename a translation key across ALL locale files in one layer.
+ *
+ * Reachable on both surfaces through {@link moveTranslationKey}, which routes a
+ * same-layer request here. Kept exported because renaming within a layer is a
+ * complete operation on its own, and a programmatic caller that means exactly
+ * that should not have to express it as a move to nowhere.
  */
 declare function renameTranslationKey(opts: {
   layer: string;
@@ -821,7 +1012,13 @@ declare function scaffoldLocaleFiles(opts: {
   projectDir?: string;
 }): Promise<ScaffoldLocaleResult>;
 /**
- * Move a key from one layer to another, carrying every locale that defines it.
+ * Move a key: to another layer, to another key path, or both.
+ *
+ * One entry point rather than two, because the caller's intent is "this key
+ * belongs somewhere else" and whether that somewhere else is a different layer
+ * is a detail of the project's shape, not a different operation. Omitting
+ * `toLayer` (or naming the layer the key already lives in) is a rename within
+ * the layer and routes to {@link renameTranslationKey}.
  *
  * Promoting an app-layer key to the shared layer once a second app needs it is
  * a first-class operation in a layered monorepo, and composing it out of
@@ -842,13 +1039,15 @@ declare function scaffoldLocaleFiles(opts: {
  * silently.
  */
 declare function moveTranslationKey(opts: {
-  fromLayer: string;
-  toLayer: string;
+  /** Layer the key lives in today. */
+  layer: string;
   key: string;
+  /** Layer to move it to. Omitted, or equal to `layer`, means a rename in place. */
+  toLayer?: string;
   newKey?: string;
   dryRun?: boolean;
   projectDir?: string;
-}): Promise<MoveTranslationKeyResult>;
+}): Promise<MoveTranslationKeyOutcome>;
 //# sourceMappingURL=ops-write.d.ts.map
 //#endregion
 //#region src/core/ops-status.d.ts
@@ -863,8 +1062,13 @@ declare function moveTranslationKey(opts: {
 declare function getTranslationStatus(opts: {
   layer?: string;
   referenceLocale?: string;
+  /**
+   * Also list the keys behind `summary.emptyKeys`, under `empty`. Off by
+   * default: the count is what a health check reads, and the list grows with
+   * the project.
+   */
+  listEmpty?: boolean;
   projectDir?: string;
-  outputFile?: string;
 }): Promise<TranslationStatusResult>;
 //# sourceMappingURL=ops-status.d.ts.map
 //#endregion
@@ -909,13 +1113,9 @@ type CallArgument = /** A literal: `t('common.save')`. */
   kind: 'unknown';
 };
 /** Everything one file yields. Unchanged from what the scanner already consumes. */
-interface FileEvidence {
-  usages: KeyUsage[];
-  dynamicKeys: DynamicKeyUsage[];
-  bareStringCandidates: Set<string>;
-}
+
 interface LanguageFrontend {
-  /** For diagnostics and for the differential harness. */
+  /** Names the frontend in diagnostics, so a decline says which one declined. */
   readonly name: string;
   /** Whether this frontend reads that file. */
   handles(filePath: string): boolean;
@@ -950,17 +1150,13 @@ interface ScanPatternSet {
    * producing `${_}.header`-class candidates that suppress every key ending
    * in those segments. Language-neutral shapes (dotted literals,
    * trailing-dot prefixes) always run.
+   *
+   * Two-valued only because the two supported languages need two shape sets.
+   * A third frontend makes this a language identifier rather than a family
+   * flag — widen it then, and key it on the language the scanner is reading.
    */
   bareShapes?: 'js' | 'php';
 }
-declare const VUE_NUXT_PATTERNS: ScanPatternSet;
-/**
- * Maps locale file format to the appropriate scan pattern set.
- * 'php-array' → Laravel (PHP translation helpers in Blade/PHP files).
- * 'json' / undefined → Vue/Nuxt ($t / t calls in Vue/TS/JS files).
- */
-declare function getPatternSet(format?: LocaleFileFormat): ScanPatternSet;
-//# sourceMappingURL=patterns.d.ts.map
 //#endregion
 //#region src/scanner/code-scanner.d.ts
 interface KeyUsage {
@@ -1005,7 +1201,18 @@ interface ScanResult {
  * frontend reports call sites, the rules decide what they mean.
  */
 
-declare function scanSourceFiles(rootDir: string, excludeDirs?: string[], patterns?: ScanPatternSet, frontends?: LanguageFrontend[]): Promise<ScanResult>;
+/** What a caller can hand a scan beyond its inputs. */
+interface ScanSourceFilesHooks {
+  /** Files to read, relative to `rootDir` — a {@link globSourceFiles} result, reused instead of walking the tree twice. */
+  files?: string[];
+  /**
+   * Called once per file, right after it was read. `done` counts completions,
+   * so it fires in completion order while the scan result itself stays in
+   * input order — a counter is all that depends on the timing.
+   */
+  onFile?: (done: number, total: number, file: string) => void;
+}
+declare function scanSourceFiles(rootDir: string, excludeDirs?: string[], patterns?: ScanPatternSet, frontends?: LanguageFrontend[], hooks?: ScanSourceFilesHooks): Promise<ScanResult>;
 //#endregion
 //#region src/core/ops-orphans.d.ts
 /**
@@ -1024,7 +1231,10 @@ declare function findOrphanKeys(opts: {
   scanDirs?: string[];
   excludeDirs?: string[];
   projectDir?: string;
-  outputFile?: string;
+  /** Scanning every source file of every app takes seconds — a caller that asked for progress hears about each stride of files. */
+  progressFn?: ProgressFn;
+  /** Called once with the number of progress steps, before the first `progressFn` call. */
+  onProgressTotal?: (total: number) => void;
 }): Promise<FindOrphanKeysResult>;
 /**
  * Scan Vue/TS source files to find where translation keys are referenced.
@@ -1034,7 +1244,6 @@ declare function scanCodeUsage(opts: {
   scanDirs?: string[];
   excludeDirs?: string[];
   projectDir?: string;
-  outputFile?: string;
 }): Promise<CodeUsageResult>;
 /**
  * Find translation keys not referenced in source code and remove them.
@@ -1047,9 +1256,10 @@ declare function removeOrphanKeys(opts: {
   excludeDirs?: string[];
   dryRun?: boolean;
   projectDir?: string;
-  outputFile?: string;
-  /** Also write the orphan findings as a GitLab Code Quality JSON array to this path. */
-  codequalityOutput?: string;
+  /** Same scan as {@link findOrphanKeys}, same reporting. */
+  progressFn?: ProgressFn;
+  /** Called once with the number of progress steps, before the first `progressFn` call. */
+  onProgressTotal?: (total: number) => void;
 }): Promise<RemoveOrphanKeysResult>;
 //# sourceMappingURL=ops-orphans.d.ts.map
 //#endregion
@@ -1114,7 +1324,6 @@ interface FindDuplicateKeysResult {
 declare function findDuplicateKeys(opts?: {
   locale?: string;
   projectDir?: string;
-  outputFile?: string;
   /**
    * Also group keys by the value they carry. Off by default: it reads every
    * canonical layer rather than only the paired ones, and the existing result
@@ -1123,10 +1332,7 @@ declare function findDuplicateKeys(opts?: {
   byValue?: boolean;
   /** Shortest value worth grouping. Below it, repetition is usually legitimate. */
   minValueLength?: number;
-}): Promise<FindDuplicateKeysResult | {
-  reportFile: string;
-  summary: FindDuplicateKeysSummary;
-}>;
+}): Promise<FindDuplicateKeysResult>;
 //# sourceMappingURL=ops-duplicates.d.ts.map
 //#endregion
 //#region src/core/ops-check.d.ts
@@ -1155,13 +1361,31 @@ interface UncertainKeyFinding extends UndefinedKeyFinding {
   /** Why this is not a hard finding. */
   reason: string;
 }
+/** The locale file `write` extracted the undefined keys into. */
+interface ExtractedUndefinedKeys {
+  layer: string;
+  /** The project's default locale — the source every other locale is filled from. */
+  locale: string;
+  /** The keys that reached the file, in alphabetical order. */
+  keys: string[];
+}
 interface CheckUndefinedKeysSummary {
   /** Distinct statically referenced keys across all scan units. */
   usedKeysChecked: number;
+  /**
+   * Keys that render raw at runtime, which is what the gate reads. After a
+   * `write` run this counts the ones still undefined: an extracted key now has
+   * a definition — an empty one — so it resolves, and `status` reports it as an
+   * empty translation instead.
+   */
   undefinedCount: number;
+  /** Keys extracted into a locale file. Present only alongside `written`. */
+  writtenCount?: number;
   uncertainCount: number;
   /** Unresolvable keys excluded by orphanScan ignorePatterns. */
   ignoredCount: number;
+  /** Unresolvable keys covered by a declaredNamespaces entry — defined by contract, never written. */
+  declaredCount: number;
   filesScanned: number;
   /** Files a syntax frontend declined; pattern matching read them instead. */
   filesDeclined: number;
@@ -1171,9 +1395,19 @@ interface CheckUndefinedKeysSummary {
   message: string;
 }
 interface CheckUndefinedKeysResult {
+  /**
+   * The findings as the scan made them. A `write` run leaves them in place —
+   * what was extracted is named in `written`, and the summary counts what is
+   * left — because the call sites are what a reader has to visit either way.
+   */
   undefinedKeys: UndefinedKeyFinding[];
   uncertainKeys: UncertainKeyFinding[];
   limitation: string;
+  /**
+   * Present only when `write` was asked for and the scan found something to
+   * write. A clean scan reports nothing here, having written nothing.
+   */
+  written?: ExtractedUndefinedKeys;
   summary: CheckUndefinedKeysSummary;
 }
 /**
@@ -1186,6 +1420,9 @@ interface CheckUndefinedKeysResult {
  * scopeByLayer — a unit resolves exactly the layers it vouches for). The
  * graph's degenerate semantics carry over: with no app info every layer is
  * resolvable everywhere, so only keys defined in NO layer are flagged.
+ *
+ * With `write`, the findings are also extracted into a locale file as empty
+ * translations, which is what turns a report into the first half of the fix.
  */
 declare function checkUndefinedKeys(opts?: {
   locale?: string;
@@ -1195,128 +1432,368 @@ declare function checkUndefinedKeys(opts?: {
    */
   scanDirs?: string[];
   excludeDirs?: string[];
+  /** Extract the undefined keys into a locale file. See extractUndefinedKeys. */
+  write?: boolean;
+  /** The layer to extract into, where the findings alone do not decide. */
+  layer?: string;
   projectDir?: string;
-  outputFile?: string;
-  /** Also write the findings as a GitLab Code Quality JSON array to this path. */
-  codequalityOutput?: string;
-}): Promise<CheckUndefinedKeysResult | {
-  reportFile: string;
-  summary: CheckUndefinedKeysSummary;
-}>;
+}): Promise<CheckUndefinedKeysResult>;
 //# sourceMappingURL=ops-check.d.ts.map
 //#endregion
-//#region src/config/detector.d.ts
-declare function detectI18nConfig(projectDir: string): Promise<I18nConfig>;
-declare function clearConfigCache(): void;
-declare function getCachedConfig(): I18nConfig | null;
-//# sourceMappingURL=detector.d.ts.map
-
+//#region src/core/codequality.d.ts
+interface CodeQualityIssue {
+  description: string;
+  check_name: string;
+  fingerprint: string;
+  severity: 'info' | 'minor' | 'major' | 'critical' | 'blocker';
+  location: {
+    path: string;
+    lines: {
+      begin: number;
+    };
+  };
+}
+/**
+ * `check` findings → one issue per usage location. Uncertain findings are
+ * not mapped: the widget has no "maybe" state, and a hard-looking finding
+ * for an unverifiable key would train consumers to ignore the report.
+ */
 //#endregion
-//#region src/config/layer-graph.d.ts
+//#region src/surface/types.d.ts
+/** Which surface is invoking an operation. They differ only in the prose they own. */
+type Surface = 'cli' | 'mcp';
 /**
- * Queryable view over the layer topology a resolved {@link I18nConfig}
- * already carries: which locale dirs are canonical (alias-free), which
- * layer owns an aliased dir, and which apps consume which layers.
+ * What a parameter carries.
  *
- * This is a pure derivation — no filesystem access, no config-shape
- * changes. Cross-layer tooling (duplicate detection, scope-aware orphan
- * scanning) builds on these queries instead of name-matching heuristics.
+ * `string[]` is a list on both surfaces: MCP passes a JSON array, the CLI a
+ * comma-separated string it splits. `record` is the one nested shape on the
+ * surface — the key → locale → value map `write` takes — so the builders state
+ * its inner levels once instead of every spec carrying a schema.
+ */
+type ParamType = 'string' | 'boolean' | 'number' | 'string[]' | 'record';
+/** The value shape of a `record` parameter: dot-path key → locale ref → string. */
+type TranslationsRecord = Record<string, Record<string, string>>;
+interface CliParamOptions {
+  /**
+   * Additional spellings citty accepts for this flag. Single characters render
+   * as `-d`; longer ones are the flag's previous name, kept working after the
+   * descriptor took the name the MCP tool used.
+   */
+  alias?: string | readonly string[];
+  /** Not exposed as a flag. Every use of this states why in a comment. */
+  hidden?: boolean;
+}
+interface McpParamOptions {
+  /** Not part of the tool's input schema. Every use of this states why in a comment. */
+  hidden?: boolean;
+}
+/** One parameter of an operation, as both surfaces expose it. */
+interface ParamSpec {
+  type: ParamType;
+  /**
+   * The one description. It reaches `--help`, the generated CLI page and the
+   * JSON Schema an MCP host hands its model, so it is written for a reader who
+   * knows neither surface: no `--flag` spellings, no "this tool".
+   */
+  description: string;
+  required?: boolean;
+  /**
+   * Applied by the CLI so `--help` can state it. Deliberately not put into the
+   * JSON Schema: the operations already apply their own defaults, and a schema
+   * default would make a host send a value the caller never chose.
+   */
+  default?: unknown;
+  /** The accepted values. The CLI validates against them and MCP emits an enum. */
+  enum?: readonly string[];
+  /** Numbers only: reject a fractional value. */
+  integer?: boolean;
+  /** Numbers only: reject anything below this. */
+  min?: number;
+  /** `string[]` parameters that also accept the literal "all". */
+  allowAll?: boolean;
+  cli?: CliParamOptions;
+  mcp?: McpParamOptions;
+}
+type Params = Record<string, ParamSpec>;
+/**
+ * A CI gate a command evaluates. `counter` is the field of `result.summary`
+ * carrying the observed value.
  *
- * ## Degenerate-case semantics
+ * The two shapes are a union rather than one type with optional halves so the
+ * invariants hold at compile time: a flagged gate always has a flag to read
+ * its name and threshold from, and a flagless one always carries both itself.
+ * Stated as options, `{ counter, threshold }` type-checks and then has no name
+ * to report the gate under.
+ */
+type GateSpec = FlaggedGateSpec | AlwaysOnGateSpec;
+interface GateSpecBase {
+  counter: string;
+  /** 'above' trips when observed > threshold (default); 'below' when observed < threshold. */
+  direction?: 'above' | 'below';
+}
+/**
+ * Requested by a flag, and evaluated only when that flag is passed. Omitting
+ * `threshold` takes it from the flag's own value, so a boolean flag pairs with
+ * `threshold: 0` and a numeric one (`--failUnder 90`) omits it.
+ */
+interface FlaggedGateSpec extends GateSpecBase {
+  flag: string;
+  name?: never;
+  threshold?: number;
+}
+/**
+ * Always evaluated, for findings that are a defect rather than a threshold — a
+ * key that renders raw in production is not something you opt into caring
+ * about. It still reports as a gate: the run succeeded, and what it found is
+ * what you are being told about.
+ */
+interface AlwaysOnGateSpec extends GateSpecBase {
+  flag?: never;
+  name: string;
+  threshold: number;
+}
+/**
+ * What the surface hands a report builder beyond the result: the project the
+ * operation ran against and the arguments it ran with.
+ */
+interface ReportContext<A = Record<string, unknown>> {
+  projectDir: string;
+  /** The project's resolved i18n configuration, as the operation itself read it. */
+  config: I18nConfig;
+  /** The operation's arguments, as the surface resolved them. */
+  args: A;
+}
+/**
+ * How a result too large to hand back is diverted to a file.
  *
- * These are load-bearing for consumers (scope-aware scanning must never
- * wrongly narrow its scan scope):
+ * An operation always returns its whole result. Whether that result is written
+ * to disk and replaced by a compact stand-in is the surface's decision — it is
+ * the surface that owns `outputFile`, the configured report directory and the
+ * name the file is written under — so the operations know nothing about any of
+ * it, and a descriptor declaring this is what gives an operation the parameters
+ * that request it.
+ */
+interface ReportSpec<R = unknown, A = Record<string, unknown>> {
+  /**
+   * The file's base name under the configured report directory, and the tool
+   * name recorded inside the report. A function where one operation answers
+   * different questions and writes each under its own name — pipelines archive
+   * these paths, so they are part of the contract.
+   */
+  name: string | ((args: A) => string);
+  /** The compact stand-in returned once the full result is on disk. */
+  summary: (result: R) => unknown;
+  /**
+   * The `outputFile` parameter as this operation offers it. Declared here and
+   * nowhere else, so an operation cannot advertise the parameter without the
+   * plumbing behind it, nor grow the plumbing without the parameter.
+   */
+  outputFile: {
+    /** The example path its description carries. */
+    example: string;
+    cli?: CliParamOptions;
+    mcp?: McpParamOptions;
+  };
+  /** The same findings, as a GitLab Code Quality report the pipeline collects. */
+  codequality?: {
+    /** What the findings are called in the parameter's description. */
+    findings: string;
+    /**
+     * Returning undefined writes nothing, which is not the same as writing an
+     * empty array: the empty array is the baseline the merge-request widget
+     * diffs against, so it is only right for a run that looked for these
+     * findings and found none.
+     */
+    issues: (result: R, ctx: ReportContext<A>) => CodeQualityIssue[] | undefined;
+  };
+}
+/**
+ * A report spec with its result type erased, as the runner sees it.
  *
- * - **No app info** (`config.apps` empty or absent, e.g. hand-built
- *   configs): consumption edges are unknowable. `appsUsingLayer` and
- *   `layersOfApp` return `[]`, and `sharedLayers` conservatively contains
- *   *every* canonical layer — with no ownership information, every
- *   layer's keys must be treated as globally visible.
- * - **Single-app config** (generic/Laravel/Vue/React adapters, or a Nuxt
- *   project with one app): the strict definition applies, so
- *   `sharedLayers` is empty (no layer is consumed by more than one app)
- *   and `appsUsingLayer` returns that one app for the layers it consumes.
- *   Per-layer scope then equals the whole project, which is correct.
- * - **Canonical layer consumed by no app** (in a multi-app config):
- *   `appsUsingLayer` returns `[]` and the layer is not in `sharedLayers`.
- *   Callers should treat such layers conservatively (global scope).
+ * `any` rather than `unknown`: the runner holds a result whose type it cannot
+ * know, while every declaration site is checked against its own operation's
+ * result type.
  */
-interface LayerGraph {
+type AnyReportSpec = ReportSpec<any>;
+/** How the MCP server advertises an operation as a tool. */
+interface McpToolSpec {
+  name: string;
+  /** The display title a host shows. */
+  title: string;
+  /** Behaviour hints a host reads. Only the translating tools declare any. */
+  annotations?: {
+    title?: string;
+    readOnlyHint?: boolean;
+  };
+}
+/** How the CLI exposes an operation as a command. */
+interface CliCommandSpec {
+  name: string;
+}
+/**
+ * What a surface hands an operation beyond its parameters.
+ *
+ * `surface` exists because the guidance an agent-mode result carries is the
+ * caller's, not the operation's: a terminal is told to pass `--provider`, a
+ * host is told to translate the fallback contexts inline. Keeping both strings
+ * in one place is the point — they used to sit in two files and say different
+ * things about the same state.
+ */
+interface OperationContext {
+  surface: Surface;
+  /** Provider-backed translation, when the surface resolved one. */
+  translateFn?: TranslateFn;
   /**
-   * Alias-free locale dirs, in `config.localeDirs` order. Aliased entries
-   * (e.g. `app-outlook` pointing at `app-shop`'s dir) are excluded.
+   * Progress reporting, when the caller asked for it. Only MCP does — a
+   * terminal is left with its exit code. The operations that take long enough
+   * to report call it (translating, orphan scans); the rest never do.
    */
-  canonicalLayers: LocaleDir[];
+  progressFn?: ProgressFn;
   /**
-   * Resolve a layer name to the canonical layer that owns its locale dir.
-   * Follows chained `aliasOf` links (an alias may point at a layer that
-   * was itself demoted to an alias). Identity for canonical names and for
-   * names unknown to `localeDirs` (e.g. layers without locale dirs).
+   * The number of steps the operation is about to report, counted in whatever
+   * unit it reports in. Called once, before the first `progressFn` call, so a
+   * notification never goes out against an unknown total.
    */
-  ownerOf: (layer: string) => string;
+  onProgressTotal?: (total: number) => void;
+}
+/**
+ * The value of one parameter as the operation receives it: already split,
+ * parsed and validated by whichever surface took it.
+ */
+type ParamValue<S extends ParamSpec> = S extends {
+  type: 'boolean';
+} ? boolean : S extends {
+  type: 'number';
+} ? number : S extends {
+  type: 'record';
+} ? TranslationsRecord : S extends {
+  type: 'string[]';
+  allowAll: true;
+} ? string[] | 'all' : S extends {
+  type: 'string[]';
+} ? string[] : S extends {
+  type: 'string';
+  enum: readonly (infer E extends string)[];
+} ? E : S extends {
+  type: 'string';
+} ? string : never;
+type RequiredParamNames<P extends Params> = { [K in keyof P]-?: P[K] extends {
+  required: true;
+} ? K : never }[keyof P];
+/**
+ * The arguments an operation's `run` receives. Required parameters are present,
+ * the rest are optional, and `projectDir` is always available because both
+ * surfaces resolve it themselves (the CLI from `--projectDir`, the server from
+ * I18N_PROJECT_DIR) rather than making every operation declare it.
+ */
+type OperationArgs<P extends Params = Params> = { [K in RequiredParamNames<P> & keyof P]: ParamValue<P[K]> } & { [K in Exclude<keyof P, RequiredParamNames<P>>]?: ParamValue<P[K]> } & {
+  projectDir?: string;
+};
+/** One operation, as both surfaces read it. */
+interface OperationDescriptor<P extends Params = Params> {
+  /** Stable identifier, independent of what either surface calls it. */
+  id: string;
+  /** Null for an operation the CLI does not expose. */
+  cli: CliCommandSpec | null;
+  /** Null for an operation the MCP server does not advertise. */
+  mcp: McpToolSpec | null;
+  /** One sentence, on both surfaces. */
+  description: string;
   /**
-   * Names of apps whose consumed layers include the given layer. The
-   * queried name and each app's layer list are alias-resolved via
-   * {@link ownerOf} first, so querying an alias name yields the owner's
-   * consumers. Returns `[]` when no app info exists.
+   * Further prose for a model deciding whether to call the tool: when to reach
+   * for it, what the result carries, what it will not do. MCP only — a `--help`
+   * line has to stay a line, and the generated CLI page says the same things in
+   * its flag table.
    */
-  appsUsingLayer: (layer: string) => string[];
+  longDescription?: string;
+  params: P;
+  /** CI gates the CLI evaluates. Exit codes are a CLI notion, so MCP ignores these. */
+  gates?: GateSpec[];
   /**
-   * Canonical layers consumed by more than one app — e.g. a shared root
-   * layer in a multi-app monorepo, identified purely from consumption
-   * edges (no name matching). When no app info exists, contains every
-   * canonical layer (see degenerate-case semantics above).
+   * The operation translates, so the surface has to hand it a backend: the CLI
+   * resolves one from the provider flags, the server from its startup
+   * environment. Without one the operation returns contexts to translate by
+   * hand rather than failing.
    */
-  sharedLayers: LocaleDir[];
+  usesTranslateFn?: boolean;
   /**
-   * Canonical layers the given app consumes (alias entries in the app's
-   * layer list resolve to their owners; layers without locale dirs are
-   * omitted). Returns `[]` for unknown apps or when no app info exists.
+   * The result is large enough to be worth writing to a file instead of
+   * returning. Declaring this is what adds the parameters that request it and
+   * what makes the configured report directory apply to the operation.
+   *
+   * The result type stays open: a `run` whose parameters are contextually typed
+   * is not an inference site, so nothing here can see the operation's own
+   * result type. Declaration sites annotate it on the builder instead, which is
+   * what type-checks them.
    */
-  layersOfApp: (app: string) => LocaleDir[];
+  report?: ReportSpec<any, OperationArgs<P>>;
+  /**
+   * Declared as a method so the table can hold descriptors with different
+   * parameter maps: method parameters are compared bivariantly, which is what
+   * lets `run` be typed against each operation's own arguments and still be
+   * callable through the erased element type below.
+   */
+  run(args: OperationArgs<P>, ctx: OperationContext): Promise<unknown>;
 }
 /**
- * Build a {@link LayerGraph} from a resolved config's `localeDirs`
- * (with their `aliasOf` markers) and `apps` (app → consumed-layers edges).
+ * A descriptor as the registrars see it, with `run` erased to plain arguments.
+ * They build those arguments from a schema at runtime and cannot know the
+ * per-operation type, so the erasure happens once, in `defineOperation`,
+ * instead of at every call site.
  */
-declare function buildLayerGraph(config: I18nConfig): LayerGraph;
+type AnyOperationDescriptor = Omit<OperationDescriptor<Params>, 'run' | 'params' | 'report'> & {
+  params: Params;
+  report?: AnyReportSpec;
+  run(args: Record<string, unknown>, ctx: OperationContext): Promise<unknown>;
+};
 /**
- * The graph as plain data, for surfaces that can only carry JSON.
+ * Declare one operation. The `const` type parameter is what keeps `required:
+ * true` and `enum: [...]` literal, so `run` receives `layer: string` rather
+ * than `string | undefined` for a parameter the surface guarantees.
  *
- * {@link LayerGraph} is function-valued, so it cannot be serialised directly.
- * This answers the question an agent actually has — *which layer does this key
- * belong in* — which the flat layer list `discover` returned could not: a key
- * used by more than one app belongs in a layer those apps share, and `shared`
- * names those layers outright (#342).
+ * An operation that declares a `report` gains the parameters that request one
+ * here, so the two cannot drift apart.
+ */
+//#endregion
+//#region src/surface/descriptors.d.ts
+/**
+ * Registry order: it is the order `the-i18n-cli --help` lists commands in and
+ * the order both generated reference overviews are written in.
+ */
+declare const descriptors: readonly AnyOperationDescriptor[];
+/** The descriptors a surface exposes, in registry order. */
+declare function descriptorsFor(surface: 'cli' | 'mcp'): AnyOperationDescriptor[];
+/** The parameter names a surface exposes for one operation, in declaration order. */
+declare function visibleParams(descriptor: AnyOperationDescriptor, surface: 'cli' | 'mcp'): string[];
+//# sourceMappingURL=descriptors.d.ts.map
+
+//#endregion
+//#region src/surface/report.d.ts
+/**
+ * Write the result where the caller asked for it, and hand back the compact
+ * stand-in — or hand back the result untouched when nothing asked for a file.
  *
- * The degenerate cases documented on {@link LayerGraph} survive the flattening,
- * because they are what keeps a consumer from wrongly narrowing scope:
- * a config with no app info reports *every* canonical layer as shared, and a
- * layer no app consumes appears in `consumers` with an empty array rather than
- * being left out. Absent and "none" must not look alike here.
+ * Called with the arguments the operation ran with, which is what lets an
+ * operation answering several questions write each under its own report name.
  */
-interface SerializedLayerGraph {
-  /** Alias-free layer names, in `config.localeDirs` order. */
-  canonical: string[];
-  /** Canonical layers consumed by more than one app — where shared keys belong. */
-  shared: string[];
-  /** Alias layer name → the canonical layer whose locale dir it points at. */
-  aliases: Record<string, string>;
-  /** Canonical layer name → the apps consuming it. Every canonical layer is a key. */
-  consumers: Record<string, string[]>;
-}
-/** Flatten {@link buildLayerGraph}'s view of `config` into plain JSON. */
-declare function serializeLayerGraph(config: I18nConfig): SerializedLayerGraph;
-//# sourceMappingURL=layer-graph.d.ts.map
+declare function divertToReport(result: unknown, descriptor: AnyOperationDescriptor, args: Record<string, unknown>): Promise<unknown>;
+//# sourceMappingURL=report.d.ts.map
+//#endregion
+//#region src/config/cache.d.ts
+/** The most recently resolved config, or null when nothing has been resolved. */
+declare function getCachedConfig(): I18nConfig | null;
+declare function clearConfigCache(): void;
+//# sourceMappingURL=cache.d.ts.map
 //#endregion
-//#region src/scanner/frontends/oxc.d.ts
-declare function createOxcFrontend(): LanguageFrontend;
-//# sourceMappingURL=oxc.d.ts.map
+//#region src/config/detector.d.ts
+declare function detectI18nConfig(projectDir: string): Promise<I18nConfig>;
+//# sourceMappingURL=detector.d.ts.map
 
 //#endregion
 //#region src/scanner/frontends/patterns.d.ts
 /**
- * The regex path as a language frontend (#332).
+ * Pattern matching as a language frontend, reached only for a file a syntax
+ * frontend declined.
  *
  * Regexes frame text and report call sites; what a site means is decided once,
  * in the rules, the same as for every other frontend. Binding is always
@@ -1339,24 +1816,6 @@ declare function createPhpFrontend(): LanguageFrontend;
  * a key's fate must not depend on which file type referenced it (#332).
  */
 
-//#endregion
-//#region src/scanner/frontends/php/blade.d.ts
-/**
- * Blade, by lifting (#404, #332).
- *
- * No maintained Blade AST parser exists, and none is needed: every construct
- * that can carry a translation key wraps a PHP expression. The lexical pass
- * here finds those wrappers — echoes, `@lang`/`@choice`, `@php` blocks, raw
- * PHP tags — and hands the expression inside to the same parser and the same
- * site collection plain PHP uses. The regex frames text; it never decides
- * what a key is.
- *
- * A lifted chunk the parser cannot read declines the whole file to the
- * pattern fallback: partially-read templates would silently drop keys.
- */
-declare function createBladeFrontend(): LanguageFrontend;
-//# sourceMappingURL=blade.d.ts.map
-
 //#endregion
 //#region src/io/locale-data.d.ts
 declare function readLocaleData(config: I18nConfig, layer: string, locale: LocaleDefinition): Promise<Record<string, unknown>>;
@@ -1400,7 +1859,7 @@ declare class TranslateProviderError extends Error {
   constructor(message: string, kind: TranslateProviderErrorKind, status?: number);
 }
 /**
- * Classify an SDK error into a TranslateProviderError:
+ * Classify a provider error into a TranslateProviderError:
  * 401/403 → auth, 429 → rate-limit, anything else → provider.
  * Already-classified errors pass through unchanged.
  */
@@ -1432,8 +1891,9 @@ declare function resolveProviderBaseUrl(sources: {
   config?: string;
 }): string | undefined;
 /**
- * Create a TranslateFn from an LLM provider config.
- * Throws if the provider SDK is not installed or API key is missing.
+ * Create a TranslateFn from an LLM provider config. Every provider is called
+ * over plain HTTP, so nothing beyond the CLI has to be installed.
+ * Throws if the API key is missing.
  */
 declare function createTranslateFn(config: LlmProviderConfig): Promise<TranslateFn>;
 //# sourceMappingURL=providers.d.ts.map
@@ -1455,5 +1915,5 @@ declare function loadProjectConfig(projectDir: string): Promise<ProjectConfig |
 //# sourceMappingURL=project-config.d.ts.map
 
 //#endregion
-export { AddTranslationsResult, BASE_URL_ENV, type CallArgument, type CallSite, type CheckUndefinedKeysResult, type CheckUndefinedKeysSummary, CodeUsageRef, CodeUsageResult, type DuplicateKeyCollision, DynamicKeyRef, EmptyTranslationsResult, type FileEvidence, type FindDuplicateKeysResult, type FindDuplicateKeysSummary, FindOrphanKeysResult, GeneratedProjectConfig, type I18nConfig, type I18nKitConfig, InitProjectConfigResult, type KeyUsageLocation, LARAVEL_PATTERNS, type LanguageFrontend, type LayerGraph, LayerStatus, type LlmProvider, type LlmProviderConfig, type LocaleDefinition, type LocaleDir, LocaleDirInfo, type LocaleRefAmbiguity, LocaleRefInfo, LocaleStatus, MisplacedUsageRef, MissingTranslationsResult, MoveTranslationKeyPlanEntry, MoveTranslationKeyResult, MutationPreview, MutationResult, PlaceholderValidationIssue, PlaceholderValidationResult, ProgressFn, type ProjectConfig, RemoveOrphanKeysResult, RemoveTranslationsPreview, RemoveTranslationsResult, RenameTranslationKeyPreview, RenameTranslationKeyResult, ScaffoldLocaleFileInfo, ScaffoldLocaleResult, ScanCodeUsageResult, type ScanResult, SearchMatch, SearchTranslationsResult, type SerializedLayerGraph, ToolError, TranslateAllLayersResult, TranslateAllLayersSummary, TranslateFailReason, TranslateFn, TranslateKeyLocaleIssue, TranslateKeyResult, TranslateLayerTotals, TranslateMissingCompactEntry, TranslateMissingLocaleResult, TranslateMissingOutcome, TranslateMissingResult, TranslateMode, TranslateProviderError, type TranslateProviderErrorKind, TranslateRequest, TranslateResponse, TranslateSkipReason, TranslationStatusResult, TranslationStatusSummary, type UncertainKeyFinding, type UndefinedKeyFinding, UnresolvedKeyWarningRef, UnresolvedLocaleRef, UpdateTranslationsResult, VUE_NUXT_PATTERNS, WriteTranslationsResult, addTranslations, buildLayerGraph, checkUndefinedKeys, classifyProviderError, clearConfigCache, createBladeFrontend, createOxcFrontend, createPatternsFrontend, createPhpFrontend, createTranslateFn, defineI18nKitConfig, detectConfig, detectI18nConfig, findDuplicateKeys, findEmptyTranslations, findLocaleImpl, findOrphanKeys, getCachedConfig, getMissingTranslations, getPatternSet, getTranslationStatus, getTranslations, listLocaleDirs, listNamespaces, loadProjectConfig, moveTranslationKey, readLocaleData, removeOrphanKeys, removeTranslations, renameTranslationKey, resolveProtectedLocales, resolveProviderBaseUrl, scaffoldLocaleFiles, scanCodeUsage, scanSourceFiles, searchTranslations, serializeLayerGraph, toErrorMessage, translateKey, translateMissing, updateTranslations, writeTranslations };
-//# sourceMappingURL=index-w-EQZEZF.d.ts.map
+export { type AnyOperationDescriptor, type AnyReportSpec, BASE_URL_ENV, type CheckUndefinedKeysResult, type CheckUndefinedKeysSummary, CodeUsageRef, CodeUsageResult, DeclaredNamespaceRef, DescribeProjectResult, type DuplicateKeyCollision, DynamicKeyRef, EmptyTranslationsResult, type FindDuplicateKeysResult, type FindDuplicateKeysSummary, FindOrphanKeysResult, GeneratedProjectConfig, type I18nConfig, type I18nKitConfig, InitProjectConfigResult, type KeyUsageLocation, LARAVEL_PATTERNS, type LanguageFrontend, type LayerGraph, LayerStatus, type LlmProvider, type LlmProviderConfig, type LocaleDefinition, type LocaleDir, LocaleDirInfo, type LocaleRefAmbiguity, LocaleRefInfo, LocaleStatus, MisplacedUsageRef, MissingTranslationsResult, MoveTranslationKeyOutcome, MoveTranslationKeyPlanEntry, MoveTranslationKeyResult, MutationPreview, MutationResult, type OperationContext, type OperationDescriptor, type ParamSpec, type ParamType, type Params, PlaceholderValidationIssue, PlaceholderValidationResult, ProgressFn, type ProjectConfig, RemoveOrphanKeysResult, RemoveTranslationsPreview, RemoveTranslationsResult, RenameTranslationKeyPreview, RenameTranslationKeyResult, type ReportContext, type ReportSpec, ScaffoldLocaleFileInfo, ScaffoldLocaleResult, ScanCodeUsageResult, type ScanResult, SearchKeyMatch, SearchMatch, SearchMatchMode, SearchTranslationsResult, type SerializedLayerGraph, type Surface, ToolError, TranslateAllLayersResult, TranslateAllLayersSummary, TranslateFailReason, TranslateFn, TranslateKeyLocaleIssue, TranslateKeyResult, TranslateKeySkip, TranslateLayerTotals, TranslateMissingCompactEntry, TranslateMissingLocaleResult, TranslateMissingOptions, TranslateMissingOutcome, TranslateMissingResult, TranslateMode, TranslateProviderError, type TranslateProviderErrorKind, TranslateRequest, TranslateResponse, TranslateSkipReason, TranslationStatusResult, TranslationStatusSummary, type TranslationsRecord, type UncertainKeyFinding, type UndefinedKeyFinding, UnresolvedKeyWarningRef, UnresolvedLocaleRef, WriteTranslationsResult, buildLayerGraph, checkUndefinedKeys, classifyProviderError, clearConfigCache, createPatternsFrontend, createPhpFrontend, createTranslateFn, defineI18nKitConfig, describeProject, descriptors, descriptorsFor, detectConfig, detectI18nConfig, divertToReport, findDuplicateKeys, findEmptyTranslations, findLocaleImpl, findOrphanKeys, getCachedConfig, getMissingTranslations, getTranslationStatus, getTranslations, listLocaleDirs, listNamespaces, loadProjectConfig, moveTranslationKey, readLocaleData, removeOrphanKeys, removeTranslations, renameTranslationKey, resolveProtectedLocales, resolveProviderBaseUrl, scaffoldLocaleFiles, scanCodeUsage, scanSourceFiles, searchTranslations, serializeLayerGraph, toErrorMessage, translateKey, translateMissing, visibleParams, writeTranslations };
+//# sourceMappingURL=index-CWFWYHf5.d.ts.map