@aotter/mantle 0.1.4 → 0.1.5-alpha.1

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

@@ -1,140 +1,124 @@
 ---
-description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and version pins.
+description: Generate a full Mantle app or select smaller modules, then safely rerun the CLI as your manifests evolve.
 ---
-# Project layout and the CLI loop
+# Project layout and CLI
 
-This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
+`mantle generate` can assemble a new application or compile manifests in an
+existing one. A new hosted app defaults to Spec, Runtime, API, MCP, Admin and
+an editable blank home. You can select a smaller set explicitly. It never
+invents a business Schema or publishes a deployment.
 
-Agents can bootstrap with the install skill; human authors can follow this guide directly. For installation paths and the pinned-package handoff, see [Agent setup](../guides/agent-setup.md):
+## Start a new app
 
-```sh
-npx skills add aotter/mantle
-```
-
-## You own the project
-
-Core is a manifest compiler and a runtime, not a project generator. You write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
-
-```txt
-my-service/
-├── package.json              exact-pinned @aotter/mantle* + peers, scripts
-├── tsconfig.json             includes src/ and .mantle/generated/
-├── wrangler.jsonc            Worker name, flags, vars, bindings
-├── .dev.vars                 local secrets for wrangler dev; never committed
-├── manifests/
-│   └── site.yaml             immediate .yaml/.yml files; multi-document with ---
-├── src/
-│   ├── index.ts              createMantleWorker({ plan, extend })
-│   └── mantle/handlers/      handler refs (a convention; any path under src/)
-├── public/                   required ASSETS root when Admin is installed; generate writes public/_mantle/admin/
-├── .mantle/generated/
-│   └── mantle.ts             written by mantle generate
-├── .agents/skills/mantle-*/  written by mantle skills
-└── .claude/skills/mantle-*/  same bytes, for Claude compatibility
-```
-
-The minimal Worker reference keeps `.mantle/`, `.agents/`, `.claude/`, `.wrangler/`, `.dev.vars*` and `.env*` out of git and regenerates the first three in its `check` script. Committing the generated files is also workable, because `generate --check` and `skills --check` detect drift either way. Commit the lockfile in a real application and install with `--frozen-lockfile` afterwards.
-
-`mantle validate` greps `./src` for the names of `handler.kind: ref` Procedures; a handler that is not found anywhere under `src/` produces a `HANDLER_NOT_REGISTERED` warning, so keep handlers under that root or pass `--source`.
-
-## The CLI
-
-The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones. Bare `mantle` / `mantle --help` prints a layered overview of optional surfaces (Minimal Spec + generate, Runtime / adapter, opt-in Admin). `generate --help` and `validate --help` stay on the compile path. After a successful `generate`, the CLI says Admin is opt-in: next steps when `@aotter/mantle-admin-ui` is installed, otherwise an API-only tip.
-
-| Command | Flags | Does |
-|---|---|---|
-| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check` | Validate, link and compile manifests; write `mantle.ts`; sync Admin assets when installed. `--check` exits 1 without writing when output is stale. |
-| `mantle validate` | `--manifests <dir>`, `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text`, `--json` | Static manifest and handler-source validation. Exit 0 with warnings allowed, 1 on any error, 2 on a CLI invocation problem. |
-| `mantle skills` | `--check` | Copy every skill marked `projection: project` into `.agents/skills/mantle-<name>/` and `.claude/skills/mantle-<name>/`. `--check` exits 1 when a projection is stale. |
-| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>` | Emit OpenAPI 3.1 for HTTP Triggers and `GET /api/views/<name>` routes to stdout or a file. MCP is out of scope. |
-| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>` (default 2000), `--require <view>` (repeatable), `--require-public`, `--format text\|json` | Execute compiled Views in crowded SQLite and inspect query plans; exit 1 when a required View lacks its access path. |
-| `mantle-harness http` | `--base-url <url>`, `--route <name=path-or-url>` (repeatable, required), `--rounds <n>` (default 20), `--warmup <n>` (default 2), `--format text\|json` | Sample a running Worker and report p50/p95 timings plus query-count and `rows_read` metric headers. |
-
-Advanced manifest primitives live in the `@aotter/mantle-spec` package's own `mantle-spec` binary: `mantle-spec introspect [--manifests <dir>]` dumps the parsed manifest tree as JSON, and `mantle-spec emit-types [--manifests <dir>] [--namespace <name>] [-o <file>]` emits standalone `.d.ts` declarations. Add `@aotter/mantle-spec` as a direct dependency to run them. The full flag reference is in [HTTP, MCP, CLI and packages](../reference/surface.md).
-
-### What `generate` does and does not do
-
-`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the **prebuilt** Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
-
-Do not Vite-build Admin unless you are developing `@aotter/mantle-admin-ui` itself. A Cloudflare project that serves Admin must declare Static Assets:
+Choose a host before running the command. The integrated hosts are `cf` and
+`chatgpt-sites`; `--features spec` works without a host. Install one exact
+published SDK version, then let the CLI declare its matching optional packages:
 
