@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.2

package/docs/spec-only-host-adoption.md

@@ -1,157 +0,0 @@
-# Spec-only adoption in an existing host
-
-An existing application can reuse Mantle's Schema grammar and validation by
-consuming the published `@aotter/mantle-spec` package, without running Mantle
-Runtime. This Spec-only path is allowed by
-[ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
-manifest grammar, or fork of Core.
-
-This recipe targets `0.1.4`. Pin the package, record the tested version, and
-rerun compatibility checks when upgrading.
-
-## What stays with the host
-
-| Concern | Spec reuse | Host responsibility |
-|---|---|---|
-| Model definitions | Schema grammar, parse/link diagnostics | Project existing definitions into supported JSON Schema |
-| Input | `EntryDataValidator` and structured errors | Authentication, authorization, normalization, write orchestration |
-| Model browser | Parsed/linked Schema metadata | UI, metadata visibility, field display, graph layout |
-| Relationships | Translation declaration/link validation | Existing slug joins, record integrity, locale policy |
-| Storage and publishing | None in this recipe | Files, database, transactions, revisions, release/recovery |
-| Operations and tools | None in this recipe | No automatic View, Procedure, Trigger, REST or MCP execution |
-
-Mantle's Web, Admin UI and platform adapters remain optional. A Vue host does
-not have to embed the React Admin SPA to reuse Spec. Avoid importing SDK
-internals or maintaining a second manifest interpreter.
-
-## One definition, several projections
-
-The motivating Aotter official-website implementation keeps its existing
-Nuxt/Nitro host and Git/D1 storage. Shared content definitions drive the site's
-content layer, admin write validation, a responsive model/ER browser, and
-Schema export. That website implementation was validated locally; this SDK
-contribution does not deploy it or claim a production rollout.
-
-```text
-Host-owned content definitions
-  ├─ existing CMS/content queries
-  └─ JSON Schema in Mantle Schema manifests
-       ├─ parse + link → model browser / metadata export
-       └─ EntryDataValidator → host-authorized write path
-```
-
-Use the existing definitions as the source of truth. If the host starts with
-Zod or another schema language, conversion is a host concern: verify that the
-result uses supported JSON Schema keywords and preserves the intended
-validation semantics. Do not hand-maintain a second field list for the graph.
-
-## Minimal public-API recipe
-
-Install the exact Spec package and its supported peer, without Runtime:
-
-```sh
-npm install --save-exact @aotter/mantle-spec zod@4.5.4
-```
-
-The [synthetic fixture](../packages/mantle-spec/test/fixtures/spec-only-host.yaml)
-contains categories, articles and article translations. It contains no real
-website records, account configuration or credentials. Given that fixture as
-`manifestYaml`, the application can prepare its validated model once:
-
-```ts
-import {
-  EntryDataValidator,
-  parseManifestSources,
-  ValidateManifestsUseCase,
-} from "@aotter/mantle-spec";
-
-const parsed = parseManifestSources({
-  sources: [{ sourceId: "host:content-model", text: manifestYaml }],
-});
-if (!parsed.ok) throw new Error(JSON.stringify(parsed.diagnostics));
-
-const checked = ValidateManifestsUseCase.run({
-  parsed: parsed.value,
-  siteLocales: ["zh-TW", "en-US"],
-});
-if (checked.errorCount || !checked.linked) {
-  throw new Error(JSON.stringify(checked.diagnostics));
-}
-
-const article = checked.linked.schemas.find(
-  ({ manifest }) => manifest.metadata.name === "articles",
-)!.manifest;
-const validator = new EntryDataValidator();
-const diagnostics = validator.validate(article, { category: 42 }, { partial: true });
-// INPUT_VALIDATION_FAILED at /category. The host must reject the write.
-```
-
-The non-null assertion is specific to this known fixture. A dynamic host must
-handle an unknown collection explicitly and fail closed. Do not fabricate
-sealed parser/linker values or re-parse the same revision in each request.
-
-`EntryDataValidator` returns diagnostics, not a sanitized payload. It does not
-persist, authorize, coerce the original object, or enforce storage integrity.
-Normalize explicitly in the host before validation and write only after
-successful validation and authorization. An `additionalProperties: true`
-compatibility policy accepts legacy fields; it is not a reason to expose those
-fields publicly.
-
-`partial: true` relaxes top-level required fields for drafts, while still
-checking supplied types and nested required fields. Validate without `partial`
-when the host needs a complete record, alongside its own publication rules.
-Create a fresh validator for each model revision: its compiled cache is keyed
-by manifest name (and partial/full mode), not by a changing schema body.
-
-## Honest ER diagrams and metadata export
-
-- Derive model nodes and field details from Schema properties. Use a small
-  host-owned relationship registry for relations not represented by Mantle
-  grammar; show logical joins distinctly from actual database foreign keys.
-- The fixture's `x-example-source` and `x-example-relations` live inside JSON
-  Schema. They are illustrative vendor annotations, **not new Mantle keys or
-  executable relationship definitions**. Core may preserve them without
-  interpreting them. The host must validate their shape and endpoint fields.
-- Do not label a filename/slug join as `x-mantle-ref`: that keyword represents
-  Mantle entry-ID references. A category slug matching a key inside a YAML
-  array remains a host-specific relation, not a generated SQL foreign key.
-- `translates` validates the parent and join-field declarations, not whether
-  actual translation records exist. A Spec-only host still owns allowed
-  locales, uniqueness, fallback, and orphan handling. See
-  [ADR-0010](adr/0010-locale-and-translates.md); Runtime locale/storage gates
-  are not installed by this recipe.
-- A read-only inventory can add derived fields such as filename `slug` or
-  directory `locale` without changing stored files. Document that projection;
-  it is not evidence that existing data is ready for Runtime import.
-- The fixture uses JSON Schema `readOnly` as an inventory annotation. It is
-  not a security boundary: entry validation does not enforce host write
-  permissions. Export only after applying the host's metadata access policy.
-- Exclude credential/account models and private data. Export schemas, not
-  records. Where appropriate, require an administrator and use
-  `Cache-Control: private, no-store` for model and export endpoints.
-- Keep the graph usable on narrow screens: searchable model selection,
-  focused relationships, zoom/scroll, keyboard controls and a field-table
-  alternative. A graph must not be the only accessible representation.
-
-## Reproducible evidence
-
-From this SDK checkout:
-
-```sh
-pnpm --filter @aotter/mantle-spec test -- test/spec-only-host.test.ts
-pnpm --filter @aotter/mantle-spec typecheck
-```
-
-The [regression test](../packages/mantle-spec/test/spec-only-host.test.ts)
-exercises the public export surface, manifest round trips, translation linking,
-and strict/partial entry validation without Runtime. It is an SDK regression
-fixture, not a new Starter workspace or a certification test suite.
-
-An adopting host must also test its own installed package, real content
-compatibility, HTTP authorization/invalid-input paths, metadata exclusions and
-responsive UI. Existing data need not be published or uploaded to prove this.
-Keep sensitive evidence internal and expose only an agreed verification report.
-
-Spec validation against an exact SDK version is not official certification or
-proof of Runtime compatibility, data migration, or security. Recognition policy
-is tracked separately in [#840](https://github.com/aotter/mantle/issues/840).

package/docs/transaction-patterns.md

@@ -1,5 +0,0 @@
-# Transaction patterns
-
-This guide lives in the Examples hub: [`docs/examples/cf-primitives-commerce-inventory.md`](examples/cf-primitives-commerce-inventory.md). The Builder-safe catalog is [`docs/examples/builtin-commerce.md`](examples/builtin-commerce.md).
-
-The handbook and examples hub ship inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/` and describe the installed release.

package/skills/README.md

@@ -1,127 +0,0 @@
-# SKILL.md briefs (mantle)
-
-Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by URL — no plugin install needed.
-
-| Skill | When to invoke |
-|---|---|
-| [`develop`](../docs/skills/develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
-| [`integrate`](../docs/skills/integrate/SKILL.md) | `mantle:integrate`: choose and carry out an existing application's Mantle integration or rebuild and data migration. |
-| [`media-gc`](../docs/skills/media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
-| [`plugin`](../docs/skills/plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
-| [`theme`](../docs/skills/theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
-| [`update`](../docs/skills/update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
-| [`mantle`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
-| [`provision`](../docs/skills/provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
-
-The skills target Mantle's v0.1 grammar. The installed package version, not
-duplicated skill prose, selects the exact runtime and embedded docs.
-
-## Disclosure audit
-
-Every skill ships as one `SKILL.md` with no reference files, scripts, or
-assets, so nothing is deferred behind a second load. Progressive disclosure
-here is section routing inside one file: the agent reads the entry constraints,
-then only the section its selected path names. `scripts/check-skills.mjs`
-enforces the columns below.
-
-| Skill | Routes on | Entry-path constraints (read before acting) | Path-gated sections | Projection | Restricted because |
-|---|---|---|---|---|---|
-| `develop` | existing project; manifest, runtime, handler, adapter, or MCP work | four-atom model; adapter neutrality; no direct D1/KV/Postgres writes; no committed secrets | performance harness; local MCP client; locale rules | project | — |
-| `integrate` | independently authored application; add Mantle or rebuild with migration | inspect application before strategy; version-matched SDK; protect live data | embed; incrementally replace; rebuild and migrate | package | Existing-project migration is opt-in; a fresh generated app does not need this brief. |
-| `plugin` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project | — |
-| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project | — |
-| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project | — |
-| `mantle` | new application, or opening an existing project | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | author local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
-| `provision` | ship to Cloudflare and finish production auth | secrets never enter source or logs; explicit auth mode | hosted auth; self-managed auth | package | Platform-specific deploy that handles production secrets; opt-in only. |
-| `media-gc` | audit or remove stale uncommitted media objects | audit by default; confirm exact account, bucket, cutoff, and candidate digest; re-audit before applying; never prefix-delete; never print keys | apply | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
-
-Deliberately monolithic:
-
-- `develop` is the widest file, but its adapter, auth, and data-ownership rules
-  constrain every path through it. Splitting them behind routing would let an
-  agent reach a write path without them, which is the failure this audit
-  exists to prevent.
-- `media-gc` keeps its full audit-confirm-reapply sequence inline for the same
-  reason: each safeguard is a precondition of the delete that follows it.
-
-## Skill authority
-
-The `mantle:*` namespace is owned by `@aotter/mantle`. Every skill declares its
-own distribution scope in front matter: `metadata.projection: project` marks a
-skill `mantle skills` should place in a consumer project, and a skill that
-withholds `project` must say why. `plugin` is the bootstrap skill and `package`
-is an opt-in brief in the installed SDK. `scripts/check-skills.mjs` holds that
-declaration and the audit table below to each other.
-
-Run `mantle skills` to project the installed package's skills into a project;
-use `mantle skills --check` to fail closed on drift. The installed package and
-`node_modules/@aotter/mantle/docs/` are the single version-matched authority.
-Application files and plugin recipes are project context, not competing
-contracts.
-
-## Source-repository marketplace install
-
-`skills/install/SKILL.md` declares `name: mantle`. It is the only repository
-skill discovered by the no-flag command and copied as a small directory.
-The other seven skills live in `docs/skills/` and ship with the npm package.
-`mantle skills` projects the four ongoing workflows after package installation.
-
-Other marketplace hosts point to the same entry:
-
-```sh
-npx skills add aotter/mantle
-```
-
-```bash
-# Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
-
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
-```
-
-Read the path printed by the installer (for project-local Codex,
-`.agents/skills/mantle/SKILL.md`). Only the selected brief is installed, not
-the SDK or handbook. After choosing and installing an exact SDK version, read
-`node_modules/@aotter/mantle/skills/install/SKILL.md` and its embedded docs;
-that package supersedes the bootstrap Git-ref instructions. After packages are
-installed, `mantle skills` projects the installed package's own skills into the
-project, and `mantle skills --check` fails on drift.
-
-Cursor and GitHub Copilot read their manifests from the repository directly.
-These manifests are not duplicated into the npm package:
-
-- Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
-- Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
-- Cursor: `.cursor-plugin/plugin.json`.
-- VS Code + GitHub Copilot: `.copilot-plugin/plugin.json`.
-
-## Audience
-
-These are written for **AI agents acting on behalf of consumers of mantle**,
-not for contributors maintaining the Mantle SDK itself. SDK contributors use
-the repo-root `CONTRIBUTING.md`; it is intentionally not shipped inside the npm
-package. Two audiences, two artifacts.
-
-## Discoverability
-
-The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "develop my Mantle site", "deploy"). Official cold start is `npx skills add aotter/mantle`. Point the agent at the repository or pass the version-matched markdown content directly.
-
-## Conventions
-
-Each SKILL.md ships:
-
-- **Front-matter** with a stable `name`, trigger-complete
-  `description`, and optional source/version `metadata`. Plugin hosts add the
-  external `mantle:` namespace.
-- **Preflight** section — environment + user-confirmation gates.
-- **Step-by-step** — concrete commands (`pnpm validate`, `mantle emit-openapi`, etc.).
-- **Diagnostic recipes** — `Symptom → Cause → Fix` table for the common failure modes.
-- **Don't** — reviewer-style list of patterns the agent must reject (often citing ADRs).
-- **When you're done** — what to report back to the user.
-
-If you're writing a new SKILL, follow the same structure. Commands and prose
-must match the package version that carries the skill; later prereleases may
-revise both together.

package/skills/develop/SKILL.md

@@ -1,258 +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
-```
-
-On 0.1.5 and newer, `generate --host cf|chatgpt-sites` assembles a new blank
-app; no `--features` selects Spec, Runtime, API, MCP, Admin and Web. Explicit
-`--features` selects a smaller composition. It never invents a business
-Schema. Existing authored apps keep compile mode, and older installed CLIs
-may not support project generation. Check this project's CLI help first.
-
-## 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
-
-Generated full apps select Admin by default; smaller selections can omit it.
-A project without `@aotter/mantle-admin-ui` is complete when Admin was not
-selected. If Admin was selected but its package is missing, install the
-CLI-declared exact version and rerun generation.
-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.
-
-Generated Cloudflare apps use `MANTLE_AUTH_MODE=local-otp` on loopback after
-copying `.dev.vars.example` to `.dev.vars` and setting a real owner email and
-random secret. Production uses `hosted` or `self-managed` with provider
-credentials and `ADMIN_GITHUB_LOGIN`. Conventional Cloudflare projects that
-do not replace Auth use those two production modes; 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,112 +0,0 @@
----
-name: mantle
-description: Set up a new Mantle application or continue an existing one using the installed SDK's matching instructions.
-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
-
-`npx skills add aotter/mantle` installs this small bootstrap skill. It does not
-install the SDK or create a project. The skill name is `mantle`; the source
-folder remains `skills/install/` so installation does not copy the repository.
-
-## Find the application and its version
-
-First locate the user's target project. If it already has `@aotter/mantle`,
-read that project's `package.json`, lockfile, and
-`node_modules/@aotter/mantle/package.json`. Follow the CLI and docs shipped in
-that exact installed package. Never use another project's dependencies, the
-SDK checkout, a floating GitHub handbook, or an old alpha/Starter fallback.
-An older installed SDK may only support direct authoring; its own
-`mantle generate --help` decides which flags exist. Upgrade only when requested.
-
-For a new project, choose `cf` or `chatgpt-sites` from the request; ask only if
-it remains ambiguous. A host-free Spec-only project needs no host. Resolve the
-latest **published stable** `@aotter/mantle` version from npm once, confirm it
-is not a prerelease, and install it with an exact version in the new project.
-For example, run `npm view @aotter/mantle@latest version`, inspect the returned
-plain `X.Y.Z`, then `npm install --save-exact @aotter/mantle@X.Y.Z` with that
-actual version substituted. Set `type=module` in `package.json` first; npm's
-default project type may be CommonJS.
-When testing a release candidate, use the explicitly supplied exact version
-or local tarball instead of npm latest. Pin every selected `@aotter/mantle*`
-package to the running CLI's exact version; `generate` writes the required
-package declarations. Do not let npm's default `^` range remain. If the
-project registry overrides public npmjs, set `@aotter:registry=https://registry.npmjs.org/`
-in a project-owned `.npmrc`.
-
-## New project sequence
-
-1. Create a separate application directory with Node 22+ and a project
-   `package.json` containing `"type":"module"`. Install the exact chosen
-   `@aotter/mantle` version locally. Read its
-   `node_modules/@aotter/mantle/skills/install/SKILL.md` and version-matched
-   `docs/handbook/start/overview.md` before continuing. These installed
-   instructions take precedence over this GitHub bootstrap copy. Check
-   `npx mantle generate --help`: if it does not list `--host`, follow the
-   installed version's direct-authoring path instead of the steps below.
-2. On a CLI that supports it, run with an explicit host, for example
-   `npx mantle generate --host cf` or `npx mantle generate --host chatgpt-sites`.
-   No `--features` means Spec, Runtime, API, MCP, Admin and a blank editable
-   home. For a smaller app, positively list the modules with `--features`
-   (for example `spec,api`); use `--features spec` for a host-free compiler.
-   Do not remove Admin merely because its package is not installed yet.
-3. The first run may declare selected dependencies and exit asking for an
-   install. Install them using the project's package manager, then rerun
-   `mantle generate` to finish. Read `docs/handbook/start/project-and-cli.md`
-   from the same installed package for saved selections, owned files,
-   `--check`.
-4. Before adding a Schema on ChatGPT Sites, review and apply its initial local
-   D1 migration as the installed Sites guide says. Then add only the user's
-   Schema, View, Procedure and Trigger manifests. Keep the blank home editable;
-   do not invent business data or media bindings. Run `mantle generate` to
-   append any new migration, review and apply it, then run `generate --check`,
-   `validate`, `skills`, build/typecheck and local smoke.
-5. For Cloudflare, follow installed `docs/handbook/start/project-and-cli.md`
-   and `docs/handbook/cloudflare/authentication.md`. Copy `.dev.vars.example`
-   to `.dev.vars`, set `ADMIN_EMAIL` and `BETTER_AUTH_SECRET`, and match
-   `PUBLIC_ORIGIN` to the loopback URL printed by `wrangler dev`. Open
-   `/admin/sign-in` with that email; read the OTP from wrangler logs. Check
-   Admin assets and an owner-only Admin API before claiming Admin works. For
-   ChatGPT Sites, follow installed
-   `docs/handbook/chatgpt-sites/generated-app.md`: review and apply local D1
-   migrations, set `OWNER_EMAIL` and `PUBLIC_ORIGIN`, then test the blank home,
-   unauthorized Admin, owner Admin, public MCP and staff MCP. Local owner
-   identity is simulated by the loopback-only smoke; it does not create a
-   browser ChatGPT session. Sites owns
-   production identity and deployment; do not deploy its Worker directly.
-   Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not provide
-   remote staff OAuth MCP. The owner can maintain content through Admin and
-   the applicable authenticated MCP surface.
-
-Use installed `docs/handbook/reference/features.md` for Manifest choices and
-`docs/examples/` for optional examples. The generated project is the starting
-point; a domain example is not a template to copy wholesale. Do not use a
-`mantle-starters` tag or `mantle create`.
-
-## Existing project and handoff
-
-For an application that already uses Mantle, preserve selected features,
-user-authored files, migrations, package versions, identity settings and
-provider resources. Use its installed CLI's `--help` and package-local docs.
-Run `generate --check` without writing, then the project's normal tests.
-
-When the request is to add Mantle to an independently authored application,
-inspect its host, code and data first. Use the exact installed package's
-`docs/skills/integrate/SKILL.md` if available. If Mantle is not installed,
-choose between selective embedding, incremental replacement and creating a
-separate Mantle app followed by frontend/data migration before installing an
-exact SDK version. The existing application does not need to adopt the
-generated project's entry or directory layout. An older SDK's own docs and
-CLI govern its behavior; upgrade deliberately if the selected strategy needs
-newer capabilities.
-
-When deployment is requested, read the installed version's
-`skills/provision/SKILL.md`. Report the target path, exact SDK version, local
-HTTP results, Admin/MCP identity evidence, and any missing provider setup.
-Local simulated Sites headers do not prove deployed ChatGPT sign-in.