@aotter/mantle 0.1.2-alpha.6 → 0.1.2

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

@@ -0,0 +1,239 @@
+---
+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."
+---
+# 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).
+
+The default embed path — Spec + Worker without Admin — is [Quickstart: a minimal Worker](./quickstart-worker.md).
+
+## Prerequisites
+
+- 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
+
+```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`.
+
+## What `mantle generate` wrote
+
+- `.mantle/generated/mantle.ts` — the sealed `plan`, generated types, `createMantle` and `bindMantle`.
+- `public/_mantle/admin/` — the prebuilt Admin SPA. Required for `/admin`.
+
+`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).
+
+## Next steps
+
+- [Project layout and the CLI loop](./project-and-cli.md) — the files you own, every CLI flag, the daily check loop, ASSETS as a hard Admin requirement.
+- [Authentication](../cloudflare/authentication.md) — production senders, GitHub / hosted modes, roles.
+- [The conventional Worker](../cloudflare/conventional-worker.md) — handlers and extra routes.
+- [Quickstart: a minimal Worker](./quickstart-worker.md) — API-only embed without Admin.
+
+## Source
+- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
+- [`docs/examples/host-local-admin-otp/package.json`](../../../docs/examples/host-local-admin-otp/package.json)
+- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
+- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
+- [`docs/examples/host-local-admin-otp/.dev.vars.example`](../../../docs/examples/host-local-admin-otp/.dev.vars.example)
+- [`docs/examples/host-local-admin-otp/smoke.mjs`](../../../docs/examples/host-local-admin-otp/smoke.mjs)

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

@@ -3,10 +3,7 @@ description: "Author a minimal Cloudflare Worker from scratch: one Schema, one p
 ---
 # Quickstart: a minimal Worker
 
-This page reproduces Core's minimal Worker reference as a from-scratch walkthrough. It is for engineers who want a running Mantle service on their machine in a few minutes, with no visitor frontend and no Cloudflare account.
-
-> **Version scope**
-> The install below uses the published `0.1.0-alpha.17` packages. That release supports this minimal Worker flow, but still includes `mantle create` and `mantle update` and does not contain this handbook. The rest of this handbook describes a later development snapshot; see [Versions](../reference/surface.md#versions) before applying its CLI and migration guidance to a registry installation.
+This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Install every `@aotter/mantle*` package from the `latest` dist-tag; see [Versions](../reference/surface.md#versions).
 
 ## Prerequisites
 
@@ -16,7 +13,7 @@ This page reproduces Core's minimal Worker reference as a from-scratch walkthrou
 
 ## 1. `package.json`
 
-Pin every `@aotter/mantle*` package to the same exact release and add the peers the Cloudflare adapter needs.
+Install every `@aotter/mantle*` package from the `latest` dist-tag and add the peers the Cloudflare adapter needs.
 
 ```json
 {
@@ -27,12 +24,12 @@ Pin every `@aotter/mantle*` package to the same exact release and add the peers
     "generate": "mantle generate",
     "validate": "mantle validate",
     "typecheck": "tsc --noEmit",
-    "dev": "wrangler dev --local",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.0-alpha.17",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",
@@ -91,6 +88,7 @@ metadata:
 spec:
   surface: public
   from: notes
+  cache: { sharedMaxAge: 3600 }
   fields: [id, title]
   filter:
     eq: { field: status, value: published }
@@ -135,15 +133,15 @@ Both compatibility flags are required by the adapter. `MANTLE_AUTH_MODE` must be
 pnpm install
 pnpm exec mantle generate
 pnpm exec mantle validate
-pnpm exec wrangler dev --local
+pnpm exec wrangler dev --local --ip 127.0.0.1 --port 8787
 ```
 
-`mantle validate` prints `OK  no issues (root: manifests, phase: preview)`. Wrangler prints the local origin, normally `http://localhost:8787`; use whatever it prints in the next step.
+`mantle validate` prints `OK  no issues (root: manifests, phase: preview)`. Wrangler prints `Ready on http://127.0.0.1:8787`. Use that origin in the next step. The Admin OTP path uses the same pin; `PUBLIC_ORIGIN` must match wrangler's printed origin there.
 
 ## 6. Probe the Worker
 
 ```sh
-curl -s http://localhost:8787/api/views/published-notes
+curl -s http://127.0.0.1:8787/api/views/published-notes
 ```
 
 ```json
@@ -153,13 +151,13 @@ curl -s http://localhost:8787/api/views/published-notes
 The View is served with no data because the local D1 is fresh. `show` follows the View's `limit` when the request carries no `?show=`; `?page=` and `?show=` are the reserved pagination params ([Reads: Views, REST and MCP](../concepts/views.md)).
 
 ```sh
-curl -i http://localhost:8787/
+curl -i http://127.0.0.1:8787/
 ```
 
 `GET /` returns `404`. No visitor frontend is installed or rendered; `mantle-web` is optional composition and never owns an implicit home route. Add your own routes or templates when the product needs them ([Public web, SEO and cache](../cloudflare/public-web.md)).
 
 ```sh
-curl -i http://localhost:8787/mcp/staff
+curl -i http://127.0.0.1:8787/mcp/staff
 ```
 
 `GET /mcp/staff` returns `503` with the error code `setup_incomplete` until `MANTLE_AUTH_MODE` is backed by a complete configuration. This is the expected fail-closed state; a working public endpoint is not evidence of a working Admin or MCP login.
@@ -171,23 +169,24 @@ curl -i http://localhost:8787/mcp/staff
 
 `generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. `mantle generate --check` reports stale output without writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
 
-> **npm and `ERESOLVE`**
-> With npm 11.16.0 a cold Cloudflare install can fail with `ERESOLVE`: Better Auth/Drizzle selects optional `@libsql/client@0.18.0` while this release declares the tested `^0.17.4` peer. If that exact conflict occurs, merge `{ "overrides": { "@libsql/client": "0.17.4" } }` into `package.json` and rerun `npm install`. Do not use `--force` or `--legacy-peer-deps`. Commit the lockfile and use `npm ci` afterwards. Recheck the peer range when upgrading; the workaround is specific to these versions.
+> **npm and optional peers**
+> A cold npm install can fail with `ERESOLVE` when an Auth peer selects a different optional `@libsql/client` than this snapshot declares. If that happens, pin `@libsql/client` in `overrides` to the range in this checkout's `package.json` and rerun `npm install`. Do not use `--force`. Commit the lockfile and use `npm ci` afterwards.
 
 ## Next steps
 
+- [Quickstart: local Admin](./quickstart-admin.md) — opt-in Dev UI: ASSETS, prebuilt Admin, email OTP.
 - [Project layout and the CLI loop](./project-and-cli.md) — the files you own, every CLI flag, the daily check loop.
 - [The four atoms](../concepts/four-atoms.md) — add a Procedure and a Trigger to accept writes.
-- [Authentication](../cloudflare/authentication.md) — complete `MANTLE_AUTH_MODE` so Admin and `/mcp/staff` open.
+- [Authentication](../cloudflare/authentication.md) — complete Auth so Admin and `/mcp/staff` open.
 - [Public web, SEO and cache](../cloudflare/public-web.md) — give the service a rendered public surface.
 
 ## Source
-- [`docs/examples/minimal-worker/README.md`](../../../docs/examples/minimal-worker/README.md)
-- [`docs/examples/minimal-worker/package.json`](../../../docs/examples/minimal-worker/package.json)
-- [`docs/examples/minimal-worker/tsconfig.json`](../../../docs/examples/minimal-worker/tsconfig.json)
-- [`docs/examples/minimal-worker/manifests/site.yaml`](../../../docs/examples/minimal-worker/manifests/site.yaml)
-- [`docs/examples/minimal-worker/src/index.ts`](../../../docs/examples/minimal-worker/src/index.ts)
-- [`docs/examples/minimal-worker/wrangler.jsonc`](../../../docs/examples/minimal-worker/wrangler.jsonc)
-- [`docs/examples/minimal-worker/smoke.mjs`](../../../docs/examples/minimal-worker/smoke.mjs)
+- [`docs/examples/host-minimal-worker/README.md`](../../../docs/examples/host-minimal-worker/README.md)
+- [`docs/examples/host-minimal-worker/package.json`](../../../docs/examples/host-minimal-worker/package.json)
+- [`docs/examples/host-minimal-worker/tsconfig.json`](../../../docs/examples/host-minimal-worker/tsconfig.json)
+- [`docs/examples/host-minimal-worker/manifests/site.yaml`](../../../docs/examples/host-minimal-worker/manifests/site.yaml)
+- [`docs/examples/host-minimal-worker/src/index.ts`](../../../docs/examples/host-minimal-worker/src/index.ts)
+- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)
+- [`docs/examples/host-minimal-worker/smoke.mjs`](../../../docs/examples/host-minimal-worker/smoke.mjs)
 - [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
 - [`packages/mantle-runtime/src/domain/service/Pagination.ts`](../../../packages/mantle-runtime/src/domain/service/Pagination.ts)

package/docs/migration-0.1.2.md

@@ -54,6 +54,32 @@ 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
 
 

package/docs/release-process.md

@@ -20,7 +20,7 @@ No task implicitly authorizes publication; no manual package/tag writer exists.
 | Channels promoted/preserved newer | GitHub release step | Existing release identity or fail |
 
 The public-registry gate uses a disposable copy of the directly authored
-`docs/examples/minimal-worker` reference, installs the exact candidate, then
+`docs/examples/host-minimal-worker` reference, installs the exact candidate, then
 checks generation, skill projection, TypeScript and real Worker HTTP behavior.
 The same reference is gated against exact tarballs before Core tagging. It is
 a test/example, not a scaffold product or another repository release.
@@ -45,11 +45,25 @@ is introduced. The runnable release-order check guards these transitions.
 
 ## Branches and channels
 
-- Alpha releases use the reviewed develop merge. Beta/RC/stable use main after
-  explicit promotion; first stable acceptance is tracked by #826.
-- Alpha/beta/RC GitHub releases are prereleases; their npm tags match suffixes.
+| Version | Source branch | npm dist-tag | GitHub release |
+|---|---|---|---|
+| `X.Y.Z-alpha.N` | `develop` | `alpha` | prerelease |
+| `X.Y.Z-beta.N` | `main` | `beta` | prerelease |
+| `X.Y.Z-rc.N` | `main` | `rc` | prerelease |
+| `X.Y.Z` | `main` | `latest` | release |
+
+- The controller derives the source branch from the version: `-alpha` means
+  `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.
+  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.
 
 ## Prepare and run
 
@@ -57,13 +71,27 @@ is introduced. The runnable release-order check guards these transitions.
    notes since the previous tag; correct PR metadata and label release-only
    PRs skip-release-notes. Do not duplicate release entries in CHANGELOG.md.
 2. Align every workspace package, plugin and marketplace ref to the version.
+   The controller checks package.json files and plugin manifests only; docs
+   pins and the admin-ui registry dependency are hand-edited, so grep for the
+   old version until only lockfiles and registry-pinned examples remain:
+
+   ```sh
+   OLD=<previous version> NEW=<version>
+   git grep -l "\"version\": \"$OLD\"" -- '*.json' ':!**/package-lock.json' \
+     | xargs perl -pi -e "s/\"version\": \"\Q$OLD\E\"/\"version\": \"$NEW\"/"
+   node scripts/sync-plugin-manifests.mjs
+   git grep -n "$OLD" -- ':!pnpm-lock.yaml' ':!**/package-lock.json'
+   ```
+
 3. Review API compatibility and migration instructions for actual consumers.
    Frozen legacy consumers stay on alpha.17; 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.
-5. Freeze the PR head for self review; CI must pass before merge. Dispatch
-   release.yml from that merge with `version` (without v). It refuses an
+5. Freeze the PR head for self review; CI must pass before merge. Merge into
+   `develop` with a merge commit for every version. For an alpha, dispatch
+   release.yml from that merge with `version` (without v). For beta, RC and
+   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:
@@ -79,6 +107,63 @@ The ten public packages remain in dependency order:
 9. @aotter/mantle-cloudflare
 10. @aotter/mantle
 
+## Promote to main (beta, RC, stable)
+
+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.
+   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
+   along, then open the promotion PR against `main`:
+
+   ```sh
+   git fetch origin
+   git push origin <develop merge SHA>:refs/heads/promote/<version>
+   gh pr create --base main --head promote/<version> \
+     --title "release: promote <version> to main" --label skip-release-notes
+   ```
+
+   The body names the version PR, the pinned SHA and the gate evidence. The
+   usual review and checks apply. An organization-admin bypass merge must be
+   recorded on the PR (see CONTRIBUTING).
+4. Merge with a merge commit, never rebase: the controller needs `main`'s tip
+   to be the PR's merge commit. `main`'s tree now equals the pinned commit.
+5. Dispatch from `main` and watch every gate exactly as for an alpha:
+
+   ```sh
+   gh workflow run release.yml --ref main -f version=<version>
+   ```
+
+6. RC to stable repeats 2–5 with the next version. `rc` keeps pointing at
+   the last RC; stable moves only `latest`.
+
+Hotfix on `main` is for a published non-alpha version that cannot wait for
+the next promotion. Branch from `main`, include the version bump, PR into
+`main`, dispatch as in step 5, then immediately PR `main` back into `develop`
+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.
+
+```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
+```
+
+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.
+
 ## Credentials and verification
 
 Core needs NPM_TOKEN for npmjs. Its job-scoped GITHUB_TOKEN creates the Core

package/docs/sealed-pipeline-ownership.md

@@ -61,7 +61,7 @@ diagnostics.
 
 The following pins record the historical sealed-pipeline migration gates.
 ADR-0021 supersedes the Starter/Landing release coupling: current Core CI and
-release use `docs/examples/minimal-worker` from the same reviewed commit.
+release use `docs/examples/host-minimal-worker` from the same reviewed commit.
 Private consumers can still run the exact-tarball checker in their own repos;
 public Core PRs receive no cross-repository credentials:
 
@@ -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.2`. 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/docs/transaction-patterns.md

@@ -1,5 +1,5 @@
 # Transaction patterns
 
-This guide moved into the handbook: [`docs/handbook/examples/commerce-transaction.md`](handbook/examples/commerce-transaction.md).
+This guide lives in the Examples hub: [`docs/examples/cf-primitives-commerce-inventory.md`](examples/cf-primitives-commerce-inventory.md). The Builder-safe catalog is [`docs/examples/builtin-commerce.md`](examples/builtin-commerce.md).
 
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.
+The handbook and examples hub ship inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/` and describe the installed release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.2-alpha.6",
+  "version": "0.1.2",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -79,8 +79,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.2-alpha.6",
-    "@aotter/mantle-spec": "0.1.2-alpha.6"
+    "@aotter/mantle-runtime": "0.1.2",
+    "@aotter/mantle-spec": "0.1.2"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -88,12 +88,12 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.2-alpha.6",
-    "@aotter/mantle-bun": "0.1.2-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.2-alpha.6",
-    "@aotter/mantle-vercel": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
-    "@aotter/mantle-web": "0.1.2-alpha.6"
+    "@aotter/mantle-admin-ui": "0.1.2",
+    "@aotter/mantle-admin": "0.1.2",
+    "@aotter/mantle-bun": "0.1.2",
+    "@aotter/mantle-cloudflare": "0.1.2",
+    "@aotter/mantle-vercel": "0.1.2",
+    "@aotter/mantle-web": "0.1.2"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -136,12 +136,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.2-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.2-alpha.6",
-    "@aotter/mantle-bun": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
-    "@aotter/mantle-vercel": "0.1.2-alpha.6",
-    "@aotter/mantle-web": "0.1.2-alpha.6"
+    "@aotter/mantle-admin": "0.1.2",
+    "@aotter/mantle-cloudflare": "0.1.2",
+    "@aotter/mantle-admin-ui": "0.1.2",
+    "@aotter/mantle-bun": "0.1.2",
+    "@aotter/mantle-vercel": "0.1.2",
+    "@aotter/mantle-web": "0.1.2"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -58,8 +58,24 @@ contracts.
 
 ## Source-repository marketplace install
 
-The source repository is also an agent plugin bundle. These manifests are not
-duplicated into the npm package:
+The source repository is also an agent plugin bundle:
+
+```bash
+# Claude Code — two separate prompts
+/plugin marketplace add aotter/mantle
+/plugin install mantle@mantle
+
+# Codex
+codex plugin marketplace add aotter/mantle
+codex plugin add mantle@mantle
+```
+
+These are authoring workflows and do not track a release. Version matching is
+the job of `mantle skills`, which projects the installed package's own skills
+into the project, and `mantle skills --check`, which 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`.