@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/docs/release-process.md

@@ -1,244 +0,0 @@
-# Release process
-
-How a version reaches npm. What each shipped stable contains is
-[Releases](handbook/releases/index.md); this document is the procedure only.
-A release has no Starter/Landing checkout, tag, dispatch, credential or
-deployment dependency.
-
-## Authority and state transitions
-
-`.github/workflows/release.yml` is the only release controller. Humans merge
-a reviewed same-repository release PR, then explicitly dispatch that merge.
-No task implicitly authorizes publication; no manual package/tag writer exists.
-
-| State | Sole next writer | Retry / invariant |
-|---|---|---|
-| Reviewed source; unused version | Core source/packed-consumer gates, then immutable Core tag | Exact canonical merged PR SHA and version required |
-| Tag exists; registry candidates partial | Existing npm/GPR publication steps | Verify existing artifact identity; publish missing versions only |
-| Tag exists and all eleven npmjs packages already exist | Metadata verify, then channel promote and the GitHub release | Skip pack and immutable tarball compare. The controller tip must not rebuild published artifact identity. npm integrity metadata still has to be `sha512`. The public-registry Worker gate stays skipped |
-| Tag exists on an ancestor of the dispatched tip; tip package versions still match | Resolve binds release identity to the tag SHA; later steps stay the existing writers | Controller-only recovery. Do not retag. The canonical merged-PR check uses the tag SHA. Fail when the tip version differs or the tag commit is not an ancestor |
-| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels and `mantle-release` unchanged |
-| Consumer passes | That registry's promote step: monotonic channel add for every package | Same version is a no-op; older runs cannot move a channel backward. Public channels are only `alpha`, `beta`, `rc`, and `latest`. `mantle-release` is never removed |
-| Channels promoted or preserved | GitHub release step | Existing release identity or fail. Leftover `mantle-release` pointing at the last published candidate is expected |
-
-The public-registry gate uses a disposable copy of the directly authored
-`docs/examples/host-minimal-worker` reference, installs the exact candidate, then
-checks generation, skill projection, TypeScript and real Worker HTTP behavior.
-The same reference is gated against exact tarballs before Core tagging. It is
-a test/example, not a scaffold product or another repository release.
-
-## Changing release automation
-
-Before editing a release workflow, put a finite state table plus its
-invariants and non-goals in a Draft PR. Name the single mutation boundary for
-each external resource; recovery must return through that boundary rather than
-introduce a second writer.
-
-Freeze one commit SHA for review. Every finding must name the affected state
-row, a concrete event interleaving, and the wrong mutation it permits. A clean
-verdict expires when that SHA changes. After two patch rounds, a new
-foundational blocker returns to the state table and the user for a scope
-decision instead of starting another local redesign loop.
-
-Invariants: immutable versions/tags retain their identity; registry integrity
-and the published-consumer gate precede public channel promotion; retries
-cannot move channels backward. No downstream mutation, unpublish, dist-tag
-removal, or rollback is introduced. The runnable release-order check guards
-these transitions.
-
-Mutation boundaries during a release: `Publish to npmjs` and `Mirror to
-GitHub Packages` attach the internal candidate dist-tag `mantle-release`
-while publishing a version. `Promote npmjs channel tags` is the only
-release step that moves npmjs public channels. `Promote GitHub Packages
-channel tags` is the only release step that moves GitHub Packages public
-channels. Neither step removes `mantle-release`. Recovery of a partial
-release reruns that same controller and version.
-
-`mantle-release` is not a public channel. It stays forever as an internal
-candidate tag pointing at the last published candidate. Official channels
-are only `alpha`, `beta`, `rc`, and `latest`. Consumers must not install
-`mantle-release`. Deleting it after promotion is not part of the release:
-dist-tag DELETE only added failure and re-run state, and Actions
-`NPM_TOKEN` 403s on that DELETE.
-
-## Branches and channels
-
-| Version | Source branch | npm dist-tag | GitHub release |
-|---|---|---|---|
-| `X.Y.Z-alpha.N` | `develop` | `alpha` | prerelease |
-| `X.Y.Z-beta.N` | `main` | `beta` | prerelease |
-| `X.Y.Z-rc.N` | `main` | `rc` | prerelease |
-| `X.Y.Z` | `main` | `latest` | release |
-
-- The controller derives the source branch from the version: `-alpha` means
-  `develop`, anything else means `main`. An untagged dispatch must be that
-  branch's tip and the merge commit of exactly one PR into that branch.
-  When the version tag already exists on an ancestor of the tip, Resolve
-  recovers from that tag SHA; see Recovery.
-  `scripts/release-tag-order.mjs` rejects any other prerelease identifier.
-- `develop` is where every change integrates first, so it is the base for all
-  work despite `main` being the repository's default branch on GitHub. `main`
-  changes only through promotion PRs and hotfix PRs (below); it is never pushed
-  directly, rebased or force-updated. Both branches share one ruleset: PR, one
-  approval, resolved threads and a current-base `Typecheck + tests` check.
-- Stable is the only release that moves `latest`. A prerelease channel keeps
-  its last version when a later stable publishes.
-- Publish uses `--tag mantle-release`. `mantle-release` is an internal
-  candidate dist-tag, not a public channel. Consumers must not install it.
-  Official channels are only `alpha`, `beta`, `rc`, and `latest`.
-  Publication does not move those channels. After the public-registry
-  consumer gate, each registry's promote step moves every package's real
-  channel and leaves `mantle-release` pointing at the last published
-  candidate.
-
-## Prepare and run
-
-1. Fetch Core refs, prove the version and tag unused. Preview GitHub generated
-   notes since the previous tag; correct PR metadata and label release-only
-   PRs skip-release-notes. Do not duplicate release entries in CHANGELOG.md.
-2. Align every workspace package, plugin and marketplace ref to the version.
-   The controller checks package.json files and plugin manifests only; docs
-   pins and the admin-ui registry dependency are hand-edited, so grep for the
-   old version until only lockfiles and registry-pinned examples remain:
-
-   ```sh
-   OLD=<previous version> NEW=<version>
-   git grep -l "\"version\": \"$OLD\"" -- '*.json' ':!**/package-lock.json' \
-     | xargs perl -pi -e "s/\"version\": \"\Q$OLD\E\"/\"version\": \"$NEW\"/"
-   node scripts/sync-plugin-manifests.mjs
-   git grep -n "$OLD" -- ':!pnpm-lock.yaml' ':!**/package-lock.json'
-   ```
-
-   Leave the consumer cold-start entry **untagged**: `npx skills add
-   aotter/mantle`, `/plugin marketplace add aotter/mantle`,
-   `codex plugin marketplace add aotter/mantle` and the plugin-manifest
-   descriptions carry no `@v…` / `--ref`. Untagged resolves to `main`, which
-   normally moves at a release but may contain a source-only hotfix; the
-   installed npm package remains the version authority
-   (#995, #998). Only "installed version" statements such as
-   `(currently \`X.Y.Z\`)` are bumped.
-
-3. Review API compatibility and migration instructions for actual consumers.
-   Frozen legacy consumers stay on their pinned version; do not make them
-   follow new Core.
-4. Run `pnpm check`, including exact packed Worker, optional products, Bun,
-   Vercel, skills, release invariants, types and tests. Inspect the umbrella
-   docs/skills payload: no workspace dependencies, secrets or local state.
-5. Freeze the PR head for self review; CI must pass before merge. Merge into
-   `develop` with a merge commit for every version. For an alpha, dispatch
-   release.yml from that merge with `version` (without v). For beta, RC and
-   stable, continue with the promotion below. The controller refuses an
-   untagged source that is no longer the expected branch tip.
-
-The eleven public packages remain in dependency order:
-
-1. @aotter/mantle-spec
-2. @aotter/mantle-admin-ui
-3. @aotter/mantle-runtime
-4. @aotter/mantle-indexeddb
-5. @aotter/mantle-web
-6. @aotter/mantle-admin
-7. @aotter/mantle-auth
-8. @aotter/mantle-bun
-9. @aotter/mantle-vercel
-10. @aotter/mantle-cloudflare
-11. @aotter/mantle
-
-## Promote to main (beta, RC, stable)
-
-Every non-alpha release is the version PR above, one promotion PR and one
-dispatch. The version PR still merges into `develop`, so `develop` always
-contains what `main` publishes and promotions never conflict.
-
-1. Stable only: the version's release-gate issue records owner acceptance.
-   Every gate item passes with linked evidence or is explicitly deferred
-   there, and no `release-gate` issue stays open against the version.
-   Beta and RC need the gate defined, not passed.
-2. Merge the version PR into `develop` with a merge commit; note its SHA.
-3. Pin the promotion head at that SHA so later `develop` merges cannot ride
-   along, then open the promotion PR against `main`:
-
-   ```sh
-   git fetch origin
-   git push origin <develop merge SHA>:refs/heads/promote/<version>
-   gh pr create --base main --head promote/<version> \
-     --title "release: promote <version> to main" --label skip-release-notes
-   ```
-
-   The body names the version PR, the pinned SHA and the gate evidence. The
-   usual review and checks apply. An organization-admin bypass merge must be
-   recorded on the PR (see CONTRIBUTING).
-4. Merge with a merge commit, never rebase: the controller needs `main`'s tip
-   to be the PR's merge commit. `main`'s tree now equals the pinned commit.
-5. Dispatch from `main` and watch every gate exactly as for an alpha:
-
-   ```sh
-   gh workflow run release.yml --ref main -f version=<version>
-   ```
-
-6. RC to stable repeats 2–5 with the next version. `rc` keeps pointing at
-   the last RC; stable moves only `latest`.
-
-Hotfix on `main` is for a published non-alpha version that cannot wait for
-the next promotion. Branch from `main`, include the version bump, PR into
-`main`, dispatch as in step 5, then immediately PR `main` back into `develop`
-and resolve version files in favour of `develop`. Until that lands, the next
-promotion conflicts on the version files.
-
-GitHub generates notes from the immediately previous tag, which for a stable
-is usually its own last RC. To cover the whole line instead, regenerate from
-the previous stable and edit the release body after the run. The body is not
-an immutable artifact; the tag and packages are.
-
-```sh
-gh api repos/aotter/mantle/releases/generate-notes \
-  -f tag_name=v<version> -f previous_tag_name=v<previous stable> --jq .body > notes.md
-gh release edit v<version> --notes-file notes.md
-```
-
-Add the version's entry to [Releases](handbook/releases/index.md) in the same
-pass, so the handbook and the GitHub release describe the same thing.
-
-After publication, move docs/examples that were pinned to a packed checkout
-back to registry installation with an updated lockfile, and close the gate
-issue with the run link and completion evidence.
-
-## Credentials and verification
-
-Core needs NPM_TOKEN for npmjs. Its job-scoped GITHUB_TOKEN creates the Core
-tag/release and mirrors GitHub Packages. No cross-repository fanout token is
-needed. Before tagging, verify credentials and new-version absence on both
-registries. Existing artifacts on retry must have matching integrity.
-
-Completion requires the Core tag SHA, all eleven npmjs/GPR packages, exact
-integrity, no workspace dependencies, a passing public-registry Worker gate,
-correct channel tags, and the GitHub release. Leftover `mantle-release`
-pointing at the last published candidate is expected. Retain run links and
-gate evidence.
-This does not prove stable production soak or upgrade safety; the version's
-release-gate issue owns those acceptance requirements. An agent acceptance run
-uses only the version-matched authoring instructions, not an SDK checkout or
-generated site.
-
-## Recovery
-
-Rerun the same controller commit/version for a transient or verified partial
-transition. Existing tags/artifacts must match; newer channels stay put. Fail
-on identity disagreement instead of guessing. A wrong public artifact needs
-a new version; never force-retag, overwrite or reuse a published version.
-
-After a controller-only fix lands on the tip, re-dispatch the same version
-from the source branch. Resolve recovers using the existing tag SHA when
-that commit is an ancestor of the tip and package versions on the tip still
-match. The tag owns the release SHA; the tip only carries controller fixes.
-Tagged recovery skips the Core source check because that tree was already
-released from the immutable tag. When `tag_exists` and all eleven npmjs
-packages already exist at that version, that same existence check skips
-packing, immutable tarball comparison, and the public-registry Worker gate.
-The controller tip must not rebuild an artifact whose identity is already
-published. Verify npm metadata still runs. The Worker gate stays skipped
-because the first run already passed it before promotion.
-
-Unpublish is reserved for actual secret/private-file exposure, never routine
-fixes. Infrastructure renames require their explicit config diff and live
-smoke; CI alone cannot prove provider identity.

package/docs/schema-indexes.md

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

package/docs/sealed-pipeline-ownership.md

@@ -1,101 +0,0 @@
-# Sealed pipeline ownership ledger
-
-This is the migration evidence for ADR-0019 and epic #656. It records the
-`v0.1.0-alpha.7` owners before code moves, the single target owner, and the
-issue that must delete or delegate the old path.
-
-## Rule ownership
-
-| Behavior | Current owner(s) | Target owner | Migration |
-|---|---|---|---|
-| YAML document decode, empty documents, syntax errors, alias cap | `ManifestParser.parseOneStream` | Parse/decode in `mantle-spec` | #663 |
-| Four-atom discrimination, envelope keys, primitive/enum shape | `ManifestParser` | Parse/normalize | #663 |
-| Source identity and document location | Synthetic parser doc index plus `loadManifests`/`ManifestPathDiagnoser` reconstruction | `ManifestSourceSet` authored metadata | #663 |
-| Schema atom-local shape, index/search/UI shape | Parser plus `ValidateManifestsUseCase` checkers | Parse/normalize | #663; old checks deleted in #673 |
-| Defaults for localized/lifecycle/indexes/search/order | `IntrospectManifestsUseCase`, runtime lifecycle checks, and callers using `??` | Parse/normalize exactly once | #663, #667 |
-| Duplicate names | `ValidateManifestsUseCase` | Link | #664 |
-| Schema/View/Procedure/Trigger cross-references | `ValidateManifestsUseCase` and repeated boot checks | Link | #664 |
-| Guard existence, self-reference, builtin/chain rules | Validate plus `ValidateBootUseCase` | Link | #664 |
-| Locale/translates graph | `checkLocaleAndTranslates` in validate and boot | Link for manifest graph; Prepare for selected deployment locales | #664, #666 |
-| Manifest-owned HTTP/MCP collisions | Validate plus boot | Link | #664 |
-| Handler source/registry availability | Optional CLI source scan plus boot registry scan | Prepare | #666 |
-| Optional Web/Admin/Auth path reservations | Fixed boot/Cloudflare prefix lists | Prepare selected capabilities only | #666, #669, #670 |
-| Kind/name lookup maps | `ValidateManifestsUseCase`, `ValidateBootUseCase`, `createCmsRuntime`, adapters | Compile once into `RuntimePlan` | #665 |
-| Authorization/guard descriptors | Raw manifests interpreted by validators, runtime use cases, and mounts | Compile plan; evaluate in Core invocation | #665, #667 |
-| Trigger indices and Procedure descriptors | Runtime construction/use cases | Compile plan | #665 |
-| Semantic fingerprint | Runtime boot from raw manifests | Compile plan | #665 |
-| Declarative View resolution | `ViewSqlCompiler` during each `ExecuteViewUseCase` call | Compile logical plan once | #665 |
-| SQLite/JSON1 View lowering and native `spec.sql` | `ViewSqlCompiler` plus `DatabaseDriver` invocation | Selected storage preparation | #666 |
-| Canonical SQL migrations, native Schema tables/indexes, readiness | `createCmsRuntime.bootInit` and runtime infrastructure | Prepare | #666 |
-| Entry/media/site repositories | Runtime constructs `Database*Repository` from `DatabaseDriver` | Prepared semantic storage ports; media/config move with final owner | #666, #669, #670 |
-| Content, View, Procedure, Trigger, lifecycle invocation | Runtime use cases over raw maps/driver | `MantleRuntime` over plan + semantic ports | #667 |
-| Target authorization/admin bypass | Runtime plus adapter entry points | One Core invocation policy; adapter resolves caller only | #667 |
-| Generated manifest module and TypeScript names | `packages/mantle/src/cli/generate.ts` + `EmitTypesUseCase` | Pure linked/plan projection and `bindMantle` | #668 |
-| Admin asset copy during generation | `packages/mantle/src/cli/generate.ts` | Removed; Admin install/composition owns assets | #668, #670 |
-| HTML/templates/public paths/Markdown/SEO/preview/`llms.txt`/sitemap | Runtime render services plus Cloudflare public routes | Optional `mantle-web` | #669 |
-| Public request mapping and cache policy | `mountPublicRoutes` | Platform adapter using selected Web projection | #669 |
-| Admin API/application/static assets | Optional `mantle-admin`; Cloudflare only binds auth/request context/assets | Optional `mantle-admin` + existing UI artifact | #670 |
-| View/HTTP Trigger route transport | Combined Cloudflare mounts | Platform adapters over the same Core descriptors | #669–#672 |
-| Bun SQLite/process lifecycle | `mantle-bun`; host owns server/database | `mantle-bun`; host owns server/database | #671 |
-| Vercel function/durable-storage lifecycle | `mantle-vercel`; host owns handler/client | `mantle-vercel`; host owns handler/client | #672 |
-| Legacy overloads, aliases, combined mounts, duplicate tests | Current public API plus temporary migration delegates | Deleted | #673 |
-| Contributor/agent/release guidance | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, two release skill copies | One tool-neutral authority and one release skill | #674 |
-
-## Deletion evidence
-
-All baseline production callers now consume `ParsedManifestSet`,
-`LinkedManifestSet`, or `RuntimePlan` according to their pipeline stage.
-`scripts/check-boundaries.mjs` fails if the removed runtime facade, generated
-site API, raw parser facade, or combined Cloudflare route owner returns.
-Parser-focused tests may inspect parser output, but runtime and platform tests
-must compile and prepare the same sealed plan used by production.
-
-## Consumer manifest corpus
-
-The Core repository does not vendor every downstream manifest. That would
-create a second source of truth. The reusable golden fixture under
-`packages/mantle-spec/test/fixtures/pipeline-v0.1/` covers every shipped atom,
-auth/guard references, all Trigger surfaces, multi-document YAML, empty
-documents, aliases, unknown keys, malformed YAML, and deterministic
-diagnostics.
-
-The following pins record the historical sealed-pipeline migration gates.
-ADR-0021 supersedes the Starter/Landing release coupling: current Core CI and
-release use `docs/examples/host-minimal-worker` from the same reviewed commit.
-Private consumers can still run the exact-tarball checker in their own repos;
-public Core PRs receive no cross-repository credentials:
-
-| Historical consumer | Revision | Gate at the time | Manifest paths |
-|---|---|---|---|
-| `aotter/mantle-starters` | `157e8f49e1e25ae1c52c0115f0dd9e8b6017ef0e` | Core CI + release | `blank/manifests/site.yaml`; `overlays/{community,intake,presence,publication,reservation,transaction}/manifests/site.yaml`; `recipes/typed-web/manifests/site.yaml` |
-| `aotter/mantle-landing` | `4381354dd25d5d94f4096cf3e55a4cb9eecbf3ad` | Landing CI + Core release | `manifests/site.yaml` |
-| `aotter/mantle-platform` (Remote Mantle/control plane) | `3cc0d9ad6ee47b15f06c915c12f56fc4b9143f32` | Platform `exact-packed-core` | `manifests/platform.yaml` |
-| Core i18n fixture | this repository | Core CI | `packages/mantle-spec/test/fixtures/i18n-parent-child/manifests/site.yaml` |
-
-## Baseline gates
-
-The alpha.7 baseline was captured from tag `v0.1.0-alpha.7` on 2026-08-16
-with Node 22, pnpm 9, Wrangler local mode, and datasets of 100/10,000 rows:
-
-| Route | p95 queries | p95 rows read | local p95 timing |
-|---|---:|---:|---:|
-| public View, 10k rows | 1 | 20 | 3.01 ms |
-| public page miss, 10k rows | 2 | 5 | 3.92 ms |
-| Admin list, 10k rows | 1 | 21–22 | 2.49–3.24 ms |
-| Admin related detail, dense | 4 | 151 | 5.23 ms |
-| public builtin create | 1 | 0 | 2.55 ms |
-
-Wall-clock values are evidence, not a cross-machine budget. The normative
-baseline is the existing `pnpm bench:wrangler` query/row gate: every gate must
-remain true, unchanged revisions must perform no repeated preparation, and any
-intentional budget change needs its own reviewed evidence.
-
-Existing full-facade behavior is covered by Cloudflare authorization, Admin,
-public-route/cache, View REST, HTTP Trigger, media, form, and facade tests.
-Issues #669–#673 move those assertions to selected modules and exact packed
-consumers; they do not duplicate the suite under new names.
-
-Issue #674 leaves `CONTRIBUTING.md` plus accepted ADRs as the contributor
-authority. `AGENTS.md`, `CLAUDE.md`, and the Claude release-skill entry are
-small routers; `.agents/skills/mantle-release/SKILL.md` is the only maintainer
-release procedure. Shipped `skills/*` remain separate consumer artifacts.

package/docs/skills/plugin/SKILL.md

@@ -1,132 +0,0 @@
----
-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/theme/SKILL.md

@@ -1,77 +0,0 @@
----
-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.