@aotter/mantle 0.0.11-alpha.73 → 0.1.0-alpha.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.73",
-  "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.",
+  "version": "0.1.0-alpha.10",
+  "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
   "repository": {
@@ -14,8 +14,8 @@
   "main": "./dist/spec.js",
   "types": "./dist/spec.d.ts",
   "bin": {
-    "mantle": "./dist/cli.js",
-    "mantle-harness": "./dist/harness-cli.js"
+    "mantle": "./dist/cli/main.js",
+    "mantle-harness": "./dist/cli/harness.js"
   },
   "publishConfig": {
     "access": "public",
@@ -27,6 +27,10 @@
       "types": "./dist/spec.d.ts",
       "import": "./dist/spec.js"
     },
+    "./provision": {
+      "types": "./dist/provision.d.ts",
+      "import": "./dist/provision.js"
+    },
     "./spec": {
       "types": "./dist/spec.d.ts",
       "import": "./dist/spec.js"
@@ -39,6 +43,30 @@
       "types": "./dist/runtime-testing.d.ts",
       "import": "./dist/runtime-testing.js"
     },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    },
+    "./admin": {
+      "types": "./dist/admin.d.ts",
+      "import": "./dist/admin.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./vercel": {
+      "types": "./dist/vercel.d.ts",
+      "import": "./dist/vercel.js"
+    },
+    "./vercel/libsql": {
+      "types": "./dist/vercel-libsql.d.ts",
+      "import": "./dist/vercel-libsql.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare.d.ts",
       "import": "./dist/cloudflare.js"
@@ -55,27 +83,69 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.73",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.73",
-    "@aotter/mantle-runtime": "0.0.11-alpha.73",
-    "@aotter/mantle-spec": "0.0.11-alpha.73"
+    "@aotter/mantle-runtime": "0.1.0-alpha.10",
+    "@aotter/mantle-spec": "0.1.0-alpha.10"
   },
   "peerDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.0",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.23",
+    "better-auth": "^1.7.1",
     "hono": "^4.12.0",
-    "zod": "^4.0.0"
+    "@libsql/client": "^0.17.4",
+    "zod": "^4.0.0",
+    "@aotter/mantle-admin": "0.1.0-alpha.10",
+    "@aotter/mantle-bun": "0.1.0-alpha.10",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.10",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.10",
+    "@aotter/mantle-vercel": "0.1.0-alpha.10",
+    "@aotter/mantle-web": "0.1.0-alpha.10"
+  },
+  "peerDependenciesMeta": {
+    "@aotter/mantle-admin": {
+      "optional": true
+    },
+    "@aotter/mantle-admin-ui": {
+      "optional": true
+    },
+    "@aotter/mantle-bun": {
+      "optional": true
+    },
+    "@aotter/mantle-cloudflare": {
+      "optional": true
+    },
+    "@aotter/mantle-vercel": {
+      "optional": true
+    },
+    "@aotter/mantle-web": {
+      "optional": true
+    },
+    "aws4fetch": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.0",
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.23",
-    "hono": "^4.12.30",
+    "better-auth": "^1.7.1",
+    "hono": "^4.12.34",
+    "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.2"
+    "zod": "^4.4.3",
+    "@aotter/mantle-admin": "0.1.0-alpha.10",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.10",
+    "@aotter/mantle-bun": "0.1.0-alpha.10",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.10",
+    "@aotter/mantle-web": "0.1.0-alpha.10",
+    "@aotter/mantle-vercel": "0.1.0-alpha.10"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -5,6 +5,7 @@ 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. |
+| [`media-gc`](media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
 | [`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. |
@@ -14,12 +15,43 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 The skills target Mantle's v0.1 grammar. The installed package version, not
 duplicated skill prose, selects the exact runtime and embedded docs.
 
+## Disclosure audit
+
+Every skill ships as one `SKILL.md` with no reference files, scripts, or
+assets, so nothing is deferred behind a second load. Progressive disclosure
+here is section routing inside one file: the agent reads the entry constraints,
+then only the section its selected path names. `scripts/check-skills.mjs`
+enforces the columns below.
+
+| Skill | Routes on | Entry-path constraints (read before acting) | Path-gated sections | Projection | Restricted because |
+|---|---|---|---|---|---|
+| `develop` | existing project; manifest, runtime, handler, adapter, or MCP work | four-atom model; adapter neutrality; no direct D1/KV/Postgres writes; no committed secrets | performance harness; local MCP client; locale rules | project, plugin | — |
+| `plugin` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project, plugin | — |
+| `theme` | brand or visual direction in a generated project | repo-owned theme and UI contracts | — | project, plugin | — |
+| `update` | drift check against SDK, starter, or plugin locks | never blindly overwrite user-owned code | — | project, plugin | — |
+| `install` | new site, or opening an existing generated one | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | create local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
+| `provision` | ship to Cloudflare and finish production auth | secrets never enter source or logs; explicit auth mode | hosted auth; self-managed auth | plugin | Platform-specific deploy that handles production secrets; opt-in only. |
+| `media-gc` | audit or remove stale uncommitted media objects | audit by default; confirm exact account, bucket, cutoff, and candidate digest; re-audit before applying; never prefix-delete; never print keys | apply | plugin | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
+
+Deliberately monolithic:
+
+- `develop` is the widest file, but its adapter, auth, and data-ownership rules
+  constrain every path through it. Splitting them behind routing would let an
+  agent reach a write path without them, which is the failure this audit
+  exists to prevent.
+- `media-gc` keeps its full audit-confirm-reapply sequence inline for the same
+  reason: each safeguard is a precondition of the delete that follows it.
+
 ## Skill authority
 
-The `mantle:*` namespace is owned by `@aotter/mantle`. Run `mantle skills` to
-project the installed package's `develop`, `plugin`, `theme`, and `update`
-skills to identical `.agent` and `.claude` paths; use `mantle skills --check`
-to fail closed on drift. The installed package and
+The `mantle:*` namespace is owned by `@aotter/mantle`. Every skill declares its
+own distribution scope in front matter: `metadata.projection: project` marks a
+skill `mantle skills` should place in a generated project, and a skill that
+withholds `project` must say why. `scripts/check-skills.mjs` holds that
+declaration and the audit table below to each other.
+
+Run `mantle skills` to project the installed package's skills into a project;
+use `mantle skills --check` to fail closed on drift. The installed package and
 `node_modules/@aotter/mantle/docs/` are the single version-matched authority.
 Starter launch files and plugin recipes are project context, not competing
 contracts.
@@ -37,9 +69,9 @@ duplicated into the npm package:
 ## Audience
 
 These are written for **AI agents acting on behalf of consumers of mantle**,
-not for agents maintaining the Mantle SDK itself. SDK maintainers use the
-repo-root `CLAUDE.md` from a source checkout; it is intentionally not shipped
-inside the npm package. Two audiences, two artifacts.
+not for contributors maintaining the Mantle SDK itself. SDK contributors use
+the repo-root `CONTRIBUTING.md`; it is intentionally not shipped inside the npm
+package. Two audiences, two artifacts.
 
 ## Discoverability
 

package/skills/develop/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/develop/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Develop
@@ -16,7 +17,7 @@ docs govern runtime/API behavior.
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
-2. `manifests/`, the active adapter config, and `src/auth.ts` when present. If the project is older, check `src/mantleConfig.ts`.
+2. `manifests/site.yaml`, the active adapter config, and `src/auth.ts` when present. If the project is older, check `src/mantleConfig.ts`.
 3. The active `.mantle/overlays/<type>/seed.json`, when present; generated
    homepages commonly import visible copy and form structure from it.
 4. Optional local context: `.mantle/launch-state.json`, `.mantle/handoff.md`,
@@ -41,18 +42,19 @@ Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
 `TemplateRegistry`, and a matching `publicPathResolver` must agree on the
 exposed collections. Do not auto-publish every Schema. Generated projects list
 their mounted URL surface in their own README.
+Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
+not install public rendering by itself.
 
 ## Authoring CLI
 
-Use the project's scripts first; generated starters expose the shipping
-`mantle` authoring CLI from `@aotter/mantle-spec`:
+Use the project's scripts first; generated projects expose the shipping
+`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
+command list instead of trusting one copied into prose — the surface is
+version-matched and changes between releases:
 
 ```bash
 pnpm exec mantle --help
 pnpm validate
-pnpm introspect
-pnpm emit-openapi
-pnpm emit-types
 ```
 
 This CLI validates and derives artifacts from an existing materialized
@@ -82,9 +84,12 @@ the atoms cannot express the behavior.
   `Procedure.spec.input` before the seed/form. Keep public mutation inputs
   `additionalProperties: false`; otherwise JSON Schema's default may strip an
   undeclared field while returning success.
-- Use `lifecycle: none` for submissions, inquiries, orders, and other
+- Use `lifecycle: operational` for submissions, inquiries, orders, and other
   Procedure-created operational records that staff inspect or correct. Reserve
-  `simple` for content a person stages and publishes.
+  `publishing` for content a person stages and publishes.
+- Lifecycle `before_update` / `after_update` hooks also fire for unpublish,
+  archive, and every other status transition whose target is not `published`;
+  do not use them for edit-only work.
 - When a form's fixed option values change, update the stored Schema and public
   Procedure input `enum` together. Keep translated labels in the page seed;
   Admin and Staff MCP derive their typed controls from the manifest values.
@@ -98,18 +103,25 @@ the atoms cannot express the behavior.
 
 - `data.locale` is reserved for `localized: true` Schemas. A non-localized
   Schema must use a domain field such as `replyLocale`.
+- Use a standalone localized Schema only for independent locale rows. For
+  versions of one entity, use a non-localized parent plus a localized child
+  with `translates: { parent, on }`. The child must own at least one field
+  besides `locale` and the join field.
 - Parallel locale blocks must keep field names, option values, step IDs, and
   result keys identical; translate display strings only.
-- `siteDefaults.locales` is code-owned and boot-synced. Brand, title,
-  description, and origin are seeded once, then changed through site settings.
+- `siteDefaults.origin`, `siteDefaults.locales`, and `siteDefaults.icons` are
+  code-owned and boot-synced. The icon list is shared by browser favicons,
+  Admin chrome, and MCP `serverInfo.icons`; keep its static files under
+  `public/`. Brand, title, and description seed once, then change through site
+  settings.
 - When changing an existing collection from `[slug]` to `[slug, locale]`,
   boot with a Mantle version that reconciles obsolete unique indexes and test
   the same slug in two locales. Do not patch D1 manually.
 
 ## Adapter Boundary
 
-The runtime is adapter-neutral. Required runtime ports are `DatabaseDriver`,
-`KvCache`, and `AssetServer`. Optional feature ports, such as `MediaStorage`
+The runtime is adapter-neutral. Required runtime ports are `DatabaseDriver`
+and `AssetServer`. Optional feature ports, such as `MediaStorage`
 or `DeferredHookDispatcher`, are enabled only when the current adapter wires
 them.
 
@@ -127,12 +139,13 @@ teaching the project Mantle internals.
 
 ## Auth Composition
 
-When a generated repo contains `src/auth.ts`, the repo owns its auth
-composition. Preserve the explicit mode recorded in its launch state and
-Worker config; do not infer a mode from whichever credentials happen to be
-present or configure competing paths. Keep provider secrets out of source.
-Follow the repo handoff for provider-specific setup rather than adding product
-policy to Core.
+Conventional Cloudflare projects declare `MANTLE_AUTH_MODE=hosted` or
+`self-managed`; Core owns that standard Auth composition and rejects partial
+or mixed bindings. Preserve the explicit mode recorded in launch state and
+Worker config, keep provider secrets out of source, and do not infer a mode
+from whichever credentials happen to be present. A repo with an explicit
+`createMantleWorker({ auth })` override owns that custom composition; follow
+its handoff instead of replacing it with the conventional factory.
 
 ## Performance Loop
 
@@ -203,7 +216,8 @@ cache.
 
 ## Rules
 
-- Prefer manifest YAML for content model changes.
+- Put all content model changes in `manifests/site.yaml`; other manifest
+  filenames are rejected.
 - Use a generated overlay `seed.json` for the auth-free local first page when
   it is already imported by `src/web/content/*`.
 - Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.

package/skills/install/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/install/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Creates a new project; nothing to project into an existing one.
 ---
 
 # Mantle Install
@@ -33,35 +35,34 @@ hosted provider flow.
 | Blog, docs, posts, or editorial site | `publication` |
 | Catalog or order intent | `transaction` |
 | Booking or request intent | `reservation` |
-| Member or participation intent | `community` |
 
-2. Choose absolute paths for a temporary starters checkout and a target
-   directory outside both Mantle repositories. Derive a short project slug,
-   brand, one-sentence description, and locales from the user's prompt.
-   Require Node 22+ and pnpm 9+; check `node --version` and `pnpm --version`
-   before materializing.
+Community and membership types are not released; `create` refuses them. Build
+those on `blank` or the closest released type.
 
-3. Clone [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
-   into a temporary directory and run its materializer. Use a starters ref
-   supplied by the user for branch testing. Otherwise use a tag matching the
-   requested Mantle version; use `develop` only for unreleased work. When the
-   user supplies a Mantle branch URL for a cold test, use the same branch name
-   in `mantle-starters` when that branch exists.
+2. Choose a target directory outside both Mantle repositories; its name
+   becomes the project slug. Derive a brand, one-sentence description, and
+   locales from the user's prompt. Require Node 22+ and pnpm 9+; check
+   `node --version` and `pnpm --version` before creating.
+
+3. Create the project with the Core CLI. It resolves the official immutable
+   starter tag for its own version, so no starters checkout is involved:
 
 ```bash
-git clone --depth 1 --branch <starters-ref> \
-  https://github.com/aotter/mantle-starters.git <temporary-starters-dir>
-pnpm --dir <temporary-starters-dir> materialize <type> \
-  --out <target-dir> \
-  --project-name <slug> \
+npx -y @aotter/mantle@alpha create <type> <target-dir> \
   --brand "<brand>" \
   --description "<one sentence>" \
   --locales <comma-separated-locales>
 ```
 
-The materializer writes the same precomposed `provision-bundles/<type>.json`
-used by Mantle landing. Do not manually copy `blank/`, merge overlays, or edit
-the generated bundle JSON.
+Pin an exact version (`@aotter/mantle@<version>`) when the user asked for one.
+`create` writes files and stops: it installs nothing, initializes no
+repository, configures no auth, and deploys nothing. It refuses to write into
+a path that already exists, and there is no force flag — choose a new
+directory instead.
+
+Do not clone the starters repository, copy `blank/`, merge overlays, or edit a
+provision bundle by hand. The CLI renders the same immutable bundle Mantle
+landing uses.
 
 4. For a typed launch, read `.mantle/handoff.md`, the selected overlay's
    `layout.md`, `seed-prompt.md`, and `seed.json`. Shape the first local page by
@@ -107,7 +108,9 @@ pnpm exec mantle skills --check
 
 Then read:
 
-3. Repo-local Mantle skills under `.agent/skills/` or `.claude/skills/`.
+3. Repo-local Mantle skills under `.agents/skills/` or `.claude/skills/`. A
+   project created before this layout may also carry `.agent/skills/`; read it
+   if present, but never write there and never delete it.
 4. Matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 
 Use remote docs only when embedded docs are unavailable, and use a tag matching
@@ -125,14 +128,12 @@ pnpm typecheck
 ```
 
 Inspect the already composed manifest, page, and seed files before changing
-them. Use the project's scripts first; generated projects expose:
+them. Use the project's scripts first; ask the installed CLI for its command
+list rather than trusting one copied into prose:
 
 ```bash
 pnpm exec mantle --help
 pnpm validate
-pnpm introspect
-pnpm emit-openapi
-pnpm emit-types
 ```
 
 ## Production

package/skills/media-gc/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: media-gc
+description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/media-gc/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
+---
+
+# Mantle Media GC
+
+Use the connected Cloudflare API. Audit by default; delete only the exact
+objects approved by the user.
+
+## Preflight
+
+1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
+   binding, bucket name, and declared public media purpose names.
+2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
+   ask; never choose by name similarity.
+3. Use the Cloudflare OpenAPI search before execution to resolve the current
+   R2 List Objects and Delete Objects endpoints. If the connected account lacks
+   access, stop. Do not create, request, or store credentials.
+4. Stop when the project has no public R2 media binding or no declared purpose.
+
+## Audit
+
+For each declared purpose, list up to 1,000 objects per page under the exact
+`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+
+An object is a deletion candidate only when all conditions hold:
+
+- `last_modified` is more than 24 hours old;
+- `custom_metadata.committedAt` is absent or empty;
+- the key matches the exact Mantle layout
+  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+  where `<purpose>` is declared by this project and `<group>` contains only
+  letters, digits, `_`, or `-`.
+
+Skip committed, unknown-prefix, unprefixed, malformed, or ambiguous objects.
+Delete only an uncommitted variant, never its whole group.
+
+Report the account, bucket, purpose prefixes, UTC cutoff, candidate object and
+group counts, total bytes, skipped count, and a SHA-256 digest of the sorted
+`key + etag` candidate set. Do not print object keys, upload group IDs,
+filenames, public URLs, signed URLs, or secrets.
+
+## Apply
+
+1. Show the audit summary and get explicit confirmation for that exact account,
+   bucket, cutoff, count, byte total, and candidate-set digest.
+2. Re-run the complete audit with the same UTC cutoff. If the candidate count,
+   bytes, or digest changed, stop and present the new audit for confirmation.
+3. Call Delete Objects with JSON arrays of exact keys, at most 1,000 keys per
+   request. Never send the `prefix` query parameter: an empty prefix can empty
+   the bucket.
+4. Do not automatically retry failed keys. Report safe API error codes and
+   counts; a later invocation can audit and retry what remains.
+5. Re-list every inspected purpose prefix and report the remaining candidate
+   count and bytes.
+
+## Don't
+
+- Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
+- Don't use prefix deletion or empty-bucket operations.
+- Don't delete private-media buckets or objects outside declared purpose
+  prefixes.
+- Don't treat missing pagination pages, metadata, or permissions as an empty
+  result.
+
+## Diagnostics
+
+| Symptom | Action |
+|---|---|
+| Multiple matching accounts or buckets | Stop and ask the user to select the exact target. |
+| A page is truncated without a cursor | Stop; do not delete from a partial audit. |
+| A candidate has an unexpected key or metadata shape | Skip it and include it only in the aggregate skipped count. |
+| A delete request partially fails | Report safe error codes and leave the remaining objects for a later audit. |
+
+## When You're Done
+
+Return whether the run was audit-only or applied, the aggregate before/after
+counts and bytes, and any safely redacted failures.

package/skills/plugin/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/plugin/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Plugin
@@ -49,7 +50,7 @@ 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.
+2. `manifests/site.yaml` for current atom names and route/tool collisions.
 3. `src/mantle/config.ts` and `src/mantle/handlers/` for registered handlers, templates, and optional ports. Older projects may use `src/mantleConfig.ts`.
 4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
 5. `.mantle/launch-state.json` only as context, not as plugin authority.

package/skills/provision/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/provision/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
 ---
 
 # Provision a Mantle Project
@@ -50,6 +52,10 @@ Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
 commit and push non-secret changes. Reuse any repo or Worker already created
 by landing. Workers Builds is optional after a direct deploy.
 
+When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
+provider's OAuth callback together, then redeploy. Do not patch `site_config`
+directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
+
 ## Choose Auth
 
 - **Self-hosted — free:** configure the owner's per-site GitHub OAuth App and
@@ -58,6 +64,9 @@ by landing. Workers Builds is optional after a direct deploy.
   hosted allocation and client configuration. Mantle Platform operates the
   identity provider; do not ask the user for a per-site GitHub OAuth App.
 
+Configure only the selected mode. Core deliberately rejects partial or mixed
+hosted/self-managed bindings with `503 setup_incomplete`.
+
 Do not claim that hosted auth can attach to an arbitrary local repo unless the
 current Mantle landing flow explicitly supplies that handoff.
 
@@ -74,11 +83,15 @@ For the exact boundary, read
 
 2. Put non-secret values in `wrangler.toml`:
 
+- `MANTLE_AUTH_MODE = "self-managed"`
 - `PUBLIC_ORIGIN`
 - `GITHUB_CLIENT_ID`
 - `ADMIN_GITHUB_LOGIN`
 - correct Worker `name`
 
+Remove `MANTLE_HOSTED_AUTH_ISSUER` and `MANTLE_HOSTED_AUTH_CLIENT_ID` if they
+were present for a hosted allocation.
+
 3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
    secrets; otherwise use hidden shell input:
 
@@ -104,8 +117,17 @@ pnpm deploy
 ## Hosted Auth
 
 Follow the landing handoff and generated client configuration. Hosted
-configuration remains in landing-managed Cloudflare Worker bindings; do not
-write client secrets into `wrangler.toml`.
+configuration remains in landing-managed Cloudflare Worker bindings. Verify:
+
+- `MANTLE_AUTH_MODE = "hosted"`;
+- `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;
+- `MANTLE_HOSTED_AUTH_CLIENT_ID` is the same-origin `/clients/<id>` URL;
+- `PUBLIC_ORIGIN` and `ADMIN_GITHUB_LOGIN` are set;
+- `BETTER_AUTH_SECRET` exists as a Worker secret;
+- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are absent.
+
+Hosted clients use PKCE and have no client secret. Do not write secrets into
+`wrangler.toml`.
 
 Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
 authenticates, then skip the self-hosted flow.

package/skills/theme/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/theme/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Theme
@@ -18,7 +19,7 @@ tokens, or recipes, but the skill contract is Core-owned.
 2. `styles/`, `components/`, `src/web/`, `src/theme*`, and UI-library config
    if present.
 3. A vendored UI palette's manifest and license, if present.
-4. `manifests/` to understand which content shape drives the public UI.
+4. `manifests/site.yaml` to understand which content shape drives the public UI.
 
 ## Ownership
 
@@ -26,6 +27,11 @@ tokens, or recipes, but the skill contract is Core-owned.
   its `:root` and `.dark` values; runtime components inherit those variables.
 - `components/` is the runtime-facing component surface when present.
   `src/web/` is project-owned composition; put new sections there.
+- `public/site-icon.svg` and `public/site-icon.png` are one site identity.
+  Keep both listed in `src/mantle/config.ts > siteDefaults.icons`: PNG first as
+  the 64x64 compatibility rendition, then SVG as the editable `any` size source.
+  The same list drives browser favicons, Admin chrome, and MCP
+  `serverInfo.icons`; do not edit generated files under `public/_mantle/`.
 - If the project includes a vendored UI reference palette, treat it as
   offline source material and provenance, not runtime source. Copy only a
   needed primitive or block into the project's runtime directories, or
@@ -35,6 +41,10 @@ tokens, or recipes, but the skill contract is Core-owned.
 ## Work
 
 - Use existing tokens, CSS, components, and installed dependencies first.
+- When replacing the site mark, regenerate PNG from the same SVG artwork so
+  every surface presents the same identity. Check it at the Admin's 28px slot
+  in both light and dark themes; a single high-contrast rendition is preferred
+  over theme-specific variants unless the artwork genuinely needs both.
 - For a standard hero image, set the section's `image: { src, alt }`; use
   `showImage: false` for text-only hero/content blocks. Put non-image media in
   a project-owned section.

package/skills/update/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/update/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Update

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;CAYhB,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,YAAY;YACf,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,YAAY;YACf,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;QAC5B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}