@panaversity/ksor 0.0.41 → 0.0.42

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @panaversity/ksor
 
+## 0.0.42
+
+### Patch Changes
+
+- d55097c: **Document what a deploy actually does to your lock.** `vercel.json` builds the
+  site with `pnpm build`, which runs `ksor build` first — so the host regenerates
+  every `index.md` and `build.lock.json` before building. That has two
+  consequences worth knowing, and neither was written down: you can deploy
+  without ever running `ksor build` yourself, and the `build.lock.json` in your
+  repository is not necessarily the one that shipped.
+
+  Nothing changes in behaviour. The record checker still runs on the deploy, so a
+  record that breaks the profile still fails there, and the `build_id` that did
+  ship is stamped into the deployed `llms.txt`.
+
+  `docs/deploying.md` now also shows the stricter posture for adopters who want
+  the deployed build reviewed before it ships — `buildCommand: "pnpm -C
+system/site build"`, which refuses `ksor-lock-missing` or `ksor-lock-stale`
+  until someone runs `ksor build` and commits it. That is one line in your own
+  `vercel.json`; ksor ships no flag for it.
+
+- abef414: **Fix the release-note lookup, properly this time.** The previous release added
+  `releaseNote()` so doc-truth assertions could survive a changeset being folded
+  into the changelog. It resolved a consumed note to the NEWEST changelog
+  section, which is only correct for the release that consumes it: a note
+  consumed in 0.0.41 lives in the 0.0.41 section forever, so by 0.0.42 the lookup
+  returned a different release entirely.
+
+  Two failures came out of that, and the second was worse than the bug it
+  replaced: presence assertions went red, and a fenced-block scan went VACUOUS —
+  passing because the section handed to it contained no code blocks at all.
+
+  `releaseNote()` now returns the whole changelog once a note is consumed, plus
+  whether the note is still `pending`. Assertions about the PRESENCE of prose use
+  the text (finding it anywhere in the changelog proves it shipped); assertions
+  about STRUCTURE gate on `pending`, because "every fenced block must show
+  `--approve-by`" is a rule about a note still under review, not one to apply to
+  the whole published history.
+
+  Verified in both states and mutation-tested against the released tree: removing
+  `--approve-by` or changing the tool-size figure in the changelog turns the
+  assertions red.
+
+- bfcf900: **A new record already names its DSN variable.** `instance.md`'s
+  `database.dsn_env` shipped commented out, so climbing to the served rung began
+  with an edit whose only purpose was to delete two `#` characters — and the
+  instruction to do it was repeated in four places, one of which (`.env.example`)
+  sat right beside a `KSOR_DB_URL=` line that was NOT commented. A first-time
+  reader had to notice that one file names the variable and another defines it,
+  and that only one of the two needed uncommenting.
+
+  It is filled in now. Naming an environment variable costs nothing and requires
+  no database: `pnpm dev` and `pnpm build` never read it, and the value only has
+  to exist when you run `provision`, `refresh` or `serve`. Verified on a real
+  scaffold from the published package with the block live and `KSOR_DB_URL`
+  unset — `check`, `ksor build` and a full static site build all succeed, and the
+  record publishes.
+
+  So the served rung is now: set `KSOR_DB_URL` in `.env`, then `provision`,
+  `refresh`, `serve`. The step that was pure ceremony is gone, and `ksor init`'s
+  own next-steps, the scaffold's `AGENTS.md`, `.env.example` and
+  `docs/ingesting.md` all say the same thing.
+
 ## 0.0.41
 
 ### Patch Changes

package/dist/cli.mjs

