@aotter/mantle 0.1.3 → 0.1.4

package/docs/handbook/concepts/mcp-and-agents.md

@@ -68,6 +68,25 @@ Only `status: published` entries appear anywhere in that set. Details are in [Pu
 
 ## WebMCP in the browser
 
+### Admin: tools for the signed-in staff member
+
+Admin UI registers staff tools in browsers supporting `document.modelContext`.
+The catalog comes from `GET /admin/api/webmcp`; calls use
+`POST /admin/api/mcp` with the current staff session. Server-side role checks,
+Procedure authorization, and optimistic concurrency remain in force.
+`admin_get_context` and `admin_navigate` add page context and navigation.
+The WebMCP control appears after registration succeeds; unsupported browsers
+can continue using the regular Admin UI.
+
+Owners can explore application API documentation in Developer UI:
+`/admin/dev/docs/api` for HTTP, `/admin/dev/docs/mcp` for remote MCP, and
+`/admin/dev/docs/webmcp` for the Admin catalog and public-page capabilities.
+These pages show projected definitions. Remote clients connect to the host's
+advertised MCP endpoints using the authentication described above.
+See the [Admin API guide](../../../packages/mantle-admin/README.md#admin-webmcp).
+
+### Public pages: opt-in registration
+
 `@aotter/mantle-web/webmcp` exposes public capabilities as tools inside a page, for browsers implementing the draft imperative WebMCP API. Importing the subpath has no side effect; registration starts only when `bindWebMcp()` is called.
 
 ```ts
@@ -78,7 +97,7 @@ const binding = await bindWebMcp();
 binding.dispose();
 ```
 
-It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. Only public capabilities are registered — staff capabilities never leave the server. Existing host tool names are inspected and skipped, never replaced. A server-backed page discovers the safe descriptors published at `GET /api/views` and calls the same-origin `GET /api/views/<name>` routes; a browser-local SPA passes `projectCallableCapabilities(plan, { surface: "public" })` and its own invoker. Procedure tools must still originate from an explicit public MCP Trigger, and invocation enters the runtime through that Trigger, so browser tools cannot bypass validation or authorization. See [Runtime pipeline and adapters](./runtime-and-adapters.md).
+It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. This public-page binding registers only public capabilities. Staff tools use the separate authenticated Admin integration above. Existing host tool names are inspected and skipped, never replaced. A server-backed page discovers the safe descriptors published at `GET /api/views` and calls the same-origin `GET /api/views/<name>` routes; a browser-local SPA passes `projectCallableCapabilities(plan, { surface: "public" })` and its own invoker. Procedure tools must still originate from an explicit public MCP Trigger, and invocation enters the runtime through that Trigger, so browser tools cannot bypass validation or authorization. See [Runtime pipeline and adapters](./runtime-and-adapters.md).
 
 ## Skills for your coding agent
 
@@ -91,11 +110,12 @@ pnpm exec mantle skills --check
 
 This copies every skill the installed package marks `projection: project` — the develop skill among them — into matching `.agents/skills/mantle-*` and `.claude/skills/mantle-*` paths. Both layouts receive identical bytes; `--check` detects drift without writing. Skills that act destructively or target one platform stay out of that set and are opt-in. Manifest generation never rewrites agent instructions.
 
-The same bundle is installable from the plugin marketplace:
+The bootstrap `mantle` skill is also available from the plugin marketplace.
+The ongoing workflows come from the installed SDK through `mantle skills`:
 
 ```sh
 # Canonical
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 
 # Claude Code — two separate prompts
 /plugin marketplace add aotter/mantle
@@ -111,4 +131,4 @@ Never point a versioned project at a mutable branch. See [Project layout and the
 - [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
 - [`packages/mantle/README.md`](../../../packages/mantle/README.md)
 - [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/procedures-and-triggers.md

@@ -218,4 +218,4 @@ Register the two `ref` keys in the project's handlers map, then run the check lo
 - [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
 - [`packages/mantle-runtime/src/domain/service/BuiltinProjector.ts`](../../../packages/mantle-runtime/src/domain/service/BuiltinProjector.ts)
 - [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -174,4 +174,4 @@ If a normal feature cannot be expressed through a purpose-shaped surface, treat
 - [`packages/adapters/bun/README.md`](../../../packages/adapters/bun/README.md)
 - [`packages/adapters/vercel/README.md`](../../../packages/adapters/vercel/README.md)
 - [`packages/adapters/indexeddb/README.md`](../../../packages/adapters/indexeddb/README.md)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

package/docs/handbook/concepts/views.md

@@ -189,4 +189,4 @@ spec:
 - [`packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts`](../../../packages/mantle-runtime/src/infrastructure/storage/SqliteViewCompiler.ts)
 - [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
 - [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -9,12 +9,12 @@ application's SDK. Installing one does not install the other.
 ## 1. Install the bootstrap skill
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
-The installer selects the repository's `install` skill. Read its printed
+The installer selects the repository's `mantle` skill. Read its printed
 installation path. In a project-local Codex installation that is
-`.agents/skills/install/SKILL.md`, not `skills/install/SKILL.md` (the latter is
+`.agents/skills/mantle/SKILL.md`, not `skills/install/SKILL.md` (the latter is
 its source-repository path). Other agent selections and global installation
 can use different locations.
 
@@ -32,6 +32,7 @@ version. `latest` and `alpha` can describe different capabilities. Resolve only
 requirements the user has not provided: host, storage, public API/HTML, and
 whether staff need Admin. Follow the bootstrap skill to install the selected
 packages locally.
+No matching `mantle-starters` tag or bundle is needed to create a project.
 
 Then read:
 
@@ -44,7 +45,7 @@ node_modules/@aotter/mantle/docs/handbook/reference/features.md
 These files are in the npm tarball. They are the version-matched authority,
 including when the bootstrap skill came from a different Git ref. Every
 `docs/...` path in the skill resolves under the installed package, not under
-`.agents/skills/install/`. Keep using that SDK's docs for host examples and CLI
+`.agents/skills/mantle/`. Keep using that SDK's docs for host examples and CLI
 behavior. No local `mantle` binary is available before package installation.
 
 ## 3. Project the ongoing workflows
@@ -61,7 +62,7 @@ pnpm exec mantle skills --check
 |---|---|
 | `.agents/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | The installed package's four project-scoped workflows. |
 | `.claude/skills/mantle-{develop,plugin,theme,update}/SKILL.md` | Identical bytes for Claude compatibility. |
-| `node_modules/@aotter/mantle/skills/` | All seven shipped skills, including opt-in `install`, `provision` and `media-gc`. |
+| `node_modules/@aotter/mantle/skills/` | All seven shipped skills, including opt-in `mantle`, `provision` and `media-gc`. |
 | `node_modules/@aotter/mantle/docs/` | Handbook and examples matched to the package. |
 
 `mantle skills` overwrites these four generated projections. Keep project-specific

package/docs/handbook/navigation.json

@@ -8,7 +8,7 @@
         { "text": "Project layout and the CLI loop", "link": "/start/project-and-cli" },
         { "text": "Quickstart: a minimal Worker", "link": "/start/quickstart-worker" },
         { "text": "Quickstart: local Admin (opt-in)", "link": "/start/quickstart-admin" },
-        { "text": "When the host is ChatGPT Sites", "link": "/sites/index" }
+        { "text": "When the host is ChatGPT Sites", "link": "/chatgpt-sites/index" }
       ]
     },
     {
@@ -49,9 +49,9 @@
     {
       "text": "ChatGPT Sites",
       "items": [
-        { "text": "Get started", "link": "/sites/index" },
-        { "text": "Host reference", "link": "/sites/host-reference" },
-        { "text": "Equipment checkout and external APIs", "link": "/sites/equipment-checkout" },
+        { "text": "Get started", "link": "/chatgpt-sites/index" },
+        { "text": "Host reference", "link": "/chatgpt-sites/host-reference" },
+        { "text": "Equipment checkout and external APIs", "link": "/chatgpt-sites/equipment-checkout" },
         { "text": "Earlier guide URL", "link": "/cloudflare/chatgpt-sites" }
       ]
     },

package/docs/handbook/releases/index.md

@@ -21,6 +21,31 @@ All eleven packages share a single version and are published together, so mixed
 versions across `@aotter/mantle*` are never a supported combination. Pin the
 version you install and upgrade the whole set at once.
 
+## 0.1.4 — 2026-09-24
+
+0.1.4 repairs the published consumer path without changing the Manifest
+grammar. Pin every selected `@aotter/mantle*` package to `0.1.4`, refresh the
+lockfile, then rerun `mantle generate` and `mantle skills` with their `--check`
+commands. Read the handbook and skills from that installed version.
+
+**ChatGPT Sites reference.** The 0.1.3 reference omitted the
+`_mantle_boot_state.store_instance_id` column required by the runtime, which
+could make deployed runtime routes return 500. The reference now adds the
+append-only `drizzle/0003_store_instance_id.sql` migration. If your project
+was copied from that reference, carry the new migration forward and apply
+pending D1 migrations **before** deploying updated code; do not edit a
+migration already applied. Repeated builds now clear `dist` so removed SQL
+files cannot remain in the deployment artifact. The Sites guide also shows
+how to mount an HTTP Trigger, identifies the browser and MCP owner workflows,
+and names its integration chapter `docs/handbook/chatgpt-sites/`.
+
+**Agent installation.** `npx skills add aotter/mantle` installs the small
+`mantle` bootstrap skill; the installed npm package supplies version-matched
+instructions and docs. The skill now checks the application's installed
+version before reading them. Superseded Starter decisions are marked as
+history: no `mantle-starters/v0.1.4` tag or `mantle create` command is needed
+to author a new application.
+
 ## 0.1.3 — 2026-09-23
 
 0.1.3 tightens the contract between Manifests, generated TypeScript, agent
@@ -98,7 +123,7 @@ See [HTTP, MCP, CLI and packages](../reference/surface.md) for the full list.
 D1 and assets bindings, Better Auth 1.7 (social providers, email OTP, magic
 link, passkey), Admin, MCP, Web and R2 media uploads. The Bun and Vercel
 adapters are experimental, cover public Views and HTTP Triggers only, and leave
-authentication and CSRF to the host. [ChatGPT Sites](../sites/index.md) is a
+authentication and CSRF to the host. [ChatGPT Sites](../chatgpt-sites/index.md) is a
 first-class integration with a runnable reference.
 
 **Agents.** `mantle skills` projects the installed package's skills into

package/docs/handbook/start/overview.md

@@ -24,7 +24,7 @@ current npm `latest` contains it.
 | Embed Runtime in an existing host | [Runtime and adapters](../concepts/runtime-and-adapters.md), then [typed queries](../guides/typed-queries.md) | Bind your storage and call the generated API. |
 | Build a local Cloudflare API | [Minimal Worker tutorial](./quickstart-worker.md) | A running public View and a verified HTTP response. |
 | Add a staff console | [Local Admin tutorial](./quickstart-admin.md) | Email OTP, Admin assets and a local human workflow. |
-| Build on ChatGPT Sites | [Sites integration](../sites/index.md) | Host-owned sign-in and deployment with Mantle content. |
+| Build on ChatGPT Sites | [Sites integration](../chatgpt-sites/index.md) | Host-owned sign-in and deployment with Mantle content. |
 | Work through a coding agent | [Skill installation and handoff](../guides/agent-setup.md) | Bootstrap skill, pinned package, then project-local instructions. |
 
 Human authors can follow these pages directly; installing an agent skill is

package/docs/handbook/start/project-and-cli.md

@@ -8,7 +8,7 @@ This page describes a directly authored Mantle project: which files are yours, w
 Agents can bootstrap with the install skill; human authors can follow this guide directly. For installation paths and the pinned-package handoff, see [Agent setup](../guides/agent-setup.md):
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 ## You own the project
@@ -96,14 +96,14 @@ Run the harness after any change to a Schema index, View filter or ordering, or
 
 ## Connecting an agent
 
-`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `install`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
+`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `mantle`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
 
-Install the plugin bundle in the agent host. Cold start uses
+Install the bootstrap skill in the agent host. Cold start uses
 the install skill; an already-installed project pins packages from `package.json`:
 
 ```sh
 # Canonical
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 
 # Claude Code — two separate prompts
 /plugin marketplace add aotter/mantle
@@ -137,4 +137,4 @@ The projected `develop` skill tells the agent to read `package.json` for the ins
 - [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
 - [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
 - [`packages/mantle-spec/src/infrastructure/cli/MantleCli.ts`](../../../packages/mantle-spec/src/infrastructure/cli/MantleCli.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)

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

@@ -174,9 +174,6 @@ curl -i http://127.0.0.1:8787/mcp/staff
 
 `generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. `mantle generate --check` reports stale output without writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
 
-> **npm and optional peers**
-> A cold npm install can fail with `ERESOLVE` when an Auth peer selects a different optional `@libsql/client` than this snapshot declares. If that happens, pin `@libsql/client` in `overrides` to the range in this checkout's `package.json` and rerun `npm install`. Do not use `--force`. Commit the lockfile and use `npm ci` afterwards.
-
 ## Next steps
 
 - [Quickstart: local Admin](./quickstart-admin.md) — opt-in Dev UI: ASSETS, prebuilt Admin, email OTP.

package/docs/release-process.md

@@ -110,10 +110,11 @@ dist-tag DELETE only added failure and re-run state, and Actions
    ```
 
    Leave the consumer cold-start entry **untagged**: `npx skills add
-   aotter/mantle --skill install`, `/plugin marketplace add aotter/mantle`,
+   aotter/mantle`, `/plugin marketplace add aotter/mantle`,
    `codex plugin marketplace add aotter/mantle` and the plugin-manifest
    descriptions carry no `@v…` / `--ref`. Untagged resolves to `main`, which
-   only moves at a release, so it is always the latest published version
+   normally moves at a release but may contain a source-only hotfix; the
+   installed npm package remains the version authority
    (#995, #998). Only "installed version" statements such as
    `(currently \`X.Y.Z\`)` are bumped.
 

package/docs/sealed-pipeline-ownership.md

@@ -65,7 +65,7 @@ release use `docs/examples/host-minimal-worker` from the same reviewed commit.
 Private consumers can still run the exact-tarball checker in their own repos;
 public Core PRs receive no cross-repository credentials:
 
-| Consumer | Revision | Gate authority | Manifest paths |
+| Historical consumer | Revision | Gate at the time | Manifest paths |
 |---|---|---|---|
 | `aotter/mantle-starters` | `157e8f49e1e25ae1c52c0115f0dd9e8b6017ef0e` | Core CI + release | `blank/manifests/site.yaml`; `overlays/{community,intake,presence,publication,reservation,transaction}/manifests/site.yaml`; `recipes/typed-web/manifests/site.yaml` |
 | `aotter/mantle-landing` | `4381354dd25d5d94f4096cf3e55a4cb9eecbf3ad` | Landing CI + Core release | `manifests/site.yaml` |

package/docs/skills/develop/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: develop
+description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/develop/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Develop
+
+This is the Core workflow skill for an existing Mantle project. Repo-local
+copies are byte-for-byte projections from the installed package; its embedded
+docs govern runtime/API behavior.
+
+## First Read
+
+1. `package.json` for the installed `@aotter/mantle*` versions.
+2. The manifest directory selected by the project scripts, the actual host
+   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
+   Read custom Auth construction there when present.
+3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
+   and `.mantle/recipes/`. Legacy launch/handoff files are context only.
+4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
+
+If `node_modules/` is missing, run `pnpm install --frozen-lockfile` before
+falling back to remote docs. Remote docs must use a tag matching the installed
+version; never use `develop` branch docs for a versioned consumer project.
+
+## Existing Examples
+
+Read installed `docs/handbook/start/project-and-cli.md` and
+`docs/examples/README.md`. Use `docs/examples/host-minimal-worker/` for Spec +
+adapter without Admin. Read `docs/examples/host-local-admin-otp/` only when the
+project already has Admin or the human asked for Dev UI — that path is opt-in.
+Ingest only `docs/examples/builtin-*.md` Manifests as grammar for new domains.
+Read `docs/examples/cf-primitives-*.md` before inventing Durable Object, Queue,
+cron, or `ref` handler patterns.
+References are test/documentation, not a Starter or a fixed application shape.
+
+Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
+`TemplateRegistry`, and a matching `publicPathResolver` must agree on the
+exposed collections. Do not auto-publish every Schema. Applications document their mounted URL surface in their own README.
+Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
+not install public rendering by itself.
+
+## Authoring CLI
+
+Use the project's scripts first; applications use the shipping
+`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
+command list instead of trusting one copied into prose — the surface is
+version-matched and changes between releases:
+
+```bash
+pnpm exec mantle --help
+pnpm validate
+```
+
+This CLI validates and derives artifacts from application-authored manifests.
+It does not create projects, business schemas or a visitor homepage. There is
+no `mantle create` / `mantle update` happy path.
+
+## Core Model
+
+Mantle exposes exactly four declarative atoms:
+
+| Atom | Purpose |
+|---|---|
+| `Schema` | Stored entity/table shape. |
+| `View` | Read/query surface. |
+| `Procedure` | Typed mutation or operation. |
+| `Trigger` | HTTP/lifecycle/MCP invocation binding. |
+
+Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
+`Membership`. Compose those from the four atoms plus TypeScript only where
+the atoms cannot express the behavior.
+
+## Choose the manifest feature first
+
+Read installed `docs/handbook/reference/features.md` to map the requested
+behavior to fields before adding handlers or a custom UI. For host-only reads,
+`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
+`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
+View params/results, indexed entry reads, and their authorization boundary.
+Use `from` for portable typed projections; SQL is for queries needing native
+SQLite and produces `unknown` row types.
+
+For Admin labels, inputs, collection columns/tabs, reports or action buttons,
+read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
+metadata and `uiSchema` before custom frontend code. These control the Admin
+console, not the visitor frontend. Regenerate and verify the actual console;
+never edit generated `public/_mantle/admin/` assets.
+
+## Content Edits
+
+- Follow the actual frontend content source. Use Admin or Staff MCP for
+  runtime-backed content. Do not invent an overlay/seed homepage.
+- For a new submitted field, update the stored `Schema` and the public
+  `Procedure.spec.input` before any form UI. Keep public mutation inputs
+  `additionalProperties: false`; otherwise JSON Schema's default may strip an
+  undeclared field while returning success.
+- Use `lifecycle: operational` for submissions, inquiries, orders, and other
+  Procedure-created operational records that staff inspect or correct. Reserve
+  `publishing` for content a person stages and publishes.
+- Lifecycle `before_update` / `after_update` hooks also fire for unpublish,
+  archive, and every other status transition whose target is not `published`;
+  do not use them for edit-only work.
+- When a form's fixed option values change, update the stored Schema and public
+  Procedure input `enum` together. Keep translated labels in the frontend content source;
+  Admin and Staff MCP derive their typed controls from the manifest values.
+- If the application has a `page` Schema with sections, update its declared
+  section properties when adding display fields; an undeclared property has no
+  runtime-backed Admin or Staff MCP path.
+- Update notification handlers when they need the new field. Test the stored
+  entry, not only the HTTP `{ "ok": true }` response.
+
+## Locales
+
+- `data.locale` is reserved for `localized: true` Schemas. A non-localized
+  Schema must use a domain field such as `replyLocale`.
+- Use a standalone localized Schema only for independent locale rows. For
+  versions of one entity, use a non-localized parent plus a localized child
+  with `translates: { parent, on }`. The child must own at least one field
+  besides `locale` and the join field.
+- Parallel locale blocks must keep field names, option values, step IDs, and
+  result keys identical; translate display strings only.
+- `siteDefaults.origin`, `siteDefaults.locales`, and `siteDefaults.icons` are
+  code-owned and boot-synced. The icon list is shared by browser favicons,
+  Admin chrome, and MCP `serverInfo.icons`; keep its static files under
+  `public/`. Brand, title, and description seed once, then change through site
+  settings.
+- When changing an existing collection from `[slug]` to `[slug, locale]`,
+  boot with a Mantle version that reconciles obsolete unique indexes and test
+  the same slug in two locales. Do not patch D1 manually.
+
+## Adapter Boundary
+
+The runtime is adapter-neutral. A `MantleStorageAdapter` prepares the compiled
+plan into semantic storage ports; `createMantleRuntime` binds that prepared
+storage and selected capabilities. Database drivers and asset serving belong
+to the host/optional composition. Follow the installed adapter guide.
+
+Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
+or its adapter config is visible. A future Netlify adapter should satisfy the
+same Core workflow through its own ports and provider setup.
+
+Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
+`runtime.entries`, and optional `runtime.siteConfig`; do not query Mantle-owned `entries` or
+`site_config`, reach through deprecated `runtime.db`, copy generated-column
+names, or construct SDK KV keys. Cloudflare bindings belong only at the
+composition root. If a normal feature cannot be expressed through a
+purpose-shaped surface, treat that as a Core abstraction gap instead of
+teaching the project Mantle internals.
+
+## Auth Composition
+
+Admin is opt-in. A project without `@aotter/mantle-admin-ui` is complete.
+When Admin is installed, `createMantleWorker({ auth })` with `email-otp`
+and `ConsoleEmailSender` is the local human path (OTP in wrangler logs).
+That override owns Auth construction; Core still owns `/admin` and
+`/api/auth/*`. Admin also requires wrangler `assets.directory=./public`
+and an `ASSETS` binding. A white screen at `/admin` with HTML 200 and
+`/_mantle/admin/assets/*` 404 is a missing assets binding, not a missing
+frontend build.
+
+Conventional Cloudflare projects that do not replace Auth declare
+`MANTLE_AUTH_MODE=hosted` or `self-managed`; Core owns that standard
+composition and rejects partial or mixed bindings. Preserve the explicit
+mode recorded in Worker config, keep provider secrets out of source, and
+do not infer a mode from whichever credentials happen to be present.
+
+## Performance Loop
+
+After changing a Schema index, View filter/order, public API, or rendered page,
+run the project's index check when present. Otherwise run the installed
+harness directly:
+
+```bash
+pnpm exec mantle-harness indexes --require-public --format text
+```
+
+The check uses crowded real SQLite and the shipped compiler. It complements
+`pnpm validate`; it does not replace correctness validation. Declare the
+smallest ordered index justified by the measured path and respect SQLite's
+leftmost-prefix rule; which columns an index may name and how a public View's
+status predicate shapes it is in the handbook (`reference/schema.md#indexes`).
+Do not change user-visible filter or ordering semantics
+just to make the gate pass. Do not add every permutation or cache every read.
+
+For relevant Cloudflare serving changes, start the project and sample the
+actual routes:
+
+```bash
+pnpm exec mantle-harness http \
+  --base-url http://127.0.0.1:8787 \
+  --route page=/en/example \
+  --rounds 20 --warmup 2 --format text
+```
+
+Prefer query plan, query count, `rows_read` scaling, and cache MISS/HIT
+evidence. Do not create CI gates from absolute local milliseconds.
+
+## Loop
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm check:indexes # when the project provides it
+pnpm typecheck
+pnpm check
+```
+
+Use `pnpm dev` for local preview when the project provides it.
+
+## Connect a Local MCP Client
+
+Start the project with `pnpm dev`, then use the exact local origin it prints.
+The conventional Cloudflare adapter exposes:
+
+- `http://localhost:8787/mcp` for public tools;
+- `http://localhost:8787/mcp/staff` for authenticated authoring tools.
+
+Prefer the client's native remote HTTP + OAuth support. Use a standard
+HTTP-to-stdio bridge such as `npx -y mcp-remote <url>` only when the client
+accepts stdio MCP servers but cannot connect to remote HTTP directly. Mantle
+does not own a separate local proxy or an auth-bypass mode.
+
+Before changing client config, confirm the Worker is reachable:
+
+```bash
+curl -i http://localhost:8787/mcp
+```
+
+An OAuth-protected endpoint should respond with `401` and a
+`WWW-Authenticate` resource-metadata challenge before sign-in. After
+connecting, inspect `tools/list`; make one read-only `query_view_*` call when
+available before invoking any mutation. Use project-scoped client config when
+the client offers it, and never commit OAuth tokens or the bridge's token
+cache.
+
+## Rules
+
+- Keep content models in the configured manifest directory; its immediate
+  `.yaml` and `.yml` files are loaded together.
+- Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.
+- Do not write directly to D1, KV, Postgres, or object storage for content
+  authoring. Use runtime use cases, admin APIs, or Staff MCP.
+- Do not commit provider secrets.
+- If the work is an installable capability, switch to `mantle:plugin`.

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

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