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

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

@@ -1,170 +1,11 @@
----
-description: What Admin serves in 0.2.0, how manifests and uiSchema become Admin's collections, reports and operations, and how to verify a change.
----
 # Customize Admin from manifests
 
-`createAdminSurface` serves Admin's API at `/admin/api/*` behind a staff gate.
-Every route reads and writes through `runtime.store.as(caller)` and
-`invokeProcedure`, so Admin sees exactly what the signed-in staff member may
-see. What Admin shows is derived from the compiled plan: labels, forms, list
-columns, reports and operations are manifest edits.
+Select `--admin` and mount [native Admin](native-admin.md) from `@aotter/mantle-admin`. The app serves its assets and owns authentication. UI and SDK are separate packages.
 
-With feature `admin`, the generated preset also serves the console, the
-prebuilt SPA in `@aotter/mantle-ui/admin`, at `/admin`: `wrangler.jsonc` binds
-`node_modules/@aotter/mantle-ui/dist/admin` as the Worker's `ASSETS`
-(`run_worker_first`), and `src/service.ts` passes `createAdminSurface` an
-`assets` function that reads from it. `mantle generate` warns when `admin` is
-selected and `wrangler.jsonc` binds no `ASSETS`. The Bun preset reads the
-same files with `bunAdminAssets` from `@aotter/mantle/bun`. Sign in at
-`/admin/sign-in`.
+Schema `uiSchema` selects fields, widgets, list columns, enum tabs and child navigation. The compiler derives sortable fields from indexed required/non-null fields; it emits selected system/statistics indexes in initial DDL. Apply those indexes through an explicit migration on existing databases.
 
-## Manifest to Admin
+Admin Views provide custom read lists; their SELECT outputs, column lineage and `uiSchema.list` define display/search/filter metadata. Procedures and MCP admin Triggers define operations with declared authorization, input checks and optional row targets. A hidden button never authorizes an operation.
 
