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

package/docs/handbook/cloudflare/media-r2.md

@@ -73,3 +73,34 @@ reconciliation and retry id.
 Admin's `media` option takes a `MediaStorage` value, so build it where `env` is available (for example once per
 Worker in the fetch handler). Uploads use presigned S3 PUT URLs: `wrangler dev --local` has an R2 binding but no S3
 endpoint, so test the upload flow against a real bucket; local tests can cover everything up to the signed URL.
+
+## Clean up stale uploads
+
+An upload that was created but never committed leaves objects under `uploads/`. Cleaning them up is an operator task:
+audit by default, and delete only the exact objects the user approves for that exact account and bucket. Create no
+Worker, Cron Trigger, lifecycle rule, table or script for it, and never create, request or store credentials.
+
+**Layout.** `POST /admin/api/media/uploads` issues presigned PUT URLs (15 minutes) for
+`uploads/<purpose>/<group>/<role>.<ext>`. Commit copies each checked object to `committed/<group>/<attempt>/<role>.<ext>`
+with `committedAt` metadata and removes the upload keys after the database commit; a rejected group also removes them.
+An old upload key may be leftover cleanup from a successful or uncertain commit, so it is not evidence that the media row
+is absent. Objects outside `uploads/` are never candidates; attempt copies under `committed/` are reconciled with live
+database references separately, under their own authorization.
+
+**Preflight.** Resolve the bucket `r2MediaStorage` uses and the purposes in `siteDefaults.media.purposes` from
+`wrangler.jsonc` and the app entry. Confirm the exact account and bucket with the user; when either is ambiguous, ask,
+never match by name. Stop when the app passes no `r2MediaStorage`, declares no purpose, or the connected account lacks
+List/Delete Objects access.
+
+**Audit.** For each declared purpose, page through `uploads/<purpose>/` until the listing is not truncated. A candidate
+is more than 24 hours old, has no `committedAt`, and matches
+`uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)` with a declared purpose and a
+`<group>` of letters, digits, `_` or `-`. Skip everything else (committed, unknown prefix, malformed, ambiguous) and
+delete single variants, never a whole group. Report the account, bucket, prefixes, UTC cutoff, candidate object and
+group counts, bytes, skipped count, and a SHA-256 digest of the sorted `key + etag` set; print no keys, group ids,
+filenames, URLs or secrets. A page truncated without a cursor stops the run: never delete from a partial audit.
+
+**Apply.** After explicit confirmation of the account, bucket, cutoff, count, bytes and digest, re-run the audit with the
+same cutoff and stop if anything changed. Delete exact keys, at most 1,000 per request, and never send a `prefix`: an
+empty prefix can empty the bucket. Do not retry failed keys automatically. Re-list each prefix and report whether the run
+was audit-only or applied, the before/after counts and bytes, and redacted error codes.

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.1/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.3/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/agent-setup.md

@@ -1,97 +1,55 @@
 ---
-description: Install the Mantle agent plugin or its one skill, hand off to the installed package's own docs, and diagnose missing or stale instructions.
+description: Install the Mantle agent skill, hand off to the installed package's `mantle help`, and diagnose missing or stale instructions.
 ---
 # Install and verify agent instructions
 
-Two separate things are installed: the agent's `mantle` skill and the
-application's `@aotter/mantle` package. Installing one does not install the
-other, and the installed package is always the authority for the version it
-carries.
+Two separate things are installed: the agent's `mantle` skill and the application's `@aotter/mantle` package. The skill
+holds no contract and does not depend on the SDK version: it sends the agent to `mantle help`, which prints the docs
+shipped inside the installed package. So the skill can come from the latest repository while the application pins any
+version.
 
 ## 1. Install the `mantle` skill
 
-The Mantle plugin carries one OSS authoring skill, `mantle`, and local
-acceptance references. It does not configure a hosted-service connection.
-Install from the Git tag matching the exact SDK version you selected (currently
-`v0.2.1-alpha.1`). Pin the tag to keep instructions aligned with the application's
-SDK. A skill install does not upgrade the application's SDK.
-
-For Codex, pin the marketplace checkout:
+Any agent that reads skills:
 
 ```sh
-codex plugin marketplace add aotter/mantle --ref v0.2.1-alpha.1
-codex plugin add mantle@mantle
+npx skills add aotter/mantle@mantle
 ```
 
-For Claude Code, first clone the release into a directory you will keep:
+The explicit name excludes the repository's maintainer skills. As a plugin, which carries the same one skill and no
+hosted-service connection:
 
 ```sh
-git clone --depth 1 --branch v0.2.1-alpha.1 https://github.com/aotter/mantle.git mantle-plugin
+codex plugin marketplace add aotter/mantle
+codex plugin add mantle@mantle
 ```
 
