@panaversity/ksor 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -1,5 +1,223 @@
 # @panaversity/ksor
 
+## 0.0.12
+
+### Patch Changes
+
+- 36e4a4c: The scaffold documents what a CLIENT has to do to reach a public MCP door
+
+  `ksor serve` implements the OAuth Resource Server handshake — an
+  unauthenticated request gets a 401 carrying
+  `WWW-Authenticate: Bearer resource_metadata="…"`, and that document names the
+  record's resource identifier and its authorization server, so a client discovers
+  where to authenticate instead of being told. None of it was written down
+  anywhere an adopter or their agent reads. The operator half was documented (the
+  three environment variables); the half their agents actually execute was not.
+
+  The scaffold's `AGENTS.md` now walks the three steps, and names the failure that
+  goes wrong quietly: a token minted for a different audience is a perfectly valid
+  token, and this door rejects it, so `aud` against `KSOR_JWT_ALLOWED_AUDIENCES` is
+  the first thing to compare when a client authenticates fine and still gets 401.
+  It also records the two behaviours a client author has to know and could not have
+  guessed — RS256 only, no opaque-token introspection, and an unknown key id
+  answering 503 rather than 401, because during a key rotation the token is
+  probably good and retrying beats sending the user back through a login.
+
+  This closes one of the three items named in issue #26; the worked provider
+  recipes and the introspection/rotation policy remain open there.
+
+- 125970c: Every 401 from the MCP door carries its `WWW-Authenticate` challenge, not just the first
+
+  Only the missing-token branch emitted `WWW-Authenticate: Bearer
+resource_metadata="…"`. A token that failed verification — expired, wrong
+  audience, no subject, bad signature — came back as a bare 401. That is the most
+  common 401 a real client will ever see, because tokens expire mid-conversation,
+  and it left the client with no pointer back to the resource-metadata document:
+  it could not re-discover the authorization server it had just been talking to.
+  Only a caller that had never sent a token was told where to go.
+
+  The MCP authorization spec requires `WWW-Authenticate` on a 401 without
+  qualification. Every 401 now carries it, with RFC 6750's `error="invalid_token"`
+  so a client refreshes rather than retrying the dead token.
+
+  A **503** stays deliberately unchallenged: an unreachable key set is our outage,
+  not the token's fault, and challenging there would send a user whose token is
+  perfectly good back through a login over a key-fetch failure.
+
+  Found by adversarially checking the release that documented this door. The
+  adversarial auth suite missed it by asserting the STATUS of each rejection and
+  never the header — it now sweeps every 401-producing token and asserts the
+  challenge on each, with the 503 as the negative control.
+
+- 0a94e31: A 503 refusal no longer puts the database host and user on the wire
+
+  When the deferred boot checks fail, `/mcp` refuses with the thrown error's
+  message in full under `data.detail`. For the three authored failures that is the
+  point — a too-old schema, a governance violation and a text-search mismatch each
+  carry a multi-line remedy the operator has to act on. But the catch treated every
+  error alike, and `pg` writes the host, its resolved address, the port and the
+  database user into its connection and authentication failures. Those went out
+  verbatim to any caller who could reach the door.
+
+  What may leave is now decided in one place and by TYPE, not by inspecting
+  message text: a class we wrote is a class whose words we control. A driver error
+  is refused with its class named and its text withheld, and the caller is told
+  which kind of failure it is — infrastructure, not their request.
+
+  The full text still reaches the operator, deliberately: the refusal says the
+  reason is in the server's logs, and the deferred-boot line recorded only the
+  error's NAME, so before this the real message existed nowhere. That is also why
+  the boot checks are not sanitised at their source — reducing a driver error to a
+  class name early would destroy the one copy anyone can act on.
+
+  **The test that covered this was holding it in place.** It asserted that
+  `http.ts` contains the literal string `data: { detail: message }` — so the leak
+  was pinned by an assertion with reasoning attached. Grepping source is the right
+  instrument for "does this check run before dispatch", because position is a
+  property of source, and the wrong one for "what does the response contain".
+  Response contents are now asserted against real bodies, including a `pg`-shaped
+  connection failure whose host, address, port and user must all be absent.
+
+  Verified live: a gateway pointed at an unreachable database answers
+  `the content store is unavailable (Error)` with no host, port, user or database
+  name anywhere in the body, while the server log carries
+  `connect ECONNREFUSED 127.0.0.1:59999` in full.
+
+- 1dd6211: The dimension ceiling says which shape it applies to, instead of blaming pgvector
+
+  `ksor schema` refuses an embedding dimension above 2000 with
+  "(pgvector vector + HNSW ceiling)". The refusal is right and the reason was
+  wrong: pgvector indexes a `vector` to 2000, but a **`halfvec` to 4000**, via an
+  expression index on the cast — verified live against a real database, where
+  `hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops)` plans an Index Scan.
+
+  The old wording read as pgvector's own limit, so an adopter whose model emits
+  more than 2000 dimensions could conclude it was unusable here, over a wall that
+  is not one. The message now names the shape the ceiling belongs to — this schema
+  declares `VECTOR(dim)` columns and indexes one directly — and the constant
+  carries why raising it is a decision rather than an edit: every query site would
+  have to use the same cast as the index or fall silently back to a sequential
+  scan, and the halfvec arm's float16 rounding lands on the score the abstention
+  gate reads.
+
+  The same claim is corrected in the scaffold's `AGENTS.md`, which gains the reason
+  `dim: 1536` is the shipped default: `gemini-embedding-001` emits 3072 and ksor
+  asks it for 1536, which per Google's published MTEB table costs nothing
+  measurable — 1536 scores 68.17 against 2048's 68.16.
+
+  The 2000 refusal is unchanged. Issue #49 records the decision it now points at.
+
+## 0.0.11
+
+### Patch Changes
+
+- 0a0dd27: A record describes itself on the surface agents discover it through
+
+  `/.well-known/mcp/server.json` carried one hard-coded sentence — "The <name>
+  Knowledge System of Record: governed markdown served with citations and honest
+  abstention." — byte-identical in every ksor record ever scaffolded. An agent
+  choosing between records in a registry learned nothing from any of them, which
+  is the opposite of what that document exists for.
+
+  The description now comes from the record's own prose: its display title and the
+  first real sentence of `instance.md`, which is what the intake interview writes.
+  A record whose owner has not described it yet SAYS so rather than borrowing a
+  confident sentence it has not earned — the same answer the MCP door already
+  gives an agent that connects, so the two surfaces do not disagree about whether
+  this record knows what it is.
+
+  The scaffold's opening paragraphs are authoring guidance, not scope, so the
+  template is detected across the whole body rather than paragraph by paragraph:
+  publishing instructions-to-the-author as a description would be worse than
+  admitting there is none.
+
+- 0fe759d: Three defects found by auditing 0.0.10 against a live record
+
+  **A repeated `sslmode` was read the wrong end.** `pinnedTlsDsn` took the FIRST
+  value of a repeated parameter; `pg` takes the LAST. So on
+  `?sslmode=require&sslmode=disable` — whose effective mode is `disable` — the pin
+  saw a weak mode, collapsed the duplicates into one `verify-full`, turned TLS on,
+  and printed "TLS verified" at an operator whose DSN ended in `disable`. The
+  direction was safe; silently overruling an explicit opt-out and then misreporting
+  it was not. All three TLS functions now read the mode the driver will use.
+
+  The same sweep asserted the larger worry the pin creates — that re-serializing a
+  connection string could alter a credential. Seventeen DSNs with the passwords
+  people actually paste (raw `@`, spaces, `%`, `+`, brackets, non-ASCII,
+  percent-encoded separators) are now checked field by field against `pg`'s own
+  resolved view: everything the driver derives is byte-identical, and so is the
+  TLS decision.
+
+  **The outline's `position` disclosed documents an audience may not see.** It was
+  the rank in the whole record, so a public caller received 1, 3, 4 — a gap exactly
+  where an internal sibling sat, telling them something exists and roughly where.
+  The same row's `child_count` was already computed over visible children only, so
+  one response object disagreed with itself. `position` is now the rank among the
+  siblings the caller can see, computed as a window over the filtered set so it
+  stays correct across pages and at every depth, and both it and `depth` say what
+  they are in the tool schema.
+
+  **`ksor serve` now says when the record has no identity yet.** The MCP door
+  already refused to pass an unedited `instance.md` to agents as instructions —
+  it substitutes a plain statement that the scope is unstated — but the operator
+  starting the server was told nothing, so a record serving with no declared
+  identity looked exactly like one that had been described. It is a boot line now,
+  beside the abstention posture: both answer "how much should I trust this".
+
+- f5cd885: The bearer door's key line joins the boot block instead of interrupting it
+
+  In bearer mode the line naming where the signing keys were discovered printed
+  before the aligned posture block and in a different shape, so it read as a stray
+  log line rather than as part of what the server was telling you about itself. It
+  is a `keys` row in the block now, under `auth`, resolved at boot exactly as
+  before.
+
+- 5f30b5f: The site build no longer fails when two evaluations of the record staging overlap
+
+  The scaffold stages a per-audience copy of the record before the site build
+  reads it, removing the previous stage first. `rmSync(..., { force: true })`
+  suppresses ENOENT but retries nothing: Node retries EBUSY / EMFILE / ENFILE /
+  ENOTEMPTY / EPERM only when `maxRetries` is set, and it defaults to zero. The
+  bundler evaluates the source config more than once when it wants it in more than
+  one place, so one run could remove the stage while another was still copying
+  into it — surfacing as `ENOTEMPTY` and failing the entire site build (seen once
+  in CI, 2026-08-21).
+
+  The removal now asks for those retries. Losing that race is safe: the stage is a
+  deterministic function of the record and the denylist, so redoing it produces
+  the same bytes.
+
+  Three claims in the scaffold's `AGENTS.md` that recent releases made false are
+  also corrected: `--actor` no longer "defaults to the operating user" (it is
+  required, and there is no default by design); the signing keys are discovered
+  from the SSO's own metadata rather than fetched from Better Auth's path; and the
+  `order:` key now drives the MCP `outline` tool alongside the sidebar and
+  `llms.txt`, which is what "one order drives every surface" was always supposed
+  to mean.
+
+- 4a1c154: The shrink guard guards `ksor ingest --flip` again — it had stopped
+
+  `.env.example` documents `KSOR_MAX_SHRINK` as "a corpus that shrinks by more
+  than this FRACTION refuses to flip". In 0.0.10 it did not. Deleting eight of ten
+  documents and running `ksor ingest --flip` published the two that were left,
+  silently, exit 0.
+
+  The cause was the fix that stopped a refused ingest from publishing. That moved
+  the flip out of `buildGeneration` and into the command, so the governance gate
+  could run against the new generation BEFORE it became the active one — and the
+  shrink check, which lived inside the build's flip branch, was stepped straight
+  over. The library test that covers the guard stayed green throughout, because it
+  drives `buildGeneration` directly with `flip: true`, which is no longer the path
+  the CLI takes.
+
+  There is now one answer to "may this generation be activated" — `flipRefusal` —
+  and both flip paths ask it, in the same transaction as the flip itself. The new
+  test drives the command rather than the library, so a guard that only one of two
+  paths performs fails the tier that proves it.
+
+  Verified against a live record: a 10 → 2 node build now names all eight removed
+  documents, refuses with exit 1, and leaves the previous generation serving.
+
 ## 0.0.10
 
 ### Patch Changes

