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

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -1,198 +1,30 @@
 ---
-description: How createMantle boots the runtime from a storage adapter, how storage converges to the plan, the D1 and PostgreSQL dialects, and the fingerprint handshake.
+description: Native execution, database handles, two SQL dialects and application-owned migrations.
 ---
-# Runtime, Store and dialects
+# Runtime and databases
 
-```
-src/index.ts (host entry) ─▶ mantle = createMantle(service, { plan, storage, schedules })
-                                 │ first request: createMantleRuntime → storage.prepare(plan)
-                                 ▼
-service.fetch(request, env, { runtime, waitUntil })
-  └ surfaces / your routes ─▶ runtime.invokeProcedure · runtime.store
-                                 └ Store: policy rewrite → dialect check → StoreExecutor
-```
+`mantle generate` compiles manifest SQL and row policy into ordinary TypeScript and SQL. Generated Views and Procedures call the target's native driver. The app owns routing, authentication, handles, connection lifetime and deployment. Import only the operations and surfaces you use.
 
-## `createMantle`
+## Schema installation and migrations
 
-```ts
-createMantle(service, { plan, storage: (env) => MantleStorageAdapter, schedules?, expectedFingerprint? })
-// → { fetch(request, env, ctx?), invokeSchedule(cron, scheduledTime, env, ctx?), runDeferredHook(message, env, ctx?) }
-// runDeferredHook replays an after-hook Invocation from your own queue; nothing in Mantle emits one
-```
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
-- `service` is `{ handlers, fetch(request, env, { runtime, waitUntil }) }`, a
-  WinterTC fetch the application owns. Mantle owns no route of its own: the
-  service decides what is mounted where.
-- The runtime boots lazily on the first call, once per isolate. A failed boot
-  is retried by the next request.
-- Each entry call binds its own `ctx.waitUntil` to the runtime facade handed
-  to the service. Handler calls, nested invocations and Store lifecycle hooks
-  retain work on that entry's context, including concurrent requests. Calls
-  without a context do not borrow another request's retainer.
-- `invokeSchedule` runs every enabled schedule Trigger whose cron is exactly
-  the given POSIX expression, as the system caller.
-- The host entry is a few lines the generator writes once
-  ([The service and its entry](../cloudflare/service-entry.md)); Core handles
-  no platform event types.
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-`createMantleRuntime(args)` is the same boot without the service, for tests
-and custom hosts. The runtime exposes `plan`, `store`, `invokeProcedure`,
-`bootReport()` (`{ fingerprint, coreVersion }`) and, with site defaults,
-`site`.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
 
-## Boot checks
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
-Boot refuses to serve when:
+## Drivers and dialects
 
-- a plan `ref` has no handler (`HANDLER_NOT_REGISTERED`), or a handler is not
-  in the plan (`HANDLER_NOT_DECLARED`);
-- the plan was compiled for another dialect, or does not match
-  `expectedFingerprint` (`PLAN_FINGERPRINT_MISMATCH`);
-- an enabled schedule exists without `schedules: true` (`SCHEDULE_NOT_WIRED`);
-- storage has a change it cannot make (`STORAGE_CHANGE_BLOCKED`), or a table
-  Mantle would create already exists without being Mantle's
-  (`STORAGE_TABLE_NOT_OWNED`).
+The driver layer is open: handles are structural contracts, not a registration API. PostgreSQL needs `unsafe(text, values)` and `begin(options, fn)` from `@aotter/mantle/contracts`; SQLite uses D1's prepare/bind/all/batch shape or bun:sqlite's query/transaction shape. Bun.SQL and postgres.js fit directly. See [adapting a driver](../guides/postgres-adapters.md).
 
-## Storage converges to the plan
+Users may supply anything that executes the emitted SQL, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle promises behavior only on supported drivers: bun:sqlite, D1, Bun.SQL and postgres.js. A structural match alone does not prove transaction, result or error semantics.
 
-There are no migration files for Schema tables. When the plan's fingerprint
-differs from the one the database last booted, boot reads the database's
-actual tables and indexes, compares them with the plan, and:
+The dialect layer is closed in 0.2.0: exactly `postgres` and `sqlite`, selected by the generation target. SQL is rendered at generation time. A third engine requires forking the compiler and Store runtime; it is not a dialect plugin.
 
-| Difference | Boot |
-|---|---|
-| a missing table, field column, index, or unique index that builds | creates it (on SQLite, `STRICT` tables with their check and FTS triggers) |
-| a unique index that fails on existing rows, a column with another type, a changed index, a missing native column | refuses with `STORAGE_CHANGE_BLOCKED`, naming the change and a SQL hint |
-| a column or non-unique index the plan no longer declares | keeps it and warns; nothing is ever dropped |
+## Store and queries
 
