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

package/docs/skills/develop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: develop
-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.
+description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity, MCP tool design and independent acceptance — using the installed package's contract.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/develop/SKILL.md
@@ -10,123 +10,79 @@ metadata:
 
 # Mantle Develop
 
-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 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.
-
-## 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.
+## Workflow
+
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+Use the native Store/query/surface entries and app-owned fetch from the [service
+composition guide](../../handbook/cloudflare/service-entry.md).
+Pair every HTTP Trigger with an MCP Trigger by default; see [Trigger](../../handbook/reference/trigger.md)
+for the generate warning and deliberate asymmetry exception.
+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.
+Before reporting any new app or feature as done, follow the [independent
+acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): write a
+private rubric, then give one fresh agent per role (`admin`, `user`) only its
+role and entry points, across every surface it uses. This is not limited to
+MCP; if it was not run, say so explicitly and report the work as UNVERIFIED
+rather than done. For MCP workflows, also run the guide's design audit before implementing
+tools.
+
+For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
+the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
+MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Keep matching SDK, Admin and UI versions. 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.
+
+For application-owned MCP App entries and host checks, follow the [MCP Apps
+guide](../../handbook/guides/mcp-apps.md).
+
+Build a custom frontend with `App` from `@modelcontextprotocol/ext-apps`: register
+`ontoolinput`/`ontoolresult` before `connect()`, and use `callServerTool` for
+host-proxied calls. Keep protocol negotiation and message routing in the official
+client; importing its types while writing a second `postMessage` bridge is
+insufficient.
+
+For Admin UI upgrades, follow the installed handbook's
+[retained-page recipe](../../handbook/guides/mcp-apps.md#keep-old-conversations-working-after-an-upgrade).
+Keep deployed snapshots in source/artifact storage and pass `previous` to
+`adminMcpApps`; verify old conversations after a changed UI build without host
+tool refresh, reconnection or cache clearing. Keep tool contracts compatible
+through the declared retention window.
+
+
+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.
+
+## Database changes
+
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
+
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
+
+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.
+
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
+
+## Data paths
+
+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.
+
+For simple creates/partial updates, prefer Store-backed ref Procedures; keep
+Procedure `requires`/generated input checks, use only allowed patch fields and
+return safe business fields with the actual returned ID/version. Preserve
+omitted fields and document null semantics. Retain SQL for atomic conditional
+or related writes; D1 batches cannot consume an earlier result. Follow the
+[Store write guidance](../../handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).

package/docs/skills/integrate/SKILL.md

@@ -10,87 +10,40 @@ 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, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+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, follow the [native guide](../../handbook/guides/native-admin.md) for its
+application-built bundle and service composition.
+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.

package/docs/skills/media-gc/SKILL.md

@@ -11,14 +11,25 @@ metadata:
 
 # Mantle Media GC
 
+## Generated native applications (alpha.7 and later)
+
+If the installed README describes generated native queries, read
+`docs/handbook/cloudflare/media-r2.md` and app-owned site/media wiring instead of Core storage
+options. Resolve the exact configured bucket and declared purposes. The
+`uploads/` candidate audit below still applies. Committed copies live under
+`committed/` and must never be candidates. Attempt-isolated committed copies
+retained after an uncertain DB outcome require reconciliation with live DB
+references before any separately authorized cleanup.
+
 Use the connected Cloudflare API. Audit by default; delete only the exact
 objects approved by the user.
 
 ## Preflight
 
-1. Read `wrangler.jsonc` and `src/service.ts`. Resolve the R2 bucket that
-   `r2MediaStorage` uses and the media purpose names in the site defaults
-   passed to `d1Storage(db, { site })`.
+1. Read `wrangler.jsonc`, the app-owned entry (`src/worker.ts` by default,
+   or the generation command's `--entry`) and its media wiring. Resolve the R2
+   bucket that `r2MediaStorage` uses and the media purpose names in
+   `siteDefaults.media.purposes` selected by `--site`.
 2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
    ask; never choose by name similarity.
 3. Use the Cloudflare OpenAPI search before execution to resolve the current
@@ -30,11 +41,13 @@ objects approved by the user.
 
 `POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
 minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
-copies each checked object to `<purpose>/<group>/<role>.<ext>` (with
-`committedAt` metadata) and deletes the upload key; a rejected group's upload
-keys are deleted. So an object still under `uploads/` long after its URL
-expired belongs to an upload that was never committed, and nothing can commit
-it any more. Objects outside `uploads/` are committed media: never candidates.
+copies each checked object to `committed/<group>/<attempt>/<role>.<ext>` (with
+`committedAt` metadata); the attempt UUID isolates concurrent commits. Upload
+keys are removed after the database commit succeeds, or when a group is
+rejected. An old upload key may also be leftover cleanup from a successful or
+uncertain commit: it is not evidence that the media row is absent. Once expired,
+it cannot create a new asset. Objects outside `uploads/` are never candidates;
+reconcile attempt copies separately with live database references.
 
 ## Audit
 

package/docs/skills/provision/SKILL.md

@@ -11,90 +11,34 @@ metadata:
 
 # Provision a Mantle project
 
-Provision only after the user asks to create remote resources or ship. Read the
-installed `docs/handbook/cloudflare/deploy-and-operate.md` and
-`docs/handbook/cloudflare/authentication.md` first.
-
-## Choose the target
-
-Ask which target, unless the project already shows one.
-
-| Target | Config | Follow |
-|---|---|---|
-| Cloudflare Workers | `wrangler.jsonc` | the rest of this skill |
-| ChatGPT Sites | the Site's hosting config | installed `docs/handbook/cloudflare/chatgpt-sites.md`; publish through Sites, never `wrangler deploy` |
-| Mantle Cloud | — | not available for 0.2 services yet; the plugin's `mantle` skill says when it is |
-| Bun (host `bun`) | `.env` | self-hosted; installed `docs/handbook/start/project-and-cli.md` (Bun), not this skill |
-
-Self-hosting is always an option; never present a hosted target as required.
-
-## Local gate
-
-```bash
-pnpm install --frozen-lockfile
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-git status --short
-```
-
-Confirm the active Cloudflare account with the user before creating anything.
-
-## Cloudflare
-
-1. **Database.** `pnpm exec wrangler d1 create <name>` and put the
-   `database_id` into `wrangler.jsonc`'s `d1_databases[0]`, keeping the
-   binding `DB`. With dialect `postgres`, instead run
-   `pnpm exec wrangler hyperdrive create <name> --caching-disabled --connection-string=...`
-   (the connection string by hidden input) and replace the placeholder id in
-   `hyperdrive[0]`, keeping the binding `HYPERDRIVE`. An existing 0.1.x
-   database is never reused: 0.2 starts on a new one.
-2. **Origin.** Set `PUBLIC_ORIGIN` in `vars` to the deployed HTTPS origin.
-   Update it together with any OAuth callback when a custom domain is added.
-3. **Sign-in (identity `mantle`).** Choose one production method and edit
-   `src/service.ts`; never deploy `ConsoleEmailSender`:
-   - **Email OTP or magic link** with the application's own `EmailSender`
-     over its email provider, `bootstrapOwner: { match: "email", value }`.
-   - **GitHub**: `{ kind: "social", provider: "github", options: { clientId, clientSecret } }`
-     and `bootstrapOwner: { match: "github-login", value }`. The user creates a
-     GitHub OAuth App with callback `<PUBLIC_ORIGIN>/api/auth/callback/github`.
-   Remove the preset's loopback-only check once the method is real.
-4. **Secrets.** Never in chat, files or logs. Use a connector, or hidden
-   input:
-
-```bash
-openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-read -rsp "GitHub client secret: " S && printf '%s' "$S" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET; unset S
-```
-
-   Set `BETTER_AUTH_SECRET` once; rotating it signs everyone out.
-5. **Optional bindings.** R2 for media only when asked
-   (`docs/handbook/cloudflare/media-r2.md`).
-6. **Deploy.** `pnpm exec wrangler deploy`. The first request creates the
-   tables. Later Schema changes on D1: run
-   `mantle generate --check --database <local SQLite file>` (local D1 under
-   `.wrangler/state/v3/d1/`, which must have run the plan now deployed) before
-   each deploy and resolve any blocked change by hand.
-
-Commit and push only non-secret changes.
-
-## Verify the deployed service
-
-- A public View and an HTTP Trigger answer.
-- Sign-in works with the production method; the owner gets
-  `GET /admin/api/me` → `owner`, a second account gets 403.
-- `/mcp` answers `tools/list`, and an anonymous call to a protected tool is
-  401 with a `WWW-Authenticate` challenge. When every public tool `requires` a
-  caller, anonymous `initialize` and `tools/list` are already that 401.
-- Every enabled schedule appears in the Worker's cron triggers.
-
-## Handoff
-
-Return the public origin, the sign-in method and who the owner is, the MCP
-URL (`<origin>/mcp`), the resources created or reused, and anything deferred.
-
-## Don't
-
-- Don't create remote resources before the user asks to ship.
-- Don't commit secrets or put them in `wrangler.jsonc` `vars`.
-- Don't point a 0.2 service at a 0.1.x database.
-- Don't patch `site_config` or `_mantle_*` tables; boot owns them.
+## Workflow
+
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+Deploy/create resources only within the user's authorization; reuse configured
+host resources. Apply reviewed and rehearsed migrations before routing traffic;
+imports/first requests perform no DDL or schema checks. Keep auth dynamic, production
+secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
+production email and selected media wiring. Configure Admin ASSETS worker-first
+as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
+Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
+including environment overrides; verify deployed MCP with a real OAuth bearer
+(`initialize` and `tools/list`), not only a browser session cookie.
+For MCP Apps, also follow [deployed host acceptance](../../handbook/guides/mcp-apps.md#verify-a-deployed-app-in-chatgpt):
+compare the current resource URI and visibly verify a newly invoked render tool.
+Archive deployed Admin pages using the guide's `previous` recipe and carry them
+through clean builds. Test the same old conversation after changing the UI build,
+without reconnecting, refreshing host tools or clearing caches. A deliberate tool
+contract change has its own migration/host rediscovery step. OAuth renewal, `tools/call` success and a
+local official-host replay do not establish that the deployed App rendered.
+Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
+(role admin), denied access, public reads, a persisted write, MCP and selected UI.
+Report artifact/resources/checks and keep rollback artifacts.
+
+For ChatGPT Sites, follow [Mantle on ChatGPT Sites](../../handbook/cloudflare/chatgpt-sites.md).
+
+The app builds Admin with `mantle bundle`; serve it as [Native
+Admin](../../handbook/guides/native-admin.md) describes. Verify both member and
+admin OTP/UI flows. Deployment of an authorized application does not authorize
+SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -10,41 +10,27 @@ metadata:
 
 # Mantle Update
 
-Upgrade deliberately; never overwrite application-owned code.
+## Workflow
 
-1. Inspect `git status`, `package.json`, the lockfile and the installed
-   `@aotter/mantle` version. Keep unrelated local changes. Work on a branch.
-2. Choose an explicit target version (`npm view @aotter/mantle dist-tags`).
-   Read its release notes on GitHub and, after installing, its own
-   `node_modules/@aotter/mantle/docs/`. The old version's docs are not the new
-   contract.
-3. **From 0.1.x to 0.2:** stop here and follow
-   `node_modules/@aotter/mantle/docs/upgrade-0.1-to-0.2.md` after installing
-   the target. There is no codemod and no in-place database upgrade: the
-   project moves by hand, to a new database.
-4. Set `@aotter/mantle`, and `@aotter/mantle-ui` where present, to the same
-   exact version (`@aotter/mantle-admin-ui` is gone: the console is
-   `@aotter/mantle-ui/admin`), and update the lockfile with the
-   package manager. Review the dependency diff and any peer changes
-   `mantle generate` names.
-5. Regenerate and check:
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
 
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-```
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
+0.2 service a new database and move data by export and import; never boot 0.2
+against a 0.1.x database. Between 0.2 versions, apply reviewed migrations
+rehearsed on a copy.
 
-6. The preset (`src/service.ts`, `src/index.ts`, `src/handlers.ts`,
-   `wrangler.jsonc`) is never
-   rewritten. Generate into a scratch directory with the same manifests and
-   `mantle.config.json`, diff it against the project's files, and apply the
-   changes that matter by hand.
-7. Run the service locally and test its real routes and sign-in. Before
-   deploying a SQLite project, run
-   `mantle generate --check --database <local SQLite file>` to see what boot
-   will change.
+Pin exact target SDK/peer versions and read its release notes and Admin build
+instructions. Core-to-native replaces app imports/wiring; it is not
+a package-only update. For 0.2-to-0.2 updates, preserve users, sessions, content
+and application code; review emitted SQL/policy diffs and rehearse explicit
+data-preserving schema/auth/role migrations on a copy. Initial schema.sql never
+authorizes rebuilding production tables. Verify auth/Admin/MCP/REST, locks and
+persistence before authorized cutover.
 
-Report the old and new versions, the checks and their results, what changed
-in the service files, and what remains. A dependency update does not
-authorize a deploy. Never commit secrets.
+Follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin)
+for the current application-built Admin; old UI subpaths have no compatibility
+aliases. Pin only actually published versions, or explicitly use a matching
+workspace preview. Recheck member and Admin OTP, all affected native routes,
+private field visibility, OCC and unknown outcomes. Do not publish a package as
+part of an application dependency update.