@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/skills/develop/SKILL.md

@@ -1,250 +0,0 @@
----
-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/skills/install/SKILL.md

@@ -1,149 +0,0 @@
----
-name: mantle
-description: Author a new Mantle application directly from version-matched SDK docs, or continue an existing project. Use when asked to install Mantle, build a Mantle application, or open a Mantle repository.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: skills/install/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: plugin
-  projectionReason: Creates a new project; nothing to project into an existing one.
----
-
-# Mantle
-
-Mantle is an embeddable manifest engine. The application owns its source and
-provider configuration. There is no Starter/type picker or `mantle create`.
-Do not use the SDK checkout as the application, copy an old Starter tree, or
-turn `generate` into implicit scaffolding.
-A same-version `mantle-starters` tag is not required; do not wait for one.
-
-## Locate the version-matched instructions
-
-`npx skills add aotter/mantle` installs this brief, not the SDK,
-a project, or the handbook. Read the path printed by the installer (Codex's
-project-local path is `.agents/skills/mantle/SKILL.md`); `metadata.sourcePath`
-is repository provenance, not a consumer path. A repository install follows
-the selected Git ref and does not pin an npm release.
-
-After selecting the host and exact version, install `@aotter/mantle` locally
-with the selected optional packages. All `docs/...` paths below then mean
-`node_modules/@aotter/mantle/docs/...`; package skills are under
-`node_modules/@aotter/mantle/skills/`. Read that package's
-`skills/install/SKILL.md` before authoring: it supersedes this bootstrap copy.
-Use the new application's installation, never another project's `node_modules`
-or an SDK checkout packing harness, to resolve these paths.
-Before reading a handbook page, verify the version in that application's
-`node_modules/@aotter/mantle/package.json` against its lockfile and confirm
-the page exists under the same package directory. If the package is missing or
-the versions differ, fix the installation first; do not substitute a nearby
-checkout's docs or another project's `node_modules`.
-If the user requested a prerelease, resolve that channel explicitly; `latest`
-need not contain prerelease features. Never mix versioned npm code with branch
-docs. No local CLI exists until the package is installed.
-
-## New application
-
-1. Determine the actual host and required surfaces from the request. Reuse an
-   existing application when available; otherwise work in its own directory.
-   Do not assume Cloudflare, public HTML or Admin is required. Check Node 22+
-   and pnpm 9+ for these SDK examples. A ChatGPT Site is not a conventional
-   Cloudflare Worker deployment; use the installed
-   `docs/handbook/chatgpt-sites/index.md` integration guide and
-   `docs/examples/host-chatgpt-sites/` runnable reference when selected.
-2. Choose the requested exact SDK version, or resolve the intended release
-   channel once. Pin all selected `@aotter/mantle*` dependencies to that same
-   version. Install only the adapter/optional packages the application needs.
-   If a global scope registry overrides public npmjs, use a project-owned
-   `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
-3. Use the host and surfaces already established in step 1; ask only for
-   information still missing. Read `docs/handbook/start/overview.md` and
-   `docs/handbook/reference/features.md`, then select the matching path:
-   - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
-   - Adapter without Admin — `docs/examples/host-minimal-worker/`.
-   - Opt-in Admin / Dev UI — only when a human needs a console: interview
-     the bootstrap owner email, then `docs/examples/host-local-admin-otp/`
-     (`pnpm install && pnpm generate && pnpm dev`, `/admin/sign-in`, OTP
-     in wrangler logs). Admin needs `@aotter/mantle-admin`,
-     `@aotter/mantle-admin-ui`, wrangler `ASSETS` on `./public`, and
-     `createAuth` email-otp + `ConsoleEmailSender`. Do not Vite-build Admin.
-   - ChatGPT Sites with Admin/D1/R2 — follow
-     `docs/examples/host-chatgpt-sites/`, not the email-OTP Worker example.
-     Copy it outside the SDK checkout, pin its `@aotter/mantle*` dependencies
-     to the selected exact version, then `npm install`,
-     `npx mantle validate --phase deploy`, `npm run generate`, `npm run check`,
-     `npx wrangler d1 migrations apply DB --local`,
-     `npm run dev -- --port 4174`, and `npm test` in a second terminal.
-     Preserve its Sites-owned identity ingress and hosting manifest; author the
-     user's Schema/View/Procedure/Trigger, then review migrations, media policy
-     and the local/production smoke gates. Sites provisions and deploys; never
-     `wrangler deploy` a Site. Request both D1 and R2 when uploads are in scope.
-     Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not enable remote staff OAuth MCP.
-     At handoff, show the owner where Admin WebMCP and the public/staff MCP
-     endpoints appear, and state which are usable from the browser versus a
-     remote connector.
-   - ChatGPT Sites with custom business rules or an external callback — the
-     runnable reference covers builtin content only. For application-owned
-     operational state, `handler: { kind: ref }` Procedures, staff-only SQL
-     Views, staff MCP Triggers with `requires.auth`, and outbound webhooks
-     called from handler code, follow
-     `docs/handbook/chatgpt-sites/equipment-checkout.md`. It is an implementation
-     guide, not a shipped app: keep Mantle-owned Schema tables and
-     application-owned tables separate, and give every application table a
-     reviewed migration.
-   - Grammar — `docs/examples/README.md`. Copy `builtin-*` Manifests directly.
-     Read `cf-primitives-*` when the request needs Durable Objects, Queues,
-     cron, payment-provider callbacks, or API-key and entitlement guards;
-     those carry `ref` handlers and are not Builder-ingestible.
-   None of these is a template to install wholesale. Other hosts use the
-   embedded adapter guides. Author package scripts, manifests, entry and
-   configuration for the user's requirements. No default notes model, home
-   page, icon, launch metadata or visitor frontend is required.
-4. Compile and verify using the application's commands. The fundamental CLI
-   sequence is:
-
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec mantle validate
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-```
-
-Run the project's TypeScript check and start its actual local server. Probe
-a route the application declares. An API-only or adapter-only project may
-correctly return 404 at `/` and have no Admin. When Admin was requested,
-probe `/admin/sign-in` and a `/_mantle/admin/assets/*` URL — both must be
-200. A white screen is an assets 404, not a missing frontend build.
-Conventional Auth routes may return `503 setup_incomplete` until that mode
-is configured; the local OTP path replaces construction instead. Do not
-introduce an auth bypass to make smoke pass.
-
-Commit the resolved lockfile in the application's normal workflow; subsequent
-installs use `pnpm install --frozen-lockfile`. Do not initialize/push a remote,
-provision resources, deploy or commit secrets as part of local verification.
-
-## Existing application
-
-Read package.json, lockfile, actual entry, manifest files, provider config and
-project instructions. `.mantle/launch-state.json`, features or handoff files
-are optional legacy context, never prerequisites. Preserve them and user code.
-Install the frozen dependency graph, project installed Core skills, then read
-those skills and embedded docs. Never apply develop docs to an older package.
-Use the installed `mantle --help` and the project's scripts as authority.
-
-For a legacy pre-stable project, retain its pinned behavior until an explicit
-upgrade is requested. Do not rewrite provider identities, delete metadata or
-fetch a nonexistent new Starter tag. SDK upgrades follow the update skill, not
-a bundle comparison command.
-
-## Ship and report
-
-When deployment is requested, read
-`node_modules/@aotter/mantle/skills/provision/SKILL.md` (not projected by
-`mantle skills`) and follow that version-matched skill and the
-observed host configuration. Legacy Landing remains a pre-stable product; it
-is not a launch dependency for new Core projects.
-
-Report the project path, exact SDK version, local URL/HTTP result and checks,
-plus any genuinely missing auth/provider setup. Do not claim a working homepage
-or authenticated MCP based only on successful generation.

