@panaversity/ksor 0.0.0 → 0.0.2

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import { exitCodes, resolveCommand, verbs } from "./index.mjs";
+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 = `
+Knowledge System of Record: 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.
+
+Follow along: ${pkg.homepage}\n`;
+const usage = `ksor ${pkg.version} — Knowledge System of Record\n
+Usage: ksor <verb>
+
+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
+
+Exit codes: 1 refused · 2 designed but not implemented · 3 environment
+Docs: node_modules/${pkg.name}/docs · ${pkg.homepage}\n`;
+function main(args) {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(usage);
+		return 0;
+	}
+	if (args.includes("--version")) {
+		process.stdout.write(`${pkg.version}\n`);
+		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;
+	}
+	const heading = verb === null ? `ksor ${pkg.version} — the name is reserved; this is not a release.` : `ksor ${verb}: designed but not implemented in ${pkg.version}.`;
+	process.stdout.write(`${heading}\n${notice}`);
+	return exitCodes.notImplemented;
+}
+process.exitCode = main(process.argv.slice(2));
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,34 @@
+//#region src/index.d.ts
+/**
+ * Public entry point of @panaversity/ksor.
+ *
+ * Nothing here is a released capability: 0.x builds expose only the CLI
+ * contract, so that scripts and agents driving `ksor` can rely on stable,
+ * documented exit semantics before the verbs are implemented.
+ */
+/**
+ * Exit-code contract for the `ksor` CLI. 2 must never be read as a crash: it
+ * is the honest "this verb is designed but not implemented in this build".
+ */
+declare const exitCodes: {
+  /** The command was refused: bad input or a guarded operation. */
+  readonly refused: 1;
+  /** The verb exists in the design but is not implemented in this build. */
+  readonly notImplemented: 2;
+  /** The environment cannot run ksor (missing runtime requirement). */
+  readonly environment: 3;
+};
+type ExitCode = (typeof exitCodes)[keyof typeof exitCodes];
+/** The CLI vocabulary. Deliberately small; see the README. */
+declare const verbs: readonly ["init", "dev", "build", "serve"];
+type Verb = (typeof verbs)[number];
+interface ResolvedCommand {
+  /** The first non-flag token, or null when only flags (or nothing) appear. */
+  readonly word: string | null;
+  /** `word` when it is in the vocabulary, otherwise null. */
+  readonly verb: Verb | null;
+}
+/** Resolve the command word from CLI arguments (flags are skipped). */
+declare function resolveCommand(argv: readonly string[]): ResolvedCommand;
+//#endregion
+export { ExitCode, ResolvedCommand, Verb, exitCodes, resolveCommand, verbs };

package/dist/index.mjs

@@ -0,0 +1,37 @@
+//#region src/index.ts
+/**
+* Public entry point of @panaversity/ksor.
+*
+* Nothing here is a released capability: 0.x builds expose only the CLI
+* contract, so that scripts and agents driving `ksor` can rely on stable,
+* documented exit semantics before the verbs are implemented.
+*/
+/**
+* Exit-code contract for the `ksor` CLI. 2 must never be read as a crash: it
+* is the honest "this verb is designed but not implemented in this build".
+*/
+const exitCodes = {
+	/** The command was refused: bad input or a guarded operation. */
+	refused: 1,
+	/** The verb exists in the design but is not implemented in this build. */
+	notImplemented: 2,
+	/** The environment cannot run ksor (missing runtime requirement). */
+	environment: 3
+};
+/** The CLI vocabulary. Deliberately small; see the README. */
+const verbs = [
+	"init",
+	"dev",
+	"build",
+	"serve"
+];
+/** Resolve the command word from CLI arguments (flags are skipped). */
+function resolveCommand(argv) {
+	const word = argv.find((arg) => !arg.startsWith("-")) ?? null;
+	return {
+		word,
+		verb: word !== null && verbs.includes(word) ? word : null
+	};
+}
+//#endregion
+export { exitCodes, resolveCommand, verbs };

package/docs/index.md

@@ -0,0 +1,53 @@
+---
+title: ksor documentation
+status: draft
+---
+
+# ksor documentation
+
+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. The corpus grows with each implemented verb.
+
+## What exists in this build
+
+- **`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
+
+- [`docs/status.md`](https://github.com/panaversity/ksor/blob/main/docs/status.md)
+  in the repository is authoritative for implemented functionality.
+- The repository [`README`](https://github.com/panaversity/ksor#readme) is the
+  concept document, not a capability claim.

package/package.json

@@ -1,39 +1,68 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.0",
+  "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.",
-  "license": "Apache-2.0",
-  "author": "Panaversity",
-  "homepage": "https://github.com/panaversity/ksor#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/panaversity/ksor.git"
-  },
-  "bugs": {
-    "url": "https://github.com/panaversity/ksor/issues"
-  },
   "keywords": [
+    "abstention",
+    "citations",
+    "documentation",
+    "docusaurus",
+    "governance",
     "knowledge-system-of-record",
-    "system-of-record",
     "mcp",
     "model-context-protocol",
-    "governance",
     "provenance",
-    "citations",
-    "abstention",
-    "documentation",
-    "docusaurus"
+    "system-of-record"
   ],
+  "homepage": "https://github.com/panaversity/ksor#readme",
+  "bugs": {
+    "url": "https://github.com/panaversity/ksor/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Panaversity",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panaversity/ksor.git",
+    "directory": "packages/ksor"
+  },
   "bin": {
-    "ksor": "bin/ksor.js"
+    "ksor": "./dist/cli.mjs"
   },
   "files": [
-    "bin"
+    "dist",
+    "docs",
+    "templates",
+    "CHANGELOG.md",
+    "NOTICE"
   ],
-  "engines": {
-    "node": ">=20"
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "playwright": "^1.58.0",
+    "publint": "0.3.23",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "publint": "publint"
   }
-}
+}

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.