@panaversity/ksor 0.0.34 → 0.0.36

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @panaversity/ksor
 
+## 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
+
+- 0fc6bce: Name the reader on the website
+
+  The scaffolded site can now sign a reader in and show who they are in the
+  navbar. It is off until three variables are set — the control does not render at
+  all without them, which stays the default.
+
+  The flow is OAuth 2.0 Authorization Code with PKCE against a public client, with
+  no secret anywhere in a build that ships to browsers. Endpoints are discovered
+  (RFC 8414, then OIDC), so no vendor is named in the code or in configuration;
+  verified end to end against Auth0 and against a Better Auth deployment. The
+  session lives in `sessionStorage` for the tab, and no refresh token is requested
+  or stored — a token that unlocks nothing on this site should not outlive the
+  visit.
+
+  What it does NOT do is restrict reading, and the documentation leads with that.
+  The site is a static export: every published document is a file the host serves
+  to whoever asks, so keeping people out is still the origin gate or a per-audience
+  build, both unchanged. This names an already-authenticated reader; it is not a
+  step toward access control, and treating it as one would be the mistake the
+  "Keeping people out of the site" section exists to prevent.
+
+  Also fixes a real gap it exposed: the site build never read the repository-root
+  `.env`, so following the scaffold's own instructions would have set variables
+  that silently never reached the bundle.
+
+- 4b431b2: Trim the shell-retirement revision in AGENTS.md from 222 words to 129, keeping
+  what an agent must act on and moving the reasoning to the commit that carried
+  it.
+
+  Working rule 6 requires a reversed decision to keep its entry and gain a
+  revision note, so removing it is not available — and it is not irrelevant
+  either: without it an agent looks for a deleted directory with no explanation,
+  or restores two-shell assertions thinking they were lost by accident, or reads
+  decision 9, sees no obstacle, and treats dropping `output: "export"` as
+  unblocked. That last one is the reason it stays.
+
+  But coding principle 1 applies to this file too — context is liability, and
+  AGENTS.md loads every session. The narrative half was 90 words explaining why
+  the proof had been valuable, which the commit already records.
+
+  Also documents the thing that was missing entirely: **how to keep people out of
+  the site.** The door's auth had four recipes; the site had nothing, and the
+  most common requirement — "everyone signs in before reading anything" — is also
+  the easiest, needs no ksor change, and was written down nowhere.
+
+  Three shapes, separated because they had been muddled: a host-level gate in
+  front of the origin (protects every byte, holds against `curl`, and makes a
+  site sign-in button redundant rather than complementary); per-audience builds
+  for a restricted subset (enforcement by absence, already built); and the
+  per-request case, which a static export cannot express and which issue #130
+  records rather than implements. Plus what does not work — hiding rendered
+  content behind a browser check, which presents rather than protects.
+
+  The per-request case gets three answers rather than a deferral: **read through
+  the door** (already applies audience scope per request and logs an actor per
+  read — per-person governance with an audit trail a static site cannot have),
+  **split the record** (content needing per-person confidentiality inside one tier
+  usually belongs in its own record), or **fork the site**, which an adopter owns
+  outright under decision 4.
+
+  The fork is offered with what it costs stated: ksor's guarantee is enforcement
+  by ABSENCE, asserted against a positive control; a request-time filter is a
+  different guarantee and becomes the adopter's to test. A filter that is bypassed
+  serves the document; an absent file cannot be.
+
 ## 0.0.34
 
 ### Patch Changes

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/authorization.md

@@ -32,8 +32,11 @@ Read this before spending an afternoon on a provider's console.
 **It protects the MCP door, not the website.** Everything on this page is a
 bearer token on `POST /mcp`. Your static site is a separate surface, served by
 whatever hosts it, and configuring auth here leaves it exactly as public as it
