@panaversity/ksor 0.0.29 → 0.0.31

package/templates/scaffold/AGENTS.md

@@ -506,11 +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 two optional companions named
-  after it, in the same folder: `<doc>.summary.md` (a short précis) and
-  `<doc>.flashcards.yaml` (a recall deck). The summary appears as a second tab
-  beside the document's own words; the deck appears at the END of that
-  document's page. Both appear nowhere else in the site.
+- **Study attachments.** A document may carry four optional companions named
+  after it, in the same folder: `<doc>.summary.md` (a short précis),
+  `<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
@@ -549,6 +553,86 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   kept in the reader's own browser, so it is per-person and per-device, and it
   is not part of the record.
 
+  A **quiz** is the same idea with an answer to choose. Each question carries
+  two to six options, `answer` as the zero-based index of the correct one, a
+  required `explanation`, and an optional `source` naming where in the document
+  the answer lives:
+
+  ```yaml
+  quiz:
+    title: Expense approvals
+    questionsPerRound: 10 # optional; the default
+  questions:
+    - question: Who approves a purchase above the threshold?
+      options:
+        - A second approver, independent of the requester
+        - The requester's own manager, in every case
+        - The finance team, after the purchase completes
+      answer: 0
+      explanation: Why that is right, and why the others are not.
+      source: Approvals — thresholds
+  ```
+
+  The reader sees whether they were right **immediately**, then the
+  explanation — a quiz here teaches through the mistake, and it does not
+  certify anybody, so there is no pass mark. Answers stay in the reader's
+  browser and are sent nowhere. A bank larger than `questionsPerRound` is drawn
+  from at random and offers another round; a smaller one is simply asked in
+  full.
+
+  **`pnpm check` and `pnpm build` both refuse a quiz a reader could pass
+  without reading**, and this is worth knowing before you write one, because
+  it is easy to trip by accident:
+
+  | Refusal                    | Means                                                 |
+  | -------------------------- | ----------------------------------------------------- |
+  | `ksor-quiz-answer-bias`    | more than 60% of answers sit 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        |
+
+  So: move the correct answer around, and keep the options close in length.
+  The ratio rules do not apply below five questions, where spreading answers
+  would mean the checker choosing them for you. These checks come from the
+  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`.
 
@@ -571,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.                                                                                                                                                           |

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

@@ -0,0 +1,90 @@
+# 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

@@ -0,0 +1,65 @@
+# 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.

package/templates/scaffold/system/site/app/docs/[[...slug]]/page.tsx

@@ -17,8 +17,10 @@ import { showGovernance } from "@/lib/shared";
 import { RecordToc, TocItems } from "@/components/record-toc";
 import { RecordViews } from "@/components/record-views";
 import { Flashcards } from "@/components/flashcards";
+import { Quiz } from "@/components/quiz";
+import { Slides } from "@/components/slides";
 import { StudyAids } from "@/components/study-aids";
-import { deckFor, summaryFor } from "@/lib/attachments";
+import { deckFor, quizFor, slidesFor, summaryFor } from "@/lib/attachments";
 import { readingMinutes } from "@/lib/reading-time";
 
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
@@ -32,6 +34,8 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const summary = summaryFor(page.path);
   const Summary = summary?.body ?? null;
   const deck = deckFor(page.path);
+  const quiz = quizFor(page.path);
+  const presentation = slidesFor(page.path);
   // Counted at BUILD time from the document's own markdown, so the figure is in
   // the shipped HTML for a reader with a failed bundle, a crawler and an agent
   // alike. The predecessor measured the rendered DOM after paint, which put it
@@ -122,6 +126,12 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
         {showGovernance ? (
           <GovernanceMeta governance={governance} replaces={replaces} markdownUrl={markdownUrl} />
         ) : null}
+        {/* BEFORE the document, not after it. The deck is the shape of the
+          thing — five minutes of slides gives the detail somewhere to land —
+          so it belongs where a reader meets it first, which is also where the
+          predecessor puts its own. The recall aids stay at the end, because
+          those are used AFTER reading. */}
+        {presentation === null ? null : <Slides slides={presentation} />}
         {/* grow-0, against the shell's own `flex-1`: the article is a flex column
           stretched to the viewport, so the body inflated from ~150px of text to
           402px and pushed Sources and everything after it to the bottom of the
@@ -157,7 +167,12 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
           region, so the quiz that will sit beside the deck is a child here and
           not a new argument about where it goes. Renders nothing at all when
           the document has no study aids. */}
