@panaversity/ksor 0.0.21 → 0.0.23

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @panaversity/ksor
 
+## 0.0.23
+
+### Patch Changes
+
+- 6d306a2: Ship the deployment artifacts: `ksor init` now emits a `Dockerfile` and
+  `.dockerignore`, and its `vercel.json` declares both surfaces — the static site
+  and the MCP door — behind one domain.
+
+  The served MCP rung is a core surface, not an optional extra, so a scaffolded
+  project should be able to reach a host without anyone hand-writing a container
+  recipe first. The emitted `Dockerfile` names no vendor: it installs the pinned
+  `@panaversity/ksor`, honours `$PORT`, and runs `ksor serve`, so the same image
+  runs on Cloud Run, Fly, Render, ECS, Kubernetes or a VPS. `vercel.json` points
+  AT that file rather than replacing it, which is what keeps the host a choice —
+  moving is a redeploy, not a rewrite. A test asserts that neutrality directly,
+  and CI now builds the emitted image, boots it against real Postgres and asks it
+  a question over MCP, with no hosting vendor involved.
+
+  Verified live before shipping, and the verification paid for itself: a
+  project-level `trailingSlash: true` — harmless while the config was static-only
+  — 308-redirected every door route including `POST /mcp`. It is removed (the
+  site's own Next config already sets it where it belongs); shipping it would have
+  broken the MCP endpoint of every adopter who deployed.
+
+  Two new documents: `docs/deploying.md` (both surfaces onto a host, the
+  configuration each needs, and what a cold start costs — measured) and
+  `docs/ingesting.md` (why serving does not publish, so a first deploy with no
+  ingest serves an empty record; where ingest belongs, which is never inside the
+  container; and how the abstention gate gets turned on).
+
+  Also drops the scaffold's build-script denials for `@google/genai` and
+  `protobufjs`. The embedding provider speaks the vendor's REST API directly now,
+  so neither package is installed at all and the entries described a dependency
+  that no longer exists.
+
+## 0.0.22
+
+### Patch Changes
+
+- ef538fa: Stage the record under a lock, so a build that evaluates its config more than
+  once cannot publish a short site.
+
+  A site build evaluates `source.config.ts` in more than one process — seven of
+  them staged the record in one measured build — and staging was destructive on
+  every evaluation: delete the whole per-audience stage, refill it. Two of those
+  overlapping deleted a tree the other was copying into. Six
+  concurrent evaluations of a 150-document record failed 42 of 48 runs — `ENOENT`
+  and `EINVAL` out of `copyFileSync`, `ENOTEMPTY` out of `rmSync` despite its
+  retries, and, in 27 of the 48, no error at all: staging returned success and
+  handed the build a stage a third of the record short. That last shape is the one
+  that matters — a crash fails a build, a short stage publishes one, with
+  documents missing from `/docs`, `llms.txt` and the search index and nothing
+  saying so.
+
+  Staging now takes a lock file (`system/site/.staged-knowledge.lock`, gitignored,
+  stamped with the holder's pid so a killed build's lock is broken rather than
+  waited on), and an evaluation that finds the stage already holding exactly its
+  plan — byte for byte — leaves it alone instead of rebuilding it. Together those
+  mean the destructive path runs once per build, alone. No behaviour changes for a
+  build that was already succeeding.
+
 ## 0.0.21
 
 ### Patch Changes

package/dist/cli.mjs

@@ -9644,7 +9644,11 @@ function isEnvironmentError(value) {
 }
 //#endregion
 //#region src/init/materialize.ts
-const EMITTED_NAMES = /* @__PURE__ */ new Map([["gitignore", ".gitignore"], ["env.example", ".env.example"]]);
+const EMITTED_NAMES = /* @__PURE__ */ new Map([
+	["gitignore", ".gitignore"],
+	["env.example", ".env.example"],
+	["dockerignore", ".dockerignore"]
+]);
 const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
 	".md",
 	".json",

package/docs/deploying.md

@@ -0,0 +1,233 @@
+---
+title: Deploying
+status: draft
+---
+
+# Deploying a Knowledge System of Record
+
+A KSoR publishes two surfaces from one record, and they deploy differently
+because they are different things:
+
+| surface      | what it is                                       | how it deploys                         |
+| ------------ | ------------------------------------------------ | -------------------------------------- |
+| **the site** | a fully static export — HTML, `llms.txt`, search | upload a folder to any static host     |
+| **the door** | the MCP server, a live process reading Postgres  | run a container that listens on a port |
+
+`ksor init` emits everything both need: `Dockerfile` and `.dockerignore` for the
+door, and a `vercel.json` that puts the two behind one domain. This page is the
+walkthrough, executed rather than described.
+
+**Publishing is a third thing, and it is not on this page's critical path.**
+Neither surface ingests. The door serves whatever generation is already active
+in the database, and the site renders `knowledge/` from the repository. Getting
+content INTO the database is [ingesting.md](./ingesting.md), and it is a deploy
+step you run, never something a booting container does.
+
+## The shape
+
+```
+                     ┌───────────────────────────────┐
+   a reader  ────────▶  /            the site        │  static files
+                     │  /docs/…                      │
+                     ├───────────────────────────────┤
+   an agent  ────────▶  /mcp         the door        │  container ──▶ Postgres
+                     │  /health /ready               │
+                     │  /.well-known/oauth-…         │
+                     └───────────────────────────────┘
+```
+
+One domain, two services. An agent that finds `https://your-host/mcp` and a
+person who opens `https://your-host/` are reading the same record.
+
+## The container is the portable artifact
+
+The emitted `Dockerfile` names no host. It installs the pinned
+`@panaversity/ksor` from your `package.json`, honours `$PORT`, and runs
+`ksor serve`:
+
+```sh
+docker build -t my-record .
+docker run --rm -p 8080:80 --env-file .env my-record
+```
+
+That runs on Cloud Run, Fly, Render, ECS, Kubernetes, or a VPS with no changes.
+`vercel.json` **points at this same file** rather than replacing it, which is
+what keeps the host a choice — the artifact is yours, and moving it is a
+redeploy, not a rewrite.
+
+What the image deliberately does NOT contain (see `.dockerignore`):
+
+- **`.env`** — configuration arrives from the environment at run time. A DSN
+  baked into a layer is published to anyone who can pull the image.
+- **`knowledge/`** — the door reads Postgres. Copying the corpus in would
+  suggest the container reads it, and it never does.
+- **`system/`** — that is the other surface, built and hosted separately.
+
+## Deploying both surfaces to Vercel
+
+The emitted `vercel.json` declares both services and routes between them:
+
+```json
+{
+  "services": {
+    "site": { "root": ".", "buildCommand": "pnpm build", "outputDirectory": "system/site/out" },
+    "door": { "root": ".", "runtime": "container", "entrypoint": "Dockerfile" }
+  },
+  "rewrites": [
+    { "source": "/mcp(.*)", "destination": { "service": "door" } },
+    { "source": "/.well-known/oauth-protected-resource(.*)", "destination": { "service": "door" } },
+    { "source": "/health", "destination": { "service": "door" } },
+    { "source": "/ready", "destination": { "service": "door" } },
+    { "source": "/(.*)", "destination": { "service": "site" } }
+  ]
+}
+```
+
+Deploy from the repository **root**, never from `system/site/`:
+
+```sh
+vercel deploy --prod
+```
+
+Two things about this file are worth knowing before you edit it.
+
+**The catch-all must stay last.** Rewrites match in order, so a `/(.*)` rule
+moved above the door's routes silently sends `POST /mcp` to the static site,
+where it becomes a 404 and reads like the door is down.
+
+**Do not add a project-level `trailingSlash`.** The site's own Next config
+already sets it and exports `index.html` directories, so it buys nothing — and
+at the project level it applies to the door too, where it redirects `POST /mcp`
+to `/mcp/` with a 308. Found exactly that way: every door route 308ed until the
+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:
+
+```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.
+
+### The site build needs the DSN too
+
+Once `instance.md` declares a `database:` block, `pnpm build` runs
+`pnpm export-denylist` first — it asks the database what has been withdrawn and
+writes `.ksor-denylist.json`. Without `KSOR_DB_URL` the build **refuses**:
+
+```
+KSOR_DB_URL is unset, and instance.md declares a database
+  why: a takedown lives in that database. Without it this build cannot tell
+       'nothing is denied' from 'nobody asked'
+```
+
+That refusal is the design working. A takedown reaches the door instantly (it is
+a row) and reaches the site at its next build (it reads a file), so a site built
+without the DSN would keep publishing what the door already refuses. Set
+`KSOR_DB_URL` on the site build as well as on the door.
+
+## Authorization, or the deliberate absence of it
+
+`ksor serve` **refuses to boot unauthenticated on a public bind.** There is no
+auth-off default, and that refusal is the last real step of a deployment. Two
+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
+  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.
+
+Check which one you got. `/health` says so plainly:
+
+```json
+{
+  "corpus_id": "book",
+  "abstain_gate": "OFF (no floor declared — will not refuse out-of-corpus questions)",
+  "embedding_space": "gemini-embedding-001/d1536 ok",
+  "auth": "disabled"
+}
+```
+
+`"auth":"disabled"` on a public host means the second option is in effect.
+
+## What a cold start costs
+
+The door is built for a runtime that suspends it. It holds **no idle database
+connections** — the pool minimum is 0 and an unused connection closes after 10s
+— so a quiet instance keeps nothing open against a serverless Postgres, and the
+first request after a suspend both wakes the database and retries the connect
+rather than failing.
+
+Measured against a live deployment on Vercel, Neon behind it, an 81-document
+record of 6,963 chunks:
+
+|                                        |           |
+| -------------------------------------- | --------- |
+| warm request                           | **~1.7s** |
+| cold start (container + database wake) | **~9.1s** |
+
+Most of the cold number is the two wakes, not ksor. If that matters for your
+readers, the levers are your host's minimum instance count and your database's
+suspend delay — both outside this tool.
+
+`SIGTERM` drains and exits within 8s (`KSOR_DRAIN_TIMEOUT_MS`), inside the ~10s
+a scale-to-zero runtime usually allows before `SIGKILL`.
+
+## Verifying a deployment
+
+In order, because each answers a different question:
+
+```sh
+B=https://your-host
+
+curl -s $B/health          # the door booted, and on which posture
+curl -s $B/ready           # the database answers
+curl -s -o /dev/null -w '%{http_code}\n' $B/   # the site is served
+
+curl -s -X POST $B/mcp \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
+       "protocolVersion":"2025-11-25","capabilities":{},
+       "clientInfo":{"name":"probe","version":"1"}}}'
+```
+
+If `/health` answers but a search returns nothing, the door is fine and the
+**record was never published** — go to [ingesting.md](./ingesting.md). A first
+deploy with no ingest serves an empty record, which is the single most common
+"it deployed but does not work".
+
+If `/mcp` returns HTML, the catch-all rewrite is matching before the door's
+route.
+
+## Deploying anywhere else
+
+Nothing above is Vercel-specific except `vercel.json`. On any other host:
+
+1. Build the site — `pnpm build` — and upload `system/site/out/` as static files.
+2. Build and run the container, giving it the environment above.
+3. Put the door at `/mcp` on the same domain, or a different one; if it is a
+   different domain, set `KSOR_MCP_RESOURCE_URL` to the door's real URL, since
+   that value is the record's identity in a token's audience, not a guess.

package/docs/index.md

@@ -32,6 +32,14 @@ instead of their training memory. The corpus grows with each implemented verb.
   export the manifest the site build reads), `ksor calibrate` (measure the
   abstention floor) and `ksor gc` (reap retired generations). Only `ksor dev` and `ksor build` remain designed, not
   implemented: each prints an honest notice and exits `2`.
+  - **[deploying.md](./deploying.md)** — getting both surfaces onto a host. The
+    scaffold emits a `Dockerfile` that names no vendor, and a `vercel.json` that
+    points at it to put the site and the MCP door behind one domain. Includes
+    what a cold start costs, measured.
+  - **[ingesting.md](./ingesting.md)** — publishing the record and keeping it
+    current. Serving does not publish, so a first deploy with no ingest serves
+    an empty record; this is the page that explains why, where ingest belongs
+    (never inside the container), and how the abstention gate gets turned on.
   - **[authorization.md](./authorization.md)** — putting the record behind an
     authorization server, with worked recipes for two of them, executed rather
     than written. `ksor serve` refuses to boot unauthenticated on a public bind,

package/docs/ingesting.md

@@ -0,0 +1,159 @@
+---
+title: Ingesting
+status: draft
+---
+
+# Publishing the record — `ksor ingest`
+
+Serving does not publish. That split is deliberate and it is the thing most
+worth understanding before a first deployment: `ksor serve` opens a port against
+whatever generation is already active, and `ksor ingest` is what makes a
+generation exist. A container that ingested on boot would pay the whole record's
+embedding cost on every cold start and would need write credentials at runtime.
+
+So **a first deploy with no ingest serves an empty record.** It is not broken;
+nothing was ever published to it.
+
+## The order, once
+
+```sh
+pnpm provision   # ksor schema --apply, then ksor grant
+pnpm refresh     # ksor ingest --flip, then ksor gc
+```
+
+`provision` is separate because applying DDL and granting ingest are acts an
+operator performs, not side effects of starting a server. Both are re-runnable
+and report what they found — an applied schema says "already applied", an
+existing grant says "already granted".
+
+Then, after every change to `knowledge/`:
+
+```sh
+pnpm refresh
+```
+
+## What a generation is
+
+Each ingest builds a **fresh generation** — invisible until activated — and
+carries every unchanged embedding forward from the last complete one, matched by
+content hash. Only changed or previously-failed chunks are re-embedded.
+
+`--flip` swaps the active pointer. The previous generation stays as a rollback
+target; `ksor gc` reaps the ones nothing points at any more.
+
+Three consequences worth knowing:
+
+- **Re-ingest is cheap.** An ordinary edit makes a handful of provider calls,
+  not a corpus-worth.
+- **An unchanged record costs nothing at all.** Ingest compares what it just
+  read against the generation already serving and, when they are identical at
+  the same commit, consumes no generation and writes no rows:
+  `unchanged — generation N already serves this corpus`.
+- **Reordering is free.** Changing `order:` frontmatter re-ingests with no
+  embedding at all; only the ordering moved.
+
+A flip that would drop more than `KSOR_MAX_SHRINK` of the record (default
+`0.15`, i.e. 15%) **refuses**. When a large deletion is intended, say so:
+`KSOR_ALLOW_SHRINK=1`.
+
+## Where ingest runs — not on the host
+
+Ingest is a long job. It embeds every new chunk through the provider, and that
+is bounded by the provider's throughput rather than by anything ksor does.
+
+**Measured:** an 81-document book — 6,963 chunks — took **about 50 minutes**
+against a remote Postgres on a first, cold ingest with nothing to carry forward.
+
+Compare that with the request timeouts of the platforms people reach for first:
+a serverless function caps out in the region of 300–800 seconds depending on
+plan. Ingest is **an order of magnitude past that**, so it cannot be a route, a
+build step, or anything else the platform is allowed to kill.
+
+Run it where nothing is watching a clock:
+
+- **From your machine**, with `KSOR_DB_URL` pointing at the deployment's
+  database. This is the honest default for a record one person maintains.
+- **From CI**, as a job triggered on changes to `knowledge/` — the right shape
+  once more than one person edits, because it makes publishing an auditable
+  event rather than something someone did locally.
+
+It does not matter whether the process that ingests is the process that serves.
+They meet in the database and nowhere else.
+
+### If an ingest is interrupted
+
+Nothing is corrupted — an unactivated generation is invisible by construction.
+Run it again. The next attempt finds the incomplete generation's work and
+carries forward everything that was already embedded, including from a
+generation that was still `building` when it died, so a resumed run pays only
+for what the first one had not reached.
+
+## Endpoints, poolers, and what actually matters
+
+If your provider offers both a **pooled** and a **direct** endpoint (Neon's
+`-pooler` host, or anything on port 6432), ksor detects which one you gave it
+and says so in the boot report. That line is **informational**: it classifies,
+it never transforms. The hazard it descends from — a transaction pooler and
+server-side prepared statements — cannot arise here, because node-postgres does
+not auto-prepare.
+
+For the record: the 6,963-chunk ingest above ran through a **pooled** endpoint
+without incident, and the same DSN serves. Use whichever your provider gives
+you, and reach for the direct endpoint only if you actually hit pooler
+connection limits under a parallel ingest — not pre-emptively.
+
+`KSOR_DB_POOLED_ENDPOINT=1` forces the classification when your host name does
+not announce itself.
+
+## Turning the abstention gate on
+
+This is a separate act, done once, **after** the record is serving — because it
+is a measurement of this corpus in this embedding space, and there is nothing to
+measure until the corpus is in there.
+
+```sh
+pnpm exec ksor calibrate --instance instance.md
+```
+
+It prints a recommended `vector_floor`. Paste it in with the date you measured
+it, and restart:
+
+```yaml
+retrieval:
+  vector_floor: 0.55 # measured by ksor calibrate on 2026-08-23
+```
+
+Until you do, `/health` reports the gate as `OFF (no floor declared — will not
+refuse out-of-corpus questions)` and every search envelope carries
+`gate: "off"`. That is honest absence, and an agent reading the envelope knows
+an answer is not evidence of coverage.
+
+**Never copy a floor from another corpus.** The number means nothing away from
+the corpus and embedding space it was measured in.
+
+If calibrate reports `NOT separable`, read what it names underneath: it lists
+the out-of-corpus probes that scored at or above your weakest in-corpus
+question. Usually one of them is a question your record actually answers, and it
+belongs on the in-corpus side — moving it separates the measurement. Sometimes
+it is a genuine near-miss the corpus cannot separate, and then the floor
+correctly stays uncalibrated.
+
+## Withdrawing a document
+
+A takedown is a row, not a file, so it reaches the door immediately:
+
+```sh
+pnpm exec ksor takedown --instance instance.md <stable-id> \
+  --reason "legal request 2026-08" --actor "j.smith"
+```
+
+`--actor` is required, and there is no default. A name taken from the
+environment reads like a person and is whatever the shell happened to be
+(`runner` under CI, `root` in a container) — worse than no name at all in the
+one row that exists to record who did this.
+
+**The site stops at its next build.** It reads `.ksor-denylist.json`, which
+`pnpm build` refreshes via `pnpm export-denylist`. So after a takedown, rebuild
+and redeploy the site, or the human surface keeps publishing what the agent
+surface already refuses. See [deploying.md](./deploying.md) for why that build
+needs `KSOR_DB_URL`.

package/package.json

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

package/templates/scaffold/AGENTS.md

@@ -356,6 +356,35 @@ refuses rather than publish a document someone took down.
 behind that audience's own access control, never on a public host.
 Details in README → Deploying.
 
+### The MCP door is a container
+
+The other surface is a live process, so it ships as one. `Dockerfile` and
+`.dockerignore` are yours, at the repo root, and they name no host:
+
+```sh
+docker build -t my-record .
+docker run --rm -p 8080:80 --env-file .env my-record
+```
+
+That image runs on Cloud Run, Fly, Render, ECS, Kubernetes or a VPS unchanged.
+`vercel.json` declares BOTH surfaces — a `site` service built from
+`system/site/out/` and a `door` service pointing at that same `Dockerfile` —
+with rewrites putting the door on `/mcp`, `/health`, `/ready` and the
+`/.well-known/oauth-protected-resource` document, and the site on everything
+else. Two rules if you edit it: the `/(.*)` catch-all must stay LAST, and do
+not add a project-level `trailingSlash` — the site's Next config already sets
+it, and at project level it 308-redirects `POST /mcp`, which breaks the door.
+
+The image deliberately excludes `.env` (a baked DSN is published to anyone who
+can pull the image), `knowledge/` (the door reads Postgres, never the folder)
+and `system/` (the other surface).
+
+**Deploying does not publish.** A container that ingested on boot would pay the
+whole record's embedding cost on every cold start and need write credentials at
+runtime. So `pnpm refresh` is a DEPLOY step you run — from your machine or from
+CI — and a first deploy without it serves an empty record. Full walkthrough:
+`node_modules/@panaversity/ksor/docs/deploying.md` and `…/docs/ingesting.md`.
+
 ## Writing knowledge
 
 - One document per file under `knowledge/`; the path is the document's

package/templates/scaffold/Dockerfile

@@ -0,0 +1,36 @@
+# The MCP door, as an ordinary container.
+#
+# Nothing here names a host. It installs the pinned `@panaversity/ksor` from
+# package.json, listens on $PORT, and runs `ksor serve` — which is all Cloud Run,
+# Fly, Render, ECS, Kubernetes or a plain VPS asks for. `vercel.json` points AT
+# this file rather than replacing it, so the artifact stays portable and the host
+# stays a choice.
+#
+# Build and run it anywhere:
+#   docker build -t my-record .
+#   docker run --rm -p 8080:80 --env-file .env my-record
+#
+# This image serves; it does not publish. `ksor ingest` is a write plane that
+# runs from CI or your machine against the same database — see the deployment
+# guide in node_modules/@panaversity/ksor/docs/deploying.md.
+
+FROM node:24-alpine
+
+WORKDIR /app
+
+# Only the manifest first, so this layer caches until the ksor pin changes.
+COPY package.json ./
+RUN npm install --omit=dev --no-audit --no-fund
+
+# The record's identity and configuration. The CORPUS is deliberately absent:
+# the door serves from Postgres, and knowledge/ belongs to the build that
+# published it — see .dockerignore.
+COPY instance.md ./
+
+# Most container hosts inject PORT; 80 is a sane default when nothing does.
+ENV PORT=80
+EXPOSE 80
+
+# `ksor serve` refuses to boot unauthenticated on a public bind. That posture
+# belongs to the record, not to the host, so it travels inside the image.
+CMD ["node_modules/.bin/ksor", "serve", "--instance", "instance.md"]

package/templates/scaffold/README.md

@@ -60,6 +60,43 @@ unauthenticated: a local run declares `KSOR_AUTH_DISABLED=1` (already in
 a public bind needs a configured SSO door instead. Any other operation is
 `pnpm exec ksor <verb>`.
 
+### Test the agent surface with an actual agent
+
+The MCP door is meant to be read by agents, so check it with one rather than
+with `curl`. With `pnpm serve` running, write `.mcp.json` at the repo root:
+
+```json
+{
+  "mcpServers": {
+    "test-record": {
+      "type": "http",
+      "url": "http://127.0.0.1:8080/mcp"
+    }
+  }
+}
+```
+
+Open a new session of your coding agent, confirm it lists the server, then ask
+it three questions **in this order** — the order is the test:
+
+1. Something the record covers, **phrased in words the document never uses**.
+   Retrieval is semantic, so this should still find it, and every answer should
+   arrive with a citation.
+2. Something **adjacent but not covered** — your record's own subject area, a
+   question it genuinely does not answer. It should decline.
+3. Something far outside the record. It should decline, and must not answer
+   from its own knowledge.
+
+Question 2 is the one that matters. Anything can answer questions it has the
+text for; refusing a plausible near-miss is the property that makes a system of
+record worth trusting, and it is the one that breaks quietly.
+
+**On a fresh record, 2 and 3 will not refuse — and that is honest, not broken.**
+The abstention gate is off until you measure a floor for this corpus, which the
+server says out loud at boot (`abstain OFF`) and in every search envelope
+(`gate: "off"`). Run `pnpm exec ksor calibrate --instance instance.md` first if
+you want to test refusal. Delete `.mcp.json`, or keep it — it holds no secret.
+
 Then talk to your coding agent — `AGENTS.md` carries the working rules, and
 the agent kit in `.agents/skills/` knows how to interview you
 (`intake-interview`), convert your source material (`add-sources`), and keep
@@ -118,7 +155,9 @@ and anything that can serve files can serve it.
 - **Vercel** — connect the repository (or run `vercel`); the shipped
   `vercel.json` answers the setup interview: deploy from the repo root
   (never pin `system/site` as the root directory — the record lives
-  outside it), build with `pnpm build`, serve `system/site/out/`. If the
+  outside it), build with `pnpm build`, serve `system/site/out/`. It also
+  declares the MCP **door** as a second service built from the shipped
+  `Dockerfile`, so `/mcp` and the site share one domain. If the
   build image's pnpm predates the `packageManager` pin, set the
   `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
 **Once `instance.md` declares a `database:`, the BUILD needs the DSN too.**
