docs(release): document .deb install and curate release-notes install block (DX-5675)

README install section reordered around one recommended path per platform —
Homebrew (macOS/Linux), Scoop (Windows), .deb (Debian/Ubuntu), AUR (Arch),
COPR (Fedora/EPEL), Docker (GHCR) — with crates.io / source / prebuilt
binaries grouped under an Alternatives subsection. The .deb, COPR, and
Docker entries are new; the others are kept verbatim.

Adds a `release-update-install-notes` justfile recipe that prepends a
curated "How to install" block (rendered from a reviewable template at
packaging/release-notes-install.md.tmpl, with {{VERSION}} substitution) to
the GitHub release body. cargo-dist's auto-generated install section is
preserved below a `---` separator. The block is bracketed by HTML-comment
markers so re-runs replace the existing block instead of stacking, making
the recipe safe to invoke standalone or as the final step of
`release-sync-manual-channels`, which it now is.

Author: johnpmitsch

Justfile

@@ -264,6 +264,55 @@ release-update-scoop-bucket version bucket_path:
   echo "Committed qn {{version}} to {{bucket_path}}. To publish:"
   echo "  git -C {{bucket_path}} push"
 
+# Prepend a curated "How to install" section to the GitHub release body for
+# v<VERSION>. The block is rendered from packaging/release-notes-install.md.tmpl
+# (substituting {{VERSION}}) and bracketed by HTML-comment markers so re-runs
+# replace the existing block instead of stacking duplicates. cargo-dist's
+# auto-generated body is preserved below a `---` separator.
+#
+# Usage:
+#   just release-update-install-notes 0.1.8            # edits the release
+#   just release-update-install-notes 0.1.8 --dry-run  # prints assembled body to stdout
+release-update-install-notes version mode="":
+  #!/usr/bin/env bash
+  set -euo pipefail
+  version="{{version}}"
+  mode="{{mode}}"
+  if [[ -n "$mode" && "$mode" != "--dry-run" ]]; then
+    echo "Error: unknown mode '$mode' (expected --dry-run or unset)." >&2
+    exit 1
+  fi
+  tmpl="packaging/release-notes-install.md.tmpl"
+  if [[ ! -f "$tmpl" ]]; then
+    echo "Error: $tmpl not found." >&2
+    exit 1
+  fi
+  rendered=$(sed "s/{{ '{{' }}VERSION{{ '}}' }}/${version}/g" "$tmpl")
+  start_marker='<!-- qn-install-block:start -->'
+  end_marker='<!-- qn-install-block:end -->'
+  # The block itself does not include the `---` separator — the separator lives
+  # between the block and the rest of the body and stays in the body across re-runs.
+  block=$(printf '%s\n%s\n%s' "$start_marker" "$rendered" "$end_marker")
+  current=$(gh release view "v${version}" --json body --jq .body)
+  if [[ "$current" == *"$start_marker"* && "$current" == *"$end_marker"* ]]; then
+    # Replace existing block (idempotent re-run). Split body around markers in pure bash.
+    before="${current%%$start_marker*}"
+    after_with_end="${current#*$start_marker}"
+    after="${after_with_end#*$end_marker}"
+    new_body="${before}${block}${after}"
+  else
+    new_body=$(printf '%s\n\n---\n%s' "$block" "$current")
+  fi
+  if [[ "$mode" == "--dry-run" ]]; then
+    printf '%s\n' "$new_body"
+    exit 0
+  fi
+  tmpfile=$(mktemp)
+  trap 'rm -f "$tmpfile"' EXIT
+  printf '%s\n' "$new_body" > "$tmpfile"
+  gh release edit "v${version}" --notes-file "$tmpfile"
+  echo "Updated release v${version} with curated install block."
+
 # Run release-update-{homebrew-tap,scoop-bucket,aur-bin} in sequence for
 # the latest release tag, then print the three `git push` commands the
 # maintainer needs to run to publish. Auto-detects the version from the
@@ -307,7 +356,9 @@ release-sync-manual-channels root="~/qn" version="":
   echo
   just release-update-aur-bin      "$version" "${root}/qn-bin"
   echo
-  echo "All three channels updated. To publish, run:"
+  just release-update-install-notes "$version"
+  echo
+  echo "Manual channels and release-notes install block updated. To publish, run:"
   echo "  git -C ${root}/homebrew-tap push"
   echo "  git -C ${root}/scoop-bucket push"
   echo "  git -C ${root}/qn-bin push"

README.md

@@ -29,13 +29,7 @@ error: null
 
 ## Installation
 
