@panaversity/ksor 0.0.45 → 0.0.47

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @panaversity/ksor
 
+## 0.0.47
+
+### Patch Changes
+
+- 00c99da: **The intake interview asks its three questions in the owner's words.** The
+  previous wording was precise and unanswerable: question 1 asked the owner to
+  finish "when someone here disagrees with this corpus, the corpus wins about
+  ___", which is not a sentence unless you already know the ledger analogy the
+  README uses, and then explained what the answer would be used for inside the
+  question itself. An owner reported being unable to tell what it wanted at all.
+
+  Now: "What is this knowledge base about?", "What is close to that, but not part
+  of it?", and "Who signs off on a document, and who can take one down?" — each
+  with one too-vague example and one specific enough, and nothing about
+  `instance.md` or the MCP surface in the question. The reasoning that used to sit
+  inside the questions moved below them, where it explains the design to whoever
+  maintains the skill instead of blocking the person answering.
+
+  Nothing about what gets written changed.
+
+## 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

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

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

@@ -14,32 +14,55 @@ question at a time, and write down what they actually say.
 
 ## 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.
+Ask them in the OWNER's words, not this project's. The vocabulary on this page
+— record, corpus, abstention, governance act — is precise and it is ours; an
+owner meeting it for the first time in a question cannot answer, and says so
+(reported 2026-08-26, against the wording these replaced: "the corpus wins
+about ___" asked them to complete a sentence that is not English unless you
+already know the ledger analogy).
+
+Ask exactly this much. Do not explain what the answer will be used for inside
+the question — that is what made the last version unanswerable.
+
+---
+
+**1 of 3 — What is this knowledge base about?**
+
+> Be specific enough that I would know what does NOT belong in it.
+>
+> Too vague: "our engineering docs" — I still could not tell what to leave out.
+> Specific enough: "our leave, expense and conduct policies, current versions
+> only."
+
+---
+
+**2 of 3 — What is close to that, but not part of it?**
+
+> Things people will ask this and it should NOT answer. A confident wrong
+> answer is worse than "I do not cover that."
+>
+> For the policies example: "not salaries, not individual HR cases, not last
+> year's versions."
+
+---
+
+**3 of 3 — Who signs off on a document, and who can take one down?**
+
+> Names or handles, not job titles. If it is just you, say so.
+
+---
+
+Follow up until each is concrete, but follow up in their words too: "what would
+someone actually ask this?" gets further than "name the boundary".
+
+**Why these three and no others.** The first two give the record an EDGE, and
+the abstention gate is meaningless without one: a knowledge base that is
+authoritative for everything has no outside, so an agent asked something the
+owner never wrote about reaches for its training instead of declining. The
+third cannot be guessed at all — the scaffold ships `human:you` in both
+authority lists, and a placeholder that survives this conversation is a person
+who was never there. Everything else has a sane default, and defaults are
+stated rather than asked.
 
 ## Then STATE the defaults; do not ask them
 

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

@@ -14,32 +14,55 @@ question at a time, and write down what they actually say.
 
 ## 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.
+Ask them in the OWNER's words, not this project's. The vocabulary on this page
+— record, corpus, abstention, governance act — is precise and it is ours; an
+owner meeting it for the first time in a question cannot answer, and says so
+(reported 2026-08-26, against the wording these replaced: "the corpus wins
+about ___" asked them to complete a sentence that is not English unless you
+already know the ledger analogy).
+
+Ask exactly this much. Do not explain what the answer will be used for inside
+the question — that is what made the last version unanswerable.
+
+---
+
+**1 of 3 — What is this knowledge base about?**
+
+> Be specific enough that I would know what does NOT belong in it.
+>
+> Too vague: "our engineering docs" — I still could not tell what to leave out.
+> Specific enough: "our leave, expense and conduct policies, current versions
+> only."
+
+---
+
+**2 of 3 — What is close to that, but not part of it?**
+
+> Things people will ask this and it should NOT answer. A confident wrong
+> answer is worse than "I do not cover that."
+>
+> For the policies example: "not salaries, not individual HR cases, not last
+> year's versions."
+
+---
+
+**3 of 3 — Who signs off on a document, and who can take one down?**
+
+> Names or handles, not job titles. If it is just you, say so.
+
+---
+
+Follow up until each is concrete, but follow up in their words too: "what would
+someone actually ask this?" gets further than "name the boundary".
+
+**Why these three and no others.** The first two give the record an EDGE, and
+the abstention gate is meaningless without one: a knowledge base that is
+authoritative for everything has no outside, so an agent asked something the
+owner never wrote about reaches for its training instead of declining. The
+third cannot be guessed at all — the scaffold ships `human:you` in both
+authority lists, and a placeholder that survives this conversation is a person
+who was never there. Everything else has a sane default, and defaults are
+stated rather than asked.
 
 ## Then STATE the defaults; do not ask them