@aotter/mantle 0.0.11-alpha.16 → 0.0.11-alpha.19

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

@@ -0,0 +1,272 @@
+# ADR-0011: Adapter port spec
+
+**Status:** Accepted for v0.1.0. New ADR. Replaces the architectural concerns previously tracked in POC ADR-0015 (`cms-astro` internal seam discipline).
+
+**Date:** 2026-05-04 (revised 2026-05-09 to absorb ADR-0014; revised 2026-05-10 to remove obsolete pre-ADR-0014 port text).
+
+## 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, KV, ASSETS, and supplies a Better Auth instance (per ADR-0014) for sign-in + MCP bearer validation.
+
+`@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.
+
+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
+
+**Three required adapter ports**, defined as TypeScript interfaces in `@aotter/mantle-runtime/src/domain/port/`. Concrete adapters provide implementations and inject them into `createCmsRuntime`.
+
+| Port | Surface |
+|---|---|
+| `DatabaseDriver` | All persistent state — `entries`, `site_config`, `staff`, `users`, `approvals`, plus migrations. |
+| `KvCache` | Publish-pipeline cache — pre-rendered HTML, `.md` mirrors, `llms.txt` per locale. Read-mostly, written by the publish pipeline. |
+| `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. |
+
+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 durable 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 durable `after_*` lifecycle hooks. 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.
+
+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-via-Hyperdrive adapter wraps `pg` to the same shape; a Netlify adapter could wrap Neon, Supabase, or PlanetScale.
+
+### `KvCache`
+
+```ts
+export interface KvCache {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, opts?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** List keys with a prefix — used by sitemap / llms.txt aggregation. */
+  list(prefix: string, cursor?: string | null): Promise<{ keys: string[]; cursor: string | null }>;
+}
+```
+
+CF adapter: Workers KV. Future: Redis, FS, S3-compatible store.
+
+### `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)`. Future: filesystem read, S3+CDN, Netlify static-publish dir.
+
+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
+
+```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,
+  KvCacheBinding,
+} from "@aotter/mantle-cloudflare";
+
+const auth = createAuth({
+  database: env.DB,
+  baseURL: env.PUBLIC_ORIGIN,
+  secret: env.BETTER_AUTH_SECRET,
+  methods: [
+    {
+      kind: "social",
+      provider: "github",
+      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),
+    kv: new KvCacheBinding(env.KV),
+    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 three required adapter ports (`db`, `kv`, `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 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.
+- 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 three 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 / KV / 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, kv.get, assets.fetch, media.createUpload, …). **Rejected**: leaks the entire surface onto every adapter. Adapter authors who only want to swap KV would have to touch the mega-port impl. 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: `{ dbPrepare, kvGet, kvPut, sessionRead, … }`. **Rejected**: TypeScript interfaces are more discoverable (an adapter author IDE-jumps from `DatabaseDriver` to its surface; jumping from `dbPrepare` is harder). Interfaces also document grouping; functions don't.
+
+**(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.
+
+**(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 / KV from runtime tests.
+
+When you're authoring an adapter (`@aotter/mantle-cloudflare` for v0.1.0; future `mantle-netlify`, `mantle-bun`, …):
+
+1. Read `mantle-runtime/src/domain/port/`. Implement each required port against your runtime's primitives.
+2. Compose the runtime via `createCmsRuntime({ db, kv, 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, …
+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.
+
+## 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
+
+- 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

@@ -0,0 +1,137 @@
+# ADR-0012: Views as the public REST surface
+
+**Status:** Accepted for v0.1.0. New ADR.
+
+**Date:** 2026-05-05
+
+## 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** — agent-facing CRUD over the entry chokepoint. Every Schema gets `create_draft_<n>` / `update_draft_<n>` per-collection authoring tools plus generic tools (`list_entries`, `get_entry`, `request_publish`, `unpublish_entry`, `archive_entry`).
+- **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 auto-exposes `GET /api/views/<view-name>`**, and Schemas do not get a public REST surface at all. Public reads always go through a named query.
+
+(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; opt-out is "don't write a View"
+
+We considered adding `View.spec.expose: { rest: false }`. Rejected — the shape `View` already has IS "public read API". Authors who want a private named query write a TypeScript helper and call `runtime` directly from their template.
+
+### 4. Pagination knobs are reserved query-string names
+
+Public callers pass `?page=<1-indexed>&show=<page-size>`. 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. Future sentinels (`$now`, `$ctx.user`) follow the same `$<name>` shape; this ADR adds none of them.
+
+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`).
+
+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
+{
+  "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 adapter 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).
+
+## Out of scope (deferred)
+
+- **MCP tools for Views.** MCP is for agents doing ops; readers don't need a separate MCP tool when they have a stable REST endpoint. Reconsider in v0.2 if downstream agent tooling demands it.
+- **`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.
+- **Auth on the public View REST surface.** v0.1.0 Views are public-read by definition. Member-gated reads land with the member system in v0.2.
+
+## Consequences
+
+**Authors gain:**
+- Public REST surface for free — declare a View, get an endpoint.
+- Single mental model for "how do consumers read?": always Views.
+- 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.
+- No way to write a "private" named query — moves to a TS helper.
+
+**Runtime gains:**
+- One auto-mount path covers every public-read use case for v0.1.0.
+- 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.
+- Reject any PR introducing a second public read surface (e.g. `/api/<collection>` shortcut).
+- 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

@@ -0,0 +1,147 @@
+# ADR-0013: Agent-provisioned consumer projects
+
+## Status
+
+Accepted (new)
+
+## Date
+
+2026-05-09
+
+## Context
+
+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 `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`.