@aotter/mantle 0.2.0-alpha.9 → 0.2.0

package/docs/examples/purchasing/smoke.mjs

@@ -171,6 +171,20 @@ try {
     assert.deepEqual(received.map(order => order.reference), [laptop, projector]);
     assert.deepEqual(await statusAndOrder(projector), { status: "ordered", supplierOrderId: "SUP-2" });
     step("daily cron retries the failed supplier order (system caller) and emails every admin about requests pending more than 3 days, and only those");
+
+    const small = await call("POST", "/api/requests", { cookie: bob, body: { title: "Pens", amount: 50, department: "Engineering" } });
+    assert.equal(small.status, 200, JSON.stringify(small.body));
+    const pens = small.body.results[0][0];
+    assert.equal(pens.requestStatus, "approved");
+    const spent = await remaining("Engineering");
+    assert.deepEqual((await ledgerRows()).filter(r => r.requestId === pens.id), [{ requestId: pens.id, amount: 50, remainingAfter: spent }]);
+    await query(`UPDATE budgets SET remaining = 20 WHERE department = 'Design'`);
+    const ledgerBefore = (await ledgerRows()).length, requestsBefore = (await query("SELECT count(*) AS n FROM requests"))[0].n;
+    assert.equal((await call("POST", "/api/requests", { cookie: alice, body: { title: "Tape", amount: 30, department: "Design" } })).status, 409);
+    assert.equal(await remaining("Design"), 20);
+    assert.equal((await ledgerRows()).length, ledgerBefore);
+    assert.equal((await query("SELECT count(*) AS n FROM requests"))[0].n, requestsBefore);
+    step("CASE approves a request of 100 or less at submission: the status, the budget and the ledger row commit together, and one that would overspend is refused with nothing written");
   }, { vars: { EMPLOYEE_DOMAIN: "example.test", SUPPLIER_API_URL: `http://127.0.0.1:${supplier.address().port}/orders`, SUPPLIER_WEBHOOK_SECRET: SECRET } });
 } finally {
   supplier.close();

package/docs/examples/recipes/README.md

@@ -25,11 +25,13 @@ Search for `AGENT:` for what an app must still provide: layout and styling, cach
 - Need members to see or edit only their own rows? Add club-events' `restrict: { recipes: "author_id = auth.uid()" }` on a View.
 - Need review before publishing, or an AI that approves? Add purchasing's guarded status transitions and admin MCP.
 
-## Copy
+## Run it
+
+This runs the example by itself, to read and try. For your own app, run `mantle init` and take only the patterns you need into its manifests and `src/` (`mantle help examples`).
 
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/   # run the example as is
 cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
 ```
 

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

@@ -81,6 +81,9 @@ export default {
         if (shell) return shell;
         // Your public frontend/web.ts routes can use an anonymous Caller without
         // loading auth; their generated SQL still controls publication visibility.
+        // Mounted here, after every Mantle surface, a root catch-all page (/:slug)
+        // cannot shadow /admin, /mcp or REST. Mount them earlier only behind a
+        // guard that skips those paths, as the app shell does.
         return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
       } catch (error) { return surfaceFailure(error); }
     });

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.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.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0/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,20 @@ 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.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.
+`v0.2.0`). Pin the tag to keep instructions aligned with the application's
+SDK. 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.9
+codex plugin marketplace add aotter/mantle --ref v0.2.0
 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.9 https://github.com/aotter/mantle.git mantle-plugin
+git clone --depth 1 --branch v0.2.0 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
 Then, in Claude Code, use that checkout's absolute path:
@@ -41,7 +40,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.9 --skill mantle
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0 --skill mantle
 ```
 
 When upgrading the SDK, update the marketplace ref or local tagged checkout and
@@ -54,10 +53,16 @@ project and copies no handbook.
 
 ## 2. Install the SDK, then read its own docs
 
-Use the version the project already pins. For a new project, choose a 0.2.x
-version with `npm view @aotter/mantle dist-tags` and install it with an exact
-version; every `@aotter/mantle*` package stays at that same version. Then
-read, from the application:
+Use the version the project already pins. For a new project, install stable
+0.2.0 exactly:
+
+```sh
+pnpm add --save-exact @aotter/mantle@0.2.0
+```
+
+Add optional `@aotter/mantle-ui@0.2.0` and `@aotter/mantle-admin@0.2.0` only
+when the selected surfaces need them. Every selected `@aotter/mantle*` package
+stays at the same exact version. Read, from the application:
 
 ```text
 node_modules/@aotter/mantle/README.md

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

@@ -6,9 +6,9 @@ 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.
+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.
@@ -29,8 +29,8 @@ the exercise pass.
 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
+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.
 
@@ -82,101 +82,111 @@ 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.
+## 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.
 
-## 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.
+## 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
@@ -188,19 +198,19 @@ fresh agent actually observed.
 
 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.
+- 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, the evaluator's own goals and criteria, per-goal
+- 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 materiality, owner, disposition, minimal repair and
+- Findings ledger with P0–P3, 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.
+- 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

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/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
@@ -371,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
@@ -516,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
@@ -527,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,