@aotter/mantle 0.1.2-rc.1 → 0.1.3-alpha.1

package/docs/release-process.md

@@ -1,9 +1,9 @@
 # Release process
 
-First stable targets 0.1.2 (#826). The last legacy Landing/Starter release is
-0.1.0-alpha.17. Its immutable artifacts and repositories remain available;
-recover that version with its tagged controller/docs. New releases have no
-Starter/Landing checkout, tag, dispatch, credential or deployment dependency.
+How a version reaches npm. What each shipped stable contains is
+[Releases](handbook/releases/index.md); this document is the procedure only.
+A release has no Starter/Landing checkout, tag, dispatch, credential or
+deployment dependency.
 
 ## Authority and state transitions
 
@@ -56,13 +56,13 @@ is introduced. The runnable release-order check guards these transitions.
   `develop`, anything else means `main`. It refuses a commit that is not that
   branch's tip or not the merge commit of exactly one PR into that branch.
   `scripts/release-tag-order.mjs` rejects any other prerelease identifier.
-- `develop` stays the default integration branch. `main` changes only through
-  promotion PRs and hotfix PRs (below); it is never pushed directly, rebased
-  or force-updated. Both branches share one ruleset: PR, one approval,
-  resolved threads and a current-base `Typecheck + tests` check.
-- Stable publishes latest. Final 0.1.0 alphas only advance alpha, preserving
-  existing legacy latest. Historic 0.0 alpha behavior remains recoverable.
-  A prerelease channel keeps its last version when a later stable publishes.
+- `develop` is where every change integrates first, so it is the base for all
+  work despite `main` being the repository's default branch on GitHub. `main`
+  changes only through promotion PRs and hotfix PRs (below); it is never pushed
+  directly, rebased or force-updated. Both branches share one ruleset: PR, one
+  approval, resolved threads and a current-base `Typecheck + tests` check.
+- Stable is the only release that moves `latest`. A prerelease channel keeps
+  its last version when a later stable publishes.
 
 ## Prepare and run
 
@@ -83,7 +83,8 @@ is introduced. The runnable release-order check guards these transitions.
    ```
 
 3. Review API compatibility and migration instructions for actual consumers.
-   Frozen legacy consumers stay on alpha.17; do not make them follow new Core.
+   Frozen legacy consumers stay on their pinned version; do not make them
+   follow new Core.
 4. Run `pnpm check`, including exact packed Worker, optional products, Bun,
    Vercel, skills, release invariants, types and tests. Inspect the umbrella
    docs/skills payload: no workspace dependencies, secrets or local state.
@@ -93,7 +94,7 @@ is introduced. The runnable release-order check guards these transitions.
    stable, continue with the promotion below. The controller refuses an
    untagged source that is no longer the expected branch tip.
 
-The ten public packages remain in dependency order:
+The eleven public packages remain in dependency order:
 
 1. @aotter/mantle-spec
 2. @aotter/mantle-admin-ui
@@ -101,10 +102,11 @@ The ten public packages remain in dependency order:
 4. @aotter/mantle-indexeddb
 5. @aotter/mantle-web
 6. @aotter/mantle-admin
-7. @aotter/mantle-bun
-8. @aotter/mantle-vercel
-9. @aotter/mantle-cloudflare
-10. @aotter/mantle
+7. @aotter/mantle-auth
+8. @aotter/mantle-bun
+9. @aotter/mantle-vercel
+10. @aotter/mantle-cloudflare
+11. @aotter/mantle
 
 ## Promote to main (beta, RC, stable)
 
@@ -112,9 +114,9 @@ Every non-alpha release is the version PR above, one promotion PR and one
 dispatch. The version PR still merges into `develop`, so `develop` always
 contains what `main` publishes and promotions never conflict.
 
-1. Stable only: the release-gate issue (#826 for 0.1.2) records owner
-   acceptance. Every gate item passes with linked evidence or is explicitly
-   deferred there, and no `release-gate` issue stays open against the version.
+1. Stable only: the version's release-gate issue records owner acceptance.
+   Every gate item passes with linked evidence or is explicitly deferred
+   there, and no `release-gate` issue stays open against the version.
    Beta and RC need the gate defined, not passed.
 2. Merge the version PR into `develop` with a merge commit; note its SHA.
 3. Pin the promotion head at that SHA so later `develop` merges cannot ride
@@ -147,18 +149,20 @@ the next promotion. Branch from `main`, include the version bump, PR into
 and resolve version files in favour of `develop`. Until that lands, the next
 promotion conflicts on the version files.
 
-First stable (0.1.2) specifics: `latest` moves from 0.1.0-alpha.16, the last
-`latest` the frozen legacy consumers saw, to 0.1.2. GitHub generates notes
-from the previous release (v0.1.2-alpha.6); to cover the whole 0.1.2 line,
-regenerate from v0.1.0-alpha.17 and edit the release body after the run. The
-body is not an immutable artifact; the tag and packages are.
+GitHub generates notes from the immediately previous tag, which for a stable
+is usually its own last RC. To cover the whole line instead, regenerate from
+the previous stable and edit the release body after the run. The body is not
+an immutable artifact; the tag and packages are.
 
 ```sh
 gh api repos/aotter/mantle/releases/generate-notes \
-  -f tag_name=v0.1.2 -f previous_tag_name=v0.1.0-alpha.17 --jq .body > notes.md
-gh release edit v0.1.2 --notes-file notes.md
+  -f tag_name=v<version> -f previous_tag_name=v<previous stable> --jq .body > notes.md
+gh release edit v<version> --notes-file notes.md
 ```
 
+Add the version's entry to [Releases](handbook/releases/index.md) in the same
+pass, so the handbook and the GitHub release describe the same thing.
+
 After publication, move docs/examples that were pinned to a packed checkout
 back to registry installation with an updated lockfile, and close the gate
 issue with the run link and completion evidence.
@@ -170,12 +174,13 @@ tag/release and mirrors GitHub Packages. No cross-repository fanout token is
 needed. Before tagging, verify credentials and new-version absence on both
 registries. Existing artifacts on retry must have matching integrity.
 
-Completion requires the Core tag SHA, all ten npmjs/GPR packages, exact
+Completion requires the Core tag SHA, all eleven npmjs/GPR packages, exact
 integrity, no workspace dependencies, a passing public-registry Worker gate,
 correct channel tags and the GitHub release. Retain run links and gate evidence.
-This does not prove stable production soak or upgrade safety; #826 owns those
-acceptance requirements. A first-stable agent acceptance uses only the
-version-matched authoring instructions, not an SDK checkout or generated site.
+This does not prove stable production soak or upgrade safety; the version's
+release-gate issue owns those acceptance requirements. An agent acceptance run
+uses only the version-matched authoring instructions, not an SDK checkout or
+generated site.
 
 ## Recovery
 

package/docs/sealed-pipeline-ownership.md

@@ -97,5 +97,5 @@ consumers; they do not duplicate the suite under new names.
 
 Issue #674 leaves `CONTRIBUTING.md` plus accepted ADRs as the contributor
 authority. `AGENTS.md`, `CLAUDE.md`, and the Claude release-skill entry are
-small routers; `.agent/skills/mantle-release/SKILL.md` is the only maintainer
+small routers; `.agents/skills/mantle-release/SKILL.md` is the only maintainer
 release procedure. Shipped `skills/*` remain separate consumer artifacts.

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

@@ -6,9 +6,8 @@ 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.0-alpha.16`. Its public APIs and peer requirements are
-prerelease contracts: pin the package, record the tested version, and rerun
-compatibility checks when upgrading.
+This recipe targets `0.1.3-alpha.1`. Pin the package, record the tested version, and
+rerun compatibility checks when upgrading.
 
 ## What stays with the host
 
@@ -51,7 +50,7 @@ validation semantics. Do not hand-maintain a second field list for the graph.
 Install the exact Spec package and its supported peer, without Runtime:
 
 ```sh
-npm install --save-exact @aotter/mantle-spec@0.1.0-alpha.16 zod@4.5.4
+npm install --save-exact @aotter/mantle-spec zod@4.5.4
 ```
 
 The [synthetic fixture](../packages/mantle-spec/test/fixtures/spec-only-host.yaml)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.2-rc.1",
-  "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
+  "version": "0.1.3-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/",
   "repository": {
@@ -51,6 +51,10 @@
       "types": "./dist/admin.d.ts",
       "import": "./dist/admin.js"
     },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js"
+    },
     "./bun": {
       "types": "./dist/bun.d.ts",
       "import": "./dist/bun.js"
@@ -79,8 +83,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.2-rc.1",
-    "@aotter/mantle-spec": "0.1.2-rc.1"
+    "@aotter/mantle-runtime": "0.1.3-alpha.1",
+    "@aotter/mantle-spec": "0.1.3-alpha.1"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -88,12 +92,13 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.2-rc.1",
-    "@aotter/mantle-bun": "0.1.2-rc.1",
-    "@aotter/mantle-cloudflare": "0.1.2-rc.1",
-    "@aotter/mantle-admin-ui": "0.1.2-rc.1",
-    "@aotter/mantle-vercel": "0.1.2-rc.1",
-    "@aotter/mantle-web": "0.1.2-rc.1"
+    "@aotter/mantle-admin": "0.1.3-alpha.1",
+    "@aotter/mantle-auth": "0.1.3-alpha.1",
+    "@aotter/mantle-vercel": "0.1.3-alpha.1",
+    "@aotter/mantle-bun": "0.1.3-alpha.1",
+    "@aotter/mantle-web": "0.1.3-alpha.1",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.1",
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.1"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -102,6 +107,9 @@
     "@aotter/mantle-admin-ui": {
       "optional": true
     },
+    "@aotter/mantle-auth": {
+      "optional": true
+    },
     "@aotter/mantle-bun": {
       "optional": true
     },
@@ -136,12 +144,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.2-rc.1",
-    "@aotter/mantle-cloudflare": "0.1.2-rc.1",
-    "@aotter/mantle-admin-ui": "0.1.2-rc.1",
-    "@aotter/mantle-bun": "0.1.2-rc.1",
-    "@aotter/mantle-vercel": "0.1.2-rc.1",
-    "@aotter/mantle-web": "0.1.2-rc.1"
+    "@aotter/mantle-admin": "0.1.3-alpha.1",
+    "@aotter/mantle-bun": "0.1.3-alpha.1",
+    "@aotter/mantle-auth": "0.1.3-alpha.1",
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.1",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.1",
+    "@aotter/mantle-vercel": "0.1.3-alpha.1",
+    "@aotter/mantle-web": "0.1.3-alpha.1"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -6,11 +6,11 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 |---|---|
 | [`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 starters and adapters. |
-| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project context but does not depend on starter-owned skill semantics. |
+| [`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 create a local Mantle site by direct authoring or continue an existing local / landing-generated project. |
-| [`provision`](provision/SKILL.md) | User wants a local or landing-generated project shipped to Cloudflare with production auth and operator handoff. |
+| [`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. |
 
 The skills target Mantle's v0.1 grammar. The installed package version, not
 duplicated skill prose, selects the exact runtime and embedded docs.
@@ -27,9 +27,9 @@ enforces the columns below.
 |---|---|---|---|---|---|
 | `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 generated project | repo-owned theme and UI contracts | — | 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 site, or opening an existing generated one | 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. |
+| `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. |
 
@@ -46,20 +46,42 @@ 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 generated project, and a skill that
+skill `mantle skills` should place in a consumer project, and a skill that
 withholds `project` must say why. `scripts/check-skills.mjs` holds that
 declaration and the audit table below to each other.
 
 Run `mantle skills` to project the installed package's skills into a project;
 use `mantle skills --check` to fail closed on drift. The installed package and
 `node_modules/@aotter/mantle/docs/` are the single version-matched authority.
-Starter launch files and plugin recipes are project context, not competing
+Application files and plugin recipes are project context, not competing
 contracts.
 
 ## Source-repository marketplace install
 
-The source repository is also an agent plugin bundle. These manifests are not
-duplicated into the npm package:
+Cold start is the pinned install skill. Other marketplace hosts are pointers
+to the same pin:
+
+```sh
+npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+```
+
+```bash
+# Claude Code — two separate prompts
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin install mantle@mantle
+
+# Codex
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.1
+codex plugin add mantle@mantle
+```
+
+Then follow the install skill to the CLI and handbook. Do not use an untagged
+`aotter/mantle` marketplace add as the official entry. After packages are
+pinned, `mantle skills` projects the installed package's own skills into the
+project, and `mantle skills --check` fails on drift.
+
+Cursor and GitHub Copilot read their manifests from the repository directly.
+These manifests are not duplicated into the npm package:
 
 - Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
 - Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
@@ -75,7 +97,7 @@ 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"). No `/skill install` slash command is required — point the agent at a version tag 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@v0.1.3-alpha.1 --skill install`. Point the agent at tag `v0.1.3-alpha.1` or pass the version-matched markdown content directly.
 
 ## Conventions
 

package/skills/install/SKILL.md

@@ -24,9 +24,7 @@ turn `generate` into implicit scaffolding.
    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. Follow
-   its SDK availability instructions; while support is unreleased, use its
-   packed-checkout workflow rather than an older registry package.
+   `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.
@@ -42,12 +40,30 @@ turn `generate` into implicit scaffolding.
      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 `host-chatgpt-sites/`, not the
-     email-OTP Worker example. 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.
+   - 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.
-   - Grammar — `docs/examples/README.md`; copy `builtin-*` Manifests only.
+   - 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
@@ -85,15 +101,15 @@ 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 legacy alpha.17 projects, retain their pinned behavior until an explicit
-upgrade is requested; read `docs/migration-0.1.2.md` before upgrading. 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.
+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, follow the installed provision skill and the
-observed host configuration. Legacy Landing remains an alpha.17 product; it
+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,

package/skills/plugin/SKILL.md

@@ -10,8 +10,8 @@ metadata:
 
 # Mantle Plugin
 
-Mantle plugins are Core SDK capability packages. They are not starter overlays
-and they are not provider provisioning scripts.
+Mantle plugins are Core SDK capability packages. They are not application
+scaffolds (retired in ADR-0021) and they are not provider provisioning scripts.
 
 A plugin may contribute:
 
@@ -82,8 +82,8 @@ Suggested ledger paths:
 .mantle/plugins.lock.json
 ```
 
-Keep starter launch state separate from plugin state. `.mantle/features.json`
-is launch/starter context, not the Core plugin ledger.
+Keep optional legacy launch files such as `.mantle/features.json` separate from
+plugin state. They are not the Core plugin ledger.
 
 ## Update
 
@@ -114,7 +114,7 @@ Then verify the plugin's declared surfaces:
 
 ## Don't
 
-- Don't treat a starter archetype as a plugin.
+- Don't treat an application template as a plugin.
 - Don't assume Cloudflare; inspect the active adapter and capability ports.
-- Don't create a second skill namespace for starter-specific plugins.
+- Don't create a second skill namespace for host-specific plugins.
 - Don't commit secrets. Provider secrets stay in the platform secret store.

package/skills/provision/SKILL.md

@@ -13,16 +13,22 @@ metadata:
 
 Local cold start deliberately stops before this skill. Provision only after the
 user asks to create remote resources or ship production. This flow is for
-consumer-owned Cloudflare Workers. For a ChatGPT Site, use the installed
-`docs/handbook/sites/index.md` integration guide and the Sites host's
-publish workflow; do not run `wrangler deploy` or require R2 S3 credentials
-merely because Sites exposes an R2 binding.
+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
+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
+run `wrangler deploy` or require R2 S3 credentials merely because Sites exposes
+an R2 binding.
 
 ## Source of Truth
 
 1. Read the actual provider config (`wrangler.jsonc` or `wrangler.toml`),
    application entry and git remotes. Read legacy `.mantle/launch-state.json`
-   and `.mantle/handoff.md` only when present; do not create them as prerequisites.
+   and `.mantle/handoff.md` only when present; they are optional leftovers from
+   Landing and must not be created as prerequisites for a new app.
 2. Read installed `@aotter/mantle*` versions from `package.json`.
 3. Use matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 4. Never infer provider authority from launch state. Confirm the active GitHub
@@ -54,8 +60,9 @@ account, prefer an available connector, or use `pnpm exec wrangler login` with
 the user's agreement, then run `pnpm deploy`.
 
 Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
-commit and push non-secret changes. Reuse any repo or Worker already created
-by landing. Workers Builds is optional after a direct deploy.
+commit and push non-secret changes. Reuse any repo or Worker already created.
+Do not recreate Landing artifacts for a new direct-authored app. Workers Builds
+is optional after a direct deploy.
 
 When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
 provider's OAuth callback together, then redeploy. Do not patch `site_config`
@@ -65,15 +72,17 @@ directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
 
 - **Self-hosted email OTP:** use the application's production transactional-email sender. Replace `ConsoleEmailSender`; never deploy it.
 - **Self-hosted GitHub OAuth — free fallback:** use when the application has no email provider. Configure the owner's per-site GitHub OAuth App and Worker secrets using the steps below.
-- **Mantle hosted auth — paid:** use only when the landing handoff records a
-  hosted allocation and client configuration. Mantle Platform operates the
-  identity provider; do not ask the user for a per-site GitHub OAuth App.
+- **Mantle hosted auth — paid, legacy/optional:** use only when a **legacy
+  Landing handoff** already records a hosted allocation and client
+  configuration. New direct-authored apps do not get this from Core. Mantle
+  Platform operates the identity provider; do not ask the user for a per-site
+  GitHub OAuth App.
 
 Configure only the selected mode. Core deliberately rejects partial or mixed
 hosted/self-managed bindings with `503 setup_incomplete`.
 
-Do not claim that hosted auth can attach to an arbitrary local repo unless the
-current Mantle landing flow explicitly supplies that handoff.
+Do not claim that hosted auth can attach to an arbitrary local repo unless a
+legacy Landing handoff already supplies that configuration.
 
 For the exact boundary, read
 `node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
@@ -129,10 +138,13 @@ git push
 pnpm deploy
 ```
 
-## Hosted Auth
+## Hosted Auth (legacy Landing)
 
-Follow the landing handoff and generated client configuration. Hosted
-configuration remains in landing-managed Cloudflare Worker bindings. Verify:
+Skip this section unless a legacy Landing handoff is already present. New
+direct-authored apps use self-hosted email OTP or GitHub OAuth above.
+
+Follow that handoff and its client configuration. Hosted configuration remains
+in landing-managed Cloudflare Worker bindings. Verify:
 
 - `MANTLE_AUTH_MODE = "hosted"`;
 - `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;

package/skills/update/SKILL.md

@@ -17,9 +17,10 @@ skill remains the version-matched upgrade workflow, not a replacement CLI.
 1. Inspect git status, package.json, lockfile, actual project scripts and
    installed versions. Preserve unrelated local changes. Read plugin locks
    and legacy `.mantle` metadata if present; they are context, not required.
-2. Select an explicit target release and read its migration notes, including
-   `docs/migration-0.1.2.md` when leaving alpha.17. Do not resolve new Starter
-   refs or compare the project to a baseline template.
+2. Select an explicit target release and read its entry in
+   `docs/handbook/releases/index.md` plus that version's GitHub release notes.
+   Do not resolve new Starter refs or compare the project to a baseline
+   template.
 3. Update only selected `@aotter/mantle*` dependencies to the same exact target
    version, preserving dependency sections. Use the package manager to update
    the lockfile; inspect the dependency diff and required peer changes.