@aotter/mantle 0.2.0-alpha.7 → 0.2.0-alpha.9

package/docs/handbook/guides/size-and-startup.md

@@ -2,7 +2,7 @@
 
 The SDK ships kernel, CLI, generator and private compiler together. Request modules do not import compiler code. Import only selected generated operations and bindings; direct operations can omit Store/Admin/auth entirely.
 
-Workers use `mantle bundle` to emit split ESM. Keep Better Auth behind `authLoader(() => import(...))`; the startup graph guard rejects eager auth imports. The official MCP SDK and selected Admin operations load on matching requests. Generated module imports perform no SQL or kernel initialization; Store metadata initializes on first use without SQL.
+Workers use `mantle bundle` to emit split ESM. Keep Better Auth behind `authLoader(() => import(...))`; the startup graph guard rejects eager auth imports, and Admin's browser code (`@aotter/mantle-admin/app`, `/hooks`, and so `generated/admin-client.ts`): import those only from `admin.tsx`, which `mantle bundle` builds into the assets directory. The official MCP SDK and selected Admin operations load on matching requests. Generated module imports perform no SQL or kernel initialization; Store metadata initializes on first use without SQL.
 
 Contributor checks use tracked fixtures to compare runtime/startup graphs against `size-budgets.json` and inspect the published allowlist in `check:package`. Package packed/unpacked bytes are reported separately from request startup and query costs. Do not infer latency from bundle bytes.
 

package/docs/handbook/guides/typed-queries.md

@@ -90,3 +90,38 @@ Interactive `transaction(async tx => …)` exists on bun:sqlite and PostgreSQL,
 Ref handlers receive `{ caller, db, store }` bound to the same Caller and transaction. Implement the generated `Handlers` interface and pass it to `store(db, caller, { handlers })`. Direct Procedure modules expose SQL Procedures; ref Procedures are reached through the bound Store or selected surfaces.
 
 See [native execution](native-execution.md) for values and write outcomes and [migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations) before changing a Schema.
+
+## Prefer Store-backed ref Procedures for simple writes
+
+For a single-entity create or partial update, prefer a declared `ref` Procedure
+whose handler awaits its caller-bound `ctx.store.collection(...).insert(...)`
+or `.update(id, allowedPatch, { lock: expectedVersion })`. Keep the Procedure's
+`requires` and generated validation at its invocation boundary: Store enforces
+row policy, but does not substitute for operation authorization. Do not invoke
+a handler directly from a route and accidentally bypass those checks.
+
+Insert/update returns the actual written native row. Inside a transaction,
+that result is provisional until the outer transaction commits; later failure
+can still roll it back. Report committed success or emit external effects only
+after that transaction succeeds. Return an explicit
+allowlist of useful business fields, its backend `id` and returned `version`;
+do not spread the entire row, echo the submitted version, calculate a new
+version instead of reading the result, or add a generic receipt adapter. These
+ref results are app-owned: declare their output schema and make any required
+native-to-wire conversion explicit at the boundary.
+
+Patch only permitted fields. Omitted fields remain unchanged; define whether
+explicit null clears a nullable field or is invalid. Do not expand a partial
+request into a full replacement with defaults for unseen fields. A stale lock
+is a conflict; preserve intent and reconcile/review rather than silently
+refreshing the lock and retrying.
+
+Use SQL Procedures when conditions or related effects must commit together:
+for example, creating an order while decrementing stock under a CHECK, a state
+transition guarded by an atomic WHERE, or an additive restock upsert. A
+pre-read in TypeScript followed by an unguarded write is not equivalent.
+Store `batch` is atomic for known writes; a D1 batch step cannot consume a prior
+step's returned ID. D1 has no interactive transaction callback, so retain the
+supported SQL program or another existing native atomic boundary for that case.
+The [MCP design audit](agent-workflow-acceptance.md) applies these choices before
+implementation and separates them from independent end-user acceptance.

package/docs/handbook/navigation.json

@@ -41,10 +41,6 @@
           "text": "Customize Admin",
           "link": "/guides/admin-ui"
         },
-        {
-          "text": "Extend Admin",
-          "link": "/guides/admin-extensions"
-        },
         {
           "text": "Another host or engine",
           "link": "/guides/adapter-guide"

package/docs/handbook/reference/admin-descriptors.md

@@ -45,44 +45,9 @@ stars, CTEs and subqueries). Translation
 metadata and selected execution share the generated translation policy. Child
 fields win; private scope fields cannot be overlaid by inherited parent fields.
 
