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

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

@@ -10,13 +10,21 @@ description: Generation targets, CLI options and ownership of native application
 | `generated/` | Generator: TypeScript, native SQL and selected bindings |
 | `migrations/` | App's agent and native migration tool |
 | `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
-| `dist/` | Disposable bundle output; do not commit |
+| `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
 mantle generate <target> <output-directory> <manifest>... [options]
-mantle bundle <entry> <outdir>
+mantle bundle <entry> <outdir> [--assets <dir>]
 ```
 
 | Target | Dialect | Handle |
@@ -34,24 +42,24 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 | `--admin` | Emit native Admin bindings and `admin/*` modules; install the separate Admin package. |
 | `--auth <module>` | Read plain `authOptions(env)` (or an exported auth instance's options) and append selected Better Auth DDL. Repeat it once per Better Auth instance. Prefer plain options without initialization side effects. |
 | `--site <module>` | Read `siteDefaults`; emit site/media bindings and deployment SQL. |
-| `--admin-extensions <module>` | Read the named/default `adminExtensions` array and the optional `navGroups` (sidebar groups; see native-admin.md "Sidebar"). The app shell passes `src/admin.ts`. |
 | `--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>` | Split bundle output; default `dist`. Keep separate from source/generated files. |
+| `--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. New assets blocks default to `ASSETS`, Worker-first routing and no HTML rewriting; existing blocks keep their binding/routing. |
 
 ## Outputs
 
-`generated/.mantle-inputs.json` records the Mantle version and a hash of every input the run read (manifests and the
-`--auth`, `--site`, `--admin-extensions` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
+`generated/.mantle-inputs.json` records the Mantle version, the target, and a hash of every input the run read (manifests and the
+`--auth` and `--site` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
 deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
 Commit it with the other generated files.
 The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
 through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 
-`generated.ts` exports typed queries and Store. Direct `views/<encoded-name>.ts` and `procedures/<encoded-name>.ts` entries export an operation and its types. Proved pageable Views also have `paged/views/*`; boundary checks live in `validation/*`. `admin-descriptors.ts`, `rest.ts` and `web.ts` are always emitted. Manifest exposure selects `mcp.ts`; `admin-bindings.ts` and `admin/*` require `--admin`. Auth and site are explicit options.
+`generated.ts` exports typed queries and Store. Direct `views/<encoded-name>.ts` and `procedures/<encoded-name>.ts` entries export an operation and its types. Proved pageable Views also have `paged/views/*`; boundary checks live in `validation/*`. `admin-descriptors.ts`, `rest.ts` and `web.ts` are always emitted. Manifest exposure selects `mcp.ts`; `admin-bindings.ts`, `admin-client.ts` (browser-side types and hooks for `admin.tsx`) and `admin/*` require `--admin`. Auth and site are explicit options.
 
 Apply `schema.sql` only to an empty database. Later changes require [explicit migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations); generation and runtime do not inspect the database. Ref declarations print the `Handlers` keys to implement.
 
 Never edit generated output by hand. Merge manifests/options, regenerate with the same command, then review TypeScript and SQL diffs. Use that exact command with `--check` in CI. Unmarked app files are preserved. Imported option modules must be pure; generation does not make their side effects safe.
 
-On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM with a startup guard for eager Better Auth imports. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler. See [service composition](../cloudflare/service-entry.md).
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM into `<outdir>/worker` with a startup guard for eager Better Auth imports and for Admin's browser code (`@aotter/mantle-admin/app` and `/hooks`, which `generated/admin-client.ts` imports; they belong to `admin.tsx`). When the Worker imports `@aotter/mantle-admin/server`, it also builds Admin with Vite into `<assets>/admin` (`--assets`, default `<outdir>/client`), from `admin.tsx` beside the Worker entry or Admin's built-in entry; `src/admin.ts` is not an entry. The assets directory must not overlap the Worker directory, and neither the outdir nor the assets directory may be the working directory or contain the Worker entry. The built-in entry is not rebuilt while the installed `@aotter/mantle-admin` keeps its path and version and its direct dependencies and its `react`/`react-dom` peers keep theirs; an `admin.tsx` entry builds every time. The build needs no install scripts (`npm ci --ignore-scripts` works). A `package-lock.json` made on one OS can lack the native build binaries (rolldown, `@tailwindcss/oxide`, lightningcss) that npm installs per platform from `optionalDependencies`, so a lockfile made on macOS can fail the build on a Linux host; create the lockfile on the build platform or use pnpm. `wrangler dev` and `wrangler deploy` run that build command, so they need `node_modules`. The built output (`<outdir>/worker`, `<assets>`) never reads it, so a pipeline that deletes `node_modules` must run `wrangler deploy` first. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler; Bun runs the server as TypeScript, so for a `bun-*` target recorded in `.mantle-inputs.json`, `mantle bundle src/server.ts dist` skips the Worker bundle and builds only Admin, into `dist/client/admin` (read with `bunAdminAssets("dist/client/admin")`, adapted for `adminShell` as in service composition). See [service composition](../cloudflare/service-entry.md).

package/docs/handbook/start/quickstart-worker.md

@@ -3,7 +3,7 @@ description: Generate a small native D1 service and mount an application-owned W
 ---
 # Quickstart: a service on Workers
 
-Create an application outside the SDK checkout. Install an exact released `@aotter/mantle` version, TypeScript, Wrangler and Cloudflare Worker types. Read that installed version's handbook; this page describes the native 0.2.0 contract.
+Create an application outside the SDK checkout. Install an exact released `@aotter/mantle` version, TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2.0 contract.
 
 Save `manifests/tickets.yaml`:
 

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` accepts open role names.
-
-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,
@@ -41,8 +61,9 @@ version? }` selects row actions and binds the row id / reviewed OCC version to
 the named inputs. Other admin operations appear under Operations in the sidebar.
 Keep state conditions in the SQL WHERE: simple AND equality/IN literals become
 row-menu hints, while the Procedure remains the authority. Required-ref child
-collections fold under their parent's sidebar group; use Schema
-`uiSchema.nav.standalone: true` for a top-level entry.
+collections fold under their parent's sidebar group; with two or more required
+`id` refs, set Schema `uiSchema.nav.parentField` to the parent's ref (generate
+refuses otherwise); use `uiSchema.nav.standalone: true` for a top-level entry.
 
 ## Database changes
 
@@ -50,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` accepts open role names.
+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/media-gc/SKILL.md

@@ -41,11 +41,13 @@ objects approved by the user.
 
 `POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
 minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
-copies each checked object to `<purpose>/<group>/<role>.<ext>` (with
-`committedAt` metadata) and deletes the upload key; a rejected group's upload
-keys are deleted. So an object still under `uploads/` long after its URL
-expired belongs to an upload that was never committed, and nothing can commit
-it any more. Objects outside `uploads/` are committed media: never candidates.
+copies each checked object to `committed/<group>/<attempt>/<role>.<ext>` (with
+`committedAt` metadata); the attempt UUID isolates concurrent commits. Upload
+keys are removed after the database commit succeeds, or when a group is
+rejected. An old upload key may also be leftover cleanup from a successful or
+uncertain commit: it is not evidence that the media row is absent. Once expired,
+it cannot create a new asset. Objects outside `uploads/` are never candidates;
+reconcile attempt copies separately with live database references.
 
 ## Audit
 

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` accepts open role names.
+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;
@@ -27,12 +22,23 @@ imports/first requests perform no DDL or schema checks. Keep auth dynamic, produ
 secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
 production email and selected media wiring. Configure Admin ASSETS worker-first
 as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
+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` accepts open role names.
+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/docs/upgrade-0.1-to-0.2.md

@@ -13,12 +13,12 @@ The remainder describes the earlier alpha contract for historical reference.
 
 No codemod, and no in-place upgrade of a 0.1.x database. A coding agent moves
 one project by hand with this guide. When it and
-[ADR-0032](https://github.com/aotter/mantle/blob/develop/docs/adr/0032-store-centric-core-and-service-contract.md),
-[ADR-0033](https://github.com/aotter/mantle/blob/develop/docs/adr/0033-storage-converges-to-the-plan.md),
-[ADR-0034](https://github.com/aotter/mantle/blob/develop/docs/adr/0034-store-is-authored-as-sql.md),
-[ADR-0035](https://github.com/aotter/mantle/blob/develop/docs/adr/0035-sql-dialects.md),
-[ADR-0036](https://github.com/aotter/mantle/blob/develop/docs/adr/0036-host-and-dialect.md) or
-[ADR-0038](https://github.com/aotter/mantle/blob/develop/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
+[ADR-0032](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
 
 ## Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.0-alpha.9",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -92,6 +92,7 @@
     }
   },
   "devDependencies": {
+    "@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

@@ -21,25 +21,20 @@ distributions (ADR-0032 decision 13):
 
 ## Install
 
-```bash
-# Claude Code: two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
+Use the [agent setup guide](../docs/handbook/guides/agent-setup.md) for Codex,
+Claude Code, Cursor and GitHub Copilot. Pin the plugin checkout to the same
+release tag as the application's SDK; alpha releases on `develop` can be newer
+than the default `main` branch. For a skill-only installation:
 
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
+```sh
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.9 --skill mantle
 ```
 
-Cursor and GitHub Copilot read the manifests from the repository
-(`.cursor-plugin/plugin.json`, `.copilot-plugin/plugin.json`). Without a
-plugin host, `npx skills add aotter/mantle` installs the `mantle` skill and its
-references. The manifests are generated by
-`scripts/sync-plugin-manifests.mjs` and checked with `--check`.
-
-Claude Code updates an installed plugin only when its manifest version
-changes, and that version is Core's, so a skill or script update reaches
-Claude Code users with the next Core release.
+The explicit skill name excludes repository maintainer skills. The manifests
+are generated by `scripts/sync-plugin-manifests.mjs` and checked with `--check`.
+When upgrading, update the marketplace ref or local tagged checkout and refresh
+the plugin. Verify the loaded manifest version; Claude Code's plugin version
+is Core's, so packaged skill changes reach users through the next Core release.
 
 ## Disclosure audit
 

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.
 
-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. 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.
+## 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,18 +97,18 @@ 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,
 publishing, paging, statistics, exact OCC, ref effects and the actual console;
 never retry unknown 503 writes automatically. Read the installed Admin README
-for extensions, raw-body limits, CSP/assets, 22 languages and the developer workspace.
+for raw-body limits, CSP/assets, 22 languages and the developer workspace.
 Use only versions actually published, or the explicitly linked workspace packages.
 
 For generated native applications, optional site settings/media are selected
@@ -107,7 +126,7 @@ without asking the user to enumerate OTP, media, Admin or SEO. Defaults are
 acceptance requirements, not evidence that a missing renderer is implemented.
 Do not report a complete website with blocked required checks.
 
-Run the [local HTTP acceptance](references/local-testing.md) for handlers and websites; compilation does not execute their behavior.
+Run the [local HTTP acceptance](references/local-testing.md) for handlers and selected interfaces; compilation does not execute their behavior. Account for every declared interface as verified, intentionally not exposed, or deferred/unverified with a reason in the existing application handoff. An early preview may defer remote MCP; preserve that pending work. WebMCP, cookie-session discovery and OAuth Bearer/client integration are separate checks.
 
 ## Self-hosted deployment
 
@@ -120,7 +139,7 @@ workflow. Local project creation alone is not deployment authorization.
 Preserve the user's manifests, `src/` files, identity, package versions and
 provider resources. The app writes its entry (`src/worker.ts` by default;
 `--entry` selects another). Workers generation creates or updates Wrangler's
-split-build settings. Run the same generation command (target, output directory,
+split-build settings and public-fetch compatibility flags. Run the same generation command (target, output directory,
 manifests and options) with `--check`, and the project's own tests,
 before and after a change.
 
@@ -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

@@ -7,5 +7,14 @@ Better Auth limits each email-OTP path to 3 requests/minute per IP; `authHardeni
 
 - Exercise actual HTTP Triggers for every custom Procedure handler: valid input/output, invalid input, anonymous refusal on protected operations, authorized synthetic caller and expected stored result. A status below 500 alone is not success; assert the expected status and JSON envelope/body. Use only the generated contract's routes, inputs and permissions.
 - For an app-owned `fetch`, exercise its real public routes, not just dist files. Assert HTML content type, visible content and metadata/canonical/JSON-LD with no JavaScript execution, sitemap, robots and an unknown URL returning 404. Create a local synthetic draft and assert it is hidden anonymously; publish, edit and delete it through authorized operations and check the page and sitemap after each change. Reuse the application's existing smoke-test pattern and clean up test rows/server in `finally`.
+- If the app serves Admin, run `npm run build` and then `node --test generated/admin-mcp-app.check.mjs` (the examples name it `npm test`): the generated `generated/admin-mcp-app.check.mjs` loads the Admin MCP App in an MCP host and fails on a network request, console error or exception. It needs `playwright-core` (a devDependency) and Chrome (`npx playwright-core install chromium` or `MANTLE_TEST_CHROMIUM`); with no browser it fails, so report it as blocked rather than skipped. See `docs/handbook/guides/mcp-apps.md`.
 - Keep caller authority explicit: use supplied `resolveCaller` and caller-scoped Store/Procedure APIs from the installed service-entry docs. Use the actual local host capabilities; local tests do not prove remote identity/provider wiring.
+- Account for each declared interface separately: verified with the command/identity/result, intentionally not exposed, or deferred/unverified with a reason. Generation proves declaration and artifacts, not route mounting. An early Admin preview or a WebMCP-only application may defer remote MCP; preserve that pending item in the application's existing README, handoff or test report, without a new status/configuration format.
+- 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/web.md

@@ -3,7 +3,7 @@
 Use this flow only when the installed package README documents concrete native
 queries and generated `web.ts`.
 Earlier Core versions use their own installed handbook. Read the installed
-`docs/handbook/reference/surface.md` and `docs/examples/generated-web/README.md` before writing
+`docs/handbook/reference/surface.md` and `docs/examples/generated-web/README.md` under `node_modules/@aotter/mantle/` before writing
 routes; the installed version is authoritative.
 
 Mount `web()` when the application serves public HTML and needs `llms.txt`, a