@panaversity/ksor 0.0.37 → 0.0.38

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @panaversity/ksor
 
+## 0.0.38
+
+### Patch Changes
+
+- ba15879: The scaffolded site says where a document sits on **every** page, and the trail
+  names the document itself.
+
+  The shell's breadcrumb renders the folders above a page and nothing else, so it
+  appeared on `/docs/surfaces/for-agents` and was absent on `/docs/installing` —
+  the block above the title came and went as a reader moved through the record,
+  and it was missing on exactly the documents at the top of it. A page now reads
+  `⌂ › Surfaces › The agent surface`: a home link, the folders, and the document
+  itself.
+
+  The home link goes to the record's front door at `/`. The record's name became
+  the page tree's root, replacing fumadocs' "Docs" default, so a screen reader
+  hears it as the home link's label.
+
+- 7eeb74d: New skill: **`make-summary`**. Ask your coding agent to summarise a document
+  and it writes `<doc>.summary.md` from the document, which the site renders as a
+  Summary tab beside the document's own words.
+
+  It is `make-slides`' discipline applied to prose: read the document whole,
+  write the summary, check every claim and every number back against it, and
+  report what it left out because the document did not support it.
+
+  With one rule of its own — **every `##` section must be represented**. A
+  summary that covers the opening and trails off is worse than none: a reader who
+  used it believes they have the whole document. It also declines to summarise a
+  document too short to compress, and says so, rather than writing a Summary tab
+  that restates the page.
+
+  Slides had a generator; summaries did not, which is why records tend to have
+  one summary and forty documents.
+
+- cb263d5: The eyebrow that names a region of a page — Teaching aid, In this section,
+  Sources — is one class now, and carries the record's accent.
+
+  It was the same string of utility classes typed out in three components, which
+  is how "Teaching aid" ended up accent-coloured and the other two grey: nothing
+  tied them together, so they drifted apart one edit at a time.
+
+- b8de20a: The scaffolded site no longer logs a React key warning on every page in
+  `pnpm dev`.
+
+  The shell renders the sidebar footer as one child of an array, so the element
+  needs a `key`. Without it React logged "Each child in a list should have a
+  unique key prop" naming `RecordShell`, on every route. A production build
+  strips the warning, which is why it survived — it only appears in the dev
+  server, which is where an adopter meets the site first.
+
+- 0f17283: A document's teaching aid now renders **after its introduction**, not above it.
+
+  The deck used to sit between the governance row and the first word of prose,
+  which reads as a slot in the page's furniture rather than as part of the
+  document — and on a long lesson it put a fourteen-slide deck in front of the
+  paragraph that says what the lesson is.
+
+  The placement comes from the document's own shape: the introduction is
+  everything before the first `##` section, so the aid goes immediately before
+  that heading, and a document with no sections gets it after its prose. No
+  marker in the record and no frontmatter key — the headings the author already
+  wrote are the structure.
+
+  The recall aids (flashcards, quiz) are unchanged and stay at the end, because
+  those are used after reading.
+
+  The aid is placed in documents only — a `<doc>.summary.md` goes through the
+  same pipeline and is rendered without one.
+
 ## 0.0.37
 
 ### Patch Changes

package/README.md

@@ -40,14 +40,17 @@ that document's page and nowhere else:
 | File                    | What it is                                             |
 | ----------------------- | ------------------------------------------------------ |
 | `<doc>.summary.md`      | a précis, shown as a second tab beside the document     |
-| `<doc>.slides.yaml`     | a presentation, at the top of the page                  |
+| `<doc>.slides.yaml`     | a presentation, after the document's introduction        |
 | `<doc>.flashcards.yaml` | a recall deck, at the end                               |
 | `<doc>.quiz.yaml`       | a multiple-choice check, at the end                     |
 
-Ask your coding agent — `make slides for knowledge/expenses/approvals.md` —
-and the `make-slides` skill writes the deck from the document, checks every
-claim and number back against it, and reports what it left out because the
-document did not support it.
+Ask your coding agent — `make slides for knowledge/expenses/approvals.md`, or
+`summarise knowledge/expenses/approvals.md` — and the `make-slides` and
+`make-summary` skills write the attachment from the document, check every claim
+and number back against it, and report what they left out because the document
+did not support it. A summary is checked section by section, because one that
+covers the opening and trails off leaves a reader believing they have the whole
+document.
 
 An attachment is **part of its document**: no URL, no sidebar row, no
 `llms.txt` line, and no id an agent can cite. It takes its `visibility:` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "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",