package/dist/cli.mjs

@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-Mjgb3l_o.mjs
+//#region ../content-gateway/dist/main-CqOtG-q1.mjs
 /**
 * A connection could not be ESTABLISHED in time — retryable.
 *
@@ -93,6 +93,20 @@ function isLoopbackHost$1(hostname) {
 	return host === "" || host === "localhost" || host === "127.0.0.1" || host === "::1";
 }
 /**
+* The sslmode the DRIVER will use, which is the LAST one written.
+*
+* `URLSearchParams.get` returns the FIRST value; `pg` takes the last. On
+* `?sslmode=require&sslmode=disable` those disagree, and reading the first made
+* the pin treat an explicitly disabled connection as a weak one — collapsing the
+* duplicates into a single `verify-full`, turning TLS on, and printing "verified"
+* at an operator whose DSN ended in `disable`. The direction was safe; silently
+* overruling an explicit opt-out and then misreporting it is not (found by
+* sweeping the driver's own parser, 2026-08-21).
+*/
+function effectiveSslMode$1(url) {
+	return (url.searchParams.getAll("sslmode").at(-1) ?? "").toLowerCase();
+}
+/**
 * The DSN ksor actually connects with — the weak sslmode SPELLED OUT.
 *
 * pg 8 treats `sslmode=require|prefer|verify-ca` as aliases for `verify-full`,
@@ -116,8 +130,7 @@ function pinnedTlsDsn$1(dsn) {
 		return dsn;
 	}
 	if (isLoopbackHost$1(url.hostname)) return dsn;
-	const mode = (url.searchParams.get("sslmode") ?? "").toLowerCase();
-	if (!WEAK_SSLMODES$1.includes(mode)) return dsn;
+	if (!WEAK_SSLMODES$1.includes(effectiveSslMode$1(url))) return dsn;
 	url.searchParams.set("sslmode", "verify-full");
 	return url.toString();
 }
@@ -133,7 +146,7 @@ function tlsPosture(dsn) {
 		return null;
 	}
 	if (isLoopbackHost$1(url.hostname)) return null;
-	const mode = (url.searchParams.get("sslmode") ?? "").toLowerCase();
+	const mode = effectiveSslMode$1(url);
 	if (mode === "disable") return "TLS off (sslmode=disable)";
 	if (mode === "no-verify") return "TLS UNVERIFIED (sslmode=no-verify)";
 	if (WEAK_SSLMODES$1.includes(mode)) return `TLS verified (sslmode=${mode} pinned to verify-full)`;
@@ -189,7 +202,7 @@ function tlsOptionsFor$1(dsn) {
 		return;
 	}
 	if (isLoopbackHost$1(url.hostname)) return void 0;
-	const mode = (url.searchParams.get("sslmode") ?? "").toLowerCase();
+	const mode = effectiveSslMode$1(url);
 	if (mode === "disable" || mode === "no-verify") return void 0;
 	return { rejectUnauthorized: true };
 }
@@ -435,6 +448,8 @@ const CHUNK_POLICY$1 = "heading-aware-1500-content-only-v5";
 * The Markdown BODY below the frontmatter is the authored agent-surface
 * instructions — byte-preserved, stripped only at the edges.
 */
