@panaversity/ksor 0.0.44 → 0.0.46

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # @panaversity/ksor
 
+## 0.0.46
+
+### Patch Changes
+
+- a28fac9: **The Auth0 recipe now names the trap that costs the afternoon it warns about.**
+  Walked end to end against a live Auth0 tenant and a deployed door for the first
+  time (2026-08-26), and the recipe was right about what to type and silent about
+  the two things that actually go wrong.
+
+  The API **Identifier** must equal `KSOR_MCP_RESOURCE_URL` character for
+  character, `/mcp` path included — and **Auth0 does not let you edit it after the
+  API is created**, so a wrong one is fixed by making a new API, not by correcting
+  the field. Neither fact was written down.
+
+  Two Auth0 errors now have a table, because both arrive as a failed token request
+  and they mean opposite things: `Service not enabled within domain` is no API
+  with that Identifier, while `Client "…" is not authorized to access resource
+server` means the Identifier is right and the grant from step 5 is missing.
+  Moving from the first to the second is progress.
+
+  And "Verify it" gains a step 0: ask the PROVIDER for a token before touching the
+  door. Half of these failures never reach ksor, and one `curl` at the token
+  endpoint separates the halves — which is how this diagnosis was actually made,
+  after several rounds of reasoning about dashboard toggles that turned out not to
+  be the cause.
+
+  **And it now says you need more than one Application.** The recipe never
+  mentioned the site's own sign-in control, never said its Application is a
+  different TYPE from an assistant's, and never said the two cannot be the same
+  registration — a public client with no secret and a confidential client that
+  sends one are different things, and using one for both returns a bare `401` at
+  the token endpoint that names nothing. A table at the top of the recipe now
+  gives one row per caller: what type, what token-endpoint auth, what callback,
+  and whether it needs the grant from step 5.
+
+## 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

package/dist/cli.mjs

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

package/docs/authorization.md

@@ -298,6 +298,25 @@ Nothing else in this recipe makes sense until that lands. You are not building
 an API; you are describing the one you already have so Auth0 can mint tokens
 aimed at it.
 
+**You will need MORE THAN ONE Application, and they are different types.** This
+is the single thing most likely to waste your afternoon, because one application
+configured for one caller returns a plain `401` to the other with nothing
+naming the mismatch (found the hard way, 2026-08-26). One API, one caller per
+row:
+
+| The caller                                        | Auth0 Application Type      | Token endpoint auth        | Callback                                                            | Needs step 5 |
+| ------------------------------------------------- | --------------------------- | -------------------------- | ------------------------------------------------------------------- | ------------ |
+| the SITE's sign-in control (`NEXT_PUBLIC_KSOR_*`) | **Single Page Application** | **None** — PKCE, no secret | `https://your-site/auth/callback`                                   | no           |
+| an assistant a person logs into (Claude, an IDE)  | **Regular Web Application** | client secret              | the assistant's own, e.g. `https://claude.ai/api/mcp/auth_callback` | **yes**      |
+| a script, worker or backend agent                 | **Machine to Machine**      | client secret              | none                                                                | **yes**      |
+
+The site row is a different flow and not really part of this page: it requests
+`openid profile email` and **no audience**, so it never touches your API and
+needs no grant. It is here only so you do not try to serve it and an assistant
+from one application — a public client with no secret and a confidential client
+that sends one cannot be the same registration, and the failure is a `401` at
+the token endpoint that says nothing about why.
+
 ### 1. Describe the door
 
 **Applications → APIs → Create API.** The **Identifier** you type becomes the
@@ -309,6 +328,24 @@ Name:       my-record
 Identifier: https://your-host.example.com/mcp
 ```
 
+**Type the whole URL, `/mcp` included, and get it right the first time.** The
+Identifier must equal `KSOR_MCP_RESOURCE_URL` character for character — the host
+alone is not enough, because that is not what the door will compare against. And
+**Auth0 does not let you edit an Identifier after the API is created**: a wrong
+one is fixed by creating a NEW API with the right string and granting your
+application access to that one instead.
+
+Two Auth0 errors tell you exactly where you are, and they are easy to confuse
+because both arrive as a failed token request (reported by an adopter,
+2026-08-26):
+
+| Auth0 says                                                               | Means                                                                                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `Service not enabled within domain: https://…/mcp`                       | **no API has that Identifier.** Yours was created with a different string — make a new one |
+| `Client "…" is not authorized to access resource server "https://…/mcp"` | the API is right and the **grant** is missing — step 5                                     |
+
+Moving from the first message to the second is progress, not a new problem.
+
 Creating it also creates a machine-to-machine **test application** named
 `<API> (Test Application)`. That is your first caller — you do not need to make
 one.
@@ -447,9 +484,25 @@ Use the commands below when it did NOT work, or when the caller is a script
 rather than a person. A token from your provider proves the provider works; it
 does not prove the door does. Both halves matter, and the refusal matters more.
 
+**0. Ask the provider for a token FIRST, before you touch the door.** Half the
+failures on this page never reach ksor at all, and this one command separates
+the two halves in a second:
+
+```sh
+curl -s -X POST https://YOUR_TENANT.us.auth0.com/oauth/token \
+  -H 'content-type: application/json' \
+  -d '{"grant_type":"client_credentials","client_id":"…","client_secret":"…",
+       "audience":"https://your-host.example.com/mcp"}'
+```
+
+An `error` here is the PROVIDER refusing, and no amount of ksor configuration
+will change it — see the table in step 1 for what each message means. An
+`access_token` here means the provider works, and anything still failing is the
+door or the token's contents, which is what the rest of this section is for.
+
 **1. Decode the token before using it.** This is the single most useful
-debugging step on this page, because a valid token audienced at the wrong thing
-looks identical to a broken one:
+debugging step once you have one, because a valid token audienced at the wrong
+thing looks identical to a broken one:
 
 ```sh
 echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '{iss, aud, exp}'

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/package.json

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