@aotter/mantle 0.1.2-alpha.6 → 0.1.2

package/skills/develop/SKILL.md

@@ -17,12 +17,11 @@ docs govern runtime/API behavior.
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
-2. `manifests/site.yaml`, the active adapter config, and `src/auth.ts` when present. If the project is older, check `src/mantleConfig.ts`.
-3. The active `.mantle/overlays/<type>/seed.json`, when present; generated
-   homepages commonly import visible copy and form structure from it.
-4. Optional local context: `.mantle/launch-state.json`, `.mantle/handoff.md`,
-   `.mantle/plugins.json`, `.mantle/plugins.lock.json`, and `.mantle/recipes/`.
-5. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
+2. `manifests/site.yaml`, the active adapter config (`wrangler.jsonc`), and
+   the Worker entry. Custom Auth lives in that entry's `createAuth` factory.
+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
@@ -30,9 +29,14 @@ version; never use `develop` branch docs for a versioned consumer project.
 
 ## Existing Examples
 
-Read installed `docs/handbook/start/project-and-cli.md`, `docs/examples/minimal-worker/`
-and `docs/handbook/examples/commerce-transaction.md` before inventing a pattern. The reference
-consumer is test/documentation, not a Starter or a fixed application shape.
+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
@@ -53,7 +57,8 @@ pnpm validate
 ```
 
 This CLI validates and derives artifacts from application-authored manifests.
-It does not create projects, business schemas or a visitor homepage.
+It does not create projects, business schemas or a visitor homepage. There is
+no `mantle create` / `mantle update` happy path.
 
 ## Core Model
 
@@ -72,11 +77,10 @@ the atoms cannot express the behavior.
 
 ## Content Edits
 
-- If a legacy homepage imports a repo seed, edit it for local/static copy.
-  Otherwise follow the actual frontend content source. Use Admin or Staff MCP
-  for runtime-backed content.
+- 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 the seed/form. Keep public mutation inputs
+  `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
@@ -134,13 +138,20 @@ teaching the project Mantle internals.
 
 ## Auth Composition
 
-Conventional Cloudflare projects declare `MANTLE_AUTH_MODE=hosted` or
-`self-managed`; Core owns that standard Auth composition and rejects partial
-or mixed bindings. Preserve the explicit mode recorded in Worker config
-and any legacy launch state, keep provider secrets out of source, and do not infer a mode
-from whichever credentials happen to be present. A repo with an explicit
-`createMantleWorker({ auth })` override owns that custom composition; follow
-its handoff instead of replacing it with the conventional factory.
+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
 
@@ -213,8 +224,6 @@ cache.
 
 - Keep content models in the configured manifest directory; its immediate
   `.yaml` and `.yml` files are loaded together.
-- Use a generated overlay `seed.json` for the auth-free local first page when
-  it is already imported by `src/web/content/*`.
 - 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.

package/skills/install/SKILL.md

@@ -21,18 +21,53 @@ turn `generate` into implicit scaffolding.
 1. Determine the actual host and required surfaces from the request. Reuse an
    existing application when available; otherwise work in its own directory.
    Do not assume Cloudflare, public HTML or Admin is required. Check Node 22+
