@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/concepts/views.md

@@ -1,192 +1,116 @@
 ---
-description: Views are the only public read surface — surfaces, declarative versus SQL form, params, identity filters, pagination, the MCP mirror and index planning.
+description: How a View's SQL SELECT is compiled, which policies the runtime injects, and how REST, MCP, Admin and Store serve it with limit and cursor paging.
 ---
 # Reads: Views, REST and MCP
 
-Views declare reusable queries and their transport visibility. This page explains why, how a View is shaped, and what it costs at query time. Field-level rules are in the [View reference](../reference/view.md).
-
-## One read surface, not two
-
-A View is a named, read-only query over Schemas. Public and staff Views mount on supported transports with no [Trigger](./procedures-and-triggers.md) involved. Schemas are never publicly readable on their own.
-
-Exposing collections directly — a `Schema.spec.expose.rest` flag, or a `GET /api/<collection>` shortcut — was considered and rejected. A Schema declares the storage shape. Its entries carry drafts, internal status, server-stamped fields and per-row data the author never intended to publish; `contact-messages` is the canonical example, where a direct collection route would be a privacy bug by default. A View already has the right semantics — a named query with explicit fields, filter, ordering and limit — so auto-exposing it only ratifies what the manifest already says.
-
-Use `surface: internal` for a named query callable only by host code. It remains in the plan and generated bindings, but is absent from REST, MCP, WebMCP and Admin reports. Its `requires` and guards still run. See [Typed queries](../guides/typed-queries.md).
-
-## Surfaces
-
-`spec.surface` is required and closed to three values.
-
-| `surface` | REST | MCP | Extra |
-|---|---|---|---|
-| `public` | `GET /api/views/<name>` | `query_view_<segment>` on `/mcp` | Listed by `GET /api/views` |
-| `staff` | `GET /admin/api/views/<name>` | `query_view_<segment>` on `/mcp/staff` | `GET /admin/api/views/<name>/export`, Admin report sidebar |
-| `internal` | None | None | Host calls through `executeView` or generated `views` bindings |
-
-The adapter filters the View set before building each MCP dispatcher, so a guessed public tool call cannot reach a staff View. Surface decides transport visibility; `spec.requires` decides whether the verified caller may execute the View, on REST and MCP alike. See [Authorization](./authorization.md).
-
-## Declarative `from` versus one `sql` SELECT
-
-A View declares exactly one of `from` or `sql`; declaring both or neither is rejected.
-
-- **`from`** names a Schema and pairs with `fields`, `filter`, `orderBy` and `limit`. The filter is a closed AST: `eq`, `gt`, `gte`, `lt`, `lte`, combined with `and` and `or`. Field-to-field comparison and arithmetic are not expressible.
-- **`sql`** is a single `SELECT` with no semicolon. Every Schema is available as a logical table named after its `metadata.name`, with data properties projected as columns; quote names containing hyphens (`"post-translations"`). Combining `sql` with `fields`, `filter` or `orderBy` is rejected.
-
-Use `from` for portable single-Schema queries, typed result rows and eligible public caching. Use `sql` for joins, aggregation or JSON expansion that the declarative form cannot express. SQL Views require a SQLite-capable adapter (`VIEW_DIALECT_UNSUPPORTED` otherwise), and generated SQL row types are `unknown`. The CLI validates SQL against an empty database of declared Schema tables; programmatic validation needs the `sqlViewSandbox` port for the same check. Exercise data-dependent behavior on your adapter or with `mantle-harness indexes`.
-
-## Params
-
-`spec.params` is a JSON Schema with `type: object` and a `properties` map. The reserved names `page`, `show` and `cursor` are rejected (`VIEW_PARAMS_RESERVED_NAME`); the rest of the query-string namespace is yours.
-
-In the declarative form, a filter value may be the sentinel `{ $param: <name> }`. The name must resolve to a declared param and must appear in `params.required`. In a SQL View, params are named bindings written `:name`; they are bound, never interpolated, and every `:name` must be a required declared param.
-
-## Identity-bound Views
-
-A View can filter to the calling user's own rows with the closed sentinel `{ "$ctx.user": "id" }`. Three rules apply, each with its own diagnostic:
-
-1. It appears only under `eq`, as a single-key object whose value is the literal string `"id"` — otherwise `VIEW_FILTER_CTX_USER_REF_INVALID`.
-2. The View must require a signed-in user: `ctx.user` in `requires.auth.all` — otherwise `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH`.
-3. The compared field must be the leftmost field of a declared index on the source Schema — otherwise `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX`.
-
-This is a filter, not a row-level policy engine. `requires` authorizes the whole query; it does not inject per-row visibility predicates. Membership, payment and entitlement checks belong in a guard Procedure. See [Procurement approvals](../../examples/builtin-procurement.md).
-
-## Shared response cache
-
-Caller-independent published data may declare `cache: { sharedMaxAge: <seconds> }`, with an integer from 1 through 86400. The Cloudflare adapter applies it only to anonymous REST responses when the Worker also has a stable `cacheScope`. Staff, guarded, identity-bound, SQL and operational-schema Views cannot opt in; MCP and WebMCP calls remain private. Publishing writes purge the deployment-scoped tag after the canonical write.
-
-## Pagination and the envelope
-
-REST callers pass `?page=<1-indexed>&show=<page size>`; MCP callers pass the same two names as tool arguments.
-
-| Knob | Behavior |
-|---|---|
-| `View.spec.limit` | The server-enforced cap. Missing or invalid becomes 50; otherwise the floor of the value, capped at 500. |
-| `show` | Missing, non-numeric or non-positive becomes the cap; otherwise the smaller of the request and the cap. |
-| `page` | Missing, non-numeric or below 1 becomes 1. |
-
-```json
-{ "ok": true, "data": { "rows": [], "page": 1, "show": 20, "hasMore": false } }
-```
-
-`hasMore` is lazy: it is true exactly when `rows.length === show`. There is no `COUNT(*)` and no `LIMIT n+1` probe, so a full final page reports `hasMore: true` and the next request returns an empty list. That is one false positive on the boundary in exchange for no extra round-trip on every request.
-
-Query strings arrive as strings, so the transport boundary coerces each declared param: `string` is identity, `integer` uses `parseInt` and rejects float-like input, `number` uses `Number()`, `boolean` accepts only `"true"` and `"false"`, and an `enum` is matched against its array. A missing required param or a coercion failure is `INPUT_VALIDATION_FAILED` (HTTP 400). Unknown query-string keys are ignored.
-
-## Staff report lists
-
-A staff View may opt into Admin's standard list chrome without changing its REST or MCP contract:
+A View is one SQL `SELECT` in PostgreSQL syntax over declared Schemas.
 
 ```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-orders }
 spec:
-  uiSchema:
-    list:
-      columns: [orderNumber, customerName, orderStatus]
-      searchFields: [orderNumber, customerName, customerEmail]
-      filterFields: [orderStatus]
+  surface: public
+  requires: { auth: { all: [ctx.user] } }
+  sql: |
+    SELECT o.id, o.qty, o.orderStatus, i.name AS item, o.version
+    FROM orders o JOIN items i ON i.id = o.itemId
+    ORDER BY o.created_at DESC
 ```
 
