@aotter/mantle 0.1.2 → 0.1.3-alpha.2

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

@@ -1,227 +1,38 @@
 ---
-description: "Open local Admin in one shot: generate the prebuilt SPA, bind ASSETS, sign in with email OTP from wrangler logs, land in the Dev UI."
+description: "Open local Admin in one shot: follow the official OTP example, bind ASSETS, sign in with email OTP from wrangler logs, land in the Dev UI."
 ---
 # Quickstart: local Admin
 
-This page reproduces Core's local Admin OTP reference as a from-scratch walkthrough. Admin is **opt-in**: use it when humans need a Dev UI. A complete Mantle service does not require this surface. Install every `@aotter/mantle*` package from the `latest` dist-tag; see [Versions](../reference/surface.md#versions).
+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).
 
-The default embed path — Spec + Worker without Admin — is [Quickstart: a minimal Worker](./quickstart-worker.md).
+The procedural source of truth is the official example:
 
-## Prerequisites
+**[`docs/examples/host-local-admin-otp/README.md`](../../examples/host-local-admin-otp/README.md)**
 
-- Node.js 22 or newer.
-- pnpm 9 or newer. The reference is tested with pnpm.
-- `wrangler` is installed as a project devDependency below. No Cloudflare account, D1 database id or production secret is needed for the local loop.
-
-An agent interviews the human for one value before writing files: the bootstrap owner email. The example uses `owner@example.com`.
-
-## 1. `package.json`
-
-Install every `@aotter/mantle*` package from the `latest` dist-tag. Admin needs both `@aotter/mantle-admin` and `@aotter/mantle-admin-ui` plus the Cloudflare adapter peers.
-
-```json
-{
-  "name": "mantle-local-admin-otp",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "generate": "mantle generate",
-    "validate": "mantle validate",
-    "typecheck": "tsc --noEmit",
-    "predev": "node ensure-dev-vars.mjs",
-    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787"
-  },
-  "dependencies": {
-    "@aotter/mantle": "latest",
-    "@aotter/mantle-admin": "latest",
-    "@aotter/mantle-admin-ui": "latest",
-    "@aotter/mantle-cloudflare": "latest",
-    "better-auth": "1.7.2",
-    "hono": "^4.13.3",
-    "zod": "^4.5.4",
-    "aws4fetch": "^1.0.20"
-  },
-  "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
-    "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
-  },
-  "packageManager": "pnpm@9.15.0"
-}
-```
-
-Add a `tsconfig.json` that includes the generated module:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "skipLibCheck": true,
-    "types": ["@cloudflare/workers-types"]
-  },
-  "include": ["src/**/*.ts", ".mantle/generated/**/*.ts"]
-}
-```
-
-`ensure-dev-vars.mjs` copies the example vars on first `pnpm dev`:
-
-```js
-import { copyFileSync, existsSync } from "node:fs";
-if (!existsSync(".dev.vars")) copyFileSync(".dev.vars.example", ".dev.vars");
-```
-
-## 2. `.dev.vars.example`
-
-```sh
-PUBLIC_ORIGIN=http://127.0.0.1:8787
-BETTER_AUTH_SECRET=local-admin-otp-dev-secret-do-not-use-in-prod
-ADMIN_EMAIL=owner@example.com
-```
-
-Copy it to `.dev.vars` (the `predev` script does this). Never commit `.dev.vars`. `pnpm dev` binds `127.0.0.1:8787` so wrangler's Ready-on origin matches this `PUBLIC_ORIGIN`. A mismatch makes Better Auth reject OTP with `INVALID_ORIGIN`.
-
-## 3. `manifests/site.yaml`
-
-One publishing Schema and one public View. `mantle generate` never invents a Schema; this notes model is example business data. `cache` is valid in this snapshot's grammar.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: notes
-spec:
-  title: Notes
-  schema:
-    type: object
-    required: [title]
-    properties:
-      title: { type: string }
-  lifecycle: publishing
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: published-notes
-spec:
-  surface: public
-  from: notes
-  cache: { sharedMaxAge: 3600 }
-  fields: [id, title]
-  filter:
-    eq: { field: status, value: published }
-  limit: 20
-```
-
-Use the docs that ship with the pinned version. A newer handbook page is not a contract for an older install.
-
-## 4. `src/index.ts`
-
-Replace conventional GitHub Auth construction with local email OTP. Core still owns `/admin` and `/api/auth/*`.
-
-```ts
-import {
-  ConsoleEmailSender,
-  createAuth,
-  createMantleWorker,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-export interface Env extends MantleCloudflareEnv {
-  readonly ASSETS: Fetcher;
-  readonly BETTER_AUTH_SECRET: string;
-  readonly ADMIN_EMAIL: string;
-}
-
-const sender = new ConsoleEmailSender();
-
-export default createMantleWorker<Env>({
-  plan,
-  cacheScope: "local-admin-otp",
-  siteDefaults: (env) => ({
-    brand: "Local Admin",
-    title: "Local Admin",
-    origin: env.PUBLIC_ORIGIN?.replace(/\/+$/, "") ?? "http://127.0.0.1:8787",
-  }),
-  auth: (env) => {
-    const origin = env.PUBLIC_ORIGIN?.replace(/\/+$/, "") ?? "http://127.0.0.1:8787";
-    return createAuth({
-      database: env.DB,
-      baseURL: origin,
-      secret: env.BETTER_AUTH_SECRET,
-      methods: [{ kind: "email-otp", sender }],
-      bootstrapOwner: { match: "email", value: env.ADMIN_EMAIL },
-      oauthProvider: {
-        loginPage: "/admin/sign-in",
-        consentPage: "/oauth/consent",
-        scopes: ["mcp"],
-        mcpResource: `${origin}/mcp`,
-      },
-    });
-  },
-});
-```
-
-`ConsoleEmailSender` writes the OTP to wrangler logs. It is the local human path. Do not wire it in production.
-
-## 5. `wrangler.jsonc`
-
-Admin requires Static Assets. This is not optional.
-
-```jsonc
-{
-  "$schema": "node_modules/wrangler/config-schema.json",
-  "name": "mantle-local-admin-otp",
-  "main": "src/index.ts",
-  "compatibility_date": "2026-09-08",
-  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
-  "assets": { "directory": "./public", "binding": "ASSETS" },
-  "d1_databases": [
-    { "binding": "DB", "database_name": "mantle-local-admin-otp" }
-  ]
-}
-```
-
-Keep a `public/` directory (empty is fine). `generate` writes `public/_mantle/admin/` into it. Do not put `/_mantle` in `run_worker_first`: those files must be served by the assets layer. A Worker-first catch-all without asset fallthrough is the white-screen class of bug — `/admin` returns SPA HTML `200` while `/_mantle/admin/assets/*` is `404`.
-
-## 6. Install, generate, run
+Copy that directory outside the SDK checkout (or author the same files from
+it). Interview the human for one value before writing files: the bootstrap
+owner email. The example uses `owner@example.com`. Then:
 
 ```sh
 pnpm install && pnpm generate && pnpm dev
 ```
 
