@aotter/mantle 0.1.3-alpha.6 → 0.1.4

package/docs/skills/theme/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: theme
+description: Apply brand and visual direction in a Mantle application using its repo-owned theme and UI contracts.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/theme/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Theme
+
+Theme work is project-owned source editing. Use the actual frontend and its
+tokens/recipes; Core does not install a default home page or UI tree.
+
+For requests to change the Admin console, first read installed
+`node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md` and use the
+develop skill. Labels, widgets, list columns, filters and actions may already
+be manifest-driven. Visitor CSS does not style the prebuilt Admin SPA, and
+`uiSchema` does not accept arbitrary CSS, components or layout keys.
+
+## First Read
+
+1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
+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. The manifest directory selected by project scripts to understand which
+   content shape drives the public UI.
+
+## Ownership
+
+- Use the actual token contract (for example `styles/globals.css`) when present.
+  Check its light/dark values before changing components.
+- `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 the actual entry/config `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
+  fork/wrap it under `src/web/sections/`; do not import the palette from
+  Worker or runtime code.
+
+## 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.
+- Keep accessibility basics: semantic HTML, focus states, contrast, and
+  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.
+
+## Check
+
+```bash
+pnpm validate
+pnpm typecheck
+pnpm dev
+```
+
+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/docs/skills/update/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: update
+description: Review and upgrade Mantle SDK dependencies and project-local skills while preserving application source, provider identities and plugin lockfiles.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/update/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Update
+
+Upgrade SDK dependencies deliberately; never overwrite application-owned code.
+The old Starter bundle comparison command `mantle update` is removed. This
+skill remains the version-matched upgrade workflow, not a replacement CLI.
+
+1. Inspect git status, package.json, lockfile, actual project scripts and
+   installed versions. Preserve unrelated local changes. Read plugin locks
+   and legacy `.mantle` metadata if present; they are context, not required.
+2. Select an explicit target release and read that version's GitHub release
+   notes. Installed docs live under `node_modules/@aotter/mantle/docs/`;
+   `handbook/releases/index.md` is a stable-release index, so a prerelease
+   need not appear there. Do not use the old package's docs as the new API contract.
+   Do not resolve new Starter refs or compare the project to a baseline
+   template.
+3. Update only selected `@aotter/mantle*` dependencies to the same exact target
+   version, preserving dependency sections. Use the package manager to update
+   the lockfile; inspect the dependency diff and required peer changes.
+4. Remove scripts that invoke retired create/bundle-update commands. Keep all
+   application manifests, handlers, routes, theme, Worker/D1/KV names, origins,
+   provider bindings, secrets, and legacy metadata. Apply API migration edits
+   individually; do not copy the reference consumer over a real application.
+5. Use the upgraded package to regenerate machine-owned bindings and project
+   its skills, then run the application's validation, types and tests:
+
+```sh
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+pnpm exec mantle skills
+pnpm exec mantle skills --check
+pnpm exec mantle validate
+```
+
+Read the refreshed `mantle-develop` skill and the upgraded package's embedded
+docs before continuing application edits.
+
+Start the local application and test its actual routes, including configured
+auth behavior. Review the final source/lockfile/generated diff; unexpected
+provider or user-source changes block completion. Provider credentials must
+never enter git or logs. Report exact old/new versions, checks, and remaining
+migration work. A dependency update does not authorize a production deploy.

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

