build: enforce complete private release workflow

docs/PUBLISHING.md

@@ -21,7 +21,58 @@ The repo `.npmrc` points the scope at public npm:
 @wrnexus:registry=https://registry.npmjs.org/
 ```
 
-## Publish
+## Mandatory release workflow
+
+Do not publish packages with ad-hoc `npm publish` commands during a normal release. The
+repository release commands enforce the complete framework + migration + documentation
+workflow.
+
+Every release must have an entry in `packages/cli/src/update.ts`'s `MIGRATIONS` list. The
+entry must be idempotent and conservative. If a release requires no project file change,
+add a documented no-op migration entry so that the decision is explicit and reviewable.
+
+### 1. Prepare
+
+Align every `packages/*/package.json` version, add the update migration and tests, then run:
+
+```bash
+bun run release:prepare
+```
+
+This command refuses to prepare a release when versions differ or migration coverage is
+missing. It runs the complete framework check, builds all publish artifacts, and verifies
+that every staged manifest uses the aligned version and `restricted` access.
+
+Review the generated `.publish` changes, then commit and push the framework repository.
+The publish step will refuse to run from an uncommitted or unpushed framework checkout.
+
+### 2. Publish privately and update documentation
+
+```bash
+bun run release:private
+```
+
+The command performs the remaining release as one guarded workflow:
+
+1. Rebuild and validate all private package artifacts from the pushed commit.
+2. Publish every missing `@wrnexus/*` package in dependency order. Already-published
+   packages are verified and skipped, so an interrupted release can be resumed safely.
+3. Confirm every package is private and run the newly published CLI updater, including its
+   migrations, against `D:\Company\wrnexusjs`.
+4. Align every docs-site dependency, regenerate package pages twice, update
+   `public/llms.txt`, `public/llms-full.txt`, the sitemap, and the documentation index.
+5. Run the docs-site check and production build, verify that `public/llms.txt` contains the
+   current version and every framework package, then commit and push the docs repository.
+
+If the documentation checkout lives elsewhere, set `WRNEXUS_DOCS_ROOT` before running the
+publish command. Both repositories must start clean and synchronized with their active
+remote branches.
+
+Only use the individual commands printed by `scripts/publish-packages.ts` for diagnosed
+recovery. Finish recovery by rerunning `bun run release:private`; it is the authoritative
+completion check.
+
+## Publishing implementation
 
 The packages ship raw TypeScript in the repo (`main`/`exports` → `src/*.ts`), so
 they are **built** for publishing. `scripts/publish-packages.ts` builds each
@@ -36,13 +87,14 @@ package with [tsup](https://tsup.egoist.dev) (bundled JS + a single `.d.ts`) and
 The dev `package.json` (pointing at `src/`) is **never modified**, so in-repo dev
 and tests keep working.
 
-### 1. Private-first (test before the world sees it)
+### Private staging details
 
-By default the script stages packages as **`restricted`** (private). Requires the
-`wrnexus` org on a paid Teams plan.
+By default the lower-level staging script creates **`restricted`** (private) manifests.
+It is called by the mandatory release commands and requires the `wrnexus` org on a paid
+Teams plan.
 
 ```bash
-# Build + stage all packages (access: restricted)
+# Lower-level recovery/debug command only
 bun run scripts/publish-packages.ts
 
 # Publish (deps first). The script prints the exact order + --access flag; e.g.
@@ -52,8 +104,8 @@ npm publish .publish/compiler --access restricted
 npm publish .publish/cli --access restricted
 ```
 
-Test the private packages (see below). When satisfied, **flip every package to
-public** (no republish needed):
+When an approved release is ready to become public, **flip every package to public** (no
+republish needed):
 
 ```bash
 npm access public @wrnexus/core
@@ -61,7 +113,7 @@ npm access public @wrnexus/compiler
 # … the script prints the full list …
 ```
 
-### 2. Public directly
+### Public staging for an explicitly approved public release
 
 To stage public manifests from the start (free org is enough):