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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.63",
+  "version": "0.0.11-alpha.64",
   "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/",
@@ -14,6 +14,7 @@
   "main": "./dist/spec.js",
   "types": "./dist/spec.d.ts",
   "bin": {
+    "mantle": "./dist/cli.js",
     "mantle-harness": "./dist/harness-cli.js"
   },
   "publishConfig": {
@@ -54,10 +55,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.63",
-    "@aotter/mantle-runtime": "0.0.11-alpha.63",
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.63",
-    "@aotter/mantle-spec": "0.0.11-alpha.63"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.64",
+    "@aotter/mantle-spec": "0.0.11-alpha.64",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.64",
+    "@aotter/mantle-runtime": "0.0.11-alpha.64"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",
@@ -73,6 +74,7 @@
     "better-auth": "^1.6.23",
     "hono": "^4.12.30",
     "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
     "zod": "^4.4.2"
   },
   "engines": {
@@ -81,6 +83,7 @@
   "scripts": {
     "prebuild": "rm -rf dist .tsbuildinfo",
     "build": "tsc -b tsconfig.lib.json",
-    "typecheck": "tsc --noEmit -p tsconfig.lib.json"
+    "typecheck": "tsc --noEmit -p tsconfig.lib.json",
+    "test": "vitest run"
   }
 }

package/skills/README.md

@@ -9,26 +9,25 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 | [`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. |
-| [`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 a local or landing-generated project shipped to Cloudflare with production auth and operator handoff. |
 
-The skills target `mantle@v0.1.0`. Each one names its assumed grammar version
-in front-matter `metadata.applies_to`; future versions add a sibling SKILL.md
-or update the existing one.
+The skills target Mantle's v0.1 grammar. The installed package version, not
+duplicated skill prose, selects the exact runtime and embedded docs.
 
 ## Skill authority
 
-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.
+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
+`node_modules/@aotter/mantle/docs/` are the single version-matched authority.
+Starter launch files and plugin recipes are project context, not competing
+contracts.
 
-## Marketplace install
+## Source-repository marketplace install
 
-The repo is also an agent plugin bundle:
+The source repository is also an agent plugin bundle. These manifests are not
+duplicated into the npm package:
 
 - Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
 - Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
@@ -37,11 +36,14 @@ The repo is also an agent plugin bundle:
 
 ## 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.
+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.
 
 ## Discoverability
 
-The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "extend my CMS", "deploy"). No `/skill install` slash command is required — point the agent at the GitHub raw URL or pass the markdown content directly.
+The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "develop my Mantle site", "deploy"). No `/skill install` slash command is required — point the agent at a version tag or pass the version-matched markdown content directly.
 
 ## Conventions
 
@@ -56,4 +58,6 @@ Each SKILL.md ships:
 - **Don't** — reviewer-style list of patterns the agent must reject (often citing ADRs).
 - **When you're done** — what to report back to the user.
 
-If you're writing a new SKILL, follow the same structure. The CLI commands referenced are stable across v0.1.x.
+If you're writing a new SKILL, follow the same structure. Commands and prose
+must match the package version that carries the skill; later prereleases may
+revise both together.

package/skills/develop/SKILL.md

@@ -4,14 +4,14 @@ description: Work on any Mantle project using the Core SDK contract. Use for man
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/develop/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Mantle Develop
 
-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.
+This is the Core workflow skill for an existing Mantle project. Repo-local
+copies are byte-for-byte projections from the installed package; its embedded
+docs govern runtime/API behavior.
 
 ## First Read
 

package/skills/install/SKILL.md

@@ -4,7 +4,7 @@ description: Start a new Mantle site locally from a deterministic starter bundle
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/install/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Mantle Install
@@ -75,6 +75,8 @@ the generated bundle JSON.
 cd <target-dir>
 git init -b main
 pnpm install --frozen-lockfile
+pnpm exec mantle skills
+pnpm exec mantle skills --check
 pnpm validate
 pnpm typecheck
 pnpm dev
@@ -93,6 +95,18 @@ 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 `.agent/skills/` or `.claude/skills/`.
 4. Matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 
@@ -105,7 +119,7 @@ live URL, and auth response, then skip work that is already complete.
 Then run:
 
 ```bash
-pnpm install --frozen-lockfile
+pnpm exec mantle skills --check
 pnpm validate
 pnpm typecheck
 ```

package/skills/plugin/SKILL.md

