@aotter/mantle 0.2.0-alpha.8 → 0.2.0

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.

package/docs/handbook/guides/local-testing.md

@@ -0,0 +1,40 @@
+---
+description: Scripted local checks before acceptance - handlers over real HTTP, public pages without JavaScript, MCP discovery, Admin's MCP App, and how to account for every surface.
+---
+# Local HTTP checks
+
+`pnpm check` proves that the manifests compile and the app typechecks; it runs no handler. Before you report an app
+or a feature ready, run it on a fresh local D1 and drive it over HTTP. In an app written by `mantle init`, that is
+`smoke.mjs` on the shell's `smoke-kit.mjs` (`pnpm smoke`): it applies `generated/schema.sql` and `seed.sql`, starts
+`wrangler dev --local`, signs users in with the console email code and deletes everything afterwards.
+These checks are the author's evidence. [Independent acceptance](agent-workflow-acceptance.md) comes after them and
+does not replace them, nor they it.
+
+## What smoke covers
+
+- **Every Procedure and HTTP Trigger the app declares:** valid input with the expected status and body (a status
+  below 500 is not success), invalid input, an anonymous call to a protected operation, the other role, and the
+  stored result read back. Use only the generated routes, inputs and permissions.
+- **Business rules at their edges:** the oversell, the stale `expectedVersion`, the second approval, a refusal that
+  must leave nothing behind (check the rows with the kit's `sql`), and two concurrent calls where a race matters.
+- **Each caller sees only its own rows:** a second member's records are absent from lists and refused by id.
+- **Visitor pages:** the checks in [public pages](public-pages.md#check-before-you-report-done), requested without
+  JavaScript.
+- **MCP:** `assertMcpDiscovery(endpoint, { tools, headers })` from `smoke-kit.mjs` for `/mcp` and `/mcp/admin`, with
+  the expected tools taken from generated code (the app-shell README shows it), plus a separate assertion that an
+  anonymous call and a member calling `/mcp/admin` are refused. Discovery needs no business `tools/call`.
+- **Admin:** `pnpm build`, then `pnpm test` (`generated/admin-mcp-app.check.mjs`) loads the Admin MCP App in an MCP
+  host and fails on a network error, console error or exception. It needs `playwright-core` and Chrome
+  (`npx playwright-core install chromium`, or `MANTLE_TEST_CHROMIUM=<executable>`). With no browser it fails: report
+  it as BLOCKED, not skipped.
+
+Better Auth allows 3 one-time-code requests per minute per client IP; the kit gives each user its own
+`cf-connecting-ip`. Credentials come only from the kit's sign-in: a check never scrapes another session or builds a
+Caller by hand.
+
+## Account for every surface
+
+In the app's README or handoff, list each declared surface (Admin, each MCP endpoint, REST, each visitor page type)
+as verified (command, identity and result), intentionally not exposed, or UNVERIFIED with a reason. Local cookie
+sessions do not prove an external MCP host's OAuth connection or a production origin; record those separately.
+Record the commands and their results for the exact commit, fix failures and rerun the affected checks.

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

@@ -85,6 +85,9 @@ All paths below start with `/admin/api` and require an admin session; mutations
 also require the shared same-origin check. Mount `entries(...)` for collection
 routes. Send JSON with `Content-Type: application/json`.
 
+These routes serve Admin's console with its session cookie; they are not a client API. A REST client reads back what it
+wrote through the app's own Views with HTTP Triggers (`mantle help trigger`).
+
 | Method and path | Request / response |
 | --- | --- |
 | `POST /entries` | Body `{ collection, data }`; creates an entry. |
@@ -92,10 +95,15 @@ routes. Send JSON with `Content-Type: application/json`.
 | `PATCH /entries/{id}?collection=<schema>` | Body `{ data, expectedVersion }`; sends the observed version, not the next one. Publishing entries must be drafts. |
 | `POST /entries/{id}/publish?collection=<schema>` | Body `{ expectedVersion }`; validates required data before publishing. |
 | `POST /entries/{id}/unpublish?collection=<schema>` | Body `{ expectedVersion }`; returns the entry to draft. |
-| `POST /operations/{name}` | Body is the Procedure's input; runs an Admin operation (a Procedure with `requires: ctx.admin` or a `target`). |
+| `POST /operations/{name}` | Body is the Procedure's input; runs an Admin operation (a Procedure with `requires: ctx.admin` or a `target`). Returns `{ ok: true, output }`, where `output` is what REST and MCP return (`{ results }` for a SQL Procedure). |
 | `GET /views/{name}` | Generated admin View query parameters plus `limit`/`cursor`; returns `{ rows, nextCursor? }`. |
 | `GET /view-batch?names=a,b` | One to 20 comma-separated admin View names, deduplicated; reads the first row of each as the caller, with the single route's checks (`requires`, scope, TTL, `authorize`), and returns `{ views: { <name>: { rows } \| { unavailable: true } \| { error: true } } }`. A refused View and a missing one are the same `{ unavailable: true }`; a View that cannot answer with no input is `{ error: true }`. Neither fails the batch. Empty or more than 20 names is a 400, before the database is acquired. |
 | `GET /me` | Returns `{ userId, role, admin, login, image }` for the signed-in caller. |
+| `GET /admin` | Administrators and pending invitations, plus `adminRoles` (mounted with `identity`). |
+| `GET /members?search=&limit=&cursor=&direction=` | Pages members (1–100), searching id, name and email. |
+| `PATCH /admin/{id}/role` | Body `{ role }`: an admin role name grants Admin, `null` removes it. You cannot change your own role. |
+| `POST /admin/invitations` | Body `{ email, role }`; invites an administrator by email. Returns `{ ok, userId, emailSent }`. |
+| `DELETE /admin/invitations/{id}` | Revokes an invitation nobody has signed in to yet (otherwise 409). |
 
 Entry create/read/patch/transitions return
 `{ collection, entry, parentEntryId, parentEntryTitle, related }`; the entry has
@@ -296,7 +304,9 @@ Generated full/partial input checks validate creates, edits, operations and
 filters. Plain titled string `oneOf` choices use the same enum checks; general
 or constrained alternatives remain refused. Draft creates can be incomplete;
 publish checks required data. Publishing edits apply only to drafts. Read-only
-collections refuse generic edits while their declared Procedures can still run.
+collections refuse generic creates, edits, deletes and transitions with 403 `AUTH_DENIED`
+("This record is read-only; use its operations.") before any read or write, while
+their declared Procedures can still run.
 
 Writes use compiler-printed native Procedure frames, bind recipes and only the
 supplied field fragments. They do not update omitted columns or run a schema
@@ -344,6 +354,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,
@@ -367,7 +381,12 @@ field and stored value. The server resolves them for the caller with one page qu
 target. A missing, deleted or unreadable target is absent, so the three look the same: Admin shows the exact ID with copy.
 A resolved title links to the related record. Admin Views and the MCP App have no such step, since their rows come from the
 View itself; a View that wants a title selects it (join the referenced table, within its own `requires`). `/bootstrap?collection=...` can include
-the first requested list page. CSV exports use `/entries/export` and
+the first requested list page.
+In the entry editor and every operation form (including a `collectionAction` create), a string field with
+`x-mantle-ref` to another Admin collection is a searchable picker: it lists the target through the same `/entries` route
+(20 records per search, read as the caller), shows each record's title and stores the referenced value (`id`, or the
+ref's unique field). A target the caller cannot list (403/404) or that is not an Admin collection keeps the plain text
+input. The picker is a convenience; the server still validates the value. CSV exports use `/entries/export` and
 `/views/{name}/export`; native browser downloads stream paged server output.
 A failure after headers aborts the stream, so a download can fail after partial
 bytes have arrived. Existing databases need an app-owned migration for the
@@ -512,7 +531,7 @@ placement on a Schema without a sidebar entry of its own: a translation, or a fo
 [`standalone`](#collection-navigation-and-operation-placement).
 The purchasing example (`node_modules/@aotter/mantle/docs/examples/purchasing/`) puts its approval queue and requests in an Approvals group.
 
-Operational collections have no generic create or draft: officers add records through a Procedure placed with `collectionAction` (the list header shows its button and input form), so every write is a declared, validated program. For a user-field scoped Schema, SQL INSERT is system-only, so that Procedure is a ref handler that inserts through `ctx.store` ([procedure.md](../reference/procedure.md)).
+Operational collections have no generic create or draft: officers add records through a Procedure placed with `collectionAction` (the list header shows its button and input form), so every write is a declared, validated program. For a user-field scoped Schema the Procedure can stay SQL; see [field scope](../reference/schema.md#field-scope) for the partition input.
 
 Admin operations are Procedures exposed by an admin MCP Trigger. Declare
 `Procedure.spec.uiSchema.collectionAction: <schema-name>` to show the operation
@@ -523,9 +542,13 @@ Names such as `approve` never determine placement. An operation without a row
 target or collection action appears on the Operations page, whose sidebar link
 appears whenever such operations exist.
 
+A record's page shows its row operations as labeled buttons in the header (more than three: two buttons and a
+"More actions" menu); list rows keep them in an "Actions for …" menu.
 Generated row metadata includes simple AND-ed equality/IN literal conditions
-from the target-row UPDATE/DELETE WHERE. The menu hides known mismatches; missing
-preview values and unsupported predicates leave actions available. These are
+from the target-row UPDATE/DELETE WHERE, and an operation whose conditions the
+row does not meet is hidden: with `WHERE … AND orderStatus = 'approved'`, "Mark
+fulfilled" appears only once the order is approved. Missing preview values and
+unsupported predicates leave actions available. These are
 presentation hints: the Procedure still enforces its WHERE and authorization.
 Conflicts show a localized refresh message with the technical diagnostic in
 Details. Successful actions show a short summary and changes, with raw output

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

@@ -25,8 +25,8 @@ query. Authored output names should be emitted into SQL where valid, avoiding
 an extra per-row projection merely to repair names already known at generation.
 
 Selected REST/MCP/Admin boundaries use static generated column lineage. Declared
-integers (including aliased system versions) are `number | string | null` on every
-target: safe integers become numbers; unsafe integers remain exact decimal text.
+integers (including aliased system versions) are `number | string` on every
+target, `| null` unless the View proves the column NOT NULL ([nullability](../reference/view.md#results-and-paging)): safe integers become numbers; unsafe integers remain exact decimal text.
 Selected SQL projections cast integers and hidden integer cursor keys to text
 before the driver reads them, preserving stored int64 values on SQLite/D1 and
 PostgreSQL. Values already rounded when written
@@ -34,7 +34,8 @@ PostgreSQL. Values already rounded when written
 `views/<name>.ts` exports both driver-native `Row` and `WireRow` (declared wire fields agree across targets);
 `paged/views/<name>.ts` keeps native `Row` rows; REST/MCP use separate
 `paged/wire/views/<name>.ts` SQL and convert at their boundary. SQLite/D1 declared JSON
-and boolean columns become JSON values and booleans, preserving aliases and nulls;
+and boolean columns, and computed outputs that are JSON documents by construction
+(JSON aggregates and builders), become JSON values and booleans, preserving aliases and nulls;
 PostgreSQL already returns those native values.
 Declared real/float outputs remain numbers. Computed outputs without proved lineage,
 SQL Procedures and app-owned ref results retain native values and types.
@@ -77,7 +78,7 @@ microseconds and days while PostgreSQL receives the canonical text. Computed val
 PostgreSQL through Bun.SQL that is a `Date`, which drops microseconds. Other
 declared scalars are driver-native.
 
-Driver-ready JSON parameters are text on every target (a JavaScript array would otherwise be bound as a PostgreSQL array), so the application serializes them. Bare PG SQL declares each JSON parameter as text
+JSON parameters are text on every target (a JavaScript array would otherwise be bound as a PostgreSQL array): an input field read as JSON takes its authored array or object, which the generated query serializes, and a string is bound as it is. Bare PG SQL declares each JSON parameter as text
 (`CAST(CAST($n AS text) AS jsonb)`), so Bun.SQL sends the text verbatim instead of
 JSON-encoding it again; generation refuses a JSON parameter used any other way. SQLite bool/date/timestamp/numeric parameters use their declared
 storage representations. Bound optional fields become explicit required values,

package/docs/handbook/guides/oauth.md

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