Document SHA-pinning as the GitHub Action best practice

Lead the channel doc's usage example and guidance with pinning uses: to
a full-length commit SHA rather than a version tag, matching what GitHub
recommends and what this repository already does for every third-party
action. Clarify the two distinct controls: the SHA pins the action ref,
and the action's checksum verification pins the release binary it
downloads, so the version: input stays a release tag by design.

https://claude.ai/code/session_01TKgJTS4UcFPqtdwkxYzTUC

Author: claude

.github/copilot-instructions.md

@@ -54,7 +54,7 @@ row: "- [{summary}](../{filename})"
 - [Rebase, CI monitoring, and review comment resolution.](../docs/development/pr-fixup-workflow.md)
 - [The `jeduden/asdf-mdsmith` plugin installs the checksum-verified prebuilt binary; the short form awaits the asdf-plugins registry entry.](../docs/development/release-channels/asdf.md)
 - [A single-file `.flatpak` bundle built in CI from the x86_64 Linux release binary and attached to each GitHub release, installed by file with host filesystem access for the linter.](../docs/development/release-channels/flatpak.md)
-- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<ref>`.](../docs/development/release-channels/github-actions.md)
+- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<commit-sha>`.](../docs/development/release-channels/github-actions.md)
 - [Per-platform mdsmith binaries plus the .vsix, the checksum file, and a Sigstore signature, attached to a tag-named release.](../docs/development/release-channels/github-releases.md)
 - [`go install` compiles mdsmith from the tagged module source with the host Go 1.25+ toolchain; no prebuilt binary is downloaded.](../docs/development/release-channels/go.md)
 - [The `jeduden/homebrew-mdsmith` tap installs the checksum-verified prebuilt binary for macOS or Linux on Intel or arm64.](../docs/development/release-channels/homebrew.md)

AGENTS.md

@@ -60,7 +60,7 @@ row: "- [{summary}]({filename})"
 - [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
 - [The `jeduden/asdf-mdsmith` plugin installs the checksum-verified prebuilt binary; the short form awaits the asdf-plugins registry entry.](docs/development/release-channels/asdf.md)
 - [A single-file `.flatpak` bundle built in CI from the x86_64 Linux release binary and attached to each GitHub release, installed by file with host filesystem access for the linter.](docs/development/release-channels/flatpak.md)
-- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<ref>`.](docs/development/release-channels/github-actions.md)
+- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<commit-sha>`.](docs/development/release-channels/github-actions.md)
 - [Per-platform mdsmith binaries plus the .vsix, the checksum file, and a Sigstore signature, attached to a tag-named release.](docs/development/release-channels/github-releases.md)
 - [`go install` compiles mdsmith from the tagged module source with the host Go 1.25+ toolchain; no prebuilt binary is downloaded.](docs/development/release-channels/go.md)
 - [The `jeduden/homebrew-mdsmith` tap installs the checksum-verified prebuilt binary for macOS or Linux on Intel or arm64.](docs/development/release-channels/homebrew.md)

CLAUDE.md

@@ -46,7 +46,7 @@ row: "- [{summary}]({filename})"
 - [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
 - [The `jeduden/asdf-mdsmith` plugin installs the checksum-verified prebuilt binary; the short form awaits the asdf-plugins registry entry.](docs/development/release-channels/asdf.md)
 - [A single-file `.flatpak` bundle built in CI from the x86_64 Linux release binary and attached to each GitHub release, installed by file with host filesystem access for the linter.](docs/development/release-channels/flatpak.md)
-- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<ref>`.](docs/development/release-channels/github-actions.md)
+- [A composite action at the repository root downloads the checksum-verified release binary for the runner's OS and architecture, puts `mdsmith` on `PATH`, and runs the command in its `args` input; referenced as `uses: jeduden/mdsmith@<commit-sha>`.](docs/development/release-channels/github-actions.md)
 - [Per-platform mdsmith binaries plus the .vsix, the checksum file, and a Sigstore signature, attached to a tag-named release.](docs/development/release-channels/github-releases.md)
 - [`go install` compiles mdsmith from the tagged module source with the host Go 1.25+ toolchain; no prebuilt binary is downloaded.](docs/development/release-channels/go.md)
 - [The `jeduden/homebrew-mdsmith` tap installs the checksum-verified prebuilt binary for macOS or Linux on Intel or arm64.](docs/development/release-channels/homebrew.md)

docs/development/release-channels/github-actions.md

@@ -5,7 +5,7 @@ summary: >-
   checksum-verified release binary for the runner's OS and
   architecture, puts `mdsmith` on `PATH`, and runs the
   command in its `args` input; referenced as
-  `uses: jeduden/mdsmith@<ref>`.
+  `uses: jeduden/mdsmith@<commit-sha>`.
 mechanism: pull
 artifact: cli
 command: "uses: jeduden/mdsmith@v0"
@@ -23,10 +23,10 @@ The repository root carries an `action.yml`, so a workflow
 step runs mdsmith with:
 
 ```yaml
-- uses: jeduden/mdsmith@v0
+- uses: jeduden/mdsmith@<commit-sha>  # v0.41.0
   with:
-    version: latest   # a release tag like v0.41.0, or latest
-    args: check .     # omit to only put mdsmith on PATH
+    version: v0.41.0   # mdsmith release to install, or latest
+    args: check .      # omit to only put mdsmith on PATH
 ```
 
 The composite action reads `$RUNNER_OS` and
@@ -50,17 +50,26 @@ later step can call it. `working-directory` sets the
 directory the `args` command runs in. The action exposes
 one output, `version`, the string `mdsmith version` prints.
 
-For a locked-down supply chain, pin `uses:` to a release
-tag or a commit SHA, the way this repository pins every
-third-party action it consumes.
+Pin `uses:` to a full-length commit SHA, not a tag. A SHA
+is immutable; a tag like `@v0` can be repointed at new
+code. GitHub recommends the SHA form, and this repository
+uses it for every third-party action. Keep the version in
+a trailing comment, as `# v0.41.0` above.
 
-The short `uses: jeduden/mdsmith@v0` form needs two
-things. A tagged release must ship this `action.yml`. The
-floating `v0` tag must then move onto it. Until that
-happens, pin the action to a commit SHA or use `@main`.
-You can also skip the action and run the release binary in
-a `run:` step. That repeats by hand the download and
-verify steps the action automates.
+The action still verifies the downloaded binary's SHA-256
+against the release `checksums.txt`. So the action and the
+binary it fetches are both pinned by digest, not by a
+movable name.
+
+No released commit carries the action yet. Pin to a commit
+SHA from this branch, or from `main` once it merges, to use
+it today. After the next release, pin to that release's
+commit. The convenience tag `@v0` comes later: it must be
+created and moved onto a release that ships `action.yml`.
+
+You can also skip the action entirely. Run the release
+binary in a `run:` step. That repeats by hand the download
+and verify steps the action automates.
 
 Because no published tag installs the action yet, this
 channel sets `unlisted: true` in its frontmatter, so