@panaversity/ksor 0.0.2 → 0.0.4

package/templates/scaffold/README.md

@@ -18,7 +18,32 @@ pnpm dev        # browse the knowledge at http://localhost:3000
 ```
 
 No pnpm? Run `npm install -g pnpm` — or `corepack enable pnpm` on Node
-versions that bundle corepack.
+versions that bundle corepack. The first `pnpm install` also fetches the
+`ksor` tool (pinned in `package.json`) and writes it into your lockfile —
+commit the updated lockfile.
+
+### Serving to agents
+
+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:
+
+```sh
+export KSOR_DB_URL='postgresql://…'   # the DSN var your instance.md names
+export GEMINI_API_KEY='…'             # the embedding provider key
+pnpm schema     # apply the database schema (once)
+pnpm grant      # authorize ingest for this corpus (once)
+pnpm ingest     # embed knowledge/ into a generation and activate it
+pnpm serve      # run the MCP server over the record
+```
+
+One setup step comes before this — adding the `database:`/`embedding:` blocks
+to `instance.md` — and there is more to know about the generation model and the
+fail-closed security posture. `AGENTS.md` → "Serving to agents" is the
+full runbook; your coding agent reads it first. `pnpm serve` binds loopback
+with auth off for local use; a public bind fails closed unless auth is
+configured. Any other operation is `pnpm exec ksor <verb>`.
 
 Then talk to your coding agent — `AGENTS.md` carries the working rules, and
 the agent kit in `.agents/skills/` knows how to interview you
@@ -34,7 +59,7 @@ 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). When the agent surface ships, this prose becomes its system prompt. |
+| `instance.md`                    | what this record is authoritative for; its `name:` is the identity every surface publishes (read at server/build start — restart `pnpm dev` after renaming). This prose IS the agent surface's system prompt — `ksor serve` wires it into the MCP server's instructions. |
 | `AGENTS.md`                      | the working contract every coding agent reads first — the rules for writing knowledge here.                                                                                                                                      |
 | `CLAUDE.md`                      | one line, pointing at `AGENTS.md`. Claude Code looks for this filename, not that one.                                                                                                                                            |
 | `.agents/skills/`                | the agent kit: `intake-interview` (define the record with you), `add-sources` (turn source material into governed documents), `format-checker` (the rules, as a program).                                                        |
@@ -43,7 +68,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.                                                                                                                            |
 | `.gitignore`                     | keeps build output, `node_modules/`, and `.env*` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the `pnpm dev` / `pnpm build` / `pnpm check` commands, and the pnpm version this project pins.                                                                                                                                   |
+| `package.json`                   | the `pnpm dev` / `pnpm build` / `pnpm check` / `pnpm schema` / `pnpm grant` / `pnpm ingest` / `pnpm serve` commands, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
 | `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.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
 
@@ -55,6 +80,33 @@ and how to fix it.
 Everything here is yours to change. The kit exists so that any coding agent can
 operate this project without being taught it first.
 
