docs: add release verification guide

Author: squaeragent

README.md

@@ -474,6 +474,7 @@ deployment project, secrets, exchange credentials, and runtime state.
 - [docs/railway-deploy.md](docs/railway-deploy.md)
 - [docs/distribution.md](docs/distribution.md)
 - [docs/release.md](docs/release.md)
+- [docs/release-verification.md](docs/release-verification.md)
 
 ## Contributor Paths
 
@@ -571,6 +572,7 @@ Machine-readable entrypoints:
 - [Agentic Contribution](docs/agentic-contribution.md)
 - [Contributor Issue Board](docs/contributor-issue-board.md)
 - [Launch Scorecard](docs/launch-scorecard.md)
+- [Release Verification](docs/release-verification.md)
 - [Roadmap](docs/roadmap.md)
 
 ## License

docs/backlog.md

@@ -23,6 +23,9 @@ issues and three help-wanted issues for agentic and human contributors.
 The corresponding live issues are listed in
 [docs/contributor-issue-board.md](contributor-issue-board.md).
 
+Completed seed issues move to the completed section on the board and keep their
+source-controlled acceptance criteria in [launch issues](launch-issues.md).
+
 ## Example Contribution Shapes
 
 ### Add a paper-first strategy plugin
@@ -64,6 +67,7 @@ Evidence:
 
 - [Release notes](releases/v0.1.1.md)
 - [Clean-download release evidence](releases/v0.1.1-evidence.md)
+- [Release verification guide](release-verification.md)
 
 Do not create new first-release tasks unless a future release target changes
 artifact requirements or public safety claims.

docs/contributor-issue-board.md

