docs/release: Update release distribution docs and DoD (ZZBSAE)

.agentplane/tasks/202605011627-ZZBSAE/README.md

@@ -0,0 +1,131 @@
+---
+id: "202605011627-ZZBSAE"
+title: "Update release distribution docs and DoD"
+status: "DOING"
+priority: "high"
+owner: "DOCS"
+revision: 6
+origin:
+  system: "manual"
+depends_on:
+  - "202605011626-KJFS07"
+  - "202605011626-TG4GZ4"
+  - "202605011627-6B8QDR"
+  - "202605011627-F40YFZ"
+tags:
+  - "docs"
+  - "release"
+verify:
+  - "agentplane doctor"
+  - "bun run docs:cli:check"
+  - "node .agentplane/policy/check-routing.mjs"
+plan_approval:
+  state: "approved"
+  updated_at: "2026-05-01T16:36:54.525Z"
+  updated_by: "ORCHESTRATOR"
+  note: null
+verification:
+  state: "ok"
+  updated_at: "2026-05-01T18:15:24.568Z"
+  updated_by: "DOCS"
+  note: "Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface."
+commit: null
+comments:
+  -
+    author: "DOCS"
+    body: "Start: align release distribution documentation and DoD with the shipped modular publish workflow."
+events:
+  -
+    type: "status"
+    at: "2026-05-01T18:11:34.701Z"
+    author: "DOCS"
+    from: "TODO"
+    to: "DOING"
+    note: "Start: align release distribution documentation and DoD with the shipped modular publish workflow."
+  -
+    type: "verify"
+    at: "2026-05-01T18:15:24.568Z"
+    author: "DOCS"
+    state: "ok"
+    note: "Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface."
+doc_version: 3
+doc_updated_at: "2026-05-01T18:15:24.575Z"
+doc_updated_by: "DOCS"
+description: "Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations."
+sections:
+  Summary: |-
+    Update release distribution docs and DoD
+
+    Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+  Scope: |-
+    - In scope: Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+    - Out of scope: unrelated refactors not required for "Update release distribution docs and DoD".
+  Plan: "Plan: update developer and user-facing release documentation so the next release checklist explains npm, GitHub Release assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations. Verification: policy routing, doctor, docs CLI freshness."
+  Verify Steps: |-
+    1. Review the requested outcome for "Update release distribution docs and DoD". Expected: the visible result matches ## Summary and stays inside approved scope.
+    2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+    3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+  Verification: |-
+    <!-- BEGIN VERIFICATION RESULTS -->
+    ### 2026-05-01T18:15:24.568Z — VERIFY — ok
+
+    By: DOCS
+
+    Note: Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface.
+
+    VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T18:11:34.701Z, excerpt_hash=sha256:2dbb888af27194ca2a1ed00065f69e84145c31fe19fac6532d73f9bd99361267
+
+    <!-- END VERIFICATION RESULTS -->
+  Rollback Plan: |-
+    - Revert task-related commit(s).
+    - Re-run required checks to confirm rollback safety.
+  Findings: |-
+    - Observation: Checks: bun run docs:ia:check; bun run release:distribution:check; bun run release:setup-action:check; bun run release:ghcr:check; bun run docs:scripts:check; bunx prettier --check docs/developer/release-and-publishing.mdx docs/releases/v0.4.1.md; git diff --check; node .agentplane/policy/check-routing.mjs; agentplane doctor; bun install --frozen-lockfile --ignore-scripts; bun run docs:site:build (success with pre-existing webpack warning about vscode-languageserver-types dynamic require).
+      Impact: Release docs now separate automatic npm/GitHub/GHCR publication from Homebrew/Scoop/setup-action handoff artifacts, so post-release status cannot be mistaken for an external tap/bucket/action repo update.
+      Resolution: No docs follow-up remains for this release contour; external repo publication automation remains represented as credential-gated module evidence rather than claimed as completed publication.
+id_source: "generated"
+---
+## Summary
+
+Update release distribution docs and DoD
+
+Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+
+## Scope
+
+- In scope: Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+- Out of scope: unrelated refactors not required for "Update release distribution docs and DoD".
+
+## Plan
+
+Plan: update developer and user-facing release documentation so the next release checklist explains npm, GitHub Release assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations. Verification: policy routing, doctor, docs CLI freshness.
+
+## Verify Steps
+
+1. Review the requested outcome for "Update release distribution docs and DoD". Expected: the visible result matches ## Summary and stays inside approved scope.
+2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+
+## Verification
+
+<!-- BEGIN VERIFICATION RESULTS -->
+### 2026-05-01T18:15:24.568Z — VERIFY — ok
+
+By: DOCS
+
+Note: Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface.
+
+VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T18:11:34.701Z, excerpt_hash=sha256:2dbb888af27194ca2a1ed00065f69e84145c31fe19fac6532d73f9bd99361267
+
+<!-- END VERIFICATION RESULTS -->
+
+## Rollback Plan
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Findings
+
+- Observation: Checks: bun run docs:ia:check; bun run release:distribution:check; bun run release:setup-action:check; bun run release:ghcr:check; bun run docs:scripts:check; bunx prettier --check docs/developer/release-and-publishing.mdx docs/releases/v0.4.1.md; git diff --check; node .agentplane/policy/check-routing.mjs; agentplane doctor; bun install --frozen-lockfile --ignore-scripts; bun run docs:site:build (success with pre-existing webpack warning about vscode-languageserver-types dynamic require).
+  Impact: Release docs now separate automatic npm/GitHub/GHCR publication from Homebrew/Scoop/setup-action handoff artifacts, so post-release status cannot be mistaken for an external tap/bucket/action repo update.
+  Resolution: No docs follow-up remains for this release contour; external repo publication automation remains represented as credential-gated module evidence rather than claimed as completed publication.

