@aotter/mantle 0.1.2-rc.1 → 0.1.3-alpha.1

package/docs/agent-prompts.md

@@ -1,10 +1,36 @@
 # Task-specific agent prompts
 
-Copy one block into a coding agent. Resolve handbook pages and official
-examples from `docs/` in this checkout, or from
-`node_modules/@aotter/mantle/docs/` after install. If neither tree exists,
-pin `@aotter/mantle` first. `npx --no-install mantle --help` is the layered
-overview. There is no `mantle create`. Admin is opt-in.
+Cold start from GitHub or a marketplace host is one pinned skill:
+
+```sh
+npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+```
+
+Copy one block into a coding agent after that skill is present. Paths below
+are relative to the Mantle docs root: `node_modules/@aotter/mantle/docs/`
+after `@aotter/mantle` is installed, or `docs/` in the installed agent plugin.
+`npx --no-install mantle --help` is the layered CLI overview; it mirrors the
+authoring docs. A live `/mcp` catalog mirrors the Manifest → RuntimePlan, not
+the CLI. Interview first. Worker is the default host unless the user names
+ChatGPT Sites. There is no `mantle create`. Empty `generate` fails until
+manifests exist. Admin is opt-in.
+
+### Interview then build
+
+```text
+Interview me about the service: host, who uses it, whether humans need a
+Dev UI, and whether we only embed Spec/Runtime. If the install skill is
+missing, run npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install. Read the
+install skill and npx --no-install mantle --help, then
+handbook/start/project-and-cli.md.
+Use examples/README.md as the examples index; copy builtin-* Manifests only
+(not cf-primitives-*). Implement locally first. Take only the surfaces we
+chose. For Spec-only use, skip Runtime and code generation. For a Worker
+without Admin, follow examples/host-minimal-worker/. For a Worker with
+Dev UI, follow examples/host-local-admin-otp/README.md. ChatGPT Sites only
+if I name that host. No mantle create. Pin all @aotter/mantle* packages
+to one exact version.
+```
 
 ### Embed Runtime with typed APIs
 
@@ -32,30 +58,11 @@ Admin or wrangler ASSETS unless I ask.
 ### Full local Dev UI (opt-in)
 
 ```text
-I want the optional Admin / Dev UI. Read handbook/start/quickstart-admin.md
-and examples/host-local-admin-otp/. Interview me for a bootstrap owner email.
-Install @aotter/mantle-admin and @aotter/mantle-admin-ui, run
-mantle generate (it syncs the prebuilt SPA — do not vite-build), and set
-wrangler assets.directory=./public with binding ASSETS (required when
-Admin is installed). Wire createAuth email-otp + ConsoleEmailSender.
-Then pnpm install && pnpm generate && pnpm dev, open /admin/sign-in, and
-read the OTP from wrangler logs. If /admin is a white screen, fetch
-/_mantle/admin/assets/* — 404 means ASSETS is missing, not a missing
-frontend build.
-```
-
-### Interview then build
-
-```text
-Interview me about the service: host, who uses it, whether humans need a
-Dev UI, and whether we only embed Spec/Runtime. Read mantle --help, then
-handbook/start/project-and-cli.md. Use docs/examples/README.md as the
-examples index; copy builtin-* Manifests only (not cf-primitives-*).
-Implement locally first. Take only the surfaces we chose.
-For Spec-only use, skip Runtime and code generation. For a Worker without
-Admin, follow examples/host-minimal-worker/. For a Worker with Dev UI,
-follow examples/host-local-admin-otp/. No mantle create. Pin all
-@aotter/mantle* packages to one exact version.
+I want the optional Admin / Dev UI. Read examples/host-local-admin-otp/README.md
+(the procedural SSOT) and the thin pointer at handbook/start/quickstart-admin.md.
+Interview me for a bootstrap owner email, then follow that example locally.
+Prefer 127.0.0.1 over localhost. After pnpm check / smoke, restore .dev.vars
+from .dev.vars.example before pnpm dev.
 ```
 
 ### Later layer: MCP or public web (opt-in)
@@ -71,12 +78,13 @@ claim Auth or Admin works from a public 200.
 
 ### Mantle on ChatGPT Sites, including media
 
