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

package/docs/examples/club-events/manifests/club-events.yaml

@@ -165,6 +165,13 @@ spec:
   source: { kind: http, method: POST, path: /api/registrations/cancel }
   target: { procedure: cancel-registration }
 ---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: cancel-registration }
+---
 # Officers add records through declared Procedures: operational collections have no generic create in Admin.
 # collectionAction puts the Procedure's button and input form in that collection's list header; the admin MCP
 # Trigger is what makes it an Admin operation (and lets the officers' AI do the same).

package/docs/examples/club-events/src/handlers.ts

@@ -17,7 +17,7 @@ export const handlers: Handlers = {
       return await store.procedures["register-write"]({ eventId, member: caller.subject, memberName: user?.name || user?.email || caller.subject });
     } catch (error) {
       // register-write's only Schema check is the capacity 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 === "events")
         throw new ContractError("CONFLICT", "The event is full.", "procedures/register");
       throw error;
     }

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

@@ -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/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/handbook/cloudflare/authentication.md

@@ -12,6 +12,8 @@ Mantle supplies the database adapter, schema generation and caller resolution:
 
 ## `auth.ts`
 
+> **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:
 
@@ -78,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
@@ -184,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

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

@@ -88,8 +88,11 @@ 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 capabilities through the selected Admin/MCP
 options; do not expose native auth administrative routes without `authRoutes` or
