@aotter/mantle 0.1.3-alpha.6 → 0.1.4

package/docs/skills/develop/SKILL.md

@@ -0,0 +1,250 @@
+---
+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.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/develop/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Develop
+
+This is the Core workflow skill for an existing Mantle project. Repo-local
+copies are byte-for-byte projections from the installed package; its embedded
+docs govern runtime/API behavior.
+
+## First Read
+
+1. `package.json` for the installed `@aotter/mantle*` versions.
+2. The manifest directory selected by the project scripts, the actual host
+   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
+   Read custom Auth construction there when present.
+3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
+   and `.mantle/recipes/`. Legacy launch/handoff files are context only.
+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. Remote docs must use a tag matching the installed
+version; never use `develop` branch docs for a versioned consumer project.
+
+## Existing Examples
+
+Read installed `docs/handbook/start/project-and-cli.md` and
+`docs/examples/README.md`. Use `docs/examples/host-minimal-worker/` for Spec +
+adapter without Admin. Read `docs/examples/host-local-admin-otp/` only when the
+project already has Admin or the human asked for Dev UI — that path is opt-in.
+Ingest only `docs/examples/builtin-*.md` Manifests as grammar for new domains.
+Read `docs/examples/cf-primitives-*.md` before inventing Durable Object, Queue,
+cron, or `ref` handler patterns.
+References are test/documentation, not a Starter or a fixed application shape.
+
+Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
+`TemplateRegistry`, and a matching `publicPathResolver` must agree on the
+exposed collections. Do not auto-publish every Schema. Applications document their mounted URL surface in their own README.
+Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
+not install public rendering by itself.
+
+## Authoring CLI
+
+Use the project's scripts first; applications use the shipping
+`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
+command list instead of trusting one copied into prose — the surface is
+version-matched and changes between releases:
+
+```bash
+pnpm exec mantle --help
+pnpm validate
+```
+
+This CLI validates and derives artifacts from application-authored manifests.
+It does not create projects, business schemas or a visitor homepage. There is
+no `mantle create` / `mantle update` happy path.
+
+## Core Model
+
+Mantle exposes exactly four declarative atoms:
+
+| Atom | Purpose |
+|---|---|
+| `Schema` | Stored entity/table shape. |
+| `View` | Read/query surface. |
+| `Procedure` | Typed mutation or operation. |
+| `Trigger` | HTTP/lifecycle/MCP invocation binding. |
+
+Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
+`Membership`. Compose those from the four atoms plus TypeScript only where
+the atoms cannot express the behavior.
+
+## Choose the manifest feature first
+
+Read installed `docs/handbook/reference/features.md` to map the requested
+behavior to fields before adding handlers or a custom UI. For host-only reads,
+`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
+`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
+View params/results, indexed entry reads, and their authorization boundary.
+Use `from` for portable typed projections; SQL is for queries needing native
+SQLite and produces `unknown` row types.
+
+For Admin labels, inputs, collection columns/tabs, reports or action buttons,
+read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
+metadata and `uiSchema` before custom frontend code. These control the Admin
+console, not the visitor frontend. Regenerate and verify the actual console;
+never edit generated `public/_mantle/admin/` assets.
+
+## Content Edits
+
+- Follow the actual frontend content source. Use Admin or Staff MCP for
+  runtime-backed content. Do not invent an overlay/seed homepage.
+- For a new submitted field, update the stored `Schema` and the public
+  `Procedure.spec.input` before any form UI. Keep public mutation inputs
+  `additionalProperties: false`; otherwise JSON Schema's default may strip an
+  undeclared field while returning success.
+- Use `lifecycle: operational` for submissions, inquiries, orders, and other
+  Procedure-created operational records that staff inspect or correct. Reserve
+  `publishing` for content a person stages and publishes.
+- Lifecycle `before_update` / `after_update` hooks also fire for unpublish,
+  archive, and every other status transition whose target is not `published`;
+  do not use them for edit-only work.
+- When a form's fixed option values change, update the stored Schema and public
+  Procedure input `enum` together. Keep translated labels in the frontend content source;
+  Admin and Staff MCP derive their typed controls from the manifest values.
+- If the application has a `page` Schema with sections, update its declared
+  section properties when adding display fields; an undeclared property has no
+  runtime-backed Admin or Staff MCP path.
+- Update notification handlers when they need the new field. Test the stored
+  entry, not only the HTTP `{ "ok": true }` response.
+
+## Locales
+
+- `data.locale` is reserved for `localized: true` Schemas. A non-localized
+  Schema must use a domain field such as `replyLocale`.
+- Use a standalone localized Schema only for independent locale rows. For
+  versions of one entity, use a non-localized parent plus a localized child
+  with `translates: { parent, on }`. The child must own at least one field
+  besides `locale` and the join field.
+- Parallel locale blocks must keep field names, option values, step IDs, and
+  result keys identical; translate display strings only.
+- `siteDefaults.origin`, `siteDefaults.locales`, and `siteDefaults.icons` are
+  code-owned and boot-synced. The icon list is shared by browser favicons,
+  Admin chrome, and MCP `serverInfo.icons`; keep its static files under
+  `public/`. Brand, title, and description seed once, then change through site
+  settings.
+- When changing an existing collection from `[slug]` to `[slug, locale]`,
+  boot with a Mantle version that reconciles obsolete unique indexes and test
+  the same slug in two locales. Do not patch D1 manually.
+
+## Adapter Boundary
+
+The runtime is adapter-neutral. A `MantleStorageAdapter` prepares the compiled
+plan into semantic storage ports; `createMantleRuntime` binds that prepared
+storage and selected capabilities. Database drivers and asset serving belong
+to the host/optional composition. Follow the installed adapter guide.
+
+Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
+or its adapter config is visible. A future Netlify adapter should satisfy the
+same Core workflow through its own ports and provider setup.
+
+Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
+`runtime.entries`, and optional `runtime.siteConfig`; do not query Mantle-owned `entries` or
+`site_config`, reach through deprecated `runtime.db`, copy generated-column
+names, or construct SDK KV keys. Cloudflare bindings belong only at the
+composition root. If a normal feature cannot be expressed through a
+purpose-shaped surface, treat that as a Core abstraction gap instead of
+teaching the project Mantle internals.
+
+## Auth Composition
+
+Admin is opt-in. A project without `@aotter/mantle-admin-ui` is complete.
+When Admin is installed, `createMantleWorker({ auth })` with `email-otp`
+and `ConsoleEmailSender` is the local human path (OTP in wrangler logs).
+That override owns Auth construction; Core still owns `/admin` and
+`/api/auth/*`. Admin also requires wrangler `assets.directory=./public`
+and an `ASSETS` binding. A white screen at `/admin` with HTML 200 and
+`/_mantle/admin/assets/*` 404 is a missing assets binding, not a missing
+frontend build.
+
+Conventional Cloudflare projects that do not replace Auth declare
+`MANTLE_AUTH_MODE=hosted` or `self-managed`; Core owns that standard
+composition and rejects partial or mixed bindings. Preserve the explicit
+mode recorded in Worker config, keep provider secrets out of source, and
+do not infer a mode from whichever credentials happen to be present.
+
+## Performance Loop
+
+After changing a Schema index, View filter/order, public API, or rendered page,
+run the project's index check when present. Otherwise run the installed
+harness directly:
+
+```bash
+pnpm exec mantle-harness indexes --require-public --format text
+```
+
+The check uses crowded real SQLite and the shipped compiler. It complements
+`pnpm validate`; it does not replace correctness validation. Declare the
+smallest ordered index justified by the measured path and respect SQLite's
+leftmost-prefix rule; which columns an index may name and how a public View's
+status predicate shapes it is in the handbook (`reference/schema.md#indexes`).
+Do not change user-visible filter or ordering semantics
+just to make the gate pass. Do not add every permutation or cache every read.
+
+For relevant Cloudflare serving changes, start the project and sample the
+actual routes:
+
+```bash
+pnpm exec mantle-harness http \
+  --base-url http://127.0.0.1:8787 \
+  --route page=/en/example \
+  --rounds 20 --warmup 2 --format text
+```
+
+Prefer query plan, query count, `rows_read` scaling, and cache MISS/HIT
+evidence. Do not create CI gates from absolute local milliseconds.
+
+## Loop
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm check:indexes # when the project provides it
+pnpm typecheck
+pnpm check
+```
+
+Use `pnpm dev` for local preview when the project provides it.
+
+## Connect a Local MCP Client
+
+Start the project with `pnpm dev`, then use the exact local origin it prints.
+The conventional Cloudflare adapter exposes:
+
+- `http://localhost:8787/mcp` for public tools;
+- `http://localhost:8787/mcp/staff` for authenticated authoring tools.
+
+Prefer the client's native remote HTTP + OAuth support. Use a standard
+HTTP-to-stdio bridge such as `npx -y mcp-remote <url>` only when the client
+accepts stdio MCP servers but cannot connect to remote HTTP directly. Mantle
+does not own a separate local proxy or an auth-bypass mode.
+
+Before changing client config, confirm the Worker is reachable:
+
+```bash
+curl -i http://localhost:8787/mcp
+```
+
+An OAuth-protected endpoint should respond with `401` and a
+`WWW-Authenticate` resource-metadata challenge before sign-in. After
+connecting, inspect `tools/list`; make one read-only `query_view_*` call when
+available before invoking any mutation. Use project-scoped client config when
+the client offers it, and never commit OAuth tokens or the bridge's token
+cache.
+
+## Rules
+
+- Keep content models in the configured manifest directory; its immediate
+  `.yaml` and `.yml` files are loaded together.
+- Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.
+- Do not write directly to D1, KV, Postgres, or object storage for content
+  authoring. Use runtime use cases, admin APIs, or Staff MCP.
+- Do not commit provider secrets.
+- If the work is an installable capability, switch to `mantle:plugin`.

package/docs/skills/media-gc/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: media-gc
+description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/media-gc/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: package
+  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
+---
+
+# Mantle Media GC
+
+Use the connected Cloudflare API. Audit by default; delete only the exact
+objects approved by the user.
+
+## Preflight
+
+1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
+   binding, bucket name, and declared public media purpose names.
+2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
+   ask; never choose by name similarity.
+3. Use the Cloudflare OpenAPI search before execution to resolve the current
+   R2 List Objects and Delete Objects endpoints. If the connected account lacks
+   access, stop. Do not create, request, or store credentials.
+4. Stop when the project has no public R2 media binding or no declared purpose.
+
+## Audit
+
+For each declared purpose, list up to 1,000 objects per page under the exact
+`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+
+An object is a deletion candidate only when all conditions hold:
+
+- `last_modified` is more than 24 hours old;
+- `custom_metadata.committedAt` is absent or empty;
+- the key matches the exact Mantle layout
+  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+  where `<purpose>` is declared by this project and `<group>` contains only
+  letters, digits, `_`, or `-`.
+
+Skip committed, unknown-prefix, unprefixed, malformed, or ambiguous objects.
+Delete only an uncommitted variant, never its whole group.
+
+Report the account, bucket, purpose prefixes, UTC cutoff, candidate object and
+group counts, total bytes, skipped count, and a SHA-256 digest of the sorted
+`key + etag` candidate set. Do not print object keys, upload group IDs,
+filenames, public URLs, signed URLs, or secrets.
+
+## Apply
+
+1. Show the audit summary and get explicit confirmation for that exact account,
+   bucket, cutoff, count, byte total, and candidate-set digest.
+2. Re-run the complete audit with the same UTC cutoff. If the candidate count,
+   bytes, or digest changed, stop and present the new audit for confirmation.
+3. Call Delete Objects with JSON arrays of exact keys, at most 1,000 keys per
+   request. Never send the `prefix` query parameter: an empty prefix can empty
+   the bucket.
+4. Do not automatically retry failed keys. Report safe API error codes and
+   counts; a later invocation can audit and retry what remains.
+5. Re-list every inspected purpose prefix and report the remaining candidate
+   count and bytes.
+
+## Don't
+
+- Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
+- Don't use prefix deletion or empty-bucket operations.
+- Don't delete private-media buckets or objects outside declared purpose
+  prefixes.
+- Don't treat missing pagination pages, metadata, or permissions as an empty
+  result.
+
+## Diagnostics
+
+| Symptom | Action |
+|---|---|
+| Multiple matching accounts or buckets | Stop and ask the user to select the exact target. |
+| A page is truncated without a cursor | Stop; do not delete from a partial audit. |
+| A candidate has an unexpected key or metadata shape | Skip it and include it only in the aggregate skipped count. |
+| A delete request partially fails | Report safe error codes and leave the remaining objects for a later audit. |
+
+## When You're Done
+
+Return whether the run was audit-only or applied, the aggregate before/after
+counts and bytes, and any safely redacted failures.

package/docs/skills/plugin/SKILL.md

@@ -0,0 +1,132 @@
+---
+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.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/plugin/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Plugin
+
+Mantle plugins are Core SDK capability packages. They are not application
+scaffolds (retired in ADR-0021) and they are not provider provisioning scripts.
+
+A plugin may contribute:
+
+- manifests: `Schema`, `View`, `Procedure`, `Trigger`;
+- handler source or handler registration notes;
+- site defaults or media policy additions;
+- expected HTTP, admin, and MCP surfaces;
+- adapter capability requirements and provider setup notes.
+
+## User Install Entry
+
+The user-facing install path is:
+
+```txt
+Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
+Use repo-local mantle:plugin to update <plugin id> in this repo.
+Use repo-local mantle:plugin to remove <plugin id> from this repo.
+```
+
+There is no `mantle plugin add` CLI yet. Do not invent one. Install from a
+marketplace entry, plugin package, or recipe URL that declares enough data for
+an agent to apply the capability deterministically.
+
+A valid marketplace entry must include:
+
+- plugin id, title, source, and version;
+- supported Mantle version range;
+- files, manifests, handlers, routes, MCP tools, and admin surfaces it adds;
+- adapter capabilities and provider resources it requires;
+- required env vars and secrets, without secret values;
+- verification commands and expected surfaces.
+
+If the marketplace page is only marketing copy or lacks an install recipe,
+stop and ask for the recipe instead of guessing.
+
+## First Read
+
+1. `package.json` for Mantle version and adapter package.
+2. The manifest directory selected by project scripts for current atom names
+   and route/tool collisions.
+3. The actual host entry and its handler, template and port registrations;
+   `src/mantle/config.ts` and `src/mantle/handlers/` are conventions, not required paths.
+4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
+5. `.mantle/launch-state.json` only as context, not as plugin authority.
+
+Read version-matched contracts under `node_modules/@aotter/mantle/docs/`,
+starting with `handbook/reference/features.md`. Plugin recipes cannot override
+the installed grammar.
+
+## Plan First
+
+Before applying any plugin, produce a plan:
+
+- files to add or change;
+- atoms to add and their names;
+- HTTP routes and MCP tools that will appear;
+- required runtime ports;
+- adapter-specific resources, env vars, and secrets;
+- checks to run.
+
+If the plugin needs a capability the current adapter does not expose, stop
+with the missing capability instead of inventing provider steps.
+
+## Apply
+
+Apply the smallest deterministic diff. Do not run arbitrary install scripts
+from a plugin package. Copy declared files, wire declared handlers, update the
+plugin ledger, then validate.
+
+Suggested ledger paths:
+
+```txt
+.mantle/plugins.json
+.mantle/plugins.lock.json
+```
+
+Keep optional legacy launch files such as `.mantle/features.json` separate from
+plugin state. They are not the Core plugin ledger.
+
+## Update
+
+Compare the installed lock entry against the marketplace entry or recipe URL.
+Apply only the declared version diff, update `.mantle/plugins.lock.json`, then
+run the same verification checks.
+
+## Remove
+
+Use the lock entry as the removal manifest. Delete only files and atoms owned
+by that plugin, unwind handler registrations it added, remove its ledger entry,
+then validate. If another plugin or local code depends on a removed atom, stop
+and report the dependency instead of deleting through it.
+
+## Verify
+
+Use the project's validation and typecheck scripts when present. Regenerate
+the plan after manifest changes before probing the running host:
+
+```bash
+pnpm exec mantle validate
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+# Run the project's TypeScript check and restart its local server.
+```
+
+Then verify the plugin's declared surfaces:
+
+- public Views via `GET /api/views/<name>`, staff Views via authenticated
+  Admin/staff MCP, and internal Views through the host binding;
+- HTTP Trigger path for public writes;
+- Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
+- adapter resource presence when the plugin requires optional ports.
+
+## Don't
+
+- Don't treat an application template as a plugin.
+- Don't assume Cloudflare; inspect the active adapter and capability ports.
+- Don't create a second skill namespace for host-specific plugins.
+- Don't commit secrets. Provider secrets stay in the platform secret store.

package/docs/skills/provision/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: provision
+description: Ship a Mantle project through its selected host, routing ChatGPT Sites to its integration guide and conventional Cloudflare Workers to production auth and provisioning.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/provision/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: package
+  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
+---
+
+# Provision a Mantle Project
+
+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. New direct-authored apps do not need Landing
+artifacts (`.mantle/launch-state.json`, `.mantle/handoff.md`, or a hosted-auth
+allocation). Treat any Landing handoff as **legacy/optional**. For a ChatGPT
+Site, use the installed `docs/handbook/chatgpt-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
+
+1. Read the actual provider config (`wrangler.jsonc` or `wrangler.toml`),
+   application entry and git remotes. Read legacy `.mantle/launch-state.json`
+   and `.mantle/handoff.md` only when present; they are optional leftovers from
+   Landing and must not be created as prerequisites for a new app.
+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
+pnpm validate
+pnpm typecheck
+git status --short
+```
+
+## 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.
+Do not recreate Landing artifacts for a new direct-authored app. Workers Builds
+is optional after a direct deploy.
+
+When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
+provider's OAuth callback together, then redeploy. Do not patch `site_config`
+directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
+
+## Choose Auth
+
+- **Self-hosted email OTP:** use the application's production transactional-email sender. Replace `ConsoleEmailSender`; never deploy it.
+- **Self-hosted GitHub OAuth — free fallback:** use when the application has no email provider. Configure the owner's per-site GitHub OAuth App and Worker secrets using the steps below.
+- **Mantle hosted auth — paid, legacy/optional:** use only when a **legacy
+  Landing handoff** already records a hosted allocation and client
+  configuration. New direct-authored apps do not get this from Core. Mantle
+  Platform operates the identity provider; do not ask the user for a per-site
+  GitHub OAuth App.
+
+Configure only the selected mode. Core deliberately rejects partial or mixed
+hosted/self-managed bindings with `503 setup_incomplete`.
+
+Do not claim that hosted auth can attach to an arbitrary local repo unless a
+legacy Landing handoff already supplies that configuration.
+
+For the exact boundary, read
+`node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
+
+## Self-hosted email OTP
+
+Keep the application's custom `createAuth()` factory, replace
+`ConsoleEmailSender` with its production `EmailSender`, and retain
+`bootstrapOwner: { match: "email", value: <owner email> }`. Store sender
+credentials and `BETTER_AUTH_SECRET` as Worker secrets, put `PUBLIC_ORIGIN` in
+non-secret vars, deploy, then verify that the owner receives an OTP at
+`/admin/sign-in`. If there is no production email provider, use GitHub OAuth
+below instead of deploying console delivery.
+
+## Self-hosted GitHub OAuth
+
+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
+
+2. Put non-secret values in `wrangler.toml`:
+
+- `MANTLE_AUTH_MODE = "self-managed"`
+- `PUBLIC_ORIGIN`
+- `GITHUB_CLIENT_ID`
+- `ADMIN_GITHUB_LOGIN`
+- correct Worker `name`
+
+Remove `MANTLE_HOSTED_AUTH_ISSUER` and `MANTLE_HOSTED_AUTH_CLIENT_ID` if they
+were present for a hosted allocation.
+
+3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
+   secrets; otherwise use hidden shell input:
+
+```bash
+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 MANTLE_GITHUB_CLIENT_SECRET
+```
+
+Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
+sessions.
+
+4. Commit and push only non-secret config, then redeploy:
+
+```bash
+git add wrangler.toml AGENTS.md
+git commit -m "mantle: wire production auth"
+git push
+pnpm deploy
+```
+
+## Hosted Auth (legacy Landing)
+
+Skip this section unless a legacy Landing handoff is already present. New
+direct-authored apps use self-hosted email OTP or GitHub OAuth above.
+
+Follow that handoff and its client configuration. Hosted configuration remains
+in landing-managed Cloudflare Worker bindings. Verify:
+
+- `MANTLE_AUTH_MODE = "hosted"`;
+- `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;
+- `MANTLE_HOSTED_AUTH_CLIENT_ID` is the same-origin `/clients/<id>` URL;
+- `PUBLIC_ORIGIN` and `ADMIN_GITHUB_LOGIN` are set;
+- `BETTER_AUTH_SECRET` exists as a Worker secret;
+- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are absent.
+
+Hosted clients use PKCE and have no client secret. Do not write secrets into
+`wrangler.toml`.
+
+Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
+authenticates, then skip the self-hosted flow.
+
+## Smoke Test
+
+- public home route;
+- `/admin/sign-in`;
+- selected admin sign-in path;
+- `/mcp/staff` with an agent client when available;
+- one type-specific core workflow.
+
+Media uploads are optional. Configure R2 only when the owner asks for
+staff-managed files; then read
+`node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md`.
+
+## Handoff
+
+Return:
+
+- 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 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 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`.