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

package/docs/{skills/performance/SKILL.md → handbook/guides/performance.md}

@@ -1,26 +1,21 @@
 ---
-name: performance
-description: Make an accepted Mantle 0.2 application fast — Lighthouse for app-authored pages, Worker cold start and first-load budgets, and backend reads and writes under realistic data volume with indexes and internal Views. Use right after independent acceptance converges, or when a user reports a slow page, first request or query.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/performance/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
+description: "After acceptance converges, or when something is slow: front end, cold start and backend load, each held to a target."
 ---
+# Performance pass
 
-# Mantle Performance
-
-This skill sets direction: when to run, what to aim for, in what order and when
+This page sets direction: when to run, what to aim for, in what order and when
 to stop. It names no tools or commands. Choose the measurement and repair
 methods that fit the application, its host and the tools available to you; the
 targets and rules below are what stay fixed.
 
 ## When to run
 
-- **After acceptance.** Once [independent acceptance](../../handbook/guides/agent-workflow-acceptance.md)
-  reports CONVERGED for a new application or a feature, continue here before
-  reporting done. Never optimize behavior that has not been accepted: after
-  BLOCKED or UNVERIFIED, report that and stop.
+- **After acceptance.** Run for every role and surface that
+  [independent acceptance](agent-workflow-acceptance.md)
+  reports CONVERGED for a new application or a feature, before reporting done.
+  Never optimize behavior that has not been accepted: report each BLOCKED or
+  UNVERIFIED role or surface as it is, with what it needs, and leave it out of
+  the pass. Stop without running only when no part is CONVERGED.
 - **On request.** When a user reports a slow page, slow first request or slow
   query, run only the part that covers it, then check the others it could affect.
 
@@ -40,6 +35,16 @@ skipped part with its reason.
 A change in one part can move another: an added index slows writes, a shared
 stylesheet or entry import affects every page. Re-measure what a repair can reach.
 
+## Propose the pass first
+
+Before measuring, stop and give the user the plan, then wait for a go-ahead:
+
+- the parts that run and the parts skipped, each with its reason (the table above);
+- the test data for backend parts: rows per table (for example 1,000,000 RSVPs across 5,000 events and 20,000
+  members), its shape (owners, states, text length) and that it goes only into an isolated local database;
+- the target for each part and the stop rule below;
+- anything that needs the user, such as a deployment to measure real cold start.
+
 ## Front end
 
 **Target:** the highest Lighthouse performance score the page allows, with a
@@ -51,7 +56,7 @@ no regression in accessibility, SEO or best practices.
   (no compression or HTTP/2, a cold cache) and say which is which.
 - Measure pages behind sign-in (member pages, Admin) through the role's session
   URL that `pnpm accept` prints