@@ -71,8 +71,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content": "0.0.0",
-    "@panaversity/ksor-content-gateway": "0.0.0"
+    "@panaversity/ksor-content-gateway": "0.0.0",
+    "@panaversity/ksor-content": "0.0.0"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/.agents/skills/make-summary/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: make-summary
+description: Write the summary of a document and attach it, so it renders as a second tab on that document's page. Use when the owner says "summarise X", "make a summary for this", "add summaries to the record", "give me the short version", or asks for a TL;DR, an abstract or a précis of a governed document.
+metadata:
+  version: "1.0.0"
+---
+
+# Writing the summary of a document
+
+You write the summary. Not an outline for somebody else to finish — the actual
+file, `<doc>.summary.md`, which the site renders as a **Summary** tab beside
+the document's own words.
+
+Run it end to end: read the document, write the summary, check every line back
+against the document, verify it builds. **The check is not optional** — it is
+what keeps a summary from becoming a second, unreviewed copy of the record.
+
+## The one rule everything else serves
+
+**A summary may only say what the document says.**
+
+It is a compression of the record, never a second source. A summary asserting a
+threshold the document does not contain is a claim nothing governs — and
+because the summary is an attachment, the record now stands behind it. Every
+number, date, name and rule is copied exactly, units included.
+
+If the document does not say something the summary seems to need, there are two
+honest options: leave it out, or tell the owner the document is missing it.
+Never a third.
+
+## The second rule: cover every section
+
+**Every `##` section of the document is represented in the summary.**
+
+A summary that covers the opening and trails off is worse than none: a reader
+who used it believes they have the whole document. Walk the headings in order
+and check each one has landed somewhere in the summary before you call it done.
+
+A `###` subsection does not need its own line — fold it into its parent's,
+unless it carries a rule or a number of its own, in which case it does.
+
+## 1 · Read the document whole, first
+
+Read `<doc>.md` completely before writing anything. Note as you go:
+
+- **the decision it settles** — the reason it exists, usually one sentence
+- **the rule, in its own words**
+- **the numbers** — thresholds, deadlines, limits, and their units
+- **each `##` section** — and the one thing it is there to say
+- **the boundary** — what the document explicitly does NOT cover
+- **its governance** — `owner`, `effective`, `status` from the frontmatter
+
+If the document already carries `<doc>.slides.yaml`, read it: it is a reviewed
+compression of the same thing, and the two must not disagree.
+
+## 2 · Write the summary
+
+Write `<doc>.summary.md` beside the document. **No frontmatter** — an
+attachment carries none, and the checker refuses one:
+
+```markdown
+The lead: what this document settles, in one or two sentences, in the
+document's own words. **Bold the thing a reader must not misremember.**
+
+- One line per `##` section, in the document's order.
+- Numbers exactly as the document states them, units included.
+- What the document explicitly does **not** cover.
+```
+
+**Shape:**
+
+| Part      | Use                                                      |
+| --------- | -------------------------------------------------------- |
+| lead      | one or two sentences — the decision the document settles |
+| bullets   | one per `##` section, in the document's own order        |
+| last line | the boundary: what this document does not settle         |
+
+**Length:** aim for a fifth of the document, and never more than a quarter. If
+the summary approaches the document's length, it has stopped being a summary
+— cut the elaboration, keep the rules.
+
+**Habits that decide whether it is any good:**
+
+- **Lead with the decision, not the definition.** A reader opening the Summary
+  tab wants what this settles, not what the topic is.
+- **Keep the document's own words for anything load-bearing.** Paraphrase the
+  explanation; copy the rule.
+- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
+- **Say what is excluded.** The boundary is the half a compression loses first
+  and the half a reader is most likely to get wrong.
+- **Do not add.** No context, no advice, no "note that" — the document is one
+  click away.
+
+## 3 · Check every line against the document
+
+Go back through the summary with the document open. For each line:
+
+- Is the claim in the document? Name where.
+- Is every number identical, same units, same rounding?
+- Does any line imply a rule the document does not state?
+- Walk the `##` headings in order: is each one represented?
+- Would a reader who read ONLY this be wrong about anything?
+
+That last question is the one that matters. A summary is used instead of the
+document, not before it.
+
+## 4 · Verify it
+
+```sh
+pnpm check     # refuses an orphan or an attachment carrying frontmatter
+pnpm dev       # open the page — a Summary tab appears beside Document
+```
+
+The build refuses:
+
+- `ksor-attachment-orphan` — no `<doc>.md` beside it
+- `ksor-attachment-frontmatter` — an attachment carries none of its own
+
+If no Summary tab appears, the file name is wrong: it must be exactly
+`<doc>.summary.md`, matching the document's own name.
+
+## 5 · Tell the owner what you did
+
+Which document, how long the summary is against the document, and **anything
+you left out because the document did not support it**. That last part is the
+useful half: it is how an owner finds out their document has a gap.
+
+Summarising several documents at once? Report them as a list with the same
+three facts each, and name any document you did NOT summarise and why — a
+document too short to compress does not need one, and saying so is the answer.
+
+## What NOT to do
+
+- **Do not summarise a document you have not read whole.** A summary written
+  from the first screen is confidently wrong about the rest.
+- **Do not write a line the document cannot support**, even a true one. If it
+  is not in the record, the record cannot stand behind it.
+- **Do not give a short document a summary.** Under roughly two screens there
+  is nothing to compress, and a Summary tab that restates the page teaches a
+  reader that the tab is not worth opening.
+- **Do not make one summary for several documents.** A summary belongs to one
+  document. One spanning five policies has no document to be governed by and
+  nothing to be withdrawn with.
+- **Do not patch a stale summary.** When the document changes materially,
+  rewrite from it. Patching is how a summary and its document drift, and a
+  reader on the Summary tab has no way to see that it happened.

