@aotter/mantle 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/adapter-guide.md

@@ -2,20 +2,24 @@
 
 This guide is the fresh-developer entry point for implementing a new mantle platform adapter.
 
-Read this with [ADR-0011](adr/0011-adapter-port-spec.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
+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.
 
-## Required runtime ports
+## Required storage boundary
 
-A first-run adapter must implement exactly these two runtime ports:
+A storage adapter prepares one `RuntimePlan` into semantic ports:
 
 | Contract | Source | Cloudflare example |
 |---|---|---|
-| `DatabaseDriver` plus `PreparedStatement` and `MigrationRunner` | `packages/mantle-runtime/src/domain/port/DatabaseDriver.ts` | `packages/adapters/cloudflare/src/bindings/D1DatabaseDriver.ts` |
-| `AssetServer` | `packages/mantle-runtime/src/domain/port/AssetServer.ts` | `packages/adapters/cloudflare/src/bindings/AssetsAssetServer.ts` |
+| `MantleStorageAdapter` / `PreparedMantleStorage` | `packages/mantle-runtime/src/domain/port/MantleStorageAdapter.ts` | `SqliteMantleStorageAdapter` over `D1DatabaseDriver` |
+| `EntryRepository & EntryReader` | Existing semantic content ports | `DatabaseEntryRepository` supplied by the SQLite adapter |
+| `ViewQueryExecutor` | `packages/mantle-runtime/src/domain/port/ViewQueryExecutor.ts` | `SqliteViewQueryExecutor` |
 
-The runtime must not import platform types such as `D1Database`, `KVNamespace`, Cloudflare `Fetcher`, Postgres pools, or adapter SDK types. Those live in adapter packages.
+`DatabaseDriver` is only the reusable SQLite/D1 implementation seam. A
+PostgreSQL, MongoDB, or application-owned-table adapter implements the semantic
+ports directly; it does not emulate D1 and needs no mapping DSL. Platform types
+such as `D1Database`, Postgres pools, and Mongo clients remain in adapter code.
 
 ## Optional capabilities
 
@@ -26,7 +30,7 @@ Optional ports are enabled only when a feature needs them:
 | `MediaStorage` | `packages/mantle-runtime/src/domain/port/MediaStorage.ts` | The adapter exposes admin/MCP media upload flows. |
 | `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants at-least-once queue delivery for `after_*` lifecycle hooks. |
 
-Test seams such as `Clock` and `IdGenerator` are injectable through `createCmsRuntime`, but normal adapters do not need custom implementations.
+Test seams such as `Clock` and `IdGenerator` are injectable through `createMantleRuntime`, but normal adapters do not need custom implementations.
 
 Deferred delivery is an optional, versioned wire contract. Queue acceptance is
 not atomic with the entry write; adapters must preserve the supplied event id,
@@ -35,37 +39,72 @@ to their retry mechanism, and document poison-message/DLQ behavior. See
 [Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md)
 for the reference implementation and exact guarantees.
 
-## Runtime boot
+## Storage preparation
 
-Adapters compose the runtime through `createCmsRuntime`:
+Compile before deployment preparation, then pass only the sealed plan:
 
 ```ts
-import { createCmsRuntime } from "@aotter/mantle-runtime";
-
-const runtime = createCmsRuntime({
-  manifests,
+import {
+  bootMantleRuntime,
+  SqliteMantleStorageAdapter,
+} from "@aotter/mantle-runtime";
+
+const storage = new SqliteMantleStorageAdapter(db, siteDefaults);
+const runtime = await bootMantleRuntime({
+  plan,
+  storage,
   handlers,
-  templates,
-  siteDefaults,
-  db,
-  assets,
-  publicPathResolver,
-  mediaStorage,
-  deferredHookDispatcher,
+  ports,
+  deployment: {
+    reservedHttpPathPrefixes: selectedCapabilities.flatMap(
+      (capability) => capability.reservedHttpPathPrefixes,
+    ),
+  },
 });
+```
+
+`bootMantleRuntime` performs one attempt and derives Procedure readiness from
+the supplied handlers. The platform adapter remains responsible for lazy boot,
+promise caching, retry policy, and teardown.
 
-await runtime.bootInit();
+Hosts that need work between preparation and binding may keep the same stages
+public and explicit:
+
+```ts
+const prepared = await prepareDeployment(plan, storage, {
+  handlerNames: Object.keys(handlers ?? {}),
+});
+const runtime = createMantleRuntime({ prepared, handlers, ports });
 ```
 
-`bootInit()` runs canonical migrations, seeds `siteDefaults`, and validates the manifest set. Call it once before serving CMS traffic. The Cloudflare adapter's reference pattern is `packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts`.
+The prepared revision carries its exact plan, but exposes both `plan` and
+`storage`; it seals the pairing invariant rather than hiding low-level host
+capabilities. Omit `handlerNames` only for a read-only embedding that never
+dispatches Procedures.
 
-Use purpose-shaped runtime surfaces for canonical data: `runtime.entryReader`
-applies Schema index declarations, locale semantics, and the public `Entry`
-projection; `runtime.siteConfig` owns site settings. `runtime.db` remains only
-for source compatibility and is deprecated. An adapter that owns additional
-tables should retain the `DatabaseDriver` it injected instead of reaching back
-through the assembled runtime. Authoring continues through the pre-wired
-content use cases.
+The official SQLite adapter runs canonical migrations, defaults, indexes, and
+schema-View reconciliation, and skips mutation for an unchanged revision. A
+custom adapter owns its own preparation and returns application-owned semantic
+ports. Unsupported native View dialects fail before the adapter mutates state.
+
+### Bun embedding
+
+`@aotter/mantle-bun` is the minimal SQLite reference: pass an application-owned
+`bun:sqlite` `Database` and a compiled `RuntimePlan` to `createBunMantle()`.
+Its `handle()` returns `null` for sibling routes and a Web-standard `Response`
+for manifest-declared public Views and HTTP Triggers. The host owns
+`Bun.serve`, database shutdown, authentication, and CSRF policy; the adapter
+prepares the semantic revision once and retries only after failed preparation.
+
+### Vercel Functions embedding
+
+`@aotter/mantle-vercel` accepts a compiled plan plus any application-owned
+`MantleStorageAdapter` and reuses the same public View/HTTP Trigger transport as
+Bun. It maps deferred work to Vercel Functions `waitUntil` and otherwise leaves
+the Web Handler, auth/CSRF, and route composition to the application. The
+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.
 
 ## HTTP and MCP surfaces
 
@@ -73,9 +112,10 @@ The runtime is a library, not an HTTP server. A new adapter must mount equivalen
 
 | Surface | Adapter responsibility | Cloudflare reference |
 |---|---|---|
-| Public/admin HTTP endpoints | Route HTTP Triggers, View REST endpoints, admin SPA assets, and public render routes into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountServerEndpoints.ts`, `mountPublicRoutes.ts` |
-| Auth endpoints | Own sign-in/session/OAuth metadata routes through the adapter's Better Auth integration. | `packages/adapters/cloudflare/src/auth/createAuth.ts`, `mountServerEndpoints.ts` |
-| MCP endpoints | Mount `/mcp/staff` and `/mcp` via `createOAuthProvider({ apiHandlers })`; the OAuth lib verifies bearer tokens against its KV grant store, then calls the matching apiHandler with `ctx.props` set. The adapter enforces the staff D1 role inside the apiHandler, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `oauth/oauthSingleton.ts`, `oauth/mountOAuth.ts` |
+| Runtime HTTP endpoints | Route HTTP Triggers and public View REST endpoints into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts` |
+| Optional Admin | Supply session/request context and assets to `mantle-admin`; mount only when selected. | `packages/adapters/cloudflare/src/mount/mountAdmin.ts` |
+| Auth endpoints | Own sign-in/session/OAuth metadata through the adapter's Better Auth implementation selected by Admin/OAuth surfaces. | `packages/adapters/cloudflare/src/auth/createAuth.ts` |
+| MCP endpoints | Mount `/mcp/staff` and `/mcp` behind one canonical protected resource. The adapter verifies Better Auth JWTs, normalizes the caller, re-reads the staff D1 role, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `auth/createAuth.ts` |
 
 Auth is not a runtime port. Per [ADR-0014](adr/0014-auth-better-auth-and-multi-tenant-mcp.md), the adapter owns Better Auth wiring and passes authenticated user/staff context into runtime dispatchers. Procedure handlers receive that data through `HandlerContext` in `packages/mantle-runtime/src/domain/model/HandlerContext.ts`.
 
@@ -93,7 +133,7 @@ Minimum HTTP behavior for a full adapter:
 - Route manifest HTTP Triggers to `runtime.invokeProcedure`.
 - Route `GET /api/views/<name>` to `runtime.executeView`.
 - Mount admin content APIs with session/role checks before calling runtime content use cases.
-- Serve admin SPA assets through `AssetServer`, with an SPA catchall for admin client-side routes.
+- 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.
 - 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
@@ -101,16 +141,20 @@ Minimum HTTP behavior for a full adapter:
 
 For the Cloudflare adapter, public rendering requires three matching consumer
 inputs: `mountPublicRoutes(...)` route declarations, a `TemplateRegistry`
-passed through `CmsConfig.templates`, and a `publicPathResolver` passed through
-`CmsConfig.publicPathResolver`. Omitting public routes is valid for a headless
+passed through `MantleCloudflareConfig.templates`, and a `publicPathResolver`
+passed through `MantleCloudflareConfig.publicPathResolver`. Omitting public routes is valid for a headless
 consumer; mounting every Schema automatically is not, because some collections
 are private even when they contain a slug.
 
+`TemplateRegistry` and `createPublicPathResolver` come from
+`@aotter/mantle-web`. Other adapters can call `createMantleWeb(runtime)` and map
+its document operations into their own routing and cache conventions.
+
 ### HTTP cache contract
 
-The Cloudflare adapter is private by default. Consumers must export
-`createOAuthProvider(...)` as the Worker's top-level handler so its final
-response policy covers admin, auth, API, OAuth, MCP, redirects, and errors.
+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.
 
@@ -146,20 +190,19 @@ Minimum auth/MCP behavior:
 
 ## Static assets
 
-`AssetServer` is required because every adapter must have a strategy for serving the prebuilt admin UI from `@aotter/mantle-admin-ui`. The adapter may serve those files from platform assets, a static publish directory, object storage plus CDN, or a filesystem bundle. Return `null` from `AssetServer.fetch()` when a specific asset is not found so the adapter can fall back to the admin SPA catchall.
+`AdminAssetServer` belongs to optional `@aotter/mantle-admin`. Headless Core
+storage preparation and binding do not accept or require a static asset port.
 
 ## Implementation checklist
 
-- [ ] Implement `DatabaseDriver`, including canonical migration tracking.
-- [ ] Implement `AssetServer` for the admin UI assets.
-- [ ] Compose `createCmsRuntime` with manifests, handlers, templates, site defaults, and required ports.
-- [ ] Call `bootInit()` before serving CMS traffic.
+- [ ] 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.
 - [ ] Mount admin/public render routes and admin SPA assets.
 - [ ] Provide adapter-owned Better Auth wiring and session helpers.
 - [ ] Normalize session/OAuth and any consumer credential seam into
       `HandlerContext.auth`; never put raw credentials in runtime context.
-- [ ] Mount `/mcp/staff` and `/mcp` via the platform's OAuth provider lib (Cloudflare adapter uses `@cloudflare/workers-oauth-provider` at top level). Enforce staff D1 role inside the apiHandler.
+- [ ] Mount `/mcp/staff` and `/mcp` behind one resource-bound token verifier. Enforce the live staff role inside the apiHandler.
 - [ ] Preserve the HTTP cache contract: private by default; explicit anonymous 200 `GET`/`HEAD` public opt-in only.
 - [ ] Prove one guarded target has identical REST/MCP outcomes, including
       mutable revocation on the next call.
@@ -174,4 +217,4 @@ Minimum auth/MCP behavior:
 - Do not add API-key, personal-token, transaction, billing, or entitlement
   repositories to Core. They are consumer state behind the adapter resolver
   and guard Procedure.
-- Do not add a second canonical migration chain for a new adapter. The runtime owns canonical migrations; adapters execute them through `DatabaseDriver.migrations`.
+- Do not generalize `DatabaseDriver` for PostgreSQL/MongoDB or add a mapping DSL. Implement semantic ports; SQLite/D1 alone reuse the canonical SQL chain.

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

@@ -1,12 +1,20 @@
 # ADR-0001: 4-atom YAML manifest model under `cms.mantle.aotter.net/v1`
 
-**Status:** Carried over from POC v0.0.x; refreshed and folded for v0.1.0 (incorporates POC ADRs 0005 + 0006).
+**Status:** Accepted for the four-atom grammar and multi-document YAML;
+the fixed `site.yaml` file contract is superseded by ADR-0019.
 
-**Date**: 2026-04-30 (POC origin), refreshed 2026-05-03 for v0.1.0 rebuild
+**Date**: 2026-04-30 (POC origin); last amended 2026-08-16
 
 **Deciders**: phsu
 
-**Related**: ADR-0002 (closed enums for bindings)
+**Related**: ADR-0002 (closed enums for bindings),
+[ADR-0019](0019-sealed-manifest-runtime-pipeline.md) (caller-owned source boundary)
+
+> **2026-08-16 amendment:** the four atoms and multi-document YAML remain
+> normative. Core no longer assigns source file names: its parser accepts
+> caller-owned source IDs, and its CLI reads immediate `.yaml` / `.yml` files
+> in lexicographic order. `manifests/site.yaml` remains only a starter
+> convention. Fixed-file statements below are retained as decision history.
 
 ---
 

package/docs/adr/0007-ai-as-primary-author.md

@@ -252,9 +252,9 @@ Concrete artifacts today:
 - Version-matched Core skills ship inside `@aotter/mantle`, through the Mantle
   agent plugin, and through exact-byte repo-local projections written by
   `mantle skills`.
-- The umbrella `mantle` CLI exposes `validate`, `generate`, `skills`, `update`,
-  `introspect`, `emit-openapi`, and `emit-types`; direct spec installs expose
-  the authoring subset through `mantle-spec`.
+- The umbrella `mantle` CLI exposes `create`, `generate`, `validate`,
+  `emit-openapi`, `update`, and `skills`; direct spec installs expose advanced
+  `introspect` and `emit-types` primitives through `mantle-spec`.
 - `@aotter/mantle/runtime/testing` and `mantle-harness` expose the measured
   SQLite/index and live-HTTP checks described in Loop 2.
 

package/docs/adr/0009-consumer-supplied-manifests.md

@@ -1,13 +1,18 @@
 # ADR-0009: Consumer-supplied manifests at SDK boot
 
-**Status:** Carried over from POC v0.0.x; amended for the parser-free v0.1
-consumer boundary.
+**Status:** Superseded by ADR-0019.
 
-**Date:** 2026-05-01 (POC); last amended 2026-08-03
+**Date:** 2026-05-01 (POC); superseded 2026-08-16
 
 **Related:** [ADR-0001](0001-four-atom-manifest-model.md),
 [ADR-0007](0007-ai-as-primary-author.md),
-[ADR-0018](0018-core-starters-repository-boundary.md)
+[ADR-0018](0018-core-starters-repository-boundary.md),
+[ADR-0019](0019-sealed-manifest-runtime-pipeline.md)
+
+> **Supersession note:** consumer ownership remains durable, but the exact
+> `site.yaml`, generated `site.ts`, and parser-free array workflow below is
+> historical. The sealed source → parse → link → compile pipeline in ADR-0019
+> is current; source names and generated code are optional caller concerns.
 
 ## Context
 

package/docs/adr/0011-adapter-port-spec.md

@@ -1,14 +1,17 @@
 # ADR-0011: Adapter port spec
 
-**Status:** Accepted for v0.1.0. Amended 2026-08-13 to remove the unimplemented adapter stub.
+**Status:** Superseded for Core storage and Admin composition by ADR-0019.
+Retained as the alpha.7 Cloudflare adapter record; `DatabaseDriver` is now an
+implementation detail of the SQLite/D1 `MantleStorageAdapter`, while the asset
+contract belongs to optional `@aotter/mantle-admin`.
 
-**Date:** 2026-05-04 (revised 2026-05-09, 2026-05-10, 2026-08-11, and 2026-08-13).
+**Date:** 2026-05-04 (revised 2026-05-09, 2026-05-10, 2026-08-11, 2026-08-13, and 2026-08-22).
 
 ## Context
 
 `@aotter/mantle-runtime` is adapter-agnostic. It owns dispatcher, entry-writer, view executor, content-ops, render pipeline, boot validation, and MCP JSON-RPC dispatch. It depends only on `@aotter/mantle-spec` and a small set of TypeScript interfaces it defines itself.
 
-`@aotter/mantle-cloudflare` is the only adapter shipping in v0.1.0. It binds the runtime's interfaces against Cloudflare Workers' D1 and ASSETS, and supplies a Better Auth instance (per ADR-0014) for sign-in + MCP bearer validation. OAuth grant KV remains adapter-owned infrastructure and is not a runtime port.
+`@aotter/mantle-cloudflare` is the only adapter shipping in v0.1.0. It binds the runtime's interfaces against Cloudflare Workers' D1 and ASSETS, and supplies a Better Auth instance (per ADR-0014) for sign-in and MCP authorization. Better Auth 1.7 stores OAuth grants in D1; auth storage remains adapter-owned infrastructure, not a runtime port.
 
 This ADR fixes the contract so:
 - Future adapter authors have a stable target.
@@ -19,7 +22,14 @@ The POC accumulated multiple half-decisions about this seam (POC ADR-0015 docume
 
 ## Decision
 
-**Two required adapter ports**, defined as TypeScript interfaces in `@aotter/mantle-runtime/src/domain/port/`. Concrete adapters provide implementations and inject them into `createCmsRuntime`.
+> 0.1.2 amendment: the portable storage input is
+> `PreparedMantleStorage` (`EntryRepository & EntryReader` plus
+> `ViewQueryExecutor`). Hosts either use an official storage adapter with an
+> already-owned client/handle or implement those semantic ports over their own
+> tables. `AssetServer` moved out of Runtime to optional Mantle Admin. The
+> two-port contract below is the historical alpha.7 shape.
+
+Alpha.7 had **two required adapter ports**, defined as TypeScript interfaces in `@aotter/mantle-runtime/src/domain/port/`. Concrete adapters provided implementations and injected them into `createCmsRuntime`.
 
 | Port | Surface |
 |---|---|
@@ -140,6 +150,10 @@ The admin SPA itself lives in `@aotter/mantle-admin-ui` as a pre-built `dist/`.
 
 ## How adapters wire ports
 
+> Historical alpha.7 example. Current convenience composition is
+> `createMantleWorker`; ADR-0014's 2026-08-22 amendment replaces the OAuth
+> provider shown below with Better Auth 1.7 MCP/CIMD.
+
 ```ts
 // simplified Cloudflare adapter wiring (post-ADR-0014, amended
 // 2026-05-15 by PR #193's OAuth carve-out).

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

@@ -2,17 +2,18 @@
 
 ## Status
 
-Accepted. Amended 2026-05-14, 2026-05-15, 2026-06-30, 2026-07-15, and
-2026-08-03.
+Accepted. Amended 2026-05-14, 2026-05-15, 2026-06-30, 2026-07-15,
+2026-08-03, and 2026-08-22.
 
 ## Date
 
-2026-05-09 (last amended 2026-08-03)
+2026-05-09 (last amended 2026-08-22)
 
 > **Current authority:** the original decision below records the rejected
-> Better-Auth-for-MCP design. The 2026-05-15 carve-out and 2026-07-15 unified
-> authorization amendment are authoritative where they conflict. Operational
-> guidance in "How to apply" is maintained against the current adapter/runtime.
+> Better-Auth-for-MCP design. The 2026-08-22 Better Auth 1.7 amendment is
+> authoritative where it conflicts with the 2026-05-15 carve-out; the
+> 2026-07-15 normalized authorization boundary still applies. Operational
+> guidance is maintained against the current adapter/runtime.
 
 ## Context
 
@@ -520,3 +521,107 @@ Dynamic membership, billing, and entitlement state remains consumer-owned.
 does not introduce a Policy atom or an entitlement service. See
 [`API and MCP authorization`](../api-mcp-authorization.md) for the public API
 and end-to-end examples.
+
+## Amendment — 2026-08-22: Better Auth 1.7 MCP and CIMD convergence
+
+Issue #734 revisits the 2026-05-15 compatibility carve-out after Better Auth
+1.7 shipped a dedicated `@better-auth/mcp` package, resource-bound JWT grants,
+and the MCP 2026-07-28 Client ID Metadata Document profile. These are the
+missing capabilities that originally forced Mantle to keep a second OAuth
+authority.
+
+The Cloudflare adapter now uses one Better Auth instance for staff identity,
+OAuth authorization, consent, client registration/discovery, token issuance,
+and MCP resource verification. `@cloudflare/workers-oauth-provider` and Core's
+`OAUTH_KV` requirement are removed. This amendment supersedes only the
+2026-05-15 transport carve-out; adapter ownership, the curated `Auth` facade,
+fresh D1 staff-role checks, the single `mcp` compatibility scope, and normalized
+`HandlerContext.auth` remain unchanged.
+
+### Provider and resource boundary
+
+`createAuth` keeps its general OAuth-provider capability and adds MCP as an
+explicit curated mode, implemented by composing `jwt()` and
+`@better-auth/mcp`. It is not replaced by an MCP-only factory and no Better
+Auth passthrough is exposed. Standard Workers bind one canonical protected
+resource, `${PUBLIC_ORIGIN}/mcp`. Both `/mcp` and `/mcp/staff` accept tokens for
+that resource; `/mcp/staff` remains a stricter server-side role projection, not
+a second OAuth audience.
+
+The adapter continues to verify and normalize credentials before calling the
+portable runtime. Better Auth imports remain confined to the default
+implementation. A host app may still implement the `Auth` facade or mount its
+own low-level routes; the generated convenience path does not make Better Auth
+a runtime dependency.
+
+MCP request verification reuses Better Auth's DPoP binding primitive and its
+database-backed replay store. Bearer JWTs remain valid; a DPoP-bound JWT is
+accepted only with a matching request proof, method, URL, token hash, and
+single-use proof id. Raw-token callers cannot bypass that request boundary.
+
+### CIMD is primary; DCR is bounded compatibility
+
+The MCP mode composes:
+
+```ts
+mcp({ resource, loginPage, consentPage, scopes: ["mcp"], ... })
+cimd({
+  fetchClientMetadataResource,
+  metadataProfile: "mcp-2026-07-28",
+})
+```
+
+Cloudflare's native `fetch` is the metadata transport only when the Worker has
+`global_fetch_strictly_public` enabled. The runtime flag makes the subrequest
+use Cloudflare's public-Internet routing boundary; Better Auth owns URL
+validation, timeout, response limits, redirect refusal, revalidation, and the
+bounded fetch governor. Mantle does not add a DNS resolver, socket HTTP client,
+or generic transport abstraction.
+
+Unauthenticated DCR remains enabled only for older MCP clients. Its lifetime
+stays at the removed provider's 90-day default. Better Auth expires confidential
+registration secrets; Mantle additionally prunes only expired ownerless DCR
+rows (`clientDiscoveryId`, user owner, and reference owner all absent) on
+OAuth traffic. CIMD-owned and operator-managed clients are never cleanup
+candidates. Cleanup is storage hygiene: failures are logged and do not turn a
+valid authorization request into an outage. No cron or second registry is
+introduced.
+
+Better Auth's `oauthClient` row is the connected-client authority. It retains
+the discovery provenance and validated name, URI, redirect URIs, application
+type, and private server metadata. The consent UI reads only the public
+secret-free projection. Remote client metadata is not copied into portable
+`HandlerContext` or deferred event envelopes.
+
+### Breaking migration
+
+All Better Auth packages upgrade together to 1.7. The D1 schema adopts account
+issuer identity, resource/client relationships, resource-bound token and
+consent fields, discovery provenance, and replay storage required by the
+installed plugins. Removed `validAudiences` configuration becomes the one
+explicit MCP resource; generic upstream OAuth adopts the 1.7 social sign-in and
+callback contract.
+
+This is an alpha breaking migration. KV registrations, grants, and opaque
+tokens are not migrated into D1 because their issuer/resource provenance cannot
+be established safely; MCP clients reconnect through CIMD or DCR. Existing
+pre-1.7 alpha auth databases are reset and re-bootstrapped rather than receiving
+a guessed account issuer backfill.
+
+The authorization endpoints consequently move from `/oauth/*` to Better
+Auth's `/api/auth/oauth2/*` discovery-advertised endpoints. No compatibility
+aliases are retained: existing KV client identifiers are invalid after the
+authority change regardless, and standards-compliant clients rediscover the
+new endpoints.
+
+### Downstream ownership
+
+Starters remove their obsolete OAuth package and `OAUTH_KV` binding while
+retaining `global_fetch_strictly_public`. Landing opts its custom `createAuth`
+construction into the same MCP mode. Landing may keep an `OAUTH_KV` binding for
+its own launch/bootstrap state; that storage is unrelated to the removed Core
+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.

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

@@ -19,9 +19,30 @@ Core (SDK producer)
   -> published npm contract
 mantle-starters (external consumer and bundle producer)
   -> immutable provision bundle
-mantle-landing (provisioner)
+mantle-landing (provisioner)   Core CLI (`mantle create`)
 ```
 
+> **Amended 2026-08-19 (#699).** The chain above is no longer linear. Core's
+> umbrella CLI is now also a consumer of the immutable bundle: `mantle create`
+> resolves the official `v${packageVersion}` starter tag, renders it through
+> the environment-neutral module Core owns, and writes a local project. Core
+> is therefore both the upstream producer of the npm contract and a downstream
+> consumer of the release train it starts.
+>
+> This does not move starter content into Core, so the decision below stands:
+> starters still author the bundles and still validate the published SDK as an
+> external consumer. What changed is the supporting argument. Two consequences
+> are worth stating rather than rediscovering:
+>
+> - **The published-consumer guarantee is now proven twice.** `mantle create`
+>   materializes a project that installs the published package, so a break in
+>   the npm contract fails in Core's own release smoke as well as in starter CI.
+> - **Reconsideration input 1 is being answered.** #699 replaces the release
+>   order so a candidate is published under a temporary dist-tag, validated
+>   against the exact packed artifacts, and only then promoted. That was listed
+>   below as an unresolved prerequisite for any future merge; when it lands,
+>   this ADR should record it as resolved rather than pending.
+
 The repositories were originally split because premium starters needed a
 private ACL. That reason does not determine where public starters must live,
 and the private premium repository remains a stub. A later decision, #191,