@panaversity/ksor 0.0.53 → 0.0.55

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-dqpI-p1a.mjs";
-import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-Ck1l_Sgs-B-_wMYLB.mjs";
+import { A as parseViewer, B as tallyHandlers, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as recordIsUndescribed, G as z$1, H as validateViewer, I as runProbe$1, L as searchHandler, M as prewarmPool, N as providerKeyEnv$1, O as parseInstanceText$1, P as readHandler, R as servingPolicy$1, S as contentPool$1, T as instancePathOf$1, U as withPgRetry$1, V as tlsPosture, W as withProbeDeadline$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as storedTextSearchConfig } from "./gateway-api-C0vL3oOK-D24n786A.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -17,7 +17,7 @@ import { Document, YAMLParseError, isCollection, isMap, isPair, isSeq, parseAllD
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 import { execFileSync, spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-mQtKKwyj.mjs
+//#region ../content-gateway/dist/main-BoKhKcP0.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -1008,7 +1008,7 @@ async function compose(rawInstancePath, version) {
 	let provider;
 	try {
 		provider = buildShippedProvider$1(instance.embeddingProvider, {
-			apiKey: process.env["GEMINI_API_KEY"] ?? null,
+			apiKey: process.env[providerKeyEnv$1(instance.embeddingProvider) ?? ""] ?? null,
 			modelId: instance.embeddingModel,
 			dim: instance.embeddingDim
 		});
@@ -1533,7 +1533,7 @@ async function main$1(version = GATEWAY_VERSION) {
 	}
 }
 //#endregion
-//#region ../content/dist/check-DNWlQuBg.mjs
+//#region ../content/dist/check-6fB_kR4G.mjs
 /**
 * One reader for the control files beside the bundle (`.ksor/*.yaml`): the
 * same parser posture as a concept's frontmatter — one document, unique keys,
@@ -2825,6 +2825,7 @@ const LEDGER_HEADER$1 = "# The takedown ledger (record spec §5): append-only, w
 const CONTROL_FILES = [
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 /** Files the operating system writes behind the author's back: ignored, never reported. */
@@ -4709,7 +4710,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-Cb63_n_A.mjs
+//#region ../content/dist/commands-CO9-bQnb.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5823,13 +5824,6 @@ const INGEST_RETRY = {
 	initialS: 1,
 	maxS: 30
 };
-/** Fail-fast for the query path: 2 attempts, sub-second backoff, no 429 retry — worst case a
-* query embed costs ~1 s before the caller degrades, never a 15 s stall on the read. */
-const QUERY_RETRY = {
-	attempts: 2,
-	initialS: .2,
-	maxS: .5
-};
 function sleepS(seconds) {
 	return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
 }
