@aotter/mantle 0.1.3-alpha.1 → 0.1.3-alpha.2

package/README.md

@@ -12,11 +12,11 @@ where agents write config and the runtime carries the complexity.
 Cold start for a new application is the pinned skill, not a bare npm add:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 To depend on this package in an existing project, pin the exact version
-from `package.json` (currently `0.1.3-alpha.1`):
+from `package.json` (currently `0.1.3-alpha.2`):
 
 ```bash
 npm install @aotter/mantle
@@ -197,7 +197,7 @@ internals or rebuilding Mantle's adapters.
 Cold start from GitHub or a marketplace host:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 That skill interviews, pins this package, then uses the CLI and the
@@ -215,25 +215,25 @@ Install the Mantle Core skill bundle before authoring or maintaining a
 consumer application. The canonical command is:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 Claude Code and Codex can install the same pinned plugin, then run that skill:
 
 ```bash
 # Claude Code
-/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
 /plugin install mantle@mantle
 
 # Codex
-codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.1
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.2
 codex plugin add mantle@mantle
 ```
 
 Cursor and VS Code Copilot can auto-discover the GitHub repo through
 `.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json` after the repo
 is cloned or opened. Still start from the `npx skills add` sentence (or open
-`skills/install/SKILL.md` at tag `v0.1.3-alpha.1`). Do not point a versioned consumer
+`skills/install/SKILL.md` at tag `v0.1.3-alpha.2`). Do not point a versioned consumer
 at a mutable branch.
 
 ## Marketplace capability installs

package/dist/cli/main.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install\n";
+export declare const MANTLE_OVERVIEW = "mantle \u2014 compile manifests into a RuntimePlan and typed binding\n\nOverview\n  Optional surfaces \u2014 take only what you need. Admin is opt-in. You can ship a\n  complete service with no Dev UI, no visitor frontend, and no extra packages.\n\n  Minimal \u2014 Spec + generate\n    validate + generate compile manifests into a sealed plan and typed binding.\n    Embed that binding in an existing host. No Admin, no visitor UI.\n\n  Runtime / adapter\n    Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).\n    HTTP Views, MCP, and Auth work without Admin.\n    See docs/examples/host-minimal-worker or\n    node_modules/@aotter/mantle/docs/examples/host-minimal-worker.\n\n  Opt-in \u2014 Admin / Dev UI\n    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need\n    a console. Then re-run generate, bind wrangler ASSETS, and open\n    /admin/sign-in (local email OTP via ConsoleEmailSender).\n    See docs/examples/host-local-admin-otp or\n    node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.\n\n  Further (ask the subcommand for details)\n    skills          project version-matched agent instructions\n    emit-openapi    OpenAPI 3.1 from HTTP Triggers and Views\n    mantle-harness  measure indexes and live HTTP (separate binary)\n\nUsage: mantle <subcommand> [options]\n\nSubcommands:\n  generate       Compile manifests into a typed runtime binding\n  validate       Static manifest and handler-source validation\n  skills         Project version-matched Core skills\n  emit-openapi   Emit OpenAPI 3.1 from Triggers and Views\n\nDocumentation:\n  Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)\n  Online:        https://mantle.tools/\n  Install skill: npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install\n";
 //# sourceMappingURL=main.d.ts.map

package/dist/cli/main.js

@@ -64,7 +64,7 @@ Subcommands:
 Documentation:
   Handbook:      node_modules/@aotter/mantle/docs/handbook/ (or docs/handbook/)
   Online:        https://mantle.tools/
-  Install skill: npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+  Install skill: npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 `;
 main().then((code) => {
     process.exitCode = code;

package/docs/agent-prompts.md

@@ -3,7 +3,7 @@
 Cold start from GitHub or a marketplace host is one pinned skill:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 Copy one block into a coding agent after that skill is present. Paths below
@@ -20,7 +20,7 @@ manifests exist. Admin is opt-in.
 ```text
 Interview me about the service: host, who uses it, whether humans need a
 Dev UI, and whether we only embed Spec/Runtime. If the install skill is
-missing, run npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install. Read the
+missing, run npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install. Read the
 install skill and npx --no-install mantle --help, then
 handbook/start/project-and-cli.md.
 Use examples/README.md as the examples index; copy builtin-* Manifests only

package/docs/handbook/concepts/mcp-and-agents.md

@@ -95,10 +95,10 @@ For Claude Code, the same bundle is installable from the plugin marketplace at t
 
 ```sh
 # Canonical
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 
 # Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
 /plugin install mantle@mantle
 ```
 

package/docs/handbook/start/project-and-cli.md

@@ -8,7 +8,7 @@ This page describes a directly authored Mantle project: which files are yours, w
 Cold start from GitHub or a marketplace host is the pinned install skill, not this page:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 ## You own the project
@@ -100,18 +100,18 @@ Run the harness after any change to a Schema index, View filter or ordering, or
 
 Install the version-matched plugin bundle in the agent host. Cold start uses
 the published pin; an already-installed project uses the exact version from
-`package.json` (currently `0.1.3-alpha.1`):
+`package.json` (currently `0.1.3-alpha.2`):
 
 ```sh
 # Canonical
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 
 # Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
 /plugin install mantle@mantle
 
 # Codex
-codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.1
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.2
 codex plugin add mantle@mantle
 ```
 

package/docs/release-process.md

@@ -15,9 +15,9 @@ No task implicitly authorizes publication; no manual package/tag writer exists.
 |---|---|---|
 | 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 |
-| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels unchanged |
-| Consumer passes | Monotonic npm/GPR channel promotion | Same version is a no-op; older runs cannot move a channel backward |
-| Channels promoted/preserved newer | GitHub release step | Existing release identity or fail |
+| 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, then `dist-tag rm` of `mantle-release` only | Same version is a no-op; older runs cannot move a channel backward. Removal runs only after that package's promote loop, and only when `mantle-release` points at this version. A missing tag is a no-op. A tag pointing at another version is left for that version's promote step. `alpha` / `beta` / `rc` / `latest` are never removed |
+| Channels promoted or preserved, and the temp tag cleared or left | GitHub release step | Existing release identity or fail |
 
 The public-registry gate uses a disposable copy of the directly authored
 `docs/examples/host-minimal-worker` reference, installs the exact candidate, then
@@ -39,9 +39,41 @@ 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 or rollback
-is introduced. The runnable release-order check guards these transitions.
+and the published-consumer gate precede public channel promotion and any
+removal of `mantle-release` by the release controller; retries cannot move
+channels backward. No downstream mutation, unpublish 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` may attach `mantle-release` while publishing a version.
+`Promote npmjs channel tags` is the only release step that moves npmjs
+channels or removes that tag for the version being released. `Promote
+GitHub Packages channel tags` is the only release step that does the same
+for GitHub Packages. Recovery of a partial release reruns that same
+controller and version. It does not call the cleanup workflow.
+
+The cleanup workflow is a separate writer for one case the controller
+cannot cover: a release commit that predates temp-tag removal still leaves
+`mantle-release` behind, and a personal npm token that is `read-write` on
+`npm access` can still receive 403 on dist-tag DELETE.
+`.github/workflows/remove-mantle-release-dist-tag.yml` uses the Actions
+`NPM_TOKEN` and `GITHUB_TOKEN`. It is not a release controller and not a
+recovery path.
+
+| State | Sole next writer | Retry / invariant |
+|---|---|---|
+| Leftover `mantle-release` after `alpha`, `beta`, `rc`, or `latest` already points at that version | `remove-mantle-release-dist-tag`, only when `confirm` is `remove-mantle-release` | Missing tag is a no-op. Only `mantle-release` is removed. Before and after dist-tags are printed and compared; every other tag is unchanged |
+| `mantle-release` points at a version no consumer channel has | No deletion | The job fails and leaves the tag. Channel moves stay on the release promote step |
+| Confirm string is anything else | No registry call | The job fails before reading or editing tags |
+
+It shares the `release-controller` concurrency group with
+`cancel-in-progress: false`, so it waits out an in-progress release instead
+of deleting `mantle-release` between publish and channel promotion. After
+this file is on `develop`:
+
+```sh
+gh workflow run remove-mantle-release-dist-tag --ref develop -f confirm=remove-mantle-release
+```
 
 ## Branches and channels
 
@@ -63,6 +95,10 @@ is introduced. The runnable release-order check guards these transitions.
   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`, so publication does not move
+  `alpha`, `beta`, `rc`, or `latest`. After the public-registry consumer
+  gate, each registry's promote step moves the real channel and then removes
+  `mantle-release` when that tag points at this version.
 
 ## Prepare and run
 
@@ -176,7 +212,8 @@ 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. Retain run links and gate evidence.
+correct channel tags, no `mantle-release` tag left on this version, and the
+GitHub release. 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

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.1`. Pin the package, record the tested version, and
+This recipe targets `0.1.3-alpha.2`. 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.1",
+  "version": "0.1.3-alpha.2",
   "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.1",
-    "@aotter/mantle-spec": "0.1.3-alpha.1"
+    "@aotter/mantle-runtime": "0.1.3-alpha.2",
+    "@aotter/mantle-spec": "0.1.3-alpha.2"
   },
   "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.1",
-    "@aotter/mantle-auth": "0.1.3-alpha.1",
-    "@aotter/mantle-vercel": "0.1.3-alpha.1",
-    "@aotter/mantle-bun": "0.1.3-alpha.1",
-    "@aotter/mantle-web": "0.1.3-alpha.1",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.1",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.1"
+    "@aotter/mantle-auth": "0.1.3-alpha.2",
+    "@aotter/mantle-admin": "0.1.3-alpha.2",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.2",
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.2",
+    "@aotter/mantle-bun": "0.1.3-alpha.2",
+    "@aotter/mantle-web": "0.1.3-alpha.2",
+    "@aotter/mantle-vercel": "0.1.3-alpha.2"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -144,13 +144,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.3-alpha.1",
-    "@aotter/mantle-bun": "0.1.3-alpha.1",
-    "@aotter/mantle-auth": "0.1.3-alpha.1",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.1",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.1",
-    "@aotter/mantle-vercel": "0.1.3-alpha.1",
-    "@aotter/mantle-web": "0.1.3-alpha.1"
+    "@aotter/mantle-admin": "0.1.3-alpha.2",
+    "@aotter/mantle-auth": "0.1.3-alpha.2",
+    "@aotter/mantle-bun": "0.1.3-alpha.2",
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.2",
+    "@aotter/mantle-web": "0.1.3-alpha.2",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.2",
+    "@aotter/mantle-vercel": "0.1.3-alpha.2"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -62,16 +62,16 @@ Cold start is the pinned install skill. Other marketplace hosts are pointers
 to the same pin:
 
 ```sh
-npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+npx skills add aotter/mantle@v0.1.3-alpha.2 --skill install
 ```
 
 ```bash
 # Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.2
 /plugin install mantle@mantle
 
 # Codex
-codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.1
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.2
 codex plugin add mantle@mantle
 ```
 
@@ -97,7 +97,7 @@ 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@v0.1.3-alpha.1 --skill install`. Point the agent at tag `v0.1.3-alpha.1` 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@v0.1.3-alpha.2 --skill install`. Point the agent at tag `v0.1.3-alpha.2` or pass the version-matched markdown content directly.
 
 ## Conventions