@aotter/mantle 0.0.11-alpha.63 → 0.0.11-alpha.64

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

@@ -0,0 +1,155 @@
+# ADR-0018: Keep Core and public starters in separate repositories
+
+**Status:** Accepted for now; revisit only under the triggers below
+
+**Date:** 2026-08-02
+
+**Related:** [#542](https://github.com/aotter/mantle/issues/542),
+[#191](https://github.com/aotter/mantle/issues/191),
+[#97](https://github.com/aotter/mantle/issues/97),
+[#99](https://github.com/aotter/mantle/issues/99)
+
+## Context
+
+Core and the public starter source currently form a producer-consumer
+boundary:
+
+```text
+Core (SDK producer)
+  -> published npm contract
+mantle-starters (external consumer and bundle producer)
+  -> immutable provision bundle
+mantle-landing (provisioner)
+```
+
+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,
+made Core, starters, and landing mirror the same version and connected them
+with an automated release fanout.
+
+The fanout accumulated real costs: release-only commits, `main`/`develop`
+backports, fallback tag creation, commit-subject detection, cross-repository
+credentials, and a Core-skill drift check that can skip when the sibling
+checkout is unavailable. Issue #542 therefore proposed moving public starters
+back into this repository.
+
+That operational pain does not by itself prove source cohesion. The separate
+starter repository now provides a useful invariant that did not exist in the
+original rationale: the canonical generated-site fixture consumes published
+SDK packages and cannot silently link Core workspace packages.
+
+A heuristic review of merged PRs from 2026-06-03 through 2026-08-02 also did
+not show sustained majority co-change. After excluding release, promotion,
+backport, and dependency PRs, 9 of 64 Core PRs explicitly referenced starters,
+and 13 of 79 starter PRs explicitly referenced Core. Explicit references
+undercount forced adaptations, so these numbers are directional rather than a
+permanent threshold. They do show that release noise is not a sufficient proxy
+for product coupling.
+
+## Decision
+
+Keep `aotter/mantle` and `aotter/mantle-starters` separate for now.
+
+The boundary is a release-contract boundary, not an ACL boundary:
+
+- Core produces versioned npm artifacts.
+- Starters validate those artifacts as an external consumer and produce
+  immutable provision bundles.
+- Landing consumes the released bundle and provisions end-user repositories.
+
+Do not merge or archive the starters repository until the following no-regret
+work has landed:
+
+1. **Pre-publish downstream harness.** Validate starters against the exact SDK
+   tarballs that would be published, preferably through an ephemeral registry,
+   before a release tag exists.
+2. **Fail-closed Core-skill drift check.** Compare starter-vendored skills with
+   the installed SDK package in normal starter CI; never depend on an optional
+   sibling checkout.
+3. **One release controller.** Replace the bump/tag/dispatch/fallback chain and
+   remove avoidable `main`/`develop` backport noise without moving source code.
+4. **Repository-agnostic updates.** Make generated sites resolve a configured
+   bundle base URL instead of hard-coding `aotter/mantle-starters`.
+
+Issue #542 remains the work and reconsideration tracker. This ADR is the
+canonical explanation of the repository-boundary decision. The current
+mechanics belong in `docs/release-process.md`; implementation details should
+not be duplicated here.
+
+## Reconsideration triggers
+
+Re-evaluate a monorepo after the four items above land if either signal persists:
+
+- the release path still needs at least two special-case workaround fixes per
+  quarter, such as fallback tags, backports, or commit-message detectors; or
+- SDK contract changes require same-release starter adaptations more often than
+  roughly once per month, making atomic cross-repository work a recurring cost.
+
+A future merge proposal must also resolve:
+
+- how the same tagged starter version is validated against the exact package
+  artifacts before npm publication;
+- a real last-legacy-version to first-new-location update for an existing site;
+- landing dispatch and release credentials, which do not disappear merely by
+  moving starters;
+- premium-repository direction;
+- nested pnpm/Dependabot/lockfile CI, licensing, open issues, and repository
+  history migration.
+
+These are decision inputs, not a disguised permanent prohibition. A monorepo
+is appropriate if its atomicity benefit remains material after the release
+machinery is simplified.
+
+## Consequences
+
+### Positive
+
+- The published-package consumer guarantee remains structural rather than
+  simulated by workspace exclusions and realpath assertions.
+- The four improvements reduce risk and complexity under either eventual
+  repository shape.
+- Existing generated-site update URLs remain valid while the updater contract
+  is made portable.
+- Starter-only product work keeps an independent source boundary.
+
+### Negative
+
+- Cross-repository changes cannot land in one atomic PR.
+- A release event still crosses repository boundaries and needs a narrowly
+  scoped credential or GitHub App.
+- Release noise remains until the controller and branch flow are simplified.
+- Core-skill drift remains possible until the fail-closed check lands.
+
+## Alternatives
+
+### Merge immediately
+
+Rejected. The proposed release order cannot both start from an immutable tag
+and regenerate a same-version registry-backed starter lockfile after publish.
+Existing generated sites also cannot cross the hard-coded repository boundary
+without a bridge.
+
+### Keep the repositories separate without simplifying the release path
+
+Rejected. The current fanout complexity and silent skill-check escape hatch are
+real defects; retaining the boundary does not justify retaining those defects.
+
+### Declare that the repositories must never merge
+
+Rejected. The current boundary is valuable, but it is replaceable with explicit
+and tested invariants if future co-change and release evidence justify the cost.
+
+## How to apply
+
+- Treat starters as a downstream SDK consumer in CI and release design.
+- Do not add starter projects to the Core pnpm workspace as a shortcut for
+  cross-contract validation.
+- Track the four prerequisite changes and future merge evidence in #542.
+- Any future repository-move proposal must supersede this ADR and #191
+  explicitly, with the transition tests listed above.
+
+## Implementation status
+
+The repository-boundary decision is active. The four no-regret improvements are
+tracked from #542 and may land independently; none requires a repository move.

package/docs/adr/README.md

@@ -8,15 +8,17 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 |---|---|---|
 | [0001](0001-four-atom-manifest-model.md) | Four-atom manifest model (Schema / View / Procedure / Trigger). Folds POC ADR-0005 (grammar discipline) and POC ADR-0006 (multi-doc YAML). | Accepted (refreshed) |
 | [0002](0002-closed-enums-for-bindings.md) | Closed enums for `x-mantle-bind` and `ctx.*` predicates. | Accepted (refreshed) |
-| [0007](0007-ai-as-primary-author.md) | AI is the primary author of consumer projects; SDK contract is the three feedback loops + structured diagnostics. Folds POC ADR-0013 (role-split surfaces). | Accepted (refreshed) |
-| [0008](0008-structured-diagnostic-shape.md) | Diagnostic shape: code, phase, severity, path, value, expected, message, candidates, suggestion. zod-translation per PR #81. | Accepted (refreshed) |
-| [0009](0009-consumer-supplied-manifests.md) | Consumers ship their own manifest YAML. SDK parses + caches; never embeds. | Accepted (refreshed) |
+| [0007](0007-ai-as-primary-author.md) | AI is the primary author of consumer projects; SDK contract is three pre-serve feedback loops, runtime diagnostics, and coder/operator role surfaces. | Accepted + amended |
+| [0008](0008-structured-diagnostic-shape.md) | Diagnostic shape for validate/boot/runtime failures, with a reserved consumer-test phase; measured harnesses keep purpose-shaped reports. | Accepted + amended |
+| [0009](0009-consumer-supplied-manifests.md) | Consumers own manifest YAML; the installed CLI emits the parser-free runtime module and handler types. Core ships no application manifests. | Accepted + amended |
 | [0010](0010-locale-and-translates.md) | Locale 3-layer (manifest / D1 site_config / data field) + translates pattern. Boot decoupled from `site_config` (issue #60 fix). | Accepted (refreshed) |
 | [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. CF impl + Netlify stub. | Accepted (new) |
-| [0012](0012-views-as-public-rest.md) | Views auto-expose `GET /api/views/<name>` as the public REST read surface. Schemas never get a public REST endpoint. Filter comparison values accept `{ $param: <name> }`; `?page=&show=` reserved for pagination. | Accepted (new) |
+| [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
 | [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. Superseded for first launch by landing provision bundles. | Superseded |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | Better Auth for staff sign-in (D1 session); the MCP OAuth surface carves out to `@cloudflare/workers-oauth-provider` (KV grant store) at top level. The two meet at `/oauth/authorize` where the consent handler reads the Better Auth session. MCP splits into `/mcp/staff` (write, admin-role) and `/mcp` (read, any signed-in). Scope advertised as `["mcp"]` (single non-colon) because claude.ai rejects colon-shaped scopes. Auth port disappears; runtime takes Better Auth instance directly. See § "Amendment 2026-05-15". | Accepted + amended |
+| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns the curated Better Auth identity/session facade and top-level `@cloudflare/workers-oauth-provider` MCP transport. Both normalize verified callers into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
 | [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
+| [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
+| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Accepted for now |
 
 ## Reading order
 
@@ -50,7 +52,7 @@ The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accum
 
 ## Contributing a new ADR
 
-1. Pick the next number (currently 0017).
+1. Pick the next number (currently 0019).
 2. File: `docs/adr/<NNNN>-<kebab-title>.md`.
 3. Sections: Status, Date, Context, Decision, Consequences, Alternatives, How to apply, Implementation status.
 4. Link from this README's table.

package/docs/cloudflare-low-level-composition.md

@@ -0,0 +1,94 @@
+# Low-level Cloudflare Worker composition
+
+Use `createMantleWorker` unless the application must own the top-level Worker
+assembly. This copyable fixture keeps Mantle's standard bindings, Auth,
+Admin/API routes, OAuth/MCP dispatch, cache policy and redacted error boundary,
+while adding one application-owned post-response Queue audit across every route.
+
+```ts
+import { Hono } from "hono";
+import {
+  createCmsRef,
+  createConventionalAuth,
+  createConventionalBindings,
+  createMcpApiHandler,
+  createOAuthProvider,
+  mountAuthorize,
+  mountServerEndpoints,
+  runMantleWorkerRequest,
+  setupIncompleteAuthResponse,
+  type MantleCloudflareEnv,
+} from "@aotter/mantle/cloudflare";
+import { manifest } from "../.mantle/generated/site.js";
+
+interface Env extends MantleCloudflareEnv {
+  readonly AUDIT_QUEUE: Queue<{
+    readonly kind: "request-complete";
+    readonly path: string;
+    readonly status: number;
+  }>;
+}
+
+let assembled: ReturnType<typeof assemble> | undefined;
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return runMantleWorkerRequest(async () => {
+      assembled ??= assemble(env);
+      const incomplete = await setupIncompleteAuthResponse(request, assembled.auth);
+      const response = incomplete ?? await assembled.fetch(request, env, ctx);
+      ctx.waitUntil(env.AUDIT_QUEUE.send({
+        kind: "request-complete",
+        path: new URL(request.url).pathname,
+        status: response.status,
+      }));
+      return response;
+    });
+  },
+} satisfies ExportedHandler<Env>;
+
+function assemble(env: Env) {
+  const bindings = createConventionalBindings(env);
+  const auth = createConventionalAuth(env);
+  const ref = createCmsRef({ manifests: manifest, bindings, auth });
+  const app = new Hono<{ Bindings: Env }>();
+
+  mountServerEndpoints(app, ref);
+  mountAuthorize(app, { auth, loginPath: "/admin/sign-in" });
+  app.get("/cache-probe", () => new Response("public", {
+    headers: { "cache-control": "public, s-maxage=60" },
+  }));
+
+  const provider = createOAuthProvider<Env>({
+    defaultHandler: {
+      fetch: (request, workerEnv, ctx) => app.fetch(request, workerEnv, ctx),
+    },
+    apiHandlers: {
+      "/mcp/staff": createMcpApiHandler<Env>({ ref, surface: "staff" }),
+      "/mcp": createMcpApiHandler<Env>({ ref, surface: "public" }),
+    },
+  });
+  return { auth, fetch: provider.fetch.bind(provider) };
+}
+```
+
+Keep the conventional `DB`, `KV` and `OAUTH_KV` bindings and
+`nodejs_compat`; add the Queue producer in `wrangler.jsonc`:
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "queues": {
+    "producers": [
+      { "binding": "AUDIT_QUEUE", "queue": "my-site-audit" }
+    ]
+  }
+}
+```
+
+After copying, the Worker entry, request audit, custom route and Queue contract
+belong to the application. Mantle still owns the imported adapters and
+standard route behavior; update them through the package version. Do not copy
+their source or replace Auth, MCP or cache handling locally. A copied
+composition has no automatic merge path back to `createMantleWorker`; keep it
+only while the custom top-level lifecycle remains necessary.

package/docs/design-atoms.md

@@ -5,19 +5,19 @@
 >
 > **Status**: v0.1 grammar lock. Atoms are shipped; rich sub-spec
 > grammar (policies, recursive views, temporal predicates, quotas,
-> projection triggers, builtin handler ops, lifecycle Triggers) is
+> projection triggers, cron/queue sources, and extended lifecycle hooks) is
 > reserved as **DRAFT** — see "Future grammar" appendix. Editorial
 > lifecycle is the one shipped grammar key whose runtime is **deferred
-> to v0.1.x**: the boot validator accepts the key shape but rejects
-> `lifecycle: editorial` with a clear "v0.1.x" diagnostic until the
-> approval-queue runtime lands.
+> to v0.1.x**: parser and boot accept the shape, while
+> `request_publish` rejects it with `LIFECYCLE_NOT_IN_V010` until the approval
+> queue lands. Do not use editorial for a v0.1 publishing workflow.
 >
 > **This is the reference manual** — what the system is. For *why* it
 > ended up this shape (alternatives considered, trade-offs accepted),
 > see the Architecture Decision Records under [`docs/adr/`](adr/README.md).
 > For the SDK's contract with its primary author (CLI feedback loops,
-> error catalog, test recipes), see
-> [`docs/authoring-contract.md`](authoring-contract.md).
+> structured diagnostics, deterministic authoring), see
+> [ADR-0007](adr/0007-ai-as-primary-author.md).
 
 ## TL;DR
 
@@ -31,7 +31,7 @@ primitives Postgres has shipped for 30 years.
 | Our atom | Postgres equivalent | Externally exposed by itself? | Has user code? |
 |---|---|---|---|
 | **`Schema`** | `CREATE TABLE` | no (manipulated via View / Procedure) | no |
-| **`View`** | `CREATE VIEW` | **yes** (auto-mounted at `GET /api/views/<name>` — `SELECT FROM` analogue, see ADR-0012) | no |
+| **`View`** | `CREATE VIEW` | **yes** (auto-mounted on its declared public/staff REST and MCP surface; see ADR-0012) | no |
 | **`Procedure`** | `CREATE FUNCTION ... LANGUAGE plpgsql` | **no** (transport-agnostic; needs a `Trigger` to bind it) | **yes — handler ref to consumer's TS file** |
 | **`Trigger`** | `CREATE TRIGGER` + `pg_cron` + PostgREST route + `LISTEN/NOTIFY` | yes (the binding atom — turns Procedures into HTTP endpoints, cron jobs, MCP tools, lifecycle hooks) | no |
 
@@ -73,7 +73,7 @@ A logical feature commonly bundles a Procedure + a Trigger (and often a
 Schema and a View). Put related atoms in one file separated by `---`:
 
 ```yaml
-# starters/blog/manifests/contact.yaml
+# manifests/contact.yaml
 apiVersion: cms.mantle.aotter.net/v1
 kind: Procedure
 metadata: { name: send-contact-message }
@@ -112,7 +112,7 @@ metadata: { name: posts }
 spec:
   title: Posts                    # required: human-readable label for the admin UI
   localized: true                 # opt-in: row carries data.locale (ADR-0010)
-  lifecycle: simple               # v0.1.0 only ships 'simple'; 'editorial' is reserved (see Lifecycle below)
+  lifecycle: simple               # default; 'none' is operational, 'editorial' is reserved
   schema:
     $schema: https://json-schema.org/draft/2020-12/schema
     type: object
@@ -157,12 +157,11 @@ entry's state machine.
   in v0.1.0.**
 - `editorial` — the six-state machine with an approval queue
   (`draft → review → approved → scheduled → published → archived`,
-  with `published` returnable to `draft` for republish). **Grammar
-  key is reserved; the runtime is on the v0.1.x
-  roadmap.** v0.1.0's boot validator rejects `lifecycle: editorial`
-  with the diagnostic `LIFECYCLE_NOT_IN_V010` and a message
-  pointing at the v0.1.x roadmap. Authors should not write
-  `lifecycle: editorial` in v0.1.0 manifests; it will fail boot.
+  with `published` returnable to `draft` for republish). The grammar and
+  state-machine vocabulary are reserved for forward compatibility, but the
+  approval/request-publish runtime is on the v0.1.x roadmap. In v0.1,
+  `request_publish` rejects with `LIFECYCLE_NOT_IN_V010`; do not declare
+  editorial for a current publishing workflow.
 - `none` — **operational records**, not authored content: orders,
   inventory snapshots, grant/audit rows — anything written by
   Procedures as a side effect rather than drafted by a person. No
@@ -291,12 +290,14 @@ appendix.
 **Postgres analogue**: `CREATE TABLE posts (id UUID PRIMARY KEY, ...,
 UNIQUE (slug, locale));`
 
-### 2. `View` — the read surface (auto-exposed)
+### 2. `View` — the read surface (auto-exposed by surface)
 
-A named, declarative read over Schemas. **Auto-mounted** at
-`GET /api/views/<name>` by the SDK — no Trigger required, just like
-`SELECT FROM view_name` in Postgres works without a separate route
-declaration. See ADR-0012 for the full design rationale.
+A named, declarative read over Schemas. No Trigger is required. A View with
+no `spec.surface` (or `surface: public`) mounts at
+`GET /api/views/<name>` and becomes `query_view_<name>` on `/mcp`.
+`surface: staff` instead mounts at `GET /admin/api/views/<name>` behind the
+staff gate and appears only on `/mcp/staff`. See ADR-0012 for the full design
+rationale.
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v1
@@ -334,7 +335,7 @@ spec:
   limit: 100
 ```
 
-Public callers paginate via reserved query-string knobs `?page=&show=`
+REST callers paginate via reserved query-string knobs `?page=&show=`
 (1-indexed page, server caps `show` at `View.spec.limit`). Reserved
 names — `page` / `show` / `cursor` — must NOT appear in
 `spec.params.properties` (the parser rejects with
@@ -405,9 +406,12 @@ spec:
 ```
 
 ```ts
-// consumer's TS at boot
+// src/mantle/config.ts
 import { sendContactMessage } from "./handlers/send-contact-message";
-sdk.registerHandler("send-contact-message", sendContactMessage);
+
+export const handlers = {
+  "send-contact-message": sendContactMessage,
+};
 ```
 
 **v0.1 `requires.auth`**: `{ all: [<predicate>] }` only. Predicates:
@@ -442,11 +446,10 @@ the consumer guard handler, not in a new atom or Core repository. See
 
 **v0.1.0 `handler.kind`**: `ref` (author-supplied function) or
 `builtin` (SDK-supplied CRUD shortcut). For `builtin`, declare
-`op: <create | update | upsert | delete>` and `schema: <Schema name>`
-in place of `ref`. The runtime dispatch path is implemented by
-`InvokeBuiltinUseCase`; the feature-named diagnostic remains as a
-defense-in-depth guard if a builtin Procedure reaches an unsupported
-runtime path.
+`op: <create | update | upsert | delete | archive>` and
+`schema: <Schema name>` in place of `ref`. The runtime dispatch path is
+implemented by `InvokeBuiltinUseCase`; parser and boot validation fail closed
+on unknown ops, Schemas, or incompatible lifecycle use.
 
 **Postgres analogue**: `CREATE FUNCTION send_contact_message(input
 JSONB) RETURNS JSONB LANGUAGE plpgsql AS $$ ... $$;`. PG functions are
@@ -467,7 +470,7 @@ kind: Trigger
 metadata: { name: contact-http }
 spec:
   source:
-    kind:   http                       # v0.1 ONLY supports http source
+    kind:   http                       # v0.1 also supports mcp and lifecycle
     method: POST                       # POST | PUT | PATCH | DELETE
     path:   /api/contact               # OpenAPI {param} syntax for path params
                                        # path params auto-bind to identically-named input fields
@@ -484,7 +487,7 @@ shared.
 **v0.1 `Trigger.source.kind`**: `http` (public endpoint), `mcp` (named
 tool on `surface: public | staff`), or `lifecycle` (entry-writer hook). For `lifecycle`, declare `schema`,
 `on: [<hook>, ...]` from `LifecycleHook`, and optional `errorPolicy`
-(`abort` rejects only on `before_*` hooks; `continue` is the default).
+(`abort` is the `before_*` default; `continue` is the `after_*` default).
 Lifecycle hooks are wired through `LifecycleHookingEntryRepository`, so
 MCP, admin, and builtin write paths share the same hook behavior.
 
@@ -494,8 +497,8 @@ MCP, admin, and builtin write paths share the same hook behavior.
 The state-machine "lifecycle" from the Schema atom
 (`Schema.spec.lifecycle: simple | editorial`) is a separate domain
 that shares the word. The Schema setting governs which states an
-entry can be in; lifecycle Triggers (when they ship; see Future
-grammar) govern what fires around mutations.
+entry can be in; shipped lifecycle Triggers govern what fires around
+mutations.
 
 **Postgres analogue**: `CREATE TRIGGER ... AFTER INSERT ON posts
 EXECUTE FUNCTION ...` (lifecycle); `pg_cron` extension (cron); plus
@@ -771,10 +774,10 @@ narrow at v0.1.0 and grows in two tiers:
 1. **v0.1.0 shipped** — grammar parses and runtime behavior is wired
    in the current rebuild.
 2. **v0.1.x committed** — on the patch-release roadmap. Spec is
-   documented; implementation lands within the v0.1 series. Boot
-   validator rejects these keys with a code naming the feature.
+   documented; implementation lands within the v0.1 series. The unsupported
+   runtime path fails closed with a code naming the feature.
 3. **DRAFT (v0.2+)** — speculative, gated by concrete consumer
-   demand. Boot validator rejects with `DRAFT_KEY_USED`. May or may
+   demand. Parser/static validation rejects with `DRAFT_KEY_USED`. May or may
    not ship — depends on whether real use cases apply pressure.
 
 ### v0.1.0 shipped
@@ -790,7 +793,7 @@ Full shape lives further down.
 
 Grammar lives in v0.1.0. Runtime is the
 `InvokeBuiltinUseCase` that dispatches `op: create | update | upsert
-| delete` against the entry-writer chokepoint with `x-mantle-bind`
+| delete | archive` against the entry-writer chokepoint with `x-mantle-bind`
 stamping and `input ∩ Schema.properties` projection. Full shape lives
 further down.
 
@@ -801,19 +804,18 @@ surface. Procedures/Views share `ctx.auth`/scope predicates and optional guard
 orchestration across REST and MCP. Staff role is loaded live for each protected
 call; staff Views remain absent and un-callable on public MCP.
 
-### v0.1.x committed
+### Detailed shipped grammar and v0.1.x reservation
 
 > The `handler.kind: builtin` and `Trigger.source.kind: lifecycle`
-> sections below now describe shipped v0.1.0 behavior. The
-> `Schema.spec.lifecycle: editorial` subsection remains v0.1.x-
-> committed proper.
+> sections below describe shipped v0.1.0 behavior. Only the
+> `Schema.spec.lifecycle: editorial` subsection remains v0.1.x-committed.
 
 #### `Schema.spec.lifecycle: editorial` runtime
 
-Grammar key already accepted in v0.1.0 (writes parse) but the boot
-validator emits `LIFECYCLE_NOT_IN_V010` because the approval-queue
-runtime ships in v0.1.x. When v0.1.x lands, the same manifest
-deploys without changes — that's why the key is reserved now.
+Grammar and boot already accept the key, but `request_publish` emits
+`LIFECYCLE_NOT_IN_V010` because the approval-queue runtime ships in v0.1.x.
+When that runtime lands, the same manifest can use the publish workflow without
+a grammar change.
 
 #### `handler.kind: builtin` — thin shortcut over the storage adapter for trivial CRUD-shaped Procedures
 
@@ -832,11 +834,11 @@ spec:
 
 | op | Behavior |
 |---|---|
-| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; status='draft'; generated id. |
+| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: none`. |
 | `update` | UPDATE in place. `input.id` + `input.expectedVersion` (OCC) required. Bumps version. |
 | `upsert` | If `input.id` resolves, behaves as `update`; else as `create`. |
 | `delete` | Hard DELETE by id. |
-| `archive` | Soft-archive (status='archived'). Editorial-lifecycle Schemas only; on `simple` Schemas this is a parse error. (Editorial runtime ships in v0.1.x — `archive` becomes available the same release.) |
+| `archive` | Soft-archive (status='archived'). The manifest validator permits this builtin only for `editorial` Schemas; the archive transition itself is runtime-wired, while editorial approval/request-publish remains deferred. |
 
 The Procedure's `input` is the contract with the *caller*. It MAY
 declare fields the Schema does not (e.g. a Turnstile token). The
@@ -876,8 +878,8 @@ spec:
 | `after_update` | After UPDATE. Default best-effort. |
 | `before_delete` | Before DELETE. Throw cancels. |
 | `after_delete` | After DELETE. Default best-effort. |
-| `before_publish` | Before status flips to `published`. Editorial Schemas only. |
-| `after_publish` | After status flips to `published`. Editorial Schemas only. |
+| `before_publish` | Before any supported status transition to `published` (the shipped workflow is `simple`). |
+| `after_publish` | After any supported status transition to `published` (the shipped workflow is `simple`). |
 
 **Atomicity defaults by phase**:
 - `before_*`: `errorPolicy: abort`. Handler throw cancels the
@@ -921,15 +923,15 @@ Cloudflare wiring, the 128 KB platform limit, retry/DLQ configuration,
 idempotency, and legacy-envelope draining are specified in
 [Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md).
 
-**Editorial-lifecycle hooks** (`before_publish`, `after_publish`)
-depend on the `lifecycle: editorial` runtime, which ships in the
-same v0.1.x cut.
+`before_publish` and `after_publish` already wrap the shipped simple publish
+transition. When editorial approval lands, the same hooks wrap its final
+transition to `published`; no second hook grammar is planned.
 
 ### DRAFT (v0.2+, speculative)
 
 Each item below lands when the first concrete real-world use case
-forces it, not on speculation. Today, do not implement; the boot
-validator rejects with `DRAFT_KEY_USED`.
+forces it, not on speculation. Today, do not implement; parser/static
+validation rejects it with `DRAFT_KEY_USED`.
 
 #### Schema future
 - **`x-mantle-ref` auto-lift to virtual column** — when a property
@@ -983,13 +985,13 @@ validator rejects with `DRAFT_KEY_USED`.
 #### Trigger future
 - **`source.kind: cron`** with `expr:` — scheduled invocation.
 - **`source.kind: queue`** — async fan-out / message-driven invocation.
-- **`source.kind: lifecycle.foo`** — DRAFT extensions to the v0.1.x
+- **`source.kind: lifecycle.foo`** — DRAFT extensions to the shipped
   lifecycle hooks (e.g. `before_archive`, `after_request_publish`).
-  The 8 hooks listed in the v0.1.x committed section are the floor,
+  The 8 hooks listed in the detailed shipped section are the floor,
   not the ceiling.
 
-(Full lifecycle Trigger spec for the 8 v0.1.x-committed hooks lives
-in the v0.1.x committed section above. The remaining DRAFT items
+(Full lifecycle Trigger spec for the 8 shipped hooks lives
+in the detailed section above. The remaining DRAFT items
 below are the speculative v0.2+ shapes that haven't yet been promoted
 to a committed roadmap.)
 

package/docs/design-references/editorial-blog-2026-05-05.md

@@ -5,9 +5,9 @@ This document preserves the visual system from the retired
 it looked like a maintained template, but the design work is still useful as a
 reference for future themes.
 
-Use this as a design specimen, not as implementation guidance. Current starters
-should keep using the maintained theme stack in `starters/blog/src/theme.default`
-and `starters/blog/src/theme`.
+Use this as a design specimen, not as implementation guidance. Apply it through
+the version-matched `mantle:theme` workflow and the generated project's owned
+theme paths, such as `styles/globals.css`, `components/`, and `src/web/`.
 
 ## Design Thesis
 
@@ -209,10 +209,10 @@ will drift from the maintained SDK packages.
 Revive it as one of these:
 
 - A documented visual preset selectable during agent seeding.
-- A `theme.default` variant in the maintained blog starter.
+- A project-owned theme preset applied through `mantle:theme`.
 - A generated design prompt that tells the provisioning agent how to style a
   user's own brand.
 
-Do not bring it back under `starters/_archive`. The repo should not contain
-frozen runnable starters because agents treat runnable code as current product
-surface.
+Do not bring it back as a runnable starter in this SDK repository. Agents treat
+runnable code as current product surface, so the preserved design belongs only
+in this reference.

package/docs/labels.md

@@ -29,7 +29,7 @@ For package README or package-local docs changes, prefer the package area label
 | `area:runtime` | `packages/mantle-runtime` behavior, ports, use cases, dispatcher, render, MCP runtime. |
 | `area:spec` | `packages/mantle-spec`, manifest parsing, validation, diagnostics, CLI, spec types. |
 | `area:cf` | `packages/adapters/cloudflare`, Workers adapter, D1/KV/ASSETS wiring, Cloudflare deploy behavior. |
-| `area:starters` | `starters/*` consumer templates and starter validation. |
+| `area:starters` | External `aotter/mantle-starters` integration, release fanout, and the local moved-starter stub. |
 | `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
 | `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
 | `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |

package/docs/media-uploads.md

@@ -75,7 +75,7 @@ wrangler secret put R2_ACCESS_KEY_ID
 wrangler secret put R2_SECRET_ACCESS_KEY
 ```
 
-## `src/mantleConfig.ts`
+## `src/mantle/config.ts`
 
 ```ts
 import { R2MediaStorage, type CmsConfig } from "@aotter/mantle/cloudflare";