-These names are output field names — SQL aliases for a `sql` View, Schema properties or reserved columns for a `from` View. Admin applies search and exact filters *before* pagination and carries them into `GET /admin/api/views/<name>/export`, whose CSV contains every matching row, not only the visible page. `uiSchema` is staff-only; a public View that declares it is `VIEW_UI_INVALID`.
-
-## The MCP mirror
-
-Every public or staff View is also a tool on its matching MCP surface; internal Views are never tools. The name is the View name lowercased with hyphens replaced by underscores, prefixed `query_view_`. Its input schema is `params.properties` plus `page` and `show`, and it is annotated `readOnlyHint: true`. One executor and one response shape serve REST and MCP, so an agent and a downstream service read exactly the same rows. See [MCP and agents](./mcp-and-agents.md).
-
-## Performance: declare the index the query needs
+## Compiled once, checked at every run
+
+`mantle generate` parses the SQL with PostgreSQL's own parser, refuses what the
+dialect does not support (with the position in the statement), and stores the
+parse tree as the View's IR in the plan. No running service parses SQL. At run time the
+runtime validates the IR against the same allowlist, injects policy, and the
+dialect prints its engine's SQL (SQLite for D1).
+
+What the D1 dialect accepts, in short (the [View reference](../reference/view.md)
+has the full table):
+
+- columns, literals, arithmetic, `CASE`, `COALESCE`, `CAST` (to `int` only for
+  integer literals: use `round(x)`), JSON `->>`;
+- `WHERE` with comparisons, `BETWEEN`, `IN (list | subquery)`, `EXISTS`,
+  `LIKE` (case-insensitive, as in SQLite), `IS DISTINCT FROM`;
+- `INNER` and `LEFT JOIN`, subqueries, `json_each(…)`;
+- `GROUP BY`, `HAVING`, `count`, `sum`, `min`, `max`, `avg`,
+  `json_group_array`, `json_group_object`; `row_number()`, `rank()` and running
+  aggregates;
+- `ORDER BY … NULLS FIRST | LAST`, `LIMIT` (it needs an `ORDER BY`),
+  `DISTINCT`;
+- `now()`, `date_trunc`, `extract`, `ts ± interval '<n> seconds|minutes|hours'`;
+- `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance`.
+
+Refused: `OFFSET` (page with cursors), `RIGHT`/`FULL`/`CROSS JOIN`, any table
+that is not a declared Schema, and SQLite's own clock (`CURRENT_TIMESTAMP`,
+`'now'`).
+
+PostgreSQL is the reference dialect (ADR-0037): on it a View may also use `WITH`
+(recursive too), `UNION` and `DISTINCT ON` inside a `WITH` or subquery,
+`LATERAL`, window frames, `FILTER`, jsonb operators, `ILIKE` and regular
+expressions. D1 refuses them as needing the PostgreSQL dialect. On every
+dialect a View may read an internal View in `FROM`, which is inlined; that is
+how a rule many Views share is written once.
+
+## Policies the runtime injects
+
+Every Schema reference, in `FROM`, joins and subqueries, is replaced by a
+subquery that keeps only visible rows:
+
+- **scope**: on a scoped Schema, a user caller's own rows (an anonymous caller
+  sees none);
+- **TTL**: unexpired rows;
+- **published-only**: on a `public` View, published rows of `publishing`
+  Schemas.
+
+So the join in `my-orders` sees only the caller's orders, and the View never
+says so. A public View that joins a Schema without `publishing` to one with it
+must join them by an explicit condition, or validation refuses it.
+
+## Output names and types
+
+- A column that reads a Schema field unchanged comes back under the field's
+  declared name and type (`o.orderStatus` is `orderStatus`).
+- Anything else keeps its alias. SQL folds unquoted names to lower case, so
+  `count(o.id) AS orderCount` comes back as `ordercount`; write
+  `AS "orderCount"` to keep the case.
+- `*` expands to the declared fields, never the scope field or native columns.
+- The generated `ViewRow_<name>` types each column the same way; an expression
+  is `unknown`.
 
