Document binary and source installation

.github/workflows/ci.yml

@@ -12,6 +12,35 @@ permissions:
   contents: read
 
 jobs:
+  minimum-rust:
+    name: Rust 1.85 source build (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-22.04
+            target: x86_64-unknown-linux-gnu
+          - runner: macos-15-intel
+            target: x86_64-apple-darwin
+          - runner: macos-15
+            target: aarch64-apple-darwin
+          - runner: windows-latest
+            target: x86_64-pc-windows-msvc
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Rust 1.85
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.85.0
+          targets: ${{ matrix.target }}
+
+      - name: Build release binary
+        run: cargo build --locked --release -p bitbygit --target ${{ matrix.target }}
+
   rust:
     name: Rust
     runs-on: ubuntu-latest
@@ -38,6 +67,10 @@ jobs:
           "${tool_dir}/actionlint"
           bash scripts/test-release-workflow.sh
 
+      - name: Validate Linux installation documentation
+        shell: bash
+        run: bash scripts/test-installation-docs.sh
+
       - name: Format
         run: cargo fmt --all --check
 
@@ -49,3 +82,30 @@ jobs:
 
       - name: Build
         run: cargo build --locked --workspace
+
+  installation-docs-macos:
+    name: macOS installation docs
+    runs-on: macos-15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Validate installation documentation
+        shell: bash
+        run: bash scripts/test-installation-docs.sh
+
+  installation-docs-windows:
+    name: Windows installation docs
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Validate installation documentation
+        shell: pwsh
+        run: ./scripts/test-installation-docs.ps1

README.md

@@ -42,23 +42,37 @@ User policy is defined in `config.toml`; see
 [`docs/configuration.md`](docs/configuration.md) for path resolution, the strict
 schema, and safe fallback behavior.
 
+## Installation
+
+See [`docs/installation.md`](docs/installation.md) for supported release
+archives, checksum verification, PATH setup, and source build instructions.
+Package-manager distribution is not currently available.
+
 ## Development
 
 Prerequisites:
 
 - Rust 1.85 or newer.
 - `git` available on `PATH`.
-- `gh` is optional for future GitHub workflows.
+- `gh` is optional and required only for GitHub-specific workflows.
 
 Run local checks:
 
 ```sh
+bash scripts/test-release-workflow.sh
+bash scripts/test-installation-docs.sh
 cargo fmt --all --check
-cargo clippy --workspace --all-targets -- -D warnings
-cargo test --workspace
-cargo build --workspace
+cargo clippy --locked --workspace --all-targets -- -D warnings
+cargo test --locked --workspace
+cargo build --locked --workspace
 ```
 
+The Bash installation validator runs on Linux and macOS without PowerShell.
+Windows contributors can run the platform-specific installation validation with
+`pwsh -NoProfile -File scripts/test-installation-docs.ps1`; CI runs that command
+on a Windows runner. The validator uses temporary process-scoped PATH state and
+never changes the persistent user PATH.
+
 Or run:
 
 ```sh

crates/bitbygit-core/src/config.rs

@@ -37,13 +37,13 @@ impl AppConfig {
         }
 
         self.policy.validate()?;
-        if let Some(branch) = &self.pull_requests.default_base_branch
-            && !valid_branch_name(branch)
-        {
-            return Err(invalid_value(
-                "pull-requests.default-base-branch",
-                "must be a valid local branch name",
-            ));
+        if let Some(branch) = &self.pull_requests.default_base_branch {
+            if !valid_branch_name(branch) {
+                return Err(invalid_value(
+                    "pull-requests.default-base-branch",
+                    "must be a valid local branch name",
+                ));
+            }
         }
         Ok(())
     }

crates/bitbygit-core/src/policy.rs

@@ -73,16 +73,17 @@ impl EffectivePolicy {
             confirmation_label(requirement)
         )];
 
-        if let Some(branch) = branch
-            && self.is_protected_branch(branch)
-            && let Some(minimum) = protected_branch_requirement(operation)
-        {
-            requirement = requirement.max(minimum);
-            reasons.push(format!(
-                "protected branch {branch}: {} requires at least {} confirmation",
-                operation.action_label(),
-                confirmation_label(minimum)
-            ));
+        if let Some(branch) = branch {
+            if self.is_protected_branch(branch) {
+                if let Some(minimum) = protected_branch_requirement(operation) {
+                    requirement = requirement.max(minimum);
+                    reasons.push(format!(
+                        "protected branch {branch}: {} requires at least {} confirmation",
+                        operation.action_label(),
+                        confirmation_label(minimum)
+                    ));
+                }
+            }
         }
 
         PolicyEvaluation {