@panaversity/ksor 0.0.32 → 0.0.34

package/CHANGELOG.md

@@ -1,5 +1,167 @@
 # @panaversity/ksor
 
+## 0.0.34
+
+### Patch Changes
+
+- e18ea08: The second site shell is retired (decision 9 revision, owner). Nothing an
+  adopter runs changes: `ksor init` has always emitted Fumadocs and never offered
+  a selector.
+
+  The proof did its job. It was built to answer whether the shell is really a slot
+  or whether the surface contract was just a description of what Fumadocs happens
+  to do, and it kept that contract honest through the visibility model,
+  attachments and the staging lock. What it costs now exceeds that: every surface
+  the record grows — quizzes, decks, slides, code tabs — has to be built twice or
+  the conformance suite goes red, and the second build is one nobody ships.
+  Maintaining a shell no adopter runs, to prove a property no adopter exercises,
+  is the "code is liability" test failing.
+
+  The five-clause surface contract survives unchanged and is still asserted,
+  against one implementation. The other clauses decision 9 always leaned on —
+  adopter ownership of `system/site`, registry-distributed shells later — are what
+  carry replaceability now. The swap recipe lives in git history; an adopter
+  actually swapping a shell restores the property as something live rather than
+  hypothetical.
+
+## 0.0.33
+
+### Patch Changes
+
+- 8f8d7b5: A third worked authorization recipe: Auth0, the hosted provider with a free
+  tier — written around the confusions rather than the happy path, because every
+  step in it is one that was got wrong first on a real tenant.
+
+  The recipe leads with the thing that causes the trouble: **Auth0's "API" is your
+  ksor door, and Auth0's "Application" is whoever calls it.** From there it covers
+  what a scripted caller needs versus an interactive one (they are two different
+  applications, because a machine-to-machine app has no browser and filling in its
+  callback field changes nothing), and the authorization step that hides — it
+  lives on the API rather than the application, and it is a `Grant Access` button
+  inside an `Edit` panel, not the toggle the table appears to offer.
+
+  Also records what Auth0 gets right: it honours RFC 8707, so an MCP client sending
+  `resource=<your mcp url>` receives a token audienced there with no vendor
+  parameter and no mapper.
+
+  Also answers the question that comes BEFORE any recipe and that the page never
+  addressed: **will your provider work at all?** Three checks — does it issue
+  RS256 JWTs rather than opaque tokens (the door verifies signatures itself and
+  makes no introspection call), does it publish RFC 8414 or OIDC metadata so the
+  keys can be discovered, and can it mint a token audienced at your identifier.
+  A provider failing any one of them cannot be used, and today that is discovered
+  several screens into a vendor console rather than in the first minute.
+
+  The page was then read cold by someone who had never used any of the three
+  providers, and their report is the rest of this change. It found the page
+  answered neither of the two questions a deployer has first, and contradicted
+  itself on a third:
+
+  - **What does this protect?** Only the MCP door. The website is a separate
+    surface and stays exactly as public as it was — now stated before anything
+    else, along with the fact that this is one gate rather than per-user rules
+    (the door reads no scopes; different readers seeing different documents is the
+    record's `audiences:` model, a different mechanism).
+  - **`KSOR_MCP_RESOURCE_URL` "never has to resolve"** was wrong. The authorization
+    server never fetches it, but a client does — it is where `www-authenticate`
+    points. An invented value boots green and breaks discovery silently.
+  - **`KSOR_AUTH` appeared only as "delete any"**, undefined, inside one recipe, so
+    readers of the other two never saw it — while a scaffold ships it SET. It is
+    now defined once, up front, as the first thing to remove.
+  - **`KSOR_SSO_URL` "is the issuer"** contradicted a later warning that the two
+    are deliberately different strings. The general rule is now stated once: one
+    is a base for path joining, the other is compared byte-exact.
+  - **"Three variables"** introduced a four-row table, and three more were
+    scattered across the page. Six now, in one table, with formats.
+  - **Nothing verified against the door.** A new section decodes the token
+    (`aud`/`iss` — the debugging step for this page's own stated failure mode) and
+    checks both the refusal and the acceptance, in that order.
+  - The Auth0 recipe dead-ended at "Save Changes" without saying what the client
+    credentials were for, and its step 3 read as permission to skip step 5 — the
+    step it calls "the one that hides".
+
+- 8f8d7b5: `deploying.md` and `ingesting.md` were each read by someone who had never used
+  the tool, told to find where the document stranded them. Both were, in the
+  reviewer's phrase, "the second half of a guide whose first half doesn't exist" —
+  prose by someone who had forgotten what it is like not to have the environment
+  already working. This is that first half, plus the contradictions the read
+  surfaced.
+
+  **A prerequisites block on both pages.** `ingesting.md` used the word "provider"
+  five times without ever naming Gemini, saying which variable holds the key, or
+  where to get one — a hard blocker on line 1. Neither page said the database needs
+  pgvector, where `knowledge/` lives, or which directory the commands run from.
+  `deploying.md` now opens with the four things that must exist and the order they
+  happen in, because its own text described skipping ingest as "the single most
+  common 'it deployed but does not work'" while telling the reader publishing was
+  "not on this page's critical path".
+
+  **A wrong claim about `gc`, corrected.** `ingesting.md` said `gc` "reaps the ones
+  nothing points at any more" directly after promising the previous generation as a
+  rollback target — reading as though the routine `pnpm refresh` destroys the safety
+  net it just created. It does not: `gc` never collects the active generation, the
+  rollback generation, or any generation a live snapshot token could pin, and always
+  leaves at least two standing.
+
+  **A verification section on both.** Neither page showed how to tell a working
+  record from a broken one — the failure `ingesting.md` opens by warning about had
+  no instrument. `deploying.md` gained the same for auth.
+
+  **Corrections found by the read:** the local `docker run` example could not work
+  as written (a container binds `0.0.0.0`, so it needs `KSOR_AUTH=disabled-public`
+  even on a laptop); the summary table sold the site as "upload a folder to any
+  static host" while its build refuses without a DSN; `KSOR_AUTH` had no documented
+  value for the SSO path (you unset it); `KSOR_ALLOWED_HOSTS`, `KSOR_ALLOWED_ORIGINS`
+  and snapshot-key rotation had no formats; `KSOR_MCP_RESOURCE_URL` was ambiguous
+  about the `/mcp` path; and an ordinary ingest needs a site rebuild too, which was
+  stated only for takedowns.
+
+  The pooler section — the longest technical passage in `ingesting.md`, about a
+  classification the same section calls informational — is cut to four sentences.
+
+  Adds a fourth recipe: **Better Auth**, an organization's own SSO — the case that
+  matters most for "vendor-free is the ownership argument", because it is the one
+  with no vendor in it. It is also the simplest shape on the page: a static public
+  client with PKCE, **no client secret**, no dynamic client registration, and no
+  authorize-this-client-for-that-resource step at all — the step that costs an
+  afternoon elsewhere simply does not exist.
+
+  Both it and Auth0 were connected to the same assistant against the same record,
+  changing only environment variables. That is the neutrality claim in its testable
+  form: **moving authorization servers is an environment change, not a code
+  change**, and the two audience variables do not change at all because they
+  describe the record rather than the provider.
+
+  Also names the vendor behind the JWKS fallback (`/api/auth/jwks` is Better
+  Auth's layout) — the cold read flagged it as "a vendor default and the vendor is
+  never named", and it turns out to be the same stack the door was first written
+  against.
+
+- 48f2a3c: Search the record in the language it is written in.
+
+  The scaffolded site pinned its search index to English tokenization. That is a
+  per-language splitter regex, and English's is Latin-only — so an Urdu, Chinese,
+  Japanese or Korean document indexed to **zero tokens** and could not be found,
+  while its page still rendered, still appeared in the sidebar, and still appeared
+  in `llms.txt`. Nothing went red. A record written in a non-Latin script was
+  published complete and silently unsearchable, which broke ksor's own claim to
+  hold "plain markdown, in any language you write in".
+
+  The pin bought nothing in exchange. Since fumadocs-core 16.14.0 the engine is
+  ZBSearch, which disables stemming and installs empty stopwords by default, so
+  `english` and `multilingual` return identical results on English text —
+  including the same miss (`recordings` does not find `recording`) under both.
+
+  The option is removed, so the engine keeps its own `multilingual` default and
+  segments every script. Existing English records are unaffected apart from a
+  small index-size change: the multilingual segmenter splits hyphenated
+  identifiers that the English splitter kept whole, which grows the exported index
+  by roughly 2% on a technical corpus.
+
+  Restoring stemming for any language remains available and is a separate,
+  deliberate change — it needs a stemmer dependency and the same tokenizer handed
+  to the browser, not a one-word option.
+
 ## 0.0.32
 
 ### Patch Changes

package/docs/authorization.md

@@ -9,28 +9,79 @@ status: draft
 posture, and it means the last step of a deployment is standing up an
 authorization server and pointing the door at it.
 
-This page is two worked recipes, both executed against real servers rather than
+This page is four worked recipes, all executed against real servers rather than
 written from their documentation, plus what an agent does to obtain a token. The
-mechanism is standard OAuth 2.0 — nothing here is specific to either product, and
-that is the point: two different implementations are shown because a single one
-proves nothing about neutrality.
+mechanism is standard OAuth 2.0 — nothing here is specific to any one product,
+and that is the point: three different implementations are shown because a
+single one proves nothing about neutrality. Two are self-hosted (one `docker
+run` each, no account), one is a hosted commercial provider with a free tier,
+and one is an organization's own SSO — which is the case that matters most,
+because it is the one where no vendor is involved at all.
+
+The claim they exist to support is narrow and testable: **moving between
+authorization servers is an environment change, not a code change.** Three
+variables point at a different provider and the door does not know the
+difference — no rebuild, no redeploy of the container, and the two audience
+variables do not even change, because they describe your record rather than
+the provider.
+
+## What this protects — and what it does not
+
+Read this before spending an afternoon on a provider's console.
+
+**It protects the MCP door, not the website.** Everything on this page is a
+bearer token on `POST /mcp`. Your static site is a separate surface, served by
+whatever hosts it, and configuring auth here leaves it exactly as public as it
+was. If people must not read the record at all, the site needs its own access
+control — or must not be published.
+
+**It is one gate, not per-user rules.** The door checks that a token was signed
+by the issuer you named and audienced at this record. It reads no scopes, no
+roles, no groups. **Any caller holding a valid token gets the whole record**, to
+the extent the audience tier allows. If different readers must see different
+documents, that is the record's `audiences:` / `visibility:` model, and it is a
+different mechanism from this page — see the scaffold's AGENTS.md.
+
+So: this page answers _"can a stranger read my record over MCP?"_ It does not
+answer _"can Alice read what Bob can."_
 
 ## What the door needs
 
-Three variables, and one more you should set even though it is optional:
-
-| variable                     | what it is                                                                    | where the value comes from                                                                          |
-| ---------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `KSOR_SSO_URL`               | your authorization server's base URL                                          | the AS itself; for OIDC it is the issuer, the URL whose `/.well-known/openid-configuration` answers |
-| `KSOR_MCP_RESOURCE_URL`      | **this record's** canonical URL — the identifier a token must be audienced at | you choose it; it is the public URL agents reach the door on                                        |
-| `KSOR_JWT_ALLOWED_AUDIENCES` | which audiences are accepted, comma-separated                                 | normally exactly `KSOR_MCP_RESOURCE_URL`                                                            |
-| `KSOR_SSO_ISSUER`            | the issuer to enforce                                                         | the `issuer` field of the AS's discovery document                                                   |
-
-`KSOR_MCP_RESOURCE_URL` is **not** a place the door fetches anything from. It is
-the name of this resource, in the RFC 8707 sense: a token minted for a different
-resource is refused even when the signature is perfect and the issuer is right.
-That is what stops a token issued for some other service being replayed at your
-record.
+**Three** variables turn auth on. The rest are hardening: add them once it
+works, not while you are trying to make it work.
+
+| variable                     | what it is                                                                    | where the value comes from                                       |
+| ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `KSOR_SSO_URL`               | your authorization server's base URL, used to FIND its metadata document      | the AS itself                                                    |
+| `KSOR_MCP_RESOURCE_URL`      | **this record's** canonical URL — the identifier a token must be audienced at | you choose it; it is the public URL agents reach the door on     |
+| `KSOR_JWT_ALLOWED_AUDIENCES` | which audiences are accepted, comma-separated                                 | normally exactly `KSOR_MCP_RESOURCE_URL`                         |
+| `KSOR_SSO_ISSUER`            | the issuer to enforce                                                         | the `iss` claim of a real token — see below                      |
+| `KSOR_ALLOWED_HOSTS`         | Host header allow-list, comma-separated `host:port` (bare host on 80/443)     | the hostname you serve on                                        |
+| `KSOR_SNAPSHOT_KEYS`         | `kid=secret[,kid2=secret2]`, first active; identical on every replica         | `openssl rand -hex 32` — used as literal text, never hex-decoded |
+
+**First, delete `KSOR_AUTH` if it is set.** It is the _auth-off_ posture —
+`disabled-local` for a loopback dev run, `disabled-public` to serve the record
+to anyone who can reach the port — and it wins over everything below. A scaffold
+ships with `KSOR_AUTH=disabled-local` in its `.env.example`, so a deployment
+that copied that file has it set and will stay unauthenticated no matter how
+carefully you configure the four variables above. Configuring the SSO door is
+what turns auth **on**; removing `KSOR_AUTH` is what stops it being off.
+
+Every variable here is read from the environment of the `ksor serve` process —
+your host's environment panel, or a `.env` beside `instance.md`. **Changing any
+of them requires restarting the door**; nothing is re-read at runtime.
+
+`KSOR_MCP_RESOURCE_URL` is this record's **name**, in the RFC 8707 sense: a
+token minted for a different resource is refused even when the signature is
+perfect and the issuer is right. That is what stops a token issued for some
+other service being replayed at your record.
+
+**Use the real URL agents reach the door on.** Your authorization server never
+fetches it — but a CLIENT does. An unauthorized request answers `401` with
+`www-authenticate: Bearer resource_metadata="…"`, and the client follows that to
+a document the door serves at its own host. Invent a value that does not resolve
+and the boot report will still look green while every standards-following client
+fails to discover where to authenticate.
 
 The door finds the signing keys by discovery, in this order, and says at boot
 which one it used:
@@ -39,15 +90,106 @@ which one it used:
 1. KSOR_JWKS_URL                        you stated the URI outright
 2. /.well-known/oauth-authorization-server   RFC 8414 metadata
 3. /.well-known/openid-configuration         OIDC discovery
-4. <KSOR_SSO_URL>/api/auth/jwks              a vendor default, reported as a GUESS
+4. <KSOR_SSO_URL>/api/auth/jwks              Better Auth's layout, reported as a GUESS
 ```
 
-**Set `KSOR_SSO_ISSUER`.** Without it, a token from a _different_ authorization
+**`KSOR_SSO_URL` and `KSOR_SSO_ISSUER` are different strings, and often differ
+by a trailing slash.** The first is a base that paths are joined onto; the
+second is compared **byte-exact** against the token's `iss` claim. Setting both
+to the same value is the commonest cause of a 401 on a perfectly good token.
+Mint one token, decode it, and copy `iss` out of it verbatim.
+
+**`KSOR_SSO_ISSUER` is optional, and you cannot set it correctly until auth
+already works** — it comes from a token you must first be able to mint. Get the
+three required variables working, decode a token, then add it. Unset, the issuer
+is simply not checked (`auth.ts:398`); the signature, the audience and the
+expiry all still are, and audience binding is what actually refuses a foreign
+token.
+
+What it buys is a better ERROR. Without it, a token from a _different_ authorization
 server produces an unknown key id, which is indistinguishable from key-rotation
 lag — so the door answers `503`, the client retries a credential that can never
 work, and a misconfiguration reads as an outage. With the issuer declared, that
 same token is refused `401` before any key is fetched.
 
+## Connecting an assistant — the way most people will use this
+
+The recipes below all end in a token you fetch with `curl`. That proves the door
+verifies tokens, and it is not what you actually want: you want to open an
+assistant and have it read your record. That path is the same for every provider,
+so it is written once, here.
+
+**What it needs from your provider — one browser client, separate from any
+machine one.** A `client_credentials` application has no browser and no redirect;
+filling in its callback field changes nothing. Create a second client that does
+`authorization_code`, and set its callback to the one your assistant uses. For
+Claude's hosted surfaces:
+
+```
+https://claude.ai/api/mcp/auth_callback
+```
+
+Then **authorize that client for your record's resource**. Every provider spells
+this differently — Auth0 calls it Application Access, Keycloak grants it through
+scope and audience mapping — and it is the step that most often looks done and
+is not. Skipping it gives an error at the authorization endpoint rather than at
+the token endpoint, so the login never even reaches your record:
+
+```
+Client "…" is not authorized to access resource server "https://your-host/mcp"
+```
+
+Finally, add the connector: the door's URL (`https://your-host/mcp`), plus the
+browser client's ID and secret. Those credentials go **into the assistant**,
+never into ksor — the door holds no client credentials and cannot mint a token
+for itself.
+
+**What you should see.** The assistant sends you to your provider's login page,
+you sign in, and it returns with the record's tools available. If instead you get
+a 401 from the door after a successful login, decode the token and compare `aud`
+against `KSOR_MCP_RESOURCE_URL` before looking anywhere else — that is the one
+failure that looks like a broken server and is a mismatched name.
+
+Standards-following clients send RFC 8707 (`resource=https://your-host/mcp`) on
+the authorization request, so a provider that honours it needs no vendor-specific
+audience parameter and no mapper.
+
+## Will your provider work? Three questions, before you start
+
+Answer these before creating anything. A provider that fails any one of them
+cannot be used, and you will not discover that until you are several screens
+into its console.
+
+**1. Does it issue RS256 JWTs, not opaque tokens?**
+The door verifies signatures itself (`algorithms: ["RS256"]`) and makes **no
+introspection call** — there is no code path that asks your provider whether a
+token is good. An opaque token it cannot read is a token it must refuse.
+
+**2. Does it publish a metadata document?**
+Keys are DISCOVERED, in this order: `KSOR_JWKS_URL` if you set it, then RFC 8414
+(`/.well-known/oauth-authorization-server`), then OpenID Discovery
+(`/.well-known/openid-configuration`). Any standards-compliant authorization
+server advertises `jwks_uri` in one of those. If yours publishes neither, you
+must supply `KSOR_JWKS_URL` yourself and hope it is stable.
+
+**3. Can it mint a token audienced at YOUR identifier?**
+Either through RFC 8707 (`resource=https://your-host/mcp` on the authorization
+request) or a vendor parameter (`audience=` on Auth0, an audience mapper on
+Keycloak). A provider that only ever issues tokens audienced at its own userinfo
+endpoint cannot express "this token is for that record", and audience binding is
+the whole point of the resource-server posture.
+
+### A provider that fails these
+
+Products built for **user sessions in your own app** frequently do. Their
+machine-to-machine tokens are minted and verified by calling _their_ backend —
+opaque by default, no OAuth token endpoint taking a custom audience, no metadata
+document. That is a coherent design; it is simply a different one, and adapting
+it means writing the verification layer ksor already is.
+
+The three recipes below all pass. If yours does too, they will read as the same
+recipe with different button names — because underneath they are.
+
 ## Recipe: Keycloak
 
 Run it:
@@ -140,6 +282,204 @@ Hydra publishes its keys at `/.well-known/jwks.json` rather than Keycloak's
 `/protocol/openid-connect/certs`. Nothing in ksor knows that; discovery reads it
 from the metadata document, which is why the door works against both unmodified.
 
+## Recipe: Auth0
+
+A hosted provider with a free tier, and the one whose vocabulary causes the most
+trouble — so this recipe is written around the confusions rather than around the
+happy path. Every step below is one that was got wrong first, on a real tenant.
+
+**Auth0's "API" is your ksor door. Auth0's "Application" is whoever calls it.**
+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.
+
+### 1. Describe the door
+
+**Applications → APIs → Create API.** The **Identifier** you type becomes the
+audience — use your record's MCP URL. It is a name, not a fetch target; it never
+has to resolve.
+
+```
+Name:       my-record
+Identifier: https://your-host.example.com/mcp
+```
+
+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.
+
+### 2. Point the door at the tenant
+
+```sh
+KSOR_SSO_URL=https://YOUR_TENANT.us.auth0.com
+KSOR_SSO_ISSUER=https://YOUR_TENANT.us.auth0.com/
+KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
+KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
+```
+
+**Mind the trailing slash on the issuer.** Auth0's `iss` carries one and
+`KSOR_SSO_URL` does not; they are deliberately different strings. Copy `iss`
+out of a real token rather than typing it.
+
+**Delete any `KSOR_AUTH`.** Configuring the SSO door is what turns auth on;
+leaving a disabled posture set keeps it off no matter what else is configured.
+
+### 3. A scripted caller (machine-to-machine)
+
+The test application already works **for this grant only** — creating the API
+authorized it. Do not read that as permission to skip step 5: any application
+you create yourself starts unauthorized, and that is where the next hour goes.
+
+Its credentials live under
+**Applications → Applications → `<API> (Test Application)` → Settings**.
+
+```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"}'
+```
+
+### 4. An interactive caller (a person, through a browser)
+
+An assistant that logs a human in needs a **different application**, because a
+machine-to-machine application has no browser and no redirect — filling in its
+callback field changes nothing.
+
+**Applications → Create Application → Regular Web Application**, then on it:
+
+- **Allowed Callback URLs**: the client's callback. For Claude's hosted
+  surfaces that is `https://claude.ai/api/mcp/auth_callback`.
+- **Save Changes** — the button is at the very bottom and nothing autosaves.
+
+Its **Client ID and Secret go into the client**, not into ksor — the connector
+form of whatever assistant you are configuring. The door never holds client
+credentials and cannot mint a token for itself; it only verifies what it is
+handed. Then do step 5, or the login will succeed and the token request will
+not.
+
+### 5. Authorize the caller for the door — the step that hides
+
+A new application is not allowed to request your API. Auth0 refuses with:
+
+```
+Client "…" is not authorized to access resource server "https://your-host.example.com/mcp"
+```
+
+The fix is on the **API**, not the application, and **it is not a toggle**:
+
+**APIs → your API → Application Access → find the application → `Edit` →
+`Grant Access`.**
+
+The greyed pills in that table are progress bars. The control is inside the side
+panel the `Edit` button opens, and `Grant ID: No per-app authorization grant`
+underneath confirms whether one exists.
+
+Pick the right column:
+
+| column                    | grant                | used by                                   |
+| ------------------------- | -------------------- | ----------------------------------------- |
+| **User-delegated Access** | `authorization_code` | an assistant acting as a signed-in person |
+| **Client Access**         | `client_credentials` | a script, worker or backend agent         |
+
+An application needs only the one it uses. Granting also ticks **"Always grant
+all permissions"**, which matters only if you later add scopes to this API —
+ksor checks issuer and audience, never scopes.
+
+### What Auth0 gets right
+
+It honours RFC 8707. An MCP client sending
+`resource=https://your-host.example.com/mcp` gets a token audienced there, with
+no `audience=` parameter and no mapper — which is why the authorization request
+works unmodified once the grant exists.
+
+## Recipe: Better Auth
+
+The simplest of the four, and the one the door was originally written against —
+the JWKS fallback in `auth.ts` is Better Auth's layout (`/api/auth/jwks`), which
+is why an unconfigured `KSOR_JWKS_URL` still finds keys on a Better Auth
+deployment even if discovery never runs.
+
+It is also the only recipe here with **no client secret**, because a static
+public client with PKCE is enough:
+
+```sh
+KSOR_SSO_URL=https://auth.your-org.example
+KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
+KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
+```
+
+Three variables, no fourth. Register one OAuth client with:
+
+- **PKCE required**, `token_endpoint_auth_method: none` — a public client, so
+  there is no secret to distribute, rotate, or leak into a config file
+- the assistant's callback in its redirect list
+  (`https://claude.ai/api/mcp/auth_callback` for Claude's hosted surfaces)
+
+### Why this shape is worth preferring
+
+**Nothing to authorize afterwards.** The step that costs an afternoon on Auth0 —
+finding where a client is granted access to a resource server — does not exist
+here. A registered client can request your resource.
+
+**No dynamic client registration.** DCR is what an assistant falls back to when
+you have not given it a client, and it brings its own tenant-wide toggles and
+third-party permission defaults. A statically-registered public client skips all
+of it.
+
+**No secret in the assistant's config.** PKCE proves the caller is the same one
+that started the flow, without a shared secret. There is simply less to get
+wrong, and less to leak.
+
+If your organization runs its own SSO, this is the shape to ask for.
+
+## Verify it — against the door, not the provider
+
+If you connected an assistant and it read your record, auth works — that is the
+end-to-end proof and you can stop here.
+
+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.
+
+**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:
+
+```sh
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '{iss, aud, exp}'
+```
+
+- `aud` must equal your `KSOR_MCP_RESOURCE_URL`. If it is your provider's
+  `/userinfo` endpoint, the audience never carried — fix that before anything
+  else.
+- `iss` is what belongs in `KSOR_SSO_ISSUER`, character for character.
+
+**2. No token must be REFUSED.** Run this first; it is the half that proves auth
+is on at all:
+
+```sh
+curl -s -i -X POST https://your-host.example.com/mcp \
+  -H 'content-type: application/json' -d '{}' | head -5
+```
+
+Expect `401`, and a `www-authenticate: Bearer resource_metadata="…"` header. A
+`200` here means auth is off — check `KSOR_AUTH` is unset and that you restarted.
+
+**3. A good token must be ACCEPTED:**
+
+```sh
+curl -s -X POST https://your-host.example.com/mcp \
+  -H "authorization: Bearer $TOKEN" \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+Expect the record's tools. A `401` here with a `200` above means the token is
+being read and rejected — go back to step 1 and compare `aud` and `iss`.
+
 ## What an agent does
 
 Ask the token endpoint for a token audienced at the record, then send it as an
@@ -187,7 +527,10 @@ A genuine key-rotation lag stays a `503` on purpose: it is transient, retrying i
 the right response, and the refusal is never cached — a valid bearer is
 re-admitted the instant the key set catches up.
 
-## Before a public bind
+## Before a public bind — recap
+
+Everything here is stated above; it is repeated because it is the checklist you
+want open while deploying.
 
 - Auth configured as above, **or** `KSOR_AUTH=disabled-public` set
   deliberately — the door will not come up on a public address without one of

package/docs/deploying.md

@@ -5,6 +5,36 @@ status: draft
 
 # Deploying a Knowledge System of Record
 
+## Before you start
+
+Four things must exist, and the order matters. Nothing below works without them,
+and three of the four are outside this page.
+
+|     | what                                                 | where                                                                                    |
+| --- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| 1   | **A Postgres with pgvector** — a managed one is fine | your provider; `CREATE EXTENSION vector;`                                                |
+| 2   | **A provider key** for embeddings — `GEMINI_API_KEY` | [aistudio.google.com](https://aistudio.google.com/apikey) — free tier is enough to start |
+| 3   | **The schema applied, and ingest authorized**        | `pnpm provision` (runs `ksor schema` + `ksor grant`)                                     |
+| 4   | **A published generation**                           | `pnpm refresh` (runs `ksor ingest --flip`)                                               |
+
+Steps 3 and 4 are [ingesting.md](./ingesting.md), and **they come before your
+first deploy, not after**. A door with no published generation boots healthy and
+serves an empty record — the single most common "it deployed but does not work".
+
+The whole sequence, end to end:
+
+```
+provision the database  →  ksor schema  →  ksor grant  →  ksor ingest --flip
+       →  set environment variables  →  deploy  →  verify  →  calibrate
+```
+
+Calibration is last on purpose: it measures the corpus, so the corpus has to be
+in there first. Until you run it, `/health` will report `abstain OFF` and the
+record will answer out-of-corpus questions instead of declining — honest, and
+not what most people want to ship.
+
+---
+
 A KSoR publishes two surfaces from one record, and they deploy differently
 because they are different things:
 
@@ -50,6 +80,14 @@ docker build -t my-record .
 docker run --rm -p 8080:80 --env-file .env my-record
 ```
 
+Two things about that command, both of which bite:
+
+- **The image listens on 80**, which is why the mapping is `8080:80`. If your
+  `.env` sets `PORT`, change the right-hand side to match.
+- **`.env` must contain `KSOR_AUTH=disabled-public`, even locally.** A container
+  gets `$PORT` and therefore binds `0.0.0.0` — a public bind — and
+  `disabled-local` refuses there by design. Your laptop is not the exception.
+
 That runs on Cloud Run, Fly, Render, ECS, Kubernetes, or a VPS with no changes.
 `vercel.json` **points at this same file** rather than replacing it, which is
 what keeps the host a choice — the artifact is yours, and moving it is a
@@ -121,6 +159,11 @@ KSOR_AUTH=disabled-local    # no auth, loopback only — a public bind REFUSES
 KSOR_AUTH=disabled-public   # no auth, and served to anyone who can reach the port
 ```
 
+`KSOR_AUTH` has no "on" value. Auth is on when the SSO door is configured and
+`KSOR_AUTH` is **absent**; setting it to either value turns auth off. If you
+move from a disabled posture to a real provider, deleting the variable is part
+of the change.
+
 **A container sets `$PORT`, so the door binds `0.0.0.0` — a public bind.**
 `disabled-local` refuses there, deliberately: copying a dev `.env` into a hosting
 dashboard must not quietly open your record to the internet. `disabled-public` is
@@ -152,7 +195,14 @@ KSOR_SNAPSHOT_KEYS="k1=$(openssl rand -hex 32)"
 ```
 
 `k1` is a label, not a secret — it appears in the token as `key_id` so you can
-rotate later. The secret is used as literal text, never hex-decoded, and must be
+rotate later. Rotation is comma-separated, newest first, keeping the old key
+until outstanding tokens age out (30 minutes):
+
+```sh
+KSOR_SNAPSHOT_KEYS="k2=<new secret>,k1=<old secret>"
+```
+
+The secret is used as literal text, never hex-decoded, and must be
 byte-identical across every instance of one deployment. Set it once and leave it
 alone: rotating invalidates every outstanding pin, and a compromised snapshot key
 cannot read a withdrawn document, cross an audience boundary, or authenticate

package/docs/index.md

@@ -68,9 +68,9 @@ instance declares an `audiences:` model, documents may carry a
 `visibility:` key and per-audience builds (`KSOR_AUDIENCE=<tier> pnpm
 build`) stage only what that tier may see — publication, not authorship:
 anyone who can clone reads everything. The site shell
-at `system/site/` is replaceable behind a five-clause surface contract; a
-Docusaurus conformance shell lives in the ksor repository under
-`workbench/shells/docusaurus/` with its swap recipe.
+at `system/site/` is replaceable behind a five-clause surface contract — the
+shell is a slot, and the contract (render the record, `llms.txt`, per-page md
+artifacts, browser smoke, no authored content) is what a replacement must meet.
 
 ## Where truth lives
 

package/docs/ingesting.md

@@ -14,6 +14,23 @@ 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.
 
+## Before the first command
+
+Ingest reads your markdown, sends each new chunk to an embedding provider, and
+writes the result to Postgres. So four things must be true, and none of them is
+created for you.
+
+|                      | what                                                                                                          | how                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **The corpus**       | `knowledge/` at your repo root — CommonMark `.md`, one document per file, `title` and `status` in frontmatter | `pnpm check` validates it and explains any violation                                           |
+| **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                                         |
+
+Both variables go in `.env` beside `instance.md` — `ksor` reads it automatically,
+and `.env` is gitignored. Every command below is run **from your repository
+root**, where `instance.md` and `package.json` live.
+
 ## The order, once
 
 ```sh
@@ -29,17 +46,29 @@ existing grant says "already granted".
 Then, after every change to `knowledge/`:
 
 ```sh
-pnpm refresh
+pnpm refresh   # publishes to the agent surface
+pnpm build     # rebuilds the website from the same corpus
 ```
 
+**Both surfaces, every time.** `refresh` publishes a generation the MCP door
+serves immediately; the website is a static build and only changes when you
+rebuild and redeploy it. Ingest alone leaves the human surface showing the old
+content, which reads as a half-failed ingest and is not one.
+
 ## What a generation is
 
 Each ingest builds a **fresh generation** — invisible until activated — and
 carries every unchanged embedding forward from the last complete one, matched by
 content hash. Only changed or previously-failed chunks are re-embedded.
 
-`--flip` swaps the active pointer. The previous generation stays as a rollback
-target; `ksor gc` reaps the ones nothing points at any more.
+`--flip` swaps the active pointer, and the previous generation stays as a
+rollback target.
+
+**`gc` will not take it.** It never collects the active generation, the rollback
+generation, or any generation a live snapshot token could still pin, and it
+always leaves at least two complete generations standing. That is why `pnpm
+refresh` can safely run `ingest` and `gc` back to back — the routine command
+does not eat the safety net it just created.
 
 Three consequences worth knowing:
 
@@ -56,6 +85,31 @@ A flip that would drop more than `KSOR_MAX_SHRINK` of the record (default
 `0.15`, i.e. 15%) **refuses**. When a large deletion is intended, say so:
 `KSOR_ALLOW_SHRINK=1`.
 
+## Did it work?
+
+The failure this page opens with — a healthy door serving an empty record — is
+invisible unless you look. Three checks, cheapest first:
+
+```sh
+# 1. the door knows which corpus it serves, and its embedding space is intact
+curl -s http://127.0.0.1:8080/health
+
+# 2. something is actually published — ask for the record's structure
+curl -s -X POST http://127.0.0.1:8080/mcp \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"outline","arguments":{}}}'
+```
+
+An empty `nodes` array means nothing was published — the ingest did not run, or
+ran without `--flip`. Then search for a phrase you know is in the record and
+check the hits carry `provenance.stable_id` and `generation`.
+
+**`provenance.stable_id` is also how you name a document to `takedown`.** For
+most documents it is `knowledge/<path-without-.md>`; a search result is the
+reliable way to read one off rather than guessing.
+
 ## Where ingest runs — not on the host
 
 Ingest is a long job. It embeds every new chunk through the provider, and that
@@ -88,22 +142,14 @@ carries forward everything that was already embedded, including from a
 generation that was still `building` when it died, so a resumed run pays only
 for what the first one had not reached.
 
-## Endpoints, poolers, and what actually matters
+## Endpoints and poolers
 
 If your provider offers both a **pooled** and a **direct** endpoint (Neon's
-`-pooler` host, or anything on port 6432), ksor detects which one you gave it
-and says so in the boot report. That line is **informational**: it classifies,
-it never transforms. The hazard it descends from — a transaction pooler and
-server-side prepared statements — cannot arise here, because node-postgres does
-not auto-prepare.
-
-For the record: the 6,963-chunk ingest above ran through a **pooled** endpoint
-without incident, and the same DSN serves. Use whichever your provider gives
-you, and reach for the direct endpoint only if you actually hit pooler
-connection limits under a parallel ingest — not pre-emptively.
-
-`KSOR_DB_POOLED_ENDPOINT=1` forces the classification when your host name does
-not announce itself.
+`-pooler` host, or port 6432), use whichever it gives you. ksor detects which and
+says so at boot, but the line is informational — it classifies, it never
+transforms, and the hazard it descends from cannot arise here. The 6,963-chunk
+ingest measured above ran through a pooled endpoint without incident. Reach for
+the direct endpoint only if you actually hit pooler connection limits.
 
 ## Turning the abstention gate on
 
@@ -115,8 +161,8 @@ measure until the corpus is in there.
 pnpm exec ksor calibrate --instance instance.md
 ```
 
-It prints a recommended `vector_floor`. Paste it in with the date you measured
-it, and restart:
+It prints a recommended `vector_floor`. Paste it into **`instance.md`** with the
+date you measured it, then restart `ksor serve` — the floor is read at boot:
 
 ```yaml
 retrieval:

package/package.json

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

@@ -708,8 +708,8 @@ You own `system/site/` outright — these are the seams, cheapest first:
   documentation shell around it stay one palette.
 - **Anything deeper** — edit the site like the Next.js app it is; the only
   rule that survives customization is critical rule 1. The whole shell is
-  replaceable behind a five-clause contract (a themed Docusaurus shell with
-  a swap recipe lives in the ksor repository under `workbench/shells/`).
+  replaceable behind a five-clause contract: render the record, `llms.txt`,
+  per-page md artifacts, browser smoke, and no authored content.
 
 ## What this project owns
 

package/templates/scaffold/system/site/app/api/search/route.ts

@@ -5,7 +5,18 @@ import { createFromSource } from "fumadocs-core/search/server";
 // search dialog downloads and queries client-side (see app/layout.tsx).
 export const revalidate = false;
 
-export const { staticGET: GET } = createFromSource(source, {
-  // https://docs.orama.com/docs/orama-js/supported-languages
-  language: "english",
-});
+// NO `language:` option, deliberately. The engine's own default is
+// `multilingual`, which segments with `Intl.Segmenter` and indexes every script;
+// naming a language selects a per-language splitter regex instead. `english`'s
+// is Latin-only, so an Urdu or Chinese document indexed under it produces ZERO
+// tokens and is unreachable by search — while its page still renders, still sits
+// in the sidebar and still appears in llms.txt. Nothing goes red. That silently
+// broke the record's own claim to hold "plain markdown, in any language they
+// write in" (found by reading the shipped tokenizer, 2026-08-24).
+//
+// It bought nothing in exchange: since fumadocs-core 16.14.0 the engine is
+// ZBSearch, which disables stemming and ships empty stopwords by default, so
+// `english` and `multilingual` return identical results on English text.
+// Restoring stemming is a separate, larger decision — it needs a stemmer
+// dependency AND the same tokenizer handed to the browser through `initDB`.
+export const { staticGET: GET } = createFromSource(source);