-### From crates.io
-
-```sh
-cargo install quicknode-cli
-```
-
-The crate name is `quicknode-cli` but the installed binary is `qn`.
+Pick the recommended path for your platform. Other channels are listed under [Alternatives](#alternatives).
 
 ### Homebrew (macOS, Linux)
 
@@ -50,19 +44,60 @@ scoop bucket add quicknode https://github.com/quicknode/scoop-bucket
 scoop install quicknode/qn
 ```
 
+### `.deb` (Debian, Ubuntu)
+
+Each GitHub release attaches `qn_<VERSION>_amd64.deb` and `qn_<VERSION>_arm64.deb`. Check your architecture with `dpkg --print-architecture`, then grab the matching file from the [latest release page](https://github.com/quicknode/cli/releases/latest):
+
+```sh
+# replace <VERSION> with the version on the release page, e.g. 0.1.8
+curl -LO https://github.com/quicknode/cli/releases/download/v<VERSION>/qn_<VERSION>_amd64.deb
+sudo apt install ./qn_<VERSION>_amd64.deb
+```
+
 ### Arch Linux (AUR)
 
 ```sh
 yay -S qn-bin   # or any other AUR helper
 ```
 
-### From source
+### Fedora, EPEL (COPR)
+
+```sh
+sudo dnf copr enable quicknode/qn
+sudo dnf install qn
+```
+
+### Docker (GHCR)
+
+```sh
+docker pull ghcr.io/quicknode/qn:latest
+docker run --rm ghcr.io/quicknode/qn:latest --help
+```
+
+### Alternatives
+
+<details>
+<summary>crates.io, from source, prebuilt binaries</summary>
+
+**crates.io:**
+
+```sh
+cargo install quicknode-cli
+```
+
+The crate name is `quicknode-cli` but the installed binary is `qn`.
+
+**From source:**
 
 ```sh
 git clone git@github.com:quicknode/cli.git && cd cli
 cargo install --path .
 ```
 
+**Prebuilt binaries:** every GitHub release attaches per-platform archives — see the [latest release page](https://github.com/quicknode/cli/releases/latest).
+
+</details>
+
 ## Authentication
 
 You will need a Quicknode API key to get started. Once you have that, you can run `qn auth login`

RELEASING.md

@@ -76,6 +76,17 @@ git -C ~/qn/qn-bin push
 
 The recipe pulls both Linux gnu sha256 sidecars (x86_64 + aarch64) from the release, renders a `PKGBUILD` + `.SRCINFO`, and stages them. Push goes to `ssh://aur@aur.archlinux.org/qn-bin.git` — the AUR's git remote.
 
+### Curated install block on the release notes
+
+`release-sync-manual-channels` finishes by calling `release-update-install-notes`, which prepends a curated "How to install" section to the GitHub release body. Source for the block is `packaging/release-notes-install.md.tmpl`; edit it there if the install copy needs to change. The recipe is idempotent — re-running against the same release replaces the existing block rather than stacking duplicates — so it's safe to invoke standalone:
+
+```fish
+just release-update-install-notes X.Y.Z            # edits the release in place
+just release-update-install-notes X.Y.Z --dry-run  # prints the assembled body without editing
+```
+
+cargo-dist's auto-generated content is preserved below a `---` separator.
+
 ## One-time setup notes
 
 A few channels needed manual setup the first time. Captured here so the next maintainer doesn't have to rediscover them.

packaging/release-notes-install.md.tmpl

@@ -0,0 +1,52 @@
+## Install
+
+Pick the recommended path for your platform.
+
+### Homebrew (macOS, Linux)
+
+```sh
+brew install quicknode/tap/qn
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop bucket add quicknode https://github.com/quicknode/scoop-bucket
+scoop install quicknode/qn
+```
+
+### `.deb` (Debian, Ubuntu)
+
+Check your architecture with `dpkg --print-architecture`, then grab the matching `.deb` asset from this release:
+
+```sh
+# amd64
+curl -LO https://github.com/quicknode/cli/releases/download/v{{VERSION}}/qn_{{VERSION}}_amd64.deb
+sudo apt install ./qn_{{VERSION}}_amd64.deb
+
+# arm64
+curl -LO https://github.com/quicknode/cli/releases/download/v{{VERSION}}/qn_{{VERSION}}_arm64.deb
+sudo apt install ./qn_{{VERSION}}_arm64.deb
+```
+
+### Arch Linux (AUR)
+
+```sh
+yay -S qn-bin   # or any other AUR helper
+```
+
+### Fedora, EPEL (COPR)
+
+```sh
+sudo dnf copr enable quicknode/qn
+sudo dnf install qn
+```
+
+### Docker (GHCR)
+
+```sh
+docker pull ghcr.io/quicknode/qn:{{VERSION}}
+docker run --rm ghcr.io/quicknode/qn:{{VERSION}} --help
+```
+
+For `cargo install`, source builds, and raw prebuilt binaries see the [project README](https://github.com/quicknode/cli#alternatives).