@aotter/mantle 0.2.1-alpha.2 → 0.2.1-alpha.4

package/skills/mantle/SKILL.md

@@ -1,90 +1,25 @@
 ---
 name: mantle
-description: Create, continue, test or deploy a Mantle application using installed @aotter/mantle docs, including manifests, SQL Views and Procedures, MCP tools, app-built Admin, mantle generate and Mantle upgrades.
+description: Create, continue, upgrade, test, speed up or deploy a Mantle application (@aotter/mantle manifests, SQL Views and Procedures, MCP, REST, Admin, mantle generate). Every contract comes from the installed version's `mantle help`.
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/mantle/SKILL.md
-  applies_to: mantle 0.2
-  projection: plugin
-  projectionReason: The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package.
 ---
 
 # Mantle
 
-The Mantle plugin's one skill. It installs no SDK and creates nothing by
-itself. Once a project has `@aotter/mantle`, the installed package is the
-authority: `node_modules/@aotter/mantle/README.md` and
-`node_modules/@aotter/mantle/docs/`. Prefer them over this file, the SDK
-checkout, or any online copy.
-
-## Start with `mantle help`
-
-Run `mantle help` first (in a project: `npx mantle help`; before one exists:
-`npx @aotter/mantle@<exact version> help`). It prints the installed version's
-entry page and every topic; `mantle help <topic>` prints one page with the next
-and linked topics as commands. Follow it rather than browsing the SDK checkout
-or an online copy.
-
-## Find the project and its version
-
-Work in the user's application, outside the SDK checkout. Read package.json, the lockfile, installed SDK README and node_modules/@aotter/mantle/docs/. Those files define the exact version's contract. Preserve existing identity, handles, routes and resources.
-For existing older applications, use their installed docs until the user requests an upgrade; if an older version
-lacks a guide named here, record the missing guidance and keep that version's contract.
-
-## Choose the installed package skill
-
-- Read `node_modules/@aotter/mantle/docs/skills/develop/SKILL.md` to change an existing project's manifests, SQL, handlers, service entry or surfaces.
-- Read `node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` to add Mantle to an application with existing code, users or data.
-- Read `node_modules/@aotter/mantle/docs/skills/update/SKILL.md` to upgrade Mantle, including from 0.1.x.
-- Read `node_modules/@aotter/mantle/docs/skills/provision/SKILL.md` only for an authorized production deployment.
-- Read `node_modules/@aotter/mantle/docs/skills/media-gc/SKILL.md` only to audit or remove stale uncommitted media uploads.
-- Read `node_modules/@aotter/mantle/docs/skills/performance/SKILL.md` after acceptance converges, or when a page, first request or query is slow.
-
-## New application
-
-Node must be 22.22 or newer. Stable 0.2.0 is available as `@aotter/mantle@0.2.0`; pin selected Mantle packages to that exact version. Create it with `npx @aotter/mantle@<exact version> init <directory>`, then follow
-`mantle help` ("Build from a product brief") and the app's `README.md`. Without the user listing them, a complete app
-includes:
-
-- Email OTP sign-in, the two roles `admin` and `user`, Admin for `admin`, MCP for both roles (`/mcp`, `/mcp/admin`)
-  and REST: the shell already wires them; keep them.
-- Real business rules in SQL Procedures (`mantle help sql-patterns`), not in handler code around separate writes.
-- For visitor pages, everything in `mantle help public-pages` (SEO, AEO, sitemap, robots, `llms.txt`), styled.
-- Local HTTP checks (`mantle help local-testing`), then independent acceptance with `pnpm accept`
-  (`mantle help agent-workflow-acceptance`), then the installed `docs/skills/performance/SKILL.md`.
-
-Take patterns from `mantle help examples` into the app's own manifests and `src/`; do not copy an example directory
-over the app. Resolve each `AGENT:` or name the ones you left. Generation only, inside an app you already have: skip
-`init` and use `mantle generate` (`mantle help project-and-cli`).
-
-## Accept before reporting done
-
-Before reporting any new app or feature as done, follow `mantle help agent-workflow-acceptance`: a private rubric,
-then one fresh agent per role given only its role and the URLs `pnpm accept` prints, at most three rounds. The first
-delivery covers every role and surface; after a repair, the guide's "Re-verify what a repair touches" rule decides what
-re-runs: a page-only repair re-runs the affected UI, while auth, scope, SQL Procedure, unique index or shared-transport changes widen
-to every surface they reach. State the round and revision of any evidence you reuse. If it was
-not run, report the work as UNVERIFIED rather than done; if it could not run, BLOCKED. Report status per layer as that
-guide's "Report done-ness in layers" defines; a block from your environment (approval policy, missing browser,
-network) is BLOCKED on its layer, not a product failure, and does not discard the other layers.
-
-Once acceptance is CONVERGED, read the installed `docs/skills/performance/SKILL.md`: it decides which of front end,
-cold start and backend load apply, and runs them before you report done. This is the one exception to installed docs
-winning: if the installed package predates that skill, read
-[the 0.2.1 copy](https://github.com/aotter/mantle/blob/v0.2.1/docs/skills/performance/SKILL.md) and the pages it links
-from the installed docs with `mantle help <topic>`.
-
-## Deployment
-
-Deploy only when the user requests it, following the installed `docs/skills/provision/SKILL.md` and the selected
-host's native workflow. Local project creation alone is not deployment authorization.
-
-## Existing project and handoff
-
-Preserve the user's manifests, `src/` files, identity, package versions and provider resources. Run the project's
-generate command with `--check` and its own tests before and after a change.
-
-Report the project path, the exact Mantle version, what you changed, the four-layer status with each layer's checks
-and results (the independent acceptance verdict, CONVERGED / BLOCKED / UNVERIFIED, is layer 3), the performance verdict
-(PASS / PARTIAL / SKIPPED) with its before and after numbers, and anything left for the user, including what would
-unblock a BLOCKED layer.
+This skill only routes; it holds no contract. The installed `@aotter/mantle` is the authority, and `mantle help` prints
+its docs one topic at a time.
+
+1. **Start with `mantle help`.** In a project run `npx mantle help`; before one exists, `npx @aotter/mantle@<exact
+   version> help`. It prints the entry page (how to choose, build and accept); `mantle help <topic>` prints one page and
+   ends with the commands for the pages it links. `mantle help topics` lists them all. For a new app, do every step of its
+   "Build from a product brief". Follow it rather than this file, an SDK checkout or an online copy.
+2. **Work in the user's application.** Read its `package.json` and lockfile for the exact Mantle version and keep using
+   that version's docs until the user asks to upgrade (`mantle help releases/index`). Preserve existing code, identity,
+   versions and resources.
+3. **Plan once, then run to the end.** For a new app, first reply with the entry page's plan, in plain business terms
+   and with the questions the brief leaves open, and wait for one go-ahead. Then build, show the Developer UI, accept
+   and measure without stopping. Never report done without acceptance and performance; end with what each found and
+   changed, and each layer as CONVERGED, BLOCKED or UNVERIFIED.
+4. **Deploy, delete remote data or publish nothing unless the user asks for that exact action.**

package/docs/skills/develop/SKILL.md

@@ -1,100 +0,0 @@
----
-name: develop
-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
-  applies_to: mantle 0.2
-  projection: package
----
-
-# Mantle Develop
-
-## 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. After a repair, re-run
-the scope its [re-verification
-rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
-names and state which evidence you reused. This is not limited to
-MCP; if it was not run, say so explicitly and report the work as UNVERIFIED
-rather than done. Hand off with the guide's [layered
-report](../../handbook/guides/agent-workflow-acceptance.md#report-done-ness-in-layers):
-an environment block is BLOCKED on its layer, never a product failure. For MCP workflows, also run the guide's design audit before implementing
-tools. Once acceptance converges, follow the [performance skill](../performance/SKILL.md) before reporting done.
-
-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).
-Custom structured inputs and browser pages can use the optional
-`@aotter/mantle-admin/media` controlled `MediaPicker`: pass `readOnly` and an exact
-`uploadPurpose` (omit for selection only), apply `onSelect` to the local draft,
-and keep its import out of the MCP App entry. See the native Admin media example.
-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 published-content replacement with preview and rollback, follow `mantle help revisions`: Core supplies OCC, Schema locks and atomic `store.batch`; the recipe binds the previewed revision ID/version and atomically seals it while switching the parent. Applications own retention and review policy; Core does not mandate a preparation step. Keep the previewed version on submit and require another preview after a revision conflict.
-Use its custom Native Admin preview/switch page: freeze the reviewed content and both row versions, then submit them through the authorized operation. Do not make editors copy version numbers or silently replace the reviewed snapshot after a refresh; conflicts require another explicit preview.
-
-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

@@ -1,51 +0,0 @@
----
-name: integrate
-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 0.2
-  projection: package
----
-
-# Integrate Mantle into an existing application
-
-## 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. Before reporting user-facing work done, run
-[independent acceptance](../../handbook/guides/agent-workflow-acceptance.md), then the
-[performance skill](../performance/SKILL.md).
-
-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

@@ -1,109 +0,0 @@
----
-name: media-gc
-description: Audit and safely remove stale, uncommitted media uploads from a Mantle 0.2 Cloudflare R2 bucket. Use when an operator asks to inspect or clean objects left under uploads/ by an upload that was created but never committed.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/media-gc/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
-  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
----
-
-# 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`, 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
-   R2 List Objects and Delete Objects endpoints. If the connected account lacks
-   access, stop. Do not create, request, or store credentials.
-4. Stop when the service passes no `r2MediaStorage` or declares no purpose.
-
-## How 0.2 lays out media
-
-`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 `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
-
-For each declared purpose, list up to 1,000 objects per page under the exact
-`uploads/<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
-
-An object is a deletion candidate only when all conditions hold:
-
-- `last_modified` is more than 24 hours old;
-- `custom_metadata.committedAt` is absent or empty;
-- the key matches the exact upload layout
-  `uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)`,
-  where `<purpose>` is declared by this project and `<group>` contains only
-  letters, digits, `_`, or `-`.
-
-Skip committed, unknown-prefix, unprefixed, malformed, or ambiguous objects.
-Delete only an uncommitted variant, never its whole group.
-
-Report the account, bucket, purpose prefixes, UTC cutoff, candidate object and
-group counts, total bytes, skipped count, and a SHA-256 digest of the sorted
-`key + etag` candidate set. Do not print object keys, upload group IDs,
-filenames, public URLs, signed URLs, or secrets.
-
-## Apply
-
-1. Show the audit summary and get explicit confirmation for that exact account,
-   bucket, cutoff, count, byte total, and candidate-set digest.
-2. Re-run the complete audit with the same UTC cutoff. If the candidate count,
-   bytes, or digest changed, stop and present the new audit for confirmation.
-3. Call Delete Objects with JSON arrays of exact keys, at most 1,000 keys per
-   request. Never send the `prefix` query parameter: an empty prefix can empty
-   the bucket.
-4. Do not automatically retry failed keys. Report safe API error codes and
-   counts; a later invocation can audit and retry what remains.
-5. Re-list every inspected purpose prefix and report the remaining candidate
-   count and bytes.
-
-## Don't
-
-- Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
-- Don't use prefix deletion or empty-bucket operations.
-- Don't delete objects outside `uploads/<declared purpose>/`, and never
-  committed media.
-- Don't treat missing pagination pages, metadata, or permissions as an empty
-  result.
-
-## Diagnostics
-
-| Symptom | Action |
-|---|---|
-| Multiple matching accounts or buckets | Stop and ask the user to select the exact target. |
-| A page is truncated without a cursor | Stop; do not delete from a partial audit. |
-| A candidate has an unexpected key or metadata shape | Skip it and include it only in the aggregate skipped count. |
-| A delete request partially fails | Report safe error codes and leave the remaining objects for a later audit. |
-
-## When You're Done
-
-Return whether the run was audit-only or applied, the aggregate before/after
-counts and bytes, and any safely redacted failures.

package/docs/skills/provision/SKILL.md

@@ -1,44 +0,0 @@
----
-name: provision
-description: Ship a Mantle 0.2 project to production — Cloudflare Workers with D1, production sign-in and secrets, or ChatGPT Sites through its guide — and verify the deployed service.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/provision/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
-  projectionReason: Creates remote resources and handles production secrets; opt-in only.
----
-
-# Provision a Mantle project
-
-## 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

@@ -1,42 +0,0 @@
----
-name: update
-description: Upgrade a Mantle project's @aotter/mantle packages to a new exact version, including the move from 0.1.x to 0.2, without overwriting application-owned code.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/update/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
----
-
-# Mantle Update
-
-## Workflow
-
-Read the installed SDK README, then follow the version-matched [project and CLI
-workflow](../../handbook/start/project-and-cli.md) before editing.
-
-For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md). Mantle
-ships no migration tool: plan the data move from
-[Moving data from 0.1.x](../../upgrade-0.1-to-0.2.md#moving-data-from-01x),
-verify each fact against the generated `schema.sql` and the 0.1.4 export, and
-have the plan reviewed. Give the 0.2 service a new database, rehearse the load
-on a copy, never boot 0.2 against a 0.1.x database, and keep exports out of the
-repository. The guide's appendix is historical; do not follow it. Between 0.2
-versions, apply reviewed migrations rehearsed on a copy.
-
-For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; to try the 0.2.1 prerelease, pin all of them to `0.2.1-alpha.2` and read its release notes. Do not upgrade an existing application by following a moving dist-tag.
-
-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.
-
-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.