@aotter/mantle 0.1.3 → 0.1.5-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.3",
+  "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.3",
-    "@aotter/mantle-spec": "0.1.3"
+    "@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": "0.1.3",
-    "@aotter/mantle-admin-ui": "0.1.3",
-    "@aotter/mantle-bun": "0.1.3",
-    "@aotter/mantle-auth": "0.1.3",
-    "@aotter/mantle-web": "0.1.3",
-    "@aotter/mantle-cloudflare": "0.1.3",
-    "@aotter/mantle-vercel": "0.1.3"
+    "@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": {
@@ -139,18 +140,18 @@
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
     "better-auth": "1.7.2",
-    "hono": "^4.13.3",
+    "hono": "^4.13.7",
     "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin-ui": "0.1.3",
-    "@aotter/mantle-admin": "0.1.3",
-    "@aotter/mantle-auth": "0.1.3",
-    "@aotter/mantle-bun": "0.1.3",
-    "@aotter/mantle-cloudflare": "0.1.3",
-    "@aotter/mantle-vercel": "0.1.3",
-    "@aotter/mantle-web": "0.1.3"
+    "@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

@@ -4,13 +4,14 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 
 | Skill | When to invoke |
 |---|---|
-| [`develop`](develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
-| [`media-gc`](media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
-| [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
-| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
-| [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
-| [`install`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
-| [`provision`](provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
+| [`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.
@@ -25,13 +26,14 @@ 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, plugin | — |
-| `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, plugin | — |
-| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project, plugin | — |
-| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project, plugin | — |
-| `install` | 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 | plugin | 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 | plugin | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
+| `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:
 
@@ -47,7 +49,8 @@ Deliberately monolithic:
 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. `scripts/check-skills.mjs` holds 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;
@@ -58,11 +61,15 @@ contracts.
 
 ## Source-repository marketplace install
 
-Cold start is the install skill. Other marketplace hosts are pointers
-to the same entry:
+`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 --skill install
+npx skills add aotter/mantle
 ```
 
 ```bash
@@ -76,7 +83,7 @@ codex plugin add mantle@mantle
 ```
 
 Read the path printed by the installer (for project-local Codex,
-`.agents/skills/install/SKILL.md`). Only the selected brief is installed, not
+`.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
@@ -100,13 +107,13 @@ 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 --skill install`. Point the agent at the repository or pass the version-matched markdown content directly.
+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 folder-matching `name`, trigger-complete
+- **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.

package/skills/develop/SKILL.md

@@ -3,9 +3,9 @@ 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: skills/develop/SKILL.md
+  sourcePath: docs/skills/develop/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Develop
@@ -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/skills/install/SKILL.md

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

@@ -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/skills/media-gc/SKILL.md

@@ -3,9 +3,9 @@ name: media-gc
 description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/media-gc/SKILL.md
+  sourcePath: docs/skills/media-gc/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: plugin
+  projection: package
   projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
 ---
 

package/skills/plugin/SKILL.md

@@ -3,9 +3,9 @@ name: plugin
 description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/plugin/SKILL.md
+  sourcePath: docs/skills/plugin/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Plugin

package/skills/provision/SKILL.md

@@ -3,9 +3,9 @@ name: provision
 description: Ship a Mantle project through its selected host, routing ChatGPT Sites to its integration guide and conventional Cloudflare Workers to production auth and provisioning.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/provision/SKILL.md
+  sourcePath: docs/skills/provision/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: plugin
+  projection: package
   projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
 ---
 
@@ -16,7 +16,7 @@ user asks to create remote resources or ship production. This flow is for
 consumer-owned Cloudflare Workers. New direct-authored apps do not need Landing
 artifacts (`.mantle/launch-state.json`, `.mantle/handoff.md`, or a hosted-auth
 allocation). Treat any Landing handoff as **legacy/optional**. For a ChatGPT
-Site, use the installed `docs/handbook/sites/index.md` integration guide and
+Site, use the installed `docs/handbook/chatgpt-sites/index.md` integration guide and
 the "Publish with Sites" steps in `docs/examples/host-chatgpt-sites/README.md`:
 request D1 and R2 on the Site, set `PUBLIC_ORIGIN` and `OWNER_EMAIL` in Sites
 settings, review the migration, then save and deploy a Sites version. Do not

package/skills/theme/SKILL.md

@@ -3,9 +3,9 @@ name: theme
 description: Apply brand and visual direction in a Mantle application using its repo-owned theme and UI contracts.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/theme/SKILL.md
+  sourcePath: docs/skills/theme/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Theme