jmgilman · Aug 20, 2026 · Aug 20, 2026
diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@ This repository defines the reusable workflows and repository contract that Meig
 ## Documentation
 
 - [Install `release-cli` with mise](docs/how-to/install-release-cli-with-mise.md)
+- [Install `release-cli` with Nix](docs/how-to/install-release-cli-with-nix.md)
 - [Configure GitHub releases](docs/how-to/configure-github-releases.md)
 - [Configure OCI image publication](docs/how-to/configure-oci-images.md)
 - [Rehearse and recover GitHub releases](docs/how-to/rehearse-and-recover-github-releases.md)
@@ -13,5 +14,6 @@ This repository defines the reusable workflows and repository contract that Meig
 - [GitHub release contract reference](docs/reference/github-release-contract.md)
 - [OCI image contract reference](docs/reference/oci-image-contract.md)
 - [Copyable Go release example](examples/go-release/)
+- [Copyable Nix consumer example](examples/nix-release-cli/)
 
-Consumer repositories call the reusable workflows at one full commit SHA. The current released pin is `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`).
+Consumer repositories call the reusable workflows at one full commit SHA. The current released pin is `0fc99489d31d400bc3f69d6636d60e7d3f3d0251` (`v0.1.3`).
diff --git a/docs/how-to/configure-github-releases.md b/docs/how-to/configure-github-releases.md
@@ -2,7 +2,7 @@
 
 Use this guide to add the shared Meigma Go release workflows to a repository. The [GitHub Release contract](../reference/github-release-contract.md) defines the reusable workflow inputs, permissions, artifacts, and failure behavior.
 
-The documented workflow revision is `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`).
+The documented workflow revision is `0fc99489d31d400bc3f69d6636d60e7d3f3d0251` (`v0.1.3`).
 
 ## Prerequisites
 
@@ -104,14 +104,14 @@ In the copied files, replace the example values with values from the consumer re
 
 Do not replace these shared contract values:
 
-- reusable workflow revision `611195c21fdd44ff2cf95c6a8833f84d095270b0`;
-- `checksum-signing-workflow-ref` value `meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0`;
+- reusable workflow revision `0fc99489d31d400bc3f69d6636d60e7d3f3d0251`;
+- `checksum-signing-workflow-ref` value `meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251`;
 - variable name `MEIGMA_RELEASE_APP_CLIENT_ID`; or
 - secret name `MEIGMA_RELEASE_APP_PRIVATE_KEY`.
 
 To change the immutable revision later, follow [Upgrade GitHub Release workflows](upgrade-github-release-workflows.md). Update all reusable workflow references and the checksum signing identity together; do not edit one reference in isolation.
 
-Keep `checksum-signing-workflow-ref` in `owner/repository/workflow@revision` form without a URL prefix. The publisher adds `https://github.com/` and passes the resulting exact certificate identity to `release-cli verify bundle` with `--identity`. For example, the documented input becomes `--identity https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0`.
+Keep `checksum-signing-workflow-ref` in `owner/repository/workflow@revision` form without a URL prefix. The publisher adds `https://github.com/` and passes the resulting exact certificate identity to `release-cli verify bundle` with `--identity`. For example, the documented input becomes `--identity https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251`.
 
 The copied GoReleaser configuration builds Darwin, Linux, and Windows archives
 for amd64 and arm64. It also packages each canonical Linux binary as DEB, RPM,
@@ -249,7 +249,7 @@ Verify that the checksum manifest was signed by the canonical reusable pre-publi
 ```bash
 mise exec -- cosign verify-blob \
   --bundle checksums.txt.sigstore.json \
-  --certificate-identity 'https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0' \
+  --certificate-identity 'https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251' \
   --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
   checksums.txt
 ```
@@ -265,7 +265,7 @@ while IFS= read -r entry; do
   mise exec -- gh attestation verify "$asset" \
     --repo "$REPOSITORY" \
     --signer-workflow meigma/release/.github/workflows/publish-github-release.yml \
-    --signer-digest 611195c21fdd44ff2cf95c6a8833f84d095270b0 \
+    --signer-digest 0fc99489d31d400bc3f69d6636d60e7d3f3d0251 \
     --source-ref "refs/tags/$TAG" \
     --deny-self-hosted-runners
 done < checksums.txt

diff --git a/docs/how-to/configure-oci-images.md b/docs/how-to/configure-oci-images.md
@@ -2,7 +2,7 @@
 
 Use this guide to add signed, multi-architecture GHCR images to a repository that already uses the Meigma Go release workflows. The [OCI image contract](../reference/oci-image-contract.md) defines the reusable workflow interfaces, image contents, tags, signatures, attestations, and recovery behavior.
 
-The documented workflow revision is `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`).
+The documented workflow revision is `0fc99489d31d400bc3f69d6636d60e7d3f3d0251` (`v0.1.3`).
 
 ## Prerequisites
 
@@ -20,7 +20,7 @@ Record the consumer repository and immutable workflow revision:
 
 ```bash
 export REPOSITORY="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
-export RELEASE_REVISION=611195c21fdd44ff2cf95c6a8833f84d095270b0
+export RELEASE_REVISION=0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 export IMAGE="ghcr.io/${REPOSITORY,,}"
 ```
 
@@ -112,7 +112,7 @@ permissions:
 Pin every reusable workflow to the same full revision:
 
 ```text
-611195c21fdd44ff2cf95c6a8833f84d095270b0
+0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 ```
 
 Make `github-release` depend on `oci-publish`. That ordering keeps the GitHub Release in draft state when registry publication, signing, or attestation fails.

diff --git a/docs/how-to/install-release-cli-with-mise.md b/docs/how-to/install-release-cli-with-mise.md
@@ -12,14 +12,14 @@ The pinned workflow revision selects and verifies the matching CLI release.
 From the project directory, install the current release:
 
 ```bash
-mise use github:meigma/release@0.1.2
+mise use github:meigma/release@0.1.3
 ```
 
 Mise writes this tool entry to the project's `mise.toml`:
 
 ```toml
 [tools]
-"github:meigma/release" = "0.1.2"
+"github:meigma/release" = "0.1.3"
 ```
 
 Verify the installed command:
@@ -36,15 +36,15 @@ The current release reports:
   "command": "version",
   "ok": true,
   "result": {
-    "version": "0.1.2",
-    "commit": "611195c21fdd44ff2cf95c6a8833f84d095270b0",
+    "version": "0.1.3",
+    "commit": "0fc99489d31d400bc3f69d6636d60e7d3f3d0251",
     "protocol": 1
   }
 }
 ```
 
 Mise selects the release archive for the host operating system and architecture.
-The `v0.1.2` release contains archives for Darwin, Linux, and Windows on `amd64`
+The `v0.1.3` release contains archives for Darwin, Linux, and Windows on `amd64`
 and `arm64`. During a verified installation, mise reports the selected archive,
 its checksum check, and GitHub artifact attestation verification.
 
@@ -53,15 +53,15 @@ its checksum check, and GitHub artifact attestation verification.
 Use `mise x` for a temporary invocation:
 
 ```bash
-mise x github:meigma/release@0.1.2 -- release-cli version --json
+mise x github:meigma/release@0.1.3 -- release-cli version --json
 ```
 
 ## Install for your user account
 
 Add `-g` to write the tool entry to the global mise configuration:
 
 ```bash
-mise use -g github:meigma/release@0.1.2
+mise use -g github:meigma/release@0.1.3
 mise exec -- release-cli version --json
 ```
 
@@ -71,7 +71,7 @@ version deliberately after verifying the target GitHub Release.
 ## Use a local shorthand
 
 `release-cli` is not registered in the mise registry. The full backend name is
-therefore required by default; `mise use release-cli@0.1.2` does not resolve.
+therefore required by default; `mise use release-cli@0.1.3` does not resolve.
 
 To define a local shorthand, add an alias and tool entry:
 
@@ -80,7 +80,7 @@ To define a local shorthand, add an alias and tool entry:
 release-cli = "github:meigma/release"
 
 [tools]
-release-cli = "0.1.2"
+release-cli = "0.1.3"
 ```
 
 The alias affects only the mise configuration that defines it. It does not

