@panaversity/ksor 0.0.7 → 0.0.8

package/dist/index.d.mts

@@ -21,7 +21,7 @@ declare const exitCodes: {
 type ExitCode = (typeof exitCodes)[keyof typeof exitCodes];
 /** The CLI vocabulary. Lifecycle verbs plus the corpus operations the bundled
  * kernel provides (one binary — decision 12 publish revision). */
-declare const verbs: readonly ["init", "dev", "build", "serve", "ingest", "schema", "grant", "calibrate", "gc"];
+declare const verbs: readonly ["init", "dev", "build", "serve", "ingest", "schema", "grant", "takedown", "calibrate", "gc"];
 type Verb = (typeof verbs)[number];
 interface ResolvedCommand {
   /** The first non-flag token, or null when only flags (or nothing) appear. */

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-CpDIVudJ.mjs";
+import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
 export { exitCodes, resolveCommand, verbs };

package/dist/{src-CpDIVudJ.mjs → src-pl4aOpVs.mjs}

@@ -28,6 +28,7 @@ const verbs = [
 	"ingest",
 	"schema",
 	"grant",
+	"takedown",
 	"calibrate",
 	"gc"
 ];

package/docs/index.md

@@ -24,10 +24,14 @@ instead of their training memory. The corpus grows with each implemented verb.
   at `http://localhost:3000`; `pnpm build` writes a fully static export to
   `system/site/out/`. `KSOR_BASE_PATH=/repo pnpm build` targets sub-path
   hosting.
-- `ksor serve` runs the MCP server over a built record (with
-  `ingest`/`schema`/`calibrate`/`gc`) — the climbed rung, needing Postgres and
-  a provider key. Only `dev` and `build` remain designed, not implemented:
-  each prints an honest notice and exits `2`.
+- `ksor serve` runs the MCP server over a built record — the climbed rung,
+  needing Postgres and a provider key — alongside the write plane that keeps
+  the record current: `ksor schema` (provision or migrate the database),
+  `ksor grant` (authorize a tenant for ingest), `ksor ingest` (build and publish
+  a generation), `ksor takedown` (withdraw a document from EVERY surface, and
+  export the manifest the site build reads), `ksor calibrate` (measure the
+  abstention floor) and `ksor gc` (reap retired generations). Only `ksor dev` and `ksor build` remain designed, not
+  implemented: each prints an honest notice and exits `2`.
 - Exit codes are a contract: `1` refused (first stderr line is a stable
   slug such as `error: bad-name`, followed by a remedy), `2` designed but
   not implemented, `3` the environment cannot run ksor

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.7",
-  "description": "Knowledge System of Record — the authoritative, governed source of knowledge that humans and AI agents operate from. Name reserved; implementation in progress.",
+  "version": "0.0.8",
+  "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",
     "citations",

package/schema/migrations/2.1-2.2__governance-on-the-node-row.sql

@@ -0,0 +1,55 @@
+-- 2.1 -> 2.2 · Governance moves onto the node row.
+--
+-- Until now the ingest adapter kept four things from a document's frontmatter
+-- (title, order, an optional sor_id, and the path-derived slug) and discarded
+-- the rest, so `visibility`, the authored `status`, `owner` and `provenance`
+-- existed only in markdown and in whichever surface happened to re-derive them.
+-- The site enforced `visibility:`; the MCP door could not, because the record
+-- did not carry it. This migration gives the record the columns every surface
+-- must read, so the guarantee lives in one place instead of being re-implemented
+-- per surface.
+--
+-- Every column is additive and nullable, so a 2.1 reader still reads a 2.2
+-- database (compatible_from stays 2.0). `corpus_id` is backfilled from the
+-- corpora pointer, which is exact while one corpus serves one tenant — the
+-- state this migration runs in.
+
+ALTER TABLE content_nodes
+    -- Which record this node belongs to. Content rows were scoped by
+    -- (tenant_id, generation) only, while corpora/ingestion_runs/takedown are
+    -- keyed (tenant_id, corpus_id); carrying it here closes that split before a
+    -- second record exists.
+    ADD COLUMN IF NOT EXISTS corpus_id     TEXT,
+    -- The audience tier the document declares. NULL = the instance's
+    -- default_visibility. Enforced at the serving door, not only at site build.
+    ADD COLUMN IF NOT EXISTS visibility    TEXT,
+    -- The AUTHORED governance status (draft / approved / superseded). Distinct
+    -- from `status`, which is the SERVING state of the row (published /
+    -- draft / archived) and is set by the pipeline, not by the author.
+    ADD COLUMN IF NOT EXISTS doc_status    TEXT,
+    ADD COLUMN IF NOT EXISTS owner         TEXT,
+    -- Where the document's claims come from, as authored. JSONB so a list of
+    -- sources survives without inventing a side table.
+    ADD COLUMN IF NOT EXISTS provenance    JSONB,
+    -- stable_id of the document that replaces this one, when it is superseded.
+    ADD COLUMN IF NOT EXISTS superseded_by TEXT;
+
+UPDATE content_nodes n
+   SET corpus_id = c.corpus_id
+  FROM corpora c
+ WHERE c.tenant_id = n.tenant_id
+   AND n.corpus_id IS NULL;
+
+-- NOTE (2.4): this index is DROPPED again by 2.2 -> 2.3, and schema.sql builds
+-- a fresh database without it. The rationale below is wrong and is kept only
+-- because a migration that has run somewhere must not be rewritten: the serving
+-- predicate filters on `coalesce(visibility, <a per-transaction GUC>)`, which no
+-- plain btree on `visibility` can serve, so the index was built and maintained
+-- and never read — the same defect the HNSW arm was fixed for. An operator
+-- reading this file sees the claim, so it is corrected here rather than
+-- silently (round-9 review of PR 43).
+--
+-- The serving filter is (tenant, generation, visibility); without this the
+-- audience predicate turns every search into a scan of the generation.
+CREATE INDEX IF NOT EXISTS idx_nodes_visibility
+    ON content_nodes (tenant_id, generation, visibility);

package/schema/migrations/2.2-2.3__takedown-writes-and-a-readable-ledger.sql

@@ -0,0 +1,70 @@
+-- 2.2 -> 2.3 · A door for takedown, and a ledger someone can read.
+--
+-- Two governance mechanisms were complete except for the permission that makes
+-- them usable:
+--
+--   takedown_denylist  the serving-side denial worked perfectly, but ingest
+--                      held only SELECT — so the only way to impose a takedown
+--                      was a superuser psql prompt, and nothing recorded who
+--                      did it.
+--   retrieval_log      FORCE row-level security, an INSERT policy, and NO
+--                      select policy and no SELECT grant to any role. The
+--                      provenance ledger the governance story rests on could
+--                      be written and never read. CI only appeared to prove
+--                      otherwise because its DSN is a superuser.
+
+-- ── takedown: the write plane ────────────────────────────────────────────────
+GRANT INSERT, UPDATE, DELETE ON takedown_denylist TO sor_content_ingest;
+
+-- Same shape as ingest_write on the content tables: the tenant GUC must match
+-- AND the grant table must authorize this role for this tenant. A takedown is
+-- a write to the record's governance and is authorized the same way every
+-- other write is.
+DROP POLICY IF EXISTS takedown_write ON takedown_denylist;
+CREATE POLICY takedown_write ON takedown_denylist FOR ALL TO sor_content_ingest
+  USING (tenant_id = current_setting('app.tenant_id', true)
+         AND EXISTS (SELECT 1 FROM ingest_tenant_grants g
+                      WHERE g.role_name = current_user
+                        AND g.tenant_id = takedown_denylist.tenant_id))
+  WITH CHECK (tenant_id = current_setting('app.tenant_id', true)
+         AND EXISTS (SELECT 1 FROM ingest_tenant_grants g
+                      WHERE g.role_name = current_user
+                        AND g.tenant_id = takedown_denylist.tenant_id));
+
+-- ── retrieval_log: a role that can actually read the ledger ──────────────────
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'sor_content_auditor') THEN
+    CREATE ROLE sor_content_auditor NOLOGIN;
+  END IF;
+END $$;
+
+GRANT USAGE ON SCHEMA public TO sor_content_auditor;
+GRANT SELECT ON retrieval_log TO sor_content_auditor;
+-- An auditor reads the ledger and the denial list; it can reach no content.
+GRANT SELECT ON takedown_denylist, schema_meta, corpora, ingestion_runs TO sor_content_auditor;
+
+-- The tenant wall applies to the auditor exactly as it does to everyone else:
+-- reading the ledger is still scoped to one tenant's rows.
+DROP POLICY IF EXISTS tenant_read ON retrieval_log;
+CREATE POLICY tenant_read ON retrieval_log FOR SELECT
+  USING (tenant_id = current_setting('app.tenant_id', true));
+
+-- The applying user can assume it, the way it can already assume the other two.
+DO $$
+BEGIN
+  EXECUTE format('GRANT sor_content_auditor TO %I WITH SET TRUE', current_user);
+END $$;
+
+-- Lifting a denial must be distinguishable from imposing one by the INDEXED
+-- action column, not only by reading each row's JSON detail.
+ALTER TABLE retrieval_log DROP CONSTRAINT IF EXISTS retrieval_log_action_check;
+ALTER TABLE retrieval_log ADD CONSTRAINT retrieval_log_action_check CHECK (action = ANY (ARRAY[
+  'content_served','similarity_searched','corpus_seeded','outline_served',
+  'search_abstained','generation_activated','takedown_applied','takedown_revoked']));
+
+-- Drop an index the serving predicate cannot use: it filters on
+-- `coalesce(visibility, <runtime GUC>)`, which no plain btree on `visibility`
+-- can satisfy. Built and maintained, never read — the same shape as the HNSW
+-- index this release also stopped paying for.
+DROP INDEX IF EXISTS idx_nodes_visibility;

package/schema/migrations/2.3-2.4__a-generation-remembers-its-schema.sql

@@ -0,0 +1,22 @@
+-- 2.3 -> 2.4 · A generation records the schema it was built against.
+--
+-- The 2.1 -> 2.2 migration added `content_nodes.visibility` and backfilled only
+-- `corpus_id`, because a migration cannot know what a document's frontmatter
+-- says. So on an upgraded database every PRE-EXISTING node has visibility NULL,
+-- and the serving predicate coalesces NULL to `app.default_visibility` — the
+-- WIDEST tier. An adopter who migrated and did not re-ingest served every
+-- `visibility: restricted` document to every public-tier agent, with the schema
+-- gate green, /ready green, and the boot line reporting the audience model as
+-- enforced (round-5 review of #43).
+--
+-- Nothing could detect that, because a generation had no record of when it was
+-- built. Now it does: `ingestion_runs.schema_version` is stamped at ingest, and
+-- NULL means "built before this column existed" — which is exactly the set of
+-- generations whose governance columns cannot be trusted. `serve` refuses to
+-- boot on one when the record declares an audience model.
+
+ALTER TABLE ingestion_runs
+    ADD COLUMN IF NOT EXISTS schema_version TEXT;
+
+COMMENT ON COLUMN ingestion_runs.schema_version IS
+  'The schema_meta version in force when this generation was built. NULL means it predates the governance columns, so its visibility values are absent rather than empty.';

package/schema/schema.sql

@@ -1,6 +1,8 @@
 -- sor-content schema v2 — the generational corpus store (specs/platform/generations.md §2 is the
 -- design this implements; specs/platform/spec.md §5 the roles; the legacy schema the quarry).
--- ONE schema file; no migration runner (spec §9: compatibility is a RANGE, recorded in schema_meta).
+-- This file provisions a FRESH database at the current version; an EXISTING one moves forward
+-- through schema/migrations/<from>-<to>__<slug>.sql (spec §9: compatibility is a RANGE, recorded
+-- in schema_meta). Both halves are required — the file alone cannot migrate rows an adopter has.
 --
 -- Carried from legacy verbatim where the eval lock demands it: HNSW (m=16, ef_construction=64)
 -- cosine, 'english' generated tsvector, per-tenant one-embedding-model trigger, fail-closed tenant
@@ -41,6 +43,12 @@ CREATE TABLE ingestion_runs (
     started_at             TIMESTAMPTZ NOT NULL DEFAULT now(),
     heartbeat_at           TIMESTAMPTZ NOT NULL DEFAULT now(),
     finished_at            TIMESTAMPTZ,
+    -- The schema version in force when this generation was BUILT. A generation
+    -- carried forward across the 2.1 -> 2.2 migration has NULL visibility on
+    -- every node, which the serving predicate reads as the widest tier — so a
+    -- record with an audience model must refuse to serve such a generation
+    -- rather than quietly publish restricted documents (2.4).
+    schema_version         TEXT,
     UNIQUE (tenant_id, corpus_id, generation)
 );
 
@@ -59,6 +67,15 @@ CREATE TABLE content_nodes (
     position   INT  NOT NULL DEFAULT 0,
     permalink  TEXT,                                  -- CONFIRMED site route (/docs/…), sitemap-verified at publish; NULL = no proven page URL (a group, or an unlisted route) — never a guess
     status     TEXT NOT NULL DEFAULT 'published' CHECK (status IN ('published','draft','archived')),
+    -- Governance the AUTHOR declares, carried by the record itself (2.2) so every
+    -- surface reads one source instead of re-deriving it from markdown. `status`
+    -- above is the SERVING state of the row; `doc_status` is what the document says.
+    corpus_id     TEXT,                               -- which record this node belongs to
+    visibility    TEXT,                               -- audience tier; NULL = instance default_visibility
+    doc_status    TEXT,                               -- draft / approved / superseded, as authored
+    owner         TEXT,
+    provenance    JSONB,                              -- where the claims come from, as authored
+    superseded_by TEXT,                               -- stable_id of the replacement
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     CONSTRAINT nodes_stable_uniq  UNIQUE (tenant_id, generation, stable_id),
@@ -71,6 +88,12 @@ CREATE TABLE content_nodes (
 CREATE INDEX idx_nodes_gen      ON content_nodes (tenant_id, generation, kind);
 CREATE INDEX idx_nodes_parent   ON content_nodes (parent_id);
 CREATE INDEX idx_nodes_keywords ON content_nodes USING gin (keywords);
+-- NO index on visibility. The serving predicate is
+-- `coalesce(n.visibility, <runtime GUC>) = ANY(...)`, and a plain btree cannot
+-- serve a coalesce over a value that is only known per transaction — the index
+-- would be built and maintained and never read, which is exactly the defect
+-- the HNSW arm was just fixed for. The audience filter rides the
+-- (tenant_id, generation, kind) index that every serving arm already uses.
 CREATE UNIQUE INDEX nodes_root_slug_uniq ON content_nodes (tenant_id, generation, slug) WHERE parent_id IS NULL;
 
 CREATE TABLE slug_aliases (
@@ -117,6 +140,11 @@ CREATE TABLE chunks (
     embedding         VECTOR(1536),                  -- NULL while pending/failed; dim = the declared space
     embedding_status  TEXT NOT NULL DEFAULT 'embedded'
                       CHECK (embedding_status IN ('pending','embedded','failed')),
+    -- The text-search configuration is RENDERED from instance.md
+    -- (retrieval.text_search_config), the way the embedding dimension is. It
+    -- is STORED and GENERATED, so it cannot be changed without a re-ingest —
+    -- which is exactly why the record declares it rather than inheriting
+    -- 'english' from the DDL (audit finding 20).
     search_tsv        TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
     created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
     embedded_at       TIMESTAMPTZ,
@@ -171,7 +199,7 @@ CREATE TABLE retrieval_log (
     actor       TEXT NOT NULL,                       -- NO default: unset errors loudly (carried)
     action      TEXT NOT NULL CHECK (action IN
                   ('content_served','similarity_searched','corpus_seeded','outline_served',
-                   'search_abstained','generation_activated','takedown_applied')),
+                   'search_abstained','generation_activated','takedown_applied','takedown_revoked')),
     source_id   TEXT,
     -- spec §7 audit fields (explicit + queryable; free detail rides JSONB)
     content_hash           TEXT,
@@ -193,9 +221,16 @@ CREATE TABLE schema_meta (
     compatible_from TEXT NOT NULL,
     applied_at      TIMESTAMPTZ NOT NULL DEFAULT now()
 );
--- 2.1 adds takedown_denylist.scope (decision 14); additive with a default, so
--- a 2.0 reader still reads a 2.1 database — compatible_from stays 2.0.
-INSERT INTO schema_meta (schema_version, compatible_from) VALUES ('2.1', '2.0');
+-- 2.1 adds takedown_denylist.scope (decision 14). 2.2 puts governance on the node
+-- row (corpus_id, visibility, doc_status, owner, provenance, superseded_by).
+-- 2.3 gives takedown a write plane and the ledger a reader (sor_content_auditor).
+-- 2.4 stamps each generation with the schema it was built against, so a
+-- generation predating the governance columns can be REFUSED rather than served
+-- at default_visibility.
+-- Both are additive and nullable, so a 2.0 reader still reads a 2.2 database —
+-- compatible_from stays 2.0. Existing databases move forward through
+-- schema/migrations/; schema.sql provisions a FRESH one at the current version.
+INSERT INTO schema_meta (schema_version, compatible_from) VALUES ('2.4', '2.0');
 
 CREATE OR REPLACE FUNCTION touch_updated_at() RETURNS trigger AS $$
 BEGIN NEW.updated_at = now(); RETURN NEW; END; $$ LANGUAGE plpgsql;
@@ -229,6 +264,9 @@ CREATE TABLE ingest_tenant_grants (
 DO $$ BEGIN
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_runtime') THEN CREATE ROLE sor_content_runtime NOLOGIN; END IF;
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_ingest')  THEN CREATE ROLE sor_content_ingest NOLOGIN;  END IF;
+  -- The ledger's READER (2.3). Without it retrieval_log was write-only under
+  -- every credential ksor ships: FORCE RLS, an INSERT policy, and no way back in.
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'sor_content_auditor') THEN CREATE ROLE sor_content_auditor NOLOGIN; END IF;
 END $$;
 
 -- Explicit in-schema membership for the APPLYING role, so SET LOCAL ROLE works from day one
@@ -236,10 +274,10 @@ END $$;
 -- every fresh project until hand-fixed). Deployment LOGIN roles receive the same membership
 -- when they are provisioned (1h).
 DO $$ BEGIN
-  EXECUTE format('GRANT sor_content_runtime, sor_content_ingest TO %I WITH SET TRUE', current_user);
+  EXECUTE format('GRANT sor_content_runtime, sor_content_ingest, sor_content_auditor TO %I WITH SET TRUE', current_user);
 END $$;
 
-GRANT USAGE ON SCHEMA public TO sor_content_runtime, sor_content_ingest;
+GRANT USAGE ON SCHEMA public TO sor_content_runtime, sor_content_ingest, sor_content_auditor;
 -- runtime: read published corpora, write the ledger — NOTHING else.
 GRANT SELECT ON corpora, content_nodes, sources, chunks, slug_aliases, node_centroids, takedown_denylist, schema_meta TO sor_content_runtime;
 -- freshness on /health (2026-07-16): the runtime reads the active run's source_commit +
@@ -248,7 +286,15 @@ GRANT SELECT ON ingestion_runs TO sor_content_runtime;
 GRANT INSERT ON retrieval_log TO sor_content_runtime;
 GRANT USAGE, SELECT ON SEQUENCE retrieval_log_id_seq TO sor_content_runtime;
 -- ingest: build generations + flip, for AUTHORIZED tenants only (policy-checked via the grant table).
-GRANT SELECT ON schema_meta, takedown_denylist, ingest_tenant_grants TO sor_content_ingest;
+GRANT SELECT ON schema_meta, ingest_tenant_grants TO sor_content_ingest;
+-- Takedown is a WRITE to the record's governance: ingest imposes and lifts it
+-- through `ksor takedown`, authorized by the same grant table every other write
+-- is (2.3 — before it, the only door was a superuser psql prompt).
+GRANT SELECT, INSERT, UPDATE, DELETE ON takedown_denylist TO sor_content_ingest;
+-- The ledger needs a READER. Without one, retrieval_log was write-only under
+-- every credential ksor ships (2.3).
+GRANT SELECT ON retrieval_log TO sor_content_auditor;
+GRANT SELECT ON takedown_denylist, schema_meta, corpora, ingestion_runs TO sor_content_auditor;
 GRANT SELECT, INSERT, UPDATE, DELETE ON corpora, ingestion_runs, content_nodes, sources, chunks, slug_aliases, node_centroids TO sor_content_ingest;
 GRANT INSERT ON retrieval_log TO sor_content_ingest;
 GRANT USAGE, SELECT ON SEQUENCE retrieval_log_id_seq, ingestion_runs_run_id_seq TO sor_content_ingest;
@@ -274,10 +320,17 @@ CREATE POLICY tenant_read ON node_centroids    FOR SELECT USING (tenant_id = cur
 CREATE POLICY tenant_read ON takedown_denylist FOR SELECT USING (tenant_id = current_setting('app.tenant_id', true));
 CREATE POLICY tenant_read ON ingestion_runs    FOR SELECT USING (tenant_id = current_setting('app.tenant_id', true));
 -- Ledger writes:
+CREATE POLICY tenant_read ON retrieval_log FOR SELECT
+  USING (tenant_id = current_setting('app.tenant_id', true));
 CREATE POLICY tenant_write ON retrieval_log FOR INSERT
   WITH CHECK (tenant_id = current_setting('app.tenant_id', true));
 -- Ingest mutations: tenant GUC match AND the grant table authorizes THIS role for THIS tenant
 -- (a CLI flag is not authorization — spec §5).
+CREATE POLICY takedown_write ON takedown_denylist FOR ALL TO sor_content_ingest
+  USING (tenant_id = current_setting('app.tenant_id', true)
+         AND EXISTS (SELECT 1 FROM ingest_tenant_grants g WHERE g.role_name = current_user AND g.tenant_id = takedown_denylist.tenant_id))
+  WITH CHECK (tenant_id = current_setting('app.tenant_id', true)
+         AND EXISTS (SELECT 1 FROM ingest_tenant_grants g WHERE g.role_name = current_user AND g.tenant_id = takedown_denylist.tenant_id));
 CREATE POLICY ingest_write ON content_nodes FOR ALL TO sor_content_ingest
   USING (tenant_id = current_setting('app.tenant_id', true)
          AND EXISTS (SELECT 1 FROM ingest_tenant_grants g WHERE g.role_name = current_user AND g.tenant_id = content_nodes.tenant_id))

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

@@ -121,6 +121,16 @@ function parseFrontmatter(text) {
   for (const raw of match[1].split("\n")) {
     const line = raw.replace(/[ \t]+$/, "");
     if (line === "") continue;
+    // A full-line `#` comment is YAML, and the kernel's own instance parser
+    // skips it — the checker refusing one made the two grammars disagree about
+    // the same file, which is exactly the drift this checker exists to stop.
+    // A TRAILING `# ...` is a different question and this is not the place it
+    // is decided: `scalarValue` below strips it, exactly as the kernel's
+    // frontmatter reader and the site's both do. (An earlier comment here
+    // claimed the opposite — that a trailing comment stays part of the value —
+    // which contradicted this file's own reader and both build scanners;
+    // round-9 review of PR 43.)
+    if (line.trimStart().startsWith("#")) continue;
     // YAML requires a space after the colon and refuses tab indentation —
     // both parsed here fine and failed the build (review findings, 2026-08-18).
     if (/^[A-Za-z_][\w-]*:\S/.test(line)) tightColons.push(line);
@@ -630,8 +640,12 @@ if (!existsSync(knowledgeDir)) {
           crossings.push({ kind: "superseded_by", rel, from: p, to: resolved, target: successor });
         }
       }
-      // visibility: one audience per document, from the set instance.md declares
-      const visibility = fm.keys.get("visibility");
+      // 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
+      // declared audience` for a document every reader resolves to `internal`
+      // (round-9 review of PR 43).
+      const visibility = scalarValue(fm, "visibility");
       const listed = fm.lists.get("visibility") ?? [];
       // A flow list ([a, b]) is already named by the shape rule above.
       const flowList = !fm.quoted.has("visibility") && /^\[.*\]$/.test(visibility ?? "");
@@ -722,6 +736,14 @@ const INSTANCE_KEYS = new Set([
   "site",
   "audiences",
   "default_visibility",
+  // Where this record's MCP surface is published. The site emits it as
+  // /.well-known/mcp/server.json so an agent can DISCOVER the record rather
+  // than being told the URL (AGENTS.md critical rule 3).
+  "mcp_url",
+  // The record's published semver. The MCP discovery document REQUIRES a
+  // version, so this key has to be declarable — and therefore accepted here,
+  // or `pnpm check` refuses the very thing the site needs.
+  "version",
   "database",
   "embedding",
   "retrieval",

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

@@ -121,6 +121,16 @@ function parseFrontmatter(text) {
   for (const raw of match[1].split("\n")) {
     const line = raw.replace(/[ \t]+$/, "");
     if (line === "") continue;
+    // A full-line `#` comment is YAML, and the kernel's own instance parser
+    // skips it — the checker refusing one made the two grammars disagree about
+    // the same file, which is exactly the drift this checker exists to stop.
+    // A TRAILING `# ...` is a different question and this is not the place it
+    // is decided: `scalarValue` below strips it, exactly as the kernel's
+    // frontmatter reader and the site's both do. (An earlier comment here
+    // claimed the opposite — that a trailing comment stays part of the value —
+    // which contradicted this file's own reader and both build scanners;
+    // round-9 review of PR 43.)
+    if (line.trimStart().startsWith("#")) continue;
     // YAML requires a space after the colon and refuses tab indentation —
     // both parsed here fine and failed the build (review findings, 2026-08-18).
     if (/^[A-Za-z_][\w-]*:\S/.test(line)) tightColons.push(line);
@@ -630,8 +640,12 @@ if (!existsSync(knowledgeDir)) {
           crossings.push({ kind: "superseded_by", rel, from: p, to: resolved, target: successor });
         }
       }
-      // visibility: one audience per document, from the set instance.md declares
-      const visibility = fm.keys.get("visibility");
+      // 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
+      // declared audience` for a document every reader resolves to `internal`
+      // (round-9 review of PR 43).
+      const visibility = scalarValue(fm, "visibility");
       const listed = fm.lists.get("visibility") ?? [];
       // A flow list ([a, b]) is already named by the shape rule above.
       const flowList = !fm.quoted.has("visibility") && /^\[.*\]$/.test(visibility ?? "");
@@ -722,6 +736,14 @@ const INSTANCE_KEYS = new Set([
   "site",
   "audiences",
   "default_visibility",
+  // Where this record's MCP surface is published. The site emits it as
+  // /.well-known/mcp/server.json so an agent can DISCOVER the record rather
+  // than being told the URL (AGENTS.md critical rule 3).
+  "mcp_url",
+  // The record's published semver. The MCP discovery document REQUIRES a
+  // version, so this key has to be declarable — and therefore accepted here,
+  // or `pnpm check` refuses the very thing the site needs.
+  "version",
   "database",
   "embedding",
   "retrieval",

package/templates/scaffold/AGENTS.md

@@ -52,8 +52,9 @@ pnpm check       # the format checker — run before handing off any knowledge c
 with honest abstention. It is the climbed rung — not required for `pnpm dev`.
 Stand it up in this order (each step's errors explain how to fix themselves):
 
-1. **Configure `instance.md`.** One block is required — the name of the
-   environment variable holding your DSN (never the DSN itself):
+1. **Configure `instance.md`.** One block is required, and it is already
+   there, commented out — uncomment it. It names the environment variable
+   holding your DSN (never the DSN itself):
 
    ```yaml
    database:
@@ -90,12 +91,58 @@ Stand it up in this order (each step's errors explain how to fix themselves):
      intended dev shape. A PUBLIC deployment configures the SSO door instead —
      see the comments in `.env.example` and "Serving safely" below.
 
-3. **Bring it up — one command:**
+3. **Bring it up.** Once, then every time:
 
    ```sh
-   pnpm serve   # schema → grant → ingest → serve
+   pnpm provision   # schema (or migrate) + grant — the privileged acts, run once
+   pnpm refresh # ingest the record, collect retired generations
+   pnpm serve   # the MCP server (one supervised process)
    ```
 
+   `provision` is separate on purpose: applying DDL and granting ingest are acts
+   an operator performs, not side effects of starting a server. (It is not
+   called `setup` because `pnpm setup` is pnpm's own command and would shadow
+   it — the step would print "No changes to the environment were made" and do
+   nothing.)
+
+   **Deploying to a container runtime you do not control** (Cloud Run, Fly,
+   Container Apps — anything that scales to zero and hands you a `$PORT`):
+   `ksor serve` is already shaped for it, and the posture is deliberate.
+
+   - It binds `$PORT` on `0.0.0.0` when the platform sets one.
+   - It holds **no idle database connections**. The pool minimum is 0 and an
+     unused connection is closed after 10s, so an idle instance keeps nothing
+     open against a serverless Postgres — and a busy one still reuses
+     connections instead of paying a TLS handshake per request.
+   - The first request after an idle period wakes the database, and that
+     connect is **retried** rather than failing: a cold start is a transient,
+     not a refusal.
+   - `SIGTERM` drains and exits within 8s, inside the ~10s a runtime usually
+     allows before `SIGKILL`.
+
+   What it does NOT do is open and close a connection per request. That is the
+   pattern connection poolers exist to remove — the handshake alone is ~26x the
+   cost of a pooled query even on localhost, before TLS — and it is not what
+   managed Postgres vendors recommend for a process that serves many requests.
+   Per-request connections are the right shape only for a per-invocation
+   runtime (an edge function), which is a different deployment and would want
+   an HTTP database driver rather than TCP.
+
+   Set `KSOR_SNAPSHOT_KEYS` for any such deployment: without it each cold start
+   mints a new signing key, so citations pinned before a scale-down stop
+   validating after it.
+
+   **`pnpm serve` serves; it does not publish.** It is `ksor serve` and nothing
+   else — it opens the port against whatever generation is already active and
+   needs no ingest privileges. Publishing is `pnpm ingest` (or `pnpm refresh`),
+   and it is a separate step ON PURPOSE: a container that re-ingested on boot
+   would pay the whole record's embedding cost on every cold start and would
+   need write credentials at runtime. So in a deployment, run `pnpm provision` and
+   `pnpm ingest` as DEPLOY steps and run `ksor serve` in the container, where
+   it honours `$PORT` and binds `0.0.0.0`. If you skip the ingest step, the
+   container serves the last generation you flipped — and on a FIRST deploy,
+   that is nothing at all.
+
    Every step is re-runnable, so this is also how you **refresh after editing
    `knowledge/`**: an applied schema reports "already applied", an existing
    grant reports "already granted", and ingest builds a fresh generation.
@@ -168,7 +215,9 @@ abandoned ones.
 
 ### Serving safely (fail-closed posture)
 
-`pnpm serve` binds **loopback with auth off** — safe for local use. A **public**
+`pnpm serve` **refuses to boot unauthenticated** — there is no auth-off
+default. A local run says so deliberately with `KSOR_AUTH_DISABLED=1` and binds
+loopback, which is the intended dev shape. A **public**
 bind refuses to boot unless auth is configured (`KSOR_SSO_URL` +
 `KSOR_MCP_RESOURCE_URL` + `KSOR_JWT_ALLOWED_AUDIENCES`, making it an OAuth
 Resource Server) OR you deliberately set `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1`.
@@ -185,12 +234,47 @@ Two things worth being deliberate about:
 - **Set `KSOR_SSO_ISSUER` when your SSO stamps a stable `iss`.** Audience is
   always enforced against `KSOR_JWT_ALLOWED_AUDIENCES`; naming the issuer adds
   one more check for the cost of one variable.
+- **Set `KSOR_JWKS_URL` unless your SSO is Better Auth.** The signing keys are
+  fetched from `<KSOR_SSO_URL>/api/auth/jwks` by default, which is Better
+  Auth's layout. Auth0, Okta, Entra, Keycloak and Cognito publish theirs
+  elsewhere, and a wrong JWKS URL fails as a transient fetch error — the door
+  boots clean and every request 503s with nothing naming the cause.
+
+## Withdrawing a document — `ksor takedown`
+
+A takedown is the one governance act that must reach EVERY surface at once.
+It needs the database (the denial is a row, not a file), so it belongs to the
+served rung.
+
+```sh
+pnpm exec ksor takedown --instance instance.md <stable-id> --reason "legal request 2026-08"
+pnpm exec ksor takedown --instance instance.md <stable-id> --reason "..." --subtree
+pnpm exec ksor takedown --instance instance.md --list      # what is currently denied
+pnpm exec ksor takedown --instance instance.md --ledger    # who denied what, when
+pnpm exec ksor takedown --instance instance.md --revoke <stable-id>
+```
+
+The stable id is what a search result reports as `provenance.stable_id` — for
+most documents that is `knowledge/<path-without-.md>`. `--subtree` withdraws a
+section and everything beneath it, including documents added later.
+`--actor NAME` names who performed the act in the ledger; it defaults to the
+operating user.
+
+**The MCP door stops serving it immediately. The SITE stops at its next
+build** — the site reads a file, not the database, and `pnpm build` refreshes
+that file for you (`pnpm export-denylist`). So after a takedown, rebuild and
+redeploy the site, or the human surface keeps publishing what the agent
+surface already refuses.
 
 ## Publishing
 
 `pnpm build` emits a fully static site (`system/site/out/`) deployable to
 any host — Vercel reads the shipped `vercel.json` (deploy from the repo
 ROOT, never `system/site/`), and every other host just serves the folder.
+Once `instance.md` declares a `database:`, `pnpm build` needs `KSOR_DB_URL` as
+well: it runs `pnpm export-denylist` first, which asks the database what has
+been withdrawn and writes `.ksor-denylist.json`. Without the DSN the build
+refuses rather than publish a document someone took down.
 `KSOR_BASE_PATH=/repo pnpm build` targets sub-path hosting. With
 `audiences:` declared, plain `pnpm build` is always the public tier;
 `KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier that belongs
@@ -217,8 +301,12 @@ Details in README → Deploying.
 - `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
-  it off and the document takes `default_visibility`. The key does nothing
-  until `instance.md` declares `audiences:`; once it does, `pnpm check`
+  it off and the document takes `default_visibility`. Using the key WITHOUT
+  an `audiences:` block is refused on both surfaces — `pnpm build` stops with
+  `ksor-visibility-without-audiences` and `pnpm serve` refuses to boot —
+  because a document marked restricted while nothing enforces it is the one
+  shape where the frontmatter is the only trace of a restriction that is not
+  happening. Once `audiences:` is declared, `pnpm check`
   refuses any link or `superseded_by:` pointing from a wider audience at a
   narrower one — the leak no single build can catch, because the build that
   publishes the link has already dropped its target.