-was. If people must not read the record at all, the site needs its own access
-control — or must not be published.
+was. Keeping people out of the SITE is a different mechanism and is not on this
+page — see "Keeping people out of the site" in
+[deploying.md](./deploying.md), which covers the three shapes: a host-level gate
+in front of everything, per-audience builds for a restricted subset, and why the
+per-request case needs a decision first.
 
 **It is one gate, not per-user rules.** The door checks that a token was signed
 by the issuer you named and audienced at this record. It reads no scopes, no

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.
 
@@ -246,6 +251,148 @@ a row) and reaches the site at its next build (it reads a file), so a site built
 without the DSN would keep publishing what the door already refuses. Set
 `KSOR_DB_URL` on the site build as well as on the door.
 
+## Keeping people out of the site
+
+The door has auth ([authorization.md](./authorization.md)). The **site** is
+static files, so it has none — and the way to protect it is not to add code, it
+is to put something in front of it.
+
+Three requirements, three different answers. Pick the row you actually have.
+
+### "Everyone must sign in before reading anything"
+
+**Put a gate in front of the origin.** Nothing in ksor changes, and it protects
+every byte — HTML, `llms.txt`, images, the search index — because the request
+never reaches the files.
+
+| host          | what to turn on                                                                                      |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| Vercel        | Deployment Protection (password, or SSO on paid plans)                                               |
+| Cloudflare    | Cloudflare Access in front of the deployment                                                         |
+| anything else | an authenticating reverse proxy — nginx with `auth_request`, oauth2-proxy, Caddy with `forward_auth` |
+
+This is the strongest gate available to a static site, and the only one that
+holds against `curl`. It is coarse — whole deployment, all or nothing — which is
+exactly right when the answer is "this record is internal".
+
+**A sign-in button on the site is not an alternative to this.** The gate has
+already authenticated the reader before a page renders; a second login inside it
+would ask the same person to sign in twice, and on its own would protect
+nothing.
+
+### "Some documents are restricted, most are not"
+
+**Build per audience.** `KSOR_AUDIENCE=<tier> pnpm build` stages only what that
+tier may see, so restricted documents are **never written into the artifact** —
+enforcement by absence, which is the only kind a static host can honour. Publish
+the public artifact openly and the wider one behind the gate above.
+
+Plain `pnpm build` is always the public tier, so the safe thing is the default.
+
+### "Different readers see different documents, decided per request"
+
+Two supported answers, and a third that is yours.
+
+**Read through the door instead.** This is the one ksor is built for. The MCP
+surface already applies the audience scope **per request** and writes a
+`retrieval_log` row carrying the actor for every read — per-person governance
+with an audit trail, which a static site cannot have at any price. If the
+requirement is "who read what, and were they allowed to", that is the door, not
+the website.
+
+**Or split the record.** Content needing per-person confidentiality inside one
+tier is usually content that belongs in its own record, with its own gate. That
+is what the audience model and the second-record design anticipate.
+
+**Or fork the site — you already own it.** `system/site` is yours outright
+(decision 4). Nothing stops you removing `output: "export"` and filtering per
+request in your own repository. ksor's contract is unaffected; this is a
+directory you own, changed the way you want it.
+
+What you take on if you do:
+
+> ksor's guarantee is **enforcement by absence** — a restricted document is
+> never written into the artifact, and a conformance suite asserts that against
+> a positive control that proves the check is not blind. A request-time filter
+> is a **different** guarantee, and it becomes yours to test, because those
+> suites will no longer be testing it for you. A filter that is bypassed serves
+> the document; an absent file cannot be.
+
+That is the whole trade. It is a reasonable thing to do with your eyes open, and
+a bad thing to drift into because a login button suggested it.
+
+### What does NOT work
+
+**Hiding rendered content behind a signed-in check in the browser.** If the page
+was built with the content in it, the content is in the response before any
+JavaScript runs — `curl` and every crawler see it. A component that blurs or
+collapses it is presenting, not protecting. If you build one, say so in its own
+comment, or the next reader will take it for a gate.
+
+## Naming the reader — the sign-in control
+
+The site ships an optional sign-in control. Read the section above before you
+turn it on, because the one thing it does not do is the thing its name suggests.
+
+**What it does:** signs the reader in against your authorization server and puts
+their name in the navbar. That is the whole feature.
+
+**What it does not do:** restrict anything. The site is a static export — every
+published document is a file the host hands to whoever asks, and no amount of
+browser JavaScript changes that. If the requirement is "keep people out", the
+answer is the origin gate above, and the sign-in control is not a step toward it.
+
+So the honest use is a record already behind a gate, where the reader is
+authenticated but anonymous to the page, and you want the navbar to say who they
+are and offer a way out. That is worth having. It is not access control.
+
+### Turning it on
+
+Register a **public** client — PKCE, no secret — at the same authorization
+server the door names in `KSOR_SSO_URL`, then set three variables in the
+repository-root `.env`:
+
+```sh
+NEXT_PUBLIC_KSOR_SSO_URL=https://your-sso.example.com
+NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID=your-client-id
+NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI=https://your-site.example.com/auth/callback
+```
+
+All three or none: with any of them missing the control does not render, which
+is the default and is not an error.
+
+They are `NEXT_PUBLIC_`, so they are **inlined at build time**. Set them before
+`pnpm build`; setting them on a running site changes nothing. This also means
+they are public — which is correct, because a public client has nothing secret
+to leak, and it is the reason none of these is a secret.
+
+Two things to get exactly right at the provider:
+
+- **The redirect URI must match byte for byte**, including the scheme and any
+  trailing slash. This is the failure everyone hits first, and providers report
+  it as a generic callback mismatch.
+- **Add the site's origin to the allowed web origins** (Auth0 calls it that;
+  others call it CORS). The token exchange is a browser `fetch`, so a missing
+  origin fails as CORS, not as auth.
+
+For local work, both values are `http://localhost:3000` — and the callback is
+`http://localhost:3000/auth/callback`.
+
+Endpoints are **discovered**, not configured: the control reads
+`/.well-known/oauth-authorization-server`, then OIDC discovery. Any provider
+publishing either one works, which is why there is no vendor setting here.
+Verified against Auth0 and against a Better Auth deployment.
+
+### What it stores, and for how long
+
+The session lives in `sessionStorage` — this tab, until it closes. No refresh
+token is requested and none is stored.
+
+That is deliberate, and it is a smaller footprint than the obvious alternative.
+A token that unlocks nothing on this site should not outlive the visit; the
+blast radius should match the benefit. If you need a longer session, you need
+the gate, not a longer-lived token in a browser.
+
 ## Authorization, or the deliberate absence of it
 
 `ksor serve` **refuses to boot unauthenticated on a public bind.** There is no

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.34",
+  "version": "0.0.36",
   "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
