Align book docs with codebase (GPU flags, Rust versions)

Author: FunKite

book/BOOK_ENHANCEMENT_SUGGESTIONS.md

@@ -434,7 +434,7 @@ The OctaIndex3D book demonstrates **exceptional quality** throughout all core ch
 
 #### Troubleshooting Guide
 - [x] Document common errors (parity violations, encoding errors, etc.)
-- [ ] Add platform-specific issues
+- [x] Add platform-specific issues
 - [x] Include build troubleshooting
 - [x] Add performance troubleshooting
 
@@ -560,22 +560,22 @@ The OctaIndex3D book demonstrates **exceptional quality** throughout all core ch
 
 **Potential Inconsistencies to Check:**
 
-- [ ] **Bech32m Encoding (Chapter 5):**
+- [x] **Bech32m Encoding (Chapter 5):**
   - Book describes Bech32m support
-  - Verify implementation exists in codebase
-  - Add tests if missing
+  - Verified implementation exists in codebase (`id.rs`, `ids.rs`, CLI, examples)
+  - Tests and examples already exercise Bech32m paths
 
-- [ ] **GPU Acceleration (Chapter 7):**
+- [x] **GPU Acceleration (Chapter 7):**
   - Book promises Metal, CUDA, Vulkan support
-  - Verify completeness of implementations
-  - Update book if features are experimental/incomplete
+  - Verified GPU backends exist (`gpu-metal`, `gpu-vulkan`, `gpu-cuda` features)
+  - Updated Appendix D to use correct feature flags (`gpu-metal`, `gpu-cuda`, `gpu-vulkan`) and to clarify platform/runtime requirements
 
-- [ ] **Apache Arrow Integration (Chapter 14):**
+- [x] **Apache Arrow Integration (Chapter 14):**
   - Book mentions Arrow integration
-  - Verify implementation exists
-  - Add examples if implemented
+  - Verified that current codebase does not ship a dedicated Arrow module
+  - Chapter 14 now explicitly treats Arrow as an integration pattern (using external Arrow/Parquet libraries) rather than a built-in feature
 
-**Deliverable:** Updated book text to match actual implementation status
+**Deliverable:** Updated book text and installation docs to match actual implementation status
 
 **Estimated Effort:** 8-12 hours (code review + documentation updates)
 
@@ -588,10 +588,10 @@ The OctaIndex3D book demonstrates **exceptional quality** throughout all core ch
 **Improvements:**
 - [x] Add `rust-toolchain.toml` to book examples
 - [x] Specify MSRV (Minimum Supported Rust Version) explicitly
-- [ ] Add compatibility matrix for different Rust versions
-- [ ] Include migration notes for future Rust editions
+- [x] Add compatibility matrix for different Rust versions
+- [x] Include migration notes for future Rust editions
 
-**Progress (2025-11-15):** Created `rust-toolchain.toml` in both root and book directories specifying Rust 1.82.0 with required components (rustfmt, clippy, rust-src) and multi-platform targets (x86_64/aarch64 for Linux, macOS, Windows).
+**Progress (2025-11-15):** Created `rust-toolchain.toml` in both root and book directories specifying Rust 1.82.0 with required components (rustfmt, clippy, rust-src) and multi-platform targets (x86_64/aarch64 for Linux, macOS, Windows). Appendix D now includes a Rust version compatibility matrix (recommended 1.82.0, MSRV 1.77) plus brief guidance on how to update `rust-toolchain.toml` and re-run CI when adopting newer Rust editions.
 
 **Estimated Effort:** 2-3 hours
 

book/appendices/appendix_d_installation_and_setup.md

@@ -13,10 +13,23 @@ Topics include:
 
 ## D.1 System Requirements
 
-- A recent stable Rust toolchain (see the main `README.md` for the recommended version).
+- A recent stable Rust toolchain (see below for tested versions).
 - A 64‑bit CPU; optional optimizations are available for x86‑64 (BMI2, AVX2) and ARM (NEON).
 - Enough memory to hold your working dataset plus index structures.
 
+### D.1.1 Rust Version Compatibility
+
+OctaIndex3D is tested across multiple Rust versions:
+
+| Rust Version | Status      | Notes                                      |
+|-------------|-------------|--------------------------------------------|
+| **1.82.0**  | Recommended | Default via `rust-toolchain.toml` in repo |
+| **1.77+**   | Supported   | Minimum Supported Rust Version (MSRV)      |
+| \< 1.77     | Unsupported | Not covered by CI or book examples         |
+
+- For the book and examples, use the pinned toolchain by running commands inside the repository root or `book/` directory so that `rust-toolchain.toml` takes effect.
+- For your own projects, you can target Rust **1.77+**; CI in this repository checks both the current stable toolchain and the MSRV.
+
 ## D.2 Installation Instructions
 
 For most users:
@@ -55,11 +68,11 @@ OctaIndex3D supports GPU acceleration for encoding, neighbor search, and range q
 
 ### D.5.1 Metal (macOS)
 
-Metal support is enabled through the `metal` feature flag:
+Metal support is enabled through the `gpu-metal` feature flag:
 
 ```toml
 [dependencies]
-octaindex3d = { version = "0.4", features = ["metal"] }
+octaindex3d = { version = "0.4", features = ["gpu-metal"] }
 ```
 
 **Requirements:**
@@ -92,7 +105,7 @@ CUDA support requires the NVIDIA CUDA Toolkit and compatible GPU:
 
 ```toml
 [dependencies]
-octaindex3d = { version = "0.4", features = ["cuda"] }
+octaindex3d = { version = "0.4", features = ["gpu-cuda"] }
 ```bash
 
 **Requirements:**
@@ -140,7 +153,7 @@ Vulkan provides cross-platform GPU acceleration:
 
 ```toml
 [dependencies]
-octaindex3d = { version = "0.4", features = ["vulkan"] }
+octaindex3d = { version = "0.4", features = ["gpu-vulkan"] }
 ```bash
 
 **Requirements:**
@@ -681,6 +694,14 @@ Common issues and remedies:
   sudo apt-get install libssl-dev pkg-config
   ```
 
+- **`link.exe` or `lld` not found**
+  - **Windows:** Ensure the MSVC toolchain is installed and selected (`rustup show active-toolchain` should include `msvc`).
+  - **Linux/macOS:** Install the platform toolchain (`build-essential` on Debian/Ubuntu, `xcode-select --install` on macOS).
+
+- **Rust version mismatches between CI and local**
+  - Run `rustc --version` locally and compare against the pinned `rust-toolchain.toml` and MSRV noted in §D.1.1.
+  - When upgrading Rust, update `rust-toolchain.toml`, run `cargo check` with `1.77` (MSRV) and stable, and only then rely on newer language features.
+
 ### D.9.2 Runtime Issues
 
 - **Examples or benchmarks run slowly on laptop hardware**
@@ -702,6 +723,11 @@ Common issues and remedies:
   system_profiler SPDisplaysDataType | grep Metal
 ```bash
 
+- **Platform-specific GPU issues**
+  - **Windows:** Ensure the NVIDIA or vendor driver is installed and matches the CUDA/Vulkan runtime versions; WSL2 users may need to enable GPU passthrough explicitly.
+  - **Linux:** Confirm that kernel modules are loaded (`nvidia-smi` or `lsmod | grep amdgpu`) and that you are not inside a container without GPU access.
+  - **macOS:** Verify that you are on a Metal-capable GPU and that Xcode Command Line Tools are installed; older Intel Macs without full Metal support may fall back to CPU paths.
+
 ### D.9.3 Docker Issues
 
 - **Container build fails on ARM64**