@verbatra/sdk 0.11.0 → 0.11.1

package/dist/index.d.cts

@@ -115,7 +115,10 @@ interface TranslateRequest {
      */
     readonly signal?: AbortSignal;
 }
-/** Token usage, when the provider reports it. Absent for providers without tokens (DeepL). */
+/**
+ * Token usage, when the provider reports it. Absent for the providers that do not bill by token
+ * (DeepL and Google Cloud Translation).
+ */
 interface Usage {
     /** Tokens consumed by the request, summed across the initial call and any repair round. */
     readonly inputTokens: number;
@@ -126,10 +129,10 @@ interface Usage {
  * Stable codes for a provider's graceful-degradation notices. These are returned DATA on a
  * successful result, NOT thrown:
  *
- * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (DeepL's free tier does not
- *   support it).
+ * - `FORMALITY_DOWNGRADED`: a requested `formal` or `informal` tone was not applied (DeepL's free
+ *   tier does not support formality, and Google Cloud Translation Basic has no formality control).
  * - `GLOSSARY_IGNORED`: a supplied generic glossary term map was not applied (DeepL only applies a
- *   native glossary id, never a term map).
+ *   native glossary id, never a term map, and Google Cloud Translation Basic supports no glossary).
  * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
  *   because the provider cannot preserve those tokens; such entries are withheld (absent from the
  *   result maps) rather than sent to the provider and mangled.
@@ -228,8 +231,8 @@ interface TranslateResult {
     readonly usage?: Usage;
     /**
      * Graceful-degradation notices for this batch. Every provider populates this as a present array:
-     * DeepL reports real notices (for example `GLOSSARY_IGNORED`); an LLM provider with nothing to
-     * report returns an empty array rather than omitting the field.
+     * DeepL and Google Cloud Translation report real notices (for example `GLOSSARY_IGNORED`); an LLM
+     * provider with nothing to report returns an empty array rather than omitting the field.
      */
     readonly notices?: readonly ProviderNotice[];
     /**
@@ -349,8 +352,9 @@ declare const supportedFormatSchema$1: z.ZodEnum<{
 type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
 /**
  * A format identifier claimed by an adapter that ships outside verbatra: the reserved
- * `custom:` prefix followed by a lowercase, hyphen-separated name, for example
- * `custom:my-format`.
+ * `custom:` prefix followed by a name of lowercase ASCII letters and digits in hyphen-separated
+ * segments, for example `custom:my-format`. The type itself accepts any text after the prefix;
+ * {@link isCustomFormatId} and adapter registration enforce the name's shape at runtime.
  *
  * No built-in format name contains a colon, so a third-party identifier can never shadow a
  * built-in one.
@@ -361,7 +365,9 @@ type CustomFormatId$1 = `custom:${string}`;
  *
  * @param format - The identifier to classify.
  * @returns True when the identifier is a well-formed `custom:` identifier. A built-in format
- *   name always returns false.
+ *   name always returns false, and so does a `custom:` identifier whose name is empty, holds any
+ *   character other than a lowercase ASCII letter, a digit, or a hyphen, or has a leading,
+ *   trailing, or doubled hyphen.
  *
  * @example
  * ```ts
@@ -478,6 +484,10 @@ interface PlaceholderIntegrityResult$1 {
     readonly reordered: boolean;
 }
 
+/**
+ * Every translation framework a source scan can target, as a tuple; {@link SourceFramework} is
+ * derived from it. It holds `i18next` alone today, the one framework an extractor ships for.
+ */
 declare const SOURCE_FRAMEWORKS: readonly ["i18next"];
 /**
  * The translation framework whose call sites a source scan looks for. The set is closed: a
@@ -635,12 +645,26 @@ interface KeyConflict {
     /** Where each of those values was found, index-aligned with `values`. */
     readonly locations: readonly SourceLocation[];
 }
+/**
+ * Why a {@link ScanDiagnostic} was reported.
+ *
+ * - `unreadable`: the file could not be opened, or the path is not a regular file.
+ * - `too-large`: the file is larger than 2,000,000 bytes, so it was skipped without being read.
+ * - `unparseable`: the file was read, but the scan either failed on it outright, in which case
+ *   nothing from it is reported, or could not follow it to its end, in which case what was found
+ *   before that point is still reported.
+ * - `unreadable-directory`: a directory under a scan root could not be listed, so nothing beneath
+ *   it was scanned.
+ */
 type ScanDiagnosticReason = "unreadable" | "too-large" | "unparseable" | "unreadable-directory";
-/** One file or directory the scan could not read, reported as data so one bad file never aborts a run. */
+/**
+ * One file or directory the scan could not read, or could not read to its end, reported as data so
+ * one bad file never aborts a run.
+ */
 interface ScanDiagnostic {
     /** The file or directory, relative to the run's working directory, with forward slashes. */
     readonly file: string;
-    /** Why it was skipped. */
+    /** Why it was skipped or only partly scanned. */
     readonly reason: ScanDiagnosticReason;
 }
 
@@ -736,8 +760,9 @@ declare const supportedFormatSchema: z.ZodEnum<{
 type SupportedFormat = z.infer<typeof supportedFormatSchema>;
 /**
  * A format identifier claimed by an adapter that ships outside verbatra: the reserved
- * `custom:` prefix followed by a lowercase, hyphen-separated name, for example
- * `custom:my-format`.
+ * `custom:` prefix followed by a name of lowercase ASCII letters and digits in hyphen-separated
+ * segments, for example `custom:my-format`. The type itself accepts any text after the prefix;
+ * {@link isCustomFormatId} and adapter registration enforce the name's shape at runtime.
  *
  * No built-in format name contains a colon, so a third-party identifier can never shadow a
  * built-in one.
@@ -935,16 +960,22 @@ interface FormatAdapter {
 }
 
 /**
- * The outcome of a size-bounded read through the {@link AdapterFs} port. A path that is not a file,
- * or a file larger than the caller's limit, is reported as a state rather than thrown, so an adapter
- * can treat "no file yet" and "too large to trust" as ordinary branches.
+ * The outcome of a size-bounded read through the {@link AdapterFs} port. A path that exists but is
+ * not a regular file, or a file larger than the caller's limit, is reported as a state rather than
+ * thrown, so an adapter can treat "not a file" and "too large to trust" as ordinary branches. A
+ * missing path is not one of these states: the port rejects instead (see
+ * {@link AdapterFs.readBounded}).
  */
 type BoundedReadOutcome = {
+    /** The file was read in full. */
     readonly kind: "ok";
+    /** The file's content, decoded as UTF-8. */
     readonly content: string;
 } | {
+    /** The path exists but is not a regular file, a directory for example, so nothing was read. */
     readonly kind: "not-a-file";
 } | {
+    /** The file is larger than the requested byte limit, so nothing was read. */
     readonly kind: "too-large";
 };
 /**
@@ -963,6 +994,10 @@ interface AdapterFs {
      * @param path - The file to read.
      * @param maxBytes - The largest file size to read; a larger file yields `too-large` and is not read.
      * @returns The file's content, or the state that prevented reading it.
+     * @throws An `Error` whose `code` is `"ENOENT"` when nothing exists at `path`, as `node:fs` does.
+     *   Several adapters re-read an existing destination before writing so they can preserve its
+     *   layout, and they rely on exactly that code to mean "no file yet, write a fresh one"; a port
+     *   that reports a missing file any other way fails those writes.
      */
     readBounded(path: string, maxBytes: number): Promise<BoundedReadOutcome>;
     /**
@@ -1050,8 +1085,10 @@ declare class AdapterRegistry {
      * can silently shadow what is already there.
      *
      * An adapter whose format is a third-party `custom:` identifier is wrapped so that an unexpected
-     * throw from any of its contract methods surfaces as an {@link AdapterError} naming the format.
-     * Built-in adapters are registered as they are.
+     * throw from any of its contract methods surfaces as an {@link AdapterError} with code
+     * `ADAPTER_FAILED` naming the format. An `AdapterError` the adapter raises itself, and a Node.js
+     * system error carrying an errno-style code such as `ENOENT`, pass through unchanged. Built-in
+     * adapters are registered as they are.
      *
      * @param adapter - The adapter to add.
      * @returns This registry, for chaining.
@@ -1208,7 +1245,10 @@ type FlatParseOutcome = Map<string, TranslationEntry> | FlatParseResult;
 interface FlatFileAdapterOptions {
     /** The format this adapter claims: a built-in name, or a `custom:` identifier of your own. */
     readonly format: FormatId;
-    /** The lowercase file extensions this format owns, each including the leading dot. */
+    /**
+     * The file extensions this format owns, each including the leading dot. Matched against a path's
+     * extension case-insensitively.
+     */
     readonly extensions: readonly string[];
     /**
      * Optional content check, consulted when a sample is available, so this adapter does not claim
@@ -1246,6 +1286,10 @@ interface FlatFileAdapterOptions {
  * supplies the bounded read, the atomic write, extension detection and the structured error
  * handling; you supply only the format's own parsing and serialization.
  *
+ * The returned adapter's `read` refuses a file larger than 16 MiB with `INPUT_TOO_LARGE` and a path
+ * that is not a regular file with `INVALID_STRUCTURE`, strips a leading byte order mark before
+ * parsing, and uses the file's base name without its extension as the namespace.
+ *
  * @param options - The format's parsing, serialization and detection behaviour.
  * @returns A complete adapter, ready to register on an `AdapterRegistry`.
  * @throws Nothing itself. The returned adapter's `read` and `write` raise `AdapterError` for content
@@ -1292,14 +1336,21 @@ type DeriveDescriptions = (content: string) => ReadonlyMap<string, string>;
 interface TreeFileAdapterOptions {
     /** The format this adapter claims: a built-in name, or a `custom:` identifier of your own. */
     readonly format: FormatId;
-    /** The lowercase file extensions this format owns, each including the leading dot. */
+    /**
+     * The file extensions this format owns, each including the leading dot. Matched against a path's
+     * extension case-insensitively.
+     */
     readonly extensions: readonly string[];
     /**
      * Optional content check, consulted when a sample is available, so this adapter does not claim
      * every file that merely shares one of its extensions.
      */
     readonly sniff?: Sniff;
-    /** Parse one file's text into a nested tree, preserving key order at every level. */
+    /**
+     * Parse one file's text into a nested tree, preserving key order at every level. Throw an
+     * `AdapterError` for content this format cannot represent; anything else thrown is reported as a
+     * structural failure.
+     */
     readonly parse: (content: string) => JsonRecord;
     /** Render a nested tree back to the format's text, preserving key order at every level. */
     readonly serialize: (tree: OrderedRecord) => string;
@@ -1330,6 +1381,10 @@ interface TreeFileAdapterOptions {
  * write, tree flattening and unflattening, extension detection and the structured error handling;
  * you supply only the format's own parsing, serialization and per-leaf facts.
  *
+ * The returned adapter's `read` refuses a file larger than 16 MiB with `INPUT_TOO_LARGE` and a path
+ * that is not a regular file with `INVALID_STRUCTURE`, strips a leading byte order mark before
+ * parsing, and uses the file's base name without its extension as the namespace.
+ *
  * @param options - The format's parsing, serialization, detection and per-entry behaviour.
  * @returns A complete adapter, ready to register on an `AdapterRegistry`.
  * @throws Nothing itself. The returned adapter's `read` and `write` raise `AdapterError` for content
@@ -1398,11 +1453,14 @@ interface DirectoryEntry {
  * `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.
  *
- * The seam carries every file the SDK touches: the run-status file, the lock-file, the config
- * glossary, workbook and interchange I/O, and the locale files themselves, which the adapters read
- * and write through a port built from this one. The single exception is a caller-supplied
- * `deps.adapterRegistry`: those adapters were constructed by the caller, so their file access is
- * whatever the caller wired into them, and supplying both means the caller owns that wiring.
+ * The seam carries every file the SDK touches once a config is loaded: the run-status file, the
+ * lock-file and the write locks, the translation-memory cache, the config glossary, workbook and TMX
+ * I/O, generated declaration and pseudolocale files, the source scan, and the locale files
+ * themselves, which the adapters read and write through a port built from this one. Two exceptions
+ * remain. {@link loadConfig} finds and loads the config file itself directly from disk; only its
+ * glossary goes through the port. And a caller-supplied `deps.adapterRegistry` holds adapters the
+ * caller constructed, so their file access is whatever the caller wired into them, and supplying
+ * both means the caller owns that wiring.
  *
  * 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
@@ -1411,7 +1469,7 @@ interface DirectoryEntry {
  * directory tree must also implement `mkdir`.
  */
 interface SdkFs {
-    /** Reports whether a readable file exists at the path. */
+    /** Reports whether a file exists at the path. The default implementation checks existence only. */
     fileExists(path: string): Promise<boolean>;
     /** Reads a file as UTF-8 text, refusing to read more than `maxBytes`. */
     readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
@@ -1531,8 +1589,9 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
  * 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`, or
  * `GOOGLE_TRANSLATE_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.
+ * control. The `openai-compatible` variant reads `OPENAI_COMPATIBLE_API_KEY` when it is set and
+ * sends no real key otherwise, since a local server usually needs none; naming a different variable
+ * through `apiKeyEnvVar` makes that variable required. It still never holds the key itself.
  */
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
 /**
@@ -1553,6 +1612,11 @@ type ProviderId = ProviderConfig["id"];
  * optional `$schema` key, accepted so a JSON or YAML config can point an editor at the JSON Schema
  * document the package ships as `@verbatra/sdk/config-schema.json`.
  *
+ * `format` accepts a built-in format name or a `custom:` identifier such as `custom:toml`. A
+ * `custom:` identifier is checked for shape only; the adapter behind it is supplied through a
+ * flow's `adapterRegistry` dependency, and a run whose registry holds none fails with
+ * `UNKNOWN_FORMAT`.
+ *
  * `fuzzyCache` is off unless `enabled` is set. With it on, a source string whose earlier form is in
  * the translation memory close enough to clear `threshold` reuses that translation instead of
  * paying the provider for it. `threshold` is a similarity ratio from `0.5` to `1` and defaults to `0.9`.
@@ -2005,7 +2069,9 @@ interface LoadConfigOptions {
 type ConfigSource = {
     /**
      * `search` means cosmiconfig found the file by walking up from the working directory, up to
-     * the nearest `.git` directory; `explicit` means the caller named it through `configPath`.
+     * the nearest `.git` directory or, failing that, the home directory or the working directory
+     * itself (see {@link loadConfigWithMeta}); `explicit` means the caller named it through
+     * `configPath`.
      */
     readonly kind: "search" | "explicit";
     /** The absolute path of the config file that was loaded. */
@@ -2029,8 +2095,8 @@ interface LoadedConfig {
  * config file is in effect, or to distinguish an inline glossary from a glossary file.
  *
  * 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`. The upward search stops at the nearest ancestor directory
+ * cosmiconfig search upward from `cwd` across `verbatra.config.ts`, `.js` and `.cjs`, the
+ * `.verbatrarc` family, and a `verbatra` property in `package.json`. The upward search stops at the nearest ancestor directory
  * containing a `.git` entry; if none is found, it stops at the user's home directory when that is an
  * ancestor of `cwd`, and otherwise it does not search above `cwd` at all, so a nested workspace
  * package finds a config at its monorepo root without wandering above it, and a project outside the
@@ -2107,19 +2173,36 @@ interface ProviderBilling {
     readonly billedByApi: boolean;
 }
 
+/**
+ * The zod schema for one token-billed rate entry: an input and an output price per million
+ * tokens, each at most `MAX_RATE` currency units.
+ */
 declare const tokenRateSchema: z.ZodObject<{
     inputPerMillionTokens: z.ZodNumber;
     outputPerMillionTokens: z.ZodNumber;
 }, z.core.$strict>;
+/**
+ * The zod schema for one character-billed rate entry (DeepL, Google Cloud Translation): a
+ * price per million source characters.
+ */
 declare const characterRateSchema: z.ZodObject<{
     perMillionCharacters: z.ZodNumber;
 }, z.core.$strict>;
+/**
+ * The zod schema for one `rates.table` entry: either {@link tokenRateSchema} or
+ * {@link characterRateSchema}, never a mix of the two shapes.
+ */
 declare const modelRateSchema: z.ZodUnion<readonly [z.ZodObject<{
     inputPerMillionTokens: z.ZodNumber;
     outputPerMillionTokens: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
     perMillionCharacters: z.ZodNumber;
 }, z.core.$strict>]>;
+/**
+ * The zod schema for the optional `rates` block: the `asOf` date and `currency` printed beside
+ * every priced estimate, plus a `table` of {@link modelRateSchema} entries keyed by rate key
+ * (`provider/model`, or the bare provider id for a provider without a model).
+ */
 declare const rateCardSchema: z.ZodObject<{
     asOf: z.ZodISODate;
     currency: z.ZodString;
@@ -2167,17 +2250,20 @@ type RateCard = z.infer<typeof rateCardSchema>;
  *   file could not be resolved or parsed. Thrown by {@link loadConfig} and
  *   {@link loadConfigWithMeta}, by {@link readGlossaryFile}, and by {@link updateGlossaryTerm},
  *   which additionally throws it for a blank term or translation and for an edit whose result would
- *   exceed the glossary file size limit. {@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.
+ *   exceed the glossary file size limit. {@link importTmx} and {@link exportTmx} throw it when the
+ *   source locale and a target locale are the same language tag once case and separators are
+ *   normalized, since a TMX segment could not be attributed to either. {@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. {@link doctor} is the exception: it
  *   reports an unresolvable format as a failed `format-adapter` check instead, since reporting that
  *   is the command's job.
  * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales. Thrown through
  *   the shared locale selection by {@link translate}, {@link watch}, {@link check}, {@link diff},
- *   {@link keyIntegrity}, {@link lockState}, {@link exportWorkbook}, {@link keyValue},
- *   {@link editEntry}, and {@link retranslateEntry}. {@link translate} throws it before anything is
+ *   {@link keyIntegrity}, {@link lockState}, {@link localeValues}, {@link exportWorkbook},
+ *   {@link exportTmx}, {@link importTmx}, {@link keyValue}, {@link editEntry}, and
+ *   {@link retranslateEntry}. {@link translate} throws it before anything is
  *   read or spent, and {@link watch} once at startup, before any watching begins.
  * - `UNKNOWN_KEY`: the requested key is not present in the source resource. Thrown by
  *   {@link keyValue}, {@link editEntry}, and {@link retranslateEntry}.
@@ -2186,9 +2272,12 @@ type RateCard = z.infer<typeof rateCardSchema>;
  *   {@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.
+ *   {@link importWorkbook} and {@link importTmx} additionally throw it when the handoff or TMX file
+ *   itself is missing.
  * - `SOURCE_INVALID`: the source locale file, or an interchange file, could not be parsed. Wraps
- *   the adapter or reader error.
+ *   the adapter or reader error. {@link pseudolocalize} also throws it when, for a format whose
+ *   writer only patches an existing document, the source file could not be copied to seed the
+ *   output.
  * - `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},
@@ -2226,7 +2315,7 @@ type RateCard = z.infer<typeof rateCardSchema>;
  *   writable, does not exist, is read-only, or is out of space. The message names the target file
  *   relative to `cwd` and the underlying file-system code, never the internal temporary file the
  *   atomic write uses. 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 that
+ *   locale, and by {@link pseudolocalize} for the pseudolocale file. {@link translate} and {@link importWorkbook} do not throw it: they record it on that
  *   locale's {@link LocaleSummary} and carry on with the other locales.
  * - `PSEUDO_OUTPUT_CONFLICT`: {@link pseudolocalize} was asked to generate a pseudolocale that
  *   names a configured locale, or to write one onto a configured locale file. Refused before
@@ -2257,7 +2346,8 @@ type RateCard = z.infer<typeof rateCardSchema>;
 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" | "GLOSSARY_NOT_FILE_BACKED" | "GLOSSARY_UNWRITABLE" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "TARGET_UNWRITABLE" | "PSEUDO_OUTPUT_CONFLICT" | "SOURCE_UNWRITABLE" | "EXTRACT_NOT_CONFIGURED" | "EXTRACT_FS_UNSUPPORTED" | "TYPES_OUTPUT_CONFLICT" | "TYPES_UNWRITABLE" | "LOCALE_FAILED";
 /**
  * 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
+ * carrying a stable {@link SdkErrorCode}, except the few a flow's `@throws` names as passed through
+ * unwrapped (a failed workbook write, a watcher factory that throws); 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.
@@ -2282,17 +2372,19 @@ declare class SdkError extends Error {
  * 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.
+ * - `PLURAL_CATEGORIES_INCOMPLETE`: `i18next-json` only. The target language needs CLDR plural
+ *   categories the source does not supply and that plural generation did not produce (it is off,
+ *   the provider is not an LLM, or a generated form was withheld), so the missing forms have to be
+ *   added by hand.
+ * - `SUB_BATCH_FAILED`: one provider sub-batch of a locale failed. Its keys are withheld and retried
+ *   on the next run, while the results of the other sub-batches are kept.
  * - `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 reached. Under `warn` the run
  *   continues and the overrun is reported; under `stop` the request that would have crossed the
  *   ceiling is withheld before it is sent, and so is every request after it.
  * - `CACHE_VERSION_UNRECOGNIZED`: the translation memory is at a version this release does not
- *   understand, so it was ignored rather than trusted.
+ *   understand, so the run used no cache and left the file untouched.
  */
 type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED" | "CACHE_VERSION_UNRECOGNIZED";
 /**
@@ -2344,7 +2436,8 @@ interface RunBudget {
      * Whether {@link tokensUsed} is entirely the provider's own reported usage. False as soon as one
      * counted request came back without a usable figure, so the total is partly verbatra's own
      * projection: a machine-translation API reports none at all, and a failed or truncated request
-     * reports none either. The budget is enforced either way.
+     * reports none either. Also false when the run sent no request at all, a dry run included, in
+     * which case nothing was counted. The budget is enforced either way.
      */
     readonly supported: boolean;
     /**
@@ -2372,6 +2465,7 @@ type EstimatePricing = "priced" | "no-rate-on-file" | "rate-unit-mismatch" | "no
 /**
  * What a pre-run estimate deliberately leaves out. Each code names a way the real run can land
  * below the figure, above it, or away from it, so an estimate is never mistaken for an invoice.
+ * The first three apply to every estimate; the last three only to a token-billed provider.
  *
  * - `CACHE_NOT_CONSULTED`: the estimate does not read the translation memory, so keys a live run
  *   would serve from cache are still counted.
@@ -2478,6 +2572,7 @@ interface CharacterRunQuantity extends EstimateIdentity {
  * and the other one is never readable as a zero.
  */
 type RunEstimateQuantity = TokenRunQuantity | CharacterRunQuantity;
+/** The money half of a {@link PricedRunEstimate}: the figure, its currency, and its date. */
 interface PricedEstimateMoney {
     /** Always `priced`: a rate was found and applied. */
     readonly pricing: "priced";
@@ -2493,6 +2588,7 @@ interface PricedEstimateMoney {
     /** The estimated total, in {@link currency}. */
     readonly cost: number;
 }
+/** The money half of an {@link UnpricedRunEstimate}: why there is no figure, and no figure. */
 interface UnpricedEstimateMoney {
     /** Why no currency figure is present. See {@link EstimatePricing}. */
     readonly pricing: Exclude<EstimatePricing, "priced">;
@@ -2505,12 +2601,16 @@ interface UnpricedEstimateMoney {
     /** Never present: an absent rate is reported as absent, never as a cost of zero. */
     readonly cost?: undefined;
 }
+/** A priced estimate for a token-billed provider: prompt and completion tokens, and their cost. */
 interface TokenPricedRunEstimate extends TokenRunQuantity, PricedEstimateMoney {
 }
+/** A priced estimate for a character-billed provider: source characters, and their cost. */
 interface CharacterPricedRunEstimate extends CharacterRunQuantity, PricedEstimateMoney {
 }
+/** An unpriced estimate for a token-billed provider: prompt and completion tokens, no cost. */
 interface TokenUnpricedRunEstimate extends TokenRunQuantity, UnpricedEstimateMoney {
 }
+/** An unpriced estimate for a character-billed provider: source characters, no cost. */
 interface CharacterUnpricedRunEstimate extends CharacterRunQuantity, UnpricedEstimateMoney {
 }
 /**
@@ -2562,8 +2662,9 @@ interface SdkNotice {
  */
 type LocaleNotice = ProviderNotice | SdkNotice;
 /**
- * A translated key the provider layer flagged as worth a human look. The translation was still
- * written; these are advisory quality signals, not rejections.
+ * A key written in this run that was flagged as worth a human look, whether by the provider layer's
+ * quality heuristics, a configured `maxLength` budget, or a fuzzy translation-memory reuse. The
+ * value was still written; these are advisory quality signals, not rejections.
  */
 interface NeedsReviewEntry {
     /** The key that was flagged. */
@@ -2591,8 +2692,9 @@ interface FuzzyCacheHit {
     /** The key's source text at the time this translation was produced. */
     readonly previousSource: string;
     /**
-     * How alike {@link previousSource} and the current source are, from `0` to `1`, as measured by
-     * the configured `fuzzyCache.threshold`. Always at or above that threshold.
+     * How alike {@link previousSource} and the current source are, from `0` to `1`: one minus the
+     * character edit distance divided by the longer string's length, after Unicode normalization.
+     * Always at or above the configured `fuzzyCache.threshold`.
      */
     readonly similarity: number;
 }
@@ -2632,11 +2734,18 @@ interface LocaleSummary {
     /** The target locale this summary describes. */
     readonly locale: string;
     /**
-     * `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.
+     * `succeeded` when no key was withheld by the integrity gate, a provider failure, or the token
+     * budget; `partial` when some keys were withheld and others landed; `failed` when keys were
+     * withheld and none landed, or when the locale threw. Keys skipped for invalid ICU source and
+     * handoff rows left blank do not change the status.
      */
     readonly status: "succeeded" | "partial" | "failed";
-    /** Keys newly translated by the provider in this run. */
+    /**
+     * Keys that received a new value in this run: from the provider for {@link translate}, keys
+     * sharing a translated key's source text included, or from the handoff for
+     * {@link importWorkbook}. On a dry run, the keys a live run would send; cache hits are not
+     * separated out, because a dry run does not read the translation memory.
+     */
     readonly translated: readonly string[];
     /** Keys already up to date against the lock-file baseline, so no provider call was made. */
     readonly unchanged: readonly string[];
@@ -2683,7 +2792,10 @@ interface LocaleSummary {
     readonly notices: readonly LocaleNotice[];
     /** Translated keys flagged as worth a human look. The translations were still written. */
     readonly needsReview: readonly NeedsReviewEntry[];
-    /** Keys left with no translation after the run, whatever the cause. */
+    /**
+     * Keys an imported handoff left blank while they were missing or out of date in this locale.
+     * Always empty for a {@link translate} run.
+     */
     readonly unfilled: readonly string[];
     /** Unreadable rows from an imported handoff. Always empty for a {@link translate} run. */
     readonly malformedRows: readonly MalformedRowReport[];
@@ -2757,6 +2869,9 @@ type BudgetStanding = "within" | "stopped-before-ceiling" | "reached";
 /**
  * Classifies a {@link RunBudget} into its {@link BudgetStanding}, so every surface that reports a
  * budget tells a `stop` run halted short of its ceiling apart from one that actually reached it.
+ *
+ * @param budget - The budget from {@link RunSummary.budget} or {@link RunStatusFile.budget}.
+ * @returns The standing. Pure; throws nothing.
  */
 declare function budgetStanding(budget: RunBudget): BudgetStanding;
 
@@ -3049,8 +3164,8 @@ interface DiffDeps {
  * head could reach as `possiblyDynamic`, never as `unused`. The report is `complete` only when the
  * scan can bound every key the source reaches; otherwise it is `unreliable` and names each reason
  * with its sites, or `not-run` with a reason code and no key list at all when there is nothing
- * trustworthy to judge by (no `extract` block, a format whose runtime is not modeled, no source
- * file, or no reference anywhere in the scanned files).
+ * trustworthy to judge by (no `extract` block, a file system with no `readDirectory`, a format
+ * whose runtime is not modeled, no source file, or no reference anywhere in the scanned files).
  *
  * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
  * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
@@ -3122,8 +3237,9 @@ interface DoctorResult {
     readonly checks: readonly DoctorCheck[];
     /**
      * What the untranslated-literal scan found. Present only on a literal run whose scan actually
-     * ran; absent when the config could not be loaded, no `extract` block is configured, or the
-     * file system cannot list directories.
+     * ran; absent when the config could not be loaded, no `extract` block is configured, the file
+     * system cannot list directories, or the scan failed to start, each of which fails the
+     * `untranslated-literals` check instead.
      */
     readonly literals?: LiteralScan;
 }
@@ -3147,8 +3263,8 @@ interface DoctorDeps {
     readonly adapterRegistry?: AdapterRegistry;
     /**
      * File-system port. Threaded into the config loader, so it backs the glossary-file read the
-     * `config` check performs, and used to read and parse the source locale file. Defaults to the
-     * real file system.
+     * `config` check performs, and used to read and parse the source locale file. On a literal run it
+     * backs the source scan, which needs its `readDirectory` member. Defaults to the real file system.
      */
     readonly fs?: SdkFs;
     /** Config loader. Defaults to {@link loadConfigWithMeta}. */
@@ -3217,8 +3333,10 @@ declare function doctor(input?: DoctorInput, deps?: DoctorDeps): Promise<DoctorR
 
 /**
  * Every reason a candidate translation can be refused before it is 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.
+ * every write path: a provider translation, a cache or duplicate-content reuse, a generated plural
+ * form, a pseudolocalized value, a workbook or TMX import, {@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.
@@ -3347,8 +3465,8 @@ type EditEntryResult = {
  * 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
+ * placeholder, breaks the source's inline markup, 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
@@ -3356,7 +3474,8 @@ type EditEntryResult = {
  * 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.
+ * reuses the edited text rather than paying the provider to translate it again. No review reason
+ * is computed for a hand-edited value, so a configured `maxLength` budget is not checked here.
  *
  * Note that the target locale file surfaces the adapter's own error and code rather than a wrapped
  * {@link SdkError}, on the write as well as on the read, because only the source read is wrapped.
@@ -3398,9 +3517,9 @@ interface AddedKey {
     readonly key: string;
     /** The value written into the catalog: the call site's default, or the empty string when it had none. */
     readonly value: string;
-    /** The source file the key was found in, relative to the run's working directory. */
+    /** The source file of the key's first call site, relative to the run's working directory. */
     readonly file: string;
-    /** The one-based line the key was found on. */
+    /** The one-based line of the key's first call site. */
     readonly line: number;
 }
 /**
@@ -3495,7 +3614,16 @@ interface ExtractDeps {
  */
 declare function extract(input: ExtractInput, deps?: ExtractDeps): Promise<ExtractResult>;
 
-/** Why verbatra declined to describe a message's arguments rather than guessing at them. */
+/**
+ * Why verbatra declined to describe a message's arguments rather than guessing at them.
+ *
+ * - `invalid-message-syntax`: the message does not parse as ICU under a format that reads its
+ *   arguments that way, or the adapter reports it as invalid.
+ * - `mixed-argument-styles`: the message combines named arguments with numbered or unnumbered
+ *   ones, or numbered with unnumbered ones, so no single call signature fits it.
+ * - `argument-index-out-of-range`: a numbered argument addresses a zero-based position below 0 or
+ *   of 64 or more (such as `%0$s` or `{64}`).
+ */
 type UnresolvedArgumentReason = "invalid-message-syntax" | "mixed-argument-styles" | "argument-index-out-of-range";
 
 /**
@@ -3566,7 +3694,10 @@ interface GenerateTypesResult {
     readonly excluded: readonly string[];
     /** Keys the adapter marked as carrying plural forms. Each sibling is declared on its own. */
     readonly plural: readonly string[];
-    /** Whether the declaration file was written. Always false in `check` mode. */
+    /**
+     * Whether the declaration file was written. False in `check` mode, and false when the file on
+     * disk already matched, so an unchanged catalog rewrites nothing.
+     */
     readonly written: boolean;
     /** Whether the file on disk differed from the freshly generated declaration when the run started. */
     readonly stale: boolean;
@@ -3594,12 +3725,14 @@ interface GenerateTypesResult {
  * What it will not claim is as important as what it will. A message whose placeholders name their
  * arguments gets an object shape; one whose placeholders are numbered or anonymous gets a readonly
  * tuple; one that takes nothing gets a shape that makes passing an argument a type error. A
- * message whose syntax the adapter reported as invalid, and one that appears to name and number
- * its arguments at once, are declared with {@link GenerateTypesResult.unresolved} recording why,
- * rather than being silently declared as taking nothing. Argument types come only from what the
- * catalog actually records: `number` where the format annotated one, and a `string | number` alias
- * everywhere else, never a permissive `any`. A name used with several types is declared as the
- * union of what each use accepts.
+ * message whose syntax the adapter reported as invalid, one that mixes named, numbered and
+ * anonymous arguments, and one that numbers an argument past the 64th are declared with
+ * {@link GenerateTypesResult.unresolved} recording why, rather than being silently declared as
+ * taking nothing. Argument types come only from what the catalog actually records: `number` for a
+ * numeric annotation, printf conversion or ICU `plural`, `string` for a text conversion or ICU
+ * `select`, `Date | number` for a date or time argument, and a `string | number` alias everywhere
+ * else, never a permissive `any`. A name used with several types is declared as the union of what
+ * each use accepts.
  *
  * With `check` set, nothing is written: the run reports whether the committed file still matches
  * what a fresh generation would produce, which is the shape a CI gate wants.
@@ -3628,7 +3761,7 @@ interface GenerateTypesResult {
  */
 declare function generateTypes(input: GenerateTypesInput, deps?: GenerateTypesDeps): Promise<GenerateTypesResult>;
 
-/** One key's placeholder and ICU verdict in a {@link LocaleKeyIntegrity} report. */
+/** One key's placeholder, ICU, and inline-markup verdict in a {@link LocaleKeyIntegrity} report. */
 interface KeyIntegrityEntry {
     /** The key this verdict describes. */
     readonly key: string;
@@ -3672,7 +3805,11 @@ interface KeyIntegrityInput {
     readonly cwd?: string;
     /** Restrict the report to these target locales. Defaults to every configured target locale. */
     readonly locales?: readonly string[];
-    /** Restrict the report to these keys. Defaults to every key the diff reports as changed. */
+    /**
+     * Restrict the report to these keys. Only keys the diff reports as changed are ever judged, so a
+     * requested key that is missing, orphaned, or up to date is left out rather than reported.
+     * Defaults to every changed key.
+     */
     readonly keys?: readonly string[];
 }
 /** Injectable dependencies for {@link keyIntegrity}. Every field has a working default. */
@@ -3684,15 +3821,17 @@ interface KeyIntegrityDeps {
 }
 /**
  * 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.
+ * placeholders and inline markup 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 placeholder, ICU and inline-markup checks the gate that
- * {@link editEntry} and {@link retranslateEntry} enforce at write time, and the data behind a
+ * This is the read-only counterpart to the placeholder, ICU and inline-markup checks of the
+ * write-time integrity gate that {@link translate}, {@link editEntry}, {@link retranslateEntry},
+ * and the workbook and TMX imports enforce, and the data behind a
  * review dashboard's per-key integrity indicator. Reporting markup here is what makes drift that
  * predates the gate visible at all: a translation written before the check existed, edited outside
  * verbatra, or produced by a path that never crossed the gate is judged here by the same rule.
@@ -4019,7 +4158,8 @@ interface PseudolocalizeInput {
     readonly cwd?: string;
     /**
      * The pseudolocale's BCP-47 code. Defaults to `en-XA`. It must not be the source locale or any
-     * configured target locale, so a pseudolocale can never stand in for a real translation.
+     * configured target locale, compared case-insensitively, so a pseudolocale can never stand in for
+     * a real translation.
      */
     readonly locale?: string;
     /**
@@ -4028,9 +4168,9 @@ interface PseudolocalizeInput {
      * `files.pattern` is expanded inside it, so the file keeps the layout the application expects.
      *
      * It must name a directory inside `cwd`: an absolute path, one that climbs out with `..`, and
-     * `cwd` itself are all refused, as is any directory that already holds a configured locale file,
-     * so a generated pseudolocale never lands outside the project or beside the real translations
-     * where nothing ignores it.
+     * `cwd` itself are all refused, as is a directory under which the expanded pattern would place
+     * the pseudolocale file beside a configured locale file, so a generated pseudolocale never lands
+     * outside the project or beside the real translations where nothing ignores it.
      */
     readonly out?: string;
 }
@@ -4076,8 +4216,8 @@ interface PseudolocalizeResult {
  *
  * The output is deliberately kept out of the project's real locale files: it is written under
  * `.verbatra-local/pseudo` by default, which `verbatra init` already adds to `.gitignore`, and the
- * pseudolocale is refused when it names a configured locale, when the output directory already
- * holds a configured locale file, and when it is directed at the project root or outside the
+ * pseudolocale is refused when it names a configured locale, when its file would land in the same
+ * directory as a configured locale file, and when it is directed at the project root or outside the
  * working directory. Because it lives outside `files.pattern`, {@link translate} never spends on it and
  * {@link check} and {@link diff} never report it as drifted.
  *
@@ -4098,9 +4238,9 @@ interface PseudolocalizeResult {
  * console.log(`${result.transformed} of ${result.entries} entries in ${result.path}`);
  * ```
  *
- * @throws {@link SdkError} `PSEUDO_OUTPUT_CONFLICT`: the pseudolocale names a configured locale, the
- * output directory already holds a configured locale file, or it is not a relative path naming a
- * directory inside `cwd`.
+ * @throws {@link SdkError} `PSEUDO_OUTPUT_CONFLICT`: the pseudolocale names a configured locale, its
+ * file would land in the same directory as a configured locale file, or the output directory is not
+ * a relative path naming a directory inside `cwd`.
  * @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 the pseudolocale has no valid path spelling under that style.
@@ -4154,9 +4294,11 @@ type RetranslateEntryResult = {
     /** 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.
+     * Quality signals the provider layer raised for this value, such as a length-ratio outlier,
+     * a value identical to the source, or `MAX_LENGTH_EXCEEDED` for a value over the key's
+     * configured `maxLength` budget. Never `FUZZY_CACHE_REUSE`, since this path always calls the
+     * provider and never consults the translation memory. Empty when nothing was flagged. The
+     * value is written either way; these are advisory.
      */
     readonly reviewReasons: readonly ReviewReasonCode[];
 } | {
@@ -4181,7 +4323,8 @@ type RetranslateEntryResult = {
  * 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
+ * loses a placeholder, breaks the source's inline markup, breaks ICU syntax, degenerates into
+ * runaway output, or comes back blank 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
@@ -4383,20 +4526,22 @@ interface ExportTmxDeps {
  * the same set a run would reuse, so the file describes the memory as it is actually being used
  * rather than every translation the project has ever produced. One `tu` element is written per
  * distinct source string, carrying the source segment and one target segment per exported locale.
- * An empty memory produces a valid, empty TMX file rather than an error.
+ * An empty memory, including a missing, unparsable or newer-version cache file, produces a valid,
+ * empty TMX file rather than an error. An existing file at the output path is replaced.
+ *
+ * It reads the memory and writes a file; it never changes the memory, which is why the CLI refuses
+ * `--dry-run` and `--overwrite` on this direction rather than accepting and ignoring them.
  *
  * @param input - The config, the output path, the locale subset, and the tool version to stamp.
  * @param deps - Optional file-system override.
  * @returns The path written, the unit count, and what was left out.
  *
- * It reads the memory and writes a file; it never changes the memory, which is why the CLI refuses
- * `--dry-run` and `--overwrite` on this direction rather than accepting and ignoring them.
- *
  * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  * @throws {@link SdkError} `CONFIG_INVALID`: the source locale and one of the target locales are the
  * same language tag once case and separators are normalized. Writing that file would produce two
  * language attributes {@link importTmx} could not tell apart, so the file this project exported
  * would be one it refuses to read back.
+ * @throws The underlying file-system error, unwrapped, when the output file could not be written.
  *
  * @example
  * ```ts
@@ -4615,6 +4760,9 @@ interface ImportTmxDeps {
  * @returns What was read, what was stored, and everything that was skipped or refused.
  *
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the source locale and one of the target locales are the
+ * same language tag once case and separators are normalized, so a segment could not be attributed
+ * to either.
  * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: no file exists at the given path.
  * @throws {@link SdkError} `SOURCE_INVALID`: the file is oversized, malformed, not a TMX document,
@@ -4690,6 +4838,10 @@ interface LocaleStartedEvent {
  * 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.
+ *
+ * Only the translation batches emit it. A dry run sends nothing and emits none, and neither do the
+ * plural-generation requests, so `totalBatches` counts translation batches alone. Keys served from
+ * the translation memory are not batched, so a fully cached locale emits none either.
  */
 interface SubBatchProgressEvent {
     /** Discriminant for {@link ProgressEvent}. */
@@ -4707,14 +4859,17 @@ interface LocaleFinishedEvent {
     readonly type: "locale-finished";
     /** The locale that finished. */
     readonly locale: string;
-    /** How many keys were newly translated for this locale. */
+    /** The length of the locale's {@link LocaleSummary.translated} list. */
     readonly translated: number;
     /** This locale's 0-based position among the run's locales. */
     readonly localeIndex: number;
     /** How many locales the run covers in total. */
     readonly totalLocales: number;
 }
-/** Emitted once, after every locale has finished. */
+/**
+ * Emitted once, after every locale has finished. Not emitted when the run rejects part way, as it
+ * does on a corrupt lock-file.
+ */
 interface RunFinishedEvent {
     /** Discriminant for {@link ProgressEvent}. */
     readonly type: "run-finished";
@@ -4731,7 +4886,10 @@ type ProgressListener = (event: ProgressEvent) => void;
 interface TranslateInput {
     /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    /**
+     * Directory the `files.pattern` is resolved against, and where the lock-file, the translation
+     * memory, and the run-status file live. Defaults to the process working directory.
+     */
     readonly cwd?: string;
     /**
      * Restrict the run to a subset of the configured target locales, which is how you translate one
@@ -4772,7 +4930,8 @@ interface TranslateInput {
     readonly prune?: boolean;
     /**
      * Generate the plural categories a target language requires rather than translating each
-     * category separately. Defaults to the config's `generatePlurals`, then to false.
+     * category separately. Defaults to the config's `generatePlurals`, then to false. Takes effect
+     * only with an LLM provider; a machine-translation provider generates nothing.
      */
     readonly generatePlurals?: boolean;
     /**
@@ -4782,7 +4941,10 @@ interface TranslateInput {
     readonly onLockWait?: LockWaitListener;
     /** Called as locales and sub-batches start and finish, for progress reporting. */
     readonly onProgress?: ProgressListener;
-    /** How long to wait for a locale's write lock before failing with `LOCK_CONTENDED`. */
+    /**
+     * How long, in milliseconds, to wait for a locale's write lock before that locale fails with
+     * `LOCK_CONTENDED`. Defaults to ten minutes. Not used on a dry run, which takes no lock.
+     */
     readonly lockAcquireTimeoutMs?: number;
     /**
      * How many locales to run at once. Must be an integer of at least 1; defaults to 1. On a live
@@ -4792,8 +4954,9 @@ interface TranslateInput {
      */
     readonly concurrency?: number;
     /**
-     * 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.
+     * Consult and update the translation memory, fuzzy reuse included. 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. A dry run never reads the memory, whatever this says.
      */
     readonly cache?: boolean;
 }
@@ -4826,14 +4989,18 @@ interface TranslateDeps {
  * ```
  */
 declare function resolveDryRun(input: {
+    /** The caller's {@link TranslateInput.dryRun}. */
     readonly dryRun?: boolean | undefined;
+    /** The caller's {@link TranslateInput.estimate}, which implies a dry run. */
     readonly estimate?: boolean | undefined;
 }): boolean;
 /**
  * Runs the one-shot translation flow over every configured target locale, or over the subset named
  * by `locales`: 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.
+ * and ICU integrity, write the locale files, and update the lock-file and translation memory. A
+ * live run also records its summary in the run-status file that {@link runStatus} reads; a failure
+ * to write that file or the translation memory is swallowed rather than failing the run.
  *
  * 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
@@ -4963,7 +5130,10 @@ interface ExportWorkbookDeps {
 }
 /** What {@link exportWorkbook} wrote. */
 interface ExportWorkbookResult {
-    /** The absolute path written, or the shared base path when one file per locale was written. */
+    /**
+     * The absolute path written: the workbook file for `xlsx`, or the directory the per-locale files
+     * were written into for a delimited format.
+     */
     readonly path: string;
     /** Row counts per exported locale. */
     readonly locales: readonly {
@@ -4975,7 +5145,10 @@ interface ExportWorkbookResult {
 }
 /**
  * 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.
+ * `.xlsx` workbook with one sheet per locale, or one `.csv` or `.tsv` file per locale. A delimited
+ * export also writes a `.verbatra-export-<format>.json` manifest into the output directory naming
+ * the locales it exported, which {@link importWorkbook} uses to tell a leftover file from an earlier
+ * export apart from a current one.
  *
  * 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
@@ -5051,9 +5224,11 @@ interface ImportWorkbookDeps {
  * 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.
+ * a placeholder, breaks inline markup or breaks ICU syntax has that row refused rather than
+ * written, and a row whose source text changed since the export is refused the same way. A row
+ * holding exactly `[[CLEAR]]` empties that key's translation. 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.
  *
  * 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
@@ -5061,9 +5236,12 @@ interface ImportWorkbookDeps {
  * 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} and {@link RunSummary.partial} rather than
- * relying on a thrown error. A corrupt lock-file is the one exception, because it is a single
+ * still import. A configured target locale the handoff carries no sheet or file for fails with
+ * `WORKBOOK_SHEET_MISSING`, a delimited file the directory's export manifest does not list fails
+ * with `HANDOFF_FILE_STALE` without being applied, and a row naming a key neither the source nor
+ * the target holds fails its locale. Once the handoff has been read, every per-locale failure is
+ * isolated this way, so callers should inspect {@link RunSummary.failed} and
+ * {@link RunSummary.partial} rather than relying on a thrown error. A corrupt lock-file is the one exception, because it is a single
  * shared file rather than a per-locale one: it aborts the whole run even when it is discovered
  * after a locale has been applied, so the locales still to come are not written at all.
  *
@@ -5116,7 +5294,8 @@ interface LocalePathResolverConfig {
     /**
      * The configured format. Every format maps each locale to a distinct path except a
      * shared-catalogue format (one holding every locale in a single file, such as `apple-xcstrings`),
-     * which maps every locale to the same path.
+     * which maps every locale to the same path. A `custom:` format is always treated as one file per
+     * locale.
      */
     readonly format: FormatId$1;
     /** The file layout. */
@@ -5132,12 +5311,15 @@ interface LocalePathResolver {
     /**
      * 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.
+     *
+     * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the locale is outside the configured set and
+     * has no valid single-segment spelling under the configured style.
      */
     pathFor(locale: string): string;
     /**
      * 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.
+     * configured locale. The path is resolved against the resolver's `cwd` and normalized before
+     * lookup, so a relative or non-canonical path still resolves.
      *
      * Always `undefined` for a shared-catalogue format: every configured locale resolves to the same
      * path there, so no single locale owns it.
@@ -5297,7 +5479,10 @@ declare const scaffoldingMetadata: {
         readonly openai: "maxOutputTokens";
         readonly gemini: "maxOutputTokens";
     };
-    /** Every i18n file format the SDK can read and write. */
+    /**
+     * Every built-in i18n file format the SDK can read and write. A `custom:` format is never listed,
+     * since its adapter ships outside verbatra.
+     */
     readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties", "apple-strings", "apple-xcstrings", "android-xml", "gettext-po", "ini", "resx"];
 };
 
@@ -5340,7 +5525,10 @@ type WatchRunResult = {
 interface WatchInput {
     /** The resolved project config, normally from {@link loadConfig}. */
     readonly config: VerbatraConfig;
-    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    /**
+     * Directory the `files.pattern` is resolved against, and where each run's lock-file, translation
+     * memory, and run-status file live. Defaults to the process working directory.
+     */
     readonly cwd?: string;
     /**
      * Restrict every run of the session to a subset of the configured target locales. Validated once
@@ -5359,11 +5547,17 @@ interface WatchInput {
     readonly onLockWait?: LockWaitListener;
     /** Called as locales and sub-batches start and finish, for progress reporting. */
     readonly onProgress?: ProgressListener;
-    /** How long to wait for a locale's write lock before that run fails. */
+    /**
+     * How long, in milliseconds, to wait for a locale's write lock before that locale fails with
+     * `LOCK_CONTENDED` on the run's summary. Defaults to ten minutes.
+     */
     readonly lockAcquireTimeoutMs?: number;
-    /** How many locales to run at once. Validated once when watching starts, and applied to every run. */
+    /**
+     * How many locales to run at once. Defaults to 1. Validated once when watching starts, and
+     * applied to every run.
+     */
     readonly concurrency?: number;
-    /** Consult and update the translation memory. Defaults to true. */
+    /** Consult and update the translation memory, fuzzy reuse included. Defaults to true. */
     readonly cache?: boolean;
 }
 /** Injectable dependencies for {@link watch}. Every field has a working default. */