@@ -233,6 +276,13 @@ 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.
 
+The site can also show a **sign-in control** that names the reader in the
+navbar. It is off until you set three variables (see `.env.example`), and it
+names people rather than keeping them out — a static export cannot gate itself,
+so it is worth having on a record already behind one of the answers above, and
+is not a substitute for them. Setup and the honest limits:
+`node_modules/@panaversity/ksor/docs/deploying.md`.
+
 ## Ownership
 
 Everything here is yours. The scaffold was generated by

package/templates/scaffold/env.example

@@ -41,6 +41,23 @@ GEMINI_API_KEY=
 #   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
 KSOR_AUTH=disabled-local
 
+# ── Sign-in on the WEBSITE (optional) ───────────────────────────────────────
+# Names the reader in the navbar. It does NOT restrict reading: the site is a
+# static export, so every published document is a file the host serves to
+# whoever asks. To actually keep people out, see docs/deploying.md →
+# "Keeping people out of the site".
+#
+# All three are required together, and are inlined at BUILD time — set them
+# before `pnpm build`, not on the running site. Leave them unset and the
+# sign-in control does not render at all.
+#
+# The issuer is the same authorization server the door names in KSOR_SSO_URL.
+# Register a PUBLIC client (PKCE, no secret) whose redirect list contains the
+# callback URL below, written out literally.
+# NEXT_PUBLIC_KSOR_SSO_URL=https://your-sso.example.com
+# NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID=
+# NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI=https://your-site.example.com/auth/callback
+
 # ── Production knobs ────────────────────────────────────────────────────────
 # Unset is fine for a local run; each one matters once this serves for real.
 

