@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/README.md

@@ -26,6 +26,46 @@ The first `pnpm install` also fetches the
 `ksor` tool (pinned in `package.json`) and writes it into your lockfile —
 commit the updated lockfile.
 
+**The five starter documents publish on the first build.** They ship
+`status: stable`, so `pnpm dev` and `pnpm build` both give you a working
+record straight away — pages, a sidebar, a `/llms.txt` an agent can read —
+instead of an empty shelf. They are approved by `ksor-starter/KSOR-STAMP-VERSION`:
+the tool that wrote them, named as a producer rather than as a person, because
+no person reviewed a word of it. That is what the trust tier _unverified_ on
+every one of those pages says, and it is true.
+
+**So your first act here is replacing them.** They describe KSoR, not your
+organisation, and a record that describes the wrong thing describes it on every
+surface. Delete each one as your own knowledge arrives — and when the last is
+gone, delete `ksor-starter/KSOR-STAMP-VERSION` from `approval_authorities` in
+`.ksor/governance.yaml` too. Nothing of yours should be approved by a tool. Ask
+your coding agent to run the intake interview: it replaces the `human:you`
+placeholder in that file with your real handle and writes `instance.md` with
+you.
+
+**What you write starts unpublished.** A new document is `status: draft`, and
+`pnpm build` admits a draft to no surface at all: no page, no sidebar row, no
+`/llms.txt` entry, nothing for an agent to read. `pnpm dev` shows it, marked —
+the preview is where drafts live.
+
+Publishing one adds two keys beside `status: stable` — what produced the text,
+and who approved it. Both, or `pnpm check` refuses the document:
+
+```yaml
+status: stable
+generated: { by: "human:you", at: 2026-01-31T09:00:00Z }
+ksor:
+  audience: [public] # already there — every document carries it, drafts too
+  approval: { by: "human:you", at: 2026-01-31T09:00:00Z }
+```
+
+`generated` is provenance: it names whatever produced the text — a person, or
+the agent that drafted it — and nothing has to authorise it. `approval.by` is
+authority, so it must name an actor `.ksor/governance.yaml` lists, and its `at`
+may not be earlier than `generated.at` — the text that was approved has to be
+the text that was written. That act is yours, so the record never claims
+authority nobody granted.
+
 ### Presenting a document
 
 Ask your coding agent for slides and it writes them, from the document, into
@@ -77,26 +117,44 @@ opening, and the skill will say so rather than write one.
 The record's other surface is an MCP server for AI agents — the same
 knowledge, cited, with honest abstention. It is the climbed rung: it needs a
 Postgres store (with pgvector) and an embedding provider key, so it is not
-part of `pnpm dev`. The ordered path is:
+part of `pnpm dev`. Three steps, and the order is load-bearing: the command
+block is last because it needs both of the things above it. Skip ahead to it
+and `pnpm provision` refuses, naming the config step 1 writes.
 
-```sh
-cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH=disabled-local
-pnpm provision         # once: apply the schema, authorize ingest
-pnpm refresh           # ingest the record, collect retired generations
-pnpm serve             # the MCP server
-```
+**1. Uncomment the `database:` block already in `instance.md`.** It names the
+VARIABLE holding your DSN, never the DSN itself:
 
-`ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH=disabled-local`
-is required for a local run: serve refuses to boot unauthenticated on purpose,
-so a server is never open by accident.
+```yaml
+database:
+  dsn_env: KSOR_DB_URL
+```
 
-Uncomment the `database:` block already in `instance.md` — it names the
-VARIABLE holding your DSN, never the DSN itself. That is the whole required
-config:
-`embedding:` already defaults to Gemini at 1536 dimensions, and leaving
+Nothing below works until it is there — `pnpm provision` refuses with
+`instance.md declares no database: block`. That is also the whole required
+config: `embedding:` already defaults to Gemini at 1536 dimensions, and leaving
 `retrieval:` out starts you with the abstention gate off and honest about it
 (turn it on afterwards with `ksor calibrate`, once the record is serving).
 