@@ -5855,17 +5849,6 @@ async function embedIntent(texts, opts) {
 	return contract(texts, await withRetry(INGEST_RETRY, (exc) => provider.isRetryable(exc), () => provider.reset(), () => provider.embed(texts, { intent })), provider.dim);
 }
 /**
-* The READ plane's door (query-embed, intent "query"). Same contract;
-* FAIL-FAST retry (no 429, 2 attempts): a rate limit degrades the search to
-* keyword-only in under a second instead of stalling the read ~15 s. Async
-* like everything here — the oracle's `a` prefix marked Python's async
-* flavor and is kept only for greppability against the Python.
-*/
-async function aembedIntent(texts, opts) {
-	const { provider, intent } = opts;
-	return contract(texts, await withRetry(QUERY_RETRY, (exc) => provider.isRetryableQuery(exc), () => provider.reset(), () => provider.embed(texts, { intent })), provider.dim);
-}
-/**
 * The deterministic, key-free fake provider — a KSOR ADDITION (no oracle
 * counterpart; decision 6 conversion note). It exists so the DB tier and CI
 * can exercise ingest + retrieval end to end without a vendor key: same text
@@ -5937,7 +5920,7 @@ var FakeEmbeddingProvider = class {
 	}
 	reset() {}
 };
-const DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta";
+const DEFAULT_BASE$1 = "https://generativelanguage.googleapis.com/v1beta";
 /**
 * An HTTP-shaped failure carrying the status the retry classifier reads.
 *
@@ -5955,7 +5938,7 @@ var GeminiHttpError = class extends Error {
 };
 /** One POST, with the key in a HEADER — never the query string, which is logged. */
 async function post(opts, apiKey, path, body, timeoutMs) {
-	const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE}${path}`, {
+	const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE$1}${path}`, {
 		method: "POST",
 		headers: {
 			"x-goog-api-key": apiKey,
@@ -6025,33 +6008,33 @@ function geminiRestTextClient(apiKey, opts = {}) {
 *   Python-SDK failure mode with no JS equivalent; `reset()`
 *   keeps its drop-never-close contract regardless.
 */
-function httpStatusOf(exc) {
+function httpStatusOf$1(exc) {
 	if (!(exc instanceof Error)) return void 0;
 	const status = exc.status;
 	return typeof status === "number" ? status : void 0;
 }
-function isTransportBlip(exc, depth = 0) {
+function isTransportBlip$1(exc, depth = 0) {
 	if (depth > 5 || !(exc instanceof Error)) return false;
 	if (exc.name === "AbortError" || exc.name === "TimeoutError") return true;
 	const code = exc.code;
 	if (typeof code === "string" && /^E[A-Z0-9_]+$/.test(code)) return true;
 	if (exc instanceof TypeError && exc.message.includes("fetch failed")) return true;
-	return isTransportBlip(exc.cause, depth + 1);
+	return isTransportBlip$1(exc.cause, depth + 1);
 }
 /** The Gemini taxonomy for the INGEST plane: transport blips, 5xx, AND 429 —
 * batch work is resumable and has no user waiting. */
-function isRetryable(exc) {
-	if (isTransportBlip(exc)) return true;
-	const status = httpStatusOf(exc);
+function isRetryable$1(exc) {
+	if (isTransportBlip$1(exc)) return true;
+	const status = httpStatusOf$1(exc);
 	if (status === void 0) return false;
 	return status >= 500 && status <= 599 || status === 429;
 }
 /** The READ path's predicate: transport blips + 5xx only — NEVER 429. A
 * rate-limited project stays rate-limited on the next second; the correct
 * move is to degrade to keyword-only NOW, not stall the read behind backoff. */
-function isRetryableQuery(exc) {
-	if (isTransportBlip(exc)) return true;
-	const status = httpStatusOf(exc);
+function isRetryableQuery$1(exc) {
+	if (isTransportBlip$1(exc)) return true;
+	const status = httpStatusOf$1(exc);
 	return status !== void 0 && status >= 500 && status <= 599;
 }
 /**
@@ -6102,10 +6085,10 @@ var GeminiEmbeddingProvider = class {
 		})).embeddings ?? []).map((e) => [...e.values ?? []]);
 	}
 	isRetryable(exc) {
-		return isRetryable(exc);
+		return isRetryable$1(exc);
 	}
 	isRetryableQuery(exc) {
-		return isRetryableQuery(exc);
+		return isRetryableQuery$1(exc);
 	}
 };
 /**
@@ -6118,7 +6101,7 @@ var GeminiTextGenerator = class {
 	clientFactory;
 	client = null;
 	constructor(opts) {
-		this.model = opts.model ?? "gemini-2.5-flash";
+		this.model = opts.model ?? "gemini-3.7-flash";
 		this.clientFactory = opts.clientFactory ?? (() => geminiRestTextClient(opts.apiKey));
 	}
 	getClient() {
@@ -6139,9 +6122,174 @@ var GeminiTextGenerator = class {
 			}
 		})).text ?? "";
 	}
+	isRetryable(exc) {
+		return isRetryable$1(exc);
+	}
+};
+/**
+* OpenAI's embedding endpoint, over `fetch` — no SDK.
+*
+* The same call decision 12's 2026-08-22 revision made for Gemini, for the same
+* reason: this is ONE HTTP call behind a structurally-typed slice, and a vendor
+* SDK would put megabytes and a transitive dependency tree into every
+* `ksor init` that never embeds anything. If a provider ever needs an SDK, the
+* seam takes one through `clientFactory`; nothing here forecloses that.
+*
+* WHAT DIFFERS FROM GEMINI, and it is worth knowing before choosing:
+*
+*   Gemini embeds ASYMMETRICALLY — `RETRIEVAL_DOCUMENT` and `RETRIEVAL_QUERY`
+*   produce different vectors for the same text, and the plane's intent picks
+*   which. OpenAI has no task type: a query and a document are embedded
+*   identically. The seam anticipates exactly this — "a provider whose two
+*   vendor labels are equal can never mis-route a plane"
+*   (`lib/embedding.ts`) — so both labels are the empty string and the intent
+*   reaches this transport and is deliberately ignored.
+*
+*   `dimensions` is supported on `text-embedding-3-*` only. Asking an older
+*   model for a dimension is an error there, not a silent full-width vector,
+*   which is the failure the framework's own width check would catch anyway.
+*/
+/**
+* An HTTP-shaped failure carrying the status the retry classifier reads — and
+* the vendor's own error `type`, which the status alone does not distinguish.
+*
+* OpenAI answers a spent balance with **429**, the same status as a rate limit:
+* `{"error":{"type":"insufficient_quota","code":"credit_balance_exhausted"}}`
+* (observed live, 2026-09-01). One clears by waiting and one never will, so a
+* classifier reading only the status retries a billing problem five times with
+* exponential backoff and then reports it — slowly, and as if it had been
+* transient.
+*/
+var OpenAiHttpError = class extends Error {
+	status;
+	/** The vendor's `error.type`, when it sends one. */
+	kind;
+	constructor(status, detail, kind = null) {
+		super(`OpenAI API error ${status}: ${detail}`);
+		this.name = "OpenAiHttpError";
+		this.status = status;
+		this.kind = kind;
+	}
+};
+const DEFAULT_BASE = "https://api.openai.com/v1";
+function openAiRestEmbedClient(apiKey, opts = {}) {
+	return { async embed(params) {
+		const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE}/embeddings`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${apiKey}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				model: params.model,
+				input: [...params.input],
+				dimensions: params.dimensions
+			}),
+			signal: AbortSignal.timeout(params.timeoutMs)
+		});
+		const text = await res.text();
+		if (!res.ok) {
+			let detail = text.slice(0, 300);
+			let kind = null;
+			try {
+				const err = JSON.parse(text).error;
+				if (typeof err?.message === "string") detail = err.message;
+				if (typeof err?.type === "string") kind = err.type;
+			} catch {}
+			throw new OpenAiHttpError(res.status, detail, kind);
+		}
+		const data = [...JSON.parse(text).data ?? []];
+		data.sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+		return { embeddings: data.map((d) => ({ values: d.embedding })) };
+	} };
+}
+/** True for a transport blip with no HTTP status of its own. */
+function isTransportBlip(exc) {
+	if (exc instanceof OpenAiHttpError) return false;
+	const name = exc?.name;
+	return name === "AbortError" || name === "TimeoutError" || name === "TypeError";
+}
+function httpStatusOf(exc) {
+	return exc instanceof OpenAiHttpError ? exc.status : void 0;
+}
+/**
+* The INGEST plane's taxonomy: transport blips, 5xx, AND 429 — batch work is
+* resumable and has nobody waiting. Deliberately the same shape as the Gemini
+* adapter's, because the two planes are a property of ksor, not of a vendor.
+*/
+function isRetryable(exc) {
+	if (isTransportBlip(exc)) return true;
+	if (exc instanceof OpenAiHttpError && exc.kind === "insufficient_quota") return false;
+	const status = httpStatusOf(exc);
+	if (status === void 0) return false;
+	return status >= 500 && status <= 599 || status === 429;
+}
+/**
+* The READ plane's: transport blips + 5xx only, NEVER 429. A rate-limited
+* project stays rate-limited on the next second, so a search degrades to
+* keyword-only now rather than stalling a reader behind backoff.
+*/
+/**
+* An ACCOUNT-level failure: no amount of waiting and no other passage changes
+* it. The drain must abort on this rather than quarantine, because the chunk
+* it happened to be holding is not what is wrong — see `ingest/worker.ts`.
+*/
+function isFatal(exc) {
+	return exc instanceof OpenAiHttpError && exc.kind === "insufficient_quota";
+}
+function isRetryableQuery(exc) {
+	if (isTransportBlip(exc)) return true;
+	const status = httpStatusOf(exc);
+	return status !== void 0 && status >= 500 && status <= 599;
+}
+var OpenAiEmbeddingProvider = class {
+	providerId = "openai";
+	modelId;
+	dim;
+	documentTaskLabel;
+	queryTaskLabel;
+	documentTimeoutMs;
+	queryTimeoutMs;
+	clientFactory;
+	client = null;
+	constructor(opts) {
+		this.modelId = opts.modelId;
+		this.dim = opts.dim;
+		this.documentTaskLabel = opts.documentTaskLabel;
+		this.queryTaskLabel = opts.queryTaskLabel;
+		this.documentTimeoutMs = Math.trunc(opts.documentTimeoutS * 1e3);
+		this.queryTimeoutMs = Math.trunc(opts.queryTimeoutS * 1e3);
+		this.clientFactory = opts.clientFactory ?? (() => openAiRestEmbedClient(opts.apiKey));
+	}
+	get recipe() {
+		return `${this.modelId}/d${this.dim}/${this.documentTaskLabel}`;
+	}
+	getClient() {
+		this.client ??= this.clientFactory();
+		return this.client;
+	}
+	/** DROP the client reference, never close it: in-flight calls finish on their
+	* own reference and the next call rebuilds lazily. Idempotent. */
+	reset() {
+		this.client = null;
+	}
+	async embed(texts, opts) {
+		return (await this.getClient().embed({
+			model: this.modelId,
+			input: texts,
+			dimensions: this.dim,
+			timeoutMs: opts.intent === "document" ? this.documentTimeoutMs : this.queryTimeoutMs
+		})).embeddings.map((e) => [...e.values ?? []]);
+	}
 	isRetryable(exc) {
 		return isRetryable(exc);
 	}
+	isRetryableQuery(exc) {
+		return isRetryableQuery(exc);
+	}
+	isFatal(exc) {
+		return isFatal(exc);
+	}
 };
 /**
 * The embedding-provider registry — a plain object, NOT any discovery
@@ -6168,20 +6316,49 @@ var GeminiTextGenerator = class {
 */
 var MissingProviderKeyError = class extends Error {
 	providerName;
-	constructor(providerName) {
-		super(`embedding provider ${JSON.stringify(providerName)} needs an API key and none was supplied`);
+	keyEnv;
+	/**
+	* `keyEnv` is not decoration. The message named the PROVIDER and nothing
+	* else, so an operator whose `ksor serve` exited 3 on an OpenAI record was
+	* told "provider openai needs an API key" and left to guess which variable —
+	* while `ksor serve --help`, `env.example` and `docs/deploying.md` all named
+	* `GEMINI_API_KEY`, which the door does not read (review, 2026-09-01). The
+	* registry row already held the answer; this is it reaching the operator.
+	*/
+	constructor(providerName, keyEnv = null) {
+		super(`embedding provider ${JSON.stringify(providerName)} needs an API key and none was supplied` + (keyEnv === null ? "" : ` — set ${keyEnv}`));
 		this.name = "MissingProviderKeyError";
 		this.providerName = providerName;
+		this.keyEnv = keyEnv;
 	}
 };
 const PROVIDERS = {
 	gemini: {
 		build: (opts) => new GeminiEmbeddingProvider(opts),
-		needsApiKey: true
+		needsApiKey: true,
+		keyEnv: "GEMINI_API_KEY",
+		taskLabels: {
+			document: EMBED_TASK_DOCUMENT,
+			query: EMBED_TASK_QUERY
+		}
+	},
+	openai: {
+		build: (opts) => new OpenAiEmbeddingProvider(opts),
+		needsApiKey: true,
+		keyEnv: "OPENAI_API_KEY",
+		taskLabels: {
+			document: "",
+			query: ""
+		}
 	},
 	fake: {
 		build: (opts) => new FakeEmbeddingProvider(opts),
-		needsApiKey: false
+		needsApiKey: false,
+		keyEnv: null,
+		taskLabels: {
+			document: EMBED_TASK_DOCUMENT,
+			query: EMBED_TASK_QUERY
+		}
 	}
 };
 function entryFor(name) {
@@ -6196,6 +6373,13 @@ function providerNeedsApiKey(name) {
 	return entryFor(name).needsApiKey;
 }
 /**
+* The environment variable this provider's key comes from, or null when it
+* needs none. Unknown name → the same loud error as building it.
+*/
+function providerKeyEnv(name) {
+	return entryFor(name).keyEnv;
+}
+/**
 * The port door: the named provider bound to the DECLARED embedding space and
 * the framework's timeout knobs. `modelId`/`dim` omitted = the shipped
 * config space (EMBED_MODEL / EMBED_DIM, eval-locked); an instance may
@@ -6207,13 +6391,13 @@ function providerNeedsApiKey(name) {
 */
 function buildShippedProvider(name, opts) {
 	const entry = entryFor(name);
-	if (entry.needsApiKey && !opts.apiKey) throw new MissingProviderKeyError(name);
+	if (entry.needsApiKey && !opts.apiKey) throw new MissingProviderKeyError(name, entry.keyEnv);
 	return entry.build({
 		apiKey: opts.apiKey ?? "",
 		modelId: opts.modelId ?? "gemini-embedding-001",
 		dim: opts.dim ?? 1536,
-		documentTaskLabel: EMBED_TASK_DOCUMENT,
-		queryTaskLabel: EMBED_TASK_QUERY,
+		documentTaskLabel: entry.taskLabels.document,
+		queryTaskLabel: entry.taskLabels.query,
 		documentTimeoutS: EMBED_TIMEOUT_S(),
 		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
@@ -6711,7 +6895,7 @@ function calibrationScope(viewer) {
 async function scoreQueries(pool, scope, gucs, provider, queries, inCorpus) {
 	const out = [];
 	for (const query of queries) {
-		const [vector] = await aembedIntent([query], {
+		const [vector] = await embedIntent([query], {
 			provider,
 			intent: "query"
 		});
@@ -9113,6 +9297,7 @@ async function drain(pending, io) {
 			literals = await io.embedBatch(batch.map(([, text]) => text));
 		} catch (exc) {
 			if (io.isRetryable(exc)) throw exc;
+			if (io.isFatal?.(exc) === true) throw exc;
 			if (batch.length === 1) {
 				await io.markFailed(failureReason(exc), batch[0][0]);
 				failed += 1;
@@ -9664,7 +9849,8 @@ async function buildGeneration(pool, instance, options) {
 		markFailed: (reason, chunkId) => runIngest(pool, tenant, async (c) => {
 			await c.query(FAIL_SQL, [reason, chunkId]);
 		}),
-		isRetryable: (exc) => provider.isRetryable(exc)
+		isRetryable: (exc) => provider.isRetryable(exc),
+		isFatal: (exc) => provider.isFatal?.(exc) === true
 	});
 	log(`embedded ${embedded}, failed ${failed}`);
 	const fin = await runIngest(pool, tenant, async (c) => {
@@ -9743,6 +9929,43 @@ function pct(fraction) {
 	return `${(fraction * 100).toFixed(0)}%`;
 }
 /**
+* What to do when calibration is refused for quota — named, not left as the
+* vendor's sentence.
+*
+* Both of these were hit walking a real free-tier key, and they are DIFFERENT
+* failures with different remedies, which is why the raw error is not enough:
+*
+*   generate_content …/gemini-3.7-flash, limit 5   the SYNTHESIZED door writes
+*                                                  one probe question per
+*                                                  sampled passage, and a free
+*                                                  key allows a handful of
+*                                                  generations a minute. No
+*                                                  amount of waiting fixes a
+*                                                  corpus of any size; the
+*                                                  answer is the zero-LLM door.
+*   global_embed_content_requests_per_minute       the EMBEDDING endpoint, which
+*                                                  both doors use. Transient:
+*                                                  an ingest immediately before
+*                                                  a calibration spends the same
+*                                                  per-minute budget.
+*
+* Product principle 4: a failure states what is wrong, why the rule exists, and
+* how to fix it. The vendor's message states only the first.
+*/
+/** The generation quota, which no wait resolves on a free key. */
+const GENERATION = /generate_content|generativelanguage\.googleapis\.com\/generate/i;
+/** The embedding quota, which clears on its own. */
+const EMBEDDING = /embed_content|global_embed/i;
+/**
+* The remedy for a quota refusal, or null when the failure is not one this
+* knows — in which case the vendor's own message stands, unembellished.
+*/
+function quotaRemedy(message) {
+	if (GENERATION.test(message)) return "the SYNTHESIZED door writes one probe question per sampled passage with an LLM, and a free-tier key allows only a few generations a minute — a bigger corpus makes this worse, not better.\n  fix: calibrate with zero LLM — write your in-corpus questions one per line and pass\n       --queries-file PATH. The floor is measured the same way; only the questions differ,\n       and the door is recorded beside the number so the two are never compared.";
+	if (EMBEDDING.test(message)) return "the EMBEDDING endpoint is limited per minute, and both doors use it — an ingest immediately before this spends the same budget.\n  fix: wait about a minute and run it again. Nothing was written; calibration only reads.";
+	return null;
+}
+/**
 * How close to the floor an answer has to be to count as marginal.
 *
 * 0.01 is not a tuned threshold — it is the size of the decision in this
@@ -10175,8 +10398,9 @@ function composeProvider(instance) {
 	try {
 		let apiKey = null;
 		if (providerNeedsApiKey(instance.embeddingProvider)) {
-			apiKey = process.env["GEMINI_API_KEY"] || null;
-			if (apiKey === null) return fail$1(ENVIRONMENT, "GEMINI_API_KEY is required (the instance's embedding provider needs a key)\n  fix: export GEMINI_API_KEY=... and rerun");
+			const keyEnv = providerKeyEnv(instance.embeddingProvider) ?? "";
+			apiKey = process.env[keyEnv] || null;
+			if (apiKey === null) return fail$1(ENVIRONMENT, `${keyEnv} is required (the instance's embedding provider ${JSON.stringify(instance.embeddingProvider)} needs a key)\n  fix: export ${keyEnv}=... and rerun`);
 		}
 		return buildShippedProvider(instance.embeddingProvider, {
 			apiKey,
@@ -10433,11 +10657,11 @@ async function calibrateCommand(args) {
 	let textGenerator = null;
 	if (queries === null) {
 		const apiKey = process.env["GEMINI_API_KEY"];
-		if (apiKey === void 0 || apiKey === "") return refuse$2("bad-args", "the synthesized door needs GEMINI_API_KEY (it writes one probe question per sampled passage) — or calibrate with zero LLM: --queries-file PATH (one in-corpus question per line)");
+		if (apiKey === void 0 || apiKey === "") return refuse$2("bad-args", "the synthesized door needs GEMINI_API_KEY (it writes one probe question per sampled passage) — or calibrate with zero LLM: --queries-file PATH (one in-corpus question per line).\n  note: this is the TEXT generator, not the embedding provider. A record on `embedding.provider: openai` still embeds with OPENAI_API_KEY; only question synthesis is Gemini-only today, and --queries-file avoids it entirely");
 		textGenerator = new GeminiTextGenerator({ apiKey });
 	}
 	const ooc = values["ooc-file"] === void 0 ? null : parseQueriesFile(readFileSync(values["ooc-file"], "utf8"));
-	const report = await withPool(dsn, async (pool) => runCalibration(pool, {
+	const report = await withQuotaRemedy(async () => withPool(dsn, async (pool) => runCalibration(pool, {
 		tenantId: instance.tenantId,
 		corpusId: instance.corpusId,
 		viewer: await widestViewer(pool, instance),
@@ -10448,12 +10672,31 @@ async function calibrateCommand(args) {
 		oocProbes: ooc,
 		perNode: values["per-node"] === void 0 ? void 0 : intFlag("--per-node", values["per-node"]),
 		minChars: values["min-chars"] === void 0 ? void 0 : intFlag("--min-chars", values["min-chars"])
-	}));
+	})));
 	process.stdout.write(renderReport(report, GATE_PREDICATE_DIGEST) + "\n");
 	const advice = overlapAdvice(report);
 	if (advice !== null) process.stdout.write(advice);
 	return 0;
 }
+/**
+* Run a calibration, turning a quota refusal into the remedy for THAT quota.
+*
+* Both failures reach here as the vendor's own sentence, which states what is
+* wrong and neither why nor how to fix it — and the two need opposite answers
+* (change door vs wait a minute). Anything `quotaRemedy` does not recognise is
+* re-thrown untouched: inventing advice for an error nobody has read is worse
+* than passing the vendor's through.
+*/
+async function withQuotaRemedy(op) {
+	try {
+		return await op();
+	} catch (exc) {
+		const message = exc instanceof Error ? exc.message : String(exc);
+		const remedy = quotaRemedy(message);
+		if (remedy === null) throw exc;
+		throw Object.assign(/* @__PURE__ */ new Error(`${message}\n  why: ${remedy}`), { slug: "ksor-calibrate-quota" });
+	}
+}
 /** How many days of traffic one --check reads. Bounded so a busy record cannot make it expensive. */
 const DRIFT_DEFAULT_DAYS = 30;
 /**
@@ -10796,7 +11039,7 @@ async function runContentCli(argv) {
 	}
 }
 //#endregion
-//#region ../content/dist/record-DnMnZelb.mjs
+//#region ../content/dist/record-Cxw0SUG3.mjs
 /**
 * May `surface` publish `doc` at instant `at`? `drafts` is the build's drafts switch,
 * which admits drafts to HUMAN surfaces only.
@@ -10842,6 +11085,7 @@ const lockSchema = z.object({
 	drafts: z.enum(["hidden", "shown"]),
 	instance_sha256: hex64,
 	policy_sha256: hex64,
+	people_sha256: hex64,
 	ledger_sha256: hex64,
 	ledger_entries: z.array(z.object({
 		id: z.string().min(1),
@@ -10914,6 +11158,7 @@ function buildIdOf(inputs) {
 		indexes: [...inputs.indexes].map((i) => [i.path, i.sha256]).sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
 		instance_sha256: inputs.instance_sha256,
 		policy_sha256: inputs.policy_sha256,
+		people_sha256: inputs.people_sha256,
 		ledger_sha256: inputs.ledger_sha256,
 		ksor_version: inputs.ksor_version,
 		drafts: inputs.drafts
@@ -10960,6 +11205,7 @@ function composeLock(input) {
 	}));
 	const instance_sha256 = sha256Hex(input.instanceText);
 	const policy_sha256 = sha256Hex(input.policyText);
+	const people_sha256 = sha256Hex(input.peopleText ?? "");
 	const ledger_sha256 = sha256Hex(input.ledgerText ?? "");
 	return {
 		format: 1,
@@ -10970,6 +11216,7 @@ function composeLock(input) {
 			indexes,
 			instance_sha256,
 			policy_sha256,
+			people_sha256,
 			ledger_sha256,
 			ksor_version: input.ksorVersion,
 			drafts: input.drafts
@@ -10982,6 +11229,7 @@ function composeLock(input) {
 		drafts: input.drafts,
 		instance_sha256,
 		policy_sha256,
+		people_sha256,
 		ledger_sha256,
 		ledger_entries: [...input.ledgerEntries].sort((a, b) => compare(a.id, b.id)),
 		audiences: {
@@ -11144,6 +11392,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 /**
@@ -11154,7 +11403,11 @@ const INPUTS = [
 * clone is invisible to every surface, so the build says so by name.
 */
 function ignoredGovernance(root) {
-	const paths = [".ksor/governance.yaml", ".ksor/takedowns.yaml"].filter((rel) => existsSync(join(root, rel)));
+	const paths = [
+		".ksor/governance.yaml",
+		".ksor/people.yaml",
+		".ksor/takedowns.yaml"
+	].filter((rel) => existsSync(join(root, rel)));
 	if (paths.length === 0) return [];
 	const out = git(root, [
 		"check-ignore",
@@ -11344,8 +11597,8 @@ function runBuild(args, cwd, io, options) {
 	const facts = gitFacts(root);
 	if (facts.repository && facts.historicLedger === null && !parsed.allowUnverifiable) return refuse$1(io, "ksor-ledger-unverifiable", facts.historyUnreadable === "shallow" ? "this is a shallow clone: the takedown ledger is append-only, and without history a deleted entry cannot be told from one that never existed" : "git could not read the takedown ledger's history (`git log -- .ksor/takedowns.yaml` failed, and this is not a shallow clone): the ledger is append-only, and without history a deleted entry cannot be told from one that never existed", facts.historyUnreadable === "shallow" ? "fetch full history (`git fetch --unshallow`; in CI, `fetch-depth: 0`), or pass --allow-unverifiable-ledger to build anyway" : "check that `git log` works in this checkout, or pass --allow-unverifiable-ledger to build anyway");
 	const ignored = facts.repository ? ignoredGovernance(root) : [];
-	if (ignored.length > 0) return refuse$1(io, "ksor-governance-ignored", `git ignores ${ignored.join(" and ")}, so ${ignored.length === 1 ? "it is" : "they are"} in no commit — the policy and the takedown ledger ARE the record, and a clone (your CI, your deploy) would build without ${ignored.length === 1 ? "it" : "them"}`, "un-ignore them in .gitignore — the directory form `.ksor/` cannot be negated, so use `.ksor/*` plus `!.ksor/governance.yaml` and `!.ksor/takedowns.yaml` — then commit them (`ksor migrate` offers that edit)");
-	if (parsed.strict && facts.dirty) return refuse$1(io, "ksor-build-dirty", facts.repository ? "an input (knowledge/, instance.md, .ksor/governance.yaml, .ksor/takedowns.yaml) differs from its last commit, and --strict stamps only committed content" : "the record is not in a git repository, so no input is committed", "commit the inputs and rebuild, or drop --strict to stamp a dirty build (the lock says `dirty: true`)");
+	if (ignored.length > 0) return refuse$1(io, "ksor-governance-ignored", `git ignores ${ignored.join(" and ")}, so ${ignored.length === 1 ? "it is" : "they are"} in no commit — the policy and the takedown ledger ARE the record, and a clone (your CI, your deploy) would build without ${ignored.length === 1 ? "it" : "them"}`, "un-ignore them in .gitignore — the directory form `.ksor/` cannot be negated, so use `.ksor/*` plus `!.ksor/governance.yaml`, `!.ksor/people.yaml` and `!.ksor/takedowns.yaml` — then commit them (`ksor migrate` offers that edit)");
+	if (parsed.strict && facts.dirty) return refuse$1(io, "ksor-build-dirty", facts.repository ? "an input (knowledge/, instance.md, .ksor/governance.yaml, .ksor/people.yaml, .ksor/takedowns.yaml) differs from its last commit, and --strict stamps only committed content" : "the record is not in a git repository, so no input is committed", "commit the inputs and rebuild, or drop --strict to stamp a dirty build (the lock says `dirty: true`)");
 	const baselines = [];
 	if (facts.historicLedger !== null) baselines.push({
 		source: "git history",
@@ -11386,6 +11639,7 @@ function runBuild(args, cwd, io, options) {
 		drafts: options.drafts,
 		instanceText: record.files.get("instance.md") ?? "",
 		policyText: record.files.get(".ksor/governance.yaml") ?? "",
+		peopleText: record.files.get(".ksor/people.yaml") ?? null,
 		ledgerText,
 		ledgerEntries: result.ledgerEntries,
 		audiences: result.policy?.audiences ?? [],
@@ -13072,11 +13326,13 @@ const BARE_DOTKSOR_PATTERNS = /* @__PURE__ */ new Set([
 ]);
 const GOVERNANCE_IGNORE_BLOCK = [
 	"# ksor's working directory — build output and scratch, never the record.",
-	"# The two governance files inside it ARE the record (the policy and the",
-	"# takedown ledger) and are un-ignored by name: the directory form `.ksor/`",
-	"# cannot be negated, so the glob is `.ksor/*`.",
+	"# The governance files inside it ARE the record (the policy, the takedown",
+	"# ledger, and the phone book the site publishes names from) and are",
+	"# un-ignored by name: the directory form `.ksor/` cannot be negated, so the",
+	"# glob is `.ksor/*`.",
 	".ksor/*",
 	"!.ksor/governance.yaml",
+	"!.ksor/people.yaml",
 	"!.ksor/takedowns.yaml"
 ];
 /**
@@ -13350,7 +13606,8 @@ function isEnvironmentError(value) {
 const EMITTED_NAMES = /* @__PURE__ */ new Map([
 	["gitignore", ".gitignore"],
 	["env.example", ".env.example"],
-	["dockerignore", ".dockerignore"]
+	["dockerignore", ".dockerignore"],
+	["mcp.json", ".mcp.json"]
 ]);
 const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
 	".md",
@@ -13712,7 +13969,9 @@ serves nothing. Runs in this process and holds it; SIGTERM/SIGINT drains.
 Configured by environment — .env beside the record is read automatically:
 
   <database.dsn_env>       the Postgres DSN, under the NAME instance.md gives
-  GEMINI_API_KEY           iff the instance's embedding provider needs a key
+  <provider key>           iff the instance's embedding provider needs one:
+                           GEMINI_API_KEY for gemini, OPENAI_API_KEY for openai.
+                           The refusal names the variable your record needs
   KSOR_AUTH                disabled-local (loopback dev) | disabled-public.
                            Serve REFUSES to boot with neither this nor a
                            configured SSO door — never open by accident