@aotter/mantle 0.1.2-rc.1 → 0.1.2

package/README.md

@@ -4,15 +4,15 @@ Umbrella entry for the embeddable Mantle SDK — a manifest-driven application
 engine built around a 4-atom YAML model (Schema / View / Procedure / Trigger)
 where agents write config and the runtime carries the complexity.
 
-> Mantle is prerelease software. Use this package's `package.json` as the exact
-> installed version; APIs may change between prereleases until the first stable 0.1.2 release.
+> Mantle's first stable release is `0.1.2`. Use this package's `package.json`
+> as the exact installed version.
 
 ## Install
 
 ```bash
-npm install @aotter/mantle@alpha
+npm install @aotter/mantle
 # or
-pnpm add @aotter/mantle@alpha
+pnpm add @aotter/mantle
 ```
 
 ## What's inside

package/docs/adapter-guide.md

@@ -90,6 +90,11 @@ ports. Unsupported native View dialects fail before the adapter mutates state.
 
 ### Bun embedding
 
+> **Experimental.** The Bun and Vercel adapters may change in a minor
+> release. They cover public Views and HTTP Triggers; the host owns
+> authentication and CSRF, and Auth, Admin and MCP are Cloudflare-only today.
+> Cloudflare is the supported host.
+
 `@aotter/mantle-bun` is the minimal SQLite reference: pass an application-owned
 `bun:sqlite` `Database` and a compiled `RuntimePlan` to `createBunMantle()`.
 Its `handle()` returns `null` for sibling routes and a Web-standard `Response`

package/docs/agent-prompts.md

@@ -1,9 +1,9 @@
 # Task-specific agent prompts
 
-Copy one block into a coding agent. Resolve handbook pages and official
-examples from `docs/` in this checkout, or from
-`node_modules/@aotter/mantle/docs/` after install. If neither tree exists,
-pin `@aotter/mantle` first. `npx --no-install mantle --help` is the layered
+Copy one block into a coding agent. Paths below are relative to the Mantle
+docs root: `node_modules/@aotter/mantle/docs/` after `@aotter/mantle` is
+installed, or `docs/` in the installed agent plugin. Pin `@aotter/mantle`
+first if neither exists. `npx --no-install mantle --help` is the layered
 overview. There is no `mantle create`. Admin is opt-in.
 
 ### Embed Runtime with typed APIs
@@ -49,7 +49,7 @@ frontend build.
 ```text
 Interview me about the service: host, who uses it, whether humans need a
 Dev UI, and whether we only embed Spec/Runtime. Read mantle --help, then
-handbook/start/project-and-cli.md. Use docs/examples/README.md as the
+handbook/start/project-and-cli.md. Use examples/README.md as the
 examples index; copy builtin-* Manifests only (not cf-primitives-*).
 Implement locally first. Take only the surfaces we chose.
 For Spec-only use, skip Runtime and code generation. For a Worker without
@@ -73,10 +73,9 @@ claim Auth or Admin works from a public 200.
 
 ```text
 Build with ChatGPT Sites; use Mantle for content management and publishing.
-Read the matching SDK docs/handbook/sites/index.md and
-docs/examples/host-chatgpt-sites/README.md. Use that runnable host as a
-reference. Follow its supported installation path, including packed-checkout
-installation while release support is pending. Derive Schema, View,
+Read handbook/sites/index.md and examples/host-chatgpt-sites/README.md.
+Use that runnable host as a reference and install its pinned
+dependencies from the registry. Derive Schema, View,
 Procedure and Trigger from my requirements and check the Admin editor/picker and public
 projections against them. Request both Sites D1 and R2 when my workflow
 includes uploads. Bind the R2 media port, declare media.purposes, and keep

package/docs/examples/host-chatgpt-sites/README.md

