@aotter/mantle 0.0.11-alpha.35 → 0.0.11-alpha.37

package/README.md

@@ -38,7 +38,41 @@ deployable Mantle site, and connects the first Cloudflare deploy. Then
 point your coding agent (Claude Code / Cursor / Codex) at the provisioned
 repo to continue.
 
-Starter source and provision bundles live in [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters); launch starts from the blank base and the agent applies the selected type as a post-launch overlay. See `skills/install` in the [Mantle repo](https://github.com/aotter/mantle/tree/develop/skills/install) for how the agent continues a provisioned repo.
+Starter source and provision bundles live in [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters); launch starts from the blank base and the agent applies the selected type as a post-launch overlay. Generated repos vendor Core-owned `mantle:*` skills from this package for repo-local use. See `skills/install` in the [Mantle repo](https://github.com/aotter/mantle/tree/develop/skills/install) for how the agent continues a provisioned repo.
+
+## Agent marketplace install
+
+Install the Mantle Core skill bundle before working on generated repos:
+
+```bash
+# Claude Code
+/plugin marketplace add aotter/mantle
+/plugin install mantle
+
+# Codex
+codex plugin marketplace add aotter/mantle --ref develop
+codex plugin add mantle@mantle
+```
+
+Cursor and VS Code Copilot can auto-discover the GitHub repo through
+`.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json` after the repo
+is cloned or opened.
+
+## Marketplace capability installs
+
+In a generated repo, tell your coding agent:
+
+```txt
+Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
+Use repo-local mantle:plugin to update <plugin id> in this repo.
+Use repo-local mantle:plugin to remove <plugin id> from this repo.
+```
+
+Mantle marketplace entries are agent-installable recipes. They declare the
+plugin source, Mantle version range, files/atoms/routes/tools, adapter
+requirements, secrets, and checks. The agent applies the recipe through the
+Core-owned `mantle:plugin` skill and records it in `.mantle/plugins.json` plus
+`.mantle/plugins.lock.json`. There is no `mantle plugin add` CLI yet.
 
 ## Adapter targets
 
@@ -54,7 +88,12 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
 - Embedded docs and agent skills ship inside this npm package for
   generated-site agents:
   - `node_modules/@aotter/mantle/docs/design-atoms.md`
+  - `node_modules/@aotter/mantle/docs/media-uploads.md` (Cloudflare R2 adapter recipe)
   - `node_modules/@aotter/mantle/docs/adr/`
+  - `node_modules/@aotter/mantle/skills/develop/SKILL.md`
+  - `node_modules/@aotter/mantle/skills/plugin/SKILL.md`
+  - `node_modules/@aotter/mantle/skills/theme/SKILL.md`
+  - `node_modules/@aotter/mantle/skills/update/SKILL.md`
   - `node_modules/@aotter/mantle/skills/install/SKILL.md`
   - `node_modules/@aotter/mantle/skills/provision/SKILL.md`
 - [Repo](https://github.com/aotter/mantle)

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

@@ -2,7 +2,8 @@
 
 ## Status
 
-Accepted (new)
+Superseded for first launch by provisioning v2 (2026-06-27). Historical
+record only.
 
 ## Date
 
@@ -10,6 +11,12 @@ Accepted (new)
 
 ## Context
 
+> **Current direction:** 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:

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

@@ -419,3 +419,42 @@ The original ADR-0014 §"Auth as contract, Better Auth as default" framing stays
 - A `@cloudflare/vitest-pool-workers`-based integration test covering the full OAuth flow (DCR → consent → token → MCP RPC). Node-vitest can't load `@cloudflare/workers-oauth-provider` because it imports from `cloudflare:workers`.
 - Starters (`aotter/mantle-starters`) migration to the same top-level OAuthProvider shape. All 8 archetypes currently use the pre-carve-out `mountMcp` API and need updating before the next starter tag.
 - Track whether Anthropic relaxes (1) the `/mcp` resource-path-prefix requirement and (2) the no-colon-in-scope requirement. Both are de-facto MCP client behaviors, not RFC requirements; if upstream relaxes them, the SDK can re-introduce `mcp:read` / `mcp:staff` scopes for finer-grained delegation.
+
+## Amendment — 2026-06-30: Hosted-auth boundary and first-party cookie fields
+
+Mantle Platform introduces a first-party hosted-auth use case:
+`platform.mantle.tools` owns site-owner account, billing, hosted
+identity, and platform email, while generated sites still own local
+grants, member records, content, commerce, forms, and legal copy. The
+product boundary is documented in
+[`docs/auth-hosting-model.md`](../auth-hosting-model.md).
+
+This does not change ADR-0014's core rule: Mantle does not expose an
+un-curated `betterAuthOptions` or `advanced` passthrough. Missing Better
+Auth knobs become first-class SDK fields only when a real Mantle use
+case needs them.
+
+The first-party SSO use case needs exactly three Better Auth fields:
+
+- `trustedOrigins` — app-owned origins that Better Auth should trust for
+  auth flows. SDK-managed provider origins, such as Apple, are still
+  injected automatically.
+- `crossSubDomainCookies` — Better Auth's same-parent-domain cookie
+  support for a trusted first-party app family.
+- `cookiePrefix` — required when two Better Auth apps can write cookies
+  under the same parent domain, so Platform cookies do not collide with
+  Landing or generated-site cookies.
+
+These fields are additive. Existing consumers that do not pass them keep
+the previous cookie/session behavior.
+
+The boundary is deliberately narrower than "hosted auth everywhere":
+
+- Free users can still self-host every login method Mantle exposes
+  through `createAuth()`.
+- Same-parent-domain SSO can use `crossSubDomainCookies` when the same
+  party controls all participating subdomains.
+- Customer-owned domains cannot receive `mantle.tools` cookies. Paid
+  hosted auth for `customer.com` must use an OAuth/OIDC broker flow:
+  Platform authenticates and returns identity; the customer site creates
+  its own local session and maps identity into local grants.

package/docs/adr/0016-site-semantic-layer.md

@@ -3,7 +3,8 @@
 ## Status
 
 Accepted (slimmed 2026-05-12 per Epic #116; `mantle/site.md` letter
-surface suspended 2026-06-19 and removed from first-run scaffolds).
+surface suspended 2026-06-19 and removed from first-run scaffolds;
+amended 2026-06-27 for landing provision bundles).
 
 ## Decision
 
@@ -27,7 +28,8 @@ from deterministic scaffold state.
 
 ## Placeholder macros
 
-`create-mantle` substitutes these across `_common/*.template` files in a single pass:
+Mantle landing substitutes these across provision-bundle `*.template`
+files in a single pass:
 
 | Macro | Source | Example |
 |---|---|---|
@@ -41,7 +43,8 @@ from deterministic scaffold state.
 | `{{INSTALL_TIMESTAMP}}` | ISO 8601 of install run | `2026-05-12T14:03:00Z` |
 | `{{INSTALL_SUMMARY}}` | CLI flag | `bootstrapped publication site for Lab Cafe in zh-TW/en` |
 
-New macros must be added here, to `_common/*.template`, and to the substitution pass in `create-mantle`.
+New macros must be added here, to `mantle-starters` bundle templates,
+and to the landing substitution pass.
 
 ## Update rules
 
@@ -58,8 +61,9 @@ New macros must be added here, to `_common/*.template`, and to the substitution
 
 ## Implementation
 
-- Templates: `mantle-starters/_common/AGENTS.md.template`.
-- Substitution: `packages/create-mantle/src/placeholder.ts`.
-- Install handoff: `skills/install/SKILL.md` describes deterministic scaffold validation and the short post-substitution notes fill.
+- Templates: `mantle-starters/blank/AGENTS.md.template` and
+  generated `.mantle/*.template` bundle files.
+- Substitution: Mantle landing provision-bundle substitution.
+- Install handoff: `skills/install/SKILL.md` describes how agents continue from the landing-provisioned repo.
 - Provision update: `skills/provision/SKILL.md` describes the `AGENTS.md` public-site rewrite after deploy.
-- Theme overlay merge (Epic #116): `themes/<theme-key>/` overlay applies after the archetype starter and may touch `src/theme/` — never these two files.
+- Type overlays are applied while building `provision-bundles/<type>.json`; generated repos should not need a second overlay step.

package/docs/adr/README.md

@@ -14,7 +14,7 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [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) |
-| [0013](0013-agent-provisioned-consumer-projects.md) | Agent-provisioned consumer projects: website prompt → Skill → npm packages → starter setup → first-run provision/seed → owner/MCP handoff. | Accepted (new) |
+| [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 |
 | [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) |
 
@@ -27,7 +27,7 @@ If you're new to the codebase:
 3. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
 4. **0011** — the boundary between the runtime and the adapter (most load-bearing for the rebuild).
 5. **0010** — how locale flows through the system.
-6. **0013** — how the website prompt, Skills, npm packages, starters, seed, provision, and handoff fit together.
+6. **0013** — historical install-session context; current first launch is landing provision bundles plus repo-local handoff.
 7. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
 
 ## What's NOT here (and why)

package/docs/auth-hosting-model.md

@@ -0,0 +1,139 @@
+# Auth Hosting Model
+
+Mantle treats authentication as a runtime capability, not a paywall on
+basic login. The split is:
+
+- **Mantle SDK** gives every generated site the primitives needed to
+  run its own auth.
+- **Mantle starters** decide whether a generated site is wired for
+  self-hosted auth or as a client of Mantle Platform hosted auth.
+- **Mantle Platform** can sell hosted identity, provider setup, email,
+  and billing convenience for site owners who do not want to operate
+  those pieces.
+
+This document is the source of truth for the product and SDK boundary.
+Do not duplicate this model in starter handoff copy or landing prose;
+link here and keep downstream docs short.
+
+## Free Self-Hosted Auth
+
+A free Mantle site can run every login method the SDK exposes through
+`createAuth()`:
+
+- social OAuth providers supported by Better Auth;
+- generic provider-specific options through the `social.extras` shape;
+- email OTP;
+- magic link;
+- passkey or additional Better Auth method support when the SDK adds a
+  curated first-class field for it;
+- first-party same-domain or same-parent-domain SSO when the site owner
+  controls every participating subdomain.
+
+The site owner supplies their own provider client ids/secrets,
+transactional email sender, DNS, cookie policy, and operational
+maintenance. Mantle must not block self-hosted login behind a paid
+feature flag.
+
+## Hosted Platform Auth
+
+Paid hosted auth is a convenience and operations product. The value is
+that Mantle Platform can:
+
+- hold OAuth provider configuration;
+- hold email provider credentials;
+- send OTP and magic-link email;
+- manage deliverability and provider rotation;
+- register generated sites as clients;
+- check billing/license entitlements before hosted capabilities are
+  enabled;
+- expose a stable hosted identity broker for generated sites.
+
+The generated site still owns local grants, member records, content,
+orders, forms, and legal copy. Platform returns identity. The site maps
+that identity into `ctx.user`, `ctx.staff`, and its own grant model.
+
+## Same Parent Domain SSO
+
+When the apps share a parent domain that the same party controls, SSO
+can use browser cookies:
+
+```ts
+createAuth({
+  // ...
+  trustedOrigins: ["https://mantle.tools", "https://www.mantle.tools"],
+  cookiePrefix: "mantle-platform",
+  crossSubDomainCookies: {
+    enabled: true,
+    domain: "mantle.tools",
+  },
+});
+```
+
+Use this only for a trusted first-party app family, for example
+`platform.mantle.tools` and `mantle.tools`.
+
+`cookiePrefix` is required whenever more than one Better Auth app can
+write cookies under the same parent domain. Without it, Platform and
+Landing can overwrite each other's default Better Auth cookie names.
+
+`trustedOrigins` is a Better Auth auth-flow trust list. It is not a
+general API CORS policy and must not be documented as one.
+
+## Customer Domain SSO
+
+Shared cookies do not work across different registrable domains:
+
+```text
+platform.mantle.tools  ->  customer.com
+```
+
+Browsers will not send a `mantle.tools` cookie to `customer.com`. For a
+customer-owned domain, hosted auth must use OAuth/OIDC:
+
+```text
+customer.com/login
+  -> platform.mantle.tools/oauth/authorize
+  -> user signs in with Platform-supported methods
+  -> customer.com/api/auth/callback/mantle
+  -> customer.com verifies the authorization response
+  -> customer.com creates its own local session
+```
+
+That local session is the customer's site session. Platform remains the
+identity broker and entitlement authority; it does not become the
+customer site's member database or authorization system.
+
+## Landing Provisioning Split
+
+Landing should branch before GitHub or Cloudflare side effects:
+
+- **Continue free**: commit a self-hosted auth-ready site with docs,
+  env placeholders, and the user's own provider setup path.
+- **Use hosted auth**: check Platform entitlement, register the site as
+  a Platform auth client, and commit the generated site's Platform auth
+  client config.
+
+Landing can probe Platform staff/session state, but provisioning's
+GitHub OAuth token is still Landing-owned unless a separate token
+handoff design is introduced.
+
+The generated site's hosted-auth client code belongs in the starter or
+a starter overlay. Core owns only the auth contract, manifest/runtime
+identity vocabulary (`ctx.user`, `ctx.staff`), and curated Better Auth
+server primitives.
+
+## SDK Surface Rule
+
+Mantle should expose Better Auth knobs only as curated first-class
+fields when there is a real Mantle use case. Do not add a generic
+`betterAuthOptions` or `advanced` passthrough.
+
+The current first-party SSO use case justifies these optional fields on
+`CreateAuthConfig`:
+
+- `trustedOrigins`
+- `crossSubDomainCookies`
+- `cookiePrefix`
+
+All three are additive. Existing generated sites that do not pass them
+keep their previous cookie and session behavior.

package/docs/media-uploads.md

@@ -0,0 +1,179 @@
+# Cloudflare R2 Media Uploads
+
+Mantle supports staff media uploads through Staff MCP tools:
+`create_media_upload` and `commit_media_upload`. This is an optional
+post-launch feature for sites that use the Cloudflare adapter and need
+staff-managed images or files.
+
+Do not make R2 part of the Day 1 launch path. Cloudflare R2 setup may
+require billing or a credit card, so landing and the blank starter do not
+provision it by default.
+
+## When To Enable
+
+Enable this after the site already has:
+
+- a working Cloudflare Worker deploy;
+- staff auth configured;
+- a real need for staff or an agent to upload images/files.
+
+Use Claude Code, Codex, Cursor, or another local/non-sandboxed coding
+agent for media maintenance. Claude Cowork often cannot complete this
+flow because the final upload is a direct HTTP PUT to
+`*.r2.cloudflarestorage.com`.
+
+## How It Works
+
+The upload flow is deliberately split:
+
+1. The agent calls Staff MCP `create_media_upload` with purpose, variant
+   metadata, byte sizes, and mime types.
+2. Mantle returns signed upload URLs and required headers.
+3. The agent reads the local/chat attachment bytes and PUTs them directly
+   to R2.
+4. The agent calls `commit_media_upload`.
+
+Do not pass image bytes or base64 payloads through MCP tool arguments.
+The Worker validates policy; the agent runtime performs file processing
+and upload.
+
+## Cloudflare Setup
+
+Create a bucket and public read URL:
+
+```bash
+wrangler r2 bucket create <project>-media
+wrangler r2 bucket dev-url enable <project>-media
+```
+
+In the Cloudflare dashboard, create an R2 S3 API token:
+
+1. Open **R2**.
+2. Open **Manage R2 API Tokens**.
+3. Create an Object Read & Write token.
+4. Copy the Access Key ID and Secret Access Key.
+
+The R2 binding alone cannot issue presigned PUT URLs; Mantle also needs
+these S3-compatible credentials.
+
+## `wrangler.toml`
+
+```toml
+[vars]
+R2_ACCOUNT_ID = "<account-id>"
+MEDIA_PUBLIC_URL_BASE = "https://pub-<hash>.r2.dev"
+
+[[r2_buckets]]
+binding = "MEDIA_BUCKET"
+bucket_name = "<project>-media"
+```
+
+Set secrets:
+
+```bash
+wrangler secret put R2_ACCESS_KEY_ID
+wrangler secret put R2_SECRET_ACCESS_KEY
+```
+
+## `src/mantleConfig.ts`
+
+```ts
+import { R2MediaStorage, type CmsConfig } from "@aotter/mantle/cloudflare";
+import { AwsClient } from "aws4fetch";
+
+export interface Env {
+  readonly MEDIA_BUCKET?: R2Bucket;
+  readonly R2_ACCOUNT_ID?: string;
+  readonly R2_ACCESS_KEY_ID?: string;
+  readonly R2_SECRET_ACCESS_KEY?: string;
+  readonly MEDIA_PUBLIC_URL_BASE?: string;
+}
+
+function buildMediaStorage(env: Env): CmsConfig["bindings"]["mediaStorage"] {
+  if (
+    !env.MEDIA_BUCKET ||
+    !env.R2_ACCOUNT_ID ||
+    !env.R2_ACCESS_KEY_ID ||
+    !env.R2_SECRET_ACCESS_KEY ||
+    !env.MEDIA_PUBLIC_URL_BASE
+  ) {
+    return undefined;
+  }
+
+  const s3 = new AwsClient({
+    accessKeyId: env.R2_ACCESS_KEY_ID,
+    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+    region: "auto",
+    service: "s3",
+  });
+
+  return new R2MediaStorage(
+    env.MEDIA_BUCKET,
+    s3,
+    `https://<project>-media.${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    env.MEDIA_PUBLIC_URL_BASE,
+  );
+}
+```
+
+Then wire it into the CMS config:
+
+```ts
+siteDefaults: {
+  media: {
+    purposes: [
+      {
+        name: "page-image",
+        required: ["image/jpeg,image/png", "image/webp", "image/avif"],
+        maxBytes: {
+          "image/jpeg": 5_000_000,
+          "image/png": 5_000_000,
+          "image/webp": 3_000_000,
+          "image/avif": 2_000_000,
+        },
+      },
+    ],
+  },
+},
+bindings: {
+  mediaStorage: buildMediaStorage(env),
+},
+```
+
+`required` is slot-based. The example above declares three slots:
+
+- slot 0: choose exactly one fallback mime, preserving the source
+  semantics (`image/jpeg` for opaque photos, `image/png` when alpha must
+  be preserved);
+- slot 1: include a WebP variant;
+- slot 2: include an AVIF variant.
+
+This models the ADR-0017 multi-variant `<picture>` shape. If a site wants
+a simpler single-variant upload for a narrow purpose, it may declare one
+slot such as `["image/jpeg,image/png,image/webp,image/gif"]`; in that
+case, the agent chooses exactly one mime from the comma-separated list and
+must not upload one variant per listed mime.
+
+## Tool Visibility
+
+The Staff MCP media tools are registered only when both are true:
+
+- `bindings.mediaStorage` is set;
+- `siteDefaults.media.purposes` contains at least one purpose.
+
+If either side is missing, `create_media_upload` and
+`commit_media_upload` will not appear in `tools/list`.
+
+## Agent Guidance
+
+For image maintenance, prefer Claude Code or another coding agent that can
+read local files, process images, and make outbound PUT requests to R2.
+Avoid Claude Cowork for this workflow; use a non-sandboxed agent instead.
+
+Preserve source semantics:
+
+- photos may use JPEG/WebP variants;
+- transparent logos must keep alpha;
+- animated GIFs must stay animated;
+- do not silently flatten, resize, or recompress user assets without
+  asking.

package/docs/release-process.md

@@ -139,7 +139,7 @@ The audit takes ~30 seconds and rules out the most common fanout failure. Do it
 `bump-from-sdk.yml` / `bump-from-starters.yml` failed at the validate / typecheck gate because the SDK release introduced a code-shape break? Re-firing the workflow won't help — it'll fail the same gate on the same source. The fix-forward path:
 
 1. Branch off `develop` (starters) or `main` (landing): `release/vX.Y.Z`.
-2. Replicate what the bump workflow would have done — bump every `@aotter/mantle*` dep + own `version` in package.json files, refresh lockfile via `pnpm install --no-frozen-lockfile`, update `sources.json.version` (starters only).
+2. Replicate what the bump workflow would have done — bump every `@aotter/mantle*` dep + own `version` in package.json files, refresh lockfiles via `pnpm install --no-frozen-lockfile`, and rebuild starter provision bundles when starters source changed.
 3. Add whatever source-code fixes satisfy the new SDK shape.
 4. Commit subject MUST be `release: bump @aotter/mantle* to vX.Y.Z` (starters) or `release: bump @aotter/mantle to vX.Y.Z` (landing) — `tag-and-dispatch-landing.yml` filters on this in starters; landing has no equivalent filter but the convention keeps history consistent.
 5. Open PR base=`main` (starters and landing), CI passes now that lockfile + source are in sync, rebase-merge.
@@ -148,11 +148,11 @@ The audit takes ~30 seconds and rules out the most common fanout failure. Do it
 
 ### Re-spin release for a downstream-content-only fix
 
-Sometimes the SDK npm artifact is fine but the GitHub release tarball — used by `create-mantle` to scaffold starters — is broken (e.g. starter content didn't include a freshly-required field at release time). Per `§ Rollback / yanking policy`, the right path is to publish the next alpha as a no-op SDK bump that re-spins the fanout:
+Sometimes the SDK npm artifact is fine but the generated starter provision bundle is broken (e.g. starter content didn't include a freshly-required field at release time). Per `§ Rollback / yanking policy`, the right path is to publish the next alpha as a no-op SDK bump that re-spins the fanout:
 
 1. Cut alpha.N+1 in `mantle/` with empty SDK diff (versions + CHANGELOG only).
 2. CHANGELOG entry MUST say explicitly: `No SDK code changes. alpha.N+1 re-spins the release fanout to ship starter content that should have been part of alpha.N (see #XXX).`
-3. Tag + push → full fanout produces fresh `mantle-starters` tag + GitHub release tarball with the corrected content.
+3. Tag + push -> full fanout produces fresh `mantle-starters` provision bundles with the corrected content.
 
 Don't force-retag the broken alpha. Don't introduce a starter-only sub-tag like `vX.Y.Z-starter.N`. Either breaks the convention that starter version === SDK version.
 
@@ -173,7 +173,7 @@ release.yml: pnpm install → build → test (gate) → verify package.json
                    │
                    ▼
 mantle-starters/bump-from-sdk.yml: bump @aotter/mantle* deps
-             + own version + sources.json.version → pnpm install →
+             + own version → pnpm install + rebuild bundles →
              validate × 5 starters (gate) → typecheck × 5 (gate) →
              PR onto main → auto-approve + auto-merge
                    │
@@ -271,22 +271,20 @@ stay individually installable for tooling / alt-adapter authors.
 
 Do **not** publish starter packages during alpha unless a separate PR
 explicitly prepares their package allowlists and verifies the tarballs.
-Current starter install flow downloads starter source tarballs from
-GitHub/template refs, extracts them without preserving the template
-repo remote, and uses npm as the runtime dependency source.
+Current starter launch flow is landing-driven: landing fetches generated
+`provision-bundles/<type>.json` artifacts from `aotter/mantle-starters`,
+commits the user's GitHub repo, and uses npm as the runtime dependency
+source.
 
 Do **not** publish `@aotter/mantle-netlify` while it is a stub.
 
-`create-mantle` lives in `aotter/mantle-starters`, not here. The
-scaffolder couples to starter content (sources.json, merge layout,
-placeholder macros) and has zero coupling to SDK runtime, so it ships
-from the starters repo as a GitHub release tarball. Releases on this SDK
-repo do not attach a create-mantle tarball and must not publish
-`@aotter/create-mantle`.
+The retired `create-mantle` scaffolder is not shipped by this SDK repo.
+Releases on this SDK repo must not attach a create-mantle tarball and
+must not publish `@aotter/create-mantle`.
 
-`skills/install/SKILL.md` consumes the command composed by the landing
-page. Human-facing direct usage belongs in the `mantle-starters` README,
-not this SDK repo.
+`skills/install/SKILL.md` consumes the repo and handoff created by the
+landing page. Human-facing starter bundle details belong in the
+`mantle-starters` README, not this SDK repo.
 
 ### Pre-publish checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.35",
+  "version": "0.0.11-alpha.37",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -47,15 +47,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.35",
-    "@aotter/mantle-runtime": "0.0.11-alpha.35",
-    "@aotter/mantle-spec": "0.0.11-alpha.35",
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.35"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.37",
+    "@aotter/mantle-runtime": "0.0.11-alpha.37",
+    "@aotter/mantle-spec": "0.0.11-alpha.37",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.37"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.7.0",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.0",
+    "better-auth": "^1.6.23",
     "hono": "^4.12.0",
     "zod": "^4.0.0"
   },
@@ -63,7 +63,7 @@
     "@cloudflare/workers-oauth-provider": "^0.7.0",
     "@types/node": "^25",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.14",
+    "better-auth": "^1.6.23",
     "hono": "^4.12.23",
     "typescript": "^6.0.3",
     "zod": "^4.4.2"

package/skills/README.md

@@ -4,13 +4,33 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 
 | Skill | When to invoke |
 |---|---|
+| [`develop`](develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
+| [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across starters and adapters. |
+| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project context but does not depend on starter-owned skill semantics. |
+| [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK, starter snapshots, and plugin lockfiles. |
 | [`install`](install/SKILL.md) | User wants to start or continue a Mantle site. Sites launch on [Mantle landing](https://mantle.tools), which provisions the GitHub repo and first Cloudflare deploy; this brief orients the agent to take over and continue the provisioned repo. |
-| [`customize-design`](customize-design/SKILL.md) | User wants to rebrand or restyle a publication starter project. Walks the L1–L4 theme stack (tokens / extraCss+icons+i18n / Header+Footer / whole-template). |
-| [`extend`](extend/SKILL.md) | User has an existing project and wants to add a Schema / View / Procedure / Trigger or wire a feature (contact form, search, newsletter signup). |
-| [`provision`](provision/SKILL.md) | User wants production fully usable after a landing launch. Verify the Cloudflare deploy, wire per-site staff auth (GitHub OAuth App + Worker secrets), smoke test, and hand off the operator setup URL. |
+| [`customize-design`](customize-design/SKILL.md) | Legacy publication-specific design guide. Prefer `mantle:theme` for generated repos. |
+| [`extend`](extend/SKILL.md) | Legacy atom-authoring guide. Prefer `mantle:develop` or `mantle:plugin` depending on whether the work is one-off or installable. |
+| [`provision`](provision/SKILL.md) | User wants production fully usable after a landing launch. Verify the current landing deploy, wire per-site staff auth, smoke test, and hand off the operator setup URL. |
 
 The skills target `mantle@v0.1.0`. Each one names its assumed grammar version in the front-matter `applies_to:` field; future versions add a sibling SKILL.md or update the existing one.
 
+## Skill authority
+
+The `mantle:*` namespace is owned by `@aotter/mantle`. Starter template
+repos may vendor exact copies for offline/repo-local use, but they must not
+fork the meaning of a `mantle:*` skill. Starter launch files and plugin recipes
+are context that Core skills read, not competing skill contracts.
+
+## Marketplace install
+
+The repo is also an agent plugin bundle:
+
+- Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
+- Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
+- Cursor: `.cursor-plugin/plugin.json`.
+- VS Code + GitHub Copilot: `.copilot-plugin/plugin.json`.
+
 ## Audience
 
 These are written for **AI agents acting on behalf of consumers of mantle**, not for agents maintaining the mantle SDK itself. SDK-internal guidance lives in [`/CLAUDE.md`](../CLAUDE.md). Two audiences, two artifacts.

package/skills/develop/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mantle:develop
+description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
+source: "@aotter/mantle"
+sourcePath: skills/develop/SKILL.md
+when_to_invoke: |
+  Working dir contains a Mantle project: package.json depends on @aotter/mantle or @aotter/mantle-*, and manifests/ or src/mantleConfig.ts exists.
+applies_to: mantle@v0.1.0
+---
+
+# Mantle Develop
+
+This is the Core SDK skill for working inside an existing Mantle project.
+Starter files, launch handoffs, and plugin recipes are context; this skill
+owns the workflow vocabulary.
+
+## First Read
+
+1. `package.json` for the installed `@aotter/mantle*` versions.
+2. `manifests/` and `src/mantleConfig.ts` for the active atoms and adapter wiring.
+3. Optional local context: `.mantle/launch-state.json`, `.mantle/handoff.md`,
+   `.mantle/plugins.json`, `.mantle/plugins.lock.json`, and `.mantle/recipes/`.
+4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
+
+If `node_modules/` is missing, run `pnpm install --frozen-lockfile` before
+falling back to remote docs.
+
+## Core Model
+
+Mantle exposes exactly four declarative atoms:
+
+| Atom | Purpose |
+|---|---|
+| `Schema` | Stored entity/table shape. |
+| `View` | Read/query surface. |
+| `Procedure` | Typed mutation or operation. |
+| `Trigger` | HTTP/lifecycle/MCP invocation binding. |
+
+Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
+`Membership`. Compose those from the four atoms plus TypeScript only where
+the atoms cannot express the behavior.
+
+## Adapter Boundary
+
+The runtime is adapter-neutral. Required runtime ports are `DatabaseDriver`,
+`KvCache`, and `AssetServer`. Optional feature ports, such as `MediaStorage`
+or `DeferredHookDispatcher`, are enabled only when the current adapter wires
+them.
+
+Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
+or its adapter config is visible. A future Netlify adapter should satisfy the
+same Core workflow through its own ports and provider setup.
+
+## Loop
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm typecheck
+pnpm check
+```
+
+Use `pnpm dev` for local preview when the project provides it.
+
+## Rules
+
+- Prefer manifest YAML for content model changes.
+- Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.
+- Do not write directly to D1, KV, Postgres, or object storage for content
+  authoring. Use runtime use cases, admin APIs, or Staff MCP.
+- Do not commit provider secrets.
+- If the work is an installable capability, switch to `mantle:plugin`.

package/skills/install/SKILL.md

@@ -42,13 +42,13 @@ A landing-provisioned repo carries its launch context and ground truth in:
 | Path | Contents |
 |---|---|
 | `.mantle/launch-state.json` | Non-secret launch choices: type, purpose, locales, repo, owner, suggested overlay |
-| `.mantle/features.json` | Selected feature overlays and applied state |
+| `.mantle/features.json` | Starter launch context and applied starter state |
 | `.mantle/handoff.md` | The launch handoff note written for you |
 | `manifests/*.yaml` | Schemas / Views / Procedures / Triggers |
 | `src/mantleConfig.ts` | Site defaults, handler registration, runtime bindings |
 | `src/handlers/` | Handler implementations |
 | `AGENTS.md` | Cross-tool agent entry |
-| `.agent/skills/` + `.claude/skills/` | Repo-local skills: `mantle:develop`, `mantle:overlay`, `mantle:theme`, `mantle:update` |
+| `.agent/skills/` + `.claude/skills/` | Vendored Core skills from `@aotter/mantle`: `mantle:develop`, `mantle:plugin`, `mantle:theme`, `mantle:update` |
 
 ## Take Over a Provisioned Repo
 
@@ -73,23 +73,37 @@ Surface both verbatim when validation fails.
 
 ## Continue With Repo-Local Skills
 
-The generated repo ships its own skills under `.agent/skills/` and
-`.claude/skills/`. Hand off to the one that fits the work:
+The generated repo vendors Core-owned skills under `.agent/skills/` and
+`.claude/skills/`. The starter carries local copies for offline/pinned use; it
+does not own a separate skill contract.
 
-- **`mantle:overlay`** — apply the selected launch type as a small
-  post-launch overlay (first useful pages plus tiny seed data in the
-  user's language). This is the usual first step on a fresh blank launch.
 - **`mantle:develop`** — manifest, runtime, content-model, layout,
   bug-fix, and validation work on the site.
+- **`mantle:plugin`** — install repeatable marketplace capabilities using
+  a plan-first Core workflow.
 - **`mantle:theme`** — brand and visual direction via Mantle / Kiwa tokens
   and source. There is no premade theme picker; visual direction is agent
   work after launch.
 - **`mantle:update`** — compare the repo against its upstream provision
-  bundle.
+  bundle or installed plugin locks.
 
 Remove the placeholder blank homepage once the selected type ships a real
 homepage.
 
+## Optional Media Uploads
+
+Media uploads are a post-launch opt-in, not part of Day 1 provisioning. Do
+not block the first deploy or first useful page on storage setup.
+
+When the current repo uses the Cloudflare adapter and really needs
+staff-managed images or files, follow the Cloudflare R2 recipe:
+<https://raw.githubusercontent.com/aotter/mantle/develop/docs/media-uploads.md>.
+
+For media maintenance, prefer Claude Code, Codex, Cursor, or another
+local/non-sandboxed coding agent that can read files and make outbound PUT
+requests. Do not rely on Claude Cowork for R2 uploads; use a
+non-sandboxed agent instead.
+
 ## Local Preview
 
 To see the site locally before pushing:
@@ -122,6 +136,8 @@ skill:
 - Don't scaffold a project from scratch locally; launch happens on landing.
 - Don't block the first useful page on polishing prose or writing a site letter.
 - Don't ask for a Cloudflare API token in the base flow.
+- Don't require R2 media setup in the base flow; it is optional
+  post-launch work.
 - Don't commit provider secrets.
 - Don't use `127.0.0.1` in OAuth callback examples; use `localhost` locally
   and the real Worker URL in production.

package/skills/plugin/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: mantle:plugin
+description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
+source: "@aotter/mantle"
+sourcePath: skills/plugin/SKILL.md
+when_to_invoke: |
+  The user asks for a marketplace/plugin/capability install, or wants a domain feature that should be repeatable across starters and adapters.
+applies_to: mantle@v0.1.0
+---
+
+# Mantle Plugin
+
+Mantle plugins are Core SDK capability packages. They are not starter overlays
+and they are not provider provisioning scripts.
+
+A plugin may contribute:
+
+- manifests: `Schema`, `View`, `Procedure`, `Trigger`;
+- handler source or handler registration notes;
+- site defaults or media policy additions;
+- expected HTTP, admin, and MCP surfaces;
+- adapter capability requirements and provider setup notes.
+
+## User Install Entry
+
+The user-facing install path is:
+
+```txt
+Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
+Use repo-local mantle:plugin to update <plugin id> in this repo.
+Use repo-local mantle:plugin to remove <plugin id> from this repo.
+```
+
+There is no `mantle plugin add` CLI yet. Do not invent one. Install from a
+marketplace entry, plugin package, or recipe URL that declares enough data for
+an agent to apply the capability deterministically.
+
+A valid marketplace entry must include:
+
+- plugin id, title, source, and version;
+- supported Mantle version range;
+- files, manifests, handlers, routes, MCP tools, and admin surfaces it adds;
+- adapter capabilities and provider resources it requires;
+- required env vars and secrets, without secret values;
+- verification commands and expected surfaces.
+
+If the marketplace page is only marketing copy or lacks an install recipe,
+stop and ask for the recipe instead of guessing.
+
+## First Read
+
+1. `package.json` for Mantle version and adapter package.
+2. `manifests/` for current atom names and route/tool collisions.
+3. `src/mantleConfig.ts` for registered handlers, templates, and optional ports.
+4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
+5. `.mantle/launch-state.json` only as context, not as plugin authority.
+
+## Plan First
+
+Before applying any plugin, produce a plan:
+
+- files to add or change;
+- atoms to add and their names;
+- HTTP routes and MCP tools that will appear;
+- required runtime ports;
+- adapter-specific resources, env vars, and secrets;
+- checks to run.
+
+If the plugin needs a capability the current adapter does not expose, stop
+with the missing capability instead of inventing provider steps.
+
+## Apply
+
+Apply the smallest deterministic diff. Do not run arbitrary install scripts
+from a plugin package. Copy declared files, wire declared handlers, update the
+plugin ledger, then validate.
+
+Suggested ledger paths:
+
+```txt
+.mantle/plugins.json
+.mantle/plugins.lock.json
+```
+
+Keep starter launch state separate from plugin state. `.mantle/features.json`
+is launch/starter context, not the Core plugin ledger.
+
+## Update
+
+Compare the installed lock entry against the marketplace entry or recipe URL.
+Apply only the declared version diff, update `.mantle/plugins.lock.json`, then
+run the same verification checks.
+
+## Remove
+
+Use the lock entry as the removal manifest. Delete only files and atoms owned
+by that plugin, unwind handler registrations it added, remove its ledger entry,
+then validate. If another plugin or local code depends on a removed atom, stop
+and report the dependency instead of deleting through it.
+
+## Verify
+
+```bash
+pnpm validate
+pnpm typecheck
+```
+
+Then verify the plugin's declared surfaces:
+
+- `GET /api/views/<name>` for View reads;
+- HTTP Trigger path for public writes;
+- Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
+- adapter resource presence when the plugin requires optional ports.
+
+## Don't
+
+- Don't treat a starter archetype as a plugin.
+- Don't assume Cloudflare; inspect the active adapter and capability ports.
+- Don't create a second skill namespace for starter-specific plugins.
+- Don't commit secrets. Provider secrets stay in the platform secret store.

package/skills/provision/SKILL.md

@@ -39,6 +39,15 @@ with v2.
 Provision does not seed production content. First real content is created
 after owner sign-in through Staff MCP / admin authoring.
 
+Media uploads are optional post-launch work. Do not require storage or media
+upload credentials to finish first production provisioning. If the current
+repo uses the Cloudflare adapter and the owner asks for staff image/file
+uploads later, follow the Cloudflare R2 recipe:
+<https://raw.githubusercontent.com/aotter/mantle/develop/docs/media-uploads.md>
+and use Claude Code or another local/non-sandboxed coding agent for the
+upload workflow. Do not use Claude Cowork for R2 uploads; use a
+non-sandboxed agent instead.
+
 ## Principles
 
 1. Use the user's accounts. The repo and Worker belong to the user's
@@ -149,10 +158,13 @@ repo-local `.agent/skills/` directory (`mantle:develop`, `mantle:overlay`,
 | GitHub OAuth callback mismatch | OAuth App callback URL is wrong | Set it exactly to `<worker-url>/api/auth/callback/github`. |
 | Owner signs in but admin / MCP returns 403 | `ADMIN_GITHUB_LOGIN` does not match the signed-in GitHub login | Fix the `ADMIN_GITHUB_LOGIN` value and redeploy. |
 | Worker boots but sessions fail after a rerun | `BETTER_AUTH_SECRET` changed or was deleted | Restore the old secret if available; otherwise users must sign in again. |
+| `create_media_upload` is missing from Staff MCP | Optional R2 media is not configured, or `media.purposes` is empty | Only fix this if the owner explicitly wants media uploads; follow `docs/media-uploads.md`. |
+| Upload session works but the PUT to R2 fails from Claude Cowork | Cowork sandbox egress blocks direct R2 uploads | Retry from Claude Code / another non-sandboxed agent. |
 
 ## Don't
 
 - Don't ask for a Cloudflare API token in the base first-run path.
+- Don't require R2 media setup in the base first-run path.
 - Don't re-create the repo or re-run the first deploy from the agent;
   landing owns first provisioning.
 - Don't resurrect `provision:up` / `provision:plan` as a second

package/skills/theme/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: mantle:theme
+description: Apply brand and visual direction in a Mantle project without depending on starter-owned skill semantics.
+source: "@aotter/mantle"
+sourcePath: skills/theme/SKILL.md
+when_to_invoke: |
+  User wants visual, brand, layout, copy, or UI polish in an existing Mantle project.
+applies_to: mantle@v0.1.0
+---
+
+# Mantle Theme
+
+Theme work is project-owned source editing. Starters may ship Kiwa files,
+tokens, or recipes, but the skill contract is Core-owned.
+
+## First Read
+
+1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
+2. `styles/`, `components/`, `src/home.tsx`, `src/theme*`, and `kiwa-ui.json`
+   if present.
+3. `manifests/` to understand which content shape drives the public UI.
+
+## Work
+
+- Edit source the repo owns.
+- Use existing tokens, CSS, components, and installed dependencies first.
+- Keep accessibility basics: semantic HTML, focus states, contrast, and
+  keyboard reachability.
+- Do not require registry access for a project that already vendors UI source.
+- Add UI dependencies only when existing source cannot cover the requested
+  change.
+
+## Check
+
+```bash
+pnpm validate
+pnpm typecheck
+pnpm dev
+```
+
+Visually verify UI changes before calling them done.

package/skills/update/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: mantle:update
+description: Check a Mantle project for drift against its Core SDK, starter source, or installed plugin lockfiles.
+source: "@aotter/mantle"
+sourcePath: skills/update/SKILL.md
+when_to_invoke: |
+  User asks to update Mantle, compare generated files, refresh starter/vendor output, or inspect marketplace plugin drift.
+applies_to: mantle@v0.1.0
+---
+
+# Mantle Update
+
+Use this for drift checks. Do not blindly overwrite user-owned code.
+
+## First Read
+
+1. `package.json` and lockfile for installed `@aotter/mantle*` versions.
+2. `.mantle/launch-state.json` and `.mantle/features.json` when the project
+   came from Mantle landing.
+3. `.mantle/plugins.json` and `.mantle/plugins.lock.json` when plugins are
+   installed.
+4. Existing project scripts such as `mantle:update`, `validate`, and
+   `typecheck`.
+
+## Workflow
+
+1. Start from a clean git worktree.
+2. Run the project's existing update or compare script if one exists.
+3. Read the generated report before editing.
+4. Apply useful differences manually.
+5. Re-run:
+
+```bash
+pnpm validate
+pnpm typecheck
+```
+
+## Boundary
+
+Starter bundles and plugin packages can provide source snapshots, but Core owns
+the update vocabulary. A stale starter recipe or plugin note is context; it does
+not override the installed Core SDK contract.