@aotter/mantle 0.1.3 → 0.1.4

package/docs/skills/plugin/SKILL.md

@@ -0,0 +1,132 @@
+---
+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: docs/skills/plugin/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Plugin
+
+Mantle plugins are Core SDK capability packages. They are not application
+scaffolds (retired in ADR-0021) and they are not provider provisioning scripts.
+
+A plugin may contribute:
+
+- manifests: `Schema`, `View`, `Procedure`, `Trigger`;
+- handler source or handler registration notes;
+- site defaults or media policy additions;
+- expected HTTP, admin, and MCP surfaces;
+- adapter capability requirements and provider setup notes.
+
+## User Install Entry
+
+The user-facing install path is:
+
+```txt
+Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
+Use repo-local mantle:plugin to update <plugin id> in this repo.
+Use repo-local mantle:plugin to remove <plugin id> from this repo.
+```
+
+There is no `mantle plugin add` CLI yet. Do not invent one. Install from a
+marketplace entry, plugin package, or recipe URL that declares enough data for
+an agent to apply the capability deterministically.
+
+A valid marketplace entry must include:
+
+- plugin id, title, source, and version;
+- supported Mantle version range;
+- files, manifests, handlers, routes, MCP tools, and admin surfaces it adds;
+- adapter capabilities and provider resources it requires;
+- required env vars and secrets, without secret values;
+- verification commands and expected surfaces.
+
+If the marketplace page is only marketing copy or lacks an install recipe,
+stop and ask for the recipe instead of guessing.
+
+## First Read
+
+1. `package.json` for Mantle version and adapter package.
+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:
+
+- files to add or change;
+- atoms to add and their names;
+- HTTP routes and MCP tools that will appear;
+- required runtime ports;
+- adapter-specific resources, env vars, and secrets;
+- checks to run.
+
+If the plugin needs a capability the current adapter does not expose, stop
+with the missing capability instead of inventing provider steps.
+
+## Apply
+
+Apply the smallest deterministic diff. Do not run arbitrary install scripts
+from a plugin package. Copy declared files, wire declared handlers, update the
+plugin ledger, then validate.
+
+Suggested ledger paths:
+
+```txt
+.mantle/plugins.json
+.mantle/plugins.lock.json
+```
+
+Keep optional legacy launch files such as `.mantle/features.json` separate from
+plugin state. They are not the Core plugin ledger.
+
+## Update
+
+Compare the installed lock entry against the marketplace entry or recipe URL.
+Apply only the declared version diff, update `.mantle/plugins.lock.json`, then
+run the same verification checks.
+
+## Remove
+
+Use the lock entry as the removal manifest. Delete only files and atoms owned
+by that plugin, unwind handler registrations it added, remove its ledger entry,
+then validate. If another plugin or local code depends on a removed atom, stop
+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 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:
+
+- 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.
+
+## Don't
+
+- Don't treat an application template as a plugin.
+- Don't assume Cloudflare; inspect the active adapter and capability ports.
+- Don't create a second skill namespace for host-specific plugins.
+- Don't commit secrets. Provider secrets stay in the platform secret store.

package/docs/skills/provision/SKILL.md