@@ -2,21 +2,35 @@
 
 The runnable application for [Mantle on ChatGPT Sites](../../handbook/sites/index.md) connects Sites D1 + R2 bindings, Sign in with ChatGPT identity, Mantle Admin and staff roles, same-origin media upload, a published-only article frontend, anonymous read-only `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. Remote OAuth MCP remains a separate integration; see [MCP support](../../handbook/sites/host-reference.md#remote-mcp-is-a-separate-gate).
 
-**SDK requirement:** this revision requires the checkout's `mountMantleAdmin.mcpEndpoints` support. Published `0.1.2-alpha.6` does not include it, even though the checkout still carries that version number. Use the exact packed-checkout workflow below; copying this folder and running `npm ci` against the registry is not a supported reproduction of this revision. Build typechecking and the endpoint smoke assertions reject that mismatch. Once a release contains this change, update every Mantle dependency and the lockfile together before switching back to registry installation.
-
 After setup, follow [Publish your first article](../../handbook/sites/index.md#publish-your-first-article) to verify the editorial workflow in Admin.
 
 ## Before writing code
 
 Read the user's business request and author the manifest for **their** records and lifecycle. The included `articles` example deliberately allows a title-only draft; `body` uses `x-mcp-hint: markdown`, while `coverAssetId` uses both `x-mantle-ref: media_assets` (Admin picker) and `x-mcp-hint: media-image` (agent guidance). The `published-articles` View is a list projection, not the detail page contract. If the user's content must always have a body, add it to `required`; if the public API must return body or cover ID, add those to the View's `fields`. Review staff roles, public filters and indexes before deployment. `mantle validate` checks grammar, **not** whether this model matches the business request. Manifest changes after deployment require a new reviewed D1 migration and matching storage fingerprint; never edit an applied migration.
 
-## Local reproduction
+## Install and run
+
+Requires Mantle 0.1.2 or newer. Copy this directory outside the SDK checkout, then:
+
+```bash
+npm install                                  # or: bun install
+npx mantle validate --phase deploy           # or: bunx mantle ...
+npm run generate && npm run check
+npx wrangler d1 migrations apply DB --local
+npm run dev -- --port 4174                   # leave running
+npm test                                     # smoke, in a second terminal
+```
+
+`npm install` resolves `@aotter/mantle*` from the `latest` dist-tag; this
+example does not commit a lockfile, so every fresh install picks up the
+current stable release. `bun install` works too, resolving from
+`package.json` the same way.
+
+Keep `.openai/hosting.json`; do not copy an existing Site's `project_id`. To use another port, also set the Worker's `PUBLIC_ORIGIN` and the test's `MANTLE_TEST_ORIGIN` to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
+
+Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
 
-1. Start from a clean, committed Mantle checkout containing this change. Record its `git rev-parse HEAD`, then run `pnpm install --frozen-lockfile` and `pnpm build` from the repository root.
-2. Run `node scripts/check-packed-consumer.mjs --project docs/examples/host-chatgpt-sites --output /absolute/path/to/new-sites-reproduction -- pnpm build`. The output path must not exist and must be outside the SDK checkout. This existing helper copies the committed example, packs the SDK, installs exact tarball overrides for all Mantle packages, and reports the source SHA and package hashes. Keep the resulting `artifacts/` beside `consumer/` so the lockfile's tarball paths remain valid.
-3. Work in `/absolute/path/to/new-sites-reproduction/consumer`. Run `pnpm exec mantle validate --phase deploy`, `pnpm check`, then `pnpm exec wrangler d1 migrations apply DB --local`. Keep `.openai/hosting.json` but do not copy an existing Site's `project_id`.
-4. Start `pnpm dev --port 4174` in another terminal, then run `pnpm test`. To use another port, also override the Worker's `PUBLIC_ORIGIN` and set `MANTLE_TEST_ORIGIN` for the test to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
-5. Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
+To run this example against an unreleased Mantle checkout instead of the registry, use `node scripts/check-packed-consumer.mjs --project docs/examples/host-chatgpt-sites --output <new dir> -- pnpm build` from a clean SDK checkout and work in its `consumer/`. That path is for SDK development only.
 
 The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest. `scripts/migration.mjs` shows the one-time generation mechanism; do **not** run it against a deployed database or overwrite an applied migration. For a new business manifest, generate/review an initial migration before the first deployment; for a later change, generate an additive migration from the previous schema state.
 

package/docs/examples/host-chatgpt-sites/package.json

@@ -1 +1 @@
-{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"0.1.2-alpha.6","@aotter/mantle-admin":"0.1.2-alpha.6","@aotter/mantle-admin-ui":"0.1.2-alpha.6","@aotter/mantle-cloudflare":"0.1.2-alpha.6","@aotter/mantle-web":"0.1.2-alpha.6","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.25.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}
+{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}

package/docs/examples/host-chatgpt-sites/src/index.ts

@@ -23,7 +23,7 @@ function assemble(env:Env) {
   mountWeb(app,get);
   mountMcp(app,get,auth);
   mountMedia(app,auth,env);
-  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2-alpha.6'});});
+  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2'});});
   app.get('/admin/sign-in',async c=>{
     if(c.req.header('cookie')?.split(';').some(v=>v.trim()==='mantle-sites-signout=1')) {
       c.header('Set-Cookie','mantle-sites-signout=; Path=/admin/sign-in; HttpOnly; SameSite=Strict; Max-Age=0'+(env.PUBLIC_ORIGIN.startsWith('https:')?'; Secure':''));

package/docs/examples/host-local-admin-otp/README.md

@@ -9,10 +9,9 @@ Schema is example business data; `mantle generate` never invents it.
 Spec + adapter without Admin:
 [`docs/examples/host-minimal-worker`](../host-minimal-worker/README.md).
 
-Pin every `@aotter/mantle*` package to the exact version in this snapshot
-(`packages/mantle/package.json`). This reference records that version as
-its published baseline; Core's test runner substitutes its exact candidate
-in a disposable copy.
+This reference depends on every `@aotter/mantle*` package via the `latest`
+dist-tag, so a fresh install always resolves the current stable release.
+Core's test runner substitutes its exact candidate in a disposable copy.
 
 ## One-shot
 

package/docs/examples/host-local-admin-otp/package.json

@@ -11,10 +11,10 @@
     "check": "node ensure-dev-vars.mjs && mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-admin": "0.1.2-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@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",

package/docs/examples/host-minimal-worker/README.md

@@ -9,9 +9,10 @@ Schema/View is example business data; `mantle generate` never invents it.
 
 For your own project, author package.json, manifests, Worker/provider config
 and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. This reference records the snapshot
-version in this tree as its published baseline; Core's test runner substitutes
-its exact candidate in a disposable copy.
+dependencies to the same intended release. This reference depends on them via
+the `latest` dist-tag instead, so a fresh install always resolves the current
+stable release; Core's test runner substitutes its exact candidate in a
+disposable copy.
 
 Outside the SDK workspace, with Node 22+ and pnpm 9+:
 

package/docs/examples/host-minimal-worker/package.json

@@ -10,8 +10,8 @@
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -112,7 +112,7 @@ Bun, with the server and SQLite handle staying yours:
 
 ```ts
 import { Database } from "bun:sqlite";