+Use only when the user names ChatGPT Sites as the host.
+
 ```text
 Build with ChatGPT Sites; use Mantle for content management and publishing.
-Read the matching SDK docs/handbook/sites/index.md and
-docs/examples/host-chatgpt-sites/README.md. Use that runnable host as a
-reference. Follow its supported installation path, including packed-checkout
-installation while release support is pending. Derive Schema, View,
+Read handbook/sites/index.md and examples/host-chatgpt-sites/README.md.
+Use that runnable host as a reference and install its pinned
+dependencies from the registry. Derive Schema, View,
 Procedure and Trigger from my requirements and check the Admin editor/picker and public
 projections against them. Request both Sites D1 and R2 when my workflow
 includes uploads. Bind the R2 media port, declare media.purposes, and keep

package/docs/auth-hosting-model.md

@@ -8,7 +8,7 @@ basic login. The split is:
 - **Mantle's conventional Cloudflare adapter** runs the generated site's
   selected self-hosted or Mantle Platform hosted client configuration.
 - **The application owner/host** declares the explicit auth mode and provider
-  configuration; legacy Landing/Starters remain on alpha.17.
+  configuration.
 - **Mantle Platform** can sell hosted identity, provider setup, email,
   and billing convenience for site owners who do not want to operate
   those pieces.

package/docs/examples/host-chatgpt-sites/README.md

@@ -2,21 +2,35 @@
 
 The runnable application for [Mantle on ChatGPT Sites](../../handbook/sites/index.md) connects Sites D1 + R2 bindings, Sign in with ChatGPT identity, Mantle Admin and staff roles, same-origin media upload, a published-only article frontend, anonymous read-only `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. Remote OAuth MCP remains a separate integration; see [MCP support](../../handbook/sites/host-reference.md#remote-mcp-is-a-separate-gate).
 
-**SDK requirement:** this revision requires the checkout's `mountMantleAdmin.mcpEndpoints` support. Published `0.1.2-alpha.6` does not include it, even though the checkout still carries that version number. Use the exact packed-checkout workflow below; copying this folder and running `npm ci` against the registry is not a supported reproduction of this revision. Build typechecking and the endpoint smoke assertions reject that mismatch. Once a release contains this change, update every Mantle dependency and the lockfile together before switching back to registry installation.
-
 After setup, follow [Publish your first article](../../handbook/sites/index.md#publish-your-first-article) to verify the editorial workflow in Admin.
 
 ## Before writing code
 
 Read the user's business request and author the manifest for **their** records and lifecycle. The included `articles` example deliberately allows a title-only draft; `body` uses `x-mcp-hint: markdown`, while `coverAssetId` uses both `x-mantle-ref: media_assets` (Admin picker) and `x-mcp-hint: media-image` (agent guidance). The `published-articles` View is a list projection, not the detail page contract. If the user's content must always have a body, add it to `required`; if the public API must return body or cover ID, add those to the View's `fields`. Review staff roles, public filters and indexes before deployment. `mantle validate` checks grammar, **not** whether this model matches the business request. Manifest changes after deployment require a new reviewed D1 migration and matching storage fingerprint; never edit an applied migration.
 
-## Local reproduction
+## Install and run
+
+Requires Mantle 0.1.2 or newer. Copy this directory outside the SDK checkout, then:
+
+```bash
+npm install                                  # or: bun install
+npx mantle validate --phase deploy           # or: bunx mantle ...
+npm run generate && npm run check
+npx wrangler d1 migrations apply DB --local
+npm run dev -- --port 4174                   # leave running
+npm test                                     # smoke, in a second terminal
+```
+
+`npm install` resolves `@aotter/mantle*` from the `latest` dist-tag; this
+example does not commit a lockfile, so every fresh install picks up the
+current stable release. `bun install` works too, resolving from
+`package.json` the same way.
+
+Keep `.openai/hosting.json`; do not copy an existing Site's `project_id`. To use another port, also set the Worker's `PUBLIC_ORIGIN` and the test's `MANTLE_TEST_ORIGIN` to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
+
+Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
 
-1. Start from a clean, committed Mantle checkout containing this change. Record its `git rev-parse HEAD`, then run `pnpm install --frozen-lockfile` and `pnpm build` from the repository root.
-2. Run `node scripts/check-packed-consumer.mjs --project docs/examples/host-chatgpt-sites --output /absolute/path/to/new-sites-reproduction -- pnpm build`. The output path must not exist and must be outside the SDK checkout. This existing helper copies the committed example, packs the SDK, installs exact tarball overrides for all Mantle packages, and reports the source SHA and package hashes. Keep the resulting `artifacts/` beside `consumer/` so the lockfile's tarball paths remain valid.
-3. Work in `/absolute/path/to/new-sites-reproduction/consumer`. Run `pnpm exec mantle validate --phase deploy`, `pnpm check`, then `pnpm exec wrangler d1 migrations apply DB --local`. Keep `.openai/hosting.json` but do not copy an existing Site's `project_id`.
-4. Start `pnpm dev --port 4174` in another terminal, then run `pnpm test`. To use another port, also override the Worker's `PUBLIC_ORIGIN` and set `MANTLE_TEST_ORIGIN` for the test to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
-5. Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
+To run this example against an unreleased Mantle checkout instead of the registry, use `node scripts/check-packed-consumer.mjs --project docs/examples/host-chatgpt-sites --output <new dir> -- pnpm build` from a clean SDK checkout and work in its `consumer/`. That path is for SDK development only.
 
 The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest. `scripts/migration.mjs` shows the one-time generation mechanism; do **not** run it against a deployed database or overwrite an applied migration. For a new business manifest, generate/review an initial migration before the first deployment; for a later change, generate an additive migration from the previous schema state.
 

package/docs/examples/host-chatgpt-sites/package.json

@@ -1 +1 @@
-{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"0.1.2-alpha.6","@aotter/mantle-admin":"0.1.2-alpha.6","@aotter/mantle-admin-ui":"0.1.2-alpha.6","@aotter/mantle-cloudflare":"0.1.2-alpha.6","@aotter/mantle-web":"0.1.2-alpha.6","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.25.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}
+{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}

package/docs/examples/host-chatgpt-sites/src/index.ts

@@ -23,7 +23,7 @@ function assemble(env:Env) {
   mountWeb(app,get);
   mountMcp(app,get,auth);
   mountMedia(app,auth,env);
-  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2-alpha.6'});});
+  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2'});});
   app.get('/admin/sign-in',async c=>{
     if(c.req.header('cookie')?.split(';').some(v=>v.trim()==='mantle-sites-signout=1')) {
       c.header('Set-Cookie','mantle-sites-signout=; Path=/admin/sign-in; HttpOnly; SameSite=Strict; Max-Age=0'+(env.PUBLIC_ORIGIN.startsWith('https:')?'; Secure':''));

package/docs/examples/host-local-admin-otp/README.md

@@ -9,10 +9,9 @@ Schema is example business data; `mantle generate` never invents it.
 Spec + adapter without Admin:
 [`docs/examples/host-minimal-worker`](../host-minimal-worker/README.md).
 
-Pin every `@aotter/mantle*` package to the exact version in this snapshot
-(`packages/mantle/package.json`). This reference records that version as
-its published baseline; Core's test runner substitutes its exact candidate
-in a disposable copy.
+This reference depends on every `@aotter/mantle*` package via the `latest`
+dist-tag, so a fresh install always resolves the current stable release.
+Core's test runner substitutes its exact candidate in a disposable copy.
 
 ## One-shot
 
@@ -59,6 +58,16 @@ paths must fall through to Static Assets.
 
 `ConsoleEmailSender` is the local path only. Do not wire it in production.
 
+## Local traps
+
+- Prefer `http://127.0.0.1:8787` over `http://localhost:8787`. Wrangler still
+  serves HTML on localhost, but the OTP `Origin` header will not match
+  `PUBLIC_ORIGIN` and Better Auth returns `INVALID_ORIGIN`.
+- `pnpm check` runs `smoke.mjs`, which rewrites `.dev.vars` to a smoke-only
+  port (`18787`). Restore `.dev.vars` from `.dev.vars.example` (or delete it
+  and let `predev` recopy) before `pnpm dev`, or OTP will fail with
+  `INVALID_ORIGIN` against the Ready-on `8787` origin.
+
 ## What this project does not do
 
 `/` is `404`: no visitor frontend is installed. Public GET

package/docs/examples/host-local-admin-otp/package.json

@@ -11,10 +11,10 @@
     "check": "node ensure-dev-vars.mjs && mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-admin": "0.1.2-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-admin": "latest",
+    "@aotter/mantle-admin-ui": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",

package/docs/examples/host-minimal-worker/README.md

@@ -9,9 +9,10 @@ Schema/View is example business data; `mantle generate` never invents it.
 
 For your own project, author package.json, manifests, Worker/provider config
 and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. This reference records the snapshot
-version in this tree as its published baseline; Core's test runner substitutes
-its exact candidate in a disposable copy.
+dependencies to the same intended release. This reference depends on them via
+the `latest` dist-tag instead, so a fresh install always resolves the current
+stable release; Core's test runner substitutes its exact candidate in a
+disposable copy.
 
 Outside the SDK workspace, with Node 22+ and pnpm 9+:
 

package/docs/examples/host-minimal-worker/package.json

@@ -10,8 +10,8 @@
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",

package/docs/handbook/cloudflare/authentication.md

@@ -77,7 +77,7 @@ The staff role is re-read from D1 on every protected REST and MCP call; a revoke
 |---|---|
 | `/admin`, `/admin/api/*` | Staff session; role gates per route |
 | `/api/auth/*`, `/oauth/*`, `/.well-known/oauth*` | Auth-owned; public endpoints of the OAuth flow |
-| `/mcp` | Any authenticated OAuth caller; anonymous requests get `401` with a `WWW-Authenticate` challenge |
+| `/mcp` | Same caller resolution as HTTP routes (bearer, same-origin cookie session, or anonymous); each tool's `requires` gates the call, and a call that needs identity answers `401` with a `WWW-Authenticate` challenge |
 | `/mcp/staff` | Authenticated caller with a staff role |
 | `/<locale>/<segment>/<slug>?preview=1` | Staff session (`401` without a session, `403` without a staff role) |
 | Public Views, public HTTP Triggers, public pages, `.md`, `llms.txt`, sitemap | None, unless the manifest declares `requires` |
@@ -112,8 +112,10 @@ methods: [
 ]
 ```
 
-Email OTP and magic-link storage defaults to `hashed`. Explicit official
-overrides remain available, including custom hashing/encryption:
+Email OTP storage defaults to a keyed HMAC-SHA-256 of the code using
+`BETTER_AUTH_SECRET`. Magic-link tokens remain `hashed` (high-entropy).
+Explicit official overrides remain available, including `plain` and custom
+hashing/encryption:
 
 ```ts
 { kind: "email-otp", sender, options: {
@@ -154,6 +156,45 @@ const auth = createAuth({
 
 Shared cookies do not cross registrable domains. A browser never sends an `example.com` cookie to `customer.com`. For a customer-owned domain, use an OAuth/OIDC broker flow: the customer site redirects to the identity provider's authorize endpoint, receives the callback, verifies the response and creates its own local session. The broker returns identity; the customer site remains the authority for its members and grants.
 
+### Account linking across providers
+
+One person signing in with Google, then with GitHub, may land on one user row
+or be refused — Better Auth decides this, and `createAuth()` does not override
+it. Left unconfigured, Better Auth's own defaults apply: implicit linking is
+on, so a social sign-in whose provider reports a verified email attaches to the
+existing row carrying that email. It never creates a second row for the same
+address; when linking is not permitted the sign-in fails with
+`account not linked`.
+
+Two defaults are worth knowing before you change anything. `requireLocalEmailVerified`
+is on, so linking is refused while the *local* row is still unverified — this is
+what stops someone pre-registering an unverified row at your user's address and
+having that user's Google identity attach to it. It is also why a staff invitation
+(`inviteUser` writes `emailVerified: 0`) cannot be claimed by a social sign-in
+until the invitee verifies by email once. Separately, `trustedProviders` is
+empty, so every provider must supply `email_verified` to link at all.
+
+Pass `accountLinking` to scope this. It is forwarded verbatim:
+
+```ts
+const auth = createAuth({
+  database: env.DB,
+  baseURL: env.PUBLIC_ORIGIN,
+  secret: env.BETTER_AUTH_SECRET,
+  methods,
+  accountLinking: {
+    // Accept these providers' word without an `email_verified` claim.
+    trustedProviders: ["google", "github"],
+  },
+});
+```
+
+Listing a provider in `trustedProviders` asserts that it verifies the addresses
+it returns; a provider that does not turns the list into an account-takeover
+path. To go the other way and keep every identity separate, set
+`disableImplicitLinking: true` (users may still link deliberately via
+`linkSocial()` while signed in) or `enabled: false` to refuse linking outright.
+
 ## Self-hosted and hosted
 
 A free self-hosted site runs every method `createAuth()` exposes: Better Auth social providers, email OTP, magic link, and parent-domain SSO. The owner supplies provider credentials, email sending and cookie policy. Hosted auth is an operations convenience: the platform holds provider and email configuration and registers the site as a PKCE client, while the site still owns grants, members, content and `ctx.user`/`ctx.staff` mapping. Neither mode changes the runtime's authorization vocabulary.

package/docs/handbook/concepts/mcp-and-agents.md

@@ -3,13 +3,13 @@ description: Mantle serves /mcp and /mcp/staff from the same Manifest — tool n
 ---
 # MCP and agents
 
-Mantle is an MCP server out of the box. Nothing is registered, exported or annotated to make it one: the same compiled plan that produces REST and Admin also produces the tool catalog, so an agent and a browser reach identical behavior through different transports. This page covers the two surfaces, how tools are named, how a client authenticates, and the rest of the agent-facing surface area.
+Mantle is an MCP server out of the box. Nothing is registered, exported or annotated to make it one: the same compiled plan that produces REST and Admin also produces the tool catalog, so an agent and a browser reach identical behavior through different transports. `/mcp` and `/mcp/staff` are that live-app catalog — Manifest → RuntimePlan verbs — not a how-to-author-Mantle manual. The CLI and pinned package docs are the authoring SSOT; MCP does not mirror the CLI. This page covers the two surfaces, how tools are named, how a client authenticates, and the rest of the agent-facing surface area.
 
 ## Two surfaces
 
 | Mount | Caller | Exposes |
 |---|---|---|
-| `/mcp` | Any authenticated OAuth caller; anonymous requests get `401` | Views with `surface: public`, and Procedures reached by an MCP Trigger with `surface: public` |
+| `/mcp` | Any caller the site's HTTP routes would accept: OAuth bearer, same-origin cookie session, or anonymous. Each tool's `requires` decides; a `tools/call` that needs identity answers `401` with the OAuth challenge | Views with `surface: public`, and Procedures reached by an MCP Trigger with `surface: public` |
 | `/mcp/staff` | Authenticated caller holding a staff role | Views with `surface: staff`, the generic authoring tools (rank-gated at `tools/call`), Procedures reached by an MCP Trigger with `surface: staff` |
 
 Both accept tokens for one canonical protected resource, `${PUBLIC_ORIGIN}/mcp`. `/mcp/staff` is a stricter server-side role projection, not a second OAuth audience.
@@ -33,7 +33,7 @@ Procedures are never exposed on their own. A Procedure becomes a tool only throu
 
 ## The OAuth model
 
-The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary. Unauthenticated Dynamic Client Registration remains available as a bounded path with a 90-day default lifetime for clients that do not present CIMD. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Unauthenticated requests to either mount answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
+The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary. Unauthenticated Dynamic Client Registration remains available as a bounded path with a 90-day default lifetime for clients that do not present CIMD. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Invalid credentials on either mount, and anonymous requests to `/mcp/staff`, answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount; on `/mcp` an anonymous caller can list tools and call anonymous ones, and receives the same `401` challenge from the first `tools/call` whose target requires identity. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
 
 ## Connecting a local client
 
@@ -91,10 +91,15 @@ pnpm exec mantle skills --check
 
 This copies every skill the installed package marks `projection: project` — the develop skill among them — into matching `.agents/skills/mantle-*` and `.claude/skills/mantle-*` paths. Both layouts receive identical bytes; `--check` detects drift without writing. Skills that act destructively or target one platform stay out of that set and are opt-in. Manifest generation never rewrites agent instructions.
 
-For Claude Code, the same bundle is installable from the plugin marketplace at the exact installed version:
+For Claude Code, the same bundle is installable from the plugin marketplace at the published pin (or the exact version in `package.json`):
 
 ```sh
-/plugin marketplace add aotter/mantle@v<installed-version>
+# Canonical
+npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+
+# Claude Code — two separate prompts
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin install mantle@mantle
 ```
 
 Never point a versioned project at a mutable branch. See [Project layout and the CLI loop](../start/project-and-cli.md).

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -112,7 +112,7 @@ Bun, with the server and SQLite handle staying yours:
 
 ```ts
 import { Database } from "bun:sqlite";
-import { createBunMantle } from "@aotter/mantle-bun";
+import { createBunMantle } from "@aotter/mantle-bun";  // experimental
 
 const database = new Database("app.sqlite");
 const mantle = createBunMantle({ plan, database, handlers });
@@ -128,7 +128,7 @@ Vercel Functions, with storage injected:
 
 ```ts
 import { SqliteMantleStorageAdapter } from "@aotter/mantle-runtime";
-import { createVercelMantle } from "@aotter/mantle-vercel";
+import { createVercelMantle } from "@aotter/mantle-vercel";  // experimental
 import { LibsqlDatabaseDriver } from "@aotter/mantle-vercel/libsql";
 
 const mantle = createVercelMantle({

package/docs/handbook/navigation.json

@@ -4,10 +4,10 @@
     {
       "text": "Start here",
       "items": [
+        { "text": "Project layout and the CLI loop", "link": "/start/project-and-cli" },
         { "text": "Quickstart: a minimal Worker", "link": "/start/quickstart-worker" },
-        { "text": "Build with ChatGPT Sites", "link": "/sites/index" },
         { "text": "Quickstart: local Admin (opt-in)", "link": "/start/quickstart-admin" },
-        { "text": "Project layout and the CLI loop", "link": "/start/project-and-cli" }
+        { "text": "When the host is ChatGPT Sites", "link": "/sites/index" }
       ]
     },
     {
@@ -73,6 +73,12 @@
         { "text": "Diagnostic codes", "link": "/reference/diagnostics" },
         { "text": "HTTP, MCP, CLI and packages", "link": "/reference/surface" }
       ]
+    },
+    {
+      "text": "Releases",
+      "items": [
+        { "text": "Stable releases", "link": "/releases/index" }
+      ]
     }
   ]
 }

package/docs/handbook/reference/diagnostics.md

@@ -98,6 +98,10 @@ Named by the same code in validate, boot or runtime, depending on where the cond
 | `TRIGGER_PATH_COLLISION` | Two HTTP Triggers claim the same `(method, path)`. | — |
 | `TRIGGER_PATH_INVALID` | An HTTP Trigger path does not start `/api/` (validate), or falls under an adapter-reserved prefix (boot). | — |
 | `MCP_TOOL_NAME_COLLISION` | Two atoms mangle to the same MCP tool name, a Procedure takes a reserved generic name or prefix, or two MCP Triggers share a `(surface, tool name)`. | — |
+| `MCP_TOOL_DESCRIPTION_MISSING` | Warning. A Procedure reached by an MCP Trigger has no `spec.description`; `tools/list` would show a generated placeholder instead of something an agent can choose by. | — |
+| `MCP_TOOL_INPUT_UNREACHABLE` | Warning. An MCP write tool requires `expectedVersion` for a collection that no View on the same surface exposes `version` for, so an agent cannot read the value it must send. SQL Views are checked only by a conservative token scan. | — |
+| `MCP_TOOL_INPUT_UNION_AMBIGUOUS` | Warning. An MCP-surfaced Procedure input is a top-level `oneOf`; MCP clients render it poorly, and when its branches require fields the advertised `required` omits a caller satisfying the schema can still be rejected. Prefer one tool per branch. Disable or tune through `ValidateManifestsRequest.mcpInput`, or `mantle validate --no-mcp-input-checks`. | — |
+| `MCP_TOOL_INPUT_UNBOUNDED` | Warning. An MCP-surfaced Procedure input has an array without `maxItems` (or above the configured bound) or a free-form object with no declared properties, so an agent must serialise an unbounded payload into one `tools/call`. Typed maps (`additionalProperties: { type: … }`) do not count as free-form. | — |
 | `PROCEDURE_NOT_FOUND` | An invocation names a Procedure that is not in the compiled plan. | — |
 | `NOT_FOUND` | The addressed resource does not exist: an entry id, a View name, a media asset, an operation name. | `404` |
 | `METHOD_NOT_ALLOWED` | The path exists but the method is not bound. | `405` |
@@ -108,7 +112,7 @@ Named by the same code in validate, boot or runtime, depending on where the cond
 | Code | Meaning | HTTP |
 |---|---|---|
 | `BUILTIN_HANDLER_SCHEMA_UNKNOWN` | `handler.schema` names no declared Schema. | — |
-| `BUILTIN_HANDLER_CONTRACT_INVALID` | The Procedure's `input` breaks the builtin op's contract, such as a missing `expectedVersion` on `update` or a `match` tuple that is not exactly one `uniqueIndexes` entry. | — |
+| `BUILTIN_HANDLER_CONTRACT_INVALID` | The Procedure's `input` breaks the builtin op's contract, such as a missing `expectedVersion` on `update` or a `match` tuple that is not exactly one `uniqueIndexes` entry; or `spec.mcp` contradicts the op (`readOnlyHint: true` on any builtin, `destructiveHint: false` on `op: delete`). | — |
 | `LIFECYCLE_SCHEMA_UNKNOWN` | A lifecycle Trigger's `source.schema` names no declared Schema. | — |
 | `LIFECYCLE_HOOK_REJECTED` | A `before_*` hook aborted the mutation. The diagnostic names the rejecting hook. | `409` |
 

package/docs/handbook/reference/manifest.md

@@ -38,7 +38,7 @@ The parser rejects keys outside the shipped grammar at every level it knows. The
 | `/metadata` | `name` |
 | `/spec` (Schema) | `title`, `description`, `schema`, `uiSchema`, `uniqueIndexes`, `indexes`, `searchableFields`, `localized`, `translates`, `lifecycle` |
 | `/spec` (View) | `title`, `uiSchema`, `from`, `sql`, `surface`, `requires`, `filter`, `fields`, `orderBy`, `limit`, `params` |
-| `/spec` (Procedure) | `title`, `description`, `requires`, `input`, `uiSchema`, `output`, `handler` |
+| `/spec` (Procedure) | `title`, `description`, `requires`, `input`, `uiSchema`, `output`, `handler`, `mcp` |
 | `/spec` (Trigger) | `source`, `target` |
 | `/spec/translates` | `parent`, `on` |
 | `/spec/requires` | `auth`, `guard` |

package/docs/handbook/reference/procedure.md

@@ -16,6 +16,7 @@ A Procedure is a typed callable: input schema, output schema, authorization requ
 | `uiSchema` | object | no | Admin-only. Accepts `collectionAction` and `fields`. Violations are `SCHEMA_UI_INVALID`. |
 | `output` | JSON Schema | yes | Checked after the handler returns. Failure is `OUTPUT_VALIDATION_FAILED` (500). |
 | `handler` | `ref` \| `builtin` | yes | Exactly one binding shape; see below. |
+| `mcp` | object | no | MCP tool annotations the author asserts: `readOnlyHint`, `destructiveHint`, `openWorldHint` (booleans). Core infers what it can prove — every builtin handler writes, `op: delete` destroys, an `x-mcp-hint: idempotency-key` input makes the tool idempotent — and emits nothing else, so absent hints keep the MCP spec's conservative defaults. `readOnlyHint: true` on a builtin handler is `BUILTIN_HANDLER_CONTRACT_INVALID`. |
 
 Both `input` and `output` are walked by the [JSON Schema subset](./schema.md#json-schema-subset) validator, so the same recognized and rejected keywords apply.
 

package/docs/handbook/reference/surface.md

@@ -30,7 +30,7 @@ All `/admin/api/*` routes require a staff session, carry a 1 MiB JSON body limit
 | `GET /admin/api/views/<name>/export` | The same query as CSV, covering every matching row rather than one page. |
 | `GET /admin/api/views-manifest` | `{ views: … }` — the View manifest projection the SPA renders from. |
 | `GET /admin/api/operations` | `{ operations: [ { name, title, description, input, uiSchema, triggers, rowBindings } ] }`, filtered per caller by re-evaluating each Procedure's `requires.auth.all`. |
-| `POST /admin/api/operations/:name` | Invokes a staff-operable Procedure through the same use case the staff MCP surface uses. `404` when the name is not staff-operable. |
+| `POST /admin/api/operations/:name` | Invokes a staff-operable Procedure through the same use case the staff MCP surface uses. `404` when the name is not staff-operable or when the caller's `requires.auth.all` predicates exclude it — the same filter the listing applies, so names cannot be probed. |
 | `GET /admin/api/me`, `/collections`, `/collections/:name/statistics`, `/entries`, `/entries/export`, `/entries/:id`, `/site` | Session, catalog and entry reads. Entry detail requires `?collection=<schema>`. |
 | `POST /admin/api/entries`, `PATCH /admin/api/entries/:id` | Create and edit. Entry mutation routes require `?collection=<schema>`; contributors are limited to drafts on publishing Schemas. |
 | `POST /admin/api/entries/:id/publish`, `/unpublish`, `DELETE /admin/api/entries/:id` | Lifecycle. Requires `?collection=<schema>` and editor or above. |
@@ -52,7 +52,7 @@ All `/admin/api/*` routes require a staff session, carry a 1 MiB JSON body limit
 | `ALL /mcp` | Public MCP surface. JSON-RPC. | `private, no-store` |
 | `ALL /mcp/staff` | Staff MCP surface. Rejects a verified caller with no staff row using `403` and `insufficient_scope`. | `private, no-store` |
 
-Both MCP surfaces verify an OAuth access token against one canonical resource, `${PUBLIC_ORIGIN}/mcp`, and one scope, `mcp`. A missing or invalid token is `401` with a `Bearer` challenge naming the resource metadata URL; DPoP failures answer with a `DPoP` challenge. Misconfigured or partial auth environment variables keep public routes serving and return `503 setup_incomplete` from every Auth-owned route above — see [Authentication](../cloudflare/authentication.md).
+Both MCP surfaces resolve the caller exactly as the HTTP routes do — consumer credential, then an OAuth access token against one canonical resource, `${PUBLIC_ORIGIN}/mcp`, and one scope, `mcp`, then a same-origin cookie session, then anonymous. The surface adds one rule: `/mcp/staff` requires a staff caller. An invalid token, or an anonymous caller on the staff surface, is `401` with a `Bearer` challenge naming the resource metadata URL; DPoP failures answer with a `DPoP` challenge; on `/mcp` an anonymous `tools/call` whose target requires identity answers the same `401` challenge. Misconfigured or partial auth environment variables keep public routes serving and return `503 setup_incomplete` from every Auth-owned route above — see [Authentication](../cloudflare/authentication.md).
 
 ### Public pages
 
@@ -98,6 +98,7 @@ Tool names are the mangled `metadata.name`: lower-cased, with `-` replaced by `_
 | Tool | Surface | Registered when |
 |---|---|---|
 | `query_view_<segment>` | The View's own `surface` | One per declared View. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
+| `<procedure_segment>` | The MCP Trigger's `surface` | One per `mcp` Trigger. `annotations` carry what Core can prove (`readOnlyHint: false` for every builtin handler, `destructiveHint: true` for `op: delete`, `idempotentHint: true` when an input carries `x-mcp-hint: idempotency-key`) plus whatever the Procedure declares under `spec.mcp`; `ref` handlers get nothing inferred beyond the idempotency key. Generic authoring, lifecycle and media tools are `readOnlyHint: false`; `delete_entry` is also `destructiveHint: true`. |
 | `<procedure segment>` | The Trigger's `surface` | One per `Trigger.source.kind: mcp`. A Procedure with no MCP Trigger is not exposed. |
 | `request_publish` | staff | Always. Rejected at call time for an operational Schema. |
 | `unpublish_entry` | staff | Always. Same restriction. |
@@ -152,11 +153,11 @@ mantle.triggers.expireOrderHttp;   // { name, source, target }
 await mantle.runtime.archive.execute({ id, ctx });
 ```
 
-`entries.<collection>` exposes `createDraft`, `get`, `list` and `delete`, supplying the required collection identity to Core. Generic MCP entry tools require a `collection` argument. `runtime` is the underlying Core runtime, so the typed projection never hides it. A host that owns its own lifecycle can skip generation entirely and call `runtime.executeView({ view: "published-notes" })` directly.
+`entries.<collection>` exposes `createDraft`, `get`, `list`, `delete`, and the indexed field reads `readBySlug`, `readByDataField`, `readByDataFieldIn` and `findManyByDataField`, supplying the required collection identity to Core. The field reads accept only declared Schema fields and their scalar types, and return entries whose `data` is the generated Schema shape, so an author never has to drop to an untyped `runtime.entries` call or scan `list` to find rows by an indexed field. Generic MCP entry tools require a `collection` argument. `runtime` is the underlying Core runtime, so the typed projection never hides it. A host that owns its own lifecycle can skip generation entirely and call `runtime.executeView({ view: "published-notes" })` directly.
 
 ## Packages
 
-The umbrella installs Spec and Runtime only. Web, Admin, Admin UI, Bun, Vercel and Cloudflare are optional peers; install one before importing its subpath. Every sub-package is also directly installable.
+The umbrella installs Spec and Runtime only. Web, Admin, Auth, Admin UI, Bun, Vercel and Cloudflare are optional peers; install one before importing its subpath. Every sub-package is also directly installable.
 
 | Package | Umbrella subpath | Holds |
 |---|---|---|
@@ -167,6 +168,7 @@ The umbrella installs Spec and Runtime only. Web, Admin, Admin UI, Bun, Vercel a
 | — | `/codegen` | The pure linked-manifests to typed-module emitter, with no IO. |
 | `@aotter/mantle-web` | `/web` | HTML, Markdown, `llms.txt`, sitemap, SEO and preview composition. No routes, no platform dependencies. |
 | `@aotter/mantle-admin` | `/admin` | Admin API, auth route mounting, OAuth pages, static-asset composition. |
+| `@aotter/mantle-auth` | `/auth` | Host-neutral Better Auth identity, staff roles, and OAuth 2.1 / MCP authorization. Adapters own IP headers and storage bindings. |
 | `@aotter/mantle-admin-ui` | `/admin-ui` | Pre-built React 19 Admin SPA bundle. |
 | `@aotter/mantle-bun` | `/bun` | Bun adapter over a caller-owned `bun:sqlite` database. |
 | `@aotter/mantle-vercel` | `/vercel` | Vercel Functions adapter with injected durable storage and platform `waitUntil`. |

package/docs/handbook/reference/trigger.md

@@ -91,7 +91,7 @@ spec:
 
 `surface` is **discovery only**. It decides which tools appear in `tools/list` on which endpoint; it authorizes nothing. The target Procedure's `requires.auth.all` predicates and its optional guard are re-evaluated on every `tools/call` against the authenticated caller, exactly as they are over HTTP. A `public`-surface Procedure that requires `ctx.staff` is discoverable on `/mcp` and will still be denied there.
 
-The tool name is derived from the **Procedure's** `metadata.name`, not the Trigger's: lower-cased, with `-` replaced by `_`. Only one Trigger may claim a given `(surface, tool name)` pair; a second is `MCP_TOOL_NAME_COLLISION`. The same code also fires when the mangled name hits a reserved generic tool name or prefix, or a Schema's or another Procedure's segment — see [Reserved names](./manifest.md#reserved-names).
+The tool name is derived from the **Procedure's** `metadata.name`, not the Trigger's: lower-cased, with `-` replaced by `_`. Only one Trigger may claim a given `(surface, tool name)` pair; a second is `MCP_TOOL_NAME_COLLISION`. The same code also fires when the mangled name hits a reserved generic tool name or prefix, or a Schema's or another Procedure's segment — see [Reserved names](./manifest.md#reserved-names). A Procedure exposed this way should carry `spec.description`; a missing one is the `MCP_TOOL_DESCRIPTION_MISSING` warning, because the catalog's generated fallback tells an agent nothing about when to call the tool. A write tool that requires `expectedVersion` also needs a View on the same surface that exposes that collection's `version`; otherwise the tool is listed but uncallable, and validation warns with `MCP_TOOL_INPUT_UNREACHABLE`.
 
 The tool carries the Procedure's `title` and `description`, with a short authorization summary appended to the description. `output` is not surfaced; MCP clients infer the response shape from the `tools/call` result. See [MCP and agents](../concepts/mcp-and-agents.md).
 

package/docs/handbook/releases/index.md

@@ -0,0 +1,75 @@
+---
+description: Every stable Mantle release — what it contains, what it requires, and what changed since the previous stable.
+---
+# Releases
+
+Mantle publishes to npm under the `@aotter/*` scope. A **stable** release is a
+plain `X.Y.Z` version on the `latest` dist-tag; it is the only kind of release
+covered by this chapter and the only kind intended for production use.
+
+```sh
+npm install @aotter/mantle
+```
+
+Prereleases exist so a stable can be prepared in the open, and they are not
+covered here: `alpha` is cut from `develop` and may break anything, `rc` is a
+stable candidate cut from `main`. Installing a prerelease means opting into an
+exact version, not a channel. [GitHub Releases](https://github.com/aotter/mantle/releases)
+is the canonical, immutable change history; this chapter is the narrative one.
+
+All ten packages share a single version and are published together, so mixed
+versions across `@aotter/mantle*` are never a supported combination. Pin the
+version you install and upgrade the whole set at once.
+
+## 0.1.2 — 2026-09-21
+
+The first stable release, and Mantle's first public one. Everything before it
+was an internal prerelease; there is no earlier stable to upgrade from and no
+migration path to follow.
+
+**Requires** Node.js 22 or newer. Cloudflare Workers is the supported host.
+
+**The manifest engine.** Describe data, queries, actions and triggers as four
+atoms — [Schema](../reference/schema.md), [View](../reference/view.md),
+[Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) —
+in YAML under `manifests/`. `mantle generate` parses, links and compiles them
+into `.mantle/generated/mantle.ts`: a sealed execution plan, TypeScript types
+and typed bindings. Fingerprint or version mismatches between a generated plan
+and the installed packages fail immediately and ask you to regenerate.
+
+**Storage.** Each Manifest Schema becomes one native SQLite/D1 table. Authored
+fields keep their exact names as columns; Mantle's row envelope adds
+`_mantle_id`, `_mantle_status`, `_mantle_version`, `_mantle_author_id`,
+`_mantle_created_at` and `_mantle_updated_at`. Generated migration artifacts
+cover initial and additive changes; renames, type changes, data transforms and
+`uniqueIndexes` tuple changes are a manual rebuild.
+
+**Surfaces.** One contract drives all of them: public REST Views and HTTP
+Triggers, server-rendered HTML with Markdown, `llms.txt` and sitemap output, the
+Admin console and its prebuilt React SPA, and MCP — anonymous read-only Views at
+`/api/mcp`, staff tools at `/api/mcp/staff`, and Admin WebMCP in the browser.
+See [HTTP, MCP, CLI and packages](../reference/surface.md) for the full list.
+
+**Hosting.** `createMantleWorker` assembles the conventional Cloudflare Worker:
+D1 and assets bindings, Better Auth 1.7 (social providers, email OTP, magic
+link, passkey), Admin, MCP, Web and R2 media uploads. The Bun and Vercel
+adapters are experimental, cover public Views and HTTP Triggers only, and leave
+authentication and CSRF to the host. [ChatGPT Sites](../sites/index.md) is a
+first-class integration with a runnable reference.
+
+**Agents.** `mantle skills` projects the installed package's skills into
+`.agents/skills/mantle-*` and `.claude/skills/mantle-*`, so an agent working in
+your project reads instructions matched to the version you installed. `--check`
+detects drift without writing.
+
+**Not yet covered.** Stable does not carry a published latency budget,
+production-traffic measurement or a soak window; those acceptance items are
+tracked for 0.1.3 in [#962](https://github.com/aotter/mantle/issues/962). The
+Bun and Vercel adapters may change in a minor release.
+
+## Source
+
+- [`CHANGELOG.md`](../../../CHANGELOG.md)
+- [`docs/release-process.md`](../../../docs/release-process.md)
+- [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)
+- [`scripts/release-tag-order.mjs`](../../../scripts/release-tag-order.mjs)