package/templates/scaffold/.claude/skills/make-summary/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: make-summary
+description: Write the summary of a document and attach it, so it renders as a second tab on that document's page. Use when the owner says "summarise X", "make a summary for this", "add summaries to the record", "give me the short version", or asks for a TL;DR, an abstract or a précis of a governed document.
+metadata:
+  version: "1.0.0"
+---
+
+# Writing the summary of a document
+
+You write the summary. Not an outline for somebody else to finish — the actual
+file, `<doc>.summary.md`, which the site renders as a **Summary** tab beside
+the document's own words.
+
+Run it end to end: read the document, write the summary, check every line back
+against the document, verify it builds. **The check is not optional** — it is
+what keeps a summary from becoming a second, unreviewed copy of the record.
+
+## The one rule everything else serves
+
+**A summary may only say what the document says.**
+
+It is a compression of the record, never a second source. A summary asserting a
+threshold the document does not contain is a claim nothing governs — and
+because the summary is an attachment, the record now stands behind it. Every
+number, date, name and rule is copied exactly, units included.
+
+If the document does not say something the summary seems to need, there are two
+honest options: leave it out, or tell the owner the document is missing it.
+Never a third.
+
+## The second rule: cover every section
+
+**Every `##` section of the document is represented in the summary.**
+
+A summary that covers the opening and trails off is worse than none: a reader
+who used it believes they have the whole document. Walk the headings in order
+and check each one has landed somewhere in the summary before you call it done.
+
+A `###` subsection does not need its own line — fold it into its parent's,
+unless it carries a rule or a number of its own, in which case it does.
+
+## 1 · Read the document whole, first
+
+Read `<doc>.md` completely before writing anything. Note as you go:
+
+- **the decision it settles** — the reason it exists, usually one sentence
+- **the rule, in its own words**
+- **the numbers** — thresholds, deadlines, limits, and their units
+- **each `##` section** — and the one thing it is there to say
+- **the boundary** — what the document explicitly does NOT cover
+- **its governance** — `owner`, `effective`, `status` from the frontmatter
+
+If the document already carries `<doc>.slides.yaml`, read it: it is a reviewed
+compression of the same thing, and the two must not disagree.
+
+## 2 · Write the summary
+
+Write `<doc>.summary.md` beside the document. **No frontmatter** — an
+attachment carries none, and the checker refuses one:
+
+```markdown
+The lead: what this document settles, in one or two sentences, in the
+document's own words. **Bold the thing a reader must not misremember.**
+
+- One line per `##` section, in the document's order.
+- Numbers exactly as the document states them, units included.
+- What the document explicitly does **not** cover.
+```
+
+**Shape:**
+
+| Part      | Use                                                      |
+| --------- | -------------------------------------------------------- |
+| lead      | one or two sentences — the decision the document settles |
+| bullets   | one per `##` section, in the document's own order        |
+| last line | the boundary: what this document does not settle         |
+
+**Length:** aim for a fifth of the document, and never more than a quarter. If
+the summary approaches the document's length, it has stopped being a summary
+— cut the elaboration, keep the rules.
+
+**Habits that decide whether it is any good:**
+
+- **Lead with the decision, not the definition.** A reader opening the Summary
+  tab wants what this settles, not what the topic is.
+- **Keep the document's own words for anything load-bearing.** Paraphrase the
+  explanation; copy the rule.
+- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
+- **Say what is excluded.** The boundary is the half a compression loses first
+  and the half a reader is most likely to get wrong.
+- **Do not add.** No context, no advice, no "note that" — the document is one
+  click away.
+
+## 3 · Check every line against the document
+
+Go back through the summary with the document open. For each line:
+
+- Is the claim in the document? Name where.
+- Is every number identical, same units, same rounding?
+- Does any line imply a rule the document does not state?
+- Walk the `##` headings in order: is each one represented?
+- Would a reader who read ONLY this be wrong about anything?
+
+That last question is the one that matters. A summary is used instead of the
+document, not before it.
+
+## 4 · Verify it
+
+```sh
+pnpm check     # refuses an orphan or an attachment carrying frontmatter
+pnpm dev       # open the page — a Summary tab appears beside Document
+```
+
+The build refuses:
+
+- `ksor-attachment-orphan` — no `<doc>.md` beside it
+- `ksor-attachment-frontmatter` — an attachment carries none of its own
+
+If no Summary tab appears, the file name is wrong: it must be exactly
+`<doc>.summary.md`, matching the document's own name.
+
+## 5 · Tell the owner what you did
+
+Which document, how long the summary is against the document, and **anything
+you left out because the document did not support it**. That last part is the
+useful half: it is how an owner finds out their document has a gap.
+
+Summarising several documents at once? Report them as a list with the same
+three facts each, and name any document you did NOT summarise and why — a
+document too short to compress does not need one, and saying so is the answer.
+
+## What NOT to do
+
+- **Do not summarise a document you have not read whole.** A summary written
+  from the first screen is confidently wrong about the rest.
+- **Do not write a line the document cannot support**, even a true one. If it
+  is not in the record, the record cannot stand behind it.
+- **Do not give a short document a summary.** Under roughly two screens there
+  is nothing to compress, and a Summary tab that restates the page teaches a
+  reader that the tab is not worth opening.
+- **Do not make one summary for several documents.** A summary belongs to one
+  document. One spanning five policies has no document to be governed by and
+  nothing to be withdrawn with.
+- **Do not patch a stale summary.** When the document changes materially,
+  rewrite from it. Patching is how a summary and its document drift, and a
+  reader on the Summary tab has no way to see that it happened.

