@aotter/mantle 0.2.1-alpha.1 → 0.2.1-alpha.3

package/docs/handbook/releases/index.md

@@ -15,6 +15,23 @@ From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
 and `@aotter/mantle-admin` (optional Admin server, SPA and MCP App).
 Pin every package you use to the same exact version and upgrade them together.
 
+## Upgrade an application
+
+1. Pin every Mantle package to the same exact published version; never follow a dist-tag. Read every release section
+   between your version and the target, including its breaking changes.
+2. Regenerate with the project's own command and review the emitted TypeScript, SQL and policy diffs. A schema change
+   needs a data-preserving migration written with the host's tool and rehearsed on a copy
+   ([Install and change schemas](../cloudflare/deploy-and-operate.md#install-and-change-schemas)); the initial
+   `schema.sql` never rebuilds production tables.
+3. Keep users, sessions, content and application code. Follow [Customising Admin](../guides/native-admin.md#customising-admin)
+   for the application-built Admin; old UI subpaths have no aliases.
+4. Re-run the project's checks, member and Admin OTP, affected REST/MCP/Admin routes, private-field visibility, OCC and
+   unknown outcomes, then [acceptance](../guides/agent-workflow-acceptance.md) before an authorized cutover. Updating a
+   dependency never publishes a package.
+
+From 0.1.x, follow [Upgrade 0.1 to 0.2](upgrade-0.1-to-0.2.md) instead: a new database, a reviewed and rehearsed data
+move, and never booting 0.2 against a 0.1.x database.
+
 ## 0.2.1 — in preparation
 
 0.2.1 adds Schema locks: a manifest rule that refuses a row's update or delete
@@ -33,6 +50,72 @@ and interactive transactions can use `store.batch` for atomic multi-writes, and
 `mantle bundle` under `wrangler dev` reports stale generated output in one line
 instead of a failed build.
 
+### Upgrading to 0.2.1-alpha.3
+
+- **Agent guidance has one home, the handbook.** The package no longer ships `docs/skills/`, so the `mantle help
+  skills/<name>` topics are gone. Their guidance is now in handbook pages:
+  [performance pass](../guides/performance.md),
+  [deploy and operate](../cloudflare/deploy-and-operate.md),
+  [cleaning up stale uploads](../cloudflare/media-r2.md#clean-up-stale-uploads),
+  [upgrading an application](#upgrade-an-application) and
+  [adoption in an existing app](../guides/typed-queries.md#adopt-mantle-in-an-existing-application).
+  `mantle help` reaches all of them from the entry page.
+- **The `mantle` skill no longer depends on the SDK version.** It routes to `mantle help`, so
+  `npx skills add aotter/mantle@mantle` no longer needs a release tag. A skill installed from an earlier tag still
+  names `docs/skills/` paths; reinstall it.
+- **Docs moves.** The 0.1 → 0.2 upgrade guide is now the topic `mantle help upgrade-0.1-to-0.2`. The package README is
+  an index of topics.
+- **The agent workflow checks in with the user.** Once the manifests generate, `pnpm accept --open` opens the Developer
+  UI (`/admin/dev`) so the user can see the wiring. The agent then stops twice with a plan: before acceptance and
+  before the performance pass. It finishes with an acceptance summary and a before → after performance summary
+  ([agents](../start/agents.md)).
+
+Regenerate to pick up the rest of this release. No manifest or API changes:
+
+- **Developer UI diagrams.**
+  - The data model is a real ER diagram: keys, types and crow's-foot cardinality, with three display modes.
+  - System wiring is laid out in columns, with a minimap.
+  - A Procedure's logic is one graph, the same in the wiring side panel and on the Procedure page: a transaction box,
+    CASE as ordered branch rows, and COMMIT and ROLLBACK ends. The SQL syntax trees stay available, folded, on the
+    Procedure page.
+  - Their wording is translated in every Admin language that has translations.
+- **Smaller startup.**
+  - Generated Workers emit a repeated SQL statement once. REST loads a Procedure on its first request, the way views and
+    MCP already did. The reference D1 Worker's startup is about 20% smaller.
+  - Admin loads sign-in, OAuth consent and the collection list on demand.
+  - The Admin MCP App uses native select and popover controls.
+
+### Upgrading to 0.2.1-alpha.2
+
+Pin the selected packages to `0.2.1-alpha.2` and regenerate. Breaking change:
+
+- **`@aotter/mantle/describe`** keeps only `matchTarget` and the
+  `AppDescription`, `DescribeTarget` and `TargetRequest` types. `describeApp`,
+  `diffApp` and the `@aotter/mantle/target-hash` subpath are removed.
+  **`mantle describe` output is the supported way to get a description outside
+  the CLI:** run `mantle describe <target> manifests/*.yaml > describe.json` in
+  Node.js or Bun (for example in a deploy step) and give the JSON to
+  `matchTarget`. Do not import compiler files from `dist`; a Worker cannot
+  compile manifests that contain SQL ([describe](../reference/describe.md)).
+  Use `mantle describe --diff` instead of `diffApp`, and `_meta.targetHash`
+  instead of `targetHash()`.
+
+Hand-built MCP tools gain three opt-in capabilities; without them the output
+is unchanged ([MCP Apps](../guides/mcp-apps.md), [surface](../reference/surface.md)):
+
+- `Tool.meta` merges into the tool's listed `_meta`. `ui.visibility: ["app"]`
+  can now hide a Procedure from clients without MCP Apps; it is a listing hint,
+  and calls are authorized as before.
+- `withResultMeta(data, meta)` returns `meta` only in the result `_meta`, so a
+  value such as a signed upload URL stays out of `content`. `callTool` returns
+  `{ data, _meta }`; drop `_meta` before forwarding a result to a model.
+- `toolsPageSize` pages `tools/list` with an opaque `nextCursor`.
+
+Also: generation reports a SQL parser that cannot load in the current runtime
+as such, instead of `SQL_SYNTAX`, and the handbook renders under Vue-based
+site generators (bare `<placeholder>` text is now quoted, and `pnpm check`
+fails on any that return).
+
 ### Upgrading to 0.2.1-alpha.1
 
 Pin `@aotter/mantle`, and any selected `@aotter/mantle-ui` and
@@ -68,7 +151,7 @@ and deployment; selected REST, MCP, public pages, publishing, translations and
 media compose around the generated operations.
 
 This is a breaking upgrade from 0.1.x: follow the [0.1-to-0.2 migration
-guide](../../upgrade-0.1-to-0.2.md), use a new 0.2 database and explicitly move
+guide](upgrade-0.1-to-0.2.md), use a new 0.2 database and explicitly move
 data. From alpha.11, pin the three selected packages to 0.2.0, regenerate and
 review owned output; the stable version commit changes release metadata and
 documentation rather than adding another runtime API.
@@ -185,7 +268,7 @@ the native migration above supersede their runtime and CLI instructions.
 
 0.2.0 replaces 0.1.x's grammar and composition; no stable 0.1.5 was released
 (`0.1.5-alpha.1` was a prerelease). It breaks every consumer, and
-`docs/upgrade-0.1-to-0.2.md` in the package is the guide for moving a project
+`mantle help upgrade-0.1-to-0.2` is the guide for moving a project
 by hand.
 
 - **Manifests are `cms.mantle.aotter.net/v2`.** Views are one SQL `SELECT` and

package/docs/{upgrade-0.1-to-0.2.md → handbook/releases/upgrade-0.1-to-0.2.md}

@@ -5,11 +5,11 @@ migration tool and no in-place upgrade of a 0.1.x database: a coding agent
 rebuilds the project on 0.2.0 and plans a reviewed data move for it.
 
 1. **Rebuild the project on 0.2.0** with the current handbook: the
-   [0.2.0 release notes](handbook/releases/index.md#upgrading-to-020) and the
-   [native SDK migration](handbook/releases/index.md#native-sdk-migration-alpha7),
-   the [CLI and generated ownership](handbook/start/project-and-cli.md), the
-   [app shell](examples/app-shell/) and the [Schema](handbook/reference/schema.md),
-   [View](handbook/reference/view.md) and [Procedure](handbook/reference/procedure.md)
+   [0.2.0 release notes](index.md#upgrading-to-020) and the
+   [native SDK migration](index.md#native-sdk-migration-alpha7),
+   the [CLI and generated ownership](../start/project-and-cli.md), the
+   [app shell](../../examples/app-shell/) and the [Schema](../reference/schema.md),
+   [View](../reference/view.md) and [Procedure](../reference/procedure.md)
    references. The application owns routing, Auth, native handles and database
    migrations. Install the same exact version of `@aotter/mantle`,
    `@aotter/mantle-ui` and, when selecting Admin, `@aotter/mantle-admin`.
@@ -44,18 +44,18 @@ for human review before it touches production data.
 
 - **Through the SDK.** The generated `store(db, caller)`, or `ctx.store` in a
   `ref` handler, with a trusted caller such as `{ kind: "system", reason }`
-  ([authorization](handbook/concepts/authorization.md)). It accepts no value
+  ([authorization](../concepts/authorization.md)). It accepts no value
   for `id`, `version`, `created_at`, `updated_at`, `author_id`, `status`,
   `published_at` or the scope column, for any caller: it sets them itself, so new IDs, versions,
   timestamps and authors replace the old ones. Publishing goes through the
   generated `<schema>.publish` Procedure, which sets `published_at` to now
-  ([lifecycle](handbook/concepts/lifecycle-and-locales.md)). With new IDs,
+  ([lifecycle](../concepts/lifecycle-and-locales.md)). With new IDs,
   remap every `x-mantle-ref`, every `translates.on` key and any ID embedded
   in JSON; `x-mantle-ref` is not a foreign key, so a missed one dangles
   quietly.
 - **Through SQL**, to keep IDs, history and authors: `INSERT` the rows with
   every native column set, as
-  [reserved entry columns](handbook/reference/schema.md#reserved-entry-columns)
+  [reserved entry columns](../reference/schema.md#reserved-entry-columns)
   lists. This bypasses row policy, so review it like a migration.
 
 ### Entry columns on D1
@@ -86,7 +86,7 @@ for human review before it touches production data.
 
 0.1.4 used Better Auth 1.7.2 with hand-written DDL; 0.2.0 uses 1.7.7, with the
 tables `mantle generate --auth src/auth.ts` adds to `schema.sql`
-([auth](handbook/cloudflare/authentication.md)).
+([auth](../cloudflare/authentication.md)).
 
 - The 0.2 caller subject is the Better Auth `user.id`. Keep user IDs, so that
   `author_id` and owner scopes still name the right people.
@@ -97,13 +97,13 @@ tables `mantle generate --auth src/auth.ts` adds to `schema.sql`
 - 0.1.4 roles `owner`, `editor` and `contributor` have no 0.2 meaning. The
   admin layer is Better Auth's admin plugin `adminRoles` (default
   `["admin"]`) and `adminUserIds`
-  ([authorization](handbook/reference/authorization.md)); decide each mapping
+  ([authorization](../reference/authorization.md)); decide each mapping
   deliberately.
 - A 0.1.4 `githubLogin` column must be declared in `user.additionalFields`
   to keep it.
 - Leave sessions, verification rows and OAuth tokens behind; users sign in
   again. Mantle re-creates its OAuth resource rows from configuration
-  ([OAuth](handbook/guides/oauth.md)). Check `jwks`, OAuth clients and
+  ([OAuth](../guides/oauth.md)). Check `jwks`, OAuth clients and
   consents against Better Auth 1.7.7 and your secrets and URLs before copying
   any.
 - The admin MCP endpoint moved from `/mcp/staff` to `/mcp/admin`; update MCP
@@ -115,7 +115,7 @@ tables `mantle generate --auth src/auth.ts` adds to `schema.sql`
   epoch **milliseconds**. Copy the rows as they are.
 - Each variant keeps its stored `storageKey` and `publicUrl`, so 0.1.x objects
   in the same bucket keep working while their prefixes stay served
-  ([media](handbook/cloudflare/media-r2.md)).
+  ([media](../cloudflare/media-r2.md)).
 - Do not carry over `pending_media_uploads`; an upload expires after 15
   minutes.
 - `site_config` keeps its `key`/`value` columns; compare its keys with the
@@ -256,7 +256,7 @@ Schema reference; do not repeat them.
 | 0.1.x | 0.2.0 |
 |---|---|
 | builtin `create` | `handler: { sql: "INSERT INTO s (a, b) VALUES (input.a, input.b) RETURNING id" }` (on a `publishing` Schema the row starts as a draft, as before) |
-| builtin `update` (always version-checked, merges over the stored row) | `UPDATE s SET a = COALESCE(input.a, a), … WHERE id = input.id AND version = input.expectedVersion`. Keep both: without the version the lock is lost; without `COALESCE` an omitted optional field is cleared. `COALESCE` also means `null` cannot clear a field; give clearing its own flag input ([clear flag](handbook/guides/sql-patterns.md#change-only-the-fields-given-coalesce), [leave out, replace or clear](handbook/guides/native-admin.md#leave-out-replace-or-clear)) |
+| builtin `update` (always version-checked, merges over the stored row) | `UPDATE s SET a = COALESCE(input.a, a), … WHERE id = input.id AND version = input.expectedVersion`. Keep both: without the version the lock is lost; without `COALESCE` an omitted optional field is cleared. `COALESCE` also means `null` cannot clear a field; give clearing its own flag input ([clear flag](../guides/sql-patterns.md#change-only-the-fields-given-coalesce), [leave out, replace or clear](../guides/native-admin.md#leave-out-replace-or-clear)) |
 | builtin `upsert` with `match` | `INSERT … ON CONFLICT (<match columns>) DO UPDATE SET x = EXCLUDED.x`; the conflict columns are a unique index; on a scoped Schema the scope field may be named or left out, Store adds it |
 | builtin `delete` | `DELETE FROM s WHERE id = input.id AND version = input.expectedVersion` |
 | builtin `archive` | a `ref` handler: `ctx.store.write([{ update: "s", set: { status: "archived" }, where: { id }, lock: expectedVersion }])` (SQL cannot set `status`) |

package/docs/handbook/start/agents.md

@@ -7,12 +7,14 @@ description: "The entry point `mantle help` prints first: choose a complete app
 Topics are the handbook paths below (for example `guides/native-admin`) or their last segment when unique (`native-admin`).
 The installed package's `docs/` is the source of every topic, so the text always matches the installed version.
 
+Node 22.22 or newer. Pin every `@aotter/mantle*` package to one exact version.
+
 ## Choose how much Mantle owns
 
 | You want | Do |
 | --- | --- |
 | A complete application | `mantle init [directory]`, then follow its `README.md`. It writes the app shell once: Better Auth email OTP with `admin` and `user`, the Admin console, MCP for both roles, REST, and a member `/sign-in` page. Existing files stop it; `--dry-run` lists what it would write. |
-| Only typed SQL and bindings inside an app you already have | Skip `init`. Write manifests and run `mantle generate <target> <output-directory> <manifest>...`; see `mantle help project-and-cli` and `mantle help typed-queries`. |
+| Only typed SQL and bindings inside an app you already have | Skip `init`. Write manifests and run `mantle generate <target> <output-directory> <manifest>...`; see `mantle help project-and-cli` and [adopting Mantle in an existing app](../guides/typed-queries.md#adopt-mantle-in-an-existing-application). |
 
 `init` writes the `cloudflare-d1` shell, the default target. `bun-sqlite`, `bun-postgres` and `cloudflare-postgres`
 generate the same bindings; their app entry is yours (`mantle help service-entry`).
@@ -36,14 +38,33 @@ the app entry (`--entry`) never imports, it warns and names the topic that shows
      canonical and Open Graph tags, JSON-LD and an answer block on detail pages, Markdown alternates, `/sitemap.xml`,
      `/robots.txt` and `/llms.txt`. A brief that names a site, shop or catalogue for visitors includes all of them.
 4. `pnpm generate`, implement every handler it lists, `pnpm check`, then `pnpm smoke`.
-5. Before reporting the app or a feature done, run [role-only acceptance](../guides/agent-workflow-acceptance.md)
+5. **Show the user the wiring.** As soon as the manifests generate, run `pnpm accept --open`: it starts the app,
+   signs the admin in without a one-time code and opens the Developer UI (`/admin/dev`) in the user's browser, showing
+   the Schemas, Views, Procedures and Triggers and how they connect, with each surface's routes and tools. Tell the user
+   what they are looking at. Keep building while they look; the app rebuilds on every change. Without a browser on the
+   machine, give the user the admin URL it prints.
+6. **Stop and ask before acceptance.** Propose the [acceptance plan](../guides/agent-workflow-acceptance.md#propose-the-run-first)
+   and wait for the user's go-ahead. Then run [role-only acceptance](../guides/agent-workflow-acceptance.md)
    (`mantle help agent-workflow-acceptance`). Scripted smoke is not acceptance. `pnpm accept` starts the app and hands
    each role to a fresh evaluator as a URL that carries that role's session. After a repair, the guide's
    [re-verification rule](../guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches) decides which roles
    and surfaces run again.
-6. Once acceptance converges, follow the [performance skill](../../skills/performance/SKILL.md): it decides which of
-   front end (Lighthouse), cold start and backend load apply, and holds each to a target before you report done.
+7. **Stop and ask before the performance pass.** For every role and surface acceptance reports CONVERGED, propose the
+   [performance plan](../guides/performance.md#propose-the-pass-first) (which parts run, how much test data, which
+   targets) and wait for the go-ahead; then run the [performance pass](../guides/performance.md). BLOCKED or UNVERIFIED
+   parts are reported as they are, never optimized. A declined step is reported as not run, never as done.
+8. **Report what changed, not only that it passed:** the [acceptance summary](../guides/agent-workflow-acceptance.md#summarise-for-the-user)
+   and the [performance summary](../guides/performance.md#summarise-for-the-user), then the layered status.
 
 The first verified sign-in with `ADMIN_EMAIL` becomes the admin. Further administrators are added in Admin:
 **More → Administrators** invites by email, and **More → Members** grants Admin to an existing member.
 [Authentication](../cloudflare/authentication.md#identity-helpers) documents the same operations as an API.
+
+## Other tasks
+
+| Task | Read |
+| --- | --- |
+| Upgrade Mantle | [Upgrade an application](../releases/index.md#upgrade-an-application) |
+| Deploy, only when the user asks | [Deploy and operate](../cloudflare/deploy-and-operate.md) |
+| A slow page, first request or query | [Performance pass](../guides/performance.md) |
+| Stale media uploads, only when the user asks | [Clean up stale uploads](../cloudflare/media-r2.md#clean-up-stale-uploads) |

package/docs/handbook/start/quickstart-worker.md

@@ -3,7 +3,7 @@ description: Generate a small native D1 service and mount an application-owned W
 ---
 # Quickstart: a service on Workers
 
-Create an application outside the SDK checkout. Install `@aotter/mantle@0.2.1-alpha.1` exactly (a prerelease; stable 0.2.0 has its own tagged handbook), TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2 contract.
+Create an application outside the SDK checkout. Install one exact `@aotter/mantle` version ([Releases](../releases/index.md)), TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2 contract.
 
 Save `manifests/tickets.yaml`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.1-alpha.1",
+  "version": "0.2.1-alpha.3",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -68,8 +68,7 @@
     "./json-body": "./dist/kernel/json-body.js",
     "./generate/auth": "./dist/infrastructure/generateAuth.js",
     "./package.json": "./package.json",
-    "./describe": "./dist/domain/describe/index.js",
-    "./target-hash": "./dist/domain/describe/target-hash.js"
+    "./describe": "./dist/domain/describe/public.js"
   },
   "peerDependencies": {
     "@modelcontextprotocol/server": "2.3.1",

package/skills/README.md

@@ -1,71 +1,9 @@
-# SKILL.md briefs (mantle)
+# Mantle agent skill
 
-Agent-readable skills for consumers of `@aotter/mantle` 0.2. There are two
-distributions (ADR-0032 decision 13):
+[`mantle`](mantle/SKILL.md) is the one consumer skill, shipped by the plugins and by `npx skills add aotter/mantle@mantle`.
+Installation: [agent setup](../docs/handbook/guides/agent-setup.md).
 
-- **The plugin** ships one OSS authoring skill, [`mantle`](mantle/SKILL.md),
-  without a hosted-service MCP connection or transport.
-- **The npm package** ships the workflow skills under `docs/skills/`. An agent
-  reads them from `node_modules/@aotter/mantle/docs/skills/`, matched to the
-  installed version. Nothing copies them into a project; 0.2 has no
-  `mantle skills` command.
-
-| Skill | When to invoke |
-|---|---|
-| [`mantle`](mantle/SKILL.md) | Create or continue a Mantle application and deploy to a user-owned host. |
-| [`develop`](../docs/skills/develop/SKILL.md) | Change manifests, SQL, handlers, the service entry or surfaces of an existing project. |
-| [`integrate`](../docs/skills/integrate/SKILL.md) | Add Mantle to an application that has its own code, users or data, or rebuild one and migrate. |
-| [`update`](../docs/skills/update/SKILL.md) | Upgrade `@aotter/mantle`, including from 0.1.x. |
-| [`provision`](../docs/skills/provision/SKILL.md) | Ship to Cloudflare Workers or ChatGPT Sites with production sign-in. |
-| [`media-gc`](../docs/skills/media-gc/SKILL.md) | Audit or remove stale, uncommitted R2 uploads. |
-| [`performance`](../docs/skills/performance/SKILL.md) | Make an accepted app fast: Lighthouse, cold start, backend load, indexes and Views. Runs after acceptance converges. |
-
-## Install
-
-Use the [agent setup guide](../docs/handbook/guides/agent-setup.md) for Codex,
-Claude Code, Cursor and GitHub Copilot. Pin the plugin checkout to the same
-release tag as the application's SDK; alpha releases on `develop` can be newer
-than the default `main` branch. For a skill-only installation:
-
-```sh
-npx skills add aotter/mantle@mantle
-```
-
-Without a version it follows `main`, the latest stable release; pin the SDK's
-release tag with `npx skills add aotter/mantle#v0.2.1-alpha.1@mantle`.
-The explicit skill name (`@mantle`) excludes repository maintainer skills. The manifests
-are generated by `scripts/sync-plugin-manifests.mjs` and checked with `--check`.
-When upgrading, update the marketplace ref or local tagged checkout and refresh
-the plugin. Verify the loaded manifest version; Claude Code's plugin version
-is Core's, so packaged skill changes reach users through the next Core release.
-
-## Disclosure audit
-
-Every skill is one `SKILL.md`; the plugin skill carries local acceptance references.
-`scripts/check-skills.mjs` holds this table, the front matter and the links to
-each other: `metadata.projection` is `plugin` for `skills/mantle` and
-`package` for `docs/skills/*`, a reason in the last column must equal
-`metadata.projectionReason`, and a relative link must stay inside what ships
-(the skill's own directory for the plugin, `docs/` for the package).
-
-| Skill | Routes on | Entry constraints | Distribution | Restricted because |
-|---|---|---|---|---|
-| `mantle` | new project, existing project, self-host deployment | the installed package's docs win; never use the SDK checkout as the application; no deploy during a cold start | plugin | The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package. |
-| `develop` | manifest, SQL, handler, service or surface work | read the installed version first; never edit generated files; writes through Store/Procedures, richer reads through internal Views | package | — |
-| `integrate` | an application with its own code, users or data | inspect before choosing; the application keeps its users; one writer per table | package | — |
-| `update` | an SDK upgrade | never overwrite application files; 0.1.x moves by the upgrade guide to a new database | package | — |
-| `provision` | ship to production | secrets never in source, chat or logs; a new database for 0.2; self-hosting is always an option | package | Creates remote resources and handles production secrets; opt-in only. |
-| `media-gc` | stale R2 uploads | audit by default; exact keys only, never a prefix delete; re-audit before applying | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
-| `performance` | converged acceptance, a slow page, first request or query | accepted behavior only; never trade scope, authorization, OCC or atomicity for speed; local unless deployment is authorized | package | — |
-
-## Audience
-
-These are for **AI agents acting for consumers of Mantle**, not for
-contributors to the SDK, who read the repository's `CONTRIBUTING.md`.
-
-## Conventions
-
-Each SKILL.md has front matter (`name`, a trigger-complete `description`,
-`metadata.source`, `sourcePath`, `applies_to`, `projection`), the reads to do
-first, concrete commands, the rules an agent must not break, and what to report
-when done. Commands and prose match the package version that carries the skill.
+The skill only routes to `mantle help`, which prints the installed package's handbook. It holds no contract, version
+number or workflow detail of its own, so it never drifts from the SDK an application pins: put any rule an agent must
+follow in the handbook instead. `scripts/check-skills.mjs` enforces that this is the only skill, its front matter, a
+line budget, no version strings, and that every `mantle help <topic>` it names exists.

package/skills/mantle/SKILL.md

@@ -1,90 +1,24 @@
 ---
 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. **Stop for the user at the entry page's checkpoints:** show the running Admin and its Developer UI once the manifests
+   generate, and ask before acceptance and before the performance pass. Never report done without them; end with what
+   each one 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/dist/domain/describe/target-hash.js

@@ -1 +0,0 @@
-import{canonical,hash,hashDefinition,targetHash}from"./chunk-P6PP6VVV.js";export{canonical,hash,hashDefinition,targetHash};

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.