kjanat · kjanat · Jun 4, 2026 · Jun 3, 2026 · Jun 3, 2026 · Jun 3, 2026
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -1,23 +1,35 @@
 #:schema https://gist.githubusercontent.com/kjanat/1172d9d2d6dbe7c6d9983aaabef2eea5/raw/cargo-config.bundle.json
 
 [alias]
-bb          = ["build", "--bin", "run", "--bin", "runner"]
-bbr         = ["bb", "--release"]
-bin-run     = ["r", "--bin", "run", "--quiet"]
-bin-runner  = ["r", "--bin", "runner", "--quiet"]
-cl          = ["clippy", "--all-targets", "--all-features"]
-comp        = ["bin-runner", "--", "completions"]
-i           = ["install", "--path", "."]
-l           = ["cl", "--", "-D", "warnings", "-D", "clippy::all"]
-lint        = "l"
-meta        = ["metadata", "--format-version", "1"]
-r           = "run"
-rbin-run    = ["bin-run", "--release"]
-rbin-runner = ["bin-runner", "--release"]
-rr          = ["r", "--release"]
-runner      = ["r", "--bin", "runner"]
-schema      = ["r", "--quiet", "--example", "gen-schema", "--features", "schema-gen"]
-t           = ["test", "--all-features", "--all-targets"]
+# one-letter
+f = "format"
+i = "install --path ."
+l = "lint"
+t = "test --all-features --all-targets"
+
+# other short
+bb  = "build --bin run --bin runner"
+bbr = "bb --release"
+cl  = "clippy --all-targets --all-features"
+rq  = "run --quiet"
+rr  = "run --release"
+
+# other
+comp   = "bin-runner -- completions"
+format = "bin-run -- --pm npm dprint fmt"
+lint   = "cl -- -D warnings -D clippy::all"
+meta   = "metadata --format-version 1"
+
+# features
+man    = "rq --features man -- man"
+schema = "rq --features schema -- schema"
+
+# bin commands
+bin-run     = "rq --bin run"
+bin-runner  = "rq --bin runner"
+rbin-run    = "bin-run --release"
+rbin-runner = "bin-runner --release"
+runner      = "bin-runner"
 
 # [target.<triple>]
 # linker = "…"              # linker to use

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,43 @@
+# Contributing
+
+## Running the working-tree build
+
+The `bin/` shims always run the current source, not the installed binary:
+
+```sh
+./bin/runner <args>
+./bin/run <args>
+```
+
+With `direnv` (`.envrc` puts `bin/` on `PATH`), plain `runner` / `run` resolve
+to the working-tree build.
+
+## Checks
+
+```sh
+cargo test
+cargo clippy --all-targets --all-features -- -D clippy::all
+dprint check        # or: cargo fmt --check
+```
+
+Cargo aliases live in `.cargo/config.toml` (`t`, `cl`, `l`/`lint`, …).
+
+## Generated artifacts
+
+Both are rendered from the CLI definition behind off-by-default features —
+never hand-edited.
+
+- **`runner.toml` JSON Schema** — committed under `schemas/`:
+
+  ```sh
+  just gen-schema                  # cargo schema --output schemas/runner.toml.schema.json
+  git diff --exit-code schemas/    # drift guard
+  ```
+
+- **Man pages** (`man`/`schema` features) — generated at release time, not
+  committed:
+
+  ```sh
+  cargo man                        # → stdout
+  cargo man -o man                 # → ./man (gitignored)
+  ```
diff --git a/.github/scripts/build/build-npm-packages.sh b/.github/scripts/build/build-npm-packages.sh
@@ -5,10 +5,15 @@ set -euo pipefail
 RELEASE_TAG="${RELEASE_TAG:?RELEASE_TAG required}"
 
 version="${RELEASE_TAG#v}"
+
+# Man pages come from the `man` job's artifact, downloaded to ./man.
+man_arg=()
+[[ -d man ]] && man_arg=(--man-dir man)
+
 # build-packages.ts is tier-aware: tier-3 (experimental) targets are
 # silently skipped when missing; tier-1/2 missing fails the job. This
 # script is only invoked from release.yml's build-npm-dist (tag-push
 # context), so a missing tier-1/2 tarball is always a real failure —
 # no --skip-missing relaxation. The flag still exists in the script
 # for local dev partial builds.
-node npm/scripts/build-packages.ts --version "${version}"
+node npm/scripts/build-packages.ts --version "${version}" "${man_arg[@]}"
diff --git a/.github/scripts/publish/aur-prepare.sh b/.github/scripts/publish/aur-prepare.sh
@@ -56,6 +56,16 @@ if [[ "${pkgname}" == 'runner-run-bin' ]]; then
 		fi
 		sed -i -E "s/^sha256sums_${carch}=\(.*/sha256sums_${carch}=('${sum}')/" "${pkgbuild}"
 	done
+
+	# Arch-independent man archive (generic sha256sums=()).
+	man_sum="$(gh release download "v${version}" \
+		--repo "${GITHUB_REPOSITORY}" \
+		--pattern "runner-v${version}-man.sha256" --output - | awk 'NR==1{print $1}')"
+	if [[ ! "${man_sum}" =~ ^[0-9a-f]{64}$ ]]; then
+		echo "error: bad sha256 for man archive: '${man_sum}'" >&2
+		exit 1
+	fi
+	sed -i -E "s/^sha256sums=\(.*/sha256sums=('${man_sum}')/" "${pkgbuild}"
 fi
 
 echo "--- prepared ${pkgbuild} ---"