package/templates/scaffold/AGENTS.md

@@ -511,10 +511,11 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   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
+  second tab beside the document's own words; the presentation appears after
+  the document's INTRODUCTION — everything before its first `##` section —
+  because a deck is the shape of the thing and belongs where the reader has
+  just been told what the thing is; 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
@@ -686,6 +687,7 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
 - `.agents/skills/add-sources/` — turn source material (documents, pages,
   notes) into governed knowledge.
 - `.agents/skills/make-slides/` — generate a presentation from one document
+- `.agents/skills/make-summary/` — write a document's summary and attach it
   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

@@ -39,8 +39,9 @@ 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.
+a gap. The deck then renders on that document's page, straight after its
+introduction: 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
@@ -49,6 +50,28 @@ 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.
 
+### Summarising a document
+
+Long documents get a **Summary** tab beside their own words, and your agent
+writes it the same way:
+
+```
+summarise knowledge/expenses/approvals.md
+```
+
+The `make-summary` skill reads the document whole, writes
+`knowledge/expenses/approvals.summary.md`, and checks every line back against
+the document — every number, every rule, and every `##` section, because a
+summary that covers the opening and trails off is worse than none: a reader who
+used it believes they have the whole document. It reports what it left out
+because the document did not support it.
+
+The summary is part of its document, not a document of its own: no route, no
+sidebar row, no line in `llms.txt`, and it takes its governance from its
+parent. Ask for one only where there is something to compress — under about two
+screens, a summary that restates the page teaches readers the tab is not worth
+opening, and the skill will say so rather than write one.
+
 ### Serving to agents
 
 The record's other surface is an MCP server for AI agents — the same
