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

package/docs/handbook/guides/oauth.md

@@ -58,6 +58,15 @@ unchanged. A POST registration whose redirect URIs are all HTTP localhost,
 127.0.0.1 or [::1] becomes `application_type: "native"` when omitted; explicit
 types and mixed/external callbacks stay under the SDK's validation.
 
+With the optional Admin UI selected, use `consentPage:
+"/admin/oauth/consent"`, as in `docs/examples/app-shell/src/auth.ts`, and keep
+`adminShell` mounted in the service entry. That page uses mantle-ui's `AuthCard`,
+cards and sign-in buttons; it loads the verified request from
+`/oauth/consent/data` and posts the original signed payload to `/oauth/consent`.
+The UI displays the client, callback origin, requested scopes and background
+access explanation. Keep Core's script-free `/oauth/consent` HTML as the
+adapter-neutral fallback, not as the reference application's styled page.
+
 `/oauth/consent` and `/oauth/consents` serve escaped, script-free English or zh-TW
 HTML. Their `/data` routes serve the 0.2 UI JSON shapes. Consent approval and
 `POST /oauth/consents/revoke` require a live cookie session and same-origin
@@ -84,6 +93,55 @@ Grant lifetime follows Better Auth. Better Auth issues a refresh token only when
 the grant includes `offline_access`; a client registered for `authorization_code`
 may use `refresh_token` too, so registering only `authorization_code` does not
 prevent long-lived grants.
+CIMD is the primary client-discovery path; dynamic client registration (DCR)
+remains available for older MCP clients. Both paths require the client to request
+`offline_access` and the user to consent before a renewable grant is issued.
+The DCR registration defaults below apply only to that compatibility path.
+
+For renewable MCP connections, the examples set both `scopes` and
+`clientRegistrationDefaultScopes` to `["mcp", "offline_access"]`, so a dynamically
+registered client that omits `scope` is registered for `mcp offline_access`. The
+client must request those registered scopes during authorization and the user must
+consent to background access. If the client explicitly requests only `mcp`, OAuth
+must not add a scope the user did not consent to: the resulting grant is bound to
+the browser session and has no refresh token. The client must request
+`offline_access`, or the user must reconnect and authorize it, to gain renewable
+access. Declaring the `refresh_token` grant type alone is insufficient.
+`offline_access` belongs in authorization-server metadata, not in the protected
+resource's required scope floor; resource metadata continues to advertise `mcp`.
+
+For renewable connections, the app-shell's MCP handler also supplies an explicit
+OAuth linking hint:
+
+```ts
+const handleMcp = mcp({
+  db: (env: Env) => env.DB,
+  caller: resolveRequestCaller,
+  authorizationScopes: ["offline_access"],
+});
+```
+
+`authorizationScopes` adds scopes to the standard `WWW-Authenticate` challenge
+when the caller is unauthenticated. With the default `requiredScopes`, that
+challenge requests `mcp offline_access`. It does **not** change the API scope
+floor, add scopes to a valid token, issue tokens or modify an already-signed
+authorization request. An existing valid `mcp`-only token can still call a tool
+that only requires `mcp`. The application must independently permit
+`offline_access` in its provider and the user must explicitly consent.
+Verify the actual requested scopes, refresh-token issuance and post-expiry
+rotation in the intended client. Do not put `offline_access` in the resource's
+required scope floor or silently add it after consent.
+
+For an existing connection granted only `mcp`, deploy the allowed-scope change,
+refresh the client's discovery/registration metadata, then reconnect or reauthorize
+once with `offline_access` and obtain updated consent. Allowing a scope does not
+add it to a stored consent. Do not edit consent rows, prolong access-token TTLs or
+disable grant checks to avoid that step. Verify a refresh token was issued and
+that the client can rotate it and resume MCP after access expiry; a successful
+initial `tools/list` does not prove renewable authorization. The reference service's
+local smoke exercises issuance, refresh after website sign-out, rotation retry
+and revocation using real OAuth endpoints and a disposable D1.
+
 Without `offline_access` the grant is bound to the browser session: its tokens
 stop working when that session expires or the user signs out. A refresh that
 narrows the scope to drop `offline_access` after the session ends returns

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

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,6 +25,8 @@ 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? }`.
@@ -219,7 +221,9 @@ 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
+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

package/docs/handbook/reference/trigger.md

@@ -24,12 +24,21 @@ 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 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

package/docs/handbook/releases/index.md

@@ -17,10 +17,10 @@ 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.8
+### 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.8`, refresh the lockfile,
+`@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.
@@ -112,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.8/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/project-and-cli.md

@@ -12,6 +12,14 @@ description: Generation targets, CLI options and ownership of native application
 | `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
 | `dist/` | Disposable bundle output (`dist/worker`, `dist/client`); do not commit |
 
