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

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

@@ -9,7 +9,7 @@ There are three packages, pinned to matching versions:
 | Package | Owns |
 | --- | --- |
 | `@aotter/mantle` | One native Core SDK: compiler, generator, query kernel and optional auth/surface primitives. |
-| `@aotter/mantle-admin` | Optional Admin server, SPA, extensions, design preview and Admin MCP App. |
+| `@aotter/mantle-admin` | Optional Admin server, the library an application builds its Admin SPA and MCP App from, design preview and `adminMcpApps`. |
 | `@aotter/mantle-ui` | Shared UI kit and generic interaction controller. |
 
 The SDK does not import Admin or its assets. Selecting Admin emits application
@@ -26,7 +26,7 @@ pnpm exec tsc --noEmit
 
 Targets are `bun-sqlite`, `bun-postgres`, `cloudflare-d1` and
 `cloudflare-postgres`. Programmatic generation accepts `admin: true` with the
-same target/source options. Optional `--auth`, `--site` and `--admin-extensions`
+same target/source options. Optional `--auth` and `--site`
 modules follow their [generation contracts](../cloudflare/service-entry.md).
 Generate, typecheck, implement every printed `Handlers` key, then typecheck
 again. Commit generated TypeScript, SQL and Wrangler edits. Never edit the
@@ -66,18 +66,19 @@ Do not manufacture an admin/system Caller from request input. Views and operatio
 also retain their own generated `requires` checks. Share one request-local
 resolver with auth, consent, MCP and REST; preserve its response cookie headers.
 
-The API handles `/admin/api/*`. The app separately serves
-`@aotter/mantle-admin/admin/index.html` and its directory at `/admin`, including
+The API handles `/admin/api/*`. The app separately serves the Admin that
+`mantle bundle` builds into `<assets>/admin` (default `dist/client/admin`, on Workers
+and on Bun, where it builds only Admin) at `/admin`, including
 client routes such as `/admin/sign-in`; missing assets stay 404. Do not serve
 that directory bare: `adminShell(request, assets)` from
 `@aotter/mantle-admin/server` returns the shell for every `/admin` page with
 `frame-ancestors 'none'`, `X-Frame-Options: DENY`, `no-store` and `nosniff`, and
-refuses traversal, encoded separators and NUL (`assets` fetches one built file
-by path; a 404 means missing; it returns `undefined` for other requests). Read the
-installed Admin README for asset bindings, CSP/import-map hashes and preview
-framing. `@aotter/mantle-ui` continues to supply the shared kit. See
+refuses traversal, encoded separators and control characters (`assets` fetches one built file
+by its path within that directory; a 404 means missing; it returns `undefined` for other requests). `@aotter/mantle-ui` continues to supply the shared kit. See
 [service composition](../cloudflare/service-entry.md) for the complete Fetch/Bun wiring.
 
+Browser pages: a collection at `/admin/c/<schema>`, an admin View at `/admin/views/<view>` (its input as query parameters), a custom page at `/admin/p/<path>`.
+
 ## HTTP routes
 
 All paths below start with `/admin/api` and require an admin session; mutations