+**2. Copy the environment file**, then fill in `KSOR_DB_URL`, `GEMINI_API_KEY`
+and `KSOR_AUTH=disabled-local`:
+
+```sh
+cp .env.example .env
+```
+
+`ksor` reads `.env` automatically — there is nothing to export, and where a
+refusal tells you to _export_ that variable, putting it in `.env` is the same
+thing. `KSOR_AUTH=disabled-local` is required for a local run: serve refuses to
+boot unauthenticated on purpose, so a server is never open by accident.
+
+**3. Bring it up.**
+
+```sh
+pnpm provision  # once: apply the schema, authorize ingest
+pnpm refresh    # build, ingest the record, collect retired generations
+pnpm serve      # the MCP server
+```
+
 `pnpm provision` runs once — it applies the schema (or migrates it forward) and
 authorizes ingest, the two privileged acts that should not happen on every
 boot. After that: `pnpm refresh` publishes what you have edited, and `pnpm serve`
@@ -104,10 +162,9 @@ runs the server. They are separate because publishing is an act, not a side
 effect of starting a process. A rerun on an unchanged record
 costs nothing: no new generation, no embedding, no rows. Edit a document and
 the next run picks up exactly that change. `AGENTS.md` → "Serving to agents" is the
-full runbook; your coding agent reads it first. `pnpm serve` refuses to boot
-unauthenticated: a local run declares `KSOR_AUTH=disabled-local` (already in
-`.env.example`) and binds loopback, so a server is never left open by accident;
-a public bind needs a configured SSO door instead. Any other operation is
+full runbook; your coding agent reads it first. A public bind needs a
+configured SSO door rather than `disabled-local` — see step 2 and
+"The agent surface deploys separately" below. Any other operation is
 `pnpm exec ksor <verb>`.
 
 ### Test the agent surface with an actual agent
@@ -194,6 +251,40 @@ equivalent (its default refusal of dependency install scripts covers the
 OTHER half of that posture), and this sentence is the disclosure.
 <!-- /ksor:pm -->
 
+### A note on `audit`
+
+An audit of this scaffold reports vulnerabilities in `next`, and will keep
+doing so: a framework that large always has open advisories against whatever
+version you have pinned.
+<!-- ksor:pm npm -->
+`npm install` prints the count at the end of every install, so you meet it
+before you have run anything, next to an invitation to run
+`npm audit fix --force`.
+<!-- /ksor:pm -->
+<!-- ksor:pm pnpm -->
+pnpm reports it only when you run `pnpm audit`.
+<!-- /ksor:pm -->
+<!-- ksor:pm bun -->
+bun reports it only when you run `bun audit`.
+<!-- /ksor:pm -->
+
+**Never let an audit tool raise the pin for you.** It moves off the version
+this scaffold was built and tested against, and that pin is the whole reason
+two machines produce the same site. Bump it deliberately instead — take the
+newer pin a newer `ksor init` emits, or raise it yourself and re-run
+`pnpm build` and the deploy check above.
+
+It also reads worse than it is, for one structural reason worth knowing:
+**this site is a static export.** `pnpm build` writes HTML, JS and CSS to
+`system/site/out/`, and no framework server ever runs in front of your
+readers — no middleware, no server actions, no rewrites, no image optimizer.
+Most framework advisories describe exactly those request paths, so they have
+nothing here to reach. Two things that argument does NOT cover, and you should
+treat as real: an advisory in the **build** toolchain, which does run, on your
+machine and in your CI; and any advisory at all if you later add a served route
+and stop exporting. Read what an advisory affects before deciding it is inert —
+the static export is a reason, not a blanket.
+
 ## The files, explained
 
 Nothing here is decoration, and the dotfiles are not ceremony — each one is a
@@ -203,7 +294,12 @@ different coding agent's way of finding the same working contract.
 | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `knowledge/`                     | **the record** — your governed markdown. The product; everything else serves it.                                                                                                                                                 |
 | `system/`                        | the code that serves the record: the site today, more as you need it.                                                                                                                                                            |