-Pass declarations with `mantle generate --admin-extensions ./admin-extensions.mjs`.
-The module exports a named `adminExtensions` array or a default array; it should
-contain plain declarations, without constructing runtime services:
-
-```js
-export const adminExtensions = [{ id: 'audit', contributes: {
-  fields: [{ id: 'color', target: 'field.input/v1',
-    optionsSchema: { type: 'object', properties: { palette: { type: 'string' } } }
-  }]
-}}];
-```
-
-The programmatic generation options accept the same declarations:
-
-```ts
-await generateFromSources({ target, sources,
-  adminExtensions: [{ id: 'audit', contributes: {
-    fields: [{ id: 'color', target: 'field.input/v1',
-      optionsSchema: { type: 'object', properties: { palette: { type: 'string' } } }
-    }]
-  }}]
-});
-```
-
-Only `id` and `contributes` are needed at generation. `extensionBindings` records
-Schema/Procedure field widgets, Schema/admin View cells and sidebar panels.
-Unknown contributions, wrong targets and invalid options fail generation with
-`UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET` or `UI_EXTENSION_OPTIONS`, retaining
-0.2 paths. Serving extension modules and handling extension actions is separate.
-
 `adminBindings()` provides the selected adapter and checked entry/View/operation
 bindings. The server shares native read templates across collections; descriptors
 carry compiler-verified policy/field fragments and generated validators, not a
 copy of full SQL for every order/direction. Metadata endpoints perform no storage
 read of their own; caller resolution and optional site/user enrichment may query.
 Statistics capability is advertised only when its native route is mounted.
-
-Full extension declarations also emit `extensionMetadata` and, with Admin selected,
-`admin-extensions.ts` with a runtime `extensionBindings` function and compiled
-settings checks. Native modules are host-served; install integrity in the host
-shell import map. `source` modules are refused.

package/docs/handbook/reference/procedure.md

