@panaversity/ksor 0.0.54 → 0.0.56

package/templates/scaffold/README.md

@@ -111,9 +111,9 @@ Before changing anything, get a feel for how the record behaves. With
 - **Ask your coding agent to do the same.** `AGENTS.md` carries the working
   rules; read it before you change how documents are written here. The kit in
   `.agents/skills/` already knows this project: `intake-interview` (define the
-  record with you), `add-sources` (turn source material into governed
-  documents), `make-slides`, `make-summary`, and `format-checker` (the rules,
-  as a program — also what `pnpm check` runs).
+  record with you), `add-sources` (turn what you have — files, or what you
+  know — into governed documents), and `format-checker` (the rules, as a program — also what
+  `pnpm check` runs).
 
 **Treat the starters as scratch paper.** They ship approved by
 `ksor-starter/KSOR-STAMP-VERSION` — a tool, not a person. Edit the body and that
@@ -174,7 +174,26 @@ the variable name here only if you want a different one.
 ### 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:
+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
@@ -254,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** —
@@ -288,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.
 
 ---
 
@@ -382,11 +400,22 @@ wrong thing describes it on every surface. So replace them, in this order:
    approve or withdraw a document — then it writes `instance.md` with you and
    replaces the `human:you` placeholder in `.ksor/governance.yaml` with your
    real handle.
-2. **Delete each starter document** as your own knowledge arrives.
-3. **When the last one is gone, delete `ksor-starter/KSOR-STAMP-VERSION` from
+2. **Write and approve at least one document of your own** — ask your agent
+   to add it (the `add-sources` skill), read it on `pnpm dev`, then approve it.
+   A record is never empty: delete all five starters before this and the next
+   build refuses `ksor-record-empty` and writes nothing.
+3. **Delete each starter document** as your own knowledge arrives.
+4. **When the last one is gone, delete `ksor-starter/KSOR-STAMP-VERSION` from
    `approval_authorities` in `.ksor/governance.yaml`.** Nothing of yours should
    be approved by a tool.
 
+If you did the hello-world tutorial first, your document is approved by
+`human:you`. The interview replaces that placeholder with your real handle —
+and re-attributes every act already recorded under it to you in the same
+change, because it is the same person. A policy that no longer names
+`human:you` beside a document that still cites it refuses
+`ksor-approver-unauthorised`.
+
 ---
 
 ## Writing knowledge
@@ -452,7 +481,7 @@ record:
 make slides for knowledge/expenses/approvals.md
 ```
 
-The `make-slides` skill reads the document whole, writes the deck into
+Your agent reads the document whole, writes the deck into
 `knowledge/expenses/approvals.slides.yaml`, checks every claim and every number
 back against the document, and tells you what it left out because the document
 did not support it — which is usually how you find out a document has a gap. The
@@ -476,7 +505,7 @@ way:
 summarise knowledge/expenses/approvals.md
 ```
 
-The `make-summary` skill reads the document whole, writes
+Your agent reads the document whole, writes
 `knowledge/expenses/approvals.summary.md`, and checks every line back against
 the document — every number, every rule, and every `##` section, because a
 summary that covers the opening and trails off is worse than none: a reader who
@@ -487,7 +516,7 @@ The summary is part of its document, not a document of its own: no route, no
 sidebar row, no line in `llms.txt`, and it takes its governance from its parent.
 Ask for one only where there is something to compress — under about two screens,
 a summary that restates the page teaches readers the tab is not worth opening,
-and the skill will say so rather than write one.
+and a good agent will say so rather than write one.
 
 ---
 
@@ -664,7 +693,7 @@ different coding agent's way of finding the same working contract.
 | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `AGENTS.md`                      | the working contract every coding agent reads first — the rules for writing knowledge here.                                                                                                             |
 | `CLAUDE.md`                      | one line, pointing at `AGENTS.md`. Claude Code looks for this filename, not that one.                                                                                                                   |