diff --git a/docs/how-to/install-release-cli-with-nix.md b/docs/how-to/install-release-cli-with-nix.md
@@ -0,0 +1,118 @@
+# Install `release-cli` with Nix
+
+Use the repository flake to build and run a tagged `release-cli` revision. The
+flake supports Darwin and Linux on `arm64` and `amd64`.
+
+This guide is for direct command-line and development-shell use. Repositories
+that call the reusable Meigma release workflows do not install or version
+`release-cli` separately. Their pinned workflow revision selects the matching
+CLI release.
+
+## Run without installing
+
+Run the current release directly from GitHub:
+
+```bash
+nix run github:meigma/release/v0.1.3#release-cli -- version --json
+```
+
+The current release reports:
+
+```json
+{
+  "schema": "release.dev/result/v1",
+  "command": "version",
+  "ok": true,
+  "result": {
+    "version": "0.1.3",
+    "commit": "0fc99489d31d400bc3f69d6636d60e7d3f3d0251",
+    "protocol": 1
+  }
+}
+```
+
+The first invocation builds `release-cli` when the result is not already in a
+configured Nix cache.
+
+## Install into your Nix profile
+
+Install the tagged package for your user account:
+
+```bash
+nix profile add github:meigma/release/v0.1.3#release-cli
+release-cli version --json
+```
+
+Pin an explicit tag in interactive installation commands. For project and CI
+use, add the flake as an input so `flake.lock` records its exact commit and
+content hash.
+
+## Add `release-cli` to a project flake
+
+Add the release flake as an input and make it follow the project's `nixpkgs`
+input:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
+    release = {
+      url = "github:meigma/release/v0.1.3";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    { nixpkgs, release, ... }:
+    let
+      system = "aarch64-darwin";
+      pkgs = import nixpkgs { inherit system; };
+    in
+    {
+      devShells.${system}.default = pkgs.mkShellNoCC {
+        packages = [ release.packages.${system}.release-cli ];
+      };
+    };
+}
+```
+
+Replace `aarch64-darwin` with the project's host system. Supported values are:
+
+- `aarch64-darwin`
+- `aarch64-linux`
+- `x86_64-darwin`
+- `x86_64-linux`
+
+Lock and verify the input:
+
+```bash
+nix flake lock
+nix develop --command release-cli version --json
+```
+
+The [Nix consumer example](../../examples/nix-release-cli/) exposes the package,
+app, and development shell on all four systems.
+
+## Update the pinned release
+
+Change `inputs.release.url` to the new tag, then update only that input:
+
+```bash
+nix flake update release
+nix develop --command release-cli version --json
+```
+
+Commit the changed `flake.lock` with the version update.
+
+## Understand the build and trust boundary
+
+The flake builds `release-cli` from the exact Git revision in the locked input.
+It uses the locked Nixpkgs revision, a fixed Go 1.26.6 source hash,
+and a fixed Go module dependency hash. It embeds the manifest version and source
+revision in the resulting binary.
+
+This path does not install the prebuilt GitHub Release archive and does not run
+GitHub artifact-attestation verification. Nix instead verifies every locked
+flake input and fixed-output dependency. Use the [mise installation
+path](install-release-cli-with-mise.md) when you need the released archive,
+checksum, and GitHub artifact-attestation checks.
diff --git a/docs/how-to/rehearse-and-recover-github-releases.md b/docs/how-to/rehearse-and-recover-github-releases.md
@@ -2,7 +2,7 @@
 
 Use this guide to populate a draft GitHub Release without publishing it, then resume publication through the same tag and draft. Complete [Configure GitHub Releases](configure-github-releases.md) first. The [GitHub Release contract](../reference/github-release-contract.md) defines the checks that each run enforces.
 
-The documented workflow revision is `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`).
+The documented workflow revision is `0fc99489d31d400bc3f69d6636d60e7d3f3d0251` (`v0.1.3`).
 
 `release-cli publish github` owns draft discovery, tag and commit binding, expected-asset upload, asset convergence, and the optional undraft operation. It never creates a release, re-drafts a public release, or deletes an asset.
 
@@ -320,7 +320,7 @@ If the repository does not need a correction, rerun the complete top-level workf
 For the documented current revision, the publisher requires a nonempty `checksums.txt`, the exact closed payload list, matching payload hashes, a regular Cosign bundle file, issuer `https://token.actions.githubusercontent.com`, and this certificate identity:
 
 ```text
-https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 ```
 
 For an upgrade rehearsal, replace the current-revision identity with the target value described in [Upgrade GitHub Release workflows](upgrade-github-release-workflows.md).

diff --git a/docs/reference/github-release-contract.md b/docs/reference/github-release-contract.md
@@ -1,6 +1,6 @@
 # GitHub release contract reference
 
-This page defines the cross-repository contract for the reusable Go producer and GitHub Release publisher at revision `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`).
+This page defines the cross-repository contract for the reusable Go producer and GitHub Release publisher at revision `0fc99489d31d400bc3f69d6636d60e7d3f3d0251` (`v0.1.3`).
 
 For configuration steps, see [Configure GitHub releases](../how-to/configure-github-releases.md). For draft rehearsals and recovery steps, see [Rehearse and recover GitHub releases](../how-to/rehearse-and-recover-github-releases.md). The [`release-cli` contract](release-cli-contract.md) defines the command, output, and exit-code surface used by the producer. The [OCI image contract](oci-image-contract.md) defines the image builder and publisher that gate the complete delivery caller. [Release trust boundaries](../explanation/release-trust-boundaries.md) explains why the workflows, setup action, and CLI have separate responsibilities. To adopt another immutable revision, see [Upgrade GitHub release workflows](../how-to/upgrade-github-release-workflows.md). A complete consumer repository is available in the [Go release example](../../examples/go-release/).
 
