@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.10

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

@@ -1,140 +1,117 @@
----
-description: What Admin serves in 0.2.0, how manifests and uiSchema become Admin's collections, reports and operations, and how to verify a change.
----
 # Customize Admin from manifests
 
-`createAdminSurface` serves Admin's API at `/admin/api/*` behind a staff gate.
-Every route reads and writes through `runtime.store.as(caller)` and
-`invokeProcedure`, so Admin sees exactly what the signed-in staff member may
-see. What Admin shows is derived from the compiled plan: labels, forms, list
-columns, reports and operations are manifest edits.
-
-With feature `admin`, the generated preset also serves the console, the
-prebuilt SPA in `@aotter/mantle-ui/admin`, at `/admin`: `wrangler.jsonc` binds
-`node_modules/@aotter/mantle-ui/dist/admin` as the Worker's `ASSETS`
-(`run_worker_first`), and `src/service.ts` passes `createAdminSurface` an
-`assets` function that reads from it. `mantle generate` warns when `admin` is
-selected and `wrangler.jsonc` binds no `ASSETS`. The Bun preset reads the
-same files with `bunAdminAssets` from `@aotter/mantle/bun`. Sign in at
-`/admin/sign-in`.
-
-## Manifest to Admin
-
-| You want | Author this | Effect and limits |
-|---|---|---|
-| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` (a string or a locale map) | Labels and help. Stored names do not change |
-| Required fields and option lists | JSON Schema `required`, `enum`, `type` | Data contracts, checked on every write, not styling |
-| Option labels | a string property's `oneOf: [{ const: open, title: { en: Open, zh-TW: 處理中 } }, …]` instead of `enum` | Selects, filter tabs and list cells show the `title` |
-| A multiline string | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | `textarea` is the only explicit widget |
-| Markdown or HTML | property `x-mcp-hint: markdown` or `html` | A rich editor |
-| A timestamp, a date or money | `format: date-time`, `format: date`; `x-mcp-hint: money-minor` on an integer | Date controls; money in minor units, with a sibling `currency` when present |
-| Columns of an operational list | Schema `uiSchema.list.primaryField`, `.columns` | `primaryField` is a scalar data field; `columns` may name native columns (`createdAt`, `updatedAt`) |
-| Business-state tabs | Schema `uiSchema.list.filterField` | Operational Schemas only; a string enum that leads an index |
-| Search | Schema `searchableFields` | Full-text search over those string fields, plus `id` |
-| Related records | a required property with `x-mantle-ref` | Children fold under their parent |
-| A folded child in navigation too | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Its own list with a parent filter |
-| A read-only report with CSV | a View with `surface: staff`, `title`, `uiSchema.list` | `columns`, `searchFields` and `filterFields` name the View's outputs; the search box and filters become `LIKE` and `=` on them. `GET /admin/api/views/<name>/export` returns every matching row |
-| An operation | a Procedure bound by a Trigger with `source: { kind: mcp, surface: staff }` | Listed at `/admin/api/operations` for staff its `requires` admits, and run with `POST /admin/api/operations/<name>` |
-| A row operation | that Procedure's `target` (declared or inferred from `WHERE id = … AND version = …`) | Bound to the row's `id`, and its version when the target names one |
-| A list-level operation | Procedure `uiSchema.collectionAction: <schema>` | Shown on that collection |
-| No generic edits | Schema root `schema.readOnly: true` | Admin's entry routes refuse writes (`CONFLICT`); declared Procedures still run |
-
-Schema list presentation (`primaryField`, `columns`, `filterField`) is for
-`lifecycle: operational`. Publishing Schemas keep the draft, publish and
-archive workflow (`POST /admin/api/entries/{id}/publish` and `/unpublish`).
-
-## Example: an operational inbox
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: support-tickets }
-spec:
-  title: { en: Support tickets, zh-TW: 客服工單 }
-  lifecycle: operational
-  indexes: [[ticketState]]
-  searchableFields: [subject, details]
-  uiSchema:
-    fields:
-      details: { widget: textarea }
-    list:
-      primaryField: subject
-      columns: [ticketState, createdAt]
-      filterField: ticketState
-  schema:
-    type: object
-    additionalProperties: false
-    required: [subject, ticketState]
-    properties:
-      subject: { type: string, title: Subject }
-      details: { type: string, description: Include the steps to reproduce. }
-      ticketState: { type: string, enum: [open, waiting, closed] }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: support-report }
-spec:
-  title: Support report
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  uiSchema:
-    list:
-      columns: [subject, ticketState, created_at]
-      searchFields: [subject]
-      filterFields: [ticketState]
-  sql: SELECT id, subject, ticketState, created_at FROM "support-tickets" ORDER BY created_at DESC
+Select `--admin` and mount [native Admin](native-admin.md) from `@aotter/mantle-admin`. The app serves its assets and owns authentication. UI and SDK are separate packages.
+
+Schema `uiSchema` selects fields, widgets, list columns, enum tabs and child navigation. The compiler derives sortable fields from indexed required/non-null fields; it emits selected system/statistics indexes in initial DDL. Apply those indexes through an explicit migration on existing databases.
+
+Admin Views provide custom read lists; their SELECT outputs, column lineage and `uiSchema.list` define display/search/filter metadata. Procedures and MCP admin Triggers define operations with declared authorization, input checks and optional row targets. A hidden button never authorizes an operation.
+
+Generic publishing edits apply to drafts; publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
+
+Use [`defineAdmin` components](native-admin.md#customising-admin) for app-owned cells, inputs, record asides and actions; server work is a Procedure, a View or an application route. Keep exact conflict/uncertain-outcome handling in the shared UI controller.
+
+## Theme
+
+Admin is themed with CSS variables. Import your own stylesheet from `src/admin.tsx` (`import "./admin.css"`) and override the public tokens on `:root` for light and on `.dark` for dark:
+
+```css
+:root {
+  --primary: #0f766e;
+  --primary-foreground: #ffffff;
+  --radius: 0.5rem;
+}
+.dark {
+  --primary: #2dd4bf;
+  --primary-foreground: #042f2e;
+}
+```
+
+Admin marks the active theme as both the `.dark` class and `data-theme="dark"` (or `"light"`) on the root. Dark tokens and Tailwind's `dark:` variant apply when either is present, so `[data-theme="dark"] {}` is equivalent to `.dark {}`. Your overrides apply in the browser Admin and, because the entry imports your CSS, in the [MCP App](mcp-apps.md#theme) too, where the host's neutral colours are laid over them.
+
+| Token | Meaning |
+| --- | --- |
+| `--background` | Page background |
+| `--foreground` | Default text |
+| `--card` | Card and panel surface |
+| `--card-foreground` | Text on a card |
+| `--popover` | Menu, popover and dialog surface |
+| `--popover-foreground` | Text on a popover |
+| `--primary` | Brand color: primary buttons, active states |
+| `--primary-foreground` | Text on `--primary` |
+| `--secondary` | Secondary button surface |
+| `--secondary-foreground` | Text on `--secondary` |
+| `--muted` | Subtle surface: table stripes, disabled areas |
+| `--muted-foreground` | Secondary text |
+| `--accent` | Hover and selected surface |
+| `--accent-foreground` | Text on `--accent` |
+| `--destructive` | Destructive actions and errors |
+| `--border` | Borders and dividers |
+| `--input` | Form control borders |
+| `--ring` | Focus ring |
+| `--radius` | Base corner radius; the other radii derive from it |
+| `--success` | Success status color |
+| `--warning` | Warning status color |
+| `--info` | Informational status color |
+| `--chart-1` | Chart series 1 |
+| `--chart-2` | Chart series 2 |
+| `--chart-3` | Chart series 3 |
+| `--chart-4` | Chart series 4 |
+| `--chart-5` | Chart series 5 |
+| `--sidebar` | Sidebar surface |
+| `--sidebar-foreground` | Sidebar text |
+| `--sidebar-primary` | Sidebar active item |
+| `--sidebar-primary-foreground` | Text on `--sidebar-primary` |
+| `--sidebar-accent` | Sidebar hover surface |
+| `--sidebar-accent-foreground` | Text on `--sidebar-accent` |
+| `--sidebar-border` | Sidebar borders |
+| `--sidebar-ring` | Sidebar focus ring |
+| `--app-base` | Solid color behind the page |
+| `--app-background` | Page backdrop (any CSS background, such as a gradient) |
+
+Every other variable, including `--mantle-blue-*` and `--chrome-glass`, is internal and may change without notice.
+
+## Eject a component
+
+`@aotter/mantle-admin` ships a [shadcn registry](https://ui.shadcn.com/docs/registry) of starting-point components for the `defineAdmin` slots. Ejecting copies one into your source: you own that file and edit it freely, while the hooks it calls (`@aotter/mantle-admin/hooks`) and the slot prop types (`@aotter/mantle-admin/app`) keep upgrading with the package. The registry is inside the installed package, so the copy matches the version you run and no registry host is involved (the shadcn CLI itself downloads from npm and needs network). Install from the package, in the app's root:
+
+```bash
+npx shadcn@4 add ./node_modules/@aotter/mantle-admin/dist/registry/admin-cell.json
+```
+
+The file lands in `src/admin/<item>.tsx` (the item's `target` ignores aliases). The CLI needs a `tsconfig.json` and a `components.json` in the app's root; this minimal one works, because no alias or stylesheet is used:
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": { "config": "", "css": "", "baseColor": "neutral", "cssVariables": true },
+  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
+}
+```
+
+The CLI removes a comment above a file's first import, so each item keeps its header below the imports. Import it in `src/admin.tsx` and name the slot, replacing the sample collection, field, View and operation with your own:
+
+```tsx
+import { AdminCell } from "./admin/admin-cell";
+
+export default defineAdmin(admin, { components: { "cell:requests.status": AdminCell } });
 ```
 
