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

package/docs/examples/purchasing/manifests/purchasing.yaml

@@ -25,7 +25,7 @@ spec:
   title: Purchase requests
   lifecycle: operational
   indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id]]
-  # Sidebar: in the Approvals group (src/admin.ts), after the queue of requests waiting for a decision.
+  # Sidebar: in the Approvals group (src/admin.tsx), after the queue of requests waiting for a decision.
   uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { group: approvals, order: 2 } }
   schema:
     type: object
@@ -117,6 +117,7 @@ kind: Procedure
 metadata: { name: submit-request }
 spec:
   title: Submit a purchase request
+  description: Submit a purchase request against an existing department budget.
   requires: { auth: { all: [ctx.user] } }
   input:
     type: object
@@ -140,6 +141,7 @@ kind: Procedure
 metadata: { name: change-amount }
 spec:
   title: Change the amount of my request
+  description: Change the amount of the signed-in member's submitted purchase request.
   requires: { auth: { all: [ctx.user] } }
   restrict: { requests: "author_id = auth.uid()" }
   input:
@@ -291,11 +293,25 @@ spec:
 ---
 apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger
+metadata: { name: submit-request-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
 metadata: { name: change-amount-http }
 spec:
   source: { kind: http, method: POST, path: '/api/requests/{id}/amount' }
   target: { procedure: change-amount }
 ---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: change-amount-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: change-amount }
+---
 # Admin MCP tools: an AI agent connected to /mcp/admin can approve or reject.
 apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger

package/docs/examples/purchasing/smoke.mjs

@@ -3,7 +3,8 @@
 import assert from "node:assert/strict";
 import { createHmac } from "node:crypto";
 import { createServer } from "node:http";
-import { smoke } from "./smoke-kit.mjs";
+import { assertMcpDiscovery, smoke } from "./smoke-kit.mjs";
+import { developerConsole } from "./generated/admin-descriptors.ts";
 
 const SECRET = "local-supplier-secret", DAILY = "0 9 * * *", DAY_US = 86_400 * 1_000_000;
 
