@panaversity/ksor 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @panaversity/ksor
 
+## 0.0.2
+
+### Patch Changes
+
+- 54a8f5f: `ksor init` is implemented — the first working verb. One command emits a
+  complete governed knowledge project: the record (`knowledge/`), a working
+  Fumadocs site (`system/site/`, static export, hot reload, static search,
+  llms.txt), the agent kit (AGENTS.md constitution, CLAUDE.md pointer,
+  `.agents/skills` with byte-identical `.claude/skills` copies, Gemini
+  pointer), adopter CI, and a dependency-free format checker (`pnpm check`).
+  Deterministic (every emitted byte ships as template content, lockfile
+  included), atomic, offline. Refusals carry stable slugs with working
+  remedies; environment failures exit 3 with slugs, never raw stack traces.
+
+  The scaffold ships branded and self-explaining: the KSoR mark as the
+  default favicon, a real landing page led by the instance name with the
+  first document derived (never hardcoded), a deletable "Built with KSoR"
+  maker's mark, a README that explains every emitted file, and a governed
+  `order:` frontmatter key that drives the sidebar, `llms.txt`, and the
+  home page from one declaration. The site shell is replaceable behind a
+  four-clause surface contract, proven by a second (Docusaurus) shell and
+  a shell-agnostic conformance suite in the ksor repository.
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -2,13 +2,31 @@
 
 **The Knowledge System of Record for humans and AI agents.**
 
-One governed source of markdown, published as a site people read and an MCP
-surface AI agents query — with citations, and an honest refusal when the corpus
-does not cover the question.
+Knowledge you can govern. Answers you can trace. Boundaries agents can
+respect. One governed source of markdown, published as a site people read
+and an MCP surface AI agents query — with citations, and an honest refusal
+when the corpus does not cover the question.
 