@@ -9,17 +9,17 @@ For configuration steps, see [Configure GitHub releases](../how-to/configure-git
 The complete caller pins all four reusable workflows to one full revision. The GitHub Release path directly calls the producer and GitHub publisher:
 
 ```yaml
-uses: meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+uses: meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 ```
 
 ```yaml
-uses: meigma/release/.github/workflows/publish-github-release.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+uses: meigma/release/.github/workflows/publish-github-release.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 ```
 
 The checksum signer identity input must name the same producer workflow revision:
 
 ```yaml
-checksum-signing-workflow-ref: meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+checksum-signing-workflow-ref: meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 ```
 
 ## Caller contract
@@ -48,7 +48,7 @@ jobs:
       attestations: read
       contents: read
       id-token: write
-    uses: meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+    uses: meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
 
   oci-image:
     name: Build OCI image
@@ -57,7 +57,7 @@ jobs:
       actions: read
       attestations: read
       contents: read
-    uses: meigma/release/.github/workflows/go-oci-build.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+    uses: meigma/release/.github/workflows/go-oci-build.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
     with:
       artifact-id: ${{ needs.release-assets.outputs.oci-input-artifact-id }}
       artifact-digest: ${{ needs.release-assets.outputs.oci-input-artifact-digest }}
@@ -72,7 +72,7 @@ jobs:
       contents: read
       id-token: write
       packages: write
-    uses: meigma/release/.github/workflows/publish-oci-image.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+    uses: meigma/release/.github/workflows/publish-oci-image.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
     with:
       artifact-id: ${{ needs.oci-image.outputs.artifact-id }}
       artifact-digest: ${{ needs.oci-image.outputs.artifact-digest }}
@@ -91,11 +91,11 @@ jobs:
       attestations: write
       contents: read
       id-token: write
-    uses: meigma/release/.github/workflows/publish-github-release.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+    uses: meigma/release/.github/workflows/publish-github-release.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
     with:
       artifact-id: ${{ needs.release-assets.outputs.artifact-id }}
       artifact-digest: ${{ needs.release-assets.outputs.artifact-digest }}
-      checksum-signing-workflow-ref: meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0
+      checksum-signing-workflow-ref: meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251
       require-oci-image: true
       oci-image-reference: ${{ needs.oci-publish.outputs.image-reference }}
       release-app-client-id: ${{ vars.MEIGMA_RELEASE_APP_CLIENT_ID }}
@@ -344,14 +344,14 @@ The checksum signature is accepted only when `release-cli verify bundle` invokes
 
 | Field | Required value |
 | --- | --- |
-| Certificate identity | `https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0` |
+| Certificate identity | `https://github.com/meigma/release/.github/workflows/go-pre-publish.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251` |
 | Certificate OIDC issuer | `https://token.actions.githubusercontent.com` |
 | Signed blob | `checksums.txt` |
 | Bundle | `checksums.txt.sigstore.json` |
 
 The workflow adds the `https://github.com/` prefix to `checksum-signing-workflow-ref` and passes the resulting exact URL to `release-cli verify bundle` with `--identity`. A branch name, tag name, different commit, or different workflow path does not satisfy the documented identity.
 
-The publisher at `meigma/release/.github/workflows/publish-github-release.yml@611195c21fdd44ff2cf95c6a8833f84d095270b0` creates GitHub build-provenance attestations in the consumer repository. Its job token creates attestations but has only `contents: read`. The workflow mints a short-lived Release App installation token with `contents: write` and passes it to `release-cli publish github`. The CLI stores the value as a redacted secret and uses it for release discovery and publication; it never mints an App token, changes repository settings, or persists credentials.
+The publisher at `meigma/release/.github/workflows/publish-github-release.yml@0fc99489d31d400bc3f69d6636d60e7d3f3d0251` creates GitHub build-provenance attestations in the consumer repository. Its job token creates attestations but has only `contents: read`. The workflow mints a short-lived Release App installation token with `contents: write` and passes it to `release-cli publish github`. The CLI stores the value as a redacted secret and uses it for release discovery and publication; it never mints an App token, changes repository settings, or persists credentials.
 
 ## Publication states