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

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/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.

package/skills/integrate/SKILL.md

@@ -1,60 +0,0 @@
----
-name: integrate
-description: Integrate Mantle into an existing application. Use when the application has its own code, routes, storage or deployment and the owner wants to add Mantle, replace part of it, or rebuild with Mantle while migrating frontend and data.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/integrate/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: package
-  projectionReason: Existing-project migration is opt-in; a fresh generated app does not need this brief.
----
-
-# Integrate Mantle into an existing application
-
-Work in the target application. Read its installed `@aotter/mantle` version,
-CLI help and package-local docs before editing. If Mantle is absent, inspect
-the application first, then install an exact SDK version only after choosing an
-integration strategy. Use the installed version's contract; do not copy
-`develop` branch examples into an older consumer.
-
-## Inspect and decide
-
-Map the actual entry points, router, frontend, auth, storage, data volume and
-relationships, deployment pipeline, URLs, background jobs and existing tests.
-Identify which behavior the owner wants Mantle to own and what must remain
-stable. Compare three approaches using the application's evidence:
-
-1. **Embed selectively:** keep the host and call Mantle's parser, Runtime or
-   selected surfaces through its documented package APIs. The host owns wiring.
-2. **Replace incrementally:** move one bounded capability at a time. Define
-   where reads and writes go during coexistence and how each step is checked.
-3. **Rebuild and migrate:** create a separate new Mantle application, port the
-   frontend and business behavior, and transform/import existing data. Prefer
-   this when adapting the old structure costs more than rebuilding. Preserve
-   relevant IDs, relations, URLs and identity semantics; rehearse the data
-   transfer before a production cutover.
-
-Explain the chosen path and its concrete tradeoffs to the owner. A small
-prototype or read-only inventory may resolve uncertainty. Do not run a generic
-project converter or assume the current application's shape matches a
-generated Cloudflare or ChatGPT Sites skeleton.
-
-## Implement and verify
-
-- For embedding, retain user-owned entry/config/build files. Use the installed
-  direct-authoring docs and CLI to validate manifests and emit bindings; wire
-  the selected Mantle capabilities into the existing host explicitly.
-- For incremental replacement, establish a clear owner for each data write
-  and request route at every stage. Verify old and new behavior together.
-- For rebuilding, generate in a **separate directory** with the installed
-  CLI, move frontend and handlers deliberately, and plan data mapping and
-  import separately. Review database migrations before application or cutover.
-- Run the application's build and representative behavior checks for the
-  changed routes, auth and data. `mantle generate --check` checks generated
-  output against its declared selection; it cannot certify host integration.
-  For live data, record migration counts and a rollback or recovery path
-  appropriate to the project.
-
-Leave existing data and deployment untouched until the requested migration
-and release steps are ready. Report which capabilities Mantle now owns,
-what was verified, and what remains for application deployment or cutover.