@aotter/mantle 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/adr/0010-locale-and-translates.md

@@ -6,7 +6,7 @@
 
 **Deciders**: phsu
 
-**Related**: [ADR-0001](0001-four-atom-manifest-model.md) (the Schema atom this extends; §"Future grammar discipline" covers the v0.1-vs-DRAFT window this lands in).
+**Related**: [ADR-0001](0001-four-atom-manifest-model.md) (the Schema atom this extends).
 
 ---
 
@@ -70,7 +70,7 @@ matches the principle that locale is opt-in.
 
 The boot validator only inspects the manifest at this layer. It
 checks shape (every `localized: true` Schema is well-formed, every
-`translates:` block resolves) and rejects DRAFT keys; it does **not**
+`translates:` block resolves) and rejects unsupported keys; it does **not**
 read D1 to confirm that the site actually has any locales configured.
 That cross-check is deferred to runtime (Layer 3).
 
@@ -206,29 +206,35 @@ apiVersion: cms.mantle.aotter.net/v1
 kind: Schema
 metadata: { name: products }
 spec:
+  title: Products
+  localized: false
   schema:
+    type: object
     properties:
       slug: { type: string }
       sku:  { type: string }
       price: { type: number }
     required: [slug, sku, price]
-  unique: [slug]
+  uniqueIndexes: [[slug]]
 ---
 apiVersion: cms.mantle.aotter.net/v1
 kind: Schema
 metadata: { name: product-translations }
 spec:
+  title: Product translations
   localized: true
   translates:
     parent: products
     on: slug
   schema:
+    type: object
     properties:
       slug: { type: string }
+      locale: { type: string }
       title: { type: string }
       description: { type: string }
-    required: [slug, title]
-  unique: [[slug, locale]]
+    required: [slug, locale, title]
+  uniqueIndexes: [[slug, locale]]
 ```
 
 `Schema.spec.translates` declares the parent/child relationship as
@@ -245,9 +251,6 @@ all treat the relation as known structure rather than convention:
 - Admin UI groups parent + per-locale translation entries together.
 - Boot validate enforces parent existence and join-field presence in
   both parent and child JSON Schemas (manifest shape, no D1 reads).
-- View executor (when `View.join` lands per the future-grammar
-  appendix) can auto-join parent + child without per-View
-  configuration.
 - AI authoring an entry against the child knows from the manifest
   that there's a parent it must reference by `slug`.
 
@@ -262,6 +265,8 @@ Validation rules introduced:
 - `TRANSLATES_REQUIRES_LOCALIZED` — `translates: ...` declared on a
   Schema where `localized` isn't `true`. (A non-localized translation
   table makes no sense.)
+- `TRANSLATES_REQUIRES_CONTENT_FIELD` — the child declares only its join
+  field and `locale`, with no locale-specific payload to translate.
 
 ## Consequences
 

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

@@ -1,16 +1,17 @@
 # ADR-0011: Adapter port spec
 
-**Status:** Accepted for v0.1.0. Amended 2026-08-11 to remove the rendered-artifact `KvCache` port.
+**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, and 2026-08-11).
+**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-netlify` is a v0.2 stub — README only. It exists in the package layout as an engineering forcing function: with N=1 adapter, "adapter-agnostic" silently rots in PR review (a `D1Database` import slips into runtime, then a second, then five). With a second adapter visible in the workspace (even if its impl is a TODO), reviewers have somewhere to point when blocking the slip.
+`@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.
@@ -21,11 +22,18 @@ 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 |
 |---|---|
-| `DatabaseDriver` | All persistent state — `entries`, `site_config`, `staff`, `users`, `approvals`, plus migrations. |
+| `DatabaseDriver` | All persistent state — `entries`, `site_config`, `staff`, `users`, plus migrations. |
 | `AssetServer` | Static-asset serving for the admin SPA. The runtime hands the adapter an asset path + `Request`; the adapter returns a `Response` with the right MIME and caching. |
 
 Rendered public artifacts are not a second storage model. D1 stays canonical;
@@ -123,7 +131,7 @@ export interface DatabaseDriver {
 
 The runtime never sees `D1Database`, `Pool` (postgres), or any concrete driver. The `prepare` / `batch` shape is intentionally close to D1's surface (which is itself close to the SQLite C API) — that's the smallest common denominator. Adapters wrap their native driver to this shape.
 
-The CF adapter's impl is a thin proxy over `env.DB` (D1). A future Postgres-via-Hyperdrive adapter wraps `pg` to the same shape; a Netlify adapter could wrap Neon, Supabase, or PlanetScale.
+The CF adapter's impl is a thin proxy over `env.DB` (D1). A future Postgres adapter can wrap its driver to the same shape.
 
 ### `AssetServer`
 
@@ -136,12 +144,16 @@ export interface AssetServer {
 }
 ```
 