-> **`0.x` status:** this package currently reserves the name and states the
-> intent. The CLI answers honestly (`exit 2`, "designed but not implemented")
-> rather than pretending. [`docs/status.md`](https://github.com/panaversity/ksor/blob/main/docs/status.md)
+## Start
+
+```bash
+npx @panaversity/ksor init my-sor
+cd my-sor
+pnpm install
+pnpm dev        # the site, live at http://localhost:3000
+```
+
+One command emits a complete governed project: the record (`knowledge/`,
+plain CommonMark), a working documentation site with hot reload, offline
+search and `llms.txt`, adopter CI, a dependency-free format checker
+(`pnpm check`), and the instructions and skills any coding agent needs to
+operate it. Everything emitted is yours (the templates are MIT-0), the
+scaffold is deterministic and offline, and every refusal explains itself.
+
+> **`0.x` status:** `init` works; `dev`, `build` and `serve` are designed,
+> not implemented — each prints an honest notice and exits `2` (inside a
+> scaffolded project, `pnpm dev` / `pnpm build` cover local work).
+> [`docs/status.md`](https://github.com/panaversity/ksor/blob/main/docs/status.md)
 > and the released version number are authoritative for implemented
 > functionality.
 

package/dist/cli.mjs

@@ -1,6 +1,334 @@
 #!/usr/bin/env node
 import { exitCodes, resolveCommand, verbs } from "./index.mjs";
-import { readFileSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+//#region src/init/errors.ts
+/** The `code` of a Node system error, or null for anything that carries none. */
+function errnoCode(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const { code } = value;
+	return typeof code === "string" ? code : null;
+}
+/**
+* Failures the environment caused and the environment must fix — exit 3. Any
+* other throw is a ksor bug and keeps its stack rather than being dressed up
+* as the operator's fault.
+*/
+const ENVIRONMENT_CODES = /* @__PURE__ */ new Set([
+	"EACCES",
+	"EAGAIN",
+	"EBUSY",
+	"EDQUOT",
+	"EEXIST",
+	"EIO",
+	"EISDIR",
+	"ELOOP",
+	"EMFILE",
+	"ENAMETOOLONG",
+	"ENFILE",
+	"ENOENT",
+	"ENOSPC",
+	"ENOTDIR",
+	"ENOTEMPTY",
+	"EPERM",
+	"EROFS",
+	"EXDEV"
+]);
+function isEnvironmentError(value) {
+	const code = errnoCode(value);
+	return code !== null && ENVIRONMENT_CODES.has(code);
+}
+//#endregion
+//#region src/init/materialize.ts
+const EMITTED_NAMES = /* @__PURE__ */ new Map([["gitignore", ".gitignore"]]);
+const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+	".md",
+	".json",
+	".yaml",
+	".yml",
+	".ts",
+	".tsx",
+	".mjs",
+	".js",
+	".css",
+	".txt"
+]);
+function isTextFile(file) {
+	const base = path.basename(file);
+	if (base === "gitignore" || base === ".gitattributes") return true;
+	return TEXT_EXTENSIONS.has(path.extname(file));
+}
+/**
+* Copy the template tree into targetDir, applying the two stamps to text
+* files. Byte-determinism holds because templates are shipped bytes and the
+* stamps are pure string substitution.
+*
+* Every path it brings into existence is appended to `created`, parents before
+* children, so a caller that cannot rename-over (the `init .` form) can undo
+* a half-written tree in reverse order.
+*/
+function materialize(templateDir, targetDir, stamps, created = []) {
+	for (const entry of readdirSync(templateDir, { withFileTypes: true })) {
+		const from = path.join(templateDir, entry.name);
+		const to = path.join(targetDir, EMITTED_NAMES.get(entry.name) ?? entry.name);
+		if (entry.isDirectory()) {
+			if (!existsSync(to)) {
+				mkdirSync(to, { recursive: true });
+				created.push(to);
+			}
+			materialize(from, to, stamps, created);
+		} else if (isTextFile(from)) {
+			const text = readFileSync(from, "utf8").replaceAll("KSOR-STAMP-NAME", stamps.name).replaceAll("KSOR-STAMP-VERSION", stamps.version);
+			created.push(to);
+			writeFileSync(to, text);
+		} else {
+			created.push(to);
+			copyFileSync(from, to);
+		}
+	}
+	return created;
+}
+//#endregion
+//#region src/init/name.ts
+/** Project-name grammar (spec: `^[a-z0-9][a-z0-9-]{0,62}$`). */
+const NAME_GRAMMAR = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/**
+* Windows refuses these as directory names at the filesystem layer, whatever
+* the grammar says — and the spec runs its acceptance on windows-latest, so a
+* name accepted here must be a directory everywhere.
+*/
+const WINDOWS_RESERVED = /* @__PURE__ */ new Set([
+	"con",
+	"prn",
+	"aux",
+	"nul",
+	...Array.from({ length: 9 }, (_, index) => `com${index + 1}`),
+	...Array.from({ length: 9 }, (_, index) => `lpt${index + 1}`)
+]);
+function nameProblem(name) {
+	if (!NAME_GRAMMAR.test(name)) return "grammar";
+	if (WINDOWS_RESERVED.has(name)) return "windows-reserved";
+	return null;
+}
+function isValidName(name) {
+	return nameProblem(name) === null;
+}
+/** A best-effort valid slug from an invalid name, for the remedy line. */
+function suggestName(input) {
+	const slug = input.toLowerCase().replaceAll(/[^a-z0-9-]+/g, "-").replaceAll(/-+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, 63);
+	const usable = WINDOWS_RESERVED.has(slug) ? `${slug}-sor` : slug;
+	return isValidName(usable) ? usable : null;
+}
+//#endregion
+//#region src/init/walk.ts
+/** Nearest ancestor (inclusive) containing instance.md, or null. */
+function findAncestorProject(startDir) {
+	let dir = path.resolve(startDir);
+	for (;;) {
+		if (existsSync(path.join(dir, "instance.md"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/**
+* Nearest ancestor (exclusive of startDir) that is a pnpm workspace root
+* whose globs could swallow a nested project. Presence of the file is enough
+* to warn — glob analysis would promise precision the warning doesn't need.
+*/
+function findAncestorWorkspace(startDir) {
+	let dir = path.dirname(path.resolve(startDir));
+	for (;;) {
+		const manifest = path.join(dir, "pnpm-workspace.yaml");
+		if (existsSync(manifest)) return dir;
+		const pkg = path.join(dir, "package.json");
+		if (existsSync(pkg)) try {
+			if (JSON.parse(readFileSync(pkg, "utf8")).workspaces !== void 0) return dir;
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+//#endregion
+//#region src/init/index.ts
+const STAGE_PREFIX = ".ksor-init-";
+const GRAMMAR = "^[a-z0-9][a-z0-9-]{0,62}$";
+function fail(io, slug, lines, code) {
+	io.err(`error: ${slug}\n${lines.join("\n")}\n`);
+	return code;
+}
+function refuse(io, slug, lines) {
+	return fail(io, slug, lines, exitCodes.refused);
+}
+function refuseExists(io, word) {
+	return refuse(io, "exists", [`${word}/ already exists here.`, `pick another name, or remove ${word}/ first if it is disposable.`]);
+}
+function usage$1(io) {
+	io.out(`ksor init <name>   create a new Knowledge System of Record in ./<name>
+ksor init .        scaffold into the current directory (must be empty)
+
+Nothing was scaffolded: bare \`ksor init\` never writes — an unattended
+agent must not scaffold into an unknown directory by accident.
+The name must match ${GRAMMAR} (e.g. accounting-sor).\n`);
+	return 0;
+}
+/**
+* Spec: stale stage dirs are reported, never deleted — they may hold work.
+*
+* Reported only once this run has written its own tree: a note ahead of a
+* refusal would take the first stderr line, which belongs to the slug (found
+* live: 25 concurrent init pairs, where the loser's refusal was pushed to line
+* two by a note about the winner's live stage — 2026-08-18).
+*/
+function noteStaleStages(dir, io) {
+	for (const entry of readdirSync(dir).sort()) if (entry.startsWith(STAGE_PREFIX)) io.err(`note: found ${entry} — left by an interrupted init; inspect and remove it\n`);
+}
+/** Undo a half-written tree, children before parents. */
+function rollback(created) {
+	for (const target of [...created].reverse()) try {
+		rmSync(target, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+/** found live: git may be absent on minimal CI images — warn, never fail. */
+function gitInit(dir, io) {
+	if (spawnSync("git", ["rev-parse", "--git-dir"], {
+		cwd: dir,
+		stdio: "ignore"
+	}).status === 0) return;
+	const result = spawnSync("git", ["init", "--quiet"], {
+		cwd: dir,
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		],
+		encoding: "utf8"
+	});
+	if (result.error !== void 0) {
+		io.err(errnoCode(result.error) === "ENOENT" ? "note: git was not found — initialize the repository yourself when convenient\n" : `note: git init failed: ${result.error.message}\n`);
+		return;
+	}
+	if (result.status !== 0) {
+		const detail = (result.stderr ?? "").trim().split("\n")[0] || `git exited ${result.status}`;
+		io.err(`note: git init failed: ${detail}\n`);
+	}
+}
+function handoff(io, name, targetWasDot) {
+	const enter = targetWasDot ? "" : `  cd ${name}\n`;
+	io.out(`${name} is ready — your knowledge, your repo, yours outright.\n
+Next (or just tell your coding agent to take it from here):
+` + enter + "  pnpm install\n  pnpm dev        # the site, live at http://localhost:3000\n\nno pnpm? run: npm install -g pnpm — or `corepack enable pnpm` on Nodes that bundle corepack\n\nStart in knowledge/ — AGENTS.md carries the working rules.\n");
+}
+function init(args, cwd, io, env) {
+	const { version, templatesDir } = env;
+	if (!existsSync(templatesDir)) return fail(io, "broken-install", [`the ksor package is missing its templates: ${templatesDir}`, "reinstall it — `pnpm add -D @panaversity/ksor`, or `npm i -g @panaversity/ksor`."], exitCodes.environment);
+	const word = args[0] ?? null;
+	if (word === null) return usage$1(io);
+	if (args.length > 1) {
+		const joined = suggestName(args.join("-"));
+		return refuse(io, "bad-name", [`a project name is one word — ${args.length} were given: ${args.join(" ")}`, joined !== null ? `try: ksor init ${joined}` : `pick a short name matching ${GRAMMAR}: ksor init <name>.`]);
+	}
+	const isDot = word === ".";
+	const targetDir = isDot ? path.resolve(cwd) : path.resolve(cwd, word);
+	const name = isDot ? path.basename(targetDir) : word;
+	const problem = nameProblem(name);
+	if (problem !== null) {
+		const reason = problem === "windows-reserved" ? "Windows reserves it as a device name, so no directory can carry it there" : `it must match ${GRAMMAR} — lowercase letters, digits, hyphens`;
+		const suggestion = suggestName(name);
+		return refuse(io, "bad-name", isDot ? [`\`ksor init .\` takes the project name from this directory, and "${name}" cannot be one: ${reason}.`, suggestion !== null ? `run \`ksor init ${suggestion}\` from the parent directory, or rename this directory first.` : "rename this directory to lowercase letters, digits and hyphens, then re-run."] : [`"${name}" is not a usable project name: ${reason}.`, suggestion !== null ? `try: ksor init ${suggestion}` : "pick a short lowercase name."]);
+	}
+	const ancestorProject = findAncestorProject(isDot ? path.dirname(targetDir) : cwd);
+	if (ancestorProject !== null) return refuse(io, "nested", [`an existing ksor project owns this path: ${ancestorProject}`, "a corpus lives inside exactly one project — create the new one outside it."]);
+	if (isDot) {
+		const contents = existsSync(targetDir) ? readdirSync(targetDir).filter((e) => e !== ".git").sort() : [];
+		if (contents.length > 0) {
+			const listed = contents.slice(0, 5).join(", ") + (contents.length > 5 ? ", …" : "");
+			return refuse(io, "blocked", [`the current directory is not empty (${contents.length} entr${contents.length === 1 ? "y" : "ies"}: ${listed}).`, "run `ksor init .` in an empty directory, or `ksor init <name>` to create one."]);
+		}
+	} else if (existsSync(targetDir)) return refuseExists(io, word);
+	const ancestorWorkspace = findAncestorWorkspace(targetDir);
+	if (isDot) {
+		const created = [];
+		try {
+			materialize(templatesDir, targetDir, {
+				name,
+				version
+			}, created);
+		} catch (error) {
+			rollback(created);
+			throw error;
+		}
+	} else {
+		const stage = mkdtempSync(path.join(path.dirname(targetDir), STAGE_PREFIX));
+		try {
+			materialize(templatesDir, stage, {
+				name,
+				version
+			});
+		} catch (error) {
+			rmSync(stage, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+		try {
+			renameSync(stage, targetDir);
+		} catch (error) {
+			rmSync(stage, {
+				recursive: true,
+				force: true
+			});
+			const code = errnoCode(error);
+			if (code === "ENOTEMPTY" || code === "EEXIST" || code === "EPERM") return refuseExists(io, word);
+			throw error;
+		}
+	}
+	try {
+		if (ancestorWorkspace !== null) io.err(`warning: parent pnpm workspace at ${ancestorWorkspace} — its globs may enroll this\nproject's packages into the parent install. Exclude it there if builds misbehave.
+`);
+		if (!isDot) {
+			chmodSync(targetDir, statSync(path.join(targetDir, "knowledge")).mode & 511);
+			noteStaleStages(path.dirname(targetDir), io);
+		}
+		gitInit(targetDir, io);
+	} catch (error) {
+		if (!isEnvironmentError(error)) throw error;
+		const detail = error instanceof Error ? error.message : String(error);
+		io.err(`note: the project was created, but a follow-up step failed: ${detail}\n`);
+	}
+	handoff(io, name, isDot);
+	return 0;
+}
+function runInit(args, cwd, io, env) {
+	try {
+		return init(args, cwd, io, env);
+	} catch (error) {
+		if (!isEnvironmentError(error)) throw error;
+		return fail(io, "environment", [`the filesystem refused: ${error instanceof Error ? error.message : String(error)}`, "fix the environment and re-run — nothing was kept."], exitCodes.environment);
+	}
+}
+//#endregion
+//#region src/init/platform.ts
+/** The scaffold's toolchain requires it (decision 5, and `engines` here). */
+const MINIMUM_NODE_MAJOR = 24;
+/**
+* The remedy for a runtime ksor cannot run on, or null when it can. Pure so
+* the refusal is testable without installing a second Node.
+*/
+function unsupportedPlatform(nodeVersion) {
+	const version = nodeVersion.replace(/^v/, "");
+	const major = Number.parseInt(version, 10);
+	if (Number.isNaN(major) || major >= MINIMUM_NODE_MAJOR) return null;
+	return `ksor requires Node >= ${MINIMUM_NODE_MAJOR} — you are on v${version}; install a current Node and re-run.`;
+}
+//#endregion
 //#region src/cli.ts
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const notice = `
@@ -12,7 +340,7 @@ Follow along: ${pkg.homepage}\n`;
 const usage = `ksor ${pkg.version} — Knowledge System of Record\n
 Usage: ksor <verb>
 
-Verbs (designed; none implemented in ${pkg.version} — each exits 2 until it ships):\n  init    create a new KSoR project
+Verbs (init is implemented; the rest exit 2 until they ship):\n  init    create a new KSoR project (implemented)
   dev     run the human surface locally, watching
   build   validate and build both surfaces
   serve   expose the MCP agent surface
@@ -29,6 +357,20 @@ function main(args) {
 		return 0;
 	}
 	const { word, verb } = resolveCommand(args);
+	if (verb === "init") {
+		const remedy = unsupportedPlatform(process.versions.node);
+		if (remedy !== null) {
+			process.stderr.write(`error: unsupported-platform\n${remedy}\n`);
+			return exitCodes.environment;
+		}
+		return runInit(args.slice(args.indexOf("init") + 1), process.cwd(), {
+			out: (text) => process.stdout.write(text),
+			err: (text) => process.stderr.write(text)
+		}, {
+			version: pkg.version,
+			templatesDir: fileURLToPath(new URL("../templates/scaffold", import.meta.url))
+		});
+	}
 	if (word !== null && verb === null) {
 		process.stderr.write(`error: unknown-verb\n"${word}" is not a ksor verb. The vocabulary is: ${verbs.join(", ")}.\n`);
 		return exitCodes.refused;

package/docs/index.md

@@ -7,15 +7,43 @@ status: draft
 
 These docs ship inside the npm package (`node_modules/@panaversity/ksor/docs/`)
 so that coding agents read documentation matching the **installed** version
-instead of their training memory. That mechanism is live from 0.x on, even
-though the docs are still small — the corpus grows with each implemented verb.
+instead of their training memory. The corpus grows with each implemented verb.
 
 ## What exists in this build
 
-- The `ksor` CLI answers honestly: every designed verb (`init`, `dev`, `build`,
-  `serve`) reports "designed but not implemented" and exits `2`.
-- The package root exports the CLI contract: `exitCodes` (1 refused,
-  2 not implemented, 3 environment), `verbs`, and `resolveCommand`.
+- **`ksor init <name>` works.** One command emits a complete governed
+  project: the record (`knowledge/`, CommonMark only), a working
+  documentation site (`system/site/`, Next.js + Fumadocs — static export,
+  hot reload, static search, `llms.txt`), the agent kit (`AGENTS.md`,
+  a `CLAUDE.md` pointer, skills under `.agents/skills/` with byte-identical
+  `.claude/skills/` copies), adopter CI, and a dependency-free format
+  checker (`pnpm check`). `ksor init .` scaffolds into an empty directory
+  whose name passes the project-name grammar. Everything emitted belongs to
+  the adopter (templates are MIT-0).
+- Inside a scaffolded project, `pnpm install && pnpm dev` serves the record
+  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.
+- The remaining verbs (`dev`, `build`, `serve`) are 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
+  (`error: unsupported-platform`, `error: broken-install`,
+  `error: environment`).
+- The package root exports the CLI contract: `exitCodes`, `verbs`, and
+  `resolveCommand`.
+
+## For the agent operating a scaffolded project
+
+Read the scaffold's own `AGENTS.md` first — it is the working contract.
+Knowledge lives in `knowledge/` and never inside the site; frontmatter uses
+a closed key set (`title` + `status` required); `pnpm check` explains any
+violation and how to fix it. Sidebar order is the governed `order:`
+frontmatter key — never `meta.json` or `sidebar_position`. The site shell
+at `system/site/` is replaceable behind a four-clause surface contract; a
+Docusaurus conformance shell lives in the ksor repository under
+`workbench/shells/docusaurus/` with its swap recipe.
 
 ## Where truth lives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Knowledge System of Record — the authoritative, governed source of knowledge that humans and AI agents operate from. Name reserved; implementation in progress.",
   "keywords": [
     "abstention",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "docs",
+    "templates",
     "CHANGELOG.md",
     "NOTICE"
   ],
@@ -50,6 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
+    "playwright": "^1.58.0",
     "publint": "0.3.23",
     "tsdown": "0.22.14",
     "typescript": "7.0.2",

package/templates/LICENSE

@@ -0,0 +1,23 @@
+MIT No Attribution (MIT-0)
+
+Copyright 2026 Panaversity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+(This licence covers the scaffold templates in this directory — the files
+`ksor init` copies into an adopter's repository. Everything init emits is the
+adopter's, with no attribution or licence-propagation obligations. See
+AGENTS.md decision 10.)

package/templates/scaffold/.agents/skills/add-sources/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: add-sources
+description: Turn source material — documents, pages, pasted text, notes — into governed knowledge in knowledge/. Use when the owner shares material to add, says "add this to the knowledge base", or asks how to get existing content in. Not for editing the site.
+metadata:
+  version: "1.1.0"
+---
+
+# Add sources
+
+Converting material into the record is the everyday work of this project.
+The rules that make it _governed_ rather than merely stored:
+
+## Placement and shape
+
+- One document per topic, under `knowledge/`, path = identity: lowercase,
+  hyphens, a folder per natural grouping. Plain CommonMark `.md` — if the
+  source is rich (tables, images), tables become markdown tables and images
+  land _beside the document_ with relative links.
+- A folder's front page is `<folder>/index.md`; reading order is the
+  `order:` frontmatter key (ordered documents first, ascending; the rest
+  follow alphabetically) — never `meta.json` or `sidebar_position`.
+- Frontmatter: `title` and `status: draft` always; add `owner` (who stands
+  behind this content) and `provenance` (a list naming the actual sources —
+  file names, systems, people, dates) whenever the owner can tell you.
+  Precision matters: "Finance policy manual §4.2, 2025 edition" governs;
+  "internal docs" does not.
+
+## Fidelity rules
+
+- **Copy load-bearing values exactly** — numbers, thresholds, dates, names.
+  Never round, never paraphrase a figure.
+- **Two disagreeing sources stay two statements**, each with its provenance
+  — never smooth a conflict into one invented truth; flag it to the owner.
+- **Do not fill gaps from general knowledge.** If the source doesn't cover
+  something, the record doesn't either — that boundary is the product.
+- A document replacing an older one: mark the old one `status: superseded`
+  with `superseded_by:` pointing at the new — never delete it.
+
+## Finish every batch
+
+Run `pnpm check` and fix what it reports (its errors explain themselves),
+then show the owner the rendered result (`pnpm dev`) — the site is the
+review surface: you write, they check.

package/templates/scaffold/.agents/skills/format-checker/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: format-checker
+description: The record's format rules as a runnable check — frontmatter, filenames, links, structure. Use before handing off any change to knowledge/, when a check fails and you need to fix it, or when unsure whether a document is well-formed. Run with `pnpm check` (or node .agents/skills/format-checker/check.mjs).
+metadata:
+  version: "1.1.0"
+---
+
+# Format checker
+
+`pnpm check` runs `check.mjs` — dependency-free Node, owned by this repo. It
+enforces what AGENTS.md states in prose:
+
+- `knowledge/` holds CommonMark `.md` and images only — no `.mdx`, no
+  `meta.json`, no other file types — and it is never empty; a record with no
+  documents stands behind nothing.
+- Every document carries `title` + `status` (level-0 requirement); the full
+  allowed key set is closed; a `superseded` document names a `superseded_by`
+  that resolves to a document that exists.
+- Filenames are portable identities: lowercase, Windows-safe, no spaces, no
+  case-collisions, no `foo.md` + `foo/index.md` pairs, no parentheses.
+  (`.DS_Store` and friends are skipped, never reported.)
+- Relative links resolve and never leave `knowledge/` — inline,
+  `<angle-bracketed>`, and reference-style (`[text][label]` with its
+  `[label]: target` definition) alike. Links inside code spans and fenced
+  blocks are code, not links, and are ignored.
+- `instance.md` exists, is `format: 1`, and carries only the keys the format
+  defines — an unknown key is named, never ignored.
+- `CLAUDE.md` stays a one-line pointer; `.agents/skills/` and
+  `.claude/skills/` hold the same files byte for byte **in both directions**
+  (a file only one tree carries is a rule nobody reviewed); the site contains
+  no content files.
+
+Every failure prints what is wrong, why the rule exists, and the fix — obey
+the printed fix literally; if it doesn't resolve the problem, that is a bug
+worth reporting to ksor.
+
+When you edit any skill under `.agents/skills/`, re-copy it to
+`.claude/skills/` — the checker holds the two trees identical, and it now
+notices a file added on either side.