@panaversity/ksor 0.0.54 → 0.0.55

package/CHANGELOG.md

@@ -1,5 +1,184 @@
 # @panaversity/ksor
 
+## 0.0.55
+
+### Patch Changes
+
+- 4ecf549: Test infrastructure only — nothing an adopter installs behaves differently.
+
+  The behavioural evals scored a missing `top_cosine` as `-1`. When a provider
+  rate-limits, the read plane degrades to keyword-only by design, so searches
+  answer with no score — and the assertions then compared sentinels, reporting a
+  vendor outage as "the abstention floor is broken". Four CI failures in a day
+  read that way before anyone looked past the assertion. A missing score now
+  refuses, naming the cause, and never invents the number that is absent.
+
+- e476197: Fix the hello-world tutorial, which could not be completed as written.
+
+  Three defects, all found by walking the published 0.0.54 rather than by reading:
+
+  - Step 3's document declared `type: Policy`. `Policy` is a reserved type, so the
+    record demands `sources` — `ksor build`, `npm run check` and the dev server all
+    refused it, and steps 4 through 10 were unreachable. It is now `type: Document`,
+    the type the profile promises never to reserve, with a note on why and on what
+    an agent should do when it reaches for a reserved one.
+  - Step 1 scaffolds with `npx`, which emits an **npm** project, and every command
+    after it said `pnpm`. On that project `pnpm install && pnpm dev` fails with
+    `sh: next: command not found`. All sixteen commands are npm's now, and the step
+    that explains manager detection says which one the rest of the tutorial speaks.
+  - The captured outputs had been trimmed after capture, in a document whose second
+    paragraph promises they were "pasted as it appeared": `ksor serve`'s boot report
+    was missing the `trust` line it has always printed, the build outputs were
+    missing their timestamp, `source:` and `wrote` lines, and the port-conflict
+    refusal was quoted offering `pnpm serve` where it says `ksor serve`.
+
+  The walk also surfaced that `ksor init` leaves a repo with no commits, so every
+  reader's first build prints `source: unspecified`. Rather than hide it, the
+  tutorial now shows it and folds `git commit` into the approval step — which is
+  where provenance belongs anyway, and which lets the second build print a real
+  commit sha.
+
+  The tutorial also said `.mcp.json`'s "first is Neon's" and named the second
+  server nowhere, and said nothing about the Neon server acting on the whole Neon
+  account. Both are fixed here for the tutorial; the emitted scaffold's copies of
+  the same two defects are fixed separately.
+
+  Only the tutorial and the test that pins its prompts changed; nothing an adopter
+  installs behaves differently.
+
+- ae49524: Stop a spent OpenAI balance from quarantining content and flipping a generation,
+  and name the right variable when a provider key is missing.
+
+  **The serious one.** `insufficient_quota` — OpenAI's answer to an exhausted
+  balance, which arrives as 429 like an ordinary rate limit — was classified
+  non-retryable, correctly, because no amount of waiting adds credit. But
+  "non-retryable" is what the ingest drain reads as **poison chunk**: it
+  binary-splits the batch down to singletons and marks each `failed`. A spent
+  balance arrives on _every_ chunk, so a run walked the queue quarantining
+  everything it touched; if the failed fraction stayed under
+  `MAX_FAILED_FRACTION` (2%), `generationReady` admitted it and the generation
+  **flipped** — publishing a record in which exactly the passages the owner had
+  just edited were unsearchable, `ksor ingest` exit 0, the billing reason visible
+  only in `chunks.embed_error`. The same event on Gemini aborts the run, so
+  switching provider silently changed what a spent quota does.
+
+  The drain now has three answers instead of two: retryable (abort, chunks stay
+  pending), **fatal** (abort the same way, but without spending five backoffs
+  first — the account is what is wrong, not the passage), and everything else
+  (binary-split to the poison chunk). `isFatal` is optional on `EmbeddingProvider`,
+  so a provider that cannot tell keeps the old two-kind behaviour and Gemini's
+  path is unchanged.
+
+  **The missing-key refusal names the variable.** `ksor serve` on an
+  `embedding.provider: openai` record said `embedding provider "openai" needs an
+API key and none was supplied` and stopped — while `ksor serve --help`,
+  `env.example` and `docs/deploying.md` all named `GEMINI_API_KEY`, which that
+  door does not read. The registry row already held `keyEnv`; it now reaches the
+  operator (`— set OPENAI_API_KEY`), and all three documents describe the choice
+  instead of one vendor.
+
+  **`ksor calibrate`'s Gemini requirement is stated rather than papered over.**
+  Question synthesis is Gemini-only today, so a record embedding with
+  `OPENAI_API_KEY` is still refused for a Google key when calibrating through the
+  synthesized door. That gap is now said plainly in the refusal and in
+  `docs/ingesting.md`, which taught calibration without mentioning it. The
+  `--queries-file` door avoids it entirely.
+
+  **The OpenAI live test announces itself.** It is gated on `OPENAI_API_KEY`, no
+  workflow supplied one, and a false `describe.runIf` contributes nothing to a run
+  — so the suite its own header calls "the tripwire for vendor drift" was absent
+  from CI and reported as absent by nobody. It now prints `skipped — set
+OPENAI_API_KEY`, the way Gemini's does, and CI passes the secret so the tripwire
+  arms the moment one is added.
+
+  Found by an adversarial review of this week's commits.
+
+- ff99eb5: Hash `.ksor/people.yaml` into `build_id`, so the two surfaces of one build
+  cannot publish different provenance.
+
+  The phone book added in 0.0.53 rewrites the actor printed on every Owner,
+  Approved, Withdrawn and Trust row — `displayActor` replaces `human:contractor-a`
+  with "Human: Jane Doe, VP Compliance", and the identifier does not appear on the
+  page at all. It was hashed by nothing. `.ksor/governance.yaml` and
+  `.ksor/takedowns.yaml` are both in `build_id`; this one was left out, on the
+  stated reasoning that including it would refuse the next site build after a
+  spelling correction.
+
+  That is the trade critical rule 1 forbids, and the consequence was reachable
+  without doing anything unusual: edit a name, `pnpm check` stays green,
+  `ksor build` emits a byte-identical lock, and the deployed page publishes an
+  approver the `/md/` twin stamped with that same `build_id` contradicts. An
+  auditor reconciling the page against the lock finds nothing wrong, because the
+  string they are auditing was never covered by it.
+
+  Now: `people_sha256` joins `policy_sha256` and `ledger_sha256` in the lock and
+  in `build_id`; `.ksor/people.yaml` joins the inputs that move `source_commit`;
+  and the site's staleness gate compares it like the other three, so an edit the
+  lock never saw refuses with `ksor-lock-stale` naming the file. Refusing until
+  `ksor build` is re-run is the behaviour, not a regression — it is what every
+  other published byte already does.
+
+  Two things found alongside it, in the same file:
+
+  - `people.ts` claimed "duplicate keys are refused by the parser rather than
+    resolved by whichever came last". They were not. `uniqueKeys: true` makes the
+    parser RECORD a duplicate; `toJS()` still resolves last-wins, and nothing read
+    the errors — so two entries for one actor published the second person's name
+    on the first person's approval, the precise collision the map replaced a name
+    derivation to avoid. A duplicate now drops the whole book, and identifiers are
+    published instead.
+  - The rule lived behind a module that reads `instance.md` on import, so it could
+    only be tested by building a record on disk — which is why it shipped asserted
+    by a comment. It is now a leaf, `lib/people-rule.ts`, with the shipped
+    function under test.
+
+  **Upgrading:** a lock written before this refuses with `ksor-lock-invalid`
+  naming `people_sha256`; run `ksor build` and commit the lock it writes.
+
+  Found by an adversarial review of this week's commits.
+
+- b45d477: Say what the scaffold's `.mcp.json` attaches to an adopter's coding agent, and
+  stop the README telling them to destroy it.
+
+  `ksor init` emits `.mcp.json` with two servers. The emitted README and AGENTS.md
+  both said "the first is Neon" and named the second nowhere — so
+  `agentfactory-system-of-record`, a Panaversity-operated endpoint, was wired into
+  every adopter's coding agent with no emitted document mentioning it. `.mcp.json`
+  attaches servers to the agent that OPERATES the record; a server nobody
+  documented is a capability nobody reviewed.
+
+  Both are now named, with what each is and that either may be deleted. The second
+  is described as what it is: a read-only example record that is **not** the
+  adopter's and that nothing in the project depends on.
+
+  The Neon step also said only that the server exists. It acts on the Neon
+  _account_ — an agent holding it can create and delete projects and branches — so
+  the README and AGENTS.md now say that before handing over a prompt that runs
+  against real infrastructure, and point at Neon's own documentation for the
+  scopes rather than paraphrasing them.
+
+  And the "Test the door with an actual agent" section told the adopter to _write_
+  `.mcp.json` with a file containing only `test-record` — overwriting the Neon
+  entry the same README depends on two sections earlier — and then closed with
+  "Delete `.mcp.json`, or keep it". It now shows the entry to **add**, and says not
+  to delete the file.
+
+  A guard derived from `mcp.json` itself asserts every server key appears in both
+  emitted documents, so adding a server and saying nothing fails on the server
+  that was added. Mutation-tested: unnaming the second server turns both red.
+
+  Found by an adversarial review of this week's commits. Whether the scaffold
+  should ship a second, vendor-operated MCP record at all is an owner question and
+  is untouched here.
+
+- 5283084: Test infrastructure only — nothing an adopter installs behaves differently.
+
+  A skill's `description` is its trigger and nothing measured it (#30). Every
+  prompt the hello world tells a reader to say is now matched to a shipped skill
+  or recorded as needing none, and each skill's trigger phrases are pinned — so
+  narrowing one, the failure mode where a skill silently stops firing, goes red
+  naming the phrase. The model-scored half of that issue is untouched.
+
 ## 0.0.54
 
 ### Patch Changes