-Then, in Claude Code, use that checkout's absolute path:
-
 ```text
-/plugin marketplace add /absolute/path/to/mantle-plugin
+/plugin marketplace add aotter/mantle
 /plugin install mantle@mantle
 ```
 
-Cursor and GitHub Copilot use their plugin manifests from the same tagged
-checkout. Without a plugin host, install only the consumer skill by name:
-
-```sh
-npx skills add aotter/mantle@mantle
-```
-
-Without a version it follows `main`, the latest stable release. To match the
-application's SDK exactly, add its release tag: `npx skills add aotter/mantle#v0.2.1-alpha.1@mantle`.
-
-When upgrading the SDK, update the marketplace ref or local tagged checkout and
-refresh/reinstall the plugin using the host's native workflow. Verify the loaded
-manifest version and skill source. Do not reset a checkout containing local edits.
-
-Read the path the installer prints (for project-local Codex,
-`.agents/skills/mantle/SKILL.md`). The skill installs no SDK, creates no
+Cursor and GitHub Copilot read their plugin manifests from the same repository. The skill installs no SDK, creates no
 project and copies no handbook.
 
-## 2. Install the SDK, then read its own docs
+## 2. Install the SDK and read its docs
 
-Use the version the project already pins. For a new project, install this
-handbook's version exactly. 0.2.1-alpha.1 is a prerelease; stable 0.2.0 remains the
-production line, and its own tagged handbook describes it.
+Use the version the project already pins. For a new project, pick one exact version from
+[Releases](../releases/index.md) (only plain `X.Y.Z` versions are for production) and pin every selected
+`@aotter/mantle*` package to it:
 
 ```sh
-pnpm add --save-exact @aotter/mantle@0.2.1-alpha.1
+pnpm add --save-exact @aotter/mantle@<version>
+npx mantle help
 ```
 
-Add optional `@aotter/mantle-ui@0.2.1-alpha.1` and `@aotter/mantle-admin@0.2.1-alpha.1` only
-when the selected surfaces need them. Every selected `@aotter/mantle*` package
-stays at the same exact version. Read, from the application:
-
-```text
-node_modules/@aotter/mantle/README.md
-node_modules/@aotter/mantle/docs/handbook/start/overview.md
-node_modules/@aotter/mantle/docs/handbook/reference/features.md
-node_modules/@aotter/mantle/docs/skills/<workflow>/SKILL.md
-```
-
-These ship in the npm tarball and match the installed code. Prefer them over
-the skill's GitHub copy and over any online handbook.
-
-| Package skill | Read it when |
-|---|---|
-| `docs/skills/develop/SKILL.md` | changing manifests, handlers, the service or its surfaces |
-| `docs/skills/integrate/SKILL.md` | adding Mantle to an existing application |
-| `docs/skills/update/SKILL.md` | upgrading `@aotter/mantle`, including from 0.1.x |
-| `docs/skills/provision/SKILL.md` | deploying, with production sign-in |
-| `docs/skills/media-gc/SKILL.md` | auditing or removing stale R2 uploads |
-| `docs/skills/performance/SKILL.md` | after acceptance converges, or when a page, first request or query is slow |
-
-0.2.0 has no `mantle skills` command: nothing is copied into the project.
-An agent reads these files from `node_modules` when the task calls for them.
+`mantle help` prints the installed version's entry page; prefer it over any online copy of this handbook.
 
 ## 3. Verify the application
 
-Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again. Test actual routes and persisted state. With selected Admin, mount `entries(bindings.schemas, bindings.adapter)` and serve assets separately. Verify member/admin OTP, row visibility and OCC. Installing a skill proves none of these flows.
+Run the app's exact generation command with `--check`, typecheck, implement every printed handler and typecheck again.
+Test actual routes and persisted state, then run acceptance as the entry page describes. Installing a skill proves none
+of these flows.
 
-If packaged docs are missing, reinstall the SDK version pinned by the app. If a feature differs from an online page, read the installed docs rather than assuming compatibility.
+If `mantle help` reports missing docs, reinstall the SDK version the app pins. If a feature differs from an online page,
+the installed docs win.

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -85,6 +85,18 @@ rounds below before claiming the user-facing work is done. Keep the author's
 capability map and worked call sequence out of the fresh agent's prompt: an MCP
 evaluator must discover the workflow from public tool descriptions and results.
 