@@ -6,7 +6,7 @@ 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.3-alpha.6`. Pin the package, record the tested version, and
+This recipe targets `0.1.4`. Pin the package, record the tested version, and
 rerun compatibility checks when upgrading.
 
 ## What stays with the host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.3-alpha.6",
+  "version": "0.1.4",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Auth, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -83,8 +83,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.3-alpha.6",
-    "@aotter/mantle-spec": "0.1.3-alpha.6"
+    "@aotter/mantle-runtime": "0.1.4",
+    "@aotter/mantle-spec": "0.1.4"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -92,13 +92,13 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.3-alpha.6",
-    "@aotter/mantle-auth": "0.1.3-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.6",
-    "@aotter/mantle-bun": "0.1.3-alpha.6",
-    "@aotter/mantle-vercel": "0.1.3-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.6",
-    "@aotter/mantle-web": "0.1.3-alpha.6"
+    "@aotter/mantle-admin-ui": "0.1.4",
+    "@aotter/mantle-auth": "0.1.4",
+    "@aotter/mantle-vercel": "0.1.4",
+    "@aotter/mantle-bun": "0.1.4",
+    "@aotter/mantle-web": "0.1.4",
+    "@aotter/mantle-cloudflare": "0.1.4",
+    "@aotter/mantle-admin": "0.1.4"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -139,18 +139,18 @@
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
     "better-auth": "1.7.2",
-    "hono": "^4.13.3",
+    "hono": "^4.13.7",
     "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.3-alpha.6",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.6",
-    "@aotter/mantle-auth": "0.1.3-alpha.6",
-    "@aotter/mantle-bun": "0.1.3-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.6",
-    "@aotter/mantle-web": "0.1.3-alpha.6",
-    "@aotter/mantle-vercel": "0.1.3-alpha.6"
+    "@aotter/mantle-admin": "0.1.4",
+    "@aotter/mantle-admin-ui": "0.1.4",
+    "@aotter/mantle-auth": "0.1.4",
+    "@aotter/mantle-bun": "0.1.4",
+    "@aotter/mantle-cloudflare": "0.1.4",
+    "@aotter/mantle-vercel": "0.1.4",
+    "@aotter/mantle-web": "0.1.4"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -4,13 +4,13 @@ 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 applications and adapters. |
-| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
-| [`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 author a local Mantle application or continue an existing project. |
-| [`provision`](provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
+| [`develop`](../docs/skills/develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
+| [`media-gc`](../docs/skills/media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
+| [`plugin`](../docs/skills/plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
+| [`theme`](../docs/skills/theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
+| [`update`](../docs/skills/update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
+| [`mantle`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
+| [`provision`](../docs/skills/provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
 
 The skills target Mantle's v0.1 grammar. The installed package version, not
 duplicated skill prose, selects the exact runtime and embedded docs.
@@ -25,13 +25,13 @@ 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 project | repo-owned theme and UI contracts | — | project, plugin | — |
-| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project, plugin | — |
-| `install` | new application, or opening an existing project | 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. |
+| `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` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project | — |
+| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project | — |
+| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project | — |
+| `mantle` | new application, or opening an existing project | 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 | package | 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 | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
 
 Deliberately monolithic:
 
@@ -47,7 +47,8 @@ Deliberately monolithic:
 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 consumer project, and a skill that
-withholds `project` must say why. `scripts/check-skills.mjs` holds that
+withholds `project` must say why. `plugin` is the bootstrap skill and `package`
+is an opt-in brief in the installed SDK. `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;
@@ -58,11 +59,15 @@ contracts.
 
 ## Source-repository marketplace install
 
-Cold start is the install skill. Other marketplace hosts are pointers
-to the same entry:
+`skills/install/SKILL.md` declares `name: mantle`. It is the only repository
+skill discovered by the no-flag command and copied as a small directory.
+The other six skills live in `docs/skills/` and ship with the npm package.
+`mantle skills` projects the four ongoing workflows after package installation.
+
+Other marketplace hosts point to the same entry:
 
 ```sh
-npx skills add aotter/mantle --skill install
+npx skills add aotter/mantle
 ```
 
 ```bash
@@ -75,7 +80,11 @@ codex plugin marketplace add aotter/mantle
 codex plugin add mantle@mantle
 ```
 
-Then follow the install skill to the CLI and handbook. After packages are
+Read the path printed by the installer (for project-local Codex,
+`.agents/skills/mantle/SKILL.md`). Only the selected brief is installed, not
+the SDK or handbook. After choosing and installing an exact SDK version, read
+`node_modules/@aotter/mantle/skills/install/SKILL.md` and its embedded docs;
+that package supersedes the bootstrap Git-ref instructions. After packages are
 installed, `mantle skills` projects the installed package's own skills into the
 project, and `mantle skills --check` fails on drift.
 
@@ -96,13 +105,13 @@ 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", "develop my Mantle site", "deploy"). Official cold start is `npx skills add aotter/mantle --skill install`. Point the agent at the repository or pass the version-matched 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"). Official cold start is `npx skills add aotter/mantle`. Point the agent at the repository or pass the version-matched markdown content directly.
 
 ## Conventions
 
 Each SKILL.md ships:
 
-- **Front-matter** with a folder-matching `name`, trigger-complete
+- **Front-matter** with a stable `name`, trigger-complete
   `description`, and optional source/version `metadata`. Plugin hosts add the
   external `mantle:` namespace.
 - **Preflight** section — environment + user-confirmation gates.

package/skills/develop/SKILL.md

@@ -3,9 +3,9 @@ name: develop
 description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/develop/SKILL.md
+  sourcePath: docs/skills/develop/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Develop
@@ -17,8 +17,9 @@ docs govern runtime/API behavior.
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
-2. `manifests/site.yaml`, the active adapter config (`wrangler.jsonc`), and
-   the Worker entry. Custom Auth lives in that entry's `createAuth` factory.
+2. The manifest directory selected by the project scripts, the actual host
+   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
+   Read custom Auth construction there when present.
 3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
    and `.mantle/recipes/`. Legacy launch/handoff files are context only.
 4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
@@ -75,6 +76,22 @@ 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.
 
+## Choose the manifest feature first
+
+Read installed `docs/handbook/reference/features.md` to map the requested
+behavior to fields before adding handlers or a custom UI. For host-only reads,
+`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
+`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
+View params/results, indexed entry reads, and their authorization boundary.
+Use `from` for portable typed projections; SQL is for queries needing native
+SQLite and produces `unknown` row types.
+
+For Admin labels, inputs, collection columns/tabs, reports or action buttons,
+read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
+metadata and `uiSchema` before custom frontend code. These control the Admin
+console, not the visitor frontend. Regenerate and verify the actual console;
+never edit generated `public/_mantle/admin/` assets.
+
 ## Content Edits
 
 - Follow the actual frontend content source. Use Admin or Staff MCP for

package/skills/install/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: install
+name: mantle
 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"
@@ -9,12 +9,37 @@ metadata:
   projectionReason: Creates a new project; nothing to project into an existing one.
 ---
 
-# Mantle Install
+# Mantle
 
 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.
+A same-version `mantle-starters` tag is not required; do not wait for one.
+
+## Locate the version-matched instructions
+
+`npx skills add aotter/mantle` installs this brief, not the SDK,
+a project, or the handbook. Read the path printed by the installer (Codex's
+project-local path is `.agents/skills/mantle/SKILL.md`); `metadata.sourcePath`
+is repository provenance, not a consumer path. A repository install follows
+the selected Git ref and does not pin an npm release.
+
+After selecting the host and exact version, install `@aotter/mantle` locally
+with the selected optional packages. All `docs/...` paths below then mean
+`node_modules/@aotter/mantle/docs/...`; package skills are under
+`node_modules/@aotter/mantle/skills/`. Read that package's
+`skills/install/SKILL.md` before authoring: it supersedes this bootstrap copy.
+Use the new application's installation, never another project's `node_modules`
+or an SDK checkout packing harness, to resolve these paths.
+Before reading a handbook page, verify the version in that application's
+`node_modules/@aotter/mantle/package.json` against its lockfile and confirm
+the page exists under the same package directory. If the package is missing or
+the versions differ, fix the installation first; do not substitute a nearby
+checkout's docs or another project's `node_modules`.
+If the user requested a prerelease, resolve that channel explicitly; `latest`
+need not contain prerelease features. Never mix versioned npm code with branch
+docs. No local CLI exists until the package is installed.
 
 ## New application
 
@@ -23,15 +48,16 @@ turn `generate` into implicit scaffolding.
    Do not assume Cloudflare, public HTML or Admin is required. Check Node 22+
    and pnpm 9+ for these SDK examples. A ChatGPT Site is not a conventional
    Cloudflare Worker deployment; use the installed
-   `docs/handbook/sites/index.md` integration guide and
+   `docs/handbook/chatgpt-sites/index.md` integration guide and
    `docs/examples/host-chatgpt-sites/` runnable reference when selected.
 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. Interview the human for host and required surfaces. Do not assume Admin,
-   public HTML or Cloudflare. Scale:
+3. Use the host and surfaces already established in step 1; ask only for
+   information still missing. Read `docs/handbook/start/overview.md` and
+   `docs/handbook/reference/features.md`, then select the matching path:
    - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
    - Adapter without Admin — `docs/examples/host-minimal-worker/`.
    - Opt-in Admin / Dev UI — only when a human needs a console: interview
@@ -42,7 +68,8 @@ turn `generate` into implicit scaffolding.
      `createAuth` email-otp + `ConsoleEmailSender`. Do not Vite-build Admin.
    - ChatGPT Sites with Admin/D1/R2 — follow
      `docs/examples/host-chatgpt-sites/`, not the email-OTP Worker example.
-     Copy it outside the SDK checkout, then `npm ci`,
+     Copy it outside the SDK checkout, pin its `@aotter/mantle*` dependencies
+     to the selected exact version, then `npm install`,
      `npx mantle validate --phase deploy`, `npm run generate`, `npm run check`,
      `npx wrangler d1 migrations apply DB --local`,
      `npm run dev -- --port 4174`, and `npm test` in a second terminal.
@@ -51,12 +78,15 @@ turn `generate` into implicit scaffolding.
      and the local/production smoke gates. Sites provisions and deploys; never
      `wrangler deploy` a Site. Request both D1 and R2 when uploads are in scope.
      Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not enable remote staff OAuth MCP.
+     At handoff, show the owner where Admin WebMCP and the public/staff MCP
+     endpoints appear, and state which are usable from the browser versus a
+     remote connector.
    - ChatGPT Sites with custom business rules or an external callback — the
      runnable reference covers builtin content only. For application-owned
      operational state, `handler: { kind: ref }` Procedures, staff-only SQL
      Views, staff MCP Triggers with `requires.auth`, and outbound webhooks
      called from handler code, follow
-     `docs/handbook/sites/equipment-checkout.md`. It is an implementation
+     `docs/handbook/chatgpt-sites/equipment-checkout.md`. It is an implementation
      guide, not a shipped app: keep Mantle-owned Schema tables and
      application-owned tables separate, and give every application table a
      reviewed migration.
@@ -108,7 +138,9 @@ a bundle comparison command.
 
 ## Ship and report
 
-When deployment is requested, follow the installed provision skill and the
+When deployment is requested, read
+`node_modules/@aotter/mantle/skills/provision/SKILL.md` (not projected by
+`mantle skills`) and follow that version-matched skill and the
 observed host configuration. Legacy Landing remains a pre-stable product; it
 is not a launch dependency for new Core projects.
 

package/skills/media-gc/SKILL.md

@@ -3,9 +3,9 @@ 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
+  sourcePath: docs/skills/media-gc/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: plugin
+  projection: package
   projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
 ---
 

package/skills/plugin/SKILL.md

@@ -3,9 +3,9 @@ name: plugin
 description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/plugin/SKILL.md
+  sourcePath: docs/skills/plugin/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Plugin
@@ -50,11 +50,17 @@ stop and ask for the recipe instead of guessing.
 ## First Read
 
 1. `package.json` for Mantle version and adapter package.
-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`.
+2. The manifest directory selected by project scripts for current atom names
+   and route/tool collisions.
+3. The actual host entry and its handler, template and port registrations;
+   `src/mantle/config.ts` and `src/mantle/handlers/` are conventions, not required paths.
 4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
 5. `.mantle/launch-state.json` only as context, not as plugin authority.
 
+Read version-matched contracts under `node_modules/@aotter/mantle/docs/`,
+starting with `handbook/reference/features.md`. Plugin recipes cannot override
+the installed grammar.
+
 ## Plan First
 
 Before applying any plugin, produce a plan:
@@ -100,14 +106,20 @@ and report the dependency instead of deleting through it.
 
 ## Verify
 
+Use the project's validation and typecheck scripts when present. Regenerate
+the plan after manifest changes before probing the running host:
+
 ```bash
-pnpm validate
-pnpm typecheck
+pnpm exec mantle validate
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+# Run the project's TypeScript check and restart its local server.
 ```
 
 Then verify the plugin's declared surfaces:
 
-- `GET /api/views/<name>` for View reads;
+- public Views via `GET /api/views/<name>`, staff Views via authenticated
+  Admin/staff MCP, and internal Views through the host binding;
 - HTTP Trigger path for public writes;
 - Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
 - adapter resource presence when the plugin requires optional ports.

package/skills/provision/SKILL.md

@@ -3,9 +3,9 @@ name: provision
 description: Ship a Mantle project through its selected host, routing ChatGPT Sites to its integration guide and conventional Cloudflare Workers to production auth and provisioning.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/provision/SKILL.md
+  sourcePath: docs/skills/provision/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: plugin
+  projection: package
   projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
 ---
 
@@ -16,7 +16,7 @@ user asks to create remote resources or ship production. This flow is for
 consumer-owned Cloudflare Workers. New direct-authored apps do not need Landing
 artifacts (`.mantle/launch-state.json`, `.mantle/handoff.md`, or a hosted-auth
 allocation). Treat any Landing handoff as **legacy/optional**. For a ChatGPT
-Site, use the installed `docs/handbook/sites/index.md` integration guide and
+Site, use the installed `docs/handbook/chatgpt-sites/index.md` integration guide and
 the "Publish with Sites" steps in `docs/examples/host-chatgpt-sites/README.md`:
 request D1 and R2 on the Site, set `PUBLIC_ORIGIN` and `OWNER_EMAIL` in Sites
 settings, review the migration, then save and deploy a Sites version. Do not

package/skills/theme/SKILL.md

@@ -3,9 +3,9 @@ name: theme
 description: Apply brand and visual direction in a Mantle application using its repo-owned theme and UI contracts.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/theme/SKILL.md
+  sourcePath: docs/skills/theme/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Theme
@@ -13,13 +13,20 @@ metadata:
 Theme work is project-owned source editing. Use the actual frontend and its
 tokens/recipes; Core does not install a default home page or UI tree.
 
+For requests to change the Admin console, first read installed
+`node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md` and use the
+develop skill. Labels, widgets, list columns, filters and actions may already
+be manifest-driven. Visitor CSS does not style the prebuilt Admin SPA, and
+`uiSchema` does not accept arbitrary CSS, components or layout keys.
+
 ## First Read
 
 1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
 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/site.yaml` to understand which content shape drives the public UI.
+4. The manifest directory selected by project scripts to understand which
+   content shape drives the public UI.
 
 ## Ownership
 

package/skills/update/SKILL.md

@@ -3,9 +3,9 @@ name: update
 description: Review and upgrade Mantle SDK dependencies and project-local skills while preserving application source, provider identities and plugin lockfiles.
 metadata:
   source: "@aotter/mantle"
-  sourcePath: skills/update/SKILL.md
+  sourcePath: docs/skills/update/SKILL.md
   applies_to: mantle grammar v0.1
-  projection: project, plugin
+  projection: project
 ---
 
 # Mantle Update
@@ -17,8 +17,10 @@ skill remains the version-matched upgrade workflow, not a replacement CLI.
 1. Inspect git status, package.json, lockfile, actual project scripts and
    installed versions. Preserve unrelated local changes. Read plugin locks
    and legacy `.mantle` metadata if present; they are context, not required.
-2. Select an explicit target release and read its entry in
-   `docs/handbook/releases/index.md` plus that version's GitHub release notes.
+2. Select an explicit target release and read that version's GitHub release
+   notes. Installed docs live under `node_modules/@aotter/mantle/docs/`;
+   `handbook/releases/index.md` is a stable-release index, so a prerelease
+   need not appear there. Do not use the old package's docs as the new API contract.
    Do not resolve new Starter refs or compare the project to a baseline
    template.
 3. Update only selected `@aotter/mantle*` dependencies to the same exact target
@@ -39,6 +41,9 @@ pnpm exec mantle skills --check
 pnpm exec mantle validate
 ```
 
+Read the refreshed `mantle-develop` skill and the upgraded package's embedded
+docs before continuing application edits.
+
 Start the local application and test its actual routes, including configured
 auth behavior. Review the final source/lockfile/generated diff; unexpected
 provider or user-source changes block completion. Provider credentials must