-On SQLite and D1, every Schema is a native table and each top-level property is
-a native column. Declared `indexes` and `uniqueIndexes` become B-tree indexes
-over those columns; Core-compiled projections, filters and ordering reference
-the same columns directly.
-
-Declare the **smallest ordered index justified by the measured path**, and respect SQLite's leftmost-prefix rule. Equality columns go first, the ordered column last. A public declarative View over a publishing Schema always carries `status = published`, so its index leads with `status`: `[status, locale, publishedAt]` serves `WHERE status = ? AND locale = ?`, `… AND publishedAt > ?`, and `… ORDER BY publishedAt`. It does not serve `WHERE publishedAt > ?` alone, and `[publishedAt]` alone does not serve the published list — without planner statistics SQLite prefers the status equality and sorts in a temporary B-tree. If a second hot path needs a different leading field, that is a second index — not a reason to enumerate every permutation, since each index costs storage and slows every write.
-
-```sh
-pnpm exec mantle-harness indexes --require-public --format text
-```
+## Surfaces
 
-The harness applies the real migrations and generated DDL, seeds skewed rows,
-compiles and executes the actual View SQL, and records `EXPLAIN QUERY PLAN`. A
-healthy indexed plan contains `SEARCH <schema-table> USING INDEX`; an indexed
-filter-and-order path should not contain `USE TEMP B-TREE FOR ORDER BY`.
-Findings are advisory unless you opt a View into the gate. Never change
-user-visible filter or ordering semantics just to make the gate pass.
+| `surface` | Served at |
+|---|---|
+| `public` | `GET /api/views/<name>` (REST) and a tool on the public MCP surface (`/mcp`) |
+| `staff` | `GET /admin/api/views/<name>`, with CSV at `/export`, and a tool on the staff MCP surface (`/mcp/staff`) |
+| `internal` | no surface: `ctx.store.view(...)` and `runtime.store` only |
 