-   and pnpm 9+ for these SDK examples.
+   and pnpm 9+ for these SDK examples. A ChatGPT Site is not a conventional
+   Cloudflare Worker deployment; use the installed
+   `docs/handbook/sites/index.md` integration guide and
+   `docs/examples/host-chatgpt-sites/` runnable reference when selected.
 2. Choose the requested exact SDK version, or resolve the intended release
    channel once. Pin all selected `@aotter/mantle*` dependencies to that same
    version. Install only the adapter/optional packages the application needs.
    If a global scope registry overrides public npmjs, use a project-owned
    `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
-3. Read the installed `node_modules/@aotter/mantle/docs/handbook/start/project-and-cli.md`.
-   The version-matched `docs/examples/minimal-worker/` is a runnable Cloudflare
-   reference, not a template to install wholesale. Other hosts use the embedded
-   adapter guides. Author package scripts, manifests, entry and configuration
-   for the user's requirements. No default notes model, home page, icon,
-   launch metadata or frontend is required.
+3. Interview the human for host and required surfaces. Do not assume Admin,
+   public HTML or Cloudflare. Scale:
+   - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
+   - Adapter without Admin — `docs/examples/host-minimal-worker/`.
+   - Opt-in Admin / Dev UI — only when a human needs a console: interview
+     the bootstrap owner email, then `docs/examples/host-local-admin-otp/`
+     (`pnpm install && pnpm generate && pnpm dev`, `/admin/sign-in`, OTP
+     in wrangler logs). Admin needs `@aotter/mantle-admin`,
+     `@aotter/mantle-admin-ui`, wrangler `ASSETS` on `./public`, and
+     `createAuth` email-otp + `ConsoleEmailSender`. Do not Vite-build Admin.
+   - ChatGPT Sites with Admin/D1/R2 — follow
+     `docs/examples/host-chatgpt-sites/`, not the email-OTP Worker example.
+     Copy it outside the SDK checkout, then `npm ci`,
+     `npx mantle validate --phase deploy`, `npm run generate`, `npm run check`,
+     `npx wrangler d1 migrations apply DB --local`,
+     `npm run dev -- --port 4174`, and `npm test` in a second terminal.
+     Preserve its Sites-owned identity ingress and hosting manifest; author the
+     user's Schema/View/Procedure/Trigger, then review migrations, media policy
+     and the local/production smoke gates. Sites provisions and deploys; never
+     `wrangler deploy` a Site. Request both D1 and R2 when uploads are in scope.
+     Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not enable remote staff OAuth MCP.
+   - ChatGPT Sites with custom business rules or an external callback — the
+     runnable reference covers builtin content only. For application-owned
+     operational state, `handler: { kind: ref }` Procedures, staff-only SQL
+     Views, staff MCP Triggers with `requires.auth`, and outbound webhooks
+     called from handler code, follow
+     `docs/handbook/sites/equipment-checkout.md`. It is an implementation
+     guide, not a shipped app: keep Mantle-owned Schema tables and
+     application-owned tables separate, and give every application table a
+     reviewed migration.
+   - Grammar — `docs/examples/README.md`. Copy `builtin-*` Manifests directly.
+     Read `cf-primitives-*` when the request needs Durable Objects, Queues,
+     cron, payment-provider callbacks, or API-key and entitlement guards;
+     those carry `ref` handlers and are not Builder-ingestible.
+   None of these is a template to install wholesale. Other hosts use the
+   embedded adapter guides. Author package scripts, manifests, entry and
+   configuration for the user's requirements. No default notes model, home
+   page, icon, launch metadata or visitor frontend is required.
 4. Compile and verify using the application's commands. The fundamental CLI
    sequence is:
 
@@ -44,10 +79,14 @@ pnpm exec mantle skills
 pnpm exec mantle skills --check
 ```
 
-Run the project's TypeScript check and start its actual local server. Probe a
-route the application declares; an API-only project may correctly return 404
-at `/`. Auth routes may return `503 setup_incomplete` until the selected auth
-provider is configured. Do not introduce an auth bypass to make smoke pass.
+Run the project's TypeScript check and start its actual local server. Probe
+a route the application declares. An API-only or adapter-only project may
+correctly return 404 at `/` and have no Admin. When Admin was requested,
+probe `/admin/sign-in` and a `/_mantle/admin/assets/*` URL — both must be
+200. A white screen is an assets 404, not a missing frontend build.
+Conventional Auth routes may return `503 setup_incomplete` until that mode
+is configured; the local OTP path replaces construction instead. Do not
+introduce an auth bypass to make smoke pass.
 
 Commit the resolved lockfile in the application's normal workflow; subsequent
 installs use `pnpm install --frozen-lockfile`. Do not initialize/push a remote,

package/skills/provision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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: skills/provision/SKILL.md
@@ -12,7 +12,13 @@ metadata:
 # 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.
+user asks to create remote resources or ship production. This flow is for
+consumer-owned Cloudflare Workers. For a ChatGPT Site, use the installed
+`docs/handbook/sites/index.md` integration guide and the "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
 
@@ -59,8 +65,8 @@ directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
 
 ## Choose Auth
 
-- **Self-hosted — free:** configure the owner's per-site GitHub OAuth App and
-  Worker secrets using the steps below.
+- **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:** 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.
@@ -74,7 +80,17 @@ 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
+## 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: