@panaversity/ksor 0.0.20 → 0.0.21

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

@@ -115,6 +115,7 @@ function parseFrontmatter(text) {
   const malformedQuote = new Map();
   const malformed = [];
   const duplicates = [];
+  const truncated = [];
   const tightColons = [];
   const tabIndents = [];
   let current = null;
@@ -157,6 +158,12 @@ function parseFrontmatter(text) {
     }
     const nested = /^[ \t]+([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
     if (nested && current !== null) {
+      // Same hazard as the top-level duplicate above, one level down: this Map
+      // keeps the LAST write while the surfaces read the FIRST occurrence, so
+      // the check validates one value and the build publishes the other
+      // (found 2026-08-20: `governance: nope` then `governance: false` passed
+      // the check and crashed the build).
+      if (children.get(current).has(nested[1])) duplicates.push(`${current}.${nested[1]}`);
       children.get(current).set(nested[1], unquote(nested[2]));
       continue;
     }
@@ -168,7 +175,16 @@ function parseFrontmatter(text) {
       // entry, and reading it as one refuses the documents instead of the
       // list (found live 2026-08-18: `- public # the default` made every
       // public document's visibility undeclared).
-      const value = /^["']/.test(item[1]) ? item[1] : item[1].replace(/\s+#.*$/, "");
+      const quotedItem = /^["']/.test(item[1]);
+      const value = quotedItem ? item[1] : item[1].replace(/\s+#.*$/, "");
+      // A `#` is a comment to YAML and an invoice or issue number to a person.
+      // In `provenance` — free text naming a real source — the truncation is
+      // silent data loss: `- Invoice #4471 from Acme Ltd` publishes as
+      // "Invoice" (found 2026-08-20). NOT flagged for `audiences`, where a
+      // trailing comment is an intended and documented use.
+      if (!quotedItem && current === "provenance" && value !== item[1]) {
+        truncated.push({ key: current, raw: item[1].trim(), kept: value.trim() });
+      }
       lists.get(current).push(unquote(value));
       continue;
     }
@@ -180,7 +196,19 @@ function parseFrontmatter(text) {
       malformed.push(line.trim());
       continue;
     }
-    if (/^[ \t]*-([ \t]|$)/.test(line) || /^[ \t]+\S/.test(line)) continue;
+    if (/^[ \t]*-([ \t]|$)/.test(line)) continue;
+    // A whole-line comment is YAML, not a wrapped value — an author annotating
+    // their own frontmatter ("# add the signed PDF once it lands") is doing
+    // nothing wrong, and refusing it turned the adopter's shipped CI red on a
+    // record both surfaces read perfectly (found 2026-08-21).
+    if (/^[ \t]*#/.test(line)) continue;
+    // An indented line that is neither a nested key nor a list item is a value
+    // WRAPPED onto a second line. YAML folds it back into the value above;
+    // this parser used to skip it, so every rule here inspected a string that
+    // was not what the surfaces publish — `effective: 2026-04-01` continued by
+    // `  00:00:00 +05:00` passed the date rule and shipped the day before
+    // (found 2026-08-20). A value the checker cannot see is a value it cannot
+    // govern.
     malformed.push(line.trim());
   }
   return {
@@ -190,6 +218,7 @@ function parseFrontmatter(text) {
     quoted,
     malformedQuote,
     duplicates,
+    truncated,
     malformed,
     tightColons,
     tabIndents,
@@ -472,9 +501,16 @@ if (!existsSync(knowledgeDir)) {
 
   // frontmatter + links per document
   const visibilityByPath = new Map();
+  const documentPaths = new Set();
   const crossings = [];
   for (const p of mdFiles) {
     const rel = path.relative(root, p);
+    // Every markdown file under knowledge/ IS a document of the record, whether
+    // or not its own frontmatter parses. Counting it only after a clean parse
+    // made a correct `superseded_by` be reported as a capitalisation mistake
+    // whenever its successor was the document still being written (round 3) —
+    // two problems for one cause, and the second one false.
+    documentPaths.add(p);
     const text = readFileSync(p, "utf8");
     const fm = parseFrontmatter(text);
     if (fm === null) {
@@ -490,7 +526,7 @@ if (!existsSync(knowledgeDir)) {
       problem(
         rel,
         `unclosed or malformed frontmatter — this is not a frontmatter line: "${fm.malformed[0]}"`,
-        "an unclosed block swallows the body: the checker reads prose as governance, and the site renders a document with no title",
+        "an unclosed block swallows the body, and a value wrapped onto a second line is folded back by YAML but invisible here — either way this check inspects something the site does not publish",
         "close the block with --- on its own line; every line inside it is `key: value` or a `- list item` — no prose, no comments",
       );
     } else {
@@ -618,9 +654,28 @@ if (!existsSync(knowledgeDir)) {
           "add superseded_by: ./<successor>.md",
         );
       }
-      // A successor that names a path must be a document that exists: the
-      // pointer is the whole value of marking something superseded.
-      if (successor && (/^\.{1,2}\//.test(successor) || successor.toLowerCase().endsWith(".md"))) {
+      if (successor && status !== "superseded") {
+        problem(
+          rel,
+          `superseded_by on a document that is status: ${status || "(none)"}`,
+          "the two keys are one statement — a successor pointer says this document was replaced, so a record that keeps the pointer while calling the document current contradicts itself, and the site publishes a Superseded notice over a live document",
+          "set status: superseded, or remove superseded_by if this document is still current",
+        );
+      }
+      // superseded_by must be a document pointer, and EVERY successor is
+      // validated. This was gated behind a shape test until 2026-08-20, so a
+      // value matching neither shape (`hr/refunds-2026`) skipped existence,
+      // escape-the-record AND the cross-audience rule — and then the site
+      // published the raw pointer, naming a document a lower tier must not know
+      // exists.
+      if (successor && !successor.split("#")[0].toLowerCase().endsWith(".md")) {
+        problem(
+          rel,
+          `superseded_by is not a document pointer: ${successor}`,
+          "unless it names a markdown document this check cannot tell whether the successor exists, stays inside the record, or is readable by this document's audience — and the site publishes the raw text of it",
+          "write it as a relative path to the successor, e.g. superseded_by: ./<successor>.md",
+        );
+      } else if (successor) {
         const resolved = path.resolve(path.dirname(p), successor.split("#")[0]);
         if (!resolved.startsWith(knowledgeDir + path.sep)) {
           problem(
@@ -629,7 +684,7 @@ if (!existsSync(knowledgeDir)) {
             "the successor is what readers are sent to instead — outside knowledge/ it is not a governed document",
             "point superseded_by at a document inside knowledge/",
           );
-        } else if (!existsSync(resolved)) {
+        } else if (!existsSync(resolved) || !lstatSync(resolved).isFile()) {
           problem(
             rel,
             `superseded_by points at a document that does not exist: ${successor}`,
@@ -640,6 +695,76 @@ if (!existsSync(knowledgeDir)) {
           crossings.push({ kind: "superseded_by", rel, from: p, to: resolved, target: successor });
         }
       }
+      for (const cut of fm.truncated) {
+        problem(
+          rel,
+          `a ${cut.key} entry is cut short at a #: ${cut.raw}`,
+          `YAML ends an unquoted value at " #", so the record stores only "${cut.kept}" and that is what the page publishes as the source — the rest is lost without a word`,
+          `quote it to keep the whole thing: - "${cut.raw.replace(/"/g, "'")}"`,
+        );
+      }
+      // Every governed key except `provenance` is ONE value. Written as a
+      // block sequence or a nested map it parses to an array or an object, and
+      // the page — which asks for text — renders nothing at all: the record
+      // declares the fact and the surface silently omits it (found 2026-08-21
+      // with `effective:` followed by `  - 2026-04-01`). `visibility` has its
+      // own list rule with a better message, so it is left to it.
+      for (const scalarKey of [
+        "title",
+        "description",
+        "status",
+        "owner",
+        "effective",
+        "superseded",
+        "superseded_by",
+        "order",
+      ]) {
+        const asList = (fm.lists.get(scalarKey) ?? []).length > 0;
+        const asMap = (fm.children.get(scalarKey)?.size ?? 0) > 0;
+        if (asList || asMap) {
+          problem(
+            rel,
+            `${scalarKey} is written as ${asList ? "a list" : "a nested block"}, not a value`,
+            "the surfaces read this key as one piece of text; as a list or a map it reaches them as neither, so the page publishes nothing where the record declares something",
+            `put the value on the key's own line: ${scalarKey}: <value>`,
+          );
+        }
+      }
+      // `effective` is the DAY a document takes effect. Written unquoted with a
+      // time, YAML makes it a timestamp, and normalizing that to a UTC day
+      // prints the day before the record's for any positive offset (found
+      // 2026-08-20: `2026-04-01 00:00:00 +05:00` rendered 2026-03-31).
+      // `effective` is the DAY a document takes effect, and the page publishes
+      // it as fact inside <time datetime>. Unquoted it must be a calendar-valid
+      // YYYY-MM-DD and nothing else, because every other shape YAML accepts
+      // here publishes something the record does not say: `2026-06-31` rolls
+      // silently to July 1st (js-yaml's date path is `Date.UTC(y, m, d)` with
+      // no validation), a value carrying a time reads back in a timezone and
+      // can land a day early, and a bare `2026` types as a number that never
+      // reaches the page at all. Three rounds of narrower rules each leaked a
+      // different one of those, so the rule is now the whole contract: a plain
+      // date, or QUOTED text that is published verbatim and never parsed.
+      const effective = fm.keys.get("effective");
+      if (effective !== undefined && effective !== "" && !fm.quoted.has("effective")) {
+        const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(effective);
+        let calendarValid = false;
+        if (iso !== null) {
+          const [year, month, day] = [Number(iso[1]), Number(iso[2]), Number(iso[3])];
+          const probe = new Date(Date.UTC(year, month - 1, day));
+          calendarValid =
+            probe.getUTCFullYear() === year &&
+            probe.getUTCMonth() === month - 1 &&
+            probe.getUTCDate() === day;
+        }
+        if (!calendarValid) {
+          problem(
+            rel,
+            `effective is not a calendar date: ${effective}`,
+            "the page publishes this as the day the document takes effect, in a <time> element a machine reads as fact — YAML rolls an impossible date to the next month without a word, reads a value carrying a time in a timezone, and types a bare year as a number that never reaches the page",
+            `write a real date (effective: 2026-04-01), or quote it to publish it as text (effective: "${effective.replace(/"/g, "'")}")`,
+          );
+        }
+      }
       // visibility: one audience per document, from the set instance.md declares.
       // Through scalarValue, so the comparison sees what the READERS see: a raw
       // read reported `visibility "internal # narrowed 2026-08" is not a
@@ -684,6 +809,58 @@ if (!existsSync(knowledgeDir)) {
     }
   }
 
+  for (const { kind, rel, to, target } of crossings) {
+    if (kind !== "superseded_by" || documentPaths.has(to)) continue;
+    problem(
+      rel,
+      `superseded_by does not name a document in the record: ${target}`,
+      "it resolves to a file the record does not govern — on a case-insensitive filesystem a mis-typed capitalisation resolves happily here and then misses every rule keyed by the real path, the cross-audience check included",
+      "match the successor's path exactly as it appears under knowledge/ (ascii lowercase)",
+    );
+  }
+
+  // A supersession must lead somewhere. A document that supersedes ITSELF, or a
+  // pair that supersede each other, published a notice telling the reader this
+  // page is replaced — by a link back to a page saying the same thing. The
+  // reader is sent in a circle and never reaches a current document (found
+  // 2026-08-20).
+  {
+    const successorOf = new Map();
+    for (const { kind, from, to } of crossings) {
+      if (kind === "superseded_by" && !successorOf.has(from)) successorOf.set(from, to);
+    }
+    const walked = new Set();
+    for (const start of successorOf.keys()) {
+      if (walked.has(start)) continue;
+      // An ORDERED path, not a set: the documents visited before the loop
+      // closes are not part of the cycle, and reporting them made the check
+      // blame a document whose pointer was correct while printing an edge the
+      // record does not contain (found 2026-08-20 — a → b → c → b was reported
+      // as "a → b → c → a").
+      const trail = [start];
+      const onTrail = new Set([start]);
+      let cursor = successorOf.get(start);
+      while (cursor !== undefined && !onTrail.has(cursor)) {
+        onTrail.add(cursor);
+        trail.push(cursor);
+        cursor = successorOf.get(cursor);
+      }
+      for (const node of trail) walked.add(node);
+      if (cursor === undefined) continue; // the chain ends at a current document
+      // The cycle is the trail from the document the walk returned to.
+      const cycle = trail.slice(trail.indexOf(cursor));
+      const names = cycle.map((file) => path.relative(root, file));
+      problem(
+        names[0],
+        cycle.length === 1
+          ? "superseded_by points at this document itself"
+          : `supersession cycle: ${names.join(" → ")} → ${names[0]}`,
+        "a supersession sends the reader to the successor that replaced this one — a pointer that comes back here sends them in a circle and never reaches a current document",
+        "point superseded_by at the document that actually replaces this one, or set status back if nothing does",
+      );
+    }
+  }
+
   // Pointers across audiences: the leak no single build can catch, because the
   // build that publishes the pointer has already dropped its target and cannot
   // know it ever existed. Only the whole record sees both ends.
@@ -750,7 +927,7 @@ const INSTANCE_KEYS = new Set([
   "budgets",
 ]);
 const INSTANCE_KSOR_KEYS = new Set(["requires", "scaffolded"]);
-const INSTANCE_SITE_KEYS = new Set(["url"]);
+const INSTANCE_SITE_KEYS = new Set(["url", "governance"]);
 // Nested field names mirror the kernel's instance schema; the kernel validates
 // their values (this checker stays dependency-free and cannot import it).
 const INSTANCE_DATABASE_KEYS = new Set(["dsn_env", "tenant_id"]);
@@ -778,7 +955,7 @@ if (!existsSync(instanceMd)) {
     problem(
       "instance.md",
       `unclosed or malformed frontmatter — this is not a frontmatter line: "${fm.malformed[0]}"`,
-      "an unclosed block swallows the identity prose and turns it into unreadable configuration",
+      "an unclosed block swallows the identity prose and turns it into unreadable configuration; a value wrapped onto a second line is folded back by YAML but invisible here, so this check governs a string the surfaces never see",
       "close the block with --- on its own line; every line inside it is `key: value` — the identity prose belongs below it",
     );
   } else {
@@ -920,6 +1097,31 @@ if (!existsSync(instanceMd)) {
         "add audiences: (ordered least- to most-restricted, public first), or remove default_visibility:",
       );
     }
+    // A group written as a flow mapping (`site: { governance: false }`) lands
+    // as a scalar with NO children, so every nested rule below — the closed key
+    // set included — silently skips it: the owner's setting is dropped without
+    // a word (found 2026-08-20). The groups are block mappings, always.
+    for (const parent of ["ksor", "site", "database", "embedding", "retrieval", "budgets"]) {
+      // A trailing ` #` comment is part of this checker's own grammar — it is
+      // stripped for values and for list items, and `audiences: # who may read`
+      // passes on the same file. Reading the raw value called `site: # notes` an
+      // inline mapping and refused a well-formed record, with a why that was
+      // factually false: the surfaces read that file perfectly (found
+      // 2026-08-20).
+      const rawGroup = fm.keys.get(parent);
+      const inline =
+        rawGroup === undefined || rawGroup.trim().startsWith("#")
+          ? ""
+          : rawGroup.replace(/\s+#.*$/, "").trim();
+      if (inline !== "") {
+        problem(
+          "instance.md",
+          `${parent}: has an inline value: ${inline}`,
+          "a group written on one line is not read as a group — every key inside it is skipped by this check AND by the surfaces, so the settings the owner wrote are silently dropped",
+          `write it as an indented block:\n      ${parent}:\n        <key>: <value>`,
+        );
+      }
+    }
     for (const [parent, allowed] of [
       ["ksor", INSTANCE_KSOR_KEYS],
       ["site", INSTANCE_SITE_KEYS],
@@ -929,6 +1131,27 @@ if (!existsSync(instanceMd)) {
       ["budgets", INSTANCE_BUDGETS_KEYS],
     ]) {
       for (const key of fm.children.get(parent)?.keys() ?? []) {
+        // site.governance is a switch, so its VALUE is checked here: a typo
+        // that silently defaulted would publish the governance the owner asked
+        // to hide, or hide what they asked to publish.
+        if (parent === "site" && key === "governance") {
+          const raw = (fm.children.get("site")?.get("governance") ?? "").trim();
+          const value = (/^["']/.test(raw) ? raw : raw.replace(/\s+#.*$/, ""))
+            .trim()
+            .replace(/^(['"])(.*)\1$/, "$2")
+            // Case-folded: js-yaml reads `False` as false, and the site's own
+            // reader lowercases before comparing. A checker stricter than both
+            // surfaces is the very divergence this rule exists to stop.
+            .toLowerCase();
+          if (value !== "true" && value !== "false") {
+            problem(
+              "instance.md",
+              `site.governance is "${value}" — it must be true or false`,
+              "it decides whether pages show the owner, effective date and sources each document declares; a value nobody can read is a setting the owner believes is in effect",
+              'write "governance: false" to keep pages plain, or remove the key (the default shows them)',
+            );
+          }
+        }
         if (!allowed.has(key)) {
           problem(
             "instance.md",

package/templates/scaffold/AGENTS.md

@@ -15,6 +15,12 @@ The record survives the system: `knowledge/` must stay readable and complete
 even if `system/` is deleted. Dependency flows one way — the system reads the
 record; the record never references the system.
 
+Every grouped key in `instance.md` (`ksor`, `site`, `database`, `embedding`,
+`retrieval`, `budgets`) is written as an indented block, never inline on one
+line: a group written as `site: { governance: false }` is not read as a group
+at all, so every setting inside it is silently dropped. `pnpm check` refuses
+that shape, and refuses a key repeated inside a group.
+
 `instance.md` carries a closed key set — `format`, `name`, `ksor`, `site`,
 the optional pair `audiences` + `default_visibility` (the record's reader
 audiences, ordered least- to most-restricted with `public` first, and the one
@@ -364,9 +370,37 @@ Details in README → Deploying.
   are required. `owner` and `provenance` (a list naming real sources) are
   strongly encouraged — they become required as this project climbs the
   governance ladder. `description`, `visibility` (below), `order` (sidebar
-  position), `effective` (the date the document takes effect) and `superseded`
-  (a legacy marker — prefer `status`) are available. No other keys; never
+  position), `effective` (the date the document takes effect — a real
+  `YYYY-MM-DD` date and nothing else, or **quote it** to publish it as text:
+  `effective: "Q1 2026"`. Unquoted, YAML turns `2026-06-31` into July 1st and
+  `2026-04-01 09:00 +05:00` into the day before, without a word, and the page
+  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.
+- **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 —
+  carries a notice above the title naming its successor and linking to it. A
+  key you leave off renders nothing at all: the site never invents a value, so
+  a missing owner reads as missing rather than as unowned.
+- **The agent surface carries them too.** `llms.txt` marks a document whose
+  status is a caveat and names the route that replaced a superseded one;
+  `llms-full.txt` puts the keys back as frontmatter above each document. An
+  agent reading the record therefore sees what a reader sees — a withdrawn
+  document is never handed over as plain prose.
+- **Don't want any of it on the published pages?** Set `governance: false`
+  under `site:` in `instance.md`. The record keeps every key — the agent
+  surface and your audit trail still read them, and `llms.txt`/`llms-full.txt`
+  keep publishing them — and the pages simply stay plain. One consequence worth
+  knowing: the home page shows the agent surface VERBATIM in its panel, so the
+  keys stay visible there even with this off. That panel's whole claim is that
+  it is the bytes an agent is served, and editing them to match a page setting
+  would make it lie. Remove the panel if you need the front page silent too. The supersession notice is the one thing it does not hide: a reader
+  handed a replaced document with no word of its successor has been misled.
+- **`status` is shown only when it is a caveat.** `draft`, `review` and
+  `superseded` appear as a small label; `approved` shows nothing, because a
+  reader already assumes a document in the record is current — so the label
+  stays rare enough to be noticed on the pages where it matters.
 - `visibility:` names the one audience a document belongs to — a single value
   from `instance.md`'s `audiences:`, never a list, and orthogonal to `status:`
   (an approved document can be restricted, and a draft is not hidden). Leave
@@ -385,7 +419,14 @@ Details in README → Deploying.
   document and can clone, the answer is a second repository.**
 
 - A replaced document is marked `status: superseded` with `superseded_by:`
-  pointing at its successor — superseded documents are never deleted.
+  pointing at its successor — superseded documents are never deleted. The two
+  keys are one statement, so `pnpm check` refuses each without the other: a
+  successor pointer left on a document you have set back to `approved` would
+  publish a "Superseded" banner over a live document. The pointer must name a
+  markdown document (`./<successor>.md`), exactly as it is capitalised under
+  `knowledge/`, and it must lead somewhere: a document that supersedes itself,
+  or a pair that supersede each other, sends the reader in a circle and is
+  refused.
 - Images and assets live in `knowledge/` beside the document that uses them,
   referenced by relative links. A relative link must never leave `knowledge/`.
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
@@ -420,9 +461,16 @@ You own `system/site/` outright — these are the seams, cheapest first:
 - **Display title** — `instance.md`'s body `# H1` (the intake interview
   writes it). Headline, navbar, and browser title follow on restart.
 - **Accent color** — the one brand pair in `system/site/app/global.css`
-  (`--color-fd-primary`, light and dark); every accented element follows.
+  (`--primary` and `--primary-foreground`, light and dark); every accented
+  element follows, in the shell and in every shadcn component alike.
 - **Logo and favicon** — replace `system/site/app/icon.png`; the tab icon
   and the home-page mark are the same file.
+- **Components** — the site is a shadcn/ui project (`system/site/components.json`),
+  so `pnpm dlx shadcn@latest add <name>` writes a component into
+  `system/site/components/ui/` that you then own like everything else here.
+  Fumadocs reads the same tokens (its `shadcn` preset maps every `--color-fd-*`
+  onto the shadcn variable of the same role), so a registry component and the
+  documentation shell around it stay one palette.
 - **Anything deeper** — edit the site like the Next.js app it is; the only
   rule that survives customization is critical rule 1. The whole shell is
   replaceable behind a five-clause contract (a themed Docusaurus shell with

package/templates/scaffold/instance.md

@@ -23,29 +23,37 @@ ksor:
 # version: 0.1.0
 ---
 
-# Knowledge System of Record
+# KSoR
 
-The heading above is this record's **display title** — the human name every
-page leads with. The intake interview replaces it with the real one
-("Acme Operations Handbook"); the machine identity stays `KSOR-STAMP-NAME`
-in the frontmatter, and that is what agents and citations use.
+This record is authoritative for what a Knowledge System of Record is, how a
+project climbs the governance ladder, and which surfaces the same governed
+knowledge is published through. It does not cover the CLI's release history or
+the internals of the retrieval kernel.
 
-This Knowledge System of Record is authoritative for — _fill this in; it is
-the single most important sentence in the project._
+Write and govern the knowledge once; every surface here derives from it. When a
+slide deck, a wiki page or a model's memory disagrees with this record, this
+record wins.
 
-Everything below this frontmatter is the identity of this instance: what the
-corpus covers, who it serves, and how strictly it should decline questions it
-does not cover. This prose IS the agent surface's system prompt — `ksor serve`
-wires it into the MCP server's instructions — so write it for a reader who must
-act on it.
+## This is a starter, and it is yours to replace
+
+Everything above describes KSoR itself. It ships filled in so that a fresh
+project has a real governed corpus on the first `pnpm dev` — statuses, owners,
+provenance, a folder and a draft — instead of an empty shelf and a placeholder.
+The documents live in `knowledge/`; delete them as your own knowledge arrives.
+
+Be deliberate about replacing it, because a starter that describes the wrong
+thing describes it _everywhere_. Two lines here are read by every surface:
+
+- **The heading** is the display title — the human name every page leads with.
+  The machine identity stays `KSOR-STAMP-NAME` in the frontmatter, and that is
+  what citations and `llms.txt` use.
+- **The first paragraph** is this record's scope. The site publishes it, and
+  `ksor serve` hands it to a connecting agent as the MCP server's instructions.
+  A record published with this paragraph unchanged will tell an agent — quite
+  accurately, and quite uselessly for you — that it is authoritative for what a
+  Knowledge System of Record is.
 
 Ask your coding agent to run the **intake interview** (it knows how — see
 `.agents/skills/intake-interview/`), answer its questions, and let it write
-this document with you.
-
-Until you do, `ksor serve` says so — at boot, and to every agent that connects:
-the MCP surface replaces this template with a plain statement that the record's
-scope is unstated, rather than passing authoring guidance to a runtime agent as
-if it were instructions. Nothing breaks, and the record still answers with
-citations; it just cannot tell an agent what it is authoritative FOR, which is
-the one thing that makes an answer worth trusting.
+this document with you. Replace those two lines and every surface follows,
+because every surface reads them from here.

package/templates/scaffold/knowledge/governance-ladder.md

@@ -0,0 +1,36 @@
+---
+title: The governance ladder
+description: Level 0 works immediately; a project climbs only as far as its domain needs.
+status: draft
+owner: Product
+order: 3
+---
+
+Governance here is a ladder, not a gate. Demanding the top rung of a project on
+the bottom one is a bug, not rigour.
+
+## Where every record starts
+
+A document needs a title and a status. That is the whole requirement, and a
+record of such documents is already publishable, searchable and citable.
+
+## The rungs above it
+
+Each rung is worth climbing when the domain asks for it, and not before.
+
+### Owners and sources
+
+An owner names who stands behind a document. Provenance names where its claims
+came from, one entry per source.
+
+### Effective dates and supersession
+
+An effective date says when a document began to apply. A replaced document is
+marked and points at its successor rather than being deleted, so the history
+stays readable.
+
+### A measured floor for abstention
+
+The served rung answers questions from the record and declines the ones it does
+not cover. The threshold for declining is measured against this corpus, never
+copied from another one, and it is recorded beside the number with its date.

package/templates/scaffold/knowledge/surfaces/for-agents.md

@@ -0,0 +1,29 @@
+---
+title: The agent surface
+description: MCP for retrieval with citations, and machine-readable files beside it.
+status: approved
+owner: Product
+order: 2
+effective: 2026-08-22
+provenance:
+  - KSoR README, "an agent interface through MCP for search, retrieval, citation, reasoning, and action"
+---
+
+Agents reach the record through MCP — an open standard, so one corpus answers in
+any assistant or framework its owner points at it.
+
+## Retrieval that cites
+
+Search and retrieval answer with citations back into the record, so a claim can
+be checked against the document that carries it rather than taken on trust.
+
+### Abstention is a feature
+
+"Not in this record" is a correct answer. It is never an error, and never a
+licence to fall back on what a model happens to remember.
+
+## Files beside the interface
+
+The build publishes the same knowledge as plain files an agent can fetch without
+a server: `llms.txt` indexes the record, `llms-full.txt` carries every document
+in one file, and each document has a markdown twin at its own address.

package/templates/scaffold/knowledge/surfaces/for-people.md

@@ -0,0 +1,35 @@
+---
+title: The human surface
+description: Pages for reading, reviewing and sharing the record.
+status: approved
+owner: Product
+order: 1
+effective: 2026-08-22
+provenance:
+  - KSoR README, "a human experience for reading, learning, reviewing, and sharing"
+---
+
+A static site renders every governed document at a route derived from its path,
+with the governance it declares.
+
+## What a page carries
+
+Under each title the page shows the facts the document declares about itself —
+who owns it, when it took effect — and lists every source it came from at the
+foot, one entry per source, so a citation can point at exactly one of them.
+
+### A status appears only when it is a caveat
+
+A draft or a withdrawn document says so. An approved one shows nothing, because
+a reader already assumes a document in the record is current, and a label that
+never varies stops being read.
+
+#### A withdrawn document names its successor
+
+Supersession runs both ways: the retired document points at what replaced it,
+and the current one names what it replaced. Nothing is deleted.
+
+## The record without the site
+
+Nothing here is authored in the site. Delete the site and the record is intact —
+it is CommonMark in a folder, readable in any editor.

package/templates/scaffold/knowledge/surfaces/index.md

@@ -0,0 +1,21 @@
+---
+title: Surfaces
+description: One source, published through several synchronized projections.
+status: approved
+owner: Product
+order: 2
+---
+
+The record is written once and published through surfaces that cannot disagree,
+because each derives from the same source rather than from a copy of it.
+
+## Why they cannot drift
+
+A surface is generated from the record at build time. Adding one never means
+editing the knowledge, and a document changed in one place changes everywhere
+the next time the record is published.
+
+## The two audiences
+
+A person reads pages. An agent reads bytes. Both are served from the same
+governed markdown, which is what makes them answer alike.

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

@@ -0,0 +1,39 @@
+---
+title: What a Knowledge System of Record is
+description: The authoritative, governed knowledge layer humans, agents and software operate from.
+status: approved
+owner: Product
+order: 1
+effective: 2026-08-22
+provenance:
+  - KSoR README, "What Is a Knowledge System of Record?"
+---
+
+A traditional system of record establishes what is true about the current state
+of a business: the ledger is authoritative for transactions, the HRIS for
+employee records. When a spreadsheet disagrees with the ledger, the ledger wins.
+
+A Knowledge System of Record establishes something else — what the organization
+knows and how it should operate. Which policies apply, which thresholds are
+approved, what a term means here, and what to do when the answer is not known.
+
+## The problem it solves
+
+That knowledge is usually scattered across wikis, decks, PDFs, prompts and
+someone's memory, with no authoritative answer to the question an agent has to
+ask: which knowledge should I trust?
+
+### Why an assistant cannot answer that question
+
+An assistant answers from everything it has ever read, which is exactly why it
+cannot tell you which of its sentences were checked. Businesses have had a
+system of record for decades. AI never did.
+
+## What this record settles, and what it does not
+
+It settles which copy governs. Every answer traces to a document here, and that
+document 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 — the judgement of whether a source is any good is a separate
+matter, and this record never claims otherwise.