@aotter/mantle 0.0.11-alpha.53 → 0.0.11-alpha.54

package/docs/adapter-guide.md

@@ -86,6 +86,13 @@ Minimum HTTP behavior for a full adapter:
 - Evaluate target auth and dynamic guards through the runtime use cases; do
   not duplicate guard logic in HTTP handlers.
 
+For the Cloudflare adapter, public rendering requires three matching consumer
+inputs: `mountPublicRoutes(...)` route declarations, a `TemplateRegistry`
+passed through `CmsConfig.templates`, and a `publicPathResolver` passed through
+`CmsConfig.publicPathResolver`. Omitting public routes is valid for a headless
+consumer; mounting every Schema automatically is not, because some collections
+are private even when they contain a slug.
+
 Minimum auth/MCP behavior:
 
 - Provide Better Auth-compatible sign-in/session routes for the platform.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.53",
+  "version": "0.0.11-alpha.54",
   "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,10 +47,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.53",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.53",
-    "@aotter/mantle-runtime": "0.0.11-alpha.53",
-    "@aotter/mantle-spec": "0.0.11-alpha.53"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.54",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.54",
+    "@aotter/mantle-runtime": "0.0.11-alpha.54",
+    "@aotter/mantle-spec": "0.0.11-alpha.54"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",

package/skills/README.md

@@ -19,10 +19,12 @@ 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.
+The `mantle:*` namespace is owned by `@aotter/mantle`. Generated starters may
+vendor Core workflow skills pinned to their starter ref for offline use. Use
+those skills for workflow and compatibility recovery; use the installed
+package version plus `node_modules/@aotter/mantle/docs/` for runtime/API
+behavior. Starter launch files and plugin recipes are project context, not
+competing contracts.
 
 ## Marketplace install
 

package/skills/develop/SKILL.md

@@ -9,17 +9,19 @@ metadata:
 
 # 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.
+This is the Core workflow skill for an existing Mantle project. A repo-local
+copy may carry compatibility guidance pinned to the starter ref; the installed
+package version and embedded docs govern runtime/API behavior.
 
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
 2. `manifests/` and `src/mantle/config.ts` for the active atoms and adapter wiring. If the project is older, check `src/mantleConfig.ts`.