+/** Mirrors `schema.ts`'s ceiling, so a bad `dim:` is refused when instance.md is
+*  PARSED rather than when the DDL is rendered. The why lives there. */
 const EMBED_DIM_MAX$1$1 = 2e3;
 const SUPPORTED_FORMATS$1$1 = [1];
 var InstanceParseError$1 = class extends Error {
@@ -528,7 +543,7 @@ const groupSchemas$1 = {
 	embedding: z.object({
 		provider: z.string().min(1).default("gemini"),
 		model: z.string().min(1).default(EMBED_MODEL$1),
-		dim: z.coerce.number().int().min(1).max(EMBED_DIM_MAX$1$1).default(EMBED_DIM$1)
+		dim: z.coerce.number().int().min(1).max(EMBED_DIM_MAX$1$1, { error: `at most ${EMBED_DIM_MAX$1$1}: this schema declares VECTOR columns and indexes one directly, and pgvector's HNSW takes a vector to ${EMBED_DIM_MAX$1$1}` }).default(EMBED_DIM$1)
 	}),
 	retrieval: z.object({
 		/**
@@ -2058,7 +2073,22 @@ walk AS (
     -- gates each row on its OWN visibility (round-9 review of PR 43).
     WHERE n.tenant_id = $1 AND n.status = 'published' AND w.depth < $5
 )
-SELECT w.slug, w.kind, w.title, w.heading_path, w.position, w.depth,
+-- The rank among the siblings THIS CALLER CAN SEE, not the stored one.
+--
+-- content_nodes.position is the rank in the whole record, so a tier that
+-- cannot see a sibling saw a GAP where it sat -- 1, 3, 4 -- which discloses
+-- that a document exists and roughly where, to a caller the record refuses to
+-- show it to. The same row's child_count was already computed over visible
+-- children only, so one response object disagreed with itself about whether
+-- hidden siblings are disclosed (found live 2026-08-21).
+--
+-- Computed as a WINDOW over the filtered set: window functions run after WHERE
+-- and before LIMIT/OFFSET, so the rank is the true visible sibling rank on
+-- every page and at every depth. Doing it in JS would have to renumber a page
+-- at a time -- which is how this query already produced two paging defects.
+SELECT w.slug, w.kind, w.title, w.heading_path,
+       row_number() OVER (PARTITION BY w.parent_id ORDER BY w.sort_key)::int AS position,
+       w.depth,
        (SELECT count(*) FROM content_nodes ch
          WHERE ch.tenant_id = $1 AND ch.generation = w.generation
            AND ch.parent_id = w.node_id AND ch.status = 'published'
@@ -2903,9 +2933,23 @@ const FRAMEWORK_INSTRUCTIONS = `You are answering from a Knowledge System of Rec
 * replaced it with "has not yet been described" (review of PR #43).
 */
 const TEMPLATE_MARKER = "_fill this in; it is";
+/**
+* Has the owner said what this record is FOR yet?
+*
+* The MCP door already answers honestly when they have not — it replaces the
+* template with a plain statement that the scope is unstated. But the operator
+* starting the server was told nothing, so a record serving with no declared
+* identity looked exactly like one that had been described. The boot report is
+* where that belongs, beside the abstention posture: both are answers to "how
+* much should I trust what this thing says".
+*/
+function recordIsUndescribed(authored) {
+	const body = authored.trim();
+	return body === "" || body.includes(TEMPLATE_MARKER);
+}
 function composeInstructions(authored) {
 	const body = authored.trim();
-	return body === "" || body.includes(TEMPLATE_MARKER) ? `${FRAMEWORK_INSTRUCTIONS}
+	return recordIsUndescribed(authored) ? `${FRAMEWORK_INSTRUCTIONS}
 
 (This record has not yet been described by its owner — instance.md still carries the scaffold template. Treat its scope as unstated.)` : `${FRAMEWORK_INSTRUCTIONS}
 
@@ -2955,8 +2999,8 @@ const OUTLINE_OUTPUT = z.object({
 		kind: z.string(),
 		title: z.string(),
 		heading_path: z.string(),
-		position: z.number().int(),
-		depth: z.number().int(),
+		position: z.number().int().describe("Rank among the siblings YOU can see, from 1. Rows already arrive in reading order, so this is for citing a place, not for sorting."),
+		depth: z.number().int().describe("Levels below the record's root, so rows are self-locating."),
 		child_count: z.number().int(),
 		permalink: z.string().nullable().describe("The page a person can open, when the record publishes one; null otherwise."),
 		has_content: z.boolean()
@@ -3568,6 +3612,16 @@ function abstainPosture(floor) {
 	return `floor ${floor} — below it, this record abstains`;
 }
 /**
+* What the boot report says when instance.md is still the scaffold template.
+*
+* Not a scolding: a level-0 record is allowed to be undescribed and this is not
+* an error. It is stated because the instance.md body IS the agent surface's
+* system prompt, so leaving it unwritten is a decision with a runtime effect —
+* every agent is told this record's scope is unstated — and an operator should
+* learn that from the server rather than from an agent's answer.
+*/
+const UNDESCRIBED_RECORD = "instance.md is still the scaffold template — agents are told this record's scope is unstated; run the intake interview to describe it";
+/**
 * Composition (oracle main.py's boot order, adapted): instance → DSN via
 * the declared env NAME → provider → pool → space guard → service context.
 * Auth is built by the door that needs it (http.ts) — BEFORE the pool
@@ -3671,6 +3725,54 @@ async function compose(instancePath, version) {
 	};
 }
 /**
+* The body of a deferred-boot refusal, and the one decision inside it: whose
+* message may go on the wire.
+*
+* Three AUTHORED failures carry a remedy written for the operator —
+* `SchemaVersionError`, `GovernanceGateError`, `TextSearchConfigMismatch`. Their
+* whole multi-line message is the point; a caller that receives only the first
+* line has been told a problem exists and not how to end it.
+*
+* Everything else reaching this catch is infrastructure — most of it straight
+* from `pg`, whose connection and authentication failures name the host, the
+* resolved address, the port and the database user. Those went out verbatim
+* under `data.detail`, because the catch treated every error alike.
+*
+* So the split is by TYPE, not by message inspection: a class we wrote is a
+* class whose text we control. A driver error is refused with its class named
+* and its text withheld — the operator finds the real message in the server's
+* own logs, which is where an infrastructure fault belongs.
+*/
+/**
+* Did WE write this error's text?
+*
+* Named classes only. Matching on message prose would put the decision back
+* inside the strings it is meant to police, and a reworded driver error would
+* quietly re-open the leak.
+*/
+function isAuthored(error) {
+	return error instanceof SchemaVersionError || error instanceof GovernanceGateError$1 || error instanceof TextSearchConfigMismatch;
+}
+function refusalBody(error) {
+	if (isAuthored(error)) return {
+		jsonrpc: "2.0",
+		error: {
+			code: -32001,
+			message: `this record cannot be served: ${error.message.split("\n")[0] ?? ""}`,
+			data: { detail: error.message }
+		},
+		id: null
+	};
+	return {
+		jsonrpc: "2.0",
+		error: {
+			code: -32001,
+			message: `this record cannot be served: the content store is unavailable (${error instanceof Error ? error.name : "Error"}). The reason is in this server's logs; it is withheld here because a driver error names the database host and user.`
+		},
+		id: null
+	};
+}
+/**
 * The MCP door: the SDK v2 HTTP entry (Request → Response, stateless)
 * behind Hono, serving the 2026-07-28 revision with 2025-era clients still
 * answered through the stateless fallback. Modern exchanges are buffered JSON;
@@ -3736,10 +3838,11 @@ function resolveSecurity(bind) {
 }
 async function runHttp(composition) {
 	const auth = buildAuth(process.env);
+	const keyLines = [];
 	if (auth.mode === "public") {
 		const keys = await auth.jwks();
-		console.error(`auth: signing keys via ${keys.source} — ${keys.url}`);
-		if (keys.advisory !== null) console.error(keys.advisory);
+		keyLines.push(bootLine("keys", `${keys.source} — ${keys.url}`));
+		if (keys.advisory !== null) keyLines.push(bootLine("", keys.advisory));
 	}
 	const resourceMetadataUrl = auth.mode === "public" ? new URL("/.well-known/oauth-protected-resource/mcp", auth.config.resourceUrl).toString() : "";
 	const bind = resolveBind(process.env);
@@ -3833,16 +3936,8 @@ async function runHttp(composition) {
 		if (verifyBoot !== null) try {
 			await verifyBoot();
 		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return new Response(JSON.stringify({
-				jsonrpc: "2.0",
-				error: {
-					code: -32001,
-					message: `this record cannot be served: ${message.split("\n")[0]}`,
-					data: { detail: message }
-				},
-				id: null
-			}), {
+			console.error(`refusing requests — boot checks failing: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+			return new Response(JSON.stringify(refusalBody(error)), {
 				status: 503,
 				headers: { "content-type": "application/json" }
 			});
@@ -3886,7 +3981,7 @@ async function runHttp(composition) {
 				identity = await auth.verify(token);
 			} catch (error) {
 				const transient = error instanceof TokenVerifyError && error.transient;
-				return c.json({ error: transient ? "token verification temporarily unavailable" : "invalid token" }, transient ? 503 : 401);
+				return c.json({ error: transient ? "token verification temporarily unavailable" : "invalid token" }, transient ? 503 : 401, transient ? {} : { "www-authenticate": `Bearer error="invalid_token", resource_metadata="${resourceMetadataUrl}"` });
 			}
 			bearer = token;
 		}
@@ -3925,7 +4020,9 @@ async function runHttp(composition) {
 		});
 		s.once("error", reject);
 	});
+	if (recordIsUndescribed(instance.instructions)) console.error(bootLine("identity", UNDESCRIBED_RECORD));
 	console.error(bootLine("auth", authPosture(auth.mode, bind.host)));
+	for (const line of keyLines) console.error(line);
 	console.error(bootLine("abstain", abstainPosture(instance.abstain.vectorFloor)));
 	console.error(bootLine("serving", `http://${bind.host}:${bind.port}/mcp`));
 	let draining = false;
@@ -4080,6 +4177,20 @@ function isLoopbackHost(hostname) {
 	return host === "" || host === "localhost" || host === "127.0.0.1" || host === "::1";
 }
 /**
+* The sslmode the DRIVER will use, which is the LAST one written.
+*
+* `URLSearchParams.get` returns the FIRST value; `pg` takes the last. On
+* `?sslmode=require&sslmode=disable` those disagree, and reading the first made
+* the pin treat an explicitly disabled connection as a weak one — collapsing the
+* duplicates into a single `verify-full`, turning TLS on, and printing "verified"
+* at an operator whose DSN ended in `disable`. The direction was safe; silently
+* overruling an explicit opt-out and then misreporting it is not (found by
+* sweeping the driver's own parser, 2026-08-21).
+*/
+function effectiveSslMode(url) {
+	return (url.searchParams.getAll("sslmode").at(-1) ?? "").toLowerCase();
+}
+/**
 * The DSN ksor actually connects with — the weak sslmode SPELLED OUT.
 *
 * pg 8 treats `sslmode=require|prefer|verify-ca` as aliases for `verify-full`,
@@ -4103,8 +4214,7 @@ function pinnedTlsDsn(dsn) {
 		return dsn;
 	}
 	if (isLoopbackHost(url.hostname)) return dsn;
-	const mode = (url.searchParams.get("sslmode") ?? "").toLowerCase();
-	if (!WEAK_SSLMODES.includes(mode)) return dsn;
+	if (!WEAK_SSLMODES.includes(effectiveSslMode(url))) return dsn;
 	url.searchParams.set("sslmode", "verify-full");
 	return url.toString();
 }
@@ -4158,7 +4268,7 @@ function tlsOptionsFor(dsn) {
 		return;
 	}
 	if (isLoopbackHost(url.hostname)) return void 0;
-	const mode = (url.searchParams.get("sslmode") ?? "").toLowerCase();
+	const mode = effectiveSslMode(url);
 	if (mode === "disable" || mode === "no-verify") return void 0;
 	return { rejectUnauthorized: true };
 }
@@ -4321,7 +4431,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-wfQycImj.mjs
+//#region ../content/dist/commands-Cysnkk_R.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4357,6 +4467,8 @@ const HARD_MAX_CHARS = 4e3;
 * The Markdown BODY below the frontmatter is the authored agent-surface
 * instructions — byte-preserved, stripped only at the edges.
 */
+/** Mirrors `schema.ts`'s ceiling, so a bad `dim:` is refused when instance.md is
+*  PARSED rather than when the DDL is rendered. The why lives there. */
 const EMBED_DIM_MAX$1 = 2e3;
 const SUPPORTED_FORMATS$1 = [1];
 var InstanceParseError = class extends Error {
@@ -4450,7 +4562,7 @@ const groupSchemas = {
 	embedding: z.object({
 		provider: z.string().min(1).default("gemini"),
 		model: z.string().min(1).default(EMBED_MODEL),
-		dim: z.coerce.number().int().min(1).max(EMBED_DIM_MAX$1).default(EMBED_DIM)
+		dim: z.coerce.number().int().min(1).max(EMBED_DIM_MAX$1, { error: `at most ${EMBED_DIM_MAX$1}: this schema declares VECTOR columns and indexes one directly, and pgvector's HNSW takes a vector to ${EMBED_DIM_MAX$1}` }).default(EMBED_DIM)
 	}),
 	retrieval: z.object({
 		/**
@@ -4874,7 +4986,29 @@ async function runIngest(pool, tenantId, op) {
 * fresh DDL is rendered from the instance that will fill it, never
 * hand-edited.
 */
-/** pgvector vector + HNSW ceiling. */
+/**
+* The largest embedding dimension this schema will render.
+*
+* It is the ceiling for the shape we USE, not pgvector's ceiling: `schema.sql`
+* declares two `VECTOR(dim)` columns and indexes one of them directly, and
+* pgvector's HNSW and IVFFlat take a `vector` to 2000. They take a `halfvec` to
+* **4000**, reachable by indexing an expression — `hnsw ((embedding::halfvec(N))
+* halfvec_cosine_ops)` — which we do not do, so 2000 binds here.
+*
+* Said precisely because the old wording ("pgvector vector + HNSW ceiling")
+* read as pgvector's own limit and sent a reader off to change providers over a
+* wall that is not one (verified live against a real database, 2026-08-21:
+* a halfvec(3072) expression index plans an Index Scan).
+*
+* Raising it is a decision, not a constant: every query site would have to use
+* the same cast as the index or fall silently back to a sequential scan, and
+* the halfvec arm's float16 rounding lands on the score the abstention gate
+* reads. Recorded in issue #49, along with the evidence for staying at 1536 —
+* Google's published MTEB table runs 128..2048 and is FLAT at the top of that
+* range (1536 scores 68.17, 2048 scores 68.16), so there is no gradient to
+* climb toward the ceiling. It carries no 3072 row, so the cost of the
+* truncation itself is unpublished; do not infer one.
+*/
 const EMBED_DIM_MAX = 2e3;
 /** The schema version schema.sql declares — parsed from the DDL so code and
 * the applied database share ONE source (a drift test pins the coupling). */
@@ -4921,7 +5055,7 @@ function verifyTemplate(text, dim) {
 }
 /** The pure core: render the given template text at the given dimension. */
 function renderSchemaText(text, dim, textSearchConfig = SHIPPED_TS_CONFIG) {
-	if (!Number.isInteger(dim) || dim < 1 || dim > 2e3) throw new Error(`dim must be an integer in 1..${EMBED_DIM_MAX} (pgvector vector + HNSW ceiling), got ${JSON.stringify(dim)}`);
+	if (!Number.isInteger(dim) || dim < 1 || dim > 2e3) throw new Error(`dim must be an integer in 1..${EMBED_DIM_MAX} — this schema indexes a vector column directly, and pgvector's HNSW takes a vector to 2000 — got ${JSON.stringify(dim)}`);
 	verifyTemplate(text, EMBED_DIM);
 	const withTs = renderTsConfig(text, textSearchConfig);
 	if (dim === 1536) return withTs;
@@ -8138,6 +8272,39 @@ async function sameCommit(c, tenantId, generation, sourceCommit) {
 	const stored = r.rows[0]?.source_commit ?? null;
 	return String(stored ?? "") === String(sourceCommit ?? "");
 }
+/**
+* May this generation be ACTIVATED? Returns the refusal, or null.
+*
+* Extracted so there is exactly ONE answer to that question. It used to live
+* inside `buildGeneration`'s flip branch, which made it unreachable the moment
+* a caller flipped separately — and `ksor ingest --flip` does, deliberately: the
+* governance gate has to run against the new generation BEFORE it becomes the
+* active one. That change silently retired this guard on the CLI path, so a
+* record that lost 80% of its documents published without a word, while the
+* library test that covers the guard stayed green because it drives
+* `buildGeneration` directly (found live 2026-08-21, auditing 0.0.10).
+*
+* A pre-flip check that only one of two flip paths performs is not a guard.
+*/
+async function flipRefusal(client, options) {
+	const { log } = options;
+	const delta = await flipDelta(client, {
+		tenantId: options.tenantId,
+		corpusId: options.corpusId,
+		newGeneration: options.newGeneration
+	});
+	const added = addedSlugs(delta);
+	const removed = removedSlugs(delta);
+	log(`pre-flip delta vs gen ${delta.priorGeneration}: ${delta.priorSlugs.size} -> ${delta.newSlugs.size} nodes (+${added.length} / -${removed.length})`);
+	if (removed.length > 0) log(`  removed: ${JSON.stringify(removed.slice(0, 20))}`);
+	if (added.length > 0) log(`  added:   ${JSON.stringify(added.slice(0, 20))}`);
+	const configuredShrink = envFloat("KSOR_MAX_SHRINK", .15, 0);
+	const maxShrink = configuredShrink <= 1 ? configuredShrink : .15;
+	if (configuredShrink > 1) log(`KSOR_MAX_SHRINK=${configuredShrink} is not a fraction in [0,1]; using ${maxShrink} (did you mean ${configuredShrink / 100}?)`);
+	const allowed = options.force || process.env["KSOR_ALLOW_SHRINK"] === "1";
+	if (!shrinkUnsafe(delta.priorSlugs.size, delta.newSlugs.size, maxShrink) || allowed) return null;
+	return `REFUSING FLIP: corpus shrank ${pct(shrinkFraction(delta.priorSlugs.size, delta.newSlugs.size))} vs gen ${delta.priorGeneration} (> KSOR_MAX_SHRINK=${pct(maxShrink)}); ${removed.length} node(s) vanished. Generation ${options.newGeneration} is READY but NOT served — the old generation keeps serving. If the drop is intended, re-run with KSOR_ALLOW_SHRINK=1; otherwise fix the corpus and re-ingest.`;
+}
 /** Thrown inside the build transaction to roll it back when nothing changed. */
 var UnchangedCorpus = class extends Error {
 	activeGeneration;
@@ -8262,26 +8429,19 @@ async function buildGeneration(pool, instance, options) {
 			flipped: false,
 			refusal: null
 		};
-		const delta = await flipDelta(c, {
+		const refusal = await flipRefusal(c, {
 			tenantId: tenant,
 			corpusId: instance.corpusId,
-			newGeneration: generation
+			newGeneration: generation,
+			force: options.force === true,
+			log
 		});
-		const added = addedSlugs(delta);
-		const removed = removedSlugs(delta);
-		log(`pre-flip delta vs gen ${delta.priorGeneration}: ${delta.priorSlugs.size} -> ${delta.newSlugs.size} nodes (+${added.length} / -${removed.length})`);
-		if (removed.length > 0) log(`  removed: ${JSON.stringify(removed.slice(0, 20))}`);
-		if (added.length > 0) log(`  added:   ${JSON.stringify(added.slice(0, 20))}`);
-		const configuredShrink = envFloat("KSOR_MAX_SHRINK", .15, 0);
-		const maxShrink = configuredShrink <= 1 ? configuredShrink : .15;
-		if (configuredShrink > 1) log(`KSOR_MAX_SHRINK=${configuredShrink} is not a fraction in [0,1]; using ${maxShrink} (did you mean ${configuredShrink / 100}?)`);
-		const allowed = options.force === true || process.env["KSOR_ALLOW_SHRINK"] === "1";
-		if (shrinkUnsafe(delta.priorSlugs.size, delta.newSlugs.size, maxShrink) && !allowed) return {
+		if (refusal !== null) return {
 			ready,
 			centroids,
 			health,
 			flipped: false,
-			refusal: `REFUSING FLIP: corpus shrank ${pct(shrinkFraction(delta.priorSlugs.size, delta.newSlugs.size))} vs gen ${delta.priorGeneration} (> KSOR_MAX_SHRINK=${pct(maxShrink)}); ${removed.length} node(s) vanished. Generation ${generation} is READY but NOT served — the old generation keeps serving. If the drop is intended, re-run with KSOR_ALLOW_SHRINK=1; otherwise fix the corpus and re-ingest.`
+			refusal
 		};
 		await flip(c, {
 			tenantId: tenant,
@@ -8652,11 +8812,23 @@ async function ingestCommand(args) {
 	const governance = await withPool(dsn, (pool) => assertGovernanceServable(pool, instance, report.generation).then(() => null, (error) => error instanceof Error ? error.message : String(error)));
 	if (governance !== null) return fail$1(REFUSED, `generation ${report.generation} was built and NOT activated — no surface could serve it\n  ${governance.split("\n").join("\n  ")}\n  note: generation ${report.generation} is left behind, un-activated; \`ksor gc\` reaps it once the grace window passes. The previously active generation still serves.`);
 	if (values.flip === true && !report.unchanged) {
-		await withPool(dsn, (pool) => runIngest(pool, instance.tenantId, (client) => flip(client, {
-			tenantId: instance.tenantId,
-			corpusId: instance.corpusId,
-			toGeneration: report.generation
-		})));
+		const refusal = await withPool(dsn, (pool) => runIngest(pool, instance.tenantId, async (client) => {
+			const stop = await flipRefusal(client, {
+				tenantId: instance.tenantId,
+				corpusId: instance.corpusId,
+				newGeneration: report.generation,
+				force: false,
+				log: (line) => process.stdout.write(line + "\n")
+			});
+			if (stop !== null) return stop;
+			await flip(client, {
+				tenantId: instance.tenantId,
+				corpusId: instance.corpusId,
+				toGeneration: report.generation
+			});
+			return null;
+		}));
+		if (refusal !== null) return fail$1(REFUSED, refusal);
 		process.stdout.write(`FLIPPED active generation -> ${report.generation}\n`);
 	}
 	if (values.flip !== true) process.stdout.write("ready; flip withheld (pass --flip to activate)\n");

package/docs/index.md

@@ -45,8 +45,9 @@ instead of their training memory. The corpus grows with each implemented verb.
 Read the scaffold's own `AGENTS.md` first — it is the working contract.
 Knowledge lives in `knowledge/` and never inside the site; frontmatter uses
 a closed key set (`title` + `status` required); `pnpm check` explains any
-violation and how to fix it. Sidebar order is the governed `order:`
-frontmatter key — never `meta.json` or `sidebar_position`. If the
+violation and how to fix it. Reading order is the governed `order:`
+frontmatter key — never `meta.json` or `sidebar_position` — and it drives
+every surface: the sidebar, `llms.txt`, and the MCP `outline` tool. If the
 instance declares an `audiences:` model, documents may carry a
 `visibility:` key and per-audience builds (`KSOR_AUDIENCE=<tier> pnpm
 build`) stage only what that tier may see — publication, not authorship:

package/package.json

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

@@ -65,8 +65,13 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`; write it out
    only to pin the space explicitly or to change it — and note that model and
    dim are the PERSISTED identity of the embedding space, so changing either
-   later means re-embedding the whole corpus. Keep `dim` at or below 2000: the
-   pgvector HNSW index refuses more, and `gemini-embedding-001` can emit 3072.
+   later means re-embedding the whole corpus. Keep `dim` at or below 2000 — the
+   schema indexes a `vector` column directly and pgvector's HNSW takes a
+   `vector` to 2000. `gemini-embedding-001` emits 3072 by default, so ksor asks
+   it for 1536. Google's published MTEB table runs 128–2048 and is flat at the
+   top of it — 1536 scores 68.17 against 2048's 68.16 — so there is no gradient
+   to climb toward the ceiling; going the other way, 768 costs 0.18 if you want
+   the storage back.
 
    Leave `retrieval:` out for now — the gate is off and the server says so.
    Turning it on is step 4, AFTER the record is serving.
@@ -227,7 +232,7 @@ bind, set `KSOR_ALLOWED_HOSTS` / `KSOR_ALLOWED_ORIGINS`; on more than one
 replica, set a shared `KSOR_SNAPSHOT_KEYS` (unset ⇒ a per-process key, so a
 search token minted by one replica fails on another).
 
-Two things worth being deliberate about:
+Three things worth being deliberate about:
 
 - **`KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` serves your whole record to anyone
   who can reach the port.** It exists for deployments fronted by your own
@@ -235,11 +240,70 @@ Two things worth being deliberate about:
 - **Set `KSOR_SSO_ISSUER` when your SSO stamps a stable `iss`.** Audience is
   always enforced against `KSOR_JWT_ALLOWED_AUDIENCES`; naming the issuer adds
   one more check for the cost of one variable.
-- **Set `KSOR_JWKS_URL` unless your SSO is Better Auth.** The signing keys are
-  fetched from `<KSOR_SSO_URL>/api/auth/jwks` by default, which is Better
-  Auth's layout. Auth0, Okta, Entra, Keycloak and Cognito publish theirs
-  elsewhere, and a wrong JWKS URL fails as a transient fetch error — the door
-  boots clean and every request 503s with nothing naming the cause.
+- **The signing keys are DISCOVERED; you rarely set `KSOR_JWKS_URL`.** The door
+  reads your SSO's own metadata document — RFC 8414
+  (`/.well-known/oauth-authorization-server`), then OpenID Discovery
+  (`/.well-known/openid-configuration`) — so Auth0, Okta, Entra, Keycloak,
+  Cognito, Google and Better Auth all work unmodified. The boot report's `keys`
+  line names which document answered and where the keys came from; set
+  `KSOR_JWKS_URL` only to override that, or when your SSO publishes no metadata
+  at all.
+
+### What a CLIENT has to do
+
+Once the SSO door is configured (the three variables above), the server is an
+OAuth **Resource Server**, which means a client is not told the authorization
+server — it discovers it. Nothing here needs configuring beyond those variables;
+this is what your agents will experience, and what to check when one cannot
+connect. With `KSOR_AUTH_DISABLED=1` — the local default `.env.example` ships —
+none of it applies: there is no challenge and the metadata document answers 404,
+because there is no authorization server to point at.
+
+1. The client calls `POST /mcp` with no token and gets **401** carrying
+
+   ```
+   WWW-Authenticate: Bearer resource_metadata="https://<your-host>/.well-known/oauth-protected-resource/mcp"
+   ```
+
+   That header is the whole handshake: it names a DOCUMENT, not the resource.
+
+2. The client fetches that document and finds the record's resource identifier
+   and its authorization server:
+
+   ```json
+   {
+     "resource": "https://<your-host>/mcp",
+     "authorization_servers": ["https://your-sso.example.com"]
+   }
+   ```
+
+   Those two values are `KSOR_MCP_RESOURCE_URL` and `KSOR_SSO_URL`.
+
+3. The client gets a token from that authorization server, asking for THIS
+   record as the resource (RFC 8707: `resource=https://<your-host>/mcp`), and
+   sends it as `Authorization: Bearer <token>`.
+
+Every 401 carries that same header, not just the first one — including the one
+your clients will hit most often, a token that expired mid-conversation. It
+arrives as `Bearer error="invalid_token", resource_metadata="…"`, so a client
+knows to refresh rather than to retry the dead token. A **503** is deliberately
+_not_ challenged: an unreachable key set is our outage, not your token's fault,
+and telling a client to re-authenticate over it would send a perfectly good user
+back through a login.
+
+The one thing that goes wrong here goes wrong quietly: a token minted for a
+different audience is a perfectly valid token, and this door rejects it. The
+`aud` claim must match one of `KSOR_JWT_ALLOWED_AUDIENCES` — normally the same
+value as `KSOR_MCP_RESOURCE_URL` — because a bearer accepted for any audience is
+a bearer stolen from one service and replayed against this one. If a client
+authenticates fine and still gets 401, compare its token's `aud` against that
+list before looking anywhere else.
+
+Tokens must be signed **RS256**; nothing else is accepted, and opaque tokens are
+not supported (there is no introspection call). When your SSO rotates its
+signing keys, an unknown key id answers **503**, not 401 — the token may well be
+good and the door's key set merely stale, so a client should retry rather than
+send the user back through a login.
 
 ## Withdrawing a document — `ksor takedown`
 
@@ -258,8 +322,12 @@ pnpm exec ksor takedown --instance instance.md --revoke <stable-id>
 The stable id is what a search result reports as `provenance.stable_id` — for
 most documents that is `knowledge/<path-without-.md>`. `--subtree` withdraws a
 section and everything beneath it, including documents added later.
-`--actor NAME` names who performed the act in the ledger; it defaults to the
-operating user.
+`--actor NAME` names who performed the act in the ledger, and a denial or a
+revocation is REFUSED without it. There is no default: a name taken from the
+environment reads like a person and is whatever the shell happened to be
+(`runner` under CI, `root` in a container), which is worse than no name at all
+in the one row that exists to record who did this. Read-only modes
+(`--list`, `--ledger`, `--export`) need nothing.
 
 **The MCP door stops serving it immediately. The SITE stops at its next
 build** — the site reads a file, not the database, and `pnpm build` refreshes
@@ -329,8 +397,10 @@ Details in README → Deploying.
   takes the position that page declares.
 - Sidebar position is the governed `order:` key: documents that declare it come
   first, ascending; the rest follow in name order.
-- One order drives the sidebar, `llms.txt`, and the home page's first-document
-  link — set it once and every surface agrees.
+- One order drives every surface — the sidebar, `llms.txt`, the home page's
+  first-document link, and the MCP `outline` tool an agent reads to decide what
+  to read first. Set it once and they agree. The door picks up a reorder at the
+  next `pnpm refresh`, which costs no embedding: only the ordering changed.
 - Never `meta.json` or `sidebar_position`: the checker refuses framework files
   in the record, which has to read the same without the site.
 

package/templates/scaffold/instance.md

@@ -42,3 +42,10 @@ act on it.
 Ask your coding agent to run the **intake interview** (it knows how — see
 `.agents/skills/intake-interview/`), answer its questions, and let it write
 this document with you.
+
+Until you do, `ksor serve` says so — at boot, and to every agent that connects:
+the MCP surface replaces this template with a plain statement that the record's
+scope is unstated, rather than passing authoring guidance to a runtime agent as
+if it were instructions. Nothing breaks, and the record still answers with
+citations; it just cannot tell an agent what it is authoritative FOR, which is
+the one thing that makes an answer worth trusting.

package/templates/scaffold/system/site/app/.well-known/mcp/server.json/route.ts

@@ -1,4 +1,4 @@
-import { appName, mcpEndpoint, mcpNamespace, recordVersion } from "@/lib/shared";
+import { appName, mcpEndpoint, mcpNamespace, recordDescription, recordVersion } from "@/lib/shared";
 
 /**
  * `/.well-known/mcp/server.json` — how an agent DISCOVERS this record's MCP
@@ -33,7 +33,10 @@ export function GET(): Response {
     {
       $schema: SCHEMA,
       name: `${mcpNamespace()}/${appName}`,
-      description: `The ${appName} Knowledge System of Record: governed markdown served with citations and honest abstention.`,
+      // The record's OWN account of itself — see recordDescription. A
+      // description identical in every ksor record cannot help an agent choose
+      // one, and a record with no scope yet says so instead of guessing.
+      description: recordDescription(),
       version: recordVersion(),
       // Absent until the owner declares where the server runs — an invented
       // URL is worse than none, because an agent would try it and conclude the

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

@@ -59,6 +59,55 @@ function readInstanceTitle(): string {
 
 export const appTitle: string = readInstanceTitle();
 
+/**
+ * How this record describes ITSELF, in one line — what an agent reads in a
+ * registry listing to decide whether this record can answer its question.
+ *
+ * It comes from the record's own prose (instance.md's first real paragraph,
+ * which the intake interview writes) because the alternative is what shipped
+ * before: one hard-coded sentence, byte-identical in every ksor record ever
+ * scaffolded, telling a discovering agent nothing that distinguishes this record
+ * from any other. "Discoverability determines whether agents find you at all" is
+ * a product principle, and a description that cannot discriminate is not
+ * discoverability (found live 2026-08-21).
+ *
+ * An UNDESCRIBED record says so rather than borrowing a confident sentence it
+ * has not earned — the same answer the MCP door already gives an agent that
+ * connects, so the two surfaces do not disagree about whether this record knows
+ * what it is. The marker is the template's own unfilled placeholder, matched on
+ * the WHOLE body: a scaffold's first paragraphs are authoring guidance, and
+ * reading one of those as the record's scope is worse than admitting there is
+ * none.
+ */
+const TEMPLATE_MARKER = "_fill this in; it is";
+
+function readInstanceScope(): string | null {
+  const text = readFileSync(findInstance(process.cwd()), "utf8");
+  const body = text.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+  if (body.includes(TEMPLATE_MARKER)) return null;
+  const afterHeading = body.replace(/^[\s\S]*?^#[ \t]+.+$/m, "");
+  for (const para of afterHeading.split(/\n[ \t]*\n/)) {
+    const one = para.trim().replace(/\s+/g, " ");
+    if (one === "" || one.startsWith("#") || one.startsWith("-") || one.startsWith(">")) continue;
+    const sentence = /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
+    return sentence.length > 300 ? `${sentence.slice(0, 297)}...` : sentence;
+  }
+  return null;
+}
+
+/** null until the owner has written one — never a guess. */
+export const appScope: string | null = readInstanceScope();
+
+/**
+ * The one-line description every discovery surface publishes. Built here so the
+ * registry document and anything else that needs one cannot drift apart.
+ */
+export function recordDescription(): string {
+  return appScope === null
+    ? `${appTitle} — its owner has not yet described what this record covers.`
+    : `${appTitle} — ${appScope}`;
+}
+
 /**
  * Where this record's MCP surface is published, if the owner has said.
  *

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

@@ -343,13 +343,30 @@ function planStage(recordDir: string, denied: DenylistManifest): StagePlan {
   return { files: [...documents, ...assets], documents: documents.length, total };
 }
 
+/**
+ * Remove the stage, asking for the retries this exact failure needs.
+ *
+ * `force: true` suppresses ENOENT; it does NOT retry anything. Node retries
+ * EBUSY / EMFILE / ENFILE / ENOTEMPTY / EPERM only when `maxRetries` is set,
+ * and it defaults to zero. The build evaluates `source.config.ts` more than
+ * once when the bundler wants it in more than one place, so two runs can
+ * overlap: one removing the stage while the other is still copying into it.
+ * That surfaced as `ENOTEMPTY` out of `rmSync` and failed the whole site build
+ * (CI, 2026-08-21) — a race that is safe to lose, because the stage is a
+ * deterministic function of the record and the denylist, so redoing it produces
+ * the same bytes.
+ */
+function removeStage(stageDir: string): void {
+  rmSync(stageDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+}
+
 /** Fill a clean stage with exactly the set this build may publish. */
 function fillStage(recordDir: string, stageDir: string, denied: DenylistManifest): void {
   // The old stage goes first, before any refusal can throw: a refused build
   // that leaves the previous, more permissive stage on disk hands the next
   // careless build a filtered copy nothing governs (review finding,
   // 2026-08-19).
-  rmSync(stageDir, { recursive: true, force: true });
+  removeStage(stageDir);
   const plan = planStage(recordDir, denied);
   // An empty record is its own problem, reported by the page that renders it;
   // an empty AUDIENCE is a misconfiguration that would otherwise surface as
@@ -468,7 +485,7 @@ export function knowledgeSourceDir(): string {
     // A stage left behind by an earlier model would be a filtered copy of the
     // record nothing governs any more — removed before the refusal below can
     // throw, so a refused build never leaves one behind either.
-    rmSync(stageDir, { recursive: true, force: true });
+    removeStage(stageDir);
     refuseVisibilityWithoutAudiences(recordDir);
     return RECORD_DIR;
   }