-import { createBunMantle } from "@aotter/mantle-bun";
+import { createBunMantle } from "@aotter/mantle-bun";  // experimental
 
 const database = new Database("app.sqlite");
 const mantle = createBunMantle({ plan, database, handlers });
@@ -128,7 +128,7 @@ Vercel Functions, with storage injected:
 
 ```ts
 import { SqliteMantleStorageAdapter } from "@aotter/mantle-runtime";
-import { createVercelMantle } from "@aotter/mantle-vercel";
+import { createVercelMantle } from "@aotter/mantle-vercel";  // experimental
 import { LibsqlDatabaseDriver } from "@aotter/mantle-vercel/libsql";
 
 const mantle = createVercelMantle({

package/docs/handbook/sites/host-reference.md

@@ -9,8 +9,6 @@ integration connects Sites hosting and sign-in to Mantle content, staff roles,
 Admin, media, and public web. Keep the application outside the Mantle SDK
 checkout and use matching SDK packages.
 
-The current reference requires unreleased host-declared MCP endpoint support. Follow its [packed-checkout installation](../../examples/host-chatgpt-sites/README.md#local-reproduction); published `0.1.2-alpha.6` does not provide that contract. The build and smoke checks verify the installed SDK rather than relying on its version string alone.
-
 Start from the [runnable Sites host reference](../../examples/host-chatgpt-sites/README.md), then replace its **example** manifest with the user's business contract. It contains the matching D1 migrations/fingerprint, R2 upload adapter, local smoke test and build layout. Its browser-backed staff identity is not an OAuth resource-server credential.
 
 ## First deployment
@@ -108,8 +106,7 @@ for live payments.
 
 ## Source
 
-- [`MediaStorage` port](../../../packages/mantle-runtime/src/domain/port/MediaStorage.ts)
-- [Media upload use case](../../../packages/mantle-runtime/src/usecase/media/CreateMediaUploadUseCase.ts)
+- `MediaStorage` port and the media upload use case in `@aotter/mantle-runtime`
 - [Cloudflare R2 Workers binding API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)
 - [Cloudflare R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
 - [OpenAI Sites](https://learn.chatgpt.com/docs/sites)

package/docs/handbook/sites/index.md

@@ -34,14 +34,6 @@ boundaries.
 
 ## Start with the supported SDK
 
-**Release status:** this revision needs the new host-declared MCP endpoint
-support. Published `0.1.2-alpha.6` does not contain it. Use the
-[packed-checkout installation](../../examples/host-chatgpt-sites/README.md#local-reproduction)
-to build this exact SDK and its reference application together. It records the
-source commit and package hashes. A registry-only installation becomes the
-starting path after a release includes this support and the example's dependency
-versions and lockfile are updated together.
-
 You need Node.js 22+, pnpm 9+, and Sites access with D1 and R2 available for your
 project. Follow the reference's local build and smoke test before deployment.
 Keep your application outside the SDK checkout. The included article schema is
@@ -50,7 +42,7 @@ a working example; adapt its fields and lifecycle to your team's content.
 ## Publish your first article
 
 1. **Prepare the application.** Follow the
-   [runnable reference](../../examples/host-chatgpt-sites/README.md#local-reproduction).
+   [runnable reference](../../examples/host-chatgpt-sites/README.md#install-and-run).
    Its local test verifies content, roles, images, public pages, and MCP together.
 2. **Connect Sites.** Follow [Publish with Sites](../../examples/host-chatgpt-sites/README.md#publish-with-sites)
    to provision D1 and R2, set the production origin and first owner's email,
@@ -77,20 +69,22 @@ deployment workflow.
 
 ## Ask your agent to set it up
 
-Give your agent the SDK checkout containing this integration and describe your
+Install the Mantle agent plugin, or `@aotter/mantle` itself, then describe your
 audience and content requirements:
 
 ```text
 Build a content site with ChatGPT Sites and Mantle. Read
