@panaversity/ksor 0.0.2 → 0.0.4

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

@@ -23,6 +23,7 @@ const ALLOWED_KEYS = new Set([
   "title",
   "description",
   "status",
+  "visibility",
   "owner",
   "provenance",
   "effective",
@@ -96,9 +97,10 @@ function unquote(value) {
 
 /**
  * The frontmatter block, two levels deep (`ksor:` has children; `provenance:`
- * has list items). Returns null when there is no block at all, and collects
- * every line that is neither `key: value`, a list item, an indented
- * continuation, nor blank — those mean the block was never closed.
+ * and `audiences:` have list items, collected under the key above them).
+ * Returns null when there is no block at all, and collects every line that is
+ * neither `key: value`, a list item, an indented continuation, nor blank —
+ * those mean the block was never closed.
  */
 function parseFrontmatter(text) {
   // An editor's byte-order mark is invisible to the author; it must not be
@@ -108,6 +110,7 @@ function parseFrontmatter(text) {
   if (!match) return null;
   const keys = new Map();
   const children = new Map();
+  const lists = new Map();
   const quoted = new Set();
   const malformedQuote = new Map();
   const malformed = [];
@@ -139,6 +142,7 @@ function parseFrontmatter(text) {
       }
       keys.set(current, unquote(top[2]));
       children.set(current, new Map());
+      lists.set(current, []);
       continue;
     }
     const nested = /^[ \t]+([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
@@ -146,10 +150,40 @@ function parseFrontmatter(text) {
       children.get(current).set(nested[1], unquote(nested[2]));
       continue;
     }
+    // A list item belongs to the key above it: audiences: is a list of
+    // audiences, and the rules that read it need the entries, not their count.
+    const item = /^[ \t]*-[ \t]+(.*)$/.exec(line);
+    if (item && current !== null) {
+      // YAML ends a plain scalar at ` #` — the comment is not part of the
+      // entry, and reading it as one refuses the documents instead of the
+      // list (found live 2026-08-18: `- public # the default` made every
+      // public document's visibility undeclared).
+      const value = /^["']/.test(item[1]) ? item[1] : item[1].replace(/\s+#.*$/, "");
+      lists.get(current).push(unquote(value));
+      continue;
+    }
+    // A dash glued to its value (`-internal`) is a list item to nobody —
+    // the indented-continuation escape below swallowed it while the build
+    // scanners stopped reading the list there: one green record, two
+    // different audience lists (review finding, 2026-08-19).
+    if (/^[ \t]*-\S/.test(line)) {
+      malformed.push(line.trim());
+      continue;
+    }
     if (/^[ \t]*-([ \t]|$)/.test(line) || /^[ \t]+\S/.test(line)) continue;
     malformed.push(line.trim());
   }
-  return { keys, children, quoted, malformedQuote, duplicates, malformed, tightColons, tabIndents };
+  return {
+    keys,
+    children,
+    lists,
+    quoted,
+    malformedQuote,
+    duplicates,
+    malformed,
+    tightColons,
+    tabIndents,
+  };
 }
 
 /**
@@ -218,13 +252,14 @@ function linkTargets(body) {
   return raw.map((t) => (t.startsWith("<") && t.endsWith(">") ? t.slice(1, -1).trim() : t));
 }
 
+/** Reports a broken target; returns the record document it resolves to, if any. */
 function checkLinkTarget(rel, docPath, target) {
   // Anything with a URI scheme (https:, mailto:, tel:, ftp:, …) or a
   // protocol-relative // host leaves the record on purpose — only relative
   // paths are the record's own links (review finding 2026-08-18: tel: was
   // reported as a dead file and //host as an escape).
-  if (target === "" || target.startsWith("#") || target.startsWith("//")) return;
-  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return;
+  if (target === "" || target.startsWith("#") || target.startsWith("//")) return null;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return null;
   const resolved = path.resolve(path.dirname(docPath), target.split("#")[0]);
   if (!resolved.startsWith(knowledgeDir + path.sep) && resolved !== knowledgeDir) {
     problem(
@@ -240,9 +275,46 @@ function checkLinkTarget(rel, docPath, target) {
       "a record with dead internal links serves different truths by path",
       "fix the path or remove the link",
     );
+  } else if (resolved.endsWith(".md")) {
+    return resolved;
   }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// the audience model: who may read a document, declared in instance.md
+// ---------------------------------------------------------------------------
+const instanceMd = path.join(root, "instance.md");
+
+/**
+ * The declared audiences, ordered least- to most-restricted, or null when the
+ * record declares none — and then every visibility rule below stays inert, so
+ * a record without an audience model behaves exactly as it did before the key
+ * existed. Read before the record itself: who may read what is a property of
+ * the whole record, which no single document can answer.
+ */
+function readAudienceModel() {
+  if (!existsSync(instanceMd)) return null;
+  const fm = parseFrontmatter(readFileSync(instanceMd, "utf8"));
+  const audiences = fm?.lists.get("audiences") ?? [];
+  if (audiences.length === 0) return null;
+  return { audiences, defaultVisibility: scalarValue(fm, "default_visibility") ?? "" };
+}
+
+/**
+ * A plain scalar ends at ` #` — the rule the list items above already follow
+ * and both build scanners apply. The checker not applying it to values let
+ * `default_visibility: public # the default` build fine and fail `pnpm check`
+ * (review finding, 2026-08-19).
+ */
+function scalarValue(fm, key) {
+  const value = fm.keys.get(key);
+  if (value === undefined || fm.quoted.has(key)) return value;
+  return value.replace(/\s+#.*$/, "").trim();
 }
 
+const audienceModel = readAudienceModel();
+
 if (!existsSync(knowledgeDir)) {
   problem(
     "knowledge/",
@@ -389,6 +461,8 @@ if (!existsSync(knowledgeDir)) {
   }
 
   // frontmatter + links per document
+  const visibilityByPath = new Map();
+  const crossings = [];
   for (const p of mdFiles) {
     const rel = path.relative(root, p);
     const text = readFileSync(p, "utf8");
@@ -552,22 +626,116 @@ if (!existsSync(knowledgeDir)) {
             "a replaced document must hand the reader its successor — a broken pointer dead-ends them on stale truth",
             "fix the path (it resolves relative to this document), or write the successor first",
           );
+        } else {
+          crossings.push({ kind: "superseded_by", rel, from: p, to: resolved, target: successor });
+        }
+      }
+      // visibility: one audience per document, from the set instance.md declares
+      const visibility = fm.keys.get("visibility");
+      const listed = fm.lists.get("visibility") ?? [];
+      // A flow list ([a, b]) is already named by the shape rule above.
+      const flowList = !fm.quoted.has("visibility") && /^\[.*\]$/.test(visibility ?? "");
+      if (listed.length > 0) {
+        problem(
+          rel,
+          "visibility is one value, not a list",
+          "a list makes every document a set-membership question, and set intersection is where access-control bugs live — one document belongs to exactly one audience",
+          `write a single audience: visibility: ${audienceModel?.audiences.at(-1) ?? "<audience>"}`,
+        );
+      } else if (visibility !== undefined && !flowList) {
+        if (audienceModel === null) {
+          problem(
+            rel,
+            `visibility: ${visibility} — the record declares no audience model`,
+            "who may read a document is governance, not a comment: with no audiences: in instance.md nothing constrains this value, and every surface publishes the document to everyone regardless",
+            "add audiences: to instance.md (ordered least- to most-restricted, public first) with default_visibility:, or remove the visibility: key",
+          );
+        } else if (!audienceModel.audiences.includes(visibility)) {
+          problem(
+            rel,
+            `visibility "${visibility}" is not a declared audience`,
+            "the audience set is closed in instance.md — a value outside it names a build that does not exist, so the document reaches either nobody or everybody",
+            `use one of: ${audienceModel.audiences.join(", ")} — or remove the key to take the default (${audienceModel.defaultVisibility})`,
+          );
         }
       }
+      if (audienceModel !== null) {
+        visibilityByPath.set(p, visibility ?? audienceModel.defaultVisibility);
+      }
     }
     // links: resolve, and never escape the record
-    for (const target of linkTargets(stripCode(text))) checkLinkTarget(rel, p, target);
+    for (const target of linkTargets(stripCode(text))) {
+      const to = checkLinkTarget(rel, p, target);
+      if (to !== null) crossings.push({ kind: "link", rel, from: p, to, target });
+    }
+  }
+
+  // Pointers across audiences: the leak no single build can catch, because the
+  // build that publishes the pointer has already dropped its target and cannot
+  // know it ever existed. Only the whole record sees both ends.
+  if (audienceModel !== null) {
+    const audienceOf = (file) => visibilityByPath.get(file) ?? audienceModel.defaultVisibility;
+    const tier = (file) => audienceModel.audiences.indexOf(audienceOf(file));
+    for (const { kind, rel, from, to, target } of crossings) {
+      const here = tier(from);
+      const there = tier(to);
+      // An undeclared audience at either end is already reported; comparing
+      // against a tier that does not exist would invent a second problem.
+      if (here === -1 || there === -1 || there <= here) continue;
+      const relTo = path.relative(root, to);
+      const both = `${relTo} is ${audienceOf(to)}, this document is ${audienceOf(from)}`;
+      if (kind === "link") {
+        problem(
+          rel,
+          `link to a more restricted document: ${target} — ${both}`,
+          "the build that publishes this link has already dropped its target: the link text and URL ship to readers who cannot open them, naming a document they were never meant to know exists",
+          `raise this document to ${audienceOf(to)}, widen ${relTo} to ${audienceOf(from)}, or remove the link`,
+        );
+      } else {
+        problem(
+          rel,
+          `superseded_by points at a more restricted document: ${target} — ${both}`,
+          "it strands the very readers the supersession exists to redirect: they are told this document is replaced, by a successor their build does not contain",
+          `widen ${relTo} to ${audienceOf(from)}, raise this document to ${audienceOf(to)}, or supersede it with a document its readers can reach`,
+        );
+      }
+    }
   }
 }
 
 // ---------------------------------------------------------------------------
 // instance.md: the identity of this SoR — format 1, closed key set
 // ---------------------------------------------------------------------------
-const INSTANCE_KEYS = new Set(["format", "name", "ksor", "site"]);
+// The identity/site keys this checker owns, PLUS the four kernel config groups
+// (database/embedding/retrieval/budgets) that `ksor serve`/`ingest` read. The
+// groups are optional — a level-0 project that only runs `pnpm dev` declares
+// none, and the default scaffold ships none (init stays database-free). They
+// must be ALLOWED here so a project climbing to the served rung is not fought
+// by its own CI: the kernel's instance parser (packages/content/src/instance.ts)
+// REQUIRES `database:` to serve and is authoritative for the VALUES inside each
+// group (dsn_env grammar, dim range, the vector_floor states). This checker
+// only guards the key NAMES so a misspelled group or field is still caught.
+const INSTANCE_KEYS = new Set([
+  "format",
+  "name",
+  "ksor",
+  "site",
+  "audiences",
+  "default_visibility",
+  "database",
+  "embedding",
+  "retrieval",
+  "budgets",
+]);
 const INSTANCE_KSOR_KEYS = new Set(["requires", "scaffolded"]);
 const INSTANCE_SITE_KEYS = new Set(["url"]);
+// Nested field names mirror the kernel's instance schema; the kernel validates
+// their values (this checker stays dependency-free and cannot import it).
+const INSTANCE_DATABASE_KEYS = new Set(["dsn_env", "tenant_id"]);
+const INSTANCE_EMBEDDING_KEYS = new Set(["provider", "model", "dim"]);
+const INSTANCE_RETRIEVAL_KEYS = new Set(["vector_floor", "keyword_floor"]);
+const INSTANCE_BUDGETS_KEYS = new Set(["maximum_response_characters"]);
 
-const instanceMd = path.join(root, "instance.md");
 if (!existsSync(instanceMd)) {
   problem(
     "instance.md",
@@ -673,9 +841,70 @@ if (!existsSync(instanceMd)) {
         );
       }
     }
+    // the audience model: ordered, public first, and never without its default
+    const audiences = fm.lists.get("audiences") ?? [];
+    const defaultVisibility = scalarValue(fm, "default_visibility") ?? "";
+    if (fm.keys.has("audiences") && audiences.length === 0) {
+      const value = fm.keys.get("audiences");
+      problem(
+        "instance.md",
+        value === ""
+          ? "audiences: declares no audiences"
+          : `audiences is a list, not a value: ${value}`,
+        "the audience list is the record's whole access model, ordered least- to most-restricted — with nothing in it, no document's visibility: can be answered",
+        "write it as list items:\n      audiences:\n        - public\n        - internal",
+      );
+    } else if (audiences.length > 0) {
+      if (audiences[0] !== "public") {
+        problem(
+          "instance.md",
+          `audiences: does not start with public (it starts with "${audiences[0]}")`,
+          "the order is the restriction level, and that ordering is what makes an internal build mean public-and-internal with no further configuration — public is the least restricted tier by definition",
+          "list public first, then each narrower audience in turn",
+        );
+      }
+      const seen = new Set();
+      for (const audience of audiences) {
+        if (seen.has(audience)) {
+          problem(
+            "instance.md",
+            `duplicate audience: ${audience}`,
+            "an audience's position in the list is its restriction level — named twice, it has two levels and neither can be trusted",
+            `keep one ${audience} entry`,
+          );
+        }
+        seen.add(audience);
+      }
+      if (defaultVisibility === "") {
+        problem(
+          "instance.md",
+          "audiences: without default_visibility:",
+          "there is no safe inference for a document that declares no audience: guessing the widest leaks the first document whose key is forgotten, guessing the narrowest hides the record from everyone it was written for",
+          `add default_visibility: — one of ${audiences.join(", ")} — the audience a document belongs to when it declares none`,
+        );
+      } else if (!audiences.includes(defaultVisibility)) {
+        problem(
+          "instance.md",
+          `default_visibility "${defaultVisibility}" is not one of the declared audiences`,
+          "every document without a visibility: key takes this value — a default outside the list puts most of the record in an audience that does not exist",
+          `use one of: ${audiences.join(", ")}`,
+        );
+      }
+    } else if (fm.keys.has("default_visibility")) {
+      problem(
+        "instance.md",
+        "default_visibility: without audiences:",
+        "a default audience with no audience list is a setting with nothing to select from — the owner believes the record has a visibility model while every surface publishes every document to everyone",
+        "add audiences: (ordered least- to most-restricted, public first), or remove default_visibility:",
+      );
+    }
     for (const [parent, allowed] of [
       ["ksor", INSTANCE_KSOR_KEYS],
       ["site", INSTANCE_SITE_KEYS],
+      ["database", INSTANCE_DATABASE_KEYS],
+      ["embedding", INSTANCE_EMBEDDING_KEYS],
+      ["retrieval", INSTANCE_RETRIEVAL_KEYS],
+      ["budgets", INSTANCE_BUDGETS_KEYS],
     ]) {
       for (const key of fm.children.get(parent)?.keys() ?? []) {
         if (!allowed.has(key)) {
@@ -757,6 +986,9 @@ if (existsSync(siteDir)) {
       (p) =>
         !p.includes(`${path.sep}.next${path.sep}`) &&
         !p.includes(`${path.sep}.source${path.sep}`) &&
+        // The per-audience stage: generated copies of the record a build makes
+        // for one audience, never authored content (specs/ksor/visibility).
+        !p.includes(`${path.sep}.staged-knowledge${path.sep}`) &&
         !p.includes(`${path.sep}out${path.sep}`),
     )
     .filter((p) => p.toLowerCase().endsWith(".md") || p.toLowerCase().endsWith(".mdx"));

package/templates/scaffold/.claude/skills/intake-interview/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: intake-interview
-description: The first conversation with the owner of this Knowledge System of Record — five questions that define what it is authoritative for, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
+description: The first conversation with the owner of this Knowledge System of Record — six questions that define what it is authoritative for and who may read it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
 metadata:
-  version: "1.1.0"
+  version: "1.3.0"
 ---
 
 # Intake interview
 
 `instance.md` is the identity of this Knowledge System of Record, and its
-prose will one day be the agent surface's system prompt. Do not draft it from
-guesses — interview the owner, one question at a time, and write down what
-they actually say.
+prose IS the agent surface's system prompt (`ksor serve` wires it into the MCP
+server's instructions). Do not draft it from guesses — interview the owner, one
+question at a time, and write down what they actually say.
 
-## The five questions
+## The six questions
 
 Ask these one at a time; follow up until each answer is concrete enough to
 act on:
@@ -30,6 +30,18 @@ act on:
 5. **Strictness** — "When the record doesn't cover a question, how firmly
    should it decline? ('Not in this corpus' is a correct answer here —
    confirm the owner wants that behavior and where they want it softened.)"
+6. **Audiences** — "Does every reader of this record see every document? If
+   not, what are the audiences, from most public to most restricted?" A yes
+   is the common answer and the whole answer: write no `audiences:` key and
+   nothing about the project changes. A list means writing it into
+   `instance.md`'s frontmatter — ordered least- to most-restricted with
+   `public` first, plus `default_visibility:` naming the audience a document
+   takes when it says nothing (there is no safe guess, so the checker
+   requires it). Tell the owner what the key does and does not do:
+   documents carry `visibility:` and builds are made per audience, but
+   anyone who can clone the repository reads everything in it — if someone
+   must not read a document and can clone, that document belongs in a
+   different repository.
 
 ## Then write
 
@@ -37,7 +49,15 @@ act on:
   record's **display title**, the human name every page will lead with
   ("Acme Operations Handbook", not the slug) — then the authority sentence,
   boundary, audience, and strictness — plain prose, written for a reader
-  who must act on it. Do not touch the frontmatter keys.
+  who must act on it. Leave the identity frontmatter keys alone; two things
+  are written there when they apply: an audience model from question 6, as
+  `audiences:` (a list) and `default_visibility:` (`pnpm check` holds the
+  record to it from that moment on); and — only when the owner stands up the
+  served MCP rung — the `database:`/`embedding:`/`retrieval:` blocks (see
+  `AGENTS.md` → "Serving to agents"; that is a later climb, not part of this
+  interview). The strictness answer from question 5 is the intent behind the
+  `retrieval.vector_floor` on that climb, measured by `ksor calibrate` — capture
+  it in the prose now so it is ready.
 - Restart `pnpm dev` afterwards so the site picks the new title up, and
   show the owner their name on the page.
 - Offer to capture the source list from question 4 as the first real

package/templates/scaffold/AGENTS.md

@@ -5,19 +5,25 @@ here; every coding agent reads this file first.
 
 ## The two worlds
 
-| Path          | What it is                                                                                                                                                                                                                                                                                                                                  |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `knowledge/`  | **the record** — governed markdown, the owner's world, the product                                                                                                                                                                                                                                                                          |
-| `system/`     | **the system** — all code that serves the record                                                                                                                                                                                                                                                                                            |
-| `instance.md` | what this SoR is authoritative for; its prose is the future agent surface's system prompt. Its `name:` is the machine identity (llms.txt, future citations) and its body `# H1` is the DISPLAY TITLE every page leads with — both read when the server or build STARTS, so restart `pnpm dev` after changing either (found live 2026-08-18) |
+| Path          | What it is                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `knowledge/`  | **the record** — governed markdown, the owner's world, the product                                                                                                                                                                                                                                                                                                                             |
+| `system/`     | **the system** — all code that serves the record                                                                                                                                                                                                                                                                                                                                               |
+| `instance.md` | what this SoR is authoritative for; its prose IS the agent surface's system prompt (`ksor serve` wires the body into the MCP server's instructions). Its `name:` is the machine identity (llms.txt, citations) and its body `# H1` is the DISPLAY TITLE every page leads with — both read when the server or build STARTS, so restart `pnpm dev` after changing either (found live 2026-08-18) |
 
 The record survives the system: `knowledge/` must stay readable and complete
 even if `system/` is deleted. Dependency flows one way — the system reads the
 record; the record never references the system.
 
-`instance.md` carries a closed key set — `format`, `name`, `ksor`, `site` —
-and everything that matters about it is the prose below that frontmatter;
-`pnpm check` names any other key rather than ignoring it.
+`instance.md` carries a closed key set — `format`, `name`, `ksor`, `site`,
+the optional pair `audiences` + `default_visibility` (the record's reader
+audiences, ordered least- to most-restricted with `public` first, and the one
+a document takes when it names none — declared together or not at all), and
+the four serve-config blocks `database` / `embedding` / `retrieval` / `budgets`
+(present only once you climb to the served MCP rung — see "Serving to agents"
+below; a `pnpm dev`-only project declares none). Everything else that matters
+about the instance is the prose below the frontmatter; `pnpm check` names any
+other key rather than ignoring it.
 
 ## Critical rules
 
@@ -27,17 +33,121 @@ and everything that matters about it is the prose below that frontmatter;
 2. **`knowledge/` is CommonMark `.md` only.** No `.mdx`, no `meta.json`, no
    framework files. A document must read cleanly in any markdown viewer.
 3. **Never edit generated files** — `system/site/.source/`, `.next/`, `out/`,
+   `system/site/.staged-knowledge/` (a build's per-audience copy of the
+   record — edit `knowledge/`, or the next build erases the change),
    lockfiles by hand.
 
 ## Commands (run at the repo root)
 
 ```sh
-pnpm install     # once, after cloning or scaffolding
+pnpm install     # once, after cloning or scaffolding (also fetches the pinned `ksor` tool)
 pnpm dev         # the site, hot-reloading, at http://localhost:3000
 pnpm build       # static site into system/site/out/
 pnpm check       # the format checker — run before handing off any knowledge change
 ```
 
+## Serving to agents — the MCP rung (needs Postgres + a provider key)
+
+`ksor serve` runs an MCP server over the record so agents get cited retrieval
+with honest abstention. It is the climbed rung — not required for `pnpm dev`.
+Stand it up in this order (each step's errors explain how to fix themselves):
+
+1. **Configure `instance.md`.** Add the serve blocks to the frontmatter
+   (`pnpm check` accepts them; the kernel validates their values):
+
+   ```yaml
+   database:
+     dsn_env: KSOR_DB_URL # the NAME of the env var holding the DSN — never the DSN itself
+   embedding:
+     provider: gemini # default; the seam, not the vendor, is the contract
+     model: gemini-embedding-001
+     dim: 1536 # ≤ 2000 for the pgvector HNSW index
+   retrieval:
+     vector_floor: uncalibrated # see step 6; `uncalibrated` REFUSES every serve until you paste a number
+   ```
+
+2. **Provision Postgres** with the `vector` extension (`CREATE EXTENSION vector`),
+   e.g. a Neon database. Export the DSN under the name `dsn_env` chose, plus the
+   provider key:
+
+   ```sh
+   export KSOR_DB_URL='postgresql://…'   # the var instance.md names
+   export GEMINI_API_KEY='…'             # the embedding provider key
+   ```
+
+3. **Apply the schema:** `pnpm schema` (creates tables, indexes, and the
+   ingest role).
+
+4. **Authorize ingest:** `pnpm grant` — writes the one row row-level security
+   requires before any write to this corpus is allowed. Idempotent, and
+   `pnpm exec ksor grant --instance instance.md --revoke` withdraws it.
+
+   This is a separate, named act on purpose: applying the schema and
+   authorizing writes are different decisions, and a schema step that granted
+   itself write access would make the tool its own authorizer. Apply the schema
+   and ingest as the SAME Postgres login (the ingest role is granted to whoever
+   applied the DDL).
+
+5. **Ingest:** `pnpm ingest` — embeds `knowledge/` into a fresh generation and
+   activates it (`--flip`). Safe to re-run (see the generation model below).
+
+6. **Calibrate the abstention floor** (only if `vector_floor: uncalibrated`):
+   `pnpm exec ksor calibrate --instance instance.md` prints a recommended
+   `vector_floor` measurement; paste the number into `instance.md`'s `retrieval:`
+   block and re-run. A corpus that declares no `retrieval:` block serves with the
+   gate OFF (honest: it will not refuse out-of-corpus questions).
+
+7. **Serve:** `pnpm serve`.
+
+```sh
+pnpm schema      # apply the DDL (once)
+pnpm grant       # authorize ingest for this corpus (once)
+pnpm ingest      # embed knowledge/ into a generation and activate it
+pnpm serve       # run the MCP server; any other verb: pnpm exec ksor <verb>
+```
+
+### How serving updates work (the generation model)
+
+Each `ksor ingest` builds a **fresh generation** (invisible until activated) and
+carries every unchanged embedding forward from the last complete generation —
+so **re-ingest is safe and cheap**; only changed or failed chunks re-embed.
+`--flip` swaps the active pointer, guarded by a catastrophic-shrink check
+(`KSOR_MAX_SHRINK`, default `0.15` — a flip that drops more than 15% of nodes
+refuses; override with `KSOR_ALLOW_SHRINK=1` when the shrink is intended). The
+previous generation stays as a rollback target; `pnpm exec ksor gc` collects
+abandoned ones.
+
+### Serving safely (fail-closed posture)
+
+`pnpm serve` binds **loopback with auth off** — safe for local use. A **public**
+bind refuses to boot unless auth is configured (`KSOR_SSO_URL` +
+`KSOR_MCP_RESOURCE_URL` + `KSOR_JWT_ALLOWED_AUDIENCES`, making it an OAuth
+Resource Server) OR you deliberately set `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1`.
+Never let a dropped auth variable silently ship an open door. On a non-loopback
+bind, set `KSOR_ALLOWED_HOSTS` / `KSOR_ALLOWED_ORIGINS`; on more than one
+replica, set a shared `KSOR_SNAPSHOT_KEYS` (unset ⇒ a per-process key, so a
+search token minted by one replica fails on another).
+
+Two things worth being deliberate about:
+
+- **`KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` serves your whole record to anyone
+  who can reach the port.** It exists for deployments fronted by your own
+  gateway or network policy. If nothing else is in front, do not set it.
+- **Set `KSOR_SSO_ISSUER` when your SSO stamps a stable `iss`.** Audience is
+  always enforced against `KSOR_JWT_ALLOWED_AUDIENCES`; naming the issuer adds
+  one more check for the cost of one variable.
+
+## Publishing
+
+`pnpm build` emits a fully static site (`system/site/out/`) deployable to
+any host — Vercel reads the shipped `vercel.json` (deploy from the repo
+ROOT, never `system/site/`), and every other host just serves the folder.
+`KSOR_BASE_PATH=/repo pnpm build` targets sub-path hosting. With
+`audiences:` declared, plain `pnpm build` is always the public tier;
+`KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier that belongs
+behind that audience's own access control, never on a public host.
+Details in README → Deploying.
+
 ## Writing knowledge
 
 - One document per file under `knowledge/`; the path is the document's
@@ -51,10 +161,23 @@ pnpm check       # the format checker — run before handing off any knowledge c
 - Frontmatter: `title` and `status` (`draft | review | approved | superseded`)
   are required. `owner` and `provenance` (a list naming real sources) are
   strongly encouraged — they become required as this project climbs the
-  governance ladder. `description`, `order` (sidebar position), `effective`
-  (the date the document takes effect) and `superseded` (a legacy marker —
-  prefer `status`) are available. No other keys; never `id:` or `name:` — the
-  path is the identity.
+  governance ladder. `description`, `visibility` (below), `order` (sidebar
+  position), `effective` (the date the document takes effect) and `superseded`
+  (a legacy marker — prefer `status`) are available. No other keys; never
+  `id:` or `name:` — the path is the identity.
+- `visibility:` names the one audience a document belongs to — a single value
+  from `instance.md`'s `audiences:`, never a list, and orthogonal to `status:`
+  (an approved document can be restricted, and a draft is not hidden). Leave
+  it off and the document takes `default_visibility`. The key does nothing
+  until `instance.md` declares `audiences:`; once it does, `pnpm check`
+  refuses any link or `superseded_by:` pointing from a wider audience at a
+  narrower one — the leak no single build can catch, because the build that
+  publishes the link has already dropped its target.
+
+  **Publication, not authorship: anyone who can clone the repository reads
+  every document regardless of frontmatter; if someone must not read a
+  document and can clone, the answer is a second repository.**
+
 - A replaced document is marked `status: superseded` with `superseded_by:`
   pointing at its successor — superseded documents are never deleted.
 - Images and assets live in `knowledge/` beside the document that uses them,
@@ -94,7 +217,7 @@ You own `system/site/` outright — these are the seams, cheapest first:
   and the home-page mark are the same file.
 - **Anything deeper** — edit the site like the Next.js app it is; the only
   rule that survives customization is critical rule 1. The whole shell is
-  replaceable behind a four-clause contract (a themed Docusaurus shell with
+  replaceable behind a five-clause contract (a themed Docusaurus shell with
   a swap recipe lives in the ksor repository under `workbench/shells/`).
 
 ## What this project owns