@panaversity/ksor 0.0.27 → 0.0.29

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @panaversity/ksor
 
+## 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
+
+- 24ec8c3: Each document page now says how long it takes to read.
+
+  The figure is counted when the site is built, from the document's own markdown,
+  so it is in the shipped HTML — a reader whose bundle failed, a crawler and an
+  agent parsing the page all get it. Fenced code and frontmatter are left out of
+  the count, so a short page carrying a long example is not reported as a
+  twenty-minute read.
+
+  Nothing to author: it is derived from the words already there. Where a document
+  has a summary, both tabs carry their own figure, so a reader can see what the
+  summary saves them before opening it.
+
+- 6abcf1f: Summaries and flashcard decks, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry two companions named after it —
+  `<doc>.summary.md` and `<doc>.flashcards.yaml`. The summary joins the record's
+  own words as a second tab; the deck renders at the end of the page, with spaced
+  review kept in the reader's browser and Shuffle / Guide / Download beneath it.
+  `ksor init` ships one of each so a fresh project shows the shape rather than
+  describing it.
+
+  An attachment is **part of its document, not a document**. It gets no URL, no
+  sidebar row, no `llms.txt` line, no markdown twin, no search entry — and no
+  stable id, so an agent can never cite it as a source in its own right. It takes
+  its `visibility:` and its takedown from its parent: restrict or withdraw the
+  document and its summary and deck go with it. An attachment declaring
+  frontmatter, or one whose document is missing, is refused by `pnpm check` and by
+  `pnpm build`.
+
+  **If your record already has `.summary.md` files and you serve over MCP, read
+  this.** They were previously ingested as ordinary documents, each with its own
+  id and its own governance defaults. They no longer are. After upgrading, run
+  `pnpm refresh`; if a takedown names one of those ids, `ksor serve` will refuse
+  to boot until the denial is pointed at the parent document or retired
+  deliberately. That refusal is the fix working — those rows governed a node that
+  should never have existed.
+
+  Review scheduling is a two-grade SM-2 variant (`ksor-sm2-v1`). It is not FSRS
+  and claims no retention target.
+
 ## 0.0.27
 
 ### 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-BF06IsJ--D-eI--yB.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 { 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-DE9PhWEx.mjs
+//#region ../content-gateway/dist/main-C-OMrGGt.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-FLQD4HUi.mjs
+//#region ../content/dist/commands-DU1nqwZa.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4148,6 +4179,54 @@ function compareSiblings(a, b) {
 	return codePointCompare$1(a.tie, b.tie);
 }
 /**
+* What makes a file in the record an ATTACHMENT rather than a document.
+*
+* A document may carry study attachments named after it — `x.summary.md` and
+* `x.flashcards.yaml` belong to `x.md` in the same directory. An attachment is
+* PART OF its parent: no route, no sidebar entry, no llms.txt line, no stable
+* id, no MCP node, and its parent's governance rather than its own.
+*
+* This rule is duplicated by construction — the kernel's ingest decides what
+* becomes a node, the site's staging decides what is copied, the site's build
+* decides what is a page, and the record's checker decides what is well-formed.
+* Four readers of one rule is exactly the shape decision 18 names, so this file
+* is canonical and every other copy is asserted against it rather than trusted.
+*
+* A LEAF: no imports, so any of those four can take it without taking anything
+* else with it.
+*/
+/** The suffix that marks each kind, longest-match first. */
+const ATTACHMENT_SUFFIXES = [
+	{
+		suffix: ".summary.md",
+		kind: "summary"
+	},
+	{
+		suffix: ".summary.mdx",
+		kind: "summary"
+	},
+	{
+		suffix: ".flashcards.yaml",
+		kind: "deck"
+	}
+];
+/**
+* The attachment kind this file name carries, or null when it is not one.
+*
+* Matched on the whole base name, never on a path: `.summary.md` in a directory
+* called `summary` is not an attachment, and a file called exactly
+* `.summary.md` (a dotfile with no stem) has no parent to attach to and is not
+* one either — the same "a dotfile has no suffix" boundary ingest's isDoc uses.
+*/
+function attachmentKindOf(baseName) {
+	for (const entry of ATTACHMENT_SUFFIXES) if (baseName.length > entry.suffix.length && baseName.endsWith(entry.suffix)) return entry.kind;
+	return null;
+}
+/** True when this file name is an attachment of some document. */
+function isAttachment(baseName) {
+	return attachmentKindOf(baseName) !== null;
+}
+/**
 * The plain-tree corpus adapter — ANY folder of Markdown becomes a corpus.
 * Converted from the oracle (sor-agentfactory @ b554f91,
 * ingest/adapters/plain_tree.py); the kernel cannot tell this manifest from
@@ -4360,8 +4439,23 @@ function buildManifestFromTree(root, options) {
 		sources
 	};
 }
-/** Python `p.suffix in (".md", ".mdx")` parity: a dotfile named exactly ".md" has NO suffix. */
+/**
+* Python `p.suffix in (".md", ".mdx")` parity: a dotfile named exactly ".md"
+* has NO suffix.
+*
+* ATTACHMENTS ARE NOT DOCUMENTS. `x.summary.md` ends in `.md`, so without the
+* attachment rule it ingested as a node of its own — `stable_id`
+* `knowledge/x.summary`, its own `content_nodes.visibility` coalescing to the
+* record default, and its own takedown state. That is one cause wearing four
+* costumes: the door served a summary the site hides; served an internal
+* parent's summary at the public tier; served a taken-down parent's summary
+* undenied (per-node denial matches a different id, and the subtree walk goes
+* through `parent_id`, which is the enclosing SECTION, not the sibling
+* document); and served an orphan the site refuses. An attachment belongs to
+* its parent, so it gets no id and is never independently citable.
+*/
 function isDoc(name) {
+	if (isAttachment(name)) return false;
 	const dot = name.lastIndexOf(".");
 	if (dot <= 0) return false;
 	const suffix = name.slice(dot);

package/dist/{gateway-api-BF06IsJ--D-eI--yB.mjs → gateway-api-8lNruq9e-CuohjtoK.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-BF06IsJ-.mjs
+//#region ../content-gateway/dist/gateway-api-8lNruq9e.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-BF06IsJ--D-eI--yB.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-8lNruq9e-CuohjtoK.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.27",
+  "version": "0.0.29",
   "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",
@@ -71,8 +71,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content-gateway": "0.0.0",
-    "@panaversity/ksor-content": "0.0.0"
+    "@panaversity/ksor-content": "0.0.0",
+    "@panaversity/ksor-content-gateway": "0.0.0"
   },
   "engines": {
     "node": ">=24"

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

@@ -35,6 +35,35 @@ const REQUIRED_KEYS = ["title", "status"]; // level 0 — the ladder, not a gate
 const STATUS_VALUES = new Set(["draft", "review", "approved", "superseded"]);
 const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]);
 
