@panaversity/ksor 0.0.48 → 0.0.50

package/CHANGELOG.md

@@ -1,5 +1,278 @@
 # @panaversity/ksor
 
+## 0.0.50
+
+### Patch Changes
+
+- f27f947: The three embed tuning variables now take effect when set in `.env`.
+  `KSOR_EMBED_TIMEOUT_S`, `KSOR_QUERY_EMBED_TIMEOUT_S` and `KSOR_EMBED_CACHE_MAX`
+  were read once at module load — before the CLI applies `.env` in `main()` — so
+  a value set there was silently ignored and the default stood. An adopter who
+  set `KSOR_EMBED_CACHE_MAX` to fit a small runtime, for instance, still got the
+  ~250 MB default cache and could OOM in production with nothing pointing at why.
+  The reads now happen at use. Exported shell variables were unaffected and still
+  are.
+
+## 0.0.49
+
+### Patch Changes
+
+- 5701679: **Three places where the record described a system that was never built.**
+  Nothing an adopter runs changes; what changes is whether the decision log can be
+  trusted without re-checking it against the code (issues #151 and #180).
+
+  Decision 13 said the door composes `secureHeaders` / `bodyLimit` middleware.
+  `bodyLimit` is real — `content-gateway/src/http.ts:26,522` — but `secureHeaders`
+  was never adopted: nothing imports it, and the door sets its own pair by hand
+  (HSTS and `x-content-type-options: nosniff`, "nothing else"). The code is right
+  and the entry was wrong, so the entry is corrected.
+
+  The same decision, and guard rule 5's why-comment, said `hono` and
+  `@hono/node-server` were "already the SDK's transitive deps, so zero new install
+  bytes". True of the 1.x monolith, false since v2 — `@modelcontextprotocol/server`
+  2.0.0 depends on `zod` and `@modelcontextprotocol/core` and nothing else. The
+  reason that survives the upgrade is the one already recorded (the SDK's only HTTP
+  shape is Web-standard and hono needs no bridge to it); the weight is a cost paid
+  deliberately rather than an absence of cost.
+
+  The README stated OpenTelemetry in the present tense — "tells us what happened",
+  "records what the infrastructure did" — with no telemetry code in the tree. It is
+  future tense now, with the constraint the row's own wording already implies:
+  default auto-instrumentation captures `pg` statement text, and a trace backend is
+  a different security boundary from the MCP response.
+
+  SLSA/Sigstore, two rows above, needed the opposite correction. It is not future:
+  `release.yml` sets `id-token: write`, so every release attests the published
+  PACKAGE through npm provenance. What is unbuilt is signing a RECORD's own
+  `build.lock.json`. Both rows now say which half runs.
+
+  Also removed: a `publishConfig` block on `@panaversity/ksor-content-gateway`,
+  which is `private: true` and is bundled rather than published, so the block could
+  never apply.
+
+- 7e72d35: **The embedding dimension ceiling is now held equal in both places it is
+  declared.**
+
+  `EMBED_DIM_MAX` is declared twice — in the instance parser, so a bad `dim:` is
+  refused when `instance.md` is READ, and in the DDL renderer, so it is refused
+  again before any schema is rendered. The split is deliberate and the comment
+  beside one calls it a mirror of the other. Nothing held them equal: before this,
+  the constant appeared in no test anywhere in the repository, so raising the
+  ceiling in one place alone would have left the parser and the renderer refusing
+  at different dimensions — one of the two would still have reddened an existing
+  wording assertion, and an instance-only edit would have passed everything.
+
+  The test asserts EQUALITY and never the number, so the ceiling can still move —
+  which is the point, because the decision that records why it sits at 2000 prices
+  raising it rather than forbidding it.
+
+  Also in the same area: the emitted `AGENTS.md` carried the benchmark figures
+  behind that default with no source and no date, shipped to every adopter. It
+  states the constraint an adopter acts on and points at the decision that holds
+  the numbers, so the measurement now lives beside the constant it constrains,
+  with its provenance, in one place.
+
+- b7a7c5b: **Two audit rows were missing the fact that makes them auditable.**
+
+  `retrieval_log` exists so an operator can say what an act was allowed to see and
+  what it answered from. Two rows could not answer that:
+
+  - **`outline_served` recorded no generation.** Its two siblings,
+    `similarity_searched` and `content_served`, both pin one — so the single act
+    that hands an agent the SHAPE of the record was the one that could not be
+    joined to the publication it described. The projection carried no generation
+    to write, so this is a column rather than an extra query: `walk` already
+    selects it, and `OUTLINE_COLUMNS` moves 9 → 10 under the same width guard that
+    exists because a narrower fixture once hid a truncated projection.
+  - **An ANSWERED search recorded no `top_cosine`.** The abstained row has always
+    carried it, so the ledger held the deciding score only for queries the gate
+    REFUSED — precisely the half that cannot show a floor drifting as a record
+    grows. Both rows now record what the decision turned on, whichever way it
+    went.
+
+  An empty outline still records NULL, deliberately: it served no row from any
+  generation, which is the same reason `search_abstained` records NULL when
+  nothing matched.
+
+  **And `cleanCut` is deleted.** It was exported and documented as the tool the
+  search budget uses to trim an overflowing hit — in the present tense, for a
+  caller that has never existed. It came from the predecessor's grain-expansion
+  path, a feature ksor deliberately never carried, so it was a mechanism brought
+  across without the purpose it existed for.
+
+- 50abe52: **`pnpm preview` no longer dies on a URL it cannot parse or a file it cannot
+  read.**
+
+  Two crashes of one shape, both in the emitted preview server. `pipe()` attaches
+  its error listener to the destination and never to the source, and
+  `decodeURIComponent` throws on a malformed escape — so either failure reached a
+  `node:http` request listener with nobody watching, which is an uncaught
+  exception. The process exited and left the adopter a dead port and a stack trace
+  instead of a page.
+
+  - **`http://localhost:3000/%`** ended the session. So did `/%zz` and any
+    truncated multi-byte escape — the first hostile URL a browser extension or a
+    scanner sends.
+  - **A file the export cannot read** did the same, with no attacker at all: a
+    mode-000 file anywhere under `out/` is a one-request kill, and so is the
+    ordinary loop of rebuilding in another pane while the preview runs, where the
+    export is torn down and a page re-requests an asset that has gone.
+
+  A request that cannot be parsed now resolves to nothing, which is what the 404
+  path is for. And a file that fails to open answers **500 with a reason**, not a
+  blank page: the response head is written on the read stream's `open` event
+  rather than before it, so a file that never opens can still be answered
+  honestly. (A file that vanished BEFORE the request was already a 404 — the
+  resolver stats every candidate — so this is the file that is there and will not
+  open.) Writing it first would have produced a complete, valid, EMPTY `200` —
+  which a browser renders as a blank page and `fetch().text()` reports as `""` —
+  and that is the same silent lie this change exists to stop telling, one layer
+  down. A failure PART WAY through, where the head is already out and no status
+  is left to send, destroys the connection instead of ending it cleanly, so the
+  client sees a truncated response because that is what happened. Either way the
+  reason goes to the console.
+
+  **Two more failures now explain themselves** instead of arriving as stack
+  traces: an occupied port names the collision — `dev` defaults to 3000 as well —
+  and a `PORT` that is not a port number is refused. That covers more than the
+  obvious case: `Number("")` and `Number(" ")` are `0`, so an unset `PORT=` in a
+  shell or a compose file used to bind an arbitrary port and print
+  `http://localhost:0`, exactly as `PORT=abc` printed `:NaN`.
+
+  **And the server binds where it says it binds.** `listen(PORT)` with no host
+  binds every interface while the log has always printed `localhost`, so the built
+  export was reachable from the whole network. It is loopback now, with
+  `KSOR_PREVIEW_HOST` as the way out for the cases where reaching it from
+  elsewhere is the point — a container published with `-p`, a cloud dev box, or
+  the built site on a phone. Set it on the command line: `preview` is plain `node`
+  and does not read `.env`.
+
+  Stated precisely, because a governance claim is the one thing to get exactly
+  right in both directions. A DEFAULT build carries no drafts at all (record spec
+  §2.5 admits them to no surface of a build), so what a default `out/` exposed is
+  the published record. The case that mattered is the one this first missed:
+  `KSOR_AUDIENCE=public,<audience> pnpm build`, whose output holds
+  audience-restricted documents and which the scaffold's AGENTS.md says "belongs
+  behind that audience's own access control, never on a public host" — that `out/`
+  was network-reachable from a preview. `KSOR_DRAFTS=show` is the other. `pnpm dev`,
+  where drafts live, is `next dev` and unchanged by this.
+
+  Alongside this, the containment check moved from once-per-request to
+  per-candidate. `resolve()` tries three filename shapes, and the third,
+  `` `${target}.html` ``, names a sibling of the export root whenever the target
+  IS the root. It is reachable only when the export has no `index.html`, so this
+  is defence in depth rather than a fixed leak — and it is the case the test now
+  builds an export without an index in order to reach, having previously asserted
+  the rule against a fixture that could not.
+
+- 33b6080: **`ksor schema --apply` no longer loses a ROLE when two run at once.**
+
+  `schema.sql` creates three roles, and Postgres roles are CLUSTER-GLOBAL — so
+  `IF NOT EXISTS ... THEN CREATE ROLE` is check-then-act across every database on
+  the instance. Two concurrent applies both see the role absent and both create
+  it. Measured on Postgres 17.7 against an empty cluster: **six concurrent applies,
+  five failed.**
+
+  The SQLSTATE that surfaces is `unique_violation` (23505) on
+  `pg_authid_rolname_index`, **not** `duplicate_object` (42710) — catching only the
+  latter is the obvious fix and does not work. Both are caught now.
+
+  And each role is created in its **own** `DO` block. A `DO` block is a single
+  statement, so an exception anywhere in it rolls the whole block back: three
+  roles in one block meant a loser on the first never created the other two, and
+  the apply then granted against roles that did not exist.
+
+  The same check-then-act sat in the 2.2 → 2.3 migration, which `ksor schema
+--apply` also reaches, and is fixed with it.
+
+  This is not only a test-tier problem, which is why it lives in the DDL: two
+  operators provisioning at once, or a deploy step racing a developer, hit it
+  identically.
+
+  **Scoped honestly:** what is fixed is role creation, which is the part that
+  raced across SEPARATE databases — the shape two concurrent runs actually have.
+  Two applies against the SAME database still race, on `CREATE EXTENSION` and then
+  on table creation; `applySchema`'s contract is a fresh database and that is
+  unchanged here.
+
+- 988d749: **The emitted site builds with webpack, so a real record still deploys.**
+
+  The scaffold's site build was `next build`, which under the pinned Next 16.2.9
+  means Turbopack — and on Vercel's default build machine (4 cores, 8 GB) that
+  does not survive a record big enough to prerender a few hundred routes.
+  Measured on a real 205-document record, 435 routes: about seven minutes, then
+
+  ```
+  FATAL: An unexpected Turbopack error occurred:
+  Failed to write app endpoint /icon.png/route
+  - timeout while receiving message from process
+  - deadline has elapsed
+  ```
+
+  Nothing in that points at the build command, and it names `/icon.png/route`,
+  which is not the problem — the trace's own middle is the PostCSS step. The same
+  record compiled in 86s with `next build --webpack`, which is Next 16's
+  documented opt-out rather than a workaround: the v16 upgrade guide ships exactly
+  this `package.json` line for a project that needs webpack.
+
+  The scaffold now emits `next build --webpack`. `dev` is unchanged and still
+  Turbopack — the failure is production-only, where every route is prerendered at
+  once. An existing project takes the fix with `ksor migrate --write-site`, which
+  already offers `system/site/package.json`.
+
+  This also retires an intermittent CI failure: the conformance suites carried a
+  retry for `TurbopackInternalError: Input image not found`, a flake in
+  Turbopack's static-image metadata pipeline reading the scaffold's `app/icon.png`
+  mark. That pipeline is no longer on the production path, so the retry is gone
+  rather than left in place — a shim retrying quietly is what would stop the suite
+  reporting a real regression.
+
+- 988d749: **A Vercel deployment that reports Ready and 404s everywhere now has a written
+  diagnosis, and the provenance hint stops blaming the reader.**
+
+  A deployment can report **Ready**, take the production alias, and serve
+  `404: NOT_FOUND` at every path, `llms.txt` included — after an install that ran,
+  a `ksor build` that ran, and every route prerendering. The only signal anywhere
+  is one build-log line, `WARNING! Build output contains no "functions" or
+"static" directory`.
+
+  **The cause is not established, and the docs now say so rather than guessing.**
+  The Application Preset was the obvious suspect and is measured NOT to be it: two
+  live Git-linked projects, one preset `Services` and one preset `Other`, both
+  built the `services` block's `site` and `door` and both serve them (`/` 200,
+  `llms.txt` 200, `/mcp` 405 from the door). Naming a wrong cause in the deploy
+  guide would have sent every future reader to a field that is not the problem.
+
+  `deploying.md` and the scaffold README now name that failure, quote the warning
+  so it is searchable, and record two things verified live on a 205-document record
+  (issue #197): patching the project's own `outputDirectory` / `buildCommand` /
+  `installCommand` and taking a fresh Git-sourced deployment does **not** fix it —
+  `vercel.json` is what Vercel reads — and replacing the `services` block with the
+  classic top-level keys does. Two earlier sentences were corrected rather than
+  extended: the docs said a wrong preset meant "`/mcp` never exists", which asserted a
+  mechanism now measured false, and offered a site-only fallback as project
+  settings, which cannot override `vercel.json`.
+
+  **And `source: unspecified` now names both of its causes.** Only one is "you
+  never made a repository"; the other is a record that IS committed and pushed, on
+  a machine the `.git` directory never reached, because an upload-based deploy
+  excludes it — Vercel's CLI does. `git init` is still offered first, because it is
+  still right for the reader who has not made one; what is new is the second line,
+  for the reader who has, and who was previously being told to redo work they had
+  already done in the one message that governs provenance.
+
+  **A remedy also stops naming a flag the verb refuses.** `--source-commit` is an
+  `ingest` flag; `ksor build` rejects it as an unknown argument and exits 1. Two of
+  the five provenance notices offered it regardless of which verb was printing —
+  including the one this change is for, read by someone whose upload stripped
+  `.git` on the deploy path, for whom it would have turned a provenance warning
+  into a failed build. The flag is now offered only by the verb that accepts it,
+  and the same correction is applied to the `(dirty)` notice's `ksor build
+--strict`, which had the defect latently. Both are asserted across every gap,
+  enumerated from the exported list rather than a copy of it.
+
+  The emitted `vercel.json` is unchanged.
+
 ## 0.0.48
 
 ### Patch Changes

package/README.md

@@ -82,8 +82,10 @@ agent surface at all.
 The architecture: **one governed record** — Markdown in the KSoR Profile of
 the Open Knowledge Format (OKF) — behind **one governance boundary**,
 projected through open standards: MCP for agents, `llms.txt` for AI
-discovery, OAuth/OIDC for identity, SLSA/Sigstore for publication integrity,
-OpenTelemetry for observability.
+discovery, and OAuth/OIDC for identity. Two more name which standard owns a
+boundary rather than a surface that fully runs today: SLSA/Sigstore, which
+attests this npm package through npm provenance but does not yet sign a
+record's own `build.lock.json`, and OpenTelemetry, which emits nothing yet.
 
 Full concept, design goals, and project status:
 **<https://github.com/panaversity/ksor>**

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-dqpI-p1a.mjs";
-import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-CF4ED9_g-BQusM_dK.mjs";
+import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-D8HlLys2-Ca8OnwLn.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -17,7 +17,7 @@ import { Document, YAMLParseError, isCollection, isMap, isPair, isSeq, parseAllD
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 import { execFileSync, spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-fqHB0gE_.mjs
+//#region ../content-gateway/dist/main-DMCMO8ye.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -4709,7 +4709,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-AMitIS8m.mjs
+//#region ../content/dist/commands-BNxmBRjs.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5131,11 +5131,15 @@ async function runIngest(pool, tenantId, op) {
 * Raising it is a decision, not a constant: every query site would have to use
 * the same cast as the index or fall silently back to a sequential scan, and
 * the halfvec arm's float16 rounding lands on the score the abstention gate
-* reads. Recorded in issue #49, along with the evidence for staying at 1536 —
-* Google's published MTEB table runs 128..2048 and is FLAT at the top of that
-* range (1536 scores 68.17, 2048 scores 68.16), so there is no gradient to
-* climb toward the ceiling. It carries no 3072 row, so the cost of the
-* truncation itself is unpublished; do not infer one.
+* reads. AGENTS.md decision 30 records the choice; the measurement behind it
+* lives HERE, beside the constant it constrains, and this is its only copy.
+*
+* Google's per-dimension table
+* (https://ai.google.dev/gemini-api/docs/embeddings, retrieved 2026-08-27)
+* runs 128..2048 and is FLAT at the top of that range: 1536 scores 68.17 MTEB
+* against 2048's 68.16. So there is no gradient to climb toward the ceiling
+* from where we sit. It carries no 3072 row, so the cost of the truncation
+* itself is unpublished; do not infer one.
 */
 const EMBED_DIM_MAX = 2e3;
 /** The schema version schema.sql declares — parsed from the DDL so code and
@@ -5783,11 +5787,12 @@ async function topOneScore(client, scope, queryVector) {
 	})).rows[0]?.[0];
 	return raw === void 0 || raw === null ? null : toNumber(raw, "score");
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 /** The text we embed for a chunk: the readable hierarchical heading path, then the content. */
 function embedInput(title, headingPath, content) {
 	const path = headingPath ? (title ? title + " > " : "") + headingPath.replaceAll("/", " > ").replaceAll("-", " ").trim() : title;
@@ -6209,8 +6214,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */
@@ -9806,15 +9811,25 @@ function provenanceGap(knowledgeDir) {
 /**
 * The remedy for each, because the reader's next command differs.
 *
-* `subject` is the artefact whose provenance is missing — the noun is the only
-* thing that differs between the verbs, so it is the only thing parameterised.
+* `subject` is the artefact whose provenance is missing. It began as the noun
+* alone — "the only thing that differs between the verbs" — and that was wrong:
+* the ESCAPE HATCH differs too. `--source-commit` is an `ingest` flag
+* (`commands.ts`); `ksor build`'s `parseArgs` refuses it as an unknown argument
+* and exits 1. So a remedy that named it unconditionally told a `build` reader
+* to run `ksor build --source-commit <sha>` and get `error: bad-args` — turning
+* a provenance WARNING into a failed build for anyone who followed it, in the
+* message product principle 4 asks to be documentation. Both are parameterised
+* now, and a verb that gains the flag renders the escape by declaring so here.
 */
 function provenanceNotice(gap, subject = "generation") {
 	const why = `so this ${subject} cannot be traced back to a reviewed commit`;
+	const offersSourceCommit = subject === "generation";
 	switch (gap) {
 		case "no-commit": return `source: unspecified — knowledge/ is in a git repository with no commits yet, ${why}.\n  fix: commit the record (git add knowledge && git commit) and re-run`;
-		case "no-repo": return `source: unspecified — knowledge/ is not in a git repository, ${why}.\n  fix: git init, commit the record, and re-run`;
-		case "no-git": return `source: unspecified — git is not installed, ${why}.\n  fix: install git, or pass --source-commit <sha> if the record is versioned elsewhere`;
+		case "no-repo": return `source: unspecified — knowledge/ is not in a git repository, ${why}.\n  fix: git init, commit the record, and re-run
+  if it IS committed: .git did not reach this machine — an upload-based deploy
+    excludes it (Vercel's CLI does). Deploy from the Git connection instead` + (offersSourceCommit ? ",\n    or pass --source-commit <sha>" : "");
+		case "no-git": return `source: unspecified — git is not installed, ${why}.\n  fix: install git` + (offersSourceCommit ? ", or pass --source-commit <sha> if the record is versioned elsewhere" : "");
 		case "no-input-commit": return `source: unspecified — no commit touches the record (knowledge/, instance.md, .ksor/governance.yaml, .ksor/takedowns.yaml), ${why}.\n  fix: commit the record (git add knowledge instance.md .ksor && git commit) and re-run`;
 		case "not-asked": return `source: unspecified — no knowledge directory was given, ${why}.`;
 	}
@@ -9865,7 +9880,7 @@ function detectSourceCommit(knowledgeDir) {
 * this record that looks like provenance and is not.
 */
 function dirtyNotice(commit, subject = "build") {
-	return `source: ${commit} (dirty) — an input differs from that commit, so it does not contain the bytes this ${subject} published.\n  fix: commit the inputs (git add -A && git commit) and re-run; \`ksor build --strict\` refuses this state instead of stamping it`;
+	return `source: ${commit} (dirty) — an input differs from that commit, so it does not contain the bytes this ${subject} published.\n  fix: commit the inputs (git add -A && git commit) and re-run${subject === "build" ? "; `ksor build --strict` refuses this state instead of stamping it" : ""}`;
 }
 /** One transaction (tenant GUC + ingest role): list collectables, then reap each. */
 async function runGc(pool, instance, options = {}) {

package/dist/{gateway-api-CF4ED9_g-BQusM_dK.mjs → gateway-api-D8HlLys2-Ca8OnwLn.mjs}

@@ -6,7 +6,7 @@ import { z, z as z$1 } from "zod";
 import path, { join } from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-CF4ED9_g.mjs
+//#region ../content-gateway/dist/gateway-api-D8HlLys2.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -8769,11 +8769,12 @@ function validate$1(ring, token, scope, nowMs = Date.now()) {
 		reason: null
 	};
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 function l2Normalize(v) {
 	const norm = Math.sqrt(v.reduce((acc, x) => acc + x * x, 0));
 	return norm === 0 ? v : v.map((x) => x / norm);
@@ -9120,8 +9121,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */
@@ -9726,7 +9727,8 @@ SELECT w.slug, w.kind, w.title, w.heading_path,
        EXISTS (SELECT 1 FROM sources s
                 WHERE s.tenant_id = $1 AND s.generation = w.generation
                   AND s.node_id = w.node_id) AS has_content,
-       w.permalink
+       w.permalink,
+       w.generation
 FROM walk w
 JOIN content_nodes n ON n.node_id = w.node_id AND n.tenant_id = $1
                     AND n.generation = w.generation
@@ -9875,7 +9877,7 @@ async function documentFrontmatter(client, scope, nodeId) {
 	return value === void 0 || value === null ? null : String(value);
 }
 function outlineRows(result) {
-	if (result.fields.length !== 9) throw new TypeError(`outline projection drift: expected 9 columns, got ${result.fields.length} (${result.fields.map((f) => f.name).join(", ")})`);
+	if (result.fields.length !== 10) throw new TypeError(`outline projection drift: expected 10 columns, got ${result.fields.length} (${result.fields.map((f) => f.name).join(", ")})`);
 	return result.rows.map((row) => ({
 		slug: String(row[0]),
 		kind: String(row[1]),
@@ -9885,7 +9887,8 @@ function outlineRows(result) {
 		depth: toNumber(row[5], "depth"),
 		childCount: toNumber(row[6], "child_count"),
 		hasContent: Boolean(row[7]),
-		permalink: row[8] === null ? null : String(row[8])
+		permalink: row[8] === null ? null : String(row[8]),
+		generation: toNumber(row[9], "generation")
 	}));
 }
 /**
@@ -9928,6 +9931,13 @@ const OUTLINE_CEILING = 5002;
 * ROOT-ABSOLUTE depth + breadcrumb (the wire contract: rows are
 * self-locating; a leaf with no children returns an empty list — the
 * anchor itself is never echoed back).
+*
+* Returns the GENERATION it served from alongside the rows, because [] cannot
+* carry one. A drill-down onto a leaf resolves its anchor and pins that
+* generation, then returns no rows — and the tool description tells an agent to
+* drill in, so that is a routine call, not an edge case. Reading the generation
+* off `rows[0]` recorded NULL for every one of them. `content_served` sets the
+* precedent: pin what was RESOLVED, however little came back.
 */
 async function outline(client, scope, options = {}) {
 	const root = options.root ?? null;
@@ -9963,7 +9973,10 @@ async function outline(client, scope, options = {}) {
 			offset
 		]
 	}));
-	if (root === null) return rows;
+	if (root === null) return {
+		rows,
+		generation: pinned ?? rows[0]?.generation ?? null
+	};
 	const anchorRow = (await arrayQuery(client, {
 		text: UP_WALK_SQL,
 		values: [
@@ -9974,11 +9987,51 @@ async function outline(client, scope, options = {}) {
 		]
 	})).rows[0];
 	if (anchorRow === void 0) throw new Error(`no node with slug ${JSON.stringify(root)} — browse from the root with outline() (omit node=)`);
-	return rebaseOutlineRows(rows, String(anchorRow[0]), toNumber(anchorRow[1], "climbed"));
+	return {
+		rows: rebaseOutlineRows(rows, String(anchorRow[0]), toNumber(anchorRow[1], "climbed")),
+		generation: pinned ?? rows[0]?.generation ?? null
+	};
 }
-let cacheMax = envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
-/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. */
-const EMBED_WALL_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
+/**
+* Query-embedding cache, converted from the oracle (sor-agentfactory @
+* b554f91, sor_content/lib/query_embed.py): L1 in-process LRU + SINGLE-FLIGHT
+* (concurrent identical misses share ONE paid embed), keyed with
+* model + task + dim so a model or dimension bump can never serve a stale
+* vector. Whitespace collapses; case does NOT fold (folding would change the
+* embedded text).
+*
+* A tiny CIRCUIT BREAKER guards the provider: after an embed failure, further
+* misses raise immediately for a short cooldown (cache hits still serve) —
+* during an outage every request degrades to keyword-only instantly instead
+* of each unique query paying its own failed attempt against a provider that
+* is already down. The breaker is keyed per SPACE (modelId, dim), like the
+* keys: a failing provider A must not degrade a healthy provider B.
+*
+* Conversion notes (decision 6):
+* - The oracle's optional Redis L2 (fail-open both directions, TTL
+*   SOR_EMBED_CACHE_TTL, the `sor:emb:*` key scheme) is DROPPED — it was
+*   multi-instance infrastructure; the L1 + single-flight carry a
+*   single-process deployment. It returns, if ever, with real multi-instance
+*   serving — nothing here forecloses it.
+* - The oracle's waiter-shield (`asyncio.shield`) and owner-cancel handling
+*   protected the shared future from one caller's cancellation. JS promises
+*   are not cancellable, so sharing the promise IS the whole mechanism: no
+*   caller can cancel another, and there is no owner-cancelled path to map.
+* - `asyncio.wait_for` CANCELLED the embed on timeout; a JS promise cannot be
+*   cancelled, so on timeout the losing call is abandoned (its settlement is
+*   still observed, so it can never surface as an unhandled rejection) and
+*   runs out its own HTTP timeout in the background.
+* - The breaker clock is Date.now() (ms) rather than a monotonic clock — the
+*   10 s cooldown is coarse, and fake-timer tests need the system clock.
+*/
+/** Oracle env var: SOR_EMBED_CACHE_MAX. */
+let memoizedCacheMax;
+function currentCacheMax() {
+	return memoizedCacheMax ??= envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
+}
+/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Read at use, not at module load
+* — see the cache-max note above. */
+const EMBED_WALL_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
 const cache = /* @__PURE__ */ new Map();
 const inflight = /* @__PURE__ */ new Map();
 const breakerOpenUntilByMs = /* @__PURE__ */ new Map();
@@ -10022,10 +10075,11 @@ function breakerOpenUntil(provider) {
 	return breakerOpenUntilByMs.get(spaceKey(provider)) ?? 0;
 }
 function withWallClock(work) {
+	const wallTimeoutS = EMBED_WALL_TIMEOUT_S();
 	return new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
-			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${EMBED_WALL_TIMEOUT_S}s wall clock — treated as a provider failure (degrade to keyword-only)`));
-		}, EMBED_WALL_TIMEOUT_S * 1e3);
+			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${wallTimeoutS}s wall clock — treated as a provider failure (degrade to keyword-only)`));
+		}, wallTimeoutS * 1e3);
 		work.then((value) => {
 			clearTimeout(timer);
 			resolve(value);
@@ -10046,7 +10100,7 @@ async function embedMiss(normalized, key, provider) {
 		const literal = vlit(vec);
 		cache.delete(key);
 		cache.set(key, literal);
-		while (cache.size > cacheMax) {
+		while (cache.size > currentCacheMax()) {
 			const oldest = cache.keys().next().value;
 			if (oldest === void 0) break;
 			cache.delete(oldest);
@@ -10409,6 +10463,7 @@ async function search(ctx, query, k = 10) {
 			query_chars: queryChars,
 			k,
 			k_effective: kb,
+			top_cosine: topCosine,
 			slugs: [...new Set(shaped.map((h) => h.slug))],
 			truncated,
 			degraded: degradedReason !== void 0
@@ -10579,7 +10634,7 @@ async function outlineDocuments(ctx, options = {}) {
 	};
 	const limit = Math.max(1, Math.min(options.limit ?? 200, MAX_OUTLINE_LIMIT));
 	const offset = Math.max(0, options.offset ?? 0);
-	const rows = await runRead(ctx.pool, inst.tenantId, (client) => outline(client, scope, {
+	const { rows, generation } = await runRead(ctx.pool, inst.tenantId, (client) => outline(client, scope, {
 		root,
 		depth,
 		limit: limit + 1,
@@ -10593,6 +10648,7 @@ async function outlineDocuments(ctx, options = {}) {
 		actor,
 		action: "outline_served",
 		instanceDigest: ctx.instanceDigest,
+		...generation === null ? {} : { generation },
 		detail: {
 			...actScope(ctx),
 			node: root,

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-CF4ED9_g-BQusM_dK.mjs";
+import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-D8HlLys2-Ca8OnwLn.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, TRUST_TIERS, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/deploying.md

@@ -133,13 +133,88 @@ What the image deliberately does NOT contain (see `.dockerignore`):
 > every dashboard import until Vercel's detection changes — the layout that
 > triggers it, code under `system/`, is decision 8 and is not moving.
 >
-> Also confirm **Application Preset is `Services`**; with any other preset the
-> `services` key is ignored and `/mcp` never exists. Vercel Services is in Beta.
+> ---
 >
-> **If it still argues, deploy the site alone** — it needs no preset and no
-> services: build command `pnpm -C system/site build`, output directory
-> `system/site/out`. That is the stricter posture decision 29 describes, and
-> the door can be deployed separately.
+> **The emitted `vercel.json` is verified working on the Git path.** Measured on
+> two live Git-linked projects, 2026-08-27: both built the `services` block's
+> `site` and `door`, and both serve — `/` 200, `/llms.txt` 200, and `/mcp` 405,
+> which is the door answering "Method Not Allowed" to a GET rather than a static
+> 404, and is how you tell the door is routed at all.
+>
+> **It does not depend on the Application Preset**, which is the first thing
+> everyone suspects and the reason to say so:
+>
+> | project's preset | `services` block built | serves                                 |
+> | ---------------- | ---------------------- | -------------------------------------- |
+> | `Services`       | `site` + `door`        | `/` 200 · `/llms.txt` 200 · `/mcp` 405 |
+> | `Other`          | `site` + `door`        | `/` 200 · `/llms.txt` 200 · `/mcp` 405 |
+>
+> **One failure has been seen that none of this explains.** On a 205-document
+> record (2026-08-26, issue #197) the install ran, `ksor build` ran, every route
+> prerendered — and Vercel collected nothing. The deployment reported **Ready**,
+> took the production alias, and served `404: NOT_FOUND` at every path,
+> `llms.txt` included. The only signal anywhere was one build-log line:
+>
+> ```
+> WARNING! Build output contains no "functions" or "static" directory;
+> the build may not have produced any deployable output.
+> ```
+>
+> **Its cause is not established**, and that is written here rather than guessed
+> at, because a wrong cause costs the reader the evening the right one would
+> have saved. What is ruled out: the preset (above), and the project's own
+> `outputDirectory` / `buildCommand` / `installCommand` — patching all three,
+> confirming they read back, and taking a fresh Git-sourced production
+> deployment (not a redeploy, which reuses the original settings snapshot)
+> produced the same warning and the same 404.
+>
+> If you hit it, the one thing worth checking is the **Root Directory** above,
+> because it is the one mechanism known to make a build read a `vercel.json`
+> that is not there — though it normally fails LOUDLY, so it would be a
+> different shape of the same cause rather than a match. Then please add what
+> you saw to issue #197, with the deployment's `services` array from the API if
+> you can: empty means the block genuinely was not read, populated moves the
+> search elsewhere.
+>
+> **The fallback, if you need to ship before that is answered:** replace the
+> `services` block with the classic top-level keys.
+>
+> ```json
+> {
+>   "$schema": "https://openapi.vercel.sh/vercel.json",
+>   "installCommand": "pnpm install --no-frozen-lockfile",
+>   "buildCommand": "pnpm build",
+>   "outputDirectory": "system/site/out"
+> }
+> ```
+>
+> Verified live on the same repository and machine: root `200`, `llms.txt` with
+> every entry, deep pages `200`, `source_commit` stamped.
+>
+> **It moves the door off your domain, and two values have to move with it.**
+> The classic keys cannot express two services — which is the whole reason the
+> emitted file uses `services` — so dropping the block also drops the rewrites
+> for `/mcp`, `/health`, `/ready` and `/.well-known/oauth-protected-resource`.
+> The door is then deployed separately from the same `Dockerfile`, on its own
+> hostname, and `KSOR_MCP_RESOURCE_URL` plus the API Identifier registered with
+> your SSO provider must both name that new origin, character for character —
+> see [Authorization](./authorization.md), where a mismatch there is the failure
+> that costs an afternoon.
+>
+> This is `buildCommand: "pnpm build"`, so it is still the DEFAULT posture of
+> decision 29 — the host regenerates the lock on every deploy. The stricter one,
+> where the shipped `build_id` is a reviewed one, is a different command and is
+> [below](#the-site-build-runs-ksor-build-first).
+>
+> **Prefer the Git connection over `vercel deploy` while you work this out.** A
+> CLI upload excludes `.git`, so `ksor build` cannot resolve a commit and every
+> deploy publishes a record whose `build.lock.json` carries
+> `"source_commit": null` — on a product whose claim is governed provenance.
+> `build.lock.json` never spells it `unspecified`: that word is what the build
+> prints, on **stdout** with the rest of its summary, so a step that inspects
+> only stderr sees nothing at all. (`ksor ingest` is the other way round — a
+> generation stores the literal string `unspecified` in `ingestion_runs`.) The
+> Git path is the one that keeps the commit.
 
 The emitted `vercel.json` declares both services and routes between them:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "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/schema/migrations/2.2-2.3__takedown-writes-and-a-readable-ledger.sql

@@ -32,11 +32,14 @@ CREATE POLICY takedown_write ON takedown_denylist FOR ALL TO sor_content_ingest
                         AND g.tenant_id = takedown_denylist.tenant_id));
 
 -- ── retrieval_log: a role that can actually read the ledger ──────────────────
-DO $$
-BEGIN
-  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'sor_content_auditor') THEN
-    CREATE ROLE sor_content_auditor NOLOGIN;
-  END IF;
+-- Concurrency-tolerant for the same reason `schema.sql` is: roles are
+-- CLUSTER-GLOBAL, so `IF NOT EXISTS` is check-then-act across every database on
+-- the instance, and the loser raises `unique_violation` (23505) on
+-- pg_authid_rolname_index — not `duplicate_object` (42710). Two `ksor schema
+-- --apply` runs reach this migration exactly as they reach the fresh DDL.
+DO $$ BEGIN
+  CREATE ROLE sor_content_auditor NOLOGIN;
+EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
 END $$;
 
 GRANT USAGE ON SCHEMA public TO sor_content_auditor;

package/schema/schema.sql

@@ -324,12 +324,36 @@ CREATE TABLE ingest_tenant_grants (
     PRIMARY KEY (role_name, tenant_id)
 );
 
+-- Roles are CLUSTER-GLOBAL, so `IF NOT EXISTS` is check-then-act across every
+-- database on the instance: two concurrent applies both see the role absent and
+-- both create it. Measured on Postgres 17.7 — six concurrent runs against an
+-- empty cluster, FIVE failed. Two `ksor schema --apply` runs, or two `pnpm
+-- test:db` runs, are all it takes.
+--
+-- The raised SQLSTATE is `unique_violation` (23505) on pg_authid_rolname_index,
+-- NOT `duplicate_object` (42710) — catching only the latter is the intuitive
+-- fix and does not work. Both are caught, because which one surfaces depends on
+-- where in the create the loser lands.
+--
+-- ONE BLOCK PER ROLE, deliberately: a `DO` block is a single statement, so an
+-- exception anywhere in it rolls back the whole block. Three roles in one block
+-- means a loser on the first role never creates the other two, and the apply
+-- continues to GRANT against roles that do not exist.
+DO $$ BEGIN
+  CREATE ROLE sor_content_runtime NOLOGIN;
+EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+END $$;
+
+DO $$ BEGIN
+  CREATE ROLE sor_content_ingest NOLOGIN;
+EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+END $$;
+
+-- The ledger's READER (2.3). Without it retrieval_log was write-only under
+-- every credential ksor ships: FORCE RLS, an INSERT policy, and no way back in.
 DO $$ BEGIN
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_runtime') THEN CREATE ROLE sor_content_runtime NOLOGIN; END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_ingest')  THEN CREATE ROLE sor_content_ingest NOLOGIN;  END IF;
-  -- The ledger's READER (2.3). Without it retrieval_log was write-only under
-  -- every credential ksor ships: FORCE RLS, an INSERT policy, and no way back in.
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_auditor') THEN CREATE ROLE sor_content_auditor NOLOGIN; END IF;
+  CREATE ROLE sor_content_auditor NOLOGIN;
+EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
 END $$;
 
 -- Explicit in-schema membership for the APPLYING role, so SET LOCAL ROLE works from day one

package/templates/scaffold/AGENTS.md

@@ -76,10 +76,10 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    later means re-embedding the whole corpus. Keep `dim` at or below 2000 — the
    schema indexes a `vector` column directly and pgvector's HNSW takes a
    `vector` to 2000. `gemini-embedding-001` emits 3072 by default, so ksor asks
-   it for 1536. Google's published MTEB table runs 128–2048 and is flat at the
-   top of it — 1536 scores 68.17 against 2048's 68.16 — so there is no gradient
-   to climb toward the ceiling; going the other way, 768 costs 0.18 if you want
-   the storage back.
+   it for 1536, which the provider's own dimensionality table shows costs
+   nothing measurable against the ceiling — going the other way trades a little
+   quality for storage. Whether to move is priced in ksor's decision 30, which
+   carries the figures and their source.
 
    Leave `retrieval:` out for now — the gate is off and the server says so.
    Turning it on is step 4, AFTER the record is serving.

package/templates/scaffold/README.md

@@ -134,6 +134,15 @@ export, so nothing serves it at runtime. `pnpm preview` is `node:http` and
 nothing else — no dependency, no network fetch — so it works offline and behind
 a firewall, like the build itself.
 
+It binds loopback, so it is reachable from this machine only. To open the built
+site from a container published with `-p`, a cloud dev box, or a phone on the
+same wifi, name the address on the command line — `preview` is plain `node` and
+does not read `.env`:
+
+```sh
+KSOR_PREVIEW_HOST=0.0.0.0 pnpm preview
+```
+
 ---
 
 ## Serving to agents
@@ -274,8 +283,20 @@ declared`. The services ARE declared, in `vercel.json` at the repo root,
 3. **Set three environment variables** in Vercel: `KSOR_DB_URL`,
    `GEMINI_API_KEY`, and `KSOR_AUTH=disabled-public`.
 
-Two things catch people here, and both are the system being deliberate:
-
+Three things catch people here. Two are the system being deliberate; the first
+is not, and it is the one that fails without saying so:
+
+- **A deployment can report Ready and serve nothing.** The build succeeds,
+  Vercel collects nothing, and the deployment takes your domain and answers
+  `404: NOT_FOUND` everywhere — with one build-log line as the only signal:
+  `WARNING! Build output contains no "functions" or "static" directory`. Seen
+  once, on a large record, and **the cause is not established**; it is *not* the
+  Application Preset, which was measured. The emitted `vercel.json` itself is
+  verified working on the Git path. If you hit this, the fallback is the
+  classic-keys form in `node_modules/@panaversity/ksor/docs/deploying.md` — read
+  it there rather than guessing, because it **moves the door off your domain**
+  and `KSOR_MCP_RESOURCE_URL` and your SSO API Identifier both have to move with
+  it.
 - **`disabled-local` will not deploy.** The container sets `$PORT`, so the door
   binds `0.0.0.0` — a PUBLIC bind — and refuses that value by design, saying so
   in as many words. `disabled-public` is you saying you know the door is
@@ -595,7 +616,7 @@ map rather than a substitute.
 | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | `pnpm check` refuses a document                                      | `status: stable` without both `generated` and `ksor.approval`, or an approval earlier than the text it approves | add both keys; approval cannot precede what it approves                                |
 | `start` — missing script                                             | there is none: the site is a static export, so nothing serves it at runtime                                | `pnpm preview`, or upload the folder                                                   |
-| `pnpm preview` exits `3`                                             | there is no `system/site/out/` yet                                                                         | run the build first                                                                    |
+| `pnpm preview` exits `3`                                             | no `system/site/out/` yet, `PORT` is not a port number, the port is taken, or `KSOR_PREVIEW_HOST` cannot be bound — it says which | build first; or set a free `PORT` (`dev` uses 3000 too). `preview` binds loopback; set `KSOR_PREVIEW_HOST` to reach it from a container or another device |
 | `pnpm serve` refuses to boot                                         | it will not run unauthenticated by accident                                                                | `KSOR_AUTH=disabled-local` in `.env` for a loopback run                                |
 | the deployed or containerised door refuses with `disabled-local`     | it binds `0.0.0.0` — a public bind                                                                         | `KSOR_AUTH=disabled-public` in the host environment, or configure the SSO variables    |
 | the agent answers questions 2 and 3 instead of declining             | no floor is measured, so the gate is off (`abstain OFF`, `gate: "off"`) — step 3's `calibrate` was skipped  | `pnpm exec ksor calibrate --instance instance.md`, paste the block, restart             |

package/templates/scaffold/system/site/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "next build",
+    "build": "next build --webpack",
     "dev": "next dev"
   },
   "dependencies": {

package/templates/scaffold/system/site/preview.mjs

@@ -27,6 +27,15 @@ import process from "node:process";
 
 const ROOT = path.resolve(import.meta.dirname, "out");
 const PORT = Number(process.env.PORT ?? 3000);
+if (!Number.isInteger(PORT) || PORT < 1 || PORT > 65535) {
+  // `Number("abc")` is NaN and `listen(NaN)` binds an arbitrary free port while
+  // the log prints `http://localhost:NaN` — a server you cannot find. So do
+  // `Number("")` and `Number(" ")`, which are 0: an unset `PORT=` in a shell or
+  // a compose file is the common way to reach this, and `listen(0)` has exactly
+  // the same ending. Hence 1, not 0.
+  console.error(`preview: PORT must be a port number, got ${JSON.stringify(process.env.PORT)}`);
+  process.exit(3);
+}
 
 const TYPES = new Map([
   [".html", "text/html; charset=utf-8"],
@@ -52,13 +61,36 @@ try {
 
 /** The file a request resolves to, or null when it escapes the export. */
 function resolve(urlPath) {
-  const decoded = decodeURIComponent(urlPath.split("?")[0]);
-  // Contain every request inside the export: a `..` that resolves outside it
-  // is refused rather than served, even in a preview.
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath.split("?")[0]);
+  } catch {
+    // `decodeURIComponent` THROWS on a malformed escape — `/%`, `/%zz`, a
+    // truncated multi-byte sequence. Thrown from a request listener that is an
+    // uncaught exception, and the whole preview server exits: one `curl
+    // http://localhost:3000/%` took it down mid-review, leaving the adopter
+    // with a dead port and a stack trace instead of a page. A request we
+    // cannot parse is a request that resolves to nothing.
+    return null;
+  }
+  // Contain every request inside the export: a `..` that resolves outside it —
+  // raw or percent-encoded — is refused rather than served, even in a preview.
+  // The check is LEXICAL, so it bounds paths and not the filesystem: a symlink
+  // INSIDE `out/` still leads wherever it points, because `statSync` follows it
+  // and these are strings. A Next export authors no symlinks, so that is a
+  // stated limit rather than a known hole; `realpathSync` on the winner is what
+  // would close it if an export ever carries one.
   const target = path.resolve(ROOT, `.${decoded}`);
   if (target !== ROOT && !target.startsWith(ROOT + path.sep)) return null;
 
   for (const candidate of [target, path.join(target, "index.html"), `${target}.html`]) {
+    // `${target}.html` is the one candidate that can sit outside the check
+    // above: whenever the target IS the root — `/`, `/.`, `/x/..` — it names
+    // the sibling `out.html`. Reachable only when the export has no
+    // `index.html` (candidate 2 wins otherwise), which is why the test builds
+    // an export without one. Containment is asserted per candidate rather than
+    // once, so the shapes we try can never outrun the rule they are tried under.
+    if (candidate !== ROOT && !candidate.startsWith(ROOT + path.sep)) continue;
     try {
       if (statSync(candidate).isFile()) return candidate;
     } catch {
@@ -68,14 +100,69 @@ function resolve(urlPath) {
   return null;
 }
 
-createServer((req, res) => {
+/**
+ * Stream a file, and answer honestly when it cannot be read.
+ *
+ * `pipe()` attaches an 'error' listener to the DESTINATION, never to the
+ * source — so an error on the read stream has no listener and becomes an
+ * uncaught exception, which is how a malformed URL used to end this process.
+ * `statSync().isFile()` in `resolve()` does not make the later `open()` safe:
+ * the file can go between the two, and it does, in the ordinary loop this
+ * command exists for — the adopter leaves `preview` running and rebuilds in
+ * another pane, the export is torn down and rewritten, and an asset the open
+ * page re-requests is gone (`ENOENT`). A mode-000 file anywhere in the export
+ * is the same crash with no timing at all (`EACCES`, reproduced).
+ *
+ * The head is written on 'open', NOT before it. Writing it first meant an
+ * unreadable file answered `200` with an empty body and a valid terminating
+ * chunk — a complete, successful response carrying nothing, which a browser
+ * renders as a blank page and `fetch().text()` reports as `""`. That is the
+ * same silent lie this file exists to stop telling, moved one layer down.
+ * Once the head IS out there is no status left to send, so a failure part way
+ * through destroys the socket instead of ending it cleanly: a truncated
+ * response is what the client must see, because it is what happened.
+ */
+function send(res, file, status, type) {
+  const stream = createReadStream(file);
+  let headSent = false;
+  stream.on("open", () => {
+    headSent = true;
+    res.writeHead(status, { "content-type": type });
+    stream.pipe(res);
+  });
+  stream.on("error", (error) => {
+    console.error(`preview: could not read ${path.relative(ROOT, file)} — ${error.message}`);
+    if (headSent) {
+      res.destroy();
+      return;
+    }
+    // ONE message, and it does not claim the file is still there. `resolve()`
+    // has already stat'd every candidate, so a file that vanished before the
+    // request is answered 404 by the 404 path and never reaches here; what does
+    // reach here is EACCES, EISDIR, EMFILE, or an ENOENT that landed in the
+    // window between that stat and this open. A split by errno was tried and
+    // removed: the window cannot be raced by a test, so it was a branch nothing
+    // could show working.
+    res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+    res.end("500 — could not read that file; the preview log says why\n");
+  });
+  // A client that navigates away leaves the source with no consumer: `pipe()`
+  // unpipes on the destination's close but never destroys the readable, so
+  // 'end' never fires, `autoClose` never runs, and the fd leaks — one per
+  // cancelled image load.
+  res.on("close", () => stream.destroy());
+}
+
+const server = createServer((req, res) => {
   const file = resolve(req.url ?? "/");
   if (file === null) {
     const notFound = path.join(ROOT, "404.html");
     try {
-      statSync(notFound);
-      res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
-      createReadStream(notFound).pipe(res);
+      // `.isFile()`, the check `resolve()` already applies: `open()` succeeds on
+      // a DIRECTORY, so a directory named `404.html` used to write a head and
+      // then fail the first read.
+      if (!statSync(notFound).isFile()) throw new Error("not a file");
+      send(res, notFound, 404, "text/html; charset=utf-8");
       return;
     } catch {
       res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
@@ -83,11 +170,60 @@ createServer((req, res) => {
       return;
     }
   }
-  res.writeHead(200, {
-    "content-type": TYPES.get(path.extname(file)) ?? "application/octet-stream",
-  });
-  createReadStream(file).pipe(res);
-}).listen(PORT, () => {
-  console.log(`preview: serving ${path.relative(process.cwd(), ROOT)} on http://localhost:${PORT}`);
+  send(res, file, 200, TYPES.get(path.extname(file)) ?? "application/octet-stream");
+});
+
+// Loopback by default, and NOT hardcoded. An omitted host binds every
+// interface while the log below has always said `localhost`, so it now binds
+// where it says it binds. But that breaks the cases where reaching it from
+// elsewhere is the point — `docker run -p`, a cloud dev box addressed by IP,
+// or opening the built site on a phone on the same wifi — and those fail as a
+// refused connection, which reaches no process and so can document nothing.
+//
+// `KSOR_PREVIEW_HOST`, not `HOST`: the door already spells this
+// `KSOR_MCP_HOST`, so the bare word would be a second name for one concept
+// (working rule 8) — and tcsh and csh export `HOST` as the machine's hostname,
+// which would make `preview` stop working on those shells for a variable
+// nobody set on purpose.
+//
+// An EMPTY value binds every interface, because `listen(port, "")` takes
+// Node's falsy-host branch — the same shape `PORT` is guarded against, the
+// same as `PORT` above, and the same way to reach it (`KSOR_PREVIEW_HOST=` in a
+// shell or a compose file). So blank falls back to loopback rather than
+// silently widening what this file just narrowed.
+const HOST = (process.env.KSOR_PREVIEW_HOST ?? "").trim() || "127.0.0.1";
+
+let listening = false;
+server.on("error", (error) => {
+  // Errors are documentation. Without this an occupied port is a raw
+  // `EADDRINUSE` stack trace — and the port most likely to be occupied is
+  // 3000, which `dev` also defaults to, so "I ran preview after dev" is the
+  // common case rather than an edge one.
+  if (!listening) {
+    if (error.code === "EADDRINUSE") {
+      console.error(`preview: port ${PORT} is already in use — set PORT to a free one.`);
+      console.error("  `dev` uses 3000 too, so stop it first or run `PORT=3001 preview`.");
+    } else if (error.code === "EADDRNOTAVAIL") {
+      console.error(`preview: nothing here can bind ${HOST} — check KSOR_PREVIEW_HOST.`);
+    } else if (error.code === "EACCES") {
+      console.error(`preview: not allowed to bind ${HOST}:${PORT}.`);
+      console.error("  usually a port below 1024 — try PORT=3000 or another high one.");
+    } else {
+      console.error(`preview: could not listen on ${HOST}:${PORT} — ${error.message}`);
+    }
+    process.exit(3);
+  }
+  // AFTER it is up, an error is an accept-path condition (EMFILE and friends),
+  // and exiting on it would be the very thing this file exists to stop: one
+  // transient ending the session.
+  // Still serving, because reaching here at all means `listening` fired and
+  // nothing closes this server — an accept-path error does not.
+  console.error(`preview: ${error.message} — still serving.`);
+});
+
+server.listen(PORT, HOST, () => {
+  listening = true;
+  const shown = HOST === "127.0.0.1" ? "localhost" : HOST;
+  console.log(`preview: serving ${path.relative(process.cwd(), ROOT)} on http://${shown}:${PORT}`);
   console.log("  this is the STATIC EXPORT — the same bytes a host would serve.");
 });