+## Accept user-facing work
+
+Before reporting any user-facing deliverable as done, run the installed
+version's [independent acceptance
+flow](../guides/agent-workflow-acceptance.md) with a fresh agent on the surface
+its user uses. For MCP work, also run that guide's design audit before choosing
+tool names or writing manifests/handlers.
+
 ## Commands
 
 ```sh
@@ -37,7 +45,7 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 | `--wrangler <path>` | Existing JSONC/JSON/TOML config; default finds one or creates `wrangler.jsonc`. TOML receives manual-edit instructions. |
 | `--entry <path>` | Worker source entry; default `src/worker.ts`. |
 | `--outdir <path>` | Bundle output; default `dist`. The Worker goes to `<outdir>/worker`. Keep separate from source/generated files. |
-| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. |
+| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. New assets blocks default to `ASSETS`, Worker-first routing and no HTML rewriting; existing blocks keep their binding/routing. |
 
 ## Outputs
 

package/docs/skills/develop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: develop
-description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity and MCP — using the installed package's contract.
+description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity, MCP tool design and independent acceptance — using the installed package's contract.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/develop/SKILL.md
@@ -12,28 +12,48 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
-
-Use the native Store/query/surface entries and app-owned fetch from the service composition guide.
+Use the native Store/query/surface entries and app-owned fetch from the [service
+composition guide](../../handbook/cloudflare/service-entry.md).
+Pair every HTTP Trigger with an MCP Trigger by default; see [Trigger](../../handbook/reference/trigger.md)
+for the generate warning and deliberate asymmetry exception.
 Keep optional modules out of unused entry imports and auth dynamically loaded.
 Run actual public/member/admin HTTP, MCP and UI scenarios; verify stored state,
 visibility, OCC and restart persistence, not just a 200 response.
+Before reporting any user-facing work as done, follow the [independent
+acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): run it
+with a fresh agent on the surface its user uses. This is not limited to MCP; if
+it was not run, say so explicitly and report the work as UNVERIFIED rather than
+done. For MCP workflows, also run the guide's design audit before implementing
+tools.
 
-For native Admin, read the [current guide](../../handbook/guides/native-admin.md).
-Select `--admin` / `admin: true`; mount `entries(bindings.schemas, bindings.adapter)`
-from the optional Admin package. Keep one Core SDK, the Admin product and shared
-UI kit at matching versions. Generate → typecheck → implement listed handlers →
-typecheck. Ref handlers retain caller-bound `ctx.store`; generic Admin reads
-use shared generated View templates and writes use native Procedure fragments.
+For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
+the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
+MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Keep matching SDK, Admin and UI versions. Ref handlers retain caller-bound
+`ctx.store`; generic Admin reads use shared generated View templates and writes
+use native Procedure fragments.
 Check actual member/Admin OTP, private scope/TTL/translation visibility, paging,
 statistics, safe/exact OCC and no automatic retry after unknown 503 outcomes.
 
+For application-owned MCP App entries and host checks, follow the [MCP Apps
+guide](../../handbook/guides/mcp-apps.md).
+
+Build a custom frontend with `App` from `@modelcontextprotocol/ext-apps`: register
+`ontoolinput`/`ontoolresult` before `connect()`, and use `callServerTool` for
+host-proxied calls. Keep protocol negotiation and message routing in the official
+client; importing its types while writing a second `postMessage` bridge is
+insufficient.
+
+For Admin UI upgrades, follow the installed handbook's
+[retained-page recipe](../../handbook/guides/mcp-apps.md#keep-old-conversations-working-after-an-upgrade).
+Keep deployed snapshots in source/artifact storage and pass `previous` to
+`adminMcpApps`; verify old conversations after a changed UI build without host
+tool refresh, reconnection or cache clearing. Keep tool contracts compatible
+through the declared retention window.
+
 
 Place admin MCP Procedures in Admin deliberately: `spec.uiSchema.collectionAction:
 <schema-name>` adds a collection-header action; `spec.target: { schema, id,
@@ -51,10 +71,17 @@ The runtime never creates, alters or checks tables. Boot and requests run no DDL
 
 For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
 Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
 ## Data paths
 
 Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.
+
+For simple creates/partial updates, prefer Store-backed ref Procedures; keep
+Procedure `requires`/generated input checks, use only allowed patch fields and
+return safe business fields with the actual returned ID/version. Preserve
+omitted fields and document null semantics. Retain SQL for atomic conditional
+or related writes; D1 batches cannot consume an earlier result. Follow the
+[Store write guidance](../../handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).

package/docs/skills/integrate/SKILL.md

@@ -12,13 +12,8 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
-
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
 Keep the application router, database/pool, identity and frontend. Replace
 Core consumers explicitly and compose only selected generated entries. Resolve
@@ -30,8 +25,8 @@ the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
 Verify cutover with actual app tests.
 
 Preserve the app router, verified identity and native resources. For selected
-Admin use the [native guide](../../handbook/guides/native-admin.md): three matching
-packages, generated checks and `entries(bindings.schemas, bindings.adapter)`.
+Admin, follow the [native guide](../../handbook/guides/native-admin.md) for its
+application-built bundle and service composition.
 Do not import old `/spec`, `/core` or runtime surface APIs. Review data/role
 migrations explicitly; full cross-target int64 parity and automated transfer
 are not this release's upgrade contract.

package/docs/skills/provision/SKILL.md

@@ -13,13 +13,8 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
-
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
 Deploy/create resources only within the user's authorization; reuse configured
 host resources. Apply reviewed and rehearsed migrations before routing traffic;
@@ -30,12 +25,20 @@ as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#wo
 Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
 including environment overrides; verify deployed MCP with a real OAuth bearer
 (`initialize` and `tools/list`), not only a browser session cookie.
+For MCP Apps, also follow [deployed host acceptance](../../handbook/guides/mcp-apps.md#verify-a-deployed-app-in-chatgpt):
+compare the current resource URI and visibly verify a newly invoked render tool.
+Archive deployed Admin pages using the guide's `previous` recipe and carry them
+through clean builds. Test the same old conversation after changing the UI build,
+without reconnecting, refreshing host tools or clearing caches. A deliberate tool
+contract change has its own migration/host rediscovery step. OAuth renewal, `tools/call` success and a
+local official-host replay do not establish that the deployed App rendered.
 Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
 (role admin), denied access, public reads, a persisted write, MCP and selected UI.
 Report artifact/resources/checks and keep rollback artifacts.
 
-Use the installed [Native Admin](../../handbook/guides/native-admin.md) asset
-contract and `entries(bindings.schemas, bindings.adapter)`. Admin SPA assets
-belong to `@aotter/mantle-admin`, while UI supplies the shared kit. Verify both
-member and admin OTP/UI flows. Deployment of an authorized application does
-not authorize SDK publication; a workspace preview remains a preview.
+For ChatGPT Sites, follow [Mantle on ChatGPT Sites](../../handbook/cloudflare/chatgpt-sites.md).
+
+The app builds Admin with `mantle bundle`; serve it as [Native
+Admin](../../handbook/guides/native-admin.md) describes. Verify both member and
+admin OTP/UI flows. Deployment of an authorized application does not authorize
+SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -12,24 +12,25 @@ metadata:
 
 ## Workflow
 
-Read the installed SDK README and version-matched handbook before editing.
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
-with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
-all generated output, run the same generation command with `--check`, and keep
-bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
+0.2 service a new database and move data by export and import; never boot 0.2
+against a 0.1.x database. Between 0.2 versions, apply reviewed migrations
+rehearsed on a copy.
 
-Pin exact target SDK/peer versions and read its release notes and Admin asset
-installation instructions. Core-to-native replaces app imports/wiring; it is not
-a package-only update. Preserve users, sessions, content and application code.
-Review emitted SQL/policy diffs and rehearse explicit data-preserving schema/auth/role
-migrations on a copy. Initial schema.sql never authorizes rebuilding production
-tables. Verify auth/Admin/MCP/REST, locks and persistence before authorized cutover.
+Pin exact target SDK/peer versions and read its release notes and Admin build
+instructions. Core-to-native replaces app imports/wiring; it is not
+a package-only update. For 0.2-to-0.2 updates, preserve users, sessions, content
+and application code; review emitted SQL/policy diffs and rehearse explicit
+data-preserving schema/auth/role migrations on a copy. Initial schema.sql never
+authorizes rebuilding production tables. Verify auth/Admin/MCP/REST, locks and
+persistence before authorized cutover.
 
-Follow [Native Admin](../../handbook/guides/native-admin.md) for the three-package
-SDK/Admin/shared-kit split and asset/extension/MCP App subpath moves; old UI
-subpaths have no compatibility aliases. Pin only actually published versions,
-or explicitly use a matching workspace preview. Recheck member and Admin OTP,
-all affected native routes, private field visibility, OCC and unknown outcomes.
-Do not publish a package as part of an application dependency update.
+Follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin)
+for the current application-built Admin; old UI subpaths have no compatibility
+aliases. Pin only actually published versions, or explicitly use a matching
+workspace preview. Recheck member and Admin OTP, all affected native routes,
+private field visibility, OCC and unknown outcomes. Do not publish a package as
+part of an application dependency update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0-alpha.9",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/client": "2.2.0",
     "@modelcontextprotocol/server": "2.2.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",

package/skills/README.md

@@ -27,7 +27,7 @@ release tag as the application's SDK; alpha releases on `develop` can be newer
 than the default `main` branch. For a skill-only installation:
 
 ```sh
-npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.8 --skill mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.9 --skill mantle
 ```
 
 The explicit skill name excludes repository maintainer skills. The manifests

package/skills/mantle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mantle
-description: Create or continue a Mantle application, test it locally and deploy to a user-owned host using the installed SDK docs.
+description: Create, continue, test or deploy a Mantle application using installed @aotter/mantle docs, including manifests, SQL Views and Procedures, MCP tools, app-built Admin, mantle generate and Mantle upgrades.
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/mantle/SKILL.md
@@ -21,10 +21,29 @@ checkout, or any online copy.
 
 Work in the user's application, outside the SDK checkout. Read package.json, the lockfile, installed SDK README and node_modules/@aotter/mantle/docs/. Those files define the exact version's contract. Preserve existing identity, handles, routes and resources.
 
+## Choose the installed package skill
+
+- Read `node_modules/@aotter/mantle/docs/skills/develop/SKILL.md` to change an existing project's manifests, SQL, handlers, service entry or surfaces.
+- Read `node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` to add Mantle to an application with existing code, users or data.
+- Read `node_modules/@aotter/mantle/docs/skills/update/SKILL.md` to upgrade Mantle, including from 0.1.x.
+- Read `node_modules/@aotter/mantle/docs/skills/provision/SKILL.md` only for an authorized production deployment.
+- Read `node_modules/@aotter/mantle/docs/skills/media-gc/SKILL.md` only to audit or remove stale uncommitted media uploads.
+
 For a new project, install an exact published SDK version with matching selected Admin/UI packages. Node must be 22.22 or newer. Add TypeScript and target types; Workers also need Wrangler. `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the Wrangler, TypeScript and type-package versions this release is tested with. Optional auth/MCP peers use the installed SDK's package.json versions. Read the installed handbook's start/project-and-cli.md before choosing a target.
 
 For a new Cloudflare app, copy `node_modules/@aotter/mantle/docs/examples/app-shell/` first, then the closest example from `docs/examples/README.md` on top of it, and edit from there: manifests, `src/handlers.ts`, `src/routes.ts`, `src/schedule.ts`, `smoke.mjs`. Search for `AGENT:` to find what the app must fill in; the example pages are unstyled on purpose, so styling them is part of that work. Before reporting done, resolve each `AGENT:` or name the ones you left. Keep the two roles `admin` and `user` unless the user asks for more.
 
+Before reporting any user-facing work as done, follow the installed
+`node_modules/@aotter/mantle/docs/handbook/guides/agent-workflow-acceptance.md`:
+run independent acceptance with a fresh agent on the surface its user uses.
+This is not limited to MCP; if it was not run, say so explicitly and report the
+work as UNVERIFIED rather than done. For MCP workflows, also run the guide's
+design audit before implementing tools. This workflow practice applies to every
+installed SDK version: if its guide is older or MCP-scoped, apply its fresh-agent
+round loop to the user-facing surface actually built. If an older installed
+version lacks this guide, record the missing guidance and preserve that version's
+contract; do not silently upgrade or substitute checkout/online docs.
+
 For existing older applications, use their installed docs until the user requests an upgrade. For partial adoption read node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md.
 
 ## Generated native applications
@@ -44,16 +63,16 @@ cookieCache `{enabled:true,maxAge:60,refreshCache:false,version:"read-60-v1"}` a
 no KV. Bump version when enabling/changing the policy; writes, Admin, consent,
 unknown/ref/media calls stay fresh. Read the installed auth docs before MCP caching.
 
-Use the workflow **generate → typecheck → implement listed handlers**. For example:
+Use the workflow **generate → implement listed handlers → check**. In an app
+copied from the installed app shell, its scripts are the canonical commands:
 
 ```sh
-pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml
-pnpm exec tsc --noEmit
-pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --check
+pnpm generate
+pnpm check
 ```
- Implement every printed `Handlers` key
+Implement every printed `Handlers` key
 and pass the implementations at `store(db, caller, { handlers })` (and selected
-surface options). Run `tsc --noEmit` again before local acceptance.
+surface options).
 Generated Store metadata initializes on its first use, once per module. Bind
 `store(db, caller, options?)` for the current request; never reuse one caller's
 bound Store for another caller.
@@ -78,12 +97,12 @@ Resolve conflicts by merging manifests/options and regenerating. Add the printed
 `.gitattributes` line and run the same generate command with `--check` in CI.
 Compose the app-owned `fetch` using `docs/handbook/cloudflare/service-entry.md`: auth/consent, Admin,
 MCP, REST behind one request-local origin-checked resolver; keep heavy auth dynamic.
+Pair every HTTP Trigger with an MCP Trigger by default; see `docs/handbook/reference/trigger.md` for the generate warning and deliberate asymmetry exception.
 
 For selected native Admin, follow the version-matched
-`docs/handbook/guides/native-admin.md`: select `--admin` (or `admin: true`),
-mount `entries(bindings.schemas, bindings.adapter)` and serve the Admin assets
-separately. The three-package preview is one Core SDK, the Admin product and the
-shared UI kit.
+`docs/handbook/guides/native-admin.md`: select `--admin` (or `admin: true`), then
+build and serve the application-owned Admin with `mantle bundle` as that guide
+describes.
 Admin reads share generated whitelisted native View templates, writes use native
 Procedure fragments and generated checks. Ref operations retain typed `ctx.store`
 at request time. Verify member/frontend and admin/Admin OTP, tenant/privacy/TTL,
@@ -128,8 +147,11 @@ To add Mantle to an application that has its own code, users and data, read
 `node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` first.
 
 Report the project path, the exact Mantle version, what you changed, the checks
-you ran with their results, and anything left for the user.
+you ran with their results, the independent acceptance verdict (CONVERGED / NOT
+CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.
 
 ## Data paths
 
-Writes use Store `insert` / `update` / `delete`, atomic `batch` / supported `transaction`, or declared Procedures. Raw SQL writes bypass row rules. Use internal Views for joins, aggregates, OR and reusable reads; Store `findById` / `find` / `first` are for id lookups and simple AND filters. Ref handlers receive `ctx.store` with the same Caller and transaction.
+Follow the installed `docs/handbook/guides/typed-queries.md` for Store,
+Procedure and View data paths; the service composition guide owns request-local
+Caller binding.

package/skills/mantle/references/local-testing.md

@@ -13,3 +13,8 @@ Better Auth limits each email-OTP path to 3 requests/minute per IP; `authHardeni
 - For selected remote MCP, use the installed `docs/examples/app-shell/smoke-kit.mjs` `assertMcpDiscovery(endpoint, { tools, headers })` in the application's smoke scenario. Derive `tools` from the generated `mcp.ts` exports, or the pure static `developerConsole.interfaces.callable` in generated `admin-descriptors.ts`; filter to the selected surface and explicitly select the expected permitted subset when application authorization narrows it. Include app-composed tools when present. Do not count `describe.targets` or reconstruct authorization rules in the harness. Assert initialized discovery and all `tools/list` pages; a 404, HTML 200, protocol error or missing expected tools must fail. Keep anonymous/member denial assertions separate. Discovery never needs a business-write `tools/call`.
 - Supply test credentials from the application's normal authorized sign-in/test setup (the smoke kit's console OTP sign-in is valid). The discovery assertion only receives credentials: it must not acquire credentials itself, scrape other sessions or manufacture authority. Report local cookie-session discovery, OAuth Bearer/client integration and browser WebMCP as separate evidence. Cookie or WebMCP success does not prove remote OAuth/ChatGPT wiring; missing credentials leave that case unverified, not passed. Do not enable remote routes or OAuth merely to make acceptance pass.
 - Record commands and passed/failed/blocked cases for the exact commit. Fix failures before source admission; rerun relevant checks after changing source. Packing does not run these checks and an agent's checklist is not server build attestation.