-| You want | Author this | Effect and limits |
-|---|---|---|
-| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` (a string or a locale map) | Labels and help. Stored names do not change |
-| Required fields and option lists | JSON Schema `required`, `enum`, `type` | Data contracts, checked on every write, not styling |
-| Option labels | a string property's `oneOf: [{ const: open, title: { en: Open, zh-TW: 處理中 } }, …]` instead of `enum` | Selects, filter tabs and list cells show the `title` |
-| A multiline string | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | `textarea` is the only built-in explicit widget |
-| Your own control, list cell or record panel | `uiSchema.fields.<name>.widget: <extension>/<contribution>`, `uiSchema.list.cells`, `uiSchema.panels` | Contributions of the project's Admin extensions; see [Extend Admin](admin-extensions.md) |
-| Markdown or HTML | property `x-mcp-hint: markdown` or `html` | A rich editor |
-| A timestamp, a date or money | `format: date-time`, `format: date`; `x-mcp-hint: money-minor` on an integer | Date controls; money in minor units, with a sibling `currency` when present |
-| Columns of an operational list | Schema `uiSchema.list.primaryField`, `.columns` | `primaryField` is a scalar data field; `columns` may name native columns (`createdAt`, `updatedAt`) |
-| Business-state tabs | Schema `uiSchema.list.filterField` | Operational Schemas only; a string enum that leads an index |
-| Search | Schema `searchableFields` | Full-text search over those string fields, plus `id` |
-| Related records | a required property with `x-mantle-ref` | Children fold under their parent |
-| A folded child in navigation too | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Its own list with a parent filter |
-| A read-only report with CSV | a View with `surface: staff`, `title`, `uiSchema.list` | `columns`, `searchFields` and `filterFields` name the View's outputs; the search box and filters become `LIKE` and `=` on them. `GET /admin/api/views/<name>/export` returns every matching row |
-| An operation | a Procedure bound by a Trigger with `source: { kind: mcp, surface: staff }` | Listed at `/admin/api/operations` for staff its `requires` admits, and run with `POST /admin/api/operations/<name>` |
-| A row operation | that Procedure's `target` (declared or inferred from `WHERE id = … AND version = …`) | Bound to the row's `id`, and its version when the target names one |
-| A list-level operation | Procedure `uiSchema.collectionAction: <schema>` | Shown on that collection |
-| No generic edits | Schema root `schema.readOnly: true` | Admin's entry routes refuse writes (`CONFLICT`); declared Procedures still run |
+Generic publishing edits apply to drafts; publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
 
-Schema list presentation (`primaryField`, `columns`, `filterField`) is for
-`lifecycle: operational`. Publishing Schemas keep the draft, publish and
-archive workflow (`POST /admin/api/entries/{id}/publish` and `/unpublish`).
-
-## Example: an operational inbox
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: support-tickets }
-spec:
-  title: { en: Support tickets, zh-TW: 客服工單 }
-  lifecycle: operational
-  indexes: [[ticketState]]
-  searchableFields: [subject, details]
-  uiSchema:
-    fields:
-      details: { widget: textarea }
-    list:
-      primaryField: subject
-      columns: [ticketState, createdAt]
-      filterField: ticketState
-  schema:
-    type: object
-    additionalProperties: false
-    required: [subject, ticketState]
-    properties:
-      subject: { type: string, title: Subject }
-      details: { type: string, description: Include the steps to reproduce. }
-      ticketState: { type: string, enum: [open, waiting, closed] }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: support-report }
-spec:
-  title: Support report
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  uiSchema:
-    list:
-      columns: [subject, ticketState, created_at]
-      searchFields: [subject]
-      filterFields: [ticketState]
-  sql: SELECT id, subject, ticketState, created_at FROM "support-tickets" ORDER BY created_at DESC
-```
-
-Schema `uiSchema.list` and View `uiSchema.list` are different contracts; do
-not copy keys between them. The report's search box matches `subject`
-(`LIKE`), its filter is `ticketState` (`=`), and a declared `input` would add
-a form above them; all of them keep cursor paging.
-
-## Developer console
-
-The Developer console's Procedure overview projects the sealed SQL AST into
-a static execution diagram: authorization, validated input, guard, applicable
-lifecycle hooks, ordered atomic statements, commit or rollback, and output
-validation. Statement cards show read/write dependencies, row versus set
-semantics, RETURNING and ordered CASE assignments. CASE chooses a field value;
-WHERE filters rows. A set operation can affect zero rows and still continue.
-Output validation and after-hook failures do not roll back an existing commit.
-Unsupported expression shapes remain explicitly opaque beside authored SQL;
-code handlers' effects and actual run history are not inferred.
-
-The inline business flow uses Schema/property titles and titled enum options
-from the developer snapshot; generic verbs and operators are UI translations.
-It expands direct `UPDATE SET field = CASE … END` assignments only. CASE
-inside arithmetic, casts, functions, SELECT or INSERT remains in the SQL
-detail tree, rather than pretending its intermediate result is the assigned
-value. SQL identifiers match manifest names case-insensitively. The existing
-`money-minor` display convention uses hundredths and a single-valued sibling
-`currency` enum; if numeric conversion or currency formatting would round a
-threshold, the flow shows its exact SQL literal marked as a raw SQL value.
-These display hints do not establish or validate business units.
-
-## Roles
-
-Admin's gate admits any staff role. Inside it, each route names the least role
-it needs: `contributor` reads and edits drafts, `editor` publishes, deletes
-and manages media, `owner` manages staff, site settings and the developer
-console. Operations and staff Views are further limited by their own
-`requires`.
-
-Those atom predicates do not restrict generic Schema entry routes. A root
-Schema `readOnly: true` blocks generic writes, not reads. In a service where
-only owner/editor reviewers may read an unscoped table, restrict the Admin
-surface in the application-owned `src/service.ts`:
-
-```ts
-// Replace the preset's Admin composition, keeping its existing options.
-const adminSurface = createAdminSurface(runtime, { /* existing Admin options */ });
-const admin = withCaller(resolver, async (request, caller) => {
-  if (new URL(request.url).pathname.startsWith("/admin/api/") &&
-      caller.kind === "user" && caller.role === "contributor") {
-    return Response.json({ error: {
-      code: "AUTH_DENIED", message: "Admin access requires an owner or editor role.",
-    } }, { status: 403 });
-  }
-  return adminSurface(request, caller);
-});
-```
-
-The preset already imports `withCaller` from `@aotter/mantle`. Reuse its
-resolver so credential validation and the session origin guard run once;
-Admin retains its own gates for members and anonymous callers. Contributors
-can use an application-owned page over an owner-filtered public View. Keep
-sign-in, OAuth consent and UI assets reachable; restricting the whole `/admin`
-prefix would also block member MCP consent at `/admin/oauth/consent`. This is
-host surface composition, not a Procedure `ref` handler or a new Manifest
-permission key. Exercise generic entry reads, reports and operations with
-each role, including after revoking a role in an existing session.
-
-## Verify a change
-
-1. Run `mantle generate`, then `mantle generate --check`.
-2. Restart `wrangler dev` (or the Bun process) so the runtime loads the new plan.
-3. Open `/admin` with a staff session and check the affected list, form,
-   report or operation. `GET /admin/api/bootstrap` carries the collections,
-   Views, operations and site the console renders.
-
-`uiSchema` keys are closed. Schema takes `fields`, `list` and `nav`;
-Procedure takes `collectionAction` and `fields`; a staff View takes `list`. No
-layout, CSS, component or permission keys exist; build those in your own UI
-over Admin's API or your own surfaces.
-
-## Source
-
-- [Schema](../reference/schema.md#uischema), [View](../reference/view.md) and [Procedure](../reference/procedure.md) references
-- [HTTP, MCP, CLI and packages](../reference/surface.md): every Admin route
+Use [extensions](admin-extensions.md) for app-owned pages, actions, panels or field renderers. Keep exact conflict/uncertain-outcome handling in the shared UI controller.

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

@@ -10,8 +10,8 @@ carries.
 
 ## 1. Install the `mantle` skill
 
-The Mantle plugin carries one skill, `mantle`, its helper script, and the
-Mantle Cloud MCP connection (`https://cloud.mantle.tools/mcp`).
+The Mantle plugin carries one OSS authoring skill, `mantle`, and local
+acceptance references. It does not configure a hosted-service connection.
 
 ```bash
 # Claude Code: two separate prompts
@@ -30,8 +30,7 @@ Without a plugin host, install the skill alone:
 npx skills add aotter/mantle
 ```
 
-A skill-only install has no Cloud MCP connection; add one by hand if you need
-it. Either way, read the path the installer prints (for project-local Codex,
+Read the path the installer prints (for project-local Codex,
 `.agents/skills/mantle/SKILL.md`). The skill installs no SDK, creates no
 project and copies no handbook.
 
@@ -65,18 +64,6 @@ An agent reads these files from `node_modules` when the task calls for them.
 
 ## 3. Verify the application
 
-Installing instructions proves only that they were copied. Prove the service:
+Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again. Test actual routes and persisted state. With selected Admin, mount `entries(bindings.schemas, bindings.adapter)` and serve assets separately. Verify member/admin OTP, row visibility and OCC. Installing a skill proves none of these flows.
 
-1. `mantle generate` and `mantle generate --check` exit 0.
-2. The project typechecks against `.mantle/generated/mantle.ts`.
-3. `wrangler dev` (or, on Bun, `bun src/index.ts`) starts, and the routes you depend on answer: a REST View, an
-   HTTP Trigger, `/mcp` `tools/list`, and with identity `mantle` a sign-in and
-   `GET /admin/api/me`.
-
-| Symptom | Cause and next step |
-|---|---|
-| `docs/...` is missing after installing the skill | The skill carries no docs. Install the SDK and read `node_modules/@aotter/mantle/docs/`. |
-| `mantle` is not found | Install `@aotter/mantle` locally and run it through the package manager (`pnpm exec mantle`). |
-| `mantle skills` is unknown | It is 0.1.x. Follow the installed 0.2.x docs. |
-| A v1 manifest or a `version: 1` config fails | The project is on 0.1.x. Follow `docs/upgrade-0.1-to-0.2.md`. |
-| A documented feature is missing | The installed version is older than the docs you read. Read its own docs, or upgrade deliberately. |
+If packaged docs are missing, reinstall the SDK version pinned by the app. If a feature differs from an online page, read the installed docs rather than assuming compatibility.

package/docs/handbook/guides/email.md

@@ -0,0 +1,86 @@
+# Transactional email
+
+Import the optional email port from `@aotter/mantle/email`. Mantle supplies
+`EmailSender`, `EmailSendArgs`, English `signInCodeEmail`, `signInLinkEmail`
+and `adminInvitationEmail` templates, and `ConsoleEmailSender` for local
+development. Applications select and configure their sender and Better Auth
+plugins.
+
+`send({ to, subject, text, html?, locale, category? })` returns `Promise<void>`.
+The templates return `{ subject, text }`, with the same English text as 0.2;
+they do not translate or consume `locale`. Pass the recipient's locale through
+to the sender, which can select localized templates. Existing categories are
+`auth.email-otp.<type>`, `auth.magic-link.sign-in` and `auth.admin-invitation`.
+
+## Application wiring
+
+```ts
+import { emailOTP } from "better-auth/plugins";
+import { hashEmailOtp } from "@aotter/mantle/auth/hardening";
+import { signInCodeEmail, adminInvitationEmail, type EmailSender } from "@aotter/mantle/email";
+
+const locale = (request?: Request) =>
+  request?.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() || "en";
+
+// Include this plugin in the app's Better Auth options.
+export const emailPlugin = (sender: EmailSender, secret: string) => emailOTP({
+  storeOTP: { hash: otp => hashEmailOtp(secret, otp) },
+  sendVerificationOTP: ({ email, otp, type }, ctx) => sender.send({
+    to: email, ...signInCodeEmail(otp), locale: locale(ctx?.request),
+    category: `auth.email-otp.${type}`,
+  }),
+});
+
+// Use the configured, trusted application origin, never an incoming Host or
+// Origin header. The application grants the OSS "admin" role before sending.
+export const inviteEmail = (sender: EmailSender, origin: string, to: string, language: string) =>
+  sender.send({
+    to, ...adminInvitationEmail("admin", new URL("/admin/sign-in", origin).href),
+    locale: language, category: "auth.admin-invitation",
+  });
+```
+
+For magic links, pass Better Auth's generated URL to `signInLinkEmail(url)`;
+configure Better Auth's `baseURL` and `trustedOrigins` to prevent untrusted
+callback destinations. Templates preserve their input as plain text and never
+interpret it as HTML. If a sender supplies `html`, it owns escaping untrusted
+text and attributes and validating link destinations. Pass structured fields
+to the provider; do not interpolate them into raw MIME headers.
+
+Use `new ConsoleEmailSender()` only in explicitly selected local development.
+It logs recipients, codes and links and sends nothing; never select it in
+production or log live messages in a production sender. Provider failures
+reject the promise; the application owns error handling and retry policy.
+
+**Never let the response wait for the send.** Better Auth calls
+`sendVerificationOTP` for `email-verification` and `forget-password` only when
+the user exists, so a response that waits for the provider reveals whether an
+account exists. Configure Better Auth's `advanced.backgroundTasks.handler` (on
+Workers, `ctx.waitUntil`) so the send runs after the response, as 0.2 did; the
+app-owned auth template wires it.
+
+## Cloudflare Email Service binding
+
+Use a verified sender and a Cloudflare Email Service `send_email` binding.
+The binding composes the message natively; no mail SDK or MIME builder is needed.
+
+```jsonc
+{ "send_email": [{ "name": "EMAIL" }] }
+```
+
+```ts
+import type { SendEmail } from "@cloudflare/workers-types";
+import type { EmailSender } from "@aotter/mantle/email";
+
+interface Env { EMAIL: SendEmail; EMAIL_FROM: string }
+export const emailSender = (env: Env): EmailSender => ({
+  async send({ to, subject, text, html }) {
+    await env.EMAIL.send({ from: env.EMAIL_FROM, to, subject, text, html });
+  },
+});
+```
+
+The English example ignores `locale` and `category`; a localized provider may
+use both. The binding's verified sender and recipient restrictions still apply.
+This example does not provision a sender, enable an auth method or send mail
+without application wiring.

package/docs/handbook/guides/mcp-apps.md

@@ -0,0 +1,44 @@
+# MCP Apps
+
+Generated `mcp()` accepts app-owned UI resources on either endpoint. Each
+endpoint accepts one contributor or an array; Admin uses the same public hook:
+
+```ts
+import type { McpApps } from '@aotter/mantle/mcp';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
+import { mcp } from './generated/mcp.js';
+
+const app: McpApps = { resources: [{
+  uri: 'ui://my-app/records', name: 'my-app-records',
+  html: () => loadAppHtml(), renders: ['records'],
+}] };
+const handler = mcp({ db, caller, apps: {
+  public: app, admin: [adminMcpApps(adminOptions), adminApp],
+} });
+```
+
+Use your own `ui://<app>/…` prefix. `ui://mantle-admin/…` is reserved for Admin.
+HTML is reusable static content; caller-specific data comes from tool results.
+Build the front end with the official `@modelcontextprotocol/ext-apps` client.
+`renders` links tools to `_meta.ui.resourceUri`; `appOnly` adds
+`visibility: ["app"]`. Both name tools actually exposed on that endpoint.
+Resources may supply CSP, permissions and `prefersBorder`.
+
+For static tool tables, construction checks contributors. Request-bound tool tables check on the first matching request and recheck changed tool names. Duplicate
+resource URIs or names, conflicting tool ownership, and absent or foreign-endpoint
+tools throw `ContractError` with code `MCP_APP_CONFLICT`. HTML loaders never run during import or handler construction. Treat descriptors as
+immutable after construction. HTML loads only on `resources/read`; failures
+return a redacted internal error.
+
+Generated media-enabled handlers keep the same cache while resolving their tool
+table against each request's environment. Database handles, storage and Caller
+are never retained in that cache. The low-level SDK also accepts an async
+`(request, env) => tools` resolver; its names must match the endpoint's App
+catalogue. If its tool names change, those links are checked again, and a call
+always uses the current request's tool table.
+
+Clients advertise `io.modelcontextprotocol/ui` and MIME type
+`text/html;profile=mcp-app` in initialization capabilities or, for stateless
+requests, in `params._meta["io.modelcontextprotocol/clientCapabilities"]`.
+An explicit capability declaration without UI support receives no UI resources, UI tool metadata or App-only tools. A stateless request with no capability declaration is treated as unknown and retains App support. Other tools retain their existing validation,
+authorization, caller, origin and database behavior.

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

@@ -0,0 +1,298 @@
+# Native Admin
+
+Select Admin explicitly; use the exact installed SDK/Admin versions.
+
+## Packages and generation
+
+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-ui` | Shared UI kit and generic interaction controller. |
+
+The SDK does not import Admin or its assets. Selecting Admin emits application
+code that imports its small public server helpers. The SPA retains all 22
+languages, rich editors and the developer workspace; language, editor and
+workspace chunks load on demand. It is not part of the SDK query bundle.
+
+Select Admin explicitly:
+
+```sh
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --admin
+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`
+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
+output by hand; regenerate after merging authored inputs. Use the matching
+CLI's `--check` with the same selected options in CI.
+
+Apply initial `schema.sql` and selected auth/site DDL only during explicit
+setup of a new database. Existing data needs reviewed migrations. Imports and
+metadata factories do no storage work. Requests run no DDL or storage checks;
+the only request-time write outside app operations is the configured OAuth
+resource row (see [OAuth](oauth.md)).
+
+## Mount the API and console
+
+```ts
+import { admin } from '@aotter/mantle-admin/server';
+import { entries } from '@aotter/mantle-admin/server/entries';
+import { adminBindings } from './generated/admin-bindings.js';
+import { handlers } from './handlers.js';
+import { resolveRequestCaller } from './identity.js'; // application-owned
+
+const bindings = adminBindings({ handlers });
+const api = admin(bindings.metadata, bindings.views, bindings.operations, {
+  db: (env: Env) => env.DB,
+  caller: resolveRequestCaller,
+  routes: entries(bindings.schemas, bindings.adapter),
+  developerViews: bindings.developerViews,
+});
+// In app-owned fetch: await api(request, env); undefined means fall through.
+```
+
+Ref operations run with the handlers given to `adminBindings({ handlers })`; `admin()` needs no second copy. Without ref Procedures, omit `handlers` and use `adminBindings()`. The app's
+resolver verifies the caller; Admin accepts an admin cookie session classified from
+Better Auth’s admin plugin `adminRoles` (default `["admin"]`), and cookie writes
+retain the shared same-origin check. Comma-separated roles are supported.
+Do not manufacture an admin/system Caller from request input. Views and operations
+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
+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
+[service composition](../cloudflare/service-entry.md) for the complete Fetch/Bun wiring.
+
+## HTTP routes
+
+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`.
+
+| 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. |
+| `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`). |
+| `GET /views/{name}` | Generated admin View query parameters plus `limit`/`cursor`; returns `{ rows, nextCursor? }`. |
+| `GET /me` | Returns `{ userId, role, admin, login, image }` for the signed-in caller. |
+
+Entry create/read/patch/transitions return
+`{ collection, entry, parentEntryId, parentEntryTitle, related }`; the entry has
+`{ id, collection, locale, status, version, data, created_at, updated_at }`.
+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).
+
+## Generated reads and writes
+
+`adminBindings()` returns static metadata, schemas, views, operations and the
+selected native adapter. Metadata-only endpoints add no storage read of their
+own; authentication, optional user enrichment or site loading may still query.
+The shared get/page/statistics functions select quoted tables and columns only
+from generated whitelists. Search/filter/cursor/range values are binds, never
+SQL identifiers. Core compiles scope, TTL, publishing and parent predicates;
+there is no request-time manifest/schema/SQL AST interpreter.
+
+Scoped rows remain private even from other admin. Translation reads merge at
+most one visible parent with the matching join key; scoped parents correlate
+scope in every mode, including trusted reads. Child declarations win over parent
+fields, and a parent's public same-named field cannot replace a child's private
+scope. Unrelated scoped Schemas cannot hide an ordinary public field. Scope and
+storage-only fields are absent from entry data and generated CSV export fields.
+Geo remains experimental: existing native outputs are readable, not generically
+editable. Metadata derives child relationships from `allCollections`.
+
+Entry queries validate indexed sort fields, directions, filters and limits
+1–500. `filter_field` and JSON `filter_values` are paired; each batch has at most
+50 scalar values. Search reuses native SQLite/D1 FTS and PostgreSQL behavior.
+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.
+
+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.
+
+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
+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
+are unchanged.
+
+Publishing/custom Admin operations load existing generated Procedure modules
+when invoked. Ref handlers retain the original typed `{ caller, db, store }`
+context and authorization. Ordinary SDK/REST/MCP emission and the synchronous
+public Store API are unchanged. Selected JSON boundaries preserve declared JSON/boolean conversions and safe
+cross-target integer normalization from SQL text; exact unsafe values are not rounded. Bare
+Views, Store and SQL Procedures keep their driver-native contract. Native
+unique/OCC errors and uncertain transaction outcomes keep their contracts. A 503 outcome may mean a write committed: do not
+retry automatically or turn it into a success by reading afterward. Core
+`statusOf` maps core codes only. App media/site/partial errors use `mediaError`
+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
+
+`GET /admin/api/collections/{name}/statistics?range=7d` supports primary or
+standalone collections; folded children/translations are not primary routes.
+Ranges are `1h`, `24h`, `7d` (default) and `20d`. It returns
+`{ total, buckets, from, to, bucketMs }` in one native aggregate query. `total`
+counts currently caller-visible retained rows, including rows outside the
+requested window; expired rows are excluded. Buckets use `[from, to)` and the
+same generated scope/TTL/parent policy. The shared native function accepts at
+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
+(default 1,000,000 bytes) after caller/origin checks and before DB acquisition.
+The API advertises capabilities for actually mounted routes, including statistics.
+
+## Acceptance
+
+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
+complete developer workspace. A generated file, typecheck or HTTP 200 alone
+does not verify these flows.
+
+Native adapter evidence covers all four targets; local D1 uses real workerd.
+Initial Admin module imports perform no DB work. Startup graphs, uploaded total,
+SDK package bytes and query/write/cold timing are separate checks. Extra selected
+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
+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`.
+
+## 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.
+
+Requests select only generated fields and append only supplied predicates. Absent filters are omitted, rather than expressed as `(? IS NULL OR …)`. Sorts and scalar values are checked before the route acquires its DB handle. In 0.2.0 there is no generated Cartesian set of filter variants or variant cap: runtime SQL shapes depend on selected filters, bounded IN lists, search, cursor and order. Only sortable fields are checked for indexes; there is no per-filter-combination index proof. Inspect EXPLAIN for the actual workload.
+
+Store keeps `find({ search })`, `first({ search })` and `count(where?)`. See [Store search and count costs](typed-queries.md#store-reads-and-writes): Admin shares the dialect search, and a View does not make PostgreSQL ILIKE faster.
+
+## Collection navigation and operation placement
+
+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.
+
+### 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
+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).
+
+```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[] = [];
+```
+
+```yaml
+# a Schema or an admin View
+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.
+
+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)).
+
+Admin operations are Procedures exposed by an admin MCP Trigger. Declare
+`Procedure.spec.uiSchema.collectionAction: <schema-name>` to show the operation
+in that collection's list header. Row operations are chosen by the Procedure's
+explicit `target: { schema, id, version? }`: `id` names the input bound to the
+row id, and optional `version` names the input bound to its reviewed OCC version.
+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.
+
+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
+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
+in a collapsed Details disclosure. CSV exports retain UTC wire timestamps.
+
+Developer Model and Logic pages share an object sidebar on wide containers
+and an object-list drawer on narrow containers.
+Schema Live data previews use collection routes even for folded children.
+Pass `bindings.developerViews` as the Admin `developerViews` option for
+public and admin View previews; ordinary Admin View routes and exports use
+only `bindings.views` (admin Views). View previews use the read-only `/admin/api/developer/views/<view>` route,
+with the signed-in admin caller and the same authorization, scope, TTL and
+publishing policy as REST. Public Views retain public visibility; internal or
+disallowed Views show an unavailable explanation. Previews never use a system
+caller or bypass a View's `requires`.