-```jsonc
-"assets": { "directory": "./public", "binding": "ASSETS" }
+```sh
+mkdir my-app && cd my-app
+npm init -y
+npm pkg set type=module
+MANTLE_VERSION=$(npm view @aotter/mantle@latest version)
+npm install --save-exact "@aotter/mantle@$MANTLE_VERSION"
+npx mantle generate --host cf
+npm install
+npx mantle generate
+npm run build
 ```
 
-That binding is a hard requirement. If `/admin` returns SPA `index.html` (`200`) while `/_mantle/admin/assets/*` is `404`, the page white-screens. Leave `/_mantle` out of `run_worker_first` so those files stay on the assets layer. `generate` warns when it syncs Admin and the local wrangler config has no `ASSETS` binding.
-
-It does not project skills, update packages, change styling, provision providers, or deploy. It does not create manifests: a missing or empty `manifests/` directory is an error, not a prompt.
-
-## The generated module
-
-`.mantle/generated/mantle.ts` exports:
+Confirm `MANTLE_VERSION` is a stable release, without a prerelease suffix.
+Use `--host chatgpt-sites` for a Site; [its guide](../chatgpt-sites/generated-app.md)
+continues with D1 migration, owner identity and local smoke. If you already
+use pnpm, keep that one package manager and run `pnpm install` /
+`pnpm exec mantle`. The first `generate` may exit asking you to install newly
+declared packages; the second completes generation. A README or lockfile from
+bootstrapping still counts as a new app. Once choices are saved, omit flags on
+rerun.
 
-| Export | Purpose |
-|---|---|
-| `plan` | The sealed RuntimePlan with its fingerprint. The conventional Worker imports only this. |
-| `MantleHandlers<Env>` | The handler map type: one typed function per `handler.kind: ref` Procedure, receiving `(input, ctx)`. |
-| `createMantle({ storage, handlers, ports })` | Prepares storage eagerly once and returns the typed binding. No caching or retry. |
-| `bindMantle(runtime)` | The same typed binding over a runtime whose lifecycle the host already owns. |
-
-The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. See [Typed queries](../guides/typed-queries.md) for internal Views and entry-reader examples. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
-
-## The daily loop
+For a smaller composition, list wanted modules positively:
 
 ```sh
-pnpm install --frozen-lockfile
-pnpm exec mantle validate
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-pnpm test                      # only when the project declares a test script
-pnpm exec mantle-harness indexes --require-public --format text
-pnpm exec wrangler dev --local
+npx mantle generate --host cf --features spec,api
+npx mantle generate --features spec
 ```
 
-Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works. When Admin is installed, also probe `/admin/sign-in` and one `/_mantle/admin/assets/*` URL — both must be `200`. HTML 200 with asset 404 is the white-screen class of bug.
-
-## Connecting an agent
+Dependencies are expanded in the saved selection: `api` includes Runtime and
+Spec; `admin` includes Runtime, API and MCP. Supported features are `spec`,
+`runtime`, `api`, `mcp`, `admin`, `web`. No host is needed for Spec-only. Use an
+explicit host in automation so a terminal prompt cannot stall. The selection
+lives in `mantle.config.json`; changing it later requires a deliberate migration,
+not an accidental CLI flag.
 
-`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `mantle`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
+## Files and ownership
 
-Install the bootstrap skill in the agent host. Cold start uses
-the install skill; an already-installed project pins packages from `package.json`:
+| File | Owner | What happens on rerun |
+|---|---|---|
+| `manifests/*.yaml`, `src/handlers.ts`, `src/home.ts` | You | Preserved. Add domain behavior and edit the blank home here. |
+| `package.json`, `mantle.config.json`, `wrangler.jsonc` | Shared | Required versions and scripts are added; existing user values are preserved or conflicts reported. |
+| `.mantle/generated/*`, `src/storage-fingerprint.json` | CLI | Rebuilt from the saved selection and manifests. |
+| `drizzle/*.sql` on Sites | Review and apply | New migrations append; applied migrations are never rewritten. |
+| `public/_mantle/admin/*` | CLI | Prebuilt Admin assets copied from the selected exact package. |
+| `.openai/hosting.json` on Sites | Sites | Binding metadata is created locally; existing project metadata is preserved. |
+
+A generated Worker imports the sealed `plan`, your handler map and the selected
+modules. Generated files carry a marker so the CLI can distinguish them from
+user-owned code. A rerun refuses to replace an unmarked file. Existing
+applications without a saved selection keep their direct-authoring compile
+behavior. For integration into an independently authored application, use the
+installed `docs/skills/integrate/SKILL.md` to choose an embedding, incremental
+replacement or rebuild strategy. Generation does not verify arbitrary host
+entry points or deployment wiring.
+
+`generate` accepts `--manifests <dir>` (default `./manifests`), `--output <dir>`
+(default `.mantle/generated`), `--namespace <name>`, `--host cf|chatgpt-sites`,
+`--features <comma-list>` and `--check`. Check mode exits nonzero
+on drift and does not write. Sites also accepts `--review-unique-indexes` for
+an explicit, source-bound unique tuple migration and duplicate preflight;
+[review the D1 procedure](../chatgpt-sites/generated-app.md) before applying
+it. `mantle validate` checks grammar and linked
+capabilities; `--phase deploy` adds deployment checks. `mantle skills` projects
+the installed SDK's project skills into `.agents/skills/` and `.claude/skills/`;
+`mantle skills --check` detects drift. `mantle emit-openapi` describes HTTP
+Triggers and View REST routes; `mantle-harness indexes` and `http` inspect
+queries and running routes. [Command reference](../reference/surface.md).
+
+## Verify the assembled app
 
 ```sh
-# Canonical
-npx skills add aotter/mantle
-
-# 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
+npx mantle generate --check
+npx mantle skills
+npx mantle skills --check
+npm run typecheck
+npm run build
+npm run dev
 ```
 
-The projected `develop` skill tells the agent to read `package.json` for the installed version, the manifests and adapter config, and the docs under `node_modules/@aotter/mantle/docs/` before editing. To connect an MCP client to the running Worker, see [MCP and agents](../concepts/mcp-and-agents.md).
-
-## Version pins
-
-- Pin every `@aotter/mantle*` package to one exact version and move them together. Check that release's peer ranges when you move.
-- This handbook describes the snapshot in this source tree. Use the docs that ship with the version in `package.json`, not a floating branch.
-- The authoring CLI is `generate`, `validate`, `emit-openapi` and `skills`. `mantle-harness` is the measurement binary. There is no `create` / `update` happy path.
-- When you change versions: pin the new exact version and refresh the lockfile; keep the Worker, D1, KV identity, origins, auth mode and secrets; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
+Run scripts that exist in the selected project; Spec-only has no server to
+start. Run `npx mantle validate` after adding the first Manifest: the validator
+reports `MANIFEST_ROOT_NOT_FOUND` on an intentionally empty app. A full
+Cloudflare app should serve the blank home and Admin assets.
+For local CF Admin, copy `.dev.vars.example` to `.dev.vars`, replace
+`ADMIN_EMAIL` with the intended owner's address and `BETTER_AUTH_SECRET` with
+a random 32-byte secret, and keep `PUBLIC_ORIGIN` equal to the loopback URL
+wrangler prints. Open `/admin/sign-in` with that email and read the OTP in
+wrangler logs. Check that `/_mantle/admin/assets/*` loads, an anonymous
+`/admin/api/site-settings` request is denied, and the signed-in owner can read
+it. Verify anonymous staff MCP access fails before claiming it works. A full
+Site must also apply its reviewed
+D1 migration before the Worker boots. The public MCP endpoint is discoverable
+without a staff session; the staff endpoint requires the host's verified
+identity and a Mantle role. See [MCP and agents](../concepts/mcp-and-agents.md).
+
+For an already installed app, confirm `node_modules/@aotter/mantle/package.json`
+and the lockfile agree. Use that package's CLI and `docs/` tree; the latest
+GitHub handbook may describe a newer release. Keep all selected
+`@aotter/mantle*` packages on one exact version. The prior direct-authoring
+contract remains valid for older installed SDKs; upgrade deliberately using
+[release notes](../releases/index.md).
 
 ## Source
-- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
-- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/MantleCli.ts`](../../../packages/mantle-spec/src/infrastructure/cli/MantleCli.ts)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+
+- [Generate CLI](../../../packages/mantle/src/cli/generate.ts)
+- [Project selection and package pins](../../../packages/mantle/src/cli/generate-project.ts)
+- [Cloudflare assembly](../../../packages/mantle/src/cli/generate-cloudflare.ts)
+- [ChatGPT Sites assembly](../../../packages/mantle/src/cli/generate-sites.ts)

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

@@ -3,9 +3,11 @@ description: "Open local Admin in one shot: follow the official OTP example, bin
 ---
 # Quickstart: local Admin
 
-Admin is **opt-in**: use it when humans need a Dev UI. A complete Mantle
-service does not require this surface. The default embed path — Spec + Worker
-without Admin — is [Quickstart: a minimal Worker](./quickstart-worker.md).
+New generated CF and Sites apps include Admin by default. To leave it out,
+select smaller features explicitly. This tutorial shows the existing
+direct-authored Worker integration with local email OTP; use it when you own
+the Worker entry. [Project layout and CLI](./project-and-cli.md) describes the
+new generated path.
 
 The procedural source of truth is the official example:
 
@@ -29,7 +31,7 @@ Traps (documented on the example):
 - `pnpm check` / smoke rewrites `.dev.vars` to a smoke-only port — restore it
   from `.dev.vars.example` before `pnpm dev`.
 
-Install every `@aotter/mantle*` package from the `latest` dist-tag; see
+Pin every selected `@aotter/mantle*` package to the same exact version; see
 [Versions](../reference/surface.md#versions). Admin needs both
 `@aotter/mantle-admin` and `@aotter/mantle-admin-ui`, wrangler `ASSETS` on
 `./public`, and `createAuth` email-otp + `ConsoleEmailSender`.

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

@@ -3,7 +3,13 @@ description: "Author a minimal Cloudflare Worker from scratch: one Schema, one p
 ---
 # Quickstart: a minimal Worker
 
-This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Resolve the intended release once and pin every `@aotter/mantle*` package to it; see [Versions](../reference/surface.md#versions).
+This page reproduces the API-only Worker reference as a direct-authoring
+walkthrough: View REST without Admin, Auth or a visitor frontend. For a new
+project, `mantle generate --host cf --features spec,api` assembles that smaller
+composition. Omit `--features` to include Admin, MCP and a blank home. The
+[local Admin tutorial](./quickstart-admin.md) covers an authored Worker entry.
+Pin every selected `@aotter/mantle*` package to one exact version; see
+[Versions](../reference/surface.md#versions).
 
 ## Prerequisites
 
@@ -13,10 +19,9 @@ This page reproduces Core's API-only Worker reference as a from-scratch walkthro
 
 ## 1. `package.json`
 
-The `latest` entries below are bootstrap placeholders. Step 5 replaces both
-with one exact version before the first build. For a prerelease evaluation,
-select its exact version explicitly rather than mixing channels. The other
-entries are the peers and tools used by this reference.
+Step 5 adds the two Mantle packages at one exact version. For a prerelease
+evaluation, select its exact version explicitly rather than mixing channels.
+The entries below are the peers and tools used by this direct-authored reference.
 
 ```json
 {
@@ -31,8 +36,6 @@ entries are the peers and tools used by this reference.
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit"
   },
   "dependencies": {
-    "@aotter/mantle": "latest",
-    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",
@@ -172,7 +175,13 @@ curl -i http://127.0.0.1:8787/mcp/staff
 - `.mantle/generated/mantle.ts` — one module with the sealed `plan`, generated types (`MantleHandlers<Env>`), `createMantle` and `bindMantle`. The Worker entry above imports only `plan`.
 - `public/_mantle/admin/` — the Admin SPA, synced only when `@aotter/mantle-admin-ui` is installed. This project did not install it, so nothing is written there and `/admin` has no assets.
 
-`generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. `mantle generate --check` reports stale output without writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
+This walkthrough uses the existing direct-authored Worker entry; in that legacy
+compile mode, `generate` expects the supplied manifests and does not add a
+home route. New applications can instead use `mantle generate --host cf`
+with `--features spec,api` for a smaller assembled Worker. The CLI never
+invents a Schema. `mantle generate --check` reports stale output without
+writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git
+and regenerates them in `check`; see [Project layout and CLI](./project-and-cli.md).
 
 ## Next steps
 

package/docs/skills/develop/SKILL.md

@@ -57,9 +57,11 @@ 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.
+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
 
@@ -155,7 +157,10 @@ teaching the project Mantle internals.
 
 ## Auth Composition
 
-Admin is opt-in. A project without `@aotter/mantle-admin-ui` is complete.
+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
@@ -164,8 +169,11 @@ 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
+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.

package/docs/skills/integrate/SKILL.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.4",
+  "version": "0.1.5-alpha.1",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Auth, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -80,11 +80,12 @@
     "dist",
     "docs",
     "skills",
+    "templates",
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.4",
-    "@aotter/mantle-spec": "0.1.4"
+    "@aotter/mantle-runtime": "0.1.5-alpha.1",
+    "@aotter/mantle-spec": "0.1.5-alpha.1"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -92,13 +93,13 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin-ui": "0.1.4",
-    "@aotter/mantle-auth": "0.1.4",
-    "@aotter/mantle-vercel": "0.1.4",
-    "@aotter/mantle-bun": "0.1.4",
-    "@aotter/mantle-web": "0.1.4",
-    "@aotter/mantle-cloudflare": "0.1.4",
-    "@aotter/mantle-admin": "0.1.4"
+    "@aotter/mantle-admin": "0.1.5-alpha.1",
+    "@aotter/mantle-admin-ui": "0.1.5-alpha.1",
+    "@aotter/mantle-auth": "0.1.5-alpha.1",
+    "@aotter/mantle-bun": "0.1.5-alpha.1",
+    "@aotter/mantle-cloudflare": "0.1.5-alpha.1",
+    "@aotter/mantle-vercel": "0.1.5-alpha.1",
+    "@aotter/mantle-web": "0.1.5-alpha.1"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -144,13 +145,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.4",
-    "@aotter/mantle-admin-ui": "0.1.4",
-    "@aotter/mantle-auth": "0.1.4",
-    "@aotter/mantle-bun": "0.1.4",
-    "@aotter/mantle-cloudflare": "0.1.4",
-    "@aotter/mantle-vercel": "0.1.4",
-    "@aotter/mantle-web": "0.1.4"
+    "@aotter/mantle-admin": "0.1.5-alpha.1",
+    "@aotter/mantle-admin-ui": "0.1.5-alpha.1",
+    "@aotter/mantle-auth": "0.1.5-alpha.1",
+    "@aotter/mantle-bun": "0.1.5-alpha.1",
+    "@aotter/mantle-cloudflare": "0.1.5-alpha.1",
+    "@aotter/mantle-vercel": "0.1.5-alpha.1",
+    "@aotter/mantle-web": "0.1.5-alpha.1"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -5,6 +5,7 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 | 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. |
@@ -26,6 +27,7 @@ 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 | — |
@@ -61,7 +63,7 @@ contracts.
 
 `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 six skills live in `docs/skills/` and ship with the npm package.
+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:

package/skills/develop/SKILL.md

@@ -57,9 +57,11 @@ 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.
+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
 
@@ -155,7 +157,10 @@ teaching the project Mantle internals.
 
 ## Auth Composition
 
-Admin is opt-in. A project without `@aotter/mantle-admin-ui` is complete.
+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
@@ -164,8 +169,11 @@ 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
+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.