@panaversity/ksor 0.0.53 → 0.0.55

package/templates/scaffold/README.md

@@ -171,7 +171,50 @@ 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.
+It ships with two, and both are yours to keep or delete — it is your file:
+
+| server                           | what it is                                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `Neon`                           | Neon's own hosted MCP server, for provisioning the Postgres the agent surface needs (step 2)     |
+| `agentfactory-system-of-record`  | a KSoR record Panaversity operates, served over MCP — an example of the surface you are building |
+
+The second is **not** your record and is not needed to run this project. It is
+read-only and it answers about the Agent Factory curriculum, not about your
+knowledge. Delete the entry if you would rather your agent not have it; nothing
+here depends on it.
+
+**Before you connect Neon, know what you are granting.** The Neon MCP server
+acts on your Neon *account*, not on one database: an agent holding it can create
+and delete projects and branches. Point it at an account you are willing to let
+an agent change, review the plan it shows you before approving, and read Neon's
+own documentation on the server's scopes and permissions rather than taking this
+paragraph as the whole of it.
+
+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 +234,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
@@ -230,17 +273,14 @@ separately](#the-agent-surface-deploys-separately). Any other operation is
 ### Test the door 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:
+with `curl`. With `pnpm serve` running, **add** an entry to the `.mcp.json` you
+already have — alongside `Neon`, not in place of it:
 
 ```json
-{
-  "mcpServers": {
     "test-record": {
       "type": "http",
       "url": "http://127.0.0.1:8080/mcp"
     }
-  }
-}
 ```
 
 **If you skipped `calibrate`, expect answers where this test wants refusals** —
@@ -264,7 +304,9 @@ 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.
 
-Delete `.mcp.json`, or keep it — it holds no secret.
+Keep the `test-record` entry or remove it — it points at loopback and holds no
+secret either way. Do not delete `.mcp.json` itself: it is where `Neon` is
+declared, and step 2 above needs it.
 
 ---
 
@@ -273,7 +315,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 +332,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 +352,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

package/templates/scaffold/env.example

@@ -10,8 +10,13 @@
 # explicitly instead of relying on a driver default that is due to change.
 KSOR_DB_URL=postgresql://user:password@host:5432/dbname
 
-# The embedding provider key. instance.md defaults to gemini-embedding-001.
+# The embedding provider key — ONE of these, whichever `embedding.provider` in
+# instance.md names. It defaults to gemini, so that is the one uncommented; on
+# `provider: openai`, comment this out and set OPENAI_API_KEY instead. A record
+# reads exactly one of them, and `ksor serve` names the one it wanted when it
+# is missing.
 GEMINI_API_KEY=
+# OPENAI_API_KEY=
 
 # ── Who may ask ─────────────────────────────────────────────────────────────
 # ONE variable, and its VALUE is the decision. `ksor serve` refuses to boot

package/templates/scaffold/gitignore

@@ -1,7 +1,8 @@
 # ksor's working directory — build output and scratch, never the record.
-# The two governance files inside it ARE the record (the policy and the
-# takedown ledger) and are un-ignored by name: the directory form `.ksor/`
-# cannot be negated, so the glob is `.ksor/*`.
+# The governance files inside it ARE the record (the policy, the takedown
+# ledger, and the phone book the site publishes names from) and are un-ignored
+# by name: the directory form `.ksor/` cannot be negated, so the glob is
+# `.ksor/*`.
 .ksor/*
 !.ksor/governance.yaml
 !.ksor/people.yaml

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 }
+    }
+  }
+}

package/templates/scaffold/system/site/lib/lock.ts

@@ -73,6 +73,8 @@ export interface ControlTexts {
   readonly policy: string;
   /** Null when `.ksor/takedowns.yaml` is not there — an empty ledger. */
   readonly ledger: string | null;
+  /** Null when `.ksor/people.yaml` is not there — no natural names declared. */
+  readonly people: string | null;
 }
 
 function sha256Text(text: string): string {
@@ -139,12 +141,17 @@ export function readLock(
     ["instance.md", lock.data.instance_sha256, sha256Text(control.instance)],
     [".ksor/governance.yaml", lock.data.policy_sha256, sha256Text(control.policy)],
     [".ksor/takedowns.yaml", lock.data.ledger_sha256, sha256Text(control.ledger ?? "")],
+    // The phone book publishes NAMES in place of stored actors, so an edit here
+    // changes the approver printed on every page. Left out, the site could
+    // publish one approver while the `/md/` twin stamped with the same
+    // `build_id` published another (review, 2026-09-01).
+    [".ksor/people.yaml", lock.data.people_sha256, sha256Text(control.people ?? "")],
   ] as const) {
     if (want === have) continue;
     refuse(
       "ksor-lock-stale",
       `${file} changed since ${LOCK_FILE} was written`,
-      "the lock's build_id is a hash over the record AND the three files that govern it, so a projection under a control file the lock never saw publishes what nothing checked — a denial lifted by deleting a line would otherwise leave the lock valid",
+      "the lock's build_id is a hash over the record AND the four files that govern it, so a projection under a control file the lock never saw publishes what nothing checked — a denial lifted by deleting a line would otherwise leave the lock valid",
       "run `ksor build` again and commit the lock with the change; lift a denial with `ksor takedown --revoke <id>`, never by editing the ledger",
     );
   }