@@ -23,7 +23,11 @@ Use the GitHub labels when choosing work:
 
 - [#23 Expand read-only MCP strategy resources](https://github.com/zero-intel/zero/issues/23)
 - [#24 Design public Network empty and stale states](https://github.com/zero-intel/zero/issues/24)
-- [#25 Add release evidence reader docs](https://github.com/zero-intel/zero/issues/25)
+
+## Completed Seed Issues
+
+- [#25 Add release evidence reader docs](https://github.com/zero-intel/zero/issues/25) -
+  delivered in [Release Verification Guide](release-verification.md).
 
 ## Contribution Rules
 

docs/launch-issues.md

@@ -151,6 +151,8 @@ Labels: `help wanted`, `release`, `docs`, `packaging`
 
 GitHub: [#25](https://github.com/zero-intel/zero/issues/25)
 
+Status: delivered in [Release Verification Guide](release-verification.md).
+
 Add a short guide that explains how a user verifies a ZERO release from scratch:
 checksums, GitHub artifact attestations, SBOM/provenance metadata, Homebrew
 formula checks, and clean-download evidence.

docs/launch-scorecard.md

@@ -61,6 +61,8 @@ reserved for ZERO Intelligence.
 - Public contribution, security, governance, support, and issue templates
 - First-release notes template, live contributor issue board, and launch issue
   seed with five good-first issues and three help-wanted issues
+- Reader-focused release verification guide covering checksums, attestations,
+  SBOM/provenance metadata, Homebrew formula drift, and clean-download evidence
 - Public boundary audit from the private repo
 
 ## Paper-Only

docs/llms-full.txt

@@ -49,6 +49,7 @@ Use this bundle for retrieval and coding agents. It is not evidence of live trad
 - `docs/zero-intelligence.md`
 - `docs/model-gateway.md`
 - `docs/release.md`
+- `docs/release-verification.md`
 
 
 ## Source: `README.md`
@@ -530,6 +531,7 @@ deployment project, secrets, exchange credentials, and runtime state.
 - [docs/railway-deploy.md](docs/railway-deploy.md)
 - [docs/distribution.md](docs/distribution.md)
 - [docs/release.md](docs/release.md)
+- [docs/release-verification.md](docs/release-verification.md)
 
 ## Contributor Paths
 
@@ -627,6 +629,7 @@ Machine-readable entrypoints:
 - [Agentic Contribution](docs/agentic-contribution.md)
 - [Contributor Issue Board](docs/contributor-issue-board.md)
 - [Launch Scorecard](docs/launch-scorecard.md)
+- [Release Verification](docs/release-verification.md)
 - [Roadmap](docs/roadmap.md)
 
 ## License
@@ -1106,6 +1109,7 @@ Out of scope:
 - [Proof Packs](proof/README.md)
 - [Railway Deploy](railway-deploy.md)
 - [Release](release.md)
+- [Release Verification](release-verification.md)
 
 ## Architecture And Contracts
 
@@ -5391,7 +5395,11 @@ Use the GitHub labels when choosing work:
 
 - [#23 Expand read-only MCP strategy resources](https://github.com/zero-intel/zero/issues/23)
 - [#24 Design public Network empty and stale states](https://github.com/zero-intel/zero/issues/24)
-- [#25 Add release evidence reader docs](https://github.com/zero-intel/zero/issues/25)
+
+## Completed Seed Issues
+
+- [#25 Add release evidence reader docs](https://github.com/zero-intel/zero/issues/25) -
+  delivered in [Release Verification Guide](release-verification.md).
 
 ## Contribution Rules
 
@@ -6671,6 +6679,9 @@ the limitation is called out clearly.
 
 ## Verification
 
+For a reader-focused verification path, start with
+[Release Verification Guide](release-verification.md).
+
 Download the artifact bundle and verify its checksum file before running it:
 
 ```bash
@@ -6912,3 +6923,138 @@ Do not publish package-registry artifacts until the registry channel has an
 owner, rollback path, least-privilege token plan, and documented support
 expectation in [distribution.md](distribution.md).
 ````
+
+
+## Source: `docs/release-verification.md`
+
+````markdown
+# Release Verification Guide
+
+This guide explains how to verify a ZERO release before installing or sharing
+it. It checks artifact integrity, GitHub artifact attestations, SBOM/provenance
+metadata, the committed Homebrew formula, and the clean-download evidence record.
+
+It verifies release integrity only. It does not prove live trading safety,
+hosted custody, future package-registry publication, or profitability.
+
+## From A Fresh Clone
+
+Use this path when you want the repository verifier to download the release
+from GitHub and check everything in a temporary clean directory:
+
+```bash
+git clone https://github.com/zero-intel/zero.git
+cd zero
+just release-evidence v0.1.1
+```
+
+For machine-readable output:
+
+```bash
+scripts/release_evidence.py v0.1.1 --json
+```
+
+The release evidence command:
+
+- reads the published GitHub Release metadata;
+- downloads every attached release asset into a clean temporary directory;
+- verifies `SHA256SUMS` with `shasum -a 256 -c SHA256SUMS`;
+- runs `scripts/release_verify.py` against the downloaded directory;
+- verifies executable GitHub artifact attestations;
+- renders a Homebrew formula from the downloaded checksums;
+- fails if the rendered formula differs from the committed `Formula/zero.rb`.
+
+The current published evidence is recorded in
+[v0.1.1 release evidence](releases/v0.1.1-evidence.md). That page is evidence
+for `v0.1.1` only; future releases need their own clean-download evidence.
+
+## From Downloaded Assets
+
+Use this path when you already downloaded all GitHub Release assets into one
+directory:
+
+```bash
+cd /path/to/downloaded/zero-release
+shasum -a 256 -c SHA256SUMS
+/path/to/zero/scripts/release_verify.py .
+```
+
+Expected launch assets include:
+
+- `SHA256SUMS`
+- `zero-linux`
+- `zero-macos`
+- `zero-paper-image.tar`
+- `zero_engine-<version>-py3-none-any.whl`
+- `zero_engine-<version>.tar.gz`
+- `SBOM.spdx.json`
+- `PROVENANCE.json`
+
+`scripts/release_verify.py` checks that the checksum manifest covers exactly
+the release assets, every checksum matches, expected launch assets are present,
+assets are non-empty, and the metadata files parse with the expected safety
+claims.
+
+## Verify GitHub Artifact Attestations
+
+Run attestation verification from the downloaded asset directory:
+
+```bash
+gh attestation verify zero-linux -R zero-intel/zero
+gh attestation verify zero-macos -R zero-intel/zero
+```
+
+These commands prove that GitHub has signed provenance for the executable
+artifacts attached to the release. They do not prove that the executable is safe
+to use for live capital; they prove release provenance for the downloaded file.
+
+## Read SBOM And Provenance
+
+The release verifier requires both files:
+
+```bash
+python3 -m json.tool SBOM.spdx.json >/dev/null
+python3 -m json.tool PROVENANCE.json >/dev/null
+```
+
+`SBOM.spdx.json` records package/component metadata. `PROVENANCE.json` records
+source commit, tag, asset hashes, dirty-state policy, and release assertions
+such as paper-first defaults and no package-registry publication.
+
+## Check The Homebrew Formula
+
+The public repo works as its own Homebrew tap:
+
+```bash
+brew tap zero-intel/zero https://github.com/zero-intel/zero
+brew install zero
+```
+
+The committed formula at `Formula/zero.rb` must be generated from a verified
+release directory:
+
+```bash
+scripts/homebrew_formula.py /path/to/downloaded/zero-release --tag v0.1.1 --output /tmp/zero.rb
+diff -u Formula/zero.rb /tmp/zero.rb
+scripts/homebrew_formula_check.py
+```
+
+The formula drift check proves that the tap points at the same GitHub Release
+assets and checksums as the downloaded release. If the rendered formula differs
+from `Formula/zero.rb`, the tap is stale or the release verification input is
+wrong.
+
+## Refuse On Any Failure
+
+Do not install or redistribute a release when any of these fail:
+
+- `shasum -a 256 -c SHA256SUMS`
+- `scripts/release_verify.py <downloaded-release-dir>`
+- `gh attestation verify zero-linux -R zero-intel/zero`
+- `gh attestation verify zero-macos -R zero-intel/zero`
+- `scripts/homebrew_formula_check.py`
+- `just release-evidence <tag>`
+
+Treat failure as an integrity incident until a maintainer publishes corrected
+evidence or replaces the release.
+````

docs/llms.txt

@@ -32,6 +32,7 @@
 - [Proof Packs](proof/README.md)
 - [Railway Deploy](railway-deploy.md)
 - [Release](release.md)
+- [Release Verification](release-verification.md)
 
 ## Architecture And Contracts
 

docs/release-verification.md

@@ -0,0 +1,129 @@
+# Release Verification Guide
+
+This guide explains how to verify a ZERO release before installing or sharing
+it. It checks artifact integrity, GitHub artifact attestations, SBOM/provenance
+metadata, the committed Homebrew formula, and the clean-download evidence record.
+
+It verifies release integrity only. It does not prove live trading safety,
+hosted custody, future package-registry publication, or profitability.
+
+## From A Fresh Clone
+
+Use this path when you want the repository verifier to download the release
+from GitHub and check everything in a temporary clean directory:
+
+```bash
+git clone https://github.com/zero-intel/zero.git
+cd zero
+just release-evidence v0.1.1
+```
+
+For machine-readable output:
+
+```bash
+scripts/release_evidence.py v0.1.1 --json
+```
+
+The release evidence command:
+
+- reads the published GitHub Release metadata;
+- downloads every attached release asset into a clean temporary directory;
+- verifies `SHA256SUMS` with `shasum -a 256 -c SHA256SUMS`;
+- runs `scripts/release_verify.py` against the downloaded directory;
+- verifies executable GitHub artifact attestations;
+- renders a Homebrew formula from the downloaded checksums;
+- fails if the rendered formula differs from the committed `Formula/zero.rb`.
+
+The current published evidence is recorded in
+[v0.1.1 release evidence](releases/v0.1.1-evidence.md). That page is evidence
+for `v0.1.1` only; future releases need their own clean-download evidence.
+
+## From Downloaded Assets
+
+Use this path when you already downloaded all GitHub Release assets into one
+directory:
+
+```bash
+cd /path/to/downloaded/zero-release
+shasum -a 256 -c SHA256SUMS
+/path/to/zero/scripts/release_verify.py .
+```
+
+Expected launch assets include:
+
+- `SHA256SUMS`
+- `zero-linux`
+- `zero-macos`
+- `zero-paper-image.tar`
+- `zero_engine-<version>-py3-none-any.whl`
+- `zero_engine-<version>.tar.gz`
+- `SBOM.spdx.json`
+- `PROVENANCE.json`
+
+`scripts/release_verify.py` checks that the checksum manifest covers exactly
+the release assets, every checksum matches, expected launch assets are present,
+assets are non-empty, and the metadata files parse with the expected safety
+claims.
+
+## Verify GitHub Artifact Attestations
+
+Run attestation verification from the downloaded asset directory:
+
+```bash
+gh attestation verify zero-linux -R zero-intel/zero
+gh attestation verify zero-macos -R zero-intel/zero
+```
+
+These commands prove that GitHub has signed provenance for the executable
+artifacts attached to the release. They do not prove that the executable is safe
+to use for live capital; they prove release provenance for the downloaded file.
+
+## Read SBOM And Provenance
+
+The release verifier requires both files:
+
+```bash
+python3 -m json.tool SBOM.spdx.json >/dev/null
+python3 -m json.tool PROVENANCE.json >/dev/null
+```
+
+`SBOM.spdx.json` records package/component metadata. `PROVENANCE.json` records
+source commit, tag, asset hashes, dirty-state policy, and release assertions
+such as paper-first defaults and no package-registry publication.
+
+## Check The Homebrew Formula
+
+The public repo works as its own Homebrew tap:
+
+```bash
+brew tap zero-intel/zero https://github.com/zero-intel/zero
+brew install zero
+```
+
+The committed formula at `Formula/zero.rb` must be generated from a verified
+release directory:
+
+```bash
+scripts/homebrew_formula.py /path/to/downloaded/zero-release --tag v0.1.1 --output /tmp/zero.rb
+diff -u Formula/zero.rb /tmp/zero.rb
+scripts/homebrew_formula_check.py
+```
+
+The formula drift check proves that the tap points at the same GitHub Release
+assets and checksums as the downloaded release. If the rendered formula differs
+from `Formula/zero.rb`, the tap is stale or the release verification input is
+wrong.
+
+## Refuse On Any Failure
+
+Do not install or redistribute a release when any of these fail:
+
+- `shasum -a 256 -c SHA256SUMS`
+- `scripts/release_verify.py <downloaded-release-dir>`
+- `gh attestation verify zero-linux -R zero-intel/zero`
+- `gh attestation verify zero-macos -R zero-intel/zero`
+- `scripts/homebrew_formula_check.py`
+- `just release-evidence <tag>`
+
+Treat failure as an integrity incident until a maintainer publishes corrected
+evidence or replaces the release.