@panaversity/ksor 0.0.53 → 0.0.55

package/dist/{gateway-api-Ck1l_Sgs-B-_wMYLB.mjs → gateway-api-C0vL3oOK-D24n786A.mjs}

@@ -6,7 +6,7 @@ import { z, z as z$1 } from "zod";
 import path, { join } from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-Ck1l_Sgs.mjs
+//#region ../content-gateway/dist/gateway-api-C0vL3oOK.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -8899,7 +8899,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.
 *
@@ -8917,7 +8917,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,
@@ -8973,33 +8973,33 @@ function geminiRestEmbedClient(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;
 }
 /**
@@ -9049,12 +9049,177 @@ var GeminiEmbeddingProvider = class {
 			}
 		})).embeddings ?? []).map((e) => [...e.values ?? []]);
 	}
+	isRetryable(exc) {
+		return isRetryable$1(exc);
+	}
+	isRetryableQuery(exc) {
+		return isRetryableQuery$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
@@ -9081,20 +9246,49 @@ var GeminiEmbeddingProvider = 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) {
@@ -9103,6 +9297,13 @@ function entryFor(name) {
 	return entry;
 }
 /**
+* 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
@@ -9114,13 +9315,13 @@ function entryFor(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()
 	});
@@ -10955,4 +11156,4 @@ function readHandler(ctx) {
 	};
 }
 //#endregion
-export { parseViewer as A, tlsPosture as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, runProbe as F, withPgRetry as H, searchHandler as I, servingPolicy as L, prewarmPool as M, readHandler as N, parseInstanceText as O, recordIsUndescribed as P, storedTextSearchConfig as R, contentPool as S, instancePathOf as T, withProbeDeadline as U, validateViewer as V, z$1 as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, tallyHandlers as z };
+export { parseViewer as A, tallyHandlers as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, recordIsUndescribed as F, z$1 as G, validateViewer as H, runProbe as I, searchHandler as L, prewarmPool as M, providerKeyEnv as N, parseInstanceText as O, readHandler as P, servingPolicy as R, contentPool as S, instancePathOf as T, withPgRetry as U, tlsPosture as V, withProbeDeadline as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, storedTextSearchConfig as z };

package/dist/gateway.d.mts

@@ -1,7 +1,7 @@
 import { CallToolResult, McpServer as McpServer$1, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
 import { z as z$1 } from "zod";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-Da-9ssbU.d.mts
+//#region ../content-gateway/dist/gateway-api-CEnK8Bc8.d.mts
 //#region src/instructions.d.ts
 /**
  * Has the owner said what this record is FOR yet?
@@ -16,7 +16,7 @@ import pg from "pg";
 declare function recordIsUndescribed(authored: string): boolean;
 declare function composeInstructions(authored: string): string;
 //#endregion
-//#region ../content/dist/index-CQcB_oVG.d.mts
+//#region ../content/dist/index-D-xEl8mz.d.mts
 declare const TRUST_TIERS: readonly ["unverified", "machine-confirmed", "human-reviewed"];
 type TrustTier = (typeof TRUST_TIERS)[number];
 //#endregion

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-Ck1l_Sgs-B-_wMYLB.mjs";
+import { D as outlineHandler, F as recordIsUndescribed, G as z$1, L as searchHandler, P as readHandler, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-C0vL3oOK-D24n786A.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, TRUST_TIERS, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/deploying.md

@@ -141,14 +141,38 @@ What the image deliberately does NOT contain (see `.dockerignore`):
 > which is the door answering "Method Not Allowed" to a GET rather than a static
 > 404, and is how you tell the door is routed at all.
 >
-> **It does not depend on the Application Preset**, which is the first thing
-> everyone suspects and the reason to say so:
+> **Set the Framework Preset to `Services` on the import screen.** Vercel's own
+> guide states it as one of two necessary conditions:
+>
+> > "A project builds as services only when two conditions are both true: the
+> > project's framework is set to Services, and `vercel.json` contains a
+> > `services` key. If either is missing, Vercel falls back to its default
+> > framework detection and ignores your services configuration."
+> > — [vercel.com/kb/guide/vercel-services](https://vercel.com/kb/guide/vercel-services)
+>
+> That is the silent-404 shape exactly: preset `Other` → fallback detection →
+> nothing detected → an empty output that deploys, reports Ready and takes the
+> alias. And no file in your repository can set it for you: `framework` is not
+> a valid top-level key while `services` is present, so this is a project
+> setting or nothing.
+>
+> **One measurement here disagrees with that guide, and is recorded rather than
+> reconciled.** On 2026-08-27 two projects were read back from the Vercel API,
+> one reading preset `Services` and one reading `Other`, and BOTH built the
+> `services` block and served:
 >
 > | project's preset | `services` block built | serves                                 |
 > | ---------------- | ---------------------- | -------------------------------------- |
 > | `Services`       | `site` + `door`        | `/` 200 · `/llms.txt` 200 · `/mcp` 405 |
 > | `Other`          | `site` + `door`        | `/` 200 · `/llms.txt` 200 · `/mcp` 405 |
 >
+> Both facts are real and they cannot both be the whole rule. Possible readings
+> — the API's `framework` field being derived rather than the project setting,
+> or Beta behaviour changing between the guide's 2026-08-12 revision and that
+> measurement — are unverified, and guessing between them is what produced the
+> earlier version of this page, which told you the preset was RULED OUT and so
+> steered you away from the one step the vendor calls required. Set the preset.
+>
 > **One failure has been seen that none of this explains.** On a 205-document
 > record (2026-08-26, issue #197) the install ran, `ksor build` ran, every route
 > prerendered — and Vercel collected nothing. The deployment reported **Ready**,
@@ -262,9 +286,15 @@ are doing it wrong" — and only the first tier is true.
 | variable                                  | why                                                  |
 | ----------------------------------------- | ---------------------------------------------------- |
 | `KSOR_DB_URL`                             | the record's Postgres store                          |
-| `GEMINI_API_KEY`                          | embeds the incoming query, so retrieval works at all |
+| the provider key                          | embeds the incoming query, so retrieval works at all |
 | `KSOR_AUTH`, **or** a configured SSO door | see below                                            |
 
+The provider key is whichever variable `embedding.provider` in `instance.md`
+names — `GEMINI_API_KEY` for `gemini` (the default), `OPENAI_API_KEY` for
+`openai`. A record reads exactly one, and the boot refusal names the one it
+wanted: `embedding provider "openai" needs an API key and none was supplied —
+set OPENAI_API_KEY`.
+
 `KSOR_AUTH` takes one of two values, and the value IS the decision:
 
 ```sh
@@ -427,12 +457,21 @@ Plain `pnpm build` is `[public]`, so the safe thing is the default.
 
 Two supported answers, and a third that is yours.
 
-**Read through the door instead.** This is the one ksor is built for. The MCP
-surface already applies the audience scope **per request** and writes a
-`retrieval_log` row carrying the actor for every read — per-person governance
-with an audit trail, which a static site cannot have at any price. If the
-requirement is "who read what, and were they allowed to", that is the door, not
-the website.
+**Run a door per audience.** The door does NOT decide per request: it serves
+ONE viewer list, read from `KSOR_AUDIENCE` once at boot
+(`content-gateway/src/compose.ts`) and validated against the policy before it
+widens past `public`. Every caller holding a valid token for that door gets the
+same view of the record — `docs/authorization.md` says so plainly, and
+per-request visibility filtering is named out of scope in
+`specs/ksor/serve/spec.md`. So the answer is one process per viewer list, each
+with its own `KSOR_AUDIENCE`, behind whatever routing already decides who
+reaches which URL.
+
+What the door gives that a static site cannot is the **audit**, not the
+authorization: every read writes a `retrieval_log` row naming the verified
+caller, so "who read what" is answerable afterwards. That is worth having, and
+it is a different thing from "were they allowed to", which is still decided by
+which door they can reach.
 
 **Or split the record.** Content needing per-person confidentiality inside one
 tier is usually content that belongs in its own record, with its own gate. That

package/docs/ingesting.md

@@ -35,12 +35,12 @@ Ingest reads your markdown, sends each new chunk to an embedding provider, and
 writes the result to Postgres. So four things must be true, and none of them is
 created for you.
 
-|                      | what                                                                                                                                                                              | how                                                                                                                                     |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, in the KSoR Profile of OKF: `type`, `title`, `description`, `status` and `ksor.audience` in frontmatter | `pnpm check` validates it and explains any violation; `ksor build` must have written a current `build.lock.json` before ingest will run |
-| **The database**     | Postgres with **pgvector** — `CREATE EXTENSION vector;`                                                                                                                           | any managed host; the DDL below needs a role that can create tables                                                                     |
-| **The provider key** | `GEMINI_API_KEY` — the default embedding provider is `gemini-embedding-001`                                                                                                       | [aistudio.google.com](https://aistudio.google.com/apikey); the free tier covers a first corpus                                          |
-| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                        | already named by `instance.md`'s `database:` block                                                                                      |
+|                      | what                                                                                                                                                                                     | how                                                                                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, in the KSoR Profile of OKF: `type`, `title`, `description`, `status` and `ksor.audience` in frontmatter        | `pnpm check` validates it and explains any violation; `ksor build` must have written a current `build.lock.json` before ingest will run |
+| **The database**     | Postgres with **pgvector** — `CREATE EXTENSION vector;`                                                                                                                                  | any managed host; the DDL below needs a role that can create tables                                                                     |
+| **The provider key** | `GEMINI_API_KEY` — the default embedding provider is `gemini-embedding-001`. Declaring `embedding.provider: openai` reads `OPENAI_API_KEY` instead: each provider names its own variable | [aistudio.google.com](https://aistudio.google.com/apikey); free tier — embedding input is free of charge                                |
+| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                               | already named by `instance.md`'s `database:` block                                                                                      |
 
 Both variables go in `.env` beside `instance.md` — `ksor` reads it automatically,
 and `.env` is gitignored. Every command below is run **from your repository
@@ -197,8 +197,30 @@ measure until the corpus is in there.
 pnpm exec ksor calibrate --instance instance.md
 ```
 
-It ends with a block to paste into **`instance.md`**'s frontmatter, exactly as
-printed — the floor, the measurement recorded beside it as a comment, and
+**The synthesized door needs `GEMINI_API_KEY`, whatever your embedding provider
+is.** The command above writes one probe question per sampled passage with an
+LLM, and question synthesis is Gemini-only today — so a record on
+`embedding.provider: openai` embeds with `OPENAI_API_KEY` and would still be
+refused here for a Google key. That is a real gap, stated rather than papered
+over; the zero-LLM door below avoids it entirely and is the better choice on a
+free-tier key anyway, because a free key allows only a few generations a minute
+and a bigger corpus makes that worse, not better.
+
+Write your own in-corpus questions, one per line, and pass them:
+
+```sh
+pnpm exec ksor calibrate --instance instance.md --queries-file questions.txt
+```
+
+Six to ten real questions is enough. They should be things this record answers,
+in the words someone would actually ask — the floor is set by the WEAKEST of
+them, so a vague question drags it down and a question the record does not
+answer invalidates the measurement. The door is recorded beside the number
+(`door: queries-file`), because floors from the two doors are measured against
+different distributions and must never be compared as interchangeable.
+
+Either way it ends with a block to paste into **`instance.md`**'s frontmatter,
+exactly as printed — the floor, the measurement recorded beside it as a comment, and
 `floor_digest`, the digest of the retrieval predicate the floor was measured
 through. Paste it, then restart `ksor serve`: the floor is read at boot.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/.agents/skills/format-checker/check.mjs

@@ -11971,6 +11971,7 @@ function changedFields(before, after) {
 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. */
