@panaversity/ksor 0.0.30 → 0.0.31

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

@@ -18,8 +18,9 @@ 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, quizFor, 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]]">) {
@@ -34,6 +35,7 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   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
@@ -124,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

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

@@ -274,6 +274,51 @@ 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

package/templates/scaffold/system/site/components/deck-viewer.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+import { ChevronLeft, ChevronRight, Maximize2 } from "lucide-react";
+import { useCallback, useRef, useState, type ReactElement } from "react";
+
+import { Button } from "@/components/ui/button";
+import type { DeckSlide } from "@/lib/attachments";
+
+/**
+ * A presentation the RECORD owns, rendered in the page.
+ *
+ * This is the mode that makes the workflow complete. An agent writes the
+ * slides from the document — no browser, no third party, no human step in the
+ * middle — and this draws them. Which means the deck is governed like every
+ * other attachment: reviewed in a PR, versioned with its document, withdrawn
+ * with it. An embedded deck is none of those things, and can rot into a dead
+ * link with nothing going red.
+ *
+ * Every slide is in the SERVER-RENDERED HTML, not fetched and not built on
+ * mount: a crawler, a reader with JavaScript off, and an agent parsing the page
+ * all get the whole deck. Only the *navigation* is client-side, so what the
+ * bytes carry never depends on a script running.
+ *
+ * The stage is dark in both themes (`.ksor-stage`, app/global.css). A slide is
+ * a PROJECTION and the page around it is a document; looking like the first
+ * thing while sitting inside the second is most of what makes a deck legible
+ * at a glance. The first version painted it `--muted` and it read as an empty
+ * placeholder — pale grey on a pale page, saying nothing.
+ */
+export function DeckViewer({
+  slides,
+  title,
+}: {
+  readonly slides: readonly DeckSlide[];
+  readonly title: string;
+}): ReactElement {
+  const [index, setIndex] = useState(0);
+  const frameRef = useRef<HTMLDivElement>(null);
+  const total = slides.length;
+
+  const go = useCallback(
+    (delta: number) => setIndex((i) => Math.min(total - 1, Math.max(0, i + delta))),
+    [total],
+  );
+
+  // Arrow keys, but ONLY while the deck has focus — a page-wide listener would
+  // hijack arrows from the reader scrolling the document.
+  const onKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === "ArrowRight" || event.key === "PageDown") {
+        event.preventDefault();
+        go(1);
+      } else if (event.key === "ArrowLeft" || event.key === "PageUp") {
+        event.preventDefault();
+        go(-1);
+      }
+    },
+    [go],
+  );
+
+  const present = useCallback(() => {
+    void frameRef.current?.requestFullscreen?.().catch(() => {
+      // Fullscreen is a nicety and is refused in plenty of ordinary contexts —
+      // an iframe without the permission, a browser that requires a gesture it
+      // did not see. The deck stays usable inline, so this is not an error.
+    });
+  }, []);
+
+  const current = slides[index];
+  if (current === undefined) return <></>;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div
+        ref={frameRef}
+        tabIndex={0}
+        role="group"
+        aria-roledescription="presentation"
+        aria-label={`${title}, slide ${index + 1} of ${total}`}
+        onKeyDown={onKeyDown}
+        className="ksor-stage relative aspect-video w-full overflow-hidden rounded-xl border border-[var(--ksor-stage-rule)] shadow-[0_1px_2px_rgba(0,0,0,0.08),0_12px_28px_-12px_rgba(0,0,0,0.35)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+      >
+        {/* The deck's own rule across the top: a slide theme in one line, and
+            the thing that stops the stage reading as a plain dark rectangle. */}
+        <div aria-hidden className="absolute inset-x-0 top-0 h-[3px] bg-fd-primary" />
+
+        {slides.map((slide, i) => (
+          <article
+            key={slide.heading + String(i)}
+            // Every slide is rendered; the inactive ones are hidden rather
+            // than absent, so the whole deck is in the shipped HTML.
+            hidden={i !== index}
+            aria-hidden={i !== index}
+            className="absolute inset-0 flex flex-col justify-center gap-6 px-[8%] pt-[8%] pb-[13%]"
+          >
+            <h3 className="font-(family-name:--font-display) text-[clamp(1.35rem,3.1vw,2.1rem)] leading-[1.15] font-semibold tracking-tight text-balance">
+              {slide.heading}
+            </h3>
+            {slide.lead === undefined ? null : (
+              <p className="ksor-stage-dim max-w-[42ch] text-[clamp(0.9rem,1.5vw,1.1rem)] leading-relaxed">
+                {slide.lead}
+              </p>
+            )}
+            {slide.bullets === undefined || slide.bullets.length === 0 ? null : (
+              <ul className="flex max-w-[48ch] flex-col gap-3">
+                {slide.bullets.map((bullet, k) => (
+                  <li
+                    key={`${bullet}-${k}`}
+                    className="flex gap-3 text-[clamp(0.85rem,1.4vw,1rem)] leading-snug"
+                  >
+                    {/* A square tick in the accent rather than a disc: it reads
+                        at projection distance, where a bullet dot disappears. */}
+                    <span
+                      aria-hidden
+                      className="mt-[0.45em] size-[0.42em] shrink-0 rounded-[1px] bg-fd-primary"
+                    />
+                    <span>{bullet}</span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </article>
+        ))}
+
+        {/* The stage's own footer: the deck's name and the position, in mono,
+            the way a real deck carries its identity on every slide. */}
+        <div className="absolute inset-x-0 bottom-0 flex items-center justify-between gap-4 px-[8%] pb-[4%]">
+          <p className="ksor-stage-dim truncate font-mono text-[0.68rem] tracking-wide uppercase">
+            {title}
+          </p>
+          <p className="ksor-stage-dim shrink-0 font-mono text-[0.68rem] tabular-nums">
+            {index + 1} / {total}
+          </p>
+        </div>
+
+        {/* How far through the deck, drawn on the stage itself so it survives
+            fullscreen — where the controls below are not on screen at all. */}
+        <div aria-hidden className="ksor-stage-rule absolute inset-x-0 bottom-0 h-[2px]">
+          <div
+            className="h-full bg-fd-primary transition-[width] duration-200 motion-reduce:transition-none"
+            style={{ width: `${((index + 1) / total) * 100}%` }}
+          />
+        </div>
+      </div>
+
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-1">
+          <Button variant="ghost" size="sm" onClick={() => go(-1)} disabled={index === 0}>
+            <ChevronLeft aria-hidden className="size-4" />
+            <span className="sr-only sm:not-sr-only">Back</span>
+          </Button>
+          <Button variant="ghost" size="sm" onClick={() => go(1)} disabled={index === total - 1}>
+            <span className="sr-only sm:not-sr-only">Next</span>
+            <ChevronRight aria-hidden className="size-4" />
+          </Button>
+        </div>
+
+        {/* Jump to any slide. Dots rather than a list, because a deck this
+            size is scanned rather than read, and they double as the shape of
+            how much is left. */}
+        <div className="flex flex-wrap items-center justify-center gap-1.5">
+          {slides.map((slide, i) => (
+            <button
+              key={`dot-${slide.heading}-${i}`}
+              type="button"
+              onClick={() => setIndex(i)}
+              aria-label={`Slide ${i + 1}: ${slide.heading}`}
+              aria-current={i === index ? "true" : undefined}
+              className={`h-1.5 rounded-full transition-all motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring ${
+                i === index
+                  ? "w-5 bg-fd-primary"
+                  : "w-1.5 bg-fd-border hover:bg-fd-muted-foreground"
+              }`}
+            />
+          ))}
+        </div>
+
+        <Button variant="ghost" size="sm" onClick={present}>
+          <Maximize2 aria-hidden className="size-3.5" />
+          <span className="font-mono text-xs tracking-wide uppercase">Present</span>
+        </Button>
+      </div>
+
+      {current.note === undefined ? null : (
+        // The presenter's note: what to SAY, never what the slide shows. Kept
+        // outside the stage so it is not projected when the deck is
+        // fullscreened, which is the whole point of a note.
+        <p className="border-s-2 border-fd-border ps-3 text-sm text-fd-muted-foreground">
+          <span className="font-mono text-xs tracking-wide uppercase">Say: </span>
+          {current.note}
+        </p>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,128 @@
+"use client";
+
+import { ExternalLink, Presentation } from "lucide-react";
+import { useState, type ReactElement } from "react";
+
+import { DeckViewer } from "@/components/deck-viewer";
+import { Button } from "@/components/ui/button";
+import type { SlidesEntry } from "@/lib/attachments";
+
+/**
+ * The presentation that teaches this document.
+ *
+ * The predecessor embeds the deck directly — an always-on `<iframe>` to Google
+ * Slides, authored as raw JSX in the lesson's MDX. Two things stop that here,
+ * and the second one changed the design rather than just the authoring:
+ *
+ *  1. `knowledge/` is CommonMark (critical rule 2), so the frame cannot be
+ *     authored in the document. It is an attachment instead.
+ *
+ *  2. The scaffold's browser test asserts **zero external requests** on a
+ *     built page. An always-on frame breaks that on every page carrying a
+ *     deck — and the guarantee is worth keeping, because it is what makes the
+ *     site work offline, behind a firewall, and without telling a third party
+ *     which of your policies someone is reading.
+ *
+ * So the frame is CLICK-TO-LOAD. Nothing reaches the provider until a reader
+ * asks for it: the page ships a placeholder, and the `<iframe>` is created on
+ * click. The link out is always available and costs nothing, because a plain
+ * `<a>` is not a request.
+ *
+ * That is a real divergence from the predecessor and it is an improvement
+ * rather than a compromise — the reader who only wanted the policy never
+ * announces themselves to a slide host.
+ */
+export function Slides({ slides }: { slides: SlidesEntry }): ReactElement {
+  const [loaded, setLoaded] = useState(false);
+  const provider = slides.provider ?? slides.derivedProvider;
+
+  return (
+    <section aria-label="Teaching aid" className="not-prose mt-8 mb-12">
+      {/* A section heading, in the record's own language for one.
+
+          An earlier version dropped the accent bar and greyed the label, on
+          the theory that anything stronger would compete with the document
+          title directly above. That went too far: with no marker and no colour
+          the block read as loose text rather than as a section (owner, seen
+          live). The fix is the established marker at a smaller SIZE, not a
+          weaker one — the label carries the accent so it reads as a marker,
+          and the title sits one step below the document's. */}
+      <header className="mb-6">
+        <p className="font-mono text-xs font-medium tracking-[0.12em] text-fd-primary uppercase">
+          Teaching aid
+        </p>
+        <h2 className="mt-2 font-(family-name:--font-display) text-2xl font-semibold tracking-tight text-fd-foreground">
+          {slides.title}
+        </h2>
+        {/* The record's own marker for "a new region starts here": a short
+            accent bar riding a full-width hairline. Every study-aid header
+            uses it, so a reader has met it before. */}
+        <div className="mt-3 h-px w-full bg-fd-border">
+          <div className="h-[3px] w-24 -translate-y-px bg-fd-primary" />
+        </div>
+        {slides.description === undefined ? null : (
+          <p className="mt-4 text-sm text-fd-muted-foreground">{slides.description}</p>
+        )}
+      </header>
+
+      <div className="flex flex-col gap-4">
+        {/* A deck the record owns needs no link and no permission: it IS the
+            presentation. The linked mode below is for an adopter who already
+            has one somewhere else. */}
+        {slides.deck !== undefined && slides.deck.length > 0 ? (
+          <DeckViewer slides={slides.deck} title={slides.title} />
+        ) : null}
+
+        {slides.url === undefined ? null : (
+          <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+            <a
+              href={slides.url}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1.5 text-fd-primary underline underline-offset-4 transition-colors hover:text-fd-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+            >
+              Open the full presentation
+              <ExternalLink aria-hidden className="size-3.5" />
+            </a>
+            {provider === undefined ? null : (
+              <span className="font-mono text-xs text-fd-muted-foreground">{provider}</span>
+            )}
+          </p>
+        )}
+
+        {slides.embed === undefined ? null : (
+          <div
+            // 16:9, the aspect every deck host serves. A ratio box rather than
+            // a fixed height, so the frame scales with the measure instead of
+            // letterboxing on a narrow window.
+            className="relative w-full overflow-hidden rounded-lg border border-fd-border bg-fd-muted"
+            style={{ paddingBottom: "56.25%" }}
+          >
+            {loaded ? (
+              <iframe
+                src={slides.embed}
+                title={slides.title}
+                allowFullScreen
+                // No referrer: the provider learns that a deck was opened, not
+                // which document of this record it was opened from.
+                referrerPolicy="no-referrer"
+                loading="lazy"
+                className="absolute inset-0 size-full"
+              />
+            ) : (
+              <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 px-6 text-center">
+                <Presentation aria-hidden className="size-8 text-fd-muted-foreground" />
+                <Button onClick={() => setLoaded(true)}>Load the slides</Button>
+                <p className="max-w-sm text-xs text-fd-muted-foreground">
+                  {/* Said plainly, because it is the reason for the click. */}
+                  The deck is hosted{provider === undefined ? " elsewhere" : ` on ${provider}`}.
+                  Nothing is requested from there until you load it.
+                </p>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/lib/attachment-rule.ts

@@ -22,6 +22,7 @@ export const ATTACHMENT_SUFFIXES = [
   { suffix: ".summary.mdx", kind: "summary" },
   { suffix: ".flashcards.yaml", kind: "deck" },
   { suffix: ".quiz.yaml", kind: "quiz" },
+  { suffix: ".slides.yaml", kind: "slides" },
 ] as const;
 
 export type AttachmentKind = (typeof ATTACHMENT_SUFFIXES)[number]["kind"];
@@ -40,6 +41,8 @@ export const ATTACHMENT_NEAR_MISSES = [
   { suffix: ".summary.markdown", want: ".summary.md" },
   { suffix: ".quiz.yml", want: ".quiz.yaml" },
   { suffix: ".quiz.json", want: ".quiz.yaml" },
+  { suffix: ".slides.yml", want: ".slides.yaml" },
+  { suffix: ".slides.json", want: ".slides.yaml" },
 ] as const;
 
 /**
@@ -106,6 +109,7 @@ export const ATTACHMENT_CASES = [
   { name: "returns.summary.md", kind: "summary", parent: "returns.md" },
   { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
   { name: "returns.quiz.yaml", kind: "quiz", parent: "returns.md" },
+  { name: "returns.slides.yaml", kind: "slides", parent: "returns.md" },
   { name: "index.summary.md", kind: "summary", parent: "index.md" },
   // A stem containing dots keeps every one of them: the parent is the same
   // name with the attachment suffix removed, never "up to the first dot".
@@ -115,12 +119,14 @@ export const ATTACHMENT_CASES = [
   { name: "summary.md", kind: null, parent: null },
   { name: "flashcards.yaml", kind: null, parent: null },
   { name: "quiz.yaml", kind: null, parent: null },
+  { name: "slides.yaml", kind: null, parent: null },
   { name: "my-summary.md", kind: null, parent: null },
   // A dotfile with no stem attaches to nothing — refused as an attachment so
   // it is refused as an unexpected file instead, which is the honest error.
   { name: ".summary.md", kind: null, parent: null },
   { name: ".flashcards.yaml", kind: null, parent: null },
   { name: ".quiz.yaml", kind: null, parent: null },
+  { name: ".slides.yaml", kind: null, parent: null },
   // Case matters: the record already refuses two names differing only in case,
   // so an uppercase suffix is a different file, not the same rule.
   { name: "returns.SUMMARY.md", kind: null, parent: null },
@@ -128,4 +134,5 @@ export const ATTACHMENT_CASES = [
   { name: "returns.flashcards.yml", kind: null, parent: null },
   { name: "returns.flashcards.json", kind: null, parent: null },
   { name: "returns.quiz.yml", kind: null, parent: null },
+  { name: "returns.slides.yml", kind: null, parent: null },
 ] as const;

package/templates/scaffold/system/site/lib/attachments.ts

@@ -1,9 +1,11 @@
-import { decks, quizzes, summaries } from "collections/server";
+import { decks, quizzes, slides, summaries } from "collections/server";
 
 import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
 import { cardHash, type Card, type Deck } from "./deck";
 import { newCard, type CardSchedule } from "./srs";
 import { type Question, type Quiz } from "./quiz";
+import { type Slide, type Slides } from "./slides";
+import { embedUrlFor, providerOf } from "./slides-embed";
 import { DEFAULT_QUESTIONS_PER_ROUND } from "./quiz-round";
 import { questionHash } from "./identity";
 
@@ -117,12 +119,57 @@ export function quizFor(documentPath: string): QuizEntry | null {
   };
 }
 
+/** One slide the record carries. */
+export type DeckSlide = Slide;
+
+export interface SlidesEntry {
+  readonly title: string;
+  /** Absent when the record owns the deck — see `deck` below. */
+  readonly url?: string;
+  readonly description?: string;
+  /** Explicit `provider:`, when the author named one. */
+  readonly provider?: string;
+  /** Derived from the host when they did not — never guessed beyond the table. */
+  readonly derivedProvider?: string;
+  /** The framable url: the author's `embed:`, or one derived from `url`. */
+  readonly embed?: string;
+  /**
+   * Slides the record owns. When present this is the presentation, and there
+   * is no url — the schema refuses both, because two decks have no answer to
+   * which one governs.
+   */
+  readonly deck?: readonly DeckSlide[];
+  readonly path: string;
+}
+
+/** The presentation for a document, or null. */
+export function slidesFor(documentPath: string): SlidesEntry | null {
+  const wanted = attachmentPath(documentPath, ".slides.yaml");
+  const hit = slides.find((entry) => entry.info.path === wanted);
+  if (hit === undefined) return null;
+  const parsed = hit as unknown as Slides & { readonly info: { readonly path: string } };
+  const d = parsed.slides;
+  return {
+    title: d.title,
+    url: d.url,
+    deck: parsed.deck,
+    description: d.description,
+    provider: d.provider,
+    derivedProvider: d.url === undefined ? undefined : (providerOf(d.url) ?? undefined),
+    // An author's explicit embed wins; otherwise derive one, and a provider we
+    // do not know simply renders as a link.
+    embed: d.url === undefined ? undefined : (d.embed ?? embedUrlFor(d.url) ?? undefined),
+    path: parsed.info.path,
+  };
+}
+
 /** True when a document has ANY attachment — the presence gate for the UI. */
 export function hasAttachments(documentPath: string): boolean {
   return (
     summaryFor(documentPath) !== null ||
     deckFor(documentPath) !== null ||
-    quizFor(documentPath) !== null
+    quizFor(documentPath) !== null ||
+    slidesFor(documentPath) !== null
   );
 }