diff --git a/.github/workflows/aur-release.yml b/.github/workflows/aur-release.yml
@@ -9,7 +9,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: Release tag to publish (e.g. v0.12.0)
+        description: Release tag to publish (e.g. v0.12.1)
         required: true
         type: string
       dry-run:
@@ -32,7 +32,7 @@ jobs:
       RELEASE_TAG: ${{ case(github.event_name == 'release', github.event.release.tag_name, inputs.tag) }}
       DRY_RUN: ${{ inputs.dry-run || 'false' }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with: { persist-credentials: false }
 
       - name: prepare PKGBUILD

diff --git a/.github/workflows/crates-release.yml b/.github/workflows/crates-release.yml
@@ -1,79 +1,53 @@
 name: crates-release
-run-name: >-
-  ${{ format('crates publish {0}',
-       case(github.event_name == 'workflow_dispatch', inputs.tag,
-            github.ref_name)) }}
+run-name: ${{ format('crates publish {0}', case(github.event_name == 'workflow_dispatch', inputs.tag, github.ref_name)) }}
 
 on:
-  push:
-    tags:
-      - v*
+  push: { tags: [v*] }
   workflow_dispatch:
     inputs:
-      tag:
-        description: Release tag to publish (e.g. v0.6.0)
-        required: true
-        type: string
-      dry-run:
-        description: Dry run only (no upload to crates.io)
-        required: false
-        default: false
-        type: boolean
-
-permissions:
-  contents: read
+      tag: { description: Release tag to publish (e.g. vX.Y.Z), required: true, type: string }
+      dry-run: { description: Dry run only (no upload to crates.io), required: false, default: false, type: boolean }
 
 env:
+  RELEASE_TAG: ${{ case(github.event_name == 'workflow_dispatch', inputs.tag, github.ref_name) }}
+  INPUT_DRY_RUN: ${{ inputs.dry-run || 'false' }}
   CARGO_TERM_COLOR: always
 
 jobs:
   publish:
     name: publish to crates.io
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    environment:
-      name: crates-io
-      url: https://crates.io/crates/runner-run
-    env:
-      RELEASE_TAG: >-
-        ${{ case(github.event_name == 'workflow_dispatch', inputs.tag,
-             github.ref_name) }}
-      INPUT_DRY_RUN: ${{ inputs.dry-run || 'false' }}
+    permissions: { contents: read, id-token: write }
+    environment: { name: crates-io, url: "${{ format('https://crates.io/crates/runner-run/{0}', steps.verify.outputs.version) }}" }
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
-        with:
-          ref: refs/tags/${{ env.RELEASE_TAG }}
-          persist-credentials: false
-
-      - name: install rust toolchain
-        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
-
-      - name: rust cache
-        uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae # v2
-
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with: { ref: "refs/tags/${{ env.RELEASE_TAG }}", persist-credentials: false }
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
       - name: verify tag matches Cargo.toml version
+        id: verify
         run: |
           set -euo pipefail
           tag_version="${RELEASE_TAG#v}"
           manifest_version=$(cargo metadata --no-deps --format-version 1 \
             | jq -r '.packages[] | select(.name == "runner-run") | .version')
           if [[ "${tag_version}" != "${manifest_version}" ]]; then
+            echo "::error file=Cargo.toml::version does not match release tag"
             echo "error: tag ${RELEASE_TAG} (${tag_version}) does not match Cargo.toml version ${manifest_version}" >&2
             exit 1
           fi
           echo "ok: tag ${RELEASE_TAG} matches Cargo.toml version ${manifest_version}"
+          echo "version=${manifest_version}" >> "$GITHUB_OUTPUT"
 
-      - name: cargo publish (dry-run verification)
-        run: cargo publish --locked --dry-run
+      - run: cargo man --output man
+      - run: cargo publish --locked --dry-run --allow-dirty
 
       - name: mint crates.io token (trusted publishing)
+        uses: rust-lang/crates-io-auth-action@b7e9a28eded4986ec6b1fa40eeee8f8f165559ec # v1.0.3
         if: env.INPUT_DRY_RUN != 'true'
         id: auth
-        uses: rust-lang/crates-io-auth-action@b7e9a28eded4986ec6b1fa40eeee8f8f165559ec # v1
 
       - name: cargo publish
         if: env.INPUT_DRY_RUN != 'true'
         env: { CARGO_REGISTRY_TOKEN: "${{ steps.auth.outputs.token }}" }
-        run: cargo publish --locked
+        run: cargo publish --locked --allow-dirty
diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml
@@ -58,7 +58,7 @@ jobs:
     outputs: { dry-run: "${{ steps.derive.outputs.dry-run }}" }
     steps:
       # Sparse-checkout from default branch — no tag-supplied code on disk.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
@@ -67,7 +67,7 @@ jobs:
             npm/targets.json
           sparse-checkout-cone-mode: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: ${{ env.NODE_VERSION }}
           registry-url: ${{ env.REGISTRY }}
@@ -105,7 +105,7 @@ jobs:
           echo "run-id=${run_id}" >> "${GITHUB_OUTPUT}"
 
       - name: download npm-dist artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: npm-dist
           path: npm/dist/