-| `.agents/skills/`                | the agent kit: `intake-interview` (define the record with you), `add-sources` (turn source material into governed documents), `make-slides`, `make-summary`, `format-checker` (the rules, as a program). |
+| `.agents/skills/`                | the agent kit: `intake-interview` (define the record with you), `add-sources` (turn files, or what you know, into governed documents), `format-checker` (the rules, as a program).                          |
 | `.claude/skills/`                | byte-identical copies of the kit — Claude Code discovers skills only here. The checker enforces the mirror, so the two cannot drift.                                                                     |
 | `.gemini/settings.json`          | points Gemini CLI at `AGENTS.md`; Gemini does not read that filename on its own.                                                                                                                        |
 | `.github/workflows/validate.yml` | your CI: runs the same checker on every pull request and push to main.                                                                                                                                  |
@@ -693,6 +722,8 @@ map rather than a substitute.
 | the agent answers questions 2 and 3 instead of declining             | no floor is measured, so the gate is off (`abstain OFF`, `gate: "off"`) — step 3's `calibrate` was skipped  | `pnpm exec ksor calibrate --instance instance.md`, paste the block, restart             |
 | a deployed door serves an empty record                               | deploying does not publish — and a laptop DSN is unreachable from the host                                 | point both at one hosted Postgres, then `pnpm refresh`                                 |
 | the home page and `/llms.txt` are empty                              | every document is still a draft — correct, not broken                                                      | approve one and rebuild                                                                |
+| `ksor-record-empty`                                                  | every document was deleted — a record is never empty, so nothing was written                               | add one document of your own (or restore one from git) before deleting the last starter |
+| `ksor-approver-unauthorised`                                         | a document is approved by an actor `.ksor/governance.yaml` no longer names — usually `human:you` after the interview | re-attribute the approval to your handle, or restore the actor to `approval_authorities` |
 | a new document never appears on the built site                       | drafts reach no built surface at all                                                                       | publish it — `status: stable` plus both governance keys                                |
 | an expired document still shows on the site but not through the door | the static build evaluated `stale_after` at build time                                                     | rebuild and redeploy; schedule a rebuild if you use it                                 |
 | Vercel: `no services are declared`                                   | Root Directory was auto-filled with `system/site`                                                          | set it to `./`                                                                         |

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/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 },

package/templates/scaffold/.agents/skills/make-slides/SKILL.md

