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

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,139 +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
 
-- 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.

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

@@ -1,79 +1,39 @@
 # 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 in the installed Core's `peerDependencies`, 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.
+## Native applications
+
+Read the installed MCP App contract. The SDK's generic hook attaches only the resources the app selects;
+only selected modules enter the service.
+
+```ts
+import type { McpApps } from '@aotter/mantle/mcp';
+import { mcp } from '../generated/mcp.js';
+const memberApp: McpApps = { resources: [{
+  uri: 'ui://shop/my-orders',
+  name: 'my-orders-app',
+  renders: ['my_orders'], // the tool for the declared public View my-orders
+  html: async () => (await import('./member-app.js')).memberHtml,
+}] };
+const tools = mcp({ db, caller, handlers, apps: { public: memberApp } });
+```
+
+Each endpoint accepts one contributor or an array. The separate
+`@aotter/mantle-admin` package contributes its admin App through this same
+`apps.admin` hook; it owns `ui://mantle-admin/…`. App resources use their own
+`ui://<app>/…` namespace. Duplicate resource URI/name, conflicting `renders`,
+or `renders`/`appOnly` naming an unavailable endpoint tool (or a Procedure for
+`appOnly`) fail when `mcp(...)` is built; with a request-bound tool table, the
+tool names are checked on the first matching request. Only clients that
+declare no MCP Apps support see no UI resources; a request that advertises no
+capabilities at all is treated as supported.
+
+Use `renders` for a declared tool; `appOnly` optionally hides it from non-UI
+clients. Import HTML lazily; it carries no secrets or caller data. Tool results
+use the caller's SQL policy, and an App cannot authorize a hidden admin tool.
+Generic interaction components and controllers remain in `@aotter/mantle-ui`;
+Admin-specific controllers/catalogues belong to `@aotter/mantle-admin`.
+
+Verify tools/list metadata, resources/read, actual tool calls and a host-rendered
+member App. Test anonymous/member isolation and resource conflicts. Never retry
+unknown writes blindly; retain OCC and re-read state after an uncertain outcome.
+Commit generated output and run generation with `--check` before deployment.

package/docs/skills/integrate/SKILL.md

@@ -10,87 +10,45 @@ metadata:
 
 # Integrate Mantle into an existing application
 
-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 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.
+## Workflow
+
+Read the installed SDK README and version-matched handbook before editing.
+
+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.
+
+Keep the application router, database/pool, identity and frontend. Replace
+Core consumers explicitly and compose only selected generated entries. Resolve
+one Caller per request with the shared cookie-session origin check. Rehearse
+data-preserving schema/auth/role migrations on a copy and retain rollback artifacts.
+Initial schema.sql is for an empty database, not an in-place upgrade. Requests run
+no DDL or storage checks; the only request-time write outside app operations is
+the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
+Verify cutover with actual app tests.
+
+Preserve the app router, verified identity and native resources. For selected
+Admin use the [native guide](../../handbook/guides/native-admin.md): three matching
+packages, generated checks and `entries(bindings.schemas, bindings.adapter)`.
+Do not import old `/spec`, `/core` or runtime surface APIs. Review data/role
+migrations explicitly; full cross-target int64 parity and automated transfer
+are not this release's upgrade contract.
+
+## Partial adoption in TypeScript/Node
+
+Keep the app's router, pool/handle, identity and frontend. Declare only the Schemas and operations being adopted; import selected `views/<encoded-name>.ts` or `procedures/<encoded-name>.ts`, then call `(appHandle, verifiedCaller, validatedInput)`. Bun.SQL and postgres.js fit directly; [node-postgres can adapt](../../handbook/guides/postgres-adapters.md). No Admin/auth/surface module is required for direct queries.
+
+Existing tables need explicit migration into the declared storage shape, including system columns and constraints. Initial schema.sql must not be applied over an occupied database. Rehearse on a copy and test scope, TTL, publication, OCC and persisted state with the app's own identity.
+
+Writes use Store or declared Procedures; never raw SQL writes to adopted collections. Use internal Views for joins, aggregates, OR and reusable reads. Store findById/find/first remain useful for simple AND lookups in existing handlers.
+
+Direct declared Schema-column outputs in Views and SQL Procedure `RETURNING`
+keep their authored field names; explicit aliases keep SQL casing rules. Store
+rows and nested SQL relations use storage names. Boundary validators support a
+permissive `format: email` check (one `@`, non-empty parts, no whitespace). For
+LEFT JOIN paging, join on the joined Schema's id or single-field unique key and
+keep the base indexed, non-null order/id tuple. Generation always emits `Handlers`
+(empty without ref Procedures); pass `handlers` at `adminBindings()`, generated REST/MCP options and
+`webmcpRoutes(catalogue, tools, handlers)`, as the app shell does.