@@ -13324,7 +13324,7 @@ function handoff(io, name, targetWasDot, manager) {
 Next (or just tell your coding agent to take it from here):
 ` + 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("provision").padEnd(15)} # once: copy .env.example to .env and set KSOR_DB_URL,\n                  #   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");
 }

package/docs/deploying.md

@@ -254,6 +254,26 @@ and reaches the site at its next build (it reads the ledger), so the act that
 withdraws a document is the same merged commit on both surfaces. Merge the
 ledger entry, rebuild, redeploy.
 
+**Your deploy runs it too, and that is deliberate.** `vercel.json` builds with
+`pnpm build`, so the host regenerates the indexes and the lock before building
+the site. The consequence is worth knowing in both directions: you can deploy
+without ever having run `ksor build` yourself — the record checker still runs
+there, so a record that breaks the profile still fails the deploy — but the
+`build.lock.json` in your repository is not necessarily the one that shipped.
+The `build_id` that DID ship is stamped into the deployed `llms.txt`.
+
+If you want the stricter property — the deployed build_id is one a human
+reviewed in a pull request — build the site alone instead:
+
+```json
+"buildCommand": "pnpm -C system/site build"
+```
+
+The site refuses `ksor-lock-missing` or `ksor-lock-stale` when the committed
+lock does not describe the tree, so a deploy then fails until someone runs
+`ksor build` and commits the result. That is your file to change; ksor does not
+choose it for you.
+
 ## Keeping people out of the site
 
 The door has auth ([authorization.md](./authorization.md)). The **site** is

package/docs/ingesting.md

@@ -25,7 +25,7 @@ created for you.
 | **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, in the KSoR Profile of OKF: `type`, `title`, `description`, `status` and `ksor.audience` in frontmatter | `pnpm check` validates it and explains any violation; `ksor build` must have written a current `build.lock.json` before ingest will run |
 | **The database**     | Postgres with **pgvector** — `CREATE EXTENSION vector;`                                                                                                                           | any managed host; the DDL below needs a role that can create tables                                                                     |
 | **The provider key** | `GEMINI_API_KEY` — the default embedding provider is `gemini-embedding-001`                                                                                                       | [aistudio.google.com](https://aistudio.google.com/apikey); the free tier covers a first corpus                                          |
-| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                        | uncomment the `database:` block in `instance.md` first                                                                                  |
+| **The DSN**          | `KSOR_DB_URL`, named by `instance.md`'s `database.dsn_env`                                                                                                                        | already named by `instance.md`'s `database:` block                                                                                      |
 
 Both variables go in `.env` beside `instance.md` — `ksor` reads it automatically,
 and `.env` is gitignored. Every command below is run **from your repository

package/package.json

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

@@ -60,9 +60,9 @@ 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`.** One block is required, and it is already
-   there, commented out — uncomment it. It names the environment variable
-   holding your DSN (never the DSN itself):
+1. **Check `instance.md`.** The one required block is already filled in — it
+   names the environment variable holding your DSN (never the DSN itself), and
+   there is nothing to do here unless you want a different variable name:
 
    ```yaml
    database:

package/templates/scaffold/env.example

@@ -2,8 +2,9 @@
 # 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 — uncomment the
-# `database:` block there first. Needs the pgvector extension:
+# The Postgres store. instance.md already names this variable in its
+# `database.dsn_env`, so setting it here is the whole of the wiring.
+# Needs the pgvector extension:
 # CREATE EXTENSION vector;
 # On a remote host prefer sslmode=verify-full, which states the TLS posture
 # explicitly instead of relying on a driver default that is due to change.

package/templates/scaffold/instance.md

@@ -6,17 +6,20 @@ description: What a Knowledge System of Record is, how a project climbs the gove
 toolchain:
   requires: ">=KSOR-STAMP-VERSION"
   scaffolded: "KSOR-STAMP-VERSION"
-# The served MCP rung needs ONE required block: the NAME of the environment
-# variable holding your Postgres DSN — never the DSN itself. Uncomment it, copy
-# .env.example to .env, then: `pnpm provision` once (schema + grant), then
-# `pnpm refresh` to PUBLISH the record, then `pnpm serve`. Serving does not
-# publish — that is deliberate, and skipping refresh serves nothing.
+# `database.dsn_env` names the environment variable holding your Postgres DSN —
+# never the DSN itself, which belongs in .env. It is filled in because naming a
+# variable costs nothing and needs no database: `pnpm dev` and `pnpm build` do
+# not read it, and the value only has to exist when you climb to the served
+# rung. To climb: copy .env.example to .env and set KSOR_DB_URL, then
+# `pnpm provision` once (schema + grant), then `pnpm refresh` to PUBLISH the
+# record, then `pnpm serve`. Serving does not publish — that is deliberate, and
+# skipping refresh serves nothing.
 # Nothing else here is required:
 # `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).
-# database:
-#   dsn_env: KSOR_DB_URL
+database:
+  dsn_env: KSOR_DB_URL
 # Where agents reach this record's MCP surface, and the semver it publishes as.
 # Both go into /.well-known/mcp/server.json, the document an agent reads to
 # DISCOVER this record instead of being told the URL. Leave mcp_url out until