package/templates/scaffold/system/site/lib/people-rule.ts

@@ -0,0 +1,56 @@
+/**
+ * What a phone book file DECLARES, as a pure function of its text.
+ *
+ * A LEAF, like `actor-display.ts`: `people.ts` roots itself at the project via
+ * `shared.ts`, which reads `instance.md` at module load, so a rule living
+ * there could only be exercised by building a whole record on disk first. That
+ * is a test nobody writes, and the duplicate-key rule below went four days
+ * asserted only by a comment because of it.
+ *
+ * A map comes back for every malformed shape rather than an error, because a
+ * phone book is DECORATION: a record with an unreadable one publishes
+ * identifiers, which is exactly what it did before the file existed.
+ */
+
+import { parseAllDocuments } from "yaml";
+
+/**
+ * The phone book a file DECLARES, as a pure function of its text.
+ *
+ * Separated from the read so the rule can be exercised without a record on
+ * disk: the loader below is a filesystem act rooted at `projectRoot`, and a
+ * test that has to build a whole scaffold to ask "what do two entries for one
+ * actor mean?" is a test nobody writes. A map is handed back for every
+ * malformed shape rather than an error, because a phone book is decoration:
+ * a record with an unreadable one publishes identifiers, which is what it did
+ * before the file existed.
+ */
+export function parsePeople(text: string): ReadonlyMap<string, string> {
+  try {
+    const docs = parseAllDocuments(text.replace(/^\ufeff/, ""), {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    const doc = docs[0];
+    if (doc === undefined) return new Map();
+    // `uniqueKeys: true` RECORDS a duplicate rather than refusing one — `toJS()`
+    // still resolves last-wins. Reading the option and not the errors is what
+    // made the claim above false: two entries for one actor silently published
+    // the second person's name on the first person's governance act.
+    if (doc.errors.length > 0) return new Map();
+    const value: unknown = doc.toJS();
+    if (typeof value !== "object" || value === null) return new Map();
+    const table = (value as { people?: unknown }).people;
+    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
+    const out = new Map<string, string>();
+    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
+      // A blank value is an entry someone started and left; printing "" would
+      // erase the identifier rather than replace it.
+      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}

package/templates/scaffold/system/site/lib/people.ts

@@ -8,8 +8,9 @@
  * `human:mjs` — most of the actors in a real record — had no expressible name
  * at all. It also collided: "Bashir Aziz" and "Bashira Ziz" both derive
  * `bashiraziz`, which would print one person's name on the other's governance
- * act. A map has neither problem, and duplicate keys are refused by the parser
- * rather than resolved by whichever came last.
+ * act. A map has neither problem, and a duplicate key drops the whole book
+ * rather than resolving to whichever came last — `uniqueKeys` only REPORTS the
+ * duplicate, so the errors have to be read for that to be true.
  *
  * ONE-WAY. The identifier is what the record stores, cites and checks against
  * the policy; this is only what a page prints. Nothing reads a name back into
@@ -34,8 +35,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
-import { parseAllDocuments } from "yaml";
-
+import { parsePeople } from "./people-rule";
 import { projectRoot } from "./shared";
 
 const PEOPLE_YAML = path.join(projectRoot, ".ksor", "people.yaml");
@@ -48,26 +48,7 @@ function loadPeople(): ReadonlyMap<string, string> {
     // Optional: its absence means "no natural names declared".
     return new Map();
   }
-  try {
-    const docs = parseAllDocuments(text.replace(/^/, ""), {
-      schema: "core",
-      uniqueKeys: true,
-      logLevel: "silent",
-    });
-    const value: unknown = docs[0]?.toJS();
-    if (typeof value !== "object" || value === null) return new Map();
-    const table = (value as { people?: unknown }).people;
-    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
-    const out = new Map<string, string>();
-    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
-      // A blank value is an entry someone started and left; printing "" would
-      // erase the identifier rather than replace it.
-      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
-    }
-    return out;
-  } catch {
-    return new Map();
-  }
+  return parsePeople(text);
 }
 
 let cached: ReadonlyMap<string, string> | null = null;

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

@@ -48,6 +48,7 @@ import type { Refusal } from "../record/refusal";
 const KNOWLEDGE = "knowledge/";
 const LEDGER_PATH = ".ksor/takedowns.yaml";
 const POLICY_PATH = ".ksor/governance.yaml";
+const PEOPLE_PATH = ".ksor/people.yaml";
 /**
  * Everything this build may publish, as bytes at bundle-relative paths: the
  * admitted concepts (copied), their companions (copied), ONLY the assets those
@@ -177,6 +178,7 @@ function planStage(recordDir: string, development: boolean): StagePlan {
           instance: record.files.get("instance.md") ?? "",
           policy: record.files.get(POLICY_PATH) ?? "",
           ledger: record.files.get(LEDGER_PATH) ?? null,
+          people: record.files.get(PEOPLE_PATH) ?? null,
         },
         { draftsRequested },
       );

package/templates/scaffold/system/site/record/load.ts

@@ -11,7 +11,17 @@ import path from "node:path";
 import type { RecordFiles } from "./check";
 import type { ScaffoldStructure } from "./hygiene";
 
-const CONTROL_FILES = ["instance.md", ".ksor/governance.yaml", ".ksor/takedowns.yaml"] as const;
+// `.ksor/people.yaml` is here because the SITE reads it and publishes what it
+// says — it rewrites the approver, owner and verifier printed on every document
+// page. A file that changes published bytes has to reach `build_id`, or the
+// human surface and the machine surface of one build can disagree about who
+// approved a document with nothing going red (found by review, 2026-09-01).
+const CONTROL_FILES = [
+  "instance.md",
+  ".ksor/governance.yaml",
+  ".ksor/people.yaml",
+  ".ksor/takedowns.yaml",
+] as const;
 /** Files the operating system writes behind the author's back: ignored, never reported. */
 const OS_JUNK = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
 

package/templates/scaffold/system/site/record/lock.ts

@@ -46,6 +46,7 @@ const lockSchema = z
     drafts: z.enum(["hidden", "shown"]),
     instance_sha256: hex64,
     policy_sha256: hex64,
+    people_sha256: hex64,
     ledger_sha256: hex64,
     ledger_entries: z.array(z.object({ id: z.string().min(1), digest: hex64 }).strict()),
     audiences: z
@@ -89,6 +90,8 @@ export interface Lock {
   readonly drafts: Drafts;
   readonly instance_sha256: string;
   readonly policy_sha256: string;
+  /** The phone book the SITE publishes names from. Empty string when absent. */
+  readonly people_sha256: string;
   readonly ledger_sha256: string;
   /** `(id, digest)` per ledger entry, sorted by id — the baseline the next build compares TEXT against. */
   readonly ledger_entries: readonly { readonly id: string; readonly digest: string }[];
@@ -154,6 +157,7 @@ export interface BuildIdInputs {
   readonly indexes: readonly { readonly path: string; readonly sha256: string }[];
   readonly instance_sha256: string;
   readonly policy_sha256: string;
+  readonly people_sha256: string;
   readonly ledger_sha256: string;
   readonly ksor_version: string;
   readonly drafts: Drafts;
@@ -181,6 +185,9 @@ export function buildIdOf(inputs: BuildIdInputs): string {
       .sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
     instance_sha256: inputs.instance_sha256,
     policy_sha256: inputs.policy_sha256,
+    // The site prints what this file says in place of the stored actor, so it
+    // is published content and belongs in the id like any other.
+    people_sha256: inputs.people_sha256,
     ledger_sha256: inputs.ledger_sha256,
     ksor_version: inputs.ksor_version,
     drafts: inputs.drafts,
@@ -233,6 +240,8 @@ export interface LockInput {
   readonly drafts: Drafts;
   readonly instanceText: string;
   readonly policyText: string;
+  /** Null when `.ksor/people.yaml` does not exist, which is every record until an owner writes one. */
+  readonly peopleText: string | null;
   /** Null when the ledger file does not exist. */
   readonly ledgerText: string | null;
   readonly ledgerEntries: readonly { readonly id: string; readonly digest: string }[];
@@ -269,6 +278,7 @@ export function composeLock(input: LockInput): Lock {
     .map((i) => ({ path: i.path, sha256: sha256Hex(i.text) }));
   const instance_sha256 = sha256Hex(input.instanceText);
   const policy_sha256 = sha256Hex(input.policyText);
+  const people_sha256 = sha256Hex(input.peopleText ?? "");
   const ledger_sha256 = sha256Hex(input.ledgerText ?? "");
   return {
     format: LOCK_FORMAT,
@@ -279,6 +289,7 @@ export function composeLock(input: LockInput): Lock {
       indexes,
       instance_sha256,
       policy_sha256,
+      people_sha256,
       ledger_sha256,
       ksor_version: input.ksorVersion,
       drafts: input.drafts,
@@ -291,6 +302,7 @@ export function composeLock(input: LockInput): Lock {
     drafts: input.drafts,
     instance_sha256,
     policy_sha256,
+    people_sha256,
     ledger_sha256,
     ledger_entries: [...input.ledgerEntries].sort((a, b) => compare(a.id, b.id)),
     audiences: { registry: [...input.audiences].sort(), viewers },