@panaversity/ksor 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @panaversity/ksor
 
+## 0.0.5
+
+### Patch Changes
+
+- 995f002: feat: scaffolded projects ship a commented `.env.example` naming every
+  variable the agent surface needs — the DSN variable, the provider key, and
+  `KSOR_AUTH_DISABLED=1`, which a local run requires because `ksor serve` refuses
+  to boot unauthenticated. Copy it to `.env` and it is read automatically.
+
+  feat: standing up the agent surface is one command and one config block.
+  `ksor` now reads `./.env` automatically (Node-native, no dependency; a real
+  environment variable still wins), scaffolded projects get `pnpm up` —
+  schema → grant → ingest → serve — and `ksor schema --apply` is re-runnable
+  instead of failing on an already-provisioned database, so the whole sequence
+  is safe to repeat and doubles as the refresh after editing `knowledge/`.
+
+  fix: a scaffolded project deploys on the first try. The shipped `vercel.json`
+  pinned `--frozen-lockfile`, so an adopter's first Vercel import failed with
+  `ERR_PNPM_OUTDATED_LOCKFILE` — the scaffold declares a root dependency whose
+  stamped version the committed lockfile cannot record.
+
+  fix: the serve runbook no longer tells first-timers to declare
+  `retrieval.vector_floor: uncalibrated` before serving, which made every request
+  refuse until a floor was measured. Configuring the record needs one `database:`
+  block; the abstention gate is turned on deliberately, after it serves.
+
+- 4e84cdf: fix: `ksor serve` reports its real version to MCP clients. In 0.0.4 every
+  client saw `serverInfo.version` of `0.0.0`: the gateway read the version from
+  an environment variable at module scope, and the CLI's static import evaluated
+  that module before the CLI could set the variable. The version now travels as
+  an argument, and a test drives the bundled binary to assert it.
+
 ## 0.0.4
 
 ### Patch Changes

package/dist/cli.mjs

@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-DxfT2qs3.mjs
+//#region ../content-gateway/dist/main-MwJTMEjf.mjs
 /**
 * The pool checkout timed out — never retried: under saturation a retry is
 * a thundering herd aimed at the component already drowning.
@@ -2907,10 +2907,17 @@ async function runHttp(composition) {
 * released `ksor serve` announce 0.0.0 to every client (verified live by
 * probe; review 2026-08-20).
 */