.agentplane/tasks/202605011627-ZZBSAE/pr/diffstat.txt

@@ -0,0 +1,3 @@
+ docs/developer/release-and-publishing.mdx | 53 +++++++++++++++++--------------
+ docs/releases/v0.4.1.md                   |  8 ++++-
+ 2 files changed, 37 insertions(+), 24 deletions(-)

.agentplane/tasks/202605011627-ZZBSAE/pr/github-body.md

@@ -0,0 +1,35 @@
+## Summary
+
+Update release distribution docs and DoD
+
+Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+
+## Scope
+
+- In scope: Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+- Out of scope: unrelated refactors not required for "Update release distribution docs and DoD".
+
+## Verification
+
+- State: ok
+- Note: Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface.
+- Full verification checklist lives in local review.md.
+
+## Handoff Notes
+
+- No handoff notes recorded yet. Use `agentplane pr note ...` to append one.
+
+<details>
+<summary>Raw evidence</summary>
+
+- Updated: 2026-05-01T18:15:36.014Z
+- Branch: task/202605011627-ZZBSAE/release-distribution-docs
+- Head: b98e017935c4
+
+```text
+ docs/developer/release-and-publishing.mdx | 53 +++++++++++++++++--------------
+ docs/releases/v0.4.1.md                   |  8 ++++-
+ 2 files changed, 37 insertions(+), 24 deletions(-)
+```
+
+</details>

.agentplane/tasks/202605011627-ZZBSAE/pr/github-title.txt

@@ -0,0 +1 @@
+docs/release: Update release distribution docs and DoD (ZZBSAE)

.agentplane/tasks/202605011627-ZZBSAE/pr/meta.json

@@ -0,0 +1,14 @@
+{
+  "base": "main",
+  "branch": "task/202605011627-ZZBSAE/release-distribution-docs",
+  "created_at": "2026-05-01T18:11:34.746Z",
+  "head_sha": "b98e017935c4324fb267450fb774dc6170f1071c",
+  "last_verified_at": "2026-05-01T18:15:24.568Z",
+  "last_verified_sha": "ef204e16d5a34b715a6e4d31b7840a2fcda9c01a",
+  "schema_version": 1,
+  "task_id": "202605011627-ZZBSAE",
+  "updated_at": "2026-05-01T18:15:36.014Z",
+  "verify": {
+    "status": "pass"
+  }
+}

.agentplane/tasks/202605011627-ZZBSAE/pr/review.md

@@ -0,0 +1,59 @@
+# PR Review
+
+Created: 2026-05-01T18:11:34.746Z
+Branch: task/202605011627-ZZBSAE/release-distribution-docs
+
+## Summary
+
+Update release distribution docs and DoD
+
+Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+
+## Scope
+
+- In scope: Update public and developer docs so the next release checklist explains npm, GitHub assets, Homebrew tap, Scoop bucket, GHCR image, setup-agentplane, recovery, and evidence expectations.
+- Out of scope: unrelated refactors not required for "Update release distribution docs and DoD".
+
+## Verification
+
+### Plan
+
+1. Review the requested outcome for "Update release distribution docs and DoD". Expected: the visible result matches ## Summary and stays inside approved scope.
+2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+
+### Current Status
+
+- State: ok
+- Note: Release distribution docs now match the merged modular publish workflow and v0.4.1 notes include GHCR/setup-action release surface.
+
+## Risks
+
+- Risk level: not recorded
+- Breaking change: no
+
+### Rollback
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Handoff Notes
+
+- No handoff notes recorded yet. Use `agentplane pr note ...` to append one.
+
+<!-- BEGIN AUTO SUMMARY -->
+<details>
+<summary>Raw evidence</summary>
+
+- Updated: 2026-05-01T18:15:36.014Z
+- Branch: task/202605011627-ZZBSAE/release-distribution-docs
+- Head: b98e017935c4
+
+```text
+ docs/developer/release-and-publishing.mdx | 53 +++++++++++++++++--------------
+ docs/releases/v0.4.1.md                   |  8 ++++-
+ 2 files changed, 37 insertions(+), 24 deletions(-)
+```
+
+</details>
+<!-- END AUTO SUMMARY -->

docs/developer/release-and-publishing.mdx

@@ -146,20 +146,24 @@ The install scripts are convenience entrypoints, not update sources of truth. Pa
 scripts must install an exact release version and must not implement self-update behavior that
 bypasses the hosted release pipeline.
 
