@panaversity/ksor 0.0.54 → 0.0.56

package/CHANGELOG.md

@@ -1,5 +1,374 @@
 # @panaversity/ksor
 
+## 0.0.56
+
+### Patch Changes
+
+- bf35e2f: `add-sources` 2.0.0: a file or a person, one skill — with a check the agent
+  runs instead of a rule it is asked to follow.
+
+  Two issues asked for two paths into the record. #31: an owner with a folder of
+  PDFs had no path — the skill stated the rules and converted nothing. #50: an
+  owner whose knowledge is only in their head had no path — the interview scoped
+  the record and stopped, leaving `knowledge/` full of samples about KSoR.
+
+  **They are one skill, not two.** The record draws no line between the kinds:
+  an interview attestation in `sources[].resource` passes `ksor build` today,
+  the fidelity rules read the same for both, and a real owner has BOTH — the
+  policy PDF and the exception everyone knows that the PDF never mentions. So
+  the person step runs after every file: "what does this not cover?" is the
+  question that finds the pages nobody wrote. A sibling skill would have made
+  the agent choose before it knew, and #50's own three-way trigger collision
+  vanishes.
+
+  **The source is a file.** Extract first, into a scratch file outside
+  `knowledge/` — the skill names the extractor per format (`pdftotext`,
+  `pandoc`, macOS `textutil`, `markitdown`) and what to do with none on `PATH`:
+  read the file directly and SAY the verification that follows is weaker. An
+  empty extraction is a scanned image, and the skill stops and tells the owner
+  rather than OCR and hope. Then decide the shape of the record, convert to
+  CommonMark a person would have written, name the source precisely, and run
+  the shipped check:
+
+  ```
+  node .agents/skills/add-sources/verify.mjs /tmp/in.txt knowledge/<path>.md
+  ```
+
+  `verify.mjs` — plain Node, no dependencies, the owner's to keep — lists every
+  number, date, threshold, code and capitalised name in the document's body that
+  does not appear in the extraction, case-folded and whitespace-collapsed.
+  Frontmatter and footnote ids are exempt, because they are the agent's words by
+  design. It is a floor, and says so: a value that passes was in the source; it
+  cannot see a value that was dropped, and it cannot tell a paraphrase from an
+  invention. Model-driven conversion is highest-fidelity for layout and
+  lowest for exact values, and this is the mechanical half of "copy load-bearing
+  values exactly".
+
+  **The source is a person.** Ask one question at a time in their words — who
+  triggers it, the steps, who approves and at what threshold, what goes wrong,
+  the exception — until someone who was not in the room could act on it. Draft
+  as the record, not a transcript; anything unconfirmed is an `Open question:`
+  line, never prose. The attestation goes in `sources` (who, role, instant,
+  conducted by) — there is no `provenance:` key, and no transcript is kept.
+  Two people describing one process differently stay two cited statements.
+
+  **Both end the same way, and the ending is new.** Read it back on `pnpm dev`,
+  then ask the owner to approve and write down what they said. A draft reaches
+  no machine surface, so a skill that stopped at the draft left every `llms.txt`
+  and every door empty — found on the journey walk: `1 document(s), 0 admitted`.
+
+  The rules that were restated here (placement, frontmatter, audience,
+  deprecation) now point at the emitted AGENTS.md instead. The trigger test that
+  asserted "no skill claims dictated knowledge" flips: add-sources claims it by
+  name, and no other skill may. Eleven cases hold `verify.mjs` to what it does
+  and, in three of them, to what it does not claim.
+
+- 73530e6: Prune the scaffold's skills to the three that make a record, and fix the two
+  seams every adopter hits on the way to one.
+
+  **Removed: `make-slides` and `make-summary`.** They were 45% of all shipped
+  skill text and 21.6% identical to each other — their own commit says
+  "make-summary is make-slides' discipline applied to prose". A companion is
+  downstream of a record existing and invisible to the agent surface (no route,
+  no `llms.txt` line, no MCP node); no fixture and no tutorial ever fired either;
+  and neither was ever shown to beat its absence, which is the bar AGENTS.md sets
+  for keeping a skill at all. Their one real rule — a card may only say what its
+  document says — already lives in the emitted AGENTS.md, and the site renders
+  companions exactly as before. Verified: the emitted checker passes with both
+  gone. `format-checker/SKILL.md` is cut to what AGENTS.md does not say; the
+  program it names is unchanged.
+
+  **Fixed: `intake-interview` was contradicting itself in its trigger.** The
+  always-resident description promised "seven questions"; the body has asked
+  three since 2026-08-26. The body handed off to "question 4" and "question 5",
+  neither of which exists, and claimed `add-sources` writes `verified:` entries —
+  nothing does. 1.6.0 says three, hands off to add-sources with whatever material
+  the owner has, and drops the false claim.
+
+  **Fixed: the recommended path turned a green record red.** Walked on the
+  published package:
+
+  - The README said run the interview, then "delete each starter as your own
+    knowledge arrives". Delete the five first and the build refuses
+    `ksor-record-empty` and writes nothing — a slug named by no document an
+    adopter reads. The README now says to write and approve one document of
+    your own before the last starter goes, and names the refusal.
+  - The hello-world tutorial approves as `human:you`. The interview then retires
+    `human:you` from the policy, and the tutorial's own document — still approved
+    by an actor the policy no longer names — refuses `ksor-approver-unauthorised`.
+    The interview now re-attributes every act recorded under the placeholder to
+    the owner's handle in the same change: it is the same person.
+
+  **Consolidated:** "the record says only what its source says — a gap is an
+  open question, never filled from general knowledge" lived only inside
+  `add-sources`; it is now stated once in the emitted AGENTS.md where every
+  other writing rule is.
+
+  Two deterministic gates hold all of this: a skill-consistency lint (a trigger's
+  question count matches its body; every "question N" resolves; every refusal
+  slug a document names is one the product raises; every skill a document names
+  ships) and a journey walk against the built CLI (interview → one draft →
+  approve → delete starters → retire the starter actor, plus the exact state
+  each refusal fires on). Every lint assertion was mutation-tested.
+
+  Found by four independent reviews of the plan to build a system of record,
+  before building any of it.
+
+- ab6a3ed: The agent tier: a shipped skill, run by a real coding agent, with the skill
+  and without it — the comparison AGENTS.md has always demanded and nothing had
+  ever run (issue #30).
+
+  `pnpm test:agent` scaffolds a fresh record, installs it, drops a real two-page
+  PDF in `src/`, and hands `claude -p` the prompt tutorial 2 hands the reader.
+  Once with `add-sources` present, once with it removed. What the agent leaves
+  behind is graded, and the split is the Testing contract's own: deterministic
+  behavioural graders GATE the with-skill arm — exactly one new document, under
+  `finance/`; `.ksor/*` and `instance.md` untouched; the record builds; `status:
+draft`, `sources` present, no `id:`/`name:`; page furniture gone; every
+  number, date and name in the body found in the extraction by the shipped
+  `verify.mjs`. Cost, turns, duration and the baseline arm are REPORTED, so the
+  delta is visible and a skill that stops winning is seen.
+
+  "Checker passes" is deliberately not a grader: while this was being designed a
+  baseline run passed the checker by hand-authoring `index.md` and editing
+  `.ksor/people.yaml` — the worse behaviour scoring better. Files touched is the
+  discriminating assertion.
+
+  It spends model tokens, so it is gated like the database tier: on
+  `ANTHROPIC_API_KEY` in CI (a repository secret the owner has not yet added; the
+  tier runs and reports itself skipped until then) or a logged-in `claude`
+  locally, pins a mid-tier model by default (a one-word reply on the default
+  model measured $0.25), and runs from `skill-evals.yml` on push to main and by
+  hand — never per pull request.
+
+  What it cannot measure is written in the suite rather than implied: a
+  conversational skill needs a scripted owner, "reads as a finished page" needs
+  a browser, and the adopter's own model is whatever they run.
+
+  Decision 31 records the three choices this week made about the skill surface —
+  pruned to three, one skill for a file and a person, and this harness shape
+  over the Python trigger script that was proposed and measured wanting.
+
+- c34cc3a: Tutorial 2, _Make it yours_: the walk from hello world's record to one that is
+  only the owner's — every output run and pasted as it appeared.
+
+  The intake interview and what it does to the placeholder approver; one policy
+  brought in from a real PDF, with the shipped check catching the one number the
+  conversion got wrong; one procedure that only ever lived in someone's head,
+  written with the thing they were not sure of as an open question rather than
+  prose; the read-back on the site and the approval act; then the samples go and
+  the tool that approved them leaves the policy. Two refusals do work on the way,
+  and the tutorial says exactly which state each fires on.
+
+  The prompt-accounting test now covers both tutorials from one table, so a new
+  prompt in either fails until someone names the skill that answers it. Only that
+  test changes under `packages/`; nothing an adopter installs behaves differently.
+
+- 87a3542: Correct a claim the tutorial made about `build_id`, and guard the general rule.
+
+  `buildIdOf` hashes `ksor_version` along with the record — deliberately, because
+  "what produced this" is part of what a publication is. So a captured `build_id`
+  is correct for exactly one release, and the sentence 0.0.54's tutorial fix added
+  — "Your timestamp will differ; the `build_id` will not" — was already false when
+  0.0.55 published it. A reader on any later ksor sees a hash that does not match
+  theirs and nothing saying why.
+
+  Found by walking the published package rather than by reading the diff: the same
+  practice that caught the tutorial being uncompletable caught the correction being
+  wrong.
+
+  The tutorial now says the id carries the toolchain, names the version its
+  outputs were captured on, and points at the reproducibility a reader can
+  actually check — run `ksor build` twice on one tree and the id is identical.
+  Both captured blocks are re-taken from a 0.0.55 walk.
+
+  A guard in `docs-truth.integration.test.ts` holds the general rule rather than
+  the sentence: a document printing a concrete `build_id` must say what moves one,
+  within 700 characters of the id. It is PROXIMITY rather than presence — the
+  first version asked whether "toolchain" appeared anywhere in the file, the file
+  already used the word once for an unrelated reason, and removing the caveat left
+  it green. Caught by mutation, and the tightened version immediately found a
+  second uncaveated id in the same document.
+
+## 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