@aotter/mantle 0.0.11-alpha.48 → 0.0.11-alpha.50

package/README.md

@@ -31,14 +31,16 @@ import { mountServerEndpoints } from "@aotter/mantle/cloudflare";
 
 ## Getting started
 
-Recommended path: open the Mantle landing page, answer the launch
-questions, and sign in with GitHub and Cloudflare. Landing provisions the
-site server-side — it creates the private GitHub repo, commits a blank
-deployable Mantle site, and connects the first Cloudflare deploy. Then
-point your coding agent (Claude Code / Cursor / Codex) at the provisioned
-repo to continue.
+Give the [Mantle repo](https://github.com/aotter/mantle) to a coding agent or
+install its agent plugin, then ask it to create a site. The install skill picks
+a deterministic bundle from
+[`aotter/mantle-starters`](https://github.com/aotter/mantle-starters),
+materializes a local project, and verifies it before any provider work.
 
-Starter source and provision bundles live in [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters); launch starts from the blank base and the agent applies the selected type as a post-launch overlay. Generated repos vendor Core-owned `mantle:*` skills from this package for repo-local use. See `skills/install` in the [Mantle repo](https://github.com/aotter/mantle/tree/develop/skills/install) for how the agent continues a provisioned repo.
+[Mantle landing](https://mantle.tools) uses the same bundles and continues
+through private GitHub repo creation, Cloudflare deployment, and optional paid
+hosted auth. Generated repos vendor Core-owned `mantle:*` skills from this
+package for repo-local use.
 
 ## Agent marketplace install
 
@@ -47,7 +49,7 @@ Install the Mantle Core skill bundle before working on generated repos:
 ```bash
 # Claude Code
 /plugin marketplace add aotter/mantle
-/plugin install mantle
+/plugin install mantle@mantle
 
 # Codex
 codex plugin marketplace add aotter/mantle --ref develop

package/docs/release-process.md

@@ -14,7 +14,8 @@ mantle is in `0.0.x-alpha` until the v0.1.0 release gate closes. The process bel
 - Use semver after v0.1.0.
 - Tag format is `vMAJOR.MINOR.PATCH`, for example `v0.1.0`.
 - Alpha tags may use prerelease suffixes, for example `v0.0.6-alpha`.
-- Package versions must stay aligned unless a future ADR explicitly changes package release policy.
+- Package versions and agent plugin manifest versions must stay aligned unless
+  a future ADR explicitly changes release policy.
 
 ## Release channels
 
@@ -278,13 +279,13 @@ source.
 
 Do **not** publish `@aotter/mantle-netlify` while it is a stub.
 
-The retired `create-mantle` scaffolder is not shipped by this SDK repo.
-Releases on this SDK repo must not attach a create-mantle tarball and
-must not publish `@aotter/create-mantle`.
+Releases on this SDK repo must not attach or publish a separate starter
+scaffolder package. Local cold start is owned by the versioned provision
+bundles and materializer in `aotter/mantle-starters`.
 
-`skills/install/SKILL.md` consumes the repo and handoff created by the
-landing page. Human-facing starter bundle details belong in the
-`mantle-starters` README, not this SDK repo.
+`skills/install/SKILL.md` creates or continues a local / landing-generated
+project. Human-facing starter bundle details belong in the `mantle-starters`
+README, not this SDK repo.
 
 ### Pre-publish checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.48",
+  "version": "0.0.11-alpha.50",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -47,10 +47,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.48",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.48",
-    "@aotter/mantle-spec": "0.0.11-alpha.48",
-    "@aotter/mantle-runtime": "0.0.11-alpha.48"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.50",
+    "@aotter/mantle-spec": "0.0.11-alpha.50",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.50",
+    "@aotter/mantle-runtime": "0.0.11-alpha.50"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",

package/skills/README.md

@@ -8,12 +8,14 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 | [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across starters and adapters. |
 | [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project context but does not depend on starter-owned skill semantics. |
 | [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK, starter snapshots, and plugin lockfiles. |
-| [`install`](install/SKILL.md) | User wants to start or continue a Mantle site. Sites launch on [Mantle landing](https://mantle.tools), which provisions the GitHub repo and first Cloudflare deploy; this brief orients the agent to take over and continue the provisioned repo. |
+| [`install`](install/SKILL.md) | User wants to create a local Mantle site from a deterministic starter bundle or continue an existing local / landing-generated project. |
 | [`customize-design`](customize-design/SKILL.md) | Legacy publication-specific design guide. Prefer `mantle:theme` for generated repos. |
 | [`extend`](extend/SKILL.md) | Legacy atom-authoring guide. Prefer `mantle:develop` or `mantle:plugin` depending on whether the work is one-off or installable. |
-| [`provision`](provision/SKILL.md) | User wants production fully usable after a landing launch. Verify the current landing deploy, wire per-site staff auth, smoke test, and hand off the operator setup URL. |
+| [`provision`](provision/SKILL.md) | User wants a local or landing-generated project shipped to Cloudflare with production auth and operator handoff. |
 
-The skills target `mantle@v0.1.0`. Each one names its assumed grammar version in the front-matter `applies_to:` field; future versions add a sibling SKILL.md or update the existing one.
+The skills target `mantle@v0.1.0`. Each one names its assumed grammar version
+in front-matter `metadata.applies_to`; future versions add a sibling SKILL.md
+or update the existing one.
 
 ## Skill authority
 
@@ -43,7 +45,9 @@ The skills target ADR-0007's "AI as primary author" thesis: agents reach these f
 
 Each SKILL.md ships:
 
-- **Front-matter** with `name`, `description`, `when_to_invoke`, `applies_to`.
+- **Front-matter** with a folder-matching `name`, trigger-complete
+  `description`, and optional source/version `metadata`. Plugin hosts add the
+  external `mantle:` namespace.
 - **Preflight** section — environment + user-confirmation gates.
 - **Step-by-step** — concrete commands (`pnpm validate`, `mantle emit-openapi`, etc.).
 - **Diagnostic recipes** — `Symptom → Cause → Fix` table for the common failure modes.

package/skills/customize-design/SKILL.md

@@ -1,9 +1,10 @@
 ---
-name: mantle customize-design
+name: customize-design
 description: Layer custom design over a mantle publication starter project using the L1–L4 theme stack (tokens / extraCss+icons+i18n / Header+Footer+PageShell slots / whole-template fork). Use when the user wants to rebrand, restyle, or swap UI pieces without forking the whole starter.
-when_to_invoke: |
-  User says: "change the colors", "use my own font", "I want a different header", "make this look like X", "this is too plain / too editorial", "translate the labels", "swap the logo". Applies to the `publication` archetype; the `blank` archetype has no UI to customize.
-applies_to: mantle@v0.1.0 + publication archetype
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/customize-design/SKILL.md
+  applies_to: mantle@v0.1.0 + publication archetype
 ---
 
 # Customize the design of a mantle publication site

package/skills/develop/SKILL.md

@@ -1,11 +1,10 @@
 ---
-name: mantle:develop
+name: develop
 description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
-source: "@aotter/mantle"
-sourcePath: skills/develop/SKILL.md
-when_to_invoke: |
-  Working dir contains a Mantle project: package.json depends on @aotter/mantle or @aotter/mantle-*, and manifests/ or src/mantle/config.ts exists. Legacy projects may still use src/mantleConfig.ts.
-applies_to: mantle@v0.1.0
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/develop/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Mantle Develop
@@ -23,7 +22,34 @@ owns the workflow vocabulary.
 4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
 
 If `node_modules/` is missing, run `pnpm install --frozen-lockfile` before
-falling back to remote docs.
+falling back to remote docs. Remote docs must use a tag matching the installed
+version; never use `develop` branch docs for a versioned consumer project.
+
+## Existing Examples
+
+Before inventing a Mantle pattern, inspect
+[`aotter/mantle-starters`](https://github.com/aotter/mantle-starters).
+Use a tag matching the installed Mantle version when available; use `develop`
+only for unreleased work. `blank/` shows the base application shape and
+`overlays/<type>/` contains working examples of manifests, handlers, routes,
+pages, and feature wiring. Copy the smallest matching pattern. Do not edit or
+copy generated `provision-bundles/*.json` by hand.
+
+## Authoring CLI
+
+Use the project's scripts first; generated starters expose the shipping
+`mantle` authoring CLI from `@aotter/mantle-spec`:
+
+```bash
+pnpm exec mantle --help
+pnpm validate
+pnpm introspect
+pnpm emit-openapi
+pnpm emit-types
+```
+
+This CLI validates and derives artifacts from an existing materialized
+project; starter creation is owned by the provision-bundle flow.
 
 ## Core Model
 

package/skills/extend/SKILL.md

@@ -1,9 +1,10 @@
 ---
-name: mantle extend
+name: extend
 description: Add new functionality to an existing mantle project — a new Schema, View, Procedure, or Trigger; or wire a feature like a contact form, newsletter signup, comment thread, or filtered list page. Use when the user already has a mantle project and wants to grow it.
-when_to_invoke: |
-  Working dir contains `manifests/`, `package.json` includes `@aotter/*`. The user describes a new content type, a public REST query, a write endpoint, or a side-effect on entry mutation.
-applies_to: mantle@v0.1.0
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/extend/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Extend a mantle project

package/skills/install/SKILL.md

@@ -1,144 +1,142 @@
 ---
-name: mantle install
-description: Orient and continue a Mantle site that Mantle landing has provisioned. Mantle sites launch on Mantle landing (mantle.tools), which creates the GitHub repo and the first Cloudflare deploy; the agent takes over the provisioned repo to complete the selected type, first pages, and content. Use when the user pasted a Mantle launch / after-launch context, opened a landing-provisioned repo, or wants to start a new Mantle site.
-when_to_invoke: |
-  The user wants a new Mantle site, pasted a Mantle landing launch / after-launch context, or opened a repo that Mantle landing provisioned and wants help continuing it.
+name: install
+description: Start a new Mantle site locally from a deterministic starter bundle, or orient and continue an existing local or Mantle landing project. Use when the user gives a Mantle repository URL and asks to try or build with it, invokes the Mantle install skill, wants a new Mantle site, or opens an existing generated site.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/install/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
-# mantle install
+# Mantle Install
 
-Mantle sites are launched on **Mantle landing** (`https://mantle.tools`),
-not scaffolded locally. Landing asks the launch questions, then provisions
-server-side: it creates the user's private GitHub repo, commits a blank
-deployable Mantle site, and connects Cloudflare Workers CI for the first
-deploy. Your job is to **continue that provisioned repo** — complete the
-selected type, first pages, and content — not to scaffold from scratch.
+Route by the working directory:
 
-There is no local scaffolder to run. The `create-mantle` CLI was retired
-when provisioning moved into landing. If the user has not launched yet,
-send them to `https://mantle.tools` to launch, then resume here once the
-repo exists. Do not rebuild the old manual interview / prompt-composition
-harness.
+- If it already contains `.mantle/launch-state.json` or depends on
+  `@aotter/mantle`, continue the existing project.
+- Otherwise create a new local project from a deterministic provision bundle.
+  Do not use the Mantle SDK checkout as the application.
 
-## Ground Truth
+Mantle landing uses the same bundles but continues through GitHub, Cloudflare,
+and optional paid hosted auth. Use landing only when the user wants that
+hosted provider flow.
 
-`@aotter/mantle-*` exposes exactly four declarative atoms scoped to
-`cms.mantle.aotter.net/v1`, mapping 1-to-1 to Postgres primitives:
+## Create a Local Project
 
-| Atom | Postgres analog | External surface |
-|---|---|---|
-| Schema | `CREATE TABLE` | none directly |
-| View | `CREATE VIEW` | auto-mounted at `GET /api/views/<name>` |
-| Procedure | `CREATE FUNCTION` | none directly |
-| Trigger | `CREATE TRIGGER` + cron + REST route + LISTEN/NOTIFY | binding atom |
+1. Infer the closest starter from the user's request. Ask only when two choices
+   would materially change the result.
 
-Anything domain-shaped (Form, Membership, Workflow) is composed in the
-consumer project from these four atoms plus user TypeScript. Full grammar
-reference:
-<https://raw.githubusercontent.com/aotter/mantle/develop/docs/design-atoms.md>.
+| Intent | Type |
+|---|---|
+| API/MCP backend or empty base | `blank` |
+| Small public or company site | `presence` |
+| Form, application, or submission flow | `intake` |
+| Blog, docs, posts, or editorial site | `publication` |
+| Catalog or order intent | `transaction` |
+| Booking or request intent | `reservation` |
+| Member or participation intent | `community` |
+
+2. Choose absolute paths for a temporary starters checkout and a target
+   directory outside both Mantle repositories. Derive a short project slug,
+   brand, one-sentence description, and locales from the user's prompt.
+
+3. Clone [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
+   into a temporary directory and run its materializer. Use a starters ref
+   supplied by the user for branch testing. Otherwise use a tag matching the
+   requested Mantle version; use `develop` only for unreleased work.
 
-A landing-provisioned repo carries its launch context and ground truth in:
+```bash
+git clone --depth 1 --branch <starters-ref> \
+  https://github.com/aotter/mantle-starters.git <temporary-starters-dir>
+pnpm --dir <temporary-starters-dir> materialize <type> \
+  --out <target-dir> \
+  --project-name <slug> \
+  --brand "<brand>" \
+  --description "<one sentence>" \
+  --locales <comma-separated-locales>
+```
 
-| Path | Contents |
-|---|---|
-| `.mantle/launch-state.json` | Non-secret launch choices: type, purpose, locales, repo, owner, suggested overlay |
-| `.mantle/features.json` | Starter launch context and applied starter state |
-| `.mantle/handoff.md` | The launch handoff note written for you |
-| `manifests/*.yaml` | Schemas / Views / Procedures / Triggers |
-| `src/mantle/config.ts` | Site defaults, runtime bindings |
-| `src/mantle/handlers/index.ts` | Procedure handler registration |
-| `src/handlers/` | Handler implementations |
-| `AGENTS.md` | Cross-tool agent entry |
-| `.agent/skills/` + `.claude/skills/` | Vendored Core skills from `@aotter/mantle`: `mantle:develop`, `mantle:plugin`, `mantle:theme`, `mantle:update` |
-
-## Take Over a Provisioned Repo
-
-The repo was already created and deployed by landing. Continue it:
-
-1. Confirm repository access through an available GitHub connector or MCP
-   tool. Use GitHub CLI only if it is already authenticated.
-2. Clone or open the repo, then read `.mantle/launch-state.json`,
-   `.mantle/features.json`, and `.mantle/handoff.md`.
-3. Inspect the four-atoms manifest, the type overlay notes, pages, and
-   seed data before changing code.
-4. Validate locally before editing:
+The materializer writes the same precomposed `provision-bundles/<type>.json`
+used by Mantle landing. Do not manually copy `blank/`, merge overlays, or edit
+the generated bundle JSON.
+
+4. Initialize and verify the local project:
 
 ```bash
+cd <target-dir>
+git init -b main
 pnpm install --frozen-lockfile
 pnpm validate
 pnpm typecheck
+pnpm dev
 ```
 
-Diagnostics are structured JSON with `code` and `suggestion` fields.
-Surface both verbatim when validation fails.
-
-## Continue With Repo-Local Skills
-
-The generated repo vendors Core-owned skills under `.agent/skills/` and
-`.claude/skills/`. The starter carries local copies for offline/pinned use; it
-does not own a separate skill contract.
+Open `http://localhost:8787`. Public preview works before auth is configured;
+auth-gated routes may return `503 setup_incomplete`.
 
-- **`mantle:develop`** — manifest, runtime, content-model, layout,
-  bug-fix, and validation work on the site.
-- **`mantle:plugin`** — install repeatable marketplace capabilities using
-  a plan-first Core workflow.
-- **`mantle:theme`** — brand and visual direction via Mantle / Kiwa tokens
-  and source. There is no premade theme picker; visual direction is agent
-  work after launch.
-- **`mantle:update`** — compare the repo against its upstream provision
-  bundle or installed plugin locks.
+## Continue an Existing Project
 
-Remove the placeholder blank homepage once the selected type ships a real
-homepage.
+Read these before editing:
 
-## Optional Media Uploads
+1. `.mantle/launch-state.json`, `.mantle/features.json`, and
+   `.mantle/handoff.md`.
+2. `package.json` for the installed `@aotter/mantle*` versions.
+3. Repo-local Mantle skills under `.agent/skills/` or `.claude/skills/`.
+4. Matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 
-Media uploads are a post-launch opt-in, not part of Day 1 provisioning. Do
-not block the first deploy or first useful page on storage setup.
+Use remote docs only when embedded docs are unavailable, and use a tag matching
+the installed version. Never use `develop` docs for a versioned project.
 
-When the current repo uses the Cloudflare adapter and really needs
-staff-managed images or files, follow the Cloudflare R2 recipe:
-<https://raw.githubusercontent.com/aotter/mantle/develop/docs/media-uploads.md>.
+Do not branch on how the project was created. Verify the current git remote,
+live URL, and auth response, then skip work that is already complete.
 
-For media maintenance, prefer Claude Code, Codex, Cursor, or another
-local/non-sandboxed coding agent that can read files and make outbound PUT
-requests. Do not rely on Claude Cowork for R2 uploads; use a
-non-sandboxed agent instead.
+Then run:
 
-## Local Preview
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm typecheck
+```
 
-To see the site locally before pushing:
+Inspect the already composed manifest, page, and seed files before changing
+them. Use the project's scripts first; generated projects expose:
 
 ```bash
-[ -f .dev.vars.example ] && cp .dev.vars.example .dev.vars
-openssl rand -hex 32
-pnpm dev
+pnpm exec mantle --help
+pnpm validate
+pnpm introspect
+pnpm emit-openapi
+pnpm emit-types
 ```
 
-Paste the generated random value into `.dev.vars` as `BETTER_AUTH_SECRET`.
-This secret is local only and must not be reused for production. Use
-`localhost`, not `127.0.0.1`, in local examples. A fresh blank site may
-return 404 on the public home route until the type overlay adds one; treat
-that as an empty-site state, not a failure, when validation and admin
-routes are alive.
-
 ## Production
 
-Landing already created the GitHub repo and the first Cloudflare deploy.
-To finish production — verify the deploy, wire per-site staff auth, smoke
-test, and hand off the operator setup URL — continue with the provision
-skill:
-<https://raw.githubusercontent.com/aotter/mantle/develop/skills/provision/SKILL.md>.
+Local cold start intentionally stops before GitHub and Cloudflare operations.
+When the user asks to ship, use `mantle:provision` from the installed plugin or
+`node_modules/@aotter/mantle/skills/provision/SKILL.md`.
+
+Mantle landing is the first-run option when the user wants Mantle to create the
+private GitHub repo, connect Cloudflare, and offer paid hosted auth. Free
+self-hosted auth requires the owner to configure their GitHub OAuth App and
+provider secrets.
+
+## Report
+
+Return:
+
+- created or opened project path;
+- selected type and why;
+- local URL;
+- validation and typecheck results;
+- observed GitHub, deploy, and auth state;
+- three tailored next options: shape the visual experience, build the first
+  real business workflow, or finish deploy/auth if incomplete. Never leave
+  auth or seed data as the only next step.
 
 ## Don't
 
-- Don't run or look for `create-mantle`; it was retired with provisioning v2.
-- Don't rebuild the manual interview / prompt-composition harness.
-- Don't scaffold a project from scratch locally; launch happens on landing.
-- Don't block the first useful page on polishing prose or writing a site letter.
-- Don't ask for a Cloudflare API token in the base flow.
-- Don't require R2 media setup in the base flow; it is optional
-  post-launch work.
+- Don't use the Mantle SDK checkout as the generated application.
+- Don't hand-compose starter layers; materialize the generated provision
+  bundle.
+- Don't push, deploy, or configure providers during local cold start.
 - Don't commit provider secrets.
-- Don't use `127.0.0.1` in OAuth callback examples; use `localhost` locally
-  and the real Worker URL in production.
+- Don't block the first useful page on optional media storage.

package/skills/plugin/SKILL.md

@@ -1,11 +1,10 @@
 ---
-name: mantle:plugin
+name: plugin
 description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
-source: "@aotter/mantle"
-sourcePath: skills/plugin/SKILL.md
-when_to_invoke: |
-  The user asks for a marketplace/plugin/capability install, or wants a domain feature that should be repeatable across starters and adapters.
-applies_to: mantle@v0.1.0
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/plugin/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Mantle Plugin

package/skills/provision/SKILL.md

@@ -1,79 +1,27 @@
 ---
-name: mantle provision
-description: Finish production for a Mantle site after Mantle landing has provisioned it. Landing already created the private GitHub repo and the first Cloudflare Worker deploy; this skill covers verifying that deploy, wiring per-site staff auth (GitHub OAuth App + Worker secrets), smoke testing, and handing off the operator setup URL.
-when_to_invoke: |
-  Mantle landing has created the repo and the first Cloudflare deploy, the user wants production fully usable, and staff sign-in / MCP still needs wiring.
-applies_to: mantle@v0.1.0
+name: provision
+description: Ship a local or Mantle landing-generated project to Cloudflare and finish production auth. Use when a Mantle project is ready for GitHub, Cloudflare deployment, self-hosted GitHub OAuth, paid Mantle hosted auth verification, production smoke testing, or operator handoff.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/provision/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Provision a Mantle Project
 
-Provisioning is landing-driven. **Mantle landing is the executor for the
-first deploy**: it creates the user's private GitHub repo, commits the
-blank deployable site, connects Cloudflare Workers CI, and triggers the
-first build. You pick up after that to make production fully usable.
-
-The Worker boots before staff auth is configured — it serves public routes
-and returns a clean `503 setup_incomplete` on auth-gated routes until the
-GitHub OAuth App and Worker secrets are set. Your remaining job is to
-finish that wiring, verify, and hand off.
-
-Keep provisioning boring: set the few secrets, commit non-secret config,
-let Cloudflare CI redeploy. Do not re-create the repo, re-run the first
-deploy, or resurrect a heavy `provision:up` orchestrator — both retired
-with v2.
-
-## End State
-
-- Cloudflare has deployed the Worker from the repo (landing's first build,
-  plus your redeploy after config).
-- `wrangler.toml` carries `PUBLIC_ORIGIN`, `GITHUB_CLIENT_ID`,
-  `ADMIN_GITHUB_LOGIN`, and the correct Worker name.
-- Worker secrets are set: `GITHUB_CLIENT_SECRET`, `BETTER_AUTH_SECRET`,
-  and any optional feature/provider secrets.
-- `AGENTS.md` `Public site:` points at the deployed Worker URL.
-- Staff MCP and browser admin sign-in work.
-- Operator setup URL handed to the owner:
-  `https://mantle.tools/connect?site=<url-encoded-worker-url>`.
-
-Provision does not seed production content. First real content is created
-after owner sign-in through Staff MCP / admin authoring.
-
-Media uploads are optional post-launch work. Do not require storage or media
-upload credentials to finish first production provisioning. If the current
-repo uses the Cloudflare adapter and the owner asks for staff image/file
-uploads later, follow the Cloudflare R2 recipe:
-<https://raw.githubusercontent.com/aotter/mantle/develop/docs/media-uploads.md>
-and use Claude Code or another local/non-sandboxed coding agent for the
-upload workflow. Do not use Claude Cowork for R2 uploads; use a
-non-sandboxed agent instead.
-
-## Principles
-
-1. Use the user's accounts. The repo and Worker belong to the user's
-   GitHub and Cloudflare accounts.
-2. No Cloudflare API token in the base flow. Prefer a Cloudflare MCP
-   connector for provider work; use `wrangler login` as a fallback after
-   the user agrees.
-3. GitHub OAuth is per-site and user-owned. The callback URL is exactly
-   `<worker-url>/api/auth/callback/github`.
-4. Launch state is context, not provider authority.
-   `.mantle/launch-state.json` may supply owner, admin login, repo name,
-   locales, and type. It does not authorize Cloudflare operations, OAuth
-   secrets, or custom domains.
-5. `BETTER_AUTH_SECRET` is load-bearing. Set it once and preserve it;
-   rotating it invalidates every session.
-
-## Flow
-
-Run from the generated project root.
-
-1. Verify the landing deploy. Confirm Cloudflare Workers CI built and
-   deployed from GitHub, and capture the live `*.workers.dev` URL. The
-   public site should respond; auth-gated routes return `503
-   setup_incomplete` until step 4 — that is expected, not a failure.
-
-2. Confirm the local repo is clean and valid before changing config:
+Local cold start deliberately stops before this skill. Provision only after the
+user asks to create remote resources or ship production.
+
+## Source of Truth
+
+1. Read `.mantle/launch-state.json`, `.mantle/handoff.md`, `wrangler.toml`,
+   and the current git remotes.
+2. Read installed `@aotter/mantle*` versions from `package.json`.
+3. Use matching embedded docs under `node_modules/@aotter/mantle/docs/`.
+4. Never infer provider authority from launch state. Confirm the active GitHub
+   and Cloudflare accounts before changing them.
+
+Run the local gate first:
 
 ```bash
 pnpm install --frozen-lockfile
@@ -82,95 +30,116 @@ pnpm typecheck
 git status --short
 ```
 
-3. Ask the user to create the per-site GitHub OAuth App once the Worker
-   URL is known:
+## Resume From Observed State
+
+Do not branch on how the project was created. Verify these facts and skip
+completed work:
+
+1. `git remote get-url origin` confirms the GitHub repo.
+2. An HTTPS `PUBLIC_ORIGIN` that responds confirms the Cloudflare deploy.
+3. `/admin/sign-in` returning `503 setup_incomplete` means auth is not bound.
+   Use the recorded auth intent only to choose hosted or self-hosted setup;
+   live behavior is authoritative.
+
+If there is no remote, confirm the target account, create a private repo,
+commit, and push `main`. If there is no live Worker, confirm the Cloudflare
+account, prefer an available connector, or use `pnpm exec wrangler login` with
+the user's agreement, then run `pnpm deploy`.
+
+Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
+commit and push non-secret changes. Reuse any repo or Worker already created
+by landing. Workers Builds is optional after a direct deploy.
+
+## Choose Auth
+
+- **Self-hosted — free:** configure the owner's per-site GitHub OAuth App and
+  Worker secrets using the steps below.
+- **Mantle hosted auth — paid:** use only when the landing handoff records a
+  hosted allocation and client configuration. Mantle Platform operates the
+  identity provider; do not ask the user for a per-site GitHub OAuth App.
+
+Do not claim that hosted auth can attach to an arbitrary local repo unless the
+current Mantle landing flow explicitly supplies that handoff.
+
+For the exact boundary, read
+`node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
+
+## Self-hosted Auth
+
+1. Ask the user to create a GitHub OAuth App:
 
 - Homepage URL: `<worker-url>`
 - Authorization callback URL: `<worker-url>/api/auth/callback/github`
 - Device Flow: unchecked
 
-Ask for the Client ID in chat. Keep the Client Secret out of chat and pass
-it through the hidden shell prompt below.
+2. Put non-secret values in `wrangler.toml`:
 
-4. Write non-secret production config into `wrangler.toml`
-   (`PUBLIC_ORIGIN=<worker-url>`, `GITHUB_CLIENT_ID`, `ADMIN_GITHUB_LOGIN`,
-   and the correct Worker `name`), then set the Worker secrets. Prefer a
-   Cloudflare MCP connector; otherwise use Wrangler after the user agrees
-   to `wrangler login`:
+- `PUBLIC_ORIGIN`
+- `GITHUB_CLIENT_ID`
+- `ADMIN_GITHUB_LOGIN`
+- correct Worker `name`
+
+3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
+   secrets; otherwise use hidden shell input:
 
 ```bash
-pnpm exec wrangler login
-read -rsp "GitHub OAuth client secret: " GITHUB_CLIENT_SECRET && printf "\n"
-printf '%s' "$GITHUB_CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
+read -rsp "GitHub OAuth client secret: " MANTLE_GITHUB_CLIENT_SECRET && printf "\n"
+printf '%s' "$MANTLE_GITHUB_CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
 openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-unset GITHUB_CLIENT_SECRET
+unset MANTLE_GITHUB_CLIENT_SECRET
 ```
 
-Set `BETTER_AUTH_SECRET` only on the first run; reuse the existing value on
-later runs.
+Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
+sessions.
 
-5. Commit and push the non-secret config so Cloudflare CI redeploys:
+4. Commit and push only non-secret config, then redeploy:
 
 ```bash
 git add wrangler.toml AGENTS.md
-git commit -m "mantle: wire production provision"
+git commit -m "mantle: wire production auth"
 git push
+pnpm deploy
 ```
 
-Wait for Workers Builds to redeploy from the pushed commit. If the
-dashboard build is unavailable, run `pnpm deploy` as a fallback and explain
-that to the user.
+## Hosted Auth
+
+Follow the landing handoff and generated client configuration. Hosted
+configuration remains in landing-managed Cloudflare Worker bindings; do not
+write client secrets into `wrangler.toml`.
 
-6. Smoke test:
+Verify that admin sign-in redirects to Mantle Platform and Staff MCP
+authenticates, then skip the self-hosted flow.
+
+## Smoke Test
 
 - public home route;
 - `/admin/sign-in`;
-- GitHub admin sign-in;
+- selected admin sign-in path;
 - `/mcp/staff` with an agent client when available;
-- a type-specific core workflow.
+- one type-specific core workflow.
 
-A fresh site may have no public home content yet. A 404 on the locale
-homepage is acceptable only after the Worker boots, `/admin/sign-in`
-loads, and auth / MCP boundaries behave correctly.
+Media uploads are optional. Configure R2 only when the owner asks for
+staff-managed files; then read
+`node_modules/@aotter/mantle/docs/media-uploads.md`.
 
 ## Handoff
 
-After smoke checks pass, render a short final handoff in the user's
-language:
-
-- Public URL.
-- Admin sign-in URL.
-- Staff MCP URL.
-- Operator setup URL (`https://mantle.tools/connect?site=...`).
-- What changed locally and what was committed.
-- Any intentionally deferred feature / provider setup.
-
-Point future agents at `AGENTS.md`, `.mantle/launch-state.json`, and the
-repo-local `.agent/skills/` directory (`mantle:develop`, `mantle:overlay`,
-`mantle:theme`, `mantle:update`).
-
-## Diagnostics
+Return:
 
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Auth-gated routes return `503 setup_incomplete` | GitHub OAuth + secrets not wired yet | Expected before step 3-4; finish the OAuth App + secrets, then redeploy. |
-| `wrangler secret put` targets the wrong account | Wrangler logged into another Cloudflare account | Re-run `pnpm exec wrangler login` and confirm the account. |
-| GitHub OAuth callback mismatch | OAuth App callback URL is wrong | Set it exactly to `<worker-url>/api/auth/callback/github`. |
-| Owner signs in but admin / MCP returns 403 | `ADMIN_GITHUB_LOGIN` does not match the signed-in GitHub login | Fix the `ADMIN_GITHUB_LOGIN` value and redeploy. |
-| Worker boots but sessions fail after a rerun | `BETTER_AUTH_SECRET` changed or was deleted | Restore the old secret if available; otherwise users must sign in again. |
-| `create_media_upload` is missing from Staff MCP | Optional R2 media is not configured, or `media.purposes` is empty | Only fix this if the owner explicitly wants media uploads; follow `docs/media-uploads.md`. |
-| Upload session works but the PUT to R2 fails from Claude Cowork | Cowork sandbox egress blocks direct R2 uploads | Retry from Claude Code / another non-sandboxed agent. |
+- public URL;
+- admin sign-in URL;
+- Staff MCP URL;
+- operator setup URL:
+  `https://mantle.tools/connect?site=<url-encoded-worker-url>`;
+- remote resources created or reused;
+- auth mode and any intentionally deferred setup.
 
 ## Don't
 
-- Don't ask for a Cloudflare API token in the base first-run path.
-- Don't require R2 media setup in the base first-run path.
-- Don't re-create the repo or re-run the first deploy from the agent;
-  landing owns first provisioning.
-- Don't resurrect `provision:up` / `provision:plan` as a second
-  provisioner; those scripts were retired with v2.
+- Don't create remote resources before the user asks to ship.
+- Don't ask for a Cloudflare API token in the base flow.
 - Don't commit provider secrets.
-- Don't use `127.0.0.1` in OAuth callback examples; use `localhost` locally
-  and the real Worker URL in production.
-- Don't use `/admin/auth/github/callback`; the Better Auth callback path is
+- Don't require R2 for first production.
+- Don't invent a second provision orchestrator.
+- Don't use `/admin/auth/github/callback`; the callback is
   `/api/auth/callback/github`.

package/skills/theme/SKILL.md

@@ -1,11 +1,10 @@
 ---
-name: mantle:theme
+name: theme
 description: Apply brand and visual direction in a Mantle project without depending on starter-owned skill semantics.
-source: "@aotter/mantle"
-sourcePath: skills/theme/SKILL.md
-when_to_invoke: |
-  User wants visual, brand, layout, copy, or UI polish in an existing Mantle project.
-applies_to: mantle@v0.1.0
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/theme/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Mantle Theme

package/skills/update/SKILL.md

@@ -1,11 +1,10 @@
 ---
-name: mantle:update
+name: update
 description: Check a Mantle project for drift against its Core SDK, starter source, or installed plugin lockfiles.
-source: "@aotter/mantle"
-sourcePath: skills/update/SKILL.md
-when_to_invoke: |
-  User asks to update Mantle, compare generated files, refresh starter/vendor output, or inspect marketplace plugin drift.
-applies_to: mantle@v0.1.0
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/update/SKILL.md
+  applies_to: mantle@v0.1.0
 ---
 
 # Mantle Update