@panaversity/ksor 0.0.30 → 0.0.32

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,70 @@ 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.
+
+- **One instruction per tool, as tabs.** When a document has to say the same
+  thing two ways — one command for one agent, another for another — put each in
+  its own fenced block and give the fence a `tab`:
+
+  ````markdown
+  ```bash tab="Claude Code" tab-group="agent"
+  curl -fsSL https://claude.ai/install.sh | bash
+  ```
+
+  ```bash tab="OpenCode" tab-group="agent"
+  curl -fsSL https://opencode.ai/install | bash
+  ```
+  ````
+
+  Consecutive blocks that declare a `tab` become one tab group. This is still
+  CommonMark: a fence's info string is free text, so any other markdown reader
+  shows both blocks one after another — correct, just without the picker.
+
+  **`tab-group` is what makes the choice stick.** Blocks sharing a group name
+  switch together across the whole page and the choice is remembered for the
+  reader's next visit, so a document with ten tabbed sections is one decision
+  rather than ten. Leave it off and each group is independent, which is almost
+  never what you want. Use the same group name for the same axis throughout a
+  record.
+
+  A tool the site knows gets its own colour and mark on its tab; anything else
+  renders in the site's accent. The list lives in `system/site/app/global.css`
+  and is yours — adding a tool is one colour and one mark.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 
@@ -617,6 +684,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.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,142 @@ html > body[data-scroll-locked] {
   --ksor-caution: #e0906e;
 }
 
+/* A tool's own colour, across the whole block.
+
+   When a document gives one instruction per tool, the tab is the moment a
+   reader picks theirs, so the choice is worth being unmistakable. The colour
+   is not confined to the tab: the strip and the panel take a wash of it too,
+   in two different strengths, so the block says which tool you are reading at
+   any scroll position and the strip still reads as a distinct band.
+
+   Each tool declares ONE value and shared rules do the rest, so adding a tool
+   is a line rather than a set. `:has()` lifts the active tab's colour onto the
+   container, which is what lets the panel follow the tab.
+
+   Keyed on `data-tab-value`, which `components/mdx.tsx` puts on the trigger.
+   Radix also encodes the value in its generated id, but that is a private
+   format and keying on it would drop the branding silently if it changed.
+
+   THIS BLOCK IS YOURS. These are the tools this scaffold happened to know
+   about; a tab value matching nothing renders in the site's own accent, which
+   is the right default for a record whose tabs are npm/pnpm or US/EU. Add
+   your own, or delete the block — nothing else depends on it. Values are the
+   vendors' own. */
+.prose [data-orientation]:has([data-tab-value="Claude Code"][data-state="active"]) {
+  --ksor-tool: #da7756;
+}
+
+.prose [data-orientation]:has([data-tab-value="OpenCode"][data-state="active"]) {
+  --ksor-tool: #6366f1;
+}
+
+/* A decorative mark per tool. Purely visual — the label beside it is the
+   accessible name — so it is CSS content rather than markup an author would
+   have to write. */
+.prose [role="tab"][data-tab-value="Claude Code"]::before {
+  content: "\2726";
+}
+
+.prose [role="tab"][data-tab-value="OpenCode"]::before {
+  content: "</>";
+  font-size: 0.85em;
+  letter-spacing: -0.05em;
+}
+
+/* Everything below is shared, and applies only where a tool was recognised. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) {
+  background-color: color-mix(in oklab, var(--ksor-tool) 7%, transparent);
+  border-color: color-mix(in oklab, var(--ksor-tool) 28%, transparent);
+  overflow: hidden;
+}
+
+/* The strip is a BAND: stronger than the panel, full width, and the tabs sit
+   inside it rather than floating above it. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) > [role="tablist"] {
+  background-color: color-mix(in oklab, var(--ksor-tool) 20%, transparent);
+  border-bottom: 1px solid color-mix(in oklab, var(--ksor-tool) 26%, transparent);
+  padding: 0.5rem;
+  gap: 0.25rem;
+}
+
+.prose [role="tab"][data-tab-value] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  /* Big enough to be a target and to read as a block rather than a word. */
+  padding: 0.7rem 1.5rem;
+  font-size: 0.95rem;
+  font-weight: 600;
+  border-radius: 0.25rem;
+}
+
+.prose [role="tab"][data-tab-value][data-state="active"] {
+  background-color: var(--ksor-tool);
+  color: #fff;
+}
+
+.prose [role="tab"][data-tab-value][data-state="inactive"]:hover {
+  background-color: color-mix(in oklab, var(--ksor-tool) 14%, transparent);
+}
+
+/* The code sits INSET on the wash, with its own surface, so the panel reads as
+   a frame around it. A tinted block on a tinted panel is one colour with words
+   in it, and the code is the part somebody actually has to read. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) figure {
+  margin: 1.25rem;
+  background-color: var(--card);
+  border-color: color-mix(in oklab, var(--ksor-tool) 18%, transparent);
+}
+
+.dark .prose [data-orientation]:has([data-tab-value][data-state="active"]) figure {
+  background-color: color-mix(in oklab, var(--muted) 88%, #000);
+}
+
+/* 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/mdx.tsx

@@ -1,9 +1,37 @@
 import defaultMdxComponents from "fumadocs-ui/mdx";
+import { CodeBlockTabsTrigger } from "fumadocs-ui/components/codeblock";
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import type { MDXComponents } from "mdx/types";
+import type * as React from "react";
+
+/**
+ * A tab trigger that says WHICH tab it is, in an attribute we own.
+ *
+ * Radix already encodes the value in its generated `id`
+ * (`radix-…-trigger-Claude Code`), and styling could key on that — but that is
+ * a private format, so a change upstream would drop the branding silently and
+ * nothing would go red. One attribute of our own costs a few lines and cannot
+ * be taken away.
+ *
+ * `app/global.css` uses it to give a known tool its own colour; a tab value it
+ * does not recognise simply renders in the site's own accent.
+ */
+function BrandedTabsTrigger({
+  value,
+  ...props
+}: React.ComponentProps<typeof CodeBlockTabsTrigger>): React.ReactElement {
+  return <CodeBlockTabsTrigger data-tab-value={value} value={value} {...props} />;
+}
 
 export function getMDXComponents(components?: MDXComponents) {
   return {
     ...defaultMdxComponents,
+    // `remarkCodeTab` (source.config.ts) rewrites consecutive fenced blocks
+    // that declare `tab="…"` into these, so they have to be in the map or the
+    // build fails on an unknown component rather than at authoring time.
+    Tabs,
+    Tab,
+    CodeBlockTabsTrigger: BrandedTabsTrigger,
     ...components,
   } satisfies MDXComponents;
 }