+
+Independent acceptance for every user-facing workflow follows the installed
+`docs/handbook/guides/agent-workflow-acceptance.md`. Scripted smoke is separate
+evidence; browser or host rendering is the acceptance surface for UI and MCP App
+deliverables.

package/skills/mantle/references/website.md

@@ -7,8 +7,8 @@ selected host's frontend kit before choosing APIs. Native applications use
 their installed `docs/handbook/guides/native-admin.md` and the
 [web contract](web.md).
 
-- For self-hosted applications, mount the selected Admin API and serve the
-  separate Admin package's assets with its shell/CSP contract. The application
+- For self-hosted applications, build Admin with `mantle bundle` and serve it as
+  the installed `docs/handbook/guides/native-admin.md` describes. The application
   owns auth, OTP delivery and verified Caller wiring; use a console/test sender
   locally and configure production email for deployment. If a host already
   supplies identity/Admin, reuse its explicit contract and reserved routes.
@@ -38,8 +38,10 @@ Follow the [local HTTP acceptance](local-testing.md) before reporting local
 readiness: inspect HTML without JavaScript, check metadata/sitemap and anonymous
 draft/permission refusal, and exercise OTP and editing with isolated synthetic
 accounts. Local readiness does not require publication, a hosted tenant or a
-candidate preview. Report production email, public origin and real object-store
-upload/commit checks separately when local capabilities cannot exercise them.
+candidate preview. Scripted local acceptance does not replace the installed
+independent acceptance guide, which is required before reporting the pages done.
+Report production email, public origin and real object-store upload/commit checks
+separately when local capabilities cannot exercise them.
 
 For an explicitly requested deployment, use the selected host's native workflow
 and any preview it provides. Verify disabled preview capabilities on an already