@panaversity/ksor 0.0.10 → 0.0.11

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @panaversity/ksor
 
+## 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-3DN4fOiE.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 };
 }
@@ -2058,7 +2071,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 +2931,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 +2997,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 +3610,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
@@ -3736,10 +3788,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);
@@ -3925,7 +3978,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 +4135,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 +4172,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 +4226,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 +4389,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-wfQycImj.mjs
+//#region ../content/dist/commands-ulU-h9ei.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -8138,6 +8206,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 +8363,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 +8746,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.11",
   "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

@@ -235,11 +235,14 @@ 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.
 
 ## Withdrawing a document — `ksor takedown`
 
@@ -258,8 +261,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 +336,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;
   }