package/templates/scaffold/system/site/app/auth/callback/page.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+/**
+ * Where the issuer sends the reader back.
+ *
+ * A PAGE, not a route handler. Under `output: "export"` a route handler cannot
+ * share a segment with a page, and more to the point there is no server to run
+ * one — the whole exchange happens in the browser, which is what lets a static
+ * site be an OAuth client at all.
+ */
+
+import { useEffect, useState } from "react";
+
+import { completeSignIn } from "@/lib/auth/flow";
+
+export default function CallbackPage(): React.ReactElement {
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const result = await completeSignIn(new URLSearchParams(window.location.search));
+      if (cancelled) return;
+      if (result.ok) {
+        // replace(), not assign(): the callback URL carries a spent
+        // authorization code, and leaving it in history means Back re-runs a
+        // flow that can only fail the second time.
+        window.location.replace(result.returnTo || "/");
+        return;
+      }
+      setError(result.reason);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <main className="mx-auto flex min-h-[60vh] max-w-md flex-col justify-center gap-3 px-6 text-center">
+      {error === null ? (
+        <p className="text-muted-foreground text-sm">Signing you in…</p>
+      ) : (
+        <>
+          <h1 className="text-lg font-semibold">Sign-in did not complete</h1>
+          <p className="text-muted-foreground text-sm">{error}</p>
+          <a className="text-sm underline underline-offset-4" href="/">
+            Back to the record
+          </a>
+        </>
+      )}
+    </main>
+  );
+}

package/templates/scaffold/system/site/components/sign-in.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+/**
+ * The navbar's sign-in control.
+ *
+ * Renders NOTHING when this record does not configure an issuer, so a scaffold
+ * that never sets one looks exactly as it does today — no placeholder, no
+ * disabled button, no hint that a feature is missing.
+ *
+ * What it does NOT do, said here because a sign-in control implies it: gate
+ * anything. The record's pages are static files the host serves to whoever
+ * asks. This names a reader; it does not decide what they may read.
+ */
+
+import { LogIn, LogOut, User } from "lucide-react";
+import { useEffect, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { authConfig } from "@/lib/auth/config";
+import { beginSignIn } from "@/lib/auth/flow";
+import { clearSession, readSession, type Session } from "@/lib/auth/session";
+
+export function SignIn(): React.ReactElement | null {
+  // Read AFTER mount, never during render: the session lives in sessionStorage,
+  // which the prerender has no access to. Reading it during render would make
+  // the server-rendered HTML and the first client render disagree, and React
+  // would blow the tree away with a hydration error.
+  const [session, setSession] = useState<Session | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    setSession(readSession());
+    setReady(true);
+  }, []);
+
+  if (authConfig === null) return null;
+
+  // Hold the space until mounted, so the navbar does not jump when the session
+  // resolves one frame later.
+  if (!ready) return <div className="h-8 w-20" aria-hidden />;
+
+  if (session === null) {
+    return (
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => {
+          void beginSignIn(window.location.pathname + window.location.search);
+        }}
+      >
+        <LogIn className="size-4" aria-hidden />
+        Sign in
+      </Button>
+    );
+  }
+
+  const label = session.name ?? session.email ?? "Signed in";
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="sm" aria-label={`Signed in as ${label}`}>
+          <User className="size-4" aria-hidden />
+          <span className="max-w-32 truncate">{label}</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-56">
+        <DropdownMenuLabel className="font-normal">
+          <span className="block truncate text-sm font-medium">{label}</span>
+          {session.email !== null && session.email !== label ? (
+            <span className="text-muted-foreground block truncate text-xs">{session.email}</span>
+          ) : null}
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          onClick={() => {
+            clearSession();
+            setSession(null);
+          }}
+        >
+          <LogOut className="size-4" aria-hidden />
+          Sign out
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/templates/scaffold/system/site/lib/auth/config.ts