-docs/handbook/sites/index.md and docs/examples/host-chatgpt-sites/README.md
-from the matching Mantle SDK. Follow the documented installation path,
-including packed-checkout installation while release support is pending.
+handbook/sites/index.md and examples/host-chatgpt-sites/README.md from the
+installed Mantle docs, and follow that reference's install and run steps.
 Adapt the article example to my content requirements. Include ChatGPT
 sign-in, Mantle staff roles, cover uploads, and published article pages.
 Run the local checks and show me a draft-to-publish walkthrough before
 deploying through Sites. Keep remote staff OAuth MCP outside this scope.
 ```
 
+For business rules beyond content, add: "use custom `ref` handlers and
+application-owned tables as described in handbook/sites/equipment-checkout.md."
+
 ## Beyond content: operational workflows
 
 Custom handlers can connect typed Mantle operations to application-owned

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

@@ -3,7 +3,7 @@ description: "Open local Admin in one shot: generate the prebuilt SPA, bind ASSE
 ---
 # 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. Pin every `@aotter/mantle*` package to the exact version in this snapshot (`packages/mantle/package.json`); see [Versions](../reference/surface.md#versions).
+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).
 
@@ -17,7 +17,7 @@ An agent interviews the human for one value before writing files: the bootstrap
 
 ## 1. `package.json`
 
-Pin every `@aotter/mantle*` package to the same exact release. Admin needs both `@aotter/mantle-admin` and `@aotter/mantle-admin-ui` plus the Cloudflare adapter peers.
+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
 {
@@ -32,10 +32,10 @@ Pin every `@aotter/mantle*` package to the same exact release. Admin needs both
     "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-admin": "0.1.2-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@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",

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

@@ -3,7 +3,7 @@ description: "Author a minimal Cloudflare Worker from scratch: one Schema, one p
 ---
 # Quickstart: a minimal Worker
 
-This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Pin every `@aotter/mantle*` package to the exact version in this snapshot (`packages/mantle/package.json`); see [Versions](../reference/surface.md#versions).
+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
 
@@ -13,7 +13,7 @@ This page reproduces Core's API-only Worker reference as a from-scratch walkthro
 
 ## 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
 {
@@ -28,8 +28,8 @@ Pin every `@aotter/mantle*` package to the same exact release and add the peers
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit"
   },
   "dependencies": {
-    "@aotter/mantle": "0.1.2-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.2-alpha.6",
+    "@aotter/mantle": "latest",
+    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",

package/docs/release-process.md

@@ -61,7 +61,8 @@ is introduced. The runnable release-order check guards these transitions.
   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

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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.2-rc.1",
+  "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-rc.1",
-    "@aotter/mantle-spec": "0.1.2-rc.1"
+    "@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-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-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-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.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`.

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

package/skills/provision/SKILL.md

@@ -14,9 +14,11 @@ 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.
+`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