@verbatra/sdk 0.7.1 → 0.8.0

package/dist/index.d.cts

@@ -4,8 +4,19 @@ import { Interactions } from '@google/genai';
 import OpenAI from 'openai';
 
 /**
- * A single, format-neutral translation unit. Placeholders are supplied already
- * extracted; core never derives them from the value.
+ * A single, format-neutral translation unit. Placeholders are supplied already extracted; core never
+ * derives them from the value, so an adapter that reads a file is the one authority on what counts as
+ * a placeholder in that format.
+ *
+ * The fields are: `key`, the entry's identifier within its namespace, non-empty and already flattened
+ * to the dotted path an adapter produced; `namespace`, the namespace the entry belongs to, empty when
+ * the format has no namespacing; `value`, the translatable string itself, which is untrusted input and
+ * may be empty; `description` and `meaning`, both optional free-form context that a provider is told to
+ * use only for disambiguation and never to translate or echo back; `placeholders`, the format's
+ * placeholder tokens in document order, used for the output integrity check and to decide which entries
+ * a placeholder-blind provider must withhold; and `isPlural`, whether the entry carries plural forms
+ * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
+ * decides and which feeds the content hash.
  */
 declare const translationEntrySchema$1: z.ZodObject<{
     key: z.ZodString;
@@ -16,12 +27,16 @@ declare const translationEntrySchema$1: z.ZodObject<{
     placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
     isPlural: z.ZodBoolean;
 }, z.core.$strip>;
-/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+/**
+ * The validated shape of one translation unit; the inferred type of {@link translationEntrySchema},
+ * made deeply readonly. See that schema for what each field carries.
+ */
 type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
 
 /**
  * Result of comparing source placeholders against translated-output placeholders as MULTISETS
- * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
+ * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
  */
 interface PlaceholderIntegrityResult$1 {
     /** True when nothing is missing or extra: the multisets match, regardless of order. */
@@ -30,13 +45,22 @@ interface PlaceholderIntegrityResult$1 {
     readonly missing: readonly string[];
     /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
     readonly extra: readonly string[];
-    /** Same multiset present in both, but in a different order. */
+    /** Same multiset present in both, but in a different order. Never true alongside a mismatch. */
     readonly reordered: boolean;
 }
 
-/** A provider is either a prompt-driven LLM or a dedicated machine-translation API. */
+/**
+ * A provider is either a prompt-driven LLM (`llm`) or a dedicated machine-translation API
+ * (`machine-translation`). The distinction is descriptive, not dispatch: both kinds satisfy the same
+ * {@link TranslationProvider} contract, and callers use it to set expectations (an LLM accepts free-form
+ * context and a glossary term map, an MT API generally does not).
+ */
 type ProviderKind = "llm" | "machine-translation";
-/** Target tone for a translation. Maps to formality for machine-translation providers. */
+/**
+ * Target tone for a translation. `formal` and `informal` request the corresponding register, and
+ * `neutral` requests neither. Machine-translation providers map it to their formality setting and may
+ * report a `FORMALITY_DOWNGRADED` {@link ProviderNotice} when they cannot apply it.
+ */
 type Tone = "formal" | "informal" | "neutral";
 /**
  * Produces the placeholder set of a value for the output integrity check. Supplied
@@ -54,7 +78,7 @@ type PlaceholderComparator = (source: string, translated: string) => Placeholder
 /**
  * A batch translation request. Format- and provider-neutral: it carries no prompt,
  * model, key, or other provider-specific field. The placeholder extractor is
- * mandatory (see validateRequest).
+ * mandatory and is checked before the data fields are parsed.
  */
 interface TranslateRequest {
     /** BCP-47 source locale of the entries (for example, "en"). */
@@ -65,7 +89,7 @@ interface TranslateRequest {
     readonly entries: readonly TranslationEntry$1[];
     /** Optional source-term to target-term map applied by glossary-capable providers. */
     readonly glossary?: Readonly<Record<string, string>>;
-    /** Optional target tone; machine-translation providers map it to formality. */
+    /** Optional target {@link Tone}; machine-translation providers map it to formality. */
     readonly tone?: Tone;
     /** Mandatory placeholder extractor; the output integrity check runs against it. */
     readonly extractPlaceholders: PlaceholderExtractor;
@@ -77,14 +101,16 @@ interface TranslateRequest {
     readonly comparePlaceholders?: PlaceholderComparator;
     /**
      * Optional cancellation signal for this batch. When aborted, an in-flight provider call rejects
-     * with the abort, unwrapped, instead of a {@link ProviderError} (see `guardProviderCall`). Not a
-     * plain-data field: it is never validated by `requestDataSchema` and never sent to a provider.
+     * with the abort, unwrapped, instead of a `ProviderError`. Not a plain-data field: it is
+     * never validated alongside the data fields and never sent to a provider.
      */
     readonly signal?: AbortSignal;
 }
 /** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
 interface Usage {
+    /** Tokens consumed by the request, summed across the initial call and any repair round. */
     readonly inputTokens: number;
+    /** Tokens produced by the response, summed across the initial call and any repair round. */
     readonly outputTokens: number;
 }
 /**
@@ -113,25 +139,38 @@ interface ProviderNotice {
 }
 /**
  * Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
- * assessment, never a raw model self-score: four are recomputable from plain source/translated
- * values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
- * a provider notice.
+ * assessment, never a raw model self-score: four are recomputable from plain source and translated
+ * values, and `PROVIDER_DEGRADED` is layered on afterwards from the batch's notices.
  *
  * - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
- * - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
- * - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
+ *   Only considered once the trimmed source is long enough for the ratio to mean anything.
+ * - `EQUALS_SOURCE`: the translated value equals the source value once both are trimmed, so a
+ *   difference in leading or trailing whitespace alone still counts as equal. Also requires that
+ *   the locales differ and that the value contains at least one letter (so a bare symbol or number
+ *   is not flagged).
+ * - `GLOSSARY_TERM_MISSED`: a configured glossary source term appeared in the source but its target
+ *   term did not appear in the translation.
  * - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
- * - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
+ * - `PROVIDER_DEGRADED`: the batch this key came from carried a `FORMALITY_DOWNGRADED` or
+ *   `GLOSSARY_IGNORED` notice, either of which can silently change wording. A
+ *   `PLACEHOLDER_UNSUPPORTED` notice does not raise it, since the affected entries are withheld
+ *   rather than degraded.
  */
 type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
 /** A key flagged for human review, carrying every reason code that applies. */
 interface ReviewFlag {
+    /** Always "review": the flag exists only for flagged keys, so there is no "ok" member. */
     readonly status: "review";
+    /** Every {@link ReviewReasonCode} that applies to this key; never empty. */
     readonly reasons: readonly ReviewReasonCode[];
 }
 /** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
 interface TranslateResult {
-    /** The translated value for each requested key. */
+    /**
+     * The translated value for each requested key. A key can be absent when the provider withheld it
+     * (see `PLACEHOLDER_UNSUPPORTED`) or never returned it, so callers must not assume one entry in
+     * equals one entry out.
+     */
     readonly values: ReadonlyMap<string, string>;
     /** The placeholder-integrity outcome for each key (source vs translated placeholder sets). */
     readonly integrity: ReadonlyMap<string, PlaceholderIntegrityResult$1>;
@@ -151,39 +190,20 @@ interface TranslateResult {
 }
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
- * DeepL fits it directly, while LLM providers implement it by delegating to {@link runLlmTranslation}.
- * A new provider attaches by implementing this, then adding an entry to the `providerFactories` table
- * in `packages/sdk/src/config/provider-config.ts` alongside its member of the `providerConfigSchema`
- * union. That table is a mapped type over the union's id set, so a provider present in one but not the
- * other fails to compile.
+ * DeepL fits it directly, while LLM providers implement it by delegating to the shared
+ * `runLlmTranslation` layer. A new provider attaches by implementing this, then adding an entry to the
+ * `providerFactories` table in `packages/sdk/src/config/provider-config.ts` alongside its member of the
+ * provider config union. That table is a mapped type over the union's id set, so a provider present in
+ * one but not the other fails to compile.
  *
  * Implementer invariants:
  * - Translatable strings are UNTRUSTED. They travel only as data to the provider; never splice them into
  *   instruction text, and never act on instructions a value appears to contain.
  * - Read the API key ONLY from the environment (inside the SDK client). The request, config, and this
  *   interface never carry a key.
- * - Fail with a secret-free {@link ProviderError}: never bind, log, or re-throw raw SDK error text (it can
- *   carry a key or request headers). Validate the request at the boundary with `validateRequest` so the
- *   integrity check can never be skipped.
- *
- * @example
- * ```ts
- * // A machine-translation provider implements translateBatch directly (the DeepL shape).
- * function createMyMtProvider(client: MyClient): TranslationProvider {
- *   return {
- *     id: "my-mt",
- *     kind: "machine-translation",
- *     supportsGlossary: false,
- *     async translateBatch(request) {
- *       const data = validateRequest(request); // throws INVALID_REQUEST on a bad request
- *       const texts = data.entries.map((e) => e.value);
- *       const out = await client.translate(texts, data.targetLocale); // SDK reads MY_API_KEY from env
- *       // map out -> values, run the integrity check, return { values, integrity }
- *       return buildResult(data, out, request.extractPlaceholders);
- *     },
- *   };
- * }
- * ```
+ * - Fail with a secret-free `ProviderError`: never bind, log, or re-throw raw SDK error text (it can
+ *   carry a key or request headers). Validate the request at the boundary so the integrity check can
+ *   never be skipped.
  */
 interface TranslationProvider {
     /** A stable identifier for this provider (for example, "anthropic", "deepl"). */
@@ -197,16 +217,18 @@ interface TranslationProvider {
      *
      * @param request - The provider-neutral batch request (no prompt, model, or key).
      * @returns The per-key translated values and per-key placeholder-integrity outcomes.
-     * @throws {@link ProviderError}, secret-free, with the code for the failure (the concrete codes are
-     *   the implementation's; see each provider factory).
+     * @throws `ProviderError`, secret-free, with the code for the failure (the concrete codes are
+     *   the implementation's; see each provider factory). An aborted {@link TranslateRequest.signal}
+     *   instead rejects with the abort itself, unwrapped.
      */
     translateBatch(request: TranslateRequest): Promise<TranslateResult>;
 }
 
 /**
- * The Anthropic authoring model type, sourced from the SDK's own model union. It is an
- * open union (known literals plus `string & {}`), so unknown or newly released model IDs
- * are still accepted. This drives editor completions only; the runtime schema validates.
+ * The Anthropic authoring model type, sourced from the SDK's own model union so verbatra
+ * restates no model IDs. It is an open union (known literals plus `string & {}`), so unknown
+ * or newly released model IDs are still accepted. Type-only: it informs editor completions
+ * and is never validated at runtime, where the schema stays `z.string().min(1)`.
  */
 type AnthropicModel = Anthropic.Messages.Model;
 
@@ -219,13 +241,24 @@ type AnthropicModel = Anthropic.Messages.Model;
 type GeminiModel = Interactions.Model;
 
 /**
- * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model
- * union. It drives editor completions only; it is never read at runtime, and the
- * runtime schema stays `z.string().min(1)`.
+ * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model union
+ * so verbatra restates no model IDs. Type-only: it drives editor completions and is never
+ * read at runtime, where the schema stays `z.string().min(1)`.
  */
 type OpenAiModel = OpenAI.ChatModel;
 
-/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+/**
+ * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
+ * member names the ecosystem it round-trips, not just a file extension, because several of them share
+ * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
+ * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
+ * `properties` (Java and Spring `.properties` files).
+ *
+ * The set is closed: a format outside it cannot be represented, so adding one means adding a member
+ * here and an adapter that claims it.
+ */
 declare const supportedFormatSchema$1: z.ZodEnum<{
     "i18next-json": "i18next-json";
     "vue-i18n-json": "vue-i18n-json";
@@ -236,92 +269,110 @@ declare const supportedFormatSchema$1: z.ZodEnum<{
     arb: "arb";
     properties: "properties";
 }>;
-/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
 type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
 
-/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+/**
+ * The outcome of a size-bounded text read. A file that is absent or larger than the caller's limit
+ * is reported as a state rather than thrown, so a caller can treat "no file yet" as normal and an
+ * oversized file as a distinct, actionable condition.
+ */
 type BoundedFileRead = {
+    /** The file was read in full. */
     readonly kind: "ok";
+    /** The file's content, decoded as UTF-8. */
     readonly content: string;
 } | {
+    /** No readable file exists at the path. */
     readonly kind: "missing";
 } | {
+    /** The file exists but exceeds the requested byte limit, so nothing was read. */
     readonly kind: "too-large";
 };
-/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+/**
+ * The outcome of a size-bounded binary read, used for interchange workbooks. Mirrors
+ * {@link BoundedFileRead} but yields raw bytes rather than decoded text.
+ */
 type BoundedBytesRead = {
+    /** The file was read in full. */
     readonly kind: "ok";
+    /** The file's raw bytes. */
     readonly bytes: Uint8Array;
 } | {
+    /** No readable file exists at the path. */
     readonly kind: "missing";
 } | {
+    /** The file exists but exceeds the requested byte limit, so nothing was read. */
     readonly kind: "too-large";
 };
 /**
- * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
+ * The file-system port the SDK's own I/O goes through. Supplying your own implementation as a
+ * `deps.fs` option redirects that I/O, which is how the SDK's tests avoid touching disk and how an
+ * embedding application can back part of a project with something other than a local disk.
+ *
+ * Know what the seam does and does not cover before relying on it. It carries the run-status file,
+ * the lock-file, the config glossary, and workbook and interchange I/O. It does not carry the
+ * locale files: those are read and written by `@verbatra/format-adapters`, which uses `node:fs`
+ * directly and is given a path rather than this port. Supplying a `deps.fs` therefore does not make
+ * a run fully in-memory, and a project's translations are still read from and written to real disk.
+ *
+ * Reads are size-bounded by contract so that a hostile or accidentally huge file cannot exhaust
+ * memory. Writes are expected to be atomic: the default implementation writes to a temporary file
+ * and renames it into place, so a crash mid-write never leaves a half-written file behind.
+ * Directory creation is the caller's job, so an implementation whose `writeFile` targets a real
+ * directory tree must also implement `mkdir`.
  */
 interface SdkFs {
-    /** Whether a readable file exists at the path. */
+    /** Reports whether a readable file exists at the path. */
     fileExists(path: string): Promise<boolean>;
-    /**
-     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
-     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
-     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
-     */
+    /** Reads a file as UTF-8 text, refusing to read more than `maxBytes`. */
     readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
+    /** Reads a file as raw bytes, refusing to read more than `maxBytes`. */
     readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    /** Writes UTF-8 text to the path, replacing any existing file atomically. */
     writeFile(path: string, data: string): Promise<void>;
-    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    /** Writes raw bytes to the path, replacing any existing file atomically. */
     writeBytes(path: string, data: Uint8Array): Promise<void>;
     /**
-     * Atomically create a file only if it does not already exist (O_EXCL semantics), creating any
-     * missing parent directory first. Returns true if this call created the file, false if a file
-     * was already present (no write performed). The backbone of {@link withLocaleWriteLock}'s
-     * exclusive-create lock: the parent-directory creation lives here so that primitive never touches
-     * `node:fs` directly and a fake `SdkFs` in tests never needs a real directory to exist.
+     * Creates a file only if it does not already exist, returning `false` when it does. This is the
+     * primitive behind the per-locale write lock, so it must be atomic against other processes.
      */
     createExclusive(path: string, data: string): Promise<boolean>;
-    /** Delete a file if present; a no-op if it is already absent. */
+    /** Removes the file at the path, succeeding even when it is already absent. */
     deleteFile(path: string): Promise<void>;
-    /**
-     * Create a directory and every missing parent (mkdir -p); a no-op if it already exists.
-     *
-     * Optional so an `SdkFs` written against an earlier version stays valid, and because an in-memory
-     * test double has no directories to create. Only the delimited export calls it, right before writing
-     * one interchange file per locale into the directory the caller named.
-     */
+    /** Creates a directory and any missing parents. Optional; omit it if the backing store has no directories. */
     mkdir?(path: string): Promise<void>;
 }
 
 /**
- * The content-addressed translation-memory (TM) cache: a local, gitignored, regenerable sidecar to
- * the lock file (`verbatra.cache.json`). It lets a translation whose source content is unchanged be
- * reused for free, even under a renamed key or across two keys with byte-identical source text,
- * instead of being re-sent to the provider.
+ * The on-disk translation memory, read from and written to `verbatra.cache.json` (see
+ * {@link CACHE_FILE_NAME}). A run consults it before calling the provider, so a string that was
+ * already translated under the same configuration is reused instead of paid for again.
  *
- * Nesting is `entries[fingerprint][targetLocale][contentHash] = value`. The fingerprint scopes every
- * entry to one translation context (provider, model, tone, glossary), so a tone or glossary change
- * never serves a stale value. Unlike the lock file, a corrupt or wrong-version cache degrades to an
- * empty cache and never fails a run: it is a cost optimization, not a correctness record.
+ * Entries are keyed by configuration fingerprint, then locale, then source-content hash. The
+ * fingerprint layer means that changing the provider, model, tone, or glossary does not silently
+ * reuse translations produced under the old settings; those entries simply stop matching.
  */
 interface TranslationMemory {
-    /** The cache schema version; a value this build does not recognize degrades the whole file to empty. */
+    /** The cache schema version. A file at an unrecognized version is ignored rather than trusted. */
     readonly version: number;
-    /** Cached values, nested fingerprint to target locale to source content hash to translated value. */
+    /** Cached values, nested as configuration fingerprint, then locale, then source-content hash. */
     readonly entries: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>;
 }
 
-/** The cache file's name, a sibling of the lock file and obviously JSON. */
+/**
+ * The file name of the project's translation memory, resolved against the run's working directory.
+ * Commit it to reuse translations across machines and CI runs, or add it to `.gitignore` to treat
+ * the cache as purely local. Deleting it is always safe: the next run simply repays for the strings
+ * it would have reused.
+ */
 declare const CACHE_FILE_NAME = "verbatra.cache.json";
 
 /**
- * The provider section of the config: a discriminated union over the provider id, reusing each
- * provider's own config schema. There is no key field anywhere in this union except
- * openai-compatible's optional `apiKeyEnvVar`, which names an environment variable rather than carrying
- * a key value; every provider still reads its actual key from the environment at construction.
+ * The zod schema for the `provider` block, discriminated on `id`. Each variant's options are
+ * validated strictly, so an option that belongs to a different provider is reported as an error
+ * rather than ignored. It is embedded in {@link verbatraConfigSchema} and produces
+ * {@link ProviderConfig}.
  */
 declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodLiteral<"anthropic">;
@@ -360,15 +411,34 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
 }, z.core.$strip>], "id">;
-/** One validated provider section: the provider id plus that provider's own options. */
+/**
+ * The `provider` block of a verbatra config: a discriminated union on `id`, so each provider
+ * carries exactly the options it supports and nothing else.
+ *
+ * No variant has a field for an API key. Keys are read from the environment by the provider itself
+ * (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`), which is what keeps
+ * them out of config files and out of version control. The `openai-compatible` variant may name a
+ * different environment variable through `apiKeyEnvVar`, but still never holds the key itself.
+ */
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
-/** The closed set of configurable provider ids. */
+/**
+ * The identifier of a supported translation provider: `anthropic`, `openai`, `gemini`, `deepl`, or
+ * `openai-compatible`. The last one targets a local or self-hosted server that speaks the OpenAI
+ * chat-completions API.
+ */
 type ProviderId = ProviderConfig["id"];
 
 /**
- * The verbatra project configuration. It carries no API key (the provider reads its key from the
- * environment), and unknown top-level keys are rejected so a stray secret cannot hide in it. Validated
- * with zod at the boundary regardless of where it was loaded from.
+ * The zod schema every verbatra config is validated against. {@link loadConfig} applies it, so most
+ * consumers never call it directly; reach for it when you build a config programmatically and want
+ * to validate it before handing it to {@link translate}, or when you surface config errors in your
+ * own tooling.
+ *
+ * The object is strict, so an unrecognized key is an error rather than being silently ignored: a
+ * typo in a config file is reported instead of quietly doing nothing. Beyond the per-field checks,
+ * three whole-config rules are enforced: `targetLocales` must not contain the source locale, it
+ * must not contain two locales that differ only in case (they would collide on a case-insensitive
+ * file system), and `files.pattern` must contain the `{locale}` token.
  */
 declare const verbatraConfigSchema: z.ZodObject<{
     sourceLocale: z.ZodString;
@@ -444,30 +514,40 @@ declare const verbatraConfigSchema: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 /**
- * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
- * is still the union of an inline record or a file path. {@link defineConfig} and the authoring types are
- * built on this; `loadConfig` accepts it as input and produces the resolved {@link VerbatraConfig}.
+ * A config exactly as it is written in a `verbatra.config.ts` file, before the SDK resolves
+ * anything. Its `glossary` may still be a path string pointing at a JSON file.
+ *
+ * This is what {@link defineConfig} returns and what {@link verbatraConfigSchema} parses. Use
+ * {@link VerbatraConfig} for the resolved shape the flows actually consume.
  */
 type VerbatraConfigInput = z.infer<typeof verbatraConfigSchema>;
 /**
- * The verbatra configuration after `loadConfig` has resolved it: identical to {@link VerbatraConfigInput}
- * except `glossary`, which is always a plain record here. A glossary given as a file path is read,
- * parsed, and validated by the loader before a `VerbatraConfig` is produced, so every downstream
- * consumer (the translation flow, `watch`, the CLI) keeps receiving the same resolved shape it always
- * did.
+ * A fully resolved config, ready to pass to any SDK entry point. It differs from
+ * {@link VerbatraConfigInput} in one respect: `glossary` is always an in-memory term map, because
+ * {@link loadConfig} has already read and validated any glossary file the config pointed at.
+ *
+ * Every entry point takes this shape, so a caller that builds a config by hand rather than loading
+ * one from disk must supply the glossary already resolved.
  */
 type VerbatraConfig = Omit<VerbatraConfigInput, "glossary"> & {
+    /**
+     * Terms that must be translated a fixed way, already resolved to an in-memory map. A config that
+     * named a glossary file has had it read by {@link loadConfig} before it reaches here.
+     */
     glossary?: Readonly<Record<string, string>>;
 };
 
 /**
- * A provider's known model literals, with the open `string` arm stripped, so the authoring field
- * accepts only that provider's models. Static authoring aid only; the runtime schema stays a
- * non-empty string, so a brand-new model the installed SDK does not yet list is flagged but still
- * runs.
+ * Reduces a model union to its literal members, discarding the bare `string` member that some
+ * vendor SDKs include to stay open to unreleased models. Without this, `string` would absorb the
+ * literals and the editor would offer no completions at all.
  */
 type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
-/** One provider's config variant with `options.model` narrowed to that provider's known literals. */
+/**
+ * One provider's config variant with its `model` field narrowed from `string` to that vendor's
+ * known model IDs, which is what turns model names into an autocompleted, checked union while
+ * authoring.
+ */
 type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
     id: Id;
 }> extends infer Variant ? Variant extends {
@@ -480,219 +560,306 @@ type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<Provide
     };
 } : never : never;
 /**
- * The authoring view of one provider variant, keyed by id. LLM providers with a known SDK model
- * union restrict `options.model` to that provider's literals. DeepL has no model field and
- * openai-compatible's model is whatever the local server exposes (no known-model list to restrict
- * against), so both are carried through unchanged.
+ * Maps each provider ID to its authoring-time config variant. The three language-model providers
+ * get narrowed model unions; DeepL has no model to narrow, and `openai-compatible` deliberately
+ * keeps a free-form model string because the endpoint is a local or self-hosted server whose model
+ * list the SDK cannot know ahead of time.
  */
 type AuthoringProviderVariant = {
+    /** Anthropic, with `model` narrowed to the Claude model IDs. */
     anthropic: AuthoringVariant<"anthropic", AnthropicModel>;
+    /** OpenAI, with `model` narrowed to the OpenAI chat model IDs. */
     openai: AuthoringVariant<"openai", OpenAiModel>;
+    /** Gemini, with `model` narrowed to the Gemini model IDs. */
     gemini: AuthoringVariant<"gemini", GeminiModel>;
+    /** DeepL, which takes no model because it is a machine-translation API rather than a language model. */
     deepl: Extract<ProviderConfig, {
         id: "deepl";
     }>;
+    /** A local or self-hosted OpenAI-compatible endpoint, whose model stays a free-form string. */
     "openai-compatible": Extract<ProviderConfig, {
         id: "openai-compatible";
     }>;
 };
 /**
- * The authoring view of the whole config for a provider id: a {@link VerbatraConfigInput} whose
- * `provider` is that id's single authoring variant, so `options.model` offers only that provider's
- * models. `glossary` stays the as-authored union (inline record or file path); resolution happens only
- * in `loadConfig`. When `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every
- * value here is assignable to {@link VerbatraConfigInput}, since a model literal is a subtype of
- * `string`.
+ * A config as authored for one specific provider: the ordinary {@link VerbatraConfigInput} shape,
+ * but with `provider` narrowed to that provider's variant so its model IDs autocomplete and a model
+ * belonging to another vendor is a type error.
+ *
+ * This is the parameter type of each {@link defineConfig} overload.
  */
 type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfigInput, "provider"> & {
+    /** The provider block, narrowed to the variant for `TId`. */
     provider: AuthoringProviderVariant[TId];
 };
 /**
- * The authoring view of the whole config across every provider (the `TId = ProviderId`
- * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfigInput} except that
- * `provider` offers per-provider model completions.
+ * A config authored for any supported provider: {@link AuthoringConfigFor} left un-narrowed, which
+ * is the type of the fallback {@link defineConfig} overload.
  */
 type AuthoringConfig = AuthoringConfigFor;
 
 /**
- * Identity helper for authoring a typed `verbatra.config.ts`. It returns its argument unchanged; its
- * only purpose is full type inference and editor autocomplete on the config object, including
- * completion of the selected provider's known model literals.
+ * Types a `verbatra.config.ts` while you author it. The call is a pure identity function at
+ * runtime: its only job is to give your editor the type of the config object so that keys are
+ * completed, unknown keys are rejected, and the model name is checked against the models the
+ * selected provider actually offers.
+ *
+ * This overload narrows to the Anthropic provider, so `provider.options.model` completes to the
+ * Claude model IDs and rejects a model belonging to another vendor.
+ *
+ * Validation at load time is a separate step: {@link loadConfig} still parses the file against
+ * {@link verbatraConfigSchema}, so a config that type-checks can still fail validation.
  *
- * The model restriction is a static authoring constraint only: `loadConfig` validates `model` as a
- * non-empty string, so a model the installed provider SDK does not yet list is flagged in the editor
- * but still runs. Likewise, `glossary` accepts either an inline record or a file path here; `loadConfig`
- * resolves a path to a record before the translation flow ever sees it.
+ * @param config - The config object, narrowed to the Anthropic provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@verbatra/sdk";
  *
- * @param config - The verbatra configuration object.
- * @returns The same config, typed as {@link VerbatraConfigInput}.
+ * export default defineConfig({
+ *   sourceLocale: "en",
+ *   targetLocales: ["de", "fr"],
+ *   format: "i18next-json",
+ *   files: { pattern: "locales/{locale}/common.json" },
+ *   provider: {
+ *     id: "anthropic",
+ *     options: { model: "claude-sonnet-4-6", maxTokens: 4096 },
+ *   },
+ * });
+ * ```
  */
 declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` narrowed to the OpenAI provider, so `provider.options.model`
+ * completes to the OpenAI chat model IDs.
+ *
+ * @param config - The config object, narrowed to the OpenAI provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
 declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` narrowed to the Gemini provider, so `provider.options.model`
+ * completes to the Gemini model IDs.
+ *
+ * @param config - The config object, narrowed to the Gemini provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
 declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` narrowed to the DeepL provider. DeepL is a machine-translation API
+ * rather than a language model, so its options carry an optional glossary ID instead of a model.
+ *
+ * @param config - The config object, narrowed to the DeepL provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
 declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` for any supported provider. This is the fallback overload, and the
+ * one that serves `openai-compatible`, where the model is a free-form string because the endpoint
+ * is a local or self-hosted server whose model list the SDK cannot know.
+ *
+ * @param config - The config object, for any provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
 declare function defineConfig(config: AuthoringConfig): VerbatraConfigInput;
 
-/** Where a config's resolved glossary came from: absent, inline, or a file at the recorded path. */
+/**
+ * Where a loaded config's glossary came from, reported by {@link loadConfigWithMeta}. The resolved
+ * {@link VerbatraConfig} holds only the final term map, so this is the one place a tool can tell an
+ * inline glossary from one read out of a file, and name that file.
+ */
 type GlossaryProvenance = {
+    /** The config declared no glossary. */
     readonly source: "none";
 } | {
+    /** The glossary was written inline in the config as a term map. */
     readonly source: "inline";
 } | {
+    /** The glossary was read from a JSON file the config pointed at. */
     readonly source: "file";
+    /** The absolute path the glossary was read from. */
     readonly path: string;
 };
 
-/** Where {@link loadConfig} should obtain the configuration. The three sources are alternatives. */
+/** Options for {@link loadConfig} and {@link loadConfigWithMeta}. */
 interface LoadConfigOptions {
-    /** Directory to start the search from. Defaults to the current working directory. */
+    /** Directory to search from, and the base for relative paths. Defaults to the process working directory. */
     readonly cwd?: string;
     /**
-     * A pre-resolved config object (e.g. one passed in code) to validate instead of
-     * searching the file system. Still validated with zod, exactly like a loaded file.
+     * A config object to validate directly instead of reading any file. Takes precedence over
+     * `configPath` and over searching. Useful for embedding verbatra in a tool that already holds the
+     * configuration in memory.
      */
     readonly configOverride?: unknown;
-    /**
-     * An explicit config file to load instead of searching. A relative path resolves against `cwd`; an
-     * absolute path is used as given. Parsed and zod-validated exactly like a searched file: a missing
-     * file is `CONFIG_NOT_FOUND`, a present but invalid one is `CONFIG_INVALID`. Takes precedence over
-     * search, but `configOverride` takes precedence over it.
-     */
+    /** An explicit config file to load, bypassing the search. A missing file is an error rather than a fallback to search. */
     readonly configPath?: string;
-    /** The file-system seam a glossary file path is read through. Defaults to {@link defaultFs}. */
+    /** File-system port used to read the glossary file. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
-/** Where the loaded config came from: an in-memory override, one explicit file, or a search result. */
+/**
+ * Where a loaded config came from, reported by {@link loadConfigWithMeta}. A tool can use it to
+ * show which file is in effect, or to tell a real file apart from an in-memory override.
+ */
 type ConfigSource = {
+    /**
+     * `search` means cosmiconfig found the file by walking up from the working directory;
+     * `explicit` means the caller named it through `configPath`.
+     */
     readonly kind: "search" | "explicit";
+    /** The absolute path of the config file that was loaded. */
     readonly filepath: string;
 } | {
+    /** The config came from `configOverride`, so no file was read. */
     readonly kind: "override";
 };
-/**
- * The result of {@link loadConfigWithMeta}: the resolved config, where it was loaded from, and where its
- * glossary came from. `filepath` (when present) and a `glossary` file path are always absolute.
- */
+/** A validated config together with the provenance of the config itself and of its glossary. */
 interface LoadedConfig {
+    /** The validated, fully resolved config, with any glossary file already read into a term map. */
     readonly config: VerbatraConfig;
+    /** Where the config itself came from. */
     readonly source: ConfigSource;
+    /** Where the glossary came from, if the config declared one. */
     readonly glossary: GlossaryProvenance;
 }
 /**
- * Load and validate the verbatra configuration, returning provenance alongside it: which source it was
- * loaded from ({@link ConfigSource}), and whether its glossary is absent, inline, or resolved from a
- * file ({@link GlossaryProvenance}). {@link loadConfig} is a thin wrapper that returns only the
- * `config` field; use this directly when the provenance is needed (for example, to display it or to
- * re-resolve a glossary file relative to the same base directory).
+ * Loads and validates the project config, and additionally reports where it came from and where its
+ * glossary came from. Use this over {@link loadConfig} when a tool needs to show the user which
+ * config file is in effect, or to distinguish an inline glossary from a glossary file.
  *
- * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, an explicit `configPath`,
- *   or a `fs` seam override.
- * @returns The resolved {@link VerbatraConfig}, its {@link ConfigSource}, and its {@link GlossaryProvenance}.
- * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
- *   does not exist.
- * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
- *   its glossary file path could not be read as a valid, UTF-8, flat string record (a raw error never
- *   escapes).
+ * Resolution order is: an explicit `configOverride`, then an explicit `configPath`, then a
+ * cosmiconfig search upward from `cwd` across `verbatra.config.ts`, the `.verbatrarc` family, and a
+ * `verbatra` property in `package.json`. A `configPath` that does not exist is an error rather than
+ * a fallback to searching, so a typo in a path never silently loads a different project's config.
+ *
+ * A glossary given as a path is read and validated here, so the returned config always carries a
+ * resolved term map.
+ *
+ * @param options - Where and how to look for the config.
+ * @returns The validated config with its config-source and glossary provenance.
+ *
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit
+ * `configPath` does not exist.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the config could not be loaded or fails validation, or
+ * its glossary file is missing, oversized, not UTF-8, not valid JSON, or not a flat string map.
  */
 declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<LoadedConfig>;
 /**
- * Load and validate the verbatra configuration. Supports a code-defined
- * verbatra.config.ts and file-based configs (.verbatrarc.json/.yaml, package.json
- * property) through cosmiconfig + cosmiconfig-typescript-loader. Multiple sources ->
- * first-found-wins by cosmiconfig precedence. Any failure is a structured SdkError;
- * a raw zod error is never thrown upward and an unvalidated config never proceeds.
- *
- * Precedence: `configOverride` (validate in-memory) > `configPath` (load one explicit file) > search.
- *
- * A `glossary` given as a file path is read, parsed, and validated at load time (see
- * {@link loadConfigWithMeta} for its provenance); a relative path resolves against the loaded config
- * file's directory, or against `cwd` for a `configOverride`. Watch mode does not re-resolve a glossary
- * file on later edits; restart to pick up a change.
- *
- * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, or an explicit `configPath`.
- * @returns The validated {@link VerbatraConfig}.
- * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
- *   does not exist.
- * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
- *   its glossary file path could not be resolved (a raw error never escapes).
+ * Loads and validates the project config. This is the normal starting point for every SDK flow:
+ * pass the result to {@link translate}, {@link check}, {@link diff}, or any other entry point.
+ *
+ * Resolution order is an explicit `configOverride`, then an explicit `configPath`, then a
+ * cosmiconfig search upward from `cwd`. A glossary declared as a file path is read and validated
+ * here, so the returned {@link VerbatraConfig} always carries a resolved term map.
+ *
+ * Reach for {@link loadConfigWithMeta} when you also need to know which file was loaded.
+ *
+ * @param options - Where and how to look for the config.
+ * @returns The validated, fully resolved config.
+ *
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit
+ * `configPath` does not exist.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the config could not be loaded or fails validation, or
+ * its glossary file is missing, oversized, not UTF-8, not valid JSON, or not a flat string map.
+ *
  * @example
  * ```ts
  * import { loadConfig, translate } from "@verbatra/sdk";
  *
- * // Search upward from the cwd (verbatra.config.ts, .verbatrarc.json, or a package.json "verbatra" key):
  * const config = await loadConfig();
- * // Or load one explicit file (relative resolves against cwd; absolute as given):
- * // const config = await loadConfig({ configPath: "verbatra.config.ts" });
- *
  * const summary = await translate({ config });
+ * console.log(`${summary.succeeded.length} locales up to date`);
  * ```
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig>;
 
 /**
- * Structured, secret-free error codes for the SDK boundaries. A key never appears in
- * any message: provider/adapter/core errors are already secret-free, and the SDK never
- * reads or holds a key. Each names a distinct boundary:
+ * The stable, structured failure codes the SDK throws. Branch on {@link SdkError.code} rather than
+ * on a message; the messages are written for humans and are not part of the contract.
+ *
+ * A code never carries a secret. API keys are read from the environment by the providers alone, so
+ * the SDK never holds one, and provider, adapter, and core errors are secret-free before the SDK
+ * wraps them.
  *
- * - `CONFIG_NOT_FOUND`: no config was found by search, or an explicit `configPath` does not exist
- *   (thrown by `loadConfig`).
+ * - `CONFIG_NOT_FOUND`: no config file was found by search, or an explicit `configPath` does not
+ *   exist. Thrown by {@link loadConfig} and {@link loadConfigWithMeta}.
  * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or its glossary
- *   file path could not be resolved (thrown by `loadConfig`).
- * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by every entry
- *   point that selects an adapter, before any file is read).
- * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown via
- *   the shared locale selection by `check`, `diff`, `keyIntegrity`, `lockState`, `exportWorkbook`,
- *   `keyValue`, `editEntry`, and `retranslateEntry`).
- * - `UNKNOWN_KEY`: a requested key is not among the source resource's own keys (thrown by
- *   `keyValue`, `editEntry`, and `retranslateEntry`).
- * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error,
- *   including a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by non-dry-run
- *   `translate` and by `retranslateEntry`).
- * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by every entry point that reads
- *   the source, and by `watch` at startup).
- * - `SOURCE_INVALID`: the source locale file could not be read or parsed; wraps the adapter read
- *   error (thrown by every entry point that reads the source).
- * - `LOCK_FILE_INVALID`: the lock-file is present but corrupt, oversized, or at an unsupported
- *   version (thrown wherever the lock-file is read or updated: `translate`, `check`, `diff`,
- *   `keyIntegrity`, `lockState`, `loadLockFile`, `exportWorkbook`, `importWorkbook`, `editEntry`,
- *   and `retranslateEntry`).
- * - `LOCK_CONTENDED`: a locale's write lock (`withLocaleWriteLock`) could not be acquired before
- *   its timeout elapsed, because another process is holding it (or an orphaned lock file was left
- *   behind by a killed process); the message names the lock file's path (thrown by `translate`,
- *   `importWorkbook`, `editEntry`, and `retranslateEntry`).
+ *   file could not be resolved or parsed. Thrown by {@link loadConfig} and
+ *   {@link loadConfigWithMeta}. {@link importWorkbook} does not throw it: when a handoff sheet or
+ *   file names a locale that is not a configured target locale, it records this code on that
+ *   locale's {@link LocaleSummary} instead.
+ * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format. Thrown by every entry
+ *   point that selects an adapter, before any file is read.
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales. Thrown through
+ *   the shared locale selection by {@link check}, {@link diff}, {@link keyIntegrity},
+ *   {@link lockState}, {@link exportWorkbook}, {@link keyValue}, {@link editEntry}, and
+ *   {@link retranslateEntry}.
+ * - `UNKNOWN_KEY`: the requested key is not present in the source resource. Thrown by
+ *   {@link keyValue}, {@link editEntry}, and {@link retranslateEntry}.
+ * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw. Wraps the provider's own error,
+ *   including a missing `*_API_KEY` environment variable. Thrown by a non-dry-run
+ *   {@link translate} and by {@link retranslateEntry}.
+ * - `SOURCE_UNREADABLE`: the source locale file is absent. Thrown by every entry point that reads
+ *   the source, including {@link importWorkbook}, and by {@link watch} at startup.
+ *   {@link importWorkbook} additionally throws it when the handoff file itself is missing.
+ * - `SOURCE_INVALID`: the source locale file, or an interchange file, could not be parsed. Wraps
+ *   the adapter or reader error.
+ * - `LOCK_FILE_INVALID`: the lock-file exists but is corrupt, oversized, or at an unsupported
+ *   version. Thrown wherever the lock-file is read or updated: {@link translate}, {@link check},
+ *   {@link diff}, {@link keyIntegrity}, {@link lockState}, {@link loadLockFile},
+ *   {@link exportWorkbook}, {@link importWorkbook}, {@link editEntry}, and
+ *   {@link retranslateEntry}.
+ * - `LOCK_CONTENDED`: a locale's write lock could not be acquired before its timeout elapsed,
+ *   because another process holds it or a killed process left the lock file behind. The message
+ *   names the lock file's path. Thrown by {@link editEntry} and {@link retranslateEntry}, which
+ *   act on one locale. {@link translate} and {@link importWorkbook} do not throw it: they record it
+ *   on the contended locale's {@link LocaleSummary} and carry on with the other locales.
  * - `LOCALE_LAYOUT_INVALID`: the configured `files.pattern` and `files.localeStyle` cannot be
- *   combined (a segment style needs the `{locale}` token to stand alone between separators), or the
- *   declared style has no valid path spelling for a configured locale (`zh-Hans` under `posix`, for
- *   instance), or a locale expands to something that is not a single path segment. Thrown by
- *   `createLocalePathResolver`, and so by every entry point that resolves a locale to a path, before
- *   any file is read and before any provider call.
- * - `LOCALE_PATH_COLLISION`: two configured locales resolve to the same absolute file path, which
- *   would make the path-to-locale direction meaningless and would let two concurrent locale workers
- *   race on one file (thrown by `createLocalePathResolver`, at the same point as the above).
- * - `CONCURRENCY_INVALID`: the `concurrency` input is not an integer of at least 1 (thrown by
- *   `translate` and, per run, by `watch`, before any locale runs).
- * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested `concurrency` greater than 1 while a token
- *   budget (`maxTokens`) is configured; the two are mutually exclusive because concurrency makes the
- *   budget's stop guarantee nondeterministic (thrown by `translate` before any provider call; a dry
- *   run is exempt, since it never folds usage into or consults the budget tracker, so the conflict
- *   cannot arise).
- * - `LOCALE_FAILED` (NOT thrown): the fallback `code` recorded on a failed `LocaleSummary` when a
- *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction
- *   on `translate`.
+ *   combined, or the style has no valid path spelling for a configured locale. Thrown by
+ *   {@link createLocalePathResolver}, and so by every entry point that maps a locale to a path,
+ *   before any file is read and before any provider call.
+ * - `LOCALE_PATH_COLLISION`: two configured locales resolve to the same absolute path, which would
+ *   make the path-to-locale direction ambiguous and let two locale workers race on one file. Thrown
+ *   at the same point as `LOCALE_LAYOUT_INVALID`.
+ * - `CONCURRENCY_INVALID`: the `concurrency` input is not an integer of at least 1. Thrown by
+ *   {@link translate} before any locale runs, and by {@link watch} once at startup, before any
+ *   watching begins, since the value is fixed for the session rather than re-read per run.
+ * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested a `concurrency` above 1 while a token
+ *   budget is configured. The two are mutually exclusive because concurrency makes the budget's
+ *   stop guarantee nondeterministic. A dry run is exempt, since it never consults the budget.
+ * - `LOCALE_FAILED`: never thrown. It is the fallback code recorded on a failed
+ *   {@link LocaleSummary} when a per-locale failure carries no code of its own.
  */
 type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "UNKNOWN_KEY" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCK_CONTENDED" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "LOCALE_FAILED";
-/** The single structured error the SDK throws or records. Never carries a secret. */
+/**
+ * The single structured error the SDK throws. Every whole-run failure surfaces as an `SdkError`
+ * carrying a stable {@link SdkErrorCode}; per-locale failures, provider notices, and integrity
+ * findings are reported as data on the {@link RunSummary} instead of being thrown.
+ *
+ * An `SdkError` never carries a secret in its message.
+ */
 declare class SdkError extends Error {
-    /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
+    /** The stable {@link SdkErrorCode} for this failure. Branch on this, not on the message. */
     readonly code: SdkErrorCode;
     /**
      * @param code - The stable failure code.
-     * @param message - A fixed, secret-free message; the SDK never holds a key to put here.
+     * @param message - A human-readable description of the failure. Never contains a secret.
      */
     constructor(code: SdkErrorCode, message: string);
 }
 
-/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
+/**
+ * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
+ * member names the ecosystem it round-trips, not just a file extension, because several of them share
+ * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
+ * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
+ * `properties` (Java and Spring `.properties` files).
+ *
+ * The set is closed: a format outside it cannot be represented, so adding one means adding a member
+ * here and an adapter that claims it.
+ */
 declare const supportedFormatSchema: z.ZodEnum<{
     "i18next-json": "i18next-json";
     "vue-i18n-json": "vue-i18n-json";
@@ -703,12 +870,23 @@ declare const supportedFormatSchema: z.ZodEnum<{
     arb: "arb";
     properties: "properties";
 }>;
-/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
+/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
 type SupportedFormat = z.infer<typeof supportedFormatSchema>;
 
 /**
- * A single, format-neutral translation unit. Placeholders are supplied already
- * extracted; core never derives them from the value.
+ * A single, format-neutral translation unit. Placeholders are supplied already extracted; core never
+ * derives them from the value, so an adapter that reads a file is the one authority on what counts as
+ * a placeholder in that format.
+ *
+ * The fields are: `key`, the entry's identifier within its namespace, non-empty and already flattened
+ * to the dotted path an adapter produced; `namespace`, the namespace the entry belongs to, empty when
+ * the format has no namespacing; `value`, the translatable string itself, which is untrusted input and
+ * may be empty; `description` and `meaning`, both optional free-form context that a provider is told to
+ * use only for disambiguation and never to translate or echo back; `placeholders`, the format's
+ * placeholder tokens in document order, used for the output integrity check and to decide which entries
+ * a placeholder-blind provider must withhold; and `isPlural`, whether the entry carries plural forms
+ * (an i18next plural key suffix, a vue-i18n pipe-separated value, or an ICU plural), which the adapter
+ * decides and which feeds the content hash.
  */
 declare const translationEntrySchema: z.ZodObject<{
     key: z.ZodString;
@@ -719,23 +897,32 @@ declare const translationEntrySchema: z.ZodObject<{
     placeholders: z.ZodReadonly<z.ZodArray<z.ZodString>>;
     isPlural: z.ZodBoolean;
 }, z.core.$strip>;
-/** The validated shape of one translation unit; the inferred type of {@link translationEntrySchema}. */
+/**
+ * The validated shape of one translation unit; the inferred type of {@link translationEntrySchema},
+ * made deeply readonly. See that schema for what each field carries.
+ */
 type TranslationEntry = Readonly<z.infer<typeof translationEntrySchema>>;
-/** All translation entries for one locale and namespace, keyed by entry key. */
+
+/**
+ * All translation entries for one locale and namespace, keyed by entry key. This is the neutral
+ * intermediate representation every adapter reads into and writes back out of, so nothing downstream
+ * of an adapter parses a format's own syntax.
+ */
 interface LocaleResource {
     /** The locale these entries belong to (for example, "en" or "de"). */
     readonly locale: string;
-    /** The namespace these entries belong to. */
+    /** The namespace these entries belong to; empty when the format has no namespacing. */
     readonly namespace: string;
-    /** The source format the resource came from, for round-trip fidelity. */
+    /** The source format the resource came from, retained for round-trip fidelity on write. */
     readonly format: SupportedFormat;
-    /** Entries addressable by key. */
+    /** Entries addressable by key, in the order the source file defined them. */
     readonly entries: ReadonlyMap<string, TranslationEntry>;
 }
 
 /**
  * Result of comparing source placeholders against translated-output placeholders as MULTISETS
- * (counts matter). Always returned (never thrown) for an ordinary mismatch.
+ * (counts matter, so dropping one of two occurrences of the same token is still a miss). Always
+ * returned, never thrown: a mismatch is data the caller decides what to do about, not a failure.
  */
 interface PlaceholderIntegrityResult {
     /** True when nothing is missing or extra: the multisets match, regardless of order. */
@@ -744,17 +931,21 @@ interface PlaceholderIntegrityResult {
     readonly missing: readonly string[];
     /** Occurrences present in the translation but absent from source, one per surplus occurrence. Sorted. */
     readonly extra: readonly string[];
-    /** Same multiset present in both, but in a different order. */
+    /** Same multiset present in both, but in a different order. Never true alongside a mismatch. */
     readonly reordered: boolean;
 }
 
 /**
- * The result of reading a file into core's intermediate representation.
+ * The result of reading a file into core's intermediate representation. The two diagnostic lists are
+ * reported as data rather than thrown, so one bad leaf never fails a whole read.
  */
 interface ReadResult {
     /** The parsed locale resource. */
     readonly resource: LocaleResource;
-    /** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
+    /**
+     * Keys whose values are invalid for the format's message syntax. Empty for a format with no
+     * message-syntax check, which treats every value as valid.
+     */
     readonly invalidIcuKeys: readonly string[];
     /**
      * Dotted paths of leaves that were present in the source but excluded because they are not
@@ -768,22 +959,14 @@ interface ReadResult {
  * The contract every format adapter implements. A new format attaches by implementing this interface
  * and registering it in an {@link AdapterRegistry}.
  *
- * For a JSON-family format, implement via {@link createJsonFileAdapter} rather than from scratch. A
- * non-JSON format implements this interface directly and first needs its format added to core's
- * `SupportedFormat`.
- *
- * @example
- * ```ts
- * const registry = createDefaultRegistry();
- * const resolution = registry.resolve("locales/en.json", { format: "i18next-json" });
- * if (resolution.status === "resolved") {
- *   const { resource } = await resolution.adapter.read("locales/en.json", "en");
- *   await resolution.adapter.write(resource, "locales/en.json");
- * }
- * ```
+ * Implement it through one of `@verbatra/format-adapters`' shared factories rather than from
+ * scratch: `createTreeFileAdapter` for a nested-tree format (with `createJsonFileAdapter` as its
+ * JSON specialization) and `createFlatFileAdapter` for a flat key/value format. A format that fits
+ * neither shape implements this interface directly, and either way it first needs its member added
+ * to core's {@link SupportedFormat}.
  */
 interface FormatAdapter {
-    /** The single format this adapter handles (a `SupportedFormat` from core). */
+    /** The single format this adapter handles (a {@link SupportedFormat} from core). */
     readonly format: SupportedFormat;
     /**
      * Detect whether this adapter can handle a file, by path extension and an optional content sample.
@@ -801,7 +984,7 @@ interface FormatAdapter {
      * @param filePath - The file to read.
      * @param locale - The locale to tag the resource with.
      * @returns The parsed resource and the keys whose values are invalid for the format.
-     * @throws {@link AdapterError} when the content is malformed, oversized, or structurally invalid
+     * @throws `AdapterError` when the content is malformed, oversized, or structurally invalid
      *   (the implementation names the specific codes). A missing or unopenable path instead rejects with
      *   the underlying filesystem error.
      */
@@ -811,7 +994,7 @@ interface FormatAdapter {
      *
      * @param resource - The resource to serialize.
      * @param filePath - The destination file.
-     * @throws {@link AdapterError} if the resource cannot be represented in the format; rejects with the
+     * @throws `AdapterError` if the resource cannot be represented in the format; rejects with the
      *   underlying filesystem error on a write failure.
      */
     write(resource: LocaleResource, filePath: string): Promise<void>;
@@ -823,8 +1006,9 @@ interface FormatAdapter {
      */
     extractPlaceholders(value: string): readonly string[];
     /**
-     * Validate a single value against the format's message syntax before it is written. Non-ICU formats
-     * (i18next, vue-i18n, ngx-translate) treat every value as valid and return true.
+     * Validate a single value against the format's message syntax before it is written. Only the
+     * ICU-message formats carry a real check today (next-intl and ARB); every other adapter has no
+     * message syntax to violate and returns true for any value.
      *
      * @param value - The candidate translated value to validate.
      * @returns True when the value is valid for the format's message syntax. Does not throw; an
@@ -836,7 +1020,7 @@ interface FormatAdapter {
      * When present, callers use it instead of independently extracting each side's placeholders with
      * {@link extractPlaceholders} and diffing the flat lists, since flattening a plural/select value loses
      * which branch a placeholder came from. Absent for every non-ICU adapter, which is compared via
-     * `extractPlaceholders` plus `checkPlaceholders` as before.
+     * `extractPlaceholders` plus a flat multiset check as before.
      *
      * @param sourceValue - The source value.
      * @param targetValue - The translated value to check against it.
@@ -845,34 +1029,56 @@ interface FormatAdapter {
     comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
 }
 
-/** Outcome of resolving an adapter for a file. Structured; never throws. */
+/**
+ * Outcome of resolving an adapter for a file. Structured, never thrown: an unresolvable file is a
+ * status the caller branches on, not an exception.
+ *
+ * `resolved` carries the single {@link FormatAdapter} to use. `no-match` means nothing claimed the
+ * file, and reports the formats that were tried (every registered format for a detection attempt, or
+ * just the one requested when an explicit format was given). `ambiguous` means more than one adapter
+ * claimed the file, which is routine since every JSON adapter claims `.json`; it reports the competing
+ * candidates instead of guessing, and the caller resolves it by naming a format explicitly.
+ */
 type AdapterResolution = {
+    /** Exactly one adapter claimed the file. */
     readonly status: "resolved";
+    /** The adapter to read and write the file with. */
     readonly adapter: FormatAdapter;
 } | {
+    /** No registered adapter claimed the file. */
     readonly status: "no-match";
+    /** The file that could not be matched. */
     readonly filePath: string;
+    /**
+     * The formats that were tried: every registered format for a detection attempt, or just the
+     * one requested when an explicit format was given.
+     */
     readonly triedFormats: readonly SupportedFormat[];
 } | {
+    /** More than one adapter claimed the file, so detection cannot choose between them. */
     readonly status: "ambiguous";
+    /** The file that several adapters claimed. */
     readonly filePath: string;
+    /** The competing formats. Resolve the ambiguity by naming one of them explicitly. */
     readonly candidates: readonly SupportedFormat[];
 };
 /** Options for {@link AdapterRegistry.resolve}: select a format explicitly, or aid detection. */
 interface ResolveOptions {
-    /** A content sample to aid detection. */
+    /** A leading content sample to aid detection. Ignored when `format` is given. */
     readonly sample?: string;
     /** Bypass detection and select this format explicitly. */
     readonly format?: SupportedFormat;
 }
 /**
- * Holds the registered adapters and resolves one for a file. Open for extension:
- * adapters attach through register without changing resolution logic.
+ * Holds the registered adapters and resolves one for a file. Open for extension: adapters attach
+ * through {@link AdapterRegistry.register} without changing resolution logic, and resolution never
+ * throws.
  */
 declare class AdapterRegistry {
     private readonly adapters;
     /**
-     * Register an adapter.
+     * Register an adapter. Registration order is the order detection consults them, and a format may be
+     * registered more than once, in which case an explicit-format lookup takes the first.
      *
      * @param adapter - The adapter to add.
      * @returns This registry, for chaining.
@@ -880,11 +1086,6 @@ declare class AdapterRegistry {
     register(adapter: FormatAdapter): this;
     private formats;
     private resolveByFormat;
-    /**
-     * Resolve by asking every registered adapter's `canHandle`. Several adapters can claim one file
-     * (all JSON adapters claim `.json`), so more than one match is reported as `ambiguous` rather
-     * than guessed at.
-     */
     private resolveByDetection;
     /**
      * Resolve the adapter for a file, by explicit format when given, otherwise by detection.
@@ -897,1447 +1098,1571 @@ declare class AdapterRegistry {
     resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
 }
 
-/** Per-locale drift status: counts only, no key lists. */
+/** One locale's counts in a {@link CheckSummary}. */
 interface LocaleCheckSummary {
-    /** The target locale this entry reports on. */
+    /** The target locale these counts describe. */
     readonly locale: string;
-    /** Keys present in source but absent from the target. */
+    /** Number of source keys with no translation in this locale yet. */
     readonly missing: number;
-    /** Keys whose source changed since the target was last translated. */
+    /** Number of keys whose source text changed since the locale was last translated. */
     readonly stale: number;
-    /** Keys whose recorded baseline still matches the source. */
+    /** Number of keys whose translation still matches the source recorded in the lock-file. */
     readonly upToDate: number;
-    /** True when nothing needs (re)translating for this locale. */
+    /** True when this locale has nothing missing and nothing stale. */
     readonly inSync: boolean;
 }
-/** The aggregate read-only status across all checked target locales. */
+/** The result of {@link check}: per-locale counts plus one project-wide verdict. */
 interface CheckSummary {
-    /** True only when every checked locale is in sync. */
+    /** True only when every reported locale is in sync. This is the value a CI gate should assert on. */
     readonly inSync: boolean;
-    /** One entry per checked target locale, in config order. */
+    /** Per-locale counts, in configured target order. */
     readonly locales: readonly LocaleCheckSummary[];
 }
-/** Input for {@link check}: the validated config and which locales to check. */
+/** Input for {@link check}. */
 interface CheckInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** Subset of target locales to check; defaults to all configured target locales. */
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
 }
-/** Composition seam for {@link check}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link check}. Every field has a working default. */
 interface CheckDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Reports how many keys are missing or stale per target locale, without calling a provider, writing
- * any file, or touching the lock. Each locale is reported as counts only (missing, stale,
- * up-to-date); a locale is `inSync` when nothing is missing or stale, and the top-level `inSync` is
- * true only when every checked locale is. Orphaned keys and integrity are not reported, since they
- * concern a write; use {@link diff} for the key lists.
+ * Reports whether every target locale is up to date, without writing anything and without calling
+ * the provider. This is the CI gate: run it on a pull request and fail the build when
+ * {@link CheckSummary.inSync} is false.
  *
- * @param input - The validated config and which locales to check.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The aggregate and per-locale drift status.
- * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
- *   among the configured target locales.
+ * Staleness is judged against the lock-file baseline, not against the target file's mere existence,
+ * so a key whose source text changed after it was translated counts as stale even though a
+ * translation is present. A locale file that does not exist yet is treated as empty rather than as
+ * an error, so a newly added locale reports every key as missing.
+ *
+ * Use {@link diff} instead when you need the key names rather than the counts.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
+ *
+ * @param input - The config and the optional locale filter.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns Per-locale counts and the project-wide in-sync verdict.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
-/** Per-locale pending change: the key lists, not counts. */
+/** One locale's pending work in a {@link DiffSummary}, as key names rather than counts. */
 interface LocaleDiff {
-    /** The target locale this entry reports on. */
+    /** The target locale this entry describes. */
     readonly locale: string;
-    /** Keys present in source but absent from the target; would be added by a run. */
+    /** Keys present in the source but absent from this locale. */
     readonly missing: readonly string[];
-    /** Keys whose source changed since last translated; would be re-translated. */
+    /** Keys whose source text changed since this locale was last translated. */
     readonly changed: readonly string[];
-    /** Keys present in target but absent from source; report-only, never pending. */
+    /**
+     * Keys present in this locale but no longer in the source. They are reported, never removed,
+     * unless a run is asked to prune.
+     */
     readonly orphaned: readonly string[];
-    /** True when the locale has missing or changed keys; orphaned keys do not count. */
+    /**
+     * True when this locale has missing or changed keys. Orphaned keys alone do not count as pending,
+     * because they need no translation work.
+     */
     readonly hasPendingChanges: boolean;
 }
-/** The aggregate read-only diff across all checked target locales. */
+/** The result of {@link diff}: per-locale key lists plus one project-wide verdict. */
 interface DiffSummary {
-    /** True when any checked locale has pending changes. */
+    /** True when any locale has missing or changed keys. */
     readonly hasPendingChanges: boolean;
-    /** One entry per checked target locale, in config order. */
+    /** Per-locale key lists, in configured target order. */
     readonly locales: readonly LocaleDiff[];
 }
-/** Input for {@link diff}: the validated config and which locales to diff. */
+/** Input for {@link diff}. */
 interface DiffInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** Subset of target locales to diff; defaults to all configured target locales. */
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
 }
-/** Composition seam for {@link diff}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link diff}. Every field has a working default. */
 interface DiffDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Reports the exact pending change per target locale as three key lists (missing, changed,
- * orphaned), without calling a provider, writing any file, or touching the lock. The detailed
- * sibling of {@link check}. A locale's `hasPendingChanges` is driven by missing or changed only;
- * orphaned keys are reported but do not flip it, since a default `translate` run does not prune.
- * The top-level `hasPendingChanges` is true when any checked locale has pending changes.
+ * Reports the per-locale drift between the source and each target locale as key names, without
+ * writing anything and without calling the provider. It answers "what exactly would a run change",
+ * where {@link check} answers "is anything pending at all".
+ *
+ * The comparison runs against the lock-file baseline, so `changed` means the source text moved
+ * since the key was last translated rather than merely that the two strings differ. Orphaned keys
+ * are reported but never removed here; pruning happens only in {@link translate}.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
  *
- * @param input - The validated config and which locales to diff.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The aggregate and per-locale pending change.
- * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
- *   among the configured target locales.
+ * @param input - The config and the optional locale filter.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns Per-locale missing, changed, and orphaned key lists.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
-/** Why {@link gateCandidateValue} rejected a candidate value. */
+/**
+ * Why a candidate translation was refused before it could be written. The same gate guards
+ * {@link editEntry} and {@link retranslateEntry}, so a hand-typed value and a provider-produced one
+ * are held to identical standards.
+ *
+ * A rejected value is never written to the locale file and never recorded in the lock-file, so the
+ * previous translation stays intact.
+ *
+ * - `placeholder`: the candidate does not carry the same placeholders as the source, so
+ *   interpolation would break at runtime.
+ * - `icu`: the candidate is not a valid ICU message under the configured format's adapter.
+ * - `degenerate`: the candidate collapsed into runaway output rather than a translation. Two shapes
+ *   are detected: the candidate is at least twelve times the length of a source of meaningful
+ *   length, or a short unit repeats consecutively enough to dominate the value. An untranslated
+ *   echo of the source is not degenerate by this rule; it surfaces as the `EQUALS_SOURCE` review
+ *   reason instead, which flags rather than refuses.
+ * - `empty`: the source has text but the candidate is blank, which would silently erase a string.
+ */
 type IntegrityGateReason = "placeholder" | "icu" | "degenerate" | "empty";
 
-/** Input for {@link editEntry}: the validated config, exactly one target locale/key pair, and the human-typed replacement value. */
+/** Input for {@link editEntry}. */
 interface EditEntryInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** The target locale to write the correction into. Must be a configured target locale. */
+    /** The target locale to write to. Must be a configured target locale. */
     readonly locale: string;
-    /** The source key being corrected. Must exist in the source resource. */
+    /** The key to edit. Must exist in the source resource. */
     readonly key: string;
-    /** The human-typed replacement value. */
+    /** The new translation. It is accepted only if it passes the integrity gate. */
     readonly value: string;
 }
-/** Composition seam for {@link editEntry}: inject a registry and a file system for tests. No provider builder: this seam never calls a provider. */
+/** Injectable dependencies for {@link editEntry}. Every field has a working default. */
 interface EditEntryDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * The two-armed result of one edit attempt: acceptance carries the newly written value; a
- * rejection carries the candidate value and which {@link gateCandidateValue} check failed it,
- * with nothing written. Deliberately has no review-reasons field: a human-typed correction never
- * touches a provider, so there is no provider-derived review signal to report.
+ * The outcome of {@link editEntry}. A rejection is data rather than an exception, because a value
+ * that fails the integrity gate is an expected editing outcome that a UI needs to explain, not a
+ * failure of the call.
  */
 type EditEntryResult = {
+    /** The value passed the integrity gate and was written. */
     readonly accepted: true;
+    /** The value now stored for the key. */
     readonly value: string;
 } | {
+    /** The value was refused; nothing was written and the previous translation is intact. */
     readonly accepted: false;
+    /** Which integrity rule the value broke. */
     readonly reason: IntegrityGateReason;
+    /** The rejected value, echoed back so a UI can show what was refused. */
     readonly value: string;
 };
 /**
- * Writes exactly one human-typed correction for exactly one target locale, gated through the
- * shared {@link gateCandidateValue} before anything reaches disk. On acceptance, writes the target
- * locale file (merging just this one key into its current entries, every other key untouched) and
- * updates the lock entry for this key only (see {@link updateLockFileLocale}'s `"merge"` mode); on
- * rejection, writes nothing. Never calls a provider: {@link EditEntryDeps} has no provider seam,
- * so there is no way to construct or call one. On acceptance it also feeds the accepted value into
- * the local translation-memory cache (best-effort, keyed by the source content hash and the config
- * fingerprint), so a later run can reuse it for free; a cache failure is swallowed and never fails
- * the edit.
- *
- * `locale` and `key` are resolved fresh on every call, never from a cache: `locale` against
- * `config.targetLocales`, `key` against the source resource read fresh from disk.
- *
- * The target-file write and the lock-file update run inside one held `withLocaleWriteLock`
- * critical section, so no second writer for this locale can observe the target file updated but
- * the lock entry not yet, or vice versa. Reading the source, resolving the key, and selecting the
- * adapter stay outside the lock: they are read-only and need no protection.
- *
- * Never touches `.verbatra-local/run-status.json`: that file is rewritten wholesale by
- * `translate()`/`watch()` outside any locale lock, so patching it here would race that rewrite. A
- * key edited here stays stale in that persisted snapshot until the next real run, which self-heals
- * it since this call already advanced the lock hash.
- *
- * @param input - The validated config, the target locale, the source key, and the replacement value.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The two-armed {@link EditEntryResult}.
+ * Saves a manually edited translation for a single key. This is the write path behind a review UI:
+ * a human corrects one string and it is persisted without re-running the whole project.
+ *
+ * The edit is held to the same integrity gate as a provider translation, so a value that drops a
+ * placeholder, breaks ICU syntax, runs away into a hugely oversized or repetition-dominated value,
+ * or blanks a non-empty string is refused. A refusal comes back as `accepted: false` rather than as
+ * a thrown error, and nothing is written.
+ *
+ * The locale's write lock is taken for the whole read-modify-write, so an edit cannot interleave
+ * with a concurrent {@link translate} run on the same locale. The gate runs inside that lock, so a
+ * refused edit takes and releases the lock as well and can therefore fail with `LOCK_CONTENDED`
+ * even though it would have written nothing. An accepted edit then updates the lock-file baseline
+ * and feeds the translation memory, which means a later run treats the key as up to date and
+ * reuses the edited text rather than paying the provider to translate it again.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
+ *
+ * @param input - The config, locale, key, and new value.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns Whether the value was accepted, and on rejection the reason.
+ *
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
- * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
- * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
- *   or unreadable.
- * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: the requested locale is not a configured target locale.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or the locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
+ * the timeout elapsed.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
- *   unsupported version.
- * @throws {@link SdkError} `LOCK_CONTENDED`: this locale's write lock could not be acquired before
- *   its timeout, because another process is holding it.
+ * unsupported version.
  */
 declare function editEntry(input: EditEntryInput, deps?: EditEntryDeps): Promise<EditEntryResult>;
 
-/**
- * One key's placeholder and ICU integrity result for one target locale. Only ever computed for a
- * "changed" key (a current source and a current target value both exist). `hasPlaceholders` is
- * false when the source value carries no placeholders, in which case `matches` is trivially true
- * and carries no signal on its own. `icuValid` is computed unconditionally, independent of
- * `matches`: unlike `gateCandidateValue`, which stops at the first failing check, this is an
- * information report and stays accurate even when the key already fails on placeholders; it is
- * always true for a non-ICU format. Carries no source or target string value: only the boolean
- * results and, on a placeholder mismatch, the specific tokens involved.
- */
+/** One key's placeholder and ICU verdict in a {@link LocaleKeyIntegrity} report. */
 interface KeyIntegrityEntry {
+    /** The key this verdict describes. */
     readonly key: string;
+    /** Whether the source text contains any placeholders at all. When false, `matches` is trivially true. */
     readonly hasPlaceholders: boolean;
+    /** True when the translation carries exactly the source's placeholders. */
     readonly matches: boolean;
+    /** Placeholders present in the source but absent from the translation. */
     readonly missing: readonly string[];
+    /** Placeholders present in the translation but not in the source. */
     readonly extra: readonly string[];
+    /** True when the translation parses as a valid ICU message under the configured format. */
     readonly icuValid: boolean;
 }
-/** One target locale's integrity entries for the keys checked against it. */
+/** One locale's per-key integrity verdicts. */
 interface LocaleKeyIntegrity {
+    /** The target locale these verdicts describe. */
     readonly locale: string;
+    /** Verdicts for the changed keys that exist in both the source and this locale. */
     readonly entries: readonly KeyIntegrityEntry[];
 }
-/** Input for {@link keyIntegrity}: the validated config, which locales to check, and an optional key filter. */
+/** Input for {@link keyIntegrity}. */
 interface KeyIntegrityInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** Subset of target locales to check; defaults to all configured target locales. */
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
-    /** Restrict the check to these keys; only the ones that are "changed" for a locale are checked. Defaults to every changed key. */
+    /** Restrict the report to these keys. Defaults to every key the diff reports as changed. */
     readonly keys?: readonly string[];
 }
-/** Composition seam for {@link keyIntegrity}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link keyIntegrity}. Every field has a working default. */
 interface KeyIntegrityDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Runs the placeholder check and the ICU message-validity check for each selected target locale's
- * "changed" keys (present with a current value on both sides, per core's `diffResources`) and
- * reports a per-key result. Uses the adapter's own `comparePlaceholders` when present (the
- * branch-aware ICU path), otherwise core's `checkPlaceholders` over the stored placeholder lists.
- * `icuValid` is `adapter.validateMessage(target)`, computed unconditionally and independently of
- * the placeholder result, so a target that is placeholder-valid but syntactically invalid ICU is
- * still reported accurately. Read-only: it calls no provider, writes no file, and never touches
- * the lock. Missing and orphaned keys are never checked, since one side's value does not exist for
- * those.
+ * Reports, per changed key, whether the existing translation still carries the source's
+ * placeholders and still parses as valid ICU. It writes nothing and calls no provider.
+ *
+ * The scope is deliberately the changed keys rather than every key: a key whose source text has not
+ * moved was already gated when it was written, so re-reporting it would bury the keys that a source
+ * edit may have just invalidated. Only keys present in both the source and the target are judged,
+ * since a missing translation has no placeholders to compare.
+ *
+ * This is the read-only counterpart to the gate that {@link editEntry} and
+ * {@link retranslateEntry} enforce at write time, and the data behind a review dashboard's
+ * per-key integrity indicator.
  *
- * The returned entries never carry a source or target string value, only the boolean results and,
- * on a placeholder mismatch, the specific tokens involved.
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
  *
- * @param input - The validated config, which locales to check, and an optional key filter.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns One entry per checked locale, each carrying the integrity result for its changed keys
- *   (narrowed to `input.keys` when supplied).
- * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`,
- *   `LOCK_FILE_INVALID`, or `UNKNOWN_LOCALE`, with the same meanings as in {@link diff}.
+ * @param input - The config and the optional locale and key filters.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns One entry per requested locale, each holding its per-key verdicts.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  */
 declare function keyIntegrity(input: KeyIntegrityInput, deps?: KeyIntegrityDeps): Promise<readonly LocaleKeyIntegrity[]>;
 
-/** Input for {@link keyValue}: the validated config and exactly one target locale/key pair. */
+/** Input for {@link keyValue}. */
 interface KeyValueInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern resolves against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** The target locale to read the current translation from. Must be a configured target locale. */
+    /** The target locale to read the translation from. Must be a configured target locale. */
     readonly locale: string;
-    /** The source key to read. Must exist in the source resource. */
+    /** The key to read. Must exist in the source resource. */
     readonly key: string;
 }
-/** Composition seam for {@link keyValue}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link keyValue}. Every field has a working default. */
 interface KeyValueDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
-/**
- * The current source and target values for one key/locale pair. `target` is absent exactly when
- * the key does not yet exist in that target locale; a present-but-empty-string target is a real
- * value and is returned as such.
- */
+/** One key's current source and target text, as returned by {@link keyValue}. */
 interface KeyValueResult {
+    /** The key's text in the source locale. Always present, since a missing key is an error. */
     readonly source: string;
+    /** The key's text in the requested target locale, or absent when it has not been translated yet. */
     readonly target?: string;
 }
 /**
- * Reads a key's current source and target values for exactly one target locale. Read-only: it
- * calls no provider, writes no file, and mutates nothing. Exposes only the current values on disk,
- * never a previous one.
+ * Reads one key's current source and target text. It writes nothing and calls no provider, and is
+ * the read half of the single-key editing flow that {@link editEntry} and
+ * {@link retranslateEntry} complete.
+ *
+ * The two sides are asymmetric on purpose: a key absent from the source is an error, because it
+ * cannot be edited or retranslated, while a key absent from the target is normal and simply comes
+ * back with no `target`.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
  *
- * `locale` and `key` are resolved fresh on every call, so a caller feeding an edit dialog with
- * this result and then submitting through `editEntry` is always working from live data, never a
- * cached snapshot.
+ * @param input - The config, locale, and key to read.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns The key's source text and, when present, its current translation.
  *
- * @param input - The validated config, the target locale, and the source key to read.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The current source value and, when present, the current target value.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
- * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
- * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
- *   or unreadable.
- * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: the requested locale is not a configured target locale.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or the locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
  */
 declare function keyValue(input: KeyValueInput, deps?: KeyValueDeps): Promise<KeyValueResult>;
 
 /**
- * One locale file reduced to a content hash per key, taken at one point in time. Two snapshots of
- * the same file can be compared with {@link diffLocaleSnapshots} to count what changed between
- * them.
+ * One locale file reduced to a per-key content hash. Holding hashes rather than values keeps a
+ * long-lived watcher's memory flat in the size of the translations and makes comparison a cheap
+ * equality check.
  */
 interface LocaleFileSnapshot {
-    /** The locale this snapshot was read for (the configured source locale or a target locale). */
+    /** The locale this snapshot was taken for. */
     readonly locale: string;
-    /** Content hash per key, from core's `contentHash`. */
+    /** Content hash per key, in the order the adapter read them. */
     readonly hashes: ReadonlyMap<string, string>;
 }
-/** Input for {@link readLocaleFileSnapshot}: the validated config and which locale to snapshot. */
+/** Input for {@link readLocaleFileSnapshot}. */
 interface ReadLocaleFileSnapshotInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** The locale to snapshot: the configured source locale or any configured target locale. */
+    /**
+     * The locale file to snapshot. Unlike most entry points this is not checked against the
+     * configured target locales, so the source locale can be snapshotted too.
+     */
     readonly locale: string;
-    /** Directory the file pattern resolves against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
 }
-/** Composition seam for {@link readLocaleFileSnapshot}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link readLocaleFileSnapshot}. Every field has a working default. */
 interface ReadLocaleFileSnapshotDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Reads one locale file through the configured adapter and reduces it to a content hash per key.
- * Uses the same tolerant read path as {@link readTarget}: a file that does not exist yet reads as
- * an empty snapshot rather than throwing, so a caller can establish a baseline before a locale's
- * first write.
+ * Reads one locale file as a per-key content hash. Together with {@link diffLocaleSnapshots} this
+ * is the building block for a live-refresh watcher: hold a snapshot, re-read on a file event, and
+ * compare the two to learn what actually changed.
+ *
+ * A locale file that does not exist yet reads as an empty snapshot rather than an error, so a
+ * watcher can start before the first translation run has written anything.
+ *
+ * Note that this entry point does not validate the locale against the configured targets, and that
+ * a malformed target file surfaces the adapter's own parse error rather than a wrapped
+ * {@link SdkError}, because no source-file contract is being asserted here.
  *
- * @param input - The validated config, the locale to snapshot, and the directory to resolve against.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The locale's per-key content hash snapshot.
- * @throws {@link SdkError} `UNKNOWN_FORMAT` when the configured format has no registered adapter;
- *   rejects with the adapter's own error when the file exists but its content is malformed.
+ * @param input - The config and the locale to snapshot.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns The locale's per-key content hashes.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
  */
 declare function readLocaleFileSnapshot(input: ReadLocaleFileSnapshotInput, deps?: ReadLocaleFileSnapshotDeps): Promise<LocaleFileSnapshot>;
-/** A locale file's added, changed, and removed key counts between two of its own snapshots. Counts only, never key names. */
+/** How many keys were added, changed, and removed between two {@link LocaleFileSnapshot}s. */
 interface LocaleSnapshotDelta {
+    /** Keys present in the current snapshot but not the previous one. */
     readonly added: number;
+    /** Keys present in both snapshots whose content hash differs. */
     readonly changed: number;
+    /** Keys present in the previous snapshot but not the current one. */
     readonly removed: number;
 }
 /**
- * Compares two snapshots of the same locale file, taken at different points in time, and counts
- * how many keys were added, changed, or removed. A direct key-to-hash comparison rather than
- * core's `diffResources`: that function's source/target/baseline shape exists for cross-resource
- * comparison, and forcing a same-file, two-points-in-time comparison through it would need a
- * confusing relabeling (missing becomes removed, orphaned becomes added).
+ * Compares two {@link LocaleFileSnapshot}s and counts what moved. It is pure, synchronous, and
+ * touches no file system, so a watcher can call it on every file event without cost.
  *
- * @param previous - The earlier snapshot of the file.
- * @param current - The later snapshot of the same file.
- * @returns The counts of keys added, changed, and removed between the two snapshots.
+ * The two snapshots are compared by key and content hash alone; neither the locale names nor the
+ * order are consulted, so passing snapshots of two different locales compares them rather than
+ * failing.
+ *
+ * @param previous - The earlier snapshot.
+ * @param current - The later snapshot.
+ * @returns The added, changed, and removed key counts.
  */
 declare function diffLocaleSnapshots(previous: LocaleFileSnapshot, current: LocaleFileSnapshot): LocaleSnapshotDelta;
 
-/** Per-locale key count and drift against the source and target files, from the recorded lock baseline. */
+/** One locale's lock-file baseline and the drift measured against it. */
 interface LockLocaleState {
-    /** The target locale this entry reports on. */
+    /** The target locale this entry describes. */
     readonly locale: string;
-    /** Number of keys the lock records a baseline for, in this locale. */
+    /** How many keys the lock-file records a baseline hash for in this locale. */
     readonly keyCount: number;
-    /** Keys present in source but absent from the target. */
+    /** Number of source keys with no translation in this locale yet. */
     readonly missing: number;
-    /** Keys whose source changed since the target was last translated. */
+    /** Number of keys whose source text changed since the recorded baseline. */
     readonly stale: number;
-    /** Keys whose recorded baseline still matches the source. */
+    /** Number of keys whose translation still matches the recorded baseline. */
     readonly upToDate: number;
 }
 /**
- * The lock-file's existence, version, and per-locale drift. `exists` is the outcome of an explicit
- * probe of the lock-file path, never inferred from {@link readLockFile}'s missing-file degrade, so
- * "no lock-file yet" and "an empty but present lock-file" stay distinguishable.
+ * The result of {@link lockState}. The absence of a lock-file is a first-class state rather than an
+ * error, because a project that has never been translated legitimately has none.
  */
 type LockStateResult = {
+    /** No lock-file exists yet, so there is no baseline to report against. */
     readonly exists: false;
 } | {
+    /** A lock-file exists and was read successfully. */
     readonly exists: true;
+    /** The lock-file's schema version. */
     readonly version: number;
+    /** Per-locale baseline sizes and drift, in configured target order. */
     readonly locales: readonly LockLocaleState[];
 };
-/** Input for {@link lockState}: the validated config and which locales to report on. */
+/** Input for {@link lockState}. */
 interface LockStateInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** Subset of target locales to report on; defaults to all configured target locales. */
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
 }
-/** Composition seam for {@link lockState}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link lockState}. Every field has a working default. */
 interface LockStateDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Report the lock-file's existence, version, and per-locale drift (key count from the recorded
- * baseline, plus missing, stale, and up-to-date counts against the current source and target),
- * without calling a provider, writing any file, or mutating the lock. `exists` comes from an
- * explicit probe of the lock-file path: when it is absent, the result is `{ exists: false }` and
- * no source or target file is read, since there is no recorded baseline to report drift against.
+ * Reports the lock-file's existence, version, and the per-locale drift measured against its
+ * baseline. It writes nothing and calls no provider.
+ *
+ * Where {@link check} answers "is the project in sync", this answers "what does the lock-file
+ * actually record", which is what a diagnostic view needs when the two disagree: a locale with
+ * translations present but a `keyCount` of zero, for instance, means the files were written outside
+ * verbatra and have no baseline.
+ *
+ * When no lock-file exists the call returns `exists: false` rather than throwing, and does no
+ * further reading.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
+ *
+ * @param input - The config and the optional locale filter.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns The lock-file's version and per-locale baseline state, or `exists: false`.
  *
- * @param input - The validated config and which locales to report on.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns The lock-file's existence and, when present, its version and per-locale drift.
- * @throws {@link SdkError} `UNKNOWN_LOCALE` when a requested locale is not among the configured
- *   target locales; when the lock-file exists, also `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`,
- *   `SOURCE_INVALID`, or `LOCK_FILE_INVALID` with the same meanings as in `translate`.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
  */
 declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
 
-/** Builds the provider from its config. Injectable so tests stay offline. */
+/**
+ * Builds a {@link TranslationProvider} from the config's `provider` block. Passed as
+ * `deps.createProvider` to {@link translate}, {@link watch}, and {@link retranslateEntry}, it is the
+ * seam for injecting a stub in a test or a provider the SDK does not ship.
+ *
+ * The default implementation dispatches on the provider ID and reads the API key from the
+ * environment. A factory that throws is reported as `PROVIDER_CONSTRUCTION_FAILED`.
+ */
 type CreateProvider = (config: ProviderConfig) => TranslationProvider;
 
-/** Input for {@link retranslateEntry}: the validated config and exactly one target locale/key pair. */
+/** Input for {@link retranslateEntry}. */
 interface RetranslateEntryInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** The target locale to retranslate the key into. Must be a configured target locale. */
+    /** The target locale to retranslate into. Must be a configured target locale. */
     readonly locale: string;
-    /** The source key to retranslate. Must exist in the source resource. */
+    /** The key to retranslate. Must exist in the source resource. */
     readonly key: string;
 }
-/** Composition seam for {@link retranslateEntry}: inject a registry, a provider builder, and a file system for tests. */
+/** Injectable dependencies for {@link retranslateEntry}. Every field has a working default. */
 interface RetranslateEntryDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** Provider factory. Defaults to constructing the provider named in the config. */
     readonly createProvider?: CreateProvider;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * The two-armed result of one retranslate attempt: `accepted` carries the newly written value and
- * any derived "needs review" reasons; a rejection carries the candidate value and which
- * {@link gateCandidateValue} check failed it, without writing anything.
+ * The outcome of {@link retranslateEntry}. As with {@link EditEntryResult}, a value refused by the
+ * integrity gate is reported as data rather than thrown, because it is an expected outcome of
+ * asking a provider for a fresh translation.
  */
 type RetranslateEntryResult = {
+    /** The provider's value passed the integrity gate and was written. */
     readonly accepted: true;
+    /** The newly translated value now stored for the key. */
     readonly value: string;
+    /**
+     * Quality signals the provider layer raised for this value, such as a length-ratio outlier or
+     * a value identical to the source. Empty when nothing was flagged. The value is written
+     * either way; these are advisory.
+     */
     readonly reviewReasons: readonly ReviewReasonCode[];
 } | {
+    /** The value was refused; nothing was written and the previous translation is intact. */
     readonly accepted: false;
+    /** Which integrity rule the provider's value broke. */
     readonly reason: IntegrityGateReason;
+    /** The rejected value, echoed back so a UI can show what was refused. */
     readonly value: string;
 };
 /**
- * Retranslate exactly one key for exactly one target locale: a single-entry `translateBatch` call
- * through the same provider registry `translate()` uses, gated through the shared
- * {@link gateCandidateValue} before anything reaches disk. On acceptance, writes the target locale
- * file (merging just this one key into its current entries, every other key untouched) and updates
- * the lock entry for this key only (see {@link updateLockFileLocale}'s `"merge"` mode); on rejection,
- * writes nothing. Reuses exactly the building blocks `translate()` already uses
- * (`selectProvider`/`provider.translateBatch`) and nothing else: no bespoke per-provider plumbing.
- * Always calls the provider (it never consults the cache for a hit, since its whole purpose is a
- * fresh translation), then feeds the accepted value into the translation-memory cache best-effort so
- * a later run can reuse it; a cache failure is swallowed and never fails the retranslate.
- *
- * `locale` and `key` are resolved fresh on every call, never cached: `locale` against
- * `config.targetLocales` (`UNKNOWN_LOCALE`), `key` against the source resource's own keys, read
- * fresh from disk (`UNKNOWN_KEY`), via a `Map`-backed lookup, never `key in obj` or
- * `obj[key] !== undefined` against a plain object.
- *
- * The target-file write and the lock-file update run inside the same held
- * `withLocaleWriteLock(cwd, locale, fs, ...)` critical section as the provider call itself, so no
- * second writer for this locale can ever observe the target file updated but the lock entry not
- * yet, or vice versa. The same locking also covers `translate()`/`watch()` and `importWorkbook()`.
- *
- * Not atomic across the two writes for a single caller's own run: the target locale file is
- * written before the lock entry is updated. If `updateLockFileLocale` then throws
- * (`LOCK_FILE_INVALID` for a corrupt lock-file, or `LOCK_CONTENDED` if its own internal lock-file
- * guard cannot be acquired before its timeout), the target file already carries the new value
- * while the lock still records the old hash, and the thrown error does not imply nothing was
- * saved. The same ordering, and the same partial-write shape on that rare path, also exists in
- * `translate()` and `importWorkbook()`.
- *
- * @param input - The validated config, the target locale, and the source key to retranslate.
- * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
- * @returns The two-armed {@link RetranslateEntryResult}.
+ * Re-runs the configured provider for a single key and saves the result. This is the paid
+ * counterpart to {@link editEntry}: it calls the provider and therefore spends tokens, which is why
+ * a UI should gate it behind an explicit user action.
+ *
+ * The returned value goes through the same integrity gate as a full run, so a translation that
+ * loses a placeholder or breaks ICU syntax is refused and nothing is written. Provider quality
+ * signals are surfaced on an accepted result as `reviewReasons` rather than blocking the write.
+ *
+ * The locale's write lock is taken before the provider is called and held across it, covering the
+ * whole read-translate-write cycle, so a slow provider keeps the lock for the length of its call
+ * and a concurrent {@link translate} run on that locale waits. The lock is held for a refused
+ * translation too, since the gate runs inside it. An accepted value then updates the lock-file
+ * baseline and feeds the translation memory, so a later {@link translate} run sees the key as up
+ * to date.
+ *
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
+ *
+ * @param input - The config, locale, and key to retranslate.
+ * @param deps - Optional adapter registry, provider factory, and file-system overrides.
+ * @returns Whether the new value was accepted, with review reasons or the rejection reason.
+ *
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
- * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locale` is not among `config.targetLocales`.
- * @throws {@link SdkError} `SOURCE_UNREADABLE` / `SOURCE_INVALID`: the source locale file is absent
- *   or unreadable.
- * @throws {@link SdkError} `UNKNOWN_KEY`: `key` does not exist in the source resource.
- * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw (wraps a
- *   missing `*_API_KEY` as `MISSING_API_KEY`).
- * @throws {@link ProviderError} the provider call itself failed, or returned no value at all for
- *   this key (`INVALID_RESPONSE`).
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: the requested locale is not a configured target locale.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or the locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
+ * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider could not be constructed,
+ * most often because its API key environment variable is unset.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
+ * the timeout elapsed.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
- *   unsupported version.
- * @throws {@link SdkError} `LOCK_CONTENDED`: this locale's write lock could not be acquired before
- *   its timeout, because another process (another CLI run, or a second Studio write) is holding it.
+ * unsupported version.
+ * @throws `ProviderError` `INVALID_RESPONSE`: the provider returned no value for the key. Provider
+ * transport and rate-limit failures propagate as `ProviderError` too, since a single-key call has
+ * no per-locale summary to record them on.
  */
 declare function retranslateEntry(input: RetranslateEntryInput, deps?: RetranslateEntryDeps): Promise<RetranslateEntryResult>;
 
-/** A stable code for an SDK-originated notice (not a provider notice). */
+/**
+ * Conditions the SDK itself reports on a locale, as opposed to the {@link ProviderNotice} codes a
+ * provider raises. Each marks a run that completed but did something a caller may want to know
+ * about.
+ *
+ * - `PLURAL_CATEGORIES_INCOMPLETE`: plural generation could not produce every category the target
+ *   language requires, so the entry is written with the categories that were produced.
+ * - `SUB_BATCH_FAILED`: one sub-batch of a locale failed while others succeeded. The locale is
+ *   reported as `partial` rather than failed.
+ * - `BLANK_ROW_BASELINE_RETAINED`: an imported handoff row was blank, so the existing translation
+ *   and its lock-file baseline were kept rather than being erased.
+ * - `BUDGET_TOKENS_EXCEEDED`: the configured token budget was passed. Under `warn` the run
+ *   continues; under `stop` the remaining keys are withheld.
+ * - `CACHE_VERSION_UNRECOGNIZED`: the translation memory is at a version this release does not
+ *   understand, so it was ignored rather than trusted.
+ */
 type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED" | "CACHE_VERSION_UNRECOGNIZED";
-/** Summed token usage across every provider call in a scope (one locale, or the whole run). */
+/**
+ * Token usage as reported by the provider. Absent when the provider does not report usage, which is
+ * the case for machine-translation APIs such as DeepL that do not bill in tokens.
+ */
 interface UsageSummary {
+    /** Tokens consumed by the prompts sent to the provider. */
     readonly inputTokens: number;
+    /** Tokens consumed by the provider's responses. */
     readonly outputTokens: number;
 }
-/** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
-type BudgetBehavior = "warn" | "stop";
 /**
- * The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
- * `supported: false` means the configured provider never reported usage in this run (a token-less
- * provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
- * `exceeded` stays `false`, never a false trip.
+ * What a run does when it passes its token budget: `warn` finishes the work and reports the
+ * overrun, `stop` withholds the remaining keys.
  */
+type BudgetBehavior = "warn" | "stop";
+/** The token budget in force for a run, and how much of it was actually consumed. */
 interface RunBudget {
-    /** The configured ceiling. */
+    /** The configured ceiling, in tokens. */
     readonly maxTokens: number;
-    /** The configured behavior once the ceiling is reached. */
+    /** Whether passing the ceiling warns or stops the run. */
     readonly behavior: BudgetBehavior;
-    /** Whether the configured provider reported usage at all this run. */
+    /**
+     * Whether the configured provider reports usage at all. When false the budget cannot be enforced,
+     * because there is nothing to count.
+     */
     readonly supported: boolean;
-    /** Cumulative input plus output tokens across the run so far. */
+    /** Tokens consumed across the whole run so far. */
     readonly tokensUsed: number;
-    /** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
+    /** True once `tokensUsed` passed `maxTokens`. */
     readonly exceeded: boolean;
 }
-/**
- * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
- * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
- * secret-free message; never a key value or translatable content.
- */
+/** A condition the SDK reported on a locale. See {@link SdkNoticeCode}. */
 interface SdkNotice {
-    /** The stable {@link SdkNoticeCode} for what the SDK is reporting. */
+    /** The stable notice code. Branch on this, not on the message. */
     readonly code: SdkNoticeCode;
-    /** A static, safe description; never a key or translatable content. */
+    /** A human-readable description of the condition. */
     readonly message: string;
 }
-/** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
+/**
+ * Any notice attached to a locale: either one the provider raised, such as a downgraded formality
+ * or an ignored glossary, or one the SDK raised. Discriminate on `code`.
+ */
 type LocaleNotice = ProviderNotice | SdkNotice;
-/** One key flagged for human review, and every reason code that applies to it. */
+/**
+ * A translated key the provider layer flagged as worth a human look. The translation was still
+ * written; these are advisory quality signals, not rejections.
+ */
 interface NeedsReviewEntry {
-    /** The flagged key. */
+    /** The key that was flagged. */
     readonly key: string;
-    /** Every {@link ReviewReasonCode} that applies to this key. */
+    /** Why it was flagged. A key can carry more than one reason. */
     readonly reasons: readonly ReviewReasonCode[];
 }
-/**
- * One row a workbook import could not read: the 1-based row number, the file line for a delimited
- * import, and the header label of the offending column. Carries no cell content, so untrusted workbook
- * text never reaches the summary.
- */
+/** A row of an imported handoff that could not be read. Reported rather than aborting the import. */
 interface MalformedRowReport {
-    /** The 1-based worksheet row number of the malformed row. */
+    /** The row's 1-based index within its sheet or file. */
     readonly row: number;
     /**
-     * The 1-based file line the malformed record starts on. Present only for a delimited (csv or tsv)
-     * import; an xlsx workbook has rows rather than lines. See {@link DuplicateKeyReport.line} for why
-     * both numbers are reported.
+     * The 1-based physical line in the source file, for delimited formats where a quoted value can
+     * span several lines. Absent for `.xlsx`, which has rows but no lines.
      */
     readonly line?: number;
-    /** The header label of the column the row was rejected on (for example "Status"). */
+    /** The column whose value was missing or unusable. */
     readonly column: string;
 }
 /**
- * One duplicate-key conflict a workbook import found in a locale's sheet: the duplicated key and the
- * 1-based worksheet row number of the later (losing) occurrence. The first occurrence is the winner.
+ * A key that appeared more than once in an imported handoff. The first occurrence wins and the rest
+ * are reported here, so a translator who duplicated a row learns which value was actually used.
  */
 interface DuplicateKeyReport {
-    /** The key that appeared more than once in the locale's sheet. */
+    /** The key that appeared more than once. */
     readonly key: string;
-    /** The 1-based worksheet row number of the later occurrence that lost to the first. */
+    /** The 1-based row index of the ignored occurrence. */
     readonly row: number;
-    /**
-     * The 1-based file line this later occurrence starts on. Present only for a delimited (csv or tsv)
-     * import.
-     *
-     * A delimited record holding a quoted line break covers one spreadsheet row but several editor
-     * lines, so `row` is the number a translator sees in a spreadsheet and `line` the one they see in a
-     * text editor. Both are reported so the position holds whichever tool they opened the file in.
-     */
+    /** The 1-based physical line of the ignored occurrence, for delimited formats. Absent for `.xlsx`. */
     readonly line?: number;
 }
-/** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
+/**
+ * Everything that happened for one locale during a run. The key lists are disjoint accounts of what
+ * became of each key, so a caller can reconstruct the whole run without re-reading any file.
+ *
+ * A locale that failed outright still appears here with `status: "failed"` and an `error`, rather
+ * than the whole run throwing. That is the central contract of {@link translate}: one unreachable
+ * provider or one unwritable file does not discard the locales that succeeded.
+ */
 interface LocaleSummary {
-    /** The target locale this summary is for. */
+    /** The target locale this summary describes. */
     readonly locale: string;
     /**
-     * This locale's honest run status (a non-success does not abort the run). `"succeeded"` when
-     * nothing was withheld, including a genuine no-op with no candidate keys at all. `"partial"` when
-     * at least one key was accepted and written (a {@link LocaleSummary.translated} key or a
-     * {@link LocaleSummary.generated} plural form) but at least one was withheld (any of
-     * {@link LocaleSummary.integrityMismatches}, {@link LocaleSummary.providerFailures}, or
-     * {@link LocaleSummary.budgetWithheld} non-empty). `"failed"` when the locale had candidate keys
-     * but accepted nothing at all (neither translated nor generated) while withholding at least one.
-     * Withheld keys keep their prior lock hash and retry next run.
-     *
-     * A workbook import's structural findings, {@link LocaleSummary.unfilled},
-     * {@link LocaleSummary.malformedRows}, and {@link LocaleSummary.duplicateKeys}, deliberately do NOT
-     * feed this status: they are surfaced in their own lists (and the CLI) but are not withholdings of
-     * an attempted translation, so a locale that dropped a malformed row, collapsed a duplicate key, or
-     * left a row unfilled while accepting its other rows can still be `"succeeded"`.
-     *
-     * This is a settled decision, not an omission. Recording the reasoning here so the question stops
-     * recurring:
-     *
-     * 1. Two questions, two commands. `import`'s exit code answers "did the import apply what the
-     *    translator gave me". `check` and `diff` answer "is this project fully translated", and both
-     *    already exit non-zero or report pending in every one of these cases. Folding pending human
-     *    work into the import exit code duplicates an existing gate rather than adding one.
-     * 2. It would break the staged handoff. With `de` and `fr` configured and only `de` filled in,
-     *    failing on unfilled work makes `fr` fail and takes the whole import with it, even though `de`
-     *    imported perfectly. Locale-at-a-time handoff is this feature's most common workflow.
-     * 3. {@link LocaleSummary.malformedRows} structurally cannot signal lost work. The Status column is
-     *    the only reachable rejection in the workbook reader; every other field is an unconstrained
-     *    string or a tolerant parse. So a row is malformed on its Status cell alone, entirely
-     *    independently of whether its Translation cell was filled. An untouched sheet with a mangled
-     *    Status column (spreadsheet autocorrect, a CAT-tool round trip) is all-malformed with zero lost
-     *    work. A bucket that cannot distinguish dropped work from absent work cannot honestly drive a
-     *    failure status.
-     * 4. {@link LocaleSummary.duplicateKeys} never could: the first occurrence wins and the intent is
-     *    honoured.
+     * `succeeded` when everything asked for was done, `partial` when some keys were translated and
+     * others were not, and `failed` when the locale produced no usable result.
      */
     readonly status: "succeeded" | "partial" | "failed";
-    /**
-     * Keys translated and written this run. In dry-run, the keys that would be translated
-     * (the provider is not called and nothing is written).
-     */
+    /** Keys newly translated by the provider in this run. */
     readonly translated: readonly string[];
-    /** Keys already up to date, left unchanged this run. */
+    /** Keys already up to date against the lock-file baseline, so no provider call was made. */
     readonly unchanged: readonly string[];
-    /** Target keys with no corresponding source key (candidates for removal). Reported regardless of pruning. */
+    /** Keys present in this locale but no longer in the source. Reported, and removed only when pruning. */
     readonly orphaned: readonly string[];
-    /**
-     * Orphaned keys actually removed this run because pruning was on. In a dry-run with pruning on, the keys
-     * that would be removed. Empty when pruning is off (the orphans then survive and are reported in
-     * `orphaned` only). A subset of `orphaned`; never includes a source-present key.
-     */
+    /** Orphaned keys that were actually removed, which happens only when the run was asked to prune. */
     readonly pruned: readonly string[];
-    /** Source keys flagged invalid-ICU that were skipped for translation this run. */
-    readonly invalidIcuSource: readonly string[];
     /**
-     * Keys served from the local translation-memory cache instead of the provider: their source content
-     * was unchanged (possibly under a renamed key or shared with another key) and the cached value passed
-     * the integrity gate, so no provider request was made for them. They are written and lock-advanced
-     * exactly like a translated key, but kept distinct from {@link LocaleSummary.translated} because they
-     * cost no provider usage. Always present, empty by default; empty in a dry-run and when the cache is
-     * bypassed. Sorted by key.
+     * Keys whose source text is not valid ICU. They are skipped rather than sent to the provider,
+     * because a broken source message cannot yield a sound translation.
      */
+    readonly invalidIcuSource: readonly string[];
+    /** Keys served from the translation memory instead of the provider, and so not paid for. */
     readonly cacheHits: readonly string[];
     /**
-     * Translated keys that failed the placeholder-integrity check and were withheld. Never includes a
-     * key withheld because the provider call itself failed; see {@link LocaleSummary.providerFailures}
-     * for that case.
+     * Keys whose translation was refused by the integrity gate, for instance because it dropped a
+     * placeholder. The previous translation, if any, is left untouched.
      */
     readonly integrityMismatches: readonly string[];
-    /**
-     * Keys withheld because nothing was translated for them this run, as distinct from a translation
-     * that came back and failed the placeholder-integrity check. This covers two causes: the provider
-     * call itself failed (for example a revoked API key, a rate limit, or a network timeout), in which
-     * case the corresponding {@link LocaleSummary.notices} entry carries the secret-free failure code
-     * and message; or the call succeeded but the key was still missing or duplicated in the response
-     * after the shared LLM layer's bounded reconcile repair round, in which case no notice is added.
-     * Empty in a dry-run.
-     */
+    /** Keys the provider failed to translate, for instance because their sub-batch errored. */
     readonly providerFailures: readonly string[];
-    /**
-     * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
-     * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
-     * and acted, and empty in a dry-run.
-     */
+    /** Keys whose plural categories were generated for the target language rather than translated one by one. */
     readonly generated: readonly string[];
-    /**
-     * Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
-     * in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
-     * candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
-     * {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
-     * its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
-     */
+    /** Keys not translated because the token budget was exhausted under `stop` behavior. */
     readonly budgetWithheld: readonly string[];
-    /**
-     * Summed token usage across every provider call for this locale (main translation plus plural
-     * generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
-     * (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
-     */
+    /** Token usage for this locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
-    /**
-     * Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
-     * (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
-     * nothing was degraded or flagged.
-     */
+    /** Provider and SDK notices raised while running this locale. Always present, possibly empty. */
     readonly notices: readonly LocaleNotice[];
-    /**
-     * Keys accepted and written this run that the review heuristics flagged for a second look, sorted
-     * by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
-     * withholds a key, so this never double-reports a key already surfaced through
-     * {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
-     * nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
-     * flags on its own path).
-     */
+    /** Translated keys flagged as worth a human look. The translations were still written. */
     readonly needsReview: readonly NeedsReviewEntry[];
-    /**
-     * Keys the translator left blank that still need a translation, drifted or not, sorted by key.
-     * Pending work made visible: the row is skipped (nothing is written and the prior lock baseline is
-     * kept), but the key is surfaced so an unfinished import is never silently reported as done. Only a
-     * workbook import populates this; the provider path, which never leaves a candidate key unfilled by
-     * a person, always leaves it empty.
-     *
-     * Membership is decided by the import-time diff, not by the `status` the row was exported with: a
-     * never-translated key exports as `new`, and a first handoff is all-new, which is the most common
-     * unfilled case there is. A row exported as `changed` whose key no longer needs work by import time
-     * is correspondingly excluded.
-     */
+    /** Keys left with no translation after the run, whatever the cause. */
     readonly unfilled: readonly string[];
-    /**
-     * Rows a workbook import could not read for this locale, each by worksheet row number and offending
-     * column, in row order. The sheet's other rows still import; a malformed row is reported, not
-     * written. Only a workbook import populates this; the provider path always leaves it empty.
-     */
+    /** Unreadable rows from an imported handoff. Always empty for a {@link translate} run. */
     readonly malformedRows: readonly MalformedRowReport[];
-    /**
-     * Duplicate-key conflicts a workbook import found in this locale's sheet, in row order. The rule is
-     * first occurrence wins: the first row for a key is judged and its later occurrences are reported
-     * here and otherwise ignored. Only a workbook import populates this; the provider path always leaves
-     * it empty.
-     */
+    /** Repeated keys from an imported handoff. Always empty for a {@link translate} run. */
     readonly duplicateKeys: readonly DuplicateKeyReport[];
     /**
-     * A structured, secret-free error for a locale that threw (an adapter/lock/provider-construction
-     * failure isolated as data): present only on a "failed" locale, and only that throw path sets it.
-     * A locale that is "failed" because every candidate key was withheld (all under `providerFailures`,
-     * `integrityMismatches`, or `budgetWithheld`) carries those lists and any notices instead, and has
-     * no `error`. `code` is a preserved string (the underlying provider/adapter error's `code`, or
-     * `"LOCALE_FAILED"` as a fallback), intentionally wider than {@link SdkErrorCode}, so do not treat
-     * it as a closed set.
+     * Why this locale failed, when the failure came from a thrown error. The `code` is the failure's
+     * own code where it has one, and `LOCALE_FAILED` otherwise. Never carries a secret.
+     *
+     * Absent unless `status` is `failed`, but a `failed` locale does not always carry it: a locale
+     * whose every key was withheld by the integrity gate, a provider failure, or the token budget is
+     * `failed` with nothing thrown, so this stays undefined and the withheld keys are the account of
+     * what went wrong. Treat it as an optional detail on a failure, never as the failure test.
      */
     readonly error?: {
+        /** The failure's own code where it had one, and `LOCALE_FAILED` otherwise. */
         readonly code: string;
+        /** A human-readable description of the failure. Never contains a secret. */
         readonly message: string;
     };
 }
-/** The aggregate result of a run across all target locales. */
+/**
+ * The result of a whole run, returned by {@link translate}, {@link watch}, and
+ * {@link importWorkbook}.
+ *
+ * Per-locale outcomes are data, not exceptions: inspect `failed` and `partial` to decide an exit
+ * code rather than relying on the call to throw. Only whole-run failures, such as an invalid config
+ * or an unreadable source file, throw an {@link SdkError}.
+ */
 interface RunSummary {
-    /** Whether this was a dry-run (no provider calls, no writes). */
+    /** True when the run computed everything but wrote nothing and called no provider. */
     readonly dryRun: boolean;
-    /** One {@link LocaleSummary} per target locale, in config order. */
+    /** The full per-locale account, in configured target order. */
     readonly locales: readonly LocaleSummary[];
-    /** Locales whose run succeeded with nothing withheld (status `"succeeded"`). */
+    /** Names of the locales whose status is `succeeded`. */
     readonly succeeded: readonly string[];
-    /**
-     * Locales that wrote at least one translation but withheld at least one candidate key (status
-     * `"partial"`). A partial locale still exits the CLI `0`: it made progress, and its withheld keys
-     * retry next run. Never overlaps `succeeded` or `failed`.
-     */
+    /** Names of the locales whose status is `partial`. */
     readonly partial: readonly string[];
-    /** Locales whose run failed, having accepted nothing (status `"failed"`; see each locale's `error`). */
+    /** Names of the locales whose status is `failed`. Check this before treating a run as clean. */
     readonly failed: readonly string[];
-    /**
-     * Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
-     * run reported usage (a dry-run, or an all-token-less-provider run).
-     */
+    /** Token usage summed across every locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
-    /** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
+    /** The token budget in force, present only when the config set one. */
     readonly budget?: RunBudget;
 }
 
 /**
- * One target locale's snapshot inside the persisted run-status file. `status` is carried over from
- * `LocaleSummary.status` unchanged, so an empty `needsReview` on a failed or partial locale is never
- * misread as "this locale ran clean with nothing to review".
+ * One locale's entry in a persisted {@link RunStatusFile}. It is a deliberately narrow projection
+ * of {@link LocaleSummary}: only the parts a later session still needs, namely the outcome, the
+ * review flags, and the cost.
  */
 interface RunStatusLocale {
+    /** The target locale this entry describes. */
     readonly locale: string;
+    /** How the locale finished in the recorded run. */
     readonly status: "succeeded" | "partial" | "failed";
-    /** The full, unmodified list from `LocaleSummary.needsReview`; already bounded and content-free. */
+    /** Keys the run flagged as worth a human look. */
     readonly needsReview: readonly NeedsReviewEntry[];
-    /** Absent exactly when the source `LocaleSummary.usage` was absent; never a fabricated zero. */
+    /** Token usage for this locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
 }
 /**
- * The persisted shape of `.verbatra-local/run-status.json`: one whole-run snapshot, overwritten on
- * every non-dry-run `translate()`/`watch()` run that reaches the end of its per-locale loop. Contains
- * only the review-flag and token/usage data already computed for `RunSummary`; never a translation
- * string, a provider error message, or a provider notice message.
+ * The snapshot a completed non-dry-run writes to `.verbatra-local/run-status.json`, read back by
+ * {@link runStatus}. It lets a tool started after the run, such as a dashboard opened once
+ * translation finished, still show what was flagged and what it cost.
+ *
+ * It is local state, not project state: unlike the lock-file it is not meant to be committed, and
+ * losing it costs nothing beyond that history.
  */
 interface RunStatusFile {
+    /** The status-file schema version. A file at an unrecognized version is ignored rather than trusted. */
     readonly version: number;
-    /** ISO timestamp of when this snapshot was written. */
+    /** When the run finished, as an ISO 8601 timestamp. */
     readonly generatedAt: string;
-    /** Summed run-wide token usage, mirroring `RunSummary.usage`; absent under the same conditions. */
+    /** Token usage summed across every locale. Absent when the provider does not report usage. */
     readonly usage?: UsageSummary;
-    /** The run-wide token-budget outcome, mirroring `RunSummary.budget`; present only when configured. */
+    /** The token budget in force during the run, present only when one was configured. */
     readonly budget?: RunBudget;
+    /** Per-locale outcomes from the recorded run. */
     readonly locales: readonly RunStatusLocale[];
 }
 
-/** Input for {@link runStatus}: the persisted file is self-contained, so no `config` is needed. */
+/** Input for {@link runStatus}. */
 interface RunStatusInput {
-    /** Directory the run-status file resolves against; defaults to cwd. */
+    /** Directory holding the `.verbatra-local` status directory. Defaults to the process working directory. */
     readonly cwd?: string;
 }
-/** Composition seam for {@link runStatus}: inject a file system for tests. */
+/** Injectable dependencies for {@link runStatus}. Every field has a working default. */
 interface RunStatusDeps {
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * The persisted run-status snapshot, or its absence. `available: false` covers a project that has
- * never run a non-dry-run `translate()`/`watch()`, exactly like every other degrade case
- * {@link runStatus} folds into it: never a distinct error, so a caller does not need to special-case
- * "first run" apart from "corrupt file" apart from "unrecognized version".
+ * The result of {@link runStatus}. Having no readable status file is a normal state, not an error:
+ * it simply means no non-dry-run has completed in this directory yet.
  */
 type RunStatusResult = {
+    /** No usable status file was found, so there is nothing to report. */
     readonly available: false;
 } | ({
+    /** A status file was found and parsed; the {@link RunStatusFile} fields are spread alongside. */
     readonly available: true;
 } & RunStatusFile);
 /**
- * Read the most recent run's persisted review-flag and token/usage snapshot from
- * `.verbatra-local/run-status.json`, without calling a provider, writing any file, or mutating the
- * lock-file. Never throws: a missing file, invalid JSON, a schema mismatch, or an unrecognized
- * `version` all degrade to `{ available: false }`, since this file is best-effort telemetry, not a
- * correctness baseline (contrast {@link lockState}, which can throw `LOCK_FILE_INVALID`).
+ * Reads the review-flag and token-usage snapshot that the last non-dry-run {@link translate} or
+ * {@link watch} left behind in `.verbatra-local/run-status.json`. It writes nothing and calls no
+ * provider.
+ *
+ * This exists so a tool started after a run, such as a dashboard opened once translation finished,
+ * can still show which keys were flagged for review and what the run cost, without re-running
+ * anything.
+ *
+ * The read is deliberately total: a missing, oversized, unparseable, schema-invalid, or
+ * wrong-version file all report `available: false` rather than throwing, because stale local status
+ * should never break the tool reading it. This call throws nothing.
  *
- * @param input - Only the directory the file resolves against; no config is needed.
- * @param deps - Optional composition seam (file system) for tests.
- * @returns `{ available: false }`, or `{ available: true, ...the persisted fields }`.
+ * @param input - The optional working directory.
+ * @param deps - Optional file-system override.
+ * @returns The persisted run status, or `available: false` when none is usable.
  */
 declare function runStatus(input?: RunStatusInput, deps?: RunStatusDeps): Promise<RunStatusResult>;
 
-/** Diagnostic details, read leniently from a held lock file, about the process currently holding it. */
+/**
+ * Whatever could be read about the process currently holding a write lock. Both fields are optional
+ * because a lock file left behind by a killed process may be truncated or unreadable, and reporting
+ * a partial holder is more useful than reporting none.
+ */
 interface LockHolder {
-    /** The holder's process id, when the lock file could be read and carried a numeric `pid`. */
+    /** The process ID recorded when the lock was taken. */
     readonly pid?: number;
-    /** The holder's acquire time as an ISO-8601 string, when the lock file carried a string `acquiredAt`. */
+    /** When the lock was taken, as an ISO 8601 timestamp. */
     readonly acquiredAt?: string;
 }
-/** One wait-progress notification emitted while an acquire is blocked on a held lock. */
+/**
+ * Reported while a run waits for another process to release a locale's write lock. It exists so a
+ * CLI or UI can explain a stall rather than appearing to hang, and can name the lock file a user
+ * may need to delete after a crash.
+ */
 interface LockWaitEvent {
-    /** The on-disk path of the contended lock file, the exact path a person can delete if it is orphaned. */
+    /** Absolute path of the lock file being waited on. */
     readonly lockPath: string;
-    /** Milliseconds elapsed since this acquire started waiting, for a "still waiting" progress line. */
+    /** How long this acquisition has been waiting, in milliseconds. */
     readonly elapsedMs: number;
-    /**
-     * Diagnostics about the holding process, present only when the lock file could be read and parsed.
-     * Purely for messaging; never consulted for any acquire decision.
-     */
+    /** What is known about the holding process, when anything could be read. */
     readonly holder?: LockHolder;
 }
-/** Called while an acquire is blocked, to surface wait progress; the lock module itself writes no output. */
+/**
+ * Called on each poll while waiting for a locale's write lock. Passed as `onLockWait` to
+ * {@link translate} and {@link watch}.
+ */
 type LockWaitListener = (event: LockWaitEvent) => void;
 
 /**
- * One structured progress notification emitted while a run advances through its locales and their
- * provider sub-batches. Emitted to a caller-supplied {@link ProgressListener}; the SDK itself writes
- * nothing to any stream, so a caller (the CLI) is free to render these to stderr and keep stdout a
- * clean summary or NDJSON stream. Discriminated on `type`, mirroring the lock-wait event contract.
+ * Any event a run emits while it works. Discriminate on `type`. Progress is reported rather than
+ * printed so that a CLI, a dashboard, and a CI log can each render it in their own way.
  */
 type ProgressEvent = LocaleStartedEvent | SubBatchProgressEvent | LocaleFinishedEvent | RunFinishedEvent;
-/** A locale is about to be processed: its position in the run's target-locale order. */
+/** Emitted when a locale's work begins. */
 interface LocaleStartedEvent {
+    /** Discriminant for {@link ProgressEvent}. */
     readonly type: "locale-started";
-    /** The target locale about to run. */
+    /** The locale starting. */
     readonly locale: string;
-    /** Zero-based index of this locale in the run's target-locale order. */
+    /**
+     * This locale's 0-based position among the run's locales. With concurrency above 1 several
+     * locales are in flight at once, so these indices do not arrive in order.
+     */
     readonly localeIndex: number;
-    /** Total number of target locales in this run. */
+    /** How many locales the run covers in total. */
     readonly totalLocales: number;
 }
 /**
- * One sub-batch of a locale's main translation loop has been reached. Emitted once per loop
- * iteration, in order, so a caller can render a "batch N of M" line. Fired at the top of the
- * iteration regardless of whether the batch then makes a provider call: a budget-withheld batch
- * (the run's token budget already tripped) still emits this event, which keeps `batchIndex` 1-based
- * and contiguous against the total. A dry-run never reaches this loop and so never emits it.
+ * Emitted as each sub-batch of a locale is reached, immediately before the provider call for it is
+ * attempted. Large locales are split into batches, so this is the finer-grained signal to drive a
+ * progress bar with.
+ *
+ * It announces an attempt rather than confirming a send: a batch withheld because the token budget
+ * has already stopped the run still emits, and no provider call follows it. That is deliberate, so
+ * that `batchIndex` always advances to `totalBatches` and a progress bar reaches its end instead of
+ * stalling at the point the budget tripped.
  */
 interface SubBatchProgressEvent {
+    /** Discriminant for {@link ProgressEvent}. */
     readonly type: "sub-batch";
-    /** The locale whose entries this sub-batch carries. */
+    /** The locale this batch belongs to. */
     readonly locale: string;
-    /** One-based index of this sub-batch within the locale. */
+    /** This batch's 1-based position within the locale, counting up to `totalBatches`. */
     readonly batchIndex: number;
-    /** Total number of sub-batches this locale's main translation loop runs. */
+    /** How many batches the locale was split into. */
     readonly totalBatches: number;
 }
-/** A locale finished processing: how many keys it accepted (translated). */
+/** Emitted when a locale's work ends, whether it succeeded, partially succeeded, or failed. */
 interface LocaleFinishedEvent {
+    /** Discriminant for {@link ProgressEvent}. */
     readonly type: "locale-finished";
-    /** The target locale that finished. */
+    /** The locale that finished. */
     readonly locale: string;
-    /** Number of keys accepted (translated) for this locale. In a dry-run, the keys that would be translated. */
+    /** How many keys were newly translated for this locale. */
     readonly translated: number;
-    /**
-     * Zero-based index of this locale in the run's target-locale order, carrying the same value as the
-     * matching {@link LocaleStartedEvent}. This is a correlation key, so a consumer can pair a finish
-     * with its start without matching on the locale name.
-     *
-     * It is deliberately NOT a progress counter. The worker pool claims indices up front, so this is a
-     * claim ordinal rather than a completion ordinal: under concurrency the locales finish in a
-     * different order, and rendering `localeIndex + 1` of `totalLocales` on a finish produces a
-     * counter that jumps around and never reaches its own total in order. Do not reintroduce one.
-     */
+    /** This locale's 0-based position among the run's locales. */
     readonly localeIndex: number;
-    /** Total number of target locales in this run, mirroring {@link LocaleStartedEvent}. */
+    /** How many locales the run covers in total. */
     readonly totalLocales: number;
 }
-/** The run reached the end of its locale loop: how many locales it processed. */
+/** Emitted once, after every locale has finished. */
 interface RunFinishedEvent {
+    /** Discriminant for {@link ProgressEvent}. */
     readonly type: "run-finished";
-    /**
-     * Number of locales the run processed (including failed locales: a per-locale failure is isolated
-     * as a summary rather than thrown, so it is still counted here).
-     */
+    /** How many locales completed, including those that failed. */
     readonly localesCompleted: number;
 }
 /**
- * Called with each {@link ProgressEvent} as a run advances; the SDK emits no output of its own. A
- * caller (the CLI) uses this to render progress, always to stderr, so stdout stays byte-identical to
- * a run with no listener attached.
+ * Called for each {@link ProgressEvent} a run emits. Passed as `onProgress` to {@link translate}
+ * and {@link watch}.
  */
 type ProgressListener = (event: ProgressEvent) => void;
 
-/** Everything the one-shot run needs: the validated config and where/how to run it. */
+/** Input for {@link translate}. Only `config` is required; every other field has a default. */
 interface TranslateInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to the current working directory. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** When true, read + diff + report only: the provider is never constructed or called and nothing is written. */
+    /**
+     * Compute the whole run but write nothing and call no provider. The returned
+     * {@link RunSummary} reports what would have happened, which makes this safe to run in CI to
+     * preview work without spending anything. Defaults to false.
+     */
     readonly dryRun?: boolean;
     /**
-     * When true, remove orphaned keys (target keys absent from source) from the written file and the lock.
-     * Off by default. When set, takes precedence over the config's `prune` option for this run; when unset,
-     * the config's `prune` applies. Only `diff.orphaned` keys are ever removed; no other key is touched.
+     * Remove keys that no longer exist in the source. Defaults to the config's `prune`, then to
+     * false, so orphaned keys are reported but kept unless removal is asked for explicitly.
      */
     readonly prune?: boolean;
     /**
-     * When true, synthesize the CLDR plural forms a richer target language requires but the source lacks
-     * (i18next-JSON + LLM providers only; every other case falls back to the existing warning). Off by
-     * default. When set, takes precedence over the config's `generatePlurals` option for this run; when
-     * unset, the config's `generatePlurals` applies.
+     * Generate the plural categories a target language requires rather than translating each
+     * category separately. Defaults to the config's `generatePlurals`, then to false.
      */
     readonly generatePlurals?: boolean;
     /**
-     * Called while a locale's write lock is blocked on another process holding it: once after the first
-     * failed acquire (with the holder's pid/acquiredAt when the lock file is readable), then periodically
-     * with the growing elapsed time. Never called for an uncontended run. The SDK writes no output; this
-     * is the only wait-progress signal (the CLI renders its "still waiting" line from it).
+     * Called while waiting on another process's write lock, so a CLI can explain a stall instead of
+     * appearing to hang.
      */
     readonly onLockWait?: LockWaitListener;
-    /**
-     * Called as the run advances: once per locale before it starts and once after it finishes, once
-     * per provider sub-batch within a locale, and once when the whole locale loop ends. Never fires a
-     * sub-batch event on a dry-run (no provider call is made). The SDK writes no output; this is the
-     * only progress signal (the CLI renders it to stderr, keeping stdout byte-identical).
-     *
-     * Pairing is not guaranteed when the run throws: a whole-run failure (for example a corrupt
-     * lock-file surfacing as `LOCK_FILE_INVALID`, which re-throws instead of being isolated per locale)
-     * can emit a `locale-started` event with no matching `locale-finished`, and no `run-finished` at
-     * all. A per-locale failure that is isolated (not re-thrown) still emits both, and is counted in
-     * `run-finished`.
-     */
+    /** Called as locales and sub-batches start and finish, for progress reporting. */
     readonly onProgress?: ProgressListener;
-    /**
-     * Override how long a locale's write lock keeps retrying before failing with `LOCK_CONTENDED`, in
-     * milliseconds. Defaults to the lock's own 10-minute default when unset (surfaced to the CLI as
-     * `--lock-timeout`).
-     */
+    /** How long to wait for a locale's write lock before failing with `LOCK_CONTENDED`. */
     readonly lockAcquireTimeoutMs?: number;
     /**
-     * How many target locales may run at once, a positive integer (surfaced to the CLI as
-     * `--concurrency`). Defaults to 1, which runs locales strictly in sequence and is byte-identical
-     * to a run with this option unset. A value below 1 or a non-integer is rejected with a whole-run
-     * `CONCURRENCY_INVALID` error. On a live run, a value greater than 1 is rejected with a whole-run
-     * `CONCURRENCY_BUDGET_CONFLICT` error when the config sets a `maxTokens` budget, because
-     * concurrency would make the budget's stop guarantee nondeterministic; a dry run is exempt. The
-     * per-locale write locks already isolate concurrent locales on disk, so no extra locking is added.
+     * How many locales to run at once. Must be an integer of at least 1; defaults to 1. On a live
+     * run it cannot be combined with a configured token budget, because concurrent locales would
+     * overshoot the budget nondeterministically.
      */
     readonly concurrency?: number;
     /**
-     * Whether to use the local content-addressed translation-memory cache (`verbatra.cache.json`). On by
-     * default; the CLI exposes it as `--no-cache`. When false, both the cache read and the end-of-run
-     * cache write are skipped: the run makes exactly the provider calls it would with no cache present,
-     * and leaves any existing cache file untouched. Ignored on a dry-run, which never reads or writes the
-     * cache regardless. See the cache module for the fingerprint and degrade-to-empty contract.
+     * Consult and update the translation memory. Defaults to true. Turning it off forces every key
+     * through the provider, which is what to do when you want to re-pay for a fresh translation.
      */
     readonly cache?: boolean;
 }
-/** Composition seam: inject a registry, a provider builder, and a file system for tests. */
+/** Injectable dependencies for {@link translate}. Every field has a working default. */
 interface TranslateDeps {
-    /** Adapter registry to resolve the format from; defaults to the built-in registry. */
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
-    /** Provider builder; defaults to constructing the configured provider (which reads its key from env). */
+    /** Provider factory. Defaults to constructing the provider named in the config. */
     readonly createProvider?: CreateProvider;
-    /** File system for existence checks and the lock-file; defaults to the real file system. */
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * The one-shot end-to-end translate flow. Whole-run failures (config already validated
- * by the caller, unknown format, provider construction, unreadable/invalid source,
- * corrupt lock-file) throw a structured SdkError. Per-locale failures are isolated: a
- * failing locale is reported and the run continues; the lock-file reflects exactly the
- * locales that succeeded. Dry-run reads + diffs + reports without constructing/calling
- * the provider and without writing any file or the lock-file.
- *
- * A per-locale failure does not throw: it is recorded on that locale's {@link LocaleSummary} as
- * `status: "failed"` with a secret-free `{ code, message }`, where `code` is a preserved string (the
- * underlying provider/adapter code, or `"LOCALE_FAILED"` as a fallback), not necessarily an
- * {@link SdkErrorCode}. DeepL notices, integrity mismatches, and invalid-ICU source keys likewise
- * surface on each `LocaleSummary`, never as throws.
- *
- * A dry-run reads the lock once, outside any lock, and reuses that one snapshot for every locale:
- * it never writes, so there is nothing to serialize against. A live run instead re-reads the lock
- * fresh inside each locale's own write lock (see `runLiveLocale`), so two concurrent live calls
- * never both diff against the same stale pre-loop snapshot. The token-budget tracker is fresh per
- * invocation: the `maxTokens` ceiling is per-run, not cumulative across watch cycles.
- *
- * On a non-dry-run that reaches the end of the loop, the run's review-flag and token/usage data is
- * also written to `.verbatra-local/run-status.json` (readable back through {@link runStatus}). This
- * write is best-effort: any failure is caught and swallowed, never re-thrown and never reflected on
- * the returned {@link RunSummary}.
- *
- * @param input - The validated config and run options (cwd, dryRun, prune, generatePlurals).
- * @param deps - Optional composition seams (registry, provider builder, file system) for tests.
- * @returns A {@link RunSummary}: the per-locale {@link LocaleSummary}s and the succeeded/partial/failed locale lists.
+ * Runs the one-shot translation flow over every configured target locale: read the source, diff
+ * each locale against the lock-file baseline, translate what is missing or stale, verify placeholder
+ * and ICU integrity, write the locale files, and update the lock-file and translation memory.
+ *
+ * Failure handling is the contract worth understanding. Whole-run problems, such as an unreadable
+ * source file or a provider that cannot be constructed, throw an {@link SdkError} before any locale
+ * runs. Once locales are running, a per-locale failure is recorded on that locale's
+ * {@link LocaleSummary} and the other locales continue, so one unreachable provider or one
+ * unwritable file never discards work that succeeded. A locale whose write lock stays contended is
+ * one of these per-locale failures: it is recorded with code `LOCK_CONTENDED` on that locale's
+ * summary rather than thrown. Callers should therefore inspect {@link RunSummary.failed} rather
+ * than relying on a thrown error to detect trouble.
+ *
+ * A corrupt lock-file is the one exception. On a live run each locale reads the lock-file inside
+ * its own write lock, so `LOCK_FILE_INVALID` escapes as a thrown error even after earlier locales
+ * have already translated and written. No further locale is started, and the locales in flight
+ * finish and release their write locks before the call rejects.
+ *
+ * Each locale takes its own write lock for the read-modify-write, so concurrent runs and
+ * single-key edits cannot interleave on one file. Translations that fail the integrity gate are
+ * refused rather than written, leaving the previous value intact.
+ *
+ * Set `dryRun` to compute the whole plan without writing or spending anything.
+ *
+ * @param input - The config and the per-run options.
+ * @param deps - Optional adapter registry, provider factory, and file-system overrides.
+ * @returns The per-locale account of the run, including usage and budget.
+ *
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
- * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw (this wraps the
- *   provider's own error, including a missing `*_API_KEY` reported as `MISSING_API_KEY`); only on a
- *   non-dry-run, since dry-run never constructs the provider.
+ * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is not an integer of at least 1.
+ * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: a live run combined a `concurrency` above
+ * 1 with a configured token budget. A dry run is exempt.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
- * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be read or parsed (wraps the
- *   adapter read error).
- * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is present but corrupt or oversized.
- * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is defined but not an integer of at
- *   least 1; raised before any locale runs.
- * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: a live run set `concurrency` greater than 1
- *   while the config configures a `maxTokens` budget; raised before any provider call (a dry run is
- *   exempt).
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `PROVIDER_CONSTRUCTION_FAILED`: the provider could not be constructed,
+ * most often because its API key environment variable is unset. Not thrown on a dry run, which
+ * never constructs a provider.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version. A dry run reads it once before any locale runs; a live run reads it per
+ * locale, so this can abort the run after other locales have already been written.
+ *
  * @example
  * ```ts
  * import { loadConfig, translate } from "@verbatra/sdk";
  *
- * // The provider reads its API key from the environment (e.g. ANTHROPIC_API_KEY); no key is passed here.
  * const config = await loadConfig();
- * const summary = await translate({ config });
+ * const summary = await translate({
+ *   config,
+ *   onProgress: (event) => {
+ *     if (event.type === "locale-finished") {
+ *       console.log(`${event.locale}: ${event.translated} keys`);
+ *     }
+ *   },
+ * });
  *
- * for (const locale of summary.locales) {
- *   if (locale.status === "failed") {
- *     // Surfaced, not thrown: code is a preserved string (LOCALE_FAILED is only the fallback).
- *     console.error(`${locale.locale}: ${locale.error?.code} ${locale.error?.message}`);
- *   } else {
- *     console.log(`${locale.locale}: ${locale.translated.length} translated, ${locale.notices.length} notices`);
+ * if (summary.failed.length > 0) {
+ *   for (const locale of summary.locales.filter((entry) => entry.status === "failed")) {
+ *     console.error(`${locale.locale}: ${locale.error?.message}`);
  *   }
+ *   process.exitCode = 1;
  * }
- *
- * // Preview only: no provider call, no writes.
- * const preview = await translate({ config, dryRun: true });
  * ```
  */
 declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
 
 /**
  * The two delimiter-separated interchange formats. They are one implementation with one parameter, the
- * field delimiter: `tsv` is not a second format, it is `csv` with a tab.
+ * field delimiter: `tsv` is not a second format, it is `csv` with a tab. The member is also the file
+ * extension an export writes and an import reads back.
  */
 type DelimitedFormat = "csv" | "tsv";
 
 /**
- * The interchange format a handoff moves in. `xlsx` is the default and the only shape that carries
- * every target locale in one artifact; `csv` and `tsv` are plain text and move one file per target
- * locale, so their path names a directory rather than a file.
+ * The file shape of a translator handoff: a single styled `.xlsx` workbook with one sheet per
+ * locale, or one plain `.csv` or `.tsv` file per locale.
+ *
+ * The workbook is the friendlier artifact to hand a human translator, while the delimited forms are
+ * easier to diff, review, and feed to another tool. {@link exportWorkbook} and
+ * {@link importWorkbook} both accept either.
  */
 type ExchangeFormat = "xlsx" | DelimitedFormat;
+/**
+ * Every {@link ExchangeFormat} at runtime, for a tool that has to validate a `--format` argument or
+ * offer the choices to a user. The order is the order to present them in: the workbook first, then
+ * the delimited forms.
+ *
+ * It is derived from a record keyed by {@link ExchangeFormat} itself, so a format added to the type
+ * without being added here fails to compile. A consumer that checks membership against this list can
+ * therefore never silently reject a format the SDK accepts.
+ */
+declare const EXCHANGE_FORMATS: readonly ExchangeFormat[];
+/** The {@link ExchangeFormat} {@link exportWorkbook} and {@link importWorkbook} use when the caller names none. */
+declare const DEFAULT_EXCHANGE_FORMAT: ExchangeFormat;
 
-/** Default workbook output path, relative to the resolved working directory. */
+/** Default output path for an `.xlsx` handoff, used when {@link ExportWorkbookInput.out} is omitted. */
 declare const DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
 /**
- * Default delimited output directory, relative to the resolved working directory. A delimited export
- * writes one file per target locale, so its output path names a directory, not a file.
+ * Default output directory for a delimited handoff. It carries no extension because it names a
+ * directory, not a file: the export creates it and writes one `<locale>.<format>` file inside it
+ * per exported locale, such as `de.csv`.
  */
 declare const DEFAULT_DELIMITED_PATH = "verbatra-translations";
-/** Input for {@link exportWorkbook}: the validated config and where/how to run the export. */
+/** Input for {@link exportWorkbook}. */
 interface ExportWorkbookInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern, lock-file, and output path resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` and `out` are resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
     /**
-     * Output path; defaults to {@link DEFAULT_WORKBOOK_PATH} for `xlsx` and to
-     * {@link DEFAULT_DELIMITED_PATH} for `csv` and `tsv`. It is the workbook file for `xlsx` and the
-     * directory the per-locale files are written into for `csv` and `tsv` (created if missing).
+     * Where to write the handoff. Defaults to {@link DEFAULT_WORKBOOK_PATH} for `xlsx` and to
+     * {@link DEFAULT_DELIMITED_PATH} for the delimited formats.
      */
     readonly out?: string;
-    /** Subset of target locales to export; defaults to all configured target locales. */
+    /** Restrict the export to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
-    /** Include unchanged keys (off by default; export is missing-and-changed only). */
+    /**
+     * Include keys that are already up to date, not just the missing and stale ones. Useful when a
+     * translator needs the surrounding context to translate consistently. Defaults to false.
+     */
     readonly includeUnchanged?: boolean;
-    /** Interchange format to write; defaults to `xlsx`, so an existing caller is unaffected. */
+    /** The handoff shape to write. Defaults to `xlsx`. */
     readonly format?: ExchangeFormat;
 }
-/** Composition seam for {@link exportWorkbook}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link exportWorkbook}. Every field has a working default. */
 interface ExportWorkbookDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
-/** The outcome of an export: where it was written and how many rows per locale. */
+/** What {@link exportWorkbook} wrote. */
 interface ExportWorkbookResult {
-    /**
-     * The absolute path written to: the workbook file for `xlsx`, the directory holding one
-     * `<locale>.csv` or `<locale>.tsv` per exported locale for the delimited formats.
-     */
+    /** The absolute path written, or the shared base path when one file per locale was written. */
     readonly path: string;
-    /** Per-locale row counts, in config order; the same set the workbook carries. */
+    /** Row counts per exported locale. */
     readonly locales: readonly {
+        /** The exported target locale. */
         readonly locale: string;
+        /** How many translatable rows that locale contributed. */
         readonly rows: number;
     }[];
 }
 /**
- * Export the strings needing human translation into a styled `.xlsx` workbook, or into one plain
- * `.csv` or `.tsv` file per target locale. Each target locale is diffed against the source and lock
- * baseline to pick the rows (missing and changed by default; add unchanged with `includeUnchanged`),
- * and the result is written to `out`. No provider is called and no lock-file is written.
+ * Writes the strings awaiting translation to a handoff a human translator can work in: a styled
+ * `.xlsx` workbook with one sheet per locale, or one `.csv` or `.tsv` file per locale.
+ *
+ * By default only missing and stale keys are exported, which is what makes the handoff a work list
+ * rather than a dump of the whole project. Each row carries the source text alongside any existing
+ * translation and a review status, so the translator sees what changed and why a string was
+ * flagged.
  *
- * The delimited formats trade the workbook's protection for a diffable, git-friendly handoff: a
- * workbook leaves only the Translation column editable and hides the source hash, while every field of
- * a delimited file is editable and its source hash is visible. An edited source hash is never trusted
- * on import; it is compared against the live source and the row is withheld as drift.
+ * This is the outbound half of the exchange; {@link importWorkbook} reads the filled handoff back
+ * through the same diff, lock, and integrity checks. It writes only the handoff file and never
+ * touches the locale files or the lock-file.
  *
- * A delimited export also writes a small hidden manifest naming the locales it wrote. It exists so a
- * re-export with a narrower `locales` selection retires the locales it dropped: their files stay on
- * disk, but the next import recognizes them as leftovers from the earlier run and refuses to apply
- * them. The export deletes nothing, so an unrelated file in the output directory is never at risk.
+ * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
+ * should be ready for an unrecognized error from a target file.
  *
- * @param input - The validated config and export options.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns Where the export was written and the per-locale row counts.
- * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
- *   among the configured target locales.
+ * @param input - The config, output path, locale filter, and handoff format.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns The path written and the per-locale row counts.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 
-/** Input for {@link importWorkbook}: the validated config, the workbook path, and run options. */
+/** Input for {@link importWorkbook}. */
 interface ImportWorkbookInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
     /**
-     * Path to the filled handoff to import: the workbook file for `xlsx`, and for `csv` and `tsv`
-     * either one `<locale>.csv` / `<locale>.tsv` file or a directory holding one per target locale.
+     * Path to the filled handoff. For a delimited import the path is tried as a single file first,
+     * so one individual `<locale>.<format>` file can be imported on its own, with the locale taken
+     * from its file name. If no file exists there, the path is treated as the directory the
+     * per-locale files were written into and every configured target locale found inside is read.
      */
     readonly workbook: string;
-    /** Directory the file pattern, lock-file, and workbook path resolve against; defaults to cwd. */
+    /** Directory the `files.pattern` and `workbook` are resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** When true, validate and report only: write no locale file and update no lock-file. */
+    /**
+     * Read and validate the handoff but write nothing. The returned {@link RunSummary} reports what
+     * would have been applied, which is the safe way to inspect a handoff before trusting it.
+     * Defaults to false.
+     */
     readonly dryRun?: boolean;
-    /** Interchange format to read; defaults to `xlsx`, so an existing caller is unaffected. */
+    /** The handoff shape to read. Defaults to `xlsx`. */
     readonly format?: ExchangeFormat;
 }
-/** Composition seam for {@link importWorkbook}: inject a registry and a file system for tests. */
+/** Injectable dependencies for {@link importWorkbook}. Every field has a working default. */
 interface ImportWorkbookDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Import a filled handoff back into the locale files. Each target-locale data sheet runs the same
- * source-drift, placeholder, and ICU checks as the translate flow, the accepted values are written
- * through the format adapter, and the lock is updated. Returns a {@link RunSummary} structurally
- * identical to `translate`'s.
+ * Reads a filled translator handoff back into the locale files. It is the inbound half of the
+ * exchange that {@link exportWorkbook} starts, and it calls no provider: every value comes from the
+ * handoff.
+ *
+ * Imported values are held to the same integrity gate as provider output, so a translator who drops
+ * a placeholder or breaks ICU syntax has that row refused rather than written. Each locale takes
+ * its write lock, and the lock-file and translation memory are updated exactly as in a
+ * {@link translate} run, so an imported translation counts as up to date afterwards.
  *
- * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
- * structured {@link SdkError}. A per-sheet failure (a sheet named for a locale not in config, a
- * broken-round-trip key, a write failure) is isolated as that locale's `status: "failed"`, not a
- * throw; per-row rejections are withheld and reported on the locale. A configured target locale with
- * no sheet at all (a deleted, renamed, or reordered tab) is reconciled after the sheet loop and
- * reported as that locale's `status: "failed"` (`WORKBOOK_SHEET_MISSING`) rather than silently
- * dropped. For a delimited directory, a locale file the most recent export into that directory did not
- * write is a leftover from an earlier, wider selection: it is never applied and is reported as that
- * locale's `status: "failed"` (`HANDOFF_FILE_STALE`). Dry-run validates and reports without writing any
- * locale or lock file, and skips lock acquisition (there is nothing to protect).
+ * Damage is contained rather than fatal: a blank row keeps the existing translation and its
+ * baseline, an unreadable row is reported as a {@link MalformedRowReport}, and a repeated key is
+ * reported as a {@link DuplicateKeyReport} with the first occurrence winning. All three surface on
+ * the returned {@link RunSummary} rather than aborting the import. A sheet or file naming a locale
+ * that is not configured is contained the same way: that locale fails with `CONFIG_INVALID` on its
+ * own {@link LocaleSummary}, so nothing is written to an unmanaged path and the configured locales
+ * still import. Once the handoff has been read, every per-locale failure is isolated this way, so
+ * callers should inspect {@link RunSummary.failed} rather than relying on a thrown error.
  *
- * The lock-file is read once, up front, for every sheet's diff baseline. On a non-dry-run, each
- * sheet's write-and-lock-update step then holds that locale's `withLocaleWriteLock` for its whole
- * critical section, so a concurrent writer touching the same locale can never interleave with it.
+ * @param input - The config and the handoff path, format, and dry-run flag.
+ * @param deps - Optional adapter registry and file-system overrides.
+ * @returns The per-locale account of what was applied.
  *
- * @param input - The validated config, the workbook path, and run options.
- * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns A {@link RunSummary} with one locale per data sheet, in workbook order.
- * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the handoff file was not found, or the source
+ * locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the handoff is oversized or could not be parsed, or
+ * the source locale file could not be parsed.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
+ * unsupported version. Read once before any locale is applied.
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
-/** The locale styles a files pattern's `{locale}` token can expand under. */
+/** The locale spellings {@link LocaleStyle} is drawn from, in declaration order. */
 declare const LOCALE_STYLES: readonly ["literal", "posix", "android"];
 /**
- * How a configured locale is spelled inside a path:
+ * How a locale is spelled inside a file path, set through the config's `files.localeStyle`.
  *
- * - `literal` (the default) expands the token to the configured tag verbatim. This covers the
- *   i18next, vue-i18n, next-intl, ngx-translate, XLIFF, YAML, and ARB layouts, and Apple's
- *   `.lproj` naming, which is the BCP-47 tag as written.
- * - `posix` replaces `-` with `_`, for gettext directories (`pt_BR/LC_MESSAGES/`) and the Java
- *   `messages_{locale}.properties` suffix layout.
- * - `android` expands the token to a complete Android resource-directory segment, `values` prefix
- *   included, and is the only style that spells the source locale differently from a target.
+ * - `literal`: the locale is written into the path exactly as configured, so `pt-BR` yields
+ *   `pt-BR`. This is the default and suits the JSON and YAML layouts most web projects use.
+ * - `posix`: the POSIX spelling, so `pt-BR` yields `pt_BR`. Common for gettext-influenced and
+ *   Java-influenced layouts.
+ * - `android`: the Android resource-qualifier spelling, so `pt-BR` yields `values-pt-rBR` and the
+ *   source locale yields the unqualified `values`. This style expands to a whole path segment, so
+ *   the `{locale}` token must stand alone between separators in the pattern.
  *
- * A style may be relaxed to accept a locale it previously refused, but the spelling it already
- * produces must never change: a re-spelling orphans every file written under the old name, leaving
- * a stale directory the platform still prefers.
+ * A locale that has no valid spelling under the declared style, or that would expand to something
+ * other than a single path segment, is rejected with `LOCALE_LAYOUT_INVALID` before any file is
+ * read.
  */
 type LocaleStyle = (typeof LOCALE_STYLES)[number];
 
 /**
- * The part of the project config locale-to-path resolution depends on. Deliberately structural, so a
- * caller holding a full `VerbatraConfig` passes it unchanged while a test can build one inline.
+ * The slice of a {@link VerbatraConfig} that determines locale-to-path mapping. It is narrower than
+ * the full config on purpose, so a caller holding only these fields can build a resolver.
  */
 interface LocalePathResolverConfig {
+    /** The source locale, which some styles spell differently from the targets. */
     readonly sourceLocale: string;
+    /** Every target locale. All of them are mapped up front so collisions are caught immediately. */
     readonly targetLocales: readonly string[];
+    /** The file layout. */
     readonly files: {
+        /** The path pattern, which must contain the `{locale}` token. */
         readonly pattern: string;
+        /** How a locale is spelled inside the path. Defaults to `literal`. */
         readonly localeStyle?: LocaleStyle | undefined;
     };
 }
-/**
- * The project's locale-to-path mapping, resolved once from the config and threaded through every
- * flow that needs a path. Holding one object rather than a `(pattern, style, sourceLocale)` triple
- * is what keeps a source-aware style from producing a wrong path in a flow that only threaded part
- * of it.
- */
+/** The two-way mapping between locales and their absolute file paths. */
 interface LocalePathResolver {
     /**
-     * The absolute file path for one locale. Never throws for a configured locale: every one of them
-     * is spelled and checked when the resolver is created.
-     *
-     * @throws SdkError `LOCALE_LAYOUT_INVALID` when the style cannot spell an unconfigured locale
-     * passed in after construction.
+     * The absolute path of a locale's file. Accepts any locale string, including ones outside the
+     * configured set, so it can be used for exploratory reads.
      */
     pathFor(locale: string): string;
     /**
-     * Which configured locale a path belongs to, or `undefined` when it belongs to none of them. This
-     * is a lookup in the forward map, never a parse: the configured locale list is the only authority
-     * on which locales exist. A relative argument is resolved against the same `cwd` the resolver was
-     * created with; the match is exact, so a path differing only in case does not resolve even on a
-     * case-insensitive file system.
-     *
-     * `undefined` is not an error. It means the path is not one of this project's locale files, which
-     * is what a watcher needs to know in order to ignore it.
+     * The configured locale owning an absolute path, or `undefined` when the path belongs to no
+     * configured locale. The path is normalized before lookup, so a relative or non-canonical path
+     * still resolves.
      */
     localeFor(absolutePath: string): string | undefined;
 }
 /**
- * Creates the project's locale-to-path resolver. Every check runs here, before any file is read and
- * before any provider call: the pattern must carry the `{locale}` token and must be combinable with
- * the declared style, the style must have a valid spelling for the source locale and every target,
- * and no two locales may resolve to the same path.
+ * Builds the project's locale-to-path mapping from the configured pattern, locales, and
+ * {@link LocaleStyle}, in both directions.
+ *
+ * Every SDK flow resolves paths through this, and a consumer that watches or reports on locale
+ * files should use it too rather than re-deriving the mapping: a watcher that guesses at paths will
+ * disagree with the SDK the moment a non-literal locale style is configured.
  *
- * Under the default `literal` style the produced path is the pattern with `{locale}` replaced by the
- * configured tag, resolved against `cwd`, which is what every project without a `files.localeStyle`
- * gets and is unchanged from before styles existed.
+ * The whole configured locale set is mapped eagerly during construction, so an unusable layout or a
+ * path collision is reported here, before any file is read and before any provider is called,
+ * rather than partway through a run.
  *
- * @param cwd - Directory the files pattern resolves against.
- * @param config - The project's locales, files pattern, and locale style.
- * @throws SdkError `LOCALE_LAYOUT_INVALID` when the pattern and style cannot be combined, or the
- * style cannot spell a configured locale.
- * @throws SdkError `LOCALE_PATH_COLLISION` when two configured locales resolve to the same path.
+ * @param cwd - Directory the pattern is resolved against.
+ * @param config - The source locale, target locales, and file layout.
+ * @returns A resolver mapping locales to paths and paths back to locales.
+ *
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the pattern lacks the `{locale}` token, a
+ * segment style's token does not stand alone between separators, or a configured locale has no
+ * valid single-segment spelling under the declared style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same
+ * absolute path.
  */
 declare function createLocalePathResolver(cwd: string, config: LocalePathResolverConfig): LocalePathResolver;
 
 /**
- * The lock-file shape: for each target locale, a map of key to the source content hash from which that
- * target key was last translated. The baseline core's diff consumes to detect changed source strings.
+ * The contents of `verbatra.lock.json` (see {@link LOCK_FILE_NAME}), the baseline that makes
+ * staleness detectable. For each locale it records the hash of the source text each key was
+ * translated from, so a later run can tell a translation that is merely present from one that is
+ * still current.
+ *
+ * Commit it: without it, every run has to treat an existing translation as up to date and a source
+ * edit would silently never be re-translated.
  */
 interface LockFile {
+    /** The lock-file schema version. An unrecognized version is rejected rather than guessed at. */
     readonly version: number;
+    /** Per locale, the source-content hash recorded for each translated key. */
     readonly locales: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
 
-/** Input for {@link loadLockFile}: the directory the lock-file resolves against. */
+/** Input for {@link loadLockFile}. */
 interface LoadLockFileInput {
-    /** Directory the lock-file resolves against; defaults to cwd. */
+    /** Directory holding the lock-file. Defaults to the process working directory. */
     readonly cwd?: string;
 }
-/** Composition seam for {@link loadLockFile}: inject a file system for tests. */
+/** Injectable dependencies for {@link loadLockFile}. Every field has a working default. */
 interface LoadLockFileDeps {
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
 }
 /**
- * Read the project's lock-file: a thin public wrapper around the internal lock-file reader,
- * following the same input/deps convention as {@link check}, {@link diff}, and {@link lockState}.
- * A missing lock-file degrades to an empty lock (first-run), the same behavior `translate` and
- * `watch` rely on internally. Callers that need to distinguish "no lock-file yet" from "an empty
- * but present lock-file" should use {@link lockState} instead, which probes the file's existence
- * explicitly.
+ * Reads the project's lock-file. Use it when you need the recorded baseline hashes themselves;
+ * {@link lockState} is the better choice when you want the drift those hashes imply.
  *
- * @param input - The directory the lock-file resolves against.
- * @param deps - Optional composition seam (file system) for tests.
- * @returns The parsed lock-file, or an empty lock when none exists yet.
- * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt, oversized,
- * or at an unsupported version.
+ * A project with no lock-file yet reads as an empty lock-file at the current version rather than an
+ * error, so a first run and a lost file behave the same way. A lock-file that exists but cannot be
+ * trusted is a different matter and throws, because silently treating a corrupt baseline as empty
+ * would make every key look stale and trigger a full re-translation.
+ *
+ * @param input - The optional working directory.
+ * @param deps - Optional file-system override.
+ * @returns The lock-file's contents, or an empty lock-file when none exists.
+ *
+ * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file exists but is oversized, not valid
+ * JSON, structurally wrong, or at an unsupported version.
  */
 declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps): Promise<LockFile>;
 
-/** The committed lock-file name, chosen to be obviously JSON and to not match a `*.lock` ignore rule. */
+/**
+ * The file name of the project's lock-file, resolved against the run's working directory. Commit it
+ * alongside the locale files: it is the baseline that lets verbatra tell a stale translation from a
+ * current one. See {@link LockFile} for its contents.
+ */
 declare const LOCK_FILE_NAME = "verbatra.lock.json";
 
 /**
- * The subset of {@link ProviderId} that `init` can scaffold: every provider with a single required
- * environment variable. "openai-compatible" is deliberately excluded: unlike every other provider it
- * has no single required environment variable, only a three-tier
- * apiKeyEnvVar/OPENAI_COMPATIBLE_API_KEY/placeholder fallback (see resolveOpenAiCompatibleKey in
- * @verbatra/ai-providers), so it does not fit the `providerEnv` table below and `init` scaffolding does
- * not offer it. This is the single source of truth for the exclusion; other packages import this type
- * rather than re-deriving `Exclude<ProviderId, "openai-compatible">` themselves.
+ * A provider that project scaffolding can offer out of the box. It excludes `openai-compatible`,
+ * which needs a `baseUrl` and a model name that only the user can supply, so there is nothing
+ * sensible to prefill.
  */
 type ScaffoldableProviderId = Exclude<ProviderId, "openai-compatible">;
 /**
- * Read-only metadata the CLI `init` scaffold derives its tables from, so the CLI never restates the
- * provider, env-var, model, or format truth owned by core and ai-providers.
+ * The facts a project generator needs to write a first config: which environment variable each
+ * provider reads its API key from, a sensible starting model per provider, and the formats the SDK
+ * can handle.
+ *
+ * It is exported so that the CLI's `init` command and any third-party generator prompt with the
+ * same values the SDK actually enforces, rather than keeping a copy that drifts. Note the key names
+ * only: no key value is present or reachable here.
  */
 declare const scaffoldingMetadata: {
-    /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
+    /** The environment variable each scaffoldable provider reads its API key from. */
     readonly providerEnv: {
         readonly anthropic: "ANTHROPIC_API_KEY";
         readonly openai: "OPENAI_API_KEY";
         readonly gemini: "GEMINI_API_KEY";
         readonly deepl: "DEEPL_API_KEY";
     };
-    /** LLM provider id -> a cosmetic default scaffold model. Owned by ai-providers. DeepL has none. */
+    /** A reasonable default model to prefill per language-model provider. DeepL has none, since it takes no model. */
     readonly scaffoldModels: {
         readonly anthropic: "claude-sonnet-4-6";
         readonly openai: "gpt-5.4-mini";
         readonly gemini: "gemini-2.5-flash";
     };
-    /** The closed set of source format ids. Owned by core. */
+    /**
+     * The option key each language-model provider takes its output token limit under, since they do
+     * not agree: Anthropic calls it `maxTokens` and the others `maxOutputTokens`. A generator that
+     * prefills a token limit must read the key from here rather than assume one, because
+     * {@link verbatraConfigSchema} validates each provider's options strictly and rejects the wrong
+     * one. DeepL has no entry, since it takes no token limit.
+     */
+    readonly providerTokenLimitKeys: {
+        readonly anthropic: "maxTokens";
+        readonly openai: "maxOutputTokens";
+        readonly gemini: "maxOutputTokens";
+    };
+    /** Every i18n file format the SDK can read and write. */
     readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties"];
 };
 
-/** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
+/**
+ * The minimal file-watching surface {@link watch} needs. Supplying your own through
+ * `deps.createWatcher` lets an embedding application reuse a watcher it already runs, or drive the
+ * flow deterministically in a test.
+ */
 interface Watcher {
-    /** Register a listener invoked once per coalesced source-change event. */
+    /** Registers a listener called on each change to the watched paths. */
     onChange(listener: () => void): void;
-    /** Stop watching and release the underlying resources. */
+    /** Stops watching and releases the underlying resources. */
     close(): Promise<void>;
 }
-/** Builds a {@link Watcher} for the given paths; the seam production fills with chokidar. */
+/** Builds a {@link Watcher} over the given absolute paths. Defaults to a chokidar-backed watcher. */
 type CreateWatcher = (paths: readonly string[]) => Watcher;
-/** The run a watch trigger performs: the one-shot translate, unchanged. */
+/** Runs one translation pass. Defaults to {@link translate}, and is the seam a test substitutes. */
 type RunTranslate = (input: TranslateInput) => Promise<RunSummary>;
-/** The outcome of one run, surfaced to the caller; never carries a secret. */
+/**
+ * The outcome of a single watch-triggered run, handed to `onRun`. A failed run is reported here
+ * rather than thrown, because a long-lived watcher must survive a bad run and keep watching.
+ */
 type WatchRunResult = {
+    /** The run completed. Inspect the summary for per-locale outcomes, which may still include failures. */
     readonly status: "succeeded";
+    /** The run's per-locale account. */
     readonly summary: RunSummary;
 } | {
+    /** The run threw before producing a summary, for instance because the source became unreadable. */
     readonly status: "failed";
-    /**
-     * A secret-free projection of the run's failure. `code` is a preserved string (the underlying
-     * error's `code`, or `"WATCH_RUN_FAILED"` as a fallback), not an {@link SdkErrorCode}.
-     */
+    /** The failure's code and message. Never carries a secret. */
     readonly error: {
+        /** The failure's own code where it had one, and `WATCH_RUN_FAILED` otherwise. */
         readonly code: string;
+        /** A human-readable description of the failure. Never contains a secret. */
         readonly message: string;
     };
 };
-/** Everything watch mode needs: the config, optional cwd/debounce, and the per-run output callback. */
+/** Input for {@link watch}. */
 interface WatchInput {
-    /** The validated configuration (typically from {@link loadConfig}). */
+    /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the file pattern and lock-file resolve against; defaults to the current working directory. */
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
-    /** Quiet period after the last change before a run fires; defaults to 300ms. */
+    /** How long to coalesce rapid source changes before running. Defaults to 300 milliseconds. */
     readonly debounceMs?: number;
-    /** Called once per run with its result. The SDK does no logging; this is the only output. */
-    readonly onRun: (result: WatchRunResult) => void;
     /**
-     * Passed through to every run's {@link TranslateInput.onLockWait}: called while a locale's write lock
-     * is blocked on another process, so a watch caller can surface the same "still waiting" progress a
-     * one-shot run does.
+     * Called after every run with its outcome. This is the only way to observe a watch session, since
+     * {@link watch} itself resolves as soon as watching starts.
      */
+    readonly onRun: (result: WatchRunResult) => void;
+    /** Called while waiting on another process's write lock. */
     readonly onLockWait?: LockWaitListener;
-    /**
-     * Passed through to every run's {@link TranslateInput.onProgress}: fires per locale and per provider
-     * sub-batch as each run advances, so a watch caller can surface the same progress a one-shot run does.
-     */
+    /** Called as locales and sub-batches start and finish, for progress reporting. */
     readonly onProgress?: ProgressListener;
-    /** Passed through to every run's {@link TranslateInput.lockAcquireTimeoutMs}; the lock's 10-minute default when unset. */
+    /** How long to wait for a locale's write lock before that run fails. */
     readonly lockAcquireTimeoutMs?: number;
-    /**
-     * Passed through to every run's {@link TranslateInput.concurrency}: how many locales each cycle may
-     * run at once. Defaults to 1 (strictly serial). Because the per-cycle budget tracker is fresh, a
-     * value greater than 1 cannot be honored alongside a `maxTokens` budget; {@link watch} refuses that
-     * combination at startup rather than letting every cycle fail on it.
-     */
+    /** How many locales to run at once. Validated once when watching starts, and applied to every run. */
     readonly concurrency?: number;
-    /**
-     * Passed through to every run's {@link TranslateInput.cache}: when false, each run bypasses the
-     * translation-memory cache (both read and write). On by default.
-     */
+    /** Consult and update the translation memory. Defaults to true. */
     readonly cache?: boolean;
 }
-/** Composition seam: inject the watcher and the run for deterministic, offline tests. */
+/** Injectable dependencies for {@link watch}. Every field has a working default. */
 interface WatchDeps {
-    /** Adapter registry passed through to each run; defaults to the built-in registry. */
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
     readonly adapterRegistry?: AdapterRegistry;
-    /** Provider builder passed through to each run; defaults to constructing the configured provider. */
+    /** Provider factory. Defaults to constructing the provider named in the config. */
     readonly createProvider?: CreateProvider;
-    /** File system passed through to each run; defaults to the real file system. */
+    /** File-system port. Defaults to the real file system. */
     readonly fs?: SdkFs;
-    /** Source-change event source; defaults to the chokidar-backed watcher. */
+    /** Watcher factory. Defaults to a chokidar-backed watcher over the source file. */
     readonly createWatcher?: CreateWatcher;
-    /** The run a trigger performs; defaults to the one-shot {@link translate}. */
+    /** Translation runner. Defaults to {@link translate} wired with the other dependencies. */
     readonly runTranslate?: RunTranslate;
 }
-/** Handle returned by {@link watch} to stop it. */
+/** The handle returned by {@link watch}, used to end the session. */
 interface WatchController {
-    /** Stop accepting triggers, close the watcher, and await the in-flight run to completion. */
+    /** Stops watching and waits for any in-flight run to settle. Safe to call more than once. */
     stop(): Promise<void>;
 }
 /**
- * Start watching the source file and re-run the one-shot {@link translate} on each debounced change.
- * Runs are serialized: changes during a run collapse into a single follow-up, so two runs never
- * overlap. A missing source at startup throws; every run outcome after start is surfaced through
- * `onRun` as a {@link WatchRunResult} and watching continues. Returns a controller whose `stop()`
- * closes the watcher and awaits the in-flight run.
- *
- * Both startup refusals are ordered deliberately: `concurrency` is resolved first because it is
- * decidable from the arguments alone, while the missing-source check is an I/O probe of project
- * state, so argument validation runs before any I/O and before the watcher exists. The concurrency
- * resolve passes `dryRun: false` unconditionally, which is exact rather than a simplification: there
- * is no dry-run watch, so the budget conflict always applies to a session.
- *
- * Resolving it here rather than leaving it to each cycle is the point, not an optimization: a watch
- * session is long-lived, so a per-cycle refusal would fail the initial run and every run after it,
- * indefinitely, while the session stayed alive and looked healthy.
- *
- * @param input - The config, optional cwd/debounce, and the `onRun` callback that receives each result.
- * @param deps - Optional composition seams (watcher, run, registry, provider builder, file system) for tests.
- * @returns A {@link WatchController}; call `stop()` to close the watcher and await the in-flight run.
- * @throws {@link SdkError} `CONCURRENCY_INVALID`: at startup only, when `concurrency` is defined but
- *   not an integer of at least 1.
- * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: at startup only, when `concurrency` is
- *   greater than 1 while the config sets a `maxTokens` budget.
- * @throws {@link SdkError} `SOURCE_UNREADABLE`: at startup only, when the source locale file is absent.
+ * Watches the source locale file and re-runs {@link translate} on each debounced change. It is the
+ * development-loop counterpart to a one-shot run: edit a string, and the target locales catch up
+ * without a manual command.
+ *
+ * One run starts immediately once watching is established, without waiting for a change, so the
+ * target locales are brought up to date the moment the session opens. Its outcome arrives through
+ * `onRun` like any other, and it may still be in flight when the returned promise resolves.
+ *
+ * The returned promise resolves as soon as watching is established, not when translation finishes,
+ * so every run outcome arrives through `onRun`. A run that throws is delivered as a failed
+ * {@link WatchRunResult} rather than escaping the session, because a watcher that died on the first
+ * bad save would be useless. Only startup problems, validated before any watching begins, throw.
+ *
+ * Rapid saves are coalesced by `debounceMs`, and runs never overlap, so an editor writing a file
+ * several times in a moment produces one run rather than a queue of them.
+ *
+ * Call {@link WatchController.stop} to end the session.
+ *
+ * @param input - The config, the debounce window, and the run callback.
+ * @param deps - Optional adapter registry, provider factory, file-system, watcher, and runner overrides.
+ * @returns A controller that stops the session.
+ *
+ * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is not an integer of at least 1.
+ * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: `concurrency` above 1 was combined with a
+ * configured token budget.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * cannot be combined, or a configured locale has no valid path spelling under that style.
+ * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
+ * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist when watching
+ * starts.
+ *
  * @example
  * ```ts
  * import { loadConfig, watch } from "@verbatra/sdk";
  *
- * // The provider reads its API key from the environment (e.g. ANTHROPIC_API_KEY); no key is passed here.
  * const config = await loadConfig();
  * const controller = await watch({
  *   config,
  *   onRun: (result) => {
- *     if (result.status === "succeeded") {
- *       console.log(`ran: ${result.summary.succeeded.length} ok, ${result.summary.failed.length} failed`);
- *     } else {
- *       // Surfaced, not thrown: code is a preserved string (WATCH_RUN_FAILED is only the fallback).
- *       console.error(`run failed: ${result.error.code} ${result.error.message}`);
+ *     if (result.status === "failed") {
+ *       console.error(`run failed: ${result.error.message}`);
+ *       return;
  *     }
+ *     console.log(`translated ${result.summary.succeeded.length} locales`);
  *   },
  * });
  *
- * // Stop cleanly on Ctrl-C: closes the watcher and awaits the in-flight run.
- * process.on("SIGINT", () => {
- *   void controller.stop();
- * });
+ * process.on("SIGINT", () => void controller.stop());
  * ```
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_DELIMITED_PATH, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExchangeFormat, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, type IntegrityGateReason, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyValueDeps, type KeyValueInput, type KeyValueResult, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type NeedsReviewEntry, type ProgressEvent, type ProgressListener, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type TranslationMemory, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, createLocalePathResolver, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_DELIMITED_PATH, DEFAULT_EXCHANGE_FORMAT, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, EXCHANGE_FORMATS, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExchangeFormat, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, type IntegrityGateReason, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyValueDeps, type KeyValueInput, type KeyValueResult, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type NeedsReviewEntry, type ProgressEvent, type ProgressListener, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type TranslationMemory, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, createLocalePathResolver, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, verbatraConfigSchema, watch };