@panaversity/ksor 0.0.30 → 0.0.31

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @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

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-CbFkHZiU-HvlJRjRB.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-CS5a_8OW.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-CLUS9CX8.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
@@ -4212,6 +4212,10 @@ const ATTACHMENT_SUFFIXES = [
 	{
 		suffix: ".quiz.yaml",
 		kind: "quiz"
+	},
+	{
+		suffix: ".slides.yaml",
+		kind: "slides"
 	}
 ];
 /**

package/dist/{gateway-api-CbFkHZiU-HvlJRjRB.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-CbFkHZiU.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-CbFkHZiU-HvlJRjRB.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.30",
+  "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", ".quiz.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.
@@ -51,6 +57,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".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", ".quiz.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.
@@ -51,6 +57,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".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.

package/templates/scaffold/AGENTS.md

@@ -506,12 +506,15 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   refused.
 - Images and assets live in `knowledge/` beside the document that uses them,
   referenced by relative links. A relative link must never leave `knowledge/`.
-- **Study attachments.** A document may carry three optional companions named
+- **Study attachments.** A document may carry four optional companions named
   after it, in the same folder: `<doc>.summary.md` (a short précis),
-  `<doc>.flashcards.yaml` (a recall deck) and `<doc>.quiz.yaml` (a
-  multiple-choice check). The summary appears as a second tab beside the
-  document's own words; the deck and the quiz appear at the END of that
-  document's page. None of them appears anywhere else in the site.
+  `<doc>.slides.yaml` (a presentation), `<doc>.flashcards.yaml` (a recall deck)
+  and `<doc>.quiz.yaml` (a multiple-choice check). The summary appears as a
+  second tab beside the document's own words; the presentation appears at the
+  TOP of the page, before the document, because a deck is the shape of the
+  thing and gives the detail somewhere to land; the deck and the quiz appear at
+  the END, because those are used after reading. None of them appears anywhere
+  else in the site.
 
   An attachment is **part of its document**, not a document. It has no URL of
   its own, no sidebar row, no line in `llms.txt`, and no identity an agent can
@@ -595,6 +598,41 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   predecessor, where the same mistakes shipped and were found by readers — one
   quiz had every correct answer in the same position across 451 questions.
 
+  A **presentation** is slides the record owns. Ask your coding agent for one
+  rather than writing it by hand — `make slides for knowledge/<path>.md` runs
+  the `make-slides` skill, which reads the document, writes the deck, checks
+  every claim back against it, and tells you what it left out:
+
+  ```yaml
+  slides:
+    title: Expense approvals
+    description: The 15-minute version, for a room.
+  deck:
+    - heading: When two copies disagree, one wins
+      bullets:
+        - Two approvers above the threshold, always
+        - The threshold is per invoice, including tax
+      note: Spoken, never shown. Pause here — people remember this one wrong.
+  ```
+
+  `heading` is required and should be a claim rather than a label; `lead` is
+  one sentence for a single-point slide; `bullets` caps at six because a slide
+  someone reads aloud is a slide nobody listens to; `note` is what the
+  presenter SAYS and never appears on the slide, including in fullscreen.
+
+  The slides render in the page — no third party, no request to anyone, and
+  every slide is in the shipped HTML, so a reader without JavaScript still gets
+  the whole deck. Because they live in the record they are reviewed in the same
+  pull request as the document, versioned with it, and withdrawn with it.
+
+  **A deck you keep elsewhere** can be pointed at instead — `slides.url:` and
+  no `deck:`. The embed url is derived for Google Slides, Canva and SlideShare;
+  anything else needs an explicit `embed:` or renders as a link. The url must
+  be `https` (a browser blocks a mixed-content frame silently), and the frame
+  loads on CLICK, so nothing is requested from the host until a reader asks.
+  Declaring both `deck:` and `slides.url:` is refused — two presentations with
+  nothing to say which one governs.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 
@@ -617,6 +655,8 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   write `instance.md` together.
 - `.agents/skills/add-sources/` — turn source material (documents, pages,
   notes) into governed knowledge.
+- `.agents/skills/make-slides/` — generate a presentation from one document
+  and attach it, so it renders on that document's page.
 - `.agents/skills/format-checker/` — the rules above, as a program;
   `pnpm check` runs it and its errors explain how to fix themselves.
 

package/templates/scaffold/README.md

@@ -23,6 +23,29 @@ versions that bundle corepack. The first `pnpm install` also fetches the
 `ksor` tool (pinned in `package.json`) and writes it into your lockfile —
 commit the updated lockfile.
 
+### Presenting a document
+
+Ask your coding agent for slides and it writes them, from the document, into
+the record:
+
+```
+make slides for knowledge/expenses/approvals.md
+```
+
+The `make-slides` skill 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 deck then renders at the top of that document's page: click through
+it inline, or **Present** for fullscreen. Presenter notes stay off the screen.
+
+The slides live in the record, so they are reviewed in the same pull request
+as the document, versioned with it, and withdrawn when it is withdrawn. There
+is no third party and no link to rot. If you already keep a deck in Google
+Slides, Canva or SlideShare you can point at it instead — `slides.url:` rather
+than `deck:` — and the page will offer it as a link with a frame the reader
+loads on click, so nothing is requested from the host until somebody asks.
+
 ### Serving to agents
 
 The record's other surface is an MCP server for AI agents — the same
@@ -128,7 +151,7 @@ different coding agent's way of finding the same working contract.
 | `instance.md`                    | what this record is authoritative for; its `name:` is the identity every surface publishes (read at server/build start — restart `pnpm dev` after renaming). This prose IS the agent surface's system prompt — `ksor serve` wires it into the MCP server's instructions. |
 | `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), `format-checker` (the rules, as a program).                                                        |
+| `.agents/skills/`                | the agent kit: `intake-interview` (define the record with you), `add-sources` (turn source material into governed documents), `make-slides` (generate a presentation from a document and attach it), `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.                                                                                                                                                           |