@@ -183,7 +206,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), `make-slides` (generate a presentation from a document and attach it), `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), `make-summary` (write a document's summary 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/system/site/app/docs/[[...slug]]/page.tsx

@@ -14,6 +14,7 @@ import {
 } from "@/components/governance";
 import { predecessorsOf, readGovernance, resolveSuccessorUrl } from "@/lib/governance";
 import { showGovernance } from "@/lib/shared";
+import { RecordBreadcrumb } from "@/components/record-breadcrumb";
 import { RecordToc, TocItems } from "@/components/record-toc";
 import { RecordViews } from "@/components/record-views";
 import { Flashcards } from "@/components/flashcards";
@@ -96,7 +97,12 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
         // headings AHEAD of the reader. The observer's options are not
         // configurable and the observer is not exported, so the selection could
         // only be replaced — `slots.toc.main` is the seam for that.
+        // The breadcrumb is ours for one reason, recorded in the component:
+        // the shell's renders nothing at all on a top-level document, so the
+        // block above the title came and went as a reader moved through the
+        // record.
         slots={{
+          breadcrumb: RecordBreadcrumb,
           toc: {
             provider: TOCProvider,
             main: RecordToc,
@@ -126,12 +132,6 @@ 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
@@ -159,6 +159,14 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
                 // relative links between documents in knowledge/ resolve to
                 // their rendered pages
                 a: createRelativeLink(source, page),
+                // The deck, rendered where the record's own shape puts it:
+                // after the introduction, before the first section. The
+                // rehype plugin marks the place on every document and this
+                // decides whether there is anything to put there — so "does
+                // this document have a teaching aid" stays one question,
+                // answered by the attachment, not two.
+                TeachingAid: () =>
+                  presentation === null ? null : <Slides slides={presentation} />,
               })}
             />
           </RecordViews>

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

@@ -771,3 +771,70 @@ html > body[data-scroll-locked] {
 #nd-page > [class*="@container"]:last-child {
   margin-top: auto;
 }
+
+/* The breadcrumb.
+   Sentence case in the body face, not the mono uppercase of the OWNER row
+   below it: this is a path made of document TITLES, and uppercasing a title
+   makes a long one unreadable and a short one shout. The row beneath is
+   labels, which is a different job.
+
+   Home icon, chevron separators, and the document itself carried by weight
+   rather than by colour — the shape the owner asked for, 2026-08-24. */
+.ksor-breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.4;
+}
+
+.ksor-breadcrumb-home,
+.ksor-breadcrumb-step {
+  color: var(--color-fd-muted-foreground);
+  transition: color 0.15s ease;
+}
+
+.ksor-breadcrumb-home {
+  display: inline-flex;
+  align-items: center;
+}
+
+.ksor-breadcrumb-home:hover,
+.ksor-breadcrumb-step:hover {
+  color: var(--color-fd-foreground);
+}
+
+.ksor-breadcrumb-sep {
+  color: var(--color-fd-muted-foreground);
+  opacity: 0.5;
+}
+
+/* You-are-here: full-strength text where the path is muted. Weight and
+   contrast do the work, not colour — an accent here competes with the title
+   directly beneath it, which is the thing the reader is meant to land on. */
+.ksor-breadcrumb-here {
+  color: var(--color-fd-foreground);
+  font-weight: 500;
+}
+
+/* A SECTION LABEL: the eyebrow that names a region of the page — Teaching aid,
+   In this section, Sources.
+
+   One class, three readers. It was the same Tailwind string typed out in each
+   component, which is how "Teaching aid" ended up accent-coloured and the
+   other two grey: nothing tied them together, so they drifted apart one edit
+   at a time. The accent is what makes these read as the page's own structure
+   rather than as small grey text (owner, 2026-08-24).
+
+   Not for the sidebar or the table-of-contents rail — those label the chrome
+   around the document, and this labels the document. */
+.ksor-section-label {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--color-fd-primary);
+}

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

@@ -215,9 +215,7 @@ export function Provenance({ entries }: { entries: readonly string[] }): ReactEl
 
   return (
     <section className="mt-10 border-t border-fd-border pt-5 text-sm">
-      <h2 className="mb-2 font-mono text-xs tracking-[0.18em] text-fd-muted-foreground uppercase">
-        Sources
-      </h2>
+      <h2 className="ksor-section-label mb-2">Sources</h2>
       {/* break-words, because a citation is often a long unbroken URL: on a
           phone it overflowed its row by 175px under an ancestor with
           `overflow-x: clip`, so the middle of the source was clipped away with

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

@@ -26,6 +26,12 @@ function BrandedTabsTrigger({
 export function getMDXComponents(components?: MDXComponents) {
   return {
     ...defaultMdxComponents,
+    // The teaching-aid marker, rendering NOTHING unless a caller supplies a
+    // deck. The rehype plugin inserts the marker into every document, and MDX
+    // throws on a component it was not given — so the default has to exist
+    // here or a document whose page forgot to pass one serves a 500 rather
+    // than a page without an aid.
+    TeachingAid: () => null,
     // `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.

