@panaversity/ksor 0.0.35 → 0.0.37

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @panaversity/ksor
 
+## 0.0.37
+
+### Patch Changes
+
+- 3eafb25: The package README states the KSoR architecture: one governed record — Markdown in the KSoR Profile of the Open Knowledge Format (OKF) — behind one governance boundary, projected through open standards.
+
+## 0.0.36
+
+### Patch Changes
+
+- 617dc46: The scaffold meets your package manager
+
+  `ksor init` now emits the scaffold for the manager that ran it: `npx
+@panaversity/ksor init` produces an npm project, `bunx` a bun one, `pnpm dlx`
+  (or anything unrecognized) the pnpm shape every scaffold got before. Node stays
+  the one prerequisite — nobody installs a second package manager to open their
+  own knowledge base (issue #28).
+
+  The whole scaffold speaks the detected manager: scripts, README, AGENTS.md, the
+  agent kit, the CLI's own handoff text. npm and bun scaffolds declare
+  `workspaces` in the manifest and ship no lockfile — the pinned CLI version
+  cannot be pre-resolved into one, so the first install writes it and the README
+  says to commit it. The install-script denial carries over (`.npmrc` with
+  `ignore-scripts=true` for npm; bun refuses dependency lifecycle scripts by
+  default). What npm and bun cannot offer is pnpm's 48-hour quarantine on newly
+  published dependency versions — the emitted scaffold discloses that instead of
+  staying silent about it.
+
+  Each manager's shape was proven end to end before shipping — install, `ksor`
+  bin resolution, format checker, full static site build — and CI now walks npm
+  and bun scaffolds on every change.
+
 ## 0.0.35
 
 ### Patch Changes

package/README.md

@@ -56,6 +56,12 @@ A quiz whose answers are guessable is refused by the build, and because ingest
 creates no node for an attachment, a quiz's answer key can never reach the
 agent surface at all.
 
+The architecture: **one governed record** — Markdown in the KSoR Profile of
+the Open Knowledge Format (OKF) — behind **one governance boundary**,
+projected through open standards: MCP for agents, `llms.txt` for AI
+discovery, OAuth/OIDC for identity, SLSA/Sigstore for publication integrity,
+OpenTelemetry for observability.
+
 Full concept, design goals, and project status:
 **<https://github.com/panaversity/ksor>**
 

package/dist/cli.mjs

@@ -6723,6 +6723,152 @@ function isEnvironmentError(value) {
 	return code !== null && ENVIRONMENT_CODES.has(code);
 }
 //#endregion
+//#region src/init/manager.ts
+/**
+* Which manager spawned this process, from `npm_config_user_agent`
+* (e.g. "pnpm/11.22.0 npm/? node/v24.5.0 darwin arm64"). The first token
+* names the manager; only managers we emit a scaffold for are recognized.
+*/
+function detectManager(userAgent) {
+	const head = (userAgent ?? "").split("/")[0]?.trim();
+	if (head === "npm") return "npm";
+	if (head === "bun") return "bun";
+	return "pnpm";
+}
+/** Template files that belong to exactly one manager's scaffold. */
+function isSkippedFor(templateName, manager) {
+	if (manager === "pnpm") return false;
+	return templateName === "pnpm-workspace.yaml" || templateName === "pnpm-lock.yaml";
+}
+/**
+* The workspace globs, shared by every manager. pnpm reads them from
+* pnpm-workspace.yaml; npm and bun read a `workspaces` field. One constant so
+* the two spellings cannot drift.
+*/
+const WORKSPACE_GLOBS = [
+	"system/site",
+	"system/gateways/*",
+	"system/packages/*"
+];
+/**
+* The root scripts, per manager. pnpm's are the template's own bytes; npm and
+* bun REPLACE the manager-specific bodies and inherit everything else.
+* npm: `--prefix` is npm's spelling of "run it over there".
+* bun: cd-chains — see the module comment for why not `--cwd`.
+*/
+const SCRIPT_BODIES = {
+	npm: {
+		dev: "npm --prefix system/site run dev",
+		build: "npm run export-denylist && npm --prefix system/site run build",
+		provision: "npm run schema && npm run grant",
+		refresh: "npm run ingest && npm run gc"
+	},
+	bun: {
+		dev: "cd system/site && bun run dev",
+		build: "bun run export-denylist && cd system/site && bun run build",
+		provision: "bun run schema && bun run grant",
+		refresh: "bun run ingest && bun run gc"
+	}
+};
+/**
+* Rewrite the scaffold's root package.json for the manager. Structured — a
+* JSON transform, never string surgery — because the manifest is the one
+* file where a half-applied spelling map would still parse and then lie.
+*/
+function transformManifest(source, manager) {
+	if (manager === "pnpm") return source;
+	const parsed = JSON.parse(source);
+	const { packageManager: _dropped, ...rest } = parsed;
+	const out = {
+		...rest,
+		scripts: {
+			...parsed.scripts,
+			...SCRIPT_BODIES[manager]
+		},
+		workspaces: [...WORKSPACE_GLOBS]
+	};
+	return `${JSON.stringify(out, null, 2)}\n`;
+}
+/**
+* Ordered prose translation, longest spelling first so `pnpm install` is
+* never half-eaten by a shorter rule. Applied to every emitted text file
+* except package.json (structured above). The conformance test asserts ZERO
+* surviving "pnpm" tokens outside the quarantine disclosure, so a template
+* edit that adds a spelling this map misses goes red instead of shipping an
+* instruction the adopter cannot run.
+*/
+const SCRIPT_NAMES = [
+	"dev",
+	"build",
+	"check",
+	"serve",
+	"provision",
+	"refresh",
+	"schema",
+	"grant",
+	"ingest",
+	"gc",
+	"export-denylist"
+];
+function spellings(manager) {
+	const run = (script) => manager === "npm" ? `npm run ${script}` : `bun run ${script}`;
+	const pairs = [
+		["pnpm install --no-frozen-lockfile", manager === "npm" ? "npm install" : "bun install"],
+		["pnpm install", manager === "npm" ? "npm install" : "bun install"],
+		["pnpm exec ksor", manager === "npm" ? "npx ksor" : "bunx ksor"],
+		["pnpm dlx", manager === "npm" ? "npx" : "bunx"],
+		["pnpm add -D", manager === "npm" ? "npm i -D" : "bun add -d"],
+		["pnpm -C system/site", manager === "npm" ? "npm --prefix system/site run" : "cd system/site && bun run"]
+	];
+	for (const script of SCRIPT_NAMES) pairs.push([`pnpm ${script}`, run(script)]);
+	return pairs;
+}
+/**
+* Manager-conditional blocks in markdown templates:
+*
+*   <!-- ksor:pm pnpm npm -->
+*   ...lines kept only for those managers...
+*   <!-- /ksor:pm -->
+*
+* The marker lines themselves never survive into any scaffold, so the pnpm
+* output stays exactly what an adopter always got.
+*/
+const BLOCK_OPEN = /^[ \t]*<!-- ksor:pm ([a-z ]+?) -->[ \t]*$/;
+const BLOCK_CLOSE = /^[ \t]*<!-- \/ksor:pm -->[ \t]*$/;
+function applyProse(text, manager) {
+	const lines = text.split("\n");
+	const kept = [];
+	let keeping = true;
+	let inBlock = false;
+	for (const line of lines) {
+		const open = BLOCK_OPEN.exec(line);
+		if (open !== null) {
+			inBlock = true;
+			keeping = open[1].split(/\s+/).includes(manager);
+			continue;
+		}
+		if (BLOCK_CLOSE.test(line)) {
+			inBlock = false;
+			keeping = true;
+			continue;
+		}
+		if (!inBlock || keeping) kept.push(line);
+	}
+	let out = kept.join("\n");
+	if (manager !== "pnpm") for (const [from, to] of spellings(manager)) out = out.replaceAll(from, to);
+	return out;
+}
+/**
+* Files a manager's scaffold gains beyond the template tree. npm's `.npmrc`
+* carries the denial half of the posture and DISCLOSES the missing half; bun
+* needs no file — denial is bun's own default — so its disclosure lives in
+* the README's lockfile note.
+*/
+function extraFiles(manager) {
+	if (manager !== "npm") return [];
+	return [[".npmrc", "# Dependency install scripts are denied — the same posture the pnpm\n# scaffold enforces per-package. Flip to false only with a comment naming\n# what breaks without it.\n#\n# What npm cannot give you is pnpm's 48-hour quarantine on newly\n# published dependency versions (minimumReleaseAge): under npm a routine\n# install can pick up a day-zero compromised release the day it ships.\n# That protection exists only under pnpm.\nignore-scripts=true\n"]];
+}
+//#endregion
 //#region src/init/materialize.ts
 const EMITTED_NAMES = /* @__PURE__ */ new Map([
 	["gitignore", ".gitignore"],
@@ -6755,9 +6901,14 @@ function isTextFile(file) {
 * 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 = []) {
+function materialize(templateDir, targetDir, stamps, manager = "pnpm", created = []) {
+	materializeTree(templateDir, targetDir, stamps, manager, created, true);
+	return created;
+}
+function materializeTree(templateDir, targetDir, stamps, manager, created, isRoot) {
 	for (const entry of readdirSync(templateDir, { withFileTypes: true })) {
 		if (entry.name === "node_modules") continue;
+		if (isRoot && isSkippedFor(entry.name, manager)) continue;
 		const from = path.join(templateDir, entry.name);
 		const to = path.join(targetDir, EMITTED_NAMES.get(entry.name) ?? entry.name);
 		if (entry.isDirectory()) {
@@ -6765,9 +6916,10 @@ function materialize(templateDir, targetDir, stamps, created = []) {
 				mkdirSync(to, { recursive: true });
 				created.push(to);
 			}
-			materialize(from, to, stamps, created);
+			materializeTree(from, to, stamps, manager, created, false);
 		} else if (isTextFile(from)) {
-			const text = readFileSync(from, "utf8").replaceAll("KSOR-STAMP-NAME", stamps.name).replaceAll("KSOR-STAMP-VERSION", stamps.version);
+			const stamped = readFileSync(from, "utf8").replaceAll("KSOR-STAMP-NAME", stamps.name).replaceAll("KSOR-STAMP-VERSION", stamps.version);
+			const text = isRoot && entry.name === "package.json" ? transformManifest(stamped, manager) : applyProse(stamped, manager);
 			created.push(to);
 			writeFileSync(to, text);
 		} else {
@@ -6775,6 +6927,14 @@ function materialize(templateDir, targetDir, stamps, created = []) {
 			copyFileSync(from, to);
 		}
 	}
+}
+/** Emit the files a manager's scaffold gains beyond the template tree. */
+function materializeExtras(targetDir, manager, created = []) {
+	for (const [name, content] of extraFiles(manager)) {
+		const to = path.join(targetDir, name);
+		created.push(to);
+		writeFileSync(to, content);
+	}
 	return created;
 }
 //#endregion
@@ -6906,14 +7066,22 @@ function gitInit(dir, io) {
 		io.err(`note: git init failed: ${detail}\n`);
 	}
 }
-function handoff(io, name, targetWasDot) {
+function handoff(io, name, targetWasDot, manager) {
 	const enter = targetWasDot ? "" : `  cd ${name}\n`;
+	const run = (script) => manager === "pnpm" ? `pnpm ${script}` : manager === "npm" ? `npm run ${script}` : `bun run ${script}`;
+	const install = manager === "pnpm" ? "pnpm install" : `${manager} install`;
+	const pnpmHint = manager === "pnpm" ? "no pnpm? run: npm install -g pnpm — or `corepack enable pnpm` on Nodes that bundle corepack\n\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\nThen, for the agent surface (needs Postgres and a provider key):\n  pnpm provision  # once: uncomment `database:` in instance.md, copy\n                  #   .env.example to .env, then apply the schema\n  pnpm refresh    # PUBLISH the record — ingest knowledge/ into a generation\n  pnpm serve      # the MCP server, over what you just published\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");
+` + enter + `  ${install}\n  ${run("dev").padEnd(15)} # the site, live at http://localhost:3000\n
+Then, for the agent surface (needs Postgres and a provider key):
+  ${run("provision").padEnd(15)} # once: uncomment \`database:\` in instance.md, copy\n                  #   .env.example to .env, then apply the schema
+  ${run("refresh").padEnd(15)} # PUBLISH the record — ingest knowledge/ into a generation\n  ${run("serve").padEnd(15)} # the MCP server, over what you just published\n
+` + pnpmHint + "Start in knowledge/ — AGENTS.md carries the working rules.\n");
 }
 function init(args, cwd, io, env) {
 	const { version, templatesDir } = env;
+	const manager = detectManager(env.userAgent);
 	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);
@@ -6946,7 +7114,8 @@ function init(args, cwd, io, env) {
 			materialize(templatesDir, targetDir, {
 				name,
 				version
-			}, created);
+			}, manager, created);
+			materializeExtras(targetDir, manager, created);
 		} catch (error) {
 			rollback(created);
 			throw error;
@@ -6957,7 +7126,8 @@ function init(args, cwd, io, env) {
 			materialize(templatesDir, stage, {
 				name,
 				version
-			});
+			}, manager);
+			materializeExtras(stage, manager);
 		} catch (error) {
 			rmSync(stage, {
 				recursive: true,
@@ -6990,7 +7160,7 @@ function init(args, cwd, io, env) {
 		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);
+	handoff(io, name, isDot, manager);
 	return 0;
 }
 function runInit(args, cwd, io, env) {
@@ -7080,7 +7250,8 @@ async function main(args) {
 			err: (text) => process.stderr.write(text)
 		}, {
 			version: pkg.version,
-			templatesDir: fileURLToPath(new URL("../templates/scaffold", import.meta.url))
+			templatesDir: fileURLToPath(new URL("../templates/scaffold", import.meta.url)),
+			userAgent: process.env.npm_config_user_agent
 		});
 	}
 	if (verb === "serve") {

package/docs/deploying.md

@@ -7,6 +7,11 @@ status: draft
 
 ## Before you start
 
+Commands on this page use the pnpm spelling (`pnpm build`, `pnpm serve`).
+Since 0.0.36, `ksor init` emits the scaffold for the manager that ran it —
+npm and bun included — and your scaffold's own README speaks that manager;
+translate accordingly (`npm run build`, `bun run build`).
+
 Four things must exist, and the order matters. Nothing below works without them,
 and three of the four are outside this page.
 

package/docs/index.md

@@ -19,7 +19,10 @@ instead of their training memory. The corpus grows with each implemented verb.
   `.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).
+  the adopter (templates are MIT-0). The scaffold is emitted for the package
+  manager that ran init — `npx …` yields an npm project, `bunx …` a bun one,
+  `pnpm dlx …` (or a bare `ksor`) the pnpm shape — so the commands below use
+  the pnpm spelling and your own scaffold's README speaks your manager.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "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",

package/templates/scaffold/AGENTS.md

@@ -112,7 +112,8 @@ Stand it up in this order (each step's errors explain how to fix themselves):
 
    `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
+   called `setup` because package managers claim that word for commands of
+   their own, which would shadow
    it — the step would print "No changes to the environment were made" and do
    nothing.)
 

package/templates/scaffold/README.md

@@ -18,8 +18,11 @@ pnpm install
 pnpm dev        # browse the knowledge at http://localhost:3000
 ```
 
+<!-- ksor:pm pnpm -->
 No pnpm? Run `npm install -g pnpm` — or `corepack enable pnpm` on Node
-versions that bundle corepack. The first `pnpm install` also fetches the
+versions that bundle corepack.
+<!-- /ksor:pm -->
+The first `pnpm install` also fetches the
 `ksor` tool (pinned in `package.json`) and writes it into your lockfile —
 commit the updated lockfile.
 
@@ -128,6 +131,7 @@ the record well-formed (`format-checker`, also `pnpm check`).
 
 ### A note on the lockfile
 
+<!-- ksor:pm pnpm -->
 The committed `pnpm-lock.yaml` covers the site. It cannot cover
 `@panaversity/ksor` itself, because the version pinned in `package.json` is
 stamped by the CLI that scaffolded this project and could not be resolved before
@@ -138,6 +142,34 @@ The deploy config already accounts for this (`vercel.json` installs with
 `--no-frozen-lockfile`), and the shipped `validate.yml` runs no install. If you
 add CI of your own, note that pnpm turns on `--frozen-lockfile` automatically
 whenever `CI` is set.
+<!-- /ksor:pm -->
+<!-- ksor:pm npm -->
+No lockfile ships with this scaffold: npm keeps ONE lock for the whole
+workspace, and the `@panaversity/ksor` version pinned in `package.json` was
+stamped by the CLI that scaffolded this project — it could not be resolved
+into a lock before it existed. Your FIRST `npm install` writes
+`package-lock.json`; run it before you push, and COMMIT the result — that
+lock is why two machines build the same site.
+
+One honest difference from the pnpm scaffold: pnpm quarantines newly
+published dependency versions for 48 hours (`minimumReleaseAge`), so a
+routine install never picks up a day-zero compromised release. npm has no
+equivalent — `.npmrc` here carries the install-script denial half of that
+posture, and this sentence is the disclosure of the half it cannot.
+<!-- /ksor:pm -->
+<!-- ksor:pm bun -->
+No lockfile ships with this scaffold: the `@panaversity/ksor` version pinned
+in `package.json` was stamped by the CLI that scaffolded this project — it
+could not be resolved into a lock before it existed. Your FIRST
+`bun install` writes `bun.lock`; run it before you push, and COMMIT the
+result — that lock is why two machines build the same site.
+
+One honest difference from the pnpm scaffold: pnpm quarantines newly
+published dependency versions for 48 hours (`minimumReleaseAge`), so a
+routine install never picks up a day-zero compromised release. bun has no
+equivalent (its default refusal of dependency install scripts covers the
+OTHER half of that posture), and this sentence is the disclosure.
+<!-- /ksor:pm -->
 
 ## The files, explained
 
@@ -158,9 +190,18 @@ different coding agent's way of finding the same working contract.
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
 | `.env.example`                   | the variables the served rung needs; copy to `.env` (gitignored) and fill in. |
 | `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the surface commands — `pnpm dev` (the site) and `pnpm provision` / `pnpm refresh` / `pnpm serve` (the agent surface: set up once, publish, then serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
+| `package.json`                   | the surface commands — `pnpm dev` (the site) and `pnpm provision` / `pnpm refresh` / `pnpm serve` (the agent surface: set up once, publish, then serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool and the workspace layout the manifest declares.                                                |
+<!-- ksor:pm pnpm -->
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
+<!-- /ksor:pm -->
+<!-- ksor:pm npm -->
+| `.npmrc`                         | dependency install scripts are denied; the comment inside discloses the one protection this scaffold lacks (a 48-hour quarantine on new releases). |
+| `package-lock.json`              | the exact dependency versions — written by your FIRST install; commit it, it is the reason two machines build the same site. |
+<!-- /ksor:pm -->
+<!-- ksor:pm bun -->
+| `bun.lock`                       | the exact dependency versions — written by your FIRST install; commit it, it is the reason two machines build the same site. |
+<!-- /ksor:pm -->
 
 `format-checker` deliberately contains a program, `check.mjs`, and not only
 prose: rules that are only written down cannot refuse anything. `pnpm check`
@@ -181,9 +222,11 @@ and anything that can serve files can serve it.
   (never pin `system/site` as the root directory — the record lives
   outside it), build with `pnpm build`, serve `system/site/out/`. It also
   declares the MCP **door** as a second service built from the shipped
-  `Dockerfile`, so `/mcp` and the site share one domain. If the
-  build image's pnpm predates the `packageManager` pin, set the
+  `Dockerfile`, so `/mcp` and the site share one domain.
+<!-- ksor:pm pnpm -->
+  If the build image's pnpm predates the `packageManager` pin, set the
   `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
+<!-- /ksor:pm -->
 **Once `instance.md` declares a `database:`, the BUILD needs the DSN too.**
 `pnpm build` first runs `pnpm export-denylist`, which asks the record's
 database what has been withdrawn (`ksor takedown --export`) and writes