@@ -4,7 +4,7 @@ description: Discover, plan, apply, and verify Mantle marketplace plugins throug
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/plugin/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Mantle Plugin

package/skills/provision/SKILL.md

@@ -4,7 +4,7 @@ description: Ship a local or Mantle landing-generated project to Cloudflare and
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/provision/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Provision a Mantle Project

package/skills/theme/SKILL.md

@@ -4,31 +4,33 @@ description: Apply brand and visual direction in a generated Mantle project usin
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/theme/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Mantle Theme
 
-Theme work is project-owned source editing. Starters may ship Kiwa files,
+Theme work is project-owned source editing. Starters may ship UI 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/web/`, `src/theme*`, and `kiwa-ui.json`
+2. `styles/`, `components/`, `src/web/`, `src/theme*`, and UI-library config
    if present.
-3. `kiwa/manifest.json` for the pinned source and per-file `mirrors`.
+3. A vendored UI palette's manifest and license, if present.
 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.
+  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.
+- 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
+  fork/wrap it under `src/web/sections/`; do not import the palette from
+  Worker or runtime code.
 
 ## Work
 

package/skills/update/SKILL.md

@@ -4,7 +4,7 @@ description: Check a Mantle project for drift against its Core SDK, starter sour
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/update/SKILL.md
-  applies_to: mantle@v0.1.0
+  applies_to: mantle grammar v0.1
 ---
 
 # Mantle Update
@@ -19,23 +19,37 @@ Use this for drift checks. Do not blindly overwrite user-owned code.
 3. `.mantle/plugins.json` and `.mantle/plugins.lock.json` when plugins are
    installed.
 4. Existing project scripts such as `mantle:update`, `validate`, and
-   `typecheck`.
+   `typecheck`; the installed `mantle update` command is authoritative.
 
 ## Workflow
 
 1. Start from a clean git worktree.
 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.
+   installed command with that immutable ref:
+
+```bash
+pnpm exec mantle update --ref <immutable-ref>
+```
+
+   For the one-time alpha.63 bridge, invoke the exact newer Core package and
+   provide the current bundle location because alpha.63 metadata does not
+   contain it:
+
+```bash
+pnpm dlx @aotter/mantle@<exact-version> update \
+  --ref <immutable-ref> \
+  --bundle-base-url 'https://raw.githubusercontent.com/aotter/mantle-starters/{ref}/provision-bundles'
+```
+
+   Do not extract or replace a repo-local updater. The Core command accepts
+   the alpha.63 no-`v` source ref, writes only the report, and records the
+   versioned bundle location for the reviewed metadata migration.
 3. Read the generated report before editing.
 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:
+6. Apply only the report's `.mantle/launch-state.json` and
+   `.mantle/features.json` metadata migration, preserving every other field.
+7. Re-run:
 
 ```bash
 pnpm validate
@@ -49,15 +63,13 @@ 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.
+- Never copy generated comparison versions of `.mantle/launch-state.json` or
+  `.mantle/features.json`; the report omits them and gives a field-level
+  migration instead. Preserve Worker/D1 names, bindings, origins, provider
+  values, and all unlisted launch state.
+- The updater reproduces project identity in legacy Wrangler files. If
+  `upstream` proposes `mantle-<type>` names for a real project, stop: the
+  bundle is incompatible and must not be ported.
 - A large `local` section is normal after customization. Counts are not a
   confidence score.
 

package/skills/customize-design/SKILL.md

