@panaversity/ksor 0.0.56 → 0.0.58

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @panaversity/ksor
 
+## 0.0.58
+
+### Patch Changes
+
+- 3807493: Twenty-six sentences that 0.0.44 through 0.0.57 had made false, found by a
+  sweep of every document against the tree and the published package, and fixed.
+
+  The two that ship on npm and would have stopped a reader: the package README
+  told `npx` users to run `pnpm install` — on the npm project `npx` emits, that
+  installs nothing under `system/site` and `pnpm dev` fails with `next: command
+not found` (the tutorial had this exact fix; the README never got it) — and it
+  still advertised the two companion skills 0.0.56 removed. It also claimed its
+  abstention envelope was "pasted as it appeared" from a tutorial that never
+  reaches one; it now says what that block is.
+
+  The rest: `calibrate --check` was documented in three places (ingesting.md,
+  the CLI help, and by implication the scaffold) as "always exits 0" — a verdict
+  always does; an unreachable database exits 3 as for every verb, and the docs
+  now say so before anyone puts it in CI. `tool-surface.md` carried two copies of
+  one bullet, the stale one missing `audit`. `upgrading.md` gave `ksor init` a
+  path, which it refuses. Three documents said "two" authorization recipes where
+  `authorization.md` has four. The emitted `instance.md` still described "all
+  four study attachments" on a starter trimmed to one companion in 0.0.44;
+  `intake-interview` and `people.yaml` said add-sources writes display names (it
+  does not); the scaffold README counted two negated `.ksor/` paths where there
+  are three; two token figures in the emitted AGENTS.md predated their own
+  re-measurement; and a sentence about "this record's own seven" embeds
+  described a record that is not the one it is emitted into. Root AGENTS.md said
+  "three tiers" above a list of four. `docs/status.md` described the seed quiz
+  and deck as shipping (trimmed in 0.0.44), the kernel as "in progress" (released
+  in 0.0.8–0.0.18), and carried yesterday's date. The introduction tutorial's
+  "where to go next" now links the two tutorials that exist and numbers the rest
+  as the index does; hello world said "five skills"; make-it-yours said `pnpm dev`
+  in an npm project.
+
+  Every fix is a document catching up to code, except the CLI help line, which
+  is text.
+
+## 0.0.57
+
+### Patch Changes
+
+- 07cddea: The tutorials are numbered in reading order, and the package README lists all
+  three.
+
+  The introduction is now `00`, hello world `01`, and _Make it yours_ stays `02`
+  — so the two hands-on tutorials that follow each other are no longer separated
+  by the 1,800-line introduction, and every existing cross-reference ("tutorial
+  2", "tutorial 4") stays true. The introduction's title drops "Tutorial 1"; it is
+  the introduction. A one-line pointer stays at the old `00-hello-world.md` for
+  one release, because the README that shipped in 0.0.56 links it.
+
+  Both READMEs gain a three-row table keyed on who each tutorial is for, and a
+  test now holds every link into `docs/tutorials/` — relative or GitHub URL —
+  to a file that exists.
+
 ## 0.0.56
 
 ### Patch Changes

package/README.md

@@ -12,17 +12,20 @@ when the corpus does not cover the question.
 ```bash
 npx @panaversity/ksor@latest init my-sor
 cd my-sor
-pnpm install
-pnpm dev        # the site, live at http://localhost:3000
+npm install
+npm run dev     # the site, live at http://localhost:3000
 ```
 
 Then write a document and publish it:
 
 ```console
-$ pnpm exec ksor build
+$ npx ksor build
 ksor build: 6 document(s), 5 admitted to a machine surface
 ```
 
+(`npx` emits an npm project; `pnpm dlx` or `bunx` emit that manager's, and
+the README it writes speaks that manager throughout.)
+
 **Six documents, five admitted.** The one you just wrote is a `draft`, so it
 reaches nothing an AI agent reads — not `llms.txt`, not the markdown twins —
 until a human approves it. Approve it and the count moves. That is the whole
@@ -42,9 +45,19 @@ where it came from:
 { "ok": false, "abstained": true, "gate": { "floor": 0.622 } }
 ```
 
-**[Hello world](https://github.com/panaversity/ksor/blob/main/docs/tutorials/00-hello-world.md)**
+**[Hello world](https://github.com/panaversity/ksor/blob/main/docs/tutorials/01-hello-world.md)**
 walks all of that in about fifteen minutes. Every command and output in it was
-run and pasted as it appeared — including the ones above.
+run and pasted as it appeared. The envelopes above show the SHAPE of an answer
+and a refusal; the refusal needs a calibrated floor, which hello world defers
+to its own tutorial.
+
+The three so far, in reading order — pick by what you want from it:
+
+| | read this if |
+| --- | --- |
+| [00 · Introduction](https://github.com/panaversity/ksor/blob/main/docs/tutorials/00-introduction-to-ksor.md) | you want to understand why this exists — no technical background needed |
+| [01 · Hello world](https://github.com/panaversity/ksor/blob/main/docs/tutorials/01-hello-world.md) | you want to see it work in fifteen minutes — Node only, nothing else |
+| [02 · Make it yours](https://github.com/panaversity/ksor/blob/main/docs/tutorials/02-make-it-yours.md) | you finished hello world and want a record that is only yours — a file in, a person's knowledge in, the samples out |
 
 One command emits a complete governed project: the record (`knowledge/`,
 plain CommonMark), a working documentation site with hot reload, offline
@@ -92,13 +105,9 @@ that document's page and nowhere else:
 | `<doc>.flashcards.yaml` | a recall deck, at the end                               |
 | `<doc>.quiz.yaml`       | a multiple-choice check, at the end                     |
 
-Ask your coding agent — `make slides for knowledge/expenses/approvals.md`, or
-`summarise knowledge/expenses/approvals.md` — and the `make-slides` and
-`make-summary` skills write the attachment from the document, check every claim
-and number back against it, and report what they left out because the document
-did not support it. A summary is checked section by section, because one that
-covers the opening and trails off leaves a reader believing they have the whole
-document.
+Companions are ordinary files beside the document. Write them yourself or ask
+your coding agent for one, and hold it to the rule the emitted AGENTS.md
+states: a companion may only say what its document says.
 
 An attachment is **part of its document**: no URL, no sidebar row, no
 `llms.txt` line, and no id an agent can cite. It takes its audience and any

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-dqpI-p1a.mjs";
-import { A as parseViewer, B as tallyHandlers, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as recordIsUndescribed, G as z$1, H as validateViewer, I as runProbe$1, L as searchHandler, M as prewarmPool, N as providerKeyEnv$1, O as parseInstanceText$1, P as readHandler, R as servingPolicy$1, S as contentPool$1, T as instancePathOf$1, U as withPgRetry$1, V as tlsPosture, W as withProbeDeadline$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as storedTextSearchConfig } from "./gateway-api-C0vL3oOK-D24n786A.mjs";
+import { A as parseViewer, B as tallyHandlers, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as recordIsUndescribed, G as z$1, H as validateViewer, I as runProbe$1, L as searchHandler, M as prewarmPool, N as providerKeyEnv$1, O as parseInstanceText$1, P as readHandler, R as servingPolicy$1, S as contentPool$1, T as instancePathOf$1, U as withPgRetry$1, V as tlsPosture, W as withProbeDeadline$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as storedTextSearchConfig } from "./gateway-api-DvM2mVtD-BXmUS4T8.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -17,7 +17,7 @@ import { Document, YAMLParseError, isCollection, isMap, isPair, isSeq, parseAllD
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 import { execFileSync, spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-BoKhKcP0.mjs
+//#region ../content-gateway/dist/main-C9M1ZaXh.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -4710,7 +4710,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-CO9-bQnb.mjs
+//#region ../content/dist/commands-BvRSdIZA.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -10285,7 +10285,8 @@ Usage:
       --check reads the record's OWN logged searches instead and reports how
       the declared floor is holding against them — no provider key, no
       embedding call, no LLM. A monitor, never a gate: it says what to
-      re-measure and always exits 0.
+      re-measure, and a verdict always exits 0 — the environment exits 3, as
+      for every verb.
   ksor grant --instance PATH [--revoke]
       Authorize ingest for the instance's tenant (the row row-level security
       requires), or withdraw it. Idempotent; reports the state it established.

package/dist/{gateway-api-C0vL3oOK-D24n786A.mjs → gateway-api-DvM2mVtD-BXmUS4T8.mjs}

@@ -6,7 +6,7 @@ import { z, z as z$1 } from "zod";
 import path, { join } from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-C0vL3oOK.mjs
+//#region ../content-gateway/dist/gateway-api-DvM2mVtD.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, F as recordIsUndescribed, G as z$1, L as searchHandler, P as readHandler, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-C0vL3oOK-D24n786A.mjs";
+import { D as outlineHandler, F as recordIsUndescribed, G as z$1, L as searchHandler, P as readHandler, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-DvM2mVtD-BXmUS4T8.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, TRUST_TIERS, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/deploying.md

@@ -314,8 +314,8 @@ correct for a genuinely public record or one behind your own gateway; it is not
 way to make a deploy go green.
 
 The alternative is a real authorization server — `KSOR_SSO_URL`,
-`KSOR_MCP_RESOURCE_URL`, `KSOR_JWT_ALLOWED_AUDIENCES`, with worked recipes for two
-of them in [authorization.md](./authorization.md).
+`KSOR_MCP_RESOURCE_URL`, `KSOR_JWT_ALLOWED_AUDIENCES`, with worked recipes for
+four of them in [authorization.md](./authorization.md).
 
 ### Set this on any container host
 
@@ -573,7 +573,7 @@ auth-off default, and that refusal is the last real step of a deployment. Two
 ways past it:
 
 - **Configure the SSO door** — `KSOR_SSO_URL`, `KSOR_MCP_RESOURCE_URL`,
-  `KSOR_JWT_ALLOWED_AUDIENCES`. Worked recipes for two different authorization
+  `KSOR_JWT_ALLOWED_AUDIENCES`. Worked recipes for four different authorization
   servers: [authorization.md](./authorization.md).
 - **Set `KSOR_AUTH=disabled-public`** — a deliberate decision that
   serves your whole record to anyone who can reach the port. Correct for a

package/docs/index.md

@@ -57,8 +57,8 @@ instead of their training memory. The corpus grows with each implemented verb.
     which a dependency bump reaches a project already scaffolded. Includes the
     list of files migrate does NOT carry, so you know what to diff by hand.
   - **[authorization.md](./authorization.md)** — putting the record behind an
-    authorization server, with worked recipes for two of them, executed rather
-    than written. `ksor serve` refuses to boot unauthenticated on a public bind,
+    authorization server, with worked recipes for four of them — two self-hosted,
+    one hosted, one an organisation's own — executed rather than written. `ksor serve` refuses to boot unauthenticated on a public bind,
     so this is the last step of a deployment, not an optional hardening pass.
 - Exit codes are a contract: `1` refused (first stderr line is a stable
   slug such as `error: bad-name`, followed by a remedy), `2` designed but

package/docs/ingesting.md

@@ -50,7 +50,7 @@ root**, where `instance.md` and `package.json` live.
 
 ```sh
 pnpm provision   # ksor schema --apply, then ksor grant
-pnpm refresh     # ksor ingest --flip, then ksor gc
+pnpm refresh     # ksor build, then ksor ingest --flip, then ksor gc
 ```
 
 `provision` is separate because applying DDL and granting ingest are acts an
@@ -289,9 +289,12 @@ decision in this project's own gold rather than a threshold somebody picked.
 Run it on a schedule, or in your own CI beside `ksor build`. Three things to
 know about what it is:
 
-- **It never fails a run.** It always exits 0. A stale floor wants
-  re-measuring, and failing a build for one would make the shortest way out
-  deleting `vector_floor` — turning the gate off entirely to clear the error.
+- **A verdict never fails a run.** STEADY, WATCH and no-data all exit 0: a
+  stale floor wants re-measuring, and failing a build for one would make the
+  shortest way out deleting `vector_floor` — turning the gate off entirely to
+  clear the error. What does exit non-zero is the environment, the same way it
+  does for every verb: 3 when `KSOR_DB_URL` is unset or the database is
+  unreachable, 1 on a bad flag. Put it in CI knowing that.
 - **It reads traffic, so it needs traffic**, and it says so rather than
   reporting a healthy-looking nothing. It also cannot see questions nobody
   asked: it can tell you the floor has gone permissive, never that it is too

package/docs/tool-surface.md

@@ -144,9 +144,6 @@ made it answer from.
   only things that can prove a passage came from the governed record. A
   hand-written one returning fabricated hits with plausible `stable_id`s would
   pass every shape check there is.
-- **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
-  `provenance`, each hit's `governance`, the `snapshot` token and `gate`. A
-  record that reshaped them would still look like a KSoR and no longer be one.
 - **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
   `provenance`, each hit's `governance`, the `snapshot` token, `gate`, and
   `audit`. A record that reshaped them would still look like a KSoR and no

package/docs/upgrading.md

@@ -76,7 +76,7 @@ These are yours, and no release touches them. Diff them against a fresh
 - `pnpm-workspace.yaml` / `.npmrc` and any lockfile
 
 ```sh
-npx @panaversity/ksor@latest init /tmp/fresh
+(cd /tmp && npx @panaversity/ksor@latest init fresh)   # init takes a NAME, not a path
 diff -ru /tmp/fresh/vercel.json ./vercel.json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "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",
@@ -72,8 +72,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content": "0.0.0",
-    "@panaversity/ksor-content-gateway": "0.0.0"
+    "@panaversity/ksor-content-gateway": "0.0.0",
+    "@panaversity/ksor-content": "0.0.0"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/.agents/skills/intake-interview/SKILL.md

@@ -146,11 +146,12 @@ never an email address.
   MAP from each actor to its natural name — `"human:bashiraziz": Bashir Aziz`.
   Keyed by the actor exactly as the record stores it, quoted because it
   contains a colon. Nothing else — the site looks the actor up at render time,
-  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance
-  act (this one, add-sources when it names a `ksor.owner`, `ksor takedown` for
-  withdrawals) asks the owner for a natural name whenever it is about to write
-  an actor that isn't in `people.yaml` yet — the owner is the only source of a
-  display name, never a convention-based guess.
+  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". This
+  is the skill that writes actors into the policy, so it is the one that asks
+  the owner for a natural name for each — the owner is the only source of a
+  display name, never a convention-based guess. An actor that arrives later
+  (an owner named in a document, an approver added by hand) gets its entry
+  when the owner adds one; the site prints the identifier until then.
 - **Offer to start replacing the starter documents — they are already
   published.** All five ship `status: stable`, approved by
   `ksor-starter/KSOR-STAMP-VERSION`, so the site and `llms.txt` carry them from

package/templates/scaffold/.claude/skills/intake-interview/SKILL.md

@@ -146,11 +146,12 @@ never an email address.
   MAP from each actor to its natural name — `"human:bashiraziz": Bashir Aziz`.
   Keyed by the actor exactly as the record stores it, quoted because it
   contains a colon. Nothing else — the site looks the actor up at render time,
-  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance
-  act (this one, add-sources when it names a `ksor.owner`, `ksor takedown` for
-  withdrawals) asks the owner for a natural name whenever it is about to write
-  an actor that isn't in `people.yaml` yet — the owner is the only source of a
-  display name, never a convention-based guess.
+  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". This
+  is the skill that writes actors into the policy, so it is the one that asks
+  the owner for a natural name for each — the owner is the only source of a
+  display name, never a convention-based guess. An actor that arrives later
+  (an owner named in a document, an approver added by hand) gets its entry
+  when the owner adds one; the site prints the identifier until then.
 - **Offer to start replacing the starter documents — they are already
   published.** All five ship `status: stable`, approved by
   `ksor-starter/KSOR-STAMP-VERSION`, so the site and `llms.txt` carry them from

package/templates/scaffold/.ksor/people.yaml

@@ -26,7 +26,7 @@
 # name has to keep rendering on those acts.
 #
 # Optional. An actor with no entry renders exactly as stored, as it did before
-# this file existed. The intake and add-sources skills offer to add one; the
-# owner can also edit this file by hand — it is theirs.
+# this file existed. The intake interview offers to add one; the owner can
+# also edit this file by hand — it is theirs.
 version: "0.1"
 people: {}

package/templates/scaffold/AGENTS.md

@@ -423,7 +423,7 @@ governance block every hit now carries:
 Three edits pay for themselves:
 
 - **Delete a tool nothing calls.** Removing `outline` and `read` gives back
-  ~2,152 tokens for the whole session.
+  ~2,310 tokens for the whole session.
 - **Say what this record covers**, above `FLOOR.search`. It is how an agent with
   several records attached picks yours; name the subject AND the boundary.
 - **Set `k`** in the input schema — it is the lever on reply size.
@@ -899,8 +899,7 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   click is informed.
 
   **You do not state a height.** A page carried in the record is measured, so
-  the frame is exactly as tall as what it holds — on this record's own seven,
-  to the pixel. A number written into a document would be a number some other
+  the frame is exactly as tall as what it holds, to the pixel. A number written into a document would be a number some other
   measure makes wrong.
 
   **Carry the page in where you can.** A file named `<name>.sim.html`, sitting

package/templates/scaffold/README.md

@@ -698,7 +698,7 @@ 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 — and negates two paths inside `.ksor/`, because the policy and the ledger ARE the record.                                   |
+| `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history — and negates three paths inside `.ksor/`, because the policy, the ledger and the phone book ARE the record.                  |
 
 `format-checker` deliberately contains a program, `check.mjs`, and not only
 prose: rules that are only written down cannot refuse anything.

package/templates/scaffold/instance.md

@@ -41,9 +41,8 @@ record wins.
 
 Everything above describes KSoR itself. It ships filled in so that a fresh
 project has a real governed corpus on the first `pnpm dev` — five approved
-documents, three of them inside a folder, and one carrying all four study
-attachments (a summary, slides, flashcards and a quiz) — instead of an empty
-shelf and a placeholder.
+documents, three of them inside a folder, and one carrying a summary
+companion — instead of an empty shelf and a placeholder.
 The documents live in `knowledge/`; delete them as your own knowledge arrives.
 
 Be deliberate about replacing it, because a starter that describes the wrong