-## Example: a public localized list
+`requires` gates every path: an anonymous caller is 401 `UNAUTHENTICATED`, a
+signed-in one who fails a predicate is 403 `AUTH_DENIED`. A staff View still
+needs its own `requires` to limit roles beyond Admin's gate.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: published-announcements
-spec:
-  title: Published announcements
-  surface: public
-  from: announcements
-  cache: { sharedMaxAge: 3600 }
-  params:
-    type: object
-    additionalProperties: false
-    required: [locale]
-    properties:
-      locale: { type: string }
-  fields: [id, slug, locale, title, summary, publishedAt]
-  filter:
-    and:
-      - eq: { field: status, value: published }
-      - eq: { field: locale, value: { $param: locale } }
-      - gte: { field: publishedAt, value: 0 }
-  orderBy:
-    - { field: publishedAt, direction: desc }
-  limit: 50
-```
+## Input and paging
 
-The source Schema declares `indexes: [[status, locale, publishedAt]]`; the `status` predicate is present whether or not the View writes it. The `gte publishedAt 0` clause is what keeps the ordered column inside the indexed range rather than forcing a sort. Omitting `locale` returns 400.
+`input` is a JSON Schema object; the SQL reads `input.<name>`. Over REST the
+properties are query parameters, coerced to their declared types; a missing
+required one is 400 `INPUT_VALIDATION_FAILED`. `limit` and `cursor` are
+reserved names.
 
-## Example: a staff SQL report
+Every surface pages the same way: `limit` (default 50, at most 500) and an
+opaque `cursor`. The response is `{ "rows": [...], "nextCursor": "…" }`, with
+`nextCursor` only when more rows exist. The compiler appends `id` to the
+`ORDER BY` so the order is total. A View's own `LIMIT` caps the whole result.
 
-A `sql` View earns its keep when the answer is not one row per entry. Here an operational `requests` Schema stores a `tags` array, and the report needs one row per tag so staff can search and filter by tag:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: requests-by-tag
-spec:
-  title: Requests by tag
-  surface: staff
-  sql: |
-    SELECT r._mantle_id AS requestId,
-           r.subject AS subject,
-           r.requestStatus AS requestStatus,
-           tag.value AS tag,
-           r._mantle_created_at AS createdAt
-    FROM requests AS r
-    JOIN json_each(r.tags) AS tag
-    WHERE r.requestStatus = :requestStatus
-    ORDER BY r._mantle_created_at DESC
-  params:
-    type: object
-    required: [requestStatus]
-    properties:
-      requestStatus: { type: string, enum: [open, waiting, closed] }
-  uiSchema:
-    list:
-      columns: [subject, tag, requestStatus]
-      searchFields: [subject, tag]
-      filterFields: [tag]
-  limit: 200
-```
+## MCP
 
-`tags` is an array property, so `json_each` unnests it and one request appears once per tag. The runtime wraps the whole statement as a subquery before applying pagination, which is why Admin's search and filters attach to the SQL output aliases — `tag` is a real filterable column even though no Schema property is named `tag`. See [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md) for the same technique over order lines.
+Each View of a surface is a read-only tool named after it in snake case
+(`my-orders` is `my_orders`), whose input is the View's `input` plus `limit`
+and `cursor`. `description` becomes the tool's description. See
+[MCP and agents](./mcp-and-agents.md).
 
-## Source
+## Further reading
 