+## Deploying
+
+The built site is a folder of files — 2 MB of HTML, JS and CSS with zero
+host-specific dependencies. `pnpm build` writes it to `system/site/out/`,
+and anything that can serve files can serve it.
+
+- **Vercel** — connect the repository (or run `vercel`); the shipped
+  `vercel.json` answers the setup interview: deploy from the repo root
+  (never pin `system/site` as the root directory — the record lives
+  outside it), build with `pnpm build`, serve `system/site/out/`. If the
+  build image's pnpm predates the `packageManager` pin, set the
+  `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
+- **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.
+
+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
+"— 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
+build may be served is yours to enforce.
+
 ## Ownership
 
 Everything here is yours. The scaffold was generated by

package/templates/scaffold/gitignore

@@ -5,6 +5,9 @@ node_modules/
 system/site/.next/
 system/site/.source/
 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/
 *.tsbuildinfo
 
 # secrets never enter the record — system/ is their future home (serve)

package/templates/scaffold/instance.md

@@ -18,8 +18,9 @@ the single most important sentence in the project._
 
 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. When the agent surface ships, this prose becomes its system
-prompt — write it for a reader who must act on 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.
 
 Ask your coding agent to run the **intake interview** (it knows how — see
 `.agents/skills/intake-interview/`), answer its questions, and let it write

package/templates/scaffold/package.json

@@ -6,7 +6,14 @@
   "scripts": {
     "dev": "pnpm -C system/site dev",
     "build": "pnpm -C system/site build",
-    "check": "node .agents/skills/format-checker/check.mjs"
+    "check": "node .agents/skills/format-checker/check.mjs",
+    "schema": "ksor schema --instance instance.md --apply",
+    "grant": "ksor grant --instance instance.md",
+    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip",
+    "serve": "ksor serve"
+  },
+  "dependencies": {
+    "@panaversity/ksor": "KSOR-STAMP-VERSION"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/pnpm-workspace.yaml

@@ -8,12 +8,28 @@ packages:
 # `pnpm install` here never picks up a day-zero compromised release.
 minimumReleaseAge: 2880
 
+# The one exception is the tool that scaffolded this project: `ksor init` pins
+# `@panaversity/ksor` to the EXACT version the adopter deliberately ran, so the
+# quarantine (a defense against unknown third-party releases) must not block the
+# first install for 48 hours after every ksor release. Remove this line only if
+# you unpin the dependency.
+minimumReleaseAgeExclude:
+  - "@panaversity/ksor"
+
 # Dependency install scripts are denied by default. Flip an entry to true
-# only with a comment naming what breaks without it. esbuild and sharp are
-# reviewed and stay denied: both ship prebuilt platform binaries as
-# optionalDependencies, so their install scripts are download fallbacks the
-# site never needs — but pnpm 11 exits 1 on every install/dev until each is
-# explicitly decided. (found live: fresh-scaffold pnpm dev, 2026-08-18)
+# only with a comment naming what breaks without it. pnpm 11 exits 1 on every
+# install until each build script is explicitly decided (found live:
+# fresh-scaffold pnpm dev, 2026-08-18). All four below are reviewed and stay
+# denied:
+#   esbuild, sharp — prebuilt platform binaries ship as optionalDependencies,
+#     so their install scripts are download fallbacks the site never needs.
+#   @google/genai, protobufjs — pulled in by the `@panaversity/ksor` serve
+#     tool. genai's flagged script is its own dev `prepare` (nothing the
+#     published tarball needs built); protobufjs's postinstall is a
+#     version-compat warning, nothing built. (Same review as the root
+#     workspace, 2026-08-19; serve works with both denied — verified live.)
 allowBuilds:
   esbuild: false
   sharp: false
+  "@google/genai": false
+  protobufjs: false

package/templates/scaffold/system/site/app/(home)/page.tsx

@@ -3,7 +3,7 @@ import Link from "next/link";
 // The same file Next serves as the favicon (app/icon.png) — one mark, one
 // asset. Replace it with your own and the tab icon changes with the page.
 import mark from "@/app/icon.png";
-import { BuiltWith } from "@/components/built-with";
+import { FooterMark } from "@/components/footer-mark";
 import { appName, appTitle } from "@/lib/shared";
 import { basePath, getSortedPages } from "@/lib/source";
 
@@ -75,7 +75,7 @@ export default function HomePage() {
 
       <footer className="mx-auto w-full max-w-2xl px-6 pb-10">
         <p className="border-t border-fd-border pt-6 text-xs">
-          <BuiltWith />
+          <FooterMark />
         </p>
       </footer>
     </main>

package/templates/scaffold/system/site/app/docs/layout.tsx

@@ -1,7 +1,7 @@
 import { getSortedPageTree } from "@/lib/source";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import { baseOptions } from "@/lib/layout.shared";
-import { BuiltWith } from "@/components/built-with";
+import { FooterMark } from "@/components/footer-mark";
 
 export default function Layout({ children }: LayoutProps<"/docs">) {
   return (
@@ -13,7 +13,7 @@ export default function Layout({ children }: LayoutProps<"/docs">) {
       sidebar={{
         footer: (
           <p className="mt-3 text-xs">
-            <BuiltWith />
+            <FooterMark />
           </p>
         ),
       }}

package/templates/scaffold/system/site/components/footer-mark.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import { BuiltWith } from "@/components/built-with";
+import { audienceNotice } from "@/lib/audience";
+
+/**
+ * The foot of the site chrome: who built it, and — on any build below the
+ * public tier — which audience that build was for, so a screenshot of an
+ * internal site names itself and a page that escapes carries its own
+ * warning.
+ *
+ * The public build renders the attribution ALONE, exactly as a site with no
+ * audience model does: the one build with nothing to disclose must not even
+ * carry the shape of a disclosure.
+ */
+export function FooterMark(): ReactElement {
+  if (audienceNotice === null) return <BuiltWith />;
+  return (
+    <>
+      <BuiltWith /> &middot; <span className="text-fd-muted-foreground">{audienceNotice}</span>
+    </>
+  );
+}

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

@@ -0,0 +1,178 @@
+import { instanceFrontmatter } from "./shared";
+
+/**
+ * The audience model, declared in instance.md — the record says who its
+ * readers are, and the build enforces it:
+ *
+ *     audiences:
+ *       - public
+ *       - internal
+ *       - restricted
+ *     default_visibility: public
+ *
+ * Ordered least- to most-restricted, so "build the internal site" means
+ * "public and internal included" with no further configuration. A record
+ * that declares no audiences has no model and publishes every document —
+ * the behaviour of every instance written before this key existed.
+ */
+export interface AudienceModel {
+  /** Least- to most-restricted, `public` first. */
+  readonly audiences: readonly string[];
+  /** The tier of a document that declares no `visibility:`. */
+  readonly defaultVisibility: string;
+}
+
+function unquote(raw: string): string {
+  const trimmed = raw.trim();
+  return /^(['"])(.*)\1$/.exec(trimmed)?.[2] ?? trimmed;
+}
+
+/** Every refusal this feature makes: a slug a pipeline can match, then the remedy. */
+export function refuse(slug: string, what: string, why: string, fix: string): never {
+  // The slug leads, so a pipeline can match on it, and the three lines below
+  // it are the whole remedy — an operator never has to read this file.
+  throw new Error(`${slug}: ${what}\n  why: ${why}\n  fix: ${fix}`);
+}
+
+function readAudienceModel(): AudienceModel | null {
+  const block = instanceFrontmatter();
+  // Top-level key only: `^` under /m cannot match an indented child.
+  if (!/^audiences:/m.test(block)) return null;
+
+  // The grammar mirrors the checker's exactly — CRLF-tolerant, list items at
+  // ANY indent (YAML allows unindented block sequences), and a ` #` comment
+  // ends an unquoted entry (all three found live 2026-08-18: records the
+  // checker blessed either failed this build or silently lost a tier).
+  const stripComment = (value: string): string =>
+    /^["']/.test(value.trim()) ? value : value.replace(/\s+#.*$/, "");
+  // A line scanner, not a block regex: a blank line among the items or a
+  // comment on the key line broke the block capture and refused every build
+  // of a checker-green record (review finding, 2026-08-19).
+  const flow = /^audiences:[ \t]*\[(.*)\][ \t]*(?:#.*)?$/m.exec(block)?.[1];
+  let items: string[] = [];
+  if (flow !== undefined) {
+    items = flow.split(",");
+  } else {
+    const lines = block.split("\n");
+    const start = lines.findIndex((line) => /^audiences:[ \t]*(?:#.*)?$/.test(line));
+    if (start !== -1) {
+      for (const line of lines.slice(start + 1)) {
+        if (line.trim() === "") continue;
+        const item = /^[ \t]*-[ \t]+(.*)$/.exec(line);
+        if (item === null) break;
+        items.push(item[1] ?? "");
+      }
+    }
+  }
+  const audiences = items
+    .map(stripComment)
+    .map(unquote)
+    .filter((value) => value !== "");
+
+  // A declared-but-unreadable model must never read as "no model": that is
+  // the one parse failure that publishes the whole record.
+  if (audiences.length === 0) {
+    refuse(
+      "ksor-audiences-unreadable",
+      "instance.md declares `audiences:` but no audience could be read from it",
+      "an unreadable model reads as no model, and no model publishes every document — the one parse failure that leaks",
+      "write the audiences as a list, least-restricted first:\n    audiences:\n      - public\n      - internal",
+    );
+  }
+
+  // The staging never depends on the checker having run: a
+  // most-restrictive-first model would make plain `pnpm build` publish
+  // every restricted document with no label (review finding, 2026-08-18).
+  if (audiences[0] !== "public") {
+    refuse(
+      "ksor-audiences-misordered",
+      `audiences: must start with public (it starts with "${audiences[0]}")`,
+      "the list is ordered least- to most-restricted, and an unset KSOR_AUDIENCE builds the FIRST entry — any other first entry makes the default build the leak",
+      "reorder audiences: with public first",
+    );
+  }
+  if (new Set(audiences).size !== audiences.length) {
+    refuse(
+      "ksor-audiences-duplicate",
+      `audiences: declares a tier twice (${audiences.join(", ")})`,
+      "a duplicated tier has two positions in the ordering, and which one a build honours is undefined",
+      "remove the duplicate entry",
+    );
+  }
+  const defaultVisibility = unquote(
+    stripComment(/^default_visibility:[ \t]*(.*)$/m.exec(block)?.[1] ?? ""),
+  );
+  if (defaultVisibility === "") {
+    refuse(
+      "ksor-default-visibility-missing",
+      "instance.md declares `audiences:` without `default_visibility:`",
+      "there is no safe guess: assuming the widest tier leaks on the first document that forgets the key, assuming the narrowest hides the record",
+      `add the tier a document without a visibility: key belongs to, e.g. default_visibility: ${audiences[0]}`,
+    );
+  }
+  if (!audiences.includes(defaultVisibility)) {
+    refuse(
+      "ksor-default-visibility-undeclared",
+      `default_visibility: ${defaultVisibility} is not one of the declared audiences (${audiences.join(", ")})`,
+      "every document without a visibility: key belongs to this tier — a tier no build understands is a record no build can publish honestly",
+      `set default_visibility: to one of ${audiences.join(", ")}, or declare ${defaultVisibility} in audiences:`,
+    );
+  }
+
+  return { audiences, defaultVisibility };
+}
+
+/** The declared model, or null when this record declares none. */
+export const audienceModel: AudienceModel | null = readAudienceModel();
+
+function resolveBuildAudience(model: AudienceModel | null): string {
+  const requested = process.env.KSOR_AUDIENCE?.trim() ?? "";
+  if (model === null) {
+    if (requested !== "") {
+      refuse(
+        "ksor-audiences-not-declared",
+        `KSOR_AUDIENCE="${requested}" was requested, but instance.md declares no audiences`,
+        "this build would publish every document — a build that cannot filter must never look like one that did",
+        "declare the model in instance.md (audiences: + default_visibility:), or build without KSOR_AUDIENCE",
+      );
+    }
+    return "";
+  }
+  // Unset means the least-restricted tier: the only default that cannot leak,
+  // so `pnpm build` keeps publishing the public site out of the box.
+  if (requested === "") return model.audiences[0] as string;
+  if (!model.audiences.includes(requested)) {
+    refuse(
+      "ksor-audience-undeclared",
+      `KSOR_AUDIENCE="${requested}" is not an audience this record declares (${model.audiences.join(", ")})`,
+      "an unrecognized audience could only be honoured by publishing more than the record names — so it refuses instead of widening",
+      `build with one of ${model.audiences.join(", ")}, or add "${requested}" to instance.md's audiences: list`,
+    );
+  }
+  return requested;
+}
+
+/** The audience this build publishes for; "" when the record has no model. */
+export const buildAudience: string = resolveBuildAudience(audienceModel);
+
+/** Whether a document of this visibility belongs in THIS build. */
+export function visibleInBuild(visibility: string | null): boolean {
+  if (audienceModel === null) return true;
+  const value =
+    visibility === null || visibility === "" ? audienceModel.defaultVisibility : visibility;
+  const rank = audienceModel.audiences.indexOf(value);
+  // An undeclared visibility is refused, never published: a value no build
+  // understands is a typo, and a typo reads as a restriction.
+  if (rank === -1) return false;
+  return rank <= audienceModel.audiences.indexOf(buildAudience);
+}
+
+/**
+ * What a non-public build calls itself, in the site chrome — so a leaked
+ * screenshot of an internal site says which audience it was built for. The
+ * public build (the least-restricted tier) says nothing new.
+ */
+export const audienceNotice: string | null =
+  audienceModel === null || buildAudience === audienceModel.audiences[0]
+    ? null
+    : `${buildAudience} build — not for publication`;

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

@@ -20,12 +20,21 @@ function findInstance(start: string): string {
   );
 }
 
-function readInstanceName(): string {
+/**
+ * instance.md's frontmatter block — the configuration every surface reads
+ * (identity here, the audience model in lib/audience.ts). Only this block:
+ * body prose that looks like a key must never become configuration (review
+ * finding, 2026-08-18).
+ */
+export function instanceFrontmatter(): string {
   const text = readFileSync(findInstance(process.cwd()), "utf8");
-  // Only the frontmatter block: body prose mentioning `name:` must never
-  // become the site's identity (review finding, 2026-08-18).
-  const block = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
-  const raw = /^name:[ \t]*(.*)$/m.exec(block)?.[1]?.trim() ?? "";
+  // The checker's boundary exactly: BOM stripped, CRLF normalized, lax close.
+  const normalized = text.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
+  return /^---\n([\s\S]*?)\n---/.exec(normalized)?.[1] ?? "";
+}
+
+function readInstanceName(): string {
+  const raw = /^name:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1]?.trim() ?? "";
   const unquoted = /^(['"])(.*)\1$/.exec(raw);
   const name = unquoted?.[2] ?? raw;
   if (name === "") {