-A renamed field is a new empty column beside the old one: copy the data
-yourself. A blocked change is the author's to make (SQL through the host's own
-tool, a data-copy Procedure, a dedupe), then boot checks again. With the same
-fingerprint boot reads nothing. `mantle generate --check --database <file>`
-prints the same diff against a local database without applying it.
+Use the [Store for writes and simple lookups, internal Views for richer reads](../guides/typed-queries.md). Store metadata initializes once on first `store()` use without SQL. Each call binds a fresh handle, verified Caller and handlers; never reuse a caller-bound Store across requests.
 
-Mantle's own tables (`_mantle_*`) and its product tables (`site_config`,
-`media_assets`, `pending_media_uploads`) keep versioned migrations of their
-own. Identity `mantle` migrates Better Auth's tables through Better Auth.
-
-## The D1 dialect
-
-The SQL language is PostgreSQL syntax, pinned to PostgreSQL 18's parser. A
-**dialect** decides which of it an engine runs and how. The built-in dialect,
-`@aotter/mantle/d1`, runs on SQLite as D1 does: its compile side refuses what
-D1 cannot compute exactly, and its runtime side prints SQLite, encodes types
-and converges storage.
-
-- `date-time` (and `created_at` / `updated_at`) is stored as microseconds,
-  `date` as days, `numeric(p, s)` as an integer of the smallest unit, so
-  arithmetic is exact on D1. On the wire a date-time is an ISO string.
-- `checks` are enforced by triggers. `x-mantle-ref` is checked by
-  `mantle generate` and used by Admin; storage does not enforce it in 0.2.0.
-  `searchableFields` uses
-  an FTS5 trigram index; `format: geo` uses an R*Tree.
-- `date_trunc` and `extract` compute in the site time zone
-  (`d1Storage(db, { timeZone })`, default UTC).
-
-`mantle.config.json` names the dialect (`sqlite`, `postgres`, or another dialect package, which must pass
-`runStorageConformance` from `@aotter/mantle/testing`). A plan records its
-dialect, and boot refuses a plan compiled for another one.
-
-## The PostgreSQL dialect
-
-`"dialect": "postgres"` in `mantle.config.json` compiles the plan for
-PostgreSQL (13 or later). On Cloudflare, `mantle generate --dialect postgres`
-writes the preset over Hyperdrive; on any other platform, add `"host": "none"`
-and compose `createMantle` with `postgresStorage` yourself (ADR-0036). PostgreSQL
-is Mantle SQL's reference dialect (ADR-0037): it accepts D1's subset without
-SQLite's own `typeof`, `hex`, `json_extract`, `json_set`, `json_insert` and
-`json_remove` (write `x ->> '$.path'`), plus `WITH`, set operations, `LATERAL`,
-window frames, `FILTER`, jsonb operators and the rest of the
-[View reference](../reference/view.md)'s PostgreSQL table. A manifest that uses
-them no longer compiles for D1; one that does not moves between engines with a
-recompile.
-
-- Columns have native types: `timestamptz`, `date`, `numeric(p, s)`, `boolean`,
-  `jsonb`, `bigint` and `double precision`. Values are decoded by the type
-  PostgreSQL reports, so computed outputs (`now()`, `date_trunc`, a `CAST`) come
-  back as wire values too: ISO date-times, booleans, parsed JSON.
-- Every write batch is one `SERIALIZABLE` transaction, retried on a
-  serialization failure, so a guard such as `WHERE NOT EXISTS` holds under
-  concurrent writers as it does on SQLite's single writer.
-- `checks` are `CHECK` constraints added `NOT VALID`: they bind every later
-  write and leave older rows alone, like D1's triggers.
-- `json_each`, `->>` and `CAST(x AS bool)` read as they do on D1 through small
-  SQL functions Mantle creates (`_mantle_json_each`, `_mantle_jget`,
-  `_mantle_bool`). `json_group_array` and `json_group_object` order by value.
-- Results match D1 where Mantle decides them. Text columns use `COLLATE "C"`,
-  so they compare by code point. An `ORDER BY` key without `NULLS FIRST/LAST`
-  puts NULL first ascending, as Core pages every View. Values never depend on
-  the server's `DateStyle`, `IntervalStyle` or `TimeZone`. Elsewhere the meaning
-  is PostgreSQL's, where D1 differs:
-  - `LIKE` is case-sensitive.
-  - Division by zero is an error.
-  - `->>` returns text.
-  - `||` prints booleans and floats as PostgreSQL does.
-- `searchableFields` and `mantle.near()` scan without an index in 0.2.0, and
-  `mantle.search_rank()` counts occurrences rather than computing bm25.
-  Site settings and media are SQLite-only (D1, bun:sqlite).
-- `date_trunc` and `extract` compute in the site time zone
-  (`postgresStorage({ connect, timeZone })`, default UTC).
-- Every statement has a `statement_timeout` of 10 seconds, pinned in each
-  transaction (`statementTimeoutMs`; 0 is none). Storage convergence has none.
-  A statement past it fails with `RESOURCE_UNAVAILABLE` and writes nothing.
-- Connect as a role that owns the service's tables but is not a superuser and
-  holds no file or server privilege (`pg_read_server_files`,
-  `pg_execute_server_program`). Mantle's allowlist refuses such functions; the
-  role is the second line.
-
-## Storage adapters
-
-| Adapter | From | Driver |
-|---|---|---|
-| `d1Storage(env.DB, { timeZone?, site? })` | `@aotter/mantle/cloudflare` | Cloudflare D1, the one the preset uses |
-| `sqliteStorage(driver, { timeZone?, maxBindings?, site?, restrict? })` | `@aotter/mantle/d1` | any `DatabaseDriver`: `{ batch(statements) }`, all or nothing |
-| `postgresStorage({ connect, timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/postgres` | `connect` opens one node-postgres (`pg`) client; Hyperdrive on Workers |
-| `bunPostgresStorage(sql, { timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/bun` | a Bun.SQL pool with `prepare: false`; its role needs TEMPORARY (ADR-0038) |
-| `bunSqliteStorage(db, { timeZone?, site?, restrict? })` | `@aotter/mantle/bun` | a bun:sqlite `Database`; foreign keys are turned on |
-
-`restrict(plan, context)` returns refusals of its own, run after the dialect's
-on every program at runtime. It only narrows what runs, for an operator that
-runs other people's plans; a self-hosted service leaves it out (ADR-0037).
-
-On Workers, PostgreSQL goes through Hyperdrive, which pools the connections, so
-`connect` opens a client per operation (a socket must not outlive its request):
-
-```ts
-import pg from "pg";
-import { pgDatabaseDriver, pgPool, postgresStorage } from "@aotter/mantle/postgres";
-
-const connect = (env: Env) => async () => {
-  const client = new pg.Client({ connectionString: env.HYPERDRIVE.connectionString });
-  await client.connect();
-  return client;
-};
-// storage: (env) => postgresStorage({ connect: connect(env) })
-// identity: createMantleAuth({ database: pgPool(connect(env)), driver: pgDatabaseDriver(connect(env)), ... })
-```
-
-The Worker needs `compatibility_flags: ["nodejs_compat"]` for `pg`. Mantle runs
-every read in a transaction, which Hyperdrive never answers from its cache.
-Better Auth's reads (sessions, roles) do not, so create the Hyperdrive config
-with caching disabled (`wrangler hyperdrive create … --caching-disabled`), or a
-revoked session can be accepted until the cache expires. `timeZone` must be an
-IANA name: PostgreSQL reads an offset such as `+08:00` with the opposite sign.
-
-Bun has a generated preset for both engines (`mantle generate --host bun`,
-ADR-0038); `bunDatabaseDriver` / `bunAuthDatabase` and `bunSqliteDriver` give
-Better Auth the same store. A `DatabaseDriver` is one method, so another engine
-(libSQL, for example) is a few lines of application code on `host: none`: the
-entry calls `createMantle` and its own server.
-
-`site` turns on the site capability (site settings and media); see
-[Site defaults and site_config](../reference/site-config.md).
-
-## Testing a service
-
-Run the service under `wrangler dev` against a fresh local D1 and drive it over
-HTTP, as the [reference service](../../examples/reference-service/README.md)'s
-`smoke.mjs` does.
+[Native execution](../guides/native-execution.md) defines input ownership, native result values, atomicity and uncertain write outcomes.