@@ -1,215 +0,0 @@
----
-name: customize-design
-description: Layer custom design over a mantle publication starter project using the L1–L4 theme stack (tokens / extraCss+icons+i18n / Header+Footer+PageShell slots / whole-template fork). Use when the user wants to rebrand, restyle, or swap UI pieces without forking the whole starter.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: skills/customize-design/SKILL.md
-  applies_to: mantle@v0.1.0 + publication archetype
----
-
-# Customize the design of a mantle publication site
-
-You are layering a consumer theme over a project built from the `publication` starter. The baseline lives at `src/theme.default/` (read-only by convention). Consumer overrides live at `src/theme/`. Always escalate from L1 → L4 and stop at the lowest layer that solves the user's stated need.
-
-## Layer cheatsheet
-
-| Layer | Where | Use for |
-|---|---|---|
-| **L1** tokens | `src/theme/tokens.ts` | palette, font stack, type scale, measure, gutter |
-| **L2** extraCss | `src/theme/index.ts:extraCss` | extra CSS rules (border-radius, hero size, etc.) |
-| **L2** icons | `src/theme/icons.ts` | replace baseline icons by name; add new ones |
-| **L2** i18n | `src/theme/i18n/<locale>.json` | retitle UI strings per locale (deep-merge) |
-| **L3** components — chrome | `src/theme/components/{Header,Footer}.tsx` | swap navigation chrome |
-| **L3** components — body layout | `src/theme/components/PageShell.tsx` | reshape body layout: sidebar variants, sticky CTAs, full-bleed hero, alternative Header / `<main>` / Footer arrangement |
-| **L4** templates | `src/theme/templates/<name>.tsx` | replace a page kind end-to-end |
-
-## Conversation pattern
-
-1. **Map the user's intent to a layer.** "Change the colors" → L1. "Different header structure" → L3. Tell the user the layer + the escape hatch ("I'll start at L1; if it doesn't get close enough, we can escalate to a custom Header at L3").
-2. **Fork → edit → review.** Run `pnpm theme:fork <path>`, edit the new file in `src/theme/`, ask the user to reload `pnpm dev`.
-3. **On dissatisfaction, iterate or revert.** `pnpm theme:reset <path>` removes the override and restores the baseline. The user can roll back any single layer without affecting others.
-
-## Layer recipes
-
-### L1 — tokens
-
-```bash
-pnpm theme:fork tokens.ts
-```
-
-Edit `src/theme/tokens.ts`:
-
-```ts
-export const TOKENS_CSS = `
-:root {
-  --paper: #fffbf3;
-  --ink: #1a1814;
-  --accent: #a3331f;
-  --font-display: "Fraunces", Georgia, serif;
-  --font-body: "Source Serif 4", Georgia, serif;
-  --measure: 36rem;
-}
-[data-theme="dark"] {
-  --paper: #1a1814;
-  --ink: #f1ebdf;
-  --accent: #e6594a;
-}
-`;
-```
-
-The override is concatenated AFTER baseline tokens, so later declarations win on standard CSS specificity. Only redeclare the vars you want to change.
-
-**Custom web fonts**: if `--font-display` references a font not in the system stack, register it with L2 `extraCss` using `@font-face`. Don't use CSS `@import`: `extraCss` is appended after baseline rules, and browsers ignore late `@import` statements.
-
-```ts
-const overrides: ThemeOverride = {
-  extraCss: `
-    @font-face {
-      font-family: "FrauncesLocal";
-      src: url("/fonts/fraunces.woff2") format("woff2");
-      font-weight: 400 700;
-      font-display: swap;
-    }
-  `,
-  tokens: `:root { --font-display: "FrauncesLocal", Georgia, serif; }`,
-};
-```
-
-Revert: `pnpm theme:reset tokens.ts`.
-
-### L2 — extraCss
-
-Edit `src/theme/index.ts` — set the `extraCss` field directly (no fork needed, it's just a string):
-
-```ts
-const overrides: ThemeOverride = {
-  extraCss: `
-    .site-main { max-width: 64rem; }
-    .post-cover { border-radius: 8px; }
-    blockquote { background: var(--rule); padding: 1rem; }
-  `,
-};
-```
-
-Revert: clear the field.
-
-### L2 — icons
-
-```bash
-pnpm theme:fork icons.ts
-```
-
-Edit `src/theme/icons.ts`:
-
-```ts
-const customIcons: Record<string, string> = {
-  // override an existing baseline icon
-  globe: '<circle cx="12" cy="12" r="9"/><path d="..."/>',
-  // add a new icon
-  logo: '<path d="M12 2L2 7v10l10 5 10-5V7l-10-5z"/>',
-};
-export default customIcons;
-```
-
-Use in any template via `icon("logo", { size: 24 })`. SVG path content only — no `<svg>` wrapper. The fork ships a stub (not a copy of the baseline), since you're extending a registry.
-
-Revert: `pnpm theme:reset icons.ts`.
-
-### L2 — i18n
-
-```bash
-pnpm theme:fork i18n/en.json
-```
-
-Edit `src/theme/i18n/en.json` — partial bundle, deep-merged over baseline:
-
-```json
-{
-  "header": { "posts": "Articles" },
-  "home": { "eyebrow": "the dispatch" },
-  "notFound": { "title": "Lost at sea" }
-}
-```
-
-Other keys carry forward from baseline. To support a new locale (`ja`, `de`, etc.), edit `src/i18n/<locale>.json` directly — locale set is consumer-level, not a theme slot.
-
-Revert: `pnpm theme:reset i18n/en.json`.
-
-### L3 — Header / Footer
-
-```bash
-pnpm theme:fork components/Header.tsx
-pnpm theme:fork components/Footer.tsx
-```
-
-Use this when the user wants different chrome — different brand mark, nav arrangement, language switcher, footer copy — but the page body still reads top → main → bottom. Key contracts:
-
-- Don't change the props signature: `Header(props: HeaderProps)`.
-- `props.site.brand`, `props.site.locales`, `props.locale`, `props.current` are available.
-- Baseline siblings (icon registry, etc.) auto-rewritten on fork to `../../theme.default/<path>`. Keep those unless you want to drop the baseline icon set.
-
-Same shape for `Footer`.
-
-Revert: `pnpm theme:reset components/Header.tsx`.
-
-### L3 — PageShell (body layout)
-
-```bash
-pnpm theme:fork components/PageShell.tsx
-```
-
-Use this to reshape the **body layout** rather than swap chrome — for example:
-
-- Sidebar with table-of-contents alongside `<main>` for docs-lite pages
-- Sticky CTA bar between `<main>` and `<Footer>`
-- Full-bleed hero section above Header on the home page
-- Different Header / `<main>` / Footer ordering (e.g., side-rail logo)
-- Custom `<main>` container width or padding rules per template kind
-
-The forked PageShell takes ownership of how (or whether) to render the Header / Footer overrides. The baseline composes them top → main → bottom; a consumer-supplied PageShell can ignore or recompose them.
-
-Revert: `pnpm theme:reset components/PageShell.tsx`.
-
-### Layout is not forkable
-
-Only `Header`, `Footer`, and `PageShell` are supported component slots. `theme:fork components/Layout.tsx` exits with a clear error pointing at PageShell as the body-layout escape hatch. Don't try to override Layout by hand-editing `src/theme/components/Layout.tsx` outside the fork machinery — the override surface won't register it.
-
-`Layout` (the document envelope — `<html>` / `<head>` / `<body>` + SEO meta + theme bootstrap) is locked. If the user needs to change `<head>` content beyond what tokens / extraCss can express, that crosses the starter-family line — switch starter rather than fork every template.
-
-### L4 — whole template (escape hatch)
-
-```bash
-pnpm theme:fork templates/post.tsx
-```
-
-Edit `src/theme/templates/post.tsx`. The forked file imports baseline Layout via `../../theme.default/components/Layout.js`.
-
-L4 is the last resort. If the user wants more than two L4 forks, suggest the conversation: "The shape you're describing isn't really `publication` any more — it sounds closer to `community` (member posts), `micro-shop` (catalog + orders), or `leads-inbox` (lead pipeline). Once you cross those lines, switching starter family is cheaper than forking more templates."
-
-Revert: `pnpm theme:reset templates/post.tsx`.
-
-## Hard rules
-
-- Don't edit `src/theme.default/`. Use fork.
-- Don't add new top-level keys to `ThemeOverride` — extend through the existing slots.
-- `Layout` is locked — change envelope shape via L4 forks (every template) or pick another starter.
-- After a fork, the file is a normal `.ts` / `.tsx` / `.json` — TS errors surface on `pnpm typecheck` as usual.
-
-## Diagnostic recipes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| `pnpm theme:fork X` exits with "Override already exists" | Already forked | `pnpm theme:reset X` first |
-| `pnpm typecheck` fails in `src/theme/components/<Name>.tsx` after fork | A baseline import didn't auto-rewrite | Manually change `from "../<sibling>"` to `from "../../theme.default/<sibling>"` |
-| Color change not visible after edit | Browser CSS cache | Hard reload (Cmd+Shift+R / Ctrl+F5); if it persists, restart `pnpm dev` |
-| Forked `en.json` discards keys I didn't redeclare | Bundle isn't deep-merging | Verify `src/i18n/index.ts:deepMerge` is present. If missing, update to latest starter |
-
-## When you're done
-
-Tell the user three things:
-
-1. **Layer landed at** — "I made the change at L1 (tokens) — palette only, no structural edits."
-2. **Revert command** — "If you don't like it, `pnpm theme:reset tokens.ts` rolls it back."
-3. **Next escalation step** — "If the colors aren't enough, the next layer would be L3 — replace the Header component."
-
-Stop after one layer per turn unless the user explicitly says "go deeper". The point of layering is to keep each customization step reversible and inspectable.