@aotter/mantle 0.1.2 → 0.1.3-alpha.2

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

@@ -58,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/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.2 --skill install
+
+# Claude Code — two separate prompts
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
+/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/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)

package/docs/handbook/start/project-and-cli.md

@@ -5,6 +5,12 @@ description: The files you own in a Mantle project, every mantle and mantle-harn
 
 This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
 
+Cold start from GitHub or a marketplace host is the pinned install skill, not this page:
+
+```sh
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
+```
+
 ## You own the project
 
 Core is a manifest compiler and a runtime, not a project generator. You write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
@@ -71,7 +77,7 @@ It does not project skills, update packages, change styling, provision providers
 | `createMantle({ storage, handlers, ports })` | Prepares storage eagerly once and returns the typed binding. No caching or retry. |
 | `bindMantle(runtime)` | The same typed binding over a runtime whose lifecycle the host already owns. |
 
-The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })` and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
+The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
 
 ## The daily loop
 
@@ -92,15 +98,20 @@ Run the harness after any change to a Schema index, View filter or ordering, or
 
 `mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `install`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
 
-Install the version-matched plugin bundle in the agent host, using the exact version from `package.json`:
+Install the version-matched plugin bundle in the agent host. Cold start uses
+the published pin; an already-installed project uses the exact version from
+`package.json` (currently `0.1.3-alpha.2`):
 
 ```sh
+# Canonical
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
+
 # Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle@v<installed-version>
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
 /plugin install mantle@mantle
 
 # Codex
-codex plugin marketplace add aotter/mantle --ref v<installed-version>
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.2
 codex plugin add mantle@mantle
 ```