-Schema `uiSchema.list` and View `uiSchema.list` are different contracts; do
-not copy keys between them. The report's search box matches `subject`
-(`LIKE`), its filter is `ticketState` (`=`), and a declared `input` would add
-a form above them; all of them keep cursor paging.
-
-## Developer console
-
-The Developer console's Procedure overview projects the sealed SQL AST into
-a static execution diagram: authorization, validated input, guard, applicable
-lifecycle hooks, ordered atomic statements, commit or rollback, and output
-validation. Statement cards show read/write dependencies, row versus set
-semantics, RETURNING and ordered CASE assignments. CASE chooses a field value;
-WHERE filters rows. A set operation can affect zero rows and still continue.
-Output validation and after-hook failures do not roll back an existing commit.
-Unsupported expression shapes remain explicitly opaque beside authored SQL;
-code handlers' effects and actual run history are not inferred.
-
-The inline business flow uses Schema/property titles and titled enum options
-from the developer snapshot; generic verbs and operators are UI translations.
-It expands direct `UPDATE SET field = CASE … END` assignments only. CASE
-inside arithmetic, casts, functions, SELECT or INSERT remains in the SQL
-detail tree, rather than pretending its intermediate result is the assigned
-value. SQL identifiers match manifest names case-insensitively. The existing
-`money-minor` display convention uses hundredths and a single-valued sibling
-`currency` enum; if numeric conversion or currency formatting would round a
-threshold, the flow shows its exact SQL literal marked as a raw SQL value.
-These display hints do not establish or validate business units.
-
-## Roles
-
-Admin's gate admits any staff role. Inside it, each route names the least role
-it needs: `contributor` reads and edits drafts, `editor` publishes, deletes
-and manages media, `owner` manages staff, site settings and the developer
-console. Operations and staff Views are further limited by their own
-`requires`.
-
-## Verify a change
-
-1. Run `mantle generate`, then `mantle generate --check`.
-2. Restart `wrangler dev` (or the Bun process) so the runtime loads the new plan.
-3. Open `/admin` with a staff session and check the affected list, form,
-   report or operation. `GET /admin/api/bootstrap` carries the collections,
-   Views, operations and site the console renders.
-
-`uiSchema` keys are closed. Schema takes `fields`, `list` and `nav`;
-Procedure takes `collectionAction` and `fields`; a staff View takes `list`. No
-layout, CSS, component or permission keys exist; build those in your own UI
-over Admin's API or your own surfaces.
-
-## Source
-
-- [Schema](../reference/schema.md#uischema), [View](../reference/view.md) and [Procedure](../reference/procedure.md) references
-- [HTTP, MCP, CLI and packages](../reference/surface.md): every Admin route
+| Item | Slots | Surface |
+| --- | --- | --- |
+| `admin-cell` | `cell:view:<view>.<column>` | both (also reusable as a browser collection cell) |
+| `admin-input` | `input:<schema>.<field>` | browser |
+| `admin-record-actions` | `record.actions:<schema>` (runs an operation with `useOperation`) | browser |
+| `admin-record-aside` | `record.aside:<schema>` (lists a View's rows with `useView`) | browser |
+| `admin-sidebar` | `Sidebar` (`renderDefault` with a footer link) | browser |
+| `admin-home` | `Home` (`renderDefault` under a section that reads a View) | browser |
+
+Each file starts with a comment naming its surface and rules, and imports only `react`, `@aotter/mantle-admin/app` and `@aotter/mantle-admin/hooks`. A `both` component also renders in the Admin MCP App, inside a host's sandboxed iframe, so keep it to these rules:
+
+- Read data only through `useView` and `useOperation`; `useEntries`, `useEntry`, `useCollectionTotal`, `useMe` and `useBadges` read `unavailable` there. Declare what a card needs as an admin View.
+- Link only with `<AdminLink>` or `useOpenLink()`; never `window.open` or `target="_blank"`.
+- No `fetch`, no `document.cookie` or `localStorage` authentication, no remote origin that the host's CSP does not allow, and no assumed width.
+- Where `useOperation` returns no `run` (a host without server tools), show the control disabled with a note rather than throwing or vanishing.
+- Branch on `useAdminSurface()` (or the `surface` prop) if you must, and render something sensible in both branches.

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

@@ -10,28 +10,45 @@ carries.
 
 ## 1. Install the `mantle` skill
 
-The Mantle plugin carries one skill, `mantle`, its helper script, and the
-Mantle Cloud MCP connection (`https://cloud.mantle.tools/mcp`).
+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.10`). 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.
 
-```bash
-# Claude Code: two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
+For Codex, pin the marketplace checkout:
 
-# Codex
-codex plugin marketplace add aotter/mantle
+```sh
+codex plugin marketplace add aotter/mantle --ref v0.2.0-alpha.10
 codex plugin add mantle@mantle
 ```
 
-Cursor and GitHub Copilot read the plugin manifests from the repository.
-Without a plugin host, install the skill alone:
+For Claude Code, first clone the release into a directory you will keep:
+
+```sh
+git clone --depth 1 --branch v0.2.0-alpha.10 https://github.com/aotter/mantle.git mantle-plugin
+```
+
+Then, in Claude Code, use that checkout's absolute path:
+
+```text
+/plugin marketplace add /absolute/path/to/mantle-plugin
+/plugin install mantle@mantle
+```
+
+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 aotter/mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.10 --skill mantle
 ```
 
-A skill-only install has no Cloud MCP connection; add one by hand if you need
-it. Either way, read the path the installer prints (for project-local Codex,
+When upgrading the SDK, update the marketplace ref or local tagged checkout and
+refresh/reinstall the plugin using the host's native workflow. Verify the loaded
+manifest version and skill source. Do not reset a checkout containing local edits.
+
+Read the path the installer prints (for project-local Codex,
 `.agents/skills/mantle/SKILL.md`). The skill installs no SDK, creates no
 project and copies no handbook.
 
@@ -65,18 +82,6 @@ An agent reads these files from `node_modules` when the task calls for them.
 
 ## 3. Verify the application
 
-Installing instructions proves only that they were copied. Prove the service:
-
-1. `mantle generate` and `mantle generate --check` exit 0.
-2. The project typechecks against `.mantle/generated/mantle.ts`.
-3. `wrangler dev` (or, on Bun, `bun src/index.ts`) starts, and the routes you depend on answer: a REST View, an
-   HTTP Trigger, `/mcp` `tools/list`, and with identity `mantle` a sign-in and
-   `GET /admin/api/me`.
+Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again. Test actual routes and persisted state. With selected Admin, mount `entries(bindings.schemas, bindings.adapter)` and serve assets separately. Verify member/admin OTP, row visibility and OCC. Installing a skill proves none of these flows.
 
-| Symptom | Cause and next step |
-|---|---|
-| `docs/...` is missing after installing the skill | The skill carries no docs. Install the SDK and read `node_modules/@aotter/mantle/docs/`. |
-| `mantle` is not found | Install `@aotter/mantle` locally and run it through the package manager (`pnpm exec mantle`). |
-| `mantle skills` is unknown | It is 0.1.x. Follow the installed 0.2.x docs. |
-| A v1 manifest or a `version: 1` config fails | The project is on 0.1.x. Follow `docs/upgrade-0.1-to-0.2.md`. |
-| A documented feature is missing | The installed version is older than the docs you read. Read its own docs, or upgrade deliberately. |
+If packaged docs are missing, reinstall the SDK version pinned by the app. If a feature differs from an online page, read the installed docs rather than assuming compatibility.

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

@@ -0,0 +1,232 @@
+# 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 only a
+role and the entry points that role uses; it derives realistic tasks itself
+and the author scores them against a private rubric.
+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. The capability map feeds the private rubric
+(below); an evaluator receives only its role and 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 role-only acceptance rounds until they converge
+
+The evaluator gets a role, not a task list. It works out what that role needs
+to get done from the interface itself; what it derives, and what it misses, is
+the evidence.
+
+1. **Write a private rubric first.** From the original brief, the author lists
+   what each role must be able to do on each surface (Admin, application
+   pages, REST, MCP), with observable success criteria, explicit exclusions
+   and the authority each role must not have. The rubric stays with the author;
+   no evaluator ever sees it, its wording or its order.
+2. **Hand each evaluator only its role.** Supply the business role and context
+   in one or two sentences, the entry points that role really uses (Admin URL,
+   site URL, REST base URL and API reference, MCP endpoint), a signed-in browser
+   session or client token from setup, the interaction/time/write budget,
+   permitted fake-data actions and what is forbidden (source, SQL, internal
+   docs, the database, other roles' credentials, blind retries of uncertain
+   writes). Withhold the brief's requirement list, capability maps, tool names,
+   precomputed IDs and earlier reports. Seed realistic fixtures: other owners'
+   records, several states and more than one page of results. Run the evaluator
+   outside the project directory, without Mantle skills or project instruction
+   files, and record that isolation.
+3. **Let it derive the work, then do it.** Before any interaction the evaluator
+   writes down what this role would need to accomplish and how it would know
+   each one succeeded. It then refines that list as it discovers the interface
+   (at least once after a first look, again after its first attempts), executes
+   it, and reports PASS/FAIL/BLOCKED per goal with readbacks, rejected writes,
+   recovery attempts and interaction counts. Zero findings is a valid result.
+4. **One fresh agent per role, every surface.** For the default two roles, run
+   an `admin` evaluator and a `user` evaluator in the same round on shared live
+   data, in the brief's natural order. Between them they cover every surface
+   the app exposes to each role: Admin for `admin`, pages for visitors and
+   members, REST for client developers, MCP for both roles' AI clients. A
+   surface no evaluator reached stays UNVERIFIED.
+5. **Score against the rubric outside the evaluator.** The author compares the
+   evaluator's derived goals and results with the rubric. A rubric item the
+   evaluator never thought of is itself a finding: the interface did not make
+   that job discoverable. Classify every finding P0 (data loss, authority or
+   integrity defect, uncertain write), P1 (a rubric item FAIL, BLOCKED or not
+   discoverable), P2 (friction) or P3 (suggestion), with evidence and the
+   smallest repair. Separate a violated explicit requirement, a demonstrated
+   defect and a newly inferred product wish; a wish is not permission to grow
+   the product.
+6. **Repair outside the evaluator's context, then start over.** The author keeps
+   the findings ledger, makes the smallest in-scope repair, adds focused
+   regressions (authorization, OCC, atomicity), and freezes a new revision.
+   The next round uses new agents and new fixtures and passes them nothing
+   from earlier rounds.
+7. **Converge or stop.** A round converges when it has no P0 or P1 and the
+   evaluators' observed results cover every rubric item visible to their roles;
+   items outside any role's view (another caller's isolation, hidden state)
+   need author regressions, reported under that label. Run at most three
+   rounds. If the third still has a P0 or P1 or an uncovered rubric item, report
+   BLOCKED with the remaining ledger, not acceptance. Setup cleans fixtures in
+   `finally` after every round, including aborted ones.
+
+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.
+
+## Hand each role to its evaluator
+
+Setup signs each role in; the evaluator receives the role's access, never a credential it could reuse or widen.
+This is the authorized test transport the BLOCKED rule above refers to.
+
+- **Local session URL (the app shell's default).** `pnpm accept` in an app written by `mantle init` starts the app
+  on a fresh local D1, signs the admin in, runs an optional fixtures module, signs the user in and prints one local
+  URL per role. Each URL forwards every request with that role's session and refuses `/api/auth/*`. Give the
+  evaluator only its URL: MCP at `<url>/mcp` (user) or `<url>/mcp/admin` (admin) for any streamable HTTP MCP client,
+  Admin at `<url>/admin` and member pages at `<url>/` in a browser, REST at `<url>/` with no credential. An evaluator
+  without an MCP client uses `node accept.mjs mcp <endpoint> [tool [json]]`, which prints the raw result including
+  `isError`. The app README's "Independent acceptance" section shows the fixtures module.
+- **An external MCP host over OAuth.** To accept the connection a real client uses (Claude, ChatGPT or another host
+  that supports MCP OAuth), deploy or tunnel the app as you would for that host, add `<origin>/mcp` or
+  `<origin>/mcp/admin` to the host in setup, and complete sign-in and consent as the role's fictional identity. The
+  evaluator then works in that already-connected host. Its token stays in the host; the evaluator neither sees nor
+  requests it. Record this as OAuth evidence, separate from the local session URL (see
+  [OAuth](oauth.md)).
+
+Either way, the evaluator's prompt names the URL or the connected host, never a cookie, token or sign-in step.
+
+If you cannot start a fresh agent yourself (for example, you are a subagent without that tool), prepare everything
+else: the rubric, the fixtures module, `pnpm accept` running, and one filled-in role prompt per role (below) naming
+its URL. Hand the prompts to whoever can start agents (the person or the orchestrating agent), keep the app running,
+and report acceptance as BLOCKED with the prompts attached until their reports come back. Score those reports as
+usual.
+
+## Give the agent a role
+
+Fill this in per role. It names the role and the doors, never the jobs:
+
+> You are [role, for example "a purchasing manager"] at [business context in
+> one sentence]. You use [entry points for this role from `pnpm accept`: Admin
+> URL, site URL, REST base URL and reference, MCP endpoint]; setup has already
+> signed you in as [fictional identity]. Budget: [interactions/time/writes]. You may create and
+> change fictional records; [owner] cleans up. Do not read source, internal docs
+> or a database, use anyone else's access, or retry a write whose outcome you
+> do not know.
+> First, write down what someone in this role needs to get done with this
+> service and how you would tell each one worked. Refine that list after a
+> first look at the interface and again after your first attempts. Then do the
+> work and report each goal as PASS/FAIL/BLOCKED with what you read back,
+> what was refused, what it cost you, and the smallest change that would have
+> helped. Report what you covered and what you could not reach; finding nothing
+> wrong is acceptable.
+
+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, the private rubric, roles, environment, per-round budgets
+  and round cap.
+- Setup assistance and what each agent could access; identify distinct rounds.
+- Per round: revision, each evaluator's derived goals (first list and
+  refinements) and criteria, the gaps between them and the rubric, 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 P0–P3, owner, disposition, minimal repair and
+  regression commands/results.
+- Coverage of each rubric item (evaluator-observed, author regression only, or
+  UNVERIFIED); the final 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.