@@ -143,6 +182,24 @@ writes "nothing denied" and exits 0.
 - **Verify any deploy** the same way: the home page, one document page,
   and `/llms.txt` all load; nothing else is required.
 
+### The agent surface deploys separately
+
+The site is files; the MCP door is a process. `Dockerfile` and `.dockerignore`
+at the repo root build it, and they name no host — the same image runs on
+Cloud Run, Fly, Render, ECS, Kubernetes or a VPS:
+
+```sh
+docker build -t my-record .
+docker run --rm -p 8080:80 --env-file .env my-record
+```
+
+One thing surprises people: **deploying does not publish.** The door serves
+whatever generation is already in the database, so a first deploy with no
+`pnpm refresh` serves an empty record. Publishing is a step you run — from your
+machine or from CI — and it is deliberately not something a booting container
+does. The full walkthrough, including what a cold start costs and where ingest
+belongs, is in `node_modules/@panaversity/ksor/docs/deploying.md`.
+
 If `instance.md` declares `audiences:`, what you deploy is a **tier**.
 Plain `pnpm build` always builds the public tier — safe for any host.
 `KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier for that

package/templates/scaffold/dockerignore

@@ -0,0 +1,26 @@
+# Keep the serving image to what serving needs.
+
+# Secrets. The image takes its configuration from the environment at RUN time;
+# baking a .env into a layer publishes it to anyone who can pull the image.
+.env
+.env.*
+!.env.example
+
+# The corpus. The door serves from Postgres — knowledge/ was published by
+# `ksor ingest` before this container ever started, and copying it in would
+# suggest the container reads it. It does not.
+knowledge/
+
+# The website. It is the OTHER surface, built and hosted separately.
+system/
+
+# Build and tooling noise.
+node_modules/
+.git/
+.github/
+.agents/
+.claude/
+.gemini/
+*.log
+.DS_Store
+.ksor-denylist.json

package/templates/scaffold/gitignore

@@ -8,6 +8,9 @@ system/site/out/
 # the per-audience copy of the record a build stages — a filtered derivative,
 # never a second record; committing it would publish what a build excluded
 system/site/.staged-knowledge/
+# and the lock that keeps one evaluation of a build staging at a time; it only
+# outlives a build that was killed mid-stage, and the next build clears it
+system/site/.staged-knowledge.lock
 *.tsbuildinfo
 
 # secrets never enter the record — system/ is their future home (serve)

package/templates/scaffold/pnpm-workspace.yaml

@@ -19,17 +19,13 @@ minimumReleaseAgeExclude:
 # Dependency install scripts are denied by default. Flip an entry to true
 # only with a comment naming what breaks without it. pnpm 11 exits 1 on every
 # install until each build script is explicitly decided (found live:
-# fresh-scaffold pnpm dev, 2026-08-18). All four below are reviewed and stay
-# denied:
+# fresh-scaffold pnpm dev, 2026-08-18). Both below are reviewed and stay denied:
 #   esbuild, sharp — prebuilt platform binaries ship as optionalDependencies,
 #     so their install scripts are download fallbacks the site never needs.
-#   @google/genai, protobufjs — pulled in by the `@panaversity/ksor` serve
-#     tool. genai's flagged script is its own dev `prepare` (nothing the
-#     published tarball needs built); protobufjs's postinstall is a
-#     version-compat warning, nothing built. (Same review as the root
-#     workspace, 2026-08-19; serve works with both denied — verified live.)
+#
+# `@google/genai` and `protobufjs` were listed here too, as deps of the serve
+# tool. The embedding provider now speaks the vendor's REST API directly, so
+# neither package is installed at all and denying them described nothing.
 allowBuilds:
   esbuild: false
   sharp: false
-  "@google/genai": false
-  protobufjs: false

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

@@ -1,11 +1,13 @@
 import {
   copyFileSync,
+  existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
   rmSync,
   statSync,
   watch,
+  writeFileSync,
 } from "node:fs";
 import path from "node:path";
 
@@ -343,47 +345,191 @@ function planStage(recordDir: string, denied: DenylistManifest): StagePlan {
   return { files: [...documents, ...assets], documents: documents.length, total };
 }
 
+/** How often a waiter looks again. */
+const LOCK_POLL_MS = 25;
+/** How long a wait goes unexplained. A build that looks hung must say why. */
+const LOCK_ANNOUNCE_MS = 10_000;
+
+/** Synchronous, because everything on this path is: a bundler cannot await. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM is a process that exists and is not ours to signal.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Is this lock abandoned — stamped with a process that no longer exists?
+ *
+ * Blank is the one ambiguous read: the holder writes its pid in the same call
+ * that creates the file, so a blank lock is either a holder caught between the
+ * two (microseconds) or one that died there (forever). Looking twice tells
+ * them apart, and only the second look may break a lock.
+ */
+function lockIsAbandoned(lockFile: string): boolean {
+  for (const look of [0, 1]) {
+    let stamp: string;
+    try {
+      stamp = readFileSync(lockFile, "utf8").trim();
+    } catch {
+      // Released while we read it; the next acquire attempt takes it.
+      return false;
+    }
+    const pid = Number(stamp);
+    if (Number.isInteger(pid) && pid > 0) return !isAlive(pid);
+    if (look === 0) sleepSync(LOCK_POLL_MS * 2);
+  }
+  return true;
+}
+
+/**
+ * Hold the stage lock for the duration of `work`: ONE evaluation writes the
+ * stage at a time, and this file says which.
+ *
+ * A build evaluates `source.config.ts` in more than one process — SEVEN of
+ * them staged the record in one measured `next build` of a scaffolded site
+ * (2026-08-23) — and staging was destructive on every evaluation: delete the
+ * whole stage, refill it. Two of those overlapping is not a rare interleaving,
+ * it is what seven of them do — six concurrent evaluations of a 150-document
+ * record failed 42 of 48 runs, in four shapes: `ENOENT` and `EINVAL` out of `copyFileSync` (the reported one,
+ * issue #100), `ENOTEMPTY` out of `rmSync` *with* its retries already in
+ * place, and — 27 of the 48, the majority — no error at all: staging returned
+ * success and handed the build a stage a third of the record short.
+ *
+ * The silent shape is why this is a lock and not another retry. A crash fails
+ * a build; a short stage PUBLISHES one, with documents missing from /docs,
+ * llms.txt and the search index, and nothing anywhere saying so.
+ *
+ * `wx` is the whole primitive: create-if-absent, atomically, on every
+ * filesystem Node supports — and it stamps the holder's pid in the same call,
+ * so a waiter can tell a live holder from a killed one.
+ *
+ * Waiting on a LIVE holder is unbounded on purpose: it is another evaluation
+ * of the same build, staging the same bytes from the same record, and this
+ * build is not finished until it has. Unbounded is not silent, though — a wait
+ * long enough to look like a hang names what it is waiting for.
+ */
+function withStageLock<T>(stageDir: string, work: () => T): T {
+  const lockFile = `${stageDir}.lock`;
+  let waited = 0;
+  let announced = false;
+  for (;;) {
+    try {
+      writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (lockIsAbandoned(lockFile)) {
+        rmSync(lockFile, { force: true });
+        continue;
+      }
+      sleepSync(LOCK_POLL_MS);
+      waited += LOCK_POLL_MS;
+      if (waited >= LOCK_ANNOUNCE_MS && !announced) {
+        announced = true;
+        console.warn(
+          `[ksor] waiting on ${path.basename(lockFile)} — another evaluation of this build is ` +
+            "staging the record. Delete that file if no build is running.",
+        );
+      }
+    }
+  }
+  try {
+    return work();
+  } finally {
+    rmSync(lockFile, { force: true });
+  }
+}
+
 /**
  * Remove the stage, asking for the retries this exact failure needs.
  *
- * `force: true` suppresses ENOENT; it does NOT retry anything. Node retries
- * EBUSY / EMFILE / ENFILE / ENOTEMPTY / EPERM only when `maxRetries` is set,
- * and it defaults to zero. The build evaluates `source.config.ts` more than
- * once when the bundler wants it in more than one place, so two runs can
- * overlap: one removing the stage while the other is still copying into it.
- * That surfaced as `ENOTEMPTY` out of `rmSync` and failed the whole site build
- * (CI, 2026-08-21) — a race that is safe to lose, because the stage is a
- * deterministic function of the record and the denylist, so redoing it produces
- * the same bytes.
+ * Callers hold the stage lock, so no OTHER evaluation is writing here — but
+ * `force: true` suppresses ENOENT and does NOT retry anything, and Node
+ * retries EBUSY / EMFILE / ENFILE / ENOTEMPTY / EPERM only when `maxRetries`
+ * is set (it defaults to zero). Those are what a Windows indexer or an
+ * antivirus scanner holding a handle looks like — not ksor, and not something
+ * the lock can serialise. Losing that race is safe: the stage is a
+ * deterministic function of the record and the denylist, so redoing it
+ * produces the same bytes.
  */
 function removeStage(stageDir: string): void {
   rmSync(stageDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
 }
 
-/** Fill a clean stage with exactly the set this build may publish. */
-function fillStage(recordDir: string, stageDir: string, denied: DenylistManifest): void {
-  // The old stage goes first, before any refusal can throw: a refused build
-  // that leaves the previous, more permissive stage on disk hands the next
-  // careless build a filtered copy nothing governs (review finding,
-  // 2026-08-19).
-  removeStage(stageDir);
-  const plan = planStage(recordDir, denied);
-  // An empty record is its own problem, reported by the page that renders it;
-  // an empty AUDIENCE is a misconfiguration that would otherwise surface as
-  // "the record has no documents" against a record full of them.
-  if (plan.documents === 0 && plan.total > 0) {
-    refuse(
-      "ksor-audience-empty",
-      `no document in the record is visible to the ${buildAudience} build (${plan.total} document${plan.total === 1 ? "" : "s"}, all above that tier)`,
-      "a site with nothing on it is a deploy that looks successful and serves nobody — and the record is not empty, this audience's slice of it is",
-      "build a wider audience with KSOR_AUDIENCE, lower default_visibility in instance.md, or give at least one document this tier",
-    );
+/**
+ * Does the stage already hold EXACTLY this plan, byte for byte?
+ *
+ * The wipe-and-refill is the destructive half of staging, and it is pure waste
+ * whenever the answer is yes — which is every evaluation after the first in
+ * one build, since the plan is a deterministic function of the record and the
+ * denylist. Skipping it is not an optimisation: while a wipe is running there
+ * is a window in which the stage is not the record, and an evaluation that has
+ * already returned is reading it. The lock stops two writers colliding; this
+ * stops the second writer existing at all.
+ *
+ * Bytes, not names and not timestamps: the alternative is serving a previous
+ * build's copy of a document that has since been edited.
+ */
+function stageHolds(recordDir: string, stageDir: string, plan: StagePlan): boolean {
+  let staged: string[];
+  try {
+    staged = walkFiles(stageDir);
+  } catch {
+    return false;
   }
-  for (const from of plan.files) {
-    const to = path.join(stageDir, path.relative(recordDir, from));
-    mkdirSync(path.dirname(to), { recursive: true });
-    copyFileSync(from, to);
+  if (staged.length !== plan.files.length) return false;
+  const expected = new Map(
+    plan.files.map((from) => [path.join(stageDir, path.relative(recordDir, from)), from]),
+  );
+  for (const file of staged) {
+    const from = expected.get(file);
+    if (from === undefined) return false;
+    if (!readFileSync(from).equals(readFileSync(file))) return false;
   }
+  return true;
+}
+
+/** Fill a clean stage with exactly the set this build may publish. */
+function fillStage(recordDir: string, stageDir: string, denied: DenylistManifest): void {
+  withStageLock(stageDir, () => {
+    let plan: StagePlan;
+    try {
+      plan = planStage(recordDir, denied);
+      // An empty record is its own problem, reported by the page that renders
+      // it; an empty AUDIENCE is a misconfiguration that would otherwise
+      // surface as "the record has no documents" against a record full of them.
+      if (plan.documents === 0 && plan.total > 0) {
+        refuse(
+          "ksor-audience-empty",
+          `no document in the record is visible to the ${buildAudience} build (${plan.total} document${plan.total === 1 ? "" : "s"}, all above that tier)`,
+          "a site with nothing on it is a deploy that looks successful and serves nobody — and the record is not empty, this audience's slice of it is",
+          "build a wider audience with KSOR_AUDIENCE, lower default_visibility in instance.md, or give at least one document this tier",
+        );
+      }
+    } catch (error) {
+      // No refusal may leave the previous, more permissive stage on disk: it
+      // hands the next careless build a filtered copy nothing governs (review
+      // finding, 2026-08-19). The removal used to lead this function, which is
+      // why nothing could ask whether the stage was already correct.
+      removeStage(stageDir);
+      throw error;
+    }
+    if (stageHolds(recordDir, stageDir, plan)) return;
+    removeStage(stageDir);
+    for (const from of plan.files) {
+      const to = path.join(stageDir, path.relative(recordDir, from));
+      mkdirSync(path.dirname(to), { recursive: true });
+      copyFileSync(from, to);
+    }
+  });
 }
 
 /**
@@ -421,13 +567,17 @@ function refuseVisibilityWithoutAudiences(recordDir: string): void {
  * published build is always staged from scratch.
  */
 function refreshStage(recordDir: string, stageDir: string, denied: DenylistManifest): void {
-  const permitted = new Set(planStage(recordDir, denied).files);
-  for (const staged of walkFiles(stageDir)) {
-    const from = path.join(recordDir, path.relative(stageDir, staged));
-    if (!permitted.has(from)) continue;
-    if (readFileSync(from).equals(readFileSync(staged))) continue;
-    copyFileSync(from, staged);
-  }
+  // Under the lock like every other write here: a save landing while another
+  // evaluation is refilling the stage is the same race from the other side.
+  withStageLock(stageDir, () => {
+    const permitted = new Set(planStage(recordDir, denied).files);
+    for (const staged of walkFiles(stageDir)) {
+      const from = path.join(recordDir, path.relative(stageDir, staged));
+      if (!permitted.has(from)) continue;
+      if (readFileSync(from).equals(readFileSync(staged))) continue;
+      copyFileSync(from, staged);
+    }
+  });
 }
 
 let watching = false;
@@ -484,8 +634,11 @@ export function knowledgeSourceDir(): string {
     // Nothing to filter — serve the record itself, the level-0 fast path.
     // A stage left behind by an earlier model would be a filtered copy of the
     // record nothing governs any more — removed before the refusal below can
-    // throw, so a refused build never leaves one behind either.
-    removeStage(stageDir);
+    // throw, so a refused build never leaves one behind either. Under the lock,
+    // because two evaluations removing one tree is the `ENOTEMPTY` shape of the
+    // same race; the existence check keeps a record that never stages from
+    // taking a lock on every build.
+    if (existsSync(stageDir)) withStageLock(stageDir, () => removeStage(stageDir));
     refuseVisibilityWithoutAudiences(recordDir);
     return RECORD_DIR;
   }

package/templates/scaffold/vercel.json

@@ -1,8 +1,26 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
-  "framework": null,
-  "installCommand": "pnpm install --no-frozen-lockfile",
-  "buildCommand": "pnpm build",
-  "outputDirectory": "system/site/out",
-  "trailingSlash": true
+  "services": {
+    "site": {
+      "root": ".",
+      "installCommand": "pnpm install --no-frozen-lockfile",
+      "buildCommand": "pnpm build",
+      "outputDirectory": "system/site/out"
+    },
+    "door": {
+      "root": ".",
+      "runtime": "container",
+      "entrypoint": "Dockerfile"
+    }
+  },
+  "rewrites": [
+    { "source": "/mcp(.*)", "destination": { "service": "door" } },
+    {
+      "source": "/.well-known/oauth-protected-resource(.*)",
+      "destination": { "service": "door" }
+    },
+    { "source": "/health", "destination": { "service": "door" } },
+    { "source": "/ready", "destination": { "service": "door" } },
+    { "source": "/(.*)", "destination": { "service": "site" } }
+  ]
 }