package/skills/media-gc/SKILL.md

@@ -1,85 +0,0 @@
----
-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.

package/skills/plugin/SKILL.md

@@ -1,132 +0,0 @@
----
-name: plugin
-description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/plugin/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
----
-
-# Mantle Plugin
-
-Mantle plugins are Core SDK capability packages. They are not application
-scaffolds (retired in ADR-0021) and they are not provider provisioning scripts.
-
-A plugin may contribute:
-
-- manifests: `Schema`, `View`, `Procedure`, `Trigger`;
-- handler source or handler registration notes;
-- site defaults or media policy additions;
-- expected HTTP, admin, and MCP surfaces;
-- adapter capability requirements and provider setup notes.
-
-## User Install Entry
-
-The user-facing install path is:
-
-```txt
-Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
-Use repo-local mantle:plugin to update <plugin id> in this repo.
-Use repo-local mantle:plugin to remove <plugin id> from this repo.
-```
-
-There is no `mantle plugin add` CLI yet. Do not invent one. Install from a
-marketplace entry, plugin package, or recipe URL that declares enough data for
-an agent to apply the capability deterministically.
-
-A valid marketplace entry must include:
-
-- plugin id, title, source, and version;
-- supported Mantle version range;
-- files, manifests, handlers, routes, MCP tools, and admin surfaces it adds;
-- adapter capabilities and provider resources it requires;
-- required env vars and secrets, without secret values;
-- verification commands and expected surfaces.
-
-If the marketplace page is only marketing copy or lacks an install recipe,
-stop and ask for the recipe instead of guessing.
-
-## First Read
-
-1. `package.json` for Mantle version and adapter package.
-2. The manifest directory selected by project scripts for current atom names
-   and route/tool collisions.
-3. The actual host entry and its handler, template and port registrations;
-   `src/mantle/config.ts` and `src/mantle/handlers/` are conventions, not required paths.
-4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
-5. `.mantle/launch-state.json` only as context, not as plugin authority.
-
-Read version-matched contracts under `node_modules/@aotter/mantle/docs/`,
-starting with `handbook/reference/features.md`. Plugin recipes cannot override
-the installed grammar.
-
-## Plan First
-
-Before applying any plugin, produce a plan:
-
-- files to add or change;
-- atoms to add and their names;
-- HTTP routes and MCP tools that will appear;
-- required runtime ports;
-- adapter-specific resources, env vars, and secrets;
-- checks to run.
-
-If the plugin needs a capability the current adapter does not expose, stop
-with the missing capability instead of inventing provider steps.
-
-## Apply
-
-Apply the smallest deterministic diff. Do not run arbitrary install scripts
-from a plugin package. Copy declared files, wire declared handlers, update the
-plugin ledger, then validate.
-
-Suggested ledger paths:
-
-```txt
-.mantle/plugins.json
-.mantle/plugins.lock.json
-```
-
-Keep optional legacy launch files such as `.mantle/features.json` separate from
-plugin state. They are not the Core plugin ledger.
-
-## Update
-
-Compare the installed lock entry against the marketplace entry or recipe URL.
-Apply only the declared version diff, update `.mantle/plugins.lock.json`, then
-run the same verification checks.
-
-## Remove
-
-Use the lock entry as the removal manifest. Delete only files and atoms owned
-by that plugin, unwind handler registrations it added, remove its ledger entry,
-then validate. If another plugin or local code depends on a removed atom, stop
-and report the dependency instead of deleting through it.
-
-## Verify
-
-Use the project's validation and typecheck scripts when present. Regenerate
-the plan after manifest changes before probing the running host:
-
-```bash
-pnpm exec mantle validate
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-# Run the project's TypeScript check and restart its local server.
-```
-
-Then verify the plugin's declared surfaces:
-
-- public Views via `GET /api/views/<name>`, staff Views via authenticated
-  Admin/staff MCP, and internal Views through the host binding;
-- HTTP Trigger path for public writes;
-- Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
-- adapter resource presence when the plugin requires optional ports.
-
-## Don't
-
-- Don't treat an application template as a plugin.
-- Don't assume Cloudflare; inspect the active adapter and capability ports.
-- Don't create a second skill namespace for host-specific plugins.
-- Don't commit secrets. Provider secrets stay in the platform secret store.