@aotter/mantle 0.1.3-alpha.6 → 0.1.4

package/README.md

@@ -12,11 +12,11 @@ where agents write config and the runtime carries the complexity.
 Cold start for a new application is the install skill, not a bare npm add:
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 To depend on this package in an existing project, pin the exact version
-from `package.json` (currently `0.1.3-alpha.6`):
+from `package.json` (currently `0.1.4`):
 
 ```bash
 npm install @aotter/mantle
@@ -205,7 +205,7 @@ internals or rebuilding Mantle's adapters.
 Cold start from GitHub or a marketplace host:
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 That skill interviews, pins this package, then uses the CLI and the
@@ -223,7 +223,7 @@ Install the Mantle Core skill bundle before authoring or maintaining a
 consumer application. The canonical command is:
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 Claude Code and Codex can install the plugin, then run that skill:
@@ -242,7 +242,7 @@ Cursor and VS Code Copilot can auto-discover the GitHub repo through
 `.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json` after the repo
 is cloned or opened. Still start from the `npx skills add` sentence (or open
 `skills/install/SKILL.md`). Untagged `aotter/mantle` resolves to `main`, which
-only advances at a release, so it is always the latest published version. Add
+can contain a source-only hotfix ahead of the latest npm release. Add
 `@vX.Y.Z` only to reproduce an older project; never point a consumer at
 `develop` or another moving branch.
 

package/dist/cli/main.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle --skill install\n";
+export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Start:         node_modules/@aotter/mantle/docs/handbook/start/overview.md\n  Features:      node_modules/@aotter/mantle/docs/handbook/reference/features.md\n  Admin UI:      node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle\n";
 //# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAgCA,eAAO,MAAM,eAAe,kxDAwC3B,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAgCA,eAAO,MAAM,eAAe,g6DA0C3B,CAAC"}

package/dist/cli/main.js

@@ -62,9 +62,11 @@ Subcommands:
   emit-openapi   Emit OpenAPI 3.1 from Triggers and Views
 
 Documentation:
-  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)
+  Start:         node_modules/@aotter/mantle/docs/handbook/start/overview.md
+  Features:      node_modules/@aotter/mantle/docs/handbook/reference/features.md
+  Admin UI:      node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md
   Online:        https://mantle.tools/
-  Install skill: npx skills add aotter/mantle --skill install
+  Install skill: npx skills add aotter/mantle
 `;
 main().then((code) => {
     process.exitCode = code;

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe;CAClC,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC9B,CAAC;AAEF,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe;CAClC,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C9B,CAAC;AAEF,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/cli/skills.js

@@ -59,7 +59,7 @@ export async function runSkills(rawArgs) {
             return 1;
         }
         if (!check)
-            stdout.write(`Mantle skills projected: ${skills.join(", ")}.\n`);
+            stdout.write(`Mantle skills projected: ${skills.join(", ")}.\nRead .agents/skills/mantle-develop/SKILL.md and node_modules/@aotter/mantle/docs/handbook/start/overview.md.\n`);
         return 0;
     }
     catch (error) {
@@ -116,7 +116,7 @@ export function projectionScopes(skillMarkdown) {
 }
 async function skillSourceRoot() {
     const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-    for (const candidate of [join(packageRoot, "skills"), resolve(packageRoot, "../../skills")]) {
+    for (const candidate of [join(packageRoot, "skills"), resolve(packageRoot, "../../docs/skills")]) {
         if ((await stat(candidate).catch(() => null))?.isDirectory())
             return candidate;
     }

package/dist/cli/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}

package/docs/adr/0001-four-atom-manifest-model.md

@@ -214,8 +214,9 @@ See § Authoring shape below for the full retirement rationale.
 Names + PG-1:1 framing are documented in this ADR and the manifest grammar
 reference. Manifest TS types live in `packages/mantle-spec/`. The external
 [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
-repository declares consumer instances of each atom. Runtime dispatcher, View
-executor, and Procedure dispatcher live in this repository.
+repository declared alpha-era consumer instances of each atom; new applications
+are authored directly under [ADR-0021](0021-retire-starter-scaffolding.md).
+Runtime dispatcher, View executor, and Procedure dispatcher live in this repository.
 
 ---
 

package/docs/adr/0013-agent-provisioned-consumer-projects.md

@@ -2,8 +2,8 @@
 
 ## Status
 
-Superseded for first launch by provisioning v2 (2026-06-27). Historical
-record only.
+Superseded by [ADR-0021](0021-retire-starter-scaffolding.md) for 0.1.2 and
+later. Historical pre-stable install flow only.
 
 ## Date
 
@@ -11,7 +11,7 @@ record only.
 
 ## Context
 
-> **Current direction:** Mantle landing creates the GitHub repo from
+> **Historical 2026-06-27 direction, no longer current:** Mantle landing creates the GitHub repo from
 > `mantle-starters` `provision-bundles/<type>.json`, commits the blank
 > or type bundle, and connects Cloudflare Workers CI when possible.
 > Do not extend the old `create-mantle launch --session` or
@@ -144,7 +144,7 @@ they are debugging a failed provision.
 
 ## Implementation status
 
-- `skills/install/SKILL.md` and `skills/provision/SKILL.md` encode the
+- `skills/install/SKILL.md` and `docs/skills/provision/SKILL.md` encode the
   current agent workflow, including the launch-session fast path.
 - `aotter/mantle-starters` hosts `packages/create-mantle`, whose
   `launch --session` mode validates the session before writing files.

package/docs/adr/0016-site-semantic-layer.md

@@ -2,9 +2,10 @@
 
 ## Status
 
-Accepted (slimmed 2026-05-12 per Epic #116; `mantle/site.md` letter
-surface suspended 2026-06-19 and removed from first-run scaffolds;
-amended 2026-06-27 for landing provision bundles).
+Superseded by [ADR-0021](0021-retire-starter-scaffolding.md) for 0.1.2 and
+later. The launch-state and provision-bundle rules below describe the legacy
+Starter/Landing flow; new applications are authored directly from the installed
+SDK's skill and handbook.
 
 ## Decision
 
@@ -65,5 +66,5 @@ and to the landing substitution pass.
   generated `.mantle/*.template` bundle files.
 - Substitution: Mantle landing provision-bundle substitution.
 - Install handoff: `skills/install/SKILL.md` describes how agents continue from the landing-provisioned repo.
-- Provision update: `skills/provision/SKILL.md` describes the `AGENTS.md` public-site rewrite after deploy.
+- Provision update: `docs/skills/provision/SKILL.md` describes the `AGENTS.md` public-site rewrite after deploy.
 - Type overlays are applied while building `provision-bundles/<type>.json`; generated repos should not need a second overlay step.

package/docs/adr/0018-core-starters-repository-boundary.md

@@ -3,7 +3,7 @@
 > Superseded for 0.1.2 by [ADR-0021](0021-retire-starter-scaffolding.md).
 > The contract below is retained as alpha.17 history, not current launch/release guidance.
 
-**Status:** Accepted for now; revisit only under the triggers below
+**Status:** Superseded by ADR-0021 for 0.1.2 and later. Historical alpha.17 decision only.
 
 **Date:** 2026-08-02
 

package/docs/adr/README.md

@@ -14,9 +14,9 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0010](0010-locale-and-translates.md) | Locale 3-layer (manifest / D1 site_config / data field) + translates pattern. Boot decoupled from `site_config` (issue #60 fix). | Accepted (refreshed) |
 | [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Accepted (new) |
 | [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
-| [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. Superseded for first launch by landing provision bundles. | Superseded |
+| [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. | Superseded by 0021 |
 | [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
-| [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
+| [0016](0016-site-semantic-layer.md) | Historical Starter/Landing `AGENTS.md` and launch-state contract. | Superseded by 0021 |
 | [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
 | [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
 | [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |

package/docs/agent-prompts.md

@@ -3,16 +3,16 @@
 Cold start from GitHub or a marketplace host is the install skill:
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 Copy one block into a coding agent after that skill is present. Paths below
 are relative to the Mantle docs root: `node_modules/@aotter/mantle/docs/`
-after `@aotter/mantle` is installed, or `docs/` in the installed agent plugin.
+after `@aotter/mantle` is installed. A standalone `skills add` installation
+contains only the selected skill, not these docs.
 `npx --no-install mantle --help` is the layered CLI overview; it mirrors the
 authoring docs. A live `/mcp` catalog mirrors the Manifest → RuntimePlan, not
-the CLI. Interview first. Worker is the default host unless the user names
-ChatGPT Sites. There is no `mantle create`. Empty `generate` fails until
+the CLI. Resolve only missing requirements first; do not assume a host. There is no `mantle create`. Empty `generate` fails until
 manifests exist. Admin is opt-in.
 
 ### Interview then build
@@ -20,9 +20,11 @@ manifests exist. Admin is opt-in.
 ```text
 Interview me about the service: host, who uses it, whether humans need a
 Dev UI, and whether we only embed Spec/Runtime. If the install skill is
-missing, run npx skills add aotter/mantle --skill install. Read the
-install skill and npx --no-install mantle --help, then
-handbook/start/project-and-cli.md.
+missing, run npx skills add aotter/mantle. Read the
+installer-reported skill, choose and install an exact SDK version, then read
+its embedded skills/install/SKILL.md,
+run npx --no-install mantle --help, and
+read handbook/start/overview.md.
 Use examples/README.md as the examples index; copy builtin-* Manifests only
 (not cf-primitives-*). Implement locally first. Take only the surfaces we
 chose. For Spec-only use, skip Runtime and code generation. For a Worker
@@ -82,7 +84,7 @@ Use only when the user names ChatGPT Sites as the host.
 
 ```text
 Build with ChatGPT Sites; use Mantle for content management and publishing.
-Read handbook/sites/index.md and examples/host-chatgpt-sites/README.md.
+Read handbook/chatgpt-sites/index.md and examples/host-chatgpt-sites/README.md.
 Use that runnable host as a reference and install its pinned
 dependencies from the registry. Derive Schema, View,
 Procedure and Trigger from my requirements and check the Admin editor/picker and public

package/docs/consumer-onboarding-audit.md

@@ -0,0 +1,65 @@
+# Consumer onboarding audit for 0.1.3
+
+Scope: source skill install → pinned npm package → CLI → generated skills and
+handbook → application manifest and Admin customization. This is maintainer
+evidence, not a release announcement. Baseline: develop `b90cebbd`, package
+version `0.1.3-alpha.5`; the package version alone does not identify unreleased
+commits on develop. Tracking: [#1042](https://github.com/aotter/mantle/issues/1042).
+
+## Clean source install
+
+Executed in an empty temporary directory:
+
+```sh
+npx --yes skills add aotter/mantle --skill install --agent codex --yes
+```
+
+Observed output: repository cloned, **7 skills found**, **1 selected**, copied
+to `./.agents/skills/install`. `skills-lock.json` records source `aotter/mantle`,
+source type `github`, and source path `skills/install/SKILL.md`. The installed
+file's hash in that lock was
+`8a6fd26aea97ae8bdf3e05fef22196c247b3f95aa049204a6ac51259d87e4e29`.
+No SDK, handbook or application is installed by that command. The explicit
+Codex and noninteractive flags make the audited destination reproducible;
+other selected agents/global scope can use another destination.
+
+This source install follows the repository's default ref. It does not test the
+unreleased edits in this PR or establish an npm version. The packed-consumer
+check below tests this branch's shipped instructions separately.
+
+## White-box path and fixes
+
+| Stage / owner | Finding before this change | Correction |
+|---|---|---|
+| README → external skills installer | Prompt told the agent to read `skills/install/SKILL.md` and `docs/agent-prompts.md`, neither installed there. | Read the installer-reported destination, then the installed SDK's embedded docs. |
+| `skills/install/SKILL.md` | Bootstrap Git instructions did not explicitly hand off to the installed package's own install skill; `docs/...` root was implicit. Host interview was repeated. | Explicit package-root resolution and version authority; ask only for missing requirements. |
+| Install → CLI | It was possible to try the local CLI before installing Core; `generate` in an empty directory fails rather than creating a project. | Spell out package installation before CLI and manifest authoring before generation. |
+| Quickstart versions | Floating `latest` dependency examples contradicted exact-pin advice. | Resolve the requested channel once and save exact Mantle versions before the first build. |
+| `mantle skills` | Correctly projected four project skills, but success output did not tell the agent what to read next. | Print the projected develop skill and installed handbook entry. Document overwrite, drift and opt-in behavior. |
+| `sync-package-docs.mjs` → npm `files` | Docs and all seven skills already shipped; presence checks did not protect the new entry paths or exercise projection from the tarball. | Assert handbook/skill files and byte-identical `.agents`/`.claude` projection in the existing packed-consumer check. |
+| View concepts → grammar/runtime | Concepts denied internal Views and recommended SQL for every new View; reference `surface` table omitted `internal`. SQL admission text was stale. | Match implemented surfaces, typed declarative reads, SQLite admission sandbox and native-dialect limits. |
+| Manifest reference | View's allowed spec keys omitted `cache`; Schema list-column prose omitted native columns. | Reconcile with parser and Admin UI checker. |
+| Plugin/update skills | Assumed conventional source paths, missed regeneration after plugin manifest edits, and treated every View as publicly callable. | Use actual project paths, regenerate the plan, verify the declared surface and distinguish stable index from target prerelease docs. |
+| Feature discovery | No task-to-manifest capability map or usable human entry; reference was buried after host-specific sections. | Add overview, capability table and task guides; move reference before host guides without breaking existing URLs. |
+| Typed query discovery | APIs existed but lacked a complete internal-View calling example or clear reader authorization distinction. | Explain generated params/results, runtime `result` versus REST `data`, SQL `unknown`, indexed reader limits and plan-based emission. |
+| Admin requests → theme/develop skills | Theme skill targeted visitor source; no routing from an Admin request to manifest-controlled presentation. | Route to Admin guide, with Schema/View/Procedure rendering table and supported customization ceiling. |
+| Auth operations | Store-bound session cache behavior existed in code/ADR but was missing from the handbook. | Explain store identity, preparation order and KV propagation limits. |
+
+## Verification and regression coverage
+
+- `packages/mantle-spec/test/handbook-contract.test.ts`: complete handbook YAML
+  examples parse and validate; navigation covers pages; relative links resolve.
+- `packages/mantle/test/cli/generate.test.ts`: extracts the new internal-View
+  YAML and TypeScript directly from the handbook, generates bindings and runs
+  strict TypeScript checking on the real example.
+- CLI surface/projection tests assert the concrete next-read destinations;
+  existing drift checks verify `--check` is read-only.
+- `scripts/check-optional-packages.mjs`: packs and installs the actual Core
+  tarball, checks embedded entry pages/skills, runs `skills` and `skills --check`,
+  and compares each project projection byte-for-byte with the installed package.
+- Repository gate: `pnpm check`. Exact execution results and any environment
+  limitations are recorded in the PR, rather than frozen as a future guarantee.
+
+No npm publish, tag, deployment or grammar change is part of this audit. Source
+skill consumers receive the corrections only once they reach the installed Git
+ref; npm consumers receive them only in a package built from the corrected tree.

package/docs/examples/README.md

@@ -19,4 +19,4 @@ Drop a `builtin-*` YAML block into `host-local-admin-otp/manifests/` (or `host-m
 | [`cf-primitives-guarded-api.md`](./cf-primitives-guarded-api.md) | API keys, scopes, live entitlement `ref` guards over REST and MCP | cf-primitives | no | none | `host-minimal-worker` plus credential resolver |
 | [`host-minimal-worker/`](./host-minimal-worker/README.md) | Executable Spec + adapter without Admin | host | no | none | itself |
 | [`host-local-admin-otp/`](./host-local-admin-otp/README.md) | Executable opt-in Admin / Dev UI with email OTP | host | no | required | itself |
-| [Mantle on ChatGPT Sites](../handbook/sites/index.md) · [runnable reference](./host-chatgpt-sites/README.md) | Runnable Sites D1/R2, ChatGPT identity, Admin media, published web and public read-only MCP | host | no | required | itself |
+| [Mantle on ChatGPT Sites](../handbook/chatgpt-sites/index.md) · [runnable reference](./host-chatgpt-sites/README.md) | Runnable Sites D1/R2, ChatGPT identity, Admin media, published web and public read-only MCP | host | no | required | itself |

package/docs/examples/host-chatgpt-sites/README.md

@@ -1,8 +1,8 @@
 # Mantle on ChatGPT Sites: runnable reference
 
-The runnable application for [Mantle on ChatGPT Sites](../../handbook/sites/index.md) connects Sites D1 + R2 bindings, Sign in with ChatGPT identity, Mantle Admin and staff roles, same-origin media upload, a published-only article frontend, anonymous read-only `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. Remote OAuth MCP remains a separate integration; see [MCP support](../../handbook/sites/host-reference.md#remote-mcp-is-a-separate-gate).
+The runnable application for [Mantle on ChatGPT Sites](../../handbook/chatgpt-sites/index.md) connects Sites D1 + R2 bindings, Sign in with ChatGPT identity, Mantle Admin and staff roles, same-origin media upload, a published-only article frontend, anonymous read-only `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. Remote OAuth MCP remains a separate integration; see [MCP support](../../handbook/chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
 
-After setup, follow [Publish your first article](../../handbook/sites/index.md#publish-your-first-article) to verify the editorial workflow in Admin.
+After setup, follow [Publish your first article](../../handbook/chatgpt-sites/index.md#publish-your-first-article) to verify the editorial workflow in Admin, then [maintain content with an agent](../../handbook/chatgpt-sites/index.md#maintain-content-with-an-agent). Article pages advertise their Markdown mirror through an HTML `rel="alternate"` link; the example does not add a visible Markdown button to the reader UI.
 
 ## Before writing code
 
@@ -10,7 +10,7 @@ Read the user's business request and author the manifest for **their** records a
 
 ## Install and run
 
-Requires Mantle 0.1.2 or newer. Copy this directory outside the SDK checkout, then:
+Requires Mantle 0.1.2 or newer. Copy this directory from the selected installed SDK version into a new application directory. Replace every `@aotter/mantle*` `latest` dependency in `package.json` with that same exact version, then:
 
 ```bash
 npm install                                  # or: bun install
@@ -21,24 +21,41 @@ npm run dev -- --port 4174                   # leave running
 npm test                                     # smoke, in a second terminal
 ```
 
-`npm install` resolves `@aotter/mantle*` from the `latest` dist-tag; this
-example does not commit a lockfile, so every fresh install picks up the
-current stable release. `bun install` works too, resolving from
-`package.json` the same way.
+This example does not commit a lockfile. Commit the lockfile created by your
+first install and use `npm ci` for subsequent installs. `bun install` also
+works when you use Bun's lockfile consistently.
+
+## Add a manifest HTTP Trigger
+
+Mounting Admin does not register a manifest HTTP Trigger on the Site's Hono
+router. For an anonymous JSON form whose Trigger declares `POST /api/rsvp`, add
+the corresponding route inside `assemble` in `src/index.ts`:
+
+```ts
+import { createMantleRequestHandler } from '@aotter/mantle/runtime';
+
+const handleHttp = createMantleRequestHandler({ plan, getRuntime: get });
+app.post('/api/rsvp', async c =>
+  (await handleHttp(c.req.raw, { user: null, staff: null, env: c.env }))
+    ?? new Response('Not found', { status: 404 }));
+```
+
+Return the handler's `Response` directly: it validates the JSON body and maps
+Mantle diagnostics to HTTP status codes. If the Trigger requires a signed-in
+user or staff role, derive that context from the verified Sites session instead
+of copying the anonymous context above. See [Procedures and Triggers](../../handbook/concepts/procedures-and-triggers.md#the-http-envelope).
 
 Keep `.openai/hosting.json`; do not copy an existing Site's `project_id`. To use another port, also set the Worker's `PUBLIC_ORIGIN` and the test's `MANTLE_TEST_ORIGIN` to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
 
 Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
 
-To run this example against an unreleased Mantle checkout instead of the registry, use `node scripts/check-packed-consumer.mjs --project docs/examples/host-chatgpt-sites --output <new dir> -- pnpm build` from a clean SDK checkout and work in its `consumer/`. That path is for SDK development only.
-
-The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest. `scripts/migration.mjs` shows the one-time generation mechanism; do **not** run it against a deployed database or overwrite an applied migration. For a new business manifest, generate/review an initial migration before the first deployment; for a later change, generate an additive migration from the previous schema state.
+The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest and runtime. Apply all pending D1 migrations before deploying updated code; managed storage does not apply runtime infrastructure migrations at boot, and a missing column can make every route return 500. `scripts/migration.mjs` shows the one-time generation mechanism; do **not** run it against a deployed database or overwrite an applied migration. For a new business manifest, generate/review an initial migration before the first deployment; for a later change, generate an additive migration from the previous schema state.
 
 ## Publish with Sites
 
 1. Create a new Site through Sites and request **both D1 and R2**. Confirm its saved hosting manifest has `d1: "DB"` and `r2: "MEDIA_BUCKET"`; the local example intentionally omits `project_id` until Sites provisions one. A missing R2 binding cannot be repaired by adding an R2 type to TypeScript. Sites controls provisioning and publishing, not `wrangler deploy`.
 2. In Sites settings, set `PUBLIC_ORIGIN` to the exact production origin and `OWNER_EMAIL` to the intended first owner. Do not commit hosted secrets or identity headers. Keep the Site audience narrow until verification. A Site Viewer is not automatically a Mantle staff member.
-3. Review the D1 migration, save a Sites version, then deploy that version. Every deployment URL is production. Confirm the deployed artifact includes `dist/server/index.js`, `dist/client/`, `dist/.openai/hosting.json` and `dist/.openai/drizzle/`; `npm run build` prepares those artifacts.
+3. Review the D1 migration, save a Sites version, then deploy that version. Every deployment URL is production. Confirm the deployed artifact includes `dist/server/index.js`, `dist/client/`, `dist/.openai/hosting.json` and `dist/.openai/drizzle/`; `npm run build` replaces `dist` before preparing those artifacts, so removed migrations cannot remain in a later build.
 4. On the deployed Site, check `/health`, `/admin/sign-in`, one `/_mantle/admin/assets/*` file, owner login and staff revocation, Admin media upload and committed public image URL, then publish an article with that asset as its cover. Anonymous draft and uncommitted image URLs must return 404. Check public HTML, Markdown, canonical/JSON-LD, sitemap and `llms.txt`; POST `/api/mcp` should discover only the public View tool, while `/api/mcp/staff` must reject anonymous/member requests and expose staff tools to a current staff session. The root `/mcp` path was intercepted in the lab and is not used by this reference.
 
 The media path uses only the R2 binding: `ports.mediaStorage` + `media.purposes` + authenticated same-origin PUT + committed-only public GET. It does not need an R2 S3 endpoint or API keys. The upload route is browser-session authenticated, so it is **not** an MCP agent upload route. Do not expose the Worker outside Sites' identity-stripping ingress: `src/chatgpt-auth.ts` trusts the `oai-*` headers only under that condition.
@@ -50,4 +67,4 @@ The media path uses only the R2 binding: `ports.mediaStorage` + `media.purposes`
 - `/api/mcp/staff` uses the Sites-injected browser identity and re-reads the Mantle staff role. It is mounted and advertised in Admin, but it is not an OAuth resource server. Do not register it as a remote ChatGPT connector until OAuth discovery, a standards-compliant bearer challenge and token verification are implemented and tested.
 - OAuth discovery returns sign-in HTML: Sites' page session is not an OAuth bearer challenge. Do not bypass Sites auth or trust browser cookies as remote MCP credentials.
 
-See the [Sites host reference](../../handbook/sites/host-reference.md) and [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites).
+See the [Sites host reference](../../handbook/chatgpt-sites/host-reference.md) and [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites).

package/docs/examples/host-chatgpt-sites/drizzle/0003_store_instance_id.sql

@@ -0,0 +1 @@
+ALTER TABLE _mantle_boot_state ADD COLUMN store_instance_id TEXT;

package/docs/examples/host-chatgpt-sites/drizzle/meta/_journal.json

@@ -1 +1 @@
-{"version":"7","dialect":"sqlite","entries":[{"idx":0,"version":"6","when":1790000000000,"tag":"0000_sites_users","breakpoints":true},{"idx":1,"version":"6","when":1790000000001,"tag":"0001_mantle","breakpoints":true},{"idx":2,"version":"6","when":1790000000002,"tag":"0002_article_cover","breakpoints":true}]}
+{"version":"7","dialect":"sqlite","entries":[{"idx":0,"version":"6","when":1790000000000,"tag":"0000_sites_users","breakpoints":true},{"idx":1,"version":"6","when":1790000000001,"tag":"0001_mantle","breakpoints":true},{"idx":2,"version":"6","when":1790000000002,"tag":"0002_article_cover","breakpoints":true},{"idx":3,"version":"6","when":1790000000003,"tag":"0003_store_instance_id","breakpoints":true}]}

package/docs/examples/host-chatgpt-sites/public/site.css

@@ -1 +1 @@
-:root{font-family:Inter,"Noto Sans TC",ui-sans-serif,system-ui,sans-serif;color:#172320;background:#f7f8f4;font-synthesis:none}*{box-sizing:border-box}body{margin:0}a{color:inherit;text-decoration:none}a:hover{text-decoration:underline}.topbar{height:78px;max-width:1440px;margin:auto;padding:0 clamp(24px,5vw,80px);display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid #d9dfd8}.brand{display:flex;align-items:center;gap:12px;font-size:18px;font-weight:760;letter-spacing:-.04em}.brand em{color:#95aa8c;font-style:normal}.mark{width:37px;height:37px;border-radius:11px;background:#183c30;color:#d9eadb;display:grid;place-items:center;font-size:19px;font-family:Georgia,serif}.topbar nav{display:flex;gap:28px;font-size:14px;color:#43564e}.hero{max-width:1440px;margin:auto;padding:100px clamp(24px,8vw,128px) 116px}.hero.small{padding-bottom:75px}.eyebrow,.feature-index{font-size:11px;letter-spacing:.19em;font-weight:750;color:#68806f}.hero h1,.article-page h1{font-family:Georgia,"Noto Serif TC",serif;font-weight:500;letter-spacing:-.055em;line-height:1.09;margin:26px 0 28px;font-size:clamp(48px,6.1vw,94px)}.dot{color:#a2b888}.hero-copy{max-width:620px;color:#52665a;font-size:18px;line-height:1.8}.actions{display:flex;align-items:center;gap:30px;margin-top:38px}.button{display:inline-flex;justify-content:space-between;gap:44px;min-width:184px;padding:17px 19px;border-radius:7px;color:#fff;background:#214f3c;font-size:14px;font-weight:650}.button:hover{background:#173c2d;text-decoration:none}.text-link{font-size:14px;color:#315640}.feature-grid{max-width:1440px;margin:auto;padding:0 clamp(24px,8vw,128px) 110px;display:grid;grid-template-columns:repeat(3,1fr);gap:18px}.feature-grid>div{border-top:1px solid #bfcac0;padding-top:24px}.feature-grid h2{font-family:Georgia,"Noto Serif TC",serif;font-size:29px;font-weight:500;margin:29px 0 10px}.feature-grid p{font-size:14px;line-height:1.75;color:#597064;max-width:270px}.content-wrap{max-width:1184px;margin:0 auto;padding:0 24px 100px}.article-row{padding:25px 0;border-top:1px solid #cbd5ca;display:grid;grid-template-columns:160px 1fr 36px;gap:24px;align-items:start}.article-row:last-child{border-bottom:1px solid #cbd5ca}.article-number{font-size:12px;color:#708477;margin-top:11px}.article-row h2{font-family:Georgia,"Noto Serif TC",serif;font-size:clamp(24px,3vw,35px);font-weight:500;letter-spacing:-.035em;margin:0 0 8px}.article-row p{font-size:14px;color:#617468;line-height:1.65;margin:0}.article-row>span{color:#739279;font-size:25px}.empty{min-height:220px;padding:52px 0}.empty h2{font-size:27px;font-family:Georgia,"Noto Serif TC",serif;font-weight:500}.empty p{color:#66796c}.pagination{margin:26px 0}.article-page{max-width:900px;padding:75px 30px 140px;margin:auto}.back{font-size:13px;color:#5c7768}.article-page article{margin-top:75px}.article-page h1{font-size:clamp(44px,5vw,75px)}.lede{font-size:21px;line-height:1.75;color:#52685a}.prose{border-top:1px solid #cbd5ca;margin-top:45px;padding-top:28px;line-height:1.95;font-size:17px;color:#33473c}.prose p{margin:0 0 1.2em}.markdown-link{display:inline-block;margin-top:40px;font-size:13px;color:#4f765b}footer{border-top:1px solid #d5ddd3;max-width:1440px;margin:auto;padding:28px clamp(24px,5vw,80px);display:flex;justify-content:space-between;font-size:12px;color:#788b7d}@media(max-width:700px){.topbar{height:68px}.topbar nav{gap:16px;font-size:12px}.hero{padding-top:74px;padding-bottom:70px}.hero-copy{font-size:16px}.feature-grid{grid-template-columns:1fr;gap:26px}.article-row{grid-template-columns:1fr 26px;gap:10px}.article-number{grid-column:1/-1;margin:0}.article-page{padding-top:55px}.article-page article{margin-top:50px}footer{gap:20px}}
+:root{font-family:Inter,"Noto Sans TC",ui-sans-serif,system-ui,sans-serif;color:#172320;background:#f7f8f4;font-synthesis:none}*{box-sizing:border-box}body{margin:0}a{color:inherit;text-decoration:none}a:hover{text-decoration:underline}.topbar{height:78px;max-width:1440px;margin:auto;padding:0 clamp(24px,5vw,80px);display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid #d9dfd8}.brand{display:flex;align-items:center;gap:12px;font-size:18px;font-weight:760;letter-spacing:-.04em}.brand em{color:#95aa8c;font-style:normal}.mark{width:37px;height:37px;border-radius:11px;background:#183c30;color:#d9eadb;display:grid;place-items:center;font-size:19px;font-family:Georgia,serif}.topbar nav{display:flex;gap:28px;font-size:14px;color:#43564e}.hero{max-width:1440px;margin:auto;padding:100px clamp(24px,8vw,128px) 116px}.hero.small{padding-bottom:75px}.eyebrow,.feature-index{font-size:11px;letter-spacing:.19em;font-weight:750;color:#68806f}.hero h1,.article-page h1{font-family:Georgia,"Noto Serif TC",serif;font-weight:500;letter-spacing:-.055em;line-height:1.09;margin:26px 0 28px;font-size:clamp(48px,6.1vw,94px)}.dot{color:#a2b888}.hero-copy{max-width:620px;color:#52665a;font-size:18px;line-height:1.8}.actions{display:flex;align-items:center;gap:30px;margin-top:38px}.button{display:inline-flex;justify-content:space-between;gap:44px;min-width:184px;padding:17px 19px;border-radius:7px;color:#fff;background:#214f3c;font-size:14px;font-weight:650}.button:hover{background:#173c2d;text-decoration:none}.text-link{font-size:14px;color:#315640}.feature-grid{max-width:1440px;margin:auto;padding:0 clamp(24px,8vw,128px) 110px;display:grid;grid-template-columns:repeat(3,1fr);gap:18px}.feature-grid>div{border-top:1px solid #bfcac0;padding-top:24px}.feature-grid h2{font-family:Georgia,"Noto Serif TC",serif;font-size:29px;font-weight:500;margin:29px 0 10px}.feature-grid p{font-size:14px;line-height:1.75;color:#597064;max-width:270px}.content-wrap{max-width:1184px;margin:0 auto;padding:0 24px 100px}.article-row{padding:25px 0;border-top:1px solid #cbd5ca;display:grid;grid-template-columns:160px 1fr 36px;gap:24px;align-items:start}.article-row:last-child{border-bottom:1px solid #cbd5ca}.article-number{font-size:12px;color:#708477;margin-top:11px}.article-row h2{font-family:Georgia,"Noto Serif TC",serif;font-size:clamp(24px,3vw,35px);font-weight:500;letter-spacing:-.035em;margin:0 0 8px}.article-row p{font-size:14px;color:#617468;line-height:1.65;margin:0}.article-row>span{color:#739279;font-size:25px}.empty{min-height:220px;padding:52px 0}.empty h2{font-size:27px;font-family:Georgia,"Noto Serif TC",serif;font-weight:500}.empty p{color:#66796c}.pagination{margin:26px 0}.article-page{max-width:900px;padding:75px 30px 140px;margin:auto}.back{font-size:13px;color:#5c7768}.article-page article{margin-top:75px}.article-page h1{font-size:clamp(44px,5vw,75px)}.lede{font-size:21px;line-height:1.75;color:#52685a}.prose{border-top:1px solid #cbd5ca;margin-top:45px;padding-top:28px;line-height:1.95;font-size:17px;color:#33473c}.prose p{margin:0 0 1.2em}footer{border-top:1px solid #d5ddd3;max-width:1440px;margin:auto;padding:28px clamp(24px,5vw,80px);display:flex;justify-content:space-between;font-size:12px;color:#788b7d}@media(max-width:700px){.topbar{height:68px}.topbar nav{gap:16px;font-size:12px}.hero{padding-top:74px;padding-bottom:70px}.hero-copy{font-size:16px}.feature-grid{grid-template-columns:1fr;gap:26px}.article-row{grid-template-columns:1fr 26px;gap:10px}.article-number{grid-column:1/-1;margin:0}.article-page{padding-top:55px}.article-page article{margin-top:50px}footer{gap:20px}}

package/docs/examples/host-chatgpt-sites/scripts/build.mjs

@@ -1,6 +1,7 @@
 import { build } from 'esbuild';
-import { cp, mkdir } from 'node:fs/promises';
+import { cp, mkdir, rm } from 'node:fs/promises';
 import { execFileSync } from 'node:child_process';
+await rm('dist',{recursive:true,force:true});
 execFileSync('node',['node_modules/@aotter/mantle/dist/cli/main.js','generate'],{stdio:'inherit'});
 // Reject older published SDKs that cannot advertise the mounted MCP endpoints.
 execFileSync('node',['node_modules/typescript/bin/tsc','--noEmit'],{stdio:'inherit'});

package/docs/examples/host-chatgpt-sites/scripts/check.mjs

@@ -76,6 +76,8 @@ assert.match(publicPage,new RegExp(mediaUrl));
 assert.doesNotMatch(publicPage,/href="javascript:/);
 assert.match(publicPage,/<meta property="og:image"/);
 assert.match(publicPage,/<link rel="canonical"/);
+assert.match(publicPage,/<link rel="alternate" type="text\/markdown"/);
+assert.doesNotMatch(publicPage,/<a\b[^>]*href="[^"]+\.md(?:[?#][^"]*)?"/);
 assert.match(publicPage,/application\/ld\+json/);
 assert.match(await (await call(`/articles/${entry.id}.md`)).text(),/Published body from Mantle/);
 assert.match(await (await call('/articles')).text(),new RegExp(entry.id));

package/docs/examples/host-chatgpt-sites/src/index.ts

@@ -23,7 +23,7 @@ function assemble(env:Env) {
   mountWeb(app,get);
   mountMcp(app,get,auth);
   mountMedia(app,auth,env);
-  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2'});});
+  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites'});});
   app.get('/admin/sign-in',async c=>{
     if(c.req.header('cookie')?.split(';').some(v=>v.trim()==='mantle-sites-signout=1')) {
       c.header('Set-Cookie','mantle-sites-signout=; Path=/admin/sign-in; HttpOnly; SameSite=Strict; Max-Age=0'+(env.PUBLIC_ORIGIN.startsWith('https:')?'; Secure':''));

package/docs/examples/host-chatgpt-sites/src/web.ts

@@ -26,7 +26,7 @@ export function mountWeb(app:Hono<{Bindings:Env}>,get:()=>Promise<MantleAdminRun
     const title=String(entry.data.title??site.title);
     const image=coverUrl?`<figure class="article-cover"><img src="${escape(coverUrl)}" alt="${escape(cover?.alt||title)}" loading="eager"></figure>`:'';
     const body=micromark(String(entry.data.body??''),{allowDangerousHtml:false,allowDangerousProtocol:false});
-    return c.html(shell(`${title}｜${site.title}`,renderSeoTagsHtml(seo),`<main class="article-page"><a class="back" href="/articles">← 返回文章</a><article><p class="eyebrow">ARTICLE · ${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</p><h1>${escape(title)}</h1>${entry.data.summary?`<p class="lede">${escape(entry.data.summary)}</p>`:''}${image}<div class="prose">${body}</div>${seo.alternateMarkdown?`<a class="markdown-link" href="${articlePath(entry.id)}.md">閱讀 Markdown 版本 ↗</a>`:''}</article></main>`));});
+    return c.html(shell(`${title}｜${site.title}`,renderSeoTagsHtml(seo),`<main class="article-page"><a class="back" href="/articles">← 返回文章</a><article><p class="eyebrow">ARTICLE · ${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</p><h1>${escape(title)}</h1>${entry.data.summary?`<p class="lede">${escape(entry.data.summary)}</p>`:''}${image}<div class="prose">${body}</div></article></main>`));});
   // ponytail: one discovery page is enough for this lab; expose cursor pages when published articles exceed the SDK page limit.
   app.get('/llms.txt',async c=>{const {site,web}=await load();const page=await web.composeLlmsTxt.execute({collections:['articles'],locale:null,site,pathFor:e=>articlePath(e.id)});const body=page?.body??`# ${site.title}\n\n文章索引：${site.origin}/articles\n`;return c.text(body,200,{'Content-Type':'text/plain; charset=utf-8'});});
   // ponytail: first 1000 published URLs; add sitemap index parts only when the catalogue reaches that ceiling.

package/docs/examples/host-minimal-worker/README.md

@@ -9,15 +9,15 @@ Schema/View is example business data; `mantle generate` never invents it.
 
 For your own project, author package.json, manifests, Worker/provider config
 and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. This reference depends on them via
-the `latest` dist-tag instead, so a fresh install always resolves the current
-stable release; Core's test runner substitutes its exact candidate in a
-disposable copy.
+dependencies to the same intended release. The checked-in `latest` values are
+placeholders for Core's disposable release test; resolve and pin one exact
+version before installing a copied application.
 
 Outside the SDK workspace, with Node 22+ and pnpm 9+:
 
 ```sh
-pnpm install
+MANTLE_VERSION=$(pnpm view @aotter/mantle@latest version)
+pnpm add --save-exact "@aotter/mantle@$MANTLE_VERSION" "@aotter/mantle-cloudflare@$MANTLE_VERSION"
 pnpm check
 pnpm dev
 ```

package/docs/handbook/{sites → chatgpt-sites}/equipment-checkout.md

@@ -208,7 +208,7 @@ because the underlying host composition or a different provider succeeded.
 
 ```text
 Extend my existing ChatGPT Site with Mantle equipment checkout. Read the matching
-SDK's docs/handbook/sites/index.md, equipment-checkout.md and host-reference.md.
+SDK's docs/handbook/chatgpt-sites/index.md, equipment-checkout.md and host-reference.md.
 Preserve current content, audience and R2 media. This guide is a design, not an
 installed app: implement and test the missing manifests, handlers and routes.
 Start with one identified kit and one fixed half-day slot per request. Include

package/docs/handbook/{sites → chatgpt-sites}/index.md

@@ -56,7 +56,8 @@ a working example; adapt its fields and lifecycle to your team's content.
    Markdown body. Upload an image in the media library and select it as the
    article's cover. The draft's public article URL should return 404.
 5. **Publish and read.** Publish the article and open `/articles`. Follow its
-   link to check the body and cover, then open its `.md` version. For a public
+   link to check the body and cover, then confirm the page head advertises
+   its `.md` version with `rel="alternate"` and `type="text/markdown"`. For a public
    Site, repeat this while signed out. A restricted Site still enforces its
    audience settings before visitors reach these pages.
 6. **Verify control.** Unpublish the article and confirm its detail page returns
@@ -67,6 +68,17 @@ For later content edits, return to Mantle Admin. Changes to the application's
 schema, code, or deployment settings follow the reference's migration and Sites
 deployment workflow.
 
+## Maintain content with an agent
+
+The owner can use Admin WebMCP in a browser that supports it to let an agent
+discover staff tools for drafts, publishing, and other permitted operations.
+Open `/admin/dev/docs/webmcp` to see that browser surface and
+`/admin/dev/docs/mcp` to see the Site's `/api/mcp` public read-only endpoint and `/api/mcp/staff`
+staff endpoint. The latter uses the current Sites browser session and checks
+the Mantle staff role on each request. It is useful to same-origin browser
+code, but is not a remote OAuth MCP connector for a desktop agent. A remote
+staff connector needs its own verified OAuth flow; see the [host reference](./host-reference.md#remote-mcp-is-a-separate-gate).
+
 ## Ask your agent to set it up
 
 Install the Mantle agent plugin, or `@aotter/mantle` itself, then describe your
@@ -74,7 +86,7 @@ audience and content requirements:
 
 ```text
 Build a content site with ChatGPT Sites and Mantle. Read
-handbook/sites/index.md and examples/host-chatgpt-sites/README.md from the
+handbook/chatgpt-sites/index.md and examples/host-chatgpt-sites/README.md from the
 installed Mantle docs, and follow that reference's install and run steps.
 Adapt the article example to my content requirements. Include ChatGPT
 sign-in, Mantle staff roles, cover uploads, and published article pages.
@@ -83,7 +95,7 @@ deploying through Sites. Keep remote staff OAuth MCP outside this scope.
 ```
 
 For business rules beyond content, add: "use custom `ref` handlers and
-application-owned tables as described in handbook/sites/equipment-checkout.md."
+application-owned tables as described in handbook/chatgpt-sites/equipment-checkout.md."
 
 ## Beyond content: operational workflows
 

package/docs/handbook/cloudflare/authentication.md

@@ -84,6 +84,22 @@ The staff role is re-read from D1 on every protected REST and MCP call; a revoke
 
 MCP tokens are session-bound: signing out of Admin ends MCP access. See [MCP and agents](../concepts/mcp-and-agents.md).
 
+## Session cache and database replacement
+
+When optional session caching is enabled, the cache is derived from the
+canonical store, not a second identity authority. Auth prefixes keys with
+`better-auth:<store-instance-id>:`. Preparing a new store gives it a distinct
+identity, so reusing the same KV namespace after replacing D1 cannot resurrect
+the previous store's cached sessions. Ordinary preparation of the same store
+preserves its identity.
+
+Custom low-level Auth composition must prepare the Mantle store before cached
+Auth operations; do not construct cache keys or seed the identity yourself.
+OTP verification remains in the primary database and rate limiting remains
+isolate-local. Revocation/user-update cache invalidation still follows KV
+propagation; the namespace change is isolation across stores, not a promise of
+instant global invalidation. See the [Auth decision](../../adr/0014-auth-better-auth-and-multi-tenant-mcp.md).
+
 ## Better Auth configuration
 
 `createAuth()` owns the Worker lifecycle, Admin metadata, sender integration,