@aotter/mantle 0.1.3 → 0.1.5-alpha.1

package/docs/handbook/start/project-and-cli.md

@@ -1,140 +1,124 @@
 ---
-description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and version pins.
+description: Generate a full Mantle app or select smaller modules, then safely rerun the CLI as your manifests evolve.
 ---
-# Project layout and the CLI loop
+# Project layout and CLI
 
-This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
+`mantle generate` can assemble a new application or compile manifests in an
+existing one. A new hosted app defaults to Spec, Runtime, API, MCP, Admin and
+an editable blank home. You can select a smaller set explicitly. It never
+invents a business Schema or publishes a deployment.
 
-Agents can bootstrap with the install skill; human authors can follow this guide directly. For installation paths and the pinned-package handoff, see [Agent setup](../guides/agent-setup.md):
+## Start a new app
 
-```sh
-npx skills add aotter/mantle --skill install
-```
-
-## You own the project
-
-Core is a manifest compiler and a runtime, not a project generator. You write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
-
-```txt
-my-service/
-├── package.json              exact-pinned @aotter/mantle* + peers, scripts
-├── tsconfig.json             includes src/ and .mantle/generated/
-├── wrangler.jsonc            Worker name, flags, vars, bindings
-├── .dev.vars                 local secrets for wrangler dev; never committed
-├── manifests/
-│   └── site.yaml             immediate .yaml/.yml files; multi-document with ---
-├── src/
-│   ├── index.ts              createMantleWorker({ plan, extend })
-│   └── mantle/handlers/      handler refs (a convention; any path under src/)
-├── public/                   required ASSETS root when Admin is installed; generate writes public/_mantle/admin/
-├── .mantle/generated/
-│   └── mantle.ts             written by mantle generate
-├── .agents/skills/mantle-*/  written by mantle skills
-└── .claude/skills/mantle-*/  same bytes, for Claude compatibility
-```
-
-The minimal Worker reference keeps `.mantle/`, `.agents/`, `.claude/`, `.wrangler/`, `.dev.vars*` and `.env*` out of git and regenerates the first three in its `check` script. Committing the generated files is also workable, because `generate --check` and `skills --check` detect drift either way. Commit the lockfile in a real application and install with `--frozen-lockfile` afterwards.
-
-`mantle validate` greps `./src` for the names of `handler.kind: ref` Procedures; a handler that is not found anywhere under `src/` produces a `HANDLER_NOT_REGISTERED` warning, so keep handlers under that root or pass `--source`.
-
-## The CLI
-
-The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones. Bare `mantle` / `mantle --help` prints a layered overview of optional surfaces (Minimal Spec + generate, Runtime / adapter, opt-in Admin). `generate --help` and `validate --help` stay on the compile path. After a successful `generate`, the CLI says Admin is opt-in: next steps when `@aotter/mantle-admin-ui` is installed, otherwise an API-only tip.
-
-| Command | Flags | Does |
-|---|---|---|
-| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check` | Validate, link and compile manifests; write `mantle.ts`; sync Admin assets when installed. `--check` exits 1 without writing when output is stale. |
-| `mantle validate` | `--manifests <dir>`, `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text`, `--json` | Static manifest and handler-source validation. Exit 0 with warnings allowed, 1 on any error, 2 on a CLI invocation problem. |
-| `mantle skills` | `--check` | Copy every skill marked `projection: project` into `.agents/skills/mantle-<name>/` and `.claude/skills/mantle-<name>/`. `--check` exits 1 when a projection is stale. |
-| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>` | Emit OpenAPI 3.1 for HTTP Triggers and `GET /api/views/<name>` routes to stdout or a file. MCP is out of scope. |
-| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>` (default 2000), `--require <view>` (repeatable), `--require-public`, `--format text\|json` | Execute compiled Views in crowded SQLite and inspect query plans; exit 1 when a required View lacks its access path. |
-| `mantle-harness http` | `--base-url <url>`, `--route <name=path-or-url>` (repeatable, required), `--rounds <n>` (default 20), `--warmup <n>` (default 2), `--format text\|json` | Sample a running Worker and report p50/p95 timings plus query-count and `rows_read` metric headers. |
-
-Advanced manifest primitives live in the `@aotter/mantle-spec` package's own `mantle-spec` binary: `mantle-spec introspect [--manifests <dir>]` dumps the parsed manifest tree as JSON, and `mantle-spec emit-types [--manifests <dir>] [--namespace <name>] [-o <file>]` emits standalone `.d.ts` declarations. Add `@aotter/mantle-spec` as a direct dependency to run them. The full flag reference is in [HTTP, MCP, CLI and packages](../reference/surface.md).
-
-### What `generate` does and does not do
-
-`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the **prebuilt** Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
-
-Do not Vite-build Admin unless you are developing `@aotter/mantle-admin-ui` itself. A Cloudflare project that serves Admin must declare Static Assets:
+Choose a host before running the command. The integrated hosts are `cf` and
+`chatgpt-sites`; `--features spec` works without a host. Install one exact
+published SDK version, then let the CLI declare its matching optional packages:
 