@@ -106,12 +109,19 @@ 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 (`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 the rest explicitly; JSONC
-comments and unrelated settings survive regeneration:
+`dist/client/admin`, served at `/admin`. Configure existing assets blocks explicitly;
+JSONC comments and unrelated settings survive regeneration:
 
 ```jsonc
 {

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/tree/v0.2.0-alpha.8/docs/examples/reference-service) 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.

package/docs/handbook/guides/agent-setup.md

@@ -13,21 +13,21 @@ carries.
 The Mantle plugin carries one OSS authoring skill, `mantle`, and local
 acceptance references. It does not configure a hosted-service connection.
 Install from the Git tag matching the exact SDK version you selected (currently
-`v0.2.0-alpha.8`). Alpha releases integrate on `develop`; an unqualified
+`v0.2.0-alpha.9`). Alpha releases integrate on `develop`; an unqualified
 `aotter/mantle` source follows `main` and can install older, incompatible
 instructions. A skill install does not upgrade the application's SDK.
 
 For Codex, pin the marketplace checkout:
 
 ```sh
-codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.8
+codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.9
 codex plugin add mantle@mantle
 ```
 
 For Claude Code, first clone the release into a directory you will keep:
 
 ```sh
-git clone --depth 1 --branch v0.2.0-alpha.8 https://github.com/aotter/mantle.git mantle-plugin
+git clone --depth 1 --branch v0.2.0-alpha.9 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
 Then, in Claude Code, use that checkout's absolute path:
@@ -41,7 +41,7 @@ Cursor and GitHub Copilot use their plugin manifests from the same tagged
 checkout. Without a plugin host, install only the consumer skill by name:
 
 ```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
 ```
 
 When upgrading the SDK, update the marketplace ref or local tagged checkout and

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -0,0 +1,222 @@
+# Independently accept a user-facing workflow
+
+Before reporting any user-facing deliverable as done, exercise it from the
+user's position with a fresh end-user agent. This applies to Admin pages and
+customisations, application pages and web routes, REST APIs used by clients,
+MCP tools and MCP Apps. Generation, typechecking, scripted smoke tests and an
+author's replay remain useful; they do not establish independent acceptance. A
+fresh context is not enough if the author still chooses a workflow that mirrors
+the implementation. Every acceptance round gives the evaluator responsibility
+for choosing realistic tasks and judging the result, not just following a
+prescribed sequence.
+If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
+or authorized test transport is unavailable, report `BLOCKED`; neither outcome
+is done.
+
+Use the surface the intended user actually uses: a real browser session for
+Admin and application pages; for REST, an HTTP client plus the public API
+reference and base URL a real client developer receives; an MCP client for
+tools; and the real MCP App host/AppBridge flow for Apps. This is an
+application-authoring practice, not an SDK runtime service or a new test runner.
+Use the project's existing local setup, normal authorized sign-in and isolated
+fixtures. Setup hands over the role's established browser session or client
+token; the evaluator never acquires or widens credentials. Give it only its
+authorized surface. Do not enable extra routes, roles or generic writes to make
+the exercise pass.
+
+## Audit MCP tool design before implementation
+
+Start with the original user brief, business role and explicit requirements,
+not a list of CRUD endpoints or a task derived from what you implemented.
+Before writing manifests or handlers, record the intended jobs and assumptions
+in the existing design note. Keep the author's capability map separate from
+the brief an evaluator receives: the evaluator chooses its own tasks and
+observable success criteria. Do not expand application scope or authority
+merely to satisfy an evaluator's newly inferred product wish.
+
+In the application's existing design note or issue, map each goal step to its
+proposed public capability: discovery inputs, returned IDs and evidence, allowed
+caller, write/transaction boundary and recovery. Mark missing capabilities or
+unresolved contracts as gaps before writing manifests or handlers. Review the
+following rubric against that map:
+
+| Design question | Required contract or explicit gap |
+| --- | --- |
+| Can the agent locate the right record? | Bounded search/filter inputs, stable IDs, deterministic cursor paging and sensible limits. It must not scan every list or guess an ID from a display label. |
+| Can it choose an eligible relation? | Finding an ID is not proof of business eligibility: verify the role, state and ownership required by the relationship. Return enough labels to distinguish same-name choices before writing. |
+| Can it correct an ordinary mistake? | State how to amend, clear or replace optional fields and relations, and how duplicate records are detected or reconciled. Test omitted, null and empty inputs against that contract; existence and type checks alone do not establish business validity. Express conditional-required inputs with the supported [input rules](../reference/surface.md) before writing handler checks. |
+| Can it read a complete business result? | ID-based detail/readback under the intended caller, including every relation the goal creates or changes. A parent list is not proof of its child/contact/state details. Distinguish absent/inaccessible from incomplete evidence. |
+| Can it verify a create or update? | Return the backend entity ID, actual committed version where applicable, and a safe result summary or a documented authorized readback. State the exact result nesting. Echoed input or the submitted `expectedVersion` is not proof of committed state. Specify PATCH versus full replacement and omitted/null-field semantics so an update cannot erase unseen fields. |
+| What does a version protect? | Name its entity/snapshot scope; a parent version does not imply child rows or aggregates are unchanged. Use the reviewed observed version for OCC, define conflict behavior and preserve the user's proposed changes without silently rebinding/retrying. |
+| Can it complete a business transition? | Name permitted source/destination states, preconditions, related effects and final readback. Prefer an outcome-oriented operation when arbitrary field updates would leave the workflow unfinished. |
+| What commits together? | Define the native Procedure/Store atomic boundary. Separate tool calls are independent; describe partial success and deliberate compensation. Do not imply that an agent can roll back earlier calls or that compensation is always possible. |
+| Can it interpret refusal and failure? | Document success and structured diagnostic/error envelopes, including MCP `isError`; HTTP 200 or a wrapper's transport success is insufficient. Inspect raw MCP diagnostics separately from host-visible wrapper errors; a wrapper label alone does not locate a runtime defect or require global error normalization. Missing relations, stale versions and denied callers need meaningful refusals without leaking another caller's records or native internals. |
+| What happens after a duplicate or uncertain write? | State whether idempotency exists, its key/scope/lifetime when supported, or that repeated successful calls may repeat effects. Provide an authorized reconciliation route for timeout/unknown outcomes; never automatically retry an uncertain write. |
+| Can it explain amounts correctly? | Declare currency, stored/wire units, exact-value representation, rounding and whether null means unknown. Label every ratio's numerator and denominator: cost/budget, sales/budget and gross/sales are different measures. |
+| Does data remain usable without an App? | Keep ordinary reads data-only; attach a renderer deliberately for interactive inspection, with structured/text fallback. Rendering must not write or imply approval. Host catalog refresh, OAuth and real client/UI behavior have separate acceptance; descriptions cannot force generative UI layout. |
+| Does every step respect the user's authority? | Verify least privilege, tenant/owner scope, allowed fields, relation access and negative cases on the server. Tool visibility, annotations, descriptions and UI confirmation never grant permission. Use authorized disposable fixtures and a cleanup owner without widening production writes/deletes. |
+
+A design passes this audit only when each required goal step has a supported
+capability and verifiable output/recovery; preserve unresolved gaps and owners.
+The audit is a design review, not execution evidence. Record intentional
+exclusions, but keep an unmet explicit user requirement unresolved until the
+user changes its scope; do not redefine it as optional to make a round pass.
+Reuse the installed version's Views,
+Procedures, Store and surface contracts; a missing business tool is not by
+itself an SDK runtime defect.
+
+For simple creates/partial updates, prefer a declared Store-backed `ref`
+Procedure: await the caller-bound Store write, return a safe allowlist with its
+actual returned ID/version, and keep `requires` plus generated input validation
+at invocation. A transaction-bound write result remains provisional until the
+outer transaction commits; publish success only after that boundary completes. Store row policy alone is not Procedure authorization. Define
+omitted versus null patch semantics; never fill unseen fields with defaults.
+Keep SQL Procedures for atomic stock changes, conditional state transitions and
+related writes. A TypeScript pre-read does not replace an atomic WHERE/CHECK;
+D1 supports batch, not an interactive transaction or consuming an earlier batch
+result. See the [Store write guide](typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).
+
+Then implement the minimum contract and run generated/type, authorization,
+atomicity and other relevant regressions. Follow the independent acceptance
+rounds below before claiming the user-facing work is done. Keep the author's
+capability map and worked call sequence out of the fresh agent's prompt: an MCP
+evaluator must discover the workflow from public tool descriptions and results.
+
+## Run independent acceptance rounds until they converge
+
+1. **Freeze scope and revision, not the evaluator's itinerary.** Supply the
+   original user brief, business role, explicit requirements and exclusions,
+   exact application/SDK revision, authorized transport, permitted fake-data
+   actions, per-round interaction/time/write budgets, a user-set total round cap of at
+   least three (default four) and a fixture cleanup owner. Seed fixtures with
+   realistic volume and variety: other owners' records, several states and more
+   than one page of results, so evaluators' own goals reach discovery, paging
+   and authority. Explicitly authorize synthetic writes only where the user has
+   authorized testing. Production writes and external side effects need their
+   own authorization.
+2. **Use a new end-user subagent in every round.** Start without inherited
+   implementation history. Withhold source, SQL, internal docs, capability maps,
+   precomputed IDs, hidden routes or tool names, prescribed interaction order
+   and previous reports or fixes. Ask
+   the agent to state its own realistic goals and observable success criteria
+   before execution, use or discover the user-facing surface and assess whether
+   it supports the work. Ask whether it can make the decisions needed for its
+   goals, not merely issue successful calls. Do not prescribe the author's
+   happy path or require a minimum number of defects. Zero findings is a valid
+   observation. Run the evaluator outside the project directory, without Mantle
+   skills or project instruction files, with only the intended browser, HTTP
+   client, MCP client or MCP App host/AppBridge available, and record that
+   isolation in the evidence. For a multi-role workflow, run one
+   fresh agent per role in the same round on shared live data in the brief's
+   natural order; the later role finds earlier records through the service, and
+   the first agent may take a resumed turn to observe the outcome. Each agent
+   still chooses its own goals.
+3. **Keep evidence and scope judgments.** Require PASS/FAIL/BLOCKED per chosen
+   goal, actual readbacks, rejected writes, recovery, interaction costs and
+   design findings with materiality, evidence and the smallest suggested repair.
+   Separate a violated explicit requirement, a demonstrated defect and a newly
+   inferred product need. Missing capability is a finding, not permission to
+   invent interfaces or automatically expand the product. A rendered page,
+   HTTP 200, successful tool result or creation ID alone does not prove a
+   complete business result. Preserve setup assistance
+   and label any coached attempt; do not count it as a clean independent round.
+4. **Repair outside the evaluator's context.** The author retains the full
+   findings ledger, classifies application design, SDK/runtime, docs, transport
+   setup and host issues separately, then makes the smallest in-scope repair.
+   Turn reproduced failures into focused regression checks and run them with
+   relevant authorization, OCC and atomicity checks. Keep native guards; do not
+   shim away errors or retry uncertain writes. A runtime change needs a minimal
+   supported-contract reproduction. Record optional product suggestions and
+   unresolved scope questions rather than silently dropping findings.
+5. **Repeat the whole evaluation with a fresh agent.** Freeze the new revision
+   and supply the same original brief and authority, with new fixtures. Let
+   this evaluator choose its own goals again; do not pass the ledger or steer
+   it toward the previous repair. Replaying a known failure remains an author's
+   regression check and does not replace independent design evaluation.
+6. **Judge convergence across rounds.** Converge only after two consecutive
+   unassisted fresh rounds on the same revision with no new material in-scope
+   finding and no unresolved material defect. A finding is material when it
+   violates an explicit requirement, makes an evaluator's goal FAIL or BLOCKED,
+   or exposes an authority, data-integrity or uncertain-write defect; record
+   why any finding was judged non-material. Every repair creates a new revision
+   and resets the streak, so hold non-material repairs until after the verdict.
+   Each explicit requirement observable from the evaluator's role needs
+   evaluator-observed evidence; requirements outside that role's view (another
+   caller's isolation or hidden state) are verified by author regressions and
+   reported under that label. A role-observable requirement no evaluator reached
+   is UNVERIFIED and blocks CONVERGED. If fresh evaluators never reach a required
+   path, vary the fixtures, not the brief or the steps, or report that path as
+   UNVERIFIED. Repeated success on one narrow path cannot establish broader
+   readiness. Keep optional wishes, non-material suggestions and external
+   BLOCKED gates visible; no finding count proves absence of defects. When the
+   round cap or an external blocker stops the loop, report NOT CONVERGED or
+   BLOCKED with the remaining work, not acceptance. Setup cleans isolated
+   fixtures in `finally` after every round, including failed/aborted rounds.
+
+If a fresh agent or authorized test transport is unavailable, record independent
+acceptance as BLOCKED and report the scripted checks separately. Do not invent
+an independent result. Do not deploy or publish merely to obtain acceptance.
+
+## Give the agent a role and the user's brief
+
+Fill in a brief like this using the actual user's request and authorized
+scope. Do not replace it with a sequence tailored to existing tools:
+
+> You are a [business role] working in [business context]. The user requested:
+> [original brief, explicit requirements and exclusions]. You are authorized
+> to test with fictional data through [user-facing surface and entry point]
+> within [allowed actions and interaction/time/write budgets]; [owner] will clean up
+> the fixtures.
+> Independently define realistic acceptance goals and observable success
+> criteria before testing. Use or discover the supplied interface and assess
+> whether it lets you make the decisions your goals require, not merely perform
+> successful interactions. Report per-goal PASS/FAIL/BLOCKED with readback
+> evidence, design shortcomings, interaction costs and minimal improvements.
+> Distinguish failures within the requested scope from newly inferred product
+> needs; do not invent unsupported interfaces or change the product. Do not inspect
+> source, internal docs or a database, blindly retry uncertain writes, or act
+> outside the supplied authority. Finding no defects is acceptable; report
+> what you actually covered and what remains unverified.
+
+The author separately verifies isolation between callers, stale-version
+refusal, unknown-outcome handling and effects hidden from the evaluator's role
+through authorized test fixtures. Do not grant the evaluator extra authority
+just to observe hidden state. Keep author regressions distinct from what the
+fresh agent actually observed.
+
+## Record evidence in the existing issue or handoff
+
+Use ordinary Markdown; no new receipt schema or framework is required:
+
+- Original brief, explicit requirements and exclusions, role, environment,
+  per-round budgets and round cap.
+- Setup assistance and what each agent could access; identify distinct rounds.
+- Per round: revision, the evaluator's own goals and criteria, per-goal
+  PASS/FAIL/BLOCKED, actual readbacks and interaction references,
+  request/page/tool counts
+  and negative/recovery attempts, with their differing scope stated.
+- Findings ledger with materiality, owner, disposition, minimal repair and
+  regression commands/results.
+- Streak and reset history; coverage of each explicit requirement
+  (evaluator-observed, author regression only, or UNVERIFIED); the final
+  CONVERGED / NOT CONVERGED / BLOCKED / UNVERIFIED verdict and rounds used. Retain every
+  failed report.
+- Fixture cleanup result and every remaining limitation.
+
+Keep credentials, raw auth logs, full resource HTML and private operational
+details local/private; publish only sanitized contract evidence. Do not claim a
+call-cost improvement when rounds exercise different negative/discovery cases.
+Version fields usually describe an entity row, not all related aggregates;
+state money units and the denominator of any budget or margin calculation.
+
+## Keep surface evidence distinct
+
+Evidence from one surface does not prove another. Tool metadata and protocol
+discovery do not prove that an MCP App rendered in its real host through
+AppBridge; a REST response does not prove the Admin or application page; and a
+browser rendering does not prove an external client can use the REST contract.
+Record the actual browser, client or host version, identity, observed interface
+and behavior for the deliverable under acceptance. Keep data results available
+without Apps; descriptions cannot force a host's generative UI layout. Local
+cookie-session acceptance, OAuth client integration and long-term renewal
+likewise require their own evidence when they are part of the requested work.

package/docs/handbook/guides/mcp-apps.md

@@ -107,6 +107,82 @@ An explicit `uri` keeps application-owned identity. A custom `html` function mus
 supply a build-specific `uri`: Core cannot infer its build or safely memoize its
 request-dependent output. A raw `html` string may use the automatic identity.
 
+### Keep old conversations working after an upgrade
+
+A new URI does not invalidate a host's saved tool definitions or old conversation
+cards. Keep previously deployed pages with `adminMcpApps({ catalogue, previous })`.
+`previous` is an array of `AdminMcpSnapshot` from `@aotter/mantle-admin/mcp`:
+`{ uri, html, csp?, domain?, title? }`. Each `html` includes the original `mantle-catalog`
+script (the page returned by `resources/read`, not the raw bundle). The SDK serves
+its original HTML and metadata at its original URI, filters its catalogue against
+the current caller's tools on every read, and gives only the current build renderer
+ownership. A removed/denied tool gains no authority through an old page.
+
+Store these snapshots in the application's source or durable artifact storage;
+an isolate cache or untracked `dist/` is insufficient for a clean CI deployment.
+Keep an explicit retention window. Old pages outside that window and incompatible
+tool renames/input/output changes need an application migration. Never answer an
+old digest with the latest HTML. Host metadata refresh is a development/recovery
+operation, not a normal compatible-upgrade requirement.
+
+For the default built loader, share the exact declaration in
+`src/mcp-app-definition.ts` (no `html` or `previous`):
+
+```ts
+import { mcpAppCatalogues } from '../generated/admin-descriptors.ts';
+export const appDefinition = { catalogue: mcpAppCatalogues.admin };
+```
+
+Keep a committed `mcp-app-previous.json` at the project root (initially `[]`). Load
+it only inside the service's MCP branch, before constructing the handler, so other
+routes do not parse archived full-page HTML at startup:
+
+```ts
+const { default: previous } = await import('../mcp-app-previous.json', { with: { type: 'json' } });
+serveMcpHandler ??= serveMcp(tools, { ...options, apps: {
+  admin: adminMcpApps({ ...appDefinition, previous }),
+} });
+```
+
+Keep custom `renders`, catalogue extensions, `domain` and `title` in the shared
+definition too. Node 22.18+ can read these generated `.ts` modules; a TypeScript
+app using `.ts` import paths enables `allowImportingTsExtensions` with `noEmit`.
+Keep snapshots outside the directory containing `admin.tsx`: Tailwind scans that
+directory, and compiled HTML/JavaScript inside a snapshot can be mistaken for
+utility class names and change subsequent CSS builds.
+
+After a successful deployment, archive the **exact asset just deployed** with
+this application-owned `scripts/archive-mcp-app.mjs`, then commit the snapshot
+for the next build. Run it in the deployment script, not as a manual cache fix:
+
+```js
+import { readFileSync, writeFileSync } from 'node:fs';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
+import { appDefinition } from '../src/mcp-app-definition.ts';
+
+const path = 'mcp-app-previous.json';
+const previous = JSON.parse(readFileSync(path, 'utf8'));
+const context = { env: {}, request: new Request('https://archive.invalid/mcp') };
+const source = adminMcpApps({ ...appDefinition,
+  html: readFileSync('dist/client/admin/mcp-app.html', 'utf8') });
+const { resources: [resource] } = typeof source === 'function' ? await source(context) : source;
+const tools = new Set([...Object.keys(appDefinition.catalogue.views),
+  ...Object.keys(appDefinition.catalogue.actions)]);
+const loaded = typeof resource.html === 'string' ? resource.html
+  : await resource.html({ ...context, tools });
+const page = typeof loaded === 'string' ? { html: loaded } : loaded;
+const snapshot = { uri: resource.uri, title: resource.title, ...page,
+  ...(resource.domain === undefined ? {} : { domain: resource.domain }) };
+// This application's policy: retain the last two deployed pages for future builds.
+writeFileSync(path, JSON.stringify([...previous.filter(p => p.uri !== snapshot.uri), snapshot].slice(-2)) + '\n');
+```
+
+This archives static UI/catalogue metadata, never rows, cookies or OAuth tokens.
+Custom loaders must archive their actual immutable resource, including CSP/domain,
+instead of using this default-asset recipe. Compare the archived URI with deployed
+`tools/list`/`resources/read`; a mismatching declaration or stale local build is
+not deployment evidence.
+
 Core accepts static contributors or async `(context: { env, request }) => McpApps`
 sources, including mixed arrays. Static declarations are checked at construction;
 async sources resolve after the endpoint's origin and caller gates, then their
@@ -133,6 +209,8 @@ authorization, caller, origin and database behavior.
 
 ## The Admin App in a host
 
+> **Verification status:** automated AppBridge coverage exists, but the compatibility claims in this section have not yet been verified manually in real ChatGPT or Claude hosts.
+
 The Admin App speaks MCP Apps `2026-01-26` to the host and asks only for what
 the host advertises in `hostCapabilities`:
 
@@ -175,7 +253,6 @@ full screen, a row action, and a link. Check too that the host advertises
 `hostCapabilities.serverTools`; without it the App is read-only. The automated interoperability test
 uses the official `AppBridge`; your app runs its generated version ([Run the compatibility test](#run-the-compatibility-test)).
 
-
 ## Customising Admin for MCP hosts
 
 `mantle bundle` builds the Admin MCP App from the same entry as the browser Admin

package/docs/handbook/guides/native-admin.md

@@ -344,6 +344,10 @@ The API advertises capabilities for actually mounted routes, including statistic
 
 ## Acceptance
 
+Before reporting Admin pages or customisations as done, follow the [independent
+acceptance guide](agent-workflow-acceptance.md) with a fresh evaluator in the
+real Admin browser session.
+
 Use a disposable database for native tests, then exercise actual OTP sign-in,
 the Admin console and member frontend. Check invalid input, another tenant's
 rows, expired rows, publishing transitions, related/translated entries, paging,