-`mantle generate` writes `.mantle/generated/mantle.ts` and syncs the **prebuilt** Admin SPA from `@aotter/mantle-admin-ui` into `public/_mantle/admin/`. Do not run Vite or otherwise build a frontend unless you are developing `admin-ui` itself.
-
-`pnpm dev` binds `127.0.0.1:8787`. Wrangler prints `Ready on http://127.0.0.1:8787`, the same origin as `PUBLIC_ORIGIN`. Open that Ready-on URL. Browsing `http://localhost:8787` still serves HTML, but the OTP Origin header mismatches `PUBLIC_ORIGIN` and Better Auth returns `INVALID_ORIGIN`.
-
-## 7. Sign in
-
-```sh
-curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8787/admin/sign-in
-curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8787/_mantle/admin/index.html
-```
-
-Both are `200`. Open `/admin/sign-in`, submit the bootstrap owner email, then read the wrangler log:
-
-```text
-[ConsoleEmailSender] auth.email-otp.sign-in → owner@example.com (en)
-  subject: Your Mantle sign-in code: 123456
-```
-
-Enter the code. The first matching sign-in is promoted to `owner` and the Admin shell loads.
-
-If the page is blank, fetch an asset URL from the HTML. A `404` there means `ASSETS` is missing or `run_worker_first` swallowed `/_mantle`. That is not a missing `vite build`.
+Open the wrangler Ready-on URL (`http://127.0.0.1:8787/admin/sign-in`), submit
+the owner email, and read the OTP from wrangler logs. `mantle generate` syncs
+the prebuilt Admin SPA; do not Vite-build Admin.
 
