@panaversity/ksor 0.0.29 → 0.0.31

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # @panaversity/ksor
 
+## 0.0.31
+
+### Patch Changes
+
+- c69232d: Adversarial coverage for the MCP door (issue #33), first slice: the governance
+  leak sweep and cross-replica snapshot behaviour.
+
+  **A withdrawn document must not appear in any field of any reachable response.**
+  The existing takedown test proves each serving arm behaves at the arms someone
+  thought of. This one plants an unguessable marker inside the withdrawn document
+  — in its body _and its title_ — and asserts the marker appears nowhere in the
+  serialized result, across eighteen request shapes: search by body, by marker, by
+  title words, at several limits, keyword search, `topOneScore`, read by
+  stable_id / slug / qualified path, and outline at every anchor and page. A leak
+  into a field the test has never heard of still fails it.
+
+  It carries a **positive control**, because every other assertion is a
+  not-contains and a probe that could never see the marker would pass them all
+  while proving nothing: each shape runs before the takedown and the ones that
+  testify are required to have found it first.
+
+  It also covers the subtlest case, which carries no content at all — `topOneScore`
+  feeds the abstention gate, so a withdrawn document scoring there would let a
+  record claim coverage on the strength of text it refuses to show.
+
+  **Cross-replica snapshot tokens**, listed in #33 as "documented, untested" and
+  since found on a real deployment: two processes with no `KSOR_SNAPSHOT_KEYS`
+  produce tokens neither can verify from the other, and the verdict is `invalid`
+  rather than `unknown_key` — the key _id_ matches and only the secret differs,
+  which is why the failure is invisible until you read it. Also pins rotation
+  (outstanding tokens survive while the old key is listed, and die when it is
+  dropped) and cross-deployment refusal.
+
+- d96b139: Presentations, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry `<doc>.slides.yaml`. It renders at the
+  top of that document's page — before the prose, because a deck is the shape of
+  the thing and gives the detail somewhere to land.
+
+  **Ask your coding agent and it writes the deck.** `make slides for
+knowledge/expenses/approvals.md` runs the new `make-slides` skill, which reads
+  the document whole, writes the slides, checks every claim and every number back
+  against it, 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. No browser, no
+  third-party tool, no step where a person takes over.
+
+  **The record owns the deck by default.** `deck:` carries the slides themselves
+  and the site renders them, which is the only mode where a presentation is
+  governed: reviewed in the same pull request as its document, versioned with it,
+  withdrawn when it is withdrawn, and incapable of rotting into a dead link. Every
+  slide ships in the server-rendered HTML, so a reader without JavaScript, a
+  crawler and an agent parsing the page all get the whole deck. Presenter notes
+  render outside the slide, so they are not projected in fullscreen.
+
+  **A deck you keep elsewhere** can be embedded instead — `slides.url:`, with the
+  embed url derived for Google Slides, Canva and SlideShare. Its frame is
+  click-to-load: nothing is requested from the host until a reader asks for it, so
+  a page still makes zero external requests and a reader who only wanted the
+  policy never announces that to a slide host. Declaring both modes is refused
+  (`ksor-slides-two-sources`) — two presentations with nothing to say which one
+  governs is the disagreement a system of record exists to settle. `http` urls are
+  refused too, since a browser blocks a mixed-content frame silently.
+
+  Like every attachment, a deck has no URL, no sidebar row, no `llms.txt` line and
+  no id an agent can cite, and it takes its `visibility:` and any takedown from its
+  parent.
+
+## 0.0.30
+
+### Patch Changes
+
+- fbf149b: Quizzes, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry `<doc>.quiz.yaml` beside its summary
+  and its flashcard deck. It renders at the end of the document's page, under the
+  deck: choose an option, see immediately whether you were right, and read the
+  explanation before moving on. There is no pass mark — a quiz here checks
+  understanding of the record, it does not certify anybody — and answers stay in
+  the reader's own browser.
+
+  A quiz is **part of its document, not a document**: no URL, no sidebar row, no
+  `llms.txt` line, no markdown twin, no search entry, and no stable id. That last
+  one settles a question worth being explicit about: because `ksor ingest` creates
+  no node for a quiz, **the answer key cannot reach the MCP surface at all**.
+  There is nothing for an agent to search and nothing for it to read — not by a
+  filter that could be forgotten, but because the row does not exist. Governance
+  inherits from the parent exactly as the summary and the deck already do.
+
+  **`pnpm check` and `pnpm build` refuse a quiz a reader could pass without
+  reading it**, naming the questions to fix:
+
+  - `ksor-quiz-answer-bias` — more than 60% of answers at one option position
+  - `ksor-quiz-length-bias` — picking the longest or shortest option usually wins
+  - `ksor-quiz-answer-run` — four or more questions in a row share an answer
+  - `ksor-quiz-contradiction` — an explanation calls the marked answer wrong
+  - `ksor-quiz-duplicate-stem` — two questions open with the same 60 characters
+
+  These are carried from the predecessor, where the same mistakes shipped and were
+  found by readers rather than by the project — one quiz put every correct answer
+  in the same position across 451 questions. There they lived in a script that was
+  run once; here they are part of loading the file, so a quiz that fails them
+  cannot be published. The ratio rules do not apply below five questions, where
+  enforcing a spread would mean choosing an author's answers for them.
+
+  `ksor init` ships a quiz on the seed document, so a first `pnpm dev` shows the
+  shape. Its own first draft was refused for putting four of five answers at
+  option B — the check catching exactly what it was carried for.
+
 ## 0.0.29
 
 ### Patch Changes

package/README.md

@@ -32,6 +32,30 @@ scaffold is deterministic and offline, and every refusal explains itself.
 > and the released version number are authoritative for the exact released
 > functionality.
 
+### Study attachments
+
+A document may carry companions named after it, and the site renders each on
+that document's page and nowhere else:
+
+| File                    | What it is                                             |
+| ----------------------- | ------------------------------------------------------ |
+| `<doc>.summary.md`      | a précis, shown as a second tab beside the document     |
+| `<doc>.slides.yaml`     | a presentation, at the top of the page                  |
+| `<doc>.flashcards.yaml` | a recall deck, at the end                               |
+| `<doc>.quiz.yaml`       | a multiple-choice check, at the end                     |
+
+Ask your coding agent — `make slides for knowledge/expenses/approvals.md` —
+and the `make-slides` skill writes the deck from the document, checks every
+claim and number back against it, and reports what it left out because the
+document did not support it.
+
+An attachment is **part of its document**: no URL, no sidebar row, no
+`llms.txt` line, and no id an agent can cite. It takes its `visibility:` and
+any takedown from its parent, so restricting the document restricts them all.
+A quiz whose answers are guessable is refused by the build, and because ingest
+creates no node for an attachment, a quiz's answer key can never reach the
+agent surface at all.
+
 Full concept, design goals, and project status:
 **<https://github.com/panaversity/ksor>**
 

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
-import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-6nC9x54K-BWFTI_6U.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-C-OMrGGt.mjs
+//#region ../content-gateway/dist/main-DdIuyneg.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -1583,7 +1583,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-DU1nqwZa.mjs
+//#region ../content/dist/commands-mZxv9bLG.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4208,6 +4208,14 @@ const ATTACHMENT_SUFFIXES = [
 	{
 		suffix: ".flashcards.yaml",
 		kind: "deck"
+	},
+	{
+		suffix: ".quiz.yaml",
+		kind: "quiz"
+	},
+	{
+		suffix: ".slides.yaml",
+		kind: "slides"
 	}
 ];
 /**

package/dist/{gateway-api-8lNruq9e-CuohjtoK.mjs → gateway-api-6nC9x54K-BWFTI_6U.mjs}

@@ -5,7 +5,7 @@ import { z, z as z$1 } from "zod";
 import pg from "pg";
 import path from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region ../content-gateway/dist/gateway-api-8lNruq9e.mjs
+//#region ../content-gateway/dist/gateway-api-6nC9x54K.mjs
 /**
 * The record's system prompt: instance.md's body, preserved beneath a framework
 * floor. Lifted out of server.ts so the public gateway surface can re-export

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-6nC9x54K-BWFTI_6U.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/package.json

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

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

@@ -41,7 +41,13 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [
+  ".summary.md",
+  ".summary.mdx",
+  ".flashcards.yaml",
+  ".quiz.yaml",
+  ".slides.yaml",
+];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +55,10 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
+  [".slides.yml", ".slides.yaml"],
+  [".slides.json", ".slides.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

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

@@ -0,0 +1,160 @@
+---
+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** — `owner`, `effective`, `status` 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, frontmatter, or a malformed deck
+pnpm dev       # look at the page — the deck renders at the end
+```
+
+`pnpm build` refuses:
+
+- `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
+- `ksor-attachment-frontmatter` — an attachment carries none of its own
+
+## 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.

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

@@ -41,7 +41,13 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [
+  ".summary.md",
+  ".summary.mdx",
+  ".flashcards.yaml",
+  ".quiz.yaml",
+  ".slides.yaml",
+];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +55,10 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
+  [".slides.yml", ".slides.yaml"],
+  [".slides.json", ".slides.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

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

@@ -0,0 +1,160 @@
+---
+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** — `owner`, `effective`, `status` 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, frontmatter, or a malformed deck
+pnpm dev       # look at the page — the deck renders at the end
+```
+
+`pnpm build` refuses:
+
+- `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
+- `ksor-attachment-frontmatter` — an attachment carries none of its own
+
+## 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.