docs: cross-platform installation for macOS, Linux, and Windows

Installation docs previously assumed Linux. Now covers all platforms:

README.md:
- New Prerequisites section with per-platform build dep table
  (macOS/Ubuntu/Fedora/Arch/Windows/Docker)
- Documents CMake + Go requirement for BoringSSL compilation

book/src/getting-started/installation.md:
- Full instructions for macOS (Homebrew), Linux (Ubuntu/Fedora/Arch),
  Windows (native MSVC and WSL2), and Docker
- Chrome installation per platform
- Troubleshooting section: BoringSSL build failures, Chrome not found,
  openssl-sys conflicts

book/src/contributing/development-setup.md:
- Cross-references Installation for platform setup
- IDE setup table (VS Code, JetBrains, Neovim, Emacs)
- Platform-specific notes for macOS, Windows, Linux

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: copyleftdev

README.md

@@ -4,6 +4,21 @@ A deterministic crawl kernel. Same input + same seed = identical crawl, identica
 
 Not a crawler. Not a Wayback clone. The canonical memory layer of the web. See [CLAUDE.md](CLAUDE.md) for the full philosophy.
 
+## Prerequisites
+
+- **Rust 1.86+** — install via [rustup.rs](https://rustup.rs/)
+- **CMake 3+, Go 1.19+, C compiler** — required for BoringSSL (TLS impersonation)
+- **Chrome/Chromium** — optional, for `--browser` capture mode
+
+| Platform | Build deps |
+|---|---|
+| macOS | `xcode-select --install && brew install cmake go` |
+| Ubuntu/Debian | `sudo apt install build-essential cmake golang-go libclang-dev` |
+| Fedora | `sudo dnf install gcc gcc-c++ cmake golang clang-devel` |
+| Arch | `sudo pacman -S cmake go clang` |
+| Windows | Visual Studio Build Tools (C++ workload) + [CMake](https://cmake.org/download/) + [Go](https://go.dev/dl/) |
+| Any (Docker) | `docker build -t palimpsest .` — no local toolchain needed |
+
 ## Quick Start
 
 ```bash

book/src/contributing/development-setup.md

@@ -2,10 +2,15 @@
 
 ## Prerequisites
 
-- **Rust 1.86+** — `rustup update stable`
-- **cargo** — included with Rust
-- **git** — for source checkout
-- **Chrome/Chromium** — optional, for browser capture tests
+| Tool | Version | Why |
+|---|---|---|
+| Rust | 1.86+ stable | `rustup update stable` |
+| CMake | 3.x+ | BoringSSL compilation |
+| Go | 1.19+ | BoringSSL compilation |
+| C compiler | gcc, clang, or MSVC | BoringSSL compilation |
+| Git | any | Source checkout |
+
+See [Installation](../getting-started/installation.md) for platform-specific setup (macOS, Linux, Windows).
 
 ## Clone and Build
 
@@ -15,10 +20,12 @@ cd palimpsest
 cargo build --workspace
 ```
 
+First build takes 2-4 minutes (BoringSSL compiles from source). Subsequent builds are incremental.
+
 ## Running Tests
 
 ```bash
-# Full test suite (excludes long-running scale tests)
+# Full test suite (288 tests, excludes long-running scale tests)
 cargo test --workspace
 
 # Simulation tests only
@@ -30,27 +37,51 @@ cargo test -p palimpsest-sim --test scale_test
 # Stress test (10K pages)
 cargo test -p palimpsest-sim --test stress_test
 
+# Stealth regression tests (requires Chrome + network access)
+cargo test -p palimpsest-fetch --test stealth_test -- --ignored --nocapture --test-threads=1
+
 # Single crate
 cargo test -p palimpsest-frontier
 ```
 
 ## Pre-Commit Checks
 
-Before submitting a PR, run:
+Before submitting a PR:
 
 ```bash
-cargo fmt --check          # Formatting
+cargo fmt --check            # Formatting
 cargo clippy -- -D warnings  # Lints (must be warning-free)
-cargo test --workspace     # All tests pass
+cargo test --workspace       # All tests pass
 ```
 
 ## IDE Setup
 
-`rust-analyzer` is recommended. The workspace `Cargo.toml` at the project root configures all 15 crates automatically.
+**rust-analyzer** is recommended for all editors. The workspace `Cargo.toml` at the project root configures all 15 crates automatically.
+
+| Editor | Setup |
+|---|---|
+| VS Code | Install `rust-analyzer` extension |
+| JetBrains (CLion/RustRover) | Built-in Rust support |
+| Neovim | `mason.nvim` → install `rust-analyzer` |
+| Emacs | `lsp-mode` + `rustic` |
 
 ## Docker Testing
 
 ```bash
 docker build -t palimpsest .
 docker run palimpsest --help
 ```
+
+## Platform Notes
+
+### macOS
+
+BoringSSL builds cleanly with Xcode command line tools + Homebrew CMake + Go. No special flags needed.
+
+### Windows (MSVC)
+
+Requires Visual Studio Build Tools with the "Desktop development with C++" workload. CMake and Go must be in `PATH`. WSL2 is the recommended alternative for a smoother experience.
+
+### Linux
+
+All major distributions work. Ensure `cmake`, `go`, and `clang` (or `gcc`) are installed. See [Installation](../getting-started/installation.md) for distro-specific package commands.

book/src/getting-started/installation.md

@@ -2,33 +2,177 @@
 
 ## Prerequisites
 
-- **Rust 1.86+** (stable toolchain)
-- **Git** for source checkout
-- **Chrome or Chromium** (optional, for browser capture mode)
-- **Docker** (optional, for containerized deployment)
+| Dependency | Required | Notes |
+|---|---|---|
+| Rust 1.86+ | Yes | Stable toolchain via [rustup](https://rustup.rs/) |
+| Git | Yes | Source checkout |
+| C compiler + CMake | Yes | BoringSSL build (via wreq) |
+| Go 1.19+ | Yes | BoringSSL build (via wreq) |
+| Chrome or Chromium | Optional | Browser capture mode (`--browser`) |
+| Docker | Optional | Containerized deployment |
 
-## Building from Source
+### Why the C/Go toolchain?
+
+Palimpsest uses [wreq](https://github.com/0x676e67/wreq) with BoringSSL for TLS fingerprint impersonation. BoringSSL is compiled from source during `cargo build`, which requires CMake, a C compiler, and Go.
+
+## macOS
 
 ```bash
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+
+# Install build dependencies (Xcode command line tools + CMake + Go)
+xcode-select --install
+brew install cmake go
+
+# Clone and build
 git clone https://github.com/copyleftdev/palimpsest.git
 cd palimpsest
 cargo build --release
+
+# Verify
+./target/release/palimpsest --help
 ```
 
-The binary is placed at `target/release/palimpsest`.
+**Chrome for browser capture:**
+```bash
+# Chrome is usually at:
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version
 
-## Verifying the Installation
+# Or install via Homebrew:
+brew install --cask google-chrome
+```
+
+## Linux (Ubuntu/Debian)
 
 ```bash
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+
+# Install build dependencies
+sudo apt update
+sudo apt install -y build-essential cmake golang-go pkg-config libclang-dev
+
+# Clone and build
+git clone https://github.com/copyleftdev/palimpsest.git
+cd palimpsest
+cargo build --release
+
+# Verify
 ./target/release/palimpsest --help
 ```
 
-You should see the full subcommand list: `crawl`, `replay`, `history`, `extract`, `shadow-compare`, `serve`, `worker`, `api`, `stats`, `migrate`.
+**Chrome for browser capture:**
+```bash
+# Install Chrome
+wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
+echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
+sudo apt update && sudo apt install -y google-chrome-stable
+
+# Verify
+google-chrome --version
+```
+
+## Linux (Fedora/RHEL)
+
+```bash
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+
+# Install build dependencies
+sudo dnf install -y gcc gcc-c++ cmake golang clang-devel pkg-config
+
+# Clone and build
+git clone https://github.com/copyleftdev/palimpsest.git
+cd palimpsest
+cargo build --release
+```
+
+## Linux (Arch)
+
+```bash
+sudo pacman -S rust cmake go clang pkg-config
+git clone https://github.com/copyleftdev/palimpsest.git
+cd palimpsest
+cargo build --release
+```
+
+## Windows
+
+### Option A: Native (MSVC)
+
+```powershell
+# 1. Install Rust from https://rustup.rs/ (choose MSVC toolchain)
+
+# 2. Install Visual Studio Build Tools (C/C++ workload)
+#    https://visualstudio.microsoft.com/visual-cpp-build-tools/
+
+# 3. Install CMake
+#    https://cmake.org/download/ (add to PATH during install)
+
+# 4. Install Go
+#    https://go.dev/dl/ (add to PATH during install)
+
+# 5. Clone and build
+git clone https://github.com/copyleftdev/palimpsest.git
+cd palimpsest
+cargo build --release
+
+# 6. Verify
+.\target\release\palimpsest.exe --help
+```
+
+### Option B: WSL2 (recommended)
+
+Windows Subsystem for Linux gives you a full Linux environment. Follow the Linux (Ubuntu/Debian) instructions above inside WSL2:
+
+```powershell
+# Install WSL2 with Ubuntu
+wsl --install -d Ubuntu
+
+# Then inside the WSL2 terminal, follow the Linux instructions
+```
+
+### Option C: Docker (any platform)
+
+If you don't want to install build tools, Docker works on all platforms:
+
+```bash
+docker build -t palimpsest .
+docker run palimpsest --help
+docker run -v ./output:/data palimpsest crawl https://example.com -d 2 -o /data
+```
+
+See [Docker Deployment](../operations/docker.md) for the full compose setup.
+
+## Verifying the Build
+
+After building, you should see all 10 subcommands:
+
+```
+$ palimpsest --help
+Usage: palimpsest <COMMAND>
+
+Commands:
+  crawl           Start a crawl with seed URLs
+  replay          Reconstruct a captured URL from artifacts
+  history         Show capture history for a URL
+  extract         Extract text and RAG chunks from captured content
+  shadow-compare  Compare against legacy crawler WARC files
+  serve           Start a distributed frontier server
+  worker          Connect to a frontier server and crawl
+  api             Start the retrieval API server
+  stats           Print workspace statistics
+  migrate         Run storage migrations
+```
 
 ## Running the Test Suite
 
 ```bash
-# All tests (excludes long-running scale tests)
+# All tests (288, excludes long-running scale tests)
 cargo test --workspace
 
 # Simulation framework only
@@ -39,28 +183,45 @@ cargo test -p palimpsest-sim --test scale_test
 
 # Stress test (10K pages)
 cargo test -p palimpsest-sim --test stress_test
+
+# Stealth regression tests (requires Chrome + network)
+cargo test -p palimpsest-fetch --test stealth_test -- --ignored --nocapture --test-threads=1
 ```
 
-## Docker
+## Troubleshooting
 
-```bash
-docker build -t palimpsest .
+### BoringSSL build fails
 
-# Verify
-docker run palimpsest --help
+The most common build issue. Check:
+
+```bash
+cmake --version   # Need 3.x+
+go version        # Need 1.19+
+clang --version   # Or gcc — need a C compiler
 ```
 
-See [Docker Deployment](../operations/docker.md) for the full compose setup.
+On macOS, ensure Xcode command line tools are installed: `xcode-select --install`
+
+On Windows, ensure Visual Studio Build Tools include the "Desktop development with C++" workload.
 
-## Browser Capture
+### Chrome not found (browser capture)
 
-Browser capture requires Chrome or Chromium accessible in `PATH`. Palimpsest communicates via the Chrome DevTools Protocol (CDP).
+Palimpsest looks for Chrome/Chromium in `PATH`. If installed in a non-standard location:
 
 ```bash
-# Verify Chrome is available
-google-chrome --version
-# or
-chromium --version
+# macOS — add to PATH
+export PATH="/Applications/Google Chrome.app/Contents/MacOS:$PATH"
+
+# Windows — add to PATH
+set PATH=%PATH%;C:\Program Files\Google\Chrome\Application
+```
+
+### `openssl-sys` linker errors
+
+Palimpsest uses BoringSSL (via wreq), not OpenSSL. If you see `openssl-sys` errors, another dependency may be pulling it in. Check with:
+
+```bash
+cargo tree -i openssl-sys
 ```
 
-No additional configuration is needed — the `--browser` flag on the `crawl` command handles the rest.
+If present, the `boring-sys2` crate's `prefix-symbols` feature should prevent symbol conflicts on Linux. On macOS this is not typically an issue.

docs/book/404.html

@@ -37,7 +37,7 @@
             const path_to_root = "";
             const default_light_theme = "light";
             const default_dark_theme = "coal";
-            window.path_to_searchindex_js = "searchindex-4f269067.js";
+            window.path_to_searchindex_js = "searchindex-d84f7c65.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="toc-7980dfd2.js"></script>

docs/book/appendix/api-reference.html

@@ -36,7 +36,7 @@
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "coal";
-            window.path_to_searchindex_js = "../searchindex-4f269067.js";
+            window.path_to_searchindex_js = "../searchindex-d84f7c65.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc-7980dfd2.js"></script>

docs/book/appendix/error-taxonomy.html

@@ -36,7 +36,7 @@
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "coal";
-            window.path_to_searchindex_js = "../searchindex-4f269067.js";
+            window.path_to_searchindex_js = "../searchindex-d84f7c65.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc-7980dfd2.js"></script>

docs/book/appendix/glossary.html

@@ -36,7 +36,7 @@
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "coal";
-            window.path_to_searchindex_js = "../searchindex-4f269067.js";
+            window.path_to_searchindex_js = "../searchindex-d84f7c65.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc-7980dfd2.js"></script>