@panaversity/ksor 0.0.52 → 0.0.54

package/dist/{gateway-api-Ck1l_Sgs-B-_wMYLB.mjs → gateway-api-uhx2l1kC-C2BAxISt.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-Ck1l_Sgs.mjs
+//#region ../content-gateway/dist/gateway-api-uhx2l1kC.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -8899,7 +8899,7 @@ var FakeEmbeddingProvider = class {
 	}
 	reset() {}
 };
-const DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta";
+const DEFAULT_BASE$1 = "https://generativelanguage.googleapis.com/v1beta";
 /**
 * An HTTP-shaped failure carrying the status the retry classifier reads.
 *
@@ -8917,7 +8917,7 @@ var GeminiHttpError = class extends Error {
 };
 /** One POST, with the key in a HEADER — never the query string, which is logged. */
 async function post(opts, apiKey, path, body, timeoutMs) {
-	const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE}${path}`, {
+	const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE$1}${path}`, {
 		method: "POST",
 		headers: {
 			"x-goog-api-key": apiKey,
@@ -8973,33 +8973,33 @@ function geminiRestEmbedClient(apiKey, opts = {}) {
 *   Python-SDK failure mode with no JS equivalent; `reset()`
 *   keeps its drop-never-close contract regardless.
 */
-function httpStatusOf(exc) {
+function httpStatusOf$1(exc) {
 	if (!(exc instanceof Error)) return void 0;
 	const status = exc.status;
 	return typeof status === "number" ? status : void 0;
 }
-function isTransportBlip(exc, depth = 0) {
+function isTransportBlip$1(exc, depth = 0) {
 	if (depth > 5 || !(exc instanceof Error)) return false;
 	if (exc.name === "AbortError" || exc.name === "TimeoutError") return true;
 	const code = exc.code;
 	if (typeof code === "string" && /^E[A-Z0-9_]+$/.test(code)) return true;
 	if (exc instanceof TypeError && exc.message.includes("fetch failed")) return true;
-	return isTransportBlip(exc.cause, depth + 1);
+	return isTransportBlip$1(exc.cause, depth + 1);
 }
 /** The Gemini taxonomy for the INGEST plane: transport blips, 5xx, AND 429 —
 * batch work is resumable and has no user waiting. */
-function isRetryable(exc) {
-	if (isTransportBlip(exc)) return true;
-	const status = httpStatusOf(exc);
+function isRetryable$1(exc) {
+	if (isTransportBlip$1(exc)) return true;
+	const status = httpStatusOf$1(exc);
 	if (status === void 0) return false;
 	return status >= 500 && status <= 599 || status === 429;
 }
 /** The READ path's predicate: transport blips + 5xx only — NEVER 429. A
 * rate-limited project stays rate-limited on the next second; the correct
 * move is to degrade to keyword-only NOW, not stall the read behind backoff. */
-function isRetryableQuery(exc) {
-	if (isTransportBlip(exc)) return true;
-	const status = httpStatusOf(exc);
+function isRetryableQuery$1(exc) {
+	if (isTransportBlip$1(exc)) return true;
+	const status = httpStatusOf$1(exc);
 	return status !== void 0 && status >= 500 && status <= 599;
 }
 /**
@@ -9049,6 +9049,160 @@ var GeminiEmbeddingProvider = class {
 			}
 		})).embeddings ?? []).map((e) => [...e.values ?? []]);
 	}
+	isRetryable(exc) {
+		return isRetryable$1(exc);
+	}
+	isRetryableQuery(exc) {
+		return isRetryableQuery$1(exc);
+	}
+};
+/**
+* OpenAI's embedding endpoint, over `fetch` — no SDK.
+*
+* The same call decision 12's 2026-08-22 revision made for Gemini, for the same
+* reason: this is ONE HTTP call behind a structurally-typed slice, and a vendor
+* SDK would put megabytes and a transitive dependency tree into every
+* `ksor init` that never embeds anything. If a provider ever needs an SDK, the
+* seam takes one through `clientFactory`; nothing here forecloses that.
+*
+* WHAT DIFFERS FROM GEMINI, and it is worth knowing before choosing:
+*
+*   Gemini embeds ASYMMETRICALLY — `RETRIEVAL_DOCUMENT` and `RETRIEVAL_QUERY`
+*   produce different vectors for the same text, and the plane's intent picks
+*   which. OpenAI has no task type: a query and a document are embedded
+*   identically. The seam anticipates exactly this — "a provider whose two
+*   vendor labels are equal can never mis-route a plane"
+*   (`lib/embedding.ts`) — so both labels are the empty string and the intent
+*   reaches this transport and is deliberately ignored.
+*
+*   `dimensions` is supported on `text-embedding-3-*` only. Asking an older
+*   model for a dimension is an error there, not a silent full-width vector,
+*   which is the failure the framework's own width check would catch anyway.
+*/
+/**
+* An HTTP-shaped failure carrying the status the retry classifier reads — and
+* the vendor's own error `type`, which the status alone does not distinguish.
+*
+* OpenAI answers a spent balance with **429**, the same status as a rate limit:
+* `{"error":{"type":"insufficient_quota","code":"credit_balance_exhausted"}}`
+* (observed live, 2026-09-01). One clears by waiting and one never will, so a
+* classifier reading only the status retries a billing problem five times with
+* exponential backoff and then reports it — slowly, and as if it had been
+* transient.
+*/
+var OpenAiHttpError = class extends Error {
+	status;
+	/** The vendor's `error.type`, when it sends one. */
+	kind;
+	constructor(status, detail, kind = null) {
+		super(`OpenAI API error ${status}: ${detail}`);
+		this.name = "OpenAiHttpError";
+		this.status = status;
+		this.kind = kind;
+	}
+};
+const DEFAULT_BASE = "https://api.openai.com/v1";
+function openAiRestEmbedClient(apiKey, opts = {}) {
+	return { async embed(params) {
+		const res = await (opts.fetchImpl ?? fetch)(`${opts.baseUrl ?? DEFAULT_BASE}/embeddings`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${apiKey}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				model: params.model,
+				input: [...params.input],
+				dimensions: params.dimensions
+			}),
+			signal: AbortSignal.timeout(params.timeoutMs)
+		});
+		const text = await res.text();
+		if (!res.ok) {
+			let detail = text.slice(0, 300);
+			let kind = null;
+			try {
+				const err = JSON.parse(text).error;
+				if (typeof err?.message === "string") detail = err.message;
+				if (typeof err?.type === "string") kind = err.type;
+			} catch {}
+			throw new OpenAiHttpError(res.status, detail, kind);
+		}
+		const data = [...JSON.parse(text).data ?? []];
+		data.sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+		return { embeddings: data.map((d) => ({ values: d.embedding })) };
+	} };
+}
+/** True for a transport blip with no HTTP status of its own. */
+function isTransportBlip(exc) {
+	if (exc instanceof OpenAiHttpError) return false;
+	const name = exc?.name;
+	return name === "AbortError" || name === "TimeoutError" || name === "TypeError";
+}
+function httpStatusOf(exc) {
+	return exc instanceof OpenAiHttpError ? exc.status : void 0;
+}
+/**
+* The INGEST plane's taxonomy: transport blips, 5xx, AND 429 — batch work is
+* resumable and has nobody waiting. Deliberately the same shape as the Gemini
+* adapter's, because the two planes are a property of ksor, not of a vendor.
+*/
+function isRetryable(exc) {
+	if (isTransportBlip(exc)) return true;
+	if (exc instanceof OpenAiHttpError && exc.kind === "insufficient_quota") return false;
+	const status = httpStatusOf(exc);
+	if (status === void 0) return false;
+	return status >= 500 && status <= 599 || status === 429;
+}
+/**
+* The READ plane's: transport blips + 5xx only, NEVER 429. A rate-limited
+* project stays rate-limited on the next second, so a search degrades to
+* keyword-only now rather than stalling a reader behind backoff.
+*/
+function isRetryableQuery(exc) {
+	if (isTransportBlip(exc)) return true;
+	const status = httpStatusOf(exc);
+	return status !== void 0 && status >= 500 && status <= 599;
+}
+var OpenAiEmbeddingProvider = class {
+	providerId = "openai";
+	modelId;
+	dim;
+	documentTaskLabel;
+	queryTaskLabel;
+	documentTimeoutMs;
+	queryTimeoutMs;
+	clientFactory;
+	client = null;
+	constructor(opts) {
+		this.modelId = opts.modelId;
+		this.dim = opts.dim;
+		this.documentTaskLabel = opts.documentTaskLabel;
+		this.queryTaskLabel = opts.queryTaskLabel;
+		this.documentTimeoutMs = Math.trunc(opts.documentTimeoutS * 1e3);
+		this.queryTimeoutMs = Math.trunc(opts.queryTimeoutS * 1e3);
+		this.clientFactory = opts.clientFactory ?? (() => openAiRestEmbedClient(opts.apiKey));
+	}
+	get recipe() {
+		return `${this.modelId}/d${this.dim}/${this.documentTaskLabel}`;
+	}
+	getClient() {
+		this.client ??= this.clientFactory();
+		return this.client;
+	}
+	/** DROP the client reference, never close it: in-flight calls finish on their
+	* own reference and the next call rebuilds lazily. Idempotent. */
+	reset() {
+		this.client = null;
+	}
+	async embed(texts, opts) {
+		return (await this.getClient().embed({
+			model: this.modelId,
+			input: texts,
+			dimensions: this.dim,
+			timeoutMs: opts.intent === "document" ? this.documentTimeoutMs : this.queryTimeoutMs
+		})).embeddings.map((e) => [...e.values ?? []]);
+	}
 	isRetryable(exc) {
 		return isRetryable(exc);
 	}
@@ -9090,11 +9244,30 @@ var MissingProviderKeyError = class extends Error {
 const PROVIDERS = {
 	gemini: {
 		build: (opts) => new GeminiEmbeddingProvider(opts),
-		needsApiKey: true
+		needsApiKey: true,
+		keyEnv: "GEMINI_API_KEY",
+		taskLabels: {
+			document: EMBED_TASK_DOCUMENT,
+			query: EMBED_TASK_QUERY
+		}
+	},
+	openai: {
+		build: (opts) => new OpenAiEmbeddingProvider(opts),
+		needsApiKey: true,
+		keyEnv: "OPENAI_API_KEY",
+		taskLabels: {
+			document: "",
+			query: ""
+		}
 	},
 	fake: {
 		build: (opts) => new FakeEmbeddingProvider(opts),
-		needsApiKey: false
+		needsApiKey: false,
+		keyEnv: null,
+		taskLabels: {
+			document: EMBED_TASK_DOCUMENT,
+			query: EMBED_TASK_QUERY
+		}
 	}
 };
 function entryFor(name) {
@@ -9103,6 +9276,13 @@ function entryFor(name) {
 	return entry;
 }
 /**
+* The environment variable this provider's key comes from, or null when it
+* needs none. Unknown name → the same loud error as building it.
+*/
+function providerKeyEnv(name) {
+	return entryFor(name).keyEnv;
+}
+/**
 * The port door: the named provider bound to the DECLARED embedding space and
 * the framework's timeout knobs. `modelId`/`dim` omitted = the shipped
 * config space (EMBED_MODEL / EMBED_DIM, eval-locked); an instance may
@@ -9119,8 +9299,8 @@ function buildShippedProvider(name, opts) {
 		apiKey: opts.apiKey ?? "",
 		modelId: opts.modelId ?? "gemini-embedding-001",
 		dim: opts.dim ?? 1536,
-		documentTaskLabel: EMBED_TASK_DOCUMENT,
-		queryTaskLabel: EMBED_TASK_QUERY,
+		documentTaskLabel: entry.taskLabels.document,
+		queryTaskLabel: entry.taskLabels.query,
 		documentTimeoutS: EMBED_TIMEOUT_S(),
 		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
@@ -10955,4 +11135,4 @@ function readHandler(ctx) {
 	};
 }
 //#endregion
-export { parseViewer as A, tlsPosture as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, runProbe as F, withPgRetry as H, searchHandler as I, servingPolicy as L, prewarmPool as M, readHandler as N, parseInstanceText as O, recordIsUndescribed as P, storedTextSearchConfig as R, contentPool as S, instancePathOf as T, withProbeDeadline as U, validateViewer as V, z$1 as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, tallyHandlers as z };
+export { parseViewer as A, tallyHandlers as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, recordIsUndescribed as F, z$1 as G, validateViewer as H, runProbe as I, searchHandler as L, prewarmPool as M, providerKeyEnv as N, parseInstanceText as O, readHandler as P, servingPolicy as R, contentPool as S, instancePathOf as T, withPgRetry as U, tlsPosture as V, withProbeDeadline as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, storedTextSearchConfig as z };

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-Ck1l_Sgs-B-_wMYLB.mjs";
+import { D as outlineHandler, F as recordIsUndescribed, G as z$1, L as searchHandler, P as readHandler, 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-uhx2l1kC-C2BAxISt.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

@@ -141,14 +141,38 @@ What the image deliberately does NOT contain (see `.dockerignore`):
 > 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:
+> **Set the Framework Preset to `Services` on the import screen.** Vercel's own
+> guide states it as one of two necessary conditions:
+>
+> > "A project builds as services only when two conditions are both true: the
+> > project's framework is set to Services, and `vercel.json` contains a
+> > `services` key. If either is missing, Vercel falls back to its default
+> > framework detection and ignores your services configuration."
+> > — [vercel.com/kb/guide/vercel-services](https://vercel.com/kb/guide/vercel-services)
+>
+> That is the silent-404 shape exactly: preset `Other` → fallback detection →
+> nothing detected → an empty output that deploys, reports Ready and takes the
+> alias. And no file in your repository can set it for you: `framework` is not
+> a valid top-level key while `services` is present, so this is a project
+> setting or nothing.
+>
+> **One measurement here disagrees with that guide, and is recorded rather than
+> reconciled.** On 2026-08-27 two projects were read back from the Vercel API,
+> one reading preset `Services` and one reading `Other`, and BOTH built the
+> `services` block and served:
 >
 > | 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 |
 >
+> Both facts are real and they cannot both be the whole rule. Possible readings
+> — the API's `framework` field being derived rather than the project setting,
+> or Beta behaviour changing between the guide's 2026-08-12 revision and that
+> measurement — are unverified, and guessing between them is what produced the
+> earlier version of this page, which told you the preset was RULED OUT and so
+> steered you away from the one step the vendor calls required. Set the preset.
+>
 > **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**,
@@ -427,12 +451,21 @@ Plain `pnpm build` is `[public]`, so the safe thing is the default.
 
 Two supported answers, and a third that is yours.
 
-**Read through the door instead.** This is the one ksor is built for. The MCP
-surface already applies the audience scope **per request** and writes a
-`retrieval_log` row carrying the actor for every read — per-person governance
-with an audit trail, which a static site cannot have at any price. If the
-requirement is "who read what, and were they allowed to", that is the door, not
-the website.
+**Run a door per audience.** The door does NOT decide per request: it serves
+ONE viewer list, read from `KSOR_AUDIENCE` once at boot
+(`content-gateway/src/compose.ts`) and validated against the policy before it
+widens past `public`. Every caller holding a valid token for that door gets the
+same view of the record — `docs/authorization.md` says so plainly, and
+per-request visibility filtering is named out of scope in
+`specs/ksor/serve/spec.md`. So the answer is one process per viewer list, each
+with its own `KSOR_AUDIENCE`, behind whatever routing already decides who
+reaches which URL.
+
+What the door gives that a static site cannot is the **audit**, not the
+authorization: every read writes a `retrieval_log` row naming the verified
+caller, so "who read what" is answerable afterwards. That is worth having, and
+it is a different thing from "were they allowed to", which is still decided by
+which door they can reach.
 
 **Or split the record.** Content needing per-person confidentiality inside one
 tier is usually content that belongs in its own record, with its own gate. That

package/docs/ingesting.md

@@ -35,12 +35,12 @@ Ingest reads your markdown, sends each new chunk to an embedding provider, and
 writes the result to Postgres. So four things must be true, and none of them is
 created for you.
 
-|                      | what                                                                                                                                                                              | how                                                                                                                                     |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, in the KSoR Profile of OKF: `type`, `title`, `description`, `status` and `ksor.audience` in frontmatter | `pnpm check` validates it and explains any violation; `ksor build` must have written a current `build.lock.json` before ingest will run |
-| **The database**     | Postgres with **pgvector** — `CREATE EXTENSION vector;`                                                                                                                           | any managed host; the DDL below needs a role that can create tables                                                                     |
-| **The provider key** | `GEMINI_API_KEY` — the default embedding provider is `gemini-embedding-001`                                                                                                       | [aistudio.google.com](https://aistudio.google.com/apikey); the free tier covers a first corpus                                          |
-| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                        | already named by `instance.md`'s `database:` block                                                                                      |
+|                      | what                                                                                                                                                                                     | how                                                                                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, in the KSoR Profile of OKF: `type`, `title`, `description`, `status` and `ksor.audience` in frontmatter        | `pnpm check` validates it and explains any violation; `ksor build` must have written a current `build.lock.json` before ingest will run |
+| **The database**     | Postgres with **pgvector** — `CREATE EXTENSION vector;`                                                                                                                                  | any managed host; the DDL below needs a role that can create tables                                                                     |
+| **The provider key** | `GEMINI_API_KEY` — the default embedding provider is `gemini-embedding-001`. Declaring `embedding.provider: openai` reads `OPENAI_API_KEY` instead: each provider names its own variable | [aistudio.google.com](https://aistudio.google.com/apikey); free tier — embedding input is free of charge                                |
+| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                               | already named by `instance.md`'s `database:` block                                                                                      |
 
 Both variables go in `.env` beside `instance.md` — `ksor` reads it automatically,
 and `.env` is gitignored. Every command below is run **from your repository
@@ -197,8 +197,25 @@ measure until the corpus is in there.
 pnpm exec ksor calibrate --instance instance.md
 ```
 
-It ends with a block to paste into **`instance.md`**'s frontmatter, exactly as
-printed — the floor, the measurement recorded beside it as a comment, and
+**On a free-tier key, use the zero-LLM door instead.** The command above is the
+SYNTHESIZED door: it writes one probe question per sampled passage with an LLM,
+and a free key allows only a few generations a minute — a bigger corpus makes
+that worse, not better. Write your own in-corpus questions, one per line, and
+pass them:
+
+```sh
+pnpm exec ksor calibrate --instance instance.md --queries-file questions.txt
+```
+
+Six to ten real questions is enough. They should be things this record answers,
+in the words someone would actually ask — the floor is set by the WEAKEST of
+them, so a vague question drags it down and a question the record does not
+answer invalidates the measurement. The door is recorded beside the number
+(`door: queries-file`), because floors from the two doors are measured against
+different distributions and must never be compared as interchangeable.
+
+Either way it ends with a block to paste into **`instance.md`**'s frontmatter,
+exactly as printed — the floor, the measurement recorded beside it as a comment, and
 `floor_digest`, the digest of the retrieval predicate the floor was measured
 through. Paste it, then restart `ksor serve`: the floor is read at boot.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "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",
@@ -72,8 +72,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content-gateway": "0.0.0",
-    "@panaversity/ksor-content": "0.0.0"
+    "@panaversity/ksor-content": "0.0.0",
+    "@panaversity/ksor-content-gateway": "0.0.0"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/AGENTS.md

@@ -100,8 +100,11 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    ```
 
    That is enough. `embedding:` is optional and already defaults to
-   `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`; write it out
-   only to pin the space explicitly or to change it — and note that model and
+   `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`. The other
+   shipped vendor is OpenAI — `provider: openai`, `model:
+text-embedding-3-small`, `dim: 1536`, key in `OPENAI_API_KEY` — and each
+   provider names its own key variable, so nothing else changes. Write the block
+   out only to pin the space explicitly or to change it — and note that model and
    dim are the PERSISTED identity of the embedding space, so changing either
    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
@@ -114,7 +117,33 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    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.
 
-2. **Copy `.env.example` to `.env`** and fill it in — `ksor` reads it
+2. **Get the database — your agent can do this one.** `.mcp.json` at the repo
+   root declares the MCP servers this project may reach, and the first is Neon.
+   With it connected, ask:
+
+   > Using the Neon MCP server, create a project called `<your-record>` and
+   > enable the pgvector extension on it. Then create a branch called `dev`,
+   > and save that branch's connection string to `.env` as `KSOR_DB_URL`.
+   > Never print my API key. Show me the plan before you run anything.
+
+   That is `create_project`, `run_sql` (`CREATE EXTENSION vector`),
+   `create_branch` and `get_connection_string` — four real tools, no dashboard.
+   Prefer the OAuth flow: an API key pasted into `.mcp.json` would be committed,
+   because that file carries no secret and is not gitignored.
+
+   Any Postgres with pgvector works — Neon is the path with an MCP server, not a
+   requirement. Locally: `docker run -e POSTGRES_PASSWORD=x -p 5432:5432
+pgvector/pgvector:pg17`.
+
+   **`GEMINI_API_KEY` is the one step no agent can do.** No vendor mints an API
+   key over a protocol; it comes from a browser at
+   [aistudio.google.com/apikey](https://aistudio.google.com/apikey) and a human
+   pastes it. An agent working through this list should ask for it by name and
+   stop, rather than trying — and should say that the FREE TIER is enough:
+   embedding input on `gemini-embedding-001` is free of charge, so this is a
+   signup, not a bill.
+
+3. **Copy `.env.example` to `.env`** and fill it in — `ksor` reads it
    automatically, so nothing needs exporting, and `.env` is already gitignored.
    A real environment variable still wins over the file, so CI and production
    overrides behave normally.
@@ -134,7 +163,7 @@ Stand it up in this order (each step's errors explain how to fix themselves):
      intended dev shape. A PUBLIC deployment configures the SSO door instead —
      see the comments in `.env.example` and "Serving safely" below.
 
-3. **Bring it up.** Once, then every time:
+4. **Bring it up.** Once, then every time:
 
    ```sh
    pnpm provision  # schema (or migrate) + grant — the privileged acts, run once
@@ -219,7 +248,7 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    serves, or a DBA who holds the credentials that authorize ingest — not as a
    daily choice.
 
-4. **Turn the abstention gate on — deliberately, once it serves.** This is the
+5. **Turn the abstention gate on — deliberately, once it serves.** This is the
    step that makes "not in this corpus" a real answer, and it is measured, never
    guessed:
 

package/templates/scaffold/README.md

@@ -171,7 +171,31 @@ That is the whole required config. `embedding:` defaults to Gemini at 1536
 dimensions, and `retrieval:` is written for you by step 3's `calibrate`. Change
 the variable name here only if you want a different one.
 
-### 2. Fill in the environment
+### 2. Get a database — your agent can do this one
+
+`.mcp.json` at the repo root declares the MCP servers this project may reach.
+The first is Neon's. With it connected, ask your coding agent:
+
+> Using the Neon MCP server, create a project called `<your-record>` and enable
+> the pgvector extension on it. Then create a branch called `dev`, and save that
+> branch's connection string to `.env` as `KSOR_DB_URL`. Never print my API key.
+> Show me the plan before you run anything.
+
+Prefer the OAuth flow. `.mcp.json` is committed and carries no secret; an API
+key pasted into it would be.
+
+Any Postgres with pgvector works — Neon is the path that has an MCP server, not
+a requirement. Locally:
+`docker run -e POSTGRES_PASSWORD=x -p 5432:5432 pgvector/pgvector:pg17`.
+
+**`GEMINI_API_KEY` is the one step no agent can do for you** — no vendor mints
+an API key over a protocol. Get it from
+[aistudio.google.com/apikey](https://aistudio.google.com/apikey) and paste it.
+**The free tier costs nothing and is enough**: embedding input on
+`gemini-embedding-001` is free of charge, and a first corpus is a few thousand
+tokens. This is a signup, not a bill.
+
+### 3. Fill in the environment
 
 ```sh
 cp .env.example .env
@@ -191,7 +215,7 @@ refusal tells you to _export_ a variable, putting it in `.env` is the same
 thing. `KSOR_AUTH=disabled-local` is required for a local run: serve refuses to
 boot unauthenticated on purpose, so a server is never open by accident.
 
-### 3. Bring it up
+### 4. Bring it up
 
 ```sh
 pnpm provision  # once: apply the schema, authorize ingest
@@ -273,7 +297,15 @@ Delete `.mcp.json`, or keep it — it holds no secret.
 Both surfaces on one domain, in about ten minutes:
 
 1. **Push the repository to GitHub.**
-2. **Import it in Vercel**, then **set Root Directory to `./`.** Vercel
+2. **Import it in Vercel**, then set **Framework Preset** to **`Services`** and
+   **Root Directory** to `./`. The preset is not cosmetic: Vercel's own guide
+   says a project builds as services only when the preset is `Services` AND
+   `vercel.json` carries a `services` key, and that "if either is missing,
+   Vercel falls back to its default framework detection and ignores your
+   services configuration" — which is the silent 404 below. No file in this
+   repository can set it for you.
+
+   As for Root Directory: Vercel
    auto-fills it with `system/site`, because that is where it finds a framework
    — and the build then reads `system/site/vercel.json`, which does not exist,
    and fails with `Project framework is set to "services", but no services are
@@ -282,6 +314,19 @@ declared`. The services ARE declared, in `vercel.json` at the repo root,
    container from the root `Dockerfile`.
 3. **Set three environment variables** in Vercel: `KSOR_DB_URL`,
    `GEMINI_API_KEY`, and `KSOR_AUTH=disabled-public`.
+4. **Check it actually serves**, before you tell anyone the URL. A Ready
+   deployment that answers 404 everywhere looks identical to a good one from
+   the dashboard:
+
+   ```sh
+   B=https://your-record.vercel.app
+   curl -o /dev/null -w '%{http_code}\n' "$B/"           # expect 200
+   curl -o /dev/null -w '%{http_code}\n' "$B/llms.txt"   # expect 200
+   curl -sI "$B/mcp" | head -1                           # expect 405
+   ```
+
+   `/mcp` answering 405 is the door refusing a GET — that is how you know it is
+   routed at all, and a 404 there means the `services` block was ignored.
 
 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:
@@ -289,10 +334,13 @@ 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
+  `WARNING! Build output contains no "functions" or "static" directory`. That
+  warning is the FALLBACK collector finding nothing, which is what step 2's
+  preset exists to prevent — check it first. One measurement of ours disagrees
+  with the vendor's rule and is recorded in
+  `node_modules/@panaversity/ksor/docs/deploying.md`; the honest state is that
+  the preset is necessary by the vendor's documentation and has once appeared
+  not to be. 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
@@ -372,6 +420,29 @@ approved has to be the text that was written. That act is yours.
 Run `pnpm check` before you commit. It runs the rules as a program, and every
 failure it reports says what is wrong, why the rule exists, and how to fix it.
 
+### Names instead of handles
+
+The record stores actors as identifiers — `human:you`, `team:legal-ops` — and a
+page would otherwise lead with the slug: "Owner · human:bashiraziz". Put the
+name beside the identifier in `.ksor/people.yaml` and pages print that instead:
+
+```yaml
+people:
+  "human:bashiraziz": Bashir Aziz
+  "human:ciso": Ayesha Khan
+```
+
+Keyed by the identifier exactly as the record stores it, quoted because it
+contains a colon. There is no rule that turns a name into a handle — `ciso` is
+nobody's squashed full name — so both are written down, and an actor with no
+entry renders exactly as stored rather than being guessed at.
+
+**This is presentation, and nothing else.** It grants no authority: who may
+approve or withdraw is `.ksor/governance.yaml`, and the two files are not
+checked against each other, because someone who leaves the authority list is
+still the recorded approver of everything they approved. Optional — a record
+that declares no names reads exactly as it did before.
+
 ### Presenting a document
 
 Ask your coding agent for slides and it writes them, from the document, into the

package/templates/scaffold/mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "Neon": {
+      "type": "http",
+      "url": "https://mcp.neon.tech/mcp"
+    },
+    "agentfactory-system-of-record": {
+      "type": "http",
+      "url": "https://sor.panaversity.org/mcp",
+      "oauth": { "clientId": "zia-tutor-ai", "callbackPort": 3118 }
+    }
+  }
+}