@@ -4,7 +4,7 @@ A Procedure requires `input`, `output` JSON Schemas and a `handler` containing S
 
 SQL uses declared Schemas, `input.<name>`, `auth.uid()` and native expressions accepted by the selected compiler dialect. Compiler policy supplies scope and system fields. Do not assign scope, version, status, published_at, timestamps or author columns yourself. Publishing writes use generated transitions. `restrict` narrows the rows the statements read and write, as on a [View](view.md#restrict); it is refused on ref handlers.
 
-A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error: check the returned rows when zero means failure. A unique clash, a failed Schema `checks` constraint (the message starts with `A check of the Schema failed`; SQLite and D1 add the check expression, PostgreSQL the constraint name) or a failed row assertion is `CONFLICT` (409); statements run atomically. Results are raw `{ results }`, not runtime-validated authored outputs. RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
+A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error: check the returned rows when zero means failure. A unique clash, a failed Schema `checks` constraint or a failed row assertion is `CONFLICT` (409); statements run atomically. A check failure keeps that code and its existing `A check of the Schema failed` message, and sets `ContractError.fields` to `{ kind: "check", schema, check }`; `check` is the expression on SQLite/D1 and the generated constraint name on PostgreSQL. Results are raw `{ results }`, not runtime-validated authored outputs. RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
 
 A row-classified UPDATE/DELETE on an excluded or missing id affects zero rows and returns HTTP 409 (`CONFLICT`), just like a stale version; reads return not found. Native Admin's visible-row pre-read returns 404 for excluded/missing ids.
 
@@ -12,8 +12,12 @@ A ref handler is application code called as `(ctx, input)`. Generation prints re
 
 `target: { schema, id, version? }` binds an Admin operation to a row. SQL targets can be inferred for a single locked row operation; declare a target for a ref operation when needed. Input fields must have the required shapes.
 
+## MCP tool hints
+
+Every generated AI-facing tool (MCP, WebMCP, publishing and media tools) carries a `title`, `readOnlyHint` and `destructiveHint`; clients such as Claude use them to decide between auto-approval and confirmation. The title is the declared `title`, else the name made readable (`add-item` reads `Add item`). A View is `readOnlyHint: true, destructiveHint: false`. A Procedure is `readOnlyHint: false`, and `destructiveHint` is `false` only when its SQL inserts without overwriting: any DELETE or UPDATE, an `ON CONFLICT DO UPDATE` or a ref handler makes it `true`. Of the generated publishing transitions only `archive` is destructive. The media tools always carry `openWorldHint: true`; the upload policy, list and get tools are read-only and only `delete_media_asset` is destructive. Admin's WebMCP navigation tools (`admin_get_context`, `admin_navigate`) are read-only. `spec.mcp` accepts `readOnlyHint`, `destructiveHint` and `openWorldHint`, and a declaration always wins; a declared `readOnlyHint: true` defaults `destructiveHint` to `false`. Outside the media tools `openWorldHint` appears only when declared. `idempotentHint` is never generated, and `spec.mcp` refuses it. Hints never change authorization.
+
 Generated requires checks gate calls. Boundary input validators are generated separately; direct queries accept driver-ready, app-validated input. Dynamic guards and lifecycle hooks are rejected. See [native execution](../guides/native-execution.md) and [surface contracts](surface.md).
 
 SQL INSERT/upsert into a user-field scoped Schema is system-only. For a verified user, insert through `ctx.store` so membership and single-partition autofill run before the native write. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
 
-Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `docs/examples/purchasing/src/requests-page.ts`.
+Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `node_modules/@aotter/mantle/docs/examples/purchasing/src/requests-page.ts`.

package/docs/handbook/reference/schema.md

@@ -54,7 +54,17 @@ Owner and field columns prefix every unique index in that order. User reads/writ
 
 ## Indexes, checks and search
 
-Indexes are ordered composite scalar/native columns. A paged View's `ORDER BY` must match an index on the base Schema after any fixed equality prefix, ending with `id` as the tiebreak: `ORDER BY createdAt DESC, id DESC` needs `indexes: [[createdAt, id]]` (generation reports `Missing index for ORDER BY ...` otherwise). Required operational fields are NOT NULL; publishing drafts may be incomplete. Store sortable types use indexed/non-null columns, with explicit nullable published_at support.
+Indexes are ordered composite scalar/native columns. A paged View's `ORDER BY` must match an index on the base Schema after any fixed equality prefix ([index prefixes](#index-prefixes-for-paged-views)), ending with `id` as the tiebreak: `ORDER BY created_at DESC, id DESC` needs `indexes: [[createdAt, id]]` (generation reports `Missing index for ORDER BY ...` otherwise). Required operational fields are NOT NULL; publishing drafts may be incomplete. Store sortable types use indexed/non-null columns, with explicit nullable published_at support.
+
+### Index prefixes for paged Views
+
+Only equality fixes an index prefix: `col = input.x`, `col = 'literal'` and an `= auth.uid()` scope or restrict. A user-field term (`region IN auth.user('region')`, as a `scope` or `restrict`) binds a set of values, so it never fixes a prefix, even when the caller holds one value or `{ all: true }`: the statement is prepared for a set, and an `ORDER BY` after that column would read and sort all of the caller's rows on every page. With `scope: "region IN auth.user('region')"`, `indexes: [[region, orderNo, id]]` and `ORDER BY orderNo`, generation refuses the View, names the bounded order and links here. The bounded ways:
+
+- `ORDER BY region, orderNo`, served by the same index: rows come back grouped by region. `region DESC, orderNo DESC` reads it backwards; on PostgreSQL confirm with `EXPLAIN` that no Sort remains. Every column added to the `ORDER BY` must be non-null and nameable in SQL; a `publishing` Schema field other than a user-field scope column can be null, and the `scope` owner column cannot be named, so the refusal then says this order is unavailable.
+- A View input bound with equality, `WHERE region = input.region ORDER BY orderNo`: the input fixes the prefix, and the scope still applies. Every set-bound column before the ordered ones needs its own equality.
+- For `{ all: true }` callers, an index on the equality-fixed columns, then the ordered columns, then `id`: `[orderNo, id]` here, `[tier, orderNo, id]` with `WHERE tier = input.tier`. It is not bounded for scoped callers, who scan the index and filter, and it does not help a View with any `restrict`, which [`{ all: true }` never lifts](view.md#restrict).
+
+Declaring both indexes does not make one View bounded for every caller. System (trusted) reads drop scope terms, so a scope-first index such as `[owner, at]` is not a proved range scan for them.
 
 `uniqueIndexes` accept declared fields only, never native entry columns such as `authorId`. For per-member uniqueness, declare a required string `member` field, write `member: caller.subject` in a handler, and use `uniqueIndexes: [[member, orderNumber]]`; do not take `member` from client input.
 
@@ -68,9 +78,9 @@ The runtime never creates, alters or checks tables. Initial DDL is for an empty
 
 A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin and the Store, not by the database: a SQL Procedure that inserts the row sets the field itself. A root `readOnly: true` makes the whole Schema read-only in Admin.
 
-`fields.<name>.widget/options` select supported controls or extension contributions; `list.primaryField`, columns/cells and enum `filterField` select list presentation; `nav.standalone/parentField` control child navigation; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)); panels select record sidebars. Generation validates these against declared fields/indexes and selected extension declarations. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
+`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation; `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
 
-See [Admin](../guides/admin-ui.md), [extensions](../guides/admin-extensions.md) and [diagnostics](diagnostics.md).
+See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
 ### Field scope
 

package/docs/handbook/reference/surface.md

@@ -13,7 +13,7 @@
   snake-cased View names on each declared surface, and snake-cased Procedure
   names per MCP Trigger. Its SDK loads only through a request-time dynamic import.
 - HTTP/MCP Triggers declare exposure only. `mantle generate` refuses schedule
