@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

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

@@ -1,281 +0,0 @@
-# ADR-0011: Adapter port spec
-
-**Status:** Superseded for Core storage and Admin composition by ADR-0019 and
-for SQLite/D1 physical storage by ADR-0024.
-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, 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 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.
-- PR reviewers can mechanically check "does this commit add a CF-specific type to runtime?"
-- The runtime can refactor freely as long as the port shapes stay stable.
-
-The POC accumulated multiple half-decisions about this seam (POC ADR-0015 documented an aspirational `cms-astro`-internal discipline; POC ADR-0029 retired Astro and dissolved the seam; the rebuild closes it properly).
-
-## Decision
-
-> 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`, 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;
-adapters render on origin misses and may use their native HTTP response cache.
-The Cloudflare adapter uses version-local Workers Cache, which runs before the
-Worker for eligible anonymous responses.
-
-Optional feature ports may also live in `domain/port/`, but they are
-not part of the first-run adapter contract until a feature is enabled.
-For v0.1.x media hosting and deferred lifecycle dispatch:
-
-| Optional port | Surface |
-|---|---|
-| `MediaStorage` | Object-storage-shaped media upload/commit/public URL/delete contract for **public** media. Cloudflare may implement with R2, but runtime must not import R2 types. |
-| `DeferredHookDispatcher` | Queue-shaped dispatcher for at-least-once `after_*` lifecycle delivery. Cloudflare may implement with Workers Queues; other adapters may use a queue, job runner, or leave it unset. |
-
-These optional ports must not force first-run provisioning to create R2
-resources. Publication starters can carry external image URLs without a
-media storage implementation.
-
-`DeferredHookDispatcher.enqueue` confirms adapter acceptance only. It cannot
-make an entry write and an external queue send atomic. The versioned envelope
-contains a stable event id plus captured Trigger names; handlers combine them
-for idempotency because retries and ambiguous producer fallback can duplicate
-execution. Deferred envelopes carry persisted entry data and normalized actor
-metadata, never arbitrary original request input. Adapter-specific retry,
-delay, batch, DLQ, and message-size settings remain outside manifest grammar.
-The operational reference is
-[`docs/deferred-lifecycle-queues.md`](https://github.com/aotter/mantle/blob/main/docs/deferred-lifecycle-queues.md).
-
-Identity, session, OAuth, and role enforcement are adapter-owned per
-ADR-0014. The runtime does not define `SessionRepository`,
-`OAuthVerifier`, `UserRepository`, or `StaffRepository` ports. Adapters
-must provide an auth surface compatible with their HTTP framework and
-must pass authenticated user/staff context into runtime dispatchers.
-
-### Public vs private media — two buckets, two ports
-
-`MediaStorage` deliberately models **public-only** semantics:
-
-- `getPublicUrl()` returns an unconditional public URL. Reads bypass
-  the Worker entirely (`MEDIA_PUBLIC_URL_BASE` → CDN → R2).
-- `MediaAsset.publicUrl` is frozen at commit time and embedded directly
-  into entry data (e.g. `posts.coverUrl`). This is intentional: for
-  public assets the URL is permanent, the read path is hot, and adding
-  a Worker round-trip on every render would defeat the cost / latency
-  model.
-- The CORS config on the underlying R2 bucket scopes browser PUTs to
-  the admin origin only.
-
-**Private content (subscription-gated, fan-club, signed-GET, etc.)
-will be a *separate* port and a *separate* R2 bucket in v0.2.** Two
-buckets, two ports — not one port with a `visibility` flag. Reasons:
-
-1. **Bucket-level isolation.** Private bucket disables public access
-   at the bucket level, so the worst-case "leaked private object" bug
-   is structurally impossible.
-2. **Different read paths.** Private reads MUST go through a Worker
-   route (`/api/media/private/<key>` or similar) that runs the policy
-   gate (staff predicate, subscription check, signed cookie, etc.)
-   before resolving the object. The Worker either streams via
-   `bucket.get()` or 302s to a short-lived signed GET URL.
-3. **Different cost models.** Public bucket is CDN-cached, near-zero
-   marginal cost. Private bucket charges Worker invocations on every
-   read. Operator should opt into the cost knowingly, not by accident.
-4. **Different MCP tool surface.** `create_private_media_upload` /
-   `commit_private_media_upload` keeps the closed-list semantics of
-   each tool tight. Agents pick the upload type explicitly.
-5. **No migration debt.** Public assets stay public forever; their
-   `coverUrl` strings remain valid. Private fields use a different
-   schema field shape (`x-mcp-hint: private-media-image` over an
-   opaque `assetId`, resolved at render time through the policy gate).
-   No batch update over already-published entries.
-
-Adding `PrivateMediaStorage` in v0.2 is a purely additive change to
-the port set and the runtime. Current `MediaStorage` callers are
-untouched. The Worker route, the use cases, the MCP tools, and the
-adapter all live in their own module — they compose alongside the
-public path rather than retrofitting it.
-
-### `DatabaseDriver`
-
-```ts
-// packages/mantle-runtime/src/domain/port/DatabaseDriver.ts
-export interface DatabaseDriver {
-  /** Run a parameterised query. Returns a typed result-set object — adapters
-   *  normalise their native driver into this shape. */
-  prepare(sql: string): PreparedStatement;
-  /** Multi-statement transaction. Adapters guarantee atomicity. */
-  batch(stmts: ReadonlyArray<PreparedStatement>): Promise<BatchResult[]>;
-  /** Migration runner — invoked by `bootInit` once per isolate. */
-  migrations: MigrationRunner;
-}
-```
-
-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 adapter can wrap its driver to the same shape.
-
-### `AssetServer`
-
-```ts
-export interface AssetServer {
-  /** Resolve a request to a static asset (typically under `/admin/assets/*`).
-   *  Returns null if the asset doesn't exist — the adapter's HTTP layer
-   *  then falls back to the SPA catchall. */
-  fetch(req: Request): Promise<Response | null>;
-}
-```
-
-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).
-import {
-  createAuth,
-  createCmsRef,
-  createMcpApiHandler,
-  createOAuthProvider,
-  mountAuthorize,
-  mountServerEndpoints,
-  AssetsAssetServer,
-  D1DatabaseDriver,
-} from "@aotter/mantle-cloudflare";
-
-const auth = createAuth({
-  database: env.DB,
-  baseURL: env.PUBLIC_ORIGIN,
-  secret: env.BETTER_AUTH_SECRET,
-  methods: [
-    {
-      kind: "social",
-      provider: "github",
-      options: {
-        clientId: env.GITHUB_CLIENT_ID,
-        clientSecret: env.GITHUB_CLIENT_SECRET,
-      },
-    },
-  ],
-  bootstrapOwner: env.ADMIN_GITHUB_LOGIN
-    ? { match: "github-login", value: env.ADMIN_GITHUB_LOGIN }
-    : undefined,
-});
-const cms = createCmsRef({
-  manifests,
-  handlers,
-  bindings: {
-    db: new D1DatabaseDriver(env.DB),
-    assets: new AssetsAssetServer(env.ASSETS),
-  },
-  auth,
-});
-const app = new Hono();
-app.all("/api/auth/*", (c) => auth.handler(c.req.raw));
-mountServerEndpoints(app, cms);
-mountAuthorize(app, { auth }); // /oauth/authorize consent gate
-
-// `OAuthProvider` must be the top-level worker entry — it injects
-// `env.OAUTH_PROVIDER` helpers the consent handler needs, and the
-// claude.ai MCP client requires it to discover AS metadata.
-export default createOAuthProvider({
-  defaultHandler: app,
-  apiHandlers: {
-    "/mcp/staff": createMcpApiHandler({ ref: cms, surface: "staff" }),
-    "/mcp":       createMcpApiHandler({ ref: cms, surface: "public" }),
-  },
-});
-```
-
-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.
-There's no module-global state holding adapter-specific bindings.
-
-## Consequences
-
-**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 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 adapter author reads this ADR + [`docs/adapter-guide.md`](https://github.com/aotter/mantle/blob/main/docs/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.
-
-## 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.
-
-**(b) Concrete CF types in runtime** — Just `import type { D1Database } from "@cloudflare/workers-types"` directly into `mantle-runtime`. Treat "CF-only" as a v0.1.0 reality, defer the abstraction. **Rejected**: this is what the POC did (via `cms-server` having implicit assumptions about D1 shape) and it's the trap the rebuild exists to escape. Once concrete CF types land in runtime, removing them is a multi-PR uplift later. Cheaper to do it right at v0.1.0.
-
-**(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. 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.
-
-## How to apply
-
-When you're authoring `@aotter/mantle-runtime` code:
-
-1. If you reach for a CF-specific type, **stop**. Define a method on a port instead.
-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:
-
-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.
-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 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.
-- [ ] CI lint: forbid `@cloudflare/*` / `D1Database` / `KVNamespace` imports in `mantle-runtime/` (post-v0.1.0; manual review until then)
-
-## See also
-
-- ADR-0007 — AI as primary author. Adapter port discipline serves the "AI debuggable" loop: a missing port method surfaces as a structured Diagnostic at boot, not a runtime 500 in production.
-- ADR-0009 — consumer-supplied manifests. Manifests don't care about ports; ports don't care about manifests. The two abstractions compose cleanly.

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

@@ -1,161 +0,0 @@
-# ADR-0012: Views as named REST and MCP read surfaces
-
-**Status:** Accepted for v0.1.0. Amended to match the shipped public/staff
-surface and authorization contract.
-
-**Date:** 2026-05-05; amended 2026-08-03
-
-## Context
-
-mantle ships two read-side surfaces and one write-side surface:
-
-- **Templates** (rendered HTML / Markdown / `llms.txt`) — composed by the consumer's `TemplateRegistry` from runtime APIs. The starter blog uses these for `/{locale}/posts/{slug}` etc.
-- **MCP tools** — the staff surface exposes entry authoring and lifecycle
-  tools; both public and staff surfaces expose `query_view_<name>` for Views
-  assigned to that surface.
-- **HTTP Triggers** — write-side endpoints declared by the consumer (`Trigger.source.kind: http`, methods `POST | PUT | PATCH | DELETE` only). Per ADR-0001 grammar, **`GET` is intentionally absent** because read endpoints belong to Views, not Procedures.
-
-What was missing: a stable, consumer-facing **public REST read surface**. The starter blog had no JSON API at all. The CMS needed an answer to "I'm a downstream service that wants `posts` filtered by locale — how do I read?" without forcing every consumer to hand-write a route handler that re-implements filtering.
-
-This ADR answers that question: **every parsed View is a named read surface**.
-Views default to public and auto-expose `GET /api/views/<view-name>` plus a
-matching public MCP tool. `surface: staff` moves both transports to the guarded
-staff surfaces. Schemas do not get a public REST surface at all.
-
-(Schemas remain available on the **admin** REST surface — `/admin/api/*` — which lands with the admin UI commit and is auth-gated to staff. That's a separate cut and out of scope here.)
-
-## Decision
-
-### 1. Public reads route through Views, never Schemas
-
-Adding `Schema.spec.expose.rest` and letting collections leak directly to public REST was the alternative considered. We rejected it because:
-
-- `Schema` declares the **storage shape**; entries carry `draft` / internal status, server-stamped fields, and per-row data the author may not have intended for the public. `contact-messages` is the canonical example — direct `GET /api/contact-messages` would be a privacy bug by default.
-- `View` already has the right semantics: a named query with explicit `filter` / `fields` / `orderBy` / `limit`. Auto-exposing it as REST ratifies what the manifest already declares.
-- One way to do public reads is simpler than two. The Mantle thesis ("agents write config; runtime carries complexity") gets stronger when the contract surface stays narrow.
-
-### 2. URL shape: `/api/views/<view-name>`
-
-No version prefix. `apiVersion: cms.mantle.aotter.net/v1` is the manifest-grammar version, locked under v0.1 grammar discipline; the public REST URL doesn't need to repeat it.
-
-`<view-name>` is `View.metadata.name` verbatim. Authors are free to pick kebab-case (`recent-posts`) or any URL-safe identifier; the runtime mounts the route as-is.
-
-### 3. Views auto-expose on one declared surface
-
-`View.spec.surface` uses the closed `public | staff` vocabulary and defaults to
-`public`:
-
-- public Views mount at `GET /api/views/<name>` and appear as
-  `query_view_<name>` on `/mcp`;
-- staff Views mount at `GET /admin/api/views/<name>` behind the live staff-role
-  gate and appear only on `/mcp/staff`.
-
-The adapter filters the View set before constructing each MCP dispatcher, so a
-guessed public tool call cannot reach a staff View. `View.spec.requires` then
-applies the same static predicates and optional guard Procedure on REST and MCP
-calls. Surface selects transport visibility; authorization decides whether the
-verified caller may execute the View.
-
-We still reject a second `expose.rest` switch. A View is externally queryable
-on exactly one surface; internal-only helpers remain TypeScript code.
-
-### 4. Pagination knobs are reserved query-string names
-
-REST callers pass `?page=<1-indexed>&show=<page-size>`. MCP callers pass the
-same reserved names as tool arguments. Internally the runtime emits
-`LIMIT show OFFSET (page-1)*show`.
-
-`page` / `show` / `cursor` are reserved names. The parser rejects any `View.spec.params.properties.<name>` colliding with these (`VIEW_PARAMS_RESERVED_NAME`). The author owns the rest of the query-string namespace.
-
-The alternative ("let `filter` express arithmetic so the author writes their own page→offset math") was rejected as a grammar-discipline violation: v0.1 filter is a closed AST (`eq` / `gt` / `gte` / `lt` / `lte` plus boolean `and` / `or`) and adding arithmetic would drag in operator precedence, type coercion, and a closed-enum-vs-expression debate that distracts from shipping.
-
-`View.spec.limit` is the **server-enforced cap** on `show`; if the caller passes `?show=10000` and the View declares `limit: 50`, the runtime trims to 50.
-
-### 5. Filter comparison `value` accepts a `{ $param: <name> }` sentinel
-
-Static Views are useful (`recent-posts`); param-driven Views are essential (`posts-by-locale?locale=zh-TW`). Until this ADR, filter values were literals, which forced one View per parameter combination — unworkable for `tag` / `locale` / `author` queries.
-
-The grammar gains:
-
-```yaml
-spec:
-  params:
-    type: object                            # required, must be type: object
-    properties:
-      locale: { type: string }              # scalar leaf types
-    required: [locale]                      # v0.1.0 enforces required-only
-  filter:
-    eq: { field: locale, value: { $param: locale } }
-```
-
-The `$param` discriminator key was chosen to match the JSON Schema `$ref` convention. The later closed `{ "$ctx.user": "id" }` sentinel follows the same `$<name>` shape; `$now` remains unimplemented.
-
-Boot validator gates:
-- `View.spec.params` MUST be `type: object` with `properties` declared (`VIEW_PARAMS_INVALID_SHAPE`).
-- Reserved names rejected (`VIEW_PARAMS_RESERVED_NAME`).
-- 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`).
-
-### 6. Response envelope is `{ rows, page, show, hasMore }`
-
-```json
-{
-  "ok": true,
-  "data": {
-    "rows": [...],
-    "page": 1,
-    "show": 20,
-    "hasMore": true
-  }
-}
-```
-
-`rows` is intentionally a generic name (matches OLAP family conventions in `aotter-mantle`). v0.1.0 Views are list-of-projected-entries, but join + group-by results land in v0.1.x and may use a different envelope (`data.value` for scalars, `data.tree` for hierarchies). The choice of `rows` over `entries` keeps the door open without forcing a v0.1.0 manifest declaration of output shape.
-
-`hasMore = (rows.length === effectiveShow)` — the lazy semantics. We do **not** issue a separate `COUNT(*)` query, and we do not pull `LIMIT n+1` to probe. If the server returns exactly `show` rows, the caller may or may not have more; if fewer, we know definitively. The trade is one false-positive on the boundary case (caller asks for next page, gets empty) in exchange for no extra round-trip per request.
-
-### 7. Param coercion happens at the transport boundary
-
-Query strings arrive as strings; `View.spec.params` declares the JSON Schema type. The Cloudflare adapter (`coerceViewParams` in `mountServerEndpoints.ts`) coerces per-property:
-
-| `params.<name>.type` | Coercion |
-|---|---|
-| `string` | identity |
-| `integer` | `parseInt` (rejects non-canonical / float-like input) |
-| `number` | `Number()` |
-| `boolean` | `"true"` / `"false"` only |
-| `enum` | string matched against the enum array |
-
-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).
-
-## Current limits
-
-- 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.
-
-## Consequences
-
-**Authors gain:**
-- REST and MCP read surfaces for free — declare a View and choose public or
-  staff visibility once.
-- Single mental model for "how do consumers and agents read?": always Views.
-- Cheap pagination + dynamic filters without hand-writing handlers.
-
-**Authors lose:**
-- 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.
-
-**Reviewers / future contributors should:**
-- Reject any PR adding `Schema.spec.expose.rest` or a similar Schema-level public-read flag.
-- Reject any PR introducing a second public read surface (e.g. `/api/<collection>` shortcut).
-- Require REST and MCP mounts to filter by the same `View.spec.surface` value,
-  and keep authorization in the shared `ExecuteViewUseCase` path.
-- Reject any PR that lets `filter` reference state outside the declared `params` (e.g. `{ $env: ... }`, `{ $cookie: ... }`) without a matching ADR amendment.

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

@@ -1,154 +0,0 @@
-# ADR-0013: Agent-provisioned consumer projects
-
-## Status
-
-Superseded by [ADR-0021](0021-retire-starter-scaffolding.md) for 0.1.2 and
-later. Historical pre-stable install flow only.
-
-## Date
-
-2026-05-09
-
-## Context
-
-> **Historical 2026-06-27 direction, no longer current:** Mantle landing creates the GitHub repo from
-> `mantle-starters` `provision-bundles/<type>.json`, commits the blank
-> or type bundle, and connects Cloudflare Workers CI when possible.
-> Do not extend the old `create-mantle launch --session` or
-> `provision:up` path.
-
-mantle is not optimized for a human developer reading a long
-installation guide and hand-editing boilerplate. The intended v0.1.0
-entry path is:
-
-1. The official site asks for a small set of launch choices: site name,
-   project/repo slug, starter/theme, locale(s), visibility, and GitHub
-   account context supplied through the Mantle GitHub App when present.
-2. The site creates a short-lived launch session and produces a one-line
-   `create-mantle launch --session ...` command for the user's agent.
-   The older localized starting prompt plus pinned Skill URL remains a
-   fallback when the session path is unavailable.
-3. A coder agent runs in the user's chosen parent directory, claims the
-   session, scaffolds immediately, initializes local launch state, installs
-   npm packages, validates it, and then proceeds toward Cloudflare
-   provision.
-4. The deployed site gives the owner an admin sign-in path and an MCP
-   URL for ongoing content operations.
-
-This is a different architecture from "SDK docs plus templates." The
-template must be safe for agents to mutate, the package dependency
-story must work outside this monorepo, and first-run content cannot
-depend on an operator MCP session that does not exist yet.
-
-## Decision
-
-Consumer projects are provisioned by an agent, using repo-hosted
-Skills as the operational contract.
-
-The source of truth for first-run scaffold intent is the website-created
-launch session. It carries structured values such as `archetype`,
-`theme`, `features`, `locales`, `project_name`, `site_name`,
-`github_owner`, `admin_github_login`, and `repo` intent. The install
-Skill should consume a valid launch session instead of running a long
-generic interview before scaffold. Prompt-first install remains the
-fallback when no valid launch session is available.
-
-The launch session is not a general provider credential. It authorizes
-the scaffold values the website just collected, and the agent writes
-only non-secret resumable state such as `.mantle/launch-state.json`.
-Cloudflare API tokens, GitHub OAuth App client secrets, paid-provider
-features, and custom domains still require explicit user authorization
-during provision.
-
-Published npm packages are the runtime dependency source. Starter files
-may still be copied from the GitHub repo or a release tag, but
-`setup:site` rewrites `workspace:*` dependencies to the requested
-`@aotter/mantle-*` npm version before `pnpm install`. This keeps
-consumer projects independent from the monorepo and avoids private-repo
-token friction in the install path.
-
-Starter-owned setup scripts are the only supported way to rewrite
-standard template fields. Agents should not hand-edit `wrangler.toml`,
-`src/mantleConfig.ts`, `package.json`, or similar standard fields when a
-starter script exists. Hand edits are reserved for actual product
-customization.
-
-Starter source is copied from pinned public GitHub refs by downloading
-source tarballs, not by leaving a normal clone in place. The extracted
-project initializes its own Git repo and should only set `origin` after
-the user creates or selects a user-owned repository. This avoids agents
-accidentally pushing back to the template source.
-
-First-run content is not seeded during real-user install/provision.
-Provision creates the operating surface first: public site, owner
-sign-in, and Staff/User MCP URLs. After owner sign-in, the operating
-agent interviews the owner and asks whether to create initial
-pages/posts through Staff MCP or admin authoring. `seed:initial` and
-fixture data are reserved for tests and contributor local dev.
-
-Cloudflare provisioning is owned by the starter's provision script. It
-creates the required free-path resources, writes bindings/secrets,
-deploys once with the real origin, and returns the handoff URLs.
-Agents should not decompose this into ad-hoc Wrangler steps unless
-they are debugging a failed provision.
-
-## Consequences
-
-- Skills become part of the compatibility surface. Updating install or
-  provision behavior requires updating the relevant Skill in the same
-  change.
-- Starter templates must remain script-configurable. Adding a new
-  standard field without updating `setup:site` is a regression for
-  agent provisioning.
-- npm publishing must precede realistic end-user provisioning tests.
-  `file:` or workspace dependencies are acceptable only for local SDK
-  development.
-- The first-run success criterion is product-level: public site,
-  owner sign-in, MCP URL, and an owner-approved path to create initial
-  content through MCP/admin authoring. A deployed but unauthored site
-  can be a valid intermediate checkpoint, not a direct-seed failure.
-- Provisioning must preserve the no-credit-card path. Optional paid or
-  billing-gated features must be opt-in after the site is already live.
-
-## Alternatives
-
-- **Human-first docs with manual edits.** Rejected because it makes the
-  non-coder path fragile and forces agents to infer boilerplate edits
-  from prose.
-- **Git dependency only.** Rejected for the default path because private
-  repos and Git authentication add friction. Git refs remain useful for
-  copying starter files, not for installed runtime dependencies.
-- **Direct seed creates the initial content.** Rejected for real-user
-  onboarding because it bypasses the same operating path we want to
-  validate. MCP/admin authoring after owner sign-in is the product
-  loop; fixtures and seed utilities remain for tests/local dev.
-- **One universal starter.** Rejected. The current publication starter
-  is intentionally fixed-manifest during bootstrap; custom workflows
-  belong in `blank` or future dedicated starters.
-
-## How to apply
-
-- If a website launch session supplies structured install values, run
-  `create-mantle launch --session ...` first and ask content/voice
-  questions later.
-- If only a website prompt supplies structured install values, consume
-  them directly and only confirm public/resource-name-impacting details.
-- Run the starter's `setup:site` script before installing
-  dependencies.
-- Download starter source as a pinned tarball/zip, extract it, run
-  `git init`, and only add a remote that belongs to the user.
-- Keep first-run provision scripts on the free Cloudflare path unless
-  the user explicitly opts into a paid feature.
-- After provisioning, hand the user to: view the site, sign in as
-  owner, then connect an MCP-capable agent to create/operate content.
-
-## Implementation status
-
-- `skills/install/SKILL.md` and `docs/skills/provision/SKILL.md` encode the
-  current agent workflow, including the launch-session fast path.
-- `aotter/mantle-starters` hosts `packages/create-mantle`, whose
-  `launch --session` mode validates the session before writing files.
-- Starters ship `provision:up` where supported; `seed:initial` remains
-  a test/contributor utility, not part of real-user provisioning.
-- Current prerelease package versions are documented in
-  `docs/release-process.md`.