@@ -0,0 +1,53 @@
+/**
+ * Whether this record's site offers sign-in, and against whom.
+ *
+ * Sign-in is ABSENT unless an issuer is configured. There is no half-state and
+ * no localhost fallback: a build with no issuer renders no control, and every
+ * function here returns null rather than guessing. That is the same posture the
+ * door takes (`ksor serve` refuses to boot rather than serve an undeclared
+ * auth state) expressed in the only way a static build can — by not existing.
+ *
+ * What this buys, stated once so nobody has to infer it: a VERIFIED reader
+ * identity, rather than a guessed one. It protects nothing the site publishes,
+ * and nothing in the browser calls the door yet — the flow requests `openid
+ * profile email` and no audience, so the access token it receives is the
+ * issuer's own and is not something the door would accept. Making the browser
+ * a door client means requesting this record's resource (RFC 8707) and is a
+ * new read surface, not a config change. Under `output: "export"` every document is a file the host serves
+ * to whoever asks; see `docs/deploying.md` → "Keeping people out of the site"
+ * for the three mechanisms that actually restrict reading.
+ */
+
+/** Values are inlined at BUILD time, so they must be NEXT_PUBLIC_ to exist. */
+export interface AuthConfig {
+  /** The authorization server's base URL — the same issuer the door names. */
+  readonly issuer: string;
+  /** This site's public OAuth client. No secret: PKCE proves the caller. */
+  readonly clientId: string;
+  /**
+   * The callback URL, written out LITERALLY.
+   *
+   * Never derived from `window.location`. A derivation has to guess whether the
+   * first path segment is a base path, and guesses wrong under `KSOR_BASE_PATH`
+   * — producing a `redirect_uri` the issuer rejects, with an error that names
+   * the URI and not the guess that built it.
+   */
+  readonly redirectUri: string;
+}
+
+const issuer = process.env["NEXT_PUBLIC_KSOR_SSO_URL"]?.trim() ?? "";
+const clientId = process.env["NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID"]?.trim() ?? "";
+const redirectUri = process.env["NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI"]?.trim() ?? "";
+
+/**
+ * The configuration, or null when this record does not offer sign-in.
+ *
+ * All three are required together. Two out of three is a misconfiguration that
+ * would otherwise surface as a failed redirect on the reader's screen, so it
+ * resolves to "no sign-in" and the control never renders.
+ */
+export const authConfig: AuthConfig | null =
+  issuer !== "" && clientId !== "" && redirectUri !== "" ? { issuer, clientId, redirectUri } : null;
+
+/** Where the record's own scopes end: identity only, and no refresh token. */
+export const OAUTH_SCOPE = "openid profile email";

package/templates/scaffold/system/site/lib/auth/discovery.ts

@@ -0,0 +1,53 @@
+/**
+ * Where the issuer's endpoints actually are — asked, never assumed.
+ *
+ * Hardcoding `/authorize` and `/oauth/token` would work against one vendor and
+ * fail against the next, which is the opposite of what this project claims.
+ * Every standards-compliant authorization server publishes a metadata document
+ * naming its own endpoints, and the door already reads exactly these two
+ * (`gateway-kit/src/jwks-discovery.ts`): RFC 8414 first, then OpenID Discovery.
+ *
+ * So the site and the door discover the same issuer the same way, and pointing
+ * both at a different provider stays an environment change.
+ */
+
+export interface Endpoints {
+  readonly authorization_endpoint: string;
+  readonly token_endpoint: string;
+}
+
+const PATHS = ["/.well-known/oauth-authorization-server", "/.well-known/openid-configuration"];
+
+function isEndpoints(value: unknown): value is Endpoints {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["authorization_endpoint"] === "string" && typeof v["token_endpoint"] === "string";
+}
+
+let cached: Endpoints | null = null;
+
+/**
+ * The issuer's endpoints, or null if it publishes no usable metadata.
+ *
+ * Memoized for the page's lifetime: the flow reads it twice (once to leave,
+ * once to come back) and those are separate page loads, so this saves a request
+ * only within one of them. Correctness does not depend on it.
+ */
+export async function discover(issuer: string): Promise<Endpoints | null> {
+  if (cached !== null) return cached;
+  const base = issuer.replace(/\/+$/, "");
+  for (const path of PATHS) {
+    try {
+      const response = await fetch(`${base}${path}`);
+      if (!response.ok) continue;
+      const document: unknown = await response.json();
+      if (isEndpoints(document)) {
+        cached = document;
+        return document;
+      }
+    } catch {
+      /* try the next document; a provider publishing neither is the null case */
+    }
+  }
+  return null;
+}