-## What `mantle generate` wrote
+Traps (documented on the example):
 
-- `.mantle/generated/mantle.ts` — the sealed `plan`, generated types, `createMantle` and `bindMantle`.
-- `public/_mantle/admin/` — the prebuilt Admin SPA. Required for `/admin`.
+- Prefer `127.0.0.1` over `localhost` (`INVALID_ORIGIN`).
+- `pnpm check` / smoke rewrites `.dev.vars` to a smoke-only port — restore it
+  from `.dev.vars.example` before `pnpm dev`.
 
-`generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. The reference keeps `.mantle/`, `.agents/`, `.claude/` and `public/_mantle/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
+Install every `@aotter/mantle*` package from the `latest` dist-tag; 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`.
 
 ## Next steps
 

package/docs/labels.md

@@ -29,12 +29,12 @@ For package README or package-local docs changes, prefer the package area label
 | `area:runtime` | `packages/mantle-runtime` behavior, ports, use cases, dispatcher, and MCP runtime. |
 | `area:spec` | `packages/mantle-spec`, manifest parsing, validation, diagnostics, CLI, spec types. |
 | `area:cf` | `packages/adapters/cloudflare`, Workers adapter, D1/KV/ASSETS wiring, Cloudflare deploy behavior. |
-| `area:starters` | Legacy `aotter/mantle-starters` source and retirement migration. |
 | `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
 | `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
 | `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |
 | `area:adapter` | Adapter boundary work spanning Cloudflare or future adapters. |
 | `area:ci` | GitHub Actions, dependency automation, and repository checks. |
+| `area:starters` | **Legacy only.** Retired `aotter/mantle-starters` source and migration notes. Do not use for new Core work. |
 
 ## Release and review gates
 
@@ -45,7 +45,7 @@ For package README or package-local docs changes, prefer the package area label
 | `breaking-change` | Semver-relevant breaking change. | Generated release notes must call it out. | The change is redesigned to be non-breaking. |
 | `skip-release-notes` | Release bookkeeping with no user-facing change. | Excluded from generated GitHub Release notes. | The PR contains a user-facing change. |
 | `needs-adr` | Architecture, trust boundary, package boundary, or long-lived decision needs an ADR or ADR-lite proposal. | Do not merge implementation until the decision is captured. | ADR/proposal lands or maintainer confirms an existing ADR covers it. |
-| `needs-grammar-revise` | Manifest grammar or closed-enum change. | Requires grammar-revise round before code/types/starters change. | Grammar decision lands or the change no longer affects grammar. |
+| `needs-grammar-revise` | Manifest grammar or closed-enum change. | Requires grammar-revise round before code/types change. | Grammar decision lands or the change no longer affects grammar. |
 | `needs-discussion` | Not converged enough for implementation. | Do not start coding from this issue. | Closing criteria are met and scope is concrete. |
 
 ## Creating missing labels
@@ -56,12 +56,12 @@ Use these commands from a checked-out repo:
 gh label create "area:runtime" --description "Runtime package, ports, use cases, dispatcher, render, MCP runtime" --color "1d76db"
 gh label create "area:spec" --description "Spec package, manifest parsing, validation, diagnostics, CLI, types" --color "1d76db"
 gh label create "area:cf" --description "Cloudflare Workers adapter and bindings" --color "1d76db"
-gh label create "area:starters" --description "Starter templates and starter validation" --color "1d76db"
 gh label create "area:skills" --description "Agent Skills and install/extend/provision workflows" --color "1d76db"
 gh label create "area:admin-ui" --description "React admin UI" --color "1d76db"
 gh label create "area:docs" --description "Documentation and governance" --color "1d76db"
 gh label create "area:adapter" --description "Adapter boundary and future adapter work" --color "1d76db"
 gh label create "area:ci" --description "CI, dependency automation, and repository checks" --color "1d76db"
+gh label create "area:starters" --description "Legacy only: retired mantle-starters source and migration" --color "cfd3d7"
 gh label create "breaking-change" --description "Semver-relevant breaking change" --color "b60205"
 gh label create "skip-release-notes" --description "Release bookkeeping only; omit from generated GitHub notes" --color "ededed"
 gh label create "needs-adr" --description "Requires an ADR or ADR-lite decision before merge" --color "d93f0b"

package/docs/migration-0.1.2.md

