@aotter/mantle 0.0.11-alpha.32 → 0.0.11-alpha.34

package/README.md

@@ -32,12 +32,13 @@ import { mountServerEndpoints } from "@aotter/mantle/cloudflare";
 ## Getting started
 
 Recommended path: open the Mantle landing page, answer the launch
-questions, sign in with GitHub, then paste the generated launch command
-into Claude Code / Cursor / Codex. The short-lived launch session carries
-the scaffold values, so the agent can run `create-mantle launch` first
-and continue with provisioning.
+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.
 
-Available starter keys and direct scaffolder usage live in [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters): `presence`, `publication`, `intake`, `transaction`, and `blank`. See `skills/install` in the [Mantle repo](https://github.com/aotter/mantle/tree/develop/skills/install) for the full agent-driven install flow.
+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. See `skills/install` in the [Mantle repo](https://github.com/aotter/mantle/tree/develop/skills/install) for how the agent continues a provisioned repo.
 
 ## Adapter targets
 

package/docs/adr/0017-media-multi-variant-agent-side-optimization.md

@@ -47,9 +47,9 @@ encode step to where it already runs in a real Node-like runtime:
 - Scaffolders, ops scripts, the admin SPA's local helper, and MCP
   agents (Claude Code, etc.) all execute in environments where
   `sharp` works.
-- A dedicated `@aotter/mantle-media-tools` package ships agent-side
-  CLI + library helpers that take a source file, produce the format
-  set, call `create_media_upload`, upload every variant, and call
+- The MCP client or operator tooling runs the agent-side image
+  processor: take a source file, produce the format set, call
+  `create_media_upload`, upload every variant, and call
   `commit_media_upload`.
 - The Worker only **enforces policy**: required mime set, per-mime
   byte caps, suspicious-shape heuristic (modern format must not be
@@ -178,4 +178,4 @@ use case layer via the repository. The R2 adapter:
 - `packages/mantle-runtime/src/infrastructure/persistence/DatabaseMediaAssetRepository.ts`
 - `packages/mantle-spec/src/domain/model/SiteConfig.ts` (MediaPurposePolicy)
 - `packages/adapters/cloudflare/src/bindings/R2MediaStorage.ts`
-- `mantle-starters/packages/mantle-media-tools/` (agent-side helper)
+- MCP client / operator-side image processing tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.32",
+  "version": "0.0.11-alpha.34",
   "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.32",
-    "@aotter/mantle-runtime": "0.0.11-alpha.32",
-    "@aotter/mantle-spec": "0.0.11-alpha.32",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.32"
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.34",
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.34",
+    "@aotter/mantle-runtime": "0.0.11-alpha.34",
+    "@aotter/mantle-spec": "0.0.11-alpha.34"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.7.0",

package/skills/README.md

@@ -4,10 +4,10 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 
 | Skill | When to invoke |
 |---|---|
-| [`install`](install/SKILL.md) | User wants to start a new mantle project. Preferred path consumes a landing-created launch session and runs the generated `create-mantle` command from the [starters monorepo](https://github.com/aotter/mantle-starters), including any selected source feature overlays. |
+| [`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. |
 | [`customize-design`](customize-design/SKILL.md) | User wants to rebrand or restyle a publication starter project. Walks the L1–L4 theme stack (tokens / extraCss+icons+i18n / Header+Footer / whole-template). |
 | [`extend`](extend/SKILL.md) | User has an existing project and wants to add a Schema / View / Procedure / Trigger or wire a feature (contact form, search, newsletter signup). |
-| [`provision`](provision/SKILL.md) | User wants to deploy to production through starter-owned lifecycle scripts: OAuth verifier swap, secrets, prod D1/KV, custom domain, and explicitly selected feature resources. |
+| [`provision`](provision/SKILL.md) | User wants production fully usable after a landing launch. Verify the Cloudflare deploy, wire per-site staff auth (GitHub OAuth App + Worker secrets), smoke test, and hand off the operator setup URL. |
 
 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.
 

package/skills/install/SKILL.md

@@ -1,26 +1,24 @@
 ---
 name: mantle install
-description: Install a Mantle consumer project from a landing-created launch command/session, then continue into deterministic provision. Use when the user pasted a Mantle launch command or session URL.
+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 has a Mantle landing launch command/session URL and wants a new Mantle site scaffolded.
+  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.
 ---
 
 # mantle install
 
-You are installing a Mantle site for the user. The normal path is:
+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.
 
-1. Mantle landing asks the launch questions.
-2. Landing renders a short-lived launch session and `create-mantle`
-   command.
-3. You run that command from the parent directory where the project
-   should be created.
-4. You validate the generated repo, push it to the user's GitHub, then
-   continue with repo-local `mantle:provision`.
-
-Do not rebuild the old interview harness in chat. If the user has no
-landing-created launch command/session, send them back to Mantle landing
-to create one. Manual flag-by-flag scaffolding is for maintainers
-debugging the scaffolder, not the user-facing install UX.
+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.
 
 ## Ground Truth
 
@@ -39,125 +37,62 @@ consumer project from these four atoms plus user TypeScript. Full grammar
 reference:
 <https://raw.githubusercontent.com/aotter/mantle/develop/docs/design-atoms.md>.
 
-After `create-mantle` runs, the scaffold's ground truth lives in:
+A landing-provisioned repo carries its launch context and ground truth in:
 
 | Path | Contents |
 |---|---|
+| `.mantle/launch-state.json` | Non-secret launch choices: type, purpose, locales, repo, owner, suggested overlay |
+| `.mantle/features.json` | Selected feature overlays and applied state |
+| `.mantle/handoff.md` | The launch handoff note written for you |
 | `manifests/*.yaml` | Schemas / Views / Procedures / Triggers |
 | `src/mantleConfig.ts` | Site defaults, handler registration, runtime bindings |
 | `src/handlers/` | Handler implementations |
-| `src/.mantle/generated.*.ts` | Scaffolder-owned feature glue |
-| `.mantle/features.json` | Selected feature overlays |
-| `.mantle/launch-state.json` | Non-secret launch choices from landing |
 | `AGENTS.md` | Cross-tool agent entry |
+| `.agent/skills/` + `.claude/skills/` | Repo-local skills: `mantle:develop`, `mantle:overlay`, `mantle:theme`, `mantle:update` |
 
-## Accepted Inputs
-
-Use the launch-session fast path when the prompt contains either:
-
-- a command shaped like `npx <tarball> launch --session <url-or-file>`;
-- a command shaped like `npx <tarball> <archetype> ...` generated by
-  Mantle landing;
-- a launch session URL/file plus instructions to run `create-mantle
-  launch`.
-
-Landing already collected the launch-critical values. Treat those values
-as user-authorized for scaffolding. Do not ask content, voice, repo, or
-locale questions again before scaffold.
-
-The launch session/command authorizes only initial scaffold values:
-
-- project name;
-- brand / site name;
-- archetype;
-- theme and selected feature overlays;
-- locales and canonical locale;
-- GitHub owner / admin login;
-- install description and summary.
-
-It does not authorize Cloudflare resources, provider billing, OAuth
-secrets, custom domains, or production deploy.
-
-## Preflight
-
-Run these before creating files:
-
-```bash
-node --version    # need >= 22
-pnpm --version    # need >= 9
-git --version
-```
-
-Confirm the current working directory is the parent directory where the
-new project should appear. If the child project directory already exists,
-stop and ask the user whether to choose another empty directory. Do not
-merge a fresh scaffold into an existing project.
-
-## Scaffold
-
-Run the launch command exactly as supplied. Do not rewrite values. Only
-replace an obvious local file path if the user gave the file out of band.
+## Take Over a Provisioned Repo
 
-Examples:
+The repo was already created and deployed by landing. Continue it:
 
-```bash
-npx <create-mantle-tarball> launch --session <session-url-or-file>
-```
-
-```bash
-npx <create-mantle-tarball> <archetype> \
-  --project-name <project-name> \
-  --brand "<brand>" \
-  --description "<description>" \
-  --locales "<locale[,locale]>" \
-  --github-owner <github-owner> \
-  --admin-github-login <admin-login> \
-  --summary "<summary>"
-```
-
-`create-mantle` validates the session before filesystem writes,
-downloads the requested starter ref, merges `_common/` + `<archetype>/`
-+ feature overlays + theme overlays, fills placeholders, runs
-`git init`, runs `pnpm install`, writes `.mantle/launch-state.json`, and
-prints RUN_NOTES JSON.
-
-After it returns:
-
-1. Read RUN_NOTES.
-2. Read `.mantle/launch-state.json`.
-3. Walk the ground-truth files above.
-4. Continue with local validation.
-
-## Local Validation
-
-From the generated project root:
+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:
 
 ```bash
+pnpm install --frozen-lockfile
 pnpm validate
 pnpm typecheck
-if node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)"; then
-  pnpm test
-else
-  echo "No pnpm test script; skipping."
-fi
-```
-
-Run deploy validation if the starter exposes it:
-
-```bash
-if node -e "process.exit(require('./package.json').scripts?.['validate:deploy'] ? 0 : 1)"; then
-  pnpm validate:deploy
-else
-  pnpm validate --phase deploy
-fi
 ```
 
 Diagnostics are structured JSON with `code` and `suggestion` fields.
 Surface both verbatim when validation fails.
 
+## Continue With Repo-Local Skills
+
+The generated repo ships its own skills under `.agent/skills/` and
+`.claude/skills/`. Hand off to the one that fits the work:
+
+- **`mantle:overlay`** — apply the selected launch type as a small
+  post-launch overlay (first useful pages plus tiny seed data in the
+  user's language). This is the usual first step on a fresh blank launch.
+- **`mantle:develop`** — manifest, runtime, content-model, layout,
+  bug-fix, and validation work on the site.
+- **`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.
+
+Remove the placeholder blank homepage once the selected type ships a real
+homepage.
+
 ## Local Preview
 
-If the user wants to see the scaffold locally:
+To see the site locally before pushing:
 
 ```bash
 [ -f .dev.vars.example ] && cp .dev.vars.example .dev.vars
@@ -165,64 +100,28 @@ openssl rand -hex 32
 pnpm dev
 ```
 
-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.
+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.
 
-A fresh scaffold may legitimately return 404 for the public home route
-because production content is not seeded yet. Treat that as an empty-site
-state, not a failed install, when validation and admin routes are alive.
+## Production
 
-## Provision Handoff
-
-Commit the deterministic scaffold:
-
-```bash
-git status --short
-git add .
-git commit -m "mantle: deterministic scaffold"
-```
-
-Then continue in the same conversation with the repo-local provision
+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:
-
-```text
-.agent/skills/mantle-provision/SKILL.md
-```
-
-The current provision shape is provider-first:
-
-1. The agent creates/pushes the user's private GitHub repo.
-2. The user creates the first Cloudflare Worker deploy from that GitHub
-   repo in Cloudflare Dashboard.
-3. The user reports the Worker URL.
-4. The user creates the per-site GitHub OAuth App.
-5. The agent runs `pnpm run provision:up` to write non-secret config,
-   set Worker secrets with Wrangler, commit, push, redeploy, and smoke
-   test.
-
-Do not stop at "here is a URL". Walk the provider steps with the user
-until the deployed Worker, GitHub owner sign-in, and Staff MCP endpoint
-are verified.
-
-## Small Adjustments
-
-Before provision, only make small deterministic edits that come directly
-from the landing answers or the user's explicit request:
-
-- delete an unused manifest;
-- add one clearly requested field to an existing Schema;
-- correct site defaults in `src/mantleConfig.ts`;
-- fix a typo in `AGENTS.md`.
-
-Run `pnpm validate` after every edit. Route larger feature work to
-`mantle:development` after production provision.
+<https://raw.githubusercontent.com/aotter/mantle/develop/skills/provision/SKILL.md>.
 
 ## Don't
 
-- Don't resurrect the manual interview / prompt-composition harness.
-- Don't block first deploy on polishing prose or writing a site letter.
-- Don't ask for a Cloudflare API token in the base first-run path.
+- 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 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 `127.0.0.1` in OAuth callback examples; use `localhost` locally
+  and the real Worker URL in production.

package/skills/provision/SKILL.md

@@ -1,174 +1,128 @@
 ---
 name: mantle provision
-description: Finish production deployment for an installed Mantle consumer project. Use after the install skill has produced a standalone project and the user wants the service online through their own GitHub and Cloudflare accounts.
+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: |
-  Project exists, `pnpm validate` + `pnpm typecheck` pass, the scaffold is ready to push to GitHub, and the user wants a production Cloudflare Worker.
+  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
 ---
 
 # Provision a Mantle Project
 
-You're taking an installed consumer project from local files to a
-user-owned GitHub repo and Cloudflare Worker.
+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 base flow is deterministic first, provider-browser second:
+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.
 
-1. The coding agent validates the scaffold and pushes a private GitHub
-   repo.
-2. The user creates the first Cloudflare Worker deploy from that GitHub
-   repo in Cloudflare Dashboard. Cloudflare owns automatic first-deploy
-   resource provisioning for id-less bindings.
-3. The user reports the deployed Worker URL back to the agent.
-4. The user creates the per-site GitHub OAuth App.
-5. The agent runs `pnpm run provision:up` to write non-secret config,
-   set Worker secrets through Wrangler, and update local handoff files.
-
-Mantle landing is not the executor. It provides launch context and a
-handoff; provider authority stays with the user and their coding agent.
-
-Do deterministic work before interrupting the user. When provider UI is
-required, give one exact browser task at a time: link, button path,
-expected result, and what value the user should report back.
+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
 
-- The scaffold is committed and pushed to the user's private GitHub repo.
-- Cloudflare has deployed the Worker from that repo at least once.
-- `wrangler.toml` contains `PUBLIC_ORIGIN`, `GITHUB_CLIENT_ID`,
+- 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 optional feature/provider secrets.
+- 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 are ready to test.
-- Operator setup URL is ready to hand to the owner:
+- 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.
+Provision does not seed production content. First real content is created
+after owner sign-in through Staff MCP / admin authoring.
 
 ## Principles
 
-1. Use the user's accounts. The repo belongs to the user's GitHub
-   account or org. The Worker belongs to the user's Cloudflare account.
-2. Do not ask for a Cloudflare API token in the base flow. Cloudflare
-   Dashboard plus Workers Builds handle the first deploy; Wrangler
-   handles secrets after the user logs in.
+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, archetype, theme,
-   and selected features. It does not authorize Cloudflare operations,
-   billing-gated features, OAuth secrets, or custom domains.
-5. `BETTER_AUTH_SECRET` is load-bearing. Preserve an existing secret;
-   rotating it invalidates sessions.
+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. Preflight:
+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:
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm validate
 pnpm typecheck
-if node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)"; then
-  pnpm test
-else
-  echo "No pnpm test script; skipping."
-fi
 git status --short
-gh auth status
-```
-
-If GitHub CLI auth is missing or points at the wrong login, pause and
-ask the user to switch/login before creating the repo.
-
-2. Create a private GitHub repo in the selected owner, add the remote,
-   commit the scaffold, and push. Use the user's GitHub auth context.
-
-3. Print the deterministic browser plan:
-
-```bash
-pnpm run provision:plan
-```
-
-4. Hand the user directly to Cloudflare's Git import path:
-
-```text
-https://dash.cloudflare.com/?to=%2F%3Aaccount%2Fworkers-and-pages
 ```
 
-Ask them to create a Worker from the pushed GitHub repo, keep the Worker
-name equal to `wrangler.toml` `name`, wait for deploy, and send back the
-live `*.workers.dev` URL. Ask for the Worker name only if Cloudflare
-forced a name different from the repo/project name.
-
-5. After the Worker URL is known, print the worker-specific plan:
-
-```bash
-pnpm run provision:plan -- --worker-url <worker-url>
-```
-
-Read only the values needed for the current project. Do not dump
-internal notes or placeholder syntax onto a non-coder.
-
-6. Ask the user to create the per-site GitHub OAuth App after the Worker
+3. Ask the user to create the per-site GitHub OAuth App once the Worker
    URL is known:
 
 - 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.
+Ask for the Client ID in chat. Keep the Client Secret out of chat and pass
+it through the hidden shell prompt below.
 
-7. Authorize Wrangler and apply provision:
+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`:
 
 ```bash
 pnpm exec wrangler login
-read -rsp "GitHub OAuth client secret: " GITHUB_CLIENT_SECRET && export GITHUB_CLIENT_SECRET && printf "\n"
-pnpm run provision:up -- --worker-url <worker-url> --github-username <gh-login> --client-id <client-id>
+read -rsp "GitHub OAuth client secret: " GITHUB_CLIENT_SECRET && printf "\n"
+printf '%s' "$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
 ```
 
-8. Commit and push generated non-secret outputs:
+Set `BETTER_AUTH_SECRET` only on the first run; reuse the existing value on
+later runs.
+
+5. Commit and push the non-secret config so Cloudflare CI redeploys:
 
 ```bash
-git status --short -- wrangler.toml src/mantleConfig.ts AGENTS.md
-git add wrangler.toml src/mantleConfig.ts AGENTS.md
+git add wrangler.toml AGENTS.md
 git commit -m "mantle: wire production provision"
 git push
 ```
 
-Wait for Cloudflare Workers Builds to redeploy from the pushed commit. If
-the dashboard build is unavailable, run `pnpm deploy` from this repo as a
-fallback and explain that fallback to the user.
+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.
 
-9. Smoke test:
+6. Smoke test:
 
 - public home route;
 - `/admin/sign-in`;
 - GitHub admin sign-in;
 - `/mcp/staff` with an agent client when available;
-- a starter-specific core workflow.
+- a 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.
-
-## Feature Overlays
-
-If `.mantle/features.json` lists features, run the repo-local feature
-overlay skill first:
-
-```text
-.agent/skills/mantle-feature-overlays/SKILL.md
-```
-
-Feature scripts are starter lifecycle scripts, not Mantle CLI commands.
-Run them only when the feature is present and the user accepts any extra
-provider/billing requirement.
+loads, and auth / MCP boundaries behave correctly.
 
 ## Handoff
 
@@ -180,28 +134,31 @@ language:
 - Staff MCP URL.
 - Operator setup URL (`https://mantle.tools/connect?site=...`).
 - What changed locally and what was committed.
-- Any intentionally deferred feature setup.
+- Any intentionally deferred feature / provider setup.
 
 Point future agents at `AGENTS.md`, `.mantle/launch-state.json`, and the
-repo-local `.agent/skills/` directory.
+repo-local `.agent/skills/` directory (`mantle:develop`, `mantle:overlay`,
+`mantle:theme`, `mantle:update`).
 
 ## Diagnostics
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| Cloudflare first deploy cannot infer a binding | Starter uses a resource Dashboard cannot auto-create | Follow `provision:plan` notes, then redeploy. |
-| `provision:up` cannot infer Worker name | Custom domain or non-workers.dev URL | Add `--worker-name <cloudflare-worker-name>`. |
-| `wrangler secret put` targets wrong account | Wrangler logged into another Cloudflare account | Re-run `pnpm exec wrangler login` and confirm account. |
+| 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 signed-in GitHub login | Re-run `provision:up` with the correct `--github-username`, or update the secret. |
-| Worker boots but sessions fail after rerun | `BETTER_AUTH_SECRET` changed or was deleted | Restore the old secret if available; otherwise users must sign in again. |
+| 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. |
 
 ## Don't
 
 - Don't ask for a Cloudflare API token in the base first-run path.
-- Don't create Cloudflare resources from Mantle landing.
+- 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 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 `/api/auth/callback/github`.
+- 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
+  `/api/auth/callback/github`.