package/templates/scaffold/system/site/lib/auth/flow.ts

@@ -0,0 +1,158 @@
+/**
+ * The two halves of an authorization-code flow, as plain functions.
+ *
+ * Everything is `fetch` and `window.location`. Nothing here needs a server on
+ * this origin, which is why a static export can do it at all.
+ */
+
+import { authConfig, OAUTH_SCOPE, type AuthConfig } from "./config";
+import { discover } from "./discovery";
+import { createPkcePair, createState } from "./pkce";
+import { writeSession, type Session } from "./session";
+
+/**
+ * The verifier and state, held across the redirect.
+ *
+ * `sessionStorage`, not a variable: the browser leaves this origin entirely and
+ * comes back to a fresh page load, so anything in memory is gone. It is also
+ * not `localStorage` — this is single-flow, single-tab state that should not
+ * outlive the tab that started it.
+ */
+const PENDING = "ksor.oauth.pending";
+
+interface Pending {
+  readonly verifier: string;
+  readonly state: string;
+  /** Where the reader was, so sign-in returns them there. */
+  readonly returnTo: string;
+}
+
+/** Send the reader to the issuer. Returns only if it could not start. */
+export async function beginSignIn(returnTo: string): Promise<void> {
+  const config: AuthConfig | null = authConfig;
+  if (config === null) return;
+
+  const { verifier, challenge } = await createPkcePair();
+  const state = createState();
+  const pending: Pending = { verifier, state, returnTo };
+  sessionStorage.setItem(PENDING, JSON.stringify(pending));
+
+  const endpoints = await discover(config.issuer);
+  if (endpoints === null) return;
+
+  const url = new URL(endpoints.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("scope", OAUTH_SCOPE);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  window.location.assign(url.toString());
+}
+
+export type CallbackResult =
+  | { readonly ok: true; readonly returnTo: string }
+  | { readonly ok: false; readonly reason: string };
+
+interface TokenResponse {
+  readonly access_token?: unknown;
+  readonly id_token?: unknown;
+  readonly expires_in?: unknown;
+}
+
+/** Claims this site reads. Everything else in the token is ignored. */
+interface IdClaims {
+  readonly sub?: unknown;
+  readonly name?: unknown;
+  readonly email?: unknown;
+}
+
+/** Decode a JWT payload WITHOUT verifying it. Read the caveat before using. */
+function decodeClaims(idToken: string): IdClaims | null {
+  try {
+    const payload = idToken.split(".")[1];
+    if (payload === undefined) return null;
+    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+    const parsed: unknown = JSON.parse(json);
+    return typeof parsed === "object" && parsed !== null ? (parsed as IdClaims) : null;
+  } catch {
+    return null;
+  }
+}
+
+const str = (value: unknown): string | null => (typeof value === "string" ? value : null);
+
+/**
+ * Redeem the code the issuer sent back, and store the session.
+ *
+ * The id_token's claims are decoded, NOT verified, and that is deliberate: they
+ * are used only to render a name in this browser's own navbar. A forged token
+ * would let a reader lie to themselves about their own display name and nothing
+ * else — no content is gated on it, and the ACCESS token is verified by the
+ * server that actually accepts it (the door checks signature, issuer and
+ * audience per request). Verifying here would mean shipping a JWKS client to
+ * defend against the reader's own devtools.
+ */
+export async function completeSignIn(params: URLSearchParams): Promise<CallbackResult> {
+  const config: AuthConfig | null = authConfig;
+  if (config === null) return { ok: false, reason: "This record does not offer sign-in." };
+
+  const issuerError = params.get("error");
+  if (issuerError !== null) {
+    return { ok: false, reason: params.get("error_description") ?? issuerError };
+  }
+
+  const raw = sessionStorage.getItem(PENDING);
+  sessionStorage.removeItem(PENDING);
+  if (raw === null) {
+    return { ok: false, reason: "This sign-in did not start here. Try again from the site." };
+  }
+  const pending = JSON.parse(raw) as Pending;
+
+  // CSRF: the state must be the one this browser generated. Checked before the
+  // code is sent anywhere, so a planted code is never redeemed.
+  if (params.get("state") !== pending.state) {
+    return { ok: false, reason: "Sign-in could not be verified. Try again." };
+  }
+  const code = params.get("code");
+  if (code === null) return { ok: false, reason: "The issuer returned no authorization code." };
+
+  // No `credentials: "include"`: a public PKCE client sends no cookies, and
+  // sending them is refused outright by browsers against a wildcard CORS origin.
+  const endpoints = await discover(config.issuer);
+  if (endpoints === null) {
+    return { ok: false, reason: "The authorization server published no metadata document." };
+  }
+
+  const response = await fetch(endpoints.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: config.redirectUri,
+      client_id: config.clientId,
+      code_verifier: pending.verifier,
+    }),
+  });
+  if (!response.ok) {
+    return { ok: false, reason: `The issuer refused the exchange (${response.status}).` };
+  }
+
+  const token = (await response.json()) as TokenResponse;
+  const accessToken = str(token.access_token);
+  if (accessToken === null) return { ok: false, reason: "The issuer returned no access token." };
+
+  const claims = typeof token.id_token === "string" ? decodeClaims(token.id_token) : null;
+  const lifetime = typeof token.expires_in === "number" ? token.expires_in : 3600;
+  const session: Session = {
+    subject: str(claims?.sub) ?? "unknown",
+    name: str(claims?.name),
+    email: str(claims?.email),
+    accessToken,
+    expiresAt: Date.now() + lifetime * 1000,
+  };
+  writeSession(session);
+  return { ok: true, returnTo: pending.returnTo };
+}