-| `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. |
+| `instance.md`                    | what this record is authoritative for; its `name:` is the identity every surface publishes and its `title:` the display title every page leads with (both read at server/build start — restart `pnpm dev` after changing either). Its BODY is the agent surface's system prompt — `ksor serve` wires it into the MCP server's instructions. |
+| `.ksor/governance.yaml`          | **the root of authority** — which audiences exist, who may approve a document, who may take one down. Committed; every governance act is checked against it. |
+| `.ksor/takedowns.yaml`           | the takedown ledger: every withdrawal and every lift, append-only and committed, so the site honours a takedown with no database in the loop. It appears at your first `ksor takedown` — an empty ledger would assert an act nobody performed. |
+| `build.lock.json`                | what the last `ksor build` published — the corpus, the commit, the toolchain — and what every machine surface stamps. Committed; written by `ksor build`, never by hand. |
+| `Dockerfile`, `.dockerignore`    | how the agent surface reaches a host. The Dockerfile names no host; `vercel.json` points at it rather than replacing it, so moving hosts is a redeploy. |
+| `vercel.json`                    | one domain, two services — the static site and the MCP door — for the host this scaffold answers the setup interview for. Delete it if you deploy elsewhere. |
 | `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), `make-summary` (write a document's summary and attach it), `format-checker` (the rules, as a program).                                                        |
@@ -212,7 +308,7 @@ different coding agent's way of finding the same working contract.
 | `.github/workflows/validate.yml` | your CI: runs the same checker on every pull request and push to main.                                                                                                                                                           |
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
 | `.env.example`                   | the variables the served rung needs; copy to `.env` (gitignored) and fill in. |
-| `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history.                                                                                                                                                    |
+| `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history — and negates two paths inside `.ksor/`, because the policy and the ledger ARE the record.                                                          |
 | `package.json`                   | the surface commands — `pnpm dev` (the site) and `pnpm provision` / `pnpm refresh` / `pnpm serve` (the agent surface: set up once, publish, then serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool and the workspace layout the manifest declares.                                                |
 <!-- ksor:pm pnpm -->
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
@@ -250,27 +346,37 @@ and anything that can serve files can serve it.
   If the build image's pnpm predates the `packageManager` pin, set the
   `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
 <!-- /ksor:pm -->
-**Once `instance.md` declares a `database:`, the BUILD needs the DSN too.**
-`pnpm build` first runs `pnpm export-denylist`, which asks the record's
-database what has been withdrawn (`ksor takedown --export`) and writes
-`.ksor-denylist.json` for the site to read. Without it the build stops:
-
-```
-KSOR_DB_URL is unset, and instance.md declares a database
-  why: a takedown lives in that database. Without it this build cannot tell
-  'nothing is denied' from 'nobody asked'
-```
-
-That is deliberate — a site built without asking would publish a document you
-withdrew. Give the build environment the same `KSOR_DB_URL` your server uses
-(read access is enough), or keep the record database-free, where the export
-writes "nothing denied" and exits 0.
+**`pnpm build` runs `ksor build` first.** It generates every `index.md`,
+runs the record checker, and writes `build.lock.json` — the committed record
+of what was published, from which commit, with which toolchain — and only
+then builds the site. A checker refusal stops the build before anything is
+written. Takedowns reach the site through `.ksor/takedowns.yaml`, the
+committed ledger — a file in this repository, so the site build needs no
+database access at all.
+
+That is deliberate. The act that withdraws a document is one merged commit,
+and both surfaces read it: the door refuses immediately, the site at its next
+build. Merge the ledger entry, rebuild, redeploy.
+
+**A withdrawal that arrives on a clock works the same way, and that one has to
+be scheduled.** `stale_after` and `ksor.effective_from` are evaluated once per
+build, at the instant that build ran, and the answer is written into
+`system/site/out/` — static files cannot re-decide themselves. So a document
+whose `stale_after` passes after your last build keeps appearing in `/llms.txt`
+and in its markdown twin, while `ksor serve` — a process, evaluating per
+request — already refuses it. `ksor build` prints the next instant at which
+this happens. Nothing here rebuilds for you: `validate.yml` runs on pull
+requests and `vercel.json` declares no cron. If this record uses either key,
+add a scheduled rebuild and redeploy.
 
 - **GitHub Pages, nginx, S3, anything static** — run `pnpm build` and
   upload `system/site/out/`. Hosted under a sub-path (like
   `user.github.io/repo`)? Build with `KSOR_BASE_PATH=/repo pnpm build`.
-- **Verify any deploy** the same way: the home page, one document page,
-  and `/llms.txt` all load; nothing else is required.
+- **Verify any deploy** the same way: the home page, one document page and
+  `/llms.txt` load, and each names the documents this record has approved. On a
+  record whose documents are all still drafts, the home page and `/llms.txt`
+  come up empty and there is no document page at all — which is the correct
+  answer, not a broken deploy. Approve a document and rebuild to see it change.
 
 ### The agent surface deploys separately
 
@@ -280,9 +386,20 @@ Cloud Run, Fly, Render, ECS, Kubernetes or a VPS:
 
 ```sh
 docker build -t my-record .
-docker run --rm -p 8080:80 --env-file .env my-record
+docker run --rm -p 8080:80 --env-file .env \
+  -e KSOR_AUTH=disabled-public my-record
 ```
 
+**That last flag is not boilerplate, and it is not a workaround.** The image
+sets `$PORT`, so the door binds `0.0.0.0` — a PUBLIC bind — and the
+`KSOR_AUTH=disabled-local` your `.env` carries refuses there by design, saying
+so in as many words. Your laptop is not the exception: a container really is
+reachable from outside itself, and `disabled-public` is you saying you know
+that. It goes on the command rather than into `.env` so your ordinary
+`pnpm serve` keeps the loopback posture — and a real deployment sets it (or,
+better, the SSO variables) in the host's environment, since `.dockerignore`
+keeps `.env` out of the image entirely.
+
 One thing surprises people: **deploying does not publish.** The door serves
 whatever generation is already in the database, so a first deploy with no
 `pnpm refresh` serves an empty record. Publishing is a step you run — from your
@@ -290,10 +407,11 @@ machine or from CI — and it is deliberately not something a booting container
 does. The full walkthrough, including what a cold start costs and where ingest
 belongs, is in `node_modules/@panaversity/ksor/docs/deploying.md`.
 
-If `instance.md` declares `audiences:`, what you deploy is a **tier**.
-Plain `pnpm build` always builds the public tier — safe for any host.
-`KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier for that
-audience's own deployment, and that build carries an
+If `.ksor/governance.yaml` registers audiences, what you deploy is a
+**viewer**. Plain `pnpm build` builds for `[public]` — safe for any host.
+`KSOR_AUDIENCE=public,<audience> pnpm build` — a comma list that must always
+include `public` — builds for a wider viewer's own deployment, and that build
+carries an
 "— not for publication" label because it must never reach a public host:
 put it behind access control you already trust (VPN, SSO proxy,
 authenticated host). The tiers govern what a build contains; where each

package/templates/scaffold/env.example

@@ -26,7 +26,10 @@ GEMINI_API_KEY=
 #                    a deploy go green.
 #
 # A container sets $PORT, so the door binds 0.0.0.0 — that is a public bind, and
-# `disabled-local` will refuse there. That refusal is the point.
+# `disabled-local` will refuse there. That refusal is the point. To smoke-test
+# the image locally, acknowledge it on the command instead of changing the line
+# below, so a plain `ksor serve` keeps the loopback posture:
+#   docker run --rm -p 8080:80 --env-file .env -e KSOR_AUTH=disabled-public my-record
 #
 # For a real deployment, delete this line and configure the SSO door instead:
 #   KSOR_SSO_URL=https://your-sso.example.com
@@ -48,7 +51,7 @@ KSOR_AUTH=disabled-local
 # "Keeping people out of the site".
 #
 # All three are required together, and are inlined at BUILD time — set them
-# before `pnpm build`, not on the running site. Leave them unset and the
+# before the site build, not on the running site. Leave them unset and the
 # sign-in control does not render at all.
 #
 # The issuer is the same authorization server the door names in KSOR_SSO_URL.
@@ -76,10 +79,38 @@ KSOR_AUTH=disabled-local
 # validating after it, even with one instance.
 # KSOR_SNAPSHOT_KEYS=v1=<32+ random bytes>
 
-# Which audience tier this server serves, when instance.md declares
-# `audiences:`. Unset = the least-privileged tier. Same variable the site's
-# per-audience build reads, so both surfaces mean the same thing.
-# KSOR_AUDIENCE=public
+# WHO this surface answers as: a comma list of audience identifiers, validated
+# against the registry in .ksor/governance.yaml. It must always contain
+# `public`, and unset means exactly `[public]`. A document is visible when its
+# `ksor.audience` list and this one OVERLAP — there is no ranking, so
+# `public,internal` is the reader who may see both, not a level.
+# The same variable the site's per-audience build reads, so both surfaces mean
+# the same thing. A build for anything wider than `public` belongs behind that
+# audience's own access control, never on a public host.
+# KSOR_AUDIENCE=public,internal
+
+# The LOWEST trust tier this door will answer from: unverified (the default),
+# machine-confirmed, or human-reviewed. unverified is the honest state of a
+# record nobody has reviewed, and it is not a defect.
+# Know what the tier IS before you raise the floor onto it. The tier itself is
+# derived and may not be authored (`trust_tier:` in frontmatter is refused),
+# but its input is: a document's own `verified:` entries. Nothing in
+# `.ksor/governance.yaml` gates who may appear there — the policy authorises
+# `ksor.approval` and takedown, and has no verification family — so what stands
+# behind `human-reviewed` is review of the pull request that added the entry,
+# and nothing else. A document that declares a review of itself gets the tier.
+# A caller can raise this per call with the `min_trust_tier` argument; it can
+# never be lowered below what is set here. Setting `human-reviewed` narrows the
+# door to the documents that CLAIM a human review: on a record with no reviews
+# that is nothing at all, and on a record where one document declares its own
+# it is that document ALONE — a floor can invert if you raise it without
+# reading what it admits.
+# KSOR_MIN_TRUST_TIER=unverified
+
+# `ksor build` records drafts as hidden from every surface (the default) or
+# shown on HUMAN surfaces only — a review build, marked noindex. Recorded in
+# build.lock.json and in build_id; never set it for a build you deploy.
+# KSOR_DRAFTS=show
 
 # Bind. PORT is honoured too, for hosts that inject it.
 # KSOR_MCP_HOST=127.0.0.1

package/templates/scaffold/gitignore

@@ -1,5 +1,10 @@
-# scratch space for ksor verbs — everything transient lives under one roof
-.ksor/
+# ksor's working directory — build output and scratch, never the record.
+# The two governance files inside it ARE the record (the policy and the
+# takedown ledger) and are un-ignored by name: the directory form `.ksor/`
+# cannot be negated, so the glob is `.ksor/*`.
+.ksor/*
+!.ksor/governance.yaml
+!.ksor/takedowns.yaml
 
 node_modules/
 system/site/.next/
@@ -8,9 +13,16 @@ system/site/out/
 # the per-audience copy of the record a build stages — a filtered derivative,
 # never a second record; committing it would publish what a build excluded
 system/site/.staged-knowledge/
+# and its manifest, which names this build's viewer and every concept it
+# staged — committing it publishes the restricted viewer's page list
+system/site/.staged-knowledge.json
 # and the lock that keeps one evaluation of a build staging at a time; it only
 # outlives a build that was killed mid-stage, and the next build clears it
 system/site/.staged-knowledge.lock
+# where this build SERVES the sims it published — copied out of the staged
+# record, so it holds one viewer's sims and the next build prunes the rest;
+# the record owns the sim, this is only the copy that gets a url
+system/site/public/sims/
 *.tsbuildinfo
 
 # secrets never enter the record — system/ is their future home (serve)
@@ -18,7 +30,3 @@ system/site/.staged-knowledge.lock
 !.env.example
 
 .DS_Store
-
-# The takedown manifest the site build reads — exported from the database,
-# never hand-edited, and re-exported on every build.
-.ksor-denylist.json

package/templates/scaffold/instance.md

@@ -1,7 +1,9 @@
 ---
-format: 1
+format: 2
 name: KSOR-STAMP-NAME
-ksor:
+title: KSoR
+description: What a Knowledge System of Record is, how a project climbs the governance ladder, and which surfaces publish the same governed knowledge.
+toolchain:
   requires: ">=KSOR-STAMP-VERSION"
   scaffolded: "KSOR-STAMP-VERSION"
 # The served MCP rung needs ONE required block: the NAME of the environment
@@ -23,8 +25,6 @@ ksor:
 # version: 0.1.0
 ---
 
-# KSoR
-
 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
@@ -37,23 +37,27 @@ record wins.
 ## 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.
+project has a real governed corpus on the first `pnpm dev` — five approved
+documents, three of them inside a folder, and one carrying all four study
+attachments (a summary, slides, flashcards and a quiz) — 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.
+thing describes it _everywhere_. Three things here are read by every surface:
+
+- **`title:`** is the display title — the human name every page leads with and
+  the heading of the record's root index. The machine identity stays
+  `KSOR-STAMP-NAME` in `name:`, and that is what citations and `llms.txt` use.
+- **`description:`** is one sentence that seeds `llms.txt` and the MCP
+  discovery document.
+- **This body** is the MCP server's instructions, handed in full to every
+  connecting agent; its first paragraph is this record's scope, which the site
+  publishes. A record published with it 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. Replace those two lines and every surface follows,
+this document with you. Replace those three and every surface follows,
 because every surface reads them from here.

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

@@ -1,9 +1,13 @@
 ---
+type: Document
 title: The governance ladder
 description: Level 0 works immediately; a project climbs only as far as its domain needs.
-status: draft
-owner: Product
+status: stable
 order: 3
+generated: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+ksor:
+  audience: [public]
+  approval: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
 ---
 
 Governance here is a ladder, not a gate. Demanding the top rung of a project on
@@ -18,6 +22,11 @@ record of such documents is already publishable, searchable and citable.
 
 Each rung is worth climbing when the domain asks for it, and not before.
 
+> [!TIP]
+> Climb one rung at a time, and only when something has gone wrong without it.
+> A record that adds owners before anyone disputes a document spends review
+> effort buying nothing.
+
 ### Owners and sources
 
 An owner names who stands behind a document. Provenance names where its claims

package/templates/scaffold/knowledge/index.md

@@ -0,0 +1,9 @@
+---
+okf_version: "0.2"
+---
+
+# KSoR
+
+* [What a Knowledge System of Record is](what-is-a-ksor.md) - The authoritative, governed knowledge layer humans, agents and software operate from.
+* [The governance ladder](governance-ladder.md) - Level 0 works immediately; a project climbs only as far as its domain needs.
+* [Surfaces](surfaces/)

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

@@ -1,12 +1,13 @@
 ---
+type: Document
 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"
+status: stable
+order: 6
+generated: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+ksor:
+  audience: [public]
+  approval: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
 ---
 
 Agents reach the record through MCP — an open standard, so one corpus answers in
@@ -22,6 +23,12 @@ be checked against the document that carries it rather than taken on trust.
 "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.
 
+> [!WARNING]
+>
+> An agent that fills a gap from its own memory has not used this record — it
+> has used it as an opening paragraph. Nothing in the answer says which half
+> came from where.
+
 ## Files beside the interface
 
 The build publishes the same knowledge as plain files an agent can fetch without

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

@@ -1,12 +1,13 @@
 ---
+type: Document
 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"
+status: stable
+order: 5
+generated: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+ksor:
+  audience: [public]
+  approval: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
 ---
 
 A static site renders every governed document at a route derived from its path,

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

@@ -1,21 +1,5 @@
----
-title: Surfaces
-description: One source, published through several synchronized projections.
-status: approved
-owner: Product
-order: 2
----
+# Surfaces
 
-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.
+* [Surfaces](overview.md) - One source, published through several synchronized projections.
+* [The human surface](for-people.md) - Pages for reading, reviewing and sharing the record.
+* [The agent surface](for-agents.md) - MCP for retrieval with citations, and machine-readable files beside it.

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

@@ -0,0 +1,25 @@
+---
+type: Document
+title: Surfaces
+description: One source, published through several synchronized projections.
+status: stable
+order: 4
+generated: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+ksor:
+  audience: [public]
+  approval: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+---
+
+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

@@ -1,12 +1,13 @@
 ---
+type: Document
 title: What a Knowledge System of Record is
 description: The authoritative, governed knowledge layer humans, agents and software operate from.
-status: approved
-owner: Product
+status: stable
 order: 1
-effective: 2026-08-22
-provenance:
-  - KSoR README, "What Is a Knowledge System of Record?"
+generated: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
+ksor:
+  audience: [public]
+  approval: { by: "ksor-starter/KSOR-STAMP-VERSION", at: 2026-08-25T00:00:00Z }
 ---
 
 A traditional system of record establishes what is true about the current state

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

@@ -1,3 +1,7 @@
+---
+type: Summary
+---
+
 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.
 

package/templates/scaffold/package.json

@@ -5,15 +5,14 @@
   "type": "module",
   "scripts": {
     "dev": "pnpm -C system/site dev",
-    "build": "pnpm export-denylist && pnpm -C system/site build",
-    "export-denylist": "ksor takedown --instance instance.md --export .ksor-denylist.json",
+    "build": "ksor build && pnpm -C system/site build",
     "check": "node .agents/skills/format-checker/check.mjs",
     "provision": "pnpm schema && pnpm grant",
     "serve": "ksor serve",
-    "refresh": "pnpm ingest && pnpm gc",
+    "refresh": "ksor build && pnpm ingest && pnpm gc",
     "schema": "ksor schema --instance instance.md --apply",
     "grant": "ksor grant --instance instance.md",
-    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip",
+    "ingest": "ksor ingest --instance instance.md --flip",
     "gc": "ksor gc --instance instance.md"
   },
   "dependencies": {