@@ -0,0 +1,194 @@
+---
+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: docs/skills/provision/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: package
+  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
+---
+
+# Provision a Mantle Project
+
+Local cold start deliberately stops before this skill. Provision only after the
+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/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
+run `wrangler deploy` or require R2 S3 credentials merely because Sites exposes
+an R2 binding.
+
+## Source of Truth
+
+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; they are optional leftovers from
+   Landing and must not be created as prerequisites for a new app.
+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
+   and Cloudflare accounts before changing them.
+
+Run the local gate first:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm typecheck
+git status --short
+```
+
+## Resume From Observed State
+
+Do not branch on how the project was created. Verify these facts and skip
+completed work:
+
+1. `git remote get-url origin` confirms the GitHub repo.
+2. An HTTPS `PUBLIC_ORIGIN` that responds confirms the Cloudflare deploy.
+3. `/admin/sign-in` returning `503 setup_incomplete` means auth is not bound.
+   Use the recorded auth intent only to choose hosted or self-hosted setup;
+   live behavior is authoritative.
+
+If there is no remote, confirm the target account, create a private repo,
+commit, and push `main`. If there is no live Worker, confirm the Cloudflare
+account, prefer an available connector, or use `pnpm exec wrangler login` with
+the user's agreement, then run `pnpm deploy`.
+
+Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
+commit and push non-secret changes. Reuse any repo or Worker already created.
+Do not recreate Landing artifacts for a new direct-authored app. Workers Builds
+is optional after a direct deploy.
+
+When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
+provider's OAuth callback together, then redeploy. Do not patch `site_config`
+directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
+
+## Choose Auth
+
+- **Self-hosted email OTP:** use the application's production transactional-email sender. Replace `ConsoleEmailSender`; never deploy it.
+- **Self-hosted GitHub OAuth — free fallback:** use when the application has no email provider. Configure the owner's per-site GitHub OAuth App and Worker secrets using the steps below.
+- **Mantle hosted auth — paid, legacy/optional:** use only when a **legacy
+  Landing handoff** already records a hosted allocation and client
+  configuration. New direct-authored apps do not get this from Core. Mantle
+  Platform operates the identity provider; do not ask the user for a per-site
+  GitHub OAuth App.
+
+Configure only the selected mode. Core deliberately rejects partial or mixed
+hosted/self-managed bindings with `503 setup_incomplete`.
+
+Do not claim that hosted auth can attach to an arbitrary local repo unless a
+legacy Landing handoff already supplies that configuration.
+
+For the exact boundary, read
+`node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
+
+## Self-hosted email OTP
+
+Keep the application's custom `createAuth()` factory, replace
+`ConsoleEmailSender` with its production `EmailSender`, and retain
+`bootstrapOwner: { match: "email", value: <owner email> }`. Store sender
+credentials and `BETTER_AUTH_SECRET` as Worker secrets, put `PUBLIC_ORIGIN` in
+non-secret vars, deploy, then verify that the owner receives an OTP at
+`/admin/sign-in`. If there is no production email provider, use GitHub OAuth
+below instead of deploying console delivery.
+
+## Self-hosted GitHub OAuth
+
+1. Ask the user to create a GitHub OAuth App:
+
+- Homepage URL: `<worker-url>`
+- Authorization callback URL: `<worker-url>/api/auth/callback/github`
+- Device Flow: unchecked
+
+2. Put non-secret values in `wrangler.toml`:
+
+- `MANTLE_AUTH_MODE = "self-managed"`
+- `PUBLIC_ORIGIN`
+- `GITHUB_CLIENT_ID`
+- `ADMIN_GITHUB_LOGIN`
+- correct Worker `name`
+
+Remove `MANTLE_HOSTED_AUTH_ISSUER` and `MANTLE_HOSTED_AUTH_CLIENT_ID` if they
+were present for a hosted allocation.
+
+3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
+   secrets; otherwise use hidden shell input:
+
+```bash
+read -rsp "GitHub OAuth client secret: " MANTLE_GITHUB_CLIENT_SECRET && printf "\n"
+printf '%s' "$MANTLE_GITHUB_CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
+openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
+unset MANTLE_GITHUB_CLIENT_SECRET
+```
+
+Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
+sessions.
+
+4. Commit and push only non-secret config, then redeploy:
+
+```bash
+git add wrangler.toml AGENTS.md
+git commit -m "mantle: wire production auth"
+git push
+pnpm deploy
+```
+
+## Hosted Auth (legacy Landing)
+
+Skip this section unless a legacy Landing handoff is already present. New
+direct-authored apps use self-hosted email OTP or GitHub OAuth above.
+
+Follow that handoff and its client configuration. Hosted configuration remains
+in landing-managed Cloudflare Worker bindings. Verify:
+
+- `MANTLE_AUTH_MODE = "hosted"`;
+- `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;
+- `MANTLE_HOSTED_AUTH_CLIENT_ID` is the same-origin `/clients/<id>` URL;
+- `PUBLIC_ORIGIN` and `ADMIN_GITHUB_LOGIN` are set;
+- `BETTER_AUTH_SECRET` exists as a Worker secret;
+- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are absent.
+
+Hosted clients use PKCE and have no client secret. Do not write secrets into
+`wrangler.toml`.
+
+Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
+authenticates, then skip the self-hosted flow.
+
+## Smoke Test
+
+- public home route;
+- `/admin/sign-in`;
+- selected admin sign-in path;
+- `/mcp/staff` with an agent client when available;
+- one type-specific core workflow.
+
+Media uploads are optional. Configure R2 only when the owner asks for
+staff-managed files; then read
+`node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md`.
+
+## Handoff
+
+Return:
+
+- public URL;
+- admin sign-in URL;
+- Staff MCP URL;
+- operator setup URL:
+  `https://mantle.tools/connect?site=<url-encoded-worker-url>`;
+- remote resources created or reused;
+- auth mode and any intentionally deferred setup.
+
+## Don't
+
+- Don't create remote resources before the user asks to ship.
+- Don't ask for a Cloudflare API token in the base flow.
+- Don't commit provider secrets.
+- Don't require R2 for first production.
+- Don't invent a second provision orchestrator.
+- Don't use `/admin/auth/github/callback`; the callback is
+  `/api/auth/callback/github`.

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`. 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",
+  "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",
-    "@aotter/mantle-spec": "0.1.3"
+    "@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",
-    "@aotter/mantle-admin-ui": "0.1.3",
-    "@aotter/mantle-bun": "0.1.3",
-    "@aotter/mantle-auth": "0.1.3",
-    "@aotter/mantle-web": "0.1.3",
-    "@aotter/mantle-cloudflare": "0.1.3",
-    "@aotter/mantle-vercel": "0.1.3"
+    "@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-ui": "0.1.3",
-    "@aotter/mantle-admin": "0.1.3",
-    "@aotter/mantle-auth": "0.1.3",
-    "@aotter/mantle-bun": "0.1.3",
-    "@aotter/mantle-cloudflare": "0.1.3",
-    "@aotter/mantle-vercel": "0.1.3",
-    "@aotter/mantle-web": "0.1.3"
+    "@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
@@ -76,7 +81,7 @@ codex plugin add mantle@mantle
 ```
 
 Read the path printed by the installer (for project-local Codex,
-`.agents/skills/install/SKILL.md`). Only the selected brief is installed, not
+`.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
@@ -100,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