@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/spec-only-host-adoption.md

@@ -0,0 +1,158 @@
+# Spec-only adoption in an existing host
+
+An existing application can reuse Mantle's Schema grammar and validation by
+consuming the published `@aotter/mantle-spec` package, without running Mantle
+Runtime. This Spec-only path is allowed by
+[ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
+manifest grammar, or fork of Core.
+
+This recipe targets `0.1.0-alpha.16`. Its public APIs and peer requirements are
+prerelease contracts: pin the package, record the tested version, and rerun
+compatibility checks when upgrading.
+
+## What stays with the host
+
+| Concern | Spec reuse | Host responsibility |
+|---|---|---|
+| Model definitions | Schema grammar, parse/link diagnostics | Project existing definitions into supported JSON Schema |
+| Input | `EntryDataValidator` and structured errors | Authentication, authorization, normalization, write orchestration |
+| Model browser | Parsed/linked Schema metadata | UI, metadata visibility, field display, graph layout |
+| Relationships | Translation declaration/link validation | Existing slug joins, record integrity, locale policy |
+| Storage and publishing | None in this recipe | Files, database, transactions, revisions, release/recovery |
+| Operations and tools | None in this recipe | No automatic View, Procedure, Trigger, REST or MCP execution |
+
+Mantle's Web, Admin UI and platform adapters remain optional. A Vue host does
+not have to embed the React Admin SPA to reuse Spec. Avoid importing SDK
+internals or maintaining a second manifest interpreter.
+
+## One definition, several projections
+
+The motivating Aotter official-website implementation keeps its existing
+Nuxt/Nitro host and Git/D1 storage. Shared content definitions drive the site's
+content layer, admin write validation, a responsive model/ER browser, and
+Schema export. That website implementation was validated locally; this SDK
+contribution does not deploy it or claim a production rollout.
+
+```text
+Host-owned content definitions
+  ├─ existing CMS/content queries
+  └─ JSON Schema in Mantle Schema manifests
+       ├─ parse + link → model browser / metadata export
+       └─ EntryDataValidator → host-authorized write path
+```
+
+Use the existing definitions as the source of truth. If the host starts with
+Zod or another schema language, conversion is a host concern: verify that the
+result uses supported JSON Schema keywords and preserves the intended
+validation semantics. Do not hand-maintain a second field list for the graph.
+
+## Minimal public-API recipe
+
+Install the exact Spec package and its supported peer, without Runtime:
+
+```sh
+npm install --save-exact @aotter/mantle-spec@0.1.0-alpha.16 zod@4.5.4
+```
+
+The [synthetic fixture](../packages/mantle-spec/test/fixtures/spec-only-host.yaml)
+contains categories, articles and article translations. It contains no real
+website records, account configuration or credentials. Given that fixture as
+`manifestYaml`, the application can prepare its validated model once:
+
+```ts
+import {
+  EntryDataValidator,
+  parseManifestSources,
+  ValidateManifestsUseCase,
+} from "@aotter/mantle-spec";
+
+const parsed = parseManifestSources({
+  sources: [{ sourceId: "host:content-model", text: manifestYaml }],
+});
+if (!parsed.ok) throw new Error(JSON.stringify(parsed.diagnostics));
+
+const checked = ValidateManifestsUseCase.run({
+  parsed: parsed.value,
+  siteLocales: ["zh-TW", "en-US"],
+});
+if (checked.errorCount || !checked.linked) {
+  throw new Error(JSON.stringify(checked.diagnostics));
+}
+
+const article = checked.linked.schemas.find(
+  ({ manifest }) => manifest.metadata.name === "articles",
+)!.manifest;
+const validator = new EntryDataValidator();
+const diagnostics = validator.validate(article, { category: 42 }, { partial: true });
+// INPUT_VALIDATION_FAILED at /category. The host must reject the write.
+```
+
+The non-null assertion is specific to this known fixture. A dynamic host must
+handle an unknown collection explicitly and fail closed. Do not fabricate
+sealed parser/linker values or re-parse the same revision in each request.
+
+`EntryDataValidator` returns diagnostics, not a sanitized payload. It does not
+persist, authorize, coerce the original object, or enforce storage integrity.
+Normalize explicitly in the host before validation and write only after
+successful validation and authorization. An `additionalProperties: true`
+compatibility policy accepts legacy fields; it is not a reason to expose those
+fields publicly.
+
+`partial: true` relaxes top-level required fields for drafts, while still
+checking supplied types and nested required fields. Validate without `partial`
+when the host needs a complete record, alongside its own publication rules.
+Create a fresh validator for each model revision: its compiled cache is keyed
+by manifest name (and partial/full mode), not by a changing schema body.
+
+## Honest ER diagrams and metadata export
+
+- Derive model nodes and field details from Schema properties. Use a small
+  host-owned relationship registry for relations not represented by Mantle
+  grammar; show logical joins distinctly from actual database foreign keys.
+- The fixture's `x-example-source` and `x-example-relations` live inside JSON
+  Schema. They are illustrative vendor annotations, **not new Mantle keys or
+  executable relationship definitions**. Core may preserve them without
+  interpreting them. The host must validate their shape and endpoint fields.
+- Do not label a filename/slug join as `x-mantle-ref`: that keyword represents
+  Mantle entry-ID references. A category slug matching a key inside a YAML
+  array remains a host-specific relation, not a generated SQL foreign key.
+- `translates` validates the parent and join-field declarations, not whether
+  actual translation records exist. A Spec-only host still owns allowed
+  locales, uniqueness, fallback, and orphan handling. See
+  [ADR-0010](adr/0010-locale-and-translates.md); Runtime locale/storage gates
+  are not installed by this recipe.
+- A read-only inventory can add derived fields such as filename `slug` or
+  directory `locale` without changing stored files. Document that projection;
+  it is not evidence that existing data is ready for Runtime import.
+- The fixture uses JSON Schema `readOnly` as an inventory annotation. It is
+  not a security boundary: entry validation does not enforce host write
+  permissions. Export only after applying the host's metadata access policy.
+- Exclude credential/account models and private data. Export schemas, not
+  records. Where appropriate, require an administrator and use
+  `Cache-Control: private, no-store` for model and export endpoints.
+- Keep the graph usable on narrow screens: searchable model selection,
+  focused relationships, zoom/scroll, keyboard controls and a field-table
+  alternative. A graph must not be the only accessible representation.
+
+## Reproducible evidence
+
+From this SDK checkout:
+
+```sh
+pnpm --filter @aotter/mantle-spec test -- test/spec-only-host.test.ts
+pnpm --filter @aotter/mantle-spec typecheck
+```
+
+The [regression test](../packages/mantle-spec/test/spec-only-host.test.ts)
+exercises the public export surface, manifest round trips, translation linking,
+and strict/partial entry validation without Runtime. It is an SDK regression
+fixture, not a new Starter workspace or a certification test suite.
+
+An adopting host must also test its own installed package, real content
+compatibility, HTTP authorization/invalid-input paths, metadata exclusions and
+responsive UI. Existing data need not be published or uploaded to prove this.
+Keep sensitive evidence internal and expose only an agreed verification report.
+
+Spec validation against an exact SDK version is not official certification or
+proof of Runtime compatibility, data migration, or security. Recognition policy
+is tracked separately in [#840](https://github.com/aotter/mantle/issues/840).

package/docs/transaction-patterns.md

@@ -0,0 +1,5 @@
+# Transaction patterns
+
+This guide moved into the handbook: [`docs/handbook/examples/commerce-transaction.md`](handbook/examples/commerce-transaction.md).
+
+The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.2-alpha.2",
   "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/",
@@ -27,10 +27,6 @@
       "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"
@@ -83,21 +79,21 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.0-alpha.9",
-    "@aotter/mantle-spec": "0.1.0-alpha.9"
+    "@aotter/mantle-runtime": "0.1.2-alpha.2",
+    "@aotter/mantle-spec": "0.1.2-alpha.2"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.7.1",
+    "better-auth": "1.7.2",
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
-    "zod": "^4.0.0",
-    "@aotter/mantle-admin": "0.1.0-alpha.9",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.9",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.9",
-    "@aotter/mantle-vercel": "0.1.0-alpha.9",
-    "@aotter/mantle-web": "0.1.0-alpha.9",
-    "@aotter/mantle-bun": "0.1.0-alpha.9"
+    "zod": "^4.5.0",
+    "@aotter/mantle-admin": "0.1.2-alpha.2",
+    "@aotter/mantle-admin-ui": "0.1.2-alpha.2",
+    "@aotter/mantle-bun": "0.1.2-alpha.2",
+    "@aotter/mantle-vercel": "0.1.2-alpha.2",
+    "@aotter/mantle-web": "0.1.2-alpha.2",
+    "@aotter/mantle-cloudflare": "0.1.2-alpha.2"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -134,18 +130,18 @@
   "devDependencies": {
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.7.1",
-    "hono": "^4.12.34",
+    "better-auth": "1.7.2",
+    "hono": "^4.13.3",
     "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10",
-    "zod": "^4.4.3",
-    "@aotter/mantle-admin": "0.1.0-alpha.9",
-    "@aotter/mantle-bun": "0.1.0-alpha.9",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.9",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.9",
-    "@aotter/mantle-vercel": "0.1.0-alpha.9",
-    "@aotter/mantle-web": "0.1.0-alpha.9"
+    "vitest": "^4.1.11",
+    "zod": "^4.5.4",
+    "@aotter/mantle-admin-ui": "0.1.2-alpha.2",
+    "@aotter/mantle-admin": "0.1.2-alpha.2",
+    "@aotter/mantle-bun": "0.1.2-alpha.2",
+    "@aotter/mantle-cloudflare": "0.1.2-alpha.2",
+    "@aotter/mantle-vercel": "0.1.2-alpha.2",
+    "@aotter/mantle-web": "0.1.2-alpha.2"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -8,8 +8,8 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 | [`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. |
-| [`install`](install/SKILL.md) | User wants to create a local Mantle site from a deterministic starter bundle or continue an existing local / landing-generated project. |
+| [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
+| [`install`](install/SKILL.md) | User wants to create a local Mantle site by direct authoring or continue an existing local / landing-generated project. |
 | [`provision`](provision/SKILL.md) | User wants a local or landing-generated project shipped to Cloudflare with production auth and operator handoff. |
 
 The skills target Mantle's v0.1 grammar. The installed package version, not
@@ -28,8 +28,8 @@ enforces the columns below.
 | `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. |
+| `update` | SDK upgrade or plugin lock review | 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 | author 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. |
 

package/skills/develop/SKILL.md

@@ -30,24 +30,19 @@ version; never use `develop` branch docs for a versioned consumer project.
 
 ## Existing Examples
 
-Before inventing a Mantle pattern, inspect
-[`aotter/mantle-starters`](https://github.com/aotter/mantle-starters).
-Use a tag matching the installed Mantle version when available; use `develop`
-only for unreleased work. `blank/` shows the base application shape and
-`overlays/<type>/` contains working examples of manifests, handlers, routes,
-page seeds, and feature wiring. Copy the smallest matching pattern. Do not edit
-or copy generated `provision-bundles/*.json` by hand.
+Read installed `docs/handbook/start/project-and-cli.md`, `docs/examples/minimal-worker/`
+and `docs/handbook/examples/commerce-transaction.md` before inventing a pattern. The reference
+consumer is test/documentation, not a Starter or a fixed application shape.
 
 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.
+exposed collections. Do not auto-publish every Schema. Applications document 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 projects expose the shipping
+Use the project's scripts first; applications use 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:
@@ -57,8 +52,8 @@ pnpm exec mantle --help
 pnpm validate
 ```
 
-This CLI validates and derives artifacts from an existing materialized
-project; starter creation is owned by the provision-bundle flow.
+This CLI validates and derives artifacts from application-authored manifests.
+It does not create projects, business schemas or a visitor homepage.
 
 ## Core Model
 
@@ -77,9 +72,9 @@ the atoms cannot express the behavior.
 
 ## Content Edits
 
-- A generated homepage reads its repo seed before auth. Change that seed for
-  local/static page copy; after auth, use Admin or Staff MCP for runtime-backed
-  content.
+- If a legacy homepage imports a repo seed, edit it for local/static copy.
+  Otherwise follow the actual frontend content source. Use Admin or Staff MCP
+  for runtime-backed content.
 - For a new submitted field, update the stored `Schema` and the public
   `Procedure.spec.input` before the seed/form. Keep public mutation inputs
   `additionalProperties: false`; otherwise JSON Schema's default may strip an
@@ -91,10 +86,10 @@ the atoms cannot express the behavior.
   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;
+  Procedure input `enum` together. Keep translated labels in the frontend content source;
   Admin and Staff MCP derive their typed controls from the manifest values.
-- For a new section display property, update the content type and the `page`
-  Schema's `sections[].properties`; an undeclared property has no
+- If the application has a `page` Schema with sections, update its declared
+  section properties when adding display fields; an undeclared property has no
   runtime-backed Admin or Staff MCP path.
 - Update notification handlers when they need the new field. Test the stored
   entry, not only the HTTP `{ "ok": true }` response.
@@ -120,17 +115,17 @@ the atoms cannot express the behavior.
 
 ## Adapter Boundary
 
-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.
+The runtime is adapter-neutral. A `MantleStorageAdapter` prepares the compiled
+plan into semantic storage ports; `createMantleRuntime` binds that prepared
+storage and selected capabilities. Database drivers and asset serving belong
+to the host/optional composition. Follow the installed adapter guide.
 
 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.
 
 Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
-`entryReader`, and `siteConfig`; do not query Mantle-owned `entries` or
+`runtime.entries`, and optional `runtime.siteConfig`; do not query Mantle-owned `entries` or
 `site_config`, reach through deprecated `runtime.db`, copy generated-column
 names, or construct SDK KV keys. Cloudflare bindings belong only at the
 composition root. If a normal feature cannot be expressed through a
@@ -141,8 +136,8 @@ teaching the project Mantle internals.
 
 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
+or mixed bindings. Preserve the explicit mode recorded in Worker config
+and any legacy launch state, 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.
@@ -191,7 +186,7 @@ Use `pnpm dev` for local preview when the project provides it.
 ## Connect a Local MCP Client
 
 Start the project with `pnpm dev`, then use the exact local origin it prints.
-Generated Cloudflare projects normally expose:
+The conventional Cloudflare adapter exposes:
 
 - `http://localhost:8787/mcp` for public tools;
 - `http://localhost:8787/mcp/staff` for authenticated authoring tools.
@@ -216,8 +211,8 @@ cache.
 
 ## Rules
 
-- Put all content model changes in `manifests/site.yaml`; other manifest
-  filenames are rejected.
+- Keep content models in the configured manifest directory; its immediate
+  `.yaml` and `.yml` files are loaded together.
 - 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

@@ -1,6 +1,6 @@
 ---
 name: install
-description: Start a new Mantle site locally from a deterministic starter bundle, or orient and continue an existing local or Mantle landing project. Use when the user gives a Mantle repository URL and asks to try or build with it, invokes the Mantle install skill, wants a new Mantle site, or opens an existing generated site.
+description: Author a new Mantle application directly from version-matched SDK docs, or continue an existing project. Use when asked to install Mantle, build a Mantle application, or open a Mantle repository.
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/install/SKILL.md
@@ -11,160 +11,68 @@ metadata:
 
 # Mantle Install
 
-Route by the working directory:
-
-- If it already contains `.mantle/launch-state.json` or depends on
-  `@aotter/mantle`, continue the existing project.
-- Otherwise create a new local project from a deterministic provision bundle.
-  Do not use the Mantle SDK checkout as the application.
-
-Mantle landing uses the same bundles but continues through GitHub, Cloudflare,
-and optional paid hosted auth. Use landing only when the user wants that
-hosted provider flow.
-
-## Create a Local Project
-
-1. Infer the closest starter from the user's request. Ask only when two choices
-   would materially change the result.
-
-| Intent | Type |
-|---|---|
-| API/MCP backend or empty base | `blank` |
-| Small public or company site | `presence` |
-| Form, application, or submission flow | `intake` |
-| Blog, docs, posts, or editorial site | `publication` |
-| Catalog or order intent | `transaction` |
-| Booking or request intent | `reservation` |
-
-Community and membership types are not released; `create` refuses them. Build
-those on `blank` or the closest released type.
-
-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
-npx -y @aotter/mantle@alpha create <type> <target-dir> \
-  --brand "<brand>" \
-  --description "<one sentence>" \
-  --locales <comma-separated-locales>
-```
-
-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
-   editing that checked-in seed; generated content modules import it directly.
-   This is application source, not direct D1 authoring. Do not use Staff MCP
-   until an auth provider is configured.
-
-5. Initialize and verify the local project:
-
-```bash
-cd <target-dir>
-git init -b main
-pnpm install --frozen-lockfile
+Mantle is an embeddable manifest engine. The application owns its source and
+provider configuration. There is no Starter/type picker or `mantle create`.
+Do not use the SDK checkout as the application, copy an old Starter tree, or
+turn `generate` into implicit scaffolding.
+
+## New application
+
+1. Determine the actual host and required surfaces from the request. Reuse an
+   existing application when available; otherwise work in its own directory.
+   Do not assume Cloudflare, public HTML or Admin is required. Check Node 22+
+   and pnpm 9+ for these SDK examples.
+2. Choose the requested exact SDK version, or resolve the intended release
+   channel once. Pin all selected `@aotter/mantle*` dependencies to that same
+   version. Install only the adapter/optional packages the application needs.
+   If a global scope registry overrides public npmjs, use a project-owned
+   `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
+3. Read the installed `node_modules/@aotter/mantle/docs/handbook/start/project-and-cli.md`.
+   The version-matched `docs/examples/minimal-worker/` is a runnable Cloudflare
+   reference, not a template to install wholesale. Other hosts use the embedded
+   adapter guides. Author package scripts, manifests, entry and configuration
+   for the user's requirements. No default notes model, home page, icon,
+   launch metadata or frontend is required.
+4. Compile and verify using the application's commands. The fundamental CLI
+   sequence is:
+
+```sh
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+pnpm exec mantle validate
 pnpm exec mantle skills
 pnpm exec mantle skills --check
-pnpm validate
-pnpm typecheck
-pnpm dev
-```
-
-Open `http://localhost:8787`. Public preview works before auth is configured;
-auth-gated routes may return `503 setup_incomplete`. `blank` is intentionally
-empty; typed launches must show the selected seed. Do not infer SDK public
-render routes from the Core README—generated projects mount only the URL
-surface documented in their own README.
-
-## Continue an Existing Project
-
-Read these before editing:
-
-1. `.mantle/launch-state.json`, `.mantle/features.json`, and
-   `.mantle/handoff.md`.
-2. `package.json` for the installed `@aotter/mantle*` versions.
-
-Install the locked dependency graph and replace any stale projected Core
-skills before reading them:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-```
-
-Then read:
-
-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
-the installed version. Never use `develop` docs for a versioned project.
-
-Do not branch on how the project was created. Verify the current git remote,
-live URL, and auth response, then skip work that is already complete.
-
-Then run:
-
-```bash
-pnpm exec mantle skills --check
-pnpm validate
-pnpm typecheck
-```
-
-Inspect the already composed manifest, page, and seed files before changing
-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
 ```
 
-## Production
+Run the project's TypeScript check and start its actual local server. Probe a
+route the application declares; an API-only project may correctly return 404
+at `/`. Auth routes may return `503 setup_incomplete` until the selected auth
+provider is configured. Do not introduce an auth bypass to make smoke pass.
 
-Local cold start intentionally stops before GitHub and Cloudflare operations.
-When the user asks to ship, use `mantle:provision` from the installed plugin or
-`node_modules/@aotter/mantle/skills/provision/SKILL.md`.
+Commit the resolved lockfile in the application's normal workflow; subsequent
+installs use `pnpm install --frozen-lockfile`. Do not initialize/push a remote,
+provision resources, deploy or commit secrets as part of local verification.
 
-Mantle landing is the first-run option when the user wants Mantle to create the
-private GitHub repo, connect Cloudflare, and offer paid hosted auth. Free
-self-hosted auth requires the owner to configure their GitHub OAuth App and
-provider secrets.
+## Existing application
 
-## Report
+Read package.json, lockfile, actual entry, manifest files, provider config and
+project instructions. `.mantle/launch-state.json`, features or handoff files
+are optional legacy context, never prerequisites. Preserve them and user code.
+Install the frozen dependency graph, project installed Core skills, then read
+those skills and embedded docs. Never apply develop docs to an older package.
+Use the installed `mantle --help` and the project's scripts as authority.
 
-Return:
+For legacy alpha.17 projects, retain their pinned behavior until an explicit
+upgrade is requested; read `docs/migration-0.1.2.md` before upgrading. Do not
+rewrite provider identities, delete metadata or fetch a nonexistent new Starter
+tag. SDK upgrades follow the update skill, not a bundle comparison command.
 
-- created or opened project path;
-- selected type and why;
-- local URL;
-- validation and typecheck results;
-- observed GitHub, deploy, and auth state;
-- three tailored next options: shape the visual experience, build the first
-  real business workflow, or finish deploy/auth if incomplete. Never leave
-  auth or seed data as the only next step.
+## Ship and report
 
-## Don't
+When deployment is requested, follow the installed provision skill and the
+observed host configuration. Legacy Landing remains an alpha.17 product; it
+is not a launch dependency for new Core projects.
 
-- Don't use the Mantle SDK checkout as the generated application.
-- Don't hand-compose starter layers; materialize the generated provision
-  bundle.
-- Don't push, deploy, or configure providers during local cold start.
-- Don't commit provider secrets.
-- Don't block the first useful page on optional media storage.
+Report the project path, exact SDK version, local URL/HTTP result and checks,
+plus any genuinely missing auth/provider setup. Do not claim a working homepage
+or authenticated MCP based only on successful generation.

package/skills/provision/SKILL.md

@@ -16,8 +16,9 @@ user asks to create remote resources or ship production.
 
 ## Source of Truth
 
-1. Read `.mantle/launch-state.json`, `.mantle/handoff.md`, `wrangler.toml`,
-   and the current git remotes.
+1. Read the actual provider config (`wrangler.jsonc` or `wrangler.toml`),
+   application entry and git remotes. Read legacy `.mantle/launch-state.json`
+   and `.mantle/handoff.md` only when present; do not create them as prerequisites.
 2. Read installed `@aotter/mantle*` versions from `package.json`.
 3. Use matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 4. Never infer provider authority from launch state. Confirm the active GitHub
@@ -142,7 +143,7 @@ authenticates, then skip the self-hosted flow.
 
 Media uploads are optional. Configure R2 only when the owner asks for
 staff-managed files; then read
-`node_modules/@aotter/mantle/docs/media-uploads.md`.
+`node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md`.
 
 ## Handoff