-  and lifecycle Triggers; Cloud scheduling is a separate capability.
+  and lifecycle Triggers; host scheduling is a separate capability.
 - Native Admin retains selected 0.2 paths and the console contracts; see
   [Native Admin](../guides/native-admin.md) for app-mounted
   `adminBindings()` and `entries(bindings.schemas, bindings.adapter)`.
@@ -25,21 +25,43 @@ challenges, JSON-RPC, web rendering, keyset paging) lives in the package's
 `rest`, `mcp`, `web`, `paging` and `validation` kernel modules, so a runtime fix
 ships as a package update instead of a regeneration.
 
+Procedure surface selection follows the [HTTP/MCP pairing default and deliberate asymmetry exception](trigger.md); no surface is implied.
+
 The generated `validation/views/<name>.ts` and
 `validation/procedures/<name>.ts` export `validate(unknown)`. View validators
 also export `query(URLSearchParams)` returning `{ input, limit?, cursor? }`.
 REST and MCP use the same generated checks, with no runtime schema interpreter.
 Supported checks are types/unions and nullable, required/properties/additionalProperties,
-arrays/items and length bounds, enum, local `$defs`/`$ref`, string length/pattern,
-numeric bounds/`multipleOf`, and date/date-time/email. The deliberately permissive
+arrays/items and length bounds, enum, `const`, local `$defs`/`$ref`, string length/pattern,
+numeric bounds/`multipleOf`, and the formats `date`, `date-time`, `email` and `uri`. The deliberately permissive
 email check requires exactly one `@`, non-empty local and domain parts, and no
 whitespace; it does not require a dot, verify deliverability, or implement full
-RFC mailbox syntax. Integers must be safe; fractional
-`multipleOf` uses a 1e-9 quotient tolerance. `const`, `oneOf`, `uniqueItems` and
-object property-count bounds are refused, alongside other unsupported keywords
-and formats. Defaults remain
+RFC mailbox syntax. `uri` means an absolute `http:` or `https:` URL, stricter than
+JSON Schema's any-scheme URI, so `javascript:` and `data:` links fail. Integers must be safe; fractional
+`multipleOf` uses a 1e-9 quotient tolerance. Defaults remain
 annotations and are not inserted into request input.
 