package/docs/handbook/concepts/views.md

@@ -1,116 +1,17 @@
----
-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
 
-A View is one SQL `SELECT` in PostgreSQL syntax over declared Schemas.
+A View declares one PostgreSQL-syntax SELECT over declared Schemas or reusable internal Views. Generation parses, checks and lowers it for postgres or sqlite, adds row policy, and emits a typed function. Requests bind values and execute SQL; they do not parse or compile manifests.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: my-orders }
-spec:
-  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
-```
+Use internal Views for joins, aggregates, OR and reusable reads. Simple handler id lookups and AND filters can use Store. See [query from TypeScript](../guides/typed-queries.md) for a complete example.
 
-## Compiled once, checked at every run
+| Surface | Exposure when mounted |
+| --- | --- |
+| public | REST `/api/views/<name>` and public MCP |
+| admin | Admin View API and admin MCP |
+| internal | Generated operation only; no public route/tool |
 
-`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).
+Every generated invocation retains its `requires`. SQL row policy limits scope, TTL and publishing visibility at every relation. The app supplies a verified Caller.
 
-What the D1 dialect accepts, in short (the [View reference](../reference/view.md)
-has the full table):
+Bare Views return native row arrays. Declared date/date-time columns are formatted by SQL; other values retain driver behavior. Proved pageable Views also get `paged/views/<encoded-name>.ts`, returning `{ rows, nextCursor? }`. Internal paging creates no exposure. Keyset paging requires generate-time order/cardinality proofs; it does not avoid the source scan for an aggregate. Inspect native EXPLAIN and indexes.
 
