@panaversity/ksor 0.0.28 → 0.0.30

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @panaversity/ksor
 
+## 0.0.30
+
+### Patch Changes
+
+- fbf149b: Quizzes, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry `<doc>.quiz.yaml` beside its summary
+  and its flashcard deck. It renders at the end of the document's page, under the
+  deck: choose an option, see immediately whether you were right, and read the
+  explanation before moving on. There is no pass mark — a quiz here checks
+  understanding of the record, it does not certify anybody — and answers stay in
+  the reader's own browser.
+
+  A quiz is **part of its document, not a document**: no URL, no sidebar row, no
+  `llms.txt` line, no markdown twin, no search entry, and no stable id. That last
+  one settles a question worth being explicit about: because `ksor ingest` creates
+  no node for a quiz, **the answer key cannot reach the MCP surface at all**.
+  There is nothing for an agent to search and nothing for it to read — not by a
+  filter that could be forgotten, but because the row does not exist. Governance
+  inherits from the parent exactly as the summary and the deck already do.
+
+  **`pnpm check` and `pnpm build` refuse a quiz a reader could pass without
+  reading it**, naming the questions to fix:
+
+  - `ksor-quiz-answer-bias` — more than 60% of answers at one option position
+  - `ksor-quiz-length-bias` — picking the longest or shortest option usually wins
+  - `ksor-quiz-answer-run` — four or more questions in a row share an answer
+  - `ksor-quiz-contradiction` — an explanation calls the marked answer wrong
+  - `ksor-quiz-duplicate-stem` — two questions open with the same 60 characters
+
+  These are carried from the predecessor, where the same mistakes shipped and were
+  found by readers rather than by the project — one quiz put every correct answer
+  in the same position across 451 questions. There they lived in a script that was
+  run once; here they are part of loading the file, so a quiz that fails them
+  cannot be published. The ratio rules do not apply below five questions, where
+  enforcing a spread would mean choosing an author's answers for them.
+
+  `ksor init` ships a quiz on the seed document, so a first `pnpm dev` shows the
+  shape. Its own first draft was refused for putting four of five answers at
+  option B — the check catching exactly what it was carried for.
+
+## 0.0.29
+
+### Patch Changes
+
+- f7e15cd: **Breaking:** `KSOR_AUTH_DISABLED` and `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED` are
+  replaced by one variable, `KSOR_AUTH`, whose value is the decision:
+
+  ```sh
+  KSOR_AUTH=disabled-local    # no auth, loopback only — a public bind REFUSES
+  KSOR_AUTH=disabled-public   # no auth, served to anyone who can reach the port
+  ```
+
+  Two booleans that had to agree to express one decision produced a state neither
+  name could tell you, and a fourth combination that meant nothing. `AUTH_DISABLED`
+  sounds like it already means "auth is off", so being told you also need
+  `ALLOW_PUBLIC_UNAUTHENTICATED` read as the tool asking you to say the same thing
+  twice. The guarantee is unchanged and unweakened — a copied `.env` carrying
+  `disabled-local` still refuses on a container, which is the leak that pair
+  existed to catch. Setting either retired variable now refuses at boot and names
+  its replacement.
+
+  **The boot report no longer stays silent about ephemeral snapshot keys.** Unset
+  `KSOR_SNAPSHOT_KEYS` mints a per-process signing key — honest for one process,
+  and wrong for the container hosts we ship a Dockerfile for. A generation pin
+  issued by one instance is then unverifiable by the next, so `read` silently drops
+  to the active generation and reports `refreshed (invalid)`. It fails soft, so
+  nothing errors and nothing logs; the only symptom is an agent reading a
+  generation it did not search. Found on a real deployment by noticing one read in
+  three come back unpinned. On a public bind the door now says so:
+
+  ```
+  snapshot EPHEMERAL key — generation pins will NOT survive a restart or a
+           second instance; set KSOR_SNAPSHOT_KEYS to a value shared by every replica
+  ```
+
+  Not a refusal — a loopback dev run and a genuine single-instance deployment are
+  both legitimate — but no longer silent where the assumption stops holding.
+
+  `docs/deploying.md` splits its configuration table into three tiers: required to
+  boot, set on any container host, and set once auth is on. Listing six variables
+  as one table read as "set all of these or you are doing it wrong", and only the
+  first tier was ever true.
+
 ## 0.0.28
 
 ### Patch Changes

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
-import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-CbFkHZiU-HvlJRjRB.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -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-DiX1MNMX.mjs
+//#region ../content-gateway/dist/main-CS5a_8OW.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -280,13 +280,18 @@ function configFromEnv(env) {
 */
 function buildAuth(env = process.env, deps = {}) {
 	const warn = deps.warn ?? defaultWarn;
-	const disabled = env.KSOR_AUTH_DISABLED === "1";
+	const declared = (env.KSOR_AUTH ?? "").trim();
 	const config = configFromEnv(env);
-	if (disabled) {
-		if (config !== null) warn("auth DISABLED via KSOR_AUTH_DISABLED despite SSO config — UNAUTHENTICATED (dev)");
-		return { mode: "disabled" };
+	if (declared === "" && (env.KSOR_AUTH_DISABLED !== void 0 || env.KSOR_ALLOW_PUBLIC_UNAUTHENTICATED !== void 0)) throw new AuthConfigError("KSOR_AUTH_DISABLED and KSOR_ALLOW_PUBLIC_UNAUTHENTICATED have been replaced by one variable, KSOR_AUTH. Set KSOR_AUTH=disabled-local for a loopback dev run, or KSOR_AUTH=disabled-public to serve the whole record to anyone who can reach the port.");
+	if (declared === "disabled-local" || declared === "disabled-public") {
+		if (config !== null) warn(`auth DISABLED via KSOR_AUTH=${declared} despite SSO config — UNAUTHENTICATED`);
+		return {
+			mode: "disabled",
+			publicAllowed: declared === "disabled-public"
+		};
 	}
-	if (config === null) throw new AuthConfigError("auth is not configured (KSOR_SSO_URL / KSOR_MCP_RESOURCE_URL unset) and KSOR_AUTH_DISABLED is not '1' — refusing to boot unauthenticated. Set both SSO env vars, or set KSOR_AUTH_DISABLED=1 for a deliberate dev/unauthenticated run.");
+	if (declared !== "") throw new AuthConfigError(`KSOR_AUTH=${JSON.stringify(declared)} is not a posture. Use "disabled-local" (loopback dev run) or "disabled-public" (serves the whole record to anyone who can reach the port), or unset it and configure the SSO door.`);
+	if (config === null) throw new AuthConfigError("auth is not configured (KSOR_SSO_URL / KSOR_MCP_RESOURCE_URL unset) and KSOR_AUTH is unset — refusing to boot unauthenticated. Set both SSO env vars, or set KSOR_AUTH=disabled-local for a deliberate dev/unauthenticated run.");
 	if (config.allowedAudiences.length === 0) throw new AuthConfigError("auth is ON but KSOR_JWT_ALLOWED_AUDIENCES is empty — set it to this server's MCP URL (fail-closed: an unset audience allowlist would accept any SSO-signed token).");
 	let resolution = null;
 	const jwks = () => {
@@ -540,10 +545,34 @@ function withoutSdkResponseModeWarning(body) {
 */
 function authPosture(mode, host, publicUnauthenticated) {
 	if (mode !== "disabled") return "bearer tokens, verified against the record's authorization server";
-	if (publicUnauthenticated) return `UNAUTHENTICATED and bound to ${host} — KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1 is set, so the whole record is served to anyone who can reach this port`;
+	if (publicUnauthenticated) return `UNAUTHENTICATED and bound to ${host} — KSOR_AUTH=disabled-public is set, so the whole record is served to anyone who can reach this port`;
 	return `DISABLED — ${host} only, and a public bind will refuse to boot`;
 }
 /**
+* Whether a generation pin will survive this deployment.
+*
+* Unset `KSOR_SNAPSHOT_KEYS` mints an EPHEMERAL per-process key. That is honest
+* for one process — the code that chose it said so — but a container is not one
+* process. On a scale-to-zero host every cold start mints a new key, so a
+* snapshot token issued by one instance is unverifiable by the next and `read`
+* silently drops to the ACTIVE generation, reporting `refreshed (invalid)`.
+*
+* Silently is the problem. It fails SOFT by design, so nothing errors and
+* nothing logs; the only symptom is an agent reading a generation it did not
+* search, which surfaces as roughly one read in three coming back unpinned.
+* Found exactly that way on a real deployment, which is why this line exists —
+* every other posture on this report announced itself and this one did not.
+*
+* Not a refusal: a loopback dev run and a genuine single-instance deployment
+* are both legitimate, and neither is harmed. So the line appears only where
+* the assumption actually stops holding — a public bind.
+*/
+function snapshotPosture(activeKeyId, loopback) {
+	if (activeKeyId !== "ephemeral") return null;
+	if (loopback) return null;
+	return "EPHEMERAL key — generation pins will NOT survive a restart or a second instance; set KSOR_SNAPSHOT_KEYS to a value shared by every replica";
+}
+/**
 * What the record will refuse. `null` means no floor is declared and the gate
 * is off — which is honest, and is a correct level-0 state, but an agent
 * pointed at this door will get a confident cited answer to a question the
@@ -968,7 +997,7 @@ async function runHttp(composition) {
 	const resourceMetadataUrl = auth.mode === "public" ? new URL("/.well-known/oauth-protected-resource/mcp", auth.config.resourceUrl).toString() : "";
 	const bind = resolveBind(process.env);
 	const loopback = bind.host === "127.0.0.1" || bind.host === "localhost" || bind.host === "::1";
-	if (auth.mode === "disabled" && !loopback && process.env["KSOR_ALLOW_PUBLIC_UNAUTHENTICATED"] !== "1") throw new AuthConfigError(`refusing an UNAUTHENTICATED PUBLIC bind (${bind.host}) — KSOR_AUTH_DISABLED is the loopback-dev flag, not a licence to serve the corpus to the internet with no auth. Configure the SSO door (KSOR_SSO_URL + KSOR_MCP_RESOURCE_URL + KSOR_JWT_ALLOWED_AUDIENCES), bind loopback, or set KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1 to accept the risk deliberately.`);
+	if (auth.mode === "disabled" && !loopback && !auth.publicAllowed) throw new AuthConfigError(`refusing an UNAUTHENTICATED PUBLIC bind (${bind.host}) — KSOR_AUTH=disabled-local is the loopback dev posture, not a licence to serve the corpus to the internet with no auth. Configure the SSO door (KSOR_SSO_URL + KSOR_MCP_RESOURCE_URL + KSOR_JWT_ALLOWED_AUDIENCES), bind loopback, or set KSOR_AUTH=disabled-public to accept the risk deliberately.`);
 	const security = resolveSecurity(bind);
 	const { ctx, instance, pool, spaceSkipReason, version, verifyBoot } = composition;
 	const maxBodyBytes = envInt$1(process.env, "KSOR_MAX_BODY_BYTES", 1e6, { minimum: 1024 });
@@ -1142,8 +1171,10 @@ 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, process.env["KSOR_ALLOW_PUBLIC_UNAUTHENTICATED"] === "1" && !loopback)));
+	console.error(bootLine("auth", authPosture(auth.mode, bind.host, auth.mode === "disabled" && auth.publicAllowed && !loopback)));
 	for (const line of keyLines) console.error(line);
+	const snapshot = snapshotPosture(ctx.ring.active, loopback);
+	if (snapshot !== null) console.error(bootLine("snapshot", snapshot));
 	console.error(bootLine("abstain", abstainPosture(instance.abstain.vectorFloor)));
 	console.error(bootLine("serving", `http://${bind.host}:${bind.port}/mcp`));
 	let draining = false;
@@ -1181,7 +1212,7 @@ async function runHttp(composition) {
 * The bind decides the posture: unset PORT/host → loopback (127.0.0.1),
 * the dev door, DNS-rebind-protected and safe with auth off; a public bind
 * is a deliberate act that fails closed unless auth is configured or
-* KSOR_AUTH_DISABLED=1 is set explicitly.
+* KSOR_AUTH=disabled-local is set explicitly.
 *
 * Env contract (each `KSOR_*` name descends from an oracle `SOR_*` var):
 *   KSOR_INSTANCE                path to instance.md (default ./instance.md)
@@ -1190,7 +1221,7 @@ async function runHttp(composition) {
 *   KSOR_SNAPSHOT_KEYS           kid=secret[,...]; unset = ephemeral key
 *   KSOR_MCP_HOST / KSOR_MCP_PORT  bind (loopback unless PORT — deliberate)
 *   KSOR_SSO_URL + KSOR_MCP_RESOURCE_URL + KSOR_JWT_ALLOWED_AUDIENCES  public door
-*   KSOR_AUTH_DISABLED=1         the deliberate unauthenticated opt-out
+*   KSOR_AUTH=disabled-local         the deliberate unauthenticated opt-out
 *
 * Exit codes follow the ksor CLI contract: refusal 1, environment 3 —
 * always a remedied message, never a stack trace.
@@ -1552,7 +1583,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-DU1nqwZa.mjs
+//#region ../content/dist/commands-CLUS9CX8.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4177,6 +4208,10 @@ const ATTACHMENT_SUFFIXES = [
 	{
 		suffix: ".flashcards.yaml",
 		kind: "deck"
+	},
+	{
+		suffix: ".quiz.yaml",
+		kind: "quiz"
 	}
 ];
 /**

package/dist/{gateway-api-8lNruq9e-CuohjtoK.mjs → gateway-api-CbFkHZiU-HvlJRjRB.mjs}

@@ -5,7 +5,7 @@ import { z, z as z$1 } from "zod";
 import pg from "pg";
 import path from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region ../content-gateway/dist/gateway-api-8lNruq9e.mjs
+//#region ../content-gateway/dist/gateway-api-CbFkHZiU.mjs
 /**
 * The record's system prompt: instance.md's body, preserved beneath a framework
 * floor. Lifted out of server.ts so the public gateway surface can re-export

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-CbFkHZiU-HvlJRjRB.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/authorization.md

@@ -189,7 +189,7 @@ re-admitted the instant the key set catches up.
 
 ## Before a public bind
 
-- Auth configured as above, **or** `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` set
+- Auth configured as above, **or** `KSOR_AUTH=disabled-public` set
   deliberately — the door will not come up on a public address without one of
   them, and the second is a decision, not a default.
 - `KSOR_ALLOWED_HOSTS` set to the host you serve on.

package/docs/deploying.md

@@ -103,30 +103,81 @@ setting came out.
 
 ## Configuration
 
-The door takes everything from the environment. Set these on the deployment, not
-in a file:
-
-| variable                | why                                                                      |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `KSOR_DB_URL`           | the record's Postgres store                                              |
-| `GEMINI_API_KEY`        | embeds the incoming query, so retrieval works at all                     |
-| `KSOR_SNAPSHOT_KEYS`    | `kid=secret` — **required in practice**, see below                       |
-| `KSOR_ALLOWED_HOSTS`    | the host you serve on (DNS-rebind defence)                               |
-| `KSOR_MCP_RESOURCE_URL` | this record's canonical URL, e.g. `https://your-host/mcp`                |
-| auth, one of two        | `KSOR_SSO_URL` + audiences, **or** `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` |
-
-`KSOR_SNAPSHOT_KEYS` is listed as a production knob but behaves as a
-requirement on any host that scales to zero. Unset, the signing key is generated
-**per process** — so a citation minted before a scale-down stops validating
-after it, with a single instance and no replicas involved. Generate one:
+Three tiers, because listing them as one table reads as "set all of these or you
+are doing it wrong" — and only the first tier is true.
+
+### Required — the door will not boot without these
+
+| variable                                  | why                                                  |
+| ----------------------------------------- | ---------------------------------------------------- |
+| `KSOR_DB_URL`                             | the record's Postgres store                          |
+| `GEMINI_API_KEY`                          | embeds the incoming query, so retrieval works at all |
+| `KSOR_AUTH`, **or** a configured SSO door | see below                                            |
+
+`KSOR_AUTH` takes one of two values, and the value IS the decision:
+
+```sh
+KSOR_AUTH=disabled-local    # no auth, loopback only — a public bind REFUSES
+KSOR_AUTH=disabled-public   # no auth, and served to anyone who can reach the port
+```
+
+**A container sets `$PORT`, so the door binds `0.0.0.0` — a public bind.**
+`disabled-local` refuses there, deliberately: copying a dev `.env` into a hosting
+dashboard must not quietly open your record to the internet. `disabled-public` is
+correct for a genuinely public record or one behind your own gateway; it is not a
+way to make a deploy go green.
+
+The alternative is a real authorization server — `KSOR_SSO_URL`,
+`KSOR_MCP_RESOURCE_URL`, `KSOR_JWT_ALLOWED_AUDIENCES`, with worked recipes for two
+of them in [authorization.md](./authorization.md).
+
+### Set this on any container host
+
+| variable             | why                                      |
+| -------------------- | ---------------------------------------- |
+| `KSOR_SNAPSHOT_KEYS` | `kid=secret`, identical on every replica |
+
+Unset mints an **ephemeral per-process key**. A `search` hands back a snapshot
+token pinning the generation it answered from; `read` honours that pin so a
+conversation stays on one version of the record. With a per-process key, a token
+minted by one instance is unverifiable by the next — so `read` silently drops to
+the ACTIVE generation and reports `refreshed (invalid)`.
+
+It fails **soft**, so nothing errors and nothing logs. The only symptom is an
+agent reading a generation it did not search, seen as roughly one read in three
+coming back unpinned. Generate one with `openssl rand -hex 32`:
 
 ```sh
 KSOR_SNAPSHOT_KEYS="k1=$(openssl rand -hex 32)"
 ```
 
-The value is `kid=secret`, not `kid:secret`, and the first entry is the active
-one. Multiple entries let you rotate without invalidating outstanding
-citations.
+`k1` is a label, not a secret — it appears in the token as `key_id` so you can
+rotate later. The secret is used as literal text, never hex-decoded, and must be
+byte-identical across every instance of one deployment. Set it once and leave it
+alone: rotating invalidates every outstanding pin, and a compromised snapshot key
+cannot read a withdrawn document, cross an audience boundary, or authenticate
+anything.
+
+The boot report now says so out loud when it matters:
+
+```
+snapshot EPHEMERAL key — generation pins will NOT survive a restart or a
+         second instance; set KSOR_SNAPSHOT_KEYS to a value shared by every replica
+```
+
+### Set these once auth is ON
+
+| variable               | why                                        |
+| ---------------------- | ------------------------------------------ |
+| `KSOR_ALLOWED_HOSTS`   | Host allow-list — DNS-rebind defence       |
+| `KSOR_ALLOWED_ORIGINS` | browser Origin allow-list                  |
+| `KSOR_SSO_ISSUER`      | one more check per token, for one variable |
+
+Unset, Host validation is simply off on a public bind — permissive, not refusing,
+so it is never the reason a deploy fails. It earns its place when auth is on:
+rebinding is worth an attacker's effort only when it reaches something they could
+not reach directly. With `KSOR_AUTH=disabled-public` the record is already served
+to anyone who types the URL, so there is nothing for rebinding to steal.
 
 ### The site build needs the DSN too
 
@@ -154,7 +205,7 @@ ways past it:
 - **Configure the SSO door** — `KSOR_SSO_URL`, `KSOR_MCP_RESOURCE_URL`,
   `KSOR_JWT_ALLOWED_AUDIENCES`. Worked recipes for two different authorization
   servers: [authorization.md](./authorization.md).
-- **Set `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1`** — a deliberate decision that
+- **Set `KSOR_AUTH=disabled-public`** — a deliberate decision that
   serves your whole record to anyone who can reach the port. Correct for a
   genuinely public record, or behind your own gateway. Never as a way to get a
   deploy green.

package/package.json

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

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

@@ -41,7 +41,7 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml", ".quiz.yaml"];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +49,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

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

@@ -41,7 +41,7 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml", ".quiz.yaml"];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +49,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

package/templates/scaffold/AGENTS.md

@@ -96,7 +96,7 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    - `KSOR_DB_URL` — the Postgres store named by `instance.md`'s `dsn_env`. It
      needs the pgvector extension: `CREATE EXTENSION vector;`
    - `GEMINI_API_KEY` — the embedding provider key.
-   - `KSOR_AUTH_DISABLED=1` — **required for a local run.** `ksor serve`
+   - `KSOR_AUTH=disabled-local` — **required for a local run.** `ksor serve`
      refuses to boot unauthenticated without it, deliberately, so a server is
      never left open by accident. It binds loopback, where auth off is the
      intended dev shape. A PUBLIC deployment configures the SSO door instead —
@@ -228,11 +228,11 @@ abandoned ones.
 ### Serving safely (fail-closed posture)
 
 `pnpm serve` **refuses to boot unauthenticated** — there is no auth-off
-default. A local run says so deliberately with `KSOR_AUTH_DISABLED=1` and binds
+default. A local run says so deliberately with `KSOR_AUTH=disabled-local` and binds
 loopback, which is the intended dev shape. A **public**
 bind refuses to boot unless auth is configured (`KSOR_SSO_URL` +
 `KSOR_MCP_RESOURCE_URL` + `KSOR_JWT_ALLOWED_AUDIENCES`, making it an OAuth
-Resource Server) OR you deliberately set `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1`.
+Resource Server) OR you deliberately set `KSOR_AUTH=disabled-public`.
 Never let a dropped auth variable silently ship an open door. On a non-loopback
 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
@@ -240,7 +240,7 @@ search token minted by one replica fails on another).
 
 Three things worth being deliberate about:
 
-- **`KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` serves your whole record to anyone
+- **`KSOR_AUTH=disabled-public` serves your whole record to anyone
   who can reach the port.** It exists for deployments fronted by your own
   gateway or network policy. If nothing else is in front, do not set it.
 - **Set `KSOR_SSO_ISSUER` when your SSO stamps a stable `iss`.** Audience is
@@ -261,7 +261,7 @@ 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 —
+connect. With `KSOR_AUTH=disabled-local` — 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.
 
@@ -506,11 +506,12 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   refused.
 - Images and assets live in `knowledge/` beside the document that uses them,
   referenced by relative links. A relative link must never leave `knowledge/`.
-- **Study attachments.** A document may carry two optional companions named
-  after it, in the same folder: `<doc>.summary.md` (a short précis) and
-  `<doc>.flashcards.yaml` (a recall deck). The summary appears as a second tab
-  beside the document's own words; the deck appears at the END of that
-  document's page. Both appear nowhere else in the site.
+- **Study attachments.** A document may carry three optional companions named
+  after it, in the same folder: `<doc>.summary.md` (a short précis),
+  `<doc>.flashcards.yaml` (a recall deck) and `<doc>.quiz.yaml` (a
+  multiple-choice check). The summary appears as a second tab beside the
+  document's own words; the deck and the quiz appear at the END of that
+  document's page. None of them appears anywhere else in the site.
 
   An attachment is **part of its document**, not a document. It has no URL of
   its own, no sidebar row, no line in `llms.txt`, and no identity an agent can
@@ -549,6 +550,51 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   kept in the reader's own browser, so it is per-person and per-device, and it
   is not part of the record.
 
+  A **quiz** is the same idea with an answer to choose. Each question carries
+  two to six options, `answer` as the zero-based index of the correct one, a
+  required `explanation`, and an optional `source` naming where in the document
+  the answer lives:
+
+  ```yaml
+  quiz:
+    title: Expense approvals
+    questionsPerRound: 10 # optional; the default
+  questions:
+    - question: Who approves a purchase above the threshold?
+      options:
+        - A second approver, independent of the requester
+        - The requester's own manager, in every case
+        - The finance team, after the purchase completes
+      answer: 0
+      explanation: Why that is right, and why the others are not.
+      source: Approvals — thresholds
+  ```
+
+  The reader sees whether they were right **immediately**, then the
+  explanation — a quiz here teaches through the mistake, and it does not
+  certify anybody, so there is no pass mark. Answers stay in the reader's
+  browser and are sent nowhere. A bank larger than `questionsPerRound` is drawn
+  from at random and offers another round; a smaller one is simply asked in
+  full.
+
+  **`pnpm check` and `pnpm build` both refuse a quiz a reader could pass
+  without reading**, and this is worth knowing before you write one, because
+  it is easy to trip by accident:
+
+  | Refusal                    | Means                                                 |
+  | -------------------------- | ----------------------------------------------------- |
+  | `ksor-quiz-answer-bias`    | more than 60% of answers sit at one option position   |
+  | `ksor-quiz-length-bias`    | picking the longest (or shortest) option usually wins |
+  | `ksor-quiz-answer-run`     | four or more questions in a row share an answer       |
+  | `ksor-quiz-contradiction`  | an explanation calls the marked answer wrong          |
+  | `ksor-quiz-duplicate-stem` | two questions open with the same 60 characters        |
+
+  So: move the correct answer around, and keep the options close in length.
+  The ratio rules do not apply below five questions, where spreading answers
+  would mean the checker choosing them for you. These checks come from the
+  predecessor, where the same mistakes shipped and were found by readers — one
+  quiz had every correct answer in the same position across 451 questions.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 

package/templates/scaffold/README.md

@@ -31,13 +31,13 @@ Postgres store (with pgvector) and an embedding provider key, so it is not
 part of `pnpm dev`. The ordered path is:
 
 ```sh
-cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH_DISABLED=1
+cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH=disabled-local
 pnpm provision         # once: apply the schema, authorize ingest
 pnpm refresh           # ingest the record, collect retired generations
 pnpm serve             # the MCP server
 ```
 
-`ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH_DISABLED=1`
+`ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH=disabled-local`
 is required for a local run: serve refuses to boot unauthenticated on purpose,
 so a server is never open by accident.
 
@@ -56,7 +56,7 @@ effect of starting a process. A rerun on an unchanged record
 costs nothing: no new generation, no embedding, no rows. Edit a document and
 the next run picks up exactly that change. `AGENTS.md` → "Serving to agents" is the
 full runbook; your coding agent reads it first. `pnpm serve` refuses to boot
-unauthenticated: a local run declares `KSOR_AUTH_DISABLED=1` (already in
+unauthenticated: a local run declares `KSOR_AUTH=disabled-local` (already in
 `.env.example`) and binds loopback, so a server is never left open by accident;
 a public bind needs a configured SSO door instead. Any other operation is
 `pnpm exec ksor <verb>`.

package/templates/scaffold/env.example

@@ -12,11 +12,23 @@ KSOR_DB_URL=postgresql://user:password@host:5432/dbname
 # The embedding provider key. instance.md defaults to gemini-embedding-001.
 GEMINI_API_KEY=
 
-# Local development posture. `ksor serve` REFUSES to boot unauthenticated
-# without this — deliberately, so a server is never open by accident. It binds
-# loopback, where auth off is the intended dev shape.
+# ── Who may ask ─────────────────────────────────────────────────────────────
+# ONE variable, and its VALUE is the decision. `ksor serve` refuses to boot
+# without either this or a configured SSO door — a server is never open by
+# accident.
 #
-# For a PUBLIC deployment, delete this line and configure the SSO door instead:
+#   disabled-local   no auth, loopback only. A PUBLIC bind REFUSES, so copying
+#                    this file into a hosting dashboard cannot quietly open your
+#                    record to the internet. This is the dev posture.
+#   disabled-public  no auth, and serve the whole record to anyone who can reach
+#                    the port. A deliberate choice, correct for a genuinely
+#                    public record or behind your own gateway. NOT a way to make
+#                    a deploy go green.
+#
+# A container sets $PORT, so the door binds 0.0.0.0 — that is a public bind, and
+# `disabled-local` will refuse there. That refusal is the point.
+#
+# For a real deployment, delete this line and configure the SSO door instead:
 #   KSOR_SSO_URL=https://your-sso.example.com
 #   KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
 #   KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
@@ -27,15 +39,19 @@ GEMINI_API_KEY=
 # answered and where the keys came from.
 # Set this only to override discovery, or when your SSO publishes no metadata:
 #   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
-# Serving a public bind with auth off additionally requires
-# KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1, which serves your whole record to anyone
-# who can reach the port.
-KSOR_AUTH_DISABLED=1
+KSOR_AUTH=disabled-local
 
 # ── Production knobs ────────────────────────────────────────────────────────
 # Unset is fine for a local run; each one matters once this serves for real.
 
 # Snapshot-token signing keys, "kid=secret[,kid2=secret2]" (first is active).
+# SET THIS ON ANY CONTAINER HOST. Unset mints an EPHEMERAL per-process key, so a
+# generation pin issued by one instance is unverifiable by the next: `read`
+# silently drops to the active generation and reports "refreshed (invalid)".
+# It fails SOFT, so nothing errors and nothing logs — the only symptom is an
+# agent reading a generation it did not search. Generate one with
+# `openssl rand -hex 32`; the secret is used as literal text, never hex-decoded,
+# and must be IDENTICAL across every replica.
 # WITHOUT this the key is generated per PROCESS. Two deployments need it, not
 # just one: any MULTI-REPLICA deploy (a token minted by one replica is refused
 # by another), and any SCALE-TO-ZERO host, where a single replica mints a new