@panaversity/ksor 0.0.42 → 0.0.44

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @panaversity/ksor
 
+## 0.0.44
+
+### Patch Changes
+
+- 2ece135: **A lighter starter, and `refresh` finally says what it does** (issues #173, #171).
+
+  `ksor init` put five of `knowledge/`'s eleven files onto a single concept — 199
+  lines of companions against a 40-line document — so the first thing an adopter
+  opened was one document wearing four attachments. The flashcards, quiz and
+  slides companions are gone; `what-is-a-ksor.summary.md` stays, because it is the
+  only companion carrying a governance rule (exactly `type: Summary`, one key), so
+  the profile marker is still demonstrated. `knowledge/` goes from 11 files to 8.
+
+  What that costs, stated rather than glossed: the recall, quiz and slides tabs are
+  no longer shown by the starter, and an adopter meets those features in the docs
+  instead. Nothing about the companion mechanism changed — decision 24 is
+  untouched, and the migrate fixture that proves a deck migrates byte-identically
+  is frozen from an older tree, so it still covers the case.
+
+  And `pnpm refresh` was a name the constitution never defined, sitting beside
+  `pnpm ingest` and `ksor ingest` with nothing saying how the three relate. It has
+  a vocabulary entry now, and `docs/ingesting.md` opens with the model: `ksor
+build` makes the SITE correct with no database, `ksor ingest` makes the AGENT
+  DOOR correct, and `pnpm refresh` runs both. The split between the scaffold's
+  script and the underlying verb is deliberate, and now it is written down instead
+  of inferred.
+
+## 0.0.43
+
+### Patch Changes
+
+- 9ecfd78: **A document page that reads at a glance, and a dev server that sees new
+  documents again.**
+
+  The governance row is two tiers. It was one line carrying 79 characters, of
+  which the approver was 32 (41%) and the three labels 19 (24%) — so a producer
+  id was the longest thing on the page and the two facts a reader actually scans
+  for, what state this is in and whether anyone has checked it, competed with it.
+  Now the chips lead with Export beside them, and provenance sits beneath in
+  muted weight. Nothing is hidden: decision 21 requires a governance act to name
+  its actor and decision 27 requires a non-human approver to be disclosed, so the
+  approver moved one line down, not one click away, and every byte of it is still
+  in the server-rendered markup an agent parses.
+
+  Export no longer lands in the middle of the row. It and the reading time each
+  carried their own `ms-auto`, and on a row narrow enough to wrap they shared a
+  line — where two auto margins SPLIT the free space rather than stacking. They
+  are one right-hand cluster now.
+
+  **And adding a document to `knowledge/` while `pnpm dev` runs shows it again.**
+  This regressed in 0.0.41: `refreshStage` walked the STAGE and skipped anything
+  the stage did not already hold, so an arrival — which has no file to walk onto
+  — was never written, and the manifest naming what publishes never learned about
+  it. Measured: `/docs/<new>/` 404 → 200, sidebar 0 → 1, `llms.txt` 0 → 1;
+  0.0.40 served it at 200, so this is a repair rather than a feature. Removals
+  still wait for a restart, deliberately — a deleted file leaves fumadocs'
+  generated imports pointing at something gone.
+
+  The comment explaining why arrivals were refused was also wrong, and is
+  corrected: fumadocs-mdx 15.3.0 DOES regenerate on a write into the
+  dot-prefixed stage. Our own function was the blocker.
+
+  Finally, the starter's `knowledge/surfaces/overview.md` was titled `Surfaces`
+  inside the Surfaces section, so its breadcrumb read `Surfaces › Surfaces`. It
+  is `Overview` now.
+
+- 9ecfd78: **Two fixes on the document page.**
+
+  The governance row put **Export** in the middle of the row with nothing under
+  it. Export and the reading time each carried their own `ms-auto`, and on a row
+  narrow enough to wrap they landed on the same line — where two auto margins
+  SPLIT the free space between them rather than stacking, so Export came to rest
+  mid-row instead of at either end. They are now one right-hand cluster and
+  travel together at every width.
+
+  And the starter's `knowledge/surfaces/overview.md` was titled `Surfaces` inside
+  a section already called Surfaces, so its breadcrumb read `Surfaces › Surfaces`
+  and the sidebar showed a Surfaces inside Surfaces. It is titled `Overview` now,
+  matching its filename, and the generated section index was regenerated with it.
+
 ## 0.0.42
 
 ### Patch Changes

package/docs/ingesting.md

@@ -14,6 +14,21 @@ embedding cost on every cold start and would need write credentials at runtime.
 So **a first deploy with no ingest serves an empty record.** It is not broken;
 nothing was ever published to it.
 
+## `ksor ingest` or `pnpm refresh`?
+
+Both, and they are not alternatives — one contains the other.
+
+|                | makes correct                                                                       | needs a database |
+| -------------- | ----------------------------------------------------------------------------------- | ---------------- |
+| `ksor build`   | the **site** — checks the record, regenerates the indexes, writes `build.lock.json` | no               |
+| `ksor ingest`  | the **agent door** — embeds, loads Postgres, flips a generation                     | yes              |
+| `pnpm refresh` | both, in order: `ksor build` → `ksor ingest --flip` → `ksor gc`                     | yes              |
+
+`pnpm refresh` is the scaffold's script and the one to reach for by hand — it
+is a single command that leaves every surface current. `ksor ingest` is the
+verb underneath it, and it is what CI, a deploy step, or an agent calls when
+the individual step is the subject. The rest of this page is about that verb.
+
 ## Before the first command
 
 Ingest reads your markdown, sends each new chunk to an embedding provider, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "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/knowledge/surfaces/index.md

@@ -1,5 +1,5 @@
 # Surfaces
 
-* [Surfaces](overview.md) - One source, published through several synchronized projections.
+* [Overview](overview.md) - One source, published through several synchronized projections.
 * [The human surface](for-people.md) - Pages for reading, reviewing and sharing the record.
 * [The agent surface](for-agents.md) - MCP for retrieval with citations, and machine-readable files beside it.

package/templates/scaffold/knowledge/surfaces/overview.md

@@ -1,6 +1,6 @@
 ---
 type: Document
-title: Surfaces
+title: Overview
 description: One source, published through several synchronized projections.
 status: stable
 order: 4

package/templates/scaffold/system/site/components/governance.tsx

@@ -216,104 +216,132 @@ export function GovernanceMeta({
   // tier, `unverified` included, and that is the whole point of printing it.
   // The early return this replaced would have hidden the tier on exactly the
   // documents whose tier is the only governance fact they have.
+  /**
+   * TWO TIERS, because the row's length was never its vocabulary.
+   *
+   * Measured on the starter's own document: 79 characters, of which the
+   * APPROVER is 32 (41%) and the three labels 19 (24%). One producer id was
+   * longer than both governance chips together, so the two facts a reader
+   * scans for — what state is this in, and has anyone checked it — competed
+   * with a string that means nothing to them, and Export was pushed onto a
+   * line of its own.
+   *
+   * So the chips lead and the provenance follows beneath them. Nothing is
+   * hidden: decision 21 says a governance act NAMES its actor and decision
+   * 27's starter revision requires a non-human approver to be DISCLOSED, so
+   * demoting `ksor.approval` to a hover would trade a governance guarantee
+   * for a tidier row (critical rule 1). It is one line lower, not one click
+   * away, and every byte of it is still in the server-rendered markup an
+   * agent parses.
+   */
   return (
-    <dl className="mb-7 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 border-b border-fd-border pb-4">
-      {state === null && alsoBadge === null ? null : (
-        <Fact label="Status">
-          <span className="flex flex-wrap items-baseline gap-1.5">
-            {state === null ? null : <Chip text={state} tone={statusTone(status)} />}
-            {alsoBadge === null ? null : (
-              <BadgeChip badge={alsoBadge} effectiveFrom={effectiveFrom} />
-            )}
-          </span>
-        </Fact>
-      )}
-      {/* The tier OKF's own vocabulary names, on every document including the
+    <div className="mb-7 border-b border-fd-border pb-4">
+      <dl className="flex flex-wrap items-baseline gap-x-8 gap-y-2.5">
+        {state === null && alsoBadge === null ? null : (
+          <Fact label="Status">
+            <span className="flex flex-wrap items-baseline gap-1.5">
+              {state === null ? null : <Chip text={state} tone={statusTone(status)} />}
+              {alsoBadge === null ? null : (
+                <BadgeChip badge={alsoBadge} effectiveFrom={effectiveFrom} />
+              )}
+            </span>
+          </Fact>
+        )}
+        {/* The tier OKF's own vocabulary names, on every document including the
           unverified ones — that is the honest state of a stable, approved
           concept nobody has reviewed, and hiding it would leave a reader unable
           to tell "checked" from "never mentioned" (research/okf-native.md
           §1.1). Never a colour: a tier is a fact about review, not a warning. */}
-      <Fact label="Trust">
-        <span className="flex flex-wrap items-baseline gap-1.5">
-          <Chip text={trust.tier} />
-          {trust.by === null ? null : (
-            <span className="font-normal text-fd-muted-foreground">
-              {trust.by}
-              {trust.at === null ? null : <> · {day(trust.at)}</>}
-            </span>
-          )}
-        </span>
-      </Fact>
-      {owner === null ? null : <Fact label="Owner">{owner}</Fact>}
-      {/* Who let this into the record. `ksor.approval` is what makes a `stable`
+        <Fact label="Trust">
+          <span className="flex flex-wrap items-baseline gap-1.5">
+            <Chip text={trust.tier} />
+            {trust.by === null ? null : (
+              <span className="font-normal text-fd-muted-foreground">
+                {trust.by}
+                {trust.at === null ? null : <> · {day(trust.at)}</>}
+              </span>
+            )}
+          </span>
+        </Fact>
+        {/* Actions ride tier ONE: a reader who wants the bytes wants them
+          immediately, and this is the row with room. */}
+        {markdownUrl === undefined && minutes === undefined ? null : (
+          <div className="ms-auto flex items-center gap-x-6">
+            {markdownUrl === undefined ? null : <DocumentActions href={markdownUrl} />}
+            {minutes === undefined ? null : (
+              <div className="flex items-center gap-2 text-sm text-fd-muted-foreground">
+                <Clock aria-hidden className="size-3.5 shrink-0" />
+                <span>{minutes} min read</span>
+              </div>
+            )}
+          </div>
+        )}
+      </dl>
+      {/* Tier two RECEDES. It is provenance — who let this in, when it takes
+          effect, what it replaced — and it is read when a reader goes looking,
+          not scanned. At full `--foreground` weight it competed with the two
+          chips above it for the same attention, which is what made a producer
+          id the loudest thing on the page.
+
+          Links keep full strength: `Replaces` points at the document this one
+          superseded, and that is an action rather than a fact. */}
+      <dl className="mt-2.5 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 empty:mt-0 [&_a]:text-fd-foreground [&_dd]:font-normal [&_dd]:text-fd-muted-foreground">
+        {owner === null ? null : <Fact label="Owner">{owner}</Fact>}
+        {/* Who let this into the record. `ksor.approval` is what makes a `stable`
           document stable at all (record spec §2.2), so a page that showed the
           word and not the signature would be publishing the claim without its
           author. */}
-      {approval === null ? null : (
-        <Fact label="Approved">
-          <>
-            {approval.by} · {day(approval.at)}
-          </>
-        </Fact>
-      )}
-      {/* found live 2026-08-25: a deprecated page named its successor and said
+        {approval === null ? null : (
+          <Fact label="Approved">
+            <>
+              {approval.by} · {day(approval.at)}
+            </>
+          </Fact>
+        )}
+        {/* found live 2026-08-25: a deprecated page named its successor and said
           nothing about WHO withdrew it, though `ksor.deprecated` is required on
           every deprecated concept (record spec §2.2) and readGovernance already
           refuses a document that omits it. Withdrawal is the most consequential
           act in a document's life; publishing it unattributed is exactly the
           gap the approver fact above closes at the other end. */}
-      {deprecated === null ? null : (
-        <Fact label="Withdrawn">
-          <>
-            {deprecated.by} · {day(deprecated.at)}
-          </>
-        </Fact>
-      )}
-      {replaces.length === 0 ? null : (
-        // The other half of a supersession. The withdrawn document names its
-        // successor above the title; this is the successor naming what it
-        // replaced, so the history the record kept is reachable from the
-        // current document instead of only from the retired one.
-        <Fact label="Replaces">
-          <>
-            {replaces.map((entry, index) => (
-              <span key={entry.href ?? `${index}-${entry.label}`}>
-                {index === 0 ? null : ", "}
-                {entry.href === null ? (
-                  entry.label
-                ) : (
-                  <Link
-                    href={entry.href}
-                    className="underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
-                  >
-                    {entry.label}
-                  </Link>
-                )}
-              </span>
-            ))}
-          </>
-        </Fact>
-      )}
-      {effectiveFrom === null || !showEffective ? null : (
-        <Fact label="Effective from">{day(effectiveFrom)}</Fact>
-      )}
-      {staleAfter === null ? null : <Fact label="Review by">{day(staleAfter)}</Fact>}
-      {markdownUrl === undefined ? null : (
-        // On the governance row, not as a footnote below the sources: it is
-        // how a reader hands this document to an agent (research/site-design.md
-        // F2). Right-aligned: a column of things you DO, against a row of
-        // things the record DECLARES (owner, 2026-08-22).
-        <span className="ms-auto">
-          <DocumentActions href={markdownUrl} />
-        </span>
-      )}
-      {minutes === undefined ? null : (
-        <div className="ms-auto flex items-center gap-2 text-sm text-fd-muted-foreground">
-          <Clock aria-hidden className="size-3.5 shrink-0" />
-          <span>{minutes} min read</span>
-        </div>
-      )}
-    </dl>
+        {deprecated === null ? null : (
+          <Fact label="Withdrawn">
+            <>
+              {deprecated.by} · {day(deprecated.at)}
+            </>
+          </Fact>
+        )}
+        {replaces.length === 0 ? null : (
+          // The other half of a supersession. The withdrawn document names its
+          // successor above the title; this is the successor naming what it
+          // replaced, so the history the record kept is reachable from the
+          // current document instead of only from the retired one.
+          <Fact label="Replaces">
+            <>
+              {replaces.map((entry, index) => (
+                <span key={entry.href ?? `${index}-${entry.label}`}>
+                  {index === 0 ? null : ", "}
+                  {entry.href === null ? (
+                    entry.label
+                  ) : (
+                    <Link
+                      href={entry.href}
+                      className="underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+                    >
+                      {entry.label}
+                    </Link>
+                  )}
+                </span>
+              ))}
+            </>
+          </Fact>
+        )}
+        {effectiveFrom === null || !showEffective ? null : (
+          <Fact label="Effective from">{day(effectiveFrom)}</Fact>
+        )}
+        {staleAfter === null ? null : <Fact label="Review by">{day(staleAfter)}</Fact>}
+      </dl>
+    </div>
   );
 }
 

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

@@ -670,30 +670,51 @@ function fillStage(recordDir: string, stageDir: string, development: boolean): v
 }
 
 /**
- * Dev only: carry edits into the files the stage already holds, so
- * `pnpm dev` shows the record as the owner is writing it rather than as it
- * stood when the server started — the regenerated indexes included, so a
- * retitled document is retitled in its folder's listing too.
+ * Dev only: carry edits AND ARRIVALS into the stage, so `pnpm dev` shows the
+ * record as the owner is writing it rather than as it stood when the server
+ * started — the regenerated indexes included, so a retitled document is
+ * retitled in its folder's listing too.
  *
- * Edits only — never adds, never removals. fumadocs' own watcher cannot see
- * a dot-prefixed collection directory (measured 2026-08-18: adding a file to
- * the stage regenerated nothing, and removing one left the generated imports
- * pointing at a file that was gone), so a document that ARRIVES or changes
- * audience needs the restart `pnpm dev` already needs for instance.md. Leaving
- * that to a restart keeps dev honest in the direction that matters: the
- * published build is always staged from scratch.
+ * Adds and edits — never removals. The 2026-08-18 measurement this refused
+ * adds on ("fumadocs' own watcher cannot see a dot-prefixed collection
+ * directory") no longer holds: on fumadocs-mdx 15.3.0 a file written into
+ * `.staged-knowledge` DOES regenerate the collection, twice-observed as
+ * `[MDX] generated files` in the dev log. What actually kept a new document
+ * off every surface was this function, which walked the STAGE and skipped
+ * anything the stage did not already hold — so a plan entry with no file on
+ * disk was never written, and the manifest that names what publishes never
+ * learned about it either.
+ *
+ * Measured before and after, adding a document while `pnpm dev` ran:
+ * `/docs/<new>/` 404 -> 200, sidebar 0 -> 1, `llms.txt` 0 -> 1. It worked
+ * this way before the stage existed (0.0.40 serves an added document at 200),
+ * so this is a regression repaired rather than a feature.
+ *
+ * REMOVALS still wait for the restart `pnpm dev` already needs for
+ * instance.md: the same measurement found a deleted file leaves fumadocs'
+ * generated imports pointing at something gone, which takes the dev server
+ * down rather than showing a stale page. An arrival has no such failure mode
+ * — nothing points at a file that has only just appeared.
  */
 function refreshStage(recordDir: string, stageDir: string): void {
   // Under the lock like every other write here: a save landing while another
   // evaluation is refilling the stage is the same race from the other side.
   withStageLock(stageDir, () => {
     const plan = planStage(recordDir, true);
-    const permitted = new Map(plan.entries.map((e) => [path.join(stageDir, e.rel), e] as const));
-    for (const staged of walkFiles(stageDir)) {
-      const entry = permitted.get(staged);
-      if (entry === undefined) continue;
+    // Drive from the PLAN, not from the stage. Walking the stage could only
+    // ever find what was already there, which is exactly why an arrival was
+    // invisible: it has no file to walk onto.
+    for (const entry of plan.entries) {
+      const staged = path.join(stageDir, entry.rel);
       const bytes = entry.bytes();
-      if (bytes.equals(readFileSync(staged))) continue;
+      let current: Buffer | null = null;
+      try {
+        current = readFileSync(staged);
+      } catch {
+        // Not staged yet — an arrival. Written below.
+      }
+      if (current !== null && current.equals(bytes)) continue;
+      mkdirSync(path.dirname(staged), { recursive: true });
       writeFileSync(staged, bytes);
     }
     writeManifest(stageDir, plan.manifest);

package/templates/scaffold/knowledge/what-is-a-ksor.flashcards.yaml

@@ -1,25 +0,0 @@
-# A recall deck for what-is-a-ksor.md.
-#
-# Every card states only what its parent document states — a deck is a way of
-# rehearsing the record, never a second source. Ask your coding agent to write
-# one of these from a document, and to check each answer against it.
-deck:
-  title: What a KSoR is
-  description: Recall checks for the record's own definition of itself.
-cards:
-  - front: When a spreadsheet disagrees with the ledger, which one wins?
-    back: The ledger. A system of record is the copy that governs.
-    why: Which copy would your organization's agents trust today?
-
-  - front: A traditional system of record settles the state of a business. What does a KSoR settle?
-    back: What the organization knows and how it should operate — which policies apply, which thresholds are approved, what a term means here.
-
-  - front: What problem does a KSoR solve?
-    back: Scatter. Knowledge spread across wikis, decks, PDFs, prompts and someone's memory, with no authoritative answer to which knowledge an agent should trust.
-
-  - front: Why can an assistant not tell you which of its sentences were checked?
-    back: Because it answers from everything it has ever read. Nothing in that process distinguishes a checked claim from an unchecked one.
-    why: This is the gap the record exists to close.
-
-  - front: Does provenance prove that a document is correct?
-    back: No. Provenance proves who said what, and when. Whether the source is any good is a separate matter, and the record never claims otherwise.

package/templates/scaffold/knowledge/what-is-a-ksor.quiz.yaml

@@ -1,90 +0,0 @@
-# A quiz for what-is-a-ksor.md.
-#
-# Every question and every answer states only what its parent document states —
-# a quiz is a way of checking the record, never a second source. Ask your coding
-# agent to write one from a document, and to check each answer back against it.
-#
-# Two habits worth copying. The options are kept close in LENGTH, because if the
-# correct answer is reliably the longest one a reader passes by looking rather
-# than by reading. And the correct answer moves POSITION between questions: a
-# quiz whose answer is usually B is a quiz you can pass without the document.
-# `pnpm check` and `pnpm build` both refuse a quiz where either is true — the
-# first draft of this one was refused for putting four of five answers at B.
-quiz:
-  title: Check yourself
-  description: Five questions on what this record is, and what it is not.
-questions:
-  - question: A spreadsheet and the ledger disagree about a number. Which one is authoritative?
-    options:
-      - Whichever of the two was most recently edited
-      - The spreadsheet, being closer to the daily work
-      - The ledger, because it is the governing copy
-      - Neither, until a person reconciles the two
-    answer: 2
-    explanation: >
-      A system of record is the copy that governs, so the ledger wins by
-      definition rather than by being newer or closer to the work. Recency is
-      not authority: an edit made this morning in a spreadsheet nobody governs
-      is still ungoverned. Reconciliation is something a record makes possible,
-      not a precondition for having an answer at all.
-    source: The opening definition
-
-  - question: What does a KSoR settle that a traditional system of record does not?
-    options:
-      - The state of a business, such as its balances
-      - Which vendor an organization has chosen to use
-      - How much storage the organization is paying for
-      - What the organization knows and how it operates
-    answer: 3
-    explanation: >
-      A traditional system of record settles the state of a business — what is
-      owed, what is owned, what was transacted. A KSoR settles the layer above
-      it: which policies apply, which thresholds are approved, and what a term
-      means inside this organization. Vendor choice and storage cost are
-      consequences of running one, never what it is authoritative for.
-    source: What this record settles
-
-  - question: Why can an ordinary assistant not tell you which of its sentences were checked?
-    options:
-      - It answers from everything it has ever read
-      - It was not given enough context to work with
-      - Its answers are checked, but only in summary
-      - It lacks permission to reveal its own sources
-    answer: 0
-    explanation: >
-      It answers from everything it has ever read, and nothing in that process
-      separates a checked claim from an unchecked one. This is not a context
-      problem and not a permissions problem: more context cannot create a
-      distinction that was never recorded in the first place. The record closes
-      the gap by governing what gets read.
-    source: Why an assistant cannot answer that question
-
-  - question: What problem does a KSoR exist to solve?
-    options:
-      - Storage costs across a growing organization
-      - Scatter, with no authoritative copy to trust
-      - The speed at which an assistant can reply
-      - The difficulty of writing documentation well
-    answer: 1
-    explanation: >
-      The problem is scatter: knowledge spread across wikis, decks, PDFs,
-      prompts and somebody's memory, with no authoritative answer to which of
-      them an agent should trust. Speed and cost are not what the record
-      addresses, and writing well is valuable but does not by itself tell an
-      agent which of two documents governs.
-    source: The problem it solves
-
-  - question: Abstention — answering "not in this corpus" — is best described as what?
-    options:
-      - An error state the record should minimise
-      - A temporary gap, pending the next ingest
-      - A setting an operator turns on when ready
-      - A correct answer the record is meant to give
-    answer: 3
-    explanation: >
-      Abstention is a correct answer, never an error and never a licence to
-      fall back on general model knowledge. A record that answers everything
-      has stopped being a record of anything in particular. It is not a gap
-      waiting to be filled, and while the gate that enforces it is configured
-      deliberately, the honesty it expresses is the product itself.
-    source: What this record settles, and what it does not

package/templates/scaffold/knowledge/what-is-a-ksor.slides.yaml

@@ -1,65 +0,0 @@
-# The presentation that teaches what-is-a-ksor.md.
-#
-# These slides live IN the record: reviewed in a pull request, versioned with
-# the document, withdrawn when it is withdrawn, and rendered by the site — so
-# there is no third party, no dead link, and nothing to keep in step by hand.
-# Your coding agent writes them from the document; `.agents/skills/make-slides/`
-# is the procedure.
-#
-# A slide may only say what the document says. A deck is a way of presenting
-# the record, never a second source.
-slides:
-  title: Introducing the record
-  description: The 15-minute version, for a room.
-deck:
-  # The opening slide does NOT repeat the page title. It sits directly under
-  # it, so restating it wastes the one slide everyone actually looks at.
-  - heading: Which copy should an agent trust?
-    lead: That question is what this record exists to answer, and nothing in an ordinary assistant can.
-    note: Open with the question, not the definition. The definition lands after they feel the problem.
-
-  - heading: The problem it solves
-    bullets:
-      - Knowledge is scattered across wikis, decks, PDFs, prompts and memory
-      - No authoritative answer to the question an agent has to ask
-      - Which of these copies should I trust?
-    note: Ask the room where their real answer lives today. Wait for the disagreement — it always comes.
-
-  - heading: When two copies disagree, one wins
-    bullets:
-      - A traditional system of record settles the state of a business
-      - The ledger is authoritative; the spreadsheet is not
-      - Recency is not authority — a fresh edit to an ungoverned copy is still ungoverned
-    note: This is the whole idea. If they take one slide away, it is this one.
-
-  - heading: AI never had one
-    bullets:
-      - An assistant answers from everything it has ever read
-      - Nothing in that separates a checked claim from an unchecked one
-      - Which is exactly why it cannot tell you which of its sentences were verified
-    note: Not a criticism of the models. It is a missing layer, and that layer is what we are building.
-
-  - heading: What this record settles
-    bullets:
-      - Which policies apply, and which thresholds are approved
-      - What a term means inside this organization
-      - What to do when the answer is not known
-    note: Point at the third one. It is the one people do not expect.
-
-  - heading: Abstention is a feature
-    lead: '"Not in this corpus" is a correct answer — never an error, and never a licence to fall back on model knowledge.'
-    note: A record that answers everything has stopped being a record of anything in particular.
-
-  - heading: One source, two surfaces
-    bullets:
-      - The website is for people
-      - The MCP server is for agents
-      - Both render the same build — they can never disagree
-    note: Open llms.txt beside the page here. Seeing one source render twice lands better than describing it.
-
-  - heading: Where the edges are
-    bullets:
-      - Provenance proves who said what, and when
-      - It does not prove the source was right — that is a separate judgment
-      - Governance is a ladder, not a gate; level 0 works on day one
-    note: Say the second bullet out loud. Overselling provenance is how these systems lose trust.