package/dist/checker/check-main.mjs

@@ -10892,7 +10892,7 @@ var require_public_api = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.stringify = stringify;
 }));
 //#endregion
-//#region ../content/dist/check-DNWlQuBg.mjs
+//#region ../content/dist/check-6fB_kR4G.mjs
 var import_dist = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	var composer = require_composer();
 	var Document = require_Document();
@@ -12150,6 +12150,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. */
@@ -13714,7 +13715,7 @@ function checkAgainstPolicy(concept, policy, refusals) {
 	}
 }
 //#endregion
-//#region ../content/dist/record-DnMnZelb.mjs
+//#region ../content/dist/record-Cxw0SUG3.mjs
 const hex64 = string().regex(/^[0-9a-f]{64}$/, "a sha256 hex digest");
 const viewerList = array(string().min(1));
 const lockSchema = object({
@@ -13732,6 +13733,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),
@@ -13928,6 +13930,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 function gitFacts(root) {

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 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-uhx2l1kC-C2BAxISt.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-BHQDvsKA.mjs
+//#region ../content-gateway/dist/main-BoKhKcP0.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -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-DM5TajmH.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
@@ -6228,6 +6229,14 @@ function isRetryable(exc) {
 * 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);
@@ -6278,6 +6287,9 @@ var OpenAiEmbeddingProvider = class {
 	isRetryableQuery(exc) {
 		return isRetryableQuery(exc);
 	}
+	isFatal(exc) {
+		return isFatal(exc);
+	}
 };
 /**
 * The embedding-provider registry — a plain object, NOT any discovery
@@ -6304,10 +6316,20 @@ var OpenAiEmbeddingProvider = 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 = {
@@ -6369,7 +6391,7 @@ function providerKeyEnv(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",
@@ -9275,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;
@@ -9826,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) => {
@@ -10633,7 +10657,7 @@ 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"));
@@ -11015,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.
@@ -11061,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),
@@ -11133,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
@@ -11179,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,
@@ -11189,6 +11216,7 @@ function composeLock(input) {
 			indexes,
 			instance_sha256,
 			policy_sha256,
+			people_sha256,
 			ledger_sha256,
 			ksor_version: input.ksorVersion,
 			drafts: input.drafts
@@ -11201,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: {
@@ -11363,6 +11392,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 /**
@@ -11373,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",
@@ -11563,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",
@@ -11605,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 ?? [],
@@ -13291,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"
 ];
 /**
@@ -13932,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

package/dist/{gateway-api-uhx2l1kC-C2BAxISt.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-uhx2l1kC.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))();
 /**
@@ -9159,6 +9159,14 @@ function isRetryable(exc) {
 * 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);
@@ -9209,6 +9217,9 @@ var OpenAiEmbeddingProvider = class {
 	isRetryableQuery(exc) {
 		return isRetryableQuery(exc);
 	}
+	isFatal(exc) {
+		return isFatal(exc);
+	}
 };
 /**
 * The embedding-provider registry — a plain object, NOT any discovery
@@ -9235,10 +9246,20 @@ var OpenAiEmbeddingProvider = 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 = {
@@ -9294,7 +9315,7 @@ function providerKeyEnv(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",

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, 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-uhx2l1kC-C2BAxISt.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

@@ -286,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

package/docs/ingesting.md

@@ -197,11 +197,16 @@ measure until the corpus is in there.
 pnpm exec ksor calibrate --instance instance.md
 ```
 
-**On a free-tier key, use the zero-LLM door instead.** The command above is the
-SYNTHESIZED door: it writes one probe question per sampled passage with an LLM,
-and a free key allows only a few generations a minute — a bigger corpus makes
-that worse, not better. Write your own in-corpus questions, one per line, and
-pass them:
+**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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.54",
+  "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

@@ -118,7 +118,15 @@ text-embedding-3-small`, `dim: 1536`, key in `OPENAI_API_KEY` — and each
    Turning it on is step 4, AFTER the record is serving.
 
 2. **Get the database — your agent can do this one.** `.mcp.json` at the repo
-   root declares the MCP servers this project may reach, and the first is Neon.
+   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

package/templates/scaffold/README.md

@@ -174,7 +174,26 @@ the variable name here only if you want a different one.
 ### 2. Get a database — your agent can do this one
 
 `.mcp.json` at the repo root declares the MCP servers this project may reach.
-The first is Neon's. With it connected, ask your coding agent:
+It ships with two, and both are yours to keep or delete — it is your file:
+
+| server                           | what it is                                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `Neon`                           | Neon's own hosted MCP server, for provisioning the Postgres the agent surface needs (step 2)     |
+| `agentfactory-system-of-record`  | a KSoR record Panaversity operates, served over MCP — an example of the surface you are building |
+
+The second is **not** your record and is not needed to run this project. It is
+read-only and it answers about the Agent Factory curriculum, not about your
+knowledge. Delete the entry if you would rather your agent not have it; nothing
+here depends on it.
+
+**Before you connect Neon, know what you are granting.** The Neon MCP server
+acts on your Neon *account*, not on one database: an agent holding it can create
+and delete projects and branches. Point it at an account you are willing to let
+an agent change, review the plan it shows you before approving, and read Neon's
+own documentation on the server's scopes and permissions rather than taking this
+paragraph as the whole of it.
+
+With it connected, ask your coding agent:
 
 > 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
@@ -254,17 +273,14 @@ separately](#the-agent-surface-deploys-separately). Any other operation is
 ### Test the door with an actual agent
 
 The MCP door is meant to be read by agents, so check it with one rather than
-with `curl`. With `pnpm serve` running, write `.mcp.json` at the repo root:
+with `curl`. With `pnpm serve` running, **add** an entry to the `.mcp.json` you
+already have — alongside `Neon`, not in place of it:
 
 ```json
-{
-  "mcpServers": {
     "test-record": {
       "type": "http",
       "url": "http://127.0.0.1:8080/mcp"
     }
-  }
-}
 ```
 
 **If you skipped `calibrate`, expect answers where this test wants refusals** —
@@ -288,7 +304,9 @@ Question 2 is the one that matters. Anything can answer questions it has the
 text for; refusing a plausible near-miss is the property that makes a system of
 record worth trusting, and it is the one that breaks quietly.
 
-Delete `.mcp.json`, or keep it — it holds no secret.
+Keep the `test-record` entry or remove it — it points at loopback and holds no
+secret either way. Do not delete `.mcp.json` itself: it is where `Neon` is
+declared, and step 2 above needs it.
 
 ---
 

package/templates/scaffold/env.example

@@ -10,8 +10,13 @@
 # explicitly instead of relying on a driver default that is due to change.
 KSOR_DB_URL=postgresql://user:password@host:5432/dbname
 
-# The embedding provider key. instance.md defaults to gemini-embedding-001.
+# The embedding provider key — ONE of these, whichever `embedding.provider` in
+# instance.md names. It defaults to gemini, so that is the one uncommented; on
+# `provider: openai`, comment this out and set OPENAI_API_KEY instead. A record
+# reads exactly one of them, and `ksor serve` names the one it wanted when it
+# is missing.
 GEMINI_API_KEY=
+# OPENAI_API_KEY=
 
 # ── Who may ask ─────────────────────────────────────────────────────────────
 # ONE variable, and its VALUE is the decision. `ksor serve` refuses to boot

package/templates/scaffold/gitignore

@@ -1,7 +1,8 @@
 # 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

package/templates/scaffold/system/site/lib/lock.ts

@@ -73,6 +73,8 @@ export interface ControlTexts {
   readonly policy: string;
   /** Null when `.ksor/takedowns.yaml` is not there — an empty ledger. */
   readonly ledger: string | null;
+  /** Null when `.ksor/people.yaml` is not there — no natural names declared. */
+  readonly people: string | null;
 }
 
 function sha256Text(text: string): string {
@@ -139,12 +141,17 @@ export function readLock(
     ["instance.md", lock.data.instance_sha256, sha256Text(control.instance)],
     [".ksor/governance.yaml", lock.data.policy_sha256, sha256Text(control.policy)],
     [".ksor/takedowns.yaml", lock.data.ledger_sha256, sha256Text(control.ledger ?? "")],
+    // The phone book publishes NAMES in place of stored actors, so an edit here
+    // changes the approver printed on every page. Left out, the site could
+    // publish one approver while the `/md/` twin stamped with the same
+    // `build_id` published another (review, 2026-09-01).
+    [".ksor/people.yaml", lock.data.people_sha256, sha256Text(control.people ?? "")],
   ] as const) {
     if (want === have) continue;
     refuse(
       "ksor-lock-stale",
       `${file} changed since ${LOCK_FILE} was written`,
-      "the lock's build_id is a hash over the record AND the three files that govern it, so a projection under a control file the lock never saw publishes what nothing checked — a denial lifted by deleting a line would otherwise leave the lock valid",
+      "the lock's build_id is a hash over the record AND the four files that govern it, so a projection under a control file the lock never saw publishes what nothing checked — a denial lifted by deleting a line would otherwise leave the lock valid",
       "run `ksor build` again and commit the lock with the change; lift a denial with `ksor takedown --revoke <id>`, never by editing the ledger",
     );
   }

package/templates/scaffold/system/site/lib/people-rule.ts

@@ -0,0 +1,56 @@
+/**
+ * What a phone book file DECLARES, as a pure function of its text.
+ *
+ * A LEAF, like `actor-display.ts`: `people.ts` roots itself at the project via
+ * `shared.ts`, which reads `instance.md` at module load, so a rule living
+ * there could only be exercised by building a whole record on disk first. That
+ * is a test nobody writes, and the duplicate-key rule below went four days
+ * asserted only by a comment because of it.
+ *
+ * A map comes back for every malformed shape rather than an error, because a
+ * phone book is DECORATION: a record with an unreadable one publishes
+ * identifiers, which is exactly what it did before the file existed.
+ */
+
+import { parseAllDocuments } from "yaml";
+
+/**
+ * The phone book a file DECLARES, as a pure function of its text.
+ *
+ * Separated from the read so the rule can be exercised without a record on
+ * disk: the loader below is a filesystem act rooted at `projectRoot`, and a
+ * test that has to build a whole scaffold to ask "what do two entries for one
+ * actor mean?" is a test nobody writes. A map is handed back for every
+ * malformed shape rather than an error, because a phone book is decoration:
+ * a record with an unreadable one publishes identifiers, which is what it did
+ * before the file existed.
+ */
+export function parsePeople(text: string): ReadonlyMap<string, string> {
+  try {
+    const docs = parseAllDocuments(text.replace(/^\ufeff/, ""), {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    const doc = docs[0];
+    if (doc === undefined) return new Map();
+    // `uniqueKeys: true` RECORDS a duplicate rather than refusing one — `toJS()`
+    // still resolves last-wins. Reading the option and not the errors is what
+    // made the claim above false: two entries for one actor silently published
+    // the second person's name on the first person's governance act.
+    if (doc.errors.length > 0) return new Map();
+    const value: unknown = doc.toJS();
+    if (typeof value !== "object" || value === null) return new Map();
+    const table = (value as { people?: unknown }).people;
+    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
+    const out = new Map<string, string>();
+    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
+      // A blank value is an entry someone started and left; printing "" would
+      // erase the identifier rather than replace it.
+      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}

package/templates/scaffold/system/site/lib/people.ts

@@ -8,8 +8,9 @@
  * `human:mjs` — most of the actors in a real record — had no expressible name
  * at all. It also collided: "Bashir Aziz" and "Bashira Ziz" both derive
  * `bashiraziz`, which would print one person's name on the other's governance
- * act. A map has neither problem, and duplicate keys are refused by the parser
- * rather than resolved by whichever came last.
+ * act. A map has neither problem, and a duplicate key drops the whole book
+ * rather than resolving to whichever came last — `uniqueKeys` only REPORTS the
+ * duplicate, so the errors have to be read for that to be true.
  *
  * ONE-WAY. The identifier is what the record stores, cites and checks against
  * the policy; this is only what a page prints. Nothing reads a name back into
@@ -34,8 +35,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
-import { parseAllDocuments } from "yaml";
-
+import { parsePeople } from "./people-rule";
 import { projectRoot } from "./shared";
 
 const PEOPLE_YAML = path.join(projectRoot, ".ksor", "people.yaml");
@@ -48,26 +48,7 @@ function loadPeople(): ReadonlyMap<string, string> {
     // Optional: its absence means "no natural names declared".
     return new Map();
   }
-  try {
-    const docs = parseAllDocuments(text.replace(/^/, ""), {
-      schema: "core",
-      uniqueKeys: true,
-      logLevel: "silent",
-    });
-    const value: unknown = docs[0]?.toJS();
-    if (typeof value !== "object" || value === null) return new Map();
-    const table = (value as { people?: unknown }).people;
-    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
-    const out = new Map<string, string>();
-    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
-      // A blank value is an entry someone started and left; printing "" would
-      // erase the identifier rather than replace it.
-      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
-    }
-    return out;
-  } catch {
-    return new Map();
-  }
+  return parsePeople(text);
 }
 
 let cached: ReadonlyMap<string, string> | null = null;

package/templates/scaffold/system/site/lib/stage-knowledge.ts

@@ -48,6 +48,7 @@ import type { Refusal } from "../record/refusal";
 const KNOWLEDGE = "knowledge/";
 const LEDGER_PATH = ".ksor/takedowns.yaml";
 const POLICY_PATH = ".ksor/governance.yaml";
+const PEOPLE_PATH = ".ksor/people.yaml";
 /**
  * Everything this build may publish, as bytes at bundle-relative paths: the
  * admitted concepts (copied), their companions (copied), ONLY the assets those
@@ -177,6 +178,7 @@ function planStage(recordDir: string, development: boolean): StagePlan {
           instance: record.files.get("instance.md") ?? "",
           policy: record.files.get(POLICY_PATH) ?? "",
           ledger: record.files.get(LEDGER_PATH) ?? null,
+          people: record.files.get(PEOPLE_PATH) ?? null,
         },
         { draftsRequested },
       );

package/templates/scaffold/system/site/record/load.ts

@@ -11,7 +11,17 @@ import path from "node:path";
 import type { RecordFiles } from "./check";
 import type { ScaffoldStructure } from "./hygiene";
 
-const CONTROL_FILES = ["instance.md", ".ksor/governance.yaml", ".ksor/takedowns.yaml"] as const;
+// `.ksor/people.yaml` is here because the SITE reads it and publishes what it
+// says — it rewrites the approver, owner and verifier printed on every document
+// page. A file that changes published bytes has to reach `build_id`, or the
+// human surface and the machine surface of one build can disagree about who
+// approved a document with nothing going red (found by review, 2026-09-01).
+const CONTROL_FILES = [
+  "instance.md",
+  ".ksor/governance.yaml",
+  ".ksor/people.yaml",
+  ".ksor/takedowns.yaml",
+] as const;
 /** Files the operating system writes behind the author's back: ignored, never reported. */
 const OS_JUNK = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
 

package/templates/scaffold/system/site/record/lock.ts

@@ -46,6 +46,7 @@ const lockSchema = z
     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), digest: hex64 }).strict()),
     audiences: z