@@ -93,6 +94,7 @@ routes. Send JSON with `Content-Type: application/json`.
 | `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`). |
 | `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. |
 
 Entry create/read/patch/transitions return
@@ -102,6 +104,164 @@ 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).
 
+## Typed data hooks
+
+`--admin` emits `generated/admin-client.ts`: the type of each admin View's input and row, of each collection's entry
+`data` (declared field names, no scope field; every field optional for a `publishing` collection, as a draft is only partly
+validated), and of each admin operation's input and output, and the hooks bound to those types. A View's row has the column
+names the browser route gives it (declared case, where the SQL output name is lowercased). An entry such as `src/admin.tsx`
+passes `admin`, which lists those renames, to `defineAdmin(admin)` so that an MCP App's rows match, and its components read
+data through the hooks:
+
+```tsx
+import { useOperation, useView } from "../generated/admin-client.js";
+
+function Queue() {
+  const { rows, status, hasMore, loadMore, loadingMore } = useView("pending-requests", {});   // names, input and rows are checked by tsc
+  const approve = useOperation("approve");
+  if (status === "unavailable") return null;
+  return (
+    <>
+      {rows.map(row => <button key={String(row.id)} onClick={() => approve.run?.({ id: String(row.id) })}>{row.title}</button>)}
+      {hasMore ? <button disabled={loadingMore} onClick={loadMore}>Load more</button> : null}
+    </>
+  );
+}
+```
+
+The hooks read only the routes above, with the Admin session cookie and Admin's own query cache, so every route still checks
+the caller, `requires`, scope and TTL; a hook has no caller, role or system argument. A 403 and a 404 both read as
+`status: "unavailable"` (an operation's `run` rejects with `AdminUnavailableError`), so the front end cannot tell a
+refused View or collection from a missing one. Showing or hiding a component grants or denies nothing.
+
+| 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 |
+| `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 |
+| `useMe()` | `GET /me` | browser only |
+| `useBadges(refs)` -> one `{ count, status }` per `{ view, field }`, in order; [freshness below](#sidebar-badges) | `GET /view-batch` | browser only |
+
+`useView` and `useEntries` accumulate: `rows` (`items`) holds every page loaded so far, in order, and `loadMore()` fetches the next
+page and appends it while `hasMore` is true. There are no page numbers and no "previous page"; changing the input (or the
+options) starts again from the first page. A failed `loadMore()` leaves `status` at `error` with the rows already loaded kept, and
+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`).
+
+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
+(context, capabilities, `openLink`, `sendMessage`, `updateModelContext`, `requestDisplayMode`) in a host; `useAdminSurface()`
+says which. `@aotter/mantle-admin/hooks` also exports the same hooks untyped, for code without generated types.
+
+`@aotter/mantle-admin/app` and `/hooks`, and so `generated/admin-client.ts`, which imports them, run in the browser only:
+`mantle bundle` refuses them in the Worker's startup graph.
+
+## Customising Admin
+
+An application replaces or wraps regions of Admin from `src/admin.tsx`. The entry passes the generated metadata and, beside it,
+what to change; the built-in entry needs none of this.
+
+If browser-only integrations need APIs that an MCP host forbids, keep their implementations outside the host graph: add a sibling `src/admin.mcp.tsx`, also default-exporting `defineAdmin(...)`, and share the host-safe config and components between the two entries. `mantle bundle` selects it automatically for the MCP asset; the SPA and preview still use `admin.tsx`. The direct build API accepts `mcpEntry`. See [isolate browser-only integrations](mcp-apps.md#isolate-browser-only-integrations).
+
+```tsx
+import { defineAdmin } from "@aotter/mantle-admin/app";
+import { admin } from "../generated/admin-client.js";
+
+export default defineAdmin(admin, {
+  pages: [{ path: "budget", title: "Budget", element: <BudgetPage />, nav: { group: "reports" } }],
+  components: {
+    // wrap: the built-in page below your own section
+    Home: (props) => <><MyQueue />{props.renderDefault(props)}</>,
+    // change a prop: the sidebar with a footer
+    Sidebar: (props) => props.renderDefault({ ...props, footer: <HelpLink /> }),
+    // replace: one value in the requests list, and the control of one field in its record form
+    "cell:requests.amount": ({ value }) => <Money cents={value} />,
+    "input:products.color": ({ value, onChange }) => <ColorPicker value={value} onChange={onChange} />,
+    "record.aside:requests": ({ entry }) => <RequestTimeline id={entry.id} />,
+  },
+  plugins: [auditTrail()],
+});
+```
+
+Every component receives the props of the built-in one and `renderDefault(props)`, which renders what it replaces: pass the
+props you were given (spread them to change some), or ignore it to replace the region. A slot is named by a key that `tsc`
+derives from the generated metadata, so a misspelt collection, field or View column is a type error. In a key `<schema>` is a
+collection's name, `<field>` one of its fields and `<column>` a column of an admin View (names contain no `.`).
+
+| Slot | Surface | Props (besides `renderDefault`) |
+| --- | --- | --- |
+| `Shell` | browser | `children`, `nav` (sidebar groups), `brand` |
+| `Sidebar` | browser | `groups`, `brand`, `footer?` (above the signed-in user) |
+| `Header` | browser | `title?`, `actions?` (before the built-in controls) |
+| `Brand` | browser | `title`, `image?`, `href?` |
+| `Home` | browser | `collections`, `site` (what the page shows; the built-in page loads its own data) |
+| `CollectionList` | browser | `collection` (filters come from the page's location) |
+| `RecordView` | browser | `collection`, `entryId`, `surface` |
+| `record.aside:<schema>` | browser | `collection`, `entry`, `surface` |
+| `record.actions:<schema>` | browser | `collection`, `entry`, `surface` |
+| `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` |
+
+`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
+`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.
+
+`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.
+
+`mcp: { csp: { connectDomains, resourceDomains, frameDomains, baseUriDomains } }` names the remote origins Admin's MCP App may
+load. `mantle bundle` builds that App from this same entry (`<assets>/admin/mcp-app.html`) and fails it on an origin that is not
+declared. The build writes the declaration into the file, and `adminMcpApps` sends it to the host as `_meta.ui.csp` on `resources/read`.
+A page may also be an MCP App view: `pages: [{ path, title, element, mcp: { renders: "<view>" } }]`, where `renders` is an admin
+View that has an MCP tool (`tsc` checks it against the generated `admin-client.ts`).
+
+Authorization is unchanged by any of this. A component that shows or hides something grants or denies nothing; the server
+checks every route, View and Procedure.
+
+### Components that also render in an MCP host
+
+Record/collection slots carry `surface: "browser"` and do not mount in an MCP
+Procedure action form. A slot marked both renders in Admin's browser page and in an MCP host (`surface` is `"browser"` or `"mcp-app"`). A component
+for one of these slots must:
+
+1. read and write data only through the hooks, not `fetch`, and keep no login state in `document.cookie` or `localStorage`;
+2. link with `<AdminLink href>` or open URLs with `useOpenLink()` (from `@aotter/mantle-admin/app` and `/hooks`),
+   never `window.open` or `target="_blank"`, which a host's sandbox blocks. In a host `<AdminLink>` opens an http(s) URL
+   through `ui/open-link` and shows any other href, such as an `/admin/...` path, as plain text, as it has no origin there;
+3. assume no width: a host sets it;
+4. render something on both surfaces when it branches on `surface` or `useAdminSurface()`.
+
+`useOpenLink()` resolves `false` for anything but an http(s) URL, and when a host cannot or refuses to open it.
+
+`mantle bundle` enforces 1 and 2 on the built App (no `/admin/api`, no `document.cookie`, no undeclared remote origin; `window.open`
+and `target="_blank"` warn), and your CSS and Tailwind classes reach the App. The surface table, the theme mapping and the full
+rules are in [Customising Admin for MCP hosts](mcp-apps.md#customising-admin-for-mcp-hosts).
+
+### Hot reload while you work on `src/admin.tsx`
+
+By default `wrangler dev` rebuilds Admin with `mantle bundle` when its sources change; reload the page. For hot module
+replacement, add a Vite config yourself; nothing in a template enables it:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { adminVitePlugin } from "@aotter/mantle-admin/build";
+export default defineConfig({ plugins: [adminVitePlugin({ entry: "src/admin.tsx" })] });
+```
+
+Run `vite` beside `wrangler dev` and open `http://localhost:5173/admin/`. The plugin proxies `/admin/api` and `/api/auth` to
+`http://localhost:8787` (`target` changes it; `authBasePath` names the auth path when the service's is not `/api/auth`). The proxy keeps
+the dev server's `Host`, so the browser's `Origin` and the service's own origin agree and session writes pass the same-origin check.
+The service may still need to trust `http://localhost:5173` as an auth origin for sign-in.
+
 ## Generated reads and writes
 
 `adminBindings()` returns static metadata, schemas, views, operations and the
@@ -128,7 +288,9 @@ Pages keep native NULL ordering, id ties, microsecond timestamp keys and an
 opaque cursor bound to caller, input, filters and ordering. Malformed/foreign
 cursors and unknown selectors fail before acquiring the route's DB handle;
 the app's authentication may already have used its own database. Admin manifest
-Views retain their complete proved key tuple, not a two-key approximation.
+Views retain their complete proved key tuple, not a two-key approximation. A View without a key is accepted only as a proved
+singleton, such as an aggregate without `GROUP BY` (`SELECT COUNT(*) AS count FROM requests WHERE status = 'submitted'`): it
+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
@@ -159,7 +321,7 @@ 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.
 
-## Statistics and extensions
+## Statistics
 
 `GET /admin/api/collections/{name}/statistics?range=7d` supports primary or
 standalone collections; folded children/translations are not primary routes.
@@ -172,23 +334,25 @@ most 20 days and 480 buckets, with safe microsecond arithmetic. Temporal enum
 subtypes return original metadata keys; equivalent offset spellings count once
 under the first key, and separate microseconds remain distinct.
 
-Site/media/identity, extensions, WebMCP, design preview and MCP Apps are selected
-through the public Admin modules, not added to the SDK kernel. Extension
-contribution declarations go to `--admin-extensions`; executable handlers and
-sources stay in app-owned server configuration. Raw extension handlers receive
-the original Request without pre-reading, cloning or rebuilding it. Custom
-`bodyLimit` checks Content-Length before DB access; the app must bound reads of
-unknown-length raw streams. Built-in JSON routes use the shared bounded reader
+Site/media/identity, WebMCP, design preview and MCP Apps are selected
+through the public Admin modules, not added to the SDK kernel. A route with
+`rawBody` receives the original Request without pre-reading, cloning or
+rebuilding it; its custom `bodyLimit` checks Content-Length before DB access,
+and the app must bound reads of unknown-length raw streams. Built-in JSON routes use the shared bounded reader
 (default 1,000,000 bytes) after caller/origin checks and before DB acquisition.
 The API advertises capabilities for actually mounted routes, including statistics.
 
 ## 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,
 statistics, CSV, operations/ref effects, stale OCC and persisted state after a
-restart. Recheck extensions, previews, all supported UI languages and the
+restart. Recheck custom components, previews, all supported UI languages and the
 complete developer workspace. A generated file, typecheck or HTTP 200 alone
 does not verify these flows.
 
@@ -198,29 +362,44 @@ SDK package bytes and query/write/cold timing are separate checks. Extra selecte
 Admin indexes add write/storage maintenance; an indexed SELECT plan does not
 prove unchanged write latency. Report remaining gates honestly; this guide does not promise measured performance.
 
-## Extension declarations
-
-Pass full declarations to `--admin-extensions`. Generation emits
-`extensionMetadata` in `admin-descriptors.ts` and compiled settings checks plus
-`extensionBindings` in `admin-extensions.ts`. Bind the same runtime definitions
-(including handlers) with `extensionBindings(adminExtensions)`, and merge the
-returned `extensions` and `routes` into `admin()` options. Declaration drift is
-refused before any handler runs. The older descriptor `extensionBindings` export
-contains manifest UI references only; it is not the runtime binding function.
-
-Native Admin does not serve `source` modules or modify shell import maps. Serve
-an extension's `module` at a same-origin absolute path and install its `integrity`
-in the host shell import map. Selecting `source` fails generation with that
-instruction. This differs from historical 0.2's automatic source-module route.
-
 Entry lists and editor reads/writes return translation badges and related
-sections in one authorized HTTP response. `/bootstrap?collection=...` can include
+sections in one authorized HTTP response.
+Reference fields show titles, not only IDs: a list of an operational collection (for its `list.columns`) and an entry
+read return `ref_titles` / `refTitles`, the title of each record that a displayed `x-mantle-ref` field points at, keyed by
+field and stored value. The server resolves them for the caller with one page query per referenced collection and field
+(at most 50 distinct values), exactly as the parent entry's title is resolved, so visibility and `authorize` apply to the
+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
 `/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
 Admin-selected `created_at` statistics indexes emitted in initial `schema.sql`.
 
+## Migrating from Admin extensions
+
+The extension mechanism is gone: Admin is an application-built React library, and the application's own code replaces
+what an extension contributed. Alpha applications that used it change as follows.
+
+| Removed | Use instead |
+| --- | --- |
+| `--admin-extensions <module>`, `adminExtensions`, `src/admin.ts`, generated `admin-extensions.ts` | Drop the flag from `generate` and `check` scripts and delete the module. `generate` now rejects the option and removes the generated `admin-extensions.ts` (it is SDK-owned). |
+| `navGroups` in that module | `defineAdmin(admin, { nav: { groups } })` in `src/admin.tsx`, an object keyed by group id instead of an array: `{ id: "approvals", title, order }` becomes `approvals: { title, order }`. `tsc` refuses a group the manifest uses and `groups` omits. See [Sidebar](#sidebar). |
+| `defineAdminExtension`, `@aotter/mantle-admin/extension` | React components in `defineAdmin`: `components` for the regions below, `pages` for whole pages; see [Customising Admin](#customising-admin) and [Sidebar](#sidebar). |
+| Field widget `widget: <extension>/<contribution>` and `options` | `"input:<schema>.<field>"` in `components`. `widget: textarea` stays. |
+| `list.cells` on a Schema or View | `"cell:<schema>.<field>"` or `"cell:view:<view>.<column>"` in `components`. |
+| `uiSchema.panels`, `record.sidebar/v1` and `home/v1` panels | `"record.aside:<schema>"` and the `Home` component. |
+| `record/v1`, `list.selection/v1` and `list.toolbar/v1` actions | `"record.actions:<schema>"` and `"list.actions:<schema>"`; call a Procedure with `useOperation`. |
+| Handlers `api`, `settings` and `actions.run`, and the `/admin/api/x/<extension>/*` routes | Server work is a Procedure (writes), a View (reads) or an application route. Authorization stays on the server: a Procedure or View carries its own `requires`. |
+| `extensionBindings`, `extensionOptions`, `@aotter/mantle-admin/server/extensions`, the `extensions` and `navGroups` options of `admin()` and the `extensions` field of `/admin/api/site` | Delete them. |
+| The import map and `shared/*.js` shims in the built Admin | None: the application's bundle holds the one React there is. Drop any CSP hash for the import map. |
+| Extension pages (`/admin/x/<extension>/<page>`) | `defineAdmin({ pages: [{ path, title, element, nav }] })` at `/admin/p/<path>`; `nav: { group, order? }` replaces the page's `nav`, in a built-in group or one the manifest uses (an extension's own `navGroups` entry that no Schema or View uses cannot hold a page). A page has no `role`: every member sees it, so gate inside the element with `useMe()`; the `requires` of the View or Procedure it calls still decides what works. |
+| Extension settings pages (declared form, `settings` handlers) | A page in `pages` whose element reads and saves through a View and a Procedure that hold the settings, or an application route. |
+
+A manifest that still names a removed key fails `mantle generate` with `SCHEMA_UI_INVALID` or `VIEW_UI_INVALID` at the
+key's path. The `UI_EXTENSION_*` diagnostics no longer exist.
+
 ## Collection list template today
 
 The compiler derives display/filter metadata from Schema `uiSchema`, searchable fields from `searchableFields`, and sortable fields from indexes plus required/non-null fields and selected system columns. It emits per-collection quoted fragments, row policies and bind recipes; Admin uses one shared `nativeEntryPage` implementation, not Store `find`, `search` or `count` for these lists.
@@ -234,29 +413,97 @@ Store keeps `find({ search })`, `first({ search })` and `count(where?)`. See [St
 A Schema with a required `x-mantle-ref` folds under its parent collection: it
 opens from the parent entry's workbench and stays out of the sidebar, while
 `/admin/c/<schema>` still lists it; translation children remain on language
-tabs. Set `Schema.spec.uiSchema.nav.standalone: true` to put a required-ref child
-at the top level instead. With multiple eligible references, set
-`nav.parentField` to the chosen reference field.
+tabs. The parent is the reference named by `Schema.spec.uiSchema.nav.parentField` (a required
+`x-mantle-ref` field, by `id` or by a unique field), else the only required `id` reference, else
+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
+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;
+a child folded only by a unique-field reference stays in its parent's workbench. With
+`standalone`, `parentField` must name a required `id` reference.
 
 ### Sidebar
 
-By default the sidebar lists publishing Schemas under Content, operational Schemas under Records (`operations`),
-admin Views under Reports and Admin's own pages under More, each in name order. A project arranges it for how its
+By default the sidebar lists publishing Schemas under Content, operational Schemas under Records (`operations`) and
+admin Views under Reports, in manifest declaration order (source files in the order given to `mantle generate`, then
+document order), with Admin's own pages under More. A project arranges it for how its
 staff work, in the same manifest change that adds a Schema or View. Placement is presentation only: permissions,
 REST, MCP and storage are unchanged, entries a caller cannot see stay hidden, and an empty group is not shown.
 
 - `Schema.spec.uiSchema.nav` and admin `View.spec.uiSchema.nav` take `group` (a group id), `order` (an integer;
-  ascending, entries without one follow in name order) and `hidden: true` (out of the sidebar, still at its URL).
-- Built-in groups need no declaration: `content`, `operations`, `reports`, `more`. Project groups are declared once
-  as `navGroups` in the `--admin-extensions` module, with a title (text or `{ locale: text }`) and an `order` among
-  the built-in groups' content 10, operations 20 and reports 30 (default 50); More always stays last.
-- Extension pages use the same ids: `pages[].nav: { group, order }` (`more` and `settings` keep their places).
+  ascending; entries without one follow in that default order, collections before Views) and
+  `hidden: true` (out of the sidebar, still at its URL).
+- Built-in groups need no declaration: `content`, `operations`, `reports`, `more`. A project declares every other
+  group once, in `src/admin.tsx`: `defineAdmin(admin, { nav: { groups } })`, each with a title (text or
+  `{ locale: text }`) and an `order` among the built-in groups' content 10, operations 20 and reports 30 (default 50);
+  More always stays last. Declaring a built-in id is a type error (and ignored at runtime). `generated/admin-client.ts` exports `ManifestNavGroup`, every group the manifest uses, and types
+  `nav.groups` so that `tsc` refuses an entry that leaves one out (`mantle generate` no longer checks it). Without an
+  `src/admin.tsx` (the built-in entry) nothing refuses it, so an undeclared group still shows its items, titled by its id.
+- `nav.items` adds entries beside the ones `uiSchema.nav` produces: `{ group, title, icon?, order?, to }`, where `title` is
+  text or `{ locale: text }`, `icon` is any React icon component, and `to` is `{ collection, filter? }` (the list, preset
+  to the value of one field) or `{ view, input? }` (an admin View with its input). Names, the filter field and value and the
+  View input are typed from the generated manifest, so a misspelling or a wrong preset fails `tsc`. Several items may lead to
+  one resource with different presets. An item whose collection or View the caller cannot see is not shown; showing or
+  hiding one changes no permission, because the target's own route still decides.
+- <a id="sidebar-badges"></a>`badge: { view, field }` on an item shows a count after its title: `field` of the one row an aggregate admin View
+  returns, typically one with `uiSchema.nav.hidden: true` so it stays out of Reports. The View is typed from the generated manifest
+  and runs for the current caller through its own `requires`, scope and TTL, with no system fallback. Admin reads every badge of the
+  sidebar in one `GET /view-batch` (the first 20 distinct Views; `defineAdmin` logs the rest and they show nothing). Zero shows a muted
+  `0`, loading a placeholder and an unreadable count `!`. A refused or missing View shows nothing, so a badge never reveals a queue
+  the caller cannot read, and no state blocks the link. Counts are cached for 30 seconds, read again when the window regains
+  focus, and refreshed after a mutation through Admin's shared query cache (`useOperation` or any Admin write); there is no polling.
+  The cache is keyed by the signed-in user. A replacement `Sidebar` reads the same counts with `useBadges`. Badges are browser only.
+- `pages` adds a page of the application's own inside Admin's shell: `{ path, title, element, icon?, nav? }`. `path` is one
+  segment of lowercase letters, digits and hyphens, and the page is at `/admin/p/<path>`. `nav: { group, order? }` places it in
+  the sidebar with the other entries of that group (the same group ids as `nav.items`: a built-in group, or one that a manifest
+  `uiSchema.nav.group` uses; `tsc` refuses any other); without `nav` it keeps its route and stays out of the sidebar. A page has
+  no `role`: every Admin member sees it, so hide a part of it with `useMe()` and rely on the `requires` of what it calls. A page's `element` reads through the [data hooks](#typed-data-hooks) and writes through
+  Procedures; showing a page grants nothing, because each View or Procedure it calls authorizes on the server.
+- `home` names where `/admin` leads: `{ collection, filter? }`, `{ view, input? }` (typed like `nav.items[].to`) or `{ page: "<path>" }`
+  for one of `pages`. When the caller can see the target, `/admin` redirects to it and Admin's own home (setup and connector
+  content, or your `Home` override) moves to `/admin/setup`, listed first under More. When the caller cannot see the target, or without
+  `home`, `/admin` stays the built-in home. Choosing a landing page grants and denies nothing; the target's own route still decides.
+  The landing is browser only.
+
+`pages[].header` composes actions beside the native page title without replacing
+Admin's shell or targeting its internal DOM:
+
+```tsx
+pages: [{ path: "queue", title: { en: "Queue", "zh-TW": "待辦" },
+  header: { description: "Items awaiting review", actions: <QueueActions /> },
+  element: <QueuePage />, mcp: { renders: "pending-requests" } }]
+```
 
-```ts
-// src/admin.ts, passed as --admin-extensions src/admin.ts (the app shell already does)
-import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
-export const navGroups: AdminNavGroup[] = [{ id: "approvals", title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 }];
-export const adminExtensions: AdminExtension[] = [];
+The explicit object renders the same native heading on both surfaces. `title`
+and `description` resolve using the browser preference or MCP host locale;
+`actions` is React content, so its component may use the existing hooks and
+host-aware links. Keep action controls disabled or provide a fallback when the
+host lacks a capability. Do not add another h1 to `element` with this header.
+Use `header: false` if the element owns its heading. Omitted preserves existing
+behavior: native title in the browser, element alone in MCP. This option does
+not customize the global application `Header` slot.
+
+
+`src/admin.tsx` is JSX and runs in the browser, so `tsconfig.json` needs `"jsx": "react-jsx"` and `"lib": ["ES2023", "DOM"]` beside the Worker's `types` (`@cloudflare/workers-types`, `node`) and must include `src/**/*.tsx`; `node_modules/@aotter/mantle/docs/examples/app-shell/tsconfig.json` is the working file. The app also depends on `react`, `react-dom` and `@types/react` (see the example's `package.json`). The app owns `react` and `react-dom` (Admin and the kit take them as peers), so pin both to the same exact version: `react-dom` refuses to run beside a different `react`. `mantle bundle` stops with a message when they differ; add `lucide-react` (or another icon package) yourself if you use icons.
+
+```tsx
+// src/admin.tsx
+import { Inbox } from "lucide-react";
+import { defineAdmin } from "@aotter/mantle-admin/app";
+import { admin } from "../generated/admin-client.js";
+
+export default defineAdmin(admin, {
+  nav: {
+    groups: { approvals: { title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 } },
+    items: [
+      { group: "approvals", title: "Waiting for me", icon: Inbox, to: { view: "pending-requests" } },
+      { group: "approvals", title: "Rejected", to: { collection: "requests", filter: { status: "rejected" } } },
+    ],
+  },
+});
 ```
 
 ```yaml
@@ -264,8 +511,10 @@ export const adminExtensions: AdminExtension[] = [];
 uiSchema: { nav: { group: approvals, order: 1 } }
 ```
 
-`mantle generate` refuses an undeclared group, a duplicate or built-in `navGroups` id and a non-integer `order`.
-The purchasing example puts its approval queue and requests in an Approvals group.
+`mantle generate` refuses a non-integer `order` and
+placement on a Schema without a sidebar entry of its own: a translation, or a folded child that is not
+[`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)).
 

package/docs/handbook/guides/oauth.md

@@ -5,7 +5,10 @@ create your `betterAuth()` instance with `jwt({ disableSettingJwtHeader: true })
 and `oauthProvider` (or the provider's MCP preset). Append `oauthGrantExtension`
 **first** in its `extensions`. The helper comes from
 `@aotter/mantle/auth/oauth` and binds issued access tokens to the current consent
-ID and Better Auth’s consent reference without changing `referenceId`.
+ID and Better Auth’s consent reference without changing `referenceId`. Add
+`oauthGrantRevocation()` from the same module to the plugins: it ends a user's
+grants on a password reset or admin action (below), and `mantle generate --auth`
+refuses an OAuth provider without it.
 Configure
 `consentPage: "/oauth/consent"`, loginPage,
 resources, allowed/default client registration scopes, and public/native DCR
@@ -55,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
@@ -66,14 +78,116 @@ private/no-store. Connected-app redirects must be same-origin paths.
 issuer, audience and request-bound DPoP through Better Auth, including a durable
 single-use proof reservation. It then checks the live consent and session and
 loads the current database user.
-All of sub, azp, sid, mantle_consent_id and the consent reference must match;
-the consent must cover the resource and every token scope, and the session must
-still be alive. `scopes` adds a resource-specific scope floor (403 when missing).
+All of sub, azp, mantle_consent_id and the consent reference must match, and so
+must sid while the token stands on its session (an `offline_access` token may
+outlive it; see below). The consent must cover the resource and every token
+scope. `scopes` adds a resource-specific scope floor (403 when missing).
 Unbound legacy tokens fail closed. Disconnect deletes the grant first, revokes
 its access/refresh tokens. Tokens issued without an active consent fail closed.
 First-party `skip_consent` tokens instead require a live, enabled client with
-`skipConsent` and allowed scopes, plus a live user session. Already-issued
+`skipConsent` and allowed scopes, plus the same session or `offline_access`
+rule as consented tokens. Already-issued
 JWTs fail on the next call, and reconsenting cannot revive the old JWT lineage.
+
+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
+`invalid_grant`, so it never yields an unusable token. An `offline_access` grant
+outlives the browser session. Expiry, deletion and sign-out of the session leave
+it usable until its current refresh token expires or is revoked. Revocation
+includes disconnect, refresh-token revocation and Better Auth's reuse detection.
+Each refresh rotates the token with a fresh `refreshTokenExpiresIn` (30 days by
+default), so an offline grant that keeps refreshing does not expire. Without a live session, its access tokens need an
+unrevoked, unexpired `offline_access` refresh token for the same user and client.
+The consent, client, scope, resource and ban checks still apply. An access token
+issued before sign-out stays valid until it expires (one hour by default).
+`oauthGrantRevocation()` ends every OAuth grant of the user once one of these
+succeeds: revokes their refresh and access tokens, deletes their consents for
+every client (the next authorization asks again, except for a first-party
+`skip_consent` client, which never asks) and their unredeemed
+authorization codes. The events and the sessions each one ends:
+
+| Event | Sessions ended |
+| --- | --- |
+| Password reset (`/reset-password`, `/email-otp/reset-password`, `/phone-number/reset-password`) | all |
+| Admin password change (`/admin/set-user-password`) | all |
+| Password change with `revokeOtherSessions` | all; Better Auth gives the current device a new session |
+| Admin ban (`/admin/ban-user`, or `/admin/update-user` setting `banned: true`) | all (Better Auth) |
+| Admin session revocation (`/admin/revoke-user-sessions`) | all (Better Auth) |
+| Email OTP or magic-link sign-in (`/sign-in/email-otp`, `/magic-link/verify`) that proves the address of an unverified user | all, and its password and linked accounts (Better Auth) |
+
+The last row covers account pre-hijacking: someone who signed up with another
+person's address before it was verified loses their OAuth grants as well as the
+password, linked accounts and sessions that Better Auth strips when the owner
+proves the address. Mantle ends these grants before Better Auth checks the code or
+link, while the user is still unverified, so a failed OTP or magic-link attempt on an
+unverified user also ends that user's OAuth grants.
+
+Otherwise a failed attempt, session expiry, a password change without `revokeOtherSessions`,
+and the user's own sign-out, `/revoke-sessions` and `/revoke-other-sessions`
+("sign out everywhere") end no OAuth grant, as in Better Auth; the user ends a
+connected app's grant by disconnecting it on the connected-apps page
+(`/oauth/consents`). Unbanning does not restore grants. An access token issued
+before the event is rejected on its next use, with one exception: an
+`offline_access` access token of a first-party `skip_consent` client passes again,
+until it expires (one hour by default), once the user grants that client offline
+access anew, because it is checked against any live `offline_access` refresh token
+of the same user and client. Better Auth's `/oauth2/introspect` reports a refreshed
+token inactive once its original session has expired, while Mantle's resource
+check accepts it; Mantle does not use introspection.
 Database failures remain server errors, rather than silently authenticating.
 
 For app-owned API keys/personal tokens, supply `resolveCredential(request)` in

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

@@ -7,9 +7,9 @@ here instead of repeating it.
 
 - **Generated `web()`**: list and detail pages straight from public Views, with `llms.txt`, sitemap, Markdown
   alternates and canonical tags. Its contract and limits are in [surface contracts](../reference/surface.md#optional-web-output);
-  the smallest example is `docs/examples/generated-web`.
+  the smallest example is `node_modules/@aotter/mantle/docs/examples/generated-web`.
 - **App-owned pages** in `src/routes.ts`, when the page needs its own layout, JSON-LD or languages. The reference
-  implementation is `docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
+  implementation is `node_modules/@aotter/mantle/docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
 
 ## Every public page