-3. Optional local context: `.mantle/launch-state.json`, `.mantle/handoff.md`,
+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`,
    `.mantle/plugins.json`, `.mantle/plugins.lock.json`, and `.mantle/recipes/`.
-4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
+5. 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. Remote docs must use a tag matching the installed
@@ -32,8 +34,13 @@ Before inventing a Mantle pattern, inspect
 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,
-pages, and feature wiring. Copy the smallest matching pattern. Do not edit or
-copy generated `provision-bundles/*.json` by hand.
+page seeds, and feature wiring. Copy the smallest matching pattern. Do not edit
+or copy generated `provision-bundles/*.json` by hand.
+
+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.
 
 ## Authoring CLI
 
@@ -66,6 +73,33 @@ 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.
 
+## 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.
+- 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
+  undeclared field while returning success.
+- For a new section display property, update the content type and the `page`
+  Schema's `sections[].properties`; 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.
+
+## Locales
+
+- `data.locale` is reserved for `localized: true` Schemas. A non-localized
+  Schema must use a domain field such as `replyLocale`.
+- 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.
+- 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`,
@@ -117,6 +151,8 @@ cache.
 ## Rules
 
 - Prefer manifest YAML for content model changes.
+- 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.
 - Do not write directly to D1, KV, Postgres, or object storage for content
   authoring. Use runtime use cases, admin APIs, or Staff MCP.

package/skills/install/SKILL.md

@@ -38,11 +38,15 @@ hosted provider flow.
 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.
 
 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.
+   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.
 
 ```bash
 git clone --depth 1 --branch <starters-ref> \
@@ -59,7 +63,13 @@ 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.
 
-4. Initialize and verify the local project:
+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>
@@ -71,7 +81,10 @@ pnpm dev
 ```
 
 Open `http://localhost:8787`. Public preview works before auth is configured;
-auth-gated routes may return `503 setup_incomplete`.
+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
 

package/skills/theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theme
-description: Apply brand and visual direction in a Mantle project without depending on starter-owned skill semantics.
+description: Apply brand and visual direction in a generated Mantle project using its repo-owned theme and UI contracts.
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/theme/SKILL.md
@@ -17,14 +17,28 @@ tokens, or recipes, but the skill contract is Core-owned.
 1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
 2. `styles/`, `components/`, `src/web/`, `src/theme*`, and `kiwa-ui.json`
    if present.
-3. `manifests/` to understand which content shape drives the public UI.
+3. `kiwa/manifest.json` for the pinned source and per-file `mirrors`.
+4. `manifests/` to understand which content shape drives the public UI.
+
+## Ownership
+
+- `styles/globals.css` is the token contract. Start a whole-site reskin with
+  its `:root` and `.dark` values; Kiwa components inherit those variables.
+- `src/web/` is project-owned. Put new sections and page composition there.
+- `kiwa/` is a vendored snapshot. In `components/`, treat paths whose manifest
+  entry's `mirrors` contains `blank` as sync-managed in the project root. For
+  a structural variant, fork or wrap the block under `src/web/sections/`
+  instead of editing a synced file.
 
 ## Work
 
-- Edit source the repo owns.
 - Use existing tokens, CSS, components, and installed dependencies first.
+- When the generated section type exposes `showImage`, set it to `false` for
+  a text-only hero/content block. Put custom media in a project-owned section.
 - Keep accessibility basics: semantic HTML, focus states, contrast, and
-  keyboard reachability.
+  keyboard reachability. Against a non-default background, check
+  `--foreground-muted` and `--primary`, not only `--foreground`; keep normal
+  text at 4.5:1 or better.
 - 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.
@@ -37,4 +51,7 @@ pnpm typecheck
 pnpm dev
 ```
 
-Visually verify UI changes before calling them done.
+If utility classes changed, rebuild `styles/generated.css` with the project's
+`build:styles`, `check`, or `dev` script. Remove routes/imports for replaced
+assets or styles, then visually verify light/dark contrast and responsive
+behavior before calling the work done.

package/skills/update/SKILL.md

@@ -24,18 +24,45 @@ Use this for drift checks. Do not blindly overwrite user-owned code.
 ## Workflow
 
 1. Start from a clean git worktree.
-2. Run the project's existing update or compare script if one exists.
+2. Resolve a mutable target branch to its current commit SHA, then run the
+   project's existing update or compare script with that immutable ref.
+   If it exits before writing a report (for example, an older
+   `mantle:update` rejects a new bundle placeholder), fetch the provision
+   bundle from that `aotter/mantle-starters` commit, extract
+   `scripts/update.mjs` and `scripts/materialize.mjs` together into a temporary
+   directory, and run the updater from the project root with the same commit
+   SHA. Do not replace the project's updater before reviewing the report.
 3. Read the generated report before editing.
-4. Apply useful differences manually.
-5. Re-run:
+4. Triage each path; do not treat the report as a patch or merge plan.
+5. Port confirmed upstream changes one hunk at a time.
+6. Re-run:
 
 ```bash
 pnpm validate
 pnpm typecheck
 ```
 
+## Report Triage
+
+Current reports compare three states: the original starter ref, the target
+ref, and the local project.
+
+- Review `upstream` to find starter changes worth porting. Use `local` only to
+  understand project-owned drift from the original starter.
+- Never copy generated comparison versions of `wrangler.toml`,
+  `.dev.vars.example`, `.mantle/launch-state.json`, or
+  `.mantle/features.json`. Preserve Worker/D1 names, bindings, origins,
+  provider values, and launch state. Port a reviewed upstream line manually
+  only when it does not replace project identity or state.
+- The updater omits the two `.mantle/*.json` state files and reproduces project
+  identity. If `upstream` proposes `mantle-<type>` names for a real project,
+  stop: the comparator is stale or incompatible. Use the target updater
+  recovery in step 2, then regenerate the report.
+- A large `local` section is normal after customization. Counts are not a
+  confidence score.
+
 ## 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.
+the workflow vocabulary. Repo-local update guidance may recover an older
+updater, but it does not override the installed Core runtime/API contract.