-        <StudyAids>{deck === null ? null : <Flashcards deck={deck} />}</StudyAids>
+        {/* Recall first, then the check on it — and each renders only if the
+            document carries one, so a page with just a quiz shows just a quiz. */}
+        <StudyAids>
+          {deck === null ? null : <Flashcards deck={deck} />}
+          {quiz === null ? null : <Quiz quiz={quiz} />}
+        </StudyAids>
         {/* A folder's index page lists what the folder holds. Without it the
           page ended at its own sentence and the documents below it were
           reachable only from the sidebar (research/site-design.md F5). Empty

package/templates/scaffold/system/site/app/global.css

@@ -274,6 +274,119 @@ html > body[data-scroll-locked] {
   --ksor-caution: #e0906e;
 }
 
+/* The slide STAGE.
+
+   A slide is a projected surface, and reading as one at a glance is most of
+   what makes a deck legible on a page full of prose. The first version painted
+   it `--muted` and it read as an empty placeholder rather than as a slide —
+   pale grey on a pale page, with nothing saying "this is a different medium".
+
+   So the stage is dark in BOTH themes, deliberately. That is not a palette
+   inconsistency: the page is a document and the stage is a projection, and the
+   whole job of this block is to look like the second thing while sitting
+   inside the first. Its ink is warm-neutral rather than pure white, which is
+   what stops a dark panel from glaring on a light page.
+
+   Light and dark differ only in how far the stage sits from its surround. */
+:root {
+  --ksor-stage: oklch(0.21 0.018 258);
+  --ksor-stage-ink: oklch(0.96 0.005 90);
+  --ksor-stage-dim: oklch(0.74 0.012 258);
+  --ksor-stage-rule: oklch(0.32 0.02 258);
+}
+
+/* In dark the stage must RISE off the page, not sink into it. A stage darker
+   than its surround measured L 4.4 against the page's 3.3 — near-identical,
+   so the slide lost its edges entirely and read as text floating on the page
+   (found live). On a dark ground, elevation reads as lighter. */
+.dark {
+  --ksor-stage: oklch(0.26 0.019 258);
+  --ksor-stage-ink: oklch(0.96 0.005 90);
+  --ksor-stage-dim: oklch(0.76 0.012 258);
+  --ksor-stage-rule: oklch(0.38 0.02 258);
+}
+
+.ksor-stage {
+  background-color: var(--ksor-stage);
+  color: var(--ksor-stage-ink);
+}
+
+.ksor-stage-dim {
+  color: var(--ksor-stage-dim);
+}
+
+.ksor-stage-rule {
+  background-color: var(--ksor-stage-rule);
+}
+
+/* Right and wrong, for the quiz — the ONE place this record spends green and
+   red, and it earns them: a reader checking an answer is asking a true/false
+   question, and the accent cannot say "this is correct" while also saying
+   "this is what you picked". Both are needed at once when you answer wrongly.
+
+   Colour is never the only channel: the correct option also carries a check,
+   the wrong one a cross, and the line above states the verdict in words — so
+   the pair works for a reader who cannot distinguish them. Declared as
+   light/dark pairs on the root for the reason `--ksor-caution` above records.
+
+   Deliberately NOT `--ksor-caution`, which means "the record withdrew this".
+   A wrong answer is not a governance state. */
+:root {
+  --ksor-correct: #1a7f4b;
+  --ksor-incorrect: #b3261e;
+}
+
+.dark {
+  --ksor-correct: #6edaa0;
+  --ksor-incorrect: #f2897f;
+}
+
+/* The three states an answered question shows at once. Written as CLASSES,
+   the way `.ksor-caution` below is, rather than as Tailwind arbitrary values:
+   `border-[color:var(--x)]` emits a rule whose `var()` did not resolve on the
+   element in a real build (found live 2026-08-23 — the class was present, the
+   rule was in the stylesheet, the token computed correctly on the element, and
+   the border still painted the default hairline). A plain class has none of
+   that ambiguity, and this file is already where this record's semantic colour
+   lives. */
+.ksor-answer-correct {
+  border-color: var(--ksor-correct);
+  background-color: color-mix(in oklab, var(--ksor-correct) 10%, transparent);
+}
+
+.ksor-answer-wrong {
+  border-color: var(--ksor-incorrect);
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 10%, transparent);
+}
+
+/* "This is the one you picked" — kept in the accent, and kept SEPARATE from
+   right/wrong, because after a wrong answer a reader needs all three facts. */
+.ksor-answer-mine {
+  outline: 2px solid var(--color-fd-primary);
+  outline-offset: 1px;
+}
+
+.ksor-answer-correct-text {
+  color: var(--ksor-correct);
+}
+
+.ksor-answer-wrong-text {
+  color: var(--ksor-incorrect);
+}
+
+.dark .ksor-answer-correct,
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, currentColor 0%, transparent);
+}
+
+.dark .ksor-answer-correct {
+  background-color: color-mix(in oklab, var(--ksor-correct) 14%, transparent);
+}
+
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 14%, transparent);
+}
+
 .ksor-caution {
   border-color: color-mix(in oklab, var(--ksor-caution) 32%, transparent);
   border-left-color: var(--ksor-caution);