@@ -1,129 +1,13 @@
-# Leaving the legacy alpha.17 launch line
+# Upgrading to 0.1.2
 
-0.1.0-alpha.17 remains immutable and is the final version for existing Landing
-and Starters. Those repositories/tags/bundle URLs remain available. Staying on
-that version requires no migration. No stable 0.1.0 release is planned.
+0.1.2 is the first stable release and the first public one. There is no earlier
+stable to upgrade from and no migration to perform.
 
-The new line removes `mantle create`, the Starter bundle `mantle update`
-command, and `@aotter/mantle/provision`. There are no aliases or replacement
-scaffold commands. `generate`, `validate`, `emit-openapi` and `skills` remain.
-Generation and runtime Web rendering retain their existing responsibilities.
+What it contains, what it requires and what it does not yet cover is in
+[Releases](handbook/releases/index.md).
 
-To upgrade an existing application:
-
-1. Read its installed version, lockfile, entry, scripts and provider bindings;
-   keep unrelated work safe in the normal git workflow.
-2. Pin the selected SDK packages to the intended exact new release and update
-   the lockfile through the package manager. Review required peer upgrades.
-3. Remove scripts invoking the retired scaffolder/bundle updater. If application
-   code imports the provision renderer, remain on alpha.17 until that host's
-   provisioning design is migrated explicitly; do not replace it with a
-   handwritten remote-code loader.
-4. Retain application source and all Worker/D1/KV identity, origins, auth mode,
-   secrets and legacy `.mantle` metadata. Those files are not templates to
-   replace or evidence that new Starter tags must exist.
-5. Run the installed `mantle generate`, `generate --check`, `skills`,
-   `skills --check`, `validate`, and the project's TypeScript/tests. Test local
-   routes and configured authorization before considering deployment.
-
-## Native Schema-table storage reset
-
-The 0.1.2 pre-beta line replaces the generic `entries` JSON table with one
-native SQLite/D1 table per Manifest Schema. Mantle's row envelope uses
-`_mantle_id`, `_mantle_status`, `_mantle_version`, `_mantle_author_id`,
-`_mantle_created_at`, and `_mantle_updated_at`; authored fields keep their exact
-names as native columns. The old generated columns, projection views and
-compatibility repository were removed.
-
-This is intentionally a storage-format break before beta. Reset and
-re-bootstrap development or internal-alpha content databases that contain the
-old `entries` layout. Move required data manually outside Mantle and Control;
-there is no product migration workflow for this unreleased format. Automatic
-artifacts cover initial and additive changes only. Removed columns and tables
-remain physically present so the previous Worker can still run. Renames, type
-changes, data transforms, and any `uniqueIndexes` tuple change require the same
-manual rebuild. The pre-beta Cloud
-path does not accept or execute destructive SQL.
-
-Row APIs are now Schema-qualified. `EntryRepository.get` and
-`EntryReader.readById` accept `{ collection, id }`; Admin entry detail and
-mutation routes require `?collection=<schema>`, and generic MCP entry tools
-require `collection`. Generated `entries.<schema>` bindings supply it for you.
-
-A new project follows [direct authoring](direct-authoring.md). Templates and
-provider setup are not hidden inside `generate`. Future Builder/landing-next
-provisioning is a separate decision; this change does not migrate those hosts.
-
-## Site chrome: GA4 and Meta Pixel leave siteConfig
-
-`SiteConfig.ga4MeasurementId`, `SiteConfig.facebookPixelId`, and their
-`SiteDefaults` seed equivalents are removed. The Admin UI no longer has
-Analytics fields for them, the Runtime site-settings use case no longer
-accepts them, and the Web HTML renderer no longer injects the gtag or Pixel
-base snippet into rendered storefront HTML. This applies to every 0.1.2
-prerelease; it is not staged behind a flag.
-
-Core's `siteConfig` remains deployment identity only (locales, brand, title,
-description, origin, icons, media); tracking and verification tags are host
-chrome because frontends are plural and Core cannot assume one `</head>` to
-rewrite. See [Why Core does not inject](handbook/cloudflare/site-chrome.md#why-core-does-not-inject).
-
-To keep GA4 or Meta Pixel across the upgrade:
-
-1. Read the existing `ga4MeasurementId` / `facebookPixelId` values from the
-   pre-upgrade site settings (Admin API or KV/D1 `SiteConfigRepository`
-   directly) before removing the old columns/fields.
-2. Move the tag injection into host chrome following
-   [Cloudflare-first install > Analytics](handbook/cloudflare/site-chrome.md#analytics):
-   render the snippet in the host's own document/layout, not through Core.
-3. Drop the old fields from any locally stored site-settings payloads; the
-   Runtime `SiteConfig` type no longer declares them, so a TypeScript build
-   against the new types is what surfaces a leftover reference.
-
-## Earlier alpha.7 compatibility changes
-
-
-0.1.2 removes the temporary full-site compatibility stack. Mantle Core is now
-an embeddable parse → link → compile → prepare → bind pipeline; Web, Admin,
-Admin UI, Bun, Vercel, and Cloudflare are selected separately.
-
-| alpha.7 | 0.1.2 |
-|---|---|
-| `parseManifests*` | `parseManifestSources({ sources })` |
-| raw `Manifest[]` validation/runtime input | `ParsedManifestSet` → `LinkedManifestSet` → `RuntimePlan` |
-| `createCmsRuntime({ manifests, db })` | `bootMantleRuntime({ plan, storage })`, or explicit prepare then `createMantleRuntime({ prepared })` |
-| `CmsRuntime.db` / `entryReader` | keep the application DB handle; use `runtime.entries` for Mantle reads |
-| generated `manifest`, `site.ts`, `types.d.ts` | generated `plan`, `createMantle`, `bindMantle`, and types in `mantle.ts` |
-| `mantle introspect` | install `@aotter/mantle-spec` directly and run `mantle-spec introspect` |
-| `mantle emit-types` | use `mantle generate`; for raw declarations, run `mantle-spec emit-types` |
-| generated `.agent/skills/` | generated `.agents/skills/`; legacy user files are left untouched |
-| `bindMantleSite` / string-keyed Views | `bindMantle(runtime)` and generated lower-camel properties |
-| `createCmsRef` / `CmsConfig` | `createMantleRuntimeRef` / `MantleCloudflareConfig` |
-| `mountServerEndpoints` | explicitly compose `mountRuntimeEndpoints` and optional `mountAdmin` |
-
-Delete stale generated `site.ts` and `types.d.ts` files once, then run
-`mantle generate`. Install only the optional package used by the host;
-installing the umbrella alone now pulls only Spec and Runtime.
-
-Intentional behavior changes:
-
-- Generated-plan fingerprint or version mismatches fail immediately and ask
-  the developer to regenerate.
-- Runtime HTTP trigger JSON bodies must be objects. Arrays and primitives are
-  rejected at the request boundary.
-- Malformed percent-encoded paths are routing misses (`404`), not claimed
-  Mantle routes.
-- Better Auth and every `@better-auth/*` package move together to 1.7.
-  `oauthProvider.validAudiences` becomes protected `resources`; MCP uses one
-  canonical `${PUBLIC_ORIGIN}/mcp` resource and CIMD client discovery.
-- The Cloudflare adapter no longer requires `OAUTH_KV` or
-  `@cloudflare/workers-oauth-provider`. Old opaque tokens and KV registrations
-  cannot be migrated safely and must reconnect.
-- Canonical plan ordering may change stable field/export order (including
-  Admin CSV columns) without changing field values.
-
-This alpha changes the Better Auth D1 schema, including required account
-issuer identity and OAuth resource/client tables. Reset and re-bootstrap a
-pre-1.7 alpha auth database; do not guess an issuer backfill. Reset old generic
-content storage as described above and move required data manually outside
-Mantle.
+Every version before 0.1.2 was an internal prerelease. If you are holding a
+database created by one of those, `LEGACY_STORAGE_RESET_REQUIRED` means it
+predates native Schema tables: rebuild it rather than migrating it. Move any
+data you need out of Mantle by hand first — there is no product migration for
+that unreleased storage format.

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
 
@@ -15,9 +15,9 @@ No task implicitly authorizes publication; no manual package/tag writer exists.
 |---|---|---|
 | Reviewed source; unused version | Core source/packed-consumer gates, then immutable Core tag | Exact canonical merged PR SHA and version required |
 | Tag exists; registry candidates partial | Existing npm/GPR publication steps | Verify existing artifact identity; publish missing versions only |
-| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels unchanged |
-| Consumer passes | Monotonic npm/GPR channel promotion | Same version is a no-op; older runs cannot move a channel backward |
-| Channels promoted/preserved newer | GitHub release step | Existing release identity or fail |
+| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels and `mantle-release` unchanged |
+| Consumer passes | That registry's promote step: monotonic channel add, then `dist-tag rm` of `mantle-release` only | Same version is a no-op; older runs cannot move a channel backward. Removal runs only after that package's promote loop, and only when `mantle-release` points at this version. A missing tag is a no-op. A tag pointing at another version is left for that version's promote step. `alpha` / `beta` / `rc` / `latest` are never removed |
+| Channels promoted or preserved, and the temp tag cleared or left | GitHub release step | Existing release identity or fail |
 
 The public-registry gate uses a disposable copy of the directly authored
 `docs/examples/host-minimal-worker` reference, installs the exact candidate, then
@@ -39,9 +39,41 @@ foundational blocker returns to the state table and the user for a scope
 decision instead of starting another local redesign loop.
 
 Invariants: immutable versions/tags retain their identity; registry integrity
-and the published-consumer gate precede public channel promotion; retries
-cannot move channels backward. No downstream mutation, unpublish or rollback
-is introduced. The runnable release-order check guards these transitions.
+and the published-consumer gate precede public channel promotion and any
+removal of `mantle-release` by the release controller; retries cannot move
+channels backward. No downstream mutation, unpublish or rollback is
+introduced. The runnable release-order check guards these transitions.
+
+Mutation boundaries during a release: `Publish to npmjs` and `Mirror to
+GitHub Packages` may attach `mantle-release` while publishing a version.
+`Promote npmjs channel tags` is the only release step that moves npmjs
+channels or removes that tag for the version being released. `Promote
+GitHub Packages channel tags` is the only release step that does the same
+for GitHub Packages. Recovery of a partial release reruns that same
+controller and version. It does not call the cleanup workflow.
+
+The cleanup workflow is a separate writer for one case the controller
+cannot cover: a release commit that predates temp-tag removal still leaves
+`mantle-release` behind, and a personal npm token that is `read-write` on
+`npm access` can still receive 403 on dist-tag DELETE.
+`.github/workflows/remove-mantle-release-dist-tag.yml` uses the Actions
+`NPM_TOKEN` and `GITHUB_TOKEN`. It is not a release controller and not a
+recovery path.
+
+| State | Sole next writer | Retry / invariant |
+|---|---|---|
+| Leftover `mantle-release` after `alpha`, `beta`, `rc`, or `latest` already points at that version | `remove-mantle-release-dist-tag`, only when `confirm` is `remove-mantle-release` | Missing tag is a no-op. Only `mantle-release` is removed. Before and after dist-tags are printed and compared; every other tag is unchanged |
+| `mantle-release` points at a version no consumer channel has | No deletion | The job fails and leaves the tag. Channel moves stay on the release promote step |
+| Confirm string is anything else | No registry call | The job fails before reading or editing tags |
+
+It shares the `release-controller` concurrency group with
+`cancel-in-progress: false`, so it waits out an in-progress release instead
+of deleting `mantle-release` between publish and channel promotion. After
+this file is on `develop`:
+
+```sh
+gh workflow run remove-mantle-release-dist-tag --ref develop -f confirm=remove-mantle-release
+```
 
 ## Branches and channels
 
@@ -56,14 +88,17 @@ 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. No prerelease moves latest; the 0.0 alpha rule that
-  also advanced it was removed once 0.0 became unreachable.
-  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.
+- Publish uses `--tag mantle-release`, so publication does not move
+  `alpha`, `beta`, `rc`, or `latest`. After the public-registry consumer
+  gate, each registry's promote step moves the real channel and then removes
+  `mantle-release` when that tag points at this version.
 
 ## Prepare and run
 
@@ -84,7 +119,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.
@@ -94,7 +130,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
@@ -102,10 +138,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)
 
@@ -113,9 +150,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
@@ -148,18 +185,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.
@@ -171,12 +210,14 @@ 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.
+correct channel tags, no `mantle-release` tag left on this version, and the
+GitHub release. Retain run links and gate evidence.
+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/spec-only-host-adoption.md

@@ -6,7 +6,7 @@ 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.2`. Pin the package, record the tested version, and
+This recipe targets `0.1.3-alpha.2`. Pin the package, record the tested version, and
 rerun compatibility checks when upgrading.
 
 ## What stays with the host