package/templates/scaffold/system/site/lib/auth/pkce.ts

@@ -0,0 +1,42 @@
+/**
+ * RFC 7636 (PKCE, S256) using the Web Crypto API — no dependency.
+ *
+ * PKCE is what lets a browser be an OAuth client with NO SECRET. The client
+ * generates a random verifier, sends only its SHA-256 hash to start the flow,
+ * and presents the verifier when redeeming the code. An attacker who steals the
+ * authorization code cannot redeem it without the verifier, which never left
+ * the browser that started the flow.
+ *
+ * That is the whole reason this site needs no server: there is nothing to keep
+ * secret, so there is nothing that must live somewhere the reader cannot see.
+ */
+
+/** Base64url without padding — RFC 7636 §4.2 requires exactly this alphabet. */
+function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function randomBase64url(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+export interface PkcePair {
+  readonly verifier: string;
+  readonly challenge: string;
+}
+
+/** A verifier and its S256 challenge. 32 bytes → 43 chars, the RFC's minimum. */
+export async function createPkcePair(): Promise<PkcePair> {
+  const verifier = randomBase64url(32);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+/** CSRF state, bound to this flow and checked when the issuer redirects back. */
+export function createState(): string {
+  return randomBase64url(16);
+}

package/templates/scaffold/system/site/lib/auth/session.ts

@@ -0,0 +1,81 @@
+/**
+ * The reader's identity, for as long as the tab is open.
+ *
+ * Storage is `sessionStorage`, deliberately, and it is the one decision here
+ * worth arguing about. The alternative — `localStorage` with long-lived tokens
+ * — is what the predecessor did and is what NOT to copy: a token readable by
+ * any script on the origin, surviving for days, for a feature that grants no
+ * access to anything on this site. The blast radius should match the benefit.
+ *
+ * So: per-tab, gone when the tab closes, and no refresh token is requested at
+ * all. Signing in again is one redirect through an issuer that already knows
+ * the reader; it is not worth holding a long-lived credential to avoid.
+ */
+
+const KEY = "ksor.session";
+
+export interface Session {
+  /** The `sub` claim — the issuer's stable identifier for this reader. */
+  readonly subject: string;
+  readonly name: string | null;
+  readonly email: string | null;
+  /**
+   * The issuer's access token. Held because a session without one is not a
+   * session — NOT because anything here calls an API with it yet. No audience
+   * is requested, so it is the issuer's own token and the door would refuse it.
+   */
+  readonly accessToken: string;
+  /** Epoch milliseconds. A session past this is treated as absent. */
+  readonly expiresAt: number;
+}
+
+function isSession(value: unknown): value is Session {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["subject"] === "string" &&
+    typeof v["accessToken"] === "string" &&
+    typeof v["expiresAt"] === "number" &&
+    (v["name"] === null || typeof v["name"] === "string") &&
+    (v["email"] === null || typeof v["email"] === "string")
+  );
+}
+
+/**
+ * The stored session, or null.
+ *
+ * Every failure returns null rather than throwing: storage can be unavailable
+ * (private windows, blocked site data), the value can be another version's
+ * shape, and none of those are worth breaking a page render over.
+ */
+export function readSession(): Session | null {
+  try {
+    const raw = sessionStorage.getItem(KEY);
+    if (raw === null) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (!isSession(parsed)) return null;
+    if (Date.now() >= parsed.expiresAt) {
+      sessionStorage.removeItem(KEY);
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSession(session: Session): void {
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(session));
+  } catch {
+    /* storage unavailable: the reader stays signed out, which is honest */
+  }
+}
+
+export function clearSession(): void {
+  try {
+    sessionStorage.removeItem(KEY);
+  } catch {
+    /* nothing to do — a session that cannot be read cannot be used */
+  }
+}

package/templates/scaffold/system/site/lib/layout.shared.tsx

@@ -1,4 +1,6 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+
+import { SignIn } from "@/components/sign-in";
 import { appTitle } from "./shared";
 
 export function baseOptions(): BaseLayoutProps {
@@ -13,5 +15,9 @@ export function baseOptions(): BaseLayoutProps {
         </span>
       ),
     },
+    // `secondary` puts it at the navbar's trailing edge, beside the theme
+    // toggle. SignIn renders null when no issuer is configured, so a record
+    // that does not offer sign-in shows nothing rather than an empty slot.
+    links: [{ type: "custom", secondary: true, children: <SignIn /> }],
   };
 }

package/templates/scaffold/system/site/next.config.mjs

@@ -1,4 +1,5 @@
 import { createMDX } from "fumadocs-mdx/next";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,6 +11,28 @@ const withMDX = createMDX();
 // resolved from this file's own location so it holds wherever the repo lands.
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
+// The record keeps ONE .env, at the repo root, because that is where `ksor`
+// reads it. This build runs in system/site, so Next would never see it — and an
+// adopter following the scaffold's own instructions would set NEXT_PUBLIC_*
+// variables that silently never reach the bundle (found live). Read the root
+// file here, and let a real environment variable win, which is the same
+// precedence the CLI states.
+function loadRootEnv() {
+  let contents;
+  try {
+    contents = readFileSync(path.join(repoRoot, ".env"), "utf8");
+  } catch {
+    return; // no .env is the normal case — only .env.example ships
+  }
+  for (const line of contents.split("\n")) {
+    const match = /^\s*(NEXT_PUBLIC_[A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+    if (match?.[1] !== undefined && process.env[match[1]] === undefined) {
+      process.env[match[1]] = (match[2] ?? "").trim().replace(/^["']|["']$/g, "");
+    }
+  }
+}
+loadRootEnv();
+
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,