package/templates/scaffold/system/site/components/record-breadcrumb.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { getBreadcrumbItemsFromPath } from "fumadocs-core/breadcrumb";
+import Link from "fumadocs-core/link";
+import { useTreeContext, useTreePath } from "fumadocs-ui/contexts/tree";
+import type { BreadcrumbProps } from "fumadocs-ui/layouts/docs/page/slots/breadcrumb";
+import { ChevronRight, Home } from "lucide-react";
+import { Fragment, type ReactElement } from "react";
+
+/**
+ * Where this document sits — on EVERY document, including the top-level ones.
+ *
+ * The shell's own breadcrumb renders the folders above a page and nothing
+ * else, so it appeared on `/docs/surfaces/for-agents` and was absent on
+ * `/docs/installing` (measured on the built pages: two of three blank). A
+ * reader clicking between them watched the block above the title appear and
+ * disappear, and the pages with no trail were exactly the ones at the top of
+ * the record.
+ *
+ * The shell has an `includeRoot` option that looks like the fix and is not:
+ * it only fires for a folder marked `root: true` in the page tree, which a
+ * plain `knowledge/` tree has none of (fumadocs-core 16.14.5, breadcrumb.js —
+ * the `item.root` branch). So the root is prepended here instead.
+ *
+ * The trail ENDS IN THE PAGE (owner's call, 2026-08-24). The first cut left it
+ * out — the title is the h1 directly beneath, so ending the trail in the
+ * heading you are already reading looked like a duplicate. It reads the other
+ * way round on a real record: without the page the trail is folders only, so a
+ * top-level document got a single word and no sense of place at all.
+ *
+ * The root is a HOME ICON, not the record's name (owner's call, 2026-08-24).
+ * The name is a project slug — `quiz-demo` — which is an identifier rather
+ * than a place, and the record's real name is already at the top of the
+ * sidebar. The name stays as the icon's accessible label, so a screen reader
+ * hears where the link goes.
+ */
+export function RecordBreadcrumb({
+  includeRoot: _includeRoot,
+  includePage: _includePage,
+  includeSeparator,
+  ...props
+}: BreadcrumbProps): ReactElement {
+  const path = useTreePath();
+  const { root } = useTreeContext();
+  const trail = getBreadcrumbItemsFromPath(root, path, { includePage: true, includeSeparator });
+
+  return (
+    <nav {...props} aria-label="Breadcrumb" className={`ksor-breadcrumb ${props.className ?? ""}`}>
+      {/* The record's front door is `/`, not `/docs` — the home page wears the
+          same shell (components/record-shell.tsx) and there is no `/docs`
+          route at all. Linking there served a 404 from the first item of every
+          page's breadcrumb; caught by walking the built routes. */}
+      <Link className="ksor-breadcrumb-home" href="/" aria-label={`${root.name} home`}>
+        <Home className="size-4" aria-hidden />
+      </Link>
+      {trail.map((item, index) => (
+        <Fragment key={index}>
+          <ChevronRight className="ksor-breadcrumb-sep size-3.5 shrink-0" aria-hidden />
+          {item.url && index < trail.length - 1 ? (
+            <Link className="ksor-breadcrumb-step" href={item.url}>
+              {item.name}
+            </Link>
+          ) : (
+            // The document itself: never a link to the page you are on.
+            <span className="ksor-breadcrumb-here" aria-current="page">
+              {item.name}
+            </span>
+          )}
+        </Fragment>
+      ))}
+    </nav>
+  );
+}

