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

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

@@ -1,166 +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 (`dist/worker`, `dist/client`); 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` | preset over a `pg.Pool` (node-postgres) | 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` (host `cloudflare` or `bun`) | `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 PostgreSQL project, on Cloudflare or Bun, also installs
-`@types/pg` as a dev dependency for the generated `pg` import; node-postgres is
-the PostgreSQL driver on every host.
-
-## `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> [--assets <dir>]
 ```
 
-| 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.
-
-### Storage SQL
-
-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).
+| 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 |
 
-### PostgreSQL on Cloudflare
+Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.0.
 
-`mantle generate --dialect postgres` writes the same preset over Hyperdrive:
-`src/service.ts` opens one `pg` client per request 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:
-
-```sh
-wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
-```
-
-Reads run under the role's own statement limit, so give it one, and UTC, before
-the first boot (locally too); the boot error names any other setting:
+| 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. |
+| `--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>` | Bundle output; default `dist`. The Worker goes to `<outdir>/worker`. Keep separate from source/generated files. |
+| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. |
 
-```sql
-ALTER ROLE app SET statement_timeout = '10s';
-ALTER ROLE app SET TimeZone = 'UTC';
-```
+## Outputs
 
-## 0.1.x projects
+`generated/.mantle-inputs.json` records the Mantle version, the target, and a hash of every input the run read (manifests and the
+`--auth` and `--site` 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`, `admin-client.ts` (browser-side types and hooks for `admin.tsx`) 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 `pg` for PostgreSQL and bun:sqlite for SQLite (`@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 on Bun is node-postgres, as on Workers (ADR-0039): the entry builds a
-`pg.Pool` with `pipeline: true`, and each request borrows one pooled client
-(`requestScoped`). Install `pg`. The role needs no privilege beyond converging its
-tables (no `TEMPORARY`); set `statement_timeout` and `TimeZone` UTC on the role,
-which boot checks.
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM into `<outdir>/worker` with a startup guard for eager Better Auth imports and for Admin's browser code (`@aotter/mantle-admin/app` and `/hooks`, which `generated/admin-client.ts` imports; they belong to `admin.tsx`). When the Worker imports `@aotter/mantle-admin/server`, it also builds Admin with Vite into `<assets>/admin` (`--assets`, default `<outdir>/client`), from `admin.tsx` beside the Worker entry or Admin's built-in entry; `src/admin.ts` is not an entry. The assets directory must not overlap the Worker directory, and neither the outdir nor the assets directory may be the working directory or contain the Worker entry. The built-in entry is not rebuilt while the installed `@aotter/mantle-admin` keeps its path and version and its direct dependencies and its `react`/`react-dom` peers keep theirs; an `admin.tsx` entry builds every time. The build needs no install scripts (`npm ci --ignore-scripts` works). A `package-lock.json` made on one OS can lack the native build binaries (rolldown, `@tailwindcss/oxide`, lightningcss) that npm installs per platform from `optionalDependencies`, so a lockfile made on macOS can fail the build on a Linux host; create the lockfile on the build platform or use pnpm. `wrangler dev` and `wrangler deploy` run that build command, so they need `node_modules`. The built output (`<outdir>/worker`, `<assets>`) never reads it, so a pipeline that deletes `node_modules` must run `wrangler deploy` first. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler; Bun runs the server as TypeScript, so for a `bun-*` target recorded in `.mantle-inputs.json`, `mantle bundle src/server.ts dist` skips the Worker bundle and builds only Admin, into `dist/client/admin` (read with `bunAdminAssets("dist/client/admin")`, adapted for `adminShell` as in service composition). 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; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. 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,139 +10,51 @@ 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` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
 
-## 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; with two or more required
+`id` refs, set Schema `uiSchema.nav.parentField` to the parent's ref (generate
+refuses otherwise); use `uiSchema.nav.standalone: true` for a top-level entry.
 
-## SQL rules that trip agents
+## Database changes
 
-- SQL over declared Schemas only, in the project's own dialect: PostgreSQL's
-  syntax on PostgreSQL, a SQLite subset on D1. Each dialect is its own target:
-  a manifest need not compile for the other, and a SQLite spelling such as
-  `json_each` or `->> '$.a'` is refused on PostgreSQL with the PostgreSQL one
-  (rewrite table: `docs/handbook/concepts/runtime-and-adapters.md`). 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`). On PostgreSQL
-  unnest with `jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)`,
-  not `json_each`; unstated `NULLS` follow PostgreSQL (last ascending).
-- 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.