-const GATEWAY_VERSION = process.env["KSOR_GATEWAY_VERSION"] || "0.0.0";
-async function main$1() {
+/**
+* Fallback only. The bundling CLI knows the PUBLISHED version and passes it to
+* `main(version)`; a module-level env read cannot work here, because this
+* module is evaluated by the CLI's static import BEFORE the CLI's own main()
+* body could set an env var (ESM evaluation order — the reason the previous
+* attempt at this shipped inert in 0.0.4).
+*/
+const GATEWAY_VERSION = "0.0.0";
+async function main$1(version = GATEWAY_VERSION) {
 	try {
-		await runHttp(await compose(path.resolve(process.env["KSOR_INSTANCE"] ?? "instance.md"), GATEWAY_VERSION));
+		await runHttp(await compose(path.resolve(process.env["KSOR_INSTANCE"] ?? "instance.md"), version));
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		console.error(`error: ${message}`);
@@ -3043,7 +3050,7 @@ async function runScopedIn(pool, gucs, op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-3cajARmF.mjs
+//#region ../content/dist/commands-D8yo1t8o.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -6148,6 +6155,14 @@ async function schemaCommand(args) {
 	if (instance === null) return fail$1(REFUSED, "schema: --apply needs --instance (the instance names the DSN env var; --dim alone names no database)");
 	const dsn = resolveDsn(instance);
 	if (typeof dsn === "number") return dsn;
+	const already = await withPool(dsn, async (pool) => {
+		const r = await pool.query("SELECT schema_version FROM schema_meta LIMIT 1").catch(() => null);
+		return r === null ? null : String(r.rows[0]?.schema_version ?? "");
+	});
+	if (already !== null) {
+		process.stdout.write(`schema: already applied (schema_meta ${already}) — nothing to do; drop the database to start over\n`);
+		return 0;
+	}
 	await withPool(dsn, (pool) => applySchema(pool, dim));
 	process.stdout.write(`schema: applied at dim ${dim} (database named by ${instance.dsnEnv})\n`);
 	return 0;
@@ -6363,7 +6378,7 @@ function isEnvironmentError(value) {
 }
 //#endregion
 //#region src/init/materialize.ts
-const EMITTED_NAMES = /* @__PURE__ */ new Map([["gitignore", ".gitignore"]]);
+const EMITTED_NAMES = /* @__PURE__ */ new Map([["gitignore", ".gitignore"], ["env.example", ".env.example"]]);
 const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
 	".md",
 	".json",
@@ -6674,7 +6689,20 @@ Verbs (dev and build exit 2 until they ship; the rest are implemented):\n  init
 
 Exit codes: 1 refused · 2 designed but not implemented · 3 environment
 Docs: node_modules/${pkg.name}/docs · ${pkg.homepage}\n`;
+/**
+* Load `./.env` when one exists, so the served rung's variables (the DSN the
+* instance names, the provider key) live in a file the adopter already
+* gitignores instead of being exported by hand into every shell. Node does
+* this natively — no dependency — and a REAL environment variable still wins
+* over the file, so CI and production overrides behave as they should.
+*/
+function loadDotEnv() {
+	try {
+		process.loadEnvFile();
+	} catch {}
+}
 async function main(args) {
+	loadDotEnv();
 	if (args.includes("--help") || args.includes("-h")) {
 		process.stdout.write(usage);
 		return 0;
@@ -6706,8 +6734,7 @@ async function main(args) {
 			return exitCodes.refused;
 		}
 		if (instance !== void 0) process.env["KSOR_INSTANCE"] = instance;
-		process.env["KSOR_GATEWAY_VERSION"] = pkg.version;
-		await main$1();
+		await main$1(pkg.version);
 		return 0;
 	}
 	if (verb === "ingest" || verb === "schema" || verb === "grant" || verb === "calibrate" || verb === "gc") return runContentCli(args.slice(args.indexOf(verb)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Knowledge System of Record — the authoritative, governed source of knowledge that humans and AI agents operate from. Name reserved; implementation in progress.",
   "keywords": [
     "abstention",

package/templates/scaffold/AGENTS.md

@@ -52,52 +52,90 @@ pnpm check       # the format checker — run before handing off any knowledge c
 with honest abstention. It is the climbed rung — not required for `pnpm dev`.
 Stand it up in this order (each step's errors explain how to fix themselves):
 
-1. **Configure `instance.md`.** Add the serve blocks to the frontmatter
-   (`pnpm check` accepts them; the kernel validates their values):
+1. **Configure `instance.md`.** One block is required — the name of the
+   environment variable holding your DSN (never the DSN itself):
 
    ```yaml
    database:
-     dsn_env: KSOR_DB_URL # the NAME of the env var holding the DSN — never the DSN itself
-   embedding:
-     provider: gemini # default; the seam, not the vendor, is the contract
-     model: gemini-embedding-001
-     dim: 1536 # ≤ 2000 for the pgvector HNSW index
-   retrieval:
-     vector_floor: uncalibrated # see step 6; `uncalibrated` REFUSES every serve until you paste a number
+     dsn_env: KSOR_DB_URL
    ```
 
-2. **Provision Postgres** with the `vector` extension (`CREATE EXTENSION vector`),
-   e.g. a Neon database. Export the DSN under the name `dsn_env` chose, plus the
-   provider key:
+   That is enough. `embedding:` is optional and already defaults to
+   `provider: gemini`, `model: gemini-embedding-001`, `dim: 1536`; write it out
+   only to pin the space explicitly or to change it — and note that model and
+   dim are the PERSISTED identity of the embedding space, so changing either
+   later means re-embedding the whole corpus. Keep `dim` at or below 2000: the
+   pgvector HNSW index refuses more, and `gemini-embedding-001` can emit 3072.
+
+   Leave `retrieval:` out for now — the gate is off and the server says so.
+   Turning it on is step 4, AFTER the record is serving.
+
+2. **Copy `.env.example` to `.env`** and fill it in — `ksor` reads it
+   automatically, so nothing needs exporting, and `.env` is already gitignored.
+   A real environment variable still wins over the file, so CI and production
+   overrides behave normally.
+
+   ```sh
+   cp .env.example .env
+   ```
+
+   Three values matter:
+
+   - `KSOR_DB_URL` — the Postgres store named by `instance.md`'s `dsn_env`. It
+     needs the pgvector extension: `CREATE EXTENSION vector;`
+   - `GEMINI_API_KEY` — the embedding provider key.
+   - `KSOR_AUTH_DISABLED=1` — **required for a local run.** `ksor serve`
+     refuses to boot unauthenticated without it, deliberately, so a server is
+     never left open by accident. It binds loopback, where auth off is the
+     intended dev shape. A PUBLIC deployment configures the SSO door instead —
+     see the comments in `.env.example` and "Serving safely" below.
+
+3. **Bring it up — one command:**
 
    ```sh
-   export KSOR_DB_URL='postgresql://…'   # the var instance.md names
-   export GEMINI_API_KEY='…'             # the embedding provider key
+   pnpm up      # schema → grant → ingest → serve
    ```
 
-3. **Apply the schema:** `pnpm schema` (creates tables, indexes, and the
-   ingest role).
+   Every step is re-runnable, so this is also how you **refresh after editing
+   `knowledge/`**: an applied schema reports "already applied", an existing
+   grant reports "already granted", and ingest builds a fresh generation.
 
-4. **Authorize ingest:** `pnpm grant` — writes the one row row-level security
-   requires before any write to this corpus is allowed. Idempotent, and
-   `pnpm exec ksor grant --instance instance.md --revoke` withdraws it.
+   **`pnpm up` ingests every time — but it re-EMBEDS nothing that has not
+   changed.** Chunks carry forward by content hash, so a rerun on an untouched
+   corpus makes zero provider calls (`embedded 0, carried N` in the output).
+   What it does spend is a generation: each run creates and activates a new one,
+   and they accumulate. So:
 
-   This is a separate, named act on purpose: applying the schema and
-   authorizing writes are different decisions, and a schema step that granted
-   itself write access would make the tool its own authorizer. Apply the schema
-   and ingest as the SAME Postgres login (the ingest role is granted to whoever
-   applied the DDL).
+   | You want to                      | Run                                        |
+   | -------------------------------- | ------------------------------------------ |
+   | set up, or refresh after an edit | `pnpm up`                                  |
+   | just restart the server          | `pnpm serve` — no new generation           |
+   | reap superseded generations      | `pnpm exec ksor gc --instance instance.md` |
 
-5. **Ingest:** `pnpm ingest` — embeds `knowledge/` into a fresh generation and
-   activates it (`--flip`). Safe to re-run (see the generation model below).
+   Run the steps individually (`pnpm schema`, `pnpm grant`, `pnpm ingest`)
+   when the acts belong to different people — a DBA holding the credentials
+   that authorize ingest, for instance.
 
-6. **Calibrate the abstention floor** (only if `vector_floor: uncalibrated`):
-   `pnpm exec ksor calibrate --instance instance.md` prints a recommended
-   `vector_floor` measurement; paste the number into `instance.md`'s `retrieval:`
-   block and re-run. A corpus that declares no `retrieval:` block serves with the
-   gate OFF (honest: it will not refuse out-of-corpus questions).
+4. **Turn the abstention gate on — deliberately, once it serves.** This is the
+   step that makes "not in this corpus" a real answer, and it is measured, never
+   guessed:
+
+   ```sh
+   pnpm exec ksor calibrate --instance instance.md
+   ```
+
+   It prints a recommended `vector_floor` for THIS corpus in THIS embedding
+   space. Paste the number in and restart:
+
+   ```yaml
+   retrieval:
+     vector_floor: 0.55 # measured by ksor calibrate on <date>
+   ```
 
-7. **Serve:** `pnpm serve`.
+   Never copy a floor from another corpus — recalibrate, and record the
+   measurement beside the number. Writing `vector_floor: uncalibrated` declares
+   the intent to gate WITHOUT a measurement, and every serve refuses until a
+   number replaces it; that is the fail-closed posture, not a starting point.
 
 ```sh
 pnpm schema      # apply the DDL (once)

package/templates/scaffold/README.md

@@ -30,17 +30,24 @@ Postgres store (with pgvector) and an embedding provider key, so it is not
 part of `pnpm dev`. The ordered path is:
 
 ```sh
-export KSOR_DB_URL='postgresql://…'   # the DSN var your instance.md names
-export GEMINI_API_KEY='…'             # the embedding provider key
-pnpm schema     # apply the database schema (once)
-pnpm grant      # authorize ingest for this corpus (once)
-pnpm ingest     # embed knowledge/ into a generation and activate it
-pnpm serve      # run the MCP server over the record
+cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH_DISABLED=1
+pnpm up                 # schema → grant → ingest → serve
 ```
 
-One setup step comes before this — adding the `database:`/`embedding:` blocks
-to `instance.md` — and there is more to know about the generation model and the
-fail-closed security posture. `AGENTS.md` → "Serving to agents" is the
+`ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH_DISABLED=1`
+is required for a local run: serve refuses to boot unauthenticated on purpose,
+so a server is never open by accident.
+
+Add one block to `instance.md` first — `database: { dsn_env: KSOR_DB_URL }`,
+the NAME of the variable, never the DSN. That is the whole required config:
+`embedding:` already defaults to Gemini at 1536 dimensions, and leaving
+`retrieval:` out starts you with the abstention gate off and honest about it
+(turn it on afterwards with `ksor calibrate`, once the record is serving).
+
+`pnpm up` is re-runnable — it is also how you refresh after editing
+`knowledge/`. It re-ingests each time but re-embeds only what changed, so an
+untouched corpus costs no provider calls; to simply restart the server without
+building a new generation, run `pnpm serve` on its own. `AGENTS.md` → "Serving to agents" is the
 full runbook; your coding agent reads it first. `pnpm serve` binds loopback
 with auth off for local use; a public bind fails closed unless auth is
 configured. Any other operation is `pnpm exec ksor <verb>`.
@@ -67,8 +74,9 @@ different coding agent's way of finding the same working contract.
 | `.gemini/settings.json`          | points Gemini CLI at `AGENTS.md`; Gemini does not read that filename on its own.                                                                                                                                                 |
 | `.github/workflows/validate.yml` | your CI: runs the same checker on every pull request and push to main.                                                                                                                                                           |
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
-| `.gitignore`                     | keeps build output, `node_modules/`, and `.env*` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the `pnpm dev` / `pnpm build` / `pnpm check` / `pnpm schema` / `pnpm grant` / `pnpm ingest` / `pnpm serve` commands, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
+| `.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 `pnpm dev` / `pnpm build` / `pnpm check` commands and the served rung's `pnpm up` (schema → grant → ingest → serve, or run them separately), the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
 

package/templates/scaffold/env.example

@@ -0,0 +1,23 @@
+# Copy to .env — ksor reads it automatically, and .env is gitignored.
+# A real environment variable always wins over this file, so CI and production
+# keep their own values.
+
+# The Postgres store, named by instance.md's database.dsn_env.
+# Needs the pgvector extension: CREATE EXTENSION vector;
+KSOR_DB_URL=postgresql://user:password@host:5432/dbname
+
+# The embedding provider key. instance.md defaults to gemini-embedding-001.
+GEMINI_API_KEY=
+
+# Local development posture. `ksor serve` REFUSES to boot unauthenticated
+# without this — deliberately, so a server is never open by accident. It binds
+# loopback, where auth off is the intended dev shape.
+#
+# For a PUBLIC deployment, delete this line and configure the SSO door instead:
+#   KSOR_SSO_URL=https://your-sso.example.com
+#   KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
+#   KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
+# Serving a public bind with auth off additionally requires
+# KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1, which serves your whole record to anyone
+# who can reach the port.
+KSOR_AUTH_DISABLED=1

package/templates/scaffold/gitignore

@@ -12,5 +12,6 @@ system/site/.staged-knowledge/
 
 # secrets never enter the record — system/ is their future home (serve)
 .env*
+!.env.example
 
 .DS_Store

package/templates/scaffold/package.json

@@ -7,6 +7,7 @@
     "dev": "pnpm -C system/site dev",
     "build": "pnpm -C system/site build",
     "check": "node .agents/skills/format-checker/check.mjs",
+    "up": "pnpm schema && pnpm grant && pnpm ingest && pnpm serve",
     "schema": "ksor schema --instance instance.md --apply",
     "grant": "ksor grant --instance instance.md",
     "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip",

package/templates/scaffold/vercel.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "framework": null,
-  "installCommand": "pnpm install --frozen-lockfile",
+  "installCommand": "pnpm install --no-frozen-lockfile",
   "buildCommand": "pnpm build",
   "outputDirectory": "system/site/out",
   "trailingSlash": true