@@ -89,6 +90,8 @@ export interface Lock {
   readonly drafts: Drafts;
   readonly instance_sha256: string;
   readonly policy_sha256: string;
+  /** The phone book the SITE publishes names from. Empty string when absent. */
+  readonly people_sha256: string;
   readonly ledger_sha256: string;
   /** `(id, digest)` per ledger entry, sorted by id — the baseline the next build compares TEXT against. */
   readonly ledger_entries: readonly { readonly id: string; readonly digest: string }[];
@@ -154,6 +157,7 @@ export interface BuildIdInputs {
   readonly indexes: readonly { readonly path: string; readonly sha256: string }[];
   readonly instance_sha256: string;
   readonly policy_sha256: string;
+  readonly people_sha256: string;
   readonly ledger_sha256: string;
   readonly ksor_version: string;
   readonly drafts: Drafts;
@@ -181,6 +185,9 @@ export function buildIdOf(inputs: BuildIdInputs): string {
       .sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
     instance_sha256: inputs.instance_sha256,
     policy_sha256: inputs.policy_sha256,
+    // The site prints what this file says in place of the stored actor, so it
+    // is published content and belongs in the id like any other.
+    people_sha256: inputs.people_sha256,
     ledger_sha256: inputs.ledger_sha256,
     ksor_version: inputs.ksor_version,
     drafts: inputs.drafts,
@@ -233,6 +240,8 @@ export interface LockInput {
   readonly drafts: Drafts;
   readonly instanceText: string;
   readonly policyText: string;
+  /** Null when `.ksor/people.yaml` does not exist, which is every record until an owner writes one. */
+  readonly peopleText: string | null;
   /** Null when the ledger file does not exist. */
   readonly ledgerText: string | null;
   readonly ledgerEntries: readonly { readonly id: string; readonly digest: string }[];
@@ -269,6 +278,7 @@ export function composeLock(input: LockInput): Lock {
     .map((i) => ({ path: i.path, sha256: sha256Hex(i.text) }));
   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: LOCK_FORMAT,
@@ -279,6 +289,7 @@ export function composeLock(input: LockInput): Lock {
       indexes,
       instance_sha256,
       policy_sha256,
+      people_sha256,
       ledger_sha256,
       ksor_version: input.ksorVersion,
       drafts: input.drafts,
@@ -291,6 +302,7 @@ export function composeLock(input: LockInput): Lock {
     drafts: input.drafts,
     instance_sha256,
     policy_sha256,
+    people_sha256,
     ledger_sha256,
     ledger_entries: [...input.ledgerEntries].sort((a, b) => compare(a.id, b.id)),
     audiences: { registry: [...input.audiences].sort(), viewers },