@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

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

@@ -85,21 +85,37 @@ 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. |
 | `GET /entries/{id}?collection=<schema>` | Reads an entry and its current `entry.version`. |
-| `PATCH /entries/{id}?collection=<schema>` | Body `{ data, expectedVersion }`; sends the observed version, not the next one. Publishing entries must be drafts. |
+| `PATCH /entries/{id}?collection=<schema>` | Body `{ data, expectedVersion }`; sends the observed version, not the next one. A key left out of `data` keeps its value and `null` clears it ([leave out, replace or clear](#leave-out-replace-or-clear)). Publishing entries must be drafts unless the Schema sets `publishing: { liveEdits: true }`; a [lock](../reference/schema.md#locks) that holds refuses it with 409 `kind: "lock"`. |
 | `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
-`{ id, collection, locale, status, version, data, created_at, updated_at }`.
+`{ id, collection, locale, status, version, data, created_at, updated_at }`. On a Schema with
+[locks](../reference/schema.md#locks), each entry of the editor payload and of `GET /entries` also has
+`locks: { update, delete }`: per verb, `{ lock, message }` of the first lock that holds for your generic write of that row,
+or `false`. Admin disables Save, rename, Delete and transitions on such a row and shows the
+message; the operational "Unlock editing" toggle does not override it. The write itself stays the authority: a refusal is
+409 `CONFLICT` with `kind: "lock"`. Every publishing entry has `locks` too: the draft-only rule (without `liveEdits`) and
+"unpublish before deleting" are the implicit lock `lock: "publishing"`, named only when no declared lock holds for that verb.
+It binds data writes only, so Publish, Unpublish and Archive stay available; with `liveEdits` a published entry's form is
+enabled with a "changes go live on save" notice, and Save waits until its required fields are filled.
 Transitions accept `{}` to use the current version; tests should send the
 observed `expectedVersion` to catch stale writes. Generic writes reject native
 columns inside `data`. See [publishing](../concepts/lifecycle-and-locales.md).
@@ -137,7 +153,7 @@ refused View or collection from a missing one. Showing or hiding a component gra
 | Hook | Route | Surface |
 | --- | --- | --- |
 | `useView(name, input, { limit? })` -> `{ rows, status, hasMore, loadMore, loadingMore }` | `GET /views/{name}` | browser and MCP App |
-| `useOperation(name)` -> `{ run, pending }`; success refreshes Views, entries, entry editors and totals | `POST /operations/{name}` | browser and MCP App |
+| `useOperation(name, { refresh? })` -> `{ run, pending }`; success refreshes every mounted View (each input, each loaded page), entries, entry editors, totals and badges once, `refresh` narrowing the Views ([below](#scoped-refresh)) | `POST /operations/{name}` | browser and MCP App |
 | `useEntries(collection, { filter?, search?, limit? })` -> `{ items, status, hasMore, loadMore, loadingMore }` | `GET /entries` (one `filter_field`/`filter_value`) | browser only |
 | `useEntry(collection, id)` | `GET /entries/{id}` | browser only |
 | `useCollectionTotal(collection)` | `GET /collections/{name}/statistics`, its `total` | browser only |
@@ -150,6 +166,18 @@ options) starts again from the first page. A failed `loadMore()` leaves `status`
 calling `loadMore()` again retries. Admin's own lists work the same way, under a "Load more" button, and so does the MCP App, which
 shows the button only when the host has `serverTools` (it calls the View's tool again with the same input and the `cursor`).
 
+<a id="scoped-refresh"></a>By default an operation's success reads every shown View again, since Admin cannot know which a
+Procedure changed: every mounted `useView`, for each input it is mounted with, and for each page it has loaded, one request
+per page (a View with five loaded pages makes five requests). To keep that cheap, unmount what is collapsed (a closed
+branch of a tree reads nothing, and reads again only when it is next shown), keep `limit` small so that fewer pages
+accumulate, and prefer one wider View over many narrow ones. A page with many Views (say one per expanded branch of a
+tree) can also name the ones to read again:
+`useOperation("move", { refresh: ["children", { view: "children", input: { parent: id } }] })`. A name covers every input of
+that View; `{ view, input }` covers the one `useView(view, input)` (any `limit`); `refresh: []` reads no View again. The names and inputs are typed like `useView`'s.
+Views not named are marked stale rather than read again, so each reads again when it is next shown. Entries, open entries,
+totals and badges still refresh: the Procedure may write any collection, and skipping those would show stale records with no
+way to name them. Leave `refresh` out when unsure; a View you forget to name keeps showing its old rows until it is shown again.
+
 In an MCP host, `useView` and `useOperation` call the View's or operation's admin MCP tool (its name lowercased, kebab to snake) through the host (`tools/call`),
 under the caller's MCP authorization; the browser-only hooks read `unavailable` there, so declare the data an App needs as an
 admin View. Without the host's `serverTools`, `run` is `undefined`. `useHost()` is `null` in the browser and the host's API
@@ -205,14 +233,164 @@ collection's name, `<field>` one of its fields and `<column>` a column of an adm
 | `list.actions:<schema>` | browser | `collection`, `selection` (empty in the toolbar, the selected ids in the bulk bar) |
 | `cell:<schema>.<field>` | browser | `value`, `row` (the list's columns only, `null` when empty), `property`, `surface` |
 | `cell:view:<view>.<column>` | both | `value`, `row`, `property`, `surface` |
-| `input:<schema>.<field>` | browser | `value`, `onChange`, `readOnly`, `property`, `surface` |
+| `input:<schema>.<field>` | browser | `value`, `onChange`, `readOnly`, `property`, `surface`, optional `onStatusChange`, `error`, `errorId` |
 
 `record.aside:` and `record.actions:` render beside Admin's own side cards and actions, which they do not replace. A
-record form's top-level fields go through `input:`; a View's parameters and a Procedure's inputs do not. A read-only field
-(a bound or `readOnly` property) has no `input:` component, and `readOnly` tells yours that the caller cannot edit the
-record. In the browser Admin, a View column that reads a Schema field also goes through that field's `cell:` component, with the column's own
+record form's top-level fields go through `input:`; a View's parameters and a Procedure's inputs do not. A field the Schema
+does not require is `T | null` in the generated types, and so is every field of a publishing collection, whose draft may lack a
+required one: it reads `null` when unset, and `onChange(null)` clears it (Save sends `null`, which the entry PATCH stores as
+NULL; a field left out keeps its value). The built-in controls clear the same way, and an emptied required field is `null` too:
+an operational record refuses it with a validation error, and a draft keeps it empty until Publish, which refuses it. A read-only field
+(a bound or `readOnly` property) never reaches the slot: it has no `input:` component and shows its value read-only.
+
+`readOnly` is one flag for the whole form, not for the field: it is `true` whenever this caller cannot edit this record now,
+which is when any of these holds:
+
+- the caller is not an admin, which includes the moment while `/me` is still loading, so expect it to start `true`;
+- the collection is read-only (`readOnly: true` at the root of its Schema), or the entry's version is outside the safe integer range;
+- an operational record has not been unlocked with "Unlock editing";
+- a publishing entry is not a draft: published without `publishing: { liveEdits: true }`, or archived, which stays read-only
+  even with `liveEdits`. With `liveEdits` a published entry's form is editable and `readOnly` is `false`;
+- a declared [Schema lock](../reference/schema.md#locks) holds the row for `update` (`entry.locks.update`). No toggle overrides
+  it. The form shows the lock's message, unless the collection is read-only, whose read-only hint shows instead.
+
+The built-in form wraps the fields in a `<fieldset disabled>` that also blocks the pointer. That disables native form controls
+inside it, but not a custom element that is focusable on its own (a `contenteditable`, a `tabIndex` element, a third-party
+widget's buttons): it can still take keyboard focus and call `onChange`. Honour `readOnly` in your component. The Save button
+stays disabled either way, so such a change is never sent.
+
+A custom input can report validation and uncommitted local text with the optional
+`onStatusChange({ error, dirty })` callback. Each call replaces that mounted root field's report:
+`error` is a message (or `null`), and `dirty` says the control holds unsaved text outside `onChange`.
+An error disables Save even if another field changes; a dirty local draft uses the record's existing
+navigation and `beforeunload` guard. These are independent: a valid but uncommitted draft can be dirty,
+and a validity error need not claim a change. Pass `{}` or call with no argument to clear both.
+
+Admin renders the error as an alert beside the input and passes back `error` and `errorId`.
+Connect your control with `aria-invalid` and `aria-describedby`, and respect `readOnly`:
+
+```tsx
+import * as React from "react";
+import type { InputProps } from "@aotter/mantle-admin/app";
+
+function JsonInput({ value, onChange, onStatusChange, error, errorId, readOnly }: InputProps<unknown>) {
+  const [text, setText] = React.useState(() => JSON.stringify(value));
+  return <textarea value={text} readOnly={readOnly} aria-invalid={Boolean(error)} aria-describedby={errorId}
+    onChange={event => {
+      const next = event.target.value;
+      setText(next);
+      try {
+        const parsed = JSON.parse(next);
+        onChange(parsed);
+        onStatusChange?.({}); // the form now owns the valid draft and protects it until Save
+      } catch {
+        onStatusChange?.({ error: "Enter valid JSON", dirty: true });
+      }
+    }} />;
+}
+```
+
+Do not emit invalid text through `onChange` merely to mark the form dirty. If valid text stays local
+until an explicit Apply action, keep reporting `{ dirty: true }` until Apply calls `onChange`.
+The server's generated checks remain authoritative: a parsed value the component does not validate
+can still be refused on Save, with the error above the form.
+
+Reports belong to mounted **root** `input:<schema>.<field>` slots, including an object or array as
+one structured value; there are no per-array-index input slots. A report clears when that field
+unmounts. Another record, a clean newer server version, an explicit **Load latest version**,
+or a completed Save resets the inputs and their local state. A row becoming locked/read-only
+preserves its local draft and dirty navigation protection; the reported error is hidden until it
+becomes editable again. Reports never override `readOnly` or enable Save on a locked row. A related
+re-read preserves a dirty local draft. A draft typed while Save is in flight is kept. A custom
+component that conditionally hides its own editor while its field stays mounted should clear its
+report when discarding that editor's draft. Procedure input forms do not use these record slots.
+
+At runtime the component also receives `field` and `build`, which the built-in control uses to render itself. They are internal,
+not part of `InputProps`, and may change in any release: do not read them. Pass the props you were given to `renderDefault`, as
+with every slot.
+
+In the browser Admin, a View column that reads a Schema field also goes through that field's `cell:` component, with the column's own
 `cell:view:` component outside it; the MCP App renders only `cell:view:`. The developer workspace (`/admin/dev`) is Admin's own tool and does not go through any slot. A record with folded child collections opens on a workbench at `/admin/c/<schema>/<id>`, which is not `RecordView`; the record form (and so `RecordView`, `record.aside:`, `record.actions:` and `input:`) is its `/edit` page. A `Shell` that does not call `renderDefault` has no status bar: the record form's Save and Publish bar then stays in the page.
 
+Creating a parent opens its field editor first. Save the parent fields, then use the named workspace link or the child-collection links above the form to continue in its workbench. Missing publish requirements name their fields; a read-only requirement must be set by an available operation or related record rather than typed into the form. Workspace links use the same unsaved-changes guard as other Admin navigation.
+
+While the record form has unsaved changes, leaving it asks first: Admin's own links, its in-app navigation and Back/Forward
+show a confirm dialog, and a reload, closing the tab or another site show the browser's own prompt (`beforeunload`). Save,
+"Load latest version" or confirming the leave clears it, and a `#hash` change on the same page never asks; a cancelled Back or
+Forward leaves the browser history as it was; there is nothing to configure or opt out of. Custom pages and
+operation forms have no such guard. An `input:` component's own state counts when it calls `onChange`
+or reports `onStatusChange({ dirty: true })`; unreported local state is outside the form's guard.
+
+### Media fields
+
+A string field with `x-mantle-ref: media_assets` holds the id of an asset in the media library (`media_assets`), never a
+URL. The record form renders a built-in control for it: a thumbnail of the asset, the id in a text box, **Pick**, which opens
+the library in a dialog, and **Upload**, which uploads an image and fills the id. It works at the top level and in the
+properties of nested objects, including objects inside an array:
+
+```yaml
+properties:
+  cover: { type: string, x-mantle-ref: media_assets }
+  gallery:
+    type: array
+    items:
+      type: object
+      properties:
+        image: { type: string, x-mantle-ref: media_assets }
+        caption: { type: string }
+```
+
+An array of bare ids (`items: { type: string, x-mantle-ref: media_assets }`) gets a plain text box per item; wrap the id
+in an object, as above, to get the picker. The control needs the media library mounted (`site` and `media` in `admin()`,
+see [media on R2](../cloudflare/media-r2.md)). Upload chooses a media purpose from the site's purposes by the collection
+and field names, and is disabled when the site declares none. Procedure and View input forms render the same control with
+Upload disabled, so an operation's media input is picked from the library.
+
+Only a top-level field goes through `input:`. To add to the built-in control, wrap it with `renderDefault`:
+
+```tsx
+"input:products.cover": (props) => (
+  <div>
+    {props.renderDefault(props)}
+    <p className="text-xs text-muted-foreground">Use a 1200 x 630 image; it is also the social card.</p>
+  </div>
+),
+```
+
+For a custom structured input or custom page, import the browser-only picker from the optional
+`@aotter/mantle-admin/media` entry. It runs inside `<MantleAdmin>` and uses the same caller-authorized media library and
+upload routes. Keep the picker import in the browser entry; when also building an MCP App, use a sibling
+`admin.mcp.tsx` without it ([separate entries](mcp-apps.md#customising-admin-for-mcp-hosts)). The host build rejects browser
+media routes. There is no public raw media HTTP client or upload function.
+
+```tsx
+import * as React from "react";
+import { MediaPicker } from "@aotter/mantle-admin/media";
+
+type Card = { image?: string; caption?: string };
+
+function CardImage({ value, onChange, readOnly }: { value: Card; onChange: (value: Card) => void; readOnly: boolean }) {
+  const [open, setOpen] = React.useState(false);
+  return <>
+    <button type="button" disabled={readOnly} onClick={() => setOpen(true)}>Choose image</button>
+    <MediaPicker open={open} onOpenChange={setOpen} readOnly={readOnly} uploadPurpose="post-cover"
+      onSelect={asset => onChange({ ...value, image: asset.id })} />
+  </>;
+}
+```
+
+`onSelect` receives only `{ id, primaryUrl: string | null }` after an explicit selection and closes the dialog via
+`onOpenChange(false)`. Cancel never calls `onSelect` or clears a value. The application owns the structured value and
+Save; selection only updates its local draft. Pass the input's `readOnly`, and key a reused custom input by its record
+identity so an open picker does not follow navigation to another record.
+
+`uploadPurpose` is an exact site media purpose, not an asset filter: existing assets remain selectable across purposes.
+Omit it for selection only; an unknown purpose disables upload, and the upload helper refuses unknown explicit purposes
+rather than choosing another policy. Upload uses the existing raster image variants and server permission checks.
+Uploads commit to the library independently of selection: closing, cancelling, becoming read-only or unmounting never
+selects a late upload and never deletes an already committed asset. Search stays in the dialog and preserves the page's
+draft. Applications that do not import `/media` do not load this optional component.
+
 `plugins` are fragments of `components`, applied in order: each one's `renderDefault` is the plugin before it, the first
 plugin's is the built-in component, and the application's own `components` are outermost. A plugin is
 `{ components: { ... } }`, so one can be written once and shared.
@@ -295,14 +473,18 @@ returns its one row on one page and has no cursor.
 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.
+publish checks required data. Publishing edits apply only to drafts unless the Schema sets
+`publishing: { liveEdits: true }`, which opens published (never archived) entries; a live edit of a published entry must still pass those publish checks
+(`INPUT_VALIDATION_FAILED`), keeps `published_at` and goes live on save. Read-only
+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
 interpreter. PATCH retains its visible-row read and exact OCC check; the mutation
 returns its row. Missing/excluded rows are 404; stale locks or failed state guards
-are 409. Safe versions are numbers; exact native int64 strings can be bound
+are 409 (a [lock](../reference/schema.md#locks) that holds is `kind: "lock"`). Safe versions are numbers; exact native int64 strings can be bound
 without rounding, while unsafe numbers are rejected. The console keeps versions
 outside its supported safe range read-only rather than casting them to numbers.
 Full cross-target int64 output parity remains incomplete; bare driver values
@@ -321,6 +503,24 @@ from `@aotter/mantle/media`; other custom ContractErrors must carry an explicit
 status, otherwise the boundary returns a redacted 500. Do not leak native
 error messages, tokens or credentials to clients.
 
+### Leave out, replace or clear
+
+Each write path reads a field it is given differently. Pick the one whose rule fits the edit:
+
+| Write path | Field left out | A value | `null` |
+| --- | --- | --- | --- |
+| Admin create (`POST /entries`) | unset, or the Schema's default | sets it | dropped, the same as leaving it out, so the default applies |
+| Admin patch (`PATCH /entries/{id}`, the record form's Save) | keeps the stored value | replaces it | clears it to NULL; a required operational field refuses it, and so does a live edit (`liveEdits`) of a field `publish` requires (`INPUT_VALIDATION_FAILED`) |
+| Store `update` (a ref handler's `ctx.store`) | keeps the stored value | replaces it | clears it to NULL; on a published row a field `publish` requires is refused (`INPUT_VALIDATION_FAILED`) |
+| SQL Procedure (`input.x`) | binds NULL, so `SET note = input.note` clears it | replaces it | binds NULL too, where the input's schema accepts `null` |
+| `ref` handler input | the key is absent | present | present, as `null`, where the input's schema accepts it |
+
+A SQL Procedure cannot tell a field left out from one cleared, since both bind NULL. For a partial update, keep the stored
+value with `COALESCE(input.note, note)`, and give clearing its own input, such as `clearNote: true` with
+`CASE WHEN input.clearNote THEN NULL ELSE COALESCE(input.note, note) END`
+([SQL patterns](sql-patterns.md#change-only-the-fields-given-coalesce)). A ref handler sees the difference: test with
+`Object.hasOwn(input, "note")`, and pass only the keys present to `store.collection(...).update`.
+
 ## Statistics
 
 `GET /admin/api/collections/{name}/statistics?range=7d` supports primary or
@@ -371,7 +571,17 @@ 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. In an operation bound to a row (`target`), a picker whose Schema folds under that row's collection
+(`nav.parentField`) lists only that row's children, filtered by `<parentField> = <the bound row's value>` as the folded
+child list is: `switch-revision`'s `revision` on a post lists that post's revisions. There is no way to pick another
+parent's child there: an operation that needs one binds to that other row instead, or is not bound (`collectionAction`
+or the Operations page), where the picker lists the whole target. 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
@@ -418,7 +628,10 @@ tabs. The parent is the reference named by `Schema.spec.uiSchema.nav.parentField
 the first required unique-field reference. A Schema with two or more required `id` references to
 existing Schemas (translations excluded) and no `parentField`, with or without `standalone`, is refused by `mantle generate` with `SCHEMA_UI_INVALID`; the diagnostic lists the
 candidates and the `nav: { parentField: <field> }` line that keeps the first one that is not a parent cycle. This applies to every build, with or without Admin, so a join table with two required `id` references needs it too. `parentField` is
-refused on a translation child and when its parent chain leads back to the Schema. Choosing the
+refused on a translation child and when its parent chain leads back to the Schema. An explicit
+`parentField` decides the fold direction: a required reference from that parent back to the child
+(a post's required `current_revision`) is not an inferred fold and does not count as a cycle,
+while two `parentField`s pointing at each other are still refused. Choosing the
 parent changes Admin navigation only: storage and authorization are unchanged.
 
 Set `nav.standalone: true` to put a child with a required `id` reference at the top level instead;
@@ -516,7 +729,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 +740,22 @@ 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 collection action of a folded child (one with a parent; see above) also shows in that child's panel of the parent's
+workbench. Run from there, the input named exactly like the child's `nav.parentField` (the child's field holding the
+parent's value) is filled with this parent's value and locked: the form hides it and the dialog lists it under the
+bound values, like a row operation's `id`. The name is the rule because it is unambiguous (one input at most, the same
+name as the column the action writes). The value takes the input's type (a numeric parent key binds a number); an
+input with that name whose `x-mantle-ref` names another Schema or key, or whose type cannot hold the parent's value, is
+left to the person, and so is every input outside a workbench. With `nav.parentField: post`, `new-revision { post }` placed with
+`collectionAction: post_revisions` runs on the open post.
+
+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.
@@ -45,7 +46,7 @@ transport conversion or runtime schema interpreter.
 Declared authorization, ownership/TTL SQL policy, explicit OCC and atomic writes
 remain required. Generate them as the native application would implement them.
 Transaction rollback and uncertain COMMIT handling must still preserve data-loss
-protection and client disposal responsibility; native errors are rethrown (one exception, below), and
+protection and client disposal responsibility; native errors are rethrown (with the contract exceptions below), and
 redaction before they reach HTTP users belongs to the application boundary through `wire` / `surfaceFailure`. Removing generic error
 normalization does not authorize dropping transaction outcome evidence.
 
@@ -56,12 +57,12 @@ unique `id =`), so a failed count check after autocommit has changed nothing.
 On PG it runs at the server's default isolation, not SERIALIZABLE: a concurrent
 OCC loser re-evaluates its `version =` predicate, matches zero rows and returns
 `CONFLICT` instead of SQLSTATE 40001. A server ErrorResponse (SQLSTATE and
-severity) is a known rollback and is rethrown natively, except a unique violation (23505, SQLite's `UNIQUE constraint failed`), which, in a generated Procedure or a Store write, is `ContractError("CONFLICT")` with the native error as `cause` on every target, and except connection,
+severity) is a known rollback and is rethrown natively, except a unique violation (23505, SQLite's `UNIQUE constraint failed`), which, in a generated Procedure or a Store write, is `ContractError("CONFLICT")` with the native error as `cause` on every target, and serialization/deadlock refusals (`40001` / `40P01`) with a definitive server response, which are `CONFLICT` with `kind: "serialization"` and the native `cause`, and except connection,
 resource and shutdown classes (08, 28, 53, 57, 58, XX), which, like any failure
 without a server response (lost socket), are `OUTCOME_UNKNOWN`. SQLSTATE is
 `errno` on Bun.SQL and `code` on postgres.js. Multi-statement Procedures run in
 `begin("isolation level serializable", ...)`: a failure before the callback
-returns was rolled back by `begin`; only a failed COMMIT is classified as above.
+returns was rolled back by `begin`; only a failed COMMIT is classified as above. The same serialization/deadlock mapping applies to Store batches and interactive transactions, including a definitive refusal at COMMIT. No write is retried automatically; re-read before deciding whether it still applies.
 
 **Date-time wire form:** a View output that is a declared `date-time` column
 (including `created_at`/`updated_at`) returns the handbook's wire form, an ISO
@@ -77,14 +78,15 @@ 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,
 with null representing absence; D1 cannot bind undefined. Native output keys are
 SQL names rather than a post-query camel-case projection. PG uses the driver's
 default type parsers (including Date and int8 strings); custom application parser
-configuration changes application-owned behavior. Procedures expose raw
+configuration changes application-owned behavior. The Store alone converts a row's
+`version` to a number ([typed queries](typed-queries.md)). Procedures expose raw
 `{ results }`, not a claim of validated authored output.
 
 The application resolves a verified Caller once at its entry, using its selected

package/docs/handbook/guides/public-pages.md

@@ -11,6 +11,12 @@ here instead of repeating it.
 - **App-owned pages** in `src/routes.ts`, when the page needs its own layout, JSON-LD or languages. The reference
   implementation is `node_modules/@aotter/mantle/docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
 
+## URLs
+
+Mantle owns `/admin`, `/mcp`, `/api/auth/`, `/oauth/consent` and `/.well-known/oauth-*`, and the app's HTTP Triggers own
+their declared paths. Give visitor pages their own prefix (`/{locale}/…`, `/teas/{slug}`), or make a root page (`/{slug}`)
+return nothing for those paths; the app shell already keeps `/admin` and `/mcp` away from `src/routes.ts`.
+
 ## Every public page
 
 - Server-rendered HTML per URL with the content in the body. A client-only SPA shell or metadata set by script is not
@@ -26,7 +32,9 @@ here instead of repeating it.
 
 - JSON-LD of the matching schema.org type (`Recipe`, `Article`, `Event`, `Product`, ...), built from the same row as
   the visible content: `name`, `description`, `url`, `inLanguage`, `datePublished`, `dateModified`, and `image` when
-  there is one (some rich results require it). Escape `<` in the serialized JSON so stored text cannot close the
+  there is one (some rich results require it). A type that has no date or language properties (`Product`) gets them on
+  a page node instead: an `@graph` with an `ItemPage` (`inLanguage`, dates, `mainEntity`) pointing to the `Product`
+  (`offers` with `price` and `priceCurrency`). Escape `<` in the serialized JSON so stored text cannot close the
   script element. Do not add facts the page does not show.
 - A short answer block for answer engines: one question heading and a one-sentence answer from the row's data.
 - A Markdown alternate at `<url>.md`, linked with `<link rel="alternate" type="text/markdown">`.
@@ -46,8 +54,40 @@ here instead of repeating it.
 - `/llms.txt` ([llmstxt.org](https://llmstxt.org)): a title, a one-line summary and a link to each item's Markdown
   alternate.
 
+## A complete site
+
+When the brief names a site, shop, catalogue or blog for visitors, these are part of the work without the user
+listing them:
+
+- Every item on this page, for every public page type the site has.
+- Accessible, responsive pages with the app's own styling; the examples are unstyled on purpose.
+- Content managed in Admin (draft, publish, edit, unpublish) shows on the site without a rebuild. Images go through
+  Admin's media library (`mantle help media-r2`); store committed asset IDs and never use an ID as an image URL.
+- Members' pages, if any, send anonymous visitors to `/sign-in` (`signInRedirect` in the app shell's `src/sign-in.ts`).
+- Who runs the site: an About/contact page and a footer with the business's name, location and contact, and on the
+  home page `Organization` (or `LocalBusiness`) JSON-LD with the same facts and the logo. Answer engines use these to
+  say whether the site is legitimate. Ask for the facts the brief lacks; never invent an address.
+- A favicon, and `og:image` on the home and list pages too.
+- A detail page leads to the action the brief sells (order, register, book), saying when it needs an account.
+- A cache policy: `Last-Modified` (from the row's `updated_at`) or an `ETag` on pages, `.md`, sitemap and `llms.txt`,
+  so crawlers can revalidate; `no-store` everywhere is safe but makes every crawl a full fetch.
+- Structured data and answer blocks state only what the page shows. Never promise ranking or AI citation.
+
 ## Check before you report done
 
-Request the HTML without running JavaScript and check the items above; publish, edit and unpublish an item and check
-that its page, Markdown, sitemap and `llms.txt` follow. The `mantle` skill's
-`references/local-testing.md` covers running this against `wrangler dev`.
+Request each page without running JavaScript (plain `fetch` in `smoke.mjs`; `mantle help local-testing`) and assert:
+
+1. HTML content type and the visible content; `<title>`, description, canonical on `PUBLIC_ORIGIN`, Open Graph; on
+   detail pages JSON-LD that parses with the visible name, and the answer block.
+2. Each `.md` alternate returns `text/markdown` with the current text.
+3. Walk the list View's complete cursor chain: its rows equal the `llms.txt` entries and the sitemap's detail URLs
+   (below the generated `web()` caps: 5,000 rows for `llms.txt`, 50,000 for the sitemap). `/robots.txt` names the
+   sitemap.
+4. An unknown URL, a malformed path, a draft and a row the visitor may not read are 404, also with an admin session.
+5. Publish, edit and unpublish an item through Admin's API (or the Procedure Admin uses); after each, its page,
+   `.md`, sitemap and `llms.txt` follow.
+6. Stored text with `<`, `&` and `</script>` renders escaped in HTML and inside JSON-LD.
+
+Report a check you could not run (for example a production origin you do not have) as UNVERIFIED with the reason.
+Then run [independent acceptance](agent-workflow-acceptance.md) with a visitor evaluator in a browser on the
+`pnpm accept` URL.