@panaversity/ksor 0.0.43 → 0.0.45

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @panaversity/ksor
 
+## 0.0.45
+
+### Patch Changes
+
+- 1875d06: **`pnpm preview` — somewhere for `pnpm build` to land.**
+
+  The site is a static export, so there is no server to start; that is what makes
+  the record hostable anywhere. But it also means the natural thing to try after a
+  build — `pnpm start` — answers `ERR_PNPM_NO_SCRIPT_OR_SERVER`, which explains
+  none of that. `pnpm preview` serves `system/site/out` on the same bytes a host
+  would. It is `node:http` and nothing else: no dependency, no network fetch, works
+  offline and behind a firewall, for the same reason the build downloads nothing.
+  Run before a build, it says so and exits `3`.
+
+  **And the Vercel dashboard import now says what actually goes wrong.** Vercel
+  auto-detects a root directory by looking for a framework, finds the Next app, and
+  fills the field with `system/site`. The build then reads
+  `system/site/vercel.json`, which does not exist, and fails with
+  `Project framework is set to "services", but no services are declared` — even
+  though the import screen just listed both services, because that step reads the
+  root file and the build step uses the Root Directory override. The fix is one
+  field: set Root Directory to the repository root. `docs/deploying.md` now names
+  the error, the cause and the fix, plus the site-only fallback.
+
+  Found by an adopter, and it will recur on every dashboard import until Vercel's
+  detection changes — the layout that triggers it is decision 8 and is not moving.
+
+  **And the intake interview asks three questions, not seven.** Seven did not
+  survive contact: an agent running the skill decided five were too many,
+  defaulted them, and reported "answered: all seven" — including the one that
+  decides who may approve a document, which it filled from a git handle. A
+  process the tool executing it shortcuts is too long.
+
+  Scope, Boundary and Authority are asked, because none can be defaulted: the
+  first two give the abstention gate an edge to be outside of, and the third is
+  a governance act, which never gets guessed (decision 21). The other four are
+  STATED as defaults in one block — read by both, declines firmly, one `public`
+  audience, no sources yet — written only if the owner does not object, and the
+  write-back must name which were answered and which were defaulted. Reporting a
+  default as an answer is now called out in the skill as the thing not to do.
+
+  **The scaffold README no longer tells you to uncomment something that ships
+  uncommented.** 0.0.42 filled in `instance.md`'s `database:` block; the README
+  kept instructing the adopter to uncomment it, and named a refusal
+  (`instance.md declares no database: block`) they could no longer reach. The
+  emitted `AGENTS.md` had already been corrected and the README had not — two
+  documents describing one file, and only one of them updated. Vercel is three
+  steps ending in the Root Directory fix, `preview` sits beside `build`, and a
+  "When something refuses you" table maps every refusal an adopter meets to what
+  to do about it.
+
+  **The scaffold README is restructured around what the record is FOR.** It now
+  opens on the agent interface — an MCP door that answers with citations and
+  declines what the record does not cover — rather than on an architecture
+  diagram, because a reader classifies the project in the first fifteen seconds
+  and "governed markdown plus a site" puts it in the wrong bucket.
+
+  `ksor calibrate` moves into the main command path, between `refresh` and
+  `serve`. It was a parenthetical and a remedy-after-the-fact, which meant the
+  README's own three-question test failed at exactly the question it says
+  matters. Verified on the five-document starter: calibrate needs an ingested
+  corpus but NO running server, produces `vector_floor: 0.609`, and with it
+  applied the test passes as written — the paraphrased in-corpus question is
+  answered at 0.701 while an adjacent miss abstains at 0.550 and a far-outside
+  one at 0.512. The "expect answers, not refusals" note moves from postscript to
+  precondition, where it prevents the disappointment instead of explaining it.
+
+  Also: Neon is named for hosted Postgres rather than leaving it abstract (it is
+  already what this project's own docs are measured against, and pgvector is on
+  its free tier), the deploy section ends at the Root Directory fix, and a
+  "When something refuses you" table maps every refusal an adopter meets to the
+  one thing to do about it.
+
+## 0.0.44
+
+### Patch Changes
+
+- 2ece135: **A lighter starter, and `refresh` finally says what it does** (issues #173, #171).
+
+  `ksor init` put five of `knowledge/`'s eleven files onto a single concept — 199
+  lines of companions against a 40-line document — so the first thing an adopter
+  opened was one document wearing four attachments. The flashcards, quiz and
+  slides companions are gone; `what-is-a-ksor.summary.md` stays, because it is the
+  only companion carrying a governance rule (exactly `type: Summary`, one key), so
+  the profile marker is still demonstrated. `knowledge/` goes from 11 files to 8.
+
+  What that costs, stated rather than glossed: the recall, quiz and slides tabs are
+  no longer shown by the starter, and an adopter meets those features in the docs
+  instead. Nothing about the companion mechanism changed — decision 24 is
+  untouched, and the migrate fixture that proves a deck migrates byte-identically
+  is frozen from an older tree, so it still covers the case.
+
+  And `pnpm refresh` was a name the constitution never defined, sitting beside
+  `pnpm ingest` and `ksor ingest` with nothing saying how the three relate. It has
+  a vocabulary entry now, and `docs/ingesting.md` opens with the model: `ksor
+build` makes the SITE correct with no database, `ksor ingest` makes the AGENT
+  DOOR correct, and `pnpm refresh` runs both. The split between the scaffold's
+  script and the underlying verb is deliberate, and now it is written down instead
+  of inferred.
+
 ## 0.0.43
 
 ### Patch Changes

package/dist/cli.mjs

@@ -11329,6 +11329,7 @@ function transformManifest(source, manager) {
 const SCRIPT_NAMES = [
 	"dev",
 	"build",
+	"preview",
 	"check",
 	"serve",
 	"provision",

package/docs/deploying.md

@@ -113,6 +113,34 @@ What the image deliberately does NOT contain (see `.dockerignore`):
 
 ## Deploying both surfaces to Vercel
 
+> **Importing from the Vercel dashboard: clear the Root Directory first.**
+> Vercel auto-detects a root directory by looking for a framework, finds the
+> Next app, and fills the field with **`system/site`**. The build then reads
+> `system/site/vercel.json`, which does not exist, and fails with:
+>
+> ```
+> Error: Project framework is set to "services", but no services are declared.
+> ```
+>
+> The services ARE declared — in `vercel.json` at the repository root, which is
+> the only place they can be, because one of them builds the site and the other
+> builds a container from the root `Dockerfile`. The import screen even lists
+> both, because that step reads the root file; the BUILD step uses the Root
+> Directory override instead.
+>
+> **Set Root Directory to the repository root (`./`) and redeploy.** Nothing in
+> the record changes. Found by an adopter on 2026-08-26, and it will happen on
+> every dashboard import until Vercel's detection changes — the layout that
+> triggers it, code under `system/`, is decision 8 and is not moving.
+>
+> Also confirm **Application Preset is `Services`**; with any other preset the
+> `services` key is ignored and `/mcp` never exists. Vercel Services is in Beta.
+>
+> **If it still argues, deploy the site alone** — it needs no preset and no
+> services: build command `pnpm -C system/site build`, output directory
+> `system/site/out`. That is the stricter posture decision 29 describes, and
+> the door can be deployed separately.
+
 The emitted `vercel.json` declares both services and routes between them:
 
 ```json

package/docs/ingesting.md

@@ -14,6 +14,21 @@ embedding cost on every cold start and would need write credentials at runtime.
 So **a first deploy with no ingest serves an empty record.** It is not broken;
 nothing was ever published to it.
 
+## `ksor ingest` or `pnpm refresh`?
+
+Both, and they are not alternatives — one contains the other.
+
+|                | makes correct                                                                       | needs a database |
+| -------------- | ----------------------------------------------------------------------------------- | ---------------- |
+| `ksor build`   | the **site** — checks the record, regenerates the indexes, writes `build.lock.json` | no               |
+| `ksor ingest`  | the **agent door** — embeds, loads Postgres, flips a generation                     | yes              |
+| `pnpm refresh` | both, in order: `ksor build` → `ksor ingest --flip` → `ksor gc`                     | yes              |
+
+`pnpm refresh` is the scaffold's script and the one to reach for by hand — it
+is a single command that leaves every surface current. `ksor ingest` is the
+verb underneath it, and it is what CI, a deploy step, or an agent calls when
+the individual step is the subject. The rest of this page is about that verb.
+
 ## Before the first command
 
 Ingest reads your markdown, sends each new chunk to an embedding provider, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "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/skills/intake-interview/SKILL.md

@@ -12,49 +12,75 @@ prose IS the agent surface's system prompt (`ksor serve` wires it into the MCP
 server's instructions). Do not draft it from guesses — interview the owner, one
 question at a time, and write down what they actually say.
 
-## The first six questions
-
-Ask these one at a time; follow up until each answer is concrete enough to
-act on:
-
-1. **Authority** — "What should this record be the _final word_ on? Finish
-   the sentence: when someone here disagrees with this corpus, the corpus
-   wins about ___."
-2. **Boundary** — "What is explicitly _outside_ it — near-miss topics people
-   will ask about that this record should refuse rather than guess at?"
-3. **Audience** — "Who reads it — people, agents, both? In what situations,
-   making what decisions?"
-4. **Sources** — "Which existing materials are authoritative inputs (name
-   the actual documents, systems, people), and which are explicitly _not_
-   trusted?"
-5. **Strictness** — "When the record doesn't cover a question, how firmly
-   should it decline? ('Not in this corpus' is a correct answer here —
-   confirm the owner wants that behavior and where they want it softened.)"
-6. **Audiences** — "Does every reader of this record see every document? If
-   not, what are the audiences?" A yes is the common answer and the whole
-   answer: register none, and every document says `ksor.audience: [public]`.
-   Anything else means registering each audience in
-   `.ksor/governance.yaml` under `audiences:`, with a one-line
-   `description:` of who is in it — `public` is reserved and never
-   registered. There is no ranking and no default: a document lists the
-   audiences that may read it, a reader holds a list that always includes
-   `public`, and the document is visible when the two lists OVERLAP. Tell
-   the owner what this does and does not do: builds are made per audience,
-   but anyone who can clone the repository reads everything in it — if
-   someone must not read a document and can clone, that document belongs in
-   a different repository.
-
-## Then ask the seventh, because a policy cannot be guessed
-
-7. **Authority** — "Who may approve a document for publication, and who may
-   withdraw one?" Names, not roles-in-the-abstract: they become
-   `approval_authorities` and `takedown_authorities` in
-   `.ksor/governance.yaml`, and the checker refuses an approval or a
-   takedown by anyone the policy does not name. The scaffold ships
-   `human:you` in both — a placeholder that must not survive this
-   conversation. An actor is `human:<handle>`, `process:<name>` or
-   `<producer>/<version>`; handles are published with the record, so use the
-   handle the owner would put in a commit, never an email address.
+## Ask THREE questions, one at a time
+
+Seven questions is where this skill used to start, and it did not survive
+contact: an agent running it decided five were too many, defaulted them, and
+reported "answered: all seven" — including the one that decides who may
+approve a document. A process the tool executing it shortcuts is too long.
+
+So three are asked, and they are the three that cannot be defaulted:
+
+1. **Scope** — "What should this record be the _final word_ on? Finish the
+   sentence: when someone here disagrees with this corpus, the corpus wins
+   about ___."
+2. **Boundary** — "What is just _outside_ that — the near-miss topics people
+   will ask about here that the record should refuse rather than guess at?"
+3. **Authority** — "Who may approve a document for publication, and who may
+   withdraw one?"
+
+Scope and Boundary are asked because the abstention gate is meaningless
+without an edge: a record authoritative for everything has no outside, so an
+agent asked something the owner never wrote about reaches for its training
+instead of declining. Authority is asked because a governance act names its
+actor and the tool never guesses one — the scaffold ships `human:you` in
+both authority lists, and a placeholder that survives this conversation is a
+person who was never there.
+
+Follow up until each is concrete. "Our engineering docs" is not yet an
+answer; "our leave, expense and conduct policies — the current ones, not
+historical versions" is.
+
+## Then STATE the defaults; do not ask them
+
+Show these as a block, say they are defaults, and invite a correction. Do not
+walk them one at a time — they are near-constant, and asking makes the
+interview feel like a form.
+
+|           | default                                           |
+| --------- | ------------------------------------------------- |
+| read by   | people and agents both                            |
+| declines  | firmly — "not in this corpus" is a correct answer |
+| audiences | one, `public` — every reader sees every document  |
+| sources   | none yet — the corpus is still the samples        |
+
+Each is written only if the owner does not object, and the write-back names
+which were answered and which were defaulted. **Never report a default as an
+answer.** Two answered and four defaulted is an honest sentence; "all seven
+answered" is not, and it is what happened the first time this skill ran.
+
+**If the owner says NOT every reader sees every document**, then and only
+then: register each audience in `.ksor/governance.yaml` under `audiences:`
+with a one-line `description:` of who is in it — `public` is reserved and
+never registered. There is no ranking and no default: a document lists the
+audiences that may read it, a reader holds a list that always includes
+`public`, and the document is visible when the two lists OVERLAP. Tell them
+what this does and does not do: builds are made per audience, but anyone who
+can clone the repository reads everything in it — if someone must not read a
+document and can clone, that document belongs in a different repository.
+
+## What the answers become
+
+Scope and Boundary become the BODY of `instance.md`, which `ksor serve` wires
+into the MCP server's instructions — so it is read by every agent that
+connects, and vague prose there is vague instructions everywhere.
+
+Authority becomes `approval_authorities` and `takedown_authorities` in
+`.ksor/governance.yaml`. Names, not roles-in-the-abstract: the checker refuses
+an approval or a takedown by anyone the policy does not name. An actor is
+`human:<handle>`, `process:<name>` or `<producer>/<version>`; handles are
+published with the record, so use the handle the owner would put in a commit,
+never an email address.
 
 ## Then write
 

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

@@ -12,49 +12,75 @@ prose IS the agent surface's system prompt (`ksor serve` wires it into the MCP
 server's instructions). Do not draft it from guesses — interview the owner, one
 question at a time, and write down what they actually say.
 
-## The first six questions
-
-Ask these one at a time; follow up until each answer is concrete enough to
-act on:
-
-1. **Authority** — "What should this record be the _final word_ on? Finish
-   the sentence: when someone here disagrees with this corpus, the corpus
-   wins about ___."
-2. **Boundary** — "What is explicitly _outside_ it — near-miss topics people
-   will ask about that this record should refuse rather than guess at?"
-3. **Audience** — "Who reads it — people, agents, both? In what situations,
-   making what decisions?"
-4. **Sources** — "Which existing materials are authoritative inputs (name
-   the actual documents, systems, people), and which are explicitly _not_
-   trusted?"
-5. **Strictness** — "When the record doesn't cover a question, how firmly
-   should it decline? ('Not in this corpus' is a correct answer here —
-   confirm the owner wants that behavior and where they want it softened.)"
-6. **Audiences** — "Does every reader of this record see every document? If
-   not, what are the audiences?" A yes is the common answer and the whole
-   answer: register none, and every document says `ksor.audience: [public]`.
-   Anything else means registering each audience in
-   `.ksor/governance.yaml` under `audiences:`, with a one-line
-   `description:` of who is in it — `public` is reserved and never
-   registered. There is no ranking and no default: a document lists the
-   audiences that may read it, a reader holds a list that always includes
-   `public`, and the document is visible when the two lists OVERLAP. Tell
-   the owner what this does and does not do: builds are made per audience,
-   but anyone who can clone the repository reads everything in it — if
-   someone must not read a document and can clone, that document belongs in
-   a different repository.
-
-## Then ask the seventh, because a policy cannot be guessed
-
-7. **Authority** — "Who may approve a document for publication, and who may
-   withdraw one?" Names, not roles-in-the-abstract: they become
-   `approval_authorities` and `takedown_authorities` in
-   `.ksor/governance.yaml`, and the checker refuses an approval or a
-   takedown by anyone the policy does not name. The scaffold ships
-   `human:you` in both — a placeholder that must not survive this
-   conversation. An actor is `human:<handle>`, `process:<name>` or
-   `<producer>/<version>`; handles are published with the record, so use the
-   handle the owner would put in a commit, never an email address.
+## Ask THREE questions, one at a time
+
+Seven questions is where this skill used to start, and it did not survive
+contact: an agent running it decided five were too many, defaulted them, and
+reported "answered: all seven" — including the one that decides who may
+approve a document. A process the tool executing it shortcuts is too long.
+
+So three are asked, and they are the three that cannot be defaulted:
+
+1. **Scope** — "What should this record be the _final word_ on? Finish the
+   sentence: when someone here disagrees with this corpus, the corpus wins
+   about ___."
+2. **Boundary** — "What is just _outside_ that — the near-miss topics people
+   will ask about here that the record should refuse rather than guess at?"
+3. **Authority** — "Who may approve a document for publication, and who may
+   withdraw one?"
+
+Scope and Boundary are asked because the abstention gate is meaningless
+without an edge: a record authoritative for everything has no outside, so an
+agent asked something the owner never wrote about reaches for its training
+instead of declining. Authority is asked because a governance act names its
+actor and the tool never guesses one — the scaffold ships `human:you` in
+both authority lists, and a placeholder that survives this conversation is a
+person who was never there.
+
+Follow up until each is concrete. "Our engineering docs" is not yet an
+answer; "our leave, expense and conduct policies — the current ones, not
+historical versions" is.
+
+## Then STATE the defaults; do not ask them
+
+Show these as a block, say they are defaults, and invite a correction. Do not
+walk them one at a time — they are near-constant, and asking makes the
+interview feel like a form.
+
+|           | default                                           |
+| --------- | ------------------------------------------------- |
+| read by   | people and agents both                            |
+| declines  | firmly — "not in this corpus" is a correct answer |
+| audiences | one, `public` — every reader sees every document  |
+| sources   | none yet — the corpus is still the samples        |
+
+Each is written only if the owner does not object, and the write-back names
+which were answered and which were defaulted. **Never report a default as an
+answer.** Two answered and four defaulted is an honest sentence; "all seven
+answered" is not, and it is what happened the first time this skill ran.
+
+**If the owner says NOT every reader sees every document**, then and only
+then: register each audience in `.ksor/governance.yaml` under `audiences:`
+with a one-line `description:` of who is in it — `public` is reserved and
+never registered. There is no ranking and no default: a document lists the
+audiences that may read it, a reader holds a list that always includes
+`public`, and the document is visible when the two lists OVERLAP. Tell them
+what this does and does not do: builds are made per audience, but anyone who
+can clone the repository reads everything in it — if someone must not read a
+document and can clone, that document belongs in a different repository.
+
+## What the answers become
+
+Scope and Boundary become the BODY of `instance.md`, which `ksor serve` wires
+into the MCP server's instructions — so it is read by every agent that
+connects, and vague prose there is vague instructions everywhere.
+
+Authority becomes `approval_authorities` and `takedown_authorities` in
+`.ksor/governance.yaml`. Names, not roles-in-the-abstract: the checker refuses
+an approval or a takedown by anyone the policy does not name. An actor is
+`human:<handle>`, `process:<name>` or `<producer>/<version>`; handles are
+published with the record, so use the handle the owner would put in a commit,
+never an email address.
 
 ## Then write