@panaversity/ksor 0.0.26 → 0.0.28

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @panaversity/ksor
 
+## 0.0.28
+
+### Patch Changes
+
+- 24ec8c3: Each document page now says how long it takes to read.
+
+  The figure is counted when the site is built, from the document's own markdown,
+  so it is in the shipped HTML — a reader whose bundle failed, a crawler and an
+  agent parsing the page all get it. Fenced code and frontmatter are left out of
+  the count, so a short page carrying a long example is not reported as a
+  twenty-minute read.
+
+  Nothing to author: it is derived from the words already there. Where a document
+  has a summary, both tabs carry their own figure, so a reader can see what the
+  summary saves them before opening it.
+
+- 6abcf1f: Summaries and flashcard decks, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry two companions named after it —
+  `<doc>.summary.md` and `<doc>.flashcards.yaml`. The summary joins the record's
+  own words as a second tab; the deck renders at the end of the page, with spaced
+  review kept in the reader's browser and Shuffle / Guide / Download beneath it.
+  `ksor init` ships one of each so a fresh project shows the shape rather than
+  describing it.
+
+  An attachment is **part of its document, not a document**. It gets no URL, no
+  sidebar row, no `llms.txt` line, no markdown twin, no search entry — and no
+  stable id, so an agent can never cite it as a source in its own right. It takes
+  its `visibility:` and its takedown from its parent: restrict or withdraw the
+  document and its summary and deck go with it. An attachment declaring
+  frontmatter, or one whose document is missing, is refused by `pnpm check` and by
+  `pnpm build`.
+
+  **If your record already has `.summary.md` files and you serve over MCP, read
+  this.** They were previously ingested as ordinary documents, each with its own
+  id and its own governance defaults. They no longer are. After upgrading, run
+  `pnpm refresh`; if a takedown names one of those ids, `ksor serve` will refuse
+  to boot until the denial is pointed at the parent document or retired
+  deliberately. That refusal is the fix working — those rows governed a node that
+  should never have existed.
+
+  Review scheduling is a two-grade SM-2 variant (`ksor-sm2-v1`). It is not FSRS
+  and claims no retention target.
+
+## 0.0.27
+
+### Patch Changes
+
+- 6bc9d8f: The emitted `Dockerfile` names the files it copies instead of `COPY . ./`.
+
+  **A `.dockerignore` is not honoured by every build host.** Vercel's container
+  builder ignores it, so `COPY . ./` swept in `node_modules` and the built site —
+  about a gigabyte — and the deploy failed with the registry rejecting the push as
+  `PAYLOAD_TOO_LARGE`. The error arrives from the host and says nothing about the
+  file that caused it.
+
+  Naming what enters the image is the only form portable across build hosts. The
+  `.dockerignore` stays as defence in depth for builders that do respect it, but it
+  is no longer what bounds the image.
+
+  The risk of naming files is forgetting one — which is exactly how the registration
+  file came to be missing from the image two releases ago. That is covered: the
+  container acceptance job boots the built image and asserts it serves the tools the
+  registration names, so a forgotten file fails there rather than at a deploy.
+
 ## 0.0.26
 
 ### Patch Changes

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
-import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-BF06IsJ--D-eI--yB.mjs";
+import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-DE9PhWEx.mjs
+//#region ../content-gateway/dist/main-DiX1MNMX.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -1552,7 +1552,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-FLQD4HUi.mjs
+//#region ../content/dist/commands-DU1nqwZa.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4148,6 +4148,54 @@ function compareSiblings(a, b) {
 	return codePointCompare$1(a.tie, b.tie);
 }
 /**
+* What makes a file in the record an ATTACHMENT rather than a document.
+*
+* A document may carry study attachments named after it — `x.summary.md` and
+* `x.flashcards.yaml` belong to `x.md` in the same directory. An attachment is
+* PART OF its parent: no route, no sidebar entry, no llms.txt line, no stable
+* id, no MCP node, and its parent's governance rather than its own.
+*
+* This rule is duplicated by construction — the kernel's ingest decides what
+* becomes a node, the site's staging decides what is copied, the site's build
+* decides what is a page, and the record's checker decides what is well-formed.
+* Four readers of one rule is exactly the shape decision 18 names, so this file
+* is canonical and every other copy is asserted against it rather than trusted.
+*
+* A LEAF: no imports, so any of those four can take it without taking anything
+* else with it.
+*/
+/** The suffix that marks each kind, longest-match first. */
+const ATTACHMENT_SUFFIXES = [
+	{
+		suffix: ".summary.md",
+		kind: "summary"
+	},
+	{
+		suffix: ".summary.mdx",
+		kind: "summary"
+	},
+	{
+		suffix: ".flashcards.yaml",
+		kind: "deck"
+	}
+];
+/**
+* The attachment kind this file name carries, or null when it is not one.
+*
+* Matched on the whole base name, never on a path: `.summary.md` in a directory
+* called `summary` is not an attachment, and a file called exactly
+* `.summary.md` (a dotfile with no stem) has no parent to attach to and is not
+* one either — the same "a dotfile has no suffix" boundary ingest's isDoc uses.
+*/
+function attachmentKindOf(baseName) {
+	for (const entry of ATTACHMENT_SUFFIXES) if (baseName.length > entry.suffix.length && baseName.endsWith(entry.suffix)) return entry.kind;
+	return null;
+}
+/** True when this file name is an attachment of some document. */
+function isAttachment(baseName) {
+	return attachmentKindOf(baseName) !== null;
+}
+/**
 * The plain-tree corpus adapter — ANY folder of Markdown becomes a corpus.
 * Converted from the oracle (sor-agentfactory @ b554f91,
 * ingest/adapters/plain_tree.py); the kernel cannot tell this manifest from
@@ -4360,8 +4408,23 @@ function buildManifestFromTree(root, options) {
 		sources
 	};
 }
-/** Python `p.suffix in (".md", ".mdx")` parity: a dotfile named exactly ".md" has NO suffix. */
+/**
+* Python `p.suffix in (".md", ".mdx")` parity: a dotfile named exactly ".md"
+* has NO suffix.
+*
+* ATTACHMENTS ARE NOT DOCUMENTS. `x.summary.md` ends in `.md`, so without the
+* attachment rule it ingested as a node of its own — `stable_id`
+* `knowledge/x.summary`, its own `content_nodes.visibility` coalescing to the
+* record default, and its own takedown state. That is one cause wearing four
+* costumes: the door served a summary the site hides; served an internal
+* parent's summary at the public tier; served a taken-down parent's summary
+* undenied (per-node denial matches a different id, and the subtree walk goes
+* through `parent_id`, which is the enclosing SECTION, not the sibling
+* document); and served an orphan the site refuses. An attachment belongs to
+* its parent, so it gets no id and is never independently citable.
+*/
 function isDoc(name) {
+	if (isAttachment(name)) return false;
 	const dot = name.lastIndexOf(".");
 	if (dot <= 0) return false;
 	const suffix = name.slice(dot);

package/dist/{gateway-api-BF06IsJ--D-eI--yB.mjs → gateway-api-8lNruq9e-CuohjtoK.mjs}

@@ -5,7 +5,7 @@ import { z, z as z$1 } from "zod";
 import pg from "pg";
 import path from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region ../content-gateway/dist/gateway-api-BF06IsJ-.mjs
+//#region ../content-gateway/dist/gateway-api-8lNruq9e.mjs
 /**
 * The record's system prompt: instance.md's body, preserved beneath a framework
 * floor. Lifted out of server.ts so the public gateway surface can re-export

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-BF06IsJ--D-eI--yB.mjs";
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/.agents/skills/format-checker/check.mjs

@@ -35,6 +35,35 @@ const REQUIRED_KEYS = ["title", "status"]; // level 0 — the ladder, not a gate
 const STATUS_VALUES = new Set(["draft", "review", "approved", "superseded"]);
 const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]);
 
+// Study attachments: `x.summary.md` and `x.flashcards.yaml` belong to `x.md`.
+// An attachment is PART OF its parent — no route, no stable id, no governance
+// of its own — so it is neither a document nor an asset, and gets its own
+// rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
+// this dependency-free file cannot import; ATTACHMENT_CASES there is the table
+// both are held to.
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+// One character off a real attachment, refused BY NAME: `.yml` reaches the
+// site bundler's `Unknown file type` throw, which names the path and nothing
+// about the rule.
+const ATTACHMENT_NEAR_MISSES = [
+  [".flashcards.yml", ".flashcards.yaml"],
+  [".flashcards.json", ".flashcards.yaml"],
+  [".summary.markdown", ".summary.md"],
+];
+
+/** The attachment suffix this name carries, or null. A dotfile has no stem. */
+function attachmentSuffixOf(base) {
+  return ATTACHMENT_SUFFIXES.find((s) => base.length > s.length && base.endsWith(s)) ?? null;
+}
+function isAttachment(base) {
+  return attachmentSuffixOf(base) !== null;
+}
+/** The document an attachment belongs to: always `<stem>.md`. */
+function parentDocumentOf(base) {
+  const suffix = attachmentSuffixOf(base);
+  return suffix === null ? null : `${base.slice(0, -suffix.length)}.md`;
+}
+
 // PNG integrity, dependency-free: signature + per-chunk CRC-32. A damaged
 // image beside a document is a check-time problem with the file named, never
 // a build-time 500 with no filename in it.
@@ -381,7 +410,9 @@ if (!existsSync(knowledgeDir)) {
   }
   const dirs = walkDirs(knowledgeDir);
   const all = [...files, ...dirs];
-  const mdFiles = files.filter((p) => p.endsWith(".md"));
+  // Attachments are never documents: they carry no frontmatter, own no route,
+  // and are checked by their own rules instead.
+  const mdFiles = files.filter((p) => p.endsWith(".md") && !isAttachment(path.basename(p)));
 
   if (mdFiles.length === 0) {
     problem(
@@ -446,7 +477,12 @@ if (!existsSync(knowledgeDir)) {
       );
     }
     seenLower.set(lower, rel);
-    if (files.includes(p) && !p.endsWith(".md") && !ASSET_EXTENSIONS.has(path.extname(p))) {
+    if (
+      files.includes(p) &&
+      !p.endsWith(".md") &&
+      !isAttachment(base) &&
+      !ASSET_EXTENSIONS.has(path.extname(p))
+    ) {
       problem(
         rel,
         `unexpected file type "${path.extname(p) || base}"`,
@@ -486,6 +522,51 @@ if (!existsSync(knowledgeDir)) {
     }
   }
 
+  // Study attachments: bound to a parent, carrying no governance of their own.
+  for (const p of files) {
+    const base = path.basename(p);
+    const rel = path.relative(root, p);
+
+    const nearMiss = ATTACHMENT_NEAR_MISSES.find(
+      ([wrong]) => base.length > wrong.length && base.endsWith(wrong),
+    );
+    if (nearMiss && !isAttachment(base)) {
+      problem(
+        rel,
+        `${nearMiss[0]} is not an attachment extension`,
+        "the site reads decks as YAML and accepts only .yaml — a near miss is not picked up as a deck, and fails the build naming the path but not the rule",
+        `rename it to ${base.slice(0, -nearMiss[0].length)}${nearMiss[1]}`,
+      );
+      continue;
+    }
+
+    if (!isAttachment(base)) continue;
+
+    const parent = parentDocumentOf(base);
+    if (parent && !existsSync(path.join(path.dirname(p), parent))) {
+      problem(
+        rel,
+        `attachment of ${parent}, which is not in the record`,
+        "an attachment inherits its parent's governance — with no parent there is nothing to inherit, so it would be published under no tier and covered by no takedown",
+        `add ${path.join(path.dirname(rel), parent)}, or remove ${rel}`,
+      );
+    }
+
+    if (base.endsWith(".md") || base.endsWith(".mdx")) {
+      const text = readFileSync(p, "utf8")
+        .replace(/^\uFEFF/, "")
+        .replaceAll("\r\n", "\n");
+      if (text.startsWith("---\n")) {
+        problem(
+          rel,
+          "attachment declares frontmatter",
+          "an attachment is part of its parent and carries none of its own governance — a key here would look like it governs something and would govern nothing (a visibility: on a summary of a restricted document is the shape that matters)",
+          `remove the frontmatter block; ${parent ?? "its parent"} is what carries the governance`,
+        );
+      }
+    }
+  }
+
   // foo.md vs foo/index.md route collisions
   for (const p of mdFiles) {
     const sibling = p.replace(/\.md$/, "");

package/templates/scaffold/.claude/skills/format-checker/check.mjs

@@ -35,6 +35,35 @@ const REQUIRED_KEYS = ["title", "status"]; // level 0 — the ladder, not a gate
 const STATUS_VALUES = new Set(["draft", "review", "approved", "superseded"]);
 const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]);
 
+// Study attachments: `x.summary.md` and `x.flashcards.yaml` belong to `x.md`.
+// An attachment is PART OF its parent — no route, no stable id, no governance
+// of its own — so it is neither a document nor an asset, and gets its own
+// rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
+// this dependency-free file cannot import; ATTACHMENT_CASES there is the table
+// both are held to.
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+// One character off a real attachment, refused BY NAME: `.yml` reaches the
+// site bundler's `Unknown file type` throw, which names the path and nothing
+// about the rule.
+const ATTACHMENT_NEAR_MISSES = [
+  [".flashcards.yml", ".flashcards.yaml"],
+  [".flashcards.json", ".flashcards.yaml"],
+  [".summary.markdown", ".summary.md"],
+];
+
+/** The attachment suffix this name carries, or null. A dotfile has no stem. */
+function attachmentSuffixOf(base) {
+  return ATTACHMENT_SUFFIXES.find((s) => base.length > s.length && base.endsWith(s)) ?? null;
+}
+function isAttachment(base) {
+  return attachmentSuffixOf(base) !== null;
+}
+/** The document an attachment belongs to: always `<stem>.md`. */
+function parentDocumentOf(base) {
+  const suffix = attachmentSuffixOf(base);
+  return suffix === null ? null : `${base.slice(0, -suffix.length)}.md`;
+}
+
 // PNG integrity, dependency-free: signature + per-chunk CRC-32. A damaged
 // image beside a document is a check-time problem with the file named, never
 // a build-time 500 with no filename in it.
@@ -381,7 +410,9 @@ if (!existsSync(knowledgeDir)) {
   }
   const dirs = walkDirs(knowledgeDir);
   const all = [...files, ...dirs];
-  const mdFiles = files.filter((p) => p.endsWith(".md"));
+  // Attachments are never documents: they carry no frontmatter, own no route,
+  // and are checked by their own rules instead.
+  const mdFiles = files.filter((p) => p.endsWith(".md") && !isAttachment(path.basename(p)));
 
   if (mdFiles.length === 0) {
     problem(
@@ -446,7 +477,12 @@ if (!existsSync(knowledgeDir)) {
       );
     }
     seenLower.set(lower, rel);
-    if (files.includes(p) && !p.endsWith(".md") && !ASSET_EXTENSIONS.has(path.extname(p))) {
+    if (
+      files.includes(p) &&
+      !p.endsWith(".md") &&
+      !isAttachment(base) &&
+      !ASSET_EXTENSIONS.has(path.extname(p))
+    ) {
       problem(
         rel,
         `unexpected file type "${path.extname(p) || base}"`,
@@ -486,6 +522,51 @@ if (!existsSync(knowledgeDir)) {
     }
   }
 
+  // Study attachments: bound to a parent, carrying no governance of their own.
+  for (const p of files) {
+    const base = path.basename(p);
+    const rel = path.relative(root, p);
+
+    const nearMiss = ATTACHMENT_NEAR_MISSES.find(
+      ([wrong]) => base.length > wrong.length && base.endsWith(wrong),
+    );
+    if (nearMiss && !isAttachment(base)) {
+      problem(
+        rel,
+        `${nearMiss[0]} is not an attachment extension`,
+        "the site reads decks as YAML and accepts only .yaml — a near miss is not picked up as a deck, and fails the build naming the path but not the rule",
+        `rename it to ${base.slice(0, -nearMiss[0].length)}${nearMiss[1]}`,
+      );
+      continue;
+    }
+
+    if (!isAttachment(base)) continue;
+
+    const parent = parentDocumentOf(base);
+    if (parent && !existsSync(path.join(path.dirname(p), parent))) {
+      problem(
+        rel,
+        `attachment of ${parent}, which is not in the record`,
+        "an attachment inherits its parent's governance — with no parent there is nothing to inherit, so it would be published under no tier and covered by no takedown",
+        `add ${path.join(path.dirname(rel), parent)}, or remove ${rel}`,
+      );
+    }
+
+    if (base.endsWith(".md") || base.endsWith(".mdx")) {
+      const text = readFileSync(p, "utf8")
+        .replace(/^\uFEFF/, "")
+        .replaceAll("\r\n", "\n");
+      if (text.startsWith("---\n")) {
+        problem(
+          rel,
+          "attachment declares frontmatter",
+          "an attachment is part of its parent and carries none of its own governance — a key here would look like it governs something and would govern nothing (a visibility: on a summary of a restricted document is the shape that matters)",
+          `remove the frontmatter block; ${parent ?? "its parent"} is what carries the governance`,
+        );
+      }
+    }
+  }
+
   // foo.md vs foo/index.md route collisions
   for (const p of mdFiles) {
     const sibling = p.replace(/\.md$/, "");

package/templates/scaffold/AGENTS.md

@@ -448,6 +448,12 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   publishes that as fact) and `superseded` (a legacy marker — prefer `status`)
   are available. No other keys; never
   `id:` or `name:` — the path is the identity.
+- **Each page says how long it takes to read**, just above the body, counted from the
+  document's own words when the site is built. Fenced code and frontmatter do
+  not count toward it, so a short page carrying a long example is not reported
+  as a long read. Nothing to author — it is derived. A document with a summary
+  shows the figure on both tabs, so a reader can see at a glance how much the
+  summary saves them.
 - **The governance keys are rendered, so they are worth filling in.** Each
   page shows its owner and effective date under the title, lists every
   `provenance` entry separately at the foot, and — for a superseded document —
@@ -500,6 +506,49 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   refused.
 - Images and assets live in `knowledge/` beside the document that uses them,
   referenced by relative links. A relative link must never leave `knowledge/`.
+- **Study attachments.** A document may carry two optional companions named
+  after it, in the same folder: `<doc>.summary.md` (a short précis) and
+  `<doc>.flashcards.yaml` (a recall deck). The summary appears as a second tab
+  beside the document's own words; the deck appears at the END of that
+  document's page. Both appear nowhere else in the site.
+
+  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
+  cite — so it carries **no frontmatter at all** (the checker refuses any), and
+  it takes its `visibility:` and any takedown from its parent. Restrict the
+  document and its summary and deck go with it; there is no way to publish a
+  summary more widely than the document it summarises. An attachment whose
+  document is missing is refused, by `pnpm check` and by `pnpm build` alike.
+
+  A deck is YAML, and the extension is exactly `.flashcards.yaml` — `.yml` is
+  refused by name:
+
+  ```yaml
+  deck:
+    title: Expense approvals
+    description: Recall checks for the approvals policy.
+  cards:
+    - front: Who approves a purchase above the threshold?
+      back: A second approver, independent of the requester.
+      why: Optional — a prompt shown before the answer.
+  ```
+
+  No `id:` anywhere, on the deck or a card: the path is the deck's identity,
+  and a card's identity is its own text. Edit a card and only that card's
+  review progress starts again; the rest is untouched.
+
+  **A card may only say what its document says.** The summary and the deck are
+  ways of rehearsing the record, never a second source — a card asserting
+  something its document does not is a claim nothing governs and no agent can
+  cite. Ask your coding agent to write them from a document and to check every
+  answer back against it.
+
+  Review scheduling uses a simple interval ladder (an SM-2 variant): a missed
+  card returns in about a minute, a recalled card's interval grows by roughly
+  2.5x each time. It is not FSRS and makes no retention guarantee. Progress is
+  kept in the reader's own browser, so it is per-person and per-device, and it
+  is not part of the record.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 

package/templates/scaffold/Dockerfile

@@ -22,12 +22,16 @@ WORKDIR /app
 COPY package.json ./
 RUN npm install --omit=dev --no-audit --no-fund
 
-# The record's identity, configuration, and its MCP registration
-# (system/gateways/). What is deliberately ABSENT is decided in .dockerignore —
-# the corpus, the website and every secret — rather than by listing files here:
-# naming them one at a time is how the door came to ship without the very file
-# that shapes its tool surface (found live).
-COPY . ./
+# The record's identity and configuration, and this door's own MCP registration.
+#
+# NAMED, not `COPY . ./`. A .dockerignore is not honoured by every builder —
+# Vercel's is not, and `COPY . ./` there swept in node_modules and the built
+# site, producing a registry push rejected as PAYLOAD_TOO_LARGE (found live).
+# Naming what enters the image is the only form that is portable across build
+# hosts. The risk of naming things is forgetting one; that is covered by a test
+# which boots the built image and asserts it serves the tools this file names.
+COPY instance.md ./
+COPY system/gateways/ ./system/gateways/
 
 # Most container hosts inject PORT; 80 is a sane default when nothing does.
 ENV PORT=80

package/templates/scaffold/README.md

@@ -5,8 +5,9 @@ project's people and AI agents operate from.
 
 Two worlds live here:
 
-- **`knowledge/` — the record.** Plain governed markdown. Yours forever,
-  readable anywhere, portable without this repository's code.
+- **`knowledge/` — the record.** Plain governed markdown (plus the optional
+  study attachments a document may carry). Yours forever, readable anywhere,
+  portable without this repository's code.
 - **`system/` — the system.** The site (and later, services) that serve the
   record. Replaceable machinery.
 

package/templates/scaffold/dockerignore

@@ -1,5 +1,10 @@
 # DENY EVERYTHING, then allow exactly what the door needs.
 #
+# Defence in depth, NOT the bound. The Dockerfile names the files it copies,
+# because a .dockerignore is not honoured by every build host — Vercel's is
+# not. This file protects local `docker build` and every builder that does
+# respect it; the Dockerfile protects the rest.
+#
 # The inverse — listing what to exclude — cannot bound the image, because it can
 # only exclude what someone thought of. A build output, a cache, a backup
 # directory or a vendored dependency in the project root all end up inside, and

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

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

package/templates/scaffold/knowledge/what-is-a-ksor.summary.md

@@ -0,0 +1,15 @@
+A Knowledge System of Record settles **which copy governs**. When a wiki page, a
+slide or a model's memory disagrees with it, this record wins.
+
+- A traditional system of record settles the _state_ of a business — the ledger
+  for transactions, the HRIS for employee records. A KSoR settles what the
+  organization _knows_ and how it should operate.
+- The problem it solves is scatter: knowledge spread across wikis, decks, PDFs,
+  prompts and memory, with no authoritative answer to the question an agent has
+  to ask — which knowledge should I trust?
+- An assistant cannot answer that question, because it answers from everything
+  it has ever read and cannot tell you which of its sentences were checked.
+- Every answer here traces to a document that names who stands behind it and
+  when it took effect.
+- It does **not** settle whether that document is right. Provenance proves who
+  said what and when; whether the source is any good is a separate matter.

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

@@ -15,6 +15,11 @@ import {
 import { predecessorsOf, readGovernance, resolveSuccessorUrl } from "@/lib/governance";
 import { showGovernance } from "@/lib/shared";
 import { RecordToc, TocItems } from "@/components/record-toc";
+import { RecordViews } from "@/components/record-views";
+import { Flashcards } from "@/components/flashcards";
+import { StudyAids } from "@/components/study-aids";
+import { deckFor, summaryFor } from "@/lib/attachments";
+import { readingMinutes } from "@/lib/reading-time";
 
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const params = await props.params;
@@ -22,6 +27,18 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   if (!page) notFound();
 
   const MDX = page.data.body;
+  // Attachments of THIS document, found by suffix on its own path. Null is the
+  // ordinary case, not an error.
+  const summary = summaryFor(page.path);
+  const Summary = summary?.body ?? null;
+  const deck = deckFor(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
+  // out of reach of all three.
+  const minutes = readingMinutes(await page.data.getText("processed"));
+  const summaryMinutes =
+    summary === null ? null : readingMinutes(await summary.getText("processed"));
   // What the record says about this document. The page renders it; it never
   // supplies it — an undeclared key shows nothing (specs/ksor/site-governance).
   const governance = readGovernance(page.data, page.path);
@@ -112,14 +129,35 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
           describes (measured, 2026-08-21). Short documents now end where their
           text ends. */}
         <DocsBody style={{ flexGrow: 0 }}>
-          <MDX
-            components={getMDXComponents({
-              // relative links between documents in knowledge/ resolve to
-              // their rendered pages
-              a: createRelativeLink(source, page),
-            })}
-          />
+          {/* The summary panel is built HERE, on the server, and handed to the
+            client tab strip as a prop — so it is in the shipped HTML whether or
+            not the bundle runs, which is what an agent parsing the page and a
+            reader with a failed bundle both depend on. Presence-driven: with no
+            summary, RecordViews renders the body alone and no tab strip exists
+            (specs/ksor/study-attachments C3, C20). */}
+          <RecordViews
+            documentMinutes={minutes}
+            summaryMinutes={summaryMinutes ?? undefined}
+            summary={
+              Summary === null ? null : (
+                <Summary components={getMDXComponents({ a: createRelativeLink(source, page) })} />
+              )
+            }
+          >
+            <MDX
+              components={getMDXComponents({
+                // relative links between documents in knowledge/ resolve to
+                // their rendered pages
+                a: createRelativeLink(source, page),
+              })}
+            />
+          </RecordViews>
         </DocsBody>
+        {/* What a reader DOES with this document once they have read it. One
+          region, so the quiz that will sit beside the deck is a child here and
+          not a new argument about where it goes. Renders nothing at all when
+          the document has no study aids. */}
+        <StudyAids>{deck === null ? null : <Flashcards deck={deck} />}</StudyAids>
         {/* A folder's index page lists what the folder holds. Without it the
           page ended at its own sentence and the documents below it were
           reachable only from the sidebar (research/site-design.md F5). Empty