-- 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`.
-
-## Surfaces
-
-| `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 |
-
-`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.
-
-## Input and paging
-
-`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.
-
-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.
-
-## MCP
-
-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).
-
-## Further reading
-
-- [View reference](../reference/view.md)
-- [Query from TypeScript](../guides/typed-queries.md)
+See the [View reference](../reference/view.md), [surface contracts](../reference/surface.md) and [native value contract](../guides/native-execution.md).

package/docs/handbook/examples/hub.md

@@ -1,21 +1,5 @@
----
-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
 
-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).
+Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-| 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 |
+The runnable [reference service](https://github.com/aotter/mantle/blob/develop/docs/examples/reference-service/README.md) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/adapter-guide.md

@@ -0,0 +1,11 @@
+# Another host or database handle
+
+Mantle has an open driver boundary and exactly two closed dialects in 0.2.0, postgres and sqlite. Choose the generation target whose emitted SQL and handle calls match your host. The app owns its router, resources, lifetime and scheduler.
+
+PostgreSQL's `Postgres` in `kernel/contracts.ts` needs `unsafe(text, values)` and `begin(options, fn)`. Bun.SQL and postgres.js fit without wrappers. [The node-postgres example](postgres-adapters.md) shows the transaction and result-count contract. SQLite handle contracts are exported by `@aotter/mantle/driver/d1` and `/driver/bun-sqlite`: D1 prepare/bind/all/batch, or SQLite query/exec/transaction. Reads may need only the narrower reader shape.
+
+A third-party driver must preserve result, binding, atomicity and uncertain-outcome semantics. A handle that cannot transact must reject before invoking the callback. Never emulate an atomic Procedure with unrelated autocommit HTTP calls.
+
+Users may choose another SQL executor, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle supports bun:sqlite, D1, Bun.SQL and postgres.js; there is no bundled Durable Object adapter. The app owns any custom adapter and its tests. A third SQL engine requires forking the compiler and Store runtime, not installing a dialect plugin.
+
+No runtime performs DDL, introspection or schema checks. Install initial SQL and rehearse migrations explicitly; see [database ownership](../concepts/runtime-and-adapters.md).

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

@@ -0,0 +1,20 @@
+# Extend Admin
+
+Native Admin accepts app-owned extension declarations, executable server handlers and optional same-origin client modules. Import client `defineAdminExtension` from `@aotter/mantle-admin/extension` and UI primitives from `@aotter/mantle-ui/kit`. Server types live in `@aotter/mantle-admin/server`.
+
+| Contribution | Placement |
+| --- | --- |
+| pages/settings | Extension page; settings forms are generated from the supported form subset |
+| actions | record, list selection or list toolbar |
+| panels | record sidebar or home |
+| fields | field input or cell |
+
+Admin contributions sit behind the admin-layer gate; optional field roles default to `admin`. Server authorization is checked on every route. Handlers own finer business permissions.
+
+Pass full declarations to `mantle generate … --admin --admin-extensions <module>` (named/default `adminExtensions` array). Generation checks contributions, manifest uiSchema references and settings schemas, then emits `extensionMetadata` and compiled `extensionBindings` in `admin-extensions.ts`. Bind the same runtime definitions with `extensionBindings(adminExtensions)` and merge its extensions/routes into `admin()` options. Drift is refused before execution.
+
+Serve each `module` at a same-origin absolute path and install its integrity in the host shell's import map. Native Admin does not serve `source` modules or inject integrity; generation rejects source. Share React and the UI kit via the built import map, rather than bundling a second React. Canonical Admin refuses framing; use its separate same-origin preview contract.
+
+Raw API handlers receive the original Request. Declared `bodyLimit` checks Content-Length before DB access, but the app must bound unknown-length streams. Built-in JSON routes use the shared bounded reader after caller/origin checks. Do not lose exact OCC or uncertain-outcome handling in custom actions.
+
+See [native Admin](native-admin.md) for mounting and acceptance and [generated descriptors](../reference/admin-descriptors.md) for build-time metadata.

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

@@ -1,169 +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 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 |
+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.