+// Study attachments: `x.summary.md` and `x.flashcards.yaml` belong to `x.md`.
+// An attachment is PART OF its parent — no route, no stable id, no governance
+// of its own — so it is neither a document nor an asset, and gets its own
+// 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"];
+// 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.
+const ATTACHMENT_NEAR_MISSES = [
+  [".flashcards.yml", ".flashcards.yaml"],
+  [".flashcards.json", ".flashcards.yaml"],
+  [".summary.markdown", ".summary.md"],
+];
+
+/** The attachment suffix this name carries, or null. A dotfile has no stem. */
+function attachmentSuffixOf(base) {
+  return ATTACHMENT_SUFFIXES.find((s) => base.length > s.length && base.endsWith(s)) ?? null;
+}
+function isAttachment(base) {
+  return attachmentSuffixOf(base) !== null;
+}
+/** The document an attachment belongs to: always `<stem>.md`. */
+function parentDocumentOf(base) {
+  const suffix = attachmentSuffixOf(base);
+  return suffix === null ? null : `${base.slice(0, -suffix.length)}.md`;
+}
+
 // PNG integrity, dependency-free: signature + per-chunk CRC-32. A damaged
 // image beside a document is a check-time problem with the file named, never
 // a build-time 500 with no filename in it.
@@ -381,7 +410,9 @@ if (!existsSync(knowledgeDir)) {
   }
   const dirs = walkDirs(knowledgeDir);
   const all = [...files, ...dirs];
-  const mdFiles = files.filter((p) => p.endsWith(".md"));
+  // Attachments are never documents: they carry no frontmatter, own no route,
+  // and are checked by their own rules instead.
+  const mdFiles = files.filter((p) => p.endsWith(".md") && !isAttachment(path.basename(p)));
 
   if (mdFiles.length === 0) {
     problem(
@@ -446,7 +477,12 @@ if (!existsSync(knowledgeDir)) {
       );
     }
     seenLower.set(lower, rel);
-    if (files.includes(p) && !p.endsWith(".md") && !ASSET_EXTENSIONS.has(path.extname(p))) {
+    if (
+      files.includes(p) &&
+      !p.endsWith(".md") &&
+      !isAttachment(base) &&
+      !ASSET_EXTENSIONS.has(path.extname(p))
+    ) {
       problem(
         rel,
         `unexpected file type "${path.extname(p) || base}"`,
@@ -486,6 +522,51 @@ if (!existsSync(knowledgeDir)) {
     }
   }
 
+  // Study attachments: bound to a parent, carrying no governance of their own.
+  for (const p of files) {
+    const base = path.basename(p);
+    const rel = path.relative(root, p);
+
+    const nearMiss = ATTACHMENT_NEAR_MISSES.find(
+      ([wrong]) => base.length > wrong.length && base.endsWith(wrong),
+    );
+    if (nearMiss && !isAttachment(base)) {
+      problem(
+        rel,
+        `${nearMiss[0]} is not an attachment extension`,
+        "the site reads decks as YAML and accepts only .yaml — a near miss is not picked up as a deck, and fails the build naming the path but not the rule",
+        `rename it to ${base.slice(0, -nearMiss[0].length)}${nearMiss[1]}`,
+      );
+      continue;
+    }
+
+    if (!isAttachment(base)) continue;
+
+    const parent = parentDocumentOf(base);
+    if (parent && !existsSync(path.join(path.dirname(p), parent))) {
+      problem(
+        rel,
+        `attachment of ${parent}, which is not in the record`,
+        "an attachment inherits its parent's governance — with no parent there is nothing to inherit, so it would be published under no tier and covered by no takedown",
+        `add ${path.join(path.dirname(rel), parent)}, or remove ${rel}`,
+      );
+    }
+
+    if (base.endsWith(".md") || base.endsWith(".mdx")) {
+      const text = readFileSync(p, "utf8")
+        .replace(/^\uFEFF/, "")
+        .replaceAll("\r\n", "\n");
+      if (text.startsWith("---\n")) {
+        problem(
+          rel,
+          "attachment declares frontmatter",
+          "an attachment is part of its parent and carries none of its own governance — a key here would look like it governs something and would govern nothing (a visibility: on a summary of a restricted document is the shape that matters)",
+          `remove the frontmatter block; ${parent ?? "its parent"} is what carries the governance`,
+        );
+      }
+    }
+  }
+
   // foo.md vs foo/index.md route collisions
   for (const p of mdFiles) {
     const sibling = p.replace(/\.md$/, "");