-Blocking release channels:
+Automated release channels:
 
 - npm packages: `@agentplaneorg/core`, `@agentplaneorg/recipes`, and `agentplane`
 - GitHub Release tag/body/assets
 - GitHub Release checksum manifest
-- GHCR image for the exact version and commit
-- AgentPlane-owned Homebrew tap update when tap credentials are configured
-- AgentPlane-owned Scoop bucket update when bucket credentials are configured
-- `setup-agentplane` release/update when action repository credentials are configured
+- GHCR image for the exact versioned CLI tarball
 
-Credentials-gated channels must be explicit in the manifest. If a credential is absent, the channel
-must record `skipped_missing_credentials` with the expected secret name and a recovery command. It
-must not fail an otherwise valid npm/GitHub release unless that channel was explicitly marked
-required for the run.
+Credentials-gated handoff channels:
+
+- AgentPlane-owned Homebrew tap formula bundle when tap credentials are configured
+- AgentPlane-owned Scoop bucket manifest bundle when bucket credentials are configured
+- `setup-agentplane` action bundle when action repository credentials are configured
+
+These handoff channels are generated by the publish workflow and uploaded as module artifacts. A
+rendered formula, manifest, or action bundle is not proof that the external repository was updated.
+If a credential is absent, the channel must record `skipped_missing_credentials` with the expected
+secret name and a recovery command. It must not fail an otherwise valid npm/GitHub/GHCR release
+unless that channel was explicitly marked required for the run.
 
 External moderated registries such as `homebrew/core`, winget, Chocolatey, AUR, and nixpkgs are
 follow-up publication targets. They should be opened as PR jobs or manual recovery tasks after the
@@ -171,18 +175,18 @@ Keep publication modules independent and evidence-backed:
 
 - npm module: publishes packages, runs published-package smoke checks, and records package outcomes.
 - GitHub assets module: creates release assets, checksum manifest, and upload evidence.
-- GHCR module: builds the exact-version image, tags `vX.Y.Z`, commit SHA, and `latest`, then runs a
-  container CLI smoke check.
+- GHCR module: builds the image from the local release npm tarball artifact, tags the semver,
+  release tag, and `latest`, writes `ghcr-result.json`, and supports a container CLI smoke check.
 - Homebrew tap module: renders `Formula/agentplane.rb` from `release-distribution.json`, verifies
-  the formula in dry-run/check mode, then opens or updates a tap PR when credentials exist.
-- Scoop bucket module: renders `bucket/agentplane.json` from `release-distribution.json`, verifies
-  checksum and URL fields in check mode, then opens or updates a bucket PR when credentials exist.
-- setup action module: updates the `setup-agentplane` release path so CI users can resolve an exact
-  AgentPlane version from the manifest.
+  the formula in dry-run/check mode, and writes `homebrew-result.json`.
+- Scoop bucket module: renders `agentplane.json` from `release-distribution.json`, verifies checksum
+  and URL fields in check mode, and writes `scoop-result.json`.
+- setup action module: renders a `setup-agentplane` composite action bundle that installs through
+  the release `install.sh` asset and writes `setup-agentplane-result.json`.
 
-Each module must emit a compact JSON evidence file under `.agentplane/.release/publish/`. The final
-`publish-result.json` should reference those module files instead of flattening every channel into
-one shell step.
+Each module must emit a compact JSON evidence file under `.agentplane/.release/publish/`. The
+publish workflow uploads the distribution manifest plus module artifact directories so a failed or
+partial run can be diagnosed from artifacts instead of shell-log archaeology.
 
 GitHub workflow `Core CI` also supports `workflow_dispatch` recovery:
 
@@ -257,7 +261,8 @@ For distribution recovery, use the manifest first:
 - if GitHub Release assets are missing, regenerate and upload assets for the same tag before running
   package-manager modules
 - if GHCR publish failed after npm succeeded, rerun the GHCR module against the exact release SHA
-- if a tap or bucket PR already exists, update that PR rather than creating a duplicate
+- if a tap, bucket, or setup-action repository PR already exists, update that PR rather than creating
+  a duplicate
 - if credentials were missing, add the secret and rerun the credentials-gated module; do not bump the
   release version
 
@@ -298,6 +303,8 @@ versions, or release notes for you.
 - verify upgrade bundle artifacts exist in release assets
 - verify `release-distribution.json` matches the published tag and release SHA
 - verify `SHA256SUMS` covers all install and upgrade assets
-- verify GHCR image tags resolve and `agentplane --version` works in the container
-- verify Homebrew tap, Scoop bucket, and setup-action outcomes are either published or explicitly
-  recorded as `skipped_missing_credentials` with recovery instructions
+- verify the GHCR tags recorded in `ghcr-result.json` resolve and `agentplane --version` works in
+  the container
+- verify Homebrew tap, Scoop bucket, and setup-action module artifacts are either externally
+  published by a follow-up PR or explicitly recorded as `skipped_missing_credentials` with recovery
+  instructions