-```jsonc
-"assets": { "directory": "./public", "binding": "ASSETS" }
+```sh
+mkdir my-app && cd my-app
+npm init -y
+npm pkg set type=module
+MANTLE_VERSION=$(npm view @aotter/mantle@latest version)
+npm install --save-exact "@aotter/mantle@$MANTLE_VERSION"
+npx mantle generate --host cf
+npm install
+npx mantle generate
+npm run build
 ```
 
-That binding is a hard requirement. If `/admin` returns SPA `index.html` (`200`) while `/_mantle/admin/assets/*` is `404`, the page white-screens. Leave `/_mantle` out of `run_worker_first` so those files stay on the assets layer. `generate` warns when it syncs Admin and the local wrangler config has no `ASSETS` binding.
-
-It does not project skills, update packages, change styling, provision providers, or deploy. It does not create manifests: a missing or empty `manifests/` directory is an error, not a prompt.
-
-## The generated module
-
-`.mantle/generated/mantle.ts` exports:
+Confirm `MANTLE_VERSION` is a stable release, without a prerelease suffix.
+Use `--host chatgpt-sites` for a Site; [its guide](../chatgpt-sites/generated-app.md)
+continues with D1 migration, owner identity and local smoke. If you already
+use pnpm, keep that one package manager and run `pnpm install` /
+`pnpm exec mantle`. The first `generate` may exit asking you to install newly
+declared packages; the second completes generation. A README or lockfile from
+bootstrapping still counts as a new app. Once choices are saved, omit flags on
+rerun.
 
-| Export | Purpose |
-|---|---|
-| `plan` | The sealed RuntimePlan with its fingerprint. The conventional Worker imports only this. |
-| `MantleHandlers<Env>` | The handler map type: one typed function per `handler.kind: ref` Procedure, receiving `(input, ctx)`. |
-| `createMantle({ storage, handlers, ports })` | Prepares storage eagerly once and returns the typed binding. No caching or retry. |
-| `bindMantle(runtime)` | The same typed binding over a runtime whose lifecycle the host already owns. |
-
-The binding exposes `mantle.views.<lowerCamelName>()`, `mantle.procedures.<name>(input, ctx)`, `mantle.entries.<collection>.createDraft({ data, authorId })`, typed indexed field reads such as `mantle.entries.<collection>.findManyByDataField({ field, value, limit })`, and the underlying `mantle.runtime`. Generated property names are deterministic lower-camel identifiers; calls keep the authored wire names internally. See [Typed queries](../guides/typed-queries.md) for internal Views and entry-reader examples. Details are in [HTTP, MCP, CLI and packages](../reference/surface.md).
-
-## The daily loop
+For a smaller composition, list wanted modules positively:
 
 ```sh
-pnpm install --frozen-lockfile
-pnpm exec mantle validate
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-pnpm test                      # only when the project declares a test script
-pnpm exec mantle-harness indexes --require-public --format text
-pnpm exec wrangler dev --local
+npx mantle generate --host cf --features spec,api
+npx mantle generate --features spec
 ```
 
-Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works. When Admin is installed, also probe `/admin/sign-in` and one `/_mantle/admin/assets/*` URL — both must be `200`. HTML 200 with asset 404 is the white-screen class of bug.
-
-## Connecting an agent
+Dependencies are expanded in the saved selection: `api` includes Runtime and
+Spec; `admin` includes Runtime, API and MCP. Supported features are `spec`,
+`runtime`, `api`, `mcp`, `admin`, `web`. No host is needed for Spec-only. Use an
+explicit host in automation so a terminal prompt cannot stall. The selection
+lives in `mantle.config.json`; changing it later requires a deliberate migration,
+not an accidental CLI flag.
 
-`mantle skills` projects the skills the installed package marks `projection: project`. At this version those are `develop`, `plugin`, `theme` and `update`; `install`, `media-gc` and `provision` stay opt-in because they create projects, delete remote objects or handle production secrets. Both tool layouts receive identical bytes. Generation never rewrites these files.
+## Files and ownership
 
-Install the plugin bundle in the agent host. Cold start uses
-the install skill; an already-installed project pins packages from `package.json`:
+| File | Owner | What happens on rerun |
+|---|---|---|
+| `manifests/*.yaml`, `src/handlers.ts`, `src/home.ts` | You | Preserved. Add domain behavior and edit the blank home here. |
+| `package.json`, `mantle.config.json`, `wrangler.jsonc` | Shared | Required versions and scripts are added; existing user values are preserved or conflicts reported. |
+| `.mantle/generated/*`, `src/storage-fingerprint.json` | CLI | Rebuilt from the saved selection and manifests. |
+| `drizzle/*.sql` on Sites | Review and apply | New migrations append; applied migrations are never rewritten. |
+| `public/_mantle/admin/*` | CLI | Prebuilt Admin assets copied from the selected exact package. |
+| `.openai/hosting.json` on Sites | Sites | Binding metadata is created locally; existing project metadata is preserved. |
+
+A generated Worker imports the sealed `plan`, your handler map and the selected
+modules. Generated files carry a marker so the CLI can distinguish them from
+user-owned code. A rerun refuses to replace an unmarked file. Existing
+applications without a saved selection keep their direct-authoring compile
+behavior. For integration into an independently authored application, use the
+installed `docs/skills/integrate/SKILL.md` to choose an embedding, incremental
+replacement or rebuild strategy. Generation does not verify arbitrary host
+entry points or deployment wiring.
+
+`generate` accepts `--manifests <dir>` (default `./manifests`), `--output <dir>`
+(default `.mantle/generated`), `--namespace <name>`, `--host cf|chatgpt-sites`,
+`--features <comma-list>` and `--check`. Check mode exits nonzero
+on drift and does not write. Sites also accepts `--review-unique-indexes` for
+an explicit, source-bound unique tuple migration and duplicate preflight;
+[review the D1 procedure](../chatgpt-sites/generated-app.md) before applying
+it. `mantle validate` checks grammar and linked
+capabilities; `--phase deploy` adds deployment checks. `mantle skills` projects
+the installed SDK's project skills into `.agents/skills/` and `.claude/skills/`;
+`mantle skills --check` detects drift. `mantle emit-openapi` describes HTTP
+Triggers and View REST routes; `mantle-harness indexes` and `http` inspect
+queries and running routes. [Command reference](../reference/surface.md).
+
+## Verify the assembled app
 
 ```sh
-# Canonical
-npx skills add aotter/mantle --skill install
-
-# Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
-
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
+npx mantle generate --check
+npx mantle skills
+npx mantle skills --check
+npm run typecheck
+npm run build
+npm run dev
 ```
 
-The projected `develop` skill tells the agent to read `package.json` for the installed version, the manifests and adapter config, and the docs under `node_modules/@aotter/mantle/docs/` before editing. To connect an MCP client to the running Worker, see [MCP and agents](../concepts/mcp-and-agents.md).
-
-## Version pins
-
-- Pin every `@aotter/mantle*` package to one exact version and move them together. Check that release's peer ranges when you move.
-- This handbook describes the snapshot in this source tree. Use the docs that ship with the version in `package.json`, not a floating branch.
-- The authoring CLI is `generate`, `validate`, `emit-openapi` and `skills`. `mantle-harness` is the measurement binary. There is no `create` / `update` happy path.
-- When you change versions: pin the new exact version and refresh the lockfile; keep the Worker, D1, KV identity, origins, auth mode and secrets; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
+Run scripts that exist in the selected project; Spec-only has no server to
+start. Run `npx mantle validate` after adding the first Manifest: the validator
+reports `MANIFEST_ROOT_NOT_FOUND` on an intentionally empty app. A full
+Cloudflare app should serve the blank home and Admin assets.
+For local CF Admin, copy `.dev.vars.example` to `.dev.vars`, replace
+`ADMIN_EMAIL` with the intended owner's address and `BETTER_AUTH_SECRET` with
+a random 32-byte secret, and keep `PUBLIC_ORIGIN` equal to the loopback URL
+wrangler prints. Open `/admin/sign-in` with that email and read the OTP in
+wrangler logs. Check that `/_mantle/admin/assets/*` loads, an anonymous
+`/admin/api/site-settings` request is denied, and the signed-in owner can read
+it. Verify anonymous staff MCP access fails before claiming it works. A full
+Site must also apply its reviewed
+D1 migration before the Worker boots. The public MCP endpoint is discoverable
+without a staff session; the staff endpoint requires the host's verified
+identity and a Mantle role. See [MCP and agents](../concepts/mcp-and-agents.md).
+
+For an already installed app, confirm `node_modules/@aotter/mantle/package.json`
+and the lockfile agree. Use that package's CLI and `docs/` tree; the latest
+GitHub handbook may describe a newer release. Keep all selected
+`@aotter/mantle*` packages on one exact version. The prior direct-authoring
+contract remains valid for older installed SDKs; upgrade deliberately using
+[release notes](../releases/index.md).
 
 ## Source
-- [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
-- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/MantleCli.ts`](../../../packages/mantle-spec/src/infrastructure/cli/MantleCli.ts)
-- [`skills/develop/SKILL.md`](../../../skills/develop/SKILL.md)
+
+- [Generate CLI](../../../packages/mantle/src/cli/generate.ts)
+- [Project selection and package pins](../../../packages/mantle/src/cli/generate-project.ts)
+- [Cloudflare assembly](../../../packages/mantle/src/cli/generate-cloudflare.ts)
+- [ChatGPT Sites assembly](../../../packages/mantle/src/cli/generate-sites.ts)

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

@@ -3,9 +3,11 @@ description: "Open local Admin in one shot: follow the official OTP example, bin
 ---
 # Quickstart: local Admin
 
-Admin is **opt-in**: use it when humans need a Dev UI. A complete Mantle
-service does not require this surface. The default embed path — Spec + Worker
-without Admin — is [Quickstart: a minimal Worker](./quickstart-worker.md).
+New generated CF and Sites apps include Admin by default. To leave it out,
+select smaller features explicitly. This tutorial shows the existing
+direct-authored Worker integration with local email OTP; use it when you own
+the Worker entry. [Project layout and CLI](./project-and-cli.md) describes the
+new generated path.
 
 The procedural source of truth is the official example:
 
@@ -29,7 +31,7 @@ Traps (documented on the example):
 - `pnpm check` / smoke rewrites `.dev.vars` to a smoke-only port — restore it
   from `.dev.vars.example` before `pnpm dev`.
 
-Install every `@aotter/mantle*` package from the `latest` dist-tag; see
+Pin every selected `@aotter/mantle*` package to the same exact version; see
 [Versions](../reference/surface.md#versions). Admin needs both
 `@aotter/mantle-admin` and `@aotter/mantle-admin-ui`, wrangler `ASSETS` on
 `./public`, and `createAuth` email-otp + `ConsoleEmailSender`.

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

@@ -3,7 +3,13 @@ description: "Author a minimal Cloudflare Worker from scratch: one Schema, one p
 ---
 # Quickstart: a minimal Worker
 
-This page reproduces Core's API-only Worker reference as a from-scratch walkthrough. It is the embed / adapter path: View REST without Admin, Auth or a visitor frontend. Admin is opt-in when humans need a console — [Quickstart: local Admin](./quickstart-admin.md). Resolve the intended release once and pin every `@aotter/mantle*` package to it; see [Versions](../reference/surface.md#versions).
+This page reproduces the API-only Worker reference as a direct-authoring
+walkthrough: View REST without Admin, Auth or a visitor frontend. For a new
+project, `mantle generate --host cf --features spec,api` assembles that smaller
+composition. Omit `--features` to include Admin, MCP and a blank home. The
+[local Admin tutorial](./quickstart-admin.md) covers an authored Worker entry.
+Pin every selected `@aotter/mantle*` package to one exact version; see
+[Versions](../reference/surface.md#versions).
 
 ## Prerequisites
 
@@ -13,10 +19,9 @@ This page reproduces Core's API-only Worker reference as a from-scratch walkthro
 
 ## 1. `package.json`
 
-The `latest` entries below are bootstrap placeholders. Step 5 replaces both
-with one exact version before the first build. For a prerelease evaluation,
-select its exact version explicitly rather than mixing channels. The other
-entries are the peers and tools used by this reference.
+Step 5 adds the two Mantle packages at one exact version. For a prerelease
+evaluation, select its exact version explicitly rather than mixing channels.
+The entries below are the peers and tools used by this direct-authored reference.
 
 ```json
 {
@@ -31,8 +36,6 @@ entries are the peers and tools used by this reference.
     "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit"
   },
   "dependencies": {
-    "@aotter/mantle": "latest",
-    "@aotter/mantle-cloudflare": "latest",
     "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "zod": "^4.5.4",
@@ -172,10 +175,13 @@ curl -i http://127.0.0.1:8787/mcp/staff
 - `.mantle/generated/mantle.ts` — one module with the sealed `plan`, generated types (`MantleHandlers<Env>`), `createMantle` and `bindMantle`. The Worker entry above imports only `plan`.
 - `public/_mantle/admin/` — the Admin SPA, synced only when `@aotter/mantle-admin-ui` is installed. This project did not install it, so nothing is written there and `/admin` has no assets.
 
-`generate` fails on missing or invalid manifests and never creates a project, a default Schema or a home route. `mantle generate --check` reports stale output without writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git and regenerates them in `check`; see [Project layout and the CLI loop](./project-and-cli.md).
-
-> **npm and optional peers**
-> A cold npm install can fail with `ERESOLVE` when an Auth peer selects a different optional `@libsql/client` than this snapshot declares. If that happens, pin `@libsql/client` in `overrides` to the range in this checkout's `package.json` and rerun `npm install`. Do not use `--force`. Commit the lockfile and use `npm ci` afterwards.
+This walkthrough uses the existing direct-authored Worker entry; in that legacy
+compile mode, `generate` expects the supplied manifests and does not add a
+home route. New applications can instead use `mantle generate --host cf`
+with `--features spec,api` for a smaller assembled Worker. The CLI never
+invents a Schema. `mantle generate --check` reports stale output without
+writing. The reference keeps `.mantle/`, `.agents/` and `.claude/` out of git
+and regenerates them in `check`; see [Project layout and CLI](./project-and-cli.md).
 
 ## Next steps
 

package/docs/release-process.md

@@ -110,10 +110,11 @@ dist-tag DELETE only added failure and re-run state, and Actions
    ```
 
    Leave the consumer cold-start entry **untagged**: `npx skills add
-   aotter/mantle --skill install`, `/plugin marketplace add aotter/mantle`,
+   aotter/mantle`, `/plugin marketplace add aotter/mantle`,
    `codex plugin marketplace add aotter/mantle` and the plugin-manifest
    descriptions carry no `@v…` / `--ref`. Untagged resolves to `main`, which
-   only moves at a release, so it is always the latest published version
+   normally moves at a release but may contain a source-only hotfix; the
+   installed npm package remains the version authority
    (#995, #998). Only "installed version" statements such as
    `(currently \`X.Y.Z\`)` are bumped.
 

package/docs/sealed-pipeline-ownership.md

@@ -65,7 +65,7 @@ release use `docs/examples/host-minimal-worker` from the same reviewed commit.
 Private consumers can still run the exact-tarball checker in their own repos;
 public Core PRs receive no cross-repository credentials:
 
-| Consumer | Revision | Gate authority | Manifest paths |
+| Historical consumer | Revision | Gate at the time | Manifest paths |
 |---|---|---|---|
 | `aotter/mantle-starters` | `157e8f49e1e25ae1c52c0115f0dd9e8b6017ef0e` | Core CI + release | `blank/manifests/site.yaml`; `overlays/{community,intake,presence,publication,reservation,transaction}/manifests/site.yaml`; `recipes/typed-web/manifests/site.yaml` |
 | `aotter/mantle-landing` | `4381354dd25d5d94f4096cf3e55a4cb9eecbf3ad` | Landing CI + Core release | `manifests/site.yaml` |

package/docs/skills/develop/SKILL.md

@@ -0,0 +1,258 @@
+---
+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
+```
+
+On 0.1.5 and newer, `generate --host cf|chatgpt-sites` assembles a new blank
+app; no `--features` selects Spec, Runtime, API, MCP, Admin and Web. Explicit
+`--features` selects a smaller composition. It never invents a business
+Schema. Existing authored apps keep compile mode, and older installed CLIs
+may not support project generation. Check this project's CLI help first.
+
+## 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
+
+Generated full apps select Admin by default; smaller selections can omit it.
+A project without `@aotter/mantle-admin-ui` is complete when Admin was not
+selected. If Admin was selected but its package is missing, install the
+CLI-declared exact version and rerun generation.
+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.
+
+Generated Cloudflare apps use `MANTLE_AUTH_MODE=local-otp` on loopback after
+copying `.dev.vars.example` to `.dev.vars` and setting a real owner email and
+random secret. Production uses `hosted` or `self-managed` with provider
+credentials and `ADMIN_GITHUB_LOGIN`. Conventional Cloudflare projects that
+do not replace Auth use those two production modes; 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`.