@@ -13551,6 +13552,7 @@ const lockSchema = object({
 	drafts: _enum(["hidden", "shown"]),
 	instance_sha256: hex64,
 	policy_sha256: hex64,
+	people_sha256: hex64,
 	ledger_sha256: hex64,
 	ledger_entries: array(object({
 		id: string().min(1),
@@ -13745,6 +13747,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 function gitFacts(root) {

package/templates/scaffold/.claude/skills/format-checker/check.mjs

@@ -11971,6 +11971,7 @@ function changedFields(before, after) {
 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. */
@@ -13551,6 +13552,7 @@ const lockSchema = object({
 	drafts: _enum(["hidden", "shown"]),
 	instance_sha256: hex64,
 	policy_sha256: hex64,
+	people_sha256: hex64,
 	ledger_sha256: hex64,
 	ledger_entries: array(object({
 		id: string().min(1),
@@ -13745,6 +13747,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 function gitFacts(root) {

package/templates/scaffold/AGENTS.md

@@ -100,8 +100,11 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    ```
 
    That is enough. `embedding:` is optional and already defaults to
-   `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`; write it out
-   only to pin the space explicitly or to change it — and note that model and
+   `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`. The other
+   shipped vendor is OpenAI — `provider: openai`, `model:
+text-embedding-3-small`, `dim: 1536`, key in `OPENAI_API_KEY` — and each
+   provider names its own key variable, so nothing else changes. Write the block
+   out only to pin the space explicitly or to change it — and note that model and
    dim are the PERSISTED identity of the embedding space, so changing either
    later means re-embedding the whole corpus. Keep `dim` at or below 2000 — the
    schema indexes a `vector` column directly and pgvector's HNSW takes a
@@ -114,7 +117,41 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    Leave `retrieval:` out for now — the gate is off and the server says so.
    Turning it on is step 4, AFTER the record is serving.
 
-2. **Copy `.env.example` to `.env`** and fill it in — `ksor` reads it
+2. **Get the database — your agent can do this one.** `.mcp.json` at the repo
+   root declares the MCP servers this project may reach. It ships with two:
+   `Neon`, which provisions the Postgres this step needs, and
+   `agentfactory-system-of-record`, a read-only KSoR record Panaversity operates
+   as an example of the surface being built here — not this project's record,
+   and not needed by anything below. Either can be deleted; the file is the
+   adopter's.
+
+   The Neon server acts on the whole Neon ACCOUNT, not on one database: it can
+   create and delete projects and branches. Show the plan before running it.
+   With it connected, ask:
+
+   > Using the Neon MCP server, create a project called `<your-record>` and
+   > enable the pgvector extension on it. Then create a branch called `dev`,
+   > and save that branch's connection string to `.env` as `KSOR_DB_URL`.
+   > Never print my API key. Show me the plan before you run anything.
+
+   That is `create_project`, `run_sql` (`CREATE EXTENSION vector`),
+   `create_branch` and `get_connection_string` — four real tools, no dashboard.
+   Prefer the OAuth flow: an API key pasted into `.mcp.json` would be committed,
+   because that file carries no secret and is not gitignored.
+
+   Any Postgres with pgvector works — Neon is the path with an MCP server, not a
+   requirement. Locally: `docker run -e POSTGRES_PASSWORD=x -p 5432:5432
+pgvector/pgvector:pg17`.
+
+   **`GEMINI_API_KEY` is the one step no agent can do.** No vendor mints an API
+   key over a protocol; it comes from a browser at
+   [aistudio.google.com/apikey](https://aistudio.google.com/apikey) and a human
+   pastes it. An agent working through this list should ask for it by name and
+   stop, rather than trying — and should say that the FREE TIER is enough:
+   embedding input on `gemini-embedding-001` is free of charge, so this is a
+   signup, not a bill.
+
+3. **Copy `.env.example` to `.env`** and fill it in — `ksor` reads it
    automatically, so nothing needs exporting, and `.env` is already gitignored.
    A real environment variable still wins over the file, so CI and production
    overrides behave normally.
@@ -134,7 +171,7 @@ Stand it up in this order (each step's errors explain how to fix themselves):
      intended dev shape. A PUBLIC deployment configures the SSO door instead —
      see the comments in `.env.example` and "Serving safely" below.
 
-3. **Bring it up.** Once, then every time:
+4. **Bring it up.** Once, then every time:
 
    ```sh
    pnpm provision  # schema (or migrate) + grant — the privileged acts, run once
@@ -219,7 +256,7 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    serves, or a DBA who holds the credentials that authorize ingest — not as a
    daily choice.
 
-4. **Turn the abstention gate on — deliberately, once it serves.** This is the
+5. **Turn the abstention gate on — deliberately, once it serves.** This is the
    step that makes "not in this corpus" a real answer, and it is measured, never
    guessed: