@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.1

package/README.md

@@ -5,7 +5,7 @@ engine built around a 4-atom YAML model (Schema / View / Procedure / Trigger)
 where agents write config and the runtime carries the complexity.
 
 > Mantle is prerelease software. Use this package's `package.json` as the exact
-> installed version; APIs may change between prereleases until v0.1.0.
+> installed version; APIs may change between prereleases until the first stable 0.1.2 release.
 
 ## Install
 
@@ -49,18 +49,18 @@ by the application.
 The package also installs `mantle` and `mantle-harness`:
 
 ```bash
-npx -y @aotter/mantle@alpha create <type> <directory>
 pnpm exec mantle generate
 pnpm exec mantle generate --check
 pnpm exec mantle skills
 pnpm exec mantle skills --check
-pnpm exec mantle update --ref <immutable-starter-ref>
 pnpm exec mantle-harness indexes --require-public
 pnpm exec mantle-harness http --base-url http://127.0.0.1:8787 --route page=/en/example
 ```
 
 `mantle generate` validates and compiles `./manifests/`, then writes one typed
-`.mantle/generated/mantle.ts` module. It performs no Admin asset installation,
+`.mantle/generated/mantle.ts` module. When `@aotter/mantle-admin-ui` is
+installed, it also syncs the Admin SPA to `public/_mantle/admin/` (excluding
+`server.*` package exports). Core-only installs skip that copy. It performs no
 skill sync, package update, styling, provisioning, or deployment.
 The same pure emitter is available from `@aotter/mantle/codegen` when a host
 wants to own parsing and filesystem IO.
@@ -86,10 +86,9 @@ does not cache or retry. Dynamic and platform hosts can keep their own lifecycle
 use generated `bindMantle(runtime)`, or skip code generation and call
 `runtime.executeView({ view: "published-notes" })` directly.
 
-`mantle create` materializes one version-matched starter bundle into a new
-directory and stops: it installs nothing, initializes no repository, configures
-no auth, and deploys nothing. It resolves only the official immutable starter
-tag for the CLI's own version, and refuses to write into an existing path.
+Author the application directly using [the installed guide](docs/handbook/start/project-and-cli.md).
+The CLI has no scaffold/type picker; missing manifests fail without creating
+an application or a visitor home page.
 
 `mantle skills` copies every skill the installed package marks
 `projection: project` in its front matter into matching
@@ -100,15 +99,10 @@ receive identical bytes; `--check` detects drift without writing. An older
 project may also carry `.agent/skills/`, which is left untouched. Manifest
 generation never rewrites agent instructions.
 
-`mantle update` compares the recorded source bundle, a target bundle, and the
-local project, then writes `.mantle/update-report.json`. It never applies the
-diff. Configure `.mantle/features.json` `registry.bundleBaseUrl` with a URL
-containing `{ref}`, or pass `--bundle-base-url` for the alpha.63 bridge. The
-report carries the only supported metadata migration; review and apply it
-after porting selected upstream changes. Format-versioned bundles use the same
-strict renderer as `mantle create`; an invalid current launch state fails
-instead of producing a guessed diff. Older bundles without `formatVersion`
-retain a read-only compatibility renderer.
+SDK upgrades use the package manager and the version-matched update skill.
+For npm peer-resolution troubleshooting, see [the authoring guide](docs/handbook/start/project-and-cli.md).
+See [0.1.2 migration](docs/migration-0.1.2.md) for removed bundle APIs and how to
+preserve legacy application source and provider configuration.
 
 ## Conventional Cloudflare Worker
 
@@ -134,7 +128,8 @@ configuration keeps public routes available but returns `503 setup_incomplete`
 from Auth-owned private routes. Pass `auth: (env) => Auth` only when the site
 needs to replace this conventional factory; Core still owns the Auth routes.
 The exact bindings and validation rules are in the
-[Cloudflare adapter README](../adapters/cloudflare/README.md#conventional-auth).
+`node_modules/@aotter/mantle-cloudflare/README.md`, under “Conventional Auth”
+(path relative to the application root).
 
 Extensions may add routes but may not replace Core surfaces. These paths are
 reserved:
@@ -181,22 +176,18 @@ identity reused by browser favicons, Admin chrome, and MCP `serverInfo.icons`;
 PNG is the compatibility rendition and SVG remains the editable source.
 
 For an uncommon deployment that must own the top-level assembly, use the
-embedded [`docs/cloudflare-low-level-composition.md`](docs/cloudflare-low-level-composition.md)
+embedded [`docs/handbook/cloudflare/low-level-composition.md`](docs/handbook/cloudflare/low-level-composition.md)
 fixture. It composes the same public primitives without importing package
 internals or rebuilding Mantle's adapters.
 
 ## Getting started
 
-Give the [Mantle repo](https://github.com/aotter/mantle) to a coding agent or
-install its agent plugin, then ask it to create a site. The install skill picks
-a deterministic bundle from
-[`aotter/mantle-starters`](https://github.com/aotter/mantle-starters),
-materializes a local project, and verifies it before any provider work.
-
-[Mantle landing](https://mantle.tools) uses the same bundles and continues
-through private GitHub repo creation, Cloudflare deployment, and optional paid
-hosted auth. Generated repos project Core-owned `mantle:*` skills from their
-installed package for repo-local use.
+Use the installed install skill and [direct-authoring guide](docs/handbook/start/project-and-cli.md).
+The owner or agent writes the application's manifests, entry and configuration;
+`generate` compiles them and `skills` projects the version-matched instructions.
+The [minimal Worker reference](docs/examples/minimal-worker/README.md) is an
+executable example, not a scaffold command. Legacy Landing/Starters remain on
+alpha.17 and are not required by new applications.
 
 ## Agent marketplace install
 
@@ -249,16 +240,20 @@ adapter is a port-implementation exercise, not a runtime refactor.
 
 ## Documentation
 
+- The handbook is the user documentation and ships inside this npm package:
+  `node_modules/@aotter/mantle/docs/handbook/` (start, concepts, Cloudflare
+  guides, examples, reference; `navigation.json` lists every page in order).
+  The copy in `node_modules` describes the installed release.
 - Embedded docs and agent skills ship inside this npm package for
   generated-site agents:
-  - `node_modules/@aotter/mantle/docs/design-atoms.md`
-  - `node_modules/@aotter/mantle/docs/api-mcp-authorization.md` (anonymous,
+  - `node_modules/@aotter/mantle/docs/handbook/reference/manifest.md`
+  - `node_modules/@aotter/mantle/docs/handbook/examples/guarded-api.md` (anonymous,
     API-key, paid guard, personal-token, OAuth, REST, and MCP examples)
-  - `node_modules/@aotter/mantle/docs/media-uploads.md` (Cloudflare R2 adapter recipe)
-  - `node_modules/@aotter/mantle/docs/deferred-lifecycle-queues.md` (versioned
+  - `node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md` (Cloudflare R2 adapter recipe)
+  - `node_modules/@aotter/mantle/docs/handbook/cloudflare/deferred-hooks-queues.md` (versioned
     Queue wiring, retry/DLQ, idempotency, and delivery guarantees)
-  - `node_modules/@aotter/mantle/docs/schema-indexes.md` (ordered composite
-    JSON-field indexes, D1 query plans, and the safe Procedure SQL helper)
+  - `node_modules/@aotter/mantle/docs/handbook/reference/schema.md` (Schema grammar,
+    ordered composite JSON-field indexes and the safe Procedure SQL helper)
   - `node_modules/@aotter/mantle/docs/performance-harness.md` (crowded SQLite,
     Wrangler-local D1 origin paths and coding-agent guardrails)
   - `node_modules/@aotter/mantle/docs/adr/`
@@ -269,9 +264,9 @@ adapter is a port-implementation exercise, not a runtime refactor.
   - `node_modules/@aotter/mantle/skills/install/SKILL.md`
   - `node_modules/@aotter/mantle/skills/provision/SKILL.md`
 - [4-atom manifest model (ADR-0001)](docs/adr/0001-four-atom-manifest-model.md)
-- [API and MCP authorization](docs/api-mcp-authorization.md)
-- [Deferred lifecycle Queues](docs/deferred-lifecycle-queues.md)
-- [Schema indexes on D1](docs/schema-indexes.md)
+- [API and MCP authorization](docs/handbook/examples/guarded-api.md)
+- [Deferred lifecycle Queues](docs/handbook/cloudflare/deferred-hooks-queues.md)
+- [Schema indexes on D1](docs/handbook/reference/schema.md)
 - [Release process](docs/release-process.md)
 - [Source repository](https://github.com/aotter/mantle)
 - [Issues](https://github.com/aotter/mantle/issues)
@@ -279,3 +274,8 @@ adapter is a port-implementation exercise, not a runtime refactor.
 ## License
 
 Apache-2.0
+
+Pure extension routes do not await content preparation. Before an extension
+uses Mantle data or database-backed Auth, await its supplied `getRuntime()`
+(or `ref.get()`). Standard protected routes establish this readiness themselves;
+queue/scheduled handlers continue to use `worker.getRuntime(env)`.

package/dist/cli/generate.d.ts

@@ -1,2 +1,11 @@
-export declare function runGenerate(rawArgs: readonly string[]): Promise<number>;
+/** Test seam for Core-only vs Admin-present installs. */
+export interface GenerateDeps {
+    readonly resolveAdminUiIndexHtml?: () => string | null;
+}
+/**
+ * Locate the optional Admin SPA. A Core-only install does not have
+ * `@aotter/mantle-admin-ui`, so resolution failure is not an error.
+ */
+export declare function resolveAdminUiIndexHtml(): string | null;
+export declare function runGenerate(rawArgs: readonly string[], deps?: GenerateDeps): Promise<number>;
 //# sourceMappingURL=generate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAeA,wBAAsB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC7E"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAiBA,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAOvD;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CA+CjB"}

package/dist/cli/generate.js

@@ -1,11 +1,26 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { cwd, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { ValidateManifestsUseCase } from "@aotter/mantle-spec";
 import { loadManifestsFromRoot } from "@aotter/mantle-spec/cli";
 import { assertMantleNamespace, emitMantleModule } from "../codegen/emitMantleModule.js";
-export async function runGenerate(rawArgs) {
+/**
+ * Locate the optional Admin SPA. A Core-only install does not have
+ * `@aotter/mantle-admin-ui`, so resolution failure is not an error.
+ */
+export function resolveAdminUiIndexHtml() {
+    try {
+        const path = fileURLToPath(import.meta.resolve("@aotter/mantle-admin-ui/index.html"));
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runGenerate(rawArgs, deps = {}) {
     let options;
     try {
         const parsed = parseGenerateArgs(rawArgs);
@@ -38,7 +53,13 @@ export async function runGenerate(rawArgs) {
         return 1;
     }
     const output = resolve(cwd(), options.output);
-    const stale = !(await syncText(join(output, "mantle.ts"), emitted.source, options.check));
+    let stale = !(await syncText(join(output, "mantle.ts"), emitted.source, options.check));
+    const adminIndex = (deps.resolveAdminUiIndexHtml ?? resolveAdminUiIndexHtml)();
+    if (adminIndex !== null) {
+        const adminSource = dirname(adminIndex);
+        const adminTarget = resolve(cwd(), "public/_mantle/admin");
+        stale = !(await syncAdminAssets(adminSource, adminTarget, options.check)) || stale;
+    }
     if (stale && options.check) {
         stderr.write("Mantle generated files are stale; run `mantle generate`.\n");
         return 1;
@@ -76,7 +97,7 @@ Options:
   --manifests <dir>   Manifest directory (default: ./manifests)
   -o, --output <dir>  Generated root (default: .mantle/generated)
   --namespace <name>  Generated type namespace (default: Mantle)
-  --check             Fail without writing when generated code is stale
+  --check             Fail without writing when generated code or Admin assets are stale
   -h, --help          This help
 `);
 }
@@ -95,6 +116,30 @@ async function syncText(path, expected, check) {
     await writeFile(path, expected, "utf8");
     return true;
 }
+async function syncAdminAssets(source, target, check) {
+    const sourceFiles = (await listFiles(source)).filter((path) => !path.startsWith("server."));
+    const targetFiles = await listFiles(target).catch(() => []);
+    const current = sourceFiles.length === targetFiles.length
+        && sourceFiles.every((path, index) => path === targetFiles[index])
+        && (await Promise.all(sourceFiles.map(async (path) => (await readFile(join(source, path))).equals(await readFile(join(target, path)))))).every(Boolean);
+    if (current || check)
+        return current;
+    await rm(target, { recursive: true, force: true });
+    for (const path of sourceFiles) {
+        const destination = join(target, path);
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, await readFile(join(source, path)));
+    }
+    return true;
+}
+async function listFiles(root, prefix = "") {
+    const entries = await readdir(join(root, prefix), { withFileTypes: true });
+    const files = await Promise.all(entries.map((entry) => {
+        const path = join(prefix, entry.name);
+        return entry.isDirectory() ? listFiles(root, path) : [path];
+    }));
+    return files.flat().sort();
+}
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/cli/generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAmB,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AASzF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA0B;IAC1D,IAAI,OAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,SAAS,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM;QAC9B,CAAC,CAAC,wBAAwB,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACzD,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IACxD,MAAM,gBAAgB,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;SACxE,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC3D,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QACtD,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC;QAC/B,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QAChB,gBAAgB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACtC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1F,IAAI,KAAK,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC3E,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,iBAAiB,CAAC,OAA0B;IACnD,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAC3B,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;QAClB,OAAO,EAAE;YACP,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE;YACtC,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7B,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;YAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;SACtC;KACF,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,QAAQ,CAAC;IAC/C,qBAAqB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAChD,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,aAAa;QAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,mBAAmB;QAC5C,SAAS;QACT,KAAK,EAAE,MAAM,CAAC,KAAK,KAAK,IAAI;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;CAUd,CAAC,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,WAAkC;IAC1D,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAgB,EAAE,KAAc;IACpE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 import { argv, stderr, stdout } from "node:process";
 import { runEmitOpenapi, runValidate, } from "@aotter/mantle-spec/cli";
-import { runCreate } from "./create.js";
 import { runGenerate } from "./generate.js";
 import { runSkills } from "./skills.js";
-import { runUpdate } from "./update.js";
 async function main() {
     const command = argv[2];
     if (!command || command === "--help" || command === "-h") {
@@ -13,10 +11,8 @@ async function main() {
 Usage: mantle <subcommand> [options]
 
 Subcommands:
-  create         Materialize a version-matched starter into a new directory
   generate       Compile manifests and handler types
   skills         Project version-matched Core skills
-  update         Compare local work with provision bundles
   validate       Static manifest + handler-source validation
   emit-openapi   Emit OpenAPI 3.1 from Triggers + Views
 `);
@@ -24,14 +20,10 @@ Subcommands:
     }
     const rest = argv.slice(3);
     switch (command) {
-        case "create":
-            return runCreate(rest);
         case "generate":
             return runGenerate(rest);
         case "skills":
             return runSkills(rest);
-        case "update":
-            return runUpdate(rest);
         case "validate":
             return runValidate(rest);
         case "emit-openapi":

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,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,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;;;;;;;;;;;CAWhB,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,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,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,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;;;;;;;;;CAShB,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,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/docs/adapter-guide.md

@@ -4,7 +4,7 @@ This guide is the fresh-developer entry point for implementing a new mantle plat
 
 Read this with [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
 
-Adapter packages live under `packages/adapters/<platform>/` using a plural `adapters` bucket. The npm package names stay unchanged, for example `@aotter/mantle-cloudflare`. Keep adapters in this monorepo until the runtime/spec API is stable enough that coordinated releases across separate repositories would not create version skew for starters.
+Adapter packages live under `packages/adapters/<platform>/` using a plural `adapters` bucket. The npm package names stay unchanged, for example `@aotter/mantle-cloudflare`. Keep adapters in this monorepo until the runtime/spec API is stable enough that coordinated releases across separate repositories would not create version skew for consumers.
 
 ## Required storage boundary
 
@@ -106,6 +106,15 @@ optional `/libsql` subpath adapts a caller-owned remote Turso/libSQL client to
 the canonical SQLite chain; the default entry has no database-vendor policy.
 Vercel's read-only filesystem and writable `/tmp` are never durable state.
 
+### Browser IndexedDB embedding
+
+`@aotter/mantle-indexeddb` implements the same required semantic storage ports
+over one application-owned IndexedDB database. It keeps browser globals out of
+Runtime Core, supports declarative Views with a documented O(n) collection
+scan, and exposes `deleteDatabase()` only on the concrete adapter. The host owns
+database naming, `navigator.storage` persistence requests, active-runtime
+selection, UI invalidation, and any remote synchronization.
+
 ## HTTP and MCP surfaces
 
 The runtime is a library, not an HTTP server. A new adapter must mount equivalent framework routes:
@@ -126,7 +135,7 @@ adapter. A narrow adapter extension seam may let consumer code verify its own
 API-key or personal-token formats, but credential storage/issuance must not
 become a runtime port. The Cloudflare reference is
 `mount/resolveCaller.ts`; consumer usage is documented in
-[API and MCP authorization](api-mcp-authorization.md).
+[API and MCP authorization](handbook/examples/guarded-api.md).
 
 Minimum HTTP behavior for a full adapter:
 
@@ -134,7 +143,7 @@ Minimum HTTP behavior for a full adapter:
 - Route `GET /api/views/<name>` to `runtime.executeView`.
 - Mount admin content APIs with session/role checks before calling runtime content use cases.
 - Serve selected Admin SPA assets through `AdminAssetServer`, with an SPA catchall for client-side routes.
-- Mount public render routes and markdown mirrors when the starter exposes public pages.
+- Mount public render routes and markdown mirrors when the application exposes public pages.
 - Translate runtime diagnostics and validation failures into stable HTTP JSON responses instead of throwing raw errors.
 - Evaluate target auth and dynamic guards through the runtime use cases; do
   not duplicate guard logic in HTTP handlers.
@@ -152,27 +161,10 @@ its document operations into their own routing and cache conventions.
 
 ### HTTP cache contract
 
-The Cloudflare adapter is private by default. Consumers must apply its final
-cache policy after admin, auth, API, OAuth, MCP, application routes, redirects,
-and errors.
-Those responses receive `Cache-Control: private, no-store`; Cloudflare-specific
-CDN cache overrides are removed.
-
-`mountPublicRoutes(...)` renders canonical D1 state and opts only successful HTML, markdown,
-`llms.txt`, and sitemap responses into the shared cache with
-`Cache-Control: public, max-age=0, s-maxage=300` and the site-level
-`Cache-Tag: mantle-public`. The top-level policy preserves
-that opt-in only for anonymous `GET`/`HEAD` responses with status 200, explicit
-shared freshness, no request `Cookie` or `Authorization`, and no response
-`Set-Cookie`. It also varies public responses by `Cookie` and `Authorization`.
-
-A starter-level Workers Cache may therefore store only responses that still
-meet that exact public contract. It must bypass credentialed/cookie requests
-and must never infer cacheability from a URL prefix. Cache entries remain
-version-local; cross-version caching is outside this contract. Successful
-publishing-content and site-setting mutations purge `mantle-public` through
-Cloudflare's native cache API. Operational records and immutable assets do not
-purge the public render cache.
+Keep responses private by default. For Cloudflare, apply the final policy after
+all routes and preserve only explicit anonymous public opt-in. Follow the
+[public cache contract](handbook/cloudflare/public-web.md#cache-contract) and the
+[performance harness](performance-harness.md#cache-contract) for verification.
 
 Minimum auth/MCP behavior:
 
@@ -195,6 +187,10 @@ storage preparation and binding do not accept or require a static asset port.
 
 ## Implementation checklist
 
+- [ ] Run `runStorageConformance` from `@aotter/mantle-runtime/testing/storage`
+      against a disposable prepared-storage factory. See the
+      [Runtime conformance guide](../packages/mantle-runtime/README.md#storage-adapter-conformance)
+      for coverage, cleanup, locale setup, and remaining adapter-specific tests.
 - [ ] Implement `MantleStorageAdapter` returning existing semantic ports, or reuse `SqliteMantleStorageAdapter` with an already-owned handle.
 - [ ] Call `bootMantleRuntime()` once per semantic revision, or explicitly prepare before binding.
 - [ ] Mount HTTP Trigger and View REST surfaces.

package/docs/adr/0008-structured-diagnostic-shape.md

@@ -3,7 +3,7 @@
 **Status:** Carried over from POC v0.0.x; amended for the shipped v0.1
 diagnostic emitters and measured harnesses.
 
-**Date:** 2026-04-30 (POC); last amended 2026-08-03.
+**Date:** 2026-04-30 (POC); last amended 2026-08-31.
 
 **Deciders**: phsu
 
@@ -215,8 +215,13 @@ admin SPA and CF Workers could share a CSP-safe path with no
 `Function`-constructor codegen. The v0.1.0 rebuild inherits zod
 from day 1 — manifest authoring stays JSON Schema, but the
 runtime validator a manifest author's request body hits is a
-zod schema, produced by the JSON-Schema → zod converter in
+zod schema, produced by Zod's official `z.fromJSONSchema` importer behind the
+compatibility boundary in
 `@aotter/mantle-spec` (see [`docs/design-atoms.md`](../design-atoms.md) § "Manifest validation — JSON Schema in, zod at runtime").
+Mantle validates its supported keyword/ref policy before import and emits
+`JSON_SCHEMA_UNSUPPORTED`, `JSON_SCHEMA_REF_INVALID`, or
+`JSON_SCHEMA_LIMIT_EXCEEDED`; Zod owns the accepted keywords' validation
+semantics.
 
 Concretely, runtime entry validation consumes `ZodError.issues`:
 

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -625,3 +625,103 @@ OAuth store and is not renamed by this decision.
 This amendment adopts the 2026-07-28 CIMD authorization profile only. Updating
 Mantle's JSON-RPC dispatcher to the complete MCP 2026-07-28 transport revision
 is a separate decision.
+
+## 2026-09-07 amendment — shared OAuth surfaces and revocation
+
+OAuth product UI is not owned by a runtime adapter. `@aotter/mantle-admin`
+owns `MantleOAuthAuth`, the consent/connected-app view models, and
+`handleMantleOAuth(Request) -> Response | null`; `mountMantleOAuth` is a thin
+Hono bridge. The Cloudflare adapter implements protocol actions using the
+same Better Auth instance and D1. Future adapters reuse this contract, not
+Cloudflare-specific UI glue. The old `mountAuthorize` export remains an alias.
+
+`@aotter/mantle-admin-ui` owns the React/shadcn sign-in, consent and connected
+apps surfaces, including i18n, theme and submit state. Auth pages initially
+follow the system theme; the light/dark toggle persists an explicit override.
+Connected apps has an Admin page, but managing one's own grants requires only
+a session, never a staff role. The no-assets HTML fallback uses native forms
+without JavaScript or a second implementation of the Admin design system.
+Both mounts retain same-origin mutation checks and private/no-store responses.
+The consent document's CSP permits only the provider-validated callback
+origin for the browser's form redirect; it never trusts an unsigned query.
+
+MCP authorization remains session-bound: the JWT's original Better Auth
+session must still exist and be unexpired. Admin sign-out/session expiration
+therefore also ends that session's MCP access. A refresh token is not an
+independent authorization to bypass this check. Staff roles are still read
+fresh on every protected request.
+
+Disconnect is scoped to the authenticated user and the selected client. It
+revokes refresh/opaque access tokens, removes pending authorization codes and
+consent rows, and prevents existing JWTs from becoming valid when the client
+is connected again. The verification-create hook captures the consent row ID
+in Better Auth's existing authorization `referenceId`; Better Auth carries it
+through the authorization code and every refresh rotation. MCP JWTs copy that
+reference into `mantle_consent_id`, which must match the active consent row.
+Never look up a new consent at token mint time: doing so could revive a refresh
+lineage whose insertion raced the revoke batch. Same-second reconnect and a
+delayed old refresh row are required regression cases, not clock delays.
+
+MCP mode reserves authorization `referenceId` for this grant identity; future
+curated configuration must not also expose Better Auth's `postLogin` reference
+hooks. MCP access requires a persisted user consent, so `skipConsent` and
+`cachedTrustedClients` must not bypass consent for MCP clients.
+
+This alpha hotfix requires existing MCP clients to reconnect once: pre-hotfix
+JWTs without the grant claim are rejected immediately. No account/session reset
+is required. The unshipped watermark migration 0008 is removed; its unused
+table in the phsu development database is harmless and is not queried or
+deleted during deployment.
+
+## 2026-09-08 amendment — request security boundaries
+
+All Admin session mutations use the existing same-origin guard, including
+same-site sibling origins. Admin HTML forbids framing and is private/no-store.
+The SPA also refuses to render in frames, covering direct static-asset URLs
+that bypass the server mount.
+The Admin/auth mounts cap request bodies at 1 MiB using Hono's body limiter;
+HTTP trigger and MCP dispatchers count streamed JSON bytes before parsing and
+return 413 above the same limit. Media bytes continue through direct uploads.
+This intentionally rejects previously accepted larger control-plane payloads.
+
+Cloudflare `createAuth` explicitly enables Better Auth rate limits regardless
+of `NODE_ENV`, including the OAuth provider's anonymous registration limit of
+five requests per minute. Only `CF-Connecting-IP` supplies the client key.
+The upstream memory store limits each isolate; deployments needing a shared
+abuse quota must additionally enforce it at ingress. No D1 migration or new
+runtime platform dependency is introduced.
+
+Workers must retain initialization work through `ExecutionContext.waitUntil`
+even when the initial challenge finishes or its client disconnects. Schema
+boot precedes OAuth handling. The adapter's static AsyncLocalStorage seeding
+is a version-pinned Better Auth 1.7.2 integration, with accessor-identity
+regression coverage; it does not replace Better Auth's request context.
+Failed Auth initialization evicts only the failed Worker assembly so a later
+request can retry. Non-HTTP callers await Auth initialization with runtime boot;
+HTTP requests anchor it without making public responses depend on Auth health.
+
+The conventional `/favicon.ico` reflects the configured site icon, but is a
+fallback after consumer routes, not a newly reserved namespace. Existing
+consumer icon routes must continue to work after a package update.
+
+## Amendment — 2026-09-14: Host-only control-plane cookies
+
+`CreateAuthConfig.hostOnlyCookies` is an opt-in, curated auth field for a
+control plane on a parent domain shared with tenants. It uses native `__Host-`
+cookie names, `Secure`, `Path=/` and no `Domain`; HTTPS is required and enabling
+cross-subdomain sharing at the same time is rejected. Existing defaults and
+Apple's `SameSite=None` requirement remain unchanged. Consumers must treat
+switching cookie names as an explicit sign-in migration, not rewrite request
+or response cookies. This keeps cookie semantics in the auth adapter rather
+than requiring each consumer to wrap Admin, member and OAuth routes.
+
+## Amendment — 2026-09-16: deployment KV session reads
+
+Cloudflare deployments may pass their deployment-owned KV namespace as
+`CreateAuthConfig.sessionCacheKv`. Better Auth reads sessions from KV while
+keeping the canonical session row in D1. OTP verification remains D1-backed
+and rate limiting remains isolate-local because Workers KV does not provide
+the atomic consume or increment operations those paths require. Auth keys use
+the `better-auth:` prefix so the namespace can also hold Mantle projections.
+Session revocation and user updates use Better Auth's cache invalidation and
+therefore follow Workers KV's propagation model.

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

@@ -1,5 +1,8 @@
 # ADR-0018: Keep Core and public starters in separate repositories
 
+> 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
 
 **Date:** 2026-08-02

package/docs/adr/0019-sealed-manifest-runtime-pipeline.md

@@ -2,10 +2,12 @@
 
 **Status:** Accepted
 
-**Date:** 2026-08-16
+**Date:** 2026-08-16; last amended 2026-09-01
 
 **Related:** [#656](https://github.com/aotter/mantle/issues/656),
 [#662](https://github.com/aotter/mantle/issues/662),
+[#759](https://github.com/aotter/mantle/issues/759),
+[#760](https://github.com/aotter/mantle/issues/760),
 [#546](https://github.com/aotter/mantle/issues/546), ADR-0008, ADR-0009,
 ADR-0011, ADR-0018
 
@@ -106,11 +108,45 @@ Concrete D1/SQLite drivers and SQL repositories remain implementation details.
 An existing application may either pass its already-owned database/client to
 an official adapter or implement the semantic ports over its own tables.
 
+`@aotter/mantle-indexeddb` is the optional browser storage implementation of
+the same semantic ports. One adapter exclusively owns one application-selected
+database name, uses structured-clone persistence and IndexedDB transaction
+completion as its write boundary, and exposes database deletion only on the
+concrete adapter. Runtime Core gains no browser global, browser facade,
+namespace, persistence request, reactive binding, or synchronization port.
+Declarative browser Views use a documented O(n) scan until measured use proves
+an IndexedDB query planner necessary.
+
 Declarative Views compile to logical plans once. Storage preparation lowers
 those plans to native queries. The v0.1 `View.spec.sql` form remains explicitly
 SQLite-only and is rejected by unsupported storage during preparation; Mantle
 does not guess a translation and does not add a universal query driver.
 
+### Callable capability projection
+
+Optional callable transports consume `projectCallableCapabilities(RuntimePlan)`.
+Each Procedure capability retains the owning MCP Trigger name while its
+input/output/title/description remain owned by the target Procedure; View
+capabilities retain their read-only View contract. Discovery and invocation use
+the same projected descriptor, and invocation routes through `invokeTrigger`
+rather than bypassing Trigger identity with a direct Procedure call. Hosts may
+select a surface and bind transport or browser lifecycle, but do not rescan raw
+manifests or maintain a second registry.
+
+`@aotter/mantle-web/webmcp` is an opt-in host binding over that projection. It
+feature-detects `document.modelContext`, adds public capabilities without
+replacing existing host tools, and uses the registration `AbortSignal` only for
+teardown. A browser-local host supplies the projected capabilities and a
+late-bound invoker; Procedure calls retain their explicit MCP Trigger identity.
+For a server-backed host, the Cloudflare adapter publishes a minimal public View
+catalog at `GET /api/views`; the binding validates that wire catalog and invokes
+the existing same-origin `GET /api/views/<name>` route. The catalog contains no
+raw manifest or staff capability.
+Invocation hooks may drive host UI effects but cannot replace Runtime
+validation, authorization, dispatch, or domain results. The binding does not
+add browser globals to Runtime Core, expose staff capabilities, or introduce a
+second manifest/runtime path.
+
 ### Naming and code generation
 
 The Core execution unit is `MantleRuntime`, not a site. Optional TypeScript