patina-cli 3.11.0 → 4.0.0

package/docs/API.md

@@ -0,0 +1,1554 @@
+# API Reference
+
+This file is generated from JSDoc comments in `src/*.js`.
+Run `npm run docs:api` after changing public exports or their JSDoc.
+
+## Worked example: programmatic scoring
+
+The package currently publishes these modules for CLI reuse, but deep imports should be treated as unstable until an explicit `exports` map is introduced.
+
+Use `scoreText` directly when you want patina's score envelope inside another Node.js tool. This example injects a mock `callLLM` so the snippet is deterministic; replace it with the default HTTP caller plus provider credentials in production.
+
+```js
+import { getRepoRoot, loadConfig } from 'patina-cli/src/config.js';
+import { loadPatterns } from 'patina-cli/src/loader.js';
+import { scoreText } from 'patina-cli/src/scoring.js';
+
+const config = loadConfig();
+config.language = 'en';
+
+const patterns = loadPatterns(getRepoRoot(), config.language);
+const text = 'Coffee has emerged as a pivotal cultural phenomenon.';
+
+const result = await scoreText({
+  text,
+  config,
+  patterns,
+  model: 'deterministic-example',
+  callLLM: async () => JSON.stringify({
+    categories: {
+      content: { detected: 1, sum: 1, max: 18, score: 5.6, weighted: 1.7 },
+    },
+    overall: 24,
+    interpretation: 'mostly human',
+  }),
+});
+
+console.log(result.overall); // 24 unless deterministic shadow scoring reconciles upward
+console.log(result.interpretation); // mostly human
+```
+
+## Generated reference
+
+<!-- Generated by scripts/generate-api-docs.mjs using jsdoc-to-markdown. Do not edit by hand. -->
+
+## Classes
+
+<a name="HttpError"></a>
+### HttpError
+
+Error raised for non-2xx HTTP responses from an LLM provider.
+
+**Kind**: global class
+
+#### Constructor parameters
+
+| Param | Type | Description |
+| --- | --- | --- |
+| status | `number` | HTTP status code returned by the provider. |
+| body | `string` | Response body text, truncated in the message. |
+| retryAfter | `string` \| `null` | Raw Retry-After response header, if present. |
+
+**Example**
+
+```js
+throw new HttpError(429, 'rate limit', '2');
+```
+
+<a name="PatinaCliError"></a>
+### PatinaCliError
+
+Structured CLI error with separate what/why/action fields and exit code.
+
+**Kind**: global class
+
+#### Constructor parameters
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | `object` | Error fields. |
+| options.what | `string` | Short failure headline. |
+| options.why | `string` | Explanation of the failure. |
+| options.action | `string` | Suggested user action. |
+| [options.exitCode=1] | `number` | Process exit code. |
+
+**Example**
+
+```js
+throw new PatinaCliError({ what: 'missing input', why: 'No file was provided', action: 'Pass a file path.' });
+```
+
+## Constants
+
+<dl>
+<dt><a href="#DEFAULT_TEMPERATURE">DEFAULT_TEMPERATURE</a> : <code>number</code></dt>
+<dd><p>Default sampling temperature for OpenAI-compatible chat completion calls.</p>
+</dd>
+<dt><a href="#HTTP_KEY_ENV_VARS">HTTP_KEY_ENV_VARS</a> : <code>Array.&lt;string&gt;</code></dt>
+<dd><p>Environment variable names checked for HTTP provider authentication.</p>
+</dd>
+<dt><a href="#DEFAULT_HTTP_KEY_ENV_VARS">DEFAULT_HTTP_KEY_ENV_VARS</a> : <code>Array.&lt;string&gt;</code></dt>
+<dd><p>Default key lookup order for the OpenAI-compatible HTTP provider.</p>
+</dd>
+<dt><a href="#defaultLogger">defaultLogger</a> : <code>Object</code></dt>
+<dd><p>Default stderr logger used by simple callers.</p>
+</dd>
+<dt><a href="#PROVIDERS">PROVIDERS</a> : <code>Record.&lt;string, {name: string, baseURL: string, apiKeyEnv: string, defaultModel: string, freeTier: boolean, note: string}&gt;</code></dt>
+<dd><p>Built-in OpenAI-compatible provider presets.</p>
+</dd>
+<dt><a href="#DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD">DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD</a> : <code>number</code></dt>
+<dd><p>Default maximum delta before deterministic and LLM scores are reconciled upward.</p>
+</dd>
+<dt><a href="#LEAKAGE_SCORE_FLOOR">LEAKAGE_SCORE_FLOOR</a> : <code>number</code></dt>
+<dd><p>Score floor applied when deterministic markup-leakage is detected.</p>
+<p>Model-output leakage (issue #332) is near-proof-grade: a single token that
+LLM tooling injects and humans never type. Unlike the stylometric/lexical
+signals it is decisive on its own, so any hit short-circuits the deterministic
+<code>overall</code> into the &#39;heavily AI&#39; band (&gt;70) regardless of the per-paragraph
+hot ratio. It is a floor, not a hard 100, because the surrounding prose may
+still be genuinely human and we avoid claiming absolute proof.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#isRetryable">isRetryable(err)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Decide whether an LLM call failure should be retried.</p>
+</dd>
+<dt><a href="#computeBackoffMs">computeBackoffMs(attempt, retryAfter, [opts])</a> ⇒ <code>number</code></dt>
+<dd><p>Compute retry delay from Retry-After or exponential backoff with jitter.</p>
+</dd>
+<dt><a href="#callLLM">callLLM(options)</a> ⇒ <code>Promise.&lt;string&gt;</code></dt>
+<dd><p>Call an OpenAI-compatible chat completions endpoint with retries, timeout, and abort support.</p>
+</dd>
+<dt><a href="#providerHttpKeyEnvVars">providerHttpKeyEnvVars([providerApiKeyEnv])</a> ⇒ <code>Array.&lt;string&gt;</code></dt>
+<dd><p>Build the key lookup order for a selected provider.</p>
+</dd>
+<dt><a href="#inspectHttpApiKeySource">inspectHttpApiKeySource([options])</a> ⇒ <code>Object</code></dt>
+<dd><p>Inspect where an HTTP API key would be read from without exposing the secret.</p>
+</dd>
+<dt><a href="#resolveHttpApiKey">resolveHttpApiKey([options])</a> ⇒ <code>string</code> | <code>undefined</code></dt>
+<dd><p>Resolve the HTTP API key from a key file or environment.</p>
+</dd>
+<dt><a href="#main">main(args)</a> ⇒ <code>Promise.&lt;void&gt;</code></dt>
+<dd><p>Run the patina CLI command dispatcher.</p>
+</dd>
+<dt><a href="#createCancellationController">createCancellationController([options])</a> ⇒ <code>Object</code></dt>
+<dd><p>Create a SIGINT-aware cancellation controller for long-running CLI operations.</p>
+</dd>
+<dt><a href="#resolveProfileForLanguage">resolveProfileForLanguage(profileName, lang, [logger])</a> ⇒ <code>string</code></dt>
+<dd><p>Resolve a profile name against language-specific profile limits.</p>
+</dd>
+<dt><a href="#loadConfig">loadConfig([path])</a> ⇒ <code>object</code></dt>
+<dd><p>Load default config and merge global/project .patina.yaml overrides.</p>
+</dd>
+<dt><a href="#getRepoRoot">getRepoRoot()</a> ⇒ <code>string</code></dt>
+<dd><p>Return the repository root inferred from this source file location.</p>
+</dd>
+<dt><a href="#resolveTone">resolveTone(options)</a> ⇒ <code>Object</code></dt>
+<dd><p>Resolve CLI/config tone settings into prompt-ready tone metadata.</p>
+</dd>
+<dt><a href="#inputError">inputError(what, why, action)</a> ⇒ <code>PatinaCliError</code></dt>
+<dd><p>Create a user-input error that should exit with code 2.</p>
+</dd>
+<dt><a href="#runtimeError">runtimeError(what, why, action)</a> ⇒ <code>PatinaCliError</code></dt>
+<dd><p>Create a runtime error that should exit with code 1.</p>
+</dd>
+<dt><a href="#renderCliError">renderCliError(err)</a> ⇒ <code>string</code></dt>
+<dd><p>Render any thrown value into the patina CLI error format.</p>
+</dd>
+<dt><a href="#getExitCode">getExitCode(err, [fallback])</a> ⇒ <code>number</code></dt>
+<dd><p>Extract a safe process exit code from an error-like value.</p>
+</dd>
+<dt><a href="#loadFile">loadFile(path)</a> ⇒ <code>string</code></dt>
+<dd><p>Read a UTF-8 text file.</p>
+</dd>
+<dt><a href="#splitFrontmatter">splitFrontmatter(content)</a> ⇒ <code>Object</code></dt>
+<dd><p>Split Markdown-style YAML frontmatter from a document body.</p>
+</dd>
+<dt><a href="#loadPatterns">loadPatterns(repoRoot, lang, [skipPatterns])</a> ⇒ <code>Array.&lt;{file: string, frontmatter: (object|null), body: string, isStructure: boolean, isScoreOnly: boolean}&gt;</code></dt>
+<dd><p>Load language-specific pattern packs from patterns/{lang}-*.md.</p>
+</dd>
+<dt><a href="#loadProfile">loadProfile(repoRoot, profileName)</a> ⇒ <code>Object</code></dt>
+<dd><p>Load a named profile from profiles/{profileName}.md after path validation.</p>
+</dd>
+<dt><a href="#loadCoreFile">loadCoreFile(repoRoot, filename)</a> ⇒ <code>Object</code></dt>
+<dd><p>Load a Markdown file from the core/ directory.</p>
+</dd>
+<dt><a href="#loadInputText">loadInputText(path)</a> ⇒ <code>string</code></dt>
+<dd><p>Read user input text from disk.</p>
+</dd>
+<dt><a href="#loadVoiceSample">loadVoiceSample(path)</a> ⇒ <code>Object</code></dt>
+<dd><p>Load up to three non-empty paragraphs from a voice sample file.</p>
+</dd>
+<dt><a href="#toneToBackboneProfile">toneToBackboneProfile(tone)</a> ⇒ <code>string</code> | <code>null</code></dt>
+<dd><p>Map a resolved named tone to its primary backbone profile.</p>
+</dd>
+<dt><a href="#createLogger">createLogger([options])</a> ⇒ <code>Object</code></dt>
+<dd><p>Create a small stderr logger with text and progress modes.</p>
+</dd>
+<dt><a href="#runOuroboros">runOuroboros(options)</a> ⇒ <code>Promise.&lt;{finalText: string, finalScore: number, iterations: number, reason: string, log: Array.&lt;object&gt;}&gt;</code></dt>
+<dd><p>Run the iterative Ouroboros rewrite-and-score loop.</p>
+</dd>
+<dt><a href="#formatOutput">formatOutput(result, mode, [parsed], [opts])</a> ⇒ <code>string</code></dt>
+<dd><p>Format a raw backend result for CLI output mode and requested format.</p>
+</dd>
+<dt><a href="#shouldColorDiff">shouldColorDiff([options])</a></dt>
+<dd></dd>
+<dt><a href="#validateScoreWeights">validateScoreWeights(output, configWeights)</a> ⇒ <code>Array.&lt;string&gt;</code></dt>
+<dd><p>Validate that a model-emitted score table used configured category weights.</p>
+</dd>
+<dt><a href="#stripSelfAudit">stripSelfAudit(body, [options])</a> ⇒ <code>string</code></dt>
+<dd><p>Remove SELF_AUDIT blocks and unwrap the BODY block from rewrite output.</p>
+</dd>
+<dt><a href="#buildDeterministicAuditBackstop">buildDeterministicAuditBackstop(text, [opts])</a> ⇒ <code>string</code></dt>
+<dd><p>Build a deterministic &quot;backstop&quot; section for audit mode. The LLM audit is
+model-dependent (a weak model silently drops 번역투/calques); these signals are
+computed deterministically so they appear regardless of which model ran. ko
+translationese rules are listed even below the hot-density gate, because audit
+is a hint surface, not a verdict.</p>
+</dd>
+<dt><a href="#buildPrompt">buildPrompt(options)</a> ⇒ <code>string</code></dt>
+<dd><p>Build the LLM prompt for rewrite, diff, audit, score, or ouroboros mode.</p>
+</dd>
+<dt><a href="#isShortText">isShortText(text)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Classify whether text should use the short-text scoring boost.</p>
+</dd>
+<dt><a href="#selectProvider">selectProvider(name)</a> ⇒ <code>object</code> | <code>null</code></dt>
+<dd><p>Resolve a provider preset by name.</p>
+</dd>
+<dt><a href="#resolveProviderConfig">resolveProviderConfig(options)</a> ⇒ <code>Object</code></dt>
+<dd><p>Resolve effective API key, base URL, and model from explicit values, provider, and env.</p>
+</dd>
+<dt><a href="#scoreText">scoreText(options)</a> ⇒ <code>Promise.&lt;object&gt;</code></dt>
+<dd><p>Score text for AI-likeness using an LLM JSON scorer plus deterministic shadow signals.</p>
+</dd>
+<dt><a href="#scoreDeterministicSignals">scoreDeterministicSignals([options])</a> ⇒ <code>object</code> | <code>null</code></dt>
+<dd><p>Compute deterministic stylometry/lexicon AI-likeness signals.</p>
+</dd>
+<dt><a href="#withShadowScore">withShadowScore(parsed, [options])</a> ⇒ <code>object</code></dt>
+<dd><p>Merge an LLM score payload with deterministic shadow-score reconciliation.</p>
+</dd>
+<dt><a href="#reconcileScoreOverall">reconcileScoreOverall([options])</a> ⇒ <code>Object</code></dt>
+<dd><p>Reconcile LLM and deterministic overall scores according to config thresholds.</p>
+</dd>
+<dt><a href="#scoreMPS">scoreMPS(options)</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
+<dd><p>Score meaning preservation between original and rewritten text.</p>
+</dd>
+<dt><a href="#interpretScore">interpretScore(score)</a> ⇒ <code>string</code></dt>
+<dd><p>Convert a numeric AI-likeness score to a human-readable band.</p>
+</dd>
+<dt><a href="#lengthRatioPoints">lengthRatioPoints(original, rewritten)</a> ⇒ <code>number</code></dt>
+<dd><p>Score rewritten length ratio on the 0-3 fidelity scale.</p>
+</dd>
+<dt><a href="#scoreFidelity">scoreFidelity(options)</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
+<dd><p>Score fidelity between original and rewritten text using length plus LLM criteria.</p>
+</dd>
+<dt><a href="#clamp03">clamp03(v)</a> ⇒ <code>number</code></dt>
+<dd><p>Clamp and round a value into the inclusive 0-3 scoring range.</p>
+</dd>
+<dt><a href="#combinedScore">combinedScore(options)</a> ⇒ <code>number</code></dt>
+<dd><p>Combine AI-likeness, inverted fidelity, and optional deterministic score.</p>
+</dd>
+<dt><a href="#validateProfileName">validateProfileName(name)</a> ⇒ <code>void</code></dt>
+<dd><p>Validate a profile name before resolving profiles/{name}.md.</p>
+</dd>
+<dt><a href="#isLoopbackHost">isLoopbackHost(hostname)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Check whether a hostname is localhost or loopback.</p>
+</dd>
+<dt><a href="#isPrivateOrSpecialIP">isPrivateOrSpecialIP(hostname)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Detect literal private, reserved, link-local, metadata, or multicast IP hosts.</p>
+</dd>
+<dt><a href="#validateBaseURL">validateBaseURL(baseURL, [options])</a> ⇒ <code>void</code></dt>
+<dd><p>Validate a provider base URL before sending prompts and bearer tokens.</p>
+</dd>
+<dt><a href="#shouldAllowInsecureBaseURL">shouldAllowInsecureBaseURL([parsed])</a> ⇒ <code>boolean</code></dt>
+<dd><p>Read CLI/env opt-in for non-loopback HTTP base URLs.</p>
+</dd>
+<dt><a href="#applyInsecureBaseURLOptIn">applyInsecureBaseURLOptIn([parsed])</a> ⇒ <code>void</code></dt>
+<dd><p>Persist CLI insecure-base-url opt-in into process.env for downstream calls.</p>
+</dd>
+<dt><a href="#shouldAllowPrivateBaseURL">shouldAllowPrivateBaseURL([parsed])</a> ⇒ <code>boolean</code></dt>
+<dd><p>Read CLI/env opt-in for private or reserved literal IP base URLs.</p>
+</dd>
+<dt><a href="#applyPrivateBaseURLOptIn">applyPrivateBaseURLOptIn([parsed])</a> ⇒ <code>void</code></dt>
+<dd><p>Persist CLI private-base-url opt-in into process.env for downstream calls.</p>
+</dd>
+</dl>
+
+<a name="DEFAULT_TEMPERATURE"></a>
+
+## DEFAULT\_TEMPERATURE : <code>number</code>
+Default sampling temperature for OpenAI-compatible chat completion calls.
+
+**Kind**: global constant
+**Example**
+```js
+const temperature = DEFAULT_TEMPERATURE; // 0.7
+```
+<a name="HTTP_KEY_ENV_VARS"></a>
+
+## HTTP\_KEY\_ENV\_VARS : <code>Array.&lt;string&gt;</code>
+Environment variable names checked for HTTP provider authentication.
+
+**Kind**: global constant
+**Example**
+```js
+const supported = HTTP_KEY_ENV_VARS.includes('OPENAI_API_KEY');
+```
+<a name="DEFAULT_HTTP_KEY_ENV_VARS"></a>
+
+## DEFAULT\_HTTP\_KEY\_ENV\_VARS : <code>Array.&lt;string&gt;</code>
+Default key lookup order for the OpenAI-compatible HTTP provider.
+
+**Kind**: global constant
+**Example**
+```js
+const first = DEFAULT_HTTP_KEY_ENV_VARS[0]; // PATINA_API_KEY
+```
+<a name="defaultLogger"></a>
+
+## defaultLogger : <code>Object</code>
+Default stderr logger used by simple callers.
+
+**Kind**: global constant
+**Example**
+```js
+defaultLogger.info('patina.ready', { message: 'ready' });
+```
+<a name="PROVIDERS"></a>
+
+## PROVIDERS : <code>Record.&lt;string, {name: string, baseURL: string, apiKeyEnv: string, defaultModel: string, freeTier: boolean, note: string}&gt;</code>
+Built-in OpenAI-compatible provider presets.
+
+**Kind**: global constant
+**Example**
+```js
+const openaiBaseURL = PROVIDERS.openai.baseURL;
+```
+<a name="DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD"></a>
+
+## DEFAULT\_DETERMINISTIC\_DIVERGENCE\_THRESHOLD : <code>number</code>
+Default maximum delta before deterministic and LLM scores are reconciled upward.
+
+**Kind**: global constant
+**Example**
+```js
+const threshold = DEFAULT_DETERMINISTIC_DIVERGENCE_THRESHOLD;
+```
+<a name="LEAKAGE_SCORE_FLOOR"></a>
+
+## LEAKAGE\_SCORE\_FLOOR : <code>number</code>
+Score floor applied when deterministic markup-leakage is detected.
+
+Model-output leakage (issue #332) is near-proof-grade: a single token that
+LLM tooling injects and humans never type. Unlike the stylometric/lexical
+signals it is decisive on its own, so any hit short-circuits the deterministic
+`overall` into the 'heavily AI' band (>70) regardless of the per-paragraph
+hot ratio. It is a floor, not a hard 100, because the surrounding prose may
+still be genuinely human and we avoid claiming absolute proof.
+
+**Kind**: global constant
+<a name="isRetryable"></a>
+
+## isRetryable(err) ⇒ <code>boolean</code>
+Decide whether an LLM call failure should be retried.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True for retryable HTTP statuses, aborts, and common network failures.
+**Throws**:
+
+- <code>Error</code> Does not intentionally throw; unexpected Error-like inputs may still propagate JavaScript runtime failures.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| err | <code>Error</code> \| <code>Object</code> | Error thrown by fetch or [HttpError](HttpError). |
+
+**Example**
+```js
+const retry = isRetryable(new HttpError(429, 'rate limit', '1'));
+```
+<a name="computeBackoffMs"></a>
+
+## computeBackoffMs(attempt, retryAfter, [opts]) ⇒ <code>number</code>
+Compute retry delay from Retry-After or exponential backoff with jitter.
+
+**Kind**: global function
+**Returns**: <code>number</code> - Delay in milliseconds, capped at opts.max.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| attempt | <code>number</code> |  | Zero-based retry attempt. |
+| retryAfter | <code>string</code> \| <code>null</code> \| <code>undefined</code> |  | Retry-After seconds or HTTP-date header. |
+| [opts] | <code>object</code> |  | Backoff tuning and deterministic test hooks. |
+| [opts.base] | <code>number</code> | <code>1000</code> | Initial exponential backoff in milliseconds. |
+| [opts.max] | <code>number</code> | <code>30000</code> | Maximum returned delay in milliseconds. |
+| [opts.now] | <code>function</code> |  | Clock returning epoch milliseconds. |
+| [opts.random] | <code>function</code> |  | Random number provider used for jitter. |
+
+**Example**
+```js
+const delay = computeBackoffMs(1, '2'); // 2000
+```
+<a name="callLLM"></a>
+
+## callLLM(options) ⇒ <code>Promise.&lt;string&gt;</code>
+Call an OpenAI-compatible chat completions endpoint with retries, timeout, and abort support.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;string&gt;</code> - Assistant message content.
+**Throws**:
+
+- <code>HttpError</code> When the provider returns a non-2xx response after retries.
+- <code>Error</code> On abort, timeout, malformed provider payload, or base URL validation failure.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>object</code> |  | LLM request options. |
+| options.prompt | <code>string</code> |  | User prompt sent as the single chat message. |
+| [options.apiKey] | <code>string</code> |  | Bearer token for the provider. |
+| [options.baseURL] | <code>string</code> |  | OpenAI-compatible API base URL. Defaults to https://api.openai.com/v1. |
+| [options.model] | <code>string</code> |  | Model id to request. Defaults to gpt-5.5. |
+| [options.temperature] | <code>number</code> | <code>DEFAULT_TEMPERATURE</code> | Sampling temperature. |
+| [options.seed] | <code>number</code> \| <code>string</code> |  | Optional deterministic seed forwarded to the provider. |
+| [options.timeout] | <code>number</code> | <code>120000</code> | Per-attempt timeout in milliseconds. |
+| [options.maxRetries] | <code>number</code> | <code>2</code> | Retry count after the first attempt. |
+| [options.deadline] | <code>number</code> |  | Absolute epoch-millisecond deadline for all attempts. |
+| [options.signal] | <code>AbortSignal</code> |  | External cancellation signal. |
+| [options.allowInsecureBaseURL] | <code>boolean</code> | <code>false</code> | Allow non-loopback HTTP base URLs. |
+| [options.onResponse] | <code>function</code> |  | Callback receiving provider metadata. |
+| [options.sleep] | <code>function</code> |  | Injectable sleep function for tests. |
+| [options.now] | <code>function</code> |  | Clock returning epoch milliseconds. |
+
+**Example**
+```js
+const text = await callLLM({ prompt: 'Rewrite this', apiKey: process.env.OPENAI_API_KEY });
+```
+<a name="providerHttpKeyEnvVars"></a>
+
+## providerHttpKeyEnvVars([providerApiKeyEnv]) ⇒ <code>Array.&lt;string&gt;</code>
+Build the key lookup order for a selected provider.
+
+**Kind**: global function
+**Returns**: <code>Array.&lt;string&gt;</code> - Unique env var names in lookup order.
+**Throws**:
+
+- <code>Error</code> Does not intentionally throw; invalid non-string env names can still propagate JavaScript runtime failures.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [providerApiKeyEnv] | <code>string</code> | Provider-specific key env var, such as GEMINI_API_KEY. |
+
+**Example**
+```js
+const vars = providerHttpKeyEnvVars('GEMINI_API_KEY');
+```
+<a name="inspectHttpApiKeySource"></a>
+
+## inspectHttpApiKeySource([options]) ⇒ <code>Object</code>
+Inspect where an HTTP API key would be read from without exposing the secret.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Source diagnostics.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Inspection options. |
+| [options.env] | <code>object</code> | <code>process.env</code> | Environment map to inspect. |
+| [options.readFile] | <code>function</code> |  | File reader for PATINA_API_KEY_FILE. |
+| [options.envVars] | <code>Array.&lt;string&gt;</code> | <code>DEFAULT_HTTP_KEY_ENV_VARS</code> | Env vars to check. |
+
+**Example**
+```js
+const source = inspectHttpApiKeySource({ env: { PATINA_API_KEY: 'sk-...' } });
+```
+<a name="resolveHttpApiKey"></a>
+
+## resolveHttpApiKey([options]) ⇒ <code>string</code> \| <code>undefined</code>
+Resolve the HTTP API key from a key file or environment.
+
+**Kind**: global function
+**Returns**: <code>string</code> \| <code>undefined</code> - Resolved key value, or undefined when unauthenticated.
+**Throws**:
+
+- <code>PatinaCliError</code> When the configured key file cannot be read or is empty.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Resolution options. |
+| [options.apiKeyFile] | <code>string</code> |  | Explicit key file path. |
+| [options.env] | <code>object</code> | <code>process.env</code> | Environment map. |
+| [options.readFile] | <code>function</code> |  | File reader for key files. |
+| [options.envVars] | <code>Array.&lt;string&gt;</code> | <code>DEFAULT_HTTP_KEY_ENV_VARS</code> | Env var lookup order. |
+
+**Example**
+```js
+const key = resolveHttpApiKey({ env: process.env });
+```
+<a name="main"></a>
+
+## main(args) ⇒ <code>Promise.&lt;void&gt;</code>
+Run the patina CLI command dispatcher.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;void&gt;</code> - Resolves after command output is written.
+**Throws**:
+
+- <code>Error</code> For validation, provider, file, or runtime failures.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| args | <code>Array.&lt;string&gt;</code> | Command-line arguments excluding node and script path. |
+
+**Example**
+```js
+await main(['--help']);
+```
+<a name="createCancellationController"></a>
+
+## createCancellationController([options]) ⇒ <code>Object</code>
+Create a SIGINT-aware cancellation controller for long-running CLI operations.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Controller facade.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Cancellation integration points. |
+| [options.processObj] | <code>NodeJS.Process</code> | <code>process</code> | Process-like object used for signal listeners. |
+| [options.stderr] | <code>NodeJS.WritableStream</code> | <code>process.stderr</code> | Stream for fallback cancel messages. |
+| [options.logger] | <code>object</code> \| <code>null</code> |  | Optional patina logger. |
+
+**Example**
+```js
+const cancellation = createCancellationController();
+cancellation.install();
+```
+<a name="resolveProfileForLanguage"></a>
+
+## resolveProfileForLanguage(profileName, lang, [logger]) ⇒ <code>string</code>
+Resolve a profile name against language-specific profile limits.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Effective profile name.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| profileName | <code>string</code> | Requested profile name. |
+| lang | <code>string</code> | Active language code. |
+| [logger] | <code>object</code> | Logger with warn(event, payload). |
+
+**Example**
+```js
+resolveProfileForLanguage('namuwiki', 'en') // 'default'
+```
+<a name="loadConfig"></a>
+
+## loadConfig([path]) ⇒ <code>object</code>
+Load default config and merge global/project .patina.yaml overrides.
+
+**Kind**: global function
+**Returns**: <code>object</code> - Merged patina configuration object.
+**Throws**:
+
+- <code>Error</code> When a config file is missing, invalid YAML, or not a mapping.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [path] | <code>string</code> | Base YAML config path. |
+
+**Example**
+```js
+const config = loadConfig();
+```
+<a name="getRepoRoot"></a>
+
+## getRepoRoot() ⇒ <code>string</code>
+Return the repository root inferred from this source file location.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Absolute repository root path.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+**Example**
+```js
+const root = getRepoRoot();
+```
+<a name="resolveTone"></a>
+
+## resolveTone(options) ⇒ <code>Object</code>
+Resolve CLI/config tone settings into prompt-ready tone metadata.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Tone metadata.
+**Throws**:
+
+- <code>Error</code> When cliTone or configTone is not supported.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Tone inputs. |
+| [options.cliTone] | <code>string</code> \| <code>null</code> | CLI tone override. |
+| [options.configTone] | <code>string</code> \| <code>null</code> | Configured tone value. |
+| [options.lang] | <code>string</code> | Active language code. |
+
+**Example**
+```js
+const tone = resolveTone({ cliTone: 'casual', lang: 'ko' });
+```
+<a name="inputError"></a>
+
+## inputError(what, why, action) ⇒ <code>PatinaCliError</code>
+Create a user-input error that should exit with code 2.
+
+**Kind**: global function
+**Returns**: <code>PatinaCliError</code> - Structured input error.
+**Throws**:
+
+- <code>Error</code> Does not intentionally throw; returns an Error instance for callers to throw.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| what | <code>string</code> | Short failure headline. |
+| why | <code>string</code> | Explanation of the invalid input. |
+| action | <code>string</code> | Suggested user action. |
+
+**Example**
+```js
+throw inputError('missing input', 'No file was provided.', 'Pass a file path.');
+```
+<a name="runtimeError"></a>
+
+## runtimeError(what, why, action) ⇒ <code>PatinaCliError</code>
+Create a runtime error that should exit with code 1.
+
+**Kind**: global function
+**Returns**: <code>PatinaCliError</code> - Structured runtime error.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| what | <code>string</code> | Short failure headline. |
+| why | <code>string</code> | Explanation of the runtime failure. |
+| action | <code>string</code> | Suggested user action. |
+
+**Example**
+```js
+throw runtimeError('provider failed', 'The API timed out.', 'Retry later.');
+```
+<a name="renderCliError"></a>
+
+## renderCliError(err) ⇒ <code>string</code>
+Render any thrown value into the patina CLI error format.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Multi-line user-facing error text.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| err | <code>unknown</code> | Error-like value to render. |
+
+**Example**
+```js
+const message = renderCliError(inputError('bad flag', 'Unknown flag.', 'Run --help.'));
+```
+<a name="getExitCode"></a>
+
+## getExitCode(err, [fallback]) ⇒ <code>number</code>
+Extract a safe process exit code from an error-like value.
+
+**Kind**: global function
+**Returns**: <code>number</code> - Non-negative integer exit code.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| err | <code>unknown</code> |  | Error-like value. |
+| [fallback] | <code>number</code> | <code>1</code> | Exit code used when err.exitCode is absent or invalid. |
+
+**Example**
+```js
+const code = getExitCode(inputError('bad', 'why', 'fix')); // 2
+```
+<a name="loadFile"></a>
+
+## loadFile(path) ⇒ <code>string</code>
+Read a UTF-8 text file.
+
+**Kind**: global function
+**Returns**: <code>string</code> - File contents.
+**Throws**:
+
+- <code>Error</code> When the file cannot be read.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | File path to read. |
+
+**Example**
+```js
+const markdown = loadFile('README.md');
+```
+<a name="splitFrontmatter"></a>
+
+## splitFrontmatter(content) ⇒ <code>Object</code>
+Split Markdown-style YAML frontmatter from a document body.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Parsed frontmatter and trimmed body.
+**Throws**:
+
+- <code>Error</code> When YAML frontmatter is invalid.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| content | <code>string</code> | File contents. |
+
+**Example**
+```js
+const { frontmatter, body } = splitFrontmatter('---\ntitle: x\n---\nBody');
+```
+<a name="loadPatterns"></a>
+
+## loadPatterns(repoRoot, lang, [skipPatterns]) ⇒ <code>Array.&lt;{file: string, frontmatter: (object\|null), body: string, isStructure: boolean, isScoreOnly: boolean}&gt;</code>
+Load language-specific pattern packs from patterns/{lang}-*.md.
+
+**Kind**: global function
+**Returns**: <code>Array.&lt;{file: string, frontmatter: (object\|null), body: string, isStructure: boolean, isScoreOnly: boolean}&gt;</code> - Pattern packs.
+**Throws**:
+
+- <code>Error</code> When the patterns directory or a pattern file cannot be read.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| repoRoot | <code>string</code> |  | Repository root path. |
+| lang | <code>string</code> |  | Language code, such as ko, en, zh, or ja. |
+| [skipPatterns] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | Pack names to omit, without .md. |
+
+**Example**
+```js
+const patterns = loadPatterns(getRepoRoot(), 'en');
+```
+<a name="loadProfile"></a>
+
+## loadProfile(repoRoot, profileName) ⇒ <code>Object</code>
+Load a named profile from profiles/{profileName}.md after path validation.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Parsed profile document.
+**Throws**:
+
+- <code>Error</code> When the profile name is invalid or the file cannot be read.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| repoRoot | <code>string</code> | Repository root path. |
+| profileName | <code>string</code> | Profile file stem. |
+
+**Example**
+```js
+const profile = loadProfile(getRepoRoot(), 'default');
+```
+<a name="loadCoreFile"></a>
+
+## loadCoreFile(repoRoot, filename) ⇒ <code>Object</code>
+Load a Markdown file from the core/ directory.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Parsed core document.
+**Throws**:
+
+- <code>Error</code> When the file cannot be read or frontmatter is invalid.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| repoRoot | <code>string</code> | Repository root path. |
+| filename | <code>string</code> | Core filename, such as scoring.md. |
+
+**Example**
+```js
+const scoring = loadCoreFile(getRepoRoot(), 'scoring.md');
+```
+<a name="loadInputText"></a>
+
+## loadInputText(path) ⇒ <code>string</code>
+Read user input text from disk.
+
+**Kind**: global function
+**Returns**: <code>string</code> - UTF-8 input text.
+**Throws**:
+
+- <code>Error</code> When the file cannot be read.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | Input file path. |
+
+**Example**
+```js
+const text = loadInputText('draft.md');
+```
+<a name="loadVoiceSample"></a>
+
+## loadVoiceSample(path) ⇒ <code>Object</code>
+Load up to three non-empty paragraphs from a voice sample file.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Voice sample payload.
+**Throws**:
+
+- <code>Error</code> When the file is unreadable or has no non-empty paragraphs.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | Voice sample file path. |
+
+**Example**
+```js
+const sample = loadVoiceSample('voice.md');
+```
+<a name="toneToBackboneProfile"></a>
+
+## toneToBackboneProfile(tone) ⇒ <code>string</code> \| <code>null</code>
+Map a resolved named tone to its primary backbone profile.
+
+**Kind**: global function
+**Returns**: <code>string</code> \| <code>null</code> - Profile name, or null when no mapping exists.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| tone | <code>string</code> | Tone name. |
+
+**Example**
+```js
+const profile = toneToBackboneProfile('casual'); // blog
+```
+<a name="createLogger"></a>
+
+## createLogger([options]) ⇒ <code>Object</code>
+Create a small stderr logger with text and progress modes.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Logger facade.
+**Throws**:
+
+- <code>Error</code> Propagates stream write errors from the configured output stream.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Logger options. |
+| [options.level] | <code>string</code> | <code>&quot;info&quot;</code> | Minimum log level. |
+| [options.quiet] | <code>boolean</code> | <code>false</code> | Suppress all log output. |
+| [options.stream] | <code>NodeJS.WritableStream</code> | <code>process.stderr</code> | Progress stream. |
+
+**Example**
+```js
+const logger = createLogger();
+logger.info('event', { message: 'ready' });
+```
+<a name="runOuroboros"></a>
+
+## runOuroboros(options) ⇒ <code>Promise.&lt;{finalText: string, finalScore: number, iterations: number, reason: string, log: Array.&lt;object&gt;}&gt;</code>
+Run the iterative Ouroboros rewrite-and-score loop.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;{finalText: string, finalScore: number, iterations: number, reason: string, log: Array.&lt;object&gt;}&gt;</code> - Final text and iteration log.
+**Throws**:
+
+- <code>Error</code> When model calls or scoring fail outside handled schema fallbacks.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Ouroboros options. |
+| options.config | <code>object</code> | Effective config with ouroboros settings. |
+| options.patterns | <code>Array.&lt;object&gt;</code> | Loaded pattern packs. |
+| options.profile | <code>object</code> \| <code>null</code> | Parsed profile. |
+| options.voice | <code>object</code> \| <code>null</code> | Parsed voice guide. |
+| [options.voiceSample] | <code>object</code> \| <code>null</code> | Optional voice sample payload. |
+| options.scoring | <code>object</code> \| <code>null</code> | Parsed scoring guide. |
+| options.text | <code>string</code> | Source text to improve. |
+| [options.apiKey] | <code>string</code> | Provider API key. |
+| [options.baseURL] | <code>string</code> | Provider base URL. |
+| [options.model] | <code>string</code> | Model id. |
+| [options.callLLM] | <code>function</code> | LLM implementation. |
+| [options.now] | <code>function</code> | Clock returning epoch milliseconds. |
+| [options.sleep] | <code>function</code> | Sleep helper for tests. |
+| [options.signal] | <code>AbortSignal</code> | External cancellation signal. |
+| [options.logger] | <code>object</code> | patina logger. |
+
+**Example**
+```js
+const result = await runOuroboros({ config, patterns, profile, voice, scoring, text });
+```
+<a name="formatOutput"></a>
+
+## formatOutput(result, mode, [parsed], [opts]) ⇒ <code>string</code>
+Format a raw backend result for CLI output mode and requested format.
+
+**Kind**: global function
+**Returns**: <code>string</code> - User-facing formatted output.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| result | <code>string</code> \| <code>object</code> |  | Backend result or structured mode result. |
+| mode | <code>string</code> |  | Output mode: rewrite, diff, audit, score, or ouroboros. |
+| [parsed] | <code>object</code> | <code>{}</code> | Parsed CLI options. |
+| [opts] | <code>object</code> | <code>{}</code> | Formatting options. |
+| [opts.tone] | <code>object</code> \| <code>null</code> |  | Tone metadata to append. |
+| [opts.logger] | <code>object</code> |  | Logger for output warnings. |
+| [opts.env] | <code>object</code> |  | Environment map for color decisions. |
+| [opts.stdout] | <code>object</code> |  | Stdout-like stream for color decisions. |
+| [opts.auditBackstop] | <code>string</code> |  | Deterministic audit-mode section to append before the tone footer. |
+
+**Example**
+```js
+const output = formatOutput('[BODY]Hi[/BODY]', 'rewrite');
+```
+<a name="shouldColorDiff"></a>
+
+## shouldColorDiff([options])
+**Kind**: global function
+
+| Param | Type |
+| --- | --- |
+| [options] | <code>object</code> |
+| [options.parsed] | <code>object</code> |
+| [options.parsed.noColor] | <code>boolean</code> |
+| [options.env] | <code>Record.&lt;string, (string\|undefined)&gt;</code> |
+| [options.stdout] | <code>object</code> |
+| [options.stdout.isTTY] | <code>boolean</code> |
+
+<a name="validateScoreWeights"></a>
+
+## validateScoreWeights(output, configWeights) ⇒ <code>Array.&lt;string&gt;</code>
+Validate that a model-emitted score table used configured category weights.
+
+**Kind**: global function
+**Returns**: <code>Array.&lt;string&gt;</code> - Human-readable warnings for missing, mismatched, or unexpected categories.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| output | <code>string</code> | Score-mode markdown output. |
+| configWeights | <code>object</code> | Expected category weight map. |
+
+**Example**
+```js
+const warnings = validateScoreWeights('| content | 0.4 | 1 | 10 | 4 |', { content: 0.4 });
+```
+<a name="stripSelfAudit"></a>
+
+## stripSelfAudit(body, [options]) ⇒ <code>string</code>
+Remove SELF_AUDIT blocks and unwrap the BODY block from rewrite output.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Clean user-facing body text.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| body | <code>string</code> | Raw model response. |
+| [options] | <code>object</code> | Strip options. |
+| [options.logger] | <code>object</code> | Logger for malformed output warnings. |
+
+**Example**
+```js
+const clean = stripSelfAudit('[BODY]Hello[/BODY]\n[SELF_AUDIT]ok[/SELF_AUDIT]');
+```
+<a name="buildDeterministicAuditBackstop"></a>
+
+## buildDeterministicAuditBackstop(text, [opts]) ⇒ <code>string</code>
+Build a deterministic "backstop" section for audit mode. The LLM audit is
+model-dependent (a weak model silently drops 번역투/calques); these signals are
+computed deterministically so they appear regardless of which model ran. ko
+translationese rules are listed even below the hot-density gate, because audit
+is a hint surface, not a verdict.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Markdown section (empty string when nothing fired).
+
+| Param | Type | Description |
+| --- | --- | --- |
+| text | <code>string</code> | Source text. |
+| [opts] | <code>object</code> |  |
+| [opts.lang] | <code>string</code> |  |
+| [opts.repoRoot] | <code>string</code> |  |
+
+<a name="buildDeterministicAuditBackstop..rows"></a>
+
+### buildDeterministicAuditBackstop~rows : <code>Array.&lt;{signal:string, label:string, severity:string, location:string}&gt;</code>
+**Kind**: inner constant of [<code>buildDeterministicAuditBackstop</code>](#buildDeterministicAuditBackstop)
+<a name="buildPrompt"></a>
+
+## buildPrompt(options) ⇒ <code>string</code>
+Build the LLM prompt for rewrite, diff, audit, score, or ouroboros mode.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Complete prompt text.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>object</code> |  | Prompt inputs. |
+| options.config | <code>object</code> |  | Effective patina config. |
+| options.patterns | <code>Array.&lt;object&gt;</code> |  | Loaded pattern packs. |
+| options.profile | <code>object</code> \| <code>null</code> |  | Parsed profile document. |
+| options.voice | <code>object</code> \| <code>null</code> |  | Parsed voice guide. |
+| [options.voiceSample] | <code>object</code> \| <code>null</code> |  | Optional voice sample payload. |
+| options.scoring | <code>object</code> \| <code>null</code> |  | Parsed scoring guide. |
+| options.text | <code>string</code> |  | Input text. |
+| [options.mode] | <code>string</code> | <code>&quot;rewrite&quot;</code> | Output mode. |
+| [options.tone] | <code>object</code> \| <code>null</code> | <code></code> | Tone resolution metadata. |
+
+**Example**
+```js
+const prompt = buildPrompt({ config, patterns, profile, voice, scoring, text: 'Draft' });
+```
+<a name="isShortText"></a>
+
+## isShortText(text) ⇒ <code>boolean</code>
+Classify whether text should use the short-text scoring boost.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True when text is <=200 non-whitespace chars or <=3 paragraphs.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| text | <code>string</code> | Text to inspect. |
+
+**Example**
+```js
+const short = isShortText('A short note.');
+```
+<a name="selectProvider"></a>
+
+## selectProvider(name) ⇒ <code>object</code> \| <code>null</code>
+Resolve a provider preset by name.
+
+**Kind**: global function
+**Returns**: <code>object</code> \| <code>null</code> - Provider preset or null.
+**Throws**:
+
+- <code>PatinaCliError</code> When name is unknown.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> \| <code>null</code> \| <code>undefined</code> | Provider name; falsy returns null. |
+
+**Example**
+```js
+const provider = selectProvider('openai');
+```
+<a name="resolveProviderConfig"></a>
+
+## resolveProviderConfig(options) ⇒ <code>Object</code>
+Resolve effective API key, base URL, and model from explicit values, provider, and env.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Resolved provider config.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Provider resolution inputs. |
+| [options.provider] | <code>object</code> \| <code>null</code> | Provider preset from [selectProvider](#selectProvider). |
+| [options.apiKey] | <code>string</code> | Explicit API key. |
+| [options.baseURL] | <code>string</code> | Explicit base URL. |
+| [options.model] | <code>string</code> | Explicit model id. |
+
+**Example**
+```js
+const resolved = resolveProviderConfig({ provider: selectProvider('openai') });
+```
+<a name="scoreText"></a>
+
+## scoreText(options) ⇒ <code>Promise.&lt;object&gt;</code>
+Score text for AI-likeness using an LLM JSON scorer plus deterministic shadow signals.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;object&gt;</code> - Score payload with overall, interpretation, llmScore, and deterministicScore.
+**Throws**:
+
+- <code>Error</code> When the operation is aborted.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Scoring options. |
+| options.text | <code>string</code> | Text to score. |
+| options.config | <code>object</code> | Effective patina config. |
+| options.patterns | <code>Array.&lt;object&gt;</code> | Loaded pattern packs, retained for scorer compatibility. |
+| [options.apiKey] | <code>string</code> | Provider API key. |
+| [options.baseURL] | <code>string</code> | Provider base URL. |
+| [options.model] | <code>string</code> | Model id. |
+| [options.deadline] | <code>number</code> | Absolute epoch-millisecond deadline. |
+| [options.signal] | <code>AbortSignal</code> | External cancellation signal. |
+| [options.callLLM] | <code>function</code> | Injectable LLM implementation. |
+| [options.logger] | <code>object</code> | patina logger. |
+| [options.now] | <code>function</code> | Clock returning epoch milliseconds. |
+| [options.sleep] | <code>function</code> | Sleep helper for tests. |
+
+**Example**
+```js
+const score = await scoreText({ text: 'Draft', config, patterns, callLLM: async () => '{"categories":{},"overall":20,"interpretation":"mostly human"}' });
+```
+<a name="scoreDeterministicSignals"></a>
+
+## scoreDeterministicSignals([options]) ⇒ <code>object</code> \| <code>null</code>
+Compute deterministic stylometry/lexicon AI-likeness signals.
+
+**Kind**: global function
+**Returns**: <code>object</code> \| <code>null</code> - Deterministic score payload, skipped payload, or null when disabled.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Deterministic scoring options. |
+| [options.text] | <code>string</code> |  | Text to analyze. |
+| [options.config] | <code>object</code> | <code>{}</code> | Effective config. |
+| [options.repoRoot] | <code>string</code> |  | Repository root for analyzer resources. |
+| [options.analyzer] | <code>function</code> |  | Analyzer implementation. |
+
+**Example**
+```js
+const deterministic = scoreDeterministicSignals({ text: 'Draft', config });
+```
+<a name="withShadowScore"></a>
+
+## withShadowScore(parsed, [options]) ⇒ <code>object</code>
+Merge an LLM score payload with deterministic shadow-score reconciliation.
+
+**Kind**: global function
+**Returns**: <code>object</code> - Score payload preserving llmScore and deterministicScore details.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| parsed | <code>object</code> |  | Parsed LLM scoring JSON. |
+| [options] | <code>object</code> |  | Reconciliation options. |
+| [options.deterministicScore] | <code>object</code> \| <code>null</code> |  | Deterministic score payload. |
+| [options.config] | <code>object</code> | <code>{}</code> | Effective config. |
+| [options.logger] | <code>object</code> |  | Logger for reconciliation warnings. |
+
+**Example**
+```js
+const score = withShadowScore({ overall: 20 }, { deterministicScore: { overall: 25 } });
+```
+<a name="reconcileScoreOverall"></a>
+
+## reconcileScoreOverall([options]) ⇒ <code>Object</code>
+Reconcile LLM and deterministic overall scores according to config thresholds.
+
+**Kind**: global function
+**Returns**: <code>Object</code> - Reconciled score and preference source.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  | Reconciliation inputs. |
+| [options.llmOverall] | <code>number</code> \| <code>null</code> |  | LLM overall score. |
+| [options.deterministicScore] | <code>object</code> \| <code>null</code> |  | Deterministic score payload. |
+| [options.config] | <code>object</code> | <code>{}</code> | Effective config. |
+| [options.logger] | <code>object</code> |  | Logger for warnings. |
+
+**Example**
+```js
+const result = reconcileScoreOverall({ llmOverall: 20, deterministicScore: { overall: 60 } });
+```
+<a name="scoreMPS"></a>
+
+## scoreMPS(options) ⇒ <code>Promise.&lt;Object&gt;</code>
+Score meaning preservation between original and rewritten text.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;Object&gt;</code> - MPS result.
+**Throws**:
+
+- <code>Error</code> When the operation is aborted.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | MPS options. |
+| options.original | <code>string</code> | Original text. |
+| options.rewritten | <code>string</code> | Rewritten text. |
+| [options.apiKey] | <code>string</code> | Provider API key. |
+| [options.baseURL] | <code>string</code> | Provider base URL. |
+| [options.model] | <code>string</code> | Model id. |
+| [options.deadline] | <code>number</code> | Absolute epoch-millisecond deadline. |
+| [options.signal] | <code>AbortSignal</code> | External cancellation signal. |
+| [options.callLLM] | <code>function</code> | Injectable LLM implementation. |
+| [options.logger] | <code>object</code> | patina logger. |
+| [options.now] | <code>function</code> | Clock returning epoch milliseconds. |
+| [options.sleep] | <code>function</code> | Sleep helper for tests. |
+
+**Example**
+```js
+const mps = await scoreMPS({ original: 'A', rewritten: 'A', callLLM: async () => '{"mps":100,"anchors":[]}' });
+```
+<a name="interpretScore"></a>
+
+## interpretScore(score) ⇒ <code>string</code>
+Convert a numeric AI-likeness score to a human-readable band.
+
+**Kind**: global function
+**Returns**: <code>string</code> - Interpretation band.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| score | <code>number</code> | AI-likeness score from 0 to 100. |
+
+**Example**
+```js
+const label = interpretScore(28); // mostly human
+```
+<a name="lengthRatioPoints"></a>
+
+## lengthRatioPoints(original, rewritten) ⇒ <code>number</code>
+Score rewritten length ratio on the 0-3 fidelity scale.
+
+**Kind**: global function
+**Returns**: <code>number</code> - Length-ratio points from 0 to 3.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| original | <code>string</code> | Original text. |
+| rewritten | <code>string</code> | Rewritten text. |
+
+**Example**
+```js
+const points = lengthRatioPoints('abcd', 'abcde');
+```
+<a name="scoreFidelity"></a>
+
+## scoreFidelity(options) ⇒ <code>Promise.&lt;Object&gt;</code>
+Score fidelity between original and rewritten text using length plus LLM criteria.
+
+**Kind**: global function
+**Returns**: <code>Promise.&lt;Object&gt;</code> - Fidelity result.
+**Throws**:
+
+- <code>Error</code> When the operation is aborted.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Fidelity options. |
+| options.original | <code>string</code> | Original text. |
+| options.rewritten | <code>string</code> | Rewritten text. |
+| [options.apiKey] | <code>string</code> | Provider API key. |
+| [options.baseURL] | <code>string</code> | Provider base URL. |
+| [options.model] | <code>string</code> | Model id. |
+| [options.deadline] | <code>number</code> | Absolute epoch-millisecond deadline. |
+| [options.signal] | <code>AbortSignal</code> | External cancellation signal. |
+| [options.callLLM] | <code>function</code> | Injectable LLM implementation. |
+| [options.logger] | <code>object</code> | patina logger. |
+| [options.now] | <code>function</code> | Clock returning epoch milliseconds. |
+| [options.sleep] | <code>function</code> | Sleep helper for tests. |
+
+**Example**
+```js
+const fidelity = await scoreFidelity({ original: 'A', rewritten: 'A', callLLM: async () => '{"criteria":{"meaning":3,"tone":3,"no_unintended_additions":3}}' });
+```
+<a name="clamp03"></a>
+
+## clamp03(v) ⇒ <code>number</code>
+Clamp and round a value into the inclusive 0-3 scoring range.
+
+**Kind**: global function
+**Returns**: <code>number</code> - Integer from 0 to 3.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| v | <code>number</code> \| <code>string</code> | Value to clamp. |
+
+**Example**
+```js
+const value = clamp03(4.2); // 3
+```
+<a name="combinedScore"></a>
+
+## combinedScore(options) ⇒ <code>number</code>
+Combine AI-likeness, inverted fidelity, and optional deterministic score.
+
+**Kind**: global function
+**Returns**: <code>number</code> - Combined score, lower is better.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | Combined score inputs. |
+| options.aiLikeness | <code>number</code> | AI-likeness score, lower is better. |
+| options.fidelity | <code>number</code> | Fidelity score, higher is better. |
+| [options.profile] | <code>string</code> | Profile name for configured weights. |
+| [options.config] | <code>object</code> | Effective config. |
+| [options.deterministicScore] | <code>number</code> \| <code>object</code> \| <code>null</code> | Optional deterministic score. |
+
+**Example**
+```js
+const score = combinedScore({ aiLikeness: 20, fidelity: 90, profile: 'default', config: {} });
+```
+<a name="validateProfileName"></a>
+
+## validateProfileName(name) ⇒ <code>void</code>
+Validate a profile name before resolving profiles/{name}.md.
+
+**Kind**: global function
+**Throws**:
+
+- <code>PatinaCliError</code> When the name is empty, non-string, or contains unsafe characters.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | Profile name supplied by CLI or config. |
+
+**Example**
+```js
+validateProfileName('default');
+```
+<a name="isLoopbackHost"></a>
+
+## isLoopbackHost(hostname) ⇒ <code>boolean</code>
+Check whether a hostname is localhost or loopback.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True for localhost, 127/8, or ::1.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| hostname | <code>string</code> | Hostname from a URL. |
+
+**Example**
+```js
+const local = isLoopbackHost('127.0.0.1');
+```
+<a name="isPrivateOrSpecialIP"></a>
+
+## isPrivateOrSpecialIP(hostname) ⇒ <code>boolean</code>
+Detect literal private, reserved, link-local, metadata, or multicast IP hosts.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True when the literal IP is private or special-use.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| hostname | <code>string</code> | Hostname or bracketed IPv6 literal. |
+
+**Example**
+```js
+const blocked = isPrivateOrSpecialIP('169.254.169.254');
+```
+<a name="validateBaseURL"></a>
+
+## validateBaseURL(baseURL, [options]) ⇒ <code>void</code>
+Validate a provider base URL before sending prompts and bearer tokens.
+
+**Kind**: global function
+**Throws**:
+
+- <code>PatinaCliError</code> When the URL is invalid, unsupported, insecure, or private without opt-in.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| baseURL | <code>string</code> |  | URL to validate. |
+| [options] | <code>object</code> |  | Validation opt-ins. |
+| [options.allowInsecure] | <code>boolean</code> | <code>false</code> | Allow non-loopback HTTP. |
+| [options.allowPrivate] | <code>boolean</code> | <code>false</code> | Allow private/reserved literal IPs. |
+
+**Example**
+```js
+validateBaseURL('https://api.openai.com/v1');
+```
+<a name="shouldAllowInsecureBaseURL"></a>
+
+## shouldAllowInsecureBaseURL([parsed]) ⇒ <code>boolean</code>
+Read CLI/env opt-in for non-loopback HTTP base URLs.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True when insecure base URLs are explicitly allowed.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [parsed] | <code>object</code> | Parsed CLI options. |
+
+**Example**
+```js
+const allowed = shouldAllowInsecureBaseURL({ allowInsecureBaseURL: true });
+```
+<a name="applyInsecureBaseURLOptIn"></a>
+
+## applyInsecureBaseURLOptIn([parsed]) ⇒ <code>void</code>
+Persist CLI insecure-base-url opt-in into process.env for downstream calls.
+
+**Kind**: global function
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [parsed] | <code>object</code> | Parsed CLI options. |
+
+**Example**
+```js
+applyInsecureBaseURLOptIn({ allowInsecureBaseURL: true });
+```
+<a name="shouldAllowPrivateBaseURL"></a>
+
+## shouldAllowPrivateBaseURL([parsed]) ⇒ <code>boolean</code>
+Read CLI/env opt-in for private or reserved literal IP base URLs.
+
+**Kind**: global function
+**Returns**: <code>boolean</code> - True when private base URLs are explicitly allowed.
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [parsed] | <code>object</code> | Parsed CLI options. |
+
+**Example**
+```js
+const allowed = shouldAllowPrivateBaseURL({ allowPrivateBaseURL: true });
+```
+<a name="applyPrivateBaseURLOptIn"></a>
+
+## applyPrivateBaseURLOptIn([parsed]) ⇒ <code>void</code>
+Persist CLI private-base-url opt-in into process.env for downstream calls.
+
+**Kind**: global function
+**Throws**:
+
+- <code>Error</code> Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [parsed] | <code>object</code> | Parsed CLI options. |
+
+**Example**
+```js
+applyPrivateBaseURLOptIn({ allowPrivateBaseURL: true });
+```