-  ([hand each role](../../handbook/guides/agent-workflow-acceptance.md#hand-each-role-to-its-evaluator)),
+  ([hand each role](agent-workflow-acceptance.md#hand-each-role-to-its-evaluator)),
   never by weakening sign-in.
 - Find the actual bottleneck before changing anything; a trace beats a guess.
 - Repair in this order: what blocks the first paint (render-blocking styles and
@@ -63,7 +68,7 @@ no regression in accessibility, SEO or best practices.
   without it. Never detect the measuring tool to serve it a different page.
 - After every change, prove nothing else moved: the page looks the same, links,
   forms and in-page anchors still work, and the
-  [public-page checks](../../handbook/guides/public-pages.md#check-before-you-report-done)
+  [public-page checks](public-pages.md#check-before-you-report-done)
   still pass without JavaScript.
 
 ## Cold start
@@ -72,9 +77,9 @@ no regression in accessibility, SEO or best practices.
 
 - **Worker:** its startup graph imports only what every request needs; auth, MCP,
   Admin and rarely used routes load on the request that uses them
-  ([size and startup](../../handbook/guides/size-and-startup.md)). On Workers the
+  ([size and startup](size-and-startup.md)). On Workers the
   startup graph is the entry chunk `mantle bundle` writes under `<outdir>/worker`
-  plus the chunks it imports statically ([outputs](../../handbook/start/project-and-cli.md#outputs));
+  plus the chunks it imports statically ([outputs](../start/project-and-cli.md#outputs));
   anything behind a dynamic import is outside it. Report its size locally as the
   *Worker entry static graph*; measure the host's startup time only on
   a deployment the user has authorized, and keep it well under the host's limit
@@ -87,7 +92,7 @@ no regression in accessibility, SEO or best practices.
   not measure it. Report the whole *MCP App HTML document* as its own number: it
   also holds CSS and markup, so never compare it with this budget.
 - Use the one definition of each metric in
-  [size metrics](../../handbook/guides/size-and-startup.md#size-metrics), with
+  [size metrics](size-and-startup.md#size-metrics), with
   its measurement. Where the SDK's own checks measure differently, that page says how.
 - An overrun is a finding to repair by splitting, not a budget to raise. Raise a
   budget only with the user's agreement and record why.
@@ -102,12 +107,12 @@ fast at a realistic volume, and no hot path scans a table that grows.
   text where fields allow it, and more than one page of results everywhere. Size
   the largest tables at 100,000 rows or 10 times the expected first-year volume,
   whichever is larger. Seed with SQL straight into that database, setting the
-  native columns as [reserved entry columns](../../handbook/reference/schema.md#reserved-entry-columns)
+  native columns as [reserved entry columns](../reference/schema.md#reserved-entry-columns)
   describes: it is test data, not an application write.
 - **Load:** call every View and Procedure through the same callers and surfaces
   the application uses, as each role. The app's local test harness already
   starts it on a fresh database, signs each role in and calls routes and MCP
-  tools as that role ([local HTTP checks](../../handbook/guides/local-testing.md#what-smoke-covers)).
+  tools as that role ([local HTTP checks](local-testing.md#what-smoke-covers)).
   Record typical and slow-tail latency and
   rows read, then run concurrent writers wherever contention matters. A business
   rule that breaks under concurrency (oversell, double approval, lost update) is
@@ -119,15 +124,15 @@ fast at a realistic volume, and no hot path scans a table that grows.
      query module under `generated/` against the seeded database; a full scan of a
      growing table is a finding.
   2. Add the index that serves it in the Schema's `indexes`
-     ([indexes](../../handbook/reference/schema.md#indexes-checks-and-search))
-     together with a native migration ([database changes](../develop/SKILL.md#database-changes)).
+     ([indexes](../reference/schema.md#indexes-checks-and-search))
+     together with a native migration ([database changes](../cloudflare/deploy-and-operate.md#install-and-change-schemas)).
      Index only what a measured query uses; every index costs writes. Paged Views
-     and [Schema locks](../../handbook/reference/schema.md#locks) are index-proven
+     and [Schema locks](../reference/schema.md#locks) are index-proven
      already: generation refuses one no index serves.
   3. Move complex reads (joins, aggregates, OR, reuse) into an
-     [internal View](../../handbook/guides/typed-queries.md#declare-an-internal-view),
-     page with keysets ([results and paging](../../handbook/reference/view.md#results-and-paging)),
-     and replace exact totals on hot paths ([search and totals](../../handbook/reference/view.md#search-and-totals)).
+     [internal View](typed-queries.md#declare-an-internal-view),
+     page with keysets ([results and paging](../reference/view.md#results-and-paging)),
+     and replace exact totals on hot paths ([search and totals](../reference/view.md#search-and-totals)).
   4. Re-measure reads and writes after each repair.
 
 ## Rules
@@ -139,17 +144,17 @@ fast at a realistic volume, and no hot path scans a table that grows.
 - Do not lower a target, shrink the seeded data or drop a slow case to pass.
   Report what is left instead.
 - Work locally. Deploying or measuring a deployment follows the
-  [provision skill](../provision/SKILL.md) and needs the user's authorization.
-- After any repair, rerun the [local HTTP checks](../../handbook/guides/local-testing.md).
+  [deploy guide](../cloudflare/deploy-and-operate.md) and needs the user's authorization.
+- After any repair, rerun the [local HTTP checks](local-testing.md).
   A repair that changes what a user sees or can do is no longer only a
   performance change: re-run acceptance for the scope the
-  [re-verification rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
+  [re-verification rule](agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
   names. A changed View or Procedure widens it to every surface that reads or
   writes that data, and so does a `uniqueIndexes` entry. A non-unique
   `indexes` entry and its migration keep the business rules: run `pnpm check`,
   the local HTTP checks and your focused regressions, not acceptance.
 - Report app-added cost and SDK-existing cost separately. Built-in Admin has a
-  recorded [baseline](../../handbook/guides/size-and-startup.md#native-admin-baselines)
+  recorded [baseline](size-and-startup.md#native-admin-baselines)
   per SDK version; while the installed version and Admin entry are unchanged,
   reuse it instead of repeating that experiment each round. Built-in Admin's
   page and MCP App both miss the first-load budget; that is SDK-existing cost,
@@ -160,10 +165,26 @@ fast at a realistic volume, and no hot path scans a table that grows.
 - Stop when every target is met, after three rounds, or when two rounds in a row
   bring no measurable gain.
 
+## Summarise for the user
+
+Report each change with the number it moved, so the gain is visible:
+
+```markdown
+| Part | Change | Before | After |
+| --- | --- | --- | --- |
+| Backend read: `event-roster`, 1,000,000 RSVPs | index `[eventId, created_at]` + keyset paging | p95 1,840 ms | p95 38 ms |
+| Front end: `/events/{slug}` (mobile) | inline critical CSS, sized images | Lighthouse 71 | 94 |
+| Cold start: Worker entry | auth and Admin behind dynamic imports | 212 KB gzip startup graph | 61 KB |
+```
+
+Give the data volume beside every backend number, the device and throttling beside every Lighthouse score, and say
+where a target is still missed and why.
+
 ## Report
 
 For each part: run or skipped (with the reason), the environment, before and
-after numbers as ranges, what changed and what is left. Close with one verdict
+after numbers as ranges, what changed and what is left. Name the roles and
+surfaces left out because acceptance did not converge on them. Close with one verdict
 beside the acceptance verdict: **PASS** (every target that applies is met),
 **PARTIAL** (improved, with the targets still missed and why) or **SKIPPED**
 (nothing applied).

package/docs/handbook/guides/size-and-startup.md

@@ -10,7 +10,7 @@ Cloudflare startup_time_ms needs an actual upload/deployment; offline dry runs d
 
 ## Size metrics
 
-Three metrics, one definition each. The [performance skill](../../skills/performance/SKILL.md)
+Three metrics, one definition each. The [performance pass](performance.md)
 and the SDK's own checks use these names. Measure the production build that
 `mantle bundle` writes, never a dev server.
 
@@ -25,7 +25,7 @@ report it.
 | MCP App HTML document | The whole built App document as served: its inline JavaScript, CSS and markup in one file. | raw bytes and gzip of the file |
 | Worker entry static graph | The Worker entry (Wrangler's `main`, such as `dist/worker/worker.js`) plus every chunk it imports statically, recursively. A dynamic `import()` is not followed. | gzip per file; raw bytes beside it |
 
-The 100 KB budget in the performance skill is first-load JavaScript. It applies to
+The 100 KB budget in the [performance pass](performance.md) is first-load JavaScript. It applies to
 an MCP App too: `mantle bundle` builds the App as one HTML file with its
 JavaScript inline, so its first-load JavaScript is its inline script text. The
 MCP App HTML document also holds CSS and markup, so do not compare the document

package/docs/handbook/guides/typed-queries.md

@@ -11,6 +11,18 @@ description: Choose Store for writes and simple lookups; declare internal Views
 
 Never write raw SQL to Mantle collections: it bypasses scope, TTL, publishing and system-column rules. The Store applies row rules but does not check a View's or Procedure's `requires`; authorize your handler before using it.
 
+## Adopt Mantle in an existing application
+
+Keep the application's router, database handle, identity and frontend; declare only the Schemas and operations you
+adopt and import their `views/<encoded-name>.ts` or `procedures/<encoded-name>.ts`. Bun.SQL and postgres.js fit
+directly; node-postgres needs an [adapter](postgres-adapters.md). Resolve one verified Caller per request, with the
+shared cookie-session origin check on writes ([authentication](../cloudflare/authentication.md)). No Admin, auth or
+surface module is required for direct queries.
+
+Existing tables need an explicit migration into the declared storage shape, including system columns and constraints;
+never apply the initial `schema.sql` over an occupied database. Rehearse the migration on a copy, keep a rollback, and
+test scope, TTL, publication, OCC and persisted state with the application's own identity and tests.
+
 ## Declare an internal View
 
 Save this as `manifests/tickets.yaml`:

package/docs/handbook/navigation.json

@@ -84,6 +84,10 @@
         {
           "text": "Size and startup",
           "link": "/guides/size-and-startup"
+        },
+        {
+          "text": "Performance pass",
+          "link": "/guides/performance"
         }
       ]
     },

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,41 @@ 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:
@@ -99,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.
@@ -216,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.2` 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.2",
+  "version": "0.2.1-alpha.3",
   "type": "module",
   "sideEffects": false,
   "engines": {

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.2@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.