docs(release): mark npm alpha published

README.md

@@ -39,7 +39,7 @@ curl -fsSL https://github.com/omerakben/code-oz/releases/download/v0.21.2-alpha.
   | sh -s -- --version v0.21.2-alpha.0
 
 # npm (scoped under the TUEL AI publisher; binary still runs as `code-oz`)
-npm install -g @tuel/code-oz
+npm install -g @tuel/code-oz@0.21.2-alpha.0
 
 # Homebrew
 brew tap omerakben/code-oz
@@ -48,7 +48,7 @@ brew install omerakben/code-oz/code-oz
 
 Platform support: macOS arm64, macOS x64, Linux x64, Linux arm64. Windows and Scoop are deferred to a future distribution milestone.
 
-If `npm install -g @tuel/code-oz` fails with a 404 or authentication error, your `~/.npmrc` is likely overriding the `@tuel` scope — see [`docs/TRUST.md` § Install gotchas](docs/TRUST.md#install-gotchas-npm-scope-routing-for-tuelcode-oz) for the fix.
+If `npm install -g @tuel/code-oz@0.21.2-alpha.0` fails with a 404 or authentication error, your `~/.npmrc` is likely overriding the `@tuel` scope — see [`docs/TRUST.md` § Install gotchas](docs/TRUST.md#install-gotchas-npm-scope-routing-for-tuelcode-oz) for the fix.
 
 ## Use it inside Claude Code (plugin)
 
@@ -59,7 +59,7 @@ code-oz ships two Claude Code plugins through a marketplace declared at this rep
 /plugin install code-oz@code-oz-marketplace
 ```
 
-The `code-oz` plugin is a thin wrapper. It adds `/code-oz-run`, `/code-oz-init`, `/code-oz-doctor`, and `/code-oz-resume`, and each command discovers the `code-oz` engine on your `PATH`, falling back to `npx @tuel/code-oz` when the binary is absent. Install the engine from the channels above for the fastest path. The plugin never writes gates, events, or reviews — the engine binary is the only writer, so the gate guarantees hold whether you drive code-oz from the CLI or through the plugin.
+The `code-oz` plugin is a thin wrapper. It adds `/code-oz-run`, `/code-oz-init`, `/code-oz-doctor`, and `/code-oz-resume`, and each command discovers the `code-oz` engine on your `PATH`, falling back to the plugin-pinned `npx @tuel/code-oz@0.21.2-alpha.0` when the binary is absent. Install the engine from the channels above for the fastest path. The plugin never writes gates, events, or reviews — the engine binary is the only writer, so the gate guarantees hold whether you drive code-oz from the CLI or through the plugin.
 
 A second plugin, `code-oz-discipline`, is optional. It installs advisory-only skills (brainstorming, source-check, RED-first) that are guidance, not enforcement:
 

docs/PROVIDER_SETUP.md

@@ -13,7 +13,7 @@
 ## Recommended first run
 
 ```sh
-npm install -g @tuel/code-oz
+npm install -g @tuel/code-oz@0.21.2-alpha.0
 mkdir /tmp/code-oz-first-run && cd /tmp/code-oz-first-run
 code-oz init
 code-oz run --provider fake --request "Create a tiny hello-world CLI"

docs/RELEASE_READINESS.md

@@ -1,6 +1,6 @@
 # Release readiness
 
-Current status as of 2026-06-14: `v0.21.2-alpha.0` is published on GitHub release assets and Homebrew. npm `@tuel/code-oz@0.21.2-alpha.0` is package-ready but still pending publish authorization; the repo-side path is `.github/workflows/npm-publish.yml`, which uses npm trusted publishing with GitHub Actions OIDC.
+Current status as of 2026-06-14: `v0.21.2-alpha.0` is published on GitHub release assets, Homebrew, and npm. npm `@tuel/code-oz@0.21.2-alpha.0` is available under the `alpha` dist-tag and by exact version; the unqualified `latest` tag still points at `0.21.1-alpha.0` until it is promoted with npm 2FA.
 
 This page separates what is publishable today from what is manual, experimental, or future work.
 
@@ -9,7 +9,7 @@ This page separates what is publishable today from what is manual, experimental,
 | Surface | Package or path | Status | Notes |
 |---|---|---|---|
 | CLI binary | `src/cli.ts` compiled by `bun build --compile` | Publishable for macOS/Linux | GitHub release workflow builds per-arch tarballs and `checksums.txt`. Windows is not built. |
-| npm launcher | `@tuel/code-oz` | Publish-ready, auth pending | `package.json.files` includes `npm-wrapper/`, `README.md`, and `LICENSE`. The wrapper downloads the matching GitHub release binary on first run. |
+| npm launcher | `@tuel/code-oz@0.21.2-alpha.0` | Published under `alpha` | `package.json.files` includes `npm-wrapper/`, `README.md`, and `LICENSE`. The wrapper downloads the matching GitHub release binary on first run. |
 | Homebrew formula | `docs/homebrew/code-oz.rb.template` | Published for `0.21.2-alpha.0` | Render from release checksums, then commit to `omerakben/homebrew-code-oz`. |
 | Claude Code plugin marketplace | `.claude-plugin/marketplace.json` | Repo-root marketplace metadata present | Contains `code-oz` engine wrapper plugin and advisory `code-oz-discipline` plugin. |
 | Agent skill bundle | `agent-skills/code-oz/` | Text-only integration surface | No executable. It teaches external agents how to drive the CLI without owning gates. |
@@ -44,7 +44,29 @@ Do not publish npm before the GitHub release assets for the exact version exist,
 
 `scripts/release/fresh-clone-smoke.sh` clones the current branch from git, so it validates committed `HEAD`, not uncommitted working-tree edits. Run it after the release-readiness patch is committed.
 
-## npm publish authorization
+## npm publish and dist-tags
+
+`0.21.2-alpha.0` is published. Verify:
+
+```sh
+npm view @tuel/code-oz@0.21.2-alpha.0 version
+npm view @tuel/code-oz dist-tags --json
+npx -y @tuel/code-oz@0.21.2-alpha.0 --version
+```
+
+Current npm install command for this exact release:
+
+```sh
+npm install -g @tuel/code-oz@0.21.2-alpha.0
+```
+
+The `latest` dist-tag still points at `0.21.1-alpha.0`. To promote this release to unqualified installs, run with npm 2FA:
+
+```sh
+npm dist-tag add @tuel/code-oz@0.21.2-alpha.0 latest --otp=<code>
+```
+
+## npm publish authorization for future releases
 
 Preferred path: use npm trusted publishing for `.github/workflows/npm-publish.yml`.
 
@@ -138,4 +160,4 @@ Measured locally on 2026-06-14:
 - `code-oz-gui`: `bun install --frozen-lockfile`, `bun run typecheck`, `bun run lint`, `bun test tests/unit`, and `bun run build` pass.
 - Dogfood flows: first-run fake provider, `bun run demo:todo-cli`, `bun run demo:failure-gates`, `doctor providers`, `doctor tools`, `doctor git`, and `bench agent-gate --fixture todo-cli-real-tests --provider fake` pass.
 
-These are enough to call the docs/package/plugin/GUI release-prep patch ready for review. The public release is live through GitHub release assets, curl install, and Homebrew. npm still needs one authorization step through trusted publishing or an authenticated local publish.
+These are enough to call the docs/package/plugin/GUI release-prep patch ready for review. The public release is live through GitHub release assets, curl install, Homebrew, and npm exact-version or `alpha` install. Unqualified npm `latest` remains one optional dist-tag promotion step.

docs/TRUST.md

@@ -90,7 +90,7 @@ All three land at the `v0.x stable` milestone. Until then, treat the alpha insta
 
 ### Install gotchas: npm scope routing for `@tuel/code-oz`
 
-`@tuel/code-oz` is published on public npm under the `@tuel` scope. If your user-level `~/.npmrc` registers a custom registry for the `@tuel` scope (for example, a private registry from a different `@tuel`-scoped package at a previous employer), `npm install -g @tuel/code-oz` routes to that registry instead of public npm. The install fails with a 404 or an authentication error, not with a useful "scope is overridden" message.
+`@tuel/code-oz` is published on public npm under the `@tuel` scope. If your user-level `~/.npmrc` registers a custom registry for the `@tuel` scope (for example, a private registry from a different `@tuel`-scoped package at a previous employer), `npm install -g @tuel/code-oz@0.21.2-alpha.0` routes to that registry instead of public npm. The install fails with a 404 or an authentication error, not with a useful "scope is overridden" message.
 
 Check your scope routing the same way npm resolves it for a global install:
 
@@ -105,7 +105,7 @@ If the output is `undefined` (the npm CLI's literal string for an unconfigured k
 1. Per-command override (preferred, leaves your config untouched):
 
    ```sh
-   npm install -g @tuel/code-oz --@tuel:registry=https://registry.npmjs.org/
+   npm install -g @tuel/code-oz@0.21.2-alpha.0 --@tuel:registry=https://registry.npmjs.org/
    ```
 
    Use the `--@tuel:registry=` form, **not** `--registry=`. The plain `--registry=` flag sets npm's default registry, but a scope-specific `@tuel:registry` mapping in your `~/.npmrc` has higher precedence and wins; the `--@scope:registry=` form sets the scope-specific registry on the command line and overrides any `.npmrc` mapping. `npm install -g` does not consult a project-local `.npmrc`, so checking out this repo's `.npmrc` does not help — the per-command flag is the reliable path.

docs/handoffs/2026-06-14-release-readiness-audit.md

@@ -1,11 +1,11 @@
 # 2026-06-14 release-readiness audit
 
-This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the shipped `v0.21.1-alpha.0` line.
+This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the shipped `v0.21.1-alpha.0` line. It was later updated after the actual `v0.21.2-alpha.0` publication completed.
 
 ## Current state
 
-- Latest published release remains `v0.21.1-alpha.0`; this branch prepares `v0.21.2-alpha.0`.
-- npm currently publishes `@tuel/code-oz@0.21.1-alpha.0`; this branch bumps the package and plugin marketplace metadata to `0.21.2-alpha.0`.
+- GitHub release assets, curl install, Homebrew, and npm now publish `v0.21.2-alpha.0`.
+- npm publishes `@tuel/code-oz@0.21.2-alpha.0` under the `alpha` dist-tag and exact version. The `latest` dist-tag still points at `0.21.1-alpha.0` until a separate npm 2FA dist-tag promotion.
 - Recent post-tag commits fix Claude Code plugin marketplace installation and no-argument command handling.
 - The root npm package is a launcher package, not a binary bundle.
 - `code-oz-gui` is private and local-only; it is not a standalone packaged app.
@@ -36,6 +36,6 @@ This note captures the `v0.21.2-alpha.0` release-readiness truth sync after the
 ## Still not proven
 
 - Live brownfield AUDIT dogfood still requires local provider credentials.
-- npm/Homebrew publishing still requires a new release tag and published GitHub assets for the exact version.
+- Unqualified npm installs still resolve through the `latest` dist-tag until `npm dist-tag add @tuel/code-oz@0.21.2-alpha.0 latest --otp=<code>` runs.
 - The isolated Claude Code marketplace install passed; a real user-profile install can still be repeated manually before announcement if desired.
 - GUI standalone packaging is not designed or implemented.

plugins/code-oz/scripts/resolve-code-oz.sh

@@ -129,7 +129,7 @@ fi
 # 4. Neither code-oz nor npx/npm available — hard-stop.
 # ---------------------------------------------------------------------------
 printf 'code-oz is not installed. Install:\n' >&2
-printf '  npm i -g @tuel/code-oz\n' >&2
+printf '  npm i -g @tuel/code-oz@%s\n' "${PINNED_VERSION}" >&2
 printf '  OR\n' >&2
 printf '  brew install omerakben/code-oz/code-oz\n' >&2
 exit 1

tests/plugins/bootstrap-resolver.test.ts

@@ -260,6 +260,8 @@ describe('resolve-code-oz.sh — hard-stop (no code-oz, no npm/npx)', () => {
     expect(result.stdout + result.stderr).toMatch(/npm/)
     // Must mention the package name
     expect(result.stdout + result.stderr).toMatch(/@tuel\/code-oz/)
+    // Must pin the plugin version instead of relying on npm's moving latest tag.
+    expect(result.stdout + result.stderr).toContain('@tuel/code-oz@0.21.2-alpha.0')
     // Must mention brew as alternative, with the correct tap form.
     expect(result.stdout + result.stderr).toMatch(/brew/)
     expect(result.stdout + result.stderr).toContain('omerakben/code-oz/code-oz')