@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/docs/skills/develop/SKILL.md

@@ -1,258 +1,132 @@
 ---
 name: develop
-description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
+description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity and MCP — using the installed package's contract.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/develop/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
+  applies_to: mantle 0.2
+  projection: package
 ---
 
 # Mantle Develop
 
-This is the Core workflow skill for an existing Mantle project. Repo-local
-copies are byte-for-byte projections from the installed package; its embedded
-docs govern runtime/API behavior.
-
-## First Read
-
-1. `package.json` for the installed `@aotter/mantle*` versions.
-2. The manifest directory selected by the project scripts, the actual host
-   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
-   Read custom Auth construction there when present.
-3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
-   and `.mantle/recipes/`. Legacy launch/handoff files are context only.
-4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
-
-If `node_modules/` is missing, run `pnpm install --frozen-lockfile` before
-falling back to remote docs. Remote docs must use a tag matching the installed
-version; never use `develop` branch docs for a versioned consumer project.
-
-## Existing Examples
-
-Read installed `docs/handbook/start/project-and-cli.md` and
-`docs/examples/README.md`. Use `docs/examples/host-minimal-worker/` for Spec +
-adapter without Admin. Read `docs/examples/host-local-admin-otp/` only when the
-project already has Admin or the human asked for Dev UI — that path is opt-in.
-Ingest only `docs/examples/builtin-*.md` Manifests as grammar for new domains.
-Read `docs/examples/cf-primitives-*.md` before inventing Durable Object, Queue,
-cron, or `ref` handler patterns.
-References are test/documentation, not a Starter or a fixed application shape.
-
-Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
-`TemplateRegistry`, and a matching `publicPathResolver` must agree on the
-exposed collections. Do not auto-publish every Schema. Applications document their mounted URL surface in their own README.
-Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
-not install public rendering by itself.
-
-## Authoring CLI
-
-Use the project's scripts first; applications use the shipping
-`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
-command list instead of trusting one copied into prose — the surface is
-version-matched and changes between releases:
-
-```bash
-pnpm exec mantle --help
-pnpm validate
-```
-
-On 0.1.5 and newer, `generate --host cf|chatgpt-sites` assembles a new blank
-app; no `--features` selects Spec, Runtime, API, MCP, Admin and Web. Explicit
-`--features` selects a smaller composition. It never invents a business
-Schema. Existing authored apps keep compile mode, and older installed CLIs
-may not support project generation. Check this project's CLI help first.
-
-## Core Model
-
-Mantle exposes exactly four declarative atoms:
-
-| Atom | Purpose |
-|---|---|
-| `Schema` | Stored entity/table shape. |
-| `View` | Read/query surface. |
-| `Procedure` | Typed mutation or operation. |
-| `Trigger` | HTTP/lifecycle/MCP invocation binding. |
-
-Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
-`Membership`. Compose those from the four atoms plus TypeScript only where
-the atoms cannot express the behavior.
-
-## Choose the manifest feature first
-
-Read installed `docs/handbook/reference/features.md` to map the requested
-behavior to fields before adding handlers or a custom UI. For host-only reads,
-`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
-`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
-View params/results, indexed entry reads, and their authorization boundary.
-Use `from` for portable typed projections; SQL is for queries needing native
-SQLite and produces `unknown` row types.
-
-For Admin labels, inputs, collection columns/tabs, reports or action buttons,
-read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
-metadata and `uiSchema` before custom frontend code. These control the Admin
-console, not the visitor frontend. Regenerate and verify the actual console;
-never edit generated `public/_mantle/admin/` assets.
-
-## Content Edits
-
-- Follow the actual frontend content source. Use Admin or Staff MCP for
-  runtime-backed content. Do not invent an overlay/seed homepage.
-- For a new submitted field, update the stored `Schema` and the public
-  `Procedure.spec.input` before any form UI. Keep public mutation inputs
-  `additionalProperties: false`; otherwise JSON Schema's default may strip an
-  undeclared field while returning success.
-- Use `lifecycle: operational` for submissions, inquiries, orders, and other
-  Procedure-created operational records that staff inspect or correct. Reserve
-  `publishing` for content a person stages and publishes.
-- Lifecycle `before_update` / `after_update` hooks also fire for unpublish,
-  archive, and every other status transition whose target is not `published`;
-  do not use them for edit-only work.
-- When a form's fixed option values change, update the stored Schema and public
-  Procedure input `enum` together. Keep translated labels in the frontend content source;
-  Admin and Staff MCP derive their typed controls from the manifest values.
-- If the application has a `page` Schema with sections, update its declared
-  section properties when adding display fields; an undeclared property has no
-  runtime-backed Admin or Staff MCP path.
-- Update notification handlers when they need the new field. Test the stored
-  entry, not only the HTTP `{ "ok": true }` response.
-
-## Locales
-
-- `data.locale` is reserved for `localized: true` Schemas. A non-localized
-  Schema must use a domain field such as `replyLocale`.
-- Use a standalone localized Schema only for independent locale rows. For
-  versions of one entity, use a non-localized parent plus a localized child
-  with `translates: { parent, on }`. The child must own at least one field
-  besides `locale` and the join field.
-- Parallel locale blocks must keep field names, option values, step IDs, and
-  result keys identical; translate display strings only.
-- `siteDefaults.origin`, `siteDefaults.locales`, and `siteDefaults.icons` are
-  code-owned and boot-synced. The icon list is shared by browser favicons,
-  Admin chrome, and MCP `serverInfo.icons`; keep its static files under
-  `public/`. Brand, title, and description seed once, then change through site
-  settings.
-- When changing an existing collection from `[slug]` to `[slug, locale]`,
-  boot with a Mantle version that reconciles obsolete unique indexes and test
-  the same slug in two locales. Do not patch D1 manually.
-
-## Adapter Boundary
-
-The runtime is adapter-neutral. A `MantleStorageAdapter` prepares the compiled
-plan into semantic storage ports; `createMantleRuntime` binds that prepared
-storage and selected capabilities. Database drivers and asset serving belong
-to the host/optional composition. Follow the installed adapter guide.
-
-Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
-or its adapter config is visible. A future Netlify adapter should satisfy the
-same Core workflow through its own ports and provider setup.
-
-Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
-`runtime.entries`, and optional `runtime.siteConfig`; do not query Mantle-owned `entries` or
-`site_config`, reach through deprecated `runtime.db`, copy generated-column
-names, or construct SDK KV keys. Cloudflare bindings belong only at the
-composition root. If a normal feature cannot be expressed through a
-purpose-shaped surface, treat that as a Core abstraction gap instead of
-teaching the project Mantle internals.
-
-## Auth Composition
-
-Generated full apps select Admin by default; smaller selections can omit it.
-A project without `@aotter/mantle-admin-ui` is complete when Admin was not
-selected. If Admin was selected but its package is missing, install the
-CLI-declared exact version and rerun generation.
-When Admin is installed, `createMantleWorker({ auth })` with `email-otp`
-and `ConsoleEmailSender` is the local human path (OTP in wrangler logs).
-That override owns Auth construction; Core still owns `/admin` and
-`/api/auth/*`. Admin also requires wrangler `assets.directory=./public`
-and an `ASSETS` binding. A white screen at `/admin` with HTML 200 and
-`/_mantle/admin/assets/*` 404 is a missing assets binding, not a missing
-frontend build.
-
-Generated Cloudflare apps use `MANTLE_AUTH_MODE=local-otp` on loopback after
-copying `.dev.vars.example` to `.dev.vars` and setting a real owner email and
-random secret. Production uses `hosted` or `self-managed` with provider
-credentials and `ADMIN_GITHUB_LOGIN`. Conventional Cloudflare projects that
-do not replace Auth use those two production modes; Core owns that standard
-composition and rejects partial or mixed bindings. Preserve the explicit
-mode recorded in Worker config, keep provider secrets out of source, and
-do not infer a mode from whichever credentials happen to be present.
-
-## Performance Loop
-
-After changing a Schema index, View filter/order, public API, or rendered page,
-run the project's index check when present. Otherwise run the installed
-harness directly:
-
-```bash
-pnpm exec mantle-harness indexes --require-public --format text
-```
-
-The check uses crowded real SQLite and the shipped compiler. It complements
-`pnpm validate`; it does not replace correctness validation. Declare the
-smallest ordered index justified by the measured path and respect SQLite's
-leftmost-prefix rule; which columns an index may name and how a public View's
-status predicate shapes it is in the handbook (`reference/schema.md#indexes`).
-Do not change user-visible filter or ordering semantics
-just to make the gate pass. Do not add every permutation or cache every read.
-
-For relevant Cloudflare serving changes, start the project and sample the
-actual routes:
-
-```bash
-pnpm exec mantle-harness http \
-  --base-url http://127.0.0.1:8787 \
-  --route page=/en/example \
-  --rounds 20 --warmup 2 --format text
-```
-
-Prefer query plan, query count, `rows_read` scaling, and cache MISS/HIT
-evidence. Do not create CI gates from absolute local milliseconds.
+The workflow for changing a Mantle 0.2 project. The installed package's docs
+govern behavior: `node_modules/@aotter/mantle/docs/`.
+
+## First read
+
+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.
+
+## The model
+
+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`.
+
+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.
+
+## SQL rules that trip agents
+
+- 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.
+
+## Handlers
+
+- `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.
+
+## The service
+
+`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(...)`.
+
+## 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 install --frozen-lockfile
-pnpm validate
-pnpm check:indexes # when the project provides it
-pnpm typecheck
-pnpm check
-```
-
-Use `pnpm dev` for local preview when the project provides it.
-
-## Connect a Local MCP Client
-
-Start the project with `pnpm dev`, then use the exact local origin it prints.
-The conventional Cloudflare adapter exposes:
-
-- `http://localhost:8787/mcp` for public tools;
-- `http://localhost:8787/mcp/staff` for authenticated authoring tools.
-
-Prefer the client's native remote HTTP + OAuth support. Use a standard
-HTTP-to-stdio bridge such as `npx -y mcp-remote <url>` only when the client
-accepts stdio MCP servers but cannot connect to remote HTTP directly. Mantle
-does not own a separate local proxy or an auth-bypass mode.
-
-Before changing client config, confirm the Worker is reachable:
-
-```bash
-curl -i http://localhost:8787/mcp
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+pnpm exec tsc --noEmit
+pnpm exec wrangler dev --local   # on Bun: bun src/index.ts
 ```
 
-An OAuth-protected endpoint should respond with `401` and a
-`WWW-Authenticate` resource-metadata challenge before sign-in. After
-connecting, inspect `tools/list`; make one read-only `query_view_*` call when
-available before invoking any mutation. Use project-scoped client config when
-the client offers it, and never commit OAuth tokens or the bridge's token
-cache.
+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.
 
 ## Rules
 
-- Keep content models in the configured manifest directory; its immediate
-  `.yaml` and `.yml` files are loaded together.
-- Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.
-- Do not write directly to D1, KV, Postgres, or object storage for content
-  authoring. Use runtime use cases, admin APIs, or Staff MCP.
-- Do not commit provider secrets.
-- If the work is an installable capability, switch to `mantle:plugin`.
+- 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.

package/docs/skills/develop/mcp-app.md

@@ -0,0 +1,79 @@
+# Recipe: an MCP App for members
+
+The preset serves Mantle's App on `/mcp/staff` only. A member-facing App, on
+`/mcp`, is the application's: the SDK attaches none, because what a member
+should see in a chat (one order, a booking form, a status card) is a product
+decision. Build it case by case from these pieces.
+
+## Pieces
+
+| Piece | From | What it gives |
+|---|---|---|
+| `apps: { resources: [...] }` | `createMcpSurface` (`@aotter/mantle/mcp`) | a `ui://` resource beside the tools; `renders` names the tools whose results it shows, `appOnly` the View tools only the App may call |
+| `appCatalog(plan, "public")`, `withCatalog(html, catalog)` | `@aotter/mantle/mcp` | each public View tool's columns as the fields they read, and the row operations, embedded in your HTML as `#mantle-catalog` |
+| `planApp(plan, { surface: "public", html: mantleAppHtml })` | `@aotter/mantle/mcp`, `@aotter/mantle-ui/mcp-app` | the staff App as is, for every public View: the quickest start when a list is what you want |
+| `App` | `@modelcontextprotocol/ext-apps` | the host bridge: `ontoolresult`, `ontoolinput`, `callServerTool`, the host's locale and theme |
+| `readCatalog`, `toolOf`, `outputOf`, `rowsOf`, `invokeTool`, `actionsFor` | `@aotter/mantle-ui` | the catalog, a result's tool, its output and rows, and a tool call as the controller reads it, so the App never parses the wire itself |
+| `renderDataValue`, `propertyLabel`, `optionLabel`, `OperationPanel` | `@aotter/mantle-ui` | a value as Admin shows it (money, dates, option titles, in the host's locale), and Admin's review-and-submit panel |
+| `createInteractionController` | `@aotter/mantle-ui/controller` | one operation on one row: review, submit once, a refusal or `CONFLICT` kept, never retried |
+| `SchemaFields` and the primitives | `@aotter/mantle-ui/kit`, styled by `@aotter/mantle-ui/kit.css` | Admin's form controls |
+
+The App's own build installs what it imports: `@modelcontextprotocol/ext-apps`
+at the exact version `@aotter/mantle` depends on, React and the kit's peers
+(`@aotter/mantle-ui`'s README lists them). `docs/handbook/concepts/mcp-and-agents.md`
+(MCP Apps) describes the catalog and the staff App these share.
+
+## Steps
+
+1. Decide what the App shows and which tool's result opens it. It renders a
+   tool the surface already serves: a public View, or a Procedure with an
+   `mcp` Trigger on `public`. Add that Trigger or View first; an App never
+   reaches data a tool does not.
+2. Build one self-contained HTML file, for example `app/dist/member.html`:
+   Vite with `vite-plugin-singlefile` (and React, if you use the components).
+   A host loads the App in a sandbox that fetches nothing else unless the
+   resource's `csp` allows it. The build runs before `wrangler dev` and
+   deploy: add it to the project's scripts.
+3. Serve it. Wrangler imports `.html` as text; declare it for TypeScript in
+   `src/env.d.ts` (`declare module "*.html" { const html: string; export default html; }`),
+   then in `src/service.ts` (identity `mantle`, whose preset defines
+   `resourceMetadata`; with `custom`, pass the surface to your own `guard`):
+
+   ```ts
+   import memberHtml from "../app/dist/member.html";
+   import { appCatalog, withCatalog } from "@aotter/mantle/mcp";
+
+   const html = withCatalog(memberHtml, appCatalog(runtime.plan, "public"));
+   const mcp = guard(createMcpSurface(runtime, { basePath: "/mcp", surface: "public", resourceMetadata,
+     apps: { resources: [{ uri: "ui://shop/my-orders", name: "my-orders", html, renders: ["my_orders"] }] } }), { resourceMetadata });
+   ```
+
+4. In the App, `readCatalog()` once; in `ontoolresult`, `toolOf(result)` names
+   the tool and `outputOf(result)` (or `rowsOf` for a View) is its data. A
+   success is `structuredContent` when the output is an object and the JSON
+   text otherwise; a failure of a tool with an output schema is the text
+   alone, which `outputOf` reads either way. Call tools through
+   `invokeTool(app.callServerTool…)`: a refusal is `{ ok: false, diagnostics }`
+   (`AUTH_DENIED`, `CONFLICT`, ...), and a thrown call (a 401 or 403 from a
+   missing scope or sign-in, a lost connection) is an unknown outcome to
+   re-read, never to retry blindly.
+
+## Rules
+
+- The HTML is a static asset: no caller data, no secrets, the same for every
+  member. Caller data arrives only in tool results.
+- Every read and write is a tool call under the member's own token; `requires`
+  and `scope` apply exactly as they do to the model's calls.
+- `appOnly` hides a read from the model; only a View can be app-only, never a
+  write.
+- A public View over a `publishing` Schema shows published rows only; over a
+  `scope`d Schema it shows the caller's own rows, without a `WHERE` of yours.
+
+## Verify
+
+Add the App's build to the develop loop, then: `tools/list` from a client that
+declares the MCP Apps extension shows the rendered tool with
+`_meta.ui.resourceUri`; `resources/read` of that URI returns your HTML with
+`#mantle-catalog`; a call to the tool returns its result with
+`_meta["net.aotter.mantle/tool"]`. Then open it in a host that renders MCP
+Apps, signed in as a member.

package/docs/skills/integrate/SKILL.md

@@ -1,60 +1,96 @@
 ---
 name: integrate
-description: Integrate Mantle into an existing application. Use when the application has its own code, routes, storage or deployment and the owner wants to add Mantle, replace part of it, or rebuild with Mantle while migrating frontend and data.
+description: Add Mantle 0.2 to an existing application, or rebuild one on Mantle and migrate its data. Use when the application already has its own code, routes, users, storage or deployment.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/integrate/SKILL.md
-  applies_to: mantle grammar v0.1
+  applies_to: mantle 0.2
   projection: package
-  projectionReason: Existing-project migration is opt-in; a fresh generated app does not need this brief.
 ---
 
 # Integrate Mantle into an existing application
 
-Work in the target application. Read its installed `@aotter/mantle` version,
-CLI help and package-local docs before editing. If Mantle is absent, inspect
-the application first, then install an exact SDK version only after choosing an
-integration strategy. Use the installed version's contract; do not copy
-`develop` branch examples into an older consumer.
+Mantle is added to a running service; it does not replace it. The service
+keeps its entry, users, auth, tables, routes and frontend. Mantle adds its own
+`_mantle_*` tables, the Schemas it declares, and the surfaces the service
+chooses to mount. Read the installed package's
+`docs/handbook/start/overview.md` and
+`docs/handbook/concepts/authorization.md` first.
 
 ## Inspect and decide
 
-Map the actual entry points, router, frontend, auth, storage, data volume and
-relationships, deployment pipeline, URLs, background jobs and existing tests.
-Identify which behavior the owner wants Mantle to own and what must remain
-stable. Compare three approaches using the application's evidence:
-
-1. **Embed selectively:** keep the host and call Mantle's parser, Runtime or
-   selected surfaces through its documented package APIs. The host owns wiring.
-2. **Replace incrementally:** move one bounded capability at a time. Define
-   where reads and writes go during coexistence and how each step is checked.
-3. **Rebuild and migrate:** create a separate new Mantle application, port the
-   frontend and business behavior, and transform/import existing data. Prefer
-   this when adapting the old structure costs more than rebuilding. Preserve
-   relevant IDs, relations, URLs and identity semantics; rehearse the data
-   transfer before a production cutover.
-
-Explain the chosen path and its concrete tradeoffs to the owner. A small
-prototype or read-only inventory may resolve uncertainty. Do not run a generic
-project converter or assume the current application's shape matches a
-generated Cloudflare or ChatGPT Sites skeleton.
-
-## Implement and verify
-
-- For embedding, retain user-owned entry/config/build files. Use the installed
-  direct-authoring docs and CLI to validate manifests and emit bindings; wire
-  the selected Mantle capabilities into the existing host explicitly.
-- For incremental replacement, establish a clear owner for each data write
-  and request route at every stage. Verify old and new behavior together.
-- For rebuilding, generate in a **separate directory** with the installed
-  CLI, move frontend and handlers deliberately, and plan data mapping and
-  import separately. Review database migrations before application or cutover.
-- Run the application's build and representative behavior checks for the
-  changed routes, auth and data. `mantle generate --check` checks generated
-  output against its declared selection; it cannot certify host integration.
-  For live data, record migration counts and a rollback or recovery path
-  appropriate to the project.
-
-Leave existing data and deployment untouched until the requested migration
-and release steps are ready. Report which capabilities Mantle now owns,
-what was verified, and what remains for application deployment or cutover.
+Map the application before installing anything: its entry and router, frontend,
+users and sign-in, database and data volume, deployment, background jobs and
+tests. Ask which behavior the owner wants Mantle to own. Then choose:
+
+1. **Embed.** Keep the application's entry. Compose Mantle into its existing
+   `fetch` (`createMantle(service, { plan, storage })`, the surfaces you want,
+   behind a `CallerResolver` over the application's own sessions). Best when
+   the application already runs on Workers with D1.
+2. **Move one capability at a time.** Give one bounded set of data (a form, a
+   catalog) a Schema, then its Views and Procedures; the rest stays. At every
+   step, each table has exactly one writer.
+3. **Rebuild and migrate.** Generate a new Mantle service in a separate
+   directory, port the frontend and business rules, and import the data. Best
+   when adapting the old structure costs more than rebuilding.
+
+Explain the choice and its tradeoffs to the owner before changing code.
+
+## Identity
+
+The application keeps its users. Pick `identity`:
+
+- `custom`: write `src/identity.ts` as a `CallerResolver` over the existing
+  sessions or tokens. `subject` is the application's stable user id,
+  namespaced when there are several issuers, never an email. Map existing
+  admin roles to `owner` / `editor` / `contributor`, or leave `role` null.
+- `mantle`: only when the application has no sign-in and wants Better Auth's.
+- `none`: a public service with no signed-in callers.
+
+Switching identity later is refused; choose deliberately.
+
+## Embedding into an existing entry
+
+`mantle generate` writes the preset only where `src/service.ts` does not
+exist; `--host none` writes no preset at all, only the plan and its types.
+For an application with its own entry, generate in a scratch
+directory with the same manifests and config, then copy the composition you
+need from the generated `src/service.ts` into the application's own entry:
+
+- the `createMantle(service, { plan, storage: (env) => d1Storage(env.DB), schedules: true })` call;
+- `withCaller(resolver, createRestSurface(runtime, { basePath: "/api" }))`
+  and any other surface, mounted on paths the application does not use;
+- the `scheduled` mapping from `src/index.ts`, if the plan has schedules.
+
+Put that composition in the application's `src/service.ts` before the first
+`mantle generate` inside the application: while `src/service.ts` is missing,
+generate writes every missing preset file (`src/service.ts`, `src/index.ts`,
+`src/handlers.ts`, `src/identity.ts` for `custom`, `tsconfig.json`,
+`.gitignore`, `.dev.vars.example` for `mantle`, and `wrangler.jsonc` unless a
+`wrangler.*` exists; on Bun `.env.example` and no `wrangler.jsonc`) beside the
+application's own.
+Commit `.mantle/generated/` and run `mantle generate --check` in CI.
+
+## Moving data into a Schema
+
+- Mantle never reads or writes a table it did not create. A table with a
+  Schema's name that Mantle does not own stops boot
+  (`STORAGE_TABLE_NOT_OWNED`); give the Schema a new name.
+- Import through `runtime.store` in trusted code. A scoped row goes through
+  `runtime.store.as(<its owner's caller>)`, so the owner field is right.
+  `status`, timestamps and `author_id` cannot be imported: publish with a
+  second update that sets `status`.
+- Rehearse on a copy, compare row counts, and keep the old table until the
+  owner confirms. Never touch live data before the cutover is agreed.
+
+## Verify
+
+Run the application's own build and tests, then `mantle generate --check`,
+the typecheck, and real requests against the routes Mantle now serves, as the
+right callers (owner, member, anonymous). `--check` proves the generated files;
+it does not prove the integration.
+
+## When you are done
+
+Report which capabilities Mantle now owns, the identity mapping, what moved and
+how it was verified, and what remains for cutover or deployment.