@@ -22,7 +23,7 @@ const supplier = createServer((request, response) => {
 await new Promise(resolve => supplier.listen(0, "127.0.0.1", resolve));
 
 try {
-  await smoke(async ({ owner, call, mcp, signIn, sql, cron, waitForLog, step, logs }) => {
+  await smoke(async ({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs }) => {
     const query = sql;
     const row = async id => (await query(`SELECT requeststatus AS status, version, supplierorderid AS "supplierOrderId" FROM requests WHERE id = '${id}'`))[0];
     const statusAndOrder = async id => { const { status, supplierOrderId } = await row(id); return { status, supplierOrderId }; };
@@ -77,9 +78,14 @@ try {
 
     const version = async id => (await row(id)).version;
     assert.equal((await operation(alice, "approve-request", { id: laptop, expectedVersion: await version(laptop) })).status, 403);
-    const publicTools = (await mcp("/mcp", alice)).body.result.tools.map(t => t.name);
+    // Generated static metadata uses the MCP tool names; the app chooses the surface and test identity.
+    const declared = developerConsole.interfaces.callable;
+    const publicTools = await assertMcpDiscovery(`${origin}/mcp`, { headers: { cookie: alice, origin }, tools: declared.filter(tool => tool.surface === "public") });
     assert.ok(!publicTools.includes("approve_request") && !publicTools.includes("reject_request"), publicTools.join());
-    const adminTools = (await mcp("/mcp/admin", admin)).body.result.tools.map(t => t.name);
+    const adminTools = await assertMcpDiscovery(`${origin}/mcp/admin`, { headers: { cookie: admin, origin }, tools: declared.filter(tool => tool.surface === "admin") });
+    // Denial is separate from successful initialized discovery.
+    assert.equal((await mcp("/mcp/admin")).status, 401);
+    assert.equal((await mcp("/mcp/admin", alice)).status, 403);
     assert.ok(adminTools.includes("approve_request") && adminTools.includes("reject_request"), adminTools.join());
     for (const hidden of ["confirm_order", "mark_ordered", "approve_request_write", "reject_request_write"])
       assert.ok(!adminTools.includes(hidden) && !publicTools.includes(hidden), hidden);

package/docs/examples/purchasing/src/admin.tsx

@@ -0,0 +1,13 @@
+import { defineAdmin } from "@aotter/mantle-admin/app";
+import { admin } from "../generated/admin-client.js";
+
+/**
+ * The Admin entry, built by `mantle bundle`. The approver's daily work gets its own sidebar group above Admin's
+ * built-in ones (content 10, operations 20, reports 30; More stays last); manifests place `pending-requests` and
+ * `requests` in it with `uiSchema.nav`. `tsc` refuses a manifest group left undeclared here.
+ * AGENT: add groups for how the staff work; titles take one string or a { locale: text } map.
+ */
+export default defineAdmin(admin, {
+  nav: { groups: { approvals: { title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 } } },
+  pages: [{ path: "guide", title: "Approver guide", element: <p>Approve a request when the amount fits the budget; reject it with a reason otherwise.</p>, nav: { group: "approvals", order: 9 } }],
+});

package/docs/examples/purchasing/src/handlers.ts

@@ -14,7 +14,7 @@ export const handlers: Handlers = {
     } catch (error) {
       // The declared budget check is a business refusal, not a server error. Nothing was written.
       // The approval's only Schema check is the budget one.
-      if (error instanceof ContractError && error.code === "CONFLICT" && error.message.startsWith("A check of the Schema failed"))
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.fields?.kind === "check" && error.fields.schema === "budgets")
         throw new ContractError("CONFLICT", "The department budget cannot cover this request.", "procedures/approve-request");
       throw error;
     }

package/docs/examples/purchasing/wrangler.jsonc

@@ -1,10 +1,11 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "mantle-app",
-  "main": "dist/index.js",
+  "main": "dist/worker/index.js",
   "compatibility_date": "2026-09-01",
   "compatibility_flags": [
-    "nodejs_compat"
+    "nodejs_compat",
+    "global_fetch_strictly_public"
   ],
   "vars": {
     "EMPLOYEE_DOMAIN": "example.com"
@@ -36,7 +37,7 @@
     }
   ],
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -48,7 +49,7 @@
   },
   "no_bundle": true,
   "find_additional_modules": true,
-  "base_dir": "dist",
+  "base_dir": "dist/worker",
   "build": {
     "command": "mantle bundle src/index.ts dist",
     "watch_dir": [

package/docs/examples/recipes/wrangler.jsonc

@@ -1,10 +1,11 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "mantle-app",
-  "main": "dist/index.js",
+  "main": "dist/worker/index.js",
   "compatibility_date": "2026-09-01",
   "compatibility_flags": [
-    "nodejs_compat"
+    "nodejs_compat",
+    "global_fetch_strictly_public"
   ],
   "secrets": {
     "required": [
@@ -43,7 +44,7 @@
     "MEDIA_S3_ENDPOINT": "https://mantle-app-media.ACCOUNT_ID.r2.cloudflarestorage.com"
   },
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -53,7 +54,7 @@
   },
   "no_bundle": true,
   "find_additional_modules": true,
-  "base_dir": "dist",
+  "base_dir": "dist/worker",
   "build": {
     "command": "mantle bundle src/index.ts dist",
     "watch_dir": [

package/docs/handbook/cloudflare/authentication.md

@@ -12,7 +12,24 @@ Mantle supplies the database adapter, schema generation and caller resolution:
 
 ## `auth.ts`
 
-Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages.
+> **Verification status:** the GitHub social-provider and magic-link recipes have not yet been exercised end to end against real deployed provider flows.
+
+Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages;
+installed, it is `node_modules/@aotter/mantle/docs/examples/app-shell/src/auth.ts`. Its essentials:
+
+- Imports: `betterAuth` from `better-auth/minimal`; `admin`, `emailOTP` (and `jwt` for MCP) from `better-auth/plugins`;
+  `createAccessControl` from `better-auth/plugins/access`; `defaultStatements` from `better-auth/plugins/admin/access`;
+  `d1Adapter` from `@aotter/mantle/auth/adapter`; the hardening and bootstrap helpers below. For MCP it also imports `jwt`,
+  `mcp` from `@better-auth/mcp`, `cimd` from `@better-auth/cimd` and `oauthGrantExtension`/`oauthGrantRevocation` from
+  `@aotter/mantle/auth/oauth`; the file marks that block as deletable.
+- `authOptions(env)` returns plain options and is the module's export for `--auth src/auth.ts`. Generation calls it with an
+  empty `env`, so it must not throw: fall back to placeholders for `secret` and origin there.
+- The bootstrap admin: `d1BootstrapAdmin(env.DB, { match: "email", value: env.ADMIN_EMAIL }, () => ({ options: { plugins } }))`
+  is assigned to `databaseHooks.user.create.after` and `.update.after` ([Identity helpers](#identity-helpers)).
+- `createAuth(env)` is the same module's second export: it checks its three variables are set and returns
+  `betterAuth(authOptions(env))`. The Worker's `authLoader(() => import("./auth.js").then(m => m.createAuth(env)))`
+  ([service composition](service-entry.md)) is what calls it.
+
 The application owns Better Auth and its optional plugins. Schema generation reads plain options without constructing
 Better Auth; apply `schema.sql` during deployment, never at boot. OAuth resource
 rows are created on first OAuth use from runtime configuration; they require no
@@ -63,6 +80,7 @@ after success; invitations still work when email is absent.
 `databaseHooks.user.create.after` (and user.update.after for a later email verification). Only the first matching signup wins (case-insensitive); email matching requires emailVerified=true (required for bootstrap).
 D1 uses one conditional UPDATE; PostgreSQL uses a transaction advisory lock before UPDATE, avoiding concurrent winners.
 A blocked promotion logs a warning. A GitHub rule requires a configured trusted GitHub provider/profile mapper.
+The promotion runs after Better Auth creates the user, so the first sign-in response (and a cached session payload) can still show the previous role, while authorization re-reads the role on every request and `/admin/api/me` and later sessions show the admin role.
 Helpers run no boot queries or DDL.
 
 ## Worker entry
@@ -154,7 +172,12 @@ Better Auth adapter code stays outside the Worker startup graph.
 
 `@aotter/mantle/auth/admin` exports `guardAuthAdminRequest(request, resolveFreshCaller, basePath?)` for selected auth transports. It resolves authority only for raw/encoded admin paths, requires an admin cookie session and checks mutation origin. Both the app-owned template and OAuth routes use this same guard.
 
-`ctx.admin` role names are open and must match `^[a-z][a-zA-Z0-9_]{0,62}$`. Bare `ctx.admin` admits any admin; a list admits admins holding one of its roles. Better Auth’s `adminRoles` decides who is an admin. Member role names alone grant no privilege.
+Bare `ctx.admin` admits any verified admin layer classified by Better Auth's
+`adminRoles` / `adminUserIds`. Role lists in `requires` are refused; decide
+per-target permissions in `authorize(target, caller)`, using `hasAdminRole`
+when appropriate. Verified role names match `^[a-z][a-zA-Z0-9_-]{0,62}$`.
+Member role names alone grant no privilege. See
+[authorization requirements](../reference/authorization.md).
 
 The generated auth DDL adds a native `(createdAt, id)` member-paging index (respecting schema field/table names). Unfiltered forward/backward paging orders native timestamps through that index; PostgreSQL cursors retain all six fractional digits and bind as text before timestamp casting. Member search (`%term%` over id/name/email, casting UUID ids to text only in the search expression) is a full scan; the index does not accelerate it.
 
@@ -164,10 +187,24 @@ The default is one instance with `admin` and `user` roles. An app that keeps two
 staff and customers) can run one Better Auth instance per population in the same Worker; every Mantle primitive
 takes the instance it works on:
 
-- Give each instance its own `basePath`, `advanced.cookiePrefix`, `secret` and table names (`user.modelName`,
-  `session.modelName`, ... and plugin `schema` options). Keep each instance's options in its own module and pass
-  one `--auth` per module to `mantle generate`; the tables are merged into one migration, and two instances that
-  define the same table differently are refused. The native adapter follows each instance's mapping.
+- Give each instance its own `basePath`, `advanced.cookiePrefix`, `secret` and core table names (`user.modelName`,
+  `session.modelName`, `account.modelName`, `verification.modelName`). Keep each instance's options in its own
+  module and pass one `--auth` per module to `mantle generate`; the tables are merged into one migration, and two
+  instances that define the same table differently are refused. The native adapter follows each instance's mapping.
+- Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances
+  in one Worker override each other. Use one of two supported ways:
+  1. Separate the instances by core table names only and leave every plugin mapping at its default.
+  2. When plugin tables must differ (`jwt`'s `jwks`, `@better-auth/oauth-provider`'s `oauth*` tables), map them
+     explicitly in every instance, the default one included, and give each instance its own copy of the plugin's
+     schema right after constructing it:
+     `const keys = jwt({ schema: { jwks: { modelName: "staff_jwks" } } }); const plugin = { ...keys, schema: structuredClone(keys.schema) };`
+
+  `mantle generate` refuses anything else when two or more `--auth` instances use the same plugin (`jwt`, `admin`,
+  `oauth-provider`, `two-factor`, `phone-number`, `anonymous`, `siwe`, `device-authorization`) and a mapping exists
+  while an instance keeps the shared schema object, or two instances resolve a mapping to the same name (generate
+  cannot tell an identical mapping from an inherited one, so mapped names must differ between instances). Build
+  every instance's plugins in the same order in the Worker as in `--auth`; an instance built earlier than a mapped
+  one can still inherit its mapping, which generate cannot see.
 - One `authLoader(load, cookiePrefix)` per instance; call `resolveCaller(request, loader)` with the instance the
   route belongs to, and mount `authRoutes(loader, ...)` per instance (it guards that instance's `/admin/*`). The
   loader takes `cookiePrefix` separately on purpose: it checks the cookie before loading Better Auth, so anonymous

package/docs/handbook/cloudflare/chatgpt-sites.md

@@ -1,9 +1,11 @@
 # Mantle on ChatGPT Sites
 
+> **Verification status:** this guide is experimental and has not yet been exercised end to end on a real ChatGPT Site.
+
 Treat the Site as an existing TypeScript host. Import selected generated Views/Procedures, pass the host's native handle and verified Caller, and compose only the surfaces it supports. Use [partial integration](../../skills/integrate/SKILL.md); Mantle supplies no Sites-specific identity or deployment adapter.
 
 Choose postgres or sqlite according to the host's actual SQL executor. Custom handles are app-owned; a structural match alone does not guarantee driver semantics. [Database boundaries](../concepts/runtime-and-adapters.md) defines the supported drivers.
 
-The runtime never creates, alters or checks tables. Apply initial `schema.sql` and selected auth/site DDL only to an empty database. For later changes the agent diffs regenerated SQL, writes and rehearses a host-native migration on a copy, and applies it before publishing new code. Cloud executes migrations at deploy time. Destructive/type changes require explicit data migration; Mantle drops nothing.
+The runtime never creates, alters or checks tables. Apply initial `schema.sql` and selected auth/site DDL only to an empty database. For later changes the agent diffs regenerated SQL, writes and rehearses a host-native migration on a copy, and applies it before publishing new code. Destructive/type changes require explicit data migration; Mantle drops nothing.
 
-Use the Site's native publication workflow. Configure trusted origin and verified identity there; never construct a system/admin Caller from browser input. Serving Admin also requires its separate assets and shell security contract. Scheduling and storage provisioning belong to the host.
+Use the Site's native publication workflow. Configure trusted origin and verified identity there; never construct a system/admin Caller from browser input. Serving Admin also requires its app-built assets and shell security contract. Scheduling and storage provisioning belong to the host.

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -5,13 +5,34 @@ description: Install schema explicitly, migrate before deploying, and operate a
 
 Run the same generation command with `--check`, typecheck the application and test its selected routes before deploying. Keep generated TypeScript, SQL and Wrangler edits committed; keep bundle `dist/` untracked. The app owns the database, auth secrets, trusted origin and assets.
 
+## Public fetch routing
+
+Workers use `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
+The public-fetch flag routes native `fetch` through Cloudflare's public Internet
+boundary. OAuth verification needs it to fetch JWKS on the service's own public
+hostname; CIMD also requires this boundary for client metadata. `nodejs_compat`
+alone does not establish it.
+
+`mantle generate cloudflare-*` adds these flags without replacing other flags,
+including in environments with their own `compatibility_flags` array. The same
+command with `--check` refuses missing flags without writing. JSON/JSONC configs
+are updated; TOML receives manual-edit instructions. Keep both flags in every
+TOML environment override. An explicit `global_fetch_private_origin` is preserved
+for applications without OAuth/CIMD, but conflicts with selected OAuth/CIMD auth
+and with the public-fetch flag: generation refuses that config without rewriting
+it. Such applications must use public routing for their OAuth/CIMD transport.
+
+After deployment, complete a real OAuth sign-in and use the resulting bearer
+for MCP `initialize` and `tools/list`. Local development and cookie-only Admin
+checks do not verify production public-hostname routing.
+
 ## Install and change schemas
 
 The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
 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.
 
@@ -19,6 +40,29 @@ For D1, create a migration with `pnpm exec wrangler d1 migrations create <databa
 
 For PostgreSQL, use the app's migration tool and deployment credentials. Plan lock waits and long index builds there; request credentials need no DDL privileges. Configure session settings on the role/database as described in [native execution](../guides/native-execution.md#postgresql-settings). Hyperdrive query caching must be disabled for authority and mutation visibility.
 
+## Latency placement and D1 read replication
+
+Measure these options against the application's real traffic; neither is a
+default latency guarantee. [Smart Placement](https://developers.cloudflare.com/workers/configuration/placement/)
+can move fetch execution closer to observed back-end services:
+
+```jsonc
+"placement": { "mode": "smart" }
+```
+
+For globally distributed, read-heavy D1 traffic, enable
+[read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
+on the database and pass one request-scoped `env.DB.withSession(...)` handle to
+the selected generated Views, Procedures and Store. Those D1 entry points accept
+`D1DatabaseSession`. Without the Sessions API, queries continue to use the primary.
+
+Use `first-unconstrained` only when a replica snapshot is acceptable,
+`first-primary` when the flow must start from the latest primary state, or carry
+a bookmark between logical sessions for sequential consistency. Reuse the same
+session within that logical flow; all writes still go to the primary. Keep fresh
+authentication/authorization checks and mutation/read-after-write paths on their
+required current-authority path rather than weakening them for replica latency.
+
 ## Operate
 
 Enable Workers Logs and traces in production. The top-level `observability.enabled` alone does not enable traces:

package/docs/handbook/cloudflare/media-r2.md

@@ -20,9 +20,8 @@ Each media purpose in `siteDefaults.media.purposes` lists mime **slots** and a b
 `required` entries use `<input accept>` grammar (full mime, comma list, or a subtype shorthand such as `webp`);
 `maxBytes` must cover every mime the slots allow, keyed by the full mime type.
 
-OSS applications own their R2 binding, public bucket URL and S3 credentials.
-Mantle Cloud supplies that wiring by default; the OSS package has no Cloud API
-or credential management. Import `r2MediaStorage` from `@aotter/mantle/media/r2`:
+Applications own their R2 binding, public bucket URL and S3 credentials; the SDK
+package does not manage them. Import `r2MediaStorage` from `@aotter/mantle/media/r2`:
 
 ```ts
 const storage = r2MediaStorage({

package/docs/handbook/cloudflare/service-entry.md

@@ -31,16 +31,18 @@ import { authLoader, resolveCaller } from '@aotter/mantle/auth';
 import { authRoutes } from '@aotter/mantle/auth/routes';
 import { withAuthTasks } from '@aotter/mantle/auth/hardening';
 import { checkOrigin, surfaceFailure, type Caller } from '@aotter/mantle/contracts';
-import { admin } from '@aotter/mantle-admin/server';
+import { admin, adminShell } from '@aotter/mantle-admin/server';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
 import { entries } from '@aotter/mantle-admin/server/entries';
 import { adminBindings } from '../generated/admin-bindings.js';
-import { adminAssets } from './admin-assets.js'; // app-owned SPA shell, assets and CSP
+import { mcpAppCatalogues } from '../generated/admin-descriptors.js';
 import { mcp } from '../generated/mcp.js';
 import { rest } from '../generated/rest.js';
 import { handlers } from './handlers.js'; // omit when there are no ref Procedures
 
 // Env comes from worker-configuration.d.ts: declare DB, ASSETS, the email provider binding
-// and the ORIGIN, AUTH_SECRET and ADMIN_EMAIL secrets in Wrangler.
+// and the PUBLIC_ORIGIN, BETTER_AUTH_SECRET and ADMIN_EMAIL secrets in Wrangler.
+// createAuth(env) is exported by the app's src/auth.ts (see the auth template).
 let auth: import('@aotter/mantle/auth').AuthLoader<ReturnType<typeof import('./auth.js').createAuth>> | undefined;
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
@@ -50,7 +52,7 @@ export default {
       let authority: Promise<Caller> | undefined, readAuthority: Promise<Caller> | undefined;
       const resolve = (readOnly: boolean) => resolveCaller(request, auth!, {
         readOnly,
-        audience: [`${env.ORIGIN}/mcp`, `${env.ORIGIN}/mcp/admin`],
+        audience: [`${env.PUBLIC_ORIGIN}/mcp`, `${env.PUBLIC_ORIGIN}/mcp/admin`],
         responseHeaders: headers,
       }).then(value => { checkOrigin(request, value); return value; });
       const caller = (_request?: Request, _env?: Env, classification = { readOnly: false }) =>
@@ -60,9 +62,9 @@ export default {
       const routes = [
         authRoutes(auth, { methods: [{ kind: 'email-otp' }], resolver: caller }),
         admin(bindings.metadata, bindings.views, bindings.operations, {
-          ...options, routes: entries(bindings.schemas, bindings.adapter),
+          ...options, developerViews: bindings.developerViews, routes: entries(bindings.schemas, bindings.adapter),
         }),
-        mcp(options),
+        mcp({ ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } }),
         rest(options),
       ];
       try {
@@ -74,8 +76,9 @@ export default {
           for (const cookie of headers.getSetCookie()) result.headers.append('set-cookie', cookie);
           return result;
         }
-        const asset = await adminAssets(request, env);
-        if (asset) return asset;
+        // Serves the built Admin shell for /admin and its client routes; undefined for any other path.
+        const shell = await adminShell(request, path => env.ASSETS.fetch(new Request(new URL('/admin/' + path, request.url), request)));
+        if (shell) return shell;
         // Your public frontend/web.ts routes can use an anonymous Caller without
         // loading auth; their generated SQL still controls publication visibility.
         return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
@@ -85,31 +88,45 @@ export default {
 };
 ```
 
-Remove imports and array entries for omitted surfaces. `mcp.ts` exists only when
-the manifest has an MCP surface, and requires the documented optional MCP peer.
+Keep the MCP and REST entries together for the normal symmetric path. For a deliberate
+asymmetric exception, remove the omitted surface's imports and array entry. `mcp.ts`
+exists only when the manifest has an MCP surface and requires the documented optional
+MCP peer. An application that deliberately does not mount MCP need not import generated
+`mcp.ts`; outside the entry import graph, it contributes nothing to the bundle.
 Pass the same handlers to each selected surface that exposes ref Procedures.
-Bind site/media/identity and extension capabilities through the selected Admin/MCP
+Bind site/media/identity capabilities through the selected Admin/MCP
 options; do not expose native auth administrative routes without `authRoutes` or
 `guardAuthAdminRequest`. `withAuthTasks` retains background callbacks on the
 current request's context; `authHardening` configures the background handler.
 Select `--admin` to emit `admin-bindings.ts`. Admin's API is a separate
 `@aotter/mantle-admin` package; the SDK never imports it. The API handles only
-`/admin/api`. The app-owned asset route serves the built shell for `/admin` and
-client routes, including `/admin/sign-in`, and preserves missing asset 404s.
-Allow its built import map through the exact CSP hash documented by the installed
-Admin package. Collection statistics use the generated shared `statisticsView`:
+`/admin/api`. `adminShell` (in the block above) serves the built shell for `/admin` and
+client routes, including `/admin/sign-in`; it sets `frame-ancestors 'none'`, `X-Frame-Options: DENY`, `no-store` and `nosniff`
+on the shell, answers a missing file under `/admin` with a 404 `Response`, and returns `undefined` for other paths and
+non-GET requests. The app owns the rest of the CSP and the asset cache headers.
+Collection statistics use the generated shared `statisticsView`:
 its collection parameter selects only a generated table and visibility policy.
 
 ## Workers assets and secrets
 
+`mantle generate --admin --wrangler wrangler.jsonc` sets the selected assets
+directory. A new assets block defaults to `binding: "ASSETS"`, `run_worker_first: true`
+and `html_handling: "none"`. Existing blocks keep their binding and routing; when
+`run_worker_first` is already true, a missing `html_handling` defaults to `none`.
+A different binding needs a custom Admin HTML loader. Deploy the built assets and
+Worker together.
+
 `mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`
-updates the split-build Wrangler keys. Configure the rest explicitly; JSONC
-comments and unrelated settings survive regeneration:
+updates the split-build Wrangler keys (`main` and `base_dir` under `dist/worker`),
+ensures `nodejs_compat` and defaults to `global_fetch_strictly_public` ([public fetch routing](deploy-and-operate.md#public-fetch-routing))
+and, with `--admin`, `assets.directory`: `mantle bundle` builds Admin into
+`dist/client/admin`, served at `/admin`. Configure existing assets blocks explicitly;
+JSONC comments and unrelated settings survive regeneration:
 
 ```jsonc
 {
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -119,16 +136,18 @@ comments and unrelated settings survive regeneration:
 ```
 
 `run_worker_first` lets the application supply shell/security/cache headers;
-`none` keeps `index.html` available by name. Admin assets are not a public database
+`none` keeps `index.html` available by name. `adminShell(request, assets)` passes
+paths relative to the Admin directory, so the app fetches them under `/admin/`:
+`path => env.ASSETS.fetch(new Request(new URL("/admin/" + path, request.url), request))`. Admin assets are not a public database
 API. PostgreSQL uses application-owned Hyperdrive/postgres.js wiring,
 with Hyperdrive query caching disabled for authority and mutation visibility.
 
 Commit `.dev.vars.example` containing variable names and placeholders only:
 
 ```dotenv
-ORIGIN=http://localhost:8787
+PUBLIC_ORIGIN=http://localhost:8787
 ADMIN_EMAIL=you@example.test
-AUTH_SECRET=replace-with-a-random-secret
+BETTER_AUTH_SECRET=replace-with-a-random-secret
 ```
 
 Copy it to ignored `.dev.vars`; use deployment secrets for production. Configure
@@ -137,8 +156,7 @@ an app-owned [`EmailSender`](../guides/email.md#application-wiring) and call its
 callbacks. Adapt the auth template's `MAIL.otp`/`MAIL.link` callbacks to this
 sender; it is an object, not a `.dev.vars` value. The auth
 module wires `ADMIN_EMAIL` to the bootstrap helper, which requires verified email.
-`PUBLIC_ORIGIN` can be your application variable instead of `ORIGIN`; map it
-explicitly when constructing auth and keep the trusted origin consistent.
+Name the variables as your `auth.ts` reads them (the app shell uses these three) and keep the trusted origin consistent.
 
 ## Scheduling and Bun
 
@@ -150,22 +168,42 @@ invocation; see the [TTL contract](../guides/native-execution.md#ttl-maintenance
 larger sweeps' cursors for a later invocation instead of scanning without a bound.
 
 On Bun, reuse a process-owned `Database` or `SQL` pool and call the same generated
-surfaces from `Bun.serve({fetch})`. The optional host reader is independent of
-the query target:
+surfaces from `Bun.serve({fetch})`. Bun runs the server as TypeScript, so
+`mantle bundle` builds only Admin for it: the `bun-*` target that
+`generated/.mantle-inputs.json` records skips the Worker bundle, and Admin goes
+to `dist/client/admin` (`--assets` as on Workers) when the server imports
+`@aotter/mantle-admin/server`. Add it as the build script and run it before
+starting the server:
+
+```json
+{ "scripts": { "build": "mantle bundle src/server.ts dist" } }
+```
+
+The optional host reader is independent of the query target:
 
 ```ts
 import { bunAdminAssets } from '@aotter/mantle/bun/assets';
-const assets = bunAdminAssets('node_modules/@aotter/mantle-admin/dist/admin');
+const assets = bunAdminAssets('dist/client/admin');
 const bindings = adminBindings({ handlers });
 const serveAdmin = admin(bindings.metadata, bindings.views, bindings.operations, {
   db: () => db, caller, handlers, routes: entries(bindings.schemas, bindings.adapter),
 });
-// Call assets(path) from your separate shell/static route.
+// Call assets(path) from your separate shell/static route. adminShell(request, reader) wants
+// paths without a leading slash and a Response (404 when missing), so adapt the reader:
+const reader = async (path: string) => (await assets('/' + path)) ?? new Response(null, { status: 404 });
 ```
 
 The reader returns a native `Response` or `null`, rejects traversal/control
 characters and escaping symlinks; the app owns shell, CSP and cache headers.
-Use ignored `.env` on Bun. Run cron work with your native scheduler; neither
+Use ignored `.env` on Bun.
+
+Admin's build tools and UI packages are dependencies of `@aotter/mantle-admin`,
+so a production install carries them (about 65 MB). For a container image, use a
+multi-stage build: the build stage installs everything and runs `mantle bundle`
+and `bun build src/server.ts --target bun --outdir dist/server`; the runtime stage
+copies only `dist/` (plus any files the server reads at runtime) and starts
+`bun dist/server/server.js`. Neither the Admin assets nor the bundled server read
+`node_modules` once built. Run cron work with your native scheduler; neither
 imports nor ordinary requests execute DDL, migrations or cron work. OAuth resource
 rows are inserted on first OAuth use from runtime configuration, with no deploy
 step; auth initialization and cookie/bearer/MCP/REST requests do no resource work.
@@ -190,13 +228,12 @@ untracked. Deployment uses committed generated source; it does not regenerate.
 # CI, with the project's exact installed SDK and peer versions:
 pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin --check
 pnpm exec tsc --noEmit
-pnpm exec mantle bundle src/worker.ts dist
+pnpm exec mantle bundle src/worker.ts dist   # dist/worker, and dist/client/admin with --admin
 ```
 
 `--check` regenerates in memory, lists missing/changed/obsolete SDK-owned files
 and stale Wrangler build settings, exits nonzero, and writes nothing. Unmarked
 application files are preserved. TOML generation prints manual edits, so an
-exact Wrangler `--check` requires JSON/JSONC. Use all the same `--site`, `--auth`,
-`--admin` and `--admin-extensions` options as normal generation. The check needs no database,
+exact Wrangler `--check` requires JSON/JSONC. Use all the same `--site`, `--auth` and `--admin` options as normal generation. The check needs no database,
 network access, credentials or deployment. Imported configuration modules must
 remain pure: exporting `authOptions(env)` avoids constructing Better Auth at build time.

package/docs/handbook/concepts/authorization.md

@@ -16,4 +16,4 @@ The compiler adds row policy to every Schema relation, including joins and neste
 
 Field `scope` hides rows even from admin callers; use View/Procedure [`restrict`](../reference/view.md#restrict) to limit member access while Admin collection reads see all rows allowed by the Schema's scope.
 
-The app owns custom identity and roles. Better Auth’s admin plugin `adminRoles` (default `["admin"]`) classifies comma-separated `user.role` values. `resolveCaller` carries this layer as `admin`; `isAdmin(caller)` and `hasAdminRole(caller, name)` consult it. Application-owned resolvers mint the original Caller with `userCaller` from `@aotter/mantle/user-fields`, using only a verified user and the identity provider’s adminRoles. Setting `admin: true` on a plain object grants no privilege. Member role names alone do not grant privilege. Optional [Better Auth](../cloudflare/authentication.md) helpers use fresh primary authority by default. Admin additionally requires an admin cookie session. UI visibility never replaces a server authorization check.
+The app owns custom identity and roles. Better Auth’s admin plugin `adminRoles` (default `["admin"]`) classifies comma-separated `user.role` values. `resolveCaller` carries this layer as `admin`; `isAdmin(caller)` and `hasAdminRole(caller, name)` consult it. Callers come from `resolveCaller` over Better Auth; an existing identity provider connects through Better Auth's OAuth or SSO plugins, since no public API builds a Caller from another provider's session (`authenticatedAs` in `@aotter/mantle/testing` is for tests). Setting `admin: true` on a plain object grants no privilege. Member role names alone do not grant privilege. Optional [Better Auth](../cloudflare/authentication.md) helpers use fresh primary authority by default. Admin additionally requires an admin cookie session. UI visibility never replaces a server authorization check.

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

@@ -16,3 +16,22 @@ The app owns OAuth configuration, discovery and consent; follow [OAuth](../guide
 [MCP Apps](../guides/mcp-apps.md) add static UI resources through the public contributor hook. Admin uses the same hook from its separate package. Credentials never go in App HTML. WebMCP catalogues are generated display/tool metadata for the mounted Admin product; server checks remain authoritative.
 
 See [surface contracts](../reference/surface.md) for tool schemas, challenges and scalar conversion.
+
+## When a host shows old tools
+
+A fresh `tools/list` always returns the deployed tools, but many hosts keep their own copy and do not ask again after a deploy. Mantle sends no list-changed notifications: tools change only at deploy, and the hosts that keep copies do not act on them. Instead each generated tool's description ends with its own version, and the results of a call that reaches the tool carry the deployed version, so a model holding an older definition can see it, correct its call or ask the user to refresh. Failures also state the input schema the tool is listed with now, except authorization refusals. A call naming a tool the catalogue no longer has gets the protocol's unknown-tool error, whose message gives `serverInfo.version`: unless the application sets it, a hash of every tool the endpoint serves, before per-caller filtering. Refusals before a call reaches its tool, such as authentication challenges, carry neither.
+
+In Admin, WebMCP results from the tool route carry the version, and refusals add it with the input schema, except authorization refusals; a tool removed since the page loaded is refused as not found, without a catalogue version. Admin's two navigation tools, `admin_get_context` and `admin_navigate`, carry no version: the page defines and runs them without a server call, so it cannot list one definition and run another, and a reload after a deploy replaces both. The exact shapes are in [surface contracts](../reference/surface.md#tool-versions).
+
+How each client refreshes its copy (as of 2026-10):
+
+| Client | Refresh |
+| --- | --- |
+| claude.ai connectors | A server-side copy keyed by URL, kept about an hour (users report up to 24 hours). Only adding the connector again under a new URL, such as `?v=2`, forces a refresh, and that needs authorization again. |
+| Claude Code | `/mcp` reconnect, or a new session |
+| ChatGPT developer mode | Refresh the connection, then start a new chat |
+| Published ChatGPT apps | A daily scan, or Rescan, followed by review; keep tools compatible meanwhile |
+| Cursor | Quit fully and reopen |
+| VS Code | Run "MCP: Reset Cached Tools", or restart the server |
+| Gemini CLI | `/mcp reload` |
+| MCP Inspector | The refresh button |

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

@@ -11,7 +11,7 @@ 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.
 

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/blob/develop/docs/examples/reference-service/README.md) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.