Know which OpenShell binaries and images belong to a development build

Start with .github/workflows/release-dev.yml and architecture/build.md, then compare the openshell-release-manifest.json guidance in docs/about/installation.mdx and PR #3445. Done means the development publication produces one verifiable manifest linking the source commit, workflow, archives, images, checksums and digests, rejects inconsistent inputs, and documents how users retain and verify it.

User Story

As a developer testing an agent integration with OpenShell development builds, I want to record exactly which CLI, gateway, sandbox and supervisor artifacts belong to the build I am using, so that I can repeat a test and tell a maintainer what I actually ran.

Problem Statement

OpenShell publishes downloadable binaries and container images. It already provides archive checksums and image provenance, but there is no single published record connecting the core binaries and images to the same source commit and build run. Users have to assemble that information from separate sources. The build architecture documents the existing artifact and image safeguards.

The rolling dev release also changes over time. Its publication workflow replaces release assets and moves the tag. Recording only “tested with dev” is therefore insufficient to identify the files used in a test.

Impact / Why This Matters

During our integration work, the development release advanced while we were checking whether a fix was available. We had to recheck the source revision and release asset identity, and maintain separate records for the runtime artifacts. That is the concrete motivation here: manual verification and record keeping around a moving release. We have not established that accidentally mixing release components caused a failure.

A developer who downloads a CLI and runs OpenShell containers needs to preserve enough information for a colleague to select the same artifacts later. A shared release record would also make bug reports more precise: the maintainer could identify the build without asking the reporter to reconstruct it from downloads and workflow logs.

Proposed Design

Publish a machine-readable record alongside each development build, covering the standalone core archives and the container images for the gateway, sandbox and supervisor.

The user workflow would be:

1. Save the record with the integration's test results.
2. Check downloaded archives against its checksums and select container images by their content digests, which identify exact image contents.
3. Share the record when reporting a problem or repeating the test, so the source commit, build run and platform are explicit.

PR #3445's proposed installation guidance describes this as openshell-release-manifest.json, with an attestation identifying its producer. Inconsistent or incomplete inputs should stop publication before existing development release assets are replaced.

Acceptance Criteria

• A development build publishes one verifiable record identifying its source commit, producing workflow and complete core artifact inventory.
• A user can verify a downloaded archive and select an image for their platform by checksum or digest from that record.
• Publication rejects missing artifacts, mismatched build identities, incorrect checksums, or disagreement between archived executables and those staged for the corresponding images.
• Documentation explains how to retain and use the record, which artifacts it covers, and the limits on compatibility and download retention.

Alternatives Considered

• Record only the version or dev tag. This does not identify all of the exact artifacts used.
• Collect checksums, image digests and build metadata manually. This is possible today, but every integration has to assemble and maintain the association itself.
• Rebuild from a source commit. That provides a local build, but does not identify the published artifacts used in the original test.

Agent Investigation

Reviewed the public release workflow, build documentation and PR changes, and searched related issues. Issue #2946 asks for broader reuse of immutable artifacts across CI and packaging. This proposal covers the release identity record; it does not implement that issue's cross-workflow resolver or make all tests and packages consume the same artifacts. No new runtime or release-publication tests were run for this issue draft.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request