Run CI-equivalent checks before push

.githooks/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$repo_root/scripts/local-ci.sh"

Cargo.toml

@@ -16,6 +16,7 @@ include = [
     "docs/install.md",
     "docs/cli.md",
     "docs/troubleshooting.md",
+    "docs/contributing.md",
     "LICENSE",
     "NOTICE",
     "config.example.toml",

README.md

@@ -86,6 +86,7 @@ bindsym $mod+Alt+d exec whispers
 - [Installation guide](docs/install.md) — package choices, prerequisites, config path, and feature notes.
 - [CLI guide](docs/cli.md) — command groups, examples, and newer rewrite-policy commands.
 - [Troubleshooting](docs/troubleshooting.md) — `wl-copy`, `/dev/uinput`, cloud checks, and hang diagnostics.
+- [Contributor workflow](docs/contributing.md) — install the local pre-push hook and mirror CI before opening a PR.
 - [config.example.toml](config.example.toml) — the canonical config template.
 
 ## Troubleshooting

docs/contributing.md

@@ -0,0 +1,46 @@
+# Contributor workflow
+
+Before you push or open a PR, run the local CI workflow so you catch the same failures that GitHub Actions would catch later.
+
+## Install the pre-push hook
+
+Run this once in your local clone:
+
+```sh
+scripts/install-git-hooks.sh
+```
+
+That configures:
+
+- `core.hooksPath=.githooks`
+- `.githooks/pre-push` to run `scripts/local-ci.sh`
+
+## Run the full local CI workflow manually
+
+```sh
+scripts/local-ci.sh
+```
+
+By default it mirrors the repo's main CI workflow as closely as practical:
+
+- `cargo fmt --all -- --check`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `cargo check --no-default-features`
+- `cargo check --no-default-features --features osd`
+- `cargo check --no-default-features --features local-rewrite`
+- `cargo package --locked --allow-dirty`
+- CUDA feature checks when `nvcc` is available
+- `scripts/build-release-bundle.sh`
+
+## Useful overrides
+
+You can skip expensive local-only steps with environment variables:
+
+```sh
+WHISPERS_LOCAL_CI_SKIP_CUDA=1 scripts/local-ci.sh
+WHISPERS_LOCAL_CI_SKIP_PACKAGE=1 scripts/local-ci.sh
+WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE=1 scripts/local-ci.sh
+```
+
+These are meant for local iteration only; the default workflow should stay as close to CI as possible before you open a PR.

scripts/build-release-bundle.sh

@@ -72,6 +72,8 @@ install -Dm644 docs/cli.md \
   "$stage_dir/$bundle_name/share/doc/whispers/docs/cli.md"
 install -Dm644 docs/troubleshooting.md \
   "$stage_dir/$bundle_name/share/doc/whispers/docs/troubleshooting.md"
+install -Dm644 docs/contributing.md \
+  "$stage_dir/$bundle_name/share/doc/whispers/docs/contributing.md"
 install -Dm644 config.example.toml \
   "$stage_dir/$bundle_name/share/doc/whispers/config.example.toml"
 install -Dm644 LICENSE \

scripts/install-git-hooks.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+git config core.hooksPath .githooks
+chmod +x .githooks/pre-push
+
+printf 'Configured git hooks path: %s\n' "$(git config --get core.hooksPath)"
+printf 'Installed pre-push hook: %s/.githooks/pre-push\n' "$repo_root"

scripts/local-ci.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+skip_cuda="${WHISPERS_LOCAL_CI_SKIP_CUDA:-0}"
+skip_package="${WHISPERS_LOCAL_CI_SKIP_PACKAGE:-0}"
+skip_release_bundle="${WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE:-0}"
+
+run_step() {
+  local label="$1"
+  shift
+  printf '\n==> %s\n' "$label"
+  "$@"
+}
+
+run_step "Check formatting" cargo fmt --all -- --check
+run_step "Clippy (default features)" cargo clippy --all-targets -- -D warnings
+run_step "Test (default features)" cargo test
+
+run_step "Check no default features" cargo check --no-default-features
+run_step "Check osd feature only" cargo check --no-default-features --features osd
+run_step "Check local rewrite feature only" cargo check --no-default-features --features local-rewrite
+
+if [[ "$skip_package" != "1" ]]; then
+  run_step "Package crate" cargo package --locked --allow-dirty
+else
+  printf '\n==> Skipping cargo package (--allow-dirty) because WHISPERS_LOCAL_CI_SKIP_PACKAGE=1\n'
+fi
+
+if [[ "$skip_cuda" == "1" ]]; then
+  printf '\n==> Skipping CUDA checks because WHISPERS_LOCAL_CI_SKIP_CUDA=1\n'
+elif command -v nvcc >/dev/null 2>&1; then
+  run_step "Check cuda feature only" cargo check --no-default-features --features cuda
+  run_step "Check cuda + local rewrite features" cargo check --no-default-features --features cuda,local-rewrite
+else
+  printf '\n==> Skipping CUDA checks because nvcc is not available on PATH\n'
+fi
+
+if [[ "$skip_release_bundle" != "1" ]]; then
+  run_step "Build release bundle" scripts/build-release-bundle.sh
+else
+  printf '\n==> Skipping release bundle because WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE=1\n'
+fi
+
+printf '\nAll local CI checks passed.\n'