@@ -1,162 +0,0 @@
----
-name: make-slides
-description: Generate a presentation from one document and attach it, so it renders on that document's page. Use when the owner says "make slides for X", "turn this into a deck", "I need to present this", asks for a teaching aid or a slideshow, or when onboarding needs a session rather than a page.
-metadata:
-  version: "2.0.0"
----
-
-# Generating a presentation for a document
-
-You write the slides. Not an outline for somebody else to build — the actual
-deck, into `<doc>.slides.yaml`, which the site renders on that document's page.
-No browser, no third-party tool, no step where a human takes over.
-
-Run it end to end: read the document, write the deck, check every line back
-against the document, verify it builds. **The check is not optional** — it is
-the step that keeps the record's guarantee true.
-
-## The one rule everything else serves
-
-**A slide may only say what the document says.**
-
-The deck is a way of presenting the record, never a second source. A slide
-asserting a threshold the document does not contain is a claim nothing governs
-and no agent can cite — and because the deck is an attachment, the record now
-stands behind it. Every number, date, name and rule is copied from the
-document exactly, units included.
-
-If the document does not say something you want on a slide, there are two
-honest options: leave it out, or tell the owner the document is missing it.
-Never a third.
-
-## 1 · Read the document whole, first
-
-Read `<doc>.md` completely before writing anything. Note as you go:
-
-- **the decision it settles** — the reason it exists
-- **the rule, in its own words** — usually one or two sentences
-- **the numbers** — thresholds, deadlines, limits, and their units
-- **the cases** — what happens in each situation it names
-- **the boundary** — what it explicitly does NOT cover
-- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
-  the frontmatter
-
-If the document carries `<doc>.summary.md`, read that too: it is a reviewed
-compression of the same thing, and it tells you what the author thought was
-load-bearing.
-
-## 2 · Write the deck
-
-Write `<doc>.slides.yaml` beside the document:
-
-```yaml
-slides:
-  title: Expense approvals
-  description: The 15-minute version, for a room.
-deck:
-  - heading: What this settles
-    lead: One sentence, in the document's own words.
-    note: What to say here. Spoken, never shown.
-
-  - heading: The rule
-    bullets:
-      - Two approvers above the threshold, always
-      - The threshold is per invoice, including tax
-    note: Pause here. This is the slide people remember wrong.
-```
-
-**Per slide:**
-
-| Field     | Use                                                          |
-| --------- | ------------------------------------------------------------ |
-| `heading` | required — a statement, not a label. "The rule", not "Rules" |
-| `lead`    | one sentence, for a slide making a single point              |
-| `bullets` | three to five. Six is the cap, and six is already too many   |
-| `note`    | what the presenter SAYS — never a repeat of the slide        |
-
-**Per deck** — 8 to 14 slides for an ordinary policy document:
-
-1. What this settles, and for whom
-2. Why it exists — the decision behind it
-3. The rule itself, stated once
-4. One slide per case, with the real numbers
-5. What people get wrong, and what is true instead
-6. The boundary — what this document does not cover
-7. Where to find it: the route, the owner, the effective date
-
-**Habits that decide whether it is any good:**
-
-- **A heading is a claim.** "Recency is not authority" teaches; "Authority"
-  does not.
-- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
-- **The note carries the argument.** The slide holds the shape; the presenter
-  holds the reasoning. A note repeating the bullets is a wasted field.
-- **Do not pad to a target.** Five slides of substance beat twelve with three
-  that exist to reach twelve.
-
-## 3 · Check every line against the document
-
-Go back through slide by slide with the document open. For each:
-
-- Is every claim in the document? Name where.
-- Is every number identical, same units, same rounding?
-- Does any slide imply a rule the document does not state?
-- Does the boundary slide match what the document actually excludes?
-
-This pass finds real errors, reliably. A transcription slip in a deck outlives
-the session it was made for, because the next presenter trusts it.
-
-## 4 · Verify it
-
-```sh
-pnpm check     # refuses an orphan deck
-pnpm dev       # look at the page — the deck renders after the introduction,
-               # immediately before the first `##` section
-```
-
-`pnpm build` refuses — the deck's own shape is checked in the site build, not
-by `pnpm check`:
-
-- `ksor-slides-empty` — neither `deck:` nor `slides.url:`; nothing to show
-- `ksor-slides-two-sources` — both, so nothing says which one governs
-- `ksor-attachment-orphan` — no `<doc>.md` beside it
-
-## 5 · Tell the owner what you did
-
-Which document, how many slides, and **anything you left out because the
-document did not support it**. That last part is the useful half: it is how an
-owner finds out their document has a gap.
-
-## Embedding a deck made elsewhere
-
-If the owner already has a deck in Google Slides, Canva or SlideShare, use the
-linked mode — `slides.url:` and no `deck:`:
-
-```yaml
-slides:
-  title: Expense approvals
-  url: https://docs.google.com/presentation/d/<id>/edit?usp=sharing
-```
-
-The embed url is derived for those three providers; for anything else add
-`embed:` explicitly or it renders as a link. `url` must be https — a browser
-blocks a mixed-content frame silently, so an http one publishes a panel that
-never loads.
-
-**Prefer the record-owned deck.** A linked deck is not reviewed in a pull
-request, not versioned with its document, not withdrawn when the document is,
-and can rot to a dead link with nothing going red. Use the link when the deck
-already exists and somebody else maintains it — not as the default.
-
-## What NOT to do
-
-- **Do not put the deck in the document.** No `<iframe>`, no raw HTML.
-  `knowledge/` is CommonMark and must read cleanly in any markdown viewer.
-- **Do not write a slide the document cannot support**, even a true one. If it
-  is not in the record, the record cannot stand behind it.
-- **Do not make one deck for several documents.** A deck belongs to one
-  document, the way a summary does. A deck spanning five policies has no
-  document to be governed by and nothing to be withdrawn with.
-- **Do not patch a stale deck.** When the document changes materially,
-  regenerate from it. Patching is how a deck and its document drift, and a
-  deck that drifts starts winning arguments it should lose.