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

package/docs/handbook/start/project-and-cli.md

@@ -1,158 +1,57 @@
 ---
-description: The files of a Mantle 0.2.0 project, who owns each, mantle.config.json, and every option of mantle generate.
+description: Generation targets, CLI options and ownership of native application files.
 ---
 # Project layout and CLI
 
-## Files
+| File | Owner |
+| --- | --- |
+| `manifests/*.yaml` | App: closed v2 declarations and SQL |
+| `src/worker.ts`, auth, handlers, frontend | App: routing, Caller verification and side effects |
+| `generated/` | Generator: TypeScript, native SQL and selected bindings |
+| `migrations/` | App's agent and native migration tool |
+| `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
+| `dist/` | Disposable bundle output; do not commit |
 
-| Path | Written by | Owner |
-|---|---|---|
-| `manifests/*.yaml` | you | you |
-| `mantle.config.json` | `mantle generate`, when the selection changes | you may edit it; generate keeps keys it does not know |
-| `.mantle/generated/plan.json` | every `mantle generate` | generated: never edit, commit it |
-| `.mantle/generated/mantle.ts` | every `mantle generate` | generated: never edit, commit it |
-| `src/service.ts`, `src/index.ts`, `src/handlers.ts`, `src/identity.ts` (identity `custom`) | the first `mantle generate` | yours from then on |
-| `wrangler.jsonc` (Cloudflare, unless a `wrangler.json` or `wrangler.toml` exists), `tsconfig.json`, `.dev.vars.example` (Cloudflare, identity `mantle`) or `.env.example` (Bun), `.gitignore` | the first `mantle generate`, each only if missing | yours |
-
-`mantle generate` writes each preset file only when it does not exist, and
-writes none once `src/service.ts` exists: from then on the application owns
-its composition. To get a fresh preset, move the old file aside and rerun.
-
-- `plan.json` is `{ "sourceHash": …, "plan": … }`: the sealed `RuntimePlan`
-  and the SHA-256 of the manifest sources. The plan's `fingerprint` is what
-  boot checks; reformatting a manifest changes `sourceHash` but not the
-  fingerprint.
-- `mantle.ts` exports `plan`, `sourceHash`, the `Mantle` namespace of row, input and output
-  types, `Store` and `CallerStore` typed over your Schemas and
-  Views, and `MantleHandlers`, which lists exactly the plan's `ref` handlers. A
-  missing or extra handler is a type error. See
-  [Query from TypeScript](../guides/typed-queries.md).
-
-## `mantle.config.json`
-
-```json
-{ "version": 2, "identity": "mantle", "features": ["mcp", "admin", "web"] }
-```
-
-| Key | Values | Meaning |
-|---|---|---|
-| `version` | `2` | `1` (a 0.1.x config) fails with exit 2 |
-| `identity` | `mantle`, `custom`, `none` | who the callers are. `mantle`: `@aotter/mantle/auth` (Better Auth sign-in, staff roles, OAuth for MCP). `custom`: your `src/identity.ts` maps your own sessions to callers. `none`: every caller is anonymous |
-| `features` | a subset of `mcp`, `admin`, `web`, in that order | `mcp`: the public MCP surface at `/mcp` (and staff MCP inside Admin). `admin`: the Admin console and its API at `/admin`, which needs an identity. `web`: reserved for public pages; REST at `/api` is always mounted |
-| `host` | `cloudflare`, `bun`, `none`, optional | where the service runs (ADR-0036); absent is `cloudflare`. `none` writes no preset: only the plan and its types, and your code calls `createMantle`. The host never enters the plan |
-| `dialect` | `sqlite` (alias `d1`), `postgres`, or a dialect package name, optional | the SQL engine; absent is `sqlite`, which runs on D1. `postgres` runs on PostgreSQL, through Hyperdrive on Cloudflare. The plan records the dialect (the SQLite dialect as `@aotter/mantle/d1`) |
-
-Without a config or flags, the selection is identity `mantle` and every
-feature. An explicit `--features` without `--identity` means identity `none`.
-A rerun keeps the saved identity, host and dialect; asking for another one is
-refused (exit 2), so switching never drops tables or orphans data. Change
-`mantle.config.json` deliberately once the data is moved.
-
-| | `cloudflare` | `bun` | `none` |
-|---|---|---|---|
-| `sqlite` | preset over D1 (the default) | native bun:sqlite | plan and types only |
-| `postgres` | preset over Hyperdrive and `pg` | native Bun.SQL PostgreSQL pool | plan and types only |
-| a dialect package | plan and types only; compose `src/service.ts` with its storage adapter | plan and types only | plan and types only |
-
-Each selection needs packages in the project. `mantle generate` checks them
-and stops before writing anything, naming the install command for your
-package manager. It never installs anything. The host and dialect rows, and the
-staff MCP App, are checked only while the preset is still to be written.
-
-Use the versions in the installed Core's `package.json` `peerDependencies`,
-not registry latest, for optional auth and MCP packages. The diagnostic's
-install command includes those versions and incompatible installed peers are
-refused before generation. Keep `@aotter/mantle-ui` at Core's
-exact version. A package manager accepting an incompatible peer does not make
-it a supported combination; inspect peer warnings before starting the service.
-
-| Selection | Packages |
-|---|---|
-| always | `@aotter/mantle` |
-| identity `mantle` | `better-auth`, `@better-auth/oauth-provider`, `@better-auth/mcp`, `@better-auth/cimd` |
-| feature `mcp` | `@modelcontextprotocol/server`, `@modelcontextprotocol/ext-apps` |
-| feature `admin` | `@aotter/mantle-ui` (its `dist/admin` is the console, bound as `ASSETS` in `wrangler.jsonc`) |
-| dialect `postgres` on `cloudflare` | `pg` |
-| host `bun` | `bun-types` |
-| feature `mcp` with an identity, without `admin` | `@aotter/mantle-ui` (the staff MCP App) |
-
-On Cloudflare the project also installs `wrangler`, `@cloudflare/workers-types` and
-`@types/node` itself. A TypeScript Cloudflare/PostgreSQL project also installs
-`@types/pg` as a dev dependency for the generated `pg` import.
-
-## `mantle generate`
+## Commands
 
 ```sh
-mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]
-mantle generate --check [--database <file>]
+mantle generate <target> <output-directory> <manifest>... [options]
+mantle bundle <entry> <outdir>
 ```
 
-| Option | Meaning |
-|---|---|
-| `--manifests <dir>` | the manifest directory, default `./manifests`. Every `.yaml` and `.yml` file directly in it is read |
-| `--features <list>` | comma-separated, a positive list. A missing dependency fails with `GENERATE_FEATURE_DEPENDENCY_MISSING`; an omitted feature is never added back |
-| `--identity <kind>` | `mantle`, `custom` or `none` |
-| `--host <host>` | `cloudflare`, `bun` or `none`, chosen on the first run. `bun` defaults the dialect to `postgres` |
-| `--dialect <name>` | `sqlite` (alias `d1`), `postgres` or a dialect package, chosen on the first run |
-| `--check` | writes nothing. Exits 1 when `plan.json`, `mantle.ts` or `mantle.config.json` differs from what generate would write, or a package is missing |
-| `--database <file>` | with `--check`: also read a local SQLite file (Wrangler's local D1 is under `.wrangler/state/v3/d1/`) read-only, and print the SQL storage convergence would run |
-
-Exit codes: 0 success, 1 a diagnostic or a stale file, 2 a usage or file
-error. Diagnostics name the manifest file, the path in it and, for SQL, the
-position in the statement.
-
-`--check` is the gate for CI and for agents: run `mantle generate`, then
-`mantle generate --check`, then your typecheck.
-
-### Schedules and Cloudflare crons
-
-On host `cloudflare`, schedule Triggers use POSIX cron. `mantle generate` translates each enabled
-one with `toCloudflareCron` and refuses (exit 1, before writing) one that
-Cloudflare cannot run the same way. It writes `triggers.crons` into a new
-`wrangler.jsonc`; once the file is yours it only warns when the crons differ
-from the plan, and you update them.
+| Target | Dialect | Handle |
+| --- | --- | --- |
+| `bun-sqlite` | sqlite | bun:sqlite Database |
+| `bun-postgres` | postgres | Bun.SQL |
+| `cloudflare-d1` | sqlite | D1 binding/session |
+| `cloudflare-postgres` | postgres | postgres.js, usually with Hyperdrive |
 
-### Storage SQL
+Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.0.
 
-Boot creates what the plan adds (tables, columns, indexes, check triggers) and
-refuses what it cannot change safely. `--check --database` prints the same
-diff without applying it, for the `sqlite` dialect; see [Deploy and operate](../cloudflare/deploy-and-operate.md).
-
-### PostgreSQL on Cloudflare
-
-`mantle generate --dialect postgres` writes the same preset over Hyperdrive:
-`src/service.ts` opens a `pg` client per operation from `env.HYPERDRIVE`, and
-`wrangler.jsonc` binds `HYPERDRIVE` with a placeholder id and a
-`localConnectionString` for `wrangler dev`. Before deploying, create the config
-with caching off and put its id in place of the placeholder; generate warns
-until you do:
+| Option | Meaning |
+| --- | --- |
+| `--check` | Compare generated owned files and Wrangler build keys without writing; stale output exits nonzero. No database or credentials are needed. |
+| `--admin` | Emit native Admin bindings and `admin/*` modules; install the separate Admin package. |
+| `--auth <module>` | Read plain `authOptions(env)` (or an exported auth instance's options) and append selected Better Auth DDL. Repeat it once per Better Auth instance. Prefer plain options without initialization side effects. |
+| `--site <module>` | Read `siteDefaults`; emit site/media bindings and deployment SQL. |
+| `--admin-extensions <module>` | Read the named/default `adminExtensions` array and the optional `navGroups` (sidebar groups; see native-admin.md "Sidebar"). The app shell passes `src/admin.ts`. |
+| `--wrangler <path>` | Existing JSONC/JSON/TOML config; default finds one or creates `wrangler.jsonc`. TOML receives manual-edit instructions. |
+| `--entry <path>` | Worker source entry; default `src/worker.ts`. |
+| `--outdir <path>` | Split bundle output; default `dist`. Keep separate from source/generated files. |
 
-```sh
-wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
-```
+## Outputs
 
-## 0.1.x projects
+`generated/.mantle-inputs.json` records the Mantle version and a hash of every input the run read (manifests and the
+`--auth`, `--site`, `--admin-extensions` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
+deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
+Commit it with the other generated files.
+The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
+through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 
-`apiVersion: cms.mantle.aotter.net/v1` manifests, a `version: 1` config, `mantle validate`,
-`mantle emit-openapi`, `mantle skills` and the `mantle-harness` bin are gone.
-`docs/upgrade-0.1-to-0.2.md` in the installed package is the guide.
+`generated.ts` exports typed queries and Store. Direct `views/<encoded-name>.ts` and `procedures/<encoded-name>.ts` entries export an operation and its types. Proved pageable Views also have `paged/views/*`; boundary checks live in `validation/*`. `admin-descriptors.ts`, `rest.ts` and `web.ts` are always emitted. Manifest exposure selects `mcp.ts`; `admin-bindings.ts` and `admin/*` require `--admin`. Auth and site are explicit options.
 
-## Bun
+Apply `schema.sql` only to an empty database. Later changes require [explicit migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations); generation and runtime do not inspect the database. Ref declarations print the `Handlers` keys to implement.
 
-`mantle generate --host bun` selects PostgreSQL on first run. Install `bun-types`
-for the generated project's typecheck, the selected feature/identity packages,
-then set DATABASE_URL in `.env` and run `bun src/index.ts`. For SQLite pass
-`--dialect sqlite` and optionally DATABASE_FILE (default mantle.sqlite).
-The preset is written once, uses native drivers from `@aotter/mantle/bun`, and
-owns Bun.serve, trusted socket IP and shutdown/background work. Admin binds the
-installed UI bundle. Enabled schedule Triggers fail generation; use `host: none`
-with an explicit scheduler when schedules are required. Behind a reverse proxy,
-set TRUSTED_PROXIES to its addresses: otherwise every client shares the proxy's
-address, and with it one sign-in rate limit.
+Never edit generated output by hand. Merge manifests/options, regenerate with the same command, then review TypeScript and SQL diffs. Use that exact command with `--check` in CI. Unmarked app files are preserved. Imported option modules must be pure; generation does not make their side effects safe.
 
-PostgreSQL pools must set `prepare: false`: Bun otherwise re-encodes JSON strings,
-and the role needs TEMPORARY on the database (`GRANT TEMPORARY ON DATABASE app TO
-app_role`), which describing a result takes.
-Mantle refuses another setting. Native raw result metadata comes from PostgreSQL
-with three extra round trips per result, preserving microseconds and exact numeric
-scale. No pg dependency or PostgreSQL clone is added. See ADR-0038.
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM with a startup guard for eager Better Auth imports. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler. See [service composition](../cloudflare/service-entry.md).

package/docs/handbook/start/quickstart-worker.md

@@ -1,146 +1,68 @@
 ---
-description: Create a Mantle 0.2.0 service on Cloudflare Workers from an empty directory, run it locally, then add sign-in, Admin and MCP.
+description: Generate a small native D1 service and mount an application-owned Worker.
 ---
-# Quickstart: a service on Cloudflare Workers
+# Quickstart: a service on Workers
 
-From an empty directory to a running service with a public View and a write.
-You need Node 22 or later and a package manager (pnpm is used below).
+Create an application outside the SDK checkout. Install an exact released `@aotter/mantle` version, TypeScript, Wrangler and Cloudflare Worker types. Read that installed version's handbook; this page describes the native 0.2.0 contract.
 
-## 1. Create the project
-
-```sh
-mkdir notes && cd notes
-pnpm init
-npm pkg set type=module
-npm view @aotter/mantle dist-tags
-```
-
-Pick a `0.2.x` version from the output. While 0.2.0 is in prerelease it is
-on the `alpha` tag, and `latest` still names 0.1.x. Install it with an exact
-version:
-
-```sh
-pnpm add --save-exact @aotter/mantle@<0.2.x version>
-pnpm add -D wrangler @cloudflare/workers-types @types/node typescript
-```
-
-## 2. Write a manifest
-
-`manifests/notes.yaml`:
+Save `manifests/tickets.yaml`:
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
-metadata: { name: notes }
+metadata: { name: tickets }
 spec:
-  title: Notes
+  title: Tickets
   lifecycle: operational
+  indexes: [[ticketState]]
   schema:
     type: object
-    required: [text]
+    additionalProperties: false
+    required: [subject, ticketState]
     properties:
-      text: { type: string, minLength: 1, maxLength: 500 }
+      subject: { type: string }
+      ticketState: { type: string, enum: [open, closed] }
 ---
 apiVersion: cms.mantle.aotter.net/v2
 kind: View
-metadata: { name: latest-notes }
+metadata: { name: tickets-by-state }
 spec:
   surface: public
-  sql: SELECT id, text, created_at FROM notes ORDER BY created_at DESC LIMIT 20
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: add-note }
-spec:
   input:
     type: object
-    required: [text]
+    additionalProperties: false
+    required: [ticketState]
     properties:
-      text: { type: string, minLength: 1, maxLength: 500 }
-  output: { type: object }
-  handler:
-    sql: INSERT INTO notes (text) VALUES (input.text) RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: add-note-http }
-spec:
-  source: { kind: http, method: POST, path: /api/notes }
-  target: { procedure: add-note }
+      ticketState: { type: string, enum: [open, closed] }
+  sql: |
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
+    WHERE ticketState = input.ticketState
+    ORDER BY id ASC
 ```
 
-## 3. Generate
-
-Start with the smallest selection: no identity (every caller is anonymous)
-and only the REST surface.
-
 ```sh
-pnpm exec mantle generate --identity none --features web
+pnpm exec mantle generate cloudflare-d1 generated manifests/tickets.yaml
+pnpm exec mantle generate cloudflare-d1 generated manifests/tickets.yaml --check
 ```
 
-It writes `.mantle/generated/plan.json` and `mantle.ts`, `mantle.config.json`,
-and once, the preset: `src/service.ts`, `src/index.ts`, `src/handlers.ts`,
-`wrangler.jsonc`, `tsconfig.json` and `.gitignore`. Commit all of them,
-`.mantle/generated` included.
-
-## 4. Run it
-
-```sh
-pnpm exec wrangler dev --local
+Write `src/worker.ts`:
+
+```ts
+import { rest } from '../generated/rest.js';
+interface Env { DB: D1Database }
+const api = rest<Env>({
+  db: env => env.DB,
+  caller: () => ({ kind: 'anonymous' }),
+});
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return await api(request, env) ?? new Response('Not found', { status: 404 });
+  },
+};
 ```
 
-On the first request the runtime creates the tables on the local D1 database.
-Then:
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/notes -H 'content-type: application/json' -d '{"text":"hello"}'
-curl -sS http://127.0.0.1:8787/api/views/latest-notes
-```
-
-The write answers `{ "results": [[{ "id": "…" }]] }` and the View
-`{ "rows": [{ "id": "…", "text": "hello", "created_at": … }] }`.
-
-## 5. Add sign-in, Admin and MCP
-
-The full selection is identity `mantle` (Better Auth sign-in, staff roles,
-OAuth for MCP) and the features `mcp`, `admin` and `web`. A rerun cannot
-switch identity, and the preset is never rewritten, so start a project that
-needs them with the full selection instead:
-
-```sh
-pnpm exec mantle generate
-```
-
-With no flags the selection is identity `mantle` and every feature. The first
-run names the packages it needs, with versioned install commands from the
-installed Core's `peerDependencies`, and writes nothing until they are installed
-at compatible versions. Copy those commands rather than installing registry
-latest; `@aotter/mantle-ui` must match Core's exact version:
-
-```sh
-# Run each versioned pnpm add command printed above first.
-pnpm exec mantle generate
-cp .dev.vars.example .dev.vars   # set ADMIN_EMAIL and a random BETTER_AUTH_SECRET
-pnpm exec wrangler dev --local
-```
-
-Request a code for `ADMIN_EMAIL` (`POST /api/auth/email-otp/send-verification-otp`
-with `{ "email": …, "type": "sign-in" }`). The code is printed to the wrangler
-log, and that email becomes the owner. Codes in the log are for local
-development only; [Authentication](../cloudflare/authentication.md) covers
-production sign-in.
-
-Or open `/admin/sign-in` in a browser: the console is served at `/admin` from
-`@aotter/mantle-ui/admin`, which the generated `wrangler.jsonc` binds as the
-Worker's `ASSETS`. Admin's API answers at `/admin/api/*`, the public MCP
-surface at `/mcp`, and the staff MCP surface at `/mcp/staff`. The
-[reference service](../../examples/reference-service/README.md) is this
-selection with a smoke test that signs in and drives every surface.
+Set the database binding `DB`, Worker name and compatibility date in `wrangler.jsonc`. Generation adds the split build configuration. Apply `generated/schema.sql` explicitly to an empty local database, for example `pnpm exec wrangler d1 execute <database> --local --file generated/schema.sql`. The first request creates nothing.
 
-## Next
+Typecheck, then run `pnpm exec wrangler dev --local`. Query `/api/views/tickets-by-state?ticketState=open`; the response is `{ rows, nextCursor? }`. The empty database returns no rows. Use Store or a declared Procedure for writes.
 
-- [Project layout and CLI](./project-and-cli.md): what each generated file is,
-  and `mantle generate --check`.
-- [Writes: Procedures, Triggers and hooks](../concepts/procedures-and-triggers.md)
-  and [Reads: Views, REST and MCP](../concepts/views.md).
-- [Deploy and operate](../cloudflare/deploy-and-operate.md).
+Commit generated files and Wrangler edits; keep bundle `dist/` untracked. Follow [service composition](../cloudflare/service-entry.md) to add auth, Admin or MCP and [deploy and operate](../cloudflare/deploy-and-operate.md) before changing schema or deploying.

package/docs/skills/develop/SKILL.md

@@ -10,133 +10,50 @@ metadata:
 
 # Mantle Develop
 
-The workflow for changing a Mantle 0.2 project. The installed package's docs
-govern behavior: `node_modules/@aotter/mantle/docs/`.
+## Workflow
 
-## First read
+Read the installed SDK README and version-matched handbook before editing.
 
-1. `package.json` and the lockfile: the installed `@aotter/mantle` version.
-   Every `@aotter/mantle*` package is at that same exact version. If
-   `node_modules/` is missing, install with the lockfile first.
-2. `mantle.config.json`: `identity` (`mantle`, `custom`, `none`),
-   `features`, `host` (`cloudflare`, `bun`, `none`) and `dialect` (`sqlite`,
-   `postgres`); absent host and dialect mean Cloudflare over D1. A
-   `version: 1` config or `cms.mantle.aotter.net/v1` manifests mean 0.1.x:
-   switch to `docs/skills/update/SKILL.md`.
-3. `manifests/*.yaml`, `src/service.ts`, `src/handlers.ts`, `src/index.ts`
-   (and `src/identity.ts` for `custom`), `wrangler.jsonc` (not on Bun).
-4. Installed docs: `docs/handbook/reference/features.md` to map the request to
-   manifest features, then the field references it links to.
-   `docs/examples/` holds whole services in the v2 grammar.
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
 
-## The model
+Use the native Store/query/surface entries and app-owned fetch from the service composition guide.
+Keep optional modules out of unused entry imports and auth dynamically loaded.
+Run actual public/member/admin HTTP, MCP and UI scenarios; verify stored state,
+visibility, OCC and restart persistence, not just a 200 response.
 
-Four atoms, nothing else: **Schema** (rows), **View** (one SQL `SELECT`),
-**Procedure** (SQL write statements, or a `ref` handler), **Trigger** (HTTP,
-MCP, lifecycle, schedule). Do not invent kinds such as `Form` or `Workflow`.
+For native Admin, read the [current guide](../../handbook/guides/native-admin.md).
+Select `--admin` / `admin: true`; mount `entries(bindings.schemas, bindings.adapter)`
+from the optional Admin package. Keep one Core SDK, the Admin product and shared
+UI kit at matching versions. Generate → typecheck → implement listed handlers →
+typecheck. Ref handlers retain caller-bound `ctx.store`; generic Admin reads
+use shared generated View templates and writes use native Procedure fragments.
+Check actual member/Admin OTP, private scope/TTL/translation visibility, paging,
+statistics, safe/exact OCC and no automatic retry after unknown 503 outcomes.
 
-Choose in this order, stopping at the first that works:
 
-1. A Schema feature: `checks`, `uniqueIndexes`, `scope`, `ttl`,
-   `searchableFields`, `lifecycle`.
-2. SQL: a View for reads; a Procedure's `sql` for writes. Several statements in
-   one `sql` apply together or not at all.
-3. `requires` for who may call; a guard for a live check before one action.
-4. A `ref` handler, only for what SQL cannot do: calling another service,
-   reading before writing, setting `status`, branching on a read.
+Place admin MCP Procedures in Admin deliberately: `spec.uiSchema.collectionAction:
+<schema-name>` adds a collection-header action; `spec.target: { schema, id,
+version? }` selects row actions and binds the row id / reviewed OCC version to
+the named inputs. Other admin operations appear under Operations in the sidebar.
+Keep state conditions in the SQL WHERE: simple AND equality/IN literals become
+row-menu hints, while the Procedure remains the authority. Required-ref child
+collections fold under their parent's sidebar group; use Schema
+`uiSchema.nav.standalone: true` for a top-level entry.
 
-## SQL rules that trip agents
+## Database changes
 
-- PostgreSQL syntax over declared Schemas only. References: `input.<name>`,
-  `auth.uid()`, `auth.role()`, `now()`; search is `mantle.search(t, q)`.
-- Native columns are snake_case in SQL (`created_at`, `author_id`) and
-  camelCase in `ctx.store` JSON and in `indexes`.
-- A write never names the scope field, `id` (on update), `version`, `status`,
-  `created_at`, `updated_at` or `author_id`. Set an owner with `auth.uid()` and
-  a time with `now()`, never from input.
-- Optimistic lock: `WHERE id = input.id AND version = input.expectedVersion`.
-  Writing no row is `CONFLICT`. Keep omitted optional fields with
-  `COALESCE(input.x, x)`.
-- `LIMIT` needs `ORDER BY`. No `OFFSET`, `RIGHT JOIN` or `CURRENT_TIMESTAMP`
-  on any dialect. On SQLite (D1) also no `WITH`, `UNION`, `ILIKE` or jsonb
-  operators, and `CAST(x AS int)` only on an integer literal: use `round(x)`.
-  PostgreSQL accepts these (`docs/handbook/reference/view.md`).
-- Unquoted aliases fold to lower case: `AS "orderCount"` keeps the case.
-- The runtime injects scope and TTL into every Schema reference, and
-  published-only into public Views. Never repeat them.
-- `scope` hides rows from staff too. When staff must see every row, store
-  `auth.uid()` in a field and filter on it instead.
-- That filter protects the View, not generic Admin Schema reads. Root
-  `schema.readOnly: true` blocks generic writes only. If a contributor must
-  not read other users' rows, restrict the application-owned Admin surface
-  inside its existing `withCaller` boundary; see
-  `docs/handbook/guides/admin-ui.md` (Roles). Keep business transitions in SQL.
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
-## Handlers
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-- `src/handlers.ts` exports `handlers: MantleHandlers` (`MantleHandlers<Env>`
-  types `ctx.env`); the generated type
-  lists exactly the plan's refs. Read and write only through `ctx.store`.
-- After hooks: loop over `ctx.cause.rows`; never read only `rows[0]`.
-- Before hooks and guards are read-only and reject by throwing
-  `DiagnosticError` (from `@aotter/mantle`); any other throw is a 500.
-- `ctx.caller.kind === "user"` means signed in; a schedule runs as `system`.
-  Never test `!== "anonymous"`.
-- `ctx.invoke(name, input)` calls another Procedure with the same caller.
+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.
 
-## The service
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
-`src/service.ts`, `src/index.ts` and `wrangler.jsonc` belong to the
-application after the first `mantle generate`; it never rewrites them. Add
-routes, bindings and env there (`docs/handbook/cloudflare/service-entry.md`).
-Reach data from service code through `runtime.store.as(caller)` or
-`runtime.invokeProcedure`; `runtime.store` alone is unscoped. A signed webhook
-is a route in the service's `fetch` that verifies the raw body, then invokes
-a Procedure as `systemCaller(...)`.
+## Data paths
 
-## MCP
-
-With feature `mcp`, the preset mounts `/mcp` (public tools) and, with an
-identity, `/mcp/staff` (staff tools for a staff role; with identity `mantle`,
-the same OAuth token as `/mcp`). `/mcp/staff` serves
-Mantle's MCP App: a host that renders MCP Apps shows each staff View's rows and
-the operations on one row. A member-facing App on `/mcp` is the application's
-to build when the product asks for one: follow [the recipe](mcp-app.md).
-
-## Loop
-
-```bash
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-pnpm exec wrangler dev --local   # on Bun: bun src/index.ts
-```
-
-Then exercise what changed over HTTP: the REST View or Trigger, `/mcp`
-`tools/list` and a call, and with identity `mantle` a console email-OTP
-sign-in and the Admin route (`docs/handbook/cloudflare/authentication.md`).
-Check the stored rows, not only a 200. Before deploying a Schema change on
-SQLite, run `mantle generate --check --database <file>` to see the storage SQL.
-For a workflow, verify valid and invalid state transitions, ownership on every
-mounted surface (including generic Admin reads and writes), concurrent writes
-with one expected version, and persisted data and sessions after a restart.
-Exercise the actual UI when the product includes one; serving HTML alone does
-not verify its forms or operations.
-
-## Rules
-
-- Never edit `.mantle/generated/`. Commit it.
-- Never write a Schema's table with `env.DB`, KV or SQL from outside Store;
-  never touch `_mantle_*` tables. The application's own tables are its own.
-- A blocked storage change (`STORAGE_CHANGE_BLOCKED`) is the author's to make
-  by hand, then rerun; Mantle never drops a column or index.
-- Do not commit secrets (`.dev.vars`, provider keys).
-- Every 0.1.x term is gone: builtin handlers, `from`/`filter`, `params`,
-  `$ctx`, `x-mantle-bind`, `mantle validate`, `mantle skills`,
-  `createMantleWorker`.
-
-## When you are done
-
-Report the manifests and code you changed, the `generate --check` and
-typecheck results, the HTTP calls you made and what they returned, and any
-access you made stricter or could not express.
+Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.