-CF adapter: wraps `env.ASSETS.fetch(req)`. Future: filesystem read, S3+CDN, Netlify static-publish dir.
+CF adapter: wraps `env.ASSETS.fetch(req)`. Other adapters can use a filesystem or object storage.
 
 The admin SPA itself lives in `@aotter/mantle-admin-ui` as a pre-built `dist/`. The adapter binds `AssetServer` to whatever serves that `dist/`; the runtime knows nothing about static asset serving except "ask the port and pass through the response."
 
 ## 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).
@@ -198,7 +210,7 @@ export default createOAuthProvider({
 });
 ```
 
-The runtime gets three required adapter ports (`db`, `kv`, `assets`)
+The runtime gets two required adapter ports (`db`, `assets`)
 alongside manifests, handlers, templates, and site defaults. Auth is
 owned by the adapter layer that mounts HTTP/MCP surfaces; the runtime
 receives authenticated context when the adapter dispatches requests.
@@ -208,19 +220,16 @@ There's no module-global state holding adapter-specific bindings.
 
 **Hard-enforced boundaries**:
 - `@aotter/mantle-runtime` MUST NOT import `D1Database`, `KVNamespace`, `Fetcher` (CF Workers ASSETS), `@cloudflare/*`, or any other adapter-specific type. CI will lint for this; PR reviewers can grep.
-- A new required port can be added only by amending this ADR and updating ALL adapters (CF + Netlify stub) in the same change. Optional feature ports must be documented here and must state when adapters are required to implement them.
+- A new required port can be added only by amending this ADR and updating every shipping adapter in the same change. Optional feature ports must be documented here and must state when adapters are required to implement them.
 - Removing a port is also possible (if a port is found to overlap or be unnecessary), again by amending this ADR.
 
 **Discoverability for adapter authors**:
-- A future Bun/Deno/Vercel/Netlify port author reads this ADR + [`docs/adapter-guide.md`](../adapter-guide.md), implements the two required ports, then wires boot and HTTP/MCP surfaces. That's the contract. No hidden state, no implicit assumptions about the HTTP framework.
+- A future adapter author reads this ADR + [`docs/adapter-guide.md`](../adapter-guide.md), implements the two required ports, then wires boot and HTTP/MCP surfaces. That's the contract. No hidden state, no implicit assumptions about the HTTP framework.
 
 **Test ergonomics**:
 - Each port is small and isolated. Tests can mock individual ports without spinning up D1 or an OAuth provider.
 - The runtime's test suite exercises against in-memory port impls; the adapter's test suite exercises the binding against real CF resources via `wrangler dev` or live deploy.
 
-**The Netlify stub's job**:
-- The `@aotter/mantle-netlify` package's README declares a public commitment to an N>=2 adapter world. If a PR adds CF-specific code to runtime, reviewers point at the stub README and reject. The stub doesn't have to ship code to perform its function — its existence is the constraint.
-
 ## Alternatives considered
 
 **(a) Single mega-port** — One `RuntimePorts` interface containing every method (db.prepare, assets.fetch, media.createUpload, …). **Rejected**: leaks the entire surface onto every adapter. Discrete ports keep change blast radius per port.
@@ -229,7 +238,7 @@ There's no module-global state holding adapter-specific bindings.
 
 **(c) Function-injection (no interfaces, just functions)** — Runtime accepts a record of functions such as `{ dbPrepare, assetFetch, sessionRead, … }`. **Rejected**: TypeScript interfaces are more discoverable and document grouping.
 
-**(d) Plugin pattern (each port is a separate package)** — `@aotter/mantle-port-database`, `@aotter/mantle-port-kv`, etc., and runtime depends on one package per port. **Rejected**: the port set is too small to warrant per-port packages. The current 5-package structure (spec / runtime / admin-ui / cloudflare / netlify) is already at the boundary of "too many"; splitting further increases the maintenance tax without useful benefit. Ports are TS interfaces in `mantle-runtime`'s `src/domain/port/` directory — that's enough.
+**(d) Plugin pattern (each port is a separate package)** — `@aotter/mantle-port-database`, `@aotter/mantle-port-kv`, etc., and runtime depends on one package per port. **Rejected**: the port set is too small to warrant per-port packages. Ports are TypeScript interfaces in `mantle-runtime`'s `src/domain/port/` directory — that's enough.
 
 **(e) gRPC / wire-protocol seam** — Make ports a network protocol so adapters can be in any language. **Rejected**: the runtime is not an external service, it's a TypeScript library that adapters compose into a single Worker / Function. Network seam adds latency, deployment complexity, and operational surface for zero authoring benefit. The ports are in-process; they always will be.
 
@@ -241,27 +250,26 @@ When you're authoring `@aotter/mantle-runtime` code:
 2. If a port is missing the method you need, **amend this ADR first** in the same PR, then add the method. Adapters in the same PR.
 3. Tests must use port mocks (in-memory implementations) — never reach into a real D1 from runtime tests.
 
-When you're authoring an adapter (`@aotter/mantle-cloudflare` for v0.1.0; future `mantle-netlify`, `mantle-bun`, …):
+When you're authoring an adapter:
 
 1. Read `mantle-runtime/src/domain/port/`. Implement each required port against your runtime's primitives.
 2. Compose the runtime via `createCmsRuntime({ db, assets, manifests, handlers, templates, siteDefaults, ... })`.
 3. Call `runtime.bootInit()` once before serving CMS traffic.
-4. Bind to your HTTP framework — Hono on CF, Netlify Functions handler, raw `fetch` Worker, …
+4. Bind to your HTTP framework.
 5. Provide adapter-owned auth and map sessions/scopes/roles into runtime handler context.
 6. Bundle `@aotter/mantle-admin-ui`'s `dist/` via your runtime's static-asset surface and bind `AssetServer` to it.
 
 When you're reviewing a PR:
 
 1. Grep the diff for `@cloudflare`, `D1Database`, `KVNamespace`, `Fetcher` — flag any occurrence in `mantle-runtime/`.
-2. If a new port method shows up, check it's also reflected in this ADR + the Netlify stub README.
-3. If a port shape changed, all 2 adapters (CF real, Netlify stub) get updated in the same PR.
+2. If a new port method shows up, check it is also reflected in this ADR.
+3. If a port shape changed, every shipping adapter gets updated in the same PR.
 
 ## Implementation status
 
 - [x] Required port interface files live in `packages/mantle-runtime/src/domain/port/*.ts`.
 - [x] Cloudflare required port implementations live in `packages/adapters/cloudflare/src/bindings/*.ts`.
 - [x] Optional feature port `MediaStorage` (public bucket) is declared but not required by first-run adapters. `PrivateMediaStorage` is v0.2.
-- [x] Netlify stub README references this ADR.
 - [ ] CI lint: forbid `@cloudflare/*` / `D1Database` / `KVNamespace` imports in `mantle-runtime/` (post-v0.1.0; manual review until then)
 
 ## See also

package/docs/adr/0012-views-as-public-rest.md

@@ -96,8 +96,6 @@ Boot validator gates:
 - Every `{ $param: <name> }` ref MUST resolve to a declared param (`VIEW_FILTER_PARAM_REF_UNKNOWN`).
 - Every `{ $param: <name> }` ref MUST appear in `params.required` (`VIEW_FILTER_PARAM_REF_NOT_REQUIRED`).
 
-The required-only rule is a v0.1.0 simplification. v0.1.x will promote optional-with-skip semantics (filter clauses referencing missing optional params evaluate to TRUE / no-op) — the runtime compiler already implements drop semantics for forward compatibility, but the parser rejects it today so authors get a clear "not yet" diagnostic.
-
 ### 6. Response envelope is `{ rows, page, show, hasMore }`
 
 ```json
@@ -130,12 +128,11 @@ Query strings arrive as strings; `View.spec.params` declares the JSON Schema typ
 
 Required params not present → `400 INPUT_VALIDATION_FAILED`. Coercion failure → `400 INPUT_VALIDATION_FAILED`. Unknown query-string keys are silently ignored (lenient v0.1.0; strict mode is a candidate v0.1.x flag).
 
-## Out of scope (deferred)
+## Current limits
 
-- **`Trigger.target.view`** (lifecycle/projection triggers fired by Views). Tracked separately as a v0.2 grammar move.
-- **`spec.output.kind`** (declaring scalar / tree / tabular result shape per View). Lands with join + group-by support in v0.1.x.
-- **Optional param-ref drop semantics in the parser.** Runtime is already implemented; parser promotes when v0.1.x lands.
-- **DRAFT filter operators** (`contains` / `in` / `like` / `not`). v0.1 keeps comparison operators closed to `eq` / `gt` / `gte` / `lt` / `lte`; field-to-field comparisons remain out of scope.
+- Param refs must be required.
+- Filter operators are closed to `eq` / `gt` / `gte` / `lt` / `lte`;
+  field-to-field comparisons are unsupported.
 - **Row-level policy rewriting.** `requires` authorizes the whole View; it does
   not inject per-row visibility predicates. Consumer-specific membership,
   payment, or entitlement checks belong in the optional guard Procedure.
@@ -149,13 +146,12 @@ Required params not present → `400 INPUT_VALIDATION_FAILED`. Coercion failure
 - Cheap pagination + dynamic filters without hand-writing handlers.
 
 **Authors lose:**
-- A View per filter combination (until DRAFT operators land). `posts-by-locale` plus `posts-by-tag` plus `posts-by-locale-and-tag` would be three Views in v0.1.0.
+- Each named query shape remains an explicit View.
 - No internal-only View surface; choose public/staff or keep the query in a TS
   helper.
 
 **Runtime gains:**
 - One executor and response shape cover public/staff REST and MCP reads.
-- Forward-compat for join / group-by / aggregation: envelope generalises by Views declaring `output.kind` later.
 
 **Reviewers / future contributors should:**
 - Reject any PR adding `Schema.spec.expose.rest` or a similar Schema-level public-read flag.

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
 
@@ -44,7 +45,7 @@ A 2026 Workers-friendly auth library — [Better Auth](https://better-auth.com)
 - **MCP plugin (`mcp`)** — purpose-built on top of the OAuth 2.1 provider for MCP DCR; auto-mounts `.well-known/oauth-authorization-server` + `.well-known/oauth-protected-resource`, exposes `auth.api.getMcpSession()` for protected-resource validation
 - Account linking with policies (verified-email match + reauth requirement)
 
-Better Auth depends on a Kysely / Drizzle / Prisma adapter for the database, not on any Cloudflare-specific service. The auth machinery becomes platform-agnostic — porting to Netlify / Bun / Deno is config-only.
+Better Auth depends on a Kysely / Drizzle / Prisma adapter for the database, not on any Cloudflare-specific service. The auth machinery remains platform-agnostic.
 
 ## Decision (historical baseline; amended below)
 
@@ -64,7 +65,7 @@ Adopt Better Auth as the SDK's full auth surface. It owns:
 
 The auth runtime stops being an adapter port. `OAuthVerifier` port + `WorkersOAuthVerifier` adapter are deleted. Validating bearer tokens at `/mcp` and `/staff/mcp` becomes `auth.api.getMcpSession(req.raw)` — a direct Better Auth API call, no port indirection.
 
-This makes the runtime more platform-agnostic, not less: Better Auth runs on Workers (D1 via Kysely), Bun (sqlite), Node (postgres) without code changes. Future Netlify / partner adapters get the auth surface for free.
+This makes the runtime more platform-agnostic, not less: Better Auth runs on Workers (D1 via Kysely), Bun (sqlite), and Node (postgres) without runtime changes.
 
 ### 2. `staff` table → `user.role` via Better Auth admin plugin
 
@@ -81,23 +82,18 @@ admin({
 
 The manifest grammar predicate `requires.auth.all: [{ "ctx.staff": ["editor"] }]` evaluates against `session.user.role` at runtime. Closed enum membership unchanged.
 
-What we lose: `grantedBy` / `grantedAt` audit trail. v0.1.0 doesn't need this; v0.1.x can re-add via `additionalFields` on user, or via a separate append-only `staff_audit_log` table.
+### 3. Two explicit MCP surfaces
 
-### 3. Two MCP routes, surface-derived from manifest predicate
-
-`/mcp` and `/staff/mcp` are mounted side-by-side from boot. v0.1.0 ships the conservative partition: `/staff/mcp` exposes all staff authoring/lifecycle tools and requires `mcp:staff` plus an admin role; `/mcp` exposes only read-only `query_view_<name>` tools and requires `mcp:read`. The v0.2+ extension point is **automatic** surface partition derived from each Procedure's `requires.auth.all` predicate:
-
-```
-predicate contains ctx.staff: [...]    → tool exposed on /staff/mcp only
-predicate only ctx.user / no predicate → tool exposed on /mcp only
-```
+`/mcp` and `/staff/mcp` are mounted side-by-side from boot. `/staff/mcp`
+exposes staff authoring/lifecycle tools and `/mcp` exposes declared public
+Views and Procedures. An MCP Trigger explicitly chooses `surface: public |
+staff`; the target's `requires.auth` still gates every call.
 
 Tool partition rules:
 
 - Per-collection auto-emitted authoring tools (`create_draft_<schema>`, `update_draft_<schema>`) — predicate baked-in to require `ctx.staff: [contributor+]`; route to `/staff/mcp`
 - `list_entries` / `get_entry` / `request_publish` / `archive_entry` / `unpublish_entry` — staff-only (return drafts, mutate state); `/staff/mcp` only
-- `query_view_<name>` (auto-emitted from each parsed View, mirroring the existing `/api/views/<name>` REST shape) — public; `/mcp` only
-- v0.2 community / v0.2.x fan-club user-facing writes (comment, reaction, subscribe, ...) — predicate `ctx.user` or `ctx.user.subscription`; `/mcp`
+- `query_view_<name>` follows `View.spec.surface`.
 
 ### 4. Scope-aware DCR via Better Auth `oauthProvider`
 
@@ -140,7 +136,7 @@ The token can carry `role` via `customAccessTokenClaims` for caller convenience,
 
 ### 6. Single auth surface, no port indirection
 
-Auth is no longer an adapter port. `mantle-runtime` does NOT define an auth port and `createCmsRuntime()` does not accept auth. Adapter packages (`mantle-cloudflare`, future `mantle-netlify`) construct the Better Auth instance with the right database adapter for their platform and keep it in the adapter-owned HTTP/MCP mount layer.
+Auth is no longer an adapter port. `mantle-runtime` does NOT define an auth port and `createCmsRuntime()` does not accept auth. Adapter packages construct the Better Auth instance with the right database adapter for their platform and keep it in the adapter-owned HTTP/MCP mount layer.
 
 The adapter uses Better Auth to validate sessions, MCP bearer tokens, scopes, and roles, then passes authenticated user/staff context into runtime dispatchers. Better Auth remains platform-agnostic, but it is not a runtime dependency.
 
@@ -188,7 +184,7 @@ This makes the implicit explicit. The SDK's auth surface is committee-curated; u
 
 ### 8. Path to `@aotter/mantle-better-auth` separate package (deferred)
 
-When `mantle-netlify` lands, the Better Auth wiring moves to its own package. Today the seam is in place:
+Each adapter owns its Better Auth wiring. Today the seam is:
 
 - `Auth` interface lives in the adapter (could move to runtime or a separate package without breaking the contract — adapters consume the type, not the implementation).
 - `createAuth.ts` is the only file with `import { betterAuth }` (~290 LOC, no Cloudflare-binding-specific code outside `config.database: D1Database`).
@@ -201,10 +197,10 @@ The future split looks like:
 @aotter/mantle-runtime           ← ports + use cases (today)
 @aotter/mantle-better-auth       ← createAuth + EmailSender impls + appleClientSecret (new, when needed)
 @aotter/mantle-cloudflare        ← Workers adapter; depends on (or accepts) Auth-shape (today)
-@aotter/mantle-netlify           ← Netlify adapter; same shape (v0.2)
+future adapter                   ← same contract, implemented when needed
 ```
 
-The pivot point — when to extract — is when the second adapter (`mantle-netlify`) needs the same wiring. Until then, in-place co-location is cheaper than a new package boundary.
+The pivot point — when to extract — is when a second adapter needs the same wiring. Until then, in-place co-location is cheaper than a new package boundary.
 
 ## Consequences
 
@@ -241,7 +237,6 @@ The pivot point — when to extract — is when the second adapter (`mantle-netl
 - `databaseHooks.user.create.after` for `ensureBootstrapOwner` semantics
 - Two `/.well-known/oauth-protected-resource/*` metadata endpoints (Better Auth helpers)
 - Public View MCP tools: dispatcher emits `query_view_<name>` on `/mcp`.
-- Future manifest grammar tools: dispatcher will read `Procedure.requires.auth.all` to route user-facing tools to `/mcp` or `/staff/mcp`.
 - Skills + docs updates for the dual MCP URL handoff
 
 ### Backward compatibility
@@ -263,20 +258,9 @@ User MCP URL:   https://<worker>.workers.dev/mcp           (give to visitors / t
 The publication starter repo's production smoke recipe uses `/mcp/staff`
 for the MCP operator smoke step.
 
-### Future-proof for v0.2
-
-The end-user MCP via DCR + role-gated content (community / fan-club) requires no architectural change — just:
-
-- Enable Better Auth `socialProviders.google` / `.apple` (config-only)
-- Enable `magicLink` and `emailOTP` plugins (config + `EmailSender` wiring already in place)
-- Promote DRAFT manifest grammar from POC ADR-0005 — `Schema.spec.policies.readable: ctx.user` and `requires.auth.all: [{ ctx.user.subscription: [premium] }]`
-- Add `additionalFields: { subscriptionTier: ... }` on user when Stripe entitlement lands
-
-No config flag flips, no surface migration. The dispatcher partition rule (predicate → surface) handles new tool emission automatically.
-
 ### Platform agnosticism
 
-By removing `@cloudflare/workers-oauth-provider` and routing auth through Better Auth, the SDK no longer depends on any CF-specific auth service. A future Netlify adapter constructs a Better Auth instance backed by a Netlify-compatible D1 / postgres / sqlite database; the rest of the runtime + dispatcher + skills + prompts work unchanged. ADR-0011 (adapter port spec) is amended: the `OAuthVerifier` port disappears; auth becomes a direct constructor argument with platform-agnostic Better Auth as the type.
+By removing `@cloudflare/workers-oauth-provider` and routing auth through Better Auth, the SDK no longer depends on any CF-specific auth service. A future adapter can construct Better Auth against its database while the runtime + dispatcher + skills + prompts stay unchanged. ADR-0011 (adapter port spec) is amended: the `OAuthVerifier` port disappears; auth becomes adapter-owned, with platform-agnostic Better Auth as the type.
 
 ## Alternatives considered
 
@@ -346,13 +330,6 @@ Phase 2 (v0.1.x):
 - Magic-link + email-OTP plugins enabled (need `ResendEmailSender` wired)
 - Account-linking with reauth UI in publication starter
 
-Phase 3 (v0.2+, with community / fan-club):
-
-- POC ADR-0005 DRAFT grammar promotion: `Schema.spec.policies.readable`, `requires.auth.all: ctx.user.subscription[*]`
-- Subscription tier on user (`additionalFields`)
-- Stripe webhook → entitlement updater
-- Community / fan-club starter manifests
-
 ## How to apply
 
 When reviewing or implementing a change that touches auth, MCP routing, or roles:
@@ -544,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,