-- [`docs/adr/0012-views-as-public-rest.md`](../../../docs/adr/0012-views-as-public-rest.md)
-- [`docs/schema-indexes.md`](../../../docs/schema-indexes.md)
-- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
-- [`packages/mantle-runtime/src/domain/service/Pagination.ts`](../../../packages/mantle-runtime/src/domain/service/Pagination.ts)
-- [`packages/mantle-runtime/src/domain/service/ViewParamCoercer.ts`](../../../packages/mantle-runtime/src/domain/service/ViewParamCoercer.ts)
-- [`packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts)
-- [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
-- [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+- [View reference](../reference/view.md)
+- [Query from TypeScript](../guides/typed-queries.md)

package/docs/handbook/examples/hub.md

@@ -1,10 +1,21 @@
 ---
-description: Index of every official Mantle example. Redirects to the Examples hub.
+description: Index of the Mantle 0.2.0 examples — whole services in the v2 grammar, each compiled by mantle generate, and the runnable reference service.
 ---
-# Examples hub
+# Examples
 
-Official examples live in [`docs/examples/README.md`](../../examples/README.md). Pages in this handbook folder are redirects into that hub.
+Each example is a whole service whose manifests compile with `mantle generate`;
+its handlers are written against the generated types. They live beside this
+handbook in [`docs/examples/`](../../examples/README.md).
 
-## Source
-
-- [`docs/examples/README.md`](../../examples/README.md)
+| Example | Shows |
+|---|---|
+| [Reference service](../../examples/reference-service/README.md) | a runnable service with its smoke test: scope, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and sign-in |
+| [Intake form](../../examples/intake.md) | an anonymous form: one SQL `INSERT` and a staff View |
+| [Intake with bot check and notification](../../examples/intake-hooks.md) | a guard and an after hook |
+| [Reservation requests](../../examples/reservation.md) | a request queue with a `check` |
+| [Publication](../../examples/publication.md) | localized posts, per-locale Views and `mantle.search` |
+| [Legal documents and consent](../../examples/legal-documents.md) | immutable revisions and a conditional insert |
+| [Procurement approvals](../../examples/procurement.md) | own rows through `auth.uid()`, a locked staff review |
+| [Commerce catalog and orders](../../examples/commerce.md) | a published catalog and guest orders |
+| [Commerce inventory](../../examples/commerce-inventory.md) | atomic stock reservation, a scheduled expiry, a verified payment callback |
+| [Guarded API access](../../examples/guarded-api.md) | API keys, scopes and an entitlement guard |

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

@@ -1,63 +1,57 @@
 ---
-description: How Schema, View, Procedure, Trigger and uiSchema become Admin forms, lists, navigation and actions, with a complete customization example.
+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 the Admin console
-
-Many Admin changes are manifest edits: labels, multiline inputs, operational
-list columns and tabs, reports and action placement. Admin API derives
-metadata from the compiled plan; the prebuilt SPA renders it. The host must
-already mount Admin API, authentication and Admin assets — see the
-[local Admin tutorial](../start/quickstart-admin.md).
-
-## Manifest to rendered UI
-
-| User request | Author this | What Admin renders / constraints |
+# 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.
+
+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`.
+
+## Manifest to Admin
+
+| You want | Author this | Effect and limits |
 |---|---|---|
-| Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` | Localized labels and help. Property names and stored values stay unchanged. |
-| Make a field required or an option list | JSON Schema `required`, `enum`, `type` | Required marker and type-derived control; enums become selects. These are data contracts, not styling flags. |
-| Make a string multiline | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | Textarea for a top-level string field. `textarea` is the only supported explicit widget. |
-| Edit Markdown or HTML | Property `x-mcp-hint: markdown` or `html` | Rich editor; these hints take precedence over `widget: textarea`. `richtext` currently uses a textarea. |
-| Edit a timestamp or show money | `format: date-time` on a string; `x-mcp-hint: timestamp-ms` or `money-minor` on a number | Date/time controls or number preview. Money uses minor units divided by 100 and a sibling `currency` when present. |
-| Reorder an operational record list | Schema `uiSchema.list.primaryField`, `.columns` | Linked leading data field, then ordered columns. Native columns such as `status` and `createdAt` are allowed in `columns`; `primaryField` must be a scalar data property. |
-| Add business-state tabs | Schema `uiSchema.list.filterField` | Operational-only enum tabs/sidebar links. Field needs a string enum and a left-prefix index. |
-| Search record contents | Schema `searchableFields` | Searches declared string fields plus entry id. This is substring search, not an index declaration. |
-| Show related records | Required property `x-mantle-ref` | Eligible child collections fold into the parent's workbench; translation children use language tabs. |
-| Also show a folded child in navigation | Schema `uiSchema.nav.standalone: true`, optional `parentField` | Adds its own list with parent filter, retaining the folded view. Multiple eligible parent refs require `parentField`; not allowed on translation children. |
-| Add a read-only report and CSV | View `surface: staff`, `title`, `uiSchema.list` | Report navigation; `columns`, `searchFields`, `filterFields` use output names. Server filters before pagination; CSV includes all matches. |
-| Add a list-level action | Eligible Procedure `uiSchema.collectionAction: <schema>` | Collection action with a form generated from Procedure `input`. |
-| Add a row action | Eligible Procedure input property `x-mantle-ref: <schema>` | Row operation with prefilled reference. Selection uses a same-name Schema property, then a sole single-field unique index, otherwise entry `id`. |
-| Make generic content editing read-only | Schema root `schema.readOnly: true` | Generic authoring writes are blocked; declared Procedures remain available. A disabled field is not an authorization rule. |
-
-The data editor also handles booleans, numbers, objects and arrays from JSON
-Schema. Bound fields (`x-mantle-bind`) display read-only because Runtime owns
-the value. Media controls depend on the supported media schema and host media
-policy; `uiSchema` alone cannot enable uploads.
+| 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 explicit widget |
+| 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 |
 
 Schema list presentation (`primaryField`, `columns`, `filterField`) is for
-`lifecycle: operational`. Publishing collections keep the built-in publishing
-workflow. For an alternate publishing table, define a staff View report.
+`lifecycle: operational`. Publishing Schemas keep the draft, publish and
+archive workflow (`POST /admin/api/entries/{id}/publish` and `/unpublish`).
 
 ## Example: an operational inbox
 
-This complete source configures a collection and a separate staff report.
-The collection filters by `ticketState`, not Mantle's native publishing status.
-
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
+apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
-metadata:
-  name: support-tickets
+metadata: { name: support-tickets }
 spec:
   title: { en: Support tickets, zh-TW: 客服工單 }
   lifecycle: operational
-  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] }
   indexes: [[ticketState]]
   searchableFields: [subject, details]
   uiSchema:
@@ -67,69 +61,80 @@ spec:
       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/v1
+apiVersion: cms.mantle.aotter.net/v2
 kind: View
-metadata:
-  name: support-report
+metadata: { name: support-report }
 spec:
   title: Support report
   surface: staff
-  from: support-tickets
-  fields: [id, subject, ticketState, createdAt]
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
   uiSchema:
     list:
-      columns: [subject, ticketState, createdAt]
+      columns: [subject, ticketState, created_at]
       searchFields: [subject]
       filterFields: [ticketState]
+  sql: SELECT id, subject, ticketState, created_at FROM "support-tickets" ORDER BY created_at DESC
 ```
 
-The collection shows Subject first, State and Created at next, state tabs,
-and a multiline Details editor. The report is a separate navigation entry
-with its own search/filter configuration and CSV export. Schema `.list` and
-View `.list` are different contracts; do not copy their keys between atoms.
-
-## When a Procedure becomes a button
-
-`uiSchema.collectionAction` alone does not expose a Procedure. Admin discovers
-staff operations from either a staff MCP Trigger or an HTTP Trigger whose
-Procedure requires `ctx.staff`. Runtime rechecks Procedure `requires` on
-execution. Use the [Procedure reference](../reference/procedure.md#uischema)
-for a complete action declaration.
-
-An eligible operation with row bindings appears on those records. One with
-`collectionAction` appears on that collection's list. Operations without either
-appear in the standalone Operations screen. Row mutations use the observed
-entry version for optimistic concurrency where the Procedure contract declares
-`expectedVersion`; keep its input contract intact when adjusting presentation.
+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`.
 
 ## Verify a change
 
-1. Edit the application manifests, then run `mantle validate`, `mantle generate`
-   and `mantle generate --check` through the local package manager.
-2. Restart/reload the host so Admin receives the new compiled plan. Check
-   `/admin/api/collections`, `/admin/api/views-manifest` or
-   `/admin/api/operations` in an authenticated session if the UI seems stale.
-3. Open the affected list and editor: check labels, actual columns, filters,
-   form values and keyboard access. Verify a record after saving, and verify
-   report filters in CSV as well as the visible page.
-
-`uiSchema` roots and supported nested keys are closed. Schema accepts `fields`,
-`list`, `nav`; Procedure accepts `collectionAction`, `fields`; staff View accepts
-`list`. They do not accept a custom layout, CSS, React component, arbitrary
-widget name or permission policy. See [Schema](../reference/schema.md#uischema),
-[View](../reference/view.md#uischemalist) and [Procedure](../reference/procedure.md#uischema).
-
-For a new layout or unsupported widget, use application-owned UI against the
-appropriate APIs or propose a change to the Admin UI package. Do not patch
-`public/_mantle/admin/`: generation replaces those prebuilt assets. Visitor
-frontend styles and the `theme` skill's site changes do not style Admin.
+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
 
-- [Admin UI contract validation](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [Admin metadata and operation discovery](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [Entry form renderer](../../../packages/mantle-admin-ui/src/features/content/entry-edit-view.tsx)
-- [Collection renderer](../../../packages/mantle-admin-ui/src/features/content/collection-view.tsx)
-- [Action renderer](../../../packages/mantle-admin-ui/src/features/content/row-operations.tsx)
-- [Navigation rules](../../../packages/mantle-admin-ui/src/lib/collection-nav.ts)
+- [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