+## Propose the run first
+
+Before the first round, stop and give the user the plan, then wait for a go-ahead:
+
+- each evaluator you will start: its role (`admin`, `user`, a visitor), the surfaces it uses (Admin, member pages,
+  REST, MCP, visitor pages) and the goals it is asked to finish, in the user's words;
+- the round limit (at most three) and what triggers a re-run;
+- anything the environment needs, such as a browser for a visitor or member page, so a missing one is settled now
+  rather than reported as BLOCKED later.
+
+Keep the rubric itself private: the plan names goals, never the checks an evaluator is graded on.
+
 ## Run role-only acceptance rounds until they converge
 
 The evaluator gets a role, not a task list. It works out what that role needs
@@ -154,10 +166,11 @@ acceptance as BLOCKED and report the scripted checks on their own
 [layers](#report-done-ness-in-layers). Do not invent
 an independent result. Do not deploy or publish merely to obtain acceptance.
 
-Acceptance proves the behavior, not its speed. Once a round converges, the
-[performance skill](../../skills/performance/SKILL.md) decides which performance
-checks apply and holds them to their targets; a performance repair that changes
-what a role sees or can do returns here, scoped by the
+Acceptance proves the behavior, not its speed. For every role and surface a
+round reports CONVERGED, the [performance pass](performance.md)
+decides which performance checks apply and holds them to their targets. BLOCKED
+or UNVERIFIED parts are reported as they are, never optimized. A performance
+repair that changes what a role sees or can do returns here, scoped by the
 [re-verification rule](#re-verify-what-a-repair-touches).
 
 ## Re-verify what a repair touches
@@ -300,6 +313,20 @@ reported, layer by layer; it is not done:
 | 4. External platform | not applicable: no deployment or external host requested | |
 ```
 
+## Summarise for the user
+
+Lead the handoff with what acceptance found and fixed, so the user sees the value of the rounds:
+
+```markdown
+| Evaluator (role, surfaces) | Rounds | Found | Fixed in | Final |
+| --- | --- | --- | --- | --- |
+| admin: Admin, admin MCP | 2 | P1: approving a stale event overwrote a newer edit | `approve-event` checks the version | CONVERGED |
+| user: member pages, MCP | 1 | none | | CONVERGED |
+| visitor: public pages | 1 | P2: no link back from an event to the list | `src/routes.ts` | CONVERGED |
+```
+
+Name each finding by its effect on the user, not the code, then give the layered status below.
+
 ## Record evidence in the existing issue or handoff
 
 Use ordinary Markdown; no new receipt schema or framework is required:
@@ -317,7 +344,7 @@ Use ordinary Markdown; no new receipt schema or framework is required:
 - Findings ledger with P0–P3, owner, disposition, minimal repair and
   regression commands/results.
 - Coverage of each rubric item (evaluator-observed in this round,
-  evaluator-observed and reused from round <n> at <revision> with the reason,
+  evaluator-observed and reused from round `<n>` at `<revision>` with the reason,
   author regression only, or UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
   used, which is layer 3 of the [layered report](#report-done-ness-in-layers).
   Retain every failed report.

package/docs/handbook/guides/mcp-apps.md

@@ -33,6 +33,46 @@ passed through as the resource's `_meta.ui`. `domain` is the dedicated sandbox
 origin for hosts that serve each App from its own origin; use the form that
 host documents.
 
+### Tool metadata and result `_meta`
+
+A hand-built kernel `Tool` may set `meta`, merged into its `_meta` in
+`tools/list` with what App links produce: the top level shallowly, `ui` one key
+deep. Use it for keys such as `ui.visibility`, `ui.resourceUri` with
+`openai/outputTemplate`, or `openai/fileParams`. A value that contradicts an App
+link (another `ui.resourceUri` than the `renders` resource, or a visibility other
+than `["app"]` on an `appOnly` tool) fails when `mcp()` is constructed.
+`meta: { ui: { visibility: ["app"] } }` hides any tool, a Procedure included,
+from clients that declare no MCP Apps support, as `appOnly` does for Views. It
+is a listing hint only: `tools/call` still runs every identity, scope, `check`
+and `authorize` decision, so an App-only write is authorized like any other.
+
+A `run` may return `withResultMeta(data, meta)` from `@aotter/mantle/mcp`. The
+result's text and `structuredContent` are built from `data` exactly as before;
+`meta` goes only into the result `_meta`, beside `net.aotter.mantle/tool`, which
+it cannot replace. Hosts give result `_meta` to the App, not the model, so a
+signed upload URL belongs there:
+
+```ts
+import { withResultMeta, type Tool } from '@aotter/mantle/mcp';
+
+declare function signUpload(caller: unknown): Promise<{ id: string; url: string; headers: Record<string, string> }>;
+
+const uploadTarget: Tool<unknown> = {
+  name: 'upload_target', surface: 'public', description: 'Prepare an upload.', closed: true,
+  meta: { ui: { visibility: ['app'] } },
+  inputSchema: { type: 'object', additionalProperties: false }, validate: raw => raw as Record<string, unknown>,
+  run: async (_db, caller) => {
+    const upload = await signUpload(caller);
+    return withResultMeta({ id: upload.id }, { uploadUrl: upload.url, requiredHeaders: upload.headers });
+  },
+};
+```
+
+`callTool` and `callToolLazy` return the wrapper itself, `{ data, _meta }`.
+A caller that forwards a result to a model, such as an application's own agent,
+must forward only `data` and drop `_meta`, or the signed URL leaks through that
+path. A thrown error still produces the standard diagnostics result.
+
 ## Package and application ownership
 
 Core (`@aotter/mantle`) owns tools, resources, endpoint links and server authorization,
@@ -46,7 +86,9 @@ source/origin guard is not a protocol implementation.
 
 Applications own domain components and build entries. A frontend MCP App uses its
 own React entry, official ext-apps and optionally mantle-ui, registered through
-Core's generic resources. It needs no Admin package or Admin session. See the
+Core's generic resources. It needs no Admin package or Admin session. Build it
+with `App` from `@modelcontextprotocol/ext-apps`: register `ontoolinput`/`ontoolresult` before `connect()` and use
+`callServerTool` for host-proxied calls; never write a second `postMessage` bridge beside the official client. See the
 [standalone frontend example](../../examples/frontend-mcp-app/README.md) for a
 small owner-scoped example. `public` names the frontend endpoint, not anonymous
 access: use the application's verified Caller and generated authorization rules.

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/reference/describe.md

@@ -5,10 +5,19 @@ An explicit target is required; use the generation target because hashes
 include the dialect. The command writes no project files. `--diff <old.json>` prints a JSON
 array of changes against a saved report.
 
-`describeApp(plan)` and `diffApp(a, b)` are exported by
-`@aotter/mantle/describe`. The `AppDescription` TypeScript type is the contract.
-`targetHash(plan, id)` is also exported by `@aotter/mantle/target-hash`.
-These exports use no Node APIs and load no SQL parser.
+This command's output is the supported way to get a description outside the
+CLI. Run it in Node.js or Bun, for example in a deploy step, from the
+committed manifests, and give the saved JSON to whatever needs it. A Worker
+cannot compile manifests that contain SQL, because the SQL parser's WASM needs
+the whole isolate memory (ADR-0034); do not import compiler files from `dist`.
+
+```sh
+mantle describe cloudflare-d1 manifests/*.yaml > describe.json
+```
+
+`@aotter/mantle/describe` exports `matchTarget` and the `AppDescription`,
+`DescribeTarget` and `TargetRequest` types; `AppDescription` is the contract.
+It loads no compiler, SQL parser or Node API.
 
 The schemaVersion 1 report contains:
 
@@ -55,8 +64,9 @@ imports no application, opens no database and makes no network call, so a
 gateway can compute `props.mantle.target` and `targetHash` before forwarding.
 
 ```ts
-import { matchTarget } from "@aotter/mantle/describe";
-const url = new URL(request.url);
+import { matchTarget, type AppDescription } from "@aotter/mantle/describe";
+import saved from "./describe.json";
+const describe = saved as AppDescription, url = new URL(request.url);
 matchTarget(describe, { surface: "rest", method: request.method, path: url.pathname });   // rest:GET /api/views/orders
 matchTarget(describe, { surface: "admin", method: request.method, path: url.pathname });  // admin:GET /entries/:id
 matchTarget(describe, { surface: "mcp", tool: params.name, path: url.pathname });         // view:orders, admin:tool:<name>

package/docs/handbook/reference/surface.md

@@ -215,6 +215,16 @@ by declared identity, scope and `check` requirements. Without `authorize`, the
 complete endpoint catalogue is not a permission-filtered catalogue. Operation
 validation, guards and credential checks still apply to calls.
 
+`toolsPageSize` pages `tools/list`: each page holds at most that many tools and
+carries an opaque `nextCursor` while more remain; pass it back as `cursor`. A
+cursor is valid only for the catalogue version that issued it; an unknown or
+stale cursor is answered with JSON-RPC error `-32602`, and the client lists
+again from the first page. Without the option, one page lists every tool and
+carries no `nextCursor`.
+
+A hand-built tool's `meta` and a `run` returning `withResultMeta(data, meta)`
+add listed and result `_meta`; see [MCP Apps](../guides/mcp-apps.md#tool-metadata-and-result-_meta).
+
 The app resolves bearer tokens with `resolveCaller(request, auth, { audience:
 new URL('/mcp', request.url).href })` (both surfaces use `<origin>/mcp`). The app
 must also mount Better Auth's `/.well-known/oauth-protected-resource/mcp`