+View and Procedure input objects (not Schemas or outputs) also take three rules
+between their declared properties, each failing with one `INPUT_VALIDATION_FAILED`
+error whose message names the rule:
+
+- `dependentRequired: { weight: [unit] }`: "'unit' is required when 'weight' is
+  present.", at the missing field.
+- `anyOf` whose every branch is exactly `{ required: [...] }`: "At least one of
+  'weight', 'heightCm' is required.", at the object.
+- `if: { properties: { undo: { const: true } }, required: [undo] }` with `then`
+  and/or `else` each exactly `{ required: [...] }`: "'item' is required unless
+  'undo' is true.", at the missing field. `if` must list its field in `required`:
+  otherwise an absent field would satisfy it.
+
+Any other `anyOf`/`if`/`then`/`else`, `oneOf`, `uniqueItems`, object property-count
+bounds and other keywords and formats are refused at generation. The rules only
+validate: types, SQL binds and Admin forms keep the declared fields, and Admin
+shows the server's error at its field. `describe` keeps them as written; MCP and
+WebMCP tools advertise the schema without them and append each rule's sentence to
+the tool description, since some model APIs refuse these keywords in a tool's
+input schema. [Trigger](trigger.md#input-rules) has an example.
+
 Native `paged/views/<name>.ts` has a default export, callable as
 `page(db, caller, input, { limit?, cursor? })` after importing it as `page`,
 answering `{ rows, nextCursor? }`.
@@ -56,10 +78,18 @@ their contracts. Native integer bigint cursor keys are serialized separately.
 REST/MCP use separate `paged/wire/views/<name>.ts` SQL when declared integers
 require exact transport projections. Web pages and internal paged Views keep
 driver-native rows. Internal paging creates no public route/tool.
-Authored SQL `LIMIT` caps each page, up to 500, rather than the whole cursor walk.
+Authored SQL `LIMIT` bounds the complete ordered row set, including across cursor pages.
+Use `limit` in the paging options to choose each page size (up to 500); it does not expand the View's declared result set.
+An MCP View page keeps the `limit` of 1 to 500 but holds only as many of those rows
+as fit 60,000 characters of JSON, so a result stays under host truncation limits. It
+is cut before the first row that overflows and its next cursor resumes at that row.
+A single row over the budget is returned alone with the cursor, and a View without an
+order stays one whole page; a page still over the budget carries a notice that hosts
+may truncate it.
 A pageable Schema View has a complete NOT NULL scalar tuple ending in the
 compiler's `id` tiebreak. Its ordered columns must match an index after fixed
-equality prefixes (including caller scope); multiple columns and mixed directions
+equality prefixes; a user-field `IN` scope or restrict is not one (see
+[index prefixes](schema.md#index-prefixes-for-paged-views)); multiple columns and mixed directions
 retain the authored order. CTE projections preserve the proof; joins must have a
 proved singleton side, or equality on the joined Schema's `id` or single-field
 unique key, so the base id cannot fan out. LEFT JOIN accepts nullable or missing
@@ -132,7 +162,10 @@ const tags = await site.head(request, env); // HTML string, empty for unknown/mi
 ```
 
 Page parameter names must exactly match the View's declared input properties.
-Page and list Views must return the page parameters; list Views must accept empty input. Markdown
+Page and list Views must return the page parameters; list Views must accept empty input: no
+`required`, no root `anyOf`, `enum` or `const`, no `else` rule, and a root `type`, when given, that includes `object`.
+These conditions also apply to each schema a root `$ref` chain reaches, and an unresolved or cyclic chain fails them.
+`web()` throws a `TypeError` for any other list View. Markdown
 must name a textual output column. HTML remains application-owned.
 
 `/llms.txt` and `/sitemap.xml` traverse each list's `nextCursor`; `.md` and head
@@ -169,14 +202,30 @@ transport loads on the first matching request. Pass `handlers` when ref
 Procedures are declared, as for REST. Admin tools are listed only on the admin
 endpoint, and publishing visibility belongs to the generated SQL.
 
+`apps.public` and `apps.admin` accept a `McpAppsSource` or an array mixing static
+contributors with async `({ env, request }) => McpApps` factories. Static resources
+are checked once at construction; factories resolve only after the endpoint's
+origin and caller gates, and their resource identities and ownership are checked
+on each request even when the tool names are unchanged.
+
+Discovery is caller-independent by default (ADR-0014); listing a tool grants no
+execution authority. Configure `authorize` to filter `tools/list` and the tool
+names supplied to resource HTML loaders: that mode also excludes tools refused
+by declared identity, scope and `check` requirements. Without `authorize`, the
+complete endpoint catalogue is not a permission-filtered catalogue. Operation
+validation, guards and credential checks still apply to calls.
+
 The app resolves bearer tokens with `resolveCaller(request, auth, { audience:
 new URL('/mcp', request.url).href })` (both surfaces use `<origin>/mcp`). The app
 must also mount Better Auth's `/.well-known/oauth-protected-resource/mcp`
 metadata route. Auth challenges point to that route. Presented bearer credentials
 need the `mcp` scope; cookie sessions use the same-origin mutation checks.
 
-Generation emits `mcp.ts` only for a non-internal View or MCP Trigger. These
-surfaces typecheck without the `@modelcontextprotocol/server` 2.1.0 peer.
+Generation emits `mcp.ts` only for a non-internal View or MCP Trigger. Omitting
+MCP remains a deliberate asymmetric choice; an HTTP-only Procedure still generates
+successfully with the warning described in [Trigger](trigger.md). These
+surfaces typecheck without the optional `@modelcontextprotocol/server` peer;
+install the exact version declared in the installed SDK's `peerDependencies`.
 The peer loads by dynamic import on the first matching `/mcp` request; if
 missing, that request fails at runtime. Publishing alone does not select MCP;
 on a selected
@@ -207,15 +256,42 @@ as an explicit option.
 ### MCP catalogue and callbacks
 
 `mcp({ db, caller, handlers?, locale?, instructions?, serverInfo?, requiredScopes?,
-resourceMetadata?, onObservation?, onRefusal? })` keeps the SDK behind its first
+resourceMetadata?, allowedOrigins?, onObservation?, onRefusal? })` keeps the SDK behind its first
 request. Locale defaults to `en`; localized titles/descriptions fall back to
-English, then their first entry. Views advertise `readOnlyHint`; Procedures use
-their declared MCP annotations. `instructions` is returned by initialize.
+English, then their first entry. Tools carry the [tool hints](procedure.md#mcp-tool-hints). `instructions` is returned by initialize.
 The scope floor defaults to `["mcp"]` for every credential except cookie sessions;
 `requiredScopes: []` disables that floor. An anonymous closed surface challenges
 from initialize, and every call in a batch is checked before any call runs.
 `resourceMetadata` overrides the challenge URL for reverse proxies.
 
+Both endpoints answer a request without `Origin`, which is what server-side MCP
+clients send; a bearer credential needs none. A cookie session is ambient authority, so
+`checkOrigin` also guards it: on a request that is not GET, HEAD or OPTIONS, at least one of
+`Origin` and `Sec-Fetch-Site` must be present and every present one must agree (`Origin` equal
+to the request's own origin; `Sec-Fetch-Site` `same-origin` or `none`), else `AUTH_DENIED` at
+`request:origin`. On MCP it runs only for a tool call that executes (not a read-only call from an
+App host), not for initialize or `tools/list`; `allowedOrigins` does not lift it. A present `Origin` marks a browser: it must name a loopback host
+(`localhost`, `127.0.0.1`, `[::1]`, any port) or an `allowedOrigins` entry, else
+403 before authentication on every credential; `Origin: null` is refused. The
+site's own origin is not implied, because a DNS-rebinding page sends an `Origin`
+equal to the `Host` it rebound, so a browser client served from your deployed
+site lists that origin: `allowedOrigins: ["https://app.example"]`. Entries are
+compared by hostname as the official SDK does (not scheme or port); each is a
+full origin (`https://console.example`) or the SDK's bare host
+(`console.example`, `localhost:8787`), and anything else, such as a path, throws
+when `mcp(...)` is configured; so does a wildcard such as `*` or
+`https://*.example.com`, since entries are matched by exact hostname. `Host` is
+not checked. Cookie writes also need the full same-origin check.
+
+`/mcp` sends no CORS headers. `allowedOrigins` therefore serves pages on the
+same origin as the endpoint, or clients behind a proxy that forwards their
+`Origin`; a browser client on another origin also needs the app to answer
+preflight and add CORS headers itself. Under `wrangler dev` with `routes` or
+`dev.host`, Miniflare rewrites an `Origin` equal to the request's own origin to
+the route or `dev.host` origin, and a DNS-rebinding request always has that
+shape. Listing that host would admit rebinding against the local server, so keep
+the route and `dev.host` hosts out of `allowedOrigins` in local development.
+
 `onObservation` receives request refusals and invocation attempt/completion
 metadata, including duration and outcome. Its Caller and scopes are frozen copies.
 `onRefusal` receives credential/origin refusals. Neither callback receives request
@@ -232,6 +308,44 @@ with an output schema they omit `structuredContent` to avoid validating an error
 against a success schema. Without one they also expose diagnostic structured
 content. MCP adds no prompts or non-UI resources.
 
+### Tool versions
+
+Each generated tool (MCP, media, publishing and WebMCP) carries `version`, a
+short hash computed by `mantle generate` of the definition as listed: name,
+title, description without the marker, input schema (a View tool's with its
+`limit` and `cursor` paging properties), output schema and annotations. A
+localized title or description is hashed with all its locales. The description
+ends with `(tool version <version>)`, so an unchanged tool keeps a
+byte-identical description across deploys.
+
+MCP results of a call that reaches the tool add a second text block,
+`tool version <version>`; failures other than authorization refusals append
+`; input schema <JSON>`, the input schema the tool is listed with.
+`structuredContent` is unchanged. A `tools/call` naming a tool the endpoint
+serves but the caller may not use is answered by the authentication or
+authorization challenge (HTTP 401 or 403) before the SDK's transport and
+request checks, even though that caller's `tools/list` omits the tool. A
+`tools/call` naming a tool not in the endpoint's catalogue, in a batch or not
+and from a host caller too, is answered with JSON-RPC error `-32602` and the
+message
+`No tool named "<name>" exists in the current catalogue (catalogue version <serverInfo.version>).`
+For such a name the SDK's transport and request checks (headers, protocol
+version, JSON-RPC shape) answer first, so a malformed request gets the same
+refusal as one naming a served tool the caller may use.
+Unless `serverInfo.version` is given, the kernel's `mcp()` sets it to
+a hash of the `surface:name:version` of every tool the endpoint serves, before
+per-caller filtering, so `/mcp` and `/mcp/admin` each report their own catalogue
+version, and it changes when a generated tool's definition changes or a tool is
+added or removed, however the tools are wired.
+
+`POST /admin/api/webmcp/{tool}` returns `{ output, version }`. A refusal's
+diagnostic adds `toolVersion`, and `inputSchema` unless it is an authorization
+refusal; internal errors and refusals before the call carry neither. Admin's
+WebMCP results repeat these as the same text block MCP adds. The navigation
+tools `admin_get_context` and `admin_navigate` have no version. Tools an
+application adds itself carry a version only if it sets one. Why: [MCP and
+agents](../concepts/mcp-and-agents.md#when-a-host-shows-old-tools).
+
 ### Declared View scalars on the wire
 
 REST and MCP View pages expose declared JSON columns as JSON values and declared

package/docs/handbook/reference/trigger.md

@@ -24,12 +24,54 @@ metadata: { name: close-ticket-http }
 spec:
   source: { kind: http, method: POST, path: '/api/tickets/{id}/close' }
   target: { procedure: close-ticket }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: close-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: close-ticket }
 ```
 
 The target names a declared Procedure. `http` sources use POST/PUT/PATCH/DELETE and an `/api/` path. Path parameters bind to corresponding declared input fields and override JSON-body values. The generated REST module retains the Procedure's authorization and validates boundary input.
 
-An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its declared description/annotations and requires checks.
+An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its description, [tool hints](procedure.md#mcp-tool-hints) and requires checks.
+
+By default, pair every HTTP Trigger with an MCP Trigger so the same operation is reachable by the user's AI. `mantle generate` warns when a Procedure has HTTP exposure but no MCP exposure, suggesting `surface: admin` for an admin-only Procedure and `public` otherwise. Triggers still decide every Procedure surface: intentional asymmetric exposure is allowed and generation succeeds.
 
 Lifecycle and schedule sources are rejected at generation with `GENERATE_UNSUPPORTED`, including disabled schedules. Use an app-owned handler or scheduler. For signed webhooks, verify the original raw Request in the app and call a generated Procedure with validated input; do not route it through a JSON boundary before signature verification.
 
+## Input rules
+
+The admin MCP tool below lists `reason` and `closed` without the rules, and its
+description ends "'reason' is required when 'closed' is false."; a call with
+`closed: false` and no `reason` fails with `INPUT_VALIDATION_FAILED` at
+`procedures/set-ticket/input/reason` (the error path is
+`procedures/<name>/input/<field>`). See [surface contracts](surface.md) for the
+supported rules.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: set-ticket }
+spec:
+  description: Open or close a ticket.
+  input:
+    type: object
+    required: [id, closed]
+    properties: { id: { type: string }, closed: { type: boolean }, reason: { type: string, maxLength: 200 } }
+    additionalProperties: false
+    if: { properties: { closed: { const: false } }, required: [closed] }
+    then: { required: [reason] }
+  output: { type: object }
+  handler: { sql: 'UPDATE tickets SET closed=input.closed WHERE id=input.id RETURNING id,closed' }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: set-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: set-ticket }
+```
+
 See [surfaces](surface.md) for mounted paths, error mapping and origin checks.

package/docs/handbook/reference/view.md

@@ -29,7 +29,7 @@ Store keeps `find`/`first` search and `count`. `count` scans every matching row;
 
 Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
 
-Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes, non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
+Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes ([index prefixes](schema.md#index-prefixes-for-paged-views)), non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
 
 Publishing Schema fields may be NULL in drafts even when required, so public View paging cannot order by them. `published_at` is accepted by Store ordering but rejected as a View paging key. Use `ORDER BY id`, or keep the business date in an operational Schema as an indexed, required non-null field.
 

package/docs/handbook/releases/index.md

@@ -17,6 +17,78 @@ Pin every package you use to the same exact version and upgrade them together.
 
 ## 0.2.0 — in preparation
 
+### Upgrading to 0.2.0-alpha.9
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
+`@aotter/mantle-admin` dependency to `0.2.0-alpha.9`, refresh the lockfile,
+then regenerate and check the application's owned artifacts. Keep existing
+production migrations application-owned; generated initial DDL is for an empty
+database. This alpha includes breaking Admin authoring and paging changes.
+
+1. **Build output and host configuration.** `mantle bundle` writes server
+   modules to `dist/worker` and static files to `dist/client`, including
+   `dist/client/admin`. Rerun `mantle generate` with the application's `--entry`
+   and check the resulting Wrangler `main`, `base_dir`, asset directory and
+   build command. See [CLI and generated ownership](../start/project-and-cli.md).
+2. **Application-owned React.** Install React and React DOM in the application
+   at the same exact version (the examples use `19.3.0`). Admin takes them as
+   peers; a mismatched pair fails its build.
+3. **Replace extensions with application composition.** Move to
+   `defineAdmin(meta, { nav, pages, home, components, plugins, mcp })` in
+   `src/admin.tsx`. Remove `--admin-extensions`, `adminExtensions`,
+   `defineAdminExtension`, extension handlers and removed manifest widget,
+   `list.cells` and panel references. `navGroups` becomes `nav.groups`.
+   Use the [Admin migration table](../guides/native-admin.md#migrating-from-admin-extensions)
+   rather than carrying the former registration layer forward.
+4. **Build the MCP App with the application.** The prebuilt
+   `@aotter/mantle-admin/mcp-app` / `mantleAppHtml` export is gone. Use
+   `adminMcpApps({ catalogue: mcpAppCatalogues.admin })` with the generated
+   catalogue; it reads the built asset. Declare CSP once in `defineAdmin`.
+   The default resource URI hashes the built HTML, catalogue and metadata;
+   custom HTML functions need an explicit immutable URI. Load interactive
+   host HTML through authenticated `resources/read`, which embeds its
+   catalogue. See [MCP Apps](../guides/mcp-apps.md).
+5. **Run the generated compatibility check.** Run
+   `node --test generated/admin-mcp-app.check.mjs` after building. Install
+   the optional `playwright-core` peer and a browser, or set
+   `MANTLE_TEST_CHROMIUM`; a missing browser fails rather than skips. This
+   checks rendering with a synthetic catalogue, not application authorization
+   or completion of a Procedure action.
+6. **Keep the host graph safe.** The MCP build rejects `/admin/api` access,
+   cookies and undeclared remote loads. Its entry must be readable in Node.
+   An optional `src/admin.mcp.tsx` (or `buildAdmin({ mcpEntry })`) isolates
+   browser-only integrations; both roots can reuse one host-safe config,
+   components and CSS. Without it the whole shared entry graph is checked.
+7. **Distinguish total bounds from page sizes.** Authored SQL `LIMIT` now
+   bounds the complete ordered result set across cursor pages, including web
+   indexes. Use paging `options.limit` for page size; remove an authored limit
+   only if it was incorrectly being used as a page-size setting. MCP accepts
+   sizes of 1–500, but a response budget can return fewer rows: append pages
+   until `nextCursor` is absent, not until a short page. See
+   [View paging](../reference/surface.md).
+8. **Install build dependencies where the build runs.** Wrangler dev/deploy
+   runs its configured build command, so that environment needs
+   `node_modules`. The resulting built server/assets do not read
+   `node_modules` when served. See the
+   [application shell](../../examples/app-shell/README.md).
+
+Record/collection cells, inputs, record actions, asides and `RecordView` are
+now truthfully browser-only (`surface: "browser"`); remove unreachable MCP
+branches. View cells remain `both`, and pages opt in through `pages[].mcp`.
+A Procedure action's input is distinct from a collection record input: use a
+Procedure target and MCP Trigger with the View's unchanged `id` and observed
+`version` for native row actions. [Shared custom-page headers](../guides/mcp-apps.md#customising-admin-for-mcp-hosts)
+can compose localized title, description and actions on both surfaces; omit the
+option to keep prior behavior, or use `header: false` for an element-owned heading.
+
+OAuth issuer verification now follows Better Auth's normalized URL while
+preserving explicit issuer/JWKS settings. Cloudflare OAuth configurations need
+`global_fetch_strictly_public` for public JWKS fetches; generated settings and
+the official examples retain it. Native MCP Apps use the official ext-apps
+client. Browser Admin now displays a localized explicit reload action when a
+lazy page fails, rather than going blank; it does not reload automatically or
+replay writes.
+
 ### Native SDK migration (alpha.7)
 
 Alpha.7 replaces the previous Core runtime and generated service contract.
@@ -32,7 +104,7 @@ Existing alpha.6 applications require a source migration:
   runs DDL at boot. Apply generated `schema.sql` only to an empty database;
   migrate existing data explicitly. PostgreSQL uses Bun.SQL on Bun and
   postgres.js on Workers. See [native execution](../guides/native-execution.md).
-- Install the separate `@aotter/mantle-admin` package when selecting Admin.
+- Install the separate `@aotter/mantle-admin` package when selecting Admin, with `react` and `react-dom` in the application pinned to one identical exact version (Admin no longer installs them).
   Compose its [native bindings](../guides/native-admin.md) in the application.
   Bare queries retain driver-native values; selected REST/MCP/Admin boundaries
   own validation and declared-column wire conversion.
@@ -40,7 +112,7 @@ Existing alpha.6 applications require a source migration:
   application code. Review [authorization and Caller wiring](../concepts/runtime-and-adapters.md)
   and regenerate all owned artifacts before running `generate --check`.
 
-The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.7/docs/examples/reference-service) and
+The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) and
 [app shell](../../examples/app-shell/) demonstrate the current composition.
 The following earlier-alpha notes are historical; the current handbook and
 the native migration above supersede their runtime and CLI instructions.

package/docs/handbook/start/overview.md

@@ -9,7 +9,7 @@ Mantle compiles a closed v2 manifest into native SQL and typed TypeScript. The a
 | --- | --- |
 | `@aotter/mantle` | SDK, private compiler, generator and `mantle` CLI |
 | `@aotter/mantle-ui` | Pure UI kit and generic interaction controller; no SDK dependency |
-| `@aotter/mantle-admin` | Admin server, SPA, extensions, preview and MCP App; SDK peer |
+| `@aotter/mantle-admin` | Admin server, app-built SPA library, preview and MCP App; SDK peer |
 
 Start with [a Worker](quickstart-worker.md) or [CLI and targets](project-and-cli.md). Existing TypeScript/Node apps can import selected generated operations using their own handle and verified Caller; no router or identity replacement is required. See the packaged [integrate skill](../../skills/integrate/SKILL.md).