package/templates/scaffold/system/site/components/record-index.tsx

@@ -47,9 +47,7 @@ export function RecordIndex({
     <section className="mt-14">
       {/* The head of the list stays a register head: this is a label, and a
           label is machine-facing furniture whatever the rows below it are. */}
-      <h2 className="mb-3 font-mono text-xs tracking-[0.18em] text-fd-muted-foreground uppercase">
-        {heading}
-      </h2>
+      <h2 className="ksor-section-label mb-3">{heading}</h2>
 
       <ul className="grid gap-3">
         {entries.map((entry) => {

package/templates/scaffold/system/site/components/record-shell.tsx

@@ -36,8 +36,15 @@ export function RecordShell({ children }: { children: ReactNode }): ReactElement
       // After the spread: a future sidebar key in baseOptions must not
       // silently swallow the attribution (review finding, 2026-08-18).
       sidebar={{
+        // `key`, because the shell renders this footer as one child of an
+        // ARRAY (fumadocs-ui 16.14.5, layouts/docs/slots/sidebar.js — the
+        // branch that also holds the language select, icon links and theme
+        // switch). Without it React logs "Each child in a list should have a
+        // unique key prop" naming RecordShell, on every page. Invisible in a
+        // production build, which is why it survived: it only shows in the
+        // dev server, where the adopter meets it first.
         footer: (
-          <div className="mt-3 flex flex-col gap-2">
+          <div key="record-footer" className="mt-3 flex flex-col gap-2">
             {/* The record's own identity, on every page rather than only the
                 home page: the slug is what citations carry and llms.txt is the
                 door an agent is told to read. The sidebar had three links and

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

@@ -48,9 +48,7 @@ export function Slides({ slides }: { slides: SlidesEntry }): ReactElement {
           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>
+        <p className="ksor-section-label">Teaching aid</p>
         <h2 className="mt-2 font-(family-name:--font-display) text-2xl font-semibold tracking-tight text-fd-foreground">
           {slides.title}
         </h2>

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

@@ -36,6 +36,14 @@ export const source = loader({
   ],
 });
 
+// The page tree's root is named "Docs" by default — fumadocs' fallback for a
+// directory carrying no meta.json. It names the software, not the thing a
+// reader is inside, and it is what the breadcrumb's first item says. The
+// record already has a name in instance.md, so it says that instead. Set here
+// rather than passed to the breadcrumb, because `slots` crosses a client
+// boundary and a server value cannot ride along with it — the tree can.
+source.pageTree.name = appName;
+
 export type KnowledgePage = (typeof source)["$inferPage"];
 
 // Sub-path hosting prefix, for URLs we WRITE INTO TEXT (llms.txt,

package/templates/scaffold/system/site/lib/teaching-aid-rule.ts

@@ -0,0 +1,92 @@
+/**
+ * WHERE the teaching aid sits in a document: after its introduction.
+ *
+ * The deck used to render above the document, between the governance row and
+ * the first word of prose. That reads as a slot in the page's furniture rather
+ * than as part of the document, and on a long lesson it puts a fourteen-slide
+ * deck in front of the paragraph that says what the lesson is.
+ *
+ * The rule is the document's own shape: a document's INTRODUCTION is
+ * everything before its first `##` section, so the aid goes immediately before
+ * that heading. It needs no marker in the record and no frontmatter key — the
+ * headings the author already wrote are the structure. A document with no
+ * sections has no such seam, and the aid follows its prose instead.
+ *
+ * This is where the imported course put its own `## Teaching Aid` by hand:
+ * after the intro material, immediately before Part 1.
+ *
+ * The marker goes into DOCUMENTS only. `<doc>.summary.md` goes through the
+ * same MDX pipeline (source.config.ts, the `summaries` collection) and is
+ * rendered with the page's own component map, which does not carry a teaching
+ * aid — so marking one threw "Expected component `TeachingAid` to be defined"
+ * and served a 500 for every document that has a summary. Found live in the
+ * dev server, on the first page with one.
+ *
+ * What counts as an attachment is HANDED IN rather than imported: this file
+ * has to stay import-free so the repo's own tests can take it on its own (a
+ * relative import here needs a `.js` extension for tsc that Next's resolver
+ * then rejects). Handing it in keeps lib/attachment-rule.ts the one place the
+ * suffix list lives — a second copy here is exactly the drift the attachment
+ * rule is written to prevent.
+ */
+
+/** The heading level that starts a section. `##` — `#` is the page title. */
+export const SECTION_HEADING = "h2";
+
+/** The component the site swaps in for the marker. */
+export const TEACHING_AID_ELEMENT = "TeachingAid";
+
+export interface TeachingAidOptions {
+  /** lib/attachment-rule.ts's `isAttachment`, handed in — see above. */
+  readonly isAttachment: (baseName: string) => boolean;
+}
+
+interface AidNode {
+  type: string;
+  tagName?: string;
+  children?: AidNode[];
+  name?: string;
+  attributes?: unknown[];
+}
+
+/**
+ * The index in `children` the aid belongs at: before the first `h2`, or after
+ * everything when the document has no sections.
+ */
+export function teachingAidIndex(children: readonly AidNode[]): number {
+  const first = children.findIndex(
+    (child) => child.type === "element" && child.tagName === SECTION_HEADING,
+  );
+  return first === -1 ? children.length : first;
+}
+
+/**
+ * Rehype plugin: put a `<TeachingAid />` marker where the aid belongs.
+ *
+ * The marker is ALWAYS inserted; the component the page supplies renders null
+ * when the document carries no deck. That keeps the decision about whether
+ * there is an aid in one place (`slidesFor`, on the server) instead of
+ * splitting it between a plugin and a component.
+ *
+ * Rehype rather than remark for the reason lib/alert-rule.ts records: the
+ * record's markdown is serialized from the mdast, so a marker inserted there
+ * would appear in `/md/` and `llms-full.txt`, publishing a component of this
+ * site to the agent surface.
+ */
+export function rehypeTeachingAid(
+  options: TeachingAidOptions,
+): (tree: AidNode, file: { path?: string }) => void {
+  return (tree: AidNode, file: { path?: string }): void => {
+    const name = (file.path ?? "").split(/[/\\]/).pop() ?? "";
+    if (options.isAttachment(name)) return;
+
+    const children = tree.children;
+    if (!children) return;
+    children.splice(teachingAidIndex(children), 0, {
+      type: "mdxJsxFlowElement",
+      name: TEACHING_AID_ELEMENT,
+      attributes: [],
+      children: [],
+    });
+  };
+}

package/templates/scaffold/system/site/source.config.ts

@@ -5,6 +5,8 @@ import { z } from "zod";
 import { DeckSchema } from "./lib/deck";
 import { QuizSchema } from "./lib/quiz";
 import { SlidesSchema } from "./lib/slides";
+import { isAttachment } from "./lib/attachment-rule";
+import { rehypeTeachingAid } from "./lib/teaching-aid-rule";
 import { knowledgeSourceDir } from "./lib/stage-knowledge";
 
 // The record lives at <repo>/knowledge — two levels up from this site.
@@ -115,6 +117,13 @@ export const slides = defineCollections({
 
 export default defineConfig({
   mdxOptions: {
+    /**
+     * WHERE the teaching aid sits: after the document's introduction, which
+     * is everything before its first `##` section. The plugin only marks the
+     * place; the page decides whether there is a deck to put there. See
+     * lib/teaching-aid-rule.ts.
+     */
+    rehypePlugins: [[rehypeTeachingAid, { isAttachment }]],
     /**
      * Alternative versions of the same instruction, as TABS.
      *